Class: Kitchen::ElementEnumeratorBase

Inherits:
Enumerator
  • Object
show all
Includes:
Mixins::BlockErrorIf
Defined in:
lib/kitchen/element_enumerator_base.rb

Overview

Base class for all element enumerators

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Mixins::BlockErrorIf

#block_error_if

Constructor Details

#initialize(size = nil, search_query: nil, upstream_enumerator: nil) ⇒ ElementEnumeratorBase

Creates a new instance

Parameters:

  • size (Integer, Proc) (defaults to: nil) —

    How to calculate the size lazily, either a value or a callable object

  • search_query (String) (defaults to: nil) —

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

  • upstream_enumerator (ElementEnumeratorBase) (defaults to: nil) —

    the enumerator to which this enumerator is chained, used to access the upstream search history



25
26
27
28
29
 
# 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

Instance Attribute Details

#search_query ⇒ String (readonly)

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

Returns:



14
15
16
 
# File 'lib/kitchen/element_enumerator_base.rb', line 14

def search_query
  @search_query
end

Instance Method Details

#[](index) ⇒ Element

Returns the element at the provided index

Parameters:

Returns:



468
469
470
 
# File 'lib/kitchen/element_enumerator_base.rb', line 468

def [](index)
  to_a[index]
end

#chain_to(enumerator_class, default_css_or_xpath: nil, css_or_xpath: nil, only: nil, except: nil) ⇒ Object

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

Parameters:

  • enumerator_class (ElementEnumeratorBase) —

    the enumerator to use for the iteration

  • default_css_or_xpath (String) (defaults to: nil) —

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

  • css_or_xpath (String) (defaults to: nil) —

    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.

  • only (Symbol, Callable) (defaults to: nil) —

    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

  • except (Symbol, Callable) (defaults to: nil) —

    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



399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
 
# File 'lib/kitchen/element_enumerator_base.rb', line 399

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) ⇒ Object

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

Parameters:

  • css_or_xpath (String) (defaults to: nil) —

    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.

  • only (Symbol, Callable) (defaults to: nil) —

    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

  • except (Symbol, Callable) (defaults to: nil) —

    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



139
140
141
142
 
# 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) ⇒ Object

Returns an enumerator that iterates through composite chapters within the scope of this enumerator

Parameters:

  • css_or_xpath (String) (defaults to: nil) —

    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.

  • only (Symbol, Callable) (defaults to: nil) —

    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

  • except (Symbol, Callable) (defaults to: nil) —

    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



105
106
107
108
109
110
111
 
# 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) ⇒ Object

Returns an enumerator that iterates through composite pages within the scope of this enumerator

Parameters:

  • css_or_xpath (String) (defaults to: nil) —

    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.

  • only (Symbol, Callable) (defaults to: nil) —

    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

  • except (Symbol, Callable) (defaults to: nil) —

    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



85
86
87
88
89
90
91
 
# 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) ⇒ Clipboard

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

Parameters:

  • to (Symbol, String, Clipboard, nil) (defaults to: 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.

Returns:



449
450
451
452
453
454
455
 
# File 'lib/kitchen/element_enumerator_base.rb', line 449

def copy(to: nil)
  to ||= Clipboard.new
  each do |element|
    element.copy(to: to)
  end
  to
end

#cut(to: nil) ⇒ Clipboard

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

Parameters:

  • to (Symbol, String, Clipboard, nil) (defaults to: 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.

Returns:



434
435
436
437
438
439
440
 
# File 'lib/kitchen/element_enumerator_base.rb', line 434

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) ⇒ Object

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

Parameters:

  • css_or_xpath (String) (defaults to: nil) —

    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.

  • only (Symbol, Callable) (defaults to: nil) —

    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

  • except (Symbol, Callable) (defaults to: nil) —

    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



218
219
220
221
 
# 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) ⇒ Object

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

Parameters:

  • only (Symbol, Callable) (defaults to: nil) —

    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

  • except (Symbol, Callable) (defaults to: nil) —

    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



264
265
266
267
 
# 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) ⇒ Object

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

Parameters:

  • css_or_xpath (String) (defaults to: nil) —

    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.

  • only (Symbol, Callable) (defaults to: nil) —

    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

  • except (Symbol, Callable) (defaults to: nil) —

    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



167
168
169
170
 
# 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') ⇒ Element

Returns the first element in this enumerator

Parameters:

  • missing_message (String) (defaults to: 'Could not return a first result') —

    the message to raise if a first element isn’t available

Returns:

Raises:

  • (RecipeError) —

    if a first element isn’t available



422
423
424
425
 
# File 'lib/kitchen/element_enumerator_base.rb', line 422

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_exercises(css_or_xpath = nil, only: nil, except: nil) ⇒ Object

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

Parameters:

  • css_or_xpath (String) (defaults to: nil) —

    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.

  • only (Symbol, Callable) (defaults to: nil) —

    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

  • except (Symbol, Callable) (defaults to: nil) —

    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



351
352
353
354
355
 
# File 'lib/kitchen/element_enumerator_base.rb', line 351

def injected_exercises(css_or_xpath=nil, only: nil, except: nil)
  block_error_if(block_given?)
  chain_to(InjectedExerciseElementEnumerator,
           css_or_xpath: css_or_xpath, only: only, except: except)
end

#injected_questions(css_or_xpath = nil, only: nil, except: nil) ⇒ Object

Returns an enumerator that iterates through injected questions within the scope of this enumerator

Parameters:

  • css_or_xpath (String) (defaults to: nil) —

    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.

  • only (Symbol, Callable) (defaults to: nil) —

    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

  • except (Symbol, Callable) (defaults to: nil) —

    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



315
316
317
318
319
 
# 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) ⇒ Object

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

Parameters:

  • css_or_xpath (String) (defaults to: nil) —

    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.

  • only (Symbol, Callable) (defaults to: nil) —

    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

  • except (Symbol, Callable) (defaults to: nil) —

    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



281
282
283
284
 
# 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) ⇒ Object

Returns an enumerator that iterates through pages that arent the introduction page within the scope of this enumerator

Parameters:

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



119
120
121
122
123
124
125
 
# 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) ⇒ Object

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

Parameters:

  • css_or_xpath (String) (defaults to: nil) —

    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.

  • only (Symbol, Callable) (defaults to: nil) —

    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

  • except (Symbol, Callable) (defaults to: nil) —

    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



184
185
186
187
 
# 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) ⇒ Object

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

Parameters:

  • css_or_xpath (String) (defaults to: nil) —

    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.

  • only (Symbol, Callable) (defaults to: nil) —

    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

  • except (Symbol, Callable) (defaults to: nil) —

    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



68
69
70
71
 
# 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) ⇒ Object

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

Parameters:

  • css_or_xpath (String) (defaults to: nil) —

    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.



250
251
252
253
 
# 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(css_or_xpath = nil, only: nil, except: nil) ⇒ Object

Returns an enumerator that iterates within the scope of this enumerator

Parameters:

  • css_or_xpath (String) (defaults to: nil) —

    additional selectors to further narrow the element iterated over



361
362
363
364
 
# File 'lib/kitchen/element_enumerator_base.rb', line 361

def search(css_or_xpath=nil, only: nil, except: nil)
  block_error_if(block_given?)
  chain_to(ElementEnumerator, css_or_xpath: css_or_xpath, only: only, except: except)
end

#search_history ⇒ SearchHistory

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

Returns:



35
36
37
 
# File 'lib/kitchen/element_enumerator_base.rb', line 35

def search_history
  (@upstream_enumerator&.search_history || SearchHistory.empty).add(@search_query)
end

#search_with(*enumerator_classes) ⇒ TypeCastingElementEnumerator

Searches for elements handled by a list of enumerator classes. All element that matches one of those enumerator classes are iterated over.

Parameters:

Returns:



372
373
374
375
376
377
378
379
380
381
 
# File 'lib/kitchen/element_enumerator_base.rb', line 372

def search_with(*enumerator_classes)
  block_error_if(block_given?)
  raise 'must supply at least one enumerator class' if enumerator_classes.empty?

  factory = enumerator_classes[0].factory
  enumerator_classes[1..-1].each do |enumerator_class|
    factory = factory.or_with(enumerator_class.factory)
  end
  factory.build_within(self)
end

#sections(css_or_xpath = nil, only: nil, except: nil) ⇒ Object

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

Parameters:

  • css_or_xpath (String) (defaults to: nil) —

    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.

  • only (Symbol, Callable) (defaults to: nil) —

    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

  • except (Symbol, Callable) (defaults to: nil) —

    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



333
334
335
336
337
 
# File 'lib/kitchen/element_enumerator_base.rb', line 333

def sections(css_or_xpath=nil, only: nil, except: nil)
  block_error_if(block_given?)
  chain_to(SectionElementEnumerator,
           css_or_xpath: css_or_xpath, only: only, except: except)
end

#solutions(css_or_xpath = nil, only: nil, except: nil) ⇒ Object

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

Parameters:

  • css_or_xpath (String) (defaults to: nil) —

    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.

  • only (Symbol, Callable) (defaults to: nil) —

    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

  • except (Symbol, Callable) (defaults to: nil) —

    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



298
299
300
301
 
# 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) ⇒ Object

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

Parameters:

  • css_or_xpath (String) (defaults to: nil) —

    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.

  • only (Symbol, Callable) (defaults to: nil) —

    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

  • except (Symbol, Callable) (defaults to: nil) —

    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



201
202
203
204
 
# 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) ⇒ Object

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

Parameters:

  • css_or_xpath (String) (defaults to: nil) —

    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.

  • only (Symbol, Callable) (defaults to: nil) —

    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

  • except (Symbol, Callable) (defaults to: nil) —

    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



51
52
53
54
 
# 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) ⇒ Object

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

Parameters:

  • css_or_xpath (String) (defaults to: nil) —

    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.

  • only (Symbol, Callable) (defaults to: nil) —

    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

  • except (Symbol, Callable) (defaults to: nil) —

    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



235
236
237
238
239
240
241
242
 
# 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 ⇒ String

Returns a concatenation of to_s for all elements in the enumerator

Returns:



476
477
478
 
# File 'lib/kitchen/element_enumerator_base.rb', line 476

def to_s
  map(&:to_s).join('')
end

#trash ⇒ Object

Removes all matching elements from the document



459
460
461
 
# File 'lib/kitchen/element_enumerator_base.rb', line 459

def trash
  each(&:trash)
end

#units(css_or_xpath = nil, only: nil, except: nil) ⇒ Object

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

Parameters:

  • css_or_xpath (String) (defaults to: nil) —

    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.



150
151
152
153
 
# 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