Guides

DirectiveRule
in package
implements Rule uses ReportsViolations

FinalYes
Tags
link
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#directives

Table of Contents

Interfaces

Rule

Constants

PRIORITY  : mixed = 70

Properties

$directives  : array<string, BaseDirective>
$generalDirective  : GeneralDirective
$inlineMarkupRule  : InlineMarkupRule
$logger  : LoggerInterface
$startingRule  : Rule|null
$violationReporter  : ViolationReporter|null

Methods

__construct()  : mixed
applies()  : bool
apply()  : TNode|null
Enters this state and loops through all relevant lines until a Node is produced.
collectDirectiveContents()  : Buffer
collectDirectiveOptionContent()  : void
Collects the content of multiline directive options:
getDirectiveHandler()  : BaseDirective
interpretDirectiveOptions()  : void
isDirectiveOption()  : bool
parseDirective()  : Directive|null
parseDirectiveOption()  : DirectiveOption
Directive options are stored in the field-list syntax:
parseDirectiveValue()  : void
Validates and, only for {@see DirectiveValueType::Inline}, parses the directive's own value -- the text right after `::`, e.g. the "image.jpg" in `.. figure:: image.jpg`. This is unrelated to the directive's body/content, the indented block that follows on later lines, which {@see collectDirectiveContents()} collects separately regardless of what happens here.
postProcessNode()  : Node
Post processes a node created by a directive to apply common options
registerDirective()  : void
reportViolation()  : void
validateDirectiveValue()  : void
Warns when a directive's value doesn't look like what its declared {@see DirectiveValueType} expects. Diagnostic only -- an invalid value is still passed through as-is via Directive::getData(), nothing here rewrites or rejects it. A value type is never required (an empty value is always allowed except for Empty, which requires it), so only a non-empty value gets checked against its declared shape.

Constants

Properties

Methods

__construct()

public __construct(InlineMarkupRule $inlineMarkupRule, LoggerInterface $logger, GeneralDirective $generalDirective[, iterable<string|int, BaseDirective> $directives = [] ][, Rule<string|int, Node>|null $startingRule = null ][, ViolationReporter|null $violationReporter = null ]) : mixed
Parameters
$inlineMarkupRule : InlineMarkupRule
$logger : LoggerInterface
$generalDirective : GeneralDirective
$directives : iterable<string|int, BaseDirective> = []
$startingRule : Rule<string|int, Node>|null = null
$violationReporter : ViolationReporter|null = null

apply()

Enters this state and loops through all relevant lines until a Node is produced.

public apply(BlockContext $blockContext[, CompoundNode|null $on = null ]) : TNode|null

The opening line is considered relevant and as such is always used (this is found the case in the self::Applies() method, otherwise we wouldn't have been here) but for all subsequent lines we use a Look Ahead to test whether it should be included in the Node.

By using a Look Ahead, we prevent the cursor from advancing; and this caused the cursor to 'rest' on the line that is considered that last relevant line. The document parser will advance the line after successfully parsing this and to send the Parser into a line that belongs to another state.

Parameters
$blockContext : BlockContext
$on : CompoundNode|null = null
Return values
TNode|null

collectDirectiveOptionContent()

Collects the content of multiline directive options:

private collectDirectiveOptionContent(LinesIterator $documentIterator, DirectiveOption $directiveOption) : void

.. figure:: foo.jpg :width: 100 :alt: Field options might use more than one line

This is a foo!

Parameters
$documentIterator : LinesIterator
$directiveOption : DirectiveOption

isDirectiveOption()

private isDirectiveOption(string|null $line) : bool
Parameters
$line : string|null
Return values
bool

parseDirectiveOption()

Directive options are stored in the field-list syntax:

private parseDirectiveOption(string $line) : DirectiveOption

.. figure:: foo.jpg :width: 100 :alt: Field options might use more than one line :yet another option: abc :empty option:

Parameters
$line : string
Tags
throws
InvalidArgumentException
Return values
DirectiveOption

parseDirectiveValue()

Validates and, only for {@see DirectiveValueType::Inline}, parses the directive's own value -- the text right after `::`, e.g. the "image.jpg" in `.. figure:: image.jpg`. This is unrelated to the directive's body/content, the indented block that follows on later lines, which {@see collectDirectiveContents()} collects separately regardless of what happens here.

private parseDirectiveValue(Directive $directive, BlockContext $blockContext, BaseDirective $directiveHandler) : void
Parameters
$directive : Directive
$blockContext : BlockContext
$directiveHandler : BaseDirective

validateDirectiveValue()

Warns when a directive's value doesn't look like what its declared {@see DirectiveValueType} expects. Diagnostic only -- an invalid value is still passed through as-is via Directive::getData(), nothing here rewrites or rejects it. A value type is never required (an empty value is always allowed except for Empty, which requires it), so only a non-empty value gets checked against its declared shape.

private validateDirectiveValue(Directive $directive, BlockContext $blockContext, DirectiveValueType $valueType) : void
Parameters
$directive : Directive
$blockContext : BlockContext
$valueType : DirectiveValueType
On this page

Search results