cuke_modeler 3.20.0 → 3.20.1

data/lib/cuke_modeler/models/model.rb

@@ -1,6 +1,6 @@
 module CukeModeler
 
-  # A class modeling an element of a Cucumber suite.
+  # A class modeling an element of a Cucumber suite. All model classes should descend from this class.
   class Model
 
     include Nested
@@ -8,37 +8,80 @@ module CukeModeler
 
 
     # Creates a new Model object and, if *source_text* is provided,
-    # populates the object.
+    # populates the object. For the base model class, there is nothing
+    # to populate.
+    #
+    # @example
+    #   Model.new
+    #   Model.new('some source text')
+    #
+    # @param source_text [String] The string that will be used to populate the model. Defaults to nil.
+    # @raise [ArgumentError] If *source_text* is not a String
+    # @return [Model] A new Model instance
     def initialize(source_text = nil)
       error_message = "Can only create models from Strings but was given a #{source_text.class}."
       raise(ArgumentError, error_message) if source_text && !source_text.is_a?(String)
 
-      # This should be overridden by a child class
+      return unless source_text
+
+      source_data = process_source(source_text)
+      populate_model(source_data)
     end
 
     # It's a lazy implementation but it's mandatory for the class to define this method
     # rubocop:disable Lint/UselessMethodDefinition
 
-    # Returns a string representation of this model.
+    # Returns a string representation of this model. Because the base model class
+    # doesn't represent anything specific, its string output is undefined.
+    #
+    # @example
+    #   model.to_s
+    #
+    # @return [String] A string representation of this model
     def to_s
-      # This should be overridden by a child class
       super
     end
 
     # rubocop:enable Lint/UselessMethodDefinition
 
-    # Returns the model objects that belong to this model.
+    # Returns the model objects that are children of this model.
+    #
+    # @example
+    #   model.children
+    #
+    # @return [Array<Model>] A collection of child models
     def children
       []
     end
 
     # See `Object#inspect`. Returns some basic information about the
-    # object, including its class and object ID.
+    # object, including its class and object ID. If *verbose* is true,
+    # provides default Ruby inspection behavior instead.
+    #
+    # @example
+    #   model.inspect
+    #   model.inspect(verbose: true)
+    #
+    # @param verbose [Boolean] Whether or not to return the full details of
+    #   the object. Defaults to false.
+    # @return [String] A string representation of this model
     def inspect(verbose: false)
       return super() if verbose
 
       "#<#{self.class.name}:#{object_id}>"
     end
 
+
+    private
+
+
+    def process_source(source_text)
+      # No-op. Overridden by child classes.
+    end
+
+    def populate_model(model_data)
+      # No-op. Overridden by child classes.
+    end
+
   end
 end

data/lib/cuke_modeler/models/outline.rb

@@ -21,27 +21,44 @@ module CukeModeler
 
     # Creates a new Outline object and, if *source_text* is provided, populates the
     # object.
+    #
+    # @example
+    #   Outline.new
+    #   Outline.new("Scenario Outline:\n  * a step")
+    #
+    # @param source_text [String] The Gherkin text that will be used to populate the model
+    # @raise [ArgumentError] If *source_text* is not a String
+    # @return [Outline] A new Outline instance
     def initialize(source_text = nil)
       @steps = []
       @tags = []
       @examples = []
 
       super(source_text)
-
-      return unless source_text
-
-      parsed_outline_data = parse_source(source_text)
-      populate_outline(self, parsed_outline_data)
     end
 
-    # Returns *true* if the two models have equivalent steps and *false* otherwise.
+    # Compares this model with another object. Returns *true* if the two objects
+    # have equivalent steps and *false* otherwise.
+    #
+    # @example
+    #   outline_1 == outline_2
+    #
+    # @param other [Object] The object to compare this model with
+    # @return [Boolean] Whether the two objects are equivalent
     def ==(other)
       return false unless other.respond_to?(:steps)
 
       steps == other.steps
     end
 
-    # Returns the model objects that belong to this model.
+    # Returns the model objects that are children of this model. For
+    # an Outline model, these would be any associated Step, Tag, or
+    # Example models.
+    #
+    # @example
+    #   outline.children
+    #
+    # @return [Array<Step, Tag, Example>] A collection of child models
     def children
       examples + steps + tags
     end
@@ -49,8 +66,13 @@ module CukeModeler
     # Building strings just isn't pretty
     # rubocop:disable Metrics/AbcSize
 
-    # Returns a string representation of this model. For an outline model,
+    # Returns a string representation of this model. For an Outline model,
     # this will be Gherkin text that is equivalent to the outline being modeled.
+    #
+    # @example
+    #   outline.to_s
+    #
+    # @return [String] A string representation of this model
     def to_s
       text = ''
 
@@ -68,7 +90,17 @@ module CukeModeler
 
     # See `Object#inspect`. Returns some basic information about the
     # object, including its class, object ID, and its most meaningful
-    # attribute. For an outline model, this will be the name of the outline.
+    # attribute. For an Outline model, this will be the name of the
+    # outline. If *verbose* is true, provides default Ruby inspection
+    # behavior instead.
+    #
+    # @example
+    #   outline.inspect
+    #   outline.inspect(verbose: true)
+    #
+    # @param verbose [Boolean] Whether or not to return the full details of
+    #   the object. Defaults to false.
+    # @return [String] A string representation of this model
     def inspect(verbose: false)
       return super(verbose: verbose) if verbose
 
@@ -79,7 +111,7 @@ module CukeModeler
     private
 
 
-    def parse_source(source_text)
+    def process_source(source_text)
       base_file_string = "# language: #{Parsing.dialect}\n#{dialect_feature_keyword}: Fake feature to parse\n"
       source_text = base_file_string + source_text
 
@@ -88,6 +120,23 @@ module CukeModeler
       parsed_file['feature']['elements'].first
     end
 
+    def populate_model(parsed_outline_data)
+      populate_parsing_data(parsed_outline_data)
+      populate_source_location(parsed_outline_data)
+      populate_keyword(parsed_outline_data)
+      populate_name(parsed_outline_data)
+      populate_description(parsed_outline_data)
+      populate_steps(parsed_outline_data)
+      populate_tags(parsed_outline_data)
+      populate_outline_examples(parsed_outline_data['examples']) if parsed_outline_data['examples']
+    end
+
+    def populate_outline_examples(parsed_examples)
+      parsed_examples.each do |example_data|
+        @examples << build_child_model(Example, example_data)
+      end
+    end
+
     def examples_output_string
       examples.empty? ? '' : examples.join("\n\n")
     end

data/lib/cuke_modeler/models/row.rb

@@ -13,24 +13,38 @@ module CukeModeler
 
     # Creates a new Row object and, if *source_text* is provided, populates
     # the object.
+    #
+    # @example
+    #   Row.new
+    #   Row.new('|value_1|value_2|')
+    #
+    # @param source_text [String] The Gherkin text that will be used to populate the model
+    # @raise [ArgumentError] If *source_text* is not a String
+    # @return [Row] A new Row instance
     def initialize(source_text = nil)
       @cells = []
 
       super(source_text)
-
-      return unless source_text
-
-      parsed_row_data = parse_source(source_text)
-      populate_row(self, parsed_row_data)
     end
 
-    # Returns the model objects that belong to this model.
+    # Returns the model objects that are children of this model. For a
+    # Row model, these would be any associated Cell models.
+    #
+    # @example
+    #   row.children
+    #
+    # @return [Array<Cell>] A collection of child models
     def children
       @cells
     end
 
-    # Returns a string representation of this model. For a row model,
+    # Returns a string representation of this model. For a Row model,
     # this will be Gherkin text that is equivalent to the row being modeled.
+    #
+    # @example
+    #   row.to_s
+    #
+    # @return [String] A string representation of this model
     def to_s
       text_cells = cells.map(&:to_s)
 
@@ -39,7 +53,17 @@ module CukeModeler
 
     # See `Object#inspect`. Returns some basic information about the
     # object, including its class, object ID, and its most meaningful
-    # attribute. For a row model, this will be the cells of the row.
+    # attribute. For a Row model, this will be the cells of the row.
+    # If *verbose* is true, provides default Ruby inspection behavior
+    # instead.
+    #
+    # @example
+    #   row.inspect
+    #   row.inspect(verbose: true)
+    #
+    # @param verbose [Boolean] Whether or not to return the full details of
+    #   the object. Defaults to false.
+    # @return [String] A string representation of this model
     def inspect(verbose: false)
       return super(verbose: verbose) if verbose
 
@@ -52,7 +76,7 @@ module CukeModeler
     private
 
 
-    def parse_source(source_text)
+    def process_source(source_text)
       base_file_string = "# language: #{Parsing.dialect}
       #{dialect_feature_keyword}: Fake feature to parse
                             #{dialect_scenario_keyword}:
@@ -64,5 +88,17 @@ module CukeModeler
       parsed_file['feature']['elements'].first['steps'].first['table']['rows'].first
     end
 
+    def populate_model(parsed_row_data)
+      populate_source_location(parsed_row_data)
+      populate_row_cells(parsed_row_data)
+      populate_parsing_data(parsed_row_data)
+    end
+
+    def populate_row_cells(parsed_row_data)
+      parsed_row_data['cells'].each do |cell_data|
+        @cells << build_child_model(Cell, cell_data)
+      end
+    end
+
   end
 end

data/lib/cuke_modeler/models/rule.rb

@@ -23,19 +23,27 @@ module CukeModeler
 
     # Creates a new Rule object and, if *source_text* is provided, populates the
     # object.
+    #
+    # @example
+    #   Rule.new
+    #   Rule.new("Rule:\nThis is a rule")
+    #
+    # @param source_text [String] The Gherkin text that will be used to populate the model
+    # @raise [ArgumentError] If *source_text* is not a String
+    # @return [Rule] A new Rule instance
     def initialize(source_text = nil)
       @tags = []
       @tests = []
 
       super(source_text)
-
-      return unless source_text
-
-      parsed_rule_data = parse_source(source_text)
-      populate_rule(self, parsed_rule_data)
     end
 
     # Returns *true* if the rule contains a background, *false* otherwise.
+    #
+    # @example
+    #   rule.background?
+    #
+    # @return [Boolean] Whether the rule contains a background
     def background?
       !@background.nil?
     end
@@ -43,16 +51,33 @@ module CukeModeler
     alias has_background? background?
 
     # Returns the scenario models contained in the rule.
+    #
+    # @example
+    #   rule.scenarios
+    #
+    # @return [Array<Scenario>] Child Scenario models
     def scenarios
       @tests.select { |test| test.is_a? Scenario }
     end
 
     # Returns the outline models contained in the rule.
+    #
+    # @example
+    #   rule.outlines
+    #
+    # @return [Array<Outline>] Child Outline models
     def outlines
       @tests.select { |test| test.is_a? Outline }
     end
 
-    # Returns the model objects that belong to this model.
+    # Returns the model objects that are children of this model. For a
+    # Rule model, these would be any associated Background, Scenario,
+    # Outline, or Tag models.
+    #
+    # @example
+    #   rule.children
+    #
+    # @return [Array<Background, Scenario, Outline, Tag>] A collection of child models
     def children
       models = tests + tags
       models << background if background
@@ -60,8 +85,13 @@ module CukeModeler
       models
     end
 
-    # Returns a string representation of this model. For a rule model,
+    # Returns a string representation of this model. For a Rule model,
     # this will be Gherkin text that is equivalent to the rule being modeled.
+    #
+    # @example
+    #   rule.to_s
+    #
+    # @return [String] A string representation of this model
     def to_s
       text = ''
 
@@ -76,7 +106,17 @@ module CukeModeler
 
     # See `Object#inspect`. Returns some basic information about the
     # object, including its class, object ID, and its most meaningful
-    # attribute. For a rule model, this will be the name of the rule.
+    # attribute. For a Rule model, this will be the name of the rule.
+    # If *verbose* is true, provides default Ruby inspection behavior
+    # instead.
+    #
+    # @example
+    #   rule.inspect
+    #   rule.inspect(verbose: true)
+    #
+    # @param verbose [Boolean] Whether or not to return the full details of
+    #   the object. Defaults to false.
+    # @return [String] A string representation of this model
     def inspect(verbose: false)
       return super(verbose: verbose) if verbose
 
@@ -87,7 +127,7 @@ module CukeModeler
     private
 
 
-    def parse_source(source_text)
+    def process_source(source_text)
       base_file_string = "# language: #{Parsing.dialect}\n#{dialect_feature_keyword}: Fake feature to parse\n"
       source_text = base_file_string + source_text
 
@@ -96,6 +136,16 @@ module CukeModeler
       parsed_file['feature']['elements'].first
     end
 
+    def populate_model(parsed_rule_data)
+      populate_parsing_data(parsed_rule_data)
+      populate_source_location(parsed_rule_data)
+      populate_keyword(parsed_rule_data)
+      populate_name(parsed_rule_data)
+      populate_description(parsed_rule_data)
+      populate_tags(parsed_rule_data)
+      populate_children(parsed_rule_data)
+    end
+
     def background_output_string
       test_output_string(background)
     end

data/lib/cuke_modeler/models/scenario.rb

@@ -18,26 +18,42 @@ module CukeModeler
 
     # Creates a new Scenario object and, if *source_text* is provided, populates the
     # object.
+    #
+    # @example
+    #   Scenario.new
+    #   Scenario.new("Scenario:\n  * a step")
+    #
+    # @param source_text [String] The Gherkin text that will be used to populate the model
+    # @raise [ArgumentError] If *source_text* is not a String
+    # @return [Scenario] A new Scenario instance
     def initialize(source_text = nil)
       @steps = []
       @tags = []
 
       super(source_text)
-
-      return unless source_text
-
-      parsed_scenario_data = parse_source(source_text)
-      populate_scenario(self, parsed_scenario_data)
     end
 
-    # Returns *true* if the two models have equivalent steps and *false* otherwise.
+    # Compares this model with another object. Returns *true* if the two objects
+    # have equivalent steps and *false* otherwise.
+    #
+    # @example
+    #   scenario_1 == scenario_2
+    #
+    # @param other [Object] The object to compare this model with
+    # @return [Boolean] Whether the two objects are equivalent
     def ==(other)
       return false unless other.respond_to?(:steps)
 
       steps == other.steps
     end
 
-    # Returns the model objects that belong to this model.
+    # Returns the model objects that are children of this model. For a
+    # Scenario model, these would be any associated Step or Tag models.
+    #
+    # @example
+    #   scenario.children
+    #
+    # @return [Array<Step, Tag>] A collection of child models
     def children
       steps + tags
     end
@@ -45,8 +61,13 @@ module CukeModeler
     # Building strings just isn't pretty
     # rubocop:disable Metrics/AbcSize
 
-    # Returns a string representation of this model. For a scenario model,
+    # Returns a string representation of this model. For a Scenario model,
     # this will be Gherkin text that is equivalent to the scenario being modeled.
+    #
+    # @example
+    #   scenario.to_s
+    #
+    # @return [String] A string representation of this model
     def to_s
       text = ''
 
@@ -63,7 +84,17 @@ module CukeModeler
 
     # See `Object#inspect`. Returns some basic information about the
     # object, including its class, object ID, and its most meaningful
-    # attribute. For a scenario model, this will be the name of the scenario.
+    # attribute. For a Scenario model, this will be the name of the
+    # scenario. If *verbose* is true, provides default Ruby inspection
+    # behavior instead.
+    #
+    # @example
+    #   scenario.inspect
+    #   scenario.inspect(verbose: true)
+    #
+    # @param verbose [Boolean] Whether or not to return the full details of
+    #   the object. Defaults to false.
+    # @return [String] A string representation of this model
     def inspect(verbose: false)
       return super(verbose: verbose) if verbose
 
@@ -74,7 +105,7 @@ module CukeModeler
     private
 
 
-    def parse_source(source_text)
+    def process_source(source_text)
       base_file_string = "# language: #{Parsing.dialect}\n#{dialect_feature_keyword}: Fake feature to parse\n"
       source_text = base_file_string + source_text
 
@@ -83,5 +114,15 @@ module CukeModeler
       parsed_file['feature']['elements'].first
     end
 
+    def populate_model(parsed_scenario_data)
+      populate_parsing_data(parsed_scenario_data)
+      populate_source_location(parsed_scenario_data)
+      populate_keyword(parsed_scenario_data)
+      populate_name(parsed_scenario_data)
+      populate_description(parsed_scenario_data)
+      populate_steps(parsed_scenario_data)
+      populate_tags(parsed_scenario_data)
+    end
+
   end
 end

data/lib/cuke_modeler/models/step.rb

@@ -20,17 +20,26 @@ module CukeModeler
 
     # Creates a new Step object and, if *source_text* is provided, populates the
     # object.
+    #
+    # @example
+    #   Step.new
+    #   Step.new("Given a step")
+    #
+    # @param source_text [String] The Gherkin text that will be used to populate the model
+    # @raise [ArgumentError] If *source_text* is not a String
+    # @return [Step] A new Step instance
     def initialize(source_text = nil)
       super(source_text)
-
-      return unless source_text
-
-      parsed_step_data = parse_source(source_text)
-      populate_step(self, parsed_step_data)
     end
 
-    # Returns *true* if the two steps have the same base text (i.e. minus any keyword,
-    # table, or doc string and *false* otherwise.
+    # Compares this model with another object. Returns *true* if the two objects
+    # have the same base text, table, and doc string and *false* otherwise.
+    #
+    # @example
+    #   step_1 == step_2
+    #
+    # @param other [Object] The object to compare this model with
+    # @return [Boolean] Whether the two objects are equivalent
     def ==(other)
       return false unless other.is_a?(CukeModeler::Step)
 
@@ -39,13 +48,24 @@ module CukeModeler
         doc_string_matches?(other)
     end
 
-    # Returns the model objects that belong to this model.
+    # Returns the model objects that are children of this model. For a
+    # Step model, these would be any associated Table or DocString models.
+    #
+    # @example
+    #   step.children
+    #
+    # @return [Array<Table, DocString>] A collection of child models
     def children
       block ? [block] : []
     end
 
-    # Returns a string representation of this model. For a step model,
+    # Returns a string representation of this model. For a Step model,
     # this will be Gherkin text that is equivalent to the step being modeled.
+    #
+    # @example
+    #   step.to_s
+    #
+    # @return [String] A string representation of this model
     def to_s
       text = "#{keyword} #{self.text}"
       text << "\n#{block.to_s.split("\n").collect { |line| "  #{line}" }.join("\n")}" if block
@@ -55,7 +75,17 @@ module CukeModeler
 
     # See `Object#inspect`. Returns some basic information about the
     # object, including its class, object ID, and its most meaningful
-    # attribute. For a step model, this will be the text of the step.
+    # attribute. For a Step model, this will be the text of the step.
+    # If *verbose* is true, provides default Ruby inspection behavior
+    # instead.
+    #
+    # @example
+    #   step.inspect
+    #   step.inspect(verbose: true)
+    #
+    # @param verbose [Boolean] Whether or not to return the full details of
+    #   the object. Defaults to false.
+    # @return [String] A string representation of this model
     def inspect(verbose: false)
       return super(verbose: verbose) if verbose
 
@@ -66,7 +96,7 @@ module CukeModeler
     private
 
 
-    def parse_source(source_text)
+    def process_source(source_text)
       base_file_string = "# language: #{Parsing.dialect}
       #{dialect_feature_keyword}: Fake feature to parse
                             #{dialect_scenario_keyword}:\n"
@@ -77,6 +107,26 @@ module CukeModeler
       parsed_file['feature']['elements'].first['steps'].first
     end
 
+    def populate_model(parsed_step_data)
+      populate_text(parsed_step_data)
+      populate_block(parsed_step_data)
+      populate_keyword(parsed_step_data)
+      populate_source_location(parsed_step_data)
+      populate_parsing_data(parsed_step_data)
+    end
+
+    def populate_text(parsed_step_data)
+      @text = parsed_step_data['name']
+    end
+
+    def populate_block(parsed_step_data)
+      @block = if parsed_step_data['table']
+                 build_child_model(Table, parsed_step_data['table'])
+               elsif parsed_step_data['doc_string']
+                 build_child_model(DocString, parsed_step_data['doc_string'])
+               end
+    end
+
     def text_matches?(other_step)
       text == other_step.text
     end