cuke_modeler 3.19.0 → 3.20.1

data/lib/cuke_modeler/models/table.rb

@@ -14,33 +14,68 @@ 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.
+    # 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
+
+      row_output = @rows&.collect { |row| row.cells.collect(&:value) }
+
+      "#{super.chop} @rows: #{row_output.inspect}>"
+    end
+
 
     private
 
 
-    def parse_source(source_text)
+    def process_source(source_text)
       base_file_string = "# language: #{Parsing.dialect}
       #{dialect_feature_keyword}:
                             #{dialect_scenario_keyword}:
@@ -52,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,34 +6,57 @@ 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. 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
+
+      "#{super.chop} @name: #{@name.inspect}>"
+    end
+
 
     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
 
@@ -42,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

@@ -9,7 +9,7 @@ require 'gherkin'
 # an 'adapter' appropriate to the version of the *cucumber-gherkin* gem that has been activated.
 gherkin_version = Gem.loaded_specs['cucumber-gherkin'].version.version
 gherkin_major_version = gherkin_version.match(/^(\d+)\./)[1].to_i
-supported_gherkin_versions = (9..26)
+supported_gherkin_versions = (9..27)
 
 raise("Unknown Gherkin version: '#{gherkin_version}'") unless supported_gherkin_versions.include?(gherkin_major_version)
 
@@ -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
 
@@ -63,9 +86,7 @@ module CukeModeler
       # inside of it, so I'm leaving this here in case it changes again
       # rubocop:disable Lint/DuplicateMethods
       case gherkin_major_version
-        when 20, 21, 22, 23, 24, 25, 26
-          # TODO: make these methods private?
-          # NOT A PART OF THE PUBLIC API
+        when 20, 21, 22, 23, 24, 25, 26, 27
           # 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")
@@ -185,7 +197,7 @@ module CukeModeler
     end
 
     def get_word(word_set)
-      word_set = word_set.is_a?(Array) ? word_set : word_set.split('|')
+      word_set = word_set.split('|') unless word_set.is_a?(Array)
 
       word_set.first
     end

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.19.0'.freeze
+  VERSION = '3.20.1'.freeze
 end

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

@@ -1,9 +1,10 @@
 Feature: Background output
 
-  A background model's string output is a Gherkin representation of itself. As such, output from a background model can be used as input for the same kind of model.
+  A background model's string output is a Gherkin representation of itself and its most relevant attribute for
+  inspection is the name of the background that it models.
 
 
-  Scenario: Outputting a background model
+  Background:
     Given the following gherkin:
       """
       Background: A background with everything that it could have
@@ -20,11 +21,14 @@ Feature: Background output
       """
     And a background model based on that gherkin
       """
-        @model = CukeModeler::Background.new(<source_text>)
+      @model = CukeModeler::Background.new(<source_text>)
       """
+
+
+  Scenario: Stringify a background model
     When the model is output as a string
       """
-        @model.to_s
+      @model.to_s
       """
     Then the following text is provided:
       """
@@ -42,5 +46,15 @@ Feature: Background output
       """
     And the output can be used to make an equivalent model
       """
-        CukeModeler::Background.new(@model.to_s)
+      CukeModeler::Background.new(@model.to_s)
+      """
+
+  Scenario: Inspect a background model
+    When the model is inspected
+      """
+      @model.inspect
+      """
+    Then the following text is provided:
+      """
+      #<CukeModeler::Background:<object_id> @name: "A background with everything that it could have">
       """

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:

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

@@ -1,22 +1,36 @@
 Feature: Cell output
 
-  A cell model's string output is a Gherkin representation of itself.
+  A cell model's string output is a Gherkin representation of itself and its most relevant attribute for
+  inspection is the value of the cell that it models.
 
 
-  Scenario: Outputting a cell model
+  Background:
     Given the following gherkin:
       """
       foo
       """
     And a cell model based on that gherkin
       """
-        @model = CukeModeler::Cell.new(<source_text>)
+      @model = CukeModeler::Cell.new(<source_text>)
       """
+
+
+  Scenario: Stringify a cell model
     When the model is output as a string
       """
-        @model.to_s
+      @model.to_s
       """
     Then the following text is provided:
       """
       foo
       """
+
+  Scenario: Inspect a cell model
+    When the model is inspected
+      """
+      @model.inspect
+      """
+    Then the following text is provided:
+      """
+      #<CukeModeler::Cell:<object_id> @value: "foo">
+      """

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

@@ -1,20 +1,24 @@
 Feature: Comment output
 
-  A comment model's string output is a Gherkin representation of itself. As such, output from a comment model can be used as input for the same kind of model.
+  A comment model's string output is a Gherkin representation of itself and its most relevant attribute for
+  inspection is the text of the comment that it models.
 
 
-  Scenario: Outputting a comment model
+  Background:
     Given the following gherkin:
       """
       # a comment
       """
     And a comment model based on that gherkin
       """
-        @model = CukeModeler::Comment.new(<source_text>)
+      @model = CukeModeler::Comment.new(<source_text>)
       """
+
+
+  Scenario: Stringify a comment model
     When the model is output as a string
       """
-        @model.to_s
+      @model.to_s
       """
     Then the following text is provided:
       """
@@ -22,5 +26,15 @@ Feature: Comment output
       """
     And the output can be used to make an equivalent model
       """
-        CukeModeler::Comment.new(@model.to_s)
+      CukeModeler::Comment.new(@model.to_s)
+      """
+
+  Scenario: Inspect a comment model
+    When the model is inspected
+      """
+      @model.inspect
+      """
+    Then the following text is provided:
+      """
+      #<CukeModeler::Comment:<object_id> @text: "# a comment">
       """