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


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



The path to the directory containing the documents.


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


All the documents currently read by this store.




Clear the cached documents in this Store.


    my $docs = $store->read_documents;

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


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

Read a single document in Markdown with optional YAML or JSON 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.


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

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

The document is written in Frontmatter format.


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

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


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

Read the file from the given path.


    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.


    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.


    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.


    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.


    $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.


    $store->remove( $path )

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