BuilderContext
Related Doc:
package directive
Provides various combinators to describe the expected format of a specific directive.
Provides various converter functions that can be used with the directive combinators to convert the string value obtained from a directive attribute or body.
Represents a directive, its name and its (combined) parts.
The context of a directive during execution.
Represents a single part (attribute or body) of a directive or a combination of multiple parts.
The parser API in case a directive function needs to manually parse one of the directive parts.
Type class required for using the generic Builders API with directives.
Creates a new directive with the specified name and part specification.
Provides the basic building blocks for defining directives, Laika's extension mechanism for creating custom tags for both, templates or text markup.
Provides the basic building blocks for defining directives, Laika's extension mechanism for creating custom tags for both, templates or text markup.
This object is used as part of the concrete objects Blocks.dsl,
Spans.dsl and Templates.dsl respectively.
It contains several simple combinators that allow to specify the expected attributes and body elements of the directive, optional converters for these elements and the function responsible for producing the final node element.
In contrast to custom tag hooks in other template engines the result of a directive is not a string. In the same way as markup documents get transformed into a tree of elements before rendering, a directive produces a node of the tree to render. As a result, the directive can be used independent from the output format.
Entry points of the API are the Templates, Blocks and Spans objects for the
three different directive types.
A directive may consist of any combination of arguments, fields and body elements:
@:myDirective arg1=value1 arg2=value2: {
This is the body of the directive. It may consist of any standard or custom
block-level and inline markup.
} In the example above arg1 and arg2 are arguments, ollowed by a body element
enclosed in curly braces.
For each of these directive elements, the API offers a combinator to specify whether the element is required or optional, and an optional function to convert or validate the parsed value.
Consider the following simple example of a directive with just one argument and a body, for specifying a specially formatted inline note:
@:note This is the title: { This is the body of the note. }The implementation of this directive could look like this:
case class Note (title: String, content: Seq[Span], options: Options = NoOpt) extends Span with SpanContainer[Note] object MyDirectives extends DirectiveRegistry { val spanDirectives = Seq( Spans.create("note") { (attribute(Default) ~ body(Default)) (Note(_,_)) } ) val blockDirectives = Seq() } Transform from Markdown to HTML using MyDirectives fromFile "hello.md" toFile "hello.html"
The attribute(Default) combinator specifies a required attribue of type String (since no conversion
function was supplied) and without a name (indicated by passing the Default object instead of a string
name). The body combinator specifies standard inline content (any span
elements that are supported in normal inline markup, too) which results in a parsed value of type
Seq[Span].
Finally you need to provide a function that accepts the results of the specified
directive elements as parameters (of the corresponding type). Here we created a case class
with a matching signature so can pass it directly as the target function. For a span directive
the final result has to be of type Span which the Note class satisfies. Finally the directive
gets registered with the Markdown parser. It can be registered for a reStructuredText parser,
too, without any changes.
If any conversion or validation is required on the individual parts of the directive they can be passed to the corresponding function:
case class Message (severity: Int, content: Seq[Block], options: Options = NoOpt) extends Block with BlockContainer[Message] val blockDirectives = Seq( Blocks.create("message") { (attribute(Default, positiveInt) ~ blockContent) (Message(_,_)) } )
In the example above the built-in positiveInt converter gets passed to the attribute
combinator, but you can easily create and use your own functions.
The function has to accept a string argument and return a Result[T].
The Failure subtype of Result will be interpreted as an error by the interpreter with the string being used as the message
and an instance of InvalidBlock containing the validator message and the raw source of the directive
will be inserted into the document tree. In this case the final function (Message) will never be invoked.
The Success subtype of Result will be used as an argument to the final function. Note how the case class now expects
an Int as the first parameter.
Finally attributes and body elements can also be optional. In case they are missing, the directive is still
considered valid and None will be passed to your function:
case class Message (severity: Int, content: Seq[Block], options: Options = NoOpt) extends Block with BlockContainer[Message] val blockDirectives = Seq( Blocks.create("message") { (attribute(Default, positiveInt).optional ~ blockContent) (Message(_,_)) } )
The attribute may be missing, but if it is present it has to pass the specified validator.
Turns a collection of directives into a map, using the name of the directive as the key.
Provides the basic building blocks for Laika's Directive API. This trait is not used directly, but instead its three subtraits
Blocks,SpansandTemplates, which represent the concrete implementations for the three directive types.