ember 0.0.1 → 0.1.0

data/HISTORY

@@ -0,0 +1,79 @@
+%#                                                                          #%
+%#             You can read this document in its full glory by              #%
+%#          opening ./doc/index.html in your favorite Web browser.          #%
+%#                                                                          #%
+
+%#----------------------------------------------------------------------------
+%| section "Version 0.1.0 (2010-04-03)"
+%#----------------------------------------------------------------------------
+
+  This release improves the handling of eRuby comment directives, fixes a bug
+  in the `<%% end %>` inference logic, and performs some minor housekeeping.
+
+  %#--------------------------------------------------------------------------
+  %| paragraph "New features"
+  %#--------------------------------------------------------------------------
+
+    * Single-line comment directives are now ignored (treated like no-ops)
+      in input templates.  This allows us to surround eRuby block directives
+      with section separators made from single-line comment directives:
+
+          %%|some_block_directive
+
+            Inside some_block_directive.
+
+          %%#-----------------------------------------------------------------
+
+            Still inside some_block_directive!
+
+            %%#---------------------------------------------------------------
+            %%| nested_block_directive
+            %%#---------------------------------------------------------------
+
+              Inside nested_block_directive.
+
+  %#--------------------------------------------------------------------------
+  %| paragraph "Bug fixes"
+  %#--------------------------------------------------------------------------
+
+    * `<%% end %>` inference did not work for blocks
+      beginning with `def`, `class`, and `module` keywords.
+
+  %#--------------------------------------------------------------------------
+  %| paragraph "Housekeeping"
+  %#--------------------------------------------------------------------------
+
+    * Upgrade to Inochi 2.0.0-rc3.  This project no longer
+      depends on the "inochi" or "trollop" gems at runtime.
+
+%#----------------------------------------------------------------------------
+%| section "Version 0.0.1 (2009-10-03)"
+%#----------------------------------------------------------------------------
+
+  This release improves Ruby 1.9 support and revises the user manual.
+
+  %#--------------------------------------------------------------------------
+  %| paragraph "Bug fixes"
+  %#--------------------------------------------------------------------------
+
+    * Nested templates could not access parent's binding in Ruby 1.9
+
+  %#--------------------------------------------------------------------------
+  %| paragraph "Housekeeping"
+  %#--------------------------------------------------------------------------
+
+    * Use simpler Copyright reminder at the top of every file.
+
+    * Rename internal `Program` class' methods to be self-documenting.
+
+    * Open source is for fun, so [be nice][1]: speak
+      of "related works" instead of "competitors".
+
+    [1]: http://loiclemeur.com/english/2009/03/never-criticize-your-competitors.html
+
+%#----------------------------------------------------------------------------
+%| section "Version 0.0.0 (2009-02-13)"
+%#----------------------------------------------------------------------------
+
+  This is the first public release of Ember.  Enjoy!
+

data/INSTALL

@@ -0,0 +1,31 @@
+%#                                                                          #%
+%#             You can read this document in its full glory by              #%
+%#          opening ./doc/index.html in your favorite Web browser.          #%
+%#                                                                          #%
+
+%#----------------------------------------------------------------------------
+%| section "Prerequisites"
+%#----------------------------------------------------------------------------
+
+  * [Ruby](http://ruby-lang.org) 1.8.6 or newer.
+
+  * [RubyGems](http://rubygems.org) 1.3.6 or newer.
+
+%#----------------------------------------------------------------------------
+%| section "Installing"
+%#----------------------------------------------------------------------------
+
+  %|command! "gem install ember"
+
+%#----------------------------------------------------------------------------
+%| section "Upgrading"
+%#----------------------------------------------------------------------------
+
+  %|command! "gem update ember"
+
+%#----------------------------------------------------------------------------
+%| section "Uninstalling"
+%#----------------------------------------------------------------------------
+
+  %|command! "gem uninstall ember"
+

data/MANUAL

@@ -0,0 +1,25 @@
+%#                                                                          #%
+%#             You can read this document in its full glory by              #%
+%#          opening ./doc/index.html in your favorite Web browser.          #%
+%#                                                                          #%
+
+% api_reference_url = 'api/index.html'
+% source_code_tool  = '[Git](http://git-scm.com)'
+% source_code_url   = 'http://github.com/sunaku/ember'
+% issue_tracker_url = 'http://github.com/sunaku/ember/issues'
+
+%|part "Welcome"
+  %+ "README"
+
+%|part "Setup"
+  %+ "INSTALL"
+
+%|part "Theory"
+  %+ "THEORY"
+
+%|part "Usage"
+  %+ "USAGE"
+
+%|part "History"
+  %|project_history
+    %+ "HISTORY"

data/README

@@ -0,0 +1,54 @@
+%#                                                                          #%
+%#             You can read this document in its full glory by              #%
+%#          opening ./doc/index.html in your favorite Web browser.          #%
+%#                                                                          #%
+
+%#----------------------------------------------------------------------------
+%| project_summary
+%#----------------------------------------------------------------------------
+
+  Ember (*EMBE*dded *R*uby) is an [eRuby template][1] processor that enables
+  debugging, reduces markup, and improves composability of eRuby templates.
+
+  * It reports correct line numbers in error message stack traces.
+  * It can infer <tt><%% end %></tt> based on indentation.
+  * It can unindent block content hierarchically.
+  * It completely silences code-only eRuby directives.
+  * It is implemented in <%= `sloccount lib`[/^\d+/] %> lines of pure Ruby.
+
+  [1]: http://en.wikipedia.org/wiki/ERuby
+
+%#----------------------------------------------------------------------------
+%| section "Resources"
+%#----------------------------------------------------------------------------
+
+  * <%= xref "History", "What's new?" %> ---
+    release notes and project history.
+
+  * [Issue tracker](<%= issue_tracker_url %>) ---
+    report bugs, request features, or ask for help.
+
+  * [Source code](<%= source_code_url %>) ---
+    browse online or obtain using <%= source_code_tool %>
+
+  * [API reference](<%= api_reference_url %>) ---
+    documentation for source code.
+
+  * [Project home](<%= Ember::WEBSITE %>) ---
+    the official project home page.
+
+%#----------------------------------------------------------------------------
+%| section "License"
+%#----------------------------------------------------------------------------
+
+  %# See the file named "LICENSE" for details.
+  %< "LICENSE"
+
+%#----------------------------------------------------------------------------
+%| section "Related works"
+%#----------------------------------------------------------------------------
+
+  * [ERB](http://www.ruby-doc.org/stdlib/libdoc/erb/rdoc/)
+  * [Erubis](http://www.kuwata-lab.com/erubis/)
+  * [eruby](http://modruby.net/en/)
+

data/THEORY

@@ -0,0 +1,151 @@
+%#----------------------------------------------------------------------------
+%| section "Directives"
+%#----------------------------------------------------------------------------
+
+  eRuby templates are plain-text documents that contain special processing
+  instructions known as **directives**, which may be expressed using either
+  **standard** or **shorthand** notation:
+
+  %|table
+    %|thead
+      %|tr
+        %|th
+          Notation
+        %|th
+          Directive
+        %|th
+          Head
+        %|th
+          Operation
+        %|th
+          Body
+        %|th
+          Tail
+    %|tbody
+      %|tr
+        %|td
+          Standard
+        %|td
+          <%%XY%>
+        %|td
+          <%%
+        %|td
+          X
+        %|td
+          Y
+        %|td
+          %%>
+      %|tr
+        %|td
+          Shorthand
+        %|td
+          %%XY
+        %|td
+          %%
+        %|td
+          X
+        %|td
+          Y
+        %|td
+
+  In standard notation, the directive is composed of a head, <%= xref \
+  "Operations", "an operation" %>, a body, and a tail.  In addition, the
+  directive may appear anywhere in the text.
+
+  In shorthand notation, the directive is composed of a head, <%= xref \
+  "Operations", "an operation" %> and a body.  However, the directive may only
+  appear in the text if it occupies an entire line (arbitrary amounts of
+  leading whitespace are permitted).
+
+  In any case, directives are atomic constructs; they cannot be nested.
+
+%#--------------------------------------------------------------------------
+%| section "Operations"
+%#--------------------------------------------------------------------------
+
+  The first character that follows the head of a directive is known as an
+  **operation**.  It prescribes how the directive should be processed:
+
+  %|table
+    %|thead
+      %|tr
+        %|th
+          Operation
+        %|th
+          Effect
+        %|th
+          Example
+    %|tbody
+      %|tr
+        %|td
+          `<%= Ember::Template::OPERATION_COMMENT_LINE %>`
+        %|td
+          The entire directive is omitted from the output.
+        %|td
+          %= xref "Comment directives"
+      %|tr
+        %|td
+          `<%= Ember::Template::OPERATION_EVAL_EXPRESSION %>`
+        %|td
+          The body of the directive is evaluated as Ruby code, and the
+          result of this evaluation is inserted into the output.
+        %|td
+          %= xref "Vocal directives"
+      %|tr
+        %|td
+          `<%= Ember::Template::OPERATION_EVAL_TEMPLATE_STRING %>`
+        %|td
+          The body of the directive is evaluated as an eRuby template, and
+          the result of this evaluation is inserted into the output.
+        %|td
+          %= xref "Dynamic template evaluation"
+      %|tr
+        %|td
+          `<%= Ember::Template::OPERATION_EVAL_TEMPLATE_FILE %>`
+        %|td
+          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.
+        %|td
+          %= xref "Template file inclusion"
+      %|tr
+        %|td
+          `<%= Ember::Template::OPERATION_INSERT_PLAIN_FILE %>`
+        %|td
+          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.
+        %|td
+          %= xref "Raw file inclusion"
+      %|tr
+        %|td
+          `<%= Ember::Template::OPERATION_BEGIN_LAMBDA %>`
+        %|td
+          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.
+        %|td
+          %= xref "Block directives"
+      %|tr
+        %|td
+          `%`
+        %|td
+          One "%" character is omitted from the head of the directive and
+          the entire directive is inserted into the output.
+        %|td
+          %= xref "Escaped directives"
+      %|tr
+        %|td
+          (none of the above)
+        %|td
+          The body of the directive is evaluated as Ruby code, but the
+          result of this evaluation *is not* inserted into the output.
+        %|td
+          %= xref "Silent directives"
+

data/USAGE

@@ -0,0 +1,250 @@
+%#                                                                          #%
+%#             You can read this document in its full glory by              #%
+%#          opening ./doc/index.html in your favorite Web browser.          #%
+%#                                                                          #%
+
+%#----------------------------------------------------------------------------
+%| section "Shell command"
+%#----------------------------------------------------------------------------
+
+  %|command! "ember --help" do |node|
+    %|text
+      %= verbatim `ruby bin/#{node.title}`
+
+%#----------------------------------------------------------------------------
+%| section "Ruby library"
+%#----------------------------------------------------------------------------
+
+  Begin by loading Ember into Ruby:
+
+  %|code
+    require 'rubygems' # only necessary if you are using Ruby 1.8
+    require 'ember'
+
+  Instantiate an Ember template processor:
+
+  %|code
+    source   = "your eRuby template here"
+    options  = { :unindent => true, :shorthand => true }
+    template = Ember::Template.new(source, options)
+
+  Inspect the Ruby program that was compiled (and is used) by the Ember
+  template processor to evaluate the eRuby template given as input:
+
+  %|code
+    puts template.program
+
+  View the result of evaluating the eRuby template:
+
+  %|code
+    puts template.render
+
+  See the [API documentation](api/index.html) for more information.
+
+  %#--------------------------------------------------------------------------
+  <%
+    standard_directive = lambda do |body|
+      '<' + '%' + body + ' %' + '>'
+    end
+
+    shorthand_directive = lambda do |body|
+      '%' + body
+    end
+  %>
+
+  %|template_example = lambda do |input, options|
+    % input = input.strip.gsub(/^ {4}/, '') << "\n" # remove indentation
+    % template = Ember::Template.new(input, options)
+
+    % text { input }
+
+    <%=
+      if options.empty?
+        "The"
+      else
+        "With `#{options.inspect}` options, the"
+      end
+    %> above template compiles into:
+
+    % code { template.program }
+
+    And renders as:
+
+    % text { template.render }
+
+  %#--------------------------------------------------------------------------
+  %| example! "An empty template"
+  %#--------------------------------------------------------------------------
+
+    Begin with an empty template:
+
+    %= template_example.call "", {}
+
+  %#--------------------------------------------------------------------------
+  %| example! "Comment directives"
+  %#--------------------------------------------------------------------------
+
+    Add comment directives:
+
+    <%=
+      template_example.call %{
+        #{standard_directive.call  '# this is a comment'}
+        #{shorthand_directive.call '# this is also a comment'}
+
+        #{standard_directive.call  "# this\nis\na\nmulti-line comment"}
+      }, :shorthand => true
+    %>
+
+  %#--------------------------------------------------------------------------
+  %| example! "Escaped directives"
+  %#--------------------------------------------------------------------------
+
+    Add escaped directives:
+
+    <%=
+      example = '% this is an escaped directive'
+
+      template_example.call %{
+        #{standard_directive.call example}
+        #{shorthand_directive.call example}
+      }, :shorthand => true
+    %>
+
+  %#--------------------------------------------------------------------------
+  %| example! "Vocal directives"
+  %#--------------------------------------------------------------------------
+
+    Add vocal directives, which produce output:
+
+    <%=
+      template_example.call %{
+        #{standard_directive.call   '= "hello"'}
+        #{shorthand_directive.call  '= "world"'}
+
+      }, :shorthand => true
+    %>
+
+  %#--------------------------------------------------------------------------
+  %| example! "Silent directives"
+  %#--------------------------------------------------------------------------
+
+    Add silent directives, which do not produce output:
+
+    <%=
+      template_example.call %{
+        #{standard_directive.call   ' a = "hello"'}
+        #{shorthand_directive.call  ' b = "world"'}
+
+        #{standard_directive.call   '= a'}
+        #{shorthand_directive.call  '= b'}
+
+      }, :shorthand => true
+    %>
+
+  %#--------------------------------------------------------------------------
+  %| example! "Block directives"
+  %#--------------------------------------------------------------------------
+
+    Add some Ruby blocks:
+
+    <%=
+      template_example.call %{
+        #{shorthand_directive.call    ' words = %w[hello world]'}
+
+        #{standard_directive.call     ' words.each do |w|'}
+          #{standard_directive.call   '= w'}
+        #{standard_directive.call     ' end'}
+
+        #{shorthand_directive.call    ' words.each do |w|'}
+          #{shorthand_directive.call  '= w'}
+        #{shorthand_directive.call    ' end'}
+
+        #{shorthand_directive.call    '|words.each |w|'}
+          #{shorthand_directive.call  '= w'}
+        #{shorthand_directive.call    ' end'}
+
+      }, :shorthand => true
+    %>
+
+  %#--------------------------------------------------------------------------
+  %| example! "Infer block endings"
+  %#--------------------------------------------------------------------------
+
+    Omit <tt><%= standard_directive.call ' end' %></tt> directives from the
+    template:
+
+    <%=
+      template_example.call %{
+        #{shorthand_directive.call    ' words = %w[hello world]'}
+
+        #{standard_directive.call     ' words.each do |w|'}
+          #{standard_directive.call   '= w'}
+
+        #{shorthand_directive.call    ' words.each do |w|'}
+          #{shorthand_directive.call  '= w'}
+
+        #{shorthand_directive.call    '|words.each |w|'}
+          #{shorthand_directive.call  '= w'}
+
+      }, :shorthand => true, :infer_end => true
+    %>
+
+  %#--------------------------------------------------------------------------
+  %| example! "Raw file inclusion"
+  %#--------------------------------------------------------------------------
+
+    When <tt>doc/example.txt</tt> contains:
+
+    %|text
+      %< "doc/example.txt"
+
+    And the eRuby template is:
+
+    <%=
+      example = '< "doc/example.txt"'
+
+      template_example.call %{
+        #{standard_directive.call example}
+
+        #{shorthand_directive.call example}
+
+      }, :shorthand => true, :source_file => __FILE__
+    %>
+
+  %#--------------------------------------------------------------------------
+  %| example! "Template file inclusion"
+  %#--------------------------------------------------------------------------
+
+    When <tt>doc/example.erb</tt> contains:
+
+    %|code :rhtml
+      %< "doc/example.erb"
+
+    And the eRuby template is:
+
+    <%=
+      example = '+ "doc/example.erb"'
+
+      template_example.call %{
+        #{standard_directive.call example}
+
+        #{shorthand_directive.call example}
+
+      }, :shorthand => true, :source_file => __FILE__
+    %>
+
+  %#--------------------------------------------------------------------------
+  %| example! "Dynamic template evaluation"
+  %#--------------------------------------------------------------------------
+
+    <%=
+      example = %{~ "#{shorthand_directive.call '= 2 + 2'}"}
+
+      template_example.call %{
+        #{standard_directive.call example}
+
+        #{shorthand_directive.call example}
+
+      }, :shorthand => true
+    %>
+