cuke_modeler 3.19.0 → 3.20.1

data/lib/cuke_modeler/models/directory.rb

@@ -16,40 +16,86 @@ module CukeModeler
 
     # Creates a new Directory object and, if *directory_path* is provided,
     # populates the object.
+    #
+    # @example
+    #   Directory.new
+    #   Directory.new('some/directory/path')
+    #
+    # @param directory_path [String] The directory path that will be used to populate the model
+    # @raise [ArgumentError] If *directory_path* is not a String
+    # @raise [ArgumentError] If the directory path does not exist
+    # @return [Directory] A new Directory instance
     def initialize(directory_path = nil)
       @path = directory_path
       @feature_files = []
       @directories = []
 
       super(directory_path)
-
-      return unless directory_path
-      raise(ArgumentError, "Unknown directory: #{directory_path.inspect}") unless File.exist?(directory_path)
-
-      processed_directory_data = process_directory(directory_path)
-      populate_directory(self, processed_directory_data)
     end
 
     # Returns the name of the modeled directory.
+    #
+    # @example
+    #   d = Directory.new('some/directory/foo')
+    #   d.name  #=> 'foo'
+    #
+    # @return [String, nil] The name of the directory
     def name
       File.basename(@path.gsub('\\', '/')) if @path
     end
 
-    # Returns the model objects that belong to this model.
+    # Returns the model objects that are children of this model. For a
+    # Directory model, these would be any associated Directory and FeatureFile
+    # models.
+    #
+    # @example
+    #   directory.children
+    #
+    # @return [Array<Directory, FeatureFile>] A collection of child models
     def children
       @feature_files + @directories
     end
 
-    # Returns a string representation of this model. For a directory
+    # Returns a string representation of this model. For a Directory
     # model, this will be the path of the modeled directory.
+    #
+    # @example
+    #   directory.to_s #=> 'some/directory/path'
+    #
+    # @return [String] A string representation of this model
     def to_s
       path.to_s
     end
 
+    # See `Object#inspect`. Returns some basic information about the
+    # object, including its class, object ID, and its most meaningful
+    # attribute. For a Directory model, this will be the path of the
+    # directory. If *verbose* is true, provides default Ruby inspection
+    # behavior instead.
+    #
+    # @example
+    #   directory.inspect
+    #   directory.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} @path: #{@path.inspect}>"
+    end
+
 
     private
 
 
+    def process_source(directory_path)
+      raise(ArgumentError, "Unknown directory: #{directory_path.inspect}") unless File.exist?(directory_path)
+
+      process_directory(directory_path)
+    end
+
     def process_directory(directory_path)
       directory_data = { 'path'          => directory_path,
                          'directories'   => [],
@@ -81,5 +127,17 @@ module CukeModeler
       feature_file_data.merge({ 'path' => file_path })
     end
 
+    def populate_model(processed_directory_data)
+      @path = processed_directory_data['path']
+
+      processed_directory_data['directories'].each do |directory_data|
+        @directories << build_child_model(Directory, directory_data)
+      end
+
+      processed_directory_data['feature_files'].each do |feature_file_data|
+        @feature_files << build_child_model(FeatureFile, feature_file_data)
+      end
+    end
+
   end
 end

data/lib/cuke_modeler/models/doc_string.rb

@@ -17,28 +17,55 @@ module CukeModeler
 
     # Creates a new DocString object and, if *source_text* is provided, populates
     # the object.
+    #
+    # @example
+    #   DocString.new
+    #   DocString.new("\"\"\" some_type\n  foo\n\"\"\"")
+    #
+    # @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 [DocString] A new DocString instance
     def initialize(source_text = nil)
       super(source_text)
-
-      return unless source_text
-
-      parsed_doc_string_data = parse_source(source_text)
-      populate_docstring(self, parsed_doc_string_data)
     end
 
-    # Returns a string representation of this model. For a doc string model,
+    # Returns a string representation of this model. For a DocString model,
     # this will be Gherkin text that is equivalent to the doc string being modeled.
+    #
+    # @example
+    #   doc_string.to_s
+    #
+    # @return [String] A string representation of this model
     def to_s
       text = "\"\"\"#{content_type_output_string}\n"
       text << content_output_string
       text << '"""'
     end
 
+    # See `Object#inspect`. Returns some basic information about the
+    # object, including its class, object ID, and its most meaningful
+    # attribute. For a DocString model, this will be the content of the
+    # doc string. If *verbose* is true, provides default Ruby inspection
+    # behavior instead.
+    #
+    # @example
+    #   doc_string.inspect
+    #   doc_string.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} @content: #{content.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}:
@@ -50,6 +77,21 @@ module CukeModeler
       parsed_file['feature']['elements'].first['steps'].first['doc_string']
     end
 
+    def populate_model(parsed_doc_string_data)
+      populate_content_type(parsed_doc_string_data)
+      populate_content(parsed_doc_string_data)
+      populate_parsing_data(parsed_doc_string_data)
+      populate_source_location(parsed_doc_string_data)
+    end
+
+    def populate_content_type(parsed_doc_string_data)
+      @content_type = parsed_doc_string_data['content_type']
+    end
+
+    def populate_content(parsed_doc_string_data)
+      @content = parsed_doc_string_data['value']
+    end
+
     def content_type_output_string
       content_type ? " #{content_type}" : ''
     end

data/lib/cuke_modeler/models/example.rb

@@ -23,28 +23,42 @@ module CukeModeler
 
     # Creates a new Example object and, if *source_text* is provided,
     # populates the object.
+    #
+    # @example
+    #   Example.new
+    #   Example.new("|param_1|param_2|\n|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 [Example] A new Example instance
     def initialize(source_text = nil)
       @tags = []
       @rows = []
 
       super(source_text)
-
-      return unless source_text
-
-      parsed_example_data = parse_source(source_text)
-      populate_example(self, parsed_example_data)
     end
 
+    # TODO: Deprecate using symbol keys in a Hash
+
     # Adds a row to the example table. The row can be given as a Hash of
     # parameters and their corresponding values or as an Array of values which
     # will be assigned in order.
+    #
+    # @example
+    #   example.add_row({'param1' => 'value1', 'param2' => 'value2'})
+    #   example.add_row({param1: 'value1', param2: 'value2'})
+    #   example.add_row(['value1', 'value2'])
+    #
+    # @param row [Hash, Array<String>] The the cell values to use for the added row
+    # @raise [ArgumentError] If *row* is not a Hash or Array
+    # @raise [Exception] If the model has no initial parameter row
     def add_row(row)
       raise('Cannot add a row. No parameters have been set.') if rows.empty?
 
       # A quick 'deep clone' so that the input isn't modified
       row = Marshal.load(Marshal.dump(row))
 
-      values = if row.is_a?(Array) # rubocop:disable Style/CaseLikeIf # False positive
+      values = if row.is_a?(Array)
                  row
                elsif row.is_a?(Hash)
                  # There is no guarantee that the user built up their hash with the keys in the same order as
@@ -58,42 +72,74 @@ module CukeModeler
       @rows << Row.new("|#{values.join('|')}|")
     end
 
+    # TODO: Add exception if using symbol keys in a Hash
+
     # Removes a row from the example table. The row can be given as a Hash of
     # parameters and their corresponding values or as an Array of values
     # which will be assigned in order.
-    def remove_row(row_removed)
+    #
+    # @example
+    #   example.remove_row({'param1' => 'value1', 'param2' => 'value2'})
+    #   example.remove_row(['value1', 'value2'])
+    #
+    # @param row [Hash, Array<String>] The the cell values to use for the added row
+    # @raise [ArgumentError] If *row* is not a Hash or Array
+    def remove_row(row)
       return if argument_rows.empty?
 
-      values = if row_removed.is_a?(Array) # rubocop:disable Style/CaseLikeIf # False positive
-                 row_removed
-               elsif row_removed.is_a?(Hash)
+      values = if row.is_a?(Array)
+                 row
+               elsif row.is_a?(Hash)
                  # There is no guarantee that the user built up their hash with the keys in the same order as
                  # the parameter row and so the values have to be ordered by us.
-                 ordered_row_values(row_removed)
+                 ordered_row_values(row)
                else
-                 raise(ArgumentError, "Can only remove row from a Hash or an Array but received #{row_removed.class}")
+                 raise(ArgumentError, "Can only remove row from a Hash or an Array but received #{row.class}")
                end
 
       location = index_for_values(values.map(&:to_s).map(&:strip))
       @rows.delete_at(location + 1) if location
     end
 
-    # The argument rows in the example table
+    # Returns the Row models associated with the argument rows
+    # in the example table
+    #
+    # @example
+    #   example.argument_rows
+    #
+    # @return [Array<Row>] The argument row models
     def argument_rows
       rows[1..rows.count] || []
     end
 
-    # The parameter row for the example table
+    # Returns the Row model associated with the parameter row
+    # in the example table
+    #
+    # @example
+    #   example.parameter_row
+    #
+    # @return [Row, nil] The parameter row model
     def parameter_row
       rows.first
     end
 
     # Returns the parameters of the example table
+    #
+    # @example
+    #   example.parameters #=> ['param_1', 'param_2']
+    #
+    # @return [Array<String>] The parameters
     def parameters
       parameter_row ? parameter_row.cells.map(&:value) : []
     end
 
-    # Returns the model objects that belong to this model.
+    # Returns the model objects that are children of this model. For an
+    # Example model, these would be any associated Row or Tag models.
+    #
+    # @example
+    #   example.children
+    #
+    # @return [Array<Row, Tag>] A collection of child models
     def children
       rows + tags
     end
@@ -101,8 +147,13 @@ module CukeModeler
     # Building strings just isn't pretty
     # rubocop:disable Metrics/AbcSize
 
-    # Returns a string representation of this model. For an example model,
+    # Returns a string representation of this model. For an Example model,
     # this will be Gherkin text that is equivalent to the example being modeled.
+    #
+    # @example
+    #   example.to_s
+    #
+    # @return [String] A string representation of this model
     def to_s
       text = ''
 
@@ -118,11 +169,30 @@ module CukeModeler
 
     # rubocop:enable Metrics/AbcSize
 
+    # See `Object#inspect`. Returns some basic information about the
+    # object, including its class, object ID, and its most meaningful
+    # attribute. For an Example model, this will be the name of the
+    # example. If *verbose* is true, provides default Ruby inspection
+    # behavior instead.
+    #
+    # @example
+    #   example.inspect
+    #   example.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 = "# language: #{Parsing.dialect}
       #{dialect_feature_keyword}: Fake feature to parse
                             #{dialect_outline_keyword}:
@@ -134,6 +204,22 @@ module CukeModeler
       parsed_file['feature']['elements'].first['examples'].first
     end
 
+    def populate_model(parsed_example_data)
+      populate_parsing_data(parsed_example_data)
+      populate_keyword(parsed_example_data)
+      populate_source_location(parsed_example_data)
+      populate_name(parsed_example_data)
+      populate_description(parsed_example_data)
+      populate_tags(parsed_example_data)
+      populate_example_rows(parsed_example_data)
+    end
+
+    def populate_example_rows(parsed_example_data)
+      parsed_example_data['rows'].each do |row_data|
+        @rows << build_child_model(Row, row_data)
+      end
+    end
+
     def determine_buffer_size(index)
       rows.collect { |row| row.cells[index].to_s.length }.max || 0
     end

data/lib/cuke_modeler/models/feature.rb

@@ -28,20 +28,28 @@ module CukeModeler
 
     # Creates a new Feature object and, if *source_text* is provided, populates the
     # object.
+    #
+    # @example
+    #   Feature.new
+    #   Feature.new("Feature:\nThis is a feature")
+    #
+    # @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 [Feature] A new Feature instance
     def initialize(source_text = nil)
       @tags = []
       @rules = []
       @tests = []
 
       super(source_text)
-
-      return unless source_text
-
-      parsed_feature_data = parse_source(source_text)
-      populate_feature(self, parsed_feature_data)
     end
 
     # Returns *true* if the feature contains a background, *false* otherwise.
+    #
+    # @example
+    #   feature.background?
+    #
+    # @return [Boolean] Whether the feature contains a background
     def background?
       !@background.nil?
     end
@@ -49,20 +57,37 @@ module CukeModeler
     alias has_background? background?
 
     # Returns the scenario models contained in the feature.
+    #
+    # @example
+    #   feature.scenarios
+    #
+    # @return [Array<Scenario>] Child Scenario models
     def scenarios
       @tests.select { |test| test.is_a? Scenario }
     end
 
     # Returns the outline models contained in the feature.
+    #
+    # @example
+    #   feature.outlines
+    #
+    # @return [Array<Outline>] Child Outline models
     def outlines
       @tests.select { |test| test.is_a? Outline }
     end
 
-    # TODO: Remove this method on next major version release
-    # DEPRECATED
+    # TODO: Remove this and other deprecated methods on next major version release
+
+    # @deprecated See CHANGELOG
+    #
     # Returns the number of test cases contained in the feature. A test case is a
     # single set of test values, such as an individual scenario or one example row
     # of an outline.
+    #
+    # @example
+    #   feature.test_case_count
+    #
+    # @return [Integer] The count of test cases
     def test_case_count
       scenarios.count + outlines.reduce(0) do |outline_sum, outline|
         outline_sum + outline.examples.reduce(0) do |example_sum, example|
@@ -71,7 +96,14 @@ module CukeModeler
       end
     end
 
-    # Returns the model objects that belong to this model.
+    # Returns the model objects that are children of this model. For a
+    # Feature model, these would be any associated Rule, Background,
+    # Scenario, Outline, or Tag models.
+    #
+    # @example
+    #   feature.children
+    #
+    # @return [Array<Rule, Background, Scenario, Outline, Tag>] A collection of child models
     def children
       models = rules + tests + tags
       models << background if background
@@ -82,8 +114,13 @@ module CukeModeler
     # Building strings just isn't pretty
     # rubocop:disable Metrics/AbcSize
 
-    # Returns a string representation of this model. For a feature model,
+    # Returns a string representation of this model. For a Feature model,
     # this will be Gherkin text that is equivalent to the feature being modeled.
+    #
+    # @example
+    #   feature.to_s
+    #
+    # @return [String] A string representation of this model
     def to_s
       text = ''
 
@@ -99,16 +136,50 @@ module CukeModeler
 
     # rubocop:enable Metrics/AbcSize
 
+    # See `Object#inspect`. Returns some basic information about the
+    # object, including its class, object ID, and its most meaningful
+    # attribute. For a Feature model, this will be the name of the
+    # feature. If *verbose* is true, provides default Ruby inspection
+    # behavior instead.
+    #
+    # @example
+    #   feature.inspect
+    #   feature.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)
       parsed_file = Parsing.parse_text(source_text, 'cuke_modeler_stand_alone_feature.feature')
 
       parsed_file['feature']
     end
 
+    def populate_model(parsed_feature_data)
+      populate_parsing_data(parsed_feature_data)
+      populate_source_location(parsed_feature_data)
+      populate_language(parsed_feature_data)
+      populate_keyword(parsed_feature_data)
+      populate_name(parsed_feature_data)
+      populate_description(parsed_feature_data)
+      populate_tags(parsed_feature_data)
+      populate_children(parsed_feature_data)
+    end
+
+    def populate_language(parsed_feature_data)
+      @language = parsed_feature_data['language']
+    end
+
     def background_output_string
       child_element_output_string(background)
     end

data/lib/cuke_modeler/models/feature_file.rb

@@ -18,45 +18,99 @@ module CukeModeler
 
     # Creates a new FeatureFile object and, if *file_path* is provided,
     # populates the object.
+    #
+    # @example
+    #   FeatureFile.new
+    #   FeatureFile.new('path/to/some.feature')
+    #
+    # @param file_path [String] The file path that will be used to populate the model
+    # @raise [ArgumentError] If *file_path* is not a String
+    # @raise [ArgumentError] If the file path does not exist
+    # @return [FeatureFile] A new FeatureFile instance
     def initialize(file_path = nil)
       @path = file_path
       @comments = []
 
       super(file_path)
-
-      return unless file_path
-      raise(ArgumentError, "Unknown file: #{file_path.inspect}") unless File.exist?(file_path)
-
-      processed_feature_file_data = process_feature_file(file_path)
-      populate_featurefile(self, processed_feature_file_data)
     end
 
     # Returns the name of the modeled feature file.
+    #
+    # @example
+    #   f = FeatureFile.new('path/to/some.feature')
+    #   f.name  #=> 'some.feature'
+    #
+    # @return [String] The name of the file
     def name
       File.basename(@path.gsub('\\', '/')) if @path
     end
 
-    # Returns the model objects that belong to this model.
+    # Returns the model objects that are children of this model. For a
+    # FeatureFile model, this would be any associated Feature model.
+    #
+    # @example
+    #   feature_file.children
+    #
+    # @return [Array<Feature>] A collection of child models
     def children
       @feature ? [@feature] : []
     end
 
-    # Returns a string representation of this model. For a feature file
+    # Returns a string representation of this model. For a FeatureFile
     # model, this will be the path of the modeled feature file.
+    #
+    # @example
+    #   feature_file.to_s #=> 'path/to/some.feature'
+    #
+    # @return [String] A string representation of this model
     def to_s
       path.to_s
     end
 
+    # See `Object#inspect`. Returns some basic information about the
+    # object, including its class, object ID, and its most meaningful
+    # attribute. For a FeatureFile model, this will be the path of
+    # the feature file. If *verbose* is true, provides default Ruby
+    # inspection behavior instead.
+    #
+    # @example
+    #   feature_file.inspect
+    #   feature_file.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} @path: #{@path.inspect}>"
+    end
+
 
     private
 
 
-    def process_feature_file(file_path)
-      source_text = File.read(file_path)
+    def process_source(file_path)
+      raise(ArgumentError, "Unknown file: #{file_path.inspect}") unless File.exist?(file_path)
+
+      source_text       = File.read(file_path)
       feature_file_data = Parsing.parse_text(source_text, file_path)
 
       feature_file_data.merge({ 'path' => file_path })
     end
 
+    def populate_model(processed_feature_file_data)
+      populate_parsing_data(processed_feature_file_data)
+      @path = processed_feature_file_data['path']
+
+      if processed_feature_file_data['feature']
+        @feature = build_child_model(Feature, processed_feature_file_data['feature'])
+      end
+
+      processed_feature_file_data['comments'].each do |comment_data|
+        @comments << build_child_model(Comment, comment_data)
+      end
+    end
+
   end
 end