Nasal library/props

The FlightGear forum has a
subforum related to: Nasal Scripting

This page contains documentation for the props namespace in Nasal. This namespace provides APIs for working with property trees (including the main Property Tree) via SGPropertyNode _(doxygen). The props namespace is sourced from fgdata/Nasal/props.nas and flightgear/src/Scripting/nasal-props.cxx.

Class

Node

The main class, used widely for manipulating property trees.

new()

props.Node.new([values]);

Constructor function. Returns a new props.Node instance.

values: An optional hash that will be the initial property structure.

Examples

var node = props.Node.new();
props.dump(node);

var tree = {
    a: 1,
    b: ["a", "b", "c"],
    c: {
        d: 1 * 4
    }
};

var node = props.Node.new(tree);
props.dump(node);

addChild()

props.Node.addChild(name[, min_idx[, append]]);

Version added: FG 2.10 (commit)

Add a new, blank child to the node. Returns the newly-created node.

name: The name of the node as a string.
min_idx: This specifies the minimum index to add the new one to. This takes precedence over append. Defaults to 0.
append: If there is already one or more children with the same name and this argument is 1 (true), the new child will be added after the child with the highest index. If 0 (false), the new child will be added at the lowest available index with the limit of min_idx. Defaults to 1 (true).

Examples

var node = props.Node.new();
node.addChild("a");
props.dump(node);

var node = props.Node.new();
node.addChild("a", 1);
props.dump(node); # a[1]

var node = props.Node.new();
node.addChild("a", 1);
props.dump(node); # a[1]
node.addChild("a", 0, 0);
props.dump(node); # a[1] and a[0]

var node = props.Node.new();
node.addChild("a", 1);
props.dump(node); # a[1]
node.addChild("a", 0, 1);
props.dump(node); # a[1] and a[2]

addChildren()

props.Node.addChildren(name, count[, min_idx[, append]]);

Version added: FG 2.10 (commit)

Adds multiple children with the same name to this node. Returns nil.

name: The name of the nodes as a string.
count: Number of new children to add.
min_idx: Performs the same function as in Node.addChild().
append: Performs the same function as in Node.addChild().

Examples

var node = props.Node.new();
node.addChildren("a", 2);
props.dump(node); # a[0] and a[1]

var node = props.Node.new();
node.addChildren("a", 2, 1);
props.dump(node); # a[1] and a[2]

var node = props.Node.new();
node.addChild("a", 2);
props.dump(node); # a[2]
node.addChildren("a", 2, 0, 0);
props.dump(node); # a[2], a[0], and a[1]

adjustValue() (since FG 2020.1)

props.Node.adjustValue(delta);

Adds delta (numeric) to current value respecting the node type.

delta: Numeric value (can be negative) to add to current node value.

alias()

props.Node.alias(node);

Aliases this node to another one. Returns 1 on success and 0 on failure.

node: The node to alias to. Can be one of:

A path to a property in the Property Tree as a string.
A prop ghost.
A props.Node object.

Examples

var node = props.Node.new();
node.alias("/position/altitude-ft");
props.dump(node); # equals the current altitude

var node1 = props.Node.new();
node1.setDoubleValue(2.34);
var node2 = props.Node.new();
node2.alias(node1);
props.dump(node2); # equals 2.34

clearValue()

props.Node.clearValue();

Clears the value and type of the node.

Example

var node = props.Node.new();
node.setDoubleValue(2.34);
props.dump(node); # prints "{DOUBLE} = 2.35"
node.clearValue();
props.dump(node); # prints "{NONE} = nil"

decrement() (since FG 2020.1)

props.Node.decrement(n = 1);

Decrements integer property by n (default: n = 1)

n: Value to subtract, will be converted to int, defaults to 1

equals()

props.Node.equals(node);

Version added: FG 2.12 (commit)

Checks whether the node refers to the same one as another. Returns 1 (true) if it is, and 0 (false) if otherwise.

node: Node to check against. May be either a prop ghost or a props.Node object.

Example

var n = props.Node.new();
var a = n;
print(a.equals(n)); # prints "1" (true)

getAliasTarget()

props.Node.getAliasTarget();

Returns the alias target of a node as another props.Node instance.

Example

setprop("/test", 2.35);
var node = props.Node.new();
node.alias("/test");
var tgt = node.getAliasTarget();
print(tgt.getPath()); # prints "/test"

getAttribute()

props.Node.getAttribute([rel_path, ]name);
props.Node.getAttribute();

Returns an attribute. If no arguments are given, the function will return an integer specifying the attributes set for the node (see simgear/simgear/props/props.hxx (line 767) for a list). A list of attributes are below

String	Return value
last	The highest used attribute code (should be 128). See for simgear/simgear/props/props.hxx (line 767) the codes.
children	Number of child nodes.
listeners	Number of listeners connected to this node.
references	Number of times the node has previously been referenced.
tied	Whether the node is tied.
alias	Whether the node is aliased.
readable	Whether the node can be read.
writable	Whether the node can be written to.
archive	Whether the node will be saved when the "save" fgcommand is triggered.
trace-read	Whether the reading of the node will be logged when `--log-level=info`.
trace-write	Whether the writing to the node will be logged when `--log-level=info`.
userarchive	Whether the node will be saved to the autosave file (only works for actual properties).
preserve	Whether the value of node will be preserved during resets (only works for actual properties).

rel_path: Optional relative path as a string.
name: Attribute as a string. See the above table for a full list.

Examples

var node = props.Node.new();
var child = node.addChild("a");
print(node.getAttribute("children")); # prints "1"

Example using relative path

var node = props.Node.new();
var child = node.addChild("a");
print(node.getAttribute("a", "readable")); # prints "1" (node can be read from)

var node = props.Node.new();
var node2 = props.Node.new();
node2.alias(node);
print(node2.getAttribute("alias")); # prints "1" (true)

print(props.globals.getNode("/sim/signals/fdm-initialized").getAttribute("listeners")); # prints the number of listeners

print(props.globals.getNode("/sim/time/elapsed-sec").getAttribute("tied")); # prints "1" (true), meaning it is tied

var node = props.Node.new();
print(node.getAttribute("writable")); # prints "1" (true), meaning the node can be written to

Example using no arguments

var node = props.Node.new();
print(node.getAttribute()); # prints "3" (true), meaning the node can be read from (1) and written to (2)

getBoolValue()

props.Node.getBoolValue();

Returns the value of a node converted to a boolean. If the node is a number type, 0 will return false, while 1 will return true. If the node is a string or unspecified type and the value is "false", false will be returned. Otherwise, true will be returned. Remember that boolean values are represented in Nasal as 1 (true) and 0 (false).

Examples

var node = props.Node.new();
node.setBoolValue(1);
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setBoolValue(0);
print(node.getBoolValue() ? "true" : "false"); # prints "false"

var node = props.Node.new();
node.setDoubleValue(1.23);
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setDoubleValue(-1.23);
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setDoubleValue(0.0);
print(node.getBoolValue() ? "true" : "false"); # prints "false"

var node = props.Node.new();
node.setIntValue(2);
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setIntValue(-2);
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setIntValue(0);
print(node.getBoolValue() ? "true" : "false"); # prints "false"

var node = props.Node.new();
node.setValue("Hello, World!");
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setValue("false");
print(node.getBoolValue() ? "true" : "false"); # prints "false"

getChild()

props.Node.getChild(rel_path[, idx[, create]]);

Returns a child of a node as another props.Node instance.

rel_path: Relative path to the child node as a string.
idx: Optional index for the child node as an integer.
create: If set to 1 (true), a new child will be created if it does not exist. If set to 0 (false), the function will not create a new child and the function will return nil if no child exists. Defaults to 0.

Examples

var node = props.Node.new();
node.addChild("a");
var c = node.getChild("a");

var node = props.Node.new();
node.addChildren("a", 3);
node.getNode("a[1]").setDoubleValue(2.35);
var c = node.getChild("a", 1);
print(c.getValue()); # prints "2.35"

var node = props.Node.new();
var c = node.getChild("a", 1, 1);
props.dump(node); # new child a[1] will have appeared

getChildren()

props.Node.getChildren([name]);

Returns a vector of child nodes, optionally those with a certain name, as props.Node instances.

name: Optional name of the child nodes as a string. If not given, all children will be returned.

Examples

var node = props.Node.new();
node.addChildren("a", 3);
node.addChildren("b", 3);
debug.dump(node.getChildren()); # all child nodes in the vector

var node = props.Node.new();
node.addChildren("a", 3);
node.addChildren("b", 3);
debug.dump(node.getChildren("b")); # only children with the name "b" in the vector

getIndex()

props.Node.getIndex();

Returns the index of a node as an integer.

Examples

var node = props.Node.new();
node.addChildren("a", 3);
print(node.getChild("a", 1).getIndex()); # prints "1"

var node = props.Node.new();
node.addChild("b");
print(node.getChild("b").getIndex()); # prints "0"

getName()

props.Node.getName();

Returns the name of the node as a string.

Examples

var node = props.Node.new();
var c = node.addChild("a");
debug.dump(c.getName()); # prints "a"

var node = props.Node.new();
node.addChildren("a", 3);
debug.dump(node.getChild("a", 2).getName()); # prints "a"

getNode()

props.Node.getNode(rel_path[, create]);

Returns a subnode as another props.Node instance.

rel_path: Relative path to the subnode as a string.
create: If 1 (true), the node will be created if it does not exist. If 0 (false) and the node does not exist, the function will return nil. Default to 0 (false).

Examples

var tree = {
    "a": 1,
    "b": "Hi",
    "c": {
        "d": "Hello, World!"
    }
};
var node = props.Node.new(tree);
print(node.getNode("c/d").getValue()); # prints "Hello, World!"

var tree = {
    "a": 1,
    "b": "Hi",
    "c": {}
};
var node = props.Node.new(tree);
node.getNode("c/d", 1).setDoubleValue(2.35);
props.dump(node); # c/d now exists

var ac = props.globals.getNode("sim/aircraft");
print("Current aircraft is: ", ac.getValue());

getParent()

props.Node.getParent();

Returns the parent of a node, or nil if there is no parent.

Examples

var tree = {
    "a": 1,
    "b": "Hi",
    "c": {
        "d": "Hello, World!"
    }
};
var node = props.Node.new(tree);
props.dump(node.getNode("c/d").getParent()); # dumps "c"

var node = props.Node.new();
debug.dump(node.getParent()); # prints nil

getPath()

props.Node.getPath();

Returns the path of the node as a string.

Example

var tree = {
    "a": 1,
    "b": "Hi",
    "c": {
        "d": "Hello, World!"
    }
};
var node = props.Node.new(tree);
print(node.getNode("c/d").getPath()); # prints "/c/d"

getType()

props.Node.getType();

Returns node's type as a string. It should be one of "NONE", "ALIAS", "BOOL", "INT", "LONG" (long integer), "FLOAT", "DOUBLE", "STRING", "VEC3D", "VEC4D", "UNSPECIFIED".

Examples

var node = props.Node.new();
print(node.getType()); # prints "NONE"

var node = props.Node.new();
node.setIntValue(12);
print(node.getType()); # prints "INT"

var node = props.Node.new();
node.setValue([0.4, 0.2, 1]);
debug.dump(node.getValue()); # prints "[0.4, 0.2, 1]"
print(node.getType()); # prints "VEC3D"

getValue()

props.Node.getValue([rel_path]);

getValues()

props.Node.getValues();

Returns the node tree as a hash, with all the various subnodes, etc. If the node has no children, the result is equivalent to getValue() . Subnodes that are indexed will be combined into one key and their values placed in a vector (see example 2).

Examples

var tree = {
    "string": "Hi",
    "number": 1.2,
    "subnode": {
        "idx-node": [1, 2, 3]
    }
};
var node = props.Node.new(tree);
node.addChild("bool").setBoolValue(1);
props.dump(node); # dump to node tree
debug.dump(node.getValues()); # dump the node converted to hash

var tree = {
    "a": [1, 2, 3]
};
var node = props.Node.new(tree);
props.dump(node); # a[0] = 1, a[1] = 2, a[2] = 3
debug.dump(node.getValues()); # a: [1, 2, 3]

increment() (since FG 2020.1)

props.Node.increment(n = 1);

Increments integer property by n (default: n = 1)

n: Value to add, will be converted to int, defaults to 1

initNode()

props.Node.initNode([path[, value[, type[, force]]]]);

Initializes a node if it doesn't exist and returns that node as a props.Node object.

path: Optional path to a subnode as a string. If not given, the node itself will be initialized.
value: Optional default value to initialize the node with.
type: Optional string that will set the type of the node. Must be one of "DOUBLE", "INT", "BOOL", or "STRING".
force: If set to 1 (true), the node's type will be forced to change.

Examples

var node = props.Node.new();
var a = node.initNode("a");
props.dump(a);

var node = props.Node.new();
var a = node.initNode("a", "Hi");
props.dump(a);

var node = props.Node.new();
var a = node.initNode("a", 1.25, "INT");
props.dump(a); # a = 1

var node = props.Node.new();
node.addChild("a").setBoolValue(0);
props.dump(node.getChild("a")); # a = 0 (type: bool)
var a = node.initNode("a", 1.25, "INT", 1);
props.dump(a); # a = 0 (type: int)

isInt() (since FG 2020.1)

props.Node.isInt();

Returns true (1) if node type is "INT" or "LONG" (long integer) otherwise false (0).

isNumeric() (since FG 2020.1)

props.Node.isNumeric();

Returns true (1) if node type is "INT", "LONG", "FLOAT" or "DOUBLE" otherwise false (0).

remove()

props.Node.remove();

Removes the node and returns the removed node.

Example

var node = props.Node.new();
node.addChild("a");
props.dump(node);
node.getChild("a").remove();
props.dump(node); # child "a" does not exist anymore

removeAllChildren()

Caution Be careful when using this API in conjunction with the Canvas system and element specific properties, for details please see Howto:Canvas Path Benchmarking

props.Node.removeAllChildren();

Version added: FG 3.2 (commit)

Removes all child nodes and returns the node.

Example

var tree = {
    "a": 1,
    "b": 2,
    "c": 3
};
var node = props.Node.new(tree);
props.dump(node);
node.removeAllChildren();
props.dump(node); # all children have been removed

removeChild()

props.Node.removeChild(rel_path, idx);

Removes a given child node child nodes and returns the node.

rel_path: Relative path to a subnode as a string.
idx: Index of the subnode to remove as an integer.

Examples

var node = props.Node.new();
node.addChild("a");
props.dump(node);
node.removeChild("a", 0);
props.dump(node); # child "a" has been removed

var node = props.Node.new();
node.addChildren("a", 2);
props.dump(node);
node.removeChild("a", 0);
props.dump(node); # just a[1] remains

removeChildren()

props.Node.removeChildren([name]);

Removes all children with a specified name. If no arguments are given, all children will be removed (see also removeAllChildren() ).

name: Optional name of children to remove as a string.

Examples

var node = props.Node.new();
node.addChildren("a", 2);
node.addChildren("b", 2);
props.dump(node);
node.removeChildren("a");
props.dump(node); # just children named "b" remain

var node = props.Node.new();
node.addChildren("a", 2);
node.addChildren("b", 2);
props.dump(node);
node.removeChildren();
props.dump(node); # all children removed

setAttribute()

props.Node.setAttribute([rel_path, ]attr, value);
props.Node.setAttribute(attrs);

Sets an attribute or multiple attributes. A list of attributes and their codes are below. For a brand new node, the default attributes are readable and writable. Returns an integer specifying the old attributes.

String	Description
readable	Whether the node can be read.
writable	Whether the node can be written to.
archive	Whether the node will be saved when the "save" fgcommand is triggered.
trace-read	Whether the reading of the node will be logged when `--log-level=info`.
trace-write	Whether the writing to the node will be logged when `--log-level=info`.
userarchive	Whether the node will be saved to the autosave file (only works for actual properties).
preserve	Whether the value of node will be preserved during resets (only works for actual properties).

rel_path: Optional relative path as a string.
attr: Name of attribute to set as a string. See above.
value: Boolean value to set the property to.
attrs: When the function is used in its second form, this argument is used. This argument should be an integer specifying which arguments are set to true. See simgear/simgear/props/props.hxx (line 767) for the full list of codes. Simply add codes of the desired attributes together.

Examples

var node = props.Node.new();
node.setAttribute("trace-write", 1);
node.setIntValue(12); # will be traced

var node = props.Node.new();
node.setAttribute("readable", 0);
var val = node.getValue();
debug.dump(val); # prints "nil"

var node = props.Node.new();
node.addChild("a");
node.setAttribute("a", "trace-write", 1);
node.getChild("a").setIntValue(12); # will be traced

var node = props.Node.new();
node.setAttribute(35); # read + write + trace-write
node.setIntValue(12); # will be traced

setBoolValue()

props.Node.setBoolValue([rel_path, ]value);

Note For setting the values of Property Tree nodes, it is recommended to use setprop() if possible, due to performance differences.

Sets a node to a boolean value. If the node has no type, it will be set to a bool type. If the node is already a number type, it will be set to either 1 or 0. If it is a string, it will be set to either "true" or "false". Returns 1 (true) if the operation was successful.

rel_path: Optional relative path as a string.
value: Value to set the node to, will be interpreted into a boolean. If it is nil, it will be false. If it is a string, it will be false. If it is a number, 0 will be false, while other numbers will be true. All other cases will be interpreted as 0.

Examples

var node = props.Node.new();
node.setBoolValue(nil);
props.dump(node); # node = 0 (false)

var node = props.Node.new();
node.setBoolValue("Hi");
props.dump(node); # node = 1 (true)

var node = props.Node.new();
node.setBoolValue(0);
props.dump(node); # node = 0 (false)
node.setBoolValue(1.25);
props.dump(node); # node = 1 (true)

var node = props.Node.new();
node.setValue("String");
props.dump(node); # node = "String" (type: string)
node.setBoolValue(1);
props.dump(node); # node = "true"

var node = props.Node.new();
node.setDoubleValue(12.32);
props.dump(node); # node = 12.32 (type: double)
node.setBoolValue(1);
props.dump(node); # node = 1

var node = props.Node.new();
node.addChild("a");
node.setBoolValue("a", 1);
props.dump(node); # /a = 1

setDoubleValue()

props.Node.setDoubleValue([rel_path, ]value);

Note For setting the values of Property Tree nodes, it is recommended to use setprop() if possible, due to performance differences.

Sets a node to a double value. If the node has no type, it will be set to a double type. If the node is a bool, values different from zero will be interpreted as true. If the node is a string, the value will be converted to a string. If the node is an integer type, it will be truncated to the closest integer to zero. Returns 1 (true) if the operation was successful.

rel_path: Optional relative path as a string.
value: Value to set the node to, will be interpreted into a double number. It must be a valid number or a string that can be converted to a number.

Examples

var node = props.Node.new();
node.setDoubleValue(1.1);
props.dump(node); # node = 1.1 (type: double)

var node = props.Node.new();
node.setDoubleValue("1.1");
props.dump(node); # node = 1.1 (type: double)

var node = props.Node.new();
node.setBoolValue(1);
node.setDoubleValue("1.1");
props.dump(node); # node = 1 (type: bool)
node.setDoubleValue(0.0);
props.dump(node); # node = 0 (type: bool)

var node = props.Node.new();
node.setIntValue(1);
node.setDoubleValue(1.1);
props.dump(node); # node = 1 (type: int)
node.setDoubleValue("-1.1");
props.dump(node); # node = -1 (type: int)

var node = props.Node.new();
node.addChild("a");
node.setDoubleValue("a", 12.2);
props.dump(node); # /a = 12.2

setIntValue()

props.Node.setIntValue([rel_path, ]value);

Note For setting the values of Property Tree nodes, it is recommended to use setprop() if possible, due to performance differences.

Sets a node to an integer value. If the node has no type, it will be set to a integer type. If the node is a bool, values different from zero will be interpreted as true. If the node is a string, the value will be converted to a string. Returns 1 (true) if the operation was successful.

rel_path: Optional relative path as a string.
value: Value to set the node to, will be interpreted into a integer. It must be a valid number or a string that can be converted to a number. If the number is a double, it will be truncated to the closest integer to zero.

Examples

var node = props.Node.new();
node.setIntValue(12);
props.dump(node); # node = 12
node.setIntValue("6");
props.dump(node); # node = 6

var node = props.Node.new();
node.setIntValue(12.2);
props.dump(node); # node = 12
node.setIntValue(-12.2);
props.dump(node); # node = 12

var node = props.Node.new();
node.setBoolValue(1);
node.setIntValue(12.5);
props.dump(node); # node = 1 (type: bool)
node.setIntValue(0);
props.dump(node); # node = 0 (type: bool)

var node = props.Node.new();
node.setValue("Hi");
node.setIntValue(12);
props.dump(node); # node = "12" (type: string)

var node = props.Node.new();
node.addChild("a");
node.setIntValue("a", 12);
props.dump(node); # /a = 12

setValue()

props.Node.setValue([rel_path, ]value);

See also setBoolValue() , setDoubleValue() , and setIntValue() .

Note For setting the values of Property Tree nodes, it is recommended to use setprop() if possible, due to performance differences.

Sets a node to a given value. See table below for conversions and effects. Note that vec3d and vec4d types are not fully integrated into SGPropertyNode. Returns 1 (true) if the operation was successful.

value type →		Number	String	Vector
Current node type ↓	Result ↘	Number	String	Vector
None/unspecified		Type set to `double` Node set to value.	Type set to `string` Node set to value.	Type set to `vecd` Node set to value*.
Bool		If value != 0, node set to true. If value == 0, node set to false.	If value == "true", node set to true. If value can be converted to an integer, and != 0, node set to true.	Node set to true.
Integer		Node set to truncated value	Node set to value converted and truncated to an integer.	Node set to 1.
Double		Node set to value.	Node set to value converted to number.	Throws an error (vector is not a number).
String		Node set to value converted to string.	Node set to value.	Node not set.

rel_path: Optional relative path as a string.
value: Value to set the node to. Must be a string, a valid number, or a vector consisting of 3 or 4 numbers. See table above for conversions and effects.

Examples

var node = props.Node.new();
node.setValue("Hi");
props.dump(node); # node = "Hi"

var node = props.Node.new();
node.addChild("a");
node.setValue("a", "Hi");
props.dump(node); # \a = "Hi"

var node = props.Node.new();
node.setValue([0.4, 0.2, 1]);
debug.dump(node.getValue()); # prints "[0.4, 0.2, 1]"
print(node.getType()); # prints "VEC3D"

setValues()

props.Node.setValues(val);

unalias()

props.Node.unalias();

Un-aliases the node and returns it to a blank state. Returns 1 on success and 0 on failure (e.g., when used on a tied property).

toggleBoolValue() (since FG 2020.1)

toggleBoolValue();

Toggle a boolean property. You have to make sure the property is of type bool!

Example

var b = props.Node.new().initNode("/_test/bool", 1, "BOOL");
print("bool ", b.getValue());
b.toggleBoolValue();
print("after toggleBoolValue ", b.getValue());

Functions

compileCondition()

condition()

props.condition(node);

Evaluates a condition property branch and returns the result as a boolean.

node: Either a props.Node containing the condition, or a string specifying a place in the Property Tree where there is a condition branch.

Examples

var tree = {
    "equals": {
        "property": '/test',
        "value": 12
    }
};
var node = props.Node.new(tree);
setprop("/test", 12);

print(props.condition(node)); # prints "1" (true)
setprop("/test", 15);
print(props.condition(node)); # prints "0" (false)

var tree = {
    "equals": {
        "property": '/test',
        "value": 12
    }
};
props.globals.getNode("test2/condition", 1).setValues(tree); # place it in the Property Tree
setprop("/test", 12);

print(props.condition(node)); # prints "1" (true)
setprop("/test", 15);
print(props.condition(node)); # prints "0" (false)

copy()

props.copy(src, dest[, attr]);

Copies the property tree of the source into the destination node. Note that aliased properties will not be copied.

src: Source props.Node object to copy from.
dest: Destination props.Node object to copy to.
attr: If set to 1 (true), attributes will also be copied. Defaults to 0 (false).

Examples

var tree = {
    "a": 1.5,
    "b": "Hi",
    "c": {
        "d": [1, 2, 3]
    }
};
var src = props.Node.new(tree);
var dest = props.Node.new();
props.copy(src, dest);
props.dump(dest);

var src = props.Node.new();
var a = src.addChild("a");
a.setAttribute("trace-write", 1);
a.setIntValue(12);
var dest = props.Node.new();
props.copy(src, dest, 1);
print(dest.getNode("a").getAttribute("trace-write")); # prints "1" (true)

dump()

props.dump(node);

Recursively dump the state of a node into the console, showing value and type of each node. Note that as of 10/2016, the value of vec*d type nodes cannot be dumped.

node: Node to dump.

Examples

var node = var tree = {
    "a": 12,
    "b": "Hi",
    "c": {
        "d": [1, 2, 3]
    }
};
var node = props.Node.new(tree);
props.dump(node); # dump into console

# Dump the entire Property Tree
# Warning! This is an intensive operation!
props.dump(props.globals);

getNode()

props.getNode();

Version added: FG 3.2 (commit)

Shortcut for props.globals.getNode(). See Node.getNode() for full documentation.

Example

print("Current aircraft is: ", props.getNode("/sim/aircraft").getValue());

nodeList()

props.nodeList(arg[, arg[, ...]]);

Converts its arguments into a vector of node objects if possible and returns that vector.

arg: Object to operate on. Must be a node object, string, vector, hash, function, or prop ghost. Vectors and hashes must contain any of the other acceptable types, functions must return any of the other types, strings will be assumed to be paths to global properties, and ghosts will be converted into node objects. There may be any number of arguments.

Examples

var node = props.Node.new();
var f = func(){
    var n = props.Node.new();
    return n._g;
}
var list = props.nodeList(node,
    "/sim/aircraft",
    ["/sim/fg-root"],
    { "path": "/sim/fg-home" },
    f
);
debug.dump(list); # dump list

var root = "/sim/version/";
var info = [
    root ~ "build-id",
    root ~ "build-number",
    root ~ "flightgear",
    root ~ "hla-support",
    root ~ "openscenegraph",
    root ~ "revision",
    root ~ "simgear"
];
info = props.nodeList(info); # turn into list of nodes
foreach(var n; info){
    print(n.getValue()); # dump info
}

runBinding()

props.runBinding(node[, module]);

Runs a binding element in a node object. Returns 1 (true) on success and 0 (false) on failure.

node: A <binding> element as a node object.
module: Optional string specifying a module to run Nasal scripts in if the command is nasal. This argument will not override any <module> element in the node

Examples

var tree = {
    "command": "dialog-show",
    "dialog-name": "map" # open map
};
var binding = props.Node.new(tree);
props.runBinding(binding);

var tree = {
    "command": "nasal",
    "script": 'print(pi)' # prints value of math.pi
};
var binding = props.Node.new(tree);
props.runBinding(binding, "math");

var tree = {
    "command": "nasal",
    "script": 'print(pi)', # prints value of math.pi
    "module": "math" # this is used
};
var binding = props.Node.new(tree);
props.runBinding(binding, "debug");

setAll()

props.setAll(base, child, value);

Sets indexed subnodes in the Property Tree with the same name to the same value.

base: Base path to the nodes.
child: Path to child nodes.
value: Value to set the subnodes to.

Examples

# apply 50% throttle to all engines
props.setAll("/controls/engines/engine", "throttle", 0.5);

var nodes = props.globals.addChildren("/test", 3);
foreach(var node; nodes){
    node.addChild("a");
}
props.setAll("/test", "a", "Hi"); # set all children (test[*]/a) to "Hi"

wrap()

props.wrap(node);

Turns prop ghosts, either in a vector or single, into props.Node objects.

node: prop ghost or vector of such ghosts.

Examples

var ghost = canvas._newCanvasGhost();
var node = props.wrap(ghost._node_ghost);
props.dump(node);

var vector = [canvas._newCanvasGhost()._node_ghost, props.Node.new()._g];
var nodes = props.wrap(vector);
foreach(var node; nodes){
    props.dump(node);
    print("----");
}

wrapNode()

props.wrapNode(node);

Turns a prop ghost into a props.Node object.

node: prop ghost to convert.

Example

var ghost = canvas._newCanvasGhost();
var node = props.wrapNode(ghost._node_ghost);
props.dump(node);

Variable

globals

props.globals;

Exposes the Property Tree as a props.Node object.

Examples

print("Current aircraft: ", props.globals.getNode("/sim/aircraft").getValue());

Alternative using getprop() .

print("Current aircraft: ", getprop("/sim/aircraft"));

Nasal library/props

Class

Node

new()

addChild()

addChildren()

adjustValue() (since FG 2020.1)

alias()

clearValue()

decrement() (since FG 2020.1)

equals()

getAliasTarget()

getAttribute()

getBoolValue()

getChild()

getChildren()

getIndex()

getName()

getNode()

getParent()

getPath()

getType()

getValue()

getValues()

increment() (since FG 2020.1)

initNode()

isInt() (since FG 2020.1)

isNumeric() (since FG 2020.1)

remove()

removeAllChildren()

removeChild()

removeChildren()

setAttribute()

setBoolValue()

setDoubleValue()

setIntValue()

setValue()

setValues()

unalias()

toggleBoolValue() (since FG 2020.1)

Functions

compileCondition()

condition()

copy()

dump()

getNode()

nodeList()

runBinding()

setAll()

wrap()

wrapNode()

Variable

globals

Navigation menu

Search