The PathToolkit keypath interpreter supports dot notation ('foo.bar.2') for object/array property lookup. It also supports relative paths, referencing other property values as a key within a path, function calls (with arguments), numbered placeholders within keypaths, wildcard paths, collections, and escaped keypaths. In addition, the operators in the interpreter may be configured if, for example, it's more convenient to use : instead of . as the separator.
PathToolkit is a constructor which is used to create PathToolkit instances. Each instance independently tracks its own configuration, so different instances may be created to process different path syntaxes.
var PathToolkit = require('path-toolkit-min');
var ptk = new PathToolkit( /* options */ );The constructor accepts an optional argument: an options object which can be used to override the default configuration at the point of instantiation. See setOptions documentation below for details - the constructor calls setOptions to process the options argument, if present.
var val1 = ptk.get(obj, path);
var val2 = ptk.get(obj, path, arg1, arg2,..., argN);If the keypath is invalid or does not exist within the target object, get returns undefined by default. This return value can be configured through options (see setDefaultReturnVal below) or by using the alternate method getWithDefault (see below). The get function will short circuit and return as soon as undefined is detected to prevent unexpected object reference exceptions.
Simple keypaths with dot notation and no special operators are optimally executed in standalone code for high performance.
var data = {
foo: {
bar: ['a','b','c']
}
};
ptk.get(data, 'foo.bar.2'); // 'c'Enclosing a path segment in [ ] is equivalent to surrounding it with the separator (. by default). Use of the separator character is optional adjacent to the [ ] container. The path a.b.c.d is equivalent to a[b]c[d].
var data = {
foo: {
bar: ['a','b','c']
}
};
ptk.get(data, 'foo.[bar].2'); // 'c'
ptk.get(data, 'foo[bar]2'); // 'c'
ptk.get(data, 'foo[bar][2]'); // 'c'Quotes, either single or double (' and ") may be used to mark a path segment as literal text - any special characters within the quoted text will be treated as plain text and will not be acted upon. Quoted path segments may appear as part of the main path string or within other containers.
var data = {
foo: {
bar: ['a','b','c'],
'abc': 'def',
'"abc"': 'xyz',
'one.two': 'three'
}
};
ptk.get(data, "foo['bar']2"); // 'c'
ptk.get(data, 'foo["bar"]2'); // 'c'
ptk.get(data, '"abc"'); // 'def'
ptk.get(data, '["abc"]'); // 'def'
ptk.get(data, '\\"abc\\"'); // 'xyz' (see escaped strings below)
ptk.get(data, '"one.two"'); // 'three'
ptk.get(data, '["one.two"]'); // 'three'Collections are implemented with ,.
var data = {
foo: {
bar: ['a','b','c'],
a: 'z',
b: 'y'
}
};
ptk.get(data, 'foo.bar.0,2'); // ['a','c']
ptk.get(data, 'foo.bar[0,2]'); // ['a','c']
ptk.get(data, 'foo.bar.a,b'); // ['z','y']The Collection separator creates an array at that point, and generally any token that follows will be an index or some function that operates on an array. The result will either be an array or a single value, depending on the evaluated result.
The "Each" separator is < by default. This can also be thought of as a "fork" operator. When this separator is used following an array, either an array created through the path using a Collection or an array that is evaluated from the data object, the token following < will be evaluated separately against each index of the array, and the results are accumulated into a new array. It is much like Array.map except that "map" executes a function against each index while the Each separator can return a property or any other PathToolkit evaluation from each index.
The Each separator will create a new array as a result of applying its token to each element of the prior array, so that token should be one that operates on each array element, not on the array as a whole. Multiple Each operations may be chained together.
var data = {
foo: {
bar: ['a','b','c']
},
people: [
{
id: 1,
name: 'John'
},
{
id: 2,
name: 'Jane'
},
{
id: 3,
name: 'Mephistopholes'
}
]
};
// The following two code sections produce equivalent results:
// 1.
// Intermediate step: ptk.get(data, 'foo.bar.0,2'); // ['a','c']
ptk.get(data, 'foo.bar.0,2<toUpperCase()'); // ['A','C'] - note that "toUpperCase" is a string function, not an array function
// 2
[data.foo.bar[0], data.foo.bar[2]].map(function(val){ return val.toUpperCase(); }); // ['A','C']
ptk.get(data, 'foo.bar.*'); // ['a','b','c']
ptk.get(data, 'foo.bar.*<toUpperCase()'); // ['A','B','C']
ptk.get(data, 'people.*<id'); // [1,2,3]
ptk.get(data, 'people.*<id,name'); // [ [1,'John'], [2,'Jane'], [3,'Mephistopholes'] ]Functions may be called with ( ).
var data = {
foo: {
bar: ['a','b','c']
}
};
ptk.get(data, 'foo.bar.2,0.sort()'); // ['a','c']
ptk.get(data, 'foo.bar.2,0.sort().0'); // 'a'Indirect property references are implemented with { }. Use of these can be confusing at times, and they don't work quite the same way as the javascript [ ] object property operator. A { } container is expected to contain a valid keypath. This keypath is interpreted from the context of the evaluated value at that point in the keypath, and the result is then interpreted as the property of the preceding path. Once the sub-keypath has been evaluated, the context is returned to the evaluation point before proceeding. Here are some examples to illustrate.
var data = {
foo: {
bar: ['a','b','c'],
a: 'one',
b: 'two'
}
};
ptk.get(data, 'foo.bar.0'); // 'a'
ptk.get(data, 'foo.a'); // 'one'
// Use the value at "foo.bar.0" as a property of "foo"...
ptk.get(data, 'foo{bar.0}'); // 'one'
ptk.get(data, 'foo{bar.0,2.sort().0}'); // 'one'Object context can be shifted upwards using prefixes ^ for 'parent' and ~ for 'root'. These prefixes apply in the base keypath as well as internal sub-keypaths.
var data = {
foo: {
bar: ['a','b','c'],
a: 'one',
b: 'two'
}
};
ptk.get(data, 'foo.bar.0'); // 'a'
ptk.get(data, 'foo.a'); // 'one'
ptk.get(data, 'foo.bar.^a'); // 'one'
ptk.get(data, 'foo.bar.~foo.bar.0'); // 'a'Numbered placeholders, indicated with %n, are supported as extra arguments to get. By numbering the placeholders according to their place in the args list, these values may be used in multiple places within the keypath. Using placeholders is another way to include string values which may contain reserved keypath characters since the placeholder values are not interpreted further; they are used as-is. The numbering sequence begins at 1.
var data = {
foo: {
bar: ['a','b','c'],
a: 'one',
b: 'two'
}
};
ptk.get(data, 'foo.bar.0'); // 'a'
ptk.get(data, 'foo.%1.%2', 'bar', (2-2)); // 'a'
ptk.get(data, 'foo{%1.0,%1.1', 'bar'); // ['one','two']
ptk.get(data, 'foo.bar.~foo.bar.0'); // 'a'Numbered context placeholders are indicated with @n, again as extra arguments to get. These placeholders are tied to arguments in the same way as the %n placeholders described above. However, context placeholders are different in that they allow references to objects external to the original data object being processed. They are called "context placeholders" because their use will replace the current object context with the referenced value instead. This provides a way to, for example, call functions defined in the programs variable scope or to pluck property names from other objects.
var data = {
foo: {
bar: ['a','b','c'],
a: 'one',
b: 'two',
xx: 'blah'
}
};
var fn = function(str){ return str+str; }
var other = {
prop: 'bar'
};
ptk.get(data, 'foo.bar.0'); // 'a'
ptk.get(data, 'foo.@1.prop', other); // 'bar'
ptk.get(data, 'foo{@1.prop}0', other); // 'a'
ptk.get(data, 'foo{@1(%2)}', fn, 'x'); // 'blah'Use of the numbered context placeholder is most likely to be helpful within the indirect property container ({ }) since that container creates a temporary context for evaluation, then returns to the original data context. In the above examples, the path 'foo.@1.prop' will replace the original data context for the remainder of the evaluation. The net result is exactly the same as finding other.prop directly, except with more work and obfuscation. Within the indirect property container, though, this mechanism can be used to create data transformations or to run externally defined functions.
Context tokens may be non-numeric, in which case the token will be used as a literal string. In all other cases in path-toolkit, when processing a keypath, each token is interpreted as a property or index of the current object context. The numbered context may be used to inject an external value into the system, but sometimes it isn't convenient to call .get() with extra arguments but instead to pass string arguments directly. When the context indicator (@) is used with a non-numeric token, the token is treated as a string literal and is not evaluated as a property of the current context. In some cases, it may be useful to quote the static string to guard against special characters in the string.
var data = {
foo: {
a: 'one',
b: '123.456',
c: 'three'
}
};
ptk.get(data, 'foo.a'); // 'one'
ptk.get(data, 'foo.a.indexOf(@1)', 'ne'); // 1
ptk.get(data, 'foo.a.indexOf(@ne)'); // 1
ptk.get(data, 'foo.b.indexOf(@".")'); // 3var val1 = ptk.get(obj, path, defaultReturnVal);
var val2 = ptk.get(obj, path, defaultReturnVal, arg1, arg2,..., argN);getWithDefault behaves exactly the same as get. When the resolved value is undefined, either because of an invalid path or because undefined is the value resolved by the path, the value in the defaultReturnVal argument will be returned in place of the current default return val configured for this path-toolkit instance.
var data = {
foo: {
a: {
one: 1,
two: 2
},
b: '123.456',
c: 'three'
}
};
// native javascript
// One way of avoiding an exception if 'foo.a' doesn't exist in 'data'.
// The results can be unclear from reading the code when some of the values may be boolean.
var x = data.foo && foo.a && foo.a.one;
// Another way that's more reliable and provides a default value.
// This method is more verbose, especially for deep objects. Also might be confused by booleans.
var y = (data.foo && data.foo.a) ? foo.a.one : 0;
// Using the new optional chaining operator to prevent exceptions, but there is no default value.
var z = data.foo?.a?.one;
// Path-toolkit
var value1 = ptk.getWithDefault(data, 'foo.a.one', 0); // returns 0 if any part of the path is invalid
var value2 = ptk.getWithDefault(data, 'foo.obj', {}); // returns an empty object if "foo.obj" doesn't existvar result1 = ptk.set(obj, path, newVal);
var result2 = ptk.set(obj, path, newVal, arg1, arg2,..., argN);Any property specified in a keypath may be set to a new value. The set function returns true if the set was successful, false if not. By default, only the final property in the keypath may be set - any intermediate properties must be defined and valid or set will fail. The final property does not need to exist prior to set, it will be created if necessary. This behavior is equivalent to setting an object property in plain javascript code.
This behavior may be changed using setOptions (see below), by enabling the "force" option (ptk.setForceOn();, see "Options" below). The "force" option will only change set behavior for simple dot-separated paths. The use of other mechanisms such as collections, indirect properties, etc. will prevent set from succeeding due to the difficulty in guessing how and what properties to create in some advanced scenarios. Note: If an intermediate value must be created, it will always be created as a plain object, never an array, even if the following path segment is an integer. Since all paths are Strings, it is impossible to guess whether the path segment "12345" is the integer 12,345 or the ZIP code "12345", for example, and it could be computationally expensive to create an array with only one defined index when that index is a very high number. Therefore, be aware that when "force" is enabled, the target object may acquire objects within in places where arrays are expected. If this is a risk in the program, it would be best to initialize these values before calling set or else leave "force" set to false.
var data = {
'foo': {}
};
data.foo.bar = 1; // valid
data.foo.a.b.c = 2; // NOT valid because "data.foo.a" is undefined, so "data.foo.a.b" throws an error
ptk.set(data, 'foo.bar', 1); // true
ptk.set(data, 'foo.a.b.c', 2); // false (ptk.set fails)
ptk.setOptions({force: true});
ptk.set(data, 'foo.a.b.c', 2); // true (ptk.set creates foo.a, foo.a.b, and foo.a.b.c, setting foo.a.b.c = 2)All keypaths that are valid for get will behave in the same way for set. One special case is worth noting: If the final path segment is a collection, then every property in that collection will be set to the new value.
var data = {
foo: {
bar: ['a','b','c']
}
};
ptk.set(data, 'foo.bar.0,1', 'xxx'); // true
ptk.get(data, 'foo.bar.0,1,2'); // ['xxx', 'xxx', 'c']var path = ptk.find(obj, val); // first found path to value
var allPaths = ptk.find(obj, val, 'all'); // all paths to valueDoes a seep scan through the data object, executing a === test on each node against the provided value. If the equals test returns true, the path is returned. By default, only one path is returned and the find function aborts as soon as it succeeds. If the last argument is 'all', find will scan the full object and return all paths with matching values.
find returns a path that is compliant with the current options. If a keypath segment includes special characters, it will be quoted with the current "singlequote" container character, and that quote will be escaped in the segment if it appears.
Note: Object keys are sorted in processing, so repeated calls to find should produce identical results.
Warning: find will not safely process objects with circular references, resulting in a stack overflow exception. For a safe, though slightly slower, alternative, see findSafe below.
var data = {
foo: {
bar: ['a','b','c']
},
xyz: 'b'
};
ptk.find(data, 'b'); // 'foo.bar.1'
ptk.find(data, 'b', 'all'); // ['foo.bar.1','xyz']var path = ptk.find(obj, val); // first found path to value
var allPaths = ptk.findSafe(obj, val, 'all'); // all paths to valueDoes a seep scan through the data object, executing a === test on each node against the provided value. If the equals test returns true, the path is returned. By default, only one path is returned and the findSafe function aborts as soon as it succeeds. If the last argument is 'all', findSafe will scan the full object and return all paths with matching values.
When scanning an object, each node is tested for circular references. If such a reference is found, findSafe will throw an Error with the text "Circular object provided." and will immediately halt. Code using this method should wrap findSafe inside a try-catch.
findSafe returns a path that is compliant with the current options. If a keypath segment includes special characters, it will be quoted with the current "singlequote" container character, and that quote will be escaped in the segment if it appears.
Note: Object keys are sorted in processing, so repeated calls to findSafe should produce identical results.
var data = {
foo: {
bar: ['a','b','c']
},
xyz: 'b'
};
data.foo.bar[3] = data.foo; // a circular reference is created
ptk.find(data, 'b', 'all'); // results in a stack overflow exception, program will halt
ptk.findSafe(data, 'b', 'all'); // Throws an Errorvar str = 'John Q. Doe';
var escapedPathSegment = ptk.escape(str);
ptk.get(data, ['people', escapedPathSegment, 'address'].join('.'));The path interpreter supports escaped characters using backslash (\). This is another way to deal with data where operators may be present in the data object as property names. For example, an object that uses full names as keys may include . or an object using phone numbers as keys may include ( ). By pre-processing the path segment with escape, these operators will all be prepended with \, making the path safe for execution.
Important: Do not execute escape on your full keypath, since it will escape all the separators (.), turning your keypath into a single property name. This function is meant to be executed on only a single keypath segment, and is most useful when building a keypath dynamically using unknown values.
The escape function will obey whatever characters are currently defined as operators at the time of execution. If using non-standard operators, simply call setOptions before executing escape to make sure escape is looking for the correct operators.
var bool = ptk.isValid(keypath);Returns a boolean value: true if the keypath is syntactically valid, false if not. This isValid does not take a data object; it does not test whether the keypath exists in an object. It merely evaluates the syntax and indicates if it is improper. This can help when dynamically building a keypath or using complex nested structures. isValid will identify mismatched containers and a keypath that ends in \, with no characters following to escape.
var tokens = ptk.getTokens(keypath);Returns the tokenized object representing the keypath. This tokens object may be used when calling get or set in place of a string keypath. When used, those functions will skip the tokenizing step. getTokens may be used to pre-compile a keypath for later use, making the get and set functions slightly more efficient for some keypaths. If the keypath is invalid, undefined is returned.
The PathToolkit library's path interpreter can be customized in many ways. Behavior like caching and whether set will create intermediate properties as well as most special characters may be customized. There are a variety of ways to set these options, ranging from the all-at-once setOptions function to individual "turn this option on or off" and "change this particular character to a different character" functions.
Options are stored locally within each PathToolkit instance, so multiple instances may carry different options.
Any time the path syntax is altered through any of the following functions, the PathToolkit instance's local cache is cleared so that paths will be re-evaluated with the new syntax.
ptk.resetOptions();Resets all options to their default state.
Clears the cache to force all paths to be re-evaluated with the new path syntax.
The default options are as follows:
{
cache: true,
force: false,
simple: false,
defaultReturnVal: undefined,
separators: {
'.': {
'exec': 'property'
},
',': {
'exec': 'collection'
},
'<': {
'exec': 'each'
}
},
prefixes: {
'^': {
'exec': 'parent'
},
'~': {
'exec': 'root'
},
'%': {
'exec': 'placeholder'
},
'@': {
'exec': 'context'
}
},
containers: {
'[': {
'closer': ']',
'exec': 'property'
},
'\'': {
'closer': '\'',
'exec': 'singlequote'
},
'"': {
'closer': '"',
'exec': 'doublequote'
},
'(': {
'closer': ')',
'exec': 'call'
},
'{': {
'closer': '}',
'exec': 'evalProperty'
}
}
}ptk.setCache(true); // Enables cache. Also accepts 'on', 'yes', 'true'; not case-sensitive.
// Any non-string value that javascript considers "truthy" will enable cache.
ptk.setCache(false); // Disables cache. Any non-string value considered "falsy" will disable cache.
ptk.setCacheOn(); // enables cache
ptk.setCacheOff(); // disables cacheFor any path beyond the simple case (see get above), a tokenizing function parses the path before it is resolved. By default, the results of the tokenizing function are cached so repeated calls for the same path string can skip the tokenizing step. If cache is disabled, any new path evaluation will execute the tokenizing routine, even if the path was stored in cache prior to cache being disabled. Any new paths processed while cache is disabled will not be stored in cache.
Each PathToolkit instance carries its own cache.
ptk.setForce(true); // Enables forced property creation. Also accepts 'on', 'yes', 'true'; not case-sensitive.
// Any non-string value that javascript considers "truthy" will enable this option.
ptk.setForce(false); // Disables forced property creation. Any non-string value considered "falsy" will disable.
ptk.setForceOn(); // enables forced property creation
ptk.setForceOff(); // disables forced property creationThis option dictates whether the set function will create intermediate properties as needed to set a value at the end of a path. This feature is described above in the documentation for set.
ptk.setSimple(true, separator); // Enables simple path syntax. Also accepts 'on', 'yes', 'true'; not case-sensitive.
// Any non-string value that javascript considers "truthy" will enable this option.
ptk.setSimple(false); // Disables simple path syntax. Any non-string value considered "falsy" will disable.
// SEE NOTE BELOW
ptk.setSimpleOn(separator); // enables simple path syntax
ptk.setSimpleOff(); // disables simple path syntax; SEE NOTE BELOWThe "separator" argument is optional. If not provided, the default property separator "." will be used.
In many cases, the more advanced PathToolkit features are not necessary and only simple, character-separated paths will be processed. It can be convenient to disable all the unnecessary special characters to avoid escaping them if they occur as property names in the paths. The "simple" option removes all special characters from the path syntax except for a single separator character. That character is "." by default, but it can be set to any other character as needed ("/", for example). Any character is allowed as long as it is only one character.
NOTE: When "simple" mode is disabled, the full set of default characters will be restored. Calling setSimpleOff() is nearly equivalent to calling resetOptions() except that the "cache" and "force" options are not affected by setSimpleOff(). Also, the property separator character will be reset to the default "." character when simple mode is disabled. The same is true for setSimple(false).
Clears the cache to force all paths to be re-evaluated with the new path syntax.
ptk.setDefaultReturnVal(0); // sets the default return value to zero
ptk.setDefaultReturnVal({}); // sets the default return value to an empty objectReplaces the default value returned by get when that method resolves to a value that is undefined.
ptk.setSeparatorProperty('/'); // 'one.two.three' -> 'one/two/three'Removes the existing character used for this purpose and sets the new character instead. The code above is merely an example: any new character is allowed as long as it is only one character.
Clears the cache to force all paths to be re-evaluated with the new path syntax.
Throws error if: argument is missing or empty string; argument is more than one character long; argument is already in use for some other purpose in the path syntax.
ptk.setSeparatorCollection('/'); // 'one.two,three.four' -> 'one.two/three.four'Removes the existing character used for this purpose and sets the new character instead. The code above is merely an example: any new character is allowed as long as it is only one character.
Clears the cache to force all paths to be re-evaluated with the new path syntax.
Throws error if: argument is missing or empty string; argument is more than one character long; argument is already in use for some other purpose in the path syntax.
ptk.setPrefixParent('!'); // 'one{^two.three}four' -> 'one{!two.three}four'Removes the existing character used for this purpose and sets the new character instead. The code above is merely an example: any new character is allowed as long as it is only one character.
Clears the cache to force all paths to be re-evaluated with the new path syntax.
Throws error if: argument is missing or empty string; argument is more than one character long; argument is already in use for some other purpose in the path syntax.
ptk.setPrefixRoot('#'); // 'one{~two.three}four' -> 'one{#two.three}four'Removes the existing character used for this purpose and sets the new character instead. The code above is merely an example: any new character is allowed as long as it is only one character.
Clears the cache to force all paths to be re-evaluated with the new path syntax.
Throws error if: argument is missing or empty string; argument is more than one character long; argument is already in use for some other purpose in the path syntax.
ptk.setPrefixPlaceholder('&'); // 'one.%1.three' -> 'one.&1.three'Removes the existing character used for this purpose and sets the new character instead. The code above is merely an example: any new character is allowed as long as it is only one character.
Clears the cache to force all paths to be re-evaluated with the new path syntax.
Throws error if: argument is missing or empty string; argument is more than one character long; argument is already in use for some other purpose in the path syntax.
ptk.setPrefixContext('+'); // 'one.@1()' -> 'one.+1()'Removes the existing character used for this purpose and sets the new character instead. The code above is merely an example: any new character is allowed as long as it is only one character.
Clears the cache to force all paths to be re-evaluated with the new path syntax.
Throws error if: argument is missing or empty string; argument is more than one character long; argument is already in use for some other purpose in the path syntax.
ptk.setContainerProperty('^', '>'); // 'one[two]three' -> 'one^two>three'Container characters are set in pairs. The first argument is the "opener" and the second is the "closer". In most cases, paths are easier to read if the arguments are different (e.g. "[" and "]"). If the opener and closer are different, it's also possible to nest the container ("a[b[c]]d". For cases like quotes, where the opener typically is the same as the closer, quotes cannot be nested directly.
Both arguments are required.
Removes the existing characters used for this purpose and sets the new characters instead. The code above is merely an example: any new characters are allowed as long as each argument is only one character long.
Clears the cache to force all paths to be re-evaluated with the new path syntax.
Throws error if: argument is missing or empty string; argument is more than one character long; argument is already in use for some other purpose in the path syntax.
ptk.setContainerSinglequote('|', '|'); // "one['two']three" -> "one[|two|]three"Container characters are set in pairs. The first argument is the "opener" and the second is the "closer". In most cases, paths are easier to read if the arguments are different (e.g. "[" and "]"). If the opener and closer are different, it's also possible to nest the container ("a[b[c]]d"). For cases like quotes, where the opener typically is the same as the closer, quotes cannot be nested directly.
Both arguments are required.
Removes the existing characters used for this purpose and sets the new characters instead. The code above is merely an example: any new characters are allowed as long as each argument is only one character long.
Clears the cache to force all paths to be re-evaluated with the new path syntax.
Throws error if: argument is missing or empty string; argument is more than one character long; argument is already in use for some other purpose in the path syntax.
ptk.setContainerDoublequote('|', '|'); // 'one["two"]three' -> 'one[|two|]three'Container characters are set in pairs. The first argument is the "opener" and the second is the "closer". In most cases, paths are easier to read if the arguments are different (e.g. "[" and "]"). If the opener and closer are different, it's also possible to nest the container ("a[b[c]]d". For cases like quotes, where the opener typically is the same as the closer, quotes cannot be nested directly.
Both arguments are required.
Removes the existing characters used for this purpose and sets the new characters instead. The code above is merely an example: any new characters are allowed as long as each argument is only one character long.
Clears the cache to force all paths to be re-evaluated with the new path syntax.
Throws error if: argument is missing or empty string; argument is more than one character long; argument is already in use for some other purpose in the path syntax.
ptk.setContainerCall('^', '>'); // 'one.fn()' -> 'one.fn^>'Container characters are set in pairs. The first argument is the "opener" and the second is the "closer". In most cases, paths are easier to read if the arguments are different (e.g. "[" and "]"). If the opener and closer are different, it's also possible to nest the container ("a[b[c]]d". For cases like quotes, where the opener typically is the same as the closer, quotes cannot be nested directly.
Both arguments are required.
Removes the existing characters used for this purpose and sets the new characters instead. The code above is merely an example: any new characters are allowed as long as each argument is only one character long.
Clears the cache to force all paths to be re-evaluated with the new path syntax.
Throws error if: argument is missing or empty string; argument is more than one character long; argument is already in use for some other purpose in the path syntax.
ptk.setContainerEvalProperty('^', '>'); // 'one{two.three}four' -> 'one^two.three>four'Container characters are set in pairs. The first argument is the "opener" and the second is the "closer". In most cases, paths are easier to read if the arguments are different (e.g. "[" and "]"). If the opener and closer are different, it's also possible to nest the container ("a[b[c]]d". For cases like quotes, where the opener typically is the same as the closer, quotes cannot be nested directly.
Both arguments are required.
Removes the existing characters used for this purpose and sets the new characters instead. The code above is merely an example: any new characters are allowed as long as each argument is only one character long.
Clears the cache to force all paths to be re-evaluated with the new path syntax.
Throws error if: argument is missing or empty string; argument is more than one character long; argument is already in use for some other purpose in the path syntax.
ptk.setOptions(opts);Takes an options object as an argument and can set one, some, or all options at once. The operator characters come in three categories: separators, prefixes, and containers. Any or all of these may be set when calling setOptions, the function will simply replace the existing group with whatever is found in the provided options object. If an option (like "cache" or "force") or a character group (like "separators") is not present in the options argument, that option or character group will not be changed.
// This command is equivalent to "setSimpleOn('/')"
ptk.setOptions({
// "cache" and "force" are not altered
simple: true,
separators: {
'/': {
exec: 'property'
}
// the "collection" character is removed from the syntax
},
// "prefixes" and "containers" are erased, these characters are removed from the syntax
prefixes: {},
containers: {}
});
// Equivalent to "setCacheOff()"
ptk.setOptions({ cache: false });If any of the character groups is set using setOptions, the cache is cleared to force all paths to be re-evaluated with the new path syntax.