Magma.DocumentStruct (Magma v0.3.2)

Recursive section-based representation of a Markdown document for transclusion resolution.

Parses Markdown via Pandoc (through Panpipe) into a struct consisting of:

a prologue (header-less content before the first section)
a list of level-1 sections (Magma.DocumentStruct.Section), each containing nested subsections recursively

Most section-level operations are implemented in Magma.DocumentStruct.Section and delegated through this module.

Summary

Types

compatible()

t()

Functions

fetch(document_struct, title)

Fetches the section with the given title and returns it in an ok tuple.

main_section(map)

Returns the first section.

parse(content)

Parses the given content into a Magma.DocumentStruct.

remove_comments(document_struct)

Removes all comment blocks from the given document_struct.

resolve_transclusions(document_struct)

Processes and resolves transclusions within the given document_struct.

section_by_title(map, title)

Fetches the first section with the given title.

set_level(document_struct, level)

Sets the header level for all sections within the document.

title(document_struct)

Extracts and returns the title of the main_section/1.

to_markdown(document)

Converts the given document_struct back into a Markdown string.

Types

compatible()

@type compatible() :: %{
  prologue: [Panpipe.AST.Node.t()],
  sections: [Magma.DocumentStruct.Section.t()]
}

t()

@type t() :: %Magma.DocumentStruct{
  prologue: [Panpipe.AST.Node.t()],
  sections: [Magma.DocumentStruct.Section.t()]
}

Functions

fetch(document_struct, title)

Fetches the section with the given title and returns it in an ok tuple.

If no section with title exists, it returns :error.

This implements Access.fetch/2 function, so that the document_struct[title] syntax and the Kernel macros for accessing nested data structures like get_in/2 are supported.

This function only searches sections directly under the given section. For a recursive search, use section_by_title/2.

main_section(map)

@spec main_section(t() | compatible()) :: Magma.DocumentStruct.Section.t() | nil

Returns the first section.

Assuming that the first section with header level 1 is the main section.

parse(content)

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

Parses the given content into a Magma.DocumentStruct.

remove_comments(document_struct)

@spec remove_comments(t()) :: t()

Removes all comment blocks from the given document_struct.

See Magma.DocumentStruct.Section.remove_comments/1 which does the same on a section level.

resolve_transclusions(document_struct)

@spec resolve_transclusions(t()) :: t()

Processes and resolves transclusions within the given document_struct.

See Magma.DocumentStruct.Section.resolve_transclusions/1 which does the same on a section level.

section_by_title(map, title)

@spec section_by_title(t() | compatible(), binary()) ::
  Magma.DocumentStruct.Section.t() | nil

Fetches the first section with the given title.

Unlike fetch/2, this function performs a recursive search throughout the document to find the desired section.

set_level(document_struct, level)

@spec set_level(t(), non_neg_integer()) :: t()

Sets the header level for all sections within the document.

See Magma.DocumentStruct.Section.set_level/2 which does the same on a section level.

title(document_struct)

@spec title(t() | compatible()) :: binary() | nil

Extracts and returns the title of the main_section/1.

to_markdown(document)

@spec to_markdown(t() | compatible()) :: binary()

Converts the given document_struct back into a Markdown string.