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



23
24
25
 
# File 'lib/qo/public_api.rb', line 23

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

#match(*args, &fn) ⇒ Qo::PatternMatchBlock, ...

"Curried" function that waits for a target, or evaluates immediately if given one.

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

Parameters:

  • fn (Proc) —

    If provided, the pattern match will become block-style, utilizing PatternMatchBlock instead. If any args are provided, the first will be treated as the target.

  • *args (Array[Any, *GuardBlockMatcher]) —

    Collection of matchers to run, potentially prefixed by a target object

Returns:

  • (Qo::PatternMatchBlock) —

    If a value is not provided, a block style pattern match will be returned that responds to proc coercion. It can be used for functions like map.

  • (Qo::PatternMatch) —

    If a value is not provided and no function is present, a PatternMatch will be returned, awaiting a value to match against.

  • (Any) —

    If a value is provided, matchers will attempt to call through on it, returning the result of the function.

Since:

  • 0.2.0



104
105
106
107
108
109
110
111
112
113
114
115
116
117
 
# File 'lib/qo/public_api.rb', line 104

def match(*args, &fn)
  if block_given?
    return args.empty? ?
      Qo::Matchers::PatternMatchBlock.new(&fn) :
      Qo::Matchers::PatternMatchBlock.new(&fn).call(args.first)
  end

  if args.first.is_a?(Qo::Matchers::GuardBlockMatcher)
    Qo::Matchers::PatternMatch.new(*args)
  else
    match_target, *qo_matchers = args
    Qo::Matchers::PatternMatch.new(*qo_matchers).call(match_target)
  end
end

#matcher(*array_matchers, **keyword_matchers, &fn) ⇒ Proc[Any] Also known as: m

Creates a Guard Block matcher.

A guard block matcher is used to guard a function from running unless the left-hand matcher passes. Once called with a value, it will either return [false, false] or [true, Any].

This wrapping is done to preserve intended false or nil responses, and is unwrapped with match below.

Parameters:

  • *array_matchers (Array) —

    varargs matchers

  • **keyword_matchers (Hash) —

    kwargs matchers

  • &fn (Proc) —

    Guarded function

Returns:

  • (Proc[Any]) —

    Any -> Proc[Any]

Since:

  • 0.2.0



71
72
73
 
# File 'lib/qo/public_api.rb', line 71

def matcher(*array_matchers, **keyword_matchers, &fn)
  Qo::Matchers::GuardBlockMatcher.new(*array_matchers, **keyword_matchers, &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



52
53
54
 
# File 'lib/qo/public_api.rb', line 52

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



39
40
41
 
# File 'lib/qo/public_api.rb', line 39

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