Stencil 0.1 → 0.1.1

data/doc/README

@@ -1,2 +1,49 @@
-== This is a Really Cool Ruby Thing
-=== ( That deserves better documentation than this. )
+== Stencil
+=== Free text templating system
+
+Stencil is a templating system designed with a free text target in mind, and built around encouraging a separation of concerns.  To that end, Stencil templates don't embed arbitrary Ruby, don't assume their output will be HTML, CSS or XML, and don't use any Ruby variable as a source.
+
+Admittedly, the goals and design of Stencil are probably idiosyncratic, but
+they do reflect needs I had, and I figured someone else might want something
+similar.
+
+Stencil is structured around data supplied in the form of hashes and arrays.
+Data is referenced using a reasonably compact (even terse) path.  Recognizing
+that usually, data comes from disparate sources, there's a module that can be
+included into an object to smoothly extract a view or subview suitable for
+rendering.
+
+Once views have been extracted, there's an RSpec matcher 'has_subview' that
+allows the details of a view to be tested easily.
+
+Stencils directives are defined using a reasonably straightforward sub-classing
+design, and it's my experience that it's reasonably painless to add new
+directives.
+
+Stencil also provides dynamic templates, that allow for output like JSON or XML from hashes and arrays.  They can be applied within a normal template.
+
+Stencil provides a number of pretty straightforward directives:
+
+* [;= <path>;] will interpolate the data referred to by the path.  Methods on the data can be called, but by design, Ruby constants and Kernel methods aren't available.  
+* [;if <condition>;] works similarly to [;=;]
+* [;each <path> <as>;] for simple loops
+* [;with <path>;] a common use case: make sure that a value exists, and assign it to the current context
+* [;/;] or [;end;] terminates if, each and with.  For convenience [;/ 3;] will dig out of 3 levels of nesting.
+* [;apply <kind>;] Apply a dynamic template
+* [;include <path>;] Because templates should be able to include each other.
+
+Some oddball directives, available by inclusion only,
+* [;indent <depth>;] (depth can come from a reference) - lets you indent text, per line
+* [;wrap <width>;] Allow lines to be wrapped to a particular size.
+* [;fcolor "red";] Terminal escapes to change text color
+* [;bcolor "blue";] Terminal escapes for the background color
+* [;bold;] [;inverse;] [;underline;] All terminal escapes
+* [;nl;] Is the same as "\n", just a little prettier.
+
+Stencil allows whitespace between the directive delimiters ([; ;]) and the
+directives themselves, which means that templates can be laid out more readably
+without wrecking the layout of the final output.  (e.g. [;      if true    ;])
+
+The directive delimiters were chosen first because they don't collide with any output I could think of, are easy to parse, an are quick to type.  The end-of-block code: [;/;] is typed all without modifier (no shift) with one hand.  It might sound weird, but I've come to really like it.
+
+Templates can be defined in strings, or loaded from a path.

data/doc/Specifications

@@ -1,6 +1,7 @@
 
 Stencil::Template parsing an invalid template
 - should indicate the line and column of the error
+- should fail if a path reference is missing (PENDING: TODO)
 
 Stencil::RenderError
 - should has a useful string representation
@@ -77,7 +78,13 @@ Stencil::View
 Stencil::TermStyleDirective
 - should change foreground color
 - should nest stylings
+- should style loops properly
 
-Finished in 0.054271 seconds
+Pending:
 
-35 examples, 0 failures
+Stencil::Template parsing an invalid template should fail if a path reference is missing (TODO)
+./spec/error_handling.rb:17
+
+Finished in 0.26494 seconds
+
+37 examples, 0 failures, 1 pending

data/lib/stencil/directives/term-style.rb

@@ -1,6 +1,6 @@
 module Stencil
-  module Styles
-    Foreground = { 
+  Styles = {
+    :foreground => { 
       'black'   => 30,
       'red'     => 31, 
       'green'   => 32, 
@@ -10,30 +10,52 @@ module Stencil
       'cyan'    => 36,
       'white'   => 37,
       'default' => 39
+    },
+
+    :bold => {
+      'set' => 1,
+      'default' => 22
+    },
+
+    :underline => {
+      'set' => 4,
+      'default' => 24
+    },
+
+    :blink => {
+      'set' => 5,
+      'default' => 25
+    },
+
+    :inverse => {
+      'set' => 7,
+      'default' => 27
     }
+  }
 
-    Background = {}
+  Styles[:background] = {}
 
-    Foreground.each() do |name, value|
-      Background[name] = value + 10
+  Styles[:foreground].each() do |name, value|
+    Styles[:background][name] = value + 10
+  end
+
+
+  class Template::State
+    def terminal_style
+      @style ||= Styles.keys.inject({}){|style, key|
+        style.merge({key => 'default'})
+      }
+      return @style
     end
 
-    Extra = {
-      'clear'     => 0, 
-      'bold'      => 1,
-      'unbold'      => 22,
-      'underline' => 4,
-      'ununderline' => 24,
-      'blink'     => 5,
-      'unblink'     => 25,
-      'inverse'   => 7,
-      'uninverse'   => 27
-    }
+    def terminal_style=(style)
+      @style = style
+    end
   end
 
   class TermStyleDirective < Block
     def initialize(location, string)
-      @previous_style = nil
+      @old_style = nil
       @style = nil
       super
     end
@@ -46,29 +68,36 @@ module Stencil
       end
     end
 
-    def escape_codes(options)
-      return "\e[0m" if options.empty?
-      return code_for(Styles::Foreground, options[:foreground]) + 
-        code_for(Styles::Background, options[:background]) + 
-        code_for(Styles::Extra, options[:extra])
-    end
+    def escape_codes(new_options, old_options)
+      return "\e[0m" if new_options.empty?
+      options = new_options.dup
+      old_options.each_pair do |key, value|
+        if options[key] == value
+          options.delete(key)
+        end
+      end
 
-    def parsed(stack)
-      reverse = Enumerable::Enumerator::new(stack, :reverse_each)
-      @previous_style = reverse.find {|dir| TermStyleDirective === dir}
-      super
+      options.keys.inject("") do |codes, key|
+        codes + code_for(Styles[key], options[key])
+      end
     end
 
     def old_style(state)
-      @old_style ||= @previous_style.style(state) rescue {:foreground => 'default', :background => 'default'}
     end
 
     def style(state)
-      @style ||= update_style(old_style(state), state.data)
     end
 
     def render(state)
-      [escape_codes(style(state))] + super + [escape_codes(old_style(state))]
+      @old_style = state.terminal_style
+      @style = update_style(@old_style, state.data)
+      state.terminal_style = @style
+      result = 
+        [escape_codes(@style, @old_style)] + 
+        super + 
+        [escape_codes(@old_style, @style)]
+      state.terminal_style = @old_style
+      result
     end
 
     def update_style(style, state)
@@ -87,41 +116,34 @@ module Stencil
     end
   end
 
+  class BackgroundColor < ForegroundColor
+    register :bcolor
+    def update_style(style, state)
+      return style.merge(:background => interpret(@color_text, state))
+    end
+  end
+
   class Bold < TermStyleDirective
     register :bold
 
-    def render(state)
-      [code_for(Styles::Extra, 'bold')] + 
-        super + 
-        [code_for(Styles::Extra, 'unbold')]
+    def update_style(style, state)
+      return style.merge({:bold => 'set'})
     end
   end
 
   class Underline < TermStyleDirective
     register :underline
 
-    def render(state)
-      [code_for(Styles::Extra, 'underline')] + 
-        super + 
-        [code_for(Styles::Extra, 'ununderline')]
+    def update_style(style, state)
+      return style.merge({:underline => 'set'})
     end
   end
 
   class Inverse < TermStyleDirective
     register :inverse
 
-
-    def render(state)
-      [code_for(Styles::Extra, 'inverse')] + 
-        super + 
-        [code_for(Styles::Extra, 'uninverse')]
-    end
-  end
-
-  class BackgroundColor < ForegroundColor
-    register :bcolor
     def update_style(style, state)
-      return style.merge(:background => interpret(@color_text, state))
+      return style.merge({:inverse => 'set'})
     end
   end
 end

data/lib/stencil/template.rb

@@ -247,7 +247,8 @@ module Stencil
 
         def render(data)
           data_context = DataContext.new(data)
-          render_raw(data_context).compact.join("")
+          raw_results = render_raw(data_context)
+          return raw_results.compact.join("")
         end
 
         def render_raw(data)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: Stencil
 version: !ruby/object:Gem::Version 
-  version: "0.1"
+  version: 0.1.1
 platform: ruby
 authors: 
 - Judson Lester
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-12-28 00:00:00 -08:00
+date: 2010-01-04 00:00:00 -08:00
 default_executable: 
 dependencies: []
 
@@ -44,7 +44,7 @@ rdoc_options:
 - --main
 - doc/README
 - --title
-- Stencil-0.1 RDoc
+- Stencil-0.1.1 RDoc
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement