Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
0.00% covered (danger)
0.00%
0 / 10
0.00% covered (danger)
0.00%
0 / 9
 CRAP
0.00% covered (danger)
0.00%
0 / 1
PipelineStage
0.00% covered (danger)
0.00%
0 / 10
0.00% covered (danger)
0.00%
0 / 9
 90
0.00% covered (danger)
0.00%
0 / 1
 __construct
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 setPipelineId
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getPipelineId
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getEnv
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 addTransformer
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 resetState
0.00% covered (danger)
0.00%
0 / 2
0.00% covered (danger)
0.00%
0 / 1
 2
 setFrame
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 setSrcOffsets
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getSrcOffsets
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 process
n/a
0 / 0
n/a
0 / 0
 0
 processChunkily
n/a
0 / 0
n/a
0 / 0
 0
 finalize
n/a
0 / 0
n/a
0 / 0
 0
1<?php
2declare( strict_types = 1 );
3
4namespace Wikimedia\Parsoid\Wt2Html;
5
6use Generator;
7use Wikimedia\Parsoid\Config\Env;
8use Wikimedia\Parsoid\Core\SourceRange;
9use Wikimedia\Parsoid\DOM\DocumentFragment;
10use Wikimedia\Parsoid\DOM\Element;
11use Wikimedia\Parsoid\Tokens\Token;
12use Wikimedia\Parsoid\Wt2Html\TT\TokenHandler;
13
14/**
15 * This represents the abstract interface for a wt2html parsing pipeline stage
16 * Currently there are four known pipeline stages:
17 * - PEGTokenizer
18 * - TokenHandlerPipeline
19 * - TreeBuilder/TreeBuilderStage ( Remex-based HTML5 Tree Builder )
20 * - DOMProcessorPipeline
21 */
22abstract class PipelineStage {
23    /** This is primarily a debugging aid. */
24    protected ?int $pipelineId = -1;
25    protected ?Env $env = null;
26    /** Defaults to false and resetState initializes it */
27    protected bool $atTopLevel = false;
28    protected bool $toFragment = true;
29    /** Both these default to null and are set by helper methods */
30    protected ?Frame $frame = null;
31    protected ?SourceRange $srcOffsets = null;
32
33    public function __construct( Env $env ) {
34        $this->env = $env;
35    }
36
37    public function setPipelineId( int $id ): void {
38        $this->pipelineId = $id;
39    }
40
41    public function getPipelineId(): int {
42        return $this->pipelineId;
43    }
44
45    public function getEnv(): Env {
46        return $this->env;
47    }
48
49    /**
50     * Register a token transformer
51     */
52    public function addTransformer( TokenHandler $t ): void {
53        throw new \BadMethodCallException( "This pipeline stage doesn't accept token transformers." );
54    }
55
56    /**
57     * Resets any internal state for this pipeline stage.
58     * This is usually called so a cached pipeline can be reused.
59     */
60    public function resetState( array $options ): void {
61        /* Default implementation */
62        $this->atTopLevel = $options['toplevel'] ?? false;
63        $this->toFragment = $options['toFragment'] ?? true;
64    }
65
66    /**
67     * Set frame on this pipeline stage
68     */
69    public function setFrame( Frame $frame ): void {
70        $this->frame = $frame;
71    }
72
73    /**
74     * Set the source offsets for the content being processed by this pipeline.
75     * This matters for when a substring of the top-level page is being processed
76     * in its own pipeline. This ensures that all source offsets assigned to tokens
77     * and DOM nodes in this stage are relative to the top-level page.
78     */
79    public function setSrcOffsets( SourceRange $srcOffsets ): void {
80        $this->srcOffsets = $srcOffsets;
81    }
82
83    public function getSrcOffsets(): ?SourceRange {
84        return $this->srcOffsets;
85    }
86
87    /**
88     * Process wikitext, an array of tokens, or a DOM document depending on
89     * what pipeline stage this is. This will be entirety of the input that
90     * will be processed by this pipeline stage and no further input or an EOF
91     * signal will follow.
92     *
93     * @param string|array|DocumentFragment|Element $input
94     * @param array{atTopLevel:bool,sol:bool} $options
95     *  - atTopLevel: (bool) Whether we are processing the top-level document
96     *  - sol: (bool) Whether input should be processed in start-of-line context
97     *  - chunky (bool) Whether we are processing the input chunkily.
98     * @return list<Token|string>|DocumentFragment|Element
99     */
100    abstract public function process(
101        string|array|DocumentFragment|Element $input,
102        array $options
103    ): array|Element|DocumentFragment;
104
105    /**
106     * Process wikitext, an array of tokens, or a DOM document depending on
107     * what pipeline stage this is. This method will either directly or indirectly
108     * implement a generator that parses the input in chunks and yields output
109     * in chunks as well.
110     *
111     * Implementations that don't consume tokens (ex: Tokenizer, DOMProcessorPipeline)
112     * will provide specialized implementations that handle their input type.
113     *
114     * @param string|array|DocumentFragment|Element $input
115     * @param array{atTopLevel:bool,sol:bool} $options
116     *  - atTopLevel: (bool) Whether we are processing the top-level document
117     *  - sol: (bool) Whether input should be processed in start-of-line context
118     * @return Generator<list<Token|string>|DocumentFragment|Element>
119     */
120    abstract public function processChunkily(
121        string|array|DocumentFragment|Element $input,
122        array $options
123    ): Generator;
124
125    /**
126     * Finalize stage. This lets us not worry about tracking EOFTk but
127     * still ensures that we always exit the pipeline no matter the error.
128     */
129    abstract public function finalize(): Generator;
130}