List of Nasal extension functions: Difference between revisions

As such, the cmdarg() function is primarily used for listener callbacks declared in XML markup, cmdarg() returns the listened-to property as props.Node object, so you can use it with all its methods (see [[$FG_ROOT]]/Nasal/props.nas) for example:

print(cmdarg().getPath(), " has been changed to ", cmdarg().getValue())

</syntaxhighlight>

The cmdarg() function avoids that you have to type the exact same path twice (once here and once in the setlistener() command) and it makes clear that this is the listened to property. Also, you can use all the nice props.Node methods on cmdarg() directly:

setlistener("/gear/launchbar/state", func {

     if (cmdarg().getValue() == "Engaged")

Concatenates an arbitrary number of arguments to one string, appends a new-line, and prints it to the terminal. Returns the number of printed characters.

print("Just", " a ", "test");

</syntaxhighlight>

Returns the node value for a given path, or <tt>nil</tt> if the node doesn't exist or hasn't been initialized yet.  

getprop(<path>);

</syntaxhighlight>

Example:

print("The frame rate is ", getprop("/sim/frame-rate"), " FPS");

</syntaxhighlight>

Sets a property value for a given node path string. Always returns nil.

setprop(<path> [, <path>, [...]], <value>);

</syntaxhighlight>

Note: <tt>setprop()</tt> concatenates a list of input arguments by means of inserting a "/" in between. That is nice for properties, as this slash is part of the tree. However, when one wants to make use of indices, like [0], one has to concatenate by hand (using "~") ''inside'' one part of the string argument list. An example is:

var i = 4;

setprop("instrumentation","cdu","page["~i~"]","title","MENU");

Examples:

setprop("/sim/current-view/view-number", 2);

setprop("/controls", "engines/engine[0]", "reverser", 1);

'''Erasing a property from the property tree''': a property that has been created, for example through <tt>setprop()</tt> can be erased via

props.globals.getNode("foo/bar").remove(); # take out the complete node

props.globals.getNode("/foo").removeChild("bar"); # take out a certain child node

Give the value from a value or a source node to a destination node in given time.

interpolate(<path>, <value>, <time>);

Examples:

interpolate("controls/switches/nav-lights-pos", 1, 0.25); # After 25ms, nav-lights-pos = 1

interpolate("controls/gear/brake-left-pos", getprop("controls/gear/brake-left"), 1); # After 1s, brake-left-pos = brake-left

Runs a function after a given simulation time (default) or real time in seconds.

settimer(<function>, <time> [, <realtime=0>]);

</syntaxhighlight>

The first object is a function object (ie, "func { ... }").  Note that this is different from a function call (ie, "func ( ... )"). If you don't understand what this means, just remember to always enclose the first argument in any call to settimer with the word "func" and braces "{ }", and it will always work. For instance, if you want print the words "My result" in five seconds, use this code:

settimer ( func { print ( "My result"); }, 5);

</syntaxhighlight>

Inside the braces of the func object you can put any valid Nasal code, including a function call.  In fact, if you want to call a function with certain values as arguments, the way to do it is to turn it into a function object by enclosing it with a func{}, for example:

myarg1="My favorite string";

myarg2=432;

The third argument is optional and defaults to 0, which lets the time argument be interpreted as "seconds simulation time". In this case the timer doesn't run when FlightGear is paused. For user interaction purposes (measuring key press time, displaying popups, etc.) one usually prefers real time.

# simulation time example

var copilot_annoyed = func { setprop("/sim/messages/copilot", "Stop it! Immediately!") }

</syntaxhighlight>

# real time example

var popdown = func ( tipArg ) {  

As of 2.11, there is a new API for making a timer that allows more control over what happens in a timer – as opposed to setting one and forgetting about it.

var timer = maketimer(<interval>, <function>)

var timer = maketimer(<interval>, <self>, <function>)

</syntaxhighlight>

timer.start()

timer.stop()

</syntaxhighlight>

# create timer with 1 second interval

var timer = maketimer(1.0, func { print('timer called'); });

</syntaxhighlight>

var Tooltip = {

   new: func

Returns information about geodetic coordinates. Takes two arguments: lat, lon (in degree) and returns a vector with two entries, or nil if no information could be obtained because the terrain tile wasn't loaded. The first entry is the elevation (in meters) for the given point, and the second is a hash with information about the assigned material, or nil if there was no material information available, because there is, for instance, an untextured building at that spot or the scenery tile is not loaded.

var lat = getprop("/position/latitude-deg");

var lon = getprop("/position/longitude-deg");

A full data set looks like this:

debug.dump(geodinfo(lat, lon));

Usage:

var apt = airportinfo("KHAF");  # get info about KHAF

var apt = airportinfo(lat, lon); # get info about apt closest to lat/lon

The command debug.dump(airportinfo("KHAF")) outputs this:

{ lon : -122.4962626410256, lat : 37.51343502564102, has_metar : 0,

   runways : { 12 : { stopway2 : 0, threshold1 : 232.5624,

Usage:

var fp = flightplan();

var fp = flightplan('/some/path/to/a/flightplan.xml');

var fp = flightplan();

for (var i=0; i<fp.getPlanSize(); i += 1)

Returns epoch time (time since 1972/01/01 00:00) in seconds as a floating point number with high resolution. This is useful for benchmarking purposes.

#benchmarking example:

var start = systime();

Converts cartesian coordinates x/y/z to geodetic coordinates lat/lon/alt, which are returned as a vector. Units are degree and meter.

var geod = carttogeod(-2737504, -4264101, 3862172);

print("lat=", geod[0], " lon=", geod[1], " alt=", geod[2]);

Converts geodetic coordinates lat/lon/alt to cartesian coordinates x/y/z. Units are degree and meter.

var cart = geodtocart(37.5, -122.7, 1000); # lat/lon/alt(m)

print("x=", cart[0], " y=", cart[1], " z=", cart[2]);

This function is an interface to the built-in [http://expat.sourceforge.net/ Expat XML parser]. It takes up to five arguments. The first is a mandatory absolute path to an XML file, the remaining four are optional callback functions, each of which can be nil (which is also the default value).

var ret = parsexml(<path> [, <start-elem> [, <end-elem> [, <data> [, <pi> ]]]]);

Example:

var start = func(name, attr) {

     print("starting tag ", name);

Example:

var guess_path = func(path...) {

     var path_concat = string.join(path, "/");