Completed
Push — develop ( 8eb671...133594 )
by Mike
19:30 queued 09:24
created

Converter/RestructuredText/Visitors/Discover.php (1 issue)

Upgrade to new PHP Analysis Engine

These results are based on our legacy PHP analysis, consider migrating to our new PHP analysis engine instead. Learn more

1
<?php
2
declare(strict_types=1);
3
4
/**
5
 * This file is part of phpDocumentor.
6
 *
7
 * For the full copyright and license information, please view the LICENSE
8
 * file that was distributed with this source code.
9
 *
10
 * @author    Mike van Riel <[email protected]>
11
 * @copyright 2010-2018 Mike van Riel / Naenius (http://www.naenius.com)
12
 * @license   http://www.opensource.org/licenses/mit-license.php MIT
13
 * @link      http://phpdoc.org
14
 */
15
16
namespace phpDocumentor\Plugin\Scrybe\Converter\RestructuredText\Visitors;
17
18
use \phpDocumentor\Plugin\Scrybe\Converter\Metadata\TableOfContents;
19
use ezcDocumentRstDocumentNode;
20
use ezcDocumentRstSectionNode;
21
22
/**
23
 * A specialized RestructuredText Parser/Visitor to aid in the discovery phase.
24
 *
25
 * This class collects all headings and their titles and populates the TableOfContents collection.
26
 */
27
class Discover extends Creator
28
{
29
    /**
30
     * This array is meant as a cache of the last entry per depth.
31
     *
32
     * To build a hierarchy from a non-recursive method, such as visitSection(), you need a way to reference the last
33
     * Entry per depth.
34
     *
35
     * By keeping track of these pointers you know onto which parent you will need to add a node by checking which of
36
     * higher depth was parsed last.
37
     *
38
     * Important: because it is possible that levels are 'skipped' we will need to unset all 'deeper' depths when
39
     * setting a new one. Otherwise we might inadvertently add an entry to the wrong tree.
40
     *
41
     * @var TableOfContents\Heading[]
42
     */
43
    protected $entry_pointers = [];
44
45
    /**
46
     * This is a pointer to the last discovered heading.
47
     *
48
     * Directives and roles may 'include' Files as children of the currently parsed heading. Elements as the toctree
49
     * directive or a plain include are examples of such.
50
     *
51
     * @var TableOfContents\Heading
52
     */
53
    protected $last_heading = null;
54
55
    public function visit(\ezcDocumentRstDocumentNode $ast)
56
    {
57
        $toc = $this->getTableOfContents();
58
        $file = $toc[$this->getFilenameWithoutExtension()];
59
        $this->entry_pointers[0] = null; // there is no level 0, 1-based list
60
        $this->entry_pointers[1] = $file;
61
        $this->last_heading = $file;
62
63
        return parent::visit($ast);
64
    }
65
66
    /**
67
     * Visitor for the section heading used to populate the TableOfContents.
68
     *
69
     * This method interprets the heading and its containing text and adds new entries to the TableOfContents object
70
     * in the RestructuredText document.
71
     *
72
     * @see getDocument() for the document containing the TableOfContents.
73
     * @see phpDocumentor\Plugin\Scrybe\Converter\Metadata\TableOfContents for the Table of Contents class.
74
     */
75
    protected function visitSection(\DOMNode $root, \ezcDocumentRstNode $node)
76
    {
77
        if ($node instanceof ezcDocumentRstSectionNode || $node instanceof ezcDocumentRstDocumentNode) {
78
            if ($node->depth === 1) {
79
                $toc = $this->getTableOfContents();
80
                $file = $toc[$this->getFilenameWithoutExtension()];
81
                $file->setName($this->nodeToString($node->title));
82
            } else {
83
                // find nearest parent pointer depth-wise
84
                $parent_depth = $node->depth - 1;
85
                while (!isset($this->entry_pointers[$parent_depth]) && $parent_depth > 0) {
86
                    --$parent_depth;
87
                }
88
89
                $parent = $this->entry_pointers[$parent_depth];
90
                $heading = new TableOfContents\Heading($parent);
91
                $heading->setName($this->nodeToString($node->title));
92
                $heading->setSlug($node->reference);
93
                $parent->addChild($heading);
0 ignored issues
show
$heading is of type object<phpDocumentor\Plu...ableOfContents\Heading>, but the function expects a object<self>.

It seems like the type of the argument is not accepted by the function/method which you are calling.

In some cases, in particular if PHP’s automatic type-juggling kicks in this might be fine. In other cases, however this might be a bug.

We suggest to add an explicit type cast like in the following example:

function acceptsInteger($int) { }

$x = '123'; // string "123"

// Instead of
acceptsInteger($x);

// we recommend to use
acceptsInteger((integer) $x);
Loading history...
94
95
                // set as last indexed heading
96
                $this->last_heading = $heading;
97
98
                // add as new entry pointer
99
                array_splice($this->entry_pointers, $parent_depth + 1, count($this->entry_pointers), [$heading]);
100
            }
101
        }
102
103
        parent::visitSection($root, $node);
104
    }
105
106
    /**
107
     * Adds a TableOfContents File object to the last heading that was discovered.
108
     *
109
     * This may be used by roles or directives to insert an include file into the TableOfContents and thus all
110
     * its headings.
111
     *
112
     * This method is explicitly bound to File objects and not other BaseEntry descendents because inline elements
113
     * such as headings should also modify the internal pointers for this visitor.
114
     */
115
    public function addFileToLastHeading(TableOfContents\File $file)
116
    {
117
        $this->last_heading->addChild($file);
118
        $file->setParent($this->last_heading);
119
    }
120
}
121