= About

Tangerine is a general-purpose templating system written in Ruby.

It fits nicely to the object-oriented model and is, due
effective code "compilation" faster than usual template systems,
like for example ERB.

Tangerine is not specific to any output; you can create all kind of
text.  There are two special classes, however---Tangerine::XML and
Tangerine::RFC822---which provide automatic (but overrideable) XML/RFC822
escaping.  Additional escaping code for special formats can be added
easily.

Tangerine does not have any requirements other than Ruby >= 1.8.

= Usage

Tangerine uses a two-step approach to templating.  First it will
_parse_ the template and generate code for it.  This is done at
instantiation. After generation, you can pass the template around
and _expand_ it on arbitrary objects. (Which should have the same
interface if you want the template to work, of course.)

A typical usage would be something like:
  # Parse template:
  template = Tangerine.new File.read("my/template/file.tng")

  # Construct object:
  object.heading = "Tangerine Developers"
  object.members << Person.new("Christian", "Neukirchen", "chneukirchen@gmail.com")

  # Expand template into a file:
  File.open("my/output/file.html", "w") { |f| template.expand(f, object) }

= Tangerine Templates

Tangerine uses a very easy to pick up templating language that is
output-agnostic.

All text is passed verbatim, except so called tags. Tags are introduced
using two commas (<tt>,,</tt>); various flags may follow.  After these,
you write the tag content.  It is either

* a ruby method name to be sent to the object, written as-is:
    ,,author
    ,,heading
    ,,recent?

* an array-like accessor to be retrieved from the object, written as usual:
    ,,[1]
    ,,['hashkey']

* or arbitrary code to get <tt>instance_eval</tt>ed, enclosed in
  parentheses (which *need* to match):
    ,,(1+1)
    ,,(Time.now)
    ,,(author.upcase)
    ,,(self['key'].reverse)

Valid flags are (and must, if you want to use several of them, be in
this order):

* <tt>#</tt> (Hash): Comment; ignore everything until the end of this line.

* <tt>|</tt> (Pipe): Indent the expansion to the current column.

* <tt>!</tt> (Bang): Don't apply any escaping code.

* <tt>:</tt> (Colon): Just run the tag, don't insert any output
  (useful for local variables, e.g. <tt>,,:(current_path=path)</tt>).

* <tt>@</tt> (At): Look up the tag in the tag library (see below).

After the tag content, there goes the _optional_ tag block, enclosed
in curly brackets that come _directly_ after the tag name.  This block
is a sub-template following the same rules as any Tangerine
template. It gets applied to each element if the tag content evaluates
to an +Enumerable+, or only once with the return value if it is true.
The braces *need* to match.

    ,,recent?{Recent entry}
    ,,authors{
      Name: ,,name
      Mail: ,,mail
    }

= Tag libraries

Tag libraries provide an easy way to build and structure complex
templates.  Tags starting with <tt>@</tt> are looked up using the tag
library which is given as the second argument to
<tt>Tangerine.new</tt> (any may be changed using the accessor
<tt>Tangerine#taglib=</tt>).

Tag libraries are objects that implement <tt>resolve(tag)</tt> and
return a string that gets evaluated as a Tangerine template *instead*
of the tag upon calling that method.

One sample tag library that maps tags to files is included as
<tt>Tangerine::FileLib</tt>.

= Copyright and License

Copyright (C) 2004  Christian Neukirchen <http://purl.org/net/chneukirchen>

Tangerine is licensed under the same terms as Ruby itself.

= Version
See Tangerine::VERSION.