PFT::Header(3)

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.