TreeFallingInTheWoods

Renshi is a templating language for Ruby which is unobtrusive in HTML and XHTML structures. 

$ Code
======
To output data on the page stick a $ in front of your var. or expression

$foo
$Time.now

If there's a space in your expression or you need formatting use ${}

${foo},$Time.now 

To insert statements in your template use $[]

$[foo = "hello world"]

$[if foo]
  $foo
$[end]

Attribute Expressions
===================
The $ syntax will give you everything ERB does, with less typing. But Renshi also has 'attribute expressions',
which can be inserted into a HTML element as an attribute - e.g. .... 

r:expression_name="expression" - the expression value is treated as a Ruby expression .

Some expressions, such as r:each, use the quoted value to also hold parameter information.

Current Attribute Expressions
* If 
* Unless
* Elsif 
* Else
* While
* For
* Each

* If
hello would render "hello"

goodbye! will render "".

* Unless
e.g. hello

* Elsif

hello!
goodbye

* Else

hello!
goodbye
neither

r:elsif and r:else must be adjacent (a sibling) to the element.

For example, the below is fine, because the if and else statements are adjacent siblings in the tree of elements.


  
 ... 

  
 ... 
  


* While


  hello$foo
  $[foo = foo + 1]


renders:


  hello0
  

  hello1
  


* For


hello$foo


renders:


hello0

...etc

hello99


* Each
The expression takes the object and then any arguments for the each block after a comma; so you can do anything with it that each supports.

r:each="foos, |k,v|" to iterate over a hash
r:each="foos, |foo|" to iterate over an array


hello$foo



hello0

...etc

hello99


Further elements will appear as I have time to make them or others want to contribute them. 
There isn't much to making them. If there's one you'd especially like, let me know on lighthouse and I'll see about adding it.

The one restriction is that I want to limit attribute expressions to one key and value combination on the element (everything fits into r:foo="expression").
I want to avoid complexity like "" for example - see r:each for the workaround.

See renshi/lib/renshi/attribute_expressions for how they work.

Other Rules
===========
$ values inside of attributes are only interpreted as Renshi variables for regular attributes (not renshi attributes).

E.g. 
 the r:if statement would treat $ exactly as Ruby does, while the id attribute value is transformed.

To print a $ use $$, e.g. $$10.95 comes out as $10.95

Renshi documents are appended with the suffix of .ren

e.g. index.html.ren or index.ren 

Installation
============
Renshi is hosted on Rubyforge so 'sudo gem install renshi'. Alternatively, use github to do what you want with it.


Framework Integration
=====================

* Rails
Simply require the renshi gem in your code, and Renshi will make itself available.

There is a Rails 2.3.2 example app in the examples directory. Go there, start up the application, and visit http://localhost:3000/hello

I'd welcome integrations for Sinatra and Merb or XYZ framework. See renshi/lib/renshi/frameworks (see below - How Fast Is It?)


How Fast Is It? - Compilable Templates
======================================
I don't know - I've not benchmarked it yet. It's built solely on Nokogiri, which is very fast. To a certain extent it's an irrelevant question, given that Renshi compiles .ren documents into chunks of ruby code, which are kept in memory and reused. This was written specifically for the Rails notion of compilable templates (see ActionView::TemplateHandlers::Compilable and Renshi::Frameworks::Rails).

ERB and HAML also do this (in fact I worked from the source code of both). It means, essentially, that a foo.html.ren document is compiled once into ruby, and each presentation of the template is then a matter of using the generated code (not reading the template).

Thus, 100 requests for the template means 1 call to Renshi to generate the necessary code. At some stage I might benchmark this raw ruby - but I've written it with an eye on efficiency as it's generated and so far it seems very fast. If someone enjoys benchmarking then please jump in.

When integrating this feature with other frameworks, simply use a delegate object to hold the compiled code and evaluate it against the binding you want to use (see the spec.s for this). 

E.g. some helper methods in the spec_helper.rb might get you started. For the integration you'd keep memory of which files had been compiled (only call compile_file once).

def compile_file(file)
  compiled = Renshi::Parser.parse(read_file(file))  
end

def interpret(file, context)
  eval(compile_file(file), context)
end

rendered_template = interpret("index.html.ren", binding)

Development
===========
Please report any bugs at the http://renshi.lighthouseapp.com . 

Contributions are welcome. Right now it's just me.

Why Renshi?
===========
Firstly, it doesn't need a reason. It's a fun project.

But ...

I've always found ERB to be a bit cumbersome - <%= is quite tiring to type out when you realise it could be much shorter. I used to think that Velocity, in Java, was the most fun templating language I'd used, and I had wanted something equally as concise for Ruby.

A real need for it emerged in a project which relied upon an external design house handing us HTML. Converting it incessantly into HAML was a headache. A colleague mentioned Genshi in Python as ideal, which was when the idea of Renshi was conceived.

It should give the developer power to do what they want, without being restrictive. You can throw $ statements around the place in a document or use attribute expressions to preserve a strict xhtml layout.

English to Japanese
===================
Renshi (錬士 : れんし ?): instructor.

In Japanese 'renshi' refers to a martial arts master - http://en.wikipedia.org/wiki/Renshi. 'Ren' means 'polished' and 'shi' means 'person'. 

It apparently also means 'to know another' in Mandarin.

The project was originally inspired by Genshi, http://genshi.edgewall.org - though it is significantly different in its approach.