openstax_kitchen 3.1.0 → 5.0.0

data/lib/kitchen/element_enumerator_base.rb

@@ -84,7 +84,30 @@ module Kitchen
     #
     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)
+      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
@@ -218,11 +241,19 @@ module Kitchen
                except: except)
     end
 
-    # Returns an enumerator that iterates through exercises within the scope of this enumerator
+    # 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

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

@@ -13,17 +13,14 @@ module Kitchen
     def initialize(node:, document: nil)
       super(node: node,
             document: document,
-            enumerator_class: ExerciseElementEnumerator,
-            short_type: :exercise)
+            enumerator_class: ExerciseElementEnumerator)
     end
 
-    # Returns true if this class represents the element for the given node
+    # Returns the short type
+    # @return [Symbol]
     #
-    # @param node [Nokogiri::XML::Node] the underlying node
-    # @return [Boolean]
-    #
-    def self.is_the_element_class_for?(node)
-      node['data-type'] == 'exercise'
+    def self.short_type
+      :exercise
     end
 
     # Returns the enumerator for problem.
@@ -31,7 +28,7 @@ module Kitchen
     # @return ElementEnumerator
     #
     def problem
-      first("[data-type='problem']")
+      first("div[data-type='problem']")
     end
 
     # Returns the enumerator for solution.
@@ -39,7 +36,7 @@ module Kitchen
     # @return ElementEnumerator
     #
     def solution
-      first("[data-type='solution']")
+      first("div[data-type='solution']")
     end
   end
 end

data/lib/kitchen/exercise_element_enumerator.rb

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

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/id_tracker.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Kitchen
+  # A class to track and modify duplicate IDs in a document
+  #
+  class IdTracker
+
+    def initialize
+      @id_data = Hash.new { |hash, key| hash[key] = { count: 0, last_pasted: false } }
+      @id_copy_suffix = '_copy_'
+    end
+
+    # Keeps track that an element with the given ID has been copied.  When such
+    # elements are pasted, this information is used to give those elements unique
+    # IDs that don't duplicate the original element.
+    #
+    # @param id [String] the ID
+    #
+    def record_id_copied(id)
+      return if id.blank?
+
+      @id_data[id][:count] += 1
+      @id_data[id][:last_pasted] = false
+    end
+
+    # Keeps track that an element with the given ID has been cut.
+    #
+    # @param id [String]
+    #
+    def record_id_cut(id)
+      return if id.blank?
+
+      @id_data[id][:count] -= 1 if @id_data[id][:count].positive?
+      @id_data[id][:last_pasted] = false
+    end
+
+    # Keeps track that an element with the given ID has been pasted.
+    #
+    # @param id [String]
+    #
+    def record_id_pasted(id)
+      return if id.blank?
+
+      @id_data[id][:count] += 1 if @id_data[id][:last_pasted]
+      @id_data[id][:last_pasted] = true
+    end
+
+    # Returns a unique ID given the ID of an element that was copied and is about
+    # to be pasted
+    #
+    # @param original_id [String]
+    # @return [String]
+    #
+    def modified_id_to_paste(original_id)
+      return nil if original_id.nil?
+      return '' if original_id.blank?
+
+      count = @id_data[original_id][:count]
+      # A count of 0 means the element was cut and this is the first paste, do not
+      # modify the ID; otherwise, use the uniquified ID.
+      if count.zero?
+        original_id
+      else
+        "#{original_id}#{@id_copy_suffix}#{count}"
+      end
+    end
+  end
+end

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

@@ -13,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
@@ -46,15 +52,6 @@ module Kitchen
       end
     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'
-    end
-
     protected
 
     def detected_note_title_key

data/lib/kitchen/note_element_enumerator.rb

@@ -11,7 +11,7 @@ module Kitchen
     #
     def self.factory
       ElementEnumeratorFactory.new(
-        default_css_or_xpath: "div[data-type='note']", # TODO: get from config?
+        default_css_or_xpath: Selector.named(:note),
         sub_element_class: NoteElement,
         enumerator_class: self
       )

data/lib/kitchen/oven.rb

@@ -28,6 +28,8 @@ module Kitchen
         config: config
       )
 
+      I18n.locale = doc.locale
+
       [recipes].flatten.each do |recipe|
         recipe.document = doc
         recipe.bake
@@ -35,10 +37,12 @@ module Kitchen
       profile.baked!
 
       File.open(output_file, 'w') do |f|
-        f.write doc.to_xhtml(indent: 2)
+        f.write doc.to_xhtml(indent: 2, encoding: doc.encoding || 'utf-8')
       end
       profile.written!
 
+      Nokogiri::XML.print_profile_data if ENV['PROFILE'] && !ENV['TESTING']
+
       profile
     end