Korin API

Context
in package

FinalYes

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

$options  : ConvertOptions

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

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
int

addText()

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
int

enter()

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
int

head()

HEAD of the document being converted: in it, every record after HEAD sees HEAD converted.

public head() : Node|null
Return values
Node|null

inExtension()

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
bool

inputHasExtension()

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
bool

inRestored()

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
bool

isFromSource()

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
bool

loss()

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
$code : string
$severity : Severity
$node : int
$storedAs : StoredAs
$message : string
Tags
throws
ConversionException

under LossPolicy::Fail

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
string

prepass()

public prepass() : Prepass
Tags
throws
LogicException

when no rule of the conversion declared needsPrepass()

Return values
Prepass

restored()

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

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|null

sourceForm()

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"|null

sourceStructure()

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|null

takeAdded()

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

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
throws
ConversionException

under LossPolicy::Fail

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
Return values
string|null
On this page

Search results