openstax_kitchen 4.1.0 → 4.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dacc1aae587e492dc42e693e46195c0ed10ba749f62929e322b0744f2f82e94c
-  data.tar.gz: 67b4f9691c4431fc172d48381527c1fd75c62dc866ea056ff6666205e73b0e22
+  metadata.gz: b80bf07271b311949246bf6a63a9d10fe5f14396175f66a129debcc9e9ef15e3
+  data.tar.gz: 7a3a7050d134a0b106d3a80dc18add9209742fca1eea4873f351eb0dd4d05034
 SHA512:
-  metadata.gz: 4a788770e4176617a260d8b2ce265303a59490dd1e95727bd38102732ce6459e3600a9eca807e6c80d364b3fb710c2dbce4ec71b66dbec6570b2d61ed8e00e40
-  data.tar.gz: 6df9ea776c2718b1d7fdc8508210774c29f407391e0802ac6e39a94b98aadfbdb6d47447f0f2a164a66413e122ba7b46e7669fd4af5caeeda26ac0cc591919ff
+  metadata.gz: 7fee3b2b4dd92639af2e20520c3f65a31255d944df649e91c5c0e5c8f0a8e1e1f6d19b4477480c5cbc899f7124727c8a40b5a0759985ec94225885baf36b3287
+  data.tar.gz: ed62932aa44e597135158cc182daefd2773b89070e1d82750669d4d1f760fa8179f1197c67eddcdec73c1cdc2b1bd7537ca28c8f5603d3a2a7962457d777141f

data/CHANGELOG.md

@@ -6,6 +6,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [4.1.1] - 2021-05-24
+
+* Adds low level Nokogiri caching, disabled by default (patch)
+* Cache Selector objects since they don't change (patch)
+* Use more specific selectors when to reduce bake time (patch)
+
 ## [4.1.0] - 2021-05-18
 
 * Fixed performance problem with element class detection (patch)

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    openstax_kitchen (4.1.0)
+    openstax_kitchen (4.1.1)
       activesupport
       i18n
       nokogiri

data/README.md

@@ -641,6 +641,22 @@ expect(book_1).to match_normalized_html("some string of HTML here")
 expect(book_1).to match_html_nodes("some string of HTML here")
 ```
 
+### Profiling
+
+If you set the `PROFILE` environment variable to something before you run specs or a recipe, search query profile data will be collected and printed, e.g.
+
+```bash
+%> PROFILE=1 rspec
+```
+
+### Caching
+
+There's a low-level CSS query caching tool that saves repeated queries.  In some tests, it saves 15% of query time.  It is disabled by default (because we aren't super sure that it is completely safe) but can be turned on with
+
+```ruby
+doc.config.enable_search_cache = true
+```
+
 ### VSCode
 
 1. Visit `vscode:extension/ms-vscode-remote.remote-containers` in a browser

data/codecov.yaml

@@ -25,3 +25,4 @@ ignore:
   - "bin"
   - "docker"
   - "books"
+  - "lib/kitchen/patches/nokogiri_profiling"

data/lib/kitchen/book_document.rb

@@ -29,7 +29,7 @@ module Kitchen
     # @return [BookElement]
     #
     def book
-      BookElement.new(node: nokogiri_document.search('html').first, document: self)
+      BookElement.new(node: nokogiri_document.root, document: self)
     end
 
   end

data/lib/kitchen/chapter_element.rb

@@ -41,7 +41,7 @@ module Kitchen
     # @return [Element, nil]
     #
     def introduction_page
-      pages('.introduction').first
+      pages('$.introduction').first
     end
 
     # Returns an enumerator for the glossaries
@@ -65,7 +65,7 @@ module Kitchen
     # @return [ElementEnumerator]
     #
     def abstracts
-      search('[data-type="abstract"]')
+      search('div[data-type="abstract"]')
     end
 
   end

data/lib/kitchen/composite_chapter_element_enumerator.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Kitchen
+  # An enumerator for composite page elements
+  #
+  class CompositeChapterElementEnumerator < ElementEnumeratorBase
+
+    # Returns a factory for this enumerator
+    #
+    # @return [ElementEnumeratorFactory]
+    #
+    def self.factory
+      ElementEnumeratorFactory.new(
+        default_css_or_xpath: Selector.named(:composite_chapter),
+        sub_element_class: CompositeChapterElement,
+        enumerator_class: self
+      )
+    end
+
+  end
+end

data/lib/kitchen/config.rb

@@ -17,6 +17,12 @@ module Kitchen
     #
     attr_accessor :enable_all_namespaces
 
+    # @!attribute [rw] enable_search_cache
+    #
+    # @return [Boolean]
+    #
+    attr_accessor :enable_search_cache
+
     # Creates a new config from a file (not implemented)
     #
     def self.new_from_file(_file)
@@ -28,6 +34,7 @@ module Kitchen
     def initialize(hash: {}, selectors: nil)
       @selectors = selectors || Kitchen::Selectors::Standard1.new
       @enable_all_namespaces = hash[:enable_all_namespaces] || true
+      @enable_search_cache = hash[:enable_search_cache] || false
       @hash = hash
     end
   end

data/lib/kitchen/directions/bake_chapter_key_concepts/v1.rb

@@ -19,7 +19,7 @@ module Kitchen::Directions::BakeChapterKeyConcepts
         key_concepts.each do |key_concept|
           key_concept.prepend(child: title)
           key_concept.wrap("<div class='os-section-area'>")
-          page.search('.os-section-area').first.cut(to: key_concepts_clipboard)
+          page.search('div.os-section-area').first.cut(to: key_concepts_clipboard)
         end
       end
 

data/lib/kitchen/directions/bake_composite_chapters.rb

@@ -4,7 +4,7 @@ module Kitchen
   module Directions
     module BakeCompositeChapters
       def self.v1(book:)
-        book.search("[data-type='composite-chapter']").each do |chapter|
+        book.composite_chapters.each do |chapter|
           chapter.first("[data-type='document-title']").id =
             "composite-chapter-#{chapter.count_in(:book)}"
         end

data/lib/kitchen/directions/bake_composite_pages.rb

@@ -4,7 +4,7 @@ module Kitchen
   module Directions
     module BakeCompositePages
       def self.v1(book:)
-        book.search("[data-type='composite-page']").each do |page|
+        book.composite_pages.each do |page|
           page.id = "composite-page-#{page.count_in(:book)}"
         end
       end

data/lib/kitchen/directions/bake_equations.rb

@@ -4,7 +4,7 @@ module Kitchen
   module Directions
     module BakeEquations
       def self.v1(book:, number_decorator: :none)
-        book.chapters.search('[data-type="equation"]:not(.unnumbered)').each do |eq|
+        book.chapters.search('div[data-type="equation"]:not(.unnumbered)').each do |eq|
           chapter = eq.ancestor(:chapter)
           number = "#{chapter.count_in(:book)}.#{eq.count_in(:chapter)}"
 

data/lib/kitchen/directions/book_answer_key_container/v1.rb

@@ -7,7 +7,7 @@ module Kitchen::Directions::BookAnswerKeyContainer
     def bake(book:)
       @metadata = book.metadata.children_to_keep.copy
       book.body.append(child: render(file: 'eob_solutions_container.xhtml.erb'))
-      book.body.first('.os-eob.os-solutions-container')
+      book.body.first('div.os-eob.os-solutions-container')
     end
   end
 end

data/lib/kitchen/directions/chapter_review_container/v1.rb

@@ -7,7 +7,7 @@ module Kitchen::Directions::ChapterReviewContainer
     def bake(chapter:, metadata_source:)
       @metadata = metadata_source.children_to_keep.copy
       chapter.append(child: render(file: 'chapter_review.xhtml.erb'))
-      chapter.first('.os-eoc.os-chapter-review-container')
+      chapter.first('div.os-eoc.os-chapter-review-container')
     end
   end
 end

data/lib/kitchen/directions/move_solutions_to_answer_key/strategies/uphysics.rb

@@ -18,7 +18,7 @@ module Kitchen::Directions::MoveSolutionsToAnswerKey
       def bake_section(chapter:, append_to:, klass:)
         section_solutions_set = []
         chapter.search(".#{klass}").each do |section|
-          section.search('[data-type="solution"]').each do |solution|
+          section.search('div[data-type="solution"]').each do |solution|
             section_solutions_set.push(solution.cut)
           end
         end
@@ -31,7 +31,7 @@ module Kitchen::Directions::MoveSolutionsToAnswerKey
 
       def bake_from_notes(chapter:, append_to:, klass:)
         solutions = []
-        chapter.notes(".#{klass}").each do |note|
+        chapter.notes("$.#{klass}").each do |note|
           note.exercises.each do |exercise|
             solution = exercise.solution
             solutions.push(solution.cut) if solution

data/lib/kitchen/document.rb

@@ -47,16 +47,8 @@ module Kitchen
       @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
+      # Nokogiri by default only recognizes the namespaces on the root node.  Add all others.
+      raw&.add_all_namespaces! if @config.enable_all_namespaces
     end
 
     # Returns an enumerator that iterates over all children of this document

data/lib/kitchen/element_base.rb

@@ -132,6 +132,7 @@ module Kitchen
       @ancestors = HashWithIndifferentAccess.new
       @search_query_matches_that_have_been_counted = {}
       @is_a_clone = false
+      @search_cache = {}
     end
 
     # Returns ElementBase descendent type or nil if none found
@@ -345,7 +346,7 @@ module Kitchen
     #   search results if the method or callable returns false
     # @return [ElementEnumerator]
     #
-    def search(*selector_or_xpath_args, only: nil, except: nil)
+    def search(*selector_or_xpath_args, only: nil, except: nil, reload: false)
       block_error_if(block_given?)
 
       ElementEnumerator.factory.build_within(
@@ -354,19 +355,29 @@ module Kitchen
           css_or_xpath: selector_or_xpath_args,
           only: only,
           except: except
-        )
+        ),
+        reload: reload
       )
     end
 
+    def raw_search(*selector_or_xpath_args, reload: false)
+      key = selector_or_xpath_args
+      @search_cache[key] = nil if reload || !config.enable_search_cache
+      # cache nil search results with a fake -1 value
+      @search_cache[key] ||= raw.search(*selector_or_xpath_args) || -1
+      @search_cache[key] == -1 ? nil : @search_cache[key]
+    end
+
     # Yields and returns the first child element that matches the provided
     # selector or XPath arguments.
     #
     # @param selector_or_xpath_args [Array<String>] CSS selectors or XPath arguments
+    # @param reload [Boolean] ignores cache if true
     # @yieldparam [Element] the matched XML element
     # @return [Element, nil] the matched XML element or nil if no match found
     #
-    def first(*selector_or_xpath_args)
-      search(*selector_or_xpath_args).first.tap do |element|
+    def first(*selector_or_xpath_args, reload: false)
+      search(*selector_or_xpath_args, reload: reload).first.tap do |element|
         yield(element) if block_given?
       end
     end
@@ -375,12 +386,13 @@ module Kitchen
     # selector or XPath arguments.
     #
     # @param selector_or_xpath_args [Array<String>] CSS selectors or XPath arguments
+    # @param reload [Boolean] ignores cache if true
     # @yieldparam [Element] the matched XML element
     # @raise [ElementNotFoundError] if no matching element is found
     # @return [Element] the matched XML element
     #
-    def first!(*selector_or_xpath_args)
-      search(*selector_or_xpath_args).first!.tap do |element|
+    def first!(*selector_or_xpath_args, reload: false)
+      search(*selector_or_xpath_args, reload: reload).first!.tap do |element|
         yield(element) if block_given?
       end
     end
@@ -694,7 +706,7 @@ module Kitchen
     #   Returns a pages enumerator
     def_delegators :as_enumerator, :pages, :chapters, :terms, :figures, :notes, :tables, :examples,
                    :metadatas, :non_introduction_pages, :units, :titles, :exercises, :references,
-                   :composite_pages
+                   :composite_pages, :composite_chapters
 
     # Returns this element as an enumerator (over only one element, itself)
     #

data/lib/kitchen/element_enumerator_base.rb

@@ -84,7 +84,30 @@ module Kitchen
     #
     def composite_pages(css_or_xpath=nil, only: nil, except: nil)
       block_error_if(block_given?)
-      chain_to(CompositePageElementEnumerator, css_or_xpath: css_or_xpath, only: only, except: except)
+      chain_to(CompositePageElementEnumerator,
+               css_or_xpath: css_or_xpath,
+               only: only,
+               except: except)
+    end
+
+    # Returns an enumerator that iterates through composite chapters 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.
+    # @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 composite_chapters(css_or_xpath=nil, only: nil, except: nil)
+      block_error_if(block_given?)
+      chain_to(CompositeChapterElementEnumerator,
+               css_or_xpath: css_or_xpath,
+               only: only,
+               except: except)
     end
 
     # Returns an enumerator that iterates through pages that arent the introduction page within the scope of this enumerator

data/lib/kitchen/element_enumerator_factory.rb

@@ -39,12 +39,22 @@ module Kitchen
     # @return [ElementEnumeratorBase] actually returns the concrete enumerator class
     #   given to the factory in its constructor.
     #
-    def build_within(enumerator_or_element, search_query: SearchQuery.new)
+    def build_within(enumerator_or_element, search_query: SearchQuery.new, reload: false)
       case enumerator_or_element
       when ElementBase
-        build_within_element(enumerator_or_element, search_query: search_query)
+        build_within_element(enumerator_or_element,
+                             search_query: search_query,
+                             reload: reload)
       when ElementEnumeratorBase
-        build_within_other_enumerator(enumerator_or_element, search_query: search_query)
+        if enumerator_class != ElementEnumerator && !search_query.expects_substitution?
+          raise "Query #{search_query} is missing the substitution character ('$') but " \
+                "is run with an enumerator #{enumerator_class.name} that has its own " \
+                "selectors for substitution."
+        end
+
+        build_within_other_enumerator(enumerator_or_element,
+                                      search_query: search_query,
+                                      reload: reload)
       end
     end
 
@@ -64,7 +74,7 @@ module Kitchen
 
     protected
 
-    def build_within_element(element, search_query:)
+    def build_within_element(element, search_query:, reload:)
       search_query.apply_default_css_or_xpath_and_normalize(default_css_or_xpath,
                                                             config: element.config)
 
@@ -77,7 +87,7 @@ module Kitchen
         # below, the counts are correct.
         element.uncount(search_query)
 
-        element.raw.search(*search_query.css_or_xpath).each do |sub_node|
+        element.raw_search(*search_query.css_or_xpath, reload: reload).each do |sub_node|
           sub_element = ElementFactory.build_from_node(
             node: sub_node,
             document: element.document,
@@ -105,13 +115,15 @@ module Kitchen
       end
     end
 
-    def build_within_other_enumerator(other_enumerator, search_query:)
+    def build_within_other_enumerator(other_enumerator, search_query:, reload:)
       # Return a new enumerator instance that internally iterates over `other_enumerator`
       # running a new enumerator for each element returned by that other enumerator.
       enumerator_class.new(search_query: search_query,
                            upstream_enumerator: other_enumerator) do |block|
         other_enumerator.each do |element|
-          build_within_element(element, search_query: search_query).each do |sub_element|
+          build_within_element(element,
+                               search_query: search_query,
+                               reload: reload).each do |sub_element|
             block.yield(sub_element)
           end
         end

data/lib/kitchen/exercise_element.rb

@@ -28,7 +28,7 @@ module Kitchen
     # @return ElementEnumerator
     #
     def problem
-      first("[data-type='problem']")
+      first("div[data-type='problem']")
     end
 
     # Returns the enumerator for solution.
@@ -36,7 +36,7 @@ module Kitchen
     # @return ElementEnumerator
     #
     def solution
-      first("[data-type='solution']")
+      first("div[data-type='solution']")
     end
   end
 end

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

@@ -29,9 +29,12 @@ 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

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

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/search_query.rb

@@ -82,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

@@ -7,7 +7,8 @@ module Kitchen
     attr_reader :name
 
     def self.named(name)
-      new(name) { |config| config.selectors.send(name) }
+      @instances ||= {}
+      @instances[name] ||= new(name) { |config| config.selectors.send(name) }
     end
 
     def initialize(name, &block)

data/lib/kitchen/version.rb

@@ -3,5 +3,5 @@
 # A library for modifying the structure of OpenStax book XML.
 #
 module Kitchen
-  VERSION = '4.1.0'
+  VERSION = '4.1.1'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: openstax_kitchen
 version: !ruby/object:Gem::Version
-  version: 4.1.0
+  version: 4.1.1
 platform: ruby
 authors:
 - JP Slavinsky
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-05-20 00:00:00.000000000 Z
+date: 2021-05-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -220,6 +220,7 @@ files:
 - lib/kitchen/chapter_element_enumerator.rb
 - lib/kitchen/clipboard.rb
 - lib/kitchen/composite_chapter_element.rb
+- lib/kitchen/composite_chapter_element_enumerator.rb
 - lib/kitchen/composite_page_element.rb
 - lib/kitchen/composite_page_element_enumerator.rb
 - lib/kitchen/config.rb
@@ -320,6 +321,7 @@ files:
 - lib/kitchen/page_element_enumerator.rb
 - lib/kitchen/pantry.rb
 - lib/kitchen/patches/nokogiri.rb
+- lib/kitchen/patches/nokogiri_profiling.rb
 - lib/kitchen/patches/renderable.rb
 - lib/kitchen/patches/string.rb
 - lib/kitchen/recipe.rb