========
 jabuti
========

Inserts values from a values file into a template file.


----------
 DOWNLOAD
----------

Sources:

jabuti-1.3.0.zip


-------
 USAGE
-------

    jabuti [-h -V -o OUTPUT -d DIRECTORY] -t TEMPLATE VALUES...

More than one VALUE file may be given. Each file is evaluated independently.


---------
 OPTIONS
---------
 
    -o, --output      Writes to OUTPUT; default is VALUES.out
    -d, --directory   Write files to DIRECTORY
    -t, --template    Specify the template file
    -h, --help        Shows this help message
    -V, --version     Shows version information


----------------
 TEMPLATE FILES
----------------

It is possible to insert values specified in the values file with

    $(NAME)

inside the template file. To insert text only if a value was defined:

    $ifdef(NAME, TEXT)

To insert text for each value defined with a name:

    $each(NAME, TEXT)

It is possible to use NAME inside TEXT. In this case, it follows the value
used by each iteration. If there is no value named NAME, it inserts no
text at the position.

It is also possible to use 'index0' (starting at 0) and 'index1' (starting
at 1) names to insert the index of each of the values.

The 'eachall' insertion is similar, but iterates over all values at once.
If a name hasn't all the needed values, it inserts no text at the position.
The 'first', 'last', 'count' and 'index' special names are substituted
by the first or last value, the number of values, and the current value
index. These special values only work inside an 'eachall' insertion.

To insert the number of values associated with NAME:

    $count(NAME)

The 'input' especial name is associated with the list of values file names
specified in the command line.

To redirect the output to file TEXT:

    $output(TEXT)

Any number of $output insertions may be used in the same template.

TEXT is a sequence, separated by spaces, of names and strings in any order.
Names are substituted by the concatenation of the associated values (except
when inside an 'each' insertion). Strings are copied without
modifications.

Strings are enclosed in quotes ("). Duplicate quotes to insert them inside
strings:

    "She said: ""Bye!"""

Names can have any combination of ANSI letters and numbers and are case
sensitive.


-------------
 VALUE FILES
-------------

Values are specified in the form:

    NAME "VALUE"

Any number of name-value pairs may be given, and the same name may be
associated with more than one value.


---------
 EXAMPLE
---------

A template file like:

    << $(title) >>

    Welcome to $(name)'s place.

    $ifdef(favorite, "These are my favorite colors:

    ")
    $each(favorite, "* " favorite "
    ")
    Bye!

With this value file:

    name "Foo"
    title "Example"

Will generate this output file:

    << Example >>

    Welcome to Foo's place.

    Bye!

But with this value file:

    title "Example 2"
    favorite "blue"
    name "Boo"
    favorite "red"
    favorite "yellow"

It generates:

    << Example 2 >>

    Welcome to Boo's place.

    These are my favorite colors:

    * blue
    * red
    * yellow

    Bye!


------
 BUGS
------

None for now...


------
 TODO
------

In decreasing order of importance:

* Better documentation
* Support for insertions inside TEXT's

    $each(First, "Student " index " of " count(First) ": " upper(Last) ", " First)

* 'upper' and 'lower' special insertions
* Convert 'count', 'first' and 'last' to functions; deprecate their usage as
  names


-----------
 CHANGELOG
-----------

1.3.0 (2004-06-18)
    * $first and $last special insertions
    * 'count', 'first', 'last' and 'input' special names
    * '-d' command line option
    * Quotes can be inserted in strings by duplicating them

1.2.1 (2003-09-02)
    * Corrected the following bugs:
      - There must be a space or empty line (' ', '\t', '\n', '\r') before the
        first name-value pair in the values file.
      - The use of the iterated name inside an $each insertion TEXT part
        issues a warning in some situations.
    * Allowed more than one values file to be used in the command line

1.2.0 (2003-09-01)
    * $count and $output special insertions
    * 'index0' and 'index1' special names
    * The characters '_', '-' and '.' can be used in names

1.0.0 (2003-08-30)
    * First version


-------
 OTHER
-------

You can contact me at 

Besides that,

     jabuti
     Copyright (C) 2003, 2004  Diogo Kollross
 
     This program is free software; you can redistribute it and/or modify
     it under the terms of the GNU General Public License as published by
     the Free Software Foundation; either version 2 of the License, or
     (at your option) any later version.
 
     This program is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     GNU General Public License for more details.
 
     You should have received a copy of the GNU General Public License
     along with this program; if not, write to the Free Software
     Foundation, Inc., 59 Temple Place - Suite 330,
     Boston, MA 02111-1307, USA.