view release on metacpan or  search on metacpan

script/mowyw  view on Meta::CPAN

non-ASCII-characters might not survive the round trip to vim if the locales
don't fit. On my systems UTF-8 locales worked, everything else didn't. So use
with caution.

=head1 OPTIONS

Currently only two options are supported, C<no-header> and C<no-footer>.
If they are set in a file via C<[% option no-header %]>, the inclusion of
header or footer files will be omitted.


=head1 DATA SOURCES

You can access external data sources by first C<bind>'ing a variable to a
data source, and then iterating with a C<for> loop over that source.

This is best illustrated with a short example.

File C<includes/news.xml>:
        
    <rootTag>
        <item>
            <headline>China buys Google</headline>
            <status>April's fool joke</stoke>
            <date>2007</date>
        </item>
        <item>
            <headline>Perl and Python join forces: Larry Wall and Guido von
            Rossum announce 'parrot'</headline>
            <status>April's fool joke</stoke>
            <date>Very old</date>
        </item>
    </rootTag>

Now you can access the contents of this XML file in your source files:

    [% bind news_variable type:xml file:news.xml root:item %]
    [% comment and iterate over news_variable %]
    [% for i in news_variable %]
        <h2>Breaking news: [% readvar i.headline %]</h2>
        <p>Status: [% readvar i.status %]</p>
    [% endfor %]

Data sources are handled via plugins. Currently XML and DBI are supported.

The XML source is explained by the example above. The only additional option
is 'limit', which can be set to a positive number and which limits the number
of iterations. This plugin is quite limited in that the file structure always
has be the
same: one root tag that contains a list of secondary tags, each of which many
only contain distinct tags. Nested tags might work, but aren't officially
supported.

DBI is perls generic database interface. You can use it to access a database.
This has some limitations, for example you can't reuse database connections,
so every C<bind> statement actually opens a database connection on its own.

For the brave, here is an example of how to use it:

    [% bind my_db type:dbi dsn:DBI:mysql:database=yourdatabse;host=dbhost
       username:your_db_user password:you_db_password encoding:latin1
       sql:'SELECT headline, status FROM news LIMIT 10'
    %]
    [% for i in my_db %]
        <h2>Breaking news: [% readvar i.headline escape:html %]</h2>
        <p>Status: [% readvar i.status escape:html %]</p>
    [% endfor %]

The options are as follows:

=over

=item

The C<dsn> option is the "data source name" that C<DBI>'s C<connect> method
accepts. It always starts with C<DBI:>, then followed by the driver name
like C<mysql> or C<Pg> (for Postgres) and the driver options.

=item

The C<encoding> option is optional and defaults to C<utf-8>. You can use 
any character encoding here that Perl's cool C<Encode> module supports,
which is quite a many.

=item

the C<password> and C<username> options can be omitted if your database
doesn't ask for them

=back

This plugin may seem weird if you don't know Perl and its database module. If
that's the case, consider toying around with Perl and DBI first (it's really
worth a try).


=head1 CONFIGURATION FILE

Mowyw tries to read a file called C<mowyw.conf>. Within that file you can
configure include pathes and file names on a per-file base, and you can
specify which files should be processed.

An example config file might look like this:

    MATCH[german]    = \.de
    POSTFIX[german]  = .de
    MATCH[english]   = \.en
    POSTFIX[english] = .en

    INCLUDE[10]      = \.xhtml$
    EXCLUDE[50]      = _private

The first part defines two sections called "german" and "english". 
If a file matches the
regular expression C<\.de>, it is treated as being in section "german". All
include files will have the postfix '.de', which means that if a file is
called C<source/index.html.de>, the header file will be C<includes/header.de>, a
menu C<foo> will be searched for in file C<includes/menu-foo.de> etc.

This configuration mechanism is primarily intented for creating mutilingual
sites, but might be useful for other things as well.

The second part consists of C<INCLUDE> and C<EXCLUDE> statements with their
priority and the regex they match. Higher priority rules are tested first.
When a rule matches the file is either processed (in the case of an C<INCLUDE>
option) or just verbatimly copied (in case of an C<EXCLUDE> option). 

Due to an limition of the module that reads the config file
([mod://Config::File]) the
only way to specify rules with the same priority is to prefix them with
distinct strings:

    INCLUDE[a5] = foo
    INCLUDE[b5] = bar

is equivalent to
    
    INCLUDE[5]  = foo|bar

Don't give C<INCLUDE> and C<EXCLUDE>-options with the same priority, the
behaviour in that case is undefined.

=head1 SEE ALSO

If something isn't clear to you, please take a look into the  C<README> file
and the examples in the source tarball. If that doesn't answer your questions,
don't hesitate to contact the author.