View Source Md.Parser behaviour (md v0.10.6)

Interface to implement for the custopm parsers.

Custom parsers might be used in syntax declaration when the generic functionality is not enough.

Let’s consider one needs a specific handling of links with titles.

The generic engine does not support it, so one would need to implement a custom parser and instruct Md.Parser to use it with:

# config/prod.exs

config :md, syntax: %{
  custom: [
    {"![", {MyApp.Parsers.Img, %{}}},
    ...
  ]
}

Once the original parser would meet the "![" binary, it’d call MyApp.Parsers.Img.parse/2. The latter must proceed until the tag is closed and return the remainder and the updated state as a tuple.

Custom parsers implementation examples might be found here.

Summary

Types

parsing_stage()

The type to be used in all the intermediate states of parsing.

Callbacks

parse(binary, state)

Takes a not parsed yet input and the state, returns the updated remainder and state.

Functions

generate(input, options \\ [])

The main function transforming the MD input to XML output.

generate(input, parser, options) deprecated

Types

parsing_stage()

@type parsing_stage() :: {binary(), Md.Listener.state()}

The type to be used in all the intermediate states of parsing.

The first element iof the tuple is the continuation (not parsed yet input,) and the latter is the current state.

Callbacks

parse(binary, state)

@callback parse(binary(), Md.Listener.state()) :: parsing_stage()

Takes a not parsed yet input and the state, returns the updated remainder and state.

Functions

generate(input, options \\ [])

@spec generate(
  binary() | Md.Listener.state(),
  keyword()
) :: binary() | {binary(), any()}

The main function transforming the MD input to XML output.

options are passed to XmlBuilder.generate/2 as is, save for the special two special options, parser: and walker:.

parser: option which is a module implementing Parser behaviour, is telling what parser to use for parsing.

walker: option which might be a function of arity 2, or a tuple {:pre | :post, fun} where fun is a function of arity 1 or 2.

If passed, XmlBuilder.{pre,post}walk/{2,3} is being called before generation.

If walker: was not passed, or a nil value was returned from the accumulator, this function returns the binary XML as is, otherwise it returns a tuple {XML, accumulator} where accumulator is what has been returned from underlying calls to XmlBuilder.traverse/4.

generate(input, parser, options)

This function is deprecated. Use generate/2 instead passing `parser: parser` as option.

@spec generate(binary() | Md.Listener.state(), module(), keyword()) ::
  binary() | {binary(), any()}