laika.ast

Extractors for pattern matching against absolute and relative paths.

Represents a target defined by an absolute path.

Label with automatic numbering.

Label using automatic numbering and explicit label names together.

Label with automatic symbol assignment.

The base type for all block level elements.

A container of other Block elements. Such a container is usually also a Block itself.

Common methods for simple block containers (without additional parameters).

Represents a placeholder block element that needs to be resolved in a rewrite step. Useful for elements that need access to the document, structure, title or configuration before being fully resolved.

Represents a block element that introduces new context that can be used in substitution references in any child element.

Usually used in directive implementations and not contributing to the rendered output itself.

A generic container element containing a list of blocks. Can be used where a sequence of blocks must be inserted in a place where a single element is required by the API. Usually renderers do not treat the container as a special element and render its children as s sub flow of the parent container.

A cell in the body part of the table.

The format of a bullet list item.

A bullet list that may contain nested lists.

Companion for creating BulletList instances.

Base trait for companions that create BulletList instances.

A single bullet list item consisting of one or more block elements.

The table caption.

A single span inside a code block that has been categorized by a syntax highlighter.

A single cell, potentially spanning multiple rows or columns, containing one or more block elements.

The cell type specifies which part of the table the cell belongs to.

Represents a single choice in a ChoiceGroup.

A citation that can be referred to by a CitationLink by id.

A resolved link to a citation.

A reference to a citation with a matching label. Only part of the raw document tree and then removed by the rewrite rule that resolves link and image references.

A block of program code. The content is a sequence of spans to support the integration of syntax highlighting systems. For unsupported languages the sequence will only consist of a single Text element.

A span of code associated with zero or more code categories.

A sequence of code spans where most of them are usually associated with zero or more code categories.

The options (like styles) for a column table.

Contains the (optional) column specification of a table.

Convenient factory for creating a Columns instance based on the options for the individual columns.

A comment that may be omitted by renderers.

A generic container. Usually not mixed in directly, instead one of the sub-traits TextContainer, ListContainer, SpanContainer or BlockContainer should be used.

Represents a reference to a value from the context of the current document. The ref attribute is a simple path expression in dot notation for accessing properties of an object (or keys of a Map).

The root elements accessible to such a reference are:

• document: the current document with all of its public properties
• parent: the parent tree of the current document
• root: the root tree
• config: all configuration values for the current document, including those inherited from parent trees

A cursor provides the necessary context during a rewrite operation. The stateless document tree cannot provide access to parent or sibling nodes in the tree, therefore a temporary cursor instance is created during a rewrite operation for this purpose.

A decorated header where the level gets determined in the rewrite phase based on the decoration used and the order they appear in the document. The first decoration type encountered is used for level 1, the second for level 2, and so on.

Represents a definition that can be used to resolve references.

Only part of the raw document tree and then removed or replaced by a rewrite rule before rendering.

A list of terms and their definitions. Not related to the Definition base trait.

A single definition item, containing the term and definition (as the content property).

A span representing deleted inline elements that may contain nested spans.

Represents a single document and provides access to the document content and structure as well as hooks for triggering rewrite operations.

Cursor for a single document, its parent, siblings and root directories, its associated template and other context information that is required during a rewrite operation.

A named document fragment that usually gets rendered separately from the main root element

Metadata associated with a document.

Represents a document structure with sections that can be turned into a navigation structure.

The structure of a markup document.

Represents a tree with all its documents, templates, configurations and subtrees.

Represents the root of a tree of documents. In addition to the recursive structure of documents, usually obtained by parsing text markup, it holds additional items like styles and static documents, which may contribute to the rendering of a site or an e-book.

The styles property of this type is currently only populated and processed when rendering PDF or XSL-FO. Styles for HTML or EPUB documents are part of the staticDocuments property instead and will be integrated into the final output, but not interpreted.

Base type for all document type descriptors.

Provides all available DocumentTypes.

The base class for all Elements forming the document tree. Usually not extended directly, instead either Span or Block should be picked as the base type for new element types.

All node types have an optional id and zero or more associated styles serving as render hints.

A generic container of other elements. Provides means to traverse, select and rewrite children of this container.

Usually not mixed in directly, instead one of the sub-traits ListContainer, SpanContainer or BlockContainer should be used.

Represents an element that introduces new context that can be used in substitution references in any child element.

Usually used in directive implementations and not contributing to the rendered output itself.

Provides means to traverse and select elements of a document tree. This trait can get mixed in by any element node, not just the root Document class, therefore providing traversal for any kind of sub-tree, too.

A single configuration value to be merged with the top document config. This is particularly useful for directive implementations that need to contribute to the configuration of the document. During rendering these embedded configuration values will be discarded.

The root element of a document tree (originating from text markup) inside a template. Usually created by a template reference like ${cursor.currentDocument.content}.

A span of emphasized inline elements that may contain nested spans.

The format of enumerated list items.

An enumerated list that may contain nested lists.

Companion for creating BulletList instances.

Base trait for companions that create EnumList instances.

A single enum list item consisting of one or more block elements.

Represents the type of an ordered list.

Enumeration of supported enum types.

An external link, outside of the virtual tree of the current transformation.

Provides a fallback for elements the renderer does not know how to deal with.

A figure consists of an image, an optional caption, and an optional legend as the content property. The image property is of type Span as the image might be wrapped inside a link reference.

A footnote with resolved id and label that can be referred to by a FootnoteLink by id.

A footnote definition that needs to be resolved to a final footnote by a rewrite rule based on the label type.

Base type for all types of footnote labels.

A resolved link to a footnote.

A reference to a footnote with a matching label. Only part of the raw document tree and then removed by the rewrite rule that resolves link and image references.

A special type of paragraph that serves as a render hint. Some renderers simplify the rendering of block elements containing only a single paragraph and render the span content inline (e.g. a <li> tag without a nested <p> tag for the paragraph). Using this element as mandated by some edge cases in both the Markdown and reStructuredText markup definitions prevents this.

Generic base trait for all path abstractions in Laika.

The most commonly used sub-type is VirtualPath which is used to assign paths to trees and documents within a Laika transformation.

This trait is the only one within the Path API that is not sealed, to allow for implementations in other modules (e.g. FilePath in laika-io).

A global link that can point to any document within the input tree or to an external target.

A cell in the head part of the table.

A header element with a level, with 1 being the top level of the document.

Represents the decoration of a header. Concrete implementations need to be provided by the parser.

Represents a hidden element that will be ignored by renderers.

These kind of nodes usually provide information that will be extracted from the tree before AST transformations and renderers get applied.

Base trait for all supported icon types.

Represents a font-based icon, identified by its code point. Ideally theme authors provide constants for icons provided out of the box, so that the user does not have to look up or memorize the hex code point.

This avoids the indirection of common approaches where the rendered HTML contains an empty tag with a class which specifies the code point with a :before pseudo-class. This approach would currently not work well with Laika's PDF support which is not based on an interim HTML renderer.

A reference to an icon by key.

The icon must have been registered with the global configuration to be accessible by this node type. The indirection provided by this key allows to more easily swap entire icon sets without touching any code.

An icon defined in a style sheet, usually defining a glyph from an icon font. This icon type is not supported for PDF output, when using font icons with PDF use IconGlyph instead.

Factory and extractor for an Options instance with an id.

An inline image optional title, alt and size properties.

An image reference, the id pointing to the id of a LinkTarget. Only part of the raw document tree and then removed by the rewrite rule that resolves link and image references.

An image reference to content within the virtual input tree, the path pointing to the source path. Only part of the unresolved document tree and then removed by the rewrite rule that replace the source path with the final target path of the output document, resolving any relative path references in the process.

A span of program code. The content is a sequence of spans to support the integration of syntax highlighting systems. Without this support the sequence will only consist of a single Text element.

An SVG icon that will render inline, supported for all output formats.

A span representing inserted inline elements that may contain nested spans.

Points to the following block or span element, making it a target for links.

Represents a target within the virtual tree that can be referred to by links.

Represents an invalid element. Renderers can choose to either render the fallback or the runtime message or both, depending on the configuration of the transformer or renderer.

Groups a block that could not be successfully parsed with a runtime message. Renderers may then choose to just render the fallback, the message or both.

Groups a span that could not be successfully parsed with a runtime message. Renderers may then choose to just render the fallback, the message or both.

Encapsulates size information with a CSS-compatible length unit.

A base for builder of CSS-compatible length units.

An explicit hard line break.

The base type for all link elements.

In contrast to the reference type, it is only mixed in by elements representing resolved links that can be dealt with by renderers.

A link target pointing to another link target, acting like an alias.

An internal or external link target that can be referenced by id, usually only part of the raw document tree and then removed by the rewrite rule that resolves link and image references.

A reference to any kind of referencable object, e.g. a link definition or an internal target.

The reference can be local, in the same document, or anywhere else in the input tree, as long as the id is not ambiguous. Search for a matching target happens recursively, from the current document, to the current tree (directory) upwards to the root tree.

Companion for creating LinkIdReference instances.

A reference to content within the virtual input tree, the path pointing to the source path. Only part of the unresolved document tree and then removed by the rewrite rule that replace the source path with the final target path of the output document, which might differ in more than just the file suffix, depending on configuration.

The base type for all link targets. The id has to be unique for the whole document across all types of LinkTarget implementations.

A container of list items. Such a container is usually a Block itself.

The base type for all list items.

A span containing plain, unparsed text.

A literal block with unparsed text content.

A local link that always points to a target within the same document.

A context reference specifically for use in markup documents.

A filter for runtime messages that meet a specified minimum message level.

Signals the severity of a runtime message.

Enumeration of available message levels.

The library's internal parsers and AST transformation only use the Error level for recoverable issues encountered during transformations. All other levels are available for user code.

A navigatable object is anything that has an associated path.

The context of a navigation builder that can get passed down in recursive calls to the various types that have an asNavigationItem method.

Represents a navigation entry with an optional target link and optional child items. When the target link is not present, this item only serves as a navigation header for its children.

Represents a book navigation entry that links to content in the document tree.

The root node of a navigation structure

Empty Options implementation.

Explicit numeric label.

Options for customizable elements.

Companion for the Options trait.

An explicit hard page break.

A paragraph consisting of span elements.

Represents a parent selector and indicates whether it is an immediate parent or an ancestor anywhere in the hierarchy.

A literal block with parsed text content.

Represents an absolute path inside a virtual tree of documents.

Since this is the most commonly used path abstraction in Laika it received a conveniently short type name. The full, accurate name of this type would be AbsoluteVirtualPath.

Factory methods for creating path instances.

A reference to content within the virtual input tree, the path pointing to the source path. Only part of the unresolved document tree and then removed by the rewrite rule that replace the source path with the final target path of the output document, which might differ in more than just the file suffix, depending on configuration.

A quoted block consisting of a list of blocks that may contain other nested quoted blocks and an attribution which may be empty.

Raw content that is usually specific to the specified output formats. Can be used as both block and inline element. If supported by a parser it usually has to be explicitly enabled due to security concerns.

A raw link element without associated content (text or image).

One potential use case is to insert AST nodes that are only responsible for rendering a single tag attribute as opposed to rendering the full tag like all other link node types.

Raw links participate in path translation (e.g. for versioning) like all other link node types.

Companion for creating RawLink instances.

The base type for all reference elements.

A reference points to some other node in the document tree and needs to be resolved and replaced by a rewrite rule before rendering. Therefore none of the available renderers include logic for dealing with references.

Represents a target defined by a relative path; the absolute path of such a target needs to be resolved later in the context of the containing document and its path.

Indicates that the element a rewrite rule had been applied to should be removed from the document AST.

Indicates that the element a rewrite rule had been applied to should be replaced with this new value.

Represents a resolved internal target where both the absolute and relative path are known, the latter relative to the document that referred to the target.

The internalFormats property describes which of the output formats treat this as an internal link. For other formats the link gets translated to an external target based on the siteBaseURL setting. This might be useful for cases where some pages get rendered to a site, but not included in an e-book format like EPUB and PDF.

Indicates that the element a rewrite rule had been applied to should be kept in the document AST unchanged.

A generic container of child elements which can have rewrite rules applied to them in recursive tree rewriting.

Describes the action to be performed for a particular node in the document AST.

Represents one of the rewrite phases for document AST transformations.

These transformations are performed between parsing and rendering and deal with tasks like link validation, resolving substitution variables, directive processing or other tasks.

A phased model allows to separate rules that contribute new nodes to the AST from nodes that analyze the existing AST, e.g. for producing navigation artifacts. Running them all in one phase would create a chicken-and-egg scenario that would usually lead to undesired or unexpected results.

A set of rewrite rules describing a set of modifications to be applied to an AST of a document.

For reasons of type-safety the major element type blocks and spans (in markup documents) and template spans (in template documents) have their separate set of rules, as an element in a block position for example can usually only be replaced by another block and not by any other element type.

Factory methods and utilities for dealing with rewrite rules.

Converts Roman numerals to integers and vice versa. Since there never have been universally accepted rules for Roman numerals, the conversion functions do not apply strict error checking, so some unusual or illegal constructs may be supported, too. They do not prevent using the same symbol more than three times in a row for example.

Cursor for the root node of a document tree, providing access to all child cursors of this tree and allowing to trigger rewrite operations.

The root element of a document tree.

A single table row. In case some of the previous rows contain cells with a colspan greater than 1, this row may contain fewer cells than the number of columns in the table.

A horizontal rule.

Message generated by the parser, a directive or a rewrite rule.

They usually get inserted immediately after the block or span that caused the problem. It mixes in both the Span and Block trait so that it can appear in sequences of both types. By default messages are ignored by most renderers (apart from AST), but they can be explicitly activated for a particular level.

A message of level MessageLevel.Error will cause a transformation to fail, unless the user has configured with the renderErrors method to debug in a visual mode in which case the errors will get rendered in-place in the output.

An icon referencing an SVG shape defined in an external file or embedded SVG element. This icon type is not supported for PDF output, when using SVG icons with PDF use InlineSVGIcon instead.

Companion for creating SVGSymbolIcon instances.

A section of the document, consisting of a header and content in the form of a list of Block elements. Sections may be nested inside other sections, they are arranged in a hierarchy based on the level of their header element.

Captures information about a document section, without its content.

Represents a section number, usually used in header elements when autonumbering is applied.

The common base for absolute and relative paths that contain one or more path segments.

Represents a selection of choices (alternatives) that represent the same content in different ways, e.g. a code sample in Scala or Java or a build setup in sbt vs. Maven. In the final output these will usually be rendered in a way to allow for a convenient selection.

Options implementation for non-empty instances.

For creating new instances it is usually more convenient to use the various factory objects. Example for creating an instance with an id and two styles applied:

val options = Id("myId") + Styles("style1","style2")

Likewise it is also often more convenient to use the corresponding extractors for pattern matching.

The base type for all inline elements.

A container of other Span elements. Such a container may be a Block or a Span itself.

Common methods for simple span containers (without additional parameters).

An link element, with the span content representing the text (description) of the link.

Companion for creating SpanLink instances.

Represents a placeholder inline element that needs to be resolved in a rewrite step. Useful for elements that need access to the document, structure, title or configuration before being fully resolved.

Represents a span element that introduces new context that can be used in substitution references in any child element.

Usually used in directive implementations and not contributing to the rendered output itself.

A generic container element containing a list of spans. Can be used where a sequence of spans must be inserted in a place where a single element is required by the API. Usually renderers do not treat the container as a special element and render its children as s sub flow of the parent container. A span sequence is special in that in can be used as both a span and a block.

Represents the specificity of a style selector or predicate. This is modeled after the precedence rules of the CSS standard.

A pure descriptor for a static document, without the actual bytes. Used for evaluating links and other AST transformation phases.

Bullet format based on a simple string.

A span of strong inline elements that may contain nested spans.

Constants for style names wrapped in Options instances which are commonly used by Laika's core parsers and rewrite rules.

Represents a single style declaration.

Companion providing factory methods for the StyleDeclaration class.

Represents a set of one or more style declarations.

Companion providing factory methods for the StyleDeclaration class.

Represents a single predicate which is part of the selector for a style declaration.

Contains the available predicate types.

The available selector types represent a subset of the full CSS standard, picking those features which are reasonably suited in the context of the Laika document model. It includes type, class and id selectors, but no attribute selectors as most Laika tree elements primarily contain a sequence of children and not many other properties to match against.

It also supports the CSS syntax to declare selectors for child elements (e.g. Paragraph .intro) or immediate children (e.g. Paragraph > .intro).

Responsible for determining whether a style declaration should be applied to a target element, basing its decision on a set of predicates.

Factory and extractor for an Options instance with style names.

A table consisting of a head and a body part and optional caption and column specification.

Contains the body rows of a table.

A container of table elements.

A table element, like a row, cell or column.

Contains the header rows of a table.

Represents a target that can be referred to by links, either within the virtual tree or external.

An element that only gets rendered for a specific output format.

A context reference specifically for use in template documents.

A template document containing the element tree of a parsed template and its extracted configuration section (if present).

Wraps a generic element that otherwise could not be placed directly into a template document tree. Useful when custom tags which are placed inside a template produce non-template tree elements.

The root element of a template document tree.

Companion with a fallback instance for setups without a default template

Represents a template span element that introduces new context that can be used in substitution references in any child element.

Usually used in directive implementations and not contributing to the rendered output itself.

The base type for all inline elements that can be found in a template.

A container of other TemplateSpan elements.

Common methods for simple template span containers (without additional parameters).

A generic container element containing a list of template spans. Can be used where a sequence of spans must be inserted in a place where a single element is required by the API. Usually renderers do not treat the container as a special element and render its children as s sub flow of the parent container.

A simple string element, representing the parts of a template that are not detected as special markup constructs and treated as raw text.

A simple text element.

A container for plain text.

Base type for all document type descriptors for text input.

The (optional) title of the document.

Generic block element with a title. Often combined with the the styles attribute of the options parameter to provide additional render hints.

Generically builds a tree structure out of a flat sequence of elements with a Path property that signifies the position in the tree. Essentially factors recursion out of the tree building process.

A titled, positional element in the document tree.

Cursor for an entire document tree, providing access to all child cursors of this tree and allowing to trigger rewrite operations.

The position of an element within a document tree.

The structure of a document tree.

Represents an element that needs to be resolved in an AST transformation step.

Passing documents that still contain elements of this kind to a renderer will usually be treated as errors.

A temporary structure usually not exposed to user code. It holds a document with an empty Config instance and its actual config (obtained from a header section if present) in unresolved form, as it needs to be resolved based on a fallback configuration later.

The abstract base for absolute and relative paths within Laika's virtual path abstraction.

A path in Laika is always virtual and not pointing to a path in the file system, even if the data was obtained by scanning a directory. This is because in Laika transformation input can come from different sources, e.g. from two different directories merged into a single virtual tree in memory with some additional documents added programmatically without any file system reference.

A wrapper for two result values.

Specifies a custom render function that may override the rendered output for one or more node types. For elements this function is not defined the renderer will fall back to the default renderer (or the next custom renderer, in case there are multiple).

Specifies how a particular element, document or document tree should be rewritten.

If the rule is not defined for a specific element or the rule returns a Retain action as a result the old element remains in the tree unchanged.

If it returns Remove then the node gets removed from the ast, if it returns Replace with a new element it will replace the old one.