class Kitchen::ElementEnumeratorBase

Base class for all element enumerators

Attributes

search_query[R]

Return the selectors or other search strings that this enumerator uses to search through the document

@return [String]

Public Class Methods

new(size=nil, search_query: nil, upstream_enumerator: nil) click to toggle source

Creates a new instance

@param size [Integer, Proc] How to calculate the size lazily, either a value

or a callable object

@param search_query [String] the selectors or other search strings that this

enumerator uses to search through the document

@param upstream_enumerator [ElementEnumeratorBase] the enumerator to which this

enumerator is chained, used to access the upstream search history
Calls superclass method
# File lib/kitchen/element_enumerator_base.rb, line 25
def initialize(size=nil, search_query: nil, upstream_enumerator: nil)
  @search_query = search_query
  @upstream_enumerator = upstream_enumerator
  super(size)
end

Public Instance Methods

[](index) click to toggle source

Returns the element at the provided index

@param index [Integer] @return [Element]

# File lib/kitchen/element_enumerator_base.rb, line 415
def [](index)
  to_a[index]
end
chain_to(enumerator_class, default_css_or_xpath: nil, css_or_xpath: nil, only: nil, except: nil) click to toggle source

Returns an enumerator that iterates through elements within the scope of this enumerator

@param enumerator_class [ElementEnumeratorBase] the enumerator to use for the iteration @param default_css_or_xpath [String] the default CSS or xpath to use when iterating. Normally,

this value is provided by the `enumerator_class`, but that isn't always the case, e.g.
when that class is a generic `ElementEnumerator`.

@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
# File lib/kitchen/element_enumerator_base.rb, line 346
def chain_to(enumerator_class, default_css_or_xpath: nil, css_or_xpath: nil,
             only: nil, except: nil)
  block_error_if(block_given?)

  search_query = SearchQuery.new(
    css_or_xpath: css_or_xpath,
    only: only,
    except: except
  )

  if default_css_or_xpath
    search_query.apply_default_css_or_xpath_and_normalize(default_css_or_xpath)
  end

  enumerator_class.factory.build_within(self, search_query: search_query)
end
chapters(css_or_xpath=nil, only: nil, except: nil) click to toggle source

Returns an enumerator that iterates through 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
# File lib/kitchen/element_enumerator_base.rb, line 139
def chapters(css_or_xpath=nil, only: nil, except: nil)
  block_error_if(block_given?)
  chain_to(ChapterElementEnumerator, css_or_xpath: css_or_xpath, only: only, except: except)
end
composite_chapters(css_or_xpath=nil, only: nil, except: nil) click to toggle source

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
# File lib/kitchen/element_enumerator_base.rb, line 105
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
composite_pages(css_or_xpath=nil, only: nil, except: nil) click to toggle source

Returns an enumerator that iterates through composite pages 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
# File lib/kitchen/element_enumerator_base.rb, line 85
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)
end
copy(to: nil) click to toggle source

Makes a copy of the enumerated elements and places them on the specified clipboard.

@param to [Symbol, String, Clipboard, nil] the name of the clipboard (or a Clipboard

object) to copy to.  String values are converted to symbols.  If not provided, the
copies are placed on a new clipboard.

@return [Clipboard] the clipboard

# File lib/kitchen/element_enumerator_base.rb, line 396
def copy(to: nil)
  to ||= Clipboard.new
  each do |element|
    element.copy(to: to)
  end
  to
end
cut(to: nil) click to toggle source

Removes enumerated elements from their parent and places them on the specified clipboard

@param to [Symbol, String, Clipboard, nil] the name of the clipboard (or a Clipboard

object) to cut to. String values are converted to symbols. If not provided, the
elements are placed on a new clipboard.

@return [Clipboard] the clipboard

# File lib/kitchen/element_enumerator_base.rb, line 381
def cut(to: nil)
  to ||= Clipboard.new
  each do |element|
    element.cut(to: to)
  end
  to
end
examples(css_or_xpath=nil, only: nil, except: nil) click to toggle source

Returns an enumerator that iterates through examples 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
# File lib/kitchen/element_enumerator_base.rb, line 218
def examples(css_or_xpath=nil, only: nil, except: nil)
  block_error_if(block_given?)
  chain_to(ExampleElementEnumerator, css_or_xpath: css_or_xpath, only: only, except: except)
end
exercises(css_or_xpath=nil, only: nil, except: nil) click to toggle source

Returns an enumerator that iterates through exercises within the scope of this enumerator

@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
# File lib/kitchen/element_enumerator_base.rb, line 264
def exercises(css_or_xpath=nil, only: nil, except: nil)
  block_error_if(block_given?)
  chain_to(ExerciseElementEnumerator, css_or_xpath: css_or_xpath, only: only, except: except)
end
figures(css_or_xpath=nil, only: nil, except: nil) click to toggle source

Returns an enumerator that iterates through figures 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
# File lib/kitchen/element_enumerator_base.rb, line 167
def figures(css_or_xpath=nil, only: nil, except: nil)
  block_error_if(block_given?)
  chain_to(FigureElementEnumerator, css_or_xpath: css_or_xpath, only: only, except: except)
end
first!(missing_message: 'Could not return a first result') click to toggle source

Returns the first element in this enumerator

@param missing_message [String] the message to raise if a first element isn't available @raise [RecipeError] if a first element isn't available @return [Element]

# File lib/kitchen/element_enumerator_base.rb, line 369
def first!(missing_message: 'Could not return a first result')
  first || raise(RecipeError, "#{missing_message} matching #{search_history.latest} " \
                              "inside [#{search_history.upstream}]")
end
injected_questions(css_or_xpath=nil, only: nil, except: nil) click to toggle source

Returns an enumerator that iterates through injected questions 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
# File lib/kitchen/element_enumerator_base.rb, line 315
def injected_questions(css_or_xpath=nil, only: nil, except: nil)
  block_error_if(block_given?)
  chain_to(InjectedQuestionElementEnumerator,
           css_or_xpath: css_or_xpath, only: only, except: except)
end
metadatas(css_or_xpath=nil, only: nil, except: nil) click to toggle source

Returns an enumerator that iterates through metadata 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
# File lib/kitchen/element_enumerator_base.rb, line 281
def metadatas(css_or_xpath=nil, only: nil, except: nil)
  block_error_if(block_given?)
  chain_to(MetadataElementEnumerator, css_or_xpath: css_or_xpath, only: only, except: except)
end
non_introduction_pages(only: nil, except: nil) click to toggle source

Returns an enumerator that iterates through pages that arent the introduction page 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.
# File lib/kitchen/element_enumerator_base.rb, line 119
def non_introduction_pages(only: nil, except: nil)
  block_error_if(block_given?)
  chain_to(PageElementEnumerator,
           css_or_xpath: '$:not(.introduction)',
           only: only,
           except: except)
end
notes(css_or_xpath=nil, only: nil, except: nil) click to toggle source

Returns an enumerator that iterates through notes 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
# File lib/kitchen/element_enumerator_base.rb, line 184
def notes(css_or_xpath=nil, only: nil, except: nil)
  block_error_if(block_given?)
  chain_to(NoteElementEnumerator, css_or_xpath: css_or_xpath, only: only, except: except)
end
pages(css_or_xpath=nil, only: nil, except: nil) click to toggle source

Returns an enumerator that iterates through pages 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
# File lib/kitchen/element_enumerator_base.rb, line 68
def pages(css_or_xpath=nil, only: nil, except: nil)
  block_error_if(block_given?)
  chain_to(PageElementEnumerator, css_or_xpath: css_or_xpath, only: only, except: except)
end
references(css_or_xpath=nil) click to toggle source

Returns an enumerator that iterates through references 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.
# File lib/kitchen/element_enumerator_base.rb, line 250
def references(css_or_xpath=nil)
  block_error_if(block_given?)
  chain_to(ReferenceElementEnumerator, css_or_xpath: css_or_xpath)
end
search_history() click to toggle source

Return the search history based on this enumerator and any upstream enumerators

@return [SearchHistory]

# File lib/kitchen/element_enumerator_base.rb, line 35
def search_history
  (@upstream_enumerator&.search_history || SearchHistory.empty).add(@search_query)
end
solutions(css_or_xpath=nil, only: nil, except: nil) click to toggle source

Returns an enumerator that iterates through solutions 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
# File lib/kitchen/element_enumerator_base.rb, line 298
def solutions(css_or_xpath=nil, only: nil, except: nil)
  block_error_if(block_given?)
  chain_to(SolutionElementEnumerator, css_or_xpath: css_or_xpath, only: only, except: except)
end
tables(css_or_xpath=nil, only: nil, except: nil) click to toggle source

Returns an enumerator that iterates through tables 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
# File lib/kitchen/element_enumerator_base.rb, line 201
def tables(css_or_xpath=nil, only: nil, except: nil)
  block_error_if(block_given?)
  chain_to(TableElementEnumerator, css_or_xpath: css_or_xpath, only: only, except: except)
end
terms(css_or_xpath=nil, only: nil, except: nil) click to toggle source

Returns an enumerator that iterates through terms 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
# File lib/kitchen/element_enumerator_base.rb, line 51
def terms(css_or_xpath=nil, only: nil, except: nil)
  block_error_if(block_given?)
  chain_to(TermElementEnumerator, css_or_xpath: css_or_xpath, only: only, except: except)
end
titles(css_or_xpath=nil, only: nil, except: nil) click to toggle source

Returns an enumerator that iterates through titles 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
# File lib/kitchen/element_enumerator_base.rb, line 235
def titles(css_or_xpath=nil, only: nil, except: nil)
  block_error_if(block_given?)
  chain_to(ElementEnumerator,
           default_css_or_xpath: '[data-type="title"]',
           css_or_xpath: css_or_xpath,
           only: only,
           except: except)
end
to_s() click to toggle source

Returns a concatenation of to_s for all elements in the enumerator

@return [String]

# File lib/kitchen/element_enumerator_base.rb, line 423
def to_s
  map(&:to_s).join('')
end
trash() click to toggle source

Removes all matching elements from the document

# File lib/kitchen/element_enumerator_base.rb, line 406
def trash
  each(&:trash)
end
units(css_or_xpath=nil, only: nil, except: nil) click to toggle source

Returns an enumerator that iterates through units 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.
# File lib/kitchen/element_enumerator_base.rb, line 150
def units(css_or_xpath=nil, only: nil, except: nil)
  block_error_if(block_given?)
  chain_to(UnitElementEnumerator, css_or_xpath: css_or_xpath, only: only, except: except)
end