FlightGear wiki - User contributions [en]

Nasal scripting language

2009-05-01T16:09:10Z

Melchior FRANZ: Reverted edits by Scotth1 (Talk); changed back to last version by Melchior FRANZ

''Please note that a considerable amount of resources has not yet been incorporated here, you can check these out by going to the "[http://wiki.flightgear.org/index.php/Talk:Nasal_scripting_language discussion]" page, where we are collecting links to webpages and mailing list discussions/postings related to Nasal.''

[[FlightGear]] offers a powerful scripting language called [http://plausible.org/nasal/ "Nasal"], which supports reading and writing of internal properties, accessing internal data via extension functions, creating dialogs and much more. It uses some of the concepts of ECMA/JavaScript, Python and Perl and implements a simple but complete way of Object Oriented Programming. Nasal code can be run by aircraft configuration files, and it can be embedded in various [[XML]] files (dialog files, animation files, bindings for joysticks, keyboard and cockpit controls). Nasal is platform independent.

Note that this page is mostly about FlightGear-specific APIs/extension functions and usage pattern. See the Nasal webpage for [http://plausible.org/nasal/lib.html core language/library documentation] and [http://plausible.org/nasal/sample.nas source code examples].

In addition, the 'Nasal' directory in the FlightGear base package contains a wealth of tested, proven and usually well-commented source code that you may want to check out for additional examples of using the Nasal scripting language in FlightGear [http://cvs.flightgear.org/viewvc/data/Nasal/].

== Loops ==

Nasal has several ways to implement an iteration. Loops using <tt>while</tt>, <tt>for</tt>, <tt>foreach</tt>, and <tt>forindex</tt> block all of FlightGear's subsystems that run in the main thread, and can, thus, only be used for instantaneous operations that don't take too long. For operations that should continue over a longer period, one needs a non-blocking solution. This is done by letting functions call themselves after a timed delay:

var loop = func {
print("this line appears once every two seconds");
settimer(loop, 2);
}

loop(); # start loop

Note that the <tt>settimer</tt> function expects a ''function object'' (<tt>loop</tt>), not a function call (<tt>loop()</tt>). The fewer code FlightGear has to execute, the better, so it is desirable to run loops only when they are needed. But how does one stop a loop? A once triggered timer function can't be revoked. But one can let the loop function check an outside variable and refuse calling itself, which makes the loop chain die off:

var running = 1;
var loop = func {
if (running) {
print("this line appears once every two seconds");
settimer(loop, 2);
}
}

loop(); # start loop ...
...
running = 0; # ... and let it die

Unfortunately, this method is rather unreliable. What if the loop is "stopped" and a new instance immediately started again? Then the ''running'' variable would be ''1'' again, and a pending old loop call, which should really finish this chain, would happily continue. And the new loop chain would start, too, so that we would end up with two loop chains.

This can be solved by providing each loop chain with a ''loop identifier'' and letting the function end itself if the id doesn't match the global loop-id. Self-called loop functions need to inherit the chain id. So, every time the global loop id is increased, all loop chains die, and a new one can immediately be started.

var loopid = 0;
var loop = func(id) {
id == loopid or return; # stop here if the id doesn't match the global loop-id
...
settimer(func { loop(id) }, 2); # call self with own loop id
}

loop(loopid); # start loop
...
loopid += 1; # this kills off all pending loops, as none can have this new identifier yet
...
loop(loopid); # start new chain; this can also be abbreviated to: loop(loopid += 1);

== OOP - Object Oriented Programming ==

In Nasal, objects ("classes") are regular hashes. Self-reference and inheritance are implemented through special variables <tt>me</tt> and <tt>parents</tt>. To get a better understanding of the concept, let's start with the very basics.

=== Hashes ===

Hashes, also known as "dictionaries" in Python or "maps" in C++/STL are data structures that hold key/value pairs in a way that allows quick access to a value via its key.

var airport = {
"LOXZ": "Zeltweg",
"LOWI": "Innsbruck",
"LOXL": "Linz Hoersching", # the last comma is optional
};

print(airport["LOXZ"]); # prints "Zeltweg"
airport["LOXA"] = "Aigen"; # adds LOXA to the hash

The quotes around keys can be left away in a hash definition if the key is a valid variable name or a number. This works just as well:

var airport = {
LOXZ: "Zeltweg",
};

There's also an alternative way to access hash members if the keys are valid variable names: <tt>airport.LOXI</tt> can be used instead of <tt>airport["LOXI"]</tt>. There is a difference, though, which is described in the next section.

Note that assigning a hash (or a vector) to another variable does never ''copy'' the contents. It only creates another reference to the same data structure. So manipulating the hash via its new name does in fact change the one, original hash.

var a = airport;
a.LOXL = "Linz"; # same as airport.LOXL!
print(airport.LOXL); # prints now "Linz", not "Linz Hoersching"

(True copies of vectors can be made by assigning a full slice: <tt>var copy = vec[:]</tt>. There's no such method for hashes.)

=== Self-reference: "<tt>me</tt>" ===

Values stored in a hash can be of any type, even of type ''function''. Member functions ("methods") can reference their own enclosing hash via reserved keyword <tt>me</tt>. This is comparable to the <tt>this</tt> keyword in C++ classes, or the <tt>self</tt> keyword in Python.

var value = "test";

var data = {
value: 23, # scalar member variable
write1: func { print(value); }, # function member
write2: func { print(me.value); }, # function member
};

data.write1(); # prints "test"
data.write2(); # prints 23

The above example is already a simple form of an object. It has its own variable namespace (''data''), its own methods, and it can be passed around by-reference as one unit. Such classes are sometimes called ''singleton classes'', as they are unique, with no independent class instances. They mostly serve as a way to keep data and methods nicely encapsulated within a Nasal module. Often they contain a method for initializing, which is usually called <tt>init</tt>.

=== Inheritance: "<tt>parents</tt>" ===

What we learned about <tt>me</tt> in the last section is only the half truth. "me" doesn't only reference an object's own hash, but also one or more parent hashes. <tt>parents</tt> is another reserved keyword. It denotes a vector referencing other object hashes, which are "inherited" that way.

var parent_object = {
value: 123,
};

var object = {
parents: [parent_object],
write: func { print(me.value) },
};

object.write(); # prints 123

Even though <tt>object</tt> itself doesn't contain a member <tt>value</tt>, it finds and uses the one of its parent object. <tt>parents</tt> is a vector that can contain several parent objects. These are then searched in the order from left to right, until a matching member variable or method is found. Each of the parents can itself have parents, which are all recursively searched.

In the section about hashes it was said that hash members can be accessed in two alternative ways, and that's also true for methods. <tt>object.write()</tt> could also be called as <tt>object["write"]()</tt>. But only in the first form will members also be searched in parent hashes if not found in the base hash, whereas the second form creates an error if it's not a direct member.

=== Creating class instances ===

With <tt>me</tt> and <tt>parents</tt> we can implement a class object and create independent instances from that:

var Class = {
write: func { print(me.value); },
increment: func { me.value += 1; },
};

var instance1 = { parents: [Class], value: 123 };
var instance2 = { parents: [Class], value: 456 };

instance1.write(); # prints 123
instance2.write(); # prints 456

As you can see, the two class instances are separate, independent objects, which share another object as parent -- they "inherit" from object <tt>Class</tt>. One can now easily change members of any of these three objects. The following will redefine the parent's <tt>write</tt> method, and all instances will automatically use this new version:

Class.write = func { print("VALUE = " ~ me.value) }

But one can also add a method to just one instance:

instance1.write = func { print("VALUE = " ~ me.value) }

Because <tt>instance1</tt> does now have its own <tt>write</tt> method, the parents won't be searched for one, so <tt>Class.write</tt> is now overridden by <tt>instance1</tt>'s own method. Nothing changed for <tt>instance2</tt> -- it will still only find and use <tt>Class.write</tt> via its parent.

Note, the we couldn't create a class instance by simple assignment, because, as we learned above, this wouldn't create a separate copy of the Class object. All "instances" would reference the same hash!

var bad_instance1 = Class; # bad
var bad_instance2 = Class; # bad

bad_instance1.value = 123; # sets Class.value to 123
bad_instance2.value = 456; # sets Class.value to 456

bad_instance1.write(); # prints 456, not 123

=== Constructor ===

Defining each class instance by explicitly creating a hash with parents is clumsy. It is nicer to have a function that does that for us. Then we can also use function arguments to initialize members of this instance.

var new_class = func(val) {
return { parents: [Class], value: val };
}

var instance1 = new_class(123);
var instance2 = new_class(456);

instance1.write(); # prints 123
instance2.write(); # prints 456

Because the class generating function <tt>new_class()</tt> really belongs to class <tt>Class</tt>, it would be nicer to put it into the class hash as well. In this case we call it a class "constructor", and as a convention, give it the name ''new''. It could have any name, though, and there could be more than one constructor.

var Class = {
new: func(val) {
return { parents: [Class], value: val };
},
write: func {
print("VALUE=" ~ me.value);
},
};

var instance1 = Class.new(123);
var instance2 = Class.new(456);

As you can see, <tt>new()</tt> doesn't return a copy of <tt>Class</tt>, but rather a small hash that contains only a list of parents and one individual member <tt>value</tt>.

Classes aren't always as simple as in our example. Usually they contain several members, of which some may have yet to be calculated in the constructor. In that case it's easier to create a local object hash first, and to let the constructor finally return it. Such local hashes are often named <tt>m</tt> (as a short reference to <tt>me</tt>), or <tt>obj</tt>.

var Class = {
new: func(val) {
var m = { parents: [Class] };
m.value = val;
return m;
},
write: func {
print("VALUE=" ~ me.value);
},
};

This last example is the most frequently used form of class definitions in FlightGear-Nasal.

=== Destructor ===

There's no such thing in Nasal. In other languages destructors are automatically called when the class gets destroyed, so that memory and other resources that were allocated by the constructor can be freed. In Nasal that's all done by the Garbage Collector (GC), anyway. In the FlightGear context, however, there ''are'' resources that should get freed. Listeners should get removed, self-calling functions ("loops") stopped. For that it's recommended to create a destructor function and to call that manually. Such functions are often called <tt>del</tt>, similar to Python and to pair nicely with the three-letter constructor name <tt>new</tt>.

=== Multiple inheritance ===

A class can inherit from one or more other classes. It can then access all methods and class members of all parent classes, but also override them and add additional members.

var A = { # simple class A
new: func {
return { parents: [A] };
},
alpha: func print("\tALPHA"),
test: func print("\tthis is A.test"),
};

var B = { # simple class B
new: func(v) { # ... whose constructor takes an argument
return { parents: [B], value: v };
},
bravo: func print("\tBRAVO"),
test: func print("\tthis is B.test"),
write: func print("\tmy value is: ", me.value),
},

var C = { # class C that inherits ...
new: func(v) {
return { parents: [C, A.new(), B.new(v)] }; # ... from class A and B
},
charlie: func print("\tCHARLIE"),
test: func print("\tthis is C.test"), # overrides A.test() and B.test()
};

print("A instance");
var a = A.new();
a.alpha();

print("B instance");
var b = B.new(123);
b.bravo();
b.write();

print("C instance");
var c = C.new(456);
c.alpha(); # use alpha from the A parent
c.bravo(); # use bravo from the B parent
c.charlie(); # use charlie from C itself
c.test(); # use C.test(), which overrides A.test() and B.test()
c.write();

Even if a class overrides a method of a parent with the same name, the parent's version can still be accessed via <tt>parents</tt> vector.

c.test() # use C.test()
c.parents[0].test(); # use C.test()
c.parents[1].test(); # use A.test()
c.parents[2].test(); # use B.test()

=== More on methods ===

Methods are function members of a class hash. They can access other class members via the <tt>me</tt> variable, which is a reference to the class hash. For this reason, a method returning <tt>me</tt> can be used like the class itself, and one can apply further methods to the return value:

var Object = {
new: func(coords...) {
return { parents: [Object], coords: coords };
},
rotate: func(angle) {
# do the rotation
return me;
},
scale: func(factor) {
# do the scaling
return me;
},
translate: func(x, y) {
# do the translation
return me;
},
};

var triangle = Object.new([0, 0], [10, 0], [5, 7]);
triangle.translate(-9, -4).scale(5).rotate(33).translate(9, 4); # concatenated methods thanks to "me"

<tt>me</tt>, however, is only known in the scope of the class. If a method is to be called as a listener callback or a timer function, <tt>me</tt> has to get wrapped in a function, so that it's stored in the function closure.

var Manager = {
new: func {
return { parents: [Manager] };
},
start_timers: func {
settimer(do_stuff, 5); # BAD: there's no "do_stuff" function in the scope
settimer(me.do_stuff, 5); # BAD: function exists, but "me" won't be known
# when the timer function is actually executed
settimer(func me.do_stuff(), 5); # GOOD: new function object packs "me" in the closure

setlistener("/sim/foo", func me.do_stuff()); # GOOD (same as with timers)
},
do_stuff: func {
print("doing stuff");
},
};

var manager = Manager.new();
manager.start_timers();

== Exception handling ==

<tt>die()</tt> aborts a function with an error message.

var divide = func(a, b) {
if (b == 0)
die("division by zero");
return a / b; # this line won't be reached if b == 0
}

die() is also used internally by built-in extension functions or Nasal core functions. <tt>getprop("/4me")</tt>, for example, dies with an error message ''"name must begin with alpha or '_'"''. Now assume we want to write a dialog where the user can type a property path into an input field, and we display the property's value in a popup dialog. What if the user typed an invalid path and we hand that over to <tt>getprop()</tt>? We don't want Nasal to abort our code because of that. We want to display a nice error message instead. The <tt>call()</tt> function can catch <tt>die()</tt> exceptions:

var value = getprop(property); # dies if 'property' is invalid
var value = call(func getprop(property), nil, var err = []); # catches invalid-property-exception and continues

The second line calls getprop(property) just like the first, and returns its value. But if 'property' was invalid then the <tt>call()</tt> function catches the exception and sets the 'err' vector instead. That vector remains empty on success.

if (size(err))
print("ERROR: bad property ", property, " (", err[0], ")"); # err[0] contains the die() message
else
print("value of ", property, " is ", value);

The first argument of <tt>call()</tt> is a function object, the second a vector of function arguments (or ''nil''), and the third a vector where the function will return a possible error. For more information on the <tt>call()</tt> function see the [http://plausible.org/nasal/lib.html Nasal library documentation].

<tt>die()</tt> doesn't really care about what its argument is. It doesn't have to be a string, and can be any variable, for example a class. This can be used to pass values through a chain of functions.

var Error = { # exception class
new: func(msg, number) {
return { parents: [Error], message: msg, number: number };
},
};

var A = func(a) {
if (a < 0)
die(Error.new("negative argument to A", a)); # throw Error
return "A received " ~ a;
}

var B = func(val) {
var result = A(val);
print("B finished"); # this line is not reached if A threw an exception
return result;
}

var value = call(B, [-4], var err = []); # try B(-4)

if (size(err)) { # catch (...)
print("ERROR: ", err[0].message, "; bad value was ", err[0].number);
die(err[0]); # re-throw
} else {
print("SUCCESS: ", value);
}

== Listeners and Signals ==

Listeners are callback functions that are attached to property nodes. They are triggered whenever the node is written to, or, depending on the listener type, also when children are added or removed, and when children are written to. Unlike polling loops, listeners don't have the least effect on the frame rate when they aren't triggered, which makes them preferable to monitor properties that aren't written to frequently. Unfortunately, listeners don't work on so-called "tied" properties when the node value isn't set via property methods. (You can spot such tied properties by Ctrl-clicking the "." entry in the property browser: they are marked with a "T".) Most of the FDM properties are "tied".

=== <tt>setlistener()</tt> ===

Syntax:

var listener_id = setlistener(<property>, <function> [, <startup=0> [, <runtime=1>]]);

The first argument is a property node object (<tt>props.Node()</tt> hash) or a property path. Because the node hash depends on the props.nas module being loaded, <tt>setlistener()</tt> calls need to be deferred when used in an $FG_ROOT/Nasal/*.nas file, usually by calling them in a <tt>settimer(func {}, 0)</tt> construction. To avoid that, one can use the raw <tt>_setlistener()</tt> function directly, for which <tt>setlistener()</tt> is a wrapper. The raw function does only accept node paths (e.g. "/sim/menubar/visibility"), but not props.Node() objects.

The second argument is a function object (not a function call!). The <tt>func</tt> keyword turns code into a function object.

The third argument is optional. If it is non-null, then it causes the listener to be called initially. This is useful to let the callback function pick up the node value at startup.

The fourth argument is optional, and defaults to 1. This means that the callback function will be executed whenever the property is written to, independent of the value. If the argument is set to 0, then the function will only get triggered if a value other than the current value is written to the node. This should be used for properties that are written to in every frame, although the written value is mostly the same. If the argument is 2, then also write access to children will get reported, as well as the creation and removal of children nodes.

<tt>setlistener()</tt> returns a unique listener id on success, and <tt>nil</tt> on error. The id is nothing else than a counter that is 0 for the first Nasal listener, 1 for the second etc. You need this id number to remove the listener. Most listeners are never removed, so that one doesn't assign the return value, but simply drop it.

Listener callback functions can access up to four values via regular function arguments, the first two of which are property nodes in the form of a <tt>props.Node()</tt> object hash.

Syntax:

callback([<changed_node> [, <listened_to_node> [, <operation> [, <is_child_event>]]]])

=== <tt>removelistener()</tt> ===

Syntax:

var num_listeners = removelistener(<listener id>);

<tt>removelistener()</tt> takes one argument: the unique listener id that a <tt>setlistener()</tt> call returned. It returns the number of remaining active Nasal listeners on success, <tt>nil</tt> on error, or -1 if a listener function applies <tt>removelistener()</tt> to itself. The fact that a listener can remove itself, can be used to implement a one-shot listener function:

var L = setlistener("/some/property", func {
print("I can only be triggered once.");
removelistener(L);
});

=== Listener Examples ===

The following example attaches an anonymous callback function to a "signal". The function will be executed when FlightGear is closed.

setlistener("/sim/signals/exit", func { print("bye!") });

Instead of an anonymous function, a named function can be used as well:

var say_bye = func { print("bye") }
setlistener("/sim/signals/exit", say_bye);

Callback functions can access up to four parameters which are handed over via regular function arguments. Usually there's only the first used, or none at all, like in the above example. The following code attaches the monitor_course() function to a gps property.

var monitor_course = func(course) {
print("Monitored course set to ", course.getValue());
}
var i = setlistener("instrumentation/gps/wp/leg-course-deviation-deg", monitor_course);

# here the listener is active

removelistener(i); # remove that listener again

The function object doesn't need to be a separate, external function -- it can also be code that is made a function object directly in the <tt>setlistener()</tt> call:

setlistener("/sim/signals/exit", func { print("bye") }); # say "bye" on exit

Attaching a function to a node that is specified as <tt>props.Node()</tt> hash:

var node = props.globals.getNode("/sim/signals/click", 1);
setlistener(node, func { gui.popupTip("don't click here!") });

Sometimes it is desirable to call the listener function initially, so that it can pick up the node value. In the following example a listener watches the view number, and turns the HUD on in cockpit view, and off in all other views. It doesn't only do that on writing to "view-number", but also once when the listener gets attached, thanks to the third argument "1":

setlistener("/sim/current-view/view-number", func(n) {
setprop("/sim/hud/visibility[0]", n.getValue() == 0);
}, 1);

There's no limit for listeners on a node. Several functions can get attached to one node, just as one function can get attached to several nodes. Listeners may write to the node they are listening to. This will not make the listener call itself causing an endless recursion.

=== Signals ===

In addition to "normal" nodes, there are "signal" nodes that were created solely for the purpose of having listeners attached:

<tt>/sim/signals/exit</tt> ... set to "true" on quitting FlightGear

<tt>/sim/signals/reinit</tt> ... set to "true" right before resetting FlightGear (Shift-Esc), and to "false" afterwards

<tt>/sim/signals/click</tt> ... set to "true" after a mouse click at the terrain. Hint that the geo coords for the click spot were updated and can be retrieved from /sim/input/click/{longitude-deg,latitude-deg,elevation-ft,elevation-m}

<tt>/sim/signals/screenshot</tt> ... set to "true" right before the screenshot is taken, and set to "false" after it. Can be used to hide and reveal dialogs etc.

<tt>/sim/signals/nasal-dir-initialized</tt> ... set to "true" after all Nasal "library" files in $FG_ROOT/Nasal/ were loaded and executed. It is only set once and can only be used to trigger listener functions that were defined in one of the Nasal files in that directory. After that signal was set
Nasal starts loading and executing aircraft Nasal files, and only later are <tt>settimer()</tt> functions
called and the next signal is set:

<tt>/sim/signals/fdm-initialized</tt> ... set to "true" when then FDM has just finished its initialization

<tt>/sim/signals/reinit-gui</tt> ... set to "true" when the GUI has just been reset (e.g. via Help menu). This
is used by the gui.Dialog class to reload Nasal-loaded XML dialogs.

<tt>/sim/signals/frame</tt> ... triggered at the beginning of each iteration of the main loop (a.k.a. "frame"). This is meant for debugging purposes. Normally, one would just use a settimer() with interval 0 for the same effect. The difference is that the signal is guaranteed to be raised at a defined moment, while the timer call may change when subsystems are re-ordered.

== FlightGear extension functions ==

=== <tt>print()</tt> ===
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");

=== <tt>getprop()</tt> ===
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>);

Example:

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

=== <tt>setprop()</tt> ===
Sets a property value for a given node path string. Always returns nil.

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

All arguments but the last are concatenated to a path string. The last value is written to the respective node. If the node isn't writable, then an error message is printed to the console.

Examples:

setprop("/sim/current-view/view-number", 2);
setprop("/controls/engines/engine[", i, "]/reverser", 1);

=== <tt>settimer()</tt> ===
Runs a function after a given simulation (default) or real time in seconds.

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

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.

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

=== <tt>systime()</tt> ===
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.

=== <tt>carttogeod()</tt> ===
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]);

# outputs
lat=37.49999782141546 lon=-122.6999914632327 alt=998.6042055172776

=== <tt>geodtocart()</tt> ===
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]);

# outputs
x=-2737504.667684828 y=-4264101.900993474 z=3862172.834656495

=== <tt>geodinfo()</tt> ===
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.

var lat = getprop("/position/latitude-deg");
var lon = getprop("/position/longitude-deg");
var info = geodinfo(lat, lon);

if (info != nil) {
print("the terrain under the aircraft is at elevation ", info[0], " m");
if (info[1] != nil)
print("and it is ", info[1].solid ? "solid ground" : "covered by water");
}

A full data set looks like this:

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

# outputs
[ 106.9892101062052, { light_coverage : 0, bumpiness : 0.5999999999999999, load_resistance : 1e+30,
solid : 0, names : [ "Lake", "Pond", "Reservoir", "Stream", "Canal" ], friction_factor : 1,
rolling_friction : 1.5 } ]

=== <tt>parsexml()</tt> ===

This function is an interface to the built-in 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> ]]]]);

<start-elem> ... called for every starting tag with two arguments: the tag name, and an attribute hash
<end-elem> ... called for every ending tag with one argument: the tag name
<data> ... called for every piece of data with one argument: the data string
<pi> ... called for every "processing information" with two args: target and data string

<ret> ... the return value is nil on error, and the <path> otherwise

Example:

var start = func(name, attr) {
print("starting tag ", name);
foreach (var a; keys(attr))
print("\twith attribute ", a, "=", attr[a]);
}
var end = func(name) { print("ending tag ", name) }
var data = func(data) { print("data=", data) }
var pi = func(target, data) { print("processing instruction: target=", target, " data=", data) }
parsexml("/tmp/foo.xml", start, end, data, pi);

== Tips ==
How to play sounds using Nasal script?

The same way one would do animations using Nasal;

Adjust properties in Nasal (they may be "private" properties in your own
subtree of the property list, say /tmp/<aircraft>) and let the sound
configuration file act on those properties.
(from flightgear-devel)

==Related content==
* [[:Category:Nasal|Category:Nasal]]

=== External links ===
* http://www.plausible.org/nasal

2008-10-12T12:48:30Z

Melchior FRANZ: remove seldom needed optional livery_update interval argument; set menu index to 100, as 10 is rather unsafe and could overwrite a system enty

[[Image:Livery_selection_dialog.jpg|thumb|270px|The livery selection dialog of the [[Sikorsky S76C]].]]

On this page we describe how you make use of a script to get a '''livery selection dialog''' for a [[Aircraft|plane]] in [[FlightGear]]. To get new liveries into [[FlightGear CVS]], you need to have them availabe with this script.

The examples are based on the [[Robin DR400]].

==Files==
There are a few files we need to make (or edit), namely:
* <tt>dr400-set.xml</tt>
* <tt>Models/dr400.xml</tt>
* <tt>Nasal/liveries.nas</tt>
We also have to make a new directory to store our liveries in. Let's make it <tt>Aircraft/DR400/Models/Liveries</tt>.

===Models/Liveries===
For every livery we need to make a file. Let's say we got a Rescue livery, we than need to make a file called Rescue.xml into our <tt>Models/Liveries directory</tt>.

<?xml version="1.0"?><nowiki>
</nowiki>
<PropertyList>
<sim>
<model>
<livery>
<name type="string">Default</name>
<texture>texture.rgb</texture>
</livery>
</model>
</sim>
</PropertyList>

===dr400.xml===
The first part is related to the nasal script. <tt>("Aircraft/DR400/Models/Liveries");</tt> points FlightGear to the directory where we store our liveries. This is a different directory for every plane, but there should be only one folder for one plane, containing all the liveries for that plane.

<nasal>
<load>
var livery_update = aircraft.livery_update.new("Aircraft/DR400/Models/Liveries");
</load><nowiki>
</nowiki>
<unload>
livery_update.stop();
</unload>
</nasal>

The second part is very important and probably the hardest of all. We need to set which parts of the model should change when you select a new livery. To find the object-names, you could make use of software like [[Blender]] or [[AC3D]]. The <tt><texture>S76livery.rgb</texture></tt> part points FlightGear to the livery that should be shown on startup.

'''Warning: be sure you don't have a slash (/) in front of sim/model/livery in the <property-base> tag! Otherwise, all planes will get the same livery!'''

<animation>
<type>material</type>
<object-name>LHgeardoor</object-name>
<object-name>RHgeardoor</object-name>
<object-name>S76C</object-name>
<object-name>RF.door</object-name>
<object-name>LF.door</object-name>
<object-name>Rr.Door</object-name>
<object-name>Lr.Door</object-name>
<object-name>RHbaggage</object-name>
<object-name>LHbaggage</object-name>
<object-name>RHfrtgeardoor</object-name>
<object-name>LHfrtgeardoor</object-name>
<property-base>sim/model/livery</property-base>
<texture-prop>texture</texture-prop>
<texture>texture.rgb</texture>
</animation>

===liveries.nas===
The only thing you might change in the nasal file is the directory of the liveries.

aircraft.livery.init("Aircraft/DR400/Models/Liveries");

===s76c-set.xml===
<model>
<path>Aircraft/DR400/models/dr400.xml</path>
<livery>
<file type="string">default</file>
</livery>
</model>

To make a nice button in the [[menubar]] we need to add the following code, just above the <tt></sim></tt> tag.

<menubar>
<default>
<menu n="100">
<label>Robin DR 400</label>
<enabled type="bool">true</enabled>
<item>
<label>Select Livery</label>
<binding>
<command>nasal</command>
<script>aircraft.livery.dialog.toggle()</script>
</binding>
</item>
</menu>
</default>
</menubar>

[[Category:Aircraft enhancement]]
[[Category:Modeling]]