A specialized Obsidian vault with directories for the Magma-specific documents.
The Magma.Vault module serves as a representation and utility module for a Magma vault - a specialized Obsidian vault that houses Magma documents, which are special kinds of Markdown documents with specific paths and purposes. The vault itself can be stored by default in the magma/ directory of a project but can be reconfigured as needed (see path/0).
Main functions of this module include:
- Retrieving paths within the vault, like the base path, template paths, etc.
- Creating and initializing a new vault (
create/2). - Indexing documents by name (
index/1). - Fetching details of documents, such as their path (
document_path/1) or type (document_type/1).
Summary
Functions
Creates and initializes a new vault.
Returns the Vault path for the custom prompt template.
Return the path of an existing document.
Determines the type of the document with the given name_or_path.
Indexes the provided document by its name.
Returns the application configured path to the vault.
Constructs a complete path by joining the specified segments to the root vault path/0.
Returns the Vault path for the Session continuation template.
Returns the Vault path for the Session response files directory.
Generates a timestamped response file path for a session.
Returns the Vault path for the Session response prompt EEx template.
Returns the Vault path for the Session template.
Returns the Vault path of the directory for templates.
Constructs a complete template path by joining the specified segments to the template_path/0.
Functions
@spec create( base_vault :: Magma.Vault.BaseVault.theme() | Path.t() | nil, keyword() ) :: :ok | {:error, any()}
Creates and initializes a new vault.
The base_vault specifies the Magma.Vault.BaseVault to be used for
initializing the new Magma vault. It can be specified with any of arguments
accepted by Magma.Vault.BaseVault.path/1.
Available opts:
:force(default:false): allow to force creation even if a vault already exists
Returns :ok if the vault is successfully created or an error tuple if
there's an error during the vault creation process.
@spec custom_prompt_template_path() :: Path.t()
Returns the Vault path for the custom prompt template.
Return the path of an existing document.
When given a path it checks if there actually exists a document at this path. When given a document name (without file extension) it trys to fetch the path from the index.
Returns nil, if no file exists at the given path or no document with the
given name is indexed.
@spec document_type(binary() | Path.t()) :: {:ok, Magma.Document.type()} | {:error, any()}
Determines the type of the document with the given name_or_path.
The type is determined by the magma_type property within the document's
YAML front matter.
Indexes the provided document by its name.
This function indexes a given Magma.Document to enable fast access to it by
its name in the document_path/1 function or the load/1 functions of
Magma.Documents.
@spec path() :: Path.t()
Returns the application configured path to the vault.
Unless specified otherwise, the path is the magma directory
inside the project directory.
It can be changed with in your config.exs file like this:
config :magma,
dir: "custom_dir"Note, that this configuration should be environment-independent. Unless you're working on Magma itself, you don't want a test-specific vault, since the vault collects knowledge about your code in its entirety.
Constructs a complete path by joining the specified segments to the root vault path/0.
Most of the time one of the more document type-specific functions is more suitable.
Example
Magma.Vault.path("directory")
# returns: "/path/to/project/magma/directory"
Magma.Vault.path(["some", "directory"])
# returns: "/path/to/project/magma/some/directory"@spec session_continuation_template_path() :: Path.t()
Returns the Vault path for the Session continuation template.
@spec session_response_directory() :: Path.t()
Returns the Vault path for the Session response files directory.
@spec session_response_file_path(String.t(), DateTime.t() | binary()) :: Path.t()
Generates a timestamped response file path for a session.
@spec session_response_prompt_template_path() :: Path.t()
Returns the Vault path for the Session response prompt EEx template.
@spec session_template_path() :: Path.t()
Returns the Vault path for the Session template.
@spec template_path() :: Path.t()
Returns the Vault path of the directory for templates.
Constructs a complete template path by joining the specified segments to the template_path/0.
Example
Magma.Vault.template_path("some_template.md")
# returns: "/path/to/project/magma/templates/some_template.md"