macros4cuke 0.3.00 → 0.3.01

data/CHANGELOG.md

@@ -1,3 +1,15 @@
+## 0.3.01 / 2013-05-10
+* [NEW] features/ folder: added `demo06.feature` file showing the new conditional section.
+* [NEW] File `placeholder_spec.rb`: Added a RSpec file to test the Placeholder class.
+* [CHANGE] File `macro_steps.rb` Macro-step definition accepts the '*' Gherkin keyword.
+* [CHANGE] Method `Engine#compile_sction` completed and tested to support section elements.
+* [CHANGE] Method `Section#variables` expanded to support section elements.
+* [CHANGE] Method `Engine#variables` expanded to support section elements.
+* [CHANGE] Method `Engine#compile_line` added two formatting rules. 
+* [CHANGE] Method `MacroStep#scan_arguments` now un-escape the \" sequence into plain quote.
+* [CHANGE] examples/ folder expanded and reorganized
+* [FIX] Method `Section#render` fixed typo in call to __method__
+
 ## 0.3.00 / 2013-05-09 Version number bumped
 * [CHANGE] Class `Templating::Engine` can handle conditional tags (TODO: document).
 * [CHANGE] File `engine_spec.rb`: Added a RSpec examples to test the conditional tags.

data/examples/demo/cucumber.yml

@@ -0,0 +1,6 @@
+default: --strict -v -b  --format progress features
+html: --strict -v -b  --format html --out result.html features
+usage: --strict -v -b  --format usage --out usage.txt features
+
+
+

data/examples/demo/features/basic.feature

@@ -0,0 +1,54 @@
+# File: basic.feature
+
+Feature: Show -visually- the several ways to use macros
+  As a Cuke user
+  So that I enjoy writing scenario.
+
+
+Scenario: Definition of a simple macro-step with two arguments
+  Given I define the step "* I [travel from <origin> to <destination>]" to mean:
+  """
+  When I leave '<origin>'
+  And I arrive in <destination>
+  """
+
+Scenario: Do a simple travel
+  # Call a macro-step defined earlier
+  When I [travel from "Brussels" to "Rome"]
+  # You should see the output:
+  # I leave 'Brussels'
+  # I arrive in Rome
+  
+  
+  # Actual values can have embedded double quotes provided they are escaped.
+  When I [travel from "Tampa" to "\"Little Italy\""]
+  # You should see the output:
+  # I leave 'Tampa'
+  # I arrive in "Little Italy"  
+  
+  # Actual values MUST be present in the phrase (but they can be empty)
+  When I [travel from "" to "North Pole"]
+  # You should see the output:
+  # I leave ''
+  # I arrive in North Pole    
+
+
+
+Scenario: Defining a macro that's calling other macro-steps
+  Given I define the step "* I [travel from <origin> to <destination> and back]" to mean:
+  """
+  # The next two steps are, in fact, macro-step invokations
+  When I [travel from "<origin>" to "<destination>"]
+  When I [travel from "<destination>" to "<origin>"]
+  """
+
+Scenario: Do a travel back and forth
+    When I [travel from "Paris" to "London" and back]
+
+  # You should see the output:
+  # I leave 'Paris'
+  # I arrive in London
+  # I leave 'London'
+  # I arrive in Paris
+
+

data/examples/demo/features/step_definitions/step_defs.rb

@@ -0,0 +1,23 @@
+# encoding: utf-8
+# File: demo_steps.rb
+# A few step definitions for demo and testing purpose.
+
+When(/^I leave '(.*)'$/) do |city|
+  show "I leave #{city}"
+end
+
+
+When(/^I visit (.+)$/) do |city|
+ show "I visit #{city}"
+end
+
+
+When(/^I arrive in (.+)$/) do |city|
+  show "I arrive in #{city}"
+end
+
+When(/^I type \"([^"]*)\"$/) do |text|
+  show text
+end
+
+# End of file

data/examples/demo/features/step_definitions/use_macro_steps.rb

@@ -0,0 +1,8 @@
+# File: use_macro_steps.rb
+# Place a copy of this file in the feature/step_definitions folder of your own Cucumber-based project.
+
+# The following require will load the step definitions from Macros4Cuke.
+# This allows feature file authors to use macro steps in their Cucumber scenarios.
+require 'macros4cuke/../macro_steps'
+
+# End of file

data/examples/demo/features/support/env.rb

@@ -0,0 +1,38 @@
+# encoding: utf-8	You should see a paragraph character: §
+# File: env.rb
+
+
+module DemoMacros4Cuke  # Use the module as a namespace
+
+ 
+# Class created just for testing and demonstration purposes.
+# Its instance, will record the output emitted by the steps.
+class TracingWorld
+  # Will contain the text emitted by the steps
+  attr_reader(:trace_steps)
+  
+  
+  def initialize()
+    # Constructor  
+    @trace_steps = []
+  end
+  
+public
+  # Write the given text to the error console
+  def show(someText)
+    # Replace every \" sequence by genuine "
+    unescaped = someText.gsub(/\\"/, '"')
+    $stderr.puts(unescaped)
+  end
+
+  
+end # class
+
+end # module
+
+# For testing purpose we override the default Cucumber behaviour
+# making our world object an instance of the TracingWorld class
+World { DemoMacros4Cuke::TracingWorld.new }
+
+
+# End of file

data/examples/demo/features/support/macro_support.rb

@@ -0,0 +1,16 @@
+# encoding: utf-8	You should see a paragraph character: §
+# File: macro_support.rb
+# Purpose: Add the support for macros in Cucumber.
+# This file is meant to be put next to the 'env.rb' file of your Cucumeber project.
+
+
+# Macros4Cuke step one: Load modules and classes from the gem.
+require 'macros4cuke'
+
+
+# Macros4Cuke step two: extend the world object with the mix-in module
+# that adds the support for macros in Cucumber.
+World(Macros4Cuke::MacroStepSupport)
+
+
+# End of file

data/{features/travelling-demo.feature → examples/demo/features/table.feature}

@@ -1,51 +1,14 @@
 # File: travelling-demo.feature
 
-Feature: Show -visually- the several ways to use macros
+
+Feature: Show how to define & use macro-steps with data table
   As a Cuke user
   So that I enjoy writing scenario.
 
 
-Scenario: Definition of a simple macro-step with two arguments
-  Given I define the step "When I [travel from <origin> to <destination>]" to mean:
-  """
-  When I leave <origin>
-  And I arrive in <destination>
-  """
-
-Scenario: Do a simple travel
-  # Call a macro-step defined earlier
-  When I [travel from "Brussels" to "Rome"]
-
-  # You should see the output:
-  # I leave Brussels
-  # I arrive in Rome
-  
-  # Actual values can have embedded double quotes provided they are escaped.
-  When I [travel from "Tampa" to "\"Little Italy\""]  
-  
-
-
-
-Scenario: Defining a macro calling other macro(s)
-  Given I define the step "When I [travel from <origin> to <destination> and back]" to mean:
-  """
-  # The next two steps are, in fact, macro-step invokations
-  When I [travel from "<origin>" to "<destination>"]
-  When I [travel from "<destination>" to "<origin>"]
-  """
-
-Scenario: Do a travel back and forth
-    When I [travel from "Paris" to "London" and back]
-
-  # You should see the output:
-  # I leave Paris
-  # I arrive in London
-  # I leave London
-  # I arrive in Paris
-
-
 Scenario: Defining a macro that requires a data table
-  Given I define the step "When I [fill in the form with]:" to mean:
+  # There is a colon : just after the phrase closing ']'. A data table must be used.
+  Given I define the step "* I [fill in the form with]:" to mean:
   """
   When I type "<firstname>"
   And I type "<lastname>"
@@ -92,7 +55,7 @@ Scenario: Using a macro-step with a data table
   
   
 Scenario: Demonstrate that it is possible to use a sub-step with a data table
-  Given I define the step "When I [fill in, as a Londonian, the form with]:" to mean:
+  Given I define the step "* I [fill in, as a Londonian, the form with]:" to mean:
   """
   When I [fill in the form with]:
   |firstname| <firstname>|

data/features/demo01.feature

@@ -9,7 +9,7 @@ Scenario: Definition of a simple macro-step
   # The next step creates a macro(-step)
   # The syntax of the new macro-step is specified between double quotes.
   # The steps to execute when the macro is used/invoked are listed in the multiline triple quotes arguments.
-  Given I define the step "When I [log in]" to mean:
+  Given I define the step "* I [log in]" to mean:
   """
   Given I landed in the homepage
   When I click "Sign in"
@@ -30,4 +30,4 @@ Invoked step: ... I click "Sign in"
 Invoked step: ... I fill in "Username" with "johndoe"
 Invoked step: ... I fill in "Password" with "unguessable"
 Invoked step: ... I click "Submit"
-  """
+  """

data/features/demo02.feature

@@ -10,7 +10,7 @@ Scenario: Creating a basic scenario with one argument
   # The syntax of the new macro-step is specified between the double quotes.
   # The steps to execute when the macro is used/invoked are listed in the multiline triple quotes arguments.
   # The macro argument is put between chevrons <...>.
-  Given I define the step "When I [log in\[\] as <userid>]" to mean:
+  Given I define the step "* I [log in\[\] as <userid>]" to mean:
   """
   Given I landed in the homepage
   When I click "Sign in"
@@ -31,4 +31,4 @@ Invoked step: ... I click "Sign in"
 Invoked step: ... I fill in "Username" with "guest"
 Invoked step: ... I fill in "Password" with "unguessable"
 Invoked step: ... I click "Submit"
-  """
+  """

data/features/demo03.feature

@@ -9,7 +9,7 @@ Scenario: defining basic macro with multiple arguments
   # The next step creates a macro(-step)double quotes.
   # The steps to execute when the macro is used/invoked are listed in the multiline triple quotes arguments.
   # The macro-step arguments are put between chevrons <...>.
-  Given I define the step "When I [enter my userid <userid> and password <password>]" to mean:
+  Given I define the step "* I [enter my userid <userid> and password <password>]" to mean:
   """
   Given I landed in the homepage
   When I click "Sign in"
@@ -33,7 +33,7 @@ Invoked step: ... I click "Submit"
   """
 
 Scenario: A macro invoking another macro (YES, it's possible!)
-  Given I define the step "When I [enter my credentials]" to mean:
+  Given I define the step "* I [enter my credentials]" to mean:
   """
   # Notice that the next step is invoking the first macro above
   When I [enter my userid "guest" and password "unguessable"]
@@ -50,4 +50,4 @@ Invoked step: ... I click "Sign in"
 Invoked step: ... I fill in "Username" with "guest"
 Invoked step: ... I fill in "Password" with "unguessable"
 Invoked step: ... I click "Submit"
-  """
+  """

data/features/demo04.feature

@@ -10,7 +10,7 @@ Scenario: Defining a macro to be used with multiple arguments in a table
   # The syntax of the new macro-step is specified between double quotes.
   # The steps to execute when the macro is used/invoked are listed in the multiline triple quotes arguments.
   # The macro arguments are put between chevrons <...>.
-  Given I define the step "When I [enter my credentials as]:" to mean:
+  Given I define the step "* I [enter my credentials as]:" to mean:
   """
   Given I landed in the homepage
   When I click "Sign in"
@@ -33,4 +33,4 @@ Invoked step: ... I click "Sign in"
 Invoked step: ... I fill in "Username" with "guest"
 Invoked step: ... I fill in "Password" with "unguessable"
 Invoked step: ... I click "Submit"
-  """
+  """

data/features/demo05.feature

@@ -10,7 +10,7 @@ Scenario: Defining a macro to be used with multiple arguments in a table
   # The syntax of the new macro-step is specified between double quotes.
   # The steps to execute when the macro is used/invoked are listed in the multiline triple quotes arguments.
   # The macro arguments are put between chevrons <...>.
-  Given I define the step "When I [enter my profile as]:" to mean:
+  Given I define the step "* I [enter my profile as]:" to mean:
   """ 
   And I fill in "location" with "<location>"
   And I fill in "email" with "<email>"
@@ -34,4 +34,4 @@ Scenario: # Let's use the macro we created above
   Invoked step: ... I fill in "email" with "nobody@example.com"
   Invoked step: ... I fill in "comment" with "First comment line<br/>Second comment line<br/>Third comment line"
   Invoked step: ... I click "Save"
-  """
+  """

data/features/demo06.feature

@@ -0,0 +1,73 @@
+# File: demo06.feature
+
+Feature: Show how to define conditional substeps in a macro-step.
+  As a Cuke user
+  So that I enjoy writing scenario.
+
+
+Scenario: Defining a macro with conditional substeps
+  Given I define the step "* I [fill in the form with]:" to mean:
+  """
+  When I fill in "first_name" with "<firstname>"
+  And I fill in "last_name" with "<lastname>"
+  And I fill in "street_address" with "<street_address>"
+  And I fill in "zip" with "<postcode>"
+  And I fill in "city" with "<city>"
+  And I fill in "country" with "<country>"
+  # Let's assume that e-mail is optional
+  <?email>
+  And I fill in "email" with "<email>"
+  </email>
+  # Let's also assume that comment is optional
+<?comment>  And I fill in "comment" with "<comment>"</comment>
+  And I click "Save"
+  """
+  
+Scenario: # Let's use the macro-step WITHOUT the optional argument values.
+  When I [fill in the form with]:
+  |firstname|Alice|
+  |lastname| Inn |
+  |street_address| 11, No Street|
+  |city| Nowhere-City|
+  |country|Wonderland|
+  # No e-mail
+  # No comment
+
+  # The next step verifies that the optional steps from the macro were ignored.
+  Then I expect the following step trace:
+  """
+  Invoked step: ... I fill in "first_name" with "Alice"
+  Invoked step: ... I fill in "last_name" with "Inn"
+  Invoked step: ... I fill in "street_address" with "11, No Street"
+  Invoked step: ... I fill in "zip" with ""
+  Invoked step: ... I fill in "city" with "Nowhere-City"
+  Invoked step: ... I fill in "country" with "Wonderland"
+  Invoked step: ... I click "Save"
+  """
+  
+  
+Scenario: # Let's use the macro-step WITH the optional argument values.  
+  # Redo, now with e-mail and comment
+  When I [fill in the form with]:
+  |firstname|Alice|
+  |lastname| Inn |
+  |street_address| 11, No Street|
+  |city| Nowhere-City|
+  |country|Wonderland|
+  # Here come the optional values
+  |email|alice.inn@wonder.land|
+  |comment|No comment!|
+
+  # The next step verifies that the optional steps from the macro were ignored.
+  Then I expect the following step trace:
+  """
+  Invoked step: ... I fill in "first_name" with "Alice"
+  Invoked step: ... I fill in "last_name" with "Inn"
+  Invoked step: ... I fill in "street_address" with "11, No Street"
+  Invoked step: ... I fill in "zip" with ""
+  Invoked step: ... I fill in "city" with "Nowhere-City"
+  Invoked step: ... I fill in "country" with "Wonderland"
+  Invoked step: ... I fill in "email" with "alice.inn@wonder.land"
+  Invoked step: ... I fill in "comment" with "No comment!"
+  Invoked step: ... I click "Save"
+  """  

data/features/step_definitions/demo_steps.rb

@@ -20,23 +20,4 @@ Then(/^I expect the following step trace:$/) do |step_text|
 end
 
 
-When(/^I leave (.+)$/) do |city|
-  show "I leave #{city}"
-end
-
-
-When(/^I visit (.+)$/) do |city|
- show "I visit #{city}"
-end
-
-
-When(/^I arrive in (.+)$/) do |city|
-  show "I arrive in #{city}"
-end
-
-When(/^I type \"([^"]*)\"$/) do |text|
-  show text
-end
-
-
 # End of file

data/lib/macros4cuke/constants.rb

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

data/lib/macros4cuke/macro-step.rb

@@ -158,11 +158,14 @@ private
         # /{{{([^}]*)}}}|{{([^}]*)}}/ # Two capturing groups!...
       when :invokation
         /"((?:[^\\"]|\\.)*)"/
-      else
-        raise InternalError, "Internal error: Unknown mode argument #{mode}"
     end
     raw_result = aMacroPhrase.scan(pattern)
-    return raw_result.flatten.compact
+    args = raw_result.flatten.compact
+    
+    # Replace escaped quotes by quote character.
+    args.map! { |a| a.sub(/\\"/, '"') }  if mode == :invokation
+    
+    return args
   end
   
   # Return the substeps text after some transformation
@@ -204,5 +207,4 @@ end # class
 
 end # module
 
-
 # End of file

data/lib/macros4cuke/templating/engine.rb

@@ -130,14 +130,31 @@ public
   def add_child(aChild)
     children << aChild
   end
+  
+  # Retrieve all placeholder names that appear in the template.
+  # @return [Array] The list of placeholder names.
+  def variables()
+    all_vars = children.each_with_object([]) do |a_child, subResult|
+      case a_child
+        when Placeholder
+          subResult << a_child.name
+        when Section
+          subResult.concat(a_child.variables)
+        else
+          # Do nothing
+      end
+    end
+    
+    return all_vars.flatten.uniq
+  end
+
 
-protected
   # 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)
-    raise NotImplementedError, "Method Section::#{_method_} must be implemented in subclass(es)."
+    raise NotImplementedError, "Method Section::#{__method__} must be implemented in subclass(es)."
   end    
 
 end # class
@@ -175,7 +192,13 @@ public
     end
     
     return result
-  end   
+  end
+
+
+  # @return [String] The original text representation of the tag.
+  def to_s()
+    return "<?#{name}>"
+  end
 
 end # class
 
@@ -232,8 +255,20 @@ public
   def variables()
     # The result will be cached/memoized...
     @variables ||= begin
-      vars = @representation.select { |element| element.is_a?(Placeholder) }
-      vars.map(&:name)
+      vars = @representation.each_with_object([]) do |element, subResult|
+        case element
+          when Placeholder          
+            subResult << element.name
+          
+          when Section
+            subResult.concat(element.variables)
+          
+          else
+            # Do nothing
+        end
+      end
+      
+      vars.flatten.uniq
     end
     
     return @variables
@@ -302,10 +337,44 @@ private
     return compile_sections(compiled_lines.flatten())
   end
   
-  # Convert the array of raw entries into full-fledged template elements.
+  # Convert the array of raw entries (per line) into full-fledged template elements.
   def compile_line(aRawLine)
     line_rep = aRawLine.map { |couple| compile_couple(couple) }
-    line_rep << EOLine.new
+    
+    # Apply the rule: when a line just consist of spaces and a section element, 
+    # then remove all the spaces from that line.
+    section_item = nil
+    line_to_squeeze = line_rep.all? do |item|
+      case item
+        when StaticText
+          item.source =~ /\s+/
+          
+        when Section, SectionEndMarker
+          if section_item.nil?
+            section_item = item
+            true
+          else
+            false
+          end
+        else
+          false
+      end
+    end
+    if line_to_squeeze && ! section_item.nil?
+      line_rep = [section_item]
+    else
+      # Apply another rule: if last item in line is an end of section marker, 
+      # then place eoline before that item. Otherwise, end the line with a eoline marker.
+      if line_rep.last.is_a?(SectionEndMarker)
+        section_end = line_rep.pop()
+        line_rep << EOLine.new
+        line_rep << section_end
+      else
+        line_rep << EOLine.new
+      end
+    end
+    
+    return line_rep
   end
 
   
@@ -353,10 +422,11 @@ private
     return result
   end
   
-  # Group the elements by sections.
+  # Transform a flat sequence of elements into a hierarchy of sections.
   # @param flat_sequence [Array] a linear list of elements (including sections)
   def compile_sections(flat_sequence)
     open_sections = []  # The list of nested open sections
+    
     compiled = flat_sequence.each_with_object([]) do |element, subResult|
       case element
         when Section
@@ -364,7 +434,7 @@ private
         
         when SectionEndMarker
           if open_sections.empty?
-            raise StandardError, "End of section</#{element.name}> found while no corresponding section must be closed."
+            raise StandardError, "End of section</#{element.name}> found while no corresponding section is open."
           end
           if element.name != open_sections.last.name
             raise StandardError, "End of section</#{element.name}> doesn't match current section '#{open_sections.last.name}'."
@@ -381,6 +451,8 @@ private
       
     end
     
+    raise StandardError, "Unterminated section #{open_sections.last}." unless open_sections.empty?
+    
     return compiled
   end
  

data/spec/macros4cuke/macro-step_spec.rb

@@ -91,7 +91,22 @@ SNIPPET
 
       text.should == expectation
     end
+    
+    it "should un-escape the double-quotes for phrase arguments" do
+      specific_phrase = %q|enter my credentials as "quotable\""|
+      text = subject.expand(specific_phrase, [ ['password', 'no-secret'] ])
+      expectation = <<-SNIPPET
+  Given I landed in the homepage
+  When I click "Sign in"
+  And I fill in "Username" with "quotable""
+  And I fill in "Password" with "no-secret"
+  And I click "Submit"
+SNIPPET
+
+      text.should == expectation
+    end
 
+    
     it "should complain when an unknown variable is used" do
       # Error case: there is no macro argument called <unknown>
       error_message = "Unknown macro-step argument 'unknown'."

data/spec/macros4cuke/templating/engine_spec.rb

@@ -27,10 +27,11 @@ SNIPPET
       source = <<-SNIPPET
   When I fill in "firstname" with "<firstname>"
   And I fill in "lastname" with "<lastname>"
-  <?address>And I fill in "address" with "<address>"</address>
+<?address>  And I fill in "address" with "<address>"</address>
   <?birthdate>
   And I fill in "birthdate" with "<birthdate>"
   </birthdate>
+<?dummy></dummy>
   And I click "Register"
 SNIPPET
     end    
@@ -201,6 +202,29 @@ SNIPPET
       lambda { Engine.new text_w_empty_arg }.should raise_error(Macros4Cuke::InvalidCharError, error_message)
     end
     
+    it "should complain when a section has no closing tag" do
+      # Removing an end of section tag...
+      text_w_open_section = sophisticated_template.sub(/<\/address>/, '')
+
+      error_message = "Unterminated section <?address>."
+      lambda { Engine.new text_w_open_section}.should raise_error(StandardError, error_message)
+    end
+    
+    it "should complain when a closing tag does not correspond to currently open section" do
+      # Replacing an end of section tag by another...
+      text_w_wrong_end = sophisticated_template.sub(/<\/address>/, '</foobar>')
+
+      error_message = "End of section</foobar> doesn't match current section 'address'."
+      lambda { Engine.new text_w_wrong_end}.should raise_error(StandardError, error_message)
+    end
+    
+    it "should complain when a closing tag is found while no section is open" do
+      # Replacing an end of section tag by another...
+      text_w_wrong_end = sophisticated_template.sub(/<\?birthdate>/, '</foobar>')
+      error_message = "End of section</foobar> found while no corresponding section is open."
+      lambda { Engine.new text_w_wrong_end}.should raise_error(StandardError, error_message)
+    end    
+    
   end # context
 
   context "Provided services" do
@@ -283,15 +307,25 @@ SNIPPET
       expected = <<-SNIPPET
   When I fill in "firstname" with "Anon"
   And I fill in "lastname" with "Eemoos"
-  
-  
   And I fill in "birthdate" with "1976-04-21"
-  
   And I click "Register"
 SNIPPET
 
       rendered_text.should == expected
       
+      # Redo with another context
+      locals["birthdate"] = nil
+      locals["address"] = "122, Mercer Street"
+      
+      rendered_text = instance.render(Object.new, locals)
+      expected = <<-SNIPPET
+  When I fill in "firstname" with "Anon"
+  And I fill in "lastname" with "Eemoos"
+  And I fill in "address" with "122, Mercer Street"
+  And I click "Register"
+SNIPPET
+
+      rendered_text.should == expected      
     end
     
 

data/spec/macros4cuke/templating/placeholder_spec.rb

@@ -0,0 +1,65 @@
+# 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 Placeholder do
+  # Default instantiation rule
+  subject { Placeholder.new('foobar') }
+
+  context "Creation and initialization:" do
+
+    it "should be created with a variable name" do
+      lambda { Placeholder.new('foobar') }.should_not raise_error
+    end
+    
+    it "should know the name of its variable" do 
+      subject.name.should == 'foobar'
+    end    
+
+  end # context 
+
+  context "Provided services:" do 
+    it "should render an empty string when no actual value is bound to the placeholder" do
+      # Case: context has no value associated to 'foobar'
+      rendered_text = subject.render(Object.new, {})
+      rendered_text.should be_empty
+      
+      # Case: locals Hash has a nil value associated to 'foobar'
+      rendered_text = subject.render(Object.new, {'foobar' => nil})
+      rendered_text.should be_empty
+
+      # Case: context object has a nil value associated to 'foobar'
+      context = Object.new
+      def context.foobar; nil; end  # Add singleton method foobar that returns nil
+      rendered_text = subject.render(context, {})
+      rendered_text.should be_empty        
+    end
+    
+    it "should render the actual value bound to the placeholder" do
+      # Case: locals Hash has a value associated to 'foobar'
+      rendered_text = subject.render(Object.new, {'foobar' => 'hello'})
+      rendered_text.should == 'hello'
+
+      # Case: context object has a value associated to 'foobar'
+      context = Object.new
+      def context.foobar; 'world'; end  # Add singleton method foobar that returns 'world'
+      rendered_text = subject.render(context, {})
+      rendered_text.should == 'world'       
+    end
+  
+  end # context
+
+end # describe
+
+end # module
+
+end # module
+
+# End of file

data/spec/macros4cuke/templating/section_spec.rb

@@ -8,23 +8,85 @@ module Macros4Cuke
 
 module Templating # Open this namespace to get rid of module qualifier prefixes
 
+# Spec for abstract class Section.
+describe Section do
+  # Default instantiation rule
+  subject { Section.new('foobar') } 
+  
+  # Return a list of possible child elements
+  let(:sample_children) do
+    [ StaticText.new("Hello "),
+      Placeholder.new("user"),
+      EOLine.new
+    ]
+  end 
+
+  context "Creation and initialization" do
+ 
+    it "should be created with a variable name" do
+      lambda { Section.new('foobar') }.should_not raise_error 
+    end
+    
+    it "should know the name of its variable" do 
+      subject.name.should == 'foobar'
+    end
+
+    it "should have no child at start" do
+      subject.should have(0).children
+    end    
+  
+  end # context
+  
+  context "Provided services:" do  
+    it "should add child element(s)" do
+      sample_children.each do |a_child|
+        subject.add_child(a_child)
+      end
+
+      # Control that the addition work as expected
+      subject.children.should == sample_children
+    end
+    
+    it "should know the name all child placeholders" do
+      # Case: simple flat list of children
+      sample_children.each { |a_child| subject.add_child(a_child) }
+      subject.variables.should == [ 'user' ]
+      
+      # Case: at least one child is a group    
+      parent = Section.new('son')
+      [ 
+        subject,
+        StaticText.new("Bye "),
+        Placeholder.new("firstname"),
+        EOLine.new
+      ].each { |a_child| parent.add_child(a_child) } 
+
+      parent.variables.should == [ 'user', 'firstname']
+      
+    end
+    
+    
+    it "should expect that its subclasses render the children" do
+      error_message = "Method Section::render must be implemented in subclass(es)."
+      lambda {subject.send(:render, Object.new, {}) }.should raise_error(NotImplementedError, error_message)
+    end
+    
+  end # context
+
+end # describe
+
+
+
 
 describe ConditionalSection do
 
-  context "Creation and initialization" 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)
@@ -32,16 +94,9 @@ describe ConditionalSection do
       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
+  context "Provided services:" do
     # Return a list of possible child elements
     let(:sample_children) do
       [ StaticText.new("Hello "),
@@ -52,15 +107,9 @@ describe ConditionalSection do
 
     # 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
-
+    
+    it "should know its original source text" do
+      subject.to_s.should == '<?foobar>'
     end
 
     it "should render its children when conditions are met" do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: macros4cuke
 version: !ruby/object:Gem::Version
-  version: 0.3.00
+  version: 0.3.01
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-09 00:00:00.000000000 Z
+date: 2013-05-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cucumber
@@ -72,14 +72,20 @@ files:
 - LICENSE.txt
 - README.md
 - lib/macros4cuke.rb
-- lib/macro_steps.rb
 - lib/macros4cuke/constants.rb
 - lib/macros4cuke/exceptions.rb
 - lib/macros4cuke/macro-collection.rb
 - lib/macros4cuke/macro-step-support.rb
 - lib/macros4cuke/macro-step.rb
 - lib/macros4cuke/templating/engine.rb
+- examples/demo/cucumber.yml
+- examples/demo/features/basic.feature
+- examples/demo/features/table.feature
 - examples/i18n/fr/cucumber.yml
+- examples/demo/features/step_definitions/step_defs.rb
+- examples/demo/features/step_definitions/use_macro_steps.rb
+- examples/demo/features/support/env.rb
+- examples/demo/features/support/macro_support.rb
 - examples/i18n/fr/features/demo01-fr.feature
 - examples/i18n/fr/features/step_definitions/demo_steps.rb
 - examples/i18n/fr/features/step_definitions/use_macro_steps.rb
@@ -89,7 +95,7 @@ files:
 - features/demo03.feature
 - features/demo04.feature
 - features/demo05.feature
-- features/travelling-demo.feature
+- features/demo06.feature
 - features/step_definitions/demo_steps.rb
 - features/step_definitions/use_macro_steps.rb
 - features/support/env.rb
@@ -99,6 +105,7 @@ files:
 - spec/macros4cuke/macro-step-support_spec.rb
 - spec/macros4cuke/macro-step_spec.rb
 - spec/macros4cuke/templating/engine_spec.rb
+- spec/macros4cuke/templating/placeholder_spec.rb
 - spec/macros4cuke/templating/section_spec.rb
 homepage: https://github.com/famished-tiger/Macros4Cuke
 licenses:

data/lib/macro_steps.rb

@@ -1,49 +0,0 @@
-# File: macro_steps.rb
-# Purpose: step definitions that help to build macro-steps (i.e. a step that is equivalent to a sequence of steps)
-
-
-
-# This step is used to define a macro-step
-# Example:
-#  Given I define the step "When I [log in as <userid>]" to mean:
-#  """
-#  Given I landed in the homepage
-#  When I click "Sign in"
-#  And I fill in "Username" with "<userid>"
-#  And I fill in "Password" with "unguessable"
-#  And I click "Submit"
-#  """
-# The regexp has two capturing group: one for the phrase, a second for the terminating colon (:)
-Given(/^I define the step "(?:Given|When|Then) I \[((?:[^\\\]]|\\.)+)\](:?)" to mean:$/) do |macro_phrase, colon_capture, template|
-  use_table = (colon_capture == ':')
-  add_macro(macro_phrase, template, use_table)
-end
-
-# This step is used to invoke a simple macro-step
-# Example:
-#  When I [log in as "guest"]
-#
-When(/^I \[((?:[^\\\]]|\\.)+)\]$/) do |macro_phrase|
-  invoke_macro(macro_phrase)  # This will call the macro with the given phrase
-end
-
-
-# This step is used to invoke a macro-step with a data table argument.
-# Example:
-#  When I [enter my credentials as]:
-#  |userid  |guest      |
-#  |password|unguessable|
-When(/^I \[([^\]]+)\]:$/) do |macro_phrase, table_argument|
-  # Ensure that the second argument is of the correct type
-  unless table_argument.kind_of?(Cucumber::Ast::Table)
-     raise Macros4Cuke::DataTableNotFound, "This step must have a data table as an argument."
-  end
-
-  # This will call the macro with the given phrase.
-  # The second argument consists of an array with couples of the kind: [argument name, actual value]
-  invoke_macro(macro_phrase, table_argument.raw)
-end
-
-
-
-# End of file