Nasal library/props

From FlightGear wiki
Jump to: navigation, search

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]

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"

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();
Note  For setting the values of Property Tree nodes, it is recommended to use getprop() if possible, due to performance differences.

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). Note that it is advised to use getprop() were possible.

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]);
Note  For setting the values of Property Tree nodes, it is recommended to use getprop() if possible, due to performance differences.

Returns the value of the node.

rel_path
Optional relative path to a subnode as a string.

Examples

var node = props.Node.new();
node.setDoubleValue(2.35);
print(node.getValue()); # prints "2.35"
var node = props.Node.new();
node.setValue("Hi");
print(node.getValue()); # prints "Hi"
var node = props.Node.new();
node.addChild("a").setValue("Hi");
print(node.getValue("a")); # prints "Hi"
var node = props.Node.new();
node.setValue([0, 0.5, 1]);
debug.dump(node.getValue()); # prints "[0, 0.5, 1]"

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]

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 "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)

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);
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 ↘
None/unspecified
  • Type set to double
  • Node set to value.
  • Type set to string
  • Node set to value.
  • Type set to vec*d
  • 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);

Sets the nodes property tree from a Nasal hash. Scalars will become nodes in the tree and hashes will become named subnodes. Vectors will be converted into indexed nodes, with the values in the vector becoming their values (see examples below).

val
A hash that will become the property tree.

Examples

var val = {
    "a": 100 # "a" will become the subnode's name, and 100 its value
};
var node = props.Node.new();
node.setValues(val);
props.dump(node); # dump tree
var val = {
    "a": 1,
    "b": "Hi",
    "c": {
        "d": [1, 2, 3]
    }
};
var node = props.Node.new();
node.setValues(val);
props.dump(node); # dump tree

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).

Functions

compileCondition()

props.compileCondition(node);

Version added: FG 3.2 (commit)

Compiles a condition property branch and returns a Condition ghost object or nil on error. This ghost will contain a test() function that will return the result of the condition as either 1 (true) or 0 (false).
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);

var cond = props.compileCondition(node);
print(cond.test()); # prints "1" (true)
setprop("/test", 15);
print(cond.test()); # 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);

var cond = props.compileCondition(node);
print(cond.test()); # prints "1" (true)
setprop("/test", 15);
print(cond.test()); # prints "0" (false)

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.

Note  For getting and setting values in the Property Tree, it is recommended to use getprop() and setprop() if possible, due to performance differences.

Examples

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