macros4cuke 0.3.17 → 0.3.18

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 0.3.18 / 2013-05-21
+* [FEATURE] Support for sub-steps having multiline text arguments (docstring).
+* [CHANGE] Method MacroStep#expand passes also built-in arguments to template engine.
+* [CHANGE] Method MacroStep#validate_phrase_args does not apply validations on built-in arguments.
+* [CHANGE] File `macro-step_spec.rb`: Added one example to test the insertion of triple quotes.
+* [NEW] File `multiline.feature` added in examples/features/ folder.
+* [CHANGE] File `README.md`: Added section 'Sub-steps with multiline text argument'
+
 ## 0.3.17 / 2013-05-20
 * [CHANGE] File `README.md`: Added dynamic dependencies badge (Gemnasium).
 

data/README.md

@@ -236,7 +236,7 @@ The next example is based on one of the demo feature files:
   """
 ```
 
-This step can be used like this:
+This step can be used like this:  
 ```cucumber
   When I [enter my address as follows]:"  
   |lastname|Doe|  
@@ -272,13 +272,13 @@ Taking again a previous example of a -partial- macro-step definition:
   """
 ```
 
-The following step invokation is invalid:
+The following step invokation is invalid:  
 ```cucumber
   When I [travel from "San Francisco" to via "Las Vegas"]
 ```
 
 The issue is: the destination value is missing, Macros4Cuke won't be able to find a step with that syntax.  
-The next invokation is syntactically correct for Macros4Cuke:
+The next invokation is syntactically correct for Macros4Cuke:  
 ```cucumber
   When I [travel from "San Francisco" to "" via "Las Vegas"]
 ```
@@ -290,6 +290,47 @@ For any argument that can receive a value through a data table, three situations
 2. A row for that argument and an empty text value are specified at invokation. The argument is bound to an empty text.  
 3. There is no row for that argument. The argument is unbound (nil) but is rendered as an empty text.  
 
+## Sub-steps with multiline text argument ##
+- __Question__: is it possible to define a macro-step with a sub-step that itself
+ uses a multiline text argument (also called a docstring)?  
+- __Answer__: Yes but there is a catch.
+
+Consider the following attempt of a macro-step definition:  
+```cucumber
+  Given I define the step "* I [make a long journey]" to mean:
+  """
+    When I visit the cities:
+    """
+    Amsterdam
+    Brussels
+    Copenhagen
+    """
+  """
+```
+
+This will result in an error. The issue is caused by the nesting of triple quotes:
+Cucumber simply doesn't allow this. In fact, the error is reported by [Gherkin](https://github.com/cucumber/gherkin), 
+a component used by Cucumber.  
+As Gherkin has other [issues](https://github.com/cucumber/gherkin/issues/124) with docstrings, we
+need a workaround today until the fixes are applied.  
+The workaround is the following:  
+- There exists in Macros4Cuke a predefined sub-step argument called __\<quotes\>__ and its value
+is set to a triple quote sequence """.  
+- Use it everywhere you want to place nested triple quotes.
+
+Thus to make the previous example work, one must change it like follows:  
+```cucumber
+  Given I define the step "* I [make a long journey]" to mean:
+  """
+    When I visit the cities:
+    <quotes>
+    Amsterdam
+    Brussels
+    Copenhagen
+    <quotes>
+  """
+```
+
 
 ## Conditional sections in substeps. ##
 To make the macros more flexible, it is possible to define conditional sections in the substep sequence.  
@@ -377,7 +418,7 @@ This last argument becomes important in the context of user acceptance testing,
  every tester is also Rubyist is -alas!- far from the truth.
 
  
-Macros with Cucumber is highly debated topic, so it is always wise to know what other people say about it:  
+Macros with Cucumber is highly debated topic, so it is good to know what other people say about it:  
 [Support for Macros] (https://github.com/cucumber/gherkin/issues/178)  
 [Substeps - macro request for the nth time] (http://grokbase.com/t/gg/cukes/133ey063b8/cucumber-substeps-macro-request-for-the-nth-time)
 

data/examples/demo/features/multiline.feature

@@ -0,0 +1,30 @@
+# File: multiline.feature
+
+Feature: Show how multiline text inside macros
+  As a Cuke user
+  So that I enjoy writing scenario.
+
+
+Scenario: Using a step with multiline text argument
+  When I visit the cities:
+  """
+  Amsterdam
+  Brussels
+  Copenhagen
+  """
+
+Scenario: Definition of macro-step having a substep with multiline text
+  Given I define the step "* I [make a long journey from <origin> to <destination>]" to mean:
+  """
+  When I visit the cities:
+  <quotes>
+  <origin>
+  Amsterdam
+  Brussels
+  Copenhagen
+  <destination>
+  <quotes>
+  """
+
+  # Now use it...
+  When I [make a long journey from "London" to "Oslo"]

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

@@ -7,15 +7,23 @@ When(/^I leave '(.*)'$/) do |city|
 end
 
 
-When(/^I visit (.+)$/) do |city|
+When(/^I visit (\S+)$/) do |city|
  show "I visit #{city}"
 end
 
 
+# This step uses a multiline text argument
+When(/^I visit the cities:$/) do |cities_raw|
+ cities = cities_raw.split(/\r\n?|\n/)
+ cities.each { |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

data/lib/macros4cuke/constants.rb

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

data/lib/macros4cuke/macro-step.rb

@@ -16,6 +16,11 @@ module Macros4Cuke # Module used as a namespace
 # The actual values bound to these arguments
 # are passed to the sub-steps at execution time.
 class MacroStep
+  # The set of predefined macro argument constant values.
+  BuiltinParameters = {
+    'quotes' => '"""'
+  }
+  
   # A template engine that expands the sub-steps upon request.
   attr_reader(:renderer)
   
@@ -28,7 +33,6 @@ class MacroStep
   # The list of macro argument names (as appearing in the substeps 
   # and in the macro phrase).
   attr_reader(:args)
-
   
   # Constructor.
   # @param aMacroPhrase[String] The text from the macro step definition 
@@ -110,11 +114,15 @@ class MacroStep
   # Render the steps from the template, given the values
   # taken by the parameters
   # @param aPhrase [String] an instance of the macro phrase.
-  # @param rawData [Array or nil] An Array with coupples of the form: 
+  # @param rawData [Array or nil] An Array with couples of the form: 
   # [macro argument name, a value].
   #   Multiple rows with same argument name are acceptable.
   def expand(aPhrase, rawData)
     params = validate_params(aPhrase, rawData)
+    
+    # Add built-in constants if necessary.
+    params = BuiltinParameters.merge(params)
+
     return renderer.render(nil, params)
   end
 
@@ -132,7 +140,6 @@ private
     quoted_values.each_with_index do |val, index|
       macro_parameters[phrase_args[index]] = val
     end
-    
 
     unless rawData.nil?
       rawData.each do |(a_key, value)|
@@ -153,7 +160,7 @@ private
   end
 
 
-  
+
 
   # Retrieve from the macro phrase, all the text between <..> or double quotes.
   # Returns an array. Each of its elements corresponds to quoted text.
@@ -180,7 +187,7 @@ private
     
     return args
   end
-  
+
   # Return the substeps text after some transformation
   # [theSubstepsSource] The source text of the steps 
   # to be expanded upon macro invokation.
@@ -208,8 +215,9 @@ private
     # and the macro-step does not use data table.
     unless use_table?
       substepsVars.each do |substep_arg|
-        unless thePhraseArgs.include? substep_arg
-          raise UnreachableSubstepArgument.new(substep_arg)
+        unless (thePhraseArgs.include?(substep_arg) ||
+        BuiltinParameters.include?(substep_arg))
+          raise UnreachableSubstepArgument.new(substep_arg) 
         end
       end      
     end

data/lib/macros4cuke/templating/engine.rb

@@ -166,9 +166,8 @@ public
 end # class
 
 
-# Represents a section in a template, that is, 
-# a set of template elements for which its rendition depends
-# on the (in)existence of an actual value bound to the variable name.
+# A specialized section in a template for which its rendition
+# depends on the (in)existence of an actual value bound to the variable name.
 class ConditionalSection < Section
   # A boolean that indicates whether the rendition condition is 
   # the existence of a value for the variable (true)

data/spec/macros4cuke/macro-step_spec.rb

@@ -94,7 +94,7 @@ 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, [ %w(password no-secret) ])
@@ -109,7 +109,7 @@ 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'."
@@ -118,6 +118,25 @@ SNIPPET
         UnknownArgumentError, error_message)
     end
 
+
+    it "should expand built-in variables" do
+      phrase = "do nothing useful"
+      substeps = <<-SNIPPET
+  Given I travel through:
+  <quotes>
+  London
+  Paris
+  San Francisco
+  <quotes>
+SNIPPET
+       
+      instance = MacroStep.new(phrase, substeps, true)
+      actual = instance.expand(phrase, [])
+      expected = substeps.gsub(/<quotes>/, '"""')
+      actual.should == expected
+    end
+   
+
   end # context
 
 end # describe

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: macros4cuke
 version: !ruby/object:Gem::Version
-  version: 0.3.17
+  version: 0.3.18
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-20 00:00:00.000000000 Z
+date: 2013-05-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cucumber
@@ -104,6 +104,7 @@ files:
 - lib/macros4cuke/templating/engine.rb
 - examples/demo/cucumber.yml
 - examples/demo/features/basic.feature
+- examples/demo/features/multiline.feature
 - examples/demo/features/step_definitions/step_defs.rb
 - examples/demo/features/step_definitions/use_macro_steps.rb
 - examples/demo/features/support/env.rb