cql 1.4.0 → 1.6.0

data/lib/cql/map_reduce.rb

@@ -6,10 +6,13 @@ require 'cql/dsl'
 
 module CQL
 
+  # Not a part of the public API. Subject to change at any time.
   class MapReduce
 
     extend Dsl
 
+
+    # Recursively gathers all models that match the given targets and filters
     def self.gather_objects(current_object, target_classes, filters)
       gathered_objects = Array.new.tap { |gathered_objects| collect_all_in(target_classes, current_object, gathered_objects) }
 

data/lib/cql/model_dsl.rb

@@ -1,13 +1,19 @@
-# todo - add some sore of error/warning if loading with the 0.x cuke_modeler?
+# todo - add some sort of error/warning if loading with the 0.x cuke_modeler?
 
 module CukeModeler
+
+  # A monkey patch that allows models to be queried directly by having them use this gem's query module.
+
   class Model
 
     include CQL::Queriable
 
+
+    # Hanging on to the original method so that it can be invoked and thus ensure that all of the normal, un-patched behavior occurs
     alias_method :original_initialize, :initialize
 
 
+    # Sets itself as the model's *query_root*. Otherwise, as per the un-patched method.
     def initialize(source_text = nil)
       original_initialize(source_text)
 

data/lib/cql/queriable.rb

@@ -1,9 +1,14 @@
 module CQL
+
+  # A mix-in module containing methods used by objects that want to be able to run queries against objects (often themselves).
+
   module Queriable
 
-    attr_accessor :query_root
+    # The object against which the query will be run.
+    attr_accessor :query_root # todo - deprecate this such that queries are always performed against *self*
 
 
+    # Performs a query against the current *query_root*
     def query(&block)
       raise(ArgumentError, 'Query cannot be run. No query root has been set.') unless @query_root
 

data/lib/cql/query.rb

@@ -0,0 +1,157 @@
+module CQL
+
+  # Not a part of the public API. Subject to change at any time.
+  class Query
+
+    include Dsl
+
+                # the root object that will be queried
+    attr_reader :data,
+                # what kinds of objects will be selected
+                :what
+
+    # Creates a new query object
+    def initialize(directory, &block)
+      # Set root object
+      @data = directory
+
+      # Populate configurables from DSL block
+      self.instance_eval(&block)
+
+
+      raise(ArgumentError, "A query must specify a 'select' clause") unless @what
+      raise(ArgumentError, "A query must specify a 'from' clause") unless @from
+
+      warn("Multiple selections made without using an 'as' clause") unless @name_transforms || (@what.count == @what.uniq.count)
+
+      # Gather relevant objects from root object and filters
+      @data = CQL::MapReduce.gather_objects(@data, @from, @filters)
+
+      # Extract properties from gathered objects
+      @data = format_output(@data)
+    end
+
+
+    private
+
+
+    def format_output(data)
+      format_data(data)
+    end
+
+    def format_data data
+      space_data
+
+      Array.new.tap do |result_array|
+        data.each do |element|
+          result_array << Hash.new.tap do |result|
+            @what.each_with_index do |attribute, index|
+              key = determine_key(attribute, index)
+              value = determine_value(element, attribute, index)
+
+              result[key] = value
+            end
+          end
+        end
+      end
+    end
+
+    def determine_key(attribute, index)
+      key = mapped_attribute(@name_transforms, attribute, index) if @name_transforms
+
+      key || attribute
+    end
+
+    def determine_value(element, attribute, index)
+      original_value = attribute.is_a?(Symbol) ? determine_special_value(element, attribute) : determine_normal_value(element, attribute)
+
+      if @value_transforms
+        value = mapped_attribute(@value_transforms, attribute, index)
+        value = value.call(original_value) if value.is_a?(Proc)
+      end
+
+      value || original_value
+    end
+
+    def determine_special_value(element, attribute)
+      # todo - Not sure what other special values to have but this could be expanded upon later.
+      case attribute
+        when :self, :model
+          val = element
+        else
+          raise(ArgumentError, ":#{attribute} is not a valid attribute for selection.")
+      end
+
+      val
+    end
+
+    def determine_normal_value(element, attribute)
+      if element.respond_to?(attribute)
+        element.send(attribute)
+      else
+        raise(ArgumentError, "'#{attribute}' is not a valid attribute for selection from a '#{element.class}'.")
+      end
+    end
+
+    def mapped_attribute(mappings, attribute, location)
+      case
+        when mappings.is_a?(Array)
+          value = mappings[location]
+        when mappings.is_a?(Hash)
+          if mappings[attribute]
+            value = mappings[attribute][location]
+          end
+        else
+          raise(ArgumentError, "Unknown mapping type '#{mappings.class}'")
+      end
+
+      value
+    end
+
+    def space_data
+      space_renamings
+      space_transforms
+    end
+
+    def space_renamings
+      if @name_transforms.is_a?(Hash)
+        new_names = {}
+
+        @name_transforms.each_pair do |key, value|
+          new_names[key] = []
+
+          @what.each do |attribute|
+            if attribute == key
+              new_names[key] << value.shift
+            else
+              new_names[key] << nil
+            end
+          end
+        end
+
+        @name_transforms = new_names
+      end
+    end
+
+    def space_transforms
+      if @value_transforms.is_a?(Hash)
+        new_values = {}
+
+        @value_transforms.each_pair do |key, value|
+          new_values[key] = []
+
+          @what.each do |attribute|
+            if attribute == key
+              new_values[key] << value.shift
+            else
+              new_values[key] << nil
+            end
+          end
+        end
+
+        @value_transforms = new_values
+      end
+    end
+
+  end
+end

data/lib/cql/repository.rb

@@ -0,0 +1,25 @@
+module CQL
+
+# A repository is a group of models. See the corresponding Cucumber documentation for details.
+
+  class Repository
+
+    include Queriable
+
+
+    # Creates a new repository object based on the passed directory path or model
+    def initialize(repository_root)
+      case
+        when repository_root.is_a?(String)
+          root = CukeModeler::Directory.new(repository_root)
+        when repository_root.class.to_s =~ /CukeModeler/
+          root = repository_root
+        else
+          raise(ArgumentError, "Don't know how to make a repository from a #{repository_root.class}")
+      end
+
+      @query_root = root
+    end
+
+  end
+end

data/lib/cql/sso_filters.rb

@@ -3,16 +3,20 @@ require 'cql/filters'
 
 module CQL
 
+  # Not a part of the public API. Subject to change at any time.
   class SsoLineCountFilter < TypeCountFilter
 
+    # Counts the numbers of steps on a test
     def type_count(test)
       test.steps.size
     end
 
   end
 
+  # Not a part of the public API. Subject to change at any time.
   class LineFilter < ContentMatchFilter
 
+    # Filters the input models so that only the desired ones are returned
     def execute(input, negate)
       method_for_filtering = negate ? :reject : :select
       method_for_text = Gem.loaded_specs['cuke_modeler'].version.version[/^0/] ? :base : :text

data/lib/cql/version.rb

@@ -1,3 +1,4 @@
 module CQL
-  VERSION = '1.4.0'
+  # The current version of the gem
+  VERSION = '1.6.0'
 end

data/testing/cucumber/features/clauses/as_clause.feature

@@ -2,12 +2,14 @@ Feature: 'as' clause'
 
   The *as* clause allows you to change the keys under which the model attributes specified by the *select* clause will be gathered. Key renaming can be done as a list of new names that are applied in order or as a mapping of specific keys to their new names.
 
-    Sample usage:
-      cql_repo.query do
-        select name
-        as title
-        from features
-      end
+  Sample usage:
+  ````
+  cql_repo.query do
+    select name
+    as title
+    from features
+  end
+  ````
 
   This will return a list of all of the feature names but under the key of 'title' instead of 'name'.
 
@@ -15,8 +17,8 @@ Feature: 'as' clause'
 
 
   Background: A sample Cucumber suite
-    Given a directory "test_directory"
-    And a file "test_directory/test_file_1.feature":
+    Given a repository to query
+    And the following feature has been modeled in the repository:
       """
       Feature: A test feature
 
@@ -36,7 +38,6 @@ Feature: 'as' clause'
           | param |
           | value |
       """
-    And a repository is made from "test_directory"
 
 
   Scenario: Using 'as' to change the name under which values are returned

data/testing/cucumber/features/clauses/from_clause.feature

@@ -4,22 +4,26 @@ Feature: 'from' clause
 
   The following are some example values:
 
-  CukeModeler::Outline  (exact class)
-  outline               (singular)
-  outlines              (pluralized)
-
-    Sample usage:
-      cql_repo.query do
-        select name
-        from scenarios
-      end
+  ````
+  CukeModeler::Outline  # exact class
+  outline               # singular
+  outlines              # pluralized
+  ````
+
+  Sample usage:
+  ````
+  cql_repo.query do
+    select name
+    from scenarios
+  end
+  ````
 
   This clause can be repeated multiple times. The arguments for successive clauses are simply added to the previous arguments.
 
 
   Background: A sample Cucumber suite
-    Given a directory "test_directory"
-    And a file "test_directory/test_file_1.feature":
+    Given a repository to query
+    And the following feature has been modeled in the repository:
       """
       Feature: A test feature
 
@@ -39,7 +43,6 @@ Feature: 'from' clause
           | param |
           | value |
       """
-    And a repository is made from "test_directory"
 
 
   Scenario: Using 'from' to specify what kind of objects from which to return attributes
@@ -116,11 +119,3 @@ Feature: 'from' clause
       from :all
       """
     Then all models are queried from
-
-
-# Commented out so that they aren't picked up by Relish
-#  @wip
-#  Scenario: Can 'from' from all type of model
-#
-#  @wip
-#  Scenario: From-ing from a collection

data/testing/cucumber/features/clauses/predefined_with_filters.feature

@@ -0,0 +1,392 @@
+# todo - Rewrite the scenarios such that they use their own test specific feature files instead of setting up a large suite in the background
+Feature: 'with' clause
+
+  There are several predefined filters that can be used with the *with* clause. Like regular 'block style' conditions, they can be negated using *without*, used in a targeted fashion, etc.
+
+  Sample usage:
+  ````
+  cql_repo.query do
+  select name, tags, description_text
+  from features
+  with tc lt 3
+  end
+  ````
+
+  The following filters are supported for models that have tags:
+
+  * tags - Filters out models that do not have the exact set of tags provided.
+  * tc   - (tag count) Filters out models based on the number of tags that they have.
+
+  The following filters are supported for models that have names:
+
+  * name - Filters out models whose name does not match the name provided. Can be a string or regular expression.
+
+  The following filters are supported for models that have steps:
+
+  * line - Filters out models whose steps do not include the provided step (keywords and blocks are ignored). Can be a string or regular expression.
+  * lc   - (line count) Filters out models based on the number of steps that they have.
+
+  The following filters are supported for feature models:
+
+  * sc   - (scenario count) Filters out models based on the number of scenarios that they have.
+  * soc  - (scenario outline count) Filters out models based on the number of outlines that they have.
+  * ssoc - (scenario and scenario outline count) Filters out models based on the total number of scenarios and outlines that they have.
+
+  For count based filters, the following operators are available:
+
+  * lt   (Less than)
+  * lte  (Less than or equals)
+  * gt   (Greater than)
+  * gte  (Greater than or equals)
+  * eq   (Equals)
+
+
+  Background: A sample Cucumber suite
+    Given a repository to query
+    And the following feature has been modeled in the repository:
+      """
+      Feature: A test feature
+
+        @tag_1 @tag_2
+        Scenario: Test 1
+          * some steps
+
+        @special_tag @tag_2
+        Scenario: Test 2
+          * some other steps
+          * some other steps
+          * some other steps
+
+        @a @b @c
+        Scenario Outline: Test 3
+          * some steps
+          * some more steps
+          * some more steps
+          * some more steps
+        Examples: First examples
+          | param |
+          | value |
+        Examples: Second examples
+          | param |
+          | value |
+
+        Scenario: Test 4
+      """
+    And the following feature has been modeled in the repository:
+      """
+      Feature: A feature with lots of scenarios
+
+        Scenario: 1
+          * different steps
+          * different steps
+
+        Scenario: 2
+          * different steps
+          * different steps
+
+        Scenario: 3
+          * different steps
+          * different steps
+      """
+    And the following feature has been modeled in the repository:
+      """
+      Feature: A feature with lots of outlines
+
+        Scenario Outline: 1
+          * different steps
+          * different steps
+        Examples:
+          | param |
+          | value |
+
+        Scenario Outline: 2
+          * different steps
+          * different steps
+        Examples:
+          | param |
+          | value |
+
+        Scenario Outline: 3
+          * different steps
+          * different steps
+        Examples:
+          | param |
+          | value |
+      """
+    And the following feature has been modeled in the repository:
+      """
+      Feature: A feature with a mix of tests
+
+        Scenario: 4
+          * different steps
+          * different steps
+
+        Scenario Outline: 4
+          * different steps
+          * different steps
+        Examples:
+          | param |
+          | value |
+      """
+
+
+  Scenario: Filtering by tags
+    When the following query is executed:
+      """
+      select name
+      from scenarios
+      with tags '@tag_1', '@tag_2'
+      """
+    Then the following values are returned:
+      | name   |
+      | Test 1 |
+
+  Scenario: Filtering by tag count
+    When the following query is executed:
+      """
+      select name
+      from scenarios, outlines
+      with tc gt 2
+      """
+    Then the following values are returned:
+      | name   |
+      | Test 3 |
+
+  Scenario: Filtering by name (exact match)
+    When the following query is executed:
+      """
+      select name
+      from scenarios, outlines
+      with name 'Test 3'
+      """
+    Then the following values are returned:
+      | name   |
+      | Test 3 |
+
+  Scenario: Filtering by name (regular expression)
+    When the following query is executed:
+      """
+      select name
+      from scenarios, outlines
+      with name /Test [12]/
+      """
+    Then the following values are returned:
+      | name   |
+      | Test 1 |
+      | Test 2 |
+
+  Scenario: Filtering by line (exact match)
+    When the following query is executed:
+      """
+      select name
+      from scenarios, outlines
+      with line 'some steps'
+      """
+    Then the following values are returned:
+      | name   |
+      | Test 1 |
+      | Test 3 |
+
+  Scenario: Filtering by line (regular expression)
+    When the following query is executed:
+      """
+      select name
+      from scenarios, outlines
+      with line /other/
+      """
+    Then the following values are returned:
+      | name   |
+      | Test 2 |
+
+  Scenario: Filtering by line count
+    When the following query is executed:
+      """
+      select name
+      from scenarios, outlines
+      with lc gt 3
+      """
+    Then the following values are returned:
+      | name   |
+      | Test 3 |
+
+  Scenario: Filtering by scenario count
+    When the following query is executed:
+      """
+      select name
+      from features
+      with sc gt 2
+      """
+    Then the following values are returned:
+      | name                             |
+      | A test feature                   |
+      | A feature with lots of scenarios |
+
+  Scenario: Filtering by outline count
+    When the following query is executed:
+      """
+      select name
+      from features
+      with soc gt 2
+      """
+    Then the following values are returned:
+      | name                            |
+      | A feature with lots of outlines |
+
+  Scenario: Filtering by combined test count
+    When the following query is executed:
+      """
+      select name
+      from features
+      with ssoc lt 3
+      """
+    Then the following values are returned:
+      | name                          |
+      | A feature with a mix of tests |
+
+  Scenario: Using the 'lt' count filter
+    When the following query is executed:
+      """
+      select name
+      from features
+      with ssoc lt 3
+      """
+    Then the following values are returned:
+      | name                          |
+      | A feature with a mix of tests |
+
+  Scenario: Using the 'lte' count filter
+    When the following query is executed:
+      """
+      select name
+      from scenarios, outlines
+      with lc lte 1
+      """
+    Then the following values are returned:
+      | name   |
+      | Test 1 |
+      | Test 4 |
+
+  Scenario: Using the 'gt' count filter
+    When the following query is executed:
+      """
+      select name
+      from scenarios, outlines
+      with lc gt 3
+      """
+    Then the following values are returned:
+      | name   |
+      | Test 3 |
+
+  Scenario: Using the 'gte' count filter
+    When the following query is executed:
+      """
+      select name
+      from scenarios, outlines
+      with lc gte 3
+      """
+    Then the following values are returned:
+      | name   |
+      | Test 2 |
+      | Test 3 |
+
+  Scenario: Using the 'eq' count filter
+    When the following query is executed:
+      """
+      select name
+      from scenarios, outlines
+      with tc eq 3
+      """
+    Then the following values are returned:
+      | name   |
+      | Test 3 |
+
+
+  Scenario: Using multiple filters
+    When the following query is executed:
+      """
+      select name
+      from scenarios
+      with tc eq 2
+      with lc gt 1
+      """
+    Then the following values are returned:
+      | name   |
+      | Test 2 |
+
+  Scenario: Using the 'with' clause multiple times
+
+  Behavior is the same as combining regular, block style filters but the syntax has to become more explicit.
+
+    When the following query is executed:
+      """
+      select name
+      from scenarios
+      with tc(eq(2)),
+           lc(gt(1))
+      """
+    Then the result is the same as the result of the following query:
+      """
+      select name
+      from scenarios
+      with tc eq 2
+      with lc gt 1
+      """
+
+  Scenario: Selectively filtering models
+    When the following query is executed:
+      """
+      select name
+      from scenarios, features
+      with scenarios => lc(eq(1))
+      """
+    Then the following values are returned:
+      | name                             |
+      | Test 1                           |
+      | A test feature                   |
+      | A feature with lots of scenarios |
+      | A feature with lots of outlines  |
+      | A feature with a mix of tests    |
+
+
+  Scenario: Mixing targeted and blanket filters
+    When the following query is executed:
+      """
+      select name
+      from scenarios, features
+      with name /test/i
+      with scenarios => tc(eq(0))
+      """
+    Then the following values are returned:
+      | name                          |
+      | Test 4                        |
+      | A test feature                |
+      | A feature with a mix of tests |
+
+  Scenario: Using 'without' for negation
+    When the following query is executed:
+      """
+      select name
+      from features
+      without ssoc lt 3
+      """
+    Then the result is the same as the result of the following query:
+      """
+      select name
+      from features
+      with ssoc gt 2
+      """
+
+  Scenario: Mixing predefined filters and regular filters
+    When the following query is executed:
+      """
+      select name
+      from scenarios, features
+      with { |element| element.name =~ /test/i }
+      with scenarios => tc(eq(0))
+      """
+    Then the following values are returned:
+      | name                          |
+      | Test 4                        |
+      | A test feature                |
+      | A feature with a mix of tests |
+