Ember 0.0.1

Software	Description	Notes
Ruby	Ruby language interpreter	Version 1.8.6, 1.8.7, and 1.9.1 have been tested successfully.
RubyGems	Ruby packaging system	Version 1.3.1 or newer is required.

What increased in the version number?	The increase indicates that the release:
major	No	Yes	Yes
minor	Yes	Yes	Yes
patch	Yes	No	Yes

Command-line interface
Ruby library interface
eRuby template directives

3.1 Command-line interface

When you run this command:

ember --help

You will see this output:

Ember - eRuby template processor

Evaluates eRuby directives in the given eRuby template and
writes the result to the standard output stream (STDOUT).


Usage:

  ember [Options] [Source]


  Source:   Path to an eRuby template file.  If this parameter is
            not specified, then the result of reading the standard
            input stream (STDIN) will be used as the eRuby template.


Options:

   --shorthand, -s:   Treat lines beginning with "%" as directives
   --infer-end, -i:   Add "end" statements based on indentation
    --unindent, -u:   Unindent block content hierarchically
     --compile, -c:   Print template program and exit
      --manual, -m:   Show the user manual
  --locale, -l <s>:   Set preferred language
     --version, -v:   Print version and exit
        --help, -h:   Show this message

3.2 Ruby library interface

Begin by loading Ember into Ruby:

require 'rubygems'
require 'ember'

Instantiate a template processor:

source   = "your eRuby template here"
options  = { :unindent => true, :shorthand => true }

template = Ember::Template.new(source, options)

Inspect the Ruby program that is used to evaluate the eRuby template:

puts template.program

View the result of evaluating the eRuby template:

puts template.render

See the API documentation for details and examples.

3.3 eRuby template directives

eRuby templates are plain-text documents that contain special processing instructions known as directives. Directives may be expressed using either standard or shorthand notation:

Notation	Directive	Head	Operation	Body	Tail
Standard	<%XY%>	<%	X	Y	%>
Shorthand	%XY	%	X	Y

In standard notation, the directive is composed of a head, an operation, a body, and a tail. Furthermore, the directive may appear anywhere in the text.

In shorthand notation, the directive is composed of a head, an operation and a body. Furthermore, the directive may only appear in the text if it occupies an entire line.

In any case, directives are atomic constructs; they may not be nested.

Operations

3.3.1 Operations

The first character that follows the head of a directive is known as an operation. Operations specify how the directive should be processed:

Operation	Effect	Example
#	The entire directive is omitted from the output.	Comment directives
=	The body of the directive is evaluated as Ruby code, and the result of this evaluation is inserted into the output.	Vocal directives
~	The body of the directive is evaluated as an eRuby template, and the result of this evaluation is inserted into the output.	Dynamic template evaluation
+	The body of the directive is evaluated as Ruby code, and the result of this evaluation is assumed to be a string that specifies the path (either absolute or relative to the eRuby template file in which this directive is found) to a file containing an eRuby template. This file is read and its contents are evaluated as an eRuby template, and the result of this evaluation is inserted into the output.	Template file inclusion
<	The body of the directive is evaluated as Ruby code, and the result of this evaluation is assumed to be a string that specifies the path (either absolute or relative to the eRuby template file in which this directive is found) to a file. This file is read and its contents are inserted into the output.	Raw file inclusion
\|	The body of the directive is treated as the beginning of a Ruby block. The `do` keyword is automatically appended to the body of the directive if missing.	Block directives
%	One ”%” character is omitted from the head of the directive and the entire directive is inserted into the output.	Escaped directives
(none of the above)	The body of the directive is evaluated as Ruby code, but the result of this evaluation is not inserted into the output.	Silent directives

Example 1. An empty template

Begin with an empty template:

This template compiles into:

(_erbout = []; _erbout << "\n"
; _erbout.join)

And renders as:

Example 2. Comment directives

Add comment directives:

<%# this is a comment %>
%# this is also a comment

<%# this is a

 multi-line comment %>

With {:shorthand=>true}, this template compiles into:

(_erbout = [];                     
                        
_erbout << "\n"
           

                    
; _erbout.join)

And renders as:

Example 3. Escaped directives

Add escaped directives:

<%% this is an escaped directive %>
%% this is an escaped directive

With {:shorthand=>true}, this template compiles into:

(_erbout = []; _erbout << "<% this is an escaped directive %>\n"
_erbout << "% this is an escaped directive\n"
; _erbout.join)

And renders as:

<% this is an escaped directive %>
% this is an escaped directive

Example 4. Vocal directives

Add vocal directives, which produce output:

<%= "hello" %>
%= "world"

With {:shorthand=>true}, this template compiles into:

(_erbout = []; _erbout << ( "hello" ) << "\n"
_erbout << ( "world") << "\n"
; _erbout.join)

And renders as:

hello
world

Example 5. Silent directives

Add silent directives, which do not produce output:

<% a = "hello" %>
% b = "world"

<%= a %>
%= b

With {:shorthand=>true}, this template compiles into:

(_erbout = [];  a = "hello" 
 b = "world"
_erbout << "\n"
_erbout << ( a ) << "\n"
_erbout << ( b) << "\n"
; _erbout.join)

And renders as:

hello
world

Example 6. Block directives

Add some Ruby blocks:

% words = %w[hello world]

<% words.each do |w| %>
  <%= w %>
<% end %>

% words.each do |w|
  %= w
% end

%|words.each |w|
  %= w
% end

With {:shorthand=>true}, this template compiles into:

(_erbout = [];  words = %w[hello world]
_erbout << "\n"
 words.each do |w| 
_erbout << "  " << ( w ) << "\n"
 end 
_erbout << "\n"
 words.each do |w|
_erbout << "  " << ( w) << "\n"
 end
_erbout << "\n"
words.each do |w|
_erbout << "  " << ( w) << "\n"
 end
; _erbout.join)

And renders as:

  hello
  world

  hello
  world

  hello
  world

Example 7. Infer block endings

Omit <% end %> directives from the template:

% words = %w[hello world]

<% words.each do |w| %>
  <%= w %>

% words.each do |w|
  %= w

%|words.each |w|
  %= w

With {:shorthand=>true, :infer_end=>true}, this template compiles into:

(_erbout = [];  words = %w[hello world]
_erbout << "\n"
 words.each do |w| 
_erbout << "  " << ( w ) << "\n"
end; _erbout << "\n"
 words.each do |w|
_erbout << "  " << ( w) << "\n"
end; _erbout << "\n"
words.each do |w|
_erbout << "  " << ( w) << "\n"
end; _erbout.join)

And renders as:

  hello
  world

  hello
  world

  hello
  world

Example 8. Raw file inclusion

When doc/example.txt contains:

This is a plain-text file.  Notice that <%=
"eRuby directives" %> have no effect here!

And the eRuby template is:

<%< "example.txt" %>

%< "example.txt"

With {:shorthand=>true, :source_file=>"doc/usage.erb"}, this template compiles into:

(_erbout = []; _erbout << (::Ember::Template.read_file(( "example.txt" ), {:shorthand=>true, :source_file=>"doc/usage.erb"})) << "\n"
_erbout << "\n"
_erbout << (::Ember::Template.read_file(( "example.txt"), {:shorthand=>true, :source_file=>"doc/usage.erb"})) << "\n"
; _erbout.join)

And renders as:

This is a plain-text file.  Notice that <%=
"eRuby directives" %> have no effect here!

This is a plain-text file.  Notice that <%=
"eRuby directives" %> have no effect here!

Example 9. Template file inclusion

When doc/example.erb contains:

This is an eRuby template.  Notice that <%=
"eRuby directives" %> do take effect here!

And the eRuby template is:

<%+ "example.erb" %>

%+ "example.erb"

With {:shorthand=>true, :source_file=>"doc/usage.erb"}, this template compiles into:

(_erbout = []; ::Ember::Template.load_file(( "example.erb" ), {:shorthand=>true, :source_file=>"doc/usage.erb"}.merge!(:continue_result => true)).render(nil, 91107170); _erbout << "\n"
_erbout << "\n"
::Ember::Template.load_file(( "example.erb"), {:shorthand=>true, :source_file=>"doc/usage.erb"}.merge!(:continue_result => true)).render(nil, 91107170); _erbout << "\n"
; _erbout.join)

And renders as:

This is an eRuby template.  Notice that eRuby directives do take effect here!

This is an eRuby template.  Notice that eRuby directives do take effect here!

Example 10. Dynamic template evaluation

<%~ "%= 2 + 2" %>

%~ "%= 2 + 2"

With {:shorthand=>true}, this template compiles into:

(_erbout = []; ::Ember::Template.new(( "%= 2 + 2" ), {:shorthand=>true}.merge!(:continue_result => true)).render(nil, 91046284); _erbout << "\n"
_erbout << "\n"
::Ember::Template.new(( "%= 2 + 2"), {:shorthand=>true}.merge!(:continue_result => true)).render(nil, 91046284); _erbout << "\n"
; _erbout.join)

And renders as:

4

4

Resource	Origin	License
	Tango Icon Theme © 2005 Tango Desktop Project	Creative Commons Attribution-ShareAlike 2.5 License Agreement
	MediaWiki Monobook Skin © 2007 MediaWiki contributors	GNU General Public License, version 2

eRuby template processor

Suraj N. Kurapati

03 October 2009

Contents

Examples

Document

Chapter 1
Introduction

1.1 Features

1.2 Etymology

1.3 License

Chapter 2
Setup

2.1 Requirements

2.2 Installation

2.3 Version numbers

Chapter 3
Usage

3.1 Command-line interface

3.2 Ruby library interface

3.3 eRuby template directives

3.3.1 Operations

Chapter 4
History

4.1 Version 0.0.1 (2009-10-03)

4.2 Version 0.0.0 (2009-02-13)

Ember 0.0.1

eRuby template processor

Suraj N. Kurapati

03 October 2009

Contents

Examples

Document

Chapter 1 Introduction

1.1 Features

1.2 Etymology

1.3 License

1.4 Related works

Chapter 2 Setup

2.1 Requirements

2.2 Installation

2.3 Version numbers

Chapter 3 Usage

3.1 Command-line interface

3.2 Ruby library interface

3.3 eRuby template directives

3.3.1 Operations

Chapter 4 History

4.1 Version 0.0.1 (2009-10-03)

4.2 Version 0.0.0 (2009-02-13)

Chapter 1
Introduction

Chapter 2
Setup

Chapter 3
Usage

Chapter 4
History