Lmml.Embed (Lmml v0.1.0)

View Source

The one abstraction behind both lmml embedding syntaxes.

@name.ext (a reference) and @@@name.ext ... @@@ (an inline embed) are two different textual renderings of the exact same semantic idea: "this document contains a named embedded entity called name.ext." They differ only in where the entity's content actually lives:

  • {:inline, binary} -- the content is the embed's own text, captured directly from a @@@name.ext ... @@@ block. Works in any lmml document, including a bare .lmml text file with no other files.
  • {:external, entry_name} -- the content lives elsewhere, referenced by @entry_name and resolved against a .lmmlz zip archive's entries. Meaningless (unresolvable) outside a zip container.

Lmml.Pack.pack/2 and Lmml.Pack.inline/2 mechanically convert one form into the other; nothing about the embed's meaning changes.

Summary

Types

content()

Where an embed's actual bytes live.

t()

Functions

external(name, entry_name \\ nil)

Builds an external embed (content resolved from a zip entry at read time).

external?(embed)

True when the embed's content must be resolved against an external (zip) entry.

inline(name, content)

Builds an inline embed (content captured directly in the narrative).

inline?(embed)

True when the embed's content is carried inline in the narrative itself.

Types

content()

@type content() :: {:inline, binary()} | {:external, String.t()}

Where an embed's actual bytes live.

t()

@type t() :: %Lmml.Embed{content: content(), name: String.t()}

Functions

external(name, entry_name \\ nil)

@spec external(String.t(), String.t() | nil) :: t()

Builds an external embed (content resolved from a zip entry at read time).

entry_name defaults to name itself when omitted or nil, so external("a.png") and external("a.png", nil) both resolve against a zip entry literally named "a.png".

external?(embed)

@spec external?(t()) :: boolean()

True when the embed's content must be resolved against an external (zip) entry.

inline(name, content)

@spec inline(String.t(), binary()) :: t()

Builds an inline embed (content captured directly in the narrative).

inline?(embed)

@spec inline?(t()) :: boolean()

True when the embed's content is carried inline in the narrative itself.