openstax_kitchen 3.2.0 → 4.0.0

data/lib/kitchen/document.rb

@@ -46,6 +46,17 @@ module Kitchen
       @config = config || Config.new
       @next_paste_count_for_id = {}
       @id_copy_suffix = '_copy_'
+
+      # Nokogiri by default only recognizes the namespaces on the root node.  Collect all
+      # namespaces and add them manually.
+      return unless @config.enable_all_namespaces && raw.present?
+
+      raw.collect_namespaces.each do |namespace, url|
+        prefix, name = namespace.split(':')
+        next unless prefix == 'xmlns' && name.present?
+
+        raw.root.add_namespace_definition(name, url)
+      end
     end
 
     # Returns an enumerator that iterates over all children of this document

data/lib/kitchen/element.rb

@@ -19,8 +19,14 @@ module Kitchen
             short_type: short_type)
     end
 
-    # # @!method pages
-    # #   Returns a pages enumerator
-    # def_delegators :as_enumerator, :pages, :chapters, :terms, :figures, :notes, :tables, :examples
+    # Returns true if this class represents the element for the given node; always false
+    # for this generic class
+    #
+    # @param node [Nokogiri::XML::Node] the underlying node
+    # @return [Boolean]
+    #
+    def self.is_the_element_class_for?(_node, **)
+      false
+    end
   end
 end

data/lib/kitchen/element_base.rb

@@ -3,6 +3,7 @@
 require 'forwardable'
 require 'securerandom'
 
+# rubocop:disable Metrics/ClassLength
 module Kitchen
   # Abstract base class for all elements.  If you are looking for a simple concrete
   # element class, use `Element`.
@@ -92,6 +93,14 @@ module Kitchen
     #   @return [Selectors::Base]
     def_delegators :config, :selectors
 
+    # @!method pantry
+    #   Access the pantry for this element's document
+    #   @return [Pantry]
+    # @!method :clipboard
+    #   Access the clipboard for this element's document
+    #   @return [Clipboard]
+    def_delegators :document, :pantry, :clipboard
+
     # Creates a new instance
     #
     # @param node [Nokogiri::XML::Node] the wrapped element
@@ -108,7 +117,9 @@ module Kitchen
 
       @enumerator_class = enumerator_class
 
-      @short_type = short_type || "unknown_type_#{SecureRandom.hex(4)}"
+      @short_type = short_type ||
+                    self.class.try(:short_type) ||
+                    "unknown_type_#{SecureRandom.hex(4)}"
 
       @document =
         case document
@@ -123,14 +134,50 @@ module Kitchen
       @is_a_clone = false
     end
 
+    # Returns ElementBase descendent type or nil if none found
+    #
+    # @param type [Symbol] the descendant type, e.g. `:page`
+    # @return [Class] the child class for the given type
+    #
+    def self.descendant(type)
+      @types_to_descendants ||=
+        descendants.each_with_object({}) do |descendant, hash|
+          next unless descendant.try(:short_type)
+
+          hash[descendant.short_type] = descendant
+        end
+
+      @types_to_descendants[type]
+    end
+
+    # Returns ElementBase descendent type or Error if none found
+    #
+    # @param type [Symbol] the descendant type, e.g. `:page`
+    # @raise if the type is unknown
+    # @return [Class] the child class for the given type
+    #
+    def self.descendant!(type)
+      descendant(type) || raise("Unknown ElementBase descendant type '#{type}'")
+    end
+
+    # Returns true if this element is the given type
+    #
+    # @param type [Symbol] the descendant type, e.g. `:page`
+    # @raise if the type is unknown
+    # @return [Boolean]
+    #
+    def is?(type)
+      ElementBase.descendant!(type).is_the_element_class_for?(raw, config: config)
+    end
+
     # Returns true if this class represents the element for the given node
     #
     # @param node [Nokogiri::XML::Node] the underlying node
+    # @param config [Kitchen::Config]
     # @return [Boolean]
     #
-    def self.is_the_element_class_for?(_node)
-      # override this in subclasses
-      false
+    def self.is_the_element_class_for?(node, config:)
+      Selector.named(short_type).matches?(node, config: config)
     end
 
     # Returns true if this element has the given class
@@ -383,7 +430,7 @@ module Kitchen
       block_error_if(block_given?)
 
       node.remove
-      clipboard(to).add(self) if to.present?
+      get_clipboard(to).add(self) if to.present?
       self
     end
 
@@ -404,7 +451,7 @@ module Kitchen
 
         document.record_id_copied(node[:id])
       end
-      clipboard(to).add(the_copy) if to.present?
+      get_clipboard(to).add(the_copy) if to.present?
       the_copy
     end
 
@@ -646,7 +693,8 @@ module Kitchen
     # @!method pages
     #   Returns a pages enumerator
     def_delegators :as_enumerator, :pages, :chapters, :terms, :figures, :notes, :tables, :examples,
-                   :metadatas, :non_introduction_pages, :units, :titles, :exercises, :composite_pages
+                   :metadatas, :non_introduction_pages, :units, :titles, :exercises, :references,
+                   :composite_pages
 
     # Returns this element as an enumerator (over only one element, itself)
     #
@@ -671,10 +719,10 @@ module Kitchen
     # @param name_or_object [String, Clipboard] the name of the clipboard or the clipboard itself
     # @return [Clipboard]
     #
-    def clipboard(name_or_object)
+    def get_clipboard(name_or_object)
       case name_or_object
       when Symbol
-        document.clipboard(name: name_or_object)
+        clipboard(name: name_or_object)
       when Clipboard
         name_or_object
       else
@@ -688,7 +736,9 @@ module Kitchen
     # @param string [String] the string to clean
     def remove_default_namespaces_if_clone(string)
       if is_a_clone
-        string.gsub('xmlns:default="http://www.w3.org/1999/xhtml"', '').gsub('default:', '')
+        string.gsub('xmlns:default="http://www.w3.org/1999/xhtml"', '')
+              .gsub('xmlns="http://www.w3.org/1999/xhtml"', '')
+              .gsub('default:', '')
       else
         string
       end
@@ -701,3 +751,4 @@ module Kitchen
 
   end
 end
+# rubocop:enable Metrics/ClassLength

data/lib/kitchen/element_enumerator_base.rb

@@ -218,11 +218,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
@@ -37,8 +40,6 @@ module Kitchen
     #   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, search_query: search_query)
@@ -55,7 +56,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
       )
@@ -64,6 +65,9 @@ module Kitchen
     protected
 
     def build_within_element(element, search_query:)
+      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)

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.

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/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
       )