openstax_kitchen 3.0.0 → 4.1.1

data/lib/kitchen/element_enumerator_base.rb

@@ -70,6 +70,60 @@ module Kitchen
       chain_to(PageElementEnumerator, css_or_xpath: css_or_xpath, only: only, except: except)
     end
 
+    # Returns an enumerator that iterates through composite 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 composite_pages(css_or_xpath=nil, only: nil, except: nil)
+      block_error_if(block_given?)
+      chain_to(CompositePageElementEnumerator,
+               css_or_xpath: css_or_xpath,
+               only: only,
+               except: except)
+    end
+
+    # Returns an enumerator that iterates through composite 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 composite_chapters(css_or_xpath=nil, only: nil, except: nil)
+      block_error_if(block_given?)
+      chain_to(CompositeChapterElementEnumerator,
+               css_or_xpath: css_or_xpath,
+               only: only,
+               except: except)
+    end
+
+    # Returns an enumerator that iterates through pages that arent the introduction page 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 non_introduction_pages(only: nil, except: nil)
+      block_error_if(block_given?)
+      chain_to(PageElementEnumerator,
+               css_or_xpath: '$:not(.introduction)',
+               only: only,
+               except: except)
+    end
+
     # 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;
@@ -166,6 +220,52 @@ module Kitchen
       chain_to(ExampleElementEnumerator, css_or_xpath: css_or_xpath, only: only, except: except)
     end
 
+    # Returns an enumerator that iterates through titles 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 titles(css_or_xpath=nil, only: nil, except: nil)
+      block_error_if(block_given?)
+      chain_to(ElementEnumerator,
+               default_css_or_xpath: '[data-type="title"]',
+               css_or_xpath: css_or_xpath,
+               only: only,
+               except: except)
+    end
+
+    # Returns an enumerator that iterates through references 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 references(css_or_xpath=nil)
+      block_error_if(block_given?)
+      chain_to(ReferenceElementEnumerator, css_or_xpath: css_or_xpath)
+    end
+
+    # Returns an enumerator that iterates through exercises within the scope of this enumerator
+    #
+    # @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 exercises(css_or_xpath=nil, only: nil, except: nil)
+      block_error_if(block_given?)
+      chain_to(ExerciseElementEnumerator, css_or_xpath: css_or_xpath, only: only, except: except)
+    end
+
     # 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;
@@ -195,7 +295,12 @@ module Kitchen
     # 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 default_css_or_xpath [String] the default CSS or xpath to use when iterating.  Normally,
+    #   this value is provided by the `enumerator_class`, but that isn't always the case, e.g.
+    #   when that class is a generic `ElementEnumerator`.
     # @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
@@ -203,16 +308,21 @@ module Kitchen
     #   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)
+    def chain_to(enumerator_class, default_css_or_xpath: nil, 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
-        )
+
+      search_query = SearchQuery.new(
+        css_or_xpath: css_or_xpath,
+        only: only,
+        except: except
       )
+
+      if default_css_or_xpath
+        search_query.apply_default_css_or_xpath_and_normalize(default_css_or_xpath)
+      end
+
+      enumerator_class.factory.build_within(self, search_query: search_query)
     end
 
     # Returns the first element in this enumerator

data/lib/kitchen/element_enumerator_factory.rb

@@ -12,8 +12,11 @@ module Kitchen
 
     # 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 default_css_or_xpath [String, Proc, Symbol] The selectors to substitute for the "$" character
+    #   when this factory is used to build an enumerator.  A string argument is used literally.  A proc
+    #   is eventually called given the document's Config object (for accessing selectors).  A symbol
+    #   is interpreted as the name of a selector and is called on the document's Config object's
+    #   selectors object.  The easiest way to get a Proc is to pass `Selector.named(:name_of_selector)`
     # @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
@@ -36,14 +39,22 @@ module Kitchen
     # @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)
-
+    def build_within(enumerator_or_element, search_query: SearchQuery.new, reload: false)
       case enumerator_or_element
       when ElementBase
-        build_within_element(enumerator_or_element, search_query: search_query)
+        build_within_element(enumerator_or_element,
+                             search_query: search_query,
+                             reload: reload)
       when ElementEnumeratorBase
-        build_within_other_enumerator(enumerator_or_element, search_query: search_query)
+        if enumerator_class != ElementEnumerator && !search_query.expects_substitution?
+          raise "Query #{search_query} is missing the substitution character ('$') but " \
+                "is run with an enumerator #{enumerator_class.name} that has its own " \
+                "selectors for substitution."
+        end
+
+        build_within_other_enumerator(enumerator_or_element,
+                                      search_query: search_query,
+                                      reload: reload)
       end
     end
 
@@ -55,7 +66,7 @@ module Kitchen
     #
     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
       )
@@ -63,7 +74,10 @@ module Kitchen
 
     protected
 
-    def build_within_element(element, search_query:)
+    def build_within_element(element, search_query:, reload:)
+      search_query.apply_default_css_or_xpath_and_normalize(default_css_or_xpath,
+                                                            config: element.config)
+
       enumerator_class.new(search_query: search_query) do |block|
         grand_ancestors = element.ancestors
         parent_ancestor = Ancestor.new(element)
@@ -73,7 +87,7 @@ module Kitchen
         # below, the counts are correct.
         element.uncount(search_query)
 
-        element.raw.search(*search_query.css_or_xpath).each do |sub_node|
+        element.raw_search(*search_query.css_or_xpath, reload: reload).each do |sub_node|
           sub_element = ElementFactory.build_from_node(
             node: sub_node,
             document: element.document,
@@ -101,13 +115,15 @@ module Kitchen
       end
     end
 
-    def build_within_other_enumerator(other_enumerator, search_query:)
+    def build_within_other_enumerator(other_enumerator, search_query:, reload:)
       # 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(search_query: search_query,
                            upstream_enumerator: other_enumerator) do |block|
         other_enumerator.each do |element|
-          build_within_element(element, search_query: search_query).each do |sub_element|
+          build_within_element(element,
+                               search_query: search_query,
+                               reload: reload).each do |sub_element|
             block.yield(sub_element)
           end
         end

data/lib/kitchen/element_factory.rb

@@ -25,7 +25,7 @@ module Kitchen
                              element_class: nil,
                              default_short_type: nil,
                              detect_element_class: false)
-      element_class ||= detect_element_class ? specific_element_class_for_node(node) : Element
+      element_class ||= detect_element_class ? find_element_class(node, document.config) : Element
 
       if element_class == Element
         element_class.new(node: node,
@@ -37,9 +37,9 @@ module Kitchen
       end
     end
 
-    def self.specific_element_class_for_node(node)
+    def self.find_element_class(node, config)
       ELEMENT_CLASSES.find do |klass|
-        klass.is_the_element_class_for?(node)
+        klass.is_the_element_class_for?(node, config: config)
       end || Element
     end
 

data/lib/kitchen/example_element.rb

@@ -13,8 +13,14 @@ module Kitchen
     def initialize(node:, document: nil)
       super(node: node,
             document: document,
-            enumerator_class: ExampleElementEnumerator,
-            short_type: :example)
+            enumerator_class: ExampleElementEnumerator)
+    end
+
+    # Returns the short type
+    # @return [Symbol]
+    #
+    def self.short_type
+      :example
     end
 
     # Returns the an enumerator for titles.
@@ -25,14 +31,5 @@ module Kitchen
       search("span[data-type='title']")
     end
 
-    # Returns true if this class represents the element for the given node
-    #
-    # @param node [Nokogiri::XML::Node] the underlying node
-    # @return [Boolean]
-    #
-    def self.is_the_element_class_for?(node)
-      node['data-type'] == 'example'
-    end
-
   end
 end

data/lib/kitchen/example_element_enumerator.rb

@@ -11,7 +11,7 @@ module Kitchen
     #
     def self.factory
       ElementEnumeratorFactory.new(
-        default_css_or_xpath: "div[data-type='example']", # TODO: element.document.selectors.example
+        default_css_or_xpath: Selector.named(:example),
         sub_element_class: ExampleElement,
         enumerator_class: self
       )

data/lib/kitchen/exercise_element.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Kitchen
+  # An element for an example
+  #
+  class ExerciseElement < ElementBase
+
+    # Creates a new +ExerciseElement+
+    #
+    # @param node [Nokogiri::XML::Node] the node this element wraps
+    # @param document [Document] this element's document
+    #
+    def initialize(node:, document: nil)
+      super(node: node,
+            document: document,
+            enumerator_class: ExerciseElementEnumerator)
+    end
+
+    # Returns the short type
+    # @return [Symbol]
+    #
+    def self.short_type
+      :exercise
+    end
+
+    # Returns the enumerator for problem.
+    #
+    # @return ElementEnumerator
+    #
+    def problem
+      first("div[data-type='problem']")
+    end
+
+    # Returns the enumerator for solution.
+    #
+    # @return ElementEnumerator
+    #
+    def solution
+      first("div[data-type='solution']")
+    end
+  end
+end

data/lib/kitchen/exercise_element_enumerator.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Kitchen
+  # An enumerator for example elements
+  #
+  class ExerciseElementEnumerator < ElementEnumeratorBase
+
+    # Returns a factory for this enumerator
+    #
+    # @return [ElementEnumeratorFactory]
+    #
+    def self.factory
+      ElementEnumeratorFactory.new(
+        default_css_or_xpath: Selector.named(:exercise),
+        sub_element_class: ExerciseElement,
+        enumerator_class: self
+      )
+    end
+
+  end
+end

data/lib/kitchen/figure_element.rb

@@ -13,8 +13,14 @@ module Kitchen
     def initialize(node:, document: nil)
       super(node: node,
             document: document,
-            enumerator_class: FigureElementEnumerator,
-            short_type: :figure)
+            enumerator_class: FigureElementEnumerator)
+    end
+
+    # Returns the short type
+    # @return [Symbol]
+    #
+    def self.short_type
+      :figure
     end
 
     # Returns the caption element
@@ -41,14 +47,5 @@ module Kitchen
       parent.name == 'figure'
     end
 
-    # Returns true if this class represents the element for the given node
-    #
-    # @param node [Nokogiri::XML::Node] the underlying node
-    # @return [Boolean]
-    #
-    def self.is_the_element_class_for?(node)
-      node.name == 'figure'
-    end
-
   end
 end

data/lib/kitchen/figure_element_enumerator.rb

@@ -11,7 +11,7 @@ module Kitchen
     #
     def self.factory
       ElementEnumeratorFactory.new(
-        default_css_or_xpath: 'figure', # TODO: get from config?
+        default_css_or_xpath: Selector.named(:figure),
         sub_element_class: FigureElement,
         enumerator_class: self
       )

data/lib/kitchen/metadata_element.rb

@@ -12,8 +12,14 @@ module Kitchen
     def initialize(node:, document: nil)
       super(node: node,
             document: document,
-            enumerator_class: MetadataElementEnumerator,
-            short_type: :metadata)
+            enumerator_class: MetadataElementEnumerator)
+    end
+
+    # Returns the short type
+    # @return [Symbol]
+    #
+    def self.short_type
+      :metadata
     end
 
     # Returns set of selected data elements

data/lib/kitchen/metadata_element_enumerator.rb

@@ -11,7 +11,7 @@ module Kitchen
     #
     def self.factory
       ElementEnumeratorFactory.new(
-        default_css_or_xpath: "div[data-type='metadata']",
+        default_css_or_xpath: Selector.named(:metadata),
         sub_element_class: MetadataElement,
         enumerator_class: self
       )

data/lib/kitchen/note_element.rb

@@ -5,13 +5,6 @@ module Kitchen
   #
   class NoteElement < ElementBase
 
-    TITLE_TRANSLATION_KEYS = %w[
-      link-to-learning
-      everyday-life
-      sciences-interconnect
-      chemist-portrait
-    ].freeze
-
     # Creates a new +NoteElement+
     #
     # @param node [Nokogiri::XML::Node] the node this element wraps
@@ -20,8 +13,14 @@ module Kitchen
     def initialize(node:, document: nil)
       super(node: node,
             document: document,
-            enumerator_class: NoteElementEnumerator,
-            short_type: :note)
+            enumerator_class: NoteElementEnumerator)
+    end
+
+    # Returns the short type
+    # @return [Symbol]
+    #
+    def self.short_type
+      :note
     end
 
     # Returns the note's title element
@@ -38,7 +37,7 @@ module Kitchen
     # @return [Boolean]
     #
     def indicates_autogenerated_title?
-      translation_key_in(TITLE_TRANSLATION_KEYS).present?
+      detected_note_title_key != 0 && detected_note_title_key.present?
     end
 
     # Get the autogenerated title for this note
@@ -46,28 +45,27 @@ module Kitchen
     # @return [String]
     #
     def autogenerated_title
-      translation_key = translation_key_in(TITLE_TRANSLATION_KEYS)
-      I18n.t(:"notes.#{document.short_name}.#{translation_key}",
-             default: :"notes.#{translation_key}")
-    end
-
-    # Returns true if this class represents the element for the given node
-    #
-    # @param node [Nokogiri::XML::Node] the underlying node
-    # @return [Boolean]
-    #
-    def self.is_the_element_class_for?(node)
-      node['data-type'] == 'note'
+      if indicates_autogenerated_title?
+        I18n.t(:"notes.#{detected_note_title_key}")
+      else
+        "unknown title for note with classes #{classes}"
+      end
     end
 
     protected
 
-    def translation_key_in(possible_translation_keys)
-      keys = possible_translation_keys & classes
-      raise("too many translation keys: #{keys.join(', ')}") if keys.many?
+    def detected_note_title_key
+      @detected_note_title_key ||= begin
+        return 0 if classes.empty? || !I18n.t('.').key?(:notes)
 
-      keys.first
-    end
+        possible_keys = I18n.t(:notes).keys.map(&:to_s)
+        keys = possible_keys & classes
+
+        raise("too many translation keys: #{keys.join(', ')}") if keys.many?
+        return 0 if keys.empty?
 
+        keys.first
+      end
+    end
   end
 end