openstax_kitchen 2.0.0 → 3.0.0

data/lib/kitchen/search_query.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Kitchen
+  # Records the search history that was used to find a certain element
+  #
+  class SearchQuery
+    attr_reader :css_or_xpath
+    attr_reader :only
+    attr_reader :except
+
+    # Create a new SearchQuery
+    #
+    # @param css_or_xpath [String, Array<String>] selectors to use to limit iteration results
+    #   a "$" in this argument can be replaced with a default selector via
+    #   #apply_default_css_or_xpath_and_normalize
+    # @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 initialize(css_or_xpath: nil, only: nil, except: nil)
+      @css_or_xpath = css_or_xpath
+      @only = only.is_a?(String) ? only.to_sym : only
+      @except = except.is_a?(String) ? except.to_sym : except
+    end
+
+    # Returns true iff the element passes the `only` and `except` conditions
+    #
+    # @return [Boolean]
+    #
+    def conditions_match?(element)
+      condition_passes?(except, element, false) && condition_passes?(only, element, true)
+    end
+
+    # Replaces '$' in the `css_or_xpath` with the provided value; also normalizes
+    # `css_or_xpath` to an array
+    #
+    def apply_default_css_or_xpath_and_normalize(default_css_or_xpath=nil)
+      @as_type = nil
+      @css_or_xpath = [css_or_xpath || '$'].flatten.map do |item|
+        item.gsub(/\$/, [default_css_or_xpath].flatten.join(', '))
+      end
+    end
+
+    # Returns the search query as a spaceless string suitable for use as an element type
+    #
+    def as_type
+      @as_type ||= [
+        [css_or_xpath].flatten.join(','),
+        stringify_condition(only, 'only'),
+        stringify_condition(except, 'except')
+      ].compact.join(';')
+    end
+
+    # Returns a string representation of the search query
+    #
+    def to_s
+      as_type
+    end
+
+    protected
+
+    def condition_passes?(method_or_callable, element, success_outcome)
+      return true if method_or_callable.nil?
+
+      result =
+        if method_or_callable.is_a?(Symbol)
+          element.send(method_or_callable)
+        else
+          method_or_callable.call(element)
+        end
+
+      !!result == success_outcome
+    end
+
+    def stringify_condition(condition, name)
+      return nil unless condition
+
+      "#{name}:#{condition.is_a?(Symbol) ? condition : condition.source_location.join(':')}"
+    end
+  end
+end

data/lib/kitchen/selectors/base.rb

@@ -1,8 +1,34 @@
+# frozen_string_literal: true
+
 module Kitchen
+  # A centralized place to put common CSS selectors so they aren't sprinkled
+  # throughout the baseline (and so that they can be changed easily if needed)
+  #
   module Selectors
+    # Base class for different selector configurations
+    #
     class Base
+      # Selector for the title in a page
+      # @return [String]
       attr_accessor :title_in_page
+      # Selector for the title in an introduction page
+      # @return [String]
       attr_accessor :title_in_introduction_page
+      # Selector for the summary in a page
+      # @return [String]
+      attr_accessor :page_summary
+
+      # Override specific selectors
+      #
+      # @param hash [Hash] a hash of selectors to selector values, e.g. {title_in_page: '.title'}
+      # @return [Base] this object
+      #
+      def override(hash={})
+        hash.each do |selector, value|
+          send("#{selector}=", value)
+        end
+        self
+      end
     end
   end
 end

data/lib/kitchen/selectors/standard_1.rb

@@ -1,10 +1,18 @@
+# frozen_string_literal: true
+
 module Kitchen
   module Selectors
+    # A specific set of selectors
+    #
     class Standard1 < Base
 
+      # Create a new instance
+      #
       def initialize
+        super
         self.title_in_page              = "./*[@data-type = 'document-title']"
         self.title_in_introduction_page = "./*[@data-type = 'document-title']"
+        self.page_summary               = 'section.summary'
       end
 
     end

data/lib/kitchen/table_element.rb

@@ -1,6 +1,15 @@
+# frozen_string_literal: true
+
 module Kitchen
+  # An element for a table
+  #
   class TableElement < ElementBase
 
+    # Creates a new +TableElement+
+    #
+    # @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,
@@ -8,28 +17,70 @@ module Kitchen
             short_type: :table)
     end
 
+    # Returns an element for the title row, if present
+    #
+    # @return [Element, nil]
+    #
     def title_row
       top_titled? ? first('thead').first('tr') : nil
     end
 
+    # Returns the title nodes in the first title row element
+    #
+    # @return [Nokogiri::XML::NodeSet] Unusual to return the raw Nokogiri nodes!
+    #
     def title
-      title_row&.first('th').children
+      # TODO: replace +children+ with +element_children+?
+      title_row&.first('th')&.children
     end
 
+    # Returns true if the table has a title at the top
+    #
+    # @return [Boolean]
+    #
     def top_titled?
       has_class?('top-titled')
     end
 
+    # Returns true if the table is unnumbered
+    #
+    # @return [Boolean]
+    #
     def unnumbered?
       has_class?('unnumbered')
     end
 
+    # Returns true if the table is unstyled
+    #
+    # @return [Boolean]
+    #
+    def unstyled?
+      has_class?('unstyled')
+    end
+
+    # Returns true if the table has a column header
+    #
+    # @return [Boolean]
+    #
+    def column_header?
+      has_class?('column-header')
+    end
+
+    # Returns an element for the table caption, if present
+    #
+    # @return [Element, nil]
+    #
     def caption
-      first("caption")
+      first('caption')
     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 == "table"
+      node.name == 'table'
     end
 
   end

data/lib/kitchen/table_element_enumerator.rb

@@ -1,9 +1,17 @@
+# frozen_string_literal: true
+
 module Kitchen
+  # An enumerator for table elements
+  #
   class TableElementEnumerator < ElementEnumeratorBase
 
+    # Returns a factory for this enumerator
+    #
+    # @return [ElementEnumeratorFactory]
+    #
     def self.factory
       ElementEnumeratorFactory.new(
-        default_css_or_xpath: "table", # TODO get from config?
+        default_css_or_xpath: 'table', # TODO: get from config?
         sub_element_class: TableElement,
         enumerator_class: self
       )

data/lib/kitchen/term_element.rb

@@ -1,6 +1,15 @@
+# frozen_string_literal: true
+
 module Kitchen
+  # An element for a term
+  #
   class TermElement < ElementBase
 
+    # Creates a new +TermElement+
+    #
+    # @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,
@@ -8,8 +17,13 @@ module Kitchen
             short_type: :term)
     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'] == "term"
+      node['data-type'] == 'term'
     end
 
   end

data/lib/kitchen/term_element_enumerator.rb

@@ -1,9 +1,17 @@
+# frozen_string_literal: true
+
 module Kitchen
+  # An enumerator for term elements
+  #
   class TermElementEnumerator < ElementEnumeratorBase
 
+    # Returns a factory for this enumerator
+    #
+    # @return [ElementEnumeratorFactory]
+    #
     def self.factory
       ElementEnumeratorFactory.new(
-        default_css_or_xpath: "span[data-type='term']", # TODO get from config?
+        default_css_or_xpath: "span[data-type='term']", # TODO: get from config?
         sub_element_class: TermElement,
         enumerator_class: self
       )

data/lib/kitchen/transliterations.rb

@@ -1,19 +1,21 @@
+# frozen_string_literal: true
+
 module Kitchen
   # These are added to every translation locale, including the `test` locale
   # set by `stub_locales`.  When we sort strings with accent marks, we use
   # `ActiveSupport::Inflector.transliterate` to ensure that the sorting is
   # sensible.  This method does not know about Greek characters by default so
   # we teach it about them by adding the rules below to the i18n configuration.
-
+  #
   TRANSLITERATIONS = {
     i18n: {
       transliterate: {
         rule: {
-          σ: "σ",
-          Δ: "Δ",
-          π: "π",
+          σ: 'σ',
+          Δ: 'Δ',
+          π: 'π'
         }
       }
     }
-  }
+  }.freeze
 end

data/lib/kitchen/type_casting_element_enumerator.rb

@@ -1,6 +1,15 @@
+# frozen_string_literal: true
+
 module Kitchen
+  # An enumerator that detects the element type as it iterates and returns specific,
+  # different element classes based on that type.
+  #
   class TypeCastingElementEnumerator < ElementEnumeratorBase
 
+    # Returns a factory for this enumerator
+    #
+    # @return [ElementEnumeratorFactory]
+    #
     def self.factory
       ElementEnumeratorFactory.new(
         enumerator_class: self,
@@ -8,12 +17,19 @@ module Kitchen
       )
     end
 
+    # Returns a new enumerator that returns only the specified element classes within the
+    # scope of this enumerator.
+    #
+    # @param element_classes [Array<ElementBase>] the element classes to limit iteration to
+    # @return [TypeCastingElementEnumerator]
+    #
     def only(*element_classes)
       element_classes.flatten!
 
       TypeCastingElementEnumerator.new do |block|
-        self.each do |element|
+        each do |element|
           next unless element_classes.include?(element.class)
+
           block.yield(element)
         end
       end

data/lib/kitchen/unit_element.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Kitchen
+  # An element for a unit
+  #
+  class UnitElement < ElementBase
+
+    # Creates a new +UnitElement+
+    #
+    # @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: UnitElementEnumerator,
+            short_type: :unit)
+    end
+
+    # Get the title in the immediate children, not the one in the metadata.  Could use
+    # CSS of ":not([data-type='metadata']) >
+    #         [data-type='document-title'], [data-type='document-title']"
+    # but xpath is shorter
+    # @return [Element]
+    #
+    def title
+      first!("./*[@data-type = 'document-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'] == 'unit'
+    end
+  end
+end

data/lib/kitchen/unit_element_enumerator.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Kitchen
+  # An enumerator for unit elements
+  #
+  class UnitElementEnumerator < ElementEnumeratorBase
+
+    # Returns a factory for this enumerator
+    #
+    # @return [ElementEnumeratorFactory]
+    #
+    def self.factory
+      ElementEnumeratorFactory.new(
+        default_css_or_xpath: "div[data-type='unit']",
+        sub_element_class: UnitElement,
+        enumerator_class: self
+      )
+    end
+  end
+end

data/lib/kitchen/utils.rb

@@ -1,19 +1,16 @@
+# frozen_string_literal: true
+
 module Kitchen
+  # Utility methods
+  #
   module Utils
-
+    # A standard way to convert a search path to an element type
+    #
+    # @param search_path [String, Array<String>] selectors
+    # @return [String]
+    #
     def self.search_path_to_type(search_path)
-      [search_path].flatten.join(",")
+      [search_path].flatten.join(',')
     end
-
-    def self.normalized_xhtml_string(xml_thing_with_to_s)
-      doc = Nokogiri::XML(xml_thing_with_to_s.to_s) do |config|
-        config.noblanks
-      end
-
-      doc.alphabetize_attributes!
-
-      doc.to_xhtml(indent: 2)
-    end
-
   end
 end