Context
in package
What a rule may use besides the record it converts: the options, the prepass, new xrefs and records, and the loss report. Losses are located in the source document: the document being converted is a copy of it, so a node keeps its id; a node added during the conversion is located at its nearest ancestor from the source, a line that could not be parsed at the structure it is in (the path of a file-level one is empty).
A route of several steps converts each record through every step in turn. The first step looks structures up in the input; a later one in the record as it was when the step began.
Table of Contents
Properties
Methods
- __construct() : mixed
- addRecord() : int
- A new record before TRLR, already in the target version of the current step (its value is escaped and split into CONT lines for that version); the remaining steps convert it too.
- addText() : int
- A new last substructure with a text value written by setValue(): the PHRASE a value rule keeps the original in, say.
- enter() : void
- extractRecord() : int
- A new record before TRLR that the current step converts too, like a record of the input: the structures a rule moves into it are converted with it (a structure taken out of a record into a record of its own). What a rule writes into it is written by the target version's rules (setValue()), like every structure a rule creates: syntax rules skip structures that are not from the source.
- head() : Node|null
- HEAD of the document being converted: in it, every record after HEAD sees HEAD converted.
- inExtension() : bool
- Whether a structure of the document being converted is an extension or inside one, by the tags it has now; cached for one record at a time, so ask before renaming its ancestors.
- inputHasExtension() : bool
- Whether the input has a structure with this extension tag. The first call walks every line of the input once (convertFile(): reads the file once more).
- inRestored() : bool
- Whether a structure is one restored() that a step before made an extension or inside one: its value may be in the form of the version before the source.
- isFromSource() : bool
- Whether a structure is in the source of the current step (the input; in a later step, the record as the step began): one a rule of the step created is written by the target version's rules already (setValue()), so a syntax rule must not rewrite it.
- loss() : void
- Reports data that the target version cannot hold as it was.
- losses() : array<int, Loss>
- newXref() : string
- The next free xref of the form @X<n>@ (SPEC section 7: "the next free n in document order"); needs the prepass.
- prepass() : Prepass
- restored() : void
- An extension made a structure again (Extensions) is read as the source structure of its tag that its value fits ($uri): the source has none there, but the rules after convert its value from it.
- setHeadDocument() : void
- setValue() : void
- Sets a text value by the rules of the current step's target version: its "@" escaping, "\n" as CONT lines.
- sourceElement() : string|null
- The payload element of a structure in the current step's source version ("<DATE_VALUE>" in 5.5.1; "<MULTIMEDIA_FILE_REFN>" for "<MULTIMEDIA_FILE_REFN>|<NULL>": a value that is there is that element), found by its place in the source document: a structure a rule moved keeps what it was. Null for a structure the conversion added, one the source version does not define there, and anything inside an extension of the document being converted.
- sourceForm() : "pointer"|"inline"|null
- 5.x: the form a structure of the source (isFromSource(), $structure its sourceStructure()) had as the step began (Structure::form()); null for a structure without forms.
- sourceStructure() : Structure|null
- The structure of a node in the current step's source version, by its place in the source document (like sourceElement()): null for a structure the conversion added, one the version does not define there, and anything inside an extension.
- takeAdded() : array<int, array{int, bool}>
- unit() : void
- unsupported() : bool
- A structure the target version has no place for: kept as an extension, "_" and its tag, with its substructures, or removed under LossPolicy::DropWithReport; reported either way.
- value() : string|null
- A text value read by the rules of the current step's target version: what setValue() wrote, and any value once the step's syntax rule has rewritten it (5.5.1 → 7.0: TextValues).
Properties
$options read-only
public
ConvertOptions
$options
Methods
__construct()
public
__construct(Document $source, Document $document, ConvertOptions $options, Prepass|null $prepass[, callable(): array<string, true>|null $inputExtensions = null ]) : mixed
Parameters
- $source : Document
- $document : Document
- $options : ConvertOptions
- $prepass : Prepass|null
- $inputExtensions : callable(): array<string, true>|null = null
-
the extension tags of the input, when they do not come from $source
addRecord()
A new record before TRLR, already in the target version of the current step (its value is escaped and split into CONT lines for that version); the remaining steps convert it too.
public
addRecord(string $tag[, string|null $xref = null ][, string|null $value = null ]) : int
Parameters
- $tag : string
- $xref : string|null = null
- $value : string|null = null
Return values
intaddText()
A new last substructure with a text value written by setValue(): the PHRASE a value rule keeps the original in, say.
public
addText(int $parent, string $tag, string $value) : int
Parameters
- $parent : int
- $tag : string
- $value : string
Return values
intenter()
public
enter(Step $step, int $record, bool $first) : void
Parameters
- $step : Step
- $record : int
- $first : bool
extractRecord()
A new record before TRLR that the current step converts too, like a record of the input: the structures a rule moves into it are converted with it (a structure taken out of a record into a record of its own). What a rule writes into it is written by the target version's rules (setValue()), like every structure a rule creates: syntax rules skip structures that are not from the source.
public
extractRecord(string $tag, string $xref) : int
Parameters
- $tag : string
- $xref : string
Return values
inthead()
HEAD of the document being converted: in it, every record after HEAD sees HEAD converted.
public
head() : Node|null
Return values
Node|nullinExtension()
Whether a structure of the document being converted is an extension or inside one, by the tags it has now; cached for one record at a time, so ask before renaming its ancestors.
public
inExtension(int $id) : bool
Parameters
- $id : int
Return values
boolinputHasExtension()
Whether the input has a structure with this extension tag. The first call walks every line of the input once (convertFile(): reads the file once more).
public
inputHasExtension(string $tag) : bool
Parameters
- $tag : string
Return values
boolinRestored()
Whether a structure is one restored() that a step before made an extension or inside one: its value may be in the form of the version before the source.
public
inRestored(int $node) : bool
Parameters
- $node : int
Return values
boolisFromSource()
Whether a structure is in the source of the current step (the input; in a later step, the record as the step began): one a rule of the step created is written by the target version's rules already (setValue()), so a syntax rule must not rewrite it.
public
isFromSource(int $node) : bool
Parameters
- $node : int
Return values
boolloss()
Reports data that the target version cannot hold as it was.
public
loss(string $code, Severity $severity, int $node, StoredAs $storedAs, string $message) : void
Parameters
Tags
losses()
public
losses() : array<int, Loss>
Return values
array<int, Loss>newXref()
The next free xref of the form @X<n>@ (SPEC section 7: "the next free n in document order"); needs the prepass.
public
newXref() : string
Return values
stringprepass()
public
prepass() : Prepass
Tags
Return values
Prepassrestored()
An extension made a structure again (Extensions) is read as the source structure of its tag that its value fits ($uri): the source has none there, but the rules after convert its value from it.
public
restored(int $node, string $uri) : void
What is inside an extension of the input is in the target's form already, as the conversion the other way writes it. What is inside one a step before made is in the form of the version before: read as the substructures of that structure, and converted (what the target does not list becomes an extension); its loss goes, as the output has the structure.
Parameters
- $node : int
- $uri : string
setHeadDocument()
public
setHeadDocument(Document $document) : void
Parameters
- $document : Document
setValue()
Sets a text value by the rules of the current step's target version: its "@" escaping, "\n" as CONT lines.
public
setValue(int $node, string|null $value) : void
Parameters
- $node : int
- $value : string|null
sourceElement()
The payload element of a structure in the current step's source version ("<DATE_VALUE>" in 5.5.1; "<MULTIMEDIA_FILE_REFN>" for "<MULTIMEDIA_FILE_REFN>|<NULL>": a value that is there is that element), found by its place in the source document: a structure a rule moved keeps what it was. Null for a structure the conversion added, one the source version does not define there, and anything inside an extension of the document being converted.
public
sourceElement(int $node) : string|null
In a later step of a route, the place is the one the structure had when the step began.
Parameters
- $node : int
Return values
string|nullsourceForm()
5.x: the form a structure of the source (isFromSource(), $structure its sourceStructure()) had as the step began (Structure::form()); null for a structure without forms.
public
sourceForm(int $node, Structure $structure) : "pointer"|"inline"|null
Parameters
- $node : int
- $structure : Structure
Return values
"pointer"|"inline"|nullsourceStructure()
The structure of a node in the current step's source version, by its place in the source document (like sourceElement()): null for a structure the conversion added, one the version does not define there, and anything inside an extension.
public
sourceStructure(int $node) : Structure|null
Parameters
- $node : int
Return values
Structure|nulltakeAdded()
public
takeAdded() : array<int, array{int, bool}>
Return values
array<int, array{int, bool}> —records added since the last call, and whether the step that added them converts them too
unit()
public
unit(Document $source, Document $document, Prepass|null $prepass) : void
Parameters
unsupported()
A structure the target version has no place for: kept as an extension, "_" and its tag, with its substructures, or removed under LossPolicy::DropWithReport; reported either way.
public
unsupported(int $node, string $code, string $message) : bool
Parameters
- $node : int
- $code : string
- $message : string
Tags
Return values
bool —whether the structure is still there
value()
A text value read by the rules of the current step's target version: what setValue() wrote, and any value once the step's syntax rule has rewritten it (5.5.1 → 7.0: TextValues).
public
value(int $node) : string|null
Parameters
- $node : int