Add collection accessor methods: add/delete/get/has/set

[eemeli]

Following this comment on PR #68, this adds the following accessor functions to all collections:

• add(value: any) – adds a value to the collection. For !!map and !!omap the value must be a Pair instance or a { key, value } object, which may not have a key that already exists in the map.
• delete(key: any): boolean – removes a value from the collection. Returns true if the item was found and removed.
• get(key: any, keepScalar: boolean?): any | undefined – returns item at key, or undefined if not found. If keepScalar is not set, unwraps scalar values from their surrounding node; collections are always returned intact.
• has(key: any): boolean – checks if the collection includes a value with the key key
• set(key: any, value: any) – sets a value in this collection. For !!set, value needs to be a boolean to add/remove the item from the set.

For all of these, the keys may be nodes or their wrapped scalar values (i.e. 42 will match Scalar { value: 42 }) . Keys for !!seq should be positive integers, or their string representations. add() and set() do not automatically call createNode() to wrap the value.

Each of the methods also has a variant that requires an iterable as the first parameter, and allows fetching or modifying deeper collections: addIn(path, value), deleteIn(path), getIn(path, keepScalar), hasIn(path), setIn(path, value). getIn and hasIn will return undefined or false (respectively) if any of the intermediate collections is not found or if the key path attempts to extend within a scalar value, but the others will throw an error in such cases. Note that for addIn the path argument points to the collection rather than the item.

The document also gets the same methods, based on the top-level collection (if any). For the *in methods using an empty path value (i.e. null, undefined, or []) will refer to the document's top-level contents.

Examples:

const map = YAML.createNode({ a: 1, b: [2, 3] })
map.add({ key: 'c', value: 4 }) // -> map.get('c') === 4 && map.has('c') === true
map.addIn(['b'], 5) // -> map.getIn(['b', 2]) === 5
map.delete('c') // true
map.deleteIn(['c', 'f']) // false
map.get('a') // 1
map.get(YAML.createNode('a'), true) // Scalar { value: 1 }
map.getIn(['b', 1]) // 3
map.has('c') // false
map.hasIn(['b', '0']) // true
map.set('c', null) // -> map.get('c') === null && map.has('c') === true
map.setIn(['c', 'x']) // throws Error: Expected YAML collection at c. Remaining path: x

const doc = YAML.parseDocument('a: 1\nb: [2, 3]\n')
doc.get('a') // 1
doc.getIn([]) // YAMLMap { items: [Pair, Pair], ... }
doc.hasIn(['b', 0]) // true
doc.setIn(['a'], 4) // -> doc.getIn(['a']) === 4

@MikeRalphson will this help with your usage with JSON pointers?

Edit 1: Added get/has/set to Document & dropped getIn/hasIn throwing for invalid key paths.
Edit 2: Added add/addIn/delete/deleteIn.

[MikeRalphson]

will this help with your usage with JSON pointers?

It looks like it will, once I get my head around it! Thanks for the heads-up.