DESCRIPTION

Erbside is an easy to use project-oriented inline templating utility. Erbside templates are written in script comments and have access to project metadata.

FEATURES

  • Easy to use.
  • Supports almost any script type.
  • Uses ERB as template format.
  • Can use .index to provide project metadata.
  • Can use other resources for metadata, such as a project's gemspec.

SYNOPSIS

Writing Templates

Erbside is an inline, or inplace, templating system. Inline templating makes it possible to add dynamic rederings to otherwise static files without the need for separate template files. This is acheived by utilizing a file type's support of comments --so this is only possible with specific file types. Obviously, the target format of erbside is Ruby (.rb), though other files formats are also supported.

Inline templating is indicated by the :erb: marker. For example, in a Ruby script we might add an inline erbside comment as follows:

  module YourLibrary
    VERSION = "1.0.0"  #:erb: VERSION = "<%= version %>"
  end

As given, an inline template will replace the whole line when rendered (albeit honoring indention). We can use the ^ match carrot to indicate that the rendering should only replace the line from the matching text onward. Notice also in this next example that we can template comment lines as well.

  # Generated on XXXX  #:erb: ^on <%= Time.now %>

I have choosen this example because it elucidates a potential gotcha in creating such inline templates. Notice we match "on". When rendered this line will have a time stamp, eg: 

  # Generated on Mon Nov 08 13:54:04 -0500 2009  #:erb: ^on <%= Time.now %>

The catch here, is that the next time this is renderd it will match the "on" in "Mon" and not the one intended. That something to watch out for. In this case we might replace "on" with "@" as a simple fix.

Inline templates can also handle multi-line substitiuations. This is acheived by specifying the number of lines to absorb in the erb marker.

  # :erb+3: <%= Dir['*'].join("\n") %>
  file1
  file2
  file3

Notice the +3. This indicates that the next three lines (after any additional comment lines) are to be replaced by this rendering.

Running the erbside Command

The erbside command simply takes the files you with to render as arguents. If a directory is provided rather than a file, any "erb-able" files within the directory will be included, e.g.

  $ erbside **/*.rb

For which all #:erb: inline templates in all the .rb files will be filled in.

HOW TO INSTALL

To install with RubyGems simply open a console and type:

  $ sudo gem install erbside

Local installation requires Setup.rb (gem install setup), then download the tarball package and type:

  $ tar -xvzf erbside-1.0.0.tar.gz
  $ cd erbside-1.0.0.tar.gz
  $ sudo setup.rb all

Windows users will not need the sudo, but will probably need to be logged-in as an admistrator of the system.