Nasal library: Difference between revisions

|text = Calls the given function with the given arguments and returns the result.  This function is very useful as it allows much more control over function calls and catches any errors or {{func link|die}} calls that would normally trigger run-time errors cancelling execution of the script otherwise.  

|param5text = A vector to append errors to.  If the called function generates an error, the error, place, and line will be written to this.  These errors can be printed using {{func link|debug.printerror()|ext=http://sourceforge.net/p/flightgear/fgdata/ci/next/tree/Nasal/debug.nas}}.

|text = Compiles the specified code string and returns a function object bound to the current lexical context.  If there is an error, the function dies, with the argument to {{func link|die}} being '''filename'''.

|text = Terminates execution and unwinds the stack.  The place and the line will be added to the '''error'''.  This invokes the same internal exception handler used for internal runtime errors. Use this to signal fatal errors, or to implement exception handling. The error thrown (including internal runtime errors) can be caught with {{func link|call}}.

|text = Returns a vector containing the elements in the input '''vector''' sorted in according to the rule given by '''function'''. Implemented with the ANSI C {{func link|qsort()|ext=http://www.cplusplus.com/reference/cstdlib/qsort/}}, <code>sort()</code> is stable.  This means that if the rules in the first example are used, equal elements in the output vector will appear in the same relative order as they do in the input.  It is run in a loop, so '''function''' is run several times.

|text = Creates and returns a string formatted using ANSI C {{Func link|vsnprintf()|ext=http://en.cppreference.com/w/c/io/vfprintf}} <ref>

|text = Similar the {{func link|subvec}}, but operates on strings. Computes and returns a substring. The first argument specifies a string, the second is the index of the start of a substring, the optional third argument specifies a length (the default is to return the rest of the string from the start).

|text = This function is a wrapper for the C++ {{func link|abort()|ext=http://www.cplusplus.com/reference/cstdlib/abort/}} function. It simply aborts FlightGear with an error, which varies depending on the operating system. This function should not really be used; instead, please use the "exit" [[Fgcommands|fgcommand]], which will exit FlightGear more gracefully (see example below).

|example1text = This example adds a new fgcommand and then runs it. Although it executes a simple {{func link|print}} statement, any valid Nasal code can be used.

|param1text = Start waypoint, in the form of a waypoint ghost, such as that provided by {{func link|flightplan}}.

|text = Returns either true if the condition evaluates as true, or aborts with a {{func link|die}} call, which can be customised.

|param2text = Optional message that will be used in any {{func link|die}} call. Defaults to "assertion failed!"

Also, you should not delay <code>cmdarg()</code> using {{func link|maketimer}}, {{func link|settimer}} or {{func link|setlistener}}, because it will return an unrelated property.

|example5text = Creates a new waypoint and adds it to the flight plan. Waypoints of the type "pseudo" are then removed from the flight plan, including the new waypoint. The {{func link|print}} statements show this.

|example2text = Creates a new waypoint and appends it to the flight plan. This way point is then removed; the {{func link|print}} statements prove this.

|text = Runs an fgcommand. See also {{readme file|commands}} and [[Bindings]] for more information. See {{flightgear file|src/Main/fg_commands.cxx|l=1425}} for the full list of fgcommands. Note that fgcommands generated by {{func link|addcommand}} can also be run using this function. Also, the full list of fgcommands depends on the version of FlightGear you have. Returns 1 (true) if the fgcommand succeeded or 0 (false) if it failed.

|text = Concatenates a message and logs it with a given priority level. Unlike {{func link|print}} and {{func link|printlog}}, message outputted by this function will be logged in your <code>[[Commonly used debugging tools#fgfs.log|fgfs.log]]</code> file as coming from the Nasal file itself rather than from {{flightgear file|src/Scripting/NasalSys.cxx}}.

Unlike {{func link|settimer}}, which it replaces, <code>maketimer()</code> provides more control over the timer. In addition, it can help reduce memory usage.

|text = Creates and prints a formatted string. For a description of its arguments, see {{func link|sprintf}} (it is, in fact, implemented using <code>sprintf()</code>).

|param1text = ID of listener as returned by {{func link|setlistener}}.

|text = Creates a listener which will be triggered when the given property is changed (depending on the '''type'''). A unique integer ID is returned; this can later be used as the argument to {{func link|removelistener}}.

* Using {{func link|removelistener}} when they are not needed any more.

{{note|Improper use of <code>settimer()</code> may cause resource leaks. It is also highly recommended that the newer {{func link|maketimer}} should be used instead of this function.}}  

|text = Makes the pseudorandom number generator (see {{func link|rand}}) generate a new {{wikipedia|random seed|noicon=1}} based on time. Returns 0.

{{note|1=High resolution timers under Windows can produce inaccurate or fixed sub-millisecond results.<ref>{{cite web|url=http://forum.flightgear.org/viewtopic.php?f=30&t=29259|title=Nasal: systime() ??!?|author=Necolatis|date=Apr 2nd, 2016}}</ref> This is due to the underlying {{func link|GetSystemTimeAsFileTime()|ext=https://msdn.microsoft.com/en-us/library/windows/desktop/ms724397(v=vs.85).aspx}} API call, which depends on hardware availability of suitable high resolution timers. See also [https://msdn.microsoft.com/en-us/library/windows/desktop/dn553408(v=vs.85).aspx Acquiring high-resolution time stamps]}}