Class: Jamespath::VM

Inherits:
Object
  • Object
show all
Defined in:
lib/jamespath/vm.rb

Overview

The virtual machine that interprets compiled expressions and searches for objects. The VM implements a handful of instructions that can be used to navigate through an object structure.

# VM Overview

The VM iterates over the instructions attempting to navigate through the given object. As instructions are evaluated, the “object” is tracked and replaced as each selection is made. The result of a search is the object value after evaluating all instructions.

The VM understands “hash-like” and “array-like” objects. “Array-like” objects are defined as any object that subclasses Array. “Hash-like” objects are defined as either Hash or Struct objects.

## Instruction list

### ‘:get_key <key>`

Gets a “key” from the hash-like object on the stack. If the object is not hash-like, this instruction sets the object value to nil.

### ‘:get_idx <idx>`

Gets an object at index “idx” from the array-like object on the stack. If the object is not array-like, this instruction sets the object value to nil. “idx” must be a number, but can be negative. Negative values index from the end of the array, where -1 is the last value.

### ‘:get_key_all`

Gets all values from the hash-like object value. If the object is not hash-like, this instruction sets the object value to nil.

### ‘:get_idx_all`

Gets all items from an array-like object. If the object is hash-like, the object is set to the keys of the hash-like structure. If the object is not array-like or hash-like, this instruction sets the object value to nil.

### ‘:flatten_list`

Flattens a list of subarrays into a single array. If the object is not array-like, this instruction sets the object value to an empty array.

### ‘:ret_if_match`

Breaks from parsing instructions if the object value is non-nil. If the object is nil, this instruction should reset the object value to the original object that was being searched.

Defined Under Namespace

Classes: ArrayGroup

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(instructions) ⇒ VM

Creates a virtual machine that can evaluate a set of instructions. Use the Parser to turn an expression into a set of instructions.

Examples:

VM for expression “foo.bar”

vm = VM.new [
 [:get_key, 'foo'],
 [:get_key, 'bar'],
 [:get_idx, -1]
]
vm.search(foo: {bar: [1, 2, 3]}) #=> 3

Parameters:

  • instructions (Array(Symbol, Object)) —

    a list of instructions to execute.

See Also:



76
77
78
 
# File 'lib/jamespath/vm.rb', line 76

def initialize(instructions)
  @instructions = instructions
end

Instance Attribute Details

#instructions ⇒ Array(Symbol, Object) (readonly)

Returns the instructions the VM executes.

Returns:

  • (Array(Symbol, Object)) —

    the instructions the VM executes.



61
62
63
 
# File 'lib/jamespath/vm.rb', line 61

def instructions
  @instructions
end

Instance Method Details

#search(object_to_search) ⇒ Object?

Searches for the compile expression against the object passed in.

Parameters:

  • object_to_search (Object) —

    the object to search for results.

Returns:

  • (Object) —

    the object, or list of objects, that match the expression.

  • (nil) —

    if no objects matched the expression



84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
 
# File 'lib/jamespath/vm.rb', line 84

def search(object_to_search)
  object = object_to_search
  @instructions.each do |instruction|
    if instruction.first == :ret_if_match
      if object
        break # short-circuit or expression
      else
        object = object_to_search  # reset search
      end
    else
      object = send(instruction[0], object, instruction[1])
    end
  end

  object
end