1<?php
2/**
3 * The base class for all PHP_CodeSniffer documentation generators.
4 *
5 * Documentation generators are used to print documentation about code sniffs
6 * in a standard.
7 *
8 * @author    Greg Sherwood <gsherwood@squiz.net>
9 * @copyright 2006-2015 Squiz Pty Ltd (ABN 77 084 670 600)
10 * @license   https://github.com/squizlabs/PHP_CodeSniffer/blob/master/licence.txt BSD Licence
11 */
12
13namespace PHP_CodeSniffer\Generators;
14
15use PHP_CodeSniffer\Ruleset;
16use PHP_CodeSniffer\Autoload;
17
18abstract class Generator
19{
20
21    /**
22     * The ruleset used for the run.
23     *
24     * @var \PHP_CodeSniffer\Ruleset
25     */
26    public $ruleset = null;
27
28    /**
29     * XML documentation files used to produce the final output.
30     *
31     * @var string[]
32     */
33    public $docFiles = [];
34
35
36    /**
37     * Constructs a doc generator.
38     *
39     * @param \PHP_CodeSniffer\Ruleset $ruleset The ruleset used for the run.
40     *
41     * @see generate()
42     */
43    public function __construct(Ruleset $ruleset)
44    {
45        $this->ruleset = $ruleset;
46
47        foreach ($ruleset->sniffs as $className => $sniffClass) {
48            $file    = Autoload::getLoadedFileName($className);
49            $docFile = str_replace(
50                DIRECTORY_SEPARATOR.'Sniffs'.DIRECTORY_SEPARATOR,
51                DIRECTORY_SEPARATOR.'Docs'.DIRECTORY_SEPARATOR,
52                $file
53            );
54            $docFile = str_replace('Sniff.php', 'Standard.xml', $docFile);
55
56            if (is_file($docFile) === true) {
57                $this->docFiles[] = $docFile;
58            }
59        }
60
61    }//end __construct()
62
63
64    /**
65     * Retrieves the title of the sniff from the DOMNode supplied.
66     *
67     * @param \DOMNode $doc The DOMNode object for the sniff.
68     *                      It represents the "documentation" tag in the XML
69     *                      standard file.
70     *
71     * @return string
72     */
73    protected function getTitle(\DOMNode $doc)
74    {
75        return $doc->getAttribute('title');
76
77    }//end getTitle()
78
79
80    /**
81     * Generates the documentation for a standard.
82     *
83     * It's probably wise for doc generators to override this method so they
84     * have control over how the docs are produced. Otherwise, the processSniff
85     * method should be overridden to output content for each sniff.
86     *
87     * @return void
88     * @see    processSniff()
89     */
90    public function generate()
91    {
92        foreach ($this->docFiles as $file) {
93            $doc = new \DOMDocument();
94            $doc->load($file);
95            $documentation = $doc->getElementsByTagName('documentation')->item(0);
96            $this->processSniff($documentation);
97        }
98
99    }//end generate()
100
101
102    /**
103     * Process the documentation for a single sniff.
104     *
105     * Doc generators must implement this function to produce output.
106     *
107     * @param \DOMNode $doc The DOMNode object for the sniff.
108     *                      It represents the "documentation" tag in the XML
109     *                      standard file.
110     *
111     * @return void
112     * @see    generate()
113     */
114    abstract protected function processSniff(\DOMNode $doc);
115
116
117}//end class
118