Lmml.Embed (lmml v0.2.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

content(embed)

The embed's actual content, unwrapped from its content/0 tuple: the inline binary for an inline embed, or the zip entry name an external embed resolves against.

entry_name(embed)

The zip entry name an external embed resolves against, or nil for an inline embed (whose bytes travel with the narrative itself).

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

content(embed)

@spec content(t()) :: binary()

The embed's actual content, unwrapped from its content/0 tuple: the inline binary for an inline embed, or the zip entry name an external embed resolves against.

This is a convenience accessor so callers need not case over the {:inline, binary} | {:external, String.t()} tuple at every site.

entry_name(embed)

@spec entry_name(t()) :: String.t() | nil

The zip entry name an external embed resolves against, or nil for an inline embed (whose bytes travel with the narrative itself).

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.