openstax_kitchen 2.0.0 → 3.0.0

data/lib/kitchen/element_enumerator.rb

@@ -1,6 +1,14 @@
+# frozen_string_literal: true
+
 module Kitchen
+  # An enumerator for any old non-specific element
+  #
   class ElementEnumerator < ElementEnumeratorBase
 
+    # Returns a factory for this enumerator
+    #
+    # @return [ElementEnumeratorFactory]
+    #
     def self.factory
       ElementEnumeratorFactory.new(
         sub_element_class: Element,

data/lib/kitchen/element_enumerator_base.rb

@@ -1,56 +1,227 @@
+# frozen_string_literal: true
+
 module Kitchen
+  # Base class for all element enumerators
+  #
   class ElementEnumeratorBase < Enumerator
+    include Mixins::BlockErrorIf
 
-    def initialize(size=nil, css_or_xpath: nil, upstream_enumerator: nil)
-      @css_or_xpath = css_or_xpath
+    # Return the selectors or other search strings that this enumerator uses to
+    # search through the document
+    #
+    # @return [String]
+    #
+    attr_reader :search_query
+
+    # Creates a new instance
+    #
+    # @param size [Integer, Proc] How to calculate the size lazily, either a value
+    #   or a callable object
+    # @param search_query [String] the selectors or other search strings that this
+    #   enumerator uses to search through the document
+    # @param upstream_enumerator [ElementEnumeratorBase] the enumerator to which this
+    #   enumerator is chained, used to access the upstream search history
+    #
+    def initialize(size=nil, search_query: nil, upstream_enumerator: nil)
+      @search_query = search_query
       @upstream_enumerator = upstream_enumerator
       super(size)
     end
 
+    # Return the search history based on this enumerator and any upstream enumerators
+    #
+    # @return [SearchHistory]
+    #
     def search_history
-      (@upstream_enumerator&.search_history || SearchHistory.empty).add(@css_or_xpath)
+      (@upstream_enumerator&.search_history || SearchHistory.empty).add(@search_query)
+    end
+
+    # Returns an enumerator that iterates through terms within the scope of this enumerator
+    #
+    # @param css_or_xpath [String] additional selectors to further narrow the element iterated over;
+    #   a "$" in this argument will be replaced with the default selector for the element being
+    #   iterated over.
+    # @param only [Symbol, Callable] the name of a method to call on an element or a
+    #   lambda or proc that accepts an element; elements will only be included in the
+    #   search results if the method or callable returns true
+    # @param except [Symbol, Callable] the name of a method to call on an element or a
+    #   lambda or proc that accepts an element; elements will not be included in the
+    #   search results if the method or callable returns false
+    #
+    def terms(css_or_xpath=nil, only: nil, except: nil)
+      block_error_if(block_given?)
+      chain_to(TermElementEnumerator, css_or_xpath: css_or_xpath, only: only, except: except)
     end
 
-    def terms(css_or_xpath=nil, &block)
-      chain_to(TermElementEnumerator, css_or_xpath: css_or_xpath, &block)
+    # Returns an enumerator that iterates through pages within the scope of this enumerator
+    #
+    # @param css_or_xpath [String] additional selectors to further narrow the element iterated over;
+    #   a "$" in this argument will be replaced with the default selector for the element being
+    #   iterated over.
+    # @param only [Symbol, Callable] the name of a method to call on an element or a
+    #   lambda or proc that accepts an element; elements will only be included in the
+    #   search results if the method or callable returns true
+    # @param except [Symbol, Callable] the name of a method to call on an element or a
+    #   lambda or proc that accepts an element; elements will not be included in the
+    #   search results if the method or callable returns false
+    #
+    def pages(css_or_xpath=nil, only: nil, except: nil)
+      block_error_if(block_given?)
+      chain_to(PageElementEnumerator, css_or_xpath: css_or_xpath, only: only, except: except)
     end
 
-    def pages(css_or_xpath=nil, &block)
-      chain_to(PageElementEnumerator, css_or_xpath: css_or_xpath, &block)
+    # Returns an enumerator that iterates through chapters within the scope of this enumerator
+    #
+    # @param css_or_xpath [String] additional selectors to further narrow the element iterated over;
+    #   a "$" in this argument will be replaced with the default selector for the element being
+    #   iterated over.
+    # @param only [Symbol, Callable] the name of a method to call on an element or a
+    #   lambda or proc that accepts an element; elements will only be included in the
+    #   search results if the method or callable returns true
+    # @param except [Symbol, Callable] the name of a method to call on an element or a
+    #   lambda or proc that accepts an element; elements will not be included in the
+    #   search results if the method or callable returns false
+    #
+    def chapters(css_or_xpath=nil, only: nil, except: nil)
+      block_error_if(block_given?)
+      chain_to(ChapterElementEnumerator, css_or_xpath: css_or_xpath, only: only, except: except)
     end
 
-    def chapters(css_or_xpath=nil, &block)
-      chain_to(ChapterElementEnumerator, css_or_xpath: css_or_xpath, &block)
+    # Returns an enumerator that iterates through units within the scope of this enumerator
+    #
+    # @param css_or_xpath [String] additional selectors to further narrow the element iterated over;
+    #   a "$" in this argument will be replaced with the default selector for the element being
+    #   iterated over.
+    #
+    def units(css_or_xpath=nil, only: nil, except: nil)
+      block_error_if(block_given?)
+      chain_to(UnitElementEnumerator, css_or_xpath: css_or_xpath, only: only, except: except)
     end
 
-    # use block_error_if
-    def figures(css_or_xpath=nil, &block)
-      chain_to(FigureElementEnumerator, css_or_xpath: css_or_xpath, &block)
+    # Returns an enumerator that iterates through figures within the scope of this enumerator
+    #
+    # @param css_or_xpath [String] additional selectors to further narrow the element iterated over;
+    #   a "$" in this argument will be replaced with the default selector for the element being
+    #   iterated over.
+    # @param only [Symbol, Callable] the name of a method to call on an element or a
+    #   lambda or proc that accepts an element; elements will only be included in the
+    #   search results if the method or callable returns true
+    # @param except [Symbol, Callable] the name of a method to call on an element or a
+    #   lambda or proc that accepts an element; elements will not be included in the
+    #   search results if the method or callable returns false
+    #
+    def figures(css_or_xpath=nil, only: nil, except: nil)
+      block_error_if(block_given?)
+      chain_to(FigureElementEnumerator, css_or_xpath: css_or_xpath, only: only, except: except)
     end
 
-    def notes(css_or_xpath=nil, &block)
-      chain_to(NoteElementEnumerator, css_or_xpath: css_or_xpath, &block)
+    # Returns an enumerator that iterates through notes within the scope of this enumerator
+    #
+    # @param css_or_xpath [String] additional selectors to further narrow the element iterated over;
+    #   a "$" in this argument will be replaced with the default selector for the element being
+    #   iterated over.
+    # @param only [Symbol, Callable] the name of a method to call on an element or a
+    #   lambda or proc that accepts an element; elements will only be included in the
+    #   search results if the method or callable returns true
+    # @param except [Symbol, Callable] the name of a method to call on an element or a
+    #   lambda or proc that accepts an element; elements will not be included in the
+    #   search results if the method or callable returns false
+    #
+    def notes(css_or_xpath=nil, only: nil, except: nil)
+      block_error_if(block_given?)
+      chain_to(NoteElementEnumerator, css_or_xpath: css_or_xpath, only: only, except: except)
     end
 
-    def tables(css_or_xpath=nil, &block)
-      chain_to(TableElementEnumerator, css_or_xpath: css_or_xpath, &block)
+    # Returns an enumerator that iterates through tables within the scope of this enumerator
+    #
+    # @param css_or_xpath [String] additional selectors to further narrow the element iterated over;
+    #   a "$" in this argument will be replaced with the default selector for the element being
+    #   iterated over.
+    # @param only [Symbol, Callable] the name of a method to call on an element or a
+    #   lambda or proc that accepts an element; elements will only be included in the
+    #   search results if the method or callable returns true
+    # @param except [Symbol, Callable] the name of a method to call on an element or a
+    #   lambda or proc that accepts an element; elements will not be included in the
+    #   search results if the method or callable returns false
+    #
+    def tables(css_or_xpath=nil, only: nil, except: nil)
+      block_error_if(block_given?)
+      chain_to(TableElementEnumerator, css_or_xpath: css_or_xpath, only: only, except: except)
     end
 
-    def examples(css_or_xpath=nil, &block)
-      chain_to(ExampleElementEnumerator, css_or_xpath: css_or_xpath, &block)
+    # Returns an enumerator that iterates through examples within the scope of this enumerator
+    #
+    # @param css_or_xpath [String] additional selectors to further narrow the element iterated over;
+    #   a "$" in this argument will be replaced with the default selector for the element being
+    #   iterated over.
+    # @param only [Symbol, Callable] the name of a method to call on an element or a
+    #   lambda or proc that accepts an element; elements will only be included in the
+    #   search results if the method or callable returns true
+    # @param except [Symbol, Callable] the name of a method to call on an element or a
+    #   lambda or proc that accepts an element; elements will not be included in the
+    #   search results if the method or callable returns false
+    #
+    def examples(css_or_xpath=nil, only: nil, except: nil)
+      block_error_if(block_given?)
+      chain_to(ExampleElementEnumerator, css_or_xpath: css_or_xpath, only: only, except: except)
     end
 
-    def search(css_or_xpath=nil, &block)
-      chain_to(ElementEnumerator, css_or_xpath: css_or_xpath, &block)
+    # Returns an enumerator that iterates through metadata within the scope of this enumerator
+    #
+    # @param css_or_xpath [String] additional selectors to further narrow the element iterated over;
+    #   a "$" in this argument will be replaced with the default selector for the element being
+    #   iterated over.
+    # @param only [Symbol, Callable] the name of a method to call on an element or a
+    #   lambda or proc that accepts an element; elements will only be included in the
+    #   search results if the method or callable returns true
+    # @param except [Symbol, Callable] the name of a method to call on an element or a
+    #   lambda or proc that accepts an element; elements will not be included in the
+    #   search results if the method or callable returns false
+    #
+    def metadatas(css_or_xpath=nil, only: nil, except: nil)
+      block_error_if(block_given?)
+      chain_to(MetadataElementEnumerator, css_or_xpath: css_or_xpath, only: only, except: except)
     end
 
-    def chain_to(enumerator_class, css_or_xpath: nil, &block)
-      raise(RecipeError, "Did you forget a `.each` call on this enumerator?") if block_given?
+    # Returns an enumerator that iterates within the scope of this enumerator
+    #
+    # @param css_or_xpath [String] additional selectors to further narrow the element iterated over
+    #
+    def search(css_or_xpath=nil, only: nil, except: nil)
+      block_error_if(block_given?)
+      chain_to(ElementEnumerator, css_or_xpath: css_or_xpath, only: only, except: except)
+    end
 
-      enumerator_class.factory.build_within(self, css_or_xpath: css_or_xpath)
+    # Returns an enumerator that iterates through elements within the scope of this enumerator
+    #
+    # @param enumerator_class [ElementEnumeratorBase] the enumerator to use for the iteration
+    # @param css_or_xpath [String] additional selectors to further narrow the element iterated over
+    # @param only [Symbol, Callable] the name of a method to call on an element or a
+    #   lambda or proc that accepts an element; elements will only be included in the
+    #   search results if the method or callable returns true
+    # @param except [Symbol, Callable] the name of a method to call on an element or a
+    #   lambda or proc that accepts an element; elements will not be included in the
+    #   search results if the method or callable returns false
+    #
+    def chain_to(enumerator_class, css_or_xpath: nil, only: nil, except: nil)
+      block_error_if(block_given?)
+      enumerator_class.factory.build_within(
+        self,
+        search_query: SearchQuery.new(
+          css_or_xpath: css_or_xpath,
+          only: only,
+          except: except
+        )
+      )
     end
 
-    def first!(missing_message: "Could not return a first result")
+    # Returns the first element in this enumerator
+    #
+    # @param missing_message [String] the message to raise if a first element isn't available
+    # @raise [RecipeError] if a first element isn't available
+    # @return [Element]
+    #
+    def first!(missing_message: 'Could not return a first result')
       first || raise(RecipeError, "#{missing_message} matching #{search_history.latest} " \
                                   "inside [#{search_history.upstream}]")
     end
@@ -64,7 +235,7 @@ module Kitchen
     #
     def cut(to: nil)
       to ||= Clipboard.new
-      self.each do |element|
+      each do |element|
         element.cut(to: to)
       end
       to
@@ -79,22 +250,33 @@ module Kitchen
     #
     def copy(to: nil)
       to ||= Clipboard.new
-      self.each do |element|
+      each do |element|
         element.copy(to: to)
       end
       to
     end
 
+    # Removes all matching elements from the document
+    #
     def trash
-      self.each(&:trash)
+      each(&:trash)
     end
 
+    # Returns the element at the provided index
+    #
+    # @param index [Integer]
+    # @return [Element]
+    #
     def [](index)
       to_a[index]
     end
 
+    # Returns a concatenation of +to_s+ for all elements in the enumerator
+    #
+    # @return [String]
+    #
     def to_s
-      self.map(&:to_s).join("")
+      map(&:to_s).join('')
     end
 
   end

data/lib/kitchen/element_enumerator_factory.rb

@@ -1,4 +1,8 @@
+# frozen_string_literal: true
+
 module Kitchen
+  # Builds specific subclasses of ElementEnumeratorBase
+  #
   class ElementEnumeratorFactory
 
     attr_reader :default_css_or_xpath
@@ -6,35 +10,52 @@ module Kitchen
     attr_reader :sub_element_class
     attr_reader :detect_sub_element_class
 
-    def initialize(default_css_or_xpath: nil, sub_element_class: nil,
-                   enumerator_class:, detect_sub_element_class: false)
+    # Creates a new instance
+    #
+    # @param default_css_or_xpath [String] The selectors to substitute for the "$" character
+    #   when this factory is used to build an enumerator.
+    # @param sub_element_class [ElementBase] The element class to use for what the enumerator finds.
+    # @param enumerator_class [ElementEnumeratorBase] The enumerator class to return
+    # @param detect_sub_element_class [Boolean] If true, infers the sub_element_class from the node
+    #
+    def initialize(enumerator_class:, default_css_or_xpath: nil, sub_element_class: nil,
+                   detect_sub_element_class: false)
       @default_css_or_xpath = default_css_or_xpath
       @sub_element_class = sub_element_class
       @enumerator_class = enumerator_class
       @detect_sub_element_class = detect_sub_element_class
     end
 
-    # TODO spec this!
-    def apply_default_css_or_xpath_and_normalize(css_or_xpath=nil)
-      css_or_xpath ||= "$"
-      [css_or_xpath].flatten.each {|item| item.gsub!(/\$/, [default_css_or_xpath].flatten.join(", ")) }
-      [css_or_xpath].flatten
-    end
-
-    def build_within(enumerator_or_element, css_or_xpath: nil)
-      css_or_xpath = apply_default_css_or_xpath_and_normalize(css_or_xpath)
+    # Builds a new enumerator within the scope of the provided argument (either
+    # an enumerator or a class).  Accepts optional selectors to further limit
+    # the scope of results found.
+    #
+    # @param enumerator_or_element [ElementEnumeratorBase, ElementBase] the object
+    #   within which to iterate
+    # @param search_query [SearchQuery] search directives to limit iteration results
+    # @return [ElementEnumeratorBase] actually returns the concrete enumerator class
+    #   given to the factory in its constructor.
+    #
+    def build_within(enumerator_or_element, search_query: SearchQuery.new)
+      search_query.apply_default_css_or_xpath_and_normalize(default_css_or_xpath)
 
       case enumerator_or_element
       when ElementBase
-        build_within_element(enumerator_or_element, css_or_xpath: css_or_xpath)
+        build_within_element(enumerator_or_element, search_query: search_query)
       when ElementEnumeratorBase
-        build_within_other_enumerator(enumerator_or_element, css_or_xpath: css_or_xpath)
+        build_within_other_enumerator(enumerator_or_element, search_query: search_query)
       end
     end
 
+    # Builds a new enumerator that finds elements matching either this factory's or the provided
+    # factory's selectors.
+    #
+    # @param other_factory [ElementEnumeratorFactory]
+    # @return [ElementEnumeratorFactory]
+    #
     def or_with(other_factory)
       self.class.new(
-        default_css_or_xpath: default_css_or_xpath + ", " + other_factory.default_css_or_xpath,
+        default_css_or_xpath: "#{default_css_or_xpath}, #{other_factory.default_css_or_xpath}",
         enumerator_class: TypeCastingElementEnumerator,
         detect_sub_element_class: true
       )
@@ -42,65 +63,51 @@ module Kitchen
 
     protected
 
-    def build_within_element(element, css_or_xpath:)
-      enumerator_class.new(css_or_xpath: css_or_xpath) do |block|
+    def build_within_element(element, search_query:)
+      enumerator_class.new(search_query: search_query) do |block|
         grand_ancestors = element.ancestors
         parent_ancestor = Ancestor.new(element)
 
-        num_sub_elements = 0
+        # If the provided `search_query` has already been iterated through on this element,
+        # we need to undo any counting on the ancestors so that when they are counted again
+        # below, the counts are correct.
+        element.uncount(search_query)
 
-        element.raw.search(*css_or_xpath).each_with_index do |sub_node, index|
+        element.raw.search(*search_query.css_or_xpath).each do |sub_node|
           sub_element = ElementFactory.build_from_node(
-                          node: sub_node,
-                          document: element.document,
-                          element_class: sub_element_class,
-                          default_short_type: Utils.search_path_to_type(css_or_xpath),
-                          detect_element_class: detect_sub_element_class
-                        )
-
-          # If the provided `css_or_xpath` has already been counted, we need to uncount
-          # them on the ancestors so that when they are counted again below, the counts
-          # are correct.  Only do this on the first loop!
-          if index == 0
-            if element.have_sub_elements_already_been_counted?(css_or_xpath)
-              grand_ancestors.values.each do |ancestor|
-                ancestor.decrement_descendant_count(
-                  sub_element.short_type,
-                  by: element.number_of_sub_elements_already_counted(css_or_xpath)
-                )
-              end
-            end
-          end
+            node: sub_node,
+            document: element.document,
+            element_class: sub_element_class,
+            default_short_type: search_query.as_type,
+            detect_element_class: detect_sub_element_class
+          )
+
+          next unless search_query.conditions_match?(sub_element)
 
           # Record this sub element's ancestors and increment their descendant counts
           sub_element.add_ancestors(grand_ancestors, parent_ancestor)
-          sub_element.count_as_descendant
 
-          # Remember how this sub element was found so can trace search history given
-          # any element.
-          sub_element.css_or_xpath_that_found_me = css_or_xpath
+          # Remember that we counted this sub element in case we need to later reset the counts
+          element.remember_that_a_sub_element_was_counted(search_query, sub_element.short_type)
 
-          # Count runs through this loop for below
-          num_sub_elements += 1
+          # Remember how this sub element was found so can trace search history given any element.
+          sub_element.search_query_that_found_me = search_query
 
           # Mark the location so that if there's an error we can show the developer where.
-          sub_element.document.location = sub_element
+          sub_element.mark_as_current_location!
 
           block.yield(sub_element)
         end
-
-        element.remember_that_sub_elements_are_already_counted(
-          css_or_xpath: css_or_xpath, count: num_sub_elements
-        )
       end
     end
 
-    def build_within_other_enumerator(other_enumerator, css_or_xpath:)
+    def build_within_other_enumerator(other_enumerator, search_query:)
       # Return a new enumerator instance that internally iterates over `other_enumerator`
       # running a new enumerator for each element returned by that other enumerator.
-      enumerator_class.new(css_or_xpath: css_or_xpath, upstream_enumerator: other_enumerator) do |block|
+      enumerator_class.new(search_query: search_query,
+                           upstream_enumerator: other_enumerator) do |block|
         other_enumerator.each do |element|
-          build_within_element(element, css_or_xpath: css_or_xpath).each do |sub_element|
+          build_within_element(element, search_query: search_query).each do |sub_element|
             block.yield(sub_element)
           end
         end