Code Coverage
 
Classes and Traits
Functions and Methods
Lines
Total
0.00% covered (danger)
0.00%
0 / 1
80.00% covered (warning)
80.00%
8 / 10
CRAP
91.27% covered (success)
91.27%
115 / 126
ReferenceStack
0.00% covered (danger)
0.00%
0 / 1
80.00% covered (warning)
80.00%
8 / 10
63.48
91.27% covered (success)
91.27%
115 / 126
 __construct
100.00% covered (success)
100.00%
1 / 1
1
100.00% covered (success)
100.00%
2 / 2
 pushInvalidRef
100.00% covered (success)
100.00%
1 / 1
1
100.00% covered (success)
100.00%
2 / 2
 pushRef
0.00% covered (danger)
0.00%
0 / 1
26.19
93.44% covered (success)
93.44%
57 / 61
 rollbackRefs
100.00% covered (success)
100.00%
1 / 1
4
100.00% covered (success)
100.00%
7 / 7
 rollbackRef
0.00% covered (danger)
0.00%
0 / 1
22.50
81.58% covered (warning)
81.58%
31 / 38
 popGroup
100.00% covered (success)
100.00%
1 / 1
1
100.00% covered (success)
100.00%
5 / 5
 hasGroup
100.00% covered (success)
100.00%
1 / 1
2
100.00% covered (success)
100.00%
1 / 1
 getGroups
100.00% covered (success)
100.00%
1 / 1
3
100.00% covered (success)
100.00%
5 / 5
 getGroupRefs
100.00% covered (success)
100.00%
1 / 1
1
100.00% covered (success)
100.00%
1 / 1
 appendText
100.00% covered (success)
100.00%
1 / 1
2
100.00% covered (success)
100.00%
4 / 4
<?php
namespace Cite;
use LogicException;
use Parser;
use StripState;
/**
 * Encapsulates most of Cite state during parsing.  This includes metadata about each ref tag,
 * and a rollback stack to correct confusion caused by lost context when `{{#tag` is used.
 *
 * @license GPL-2.0-or-later
 */
class ReferenceStack {
    /**
     * Data structure representing all <ref> tags parsed so far, indexed by group name (an empty
     * string for the default group) and reference name.
     *
     * References without a name get a numeric index, starting from 0. Conflicts are avoided by
     * disallowing numeric names (e.g. <ref name="1">) in {@see Cite::validateRef}.
     *
     * Elements (almost all are optional):
     * - 'name': The original name="…" of a reference (also used as the array key), or null for
     *       anonymous references.
     * - 'key': Sequence number for all references, no matter which group, starting from 1. Used to
     *       generate IDs and anchors.
     * - 'number': Sequence number per group, starting from 1. To be used in the [1] footnote
     *       marker.
     * - 'extendsIndex': Sequence number for sub-references with the same extends="…", starting
     *       from 1. Used in addition to the 'number' in [1.1] footnote markers.
     * - 'count': How often a reference is reused. 0 means not reused, i.e. the reference appears
     *       only one time. -1 for anonymous references that cannot be reused.
     * - 'extends': Marks a sub-reference. Points to the parent reference by name.
     * - 'follow': Marks an incomplete follow="…". This is valid e.g. in the Page:… namespace on
     *       Wikisource.
     * - '__placeholder__': Temporarily marks an incomplete parent reference that was referenced via
     *       extends="…" before it exists.
     * - 'text': The content inside the <ref>…</ref> tag. Null for <ref /> without content. Also
     *       null for <ref></ref> without any non-whitespace content.
     * - 'dir': Direction of the text. Should either be "ltr" or "rtl".
     *
     * @var array[][]
     */
    private $refs = [];
    /**
     * Auto-incrementing sequence number for all <ref>, no matter which group
     *
     * @var int
     */
    private $refSequence = 0;
    /**
     * Counter for the number of refs in each group.
     * @var int[]
     */
    private $groupRefSequence = [];
    /**
     * @var int[][]
     */
    private $extendsCount = [];
    /**
     * <ref> call stack
     * Used to cleanup out of sequence ref calls created by #tag
     * See description of function rollbackRef.
     *
     * @var (array|false)[]
     */
    private $refCallStack = [];
    /**
     * @deprecated We should be able to push this responsibility to calling code.
     * @var ErrorReporter
     */
    private $errorReporter;
    /**
     * @param ErrorReporter $errorReporter
     */
    public function __construct( ErrorReporter $errorReporter ) {
        $this->errorReporter = $errorReporter;
    }
    /**
     * Leave a mark in the stack which matches an invalid ref tag.
     */
    public function pushInvalidRef() {
        $this->refCallStack[] = false;
    }
    /**
     * Populate $this->refs and $this->refCallStack based on input and arguments to <ref>
     *
     * @param Parser $parser
     * @param StripState $stripState
     * @param ?string $text Content from the <ref> tag
     * @param string[] $argv
     * @param string $group
     * @param ?string $name
     * @param ?string $extends
     * @param ?string $follow Guaranteed to not be a numeric string
     * @param ?string $dir ref direction
     *
     * @return ?array ref structure, or null if no footnote marker should be rendered
     * @suppress PhanTypePossiblyInvalidDimOffset To many complaints about array indizes
     */
    public function pushRef(
        Parser $parser,
        StripState $stripState,
        ?string $text,
        array $argv,
        string $group,
        ?string $name,
        ?string $extends,
        ?string $follow,
        ?string $dir
    ): ?array {
        if ( !isset( $this->refs[$group] ) ) {
            $this->refs[$group] = [];
        }
        if ( !isset( $this->groupRefSequence[$group] ) ) {
            $this->groupRefSequence[$group] = 0;
        }
        $ref = [
            'count' => $name ? 0 : -1,
            'dir' => $dir,
            // This assumes we are going to register a new reference, instead of reusing one
            'key' => ++$this->refSequence,
            'name' => $name,
            'text' => $text,
        ];
        if ( $follow ) {
            if ( !isset( $this->refs[$group][$follow] ) ) {
                // Mark an incomplete follow="…" as such. This is valid e.g. in the Page:… namespace
                // on Wikisource.
                $this->refs[$group][] = $ref + [ 'follow' => $follow ];
                $this->refCallStack[] = [ 'new', $this->refSequence, $group, $name, $extends, $text,
                    $argv ];
            } elseif ( $text !== null ) {
                // We know the parent already, so just perform the follow="…" and bail out
                $this->appendText( $group, $follow, ' ' . $text );
                $this->refSequence--;
            }
            // A follow="…" never gets its own footnote marker
            return null;
        }
        if ( !$name ) {
            // This is an anonymous reference, which will be given a numeric index.
            $this->refs[$group][] = &$ref;
            $action = 'new';
        } elseif ( isset( $this->refs[$group][$name]['__placeholder__'] ) ) {
            // Populate a placeholder.
            unset( $this->refs[$group][$name]['__placeholder__'] );
            unset( $ref['number'] );
            $ref = array_merge( $ref, $this->refs[$group][$name] );
            $this->refs[$group][$name] =& $ref;
            $action = 'new-from-placeholder';
        } elseif ( !isset( $this->refs[$group][$name] ) ) {
            // Valid key with first occurrence
            $this->refs[$group][$name] = &$ref;
            $action = 'new';
        } else {
            // Change an existing entry.
            $ref = &$this->refs[$group][$name];
            $ref['count']++;
            // Rollback the global counter since we won't create a new ref.
            $this->refSequence--;
            if ( $ref['text'] === null && $text !== null ) {
                // If no text was set before, use this text
                $ref['text'] = $text;
                // Use the dir parameter only from the full definition of a named ref tag
                $ref['dir'] = $dir;
                $action = 'assign';
            } else {
                if ( $text !== null
                    // T205803 different strip markers might hide the same text
                    && $stripState->unstripBoth( $text )
                    !== $stripState->unstripBoth( $ref['text'] )
                ) {
                    // two refs with same name and different text
                    // add error message to the original ref
                    // TODO: standardize error display and move to `validateRef`.
                    $ref['text'] .= ' ' . $this->errorReporter->plain(
                        $parser, 'cite_error_references_duplicate_key', $name
                    );
                }
                $action = 'increment';
            }
        }
        $ref['number'] = $ref['number'] ?? ++$this->groupRefSequence[$group];
        // Do not mess with a known parent a second time
        if ( $extends && !isset( $ref['extendsIndex'] ) ) {
            $this->extendsCount[$group][$extends] =
                ( $this->extendsCount[$group][$extends] ?? 0 ) + 1;
            $ref['extends'] = $extends;
            $ref['extendsIndex'] = $this->extendsCount[$group][$extends];
            if ( isset( $this->refs[$group][$extends]['number'] ) ) {
                // Adopt the parent's number.
                $ref['number'] = $this->refs[$group][$extends]['number'];
                // Roll back the group sequence number.
                --$this->groupRefSequence[$group];
            } else {
                // Transfer my number to parent ref.
                $this->refs[$group][$extends] = [
                    'number' => $ref['number'],
                    '__placeholder__' => true,
                ];
            }
        } elseif ( $extends && $ref['extends'] !== $extends ) {
            // TODO: Change the error message to talk about "conflicting content or parent"?
            $error = $this->errorReporter->plain( $parser, 'cite_error_references_duplicate_key',
                $name );
            if ( isset( $ref['text'] ) ) {
                $ref['text'] .= ' ' . $error;
            } else {
                $ref['text'] = $error;
            }
        }
        $this->refCallStack[] = [ $action, $ref['key'], $group, $name, $extends, $text, $argv ];
        return $ref;
    }
    /**
     * Undo the changes made by the last $count ref tags.  This is used when we discover that the
     * last few tags were actually inside of a references tag.
     *
     * @param int $count
     *
     * @return array[] Refs to restore under the correct context, as a list of [ $text, $argv ]
     */
    public function rollbackRefs( int $count ): array {
        $redoStack = [];
        while ( $count-- && $this->refCallStack ) {
            $call = array_pop( $this->refCallStack );
            if ( $call ) {
                $redoStack[] = $this->rollbackRef( ...$call );
            }
        }
        // Drop unused rollbacks, this group is finished.
        $this->refCallStack = [];
        return array_reverse( $redoStack );
    }
    /**
     * Partially undoes the effect of calls to stack()
     *
     * Called by guardedReferences()
     *
     * The option to define <ref> within <references> makes the
     * behavior of <ref> context dependent.  This is normally fine
     * but certain operations (especially #tag) lead to out-of-order
     * parser evaluation with the <ref> tags being processed before
     * their containing <reference> element is read.  This leads to
     * stack corruption that this function works to fix.
     *
     * This function is not a total rollback since some internal
     * counters remain incremented.  Doing so prevents accidentally
     * corrupting certain links.
     *
     * @param string $action
     * @param int $key Autoincrement counter for this ref.
     * @param string $group
     * @param ?string $name The name attribute passed in the ref tag.
     * @param ?string $extends
     * @param ?string $text
     * @param array $argv
     *
     * @return array [ $text, $argv ] Ref redo item.
     */
    private function rollbackRef(
        string $action,
        int $key,
        string $group,
        ?string $name,
        ?string $extends,
        ?string $text,
        array $argv
    ): array {
        if ( !$this->hasGroup( $group ) ) {
            throw new LogicException( "Cannot roll back ref with unknown group \"$group\"." );
        }
        $lookup = $name ?: null;
        if ( $lookup === null ) {
            // Find anonymous ref by key.
            foreach ( $this->refs[$group] as $k => $v ) {
                if ( isset( $this->refs[$group][$k]['key'] ) &&
                    $this->refs[$group][$k]['key'] === $key
                ) {
                    $lookup = $k;
                    break;
                }
            }
        }
        // Obsessive sanity checks that the specified element exists.
        if ( $lookup === null ) {
            throw new LogicException( "Cannot roll back unknown ref by key $key." );
        } elseif ( !isset( $this->refs[$group][$lookup] ) ) {
            throw new LogicException( "Cannot roll back missing named ref \"$lookup\"." );
        } elseif ( $this->refs[$group][$lookup]['key'] !== $key ) {
            throw new LogicException(
                "Cannot roll back corrupt named ref \"$lookup\" which should have had key $key." );
        }
        if ( $extends ) {
            $this->extendsCount[$group][$extends]--;
        }
        switch ( $action ) {
            case 'new':
                // Rollback the addition of new elements to the stack
                unset( $this->refs[$group][$lookup] );
                if ( !$this->refs[$group] ) {
                    $this->popGroup( $group );
                } elseif ( isset( $this->groupRefSequence[$group] ) ) {
                    $this->groupRefSequence[$group]--;
                }
                // TODO: Don't we need to rollback extendsCount as well?
                break;
            case 'new-from-placeholder':
                $this->refs[$group][$lookup]['__placeholder__'] = true;
                unset( $this->refs[$group][$lookup]['count'] );
                break;
            case 'assign':
                // Rollback assignment of text to pre-existing elements
                $this->refs[$group][$lookup]['text'] = null;
                $this->refs[$group][$lookup]['count']--;
                break;
            case 'increment':
                // Rollback increase in named ref occurrences
                $this->refs[$group][$lookup]['count']--;
                break;
            default:
                throw new LogicException( "Unknown call stack action \"$action\"" );
        }
        return [ $text, $argv ];
    }
    /**
     * Clear state for a single group.
     *
     * @param string $group
     *
     * @return array[] The references from the removed group
     */
    public function popGroup( string $group ): array {
        $refs = $this->getGroupRefs( $group );
        unset( $this->refs[$group] );
        unset( $this->groupRefSequence[$group] );
        unset( $this->extendsCount[$group] );
        return $refs;
    }
    /**
     * Retruns true if the group exists and contains references.
     *
     * @param string $group
     *
     * @return bool
     */
    public function hasGroup( string $group ): bool {
        return isset( $this->refs[$group] ) && $this->refs[$group];
    }
    /**
     * Returns a list of all groups with references.
     *
     * @return string[]
     */
    public function getGroups(): array {
        $groups = [];
        foreach ( $this->refs as $group => $refs ) {
            if ( $refs ) {
                $groups[] = $group;
            }
        }
        return $groups;
    }
    /**
     * Return all references for a group.
     *
     * @param string $group
     *
     * @return array[]
     */
    public function getGroupRefs( string $group ): array {
        return $this->refs[$group] ?? [];
    }
    /**
     * @param string $group
     * @param string $name
     * @param string $text
     */
    public function appendText( string $group, string $name, string $text ) {
        if ( isset( $this->refs[$group][$name]['text'] ) ) {
            $this->refs[$group][$name]['text'] .= $text;
        } else {
            $this->refs[$group][$name]['text'] = $text;
        }
    }
}