openstax_kitchen 1.0.0 → 4.0.0

data/lib/kitchen/reference_element.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Kitchen
+  # An element for an example
+  #
+  class ReferenceElement < ElementBase
+
+    # Creates a new +ReferenceElement+
+    #
+    # @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: ReferenceElementEnumerator)
+    end
+
+    # Returns the short type
+    # @return [Symbol]
+    #
+    def self.short_type
+      :reference
+    end
+
+  end
+end

data/lib/kitchen/references_element_enumerator.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Kitchen
+  # An enumerator for table elements
+  #
+  class ReferenceElementEnumerator < ElementEnumeratorBase
+    # Returns a factory for this enumerator
+    #
+    # @return [ElementEnumeratorFactory]
+    #
+    def self.factory
+      ElementEnumeratorFactory.new(
+        default_css_or_xpath: Selector.named(:reference),
+        sub_element_class: ReferenceElement,
+        enumerator_class: self
+      )
+    end
+
+  end
+end

data/lib/kitchen/search_history.rb

@@ -1,31 +1,70 @@
+# frozen_string_literal: true
+
 module Kitchen
+  # Records the search history that was used to find a certain element
+  #
   class SearchHistory
     attr_reader :latest
     attr_reader :upstream
 
+    # Returns an empty search history
+    #
+    # @return [SearchHistory]
+    #
     def self.empty
       new
     end
 
-    def add(css_or_xpath)
-      self.class.new(self, css_or_xpath.nil? ? nil : [css_or_xpath].join(", "))
+    # Returns a new +SearchHistory+ that contains the current history plus the
+    # provided query
+    #
+    # @param search_query [SearchQuery] the search query to add to the history
+    # @return [SearchHistory]
+    #
+    def add(search_query)
+      search_query = SearchQuery.new(css_or_xpath: search_query) if search_query.is_a?(String)
+      self.class.new(self, search_query)
     end
 
-    def to_s(missing_string="?")
-      to_a.map{|item| "[#{item || missing_string}]"}.join(" ")
+    # Returns the history as a string
+    #
+    # @param missing_string [String] if there's a missing part of the history, this string
+    #   is used in its place
+    # @return [String]
+    #
+    def to_s(missing_string='?')
+      array = to_a
+      array.shift while array.any? && array[0].nil?
+      array.map { |item| "[#{item || missing_string}]" }.join(' ')
     end
 
+    # Returns this instance as an array of selectors
+    #
+    # @return [Array<String>]
+    #
     def to_a
       empty? ? [] : [upstream&.to_a || [], latest].flatten
     end
 
+    # Returns true if the search history is empty
+    #
+    # @return [Boolean]
+    #
     def empty?
       upstream.nil? && latest.nil?
     end
 
     protected
 
+    # Create a new instance
+    #
+    # @param upstream [SearchHistory] prior search history
+    # @param latest [SearchQuery] the new history
+    #
     def initialize(upstream=nil, latest=nil)
+      raise 'Upstream must be a SearchHistory' unless upstream.nil? || upstream.is_a?(SearchHistory)
+      raise 'Latest must be a SearchQuery' unless latest.nil? || latest.is_a?(SearchQuery)
+
       @upstream = upstream
       @latest = latest
     end

data/lib/kitchen/search_query.rb

@@ -0,0 +1,106 @@
+# 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
+      @default_already_applied = false
+    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.
+    #
+    # @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.
+    #
+    def apply_default_css_or_xpath_and_normalize(default_css_or_xpath=nil, config: nil)
+      return if @default_already_applied
+
+      default_css_or_xpath = [default_css_or_xpath].flatten.map do |item|
+        case item
+        when Proc
+          item.call(config)
+        when Symbol
+          config.selectors.send(item)
+        else
+          item
+        end
+      end
+
+      @as_type = nil
+      @css_or_xpath = [css_or_xpath || '$'].flatten.map do |item|
+        item.gsub(/\$/, default_css_or_xpath.join(', '))
+      end
+
+      @default_already_applied = true
+    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/selector.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Kitchen
+  # A wrapper for a selector.  Can be used as the default_css_or_xpath.
+  #
+  class Selector < Proc
+    attr_reader :name
+
+    def self.named(name)
+      new(name) { |config| config.selectors.send(name) }
+    end
+
+    def initialize(name, &block)
+      @name = name
+      super(&block)
+    end
+
+    def matches?(node, config:)
+      # This may not be incredibly efficient as it does a search of this node's
+      # ancestors to see if the node is in the results.  Watch the performance.
+      node.matches?(call(config))
+    end
+  end
+end

data/lib/kitchen/selectors/base.rb

@@ -1,8 +1,73 @@
+# 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
+      # Selector for a reference
+      # @return [String]
+      attr_accessor :reference
+      # Selector for a chapter
+      # @return [String]
+      attr_accessor :chapter
+      # Selector for a page
+      # @return [String]
+      attr_accessor :page
+      # Selector for a note
+      # @return [String]
+      attr_accessor :note
+      # Selector for a term
+      # @return [String]
+      attr_accessor :term
+      # Selector for a table
+      # @return [String]
+      attr_accessor :table
+      # Selector for a figure
+      # @return [String]
+      attr_accessor :figure
+      # Selector for a metadata
+      # @return [String]
+      attr_accessor :metadata
+      # Selector for a composite page
+      # @return [String]
+      attr_accessor :composite_page
+      # Selector for a composite chapter
+      # @return [String]
+      attr_accessor :composite_chapter
+      # Selector for an example
+      # @return [String]
+      attr_accessor :example
+      # Selector for an exercise
+      # @return [String]
+      attr_accessor :exercise
+      # Selector for an unit
+      # @return [String]
+      attr_accessor :unit
+
+      # 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,31 @@
+# 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'
+        self.reference                  = '.reference'
+        self.chapter                    = "div[data-type='chapter']"
+        self.page                       = "div[data-type='page']"
+        self.note                       = "div[data-type='note']"
+        self.term                       = "span[data-type='term']"
+        self.table                      = 'table'
+        self.figure                     = 'figure'
+        self.metadata                   = "div[data-type='metadata']"
+        self.composite_page             = "div[data-type='composite-page']"
+        self.composite_chapter          = "div[data-type='composite-chapter']"
+        self.example                    = "div[data-type='example']"
+        self.exercise                   = "div[data-type='exercise']"
+        self.unit                       = "div[data-type='unit']"
       end
 
     end

data/lib/kitchen/table_element.rb

@@ -1,35 +1,83 @@
+# 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,
-            enumerator_class: TableElementEnumerator,
-            short_type: :table)
+            enumerator_class: TableElementEnumerator)
+    end
+
+    # Returns the short type
+    # @return [Symbol]
+    #
+    def self.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
 
-    def caption
-      first("caption")
+    # Returns true if the table is unstyled
+    #
+    # @return [Boolean]
+    #
+    def unstyled?
+      has_class?('unstyled')
     end
 
-    def self.is_the_element_class_for?(node)
-      node.name == "table"
+    # 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')
     end
 
   end