Traverse

Overview

Traverse is a mutable class to traverse given JSON Object according to its object methods. This class is used in Rjson.traverse()

The flow of traversal follows method calling flow in Promise.js.

traverse({ foo: 'bar' })
    .toLineNo(0)
    .then(( obj, name, self ) => { /* ... */ });

Each object methods will return same (i.e. this) instance of Traverse Object.

API

Instantiation

traverse(sourceObj)

Each instantiation should be carried out using ordinary function call.

Parameter	Type	Description	Default	Required
sourceObj	Object	Object to be traversed	—	Yes

Class Attribute

.from

Enumeration for traversing directions. Used in .eachInodes().

Return	Type	Description
LEFT_TO_RIGHT	number	From Left to Right
RIGHT_TO_LEFT	number	From Right to Left

Accessibility
Getter	Yes
Setter	No

.to

Enumeration for targets. Used in .toDeepestTerminal().

Return	Type	Description
FIRST	number	To First Terminal
MIDDLE	number	To Middle Terminal
LAST	number	To Last Terminal

Accessibility
Getter	Yes
Setter	No

Object Attribute

.return

Flattening then() to return LAST result (i.e. parameters passed to f) without callback.

Return	Type	Description
o	Object	Parent object of destinating object
name	name	Key inside o

Accessibility
Getter	Yes
Setter	No

.self

Raw underlying object.

Accessibility
Getter	Yes
Setter	No

Object Method

.eachInodes([direction])

Run then() on each inodes breadth-wise and run whenNextLevel() for each level advancement

Parameter	Type	Description	Default	Required
direction	number (Enum)	Direction for breadth-wise traverse	Traverse.from.LEFT_TO_RIGHT	No

Return	Type	Description
*	TraverseEachInodes	New object with extra whenNextLevel()

Example

const { Rjson } = require('reyaml-core');
const rj = new Rjson({ foo: 'bar' });

rj.traverse(t => t
    .eachInodes(t.constructor.from.LEFT_TO_RIGHT)
    .whenNextLevel((o, next) => { /* ... */ })
    .then((o, name, next) => { /* ... */ })
);
// or
rj.traverse(t => { return t
    .eachInodes(t.constructor.from.LEFT_TO_RIGHT)
    .whenNextLevel((o, next) => { /* ... */ })
    .then((o, name, next) => { /* ... */ })
});

---

.eachInodesWithObject(obj)

Run then() on each inodes containing obj, starting from root depth-wise. obj is called by reference.

Parameter	Type	Description	Default	Required
obj	Object	Each traverse must contain obj as children	—	Yes

Return	Type	Description
*	Traverse	Mutable self reference (i.e. this)

Example

const { Rjson } = require('reyaml-core');
const bar = { reyaml: 'core' };
const rj = new Rjson({ foo: bar });

rj.traverse(t => t
    .eachInodesWithObject(bar)
    .then((o, name, next) => { /* ... */ })
);
// or
rj.traverse(t => { return t
    .eachInodesWithObject(bar)
    .then((o, name, next) => { /* ... */ })
});

---

.toDeepestTerminal([target])

Run then() on the deepest terminal, using target to destinate which deepest terminal in case of multiple leaves. In case multiple branches with terminals of same level, first branch will be traversed.

Parameter	Type	Description	Default	Required
target	number (Enum)	if deepest terminal has siblings, determine which to run then()	Traverse.to.FIRST	No

Return	Type	Description
*	Traverse	Mutable self reference (i.e. this)

Example

const { Rjson } = require('reyaml-core');
const rj = new Rjson({ foo: 'bar' });

rj.traverse(t => t
    .toDeepestTerminal(t.constructor.to.MIDDLE)
    .then((o, name, next) => { /* ... */ })
);
// or
rj.traverse(t => { return t
    .toDeepestTerminal(t.constructor.to.MIDDLE)
    .then((o, name, next) => { /* ... */ })
});

---

.toLineNo(lineNo)

Run then() on specific line number, with reference to the YAML form of underlying JSON Object.

Parameter	Type	Description	Default	Required
lineNo	number	Presented as numeric index of underlying JSON as depth-wise, root as 0	—	Yes

Return	Type	Description
*	Traverse	Mutable self reference (i.e. this)

Example

const { Rjson } = require('reyaml-core');
const rj = new Rjson({ foo: 'bar' });

rj.traverse(t => t
    .toLineNo(0)
    .then((o, name, next) => { /* ... */ })
);
// or
rj.traverse(t => { return t
    .toLineNo(0)
    .then((o, name, next) => { /* ... */ })
});

---

.toObject(obj)

Run then() on specific object obj. obj is called by reference.

Parameter	Type	Description	Default	Required
obj	Object	Specific object to traverse	—	Yes

Return	Type	Description
*	Traverse	Mutable self reference (i.e. this)

Example

const { Rjson } = require('reyaml-core');
const bar = { reyaml: 'core' };
const rj = new Rjson({ foo: bar });

rj.traverse(t => t
    .toObject(bar)
    .then((o, name, next) => { /* ... */ })
);
// or
rj.traverse(t => { return t
    .toObject(bar)
    .then((o, name, next) => { /* ... */ })
});

---

.then(callback)

This method acts like .then() in Promise.js, which will conduct actual traversal constructed by traverser.toXXX(), while running callback after reaching targeted destination(s). callback is structured with the following parameters as (o, name, self) => { ... }.

Parameter	Type	Description	Default	Required
callback	Function	Callback	—	Yes

Return	Type	Description
*	Traverse	Mutable self reference (i.e. this)

callback

Parameter	Type	Description
o	Object	Parent object of destinating object
name	string	Key of destinating object in sourceObj
self	Traverse	Self reference of traverser (i.e. equivalent to this inside traverser)

---

.whenNextLevel(callback)

Invoked at the end of each traversal level. Only can be called by TraverseEachInodes (i.e. .eachInodes()). callback is structured with the following parameters as (sourceObj, self) => { ... }.

Parameter	Type	Description	Default	Required
callback	Function	Callback	—	Yes

Return	Type	Description
*	TraverseEachInodes	Mutable self reference (i.e. this)

callback

Parameter	Type	Description
o	Object	Parent object of destinating object
self	TraverseEachInodes	Self reference of t (i.e. equivalent to this)