= 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 (,,); 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 instance_evaled, 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): * # (Hash): Comment; ignore everything until the end of this line. * | (Pipe): Indent the expansion to the current column. * ! (Bang): Don't apply any escaping code. * : (Colon): Just run the tag, don't insert any output (useful for local variables, e.g. ,,:(current_path=path)). * @ (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 @ are looked up using the tag library which is given as the second argument to Tangerine.new (any may be changed using the accessor Tangerine#taglib=). Tag libraries are objects that implement resolve(tag) 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 Tangerine::FileLib. = Copyright and License Copyright (C) 2004 Christian Neukirchen Tangerine is licensed under the same terms as Ruby itself. = Version See Tangerine::VERSION.