Nasal library/props: Difference between revisions

From FlightGear wiki
Jump to navigation Jump to search
(Notes about getprop()/setprop())
(→‎Node: Doc setValues())
Line 702: Line 702:


==== setValues() ====
==== setValues() ====
{{Nasal doc
|syntax = props.Node.setValues(val);
|text = {{hatnote|See also {{func link|getValues()}}.}}
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).
|param1 = val
|param1text = A hash that will become the property tree.
|example1 = 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
|example2 = 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() ====
==== unalias() ====



Revision as of 12:12, 3 October 2016

WIP.png Work in progress
This article or section will be worked on in the upcoming hours or days.
See history for the latest developments.

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

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

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([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()

Functions

compileCondition()

condition()

copy()

dump()

getNode()

nodeList()

runBinding()

setAll()

wrap()

wrapNode()

Variable

globals