openstax_kitchen 2.0.0 → 4.1.0

data/lib/kitchen/patches/string.rb

@@ -1,4 +1,12 @@
+# frozen_string_literal: true
+
+# Monkey patches for +String+
+#
 class String
+  # Downcases the first letter of self, returning a new string
+  #
+  # @return [String]
+  #
   def uncapitalize
     sub(/^[A-Z]/, &:downcase)
   end

data/lib/kitchen/recipe.rb

@@ -1,9 +1,28 @@
+# frozen_string_literal: true
+
 module Kitchen
+  # An object that yields a +Document+ for modification (those modifications are
+  # the "recipe")
+  #
   class Recipe
 
+    # The document the recipe makes available for modification
+    # @return [Document]
     attr_reader :document
+
+    # The file location of the recipe
+    # @return [String]
     attr_reader :source_location
 
+    # An I18n backend specific to this recipe, may be nil
+    # @return [I18n::Backend::Simple, nil]
+    attr_reader :my_i18n_backend
+
+    # Sets the document so the recipe can yield it for modification
+    #
+    # @param document [Document] the document to modify
+    # @raise [StandardError] if not passed supported document type
+    #
     def document=(document)
       @document =
         case document
@@ -16,57 +35,75 @@ module Kitchen
 
     # Make a new Recipe
     #
+    # @param locales_dir [String, nil] the absolute path to a folder containing recipe-specific
+    #   I18n translations.  If not provided, Kitchen will look for a `locales` directory in the
+    #   same directory as the recipe source.  Recipe-specific translations override those in
+    #   Kitchen.  If no recipe-specific locales directory exists, Kitchen will just use its default
+    #   translations.
+    # @yield A block for defining the steps of the recipe
     # @yieldparam doc [Document] an object representing an XML document
     #
-    def initialize(&block)
+    def initialize(locales_dir: nil, &block)
+      raise(RecipeError, 'Recipes must be initialized with a block') unless block_given?
+
       @source_location = block.source_location[0]
       @block = block
-    end
 
-    def node!
-      node || raise("The recipe's node has not been set")
+      load_my_i18n_backend(locales_dir)
     end
 
+    # Executes the block given to +Recipe.new+ on the document.  Aka, does the baking.
+    #
     def bake
-      begin
+      with_my_locales do
         @block.to_proc.call(document)
-      rescue RecipeError => ee
-        print_recipe_error_and_exit(ee)
-      rescue ArgumentError => ee
-        if if_any_stack_file_matches_source_location?(ee)
-          print_recipe_error_and_exit(ee)
-        else
-          raise
-        end
-      rescue NoMethodError => ee
-        if if_any_stack_file_matches_source_location?(ee)
-          print_recipe_error_and_exit(ee)
-        else
-          raise
-        end
-      rescue NameError => ee
-        if if_stack_starts_with_source_location?(ee)
-          print_recipe_error_and_exit(ee)
-        else
-          raise
-        end
-      rescue ElementNotFoundError => ee
-        print_recipe_error_and_exit(ee)
-      rescue Nokogiri::CSS::SyntaxError => ee
-        print_recipe_error_and_exit(ee)
       end
+    rescue RecipeError, ElementNotFoundError, Nokogiri::CSS::SyntaxError => e
+      print_recipe_error_and_exit(e)
+    rescue ArgumentError, NoMethodError => e
+      raise unless any_stack_file_matches_source_location?(e)
+
+      print_recipe_error_and_exit(e)
+    rescue NameError => e
+      raise unless stack_starts_with_source_location?(e)
+
+      print_recipe_error_and_exit(e)
     end
 
     protected
 
-    def if_stack_starts_with_source_location?(error)
+    def stack_starts_with_source_location?(error)
       error.backtrace.first.start_with?(source_location)
     end
 
-    def if_any_stack_file_matches_source_location?(error)
-      error.backtrace.any? {|entry| entry.start_with?(@source_location)}
+    def any_stack_file_matches_source_location?(error)
+      error.backtrace.any? { |entry| entry.start_with?(@source_location) }
+    end
+
+    def load_my_i18n_backend(locales_dir)
+      locales_dir ||= begin
+        guessed_locales_dir = "#{File.dirname(@source_location)}/locales"
+        File.directory?(guessed_locales_dir) ? guessed_locales_dir : nil
+      end
+
+      return unless locales_dir
+
+      @my_i18n_backend = I18n::Backend::Simple.new
+      @my_i18n_backend.load_translations(Dir[File.expand_path("#{locales_dir}/*.yml")])
+    end
+
+    def with_my_locales
+      original_i18n_backend = I18n.backend
+      I18n.backend = I18n::Backend::Chain.new(my_i18n_backend, original_i18n_backend)
+      yield
+    ensure
+      I18n.backend = original_i18n_backend
     end
 
+    # Print the given recipe error and do a process exit
+    #
+    # @param error [RecipeError] the error
+    #
     def print_recipe_error_and_exit(error)
       Kitchen::Debug.print_recipe_error(error: error,
                                         source_location: source_location,

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.quick_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