jonschlinkert/expand-object

Expand a string into a JavaScript object using a simple notation.

expand-object

Expand a string into a JavaScript object using a simple notation. Use the CLI or as a node.js lib.

• Install
  • Type casting
• Install
• CLI
• node.js
  • children
  • siblings
    • general siblings
    • adjacent siblings
    • difference between sibling types
  • key-value pairs
  • arrays
• Usage examples
• Related projects
• Running tests
• Contributing
• Author
• License

(TOC generated by verb using markdown-toc)

Install

Install with npm

$ npm i expand-object --save

Also see collapse-object, for doing the reverse of this library.

Examples

expand('a')
//=> {a: ''}

expand('a.b')
//=> {a: {b: ''}}

expand('a|b')
//=> {a: '', b: ''}

expand('a|b', {toBoolean: true})
//=> {a: true, b: true}

expand('a:b')
//=> {a: 'b'}

expand('a,b')
//=> ['a', 'b']

Type casting

Introduced in v0.2.2, some values are cast to their JavaScript type.

Booleans

If the value is "true" or "false" it will be coerced to a boolean value.

expand('a:true')
//=> {a: true}
expand('a:false')
//=> {a: false}

Numbers

If the value is an integer it will be coerced to a number.

expand('a:1')
//=> {a: 1}
expand('a:123')
//=> {a: 123}

Regex

If the value is a simple regular expression it will be coerced to a new RegExp().

expand('a:/foo/')
//=> {a: /foo/}
expand('a.b.c:/^bar/gmi')
//=> {a: {b: {c: /^bar/gmi}}}

Install

Install with npm

$ npm i expand-object --save

CLI

Usage with cli:

❯ expand-object --help

  Usage: expand-object [options] <string>

  Expand a string into a JavaScript object using a simple notation.

  Options:

    -h, --help     output usage information
    -V, --version  output the version number
    -r, --raw      Output as raw javascript object - not stringified

  Examples:

    $ expand-object "a:b"
    $ expand-object --raw "a:b"
    $ echo "a:b" | expand-object

node.js

To use as a node.js library:

var expand = require('expand-object');

children

Expand dots into child objects:

expand('a')
//=> {a: ''}
expand('a.b')
//=> {a: {b: ''}}
expand('a.b.c')
//=> {a: {b: {c: ''}}}
expand('a.b.c.d')
//=> {a: {b: {c: {d: ''}}}}

siblings

expand-object supports two kinds of siblings, general and adjacent. It's much easier to understand the difference in the last example.

general siblings

Use pipes (|) to expand general siblings:

expand('a|b')
//=> {a: '', b: ''}
expand('a|b|c')
//=> {a: '', b: '', c: ''}
expand('a|b|c|d')
//=> {a: '', b: '', c: '', d: ''}
expand('a:b|c:d')
//=> {a: 'b', c: 'd'}

adjacent siblings

Use plus (+) to expand adjacent siblings:

Adjacent siblings are objects that immediately follow one another.

expand('a:b+c:d')
//=> {a: 'b', c: 'd'}
expand('a.b:c+d:e')
//=> {a: {b: 'c', d: 'e'}}

difference between sibling types

In the example below:

• general: d is a sibling to a
• adjacent: d is a sibling to b

// general siblings
expand('a.b:c|d:e')
//=> { a: { b: 'c' }, d: 'e' }

// adjacent siblings
expand('a.b:c+d:e')
//=> { a: { b: 'c', d: 'e' } }

key-value pairs

Expand colons into key-value pairs:

expand('a:b')
//=> {a: 'b'}
expand('a.b:c')
//=> {a: {b: 'c'}}
expand('a.b.c:d')
//=> {a: {b: {c: 'd'}}}

arrays

Expand comma separated values into arrays:

expand('a,b')
//=> ['a', 'b']
expand('a,b,c')
//=> ['a', 'b', 'c']
expand('a:b,c,d|e:f,g,h')
//=> {a: ['b', 'c', 'd'], e: ['f', 'g', 'h']}

Usage examples

Expand siblings with comma separated values into arrays:

expand('a:b,c,d|e:f,g,h')
//=> {a: ['b', 'c', 'd'], e: ['f', 'g', 'h']}

Expand children with comma separated values into arrays:

expand('a.b.c:d,e,f|g.h:i,j,k')
//=> {a: { b: {c: ['d', 'e', 'f']}}, g: {h: ['i', 'j', 'k']}}

Expand sibling objects into key-value pairs:

expand('a:b|c:d')
//=> {a: 'b', c: 'd'}
expand('a:b|c:d|e:f')
//=> {a: 'b', c: 'd', e: 'f'}
expand('a:b|c:d|e:f|g:h')
//=> {a: 'b', c: 'd', e: 'f', g: 'h'}

Expand child objects into key-value pairs:

expand('a.b:c')
//=> {a: {b: 'c'}}
expand('a.b.c:d')
//=> {a: {b: {c: 'd'}}}
expand('a.b.c.d:e')
//=> {a: {b: {c: {d: 'e'}}}}

Expand sibling and child objects into key-value pairs:

expand('a:b|c:d')
//=> {a: 'b', c: 'd'}
expand('a.b.c|d.e:f')
//=> {a: {b: {c: ''}}, d: {e: 'f'}}
expand('a.b:c|d.e:f')
//=> {a: {b: 'c'}, d: {e: 'f'}}
expand('a.b.c:d|e.f.g:h')
//=> {a: {b: {c: 'd'}}, e: {f: {g: 'h'}}}

Related projects

expand-args: Expand parsed command line arguments using expand-object. | homepage

Running tests

Install dev dependencies:

$ npm i -d && npm test

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

Author

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

License

Copyright © 2015 Jon Schlinkert Released under the MIT license.

---

This file was generated by verb on December 23, 2015.