Module: Qo::PublicApi

Includes:
Exceptions
Included in:
Qo
Defined in:
lib/qo/public_api.rb

Overview

The Public API consists of methods that should be openly accessible to the top level Qo namespace, and should not change. It should be used as the subject of Acceptance level tests for the library and should not have its externally facing methods renamed or moved under pain of a look of profound disappointment from the creator.

Author:

  • baweaver

Since:

  • 0.2.0

Instance Method Summary collapse

Instance Method Details

#and(*array_matchers, **keyword_matchers) ⇒ Proc[Any] Also known as: []

Creates an and type query matcher. All conditions in this type of matcher must pass to be considered a "match". It will short-circuit in the case of a false match.

Parameters:

  • *array_matchers (Array) —

    Array-like conditionals

  • **keyword_matchers (Hash) —

    Keyword style conditionals

Returns:

  • (Proc[Any]) —

    Any -> Bool # Given a target, will return if it "matches"

Since:

  • 0.2.0



26
27
28
 
# File 'lib/qo/public_api.rb', line 26

def and(*array_matchers, **keyword_matchers)
  create_matcher('and', array_matchers, keyword_matchers)
end

#case(value, &fn) ⇒ Any

Note:

I refer to the potential 2.6+ features currently being discussed here:

Similar to the common case statement of Ruby, except in that it behaves as if Array#=== and Hash#=== exist in the form of Qo matchers.

Examples:

Qo.case([1, 1]) { |m|
  m.when(Any, Any) { |a, b| a + b }
  m.else { |v| v }
}
=> 2

Parameters:

  • value (Any) —

    Value to match against

  • &fn (Proc) —

    Body of the matcher, as shown above

Returns:

  • (Any) —

    The result of calling a pattern match with a provided value

See Also:

  • Qo#match

Since:

  • 0.2.0



113
114
115
 
# File 'lib/qo/public_api.rb', line 113

def case(value, &fn)
  Qo::Matchers::PatternMatch.new(&fn).call(value)
end

#match(&fn) ⇒ Qo::PatternMatch

A pattern match will try and run all guard block style matchers in sequence until it finds one that "matches". Once found, it will pass the target into the associated matcher's block function.

Examples:

[1,2,3].map(&Qo.match { |m|
  m.when(:even?) { |v| v * 3 }
  m.else         { |v| v - 1 }
})
=> [0, 6, 2]

Parameters:

  • fn (Proc) —

    Body of the matcher, as shown in examples

Returns:

  • (Qo::PatternMatch) —

    A function awaiting a value to match against

Since:

  • 0.2.0



81
82
83
84
85
 
# File 'lib/qo/public_api.rb', line 81

def match(&fn)
  return proc { false } unless block_given?

  Qo::Matchers::PatternMatch.new(&fn)
end

#not(*array_matchers, **keyword_matchers) ⇒ Proc[Any]

Creates a not type query matcher. No conditions in this type of matcher should pass to be considered a "match". It will short-circuit in the case of a true match.

Parameters:

  • *array_matchers (Array) —

    Array-like conditionals

  • **keyword_matchers (Hash) —

    Keyword style conditionals

Returns:

  • (Proc[Any]) —

    Any -> Bool # Given a target, will return if it "matches"

Since:

  • 0.2.0



61
62
63
 
# File 'lib/qo/public_api.rb', line 61

def not(*array_matchers, **keyword_matchers)
  create_matcher('not', array_matchers, keyword_matchers)
end

#or(*array_matchers, **keyword_matchers) ⇒ Proc[Any]

Creates an or type query matcher. Any conditions in this type of matcher must pass to be considered a "match". It will short-circuit in the case of a true match.

Parameters:

  • *array_matchers (Array) —

    Array-like conditionals

  • **keyword_matchers (Hash) —

    Keyword style conditionals

Returns:

  • (Proc[Any]) —

    Any -> Bool # Given a target, will return if it "matches"

Since:

  • 0.2.0



45
46
47
 
# File 'lib/qo/public_api.rb', line 45

def or(*array_matchers, **keyword_matchers)
  create_matcher('or', array_matchers, keyword_matchers)
end