Guides

LiteralincludeDirective extends BaseDirective
in package

FinalYes

A directive is like a function you can call or apply to a block It looks like:

.. function:: main :arg1: value :arg2: otherValue

Some block !

The directive can define variables, create special nodes or change the node that directly follows it

Table of Contents

Properties

$codeNodeOptionMapper  : CodeNodeOptionMapper
$logger  : LoggerInterface|null

Methods

__construct()  : mixed
createNode()  : Node|null
getAliases()  : array<string|int, string>
Allow a directive to be registered under multiple names.
getName()  : string
Get the directive name
process()  : Node|null
This is the function called by the parser to process the directive, it can be overloaded to do anything with the document, like tweaking nodes or change the parser context
processNode()  : Node
This can be overloaded to write a directive that just create one node for the document, which is common
optionsToArray()  : array<string, scalar|null>
readAllOptions()  : array<string, scalar|array<string|int, scalar>|null>
readOption()  : mixed
Gets an option value from a directive based on attribute configuration.
findMarker()  : int|null
Returns the number of the first line at or behind $offset that contains $marker, or null if there is none.
optionValue()  : string|null
Returns the text of an option, or null if the option was used without a usable value.
parseRange()  : array{int, int}
Splits a single entry of the ``lines`` option into its first and last line number.
selectLineRanges()  : array<string|int, string>
Reduces the included region to the line numbers listed in ``lines``, for example ``1,3-5,20-``.
selectLines()  : array<string|int, string>
Reduces the included file to the region enclosed by the ``start-after`` and ``end-before`` markers.
warnMarkerNotFound()  : void

Properties

Methods

getAliases()

Allow a directive to be registered under multiple names.

public getAliases() : array<string|int, string>

Aliases can be used for directives whose name has been deprecated or allows for multiple spellings.

Return values
array<string|int, string>

process()

This is the function called by the parser to process the directive, it can be overloaded to do anything with the document, like tweaking nodes or change the parser context

public process(BlockContext $blockContext, Directive $directive) : Node|null

The node that directly follows the directive is also passed to it

Parameters
$blockContext : BlockContext

the current document context with the content of the directive

$directive : Directive

parsed directive containing options and variable

Return values
Node|null

optionsToArray()

protected optionsToArray(array<string|int, DirectiveOption> $options) : array<string, scalar|null>
Parameters
$options : array<string|int, DirectiveOption>
Return values
array<string, scalar|null>

readAllOptions()

protected final readAllOptions(Directive $directive) : array<string, scalar|array<string|int, scalar>|null>
Parameters
$directive : Directive
Return values
array<string, scalar|array<string|int, scalar>|null>

readOption()

Gets an option value from a directive based on attribute configuration.

protected final readOption(Directive $directive, string $optionName) : mixed

Looks up the option in the directive and returns its value converted to the appropriate type based on the Option attribute defined on this directive class. If the option is not present in the directive, returns the default value from the attribute.

Parameters
$directive : Directive

The directive containing the options

$optionName : string

The name of the option to retrieve

Return values
mixed —

The option value converted to the appropriate type, or the default value

findMarker()

Returns the number of the first line at or behind $offset that contains $marker, or null if there is none.

private findMarker(array<string|int, string> $lines, string $marker, int $offset) : int|null
Parameters
$lines : array<string|int, string>
$marker : string
$offset : int
Return values
int|null

parseRange()

Splits a single entry of the ``lines`` option into its first and last line number.

private parseRange(string $range, int $lineCount) : array{int, int}

Both are clamped to the lines actually available, so that a range far beyond the end of the file does not turn into a loop over the numbers the author wrote down. A first line greater than the last one means the range selects nothing.

Parameters
$range : string
$lineCount : int
Return values
array{int, int}

selectLineRanges()

Reduces the included region to the line numbers listed in ``lines``, for example ``1,3-5,20-``.

private selectLineRanges(array<string|int, string> $lines, Directive $directive, BlockContext $blockContext) : array<string|int, string>

Line numbers are 1 based, ranges are inclusive and an omitted end means "up to the last line". They count within the region selected by start-after and end-before, not within the file.

Parameters
$lines : array<string|int, string>
$directive : Directive
$blockContext : BlockContext
Return values
array<string|int, string>

selectLines()

Reduces the included file to the region enclosed by the ``start-after`` and ``end-before`` markers.

private selectLines(array<string|int, string> $lines, Directive $directive, BlockContext $blockContext) : array<string|int, string>

The region starts on the line following the first line containing the start-after marker and ends on the line preceding the first line containing the end-before marker. The end-before marker is searched behind the start of the region, so the same marker text may be used more than once in a file.

Parameters
$lines : array<string|int, string>
$directive : Directive
$blockContext : BlockContext
Return values
array<string|int, string>
On this page

Search results