openstax_kitchen 3.0.0 → 4.1.1

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

@@ -39,6 +39,8 @@ module Kitchen
       end
       profile.written!
 
+      Nokogiri::XML.print_profile_data if ENV['PROFILE'] && !ENV['TESTING']
+
       profile
     end
 

data/lib/kitchen/page_element.rb

@@ -13,8 +13,14 @@ module Kitchen
     def initialize(node:, document: nil)
       super(node: node,
             document: document,
-            enumerator_class: PageElementEnumerator,
-            short_type: :page)
+            enumerator_class: PageElementEnumerator)
+    end
+
+    # Returns the short type
+    # @return [Symbol]
+    #
+    def self.short_type
+      :page
     end
 
     # Returns the title element.  This method is aware that the title of the
@@ -23,9 +29,20 @@ module Kitchen
     # @raise [ElementNotFoundError] if no matching element is found
     # @return [Element]
     #
-    def title
+    def title(reload: false)
       # The selector for intro titles changes during the baking process
-      first!(is_introduction? ? selectors.title_in_introduction_page : selectors.title_in_page)
+      @title ||= begin
+        selector = is_introduction? ? selectors.title_in_introduction_page : selectors.title_in_page
+        first!(selector, reload: reload)
+      end
+    end
+
+    # Returns the title's text regardless of whether the title has been baked
+    #
+    # @return [String]
+    #
+    def title_text
+      title.children.one? ? title.text : title.first('.os-text').text
     end
 
     # Returns an enumerator for titles.
@@ -87,13 +104,20 @@ module Kitchen
       first!('section.exercises')
     end
 
-    # Returns true if this class represents the element for the given node
+    # Returns the key concepts
     #
-    # @param node [Nokogiri::XML::Node] the underlying node
-    # @return [Boolean]
+    # @return [Element]
+    #
+    def key_concepts
+      search('section.key-concepts')
+    end
+
+    # Returns the free response questions
+    #
+    # @return [Element]
     #
-    def self.is_the_element_class_for?(node)
-      node['data-type'] == 'page'
+    def free_response
+      search('section.free-response')
     end
 
   end

data/lib/kitchen/page_element_enumerator.rb

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

data/lib/kitchen/patches/nokogiri.rb

@@ -31,6 +31,21 @@ module Nokogiri
           end
         end
       end
+
+      def add_all_namespaces!
+        # Nokogiri by default only recognizes the namespaces on the root node.  Collect all
+        # namespaces and add them manually.
+        return if @all_namespaces_added
+
+        collect_namespaces.each do |namespace, url|
+          prefix, name = namespace.split(':')
+          next unless prefix == 'xmlns' && name.present?
+
+          root.add_namespace_definition(name, url)
+        end
+
+        @all_namespaces_added = true
+      end
     end
 
     # Monkey patches for Nokogiri::XML::Node
@@ -43,6 +58,46 @@ module Nokogiri
       def inspect
         to_s
       end
+
+      def quick_matches?(selector)
+        self.class.selector_to_css_nodes(selector).any? { |css_node| matches_css_node?(css_node) }
+      end
+
+      def classes
+        self[:class]&.split || []
+      end
+
+      def self.selector_to_css_nodes(selector)
+        # No need to parse the same selector more than once.
+        @parsed_selectors ||= {}
+        @parsed_selectors[selector] ||= Nokogiri::CSS::Parser.new.parse(selector)
+      end
+
+      protected
+
+      # rubocop:disable Metrics/CyclomaticComplexity
+      def matches_css_node?(css_node)
+        case css_node.type
+        when :CONDITIONAL_SELECTOR
+          css_node.value.all? { |inner_css_node| matches_css_node?(inner_css_node) }
+        when :ELEMENT_NAME
+          css_node.value == ['*'] || css_node.value.include?(name)
+        when :CLASS_CONDITION
+          (css_node.value & classes).any?
+        when :ATTRIBUTE_CONDITION
+          attribute, operator, value = css_node.value
+
+          raise "Unknown attribute condition operator in #{css_node}" if operator != :equal
+
+          attribute_name = attribute.value
+          raise "More attribute names than expected, #{attribute_name}" if attribute_name.many?
+
+          self[attribute_name.first] == value.gsub('"', '').gsub("'", '')
+        else
+          raise "Unknown Nokogiri::CSS:Node type in #{css_node}"
+        end
+      end
+      # rubocop:enable Metrics/CyclomaticComplexity
     end
   end
 end

data/lib/kitchen/patches/nokogiri_profiling.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+# rubocop:disable Style/Documentation
+
+# Make debug output more useful (dumping entire document out is not useful)
+module Nokogiri
+  module XML
+    # rubocop:disable Style/MutableConstant
+    PROFILE_DATA = {}
+    # rubocop:enable Style/MutableConstant
+
+    if ENV['PROFILE']
+      ENV['VERBOSE_PROFILE'] = 1 if ENV['PROFILE'].to_s.downcase == 'verbose'
+
+      # Patches inside Nokogiri to count, time, and print searches.  At end of baking
+      # you can `puts Nokogiri::XML::PROFILE_DATA` to see the totals.  The counts
+      # hash is defined outside of the if block so that code that prints it doesn't
+      # explode if run without the env var.  The `print_profile_data` method is also
+      # provided for a nice printout
+
+      def self.print_profile_data
+        total_duration = 0
+
+        sorted_profile_data = PROFILE_DATA.sort_by { |_, data| data[:time] / data[:count] }.reverse
+
+        puts "\nSearch Profile Data"
+        puts '-----------------------------------------------------------------'
+        puts "#{'Total Time (ms)'.ljust(17)}#{'Avg Time (ms)'.ljust(15)}#{'Count'.ljust(7)}Query"
+        puts '-----------------------------------------------------------------'
+
+        sorted_profile_data.each do |search_path, data|
+          total_time = format('%0.4f', (data[:time] * 1000))
+          avg_time = format('%0.4f', ((data[:time] / data[:count]) * 1000))
+          puts total_time.ljust(17) + avg_time.to_s.ljust(15) + data[:count].to_s.ljust(7) + \
+               search_path
+          total_duration += data[:time] * 1000
+        end
+
+        puts "\nTotal time across all searches (ms): #{total_duration}"
+      end
+
+      class XPathContext
+        alias_method :original_evaluate, :evaluate
+        def evaluate(search_path, handler=nil)
+          puts search_path if ENV['VERBOSE_PROFILE']
+
+          PROFILE_DATA[search_path] ||= Hash.new(0)
+          PROFILE_DATA[search_path][:count] += 1
+
+          start_time = Time.now
+          original_evaluate(search_path, handler).tap do
+            PROFILE_DATA[search_path][:time] += Time.now - start_time
+          end
+        end
+      end
+    end
+  end
+end
+
+# rubocop:enable Style/Documentation

data/lib/kitchen/recipe.rb

@@ -14,6 +14,10 @@ module Kitchen
     # @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
@@ -31,20 +35,29 @@ 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
+
+      load_my_i18n_backend(locales_dir)
     end
 
     # Executes the block given to +Recipe.new+ on the document.  Aka, does the baking.
     #
     def bake
-      @block.to_proc.call(document)
+      with_my_locales do
+        @block.to_proc.call(document)
+      end
     rescue RecipeError, ElementNotFoundError, Nokogiri::CSS::SyntaxError => e
       print_recipe_error_and_exit(e)
     rescue ArgumentError, NoMethodError => e
@@ -67,6 +80,26 @@ module Kitchen
       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

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_query.rb

@@ -24,6 +24,7 @@ module Kitchen
       @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
@@ -35,13 +36,34 @@ module Kitchen
     end
 
     # Replaces '$' in the `css_or_xpath` with the provided value; also normalizes
-    # `css_or_xpath` to an array
+    # `css_or_xpath` to an array.
     #
-    def apply_default_css_or_xpath_and_normalize(default_css_or_xpath=nil)
+    # @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].flatten.join(', '))
+        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
@@ -60,6 +82,12 @@ module Kitchen
       as_type
     end
 
+    # Returns true if the query has the substitution character ('$')
+    #
+    def expects_substitution?
+      css_or_xpath.nil? || [css_or_xpath].flatten.all? { |item| item.include?('$') }
+    end
+
     protected
 
     def condition_passes?(method_or_callable, element, success_outcome)

data/lib/kitchen/selector.rb

@@ -0,0 +1,25 @@
+# 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)
+      @instances ||= {}
+      @instances[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

@@ -17,6 +17,45 @@ module Kitchen
       # 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
       #