cuke_modeler 3.20.0 → 3.21.0

data/lib/cuke_modeler/containing.rb

@@ -1,17 +1,26 @@
-# It's the module that has functionality for every possible model type. So, yes, it's long.
-# rubocop:disable Metrics/ModuleLength
-
 module CukeModeler
 
-  # NOT A PART OF THE PUBLIC API
-  # A mix-in module containing methods used by models that contain other models.
+  # @api private
+  #
+  # A mix-in module containing methods used by models that contain other models. Internal helper class.
   module Containing
 
     include Enumerable
 
+    # TODO: Have this method return `self` so that method chaining can be done?
+
+    # @api
+    #
     # Executes the given code block with this model and every model that is a child of this model. Exact
     # order of model tree traversal is not guaranteed beyond the first model traversed, which will be the
     # model that called this method. If no block is provided, an `Enumerator` is returned instead.
+    #
+    # @example
+    #   model.each
+    #   model.each { |model| puts model.inspect }
+    #
+    # @yieldparam [Model] The current model being visited
+    # @return [Enumerable] if no block is given
     def each(&block)
       if block
         block.call(self)
@@ -21,8 +30,15 @@ module CukeModeler
       end
     end
 
+    # @api
+    # @deprecated Use `Enumerable` module methods instead
+    #
     # Executes the given code block with every model that is a child of this model.
-    # DEPRECATED: use `Enumerable` module methods instead
+    #
+    # @example
+    #   model.each_descendant { |model| puts model.inspect }
+    #
+    # @yieldparam [Model] The current model being visited
     def each_descendant(&block)
       children.each do |child_model|
         block.call(child_model)
@@ -30,8 +46,15 @@ module CukeModeler
       end
     end
 
+    # @api
+    # @deprecated Use `Enumerable` module methods instead
+    #
     # Executes the given code block with this model and every model that is a child of this model.
-    # DEPRECATED: use `Enumerable` module methods instead
+    #
+    # @example
+    #   model.each_model { |model| puts model.inspect }
+    #
+    # @yieldparam [Model] The current model being visited
     def each_model(&block)
       block.call(self)
 
@@ -44,229 +67,39 @@ module CukeModeler
 
     def build_child_model(clazz, model_data)
       model = clazz.new
-
-      tiny_class = clazz.name.match(/::(\w+)/)[1].downcase
-      model.send("populate_#{tiny_class}", model, model_data)
-
+      # Send-ing to get around private scoping. Don't want the make the method public
+      # and there is no way to get the already processed data to the child model that
+      # wouldn't require something public.
+      model.send('populate_model', model_data)
       model.parent_model = self
 
       model
     end
 
-    def populate_scenario(scenario_object, parsed_scenario_data)
-      populate_parsing_data(scenario_object, parsed_scenario_data)
-      populate_source_location(scenario_object, parsed_scenario_data)
-      populate_keyword(scenario_object, parsed_scenario_data)
-      populate_name(scenario_object, parsed_scenario_data)
-      populate_description(scenario_object, parsed_scenario_data)
-      populate_steps(scenario_object, parsed_scenario_data)
-      populate_tags(scenario_object, parsed_scenario_data)
-    end
-
-    def populate_outline(outline_object, parsed_outline_data)
-      populate_parsing_data(outline_object, parsed_outline_data)
-      populate_source_location(outline_object, parsed_outline_data)
-      populate_keyword(outline_object, parsed_outline_data)
-      populate_name(outline_object, parsed_outline_data)
-      populate_description(outline_object, parsed_outline_data)
-      populate_steps(outline_object, parsed_outline_data)
-      populate_tags(outline_object, parsed_outline_data)
-      populate_outline_examples(outline_object, parsed_outline_data['examples']) if parsed_outline_data['examples']
-    end
-
-    def populate_background(background_object, parsed_background_data)
-      populate_parsing_data(background_object, parsed_background_data)
-      populate_keyword(background_object, parsed_background_data)
-      populate_name(background_object, parsed_background_data)
-      populate_description(background_object, parsed_background_data)
-      populate_source_location(background_object, parsed_background_data)
-      populate_steps(background_object, parsed_background_data)
-    end
-
-    def populate_step(step_object, parsed_step_data)
-      populate_text(step_object, parsed_step_data)
-      populate_block(step_object, parsed_step_data)
-      populate_keyword(step_object, parsed_step_data)
-      populate_source_location(step_object, parsed_step_data)
-      populate_parsing_data(step_object, parsed_step_data)
-    end
-
-    def populate_block(step_object, parsed_step_data)
-      step_object.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 populate_table(table_object, parsed_table_data)
-      populate_row_models(table_object, parsed_table_data)
-      populate_parsing_data(table_object, parsed_table_data)
-      populate_source_location(table_object, parsed_table_data)
-    end
-
-    def populate_cell(cell_object, parsed_cell_data)
-      populate_cell_value(cell_object, parsed_cell_data)
-      populate_source_location(cell_object, parsed_cell_data)
-      populate_parsing_data(cell_object, parsed_cell_data)
-    end
-
-    def populate_docstring(doc_string_object, parsed_doc_string_data)
-      populate_content_type(doc_string_object, parsed_doc_string_data)
-      populate_content(doc_string_object, parsed_doc_string_data)
-      populate_parsing_data(doc_string_object, parsed_doc_string_data)
-      populate_source_location(doc_string_object, parsed_doc_string_data)
+    # TODO: move to mix-in module
+    def populate_keyword(parsed_model_data)
+      @keyword = parsed_model_data['keyword'].strip
     end
 
-    def populate_example(example_object, parsed_example_data)
-      populate_parsing_data(example_object, parsed_example_data)
-      populate_keyword(example_object, parsed_example_data)
-      populate_source_location(example_object, parsed_example_data)
-      populate_name(example_object, parsed_example_data)
-      populate_description(example_object, parsed_example_data)
-      populate_tags(example_object, parsed_example_data)
-      populate_example_rows(example_object, parsed_example_data)
-    end
-
-    def populate_row(row_object, parsed_row_data)
-      populate_source_location(row_object, parsed_row_data)
-      populate_row_cells(row_object, parsed_row_data)
-      populate_parsing_data(row_object, parsed_row_data)
-    end
-
-    def populate_feature(feature_object, parsed_feature_data)
-      populate_parsing_data(feature_object, parsed_feature_data)
-      populate_source_location(feature_object, parsed_feature_data)
-      populate_language(feature_object, parsed_feature_data)
-      populate_keyword(feature_object, parsed_feature_data)
-      populate_name(feature_object, parsed_feature_data)
-      populate_description(feature_object, parsed_feature_data)
-      populate_tags(feature_object, parsed_feature_data)
-      populate_children(feature_object, parsed_feature_data)
-    end
-
-    def populate_rule(rule_object, parsed_rule_data)
-      populate_parsing_data(rule_object, parsed_rule_data)
-      populate_source_location(rule_object, parsed_rule_data)
-      populate_keyword(rule_object, parsed_rule_data)
-      populate_name(rule_object, parsed_rule_data)
-      populate_description(rule_object, parsed_rule_data)
-      populate_tags(rule_object, parsed_rule_data)
-      populate_children(rule_object, parsed_rule_data)
-    end
-
-    def populate_directory(directory_object, processed_directory_data)
-      directory_object.path = processed_directory_data['path']
-
-      processed_directory_data['directories'].each do |directory_data|
-        directory_object.directories << build_child_model(Directory, directory_data)
-      end
-
-      processed_directory_data['feature_files'].each do |feature_file_data|
-        directory_object.feature_files << build_child_model(FeatureFile, feature_file_data)
-      end
-    end
-
-    def populate_featurefile(feature_file_object, processed_feature_file_data)
-      populate_parsing_data(feature_file_object, processed_feature_file_data)
-      feature_file_object.path = processed_feature_file_data['path']
-
-      if processed_feature_file_data['feature']
-        feature_file_object.feature = build_child_model(Feature, processed_feature_file_data['feature'])
-      end
-
-      processed_feature_file_data['comments'].each do |comment_data|
-        feature_file_object.comments << build_child_model(Comment, comment_data)
-      end
-    end
-
-    def populate_tag(tag_object, processed_tag_data)
-      populate_name(tag_object, processed_tag_data)
-      populate_parsing_data(tag_object, processed_tag_data)
-      populate_source_location(tag_object, processed_tag_data)
-    end
-
-    def populate_comment(comment_object, processed_comment_data)
-      populate_comment_text(comment_object, processed_comment_data)
-      populate_parsing_data(comment_object, processed_comment_data)
-      populate_source_location(comment_object, processed_comment_data)
-    end
-
-    def populate_language(feature_model, parsed_feature_data)
-      feature_model.language = parsed_feature_data['language']
-    end
-
-    def populate_comment_text(comment_model, parsed_comment_data)
-      comment_model.text = parsed_comment_data['text'].strip
-    end
-
-    def populate_text(step_model, parsed_step_data)
-      step_model.text = parsed_step_data['name']
-    end
-
-    def populate_keyword(model, parsed_model_data)
-      model.keyword = parsed_model_data['keyword'].strip
-    end
-
-    def populate_row_models(table_model, parsed_table_data)
-      parsed_table_data['rows'].each do |row_data|
-        table_model.rows << build_child_model(Row, row_data)
-      end
-    end
-
-    def populate_row_cells(row_model, parsed_row_data)
-      parsed_row_data['cells'].each do |cell_data|
-        row_model.cells << build_child_model(Cell, cell_data)
-      end
-    end
-
-    def populate_cell_value(cell_model, parsed_cell_data)
-      cell_model.value = parsed_cell_data['value']
-    end
-
-    def populate_content_type(doc_string_model, parsed_doc_string_data)
-      doc_string_model.content_type = parsed_doc_string_data['content_type']
-    end
-
-    def populate_content(doc_string_model, parsed_doc_string_data)
-      doc_string_model.content = parsed_doc_string_data['value']
-    end
-
-    def populate_outline_examples(outline_model, parsed_examples)
-      parsed_examples.each do |example_data|
-        outline_model.examples << build_child_model(Example, example_data)
-      end
-    end
-
-    def populate_example_rows(example_model, parsed_example_data)
-      parsed_example_data['rows'].each do |row_data|
-        example_model.rows << build_child_model(Row, row_data)
-      end
-    end
-
-    # It's not getting better any time soon
-    # rubocop:disable Metrics/AbcSize
-
-    def populate_children(model, parsed_feature_data)
+    # TODO: move elsewhere?
+    def populate_children(parsed_feature_data)
       return unless parsed_feature_data['elements']
 
       parsed_feature_data['elements'].each do |element|
         case element['type']
           when 'Scenario', 'scenario'
-            model.tests << build_child_model(Scenario, element)
+            @tests << build_child_model(Scenario, element)
           when 'ScenarioOutline', 'scenario_outline'
-            model.tests << build_child_model(Outline, element)
+            @tests << build_child_model(Outline, element)
           when 'Background', 'background'
-            model.background = build_child_model(Background, element)
+            @background = build_child_model(Background, element)
           when 'Rule'
-            model.rules << build_child_model(Rule, element)
+            @rules << build_child_model(Rule, element)
           else
             raise(ArgumentError, "Unknown element type: #{element['type']}")
         end
       end
     end
-    # rubocop:enable Metrics/AbcSize
 
   end
 end
-# rubocop:enable Metrics/ModuleLength

data/lib/cuke_modeler/described.rb

@@ -1,9 +1,13 @@
 module CukeModeler
 
-  # NOT A PART OF THE PUBLIC API
-  # A mix-in module containing methods used by models that represent an element that has a description.
+  # @api private
+  #
+  # A mix-in module containing methods used by models that represent an element that has a
+  # description. Internal helper class.
   module Described
 
+    # @api
+    #
     # The description of the element
     attr_accessor :description
 
@@ -28,8 +32,8 @@ module CukeModeler
       description.nil? || description.empty?
     end
 
-    def populate_description(model, parsed_model_data)
-      model.description = trimmed_description(parsed_model_data['description'])
+    def populate_description(parsed_model_data)
+      @description = trimmed_description(parsed_model_data['description'])
     end
 
     def trimmed_description(description)

data/lib/cuke_modeler/models/background.rb

@@ -17,31 +17,55 @@ module CukeModeler
 
     # Creates a new Background object and, if *source_text* is provided, populates
     # the object.
+    #
+    # @example
+    #   Background.new
+    #   Background.new("Background:\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 [Background] A new Background instance
     def initialize(source_text = nil)
       @steps = []
 
       super(source_text)
-
-      return unless source_text
-
-      parsed_background_data = parse_source(source_text)
-      populate_background(self, parsed_background_data)
     end
 
-    # Returns *true* if the two models have equivalent steps and *false* otherwise.
+    # TODO: Have (all) models be equivalent if they have the same #to_s output. Would
+    # likely require major version change.
+
+    # Compares this model with another object. Returns *true* if the two objects
+    # have equivalent steps and *false* otherwise.
+    #
+    # @example
+    #   background_1 == background_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
+    # Background model, these would be any associated Step models.
+    #
+    # @example
+    #   background.children
+    #
+    # @return [Array<Step>] A collection of child models
     def children
       steps
     end
 
-    # Returns a string representation of this model. For a background model,
+    # Returns a string representation of this model. For a Background model,
     # this will be Gherkin text that is equivalent to the background being modeled.
+    #
+    # @example
+    #   background.to_s
+    #
+    # @return [String] A string representation of this model
     def to_s
       text = ''
 
@@ -55,8 +79,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 background model, this will be the name of the
-    # background.
+    # attribute. For a Background model, this will be the name of the
+    # background. If *verbose* is true, provides default Ruby inspection
+    # behavior instead.
+    #
+    # @example
+    #   background.inspect
+    #   background.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
 
@@ -67,7 +100,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
 
@@ -76,5 +109,14 @@ module CukeModeler
       parsed_file['feature']['elements'].first
     end
 
+    def populate_model(parsed_background_data)
+      populate_parsing_data(parsed_background_data)
+      populate_keyword(parsed_background_data)
+      populate_name(parsed_background_data)
+      populate_description(parsed_background_data)
+      populate_source_location(parsed_background_data)
+      populate_steps(parsed_background_data)
+    end
+
   end
 end

data/lib/cuke_modeler/models/cell.rb

@@ -14,17 +14,25 @@ module CukeModeler
 
     # Creates a new Cell object and, if *source_text* is provided, populates
     # the object.
+    #
+    # @example
+    #   Cell.new
+    #   Cell.new('some value')
+    #
+    # @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 [Cell] A new Cell instance
     def initialize(source_text = nil)
       super(source_text)
-
-      return unless source_text
-
-      parsed_cell_data = parse_source(source_text)
-      populate_cell(self, parsed_cell_data)
     end
 
-    # Returns a string representation of this model. For a cell model,
+    # Returns a string representation of this model. For a Cell model,
     # this will be Gherkin text that is equivalent to the cell being modeled.
+    #
+    # @example
+    #   cell.to_s
+    #
+    # @return [String] A string representation of this model
     def to_s
       # Vertical bars and backslashes are special characters that need to be escaped
       @value ? @value.gsub('\\', '\\\\\\').gsub('|', '\|') : ''
@@ -32,7 +40,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 cell model, this will be the value of the cell.
+    # attribute. For a Cell model, this will be the value of the
+    # cell. If *verbose* is true, provides default Ruby inspection
+    # behavior instead.
+    #
+    # @example
+    #   cell.inspect
+    #   cell.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
 
@@ -43,7 +61,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}:
@@ -55,6 +73,16 @@ module CukeModeler
       parsed_file['feature']['elements'].first['steps'].first['table']['rows'].first['cells'].first
     end
 
+    def populate_model(parsed_cell_data)
+      populate_cell_value(parsed_cell_data)
+      populate_source_location(parsed_cell_data)
+      populate_parsing_data(parsed_cell_data)
+    end
+
+    def populate_cell_value(parsed_cell_data)
+      @value = parsed_cell_data['value']
+    end
+
   end
 
 end

data/lib/cuke_modeler/models/comment.rb

@@ -14,24 +14,41 @@ module CukeModeler
 
     # Creates a new Comment object and, if *source_text* is provided, populates the
     # object.
+    #
+    # @example
+    #   Comment.new
+    #   Comment.new('# A comment')
+    #
+    # @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 [Comment] A new Comment instance
     def initialize(source_text = nil)
       super(source_text)
-
-      return unless source_text
-
-      parsed_comment_data = parse_source(source_text)
-      populate_comment(self, parsed_comment_data)
     end
 
-    # Returns a string representation of this model. For a comment model,
+    # Returns a string representation of this model. For a Comment model,
     # this will be Gherkin text that is equivalent to the comment being modeled.
+    #
+    # @example
+    #   comment.to_s
+    #
+    # @return [String] A string representation of this model
     def to_s
       text || ''
     end
 
     # See `Object#inspect`. Returns some basic information about the
     # object, including its class, object ID, and its most meaningful
-    # attribute. For a comment model, this will be the text of the comment.
+    # attribute. For a Comment model, this will be the text of the comment.
+    # If *verbose* is true, provides default Ruby inspection behavior instead.
+    #
+    # @example
+    #   comment.inspect
+    #   comment.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
 
@@ -42,7 +59,7 @@ module CukeModeler
     private
 
 
-    def parse_source(source_text)
+    def process_source(source_text)
       base_file_string = "\n#{dialect_feature_keyword}: Fake feature to parse"
       source_text = "# language: #{Parsing.dialect}\n" + source_text + base_file_string
 
@@ -51,5 +68,15 @@ module CukeModeler
       parsed_file['comments'].last
     end
 
+    def populate_model(processed_comment_data)
+      populate_comment_text(processed_comment_data)
+      populate_parsing_data(processed_comment_data)
+      populate_source_location(processed_comment_data)
+    end
+
+    def populate_comment_text(parsed_comment_data)
+      @text = parsed_comment_data['text'].strip
+    end
+
   end
 end