https://wiki.flightgear.org/w/api.php?action=feedcontributions&feedformat=atom&user=Chris-barryFlightGear wiki - User contributions [en]2026-04-05T05:53:05ZUser contributionsMediaWiki 1.39.6https://wiki.flightgear.org/w/index.php?title=Nasal_library&diff=92156Nasal library2016-02-01T03:45:49Z<p>Chris-barry: /* subvec() */</p>
<hr />
<div>{{Nasal Navigation}}<br />
<br />
This page documents the global '''library functions''' of FlightGear's built-in scripting language, [[Nasal]]. This includes ''[[#Core library functions|core library functions]]'', which were included in Nasal before its integration into FlightGear, and ''[[#Extension functions|extension functions]]'', which have been subsequently added, and are specifically designed for FlightGear. The main relevant folders in [[Git]] are:<br />
* {{flightgear file|src/Scripting}}<br />
* {{simgear file|simgear/nasal}}<br />
<br />
{{tip|Copy & paste the examples into your [[Nasal Console]] and execute them to see what they do.|width=70%}}<br />
<br />
== Core library functions ==<br />
This is the list of the basic '''core library functions.''' Most of these functions were part of the original Nasal library (before its integration in to FlightGear), while some have been added or changed over time. See also:<br />
* http://plausible.org/nasal/lib.html ([http://web.archive.org/web/20101010094553/http://plausible.org/nasal/lib.html archive])<br />
* {{simgear file|simgear/nasal/lib.c}} ([http://sourceforge.net/p/flightgear/simgear/ci/next/log/?path=/simgear/nasal/lib.c history])<br />
<br />
=== append() ===<br />
{{Nasal doc<br />
|syntax = append(vector, element[, element[, ...]]);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=42|t=Source}}<br />
|text = This function appends, or adds, the given element(s) to the end of the vector given in the first argument. Returns the vector operated on.<br />
|param1 = vector<br />
|param1text = The vector to which the arguments will be appended.<br />
|param2 = element<br />
|param2text = An element to be added to the vector.<br />
|example1 = <br />
var vector = [1, 2, 3]; # Initialize the vector<br />
append(vector, 4); # Append the number 4 to the end of the vector<br />
debug.dump(vector); # Print the contents of the vector<br />
|example2 = <br />
var vector = [1, 2, 3]; # Initialize the vector<br />
append(vector, 4, 5, 6); # Append the numbers 4, 5, and 6 to the end of the vector<br />
debug.dump(vector); # Print the contents of the vector<br />
}}<br />
<br />
=== bind() ===<br />
{{Nasal doc<br />
|syntax = bind(function, locals[, outer_scope]);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=502|t=Source}}<br />
|text = This creates a new function object. A function in Nasal is three things: the actual code, a hash/namespace of local variables available to the function namespace, and the closure object of that namespace. These correspond to the three arguments respectively.<br />
|param1 = function<br />
|param1text = Function to evaluate.<br />
|param2 = locals<br />
|param2text = Hash containing values that will become the namespace (first closure) for the function.<br />
|param3 = outer_scope<br />
|param3text = Optional function which is bound to the next closure. This can be bound to yet another, making a linked list.<br />
|example1 = # This is a namespace/hash with a single member, named "key," which is initialized to 12 <br />
var Namespace = {<br />
key: 12<br />
};<br />
<br />
# This is different namespace/hash containing a function<br />
# dividing a variable "key" (which is unavailable/nil in this namespace) by 2<br />
var AnotherNamespace = {<br />
ret: func {<br />
key /= 2;<br />
}<br />
};<br />
<br />
# To see that key is not available, try to call AnotherNamespace.ret() first<br />
call(AnotherNamespace.ret, [], nil, nil, var errors = []);<br />
if(size(errors)){<br />
print("Key could not be divided/resolved!");<br />
debug.printerror(errors);<br />
}<br />
<br />
# Associate the AnotherNamespace.ret() function with the first namespace<br />
# so that "key" is now available<br />
var function = bind(AnotherNamespace.ret, Namespace);<br />
<br />
# Invoke the new function<br />
function();<br />
<br />
# Print out the value of Namespace.key<br />
# It was changed to 12 from 6 by AnotherNamespace.ret()<br />
print(Namespace.key);<br />
}}<br />
<br />
=== call() ===<br />
{{Nasal doc<br />
|syntax = call(func[, args[, me[, locals[, error]]]);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=247|t=Source}}<br />
|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. <br />
|param1 = func<br />
|param1text = Function to execute.<br />
|param2 = args<br />
|param2text = Vector containing arguments to give to the called function.<br />
|param3 = me<br />
|param3text = <code>'''me'''</code> reference for the function call (i.e., for method calls). If given, this will override any <code>'''me'''</code> value existing in the namespace (locals argument).<br />
|param4 = locals<br />
|param4text = A hash with key/value pairs that will be available to the called function, typically used as the namespace for the function to be called.<br />
|param5 = error<br />
|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}}.<br />
|example1 =<br />
# prints "Called from call()"<br />
call(func {<br />
print("Called from call()");<br />
});<br />
|example2 =<br />
# prints "a = 1 : b = 2<br />
call(func(a, b){<br />
print("a = ", a, " : b = ", b);<br />
},<br />
[1, 2]<br />
);<br />
|example3 =<br />
var Hash = {<br />
new: func {<br />
var m = { parents: [Hash] };<br />
<br />
m.el1 = "string1";<br />
m.el2 = "string2";<br />
<br />
return m;<br />
}<br />
};<br />
<br />
# prints "me.el1 = string1", then "me.el2 = string2" on the next line<br />
call(func(a, b){ <br />
print("me.el", a, " = ", me["el" ~ a]); <br />
print("me.el", b, " = ", me["el" ~ b]);<br />
},<br />
[1, 2],<br />
Hash.new()<br />
);<br />
|example4 =<br />
# prints the value of math.pi<br />
call(func {<br />
print(pi);<br />
}, nil, nil, <br />
math<br />
);<br />
|example5 =<br />
call(func {<br />
print(math.ip); # math.ip doesn't exist<br />
}, nil, nil, nil,<br />
var errs = []<br />
);<br />
debug.printerror(errs); # The error is caught and printed using debug.printerror()<br />
}}<br />
<br />
=== caller() ===<br />
{{Nasal doc<br />
|syntax = caller([level]);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=404|t=Source}}<br />
|text = Returns a vector containing a record from the current call stack. The level numbering starts from the currently executing function (level 0). Level 1 (the default) is the caller of the current function, and so on. The result is a four-element vector containing a hash of local variables, the function object, the source, and the line number. <br />
|param1 = level<br />
|param1text = Optional integer specifying the stack level to return a result from. Defaults to 1 (the caller of the currently executing function.<br />
|example1 =<br />
var myFunction = func(a, b){<br />
debug.dump(caller(0)[0]); # prints a hash of local variables, including arguments a and b<br />
return 2 * 2;<br />
};<br />
<br />
print("2 x 2 = ", myFunction(2, 2));<br />
|example2 =<br />
var get_arg_value = func(){<br />
print("Argument to myFunc = ", caller(1)[0]['a']); # print the value of myFunc's single argument, using caller()<br />
};<br />
<br />
var myFunc = func(a){<br />
get_arg_value();<br />
};<br />
<br />
myFunc(3);<br />
|example3text = This is a real example taken from {{fgdata file|Nasal/canvas/MapStructure.nas}}. Function <code>r()</code> (above the TODOs) returns a hash with the key/value pairs as per its arguments. For example, something like this is returned: <code>{ name: "<name>", vis: 1, zindex: nil }</code>.<br />
|example3 =<br />
var MapStructure_selfTest = func() {<br />
var temp = {};<br />
temp.dlg = canvas.Window.new([600,400],"dialog");<br />
temp.canvas = temp.dlg.createCanvas().setColorBackground(1,1,1,0.5);<br />
temp.root = temp.canvas.createGroup();<br />
var TestMap = temp.root.createChild("map");<br />
TestMap.setController("Aircraft position");<br />
TestMap.setRange(25); # TODO: implement zooming/panning via mouse/wheel here, for lack of buttons :-/<br />
TestMap.setTranslation(<br />
temp.canvas.get("view[0]")/2,<br />
temp.canvas.get("view[1]")/2<br />
);<br />
var r = func(name,vis=1,zindex=nil) return caller(0)[0];<br />
# TODO: we'll need some z-indexing here, right now it's just random<br />
# TODO: use foreach/keys to show all layers in this case by traversing SymbolLayer.registry direclty ?<br />
# maybe encode implicit z-indexing for each lcontroller ctor call ? - i.e. preferred above/below order ?<br />
foreach(var type; [r('TFC',0),r('APT'),r('DME'),r('VOR'),r('NDB'),r('FIX',0),r('RTE'),r('WPT'),r('FLT'),r('WXR'),r('APS'), ] ) <br />
TestMap.addLayer(factory: canvas.SymbolLayer, type_arg: type.name,<br />
visible: type.vis, priority: type.zindex,<br />
);<br />
}; # MapStructure_selfTest<br />
}}<br />
<br />
=== chr() ===<br />
{{Nasal doc<br />
|syntax = chr(code);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=175|t=Source}}<br />
|text = Returns a character as per the single argument. Extended ASCII is supported (see http://www.asciitable.com/ for a list of supported characters), although this may vary between different systems. For a list of the most commonly used characters, see the {{wikipedia|ASCII#ASCII printable code chart|ASCII printable code chart}} ('''Dec''' column). The following table lists supported control characters, along with their equivalent control characters in Nasal strings. {{Note|In Nasal, only strings enclosed with double-quotes (<code>"string"</code>) supports control chracters. Strings in single quotes (<code>'string'</code>) do not.}}<br />
{{{!}} class="wikitable"<br />
! Code !! Name !! Equivalent to<br />
{{!-}}<br />
{{!}} 10 {{!!}} {{Wikipedia|Newline}} {{!!}} <code>\n</code><br />
{{!-}}<br />
{{!}} 9 {{!!}} {{Wikipedia|Tab key#Tab characters|Horizontal tab}} {{!!}} <code>\t</code><br />
{{!-}}<br />
{{!}} 13 {{!!}} {{Wikipedia|Carriage return}} {{!!}} <code>\r</code><br />
{{!}}}<br />
|param1 = code<br />
|param1text = Integer character code for the desired glyph.<br />
|example1 = print("Code 65 = ", chr(65)); # prints "Code 65 = A"<br />
|example2text = This example displays all of the characters in a list, in the format <code>Code '''n''' = >'''char'''<</code>, '''n''' being the index, and '''char''' being the character.<br />
|example2 =<br />
for(var i = 0; i <= 255; i += 1){<br />
print("Code ", i, " = >", chr(i), "<");<br />
}<br />
}}<br />
<br />
=== closure() ===<br />
{{Nasal doc<br />
|syntax = closure(func[, level]);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=421|t=Source}}<br />
|text = Returns the hash table containing the lexical namespace of the given function. The level numbering start with level 0 being the namespace of '''func'''. <br />
|param1 = func<br />
|param1text = Function to evaluate.<br />
|param2 = level<br />
|param2text = Optional integer specifying the scope level. Defaults to 0 (the namespace of '''func''').<br />
|example1 =<br />
var get_math_e = func {<br />
return e; # return the value of math.e<br />
}<br />
<br />
var myFunction = bind(get_math_e, math); # bind get_math_e to the math namespace, so that math.e is immediately available to get_math_e<br />
debug.dump(closure(myFunction)); # print the namespace of get_math_e<br />
<br />
print(myFunction());<br />
}}<br />
<br />
=== cmp() ===<br />
{{Nasal doc<br />
|syntax = cmp(a, b);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=112|t=Source}}<br />
|text = Compares two strings, returning -1 if '''a''' is less than '''b''', 0 if they are identical and 1 if '''a''' is greater than '''b'''. <br />
|param1 = a<br />
|param1text = First string argument for comparison.<br />
|param2 = b<br />
|param2text = Second string argument for comparison.<br />
|example1 = print(cmp("1", "two")); # prints -1<br />
|example2 = print(cmp("string", "string")); # prints 0<br />
|example3 = print(cmp("one", "2")); # prints 1<br />
|example4 = print(cmp("string1", "string2")); # prints -1<br />
}}<br />
<br />
=== compile() ===<br />
{{Nasal doc<br />
|syntax = compile(code[, filename]);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=220|t=Source}}<br />
|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'''.<br />
|param1 = code<br />
|param1text = String containing Nasal code to be compiled.<br />
|param2 = filename<br />
|param2text = Optional string used for error messages/logging. Defaults to <code><compile></code><br />
|example1 = <br />
var myCode = 'print("hello");';<br />
var helloFunc = compile(myCode, "myCode");<br />
helloFunc();<br />
|example2text = <code>compile</code> is very convenient to support Nasal loaded from other files. For instance, [[PropertyList XML files]] (such as GUI dialogs) may contain embedded Nasal sections that need to be parsed, processed and compiled. For an example of how to do this, save the below XML code as <tt>''[[$FG_ROOT]]/gui/dialogs/test.xml''</tt>.<br />
<syntaxhighlight land="xml"><br />
<?xml version="1.0"?><br />
<br />
<PropertyList><br />
<br />
<nasal><![CDATA[<br />
print("You have FlightGear v", getprop("/sim/version/flightgear"));<br />
]]></nasal><br />
<br />
</PropertyList><br />
</syntaxhighlight><br />
Now, start FlightGear and execute this code in the [[Nasal Console]].<br />
|example2 =<br />
# Build the path<br />
var FGRoot = getprop("/sim/fg-root");<br />
var filename = "/gui/dialogs/test.xml";<br />
var path = FGRoot ~ filename;<br />
<br />
var blob = io.read_properties(path);<br />
var script = blob.getValues().nasal; # Get the nasal string<br />
<br />
# Compile the script. We're passing the filename here for better runtime diagnostics <br />
var code = call(func {<br />
compile(script, filename);<br />
}, nil, nil, var compilation_errors = []);<br />
<br />
if(size(compilation_errors)){<br />
die("Error compiling code in: " ~ filename);<br />
}<br />
<br />
# Invoke the compiled script, equivalent to code(); <br />
# We're using call() here to detect errors:<br />
call(code, [], nil, nil, var runtime_errors = []);<br />
<br />
if(size(runtime_errors)){<br />
die("Error calling code compiled loaded from: " ~ filename);<br />
}<br />
}}<br />
<br />
=== contains() ===<br />
{{Nasal doc<br />
|syntax = contains(hash, key);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=184|t=Source}}<br />
|text = Returns 1 (True) if the hash contains the specified key, or 0 (False) if not.<br />
|param1 = hash<br />
|param1text = The hash to search in.<br />
|param2 = key<br />
|param2text = The scalar to be searched for, contained as a key in the hash.<br />
|example1 =<br />
# Initialize a hash<br />
var hash = {<br />
element: "value"<br />
};<br />
print(contains(hash, "element") ? "Yes" : "No"); # This will print "Yes"<br />
|example2 =<br />
# Initialize a hash<br />
var hash = {<br />
element: "value"<br />
};<br />
print(contains(hash, "element2") ? "Yes" : "No"); # This will print "No"<br />
}}<br />
<br />
=== delete() ===<br />
{{Nasal doc<br />
|syntax = delete(hash, key);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=83|t=Source}}<br />
|text = Deletes the key from the hash if it exists. Operationally, this is identical to setting the hash value specified by the key to <code>'''nil'''</code>, but this variant potentially frees storage by deleting the reference to the key and by shrinking the hash. Returns the hash that has been operated on.<br />
|param1 = hash<br />
|param1text = The hash from which to delete the key.<br />
|param2 = key<br />
|param2text = The scalar to be deleted, contained as a key in the hash.<br />
|example1 =<br />
# Initialize the hash<br />
var hash = {<br />
element1: "value1",<br />
element2: "value2"<br />
};<br />
delete(hash, "element1"); # Delete element1<br />
debug.dump(hash); # prints the hash, which is now minus element1<br />
}}<br />
<br />
=== die() ===<br />
{{Nasal doc<br />
|syntax = die(error);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=288|t=Source}}<br />
|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}}.<br />
|param1 = error<br />
|param1text = String describing the error.<br />
:{{inote|This parameter is technically optional, but it is highly recommended to use it.}}<br />
|example1 = <br />
print("Will print");<br />
die("Don't go any further!"); <br />
print("Won't print"); # Will not be printed because die() stops the process<br />
}}<br />
<br />
=== find() ===<br />
{{Nasal doc<br />
|syntax = find(needle, haystack);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=450|t=Source}}<br />
|text = Finds and returns the index of the first occurrence of the string '''needle''' in the string '''haystack''', or -1 if no such occurrence was found.<br />
|param1 = needle<br />
|param1text = String to search for.<br />
|param2 = haystack<br />
|param2text = String to search in.<br />
|example1 = print(find("c", "abcdef")); # prints 2<br />
|example2 = print(find("x", "abcdef")); # prints -1<br />
|example3 = print(find("cd", "abcdef")); # prints 2<br />
}}<br />
<br />
=== ghosttype() ===<br />
{{Nasal doc<br />
|syntax = ghosttype(ghost);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=207|t=Source}}<br />
|text = Returns a string containing either a descriptive name of a ghost (a raw C/C++ object), or a unique id (the pointer to the C/C++ <code>naGhostType</code> instance) if no name has been set. Ghost is an acronym that stands for '''G'''arbage-collected '''H'''andle to '''O'''ut'''S'''ide '''T'''hingy.<br />
|param1 = ghost<br />
|param1text = Ghost to return a description for.<br />
|example1 = print(ghosttype(airportinfo())); # prints "airport"<br />
}}<br />
<br />
=== id() ===<br />
{{Nasal doc<br />
|syntax = id(object);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=570|t=Source}}<br />
|text = Returns a string containing information on the type and ID of the object provided in the single argument. The information is returned in the form of <code>'''<type>''':'''<id>'''</code>, where '''<type>''' is the type of object, and '''<id>''' is the ID.<br />
|param1 = object<br />
|param1text = Can be either of a string, a vector, a hash, a code, a function, or a ghost.<br />
|example1 = print(id("A")); # prints "str:000000001624A590"<br />
}}<br />
<br />
=== int() ===<br />
{{Nasal doc<br />
|syntax = int(number);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=90|t=Source}}<br />
|text = Returns the integer part of the numeric value of the single argument, or <code>'''nil'''</code> if none exists.<br />
|param1 = number<br />
|param1text = Number or string with just a number in it to return an integer from.<br />
|example1 = print(int(23)); # prints "23"<br />
|example2 = print(int(23.123)); # prints "23"<br />
|example3 = debug.dump(int("string")); # prints "nil"<br />
}}<br />
<br />
=== keys() ===<br />
{{Nasal doc<br />
|syntax = keys(hash);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=33|t=Source}}<br />
|text = Returns a vector containing the list of keys found in the single hash argument. <br />
|param1 = hash<br />
|param1text = The hash to return the keys from.<br />
|example1 = <br />
# Initialize a hash<br />
var hash = {<br />
element1: "value",<br />
element2: "value"<br />
};<br />
debug.dump(keys(hash)); # print the vector<br />
}}<br />
<br />
=== left() ===<br />
{{Nasal doc<br />
|syntax = left(string, length);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=149|t=Source}}<br />
|version = 2.12<br />
|text = Returns a substring of '''string''', starting from the left.<br />
|param1 = string<br />
|param1text = String to return part of.<br />
|param2 = length<br />
|param2text = Integer specifying the length of the substring to return.<br />
|example1 = print(left("string", 2)); # prints "st"<br />
}}<br />
<br />
=== num() ===<br />
{{Nasal doc<br />
|syntax = num(number);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=102|t=Source}}<br />
|text = Returns the numerical value of the single string argument, or <code>'''nil'''</code> if none exists. <br />
|param1 = number<br />
|param1text = String with just a number in it to return a number from.<br />
|example1 = print(num("23")); # prints "23"<br />
|example2 = print(num("23.123")); # prints "23.123"<br />
|example3 = debug.dump(num("string")); # prints "nil"<br />
}}<br />
<br />
=== pop() ===<br />
{{Nasal doc<br />
|syntax = pop(vector);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=50|t=Source}}<br />
|text = Removes and returns the last element of the single vector argument, or <code>'''nil'''</code> if the vector is empty. <br />
|param1 = vector<br />
|param1text = Vector to remove an element from.<br />
|example1 = <br />
var vector = [1, 2, 3];<br />
pop(vector);<br />
debug.dump(vector); # prints "[1, 2]"<br />
|example2 = <br />
var vector = [1, 2, 3];<br />
debug.dump(pop(vector)); # prints "3"<br />
|example3 = <br />
var vector = [];<br />
debug.dump(pop(vector)); # prints "nil"<br />
}}<br />
<br />
=== right() ===<br />
{{Nasal doc<br />
|syntax = right(string, length);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=161|t=Source}}<br />
|version = 2.12<br />
|text = Returns a substring of '''string''', starting from the right.<br />
|param1 = string<br />
|param1text = String to return part of.<br />
|param2 = length<br />
|param2text = Integer specifying the length of the substring to return.<br />
|example1 = print(right("string", 2)); # prints "ng"<br />
}}<br />
<br />
=== setsize() ===<br />
{{Nasal doc<br />
|syntax = setsize(vector, size);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=56|t=Source}}<br />
|text = Sets the size of a vector. The first argument specifies a vector, the second a number representing the desired size of that vector. If the vector is currently larger than the specified size, it is truncated. If it is smaller, it is padded with <code>'''nil'''</code> entries. Returns the vector operated upon. <br />
|param1 = vector<br />
|param1text = The vector to be operated on.<br />
|param2 = size<br />
|param2text = The desired size of the vector in number of entries.<br />
|example1 = <br />
var vector = [1, 2, 3]; # Initialize a vector<br />
setsize(vector, 4);<br />
debug.dump(vector); # print the vector<br />
|example2 = <br />
var vector = [1, 2, 3]; # Initialize a vector<br />
setsize(vector, 2);<br />
debug.dump(vector); # print the vector<br />
}}<br />
<br />
=== size() ===<br />
{{Nasal doc<br />
|syntax = size(object);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=23|t=Source}}<br />
|text = Returns the size of the single argument. For strings, this is the length in bytes. For vectors, this is the number of elements. For hashes, it is the number of key/value pairs. If the argument is <code>'''nil'''</code> or a number, this error will be thrown: <code>object has no size()</code>.<br />
|param1 = object<br />
|param1text = Object to find the size of. Must be a string, a vector or a hash.<br />
|example1 = <br />
var string = "string";<br />
print(size(string)); # prints "6"<br />
|example2 =<br />
var vector = [1, 2, 3];<br />
print(size(vector)); # prints "3"<br />
|example3 =<br />
var hash = {<br />
element1: "value1",<br />
element2: "value2",<br />
element3: "value3"<br />
};<br />
print(size(hash)); # prints "3"<br />
}}<br />
<br />
=== sort() ===<br />
{{Nasal doc<br />
|syntax = sort(vector, function);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=542|t=Source}}<br />
|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.<br />
|param1 = vector<br />
|param1text = Input vector to sort.<br />
|param2 = function<br />
|param2text = Function according to which the elements will be sorted by. It should take two arguments and should return one of 1, 0, or -1.<br />
{{{!}} class="wikitable"<br />
! Return value !! Meaning<br />
{{!-}}<br />
{{!}} less than 0 {{!!}} first argument should go before second argument<br />
{{!-}}<br />
{{!}} 0 {{!!}} first argument equals second argument<br />
{{!-}}<br />
{{!}} greater than 0 {{!!}} first argument should go after second argument<br />
{{!}}}<br />
<br />
|example1text = This example sorts elements from smallest to greatest.<br />
|example1 = <br />
var sort_rules = func(a, b){<br />
if(a < b){<br />
return -1; # A should before b in the returned vector<br />
}elsif(a == b){<br />
return 0; # A is equivalent to b <br />
}else{<br />
return 1; # A should after b in the returned vector<br />
}<br />
}<br />
debug.dump(sort([3, 2, 5, 6, 4, 1], sort_rules)); # prints "[1, 2, 3, 4, 5, 6]"<br />
|example1text = This example sorts elements from greatest to smallest.<br />
|example2 = <br />
# Outputs the elements in reverse order (greatest to smallest)<br />
var sort_rules = func(a, b){<br />
if(a < b){<br />
return 1; # -1 in the above example<br />
}elsif(a == b){<br />
return 0;<br />
}else{<br />
return -1; # 1 in the above example<br />
}<br />
}<br />
debug.dump(sort([3, 2, 5, 6, 4, 1], sort_rules)); # prints "[6, 5, 4, 3, 2, 1]"<br />
}}<br />
<br />
=== split() ===<br />
{{Nasal doc<br />
|syntax = split(delimiter, string);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=460|t=Source}}<br />
|text = Splits the input string into a vector of substrings bounded by occurrences of the delimiter substring.<br />
|param1 = delimiter<br />
|param1text = String that will split the substrings in the returned vector.<br />
|param2 = string<br />
|param2text = String to split up.<br />
|example1 = debug.dump(split("cd", "abcdef")); # prints "['ab', 'ef']"<br />
|example2 = debug.dump(split(".", "3.2.0")); # prints "[3, 2, 0]"<br />
|example3 = debug.dump(split("/", "path/to/file")); # prints "['path', 'to', 'file']"<br />
}}<br />
<br />
=== sprintf() ===<br />
{{Nasal doc<br />
|syntax = sprintf(format[, arg[, arg, [...]]]);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=355|t=Source}}<br />
|text = Creates and returns a string formatted using ANSI C {{Func link|vsnprintf()|ext=http://en.cppreference.com/w/c/io/vfprintf}} <ref><br />
{{Cite web<br />
|url = http://sourceforge.net/p/flightgear/simgear/ci/next/tree/simgear/nasal/lib.c#l308<br />
|title = fgdata/simgear/simgear/nasal/lib.c, line 308<br />
|accessdate = October 2015<br />
}}<br />
</ref>. Below is a table of supported format specifiers.<br />
{{{!}} class="wikitable" width="75%"<br />
{{!}}+ %[flags][width][.precision]specifier<br />
! colspan="2" {{!}} Flags<br />
{{!-}}<br />
! Flag !! Output<br />
{{!-}}<br />
{{!}} <code>+</code> {{!!}} Forces to precede the result with a plus or minus sign ('''+''' or '''-''') even for positive numbers. By default, only negative numbers are preceded with a '''-''' sign.<br />
{{!-}}<br />
{{!}} ''space'' {{!!}} Prefixes non-signed numbers with a space.<br />
{{!-}}<br />
{{!}} <code>-</code> {{!!}} Left-align the output of this placeholder (the default is to right-align the output) when the width option is specified.<br />
{{!-}}<br />
{{!}} <code>0</code> {{!!}} Use 0 instead of spaces to pad a field when the width option is specified.<br />
{{!-}}<br />
{{!}} <code>#</code> {{!!}} Used with <code>o</code>, <code>x</code> or <code>X</code> specifiers the value is preceded with <tt>0</tt>, <tt>0x</tt> or <tt>0X</tt> respectively for values different than zero. Used with <code>e</code>, <code>E</code> and <code>f</code>, it forces the written output to contain a decimal point even if no digits would follow. By default, if no digits follow, no decimal point is written. Used with <code>g</code> or <code>G</code> the result is the same as with <code>e</code> or <code>E</code> but trailing zeros are not removed.<br />
{{!-}}<br />
! colspan="2" {{!}} Width<br />
{{!-}}<br />
{{!}} colspan="2" {{!}} Integer specifying the minimum number of characters to be returned.<br />
{{!-}}<br />
! colspan="2" {{!}} Precision<br />
{{!-}}<br />
{{!}} colspan="2" {{!}} Integer preceded by a dot specifying the number of decimal places to be written.<br />
{{!-}}<br />
! colspan="2" {{!}} Specifiers<br />
{{!-}}<br />
! Specifier !! Output<br />
{{!-}}<br />
{{!}} <code>d</code>, <code>i</code> {{!!}} Signed decimal number.<br />
{{!-}}<br />
{{!}} <code>%</code> {{!!}} Percent (%) character.<br />
{{!-}}<br />
{{!}} <code>c</code> {{!!}} A single character assigned to a character code, the code given in an integer argument. See http://www.asciitable.com/ for a list of supported characters and their codes.<br />
{{!-}}<br />
{{!}} <code>o</code> {{!!}} Unsigned integer as an octal number.<br />
{{!-}}<br />
{{!}} <code>u</code> {{!!}} Unsigned decimal integer.<br />
{{!-}}<br />
{{!}} <code>x</code>, <code>X</code> {{!!}} Unsigned integer as a hexadecimal number. If <code>x</code> is used, any letters in the number are lowercase, while <code>X</code> gives uppercase.<br />
{{!-}}<br />
{{!}} <code>e</code>, <code>E</code> {{!!}} Double value in scientific notation (i.e., ''[-]ddd.ddd'''e'''[+/-]ddd''), with an exponent being denoted by <tt>e</tt> or <tt>E</tt> depending on whether an upper or lowercase is used respectively.<br />
{{!-}}<br />
{{!}} <code>f</code> {{!!}} Floating-point number, in fixed decimal notation, by default with 6 decimal places.<br />
{{!-}}<br />
{{!}} <code>F</code> {{!!}} Appears to be available<ref><br />
{{Cite web<br />
|url = http://sourceforge.net/p/flightgear/simgear/ci/next/tree/simgear/nasal/lib.c#l389<br />
|title = fgdata/simgear/simgear/nasal/lib.c, line 389<br />
|accessdate = October 2015<br />
}}<br />
</ref>, but doesn't work.<br />
{{!-}}<br />
{{!}} <code>g</code>, <code>G</code> {{!!}} Double in either normal or exponential notation, whichever is more appropriate for its magnitude. <code>g</code> uses lower-case letters, <code>G</code> uses upper-case letters. This type differs slightly from fixed-point notation in that insignificant zeroes to the right of the decimal point are not included. Also, the decimal point is not included on whole numbers.<br />
{{!}}}<br />
<br />
|param1 = format<br />
|param1text = String specifying the format. Can be used with or without a format specifiers. See below for examples.<br />
|param2 = arg<br />
|param2text = Argument specifying a value to replace a format placeholder (such as <code>%d</code>) in the format string. Not required if there are no format specifiers.<br />
<br />
|example1 = print(sprintf("%i", 54)); # prints "54"<br />
|example2 = print(sprintf("Pi = %+.10f", math.pi)); # prints "Pi = +3.1415926536"<br />
|example3 = <br />
print(sprintf("%6d", 23)); # prints " 23"<br />
print(sprintf("%06d", 23)); # prints "000023"<br />
|example4 =<br />
var FGVer = getprop("/sim/version/flightgear");<br />
print(sprintf("You have FlightGear v%s", FGVer)); # prints "You have FlightGear v<your version>"<br />
|example5 = <br />
print(sprintf("Hexadecimal 100000 = %X", 100000)); # prints "Hexadecimal 100000 = 186A0"<br />
print(sprintf("Hexadecimal 100000 = %x", 100000)); # prints "Hexadecimal 100000 = 186a0"<br />
|example6 = print(sprintf("Code 65 is %c", 65)); # prints "Code 65 is A"<br />
|example7 = <br />
print(sprintf("%e", 54)); # prints "5.400000e+001"<br />
print(sprintf("%E", 54)); # prints "5.400000E+001"<br />
|example8 = print(sprintf("%o", 54)); # prints "66"<br />
|example9 = print(sprintf("50%% of 100 is %i", 100 / 2)); # prints "50% of 100 is 50"<br />
}}<br />
<br />
=== streq() ===<br />
{{Nasal doc<br />
|syntax = streq(a, b);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=107|t=Source}}<br />
|text = Tests the string values of the two arguments for equality. This function is needed because the <code>'''=='''</code> operator (see [[Nasal_Operators#Equality|Nasal Operators]]) tests for numeric equality first. If either or both the arguments are not strings, 0 (False) will be returned. Returns either 0 (False) or 1 (True). {{Note|This function is rarely required in typical code.}}<br />
|param1 = a<br />
|param1text = First argument for testing equality.<br />
|param2 = b<br />
|param2text = Second argument for testing equality.<br />
|example1 = print(streq("0", "0")); # prints "1" (True)<br />
|example2 = <br />
print(0 == 0.0); # prints "1" (True)<br />
print(streq("0", "0.0")); # prints "0" (False)<br />
}}<br />
<br />
=== substr() ===<br />
{{Nasal doc<br />
|syntax = substr(string, start [, length]);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=129|t=Source}}<br />
|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).<br />
|param1 = string<br />
|param1text = String to return a substring from.<br />
|param2 = start<br />
|param2text = Integer specifying the start of a substring.<br />
|param3 = length<br />
|param3text = Optional argument specifying the length of the substring. Defaults to the end of the string.<br />
|example1 = print(substr("abcde", 1, 3)); # prints "bcd"<br />
|example2 = print(substr("abcde", 1)); # prints "bcde"<br />
|example3 = print(substr("abcde", 2, 1)); # prints "c"<br />
}}<br />
<br />
=== subvec() ===<br />
{{Nasal doc<br />
|syntax = subvec(vector, start[, length]);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=63|t=Source}}<br />
|text = Returns a sub-range of a vector. The first argument specifies a vector, the second a starting index, and the optional third argument indicates a length (the default is to the end of the vector). <br />
|param1 = vector<br />
|param1text = The vector to take the sub-vector from.<br />
|param2 = start<br />
|param2text = The starting point of the sub-vector within the given vector.<br />
|param3 = length<br />
|param3text = Optional argument specifying the length of the sub-vector, from the starting point.<br />
'''Notes:'''<br />
<ol><br />
<li><br />
Omitting the ''vector'' and ''start'' arguments is not an error (possibly it should be) but the return value is ''nil''.<br />
</li><br />
<li><br />
A negative ''start'' argument ''is'' an error. This seems wrong. Perhaps the language designer could comment.<br />
</li><br />
<li><br />
A value of ''start'' greater than ''size(vector)'' causes an error. A value equal to ''size(vector)'' returns an empty vector.<br />
</li><br />
<li><br />
If the value of ''length'' is greater than ''size(vector) - start'' then it is ignored. That is, all elements from ''start'' to the end of ''vector'' are returned. If ''length'' is zero then an empty vector is returned. A negative value of ''length'' causes an error.<br />
</ol><br />
<br />
|example1 = <br />
var vector = [1, 2, 3];<br />
debug.dump(subvec(vector, 0)); # prints "[1, 2, 3]"<br />
|example2 = <br />
var vector = [1, 2, 3];<br />
debug.dump(subvec(vector, 1)); # prints "[2, 3]"<br />
|example3 = <br />
var vector = [1, 2, 3];<br />
debug.dump(subvec(vector, 1, 1)); # prints "[2]"<br />
}}<br />
<br />
=== typeof() ===<br />
{{Nasal doc<br />
|syntax = typeof(object);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=193|t=Source}}<br />
|text = Returns a string indicating the whether the object is <code>'''nil'''</code>, a scalar (number or string), a vector, a hash, a function, or a ghost.<br />
|param1 = object<br />
|param1text = Object to return the type of.<br />
|example1 = <br />
var object = nil;<br />
print(typeof(object)); # prints "nil"<br />
|example2 = <br />
var object = "Hello world!";<br />
print(typeof(object)); # prints "scalar"<br />
|example3 = <br />
var object = math.pi;<br />
print(typeof(object)); # prints "scalar"<br />
|example4 = <br />
var object = [1, 2, 3];<br />
print(typeof(object)); # prints "vector"<br />
|example5 = <br />
var object = {};<br />
print(typeof(object)); # prints "hash"<br />
|example6 = <br />
var object = func {};<br />
print(typeof(object)); # prints "func"<br />
|example7 =<br />
var object = airportinfo();<br />
print(typeof(object)); # prints "ghost"<br />
}}<br />
<br />
== Extension functions ==<br />
The '''extension functions''' are global functions that have been added to Nasal since its integration into FlightGear. Unlike the core library functions, they are generally specifically designed to interact directly with FlightGear. Extension functions come from three source files:<br />
* {{flightgear file|src/Scripting/NasalPositioned.cxx}}<br />
* {{flightgear file|src/Scripting/NasalSys.cxx}}<br />
* {{fgdata file|Nasal/globals.nas}}<br />
<br />
=== abort() ===<br />
{{Nasal doc<br />
|syntax = abort();<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=565|t=Source}}<br />
|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).<br />
|example1text = This example will immediately stop FlightGear with an error, such as "FlightGear has stopped working."<br />
|example1 = abort();<br />
|example2text = For exiting FlightGear in a better way, please use the following code:<br />
|example2 = fgcommand("exit");<br />
}}<br />
<br />
=== abs() ===<br />
{{Nasal doc<br />
|syntax = abs(number);<br />
|source = {{fgdata file|Nasal/globals.nas|t=Source}}<br />
|text = This simple function returns the {{wikipedia|absolute value|noicon=1}} of the provided number.<br />
|param1 = number<br />
|param1text = This argument is required and should be a number.<br />
|example1 = print(abs(1)); # prints "1"<br />
|example2 = print(abs(-1)); # prints "1"<br />
}}<br />
<br />
=== addcommand() ===<br />
{{Nasal doc<br />
|syntax = addcommand(name, code);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=648|t=Source}}<br />
|version = 2.12<br />
|text = {{see also|Howto:Add new fgcommands to FlightGear}}<br />
<br />
This function enables the addition of a new custom [[fgcommands|fgcommand]] to FlightGear from within Nasal. An fgcommand created using this method can be used in exactly the same way as the built-in fgcommands. Also, an fgcommand created via this method will always return True or 1, like all other fgcommands.<br />
|param1 = name<br />
|param1text = This will become the name of the new fgcommand. Must be a string.<br />
|param2 = code<br />
|param2text = The code that will be executed when the fgcommand is run. Must be a function.<br />
|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.<br />
|example1 = addcommand("myFGCmd", func {<br />
print("fgcommand 'myFGCmd' has been run.");<br />
});<br />
fgcommand("myFGCmd");<br />
|example2text = This example demonstrates how parameters are defined in a new fgcommand.<br />
|example2 = addcommand("myFGCmd", func(node){<br />
print(node.getNode("number").getValue()); # prints the value of "number," which is 12<br />
});<br />
fgcommand("myFGCmd", props.Node.new({"number": 12}));<br />
}}<br />
<br />
=== airportinfo() ===<br />
{{Nasal doc<br />
|syntax = airportinfo();<br />
airportinfo(type);<br />
airportinfo(id);<br />
airportinfo(lat, lon[, type]);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1024|t=Source}}<br />
|text = Function for retrieval of airport, heliport, or seaplane base information. It returns a Nasal ghost; however, its structure is like that of a Nasal hash. The following information is returned:<br />
* '''lon''': Longitude of the location.<br />
* '''lat''': Latitude of the location.<br />
* '''has_metar''': True or false depending whether the airport has a [[METAR]] code defined for it.<br />
* '''elevation''': Elevation of the location in metres.<br />
* '''id''': ICAO code of the airport (or ID of the seaplane base/heliport).<br />
* '''name''': Name of the airport/heliport/seaplane base.<br />
* '''runways'''<br />
** '''<runway name>'''<br />
*** '''stopway''': Length of the runway's stopway (the area before the threshold) in metres. Will return 0 if there is none.<br />
*** '''threshold''': Length of the runway's {{wikipedia|displaced threshold}} in metres. Will return 0 if there is none.<br />
*** '''lat''': Latitude of the runway.<br />
*** '''lon''': Longitude of the runway.<br />
*** '''width''': Width of the runway in metres.<br />
*** '''heading''': Heading of the runway.<br />
*** '''length''': Length of the runway in metres.<br />
<br />
Information is extracted in the same way as accessing members of a Nasal hash. For example:<br />
<syntaxhighlight lang="nasal"><br />
# prints to lengths of the runways of the nearest airport in feet and metres<br />
var info = airportinfo();<br />
print("-- Lengths of the runways at ", info.name, " (", info.id, ") --");<br />
foreach(var rwy; keys(info.runways)){<br />
print(rwy, ": ", math.round(info.runways[rwy].length * M2FT), " ft (", info.runways[rwy].length, " m)");<br />
}<br />
</syntaxhighlight><br />
<br />
Note that searches for locations that are a long way away (e.g., the nearest seaplane base to the middle of the Sahara) may cause FlightGear to pause for an amount of time.<br />
|param1 = id<br />
|param1text = The {{wikipedia|International Civil Aviation Organization airport code|ICAO code|noicon=1}} of an airport to retrieve information about.<br />
|param2 = type<br />
|param2text = When this argument is used, the function will return the closest airport of a certain type. Can be one of "heliport," "seaport," or "airport" (default).<br />
: {{inote|Running this function without any parameters is equivalent to this:<br />
: <syntaxhighlight lang="nasal"><br />
airportinfo("airport");<br />
</syntaxhighlight><br />
}}<br />
|param3 = lat ''and'' lon<br />
|param3text = When these parameters are used, the function will return information on the nearest airport, heliport or seaplane base (depending on the '''type''' parameter) to those coordinates.<br />
|example1 = var info = airportinfo();<br />
print("Nearest airport: ", info.name, " (", info.id, ")"); # prints the name and ICAO code of the nearest airport<br />
|example2 = var info = airportinfo("heliport");<br />
print("Elevation of the nearest heliport: ", math.round(info.elevation * M2FT), " ft"); # prints the elevation and name of the nearest heliport<br />
|example3 = var info = airportinfo("KSQL");<br />
print("-- Runways of ", info.name, " (", info.id, "): --");<br />
foreach(var rwy; keys(info.runways)) {<br />
print(rwy); # prints the runways of KSQL<br />
}<br />
|example4 = var info = airportinfo(37.81909385, -122.4722484);<br />
print("Coordinates of the nearest airport: ", info.lat, ", ", info.lon); # print the name and ICAO of the nearest airport to the Golden Gate Bridge<br />
|example5 = var info = airportinfo(37.81909385, -122.4722484, "seaport");<br />
print("Nearest seaplane base: ", info.name, " (", info.id, ")"); # print the name and ID of the nearest seaplane base to the Golden Gate Bridge<br />
|example6text = This example prints the all information from an <code>airportinfo()</code> call.<br />
|example6 = var info = airportinfo("KSFO");<br />
print(info.name);<br />
print(info.id);<br />
print(info.lat);<br />
print(info.lon);<br />
print(info.has_metar);<br />
print(info.elevation);<br />
foreach(var rwy; keys(info.runways)){<br />
print("-- ", rwy, " --");<br />
print(info.runways[rwy].lat);<br />
print(info.runways[rwy].lon);<br />
print(info.runways[rwy].length);<br />
print(info.runways[rwy].width);<br />
print(info.runways[rwy].heading);<br />
print(info.runways[rwy].stopway);<br />
print(info.runways[rwy].threshold);<br />
}<br />
}}<br />
<br />
=== airwaysRoute() ===<br />
{{Nasal doc<br />
|syntax = airwaysRoute(start, end[, type]);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1933|t=Source}}<br />
|text = {{see also|Nasal Flightplan}}<br />
This function returns a vector containing waypoints between two given waypoints. The returned waypoints are ghosts, but can be accessed in the same way as a Nasal hash. See [[Nasal Flightplan]] for more information.<br />
|param1 = start<br />
|param1text = Start waypoint, in the form of a waypoint ghost, such as that provided by {{func link|flightplan}}.<br />
|param2 = end<br />
|param2text = Same as above.<br />
|param3 = type<br />
|param3text = Instructs the function to compute a high level route (when set to "highlevel"), or a low level route (when set to "lowlevel"). Defaults to "highlevel."<br />
|example1text = In the [[route manager]] dialog, add two waypoints to the flightplan, ideally ones that are far apart (tip: use the [[Map]] for this). Then run this code in your Nasal Console.<br />
|example1 = var fp = flightplan();<br />
var start = fp.getWP(0);<br />
var end = fp.getWP(fp.getPlanSize() - 1);<br />
var rt = airwaysRoute(start, end);<br />
foreach(var wp; rt){<br />
print(wp.wp_name); # print the waypoints in the computed route<br />
}<br />
|example2text = Exactly the same as above, but computes a low level path.<br />
|example2 = var fp = flightplan();<br />
var start = fp.getWP(0);<br />
var end = fp.getWP(fp.getPlanSize() - 1);<br />
var rt = airwaysRoute(start, end, "lowlevel");<br />
foreach(var wp; rt){<br />
print(wp.wp_name); # print the waypoints in the computed route<br />
}<br />
}}<br />
<br />
=== assert() ===<br />
{{Nasal doc<br />
|syntax = assert(condition[, message]);<br />
|source = {{fgdata file|Nasal/globals.nas|t=Source}}<br />
|version = 3.2<br />
|text = Returns either true if the condition evaluates as true, or aborts with a {{func link|die}} call, which can be customised.<br />
|param1 = condition<br />
|param1text = Condition to evaluate.<br />
|param2 = message<br />
|param2text = Optional message that will be used in any {{func link|die}} call. Defaults to "assertion failed!"<br />
|example1 = var a = 1;<br />
var b = 2;<br />
print(assert(a < b)); # prints "1" (true)<br />
|example2 = var a = 1;<br />
var b = 2;<br />
assert(a > b, 'a is not greater than b'); # aborts with a custom error message<br />
}}<br />
<br />
=== carttogeod() ===<br />
{{Nasal doc<br />
|syntax = carttogeod(x, y, z);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=945|t=Source}}<br />
|text = Converts {{wikipedia|ECEF|Earth-centered, Earth-fixed}} coordinates (x, y and z) to {{wikipedia|geodetic coordinates}} (latitude, longitude, and altitude). A vector is returned containing latitude and longitude, both in degrees, and altitude, which is returned in metres above the equatorial radius of Earth as defined by the {{wikipedia|WGS 84}} (6,378,137 metres).<ref>{{simgear file|simgear/math/sg_geodesy.hxx|l=43}}</ref><br />
|param1 = x<br />
|param1text = Mandatory x-axis value, in metres.<br />
|param2 = y<br />
|param2text = Mandatory y-axis value, in metres.<br />
|param3 = z<br />
|param3text = Mandatory z-axis value, in metres.<br />
|example1 = var (lat, lon, alt) = carttogeod(6378137, 0, 0); # point is the intersection of the prime meridian and equator.<br />
print("Latitude: ", lat); # prints lat, lon and alt, which are all zero, see above<br />
print("Longitude: ", lon);<br />
print("Altitude: ", alt);<br />
}}<br />
<br />
=== cmdarg() ===<br />
{{Nasal doc<br />
|private = _cmdarg()<br />
|syntax = cmdarg();<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=513|t=Part 1}} {{!}} {{fgdata file|Nasal/globals.nas|t=Part 2}}<br />
|text = <code>cmdarg()</code> returns the property root of certain types of XML files. These could be nodes in the [[Property Tree]], or temporary and/or non-public nodes outside the Property tree. <br />
It is used by Nasal scripts embedded in XML files. It returns a <code>props.Node</code> object (see {{fgdata file|Nasal/props.nas}}), and you can use all of its methods on the returned value. <code>cmdarg()</code> should only be used in four types/places of XML files:<br />
* Bindings: This is needed so that the value of a joystick's axis can be accessed internally.<br />
* Dialogs: This will return the root of the dialog in the Property Tree. This is useful for dialogs that are created/modified procedurally (e.g. for populating/changing widgets while loading the dialog). <br />
* Embedded Canvases: The Nasal code behind [[Canvas]] windows [[Howto:Adding a canvas to a GUI dialog|embedded in PUI dialogs]] can use it to accessing the root directory of their Canvas.<br />
* Animation XML files: If the animation XML file is used in an AI/MP model, <code>cmdarg()</code> will return the root of the AI model in the <code>/ai/models/</code> directory. Examples: <code>/ai/models/aircraft[3]/</code>, <code>/ai/models/multiplayer[1]/</code><br />
<br />
You should not use <code>cmdarg()</code> in places other than those stated above. Although it won't cause an error, it will return the value of the last legitimate <code>cmdarg()</code> call. <br />
<br />
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.<br />
|example1 = fgcommand("dialog-show", {"dialog-name": "cmdarg-demo"});<br />
|example1text = <br>This example demonstrates the usage of <code>cmdarg()</code> in a binding. Save the below XML snippet as <tt>[[$FG_ROOT]]/gui/dialogs/cmdarg-demo.xml</tt>. Then run the Nasal snippet below in your [[Nasal Console]]. Upon clicking {{button|Close}}, a message will be printed sowing the root of the binding in the Property Tree.<br />
<syntaxhighlight lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<br />
<PropertyList><br />
<br />
<name>cmdarg-demo</name><br />
<layout>vbox</layout><br />
<br />
<text><br />
<label>Click "Close" to activate the demonstration (a message in the console).</label><br />
</text><br />
<br />
<button><br />
<legend>Close</legend><br />
<binding><br />
<command>nasal</command><br />
<script>print("Button binding root: '" ~ cmdarg().getPath() ~ "'");</script><br />
</binding><br />
<binding><br />
<command>dialog-close</command><br />
</binding><br />
</button><br />
<br />
</PropertyList><br />
</syntaxhighlight><br />
|example2text = This example demonstrates the usage of <code>cmdarg()</code> in Nasal code within dialogs. Open <tt>[[$FG_ROOT]]/gui/dialogs/cmdarg-demo.xml</tt> from the previous example, copy & paste the code below, and save it. Then run the same Nasal snippet as the previous example in your Nasal Console. If you click {{button|Click me!}}, the button's label will change to "I've been changed!"<br />
<syntaxhighlight lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<br />
<PropertyList><br />
<br />
<name>cmdarg-demo</name><br />
<layout>vbox</layout><br />
<br />
<text><br />
<label>Click "Click me!" to activate the demonstration (the button's label will change).</label><br />
</text><br />
<br />
<button><br />
<legend>Click me!</legend><br />
<binding><br />
<command>nasal</command><br />
<script>change_label();</script><br />
</binding><br />
</button><br />
<br />
<button><br />
<legend>Close</legend><br />
<binding><br />
<command>dialog-close</command><br />
</binding><br />
</button><br />
<br />
<nasal><br />
<open><![CDATA[<br />
var dlg_root = cmdarg();<br />
var dlg_name = {"dialog-name": "cmdarg-demo"};<br />
var change_label = func {<br />
dlg_root.getNode("button[0]/legend").setValue("I've been changed!");<br />
fgcommand("dialog-close", dlg_name);<br />
fgcommand("dialog-show", dlg_name);<br />
}<br />
]]></open><br />
</nasal><br />
<br />
</PropertyList><br />
</syntaxhighlight><br />
|example3text = For an example of <code>cmdarg()</code> used with Canvas, please see [[Howto:Adding a canvas to a GUI dialog#FGPlot|Howto:Adding a canvas to a GUI dialog]].<br />
}}<br />
<br />
=== courseAndDistance() ===<br />
{{Nasal doc<br />
|syntax = courseAndDistance(to);<br />
courseAndDistance(from, to);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1668|t=Source}}<br />
|text = Returns a vector containing the course from one point to another and the distance between them in nautical miles. The course is the initial bearing (see [http://www.movable-type.co.uk/scripts/latlong.html#bearing here]), and is in the range 0–360. Both arguments can be one of:<br />
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type<br />
:* A hash with ''lat'' and ''lon'' members<br />
:* A geo.Coord object<br />
|param1 = from<br />
|param1text = Optional parameter defining the from where the function should calculate its results. If the function is given one argument ('''to'''), the aircraft's current position will be used. As well as the argument types as defined above, this argument can be two numbers separated with a comma, as if the function is taking three arguments. See example 5 below.<br />
|param2 = to<br />
|param2text = Like the first parameter, but defines the second point.<br />
|example1text = This example demonstrates the usage of the function with the <code>airport</code> ghost type.<br />
|example1 = var from = airportinfo("KSFO");<br />
var to = airportinfo("KSQL");<br />
var (course, dist) = courseAndDistance(from, to);<br />
print(course); # prints course from KSFO to KSQL<br />
print(dist); # prints distance in nm from KSFO to KSQL<br />
|example2text = This example demonstrates the usage of the function with hashes containing ''lat'' and ''lon''.<br />
|example2 = var from = {lat: 0, lon: 0};<br />
var to = {lat: 1, lon: 1};<br />
var (course, dist) = courseAndDistance(from, to);<br />
print(course);<br />
print(dist);<br />
|example3text = This example demonstrates usage of a geo.Coord object.<br />
|example3 = var from = geo.Coord.new().set_latlon(0, 0);<br />
var to = geo.Coord.new().set_latlon(1, 1);<br />
var (course, dist) = courseAndDistance(from, to);<br />
print(course);<br />
print(dist);<br />
|example4text = This example demonstrates usage of differing parameter types.<br />
|example4 = var from = airportinfo("KSFO");<br />
var to = geo.Coord.new().set_latlon(0, 0);<br />
var (course, dist) = courseAndDistance(from, to);<br />
print(course);<br />
print(dist);<br />
|example5text = The same as above, but the other way round.<br />
|example5 = var to = {lat: 1, lon: 1};<br />
var (course, dist) = courseAndDistance(0, 0, to);<br />
print(course);<br />
print(dist);<br />
|example6text = Usage of just one parameter.<br />
|example6 = var dest = airportinfo("KSQL");<br />
var (course, dist) = courseAndDistance(dest);<br />
print("Turn to heading ", math.round(course), ". You have ", sprintf("%.2f", dist), " nm to go");<br />
}}<br />
<br />
=== createWP() ===<br />
{{Nasal doc<br />
|syntax = createWP(pos, name[, flag]);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1964|t=Source}}<br />
|text = Creates a new waypoint ghost object.<br />
|param1 = pos<br />
|param1text = Dictates the position of the new waypoint. It can be one of the following:<br />
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type<br />
:* A hash with ''lat'' and ''lon'' members<br />
:* A geo.Coord object<br />
:* Two numbers separated by a comma, as if the function is taking three arguments. See example 4 below.<br />
|param2 = name<br />
|param2text = String that will become the name of the new waypoint.<br />
|param3 = flag<br />
|param3text = Optional string that will tell FlightGear what type of waypoint it is. Must be one of "sid," "star," "approach," "missed," or "pseudo."<br />
|example1text = Creates a waypoint directly in front and 1 km away and appends it to the flight plan.<br />
|example1 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);<br />
var wp = createWP(pos, "NEWWP");<br />
var fp = flightplan();<br />
fp.appendWP(wp);<br />
|example2 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);<br />
var wp = createWP({lat: pos.lat(), lon: pos.lon()}, "NEWWP");<br />
var fp = flightplan();<br />
fp.appendWP(wp);<br />
|example3 = var apt = airportinfo();<br />
var wp = createWP(apt, "NEWWP");<br />
var fp = flightplan();<br />
fp.appendWP(wp);<br />
|example4 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);<br />
var wp = createWP(pos.lat(), pos.lon(), "NEWWP");<br />
var fp = flightplan();<br />
fp.appendWP(wp);<br />
|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.<br />
|example5 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);<br />
var wp = createWP(pos, "NEWWP", "pseudo");<br />
var fp = flightplan();<br />
fp.appendWP(wp);<br />
print(fp.getPlanSize());<br />
fp.clearWPType("pseudo");<br />
print(fp.getPlanSize());<br />
}}<br />
<br />
=== createWPFrom() ===<br />
{{Nasal doc<br />
|syntax = createWPFrom(object[, flag]);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1989|t=Source}}<br />
|text = Creates a new waypoint object from another object.<br />
|param1 = object<br />
|param1text = A ghost object. Must be a ghost type that is one of "airport," "navaid," "runway," or "fix."<br />
|param2 = flag<br />
|param2text = Optional string that will tell FlightGear what type of waypoint it is. Must be one of "sid," "star," "approach," "missed," or "pseudo."<br />
|example1text = Creates a new waypoint and appends it to the flight plan.<br />
|example1 = var apt = airportinfo("KSFO");<br />
var wp = createWPFrom(apt);<br />
var fp = flightplan();<br />
fp.appendWP(wp);<br />
|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.<br />
|example2 = var apt = airportinfo("KSFO");<br />
var wp = createWPFrom(apt, "pseudo");<br />
print(wp.wp_name);<br />
var fp = flightplan();<br />
fp.appendWP(wp);<br />
print(fp.getPlanSize());<br />
fp.clearWPType("pseudo");<br />
print(fp.getPlanSize());<br />
}}<br />
<br />
=== defined() ===<br />
{{Nasal doc<br />
|syntax = defined(symbol);<br />
|source = {{fgdata file|Nasal/globals.nas|t=Source}}<br />
|text = Returns 1 (true) or 0 (false) depending on whether a variable exists.<br />
|param1 = symbol<br />
|param1text = A string that will be what the function searches for.<br />
|example1 = var number = 12;<br />
var check_exist = func {<br />
print("Variable 'number' ", defined("number") == 1 ? "exists" : "does not exist"); # 'number' does exist<br />
print("Variable 'number2' ", defined("number2") == 1 ? "exists" : "does not exist"); # 'number2' does not exist<br />
}<br />
check_exist();<br />
}}<br />
<br />
=== directory() ===<br />
{{Nasal doc<br />
|syntax = directory(path);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=572|t=Source}}<br />
|text = Returns a vector containing a list of the folders and files in a given file path or <code>'''nil'''</code> if the path doesn't exist. Hidden folders and files are not added to the vector.<br />
{{inote|The first two elements of the vector will be <code>'.'</code> and <code>'..'</code>. These are for navigating back up the file tree, but have no use in Nasal. They can be safely removed from the vector.}}<br />
|param1 = path<br />
|param1text = Absolute file path.<br />
|example1text = Gets the folders and files in [[$FG_ROOT]], and then removes the extra first two elements (see note above). <br />
|example1 = var dir = directory(getprop("/sim/fg-root")); # get directory<br />
dir = subvec(dir, 2); # strips off the first two elements<br />
debug.dump(dir); # dump the vector<br />
}}<br />
<br />
=== fgcommand() ===<br />
{{Nasal doc<br />
|syntax = fgcommand(cmd[, args]);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=456|t=Part 1}} {{!}} {{fgdata file|Nasal/globals.nas|t=Part 2}}<br />
|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.<br />
|param1 = cmd<br />
|param1text = String that is the name of the command that is to be run.<br />
|param2 = args<br />
|param2text = If the fgcommand takes arguments, they are inputted using this argument. Can either be a <code>props.Node</code> object, or a hash (see examples below).<br />
|example1 = fgcommand("null"); # does nothing<br />
|example2 = var args = props.Node.new({'script': 'print("Running fgcommand");'});<br />
if (fgcommand("nasal", args)) { # prints "Running fgcommand" and then one of these print statements<br />
print("Fgcommand succeeded");<br />
} else {<br />
print("Fgcommand encountered a problem");<br />
}<br />
|example3 = var args = { 'dialog-name': 'about' };<br />
fgcommand("dialog-show", args); # shows the 'about' dialog<br />
}}<br />
<br />
=== findAirportsByICAO() ===<br />
{{Nasal doc<br />
|syntax = findAirportsByICAO(search[, type]);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1096|t=Source}}<br />
|text = Returns a vector containing <code>airport</code> ghost objects which are (by default) airports whose ICAO code matches the search string. The results are sorted by range from closest to furthest.<br />
|param1 = search<br />
|param1text = Search string for the function. Can either be a partial or a full ICAO code.<br />
:{{icaution|The more matches there are for the given code, the longer the function will take. Passing just one character (e.g., "K"), might make FlightGear hang for a certain amount of time.}}<br />
|param2 = type<br />
|param2text = This will narrow the search to airports of a certain type. By default, only airports are searched for. May be one of "airport," "heliport," or "seaport."<br />
|example1 = var apts = findAirportsByICAO("KSF"); # finds all airports matching "KSF"<br />
foreach(var apt; apts){<br />
print(apt.name, " (", apt.id, ")"); # prints them<br />
}<br />
|example2 = var apts = findAirportsByICAO("SP0", "seaport"); # finds all seaplane bases matching "SP0"<br />
foreach(var apt; apts){<br />
print(apt.name, " (", apt.id, ")"); # prints them<br />
}<br />
|example3 = var apt = findAirportsByICAO("XBET"); # one way to check if an airport does exist"<br />
if (size(apt) == 0) {<br />
print("Airport does not exist"); # this one will be printed<br />
} else {<br />
print("Airport does exist");<br />
}<br />
}}<br />
<br />
=== findAirportsWithinRange() ===<br />
{{Nasal doc<br />
|syntax = findAirportsWithinRange([pos, ]range[, type]);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1066|t=Source}}<br />
|text = Returns a vector of <code>airport</code> ghost object which are (by default) airports that are within a given range of a given position, or the aircraft's current position. The results are sorted by range from closest to furthest.<br />
|param1 = pos<br />
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:<br />
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type<br />
:* A hash with ''lat'' and ''lon'' members<br />
:* A geo.Coord object<br />
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findAirportsWithinRange(lat, lon, range, type);</code>.<br />
|param2 = range<br />
|param2text = Mandatory number giving the range in nautical miles within which to search for airports/heliports/seaplane bases.only airports are searched for.<br />
|param3 = type<br />
|param3text = This will narrow the search to airports of a certain type. By default, only airports are searched for. May be one of "airport," "heliport," or "seaport."<br />
|example1text = Searches for airports within 10 nm of [[KSFO]].<br />
|example1 = var pos = airportinfo("KSFO");<br />
var apts = findAirportsWithinRange(pos, 10);<br />
foreach(var apt; apts){<br />
print(apt.name, " (", apt.id, ")");<br />
}<br />
|example2text = Searches for seaplane bases within 15 nm of [[KSFO]].<br />
|example2 = var pos = airportinfo("KSFO");<br />
var apts = findAirportsWithinRange(pos, 15, "seaport");<br />
foreach(var apt; apts){<br />
print(apt.name, " (", apt.id, ")");<br />
}<br />
|example3text = Searches for airports within 10 nm of your current position.<br />
|example3 = var apts = findAirportsWithinRange(10);<br />
foreach(var apt; apts){<br />
print(apt.name, " (", apt.id, ")");<br />
}<br />
}}<br />
<br />
=== findFixesByID() ===<br />
{{Nasal doc<br />
|syntax = findFixesByID([pos, ]id);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1627|t=Source}}<br />
|text = Returns a vector containing <code>fix</code> ghost objects matching a given ID, sorted by range from a certain position.<br />
{{inote|Fixes are (usually) also known as waypoints.}}<br />
|param1 = pos<br />
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:<br />
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type<br />
:* A hash with ''lat'' and ''lon'' members<br />
:* A geo.Coord object<br />
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findFixesByID(lat, lon, id);</code>.<br />
|param2 = id<br />
|param2text = Full or partial ID of the fix to search for.<br />
:{{inote|1=Inputting a partial ID does not work correctly (see [http://forum.flightgear.org/viewtopic.php?f=30&t=28129 here]). It is best to just input a full ID.}}<br />
|example1 = var fixes = findFixesByID("POGIC");<br />
foreach(var fix; fixes){<br />
print(fix.id, " - lat: ", fix.lat, " {{!}} lon: ", fix.lon); # prints information about POGIC<br />
}<br />
|example2 = var fix = findFixesByID("ZUNAP");<br />
fix = fix[0];<br />
var (course, dist) = courseAndDistance(fix);<br />
print("Turn to heading ", math.round(course), ". You have ", sprintf("%.2f", dist), " nm to go to reach ", fixes[0].id);<br />
}}<br />
<br />
=== findNavaidByFrequency() ===<br />
{{Nasal doc<br />
|syntax = findNavaidByFrequency([pos, ]freq[, type]);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1547|t=Source}}<br />
|text = Returns a <code>navaid</code> ghost object for a navaid matching a given frequency. If there is more than one navaid with that frequency, the nearest station is returned.<br />
|param1 = pos<br />
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:<br />
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type<br />
:* A hash with ''lat'' and ''lon'' members<br />
:* A geo.Coord object<br />
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidByFrequency(lat, lon, freq, type);</code>.<br />
|param2 = freq<br />
|param2text = Frequency, in megahertz, of the navaid to search for.<br />
|param3 = type<br />
|param3text = This will narrow the search to navaids of a certain type. Defaults to "all." For the full list of accepted type arguments, see {{flightgear file|src/Navaids/positioned.cxx|l=127}}.<br />
|example1 = var navaid = findNavaidByFrequency(11.17);<br />
print("ID: ", navaid.id); # prints info about the navaid<br />
print("Name: ", navaid.name);<br />
print("Latitude: ", navaid.lat);<br />
print("Longitude: ", navaid.lon);<br />
print("Elevation (AMSL): ", navaid.elevation, " m");<br />
print("Type: ", navaid.type);<br />
print("Frequency: ", sprintf("%.3f", navaid.frequency / 1000), " Mhz");<br />
print("Range: ", navaid.range_nm, " nm");<br />
if(navaid.course) print("Course: ", navaid.course);<br />
}}<br />
<br />
=== findNavaidsByFrequency() ===<br />
{{Nasal doc<br />
|syntax = findNavaidsByFrequency([pos, ]freq[, type]);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1572|t=Source}}<br />
|text = Returns a vector conatining <code>navaid</code> ghost objects for navaids that match a given frequency, sorted from nearest to furthest.<br />
|param1 = pos<br />
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:<br />
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type<br />
:* A hash with ''lat'' and ''lon'' members<br />
:* A geo.Coord object<br />
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidsByFrequency(lat, lon, freq, type);</code>.<br />
|param2 = freq<br />
|param2text = Frequency, in megahertz, of the navaid to search for.<br />
|param3 = type<br />
|param3text = This will narrow the search to navaids of a certain type. Defaults to "all." For the full list of accepted type arguments, see {{flightgear file|src/Navaids/positioned.cxx|l=127}}.<br />
|example1 = var navaids = findNavaidsByFrequency(10.955);<br />
foreach(var navaid; navaids){<br />
print("--");<br />
print("ID: ", navaid.id); # prints info about the navaid<br />
print("Name: ", navaid.name);<br />
print("Latitude: ", navaid.lat);<br />
print("Longitude: ", navaid.lon);<br />
print("Elevation (AMSL): ", navaid.elevation, " m");<br />
print("Type: ", navaid.type);<br />
print("Frequency: ", sprintf("%.3f", navaid.frequency / 1000), " Mhz");<br />
print("Range: ", navaid.range_nm, " nm");<br />
if(navaid.course) print("Course: ", navaid.course);<br />
print("--");<br />
}<br />
}}<br />
<br />
=== findNavaidsByID() ===<br />
{{Nasal doc<br />
|syntax = findNavaidsByID([pos, ]id[, type]);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1600|t=Source}}<br />
|text = Returns a vector containing <code>navaid</code> ghost objects matching a given ID, sorted by range from a certain position.<br />
|param1 = pos<br />
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:<br />
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type<br />
:* A hash with ''lat'' and ''lon'' members<br />
:* A geo.Coord object<br />
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidsByID(lat, lon, id, type);</code>.<br />
|param2 = id<br />
|param2text = Full or partial ID of the fix to search for.<br />
:{{inote|1=Inputting a partial ID does not work correctly (see [http://forum.flightgear.org/viewtopic.php?f=30&t=28129 here]). It is best to just input a full ID.}}<br />
|param3 = type<br />
|param3text = This will narrow the search to navaids of a certain type. Defaults to "all." For the full list of accepted type arguments, see {{flightgear file|src/Navaids/positioned.cxx|l=127}}.<br />
|example1 = var navaid = findNavaidsByID("MXW");<br />
navaid = navaid[0];<br />
print("ID: ", navaid.id); # prints info about 'MXW' (a VOR station)<br />
print("Name: ", navaid.name);<br />
print("Latitude: ", navaid.lat);<br />
print("Longitude: ", navaid.lon);<br />
print("Elevation (AMSL): ", navaid.elevation, " m");<br />
print("Type: ", navaid.type);<br />
print("Frequency: ", sprintf("%.3f", navaid.frequency / 1000), " Mhz");<br />
print("Range: ", navaid.range_nm, " nm");<br />
}}<br />
<br />
=== findNavaidsWithinRange() ===<br />
{{Nasal doc<br />
|syntax = findNavaidsWithinRange([pos, ]range[, type]);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1518|t=Source}}<br />
|text = Returns a vector of <code>navaid</code> ghost objects which are within a given range of a given position (by default the aircraft's current position). The results are sorted from closest to furthest.<br />
|param1 = pos<br />
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:<br />
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type<br />
:* A hash with ''lat'' and ''lon'' members<br />
:* A geo.Coord object<br />
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidsWithinRange(lat, lon, range, type);</code>.<br />
|param2 = range<br />
|param2text = Mandatory number giving the range in nautical miles within which to search for navaids. Defaults to "all." For the full list of accepted type arguments, see {{flightgear file|src/Navaids/positioned.cxx|l=127}}.<br />
|param3 = type<br />
|param3text = This will narrow the search to navaids of a certain type.<br />
|example1text = Searches for navaids within 10 nm of [[KSFO]].<br />
|example1 = var pos = airportinfo("KSFO");<br />
var navs = findNavaidsWithinRange(pos, 10);<br />
foreach(var nav; navs){<br />
print(nav.name, " (ID: ", nav.id, ")");<br />
}<br />
|example2text = Searches for navaids within 10 nm of your current position.<br />
|example2 = var navs = findNavaidsWithinRange(10);<br />
foreach(var nav; navs){<br />
print(nav.name, " (ID: ", nav.id, ")");<br />
}<br />
}}<br />
<br />
=== finddata() ===<br />
{{Nasal doc<br />
|syntax = finddata(path);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=603|t=Source}}<br />
|text = Takes a relative path and tries to return an absolute one. It works by appending the relative path to some paths and testing to see if they exist. As of FlightGear v3.7, these paths are the TerraSync directory (tested first) and [[$FG_ROOT]]. <br />
|param1 = path<br />
|param1text = A relative path as a string.<br />
|example1 = var path = finddata("Aircraft/Generic");<br />
print(path); # prints the absolute path to $FG_ROOT/Aircraft/Generic<br />
|example2 = var path = finddata("Airports");<br />
print(path); # prints the absolute path to <TerraSync dir>/Airports<br />
|example3 = var path = finddata("preferences.xml");<br />
print(path); # prints the absolute path to $FG_ROOT/preferences.xml<br />
}}<br />
<br />
=== flightplan() ===<br />
{{Nasal doc<br />
|syntax = flightplan([path]);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1738|t=Source}}<br />
|text = {{see also|Nasal Flightplan}}<br />
Returns a flight plan object, either one for the current flight plan, or one loaded from a given path.<br />
|param1 = path<br />
|param1text = Optional path to flight plan XML file.<br />
|example1text = Gets the active flight plan and gets the ID of the current waypoint. Note that this example requires a flight plan to be set in the [[Route Manager]] first.<br />
|example1 = var fp = flightplan();<br />
print(fp.getWP(fp.current).id);<br />
|example2text = Creates a new flight plan from an XML file and prints the IDs of the waypoints. Note that this example requires a flight plan to have been created and saved as <tt>''[[$FG_HOME]]/fp-demo.xml''</tt>.<br />
|example2 = var path = getprop('/sim/fg-home') ~ '/fp-demo.xml';<br />
var fp = flightplan(path);<br />
for(var i = 0; i < fp.getPlanSize(); i += 1){<br />
print(fp.getWP(i).id);<br />
}<br />
}}<br />
<br />
=== geodinfo() ===<br />
{{Nasal doc<br />
|syntax = geodinfo(lat, lon[, max_alt]);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=981|t=Source}}<br />
|text = Returns a vector containing two entries or <code>'''nil'''</code> if no information could be obtained because the terrain tile wasn't loaded. The first entry in the vector is the elevation (in meters) for the given point, and the second is a hash with information about the assigned material (as defined in <tt>''[[$FG_ROOT]]/Materials''</tt>), or <code>'''nil'''</code> if there was no material information available (for example, because there is an untextured building at that location). The structure of the hash is as follows (see also {{readme file|materials}}):<br />
* '''light_coverage:''' The coverage of a single point of light in m<sup>2</sup>.<br />
* '''bumpiness:''' Normalized bumpiness factor for the material.<br />
* '''load_resistance:''' The amount of pressure in N/m<sup>2</sup> the material can withstand without deformation.<br />
* '''solid:''' 1 (true) or false (0) depending on whether the material is solid or not.<br />
* '''names:''' Vector of scenery types (usually generated by [[TerraGear]]) that will use this material. <br />
* '''friction_factor:''' Normalized friction factor of the material.<br />
* '''rolling_friction:''' The rolling friction coefficient of the material.<br />
<br />
Note that this function is a ''very'' CPU-intensive operation, particularly in FlightGear v2.4 and earlier. It is advised to use this function as little as possible.<br />
|param1 = lat<br />
|param1text = Latitude, inputted as a number.<br />
|param2 = lon<br />
|param2text = Longitude, inputted as a number.<br />
|param3 = max_alt<br />
|param3text = The altitude, in metres, from which the function will begin searching for the height of the terrain. Defaults to 10,000 metres. If the terrain is higher than this argument specifies, <code>'''nil'''</code> will be returned.<br />
|example1text = Dumps information about ground underneath the aircraft.<br />
|example1 = var pos = geo.aircraft_position();<br />
var info = geodinfo(pos.lat(), pos.lon());<br />
debug.dump(info);<br />
|example2text = Prints whether the ground underneath the aircraft is solid or is water.<br />
|example2 = var pos = geo.aircraft_position();<br />
var info = geodinfo(pos.lat(), pos.lon());<br />
if (info != nil and info[1] != nil) {<br />
print("The ground underneath the aircraft is ", info[1].solid == 1 ? "solid." : "water.");<br />
}<br />
}}<br />
<br />
=== geodtocart() ===<br />
{{Nasal doc<br />
|syntax = geodtocart(lat, lon, alt);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=962|t=Source}}<br />
|text = Converts {{wikipedia|geodetic coordinates}} (latitude, longitude, and altitude) to {{wikipedia|ECEF|Earth-centered, Earth-fixed}} coordinates (x, y and z). A vector is returned containing x, y, and z in metres. The equatorial radius of earth used is that defined by the {{wikipedia|WGS 84}} (6,378,137 metres). All argument are mandatory.<br />
|param1 = lat<br />
|param1text = Latitude, in degrees.<br />
|param2 = lon<br />
|param2text = Longitude, in degrees.<br />
|param3 = alt<br />
|param3text = Altitude, in metres.<br />
|example1 = var (x, y, z) = geodtocart(0, 0, 0); # point is the intersection of the prime meridian and equator.<br />
print("x: ", x); # prints "x: 6378137"<br />
print("y: ", y); # prints "y: 0"<br />
print("z: ", z); # prints "y: 0"<br />
}}<br />
<br />
=== getprop() ===<br />
{{Nasal doc<br />
|syntax = getprop(arg[, arg[, ...]]);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=345|t=Source}}<br />
|text = Returns the value of a node in the [[property tree]] or <code>'''nil'''</code> if the node does not exist or the value is not a number (NaN).<br />
|param1 = arg<br />
|param1text = There needs to be at least one argument, but there is no limit to the maximum amount of arguments that can be given. The arguments will be concatenated together to form a property tree path. The arguments must be strings, but in FlightGear v3.2 onwards, there is support (added by {{flightgear commit|34ed79}}) for numeric arguments as indices. See example 2 below.<br />
|example1 = print("You have FlightGear v", getprop("/sim/version/flightgear")); # prints FlightGear version<br />
|example2text = Note that the example below will only work in FlightGear 3.2 and above.<br />
|example2 = for(var i = 0; i < 8; i += 1){<br />
print("View #", i + 1, " is named ", getprop("/sim/view", i, "name"));<br />
}<br />
|example3text = Same as above, but is supported by all version of FlightGear.<br />
|example3 = for(var i = 0; i < 8; i += 1){<br />
print("View #", i + 1, " is named ", getprop("/sim/view[" ~ i ~ "]/name"));<br />
}<br />
}}<br />
<br />
=== greatCircleMove() ===<br />
{{Nasal doc<br />
|syntax = greatCircleMove([pos, ]course, dist);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1681|t=Source}}<br />
|text = Calculates a new set of geodetic coordinates using inputs of course and distance, either from the aircraft's current position (by default) or from another set of coordinates. Returns a hash containing two members, ''lat'' and ''lon'' (latitude and longitude respectively).<br />
|param1 = pos<br />
|param1text = Optional position to calculate from. If not given, the aircraft's current position will be used. Can be one of:<br />
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost object.<br />
:* A hash with ''lat'' and ''lon'' members<br />
:* A <code>geo.Coord</code> object<br />
:* A lat/lon pair, that is, a pair of numbers (latitude followed by longitude) separated by a comma: <code>greatCircleMove(lat,lon, ...)</code>.<br />
|param2 = course<br />
|param2text = Course to new set of coordinates, in degrees (in the range 0–360).<br />
|param3 = dist<br />
|param3text = Distance in nautical miles to the new set of coordinates.<br />
|example1 = var pos = greatCircleMove(0,0, 0, 1);<br />
debug.dump(pos); # print hash with coordinates<br />
|example2 = var fix = findFixesByID("POGIC");<br />
fix = fix[0];<br />
var pos = greatCircleMove(fix, 45, 10);<br />
debug.dump(pos); # print hash with coordinates<br />
}}<br />
<br />
=== interpolate() ===<br />
{{Nasal doc<br />
|private = _interpolate()<br />
|syntax = interpolate(prop, value1, time1[, value2, time2[, ...]]);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=522|t=Part 1}} {{!}} {{fgdata file|Nasal/globals.nas|t=Part 2}}<br />
|text = Linearly interpolates a node in the property tree to a given value in a specified time. The value/time pairs will be run one after the other in the order that they are passed to the function. Note that the interpolation will continue even when the simulation is paused.<br />
|param1 = prop<br />
|param1text = String or <code>props.Node</code> object that indicates a node in the property tree to be used.<br />
|param2 = value''n''<br />
|param2text = Target value to change the property to in the set amount of time. This should be a number.<br />
|param3 = time''n''<br />
|param3text = Time in seconds, that will be taken for the interpolation.<br />
|example1text = Paste the code below into the Nasal Console and execute. Then, open the Property Browser and look for the property. Finally, run the code again, and watch the value of the property change.<br />
|example1 = setprop("/test", 0); # (re-)set property<br />
interpolate("/test",<br />
50, 5, # interpolate to 50 in 5 seconds<br />
10, 2, # interpolate to 10 in 2 seconds<br />
0, 5); # interpolate to 0 in 5 seconds<br />
|example2 = # Apply the left brake at 20% per second<br />
var prop = "controls/gear/brake-left";<br />
var dist = 1 - getprop(prop);<br />
if (dist == 1) {<br />
interpolate(prop, 1, dist / 0.2);<br />
}<br />
}}<br />
<br />
=== isa() ===<br />
{{Nasal doc<br />
|syntax = isa(object, class);<br />
|source = {{fgdata file|Nasal/globals.nas|t=Source}}<br />
|text = Checks if an object is an instance of, or inherits from, a second object (or class), returning 1 (true) if it is and 0 (false) if otherwise.<br />
|param1 = object<br />
|param1text = Object to check.<br />
|param2 = class<br />
|param2text = Class/object to check that '''object''' inherits from or is an instance of.<br />
|example1 = var coord = geo.Coord.new();<br />
if(isa(coord, geo.Coord)){<br />
print("Variable 'coord' is an instance of class 'geo.Coord'"); # this one will be printed<br />
} else {<br />
print("Variable 'coord' is not an instance of class 'geo.Coord'");<br />
}<br />
|example2 = var coord = geo.Coord.new();<br />
if(isa(coord, props.Node)){<br />
print("Variable 'coord' is an instance of class 'props.Node'");<br />
} else {<br />
print("Variable 'coord' is not an instance of class 'props.Node'"); # this one will be printed<br />
}<br />
|example3text = The example below demonstrates checking of inheritance.<br />
|example3 = var Const = {<br />
constant: 2,<br />
getConst: func {<br />
return me.constant;<br />
}<br />
};<br />
<br />
var Add = {<br />
new: func {<br />
return { parents: [Add, Const] };<br />
},<br />
<br />
addToConst: func(a){<br />
return a * me.getConst();<br />
}<br />
};<br />
<br />
var m = Add.new();<br />
print(m.addToConst(4));<br />
<br />
if(isa(m, Add)) print("Variable 'm' is an instance of class 'Add'"); # will be printed<br />
if(isa(m, Const)) print("Variable 'm' is an instance of class 'Const'"); # will also be printed<br />
}}<br />
<br />
=== logprint() ===<br />
{{Nasal doc<br />
|syntax = logprint(priority[, msg[, msg[, ...]]]);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=431|t=Source}}<br />
|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, for example, the Nasal Console, rather than {{flightgear file|src/Scripting/NasalSys.cxx}}.<br />
|param1 = priority<br />
|param1text = Number specifying the priority level of the outputted message:<br />
:{{{!}} class="wikitable"<br />
! Number !! Debug type<br />
{{!-}}<br />
{{!}} 1 {{!!}} Bulk<br />
{{!-}}<br />
{{!}} 2 {{!!}} Debug<br />
{{!-}}<br />
{{!}} 3 {{!!}} Info<br />
{{!-}}<br />
{{!}} 4 {{!!}} Warn<br />
{{!-}}<br />
{{!}} 5 {{!!}} Alert<br />
{{!}}}<br />
|param2 = msg<br />
|param2text = The message. There is no limit to the arguments you give give. They will be concatenated together before logging.<br />
|example1 = # logs the value of pi to three decimal places with log level 3<br />
logprint(3, "pi = ", sprintf("%.3f", math.pi));<br />
|example2 = logprint(5, "Alert! This is an important message!");<br />
}}<br />
<br />
=== removecommand() ===<br />
<br />
As you can guess, there's also a removecommand() function which will remove '''any''' command – even those implemented in C++! As such it can be very dangerous and remove core functionality, so use with caution.<br />
<br />
=== print() ===<br />
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.<br />
<br />
<syntaxhighlight lang="nasal"><br />
print("Just", " a ", "test");<br />
</syntaxhighlight><br />
<br />
=== setprop() ===<br />
Sets a property value for a given node path string. Returns 1 on success or 0 if the property could not be set (i.e. was read-only).<br />
<br />
<syntaxhighlight lang="nasal"><br />
setprop(<path> [, <path>, [...]], <value>);<br />
</syntaxhighlight><br />
<br />
All arguments but the last are concatenated to a path string, like getprop() above. The last value is written to the respective node. If the node isn't writable, then an error message is printed to the console.<br />
<br />
Examples:<br />
<br />
<syntaxhighlight lang="nasal"><br />
setprop("/sim/current-view/view-number", 2);<br />
setprop("/controls", "engines/engine[0]", "reverser", 1);<br />
</syntaxhighlight><br />
<br />
'''Erasing a property from the property tree''': a property that has been created, for example through <tt>setprop()</tt> has to be erased using the props namespace helper, like this:<br />
<br />
<syntaxhighlight lang="nasal"><br />
props.globals.getNode("foo/bar").remove(); # take out the complete node<br />
props.globals.getNode("foo").removeChild("bar"); # take out a certain child node<br />
</syntaxhighlight><br />
<br />
=== setlistener() ===<br />
<br />
=== settimer() ===<br />
{{Leaking Nasal Disclaimer<br />
|oldapi=settimer()<br />
|newapi=maketimer()<br />
}}<br />
Runs a function after a given simulation time (default) or real time in seconds.<br />
<br />
<syntaxhighlight lang="nasal"><br />
settimer(<function>, <time> [, <realtime=0>]);<br />
</syntaxhighlight><br />
<br />
The '''first argument''' 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. <br />
<br />
The '''second argument''' is a delay time. After this amount of time the function will be executed.<br />
For instance, if you want to print the words "My result" in five seconds, use this code:<br />
<br />
<syntaxhighlight lang="nasal"><br />
settimer ( func { print ( "My result"); }, 5);<br />
</syntaxhighlight><br />
<br />
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:<br />
<br />
<syntaxhighlight lang="nasal"><br />
myarg1="My favorite string";<br />
myarg2=432;<br />
settimer ( func { myfunction ( myarg1, myarg2); }, 25);<br />
</syntaxhighlight><br />
<br />
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.<br />
<br />
<syntaxhighlight lang="nasal"><br />
# simulation time example<br />
var copilot_annoyed = func { setprop("/sim/messages/copilot", "Stop it! Immediately!") }<br />
settimer(copilot_annoyed, 10);<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="nasal"><br />
# real time example<br />
var popdown = func ( tipArg ) { <br />
fgcommand("dialog-close", tipArg); <br />
}<br />
<br />
var selfStatusPopupTip = func (label, delay = 10, override = nil) { <br />
var tmpl = props.Node.new({<br />
name : "PopTipSelf", modal : 0, layout : "hbox",<br />
y: 140,<br />
text : { label : label, padding : 6 }<br />
});<br />
if (override != nil) tmpl.setValues(override);<br />
<br />
popdown(tipArgSelf);<br />
fgcommand("dialog-new", tmpl);<br />
fgcommand("dialog-show", tipArgSelf);<br />
<br />
currTimerSelf += 1;<br />
var thisTimerSelf = currTimerSelf;<br />
<br />
# Final argument 1 is a flag to use "real" time, not simulated time<br />
settimer(func { if(currTimerSelf == thisTimerSelf) { popdown(tipArgSelf) } }, delay, 1);<br />
}<br />
</syntaxhighlight><br />
<br />
[[Nasal scripting language#settimer loops|More information about using the settimer function to create loops.]]<br />
<br />
=== maketimer() ===<br />
{{FG ver|2.12+}}<br />
<br />
Since FlightGear v2.12, 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.<br />
<br />
<syntaxhighlight lang="nasal"><br />
var timer = maketimer(<interval>, <function>);<br />
var timer = maketimer(<interval>, <self>, <function>);<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="nasal"><br />
timer.start();<br />
timer.stop();<br />
timer.restart(<interval>);<br />
timer.singleShot [read/write]<br />
timer.isRunning [read-only]<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="nasal"><br />
# create timer with 1 second interval<br />
var timer = maketimer(1, func(){ <br />
print('timer called'); <br />
});<br />
<br />
# start the timer (with 1 second inverval)<br />
timer.start();<br />
<br />
# restart timer with 4 second interval<br />
timer.restart(4);<br />
<br />
# fire one single time in 6 seconds<br />
timer.singleShot = 1;<br />
timer.restart(6);<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="nasal"><br />
var Tooltip = {<br />
new: func(){<br />
var m = { parents: [Tooltip] };<br />
<br />
m._hideTimer = maketimer(1.0, m, Tooltip._hideTimeout);<br />
m._hideTimer.singleShot = 1;<br />
<br />
return m;<br />
},<br />
<br />
run: func(){<br />
if(!me._hideTimer.isRunning) me._hideTimer.start();<br />
},<br />
<br />
_hideTimeout: func(){<br />
print("_hideTimeout");<br />
}<br />
};<br />
<br />
var t = Tooltip.new();<br />
t.run();<br />
</syntaxhighlight><br />
<br />
=== history() (3.1+) ===<br />
<br />
Function to expose flight history as aircraft.history()<br />
<br />
<syntaxhighlight lang="nasal"><br />
var hist = aircraft.history();<br />
<br />
# get history of aircraft position/orientation collapsing<br />
# nodes with a distance smaller than the given minimum<br />
# edge legth<br />
debug.dump( hist.pathForHistory(<minimum-edge-length-meter>) );<br />
</syntaxhighlight><br />
<br />
=== systime() ===<br />
Returns epoch time (time since 1970/01/01 00:00) in seconds as a floating point number with high resolution. This is useful for benchmarking purposes.<br />
<br />
<syntaxhighlight lang="nasal"><br />
#benchmarking example:<br />
var start = systime();<br />
how_fast_am_I(123);<br />
var end = systime();<br />
print("took ", end - start, " seconds");<br />
</syntaxhighlight><br />
<br />
=== parsexml() ===<br />
<br />
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).<br />
<br />
<syntaxhighlight lang="nasal"><br />
var ret = parsexml(<path> [, <start-elem> [, <end-elem> [, <data> [, <pi> ]]]]);<br />
<br />
<start-elem> ... called for every starting tag with two arguments: the tag name, and an attribute hash<br />
<end-elem> ... called for every ending tag with one argument: the tag name<br />
<data> ... called for every piece of data with one argument: the data string<br />
<pi> ... called for every "processing information" with two args: target and data string<br />
<br />
<ret> ... the return value is nil on error, and the <path> otherwise<br />
</syntaxhighlight><br />
<br />
Example:<br />
<br />
<syntaxhighlight lang="nasal"><br />
var start = func(name, attr) {<br />
print("starting tag ", name);<br />
foreach (var a; keys(attr))<br />
print("\twith attribute ", a, "=", attr[a]);<br />
}<br />
var end = func(name) { print("ending tag ", name) }<br />
var data = func(data) { print("data=", data) }<br />
var pi = func(target, data) { print("processing instruction: target=", target, " data=", data) }<br />
parsexml("/tmp/foo.xml", start, end, data, pi);<br />
</syntaxhighlight><br />
<br />
=== resolvepath() ===<br />
<br />
SimGear features its own [[Resolving Paths|path resolving framework]] that takes a relative path and returns an absolute path, checking from base directories such as [[$FG_ROOT]], [[$FG_HOME]], [[$FG_AIRCRAFT]], and the current aircraft directory (<tt>/sim/aircraft-dir</tt>). This function in Nasal takes a path string and returns the absolute path or an empty string if the path couldn't be resolved.<br />
<br />
Example:<br />
<br />
<syntaxhighlight lang="nasal"><br />
var guess_path = func(path...) {<br />
var path_concat = string.join(path, "/");<br />
var file_path = resolvepath(path_concat);<br />
if (file_path == "") die("Path not found: "~path_concat);<br />
return file_path;<br />
}<br />
</syntaxhighlight><br />
<br />
=== HTTP module (2.99+) ===<br />
<br />
Get remote data using the HTTP.<br />
<br />
==== http.load() ====<br />
<br />
Load resource identified by its URL into memory.<br />
<br />
<syntaxhighlight lang="nasal"><br />
var request = http.load(<url>);<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="nasal"><br />
http.load("http://example.com/test.txt")<br />
.done(func(r) print("Got response: " ~ r.response));<br />
</syntaxhighlight><br />
<br />
==== http.save() ====<br />
<br />
Save resource to a local file.<br />
<br />
<syntaxhighlight lang="nasal"><br />
var request = http.save(<url>, <file_path>);<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="nasal"><br />
http.save("http://example.com/test.png", getprop('/sim/fg-home') ~ '/cache/test.png')<br />
.fail(func print("Download failed!"))<br />
.done(func(r) print("Finished request with status: " ~ r.status ~ " " ~ r.reason))<br />
.always(func print("Request complete (fail or success)"));<br />
</syntaxhighlight><br />
<br />
=== rand() ===<br />
<br />
Return a random number as generated by <tt>sg_random</tt>.<br />
<br />
=== srand() ===<br />
<br />
Seed the random number generator based upon the current time. Returns 0.<br />
<br />
=== md5() (3.1+) ===<br />
<br />
Get the md5 hash of a string.<br />
<br />
<syntaxhighlight lang="nasal"><br />
var hash = md5(<str>);<br />
</syntaxhighlight><br />
<br />
{{Appendix}}</div>Chris-barryhttps://wiki.flightgear.org/w/index.php?title=Nasal_library&diff=92155Nasal library2016-02-01T03:34:45Z<p>Chris-barry: /* subvec() */</p>
<hr />
<div>{{Nasal Navigation}}<br />
<br />
This page documents the global '''library functions''' of FlightGear's built-in scripting language, [[Nasal]]. This includes ''[[#Core library functions|core library functions]]'', which were included in Nasal before its integration into FlightGear, and ''[[#Extension functions|extension functions]]'', which have been subsequently added, and are specifically designed for FlightGear. The main relevant folders in [[Git]] are:<br />
* {{flightgear file|src/Scripting}}<br />
* {{simgear file|simgear/nasal}}<br />
<br />
{{tip|Copy & paste the examples into your [[Nasal Console]] and execute them to see what they do.|width=70%}}<br />
<br />
== Core library functions ==<br />
This is the list of the basic '''core library functions.''' Most of these functions were part of the original Nasal library (before its integration in to FlightGear), while some have been added or changed over time. See also:<br />
* http://plausible.org/nasal/lib.html ([http://web.archive.org/web/20101010094553/http://plausible.org/nasal/lib.html archive])<br />
* {{simgear file|simgear/nasal/lib.c}} ([http://sourceforge.net/p/flightgear/simgear/ci/next/log/?path=/simgear/nasal/lib.c history])<br />
<br />
=== append() ===<br />
{{Nasal doc<br />
|syntax = append(vector, element[, element[, ...]]);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=42|t=Source}}<br />
|text = This function appends, or adds, the given element(s) to the end of the vector given in the first argument. Returns the vector operated on.<br />
|param1 = vector<br />
|param1text = The vector to which the arguments will be appended.<br />
|param2 = element<br />
|param2text = An element to be added to the vector.<br />
|example1 = <br />
var vector = [1, 2, 3]; # Initialize the vector<br />
append(vector, 4); # Append the number 4 to the end of the vector<br />
debug.dump(vector); # Print the contents of the vector<br />
|example2 = <br />
var vector = [1, 2, 3]; # Initialize the vector<br />
append(vector, 4, 5, 6); # Append the numbers 4, 5, and 6 to the end of the vector<br />
debug.dump(vector); # Print the contents of the vector<br />
}}<br />
<br />
=== bind() ===<br />
{{Nasal doc<br />
|syntax = bind(function, locals[, outer_scope]);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=502|t=Source}}<br />
|text = This creates a new function object. A function in Nasal is three things: the actual code, a hash/namespace of local variables available to the function namespace, and the closure object of that namespace. These correspond to the three arguments respectively.<br />
|param1 = function<br />
|param1text = Function to evaluate.<br />
|param2 = locals<br />
|param2text = Hash containing values that will become the namespace (first closure) for the function.<br />
|param3 = outer_scope<br />
|param3text = Optional function which is bound to the next closure. This can be bound to yet another, making a linked list.<br />
|example1 = # This is a namespace/hash with a single member, named "key," which is initialized to 12 <br />
var Namespace = {<br />
key: 12<br />
};<br />
<br />
# This is different namespace/hash containing a function<br />
# dividing a variable "key" (which is unavailable/nil in this namespace) by 2<br />
var AnotherNamespace = {<br />
ret: func {<br />
key /= 2;<br />
}<br />
};<br />
<br />
# To see that key is not available, try to call AnotherNamespace.ret() first<br />
call(AnotherNamespace.ret, [], nil, nil, var errors = []);<br />
if(size(errors)){<br />
print("Key could not be divided/resolved!");<br />
debug.printerror(errors);<br />
}<br />
<br />
# Associate the AnotherNamespace.ret() function with the first namespace<br />
# so that "key" is now available<br />
var function = bind(AnotherNamespace.ret, Namespace);<br />
<br />
# Invoke the new function<br />
function();<br />
<br />
# Print out the value of Namespace.key<br />
# It was changed to 12 from 6 by AnotherNamespace.ret()<br />
print(Namespace.key);<br />
}}<br />
<br />
=== call() ===<br />
{{Nasal doc<br />
|syntax = call(func[, args[, me[, locals[, error]]]);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=247|t=Source}}<br />
|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. <br />
|param1 = func<br />
|param1text = Function to execute.<br />
|param2 = args<br />
|param2text = Vector containing arguments to give to the called function.<br />
|param3 = me<br />
|param3text = <code>'''me'''</code> reference for the function call (i.e., for method calls). If given, this will override any <code>'''me'''</code> value existing in the namespace (locals argument).<br />
|param4 = locals<br />
|param4text = A hash with key/value pairs that will be available to the called function, typically used as the namespace for the function to be called.<br />
|param5 = error<br />
|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}}.<br />
|example1 =<br />
# prints "Called from call()"<br />
call(func {<br />
print("Called from call()");<br />
});<br />
|example2 =<br />
# prints "a = 1 : b = 2<br />
call(func(a, b){<br />
print("a = ", a, " : b = ", b);<br />
},<br />
[1, 2]<br />
);<br />
|example3 =<br />
var Hash = {<br />
new: func {<br />
var m = { parents: [Hash] };<br />
<br />
m.el1 = "string1";<br />
m.el2 = "string2";<br />
<br />
return m;<br />
}<br />
};<br />
<br />
# prints "me.el1 = string1", then "me.el2 = string2" on the next line<br />
call(func(a, b){ <br />
print("me.el", a, " = ", me["el" ~ a]); <br />
print("me.el", b, " = ", me["el" ~ b]);<br />
},<br />
[1, 2],<br />
Hash.new()<br />
);<br />
|example4 =<br />
# prints the value of math.pi<br />
call(func {<br />
print(pi);<br />
}, nil, nil, <br />
math<br />
);<br />
|example5 =<br />
call(func {<br />
print(math.ip); # math.ip doesn't exist<br />
}, nil, nil, nil,<br />
var errs = []<br />
);<br />
debug.printerror(errs); # The error is caught and printed using debug.printerror()<br />
}}<br />
<br />
=== caller() ===<br />
{{Nasal doc<br />
|syntax = caller([level]);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=404|t=Source}}<br />
|text = Returns a vector containing a record from the current call stack. The level numbering starts from the currently executing function (level 0). Level 1 (the default) is the caller of the current function, and so on. The result is a four-element vector containing a hash of local variables, the function object, the source, and the line number. <br />
|param1 = level<br />
|param1text = Optional integer specifying the stack level to return a result from. Defaults to 1 (the caller of the currently executing function.<br />
|example1 =<br />
var myFunction = func(a, b){<br />
debug.dump(caller(0)[0]); # prints a hash of local variables, including arguments a and b<br />
return 2 * 2;<br />
};<br />
<br />
print("2 x 2 = ", myFunction(2, 2));<br />
|example2 =<br />
var get_arg_value = func(){<br />
print("Argument to myFunc = ", caller(1)[0]['a']); # print the value of myFunc's single argument, using caller()<br />
};<br />
<br />
var myFunc = func(a){<br />
get_arg_value();<br />
};<br />
<br />
myFunc(3);<br />
|example3text = This is a real example taken from {{fgdata file|Nasal/canvas/MapStructure.nas}}. Function <code>r()</code> (above the TODOs) returns a hash with the key/value pairs as per its arguments. For example, something like this is returned: <code>{ name: "<name>", vis: 1, zindex: nil }</code>.<br />
|example3 =<br />
var MapStructure_selfTest = func() {<br />
var temp = {};<br />
temp.dlg = canvas.Window.new([600,400],"dialog");<br />
temp.canvas = temp.dlg.createCanvas().setColorBackground(1,1,1,0.5);<br />
temp.root = temp.canvas.createGroup();<br />
var TestMap = temp.root.createChild("map");<br />
TestMap.setController("Aircraft position");<br />
TestMap.setRange(25); # TODO: implement zooming/panning via mouse/wheel here, for lack of buttons :-/<br />
TestMap.setTranslation(<br />
temp.canvas.get("view[0]")/2,<br />
temp.canvas.get("view[1]")/2<br />
);<br />
var r = func(name,vis=1,zindex=nil) return caller(0)[0];<br />
# TODO: we'll need some z-indexing here, right now it's just random<br />
# TODO: use foreach/keys to show all layers in this case by traversing SymbolLayer.registry direclty ?<br />
# maybe encode implicit z-indexing for each lcontroller ctor call ? - i.e. preferred above/below order ?<br />
foreach(var type; [r('TFC',0),r('APT'),r('DME'),r('VOR'),r('NDB'),r('FIX',0),r('RTE'),r('WPT'),r('FLT'),r('WXR'),r('APS'), ] ) <br />
TestMap.addLayer(factory: canvas.SymbolLayer, type_arg: type.name,<br />
visible: type.vis, priority: type.zindex,<br />
);<br />
}; # MapStructure_selfTest<br />
}}<br />
<br />
=== chr() ===<br />
{{Nasal doc<br />
|syntax = chr(code);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=175|t=Source}}<br />
|text = Returns a character as per the single argument. Extended ASCII is supported (see http://www.asciitable.com/ for a list of supported characters), although this may vary between different systems. For a list of the most commonly used characters, see the {{wikipedia|ASCII#ASCII printable code chart|ASCII printable code chart}} ('''Dec''' column). The following table lists supported control characters, along with their equivalent control characters in Nasal strings. {{Note|In Nasal, only strings enclosed with double-quotes (<code>"string"</code>) supports control chracters. Strings in single quotes (<code>'string'</code>) do not.}}<br />
{{{!}} class="wikitable"<br />
! Code !! Name !! Equivalent to<br />
{{!-}}<br />
{{!}} 10 {{!!}} {{Wikipedia|Newline}} {{!!}} <code>\n</code><br />
{{!-}}<br />
{{!}} 9 {{!!}} {{Wikipedia|Tab key#Tab characters|Horizontal tab}} {{!!}} <code>\t</code><br />
{{!-}}<br />
{{!}} 13 {{!!}} {{Wikipedia|Carriage return}} {{!!}} <code>\r</code><br />
{{!}}}<br />
|param1 = code<br />
|param1text = Integer character code for the desired glyph.<br />
|example1 = print("Code 65 = ", chr(65)); # prints "Code 65 = A"<br />
|example2text = This example displays all of the characters in a list, in the format <code>Code '''n''' = >'''char'''<</code>, '''n''' being the index, and '''char''' being the character.<br />
|example2 =<br />
for(var i = 0; i <= 255; i += 1){<br />
print("Code ", i, " = >", chr(i), "<");<br />
}<br />
}}<br />
<br />
=== closure() ===<br />
{{Nasal doc<br />
|syntax = closure(func[, level]);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=421|t=Source}}<br />
|text = Returns the hash table containing the lexical namespace of the given function. The level numbering start with level 0 being the namespace of '''func'''. <br />
|param1 = func<br />
|param1text = Function to evaluate.<br />
|param2 = level<br />
|param2text = Optional integer specifying the scope level. Defaults to 0 (the namespace of '''func''').<br />
|example1 =<br />
var get_math_e = func {<br />
return e; # return the value of math.e<br />
}<br />
<br />
var myFunction = bind(get_math_e, math); # bind get_math_e to the math namespace, so that math.e is immediately available to get_math_e<br />
debug.dump(closure(myFunction)); # print the namespace of get_math_e<br />
<br />
print(myFunction());<br />
}}<br />
<br />
=== cmp() ===<br />
{{Nasal doc<br />
|syntax = cmp(a, b);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=112|t=Source}}<br />
|text = Compares two strings, returning -1 if '''a''' is less than '''b''', 0 if they are identical and 1 if '''a''' is greater than '''b'''. <br />
|param1 = a<br />
|param1text = First string argument for comparison.<br />
|param2 = b<br />
|param2text = Second string argument for comparison.<br />
|example1 = print(cmp("1", "two")); # prints -1<br />
|example2 = print(cmp("string", "string")); # prints 0<br />
|example3 = print(cmp("one", "2")); # prints 1<br />
|example4 = print(cmp("string1", "string2")); # prints -1<br />
}}<br />
<br />
=== compile() ===<br />
{{Nasal doc<br />
|syntax = compile(code[, filename]);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=220|t=Source}}<br />
|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'''.<br />
|param1 = code<br />
|param1text = String containing Nasal code to be compiled.<br />
|param2 = filename<br />
|param2text = Optional string used for error messages/logging. Defaults to <code><compile></code><br />
|example1 = <br />
var myCode = 'print("hello");';<br />
var helloFunc = compile(myCode, "myCode");<br />
helloFunc();<br />
|example2text = <code>compile</code> is very convenient to support Nasal loaded from other files. For instance, [[PropertyList XML files]] (such as GUI dialogs) may contain embedded Nasal sections that need to be parsed, processed and compiled. For an example of how to do this, save the below XML code as <tt>''[[$FG_ROOT]]/gui/dialogs/test.xml''</tt>.<br />
<syntaxhighlight land="xml"><br />
<?xml version="1.0"?><br />
<br />
<PropertyList><br />
<br />
<nasal><![CDATA[<br />
print("You have FlightGear v", getprop("/sim/version/flightgear"));<br />
]]></nasal><br />
<br />
</PropertyList><br />
</syntaxhighlight><br />
Now, start FlightGear and execute this code in the [[Nasal Console]].<br />
|example2 =<br />
# Build the path<br />
var FGRoot = getprop("/sim/fg-root");<br />
var filename = "/gui/dialogs/test.xml";<br />
var path = FGRoot ~ filename;<br />
<br />
var blob = io.read_properties(path);<br />
var script = blob.getValues().nasal; # Get the nasal string<br />
<br />
# Compile the script. We're passing the filename here for better runtime diagnostics <br />
var code = call(func {<br />
compile(script, filename);<br />
}, nil, nil, var compilation_errors = []);<br />
<br />
if(size(compilation_errors)){<br />
die("Error compiling code in: " ~ filename);<br />
}<br />
<br />
# Invoke the compiled script, equivalent to code(); <br />
# We're using call() here to detect errors:<br />
call(code, [], nil, nil, var runtime_errors = []);<br />
<br />
if(size(runtime_errors)){<br />
die("Error calling code compiled loaded from: " ~ filename);<br />
}<br />
}}<br />
<br />
=== contains() ===<br />
{{Nasal doc<br />
|syntax = contains(hash, key);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=184|t=Source}}<br />
|text = Returns 1 (True) if the hash contains the specified key, or 0 (False) if not.<br />
|param1 = hash<br />
|param1text = The hash to search in.<br />
|param2 = key<br />
|param2text = The scalar to be searched for, contained as a key in the hash.<br />
|example1 =<br />
# Initialize a hash<br />
var hash = {<br />
element: "value"<br />
};<br />
print(contains(hash, "element") ? "Yes" : "No"); # This will print "Yes"<br />
|example2 =<br />
# Initialize a hash<br />
var hash = {<br />
element: "value"<br />
};<br />
print(contains(hash, "element2") ? "Yes" : "No"); # This will print "No"<br />
}}<br />
<br />
=== delete() ===<br />
{{Nasal doc<br />
|syntax = delete(hash, key);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=83|t=Source}}<br />
|text = Deletes the key from the hash if it exists. Operationally, this is identical to setting the hash value specified by the key to <code>'''nil'''</code>, but this variant potentially frees storage by deleting the reference to the key and by shrinking the hash. Returns the hash that has been operated on.<br />
|param1 = hash<br />
|param1text = The hash from which to delete the key.<br />
|param2 = key<br />
|param2text = The scalar to be deleted, contained as a key in the hash.<br />
|example1 =<br />
# Initialize the hash<br />
var hash = {<br />
element1: "value1",<br />
element2: "value2"<br />
};<br />
delete(hash, "element1"); # Delete element1<br />
debug.dump(hash); # prints the hash, which is now minus element1<br />
}}<br />
<br />
=== die() ===<br />
{{Nasal doc<br />
|syntax = die(error);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=288|t=Source}}<br />
|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}}.<br />
|param1 = error<br />
|param1text = String describing the error.<br />
:{{inote|This parameter is technically optional, but it is highly recommended to use it.}}<br />
|example1 = <br />
print("Will print");<br />
die("Don't go any further!"); <br />
print("Won't print"); # Will not be printed because die() stops the process<br />
}}<br />
<br />
=== find() ===<br />
{{Nasal doc<br />
|syntax = find(needle, haystack);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=450|t=Source}}<br />
|text = Finds and returns the index of the first occurrence of the string '''needle''' in the string '''haystack''', or -1 if no such occurrence was found.<br />
|param1 = needle<br />
|param1text = String to search for.<br />
|param2 = haystack<br />
|param2text = String to search in.<br />
|example1 = print(find("c", "abcdef")); # prints 2<br />
|example2 = print(find("x", "abcdef")); # prints -1<br />
|example3 = print(find("cd", "abcdef")); # prints 2<br />
}}<br />
<br />
=== ghosttype() ===<br />
{{Nasal doc<br />
|syntax = ghosttype(ghost);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=207|t=Source}}<br />
|text = Returns a string containing either a descriptive name of a ghost (a raw C/C++ object), or a unique id (the pointer to the C/C++ <code>naGhostType</code> instance) if no name has been set. Ghost is an acronym that stands for '''G'''arbage-collected '''H'''andle to '''O'''ut'''S'''ide '''T'''hingy.<br />
|param1 = ghost<br />
|param1text = Ghost to return a description for.<br />
|example1 = print(ghosttype(airportinfo())); # prints "airport"<br />
}}<br />
<br />
=== id() ===<br />
{{Nasal doc<br />
|syntax = id(object);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=570|t=Source}}<br />
|text = Returns a string containing information on the type and ID of the object provided in the single argument. The information is returned in the form of <code>'''<type>''':'''<id>'''</code>, where '''<type>''' is the type of object, and '''<id>''' is the ID.<br />
|param1 = object<br />
|param1text = Can be either of a string, a vector, a hash, a code, a function, or a ghost.<br />
|example1 = print(id("A")); # prints "str:000000001624A590"<br />
}}<br />
<br />
=== int() ===<br />
{{Nasal doc<br />
|syntax = int(number);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=90|t=Source}}<br />
|text = Returns the integer part of the numeric value of the single argument, or <code>'''nil'''</code> if none exists.<br />
|param1 = number<br />
|param1text = Number or string with just a number in it to return an integer from.<br />
|example1 = print(int(23)); # prints "23"<br />
|example2 = print(int(23.123)); # prints "23"<br />
|example3 = debug.dump(int("string")); # prints "nil"<br />
}}<br />
<br />
=== keys() ===<br />
{{Nasal doc<br />
|syntax = keys(hash);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=33|t=Source}}<br />
|text = Returns a vector containing the list of keys found in the single hash argument. <br />
|param1 = hash<br />
|param1text = The hash to return the keys from.<br />
|example1 = <br />
# Initialize a hash<br />
var hash = {<br />
element1: "value",<br />
element2: "value"<br />
};<br />
debug.dump(keys(hash)); # print the vector<br />
}}<br />
<br />
=== left() ===<br />
{{Nasal doc<br />
|syntax = left(string, length);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=149|t=Source}}<br />
|version = 2.12<br />
|text = Returns a substring of '''string''', starting from the left.<br />
|param1 = string<br />
|param1text = String to return part of.<br />
|param2 = length<br />
|param2text = Integer specifying the length of the substring to return.<br />
|example1 = print(left("string", 2)); # prints "st"<br />
}}<br />
<br />
=== num() ===<br />
{{Nasal doc<br />
|syntax = num(number);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=102|t=Source}}<br />
|text = Returns the numerical value of the single string argument, or <code>'''nil'''</code> if none exists. <br />
|param1 = number<br />
|param1text = String with just a number in it to return a number from.<br />
|example1 = print(num("23")); # prints "23"<br />
|example2 = print(num("23.123")); # prints "23.123"<br />
|example3 = debug.dump(num("string")); # prints "nil"<br />
}}<br />
<br />
=== pop() ===<br />
{{Nasal doc<br />
|syntax = pop(vector);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=50|t=Source}}<br />
|text = Removes and returns the last element of the single vector argument, or <code>'''nil'''</code> if the vector is empty. <br />
|param1 = vector<br />
|param1text = Vector to remove an element from.<br />
|example1 = <br />
var vector = [1, 2, 3];<br />
pop(vector);<br />
debug.dump(vector); # prints "[1, 2]"<br />
|example2 = <br />
var vector = [1, 2, 3];<br />
debug.dump(pop(vector)); # prints "3"<br />
|example3 = <br />
var vector = [];<br />
debug.dump(pop(vector)); # prints "nil"<br />
}}<br />
<br />
=== right() ===<br />
{{Nasal doc<br />
|syntax = right(string, length);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=161|t=Source}}<br />
|version = 2.12<br />
|text = Returns a substring of '''string''', starting from the right.<br />
|param1 = string<br />
|param1text = String to return part of.<br />
|param2 = length<br />
|param2text = Integer specifying the length of the substring to return.<br />
|example1 = print(right("string", 2)); # prints "ng"<br />
}}<br />
<br />
=== setsize() ===<br />
{{Nasal doc<br />
|syntax = setsize(vector, size);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=56|t=Source}}<br />
|text = Sets the size of a vector. The first argument specifies a vector, the second a number representing the desired size of that vector. If the vector is currently larger than the specified size, it is truncated. If it is smaller, it is padded with <code>'''nil'''</code> entries. Returns the vector operated upon. <br />
|param1 = vector<br />
|param1text = The vector to be operated on.<br />
|param2 = size<br />
|param2text = The desired size of the vector in number of entries.<br />
|example1 = <br />
var vector = [1, 2, 3]; # Initialize a vector<br />
setsize(vector, 4);<br />
debug.dump(vector); # print the vector<br />
|example2 = <br />
var vector = [1, 2, 3]; # Initialize a vector<br />
setsize(vector, 2);<br />
debug.dump(vector); # print the vector<br />
}}<br />
<br />
=== size() ===<br />
{{Nasal doc<br />
|syntax = size(object);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=23|t=Source}}<br />
|text = Returns the size of the single argument. For strings, this is the length in bytes. For vectors, this is the number of elements. For hashes, it is the number of key/value pairs. If the argument is <code>'''nil'''</code> or a number, this error will be thrown: <code>object has no size()</code>.<br />
|param1 = object<br />
|param1text = Object to find the size of. Must be a string, a vector or a hash.<br />
|example1 = <br />
var string = "string";<br />
print(size(string)); # prints "6"<br />
|example2 =<br />
var vector = [1, 2, 3];<br />
print(size(vector)); # prints "3"<br />
|example3 =<br />
var hash = {<br />
element1: "value1",<br />
element2: "value2",<br />
element3: "value3"<br />
};<br />
print(size(hash)); # prints "3"<br />
}}<br />
<br />
=== sort() ===<br />
{{Nasal doc<br />
|syntax = sort(vector, function);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=542|t=Source}}<br />
|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.<br />
|param1 = vector<br />
|param1text = Input vector to sort.<br />
|param2 = function<br />
|param2text = Function according to which the elements will be sorted by. It should take two arguments and should return one of 1, 0, or -1.<br />
{{{!}} class="wikitable"<br />
! Return value !! Meaning<br />
{{!-}}<br />
{{!}} less than 0 {{!!}} first argument should go before second argument<br />
{{!-}}<br />
{{!}} 0 {{!!}} first argument equals second argument<br />
{{!-}}<br />
{{!}} greater than 0 {{!!}} first argument should go after second argument<br />
{{!}}}<br />
<br />
|example1text = This example sorts elements from smallest to greatest.<br />
|example1 = <br />
var sort_rules = func(a, b){<br />
if(a < b){<br />
return -1; # A should before b in the returned vector<br />
}elsif(a == b){<br />
return 0; # A is equivalent to b <br />
}else{<br />
return 1; # A should after b in the returned vector<br />
}<br />
}<br />
debug.dump(sort([3, 2, 5, 6, 4, 1], sort_rules)); # prints "[1, 2, 3, 4, 5, 6]"<br />
|example1text = This example sorts elements from greatest to smallest.<br />
|example2 = <br />
# Outputs the elements in reverse order (greatest to smallest)<br />
var sort_rules = func(a, b){<br />
if(a < b){<br />
return 1; # -1 in the above example<br />
}elsif(a == b){<br />
return 0;<br />
}else{<br />
return -1; # 1 in the above example<br />
}<br />
}<br />
debug.dump(sort([3, 2, 5, 6, 4, 1], sort_rules)); # prints "[6, 5, 4, 3, 2, 1]"<br />
}}<br />
<br />
=== split() ===<br />
{{Nasal doc<br />
|syntax = split(delimiter, string);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=460|t=Source}}<br />
|text = Splits the input string into a vector of substrings bounded by occurrences of the delimiter substring.<br />
|param1 = delimiter<br />
|param1text = String that will split the substrings in the returned vector.<br />
|param2 = string<br />
|param2text = String to split up.<br />
|example1 = debug.dump(split("cd", "abcdef")); # prints "['ab', 'ef']"<br />
|example2 = debug.dump(split(".", "3.2.0")); # prints "[3, 2, 0]"<br />
|example3 = debug.dump(split("/", "path/to/file")); # prints "['path', 'to', 'file']"<br />
}}<br />
<br />
=== sprintf() ===<br />
{{Nasal doc<br />
|syntax = sprintf(format[, arg[, arg, [...]]]);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=355|t=Source}}<br />
|text = Creates and returns a string formatted using ANSI C {{Func link|vsnprintf()|ext=http://en.cppreference.com/w/c/io/vfprintf}} <ref><br />
{{Cite web<br />
|url = http://sourceforge.net/p/flightgear/simgear/ci/next/tree/simgear/nasal/lib.c#l308<br />
|title = fgdata/simgear/simgear/nasal/lib.c, line 308<br />
|accessdate = October 2015<br />
}}<br />
</ref>. Below is a table of supported format specifiers.<br />
{{{!}} class="wikitable" width="75%"<br />
{{!}}+ %[flags][width][.precision]specifier<br />
! colspan="2" {{!}} Flags<br />
{{!-}}<br />
! Flag !! Output<br />
{{!-}}<br />
{{!}} <code>+</code> {{!!}} Forces to precede the result with a plus or minus sign ('''+''' or '''-''') even for positive numbers. By default, only negative numbers are preceded with a '''-''' sign.<br />
{{!-}}<br />
{{!}} ''space'' {{!!}} Prefixes non-signed numbers with a space.<br />
{{!-}}<br />
{{!}} <code>-</code> {{!!}} Left-align the output of this placeholder (the default is to right-align the output) when the width option is specified.<br />
{{!-}}<br />
{{!}} <code>0</code> {{!!}} Use 0 instead of spaces to pad a field when the width option is specified.<br />
{{!-}}<br />
{{!}} <code>#</code> {{!!}} Used with <code>o</code>, <code>x</code> or <code>X</code> specifiers the value is preceded with <tt>0</tt>, <tt>0x</tt> or <tt>0X</tt> respectively for values different than zero. Used with <code>e</code>, <code>E</code> and <code>f</code>, it forces the written output to contain a decimal point even if no digits would follow. By default, if no digits follow, no decimal point is written. Used with <code>g</code> or <code>G</code> the result is the same as with <code>e</code> or <code>E</code> but trailing zeros are not removed.<br />
{{!-}}<br />
! colspan="2" {{!}} Width<br />
{{!-}}<br />
{{!}} colspan="2" {{!}} Integer specifying the minimum number of characters to be returned.<br />
{{!-}}<br />
! colspan="2" {{!}} Precision<br />
{{!-}}<br />
{{!}} colspan="2" {{!}} Integer preceded by a dot specifying the number of decimal places to be written.<br />
{{!-}}<br />
! colspan="2" {{!}} Specifiers<br />
{{!-}}<br />
! Specifier !! Output<br />
{{!-}}<br />
{{!}} <code>d</code>, <code>i</code> {{!!}} Signed decimal number.<br />
{{!-}}<br />
{{!}} <code>%</code> {{!!}} Percent (%) character.<br />
{{!-}}<br />
{{!}} <code>c</code> {{!!}} A single character assigned to a character code, the code given in an integer argument. See http://www.asciitable.com/ for a list of supported characters and their codes.<br />
{{!-}}<br />
{{!}} <code>o</code> {{!!}} Unsigned integer as an octal number.<br />
{{!-}}<br />
{{!}} <code>u</code> {{!!}} Unsigned decimal integer.<br />
{{!-}}<br />
{{!}} <code>x</code>, <code>X</code> {{!!}} Unsigned integer as a hexadecimal number. If <code>x</code> is used, any letters in the number are lowercase, while <code>X</code> gives uppercase.<br />
{{!-}}<br />
{{!}} <code>e</code>, <code>E</code> {{!!}} Double value in scientific notation (i.e., ''[-]ddd.ddd'''e'''[+/-]ddd''), with an exponent being denoted by <tt>e</tt> or <tt>E</tt> depending on whether an upper or lowercase is used respectively.<br />
{{!-}}<br />
{{!}} <code>f</code> {{!!}} Floating-point number, in fixed decimal notation, by default with 6 decimal places.<br />
{{!-}}<br />
{{!}} <code>F</code> {{!!}} Appears to be available<ref><br />
{{Cite web<br />
|url = http://sourceforge.net/p/flightgear/simgear/ci/next/tree/simgear/nasal/lib.c#l389<br />
|title = fgdata/simgear/simgear/nasal/lib.c, line 389<br />
|accessdate = October 2015<br />
}}<br />
</ref>, but doesn't work.<br />
{{!-}}<br />
{{!}} <code>g</code>, <code>G</code> {{!!}} Double in either normal or exponential notation, whichever is more appropriate for its magnitude. <code>g</code> uses lower-case letters, <code>G</code> uses upper-case letters. This type differs slightly from fixed-point notation in that insignificant zeroes to the right of the decimal point are not included. Also, the decimal point is not included on whole numbers.<br />
{{!}}}<br />
<br />
|param1 = format<br />
|param1text = String specifying the format. Can be used with or without a format specifiers. See below for examples.<br />
|param2 = arg<br />
|param2text = Argument specifying a value to replace a format placeholder (such as <code>%d</code>) in the format string. Not required if there are no format specifiers.<br />
<br />
|example1 = print(sprintf("%i", 54)); # prints "54"<br />
|example2 = print(sprintf("Pi = %+.10f", math.pi)); # prints "Pi = +3.1415926536"<br />
|example3 = <br />
print(sprintf("%6d", 23)); # prints " 23"<br />
print(sprintf("%06d", 23)); # prints "000023"<br />
|example4 =<br />
var FGVer = getprop("/sim/version/flightgear");<br />
print(sprintf("You have FlightGear v%s", FGVer)); # prints "You have FlightGear v<your version>"<br />
|example5 = <br />
print(sprintf("Hexadecimal 100000 = %X", 100000)); # prints "Hexadecimal 100000 = 186A0"<br />
print(sprintf("Hexadecimal 100000 = %x", 100000)); # prints "Hexadecimal 100000 = 186a0"<br />
|example6 = print(sprintf("Code 65 is %c", 65)); # prints "Code 65 is A"<br />
|example7 = <br />
print(sprintf("%e", 54)); # prints "5.400000e+001"<br />
print(sprintf("%E", 54)); # prints "5.400000E+001"<br />
|example8 = print(sprintf("%o", 54)); # prints "66"<br />
|example9 = print(sprintf("50%% of 100 is %i", 100 / 2)); # prints "50% of 100 is 50"<br />
}}<br />
<br />
=== streq() ===<br />
{{Nasal doc<br />
|syntax = streq(a, b);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=107|t=Source}}<br />
|text = Tests the string values of the two arguments for equality. This function is needed because the <code>'''=='''</code> operator (see [[Nasal_Operators#Equality|Nasal Operators]]) tests for numeric equality first. If either or both the arguments are not strings, 0 (False) will be returned. Returns either 0 (False) or 1 (True). {{Note|This function is rarely required in typical code.}}<br />
|param1 = a<br />
|param1text = First argument for testing equality.<br />
|param2 = b<br />
|param2text = Second argument for testing equality.<br />
|example1 = print(streq("0", "0")); # prints "1" (True)<br />
|example2 = <br />
print(0 == 0.0); # prints "1" (True)<br />
print(streq("0", "0.0")); # prints "0" (False)<br />
}}<br />
<br />
=== substr() ===<br />
{{Nasal doc<br />
|syntax = substr(string, start [, length]);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=129|t=Source}}<br />
|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).<br />
|param1 = string<br />
|param1text = String to return a substring from.<br />
|param2 = start<br />
|param2text = Integer specifying the start of a substring.<br />
|param3 = length<br />
|param3text = Optional argument specifying the length of the substring. Defaults to the end of the string.<br />
|example1 = print(substr("abcde", 1, 3)); # prints "bcd"<br />
|example2 = print(substr("abcde", 1)); # prints "bcde"<br />
|example3 = print(substr("abcde", 2, 1)); # prints "c"<br />
}}<br />
<br />
=== subvec() ===<br />
{{Nasal doc<br />
|syntax = subvec(vector, start[, length]);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=63|t=Source}}<br />
|text = Returns a sub-range of a vector. The first argument specifies a vector, the second a starting index, and the optional third argument indicates a length (the default is to the end of the vector). <br />
|param1 = vector<br />
|param1text = The vector to take the sub-vector from.<br />
|param2 = start<br />
|param2text = The starting point of the sub-vector within the given vector.<br />
|param3 = length<br />
|param3text = Optional argument specifying the length of the sub-vector, from the starting point.<br />
'''Notes:'''<br />
<ol><br />
<li><br />
Omitting the ''vector'' and ''start'' arguments is not an error (possibly it should be) but the return value is ''nil''.<br />
</li><br />
<li><br />
A negative ''start'' argument ''is'' an error. This seems wrong. Perhaps the language designer could comment.<br />
</li><br />
<li><br />
A value of ''start'' greater than ''size(vect)'' causes an error. A value equal to ''size(vector)'' returns an empty vector.<br />
</li><br />
<li><br />
If the value of ''length'' is greater than ''size(vector) - start'' then it is ignored. That is, all elements from ''start'' to the end of ''vector'' are returned. If ''length'' is zero then an empty vector is returned. A negative value of ''length'' causes an error.<br />
</ol><br />
<br />
|example1 = <br />
var vector = [1, 2, 3];<br />
debug.dump(subvec(vector, 0)); # prints "[1, 2, 3]"<br />
|example2 = <br />
var vector = [1, 2, 3];<br />
debug.dump(subvec(vector, 1)); # prints "[2, 3]"<br />
|example3 = <br />
var vector = [1, 2, 3];<br />
debug.dump(subvec(vector, 1, 1)); # prints "[2]"<br />
}}<br />
<br />
=== typeof() ===<br />
{{Nasal doc<br />
|syntax = typeof(object);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=193|t=Source}}<br />
|text = Returns a string indicating the whether the object is <code>'''nil'''</code>, a scalar (number or string), a vector, a hash, a function, or a ghost.<br />
|param1 = object<br />
|param1text = Object to return the type of.<br />
|example1 = <br />
var object = nil;<br />
print(typeof(object)); # prints "nil"<br />
|example2 = <br />
var object = "Hello world!";<br />
print(typeof(object)); # prints "scalar"<br />
|example3 = <br />
var object = math.pi;<br />
print(typeof(object)); # prints "scalar"<br />
|example4 = <br />
var object = [1, 2, 3];<br />
print(typeof(object)); # prints "vector"<br />
|example5 = <br />
var object = {};<br />
print(typeof(object)); # prints "hash"<br />
|example6 = <br />
var object = func {};<br />
print(typeof(object)); # prints "func"<br />
|example7 =<br />
var object = airportinfo();<br />
print(typeof(object)); # prints "ghost"<br />
}}<br />
<br />
== Extension functions ==<br />
The '''extension functions''' are global functions that have been added to Nasal since its integration into FlightGear. Unlike the core library functions, they are generally specifically designed to interact directly with FlightGear. Extension functions come from three source files:<br />
* {{flightgear file|src/Scripting/NasalPositioned.cxx}}<br />
* {{flightgear file|src/Scripting/NasalSys.cxx}}<br />
* {{fgdata file|Nasal/globals.nas}}<br />
<br />
=== abort() ===<br />
{{Nasal doc<br />
|syntax = abort();<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=565|t=Source}}<br />
|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).<br />
|example1text = This example will immediately stop FlightGear with an error, such as "FlightGear has stopped working."<br />
|example1 = abort();<br />
|example2text = For exiting FlightGear in a better way, please use the following code:<br />
|example2 = fgcommand("exit");<br />
}}<br />
<br />
=== abs() ===<br />
{{Nasal doc<br />
|syntax = abs(number);<br />
|source = {{fgdata file|Nasal/globals.nas|t=Source}}<br />
|text = This simple function returns the {{wikipedia|absolute value|noicon=1}} of the provided number.<br />
|param1 = number<br />
|param1text = This argument is required and should be a number.<br />
|example1 = print(abs(1)); # prints "1"<br />
|example2 = print(abs(-1)); # prints "1"<br />
}}<br />
<br />
=== addcommand() ===<br />
{{Nasal doc<br />
|syntax = addcommand(name, code);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=648|t=Source}}<br />
|version = 2.12<br />
|text = {{see also|Howto:Add new fgcommands to FlightGear}}<br />
<br />
This function enables the addition of a new custom [[fgcommands|fgcommand]] to FlightGear from within Nasal. An fgcommand created using this method can be used in exactly the same way as the built-in fgcommands. Also, an fgcommand created via this method will always return True or 1, like all other fgcommands.<br />
|param1 = name<br />
|param1text = This will become the name of the new fgcommand. Must be a string.<br />
|param2 = code<br />
|param2text = The code that will be executed when the fgcommand is run. Must be a function.<br />
|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.<br />
|example1 = addcommand("myFGCmd", func {<br />
print("fgcommand 'myFGCmd' has been run.");<br />
});<br />
fgcommand("myFGCmd");<br />
|example2text = This example demonstrates how parameters are defined in a new fgcommand.<br />
|example2 = addcommand("myFGCmd", func(node){<br />
print(node.getNode("number").getValue()); # prints the value of "number," which is 12<br />
});<br />
fgcommand("myFGCmd", props.Node.new({"number": 12}));<br />
}}<br />
<br />
=== airportinfo() ===<br />
{{Nasal doc<br />
|syntax = airportinfo();<br />
airportinfo(type);<br />
airportinfo(id);<br />
airportinfo(lat, lon[, type]);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1024|t=Source}}<br />
|text = Function for retrieval of airport, heliport, or seaplane base information. It returns a Nasal ghost; however, its structure is like that of a Nasal hash. The following information is returned:<br />
* '''lon''': Longitude of the location.<br />
* '''lat''': Latitude of the location.<br />
* '''has_metar''': True or false depending whether the airport has a [[METAR]] code defined for it.<br />
* '''elevation''': Elevation of the location in metres.<br />
* '''id''': ICAO code of the airport (or ID of the seaplane base/heliport).<br />
* '''name''': Name of the airport/heliport/seaplane base.<br />
* '''runways'''<br />
** '''<runway name>'''<br />
*** '''stopway''': Length of the runway's stopway (the area before the threshold) in metres. Will return 0 if there is none.<br />
*** '''threshold''': Length of the runway's {{wikipedia|displaced threshold}} in metres. Will return 0 if there is none.<br />
*** '''lat''': Latitude of the runway.<br />
*** '''lon''': Longitude of the runway.<br />
*** '''width''': Width of the runway in metres.<br />
*** '''heading''': Heading of the runway.<br />
*** '''length''': Length of the runway in metres.<br />
<br />
Information is extracted in the same way as accessing members of a Nasal hash. For example:<br />
<syntaxhighlight lang="nasal"><br />
# prints to lengths of the runways of the nearest airport in feet and metres<br />
var info = airportinfo();<br />
print("-- Lengths of the runways at ", info.name, " (", info.id, ") --");<br />
foreach(var rwy; keys(info.runways)){<br />
print(rwy, ": ", math.round(info.runways[rwy].length * M2FT), " ft (", info.runways[rwy].length, " m)");<br />
}<br />
</syntaxhighlight><br />
<br />
Note that searches for locations that are a long way away (e.g., the nearest seaplane base to the middle of the Sahara) may cause FlightGear to pause for an amount of time.<br />
|param1 = id<br />
|param1text = The {{wikipedia|International Civil Aviation Organization airport code|ICAO code|noicon=1}} of an airport to retrieve information about.<br />
|param2 = type<br />
|param2text = When this argument is used, the function will return the closest airport of a certain type. Can be one of "heliport," "seaport," or "airport" (default).<br />
: {{inote|Running this function without any parameters is equivalent to this:<br />
: <syntaxhighlight lang="nasal"><br />
airportinfo("airport");<br />
</syntaxhighlight><br />
}}<br />
|param3 = lat ''and'' lon<br />
|param3text = When these parameters are used, the function will return information on the nearest airport, heliport or seaplane base (depending on the '''type''' parameter) to those coordinates.<br />
|example1 = var info = airportinfo();<br />
print("Nearest airport: ", info.name, " (", info.id, ")"); # prints the name and ICAO code of the nearest airport<br />
|example2 = var info = airportinfo("heliport");<br />
print("Elevation of the nearest heliport: ", math.round(info.elevation * M2FT), " ft"); # prints the elevation and name of the nearest heliport<br />
|example3 = var info = airportinfo("KSQL");<br />
print("-- Runways of ", info.name, " (", info.id, "): --");<br />
foreach(var rwy; keys(info.runways)) {<br />
print(rwy); # prints the runways of KSQL<br />
}<br />
|example4 = var info = airportinfo(37.81909385, -122.4722484);<br />
print("Coordinates of the nearest airport: ", info.lat, ", ", info.lon); # print the name and ICAO of the nearest airport to the Golden Gate Bridge<br />
|example5 = var info = airportinfo(37.81909385, -122.4722484, "seaport");<br />
print("Nearest seaplane base: ", info.name, " (", info.id, ")"); # print the name and ID of the nearest seaplane base to the Golden Gate Bridge<br />
|example6text = This example prints the all information from an <code>airportinfo()</code> call.<br />
|example6 = var info = airportinfo("KSFO");<br />
print(info.name);<br />
print(info.id);<br />
print(info.lat);<br />
print(info.lon);<br />
print(info.has_metar);<br />
print(info.elevation);<br />
foreach(var rwy; keys(info.runways)){<br />
print("-- ", rwy, " --");<br />
print(info.runways[rwy].lat);<br />
print(info.runways[rwy].lon);<br />
print(info.runways[rwy].length);<br />
print(info.runways[rwy].width);<br />
print(info.runways[rwy].heading);<br />
print(info.runways[rwy].stopway);<br />
print(info.runways[rwy].threshold);<br />
}<br />
}}<br />
<br />
=== airwaysRoute() ===<br />
{{Nasal doc<br />
|syntax = airwaysRoute(start, end[, type]);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1933|t=Source}}<br />
|text = {{see also|Nasal Flightplan}}<br />
This function returns a vector containing waypoints between two given waypoints. The returned waypoints are ghosts, but can be accessed in the same way as a Nasal hash. See [[Nasal Flightplan]] for more information.<br />
|param1 = start<br />
|param1text = Start waypoint, in the form of a waypoint ghost, such as that provided by {{func link|flightplan}}.<br />
|param2 = end<br />
|param2text = Same as above.<br />
|param3 = type<br />
|param3text = Instructs the function to compute a high level route (when set to "highlevel"), or a low level route (when set to "lowlevel"). Defaults to "highlevel."<br />
|example1text = In the [[route manager]] dialog, add two waypoints to the flightplan, ideally ones that are far apart (tip: use the [[Map]] for this). Then run this code in your Nasal Console.<br />
|example1 = var fp = flightplan();<br />
var start = fp.getWP(0);<br />
var end = fp.getWP(fp.getPlanSize() - 1);<br />
var rt = airwaysRoute(start, end);<br />
foreach(var wp; rt){<br />
print(wp.wp_name); # print the waypoints in the computed route<br />
}<br />
|example2text = Exactly the same as above, but computes a low level path.<br />
|example2 = var fp = flightplan();<br />
var start = fp.getWP(0);<br />
var end = fp.getWP(fp.getPlanSize() - 1);<br />
var rt = airwaysRoute(start, end, "lowlevel");<br />
foreach(var wp; rt){<br />
print(wp.wp_name); # print the waypoints in the computed route<br />
}<br />
}}<br />
<br />
=== assert() ===<br />
{{Nasal doc<br />
|syntax = assert(condition[, message]);<br />
|source = {{fgdata file|Nasal/globals.nas|t=Source}}<br />
|version = 3.2<br />
|text = Returns either true if the condition evaluates as true, or aborts with a {{func link|die}} call, which can be customised.<br />
|param1 = condition<br />
|param1text = Condition to evaluate.<br />
|param2 = message<br />
|param2text = Optional message that will be used in any {{func link|die}} call. Defaults to "assertion failed!"<br />
|example1 = var a = 1;<br />
var b = 2;<br />
print(assert(a < b)); # prints "1" (true)<br />
|example2 = var a = 1;<br />
var b = 2;<br />
assert(a > b, 'a is not greater than b'); # aborts with a custom error message<br />
}}<br />
<br />
=== carttogeod() ===<br />
{{Nasal doc<br />
|syntax = carttogeod(x, y, z);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=945|t=Source}}<br />
|text = Converts {{wikipedia|ECEF|Earth-centered, Earth-fixed}} coordinates (x, y and z) to {{wikipedia|geodetic coordinates}} (latitude, longitude, and altitude). A vector is returned containing latitude and longitude, both in degrees, and altitude, which is returned in metres above the equatorial radius of Earth as defined by the {{wikipedia|WGS 84}} (6,378,137 metres).<ref>{{simgear file|simgear/math/sg_geodesy.hxx|l=43}}</ref><br />
|param1 = x<br />
|param1text = Mandatory x-axis value, in metres.<br />
|param2 = y<br />
|param2text = Mandatory y-axis value, in metres.<br />
|param3 = z<br />
|param3text = Mandatory z-axis value, in metres.<br />
|example1 = var (lat, lon, alt) = carttogeod(6378137, 0, 0); # point is the intersection of the prime meridian and equator.<br />
print("Latitude: ", lat); # prints lat, lon and alt, which are all zero, see above<br />
print("Longitude: ", lon);<br />
print("Altitude: ", alt);<br />
}}<br />
<br />
=== cmdarg() ===<br />
{{Nasal doc<br />
|private = _cmdarg()<br />
|syntax = cmdarg();<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=513|t=Part 1}} {{!}} {{fgdata file|Nasal/globals.nas|t=Part 2}}<br />
|text = <code>cmdarg()</code> returns the property root of certain types of XML files. These could be nodes in the [[Property Tree]], or temporary and/or non-public nodes outside the Property tree. <br />
It is used by Nasal scripts embedded in XML files. It returns a <code>props.Node</code> object (see {{fgdata file|Nasal/props.nas}}), and you can use all of its methods on the returned value. <code>cmdarg()</code> should only be used in four types/places of XML files:<br />
* Bindings: This is needed so that the value of a joystick's axis can be accessed internally.<br />
* Dialogs: This will return the root of the dialog in the Property Tree. This is useful for dialogs that are created/modified procedurally (e.g. for populating/changing widgets while loading the dialog). <br />
* Embedded Canvases: The Nasal code behind [[Canvas]] windows [[Howto:Adding a canvas to a GUI dialog|embedded in PUI dialogs]] can use it to accessing the root directory of their Canvas.<br />
* Animation XML files: If the animation XML file is used in an AI/MP model, <code>cmdarg()</code> will return the root of the AI model in the <code>/ai/models/</code> directory. Examples: <code>/ai/models/aircraft[3]/</code>, <code>/ai/models/multiplayer[1]/</code><br />
<br />
You should not use <code>cmdarg()</code> in places other than those stated above. Although it won't cause an error, it will return the value of the last legitimate <code>cmdarg()</code> call. <br />
<br />
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.<br />
|example1 = fgcommand("dialog-show", {"dialog-name": "cmdarg-demo"});<br />
|example1text = <br>This example demonstrates the usage of <code>cmdarg()</code> in a binding. Save the below XML snippet as <tt>[[$FG_ROOT]]/gui/dialogs/cmdarg-demo.xml</tt>. Then run the Nasal snippet below in your [[Nasal Console]]. Upon clicking {{button|Close}}, a message will be printed sowing the root of the binding in the Property Tree.<br />
<syntaxhighlight lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<br />
<PropertyList><br />
<br />
<name>cmdarg-demo</name><br />
<layout>vbox</layout><br />
<br />
<text><br />
<label>Click "Close" to activate the demonstration (a message in the console).</label><br />
</text><br />
<br />
<button><br />
<legend>Close</legend><br />
<binding><br />
<command>nasal</command><br />
<script>print("Button binding root: '" ~ cmdarg().getPath() ~ "'");</script><br />
</binding><br />
<binding><br />
<command>dialog-close</command><br />
</binding><br />
</button><br />
<br />
</PropertyList><br />
</syntaxhighlight><br />
|example2text = This example demonstrates the usage of <code>cmdarg()</code> in Nasal code within dialogs. Open <tt>[[$FG_ROOT]]/gui/dialogs/cmdarg-demo.xml</tt> from the previous example, copy & paste the code below, and save it. Then run the same Nasal snippet as the previous example in your Nasal Console. If you click {{button|Click me!}}, the button's label will change to "I've been changed!"<br />
<syntaxhighlight lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<br />
<PropertyList><br />
<br />
<name>cmdarg-demo</name><br />
<layout>vbox</layout><br />
<br />
<text><br />
<label>Click "Click me!" to activate the demonstration (the button's label will change).</label><br />
</text><br />
<br />
<button><br />
<legend>Click me!</legend><br />
<binding><br />
<command>nasal</command><br />
<script>change_label();</script><br />
</binding><br />
</button><br />
<br />
<button><br />
<legend>Close</legend><br />
<binding><br />
<command>dialog-close</command><br />
</binding><br />
</button><br />
<br />
<nasal><br />
<open><![CDATA[<br />
var dlg_root = cmdarg();<br />
var dlg_name = {"dialog-name": "cmdarg-demo"};<br />
var change_label = func {<br />
dlg_root.getNode("button[0]/legend").setValue("I've been changed!");<br />
fgcommand("dialog-close", dlg_name);<br />
fgcommand("dialog-show", dlg_name);<br />
}<br />
]]></open><br />
</nasal><br />
<br />
</PropertyList><br />
</syntaxhighlight><br />
|example3text = For an example of <code>cmdarg()</code> used with Canvas, please see [[Howto:Adding a canvas to a GUI dialog#FGPlot|Howto:Adding a canvas to a GUI dialog]].<br />
}}<br />
<br />
=== courseAndDistance() ===<br />
{{Nasal doc<br />
|syntax = courseAndDistance(to);<br />
courseAndDistance(from, to);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1668|t=Source}}<br />
|text = Returns a vector containing the course from one point to another and the distance between them in nautical miles. The course is the initial bearing (see [http://www.movable-type.co.uk/scripts/latlong.html#bearing here]), and is in the range 0–360. Both arguments can be one of:<br />
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type<br />
:* A hash with ''lat'' and ''lon'' members<br />
:* A geo.Coord object<br />
|param1 = from<br />
|param1text = Optional parameter defining the from where the function should calculate its results. If the function is given one argument ('''to'''), the aircraft's current position will be used. As well as the argument types as defined above, this argument can be two numbers separated with a comma, as if the function is taking three arguments. See example 5 below.<br />
|param2 = to<br />
|param2text = Like the first parameter, but defines the second point.<br />
|example1text = This example demonstrates the usage of the function with the <code>airport</code> ghost type.<br />
|example1 = var from = airportinfo("KSFO");<br />
var to = airportinfo("KSQL");<br />
var (course, dist) = courseAndDistance(from, to);<br />
print(course); # prints course from KSFO to KSQL<br />
print(dist); # prints distance in nm from KSFO to KSQL<br />
|example2text = This example demonstrates the usage of the function with hashes containing ''lat'' and ''lon''.<br />
|example2 = var from = {lat: 0, lon: 0};<br />
var to = {lat: 1, lon: 1};<br />
var (course, dist) = courseAndDistance(from, to);<br />
print(course);<br />
print(dist);<br />
|example3text = This example demonstrates usage of a geo.Coord object.<br />
|example3 = var from = geo.Coord.new().set_latlon(0, 0);<br />
var to = geo.Coord.new().set_latlon(1, 1);<br />
var (course, dist) = courseAndDistance(from, to);<br />
print(course);<br />
print(dist);<br />
|example4text = This example demonstrates usage of differing parameter types.<br />
|example4 = var from = airportinfo("KSFO");<br />
var to = geo.Coord.new().set_latlon(0, 0);<br />
var (course, dist) = courseAndDistance(from, to);<br />
print(course);<br />
print(dist);<br />
|example5text = The same as above, but the other way round.<br />
|example5 = var to = {lat: 1, lon: 1};<br />
var (course, dist) = courseAndDistance(0, 0, to);<br />
print(course);<br />
print(dist);<br />
|example6text = Usage of just one parameter.<br />
|example6 = var dest = airportinfo("KSQL");<br />
var (course, dist) = courseAndDistance(dest);<br />
print("Turn to heading ", math.round(course), ". You have ", sprintf("%.2f", dist), " nm to go");<br />
}}<br />
<br />
=== createWP() ===<br />
{{Nasal doc<br />
|syntax = createWP(pos, name[, flag]);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1964|t=Source}}<br />
|text = Creates a new waypoint ghost object.<br />
|param1 = pos<br />
|param1text = Dictates the position of the new waypoint. It can be one of the following:<br />
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type<br />
:* A hash with ''lat'' and ''lon'' members<br />
:* A geo.Coord object<br />
:* Two numbers separated by a comma, as if the function is taking three arguments. See example 4 below.<br />
|param2 = name<br />
|param2text = String that will become the name of the new waypoint.<br />
|param3 = flag<br />
|param3text = Optional string that will tell FlightGear what type of waypoint it is. Must be one of "sid," "star," "approach," "missed," or "pseudo."<br />
|example1text = Creates a waypoint directly in front and 1 km away and appends it to the flight plan.<br />
|example1 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);<br />
var wp = createWP(pos, "NEWWP");<br />
var fp = flightplan();<br />
fp.appendWP(wp);<br />
|example2 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);<br />
var wp = createWP({lat: pos.lat(), lon: pos.lon()}, "NEWWP");<br />
var fp = flightplan();<br />
fp.appendWP(wp);<br />
|example3 = var apt = airportinfo();<br />
var wp = createWP(apt, "NEWWP");<br />
var fp = flightplan();<br />
fp.appendWP(wp);<br />
|example4 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);<br />
var wp = createWP(pos.lat(), pos.lon(), "NEWWP");<br />
var fp = flightplan();<br />
fp.appendWP(wp);<br />
|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.<br />
|example5 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);<br />
var wp = createWP(pos, "NEWWP", "pseudo");<br />
var fp = flightplan();<br />
fp.appendWP(wp);<br />
print(fp.getPlanSize());<br />
fp.clearWPType("pseudo");<br />
print(fp.getPlanSize());<br />
}}<br />
<br />
=== createWPFrom() ===<br />
{{Nasal doc<br />
|syntax = createWPFrom(object[, flag]);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1989|t=Source}}<br />
|text = Creates a new waypoint object from another object.<br />
|param1 = object<br />
|param1text = A ghost object. Must be a ghost type that is one of "airport," "navaid," "runway," or "fix."<br />
|param2 = flag<br />
|param2text = Optional string that will tell FlightGear what type of waypoint it is. Must be one of "sid," "star," "approach," "missed," or "pseudo."<br />
|example1text = Creates a new waypoint and appends it to the flight plan.<br />
|example1 = var apt = airportinfo("KSFO");<br />
var wp = createWPFrom(apt);<br />
var fp = flightplan();<br />
fp.appendWP(wp);<br />
|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.<br />
|example2 = var apt = airportinfo("KSFO");<br />
var wp = createWPFrom(apt, "pseudo");<br />
print(wp.wp_name);<br />
var fp = flightplan();<br />
fp.appendWP(wp);<br />
print(fp.getPlanSize());<br />
fp.clearWPType("pseudo");<br />
print(fp.getPlanSize());<br />
}}<br />
<br />
=== defined() ===<br />
{{Nasal doc<br />
|syntax = defined(symbol);<br />
|source = {{fgdata file|Nasal/globals.nas|t=Source}}<br />
|text = Returns 1 (true) or 0 (false) depending on whether a variable exists.<br />
|param1 = symbol<br />
|param1text = A string that will be what the function searches for.<br />
|example1 = var number = 12;<br />
var check_exist = func {<br />
print("Variable 'number' ", defined("number") == 1 ? "exists" : "does not exist"); # 'number' does exist<br />
print("Variable 'number2' ", defined("number2") == 1 ? "exists" : "does not exist"); # 'number2' does not exist<br />
}<br />
check_exist();<br />
}}<br />
<br />
=== directory() ===<br />
{{Nasal doc<br />
|syntax = directory(path);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=572|t=Source}}<br />
|text = Returns a vector containing a list of the folders and files in a given file path or <code>'''nil'''</code> if the path doesn't exist. Hidden folders and files are not added to the vector.<br />
{{inote|The first two elements of the vector will be <code>'.'</code> and <code>'..'</code>. These are for navigating back up the file tree, but have no use in Nasal. They can be safely removed from the vector.}}<br />
|param1 = path<br />
|param1text = Absolute file path.<br />
|example1text = Gets the folders and files in [[$FG_ROOT]], and then removes the extra first two elements (see note above). <br />
|example1 = var dir = directory(getprop("/sim/fg-root")); # get directory<br />
dir = subvec(dir, 2); # strips off the first two elements<br />
debug.dump(dir); # dump the vector<br />
}}<br />
<br />
=== fgcommand() ===<br />
{{Nasal doc<br />
|syntax = fgcommand(cmd[, args]);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=456|t=Part 1}} {{!}} {{fgdata file|Nasal/globals.nas|t=Part 2}}<br />
|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.<br />
|param1 = cmd<br />
|param1text = String that is the name of the command that is to be run.<br />
|param2 = args<br />
|param2text = If the fgcommand takes arguments, they are inputted using this argument. Can either be a <code>props.Node</code> object, or a hash (see examples below).<br />
|example1 = fgcommand("null"); # does nothing<br />
|example2 = var args = props.Node.new({'script': 'print("Running fgcommand");'});<br />
if (fgcommand("nasal", args)) { # prints "Running fgcommand" and then one of these print statements<br />
print("Fgcommand succeeded");<br />
} else {<br />
print("Fgcommand encountered a problem");<br />
}<br />
|example3 = var args = { 'dialog-name': 'about' };<br />
fgcommand("dialog-show", args); # shows the 'about' dialog<br />
}}<br />
<br />
=== findAirportsByICAO() ===<br />
{{Nasal doc<br />
|syntax = findAirportsByICAO(search[, type]);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1096|t=Source}}<br />
|text = Returns a vector containing <code>airport</code> ghost objects which are (by default) airports whose ICAO code matches the search string. The results are sorted by range from closest to furthest.<br />
|param1 = search<br />
|param1text = Search string for the function. Can either be a partial or a full ICAO code.<br />
:{{icaution|The more matches there are for the given code, the longer the function will take. Passing just one character (e.g., "K"), might make FlightGear hang for a certain amount of time.}}<br />
|param2 = type<br />
|param2text = This will narrow the search to airports of a certain type. By default, only airports are searched for. May be one of "airport," "heliport," or "seaport."<br />
|example1 = var apts = findAirportsByICAO("KSF"); # finds all airports matching "KSF"<br />
foreach(var apt; apts){<br />
print(apt.name, " (", apt.id, ")"); # prints them<br />
}<br />
|example2 = var apts = findAirportsByICAO("SP0", "seaport"); # finds all seaplane bases matching "SP0"<br />
foreach(var apt; apts){<br />
print(apt.name, " (", apt.id, ")"); # prints them<br />
}<br />
|example3 = var apt = findAirportsByICAO("XBET"); # one way to check if an airport does exist"<br />
if (size(apt) == 0) {<br />
print("Airport does not exist"); # this one will be printed<br />
} else {<br />
print("Airport does exist");<br />
}<br />
}}<br />
<br />
=== findAirportsWithinRange() ===<br />
{{Nasal doc<br />
|syntax = findAirportsWithinRange([pos, ]range[, type]);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1066|t=Source}}<br />
|text = Returns a vector of <code>airport</code> ghost object which are (by default) airports that are within a given range of a given position, or the aircraft's current position. The results are sorted by range from closest to furthest.<br />
|param1 = pos<br />
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:<br />
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type<br />
:* A hash with ''lat'' and ''lon'' members<br />
:* A geo.Coord object<br />
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findAirportsWithinRange(lat, lon, range, type);</code>.<br />
|param2 = range<br />
|param2text = Mandatory number giving the range in nautical miles within which to search for airports/heliports/seaplane bases.only airports are searched for.<br />
|param3 = type<br />
|param3text = This will narrow the search to airports of a certain type. By default, only airports are searched for. May be one of "airport," "heliport," or "seaport."<br />
|example1text = Searches for airports within 10 nm of [[KSFO]].<br />
|example1 = var pos = airportinfo("KSFO");<br />
var apts = findAirportsWithinRange(pos, 10);<br />
foreach(var apt; apts){<br />
print(apt.name, " (", apt.id, ")");<br />
}<br />
|example2text = Searches for seaplane bases within 15 nm of [[KSFO]].<br />
|example2 = var pos = airportinfo("KSFO");<br />
var apts = findAirportsWithinRange(pos, 15, "seaport");<br />
foreach(var apt; apts){<br />
print(apt.name, " (", apt.id, ")");<br />
}<br />
|example3text = Searches for airports within 10 nm of your current position.<br />
|example3 = var apts = findAirportsWithinRange(10);<br />
foreach(var apt; apts){<br />
print(apt.name, " (", apt.id, ")");<br />
}<br />
}}<br />
<br />
=== findFixesByID() ===<br />
{{Nasal doc<br />
|syntax = findFixesByID([pos, ]id);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1627|t=Source}}<br />
|text = Returns a vector containing <code>fix</code> ghost objects matching a given ID, sorted by range from a certain position.<br />
{{inote|Fixes are (usually) also known as waypoints.}}<br />
|param1 = pos<br />
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:<br />
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type<br />
:* A hash with ''lat'' and ''lon'' members<br />
:* A geo.Coord object<br />
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findFixesByID(lat, lon, id);</code>.<br />
|param2 = id<br />
|param2text = Full or partial ID of the fix to search for.<br />
:{{inote|1=Inputting a partial ID does not work correctly (see [http://forum.flightgear.org/viewtopic.php?f=30&t=28129 here]). It is best to just input a full ID.}}<br />
|example1 = var fixes = findFixesByID("POGIC");<br />
foreach(var fix; fixes){<br />
print(fix.id, " - lat: ", fix.lat, " {{!}} lon: ", fix.lon); # prints information about POGIC<br />
}<br />
|example2 = var fix = findFixesByID("ZUNAP");<br />
fix = fix[0];<br />
var (course, dist) = courseAndDistance(fix);<br />
print("Turn to heading ", math.round(course), ". You have ", sprintf("%.2f", dist), " nm to go to reach ", fixes[0].id);<br />
}}<br />
<br />
=== findNavaidByFrequency() ===<br />
{{Nasal doc<br />
|syntax = findNavaidByFrequency([pos, ]freq[, type]);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1547|t=Source}}<br />
|text = Returns a <code>navaid</code> ghost object for a navaid matching a given frequency. If there is more than one navaid with that frequency, the nearest station is returned.<br />
|param1 = pos<br />
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:<br />
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type<br />
:* A hash with ''lat'' and ''lon'' members<br />
:* A geo.Coord object<br />
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidByFrequency(lat, lon, freq, type);</code>.<br />
|param2 = freq<br />
|param2text = Frequency, in megahertz, of the navaid to search for.<br />
|param3 = type<br />
|param3text = This will narrow the search to navaids of a certain type. Defaults to "all." For the full list of accepted type arguments, see {{flightgear file|src/Navaids/positioned.cxx|l=127}}.<br />
|example1 = var navaid = findNavaidByFrequency(11.17);<br />
print("ID: ", navaid.id); # prints info about the navaid<br />
print("Name: ", navaid.name);<br />
print("Latitude: ", navaid.lat);<br />
print("Longitude: ", navaid.lon);<br />
print("Elevation (AMSL): ", navaid.elevation, " m");<br />
print("Type: ", navaid.type);<br />
print("Frequency: ", sprintf("%.3f", navaid.frequency / 1000), " Mhz");<br />
print("Range: ", navaid.range_nm, " nm");<br />
if(navaid.course) print("Course: ", navaid.course);<br />
}}<br />
<br />
=== findNavaidsByFrequency() ===<br />
{{Nasal doc<br />
|syntax = findNavaidsByFrequency([pos, ]freq[, type]);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1572|t=Source}}<br />
|text = Returns a vector conatining <code>navaid</code> ghost objects for navaids that match a given frequency, sorted from nearest to furthest.<br />
|param1 = pos<br />
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:<br />
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type<br />
:* A hash with ''lat'' and ''lon'' members<br />
:* A geo.Coord object<br />
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidsByFrequency(lat, lon, freq, type);</code>.<br />
|param2 = freq<br />
|param2text = Frequency, in megahertz, of the navaid to search for.<br />
|param3 = type<br />
|param3text = This will narrow the search to navaids of a certain type. Defaults to "all." For the full list of accepted type arguments, see {{flightgear file|src/Navaids/positioned.cxx|l=127}}.<br />
|example1 = var navaids = findNavaidsByFrequency(10.955);<br />
foreach(var navaid; navaids){<br />
print("--");<br />
print("ID: ", navaid.id); # prints info about the navaid<br />
print("Name: ", navaid.name);<br />
print("Latitude: ", navaid.lat);<br />
print("Longitude: ", navaid.lon);<br />
print("Elevation (AMSL): ", navaid.elevation, " m");<br />
print("Type: ", navaid.type);<br />
print("Frequency: ", sprintf("%.3f", navaid.frequency / 1000), " Mhz");<br />
print("Range: ", navaid.range_nm, " nm");<br />
if(navaid.course) print("Course: ", navaid.course);<br />
print("--");<br />
}<br />
}}<br />
<br />
=== findNavaidsByID() ===<br />
{{Nasal doc<br />
|syntax = findNavaidsByID([pos, ]id[, type]);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1600|t=Source}}<br />
|text = Returns a vector containing <code>navaid</code> ghost objects matching a given ID, sorted by range from a certain position.<br />
|param1 = pos<br />
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:<br />
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type<br />
:* A hash with ''lat'' and ''lon'' members<br />
:* A geo.Coord object<br />
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidsByID(lat, lon, id, type);</code>.<br />
|param2 = id<br />
|param2text = Full or partial ID of the fix to search for.<br />
:{{inote|1=Inputting a partial ID does not work correctly (see [http://forum.flightgear.org/viewtopic.php?f=30&t=28129 here]). It is best to just input a full ID.}}<br />
|param3 = type<br />
|param3text = This will narrow the search to navaids of a certain type. Defaults to "all." For the full list of accepted type arguments, see {{flightgear file|src/Navaids/positioned.cxx|l=127}}.<br />
|example1 = var navaid = findNavaidsByID("MXW");<br />
navaid = navaid[0];<br />
print("ID: ", navaid.id); # prints info about 'MXW' (a VOR station)<br />
print("Name: ", navaid.name);<br />
print("Latitude: ", navaid.lat);<br />
print("Longitude: ", navaid.lon);<br />
print("Elevation (AMSL): ", navaid.elevation, " m");<br />
print("Type: ", navaid.type);<br />
print("Frequency: ", sprintf("%.3f", navaid.frequency / 1000), " Mhz");<br />
print("Range: ", navaid.range_nm, " nm");<br />
}}<br />
<br />
=== findNavaidsWithinRange() ===<br />
{{Nasal doc<br />
|syntax = findNavaidsWithinRange([pos, ]range[, type]);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1518|t=Source}}<br />
|text = Returns a vector of <code>navaid</code> ghost objects which are within a given range of a given position (by default the aircraft's current position). The results are sorted from closest to furthest.<br />
|param1 = pos<br />
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:<br />
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type<br />
:* A hash with ''lat'' and ''lon'' members<br />
:* A geo.Coord object<br />
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidsWithinRange(lat, lon, range, type);</code>.<br />
|param2 = range<br />
|param2text = Mandatory number giving the range in nautical miles within which to search for navaids. Defaults to "all." For the full list of accepted type arguments, see {{flightgear file|src/Navaids/positioned.cxx|l=127}}.<br />
|param3 = type<br />
|param3text = This will narrow the search to navaids of a certain type.<br />
|example1text = Searches for navaids within 10 nm of [[KSFO]].<br />
|example1 = var pos = airportinfo("KSFO");<br />
var navs = findNavaidsWithinRange(pos, 10);<br />
foreach(var nav; navs){<br />
print(nav.name, " (ID: ", nav.id, ")");<br />
}<br />
|example2text = Searches for navaids within 10 nm of your current position.<br />
|example2 = var navs = findNavaidsWithinRange(10);<br />
foreach(var nav; navs){<br />
print(nav.name, " (ID: ", nav.id, ")");<br />
}<br />
}}<br />
<br />
=== finddata() ===<br />
{{Nasal doc<br />
|syntax = finddata(path);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=603|t=Source}}<br />
|text = Takes a relative path and tries to return an absolute one. It works by appending the relative path to some paths and testing to see if they exist. As of FlightGear v3.7, these paths are the TerraSync directory (tested first) and [[$FG_ROOT]]. <br />
|param1 = path<br />
|param1text = A relative path as a string.<br />
|example1 = var path = finddata("Aircraft/Generic");<br />
print(path); # prints the absolute path to $FG_ROOT/Aircraft/Generic<br />
|example2 = var path = finddata("Airports");<br />
print(path); # prints the absolute path to <TerraSync dir>/Airports<br />
|example3 = var path = finddata("preferences.xml");<br />
print(path); # prints the absolute path to $FG_ROOT/preferences.xml<br />
}}<br />
<br />
=== flightplan() ===<br />
{{Nasal doc<br />
|syntax = flightplan([path]);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1738|t=Source}}<br />
|text = {{see also|Nasal Flightplan}}<br />
Returns a flight plan object, either one for the current flight plan, or one loaded from a given path.<br />
|param1 = path<br />
|param1text = Optional path to flight plan XML file.<br />
|example1text = Gets the active flight plan and gets the ID of the current waypoint. Note that this example requires a flight plan to be set in the [[Route Manager]] first.<br />
|example1 = var fp = flightplan();<br />
print(fp.getWP(fp.current).id);<br />
|example2text = Creates a new flight plan from an XML file and prints the IDs of the waypoints. Note that this example requires a flight plan to have been created and saved as <tt>''[[$FG_HOME]]/fp-demo.xml''</tt>.<br />
|example2 = var path = getprop('/sim/fg-home') ~ '/fp-demo.xml';<br />
var fp = flightplan(path);<br />
for(var i = 0; i < fp.getPlanSize(); i += 1){<br />
print(fp.getWP(i).id);<br />
}<br />
}}<br />
<br />
=== geodinfo() ===<br />
{{Nasal doc<br />
|syntax = geodinfo(lat, lon[, max_alt]);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=981|t=Source}}<br />
|text = Returns a vector containing two entries or <code>'''nil'''</code> if no information could be obtained because the terrain tile wasn't loaded. The first entry in the vector is the elevation (in meters) for the given point, and the second is a hash with information about the assigned material (as defined in <tt>''[[$FG_ROOT]]/Materials''</tt>), or <code>'''nil'''</code> if there was no material information available (for example, because there is an untextured building at that location). The structure of the hash is as follows (see also {{readme file|materials}}):<br />
* '''light_coverage:''' The coverage of a single point of light in m<sup>2</sup>.<br />
* '''bumpiness:''' Normalized bumpiness factor for the material.<br />
* '''load_resistance:''' The amount of pressure in N/m<sup>2</sup> the material can withstand without deformation.<br />
* '''solid:''' 1 (true) or false (0) depending on whether the material is solid or not.<br />
* '''names:''' Vector of scenery types (usually generated by [[TerraGear]]) that will use this material. <br />
* '''friction_factor:''' Normalized friction factor of the material.<br />
* '''rolling_friction:''' The rolling friction coefficient of the material.<br />
<br />
Note that this function is a ''very'' CPU-intensive operation, particularly in FlightGear v2.4 and earlier. It is advised to use this function as little as possible.<br />
|param1 = lat<br />
|param1text = Latitude, inputted as a number.<br />
|param2 = lon<br />
|param2text = Longitude, inputted as a number.<br />
|param3 = max_alt<br />
|param3text = The altitude, in metres, from which the function will begin searching for the height of the terrain. Defaults to 10,000 metres. If the terrain is higher than this argument specifies, <code>'''nil'''</code> will be returned.<br />
|example1text = Dumps information about ground underneath the aircraft.<br />
|example1 = var pos = geo.aircraft_position();<br />
var info = geodinfo(pos.lat(), pos.lon());<br />
debug.dump(info);<br />
|example2text = Prints whether the ground underneath the aircraft is solid or is water.<br />
|example2 = var pos = geo.aircraft_position();<br />
var info = geodinfo(pos.lat(), pos.lon());<br />
if (info != nil and info[1] != nil) {<br />
print("The ground underneath the aircraft is ", info[1].solid == 1 ? "solid." : "water.");<br />
}<br />
}}<br />
<br />
=== geodtocart() ===<br />
{{Nasal doc<br />
|syntax = geodtocart(lat, lon, alt);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=962|t=Source}}<br />
|text = Converts {{wikipedia|geodetic coordinates}} (latitude, longitude, and altitude) to {{wikipedia|ECEF|Earth-centered, Earth-fixed}} coordinates (x, y and z). A vector is returned containing x, y, and z in metres. The equatorial radius of earth used is that defined by the {{wikipedia|WGS 84}} (6,378,137 metres). All argument are mandatory.<br />
|param1 = lat<br />
|param1text = Latitude, in degrees.<br />
|param2 = lon<br />
|param2text = Longitude, in degrees.<br />
|param3 = alt<br />
|param3text = Altitude, in metres.<br />
|example1 = var (x, y, z) = geodtocart(0, 0, 0); # point is the intersection of the prime meridian and equator.<br />
print("x: ", x); # prints "x: 6378137"<br />
print("y: ", y); # prints "y: 0"<br />
print("z: ", z); # prints "y: 0"<br />
}}<br />
<br />
=== getprop() ===<br />
{{Nasal doc<br />
|syntax = getprop(arg[, arg[, ...]]);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=345|t=Source}}<br />
|text = Returns the value of a node in the [[property tree]] or <code>'''nil'''</code> if the node does not exist or the value is not a number (NaN).<br />
|param1 = arg<br />
|param1text = There needs to be at least one argument, but there is no limit to the maximum amount of arguments that can be given. The arguments will be concatenated together to form a property tree path. The arguments must be strings, but in FlightGear v3.2 onwards, there is support (added by {{flightgear commit|34ed79}}) for numeric arguments as indices. See example 2 below.<br />
|example1 = print("You have FlightGear v", getprop("/sim/version/flightgear")); # prints FlightGear version<br />
|example2text = Note that the example below will only work in FlightGear 3.2 and above.<br />
|example2 = for(var i = 0; i < 8; i += 1){<br />
print("View #", i + 1, " is named ", getprop("/sim/view", i, "name"));<br />
}<br />
|example3text = Same as above, but is supported by all version of FlightGear.<br />
|example3 = for(var i = 0; i < 8; i += 1){<br />
print("View #", i + 1, " is named ", getprop("/sim/view[" ~ i ~ "]/name"));<br />
}<br />
}}<br />
<br />
=== greatCircleMove() ===<br />
{{Nasal doc<br />
|syntax = greatCircleMove([pos, ]course, dist);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1681|t=Source}}<br />
|text = Calculates a new set of geodetic coordinates using inputs of course and distance, either from the aircraft's current position (by default) or from another set of coordinates. Returns a hash containing two members, ''lat'' and ''lon'' (latitude and longitude respectively).<br />
|param1 = pos<br />
|param1text = Optional position to calculate from. If not given, the aircraft's current position will be used. Can be one of:<br />
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost object.<br />
:* A hash with ''lat'' and ''lon'' members<br />
:* A <code>geo.Coord</code> object<br />
:* A lat/lon pair, that is, a pair of numbers (latitude followed by longitude) separated by a comma: <code>greatCircleMove(lat,lon, ...)</code>.<br />
|param2 = course<br />
|param2text = Course to new set of coordinates, in degrees (in the range 0–360).<br />
|param3 = dist<br />
|param3text = Distance in nautical miles to the new set of coordinates.<br />
|example1 = var pos = greatCircleMove(0,0, 0, 1);<br />
debug.dump(pos); # print hash with coordinates<br />
|example2 = var fix = findFixesByID("POGIC");<br />
fix = fix[0];<br />
var pos = greatCircleMove(fix, 45, 10);<br />
debug.dump(pos); # print hash with coordinates<br />
}}<br />
<br />
=== interpolate() ===<br />
{{Nasal doc<br />
|private = _interpolate()<br />
|syntax = interpolate(prop, value1, time1[, value2, time2[, ...]]);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=522|t=Part 1}} {{!}} {{fgdata file|Nasal/globals.nas|t=Part 2}}<br />
|text = Linearly interpolates a node in the property tree to a given value in a specified time. The value/time pairs will be run one after the other in the order that they are passed to the function. Note that the interpolation will continue even when the simulation is paused.<br />
|param1 = prop<br />
|param1text = String or <code>props.Node</code> object that indicates a node in the property tree to be used.<br />
|param2 = value''n''<br />
|param2text = Target value to change the property to in the set amount of time. This should be a number.<br />
|param3 = time''n''<br />
|param3text = Time in seconds, that will be taken for the interpolation.<br />
|example1text = Paste the code below into the Nasal Console and execute. Then, open the Property Browser and look for the property. Finally, run the code again, and watch the value of the property change.<br />
|example1 = setprop("/test", 0); # (re-)set property<br />
interpolate("/test",<br />
50, 5, # interpolate to 50 in 5 seconds<br />
10, 2, # interpolate to 10 in 2 seconds<br />
0, 5); # interpolate to 0 in 5 seconds<br />
|example2 = # Apply the left brake at 20% per second<br />
var prop = "controls/gear/brake-left";<br />
var dist = 1 - getprop(prop);<br />
if (dist == 1) {<br />
interpolate(prop, 1, dist / 0.2);<br />
}<br />
}}<br />
<br />
=== isa() ===<br />
{{Nasal doc<br />
|syntax = isa(object, class);<br />
|source = {{fgdata file|Nasal/globals.nas|t=Source}}<br />
|text = Checks if an object is an instance of, or inherits from, a second object (or class), returning 1 (true) if it is and 0 (false) if otherwise.<br />
|param1 = object<br />
|param1text = Object to check.<br />
|param2 = class<br />
|param2text = Class/object to check that '''object''' inherits from or is an instance of.<br />
|example1 = var coord = geo.Coord.new();<br />
if(isa(coord, geo.Coord)){<br />
print("Variable 'coord' is an instance of class 'geo.Coord'"); # this one will be printed<br />
} else {<br />
print("Variable 'coord' is not an instance of class 'geo.Coord'");<br />
}<br />
|example2 = var coord = geo.Coord.new();<br />
if(isa(coord, props.Node)){<br />
print("Variable 'coord' is an instance of class 'props.Node'");<br />
} else {<br />
print("Variable 'coord' is not an instance of class 'props.Node'"); # this one will be printed<br />
}<br />
|example3text = The example below demonstrates checking of inheritance.<br />
|example3 = var Const = {<br />
constant: 2,<br />
getConst: func {<br />
return me.constant;<br />
}<br />
};<br />
<br />
var Add = {<br />
new: func {<br />
return { parents: [Add, Const] };<br />
},<br />
<br />
addToConst: func(a){<br />
return a * me.getConst();<br />
}<br />
};<br />
<br />
var m = Add.new();<br />
print(m.addToConst(4));<br />
<br />
if(isa(m, Add)) print("Variable 'm' is an instance of class 'Add'"); # will be printed<br />
if(isa(m, Const)) print("Variable 'm' is an instance of class 'Const'"); # will also be printed<br />
}}<br />
<br />
=== logprint() ===<br />
{{Nasal doc<br />
|syntax = logprint(priority[, msg[, msg[, ...]]]);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=431|t=Source}}<br />
|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, for example, the Nasal Console, rather than {{flightgear file|src/Scripting/NasalSys.cxx}}.<br />
|param1 = priority<br />
|param1text = Number specifying the priority level of the outputted message:<br />
:{{{!}} class="wikitable"<br />
! Number !! Debug type<br />
{{!-}}<br />
{{!}} 1 {{!!}} Bulk<br />
{{!-}}<br />
{{!}} 2 {{!!}} Debug<br />
{{!-}}<br />
{{!}} 3 {{!!}} Info<br />
{{!-}}<br />
{{!}} 4 {{!!}} Warn<br />
{{!-}}<br />
{{!}} 5 {{!!}} Alert<br />
{{!}}}<br />
|param2 = msg<br />
|param2text = The message. There is no limit to the arguments you give give. They will be concatenated together before logging.<br />
|example1 = # logs the value of pi to three decimal places with log level 3<br />
logprint(3, "pi = ", sprintf("%.3f", math.pi));<br />
|example2 = logprint(5, "Alert! This is an important message!");<br />
}}<br />
<br />
=== removecommand() ===<br />
<br />
As you can guess, there's also a removecommand() function which will remove '''any''' command – even those implemented in C++! As such it can be very dangerous and remove core functionality, so use with caution.<br />
<br />
=== print() ===<br />
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.<br />
<br />
<syntaxhighlight lang="nasal"><br />
print("Just", " a ", "test");<br />
</syntaxhighlight><br />
<br />
=== setprop() ===<br />
Sets a property value for a given node path string. Returns 1 on success or 0 if the property could not be set (i.e. was read-only).<br />
<br />
<syntaxhighlight lang="nasal"><br />
setprop(<path> [, <path>, [...]], <value>);<br />
</syntaxhighlight><br />
<br />
All arguments but the last are concatenated to a path string, like getprop() above. The last value is written to the respective node. If the node isn't writable, then an error message is printed to the console.<br />
<br />
Examples:<br />
<br />
<syntaxhighlight lang="nasal"><br />
setprop("/sim/current-view/view-number", 2);<br />
setprop("/controls", "engines/engine[0]", "reverser", 1);<br />
</syntaxhighlight><br />
<br />
'''Erasing a property from the property tree''': a property that has been created, for example through <tt>setprop()</tt> has to be erased using the props namespace helper, like this:<br />
<br />
<syntaxhighlight lang="nasal"><br />
props.globals.getNode("foo/bar").remove(); # take out the complete node<br />
props.globals.getNode("foo").removeChild("bar"); # take out a certain child node<br />
</syntaxhighlight><br />
<br />
=== setlistener() ===<br />
<br />
=== settimer() ===<br />
{{Leaking Nasal Disclaimer<br />
|oldapi=settimer()<br />
|newapi=maketimer()<br />
}}<br />
Runs a function after a given simulation time (default) or real time in seconds.<br />
<br />
<syntaxhighlight lang="nasal"><br />
settimer(<function>, <time> [, <realtime=0>]);<br />
</syntaxhighlight><br />
<br />
The '''first argument''' 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. <br />
<br />
The '''second argument''' is a delay time. After this amount of time the function will be executed.<br />
For instance, if you want to print the words "My result" in five seconds, use this code:<br />
<br />
<syntaxhighlight lang="nasal"><br />
settimer ( func { print ( "My result"); }, 5);<br />
</syntaxhighlight><br />
<br />
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:<br />
<br />
<syntaxhighlight lang="nasal"><br />
myarg1="My favorite string";<br />
myarg2=432;<br />
settimer ( func { myfunction ( myarg1, myarg2); }, 25);<br />
</syntaxhighlight><br />
<br />
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.<br />
<br />
<syntaxhighlight lang="nasal"><br />
# simulation time example<br />
var copilot_annoyed = func { setprop("/sim/messages/copilot", "Stop it! Immediately!") }<br />
settimer(copilot_annoyed, 10);<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="nasal"><br />
# real time example<br />
var popdown = func ( tipArg ) { <br />
fgcommand("dialog-close", tipArg); <br />
}<br />
<br />
var selfStatusPopupTip = func (label, delay = 10, override = nil) { <br />
var tmpl = props.Node.new({<br />
name : "PopTipSelf", modal : 0, layout : "hbox",<br />
y: 140,<br />
text : { label : label, padding : 6 }<br />
});<br />
if (override != nil) tmpl.setValues(override);<br />
<br />
popdown(tipArgSelf);<br />
fgcommand("dialog-new", tmpl);<br />
fgcommand("dialog-show", tipArgSelf);<br />
<br />
currTimerSelf += 1;<br />
var thisTimerSelf = currTimerSelf;<br />
<br />
# Final argument 1 is a flag to use "real" time, not simulated time<br />
settimer(func { if(currTimerSelf == thisTimerSelf) { popdown(tipArgSelf) } }, delay, 1);<br />
}<br />
</syntaxhighlight><br />
<br />
[[Nasal scripting language#settimer loops|More information about using the settimer function to create loops.]]<br />
<br />
=== maketimer() ===<br />
{{FG ver|2.12+}}<br />
<br />
Since FlightGear v2.12, 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.<br />
<br />
<syntaxhighlight lang="nasal"><br />
var timer = maketimer(<interval>, <function>);<br />
var timer = maketimer(<interval>, <self>, <function>);<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="nasal"><br />
timer.start();<br />
timer.stop();<br />
timer.restart(<interval>);<br />
timer.singleShot [read/write]<br />
timer.isRunning [read-only]<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="nasal"><br />
# create timer with 1 second interval<br />
var timer = maketimer(1, func(){ <br />
print('timer called'); <br />
});<br />
<br />
# start the timer (with 1 second inverval)<br />
timer.start();<br />
<br />
# restart timer with 4 second interval<br />
timer.restart(4);<br />
<br />
# fire one single time in 6 seconds<br />
timer.singleShot = 1;<br />
timer.restart(6);<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="nasal"><br />
var Tooltip = {<br />
new: func(){<br />
var m = { parents: [Tooltip] };<br />
<br />
m._hideTimer = maketimer(1.0, m, Tooltip._hideTimeout);<br />
m._hideTimer.singleShot = 1;<br />
<br />
return m;<br />
},<br />
<br />
run: func(){<br />
if(!me._hideTimer.isRunning) me._hideTimer.start();<br />
},<br />
<br />
_hideTimeout: func(){<br />
print("_hideTimeout");<br />
}<br />
};<br />
<br />
var t = Tooltip.new();<br />
t.run();<br />
</syntaxhighlight><br />
<br />
=== history() (3.1+) ===<br />
<br />
Function to expose flight history as aircraft.history()<br />
<br />
<syntaxhighlight lang="nasal"><br />
var hist = aircraft.history();<br />
<br />
# get history of aircraft position/orientation collapsing<br />
# nodes with a distance smaller than the given minimum<br />
# edge legth<br />
debug.dump( hist.pathForHistory(<minimum-edge-length-meter>) );<br />
</syntaxhighlight><br />
<br />
=== systime() ===<br />
Returns epoch time (time since 1970/01/01 00:00) in seconds as a floating point number with high resolution. This is useful for benchmarking purposes.<br />
<br />
<syntaxhighlight lang="nasal"><br />
#benchmarking example:<br />
var start = systime();<br />
how_fast_am_I(123);<br />
var end = systime();<br />
print("took ", end - start, " seconds");<br />
</syntaxhighlight><br />
<br />
=== parsexml() ===<br />
<br />
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).<br />
<br />
<syntaxhighlight lang="nasal"><br />
var ret = parsexml(<path> [, <start-elem> [, <end-elem> [, <data> [, <pi> ]]]]);<br />
<br />
<start-elem> ... called for every starting tag with two arguments: the tag name, and an attribute hash<br />
<end-elem> ... called for every ending tag with one argument: the tag name<br />
<data> ... called for every piece of data with one argument: the data string<br />
<pi> ... called for every "processing information" with two args: target and data string<br />
<br />
<ret> ... the return value is nil on error, and the <path> otherwise<br />
</syntaxhighlight><br />
<br />
Example:<br />
<br />
<syntaxhighlight lang="nasal"><br />
var start = func(name, attr) {<br />
print("starting tag ", name);<br />
foreach (var a; keys(attr))<br />
print("\twith attribute ", a, "=", attr[a]);<br />
}<br />
var end = func(name) { print("ending tag ", name) }<br />
var data = func(data) { print("data=", data) }<br />
var pi = func(target, data) { print("processing instruction: target=", target, " data=", data) }<br />
parsexml("/tmp/foo.xml", start, end, data, pi);<br />
</syntaxhighlight><br />
<br />
=== resolvepath() ===<br />
<br />
SimGear features its own [[Resolving Paths|path resolving framework]] that takes a relative path and returns an absolute path, checking from base directories such as [[$FG_ROOT]], [[$FG_HOME]], [[$FG_AIRCRAFT]], and the current aircraft directory (<tt>/sim/aircraft-dir</tt>). This function in Nasal takes a path string and returns the absolute path or an empty string if the path couldn't be resolved.<br />
<br />
Example:<br />
<br />
<syntaxhighlight lang="nasal"><br />
var guess_path = func(path...) {<br />
var path_concat = string.join(path, "/");<br />
var file_path = resolvepath(path_concat);<br />
if (file_path == "") die("Path not found: "~path_concat);<br />
return file_path;<br />
}<br />
</syntaxhighlight><br />
<br />
=== HTTP module (2.99+) ===<br />
<br />
Get remote data using the HTTP.<br />
<br />
==== http.load() ====<br />
<br />
Load resource identified by its URL into memory.<br />
<br />
<syntaxhighlight lang="nasal"><br />
var request = http.load(<url>);<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="nasal"><br />
http.load("http://example.com/test.txt")<br />
.done(func(r) print("Got response: " ~ r.response));<br />
</syntaxhighlight><br />
<br />
==== http.save() ====<br />
<br />
Save resource to a local file.<br />
<br />
<syntaxhighlight lang="nasal"><br />
var request = http.save(<url>, <file_path>);<br />
</syntaxhighlight><br />
<br />
<syntaxhighlight lang="nasal"><br />
http.save("http://example.com/test.png", getprop('/sim/fg-home') ~ '/cache/test.png')<br />
.fail(func print("Download failed!"))<br />
.done(func(r) print("Finished request with status: " ~ r.status ~ " " ~ r.reason))<br />
.always(func print("Request complete (fail or success)"));<br />
</syntaxhighlight><br />
<br />
=== rand() ===<br />
<br />
Return a random number as generated by <tt>sg_random</tt>.<br />
<br />
=== srand() ===<br />
<br />
Seed the random number generator based upon the current time. Returns 0.<br />
<br />
=== md5() (3.1+) ===<br />
<br />
Get the md5 hash of a string.<br />
<br />
<syntaxhighlight lang="nasal"><br />
var hash = md5(<str>);<br />
</syntaxhighlight><br />
<br />
{{Appendix}}</div>Chris-barryhttps://wiki.flightgear.org/w/index.php?title=Nasal_library_functions&diff=92154Nasal library functions2016-02-01T03:24:00Z<p>Chris-barry: </p>
<hr />
<div>{{Nasal Navigation}}<br />
<br />
Please first see: http://plausible.org/nasal/lib.html<br />
<br />
A better and more complete description of these functions can also be found at http://wiki.flightgear.org/Nasal_library<br />
<br />
== size() ==<br />
'''Usage:'''<br />
<br />
size(''object'');<br />
<br />
where ''object'' may be a ''string'', a ''vector'' or a ''hash''.<br />
<br />
'''Return value'''<br />
<br />
An intger equal to the number of characters in a ''string'' argument or the number of elements in a ''vector'' or ''hash''.<br />
<br />
If the argument is a non-string scalar then the error '''object has no size()''' will be generated.<br />
<br />
== keys() ==<br />
<br />
== append() ==<br />
<br />
== pop() ==<br />
<br />
== setsize() ==<br />
'''Usage:'''<br />
<br />
setsize(vect, new_size)<br />
<br />
where ''vect'' is an expression which evaluates to a vector and ''new_size'' is an expression that evaluates to a non-negative number.<br />
<br />
'''Action:'''<br />
<br />
Changes the number of elements in the vetor ''v'' to the value of s.<br />
<br />
'''Return value:'''<br />
<br />
The resized vector.<br />
<br />
'''Notes'''<br />
<br />
Elements that exist in both the original and the resized vector retain their values. When the vector is enlarged newly created elements are set to ''nil''. When the size is reduced the values of all elements beyond the new size are permanently lost.<br />
<br />
The ''new_size'' argument may be any non-negative number. Non-integer values are rounded down.<br />
<br />
The ''vect'' argument need not be a named variable. The expression:<br />
<br />
var v1 = setsize([], n);<br />
<br />
Is a convenient way to allocate an empty vector of a specific size.<br />
<br />
== subvec() ==<br />
<br />
Create a new vector comprising elements from a contiguous range of elements of an existing vector.<br />
<br />
'''Usage:'''<br />
<br />
subvec([''vect'', [''start'', [''count'']]])<br />
<br />
<dl><br />
<dt>''vect''</dt><br />
<dd>The original vector</dd><br />
<dt>''start''</dt><br />
<dd>The zero-based index in the original vector of the first element to be copied.</dd><br />
<dt>''count''</dt><br />
<dd>The number of elements to copy. If this argument is omitted then ''size(vect) - start'' is assumed.</dd><br />
</dl><br />
<br />
'''Return value'''<br />
<br />
A new vector containing the specified range from the original vector, or ''nil''.<br />
<br />
'''Notes:'''<br />
<ol><br />
<li><br />
Omitting the ''vect'' and ''start'' arguments is not an error (possibly it should be) but the return value is ''nil''.<br />
</li><br />
<li><br />
A negative ''start'' argument ''is'' an error. This seems wrong. Perhaps the language designer could comment.<br />
</li><br />
<li><br />
A value of ''start'' greater than ''size(vect)'' causes an error. A value equal to ''size(vect)'' returns an empty vector.<br />
</li><br />
<li><br />
If the value of ''count'' is greater than ''size(vect) - start'' then it is ignored. That is, all elements from ''start'' to the end of ''vect'' are returned. If ''count'' is zero then an empty vector is returned. A negative value of ''count'' causes an error.<br />
</ol><br />
<br />
Example :<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var FGRoot = getprop("/sim/fg-root");<br />
var filename = "/Aircraft";<br />
var path_files = directory(FGRoot ~ filename);<br />
<br />
foreach(var key; path_files) {<br />
print(key);<br />
}<br />
</syntaxhighlight><br />
returns : '''"." , ".." , "Generic", "Instruments", "Instruments-3d", "c172p", "ufo"'''<br />
<br />
<br />
With subvec():<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var FGRoot = getprop("/sim/fg-root");<br />
var filename = "/Aircraft";<br />
var path_files = subvec(directory(FGRoot ~ filename),2);<br />
<br />
foreach(var key; path_files) {<br />
print(key);<br />
}<br />
</syntaxhighlight><br />
returns : '''"Generic", "Instruments", "Instruments-3d", "c172p", "ufo"'''<br />
<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var FGRoot = getprop("/sim/fg-root");<br />
var filename = "/Aircraft";<br />
var path_files = subvec(directory(FGRoot ~ filename),3);<br />
<br />
foreach(var key; path_files) {<br />
print(key);<br />
}<br />
</syntaxhighlight><br />
returns : '''"Instruments", "Instruments-3d", "c172p", "ufo"'''<br />
<br />
== delete() ==<br />
Remove an element from a hash.<br />
<br />
'''Usage'''<br />
<br />
delete(''hash'', ''key'')<br />
<br />
Remove the element with key ''key'' from the hash ''hash''. If the key is not present then the hash is unaltered.<br />
<br />
== int() ==<br />
<br />
== num(str) ==<br />
Convert string to number.<br />
Returns nil if str is nil, empty string, string with no number.<br />
<br />
== streq() ==<br />
<br />
== cmp() ==<br />
<br />
== substr() ==<br />
<br />
== chr() ==<br />
<br />
== contains() ==<br />
<br />
== typeof() ==<br />
<br />
== ghosttype(ghost) ==<br />
Returns a string containing either a descriptive name as passed to ''naNewGhost'' or ''naNewGhost2'' in C/C++ while creating the ghost or a unique id (aka the pointer to the C/C++ naGhostType instance) if no name has been set.<br />
<br />
== compile() ==<br />
<br />
== call() ==<br />
<br />
== die() ==<br />
<br />
== sprintf() ==<br />
<br />
== caller() ==<br />
<br />
== closure() ==<br />
<br />
== find() ==<br />
<br />
== split() ==<br />
<br />
== rand() ==<br />
<br />
== bind() ==<br />
<br />
== sort() ==<br />
<br />
== id() ==<br />
<br />
= math =<br />
== Trigonometric_functions ==<br />
'''Caution''': All trigonometric functions works with [https://en.wikipedia.org/wiki/Radian Radian]-values - not with Degree!<br />
<br />
<u>To convert this</u>:<br><br />
radians = degree * math.pi / 180<br><br />
degree = radians * 180 / math.pi<br />
=== sin() ===<br />
=== cos() ===<br />
=== tan() ===<br />
=== asin() ===<br />
=== acos() ===<br />
=== atan2() ===<br />
== exp() ==<br />
== ln() ==<br />
== pow() ==<br />
== sqrt() ==<br />
== floor() ==<br />
Returns the value rounded downward<br />
<br />
Example:<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
math.floor(1.2); # returns 1<br />
math.floor(1.6); # returns 1<br />
</syntaxhighlight><br />
<br />
== ceil() ==<br />
Returns the value rounded upward<br />
<br />
Example:<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
math.ceil(1.2); # returns 2<br />
math.ceil(1.6); # returns 2<br />
</syntaxhighlight><br />
<br />
== fmod() ==<br />
A '''modulo'''-operator. The [https://en.wikipedia.org/wiki/Modulo_operation modulo]-operation finds the remainder of division of one number by another (sometimes called modulus).<br />
<br />
fmod(x , y) may be negative if x < 0, whereas mod() seems to guarantee that 0 ≤ mod(x,y) < y, according to tests made with x and y integers, y > 0, x positive or negative.<br />
<br />
== clamp() ==<br />
== periodic() ==<br />
== round() ==<br />
== pi ==<br />
== e ==<br />
<br />
= io =<br />
<br />
* SEEK_SET<br />
* SEEK_CUR<br />
* SEEK_END<br />
* stdin<br />
* stdout<br />
* stderr<br />
<br />
== stat() ==<br />
== directory() ==<br />
returns the files in a given directory<br />
<br />
e.g. chatter_list = directory( chatter_dir );<br />
<br />
Example : <br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var FGRoot = getprop("/sim/fg-root");<br />
var filename = "/Aircraft";<br />
var path_files = directory(FGRoot ~ filename);<br />
<br />
foreach(var key; path_files) {<br />
print(key);<br />
}<br />
</syntaxhighlight><br />
returns : <br />
'''"." , ".." , "Generic", "Instruments", "Instruments-3d", "c172p", "ufo"'''<br />
<br />
To delete the "." and ".." see the subvec() function.<br />
<br />
== open() ==<br />
== read() ==<br />
== readln() ==<br />
== seek() ==<br />
== tell() ==<br />
== write() ==<br />
== flush() ==<br />
== close() ==<br />
<br />
= utf8 =<br />
== chstr() ==<br />
== strc() ==<br />
== substr() ==<br />
== size() ==<br />
== validate() ==</div>Chris-barryhttps://wiki.flightgear.org/w/index.php?title=Nasal_library_functions&diff=92153Nasal library functions2016-02-01T03:17:55Z<p>Chris-barry: /* delete() */</p>
<hr />
<div>{{Nasal Navigation}}<br />
<br />
Please first see: http://plausible.org/nasal/lib.html<br />
<br />
== size() ==<br />
'''Usage:'''<br />
<br />
size(''object'');<br />
<br />
where ''object'' may be a ''string'', a ''vector'' or a ''hash''.<br />
<br />
'''Return value'''<br />
<br />
An intger equal to the number of characters in a ''string'' argument or the number of elements in a ''vector'' or ''hash''.<br />
<br />
If the argument is a non-string scalar then the error '''object has no size()''' will be generated.<br />
<br />
== keys() ==<br />
<br />
== append() ==<br />
<br />
== pop() ==<br />
<br />
== setsize() ==<br />
'''Usage:'''<br />
<br />
setsize(vect, new_size)<br />
<br />
where ''vect'' is an expression which evaluates to a vector and ''new_size'' is an expression that evaluates to a non-negative number.<br />
<br />
'''Action:'''<br />
<br />
Changes the number of elements in the vetor ''v'' to the value of s.<br />
<br />
'''Return value:'''<br />
<br />
The resized vector.<br />
<br />
'''Notes'''<br />
<br />
Elements that exist in both the original and the resized vector retain their values. When the vector is enlarged newly created elements are set to ''nil''. When the size is reduced the values of all elements beyond the new size are permanently lost.<br />
<br />
The ''new_size'' argument may be any non-negative number. Non-integer values are rounded down.<br />
<br />
The ''vect'' argument need not be a named variable. The expression:<br />
<br />
var v1 = setsize([], n);<br />
<br />
Is a convenient way to allocate an empty vector of a specific size.<br />
<br />
== subvec() ==<br />
<br />
Create a new vector comprising elements from a contiguous range of elements of an existing vector.<br />
<br />
'''Usage:'''<br />
<br />
subvec([''vect'', [''start'', [''count'']]])<br />
<br />
<dl><br />
<dt>''vect''</dt><br />
<dd>The original vector</dd><br />
<dt>''start''</dt><br />
<dd>The zero-based index in the original vector of the first element to be copied.</dd><br />
<dt>''count''</dt><br />
<dd>The number of elements to copy. If this argument is omitted then ''size(vect) - start'' is assumed.</dd><br />
</dl><br />
<br />
'''Return value'''<br />
<br />
A new vector containing the specified range from the original vector, or ''nil''.<br />
<br />
'''Notes:'''<br />
<ol><br />
<li><br />
Omitting the ''vect'' and ''start'' arguments is not an error (possibly it should be) but the return value is ''nil''.<br />
</li><br />
<li><br />
A negative ''start'' argument ''is'' an error. This seems wrong. Perhaps the language designer could comment.<br />
</li><br />
<li><br />
A value of ''start'' greater than ''size(vect)'' causes an error. A value equal to ''size(vect)'' returns an empty vector.<br />
</li><br />
<li><br />
If the value of ''count'' is greater than ''size(vect) - start'' then it is ignored. That is, all elements from ''start'' to the end of ''vect'' are returned. If ''count'' is zero then an empty vector is returned. A negative value of ''count'' causes an error.<br />
</ol><br />
<br />
Example :<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var FGRoot = getprop("/sim/fg-root");<br />
var filename = "/Aircraft";<br />
var path_files = directory(FGRoot ~ filename);<br />
<br />
foreach(var key; path_files) {<br />
print(key);<br />
}<br />
</syntaxhighlight><br />
returns : '''"." , ".." , "Generic", "Instruments", "Instruments-3d", "c172p", "ufo"'''<br />
<br />
<br />
With subvec():<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var FGRoot = getprop("/sim/fg-root");<br />
var filename = "/Aircraft";<br />
var path_files = subvec(directory(FGRoot ~ filename),2);<br />
<br />
foreach(var key; path_files) {<br />
print(key);<br />
}<br />
</syntaxhighlight><br />
returns : '''"Generic", "Instruments", "Instruments-3d", "c172p", "ufo"'''<br />
<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var FGRoot = getprop("/sim/fg-root");<br />
var filename = "/Aircraft";<br />
var path_files = subvec(directory(FGRoot ~ filename),3);<br />
<br />
foreach(var key; path_files) {<br />
print(key);<br />
}<br />
</syntaxhighlight><br />
returns : '''"Instruments", "Instruments-3d", "c172p", "ufo"'''<br />
<br />
== delete() ==<br />
Remove an element from a hash.<br />
<br />
'''Usage'''<br />
<br />
delete(''hash'', ''key'')<br />
<br />
Remove the element with key ''key'' from the hash ''hash''. If the key is not present then the hash is unaltered.<br />
<br />
== int() ==<br />
<br />
== num(str) ==<br />
Convert string to number.<br />
Returns nil if str is nil, empty string, string with no number.<br />
<br />
== streq() ==<br />
<br />
== cmp() ==<br />
<br />
== substr() ==<br />
<br />
== chr() ==<br />
<br />
== contains() ==<br />
<br />
== typeof() ==<br />
<br />
== ghosttype(ghost) ==<br />
Returns a string containing either a descriptive name as passed to ''naNewGhost'' or ''naNewGhost2'' in C/C++ while creating the ghost or a unique id (aka the pointer to the C/C++ naGhostType instance) if no name has been set.<br />
<br />
== compile() ==<br />
<br />
== call() ==<br />
<br />
== die() ==<br />
<br />
== sprintf() ==<br />
<br />
== caller() ==<br />
<br />
== closure() ==<br />
<br />
== find() ==<br />
<br />
== split() ==<br />
<br />
== rand() ==<br />
<br />
== bind() ==<br />
<br />
== sort() ==<br />
<br />
== id() ==<br />
<br />
= math =<br />
== Trigonometric_functions ==<br />
'''Caution''': All trigonometric functions works with [https://en.wikipedia.org/wiki/Radian Radian]-values - not with Degree!<br />
<br />
<u>To convert this</u>:<br><br />
radians = degree * math.pi / 180<br><br />
degree = radians * 180 / math.pi<br />
=== sin() ===<br />
=== cos() ===<br />
=== tan() ===<br />
=== asin() ===<br />
=== acos() ===<br />
=== atan2() ===<br />
== exp() ==<br />
== ln() ==<br />
== pow() ==<br />
== sqrt() ==<br />
== floor() ==<br />
Returns the value rounded downward<br />
<br />
Example:<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
math.floor(1.2); # returns 1<br />
math.floor(1.6); # returns 1<br />
</syntaxhighlight><br />
<br />
== ceil() ==<br />
Returns the value rounded upward<br />
<br />
Example:<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
math.ceil(1.2); # returns 2<br />
math.ceil(1.6); # returns 2<br />
</syntaxhighlight><br />
<br />
== fmod() ==<br />
A '''modulo'''-operator. The [https://en.wikipedia.org/wiki/Modulo_operation modulo]-operation finds the remainder of division of one number by another (sometimes called modulus).<br />
<br />
fmod(x , y) may be negative if x < 0, whereas mod() seems to guarantee that 0 ≤ mod(x,y) < y, according to tests made with x and y integers, y > 0, x positive or negative.<br />
<br />
== clamp() ==<br />
== periodic() ==<br />
== round() ==<br />
== pi ==<br />
== e ==<br />
<br />
= io =<br />
<br />
* SEEK_SET<br />
* SEEK_CUR<br />
* SEEK_END<br />
* stdin<br />
* stdout<br />
* stderr<br />
<br />
== stat() ==<br />
== directory() ==<br />
returns the files in a given directory<br />
<br />
e.g. chatter_list = directory( chatter_dir );<br />
<br />
Example : <br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var FGRoot = getprop("/sim/fg-root");<br />
var filename = "/Aircraft";<br />
var path_files = directory(FGRoot ~ filename);<br />
<br />
foreach(var key; path_files) {<br />
print(key);<br />
}<br />
</syntaxhighlight><br />
returns : <br />
'''"." , ".." , "Generic", "Instruments", "Instruments-3d", "c172p", "ufo"'''<br />
<br />
To delete the "." and ".." see the subvec() function.<br />
<br />
== open() ==<br />
== read() ==<br />
== readln() ==<br />
== seek() ==<br />
== tell() ==<br />
== write() ==<br />
== flush() ==<br />
== close() ==<br />
<br />
= utf8 =<br />
== chstr() ==<br />
== strc() ==<br />
== substr() ==<br />
== size() ==<br />
== validate() ==</div>Chris-barryhttps://wiki.flightgear.org/w/index.php?title=Nasal_library_functions&diff=92152Nasal library functions2016-02-01T02:50:47Z<p>Chris-barry: /* subvec() */</p>
<hr />
<div>{{Nasal Navigation}}<br />
<br />
Please first see: http://plausible.org/nasal/lib.html<br />
<br />
== size() ==<br />
'''Usage:'''<br />
<br />
size(''object'');<br />
<br />
where ''object'' may be a ''string'', a ''vector'' or a ''hash''.<br />
<br />
'''Return value'''<br />
<br />
An intger equal to the number of characters in a ''string'' argument or the number of elements in a ''vector'' or ''hash''.<br />
<br />
If the argument is a non-string scalar then the error '''object has no size()''' will be generated.<br />
<br />
== keys() ==<br />
<br />
== append() ==<br />
<br />
== pop() ==<br />
<br />
== setsize() ==<br />
'''Usage:'''<br />
<br />
setsize(vect, new_size)<br />
<br />
where ''vect'' is an expression which evaluates to a vector and ''new_size'' is an expression that evaluates to a non-negative number.<br />
<br />
'''Action:'''<br />
<br />
Changes the number of elements in the vetor ''v'' to the value of s.<br />
<br />
'''Return value:'''<br />
<br />
The resized vector.<br />
<br />
'''Notes'''<br />
<br />
Elements that exist in both the original and the resized vector retain their values. When the vector is enlarged newly created elements are set to ''nil''. When the size is reduced the values of all elements beyond the new size are permanently lost.<br />
<br />
The ''new_size'' argument may be any non-negative number. Non-integer values are rounded down.<br />
<br />
The ''vect'' argument need not be a named variable. The expression:<br />
<br />
var v1 = setsize([], n);<br />
<br />
Is a convenient way to allocate an empty vector of a specific size.<br />
<br />
== subvec() ==<br />
<br />
Create a new vector comprising elements from a contiguous range of elements of an existing vector.<br />
<br />
'''Usage:'''<br />
<br />
subvec([''vect'', [''start'', [''count'']]])<br />
<br />
<dl><br />
<dt>''vect''</dt><br />
<dd>The original vector</dd><br />
<dt>''start''</dt><br />
<dd>The zero-based index in the original vector of the first element to be copied.</dd><br />
<dt>''count''</dt><br />
<dd>The number of elements to copy. If this argument is omitted then ''size(vect) - start'' is assumed.</dd><br />
</dl><br />
<br />
'''Return value'''<br />
<br />
A new vector containing the specified range from the original vector, or ''nil''.<br />
<br />
'''Notes:'''<br />
<ol><br />
<li><br />
Omitting the ''vect'' and ''start'' arguments is not an error (possibly it should be) but the return value is ''nil''.<br />
</li><br />
<li><br />
A negative ''start'' argument ''is'' an error. This seems wrong. Perhaps the language designer could comment.<br />
</li><br />
<li><br />
A value of ''start'' greater than ''size(vect)'' causes an error. A value equal to ''size(vect)'' returns an empty vector.<br />
</li><br />
<li><br />
If the value of ''count'' is greater than ''size(vect) - start'' then it is ignored. That is, all elements from ''start'' to the end of ''vect'' are returned. If ''count'' is zero then an empty vector is returned. A negative value of ''count'' causes an error.<br />
</ol><br />
<br />
Example :<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var FGRoot = getprop("/sim/fg-root");<br />
var filename = "/Aircraft";<br />
var path_files = directory(FGRoot ~ filename);<br />
<br />
foreach(var key; path_files) {<br />
print(key);<br />
}<br />
</syntaxhighlight><br />
returns : '''"." , ".." , "Generic", "Instruments", "Instruments-3d", "c172p", "ufo"'''<br />
<br />
<br />
With subvec():<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var FGRoot = getprop("/sim/fg-root");<br />
var filename = "/Aircraft";<br />
var path_files = subvec(directory(FGRoot ~ filename),2);<br />
<br />
foreach(var key; path_files) {<br />
print(key);<br />
}<br />
</syntaxhighlight><br />
returns : '''"Generic", "Instruments", "Instruments-3d", "c172p", "ufo"'''<br />
<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var FGRoot = getprop("/sim/fg-root");<br />
var filename = "/Aircraft";<br />
var path_files = subvec(directory(FGRoot ~ filename),3);<br />
<br />
foreach(var key; path_files) {<br />
print(key);<br />
}<br />
</syntaxhighlight><br />
returns : '''"Instruments", "Instruments-3d", "c172p", "ufo"'''<br />
<br />
== delete() ==<br />
<br />
<br />
== int() ==<br />
<br />
== num(str) ==<br />
Convert string to number.<br />
Returns nil if str is nil, empty string, string with no number.<br />
<br />
== streq() ==<br />
<br />
== cmp() ==<br />
<br />
== substr() ==<br />
<br />
== chr() ==<br />
<br />
== contains() ==<br />
<br />
== typeof() ==<br />
<br />
== ghosttype(ghost) ==<br />
Returns a string containing either a descriptive name as passed to ''naNewGhost'' or ''naNewGhost2'' in C/C++ while creating the ghost or a unique id (aka the pointer to the C/C++ naGhostType instance) if no name has been set.<br />
<br />
== compile() ==<br />
<br />
== call() ==<br />
<br />
== die() ==<br />
<br />
== sprintf() ==<br />
<br />
== caller() ==<br />
<br />
== closure() ==<br />
<br />
== find() ==<br />
<br />
== split() ==<br />
<br />
== rand() ==<br />
<br />
== bind() ==<br />
<br />
== sort() ==<br />
<br />
== id() ==<br />
<br />
= math =<br />
== Trigonometric_functions ==<br />
'''Caution''': All trigonometric functions works with [https://en.wikipedia.org/wiki/Radian Radian]-values - not with Degree!<br />
<br />
<u>To convert this</u>:<br><br />
radians = degree * math.pi / 180<br><br />
degree = radians * 180 / math.pi<br />
=== sin() ===<br />
=== cos() ===<br />
=== tan() ===<br />
=== asin() ===<br />
=== acos() ===<br />
=== atan2() ===<br />
== exp() ==<br />
== ln() ==<br />
== pow() ==<br />
== sqrt() ==<br />
== floor() ==<br />
Returns the value rounded downward<br />
<br />
Example:<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
math.floor(1.2); # returns 1<br />
math.floor(1.6); # returns 1<br />
</syntaxhighlight><br />
<br />
== ceil() ==<br />
Returns the value rounded upward<br />
<br />
Example:<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
math.ceil(1.2); # returns 2<br />
math.ceil(1.6); # returns 2<br />
</syntaxhighlight><br />
<br />
== fmod() ==<br />
A '''modulo'''-operator. The [https://en.wikipedia.org/wiki/Modulo_operation modulo]-operation finds the remainder of division of one number by another (sometimes called modulus).<br />
<br />
fmod(x , y) may be negative if x < 0, whereas mod() seems to guarantee that 0 ≤ mod(x,y) < y, according to tests made with x and y integers, y > 0, x positive or negative.<br />
<br />
== clamp() ==<br />
== periodic() ==<br />
== round() ==<br />
== pi ==<br />
== e ==<br />
<br />
= io =<br />
<br />
* SEEK_SET<br />
* SEEK_CUR<br />
* SEEK_END<br />
* stdin<br />
* stdout<br />
* stderr<br />
<br />
== stat() ==<br />
== directory() ==<br />
returns the files in a given directory<br />
<br />
e.g. chatter_list = directory( chatter_dir );<br />
<br />
Example : <br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var FGRoot = getprop("/sim/fg-root");<br />
var filename = "/Aircraft";<br />
var path_files = directory(FGRoot ~ filename);<br />
<br />
foreach(var key; path_files) {<br />
print(key);<br />
}<br />
</syntaxhighlight><br />
returns : <br />
'''"." , ".." , "Generic", "Instruments", "Instruments-3d", "c172p", "ufo"'''<br />
<br />
To delete the "." and ".." see the subvec() function.<br />
<br />
== open() ==<br />
== read() ==<br />
== readln() ==<br />
== seek() ==<br />
== tell() ==<br />
== write() ==<br />
== flush() ==<br />
== close() ==<br />
<br />
= utf8 =<br />
== chstr() ==<br />
== strc() ==<br />
== substr() ==<br />
== size() ==<br />
== validate() ==</div>Chris-barryhttps://wiki.flightgear.org/w/index.php?title=Nasal_library_functions&diff=92151Nasal library functions2016-02-01T02:49:03Z<p>Chris-barry: /* subvec() */</p>
<hr />
<div>{{Nasal Navigation}}<br />
<br />
Please first see: http://plausible.org/nasal/lib.html<br />
<br />
== size() ==<br />
'''Usage:'''<br />
<br />
size(''object'');<br />
<br />
where ''object'' may be a ''string'', a ''vector'' or a ''hash''.<br />
<br />
'''Return value'''<br />
<br />
An intger equal to the number of characters in a ''string'' argument or the number of elements in a ''vector'' or ''hash''.<br />
<br />
If the argument is a non-string scalar then the error '''object has no size()''' will be generated.<br />
<br />
== keys() ==<br />
<br />
== append() ==<br />
<br />
== pop() ==<br />
<br />
== setsize() ==<br />
'''Usage:'''<br />
<br />
setsize(vect, new_size)<br />
<br />
where ''vect'' is an expression which evaluates to a vector and ''new_size'' is an expression that evaluates to a non-negative number.<br />
<br />
'''Action:'''<br />
<br />
Changes the number of elements in the vetor ''v'' to the value of s.<br />
<br />
'''Return value:'''<br />
<br />
The resized vector.<br />
<br />
'''Notes'''<br />
<br />
Elements that exist in both the original and the resized vector retain their values. When the vector is enlarged newly created elements are set to ''nil''. When the size is reduced the values of all elements beyond the new size are permanently lost.<br />
<br />
The ''new_size'' argument may be any non-negative number. Non-integer values are rounded down.<br />
<br />
The ''vect'' argument need not be a named variable. The expression:<br />
<br />
var v1 = setsize([], n);<br />
<br />
Is a convenient way to allocate an empty vector of a specific size.<br />
<br />
== subvec() ==<br />
<br />
Create a new vector comprising elements from a contiguous range of elements of an existing vector.<br />
<br />
'''Usage:'''<br />
<br />
subvec([''vect'', [''start'', [''count'']]])<br />
<br />
<dl><br />
<dt>''vect''</dt><br />
<dd>The original vector</dd><br />
<dt>''start''</dt><br />
<dd>The zero-based index in the original vector of the first element to be copied.</dd><br />
<dt>''count''</dt><br />
<dd>The number of elements to copy. If this argument is omitted then ''size(vect) - start'' is assumed.</dd><br />
</dl><br />
<br />
'''Return value'''<br />
<br />
A new vector containing the specified range from the original vector, or ''nil''.<br />
<br />
'''Notes:'''<br />
<ol><br />
<li><br />
Omitting the ''vect'' and ''start'' arguments is not an error (possibly it should be) but the return value is ''nil''.<br />
</li><br />
<li><br />
A negative ''start'' argument ''is'' an error. This seems wrong. Perhaps the language designer could comment.<br />
</li><br />
<li><br />
A value of ''start'' greater than ''size(vect)'' causes an error. A value equal to ''size(vect)'' returns an empty vector.<br />
</li><br />
<li><br />
If the value of ''count'' is greater than ''size(vect) - start'' then it is ignored. That is, all elements from ''start'' to the end of ''vect'' are returned. A negative value of ''count'' causes an error.<br />
</ol><br />
<br />
Example :<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var FGRoot = getprop("/sim/fg-root");<br />
var filename = "/Aircraft";<br />
var path_files = directory(FGRoot ~ filename);<br />
<br />
foreach(var key; path_files) {<br />
print(key);<br />
}<br />
</syntaxhighlight><br />
returns : '''"." , ".." , "Generic", "Instruments", "Instruments-3d", "c172p", "ufo"'''<br />
<br />
<br />
With subvec():<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var FGRoot = getprop("/sim/fg-root");<br />
var filename = "/Aircraft";<br />
var path_files = subvec(directory(FGRoot ~ filename),2);<br />
<br />
foreach(var key; path_files) {<br />
print(key);<br />
}<br />
</syntaxhighlight><br />
returns : '''"Generic", "Instruments", "Instruments-3d", "c172p", "ufo"'''<br />
<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var FGRoot = getprop("/sim/fg-root");<br />
var filename = "/Aircraft";<br />
var path_files = subvec(directory(FGRoot ~ filename),3);<br />
<br />
foreach(var key; path_files) {<br />
print(key);<br />
}<br />
</syntaxhighlight><br />
returns : '''"Instruments", "Instruments-3d", "c172p", "ufo"'''<br />
<br />
== delete() ==<br />
<br />
<br />
== int() ==<br />
<br />
== num(str) ==<br />
Convert string to number.<br />
Returns nil if str is nil, empty string, string with no number.<br />
<br />
== streq() ==<br />
<br />
== cmp() ==<br />
<br />
== substr() ==<br />
<br />
== chr() ==<br />
<br />
== contains() ==<br />
<br />
== typeof() ==<br />
<br />
== ghosttype(ghost) ==<br />
Returns a string containing either a descriptive name as passed to ''naNewGhost'' or ''naNewGhost2'' in C/C++ while creating the ghost or a unique id (aka the pointer to the C/C++ naGhostType instance) if no name has been set.<br />
<br />
== compile() ==<br />
<br />
== call() ==<br />
<br />
== die() ==<br />
<br />
== sprintf() ==<br />
<br />
== caller() ==<br />
<br />
== closure() ==<br />
<br />
== find() ==<br />
<br />
== split() ==<br />
<br />
== rand() ==<br />
<br />
== bind() ==<br />
<br />
== sort() ==<br />
<br />
== id() ==<br />
<br />
= math =<br />
== Trigonometric_functions ==<br />
'''Caution''': All trigonometric functions works with [https://en.wikipedia.org/wiki/Radian Radian]-values - not with Degree!<br />
<br />
<u>To convert this</u>:<br><br />
radians = degree * math.pi / 180<br><br />
degree = radians * 180 / math.pi<br />
=== sin() ===<br />
=== cos() ===<br />
=== tan() ===<br />
=== asin() ===<br />
=== acos() ===<br />
=== atan2() ===<br />
== exp() ==<br />
== ln() ==<br />
== pow() ==<br />
== sqrt() ==<br />
== floor() ==<br />
Returns the value rounded downward<br />
<br />
Example:<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
math.floor(1.2); # returns 1<br />
math.floor(1.6); # returns 1<br />
</syntaxhighlight><br />
<br />
== ceil() ==<br />
Returns the value rounded upward<br />
<br />
Example:<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
math.ceil(1.2); # returns 2<br />
math.ceil(1.6); # returns 2<br />
</syntaxhighlight><br />
<br />
== fmod() ==<br />
A '''modulo'''-operator. The [https://en.wikipedia.org/wiki/Modulo_operation modulo]-operation finds the remainder of division of one number by another (sometimes called modulus).<br />
<br />
fmod(x , y) may be negative if x < 0, whereas mod() seems to guarantee that 0 ≤ mod(x,y) < y, according to tests made with x and y integers, y > 0, x positive or negative.<br />
<br />
== clamp() ==<br />
== periodic() ==<br />
== round() ==<br />
== pi ==<br />
== e ==<br />
<br />
= io =<br />
<br />
* SEEK_SET<br />
* SEEK_CUR<br />
* SEEK_END<br />
* stdin<br />
* stdout<br />
* stderr<br />
<br />
== stat() ==<br />
== directory() ==<br />
returns the files in a given directory<br />
<br />
e.g. chatter_list = directory( chatter_dir );<br />
<br />
Example : <br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var FGRoot = getprop("/sim/fg-root");<br />
var filename = "/Aircraft";<br />
var path_files = directory(FGRoot ~ filename);<br />
<br />
foreach(var key; path_files) {<br />
print(key);<br />
}<br />
</syntaxhighlight><br />
returns : <br />
'''"." , ".." , "Generic", "Instruments", "Instruments-3d", "c172p", "ufo"'''<br />
<br />
To delete the "." and ".." see the subvec() function.<br />
<br />
== open() ==<br />
== read() ==<br />
== readln() ==<br />
== seek() ==<br />
== tell() ==<br />
== write() ==<br />
== flush() ==<br />
== close() ==<br />
<br />
= utf8 =<br />
== chstr() ==<br />
== strc() ==<br />
== substr() ==<br />
== size() ==<br />
== validate() ==</div>Chris-barryhttps://wiki.flightgear.org/w/index.php?title=Nasal_library_functions&diff=92150Nasal library functions2016-02-01T02:48:04Z<p>Chris-barry: /* subvec() */</p>
<hr />
<div>{{Nasal Navigation}}<br />
<br />
Please first see: http://plausible.org/nasal/lib.html<br />
<br />
== size() ==<br />
'''Usage:'''<br />
<br />
size(''object'');<br />
<br />
where ''object'' may be a ''string'', a ''vector'' or a ''hash''.<br />
<br />
'''Return value'''<br />
<br />
An intger equal to the number of characters in a ''string'' argument or the number of elements in a ''vector'' or ''hash''.<br />
<br />
If the argument is a non-string scalar then the error '''object has no size()''' will be generated.<br />
<br />
== keys() ==<br />
<br />
== append() ==<br />
<br />
== pop() ==<br />
<br />
== setsize() ==<br />
'''Usage:'''<br />
<br />
setsize(vect, new_size)<br />
<br />
where ''vect'' is an expression which evaluates to a vector and ''new_size'' is an expression that evaluates to a non-negative number.<br />
<br />
'''Action:'''<br />
<br />
Changes the number of elements in the vetor ''v'' to the value of s.<br />
<br />
'''Return value:'''<br />
<br />
The resized vector.<br />
<br />
'''Notes'''<br />
<br />
Elements that exist in both the original and the resized vector retain their values. When the vector is enlarged newly created elements are set to ''nil''. When the size is reduced the values of all elements beyond the new size are permanently lost.<br />
<br />
The ''new_size'' argument may be any non-negative number. Non-integer values are rounded down.<br />
<br />
The ''vect'' argument need not be a named variable. The expression:<br />
<br />
var v1 = setsize([], n);<br />
<br />
Is a convenient way to allocate an empty vector of a specific size.<br />
<br />
== subvec() ==<br />
<br />
Create a new vector comprising elements from a contiguous range of elements of an existing vector.<br />
<br />
'''Usage:'''<br />
<br />
subvec([''vect'', [''start'', [''count'']]])<br />
<br />
<dl><br />
<dt>''vect''</dt><br />
<dd>The original vector</dd><br />
<dt>''start''</dt><br />
<dd>The zero-based index in the original vector of the first element to be copied.</dd><br />
<dt>''count''</dt><br />
<dd>The number of elements to copy. If this argument is omitted then ''size(vect) - start'' is assumed.</dd><br />
</dl><br />
<br />
'''Return value'''<br />
<br />
A new vector containing the specified range from the original vector, or ''nil''.<br />
<br />
'''Notes:'''<br />
<ol><br />
<li><br />
Omitting the ''vect'' and ''start'' arguments is not an error (possibly it should be) but the return value is ''nil''.<br />
</li><br />
<li><br />
A negative ''start'' argument '''is'' an error. This seems wrong. Perhaps the language designer could comment.<br />
</li><br />
<li><br />
A value of ''start'' greater than ''size(vect)'' causes an error. A value equal to ''size(vect)'' returns an empty vector.<br />
</li><br />
<li><br />
If the value of ''count'' is greater than ''size(vect) - start'' then it is ignored. That is, all elements from ''start'' to the end of ''vect'' are returned. A negative value of ''count'' causes an error.<br />
</ol><br />
<br />
Example :<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var FGRoot = getprop("/sim/fg-root");<br />
var filename = "/Aircraft";<br />
var path_files = directory(FGRoot ~ filename);<br />
<br />
foreach(var key; path_files) {<br />
print(key);<br />
}<br />
</syntaxhighlight><br />
returns : '''"." , ".." , "Generic", "Instruments", "Instruments-3d", "c172p", "ufo"'''<br />
<br />
<br />
With subvec():<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var FGRoot = getprop("/sim/fg-root");<br />
var filename = "/Aircraft";<br />
var path_files = subvec(directory(FGRoot ~ filename),2);<br />
<br />
foreach(var key; path_files) {<br />
print(key);<br />
}<br />
</syntaxhighlight><br />
returns : '''"Generic", "Instruments", "Instruments-3d", "c172p", "ufo"'''<br />
<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var FGRoot = getprop("/sim/fg-root");<br />
var filename = "/Aircraft";<br />
var path_files = subvec(directory(FGRoot ~ filename),3);<br />
<br />
foreach(var key; path_files) {<br />
print(key);<br />
}<br />
</syntaxhighlight><br />
returns : '''"Instruments", "Instruments-3d", "c172p", "ufo"'''<br />
<br />
== delete() ==<br />
<br />
<br />
== int() ==<br />
<br />
== num(str) ==<br />
Convert string to number.<br />
Returns nil if str is nil, empty string, string with no number.<br />
<br />
== streq() ==<br />
<br />
== cmp() ==<br />
<br />
== substr() ==<br />
<br />
== chr() ==<br />
<br />
== contains() ==<br />
<br />
== typeof() ==<br />
<br />
== ghosttype(ghost) ==<br />
Returns a string containing either a descriptive name as passed to ''naNewGhost'' or ''naNewGhost2'' in C/C++ while creating the ghost or a unique id (aka the pointer to the C/C++ naGhostType instance) if no name has been set.<br />
<br />
== compile() ==<br />
<br />
== call() ==<br />
<br />
== die() ==<br />
<br />
== sprintf() ==<br />
<br />
== caller() ==<br />
<br />
== closure() ==<br />
<br />
== find() ==<br />
<br />
== split() ==<br />
<br />
== rand() ==<br />
<br />
== bind() ==<br />
<br />
== sort() ==<br />
<br />
== id() ==<br />
<br />
= math =<br />
== Trigonometric_functions ==<br />
'''Caution''': All trigonometric functions works with [https://en.wikipedia.org/wiki/Radian Radian]-values - not with Degree!<br />
<br />
<u>To convert this</u>:<br><br />
radians = degree * math.pi / 180<br><br />
degree = radians * 180 / math.pi<br />
=== sin() ===<br />
=== cos() ===<br />
=== tan() ===<br />
=== asin() ===<br />
=== acos() ===<br />
=== atan2() ===<br />
== exp() ==<br />
== ln() ==<br />
== pow() ==<br />
== sqrt() ==<br />
== floor() ==<br />
Returns the value rounded downward<br />
<br />
Example:<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
math.floor(1.2); # returns 1<br />
math.floor(1.6); # returns 1<br />
</syntaxhighlight><br />
<br />
== ceil() ==<br />
Returns the value rounded upward<br />
<br />
Example:<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
math.ceil(1.2); # returns 2<br />
math.ceil(1.6); # returns 2<br />
</syntaxhighlight><br />
<br />
== fmod() ==<br />
A '''modulo'''-operator. The [https://en.wikipedia.org/wiki/Modulo_operation modulo]-operation finds the remainder of division of one number by another (sometimes called modulus).<br />
<br />
fmod(x , y) may be negative if x < 0, whereas mod() seems to guarantee that 0 ≤ mod(x,y) < y, according to tests made with x and y integers, y > 0, x positive or negative.<br />
<br />
== clamp() ==<br />
== periodic() ==<br />
== round() ==<br />
== pi ==<br />
== e ==<br />
<br />
= io =<br />
<br />
* SEEK_SET<br />
* SEEK_CUR<br />
* SEEK_END<br />
* stdin<br />
* stdout<br />
* stderr<br />
<br />
== stat() ==<br />
== directory() ==<br />
returns the files in a given directory<br />
<br />
e.g. chatter_list = directory( chatter_dir );<br />
<br />
Example : <br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var FGRoot = getprop("/sim/fg-root");<br />
var filename = "/Aircraft";<br />
var path_files = directory(FGRoot ~ filename);<br />
<br />
foreach(var key; path_files) {<br />
print(key);<br />
}<br />
</syntaxhighlight><br />
returns : <br />
'''"." , ".." , "Generic", "Instruments", "Instruments-3d", "c172p", "ufo"'''<br />
<br />
To delete the "." and ".." see the subvec() function.<br />
<br />
== open() ==<br />
== read() ==<br />
== readln() ==<br />
== seek() ==<br />
== tell() ==<br />
== write() ==<br />
== flush() ==<br />
== close() ==<br />
<br />
= utf8 =<br />
== chstr() ==<br />
== strc() ==<br />
== substr() ==<br />
== size() ==<br />
== validate() ==</div>Chris-barryhttps://wiki.flightgear.org/w/index.php?title=Nasal_library_functions&diff=92149Nasal library functions2016-02-01T02:47:13Z<p>Chris-barry: /* subvec() */ The previous description began with a statement that was incorrect and then gave no further description. The examples are trivial but that probably does not justify removing them.</p>
<hr />
<div>{{Nasal Navigation}}<br />
<br />
Please first see: http://plausible.org/nasal/lib.html<br />
<br />
== size() ==<br />
'''Usage:'''<br />
<br />
size(''object'');<br />
<br />
where ''object'' may be a ''string'', a ''vector'' or a ''hash''.<br />
<br />
'''Return value'''<br />
<br />
An intger equal to the number of characters in a ''string'' argument or the number of elements in a ''vector'' or ''hash''.<br />
<br />
If the argument is a non-string scalar then the error '''object has no size()''' will be generated.<br />
<br />
== keys() ==<br />
<br />
== append() ==<br />
<br />
== pop() ==<br />
<br />
== setsize() ==<br />
'''Usage:'''<br />
<br />
setsize(vect, new_size)<br />
<br />
where ''vect'' is an expression which evaluates to a vector and ''new_size'' is an expression that evaluates to a non-negative number.<br />
<br />
'''Action:'''<br />
<br />
Changes the number of elements in the vetor ''v'' to the value of s.<br />
<br />
'''Return value:'''<br />
<br />
The resized vector.<br />
<br />
'''Notes'''<br />
<br />
Elements that exist in both the original and the resized vector retain their values. When the vector is enlarged newly created elements are set to ''nil''. When the size is reduced the values of all elements beyond the new size are permanently lost.<br />
<br />
The ''new_size'' argument may be any non-negative number. Non-integer values are rounded down.<br />
<br />
The ''vect'' argument need not be a named variable. The expression:<br />
<br />
var v1 = setsize([], n);<br />
<br />
Is a convenient way to allocate an empty vector of a specific size.<br />
<br />
== subvec() ==<br />
<br />
Create a new vector comprising elements from a contiguous range of elements of an existing vector.<br />
'''Usage:'''<br />
<br />
subvec([''vect'', [''start'', [''count'']]])<br />
<br />
<dl><br />
<dt>''vect''</dt><br />
<dd>The original vector</dd><br />
<dt>''start''</dt><br />
<dd>The zero-based index in the original vector of the first element to be copied.</dd><br />
<dt>''count''</dt><br />
<dd>The number of elements to copy. If this argument is omitted then ''size(vect) - start'' is assumed.</dd><br />
</dl><br />
<br />
'''Return value'''<br />
<br />
A new vector containing the specified range from the original vector, or ''nil''.<br />
<br />
'''Notes:'''<br />
<ol><br />
<li><br />
Omitting the ''vect'' and ''start'' arguments is not an error (possibly it should be) but the return value is ''nil''.<br />
</li><br />
<li><br />
A negative ''start'' argument '''is'' an error. This seems wrong. Perhaps the language designer could comment.<br />
</li><br />
<li><br />
A value of ''start'' greater than ''size(vect)'' causes an error. A value equal to ''size(vect)'' returns an empty vector.<br />
</li><br />
<li><br />
If the value of ''count'' is greater than ''size(vect) - start'' then it is ignored. That is, all elements from ''start'' to the end of ''vect'' are returned. A negative value of ''count'' causes an error.<br />
</ol><br />
<br />
Example :<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var FGRoot = getprop("/sim/fg-root");<br />
var filename = "/Aircraft";<br />
var path_files = directory(FGRoot ~ filename);<br />
<br />
foreach(var key; path_files) {<br />
print(key);<br />
}<br />
</syntaxhighlight><br />
returns : '''"." , ".." , "Generic", "Instruments", "Instruments-3d", "c172p", "ufo"'''<br />
<br />
<br />
With subvec():<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var FGRoot = getprop("/sim/fg-root");<br />
var filename = "/Aircraft";<br />
var path_files = subvec(directory(FGRoot ~ filename),2);<br />
<br />
foreach(var key; path_files) {<br />
print(key);<br />
}<br />
</syntaxhighlight><br />
returns : '''"Generic", "Instruments", "Instruments-3d", "c172p", "ufo"'''<br />
<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var FGRoot = getprop("/sim/fg-root");<br />
var filename = "/Aircraft";<br />
var path_files = subvec(directory(FGRoot ~ filename),3);<br />
<br />
foreach(var key; path_files) {<br />
print(key);<br />
}<br />
</syntaxhighlight><br />
returns : '''"Instruments", "Instruments-3d", "c172p", "ufo"'''<br />
<br />
== delete() ==<br />
<br />
<br />
== int() ==<br />
<br />
== num(str) ==<br />
Convert string to number.<br />
Returns nil if str is nil, empty string, string with no number.<br />
<br />
== streq() ==<br />
<br />
== cmp() ==<br />
<br />
== substr() ==<br />
<br />
== chr() ==<br />
<br />
== contains() ==<br />
<br />
== typeof() ==<br />
<br />
== ghosttype(ghost) ==<br />
Returns a string containing either a descriptive name as passed to ''naNewGhost'' or ''naNewGhost2'' in C/C++ while creating the ghost or a unique id (aka the pointer to the C/C++ naGhostType instance) if no name has been set.<br />
<br />
== compile() ==<br />
<br />
== call() ==<br />
<br />
== die() ==<br />
<br />
== sprintf() ==<br />
<br />
== caller() ==<br />
<br />
== closure() ==<br />
<br />
== find() ==<br />
<br />
== split() ==<br />
<br />
== rand() ==<br />
<br />
== bind() ==<br />
<br />
== sort() ==<br />
<br />
== id() ==<br />
<br />
= math =<br />
== Trigonometric_functions ==<br />
'''Caution''': All trigonometric functions works with [https://en.wikipedia.org/wiki/Radian Radian]-values - not with Degree!<br />
<br />
<u>To convert this</u>:<br><br />
radians = degree * math.pi / 180<br><br />
degree = radians * 180 / math.pi<br />
=== sin() ===<br />
=== cos() ===<br />
=== tan() ===<br />
=== asin() ===<br />
=== acos() ===<br />
=== atan2() ===<br />
== exp() ==<br />
== ln() ==<br />
== pow() ==<br />
== sqrt() ==<br />
== floor() ==<br />
Returns the value rounded downward<br />
<br />
Example:<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
math.floor(1.2); # returns 1<br />
math.floor(1.6); # returns 1<br />
</syntaxhighlight><br />
<br />
== ceil() ==<br />
Returns the value rounded upward<br />
<br />
Example:<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
math.ceil(1.2); # returns 2<br />
math.ceil(1.6); # returns 2<br />
</syntaxhighlight><br />
<br />
== fmod() ==<br />
A '''modulo'''-operator. The [https://en.wikipedia.org/wiki/Modulo_operation modulo]-operation finds the remainder of division of one number by another (sometimes called modulus).<br />
<br />
fmod(x , y) may be negative if x < 0, whereas mod() seems to guarantee that 0 ≤ mod(x,y) < y, according to tests made with x and y integers, y > 0, x positive or negative.<br />
<br />
== clamp() ==<br />
== periodic() ==<br />
== round() ==<br />
== pi ==<br />
== e ==<br />
<br />
= io =<br />
<br />
* SEEK_SET<br />
* SEEK_CUR<br />
* SEEK_END<br />
* stdin<br />
* stdout<br />
* stderr<br />
<br />
== stat() ==<br />
== directory() ==<br />
returns the files in a given directory<br />
<br />
e.g. chatter_list = directory( chatter_dir );<br />
<br />
Example : <br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var FGRoot = getprop("/sim/fg-root");<br />
var filename = "/Aircraft";<br />
var path_files = directory(FGRoot ~ filename);<br />
<br />
foreach(var key; path_files) {<br />
print(key);<br />
}<br />
</syntaxhighlight><br />
returns : <br />
'''"." , ".." , "Generic", "Instruments", "Instruments-3d", "c172p", "ufo"'''<br />
<br />
To delete the "." and ".." see the subvec() function.<br />
<br />
== open() ==<br />
== read() ==<br />
== readln() ==<br />
== seek() ==<br />
== tell() ==<br />
== write() ==<br />
== flush() ==<br />
== close() ==<br />
<br />
= utf8 =<br />
== chstr() ==<br />
== strc() ==<br />
== substr() ==<br />
== size() ==<br />
== validate() ==</div>Chris-barryhttps://wiki.flightgear.org/w/index.php?title=Howto:Set_up_a_multiplayer_server&diff=92138Howto:Set up a multiplayer server2016-01-31T20:33:51Z<p>Chris-barry: One would not refer to a beautiful view about a sunset, or an unobstructed view about the sewage farm. The same applies to "overview".</p>
<hr />
<div>This page is dedicated to providing a short overview of installing the [[FlightGear Multiplayer Server]] ('fgms'). The reader is assumed to be reasonably familiar with working in a Unix/Linux shell environment.<br />
<br />
== Pre-Requisites ==<br />
* A computer running a variant of *nix to compile and host the server. Speed of the machine isn't of great consequence as the protocol is a multiplexer which doesn't require much processing grunt.<br />
** For specific documentation for setting up on FreeBSD see [[Howto:Set up a multiplayer server on FreeBSD]].<br />
* direct/physical or remote access to the server (i.e. SSH/telnet, a conventional web hosting package will usually '''not''' be sufficient!)-suitable hosting packages are: dedicated root servers, virtual private servers, shell servers - for a collection of '''free''' shell account providers that may be suitable for fgms, see [[Free Shell Providers]] (you may want to check this out if you are interested in running fgms but don't have hosting yet)<br />
* if the server is meant to be a public internet server: an internet connection, featuring sufficient upstream/downstream capabilities (see below for details concerning bandwidth requirements). <br />
* firewall policies will need to be set up to allow for incoming and outgoing UDP traffic for the corresponding ports, the same applies to the administration port (TCP)<br />
* permission to run unattended background processes (this may only be an issue with certain limited hosting packages)<br />
* a working GNU toolchain including gcc/g++ (compiler), make & cmake<br />
* fgms source code, currently version 0.10.23<br />
* about 5-10 MB of hard disk space (mainly required for building the binary)<br />
<br />
== Traffic & Bandwidth Considerations ==<br />
<br />
Note: Currently (May 2008), the server code basically boils down to a packet multiplexer (i.e. most data is -unconditionally- transmitted to all 'active' clients), which may thus create considerable amounts of traffic; this ought to be taken into consideration due to bandwidth limitations in most hosting packages (i.e. '''fgms may create considerable amounts of traffic!'''). For basic calculations: inbound traffic is 25 Kilobit per second while outbound is 25 Kbits per second for each plane/client that can 'see' another. <br />
<br />
By default, assuming a 10hz update interval, each active fgfs client will currently cause I/O traffic of approximately 5 kbytes/sec (one update consuming ~500 bytes) [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg16016.html].<br />
<br />
As client updates have to be propagated to all other active clients by the server, this number has to be multiplied by the number of active clients -1 (i.e. clients within a configurable range, minus the originating client). <br />
In addition, the fgms system allows for traffic updates to be sort of 'mirrored' on (relayed to) other configurable multiplayer/relay servers. <br />
<br />
This feature makes it possible for users/clients to use an arbitrary server (with acceptable latency), but still see clients/vehicles connected to different servers. Thus, such relay servers may additionally increase inbound/outbound traffic considerably as all traffic is mirrored/propagated to such relays.<br />
<br />
Having more servers should actually decrease the load on each server in high load situations, i.e. when most of the clients are within range of each other. See this<br />
[http://www.gidenstam.org/FlightGear/fgms/fgms_bandwidth_estimates.txt brief note on the theoretical bandwidth behaviour of fgms.]<br />
<br />
=== Facts ===<br />
In March 2008, the main fgms multiplayer server (pigeond.net) was reported to consume approximately 15 gb of bandwidth per '''day''', with an average throughput of 200 kB/sec and peak loads of up to ~ 650 kB/sec [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg16016.html].<br />
<br />
During the same month (the much less used but interconnected) mpserver06.flightgear.org had on average 742 MB incoming and 688 MB outgoing traffic per day (i.e. 72 kbit/sec respective 66 kbit/sec on average).<br />
<br />
In September 2009, mpserver 05 had a massive peak bandwidth of 1.0 MB/sec. Average bandwidth consumed was about 9 GB of bandwidth per day. The average bandwidth usage per day is climbing due to more users moving from 02 to 05.<br />
<br />
In July 2013, mpserver01 load was reported averaging at 10 MBit/sec<br />
<br />
=== Reducing bandwidth requirements ===<br />
Total network traffic is mainly determined by the number of active clients that 'see eachother' and configured mirrors. <br />
If traffic considerations are relevant, the following options exist to reduce overall server/network load:<br />
<br />
* configure a relatively low "server.out_of_reach" value, so that clients outside a certain range are not provided with updates (usually about 100 nm on the main server network)<br />
* for virtual gatherings (i.e. fly-ins), have clients use airports and places that do not have lots of other traffic (i.e. in other words, avoid places like standard airports such as KSFO)<br />
* avoid the use of unnecessary relay servers<br />
* if you are not interested in your server being publicly available, only share its address with your friends privately<br />
* for local testing/development purposes, you may want to run only a private fgms session, that may be specific to your LAN or even computer.<br />
<br />
== Getting & Building fgms ==<br />
* You will need the build tools cmake and make, and also g++ to compile the fgms application. These can usually be found in the package manager for most the common Linux distributions. You will also need the git client to fetch the source code from the repository, if you plan to download it from the command line interface (see below).<br />
* Once the build tools are installed on your machine, create a directory to hold the source code. This could be named anything, such as fgms. Create it in your user home directory. Note that this WILL NOT be the directory where the program will be compiled.<br />
* Now 'cd' into the directory you just made, where you will run the command to fetch the source code from the git repository (see below). <br />
* To download the latest stable version via HTTP, you can use direct your browse to the URL https://gitlab.com/fgms/fgms-0-x. Download and unzip the source code, and place it in the directory you created above.<br />
* To download a file directly to your server from an ssh session, you can use git tools with the following command:<br />
:<syntaxhighlight lang="bash">git clone https://gitlab.com/fgms/fgms-0-x.git</syntaxhighlight><br />
<br />
== Compiling FGMS ==<br />
<br />
For FreeBSD-specific instructions, please see [[Howto:Set up a multiplayer server on FreeBSD]]<br />
<br />
NOTE: In general, on any current machine this process should not take longer than about 60 seconds.<br />
<br />
* Once you have the source code, 'cd' into the ~/fgms/fgms-0-x/ directory and note the presence of the CMakeLists.txt file and the README.cmake file. Open the README.cmake file and take a minute to read it over. Also, note the path to the CMakeLists.txt file, as you will need this in the following steps.<br />
<br />
* Now create a build-fgms directory in your home directory, and 'cd' into it. From inside the ~/build-fgms/ directory, run the cmake command using the path to the CMakeLists.txt as an argument. For example: cmake /home/<user_name>/fgms/fgms-0-x/<br />
<br />
* Once the build finishes, you can either run the "cmake --build ..." command as shown in the README.cmake file, or you can simply use "make" to build the program.<br />
<br />
* Once the compilation process finishes, you need to install the program using "make install" (as user), or you can also install as root.<br />
<br />
* Once the program has been installed, you need to copy the fgms_example.conf file from the /fgms/fgms-0-x/src/server directory, into the build-fgms directory. To do this from inside the /fgms/fgms-0-x/src/server directory, you can use this command: cp ./fgms_example.conf ~/build-fgms/<br />
<br />
* Now 'cd' into the build-fgms directory, and rename the file you just copied as "fgms.conf" so that fgms can find the proper configuration.<br />
<br />
== Setting up the config file ==<br />
<br />
At this point you should have a working 'fgms' binary in the build-fgms directory. If the server will be offline or for private use (i.e. LAN-only, please comment out the relay servers section. This will save bandwidth from the server being consumed.<br />
<br />
* Edit the fgms.conf file according to the instructions found elsewhere on this page, then save and close the file.<br />
<br />
{{cquote|As long as you are not absolutly sure what you are doing you should:<br />
- disable tracking<br />
- disable HUB setting<ref>{{cite web |url=http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg40454.html|title=<nowiki>Re: [Flightgear-devel] New FlightGear Multiplayer Server</nowiki>|author=Oliver Schröder|date=Wed, 10 Jul 2013 13:53:55 -0700}}</ref>|Oliver Schröder}}<br />
<br />
<br />
{{cquote|fgms will ignore traffic comming from unknown relays and since the multiplayer network is a star topology you should list only mpserver01<br />
as your only relay. Currently mpserver01 is the only HUB, Although multiple HUBs should work I have not tested a multi HUB environment yet.<br />
And for those interrested: Current traffic load on mpserver01 is around 10 MBit/s<ref>{{cite web |url=http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg40454.html|title=<nowiki>Re: [Flightgear-devel] New FlightGear Multiplayer Server</nowiki>|author=Oliver Schröder|date=Wed, 10 Jul 2013 13:53:55 -0700}}</ref>|Oliver Schröder}}<br />
<br />
{{cquote|your fgms.conf should look like:<br />
<pre><br />
# basic setting<br />
server.name = mpserver02<br />
server.port = 5000<br />
<br />
# you can telnet to this port with this username/password<br />
# and see statistics (nice cisco like CLI)<br />
server.admin_port = 6002<br />
server.admin_user = fred<br />
server.admin_pass = fred<br />
<br />
server.admin_enable = fred<br />
<br />
# mpserver01 does this<br />
server.tracked = false<br />
<br />
# mpserver01 is hub<br />
server.is_hub = false</pre><ref>{{cite web |url=http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg40454.html|title=<nowiki>Re: [Flightgear-devel] New FlightGear Multiplayer Server</nowiki>|author=Oliver Schröder|date=Wed, 10 Jul 2013 13:53:55 -0700}}</ref>|Oliver Schröder}}<br />
<br />
{{cquote|<pre># don't set this too high<br />
server.out_of_reach = 100<br />
<br />
# your only relay should be mpserver01<br />
relay.host = mpserver01.flightgear.org<br />
relay.port = 5000<br />
<br />
# you don't need a crossfeed, it's only interresting for fgms-developers<br />
# crossfeed.host = foo.example.com<br />
# crossfeed.port = 5002<br />
<br />
# you can add static entries of IPs which get blocked,<br />
# but it's generally not needed and you can add them via<br />
# the admin CLI<br />
# blacklist = 123.123.123.123</pre><ref>{{cite web |url=http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg40454.html|title=<nowiki>Re: [Flightgear-devel] New FlightGear Multiplayer Server</nowiki>|author=Oliver Schröder|date=Wed, 10 Jul 2013 13:53:55 -0700}}</ref>|Oliver Schröder}}<br />
<br />
== Running FGMS for the first time ==<br />
<br />
In addition to its configuration file, FGMS supports a number of configuration parameters that can be passed at startup (and that will by default override any configuration file settings), to get a summary of supported parameters, you may want to run:<br />
$ ./fgms --help<br />
<br />
Which should present you with the following output:<br />
<br />
<pre><br />
options are:<br />
-h print this help screen<br />
-a PORT listen to PORT for telnet<br />
-c config read 'config' as configuration file<br />
-p PORT listen to PORT<br />
-t TTL Time a client is active while not sending packets<br />
-o OOR nautical miles two players must be apart to be out of reach<br />
-l LOGFILE Log to LOGFILE<br />
-v LEVEL verbosity (loglevel) in range 1 (few) and 5 (much)<br />
-d do _not_ run as a daemon (stay in foreground)<br />
-D do run as a daemon<br />
<br />
the default is to run as a daemon, which can be overridden in the<br />
config file.<br />
commandline parameters always override config file options<br />
</pre><br />
<br />
After having finished the fgms configuration, you can try running fgms and start up fgfs to use the new server.<br />
=== Public Server ===<br />
If you'd like to make it a public server, you can simply use your external (public) IP address to set up the multiplayer in fgfs.<br />
<br />
For others to know about your public server you should notify the developers of the existence of your server by posting a message to the [[Mailing list|developers mailing list]].<br />
<br />
Add your server to this list: http://wiki.flightgear.org/Howto:Multiplayer#Servers<br />
<br />
== Related content ==<br />
* [http://fgms.freeflightsim.org/ Website: fgms.freeflightsim.org]<br />
* [[Howto: Multiplayer|Multiplayer howto]]<br />
* [[MPmap]]<br />
<br />
<references/><br />
<br />
[[Category:Howto]]<br />
[[Category:Multiplayer]]<br />
<br />
[[fr:Installer un serveur multijoueur]]</div>Chris-barryhttps://wiki.flightgear.org/w/index.php?title=Nasal_Conditionals&diff=91978Nasal Conditionals2016-01-28T15:36:36Z<p>Chris-barry: /* Conditionals */</p>
<hr />
<div>{{Template:Nasal Navigation}}<br />
<br />
<br />
Sometimes you may only want to execute certain portions of your code, depending on conditions. This can be accomplished in several ways. One of the most straightforward ways being an '''if''' expression, which has the form:<br />
<br />
<syntaxhighlight lang="nasal"><br />
var condition=1; # this evaluates to boolean true<br />
if (condition) {<br />
# true block, will be executed if condition is true<br />
} else {<br />
# false block, will be executed if condition is false<br />
}<br />
</syntaxhighlight><br />
<br />
To negate the whole thing, use the '''!''' operator:<br />
<br />
<syntaxhighlight lang="nasal"><br />
var condition=1; # boolean true<br />
if (!condition) {<br />
# false block, will be executed if condition is true<br />
} else {<br />
# true block, will be executed if condition is false<br />
}<br />
</syntaxhighlight><br />
<br />
In both examples, the '''condition''' variable is just a placeholder, it could be a variable named '''condition''', but it could also be a more complex expression, such as a '''getprop''' call for example:<br />
<br />
<syntaxhighlight lang="nasal"><br />
var condition = getprop("/sim/signals/freeze");<br />
<br />
if (condition) {<br />
# true block, will be executed if condition is true<br />
} else {<br />
# false block, will be executed if condition is false<br />
}<br />
</syntaxhighlight><br />
<br />
The same thing could be accomplished by using a call to getprop() as part of the condition:<br />
<br />
<br />
<syntaxhighlight lang="nasal"><br />
if (var condition = getprop("/sim/signals/freeze")) {<br />
# true block, will be executed if condition is true<br />
} else {<br />
# false block, will be executed if condition is false<br />
}<br />
</syntaxhighlight><br />
<br />
Note that you are never using the condition variable here, so you could also omit the whole declaration and directly use the getprop call:<br />
<br />
<br />
<syntaxhighlight lang="nasal"><br />
if (getprop("/sim/signals/freeze")) {<br />
# true block, will be executed if condition is true<br />
} else {<br />
# false block, will be executed if condition is false<br />
}<br />
</syntaxhighlight><br />
<br />
The condition can also be arbitrarily complex, in that it can be made up of other conditions, that may be nested using these boolean operators:<br />
* '''!''' (not)<br />
* '''and'''<br />
* '''or'''<br />
<br />
<syntaxhighlight lang="nasal"><br />
var condition = (1==1 and 2==2 and 3==3) or (4!=5 and !0);<br />
if (condition) {<br />
# true block, will be executed if condition is true<br />
} else {<br />
# false block, will be executed if condition is false<br />
}<br />
</syntaxhighlight><br />
<br />
<br />
== Conditionals ==<br />
<br />
Nasal has no "statements", which means that any expression can appear in any context. This means that you can use an if/else clause to do what the ?: (ternary operator) does in C. <br />
The last semicolon in a code block is optional, to make this prettier. First, a completely conventional implementation of the '''abs''' function:<br />
<br />
<syntaxhighlight lang="nasal"><br />
var abs = func(n) { <br />
if(n<0) <br />
{ return -n }<br />
else <br />
{ return n }<br />
}<br />
</syntaxhighlight><br />
<br />
This form would work as it is in "C" and, with minor adjustments for syntax, in many other languages. However, the following form would not work in "C":<br />
<br />
<syntaxhighlight lang="nasal"><br />
var abs = func(n) { <br />
return if (n<0) <br />
{ -n }<br />
else <br />
{ n }<br />
}<br />
</syntaxhighlight><br />
<br />
In this form the '''if''' clause is clearly an expression that yields a value. That value is the result of the last expression executed within the '''if''' clause.<br />
<br />
And for those who don't like typing, the ternary operator works like you expect:<br />
<br />
<syntaxhighlight lang="nasal"><br />
var abs = func(n) { n < 0 ? -n : n }<br />
</syntaxhighlight><br />
<br />
This also illustrates that a function will return a value even when there is no '''return''' clause. The value returned is the value of the last expression evaluated within the function.<br />
<br />
In addition, Nasal supports braceless blocks, like they're known from C/C++ and other languages. Basically, the block ends with a semicolon, instead of being encapsulated inside a <tt>{</tt>/<tt>}</tt> pair. This means basically that the first statement (expression) after a conditional is evaluated if the condition is true, otherwise it will be ignored:<br />
<br />
<syntaxhighlight lang="nasal"><br />
var foo=1;<br />
if (foo)<br />
print("1\n");<br />
else<br />
print("0\n");<br />
print("this is printed regardless\n")<br />
</syntaxhighlight><br />
<br />
<br />
Instead of a switch statement one can use<br />
<br />
<syntaxhighlight lang="nasal"><br />
if (1==2) {<br />
print("wrong");<br />
} else if (1==3) { # NOTE the space between else and if<br />
print("wronger");<br />
} else {<br />
print("don't know");<br />
}<br />
</syntaxhighlight><br />
which produces the expected output of <code>don't know</code>.<br />
<br />
Instead of "else if", you can also use the shorter equivalent form "elsif":<br />
<br />
<syntaxhighlight lang="nasal"><br />
if (1==2) {<br />
print("wrong");<br />
} elsif (1==3) { <br />
print("wronger");<br />
} else {<br />
print("don't know");<br />
}<br />
</syntaxhighlight><br />
<br />
<br />
The <tt>nil</tt> logic is actually quite logical, let's just restate the obvious:<br />
<br />
<syntaxhighlight lang="nasal"><br />
if (nil) {<br />
print("This should never be printed");<br />
} else {<br />
print("This will be printed, because nil is always false"); <br />
};<br />
</syntaxhighlight><br />
<br />
<br />
<br />
Nasal's binary boolean operators are "and" and "or", unlike C. Unary not is still "!" however. They short-circuit like you expect:<br />
<br />
<syntaxhighlight lang="nasal"><br />
var toggle = 0;<br />
var a = nil;<br />
if (a != nil and a.field == 42) {<br />
toggle = !toggle; # doesn't crash when a is nil<br />
}<br />
</syntaxhighlight><br />
<br />
Note that you should always surround multiple conditions within outer parentheses:<br />
<br />
<syntaxhighlight lang="nasal"><br />
if (1) do_something();<br />
if (1 and 1) do_something();<br />
if ( (1) and (1) ) do_something();<br />
if ( (1) or (0) ) do_something();<br />
</syntaxhighlight><br />
<br />
Nasal's binary boolean operators can also be used to default expressions to certain values:<br />
<br />
<syntaxhighlight lang="nasal"><br />
var altitude = getprop("/position/altitude-ft") or 0.00;<br />
</syntaxhighlight><br />
<br />
Basically this will first execute the getprop() call and if it doesn't return "true" (i.e. if it isn't zero or nil), it will instead use 0.00 as the value for the altitude variable.<br />
<br />
Regarding boolean operators like and/or: This is working because they "short circuit", i.e. in an OR comparison, the remaining checks are NEVER done IF any single of the previous checks is true (1), because that'll suffice to satisfy the OR expression (i.e. knowing that a single check evaluates to true).<br />
<br />
Similarly, an "and" expression will inevitably need to do ALL "and" checks in order to evaluate the whole expression.<br />
<br />
At first, this may seem pretty complex and counter-intuitive - but it's important to keep this technique in mind, especially for variables that are later on used in calcuations:<br />
<br />
<syntaxhighlight lang="nasal"><br />
var x = getprop("/velocities/airspeed-kts") or 0.00; # to ensure that x is always valid number<br />
var foo = 10*3.1*x; # ... for this computation<br />
</syntaxhighlight><br />
<br />
So this is to ensure that invalid property tree state does not mess up the calculations done in Nasal by defaulting x to 0.00, i.e. a valid numeric value.<br />
<br />
Bottom line being, using "or" to default a variable to a given value is a short and succinct way to avoid otherwise elaborate checks, e.g. compare:<br />
<br />
<syntaxhighlight lang="nasal"><br />
var altitude_ft = getprop("/position/altitude-ft");<br />
if (altitude_ft == nil) {<br />
altitude_ft = 0.0;<br />
}<br />
</syntaxhighlight><br />
<br />
versus:<br />
<br />
<syntaxhighlight lang="nasal"><br />
var altitude_ft = getprop("/position/altitude-ft") or 0.00;<br />
</syntaxhighlight><br />
<br />
Basically: whenever you read important state from the property tree that you'll use in calculations, it's a good practice to default the value to some sane value.<br />
<br />
But this technique isn't really specific to getprop (or any other library call).<br />
<br />
Nasal is a language that has no statements, it's all about EXPRESSIONS. So you can put things in pretty much arbitrary places.<br />
<br />
<syntaxhighlight lang="nasal"><br />
var do_something = func return 0;<br />
if (a==1) {<br />
do_something() or print("failed");<br />
}<br />
<br />
var do_something = func return 0;<br />
( (a==1) and do_something() ) or print("failed");<br />
</syntaxhighlight><br />
<br />
In a boolean comparison, 1 always means "true" while 0 always means "false". For instance, ANY comparison with if x ==1 can be abbreviated to if (x), because the ==1 check is implictly done:<br />
<br />
<syntaxhighlight lang="nasal"><br />
var do_something = func return 0;<br />
( a and do_something() ) or print("failed");<br />
</syntaxhighlight><br />
<br />
== Using Hashs to map keys to functions ==<br />
<br />
You can easily reduce the complexity of huge conditional (IF) statements, such as this one:<br />
<br />
<syntaxhighlight lang="nasal"><br />
if (a==1) function_a();<br />
else<br />
if (a==2) function_b();<br />
else<br />
if (a==3) function_c();<br />
else<br />
if (a==4) function_d();<br />
else<br />
if (a==5) function_e();<br />
</syntaxhighlight><br />
<br />
.. just by using the variable as a key (index) into a hash, so that you can directly call the corresponding function:<br />
<br />
<syntaxhighlight lang="nasal"><br />
var mapping = {1:function_a, 2:function_b, 3:function_c, 4:function_d,5:function_e};<br />
mapping[a] ();<br />
</syntaxhighlight><br />
<br />
This initializes first a hash map of values and maps a function "pointer" to each value, so that accessing mapping[x] will return the function pointer for the key "x".<br />
<br />
Next, you can actually call the function by appending a list of function arguments (empty parentheses for no args) to the hash lookup.<br />
<br />
Using this technique, you can reduce the complexity of huge conditional blocks. For example, consider this extract from weather_tile_management.nas:<br />
<br />
<syntaxhighlight lang="nasal"><br />
if (code == "altocumulus_sky"){weather_tiles.set_altocumulus_tile();}<br />
else if (code == "broken_layers") {weather_tiles.set_broken_layers_tile();}<br />
else if (code == "stratus") {weather_tiles.set_overcast_stratus_tile();}<br />
else if (code == "cumulus_sky") {weather_tiles.set_fair_weather_tile();}<br />
else if (code == "gliders_sky") {weather_tiles.set_gliders_sky_tile();}<br />
else if (code == "blue_thermals") {weather_tiles.set_blue_thermals_tile();}<br />
else if (code == "summer_rain") {weather_tiles.set_summer_rain_tile();}<br />
else if (code == "high_pressure_core") {weather_tiles.set_high_pressure_core_tile();}<br />
else if (code == "high_pressure") {weather_tiles.set_high_pressure_tile();}<br />
else if (code == "high_pressure_border") {weather_tiles.set_high_pressure_border_tile();}<br />
else if (code == "low_pressure_border") {weather_tiles.set_low_pressure_border_tile();}<br />
else if (code == "low_pressure") {weather_tiles.set_low_pressure_tile();}<br />
else if (code == "low_pressure_core") {weather_tiles.set_low_pressure_core_tile();}<br />
else if (code == "cold_sector") {weather_tiles.set_cold_sector_tile();}<br />
else if (code == "warm_sector") {weather_tiles.set_warm_sector_tile();}<br />
else if (code == "tropical_weather") {weather_tiles.set_tropical_weather_tile();}<br />
else if (code == "test") {weather_tiles.set_4_8_stratus_tile();}<br />
else ...<br />
</syntaxhighlight><br />
<br />
While this is not a very complex or huge block of code, it is an excellent example for very good naming conventions used already, because the consistency of naming variables and functions can pay off easily here, with just some very small changes, you can already reduce the whole thing to a hash lookup like this:<br />
<br />
<syntaxhighlight lang="nasal"><br />
weather_tiles["set_"~code~"_tile"](); # naming convention<br />
</syntaxhighlight><br />
<br />
This would dynamically concatenate a key consisting of "set_" + code + "_title" into the hash named weather_tiles, and then call the function that is returned from the hash lookup.<br />
<br />
So for this to work you only need to enforce consistency when naming your functions (i.e. this would of course CURRENTLY fail when the variable code contains "test" because there is no such hash member (it's "4_8_stratus" instead).<br />
<br />
The same applies to cumulus sky (fair weather), stratus/overcast stratus.<br />
<br />
But these are very simple changes to do (just renaming these functions to match the existing conventions). When you do that, you can easily replace such huge IF statements and replace them with a single hash lookup and function call:<br />
<br />
<syntaxhighlight lang="nasal"><br />
hash[key] (arguments...);<br />
</syntaxhighlight><br />
<br />
For example, consider:<br />
<br />
<syntaxhighlight lang="nasal"><br />
var makeFuncString = func(c) return tolower("set_"~c~"_tile");<br />
var isFunc = func(f) typeof(f)=='func';<br />
var hasMethod = func(h,m) contains(h,m) and isFunc;<br />
var callIfAvailable = func(hash, method, unavailable=func{} ) {<br />
var c=hasMethod(hash,makeFuncString(m) ) or unavailable();<br />
hash[makeFuncString(m)] ();<br />
}<br />
callIfAvailable( weather_tiles,code, func {die("key not found in hash or not a func");} );<br />
</syntaxhighlight></div>Chris-barryhttps://wiki.flightgear.org/w/index.php?title=Nasal_Conditionals&diff=91927Nasal Conditionals2016-01-27T20:24:09Z<p>Chris-barry: If I have undestood correctly then the example given did not illustrate the feature it was intended to, that is that the 'if' clause is an expression that reurns a value.</p>
<hr />
<div>{{Template:Nasal Navigation}}<br />
<br />
<br />
Sometimes you may only want to execute certain portions of your code, depending on conditions. This can be accomplished in several ways. One of the most straightforward ways being an '''if''' expression, which has the form:<br />
<br />
<syntaxhighlight lang="nasal"><br />
var condition=1; # this evaluates to boolean true<br />
if (condition) {<br />
# true block, will be executed if condition is true<br />
} else {<br />
# false block, will be executed if condition is false<br />
}<br />
</syntaxhighlight><br />
<br />
To negate the whole thing, use the '''!''' operator:<br />
<br />
<syntaxhighlight lang="nasal"><br />
var condition=1; # boolean true<br />
if (!condition) {<br />
# false block, will be executed if condition is true<br />
} else {<br />
# true block, will be executed if condition is false<br />
}<br />
</syntaxhighlight><br />
<br />
In both examples, the '''condition''' variable is just a placeholder, it could be a variable named '''condition''', but it could also be a more complex expression, such as a '''getprop''' call for example:<br />
<br />
<syntaxhighlight lang="nasal"><br />
var condition = getprop("/sim/signals/freeze");<br />
<br />
if (condition) {<br />
# true block, will be executed if condition is true<br />
} else {<br />
# false block, will be executed if condition is false<br />
}<br />
</syntaxhighlight><br />
<br />
The same thing could be accomplished by using a call to getprop() as part of the condition:<br />
<br />
<br />
<syntaxhighlight lang="nasal"><br />
if (var condition = getprop("/sim/signals/freeze")) {<br />
# true block, will be executed if condition is true<br />
} else {<br />
# false block, will be executed if condition is false<br />
}<br />
</syntaxhighlight><br />
<br />
Note that you are never using the condition variable here, so you could also omit the whole declaration and directly use the getprop call:<br />
<br />
<br />
<syntaxhighlight lang="nasal"><br />
if (getprop("/sim/signals/freeze")) {<br />
# true block, will be executed if condition is true<br />
} else {<br />
# false block, will be executed if condition is false<br />
}<br />
</syntaxhighlight><br />
<br />
The condition can also be arbitrarily complex, in that it can be made up of other conditions, that may be nested using these boolean operators:<br />
* '''!''' (not)<br />
* '''and'''<br />
* '''or'''<br />
<br />
<syntaxhighlight lang="nasal"><br />
var condition = (1==1 and 2==2 and 3==3) or (4!=5 and !0);<br />
if (condition) {<br />
# true block, will be executed if condition is true<br />
} else {<br />
# false block, will be executed if condition is false<br />
}<br />
</syntaxhighlight><br />
<br />
<br />
== Conditionals ==<br />
<br />
Nasal has no "statements", which means that any expression can appear in any context. This means that you can use an if/else clause to do what the ?: (ternary operator) does in C. <br />
The last semicolon in a code block is optional, to make this prettier. First, a completely conventional implementation of the '''abs''' function:<br />
<br />
<syntaxhighlight lang="nasal"><br />
var abs = func(n) { <br />
if(n<0) <br />
{ return -n }<br />
else <br />
{ return n }<br />
}<br />
</syntaxhighlight><br />
<br />
This form would work as it is in "C" and, with minor adjustments for syntax, in many other languages. However, te following form would not work in "C":<br />
<br />
<syntaxhighlight lang="nasal"><br />
var abs = func(n) { <br />
return if (n<0) <br />
{ -n }<br />
else <br />
{ n }<br />
}<br />
</syntaxhighlight><br />
<br />
In this form the '''if''' clause is clearly an expression that yields a value. That value is the result of the last expression executed within the '''if''' clause.<br />
<br />
And for those who don't like typing, the ternary operator works like you expect:<br />
<br />
<syntaxhighlight lang="nasal"><br />
var abs = func(n) { n < 0 ? -n : n }<br />
</syntaxhighlight><br />
<br />
This also illustrates that a function will return a value even when there is no '''return''' clause. The value returned is the value of the last expression evaluated within the function.<br />
<br />
In addition, Nasal supports braceless blocks, like they're known from C/C++ and other languages. Basically, the block ends with a semicolon, instead of being encapsulated inside a <tt>{</tt>/<tt>}</tt> pair. This means basically that the first statement (expression) after a conditional is evaluated if the condition is true, otherwise it will be ignored:<br />
<br />
<syntaxhighlight lang="nasal"><br />
var foo=1;<br />
if (foo)<br />
print("1\n");<br />
else<br />
print("0\n");<br />
print("this is printed regardless\n")<br />
</syntaxhighlight><br />
<br />
<br />
Instead of a switch statement one can use<br />
<br />
<syntaxhighlight lang="nasal"><br />
if (1==2) {<br />
print("wrong");<br />
} else if (1==3) { # NOTE the space between else and if<br />
print("wronger");<br />
} else {<br />
print("don't know");<br />
}<br />
</syntaxhighlight><br />
which produces the expected output of <code>don't know</code>.<br />
<br />
Instead of "else if", you can also use the shorter equivalent form "elsif":<br />
<br />
<syntaxhighlight lang="nasal"><br />
if (1==2) {<br />
print("wrong");<br />
} elsif (1==3) { <br />
print("wronger");<br />
} else {<br />
print("don't know");<br />
}<br />
</syntaxhighlight><br />
<br />
<br />
The <tt>nil</tt> logic is actually quite logical, let's just restate the obvious:<br />
<br />
<syntaxhighlight lang="nasal"><br />
if (nil) {<br />
print("This should never be printed");<br />
} else {<br />
print("This will be printed, because nil is always false"); <br />
};<br />
</syntaxhighlight><br />
<br />
<br />
<br />
Nasal's binary boolean operators are "and" and "or", unlike C. Unary not is still "!" however. They short-circuit like you expect:<br />
<br />
<syntaxhighlight lang="nasal"><br />
var toggle = 0;<br />
var a = nil;<br />
if (a != nil and a.field == 42) {<br />
toggle = !toggle; # doesn't crash when a is nil<br />
}<br />
</syntaxhighlight><br />
<br />
Note that you should always surround multiple conditions within outer parentheses:<br />
<br />
<syntaxhighlight lang="nasal"><br />
if (1) do_something();<br />
if (1 and 1) do_something();<br />
if ( (1) and (1) ) do_something();<br />
if ( (1) or (0) ) do_something();<br />
</syntaxhighlight><br />
<br />
Nasal's binary boolean operators can also be used to default expressions to certain values:<br />
<br />
<syntaxhighlight lang="nasal"><br />
var altitude = getprop("/position/altitude-ft") or 0.00;<br />
</syntaxhighlight><br />
<br />
Basically this will first execute the getprop() call and if it doesn't return "true" (i.e. if it isn't zero or nil), it will instead use 0.00 as the value for the altitude variable.<br />
<br />
Regarding boolean operators like and/or: This is working because they "short circuit", i.e. in an OR comparison, the remaining checks are NEVER done IF any single of the previous checks is true (1), because that'll suffice to satisfy the OR expression (i.e. knowing that a single check evaluates to true).<br />
<br />
Similarly, an "and" expression will inevitably need to do ALL "and" checks in order to evaluate the whole expression.<br />
<br />
At first, this may seem pretty complex and counter-intuitive - but it's important to keep this technique in mind, especially for variables that are later on used in calcuations:<br />
<br />
<syntaxhighlight lang="nasal"><br />
var x = getprop("/velocities/airspeed-kts") or 0.00; # to ensure that x is always valid number<br />
var foo = 10*3.1*x; # ... for this computation<br />
</syntaxhighlight><br />
<br />
So this is to ensure that invalid property tree state does not mess up the calculations done in Nasal by defaulting x to 0.00, i.e. a valid numeric value.<br />
<br />
Bottom line being, using "or" to default a variable to a given value is a short and succinct way to avoid otherwise elaborate checks, e.g. compare:<br />
<br />
<syntaxhighlight lang="nasal"><br />
var altitude_ft = getprop("/position/altitude-ft");<br />
if (altitude_ft == nil) {<br />
altitude_ft = 0.0;<br />
}<br />
</syntaxhighlight><br />
<br />
versus:<br />
<br />
<syntaxhighlight lang="nasal"><br />
var altitude_ft = getprop("/position/altitude-ft") or 0.00;<br />
</syntaxhighlight><br />
<br />
Basically: whenever you read important state from the property tree that you'll use in calculations, it's a good practice to default the value to some sane value.<br />
<br />
But this technique isn't really specific to getprop (or any other library call).<br />
<br />
Nasal is a language that has no statements, it's all about EXPRESSIONS. So you can put things in pretty much arbitrary places.<br />
<br />
<syntaxhighlight lang="nasal"><br />
var do_something = func return 0;<br />
if (a==1) {<br />
do_something() or print("failed");<br />
}<br />
<br />
var do_something = func return 0;<br />
( (a==1) and do_something() ) or print("failed");<br />
</syntaxhighlight><br />
<br />
In a boolean comparison, 1 always means "true" while 0 always means "false". For instance, ANY comparison with if x ==1 can be abbreviated to if (x), because the ==1 check is implictly done:<br />
<br />
<syntaxhighlight lang="nasal"><br />
var do_something = func return 0;<br />
( a and do_something() ) or print("failed");<br />
</syntaxhighlight><br />
<br />
== Using Hashs to map keys to functions ==<br />
<br />
You can easily reduce the complexity of huge conditional (IF) statements, such as this one:<br />
<br />
<syntaxhighlight lang="nasal"><br />
if (a==1) function_a();<br />
else<br />
if (a==2) function_b();<br />
else<br />
if (a==3) function_c();<br />
else<br />
if (a==4) function_d();<br />
else<br />
if (a==5) function_e();<br />
</syntaxhighlight><br />
<br />
.. just by using the variable as a key (index) into a hash, so that you can directly call the corresponding function:<br />
<br />
<syntaxhighlight lang="nasal"><br />
var mapping = {1:function_a, 2:function_b, 3:function_c, 4:function_d,5:function_e};<br />
mapping[a] ();<br />
</syntaxhighlight><br />
<br />
This initializes first a hash map of values and maps a function "pointer" to each value, so that accessing mapping[x] will return the function pointer for the key "x".<br />
<br />
Next, you can actually call the function by appending a list of function arguments (empty parentheses for no args) to the hash lookup.<br />
<br />
Using this technique, you can reduce the complexity of huge conditional blocks. For example, consider this extract from weather_tile_management.nas:<br />
<br />
<syntaxhighlight lang="nasal"><br />
if (code == "altocumulus_sky"){weather_tiles.set_altocumulus_tile();}<br />
else if (code == "broken_layers") {weather_tiles.set_broken_layers_tile();}<br />
else if (code == "stratus") {weather_tiles.set_overcast_stratus_tile();}<br />
else if (code == "cumulus_sky") {weather_tiles.set_fair_weather_tile();}<br />
else if (code == "gliders_sky") {weather_tiles.set_gliders_sky_tile();}<br />
else if (code == "blue_thermals") {weather_tiles.set_blue_thermals_tile();}<br />
else if (code == "summer_rain") {weather_tiles.set_summer_rain_tile();}<br />
else if (code == "high_pressure_core") {weather_tiles.set_high_pressure_core_tile();}<br />
else if (code == "high_pressure") {weather_tiles.set_high_pressure_tile();}<br />
else if (code == "high_pressure_border") {weather_tiles.set_high_pressure_border_tile();}<br />
else if (code == "low_pressure_border") {weather_tiles.set_low_pressure_border_tile();}<br />
else if (code == "low_pressure") {weather_tiles.set_low_pressure_tile();}<br />
else if (code == "low_pressure_core") {weather_tiles.set_low_pressure_core_tile();}<br />
else if (code == "cold_sector") {weather_tiles.set_cold_sector_tile();}<br />
else if (code == "warm_sector") {weather_tiles.set_warm_sector_tile();}<br />
else if (code == "tropical_weather") {weather_tiles.set_tropical_weather_tile();}<br />
else if (code == "test") {weather_tiles.set_4_8_stratus_tile();}<br />
else ...<br />
</syntaxhighlight><br />
<br />
While this is not a very complex or huge block of code, it is an excellent example for very good naming conventions used already, because the consistency of naming variables and functions can pay off easily here, with just some very small changes, you can already reduce the whole thing to a hash lookup like this:<br />
<br />
<syntaxhighlight lang="nasal"><br />
weather_tiles["set_"~code~"_tile"](); # naming convention<br />
</syntaxhighlight><br />
<br />
This would dynamically concatenate a key consisting of "set_" + code + "_title" into the hash named weather_tiles, and then call the function that is returned from the hash lookup.<br />
<br />
So for this to work you only need to enforce consistency when naming your functions (i.e. this would of course CURRENTLY fail when the variable code contains "test" because there is no such hash member (it's "4_8_stratus" instead).<br />
<br />
The same applies to cumulus sky (fair weather), stratus/overcast stratus.<br />
<br />
But these are very simple changes to do (just renaming these functions to match the existing conventions). When you do that, you can easily replace such huge IF statements and replace them with a single hash lookup and function call:<br />
<br />
<syntaxhighlight lang="nasal"><br />
hash[key] (arguments...);<br />
</syntaxhighlight><br />
<br />
For example, consider:<br />
<br />
<syntaxhighlight lang="nasal"><br />
var makeFuncString = func(c) return tolower("set_"~c~"_tile");<br />
var isFunc = func(f) typeof(f)=='func';<br />
var hasMethod = func(h,m) contains(h,m) and isFunc;<br />
var callIfAvailable = func(hash, method, unavailable=func{} ) {<br />
var c=hasMethod(hash,makeFuncString(m) ) or unavailable();<br />
hash[makeFuncString(m)] ();<br />
}<br />
callIfAvailable( weather_tiles,code, func {die("key not found in hash or not a func");} );<br />
</syntaxhighlight></div>Chris-barryhttps://wiki.flightgear.org/w/index.php?title=Nasal_library_functions&diff=91909Nasal library functions2016-01-27T18:18:49Z<p>Chris-barry: /* size() */</p>
<hr />
<div>{{Nasal Navigation}}<br />
<br />
Please first see: http://plausible.org/nasal/lib.html<br />
<br />
== size() ==<br />
'''Usage:'''<br />
<br />
size(''object'');<br />
<br />
where ''object'' may be a ''string'', a ''vector'' or a ''hash''.<br />
<br />
'''Return value'''<br />
<br />
An intger equal to the number of characters in a ''string'' argument or the number of elements in a ''vector'' or ''hash''.<br />
<br />
If the argument is a non-string scalar then the error '''object has no size()''' will be generated.<br />
<br />
== keys() ==<br />
<br />
== append() ==<br />
<br />
== pop() ==<br />
<br />
== setsize() ==<br />
'''Usage:'''<br />
<br />
setsize(vect, new_size)<br />
<br />
where ''vect'' is an expression which evaluates to a vector and ''new_size'' is an expression that evaluates to a non-negative number.<br />
<br />
'''Action:'''<br />
<br />
Changes the number of elements in the vetor ''v'' to the value of s.<br />
<br />
'''Return value:'''<br />
<br />
The resized vector.<br />
<br />
'''Notes'''<br />
<br />
Elements that exist in both the original and the resized vector retain their values. When the vector is enlarged newly created elements are set to ''nil''. When the size is reduced the values of all elements beyond the new size are permanently lost.<br />
<br />
The ''new_size'' argument may be any non-negative number. Non-integer values are rounded down.<br />
<br />
The ''vect'' argument need not be a named variable. The expression:<br />
<br />
var v1 = setsize([], n);<br />
<br />
Is a convenient way to allocate an empty vector of a specific size.<br />
<br />
== subvec() ==<br />
Extract items of a vector - equivalent to the left() function for a string<br />
<br />
Example :<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var FGRoot = getprop("/sim/fg-root");<br />
var filename = "/Aircraft";<br />
var path_files = directory(FGRoot ~ filename);<br />
<br />
foreach(var key; path_files) {<br />
print(key);<br />
}<br />
</syntaxhighlight><br />
returns : '''"." , ".." , "Generic", "Instruments", "Instruments-3d", "c172p", "ufo"'''<br />
<br />
<br />
With subvec():<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var FGRoot = getprop("/sim/fg-root");<br />
var filename = "/Aircraft";<br />
var path_files = subvec(directory(FGRoot ~ filename),2);<br />
<br />
foreach(var key; path_files) {<br />
print(key);<br />
}<br />
</syntaxhighlight><br />
returns : '''"Generic", "Instruments", "Instruments-3d", "c172p", "ufo"'''<br />
<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var FGRoot = getprop("/sim/fg-root");<br />
var filename = "/Aircraft";<br />
var path_files = subvec(directory(FGRoot ~ filename),3);<br />
<br />
foreach(var key; path_files) {<br />
print(key);<br />
}<br />
</syntaxhighlight><br />
returns : '''"Instruments", "Instruments-3d", "c172p", "ufo"'''<br />
<br />
== delete() ==<br />
<br />
<br />
== int() ==<br />
<br />
== num(str) ==<br />
Convert string to number.<br />
Returns nil if str is nil, empty string, string with no number.<br />
<br />
== streq() ==<br />
<br />
== cmp() ==<br />
<br />
== substr() ==<br />
<br />
== chr() ==<br />
<br />
== contains() ==<br />
<br />
== typeof() ==<br />
<br />
== ghosttype(ghost) ==<br />
Returns a string containing either a descriptive name as passed to ''naNewGhost'' or ''naNewGhost2'' in C/C++ while creating the ghost or a unique id (aka the pointer to the C/C++ naGhostType instance) if no name has been set.<br />
<br />
== compile() ==<br />
<br />
== call() ==<br />
<br />
== die() ==<br />
<br />
== sprintf() ==<br />
<br />
== caller() ==<br />
<br />
== closure() ==<br />
<br />
== find() ==<br />
<br />
== split() ==<br />
<br />
== rand() ==<br />
<br />
== bind() ==<br />
<br />
== sort() ==<br />
<br />
== id() ==<br />
<br />
= math =<br />
== Trigonometric_functions ==<br />
'''Caution''': All trigonometric functions works with [https://en.wikipedia.org/wiki/Radian Radian]-values - not with Degree!<br />
<br />
<u>To convert this</u>:<br><br />
radians = degree * math.pi / 180<br><br />
degree = radians * 180 / math.pi<br />
=== sin() ===<br />
=== cos() ===<br />
=== tan() ===<br />
=== asin() ===<br />
=== acos() ===<br />
=== atan2() ===<br />
== exp() ==<br />
== ln() ==<br />
== pow() ==<br />
== sqrt() ==<br />
== floor() ==<br />
Returns the value rounded downward<br />
<br />
Example:<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
math.floor(1.2); # returns 1<br />
math.floor(1.6); # returns 1<br />
</syntaxhighlight><br />
<br />
== ceil() ==<br />
Returns the value rounded upward<br />
<br />
Example:<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
math.ceil(1.2); # returns 2<br />
math.ceil(1.6); # returns 2<br />
</syntaxhighlight><br />
<br />
== fmod() ==<br />
A '''modulo'''-operator. The [https://en.wikipedia.org/wiki/Modulo_operation modulo]-operation finds the remainder of division of one number by another (sometimes called modulus).<br />
<br />
fmod(x , y) may be negative if x < 0, whereas mod() seems to guarantee that 0 ≤ mod(x,y) < y, according to tests made with x and y integers, y > 0, x positive or negative.<br />
<br />
== clamp() ==<br />
== periodic() ==<br />
== round() ==<br />
== pi ==<br />
== e ==<br />
<br />
= io =<br />
<br />
* SEEK_SET<br />
* SEEK_CUR<br />
* SEEK_END<br />
* stdin<br />
* stdout<br />
* stderr<br />
<br />
== stat() ==<br />
== directory() ==<br />
returns the files in a given directory<br />
<br />
e.g. chatter_list = directory( chatter_dir );<br />
<br />
Example : <br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var FGRoot = getprop("/sim/fg-root");<br />
var filename = "/Aircraft";<br />
var path_files = directory(FGRoot ~ filename);<br />
<br />
foreach(var key; path_files) {<br />
print(key);<br />
}<br />
</syntaxhighlight><br />
returns : <br />
'''"." , ".." , "Generic", "Instruments", "Instruments-3d", "c172p", "ufo"'''<br />
<br />
To delete the "." and ".." see the subvec() function.<br />
<br />
== open() ==<br />
== read() ==<br />
== readln() ==<br />
== seek() ==<br />
== tell() ==<br />
== write() ==<br />
== flush() ==<br />
== close() ==<br />
<br />
= utf8 =<br />
== chstr() ==<br />
== strc() ==<br />
== substr() ==<br />
== size() ==<br />
== validate() ==</div>Chris-barryhttps://wiki.flightgear.org/w/index.php?title=Nasal_library_functions&diff=91908Nasal library functions2016-01-27T18:13:30Z<p>Chris-barry: /* setsize() */</p>
<hr />
<div>{{Nasal Navigation}}<br />
<br />
Please first see: http://plausible.org/nasal/lib.html<br />
<br />
== size() ==<br />
Usage:<br />
size(''object'');<br />
<br />
where ''object'' may be a ''string'', a ''vector'' or a ''hash''.<br />
<br />
Returns an intger equal to the number of characters in a ''string'' argument or the number of elements in a ''vector'' or ''hash''.<br />
<br />
If the argument is a non-string scalar then the error '''object has no size()''' will be generated.<br />
<br />
== keys() ==<br />
<br />
== append() ==<br />
<br />
== pop() ==<br />
<br />
== setsize() ==<br />
'''Usage:'''<br />
<br />
setsize(vect, new_size)<br />
<br />
where ''vect'' is an expression which evaluates to a vector and ''new_size'' is an expression that evaluates to a non-negative number.<br />
<br />
'''Action:'''<br />
<br />
Changes the number of elements in the vetor ''v'' to the value of s.<br />
<br />
'''Return value:'''<br />
<br />
The resized vector.<br />
<br />
'''Notes'''<br />
<br />
Elements that exist in both the original and the resized vector retain their values. When the vector is enlarged newly created elements are set to ''nil''. When the size is reduced the values of all elements beyond the new size are permanently lost.<br />
<br />
The ''new_size'' argument may be any non-negative number. Non-integer values are rounded down.<br />
<br />
The ''vect'' argument need not be a named variable. The expression:<br />
<br />
var v1 = setsize([], n);<br />
<br />
Is a convenient way to allocate an empty vector of a specific size.<br />
<br />
== subvec() ==<br />
Extract items of a vector - equivalent to the left() function for a string<br />
<br />
Example :<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var FGRoot = getprop("/sim/fg-root");<br />
var filename = "/Aircraft";<br />
var path_files = directory(FGRoot ~ filename);<br />
<br />
foreach(var key; path_files) {<br />
print(key);<br />
}<br />
</syntaxhighlight><br />
returns : '''"." , ".." , "Generic", "Instruments", "Instruments-3d", "c172p", "ufo"'''<br />
<br />
<br />
With subvec():<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var FGRoot = getprop("/sim/fg-root");<br />
var filename = "/Aircraft";<br />
var path_files = subvec(directory(FGRoot ~ filename),2);<br />
<br />
foreach(var key; path_files) {<br />
print(key);<br />
}<br />
</syntaxhighlight><br />
returns : '''"Generic", "Instruments", "Instruments-3d", "c172p", "ufo"'''<br />
<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var FGRoot = getprop("/sim/fg-root");<br />
var filename = "/Aircraft";<br />
var path_files = subvec(directory(FGRoot ~ filename),3);<br />
<br />
foreach(var key; path_files) {<br />
print(key);<br />
}<br />
</syntaxhighlight><br />
returns : '''"Instruments", "Instruments-3d", "c172p", "ufo"'''<br />
<br />
== delete() ==<br />
<br />
<br />
== int() ==<br />
<br />
== num(str) ==<br />
Convert string to number.<br />
Returns nil if str is nil, empty string, string with no number.<br />
<br />
== streq() ==<br />
<br />
== cmp() ==<br />
<br />
== substr() ==<br />
<br />
== chr() ==<br />
<br />
== contains() ==<br />
<br />
== typeof() ==<br />
<br />
== ghosttype(ghost) ==<br />
Returns a string containing either a descriptive name as passed to ''naNewGhost'' or ''naNewGhost2'' in C/C++ while creating the ghost or a unique id (aka the pointer to the C/C++ naGhostType instance) if no name has been set.<br />
<br />
== compile() ==<br />
<br />
== call() ==<br />
<br />
== die() ==<br />
<br />
== sprintf() ==<br />
<br />
== caller() ==<br />
<br />
== closure() ==<br />
<br />
== find() ==<br />
<br />
== split() ==<br />
<br />
== rand() ==<br />
<br />
== bind() ==<br />
<br />
== sort() ==<br />
<br />
== id() ==<br />
<br />
= math =<br />
== Trigonometric_functions ==<br />
'''Caution''': All trigonometric functions works with [https://en.wikipedia.org/wiki/Radian Radian]-values - not with Degree!<br />
<br />
<u>To convert this</u>:<br><br />
radians = degree * math.pi / 180<br><br />
degree = radians * 180 / math.pi<br />
=== sin() ===<br />
=== cos() ===<br />
=== tan() ===<br />
=== asin() ===<br />
=== acos() ===<br />
=== atan2() ===<br />
== exp() ==<br />
== ln() ==<br />
== pow() ==<br />
== sqrt() ==<br />
== floor() ==<br />
Returns the value rounded downward<br />
<br />
Example:<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
math.floor(1.2); # returns 1<br />
math.floor(1.6); # returns 1<br />
</syntaxhighlight><br />
<br />
== ceil() ==<br />
Returns the value rounded upward<br />
<br />
Example:<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
math.ceil(1.2); # returns 2<br />
math.ceil(1.6); # returns 2<br />
</syntaxhighlight><br />
<br />
== fmod() ==<br />
A '''modulo'''-operator. The [https://en.wikipedia.org/wiki/Modulo_operation modulo]-operation finds the remainder of division of one number by another (sometimes called modulus).<br />
<br />
fmod(x , y) may be negative if x < 0, whereas mod() seems to guarantee that 0 ≤ mod(x,y) < y, according to tests made with x and y integers, y > 0, x positive or negative.<br />
<br />
== clamp() ==<br />
== periodic() ==<br />
== round() ==<br />
== pi ==<br />
== e ==<br />
<br />
= io =<br />
<br />
* SEEK_SET<br />
* SEEK_CUR<br />
* SEEK_END<br />
* stdin<br />
* stdout<br />
* stderr<br />
<br />
== stat() ==<br />
== directory() ==<br />
returns the files in a given directory<br />
<br />
e.g. chatter_list = directory( chatter_dir );<br />
<br />
Example : <br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var FGRoot = getprop("/sim/fg-root");<br />
var filename = "/Aircraft";<br />
var path_files = directory(FGRoot ~ filename);<br />
<br />
foreach(var key; path_files) {<br />
print(key);<br />
}<br />
</syntaxhighlight><br />
returns : <br />
'''"." , ".." , "Generic", "Instruments", "Instruments-3d", "c172p", "ufo"'''<br />
<br />
To delete the "." and ".." see the subvec() function.<br />
<br />
== open() ==<br />
== read() ==<br />
== readln() ==<br />
== seek() ==<br />
== tell() ==<br />
== write() ==<br />
== flush() ==<br />
== close() ==<br />
<br />
= utf8 =<br />
== chstr() ==<br />
== strc() ==<br />
== substr() ==<br />
== size() ==<br />
== validate() ==</div>Chris-barryhttps://wiki.flightgear.org/w/index.php?title=Nasal_library_functions&diff=91906Nasal library functions2016-01-27T17:34:30Z<p>Chris-barry: /* size() */</p>
<hr />
<div>{{Nasal Navigation}}<br />
<br />
Please first see: http://plausible.org/nasal/lib.html<br />
<br />
== size() ==<br />
Usage:<br />
size(''object'');<br />
<br />
where ''object'' may be a ''string'', a ''vector'' or a ''hash''.<br />
<br />
Returns an intger equal to the number of characters in a ''string'' argument or the number of elements in a ''vector'' or ''hash''.<br />
<br />
If the argument is a non-string scalar then the error '''object has no size()''' will be generated.<br />
<br />
== keys() ==<br />
<br />
== append() ==<br />
<br />
== pop() ==<br />
<br />
== setsize() ==<br />
<br />
== subvec() ==<br />
Extract items of a vector - equivalent to the left() function for a string<br />
<br />
Example :<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var FGRoot = getprop("/sim/fg-root");<br />
var filename = "/Aircraft";<br />
var path_files = directory(FGRoot ~ filename);<br />
<br />
foreach(var key; path_files) {<br />
print(key);<br />
}<br />
</syntaxhighlight><br />
returns : '''"." , ".." , "Generic", "Instruments", "Instruments-3d", "c172p", "ufo"'''<br />
<br />
<br />
With subvec():<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var FGRoot = getprop("/sim/fg-root");<br />
var filename = "/Aircraft";<br />
var path_files = subvec(directory(FGRoot ~ filename),2);<br />
<br />
foreach(var key; path_files) {<br />
print(key);<br />
}<br />
</syntaxhighlight><br />
returns : '''"Generic", "Instruments", "Instruments-3d", "c172p", "ufo"'''<br />
<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var FGRoot = getprop("/sim/fg-root");<br />
var filename = "/Aircraft";<br />
var path_files = subvec(directory(FGRoot ~ filename),3);<br />
<br />
foreach(var key; path_files) {<br />
print(key);<br />
}<br />
</syntaxhighlight><br />
returns : '''"Instruments", "Instruments-3d", "c172p", "ufo"'''<br />
<br />
== delete() ==<br />
<br />
<br />
== int() ==<br />
<br />
== num(str) ==<br />
Convert string to number.<br />
Returns nil if str is nil, empty string, string with no number.<br />
<br />
== streq() ==<br />
<br />
== cmp() ==<br />
<br />
== substr() ==<br />
<br />
== chr() ==<br />
<br />
== contains() ==<br />
<br />
== typeof() ==<br />
<br />
== ghosttype(ghost) ==<br />
Returns a string containing either a descriptive name as passed to ''naNewGhost'' or ''naNewGhost2'' in C/C++ while creating the ghost or a unique id (aka the pointer to the C/C++ naGhostType instance) if no name has been set.<br />
<br />
== compile() ==<br />
<br />
== call() ==<br />
<br />
== die() ==<br />
<br />
== sprintf() ==<br />
<br />
== caller() ==<br />
<br />
== closure() ==<br />
<br />
== find() ==<br />
<br />
== split() ==<br />
<br />
== rand() ==<br />
<br />
== bind() ==<br />
<br />
== sort() ==<br />
<br />
== id() ==<br />
<br />
= math =<br />
== Trigonometric_functions ==<br />
'''Caution''': All trigonometric functions works with [https://en.wikipedia.org/wiki/Radian Radian]-values - not with Degree!<br />
<br />
<u>To convert this</u>:<br><br />
radians = degree * math.pi / 180<br><br />
degree = radians * 180 / math.pi<br />
=== sin() ===<br />
=== cos() ===<br />
=== tan() ===<br />
=== asin() ===<br />
=== acos() ===<br />
=== atan2() ===<br />
== exp() ==<br />
== ln() ==<br />
== pow() ==<br />
== sqrt() ==<br />
== floor() ==<br />
Returns the value rounded downward<br />
<br />
Example:<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
math.floor(1.2); # returns 1<br />
math.floor(1.6); # returns 1<br />
</syntaxhighlight><br />
<br />
== ceil() ==<br />
Returns the value rounded upward<br />
<br />
Example:<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
math.ceil(1.2); # returns 2<br />
math.ceil(1.6); # returns 2<br />
</syntaxhighlight><br />
<br />
== fmod() ==<br />
A '''modulo'''-operator. The [https://en.wikipedia.org/wiki/Modulo_operation modulo]-operation finds the remainder of division of one number by another (sometimes called modulus).<br />
<br />
fmod(x , y) may be negative if x < 0, whereas mod() seems to guarantee that 0 ≤ mod(x,y) < y, according to tests made with x and y integers, y > 0, x positive or negative.<br />
<br />
== clamp() ==<br />
== periodic() ==<br />
== round() ==<br />
== pi ==<br />
== e ==<br />
<br />
= io =<br />
<br />
* SEEK_SET<br />
* SEEK_CUR<br />
* SEEK_END<br />
* stdin<br />
* stdout<br />
* stderr<br />
<br />
== stat() ==<br />
== directory() ==<br />
returns the files in a given directory<br />
<br />
e.g. chatter_list = directory( chatter_dir );<br />
<br />
Example : <br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var FGRoot = getprop("/sim/fg-root");<br />
var filename = "/Aircraft";<br />
var path_files = directory(FGRoot ~ filename);<br />
<br />
foreach(var key; path_files) {<br />
print(key);<br />
}<br />
</syntaxhighlight><br />
returns : <br />
'''"." , ".." , "Generic", "Instruments", "Instruments-3d", "c172p", "ufo"'''<br />
<br />
To delete the "." and ".." see the subvec() function.<br />
<br />
== open() ==<br />
== read() ==<br />
== readln() ==<br />
== seek() ==<br />
== tell() ==<br />
== write() ==<br />
== flush() ==<br />
== close() ==<br />
<br />
= utf8 =<br />
== chstr() ==<br />
== strc() ==<br />
== substr() ==<br />
== size() ==<br />
== validate() ==</div>Chris-barryhttps://wiki.flightgear.org/w/index.php?title=Nasal_library_functions&diff=91905Nasal library functions2016-01-27T17:33:39Z<p>Chris-barry: /* size() */</p>
<hr />
<div>{{Nasal Navigation}}<br />
<br />
Please first see: http://plausible.org/nasal/lib.html<br />
<br />
== size() ==<br />
Usage:<br />
size(''object'');<br />
where ''object'' may be a ''string'', a ''vector'' or a ''hash''.<br />
Returns an intger equal to the number of characters in a ''string'' argument or the number of elements in a ''vector'' or ''hash''.<br />
If the argument is a non-string scalar then the error '''object has no size()''' will be generated.<br />
<br />
== keys() ==<br />
<br />
== append() ==<br />
<br />
== pop() ==<br />
<br />
== setsize() ==<br />
<br />
== subvec() ==<br />
Extract items of a vector - equivalent to the left() function for a string<br />
<br />
Example :<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var FGRoot = getprop("/sim/fg-root");<br />
var filename = "/Aircraft";<br />
var path_files = directory(FGRoot ~ filename);<br />
<br />
foreach(var key; path_files) {<br />
print(key);<br />
}<br />
</syntaxhighlight><br />
returns : '''"." , ".." , "Generic", "Instruments", "Instruments-3d", "c172p", "ufo"'''<br />
<br />
<br />
With subvec():<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var FGRoot = getprop("/sim/fg-root");<br />
var filename = "/Aircraft";<br />
var path_files = subvec(directory(FGRoot ~ filename),2);<br />
<br />
foreach(var key; path_files) {<br />
print(key);<br />
}<br />
</syntaxhighlight><br />
returns : '''"Generic", "Instruments", "Instruments-3d", "c172p", "ufo"'''<br />
<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var FGRoot = getprop("/sim/fg-root");<br />
var filename = "/Aircraft";<br />
var path_files = subvec(directory(FGRoot ~ filename),3);<br />
<br />
foreach(var key; path_files) {<br />
print(key);<br />
}<br />
</syntaxhighlight><br />
returns : '''"Instruments", "Instruments-3d", "c172p", "ufo"'''<br />
<br />
== delete() ==<br />
<br />
<br />
== int() ==<br />
<br />
== num(str) ==<br />
Convert string to number.<br />
Returns nil if str is nil, empty string, string with no number.<br />
<br />
== streq() ==<br />
<br />
== cmp() ==<br />
<br />
== substr() ==<br />
<br />
== chr() ==<br />
<br />
== contains() ==<br />
<br />
== typeof() ==<br />
<br />
== ghosttype(ghost) ==<br />
Returns a string containing either a descriptive name as passed to ''naNewGhost'' or ''naNewGhost2'' in C/C++ while creating the ghost or a unique id (aka the pointer to the C/C++ naGhostType instance) if no name has been set.<br />
<br />
== compile() ==<br />
<br />
== call() ==<br />
<br />
== die() ==<br />
<br />
== sprintf() ==<br />
<br />
== caller() ==<br />
<br />
== closure() ==<br />
<br />
== find() ==<br />
<br />
== split() ==<br />
<br />
== rand() ==<br />
<br />
== bind() ==<br />
<br />
== sort() ==<br />
<br />
== id() ==<br />
<br />
= math =<br />
== Trigonometric_functions ==<br />
'''Caution''': All trigonometric functions works with [https://en.wikipedia.org/wiki/Radian Radian]-values - not with Degree!<br />
<br />
<u>To convert this</u>:<br><br />
radians = degree * math.pi / 180<br><br />
degree = radians * 180 / math.pi<br />
=== sin() ===<br />
=== cos() ===<br />
=== tan() ===<br />
=== asin() ===<br />
=== acos() ===<br />
=== atan2() ===<br />
== exp() ==<br />
== ln() ==<br />
== pow() ==<br />
== sqrt() ==<br />
== floor() ==<br />
Returns the value rounded downward<br />
<br />
Example:<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
math.floor(1.2); # returns 1<br />
math.floor(1.6); # returns 1<br />
</syntaxhighlight><br />
<br />
== ceil() ==<br />
Returns the value rounded upward<br />
<br />
Example:<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
math.ceil(1.2); # returns 2<br />
math.ceil(1.6); # returns 2<br />
</syntaxhighlight><br />
<br />
== fmod() ==<br />
A '''modulo'''-operator. The [https://en.wikipedia.org/wiki/Modulo_operation modulo]-operation finds the remainder of division of one number by another (sometimes called modulus).<br />
<br />
fmod(x , y) may be negative if x < 0, whereas mod() seems to guarantee that 0 ≤ mod(x,y) < y, according to tests made with x and y integers, y > 0, x positive or negative.<br />
<br />
== clamp() ==<br />
== periodic() ==<br />
== round() ==<br />
== pi ==<br />
== e ==<br />
<br />
= io =<br />
<br />
* SEEK_SET<br />
* SEEK_CUR<br />
* SEEK_END<br />
* stdin<br />
* stdout<br />
* stderr<br />
<br />
== stat() ==<br />
== directory() ==<br />
returns the files in a given directory<br />
<br />
e.g. chatter_list = directory( chatter_dir );<br />
<br />
Example : <br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var FGRoot = getprop("/sim/fg-root");<br />
var filename = "/Aircraft";<br />
var path_files = directory(FGRoot ~ filename);<br />
<br />
foreach(var key; path_files) {<br />
print(key);<br />
}<br />
</syntaxhighlight><br />
returns : <br />
'''"." , ".." , "Generic", "Instruments", "Instruments-3d", "c172p", "ufo"'''<br />
<br />
To delete the "." and ".." see the subvec() function.<br />
<br />
== open() ==<br />
== read() ==<br />
== readln() ==<br />
== seek() ==<br />
== tell() ==<br />
== write() ==<br />
== flush() ==<br />
== close() ==<br />
<br />
= utf8 =<br />
== chstr() ==<br />
== strc() ==<br />
== substr() ==<br />
== size() ==<br />
== validate() ==</div>Chris-barry