NAME

PFT::Header - Header for PFT content textfiles

SYNOPSIS

    use PFT::Header;

    my $hdr = PFT::Header->new(
        title => $title,        # mandatory (conditions apply)
        slug => $slug,          # optional short identifier
        date => $date,          # optional (conditions apply) PFT::Date
        author => $author,      # optional
        tags => $tags,          # list of decoded strins, defaults to []
        opts => $opts,          # ignored by internals, defaults to {}
    );

    my $hdr = PFT::Header->load(\*STDIN);

    my $hdr = PFT::Header->load('/path/to/file');

DESCRIPTION

A header is a chunk of meta-information describing content properties.

It is used in a PFT::Tree::Content structure as index for retrieving the content on the filesystem. Every textual content (i.e. PFT::Content::Entry) stores a textual representation of an header in the beginning of the file.

Structure

Each content has a title, an optional author, an optional list of tags in form of strings, an optional hash opts containing other options.

Textual representation

The textual representation of a header starts with a valid YAML document (including the leading '---' line and ends with another '---' line).

Construction

The header can be constructed in three ways, corresponding to the three forms in the SYNOPSIS.

The first form is constructed in code. The title field is mandatory unless there is a date field, and the date represents a month (i.e. lacks the day field). This property is enforced by the constructor.

The second and third forms are equivalent, and they differ in the source from which a header is loaded (a stream or a file path, respectively).

Functions

The following functions are not associated with an instance. Call them as PFT::Header::function(...)

slugify

Given a string, construct a slug, that is a simplified version of such string.

(TODO: better describe it, also w.r.t. Unicode)

Properties

    $hdr->title
    $hdr->author
    $hdr->template
    $hdr->tags
    $hdr->date
    $hdr->opts
    $hdr->slug
    $hdr->tags_slug

title

Returns the title of the content.

Outputs a in decoded string.

author

Returns the author of the content, or undef if there is no author.

Outputs a in decoded string.

tags

A list of tags declared by the header.

The tags are in a normal (i.e. not slugified) form. For a slugified version use the tags_slug method.

date

The date declared by the heade, as PFT::Date object.

opts

A list of options for this content.

slug

A slug of the title.

tags_slug

A list of tags as for the tags method, but in slugified form.

Methods

set_date

Setter for date. The parameter must be a PFT::Date object.

dump

Dump the header on a file. A GLOB or IO::File is expected as argument.