macros4cuke 0.2.13 → 0.2.14

data/.yardopts

@@ -0,0 +1,6 @@
+--exclude features
+--no-private
+--markup markdown
+-
+Changelog.md
+License.txt

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+## 0.2.14 / 2013-05-03
+* [CHANGE] Code comments reformatted to YARD. The command line `yard stats`display a 100% documented score!
+* [CHANGE] Moved all classes related to the template engine to the new module Templating.
+* [CHANGE] Classes `StaticRep, EOLRep, VariableRep, TemplateEngine` renamed to `StaticText, EOLine, Placeholder, Engine` respectively.
+* [CHANGE] Added spec file for `MacroStepSupport` module.
+* [CHANGE] Initialization of `MacroStepSupport` singleton changed (no dependency on `extended` hook).
+
 ## 0.2.13 / 2013-05-02
 * [NEW] File `macro-collection_spec.rb`: partial spec file for the `MacroCollection` class.
 * [FIX] `DuplicateMacroError#initialize`: Removed superfluous [ in error message.

data/lib/macro_steps.rb

@@ -5,17 +5,17 @@
 
 # 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 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 "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_present, template|
-  use_table = (colon_present == ':')
+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
 
@@ -45,4 +45,5 @@ When(/^I \[([^\]]+)\]:$/) do |macro_phrase, table_argument|
 end
 
 
+
 # End of file

data/lib/macros4cuke/constants.rb

@@ -3,20 +3,20 @@
 
 module Macros4Cuke # Module used as a namespace
 	# The version number of the gem.
-	Version = '0.2.13'
-  
+	Version = '0.2.14'
+
   # Brief description of the gem.
   Description = "Macros for Cucumber"
-	
+
 	# Constant Macros4Cuke::RootDir contains the absolute path of Rodent's root directory. Note: it also ends with a slash character.
 	unless defined?(RootDir)
     # The initialisation of constant RootDir is guarded in order to avoid multiple initialisation (not allowed for constants)
-    
+
     # The root folder of Macros4Cuke.
 		RootDir = begin
       require 'pathname'	# Load Pathname class from standard library
       rootdir = Pathname(__FILE__).dirname.parent.parent.expand_path()
-      rootdir.to_s() + '/'	# Append trailing slash character to it     
+      rootdir.to_s() + '/'	# Append trailing slash character to it
     end
 	end
 end # module

data/lib/macros4cuke/exceptions.rb

@@ -1,82 +1,83 @@
-# encoding: utf-8 -- You should see a paragraph character: § 
-# File: exceptions.rb
-
-module Macros4Cuke # Module used as a namespace
-
-# Base class for any exception explicitly raised in the Macros4Cuke methods.
-class Macros4CukeError < StandardError
-end # class
-
-# Raised when one attempts to define a new macro 
-# that has the same phrase as an existing macro.
-class DuplicateMacroError < Macros4CukeError
-  def initialize(aPhrase)
-    super("A macro-step with phrase '#{aPhrase}' already exist.")
-  end
-end # class
-
-# Raised when one defines an argument name in a macro-step's phrase
-# and that argument name does not appear in any sub-step.
-class UselessPhraseArgument < Macros4CukeError
-  def initialize(anArgName)
-    super("The phrase argument '#{anArgName}' does not appear in a sub-step.")
-  end
-end # class
-
-
-
-# Raised when one defines an argument name in a macro-step's phrase
-# and that argument name does not appear in any sub-step.
-class UnreachableSubstepArgument < Macros4CukeError
-  def initialize(anArgName)
-    super("The sub-step argument '#{anArgName}' does not appear in the phrase.")
-  end
-end # class
-
-
-
-# Raised when a sub-step has an empty or blank argument name.
-class EmptyArgumentError < Macros4CukeError
-  def initialize(aText)
-    super("An empty or blank argument occurred in '#{aText}'.")
-  end
-end # class
-
-
-# Raised when one invokes a macro-step with an unknown phrase. 
-class UnknownMacroError < Macros4CukeError
-  def initialize(aPhrase)
-    super("Unknown macro-step with phrase: '[#{aPhrase}'.")
-  end
-end # class
-
-
-
-# Raised when one invokes a macro-step with an argument
-# that has an unknown name. 
-class UnknownArgumentError < Macros4CukeError
-  def initialize(argName)
-    super("Unknown macro-step argument '#{argName}'.")
-  end
-end # class
-
-
-
-# Raised when one invokes a macro-step without a required data table argument
-class DataTableNotFound < Macros4CukeError
-  def initialize(argName)
-    super("The macro-step is missing a data table argument.")
-  end
-end # class
-
-
-
-# Raised when Macros4Cuke encountered an issue
-# that it can't handle properly.
-class InternalError < Macros4CukeError
-end # class
-
-
-end # module
-
+# encoding: utf-8 -- You should see a paragraph character: § 
+# File: exceptions.rb
+
+module Macros4Cuke # Module used as a namespace
+
+# @abstract
+# Base class for any exception explicitly raised in the Macros4Cuke methods.
+class Macros4CukeError < StandardError
+end # class
+
+# Raised when one attempts to define a new macro 
+# that has the same phrase as an existing macro.
+class DuplicateMacroError < Macros4CukeError
+  def initialize(aPhrase)
+    super("A macro-step with phrase '#{aPhrase}' already exist.")
+  end
+end # class
+
+# Raised when one defines an argument name in a macro-step's phrase
+# and that argument name does not appear in any sub-step.
+class UselessPhraseArgument < Macros4CukeError
+  def initialize(anArgName)
+    super("The phrase argument '#{anArgName}' does not appear in a sub-step.")
+  end
+end # class
+
+
+
+# Raised when one defines an argument name in a macro-step's phrase
+# and that argument name does not appear in any sub-step.
+class UnreachableSubstepArgument < Macros4CukeError
+  def initialize(anArgName)
+    super("The sub-step argument '#{anArgName}' does not appear in the phrase.")
+  end
+end # class
+
+
+
+# Raised when a sub-step has an empty or blank argument name.
+class EmptyArgumentError < Macros4CukeError
+  def initialize(aText)
+    super("An empty or blank argument occurred in '#{aText}'.")
+  end
+end # class
+
+
+# Raised when one invokes a macro-step with an unknown phrase. 
+class UnknownMacroError < Macros4CukeError
+  def initialize(aPhrase)
+    super("Unknown macro-step with phrase: '[#{aPhrase}'.")
+  end
+end # class
+
+
+
+# Raised when one invokes a macro-step with an argument
+# that has an unknown name. 
+class UnknownArgumentError < Macros4CukeError
+  def initialize(argName)
+    super("Unknown macro-step argument '#{argName}'.")
+  end
+end # class
+
+
+
+# Raised when one invokes a macro-step without a required data table argument
+class DataTableNotFound < Macros4CukeError
+  def initialize(argName)
+    super("The macro-step is missing a data table argument.")
+  end
+end # class
+
+
+
+# Raised when Macros4Cuke encountered an issue
+# that it can't handle properly.
+class InternalError < Macros4CukeError
+end # class
+
+
+end # module
+
 # End of file

data/lib/macros4cuke/macro-collection.rb

@@ -6,32 +6,22 @@ require_relative "macro-step"
 
 module Macros4Cuke # Module used as a namespace
 
-# Represents a container of macros.
-# It gather all the macros encountered by Cucumber while "executing" the feature files.
+# Represents a container of macros.  
+# It gathers all the macros encountered by Cucumber while "executing" the feature files.
+# @note This is a singleton class (i.e. there is only one macro collection object).
 class MacroCollection
   include Singleton # Use the Singleton design pattern.
 
-  # A Hash with pairs of the form: phrase => MacroStep object
-  attr_reader(:macro_steps)
+  # @!attribute [r] macro_steps.
+  #   A Hash with pairs of the form: macro key => MacroStep object
 
-  # Init the pool if it was not done yet.
-  def init()
-    @macro_steps = {} if @macro_steps.nil?
-  end
   
 public
-  # Return true iff the host has a macro with the given key.
-  def has_macro?(aPhrase, mode)
-    key = MacroStep::macro_key(aPhrase, mode)
-    return @macro_steps.include? key
-  end
-  
-  
   # Add a new macro.
   # Pre-condition: there is no existing macro with the same key.
-  # [aPhrase] The text that is enclosed between the square brackets.
-  # [aTemplate] A text that consists of a sequence of Cucumber steps.
-  # [useTable] A boolean that indicates whether a table should be used to pass actual values.
+  # @param aPhrase [String] The text that is enclosed between the square brackets.
+  # @param aTemplate [String] A text that consists of a sequence of sub-steps.
+  # @param useTable [boolean] A flag indicating whether a table should be used to pass actual values.
   def add_macro(aPhrase, aTemplate, useTable)
     new_macro = MacroStep.new(aPhrase, aTemplate, useTable)
     
@@ -40,17 +30,17 @@ public
     # An exception is raised if the phrase syntax of both macros are the     
     raise DuplicateMacroError.new(aPhrase) if find_macro(aPhrase, useTable)
     
-    @macro_steps[new_macro.key] = new_macro    
+    macro_steps[new_macro.key] = new_macro    
 
   end
-  
+
   # Render the steps associated to the macro with given phrase
   # and (optionally) given a table of values.
   # Return the rendered steps as a text.
-  # [aPhrase] an instance of the macro phrase.
-  # [rawData] An Array of couples.
-  # Each couple is of the form: argument name, a value.
-  # Multiple rows with same argument name are acceptable.  
+  # @param aPhrase [String] an instance of the macro phrase.
+  # @param rawData [Array] An array of couples of the form: [ argument name, a value].
+  #   Multiple rows with same argument name are acceptable.
+  # @return [String]
   def render_steps(aPhrase, rawData = nil)
     useTable = ! rawData.nil?
     macro = find_macro(aPhrase, useTable) 
@@ -60,10 +50,24 @@ public
     return  macro.expand(aPhrase, rawData)
   end
 
+
+  # Clear/remove all macro definitions from the collection.
+  # Post-condition: we are back to the same situation as no macro was ever defined.
+  def clear()
+    macro_steps.clear()
+  end
+
+  
+  # Read accessor for the @macro_steps attribute.
+  def macro_steps()
+    @macro_steps ||= {}
+    return @macro_steps
+  end
+  
 private
   # Retrieve the macro, given a phrase.
   def find_macro(aMacroPhrase, useTable)
-    return @macro_steps[MacroStep::macro_key(aMacroPhrase, useTable, :invokation)]
+    return macro_steps[MacroStep::macro_key(aMacroPhrase, useTable, :invokation)]
   end
 
 end # class

data/lib/macros4cuke/macro-step-support.rb

@@ -1,52 +1,52 @@
-# File: macro-step-support.rb
-
-require_relative "exceptions"
-require_relative "macro-collection"
-
-module Macros4Cuke # Module used as a namespace
-
-# Mix-in module that should be extending World objects in Cucumber.
-# Synopsis (in env.rb):
-# require 'macros4cuke'
-# ...
-# World(Macros4Cuke::MacroStepSupport) # Extend the world object with this module.
-#
-module MacroStepSupport
-
-  # Callback invoked when a World object is extend(ed) with this module.
-  def self.extended(world)
-    # Add & initialize an instance variable for macro support.  
-    MacroCollection::instance.init()
-  end
-
-
-public
-
-  # Add a new macro.
-  # Pre-condition: there is no existing macro with the same key.
-  # [aPhrase] The text that is enclosed between the square brackets.
-  # [aTemplate] A text that consists of a sequence of Cucumber steps.
-  # [useTable] A boolean that indicates whether a table should be used to pass actual values.
-  def add_macro(aPhrase, aTemplate, useTable)
-    MacroCollection::instance.add_macro(aPhrase, aTemplate, useTable)
-  end
-
-  
-  # Invoke a macro with given phrase and (optionally) a table of values
-  # [aPhrase] an instance of the macro phrase.
-  # [rawData] An Array of couples.
-  # Each couple is of the form: argument name, a value.
-  # Multiple rows with same argument name are acceptable.  
-  def invoke_macro(aPhrase, rawData = nil)
-    # Generate a text rendition of the step to be executed.
-    rendered_steps = MacroCollection::instance.render_steps(aPhrase, rawData)
-    
-    # Execute the steps
-    steps(rendered_steps)
-  end
-
-end # module
-
-end # module
-
+# File: macro-step-support.rb
+
+require_relative "exceptions"
+require_relative "macro-collection"
+
+module Macros4Cuke # Module used as a namespace
+
+# Mix-in module that should be extending World objects in Cucumber.  
+# Synopsis (in env.rb):  
+#   
+#   require 'macros4cuke'  
+#   ...  
+#   World(Macros4Cuke::MacroStepSupport) # Extend the world object with this module.
+#    
+module MacroStepSupport
+public
+
+  # Add a new macro.
+  # Pre-condition: there is no existing macro with the same key.
+  # @param aPhrase [String] The text that is enclosed between the square brackets [...].
+  # @param aTemplate [String] The text template that consists of a sequence of sub-steps.
+  # @param useTable [boolean] A flag that indicates whether a table should be used to pass actual values.
+  def add_macro(aPhrase, aTemplate, useTable)
+    MacroCollection::instance.add_macro(aPhrase, aTemplate, useTable)
+  end
+
+
+  # Invoke a macro with given phrase and (optionally) a table of values
+  # @param aPhraseInstance [String] an instance of the macro phrase. That is, the text between [...] and with zero or more actual values.
+  # @param rawData [Array or nil] An array of couples. Each couple is of the form: [macro argument name, a value].
+  # Multiple rows with same argument name are acceptable.  
+  def invoke_macro(aPhraseInstance, rawData = nil)
+    # Generate a text rendition of the step to be executed.
+    rendered_steps = MacroCollection::instance.render_steps(aPhraseInstance, rawData)
+    
+    # Let Cucumber execute the sub-steps
+    steps(rendered_steps)
+  end
+
+
+  # Clear (remove) all the macro-step definitions.
+  # After this, we are in the same situation when no macro-step was ever defined.
+  def clear_macros()
+    MacroCollection::instance.clear()
+  end
+
+end # module
+
+end # module
+
+
 # End of file

data/lib/macros4cuke/macro-step.rb

@@ -3,14 +3,18 @@
 
 
 require_relative 'exceptions'
-require_relative 'template-engine'
+require_relative 'templating/engine'
 
 module Macros4Cuke # Module used as a namespace
 
-# In essence, a macro step object represents a Cucumber step that is itself
-# an aggregation of lower-level Cucumber steps.
+# A macro-step object is a Cucumber step that is itself
+# an aggregation of lower-level sub-steps.
+# When a macro-step is used in a scenario, then its execution is equivalent
+# to the execution of its sub-steps.
+# A macro-step may have zero or more arguments. The actual values bound to these arguments
+# are passed to the sub-steps at execution time.
 class MacroStep
-  # A template engine that expands the substeps upon request.
+  # A template engine that expands the sub-steps upon request.
   attr_reader(:renderer)
   
   # Unique key of the macro as derived from the macro phrase.
@@ -24,54 +28,56 @@ class MacroStep
 
   
   # Constructor.
-  # [aMacroPhrase] The text from the macro step definition that is between the square brackets.
-  # [theSubsteps] The source text of the steps to be expanded upon macro invokation.
-  # [useTable] A boolean that indicates whether a data table must be used to pass actual values.
+  # @param aMacroPhrase[String] The text from the macro step definition that is between the square brackets.
+  # @param theSubsteps [String] The source text of the steps to be expanded upon macro invokation.
+  # @param useTable [boolean] A flag indicating whether a data table must be used to pass actual values.
   def initialize(aMacroPhrase, theSubsteps, useTable)
     @key = self.class.macro_key(aMacroPhrase, useTable, :definition)
-    
+
     # Retrieve the macro arguments embedded in the phrase.
     @phrase_args = scan_arguments(aMacroPhrase, :definition)
-    
+
     # Manipulate the substeps source text
     substeps_processed = preprocess(theSubsteps)
 
-    @renderer = TemplateEngine.new(substeps_processed)
+    @renderer = Templating::Engine.new(substeps_processed)
     substeps_vars = renderer.variables
-    
-    
+
+
     @args = validate_phrase_args(@phrase_args, substeps_vars)
     @args.concat(substeps_vars)
     @args.uniq!
   end
-  
-  
-  # Compute the identifier of the macro from the given macro phrase.
-  # A macro phrase is a text that must start with a recognised verb and may contain zero or more placeholders.
-  # In definition mode, a placeholder is delimited by chevrons <..>
-  # In invokation mode, a placeholder is delimited by double quotes.
-  # The rule for building the identifier are:
-  # - Leading and trailing space(s) are removed.
-  # - Each underscore character is removed.
-  # - Every sequence of one or more space(s) is converted into an underscore
-  # - Each placeholder (i.e. = delimiters + enclosed text) is converted into a letter X.
-  # - when useTable is true, concatenate: _T 
-  # Example:
-  # Consider the macro phrase: 'create the following "contactType" contact]:'
-  # The resulting macro_key is: 'create_the_following_X_contact_T'
-  # [aMacroPhrase] The text from the macro step definition that is between the square brackets.
-  # [useTable] A boolean that indicates whether a table should be used to pass actual values.
-  # [mode] one of the following: :definition, :invokation
+
+
+  # Compute the identifier of the macro from the given macro phrase.  
+  # A macro phrase is a text that may contain zero or more placeholders.   
+  # In definition mode, a placeholder is delimited by chevrons <..>.  
+  # In invokation mode, a value bound to a placeholder is delimited by double quotes.  
+  # The rule for building the identifying key are:  
+  # - Leading and trailing space(s) are removed.  
+  # - Each underscore character is removed.  
+  # - Every sequence of one or more space(s) is converted into an underscore  
+  # - Each placeholder (i.e. = delimiters + enclosed text) is converted into a letter X.  
+  # - when useTable is true, concatenate: _T   
+  # @example:
+  #   Consider the macro phrase: 'create the following "contactType" contact'  
+  #   The resulting macro_key is: 'create_the_following_X_contact_T'
+  #
+  # @param aMacroPhrase [String] The text from the macro step definition that is between the square brackets.
+  # @param useTable [boolean] A flag indicating whether a table should be used to pass actual values.
+  # @param mode [:definition, :invokation]
+  # @return [String] the key of the phrase/macro.
   def self.macro_key(aMacroPhrase, useTable, mode)
     stripped_phrase = aMacroPhrase.strip # Remove leading ... trailing space(s)
-    
+
     # Remove every underscore
     stripped_phrase.gsub!(/_/, '')
-    
+
     # Replace all consecutive whitespaces by an underscore    
     stripped_phrase.gsub!(/\s+/, '_')
-    
-    
+
+
     # Determine the pattern to isolate each argument/parameter with its delimiters
     pattern = case mode
       when :definition
@@ -80,28 +86,27 @@ class MacroStep
         /"([^\\"]|\\.)*"/
 
     end
-    
+
     # Each text between quotes or chevron is replaced by the letter X
     normalized = stripped_phrase.gsub(pattern, 'X')
-    
+
     key = normalized + (useTable ? '_T' : '')
-    
+
     return key
-  end  
-  
-  
+  end
+
+
   # Render the steps from the template, given the values
   # taken by the parameters
-  # [aPhrase] an instance of the macro phrase.
-  # [rawData] An Array of couples.
-  # Each couple is of the form: argument name, a value.
-  # Multiple rows with same argument name are acceptable.
+  # @param aPhrase [String] an instance of the macro phrase.
+  # @param rawData [Array] An array of couples of the form: [argument name, a value].
+  #   Multiple rows with same argument name are acceptable.
   def expand(aPhrase, rawData)
     params = validate_params(aPhrase, rawData)
     return renderer.render(nil, params)
   end
 
-private  
+private
   # Build a Hash from the given raw data.
   # [aPhrase] an instance of the macro phrase.
   # [rawData] An Array of couples.
@@ -109,7 +114,7 @@ private
   # Multiple rows with same argument name are acceptable.
   def validate_params(aPhrase, rawData)
     macro_parameters = {}
-    
+
     # Retrieve the value(s) per variable in the phrase.
     quoted_values = scan_arguments(aPhrase, :invokation)   
     quoted_values.each_with_index do |val, index|

data/lib/macros4cuke/{template-engine.rb → templating/engine.rb}

@@ -1,37 +1,59 @@
-# File: template-engine.rb
+# File: engine.rb
 # Purpose: Implementation of the MacroStep class.
 
 require 'strscan' # Use the StringScanner for lexical analysis.
-require_relative 'exceptions' # Load the 
+require_relative '../exceptions' # Load the custom exception classes.
+
 
 module Macros4Cuke # Module used as a namespace
 
 
+# Module containing all classes implementing the simple template engine
+# used internally in Macros4Cuke.  
+module Templating
 
-class StaticRep
+# Class used internally by the template engine.  
+# Represents a static piece of text from a template.  
+# A static text is a text that is reproduced verbatim when rendering a template.
+class StaticText
+  # The static text extracted from the original template.
   attr_reader(:source)
   
+
+  # @param aSourceText [String] A piece of text extracted from the template that must be rendered verbatim.
   def initialize(aSourceText)
     @source = aSourceText
   end
-  
+
 public
-  def render(aContextObject = nil, theLocals)
+
+  # Render the static text.
+  # This method has the same signature as the {Engine#render} method.
+  # @return [String] Static text is returned verbatim ("as is")
+  def render(aContextObject, theLocals)
     return source
   end
 end # class
 
 
-class VariableRep
+# 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
+  # The name of the placeholder/variable.
   attr_reader(:name)
   
+  # @param aVarName [String] The name of the placeholder from a template.
   def initialize(aVarName)
     @name = aVarName
   end
-  
+
 public
-  # The signature of this method should comply to the Tilt API.
-  # Actual values from the 'locals' Hash take precedence over the context object.
+  # 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?
@@ -41,59 +63,74 @@ public
     
     return actual_value.is_a?(String) ? actual_value : actual_value.to_s
   end  
-  
+
 end # class
 
 
-class EOLRep
+# Class used internally by the template engine.  
+# 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
 
 
-# A very simple implementation of a templating engine. 
-class TemplateEngine
+# 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.  
+# The reasons were the following:  
+# - Be closer to the usual Gherkin syntax (parameters of scenario outlines use chevrons <...>, 
+#     while Mustache use !{{...}} delimiters),  
+# - Feature files are meant to be simple, so should the template engine be. 
+class Engine
   # The original text of the template is kept here.
   attr_reader(:source)
   
-  # Constructor.
-  # [aSourceTemplate] the template source text. It may contain zero or tags enclosed between chevrons <...>.
+  # Builds an Engine and compiles the given template text into an internal representation.
+  # @param aSourceTemplate [String] The template source text. It may contain zero or tags enclosed between chevrons <...>.
   def initialize(aSourceTemplate)
     @source = aSourceTemplate
     @representation = compile(aSourceTemplate)
   end
 
 public
-  # [aContextObject] context object to get actual values (when not present in the Hash parameter).
-  # [theLocals] a Hash with pairs of the form: argument name => actual value.
-  def render(aContextObject = nil, theLocals)
+  # Render the template within the given scope object and with the locals specified.
+  # The method mimicks the signature of the Tilt::Template#render method.
+  # @param aContextObject [anything] context object to get actual values (when not present in the locals Hash).
+  # @param theLocals [Hash] Contains one or more pairs of the form: tag/placeholder name => actual value.
+  # @return [String] The rendition of the template given the passed argument values.
+  def render(aContextObject = Object.new, theLocals)
     return '' if @representation.empty?
-    context = aContextObject.nil? ? Object.new : aContextObject
     
     result = @representation.each_with_object('') do |element, subResult|
-      subResult << element.render(context, theLocals)
+      subResult << element.render(aContextObject, theLocals)
     end
     
     return result
   end
+
   
-  # Return all variable names that appear in the template.
+  # Retrieve all placeholder names that appear in the template.
+  # @return [Array] The list of placeholder names.
   def variables()
     # The result will be cached/memoized...
     @variables ||= begin
-      vars = @representation.select { |element| element.is_a?(VariableRep) }
+      vars = @representation.select { |element| element.is_a?(Placeholder) }
       vars.map(&:name)
     end
     
     return @variables
   end
 
-  # Class method. Parse the given line text.
-  # Returns an array of couples.
-  # Couples are of the form:
-  # [:static, text] or [:dynamic, text]
+
+  # Class method. Parse the given line text into a raw representation.
+  # @return [Array] Couples of the form:
+  # [:static, text] or [:dynamic, tag text]
   def self.parse(aTextLine)
     scanner = StringScanner.new(aTextLine)
     result = []
@@ -157,7 +194,7 @@ private
   # Convert the array of raw entries into full-fledged template elements.
   def compile_line(aRawLine)
     line_rep = aRawLine.map { |couple| compile_couple(couple) }
-    line_rep << EOLRep.new
+    line_rep << EOLine.new
   end
 
   
@@ -168,9 +205,10 @@ private
     
     result = case kind
       when :static
-        StaticRep.new(text) 
+        StaticText.new(text)
+        
       when :dynamic
-        VariableRep.new(text)
+        Placeholder.new(text)
       else
         raise StandardError, "Internal error: Don't know template element of kind #{kind}"
       end
@@ -182,4 +220,6 @@ end # class
 
 end # module
 
+end # module
+
 # End of file

data/spec/macros4cuke/macro-collection_spec.rb

@@ -8,20 +8,15 @@ module Macros4Cuke # Open this namespace to get rid of module qualifier prefixes
 
 describe MacroCollection do
 
-  before(:all) do
-    # Initialize the sole instance
-    MacroCollection.instance.init()
-  end
-  
   let(:singleton) { MacroCollection.instance() }
-  
+
   context "Initialization:" do
     it "should be empty" do
       singleton.macro_steps.should be_empty
     end
-  
+
   end
-  
+
   context "Provided services:" do
     let(:sample_substeps) do
       snippet = <<-SNIPPET
@@ -32,20 +27,20 @@ describe MacroCollection do
   And I click "Submit"
 SNIPPET
 
-      snippet    
+      snippet
     end
 
     it "should accept the addition of a new macro-step" do
       phrase = "[enter my credentials]"
       lambda { singleton.add_macro(phrase, sample_substeps, true)}.should_not raise_error
       singleton.should have(1).macro_steps
-      
+
       # Error case: inserting another macro with same phrase.
       error_message = "A macro-step with phrase '[enter my credentials]' already exist."
       lambda { singleton.add_macro(phrase, sample_substeps, true) }.should raise_error(Macros4Cuke::DuplicateMacroError, error_message)
     end
   end
-  
+
 end # describe
 
 end # module

data/spec/macros4cuke/macro-step-support_spec.rb

@@ -0,0 +1,50 @@
+# File: macro-step_spec.rb
+
+require_relative '../spec_helper'
+require_relative '../../lib/macros4cuke/macro-step-support'	# The class under test
+
+
+module Macros4Cuke	# Open the module to avoid lengthy qualified names
+
+# Class created just for testing purposes.
+class MyWorld
+  include Macros4Cuke::MacroStepSupport
+end # class
+
+describe MacroStepSupport do
+  # Rule to build a bland world object
+  let(:world) do  
+    w = Object.new
+    w.extend(Macros4Cuke::MacroStepSupport)
+    w
+  end
+  
+  context "Defining macro(s):" do
+    let(:m1_phrase) { "enter the credentials" }
+    let(:m1_substeps) do
+      ssteps = <<-SNIPPET
+  Given I landed in the homepage
+  When I click "Sign in"
+  And I fill in "Username" with "<userid>"
+  And I fill in "Password" with "<password>"
+  And I click "Submit"      
+SNIPPET
+      ssteps
+    end
+    it "should add valid new macro" do
+      lambda { world.add_macro(m1_phrase, m1_substeps, true) }.should_not raise_error
+    end
+    
+    it "should complain when entering the same macro again" do
+      # Error case: trying to register another macro with same key/phrase.
+      error_message = "A macro-step with phrase 'enter the credentials' already exist."
+      lambda { world.add_macro(m1_phrase, m1_substeps, true) }.should raise_error(Macros4Cuke::DuplicateMacroError, error_message)
+    end
+  end # context
+
+end # describe
+
+end # module
+
+
+# End of file

data/spec/macros4cuke/macro-step_spec.rb

@@ -10,7 +10,7 @@ module Macros4Cuke	# Open the module to avoid lengthy qualified names
 
 describe MacroStep do
   let(:sample_phrase) { "enter my credentials as <userid>" }
-  
+
   let(:sample_template) do
     snippet = <<-SNIPPET
   Given I landed in the homepage
@@ -29,42 +29,42 @@ end
 
   context "Creation & initialization" do
     it "should be created with a phrase, substeps and a table use indicator" do
-      lambda { MacroStep.new(sample_phrase, sample_template, true) }.should_not raise_error     
+      lambda { MacroStep.new(sample_phrase, sample_template, true) }.should_not raise_error
     end
-    
-      
+
+
     it "should complain when a sub-step argument can never be assigned a value via the phrase" do
       error_message = "The sub-step argument 'password' does not appear in the phrase."
-      lambda { MacroStep.new(sample_phrase, sample_template, false) }.should raise_error(Macros4Cuke::UnreachableSubstepArgument, error_message)   
+      lambda { MacroStep.new(sample_phrase, sample_template, false) }.should raise_error(Macros4Cuke::UnreachableSubstepArgument, error_message)
     end
-    
-    
+
+
     it "should complain when an argument from the phrase never occurs in a substep" do
       a_phrase = "enter my credentials as <foobar>"
       error_message = "The phrase argument 'foobar' does not appear in a sub-step."
-      lambda { MacroStep.new(a_phrase, sample_template, true) }.should raise_error(Macros4Cuke::UselessPhraseArgument, error_message)   
-    end    
+      lambda { MacroStep.new(a_phrase, sample_template, true) }.should raise_error(Macros4Cuke::UselessPhraseArgument, error_message)
+    end
+
 
-  
     it "should know its key" do
       subject.key.should == "enter_my_credentials_as_X_T"
     end
-  
+
     it "should know the tags(placeholders) from its phrase" do
       subject.phrase_args.should == %w[userid]
     end
-    
+
     it "should know the tags(placeholders) from its phrase and template" do
-      subject.args.should == %w[userid password]    
+      subject.args.should == %w[userid password]
     end
-    
+
   end # context
-  
-  
+
+
   context "Provided services" do
-  
+
     let(:phrase_instance) {%Q|enter my credentials as "nobody"|}
-    
+
     it "should render the substeps" do
       text = subject.expand(phrase_instance, [ ['password', 'no-secret'] ])
       expectation = <<-SNIPPET
@@ -74,10 +74,10 @@ end
   And I fill in "Password" with "no-secret"
   And I click "Submit"
 SNIPPET
-      
+
       text.should == expectation
     end
-    
+
     it "should render steps even when one argument has no actual value" do
       # Special case: password has no value...
       text = subject.expand(phrase_instance, [ ])
@@ -88,10 +88,10 @@ SNIPPET
   And I fill in "Password" with ""
   And I click "Submit"
 SNIPPET
-      
-      text.should == expectation    
+
+      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'."
@@ -99,7 +99,7 @@ SNIPPET
     end
 
   end # context
-  
+
 
 end # describe
 

data/spec/macros4cuke/{template-engine_spec.rb → templating/engine_spec.rb}

@@ -1,12 +1,15 @@
 # encoding: utf-8 -- You should see a paragraph character: §
-# File: template-engine_spec.rb
+# File: engine_spec.rb
 
-require_relative '../spec_helper'
-require_relative '../../lib/macros4cuke/template-engine'	# Load the class under test
+require_relative '../../spec_helper'
+require_relative '../../../lib/macros4cuke/templating/engine'	# Load the class under test
 
-module Macros4Cuke # Open this namespace to get rid of module qualifier prefixes
+module Macros4Cuke
 
-describe TemplateEngine do
+module Templating # Open this namespace to get rid of module qualifier prefixes
+
+
+describe Engine do
   let(:sample_template) do
       source = <<-SNIPPET
   Given I landed in the homepage
@@ -17,29 +20,25 @@ describe TemplateEngine do
 SNIPPET
     end
 
-  # Rule for default instantiation 
-  subject { TemplateEngine.new sample_template }
+  # Rule for default instantiation
+  subject { Engine.new sample_template }
 
 
   context "Class services" do
-    # Convenience method used to shorten method call.
-    def parse_it(aText)
-      return TemplateEngine::parse(aText)
-    end
-
-    # remove enclosing chevrons <..> (if any)
+    # Helper method.
+    # Remove enclosing chevrons <..> (if any)
     def strip_chevrons(aText)
       return aText.gsub(/^<|>$/, '')
     end
 
     it "should parse an empty text line" do
       # Expectation: result should be an empty array.
-      parse_it('').should be_empty
+      Engine::parse('').should be_empty
     end
 
     it "should parse a text line without tag" do
       sample_text = 'Mary has a little lamb'
-      result = parse_it(sample_text)
+      result = Engine::parse(sample_text)
 
       # Expectation: an array with one couple: [:static, the source text]
       result.should have(1).items
@@ -48,7 +47,7 @@ SNIPPET
 
     it "should parse a text line that consists of just a tag" do
       sample_text = '<some_tag>'
-      result = parse_it(sample_text)
+      result = Engine::parse(sample_text)
 
       # Expectation: an array with one couple: [:static, the source text]
       result.should have(1).items
@@ -57,7 +56,7 @@ SNIPPET
 
     it "should parse a text line with a tag at the start" do
       sample_text = '<some_tag>some text'
-      result = parse_it(sample_text)
+      result = Engine::parse(sample_text)
 
       # Expectation: an array with two couples: [dynamic, 'some_tag'][:static, some text]
       result.should have(2).items
@@ -67,7 +66,7 @@ SNIPPET
 
     it "should parse a text line with a tag at the end" do
       sample_text = 'some text<some_tag>'
-      result = parse_it(sample_text)
+      result = Engine::parse(sample_text)
 
       # Expectation: an array with two couples: [:static, some text] [dynamic, 'some_tag']
       result.should have(2).items
@@ -77,7 +76,7 @@ SNIPPET
 
     it "should parse a text line with a tag in the middle" do
       sample_text = 'begin <some_tag> end'
-      result = parse_it(sample_text)
+      result = Engine::parse(sample_text)
 
       # Expectation: an array with three couples:
       result.should have(3).items
@@ -88,7 +87,7 @@ SNIPPET
 
     it "should parse a text line with two tags in the middle" do
       sample_text = 'begin <some_tag>middle<another_tag> end'
-      result = parse_it(sample_text)
+      result = Engine::parse(sample_text)
 
       # Expectation: an array with items couples:
       result.should have(5).items
@@ -100,7 +99,7 @@ SNIPPET
 
       # Case: two consecutive tags
       sample_text = 'begin <some_tag><another_tag> end'
-      result = parse_it(sample_text)
+      result = Engine::parse(sample_text)
 
       # Expectation: an array with four couples:
       result.should have(4).items
@@ -112,7 +111,7 @@ SNIPPET
 
     it "should parse a text line with escaped chevrons" do
       sample_text = 'Mary has a \<little\> lamb'
-      result = parse_it(sample_text)
+      result = Engine::parse(sample_text)
 
       # Expectation: an array with one couple: [:static, the source text]
       result.should have(1).items
@@ -121,7 +120,7 @@ SNIPPET
 
     it "should parse a text line with escaped chevrons in a tag" do
       sample_text = 'begin <some_\<\\>weird\>_tag> end'
-      result = parse_it(sample_text)
+      result = Engine::parse(sample_text)
 
       # Expectation: an array with three couples:
       result.should have(3).items
@@ -133,7 +132,7 @@ SNIPPET
     it "should complain if a tag misses an closing chevron" do
       sample_text = 'begin <some_tag\> end'
       error_message = "Missing closing chevron '>'."
-      lambda { parse_it(sample_text) }.should raise_error(StandardError, error_message)
+      lambda { Engine::parse(sample_text) }.should raise_error(StandardError, error_message)
     end
 
   end # context
@@ -141,43 +140,43 @@ SNIPPET
   context "Creation and initialization" do
 
     it "should accept an empty template text" do
-      lambda { TemplateEngine.new '' }.should_not raise_error
+      lambda { Engine.new '' }.should_not raise_error
     end
 
     it "should be created with a template text" do
-      lambda { TemplateEngine.new sample_template }.should_not raise_error
+      lambda { Engine.new sample_template }.should_not raise_error
     end
 
     it "should know the source text" do
       subject.source.should == sample_template
 
       # Case of an empty template
-      instance = TemplateEngine.new ''
+      instance = Engine.new ''
       instance.source.should be_empty
     end
-    
+
     it "should complain when a placeholder is empty or blank" do
       text_w_empty_arg = sample_template.sub(/userid/, '')
       error_message = %Q|An empty or blank argument occurred in 'And I fill in "Username" with "<>"'.|
-      lambda { TemplateEngine.new text_w_empty_arg }.should raise_error(Macros4Cuke::EmptyArgumentError, error_message)      
-      
+      lambda { Engine.new text_w_empty_arg }.should raise_error(Macros4Cuke::EmptyArgumentError, error_message)
+
     end
   end
-  
+
   context "Provided services" do
-  
+
     it "should know the variable(s) it contains" do
       subject.variables == [:userid, :password]
 
       # Case of an empty source template text
-      instance = TemplateEngine.new ''
+      instance = Engine.new ''
       instance.variables.should be_empty
     end
-    
+
     it "should render the text given the actuals" do
       locals = {'userid' => "johndoe"}
-      
-      rendered_text = subject.render(nil, locals)
+
+      rendered_text = subject.render(Object.new, locals)
       expected = <<-SNIPPET
   Given I landed in the homepage
   # The credentials are entered here
@@ -197,10 +196,10 @@ SNIPPET
   And I fill in "Password" with "holmes"
   And I click "Sign in"
 SNIPPET
-      
+
 
       # Case of an empty source template text
-      instance = TemplateEngine.new ''
+      instance = Engine.new ''
       instance.render(nil, {}).should be_empty
     end
   end
@@ -209,4 +208,6 @@ 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.13
+  version: 0.2.14
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-02 00:00:00.000000000 Z
+date: 2013-05-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cucumber
@@ -49,6 +49,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- .yardopts
 - cucumber.yml
 - CHANGELOG.md
 - LICENSE.txt
@@ -60,7 +61,7 @@ files:
 - lib/macros4cuke/macro-collection.rb
 - lib/macros4cuke/macro-step-support.rb
 - lib/macros4cuke/macro-step.rb
-- lib/macros4cuke/template-engine.rb
+- lib/macros4cuke/templating/engine.rb
 - features/demo01.feature
 - features/demo02.feature
 - features/demo03.feature
@@ -72,8 +73,9 @@ files:
 - features/support/macro_support.rb
 - spec/spec_helper.rb
 - spec/macros4cuke/macro-collection_spec.rb
+- spec/macros4cuke/macro-step-support_spec.rb
 - spec/macros4cuke/macro-step_spec.rb
-- spec/macros4cuke/template-engine_spec.rb
+- spec/macros4cuke/templating/engine_spec.rb
 homepage: https://github.com/famished-tiger/Macros4Cuke
 licenses:
 - MIT