cuke_modeler 3.20.0 → 3.20.1

data/lib/cuke_modeler/models/table.rb

@@ -14,31 +14,55 @@ module CukeModeler
 
     # Creates a new Table object and, if *source_text* is provided, populates
     # the object.
+    #
+    # @example
+    #   Table.new
+    #   Table.new("|value_1|value_2|\n|value_3|value_4|")
+    #
+    # @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 [Table] A new Table instance
     def initialize(source_text = nil)
       @rows = []
 
       super(source_text)
-
-      return unless source_text
-
-      parsed_table_data = parse_source(source_text)
-      populate_table(self, parsed_table_data)
     end
 
-    # Returns the model objects that belong to this model.
+    # Returns the model objects that are children of this model. For a
+    # Table model, these would be any associated Row models.
+    #
+    # @example
+    #   table.children
+    #
+    # @return [Array<Row>] A collection of child models
     def children
       rows
     end
 
-    # Returns a string representation of this model. For a table model,
+    # Returns a string representation of this model. For a Table model,
     # this will be Gherkin text that is equivalent to the table being modeled.
+    #
+    # @example
+    #   table.to_s
+    #
+    # @return [String] A string representation of this model
     def to_s
       rows.empty? ? '' : rows.collect { |row| row_output_string(row) }.join("\n")
     end
 
     # See `Object#inspect`. Returns some basic information about the
     # object, including its class, object ID, and its most meaningful
-    # attribute. For a table model, this will be the rows of the table.
+    # attribute. For a Table model, this will be the rows of the table.
+    # If *verbose* is true, provides default Ruby inspection behavior
+    # instead.
+    #
+    # @example
+    #   table.inspect
+    #   table.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
 
@@ -51,7 +75,7 @@ module CukeModeler
     private
 
 
-    def parse_source(source_text)
+    def process_source(source_text)
       base_file_string = "# language: #{Parsing.dialect}
       #{dialect_feature_keyword}:
                             #{dialect_scenario_keyword}:
@@ -63,6 +87,18 @@ module CukeModeler
       parsed_file['feature']['elements'].first['steps'].first['table']
     end
 
+    def populate_model(parsed_table_data)
+      populate_row_models(parsed_table_data)
+      populate_parsing_data(parsed_table_data)
+      populate_source_location(parsed_table_data)
+    end
+
+    def populate_row_models(parsed_table_data)
+      parsed_table_data['rows'].each do |row_data|
+        @rows << build_child_model(Row, row_data)
+      end
+    end
+
     def row_output_string(row)
       row_text = '|'
 

data/lib/cuke_modeler/models/tag.rb

@@ -6,32 +6,46 @@ module CukeModeler
     include Parsing
     include Parsed
     include Sourceable
-
-
-    # The name of the tag
-    attr_accessor :name
+    include Named
 
 
     # Creates a new Tag object and, if *source_text* is provided, populates the
     # object.
+    #
+    # @example
+    #   Tag.new
+    #   Tag.new('@a_tag')
+    #
+    # @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 [Tag] A new Tag instance
     def initialize(source_text = nil)
       super(source_text)
-
-      return unless source_text
-
-      parsed_tag_data = parse_source(source_text)
-      populate_tag(self, parsed_tag_data)
     end
 
-    # Returns a string representation of this model. For a tag model,
+    # Returns a string representation of this model. For a Tag model,
     # this will be Gherkin text that is equivalent to the tag being modeled.
+    #
+    # @example
+    #   tag.to_s
+    #
+    # @return [String] A string representation of this model
     def to_s
       name || ''
     end
 
     # See `Object#inspect`. Returns some basic information about the
     # object, including its class, object ID, and its most meaningful
-    # attribute. For a tag model, this will be the name of the tag.
+    # attribute. For a Tag model, this will be the name of the tag. If
+    # *verbose* is true, provides default Ruby inspection behavior instead.
+    #
+    # @example
+    #   tag.inspect
+    #   tag.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 +56,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,8 +65,10 @@ module CukeModeler
       parsed_file['feature']['tags'].first
     end
 
-    def populate_name(model, parsed_model_data)
-      model.name = parsed_model_data['name']
+    def populate_model(processed_tag_data)
+      populate_name(processed_tag_data)
+      populate_parsing_data(processed_tag_data)
+      populate_source_location(processed_tag_data)
     end
 
   end

data/lib/cuke_modeler/named.rb

@@ -1,9 +1,12 @@
 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 name.
+  # @api private
+  #
+  # A mix-in module containing methods used by models that represent an element that has a name. Internal helper class.
   module Named
 
+    # @api
+    #
     # The name of the element
     attr_accessor :name
 
@@ -15,8 +18,8 @@ module CukeModeler
       name.nil? || name.empty? ? '' : " #{name}"
     end
 
-    def populate_name(model, parsed_model_data)
-      model.name = parsed_model_data['name']
+    def populate_name(parsed_model_data)
+      @name = parsed_model_data['name']
     end
 
   end

data/lib/cuke_modeler/nested.rb

@@ -1,15 +1,30 @@
 module CukeModeler
 
-  # NOT A PART OF THE PUBLIC API
+  # @api private
+  #
   # A mix-in module containing methods used by models that are nested inside
-  # of other models.
+  # of other models. Internal helper class.
   module Nested
 
+    # @api
+    #
     # The parent model that contains this model
     attr_accessor :parent_model
 
-
-    # Returns the ancestor model of this model that matches the given type.
+    # TODO: Use an Enum type instead of symbols as arguments?
+
+    # @api
+    #
+    # Returns the ancestor model of this model that matches the given type. Available
+    # types are simply snake_case versions of the model Class names. Additionally, a
+    # special type *:test* will return either a Scenario or an Outline model.
+    #
+    # @example
+    #   model.get_ancestor(:directory)
+    #
+    # @param ancestor_type [Symbol] The ancestor type to get
+    # @raise [ArgumentError] If the passed type is not a valid model type
+    # @return [Model, nil] The ancestor model, if one is found
     def get_ancestor(ancestor_type)
       target_classes = classes_for_type(ancestor_type)
 

data/lib/cuke_modeler/parsed.rb

@@ -1,18 +1,23 @@
 module CukeModeler
 
-  # NOT A PART OF THE PUBLIC API
-  # A mix-in module containing methods used by models that are parsed from source text.
+  # @api private
+  #
+  # A mix-in module containing methods used by models that are parsed from
+  # source text. Internal helper class.
   module Parsed
 
-    # The parsing data for this element that was generated by the parsing engine (i.e. the *gherkin* gem)
+    # @api
+    #
+    # The parsing data for this element that was generated by
+    # the parsing engine (i.e. the *cucumber-gherkin* gem)
     attr_accessor :parsing_data
 
 
     private
 
 
-    def populate_parsing_data(model, parsed_model_data)
-      model.parsing_data = parsed_model_data['cuke_modeler_parsing_data']
+    def populate_parsing_data(parsed_model_data)
+      @parsing_data = parsed_model_data['cuke_modeler_parsing_data']
     end
 
   end

data/lib/cuke_modeler/parsing.rb

@@ -28,18 +28,38 @@ module CukeModeler
 
 
       # The dialect that will be used to parse snippets of Gherkin text
+      #
+      # @example
+      #   Parsing.dialect
+      #
+      # @return [String] The current dialect. Defaults to 'en'.
       def dialect
         @dialect || 'en'
       end
 
-      # The dialects currently known by the gherkin gem
+      # The dialects currently known by the cucumber-gherkin gem. See *Gherkin::DIALECTS*.
+      #
+      # @example
+      #   Parsing.dialects
+      #
+      # @return [Hash] The dialect data
       def dialects
         Gherkin::DIALECTS
       end
 
-      # Parses the Cucumber feature given in *source_text* and returns a hash representation of
+      # Parses the Cucumber feature given in *source_text* and returns a Hash representation of
       # its logical structure. This is a standardized AST that should remain consistent across
       # different versions of `cucumber-gherkin`
+      #
+      # @example
+      #   Parsing.parse_text('Feature: Some feature')
+      #   Parsing.parse_text('Feature: Some feature', 'my.feature')
+      #
+      # @param source_text [String] The Gherkin text to parse
+      # @param filename [String] The file name associated with the parsed text. Used for error messages.
+      # @raise [ArgumentError] If *source_text* is not a String
+      # @raise [ArgumentError] If *source_text* does not parse cleanly
+      # @return [Hash] An AST of the text
       def parse_text(source_text, filename = 'cuke_modeler_fake_file.feature')
         unless source_text.is_a?(String)
           raise(ArgumentError, "Text to parse must be a String but got #{source_text.class}")
@@ -55,6 +75,9 @@ module CukeModeler
       end
 
 
+      private
+
+
       gherkin_version = Gem.loaded_specs['cucumber-gherkin'].version.version
       gherkin_major_version = gherkin_version.match(/^(\d+)\./)[1].to_i
 
@@ -64,8 +87,6 @@ module CukeModeler
       # rubocop:disable Lint/DuplicateMethods
       case gherkin_major_version
         when 20, 21, 22, 23, 24, 25, 26, 27
-          # TODO: make these methods private?
-          # NOT A PART OF THE PUBLIC API
           # The method to use for parsing Gherkin text
           def parsing_method(source_text, filename)
             messages = Gherkin.from_source(filename,
@@ -81,8 +102,6 @@ module CukeModeler
             gherkin_ast_message.gherkin_document
           end
         when 19
-          # TODO: make these methods private?
-          # NOT A PART OF THE PUBLIC API
           # The method to use for parsing Gherkin text
           def parsing_method(source_text, filename)
             messages = Gherkin.from_source(filename,
@@ -98,8 +117,6 @@ module CukeModeler
             gherkin_ast_message[:gherkinDocument]
           end
         when 13, 14, 15, 16, 17, 18
-          # TODO: make these methods private?
-          # NOT A PART OF THE PUBLIC API
           # The method to use for parsing Gherkin text
           def parsing_method(source_text, filename)
             messages = Gherkin.from_source(filename,
@@ -115,8 +132,6 @@ module CukeModeler
             gherkin_ast_message[:gherkin_document]
           end
         when 12
-          # TODO: make these methods private?
-          # NOT A PART OF THE PUBLIC API
           # The method to use for parsing Gherkin text
           def parsing_method(source_text, filename)
             messages = Gherkin.from_source(filename,
@@ -134,8 +149,6 @@ module CukeModeler
             gherkin_ast_message[:gherkin_document]
           end
         when 9, 10, 11
-          # TODO: make these methods private?
-          # NOT A PART OF THE PUBLIC API
           # The method to use for parsing Gherkin text
           def parsing_method(source_text, filename)
             messages = Gherkin.from_source(filename,
@@ -155,7 +168,6 @@ module CukeModeler
       end
       # rubocop:enable Lint/DuplicateMethods
 
-      # NOT A PART OF THE PUBLIC API
       # The adapter to use when converting an AST to a standard internal shape
       define_method('adapter_class') do
         CukeModeler.const_get("Gherkin#{gherkin_major_version}Adapter")

data/lib/cuke_modeler/sourceable.rb

@@ -1,22 +1,28 @@
 module CukeModeler
 
-  # NOT A PART OF THE PUBLIC API
+  # @api private
+  #
   # A mix-in module containing methods used by models that know from which line of
-  # source code they originate.
+  # source code they originate. Internal helper class.
   module Sourceable
 
+    # @api
+    #
     # The line number where the element began in the source code
     attr_accessor :source_line
 
+    # @api
+    #
     # The column number where the element began in the source code
     attr_accessor :source_column
 
+
     private
 
 
-    def populate_source_location(model, parsed_model_data)
-      model.source_line = parsed_model_data['line']
-      model.source_column = parsed_model_data['column']
+    def populate_source_location(parsed_model_data)
+      @source_line = parsed_model_data['line']
+      @source_column = parsed_model_data['column']
     end
 
   end

data/lib/cuke_modeler/stepped.rb

@@ -1,10 +1,12 @@
 module CukeModeler
 
-  # NOT A PART OF THE PUBLIC API
-  # A mix-in module containing methods used by models that represent an element that has steps.
+  # @api private
+  #
+  # A mix-in module containing methods used by models that represent an element that has steps. Internal helper class.
   module Stepped
 
-
+    # @api
+    #
     # The step models contained by this model
     attr_accessor :steps
 
@@ -20,11 +22,11 @@ module CukeModeler
       step.to_s.split("\n").collect { |line| "  #{line}" }.join("\n")
     end
 
-    def populate_steps(model, parsed_model_data)
+    def populate_steps(parsed_model_data)
       return unless parsed_model_data['steps']
 
       parsed_model_data['steps'].each do |step_data|
-        model.steps << build_child_model(Step, step_data)
+        @steps << build_child_model(Step, step_data)
       end
     end
 

data/lib/cuke_modeler/taggable.rb

@@ -1,20 +1,38 @@
 module CukeModeler
 
-  # NOT A PART OF THE PUBLIC API
-  # A mix-in module containing methods used by models that represent an element that can be tagged.
+  # @api private
+  #
+  # A mix-in module containing methods used by models that represent an element that can be
+  # tagged. Internal helper class.
   module Taggable
 
+    # @api
+    #
     # The models for tags which are directly assigned to the element
     attr_accessor :tags
 
 
+    # @api
+    #
     # Returns the models for tags which are indirectly assigned to the element (i.e. they
     # have been inherited from a parent element).
+    #
+    # @example
+    #   model.applied_tags
+    #
+    # @return [Array<Tag>] Applied tag models
     def applied_tags
       parent_model.respond_to?(:all_tags) ? parent_model.all_tags : []
     end
 
+    # @api
+    #
     # Returns models for all of the tags which are applicable to the element.
+    #
+    # @example
+    #   model.all_tags
+    #
+    # @return [Array<Tag>] All tag models
     def all_tags
       applied_tags + @tags
     end
@@ -27,11 +45,11 @@ module CukeModeler
       tags.map(&:name).join(' ')
     end
 
-    def populate_tags(model, parsed_model_data)
+    def populate_tags(parsed_model_data)
       return unless parsed_model_data['tags']
 
       parsed_model_data['tags'].each do |tag|
-        model.tags << build_child_model(Tag, tag)
+        @tags << build_child_model(Tag, tag)
       end
     end
 

data/lib/cuke_modeler/version.rb

@@ -1,4 +1,4 @@
 module CukeModeler
   # The gem version
-  VERSION = '3.20.0'.freeze
+  VERSION = '3.20.1'.freeze
 end

data/testing/cucumber/features/modeling/base_model.feature

@@ -0,0 +1,3 @@
+# TODO: demo the base model class and generic model usage (it's not abstract, just situationally useful)
+@wip
+Feature:

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cuke_modeler
 version: !ruby/object:Gem::Version
-  version: 3.20.0
+  version: 3.20.1
 platform: ruby
 authors:
 - Eric Kessler
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-09-22 00:00:00.000000000 Z
+date: 2023-10-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cucumber-gherkin
@@ -266,6 +266,7 @@ files:
 - testing/cucumber/features/analysis/test_comparison.feature
 - testing/cucumber/features/modeling/background_modeling.feature
 - testing/cucumber/features/modeling/background_output.feature
+- testing/cucumber/features/modeling/base_model.feature
 - testing/cucumber/features/modeling/cell_modeling.feature
 - testing/cucumber/features/modeling/cell_output.feature
 - testing/cucumber/features/modeling/comment_modeling.feature