laika-core
API
Generated with
laika-core/laika/laika.directive/Templates

Templates

laika.directive.Templates$
object Templates extends BuilderContext[TemplateSpan]

The API for declaring directives that can be used in templates.

Attributes

Graph
Supertypes
class Object
trait Matchable
class Any
Self type
Templates.type

Members list

Type members

Classlikes

case class DirectiveInstance(directive: Option[Directive], parsedResult: ParsedDirective, parser: RecursiveSpanParsers, source: SourceFragment, options: Options) extends SpanResolver, TemplateSpan

Attributes

Supertypes
trait TemplateSpan
trait SpanResolver
trait Unresolved
trait Span
class Element
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
case class SeparatorInstance(parsedResult: ParsedDirective, source: SourceFragment, options: Options) extends TemplateSpan, SpanResolver

Attributes

Supertypes
trait SpanResolver
trait Unresolved
trait TemplateSpan
trait Span
class Element
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all

Inherited classlikes

object BodyContent

Attributes

Inherited from:
BuilderContext
Supertypes
trait Sum
trait Mirror
class Object
trait Matchable
class Any
sealed trait BodyContent

The content of a directive part, either an attribute or the body.

The content of a directive part, either an attribute or the body.

Attributes

Inherited from:
BuilderContext
Supertypes
class Object
trait Matchable
class Any
Known subtypes
class Parsed
class Source
trait Combinators

Provides combinators to describe the expected structure of a specific directive.

Provides combinators to describe the expected structure of a specific directive.

Attributes

Inherited from:
BuilderContext
Supertypes
class Object
trait Matchable
class Any
Known subtypes
object dsl.type
class Directive

Represents a directive, its name and its (combined) parts.

Represents a directive, its name and its (combined) parts.

Attributes

Inherited from:
BuilderContext
Supertypes
class Object
trait Matchable
class Any
case class DirectiveContent(attributes: Config, body: Option[BodyContent])

The content of a parsed directive with the HOCON attributes captured in a Config instance.

The content of a parsed directive with the HOCON attributes captured in a Config instance.

Attributes

Inherited from:
BuilderContext
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
case class DirectiveContext(content: DirectiveContent, parser: Parser, cursor: DocumentCursor, source: SourceFragment)

The context of a directive during execution.

The context of a directive during execution.

Attributes

Inherited from:
BuilderContext
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
abstract class DirectivePart[+A] extends DirectiveContext => Result[A]

Represents a single part (attribute or body) of a directive or a combination of multiple parts.

Represents a single part (attribute or body) of a directive or a combination of multiple parts.

Attributes

Inherited from:
BuilderContext
Supertypes
trait DirectiveContext => Result[A]
class Object
trait Matchable
class Any
Known subtypes
class AttributePart[T]
object DirectivePart

Attributes

Inherited from:
BuilderContext
Supertypes
class Object
trait Matchable
class Any
case class Multipart[T](mainBody: Seq[E], children: Seq[T])

The content of a body element divided by separator directives.

The content of a body element divided by separator directives.

Attributes

Inherited from:
BuilderContext
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
class SeparatorDirective[+T]

Represents a separator directive, its name and its (combined) parts. It also allows to specify requirements for the minimum and maximum number of occurrences allowed for this directive. The default is unbounded, with 0 or more instances allowed.

Represents a separator directive, its name and its (combined) parts. It also allows to specify requirements for the minimum and maximum number of occurrences allowed for this directive. The default is unbounded, with 0 or more instances allowed.

Attributes

Inherited from:
BuilderContext
Supertypes
class Object
trait Matchable
class Any
object dsl extends Combinators

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 attributes 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 attributes, followed 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.

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[Block], options: Options = NoOpt)
                                                    extends Block with BlockContainer[Note]

object MyDirectives extends DirectiveRegistry {
  val blockDirectives = Seq(
    Blocks.create("note") {
      (defaultAttribute.as[String], parsedBody).mapN(Note(_,_))
    }
  )
  val spanDirectives = Seq()
}

val transformer = Transformer.from(Markdown).to(HTML).using(MyDirectives)

The defaultAttribute combinator specifies a required attribute of type String and without a name. The parsedBody combinator specifies standard block content (any block elements that are supported in normal markup, too) which results in a parsed value of type Seq[Block].

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 block directive the final result has to be of type Block 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 of attributes is required it can be performed with the as[T] method:

case class Message (severity: Int,
                    content: Seq[Block],
                    options: Options = NoOpt) extends Block
                                              with BlockContainer[Message]

val blockDirectives = Seq(
  Blocks.create("message") {
    (defaultAttribute.as[Int], blockContent).mapN(Message(_,_))
  }
)

In the example above the built-in Int decoder gets passed to the defaultAttribute combinator, but you can easily create and use your own instances of ConfigDecoder[T].

If required attributes or bodies are missing or any type conversion fails, an instance of InvalidBlock containing the error 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.

Finally attributes 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") {
    (defaultAttribute.as[Int].optional, blockContent).mapN {
      (severity, content) => Message(severity.getOrElse(0), content)
    }
  }
)

The attribute may be missing, but if it is present it has to pass the specified validator.

Attributes

Inherited from:
BuilderContext
Supertypes
trait Combinators
class Object
trait Matchable
class Any

Types

type Parser = RecursiveSpanParsers

The parser API in case a directive function needs to manually parse one of the directive parts.

The parser API in case a directive function needs to manually parse one of the directive parts.

Attributes

Inherited types

type Result[+A] = Either[Seq[String], A]

Attributes

Inherited from:
BuilderContext

Value members

Inherited methods

def create(name: String)(part: DirectivePart[TemplateSpan]): Directive

Creates a new directive with the specified name and part specification.

Creates a new directive with the specified name and part specification.

Attributes

Inherited from:
BuilderContext
def eval(name: String)(part: DirectivePart[Either[String, TemplateSpan]]): Directive

Creates a new directive with the specified name and part specification.

Creates a new directive with the specified name and part specification.

When the result of the directive is a Left, the directive will produce an invalid AST element with the string as the error message.

Attributes

Inherited from:
BuilderContext
def separator[T](name: String, min: Int, max: Int)(part: DirectivePart[T]): SeparatorDirective[T]

Creates a new separator directive with the specified name and part specification.

Creates a new separator directive with the specified name and part specification.

Attributes

Inherited from:
BuilderContext
def toMap(directives: Iterable[Directive]): Map[String, Directive]

Turns a collection of directives into a map, using the name of the directive as the key.

Turns a collection of directives into a map, using the name of the directive as the key.

Attributes

Inherited from:
BuilderContext
Generated with