The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Zucchini-0.0.17
River stage zero No dependents
2 ++
/ Zucchini::Config

NAME

Zucchini::Config - manage configuration file loading

SYNOPSIS

  # get a new config object
  my $zcfg = Zucchini::Config->new();

  # get a new config object (using an alternative file)
  my $zcfg = Zucchini::Config->new(
    { config_file => $some_other_file }
  );

  # get the parsed config data
  my $stuff = $zcfg->get_data();

DESCRIPTION

This module uses Config::Any to attempt to load .zucchini in the user's home directory.

The preferred format is Config::General, but any format supported by Config::Any can be used.

All examples will assume the user is using the Config::General format.

CONFIGURATION FILE

The .zucchini configuration file is the governing force for the behaviour of the various Zucchini components.

The default location for the configuration is set to

  $ENV{HOME}/.zucchini

This is usually overridden by using the --config=FILE option when using script/zucchini.

The file takes the following general form:

  # the site section to use if none specified
  default_site   'sitelabel1'

  # site section definitions
  <site>
    <sitelabel1>
    ...
    </sitelabel1>

    <sitelabel2>
    ...
    </sitelabel2>
  </site>

The <sitelabelX> section contains information to configure the behaviour for a single website. This section takes the following general form:

  <sitelabel>
    source_dir          /path/to/tt_templates
    includes_dir        /path/to/tt_includes
    output_dir          /var/www/default_site/html

    template_files      \.html\z

    always_process      impressum.html
    always_process      \.imp\z

    ignore_dirs         CVS
    ignore_dirs         .svn

    ignore_files        \.swp\z
    ignore_files        \.tmp\z

    <tags>
        variable1       value1
        variable2       value2
    </tags>

    <rsync>
        hostname        remote.hosting.site
        path            /home/username/default_site/www
    </rsync>

    <ftp>
        hostname        remote.ftp.site
        username        joe.bloggs
        password        SecretWord
        passive         1
        path            /htdocs
    </ftp>

    <tt_options>
        PRE_PROCESS     my_header
        POST_PROCESS    my_footer
        # ... etc
  </sitelabel>

CONFIGURATION FILE ELEMENTS

These are the blocks and variables that make up a .zucchini configuration file:

<site>

The <site> tag is a top-level element to hold the various configuration blocks for each site.

<"sitelabel">

Each site specific configuration block is contained in a <sitelabel>...</sitelabel> block. "sitelabel" should be replaced with a meaningful label. For example, a configuration block for the site "www.herlpacker.co.uk" might look like this:

  <site>
    <herlpacker>
      # site configuration here
    </herlpacker>
  </site>

To configure more than one site, simply add a new "sitelabel" block for each site:

  <site>
    <herlpacker>
      # site configuration here
    </herlpacker>

    <chizography>
      # site configuration here
    </chizography>
  </site>
source_dir

Found in a "sitelabel" block, this is the path to the root directory of the templated version of the site.

This is the directory that contains the files that will be processed and copied to the output_dir.

   # e.g.
   source_dir /home/zucchini/sites/MYSITE/tt_templates
includes_dir

Found in a "sitelabel" block, this is the path to the directory containing blocks of Template Toolkit magic that are INCLUDEd or PROCESSed by the files in source_dir.

Examples of files you might expect to find as includes are header.tt and footer.tt - the common parts before and after the varying body content.

   # e.g.
   source_dir /home/zucchini/sites/MYSITE/tt_includes
output_dir

Found in a "sitelabel" block, this is the path to the directory where processed templates will be written to.

Also, files that are not ignored as a result of ignore_dirs or ignore_files will be copied to the appropriate location under this specified directory.

Quite often this will match the DocumentRoot location for a locally configured VirtualHost in apache2.

    # e.g.
    output_dir /var/www/mysite
website

Found in a "sitelabel" block, this is the URL for the live site. It's primarily used by the Zucchini::Fsync functionality to retrieve the digest.md5 file it uses for local-remote file comparison.

    # e.g.
    website http://www.mysite.com/
template_files

Found in a "sitelabel" block, this option specifies which files should be treated as templates.

Most of the time you will only need one entry, to specify files with the ".html" extension.

    # .html files should be treated as templates
    template_files      '\.html\z'

To indicate that other filetypes should also be treated as templates, add a new row for each filetype you require.

    # .html files should be treated as templates
    template_files      '\.html\z'
    # .txt files also require template processing
    template_files      '\.txt\z'

The value used should be a perl regexp that can be applied to a filename. If in doubt, copy an existing rule and modify the '.html'.

always_process

Found in a "sitelabel" block, this option specifies which files should always be processed regardless of their modification time.

    # always process *.imp files
    always_process      '\.imp\z'

You can specify as many items as you require. Each value is interpolated into a regular expression.

This means that

    # this probably doesn't do what you think ...
    always_process      dex.html

will cause all of your index.html files to be processed. Instead use something like:

    # you need to use start- and end- of string anchors
    always_process      \Adex.html\z

\A and \z are similar to ^ amd $. See "Assertions" in perlre for more details.

ignore_dirs

Found in a "sitelabel" block, this option is used to specify directories which should not be processed during site templating.

This is mostly useful if your templates are managed with a version control system (e.g. CVS, or subversion) and you don't want the repository management directories to be copied as part of the live site source.

One ignore_dirs statement is required for each directory to be ignored.

    # ignore CVS and subversion directories
    ignore_dirs 'CVS'
    ignore_dirs '.svn'
ignore_files

Found in a "sitelabel" block, this option is used to specify files which should not be processed during site templating.

This is useful to prevent, for example, editor swap files from being copied into the output_dir as part of the processed site source.

One ignore_files statement is required for each file to be ignored.

    # ignore vim swap files
    ignore_files '\.swp\z'

The value used should be a perl regexp that can be applied to a filename. If in doubt, copy an existing rule and modify the '.html'.

lint_check

Found in a "sitelabel" block, this option enables HTML error checking. While not as thorough as a full W3C validator, this option should alert you to commons errors.

    # check for HTML errors
    lint_check 1
<tags>

This block, found in a "sitelabel" block, is used to set variables that will be available in the template as a [% ... %] style variable.

For example, defining:

    <tags>
        author     Joe Bloggs
        copyright  &copy; 2008 Joe Bloggs. All rights reserved.
    </tags>

will allow you to do the following in your templates (or footer.tt):

    <p>Site Designed by [%author%]</p>
    <p>[%copyright%]</p>
<rsync>

This block, found in a "sitelabel" block, defines the conection details used when using the rsync options to transfer the generated site to the remote server.

    <rsync>
        # options go here
    </rsync>
<ftp>

This block, found in a "sitelabel" block, defines the conection details used when using the fsync options to transfer the generated site to the remote server.

    <ftp>
        # options go here
    </ftp>
hostname

Found in an "rsync" or "ftp" block, this is the destination server for the generated website.

    # e.g.
    <rsync>
        hostname    some.remote.server
        # ...
    </rsync>

In an "rsync" block you may prepend the value with the username:

    # e.g.
    <rsync>
        hostname    someuser@some.remote.server
        # ...
    </rsync>
path

Found in an "rsync" or "ftp" block, this is the path on the remote server where the generated site will be copied to.

Note: You don't usually require a trailing '-' for the "path" value inside an "rsync" block.

    # e.g.
    <rsync>
        # ...
        path    /home/someuser/MYSITE/www
    </rsync>
username

Found in an "ftp" block, this is the username used during the FTP log-in phase of the remote transfer.

    # e.g.
    <ftp>
        # ...
        username    joebloggs 
    </ftp>
password

Found in an "ftp" block, this is the password used during the FTP log-in phase of the remote transfer.

    # e.g.
    <ftp>
        # ...
        password    SekritWurd 
    </ftp>

Note: This password is stored unencrypted. Please be strict with the file permissions of your .zucchini file, preferably making the file only readable to yourself:

    # stop people peeking at our FTP credentials
    chmod 0600 ~/.zucchini
<ttoptions>

This block allows you to set or override configuration options for the Template object that's created to process the templates.

No validation is performed by Zucchini. You can explore the available options by reading Template::Manual::Config's manual.

    # e.g.
    <tt_options>
        PRE_PROCESS     my_header
        POST_PROCESS    my_footer
        EVAL_PERL       1
    </tt_options>

SETTING DEFAULT COMMAND-LINE VALUES

Sometimes it can be tedious adding the same command-line switches to calls to zucchini.

You can preset commonly used options in the cli_defaults section of your .zucchini file:

  <cli_defaults>
    verbose         1
    showdest        1
    showpath        1
  </cli_defaults>

Any options specified on the command-line will take precedence over the defaults in the .zucchini file.

  # we don't really want to see the destination
  zucchini --no-showdest

SEE ALSO

Config::Any, Config::General, "Assertions" in perlre, Template::Manual::Config, Zucchini, Zucchini::Fsync, Zucchini::Rsync

AUTHOR

Chisel Wright <chiselwright@users.berlios.de>

LICENSE

Copyright 2008-2009 by Chisel Wright

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See <http://www.perl.com/perl/misc/Artistic.html>