yard-lucid 0.1.0

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

@@ -0,0 +1,66 @@
+module YARD::CodeObjects::Lucid
+  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
+
+      # 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/lucid/step.rb

@@ -0,0 +1,32 @@
+module YARD::CodeObjects::Lucid
+  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/lucid/tag.rb

@@ -0,0 +1,21 @@
+module YARD::CodeObjects::Lucid
+  class Tag < NamespaceObject
+    attr_accessor :value, :owners
+
+    def features
+      @owners.find_all { |owner| owner.is_a?(Feature) }
+    end
+
+    def scenarios
+      @owners.find_all { |owner| owner.is_a?(Scenario) || owner.is_a?(ScenarioOutline) }
+    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,3 @@
+module YARD::CodeObjects
+  class StepDefinitionObject < StepTransformerObject ; end
+end

data/lib/yard/code_objects/step_transform.rb

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

data/lib/yard/code_objects/step_transformer.rb

@@ -0,0 +1,85 @@
+module YARD::CodeObjects
+  class StepTransformerObject < Base
+
+    include Lucid::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. It's important to note that this will not
+    # handle the result of method calls and it will not handle multiple
+    # constants within the same escaped area.
+    def escape_pattern
+      /#\{\s*(\w+)\s*\}/
+    end
+
+    # The idea of this is method is that when requesting a step tranform object
+    # value, process it, if it hasn't alredy been processed, replacing any
+    # constants that may be escaped within the value.
+    #
+    # Processing here means looking for any escaped characters that happen to
+    # be CONSTANTS that could be matched and then replaced. This needs to be
+    # done recursively since 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 transform 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 the
+    # step transform 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
+
+    # This looks through all the constants in the registry and returns 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
+
+    # Strip the regex starting / and ending / from the value.
+    def strip_regex_from(value)
+      value.gsub(/^\/|\/$/,'')
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+module YARD
+  module Handlers
+    module Lucid
+      class Base < Handlers::Base
+        class << self
+          include Parser::Lucid
+          def handles?(node)
+            handlers.any? do |a_handler|
+              node.class == a_handler
+            end
+          end
+          include Parser::Lucid
+        end
+      end
+
+      Processor.register_handler_namespace :feature, Lucid
+    end
+  end
+end

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

@@ -0,0 +1,102 @@
+module YARD
+  module Handlers
+    module Lucid
+      class FeatureHandler < Base
+        handles CodeObjects::Lucid::Feature
+
+        # This method is currently not needed. It would be needed if there was
+        # further processing to be done on the features.
+        def process
+        end
+
+        # Register, once, when all files are finished. This will trigger the
+        # final matching of feature steps to step definitions and steps to
+        # transforms.
+        YARD::Parser::SourceParser.after_parse_list do |files,globals|
+          YARD::Registry.all(:feature).each do |feature|
+            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 steps and the 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?
+                  scenario.scenarios.each_with_index do |example,index|
+                    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
+
+          # The cache is used to store all comparable items with their
+          # compare_value as the key and the item as the value. This will
+          # reject any compare values that contain escapes -- #{} -- because
+          # that means the values have unpacked constants.
+          def cache(type)
+            YARD::Registry.all(type).inject({}) do |hash,item|
+              hash[item.regex] = item if item.regex
+              hash
+            end
+          end
+
+          def process_scenario(scenario)
+            scenario.steps.each {|step| process_step(step) }
+          end
+
+          def process_step(step)
+            match_step_to_step_definition_and_transforms(step)
+          end
+
+          # Given a step object, attempt to match that step to a transform.
+          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
+
+                # A this point the step has been matched to the definition and
+                # to any transforms. As a design note, if the step were to
+                # match again, it would be possible to display any steps that
+                # are considered ambiguous.
+                # This would be a nice to have.
+                break
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/yard/handlers/step_definition_handler.rb

@@ -0,0 +1,67 @@
+# Finds and processes all the step matchers defined in the source code.
+#
+# To override the language you can define the step keywords in the YARD
+# configuration file `~./yard/config`.
+class YARD::Handlers::Ruby::StepDefinitionHandler < YARD::Handlers::Ruby::Base
+  def self.default_step_definitions
+    [ "Given", "When", "Then", "And", "But", "*" ]
+  end
+
+  def self.custom_step_definitions
+    YARD::Config.options["yard-lucid"]["language"]["step_definitions"]
+  end
+
+  def self.custom_step_definitions_defined?
+    YARD::Config.options["yard-lucid"] and
+    YARD::Config.options["yard-lucid"]["language"] and
+    YARD::Config.options["yard-lucid"]["language"]["step_definitions"]
+  end
+
+  def self.step_definitions
+    if custom_step_definitions_defined?
+      custom_step_definitions
+    else
+      default_step_definitions
+    end
+  end
+
+  step_definitions.each { |step_def| handles method_call(step_def) }
+
+  process do
+    instance = YARD::CodeObjects::StepDefinitionObject.new(step_transform_namespace, step_definition_name) do |o|
+      o.source = statement.source
+      o.comments = statement.comments
+      o.keyword = statement.method_name.source
+      o.value = statement.parameters.source
+      o.pending = pending_keyword_used?(statement.block)
+    end
+
+    obj = register instance
+    parse_block(statement[2],:owner => obj)
+  end
+
+  def pending_keyword
+    "pending"
+  end
+
+  def pending_command_statement?(line)
+    (line.type == :command || line.type == :vcall) && line.first.source == pending_keyword
+  end
+
+  def pending_keyword_used?(block)
+    code_in_block = block.last
+    code_in_block.find { |line| pending_command_statement?(line) }
+  end
+
+  def step_transform_namespace
+    YARD::CodeObjects::Lucid::LUCID_STEPTRANSFORM_NAMESPACE
+  end
+
+  def step_definition_name
+    "step_definition#{self.class.generate_unique_id}"
+  end
+
+  def self.generate_unique_id
+    @step_definition_count = @step_definition_count.to_i + 1
+  end
+end

data/lib/yard/handlers/step_transform_handler.rb

@@ -0,0 +1,28 @@
+class YARD::Handlers::Ruby::StepTransformHandler < YARD::Handlers::Ruby::Base
+  handles method_call(:Transform)
+
+  process do
+    instance = YARD::CodeObjects::StepTransformObject.new(step_transform_namespace,step_transformer_name) do |o|
+      o.source = statement.source
+      o.comments = statement.comments
+      o.keyword = statement[0].source
+      o.value = statement[1].source
+    end
+
+    obj = register instance
+    parse_block(statement[2],:owner => obj)
+  end
+
+  def step_transform_namespace
+    YARD::CodeObjects::Lucid::LUCID_STEPTRANSFORM_NAMESPACE
+  end
+
+  def step_transformer_name
+    "step_transform#{self.class.generate_unique_id}"
+  end
+
+  def self.generate_unique_id
+    @step_transformer_count = @step_transformer_count.to_i + 1
+  end
+
+end

data/lib/yard/parser/lucid/feature.rb

@@ -0,0 +1,58 @@
+require "yard"
+
+module YARD::Parser::Lucid
+  class FeatureParser < YARD::Parser::Base
+    # Each feature found creates a new FeatureParser.
+    #
+    # A Gherkin "builder" is created that will store a representation of the
+    # feature file. That feature file is then sent to the Gherkin parser.
+    # The Lucid::Parser::GherkinRepr is being used to parse the elements of
+    # the faeture file into YARD::CodeObjects.
+    def initialize(source, file = '(stdin)')
+      @builder = Lucid::Parser::GherkinRepr.new(file)
+      @tag_counts = {}
+      @parser = Gherkin::Parser.new(@builder)
+
+      @source = source
+      @file = file
+
+      @feature = nil
+    end
+
+    # When parse is called, the Gherkin parser is executed and all the feature
+    # elements that are found are sent to the various methods in the
+    # Lucid::Parser::GherkinRepr. The result of this is a syntax tree
+    # representation of the feature that contains all the scenarios and steps.
+    def parse
+      begin
+        @parser.parse(@source)
+        @feature = @builder.ast
+        return nil if @feature.nil?
+
+        # The parser used the following keywords when parsing the feature
+        # @feature.language = @parser.i18n_language.get_code_keywords.map {|word| word }
+
+      rescue Gherkin::ParserError => e
+        e.message.insert(0, "#{@file}: ")
+        warn e
+      end
+
+      self
+    end
+
+    # While the method is necessary, nothing actually happens here because all
+    # of the work is done in the parse method.
+    def tokenize
+    end
+
+    # The only enumeration that can be done at this level is the feature
+    # itself. There is no construct higher than a feature wherein a feature
+    # can be enumerated.
+    def enumerator
+      [@feature]
+    end
+  end
+
+  # Register all feature files to be processed with the above FeatureParser
+  YARD::Parser::SourceParser.register_parser_type :feature, FeatureParser, 'feature'
+end

data/lib/yard/server/adapter.rb

@@ -0,0 +1,32 @@
+module YARD
+  module Server
+    class Adapter
+      class << self
+        alias_method :yard_setup, :setup
+
+        # To provide the templates necessary for `yard-lucid` to integrate
+        # with YARD the adapter has to around-alias the setup method to place
+        # the `yard-lucid` server templates as the last template in the list.
+        #
+        # When they are normally loaded with the plugin they cause an error with
+        # the `yardoc` command. They are also not used because the YARD server
+        # templates are placed after all plugin templates.
+        def setup
+          yard_setup
+          YARD::Templates::Engine.template_paths +=
+          [File.dirname(__FILE__) + '/../../templates',File.dirname(__FILE__) + '/../../docserver']
+        end
+
+        alias_method :yard_shutdown, :shutdown
+
+        # Similar to the addition, it is good business to tear down the templates
+        # that were added by again around-aliasing the shutdown method.
+        def shutdown
+          yard_shutdown
+          YARD::Templates::Engine.template_paths -=
+          [File.dirname(__FILE__) + '/../../templates',File.dirname(__FILE__) + '/../../docserver']
+        end
+      end
+    end
+  end
+end

data/lib/yard/server/commands/list_command.rb

@@ -0,0 +1,25 @@
+module YARD
+  module Server
+    module Commands
+      # List Features powers the features menu option in `yard server`
+      class ListFeaturesCommand < ListCommand
+        def type; :features end
+
+        def items
+          Registry.load_all
+          run_verifier(Registry.all(:feature))
+        end
+      end
+
+      # List Tags powers the tags menu option in `yard server`
+      class ListTagsCommand < ListCommand
+        def type; :tags end
+
+        def items
+          Registry.load_all
+          run_verifier(Registry.all(:tag).sort_by {|t| t.value.to_s })
+        end
+      end
+    end
+  end
+end

data/lib/yard/server/router.rb

@@ -0,0 +1,23 @@
+module YARD
+  module Server
+    # The YARD::Server::Router needs the following modification,
+    # so that it will provide routing for the features and tags commands
+    # to their appropriate definitions
+    Router.class_eval do
+      alias_method :core_route_list, :route_list
+
+      # Provide the full list of features and tags
+      def route_list(library, paths)
+        if paths && !paths.empty? && paths.first =~ /^(?:features|tags)$/
+          case paths.shift
+          when "features"; cmd = Commands::ListFeaturesCommand
+          when "tags"; cmd = Commands::ListTagsCommand
+          end
+          cmd.new(final_options(library, paths)).call(request)
+        else
+          core_route_list(library,paths)
+        end
+      end
+    end
+  end
+end

data/lib/yard/templates/helpers/base_helper.rb

@@ -0,0 +1,22 @@
+module YARD::Templates::Helpers
+  module BaseHelper
+    def format_object_title(object)
+      if object.is_a?(YARD::CodeObjects::Lucid::FeatureTags)
+        "Tags"
+      elsif object.is_a?(YARD::CodeObjects::Lucid::StepTransformersObject)
+        "Steps and Transforms"
+      elsif object.is_a?(YARD::CodeObjects::Lucid::NamespaceObject)
+        "#{format_object_type(object)}#{object.value ? ": #{object.value}" : ''}"
+      elsif object.is_a?(YARD::CodeObjects::Lucid::FeatureDirectory)
+        "Feature Directory: #{object.name}"
+      else
+        case object
+        when YARD::CodeObjects::RootObject
+          "Top Level Namespace"
+        else
+          format_object_type(object) + ": " + object.path
+        end
+      end
+    end
+  end
+end

data/lib/yard-lucid/version.rb

@@ -0,0 +1,3 @@
+module YardLucid
+  VERSION = "0.1.0".freeze
+end

data/lib/yard-lucid.rb

@@ -0,0 +1,36 @@
+require "gherkin/parser"
+
+require "yard-lucid/version"
+
+require "lucid/gherkin_repr"
+
+require "yard/parser/lucid/feature"
+
+require "yard/code_objects/lucid/base"
+require "yard/code_objects/lucid/namespace_object"
+require "yard/code_objects/lucid/feature"
+require "yard/code_objects/lucid/scenario_outline"
+require "yard/code_objects/lucid/scenario"
+require "yard/code_objects/lucid/step"
+require "yard/code_objects/lucid/tag"
+require "yard/code_objects/step_transformer"
+require "yard/code_objects/step_definition"
+require "yard/code_objects/step_transform"
+
+require "yard/handlers/lucid/base"
+require "yard/handlers/lucid/feature_handler"
+require "yard/handlers/step_definition_handler"
+require "yard/handlers/step_transform_handler"
+
+require "yard/templates/helpers/base_helper"
+
+require "yard/server/adapter"
+require "yard/server/commands/list_command"
+require "yard/server/router"
+
+# This registered template works for yardoc
+YARD::Templates::Engine.register_template_path File.dirname(__FILE__) + '/templates'
+
+# The following paths are needed for the yard server
+YARD::Server.register_static_path File.dirname(__FILE__) + "/templates/default/fulldoc/html"
+YARD::Server.register_static_path File.dirname(__FILE__) + "/docserver/default/fulldoc/html"

data/yard-lucid.gemspec

@@ -0,0 +1,38 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'yard-lucid/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "yard-lucid"
+  spec.version       = YardLucid::VERSION
+  spec.authors       = ["Jeff Nyman"]
+  spec.email         = ["jeffnyman@gmail.com"]
+
+  spec.summary       = %q{YARD Documentation Generator for Gherkin-based Repositories}
+  spec.description   = %q{YARD Documentation Generator for Gherkin-based Repositories}
+  spec.homepage      = "https://github.com/jeffnyman/yard-lucid"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.14"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "pry"
+
+  spec.add_runtime_dependency "yard"
+  spec.add_runtime_dependency "gherkin", "~> 4.0"
+  spec.add_runtime_dependency "cucumber", "~> 2.0"
+
+  spec.post_install_message = %{
+(::) (::) (::) (::) (::) (::) (::) (::) (::) (::) (::) (::)
+  Yard-Lucid #{YardLucid::VERSION} has been installed.
+(::) (::) (::) (::) (::) (::) (::) (::) (::) (::) (::) (::)
+  }
+end