[ruby-talk:24475] ANN: Ruby Templating System 0.0.1

I decided to put this up on the RAA in case someone might find it useful.

Here's the README:
ruby_templates

files: template.rb - defines TemplateFile class
       tests/vhdl  - test file
       tests/license.txt - test file


What is it/what does it do?:
It takes a template file, which is a text file that may include embedded 
Ruby 
code, and returns a string where any embedded Ruby code is replaced with 
the results of executing that code.
You can also think of this as sort of like the C preprocessor (cpp) 
with the additional feature that  allows you to include Ruby code.  
There are also directives which allow conditionals based on 
Ruby expressions.

Directives which can be used in your template files:

#>IF #{condition} 
  - condition can be any kind of Ruby expression that results in a true or
    false value. If it returned 'true' then you're in this branch.
#>ELSE
  - if condition was false, this branch will be evaluated.
#>END
  - end of a #>IF or #>IF - #>ELSE - #>END block.  
(NOTE: #>IF directives can be nested)
#>INCLUDE <filename>
  - where the file in 'filename' will be included in the current 
TemplateFile.
#{ .. } - Ruby code and/or variables must be surounded by these blocks 
        in your template file just
        as they are in double quoted Ruby strings.  I'll refer to these as
        'interpolation blocks' from here on.

TemplateFile public methods:

new(file,bind) - file is the name of your template file, bind is a binding
                 for the eval.
transform    - transform the TemplateFile by evaluating all of the Ruby 
               expressions embedded in it.

USAGE NOTES:

Ruby code or variables are placed between #{ and } (interpolation blocks)
just as you would do in a double-quoted string.  Note that the last string 
returned from the #{..} block will be included in the transformed string.  
So in practice, if you have a template file and you want to include code 
that will print n number of lines which start with a line number, you 
would 
have to introduce a string variable in your block like (of course n has to 
be defined in your Ruby code:

first line
some text#{$/} #{str="";n.times do |i| 
                      str << "#{i}:blah#{$/}"
                   end
            str }
more text
end

If n = 3, this example will print:

first line
some text
0:blah
1:blah
2:blah
more text
end

(I know, not too useful, but I needed some kind of example :)
There are a few things to notice here:
1) Newlines - in order to allow user's to include newlines "\n" in their
code (for example, what if you are using this on a C file which contains:
'printf("\n")' - you don't want that '\n' to be transformed.  So note that
the first interpolation block contains '$/' which is a built-in Ruby 
global 
that contains the appropriate newline character(s) for your system (So 
don't
change the value in $/ if you're using this!)
2)In the second interpolation block we define a string variable called str 
which is just a temporary (and local) string variable defined so we can 
return it from the block later after we've appended to it.  You'll need to 
follow this model if you want to do any kind of iterative processing 
inside 
an interpolation block.
3)The code in your interpolation block can span multiple lines (the first
version of this that I posted to comp.lang.ruby and on the RubyCookbook
would not allow your code to span multiple lines - I fixed it in this 
version)



Examples:
take a look at the end of the file template.rb, it shows how to 
instantiate and transform a template file called "vhdl" in the tests 
subdirectory.  The file "vhdl" shows how to use all of those directives 
defined above and #>INCLUDE's a file called license.txt which also has 
embedded Ruby code in it.
Remember, you'll have to 'require "template.rb"' in your own scripts
in order to use the TemplateFile class.


That's about it.  If you have questions you can contact me at:
[e-mail]

Licencse:
Everything here is covered under the same license as Ruby.

Credits:
thanks to Ruby's '#{ }' operator, this was a lot  easier to do in Ruby 
than it was in Perl.