Chris@17: <?php
Chris@17: /**
Chris@17:  * The base class for all PHP_CodeSniffer documentation generators.
Chris@17:  *
Chris@17:  * Documentation generators are used to print documentation about code sniffs
Chris@17:  * in a standard.
Chris@17:  *
Chris@17:  * @author    Greg Sherwood <gsherwood@squiz.net>
Chris@17:  * @copyright 2006-2015 Squiz Pty Ltd (ABN 77 084 670 600)
Chris@17:  * @license   https://github.com/squizlabs/PHP_CodeSniffer/blob/master/licence.txt BSD Licence
Chris@17:  */
Chris@17: 
Chris@17: namespace PHP_CodeSniffer\Generators;
Chris@17: 
Chris@17: use PHP_CodeSniffer\Ruleset;
Chris@17: use PHP_CodeSniffer\Autoload;
Chris@17: 
Chris@17: abstract class Generator
Chris@17: {
Chris@17: 
Chris@17:     /**
Chris@17:      * The ruleset used for the run.
Chris@17:      *
Chris@17:      * @var \PHP_CodeSniffer\Ruleset
Chris@17:      */
Chris@17:     public $ruleset = null;
Chris@17: 
Chris@17:     /**
Chris@17:      * XML documentation files used to produce the final output.
Chris@17:      *
Chris@17:      * @var string[]
Chris@17:      */
Chris@17:     public $docFiles = [];
Chris@17: 
Chris@17: 
Chris@17:     /**
Chris@17:      * Constructs a doc generator.
Chris@17:      *
Chris@17:      * @param \PHP_CodeSniffer\Ruleset $ruleset The ruleset used for the run.
Chris@17:      *
Chris@17:      * @see generate()
Chris@17:      */
Chris@17:     public function __construct(Ruleset $ruleset)
Chris@17:     {
Chris@17:         $this->ruleset = $ruleset;
Chris@17: 
Chris@17:         foreach ($ruleset->sniffs as $className => $sniffClass) {
Chris@17:             $file    = Autoload::getLoadedFileName($className);
Chris@17:             $docFile = str_replace(
Chris@17:                 DIRECTORY_SEPARATOR.'Sniffs'.DIRECTORY_SEPARATOR,
Chris@17:                 DIRECTORY_SEPARATOR.'Docs'.DIRECTORY_SEPARATOR,
Chris@17:                 $file
Chris@17:             );
Chris@17:             $docFile = str_replace('Sniff.php', 'Standard.xml', $docFile);
Chris@17: 
Chris@17:             if (is_file($docFile) === true) {
Chris@17:                 $this->docFiles[] = $docFile;
Chris@17:             }
Chris@17:         }
Chris@17: 
Chris@17:     }//end __construct()
Chris@17: 
Chris@17: 
Chris@17:     /**
Chris@17:      * Retrieves the title of the sniff from the DOMNode supplied.
Chris@17:      *
Chris@17:      * @param \DOMNode $doc The DOMNode object for the sniff.
Chris@17:      *                      It represents the "documentation" tag in the XML
Chris@17:      *                      standard file.
Chris@17:      *
Chris@17:      * @return string
Chris@17:      */
Chris@17:     protected function getTitle(\DOMNode $doc)
Chris@17:     {
Chris@17:         return $doc->getAttribute('title');
Chris@17: 
Chris@17:     }//end getTitle()
Chris@17: 
Chris@17: 
Chris@17:     /**
Chris@17:      * Generates the documentation for a standard.
Chris@17:      *
Chris@17:      * It's probably wise for doc generators to override this method so they
Chris@17:      * have control over how the docs are produced. Otherwise, the processSniff
Chris@17:      * method should be overridden to output content for each sniff.
Chris@17:      *
Chris@17:      * @return void
Chris@17:      * @see    processSniff()
Chris@17:      */
Chris@17:     public function generate()
Chris@17:     {
Chris@17:         foreach ($this->docFiles as $file) {
Chris@17:             $doc = new \DOMDocument();
Chris@17:             $doc->load($file);
Chris@17:             $documentation = $doc->getElementsByTagName('documentation')->item(0);
Chris@17:             $this->processSniff($documentation);
Chris@17:         }
Chris@17: 
Chris@17:     }//end generate()
Chris@17: 
Chris@17: 
Chris@17:     /**
Chris@17:      * Process the documentation for a single sniff.
Chris@17:      *
Chris@17:      * Doc generators must implement this function to produce output.
Chris@17:      *
Chris@17:      * @param \DOMNode $doc The DOMNode object for the sniff.
Chris@17:      *                      It represents the "documentation" tag in the XML
Chris@17:      *                      standard file.
Chris@17:      *
Chris@17:      * @return void
Chris@17:      * @see    generate()
Chris@17:      */
Chris@17:     abstract protected function processSniff(\DOMNode $doc);
Chris@17: 
Chris@17: 
Chris@17: }//end class