macros4cuke 0.0.02 → 0.1.00

data/features/demo01.feature

@@ -4,14 +4,12 @@ Feature: Show the use of a basic macro
   As a Cuke user
   So that I enjoy writing scenario.
 
-# The background section is THE good place to define your macros.
-# Since the steps from this section are pre-pended to the steps of every scenario (outline),
-# the macros will be available to every scenario in the feature file.
-Background:
+
+Scenario: Definition of a simple macro-step
   # The next step creates a macro(-step)
-  # The syntax of the new macro-step is specified between the < ... > delimiters.
+  # 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 "When I [log in]" to mean:
   """
   Given I landed in the homepage
   When I click "Sign in"

data/features/demo02.feature

@@ -4,15 +4,13 @@ Feature: Show the use of a basic macro with one argument
   As a Cuke user
   So that I enjoy writing scenario.
 
-# The background section is THE good place to define your macros.
-# Since the steps from this section are pre-pended to the steps of every scenario (outline),
-# the macros will be available to every scenario in the feature file.
-Background:
+
+Scenario: Creating a basic scenario with one argument
   # The next step creates a macro(-step)
-  # The syntax of the new macro-step is specified between the < ... > delimiters.
+  # 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 double(triple) curly braces {{...}} as required by the Mustache template library.
-  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"

data/features/demo03.feature

@@ -4,15 +4,12 @@ Feature: Show the use of a basic macro with multiple arguments
   As a Cuke user
   So that I enjoy writing scenario.
 
-# The background section is THE good place to define your macros.
-# Since the steps from this section are pre-pended to the steps of every scenario (outline),
-# the macros will be available to every scenario in the feature file.
-Background:
-  # The next step creates a macro(-step)
-  # The syntax of the new macro-step is specified between the < ... > delimiters.
+
+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 argument is put between double(triple) curly braces {{...}} as required by the Mustache template library.
-  Given I define the step <When I [enter my userid {{userid}} and password {{password}}]> to mean:
+  Given I define the step "When I [enter my userid {{userid}} and password {{password}}]" to mean:
   """
   Given I landed in the homepage
   When I click "Sign in"
@@ -36,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 "When 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"]

data/features/demo04.feature

@@ -4,15 +4,13 @@ Feature: Show the use of a macro with multiple arguments in a table
   As a Cuke user
   So that I enjoy writing scenario.
 
-# The background section is THE good place to define your macros.
-# Since the steps from this section are pre-pended to the steps of every scenario (outline),
-# the macros will be available to every scenario in the feature file.
-Background:
+
+Scenario: Defining a macro to be used with multiple arguments in a table
   # The next step creates a macro(-step)
-  # The syntax of the new macro-step is specified between the < ... > delimiters.
+  # 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 argument is put between double(triple) curly braces {{...}} as required by the Mustache template library.
-  Given I define the step <When I [enter my credentials as]:> to mean:
+  Given I define the step "When I [enter my credentials as]:" to mean:
   """
   Given I landed in the homepage
   When I click "Sign in"

data/features/support/env.rb

@@ -36,7 +36,6 @@ end # module
 World { Macros4Cuke::TracingWorld.new }
 
 
-
 # Macros4Cuke step two: extend the world object with the mix-in module
 # that adds the support for macros in Cucumber.
 World(Macros4Cuke::MacroStepSupport)

data/lib/macro_steps.rb

@@ -3,69 +3,44 @@
 
 
 
-=begin This step is used to define a macro-step
-Example:
-  Given I define the step <When I [create the following {{contactType}} contact]:> to mean:
-  """
-  # In the next step we use triple curly brace in order to get un-escaped text
-  When I select "<type>" from "type"
-	When I fill in "name" with "{{{name}}}"
-	And I fill in "companyName" with "{{companyName}}"
-	And I fill in "companyName2" with "{{companyName2}}"
-  """
-=end
-Given(/^I define the step <When I \[([^\]]+\]:?)> to mean:$/) do |macro_phrase, template|
+# 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"
+#  """
+
+Given(/^I define the step "When I \[([^\]]+\]:?)" to mean:$/) do |macro_phrase, template|
   add_macro(macro_phrase, template)
 end
 
-=begin This step is used to invoke a simple macro-step
+# This step is used to invoke a simple macro-step
 # Example:
-  # Here we define a simple macro-step
-  Given I define the step <When I [fly from {{origin}} to {{destination}} via {{waypoint}}]> to mean:
-  """ 
-    When I display the text "Departure: {{origin}}."
-    When I display the text "Stop at: {{waypoint}}."
-    When I display the text "Destination {{destination}}."
-  """
-=end
+#  When I [log in as "guest"]
+#
 When(/^I \[([^\]]+\])$/) do |macro_phrase|
-  macro = find_macro(macro_phrase) 
-  raise StandardError, "Undefined macro step for '[#{macro_phrase}'." if macro.nil?
-  
-  # Retrieve macro argument names and their associated value from the table
-  params = macro.validate_params(macro_phrase, nil)
-
-  # Render the steps
-  rendered_steps = macro.expand(params)
-  
-  # Execute the steps
-  steps(rendered_steps)
+  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 table argument.
 # Example:
-#  When I [create the following "Registrant" contact]:
-#  |name|John Doe|
-#  |city|Gotham City|
-#  |street| Main street|
-#  |street3| Small street|
+#  When I [enter my credentials as]:
+#  |userid  |guest      |
+#  |password|unguessable|
 When(/^I \[([^\]]+\]:)$/) do |macro_phrase, table_argument|
-  macro = find_macro(macro_phrase) 
-  raise StandardError, "Undefined macro step for '#{macro_phrase}'." if macro.nil?
-  
+  # Ensure that the second argument is of the correct type
   unless table_argument.kind_of?(Cucumber::Ast::Table)
-     raise StandardError, "This step must have a table as an argument."
+     raise StandardError, "This step must have a data table as an argument."
   end
   
-  # Retrieve macro argument names and their associated value from the table
-  params = macro.validate_params(macro_phrase, table_argument.rows_hash())
-
-  # Render the steps
-  rendered_steps = macro.expand(params)
-  
-  # Execute the steps
-  steps(rendered_steps)
+  # This will call the macro with the given phrase.
+  # The second argument consists of a hash with pairs of the kind: argument name => actual value
+  invoke_macro(macro_phrase, table_argument.rows_hash())
 end
 
 

data/lib/macros4cuke/constants.rb

@@ -3,7 +3,7 @@
 
 module Macros4Cuke # Module used as a namespace
 	# This constant keeps the current version of the gem.
-	Version = '0.0.02'
+	Version = '0.1.00'
   
   Description = "Macros for Cucumber"
 	

data/lib/macros4cuke/exceptions.rb

@@ -0,0 +1,46 @@
+# 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 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 argument #{argName}.")
+  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

@@ -0,0 +1,81 @@
+# File: macro-collection.rb
+# Purpose: Implementation of the MacroCollection class.
+
+require 'singleton'  # We'll use the Singleton design pattern for this class.
+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.
+class MacroCollection
+  include Singleton # Use the Singleton design pattern.
+
+  # A Hash with pairs of the form: phrase => MacroStep object
+  attr_reader(:macro_steps)
+
+  # 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.
+  # These steps
+  def add_macro(aPhrase, aTemplate)
+    new_macro = MacroStep.new(aPhrase, aTemplate)
+    
+    # Prevent collision of macros (macros with same phrase).
+    # This can occur if a macro was defined in a background section.
+    # An exception is raised if the phrase syntax of both macros are the     
+    if find_macro(aPhrase)
+      pp find_macro(aPhrase)
+      raise DuplicateMacroError.new(aPhrase)
+    end
+    
+    @macro_steps[new_macro.name] = 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.  
+  def render_steps(aPhrase, rawData = nil)
+
+    macro = find_macro(aPhrase) 
+    raise UnknownMacroError.new(aPhrase) if macro.nil?
+    
+    # Retrieve macro argument names and their associated value from the table
+    params = macro.validate_params(aPhrase, rawData)
+
+    # Render the steps
+    rendered_steps = macro.expand(params)
+    
+  end
+
+private
+  # Retrieve the macro, given a phrase.
+  def find_macro(aMacroPhrase)
+    return @macro_steps[MacroStep::macro_key(aMacroPhrase, :invokation)]
+  end
+
+end # class
+
+end # module
+
+
+# End of file

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

@@ -1,46 +1,48 @@
 # File: macro-step-support.rb
 
-require_relative "macro-step"
+require_relative "exceptions"
+require_relative "macro-collection"
 
 module Macros4Cuke # Module used as a namespace
 
-# Mix-in module that should be extending World objects of Cucumber.
-# Synopsis (in env.rb): 
-module MacroStepSupport 
+# 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.
-    world.clear_macro_steps()
+    # Add & initialize an instance variable for macro support.  
+    MacroCollection::instance.init()
   end
 
-  
+
 public
-  # Remove all macro steps
-  def clear_macro_steps()
-    @macro_steps = {}
-  end
-  
-  # Return true iff the host has a macro with the given key.
-  def has_macro?(aMacroPhrase, mode)
-    key = MacroStep::macro_key(aMacroPhrase, 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.
+  # These steps
   def add_macro(aPhrase, aTemplate)
-    if has_macro?(aPhrase, :definition)
-      raise StandardError, "Macro step for '[#{aPhrase}' already exist."
-    else
-      new_macro = MacroStep.new(aPhrase, aTemplate)
-      @macro_steps[new_macro.name] = new_macro
-    end
+    MacroCollection::instance.add_macro(aPhrase, aTemplate)
   end
+
   
-  # Retrieve the macro, given a phrase.
-  def find_macro(aMacroPhrase)
-    return @macro_steps[MacroStep::macro_key(aMacroPhrase, :invokation)]
+  # 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

data/lib/macros4cuke/macro-step.rb

@@ -5,7 +5,8 @@ require 'mustache'  # Load the Mustache template library
 
 module Macros4Cuke # Module used as a namespace
 
-# In essence, a macro step object represents a Cucumber step that stands for a sequence of steps.
+# In essence, a macro step object represents a Cucumber step that is itself
+# an aggregation of lower-level Cucumber steps.
 class MacroStep
   # A Mustache instance that expands the steps upon request.
   attr_reader(:renderer)
@@ -18,6 +19,7 @@ class MacroStep
   
   # The list of macro argument names (as appearing in the Mustache template and in the macro phrase).
   attr_reader(:args)
+
   
   # Constructor.
   # [aMacroPhrase]
@@ -106,7 +108,7 @@ class MacroStep
 
     unless rawData.nil?
       rawData.each do |(key, value)|
-        raise StandardError,"Unknown macro argument #{key}." unless @args.include? key
+        raise UnknownArgumentError.new(key) unless @args.include? key
         if macro_parameters.include? key
           if macro_parameters[key].kind_of?(Array)
              macro_parameters[key] << value
@@ -122,6 +124,7 @@ class MacroStep
     return macro_parameters
   end
 
+
   
 private
   # Retrieve from the macro phrase, all the text between "mustaches" or double quotes.
@@ -140,7 +143,7 @@ private
       when :invokation
         /"([^"]*)"/
       else
-        raise Standard, "Internal error: Unknown mode argument #{mode}"
+        raise InternalError, "Internal error: Unknown mode argument #{mode}"
     end
     raw_result = aMacroPhrase.scan(pattern)
     return raw_result.flatten.compact
@@ -152,7 +155,7 @@ private
   def add_tags_multi(tokens)
     first_token = tokens.shift
     unless first_token == :multi
-      raise StandardError, "Expecting a :multi token instead of a #{first_token}"
+      raise InternalError, "Expecting a :multi token instead of a #{first_token}"
     end
     
     tokens.each do |an_opcode|
@@ -166,7 +169,7 @@ private
         when String
           #Do nothing...
         else
-          raise StandardError, "Unknown Mustache token type #{an_opcode.first}"
+          raise InternalError, "Unknown Mustache token type #{an_opcode.first}"
       end
     end
   end
@@ -178,8 +181,8 @@ private
     case mustache_opcode[0]
       when :etag
         triplet = mustache_opcode[1]
-        raise StandardError, "expected 'mustache' token instead of '#{triplet[0]}'" unless triplet[0] == :mustache
-        raise StandardError, "expected 'fetch' token instead of '#{triplet[1]}'" unless triplet[1] == :fetch
+        raise InternalError, "expected 'mustache' token instead of '#{triplet[0]}'" unless triplet[0] == :mustache
+        raise InternalError, "expected 'fetch' token instead of '#{triplet[1]}'" unless triplet[1] == :fetch
         @args << triplet.last
         
       when :fetch
@@ -189,7 +192,7 @@ private
         add_tags_section(mustache_opcode)
 
       else
-        raise StandardError, "Unknown Mustache token type #{mustache_opcode.first}"        
+        raise InternalError, "Unknown Mustache token type #{mustache_opcode.first}"        
     end
   end
   
@@ -208,7 +211,7 @@ private
         when String
           return
         else
-          raise StandardError, "Unknown Mustache token type #{op.first}"
+          raise InternalError, "Unknown Mustache token type #{op.first}"
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: macros4cuke
 version: !ruby/object:Gem::Version
-  version: 0.0.02
+  version: 0.1.00
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-04-21 00:00:00.000000000 Z
+date: 2013-04-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -60,8 +60,8 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 description: ! "\tMacros4Cuke is a lightweight library that adds a macro facility
-  your Cucumber scenarios.\n  In short, you will be able to create new steps that
-  will replace a sequence of lower-level steps. \n"
+  your Cucumber scenarios.\n  In short, you can create new steps that replace a sequence
+  of lower-level steps. \n"
 email: famished.tiger@yahoo.com
 executables: []
 extensions: []
@@ -74,6 +74,8 @@ files:
 - 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
 - features/demo01.feature