lucid 0.1.1 → 0.2.0

data/lib/lucid/generators/project/events-symbiont.rb

@@ -2,7 +2,7 @@ AfterConfiguration do |config|
   puts("Specs are being executed from: #{config.spec_location}")
 end
 
-Before('~@practice') do
+Before('~@practice','~@sequence') do
   @browser = Symbiont::Browser.start
 end
 

data/lib/lucid/platform.rb

@@ -2,7 +2,7 @@ require 'rbconfig'
 
 module Lucid
   unless defined?(Lucid::VERSION)
-    VERSION       = '0.1.1'
+    VERSION       = '0.2.0'
     BINARY        = File.expand_path(File.dirname(__FILE__) + '/../../bin/lucid')
     LIBDIR        = File.expand_path(File.dirname(__FILE__) + '/../../lib')
     JRUBY         = defined?(JRUBY_VERSION)

data/lib/lucid/runtime.rb

@@ -13,7 +13,7 @@ require 'lucid/runtime/orchestrator'
 
 module Lucid
   class Runtime
-    attr_reader :results
+    attr_reader :results, :orchestrator
 
     include Formatter::Duration
     include Runtime::InterfaceIO

data/lib/lucid/sequence.rb

@@ -0,0 +1,5 @@
+# This file is the starting point for the Sequence functionality.
+# It will only reference files in the sequence directory and does
+# not impact the core runtime at all.
+
+require 'lucid/sequence/sequence_support'

data/lib/lucid/sequence/sequence_errors.rb

@@ -0,0 +1,64 @@
+module Sequence
+  
+  class SequenceError < StandardError
+  end
+  
+  class DuplicateSequenceError < SequenceError
+    def initialize(phrase)
+      super("A sequence with phrase '#{phrase}' already exists.")
+    end
+  end
+
+  class UnknownSequenceError < SequenceError
+    def initialize(phrase)
+      super("Unknown sequence step with phrase: '#{phrase}'.")
+    end
+  end
+
+  class EmptyParameterError < SequenceError
+    def initialize(text)
+      super("An empty or blank parameter occurred in '#{text}'.")
+    end
+  end
+
+  class InvalidElementError < SequenceError
+    def initialize(tag, invalid_element)
+      msg = "The invalid element '#{invalid_element}' occurs in the parameter '#{tag}'."
+      super(msg)
+    end
+  end
+
+  class UselessPhraseParameter < SequenceError
+    def initialize(param)
+      super("The phrase parameter '#{param}' does not appear in any step.")
+    end
+  end
+
+  class DataTableNotFound < SequenceError
+    def initialize(phrase)
+      msg = "The step with phrase [#{phrase}]: requires a data table."
+      super(msg)
+    end
+  end
+
+  class UnknownParameterError < SequenceError
+    def initialize(name)
+      super("Unknown sequence step parameter '#{name}'.")
+    end
+  end
+
+  class AmbiguousParameterValue < SequenceError
+    def initialize(name, phrase, table)
+      msg = "The sequence parameter '#{name}' has value '#{phrase}' and '#{table}'."
+      super(msg)
+    end
+  end
+
+  class UnreachableStepParameter < SequenceError
+    def initialize(param)
+      msg = "The step parameter '#{param}' does not appear in the phrase."
+      super(msg)
+    end
+  end
+  
+end

data/lib/lucid/sequence/sequence_group.rb

@@ -0,0 +1,35 @@
+require 'singleton'
+require 'lucid/sequence/sequence_phrase'
+
+module Sequence
+  class SequenceGroup
+    include Singleton
+    
+    def add_sequence(phrase, sequence, data)
+      new_sequence = SequencePhrase.new(phrase, sequence, data)
+      raise DuplicateSequenceError.new(phrase) if find_sequence(phrase, data)
+      sequence_steps[new_sequence.key] = new_sequence
+    end
+    
+    def sequence_steps
+      @sequence_steps ||= {}
+      return @sequence_steps
+    end
+    
+    def generate_steps(phrase, data = nil)
+      data_table =! data.nil?
+      sequence = find_sequence(phrase, data_table)
+      raise UnknownSequenceError.new(phrase) if sequence.nil?
+      return sequence.expand(phrase, data)
+    end
+    
+    def clear
+      sequence_steps.clear
+    end
+    
+    def find_sequence(phrase, data)
+      key = SequencePhrase.sequence_key(phrase, data, :invoke)
+      return sequence_steps[key]
+    end
+  end
+end

data/lib/lucid/sequence/sequence_phrase.rb

@@ -0,0 +1,166 @@
+require 'lucid/sequence/sequence_template'
+require 'lucid/sequence/sequence_errors'
+
+module Sequence
+  class SequencePhrase
+    
+    attr_reader :key
+    attr_reader :values
+    attr_reader :template
+    attr_reader :phrase_params
+
+    ParameterConstant = { 'quotes' => '"""'}
+    
+    def initialize(phrase, sequence, data)
+      @key = self.class.sequence_key(phrase, data, :define)
+      #puts "*** [Sequence Step] - Key: #{@key}"
+
+      @phrase_params = scan_parameters(phrase, :define)
+      #puts "*** [Sequence Step] - Phrase Params: #{@phrase_params}"
+      
+      transformed_steps = preprocess(sequence)
+      #puts "*** [Sequence Step] - Steps: \n#{transformed_steps}"
+
+      @template = SequenceTemplate::Engine.new(transformed_steps)
+      #puts "\n*** [Sequence Step] - Template: #{@template.inspect}\n"
+
+      phrase_variables = template.variables
+      #puts "\n*** [Sequence Step] - Phrase Variables: #{phrase_variables}"
+      
+      @values = validate_phrase_values(@phrase_params, phrase_variables)
+      @values.concat(phrase_variables)
+      #puts "*** [Sequence Step] - Values: #{@values}"
+      
+      @values.uniq!
+    end
+    
+    def self.sequence_key(phrase, data, mode)
+      new_phrase = phrase.strip
+
+      # These lines replace every series of whitespace with an underscore.
+      # For that to work, I have to make sure there are no existing
+      # underscore characters in the first place so any pre-existing
+      # underscores get removed first.
+      new_phrase.gsub!(/_/, '')
+      new_phrase.gsub!(/\s+/, '_')
+
+      pattern = case mode
+                  when :define
+                    /<(?:[^\\<>]|\\.)*>/
+                  when :invoke
+                    /"([^\\"]|\\.)*"/
+                end
+
+      # Here 'patterned' means that for a given phrase, any bit of text
+      # between quotes or chevrons is replaced by the letter X.
+      patterned = new_phrase.gsub(pattern, 'X')
+
+      key = patterned + (data ? '_T' : '')
+      
+      return key
+    end
+
+    # "Scanning parameters" means that a phrase will be scanned to find any
+    # text between chevrons or double quotes. These will be placed into an
+    # array.
+    def scan_parameters(phrase, mode)
+      pattern = case mode
+                  when :define
+                    /<((?:[^\\<>]|\\.)*)>/
+                  when :invoke
+                    /"((?:[^\\"]|\\.)*)"/
+                end
+
+      result = phrase.scan(pattern)
+      params = result.flatten.compact
+      
+      # Any escaped double quotes need to be replaced by a double quote.
+      params.map! { |item| item.sub(/\\"/, '"') } if mode == :invoke
+      
+      return params
+    end
+    
+    def preprocess(sequence)
+      # Split text into individual lines and make sure to remove any lines
+      # with hash style comments.
+      lines = sequence.split(/\r\n?|\n/)
+      processed = lines.reject { |line| line =~ /\s*#/ }
+
+      return processed.join("\n")
+    end
+    
+    # The goal of this method is to check for various inconsistencies that
+    # can occur between parameter names in the sequence phrase and those
+    # in the actual steps.
+    def validate_phrase_values(params, phrase_variables)
+      # This covers the case when phrase names a parameter that never
+      # occurs in any of the steps.
+      params.each do |param|
+        unless phrase_variables.include? param
+          raise UselessPhraseParameter.new(param)
+        end
+      end
+
+      # This covers the case when a step has a parameter that never appears
+      # in the sequence phrase and when data table is not being used.
+      unless data_table_required?
+        phrase_variables.each do |variable|
+          unless params.include?(variable) || ParameterConstant.include?(variable)
+            raise UnreachableStepParameter.new(variable)
+          end
+        end  
+      end
+      
+      return phrase_params.dup
+    end
+
+    def data_table_required?
+      return key =~ /_T$/
+    end
+    
+    def expand(phrase, data)
+      params = validate_params(phrase, data)
+      params = ParameterConstant.merge(params)
+      return template.output(nil, params)
+    end
+    
+    def validate_params(phrase, data)
+      sequence_parameters = {}
+      
+      quoted_values = scan_parameters(phrase, :invoke)
+      quoted_values.each_with_index do |val, index|
+        sequence_parameters[phrase_params[index]] = val
+      end
+
+      unless data.nil?
+        data.each do |row|
+          (key, value) = validate_row(row, sequence_parameters)
+          if sequence_parameters.include? key
+            if sequence_parameters[key].kind_of?(Array)
+              sequence_parameters[key] << value
+            else
+              sequence_parameters[key] = [sequence_parameters[key], value]
+            end
+          else
+            sequence_parameters[key] = value
+          end
+        end
+      end
+
+      return sequence_parameters
+    end
+    
+    def validate_row(row, params)
+      (key, value) = row
+
+      raise UnknownParameterError.new(key) unless values.include? key
+
+      if (phrase_params.include? key) && (params[key] != value)
+        raise AmbiguousParameterValue.new(key, params[key], value)
+      end
+
+      return row
+    end
+    
+  end
+end

data/lib/lucid/sequence/sequence_steps.rb

@@ -0,0 +1,20 @@
+# The only test definitions that should go in here are those that
+# will build sequence steps. Meaning, each test step here is meant
+# to be one that is equivalent to a sequence of test steps.
+
+Given(/^the step "(?:Given|When|Then|\*) \[((?:[^\\\]]|\\.)+)\](:?)" is defined to mean:$/) do |phrase, table, sequence|
+  data_provided = (table == ':')
+  add_sequence(phrase, sequence, data_provided)
+end
+
+When(/^\[((?:[^\\\]]|\\.)+)\]$/) do |phrase|
+  invoke_sequence(phrase)
+end
+
+When(/^\[([^\]]+)\]:$/) do |phrase, data_table|
+  unless data_table.kind_of?(Lucid::AST::Table)
+    raise Sequence::DataTableNotFound.new(phrase)
+  end
+
+  invoke_sequence(phrase, data_table.raw)
+end

data/lib/lucid/sequence/sequence_support.rb

@@ -0,0 +1,26 @@
+require 'lucid/sequence/sequence_group'
+require 'lucid/sequence/sequence_errors'
+
+module Sequence
+  module SequenceSupport
+    
+    def add_sequence(phrase, sequence, data)
+      SequenceGroup.instance.add_sequence(phrase, sequence, data)
+    end
+    
+    def invoke_sequence(phrase, data = nil)
+      # It's necessary to generate textual versions of all the steps that
+      # are to be executed.
+      group = SequenceGroup.instance
+      generated_steps = group.generate_steps(phrase, data)
+      
+      # This statement causes Lucid to execute the generated test steps.
+      steps(generated_steps)
+    end
+    
+    def clear_sequences
+      SequenceGroup.instance.clear
+    end
+    
+  end
+end

data/lib/lucid/sequence/sequence_template.rb

@@ -0,0 +1,354 @@
+require 'strscan'
+
+module Sequence
+  module SequenceTemplate
+    
+    class StaticText
+      attr_reader :source
+      
+      def initialize(source)
+        @source = source
+      end
+      
+      def output(context, params)
+        return source
+      end
+    end
+    
+    class UnaryElement
+      attr_reader :name
+      
+      def initialize(name)
+        @name = name
+      end
+      
+      def retrieve_value_from(context, params)
+        actual_value = params[name]
+
+        if actual_value.nil? && context.respond_to?(name.to_sym)
+          actual_value = context.send(name.to_sym)
+        end
+        
+        return actual_value
+      end
+    end
+    
+    class Placeholder < UnaryElement
+      def output(context, params)
+        actual_value = retrieve_value_from(context, params)
+        
+        result = case actual_value
+                   when NilClass
+                     ''
+                   when Array
+                     actual_value.join('<br/>')
+                   when String
+                     actual_value
+                   else
+                     actual_value.to_s()
+                 end
+        
+        return result
+      end
+    end
+    
+    class EOLine
+      def output(context, params)
+        return "\n"
+      end
+    end
+
+    class Section < UnaryElement
+      attr_reader :children
+
+      def initialize(name)
+        super(name)
+        @children = []
+      end
+      
+      def add_child(child)
+        children << child
+      end
+      
+      def variables
+        section_variables = children.each_with_object([]) do |child, result|
+          case child
+            when Placeholder
+              result << child.name
+            when Section
+              result.concat(child.variables)
+            else
+              # noop
+          end
+        end
+        return section_variables.flatten.uniq
+      end
+      
+      def output(context, params)
+        msg = "Method Section.#{__method__} must be implemented in subclass."
+        raise NotImplementedError, msg
+      end
+    end
+
+    class ConditionalSection < Section
+      attr_reader :existence
+      
+      def initialize(name, generate)
+        super(name)
+        @existence = generate
+      end
+      
+      def output(context, params)
+        value = retrieve_value_from(context, params)
+        if (!value.nil? && existence) || (value.nil? && !existence)
+          result = children.each_with_object('') do |child, item|
+            item << child.output(context, params)
+          end
+        else
+          result = ''
+        end
+        
+        return result
+      end
+      
+      def to_s
+        return "<?#{name}>"
+      end
+    end
+    
+    SectionEndMarker = Struct.new(:name)
+    
+    class Engine
+      attr_reader :source
+      
+      # Invalid internal elements refers to spaces, any punctuation sign or
+      # delimiter that is forbidden between chevrons <...> template tags.
+      InvalidInternalElements = begin
+        forbidden = ' !"#' + "$%&'()*+,-./:;<=>?[\\]^`{|}~"
+        all_escaped = []
+        forbidden.each_char() { |ch| all_escaped << Regexp.escape(ch) }
+        pattern = all_escaped.join('|')
+        Regexp.new(pattern)
+      end
+      
+      def initialize(source)
+        @source = source
+        
+        # The generated source contains an internal representation of the
+        # given template text.
+        @generated_source = generate(source)
+      end
+      
+      # The parse mechanism is designed to break up TDL lines into static
+      # and dynamic components. Dynamic components will correspond to
+      # tagged elements of the string, which indicate parameters in the
+      # original TDL phrase.
+      def self.parse(line)
+        scanner = StringScanner.new(line)
+        result = []
+        
+        until scanner.eos?
+          tag_literal = scanner.scan(/<(?:[^\\<>]|\\.)*>/)
+          
+          unless tag_literal.nil?
+            result << [:dynamic, tag_literal.gsub(/^<|>$/, '')]
+          end
+
+          text_literal = scanner.scan(/(?:[^\\<>]|\\.)+/)
+          result << [:static, text_literal] unless text_literal.nil?
+
+          indicate_parsing_error(line) if tag_literal.nil? && text_literal.nil?
+        end
+
+        return result
+      end
+
+      def self.indicate_parsing_error(line)
+        # The regular expression will be looking to match \< or \>. Those are
+        # escaped chevrons and will be replaced.
+        no_escaped = line.gsub(/\\[<>]/, '--')
+        unbalance_count = 0
+
+        no_escaped.each_char do |ch|
+          case ch
+            when '<'
+              unbalance_count += 1
+            when '>'
+              unbalance_count -= 1
+          end
+
+          raise StandardError, "Nested opening chevron '<'." if unbalance_count > 1
+          raise StandardError, "Missing opening chevron '<'." if unbalance_count < 0
+        end
+
+        raise StandardError, "Missing closing chevron '>'." if unbalance_count == 1
+      end
+      
+      def parse_element(text)
+        # Check if the text matched is a ? or a / character. If the next bit
+        # of text after the ? or / is a invalid element of if there is an
+        # invalid element at all, an error will be raised.
+        if text =~ /^[\?\/]/
+          matching = InvalidInternalElements.match(text[1..-1])
+        else
+          matching = InvalidInternalElements.match(text)
+        end
+
+        raise InvalidElementError.new(text, matching[0]) if matching
+        
+        result = case text[0, 1]
+                   when '/'
+                     SectionEndMarker.new(text[1..-1])
+                   when '?'
+                     ConditionalSection.new(text[1..-1], true)
+                   else
+                     Placeholder.new(text)
+                 end
+        
+        return result
+      end
+      
+      # This method is used to retrieve all of the variable elements, which
+      # will be placeholder names, that appear in the template.
+      def variables
+        @variables ||= begin
+          vars = @generated_source.each_with_object([]) do |element, result|
+            case element
+              when Placeholder
+                result << element.name
+              when Section
+                result.concat(element.variables)
+              else
+                # noop
+            end
+          end
+          vars.flatten.uniq
+        end
+        return @variables
+      end
+      
+      # This general output method will provide a final template within
+      # the given scope object (Placeholder, StaticText, etc) and with
+      # any of the parameters specified.
+      def output(context, params)
+        return '' if @generated_source.empty?
+        result = @generated_source.each_with_object('') do |element, item|
+          item << element.output(context, params)
+        end
+        return result
+      end
+      
+      # To "generate" means to create an internal representation of
+      # the template.
+      def generate(source)
+        input_lines = source.split(/\r\n?|\n/)
+
+        raw_lines = input_lines.map do |line|
+          line_items = self.class.parse(line)
+          line_items.each do |(kind, text)|
+            if (kind == :dynamic) && text.strip.empty?
+              raise EmptyParameterError.new(line.strip)
+            end
+          end
+          line_items
+        end
+
+        template_lines = raw_lines.map { |line| generate_line(line) }
+        return generate_sections(template_lines.flatten)
+      end
+
+      def generate_line(line)
+        line_rep = line.map { |item| generate_couple(item) }
+        section_item = nil
+        
+        line_to_despace = line_rep.all? do |item|
+          case item
+            when StaticText
+              item.source =~ /\s+/
+            when Section, SectionEndMarker
+              if section_item.nil?
+                section_item = item
+                true
+              else
+                false
+              end
+            else
+              false
+          end
+        end
+
+        if line_to_despace && ! section_item.nil?
+          line_rep = [section_item]
+        else
+          line_rep_ending(line_rep)
+        end
+        
+        return line_rep
+      end
+      
+      def generate_couple(item)
+        (kind, text) = item
+        
+        result = case kind
+                   when :static
+                     StaticText.new(text)
+                   when :dynamic
+                     parse_element(text)
+                 end
+        
+        return result
+      end
+      
+      def generate_sections(sequence)
+        open_sections = []
+        
+        generated = sequence.each_with_object([]) do |element, result|
+          case element
+            when Section
+              open_sections << element
+            when SectionEndMarker
+              validate_section_end(element, open_sections)
+              result << open_sections.pop()
+            else
+              if open_sections.empty?
+                result << element
+              else
+                open_sections.last.add_child(element)
+              end
+            end
+          end
+
+        unless open_sections.empty?
+          error_message = "Unterminated section #{open_sections.last}."
+          raise StandardError, error_message
+        end
+        
+        return generated
+      end
+
+      def validate_section_end(marker, sections)
+        if sections.empty?
+          msg = "End of section </#{marker.name}> found while no corresponding section is open."
+          raise StandardError, msg
+        end
+
+        if marker.name != sections.last.name
+          msg = "End of section </#{marker.name}> does not match current section '#{sections.last.name}'."
+          raise StandardError, msg
+        end
+      end
+      
+      def line_rep_ending(line)
+        if line.last.is_a?(SectionEndMarker)
+          section_end = line.pop()
+          line << EOLine.new
+          line << section_end
+        else
+          line << EOLine.new
+        end
+      end
+      
+    end # class: Engine
+    
+  end
+end