Lmml.Document (Lmml v0.1.0)

View Source

A parsed lmml narrative: the Md-produced AST plus the flat list of Lmml.Embeds discovered anywhere within it (however deeply nested -- inside a list item, a blockquote, an emphasis span, and so on).

This is the file-form-independent half of the data model: a Document knows exactly what embeds a narrative mentions, but nothing about where an external one's bytes actually live -- that's Lmml.Bundle's job, since only the bundle knows whether it's backed by a bare .lmml text file (nothing to resolve @refs against) or a .lmmlz zip archive (which has real entries to look up).

Summary

Types

ast()
t()

Functions

embed(document, name)

Looks up the first embed named name.

embed_names(document)

Names of every embed mentioned in the document, in first-seen order, deduplicated.

external_embeds(document)

Embeds whose content is external (a @name.ext reference needing a zip entry to resolve).

inline_embeds(document)

Embeds whose content is carried inline (a @@@name.ext ... @@@ block).

parse(narrative)

Parses raw narrative text into a Document, extracting every @name.ext reference and @@@name.ext ... @@@ inline embed found anywhere in the resulting AST.

parse!(narrative)

Same as parse/1, but raises on failure.

Types

ast()

@type ast() :: [Md.Listener.branch()]

t()

@type t() :: %Lmml.Document{ast: ast(), embeds: [Lmml.Embed.t()]}

Functions

embed(document, name)

@spec embed(t(), String.t()) :: {:ok, Lmml.Embed.t()} | {:error, :not_found}

Looks up the first embed named name.

A narrative may legitimately mention the same external reference more than once (e.g. @image.png appearing twice just means "this image, again"); this always returns the first occurrence. Detecting inline embeds that share a name but disagree on content is Lmml.Bundle.validate/1's job, not this function's.

embed_names(document)

@spec embed_names(t()) :: [String.t()]

Names of every embed mentioned in the document, in first-seen order, deduplicated.

external_embeds(document)

@spec external_embeds(t()) :: [Lmml.Embed.t()]

Embeds whose content is external (a @name.ext reference needing a zip entry to resolve).

inline_embeds(document)

@spec inline_embeds(t()) :: [Lmml.Embed.t()]

Embeds whose content is carried inline (a @@@name.ext ... @@@ block).

parse(narrative)

@spec parse(binary()) :: {:ok, t()} | {:error, term()}

Parses raw narrative text into a Document, extracting every @name.ext reference and @@@name.ext ... @@@ inline embed found anywhere in the resulting AST.

Never fails on malformed/unexpected input in the way a strict grammar might: lmml is a superset of Markdown, so anything Md.Parser.Default itself can parse, this parses too (see Lmml.Narrative.Parser).

The @@@name ... @@@ block is declared with escape: false in Lmml.Narrative.Syntax (Md >= 0.12.2), so an :lmml_embed node's content already matches the literal bytes written between the fences verbatim -- no post-processing needed here.

parse!(narrative)

@spec parse!(binary()) :: t()

Same as parse/1, but raises on failure.