view release on metacpan or  search on metacpan

lib/App/FuguWeb/Config.pod  view on Meta::CPAN

=head1 NAME

App::FuguWeb::Config - the site description over Fugu::Config

=head1 SYNOPSIS

    use App::FuguWeb::Config;

    my $config = App::FuguWeb::Config->load(error => \my $reason)
        or die "$reason\n";

    say $config->site;
    say $_->{href} for $config->nav;
    say $_->{file} for $config->pages;

=head1 DESCRIPTION

The class reads F<.fuguwebrc>, applies the defaults, and validates the
result. The grammar, the quoting, and the yes/no spellings come from
L<Fugu::Config>; this class holds what is true of a site.

The object is immutable once loaded, and the module keeps no package
state. Two sites in one process therefore share nothing.

=head1 METHODS

=head2 load

    App::FuguWeb::Config->load(
        root  => $dir,          # default: discover
        error => \my $reason,
    )

Read and validate the description. The method returns the object, or
C<undef> with the reason in C<$reason>.

Without C<root>, the method walks up from the working directory to the
first directory that holds F<.fuguwebrc>, as C<fuguvm> finds
F<.fuguvmrc>.

The reason travels through a reference because the object that would
hold it does not exist when the load fails.

A load fails when the file is absent, when a line does not parse, or
when the description would make the build do something it must not.
Every message names the file, and the block when a block is at fault.

The description is rejected when:

=over 4

=item *

there is no C<site> setting;

=item *

a C<page> block names no source, or more than one;

=item *

two C<page> blocks name the same file, or two manuals would become the
same page;

=item *

a C<nav> block has no label;

=item *

a path setting steps out of the project with a C<..> component;

=item *

a C<page> block name is absolute or steps out of the output directory:
the name becomes a file there, so it is a path and gets the same guard
the sources get;

=item *

a C<manuals> namespace holds a path separator: it prefixes a manual
name, and that name becomes both the staged file and the published
page;

=item *

a C<modules> directory is not below C<module_root>, which would leave
the module with no name to take but its whole path;

=item *

a yes/no setting holds something that is neither;

=item *