yard-nrser-cucumber 0.1.0

data/lib/yard/code_objects/cucumber/scenario.rb

@@ -0,0 +1,25 @@
+
+require 'active_support/core_ext/string/filters'
+
+module YARD::CodeObjects::Cucumber
+
+  class Scenario < NamespaceObject
+
+    attr_accessor :value, :comments, :keyword, :description, :steps, :tags, :feature
+
+    def initialize(namespace, name)
+      super(namespace, name.to_s.strip)
+      @comments = @description = @keyword = @value = @feature = nil
+      @steps = []
+      @tags = []
+    end
+
+    def background?
+      @keyword == "Background"
+    end
+
+    def outline?
+      false
+    end
+  end
+end

data/lib/yard/code_objects/cucumber/scenario_outline.rb

@@ -0,0 +1,68 @@
+module YARD::CodeObjects::Cucumber
+  class ScenarioOutline < NamespaceObject
+
+    attr_accessor :value, :comments, :keyword, :description, :steps, :tags, :feature
+    attr_accessor :scenarios, :examples
+
+    def initialize(namespace, name)
+      super(namespace, name.to_s.strip)
+      @comments = @description = @value = @feature = nil
+      @steps = []
+      @tags = []
+      @scenarios = []
+      @examples = []
+    end
+
+    def background?
+      false
+    end
+
+    def outline?
+      true
+    end
+
+    def examples?
+      @examples.find { |example| example.rows }
+    end
+
+    class Examples
+
+      attr_accessor :name, :line, :keyword, :comments, :rows, :tags, :scenario
+
+      # The first row of the rows contains the headers for the table
+      def headers
+        rows.first
+      end
+
+      # The data of the table starts at the second row. When there is no data then
+      # return a empty string.
+      def data
+        rows ? rows[1..-1] : ""
+      end
+
+      def values_for_row(row)
+        hash = {}
+
+        headers.each_with_index do |header, index|
+          hash[header] = data[row][index]
+        end
+
+        hash
+      end
+
+      def to_hash
+        hash = {}
+
+        rows.each_with_index do |header, index|
+          hash[header] = rows.collect { |row| row[index] }
+        end
+
+        hash
+      end
+
+      def initialize(parameters = {})
+        parameters.each { |key, value| send("#{key.to_sym}=", value) if respond_to? "#{key.to_sym}=" }
+      end
+    end
+  end
+end

data/lib/yard/code_objects/cucumber/step.rb

@@ -0,0 +1,41 @@
+module YARD::CodeObjects::Cucumber
+  class Step < Base
+
+    attr_accessor :comments,
+                  :definition,
+                  :examples,
+                  :keyword,
+                  :scenario,
+                  :table,
+                  :text,
+                  :transforms,
+                  :value
+
+    def initialize(namespace, name)
+      super(namespace, name.to_s.strip)
+      @comments = @definition = @description = @keyword = @table = @text = @value = nil
+      @examples = {}
+      @transforms = []
+    end
+
+    def has_table?
+      !@table.nil?
+    end
+
+    def has_text?
+      !@text.nil?
+    end
+
+    def definition=(stepdef)
+      @definition = stepdef
+
+      unless stepdef.steps.map(&:files).include?(files)
+        stepdef.steps << self
+      end
+    end
+
+    def transformed?
+      !@transforms.empty?
+    end
+  end
+end

data/lib/yard/code_objects/cucumber/tag.rb

@@ -0,0 +1,31 @@
+module YARD::CodeObjects::Cucumber
+  class Tag < NamespaceObject
+
+    attr_accessor :value, :owners, :total_scenarios
+
+    def features
+      @owners.find_all { |owner| owner.is_a?(Feature) }
+    end
+
+    def scenarios
+      all = @owners.find_all do |owner|
+        owner.is_a?(Scenario) || owner.is_a?(ScenarioOutline) || ()
+      end
+
+      @owners.each do |owner|
+        if owner.is_a?(ScenarioOutline::Examples) && !all.include?(owner.scenario)
+          all << owner.scenario
+        end
+      end
+      all
+    end
+
+    def indirect_scenarios
+      @owners.find_all { |owner| owner.is_a?(Feature) }.collect { |feature| feature.scenarios }.flatten
+    end
+
+    def all_scenarios
+      scenarios + indirect_scenarios
+    end
+  end
+end

data/lib/yard/code_objects/step_definition.rb

@@ -0,0 +1,4 @@
+module YARD::CodeObjects
+  class StepDefinitionObject < StepTransformerObject;
+  end
+end

data/lib/yard/code_objects/step_transform.rb

@@ -0,0 +1,4 @@
+module YARD::CodeObjects
+  class StepTransformObject < StepTransformerObject;
+  end
+end

data/lib/yard/code_objects/step_transformer.rb

@@ -0,0 +1,94 @@
+module YARD::CodeObjects
+  class StepTransformerObject < Base
+
+    include Cucumber::LocationHelper
+
+    attr_reader :constants, :keyword, :source, :value, :literal_value
+    attr_accessor :steps, :pending, :substeps
+
+    # This defines an escape pattern within a string or regex:
+    #     /^the first #{CONSTANT} step$/
+    #
+    # This is used below in the value to process it if there happen to be
+    # constants defined here.
+    #
+    # @note this does not handle the result of method calls
+    # @note this does not handle multiple constants within the same escaped area
+    #
+    def escape_pattern
+      /#\{\s*(\w+)\s*\}/
+    end
+
+    #
+    # When requesting a step tranformer object value, process it, if it hasn't
+    # alredy been processed, replacing any constants that may be lurking within
+    # the value.
+    #
+    # Processing it means looking for any escaped characters that happen to be
+    # CONSTANTS that could be matched and then replaced. This is done recursively
+    # as CONSTANTS can be defined with more CONSTANTS.
+    #
+    def value
+      unless @processed
+        @processed = true
+        until (nested = constants_from_value).empty?
+          nested.each {|n| @value.gsub!(value_regex(n),find_value_for_constant(n)) }
+        end
+      end
+
+      @value
+    end
+
+    #
+    # Set the literal value and the value of the step definition.
+    #
+    # The literal value is as it appears in the step definition file with any
+    # constants. The value, when retrieved will attempt to replace those
+    # constants with their regex or string equivalents to hopefully match more
+    # steps and step definitions.
+    #
+    #
+    def value=(value)
+      @literal_value = format_source(value)
+      @value = format_source(value)
+
+      @steps = []
+      value
+    end
+
+    # Generate a regex with the step transformers value
+    def regex
+      @regex ||= /#{strip_regex_from(value)}/
+    end
+
+    # Look through the specified data for the escape pattern and return an array
+    # of those constants found. This defaults to the @value within step transformer
+    # as it is used internally, however, it can be called externally if it's
+    # needed somewhere.
+    def constants_from_value(data=@value)
+      data.scan(escape_pattern).flatten.collect { |value| value.strip }
+    end
+
+    protected
+
+    #
+    # Looking through all the constants in the registry and returning the value
+    # with the regex items replaced from the constnat if present
+    #
+    def find_value_for_constant(name)
+      constant = YARD::Registry.all(:constant).find{|c| c.name == name.to_sym }
+      log.warn "StepTransformer#find_value_for_constant : Could not find the CONSTANT [#{name}] using the string value." unless constant
+      constant ? strip_regex_from(constant.value) : name
+    end
+
+    # Return a regex of the value
+    def value_regex(value)
+      /#\{\s*#{value}\s*\}/
+    end
+
+    # Step the regex starting / and ending / from the value
+    def strip_regex_from(value)
+      value.gsub(/^\/|\/$/,'')
+    end
+  end
+end

data/lib/yard/handlers/constant_transform_handler.rb

@@ -0,0 +1,98 @@
+# There might be a nicer way to decorate this class but with my limited knowledge could only get this handler
+# to be applied after the default constant handler by inheriting from the default constant handler.
+# This is required so that the value assigned from the transform is not overridden in the registry by the
+# default handler
+class YARD::Handlers::Ruby::ConstantTransformHandler < YARD::Handlers::Ruby::ConstantHandler
+  include YARD::Handlers::Ruby::StructHandlerMethods
+  handles :assign
+
+  namespace_only
+
+  process do
+    begin
+      if statement[1][0][0] == "Transform"
+        name = statement[0][0][0]
+        # Move the docstring to the transform statement
+        statement[1].docstring = statement.docstring
+        # Set the docstring on the constant to reference the transform that will be processed
+        statement.docstring = "Reference to {#{YARD::CodeObjects::Cucumber::CUCUMBER_STEPTRANSFORM_NAMESPACE}::#{name} transform}"
+        value = statement[1][1].source
+        value = substitute(value)
+        value = convert_captures(strip_anchors(value))
+        instance = register ConstantObject.new(namespace, name) {|o| o.source = statement; o.value = value }
+        # specify the owner so that the transform can use the registered constant's name
+        parse_block(statement[1], {:owner => instance})
+      elsif statement[1][0][0] == "ParameterType"
+        name = statement[0][0][0]
+        # Move the docstring to the transform statement
+        statement[1].docstring = statement.docstring
+        # Set the docstring on the constant to reference the transform that will be processed
+        statement.docstring = "Reference to {#{YARD::CodeObjects::Cucumber::CUCUMBER_STEPTRANSFORM_NAMESPACE}::#{name} transform}"
+
+        value = find(statement, :label, 'regexp:').parent.children[1].source
+
+        value = substitute(value)
+        value = convert_captures(strip_anchors(value))
+        instance = register ConstantObject.new(namespace, name) {|o| o.source = statement; o.value = value }
+        # specify the owner so that the transform can use the registered constant's name
+        parse_block(statement[1], {:owner => instance})
+      end
+    rescue
+      # This supresses any errors where any of the statement elements are out of bounds. 
+      # In this case the or in cases where the object being assigned is not a Transform
+      # the default constant handler will already have performed the relevant action
+    end
+  end
+
+  private
+
+  def find(node, node_type, value)
+    node.traverse { |child| return(child) if node_type == child.type && child.source == value }
+    self
+  end
+
+  # Cucumber's Transform object overrides the to_s function and strips
+  # the anchor tags ^$ and any captures so that id it is interpolated in a step definition
+  # the it can appear anywhere in the step without being effected by position or captures
+  def convert_captures(regexp_source)
+    regexp_source
+      .gsub(/(\()(?!\?[<:=!])/,'(?:')
+      .gsub(/(\(\?<)(?![=!])/,'(?:<')
+  end
+
+  def strip_anchors(regexp_source)
+    regexp_source.
+      gsub(/(^\(\/|\/\)$)/, '').
+      gsub(/(^\^|\$$)/, '')
+  end
+
+  # Support for interpolation in the Transform's Regex
+  def substitute(data)
+    until (nested = constants_from_value(data)).empty?
+      nested.each {|n| data.gsub!(value_regex(n),find_value_for_constant(n)) }
+    end
+    data
+  end
+
+  def constants_from_value(data)
+    escape_pattern = /#\{\s*(\w+)\s*\}/
+    data.scan(escape_pattern).flatten.collect { |value| value.strip }
+  end
+
+  # Return a regex of the value
+  def value_regex(value)
+    /#\{\s*#{value}\s*\}/
+  end
+
+  def find_value_for_constant(name)
+    constant = YARD::Registry.all(:constant).find{|c| c.name == name.to_sym }
+    log.warn "ConstantTransformHandler#find_value_for_constant : Could not find the CONSTANT [#{name}] using the string value." unless constant
+    constant ? strip_regex_from(constant.value) : name
+  end
+
+  # Step the regex starting / and ending / from the value
+  def strip_regex_from(value)
+    value.gsub(/^\/|\/$/,'')
+  end
+
+end

data/lib/yard/handlers/cucumber/base.rb

@@ -0,0 +1,21 @@
+module YARD
+  module Handlers
+    module Cucumber
+
+      class Base < Handlers::Base
+        class << self
+          include Parser::Cucumber
+          def handles?(node)
+            handlers.any? do |a_handler|
+              #log.debug "YARD::Handlers::Cucumber::Base#handles?(#{node.class})"
+              node.class == a_handler
+            end
+          end
+          include Parser::Cucumber
+        end
+      end
+
+      Processor.register_handler_namespace :feature, Cucumber
+    end
+  end
+end

data/lib/yard/handlers/cucumber/feature_handler.rb

@@ -0,0 +1,131 @@
+module YARD
+  module Handlers
+    module Cucumber
+      class FeatureHandler < Base
+
+        handles CodeObjects::Cucumber::Feature
+
+        def process
+          #
+          # Features have already been created when they were parsed. So there
+          # is no need to process the feature further. Previously this is where
+          # feature steps were matched to step definitions and step definitions
+          # were matched to step transforms. This only worked if the feature
+          # files were were assured to be processed last which was accomplished
+          # by overriding YARD::SourceParser to make it load file in a similar
+          # order as Cucumber.
+          #
+          # As of YARD 0.7.0 this is no longer necessary as there are callbacks
+          # that can be registered after all the files have been loaded. That
+          # callback _after_parse_list_ is defined below and performs the
+          # functionality described above.
+          #
+        end
+
+        #
+        # Register, once, when that when all files are finished to perform
+        # the final matching of feature steps to step definitions and step
+        # definitions to step transforms.
+        #
+        YARD::Parser::SourceParser.after_parse_list do |files,globals|
+          # For every feature found in the Registry, find their steps and step
+          # definitions...
+          YARD::Registry.all(:feature).each do |feature|
+            log.debug "Finding #{feature.file} - steps, step definitions, and step transforms"
+            FeatureHandler.match_steps_to_step_definitions(feature)
+          end
+
+        end
+
+        class << self
+
+          @@step_definitions = nil
+          @@step_transforms = nil
+
+          def match_steps_to_step_definitions(statement)
+            # Create a cache of all of the step definitions and the step transforms
+            @@step_definitions = cache(:stepdefinition) unless @@step_definitions
+            @@step_transforms = cache(:steptransform) unless @@step_transforms
+
+            if statement
+              # For the background and the scenario, find the steps that have definitions
+              process_scenario(statement.background) if statement.background
+
+              statement.scenarios.each do |scenario|
+                if scenario.outline?
+                  #log.info "Scenario Outline: #{scenario.value}"
+                  scenario.scenarios.each_with_index do |example,index|
+                    #log.info " * Processing Example #{index + 1}"
+                    process_scenario(example)
+                  end
+                else
+                  process_scenario(scenario)
+                end
+              end
+
+
+            else
+              log.warn "Empty feature file.  A feature failed to process correctly or contains no feature"
+            end
+
+          rescue YARD::Handlers::NamespaceMissingError
+          rescue Exception => exception
+            log.error "Skipping feature because an error has occurred."
+            log.debug "\n#{exception}\n#{exception.backtrace.join("\n")}\n"
+          end
+
+          #
+          # Store all comparable items with their compare_value as the key and the item as the value
+          # - Reject any compare values that contain escapes #{} as that means they have unpacked constants
+          #
+          def cache(type)
+            YARD::Registry.all(type).inject({}) do |hash,item|
+              hash[item.regex] = item if item.regex
+              hash
+            end
+          end
+
+          # process a scenario
+          def process_scenario(scenario)
+            scenario.steps.each {|step| process_step(step) }
+          end
+
+          # process a step
+          def process_step(step)
+            match_step_to_step_definition_and_transforms(step)
+          end
+
+          #
+          # Given a step object, attempt to match that step to a step
+          # transformation
+          #
+          def match_step_to_step_definition_and_transforms(step)
+            @@step_definitions.each_pair do |stepdef,stepdef_object|
+              stepdef_matches = step.value.match(stepdef)
+
+              if stepdef_matches
+                step.definition = stepdef_object
+                stepdef_matches[1..-1].each do |match|
+                  @@step_transforms.each do |steptrans,steptransform_object|
+                    if steptrans.match(match)
+                      step.transforms << steptransform_object
+                      steptransform_object.steps << step
+                    end
+                  end
+                end
+
+                # Step has been matched to step definition and step transforms
+                # TODO: If the step were to match again then we would be able to display ambigous step definitions
+                break
+
+              end
+
+            end
+
+          end
+
+        end
+      end
+    end
+  end
+end