NAME

Statocles::Store - The source for data documents and files

DESCRIPTION

A Statocles::Store reads and writes documents and files (mostly pages).

This class also handles the parsing and inflating of "document objects".

Frontmatter Document Format

Documents are formatted with a YAML document on top, and Markdown content on the bottom, like so:

    ---
    title: This is a title
    author: preaction
    ---
    # This is the markdown content
    
    This is a paragraph

ATTRIBUTES

path

The path to the directory containing the documents.

document_extensions

An array of file extensions that should be considered documents. Defaults to "markdown" and "md".

documents

All the documents currently read by this store.

METHODS

clear

    $store->clear;

Clear the cached documents in this Store.

read_documents

    my $docs = $store->read_documents;

Read the directory path and create the document objects inside. Returns an arrayref of document objects.

read_document

    my $doc = $store->read_document( $path )

Read a single document in Markdown with optional YAML or JSON frontmatter.

parse_frontmatter

    my %doc_attrs = $store->parse_frontmatter( $from, $content )

Parse a document with YAML frontmatter. $from is a string identifying where the content comes from (a path or other identifier). $content is the content to parse for frontmatter.

write_document

    $store->write_document( $path, $doc );

Write a document to the store at the given store path.

The document is written in Frontmatter format.

is_document

    my $bool = $store->is_document( $path );

Returns true if the path looks like a document path (matches the "document_extensions").

read_file

    my $content = $store->read_file( $path )

Read the file from the given path.

has_file

    my $bool = $store->has_file( $path )

Returns true if a file exists with the given path.

NOTE: This should not be used to check for directories, as not all stores have directories.

files

    my $iter = $store->files

Returns an iterator which iterates over all files in the store, regardless of type of file. The iterator returns a Path::Tiny object or undef if no files remain. It is used by find_files.

find_files

    my $iter = $store->find_files( %opt )
    while ( my $path = $iter->() ) {
        # ...
    }

Returns an iterator that, when called, produces a single path suitable to be passed to read_file.

Available options are:

    include_documents      - If true, will include files that look like documents.
                             Defaults to false.

It obtains its list of files from files.

open_file

    my $fh = $store->open_file( $path )

Open the file with the given path. Returns a filehandle.

The filehandle opened is using raw bytes, not UTF-8 characters.

write_file

    $store->write_file( $path, $content );

Write the given content to the given path. This is mostly used to write out page objects.

content may be a simple string or a filehandle. If given a string, will write the string using UTF-8 characters. If given a filehandle, will write out the raw bytes read from it with no special encoding.

remove

    $store->remove( $path )

Remove the given path from the store. If the path is a directory, the entire directory is removed.