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