macros4cuke 0.2.20 → 0.2.21

data/CHANGELOG.md

@@ -1,7 +1,15 @@
-## 0.2.20 / 2013-05-06
+## 0.2.21 / 2013-05-08
+* [NEW] Added new class `Templating::UnaryElement`.
+* [CHANGE] Made `Placeholder` class inherit from `UnaryElement`.
+* [NEW] Added new class `Templating::Section`, a subclass of `UnaryElement`.
+* [NEW] Added new class `Templating::ConditionalSection, a subclass of `Section`.
+* [CHANGE] Method Engine#parse_tag modified in prevision of conditional tags.
+* [NEW] File `section_spec.rb`: Added a RSpec to test the Conditional class.
+
+## 0.2.20 / 2013-05-07
 * [NEW] Added `examples` folder with a first example of an internationalized customisation of __Macros4Cuke__.
 
-## 0.2.19 / 2013-05-06
+## 0.2.19 / 2013-05-07
 * [CHANGE] Added validation of macro argument names in new `Engine::parse_tag` method.
 * [CHANGE] InvalidCharError exception added.
 * [CHANGE] File `engine_spec.rb`: Added one RSpec example for an invalid argument name.

data/lib/macros4cuke/constants.rb

@@ -3,7 +3,7 @@
 
 module Macros4Cuke # Module used as a namespace
 	# The version number of the gem.
-	Version = '0.2.20'
+	Version = '0.2.21'
 
   # Brief description of the gem.
   Description = "Macros for Cucumber"

data/lib/macros4cuke/templating/engine.rb

@@ -37,10 +37,22 @@ end # class
 
 
 # Class used internally by the template engine.  
-# Represents a named placeholder in a template, that is, 
-# a name placed between <..> in the template.  
-# At rendition, a placeholder is replaced by the text value that is associated with it. 
-class Placeholder
+# Represents an end of line that must be rendered as such.
+class EOLine
+public
+  # Render an end of line.
+  # This method has the same signature as the {Engine#render} method.
+  # @return [String] An end of line marker. Its exact value is OS-dependent.
+  def render(aContextObject, theLocals)
+    return "\n"
+  end
+end # class
+
+
+# Base class used internally by the template engine.  
+# The generalization of any element from a template that has one variable
+# whose actual value influences the rendition.
+class UnaryElement
   # The name of the placeholder/variable.
   attr_reader(:name)
   
@@ -49,16 +61,35 @@ class Placeholder
     @name = aVarName
   end
 
+protected
+  # This method has the same signature as the {Engine#render} method.
+  # @return [Object] The actual value from the locals or context that is assigned to the variable.
+  def retrieve_value_from(aContextObject, theLocals)
+    actual_value = theLocals[name]
+    if actual_value.nil? && aContextObject.respond_to?(name.to_sym)
+      actual_value = aContextObject.send(name.to_sym)
+    end
+    
+    return actual_value
+  end  
+  
+end # class
+
+
+
+# Class used internally by the template engine.  
+# Represents a named placeholder in a template, that is, 
+# a name placed between <..> in the template.  
+# At rendition, a placeholder is replaced by the text value that is associated with it. 
+class Placeholder < UnaryElement
+
 public
   # Render the placeholder given the passed arguments.
   # This method has the same signature as the {Engine#render} method.
   # @return [String] The text value assigned to the placeholder. 
   #   Returns an empty string when no value is assigned to the placeholder.
   def render(aContextObject, theLocals)
-    actual_value = theLocals[name]
-    if actual_value.nil? && aContextObject.respond_to?(name.to_sym)
-      actual_value = aContextObject.send(name.to_sym)
-    end
+    actual_value = retrieve_value_from(aContextObject, theLocals)
     
     result = case actual_value
       when NilClass
@@ -80,19 +111,78 @@ public
 end # class
 
 
-# Class used internally by the template engine.  
-# Represents an end of line that must be rendered as such.
-class EOLine
+# Base class used internally by the template engine.  
+# Represents a section in a template, that is, 
+# a set of template elements for which its rendition depends
+# on the value of a variable.
+class Section  < UnaryElement
+  # The child elements of the section
+  attr_reader(:children)
+  
+  # @param aVarName [String] The name of the placeholder from a template.
+  def initialize(aVarName)
+    super(aVarName)
+    @children = []
+  end
+
 public
-  # Render an end of line.
+  # Add a child element as member of the section
+  def add_child(aChild)
+    children << aChild
+  end
+
+protected
+  # Render the placeholder given the passed arguments.
   # This method has the same signature as the {Engine#render} method.
-  # @return [String] An end of line marker. Its exact value is OS-dependent.
+  # @return [String] The text value assigned to the placeholder. 
+  #   Returns an empty string when no value is assigned to the placeholder.
   def render(aContextObject, theLocals)
-    return "\n"
+    raise NotImplementedError, "Method Section::#{_method_} must be implemented in subclass(es)."
+  end    
+
+end # class
+
+
+# Represents a section in a template, that is, 
+# a set of template elements for which its rendition depends
+# on the (in)existence of an actual value bound to the variable name.
+class ConditionalSection < Section
+  # A boolean that indicates whether the rendition condition is the existence of a value for the variable (true)
+  # or its inexistence (false).
+  attr_reader(:existence)
+
+  # @param aVarName [String] The name of the placeholder from a template.
+  # @param renderWhenExisting [boolean] When true, render the children elements if a value exists for the variable.  
+  def initialize(aVarName, renderWhenExisting = true)
+    super(aVarName)
+    @existence = renderWhenExisting
   end
+  
+public
+  # Render the placeholder given the passed arguments.
+  # This method has the same signature as the {Engine#render} method.
+  # @return [String] The text value assigned to the placeholder. 
+  #   Returns an empty string when no value is assigned to the placeholder.
+  def render(aContextObject, theLocals)
+    actual_value = retrieve_value_from(aContextObject, theLocals)
+    if (!actual_value.nil? && existence) || (actual_value.nil? && !existence)
+      # Let render the children
+      result = children.each_with_object('') do |a_child, sub_result|
+        sub_result << a_child.render(aContextObject, theLocals)
+      end
+    else
+      result = ''
+    end
+    
+    return result
+  end   
+
 end # class
 
 
+SectionEndMarker = Struct.new(:name)
+
+
 # A very simple implementation of a templating engine.  
 # Earlier versions of Macros4Cuke relied on the logic-less Mustache template engine.  
 # But it was decided afterwards to replace it by a very simple template engine.  
@@ -101,9 +191,9 @@ end # class
 #     while Mustache use !{{...}} delimiters),  
 # - Feature files are meant to be simple, so should the template engine be. 
 class Engine
-  # The regular expression that matches any punctuation sign or delimiter that is forbidden between chevrons <...> template tags.
+  # The regular expression that matches a space, any punctuation sign or delimiter that is forbidden between chevrons <...> template tags.
   DisallowedSigns = begin 
-    forbidden =  '!"#' + "$%&'()*+,-./:;<=>?[\\]^`{|}~" # Used concatenation (+) to work around Ruby bug!
+    forbidden =  ' !"#' + "$%&'()*+,-./:;<=>?[\\]^`{|}~" # Used concatenation (+) to work around Ruby bug!
     all_escaped = [] 
     forbidden.each_char() { |ch| all_escaped << Regexp.escape(ch) }
     pattern = all_escaped.join("|")
@@ -240,11 +330,27 @@ private
   # Parse the contents of a tag entry.
   # @param aText [String] The text that is enclosed between chevrons.
   def parse_tag(aText)
-    # Disallow punctuation and delimiter signs in tags.
-    matching = DisallowedSigns.match(aText)
+    # Recognize the first character
+    if aText =~ /^[\?\/]/
+      matching = DisallowedSigns.match(aText[1..-1])
+    else
+      # Disallow punctuation and delimiter signs in tags.
+      matching = DisallowedSigns.match(aText)
+    end
     raise InvalidCharError.new(aText, matching[0]) if matching
+    
+    SectionEndMarker
+    result = case aText[0, 1]
+      when '?'
+        ConditionalSection.new(aText[1..-1], true)
+        
+      when '/'
+        SectionEndMarker.new(aText[1..-1])
+      else
+        Placeholder.new(aText)
+    end
 
-    return Placeholder.new(aText)    
+    return result
   end
  
 end # class

data/spec/macros4cuke/templating/section_spec.rb

@@ -0,0 +1,113 @@
+# encoding: utf-8 -- You should see a paragraph character: §
+# File: section_spec.rb
+
+require_relative '../../spec_helper'
+require_relative '../../../lib/macros4cuke/templating/engine'	# Load the classes under test
+
+module Macros4Cuke
+
+module Templating # Open this namespace to get rid of module qualifier prefixes
+
+
+describe ConditionalSection do
+
+  context "Creation and initialization" do
+
+    it "should be created with a variable name and a boolean" do
+      lambda { ConditionalSection.new('foobar', false) }.should_not raise_error
+      lambda { ConditionalSection.new('foobar', true) }.should_not raise_error
+    end
+
+    it "should know the name of its variable" do
+      [false, true].each do |existence|
+        instance = ConditionalSection.new('foobar', existence)
+        instance.name.should == 'foobar'
+      end
+    end
+
+    it "should know whether the rendition on existence of actual value or not" do
+      [false, true].each do |existence|
+        instance = ConditionalSection.new('foobar', existence)
+        instance.existence.should == existence
+      end
+    end
+
+    it "should have no child at start" do
+      [false, true].each do |existence|
+        instance = ConditionalSection.new('foobar', existence)
+        instance.should have(0).children
+      end
+    end
+
+  end # context
+
+  context "Provided services" do
+    # Return a list of possible child elements
+    let(:sample_children) do
+      [ StaticText.new("Hello "),
+        Placeholder.new("user"),
+        EOLine.new
+      ]
+    end
+
+    # Default instantiation rule
+    subject { ConditionalSection.new('foobar', true) }
+
+    it "should add child element(s)" do
+      sample_children.each do |a_child|
+        subject.add_child(a_child)
+      end
+
+      # Control that the addition worek as expected
+      subject.children.should == sample_children
+
+    end
+
+    it "should render its children when conditions are met" do
+      # Adding the children
+      sample_children.each { |a_child| subject.add_child(a_child) }
+
+      # Case of an existing actual
+      locals = {'user' => "joe", "foobar" => 'exists' }
+      rendered_text = subject.render(Object.new, locals)
+      expected_text = "Hello joe\n"
+      rendered_text.should == expected_text
+
+      # Case of a conditional section that should be rendering when value is non-existing.
+      instance = ConditionalSection.new('foobar', false)
+      sample_children.each { |a_child| instance.add_child(a_child) }
+
+      # Case of a non-existing actual
+      locals = {'user' => "joe" }
+      rendered_text = instance.render(Object.new, locals)
+      rendered_text.should == expected_text
+    end
+
+    it "should render noting when conditions are'nt met" do
+      # Adding the children
+      sample_children.each { |a_child| subject.add_child(a_child) }
+
+      # Case of a non-existing actual
+      locals = {'user' => "joe"}
+      rendered_text = subject.render(Object.new, locals)
+      rendered_text.should == ""
+
+      # Case of a conditional section that should be rendering when value is non-existing.
+      instance = ConditionalSection.new('foobar', false)
+      sample_children.each { |a_child| instance.add_child(a_child) }
+
+      # Case of a non-existing actual
+      locals = {'user' => "joe", "foobar" => 'exists' }
+      rendered_text = instance.render(Object.new, locals)
+      rendered_text.should == ""
+    end
+
+  end # context
+
+end # describe
+
+end # module
+
+end # module
+
+# End of file

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: macros4cuke
 version: !ruby/object:Gem::Version
-  version: 0.2.20
+  version: 0.2.21
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-07 00:00:00.000000000 Z
+date: 2013-05-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cucumber
@@ -99,6 +99,7 @@ files:
 - spec/macros4cuke/macro-step-support_spec.rb
 - spec/macros4cuke/macro-step_spec.rb
 - spec/macros4cuke/templating/engine_spec.rb
+- spec/macros4cuke/templating/section_spec.rb
 homepage: https://github.com/famished-tiger/Macros4Cuke
 licenses:
 - MIT