Magma.Document behaviour (Magma v0.3.2)

A behavior for the different kinds of document types in Magma.

Besides the callback definition, it provides shared fields and logic between all document types. Each document type defines additional fields for its specific tasks and a path scheme that determines where instances of this type are stored.

Note, that in general the content under the YAML frontmatter of a document is not further interpreted. Magma.DocumentStruct allows to get the AST of a Markdown document.

Summary

Types

t()

type()

Callbacks

build_path(t)

Builds the path of a new document during its creation.

load_document(t)

Document type specific logic when loading a document.

render_front_matter(t)

Renders the document type specific fields as YAML front matter lines.

title(t)

The title of the document used in the initial top-level header of a document.

Functions

fields()

save(document, opts \\ [])

Saves the changes on a document.

type(string)

Returns the document type module for the given string.

type?(module)

Returns if the given module is a document type module.

type_name(type)

Returns the document type name for the given document.

Types

t()

@type t() :: Magma.Prompt.t() | Magma.PromptResult.t() | Magma.Session.t()

type()

@type type() :: module()

Callbacks

build_path(t)

@callback build_path(t()) :: {:ok, Path.t()}

Builds the path of a new document during its creation.

The function will receive a struct created with the respective new function, which should have initialized all parts required for this path building step.

load_document(t)

@callback load_document(t()) :: {:ok, t()} | {:error, any()}

Document type specific logic when loading a document.

Usually the document type specific fields of the YAML front matter of the document are extracted and interpreted here.

render_front_matter(t)

@callback render_front_matter(t()) :: binary() | nil

Renders the document type specific fields as YAML front matter lines.

title(t)

@callback title(t()) :: binary()

The title of the document used in the initial top-level header of a document.

Functions

fields()

save(document, opts \\ [])

Saves the changes on a document.

type(string)

Returns the document type module for the given string.

Example

iex> Magma.Document.type("Prompt")
Magma.Prompt

iex> Magma.Document.type("Session")
Magma.Session

iex> Magma.Document.type("PromptResult")
Magma.PromptResult

iex> Magma.Document.type("Config.System")
Magma.Config.System

iex> Magma.Document.type("Vault")
nil

iex> Magma.Document.type("NonExisting")
nil

type?(module)

Returns if the given module is a document type module.

type_name(type)

Returns the document type name for the given document.

Example

iex> Magma.Document.type_name(Magma.Prompt)
"Prompt"

iex> Magma.Document.type_name(Magma.PromptResult)
"PromptResult"

iex> Magma.Document.type_name(Magma.Session)
"Session"

iex> Magma.Document.type_name(Magma.Vault)
** (RuntimeError) Invalid Magma.Document type: Magma.Vault

iex> Magma.Document.type_name(NonExisting)
** (RuntimeError) Invalid Magma.Document type: NonExisting