Struct Machine 

pub struct Machine<G = Group> { /* private fields */ }

Available on crate feature pointer only.

State machine for identifying JSON Pointer matches against a JSON pattern.

Evaluating a JSON Pointer is primarily a structural question. With the exception of object member names, scalar values do not matter. Furthermore, once a “dead path” within the JSON text has been reached where no possible JSON Pointer can match deeper within that path, the structure underneath the “dead path” does not matter either (you have to return from the path before any further matches are possible). Consequently, a Machine only consumes the structural pattern of a JSON text that is needed for matching the JSON Pointers it knows about. Some examples of this pattern-based interface are:

1. The arr_begin and obj_begin methods can return a StructAction::Skip instruction indicating that the interior values contained within the array or object do not matter and must not be sent to the Machine.
2. The primitive method, which indicates a number token, literal token, or a string token that is not an object member name, does not accept a parameter for the actual token value.
3. The Machine has no methods for punctuation tokens or whitespace.

Examples

Test the JSON pattern corresponding to a nested array like [[false, true]] or [[0, 1]] against a JSON Pointer that matches the second element of the inner array.

use bufjson::pointer::{Group, Pointer, state::{Machine, StructAction}};

let pointer = Pointer::from_static("/0/1");
let group: Group = pointer.clone().into();
let mut mach = Machine::new(group, false); // Don't unescape object member names.

assert_eq!((StructAction::Enter, None), mach.arr_begin());  // Outer [
assert_eq!((StructAction::Enter, None), mach.arr_begin());  // Inner [
assert_eq!(None, mach.primitive());                         // Inner array element #1
assert_eq!(Some(&pointer), mach.primitive());               // Inner array element #2 matches!
assert_eq!(None, mach.arr_end());                           // Inner ]
assert_eq!(None, mach.arr_end());                           // Outer ]

Test the JSON pattern corresponding to a nested structure like {"foo":[],"bar":1} against a group of JSON Pointers that will match the "foo" member but not the"bar" member.

use bufjson::{
    lexical::fixed::Content,
    pointer::{Group, Pointer, state::{Machine, StructAction}},
};

let group = Group::from_pointers([Pointer::from_static("/foo"), Pointer::from_static("/baz")]);
let mut mach = Machine::new(group, false); // Don't unescape object member names.

assert_eq!((StructAction::Enter, None), mach.obj_begin());          // {
mach.member_name(Content::from_static(r#""foo""#));                 // "foo"
assert_eq!(                                                         // [ starts match!
    (StructAction::Skip, Some(&Pointer::from_static("/foo"))),
    mach.arr_begin()
);
assert_eq!(Some(&Pointer::from_static("/foo")), mach.arr_end());    // ] ends match
mach.member_name(Content::from_static(r#""bar""#));                 // "bar"
assert_eq!(None, mach.primitive());                                 // 1
assert_eq!(None, mach.obj_end());                                   // }

Unescape object member names, so that the JSON string literal "\u0066oo" matches “foo”, and test the JSON pattern corresponding to {"\u0066oo":{"bar":1}} against the JSON Pointer /foo/bar.

use bufjson::{
    lexical::fixed::Content,
    pointer::{Group, Pointer, state::{Machine, StructAction}},
};

let pointer = Pointer::from_static("/foo/bar");
let group: Group = pointer.clone().into();
let mut mach = Machine::new(group, true); // Expand escape sequences in object member names.

assert_eq!((StructAction::Enter, None), mach.obj_begin());              // Outer {
mach.member_name(Content::from_static(r#""\u0066oo""#));                // ~ "foo"
assert_eq!((StructAction::Enter, None), mach.obj_begin());              // Inner {
mach.member_name(Content::from_static(r#""bar""#));                     // "bar"
assert_eq!(Some(&Pointer::from_static("/foo/bar")), mach.primitive());  // 1
assert_eq!(None, mach.obj_end());                                       // Inner }
assert_eq!(None, mach.obj_end());                                       // Outer }

Implementations

impl<G: AsRef<Group>> Machine<G>

pub fn new(group: G, unescape: bool) -> Self

Returns a new Machine for evaluating a group of JSON Pointers against a JSON pattern.

The group parameter may be an owned Group; or it can be any other owned value that can provide a reference to a group, including &Group or a smart pointer like Arc<Group>. This allows a single compiled JSON Pointer group to be shared across multiple machines.

The unescape parameter controls whether object member name strings are unescaped. If false, escape sequences within member names are not expanded, so member names must match the JSON Pointers literally. If true, escape sequences are expanded. For example, with unescaping off, only the object member name "foo" will match /foo; but with unescaping on, /foo can be matched by a string literal containing escape sequences that expand to "foo", for example "\u0066oo" or "fo\u006f".

Examples

Create a machine with an owned pointer group and unescaping enabled.

use bufjson::pointer::{Group, Pointer, state::Machine};

let mach = Machine::new(Group::from_pointer(Pointer::from_static("/foo")), true);

Create a machine with a borrowed pointer group and unescaping disabled.

use bufjson::pointer::{Group, Pointer, state::Machine};

let group = Group::from_pointer(Pointer::from_static("/foo"));
let mach = Machine::new(&group, false);

pub fn arr_begin(&mut self) -> (StructAction, Option<&Pointer>)

Starts an array value.

The return value is a pair consisting of:

1. An action guiding the caller on how to handle the interior values contained by the array (whether to skip them or provide them).
2. An optional value indicating if the array being started matches a JSON Pointer (Some); or does not match any pointers (None).

Array elements, if any, can be provided using primitive for primitive values or by starting sub-arrays or sub-objects using arr_begin or obj_begin.

The array must be ended with arr_end.

Panics

Panics if a value is not allowed.

This can occur either because the last method called was obj_begin and an object member name has not been provided yet; or because the containing object or array received a value of StructAction::Skip when it was started by an earlier call to arr_begin or obj_begin.

pub fn arr_end(&mut self) -> Option<&Pointer>

Ends an array value previously started with arr_begin.

The return value indicates whether the array being ended matches a JSON Pointer (Some), or does not match any pointers (None).

Panics

Panics if the current structured value is not an array.

pub fn obj_begin(&mut self) -> (StructAction, Option<&Pointer>)

Starts an object value.

The return value is a pair consisting of:

1. An action guiding the caller on how to handle the interior values contained by the object (whether to skip them or provide them).
2. An optional value indicating if the object being started matches a JSON Pointer (Some); or does not match any pointers (None).

Object members, if any, can be provided by starting each member with a call to member_name and then providing the value using one of primitive for primitive values; arr_begin for array values; or obj_begin for object values.

The object must be ended with obj_end.

Panics

Panics if a value is not allowed.

This can occur either because the last method called was obj_begin and an object member name has not been provided yet; or because the containing object or array received a value of StructAction::Skip when it was started by an earlier call to arr_begin or obj_begin.

pub fn obj_end(&mut self) -> Option<&Pointer>

Ends an object value previously started with obj_begin.

The return value indicates whether the object being ended matches a JSON Pointer (Some) or does not match any pointers (None).

Panics

Panics if the current structured value is not an object.

pub fn member_name<C: Content>(&mut self, name: C)

Provides the next member name within an object.

Object members are name/value pairs. Within an object started with obj_begin, provide each pair by first calling member_name and then providing the value using one of arr_begin, obj_begin, or primitive.

Panics

Panics if a member name is not allowed in the current state. This can occur if the current structured value is not an object, or if the current value is an object but a member name was just provided so a value is now needed.

pub fn primitive(&mut self) -> Option<&Pointer>

Provides a primitive value.

The return value indicates whether the primitive matches a JSON Pointer (Some), or does not match any pointers (None).

Primitive values include numbers, strings, and the three JSON literals, null, true, and false.

This method does not accept an argument because the value of a primitive does not matter for the purposes of JSON Pointer evaluation. Whether or not a primitive matches a JSON Pointer is entirely dictated by the structure of the JSON before the value, i.e., the path of object member names and array indices that leads to the value.

Panics

Panics if a value is not allowed.

This can occur either because the last method called was obj_begin and an object member name has not been provided yet; or because the containing object or array received a value of StructAction::Skip when it was started by an earlier call to arr_begin or obj_begin.

pub fn into_inner(self) -> G

Returns the contained JSON Pointer group, consuming the self value.

Example

use bufjson::pointer::{Group, Pointer, state::Machine};

let group: Group = Pointer::from_static("/foo/bar").into();
let mut mach1 = Machine::new(group, false);
let _ = mach1.arr_begin();
let _ = mach1.arr_end();

let group = mach1.into_inner();
let mach2 = Machine::new(group, true);

Trait Implementations

impl<G: Debug> Debug for Machine<G>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.