propref-parser
- Usage
- Accessing nested properties
- API
- Options
- Examples
- Custom Key Patterns
- Dynamic Property Values
Usage
var PropRefParser = ; var props = foo: true bar: '@{foo}'; // instanciate new PropRefParservar parser = props opts; parser;// -> true
Accessing nested properties
Nested properties are supported through the 'getter' option which allows you to define a custom getter function –used to get the value for a referenced property key.
For dot-notation, we recommend using the getobject package to define your custom getter:
var PropRefParser = ;var getobject = ; var props = foo: true bar: '@{foo}' // nested and relative keys nested: foo: false df: '@{foo}' // relative rel: '@{-.foo}' // relative up: '@{--.foo}' // move up abs: '@{.foo}' // absolute ; var options = splitChar: '.' { return getobject; } ; var parser = props options; parser;// -> true parser;// -> {// foo: true,// nested: {// foo: false,// df: false,// rel: false,// baz: true// }// }
The example above also shows support for relative key paths. How nested and relative key paths are formatted can be controlled using the splitChar and upLvlChar options.
Constructor arguments
props
(Object) required
Plain properties object, with cross-referencing property values.
options
(Object) [{}]
See Options below for documentation and default values.
API
.parse( value )
Resolves property references in given value.
.get( key )
gets resolved value for given property key
.keyJoin( ..keys )
creates keypath by joining given property keys and resolving relative and absolute patterns.
.keyResolve( ..keys )
creates keypath by joining given property keys,in the context of options.keyBase
(will be joined in front of other given keys).
Options
options.getter
(Function) required
Custom getter function used to return values for referenced property keys.
Signature: function( props, key, options ) { /*...*/ }
- props
context properties used to resolve given key
- key
absolute key to resolve
- options
options for PropRefParser instance
options.parser
(Function) [null]
Custom parser function, ran whenever the PropRefParser is parsing a property value.
Signature: funcion( props, value, options ) { /* ... */
- props
context properties used to resolve given key
- value
value that is being parsed (with property refernces resolved!)
- options
options for PropRefParser instance
Important: Referenced property values are already resolved in the value passed as second argument to custom parser functions.
options.refPattern
(String | RegExp) [ /@{\s*$&\s*}/ ]
Pattern used to recognize property references in string values.
This option needs to include the $&
string, used as placeholder for referenced property keys.
options.keyPattern
(String | RegExp) [ /[a-zA-Z0-9_]/ ]
Pattern used to recognize property keys in property references.
options.splitChar
(String | RegExp) [ /./ ]
Char(s) separating path levels in property keypaths.
options.upLevelChar
(String | RegExp) [ /-/ ]
Char(s) used for moving up in relative keypaths.
Examples
Custom key patterns
// Default key patternsvar parser = ;parser; // nested.object.propparser; // nested.object.propparser; // nested.propparser; // propparser; // nested.prop
// Use *filepath-like* key patternsvar parser = /*...*/ splitChar: '/' upLevelChar: '.'; parser; // nested/object/propparser; // nested/object/propparser; // nested/object/propparser; // propparser; // nested/prop
// Define your own key patternsvar parser = /*...*/ splitChar: ':' upLevelChar: '_'; parser; // nested:object:propparser; // nested:object:propparser; // nested:propparser; // propparser; // nested:prop
Dynamic property values
Using template strings and the parser option, you can get dynamic property values, based on expressions using property references:
var PropRefParser = ;var _templ = ; var props = foo: true bar: '<% if(@{foo}) { print("yup"); }'; var opts = { return propskey; } { if typeof val == 'string' return props; }; var parser = props opts;parser;// -> {// foo: true,// bar: "yup"// }
TODO
-
Implement an '.escape' method to escape references in given value
-
Ignore escaped references, split and upLevel characters
-
Ignore context for absolute keypaths in property references
-
Default to simple getter
function(props, key, opts) { return props[key]; }
-
Test loading in AMD
-
Test browser global
-
Test multiple split and upLevel characters
-
Write test suite
-
Support advanced keypath using mutliple key adapters –each with their own splitChar, upLevelChar, getter and parser
-
Support file and url references
-
Support custom sources (yaml, json, db, ...)
-
Support sync and async (callback or promise) loading of files and urls