Class: Mongory::Matchers::AbstractMatcher Abstract

Inherits:
Object
  • Object
show all
Includes:
Utils
Defined in:
lib/mongory/matchers/abstract_matcher.rb

Overview

This class is abstract.

Subclasses must implement #match to define their matching logic

AbstractMatcher is the base class for all matchers in Mongory.

It defines a common interface (#match?) and provides shared behavior such as condition storage, optional conversion handling, and debugging output.

Each matcher is responsible for evaluating a specific type of condition against a record value. The base class provides infrastructure for:

  • Condition validation
  • Value conversion
  • Debug output
  • Proc caching

Examples:

Basic matcher implementation

class MyMatcher < AbstractMatcher
  def match(record)
    record == @condition
  end
end

Using a matcher

matcher = MyMatcher.build(42)
matcher.match?(42)  #=> true
matcher.match?(43)  #=> false

See Also:

Constant Summary collapse

KEY_NOT_FOUND =

This constant is part of a private API. You should avoid using this constant if possible, as it may be removed or be changed in the future.

Sentinel value used to represent missing keys when traversing nested hashes. This is used instead of nil to distinguish between missing keys and nil values.

SingletonBuilder.new('KEY_NOT_FOUND')

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Utils

included, included_classes, #is_blank?, #is_present?

Constructor Details

#initialize(condition, context: Context.new) ⇒ AbstractMatcher

Initializes the matcher with a raw condition.

Parameters:

  • condition (Object) —

    the condition to match against

  • context (Context) (defaults to: Context.new) —

    the query context containing configuration



76
77
78
79
80
81
 
# File 'lib/mongory/matchers/abstract_matcher.rb', line 76

def initialize(condition, context: Context.new)
  @condition = condition
  @context = context

  check_validity!
end

Instance Attribute Details

#condition ⇒ Object (readonly)

Returns the raw condition this matcher was initialized with.

Returns:

  • (Object) —

    the raw condition this matcher was initialized with



58
59
60
 
# File 'lib/mongory/matchers/abstract_matcher.rb', line 58

def condition
  @condition
end

#context ⇒ Context (readonly)

Returns the query context containing configuration and current record.

Returns:

  • (Context) —

    the query context containing configuration and current record



61
62
63
 
# File 'lib/mongory/matchers/abstract_matcher.rb', line 61

def context
  @context
end

Class Method Details

.define_matcher(name) { ... } ⇒ void

This method returns an undefined value.

Defines a lazily-evaluated matcher accessor with instance-level caching. This is used to create cached accessors for submatcher instances.

Examples:

define_matcher(:array_matcher) do
  ArrayMatcher.build(@condition)
end

Parameters:

  • name (Symbol) —

    the name of the matcher (e.g., :collection)

Yields:

  • the block that constructs the matcher instance



53
54
55
 
# File 'lib/mongory/matchers/abstract_matcher.rb', line 53

def self.define_matcher(name, &block)
  define_instance_cache_method(:"#{name}_matcher", &block)
end

Instance Method Details

#cached_proc ⇒ Proc Also known as: to_proc

Converts the matcher into a Proc that can be used for matching. The Proc is cached for better performance.

Returns:

  • (Proc) —

    a Proc that can be used to match records



98
99
100
 
# File 'lib/mongory/matchers/abstract_matcher.rb', line 98

def cached_proc
  @cached_proc ||= raw_proc
end

#check_validity! ⇒ void

This method is abstract.

This method returns an undefined value.

Validates the condition (no-op by default). Override in subclasses to raise error if invalid.

Raises:

  • (TypeError) —

    if the condition is invalid



152
 
# File 'lib/mongory/matchers/abstract_matcher.rb', line 152

def check_validity!; end

#debug_proc ⇒ Proc

Creates a debug-enabled version of the matcher proc. This version includes tracing and error handling.

Returns:

  • (Proc) —

    a debug-enabled version of the matcher proc



108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
 
# File 'lib/mongory/matchers/abstract_matcher.rb', line 108

def debug_proc
  return @debug_proc if defined?(@debug_proc)

  raw_proc = raw_proc()
  @debug_proc = Proc.new do |record|
    result = nil

    Debugger.instance.with_indent do
      result = begin
        raw_proc.call(record)
      rescue StandardError => e
        e
      end

      debug_display(record, result)
    end

    result.is_a?(Exception) ? false : result
  end
end

#match(record) ⇒ Boolean

This method is abstract.

Performs the actual match logic. Subclasses must override this method.

Parameters:

  • record (Object) —

    the input record to test

Returns:

  • (Boolean) —

    whether the record matches the condition



144
 
# File 'lib/mongory/matchers/abstract_matcher.rb', line 144

def match(record); end

#match?(record) ⇒ Boolean

Matches the given record against the condition. This method handles error cases and uses the cached proc for performance.

Parameters:

  • record (Object) —

    the input record

Returns:

  • (Boolean) —

    whether the record matches the condition



88
89
90
91
92
 
# File 'lib/mongory/matchers/abstract_matcher.rb', line 88

def match?(record)
  to_proc.call(record)
rescue StandardError
  false
end

#raw_proc ⇒ Proc

Creates a raw Proc from the match method. This is used internally by to_proc and can be overridden by subclasses to provide custom matching behavior.

Returns:

  • (Proc) —

    the raw Proc implementation of the match method



134
135
136
 
# File 'lib/mongory/matchers/abstract_matcher.rb', line 134

def raw_proc
  method(:match).to_proc
end

#render_tree(prefix = '', is_last: true) ⇒ void

This method returns an undefined value.

Recursively prints the matcher structure into a formatted tree. Supports indentation and branching layout using prefix symbols.

Parameters:

  • prefix (String) (defaults to: '') —

    tree prefix (indentation + lines)

  • is_last (Boolean) (defaults to: true) —

    whether this node is the last among siblings



160
161
162
 
# File 'lib/mongory/matchers/abstract_matcher.rb', line 160

def render_tree(prefix = '', is_last: true)
  puts "#{prefix}#{is_last ? '└─ ' : '├─ '}#{tree_title}\n"
end

#uniq_key ⇒ String

Returns a unique key representing this matcher instance. Used for deduplication in multi-matchers.

Returns:

  • (String) —

    a unique key for this matcher instance

See Also:

  • AbstractMultiMatcher#matchers


68
69
70
 
# File 'lib/mongory/matchers/abstract_matcher.rb', line 68

def uniq_key
  "#{self.class}:condition:#{@condition.class}:#{@condition}"
end