View Source Magma.DocumentStruct (Magma v0.2.0)

Provides an abstract representation of a Markdown document structured based on the Pandoc AST.

The Magma.DocumentStruct module provides an Elixir struct for representing the contents of a Markdown document as an Abstract Syntax Tree (AST) based on the Pandoc AST. The struct is designed to access the individual sections including their subsections and facilitate the transclusion resolution feature, which is essential for the prompt generation in Magma.

The Magma.DocumentStruct struct consists of a prologue, which is the header-less text before the first section, and all sections of level 1 (which in turn consist of sections of level 2 and so on). The core functionalities related to sections are implemented in the Magma.DocumentStruct.Section module. The Magma.DocumentStruct acts as a wrapper around this recursive section structure and delegates most of its functions to the said 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()]
  }
  | Magma.Concept.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.