Nasal and the Property-tree

In the namespace props is a class called Node, which can be used to manipulate the property tree. This is useful if more control than getprop() and setprop() gives is needed. See here for info on performance.

The root node

props.globals is a instance of Node, which represents the root node in the public property tree.

The Node class

The class props.Node has these functions:

new(values = nil)

Static constructor for a Node object. Accepts a Nasal hash expression to initialize the object a-la setValues().

setValues(val)

Useful utility. Sets a whole property tree from a Nasal hash object, such that scalars become leafs in the property tree, hashes become named subnodes, and vectors become indexed subnodes. This works recursively, so you can define whole property trees with syntax like:

dialog = {
   name : "exit", width : 180, height : 100, modal : 0,
   text : { x : 10, y : 70, label : "Hello World!" } };

getValues()

Counter piece of setValues(). Returns a hash with all values in the subtree. Nodes with same name are returned as vector, where the original node indices are lost. The function should only be used if all or almost all values are needed, and never in performance-critical code paths. If it's called on a node without children, then the result is equivalent to getValue().

initNode(path = nil, value = 0, type = nil, force = 0)

Initializes property if it's still undefined. First argument is a property name/path. It can also be nil or an empty string, in which case the node itself gets initialized, rather than one of its children. Second argument is the default value. The third, optional argument is a property type (one of "STRING", "DOUBLE", "INT", or "BOOL"). If it is omitted, then "DOUBLE" is used for numbers, and STRING for everything else. Returns the property as props.Node. The fourth optional argument enforces a type if non-zero.

getNode(relative_path, index=0, create = false)

Returns another node by relative path.

This method leaves the index off the last member of the path, so that the user can specify it separately (and save some string building). For example, getNode("/bar[1]/foo", 3) is exactly equivalent to getNode("bar[1]/foo[3]"). The index provided overrides any given in the path itself for the last component.

getParent()

Returns the parent node.

getChild(name, index=0, create=false)

Returns a child node by name and index, creating it if necessary.

getChild(position)

Get a child node by position (*NOT* index).

getChildren(name)

Returns a vector of all children with the specified name (but different indices).

addChild(name)

Create a child node by name after the last node with the same name. Returns the new child node.

removeChild(pos, keep=true)

Remove child by position. Returns the removed child.

removeChild(name, index=0, keep=true)

Remove a child node. (For some reason index must be specified for this to work) Returns the removed child.

removeChildren(name, keep=true)

Remove all children with the specified name. Returns a vector with the removed children.

getAliasTarget

Returns the current alias target node, if any.

getName()

Returns the node's simple (XML) name.

getIndex()

Returns the node's integer index.

getType()

Returns the type of leaf value, if any, for this node.

getType(relative_path)

Returns the value type for another node.

getAttribute(attr)

Returns a single mode attribute for the property node.

Note: unclear how to create a attr argument in Nasal. Need example.

setAttribute(attr, state)

Set a single mode attribute for the property node. The argument state is a bool.

getValue(relative_path=nil)

Get a value from a node, or a relative child/parent specified in the argument (new in 2.12).

If the actual type of the node doesn't match the desired type, a conversion isn't guaranteed.

All old uses of the form:

node.getNode("foo").getValue()

Should be replaced with:

node.getValue("foo")

setIntValue(value)

Set an int value for this node.

setIntValue(relative_path, value)

Set another node's value as an int.

setBoolValue(value)

Set a bool value for this node.

setBoolValue(relative_path, value)

Set another node's value as a bool.

setDoubleValue(value)

Set a double value for this node.

setDoubleValue(relative_path, value)

Set another node's value as a double.

unalias()

Remove any alias for this node.

alias(target)

Alias this node's leaf value to another node's.

alias(path)

Alias this node's leaf value to another's by relative path.

clearValue()

Clear any existing value and set the type to NONE.

getPath()

Returns the full path of the node.

getBoolValue()

Returns the value as a boolean (0 or 1).

remove()

Detaches the node from its parent. If the node has no parent, the function returns nil.

Functions in props

dump(node) and dump(prefix, node)

Useful debugging utility. Recursively dumps the full state of a Node object to the console. Try binding

props.dump(props.globals)

to a key for a fun hack.

copy(src, dest, attr = 0)

Recursively copy property branch from source Node to destination Node. Doesn't copy aliases. Copies attributes if optional third argument is set and non-zero.

setAll(base, child, value)

Sets all indexed property children to a single value. arg[0] specifies a property name (e.g. /controls/engines/engine), arg[1] a path under each node of that name to set (e.g. "throttle"), arg[2] is the value.

nodeList(arg...)

Turns about anything into a list of props.Nodes, including ghosts, path strings, vectors or hashes containing, as well as functions returning any of the former and in arbitrary nesting. This is meant to be used in functions whose main purpose is to handle collections of properties.

condition(p)

Evaluates a <condition> property branch according to the rules set out in $FG_ROOT/Docs/README.conditions. Undefined conditions and a nil argument are "true". The function dumps the condition branch and returns nil on error.

runBinding(node, module = nil)

Runs <binding> as described in $FG_ROOT/Docs/README.commands using a given module by default, and returns 1 if fgcommand() succeeded, or 0 otherwise. The module name won't override a <module> defined in the binding.