View Source Magma.Document behaviour (Magma v0.2.0)

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 (except Magma.Concept). 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.

from(arg1)

Fetches a document from a related document.

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()

recreate(document)

Creates the file for document, overwriting the existing one.

recreate!(document)

Creates the file for document, overwriting the existing one.

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.Concept.t()
  | Magma.Prompt.t()
  | Magma.Artefact.Prompt.t()
  | Magma.PromptResult.t()
  | Magma.Artefact.Version.t()
  | Magma.Text.Preview.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.

from(arg1)

@callback from(t() | {Magma.Concept.t(), Magma.Artefact.t()}) :: t() | binary()

Fetches a document from a related document.

For example, Concept.from(prompt) will return the Magma.Concept document from the given prompt.

Implementation should implement clauses for all document types for which it is possible.

For Magma.Artefact-specific documents from a Magma.Concept, the concept must be given in a {Concept.t(), Artefact.t()} tuple.

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()

recreate(document)

Creates the file for document, overwriting the existing one.

This function is used by the Mix.Tasks.Magma.Prompt.Update Mix task.

recreate!(document)

Creates the file for document, overwriting the existing one.

This function is used by the Mix.Tasks.Magma.Prompt.Update Mix task.

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("Concept")
Magma.Concept

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

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.Concept)
"Concept"

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

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

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

iex> Magma.Document.type_name(Magma.Artefact.Version)
"Artefact.Version"

iex> Magma.Document.type_name(Magma.Text.Preview)
"Text.Preview"

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