Nasal library/props
Work in progress This article or section will be worked on in the upcoming hours or days. See history for the latest developments. |
The FlightGear forum has a subforum related to: Nasal Scripting |
Nasal scripting |
---|
Nasal internals |
---|
Memory Management (GC) |
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
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
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
prop.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"
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). 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"
getValue()
props.Node.getValue([rel_path]);
getBoolValue()
.Returns the value of the node. Note that it is advised to use getprop
where possible.
- 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"
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()
props.Node.removeAllChildren();
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.
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(value);
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.
- value
- Value to set the node too, 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
setDoubleValue()
props.Node.setDoubleValue(value);
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.
- value
- Value to set the node too, will be interpreted into a double number. It must be a number or a string that can be converted to a numeber.