https://wiki.flightgear.org/w/api.php?action=feedcontributions&feedformat=atom&user=Clm76FlightGear wiki - User contributions [en]2026-04-05T08:38:08ZUser contributionsMediaWiki 1.39.6https://wiki.flightgear.org/w/index.php?title=Nasal_library&diff=138674Nasal library2023-11-12T10:31:53Z<p>Clm76: </p>
<hr />
<div>{{Nasal Navigation|nocat=1}}<br />
This page documents the global '''library functions and variables''' 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, the ''[[#Extension functions|extension functions]]'', which have been subsequently added, and are specifically designed for FlightGear, and the ''[[#variables|global variables]]'', which are conversion variables, added with extension functions, for converting between units. The relevant folders in [[Git]] are:<br />
* {{flightgear file|src/Scripting}}<br />
* {{simgear file|simgear/nasal}}<br />
<br />
All these functions and variables are in the global namespace, that is, they are directly accessible (e.g., one can call <syntaxhighlight lang="nasal" inline>magvar()</syntaxhighlight> instead of <syntaxhighlight lang="nasal" inline>namespace.magvar()</syntaxhighlight>). However, if a namespace must be used, <code>globals</code> is the correct namespace, but using it is not recommended. For a more complete explanation, see [[Nasal Namespaces in-depth]].<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|printerror()|debug}}.<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.<br />
<br />
The result is a four-element vector containing '''[0]''' a hash of local variables, '''[1]''' the function object, '''[2]''' the full source file name (incl. path) and '''[3]''' the line number. <br />
|param1 = level<br />
|param1text = Optional integer specifying the stack level to return a result from. Defaults to 1 (i.e. 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 lang="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 />
<br />
===contains()===<br />
{{Requires commit|desc=Vector support|details=see {{Merge-request|project=fgdata|id=305}}|commit=ee39abbd3b70c9b6d5e3a1c4ccedddaac1a92b11|repo=Simgear}}<br />
{{Nasal doc<br />
|syntax = contains(vector, item);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=184|t=Source}}<br />
|text = Returns 1 (True) if the vector contains the specified item, or 0 (False) if not.<br />
|param1 = vector<br />
|param1text = The vector to search in.<br />
|param2 = item<br />
|param2text = The object to be searched for in the vector.<br />
|example1 =<br />
# Initialize a hash<br />
var vec = ["element", "foo"];<br />
print(contains(hash, "element") ? "Yes" : "No"); # This will print "Yes"<br />
|example2 =<br />
# Initialize a hash<br />
var vec = ["element", "foo"];<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 NOT identical to setting the hash value specified by the key to <code>'''nil'''</code> as the key will stay in the hash (at least for a while). 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 />
|commit = {{simgear commit|bd7163|t=commit}}<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 />
|commit = {{simgear commit|bd7163|t=commit}}<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()|link=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 />
|example2text = 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 />
|example3text = This example sorts a vector of strings (runways for example) from smallest to greatest.<br />
|example3 = <br />
var runways = ["09R","27R","26L","09L","15"];<br />
var rwy = sort(runways,func(a,b) cmp(a,b));<br />
debug.dump(rwy); # prints ['09L','09R','15','26L','27R']<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 = <nowiki>sprintf(format[, arg[, arg, [...]]]);</nowiki><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()|link=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. This includes the decimal point and decimal fraction as well as + or - signs.<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>s</code> {{!!}} A string<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 />
|example10 =<br />
print(sprintf("%.2f", 1.4)); #prints "1.40"<br />
print(sprintf("%.1f", 1.4)); #prints "1.4"<br />
print(sprintf("% 4.1f", 1.4)); #prints " 1.4"<br />
print(sprintf("%04.1f", 1.4)); #prints "01.4"<br />
print(sprintf("% 6.1f", 1.4)); #prints " 1.4"<br />
print(sprintf("%06.1f", 1.4)); #prints "0001.4"<br />
}}<br />
<br />
===streq()===<br />
{{Nasal doc<br />
|syntax = streq(a, b);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=129|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. Negative values specify a position from the end of the string.<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 />
|example4 = print(substr("abcde", -2)); # prints "de"<br />
|example5 = print(substr("abcde", -3, 2)); # prints "cd"<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 />
* Omitting the ''vector'' and ''start'' arguments is not an error (possibly it should be) but the return value is ''nil''.<br />
* A negative ''start'' argument ''is'' an error. This seems wrong. Perhaps the language designer could comment.<br />
* A value of ''start'' greater than ''size(vector)'' causes an error. A value equal to ''size(vector)'' returns an empty vector.<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 />
|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 modules ==<br />
=== thread ===<br />
{{WIP}}<br />
<br />
{{Nasal doc<br />
|syntax = thread.newthread(func);<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = start a new worker thread<br />
|example1 = thread.newthread( func() {} );<br />
}}<br />
<br />
{{Nasal doc<br />
|syntax = thread.newlock();<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = create a new lock<br />
|example1 = var lock = thread.newlock()<br />
}}<br />
<br />
{{Nasal doc<br />
|syntax = thread.lock();<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = lock a lock<br />
|example1 = var lock = thread.newlock()<br />
}}<br />
<br />
{{Nasal doc<br />
|syntax = thread.unlock();<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = unlock a lock<br />
|example1 = var lock = thread.unlock()<br />
}}<br />
<br />
<br />
{{Nasal doc<br />
|syntax = thread.newsem();<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = create a new {{Wikipedia|semaphore}}<br />
|example1 = var semaphore = thread.newsem()<br />
}}<br />
<br />
<br />
{{Nasal doc<br />
|syntax = thread.semdown();<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = semaphore down<br />
|example1 = thread.semdown(semaphore)<br />
}}<br />
<br />
<br />
{{Nasal doc<br />
|syntax = thread.semup();<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = semaphore up<br />
|example1 = thread.semup(semaphore)<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()|link=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 />
===aircraftToCart() ===<br />
This new function in FG 2017.2.1 takes coordinates in aircraft structural coordinate system, and translate them into geocentric coordinates.<br />
Example for (5,6,7):<br />
<syntaxhighlight lang="nasal"><br />
var pos = aircraftToCart({x: -5, y: 6, z: -7});<br />
var coord = geo.Coord.new();<br />
coord.set_xyz(pos.x, pos.y, pos.z);<br />
</syntaxhighlight><br />
Notice: x and z is inverted sign on purpose.<br />
if you want lat. lon, alt from that, just call: (degrees and meters)<br />
<br />
<syntaxhighlight lang="nasal"><br />
coord.lat()<br />
coord.lon()<br />
coord.alt()<br />
</syntaxhighlight><br />
<br />
===addcommand() ===<br />
{{Nasal doc<br />
|syntax = addcommand(name, code);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=659|t=Source}}<br />
|version = 2.12<br />
|commit = {{flightgear commit|7b663c|t=commit}}<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(node) {<br />
print("fgcommand 'myFGCmd' has been run.");<br />
props.dump( node );<br />
});<br />
fgcommand("myFGCmd", props.Node.new({foo:1, bar:2}) );<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 />
* '''parents''': A vector containing a hash of various functions to access information about the runway. See {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2659}} for full list.<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 />
*** '''id''': Name of runway.<br />
*** '''lat''': Latitude of the runway.<br />
*** '''lon''': Longitude of the runway.<br />
*** '''heading''': Heading of the runway.<br />
*** '''length''': Length of the runway in metres.<br />
*** '''width''': Width of the runway in metres.<br />
*** '''surface''': Runway surface type.<br />
*** '''threshold''': Length of the runway's {{wikipedia|displaced threshold}} in metres. Will return 0 if there is none.<br />
*** '''stopway''': Length of the runway's stopway (the area before the threshold) in metres. Will return 0 if there is none.<br />
*** '''reciprocal''': <code>runway</code> ghost of the reciprocal runway.<br />
*** '''ils_frequency_mhz''': ILS frequency in megahertz.<br />
*** '''ils''': <code>navaid</code> ghost of the ILS transmitter.<br />
* '''helipads'''<br />
** '''<helipad name>'''<br />
*** '''id''': Name of helipad.<br />
*** '''lat''': Latitude of the helipad.<br />
*** '''lon''': Longitude of the helipad.<br />
*** '''heading''': Heading of the helipad.<br />
*** '''length''': Length of the helipad in metres.<br />
*** '''width''': Width of the helipad in metres.<br />
*** '''surface''': Helipad surface type.<br />
* '''taxiways'''<br />
** '''<taxiway name>'''<br />
*** '''id''': Name of taxiway.<br />
*** '''lat''': Latitude of the taxiway.<br />
*** '''lon''': Longitude of the taxiway.<br />
*** '''heading''': Heading of the taxiway.<br />
*** '''length''': Length of the taxiway in metres.<br />
*** '''width''': Width of the taxiway in metres.<br />
*** '''surface''': Taxiway surface type.<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 />
<nowiki>}</nowiki><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 />
<nowiki>}</nowiki><br />
}}<br />
<br />
===airway()===<br />
<br />
{{Nasal doc<br />
|syntax = airway(ident [, pos]);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2644|t=Source}}<br />
|text = {{see also|Nasal Flightplan}}<br />
This function returns a ghost containing an airway of a specified id.<br />
|param1 = ident<br />
|param1text = a Positioned ghost (leg, navaid, airport) and so on, passed to the search function.<br />
|param2 = pos<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 />
|commit = {{fgdata commit|8b16a7|t=commit}}<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 with geodetic coordinates (cartesian coordinates will not be accepted)<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 />
===createFlightplan()===<br />
{{Nasal doc<br />
|syntax = createFlightplan(path);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2331|t=Source}}<br />
|text = Creates an empty flightplan object. It accepts one argument, ''path'' passed an absolute path to a .fgfp / .gpx file, it will populate the flightplan with waypoints from the file.<br />
|param1 = path<br />
|param1text = Optional parameter defining the file from which a flightplan will be populated.<br />
|example1 = <br />
var path = getprop("/sim/fg-home") ~ "/Export/test.fgfp";<br />
var flightplan = createFlightplan(path);<br />
debug.dump(flightplan);<br />
}}<br />
<br />
===createDiscontinuity()===<br />
{{Nasal doc<br />
|syntax = createDiscontinuity();<br />
|text = Returns a <code>waypoint</code> ghost object. A route discontinuity is inserted by an {{abbr|FMS|Flight Management System}} when it is unsure how to connect two waypoints.<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2045|t=Source}}<br />
|version = 2016.1<br />
|commit = {{flightgear commit|caead6|t=commit}}<br />
}}<br />
===createViaTo()===<br />
{{Nasal doc<br />
|syntax = createViaTo(airway, waypoint);<br />
|text = Returns a <code>waypoint</code> ghost object. It represents a route "via '''airway''' to '''waypoint'''".<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2009|t=Source}}<br />
|version = 2016.1<br />
|commit = {{flightgear commit|caead6|t=commit}}<br />
|param1 = airway<br />
|param1text = The name of an airway.<br />
|param2 = waypoint<br />
|param2text = Must be in the airway and one of:<br />
* The name of a waypoint.<br />
* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, or <code>fix</code> ghost object.<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 />
<nowiki>}</nowiki><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 />
<nowiki>}</nowiki><br />
}}<br />
<br />
===findCommByFrequencyMHz()===<br />
findCommByFrequencyMHz([pos, ]freq[, type]);<br />
[[sourceforge:p/flightgear/flightgear/ci/next/tree/src/Scripting/NasalPositioned.cxx#l1547|source]]<br />
<br />
Returns a <code>comm</code> ghost object for a station matching a given frequency. If there is more than one station with that frequency, the nearest station is returned.<br />
<br />
'''pos'''<br />
<br />
: 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>findCommByFrequencyMHz(lat, lon, freq, type);</code>.<br />
; freq<br />
: Frequency, in megahertz, of the station to search for.<br />
; type<br />
: This will narrow the search to station of a certain type. Defaults to "all." For the full list of accepted type arguments, see flightgear/src/Navaids/positioned.cxx (line 160)<br />
'''Example'''<br />
var com = findCommByFrequencyMHz(123.6);<br />
print("ID: ", com.id); # prints info about the comm station<br />
print("Name: ", com.name);<br />
print("Latitude: ", com.lat);<br />
print("Longitude: ", com.lon);<br />
print("Type: ", com.type);<br />
print("Frequency: ", sprintf("%.3f", com.frequency), " Mhz");<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 />
===findNavaidByFrequencyMHz()===<br />
{{Nasal doc<br />
|syntax = findNavaidByFrequencyMHz([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>findNavaidByFrequencyMHz(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 = findNavaidByFrequencyMHz(109.55);<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 / 100), " Mhz");<br />
print("Range: ", navaid.range_nm, " nm");<br />
if(navaid.course) print("Course: ", navaid.course);<br />
}}<br />
<br />
=== findNavaidsByFrequencyMHz()===<br />
{{Nasal doc<br />
|syntax = findNavaidsByFrequencyMHz([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>findNavaidsByFrequencyMHz(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 = findNavaidsByFrequencyMHz(109.55);<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 / 100), " Mhz");<br />
print("Range: ", navaid.range_nm, " nm");<br />
if(navaid.course) print("Course: ", navaid.course);<br />
print("--");<br />
<nowiki>}</nowiki><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 />
<nowiki>}</nowiki><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 />
<nowiki>}</nowiki><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 />
<nowiki>}</nowiki><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 />
=== get_cart_ground_intersection()===<br />
Introduced in 2017.2.1, see [[Terrain Detection]].<br />
<br />
===getprop()===<br />
{{Nasal doc<br />
|syntax = <nowiki>getprop(path[, path[, ...]]);</nowiki><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 = path<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 also 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 versions 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 />
<nowiki>}</nowiki><br />
}}<br />
==== See also====<br />
{{note| If you have to read/write the same property multiple times (e.g. in an update loop), it is more efficient to use a node object: <br />
To get a Node rather than its value, use <code>props.globals.getNode()</code> - see [[Nasal_library/props]]. }}<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 = <nowiki>interpolate(prop, value1, time1[, value2, time2[, ...]]);</nowiki><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 />
<nowiki>}</nowiki><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 = <nowiki>logprint(priority[, msg[, msg[, ...]]]);</nowiki><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 from the Nasal file itself rather than from {{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 />
{{note| <br />
The following constants have been added to the development branch of FlightGear ("next") and will be releases with FG 2020.1 so you won't have to remember the numbers anymore:<br />
<br />
LOG_BULK, LOG_WARN, LOG_DEBUG, LOG_INFO, LOG_ALERT, DEV_WARN, DEV_ALERT }}<br />
<br />
===magvar() ===<br />
{{Nasal doc<br />
|syntax = magvar([pos]);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1642|t=Source}}<br />
|text = Returns the {{wikipedia|magnetic variation}} at a given set of coordinates. The table below gives the magnetic model used depending on the version of FlightGear.<br />
{{{!}} class="wikitable"<br />
! FlightGear versions !! Model !! Reference date<br />
{{!-}}<br />
{{!}} 3.6 and above {{!!}} {{wikipedia|World Magnetic Model}} (WMM) 2015 {{!!}} 1 January 2015<br />
{{!-}}<br />
{{!}} 0.9.11-pre1 to 3.4 {{!!}} WMM 2005 {{!!}} 1 January 2005<br />
{{!-}}<br />
{{!}} 0.7.3 to 0.9.10 {{!!}} WMM 2000 {{!!}} 1 January 2000<br />
{{!}}}<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>magvar(lat,lon)</code>.<br />
|example1 = print(magvar(0, 0)); # prints the magnetic variation at 0, 0<br />
}}<br />
<br />
===maketimer() ===<br />
{{Nasal doc<br />
|syntax = maketimer(interval[, self], function);<br />
|source = ''Implemented using the {{API Link|flightgear|class|TimerObj}} class.''<br>{{flightgear file|src/Scripting/NasalSys.cxx|l=90|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=533|t=Part 2}}<br />
|version = 2.12<br />
|commit = {{flightgear commit|ab939f|t=commit}}<br />
|text = Returns a timer object containing the following methods and members:<br />
* '''start()''': Starts the timer.<br />
* '''stop()''': Stops the timer.<br />
* '''restart(interval)''': Restarts the timer with the given interval.<br />
* '''singleShot''': Bool showing whether the timer is only to be run once, or continuously until told to stop. Can be both set and read from (see examples).<br />
* '''isRunning''': Read-only bool telling whether the timer is currently running.<br />
* '''simulatedTime''': (FG 2017.1+; {{flightgear commit|0af316|t=commit}}) Bool telling whether the timer is using simulated time (which accounts for pause, etc.). Defaults to false (use real time). Can be both read and set. This cannot be changed while the timer is running.<br />
Unlike {{func link|settimer()}}, which it replaces, <code>maketimer()</code> provides more control over the timer. In addition, it can help reduce memory usage.<br />
|param1 = interval<br />
|param1text = Interval in seconds for the timer.<br />
|param2 = self<br />
|param2text = Optional parameter specifying what any <code>'''me'''</code> references in the function being called will refer to.<br />
|param3 = function<br />
|param3text = Function to be called at the given interval.<br />
|example1 = var timer = maketimer(1, func(){<br />
print("Hello, World!"); # print "Hello, World!" once every second (call timer.stop() to stop it)<br />
});<br />
timer.start();<br />
|example2 = var timer = maketimer(1, math, func(){<br />
print(me.math); # 'me' reference is the 'math' namespace<br />
});<br />
timer.singleShot = 1; # timer will only be run once<br />
timer.start();<br />
|example3 = var timer = maketimer(1, func(){<br />
print("Hello, World!"); # print "Hello, World!" once every second (call timer.stop() to stop it)<br />
});<br />
timer.start();<br />
print(timer.isRunning); # prints 1<br />
|example4text = In the example below, "Hello, World!" will be printed after one second the first time, and after two seconds thereafter.<br />
|example4 = var update = func(){<br />
print("Hello, World!");<br />
timer.restart(2); # restarts the timer with a two second interval<br />
}<br />
<br />
var timer = maketimer(1, update);<br />
timer.singleShot = 1;<br />
timer.start();<br />
}}<br />
<br />
===maketimestamp()===<br />
{{Nasal doc<br />
|syntax = maketimestamp()<br />
|source = ''Implemented using the {{API Link|flightgear|class|TimeStampObj}} class.''<br>{{flightgear file|src/Scripting/NasalSys.cxx|l=214|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=589|t=Part 2}}<br />
|version = 2019.2<br />
|commit = {{flightgear commit|7db06300|t=commit}}<br />
|text = Returns a time stamp object to allow high resolution timing of Nasal operations. When created the timer will automatically be stamped. The object has the following methods:<br />
* '''stamp()''': Resets the timing operation. Call this first.<br />
* '''elapsedMSec()''': returns number of milliseconds elapsed since stamp() called. Resolution may vary depending on platform but is usually at least millisecond accuracy.<br />
* '''elapsedUSec()''': returns number of microseconds elapsed since stamp() called. Resolution may vary depending on platform but is usually at least millisecond accuracy.<br />
|<br />
|example1text = In the example below the number of milliseconds elapsed will be printed.<br />
|example1 = var timestamp = maketimestamp();<br />
timestamp.stamp();<br />
print(timestamp.elapsedMSec(), "ms elapsed");<br />
print(timestamp.elapsedMSec(), "ms elapsed");<br />
}}<br />
<br />
===md5()===<br />
{{Nasal doc<br />
|syntax = md5(string);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=758|t=Source}}<br />
|version = 3.2<br />
|commit = {{flightgear commit|cfbf9e|t=commit}}<br />
|text = Returns a the {{wikipedia|MD5}} hash (as a string) of the inputted string.<br />
|param1 = string<br />
|param1text = String the generate the hash of. Mandatory.<br />
|example1text = The below code should output <code>65a8e27d8879283831b664bd8b7f0ad4</code>.<br />
|example1 = print(md5("Hello, World!"));<br />
}}<br />
<br />
===navinfo()===<br />
{{Nasal doc<br />
|syntax = navinfo(lat, lon, type, id);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1453|t=Source}}<br />
|text = Returns vector <code>navaid</code> ghost objects matching the given '''type''' and '''id''' or <code>'''nil'''</code> on error.<br />
|param1 = lat ''and'' lon<br />
|param1text = If given, the returned navaids will be put into order of ascending distance from the location.<br />
|param2 = type<br />
|param2text = Narrows the search to the given type. Must be one of "any," "fix," "vor," "ndb," "ils," "dme," or "tacan." Defaults to the equivalent of "any."<br />
|param3 = id<br />
|param3text = ID to search for. Note that, although all the parameters are technically optional, this parameter must be given, otherwise an empty vector will be returned.<br />
|example1 = navinfo("vor"); # returns all VORs<br />
|example2 = navinfo("HAM"); # return all navaids whose names start with "HAM"<br />
|example3 = navinfo("vor", "HAM"); # return all VORs whose names start with "HAM"<br />
|example4 = navinfo(34,48,"vor","HAM"); # return all VORs whose names start with "HAM" and sorted by distance relative to 34°, 48°<br />
}}<br />
<br />
===parse_markdown()===<br />
{{Nasal doc<br />
|syntax = parse_markdown(markdown);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=745|t=Part 1}} {{!}} {{simgear file|simgear/misc/SimpleMarkdown.cxx|t=Part 2}} <br />
|version = 3.2<br />
|text = Parses a string containing {{wikipedia|Markdown}} and returns the result as a string. As of FlightGear 2016.1, it is just a simple parser, and does the following:<br />
* It strips whitespace from the beginning of the string.<br />
* It supports [http://daringfireball.net/projects/markdown/syntax#p paragraphs and line breaks].<br />
* It collapses whitespace.<br />
* It converts unordered [http://daringfireball.net/projects/markdown/syntax#list lists] to use a bullet character (&bull;). Note that the bullet character is implemented in hexadecimal UTF-8 character bytes (<code>E2 80 A2</code>), as so may not work properly when the being displayed in an encoding other than UTF-8.<br />
|param1 = markdown<br />
|param1text = String containing Markdown to be parsed.<br />
|example1text = <br />
Save the below code as <tt>''[[$FG_ROOT]]/gui/dialogs/test.xml''</tt>, then run the Nasal code below it to open the dialog. To change the markdown to be parsed, simply change the code in the highlighted section, save it, and reload the GUI (<tt>Debug > Reload GUI</tt>).<br />
<syntaxhighlight lang="xml" highlight="41-50"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<br />
<PropertyList><br />
<br />
<name>test</name><br />
<layout>vbox</layout><br />
<br />
<group><br />
<layout>hbox</layout><br />
<br />
<empty><br />
<stretch>true</stretch><br />
</empty><br />
<br />
<text><br />
<label>parse_markdown() test dialog</label><br />
</text><br />
<br />
<empty><br />
<stretch>true</stretch><br />
</empty><br />
<br />
<button><br />
<legend></legend><br />
<pref-width>16</pref-width><br />
<pref-height>16</pref-height><br />
<binding><br />
<command>dialog-close</command><br />
</binding><br />
</button><br />
<br />
</group><br />
<br />
<canvas><br />
<name>Canvas plot</name><br />
<stretch>true</stretch><br />
<pref-width>400</pref-width><br />
<pref-height>300</pref-height><br />
<nasal><br />
<load><![CDATA[<br />
var text = 'Items:<br />
* apples<br />
* oranges<br />
* pears<br />
<br />
Some text.<br />
Some more items:<br />
* apples<br />
* oranges<br />
* pears';<br />
<br />
var parsed = parse_markdown(text);<br />
<br />
var root_canvas = canvas.get(cmdarg());<br />
root_canvas.setColorBackground(255, 255, 255);<br />
var root = root_canvas.createGroup();<br />
<br />
var text_dis = root.createChild("text")<br />
.setText(parsed)<br />
.setTranslation(5, 5)<br />
.setFont("LiberationFonts\LiberationSans-Regular.ttf")<br />
.setFontSize(15)<br />
.setColor(0, 0, 0)<br />
.setDrawMode(canvas.Text.TEXT)<br />
.setAlignment("left-top");<br />
]]></load><br />
</nasal><br />
</canvas><br />
<br />
</PropertyList><br />
</syntaxhighlight><br />
|example1 = fgcommand("dialog-show", {"dialog-name": "test"});<br />
|example2text = The example below parses Markdown and outputs it in a HTML document. The parsed text is placed in <syntaxhighlight lang="xml" inline><pre></pre></syntaxhighlight> tags. To change the Markdown to be parsed, simply edit the variable <tt>markdown</tt> at the top of the code.<br />
|example2 = <nowiki>var markdown = 'Items:<br />
* apples<br />
* oranges<br />
* pears<br />
<br />
Some text.<br />
Some more items:<br />
* apples<br />
* oranges<br />
* pears';<br />
<br />
var parsed = parse_markdown(markdown);<br />
<br />
debug.dump(parsed);<br />
<br />
var path = string.normpath(getprop("/sim/fg-home") ~ '/Export/parse_markdown()-test.html');<br />
<br />
var file = io.open(path, "w");<br />
<br />
var html = "<!DOCTYPE html>\n\n<html>\n\n<head>\n\t<meta charset=\"UTF-8\">\n\t<title>parse_markdown() test generated by Nasal</title>\n</head>\n\n<body>\n\t<pre>" ~ parsed ~ "</pre>\n</body>\n\n</html>";<br />
<br />
io.write(file, html);<br />
io.close(file);<br />
print("Done, file ready for viewing (" ~ path ~ ")");</nowiki><br />
}}<br />
<br />
===parsexml()===<br />
{{Nasal doc<br />
|syntax = <nowiki>parsexml(path[, start[, end[, data[, pro_ins]]]]);</nowiki><br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=710|t=Source}}<br />
|text = This function is an interface into the built-in [http://expat.sourceforge.net/ Expat XML parser]. The absolute path to the file is returned as string, or <code>'''nil'''</code> is returned on error.<br />
|param1 = path<br />
|param1text = Mandatory absolute path to the XML file to be parsed.<br />
|param2 = start<br />
|param2text = Optional callback function that will be called for every starting tag. The function should take two argument: the tag name and a hash containing attributes.<br />
|param3 = end<br />
|param3text = Optional callback function that will be called for every ending tag. The function should take one argument: the tag name.<br />
|param4 = data<br />
|param4text = Optional callback function that will be called for every piece of data within a set of tags. The function should take one argument: the data as a string.<br />
|param5 = pro_ins<br />
|param5text = Optional callback function that will be called for every {{wikipedia|Processing Instruction|processing instruction}}. The function should take two argument: the target and the data string.<br />
|example1text = Save the below XML code in <tt>''[[$FG_HOME]]/Export/demo.xml''</tt>. Then, execute the Nasal code below in the Nasal Console. The XML will be parsed and each bit of the code will be printed.<br />
<syntaxhighlight lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<br />
<?xml-stylesheet type="text/xsl" href="style.xsl"?><br />
<br />
<foo><br />
<blah type="string"><![CDATA[ <sender>John Smith</sender> ]]></blah><br />
<blah2 type="string">Orange &amp; lemons</blah2><br />
</foo><br />
</syntaxhighlight><br />
|example1 = 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 />
}<br />
<br />
var end = func(name){<br />
print("Ending tag: '", name, "'");<br />
}<br />
<br />
var data = func(data){<br />
print("Data = '", data, "'");<br />
}<br />
<br />
var pro_instr = func(target, data){<br />
print("Processing instruction: target = '", target, "', data = '", data, "'");<br />
}<br />
<br />
parsexml(getprop("/sim/fg-home") ~ '/Export/demo.xml', start, end, data, pro_instr);<br />
}}<br />
<br />
===print()===<br />
{{Note|As of 07/2020, we are in the process of slowly deprecating and removing Nasal print() (in fgdata) where possible in favor of log [[#logprint()]] which takes a priority level.<br />
<br />
This is part of the goal that we achieve zero output at log-level at alert, and everything shown at ‘warn; is really a warning, not just information.<ref>https://sourceforge.net/p/flightgear/mailman/message/37042224/</ref>}}<br />
<br />
{{Nasal doc<br />
|syntax = <nowiki>print(data[, data[, ...]]);</nowiki><br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=415|t=Source}}<br />
|text = Concatenates its arguments and then prints it to the terminal and the [[Commonly used debugging tools#fgfs.log|log]]. Note that a newline is automatically added.<br />
|param1 = data<br />
|param1text = Data to print. Only strings and numbers can be printed; other data types will not be. There many be any number of arguments; they will just be concatenated together.<br />
|example1 = print("Just", " a ", "test"); # prints "Just a test"<br />
|example2 = print("pi = ", math.pi); # prints "pi = 3.141592..."<br />
}}<br />
<br />
=== printf() ===<br />
{{Nasal doc<br />
|syntax = <nowiki>printf(format[, arg[, arg, [...]]]);</nowiki><br />
|source = {{fgdata file|Nasal/globals.nas|t=Source}}<br />
|text = Creates and prints a formatted string. For a description of its arguments, see {{func link|sprintf()}} (it is, in fact, implemented using <code>sprintf()</code>).<br />
|example1 = printf("In hexadecimal, 100000 = %X", 186A0); # prints "In hexadecimal, 100000 = 186A0"<br />
}}<br />
<br />
===printlog()===<br />
{{Nasal doc<br />
|syntax = <nowiki>printlog(level, data[, data[, ...]]);</nowiki><br />
|source = {{fgdata file|Nasal/globals.nas|t=Source}}<br />
|text = Prints the given message with the given log level. If the log level is higher or equal to <code>/sim/logging/priority</code>, it is printed.<br />
|param1 = level<br />
|param1text = Mandatory log level as a string. Must be one of "none," "bulk," "debug," "info," "warn," or "alert." Note that "none" will mean that the message will never be printed.<br />
|param2 = data<br />
|param2text = Data to be printed. Only strings and numbers will be printed; others will not be. There may be any number of arguments; they will just be concatenated together.<br />
|example1 = printlog("alert", "This is an alert"); # message will be printed<br />
|example2 = printlog("info", "Just informing you about something"); # message will be printed only if log level is set to "info" or less<br />
}}<br />
<br />
===rand()===<br />
{{Nasal doc<br />
|syntax = rand();<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=554|t=Source}}<br />
|text = Returns a random floating point number between 0 (inclusive) and 1 (exclusive). It takes no arguments.<br />
|example1 = print(rand()); # prints random number<br />
}}<br />
<br />
===registerFlightPlanDelegate()===<br />
{{Nasal doc<br />
|syntax = registerFlightPlanDelegate(init_func);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1879|t=Source}}<br />
|text = Registers a flight plan delegate. See <tt>''{{fgdata file|Nasal/route_manager.nas|t=$FG_ROOT/Nasal/route_manager.nas}}''</tt> for examples.<br />
|param1 = init_func<br />
|param1text = Initialization function which will be called during FlightGear's startup.<br />
}}<br />
===removecommand()===<br />
{{Nasal doc<br />
|syntax = removecommand(cmd);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=668|t=Source}}<br />
|text = Removes the given fgcommand. Returns <code>'''nil'''</code>.<br />
{{caution|This will remove '''any''' [[fgcommands|fgcommand]], even those implemented in C++, so use with caution!}}<br />
|param1 = cmd<br />
|param1text = String specifying the name of the command to remove.<br />
|example1 = addcommand("hello", func(){<br />
print("Hello");<br />
});<br />
fgcommand("hello"); # "Hello" will be printed<br />
removecommand("hello"); # removes it<br />
}}<br />
<br />
===removelistener()===<br />
{{Nasal doc<br />
|syntax = removelistener(id);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=1384|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=506|t=Part 2}}<br />
|text = Removes and deactivates the given listener and returns the number of listeners left or <code>'''nil'''</code> on error.<br />
{{note|It is good practice to remove listeners when they are not required anymore. This prevents the listeners reducing FlightGear's run performance.}}<br />
|param1 = id<br />
|param1text = ID of listener as returned by {{func link|setlistener()}}.<br />
|example1 = var ls = setlistener("/sim/test", func(){<br />
print("Property '/sim/test' has been changed");<br />
});<br />
setprop("/sim/test", "blah"); # trigger listener<br />
var rem = removelistener(ls); # remove listener<br />
print("There are ", rem, " listeners remaining");<br />
}}<br />
<br />
===resolvepath()===<br />
{{Nasal doc<br />
|syntax = resolvepath(path);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=604|t=Source}}<br />
|text = Takes a relative path as a string and uses [[SimGear]]'s path-resolving framework to return an absolute path as a string. If the path could not be resolved, an empty string is returned. See [[Resolving Paths]] for a detailed description of the algorithm. This function can also be used to check if a file exists.<br />
|param1 = path<br />
|param1text = Relative path to be completed.<br />
|example1 = print(resolvepath("Nasal/globals.nas")); # prints the equivalent of $FG_ROOT/Nasal/globals.nas<br />
|example2 = print(resolvepath("blah")); # prints nothing; could not be resolved<br />
|example3 = var file_path = resolvepath("Aircraft/SenecaII/some-file");<br />
if (file_path != ""){<br />
gui.popupTip("some-file found", 2);<br />
} else {<br />
gui.popupTip("some-file not found", 2);<br />
<nowiki>}</nowiki><br />
}}<br />
<br />
===setlistener()===<br />
{{Nasal doc<br />
|syntax = <nowiki>setlistener(node, code[, init[, type]]);</nowiki><br />
|private = _setlistener()<br />
|source = {{flightgear file|src/Scripting/Nasal|l=499|t=Part 1}} {{!}} {{flightgear file|src/Scripting/Nasal|l=1350|t=Part 2}}<br>''Listener implemented using the {{API Link|flightgear|class|FGNasalListener}} class.''<br />
|text = Creates a listener which will be triggered when the given property is changed (depending on the '''type'''). A unique integer ID is returned; this can later be used as the argument to {{func link|removelistener()}}.<br />
{{note|Listeners are known to be a source of resource leaks. To avoid this, please take measures such as:<br />
* Using {{func link|removelistener()}} when they are not needed any more.<br />
* Using a single initialization listener.<br />
* Avoiding tying listeners to properties that are rapidly updated (e.g., many times per frame).<br />
}}<br />
|param1 = node<br />
|param1text = Mandatory string or <code>props.Node</code> object pointing to a property in the [[Property Tree]].<br />
|param2 = code<br />
|param2text = Mandatory callback function to execute when the listener is triggered. The function can take up to four arguments in the following order:<br />
* '''changed''': a <code>props.Node</code> object pointing to the changed node.<br />
* '''listen''': a <code>props.Node</code> object pointing to the listened-to node. Note that this argument maybe different depending on the '''type'''.<br />
* '''mode''': an integer telling how the listener was triggered. 0 means that the value was changed. 1 means that a child property was added. -1 means that a child property was removed.<br />
* '''is_child''': boolean telling whether '''changed''' is a child property of the listened-to '''node''' or not. 1 (true) if it is, 0 (false) otherwise.<br />
|param3 = init<br />
|param3text = If set to 1 (true), the listener will additionally be triggered when it is created. This argument is optional and defaults to 0 (false).<br />
|param4 = type<br />
|param4text = Integer specifying the listener's behavior. 0 means that the listener will only trigger when the property is changed. 1 means that the trigger will always be triggered when the property is written to. 2 will mean that the listener will be triggered even if child properties are modified. This argument is optional and defaults to 1.<br />
|example1 = var prop = props.globals.initNode("/sim/test", "", "STRING"); # create property<br />
var id = setlistener("/sim/test", func(n){ # create listener<br />
print("Value: ", n.getValue());<br />
});<br />
setprop("/sim/test", "blah"); # trigger listener<br />
removelistener(id); # remove listener<br />
prop.remove(); # remove property<br />
}}<br />
<br />
===setprop()===<br />
{{Nasal doc<br />
|syntax = <nowiki>setprop(path[, path[, ...]], value);</nowiki><br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=385|t=Source}}<br />
|text = Sets the value of a property in the [[Property Tree]]. If the property does not exist, it will be created. Returns 1 (true) on success or 0 (false) if there was an error.<br />
{{note|If you want to remove a property, you will have to use one of the <code>props</code> helpers:<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 />
|param1 = path<br />
|param1text = There needs to be at least one '''path''' argument, but there is no limit to the maximum amount that can be given. They will be concatenated together to form a property tree path. The arguments must be strings, but in FlightGear v3.2 onwards, there also is support (added by {{flightgear commit|34ed79}}) for numeric arguments as indices. See example 2 below.<br />
|param2 = value<br />
|param2text = Value to write to the given property. Must be either a string or a number.<br />
|example1 = setprop("/sim/demo", "This is a demo");<br />
|example2text = Note that the example below will only work in FlightGear 3.2 and above.<br />
|example2 = for(var i = 0; i < 3; i += 1){<br />
setprop("/sim/demo", i, "Demo #" ~ i));<br />
}<br />
|example3text = Same as above, but is supported by all versions of FlightGear.<br />
|example3 = for(var i = 0; i < 3; i += 1){<br />
setprop("/sim/demo[" ~ i ~ "]", "Demo #" ~ i));<br />
<nowiki>}</nowiki><br />
}}<br />
====See also====<br />
{{note| If you have to read/write the same property multiple times (e.g. in an update loop), it is more efficient to use a node object: <br />
To get a Node rather than its value, use <code>props.globals.getNode()</code> - see [[Nasal_library/props]]. }}<br />
<br />
===settimer() ===<br />
{{Nasal doc<br />
|syntax = settimer(function, delta[, realtime]);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=499|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=1286|t=Part 2}}<br />
|text = Runs the given function a specified amount of seconds after the current time. Returns <code>'''nil'''</code>.<br />
{{note|Improper use of <code>settimer()</code> may cause resource leaks. It is also highly recommended that the newer {{func link|maketimer()}} should be used instead of this function.}} <br />
|param1 = function<br />
|param1text = Mandatory function that will be called. It may be necessary to enclose code in an anonymous function (see example).<br />
|param2 = delta<br />
|param2text = Mandatory amount of time in seconds after which the function will be called.<br />
|param3 = realtime<br />
|param3text = If 1 (true), "real time" will be used instead of "simulation time." Defaults to 0 (false). Note that if "simulation time" is used, the timer will not run while FlightGear is paused.<br />
|example1 = var myFunc = func(){<br />
print("Hello");<br />
}<br />
<br />
settimer(myFunc, 2); # runs myFunc after 2 seconds<br />
|example2 = var sqr = func(a){<br />
return a * a;<br />
}<br />
<br />
settimer(func(){<br />
print(sqr(2)); # will print 4 after 2 seconds<br />
}, 2);<br />
}}<br />
<br />
===srand() ===<br />
{{Nasal doc<br />
|syntax = srand();<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=559|t=Source}}<br />
|text = Makes the pseudorandom number generator (see {{func link|rand()}}) generate a new {{wikipedia|random seed|noicon=1}} based on time. Returns 0.<br />
}}<br />
===systime()===<br />
{{Nasal doc<br />
|syntax = systime();<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=770|t=Source}}<br />
|text = Returns the {{wikipedia|Unix time}} (seconds since since 00:00:00 UTC, 1/1/1970) as a floating point number with high resolution. This function is useful for benchmarking purposes (see example 2).<br />
{{note|1=High resolution timers under Windows can produce inaccurate or fixed sub-millisecond results.<ref>{{cite web|url=http://forum.flightgear.org/viewtopic.php?f=30&t=29259|title=Nasal: systime() ??!?|author=Necolatis|date=Apr 2nd, 2016}}</ref> This is due to the underlying {{func link|GetSystemTimeAsFileTime()|link=https://msdn.microsoft.com/en-us/library/windows/desktop/ms724397(v=vs.85).aspx}} API call, which depends on hardware availability of suitable high resolution timers. See also [https://msdn.microsoft.com/en-us/library/windows/desktop/dn553408(v=vs.85).aspx Acquiring high-resolution time stamps]}}<br />
|example1 = print("Unix time: ", systime()); # prints Unix time<br />
|example2 = var myFunc = func(){<br />
for(var i = 0; i <= 10; i += 1){<br />
print("Interation #", i);<br />
}<br />
}<br />
var t = systime(); # record time<br />
myFunc(); # run function<br />
var t2 = systime(); # record new time<br />
print("myFunc() took ", t2 - t, " seconds"); # print result<br />
}}<br />
<br />
===thisfunc()===<br />
{{Nasal doc<br />
|syntax = thisfunc();<br />
|source = {{fgdata file|Nasal/globals.nas|t=Source}}<br />
|text = Returns the function from which this function is called. This allows a function to reliably and safely call itself from within a closure.<br />
|example1 = var stringify_vec = func(input){<br />
if (typeof(input) == "scalar"){<br />
return sprintf("%s", input);<br />
} elsif (typeof(input) == "vector") {<br />
if (size(input) == 0) return "[]";<br />
var this = thisfunc();<br />
var buffer = "[";<br />
for(var i = 0; i < size(input); i += 1){<br />
buffer ~= this(input[i]);<br />
if (i == size(input) - 1) {<br />
buffer ~= "]";<br />
} else {<br />
buffer ~= ", ";<br />
}<br />
}<br />
return buffer;<br />
} else {<br />
die("stringify_vec(): Error! Invalid input. Must be a vector or scalar");<br />
}<br />
}<br />
<br />
var test_vec = ["a", "b", "c", 1, 2, 3];<br />
debug.dump(stringify_vec(test_vec)); # prints "[a, b, c, 1, 2, 3]"<br />
test_vec = [];<br />
debug.dump(stringify_vec(test_vec)); # prints "[]"<br />
test_vec = {};<br />
debug.dump(stringify_vec(test_vec)); # will throw an error<br />
}}<br />
<br />
===tileIndex() ===<br />
{{Nasal doc<br />
|syntax = tileIndex();<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1720|t=Source}}<br />
|text = Returns the index of the tile at the aircraft's current position as a string. This corresponds to the name of the STG file of the tile. For example, at [[KSFO]], this would be <code>942050</code>, corresponding to <tt>''[[$FG_SCENERY]]/Terrain/w130n30/w123n3/942050.stg''</tt>.<br />
|example1 = print(tileIndex()); # print index<br />
}}<br />
<br />
=== tilePath()===<br />
{{Nasal doc<br />
|syntax = tilePath();<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1712|t=Source}}<br />
|text = Returns the base path of the tile at the aircraft's current position as a string. For example, at KSFO, this would be <code>w130n30/w123n3</code>, corresponding to <tt>''[[$FG_SCENERY]]/Terrain/w130n30/w123n3''</tt>.<br />
|example1 = print(tilePath()); # print path<br />
}}<br />
<br />
=== values()===<br />
{{Nasal doc<br />
|syntax = values(hash);<br />
|source = {{fgdata file|Nasal/globals.nas|t=Source}}<br />
|text = Returns a vector containing the values of the given hash.<br />
|param1 = hash<br />
|param1text = Mandatory hash to get the values of.<br />
|example1 = var hash = {<br />
"a": 1,<br />
"b": 2,<br />
"c": 3<br />
};<br />
<br />
foreach(var val; values(hash)){<br />
print(val);<br />
}<br />
|example2text = The below example does exactly the same thing as the above example, but does not use <code>values()</code>:<br />
|example2 = var hash = {<br />
"a": 1,<br />
"b": 2,<br />
"c": 3<br />
};<br />
<br />
foreach(var key; keys(hash)){<br />
print(hash[key]);<br />
<nowiki>}</nowiki><br />
}}<br />
<br />
==Extension functions new in FG 2020.1 ==<br />
The following functions have been added to the nasal core library and will be released with FlightGear version 2020.1. <br />
Before the release they are available in the development branch "next".<br />
<br />
===isfunc()===<br />
Returns 1 if type or argument is a function, otherwise 0.<br />
<br />
===isghost()===<br />
Returns 1 if type or argument is a ghost, otherwise 0.<br />
<br />
=== ishash()===<br />
Returns 1 if type or argument is a hash, otherwise 0.<br />
<br />
===isint()===<br />
{{Nasal doc<br />
|syntax = isint(x);<br />
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}<br />
|text = Returns 1 if argument has a numeric value and x == floor(x), e.g. integer.<br />
}}<br />
<br />
===isnum()===<br />
{{Nasal doc<br />
|syntax = isnum(x);<br />
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}<br />
|text = Returns 1 if typeof(x) is "scalar" and x has a numeric value otherwise 0. <br />
}}<br />
<br />
===isscalar()===<br />
{{Nasal doc<br />
|syntax = isscalar(x);<br />
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}<br />
|text = Returns 1 if type or argument is a scalar (string or numeric), otherwise (vector, hash, func, ...) it returns 0. This is useful to check if a variable can be converted to string e.g. when useing the string concat operator "~". <br />
|example1 = var a = "foo"; <br />
var b=42;<br />
if (isscalar(a) and isscalar(b)) print(a~b);<br />
if (isstr(a)) print("a is a string");<br />
if (isint(b)) print("b is an integer");<br />
# if (isscalar(a))... is equivalent to if (typeof(a) == "scalar")...<br />
}}<br />
<br />
===isstr()===<br />
Returns 1 if type or argument is a string, otherwise 0. <br />
<br />
===isvec()===<br />
Returns 1 if type or argument is a vector, otherwise 0.<br />
<br />
===vecindex()===<br />
{{Nasal doc<br />
|syntax = vecindex(vector, value);<br />
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}<br />
|text = Returns the index of value or nil, if value is not found in vector.<br />
|example1=<br />
var myvector = ["apple", "bananna", "coconut"];<br />
# to check if a vector contains a certain value compare vecindex to nil<br />
if (vecindex(myvector, "apple") != nil) {<br />
print("found apple");<br />
}<br />
# WARNING: this will not work as desired because index is 0<br />
if (vecindex(myvector, "apple")) {<br />
print("found apple");<br />
<nowiki>}</nowiki><br />
<br />
}}<br />
<br />
==Variables==<br />
Various global constants (technically variables) are provided for use in converting between different units. They are all found in {{fgdata file|Nasal/globals.nas|text=$FG_ROOT/Nasal/globals.nas}}.<br />
<br />
===D2R===<br />
{{Nasal doc<br />
|syntax = var radians = degrees * D2R;<br />
|text = Converts an angle from degrees to radians when multiplied by the angle in degrees. Equal to <code>π / 180</code>.<br />
}}<br />
===FPS2KT===<br />
{{Nasal doc<br />
|syntax = var knots = feet_per_second * FPS2KT;<br />
|text = Converts a velocity from feet per second to knots when multiplied by the velocity in feet per second. Approximately equal to 0.5925.<br />
}}<br />
===FT2M===<br />
{{Nasal doc<br />
|syntax = var metres = feet * FT2M;<br />
|text = Converts a length from feet to metres when multiplied by the length in feet. Equal to 0.3048.<br />
}}<br />
===GAL2L ===<br />
{{Nasal doc<br />
|syntax = var litres = gallons * GAL2L;<br />
|text = Converts a volume from US liquid gallons to litres when multiplied by the volume in gallons. Approximately equal to 3.7854.<br />
}}<br />
===IN2M===<br />
{{Nasal doc<br />
|syntax = var metres = inches * IN2M;<br />
|text = Converts a length from inches to metres when multiplied by the length in inches. Equal to 0.0254.<br />
}}<br />
===KG2LB===<br />
{{Nasal doc<br />
|syntax = var pounds = kilograms * KG2LB;<br />
|text = Converts a mass from kilograms to pounds when multiplied by the mass in kilograms. Approximately equal to 2.2046.<br />
}}<br />
===KT2FPS===<br />
{{Nasal doc<br />
|syntax = var feet_per_second = knots * KT2FPS;<br />
|text = Converts a velocity from knots to feet per second when multiplied by the velocity in knots. Approximately equal to 1.6878.<br />
}}<br />
===KT2MPS===<br />
{{Nasal doc<br />
|syntax = var metres_per_second = knots * KT2MPS;<br />
|text = Converts a velocity from knots to metres per second when multiplied by the velocity in knots. Approximately equal to 0.5144.<br />
}}<br />
===L2GAL===<br />
{{Nasal doc<br />
|syntax = var gallons = litres * L2GAL;<br />
|text = Converts a volume from litres to US liquid gallons when multiplied by the volume in litres. Approximately equal to 0.2642.<br />
}}<br />
===LB2KG===<br />
{{Nasal doc<br />
|syntax = var kilograms = pounds * LB2KG;<br />
|text = Converts a mass from pounds to kilograms when multiplied by the mass in pounds. Approximately equal to 0.4536.<br />
}}<br />
===M2FT ===<br />
{{Nasal doc<br />
|syntax = var feet = metres * M2FT;<br />
|text = Converts a length from metres to feet when multiplied by the length in metres. Approximately equal to 3.2808.<br />
}}<br />
===M2IN===<br />
{{Nasal doc<br />
|syntax = var inches = metres * M2IN;<br />
|text = Converts a length from metres to inches when multiplied by the length in metres. Approximately equal to 39.3701.<br />
}}<br />
===M2NM ===<br />
{{Nasal doc<br />
|syntax = var nautical_miles = metres * M2NM;<br />
|text = Converts a length from metres to nautical miles when multiplied by the length in metres. Approximately equal to 0.00054.<br />
}}<br />
===MPS2KT ===<br />
{{Nasal doc<br />
|syntax = var knots = metres_per_second * MPS2KT;<br />
|text = Converts a velocity from metres per second to knots when multiplied by the velocity in metres per second. Approximately equal to 1.9438.<br />
}}<br />
===NM2M ===<br />
{{Nasal doc<br />
|syntax = var metres = nautical_miles * NM2M;<br />
|text = Converts a length from nautical miles to metres when multiplied by the length in nautical miles. Equal to 1,852.<br />
}}<br />
===R2D===<br />
{{Nasal doc<br />
|syntax = var degrees = radians * R2D;<br />
|text = Converts an angle from radians to degrees when multiplied by the angle in radians. Equal to <code>180 / π</code>.<br />
}}<br />
<br />
{{Appendix}}<br />
<br />
<br />
{{Nasal namespaces}}</div>Clm76https://wiki.flightgear.org/w/index.php?title=Nasal_library&diff=138673Nasal library2023-11-12T10:29:01Z<p>Clm76: </p>
<hr />
<div>{{Nasal Navigation|nocat=1}}<br />
This page documents the global '''library functions and variables''' 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, the ''[[#Extension functions|extension functions]]'', which have been subsequently added, and are specifically designed for FlightGear, and the ''[[#variables|global variables]]'', which are conversion variables, added with extension functions, for converting between units. The relevant folders in [[Git]] are:<br />
* {{flightgear file|src/Scripting}}<br />
* {{simgear file|simgear/nasal}}<br />
<br />
All these functions and variables are in the global namespace, that is, they are directly accessible (e.g., one can call <syntaxhighlight lang="nasal" inline>magvar()</syntaxhighlight> instead of <syntaxhighlight lang="nasal" inline>namespace.magvar()</syntaxhighlight>). However, if a namespace must be used, <code>globals</code> is the correct namespace, but using it is not recommended. For a more complete explanation, see [[Nasal Namespaces in-depth]].<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|printerror()|debug}}.<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.<br />
<br />
The result is a four-element vector containing '''[0]''' a hash of local variables, '''[1]''' the function object, '''[2]''' the full source file name (incl. path) and '''[3]''' the line number. <br />
|param1 = level<br />
|param1text = Optional integer specifying the stack level to return a result from. Defaults to 1 (i.e. 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 lang="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 />
<br />
===contains()===<br />
{{Requires commit|desc=Vector support|details=see {{Merge-request|project=fgdata|id=305}}|commit=ee39abbd3b70c9b6d5e3a1c4ccedddaac1a92b11|repo=Simgear}}<br />
{{Nasal doc<br />
|syntax = contains(vector, item);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=184|t=Source}}<br />
|text = Returns 1 (True) if the vector contains the specified item, or 0 (False) if not.<br />
|param1 = vector<br />
|param1text = The vector to search in.<br />
|param2 = item<br />
|param2text = The object to be searched for in the vector.<br />
|example1 =<br />
# Initialize a hash<br />
var vec = ["element", "foo"];<br />
print(contains(hash, "element") ? "Yes" : "No"); # This will print "Yes"<br />
|example2 =<br />
# Initialize a hash<br />
var vec = ["element", "foo"];<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 NOT identical to setting the hash value specified by the key to <code>'''nil'''</code> as the key will stay in the hash (at least for a while). 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 />
|commit = {{simgear commit|bd7163|t=commit}}<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 />
|commit = {{simgear commit|bd7163|t=commit}}<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()|link=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 />
|example2text = 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 />
|example3text = This example sorts a vector of strings (runways for example) from smallest to greatest.<br />
|example3 = <br />
var runways = ["09R","27R","26L","09L","15"];<br />
var rwy = sort(runways,func(a,b) cmp(a,b));<br />
debug.dump(rwy); # prints ['09L','09R','15','26L','27R']<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 = <nowiki>sprintf(format[, arg[, arg, [...]]]);</nowiki><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()|link=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. This includes the decimal point and decimal fraction as well as + or - signs.<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>s</code> {{!!}} A string<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 />
|example10 =<br />
print(sprintf("%.2f", 1.4)); #prints "1.40"<br />
print(sprintf("%.1f", 1.4)); #prints "1.4"<br />
print(sprintf("% 4.1f", 1.4)); #prints " 1.4"<br />
print(sprintf("%04.1f", 1.4)); #prints "01.4"<br />
print(sprintf("% 6.1f", 1.4)); #prints " 1.4"<br />
print(sprintf("%06.1f", 1.4)); #prints "0001.4"<br />
}}<br />
<br />
===streq()===<br />
{{Nasal doc<br />
|syntax = streq(a, b);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=129|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. Negative values specify a position from the end of the string.<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 />
|example4 = print(substr("abcde", -2)); # prints "de"<br />
|example5 = print(substr("abcde", -3, 2)); # prints "cd"<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 />
* Omitting the ''vector'' and ''start'' arguments is not an error (possibly it should be) but the return value is ''nil''.<br />
* A negative ''start'' argument ''is'' an error. This seems wrong. Perhaps the language designer could comment.<br />
* A value of ''start'' greater than ''size(vector)'' causes an error. A value equal to ''size(vector)'' returns an empty vector.<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 />
|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 modules ==<br />
=== thread ===<br />
{{WIP}}<br />
<br />
{{Nasal doc<br />
|syntax = thread.newthread(func);<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = start a new worker thread<br />
|example1 = thread.newthread( func() {} );<br />
}}<br />
<br />
{{Nasal doc<br />
|syntax = thread.newlock();<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = create a new lock<br />
|example1 = var lock = thread.newlock()<br />
}}<br />
<br />
{{Nasal doc<br />
|syntax = thread.lock();<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = lock a lock<br />
|example1 = var lock = thread.newlock()<br />
}}<br />
<br />
{{Nasal doc<br />
|syntax = thread.unlock();<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = unlock a lock<br />
|example1 = var lock = thread.unlock()<br />
}}<br />
<br />
<br />
{{Nasal doc<br />
|syntax = thread.newsem();<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = create a new {{Wikipedia|semaphore}}<br />
|example1 = var semaphore = thread.newsem()<br />
}}<br />
<br />
<br />
{{Nasal doc<br />
|syntax = thread.semdown();<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = semaphore down<br />
|example1 = thread.semdown(semaphore)<br />
}}<br />
<br />
<br />
{{Nasal doc<br />
|syntax = thread.semup();<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = semaphore up<br />
|example1 = thread.semup(semaphore)<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()|link=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 />
===aircraftToCart() ===<br />
This new function in FG 2017.2.1 takes coordinates in aircraft structural coordinate system, and translate them into geocentric coordinates.<br />
Example for (5,6,7):<br />
<syntaxhighlight lang="nasal"><br />
var pos = aircraftToCart({x: -5, y: 6, z: -7});<br />
var coord = geo.Coord.new();<br />
coord.set_xyz(pos.x, pos.y, pos.z);<br />
</syntaxhighlight><br />
Notice: x and z is inverted sign on purpose.<br />
if you want lat. lon, alt from that, just call: (degrees and meters)<br />
<br />
<syntaxhighlight lang="nasal"><br />
coord.lat()<br />
coord.lon()<br />
coord.alt()<br />
</syntaxhighlight><br />
<br />
===addcommand() ===<br />
{{Nasal doc<br />
|syntax = addcommand(name, code);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=659|t=Source}}<br />
|version = 2.12<br />
|commit = {{flightgear commit|7b663c|t=commit}}<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(node) {<br />
print("fgcommand 'myFGCmd' has been run.");<br />
props.dump( node );<br />
});<br />
fgcommand("myFGCmd", props.Node.new({foo:1, bar:2}) );<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 />
* '''parents''': A vector containing a hash of various functions to access information about the runway. See {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2659}} for full list.<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 />
*** '''id''': Name of runway.<br />
*** '''lat''': Latitude of the runway.<br />
*** '''lon''': Longitude of the runway.<br />
*** '''heading''': Heading of the runway.<br />
*** '''length''': Length of the runway in metres.<br />
*** '''width''': Width of the runway in metres.<br />
*** '''surface''': Runway surface type.<br />
*** '''threshold''': Length of the runway's {{wikipedia|displaced threshold}} in metres. Will return 0 if there is none.<br />
*** '''stopway''': Length of the runway's stopway (the area before the threshold) in metres. Will return 0 if there is none.<br />
*** '''reciprocal''': <code>runway</code> ghost of the reciprocal runway.<br />
*** '''ils_frequency_mhz''': ILS frequency in megahertz.<br />
*** '''ils''': <code>navaid</code> ghost of the ILS transmitter.<br />
* '''helipads'''<br />
** '''<helipad name>'''<br />
*** '''id''': Name of helipad.<br />
*** '''lat''': Latitude of the helipad.<br />
*** '''lon''': Longitude of the helipad.<br />
*** '''heading''': Heading of the helipad.<br />
*** '''length''': Length of the helipad in metres.<br />
*** '''width''': Width of the helipad in metres.<br />
*** '''surface''': Helipad surface type.<br />
* '''taxiways'''<br />
** '''<taxiway name>'''<br />
*** '''id''': Name of taxiway.<br />
*** '''lat''': Latitude of the taxiway.<br />
*** '''lon''': Longitude of the taxiway.<br />
*** '''heading''': Heading of the taxiway.<br />
*** '''length''': Length of the taxiway in metres.<br />
*** '''width''': Width of the taxiway in metres.<br />
*** '''surface''': Taxiway surface type.<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 />
<nowiki>}</nowiki><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 />
<nowiki>}</nowiki><br />
}}<br />
<br />
===airway()===<br />
<br />
{{Nasal doc<br />
|syntax = airway(ident [, pos]);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2644|t=Source}}<br />
|text = {{see also|Nasal Flightplan}}<br />
This function returns a ghost containing an airway of a specified id.<br />
|param1 = ident<br />
|param1text = a Positioned ghost (leg, navaid, airport) and so on, passed to the search function.<br />
|param2 = pos<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 />
|commit = {{fgdata commit|8b16a7|t=commit}}<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 with geodetic coordinates (cartesian coordinates will not be accepted)<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 />
===createFlightplan()===<br />
{{Nasal doc<br />
|syntax = createFlightplan(path);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2331|t=Source}}<br />
|text = Creates an empty flightplan object. It accepts one argument, ''path'' passed an absolute path to a .fgfp / .gpx file, it will populate the flightplan with waypoints from the file.<br />
|param1 = path<br />
|param1text = Optional parameter defining the file from which a flightplan will be populated.<br />
|example1 = <br />
var path = getprop("/sim/fg-home") ~ "/Export/test.fgfp";<br />
var flightplan = createFlightplan(path);<br />
debug.dump(flightplan);<br />
}}<br />
<br />
===createDiscontinuity()===<br />
{{Nasal doc<br />
|syntax = createDiscontinuity();<br />
|text = Returns a <code>waypoint</code> ghost object. A route discontinuity is inserted by an {{abbr|FMS|Flight Management System}} when it is unsure how to connect two waypoints.<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2045|t=Source}}<br />
|version = 2016.1<br />
|commit = {{flightgear commit|caead6|t=commit}}<br />
}}<br />
===createViaTo()===<br />
{{Nasal doc<br />
|syntax = createViaTo(airway, waypoint);<br />
|text = Returns a <code>waypoint</code> ghost object. It represents a route "via '''airway''' to '''waypoint'''".<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2009|t=Source}}<br />
|version = 2016.1<br />
|commit = {{flightgear commit|caead6|t=commit}}<br />
|param1 = airway<br />
|param1text = The name of an airway.<br />
|param2 = waypoint<br />
|param2text = Must be in the airway and one of:<br />
* The name of a waypoint.<br />
* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, or <code>fix</code> ghost object.<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 />
<nowiki>}</nowiki><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 />
<nowiki>}</nowiki><br />
}}<br />
<br />
===findCommByFrequencyMHz()===<br />
findCommByFrequencyMHz([pos, ]freq[, type]);<br />
[[sourceforge:p/flightgear/flightgear/ci/next/tree/src/Scripting/NasalPositioned.cxx#l1547|source]]<br />
<br />
Returns a <code>comm</code> ghost object for a station matching a given frequency. If there is more than one station with that frequency, the nearest station is returned.<br />
<br />
'''Pos'''<br />
<br />
: 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>findCommByFrequencyMHz(lat, lon, freq, type);</code>.<br />
; freq<br />
: Frequency, in megahertz, of the station to search for.<br />
; type<br />
: This will narrow the search to station of a certain type. Defaults to "all." For the full list of accepted type arguments, see flightgear/src/Navaids/positioned.cxx (line 160)<br />
'''Example'''<br />
var com = findCommByFrequencyMHz(123.6);<br />
print("ID: ", com.id); # prints info about the comm station<br />
print("Name: ", com.name);<br />
print("Latitude: ", com.lat);<br />
print("Longitude: ", com.lon);<br />
print("Type: ", com.type);<br />
print("Frequency: ", sprintf("%.3f", com.frequency), " Mhz");<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 />
===findNavaidByFrequencyMHz()===<br />
{{Nasal doc<br />
|syntax = findNavaidByFrequencyMHz([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>findNavaidByFrequencyMHz(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 = findNavaidByFrequencyMHz(109.55);<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 / 100), " Mhz");<br />
print("Range: ", navaid.range_nm, " nm");<br />
if(navaid.course) print("Course: ", navaid.course);<br />
}}<br />
<br />
=== findNavaidsByFrequencyMHz()===<br />
{{Nasal doc<br />
|syntax = findNavaidsByFrequencyMHz([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>findNavaidsByFrequencyMHz(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 = findNavaidsByFrequencyMHz(109.55);<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 / 100), " Mhz");<br />
print("Range: ", navaid.range_nm, " nm");<br />
if(navaid.course) print("Course: ", navaid.course);<br />
print("--");<br />
<nowiki>}</nowiki><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 />
<nowiki>}</nowiki><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 />
<nowiki>}</nowiki><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 />
<nowiki>}</nowiki><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 />
=== get_cart_ground_intersection()===<br />
Introduced in 2017.2.1, see [[Terrain Detection]].<br />
<br />
===getprop()===<br />
{{Nasal doc<br />
|syntax = <nowiki>getprop(path[, path[, ...]]);</nowiki><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 = path<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 also 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 versions 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 />
<nowiki>}</nowiki><br />
}}<br />
==== See also====<br />
{{note| If you have to read/write the same property multiple times (e.g. in an update loop), it is more efficient to use a node object: <br />
To get a Node rather than its value, use <code>props.globals.getNode()</code> - see [[Nasal_library/props]]. }}<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 = <nowiki>interpolate(prop, value1, time1[, value2, time2[, ...]]);</nowiki><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 />
<nowiki>}</nowiki><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 = <nowiki>logprint(priority[, msg[, msg[, ...]]]);</nowiki><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 from the Nasal file itself rather than from {{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 />
{{note| <br />
The following constants have been added to the development branch of FlightGear ("next") and will be releases with FG 2020.1 so you won't have to remember the numbers anymore:<br />
<br />
LOG_BULK, LOG_WARN, LOG_DEBUG, LOG_INFO, LOG_ALERT, DEV_WARN, DEV_ALERT }}<br />
<br />
===magvar() ===<br />
{{Nasal doc<br />
|syntax = magvar([pos]);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1642|t=Source}}<br />
|text = Returns the {{wikipedia|magnetic variation}} at a given set of coordinates. The table below gives the magnetic model used depending on the version of FlightGear.<br />
{{{!}} class="wikitable"<br />
! FlightGear versions !! Model !! Reference date<br />
{{!-}}<br />
{{!}} 3.6 and above {{!!}} {{wikipedia|World Magnetic Model}} (WMM) 2015 {{!!}} 1 January 2015<br />
{{!-}}<br />
{{!}} 0.9.11-pre1 to 3.4 {{!!}} WMM 2005 {{!!}} 1 January 2005<br />
{{!-}}<br />
{{!}} 0.7.3 to 0.9.10 {{!!}} WMM 2000 {{!!}} 1 January 2000<br />
{{!}}}<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>magvar(lat,lon)</code>.<br />
|example1 = print(magvar(0, 0)); # prints the magnetic variation at 0, 0<br />
}}<br />
<br />
===maketimer() ===<br />
{{Nasal doc<br />
|syntax = maketimer(interval[, self], function);<br />
|source = ''Implemented using the {{API Link|flightgear|class|TimerObj}} class.''<br>{{flightgear file|src/Scripting/NasalSys.cxx|l=90|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=533|t=Part 2}}<br />
|version = 2.12<br />
|commit = {{flightgear commit|ab939f|t=commit}}<br />
|text = Returns a timer object containing the following methods and members:<br />
* '''start()''': Starts the timer.<br />
* '''stop()''': Stops the timer.<br />
* '''restart(interval)''': Restarts the timer with the given interval.<br />
* '''singleShot''': Bool showing whether the timer is only to be run once, or continuously until told to stop. Can be both set and read from (see examples).<br />
* '''isRunning''': Read-only bool telling whether the timer is currently running.<br />
* '''simulatedTime''': (FG 2017.1+; {{flightgear commit|0af316|t=commit}}) Bool telling whether the timer is using simulated time (which accounts for pause, etc.). Defaults to false (use real time). Can be both read and set. This cannot be changed while the timer is running.<br />
Unlike {{func link|settimer()}}, which it replaces, <code>maketimer()</code> provides more control over the timer. In addition, it can help reduce memory usage.<br />
|param1 = interval<br />
|param1text = Interval in seconds for the timer.<br />
|param2 = self<br />
|param2text = Optional parameter specifying what any <code>'''me'''</code> references in the function being called will refer to.<br />
|param3 = function<br />
|param3text = Function to be called at the given interval.<br />
|example1 = var timer = maketimer(1, func(){<br />
print("Hello, World!"); # print "Hello, World!" once every second (call timer.stop() to stop it)<br />
});<br />
timer.start();<br />
|example2 = var timer = maketimer(1, math, func(){<br />
print(me.math); # 'me' reference is the 'math' namespace<br />
});<br />
timer.singleShot = 1; # timer will only be run once<br />
timer.start();<br />
|example3 = var timer = maketimer(1, func(){<br />
print("Hello, World!"); # print "Hello, World!" once every second (call timer.stop() to stop it)<br />
});<br />
timer.start();<br />
print(timer.isRunning); # prints 1<br />
|example4text = In the example below, "Hello, World!" will be printed after one second the first time, and after two seconds thereafter.<br />
|example4 = var update = func(){<br />
print("Hello, World!");<br />
timer.restart(2); # restarts the timer with a two second interval<br />
}<br />
<br />
var timer = maketimer(1, update);<br />
timer.singleShot = 1;<br />
timer.start();<br />
}}<br />
<br />
===maketimestamp()===<br />
{{Nasal doc<br />
|syntax = maketimestamp()<br />
|source = ''Implemented using the {{API Link|flightgear|class|TimeStampObj}} class.''<br>{{flightgear file|src/Scripting/NasalSys.cxx|l=214|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=589|t=Part 2}}<br />
|version = 2019.2<br />
|commit = {{flightgear commit|7db06300|t=commit}}<br />
|text = Returns a time stamp object to allow high resolution timing of Nasal operations. When created the timer will automatically be stamped. The object has the following methods:<br />
* '''stamp()''': Resets the timing operation. Call this first.<br />
* '''elapsedMSec()''': returns number of milliseconds elapsed since stamp() called. Resolution may vary depending on platform but is usually at least millisecond accuracy.<br />
* '''elapsedUSec()''': returns number of microseconds elapsed since stamp() called. Resolution may vary depending on platform but is usually at least millisecond accuracy.<br />
|<br />
|example1text = In the example below the number of milliseconds elapsed will be printed.<br />
|example1 = var timestamp = maketimestamp();<br />
timestamp.stamp();<br />
print(timestamp.elapsedMSec(), "ms elapsed");<br />
print(timestamp.elapsedMSec(), "ms elapsed");<br />
}}<br />
<br />
===md5()===<br />
{{Nasal doc<br />
|syntax = md5(string);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=758|t=Source}}<br />
|version = 3.2<br />
|commit = {{flightgear commit|cfbf9e|t=commit}}<br />
|text = Returns a the {{wikipedia|MD5}} hash (as a string) of the inputted string.<br />
|param1 = string<br />
|param1text = String the generate the hash of. Mandatory.<br />
|example1text = The below code should output <code>65a8e27d8879283831b664bd8b7f0ad4</code>.<br />
|example1 = print(md5("Hello, World!"));<br />
}}<br />
<br />
===navinfo()===<br />
{{Nasal doc<br />
|syntax = navinfo(lat, lon, type, id);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1453|t=Source}}<br />
|text = Returns vector <code>navaid</code> ghost objects matching the given '''type''' and '''id''' or <code>'''nil'''</code> on error.<br />
|param1 = lat ''and'' lon<br />
|param1text = If given, the returned navaids will be put into order of ascending distance from the location.<br />
|param2 = type<br />
|param2text = Narrows the search to the given type. Must be one of "any," "fix," "vor," "ndb," "ils," "dme," or "tacan." Defaults to the equivalent of "any."<br />
|param3 = id<br />
|param3text = ID to search for. Note that, although all the parameters are technically optional, this parameter must be given, otherwise an empty vector will be returned.<br />
|example1 = navinfo("vor"); # returns all VORs<br />
|example2 = navinfo("HAM"); # return all navaids whose names start with "HAM"<br />
|example3 = navinfo("vor", "HAM"); # return all VORs whose names start with "HAM"<br />
|example4 = navinfo(34,48,"vor","HAM"); # return all VORs whose names start with "HAM" and sorted by distance relative to 34°, 48°<br />
}}<br />
<br />
===parse_markdown()===<br />
{{Nasal doc<br />
|syntax = parse_markdown(markdown);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=745|t=Part 1}} {{!}} {{simgear file|simgear/misc/SimpleMarkdown.cxx|t=Part 2}} <br />
|version = 3.2<br />
|text = Parses a string containing {{wikipedia|Markdown}} and returns the result as a string. As of FlightGear 2016.1, it is just a simple parser, and does the following:<br />
* It strips whitespace from the beginning of the string.<br />
* It supports [http://daringfireball.net/projects/markdown/syntax#p paragraphs and line breaks].<br />
* It collapses whitespace.<br />
* It converts unordered [http://daringfireball.net/projects/markdown/syntax#list lists] to use a bullet character (&bull;). Note that the bullet character is implemented in hexadecimal UTF-8 character bytes (<code>E2 80 A2</code>), as so may not work properly when the being displayed in an encoding other than UTF-8.<br />
|param1 = markdown<br />
|param1text = String containing Markdown to be parsed.<br />
|example1text = <br />
Save the below code as <tt>''[[$FG_ROOT]]/gui/dialogs/test.xml''</tt>, then run the Nasal code below it to open the dialog. To change the markdown to be parsed, simply change the code in the highlighted section, save it, and reload the GUI (<tt>Debug > Reload GUI</tt>).<br />
<syntaxhighlight lang="xml" highlight="41-50"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<br />
<PropertyList><br />
<br />
<name>test</name><br />
<layout>vbox</layout><br />
<br />
<group><br />
<layout>hbox</layout><br />
<br />
<empty><br />
<stretch>true</stretch><br />
</empty><br />
<br />
<text><br />
<label>parse_markdown() test dialog</label><br />
</text><br />
<br />
<empty><br />
<stretch>true</stretch><br />
</empty><br />
<br />
<button><br />
<legend></legend><br />
<pref-width>16</pref-width><br />
<pref-height>16</pref-height><br />
<binding><br />
<command>dialog-close</command><br />
</binding><br />
</button><br />
<br />
</group><br />
<br />
<canvas><br />
<name>Canvas plot</name><br />
<stretch>true</stretch><br />
<pref-width>400</pref-width><br />
<pref-height>300</pref-height><br />
<nasal><br />
<load><![CDATA[<br />
var text = 'Items:<br />
* apples<br />
* oranges<br />
* pears<br />
<br />
Some text.<br />
Some more items:<br />
* apples<br />
* oranges<br />
* pears';<br />
<br />
var parsed = parse_markdown(text);<br />
<br />
var root_canvas = canvas.get(cmdarg());<br />
root_canvas.setColorBackground(255, 255, 255);<br />
var root = root_canvas.createGroup();<br />
<br />
var text_dis = root.createChild("text")<br />
.setText(parsed)<br />
.setTranslation(5, 5)<br />
.setFont("LiberationFonts\LiberationSans-Regular.ttf")<br />
.setFontSize(15)<br />
.setColor(0, 0, 0)<br />
.setDrawMode(canvas.Text.TEXT)<br />
.setAlignment("left-top");<br />
]]></load><br />
</nasal><br />
</canvas><br />
<br />
</PropertyList><br />
</syntaxhighlight><br />
|example1 = fgcommand("dialog-show", {"dialog-name": "test"});<br />
|example2text = The example below parses Markdown and outputs it in a HTML document. The parsed text is placed in <syntaxhighlight lang="xml" inline><pre></pre></syntaxhighlight> tags. To change the Markdown to be parsed, simply edit the variable <tt>markdown</tt> at the top of the code.<br />
|example2 = <nowiki>var markdown = 'Items:<br />
* apples<br />
* oranges<br />
* pears<br />
<br />
Some text.<br />
Some more items:<br />
* apples<br />
* oranges<br />
* pears';<br />
<br />
var parsed = parse_markdown(markdown);<br />
<br />
debug.dump(parsed);<br />
<br />
var path = string.normpath(getprop("/sim/fg-home") ~ '/Export/parse_markdown()-test.html');<br />
<br />
var file = io.open(path, "w");<br />
<br />
var html = "<!DOCTYPE html>\n\n<html>\n\n<head>\n\t<meta charset=\"UTF-8\">\n\t<title>parse_markdown() test generated by Nasal</title>\n</head>\n\n<body>\n\t<pre>" ~ parsed ~ "</pre>\n</body>\n\n</html>";<br />
<br />
io.write(file, html);<br />
io.close(file);<br />
print("Done, file ready for viewing (" ~ path ~ ")");</nowiki><br />
}}<br />
<br />
===parsexml()===<br />
{{Nasal doc<br />
|syntax = <nowiki>parsexml(path[, start[, end[, data[, pro_ins]]]]);</nowiki><br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=710|t=Source}}<br />
|text = This function is an interface into the built-in [http://expat.sourceforge.net/ Expat XML parser]. The absolute path to the file is returned as string, or <code>'''nil'''</code> is returned on error.<br />
|param1 = path<br />
|param1text = Mandatory absolute path to the XML file to be parsed.<br />
|param2 = start<br />
|param2text = Optional callback function that will be called for every starting tag. The function should take two argument: the tag name and a hash containing attributes.<br />
|param3 = end<br />
|param3text = Optional callback function that will be called for every ending tag. The function should take one argument: the tag name.<br />
|param4 = data<br />
|param4text = Optional callback function that will be called for every piece of data within a set of tags. The function should take one argument: the data as a string.<br />
|param5 = pro_ins<br />
|param5text = Optional callback function that will be called for every {{wikipedia|Processing Instruction|processing instruction}}. The function should take two argument: the target and the data string.<br />
|example1text = Save the below XML code in <tt>''[[$FG_HOME]]/Export/demo.xml''</tt>. Then, execute the Nasal code below in the Nasal Console. The XML will be parsed and each bit of the code will be printed.<br />
<syntaxhighlight lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<br />
<?xml-stylesheet type="text/xsl" href="style.xsl"?><br />
<br />
<foo><br />
<blah type="string"><![CDATA[ <sender>John Smith</sender> ]]></blah><br />
<blah2 type="string">Orange &amp; lemons</blah2><br />
</foo><br />
</syntaxhighlight><br />
|example1 = 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 />
}<br />
<br />
var end = func(name){<br />
print("Ending tag: '", name, "'");<br />
}<br />
<br />
var data = func(data){<br />
print("Data = '", data, "'");<br />
}<br />
<br />
var pro_instr = func(target, data){<br />
print("Processing instruction: target = '", target, "', data = '", data, "'");<br />
}<br />
<br />
parsexml(getprop("/sim/fg-home") ~ '/Export/demo.xml', start, end, data, pro_instr);<br />
}}<br />
<br />
===print()===<br />
{{Note|As of 07/2020, we are in the process of slowly deprecating and removing Nasal print() (in fgdata) where possible in favor of log [[#logprint()]] which takes a priority level.<br />
<br />
This is part of the goal that we achieve zero output at log-level at alert, and everything shown at ‘warn; is really a warning, not just information.<ref>https://sourceforge.net/p/flightgear/mailman/message/37042224/</ref>}}<br />
<br />
{{Nasal doc<br />
|syntax = <nowiki>print(data[, data[, ...]]);</nowiki><br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=415|t=Source}}<br />
|text = Concatenates its arguments and then prints it to the terminal and the [[Commonly used debugging tools#fgfs.log|log]]. Note that a newline is automatically added.<br />
|param1 = data<br />
|param1text = Data to print. Only strings and numbers can be printed; other data types will not be. There many be any number of arguments; they will just be concatenated together.<br />
|example1 = print("Just", " a ", "test"); # prints "Just a test"<br />
|example2 = print("pi = ", math.pi); # prints "pi = 3.141592..."<br />
}}<br />
<br />
=== printf() ===<br />
{{Nasal doc<br />
|syntax = <nowiki>printf(format[, arg[, arg, [...]]]);</nowiki><br />
|source = {{fgdata file|Nasal/globals.nas|t=Source}}<br />
|text = Creates and prints a formatted string. For a description of its arguments, see {{func link|sprintf()}} (it is, in fact, implemented using <code>sprintf()</code>).<br />
|example1 = printf("In hexadecimal, 100000 = %X", 186A0); # prints "In hexadecimal, 100000 = 186A0"<br />
}}<br />
<br />
===printlog()===<br />
{{Nasal doc<br />
|syntax = <nowiki>printlog(level, data[, data[, ...]]);</nowiki><br />
|source = {{fgdata file|Nasal/globals.nas|t=Source}}<br />
|text = Prints the given message with the given log level. If the log level is higher or equal to <code>/sim/logging/priority</code>, it is printed.<br />
|param1 = level<br />
|param1text = Mandatory log level as a string. Must be one of "none," "bulk," "debug," "info," "warn," or "alert." Note that "none" will mean that the message will never be printed.<br />
|param2 = data<br />
|param2text = Data to be printed. Only strings and numbers will be printed; others will not be. There may be any number of arguments; they will just be concatenated together.<br />
|example1 = printlog("alert", "This is an alert"); # message will be printed<br />
|example2 = printlog("info", "Just informing you about something"); # message will be printed only if log level is set to "info" or less<br />
}}<br />
<br />
===rand()===<br />
{{Nasal doc<br />
|syntax = rand();<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=554|t=Source}}<br />
|text = Returns a random floating point number between 0 (inclusive) and 1 (exclusive). It takes no arguments.<br />
|example1 = print(rand()); # prints random number<br />
}}<br />
<br />
===registerFlightPlanDelegate()===<br />
{{Nasal doc<br />
|syntax = registerFlightPlanDelegate(init_func);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1879|t=Source}}<br />
|text = Registers a flight plan delegate. See <tt>''{{fgdata file|Nasal/route_manager.nas|t=$FG_ROOT/Nasal/route_manager.nas}}''</tt> for examples.<br />
|param1 = init_func<br />
|param1text = Initialization function which will be called during FlightGear's startup.<br />
}}<br />
===removecommand()===<br />
{{Nasal doc<br />
|syntax = removecommand(cmd);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=668|t=Source}}<br />
|text = Removes the given fgcommand. Returns <code>'''nil'''</code>.<br />
{{caution|This will remove '''any''' [[fgcommands|fgcommand]], even those implemented in C++, so use with caution!}}<br />
|param1 = cmd<br />
|param1text = String specifying the name of the command to remove.<br />
|example1 = addcommand("hello", func(){<br />
print("Hello");<br />
});<br />
fgcommand("hello"); # "Hello" will be printed<br />
removecommand("hello"); # removes it<br />
}}<br />
<br />
===removelistener()===<br />
{{Nasal doc<br />
|syntax = removelistener(id);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=1384|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=506|t=Part 2}}<br />
|text = Removes and deactivates the given listener and returns the number of listeners left or <code>'''nil'''</code> on error.<br />
{{note|It is good practice to remove listeners when they are not required anymore. This prevents the listeners reducing FlightGear's run performance.}}<br />
|param1 = id<br />
|param1text = ID of listener as returned by {{func link|setlistener()}}.<br />
|example1 = var ls = setlistener("/sim/test", func(){<br />
print("Property '/sim/test' has been changed");<br />
});<br />
setprop("/sim/test", "blah"); # trigger listener<br />
var rem = removelistener(ls); # remove listener<br />
print("There are ", rem, " listeners remaining");<br />
}}<br />
<br />
===resolvepath()===<br />
{{Nasal doc<br />
|syntax = resolvepath(path);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=604|t=Source}}<br />
|text = Takes a relative path as a string and uses [[SimGear]]'s path-resolving framework to return an absolute path as a string. If the path could not be resolved, an empty string is returned. See [[Resolving Paths]] for a detailed description of the algorithm. This function can also be used to check if a file exists.<br />
|param1 = path<br />
|param1text = Relative path to be completed.<br />
|example1 = print(resolvepath("Nasal/globals.nas")); # prints the equivalent of $FG_ROOT/Nasal/globals.nas<br />
|example2 = print(resolvepath("blah")); # prints nothing; could not be resolved<br />
|example3 = var file_path = resolvepath("Aircraft/SenecaII/some-file");<br />
if (file_path != ""){<br />
gui.popupTip("some-file found", 2);<br />
} else {<br />
gui.popupTip("some-file not found", 2);<br />
<nowiki>}</nowiki><br />
}}<br />
<br />
===setlistener()===<br />
{{Nasal doc<br />
|syntax = <nowiki>setlistener(node, code[, init[, type]]);</nowiki><br />
|private = _setlistener()<br />
|source = {{flightgear file|src/Scripting/Nasal|l=499|t=Part 1}} {{!}} {{flightgear file|src/Scripting/Nasal|l=1350|t=Part 2}}<br>''Listener implemented using the {{API Link|flightgear|class|FGNasalListener}} class.''<br />
|text = Creates a listener which will be triggered when the given property is changed (depending on the '''type'''). A unique integer ID is returned; this can later be used as the argument to {{func link|removelistener()}}.<br />
{{note|Listeners are known to be a source of resource leaks. To avoid this, please take measures such as:<br />
* Using {{func link|removelistener()}} when they are not needed any more.<br />
* Using a single initialization listener.<br />
* Avoiding tying listeners to properties that are rapidly updated (e.g., many times per frame).<br />
}}<br />
|param1 = node<br />
|param1text = Mandatory string or <code>props.Node</code> object pointing to a property in the [[Property Tree]].<br />
|param2 = code<br />
|param2text = Mandatory callback function to execute when the listener is triggered. The function can take up to four arguments in the following order:<br />
* '''changed''': a <code>props.Node</code> object pointing to the changed node.<br />
* '''listen''': a <code>props.Node</code> object pointing to the listened-to node. Note that this argument maybe different depending on the '''type'''.<br />
* '''mode''': an integer telling how the listener was triggered. 0 means that the value was changed. 1 means that a child property was added. -1 means that a child property was removed.<br />
* '''is_child''': boolean telling whether '''changed''' is a child property of the listened-to '''node''' or not. 1 (true) if it is, 0 (false) otherwise.<br />
|param3 = init<br />
|param3text = If set to 1 (true), the listener will additionally be triggered when it is created. This argument is optional and defaults to 0 (false).<br />
|param4 = type<br />
|param4text = Integer specifying the listener's behavior. 0 means that the listener will only trigger when the property is changed. 1 means that the trigger will always be triggered when the property is written to. 2 will mean that the listener will be triggered even if child properties are modified. This argument is optional and defaults to 1.<br />
|example1 = var prop = props.globals.initNode("/sim/test", "", "STRING"); # create property<br />
var id = setlistener("/sim/test", func(n){ # create listener<br />
print("Value: ", n.getValue());<br />
});<br />
setprop("/sim/test", "blah"); # trigger listener<br />
removelistener(id); # remove listener<br />
prop.remove(); # remove property<br />
}}<br />
<br />
===setprop()===<br />
{{Nasal doc<br />
|syntax = <nowiki>setprop(path[, path[, ...]], value);</nowiki><br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=385|t=Source}}<br />
|text = Sets the value of a property in the [[Property Tree]]. If the property does not exist, it will be created. Returns 1 (true) on success or 0 (false) if there was an error.<br />
{{note|If you want to remove a property, you will have to use one of the <code>props</code> helpers:<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 />
|param1 = path<br />
|param1text = There needs to be at least one '''path''' argument, but there is no limit to the maximum amount that can be given. They will be concatenated together to form a property tree path. The arguments must be strings, but in FlightGear v3.2 onwards, there also is support (added by {{flightgear commit|34ed79}}) for numeric arguments as indices. See example 2 below.<br />
|param2 = value<br />
|param2text = Value to write to the given property. Must be either a string or a number.<br />
|example1 = setprop("/sim/demo", "This is a demo");<br />
|example2text = Note that the example below will only work in FlightGear 3.2 and above.<br />
|example2 = for(var i = 0; i < 3; i += 1){<br />
setprop("/sim/demo", i, "Demo #" ~ i));<br />
}<br />
|example3text = Same as above, but is supported by all versions of FlightGear.<br />
|example3 = for(var i = 0; i < 3; i += 1){<br />
setprop("/sim/demo[" ~ i ~ "]", "Demo #" ~ i));<br />
<nowiki>}</nowiki><br />
}}<br />
====See also====<br />
{{note| If you have to read/write the same property multiple times (e.g. in an update loop), it is more efficient to use a node object: <br />
To get a Node rather than its value, use <code>props.globals.getNode()</code> - see [[Nasal_library/props]]. }}<br />
<br />
===settimer() ===<br />
{{Nasal doc<br />
|syntax = settimer(function, delta[, realtime]);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=499|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=1286|t=Part 2}}<br />
|text = Runs the given function a specified amount of seconds after the current time. Returns <code>'''nil'''</code>.<br />
{{note|Improper use of <code>settimer()</code> may cause resource leaks. It is also highly recommended that the newer {{func link|maketimer()}} should be used instead of this function.}} <br />
|param1 = function<br />
|param1text = Mandatory function that will be called. It may be necessary to enclose code in an anonymous function (see example).<br />
|param2 = delta<br />
|param2text = Mandatory amount of time in seconds after which the function will be called.<br />
|param3 = realtime<br />
|param3text = If 1 (true), "real time" will be used instead of "simulation time." Defaults to 0 (false). Note that if "simulation time" is used, the timer will not run while FlightGear is paused.<br />
|example1 = var myFunc = func(){<br />
print("Hello");<br />
}<br />
<br />
settimer(myFunc, 2); # runs myFunc after 2 seconds<br />
|example2 = var sqr = func(a){<br />
return a * a;<br />
}<br />
<br />
settimer(func(){<br />
print(sqr(2)); # will print 4 after 2 seconds<br />
}, 2);<br />
}}<br />
<br />
===srand() ===<br />
{{Nasal doc<br />
|syntax = srand();<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=559|t=Source}}<br />
|text = Makes the pseudorandom number generator (see {{func link|rand()}}) generate a new {{wikipedia|random seed|noicon=1}} based on time. Returns 0.<br />
}}<br />
===systime()===<br />
{{Nasal doc<br />
|syntax = systime();<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=770|t=Source}}<br />
|text = Returns the {{wikipedia|Unix time}} (seconds since since 00:00:00 UTC, 1/1/1970) as a floating point number with high resolution. This function is useful for benchmarking purposes (see example 2).<br />
{{note|1=High resolution timers under Windows can produce inaccurate or fixed sub-millisecond results.<ref>{{cite web|url=http://forum.flightgear.org/viewtopic.php?f=30&t=29259|title=Nasal: systime() ??!?|author=Necolatis|date=Apr 2nd, 2016}}</ref> This is due to the underlying {{func link|GetSystemTimeAsFileTime()|link=https://msdn.microsoft.com/en-us/library/windows/desktop/ms724397(v=vs.85).aspx}} API call, which depends on hardware availability of suitable high resolution timers. See also [https://msdn.microsoft.com/en-us/library/windows/desktop/dn553408(v=vs.85).aspx Acquiring high-resolution time stamps]}}<br />
|example1 = print("Unix time: ", systime()); # prints Unix time<br />
|example2 = var myFunc = func(){<br />
for(var i = 0; i <= 10; i += 1){<br />
print("Interation #", i);<br />
}<br />
}<br />
var t = systime(); # record time<br />
myFunc(); # run function<br />
var t2 = systime(); # record new time<br />
print("myFunc() took ", t2 - t, " seconds"); # print result<br />
}}<br />
<br />
===thisfunc()===<br />
{{Nasal doc<br />
|syntax = thisfunc();<br />
|source = {{fgdata file|Nasal/globals.nas|t=Source}}<br />
|text = Returns the function from which this function is called. This allows a function to reliably and safely call itself from within a closure.<br />
|example1 = var stringify_vec = func(input){<br />
if (typeof(input) == "scalar"){<br />
return sprintf("%s", input);<br />
} elsif (typeof(input) == "vector") {<br />
if (size(input) == 0) return "[]";<br />
var this = thisfunc();<br />
var buffer = "[";<br />
for(var i = 0; i < size(input); i += 1){<br />
buffer ~= this(input[i]);<br />
if (i == size(input) - 1) {<br />
buffer ~= "]";<br />
} else {<br />
buffer ~= ", ";<br />
}<br />
}<br />
return buffer;<br />
} else {<br />
die("stringify_vec(): Error! Invalid input. Must be a vector or scalar");<br />
}<br />
}<br />
<br />
var test_vec = ["a", "b", "c", 1, 2, 3];<br />
debug.dump(stringify_vec(test_vec)); # prints "[a, b, c, 1, 2, 3]"<br />
test_vec = [];<br />
debug.dump(stringify_vec(test_vec)); # prints "[]"<br />
test_vec = {};<br />
debug.dump(stringify_vec(test_vec)); # will throw an error<br />
}}<br />
<br />
===tileIndex() ===<br />
{{Nasal doc<br />
|syntax = tileIndex();<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1720|t=Source}}<br />
|text = Returns the index of the tile at the aircraft's current position as a string. This corresponds to the name of the STG file of the tile. For example, at [[KSFO]], this would be <code>942050</code>, corresponding to <tt>''[[$FG_SCENERY]]/Terrain/w130n30/w123n3/942050.stg''</tt>.<br />
|example1 = print(tileIndex()); # print index<br />
}}<br />
<br />
=== tilePath()===<br />
{{Nasal doc<br />
|syntax = tilePath();<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1712|t=Source}}<br />
|text = Returns the base path of the tile at the aircraft's current position as a string. For example, at KSFO, this would be <code>w130n30/w123n3</code>, corresponding to <tt>''[[$FG_SCENERY]]/Terrain/w130n30/w123n3''</tt>.<br />
|example1 = print(tilePath()); # print path<br />
}}<br />
<br />
=== values()===<br />
{{Nasal doc<br />
|syntax = values(hash);<br />
|source = {{fgdata file|Nasal/globals.nas|t=Source}}<br />
|text = Returns a vector containing the values of the given hash.<br />
|param1 = hash<br />
|param1text = Mandatory hash to get the values of.<br />
|example1 = var hash = {<br />
"a": 1,<br />
"b": 2,<br />
"c": 3<br />
};<br />
<br />
foreach(var val; values(hash)){<br />
print(val);<br />
}<br />
|example2text = The below example does exactly the same thing as the above example, but does not use <code>values()</code>:<br />
|example2 = var hash = {<br />
"a": 1,<br />
"b": 2,<br />
"c": 3<br />
};<br />
<br />
foreach(var key; keys(hash)){<br />
print(hash[key]);<br />
<nowiki>}</nowiki><br />
}}<br />
<br />
==Extension functions new in FG 2020.1 ==<br />
The following functions have been added to the nasal core library and will be released with FlightGear version 2020.1. <br />
Before the release they are available in the development branch "next".<br />
<br />
===isfunc()===<br />
Returns 1 if type or argument is a function, otherwise 0.<br />
<br />
===isghost()===<br />
Returns 1 if type or argument is a ghost, otherwise 0.<br />
<br />
=== ishash()===<br />
Returns 1 if type or argument is a hash, otherwise 0.<br />
<br />
===isint()===<br />
{{Nasal doc<br />
|syntax = isint(x);<br />
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}<br />
|text = Returns 1 if argument has a numeric value and x == floor(x), e.g. integer.<br />
}}<br />
<br />
===isnum()===<br />
{{Nasal doc<br />
|syntax = isnum(x);<br />
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}<br />
|text = Returns 1 if typeof(x) is "scalar" and x has a numeric value otherwise 0. <br />
}}<br />
<br />
===isscalar()===<br />
{{Nasal doc<br />
|syntax = isscalar(x);<br />
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}<br />
|text = Returns 1 if type or argument is a scalar (string or numeric), otherwise (vector, hash, func, ...) it returns 0. This is useful to check if a variable can be converted to string e.g. when useing the string concat operator "~". <br />
|example1 = var a = "foo"; <br />
var b=42;<br />
if (isscalar(a) and isscalar(b)) print(a~b);<br />
if (isstr(a)) print("a is a string");<br />
if (isint(b)) print("b is an integer");<br />
# if (isscalar(a))... is equivalent to if (typeof(a) == "scalar")...<br />
}}<br />
<br />
===isstr()===<br />
Returns 1 if type or argument is a string, otherwise 0. <br />
<br />
===isvec()===<br />
Returns 1 if type or argument is a vector, otherwise 0.<br />
<br />
===vecindex()===<br />
{{Nasal doc<br />
|syntax = vecindex(vector, value);<br />
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}<br />
|text = Returns the index of value or nil, if value is not found in vector.<br />
|example1=<br />
var myvector = ["apple", "bananna", "coconut"];<br />
# to check if a vector contains a certain value compare vecindex to nil<br />
if (vecindex(myvector, "apple") != nil) {<br />
print("found apple");<br />
}<br />
# WARNING: this will not work as desired because index is 0<br />
if (vecindex(myvector, "apple")) {<br />
print("found apple");<br />
<nowiki>}</nowiki><br />
<br />
}}<br />
<br />
==Variables==<br />
Various global constants (technically variables) are provided for use in converting between different units. They are all found in {{fgdata file|Nasal/globals.nas|text=$FG_ROOT/Nasal/globals.nas}}.<br />
<br />
===D2R===<br />
{{Nasal doc<br />
|syntax = var radians = degrees * D2R;<br />
|text = Converts an angle from degrees to radians when multiplied by the angle in degrees. Equal to <code>π / 180</code>.<br />
}}<br />
===FPS2KT===<br />
{{Nasal doc<br />
|syntax = var knots = feet_per_second * FPS2KT;<br />
|text = Converts a velocity from feet per second to knots when multiplied by the velocity in feet per second. Approximately equal to 0.5925.<br />
}}<br />
===FT2M===<br />
{{Nasal doc<br />
|syntax = var metres = feet * FT2M;<br />
|text = Converts a length from feet to metres when multiplied by the length in feet. Equal to 0.3048.<br />
}}<br />
===GAL2L ===<br />
{{Nasal doc<br />
|syntax = var litres = gallons * GAL2L;<br />
|text = Converts a volume from US liquid gallons to litres when multiplied by the volume in gallons. Approximately equal to 3.7854.<br />
}}<br />
===IN2M===<br />
{{Nasal doc<br />
|syntax = var metres = inches * IN2M;<br />
|text = Converts a length from inches to metres when multiplied by the length in inches. Equal to 0.0254.<br />
}}<br />
===KG2LB===<br />
{{Nasal doc<br />
|syntax = var pounds = kilograms * KG2LB;<br />
|text = Converts a mass from kilograms to pounds when multiplied by the mass in kilograms. Approximately equal to 2.2046.<br />
}}<br />
===KT2FPS===<br />
{{Nasal doc<br />
|syntax = var feet_per_second = knots * KT2FPS;<br />
|text = Converts a velocity from knots to feet per second when multiplied by the velocity in knots. Approximately equal to 1.6878.<br />
}}<br />
===KT2MPS===<br />
{{Nasal doc<br />
|syntax = var metres_per_second = knots * KT2MPS;<br />
|text = Converts a velocity from knots to metres per second when multiplied by the velocity in knots. Approximately equal to 0.5144.<br />
}}<br />
===L2GAL===<br />
{{Nasal doc<br />
|syntax = var gallons = litres * L2GAL;<br />
|text = Converts a volume from litres to US liquid gallons when multiplied by the volume in litres. Approximately equal to 0.2642.<br />
}}<br />
===LB2KG===<br />
{{Nasal doc<br />
|syntax = var kilograms = pounds * LB2KG;<br />
|text = Converts a mass from pounds to kilograms when multiplied by the mass in pounds. Approximately equal to 0.4536.<br />
}}<br />
===M2FT ===<br />
{{Nasal doc<br />
|syntax = var feet = metres * M2FT;<br />
|text = Converts a length from metres to feet when multiplied by the length in metres. Approximately equal to 3.2808.<br />
}}<br />
===M2IN===<br />
{{Nasal doc<br />
|syntax = var inches = metres * M2IN;<br />
|text = Converts a length from metres to inches when multiplied by the length in metres. Approximately equal to 39.3701.<br />
}}<br />
===M2NM ===<br />
{{Nasal doc<br />
|syntax = var nautical_miles = metres * M2NM;<br />
|text = Converts a length from metres to nautical miles when multiplied by the length in metres. Approximately equal to 0.00054.<br />
}}<br />
===MPS2KT ===<br />
{{Nasal doc<br />
|syntax = var knots = metres_per_second * MPS2KT;<br />
|text = Converts a velocity from metres per second to knots when multiplied by the velocity in metres per second. Approximately equal to 1.9438.<br />
}}<br />
===NM2M ===<br />
{{Nasal doc<br />
|syntax = var metres = nautical_miles * NM2M;<br />
|text = Converts a length from nautical miles to metres when multiplied by the length in nautical miles. Equal to 1,852.<br />
}}<br />
===R2D===<br />
{{Nasal doc<br />
|syntax = var degrees = radians * R2D;<br />
|text = Converts an angle from radians to degrees when multiplied by the angle in radians. Equal to <code>180 / π</code>.<br />
}}<br />
<br />
{{Appendix}}<br />
<br />
<br />
{{Nasal namespaces}}</div>Clm76https://wiki.flightgear.org/w/index.php?title=Nasal_library&diff=138672Nasal library2023-11-12T10:18:36Z<p>Clm76: Add findCommByFrequencyMHz()</p>
<hr />
<div>{{Nasal Navigation|nocat=1}}<br />
This page documents the global '''library functions and variables''' 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, the ''[[#Extension functions|extension functions]]'', which have been subsequently added, and are specifically designed for FlightGear, and the ''[[#variables|global variables]]'', which are conversion variables, added with extension functions, for converting between units. The relevant folders in [[Git]] are:<br />
* {{flightgear file|src/Scripting}}<br />
* {{simgear file|simgear/nasal}}<br />
<br />
All these functions and variables are in the global namespace, that is, they are directly accessible (e.g., one can call <syntaxhighlight lang="nasal" inline>magvar()</syntaxhighlight> instead of <syntaxhighlight lang="nasal" inline>namespace.magvar()</syntaxhighlight>). However, if a namespace must be used, <code>globals</code> is the correct namespace, but using it is not recommended. For a more complete explanation, see [[Nasal Namespaces in-depth]].<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|printerror()|debug}}.<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.<br />
<br />
The result is a four-element vector containing '''[0]''' a hash of local variables, '''[1]''' the function object, '''[2]''' the full source file name (incl. path) and '''[3]''' the line number. <br />
|param1 = level<br />
|param1text = Optional integer specifying the stack level to return a result from. Defaults to 1 (i.e. 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 lang="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 />
<br />
===contains()===<br />
{{Requires commit|desc=Vector support|details=see {{Merge-request|project=fgdata|id=305}}|commit=ee39abbd3b70c9b6d5e3a1c4ccedddaac1a92b11|repo=Simgear}}<br />
{{Nasal doc<br />
|syntax = contains(vector, item);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=184|t=Source}}<br />
|text = Returns 1 (True) if the vector contains the specified item, or 0 (False) if not.<br />
|param1 = vector<br />
|param1text = The vector to search in.<br />
|param2 = item<br />
|param2text = The object to be searched for in the vector.<br />
|example1 =<br />
# Initialize a hash<br />
var vec = ["element", "foo"];<br />
print(contains(hash, "element") ? "Yes" : "No"); # This will print "Yes"<br />
|example2 =<br />
# Initialize a hash<br />
var vec = ["element", "foo"];<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 NOT identical to setting the hash value specified by the key to <code>'''nil'''</code> as the key will stay in the hash (at least for a while). 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 />
|commit = {{simgear commit|bd7163|t=commit}}<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 />
|commit = {{simgear commit|bd7163|t=commit}}<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()|link=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 />
|example2text = 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 />
|example3text = This example sorts a vector of strings (runways for example) from smallest to greatest.<br />
|example3 = <br />
var runways = ["09R","27R","26L","09L","15"];<br />
var rwy = sort(runways,func(a,b) cmp(a,b));<br />
debug.dump(rwy); # prints ['09L','09R','15','26L','27R']<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 = <nowiki>sprintf(format[, arg[, arg, [...]]]);</nowiki><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()|link=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. This includes the decimal point and decimal fraction as well as + or - signs.<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>s</code> {{!!}} A string<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 />
|example10 =<br />
print(sprintf("%.2f", 1.4)); #prints "1.40"<br />
print(sprintf("%.1f", 1.4)); #prints "1.4"<br />
print(sprintf("% 4.1f", 1.4)); #prints " 1.4"<br />
print(sprintf("%04.1f", 1.4)); #prints "01.4"<br />
print(sprintf("% 6.1f", 1.4)); #prints " 1.4"<br />
print(sprintf("%06.1f", 1.4)); #prints "0001.4"<br />
}}<br />
<br />
===streq()===<br />
{{Nasal doc<br />
|syntax = streq(a, b);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=129|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. Negative values specify a position from the end of the string.<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 />
|example4 = print(substr("abcde", -2)); # prints "de"<br />
|example5 = print(substr("abcde", -3, 2)); # prints "cd"<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 />
* Omitting the ''vector'' and ''start'' arguments is not an error (possibly it should be) but the return value is ''nil''.<br />
* A negative ''start'' argument ''is'' an error. This seems wrong. Perhaps the language designer could comment.<br />
* A value of ''start'' greater than ''size(vector)'' causes an error. A value equal to ''size(vector)'' returns an empty vector.<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 />
|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 modules ==<br />
=== thread ===<br />
{{WIP}}<br />
<br />
{{Nasal doc<br />
|syntax = thread.newthread(func);<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = start a new worker thread<br />
|example1 = thread.newthread( func() {} );<br />
}}<br />
<br />
{{Nasal doc<br />
|syntax = thread.newlock();<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = create a new lock<br />
|example1 = var lock = thread.newlock()<br />
}}<br />
<br />
{{Nasal doc<br />
|syntax = thread.lock();<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = lock a lock<br />
|example1 = var lock = thread.newlock()<br />
}}<br />
<br />
{{Nasal doc<br />
|syntax = thread.unlock();<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = unlock a lock<br />
|example1 = var lock = thread.unlock()<br />
}}<br />
<br />
<br />
{{Nasal doc<br />
|syntax = thread.newsem();<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = create a new {{Wikipedia|semaphore}}<br />
|example1 = var semaphore = thread.newsem()<br />
}}<br />
<br />
<br />
{{Nasal doc<br />
|syntax = thread.semdown();<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = semaphore down<br />
|example1 = thread.semdown(semaphore)<br />
}}<br />
<br />
<br />
{{Nasal doc<br />
|syntax = thread.semup();<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = semaphore up<br />
|example1 = thread.semup(semaphore)<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()|link=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 />
===aircraftToCart() ===<br />
This new function in FG 2017.2.1 takes coordinates in aircraft structural coordinate system, and translate them into geocentric coordinates.<br />
Example for (5,6,7):<br />
<syntaxhighlight lang="nasal"><br />
var pos = aircraftToCart({x: -5, y: 6, z: -7});<br />
var coord = geo.Coord.new();<br />
coord.set_xyz(pos.x, pos.y, pos.z);<br />
</syntaxhighlight><br />
Notice: x and z is inverted sign on purpose.<br />
if you want lat. lon, alt from that, just call: (degrees and meters)<br />
<br />
<syntaxhighlight lang="nasal"><br />
coord.lat()<br />
coord.lon()<br />
coord.alt()<br />
</syntaxhighlight><br />
<br />
===addcommand() ===<br />
{{Nasal doc<br />
|syntax = addcommand(name, code);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=659|t=Source}}<br />
|version = 2.12<br />
|commit = {{flightgear commit|7b663c|t=commit}}<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(node) {<br />
print("fgcommand 'myFGCmd' has been run.");<br />
props.dump( node );<br />
});<br />
fgcommand("myFGCmd", props.Node.new({foo:1, bar:2}) );<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 />
* '''parents''': A vector containing a hash of various functions to access information about the runway. See {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2659}} for full list.<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 />
*** '''id''': Name of runway.<br />
*** '''lat''': Latitude of the runway.<br />
*** '''lon''': Longitude of the runway.<br />
*** '''heading''': Heading of the runway.<br />
*** '''length''': Length of the runway in metres.<br />
*** '''width''': Width of the runway in metres.<br />
*** '''surface''': Runway surface type.<br />
*** '''threshold''': Length of the runway's {{wikipedia|displaced threshold}} in metres. Will return 0 if there is none.<br />
*** '''stopway''': Length of the runway's stopway (the area before the threshold) in metres. Will return 0 if there is none.<br />
*** '''reciprocal''': <code>runway</code> ghost of the reciprocal runway.<br />
*** '''ils_frequency_mhz''': ILS frequency in megahertz.<br />
*** '''ils''': <code>navaid</code> ghost of the ILS transmitter.<br />
* '''helipads'''<br />
** '''<helipad name>'''<br />
*** '''id''': Name of helipad.<br />
*** '''lat''': Latitude of the helipad.<br />
*** '''lon''': Longitude of the helipad.<br />
*** '''heading''': Heading of the helipad.<br />
*** '''length''': Length of the helipad in metres.<br />
*** '''width''': Width of the helipad in metres.<br />
*** '''surface''': Helipad surface type.<br />
* '''taxiways'''<br />
** '''<taxiway name>'''<br />
*** '''id''': Name of taxiway.<br />
*** '''lat''': Latitude of the taxiway.<br />
*** '''lon''': Longitude of the taxiway.<br />
*** '''heading''': Heading of the taxiway.<br />
*** '''length''': Length of the taxiway in metres.<br />
*** '''width''': Width of the taxiway in metres.<br />
*** '''surface''': Taxiway surface type.<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 />
<nowiki>}</nowiki><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 />
<nowiki>}</nowiki><br />
}}<br />
<br />
===airway()===<br />
<br />
{{Nasal doc<br />
|syntax = airway(ident [, pos]);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2644|t=Source}}<br />
|text = {{see also|Nasal Flightplan}}<br />
This function returns a ghost containing an airway of a specified id.<br />
|param1 = ident<br />
|param1text = a Positioned ghost (leg, navaid, airport) and so on, passed to the search function.<br />
|param2 = pos<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 />
|commit = {{fgdata commit|8b16a7|t=commit}}<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 with geodetic coordinates (cartesian coordinates will not be accepted)<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 />
===createFlightplan()===<br />
{{Nasal doc<br />
|syntax = createFlightplan(path);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2331|t=Source}}<br />
|text = Creates an empty flightplan object. It accepts one argument, ''path'' passed an absolute path to a .fgfp / .gpx file, it will populate the flightplan with waypoints from the file.<br />
|param1 = path<br />
|param1text = Optional parameter defining the file from which a flightplan will be populated.<br />
|example1 = <br />
var path = getprop("/sim/fg-home") ~ "/Export/test.fgfp";<br />
var flightplan = createFlightplan(path);<br />
debug.dump(flightplan);<br />
}}<br />
<br />
===createDiscontinuity()===<br />
{{Nasal doc<br />
|syntax = createDiscontinuity();<br />
|text = Returns a <code>waypoint</code> ghost object. A route discontinuity is inserted by an {{abbr|FMS|Flight Management System}} when it is unsure how to connect two waypoints.<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2045|t=Source}}<br />
|version = 2016.1<br />
|commit = {{flightgear commit|caead6|t=commit}}<br />
}}<br />
===createViaTo()===<br />
{{Nasal doc<br />
|syntax = createViaTo(airway, waypoint);<br />
|text = Returns a <code>waypoint</code> ghost object. It represents a route "via '''airway''' to '''waypoint'''".<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2009|t=Source}}<br />
|version = 2016.1<br />
|commit = {{flightgear commit|caead6|t=commit}}<br />
|param1 = airway<br />
|param1text = The name of an airway.<br />
|param2 = waypoint<br />
|param2text = Must be in the airway and one of:<br />
* The name of a waypoint.<br />
* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, or <code>fix</code> ghost object.<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 />
<nowiki>}</nowiki><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 />
<nowiki>}</nowiki><br />
}}<br />
<br />
===findCommByFrequencyMHz()===<br />
findCommByFrequencyMHz([pos, ]freq[, type]);<br />
[[sourceforge:p/flightgear/flightgear/ci/next/tree/src/Scripting/NasalPositioned.cxx#l1547|source]]<br />
<br />
Returns a <code>comm</code> ghost object for a station matching a given frequency. If there is more than one station with that frequency, the nearest station is returned.<br />
pos<br />
<br />
: 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>findCommByFrequencyMHz(lat, lon, freq, type);</code>.<br />
; freq<br />
: Frequency, in megahertz, of the station to search for.<br />
; type<br />
: This will narrow the search to station of a certain type. Defaults to "all." For the full list of accepted type arguments, see flightgear/src/Navaids/positioned.cxx (line 160)<br />
'''Example'''<br />
var com = findCommByFrequencyMHz(123.6);<br />
print("ID: ", com.id); # prints info about the comm station<br />
print("Name: ", com.name);<br />
print("Latitude: ", com.lat);<br />
print("Longitude: ", com.lon);<br />
print("Type: ", com.type);<br />
print("Frequency: ", sprintf("%.3f", com.frequency), " Mhz");<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 />
===findNavaidByFrequencyMHz()===<br />
{{Nasal doc<br />
|syntax = findNavaidByFrequencyMHz([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>findNavaidByFrequencyMHz(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 = findNavaidByFrequencyMHz(109.55);<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 / 100), " Mhz");<br />
print("Range: ", navaid.range_nm, " nm");<br />
if(navaid.course) print("Course: ", navaid.course);<br />
}}<br />
<br />
=== findNavaidsByFrequencyMHz()===<br />
{{Nasal doc<br />
|syntax = findNavaidsByFrequencyMHz([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>findNavaidsByFrequencyMHz(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 = findNavaidsByFrequencyMHz(109.55);<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 / 100), " Mhz");<br />
print("Range: ", navaid.range_nm, " nm");<br />
if(navaid.course) print("Course: ", navaid.course);<br />
print("--");<br />
<nowiki>}</nowiki><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 />
<nowiki>}</nowiki><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 />
<nowiki>}</nowiki><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 />
<nowiki>}</nowiki><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 />
=== get_cart_ground_intersection()===<br />
Introduced in 2017.2.1, see [[Terrain Detection]].<br />
<br />
===getprop()===<br />
{{Nasal doc<br />
|syntax = <nowiki>getprop(path[, path[, ...]]);</nowiki><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 = path<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 also 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 versions 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 />
<nowiki>}</nowiki><br />
}}<br />
==== See also====<br />
{{note| If you have to read/write the same property multiple times (e.g. in an update loop), it is more efficient to use a node object: <br />
To get a Node rather than its value, use <code>props.globals.getNode()</code> - see [[Nasal_library/props]]. }}<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 = <nowiki>interpolate(prop, value1, time1[, value2, time2[, ...]]);</nowiki><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 />
<nowiki>}</nowiki><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 = <nowiki>logprint(priority[, msg[, msg[, ...]]]);</nowiki><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 from the Nasal file itself rather than from {{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 />
{{note| <br />
The following constants have been added to the development branch of FlightGear ("next") and will be releases with FG 2020.1 so you won't have to remember the numbers anymore:<br />
<br />
LOG_BULK, LOG_WARN, LOG_DEBUG, LOG_INFO, LOG_ALERT, DEV_WARN, DEV_ALERT }}<br />
<br />
===magvar() ===<br />
{{Nasal doc<br />
|syntax = magvar([pos]);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1642|t=Source}}<br />
|text = Returns the {{wikipedia|magnetic variation}} at a given set of coordinates. The table below gives the magnetic model used depending on the version of FlightGear.<br />
{{{!}} class="wikitable"<br />
! FlightGear versions !! Model !! Reference date<br />
{{!-}}<br />
{{!}} 3.6 and above {{!!}} {{wikipedia|World Magnetic Model}} (WMM) 2015 {{!!}} 1 January 2015<br />
{{!-}}<br />
{{!}} 0.9.11-pre1 to 3.4 {{!!}} WMM 2005 {{!!}} 1 January 2005<br />
{{!-}}<br />
{{!}} 0.7.3 to 0.9.10 {{!!}} WMM 2000 {{!!}} 1 January 2000<br />
{{!}}}<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>magvar(lat,lon)</code>.<br />
|example1 = print(magvar(0, 0)); # prints the magnetic variation at 0, 0<br />
}}<br />
<br />
===maketimer() ===<br />
{{Nasal doc<br />
|syntax = maketimer(interval[, self], function);<br />
|source = ''Implemented using the {{API Link|flightgear|class|TimerObj}} class.''<br>{{flightgear file|src/Scripting/NasalSys.cxx|l=90|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=533|t=Part 2}}<br />
|version = 2.12<br />
|commit = {{flightgear commit|ab939f|t=commit}}<br />
|text = Returns a timer object containing the following methods and members:<br />
* '''start()''': Starts the timer.<br />
* '''stop()''': Stops the timer.<br />
* '''restart(interval)''': Restarts the timer with the given interval.<br />
* '''singleShot''': Bool showing whether the timer is only to be run once, or continuously until told to stop. Can be both set and read from (see examples).<br />
* '''isRunning''': Read-only bool telling whether the timer is currently running.<br />
* '''simulatedTime''': (FG 2017.1+; {{flightgear commit|0af316|t=commit}}) Bool telling whether the timer is using simulated time (which accounts for pause, etc.). Defaults to false (use real time). Can be both read and set. This cannot be changed while the timer is running.<br />
Unlike {{func link|settimer()}}, which it replaces, <code>maketimer()</code> provides more control over the timer. In addition, it can help reduce memory usage.<br />
|param1 = interval<br />
|param1text = Interval in seconds for the timer.<br />
|param2 = self<br />
|param2text = Optional parameter specifying what any <code>'''me'''</code> references in the function being called will refer to.<br />
|param3 = function<br />
|param3text = Function to be called at the given interval.<br />
|example1 = var timer = maketimer(1, func(){<br />
print("Hello, World!"); # print "Hello, World!" once every second (call timer.stop() to stop it)<br />
});<br />
timer.start();<br />
|example2 = var timer = maketimer(1, math, func(){<br />
print(me.math); # 'me' reference is the 'math' namespace<br />
});<br />
timer.singleShot = 1; # timer will only be run once<br />
timer.start();<br />
|example3 = var timer = maketimer(1, func(){<br />
print("Hello, World!"); # print "Hello, World!" once every second (call timer.stop() to stop it)<br />
});<br />
timer.start();<br />
print(timer.isRunning); # prints 1<br />
|example4text = In the example below, "Hello, World!" will be printed after one second the first time, and after two seconds thereafter.<br />
|example4 = var update = func(){<br />
print("Hello, World!");<br />
timer.restart(2); # restarts the timer with a two second interval<br />
}<br />
<br />
var timer = maketimer(1, update);<br />
timer.singleShot = 1;<br />
timer.start();<br />
}}<br />
<br />
===maketimestamp()===<br />
{{Nasal doc<br />
|syntax = maketimestamp()<br />
|source = ''Implemented using the {{API Link|flightgear|class|TimeStampObj}} class.''<br>{{flightgear file|src/Scripting/NasalSys.cxx|l=214|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=589|t=Part 2}}<br />
|version = 2019.2<br />
|commit = {{flightgear commit|7db06300|t=commit}}<br />
|text = Returns a time stamp object to allow high resolution timing of Nasal operations. When created the timer will automatically be stamped. The object has the following methods:<br />
* '''stamp()''': Resets the timing operation. Call this first.<br />
* '''elapsedMSec()''': returns number of milliseconds elapsed since stamp() called. Resolution may vary depending on platform but is usually at least millisecond accuracy.<br />
* '''elapsedUSec()''': returns number of microseconds elapsed since stamp() called. Resolution may vary depending on platform but is usually at least millisecond accuracy.<br />
|<br />
|example1text = In the example below the number of milliseconds elapsed will be printed.<br />
|example1 = var timestamp = maketimestamp();<br />
timestamp.stamp();<br />
print(timestamp.elapsedMSec(), "ms elapsed");<br />
print(timestamp.elapsedMSec(), "ms elapsed");<br />
}}<br />
<br />
===md5()===<br />
{{Nasal doc<br />
|syntax = md5(string);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=758|t=Source}}<br />
|version = 3.2<br />
|commit = {{flightgear commit|cfbf9e|t=commit}}<br />
|text = Returns a the {{wikipedia|MD5}} hash (as a string) of the inputted string.<br />
|param1 = string<br />
|param1text = String the generate the hash of. Mandatory.<br />
|example1text = The below code should output <code>65a8e27d8879283831b664bd8b7f0ad4</code>.<br />
|example1 = print(md5("Hello, World!"));<br />
}}<br />
<br />
===navinfo()===<br />
{{Nasal doc<br />
|syntax = navinfo(lat, lon, type, id);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1453|t=Source}}<br />
|text = Returns vector <code>navaid</code> ghost objects matching the given '''type''' and '''id''' or <code>'''nil'''</code> on error.<br />
|param1 = lat ''and'' lon<br />
|param1text = If given, the returned navaids will be put into order of ascending distance from the location.<br />
|param2 = type<br />
|param2text = Narrows the search to the given type. Must be one of "any," "fix," "vor," "ndb," "ils," "dme," or "tacan." Defaults to the equivalent of "any."<br />
|param3 = id<br />
|param3text = ID to search for. Note that, although all the parameters are technically optional, this parameter must be given, otherwise an empty vector will be returned.<br />
|example1 = navinfo("vor"); # returns all VORs<br />
|example2 = navinfo("HAM"); # return all navaids whose names start with "HAM"<br />
|example3 = navinfo("vor", "HAM"); # return all VORs whose names start with "HAM"<br />
|example4 = navinfo(34,48,"vor","HAM"); # return all VORs whose names start with "HAM" and sorted by distance relative to 34°, 48°<br />
}}<br />
<br />
===parse_markdown()===<br />
{{Nasal doc<br />
|syntax = parse_markdown(markdown);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=745|t=Part 1}} {{!}} {{simgear file|simgear/misc/SimpleMarkdown.cxx|t=Part 2}} <br />
|version = 3.2<br />
|text = Parses a string containing {{wikipedia|Markdown}} and returns the result as a string. As of FlightGear 2016.1, it is just a simple parser, and does the following:<br />
* It strips whitespace from the beginning of the string.<br />
* It supports [http://daringfireball.net/projects/markdown/syntax#p paragraphs and line breaks].<br />
* It collapses whitespace.<br />
* It converts unordered [http://daringfireball.net/projects/markdown/syntax#list lists] to use a bullet character (&bull;). Note that the bullet character is implemented in hexadecimal UTF-8 character bytes (<code>E2 80 A2</code>), as so may not work properly when the being displayed in an encoding other than UTF-8.<br />
|param1 = markdown<br />
|param1text = String containing Markdown to be parsed.<br />
|example1text = <br />
Save the below code as <tt>''[[$FG_ROOT]]/gui/dialogs/test.xml''</tt>, then run the Nasal code below it to open the dialog. To change the markdown to be parsed, simply change the code in the highlighted section, save it, and reload the GUI (<tt>Debug > Reload GUI</tt>).<br />
<syntaxhighlight lang="xml" highlight="41-50"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<br />
<PropertyList><br />
<br />
<name>test</name><br />
<layout>vbox</layout><br />
<br />
<group><br />
<layout>hbox</layout><br />
<br />
<empty><br />
<stretch>true</stretch><br />
</empty><br />
<br />
<text><br />
<label>parse_markdown() test dialog</label><br />
</text><br />
<br />
<empty><br />
<stretch>true</stretch><br />
</empty><br />
<br />
<button><br />
<legend></legend><br />
<pref-width>16</pref-width><br />
<pref-height>16</pref-height><br />
<binding><br />
<command>dialog-close</command><br />
</binding><br />
</button><br />
<br />
</group><br />
<br />
<canvas><br />
<name>Canvas plot</name><br />
<stretch>true</stretch><br />
<pref-width>400</pref-width><br />
<pref-height>300</pref-height><br />
<nasal><br />
<load><![CDATA[<br />
var text = 'Items:<br />
* apples<br />
* oranges<br />
* pears<br />
<br />
Some text.<br />
Some more items:<br />
* apples<br />
* oranges<br />
* pears';<br />
<br />
var parsed = parse_markdown(text);<br />
<br />
var root_canvas = canvas.get(cmdarg());<br />
root_canvas.setColorBackground(255, 255, 255);<br />
var root = root_canvas.createGroup();<br />
<br />
var text_dis = root.createChild("text")<br />
.setText(parsed)<br />
.setTranslation(5, 5)<br />
.setFont("LiberationFonts\LiberationSans-Regular.ttf")<br />
.setFontSize(15)<br />
.setColor(0, 0, 0)<br />
.setDrawMode(canvas.Text.TEXT)<br />
.setAlignment("left-top");<br />
]]></load><br />
</nasal><br />
</canvas><br />
<br />
</PropertyList><br />
</syntaxhighlight><br />
|example1 = fgcommand("dialog-show", {"dialog-name": "test"});<br />
|example2text = The example below parses Markdown and outputs it in a HTML document. The parsed text is placed in <syntaxhighlight lang="xml" inline><pre></pre></syntaxhighlight> tags. To change the Markdown to be parsed, simply edit the variable <tt>markdown</tt> at the top of the code.<br />
|example2 = <nowiki>var markdown = 'Items:<br />
* apples<br />
* oranges<br />
* pears<br />
<br />
Some text.<br />
Some more items:<br />
* apples<br />
* oranges<br />
* pears';<br />
<br />
var parsed = parse_markdown(markdown);<br />
<br />
debug.dump(parsed);<br />
<br />
var path = string.normpath(getprop("/sim/fg-home") ~ '/Export/parse_markdown()-test.html');<br />
<br />
var file = io.open(path, "w");<br />
<br />
var html = "<!DOCTYPE html>\n\n<html>\n\n<head>\n\t<meta charset=\"UTF-8\">\n\t<title>parse_markdown() test generated by Nasal</title>\n</head>\n\n<body>\n\t<pre>" ~ parsed ~ "</pre>\n</body>\n\n</html>";<br />
<br />
io.write(file, html);<br />
io.close(file);<br />
print("Done, file ready for viewing (" ~ path ~ ")");</nowiki><br />
}}<br />
<br />
===parsexml()===<br />
{{Nasal doc<br />
|syntax = <nowiki>parsexml(path[, start[, end[, data[, pro_ins]]]]);</nowiki><br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=710|t=Source}}<br />
|text = This function is an interface into the built-in [http://expat.sourceforge.net/ Expat XML parser]. The absolute path to the file is returned as string, or <code>'''nil'''</code> is returned on error.<br />
|param1 = path<br />
|param1text = Mandatory absolute path to the XML file to be parsed.<br />
|param2 = start<br />
|param2text = Optional callback function that will be called for every starting tag. The function should take two argument: the tag name and a hash containing attributes.<br />
|param3 = end<br />
|param3text = Optional callback function that will be called for every ending tag. The function should take one argument: the tag name.<br />
|param4 = data<br />
|param4text = Optional callback function that will be called for every piece of data within a set of tags. The function should take one argument: the data as a string.<br />
|param5 = pro_ins<br />
|param5text = Optional callback function that will be called for every {{wikipedia|Processing Instruction|processing instruction}}. The function should take two argument: the target and the data string.<br />
|example1text = Save the below XML code in <tt>''[[$FG_HOME]]/Export/demo.xml''</tt>. Then, execute the Nasal code below in the Nasal Console. The XML will be parsed and each bit of the code will be printed.<br />
<syntaxhighlight lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<br />
<?xml-stylesheet type="text/xsl" href="style.xsl"?><br />
<br />
<foo><br />
<blah type="string"><![CDATA[ <sender>John Smith</sender> ]]></blah><br />
<blah2 type="string">Orange &amp; lemons</blah2><br />
</foo><br />
</syntaxhighlight><br />
|example1 = 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 />
}<br />
<br />
var end = func(name){<br />
print("Ending tag: '", name, "'");<br />
}<br />
<br />
var data = func(data){<br />
print("Data = '", data, "'");<br />
}<br />
<br />
var pro_instr = func(target, data){<br />
print("Processing instruction: target = '", target, "', data = '", data, "'");<br />
}<br />
<br />
parsexml(getprop("/sim/fg-home") ~ '/Export/demo.xml', start, end, data, pro_instr);<br />
}}<br />
<br />
===print()===<br />
{{Note|As of 07/2020, we are in the process of slowly deprecating and removing Nasal print() (in fgdata) where possible in favor of log [[#logprint()]] which takes a priority level.<br />
<br />
This is part of the goal that we achieve zero output at log-level at alert, and everything shown at ‘warn; is really a warning, not just information.<ref>https://sourceforge.net/p/flightgear/mailman/message/37042224/</ref>}}<br />
<br />
{{Nasal doc<br />
|syntax = <nowiki>print(data[, data[, ...]]);</nowiki><br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=415|t=Source}}<br />
|text = Concatenates its arguments and then prints it to the terminal and the [[Commonly used debugging tools#fgfs.log|log]]. Note that a newline is automatically added.<br />
|param1 = data<br />
|param1text = Data to print. Only strings and numbers can be printed; other data types will not be. There many be any number of arguments; they will just be concatenated together.<br />
|example1 = print("Just", " a ", "test"); # prints "Just a test"<br />
|example2 = print("pi = ", math.pi); # prints "pi = 3.141592..."<br />
}}<br />
<br />
=== printf() ===<br />
{{Nasal doc<br />
|syntax = <nowiki>printf(format[, arg[, arg, [...]]]);</nowiki><br />
|source = {{fgdata file|Nasal/globals.nas|t=Source}}<br />
|text = Creates and prints a formatted string. For a description of its arguments, see {{func link|sprintf()}} (it is, in fact, implemented using <code>sprintf()</code>).<br />
|example1 = printf("In hexadecimal, 100000 = %X", 186A0); # prints "In hexadecimal, 100000 = 186A0"<br />
}}<br />
<br />
===printlog()===<br />
{{Nasal doc<br />
|syntax = <nowiki>printlog(level, data[, data[, ...]]);</nowiki><br />
|source = {{fgdata file|Nasal/globals.nas|t=Source}}<br />
|text = Prints the given message with the given log level. If the log level is higher or equal to <code>/sim/logging/priority</code>, it is printed.<br />
|param1 = level<br />
|param1text = Mandatory log level as a string. Must be one of "none," "bulk," "debug," "info," "warn," or "alert." Note that "none" will mean that the message will never be printed.<br />
|param2 = data<br />
|param2text = Data to be printed. Only strings and numbers will be printed; others will not be. There may be any number of arguments; they will just be concatenated together.<br />
|example1 = printlog("alert", "This is an alert"); # message will be printed<br />
|example2 = printlog("info", "Just informing you about something"); # message will be printed only if log level is set to "info" or less<br />
}}<br />
<br />
===rand()===<br />
{{Nasal doc<br />
|syntax = rand();<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=554|t=Source}}<br />
|text = Returns a random floating point number between 0 (inclusive) and 1 (exclusive). It takes no arguments.<br />
|example1 = print(rand()); # prints random number<br />
}}<br />
<br />
===registerFlightPlanDelegate()===<br />
{{Nasal doc<br />
|syntax = registerFlightPlanDelegate(init_func);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1879|t=Source}}<br />
|text = Registers a flight plan delegate. See <tt>''{{fgdata file|Nasal/route_manager.nas|t=$FG_ROOT/Nasal/route_manager.nas}}''</tt> for examples.<br />
|param1 = init_func<br />
|param1text = Initialization function which will be called during FlightGear's startup.<br />
}}<br />
===removecommand()===<br />
{{Nasal doc<br />
|syntax = removecommand(cmd);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=668|t=Source}}<br />
|text = Removes the given fgcommand. Returns <code>'''nil'''</code>.<br />
{{caution|This will remove '''any''' [[fgcommands|fgcommand]], even those implemented in C++, so use with caution!}}<br />
|param1 = cmd<br />
|param1text = String specifying the name of the command to remove.<br />
|example1 = addcommand("hello", func(){<br />
print("Hello");<br />
});<br />
fgcommand("hello"); # "Hello" will be printed<br />
removecommand("hello"); # removes it<br />
}}<br />
<br />
===removelistener()===<br />
{{Nasal doc<br />
|syntax = removelistener(id);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=1384|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=506|t=Part 2}}<br />
|text = Removes and deactivates the given listener and returns the number of listeners left or <code>'''nil'''</code> on error.<br />
{{note|It is good practice to remove listeners when they are not required anymore. This prevents the listeners reducing FlightGear's run performance.}}<br />
|param1 = id<br />
|param1text = ID of listener as returned by {{func link|setlistener()}}.<br />
|example1 = var ls = setlistener("/sim/test", func(){<br />
print("Property '/sim/test' has been changed");<br />
});<br />
setprop("/sim/test", "blah"); # trigger listener<br />
var rem = removelistener(ls); # remove listener<br />
print("There are ", rem, " listeners remaining");<br />
}}<br />
<br />
===resolvepath()===<br />
{{Nasal doc<br />
|syntax = resolvepath(path);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=604|t=Source}}<br />
|text = Takes a relative path as a string and uses [[SimGear]]'s path-resolving framework to return an absolute path as a string. If the path could not be resolved, an empty string is returned. See [[Resolving Paths]] for a detailed description of the algorithm. This function can also be used to check if a file exists.<br />
|param1 = path<br />
|param1text = Relative path to be completed.<br />
|example1 = print(resolvepath("Nasal/globals.nas")); # prints the equivalent of $FG_ROOT/Nasal/globals.nas<br />
|example2 = print(resolvepath("blah")); # prints nothing; could not be resolved<br />
|example3 = var file_path = resolvepath("Aircraft/SenecaII/some-file");<br />
if (file_path != ""){<br />
gui.popupTip("some-file found", 2);<br />
} else {<br />
gui.popupTip("some-file not found", 2);<br />
<nowiki>}</nowiki><br />
}}<br />
<br />
===setlistener()===<br />
{{Nasal doc<br />
|syntax = <nowiki>setlistener(node, code[, init[, type]]);</nowiki><br />
|private = _setlistener()<br />
|source = {{flightgear file|src/Scripting/Nasal|l=499|t=Part 1}} {{!}} {{flightgear file|src/Scripting/Nasal|l=1350|t=Part 2}}<br>''Listener implemented using the {{API Link|flightgear|class|FGNasalListener}} class.''<br />
|text = Creates a listener which will be triggered when the given property is changed (depending on the '''type'''). A unique integer ID is returned; this can later be used as the argument to {{func link|removelistener()}}.<br />
{{note|Listeners are known to be a source of resource leaks. To avoid this, please take measures such as:<br />
* Using {{func link|removelistener()}} when they are not needed any more.<br />
* Using a single initialization listener.<br />
* Avoiding tying listeners to properties that are rapidly updated (e.g., many times per frame).<br />
}}<br />
|param1 = node<br />
|param1text = Mandatory string or <code>props.Node</code> object pointing to a property in the [[Property Tree]].<br />
|param2 = code<br />
|param2text = Mandatory callback function to execute when the listener is triggered. The function can take up to four arguments in the following order:<br />
* '''changed''': a <code>props.Node</code> object pointing to the changed node.<br />
* '''listen''': a <code>props.Node</code> object pointing to the listened-to node. Note that this argument maybe different depending on the '''type'''.<br />
* '''mode''': an integer telling how the listener was triggered. 0 means that the value was changed. 1 means that a child property was added. -1 means that a child property was removed.<br />
* '''is_child''': boolean telling whether '''changed''' is a child property of the listened-to '''node''' or not. 1 (true) if it is, 0 (false) otherwise.<br />
|param3 = init<br />
|param3text = If set to 1 (true), the listener will additionally be triggered when it is created. This argument is optional and defaults to 0 (false).<br />
|param4 = type<br />
|param4text = Integer specifying the listener's behavior. 0 means that the listener will only trigger when the property is changed. 1 means that the trigger will always be triggered when the property is written to. 2 will mean that the listener will be triggered even if child properties are modified. This argument is optional and defaults to 1.<br />
|example1 = var prop = props.globals.initNode("/sim/test", "", "STRING"); # create property<br />
var id = setlistener("/sim/test", func(n){ # create listener<br />
print("Value: ", n.getValue());<br />
});<br />
setprop("/sim/test", "blah"); # trigger listener<br />
removelistener(id); # remove listener<br />
prop.remove(); # remove property<br />
}}<br />
<br />
===setprop()===<br />
{{Nasal doc<br />
|syntax = <nowiki>setprop(path[, path[, ...]], value);</nowiki><br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=385|t=Source}}<br />
|text = Sets the value of a property in the [[Property Tree]]. If the property does not exist, it will be created. Returns 1 (true) on success or 0 (false) if there was an error.<br />
{{note|If you want to remove a property, you will have to use one of the <code>props</code> helpers:<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 />
|param1 = path<br />
|param1text = There needs to be at least one '''path''' argument, but there is no limit to the maximum amount that can be given. They will be concatenated together to form a property tree path. The arguments must be strings, but in FlightGear v3.2 onwards, there also is support (added by {{flightgear commit|34ed79}}) for numeric arguments as indices. See example 2 below.<br />
|param2 = value<br />
|param2text = Value to write to the given property. Must be either a string or a number.<br />
|example1 = setprop("/sim/demo", "This is a demo");<br />
|example2text = Note that the example below will only work in FlightGear 3.2 and above.<br />
|example2 = for(var i = 0; i < 3; i += 1){<br />
setprop("/sim/demo", i, "Demo #" ~ i));<br />
}<br />
|example3text = Same as above, but is supported by all versions of FlightGear.<br />
|example3 = for(var i = 0; i < 3; i += 1){<br />
setprop("/sim/demo[" ~ i ~ "]", "Demo #" ~ i));<br />
<nowiki>}</nowiki><br />
}}<br />
====See also====<br />
{{note| If you have to read/write the same property multiple times (e.g. in an update loop), it is more efficient to use a node object: <br />
To get a Node rather than its value, use <code>props.globals.getNode()</code> - see [[Nasal_library/props]]. }}<br />
<br />
===settimer() ===<br />
{{Nasal doc<br />
|syntax = settimer(function, delta[, realtime]);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=499|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=1286|t=Part 2}}<br />
|text = Runs the given function a specified amount of seconds after the current time. Returns <code>'''nil'''</code>.<br />
{{note|Improper use of <code>settimer()</code> may cause resource leaks. It is also highly recommended that the newer {{func link|maketimer()}} should be used instead of this function.}} <br />
|param1 = function<br />
|param1text = Mandatory function that will be called. It may be necessary to enclose code in an anonymous function (see example).<br />
|param2 = delta<br />
|param2text = Mandatory amount of time in seconds after which the function will be called.<br />
|param3 = realtime<br />
|param3text = If 1 (true), "real time" will be used instead of "simulation time." Defaults to 0 (false). Note that if "simulation time" is used, the timer will not run while FlightGear is paused.<br />
|example1 = var myFunc = func(){<br />
print("Hello");<br />
}<br />
<br />
settimer(myFunc, 2); # runs myFunc after 2 seconds<br />
|example2 = var sqr = func(a){<br />
return a * a;<br />
}<br />
<br />
settimer(func(){<br />
print(sqr(2)); # will print 4 after 2 seconds<br />
}, 2);<br />
}}<br />
<br />
===srand() ===<br />
{{Nasal doc<br />
|syntax = srand();<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=559|t=Source}}<br />
|text = Makes the pseudorandom number generator (see {{func link|rand()}}) generate a new {{wikipedia|random seed|noicon=1}} based on time. Returns 0.<br />
}}<br />
===systime()===<br />
{{Nasal doc<br />
|syntax = systime();<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=770|t=Source}}<br />
|text = Returns the {{wikipedia|Unix time}} (seconds since since 00:00:00 UTC, 1/1/1970) as a floating point number with high resolution. This function is useful for benchmarking purposes (see example 2).<br />
{{note|1=High resolution timers under Windows can produce inaccurate or fixed sub-millisecond results.<ref>{{cite web|url=http://forum.flightgear.org/viewtopic.php?f=30&t=29259|title=Nasal: systime() ??!?|author=Necolatis|date=Apr 2nd, 2016}}</ref> This is due to the underlying {{func link|GetSystemTimeAsFileTime()|link=https://msdn.microsoft.com/en-us/library/windows/desktop/ms724397(v=vs.85).aspx}} API call, which depends on hardware availability of suitable high resolution timers. See also [https://msdn.microsoft.com/en-us/library/windows/desktop/dn553408(v=vs.85).aspx Acquiring high-resolution time stamps]}}<br />
|example1 = print("Unix time: ", systime()); # prints Unix time<br />
|example2 = var myFunc = func(){<br />
for(var i = 0; i <= 10; i += 1){<br />
print("Interation #", i);<br />
}<br />
}<br />
var t = systime(); # record time<br />
myFunc(); # run function<br />
var t2 = systime(); # record new time<br />
print("myFunc() took ", t2 - t, " seconds"); # print result<br />
}}<br />
<br />
===thisfunc()===<br />
{{Nasal doc<br />
|syntax = thisfunc();<br />
|source = {{fgdata file|Nasal/globals.nas|t=Source}}<br />
|text = Returns the function from which this function is called. This allows a function to reliably and safely call itself from within a closure.<br />
|example1 = var stringify_vec = func(input){<br />
if (typeof(input) == "scalar"){<br />
return sprintf("%s", input);<br />
} elsif (typeof(input) == "vector") {<br />
if (size(input) == 0) return "[]";<br />
var this = thisfunc();<br />
var buffer = "[";<br />
for(var i = 0; i < size(input); i += 1){<br />
buffer ~= this(input[i]);<br />
if (i == size(input) - 1) {<br />
buffer ~= "]";<br />
} else {<br />
buffer ~= ", ";<br />
}<br />
}<br />
return buffer;<br />
} else {<br />
die("stringify_vec(): Error! Invalid input. Must be a vector or scalar");<br />
}<br />
}<br />
<br />
var test_vec = ["a", "b", "c", 1, 2, 3];<br />
debug.dump(stringify_vec(test_vec)); # prints "[a, b, c, 1, 2, 3]"<br />
test_vec = [];<br />
debug.dump(stringify_vec(test_vec)); # prints "[]"<br />
test_vec = {};<br />
debug.dump(stringify_vec(test_vec)); # will throw an error<br />
}}<br />
<br />
===tileIndex() ===<br />
{{Nasal doc<br />
|syntax = tileIndex();<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1720|t=Source}}<br />
|text = Returns the index of the tile at the aircraft's current position as a string. This corresponds to the name of the STG file of the tile. For example, at [[KSFO]], this would be <code>942050</code>, corresponding to <tt>''[[$FG_SCENERY]]/Terrain/w130n30/w123n3/942050.stg''</tt>.<br />
|example1 = print(tileIndex()); # print index<br />
}}<br />
<br />
=== tilePath()===<br />
{{Nasal doc<br />
|syntax = tilePath();<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1712|t=Source}}<br />
|text = Returns the base path of the tile at the aircraft's current position as a string. For example, at KSFO, this would be <code>w130n30/w123n3</code>, corresponding to <tt>''[[$FG_SCENERY]]/Terrain/w130n30/w123n3''</tt>.<br />
|example1 = print(tilePath()); # print path<br />
}}<br />
<br />
=== values()===<br />
{{Nasal doc<br />
|syntax = values(hash);<br />
|source = {{fgdata file|Nasal/globals.nas|t=Source}}<br />
|text = Returns a vector containing the values of the given hash.<br />
|param1 = hash<br />
|param1text = Mandatory hash to get the values of.<br />
|example1 = var hash = {<br />
"a": 1,<br />
"b": 2,<br />
"c": 3<br />
};<br />
<br />
foreach(var val; values(hash)){<br />
print(val);<br />
}<br />
|example2text = The below example does exactly the same thing as the above example, but does not use <code>values()</code>:<br />
|example2 = var hash = {<br />
"a": 1,<br />
"b": 2,<br />
"c": 3<br />
};<br />
<br />
foreach(var key; keys(hash)){<br />
print(hash[key]);<br />
<nowiki>}</nowiki><br />
}}<br />
<br />
==Extension functions new in FG 2020.1 ==<br />
The following functions have been added to the nasal core library and will be released with FlightGear version 2020.1. <br />
Before the release they are available in the development branch "next".<br />
<br />
===isfunc()===<br />
Returns 1 if type or argument is a function, otherwise 0.<br />
<br />
===isghost()===<br />
Returns 1 if type or argument is a ghost, otherwise 0.<br />
<br />
=== ishash()===<br />
Returns 1 if type or argument is a hash, otherwise 0.<br />
<br />
===isint()===<br />
{{Nasal doc<br />
|syntax = isint(x);<br />
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}<br />
|text = Returns 1 if argument has a numeric value and x == floor(x), e.g. integer.<br />
}}<br />
<br />
===isnum()===<br />
{{Nasal doc<br />
|syntax = isnum(x);<br />
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}<br />
|text = Returns 1 if typeof(x) is "scalar" and x has a numeric value otherwise 0. <br />
}}<br />
<br />
===isscalar()===<br />
{{Nasal doc<br />
|syntax = isscalar(x);<br />
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}<br />
|text = Returns 1 if type or argument is a scalar (string or numeric), otherwise (vector, hash, func, ...) it returns 0. This is useful to check if a variable can be converted to string e.g. when useing the string concat operator "~". <br />
|example1 = var a = "foo"; <br />
var b=42;<br />
if (isscalar(a) and isscalar(b)) print(a~b);<br />
if (isstr(a)) print("a is a string");<br />
if (isint(b)) print("b is an integer");<br />
# if (isscalar(a))... is equivalent to if (typeof(a) == "scalar")...<br />
}}<br />
<br />
===isstr()===<br />
Returns 1 if type or argument is a string, otherwise 0. <br />
<br />
===isvec()===<br />
Returns 1 if type or argument is a vector, otherwise 0.<br />
<br />
===vecindex()===<br />
{{Nasal doc<br />
|syntax = vecindex(vector, value);<br />
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}<br />
|text = Returns the index of value or nil, if value is not found in vector.<br />
|example1=<br />
var myvector = ["apple", "bananna", "coconut"];<br />
# to check if a vector contains a certain value compare vecindex to nil<br />
if (vecindex(myvector, "apple") != nil) {<br />
print("found apple");<br />
}<br />
# WARNING: this will not work as desired because index is 0<br />
if (vecindex(myvector, "apple")) {<br />
print("found apple");<br />
<nowiki>}</nowiki><br />
<br />
}}<br />
<br />
==Variables==<br />
Various global constants (technically variables) are provided for use in converting between different units. They are all found in {{fgdata file|Nasal/globals.nas|text=$FG_ROOT/Nasal/globals.nas}}.<br />
<br />
===D2R===<br />
{{Nasal doc<br />
|syntax = var radians = degrees * D2R;<br />
|text = Converts an angle from degrees to radians when multiplied by the angle in degrees. Equal to <code>π / 180</code>.<br />
}}<br />
===FPS2KT===<br />
{{Nasal doc<br />
|syntax = var knots = feet_per_second * FPS2KT;<br />
|text = Converts a velocity from feet per second to knots when multiplied by the velocity in feet per second. Approximately equal to 0.5925.<br />
}}<br />
===FT2M===<br />
{{Nasal doc<br />
|syntax = var metres = feet * FT2M;<br />
|text = Converts a length from feet to metres when multiplied by the length in feet. Equal to 0.3048.<br />
}}<br />
===GAL2L ===<br />
{{Nasal doc<br />
|syntax = var litres = gallons * GAL2L;<br />
|text = Converts a volume from US liquid gallons to litres when multiplied by the volume in gallons. Approximately equal to 3.7854.<br />
}}<br />
===IN2M===<br />
{{Nasal doc<br />
|syntax = var metres = inches * IN2M;<br />
|text = Converts a length from inches to metres when multiplied by the length in inches. Equal to 0.0254.<br />
}}<br />
===KG2LB===<br />
{{Nasal doc<br />
|syntax = var pounds = kilograms * KG2LB;<br />
|text = Converts a mass from kilograms to pounds when multiplied by the mass in kilograms. Approximately equal to 2.2046.<br />
}}<br />
===KT2FPS===<br />
{{Nasal doc<br />
|syntax = var feet_per_second = knots * KT2FPS;<br />
|text = Converts a velocity from knots to feet per second when multiplied by the velocity in knots. Approximately equal to 1.6878.<br />
}}<br />
===KT2MPS===<br />
{{Nasal doc<br />
|syntax = var metres_per_second = knots * KT2MPS;<br />
|text = Converts a velocity from knots to metres per second when multiplied by the velocity in knots. Approximately equal to 0.5144.<br />
}}<br />
===L2GAL===<br />
{{Nasal doc<br />
|syntax = var gallons = litres * L2GAL;<br />
|text = Converts a volume from litres to US liquid gallons when multiplied by the volume in litres. Approximately equal to 0.2642.<br />
}}<br />
===LB2KG===<br />
{{Nasal doc<br />
|syntax = var kilograms = pounds * LB2KG;<br />
|text = Converts a mass from pounds to kilograms when multiplied by the mass in pounds. Approximately equal to 0.4536.<br />
}}<br />
===M2FT ===<br />
{{Nasal doc<br />
|syntax = var feet = metres * M2FT;<br />
|text = Converts a length from metres to feet when multiplied by the length in metres. Approximately equal to 3.2808.<br />
}}<br />
===M2IN===<br />
{{Nasal doc<br />
|syntax = var inches = metres * M2IN;<br />
|text = Converts a length from metres to inches when multiplied by the length in metres. Approximately equal to 39.3701.<br />
}}<br />
===M2NM ===<br />
{{Nasal doc<br />
|syntax = var nautical_miles = metres * M2NM;<br />
|text = Converts a length from metres to nautical miles when multiplied by the length in metres. Approximately equal to 0.00054.<br />
}}<br />
===MPS2KT ===<br />
{{Nasal doc<br />
|syntax = var knots = metres_per_second * MPS2KT;<br />
|text = Converts a velocity from metres per second to knots when multiplied by the velocity in metres per second. Approximately equal to 1.9438.<br />
}}<br />
===NM2M ===<br />
{{Nasal doc<br />
|syntax = var metres = nautical_miles * NM2M;<br />
|text = Converts a length from nautical miles to metres when multiplied by the length in nautical miles. Equal to 1,852.<br />
}}<br />
===R2D===<br />
{{Nasal doc<br />
|syntax = var degrees = radians * R2D;<br />
|text = Converts an angle from radians to degrees when multiplied by the angle in radians. Equal to <code>180 / π</code>.<br />
}}<br />
<br />
{{Appendix}}<br />
<br />
<br />
{{Nasal namespaces}}</div>Clm76https://wiki.flightgear.org/w/index.php?title=Nasal_library&diff=138566Nasal library2023-10-30T10:08:26Z<p>Clm76: /* findNavaidByFrequencyMHz() */</p>
<hr />
<div>{{Nasal Navigation|nocat=1}}<br />
This page documents the global '''library functions and variables''' 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, the ''[[#Extension functions|extension functions]]'', which have been subsequently added, and are specifically designed for FlightGear, and the ''[[#variables|global variables]]'', which are conversion variables, added with extension functions, for converting between units. The relevant folders in [[Git]] are:<br />
* {{flightgear file|src/Scripting}}<br />
* {{simgear file|simgear/nasal}}<br />
<br />
All these functions and variables are in the global namespace, that is, they are directly accessible (e.g., one can call <syntaxhighlight lang="nasal" inline>magvar()</syntaxhighlight> instead of <syntaxhighlight lang="nasal" inline>namespace.magvar()</syntaxhighlight>). However, if a namespace must be used, <code>globals</code> is the correct namespace, but using it is not recommended. For a more complete explanation, see [[Nasal Namespaces in-depth]].<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|printerror()|debug}}.<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.<br />
<br />
The result is a four-element vector containing '''[0]''' a hash of local variables, '''[1]''' the function object, '''[2]''' the full source file name (incl. path) and '''[3]''' the line number. <br />
|param1 = level<br />
|param1text = Optional integer specifying the stack level to return a result from. Defaults to 1 (i.e. 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 lang="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 />
<br />
===contains()===<br />
{{Requires commit|desc=Vector support|details=see {{Merge-request|project=fgdata|id=305}}|commit=ee39abbd3b70c9b6d5e3a1c4ccedddaac1a92b11|repo=Simgear}}<br />
{{Nasal doc<br />
|syntax = contains(vector, item);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=184|t=Source}}<br />
|text = Returns 1 (True) if the vector contains the specified item, or 0 (False) if not.<br />
|param1 = vector<br />
|param1text = The vector to search in.<br />
|param2 = item<br />
|param2text = The object to be searched for in the vector.<br />
|example1 =<br />
# Initialize a hash<br />
var vec = ["element", "foo"];<br />
print(contains(hash, "element") ? "Yes" : "No"); # This will print "Yes"<br />
|example2 =<br />
# Initialize a hash<br />
var vec = ["element", "foo"];<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 NOT identical to setting the hash value specified by the key to <code>'''nil'''</code> as the key will stay in the hash (at least for a while). 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 />
|commit = {{simgear commit|bd7163|t=commit}}<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 />
|commit = {{simgear commit|bd7163|t=commit}}<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()|link=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 />
|example2text = 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 />
|example3text = This example sorts a vector of strings (runways for example) from smallest to greatest.<br />
|example3 = <br />
var runways = ["09R","27R","26L","09L","15"];<br />
var rwy = sort(runways,func(a,b) cmp(a,b));<br />
debug.dump(rwy); # prints ['09L','09R','15','26L','27R']<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 = <nowiki>sprintf(format[, arg[, arg, [...]]]);</nowiki><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()|link=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. This includes the decimal point and decimal fraction as well as + or - signs.<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>s</code> {{!!}} A string<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 />
|example10 =<br />
print(sprintf("%.2f", 1.4)); #prints "1.40"<br />
print(sprintf("%.1f", 1.4)); #prints "1.4"<br />
print(sprintf("% 4.1f", 1.4)); #prints " 1.4"<br />
print(sprintf("%04.1f", 1.4)); #prints "01.4"<br />
print(sprintf("% 6.1f", 1.4)); #prints " 1.4"<br />
print(sprintf("%06.1f", 1.4)); #prints "0001.4"<br />
}}<br />
<br />
===streq()===<br />
{{Nasal doc<br />
|syntax = streq(a, b);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=129|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. Negative values specify a position from the end of the string.<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 />
|example4 = print(substr("abcde", -2)); # prints "de"<br />
|example5 = print(substr("abcde", -3, 2)); # prints "cd"<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 />
* Omitting the ''vector'' and ''start'' arguments is not an error (possibly it should be) but the return value is ''nil''.<br />
* A negative ''start'' argument ''is'' an error. This seems wrong. Perhaps the language designer could comment.<br />
* A value of ''start'' greater than ''size(vector)'' causes an error. A value equal to ''size(vector)'' returns an empty vector.<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 />
|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 modules ==<br />
=== thread ===<br />
{{WIP}}<br />
<br />
{{Nasal doc<br />
|syntax = thread.newthread(func);<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = start a new worker thread<br />
|example1 = thread.newthread( func() {} );<br />
}}<br />
<br />
{{Nasal doc<br />
|syntax = thread.newlock();<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = create a new lock<br />
|example1 = var lock = thread.newlock()<br />
}}<br />
<br />
{{Nasal doc<br />
|syntax = thread.lock();<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = lock a lock<br />
|example1 = var lock = thread.newlock()<br />
}}<br />
<br />
{{Nasal doc<br />
|syntax = thread.unlock();<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = unlock a lock<br />
|example1 = var lock = thread.unlock()<br />
}}<br />
<br />
<br />
{{Nasal doc<br />
|syntax = thread.newsem();<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = create a new {{Wikipedia|semaphore}}<br />
|example1 = var semaphore = thread.newsem()<br />
}}<br />
<br />
<br />
{{Nasal doc<br />
|syntax = thread.semdown();<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = semaphore down<br />
|example1 = thread.semdown(semaphore)<br />
}}<br />
<br />
<br />
{{Nasal doc<br />
|syntax = thread.semup();<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = semaphore up<br />
|example1 = thread.semup(semaphore)<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()|link=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 />
===aircraftToCart() ===<br />
This new function in FG 2017.2.1 takes coordinates in aircraft structural coordinate system, and translate them into geocentric coordinates.<br />
Example for (5,6,7):<br />
<syntaxhighlight lang="nasal"><br />
var pos = aircraftToCart({x: -5, y: 6, z: -7});<br />
var coord = geo.Coord.new();<br />
coord.set_xyz(pos.x, pos.y, pos.z);<br />
</syntaxhighlight><br />
Notice: x and z is inverted sign on purpose.<br />
if you want lat. lon, alt from that, just call: (degrees and meters)<br />
<br />
<syntaxhighlight lang="nasal"><br />
coord.lat()<br />
coord.lon()<br />
coord.alt()<br />
</syntaxhighlight><br />
<br />
===addcommand() ===<br />
{{Nasal doc<br />
|syntax = addcommand(name, code);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=659|t=Source}}<br />
|version = 2.12<br />
|commit = {{flightgear commit|7b663c|t=commit}}<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(node) {<br />
print("fgcommand 'myFGCmd' has been run.");<br />
props.dump( node );<br />
});<br />
fgcommand("myFGCmd", props.Node.new({foo:1, bar:2}) );<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 />
* '''parents''': A vector containing a hash of various functions to access information about the runway. See {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2659}} for full list.<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 />
*** '''id''': Name of runway.<br />
*** '''lat''': Latitude of the runway.<br />
*** '''lon''': Longitude of the runway.<br />
*** '''heading''': Heading of the runway.<br />
*** '''length''': Length of the runway in metres.<br />
*** '''width''': Width of the runway in metres.<br />
*** '''surface''': Runway surface type.<br />
*** '''threshold''': Length of the runway's {{wikipedia|displaced threshold}} in metres. Will return 0 if there is none.<br />
*** '''stopway''': Length of the runway's stopway (the area before the threshold) in metres. Will return 0 if there is none.<br />
*** '''reciprocal''': <code>runway</code> ghost of the reciprocal runway.<br />
*** '''ils_frequency_mhz''': ILS frequency in megahertz.<br />
*** '''ils''': <code>navaid</code> ghost of the ILS transmitter.<br />
* '''helipads'''<br />
** '''<helipad name>'''<br />
*** '''id''': Name of helipad.<br />
*** '''lat''': Latitude of the helipad.<br />
*** '''lon''': Longitude of the helipad.<br />
*** '''heading''': Heading of the helipad.<br />
*** '''length''': Length of the helipad in metres.<br />
*** '''width''': Width of the helipad in metres.<br />
*** '''surface''': Helipad surface type.<br />
* '''taxiways'''<br />
** '''<taxiway name>'''<br />
*** '''id''': Name of taxiway.<br />
*** '''lat''': Latitude of the taxiway.<br />
*** '''lon''': Longitude of the taxiway.<br />
*** '''heading''': Heading of the taxiway.<br />
*** '''length''': Length of the taxiway in metres.<br />
*** '''width''': Width of the taxiway in metres.<br />
*** '''surface''': Taxiway surface type.<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 />
<nowiki>}</nowiki><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 />
<nowiki>}</nowiki><br />
}}<br />
<br />
===airway()===<br />
<br />
{{Nasal doc<br />
|syntax = airway(ident [, pos]);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2644|t=Source}}<br />
|text = {{see also|Nasal Flightplan}}<br />
This function returns a ghost containing an airway of a specified id.<br />
|param1 = ident<br />
|param1text = a Positioned ghost (leg, navaid, airport) and so on, passed to the search function.<br />
|param2 = pos<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 />
|commit = {{fgdata commit|8b16a7|t=commit}}<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 with geodetic coordinates (cartesian coordinates will not be accepted)<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 />
===createFlightplan()===<br />
{{Nasal doc<br />
|syntax = createFlightplan(path);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2331|t=Source}}<br />
|text = Creates an empty flightplan object. It accepts one argument, ''path'' passed an absolute path to a .fgfp / .gpx file, it will populate the flightplan with waypoints from the file.<br />
|param1 = path<br />
|param1text = Optional parameter defining the file from which a flightplan will be populated.<br />
|example1 = <br />
var path = getprop("/sim/fg-home") ~ "/Export/test.fgfp";<br />
var flightplan = createFlightplan(path);<br />
debug.dump(flightplan);<br />
}}<br />
<br />
===createDiscontinuity()===<br />
{{Nasal doc<br />
|syntax = createDiscontinuity();<br />
|text = Returns a <code>waypoint</code> ghost object. A route discontinuity is inserted by an {{abbr|FMS|Flight Management System}} when it is unsure how to connect two waypoints.<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2045|t=Source}}<br />
|version = 2016.1<br />
|commit = {{flightgear commit|caead6|t=commit}}<br />
}}<br />
===createViaTo()===<br />
{{Nasal doc<br />
|syntax = createViaTo(airway, waypoint);<br />
|text = Returns a <code>waypoint</code> ghost object. It represents a route "via '''airway''' to '''waypoint'''".<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2009|t=Source}}<br />
|version = 2016.1<br />
|commit = {{flightgear commit|caead6|t=commit}}<br />
|param1 = airway<br />
|param1text = The name of an airway.<br />
|param2 = waypoint<br />
|param2text = Must be in the airway and one of:<br />
* The name of a waypoint.<br />
* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, or <code>fix</code> ghost object.<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 />
<nowiki>}</nowiki><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 />
<nowiki>}</nowiki><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 />
===findNavaidByFrequencyMHz()===<br />
{{Nasal doc<br />
|syntax = findNavaidByFrequencyMHz([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>findNavaidByFrequencyMHz(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 = findNavaidByFrequencyMHz(109.55);<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 / 100), " Mhz");<br />
print("Range: ", navaid.range_nm, " nm");<br />
if(navaid.course) print("Course: ", navaid.course);<br />
}}<br />
<br />
=== findNavaidsByFrequencyMHz()===<br />
{{Nasal doc<br />
|syntax = findNavaidsByFrequencyMHz([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>findNavaidsByFrequencyMHz(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 = findNavaidsByFrequencyMHz(109.55);<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 / 100), " Mhz");<br />
print("Range: ", navaid.range_nm, " nm");<br />
if(navaid.course) print("Course: ", navaid.course);<br />
print("--");<br />
<nowiki>}</nowiki><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 />
<nowiki>}</nowiki><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 />
<nowiki>}</nowiki><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 />
<nowiki>}</nowiki><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 />
=== get_cart_ground_intersection()===<br />
Introduced in 2017.2.1, see [[Terrain Detection]].<br />
<br />
===getprop()===<br />
{{Nasal doc<br />
|syntax = <nowiki>getprop(path[, path[, ...]]);</nowiki><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 = path<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 also 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 versions 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 />
<nowiki>}</nowiki><br />
}}<br />
==== See also====<br />
{{note| If you have to read/write the same property multiple times (e.g. in an update loop), it is more efficient to use a node object: <br />
To get a Node rather than its value, use <code>props.globals.getNode()</code> - see [[Nasal_library/props]]. }}<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 = <nowiki>interpolate(prop, value1, time1[, value2, time2[, ...]]);</nowiki><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 />
<nowiki>}</nowiki><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 = <nowiki>logprint(priority[, msg[, msg[, ...]]]);</nowiki><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 from the Nasal file itself rather than from {{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 />
{{note| <br />
The following constants have been added to the development branch of FlightGear ("next") and will be releases with FG 2020.1 so you won't have to remember the numbers anymore:<br />
<br />
LOG_BULK, LOG_WARN, LOG_DEBUG, LOG_INFO, LOG_ALERT, DEV_WARN, DEV_ALERT }}<br />
<br />
===magvar() ===<br />
{{Nasal doc<br />
|syntax = magvar([pos]);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1642|t=Source}}<br />
|text = Returns the {{wikipedia|magnetic variation}} at a given set of coordinates. The table below gives the magnetic model used depending on the version of FlightGear.<br />
{{{!}} class="wikitable"<br />
! FlightGear versions !! Model !! Reference date<br />
{{!-}}<br />
{{!}} 3.6 and above {{!!}} {{wikipedia|World Magnetic Model}} (WMM) 2015 {{!!}} 1 January 2015<br />
{{!-}}<br />
{{!}} 0.9.11-pre1 to 3.4 {{!!}} WMM 2005 {{!!}} 1 January 2005<br />
{{!-}}<br />
{{!}} 0.7.3 to 0.9.10 {{!!}} WMM 2000 {{!!}} 1 January 2000<br />
{{!}}}<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>magvar(lat,lon)</code>.<br />
|example1 = print(magvar(0, 0)); # prints the magnetic variation at 0, 0<br />
}}<br />
<br />
===maketimer() ===<br />
{{Nasal doc<br />
|syntax = maketimer(interval[, self], function);<br />
|source = ''Implemented using the {{API Link|flightgear|class|TimerObj}} class.''<br>{{flightgear file|src/Scripting/NasalSys.cxx|l=90|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=533|t=Part 2}}<br />
|version = 2.12<br />
|commit = {{flightgear commit|ab939f|t=commit}}<br />
|text = Returns a timer object containing the following methods and members:<br />
* '''start()''': Starts the timer.<br />
* '''stop()''': Stops the timer.<br />
* '''restart(interval)''': Restarts the timer with the given interval.<br />
* '''singleShot''': Bool showing whether the timer is only to be run once, or continuously until told to stop. Can be both set and read from (see examples).<br />
* '''isRunning''': Read-only bool telling whether the timer is currently running.<br />
* '''simulatedTime''': (FG 2017.1+; {{flightgear commit|0af316|t=commit}}) Bool telling whether the timer is using simulated time (which accounts for pause, etc.). Defaults to false (use real time). Can be both read and set. This cannot be changed while the timer is running.<br />
Unlike {{func link|settimer()}}, which it replaces, <code>maketimer()</code> provides more control over the timer. In addition, it can help reduce memory usage.<br />
|param1 = interval<br />
|param1text = Interval in seconds for the timer.<br />
|param2 = self<br />
|param2text = Optional parameter specifying what any <code>'''me'''</code> references in the function being called will refer to.<br />
|param3 = function<br />
|param3text = Function to be called at the given interval.<br />
|example1 = var timer = maketimer(1, func(){<br />
print("Hello, World!"); # print "Hello, World!" once every second (call timer.stop() to stop it)<br />
});<br />
timer.start();<br />
|example2 = var timer = maketimer(1, math, func(){<br />
print(me.math); # 'me' reference is the 'math' namespace<br />
});<br />
timer.singleShot = 1; # timer will only be run once<br />
timer.start();<br />
|example3 = var timer = maketimer(1, func(){<br />
print("Hello, World!"); # print "Hello, World!" once every second (call timer.stop() to stop it)<br />
});<br />
timer.start();<br />
print(timer.isRunning); # prints 1<br />
|example4text = In the example below, "Hello, World!" will be printed after one second the first time, and after two seconds thereafter.<br />
|example4 = var update = func(){<br />
print("Hello, World!");<br />
timer.restart(2); # restarts the timer with a two second interval<br />
}<br />
<br />
var timer = maketimer(1, update);<br />
timer.singleShot = 1;<br />
timer.start();<br />
}}<br />
<br />
===maketimestamp()===<br />
{{Nasal doc<br />
|syntax = maketimestamp()<br />
|source = ''Implemented using the {{API Link|flightgear|class|TimeStampObj}} class.''<br>{{flightgear file|src/Scripting/NasalSys.cxx|l=214|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=589|t=Part 2}}<br />
|version = 2019.2<br />
|commit = {{flightgear commit|7db06300|t=commit}}<br />
|text = Returns a time stamp object to allow high resolution timing of Nasal operations. When created the timer will automatically be stamped. The object has the following methods:<br />
* '''stamp()''': Resets the timing operation. Call this first.<br />
* '''elapsedMSec()''': returns number of milliseconds elapsed since stamp() called. Resolution may vary depending on platform but is usually at least millisecond accuracy.<br />
* '''elapsedUSec()''': returns number of microseconds elapsed since stamp() called. Resolution may vary depending on platform but is usually at least millisecond accuracy.<br />
|<br />
|example1text = In the example below the number of milliseconds elapsed will be printed.<br />
|example1 = var timestamp = maketimestamp();<br />
timestamp.stamp();<br />
print(timestamp.elapsedMSec(), "ms elapsed");<br />
print(timestamp.elapsedMSec(), "ms elapsed");<br />
}}<br />
<br />
===md5()===<br />
{{Nasal doc<br />
|syntax = md5(string);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=758|t=Source}}<br />
|version = 3.2<br />
|commit = {{flightgear commit|cfbf9e|t=commit}}<br />
|text = Returns a the {{wikipedia|MD5}} hash (as a string) of the inputted string.<br />
|param1 = string<br />
|param1text = String the generate the hash of. Mandatory.<br />
|example1text = The below code should output <code>65a8e27d8879283831b664bd8b7f0ad4</code>.<br />
|example1 = print(md5("Hello, World!"));<br />
}}<br />
<br />
===navinfo()===<br />
{{Nasal doc<br />
|syntax = navinfo(lat, lon, type, id);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1453|t=Source}}<br />
|text = Returns vector <code>navaid</code> ghost objects matching the given '''type''' and '''id''' or <code>'''nil'''</code> on error.<br />
|param1 = lat ''and'' lon<br />
|param1text = If given, the returned navaids will be put into order of ascending distance from the location.<br />
|param2 = type<br />
|param2text = Narrows the search to the given type. Must be one of "any," "fix," "vor," "ndb," "ils," "dme," or "tacan." Defaults to the equivalent of "any."<br />
|param3 = id<br />
|param3text = ID to search for. Note that, although all the parameters are technically optional, this parameter must be given, otherwise an empty vector will be returned.<br />
|example1 = navinfo("vor"); # returns all VORs<br />
|example2 = navinfo("HAM"); # return all navaids whose names start with "HAM"<br />
|example3 = navinfo("vor", "HAM"); # return all VORs whose names start with "HAM"<br />
|example4 = navinfo(34,48,"vor","HAM"); # return all VORs whose names start with "HAM" and sorted by distance relative to 34°, 48°<br />
}}<br />
<br />
===parse_markdown()===<br />
{{Nasal doc<br />
|syntax = parse_markdown(markdown);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=745|t=Part 1}} {{!}} {{simgear file|simgear/misc/SimpleMarkdown.cxx|t=Part 2}} <br />
|version = 3.2<br />
|text = Parses a string containing {{wikipedia|Markdown}} and returns the result as a string. As of FlightGear 2016.1, it is just a simple parser, and does the following:<br />
* It strips whitespace from the beginning of the string.<br />
* It supports [http://daringfireball.net/projects/markdown/syntax#p paragraphs and line breaks].<br />
* It collapses whitespace.<br />
* It converts unordered [http://daringfireball.net/projects/markdown/syntax#list lists] to use a bullet character (&bull;). Note that the bullet character is implemented in hexadecimal UTF-8 character bytes (<code>E2 80 A2</code>), as so may not work properly when the being displayed in an encoding other than UTF-8.<br />
|param1 = markdown<br />
|param1text = String containing Markdown to be parsed.<br />
|example1text = <br />
Save the below code as <tt>''[[$FG_ROOT]]/gui/dialogs/test.xml''</tt>, then run the Nasal code below it to open the dialog. To change the markdown to be parsed, simply change the code in the highlighted section, save it, and reload the GUI (<tt>Debug > Reload GUI</tt>).<br />
<syntaxhighlight lang="xml" highlight="41-50"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<br />
<PropertyList><br />
<br />
<name>test</name><br />
<layout>vbox</layout><br />
<br />
<group><br />
<layout>hbox</layout><br />
<br />
<empty><br />
<stretch>true</stretch><br />
</empty><br />
<br />
<text><br />
<label>parse_markdown() test dialog</label><br />
</text><br />
<br />
<empty><br />
<stretch>true</stretch><br />
</empty><br />
<br />
<button><br />
<legend></legend><br />
<pref-width>16</pref-width><br />
<pref-height>16</pref-height><br />
<binding><br />
<command>dialog-close</command><br />
</binding><br />
</button><br />
<br />
</group><br />
<br />
<canvas><br />
<name>Canvas plot</name><br />
<stretch>true</stretch><br />
<pref-width>400</pref-width><br />
<pref-height>300</pref-height><br />
<nasal><br />
<load><![CDATA[<br />
var text = 'Items:<br />
* apples<br />
* oranges<br />
* pears<br />
<br />
Some text.<br />
Some more items:<br />
* apples<br />
* oranges<br />
* pears';<br />
<br />
var parsed = parse_markdown(text);<br />
<br />
var root_canvas = canvas.get(cmdarg());<br />
root_canvas.setColorBackground(255, 255, 255);<br />
var root = root_canvas.createGroup();<br />
<br />
var text_dis = root.createChild("text")<br />
.setText(parsed)<br />
.setTranslation(5, 5)<br />
.setFont("LiberationFonts\LiberationSans-Regular.ttf")<br />
.setFontSize(15)<br />
.setColor(0, 0, 0)<br />
.setDrawMode(canvas.Text.TEXT)<br />
.setAlignment("left-top");<br />
]]></load><br />
</nasal><br />
</canvas><br />
<br />
</PropertyList><br />
</syntaxhighlight><br />
|example1 = fgcommand("dialog-show", {"dialog-name": "test"});<br />
|example2text = The example below parses Markdown and outputs it in a HTML document. The parsed text is placed in <syntaxhighlight lang="xml" inline><pre></pre></syntaxhighlight> tags. To change the Markdown to be parsed, simply edit the variable <tt>markdown</tt> at the top of the code.<br />
|example2 = <nowiki>var markdown = 'Items:<br />
* apples<br />
* oranges<br />
* pears<br />
<br />
Some text.<br />
Some more items:<br />
* apples<br />
* oranges<br />
* pears';<br />
<br />
var parsed = parse_markdown(markdown);<br />
<br />
debug.dump(parsed);<br />
<br />
var path = string.normpath(getprop("/sim/fg-home") ~ '/Export/parse_markdown()-test.html');<br />
<br />
var file = io.open(path, "w");<br />
<br />
var html = "<!DOCTYPE html>\n\n<html>\n\n<head>\n\t<meta charset=\"UTF-8\">\n\t<title>parse_markdown() test generated by Nasal</title>\n</head>\n\n<body>\n\t<pre>" ~ parsed ~ "</pre>\n</body>\n\n</html>";<br />
<br />
io.write(file, html);<br />
io.close(file);<br />
print("Done, file ready for viewing (" ~ path ~ ")");</nowiki><br />
}}<br />
<br />
===parsexml()===<br />
{{Nasal doc<br />
|syntax = <nowiki>parsexml(path[, start[, end[, data[, pro_ins]]]]);</nowiki><br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=710|t=Source}}<br />
|text = This function is an interface into the built-in [http://expat.sourceforge.net/ Expat XML parser]. The absolute path to the file is returned as string, or <code>'''nil'''</code> is returned on error.<br />
|param1 = path<br />
|param1text = Mandatory absolute path to the XML file to be parsed.<br />
|param2 = start<br />
|param2text = Optional callback function that will be called for every starting tag. The function should take two argument: the tag name and a hash containing attributes.<br />
|param3 = end<br />
|param3text = Optional callback function that will be called for every ending tag. The function should take one argument: the tag name.<br />
|param4 = data<br />
|param4text = Optional callback function that will be called for every piece of data within a set of tags. The function should take one argument: the data as a string.<br />
|param5 = pro_ins<br />
|param5text = Optional callback function that will be called for every {{wikipedia|Processing Instruction|processing instruction}}. The function should take two argument: the target and the data string.<br />
|example1text = Save the below XML code in <tt>''[[$FG_HOME]]/Export/demo.xml''</tt>. Then, execute the Nasal code below in the Nasal Console. The XML will be parsed and each bit of the code will be printed.<br />
<syntaxhighlight lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<br />
<?xml-stylesheet type="text/xsl" href="style.xsl"?><br />
<br />
<foo><br />
<blah type="string"><![CDATA[ <sender>John Smith</sender> ]]></blah><br />
<blah2 type="string">Orange &amp; lemons</blah2><br />
</foo><br />
</syntaxhighlight><br />
|example1 = 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 />
}<br />
<br />
var end = func(name){<br />
print("Ending tag: '", name, "'");<br />
}<br />
<br />
var data = func(data){<br />
print("Data = '", data, "'");<br />
}<br />
<br />
var pro_instr = func(target, data){<br />
print("Processing instruction: target = '", target, "', data = '", data, "'");<br />
}<br />
<br />
parsexml(getprop("/sim/fg-home") ~ '/Export/demo.xml', start, end, data, pro_instr);<br />
}}<br />
<br />
===print()===<br />
{{Note|As of 07/2020, we are in the process of slowly deprecating and removing Nasal print() (in fgdata) where possible in favor of log [[#logprint()]] which takes a priority level.<br />
<br />
This is part of the goal that we achieve zero output at log-level at alert, and everything shown at ‘warn; is really a warning, not just information.<ref>https://sourceforge.net/p/flightgear/mailman/message/37042224/</ref>}}<br />
<br />
{{Nasal doc<br />
|syntax = <nowiki>print(data[, data[, ...]]);</nowiki><br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=415|t=Source}}<br />
|text = Concatenates its arguments and then prints it to the terminal and the [[Commonly used debugging tools#fgfs.log|log]]. Note that a newline is automatically added.<br />
|param1 = data<br />
|param1text = Data to print. Only strings and numbers can be printed; other data types will not be. There many be any number of arguments; they will just be concatenated together.<br />
|example1 = print("Just", " a ", "test"); # prints "Just a test"<br />
|example2 = print("pi = ", math.pi); # prints "pi = 3.141592..."<br />
}}<br />
<br />
=== printf() ===<br />
{{Nasal doc<br />
|syntax = <nowiki>printf(format[, arg[, arg, [...]]]);</nowiki><br />
|source = {{fgdata file|Nasal/globals.nas|t=Source}}<br />
|text = Creates and prints a formatted string. For a description of its arguments, see {{func link|sprintf()}} (it is, in fact, implemented using <code>sprintf()</code>).<br />
|example1 = printf("In hexadecimal, 100000 = %X", 186A0); # prints "In hexadecimal, 100000 = 186A0"<br />
}}<br />
<br />
===printlog()===<br />
{{Nasal doc<br />
|syntax = <nowiki>printlog(level, data[, data[, ...]]);</nowiki><br />
|source = {{fgdata file|Nasal/globals.nas|t=Source}}<br />
|text = Prints the given message with the given log level. If the log level is higher or equal to <code>/sim/logging/priority</code>, it is printed.<br />
|param1 = level<br />
|param1text = Mandatory log level as a string. Must be one of "none," "bulk," "debug," "info," "warn," or "alert." Note that "none" will mean that the message will never be printed.<br />
|param2 = data<br />
|param2text = Data to be printed. Only strings and numbers will be printed; others will not be. There may be any number of arguments; they will just be concatenated together.<br />
|example1 = printlog("alert", "This is an alert"); # message will be printed<br />
|example2 = printlog("info", "Just informing you about something"); # message will be printed only if log level is set to "info" or less<br />
}}<br />
<br />
===rand()===<br />
{{Nasal doc<br />
|syntax = rand();<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=554|t=Source}}<br />
|text = Returns a random floating point number between 0 (inclusive) and 1 (exclusive). It takes no arguments.<br />
|example1 = print(rand()); # prints random number<br />
}}<br />
<br />
===registerFlightPlanDelegate()===<br />
{{Nasal doc<br />
|syntax = registerFlightPlanDelegate(init_func);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1879|t=Source}}<br />
|text = Registers a flight plan delegate. See <tt>''{{fgdata file|Nasal/route_manager.nas|t=$FG_ROOT/Nasal/route_manager.nas}}''</tt> for examples.<br />
|param1 = init_func<br />
|param1text = Initialization function which will be called during FlightGear's startup.<br />
}}<br />
===removecommand()===<br />
{{Nasal doc<br />
|syntax = removecommand(cmd);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=668|t=Source}}<br />
|text = Removes the given fgcommand. Returns <code>'''nil'''</code>.<br />
{{caution|This will remove '''any''' [[fgcommands|fgcommand]], even those implemented in C++, so use with caution!}}<br />
|param1 = cmd<br />
|param1text = String specifying the name of the command to remove.<br />
|example1 = addcommand("hello", func(){<br />
print("Hello");<br />
});<br />
fgcommand("hello"); # "Hello" will be printed<br />
removecommand("hello"); # removes it<br />
}}<br />
<br />
===removelistener()===<br />
{{Nasal doc<br />
|syntax = removelistener(id);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=1384|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=506|t=Part 2}}<br />
|text = Removes and deactivates the given listener and returns the number of listeners left or <code>'''nil'''</code> on error.<br />
{{note|It is good practice to remove listeners when they are not required anymore. This prevents the listeners reducing FlightGear's run performance.}}<br />
|param1 = id<br />
|param1text = ID of listener as returned by {{func link|setlistener()}}.<br />
|example1 = var ls = setlistener("/sim/test", func(){<br />
print("Property '/sim/test' has been changed");<br />
});<br />
setprop("/sim/test", "blah"); # trigger listener<br />
var rem = removelistener(ls); # remove listener<br />
print("There are ", rem, " listeners remaining");<br />
}}<br />
<br />
===resolvepath()===<br />
{{Nasal doc<br />
|syntax = resolvepath(path);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=604|t=Source}}<br />
|text = Takes a relative path as a string and uses [[SimGear]]'s path-resolving framework to return an absolute path as a string. If the path could not be resolved, an empty string is returned. See [[Resolving Paths]] for a detailed description of the algorithm. This function can also be used to check if a file exists.<br />
|param1 = path<br />
|param1text = Relative path to be completed.<br />
|example1 = print(resolvepath("Nasal/globals.nas")); # prints the equivalent of $FG_ROOT/Nasal/globals.nas<br />
|example2 = print(resolvepath("blah")); # prints nothing; could not be resolved<br />
|example3 = var file_path = resolvepath("Aircraft/SenecaII/some-file");<br />
if (file_path != ""){<br />
gui.popupTip("some-file found", 2);<br />
} else {<br />
gui.popupTip("some-file not found", 2);<br />
<nowiki>}</nowiki><br />
}}<br />
<br />
===setlistener()===<br />
{{Nasal doc<br />
|syntax = <nowiki>setlistener(node, code[, init[, type]]);</nowiki><br />
|private = _setlistener()<br />
|source = {{flightgear file|src/Scripting/Nasal|l=499|t=Part 1}} {{!}} {{flightgear file|src/Scripting/Nasal|l=1350|t=Part 2}}<br>''Listener implemented using the {{API Link|flightgear|class|FGNasalListener}} class.''<br />
|text = Creates a listener which will be triggered when the given property is changed (depending on the '''type'''). A unique integer ID is returned; this can later be used as the argument to {{func link|removelistener()}}.<br />
{{note|Listeners are known to be a source of resource leaks. To avoid this, please take measures such as:<br />
* Using {{func link|removelistener()}} when they are not needed any more.<br />
* Using a single initialization listener.<br />
* Avoiding tying listeners to properties that are rapidly updated (e.g., many times per frame).<br />
}}<br />
|param1 = node<br />
|param1text = Mandatory string or <code>props.Node</code> object pointing to a property in the [[Property Tree]].<br />
|param2 = code<br />
|param2text = Mandatory callback function to execute when the listener is triggered. The function can take up to four arguments in the following order:<br />
* '''changed''': a <code>props.Node</code> object pointing to the changed node.<br />
* '''listen''': a <code>props.Node</code> object pointing to the listened-to node. Note that this argument maybe different depending on the '''type'''.<br />
* '''mode''': an integer telling how the listener was triggered. 0 means that the value was changed. 1 means that a child property was added. -1 means that a child property was removed.<br />
* '''is_child''': boolean telling whether '''changed''' is a child property of the listened-to '''node''' or not. 1 (true) if it is, 0 (false) otherwise.<br />
|param3 = init<br />
|param3text = If set to 1 (true), the listener will additionally be triggered when it is created. This argument is optional and defaults to 0 (false).<br />
|param4 = type<br />
|param4text = Integer specifying the listener's behavior. 0 means that the listener will only trigger when the property is changed. 1 means that the trigger will always be triggered when the property is written to. 2 will mean that the listener will be triggered even if child properties are modified. This argument is optional and defaults to 1.<br />
|example1 = var prop = props.globals.initNode("/sim/test", "", "STRING"); # create property<br />
var id = setlistener("/sim/test", func(n){ # create listener<br />
print("Value: ", n.getValue());<br />
});<br />
setprop("/sim/test", "blah"); # trigger listener<br />
removelistener(id); # remove listener<br />
prop.remove(); # remove property<br />
}}<br />
<br />
===setprop()===<br />
{{Nasal doc<br />
|syntax = <nowiki>setprop(path[, path[, ...]], value);</nowiki><br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=385|t=Source}}<br />
|text = Sets the value of a property in the [[Property Tree]]. If the property does not exist, it will be created. Returns 1 (true) on success or 0 (false) if there was an error.<br />
{{note|If you want to remove a property, you will have to use one of the <code>props</code> helpers:<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 />
|param1 = path<br />
|param1text = There needs to be at least one '''path''' argument, but there is no limit to the maximum amount that can be given. They will be concatenated together to form a property tree path. The arguments must be strings, but in FlightGear v3.2 onwards, there also is support (added by {{flightgear commit|34ed79}}) for numeric arguments as indices. See example 2 below.<br />
|param2 = value<br />
|param2text = Value to write to the given property. Must be either a string or a number.<br />
|example1 = setprop("/sim/demo", "This is a demo");<br />
|example2text = Note that the example below will only work in FlightGear 3.2 and above.<br />
|example2 = for(var i = 0; i < 3; i += 1){<br />
setprop("/sim/demo", i, "Demo #" ~ i));<br />
}<br />
|example3text = Same as above, but is supported by all versions of FlightGear.<br />
|example3 = for(var i = 0; i < 3; i += 1){<br />
setprop("/sim/demo[" ~ i ~ "]", "Demo #" ~ i));<br />
<nowiki>}</nowiki><br />
}}<br />
====See also====<br />
{{note| If you have to read/write the same property multiple times (e.g. in an update loop), it is more efficient to use a node object: <br />
To get a Node rather than its value, use <code>props.globals.getNode()</code> - see [[Nasal_library/props]]. }}<br />
<br />
===settimer() ===<br />
{{Nasal doc<br />
|syntax = settimer(function, delta[, realtime]);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=499|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=1286|t=Part 2}}<br />
|text = Runs the given function a specified amount of seconds after the current time. Returns <code>'''nil'''</code>.<br />
{{note|Improper use of <code>settimer()</code> may cause resource leaks. It is also highly recommended that the newer {{func link|maketimer()}} should be used instead of this function.}} <br />
|param1 = function<br />
|param1text = Mandatory function that will be called. It may be necessary to enclose code in an anonymous function (see example).<br />
|param2 = delta<br />
|param2text = Mandatory amount of time in seconds after which the function will be called.<br />
|param3 = realtime<br />
|param3text = If 1 (true), "real time" will be used instead of "simulation time." Defaults to 0 (false). Note that if "simulation time" is used, the timer will not run while FlightGear is paused.<br />
|example1 = var myFunc = func(){<br />
print("Hello");<br />
}<br />
<br />
settimer(myFunc, 2); # runs myFunc after 2 seconds<br />
|example2 = var sqr = func(a){<br />
return a * a;<br />
}<br />
<br />
settimer(func(){<br />
print(sqr(2)); # will print 4 after 2 seconds<br />
}, 2);<br />
}}<br />
<br />
===srand() ===<br />
{{Nasal doc<br />
|syntax = srand();<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=559|t=Source}}<br />
|text = Makes the pseudorandom number generator (see {{func link|rand()}}) generate a new {{wikipedia|random seed|noicon=1}} based on time. Returns 0.<br />
}}<br />
===systime()===<br />
{{Nasal doc<br />
|syntax = systime();<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=770|t=Source}}<br />
|text = Returns the {{wikipedia|Unix time}} (seconds since since 00:00:00 UTC, 1/1/1970) as a floating point number with high resolution. This function is useful for benchmarking purposes (see example 2).<br />
{{note|1=High resolution timers under Windows can produce inaccurate or fixed sub-millisecond results.<ref>{{cite web|url=http://forum.flightgear.org/viewtopic.php?f=30&t=29259|title=Nasal: systime() ??!?|author=Necolatis|date=Apr 2nd, 2016}}</ref> This is due to the underlying {{func link|GetSystemTimeAsFileTime()|link=https://msdn.microsoft.com/en-us/library/windows/desktop/ms724397(v=vs.85).aspx}} API call, which depends on hardware availability of suitable high resolution timers. See also [https://msdn.microsoft.com/en-us/library/windows/desktop/dn553408(v=vs.85).aspx Acquiring high-resolution time stamps]}}<br />
|example1 = print("Unix time: ", systime()); # prints Unix time<br />
|example2 = var myFunc = func(){<br />
for(var i = 0; i <= 10; i += 1){<br />
print("Interation #", i);<br />
}<br />
}<br />
var t = systime(); # record time<br />
myFunc(); # run function<br />
var t2 = systime(); # record new time<br />
print("myFunc() took ", t2 - t, " seconds"); # print result<br />
}}<br />
<br />
===thisfunc()===<br />
{{Nasal doc<br />
|syntax = thisfunc();<br />
|source = {{fgdata file|Nasal/globals.nas|t=Source}}<br />
|text = Returns the function from which this function is called. This allows a function to reliably and safely call itself from within a closure.<br />
|example1 = var stringify_vec = func(input){<br />
if (typeof(input) == "scalar"){<br />
return sprintf("%s", input);<br />
} elsif (typeof(input) == "vector") {<br />
if (size(input) == 0) return "[]";<br />
var this = thisfunc();<br />
var buffer = "[";<br />
for(var i = 0; i < size(input); i += 1){<br />
buffer ~= this(input[i]);<br />
if (i == size(input) - 1) {<br />
buffer ~= "]";<br />
} else {<br />
buffer ~= ", ";<br />
}<br />
}<br />
return buffer;<br />
} else {<br />
die("stringify_vec(): Error! Invalid input. Must be a vector or scalar");<br />
}<br />
}<br />
<br />
var test_vec = ["a", "b", "c", 1, 2, 3];<br />
debug.dump(stringify_vec(test_vec)); # prints "[a, b, c, 1, 2, 3]"<br />
test_vec = [];<br />
debug.dump(stringify_vec(test_vec)); # prints "[]"<br />
test_vec = {};<br />
debug.dump(stringify_vec(test_vec)); # will throw an error<br />
}}<br />
<br />
===tileIndex() ===<br />
{{Nasal doc<br />
|syntax = tileIndex();<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1720|t=Source}}<br />
|text = Returns the index of the tile at the aircraft's current position as a string. This corresponds to the name of the STG file of the tile. For example, at [[KSFO]], this would be <code>942050</code>, corresponding to <tt>''[[$FG_SCENERY]]/Terrain/w130n30/w123n3/942050.stg''</tt>.<br />
|example1 = print(tileIndex()); # print index<br />
}}<br />
<br />
=== tilePath()===<br />
{{Nasal doc<br />
|syntax = tilePath();<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1712|t=Source}}<br />
|text = Returns the base path of the tile at the aircraft's current position as a string. For example, at KSFO, this would be <code>w130n30/w123n3</code>, corresponding to <tt>''[[$FG_SCENERY]]/Terrain/w130n30/w123n3''</tt>.<br />
|example1 = print(tilePath()); # print path<br />
}}<br />
<br />
=== values()===<br />
{{Nasal doc<br />
|syntax = values(hash);<br />
|source = {{fgdata file|Nasal/globals.nas|t=Source}}<br />
|text = Returns a vector containing the values of the given hash.<br />
|param1 = hash<br />
|param1text = Mandatory hash to get the values of.<br />
|example1 = var hash = {<br />
"a": 1,<br />
"b": 2,<br />
"c": 3<br />
};<br />
<br />
foreach(var val; values(hash)){<br />
print(val);<br />
}<br />
|example2text = The below example does exactly the same thing as the above example, but does not use <code>values()</code>:<br />
|example2 = var hash = {<br />
"a": 1,<br />
"b": 2,<br />
"c": 3<br />
};<br />
<br />
foreach(var key; keys(hash)){<br />
print(hash[key]);<br />
<nowiki>}</nowiki><br />
}}<br />
<br />
==Extension functions new in FG 2020.1 ==<br />
The following functions have been added to the nasal core library and will be released with FlightGear version 2020.1. <br />
Before the release they are available in the development branch "next".<br />
<br />
===isfunc()===<br />
Returns 1 if type or argument is a function, otherwise 0.<br />
<br />
===isghost()===<br />
Returns 1 if type or argument is a ghost, otherwise 0.<br />
<br />
=== ishash()===<br />
Returns 1 if type or argument is a hash, otherwise 0.<br />
<br />
===isint()===<br />
{{Nasal doc<br />
|syntax = isint(x);<br />
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}<br />
|text = Returns 1 if argument has a numeric value and x == floor(x), e.g. integer.<br />
}}<br />
<br />
===isnum()===<br />
{{Nasal doc<br />
|syntax = isnum(x);<br />
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}<br />
|text = Returns 1 if typeof(x) is "scalar" and x has a numeric value otherwise 0. <br />
}}<br />
<br />
===isscalar()===<br />
{{Nasal doc<br />
|syntax = isscalar(x);<br />
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}<br />
|text = Returns 1 if type or argument is a scalar (string or numeric), otherwise (vector, hash, func, ...) it returns 0. This is useful to check if a variable can be converted to string e.g. when useing the string concat operator "~". <br />
|example1 = var a = "foo"; <br />
var b=42;<br />
if (isscalar(a) and isscalar(b)) print(a~b);<br />
if (isstr(a)) print("a is a string");<br />
if (isint(b)) print("b is an integer");<br />
# if (isscalar(a))... is equivalent to if (typeof(a) == "scalar")...<br />
}}<br />
<br />
===isstr()===<br />
Returns 1 if type or argument is a string, otherwise 0. <br />
<br />
===isvec()===<br />
Returns 1 if type or argument is a vector, otherwise 0.<br />
<br />
===vecindex()===<br />
{{Nasal doc<br />
|syntax = vecindex(vector, value);<br />
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}<br />
|text = Returns the index of value or nil, if value is not found in vector.<br />
|example1=<br />
var myvector = ["apple", "bananna", "coconut"];<br />
# to check if a vector contains a certain value compare vecindex to nil<br />
if (vecindex(myvector, "apple") != nil) {<br />
print("found apple");<br />
}<br />
# WARNING: this will not work as desired because index is 0<br />
if (vecindex(myvector, "apple")) {<br />
print("found apple");<br />
<nowiki>}</nowiki><br />
<br />
}}<br />
<br />
==Variables==<br />
Various global constants (technically variables) are provided for use in converting between different units. They are all found in {{fgdata file|Nasal/globals.nas|text=$FG_ROOT/Nasal/globals.nas}}.<br />
<br />
===D2R===<br />
{{Nasal doc<br />
|syntax = var radians = degrees * D2R;<br />
|text = Converts an angle from degrees to radians when multiplied by the angle in degrees. Equal to <code>π / 180</code>.<br />
}}<br />
===FPS2KT===<br />
{{Nasal doc<br />
|syntax = var knots = feet_per_second * FPS2KT;<br />
|text = Converts a velocity from feet per second to knots when multiplied by the velocity in feet per second. Approximately equal to 0.5925.<br />
}}<br />
===FT2M===<br />
{{Nasal doc<br />
|syntax = var metres = feet * FT2M;<br />
|text = Converts a length from feet to metres when multiplied by the length in feet. Equal to 0.3048.<br />
}}<br />
===GAL2L ===<br />
{{Nasal doc<br />
|syntax = var litres = gallons * GAL2L;<br />
|text = Converts a volume from US liquid gallons to litres when multiplied by the volume in gallons. Approximately equal to 3.7854.<br />
}}<br />
===IN2M===<br />
{{Nasal doc<br />
|syntax = var metres = inches * IN2M;<br />
|text = Converts a length from inches to metres when multiplied by the length in inches. Equal to 0.0254.<br />
}}<br />
===KG2LB===<br />
{{Nasal doc<br />
|syntax = var pounds = kilograms * KG2LB;<br />
|text = Converts a mass from kilograms to pounds when multiplied by the mass in kilograms. Approximately equal to 2.2046.<br />
}}<br />
===KT2FPS===<br />
{{Nasal doc<br />
|syntax = var feet_per_second = knots * KT2FPS;<br />
|text = Converts a velocity from knots to feet per second when multiplied by the velocity in knots. Approximately equal to 1.6878.<br />
}}<br />
===KT2MPS===<br />
{{Nasal doc<br />
|syntax = var metres_per_second = knots * KT2MPS;<br />
|text = Converts a velocity from knots to metres per second when multiplied by the velocity in knots. Approximately equal to 0.5144.<br />
}}<br />
===L2GAL===<br />
{{Nasal doc<br />
|syntax = var gallons = litres * L2GAL;<br />
|text = Converts a volume from litres to US liquid gallons when multiplied by the volume in litres. Approximately equal to 0.2642.<br />
}}<br />
===LB2KG===<br />
{{Nasal doc<br />
|syntax = var kilograms = pounds * LB2KG;<br />
|text = Converts a mass from pounds to kilograms when multiplied by the mass in pounds. Approximately equal to 0.4536.<br />
}}<br />
===M2FT ===<br />
{{Nasal doc<br />
|syntax = var feet = metres * M2FT;<br />
|text = Converts a length from metres to feet when multiplied by the length in metres. Approximately equal to 3.2808.<br />
}}<br />
===M2IN===<br />
{{Nasal doc<br />
|syntax = var inches = metres * M2IN;<br />
|text = Converts a length from metres to inches when multiplied by the length in metres. Approximately equal to 39.3701.<br />
}}<br />
===M2NM ===<br />
{{Nasal doc<br />
|syntax = var nautical_miles = metres * M2NM;<br />
|text = Converts a length from metres to nautical miles when multiplied by the length in metres. Approximately equal to 0.00054.<br />
}}<br />
===MPS2KT ===<br />
{{Nasal doc<br />
|syntax = var knots = metres_per_second * MPS2KT;<br />
|text = Converts a velocity from metres per second to knots when multiplied by the velocity in metres per second. Approximately equal to 1.9438.<br />
}}<br />
===NM2M ===<br />
{{Nasal doc<br />
|syntax = var metres = nautical_miles * NM2M;<br />
|text = Converts a length from nautical miles to metres when multiplied by the length in nautical miles. Equal to 1,852.<br />
}}<br />
===R2D===<br />
{{Nasal doc<br />
|syntax = var degrees = radians * R2D;<br />
|text = Converts an angle from radians to degrees when multiplied by the angle in radians. Equal to <code>180 / π</code>.<br />
}}<br />
<br />
{{Appendix}}<br />
<br />
<br />
{{Nasal namespaces}}</div>Clm76https://wiki.flightgear.org/w/index.php?title=Nasal_library&diff=138565Nasal library2023-10-30T09:59:42Z<p>Clm76: /* findNavaidsByFrequencyMHz() */</p>
<hr />
<div>{{Nasal Navigation|nocat=1}}<br />
This page documents the global '''library functions and variables''' 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, the ''[[#Extension functions|extension functions]]'', which have been subsequently added, and are specifically designed for FlightGear, and the ''[[#variables|global variables]]'', which are conversion variables, added with extension functions, for converting between units. The relevant folders in [[Git]] are:<br />
* {{flightgear file|src/Scripting}}<br />
* {{simgear file|simgear/nasal}}<br />
<br />
All these functions and variables are in the global namespace, that is, they are directly accessible (e.g., one can call <syntaxhighlight lang="nasal" inline>magvar()</syntaxhighlight> instead of <syntaxhighlight lang="nasal" inline>namespace.magvar()</syntaxhighlight>). However, if a namespace must be used, <code>globals</code> is the correct namespace, but using it is not recommended. For a more complete explanation, see [[Nasal Namespaces in-depth]].<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|printerror()|debug}}.<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.<br />
<br />
The result is a four-element vector containing '''[0]''' a hash of local variables, '''[1]''' the function object, '''[2]''' the full source file name (incl. path) and '''[3]''' the line number. <br />
|param1 = level<br />
|param1text = Optional integer specifying the stack level to return a result from. Defaults to 1 (i.e. 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 lang="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 />
<br />
===contains()===<br />
{{Requires commit|desc=Vector support|details=see {{Merge-request|project=fgdata|id=305}}|commit=ee39abbd3b70c9b6d5e3a1c4ccedddaac1a92b11|repo=Simgear}}<br />
{{Nasal doc<br />
|syntax = contains(vector, item);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=184|t=Source}}<br />
|text = Returns 1 (True) if the vector contains the specified item, or 0 (False) if not.<br />
|param1 = vector<br />
|param1text = The vector to search in.<br />
|param2 = item<br />
|param2text = The object to be searched for in the vector.<br />
|example1 =<br />
# Initialize a hash<br />
var vec = ["element", "foo"];<br />
print(contains(hash, "element") ? "Yes" : "No"); # This will print "Yes"<br />
|example2 =<br />
# Initialize a hash<br />
var vec = ["element", "foo"];<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 NOT identical to setting the hash value specified by the key to <code>'''nil'''</code> as the key will stay in the hash (at least for a while). 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 />
|commit = {{simgear commit|bd7163|t=commit}}<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 />
|commit = {{simgear commit|bd7163|t=commit}}<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()|link=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 />
|example2text = 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 />
|example3text = This example sorts a vector of strings (runways for example) from smallest to greatest.<br />
|example3 = <br />
var runways = ["09R","27R","26L","09L","15"];<br />
var rwy = sort(runways,func(a,b) cmp(a,b));<br />
debug.dump(rwy); # prints ['09L','09R','15','26L','27R']<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 = <nowiki>sprintf(format[, arg[, arg, [...]]]);</nowiki><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()|link=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. This includes the decimal point and decimal fraction as well as + or - signs.<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>s</code> {{!!}} A string<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 />
|example10 =<br />
print(sprintf("%.2f", 1.4)); #prints "1.40"<br />
print(sprintf("%.1f", 1.4)); #prints "1.4"<br />
print(sprintf("% 4.1f", 1.4)); #prints " 1.4"<br />
print(sprintf("%04.1f", 1.4)); #prints "01.4"<br />
print(sprintf("% 6.1f", 1.4)); #prints " 1.4"<br />
print(sprintf("%06.1f", 1.4)); #prints "0001.4"<br />
}}<br />
<br />
===streq()===<br />
{{Nasal doc<br />
|syntax = streq(a, b);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=129|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. Negative values specify a position from the end of the string.<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 />
|example4 = print(substr("abcde", -2)); # prints "de"<br />
|example5 = print(substr("abcde", -3, 2)); # prints "cd"<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 />
* Omitting the ''vector'' and ''start'' arguments is not an error (possibly it should be) but the return value is ''nil''.<br />
* A negative ''start'' argument ''is'' an error. This seems wrong. Perhaps the language designer could comment.<br />
* A value of ''start'' greater than ''size(vector)'' causes an error. A value equal to ''size(vector)'' returns an empty vector.<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 />
|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 modules ==<br />
=== thread ===<br />
{{WIP}}<br />
<br />
{{Nasal doc<br />
|syntax = thread.newthread(func);<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = start a new worker thread<br />
|example1 = thread.newthread( func() {} );<br />
}}<br />
<br />
{{Nasal doc<br />
|syntax = thread.newlock();<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = create a new lock<br />
|example1 = var lock = thread.newlock()<br />
}}<br />
<br />
{{Nasal doc<br />
|syntax = thread.lock();<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = lock a lock<br />
|example1 = var lock = thread.newlock()<br />
}}<br />
<br />
{{Nasal doc<br />
|syntax = thread.unlock();<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = unlock a lock<br />
|example1 = var lock = thread.unlock()<br />
}}<br />
<br />
<br />
{{Nasal doc<br />
|syntax = thread.newsem();<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = create a new {{Wikipedia|semaphore}}<br />
|example1 = var semaphore = thread.newsem()<br />
}}<br />
<br />
<br />
{{Nasal doc<br />
|syntax = thread.semdown();<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = semaphore down<br />
|example1 = thread.semdown(semaphore)<br />
}}<br />
<br />
<br />
{{Nasal doc<br />
|syntax = thread.semup();<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = semaphore up<br />
|example1 = thread.semup(semaphore)<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()|link=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 />
===aircraftToCart() ===<br />
This new function in FG 2017.2.1 takes coordinates in aircraft structural coordinate system, and translate them into geocentric coordinates.<br />
Example for (5,6,7):<br />
<syntaxhighlight lang="nasal"><br />
var pos = aircraftToCart({x: -5, y: 6, z: -7});<br />
var coord = geo.Coord.new();<br />
coord.set_xyz(pos.x, pos.y, pos.z);<br />
</syntaxhighlight><br />
Notice: x and z is inverted sign on purpose.<br />
if you want lat. lon, alt from that, just call: (degrees and meters)<br />
<br />
<syntaxhighlight lang="nasal"><br />
coord.lat()<br />
coord.lon()<br />
coord.alt()<br />
</syntaxhighlight><br />
<br />
===addcommand() ===<br />
{{Nasal doc<br />
|syntax = addcommand(name, code);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=659|t=Source}}<br />
|version = 2.12<br />
|commit = {{flightgear commit|7b663c|t=commit}}<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(node) {<br />
print("fgcommand 'myFGCmd' has been run.");<br />
props.dump( node );<br />
});<br />
fgcommand("myFGCmd", props.Node.new({foo:1, bar:2}) );<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 />
* '''parents''': A vector containing a hash of various functions to access information about the runway. See {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2659}} for full list.<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 />
*** '''id''': Name of runway.<br />
*** '''lat''': Latitude of the runway.<br />
*** '''lon''': Longitude of the runway.<br />
*** '''heading''': Heading of the runway.<br />
*** '''length''': Length of the runway in metres.<br />
*** '''width''': Width of the runway in metres.<br />
*** '''surface''': Runway surface type.<br />
*** '''threshold''': Length of the runway's {{wikipedia|displaced threshold}} in metres. Will return 0 if there is none.<br />
*** '''stopway''': Length of the runway's stopway (the area before the threshold) in metres. Will return 0 if there is none.<br />
*** '''reciprocal''': <code>runway</code> ghost of the reciprocal runway.<br />
*** '''ils_frequency_mhz''': ILS frequency in megahertz.<br />
*** '''ils''': <code>navaid</code> ghost of the ILS transmitter.<br />
* '''helipads'''<br />
** '''<helipad name>'''<br />
*** '''id''': Name of helipad.<br />
*** '''lat''': Latitude of the helipad.<br />
*** '''lon''': Longitude of the helipad.<br />
*** '''heading''': Heading of the helipad.<br />
*** '''length''': Length of the helipad in metres.<br />
*** '''width''': Width of the helipad in metres.<br />
*** '''surface''': Helipad surface type.<br />
* '''taxiways'''<br />
** '''<taxiway name>'''<br />
*** '''id''': Name of taxiway.<br />
*** '''lat''': Latitude of the taxiway.<br />
*** '''lon''': Longitude of the taxiway.<br />
*** '''heading''': Heading of the taxiway.<br />
*** '''length''': Length of the taxiway in metres.<br />
*** '''width''': Width of the taxiway in metres.<br />
*** '''surface''': Taxiway surface type.<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 />
<nowiki>}</nowiki><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 />
<nowiki>}</nowiki><br />
}}<br />
<br />
===airway()===<br />
<br />
{{Nasal doc<br />
|syntax = airway(ident [, pos]);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2644|t=Source}}<br />
|text = {{see also|Nasal Flightplan}}<br />
This function returns a ghost containing an airway of a specified id.<br />
|param1 = ident<br />
|param1text = a Positioned ghost (leg, navaid, airport) and so on, passed to the search function.<br />
|param2 = pos<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 />
|commit = {{fgdata commit|8b16a7|t=commit}}<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 with geodetic coordinates (cartesian coordinates will not be accepted)<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 />
===createFlightplan()===<br />
{{Nasal doc<br />
|syntax = createFlightplan(path);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2331|t=Source}}<br />
|text = Creates an empty flightplan object. It accepts one argument, ''path'' passed an absolute path to a .fgfp / .gpx file, it will populate the flightplan with waypoints from the file.<br />
|param1 = path<br />
|param1text = Optional parameter defining the file from which a flightplan will be populated.<br />
|example1 = <br />
var path = getprop("/sim/fg-home") ~ "/Export/test.fgfp";<br />
var flightplan = createFlightplan(path);<br />
debug.dump(flightplan);<br />
}}<br />
<br />
===createDiscontinuity()===<br />
{{Nasal doc<br />
|syntax = createDiscontinuity();<br />
|text = Returns a <code>waypoint</code> ghost object. A route discontinuity is inserted by an {{abbr|FMS|Flight Management System}} when it is unsure how to connect two waypoints.<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2045|t=Source}}<br />
|version = 2016.1<br />
|commit = {{flightgear commit|caead6|t=commit}}<br />
}}<br />
===createViaTo()===<br />
{{Nasal doc<br />
|syntax = createViaTo(airway, waypoint);<br />
|text = Returns a <code>waypoint</code> ghost object. It represents a route "via '''airway''' to '''waypoint'''".<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2009|t=Source}}<br />
|version = 2016.1<br />
|commit = {{flightgear commit|caead6|t=commit}}<br />
|param1 = airway<br />
|param1text = The name of an airway.<br />
|param2 = waypoint<br />
|param2text = Must be in the airway and one of:<br />
* The name of a waypoint.<br />
* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, or <code>fix</code> ghost object.<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 />
<nowiki>}</nowiki><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 />
<nowiki>}</nowiki><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 />
===findNavaidByFrequencyMHz()===<br />
{{Nasal doc<br />
|syntax = findNavaidByFrequencyMHz([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 = findNavaidByFrequencyMHz(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 />
=== findNavaidsByFrequencyMHz()===<br />
{{Nasal doc<br />
|syntax = findNavaidsByFrequencyMHz([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>findNavaidsByFrequencyMHz(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 = findNavaidsByFrequencyMHz(109.55);<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 / 100), " Mhz");<br />
print("Range: ", navaid.range_nm, " nm");<br />
if(navaid.course) print("Course: ", navaid.course);<br />
print("--");<br />
<nowiki>}</nowiki><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 />
<nowiki>}</nowiki><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 />
<nowiki>}</nowiki><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 />
<nowiki>}</nowiki><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 />
=== get_cart_ground_intersection()===<br />
Introduced in 2017.2.1, see [[Terrain Detection]].<br />
<br />
===getprop()===<br />
{{Nasal doc<br />
|syntax = <nowiki>getprop(path[, path[, ...]]);</nowiki><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 = path<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 also 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 versions 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 />
<nowiki>}</nowiki><br />
}}<br />
==== See also====<br />
{{note| If you have to read/write the same property multiple times (e.g. in an update loop), it is more efficient to use a node object: <br />
To get a Node rather than its value, use <code>props.globals.getNode()</code> - see [[Nasal_library/props]]. }}<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 = <nowiki>interpolate(prop, value1, time1[, value2, time2[, ...]]);</nowiki><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 />
<nowiki>}</nowiki><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 = <nowiki>logprint(priority[, msg[, msg[, ...]]]);</nowiki><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 from the Nasal file itself rather than from {{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 />
{{note| <br />
The following constants have been added to the development branch of FlightGear ("next") and will be releases with FG 2020.1 so you won't have to remember the numbers anymore:<br />
<br />
LOG_BULK, LOG_WARN, LOG_DEBUG, LOG_INFO, LOG_ALERT, DEV_WARN, DEV_ALERT }}<br />
<br />
===magvar() ===<br />
{{Nasal doc<br />
|syntax = magvar([pos]);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1642|t=Source}}<br />
|text = Returns the {{wikipedia|magnetic variation}} at a given set of coordinates. The table below gives the magnetic model used depending on the version of FlightGear.<br />
{{{!}} class="wikitable"<br />
! FlightGear versions !! Model !! Reference date<br />
{{!-}}<br />
{{!}} 3.6 and above {{!!}} {{wikipedia|World Magnetic Model}} (WMM) 2015 {{!!}} 1 January 2015<br />
{{!-}}<br />
{{!}} 0.9.11-pre1 to 3.4 {{!!}} WMM 2005 {{!!}} 1 January 2005<br />
{{!-}}<br />
{{!}} 0.7.3 to 0.9.10 {{!!}} WMM 2000 {{!!}} 1 January 2000<br />
{{!}}}<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>magvar(lat,lon)</code>.<br />
|example1 = print(magvar(0, 0)); # prints the magnetic variation at 0, 0<br />
}}<br />
<br />
===maketimer() ===<br />
{{Nasal doc<br />
|syntax = maketimer(interval[, self], function);<br />
|source = ''Implemented using the {{API Link|flightgear|class|TimerObj}} class.''<br>{{flightgear file|src/Scripting/NasalSys.cxx|l=90|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=533|t=Part 2}}<br />
|version = 2.12<br />
|commit = {{flightgear commit|ab939f|t=commit}}<br />
|text = Returns a timer object containing the following methods and members:<br />
* '''start()''': Starts the timer.<br />
* '''stop()''': Stops the timer.<br />
* '''restart(interval)''': Restarts the timer with the given interval.<br />
* '''singleShot''': Bool showing whether the timer is only to be run once, or continuously until told to stop. Can be both set and read from (see examples).<br />
* '''isRunning''': Read-only bool telling whether the timer is currently running.<br />
* '''simulatedTime''': (FG 2017.1+; {{flightgear commit|0af316|t=commit}}) Bool telling whether the timer is using simulated time (which accounts for pause, etc.). Defaults to false (use real time). Can be both read and set. This cannot be changed while the timer is running.<br />
Unlike {{func link|settimer()}}, which it replaces, <code>maketimer()</code> provides more control over the timer. In addition, it can help reduce memory usage.<br />
|param1 = interval<br />
|param1text = Interval in seconds for the timer.<br />
|param2 = self<br />
|param2text = Optional parameter specifying what any <code>'''me'''</code> references in the function being called will refer to.<br />
|param3 = function<br />
|param3text = Function to be called at the given interval.<br />
|example1 = var timer = maketimer(1, func(){<br />
print("Hello, World!"); # print "Hello, World!" once every second (call timer.stop() to stop it)<br />
});<br />
timer.start();<br />
|example2 = var timer = maketimer(1, math, func(){<br />
print(me.math); # 'me' reference is the 'math' namespace<br />
});<br />
timer.singleShot = 1; # timer will only be run once<br />
timer.start();<br />
|example3 = var timer = maketimer(1, func(){<br />
print("Hello, World!"); # print "Hello, World!" once every second (call timer.stop() to stop it)<br />
});<br />
timer.start();<br />
print(timer.isRunning); # prints 1<br />
|example4text = In the example below, "Hello, World!" will be printed after one second the first time, and after two seconds thereafter.<br />
|example4 = var update = func(){<br />
print("Hello, World!");<br />
timer.restart(2); # restarts the timer with a two second interval<br />
}<br />
<br />
var timer = maketimer(1, update);<br />
timer.singleShot = 1;<br />
timer.start();<br />
}}<br />
<br />
===maketimestamp()===<br />
{{Nasal doc<br />
|syntax = maketimestamp()<br />
|source = ''Implemented using the {{API Link|flightgear|class|TimeStampObj}} class.''<br>{{flightgear file|src/Scripting/NasalSys.cxx|l=214|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=589|t=Part 2}}<br />
|version = 2019.2<br />
|commit = {{flightgear commit|7db06300|t=commit}}<br />
|text = Returns a time stamp object to allow high resolution timing of Nasal operations. When created the timer will automatically be stamped. The object has the following methods:<br />
* '''stamp()''': Resets the timing operation. Call this first.<br />
* '''elapsedMSec()''': returns number of milliseconds elapsed since stamp() called. Resolution may vary depending on platform but is usually at least millisecond accuracy.<br />
* '''elapsedUSec()''': returns number of microseconds elapsed since stamp() called. Resolution may vary depending on platform but is usually at least millisecond accuracy.<br />
|<br />
|example1text = In the example below the number of milliseconds elapsed will be printed.<br />
|example1 = var timestamp = maketimestamp();<br />
timestamp.stamp();<br />
print(timestamp.elapsedMSec(), "ms elapsed");<br />
print(timestamp.elapsedMSec(), "ms elapsed");<br />
}}<br />
<br />
===md5()===<br />
{{Nasal doc<br />
|syntax = md5(string);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=758|t=Source}}<br />
|version = 3.2<br />
|commit = {{flightgear commit|cfbf9e|t=commit}}<br />
|text = Returns a the {{wikipedia|MD5}} hash (as a string) of the inputted string.<br />
|param1 = string<br />
|param1text = String the generate the hash of. Mandatory.<br />
|example1text = The below code should output <code>65a8e27d8879283831b664bd8b7f0ad4</code>.<br />
|example1 = print(md5("Hello, World!"));<br />
}}<br />
<br />
===navinfo()===<br />
{{Nasal doc<br />
|syntax = navinfo(lat, lon, type, id);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1453|t=Source}}<br />
|text = Returns vector <code>navaid</code> ghost objects matching the given '''type''' and '''id''' or <code>'''nil'''</code> on error.<br />
|param1 = lat ''and'' lon<br />
|param1text = If given, the returned navaids will be put into order of ascending distance from the location.<br />
|param2 = type<br />
|param2text = Narrows the search to the given type. Must be one of "any," "fix," "vor," "ndb," "ils," "dme," or "tacan." Defaults to the equivalent of "any."<br />
|param3 = id<br />
|param3text = ID to search for. Note that, although all the parameters are technically optional, this parameter must be given, otherwise an empty vector will be returned.<br />
|example1 = navinfo("vor"); # returns all VORs<br />
|example2 = navinfo("HAM"); # return all navaids whose names start with "HAM"<br />
|example3 = navinfo("vor", "HAM"); # return all VORs whose names start with "HAM"<br />
|example4 = navinfo(34,48,"vor","HAM"); # return all VORs whose names start with "HAM" and sorted by distance relative to 34°, 48°<br />
}}<br />
<br />
===parse_markdown()===<br />
{{Nasal doc<br />
|syntax = parse_markdown(markdown);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=745|t=Part 1}} {{!}} {{simgear file|simgear/misc/SimpleMarkdown.cxx|t=Part 2}} <br />
|version = 3.2<br />
|text = Parses a string containing {{wikipedia|Markdown}} and returns the result as a string. As of FlightGear 2016.1, it is just a simple parser, and does the following:<br />
* It strips whitespace from the beginning of the string.<br />
* It supports [http://daringfireball.net/projects/markdown/syntax#p paragraphs and line breaks].<br />
* It collapses whitespace.<br />
* It converts unordered [http://daringfireball.net/projects/markdown/syntax#list lists] to use a bullet character (&bull;). Note that the bullet character is implemented in hexadecimal UTF-8 character bytes (<code>E2 80 A2</code>), as so may not work properly when the being displayed in an encoding other than UTF-8.<br />
|param1 = markdown<br />
|param1text = String containing Markdown to be parsed.<br />
|example1text = <br />
Save the below code as <tt>''[[$FG_ROOT]]/gui/dialogs/test.xml''</tt>, then run the Nasal code below it to open the dialog. To change the markdown to be parsed, simply change the code in the highlighted section, save it, and reload the GUI (<tt>Debug > Reload GUI</tt>).<br />
<syntaxhighlight lang="xml" highlight="41-50"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<br />
<PropertyList><br />
<br />
<name>test</name><br />
<layout>vbox</layout><br />
<br />
<group><br />
<layout>hbox</layout><br />
<br />
<empty><br />
<stretch>true</stretch><br />
</empty><br />
<br />
<text><br />
<label>parse_markdown() test dialog</label><br />
</text><br />
<br />
<empty><br />
<stretch>true</stretch><br />
</empty><br />
<br />
<button><br />
<legend></legend><br />
<pref-width>16</pref-width><br />
<pref-height>16</pref-height><br />
<binding><br />
<command>dialog-close</command><br />
</binding><br />
</button><br />
<br />
</group><br />
<br />
<canvas><br />
<name>Canvas plot</name><br />
<stretch>true</stretch><br />
<pref-width>400</pref-width><br />
<pref-height>300</pref-height><br />
<nasal><br />
<load><![CDATA[<br />
var text = 'Items:<br />
* apples<br />
* oranges<br />
* pears<br />
<br />
Some text.<br />
Some more items:<br />
* apples<br />
* oranges<br />
* pears';<br />
<br />
var parsed = parse_markdown(text);<br />
<br />
var root_canvas = canvas.get(cmdarg());<br />
root_canvas.setColorBackground(255, 255, 255);<br />
var root = root_canvas.createGroup();<br />
<br />
var text_dis = root.createChild("text")<br />
.setText(parsed)<br />
.setTranslation(5, 5)<br />
.setFont("LiberationFonts\LiberationSans-Regular.ttf")<br />
.setFontSize(15)<br />
.setColor(0, 0, 0)<br />
.setDrawMode(canvas.Text.TEXT)<br />
.setAlignment("left-top");<br />
]]></load><br />
</nasal><br />
</canvas><br />
<br />
</PropertyList><br />
</syntaxhighlight><br />
|example1 = fgcommand("dialog-show", {"dialog-name": "test"});<br />
|example2text = The example below parses Markdown and outputs it in a HTML document. The parsed text is placed in <syntaxhighlight lang="xml" inline><pre></pre></syntaxhighlight> tags. To change the Markdown to be parsed, simply edit the variable <tt>markdown</tt> at the top of the code.<br />
|example2 = <nowiki>var markdown = 'Items:<br />
* apples<br />
* oranges<br />
* pears<br />
<br />
Some text.<br />
Some more items:<br />
* apples<br />
* oranges<br />
* pears';<br />
<br />
var parsed = parse_markdown(markdown);<br />
<br />
debug.dump(parsed);<br />
<br />
var path = string.normpath(getprop("/sim/fg-home") ~ '/Export/parse_markdown()-test.html');<br />
<br />
var file = io.open(path, "w");<br />
<br />
var html = "<!DOCTYPE html>\n\n<html>\n\n<head>\n\t<meta charset=\"UTF-8\">\n\t<title>parse_markdown() test generated by Nasal</title>\n</head>\n\n<body>\n\t<pre>" ~ parsed ~ "</pre>\n</body>\n\n</html>";<br />
<br />
io.write(file, html);<br />
io.close(file);<br />
print("Done, file ready for viewing (" ~ path ~ ")");</nowiki><br />
}}<br />
<br />
===parsexml()===<br />
{{Nasal doc<br />
|syntax = <nowiki>parsexml(path[, start[, end[, data[, pro_ins]]]]);</nowiki><br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=710|t=Source}}<br />
|text = This function is an interface into the built-in [http://expat.sourceforge.net/ Expat XML parser]. The absolute path to the file is returned as string, or <code>'''nil'''</code> is returned on error.<br />
|param1 = path<br />
|param1text = Mandatory absolute path to the XML file to be parsed.<br />
|param2 = start<br />
|param2text = Optional callback function that will be called for every starting tag. The function should take two argument: the tag name and a hash containing attributes.<br />
|param3 = end<br />
|param3text = Optional callback function that will be called for every ending tag. The function should take one argument: the tag name.<br />
|param4 = data<br />
|param4text = Optional callback function that will be called for every piece of data within a set of tags. The function should take one argument: the data as a string.<br />
|param5 = pro_ins<br />
|param5text = Optional callback function that will be called for every {{wikipedia|Processing Instruction|processing instruction}}. The function should take two argument: the target and the data string.<br />
|example1text = Save the below XML code in <tt>''[[$FG_HOME]]/Export/demo.xml''</tt>. Then, execute the Nasal code below in the Nasal Console. The XML will be parsed and each bit of the code will be printed.<br />
<syntaxhighlight lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<br />
<?xml-stylesheet type="text/xsl" href="style.xsl"?><br />
<br />
<foo><br />
<blah type="string"><![CDATA[ <sender>John Smith</sender> ]]></blah><br />
<blah2 type="string">Orange &amp; lemons</blah2><br />
</foo><br />
</syntaxhighlight><br />
|example1 = 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 />
}<br />
<br />
var end = func(name){<br />
print("Ending tag: '", name, "'");<br />
}<br />
<br />
var data = func(data){<br />
print("Data = '", data, "'");<br />
}<br />
<br />
var pro_instr = func(target, data){<br />
print("Processing instruction: target = '", target, "', data = '", data, "'");<br />
}<br />
<br />
parsexml(getprop("/sim/fg-home") ~ '/Export/demo.xml', start, end, data, pro_instr);<br />
}}<br />
<br />
===print()===<br />
{{Note|As of 07/2020, we are in the process of slowly deprecating and removing Nasal print() (in fgdata) where possible in favor of log [[#logprint()]] which takes a priority level.<br />
<br />
This is part of the goal that we achieve zero output at log-level at alert, and everything shown at ‘warn; is really a warning, not just information.<ref>https://sourceforge.net/p/flightgear/mailman/message/37042224/</ref>}}<br />
<br />
{{Nasal doc<br />
|syntax = <nowiki>print(data[, data[, ...]]);</nowiki><br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=415|t=Source}}<br />
|text = Concatenates its arguments and then prints it to the terminal and the [[Commonly used debugging tools#fgfs.log|log]]. Note that a newline is automatically added.<br />
|param1 = data<br />
|param1text = Data to print. Only strings and numbers can be printed; other data types will not be. There many be any number of arguments; they will just be concatenated together.<br />
|example1 = print("Just", " a ", "test"); # prints "Just a test"<br />
|example2 = print("pi = ", math.pi); # prints "pi = 3.141592..."<br />
}}<br />
<br />
=== printf() ===<br />
{{Nasal doc<br />
|syntax = <nowiki>printf(format[, arg[, arg, [...]]]);</nowiki><br />
|source = {{fgdata file|Nasal/globals.nas|t=Source}}<br />
|text = Creates and prints a formatted string. For a description of its arguments, see {{func link|sprintf()}} (it is, in fact, implemented using <code>sprintf()</code>).<br />
|example1 = printf("In hexadecimal, 100000 = %X", 186A0); # prints "In hexadecimal, 100000 = 186A0"<br />
}}<br />
<br />
===printlog()===<br />
{{Nasal doc<br />
|syntax = <nowiki>printlog(level, data[, data[, ...]]);</nowiki><br />
|source = {{fgdata file|Nasal/globals.nas|t=Source}}<br />
|text = Prints the given message with the given log level. If the log level is higher or equal to <code>/sim/logging/priority</code>, it is printed.<br />
|param1 = level<br />
|param1text = Mandatory log level as a string. Must be one of "none," "bulk," "debug," "info," "warn," or "alert." Note that "none" will mean that the message will never be printed.<br />
|param2 = data<br />
|param2text = Data to be printed. Only strings and numbers will be printed; others will not be. There may be any number of arguments; they will just be concatenated together.<br />
|example1 = printlog("alert", "This is an alert"); # message will be printed<br />
|example2 = printlog("info", "Just informing you about something"); # message will be printed only if log level is set to "info" or less<br />
}}<br />
<br />
===rand()===<br />
{{Nasal doc<br />
|syntax = rand();<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=554|t=Source}}<br />
|text = Returns a random floating point number between 0 (inclusive) and 1 (exclusive). It takes no arguments.<br />
|example1 = print(rand()); # prints random number<br />
}}<br />
<br />
===registerFlightPlanDelegate()===<br />
{{Nasal doc<br />
|syntax = registerFlightPlanDelegate(init_func);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1879|t=Source}}<br />
|text = Registers a flight plan delegate. See <tt>''{{fgdata file|Nasal/route_manager.nas|t=$FG_ROOT/Nasal/route_manager.nas}}''</tt> for examples.<br />
|param1 = init_func<br />
|param1text = Initialization function which will be called during FlightGear's startup.<br />
}}<br />
===removecommand()===<br />
{{Nasal doc<br />
|syntax = removecommand(cmd);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=668|t=Source}}<br />
|text = Removes the given fgcommand. Returns <code>'''nil'''</code>.<br />
{{caution|This will remove '''any''' [[fgcommands|fgcommand]], even those implemented in C++, so use with caution!}}<br />
|param1 = cmd<br />
|param1text = String specifying the name of the command to remove.<br />
|example1 = addcommand("hello", func(){<br />
print("Hello");<br />
});<br />
fgcommand("hello"); # "Hello" will be printed<br />
removecommand("hello"); # removes it<br />
}}<br />
<br />
===removelistener()===<br />
{{Nasal doc<br />
|syntax = removelistener(id);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=1384|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=506|t=Part 2}}<br />
|text = Removes and deactivates the given listener and returns the number of listeners left or <code>'''nil'''</code> on error.<br />
{{note|It is good practice to remove listeners when they are not required anymore. This prevents the listeners reducing FlightGear's run performance.}}<br />
|param1 = id<br />
|param1text = ID of listener as returned by {{func link|setlistener()}}.<br />
|example1 = var ls = setlistener("/sim/test", func(){<br />
print("Property '/sim/test' has been changed");<br />
});<br />
setprop("/sim/test", "blah"); # trigger listener<br />
var rem = removelistener(ls); # remove listener<br />
print("There are ", rem, " listeners remaining");<br />
}}<br />
<br />
===resolvepath()===<br />
{{Nasal doc<br />
|syntax = resolvepath(path);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=604|t=Source}}<br />
|text = Takes a relative path as a string and uses [[SimGear]]'s path-resolving framework to return an absolute path as a string. If the path could not be resolved, an empty string is returned. See [[Resolving Paths]] for a detailed description of the algorithm. This function can also be used to check if a file exists.<br />
|param1 = path<br />
|param1text = Relative path to be completed.<br />
|example1 = print(resolvepath("Nasal/globals.nas")); # prints the equivalent of $FG_ROOT/Nasal/globals.nas<br />
|example2 = print(resolvepath("blah")); # prints nothing; could not be resolved<br />
|example3 = var file_path = resolvepath("Aircraft/SenecaII/some-file");<br />
if (file_path != ""){<br />
gui.popupTip("some-file found", 2);<br />
} else {<br />
gui.popupTip("some-file not found", 2);<br />
<nowiki>}</nowiki><br />
}}<br />
<br />
===setlistener()===<br />
{{Nasal doc<br />
|syntax = <nowiki>setlistener(node, code[, init[, type]]);</nowiki><br />
|private = _setlistener()<br />
|source = {{flightgear file|src/Scripting/Nasal|l=499|t=Part 1}} {{!}} {{flightgear file|src/Scripting/Nasal|l=1350|t=Part 2}}<br>''Listener implemented using the {{API Link|flightgear|class|FGNasalListener}} class.''<br />
|text = Creates a listener which will be triggered when the given property is changed (depending on the '''type'''). A unique integer ID is returned; this can later be used as the argument to {{func link|removelistener()}}.<br />
{{note|Listeners are known to be a source of resource leaks. To avoid this, please take measures such as:<br />
* Using {{func link|removelistener()}} when they are not needed any more.<br />
* Using a single initialization listener.<br />
* Avoiding tying listeners to properties that are rapidly updated (e.g., many times per frame).<br />
}}<br />
|param1 = node<br />
|param1text = Mandatory string or <code>props.Node</code> object pointing to a property in the [[Property Tree]].<br />
|param2 = code<br />
|param2text = Mandatory callback function to execute when the listener is triggered. The function can take up to four arguments in the following order:<br />
* '''changed''': a <code>props.Node</code> object pointing to the changed node.<br />
* '''listen''': a <code>props.Node</code> object pointing to the listened-to node. Note that this argument maybe different depending on the '''type'''.<br />
* '''mode''': an integer telling how the listener was triggered. 0 means that the value was changed. 1 means that a child property was added. -1 means that a child property was removed.<br />
* '''is_child''': boolean telling whether '''changed''' is a child property of the listened-to '''node''' or not. 1 (true) if it is, 0 (false) otherwise.<br />
|param3 = init<br />
|param3text = If set to 1 (true), the listener will additionally be triggered when it is created. This argument is optional and defaults to 0 (false).<br />
|param4 = type<br />
|param4text = Integer specifying the listener's behavior. 0 means that the listener will only trigger when the property is changed. 1 means that the trigger will always be triggered when the property is written to. 2 will mean that the listener will be triggered even if child properties are modified. This argument is optional and defaults to 1.<br />
|example1 = var prop = props.globals.initNode("/sim/test", "", "STRING"); # create property<br />
var id = setlistener("/sim/test", func(n){ # create listener<br />
print("Value: ", n.getValue());<br />
});<br />
setprop("/sim/test", "blah"); # trigger listener<br />
removelistener(id); # remove listener<br />
prop.remove(); # remove property<br />
}}<br />
<br />
===setprop()===<br />
{{Nasal doc<br />
|syntax = <nowiki>setprop(path[, path[, ...]], value);</nowiki><br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=385|t=Source}}<br />
|text = Sets the value of a property in the [[Property Tree]]. If the property does not exist, it will be created. Returns 1 (true) on success or 0 (false) if there was an error.<br />
{{note|If you want to remove a property, you will have to use one of the <code>props</code> helpers:<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 />
|param1 = path<br />
|param1text = There needs to be at least one '''path''' argument, but there is no limit to the maximum amount that can be given. They will be concatenated together to form a property tree path. The arguments must be strings, but in FlightGear v3.2 onwards, there also is support (added by {{flightgear commit|34ed79}}) for numeric arguments as indices. See example 2 below.<br />
|param2 = value<br />
|param2text = Value to write to the given property. Must be either a string or a number.<br />
|example1 = setprop("/sim/demo", "This is a demo");<br />
|example2text = Note that the example below will only work in FlightGear 3.2 and above.<br />
|example2 = for(var i = 0; i < 3; i += 1){<br />
setprop("/sim/demo", i, "Demo #" ~ i));<br />
}<br />
|example3text = Same as above, but is supported by all versions of FlightGear.<br />
|example3 = for(var i = 0; i < 3; i += 1){<br />
setprop("/sim/demo[" ~ i ~ "]", "Demo #" ~ i));<br />
<nowiki>}</nowiki><br />
}}<br />
====See also====<br />
{{note| If you have to read/write the same property multiple times (e.g. in an update loop), it is more efficient to use a node object: <br />
To get a Node rather than its value, use <code>props.globals.getNode()</code> - see [[Nasal_library/props]]. }}<br />
<br />
===settimer() ===<br />
{{Nasal doc<br />
|syntax = settimer(function, delta[, realtime]);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=499|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=1286|t=Part 2}}<br />
|text = Runs the given function a specified amount of seconds after the current time. Returns <code>'''nil'''</code>.<br />
{{note|Improper use of <code>settimer()</code> may cause resource leaks. It is also highly recommended that the newer {{func link|maketimer()}} should be used instead of this function.}} <br />
|param1 = function<br />
|param1text = Mandatory function that will be called. It may be necessary to enclose code in an anonymous function (see example).<br />
|param2 = delta<br />
|param2text = Mandatory amount of time in seconds after which the function will be called.<br />
|param3 = realtime<br />
|param3text = If 1 (true), "real time" will be used instead of "simulation time." Defaults to 0 (false). Note that if "simulation time" is used, the timer will not run while FlightGear is paused.<br />
|example1 = var myFunc = func(){<br />
print("Hello");<br />
}<br />
<br />
settimer(myFunc, 2); # runs myFunc after 2 seconds<br />
|example2 = var sqr = func(a){<br />
return a * a;<br />
}<br />
<br />
settimer(func(){<br />
print(sqr(2)); # will print 4 after 2 seconds<br />
}, 2);<br />
}}<br />
<br />
===srand() ===<br />
{{Nasal doc<br />
|syntax = srand();<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=559|t=Source}}<br />
|text = Makes the pseudorandom number generator (see {{func link|rand()}}) generate a new {{wikipedia|random seed|noicon=1}} based on time. Returns 0.<br />
}}<br />
===systime()===<br />
{{Nasal doc<br />
|syntax = systime();<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=770|t=Source}}<br />
|text = Returns the {{wikipedia|Unix time}} (seconds since since 00:00:00 UTC, 1/1/1970) as a floating point number with high resolution. This function is useful for benchmarking purposes (see example 2).<br />
{{note|1=High resolution timers under Windows can produce inaccurate or fixed sub-millisecond results.<ref>{{cite web|url=http://forum.flightgear.org/viewtopic.php?f=30&t=29259|title=Nasal: systime() ??!?|author=Necolatis|date=Apr 2nd, 2016}}</ref> This is due to the underlying {{func link|GetSystemTimeAsFileTime()|link=https://msdn.microsoft.com/en-us/library/windows/desktop/ms724397(v=vs.85).aspx}} API call, which depends on hardware availability of suitable high resolution timers. See also [https://msdn.microsoft.com/en-us/library/windows/desktop/dn553408(v=vs.85).aspx Acquiring high-resolution time stamps]}}<br />
|example1 = print("Unix time: ", systime()); # prints Unix time<br />
|example2 = var myFunc = func(){<br />
for(var i = 0; i <= 10; i += 1){<br />
print("Interation #", i);<br />
}<br />
}<br />
var t = systime(); # record time<br />
myFunc(); # run function<br />
var t2 = systime(); # record new time<br />
print("myFunc() took ", t2 - t, " seconds"); # print result<br />
}}<br />
<br />
===thisfunc()===<br />
{{Nasal doc<br />
|syntax = thisfunc();<br />
|source = {{fgdata file|Nasal/globals.nas|t=Source}}<br />
|text = Returns the function from which this function is called. This allows a function to reliably and safely call itself from within a closure.<br />
|example1 = var stringify_vec = func(input){<br />
if (typeof(input) == "scalar"){<br />
return sprintf("%s", input);<br />
} elsif (typeof(input) == "vector") {<br />
if (size(input) == 0) return "[]";<br />
var this = thisfunc();<br />
var buffer = "[";<br />
for(var i = 0; i < size(input); i += 1){<br />
buffer ~= this(input[i]);<br />
if (i == size(input) - 1) {<br />
buffer ~= "]";<br />
} else {<br />
buffer ~= ", ";<br />
}<br />
}<br />
return buffer;<br />
} else {<br />
die("stringify_vec(): Error! Invalid input. Must be a vector or scalar");<br />
}<br />
}<br />
<br />
var test_vec = ["a", "b", "c", 1, 2, 3];<br />
debug.dump(stringify_vec(test_vec)); # prints "[a, b, c, 1, 2, 3]"<br />
test_vec = [];<br />
debug.dump(stringify_vec(test_vec)); # prints "[]"<br />
test_vec = {};<br />
debug.dump(stringify_vec(test_vec)); # will throw an error<br />
}}<br />
<br />
===tileIndex() ===<br />
{{Nasal doc<br />
|syntax = tileIndex();<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1720|t=Source}}<br />
|text = Returns the index of the tile at the aircraft's current position as a string. This corresponds to the name of the STG file of the tile. For example, at [[KSFO]], this would be <code>942050</code>, corresponding to <tt>''[[$FG_SCENERY]]/Terrain/w130n30/w123n3/942050.stg''</tt>.<br />
|example1 = print(tileIndex()); # print index<br />
}}<br />
<br />
=== tilePath()===<br />
{{Nasal doc<br />
|syntax = tilePath();<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1712|t=Source}}<br />
|text = Returns the base path of the tile at the aircraft's current position as a string. For example, at KSFO, this would be <code>w130n30/w123n3</code>, corresponding to <tt>''[[$FG_SCENERY]]/Terrain/w130n30/w123n3''</tt>.<br />
|example1 = print(tilePath()); # print path<br />
}}<br />
<br />
=== values()===<br />
{{Nasal doc<br />
|syntax = values(hash);<br />
|source = {{fgdata file|Nasal/globals.nas|t=Source}}<br />
|text = Returns a vector containing the values of the given hash.<br />
|param1 = hash<br />
|param1text = Mandatory hash to get the values of.<br />
|example1 = var hash = {<br />
"a": 1,<br />
"b": 2,<br />
"c": 3<br />
};<br />
<br />
foreach(var val; values(hash)){<br />
print(val);<br />
}<br />
|example2text = The below example does exactly the same thing as the above example, but does not use <code>values()</code>:<br />
|example2 = var hash = {<br />
"a": 1,<br />
"b": 2,<br />
"c": 3<br />
};<br />
<br />
foreach(var key; keys(hash)){<br />
print(hash[key]);<br />
<nowiki>}</nowiki><br />
}}<br />
<br />
==Extension functions new in FG 2020.1 ==<br />
The following functions have been added to the nasal core library and will be released with FlightGear version 2020.1. <br />
Before the release they are available in the development branch "next".<br />
<br />
===isfunc()===<br />
Returns 1 if type or argument is a function, otherwise 0.<br />
<br />
===isghost()===<br />
Returns 1 if type or argument is a ghost, otherwise 0.<br />
<br />
=== ishash()===<br />
Returns 1 if type or argument is a hash, otherwise 0.<br />
<br />
===isint()===<br />
{{Nasal doc<br />
|syntax = isint(x);<br />
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}<br />
|text = Returns 1 if argument has a numeric value and x == floor(x), e.g. integer.<br />
}}<br />
<br />
===isnum()===<br />
{{Nasal doc<br />
|syntax = isnum(x);<br />
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}<br />
|text = Returns 1 if typeof(x) is "scalar" and x has a numeric value otherwise 0. <br />
}}<br />
<br />
===isscalar()===<br />
{{Nasal doc<br />
|syntax = isscalar(x);<br />
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}<br />
|text = Returns 1 if type or argument is a scalar (string or numeric), otherwise (vector, hash, func, ...) it returns 0. This is useful to check if a variable can be converted to string e.g. when useing the string concat operator "~". <br />
|example1 = var a = "foo"; <br />
var b=42;<br />
if (isscalar(a) and isscalar(b)) print(a~b);<br />
if (isstr(a)) print("a is a string");<br />
if (isint(b)) print("b is an integer");<br />
# if (isscalar(a))... is equivalent to if (typeof(a) == "scalar")...<br />
}}<br />
<br />
===isstr()===<br />
Returns 1 if type or argument is a string, otherwise 0. <br />
<br />
===isvec()===<br />
Returns 1 if type or argument is a vector, otherwise 0.<br />
<br />
===vecindex()===<br />
{{Nasal doc<br />
|syntax = vecindex(vector, value);<br />
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}<br />
|text = Returns the index of value or nil, if value is not found in vector.<br />
|example1=<br />
var myvector = ["apple", "bananna", "coconut"];<br />
# to check if a vector contains a certain value compare vecindex to nil<br />
if (vecindex(myvector, "apple") != nil) {<br />
print("found apple");<br />
}<br />
# WARNING: this will not work as desired because index is 0<br />
if (vecindex(myvector, "apple")) {<br />
print("found apple");<br />
<nowiki>}</nowiki><br />
<br />
}}<br />
<br />
==Variables==<br />
Various global constants (technically variables) are provided for use in converting between different units. They are all found in {{fgdata file|Nasal/globals.nas|text=$FG_ROOT/Nasal/globals.nas}}.<br />
<br />
===D2R===<br />
{{Nasal doc<br />
|syntax = var radians = degrees * D2R;<br />
|text = Converts an angle from degrees to radians when multiplied by the angle in degrees. Equal to <code>π / 180</code>.<br />
}}<br />
===FPS2KT===<br />
{{Nasal doc<br />
|syntax = var knots = feet_per_second * FPS2KT;<br />
|text = Converts a velocity from feet per second to knots when multiplied by the velocity in feet per second. Approximately equal to 0.5925.<br />
}}<br />
===FT2M===<br />
{{Nasal doc<br />
|syntax = var metres = feet * FT2M;<br />
|text = Converts a length from feet to metres when multiplied by the length in feet. Equal to 0.3048.<br />
}}<br />
===GAL2L ===<br />
{{Nasal doc<br />
|syntax = var litres = gallons * GAL2L;<br />
|text = Converts a volume from US liquid gallons to litres when multiplied by the volume in gallons. Approximately equal to 3.7854.<br />
}}<br />
===IN2M===<br />
{{Nasal doc<br />
|syntax = var metres = inches * IN2M;<br />
|text = Converts a length from inches to metres when multiplied by the length in inches. Equal to 0.0254.<br />
}}<br />
===KG2LB===<br />
{{Nasal doc<br />
|syntax = var pounds = kilograms * KG2LB;<br />
|text = Converts a mass from kilograms to pounds when multiplied by the mass in kilograms. Approximately equal to 2.2046.<br />
}}<br />
===KT2FPS===<br />
{{Nasal doc<br />
|syntax = var feet_per_second = knots * KT2FPS;<br />
|text = Converts a velocity from knots to feet per second when multiplied by the velocity in knots. Approximately equal to 1.6878.<br />
}}<br />
===KT2MPS===<br />
{{Nasal doc<br />
|syntax = var metres_per_second = knots * KT2MPS;<br />
|text = Converts a velocity from knots to metres per second when multiplied by the velocity in knots. Approximately equal to 0.5144.<br />
}}<br />
===L2GAL===<br />
{{Nasal doc<br />
|syntax = var gallons = litres * L2GAL;<br />
|text = Converts a volume from litres to US liquid gallons when multiplied by the volume in litres. Approximately equal to 0.2642.<br />
}}<br />
===LB2KG===<br />
{{Nasal doc<br />
|syntax = var kilograms = pounds * LB2KG;<br />
|text = Converts a mass from pounds to kilograms when multiplied by the mass in pounds. Approximately equal to 0.4536.<br />
}}<br />
===M2FT ===<br />
{{Nasal doc<br />
|syntax = var feet = metres * M2FT;<br />
|text = Converts a length from metres to feet when multiplied by the length in metres. Approximately equal to 3.2808.<br />
}}<br />
===M2IN===<br />
{{Nasal doc<br />
|syntax = var inches = metres * M2IN;<br />
|text = Converts a length from metres to inches when multiplied by the length in metres. Approximately equal to 39.3701.<br />
}}<br />
===M2NM ===<br />
{{Nasal doc<br />
|syntax = var nautical_miles = metres * M2NM;<br />
|text = Converts a length from metres to nautical miles when multiplied by the length in metres. Approximately equal to 0.00054.<br />
}}<br />
===MPS2KT ===<br />
{{Nasal doc<br />
|syntax = var knots = metres_per_second * MPS2KT;<br />
|text = Converts a velocity from metres per second to knots when multiplied by the velocity in metres per second. Approximately equal to 1.9438.<br />
}}<br />
===NM2M ===<br />
{{Nasal doc<br />
|syntax = var metres = nautical_miles * NM2M;<br />
|text = Converts a length from nautical miles to metres when multiplied by the length in nautical miles. Equal to 1,852.<br />
}}<br />
===R2D===<br />
{{Nasal doc<br />
|syntax = var degrees = radians * R2D;<br />
|text = Converts an angle from radians to degrees when multiplied by the angle in radians. Equal to <code>180 / π</code>.<br />
}}<br />
<br />
{{Appendix}}<br />
<br />
<br />
{{Nasal namespaces}}</div>Clm76https://wiki.flightgear.org/w/index.php?title=Nasal_library&diff=138564Nasal library2023-10-30T09:52:45Z<p>Clm76: /* findNavaidByFrequencyMHz() */</p>
<hr />
<div>{{Nasal Navigation|nocat=1}}<br />
This page documents the global '''library functions and variables''' 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, the ''[[#Extension functions|extension functions]]'', which have been subsequently added, and are specifically designed for FlightGear, and the ''[[#variables|global variables]]'', which are conversion variables, added with extension functions, for converting between units. The relevant folders in [[Git]] are:<br />
* {{flightgear file|src/Scripting}}<br />
* {{simgear file|simgear/nasal}}<br />
<br />
All these functions and variables are in the global namespace, that is, they are directly accessible (e.g., one can call <syntaxhighlight lang="nasal" inline>magvar()</syntaxhighlight> instead of <syntaxhighlight lang="nasal" inline>namespace.magvar()</syntaxhighlight>). However, if a namespace must be used, <code>globals</code> is the correct namespace, but using it is not recommended. For a more complete explanation, see [[Nasal Namespaces in-depth]].<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|printerror()|debug}}.<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.<br />
<br />
The result is a four-element vector containing '''[0]''' a hash of local variables, '''[1]''' the function object, '''[2]''' the full source file name (incl. path) and '''[3]''' the line number. <br />
|param1 = level<br />
|param1text = Optional integer specifying the stack level to return a result from. Defaults to 1 (i.e. 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 lang="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 />
<br />
===contains()===<br />
{{Requires commit|desc=Vector support|details=see {{Merge-request|project=fgdata|id=305}}|commit=ee39abbd3b70c9b6d5e3a1c4ccedddaac1a92b11|repo=Simgear}}<br />
{{Nasal doc<br />
|syntax = contains(vector, item);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=184|t=Source}}<br />
|text = Returns 1 (True) if the vector contains the specified item, or 0 (False) if not.<br />
|param1 = vector<br />
|param1text = The vector to search in.<br />
|param2 = item<br />
|param2text = The object to be searched for in the vector.<br />
|example1 =<br />
# Initialize a hash<br />
var vec = ["element", "foo"];<br />
print(contains(hash, "element") ? "Yes" : "No"); # This will print "Yes"<br />
|example2 =<br />
# Initialize a hash<br />
var vec = ["element", "foo"];<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 NOT identical to setting the hash value specified by the key to <code>'''nil'''</code> as the key will stay in the hash (at least for a while). 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 />
|commit = {{simgear commit|bd7163|t=commit}}<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 />
|commit = {{simgear commit|bd7163|t=commit}}<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()|link=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 />
|example2text = 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 />
|example3text = This example sorts a vector of strings (runways for example) from smallest to greatest.<br />
|example3 = <br />
var runways = ["09R","27R","26L","09L","15"];<br />
var rwy = sort(runways,func(a,b) cmp(a,b));<br />
debug.dump(rwy); # prints ['09L','09R','15','26L','27R']<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 = <nowiki>sprintf(format[, arg[, arg, [...]]]);</nowiki><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()|link=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. This includes the decimal point and decimal fraction as well as + or - signs.<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>s</code> {{!!}} A string<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 />
|example10 =<br />
print(sprintf("%.2f", 1.4)); #prints "1.40"<br />
print(sprintf("%.1f", 1.4)); #prints "1.4"<br />
print(sprintf("% 4.1f", 1.4)); #prints " 1.4"<br />
print(sprintf("%04.1f", 1.4)); #prints "01.4"<br />
print(sprintf("% 6.1f", 1.4)); #prints " 1.4"<br />
print(sprintf("%06.1f", 1.4)); #prints "0001.4"<br />
}}<br />
<br />
===streq()===<br />
{{Nasal doc<br />
|syntax = streq(a, b);<br />
|source = {{simgear file|simgear/nasal/lib.c|l=129|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. Negative values specify a position from the end of the string.<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 />
|example4 = print(substr("abcde", -2)); # prints "de"<br />
|example5 = print(substr("abcde", -3, 2)); # prints "cd"<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 />
* Omitting the ''vector'' and ''start'' arguments is not an error (possibly it should be) but the return value is ''nil''.<br />
* A negative ''start'' argument ''is'' an error. This seems wrong. Perhaps the language designer could comment.<br />
* A value of ''start'' greater than ''size(vector)'' causes an error. A value equal to ''size(vector)'' returns an empty vector.<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 />
|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 modules ==<br />
=== thread ===<br />
{{WIP}}<br />
<br />
{{Nasal doc<br />
|syntax = thread.newthread(func);<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = start a new worker thread<br />
|example1 = thread.newthread( func() {} );<br />
}}<br />
<br />
{{Nasal doc<br />
|syntax = thread.newlock();<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = create a new lock<br />
|example1 = var lock = thread.newlock()<br />
}}<br />
<br />
{{Nasal doc<br />
|syntax = thread.lock();<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = lock a lock<br />
|example1 = var lock = thread.newlock()<br />
}}<br />
<br />
{{Nasal doc<br />
|syntax = thread.unlock();<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = unlock a lock<br />
|example1 = var lock = thread.unlock()<br />
}}<br />
<br />
<br />
{{Nasal doc<br />
|syntax = thread.newsem();<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = create a new {{Wikipedia|semaphore}}<br />
|example1 = var semaphore = thread.newsem()<br />
}}<br />
<br />
<br />
{{Nasal doc<br />
|syntax = thread.semdown();<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = semaphore down<br />
|example1 = thread.semdown(semaphore)<br />
}}<br />
<br />
<br />
{{Nasal doc<br />
|syntax = thread.semup();<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = semaphore up<br />
|example1 = thread.semup(semaphore)<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()|link=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 />
===aircraftToCart() ===<br />
This new function in FG 2017.2.1 takes coordinates in aircraft structural coordinate system, and translate them into geocentric coordinates.<br />
Example for (5,6,7):<br />
<syntaxhighlight lang="nasal"><br />
var pos = aircraftToCart({x: -5, y: 6, z: -7});<br />
var coord = geo.Coord.new();<br />
coord.set_xyz(pos.x, pos.y, pos.z);<br />
</syntaxhighlight><br />
Notice: x and z is inverted sign on purpose.<br />
if you want lat. lon, alt from that, just call: (degrees and meters)<br />
<br />
<syntaxhighlight lang="nasal"><br />
coord.lat()<br />
coord.lon()<br />
coord.alt()<br />
</syntaxhighlight><br />
<br />
===addcommand() ===<br />
{{Nasal doc<br />
|syntax = addcommand(name, code);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=659|t=Source}}<br />
|version = 2.12<br />
|commit = {{flightgear commit|7b663c|t=commit}}<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(node) {<br />
print("fgcommand 'myFGCmd' has been run.");<br />
props.dump( node );<br />
});<br />
fgcommand("myFGCmd", props.Node.new({foo:1, bar:2}) );<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 />
* '''parents''': A vector containing a hash of various functions to access information about the runway. See {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2659}} for full list.<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 />
*** '''id''': Name of runway.<br />
*** '''lat''': Latitude of the runway.<br />
*** '''lon''': Longitude of the runway.<br />
*** '''heading''': Heading of the runway.<br />
*** '''length''': Length of the runway in metres.<br />
*** '''width''': Width of the runway in metres.<br />
*** '''surface''': Runway surface type.<br />
*** '''threshold''': Length of the runway's {{wikipedia|displaced threshold}} in metres. Will return 0 if there is none.<br />
*** '''stopway''': Length of the runway's stopway (the area before the threshold) in metres. Will return 0 if there is none.<br />
*** '''reciprocal''': <code>runway</code> ghost of the reciprocal runway.<br />
*** '''ils_frequency_mhz''': ILS frequency in megahertz.<br />
*** '''ils''': <code>navaid</code> ghost of the ILS transmitter.<br />
* '''helipads'''<br />
** '''<helipad name>'''<br />
*** '''id''': Name of helipad.<br />
*** '''lat''': Latitude of the helipad.<br />
*** '''lon''': Longitude of the helipad.<br />
*** '''heading''': Heading of the helipad.<br />
*** '''length''': Length of the helipad in metres.<br />
*** '''width''': Width of the helipad in metres.<br />
*** '''surface''': Helipad surface type.<br />
* '''taxiways'''<br />
** '''<taxiway name>'''<br />
*** '''id''': Name of taxiway.<br />
*** '''lat''': Latitude of the taxiway.<br />
*** '''lon''': Longitude of the taxiway.<br />
*** '''heading''': Heading of the taxiway.<br />
*** '''length''': Length of the taxiway in metres.<br />
*** '''width''': Width of the taxiway in metres.<br />
*** '''surface''': Taxiway surface type.<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 />
<nowiki>}</nowiki><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 />
<nowiki>}</nowiki><br />
}}<br />
<br />
===airway()===<br />
<br />
{{Nasal doc<br />
|syntax = airway(ident [, pos]);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2644|t=Source}}<br />
|text = {{see also|Nasal Flightplan}}<br />
This function returns a ghost containing an airway of a specified id.<br />
|param1 = ident<br />
|param1text = a Positioned ghost (leg, navaid, airport) and so on, passed to the search function.<br />
|param2 = pos<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 />
|commit = {{fgdata commit|8b16a7|t=commit}}<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 with geodetic coordinates (cartesian coordinates will not be accepted)<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 />
===createFlightplan()===<br />
{{Nasal doc<br />
|syntax = createFlightplan(path);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2331|t=Source}}<br />
|text = Creates an empty flightplan object. It accepts one argument, ''path'' passed an absolute path to a .fgfp / .gpx file, it will populate the flightplan with waypoints from the file.<br />
|param1 = path<br />
|param1text = Optional parameter defining the file from which a flightplan will be populated.<br />
|example1 = <br />
var path = getprop("/sim/fg-home") ~ "/Export/test.fgfp";<br />
var flightplan = createFlightplan(path);<br />
debug.dump(flightplan);<br />
}}<br />
<br />
===createDiscontinuity()===<br />
{{Nasal doc<br />
|syntax = createDiscontinuity();<br />
|text = Returns a <code>waypoint</code> ghost object. A route discontinuity is inserted by an {{abbr|FMS|Flight Management System}} when it is unsure how to connect two waypoints.<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2045|t=Source}}<br />
|version = 2016.1<br />
|commit = {{flightgear commit|caead6|t=commit}}<br />
}}<br />
===createViaTo()===<br />
{{Nasal doc<br />
|syntax = createViaTo(airway, waypoint);<br />
|text = Returns a <code>waypoint</code> ghost object. It represents a route "via '''airway''' to '''waypoint'''".<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2009|t=Source}}<br />
|version = 2016.1<br />
|commit = {{flightgear commit|caead6|t=commit}}<br />
|param1 = airway<br />
|param1text = The name of an airway.<br />
|param2 = waypoint<br />
|param2text = Must be in the airway and one of:<br />
* The name of a waypoint.<br />
* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, or <code>fix</code> ghost object.<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 />
<nowiki>}</nowiki><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 />
<nowiki>}</nowiki><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 />
===findNavaidByFrequencyMHz()===<br />
{{Nasal doc<br />
|syntax = findNavaidByFrequencyMHz([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 = findNavaidByFrequencyMHz(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 />
<nowiki>}</nowiki><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 />
<nowiki>}</nowiki><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 />
<nowiki>}</nowiki><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 />
<nowiki>}</nowiki><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 />
=== get_cart_ground_intersection()===<br />
Introduced in 2017.2.1, see [[Terrain Detection]].<br />
<br />
===getprop()===<br />
{{Nasal doc<br />
|syntax = <nowiki>getprop(path[, path[, ...]]);</nowiki><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 = path<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 also 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 versions 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 />
<nowiki>}</nowiki><br />
}}<br />
==== See also====<br />
{{note| If you have to read/write the same property multiple times (e.g. in an update loop), it is more efficient to use a node object: <br />
To get a Node rather than its value, use <code>props.globals.getNode()</code> - see [[Nasal_library/props]]. }}<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 = <nowiki>interpolate(prop, value1, time1[, value2, time2[, ...]]);</nowiki><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 />
<nowiki>}</nowiki><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 = <nowiki>logprint(priority[, msg[, msg[, ...]]]);</nowiki><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 from the Nasal file itself rather than from {{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 />
{{note| <br />
The following constants have been added to the development branch of FlightGear ("next") and will be releases with FG 2020.1 so you won't have to remember the numbers anymore:<br />
<br />
LOG_BULK, LOG_WARN, LOG_DEBUG, LOG_INFO, LOG_ALERT, DEV_WARN, DEV_ALERT }}<br />
<br />
===magvar() ===<br />
{{Nasal doc<br />
|syntax = magvar([pos]);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1642|t=Source}}<br />
|text = Returns the {{wikipedia|magnetic variation}} at a given set of coordinates. The table below gives the magnetic model used depending on the version of FlightGear.<br />
{{{!}} class="wikitable"<br />
! FlightGear versions !! Model !! Reference date<br />
{{!-}}<br />
{{!}} 3.6 and above {{!!}} {{wikipedia|World Magnetic Model}} (WMM) 2015 {{!!}} 1 January 2015<br />
{{!-}}<br />
{{!}} 0.9.11-pre1 to 3.4 {{!!}} WMM 2005 {{!!}} 1 January 2005<br />
{{!-}}<br />
{{!}} 0.7.3 to 0.9.10 {{!!}} WMM 2000 {{!!}} 1 January 2000<br />
{{!}}}<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>magvar(lat,lon)</code>.<br />
|example1 = print(magvar(0, 0)); # prints the magnetic variation at 0, 0<br />
}}<br />
<br />
===maketimer() ===<br />
{{Nasal doc<br />
|syntax = maketimer(interval[, self], function);<br />
|source = ''Implemented using the {{API Link|flightgear|class|TimerObj}} class.''<br>{{flightgear file|src/Scripting/NasalSys.cxx|l=90|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=533|t=Part 2}}<br />
|version = 2.12<br />
|commit = {{flightgear commit|ab939f|t=commit}}<br />
|text = Returns a timer object containing the following methods and members:<br />
* '''start()''': Starts the timer.<br />
* '''stop()''': Stops the timer.<br />
* '''restart(interval)''': Restarts the timer with the given interval.<br />
* '''singleShot''': Bool showing whether the timer is only to be run once, or continuously until told to stop. Can be both set and read from (see examples).<br />
* '''isRunning''': Read-only bool telling whether the timer is currently running.<br />
* '''simulatedTime''': (FG 2017.1+; {{flightgear commit|0af316|t=commit}}) Bool telling whether the timer is using simulated time (which accounts for pause, etc.). Defaults to false (use real time). Can be both read and set. This cannot be changed while the timer is running.<br />
Unlike {{func link|settimer()}}, which it replaces, <code>maketimer()</code> provides more control over the timer. In addition, it can help reduce memory usage.<br />
|param1 = interval<br />
|param1text = Interval in seconds for the timer.<br />
|param2 = self<br />
|param2text = Optional parameter specifying what any <code>'''me'''</code> references in the function being called will refer to.<br />
|param3 = function<br />
|param3text = Function to be called at the given interval.<br />
|example1 = var timer = maketimer(1, func(){<br />
print("Hello, World!"); # print "Hello, World!" once every second (call timer.stop() to stop it)<br />
});<br />
timer.start();<br />
|example2 = var timer = maketimer(1, math, func(){<br />
print(me.math); # 'me' reference is the 'math' namespace<br />
});<br />
timer.singleShot = 1; # timer will only be run once<br />
timer.start();<br />
|example3 = var timer = maketimer(1, func(){<br />
print("Hello, World!"); # print "Hello, World!" once every second (call timer.stop() to stop it)<br />
});<br />
timer.start();<br />
print(timer.isRunning); # prints 1<br />
|example4text = In the example below, "Hello, World!" will be printed after one second the first time, and after two seconds thereafter.<br />
|example4 = var update = func(){<br />
print("Hello, World!");<br />
timer.restart(2); # restarts the timer with a two second interval<br />
}<br />
<br />
var timer = maketimer(1, update);<br />
timer.singleShot = 1;<br />
timer.start();<br />
}}<br />
<br />
===maketimestamp()===<br />
{{Nasal doc<br />
|syntax = maketimestamp()<br />
|source = ''Implemented using the {{API Link|flightgear|class|TimeStampObj}} class.''<br>{{flightgear file|src/Scripting/NasalSys.cxx|l=214|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=589|t=Part 2}}<br />
|version = 2019.2<br />
|commit = {{flightgear commit|7db06300|t=commit}}<br />
|text = Returns a time stamp object to allow high resolution timing of Nasal operations. When created the timer will automatically be stamped. The object has the following methods:<br />
* '''stamp()''': Resets the timing operation. Call this first.<br />
* '''elapsedMSec()''': returns number of milliseconds elapsed since stamp() called. Resolution may vary depending on platform but is usually at least millisecond accuracy.<br />
* '''elapsedUSec()''': returns number of microseconds elapsed since stamp() called. Resolution may vary depending on platform but is usually at least millisecond accuracy.<br />
|<br />
|example1text = In the example below the number of milliseconds elapsed will be printed.<br />
|example1 = var timestamp = maketimestamp();<br />
timestamp.stamp();<br />
print(timestamp.elapsedMSec(), "ms elapsed");<br />
print(timestamp.elapsedMSec(), "ms elapsed");<br />
}}<br />
<br />
===md5()===<br />
{{Nasal doc<br />
|syntax = md5(string);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=758|t=Source}}<br />
|version = 3.2<br />
|commit = {{flightgear commit|cfbf9e|t=commit}}<br />
|text = Returns a the {{wikipedia|MD5}} hash (as a string) of the inputted string.<br />
|param1 = string<br />
|param1text = String the generate the hash of. Mandatory.<br />
|example1text = The below code should output <code>65a8e27d8879283831b664bd8b7f0ad4</code>.<br />
|example1 = print(md5("Hello, World!"));<br />
}}<br />
<br />
===navinfo()===<br />
{{Nasal doc<br />
|syntax = navinfo(lat, lon, type, id);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1453|t=Source}}<br />
|text = Returns vector <code>navaid</code> ghost objects matching the given '''type''' and '''id''' or <code>'''nil'''</code> on error.<br />
|param1 = lat ''and'' lon<br />
|param1text = If given, the returned navaids will be put into order of ascending distance from the location.<br />
|param2 = type<br />
|param2text = Narrows the search to the given type. Must be one of "any," "fix," "vor," "ndb," "ils," "dme," or "tacan." Defaults to the equivalent of "any."<br />
|param3 = id<br />
|param3text = ID to search for. Note that, although all the parameters are technically optional, this parameter must be given, otherwise an empty vector will be returned.<br />
|example1 = navinfo("vor"); # returns all VORs<br />
|example2 = navinfo("HAM"); # return all navaids whose names start with "HAM"<br />
|example3 = navinfo("vor", "HAM"); # return all VORs whose names start with "HAM"<br />
|example4 = navinfo(34,48,"vor","HAM"); # return all VORs whose names start with "HAM" and sorted by distance relative to 34°, 48°<br />
}}<br />
<br />
===parse_markdown()===<br />
{{Nasal doc<br />
|syntax = parse_markdown(markdown);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=745|t=Part 1}} {{!}} {{simgear file|simgear/misc/SimpleMarkdown.cxx|t=Part 2}} <br />
|version = 3.2<br />
|text = Parses a string containing {{wikipedia|Markdown}} and returns the result as a string. As of FlightGear 2016.1, it is just a simple parser, and does the following:<br />
* It strips whitespace from the beginning of the string.<br />
* It supports [http://daringfireball.net/projects/markdown/syntax#p paragraphs and line breaks].<br />
* It collapses whitespace.<br />
* It converts unordered [http://daringfireball.net/projects/markdown/syntax#list lists] to use a bullet character (&bull;). Note that the bullet character is implemented in hexadecimal UTF-8 character bytes (<code>E2 80 A2</code>), as so may not work properly when the being displayed in an encoding other than UTF-8.<br />
|param1 = markdown<br />
|param1text = String containing Markdown to be parsed.<br />
|example1text = <br />
Save the below code as <tt>''[[$FG_ROOT]]/gui/dialogs/test.xml''</tt>, then run the Nasal code below it to open the dialog. To change the markdown to be parsed, simply change the code in the highlighted section, save it, and reload the GUI (<tt>Debug > Reload GUI</tt>).<br />
<syntaxhighlight lang="xml" highlight="41-50"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<br />
<PropertyList><br />
<br />
<name>test</name><br />
<layout>vbox</layout><br />
<br />
<group><br />
<layout>hbox</layout><br />
<br />
<empty><br />
<stretch>true</stretch><br />
</empty><br />
<br />
<text><br />
<label>parse_markdown() test dialog</label><br />
</text><br />
<br />
<empty><br />
<stretch>true</stretch><br />
</empty><br />
<br />
<button><br />
<legend></legend><br />
<pref-width>16</pref-width><br />
<pref-height>16</pref-height><br />
<binding><br />
<command>dialog-close</command><br />
</binding><br />
</button><br />
<br />
</group><br />
<br />
<canvas><br />
<name>Canvas plot</name><br />
<stretch>true</stretch><br />
<pref-width>400</pref-width><br />
<pref-height>300</pref-height><br />
<nasal><br />
<load><![CDATA[<br />
var text = 'Items:<br />
* apples<br />
* oranges<br />
* pears<br />
<br />
Some text.<br />
Some more items:<br />
* apples<br />
* oranges<br />
* pears';<br />
<br />
var parsed = parse_markdown(text);<br />
<br />
var root_canvas = canvas.get(cmdarg());<br />
root_canvas.setColorBackground(255, 255, 255);<br />
var root = root_canvas.createGroup();<br />
<br />
var text_dis = root.createChild("text")<br />
.setText(parsed)<br />
.setTranslation(5, 5)<br />
.setFont("LiberationFonts\LiberationSans-Regular.ttf")<br />
.setFontSize(15)<br />
.setColor(0, 0, 0)<br />
.setDrawMode(canvas.Text.TEXT)<br />
.setAlignment("left-top");<br />
]]></load><br />
</nasal><br />
</canvas><br />
<br />
</PropertyList><br />
</syntaxhighlight><br />
|example1 = fgcommand("dialog-show", {"dialog-name": "test"});<br />
|example2text = The example below parses Markdown and outputs it in a HTML document. The parsed text is placed in <syntaxhighlight lang="xml" inline><pre></pre></syntaxhighlight> tags. To change the Markdown to be parsed, simply edit the variable <tt>markdown</tt> at the top of the code.<br />
|example2 = <nowiki>var markdown = 'Items:<br />
* apples<br />
* oranges<br />
* pears<br />
<br />
Some text.<br />
Some more items:<br />
* apples<br />
* oranges<br />
* pears';<br />
<br />
var parsed = parse_markdown(markdown);<br />
<br />
debug.dump(parsed);<br />
<br />
var path = string.normpath(getprop("/sim/fg-home") ~ '/Export/parse_markdown()-test.html');<br />
<br />
var file = io.open(path, "w");<br />
<br />
var html = "<!DOCTYPE html>\n\n<html>\n\n<head>\n\t<meta charset=\"UTF-8\">\n\t<title>parse_markdown() test generated by Nasal</title>\n</head>\n\n<body>\n\t<pre>" ~ parsed ~ "</pre>\n</body>\n\n</html>";<br />
<br />
io.write(file, html);<br />
io.close(file);<br />
print("Done, file ready for viewing (" ~ path ~ ")");</nowiki><br />
}}<br />
<br />
===parsexml()===<br />
{{Nasal doc<br />
|syntax = <nowiki>parsexml(path[, start[, end[, data[, pro_ins]]]]);</nowiki><br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=710|t=Source}}<br />
|text = This function is an interface into the built-in [http://expat.sourceforge.net/ Expat XML parser]. The absolute path to the file is returned as string, or <code>'''nil'''</code> is returned on error.<br />
|param1 = path<br />
|param1text = Mandatory absolute path to the XML file to be parsed.<br />
|param2 = start<br />
|param2text = Optional callback function that will be called for every starting tag. The function should take two argument: the tag name and a hash containing attributes.<br />
|param3 = end<br />
|param3text = Optional callback function that will be called for every ending tag. The function should take one argument: the tag name.<br />
|param4 = data<br />
|param4text = Optional callback function that will be called for every piece of data within a set of tags. The function should take one argument: the data as a string.<br />
|param5 = pro_ins<br />
|param5text = Optional callback function that will be called for every {{wikipedia|Processing Instruction|processing instruction}}. The function should take two argument: the target and the data string.<br />
|example1text = Save the below XML code in <tt>''[[$FG_HOME]]/Export/demo.xml''</tt>. Then, execute the Nasal code below in the Nasal Console. The XML will be parsed and each bit of the code will be printed.<br />
<syntaxhighlight lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<br />
<?xml-stylesheet type="text/xsl" href="style.xsl"?><br />
<br />
<foo><br />
<blah type="string"><![CDATA[ <sender>John Smith</sender> ]]></blah><br />
<blah2 type="string">Orange &amp; lemons</blah2><br />
</foo><br />
</syntaxhighlight><br />
|example1 = 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 />
}<br />
<br />
var end = func(name){<br />
print("Ending tag: '", name, "'");<br />
}<br />
<br />
var data = func(data){<br />
print("Data = '", data, "'");<br />
}<br />
<br />
var pro_instr = func(target, data){<br />
print("Processing instruction: target = '", target, "', data = '", data, "'");<br />
}<br />
<br />
parsexml(getprop("/sim/fg-home") ~ '/Export/demo.xml', start, end, data, pro_instr);<br />
}}<br />
<br />
===print()===<br />
{{Note|As of 07/2020, we are in the process of slowly deprecating and removing Nasal print() (in fgdata) where possible in favor of log [[#logprint()]] which takes a priority level.<br />
<br />
This is part of the goal that we achieve zero output at log-level at alert, and everything shown at ‘warn; is really a warning, not just information.<ref>https://sourceforge.net/p/flightgear/mailman/message/37042224/</ref>}}<br />
<br />
{{Nasal doc<br />
|syntax = <nowiki>print(data[, data[, ...]]);</nowiki><br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=415|t=Source}}<br />
|text = Concatenates its arguments and then prints it to the terminal and the [[Commonly used debugging tools#fgfs.log|log]]. Note that a newline is automatically added.<br />
|param1 = data<br />
|param1text = Data to print. Only strings and numbers can be printed; other data types will not be. There many be any number of arguments; they will just be concatenated together.<br />
|example1 = print("Just", " a ", "test"); # prints "Just a test"<br />
|example2 = print("pi = ", math.pi); # prints "pi = 3.141592..."<br />
}}<br />
<br />
=== printf() ===<br />
{{Nasal doc<br />
|syntax = <nowiki>printf(format[, arg[, arg, [...]]]);</nowiki><br />
|source = {{fgdata file|Nasal/globals.nas|t=Source}}<br />
|text = Creates and prints a formatted string. For a description of its arguments, see {{func link|sprintf()}} (it is, in fact, implemented using <code>sprintf()</code>).<br />
|example1 = printf("In hexadecimal, 100000 = %X", 186A0); # prints "In hexadecimal, 100000 = 186A0"<br />
}}<br />
<br />
===printlog()===<br />
{{Nasal doc<br />
|syntax = <nowiki>printlog(level, data[, data[, ...]]);</nowiki><br />
|source = {{fgdata file|Nasal/globals.nas|t=Source}}<br />
|text = Prints the given message with the given log level. If the log level is higher or equal to <code>/sim/logging/priority</code>, it is printed.<br />
|param1 = level<br />
|param1text = Mandatory log level as a string. Must be one of "none," "bulk," "debug," "info," "warn," or "alert." Note that "none" will mean that the message will never be printed.<br />
|param2 = data<br />
|param2text = Data to be printed. Only strings and numbers will be printed; others will not be. There may be any number of arguments; they will just be concatenated together.<br />
|example1 = printlog("alert", "This is an alert"); # message will be printed<br />
|example2 = printlog("info", "Just informing you about something"); # message will be printed only if log level is set to "info" or less<br />
}}<br />
<br />
===rand()===<br />
{{Nasal doc<br />
|syntax = rand();<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=554|t=Source}}<br />
|text = Returns a random floating point number between 0 (inclusive) and 1 (exclusive). It takes no arguments.<br />
|example1 = print(rand()); # prints random number<br />
}}<br />
<br />
===registerFlightPlanDelegate()===<br />
{{Nasal doc<br />
|syntax = registerFlightPlanDelegate(init_func);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1879|t=Source}}<br />
|text = Registers a flight plan delegate. See <tt>''{{fgdata file|Nasal/route_manager.nas|t=$FG_ROOT/Nasal/route_manager.nas}}''</tt> for examples.<br />
|param1 = init_func<br />
|param1text = Initialization function which will be called during FlightGear's startup.<br />
}}<br />
===removecommand()===<br />
{{Nasal doc<br />
|syntax = removecommand(cmd);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=668|t=Source}}<br />
|text = Removes the given fgcommand. Returns <code>'''nil'''</code>.<br />
{{caution|This will remove '''any''' [[fgcommands|fgcommand]], even those implemented in C++, so use with caution!}}<br />
|param1 = cmd<br />
|param1text = String specifying the name of the command to remove.<br />
|example1 = addcommand("hello", func(){<br />
print("Hello");<br />
});<br />
fgcommand("hello"); # "Hello" will be printed<br />
removecommand("hello"); # removes it<br />
}}<br />
<br />
===removelistener()===<br />
{{Nasal doc<br />
|syntax = removelistener(id);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=1384|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=506|t=Part 2}}<br />
|text = Removes and deactivates the given listener and returns the number of listeners left or <code>'''nil'''</code> on error.<br />
{{note|It is good practice to remove listeners when they are not required anymore. This prevents the listeners reducing FlightGear's run performance.}}<br />
|param1 = id<br />
|param1text = ID of listener as returned by {{func link|setlistener()}}.<br />
|example1 = var ls = setlistener("/sim/test", func(){<br />
print("Property '/sim/test' has been changed");<br />
});<br />
setprop("/sim/test", "blah"); # trigger listener<br />
var rem = removelistener(ls); # remove listener<br />
print("There are ", rem, " listeners remaining");<br />
}}<br />
<br />
===resolvepath()===<br />
{{Nasal doc<br />
|syntax = resolvepath(path);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=604|t=Source}}<br />
|text = Takes a relative path as a string and uses [[SimGear]]'s path-resolving framework to return an absolute path as a string. If the path could not be resolved, an empty string is returned. See [[Resolving Paths]] for a detailed description of the algorithm. This function can also be used to check if a file exists.<br />
|param1 = path<br />
|param1text = Relative path to be completed.<br />
|example1 = print(resolvepath("Nasal/globals.nas")); # prints the equivalent of $FG_ROOT/Nasal/globals.nas<br />
|example2 = print(resolvepath("blah")); # prints nothing; could not be resolved<br />
|example3 = var file_path = resolvepath("Aircraft/SenecaII/some-file");<br />
if (file_path != ""){<br />
gui.popupTip("some-file found", 2);<br />
} else {<br />
gui.popupTip("some-file not found", 2);<br />
<nowiki>}</nowiki><br />
}}<br />
<br />
===setlistener()===<br />
{{Nasal doc<br />
|syntax = <nowiki>setlistener(node, code[, init[, type]]);</nowiki><br />
|private = _setlistener()<br />
|source = {{flightgear file|src/Scripting/Nasal|l=499|t=Part 1}} {{!}} {{flightgear file|src/Scripting/Nasal|l=1350|t=Part 2}}<br>''Listener implemented using the {{API Link|flightgear|class|FGNasalListener}} class.''<br />
|text = Creates a listener which will be triggered when the given property is changed (depending on the '''type'''). A unique integer ID is returned; this can later be used as the argument to {{func link|removelistener()}}.<br />
{{note|Listeners are known to be a source of resource leaks. To avoid this, please take measures such as:<br />
* Using {{func link|removelistener()}} when they are not needed any more.<br />
* Using a single initialization listener.<br />
* Avoiding tying listeners to properties that are rapidly updated (e.g., many times per frame).<br />
}}<br />
|param1 = node<br />
|param1text = Mandatory string or <code>props.Node</code> object pointing to a property in the [[Property Tree]].<br />
|param2 = code<br />
|param2text = Mandatory callback function to execute when the listener is triggered. The function can take up to four arguments in the following order:<br />
* '''changed''': a <code>props.Node</code> object pointing to the changed node.<br />
* '''listen''': a <code>props.Node</code> object pointing to the listened-to node. Note that this argument maybe different depending on the '''type'''.<br />
* '''mode''': an integer telling how the listener was triggered. 0 means that the value was changed. 1 means that a child property was added. -1 means that a child property was removed.<br />
* '''is_child''': boolean telling whether '''changed''' is a child property of the listened-to '''node''' or not. 1 (true) if it is, 0 (false) otherwise.<br />
|param3 = init<br />
|param3text = If set to 1 (true), the listener will additionally be triggered when it is created. This argument is optional and defaults to 0 (false).<br />
|param4 = type<br />
|param4text = Integer specifying the listener's behavior. 0 means that the listener will only trigger when the property is changed. 1 means that the trigger will always be triggered when the property is written to. 2 will mean that the listener will be triggered even if child properties are modified. This argument is optional and defaults to 1.<br />
|example1 = var prop = props.globals.initNode("/sim/test", "", "STRING"); # create property<br />
var id = setlistener("/sim/test", func(n){ # create listener<br />
print("Value: ", n.getValue());<br />
});<br />
setprop("/sim/test", "blah"); # trigger listener<br />
removelistener(id); # remove listener<br />
prop.remove(); # remove property<br />
}}<br />
<br />
===setprop()===<br />
{{Nasal doc<br />
|syntax = <nowiki>setprop(path[, path[, ...]], value);</nowiki><br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=385|t=Source}}<br />
|text = Sets the value of a property in the [[Property Tree]]. If the property does not exist, it will be created. Returns 1 (true) on success or 0 (false) if there was an error.<br />
{{note|If you want to remove a property, you will have to use one of the <code>props</code> helpers:<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 />
|param1 = path<br />
|param1text = There needs to be at least one '''path''' argument, but there is no limit to the maximum amount that can be given. They will be concatenated together to form a property tree path. The arguments must be strings, but in FlightGear v3.2 onwards, there also is support (added by {{flightgear commit|34ed79}}) for numeric arguments as indices. See example 2 below.<br />
|param2 = value<br />
|param2text = Value to write to the given property. Must be either a string or a number.<br />
|example1 = setprop("/sim/demo", "This is a demo");<br />
|example2text = Note that the example below will only work in FlightGear 3.2 and above.<br />
|example2 = for(var i = 0; i < 3; i += 1){<br />
setprop("/sim/demo", i, "Demo #" ~ i));<br />
}<br />
|example3text = Same as above, but is supported by all versions of FlightGear.<br />
|example3 = for(var i = 0; i < 3; i += 1){<br />
setprop("/sim/demo[" ~ i ~ "]", "Demo #" ~ i));<br />
<nowiki>}</nowiki><br />
}}<br />
====See also====<br />
{{note| If you have to read/write the same property multiple times (e.g. in an update loop), it is more efficient to use a node object: <br />
To get a Node rather than its value, use <code>props.globals.getNode()</code> - see [[Nasal_library/props]]. }}<br />
<br />
===settimer() ===<br />
{{Nasal doc<br />
|syntax = settimer(function, delta[, realtime]);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=499|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=1286|t=Part 2}}<br />
|text = Runs the given function a specified amount of seconds after the current time. Returns <code>'''nil'''</code>.<br />
{{note|Improper use of <code>settimer()</code> may cause resource leaks. It is also highly recommended that the newer {{func link|maketimer()}} should be used instead of this function.}} <br />
|param1 = function<br />
|param1text = Mandatory function that will be called. It may be necessary to enclose code in an anonymous function (see example).<br />
|param2 = delta<br />
|param2text = Mandatory amount of time in seconds after which the function will be called.<br />
|param3 = realtime<br />
|param3text = If 1 (true), "real time" will be used instead of "simulation time." Defaults to 0 (false). Note that if "simulation time" is used, the timer will not run while FlightGear is paused.<br />
|example1 = var myFunc = func(){<br />
print("Hello");<br />
}<br />
<br />
settimer(myFunc, 2); # runs myFunc after 2 seconds<br />
|example2 = var sqr = func(a){<br />
return a * a;<br />
}<br />
<br />
settimer(func(){<br />
print(sqr(2)); # will print 4 after 2 seconds<br />
}, 2);<br />
}}<br />
<br />
===srand() ===<br />
{{Nasal doc<br />
|syntax = srand();<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=559|t=Source}}<br />
|text = Makes the pseudorandom number generator (see {{func link|rand()}}) generate a new {{wikipedia|random seed|noicon=1}} based on time. Returns 0.<br />
}}<br />
===systime()===<br />
{{Nasal doc<br />
|syntax = systime();<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=770|t=Source}}<br />
|text = Returns the {{wikipedia|Unix time}} (seconds since since 00:00:00 UTC, 1/1/1970) as a floating point number with high resolution. This function is useful for benchmarking purposes (see example 2).<br />
{{note|1=High resolution timers under Windows can produce inaccurate or fixed sub-millisecond results.<ref>{{cite web|url=http://forum.flightgear.org/viewtopic.php?f=30&t=29259|title=Nasal: systime() ??!?|author=Necolatis|date=Apr 2nd, 2016}}</ref> This is due to the underlying {{func link|GetSystemTimeAsFileTime()|link=https://msdn.microsoft.com/en-us/library/windows/desktop/ms724397(v=vs.85).aspx}} API call, which depends on hardware availability of suitable high resolution timers. See also [https://msdn.microsoft.com/en-us/library/windows/desktop/dn553408(v=vs.85).aspx Acquiring high-resolution time stamps]}}<br />
|example1 = print("Unix time: ", systime()); # prints Unix time<br />
|example2 = var myFunc = func(){<br />
for(var i = 0; i <= 10; i += 1){<br />
print("Interation #", i);<br />
}<br />
}<br />
var t = systime(); # record time<br />
myFunc(); # run function<br />
var t2 = systime(); # record new time<br />
print("myFunc() took ", t2 - t, " seconds"); # print result<br />
}}<br />
<br />
===thisfunc()===<br />
{{Nasal doc<br />
|syntax = thisfunc();<br />
|source = {{fgdata file|Nasal/globals.nas|t=Source}}<br />
|text = Returns the function from which this function is called. This allows a function to reliably and safely call itself from within a closure.<br />
|example1 = var stringify_vec = func(input){<br />
if (typeof(input) == "scalar"){<br />
return sprintf("%s", input);<br />
} elsif (typeof(input) == "vector") {<br />
if (size(input) == 0) return "[]";<br />
var this = thisfunc();<br />
var buffer = "[";<br />
for(var i = 0; i < size(input); i += 1){<br />
buffer ~= this(input[i]);<br />
if (i == size(input) - 1) {<br />
buffer ~= "]";<br />
} else {<br />
buffer ~= ", ";<br />
}<br />
}<br />
return buffer;<br />
} else {<br />
die("stringify_vec(): Error! Invalid input. Must be a vector or scalar");<br />
}<br />
}<br />
<br />
var test_vec = ["a", "b", "c", 1, 2, 3];<br />
debug.dump(stringify_vec(test_vec)); # prints "[a, b, c, 1, 2, 3]"<br />
test_vec = [];<br />
debug.dump(stringify_vec(test_vec)); # prints "[]"<br />
test_vec = {};<br />
debug.dump(stringify_vec(test_vec)); # will throw an error<br />
}}<br />
<br />
===tileIndex() ===<br />
{{Nasal doc<br />
|syntax = tileIndex();<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1720|t=Source}}<br />
|text = Returns the index of the tile at the aircraft's current position as a string. This corresponds to the name of the STG file of the tile. For example, at [[KSFO]], this would be <code>942050</code>, corresponding to <tt>''[[$FG_SCENERY]]/Terrain/w130n30/w123n3/942050.stg''</tt>.<br />
|example1 = print(tileIndex()); # print index<br />
}}<br />
<br />
=== tilePath()===<br />
{{Nasal doc<br />
|syntax = tilePath();<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1712|t=Source}}<br />
|text = Returns the base path of the tile at the aircraft's current position as a string. For example, at KSFO, this would be <code>w130n30/w123n3</code>, corresponding to <tt>''[[$FG_SCENERY]]/Terrain/w130n30/w123n3''</tt>.<br />
|example1 = print(tilePath()); # print path<br />
}}<br />
<br />
=== values()===<br />
{{Nasal doc<br />
|syntax = values(hash);<br />
|source = {{fgdata file|Nasal/globals.nas|t=Source}}<br />
|text = Returns a vector containing the values of the given hash.<br />
|param1 = hash<br />
|param1text = Mandatory hash to get the values of.<br />
|example1 = var hash = {<br />
"a": 1,<br />
"b": 2,<br />
"c": 3<br />
};<br />
<br />
foreach(var val; values(hash)){<br />
print(val);<br />
}<br />
|example2text = The below example does exactly the same thing as the above example, but does not use <code>values()</code>:<br />
|example2 = var hash = {<br />
"a": 1,<br />
"b": 2,<br />
"c": 3<br />
};<br />
<br />
foreach(var key; keys(hash)){<br />
print(hash[key]);<br />
<nowiki>}</nowiki><br />
}}<br />
<br />
==Extension functions new in FG 2020.1 ==<br />
The following functions have been added to the nasal core library and will be released with FlightGear version 2020.1. <br />
Before the release they are available in the development branch "next".<br />
<br />
===isfunc()===<br />
Returns 1 if type or argument is a function, otherwise 0.<br />
<br />
===isghost()===<br />
Returns 1 if type or argument is a ghost, otherwise 0.<br />
<br />
=== ishash()===<br />
Returns 1 if type or argument is a hash, otherwise 0.<br />
<br />
===isint()===<br />
{{Nasal doc<br />
|syntax = isint(x);<br />
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}<br />
|text = Returns 1 if argument has a numeric value and x == floor(x), e.g. integer.<br />
}}<br />
<br />
===isnum()===<br />
{{Nasal doc<br />
|syntax = isnum(x);<br />
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}<br />
|text = Returns 1 if typeof(x) is "scalar" and x has a numeric value otherwise 0. <br />
}}<br />
<br />
===isscalar()===<br />
{{Nasal doc<br />
|syntax = isscalar(x);<br />
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}<br />
|text = Returns 1 if type or argument is a scalar (string or numeric), otherwise (vector, hash, func, ...) it returns 0. This is useful to check if a variable can be converted to string e.g. when useing the string concat operator "~". <br />
|example1 = var a = "foo"; <br />
var b=42;<br />
if (isscalar(a) and isscalar(b)) print(a~b);<br />
if (isstr(a)) print("a is a string");<br />
if (isint(b)) print("b is an integer");<br />
# if (isscalar(a))... is equivalent to if (typeof(a) == "scalar")...<br />
}}<br />
<br />
===isstr()===<br />
Returns 1 if type or argument is a string, otherwise 0. <br />
<br />
===isvec()===<br />
Returns 1 if type or argument is a vector, otherwise 0.<br />
<br />
===vecindex()===<br />
{{Nasal doc<br />
|syntax = vecindex(vector, value);<br />
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}<br />
|text = Returns the index of value or nil, if value is not found in vector.<br />
|example1=<br />
var myvector = ["apple", "bananna", "coconut"];<br />
# to check if a vector contains a certain value compare vecindex to nil<br />
if (vecindex(myvector, "apple") != nil) {<br />
print("found apple");<br />
}<br />
# WARNING: this will not work as desired because index is 0<br />
if (vecindex(myvector, "apple")) {<br />
print("found apple");<br />
<nowiki>}</nowiki><br />
<br />
}}<br />
<br />
==Variables==<br />
Various global constants (technically variables) are provided for use in converting between different units. They are all found in {{fgdata file|Nasal/globals.nas|text=$FG_ROOT/Nasal/globals.nas}}.<br />
<br />
===D2R===<br />
{{Nasal doc<br />
|syntax = var radians = degrees * D2R;<br />
|text = Converts an angle from degrees to radians when multiplied by the angle in degrees. Equal to <code>π / 180</code>.<br />
}}<br />
===FPS2KT===<br />
{{Nasal doc<br />
|syntax = var knots = feet_per_second * FPS2KT;<br />
|text = Converts a velocity from feet per second to knots when multiplied by the velocity in feet per second. Approximately equal to 0.5925.<br />
}}<br />
===FT2M===<br />
{{Nasal doc<br />
|syntax = var metres = feet * FT2M;<br />
|text = Converts a length from feet to metres when multiplied by the length in feet. Equal to 0.3048.<br />
}}<br />
===GAL2L ===<br />
{{Nasal doc<br />
|syntax = var litres = gallons * GAL2L;<br />
|text = Converts a volume from US liquid gallons to litres when multiplied by the volume in gallons. Approximately equal to 3.7854.<br />
}}<br />
===IN2M===<br />
{{Nasal doc<br />
|syntax = var metres = inches * IN2M;<br />
|text = Converts a length from inches to metres when multiplied by the length in inches. Equal to 0.0254.<br />
}}<br />
===KG2LB===<br />
{{Nasal doc<br />
|syntax = var pounds = kilograms * KG2LB;<br />
|text = Converts a mass from kilograms to pounds when multiplied by the mass in kilograms. Approximately equal to 2.2046.<br />
}}<br />
===KT2FPS===<br />
{{Nasal doc<br />
|syntax = var feet_per_second = knots * KT2FPS;<br />
|text = Converts a velocity from knots to feet per second when multiplied by the velocity in knots. Approximately equal to 1.6878.<br />
}}<br />
===KT2MPS===<br />
{{Nasal doc<br />
|syntax = var metres_per_second = knots * KT2MPS;<br />
|text = Converts a velocity from knots to metres per second when multiplied by the velocity in knots. Approximately equal to 0.5144.<br />
}}<br />
===L2GAL===<br />
{{Nasal doc<br />
|syntax = var gallons = litres * L2GAL;<br />
|text = Converts a volume from litres to US liquid gallons when multiplied by the volume in litres. Approximately equal to 0.2642.<br />
}}<br />
===LB2KG===<br />
{{Nasal doc<br />
|syntax = var kilograms = pounds * LB2KG;<br />
|text = Converts a mass from pounds to kilograms when multiplied by the mass in pounds. Approximately equal to 0.4536.<br />
}}<br />
===M2FT ===<br />
{{Nasal doc<br />
|syntax = var feet = metres * M2FT;<br />
|text = Converts a length from metres to feet when multiplied by the length in metres. Approximately equal to 3.2808.<br />
}}<br />
===M2IN===<br />
{{Nasal doc<br />
|syntax = var inches = metres * M2IN;<br />
|text = Converts a length from metres to inches when multiplied by the length in metres. Approximately equal to 39.3701.<br />
}}<br />
===M2NM ===<br />
{{Nasal doc<br />
|syntax = var nautical_miles = metres * M2NM;<br />
|text = Converts a length from metres to nautical miles when multiplied by the length in metres. Approximately equal to 0.00054.<br />
}}<br />
===MPS2KT ===<br />
{{Nasal doc<br />
|syntax = var knots = metres_per_second * MPS2KT;<br />
|text = Converts a velocity from metres per second to knots when multiplied by the velocity in metres per second. Approximately equal to 1.9438.<br />
}}<br />
===NM2M ===<br />
{{Nasal doc<br />
|syntax = var metres = nautical_miles * NM2M;<br />
|text = Converts a length from nautical miles to metres when multiplied by the length in nautical miles. Equal to 1,852.<br />
}}<br />
===R2D===<br />
{{Nasal doc<br />
|syntax = var degrees = radians * R2D;<br />
|text = Converts an angle from radians to degrees when multiplied by the angle in radians. Equal to <code>180 / π</code>.<br />
}}<br />
<br />
{{Appendix}}<br />
<br />
<br />
{{Nasal namespaces}}</div>Clm76https://wiki.flightgear.org/w/index.php?title=Nasal_library&diff=118209Nasal library2019-05-10T07:10:00Z<p>Clm76: /* sort() */</p>
<hr />
<div>{{Nasal Navigation|nocat=1}}<br />
This page documents the global '''library functions and variables''' 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, the ''[[#Extension functions|extension functions]]'', which have been subsequently added, and are specifically designed for FlightGear, and the ''[[#variables|global variables]]'', which are conversion variables, added with extension functions, for converting between units. The relevant folders in [[Git]] are:<br />
* {{flightgear file|src/Scripting}}<br />
* {{simgear file|simgear/nasal}}<br />
<br />
All these functions and variables are in the global namespace, that is, they are directly accessible (e.g., one can call <syntaxhighlight lang="nasal" inline>magvar()</syntaxhighlight> instead of <syntaxhighlight lang="nasal" inline>namespace.magvar()</syntaxhighlight>). However, if a namespace must be used, <code>globals</code> is the correct namespace, but using it is not recommended. For a more complete explanation, see [[Nasal Namespaces in-depth]].<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|printerror()|debug}}.<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 (i.e. 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 lang="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 NOT identical to setting the hash value specified by the key to <code>'''nil'''</code> as the key will stay in the hash (at least for a while). 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 />
|commit = {{simgear commit|bd7163|t=commit}}<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 />
|commit = {{simgear commit|bd7163|t=commit}}<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()|link=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 />
|example2text = 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 />
|example3text = This example sorts a vector of strings (runways for example) from smallest to greatest.<br />
|example3 = <br />
var runways = ["09R","27R","26L","09L","15"];<br />
var rwy = sort(runways,func(a,b) cmp(a,b));<br />
debug.dump(rwy); # prints ['09L','09R','15','26L','27R']<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()|link=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. This includes the decimal point and decimal fraction.<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>s</code> {{!!}} A string<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 />
|example10 =<br />
print(sprintf("%.2f", 1.4)); #prints "1.40"<br />
print(sprintf("%.1f", 1.4)); #prints "1.4"<br />
print(sprintf("% 4.1f", 1.4)); #prints " 1.4"<br />
print(sprintf("%04.1f", 1.4)); #prints "01.4"<br />
print(sprintf("% 6.1f", 1.4)); #prints " 1.4"<br />
print(sprintf("%06.1f", 1.4)); #prints "0001.4"<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. Negative values specify a position from the end of the string.<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 />
|example4 = print(substr("abcde", -2)); # prints "de"<br />
|example5 = print(substr("abcde", -3, 2)); # prints "cd"<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 />
* Omitting the ''vector'' and ''start'' arguments is not an error (possibly it should be) but the return value is ''nil''.<br />
* A negative ''start'' argument ''is'' an error. This seems wrong. Perhaps the language designer could comment.<br />
* A value of ''start'' greater than ''size(vector)'' causes an error. A value equal to ''size(vector)'' returns an empty vector.<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 />
|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 modules ==<br />
=== thread ===<br />
{{WIP}}<br />
<br />
{{Nasal doc<br />
|syntax = thread.newthread(func);<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = start a new worker thread<br />
|example1 = thread.newthread( func() {} );<br />
}}<br />
<br />
{{Nasal doc<br />
|syntax = thread.newlock();<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = create a new lock<br />
|example1 = var lock = thread.newlock()<br />
}}<br />
<br />
{{Nasal doc<br />
|syntax = thread.lock();<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = lock a lock<br />
|example1 = var lock = thread.newlock()<br />
}}<br />
<br />
{{Nasal doc<br />
|syntax = thread.unlock();<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = unlock a lock<br />
|example1 = var lock = thread.unlock()<br />
}}<br />
<br />
<br />
{{Nasal doc<br />
|syntax = thread.newsem();<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = create a new {{Wikipedia|semaphore}}<br />
|example1 = var semaphore = thread.newsem()<br />
}}<br />
<br />
<br />
{{Nasal doc<br />
|syntax = thread.semdown();<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = semaphore down<br />
|example1 = thread.semdown(semaphore)<br />
}}<br />
<br />
<br />
{{Nasal doc<br />
|syntax = thread.semup();<br />
|source = {{simgear file|simgear/nasal/threadlib.c|l=101|t=Source}}<br />
|text = <br />
|example1text = semaphore up<br />
|example1 = thread.semup(semaphore)<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()|link=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 />
=== aircraftToCart() ===<br />
This new function in FG 2017.2.1 takes coordinates in aircraft structural coordinate system, and translate them into geocentric coordinates.<br />
Example for (5,6,7):<br />
<syntaxhighlight lang="nasal"><br />
var pos = aircraftToCart({x: -5, y: 6, z: -7});<br />
var coord = geo.Coord.new();<br />
coord.set_xyz(pos.x, pos.y, pos.z);<br />
</syntaxhighlight><br />
Notice: x and z is inverted sign on purpose.<br />
if you want lat. lon, alt from that, just call: (degrees and meters)<br />
<br />
<syntaxhighlight lang="nasal"><br />
coord.lat()<br />
coord.lon()<br />
coord.alt()<br />
</syntaxhighlight><br />
<br />
=== addcommand() ===<br />
{{Nasal doc<br />
|syntax = addcommand(name, code);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=659|t=Source}}<br />
|version = 2.12<br />
|commit = {{flightgear commit|7b663c|t=commit}}<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(node) {<br />
print("fgcommand 'myFGCmd' has been run.");<br />
props.dump( node );<br />
});<br />
fgcommand("myFGCmd", props.Node.new({foo:1, bar:2}) );<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 />
* '''parents''': A vector containing a hash of various functions to access information about the runway. See {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2659}} for full list.<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 />
*** '''id''': Name of runway.<br />
*** '''lat''': Latitude of the runway.<br />
*** '''lon''': Longitude of the runway.<br />
*** '''heading''': Heading of the runway.<br />
*** '''length''': Length of the runway in metres.<br />
*** '''width''': Width of the runway in metres.<br />
*** '''surface''': Runway surface type.<br />
*** '''threshold''': Length of the runway's {{wikipedia|displaced threshold}} in metres. Will return 0 if there is none.<br />
*** '''stopway''': Length of the runway's stopway (the area before the threshold) in metres. Will return 0 if there is none.<br />
*** '''reciprocal''': <code>runway</code> ghost of the reciprocal runway.<br />
*** '''ils_frequency_mhz''': ILS frequency in megahertz.<br />
*** '''ils''': <code>navaid</code> ghost of the ILS transmitter.<br />
* '''helipads'''<br />
** '''<helipad name>'''<br />
*** '''id''': Name of helipad.<br />
*** '''lat''': Latitude of the helipad.<br />
*** '''lon''': Longitude of the helipad.<br />
*** '''heading''': Heading of the helipad.<br />
*** '''length''': Length of the helipad in metres.<br />
*** '''width''': Width of the helipad in metres.<br />
*** '''surface''': Helipad surface type.<br />
* '''taxiways'''<br />
** '''<taxiway name>'''<br />
*** '''id''': Name of taxiway.<br />
*** '''lat''': Latitude of the taxiway.<br />
*** '''lon''': Longitude of the taxiway.<br />
*** '''heading''': Heading of the taxiway.<br />
*** '''length''': Length of the taxiway in metres.<br />
*** '''width''': Width of the taxiway in metres.<br />
*** '''surface''': Taxiway surface type.<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 />
|commit = {{fgdata commit|8b16a7|t=commit}}<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 />
=== createDiscontinuity() ===<br />
{{Nasal doc<br />
|syntax = createDiscontinuity();<br />
|text = Returns a <code>waypoint</code> ghost object. A route discontinuity is inserted by an {{abbr|FMS|Flight Management System}} when it is unsure how to connect two waypoints.<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2045|t=Source}}<br />
|version = 2016.1<br />
|commit = {{flightgear commit|caead6|t=commit}}<br />
}}<br />
=== createViaTo() ===<br />
{{Nasal doc<br />
|syntax = createViaTo(airway, waypoint);<br />
|text = Returns a <code>waypoint</code> ghost object. It represents a route "via '''airway''' to '''waypoint'''".<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2009|t=Source}}<br />
|version = 2016.1<br />
|commit = {{flightgear commit|caead6|t=commit}}<br />
|param1 = airway<br />
|param1text = The name of an airway.<br />
|param2 = waypoint<br />
|param2text = Must be in the airway and one of:<br />
* The name of a waypoint.<br />
* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, or <code>fix</code> ghost object.<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 />
=== get_cart_ground_intersection() ===<br />
Introduced in 2017.2.1, see [[Terrain Detection]].<br />
<br />
=== getprop() ===<br />
{{Nasal doc<br />
|syntax = getprop(path[, path[, ...]]);<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 = path<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 also 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 versions 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 from the Nasal file itself rather than from {{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 />
=== magvar() ===<br />
{{Nasal doc<br />
|syntax = magvar([pos]);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1642|t=Source}}<br />
|text = Returns the {{wikipedia|magnetic variation}} at a given set of coordinates. The table below gives the magnetic model used depending on the version of FlightGear.<br />
{{{!}} class="wikitable"<br />
! FlightGear versions !! Model !! Reference date<br />
{{!-}}<br />
{{!}} 3.6 and above {{!!}} {{wikipedia|World Magnetic Model}} (WMM) 2015 {{!!}} 1 January 2015<br />
{{!-}}<br />
{{!}} 0.9.11-pre1 to 3.4 {{!!}} WMM 2005 {{!!}} 1 January 2005<br />
{{!-}}<br />
{{!}} 0.7.3 to 0.9.10 {{!!}} WMM 2000 {{!!}} 1 January 2000<br />
{{!}}}<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>magvar(lat,lon)</code>.<br />
|example1 = print(magvar(0, 0)); # prints the magnetic variation at 0, 0<br />
}}<br />
<br />
=== maketimer() ===<br />
{{Nasal doc<br />
|syntax = maketimer(interval[, self], function);<br />
|source = ''Implemented using the {{API Link|flightgear|class|TimerObj}} class.''<br>{{flightgear file|src/Scripting/NasalSys.cxx|l=90|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=533|t=Part 2}}<br />
|version = 2.12<br />
|commit = {{flightgear commit|ab939f|t=commit}}<br />
|text = Returns a timer object containing the following methods and members:<br />
* '''start()''': Starts the timer.<br />
* '''stop()''': Stops the timer.<br />
* '''restart(interval)''': Restarts the timer with the given interval.<br />
* '''singleShot''': Bool showing whether the timer is only to be run once, or continuously until told to stop. Can be both set and read from (see examples).<br />
* '''isRunning''': Read-only bool telling whether the timer is currently running.<br />
* '''simulatedTime''': (FG 2017.1+; {{flightgear commit|0af316|t=commit}}) Bool telling whether the timer is using simulated time (which accounts for pause, etc.). Defaults to false (use real time). Can be both read and set. This cannot be changed while the timer is running.<br />
Unlike {{func link|settimer()}}, which it replaces, <code>maketimer()</code> provides more control over the timer. In addition, it can help reduce memory usage.<br />
|param1 = interval<br />
|param1text = Interval in seconds for the timer.<br />
|param2 = self<br />
|param2text = Optional parameter specifying what any <code>'''me'''</code> references in the function being called will refer to.<br />
|param3 = function<br />
|param3text = Function to be called at the given interval.<br />
|example1 = var timer = maketimer(1, func(){<br />
print("Hello, World!"); # print "Hello, World!" once every second (call timer.stop() to stop it)<br />
});<br />
timer.start();<br />
|example2 = var timer = maketimer(1, math, func(){<br />
print(me.math); # 'me' reference is the 'math' namespace<br />
});<br />
timer.singleShot = 1; # timer will only be run once<br />
timer.start();<br />
|example3 = var timer = maketimer(1, func(){<br />
print("Hello, World!"); # print "Hello, World!" once every second (call timer.stop() to stop it)<br />
});<br />
timer.start();<br />
print(timer.isRunning); # prints 1<br />
|example4text = In the example below, "Hello, World!" will be printed after one second the first time, and after two seconds thereafter.<br />
|example4 = var update = func(){<br />
print("Hello, World!");<br />
timer.restart(2); # restarts the timer with a two second interval<br />
}<br />
<br />
var timer = maketimer(1, update);<br />
timer.singleShot = 1;<br />
timer.start();<br />
}}<br />
<br />
=== maketimestamp() ===<br />
{{Nasal doc<br />
|syntax = maketimestamp()<br />
|source = ''Implemented using the {{API Link|flightgear|class|TimeStampObj}} class.''<br>{{flightgear file|src/Scripting/NasalSys.cxx|l=214|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=589|t=Part 2}}<br />
|version = 2019.2<br />
|commit = {{flightgear commit|7db06300|t=commit}}<br />
|text = Returns a time stamp object to allow high resolution timing of Nasal operations. When created the timer will automatically be stamped. The object has the following methods:<br />
* '''stamp()''': Resets the timing operation. Call this first.<br />
* '''elapsedMSec()''': returns number of milliseconds elapsed since stamp() called. Resolution may vary depending on platform but is usually at least millisecond accuracy.<br />
* '''elapsedUSec()''': returns number of microseconds elapsed since stamp() called. Resolution may vary depending on platform but is usually at least millisecond accuracy.<br />
|<br />
|example1text = In the example below the number of milliseconds elapsed will be printed.<br />
|example1 = var timestamp = maketimestamp();<br />
timestamp.stamp();<br />
print(timestamp.elapsedMSec(), "ms elapsed");<br />
print(timestamp.elapsedMSec(), "ms elapsed");<br />
}}<br />
<br />
=== md5() ===<br />
{{Nasal doc<br />
|syntax = md5(string);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=758|t=Source}}<br />
|version = 3.2<br />
|commit = {{flightgear commit|cfbf9e|t=commit}}<br />
|text = Returns a the {{wikipedia|MD5}} hash (as a string) of the inputted string.<br />
|param1 = string<br />
|param1text = String the generate the hash of. Mandatory.<br />
|example1text = The below code should output <code>65a8e27d8879283831b664bd8b7f0ad4</code>.<br />
|example1 = print(md5("Hello, World!"));<br />
}}<br />
<br />
=== navinfo() ===<br />
{{Nasal doc<br />
|syntax = navinfo(lat, lon, type, id);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1453|t=Source}}<br />
|text = Returns vector <code>navaid</code> ghost objects matching the given '''type''' and '''id''' or <code>'''nil'''</code> on error.<br />
|param1 = lat ''and'' lon<br />
|param1text = If given, the returned navaids will be put into order of ascending distance from the location.<br />
|param2 = type<br />
|param2text = Narrows the search to the given type. Must be one of "any," "fix," "vor," "ndb," "ils," "dme," or "tacan." Defaults to the equivalent of "any."<br />
|param3 = id<br />
|param3text = ID to search for. Note that, although all the parameters are technically optional, this parameter must be given, otherwise an empty vector will be returned.<br />
|example1 = navinfo("vor"); # returns all VORs<br />
|example2 = navinfo("HAM"); # return all navaids whose names start with "HAM"<br />
|example3 = navinfo("vor", "HAM"); # return all VORs whose names start with "HAM"<br />
|example4 = navinfo(34,48,"vor","HAM"); # return all VORs whose names start with "HAM" and sorted by distance relative to 34°, 48°<br />
}}<br />
<br />
=== parse_markdown() ===<br />
{{Nasal doc<br />
|syntax = parse_markdown(markdown);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=745|t=Part 1}} {{!}} {{simgear file|simgear/misc/SimpleMarkdown.cxx|t=Part 2}} <br />
|version = 3.2<br />
|text = Parses a string containing {{wikipedia|Markdown}} and returns the result as a string. As of FlightGear 2016.1, it is just a simple parser, and does the following:<br />
* It strips whitespace from the beginning of the string.<br />
* It supports [http://daringfireball.net/projects/markdown/syntax#p paragraphs and line breaks].<br />
* It collapses whitespace.<br />
* It converts unordered [http://daringfireball.net/projects/markdown/syntax#list lists] to use a bullet character (&bull;). Note that the bullet character is implemented in hexadecimal UTF-8 character bytes (<code>E2 80 A2</code>), as so may not work properly when the being displayed in an encoding other than UTF-8.<br />
|param1 = markdown<br />
|param1text = String containing Markdown to be parsed.<br />
|example1text = <br />
Save the below code as <tt>''[[$FG_ROOT]]/gui/dialogs/test.xml''</tt>, then run the Nasal code below it to open the dialog. To change the markdown to be parsed, simply change the code in the highlighted section, save it, and reload the GUI (<tt>Debug > Reload GUI</tt>).<br />
<syntaxhighlight lang="xml" highlight="41-50"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<br />
<PropertyList><br />
<br />
<name>test</name><br />
<layout>vbox</layout><br />
<br />
<group><br />
<layout>hbox</layout><br />
<br />
<empty><br />
<stretch>true</stretch><br />
</empty><br />
<br />
<text><br />
<label>parse_markdown() test dialog</label><br />
</text><br />
<br />
<empty><br />
<stretch>true</stretch><br />
</empty><br />
<br />
<button><br />
<legend></legend><br />
<pref-width>16</pref-width><br />
<pref-height>16</pref-height><br />
<binding><br />
<command>dialog-close</command><br />
</binding><br />
</button><br />
<br />
</group><br />
<br />
<canvas><br />
<name>Canvas plot</name><br />
<stretch>true</stretch><br />
<pref-width>400</pref-width><br />
<pref-height>300</pref-height><br />
<nasal><br />
<load><![CDATA[<br />
var text = 'Items:<br />
* apples<br />
* oranges<br />
* pears<br />
<br />
Some text.<br />
Some more items:<br />
* apples<br />
* oranges<br />
* pears';<br />
<br />
var parsed = parse_markdown(text);<br />
<br />
var root_canvas = canvas.get(cmdarg());<br />
root_canvas.setColorBackground(255, 255, 255);<br />
var root = root_canvas.createGroup();<br />
<br />
var text_dis = root.createChild("text")<br />
.setText(parsed)<br />
.setTranslation(5, 5)<br />
.setFont("LiberationFonts\LiberationSans-Regular.ttf")<br />
.setFontSize(15)<br />
.setColor(0, 0, 0)<br />
.setDrawMode(canvas.Text.TEXT)<br />
.setAlignment("left-top");<br />
]]></load><br />
</nasal><br />
</canvas><br />
<br />
</PropertyList><br />
</syntaxhighlight><br />
|example1 = fgcommand("dialog-show", {"dialog-name": "test"});<br />
|example2text = The example below parses Markdown and outputs it in a HTML document. The parsed text is placed in <syntaxhighlight lang="xml" inline><pre></pre></syntaxhighlight> tags. To change the Markdown to be parsed, simply edit the variable <tt>markdown</tt> at the top of the code.<br />
|example2 = <nowiki>var markdown = 'Items:<br />
* apples<br />
* oranges<br />
* pears<br />
<br />
Some text.<br />
Some more items:<br />
* apples<br />
* oranges<br />
* pears';<br />
<br />
var parsed = parse_markdown(markdown);<br />
<br />
debug.dump(parsed);<br />
<br />
var path = string.normpath(getprop("/sim/fg-home") ~ '/Export/parse_markdown()-test.html');<br />
<br />
var file = io.open(path, "w");<br />
<br />
var html = "<!DOCTYPE html>\n\n<html>\n\n<head>\n\t<meta charset=\"UTF-8\">\n\t<title>parse_markdown() test generated by Nasal</title>\n</head>\n\n<body>\n\t<pre>" ~ parsed ~ "</pre>\n</body>\n\n</html>";<br />
<br />
io.write(file, html);<br />
io.close(file);<br />
print("Done, file ready for viewing (" ~ path ~ ")");</nowiki><br />
}}<br />
<br />
=== parsexml() ===<br />
{{Nasal doc<br />
|syntax = parsexml(path[, start[, end[, data[, pro_ins]]]]);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=710|t=Source}}<br />
|text = This function is an interface into the built-in [http://expat.sourceforge.net/ Expat XML parser]. The absolute path to the file is returned as string, or <code>'''nil'''</code> is returned on error.<br />
|param1 = path<br />
|param1text = Mandatory absolute path to the XML file to be parsed.<br />
|param2 = start<br />
|param2text = Optional callback function that will be called for every starting tag. The function should take two argument: the tag name and a hash containing attributes.<br />
|param3 = end<br />
|param3text = Optional callback function that will be called for every ending tag. The function should take one argument: the tag name.<br />
|param4 = data<br />
|param4text = Optional callback function that will be called for every piece of data within a set of tags. The function should take one argument: the data as a string.<br />
|param5 = pro_ins<br />
|param5text = Optional callback function that will be called for every {{wikipedia|Processing Instruction|processing instruction}}. The function should take two argument: the target and the data string.<br />
|example1text = Save the below XML code in <tt>''[[$FG_HOME]]/Export/demo.xml''</tt>. Then, execute the Nasal code below in the Nasal Console. The XML will be parsed and each bit of the code will be printed.<br />
<syntaxhighlight lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<br />
<?xml-stylesheet type="text/xsl" href="style.xsl"?><br />
<br />
<foo><br />
<blah type="string"><![CDATA[ <sender>John Smith</sender> ]]></blah><br />
<blah2 type="string">Orange &amp; lemons</blah2><br />
</foo><br />
</syntaxhighlight><br />
|example1 = 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 />
}<br />
<br />
var end = func(name){<br />
print("Ending tag: '", name, "'");<br />
}<br />
<br />
var data = func(data){<br />
print("Data = '", data, "'");<br />
}<br />
<br />
var pro_instr = func(target, data){<br />
print("Processing instruction: target = '", target, "', data = '", data, "'");<br />
}<br />
<br />
parsexml(getprop("/sim/fg-home") ~ '/Export/demo.xml', start, end, data, pro_instr);<br />
}}<br />
<br />
=== print() ===<br />
{{Nasal doc<br />
|syntax = print(data[, data[, ...]]);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=415|t=Source}}<br />
|text = Concatenates its arguments and then prints it to the terminal and the [[Commonly used debugging tools#fgfs.log|log]]. Note that a newline is automatically added.<br />
|param1 = data<br />
|param1text = Data to print. Only strings and numbers can be printed; other data types will not be. There many be any number of arguments; they will just be concatenated together.<br />
|example1 = print("Just", " a ", "test"); # prints "Just a test"<br />
|example2 = print("pi = ", math.pi); # prints "pi = 3.141592..."<br />
}}<br />
<br />
=== printf() ===<br />
{{Nasal doc<br />
|syntax = printf(format[, arg[, arg, [...]]]);<br />
|source = {{fgdata file|Nasal/globals.nas|t=Source}}<br />
|text = Creates and prints a formatted string. For a description of its arguments, see {{func link|sprintf()}} (it is, in fact, implemented using <code>sprintf()</code>).<br />
|example1 = printf("In hexadecimal, 100000 = %X", 186A0); # prints "In hexadecimal, 100000 = 186A0"<br />
}}<br />
<br />
=== printlog() ===<br />
{{Nasal doc<br />
|syntax = printlog(level, data[, data[, ...]]);<br />
|source = {{fgdata file|Nasal/globals.nas|t=Source}}<br />
|text = Prints the given message with the given log level. If the log level is higher or equal to <code>/sim/logging/priority</code>, it is printed.<br />
|param1 = level<br />
|param1text = Mandatory log level as a string. Must be one of "none," "bulk," "debug," "info," "warn," or "alert." Note that "none" will mean that the message will never be printed.<br />
|param2 = data<br />
|param2text = Data to be printed. Only strings and numbers will be printed; others will not be. There may be any number of arguments; they will just be concatenated together.<br />
|example1 = printlog("alert", "This is an alert"); # message will be printed<br />
|example2 = printlog("info", "Just informing you about something"); # message will be printed only if log level is set to "info" or less<br />
}}<br />
<br />
=== rand() ===<br />
{{Nasal doc<br />
|syntax = rand();<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=554|t=Source}}<br />
|text = Returns a random floating point number between 0 (inclusive) and 1 (exclusive). It takes no arguments.<br />
|example1 = print(rand()); # prints random number<br />
}}<br />
<br />
=== registerFlightPlanDelegate() ===<br />
{{Nasal doc<br />
|syntax = registerFlightPlanDelegate(init_func);<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1879|t=Source}}<br />
|text = Registers a flight plan delegate. See <tt>''{{fgdata file|Nasal/route_manager.nas|t=$FG_ROOT/Nasal/route_manager.nas}}''</tt> for examples.<br />
|param1 = init_func<br />
|param1text = Initialization function which will be called during FlightGear's startup.<br />
}}<br />
=== removecommand() ===<br />
{{Nasal doc<br />
|syntax = removecommand(cmd);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=668|t=Source}}<br />
|text = Removes the given fgcommand. Returns <code>'''nil'''</code>.<br />
{{caution|This will remove '''any''' [[fgcommands|fgcommand]], even those implemented in C++, so use with caution!}}<br />
|param1 = cmd<br />
|param1text = String specifying the name of the command to remove.<br />
|example1 = addcommand("hello", func(){<br />
print("Hello");<br />
});<br />
fgcommand("hello"); # "Hello" will be printed<br />
removecommand("hello"); # removes it<br />
}}<br />
<br />
=== removelistener() ===<br />
{{Nasal doc<br />
|syntax = removelistener(id);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=1384|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=506|t=Part 2}}<br />
|text = Removes and deactivates the given listener and returns the number of listeners left or <code>'''nil'''</code> on error.<br />
{{note|It is good practice to remove listeners when they are not required anymore. This prevents the listeners reducing FlightGear's run performance.}}<br />
|param1 = id<br />
|param1text = ID of listener as returned by {{func link|setlistener()}}.<br />
|example1 = var ls = setlistener("/sim/test", func(){<br />
print("Property '/sim/test' has been changed");<br />
});<br />
setprop("/sim/test", "blah"); # trigger listener<br />
var rem = removelistener(ls); # remove listener<br />
print("There are ", rem, " listeners remaining");<br />
}}<br />
<br />
=== resolvepath() ===<br />
{{Nasal doc<br />
|syntax = resolvepath(path);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=604|t=Source}}<br />
|text = Takes a relative path as a string and uses [[SimGear]]'s path-resolving framework to return an absolute path as a string. If the path could not be resolved, an empty string is returned. See [[Resolving Paths]] for a detailed description of the algorithm. This function can also be used to check if a file exists.<br />
|param1 = path<br />
|param1text = Relative path to be completed.<br />
|example1 = print(resolvepath("Nasal/globals.nas")); # prints the equivalent of $FG_ROOT/Nasal/globals.nas<br />
|example2 = print(resolvepath("blah")); # prints nothing; could not be resolved<br />
|example3 = var file_path = resolvepath("Aircraft/SenecaII/some-file");<br />
if (file_path != ""){<br />
gui.popupTip("some-file found", 2);<br />
} else {<br />
gui.popupTip("some-file not found", 2);<br />
}<br />
}}<br />
<br />
=== setlistener() ===<br />
{{Nasal doc<br />
|syntax = setlistener(node, code[, init[, type]]);<br />
|private = _setlistener()<br />
|source = {{flightgear file|src/Scripting/Nasal|l=499|t=Part 1}} {{!}} {{flightgear file|src/Scripting/Nasal|l=1350|t=Part 2}}<br>''Listener implemented using the {{API Link|flightgear|class|FGNasalListener}} class.''<br />
|text = Creates a listener which will be triggered when the given property is changed (depending on the '''type'''). A unique integer ID is returned; this can later be used as the argument to {{func link|removelistener()}}.<br />
{{note|Listeners are known to be a source of resource leaks. To avoid this, please take measures such as:<br />
* Using {{func link|removelistener()}} when they are not needed any more.<br />
* Using a single initialization listener.<br />
* Avoiding tying listeners to properties that are rapidly updated (e.g., many times per frame).<br />
}}<br />
|param1 = node<br />
|param1text = Mandatory string or <code>props.Node</code> object pointing to a property in the [[Property Tree]].<br />
|param2 = code<br />
|param2text = Mandatory callback function to execute when the listener is triggered. The function can take up to four arguments in the following order:<br />
* '''changed''': a <code>props.Node</code> object pointing to the changed node.<br />
* '''listen''': a <code>props.Node</code> object pointing to the listened-to node. Note that this argument maybe different depending on the '''type'''.<br />
* '''mode''': an integer telling how the listener was triggered. 0 means that the value was changed. 1 means that a child property was added. -1 means that a child property was removed.<br />
* '''is_child''': boolean telling whether '''changed''' is a child property of the listened-to '''node''' or not. 1 (true) if it is, 0 (false) otherwise.<br />
|param3 = init<br />
|param3text = If set to 1 (true), the listener will additionally be triggered when it is created. This argument is optional and defaults to 0 (false).<br />
|param4 = type<br />
|param4text = Integer specifying the listener's behavior. 0 means that the listener will only trigger when the property is changed. 1 means that the trigger will always be triggered when the property is written to. 2 will mean that the listener will be triggered even if child properties are modified. This argument is optional and defaults to 1.<br />
|example1 = var prop = props.globals.initNode("/sim/test", "", "STRING"); # create property<br />
var id = setlistener("/sim/test", func(n){ # create listener<br />
print("Value: ", n.getValue());<br />
});<br />
setprop("/sim/test", "blah"); # trigger listener<br />
removelistener(id); # remove listener<br />
prop.remove(); # remove property<br />
}}<br />
<br />
=== setprop() ===<br />
{{Nasal doc<br />
|syntax = setprop(path[, path[, ...]], value);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=385|t=Source}}<br />
|text = Sets the value of a property in the [[Property Tree]]. If the property does not exist, it will be created. Returns 1 (true) on success or 0 (false) if there was an error.<br />
{{note|If you want to remove a property, you will have to use one of the <code>props</code> helpers:<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 />
|param1 = path<br />
|param1text = There needs to be at least one '''path''' argument, but there is no limit to the maximum amount that can be given. They will be concatenated together to form a property tree path. The arguments must be strings, but in FlightGear v3.2 onwards, there also is support (added by {{flightgear commit|34ed79}}) for numeric arguments as indices. See example 2 below.<br />
|param2 = value<br />
|param2text = Value to write to the given property. Must be either a string or a number.<br />
|example1 = setprop("/sim/demo", "This is a demo");<br />
|example2text = Note that the example below will only work in FlightGear 3.2 and above.<br />
|example2 = for(var i = 0; i < 3; i += 1){<br />
setprop("/sim/demo", i, "Demo #" ~ i));<br />
}<br />
|example3text = Same as above, but is supported by all versions of FlightGear.<br />
|example3 = for(var i = 0; i < 3; i += 1){<br />
setprop("/sim/demo[" ~ i ~ "]", "Demo #" ~ i));<br />
}<br />
}}<br />
<br />
=== settimer() ===<br />
{{Nasal doc<br />
|syntax = settimer(function, delta[, realtime]);<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=499|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=1286|t=Part 2}}<br />
|text = Runs the given function a specified amount of seconds after the current time. Returns <code>'''nil'''</code>.<br />
{{note|Improper use of <code>settimer()</code> may cause resource leaks. It is also highly recommended that the newer {{func link|maketimer()}} should be used instead of this function.}} <br />
|param1 = function<br />
|param1text = Mandatory function that will be called. It may be necessary to enclose code in an anonymous function (see example).<br />
|param2 = delta<br />
|param2text = Mandatory amount of time in seconds after which the function will be called.<br />
|param3 = realtime<br />
|param3text = If 1 (true), "real time" will be used instead of "simulation time." Defaults to 0 (false). Note that if "simulation time" is used, the timer will not run while FlightGear is paused.<br />
|example1 = var myFunc = func(){<br />
print("Hello");<br />
}<br />
<br />
settimer(myFunc, 2); # runs myFunc after 2 seconds<br />
|example2 = var sqr = func(a){<br />
return a * a;<br />
}<br />
<br />
settimer(func(){<br />
print(sqr(2)); # will print 4 after 2 seconds<br />
}, 2);<br />
}}<br />
<br />
=== srand() ===<br />
{{Nasal doc<br />
|syntax = srand();<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=559|t=Source}}<br />
|text = Makes the pseudorandom number generator (see {{func link|rand()}}) generate a new {{wikipedia|random seed|noicon=1}} based on time. Returns 0.<br />
}}<br />
=== systime() ===<br />
{{Nasal doc<br />
|syntax = systime();<br />
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=770|t=Source}}<br />
|text = Returns the {{wikipedia|Unix time}} (seconds since since 00:00:00 UTC, 1/1/1970) as a floating point number with high resolution. This function is useful for benchmarking purposes (see example 2).<br />
{{note|1=High resolution timers under Windows can produce inaccurate or fixed sub-millisecond results.<ref>{{cite web|url=http://forum.flightgear.org/viewtopic.php?f=30&t=29259|title=Nasal: systime() ??!?|author=Necolatis|date=Apr 2nd, 2016}}</ref> This is due to the underlying {{func link|GetSystemTimeAsFileTime()|link=https://msdn.microsoft.com/en-us/library/windows/desktop/ms724397(v=vs.85).aspx}} API call, which depends on hardware availability of suitable high resolution timers. See also [https://msdn.microsoft.com/en-us/library/windows/desktop/dn553408(v=vs.85).aspx Acquiring high-resolution time stamps]}}<br />
|example1 = print("Unix time: ", systime()); # prints Unix time<br />
|example2 = var myFunc = func(){<br />
for(var i = 0; i <= 10; i += 1){<br />
print("Interation #", i);<br />
}<br />
}<br />
var t = systime(); # record time<br />
myFunc(); # run function<br />
var t2 = systime(); # record new time<br />
print("myFunc() took ", t2 - t, " seconds"); # print result<br />
}}<br />
<br />
=== thisfunc() ===<br />
{{Nasal doc<br />
|syntax = thisfunc();<br />
|source = {{fgdata file|Nasal/globals.nas|t=Source}}<br />
|text = Returns the function from which this function is called. This allows a function to reliably and safely call itself from within a closure.<br />
|example1 = var stringify_vec = func(input){<br />
if (typeof(input) == "scalar"){<br />
return sprintf("%s", input);<br />
} elsif (typeof(input) == "vector") {<br />
if (size(input) == 0) return "[]";<br />
var this = thisfunc();<br />
var buffer = "[";<br />
for(var i = 0; i < size(input); i += 1){<br />
buffer ~= this(input[i]);<br />
if (i == size(input) - 1) {<br />
buffer ~= "]";<br />
} else {<br />
buffer ~= ", ";<br />
}<br />
}<br />
return buffer;<br />
} else {<br />
die("stringify_vec(): Error! Invalid input. Must be a vector or scalar");<br />
}<br />
}<br />
<br />
var test_vec = ["a", "b", "c", 1, 2, 3];<br />
debug.dump(stringify_vec(test_vec)); # prints "[a, b, c, 1, 2, 3]"<br />
test_vec = [];<br />
debug.dump(stringify_vec(test_vec)); # prints "[]"<br />
test_vec = {};<br />
debug.dump(stringify_vec(test_vec)); # will throw an error<br />
}}<br />
<br />
=== tileIndex() ===<br />
{{Nasal doc<br />
|syntax = tileIndex();<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1720|t=Source}}<br />
|text = Returns the index of the tile at the aircraft's current position as a string. This corresponds to the name of the STG file of the tile. For example, at [[KSFO]], this would be <code>942050</code>, corresponding to <tt>''[[$FG_SCENERY]]/Terrain/w130n30/w123n3/942050.stg''</tt>.<br />
|example1 = print(tileIndex()); # print index<br />
}}<br />
<br />
=== tilePath() ===<br />
{{Nasal doc<br />
|syntax = tilePath();<br />
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1712|t=Source}}<br />
|text = Returns the base path of the tile at the aircraft's current position as a string. For example, at KSFO, this would be <code>w130n30/w123n3</code>, corresponding to <tt>''[[$FG_SCENERY]]/Terrain/w130n30/w123n3''</tt>.<br />
|example1 = print(tilePath()); # print path<br />
}}<br />
<br />
=== values() ===<br />
{{Nasal doc<br />
|syntax = values(hash);<br />
|source = {{fgdata file|Nasal/globals.nas|t=Source}}<br />
|text = Returns a vector containing the values of the given hash.<br />
|param1 = hash<br />
|param1text = Mandatory hash to get the values of.<br />
|example1 = var hash = {<br />
"a": 1,<br />
"b": 2,<br />
"c": 3<br />
};<br />
<br />
foreach(var val; values(hash)){<br />
print(val);<br />
}<br />
|example2text = The below example does exactly the same thing as the above example, but does not use <code>values()</code>:<br />
|example2 = var hash = {<br />
"a": 1,<br />
"b": 2,<br />
"c": 3<br />
};<br />
<br />
foreach(var key; keys(hash)){<br />
print(hash[key]);<br />
}<br />
}}<br />
<br />
== Variables ==<br />
Various global constants (technically variables) are provided for use in converting between different units. They are all found in {{fgdata file|Nasal/globals.nas|text=$FG_ROOT/Nasal/globals.nas}}.<br />
<br />
=== D2R ===<br />
{{Nasal doc<br />
|syntax = var radians = degrees * D2R;<br />
|text = Converts an angle from degrees to radians when multiplied by the angle in degrees. Equal to <code>π / 180</code>.<br />
}}<br />
=== FPS2KT ===<br />
{{Nasal doc<br />
|syntax = var knots = feet_per_second * FPS2KT;<br />
|text = Converts a velocity from feet per second to knots when multiplied by the velocity in feet per second. Approximately equal to 0.5925.<br />
}}<br />
=== FT2M ===<br />
{{Nasal doc<br />
|syntax = var metres = feet * FT2M;<br />
|text = Converts a length from feet to metres when multiplied by the length in feet. Equal to 0.3048.<br />
}}<br />
=== GAL2L ===<br />
{{Nasal doc<br />
|syntax = var litres = gallons * GAL2L;<br />
|text = Converts a volume from US liquid gallons to litres when multiplied by the volume in gallons. Approximately equal to 3.7854.<br />
}}<br />
=== IN2M ===<br />
{{Nasal doc<br />
|syntax = var metres = inches * IN2M;<br />
|text = Converts a length from inches to metres when multiplied by the length in inches. Equal to 0.0254.<br />
}}<br />
=== KG2LB ===<br />
{{Nasal doc<br />
|syntax = var pounds = kilograms * KG2LB;<br />
|text = Converts a mass from kilograms to pounds when multiplied by the mass in kilograms. Approximately equal to 2.2046.<br />
}}<br />
=== KT2FPS ===<br />
{{Nasal doc<br />
|syntax = var feet_per_second = knots * KT2FPS;<br />
|text = Converts a velocity from knots to feet per second when multiplied by the velocity in knots. Approximately equal to 1.6878.<br />
}}<br />
=== KT2MPS ===<br />
{{Nasal doc<br />
|syntax = var metres_per_second = knots * KT2MPS;<br />
|text = Converts a velocity from knots to metres per second when multiplied by the velocity in knots. Approximately equal to 0.5144.<br />
}}<br />
=== L2GAL ===<br />
{{Nasal doc<br />
|syntax = var gallons = litres * L2GAL;<br />
|text = Converts a volume from litres to US liquid gallons when multiplied by the volume in litres. Approximately equal to 0.2642.<br />
}}<br />
=== LB2KG ===<br />
{{Nasal doc<br />
|syntax = var kilograms = pounds * LB2KG;<br />
|text = Converts a mass from pounds to kilograms when multiplied by the mass in pounds. Approximately equal to 0.4536.<br />
}}<br />
=== M2FT ===<br />
{{Nasal doc<br />
|syntax = var feet = metres * M2FT;<br />
|text = Converts a length from metres to feet when multiplied by the length in metres. Approximately equal to 3.2808.<br />
}}<br />
=== M2IN ===<br />
{{Nasal doc<br />
|syntax = var inches = metres * M2IN;<br />
|text = Converts a length from metres to inches when multiplied by the length in metres. Approximately equal to 39.3701.<br />
}}<br />
=== M2NM ===<br />
{{Nasal doc<br />
|syntax = var nautical_miles = metres * M2NM;<br />
|text = Converts a length from metres to nautical miles when multiplied by the length in metres. Approximately equal to 0.00054.<br />
}}<br />
=== MPS2KT ===<br />
{{Nasal doc<br />
|syntax = var knots = metres_per_second * MPS2KT;<br />
|text = Converts a velocity from metres per second to knots when multiplied by the velocity in metres per second. Approximately equal to 1.9438.<br />
}}<br />
=== NM2M ===<br />
{{Nasal doc<br />
|syntax = var metres = nautical_miles * NM2M;<br />
|text = Converts a length from nautical miles to metres when multiplied by the length in nautical miles. Equal to 1,852.<br />
}}<br />
=== R2D ===<br />
{{Nasal doc<br />
|syntax = var degrees = radians * R2D;<br />
|text = Converts an angle from radians to degrees when multiplied by the angle in radians. Equal to <code>180 / π</code>.<br />
}}<br />
<br />
{{Appendix}}<br />
<br />
<br />
{{Nasal namespaces}}</div>Clm76https://wiki.flightgear.org/w/index.php?title=FG1000&diff=116247FG10002018-09-29T16:17:35Z<p>Clm76: /* Load and start the FG1000 system */</p>
<hr />
<div><br />
[[File:Mirrored MFD.png|thumb|FG1000 MFD being displayed (incorrectly!) in a DA-40, and mirrored to a GUI window at 50% scale (02/2018)]]<br />
[[File:FG1000 SVG UI.jpg|thumb|Stuart pushed an SVG UI for the FG1000, replacing the PUI version. (01/2018)]]<br />
<br />
{{Infobox subsystem<br />
|name = FG1000<br />
|started = 07/2017 <br />
|description = G1000-based MFD emulation<br />
|status = Under active development as of 07/2017<br />
|developers = {{Usr|Stuart}}, Richard (via [[Emesary]]), Michat (UI graphics), www2 (3D artwork) <ref>https://forum.flightgear.org/viewtopic.php?f=71&t=32764&start=60#p327229</ref><br />
|changelog = https://sourceforge.net/p/flightgear/fgdata/ci/next/log/?path=/Aircraft/Instruments-3d/FG1000<br />
|folders = https://sourceforge.net/p/flightgear/fgdata/ci/next/tree/Aircraft/Instruments-3d/FG1000/<br />
}}<br />
<br />
<br />
== Current Status ==<br />
<br />
06/04/2018:<br />
* PFD is largely complete. Transponder, NRST, ALT units and alternative units still to implement.<br />
* MFD is functional, and now includes display and editing of the current flightplan, along with moving map, engine information.<br />
* MFD and PFD can be displayed as a GUI window under Debug menu or added to an aircraft with the GDU-1045 model as part of a 3D cockpit. <br />
<br />
There's still a huge number of pages to write, and the more complex pages around route planning will likely be particularly challenging, but it should be far faster now these blocks are in place. . If anyone is interested in creating a specific page, please also get in touch with Stuart. The various ''Nearest... and ...Information'' pages should be quite easy to do based on the pages that have been written already. See the Design Notes for details.<br />
<br />
Next steps:<br />
* Writing the remaining (large) number of pages<br />
* Styling the pages - making the iconography match Garmin exactly.<br />
<br />
=== Gallery ===<br />
<gallery mode=packed widths=230px heights=230px><br />
PFD 20180406.png|FG1000 PFD showing inset map, current wind data, HSI with GPS bearing, active flightplan list<br />
MFD 20180406.png|FG1000 MFD with Cessna 182T Engine Information System (EIS), and Active Flightplan<br />
FG1000_Checklist_MFD_page.png|FG1000 MFD with Checklist page displayed<br />
</gallery><br />
<br />
== A Cheat's Guide to Using the FG1000 ==<br />
<br />
For those without the time or interest to read the G1000 User Guide, here's a very quick run-down on navigating through the MFD:<br />
<br />
General:<br />
* Click on the buttons, though some are not implemented yet.<br />
* Use the mouse wheel to scroll the knobs (NAV, HDG, ALT, COM, CRS/BARO, RANGE, FMS). For knobs with both and inner and an outer (NAV, COM, CRS/BARO, FMS), scrolling when pressing the Shift key changes the outer knob.<br />
* Use the outer FMS knob (shift-mouse wheel on the FMS knob on the bottom right) to navigate through the page groups.<br />
* Use the inner FMS knob (mouse wheel on the FMS knob on the bottom right) to navigate through the pages within the group. The currently selected page is shown in blue. If you stop moving the cursor, the page will be loaded in 0.5s.<br />
* Within a page, click on the FMS knob to activate the cursor (CRSR). You you should see some element highlighted on the page, typically flashing. You can navigate around the page using the outer and inner FMS knobs. The Outer FMS knob (shift-mouse wheel) typical moves the cursor between elements. The Inner FMS knob typically changes the selected item.<br />
* Use the RANGE knob to zoom map views in/out.<br />
<br />
Implemented function:<br />
<br />
PFD:<br />
* Artificial horizon, compass rose, altimeter and airspeed indicator<br />
* HSI that can display NAV1, NAV2, GPS deviation (press CDI)<br />
* Wind information (press PFD->WIND then select one of the options for display)<br />
* Bearings to NAV1, NAV2, GPS (press PFD then BRG1/BRG2 to cycle through the options)<br />
* Inset Map (Press INSET softkey)<br />
* Active Flight Plan (press FPL when there is an active flightplan to display)<br />
* DirectTo GPS (press DTO)<br />
<br />
MFD:<br />
* There is a two channel NAV/COM with an active and standby frequency and automatic ID of NAV frequencies at the top of the UI. They all integrate with the standard properties, so should work automatically with most aircraft.<br />
* If you have a frequency highlighted in any of the pages (e.g. WPT - AIRPORT INFORMATION) press the ENT key to load it into the standby NAV/COM frequency as appropriate.<br />
* To set up a GPS Direct To route:<br />
** Press the DTO button (D with an arrow through it on the right side of the panel, below the word "PAN"). This will bring up a Direct To window, allowing you to enter the ID of an airport, Fix etc. to navigate to.<br />
** You can enter the ID in one of two ways:<br />
*** Scroll the FMS knob backwards to bring up a sub-menu of waypoints categories (FPL, NRST, RECENT, USER, AIRWAY). Use the inner FMS knob to scroll between the different categories, and the outer FMS knob to select a specific item. <br />
*** Scroll the FMS knob forwards to enter an ID manually using the FMS knob. Use the outer FMS knob to move to the next poisition in the ID. <br />
** Once you've got an ID, press ENT which will load details into the window and highlight the ACTIVATE button.<br />
** Press ENT once more to load the Direct-to into the GPS and activate it.<br />
* To view airport information, select the WPT - AIRPORT INFORMATION page. Use the outer FMS knob to move between the AIRPORT, RUNWAYS and FREQUENCY boxes, and the inner FMS to edit the airport ID, scroll through available runways, or highlight a frequency.<br />
* To edit the current flightplan, press the FPL page, then press the CRSR and enter waypoints for DTO above.<br />
<br />
== Aircraft Installation ==<br />
<br />
Adding the FG1000 to an aircraft is intended to be fairly straightforward.<br />
<br />
=== Add the GDU to the cockpit ===<br />
<br />
Place one or more of the display (GDU) units in your model. The XML files<br />
are in GDU104X directory and are named <model>.<device-number>.xml, e.g.<br />
<br />
GDU-1045.1.xml GDU-1045.2.xml GDU-1045.3.xml GDU-1045.4.xml<br />
<br />
The <device-number> is referenced later to identify which displays to used<br />
for each PFD, MFD etc. You must only used one of each <device-number> value,<br />
though you can mix and match the GDU models.<br />
<br />
The different GDU models are as follows:<br />
<br />
* GDU-1040 - No autopilot controls<br />
* GDU-1044B - autopilot controls without VNAV<br />
* GDU-1045 - autopilot controls with VNAV<br />
<br />
=== Load the Interfaces to provide data ===<br />
<br />
This is used to provide airdata, navdata, NAV/COM settings, engine information <br />
to the GDUs. There is a<br />
generic interface (GenericInterfaceController) that uses the standard FG route<br />
manager, GPS, navigation data and NAV/COM settings, and engine data for a single<br />
piston engine.<br />
<br />
You need to load it as follows:<br />
<br />
<syntaxhighlight lang="nasal"><br />
var nasal_dir = getprop("/sim/fg-root") ~ "/Aircraft/Instruments-3d/FG1000/Nasal/";<br />
io.load_nasal(nasal_dir ~ 'Interfaces/GenericInterfaceController.nas', "fg1000");<br />
<br />
var interfaceController = fg1000.GenericInterfaceController.getOrCreateInstance();<br />
interfaceController.start();<br />
</syntaxhighlight><br />
<br />
You may want to create your own version depending on what properties you are<br />
using for the NAV/COM, and your engine configuration.<br />
<br />
Note that you should only start the interface after you've started the FG1000<br />
as they will publish information at start of day that the displays need.<br />
<br />
=== Create an EIS Display ===<br />
<br />
This is the Engine Information System and displays on the left side of the MFD.<br />
<br />
There is a generic EIS provided<br />
(see FG1000/Nasal/EIS, and FG1000/MFDPages/EIS.svg) that is intended to match<br />
a Cessna 172. If you need something different, you should create your own<br />
EIS class and SVG file.<br />
<br />
Note that you need to pass data to/from the engine using Emesary. See<br />
Interfaces/GenericEISPublisher.nas for a reference implementation.<br />
<br />
=== Load and start the FG1000 system ===<br />
<br />
See FG1000/Nasal/FG1000.nas for full details,<br />
including how to pass in the EIS. A simple FG1000 using the generic EIS, and<br />
displaying PFD on device-number 1 and an MFD on device-number 2 is as follows:<br />
<br />
<syntaxhighlight lang="nasal"><br />
var nasal_dir = getprop("/sim/fg-root") ~ "/Aircraft/Instruments-3d/FG1000/Nasal/";<br />
io.load_nasal(nasal_dir ~ 'FG1000.nas', "fg1000");<br />
<br />
# Create the FG1000<br />
var fg1000system = fg1000.FG1000.getOrCreateInstance();<br />
<br />
# Create a PFD as device 1, MFD as device 2<br />
fg1000system.addPFD(1);<br />
fg1000system.addMFD(2);<br />
<br />
# Display the devices<br />
fg1000system.display(1);<br />
fg1000system.display(2);<br />
<br />
fg1000system.show();<br />
<br />
# Display a GUI version of device 1 at 50% scale.<br />
#fg1000system.displayGUI(1, 0.5);<br />
</syntaxhighlight><br />
<br />
== Page Status ==<br />
<br />
This is the current status of the individual pages. Full progress bars indicate that they are functionally complete, though the iconography is not correct.<br />
<br />
{| class="wikitable sortable"<br />
|-<br />
! Page !! Reference !! Status !! Notes<br />
|-<br />
| {{FG1000 file|name=NavigationMap|label=Navigation Map}} || || {{progressbar|100|20}} || See Layers below<br />
|-<br />
| {{FG1000 file|name=TrafficMap|label=Traffic Map}} || || {{progressbar|100|20}} || Zoom controls unclear<br />
|-<br />
| {{FG1000 file|name=Stormscope|label=Storm Scope}} || || {{progressbar|0|20}} || <br />
|-<br />
| {{FG1000 file|name=WeatherDataLink|label=Weather Data Link}} || || {{progressbar|0|20}} || <br />
|-<br />
| {{FG1000 file|name=TAWSB|label=TAWS-B}}|| || {{progressbar|0|20}} || <br />
|-<br />
| {{FG1000 file|name=AirportInformation|label=Airport Information}} || || {{progressbar|100|20}} || Needs additional page of AOPA information, which we don't have<br />
|-<br />
| {{FG1000 file|name=IntersectionInfo|label=Intersection Information}} || || {{progressbar|100|20}} || <br />
|-<br />
| {{FG1000 file|name=NDBInfo|label=NDB Information}} || || {{progressbar|100|20}} || <br />
|-<br />
| {{FG1000 file|name=VORInfo|label=VOR Information}} || || {{progressbar|100|20}} || <br />
|-<br />
| User WPT Information || || {{progressbar|0|20}} || <br />
|-<br />
| Trip Planning || || {{progressbar|0|20}} || <br />
|-<br />
| Utility || || {{progressbar|0|20}} || <br />
|-<br />
| GPS Status || || {{progressbar|0|20}} || <br />
|-<br />
| XM Radio || || {{progressbar|0|20}} || <br />
|-<br />
| System Status || || {{progressbar|0|20}} || <br />
|-<br />
| {{FG1000 file|name=ActiveFlightPlanNarrow|label=Active Flight Plan}} || || {{progressbar|100|20}} || Viewing and editing of the active flight plan implemented. VNAV and the "wide view" not yet implemented<br />
|-<br />
| Flight Plan Catalog || || {{progressbar|0|20}} || <br />
|-<br />
| Stored Flight Plan || || {{progressbar|0|20}} || <br />
|-<br />
| {{FG1000 file|name=Checklist|label=Checklist}} || || {{progressbar|100|20}} || <br />
|-<br />
| {{FG1000 file|name=NearestAirports|label=Nearest Airports}} || || {{progressbar|100|20}} || <br />
|-<br />
| {{FG1000 file|name=NearestIntersections|label=Nearest Intersections}} || || {{progressbar|100|20}} || <br />
|-<br />
| {{FG1000 file|name=NearestNDB|label=Nearest NDB}} || || {{progressbar|100|20}} || <br />
|-<br />
| {{FG1000 file|name=NearestNDB|label=Nearest VOR}} || || {{progressbar|100|20}} || <br />
|-<br />
| Nearest User Waypoints || || {{progressbar|0|20}} || <br />
|-<br />
| Nearest Frequencies || || {{progressbar|0|20}} || <br />
|-<br />
| Nearest Airspaces || || {{progressbar|0|20}}|| <br />
|}<br />
<br />
This is the current status of the major functional elements<br />
<br />
{| class="wikitable"<br />
|-<br />
! Area !! Status !! Notes<br />
|-<br />
| Navigation - FMS || {{progressbar|100|20}} || <br />
|-<br />
| Softkeys || {{progressbar|100|20}} || <br />
|-<br />
| MENU key || {{progressbar|0|20}} || <br />
|-<br />
| NAV/COM || {{progressbar|90|20}} || Volume controls to be added<br />
|-<br />
| GPE Header || {{progressbar|0|20}} ||<br />
|}<br />
<br />
== Motivation ==<br />
{{Main article|Canvas_News#Moving_map.2FRNAV_discussion}}<br />
<br />
The enormous variety in current glass flight decks means we really need to think of a new way of defining glass cockpit layouts.<ref>{{cite web<br />
|url = https://sourceforge.net/p/flightgear/mailman/message/15602744/ <br />
|title = <nowiki> Re: [Flightgear-devel] Glass cockpit and external gauges. </nowiki> <br />
|author = <nowiki> Robin van Steenbergen </nowiki> <br />
|date = Oct 2nd, 2007 <br />
|added = Oct 2nd, 2007 <br />
|script_version = 0.40 <br />
}}</ref><br />
<br />
<br />
The airspace system is in the process of changing drastically [...] this isn't just a matter of throwing up a canvas showing some GPS waypoints and a magenta line. Modern navigators are astoundingly-complex devices — probably an order of magnitude more lines of code than FlightGear itself — and even their basic flight planning algorithms and databases (e.g. fly-by waypoints vs fly-over waypoints, open vs closed approach procedures, transitions into RNAV approaches, etc.) are far beyond the scope of anything we've tried, and we'd also need an up-to-date database far more complex than the ones we have now. Once you get to the extra features, like FIS-B weather or TIS-B traffic info over ADS-B, or TAWS (terrain alerting), we're probably in way over our heads trying to emulate even the simplest general-aviation IFR GPS.<br />
<br />
This may help folks understand what the G1000 is all about: http://static.garmincdn.com/pumac/190-00498-07_0A_Web.pdf <br />
Writing a G1000 isn't that hard. Writing a '''feature complete''' G1000 is a ton of work. <ref>{{cite web<br />
|url = https://sourceforge.net/p/flightgear/mailman/message/35925783/ <br />
|title = <nowiki> Re: [Flightgear-devel] RFD: FlightGear and the changing state of<br />
air navigation </nowiki> <br />
|author = <nowiki> geneb </nowiki> <br />
|date = Jul 3rd, 2017 <br />
|added = Jul 3rd, 2017 <br />
|script_version = 0.40 <br />
}}</ref><br />
<br />
<br />
Depending on how we deal with this challenge, the question is whether that means that the usefulness of FlightGear will also gradually taper off. <ref>{{cite web<br />
|url = https://sourceforge.net/p/flightgear/mailman/message/35924395/ <br />
|title = <nowiki> [Flightgear-devel] RFD: FlightGear and the changing state of air<br />
navigation </nowiki> <br />
|author = <nowiki> David Megginson </nowiki> <br />
|date = Jul 3rd, 2017 <br />
|added = Jul 3rd, 2017 <br />
|script_version = 0.40 <br />
}}</ref><br />
<br />
Instead of just making one-off tweaks like the consumer sims did, we (as a team) emulated entire systems like the vacuum, pitot-static, and electrical systems, so that failures would be realistic. In the RNAV age, we need to do the same thing; it's just that it's a bigger job. FlightGear will still be great for people who want to practice the mechanical parts of flying (e.g. crosswind wheel landings in a Cub), but will slip further and further behind for people who want to use it for real IFR practice.<ref>{{cite web<br />
|url = https://sourceforge.net/p/flightgear/mailman/message/35927088/ <br />
|title = <nowiki> Re: [Flightgear-devel] RFD: FlightGear and the changing state of<br />
air navigation </nowiki> <br />
|author = <nowiki> David Megginson </nowiki> <br />
|date = Jul 4th, 2017 <br />
|added = Jul 4th, 2017 <br />
|script_version = 0.40 <br />
}}</ref><br />
<br />
== Background ==<br />
{{Main article|Complex Canvas Avionics}}<br />
<br />
== Challenges ==<br />
=== Performance ===<br />
{{See also|Canvas_Development#Property_I.2FO_observations|Canvas_MapStructure#Performance}}<br />
Nasal as such is fast, and compared with the cost of rendering the terrain, rendering a canvas display is fast on the GPU (you can test by rendering but not updating a canvas display), and unless you're doing something very inefficient, calculating a display but not writing it to the property tree is fast (you can test this by disabling the write commands). It's the property I/O which you need to structure well, and then canvas will run fast. And of course the complexity of your underlying simulation costs - if you run a thermal model underneath to get real temperature reading, it costs more than inventing the numbers. But that has nothing to do with canvas. <ref>{{cite web<br />
|url = https://sourceforge.net/p/flightgear/mailman/message/35926343/ <br />
|title = <nowiki> Re: [Flightgear-devel] RFD: FlightGear and the changing state of<br />
air navigation </nowiki> <br />
|author = <nowiki> Thorsten Renk </nowiki> <br />
|date = Jul 4th, 2017 <br />
|added = Jul 4th, 2017 <br />
|script_version = 0.40 <br />
}}</ref><br />
<br />
<br />
it's a lot of work to code all these displays which someone has to do, but there's no reason to assume it'd be hopeless performance-wise.<ref>{{cite web<br />
|url = https://sourceforge.net/p/flightgear/mailman/message/35926412/ <br />
|title = <nowiki> Re: [Flightgear-devel] RFD: FlightGear and the changing state of<br />
air navigation </nowiki> <br />
|author = <nowiki> Thorsten Renk </nowiki> <br />
|date = Jul 4th, 2017 <br />
|added = Jul 4th, 2017 <br />
|script_version = 0.40 <br />
}}</ref><br />
<br />
we need to be realistic here: The G1000 is a fairly significant piece of computer hardware that we're going to emulate. It's not going to be "free" particularly for those on older hardware that's already struggling. However, hopefully we can offload a chunk of the logic (route management, autopilot/flight director) to the core, and do things like offline generation of terrain maps to minimize the impact.<ref>{{cite web<br />
|url = https://sourceforge.net/p/flightgear/mailman/message/35926745/ <br />
|title = <nowiki> Re: [Flightgear-devel] RFD: FlightGear and the changing state of<br />
air navigation </nowiki> <br />
|author = <nowiki> Stuart Buchanan </nowiki> <br />
|date = Jul 4th, 2017 <br />
|added = Jul 4th, 2017 <br />
|script_version = 0.40 <br />
}}</ref><br />
<br />
=== Route Manager ===<br />
that's exactly the kind of device James hopes the new code can support. He's read the G1000 pilot's manual, and *thinks* that nearly all the functions can be provided by the current GPS code It would be great if people could look over the current GPS features and indicate any pieces you think might be missing - additional commands, additional search features, extra data, or anything really. <ref>{{cite web<br />
|url = https://sourceforge.net/p/flightgear/mailman/message/23814733/ <br />
|title = <nowiki> Re: [Flightgear-devel] ZKV500 GPS instrument; (New?) GPS code bug </nowiki> <br />
|author = <nowiki> James Turner </nowiki> <br />
|date = Oct 22nd, 2009 <br />
|added = Oct 22nd, 2009 <br />
|script_version = 0.40 <br />
}}</ref><br />
<br />
=== tile servers ===<br />
Please keep in mind that most tile servers discourage bulk downloads. For the whole planet,oomlevel 8 is approx. 67k files, at zoomlevel 9 you have 265k, level 10 has a little over one million tiles. And one would probably want to go up to level 15 (roughly 1e9 files)<ref>{{cite web<br />
|url = https://sourceforge.net/p/flightgear/mailman/message/36057678/ <br />
|title = <nowiki> Re: [Flightgear-devel] Canvas MapLayer for OpenStreetMap, OpenAIP,<br />
VFR Sectionals </nowiki> <br />
|author = <nowiki> Torsten Dreyer </nowiki> <br />
|date = Sep 29th, 2017 <br />
|added = Sep 29th, 2017 <br />
|script_version = 0.40 <br />
}}</ref><br />
<br />
=== Offline mode ===<br />
would it be possible to provide an offline tool to pre-fetch a region, like TerraMaster, or terrasync.py? Call me old-fashioned or paranoid, but I don't want FG to go online and do stuff automatically, I prefer downloading what I need manually so that I know what gets onto my harddisk. Also - think of all the people with poor home internet which might have larger bandwidth only in a library elsewhere.<ref>{{cite web<br />
|url = https://sourceforge.net/p/flightgear/mailman/message/36057499/ <br />
|title = <nowiki> Re: [Flightgear-devel] Canvas MapLayer for OpenStreetMap, OpenAIP,<br />
VFR Sectionals </nowiki> <br />
|author = <nowiki> Thorsten Renk </nowiki> <br />
|date = Sep 29th, 2017 <br />
|added = Sep 29th, 2017 <br />
|script_version = 0.40 <br />
}}</ref><br />
<br />
that would certainly be possible - the code retrieving the data is pretty trivial and porting the Nasal code to python or some other script should be straightforward.<ref>{{cite web<br />
|url = https://sourceforge.net/p/flightgear/mailman/message/36057657/ <br />
|title = <nowiki> Re: [Flightgear-devel] Canvas MapLayer for OpenStreetMap, OpenAIP,<br />
VFR Sectionals </nowiki> <br />
|author = <nowiki> Stuart Buchanan </nowiki> <br />
|date = Sep 29th, 2017 <br />
|added = Sep 29th, 2017 <br />
|script_version = 0.40 <br />
}}</ref><br />
<br />
=== Navdata ===<br />
we need some better data sources, especially with direct routing replacing airways in many areas, and having airspace data would help the map displays, but the current API is specifically designed to support G430, G1000 and similar class devices. Adding RNAV approaches is eminently doable, see the the RNavController base class which the GPS/FMS layer uses to allow new waypoint / route segments to define how they are flown and drive CDIs <ref>{{cite web<br />
|url = https://sourceforge.net/p/flightgear/mailman/message/35927598/ <br />
|title = <nowiki> Re: [Flightgear-devel] RFD: FlightGear and the changing state of<br />
air navigation </nowiki> <br />
|author = <nowiki> James Turner </nowiki> <br />
|date = Jul 4th, 2017 <br />
|added = Jul 4th, 2017 <br />
|script_version = 0.40 <br />
}}</ref><br />
<br />
<br />
Getting the algorithms right, and keeping the data up to date every 7 weeks (we have only a tiny sliver of that data currently), is going to be much more of a challenge. I expect that it's probably an order of magnitude more complicated than our current flight dynamics (etc.), so we'd have to grow our contributor base, and find funding to pay at least Curt (and maybe a couple of others) full time to manage the project. Note that that's what has happened for other complex FOSS projects, like office suites and browsers, which generally end up working through a foundation, rather than our current relaxed circle-of-friends arrangement. The reason it's so much harder now is that the software *is* the product for GPS navigators, FMSs, etc. (unlike with older avionics, where the hardware was the main thing). That means that emulating even a simple unit like the GTN 650 or GNS 430W is almost difficult as building one, so we're trying to keep up with armies of full-time software developers at Garmin, Avidyne, etc.<ref>{{cite web<br />
|url = https://sourceforge.net/p/flightgear/mailman/message/35927243/ <br />
|title = <nowiki> Re: [Flightgear-devel] RFD: FlightGear and the changing state of<br />
air navigation </nowiki> <br />
|author = <nowiki> David Megginson </nowiki> <br />
|date = Jul 4th, 2017 <br />
|added = Jul 4th, 2017 <br />
|script_version = 0.40 <br />
}}</ref><br />
<br />
<br />
According to the Route Manager wiki page, we already have support for SID/STAR data provided from Navigraph, which is released on the AIRAC cycle, and costs a pretty small amount (9 EUR for a single download of FMS data, or 90 EUR per year) Given the relatively low cost, I don't think that we as an organiation want to get into trying to digitize data ourselves just to make it open-source or public domain. Particularly given the low cost of a download. We might want to digitize the STAR/SIDs for the default airport with each release so there are some approaches available for those who don't want to purchase the data.<ref>{{cite web<br />
|url = https://sourceforge.net/p/flightgear/mailman/message/35927426/ <br />
|title = <nowiki> Re: [Flightgear-devel] RFD: FlightGear and the changing state of<br />
air navigation </nowiki> <br />
|author = <nowiki> Stuart Buchanan </nowiki> <br />
|date = Jul 4th, 2017 <br />
|added = Jul 4th, 2017 <br />
|script_version = 0.40 <br />
}}</ref><br />
<br />
everyone agrees we would like to add airspace data - what we’re missing is a suitable data source with the correct license. Torsten found a raster-based source but for wider use in the sim we really need vector data, so we can render it ourselves directly. <ref>{{cite web |url = https://sourceforge.net/p/flightgear/mailman/message/36178857/ |title = <nowiki> Re: [Flightgear-devel] [flightgear/simgear] Nasal regex patch </nowiki> |author = <nowiki> James Turner </nowiki> |date = Jan 5th, 2018 |added = Jan 5th, 2018 |script_version = 0.36 }}</ref><br />
<br />
For airspace data we could use [https://openflightmaps.org/ https://openflightmaps.org/] . It provides community created navigation data for many countries in (currently only) Europe with a free license.<ref>{{cite web<br />
|url = https://forum.flightgear.org/viewtopic.php?p=326105#p326105 <br />
|title = <nowiki> Re: Canvas G1000 </nowiki> <br />
|author = <nowiki> TheTom </nowiki> <br />
|date = Jan 9th, 2018 <br />
|added = Jan 9th, 2018 <br />
|script_version = 0.36 <br />
}}</ref><br />
<br />
we definitely want vector data. Stuart is hoping that we might convince the source of the raster data we're using at present to provide it as raw vector data, but we haven't had any luck so far.<ref>{{cite web<br />
|url = https://forum.flightgear.org/viewtopic.php?p=326201&sid=137f64d32b770e50a3c4061be42ce28a#p326201 <br />
|title = <nowiki> Re: Canvas G1000 </nowiki> <br />
|author = <nowiki> stuart </nowiki> <br />
|date = Jan 10th, 2018 <br />
|added = Jan 10th, 2018 <br />
|script_version = 0.36 <br />
}}</ref><br />
<br />
== Airport Data (US - only )==<br />
At least for the US, all required information is available in the form of regularly updated UDFF files:<br />
* https://www.ngs.noaa.gov/AERO/aero.html<br />
* https://www.ngs.noaa.gov/AERO/uddf/WESTERN-PACIFIC/CALIFORNIA/SFO__03B.F77<br />
* https://www.ngs.noaa.gov/AERO/annof_7.pdf<br />
<br />
It would seem relatively straightforward to provide a scripted parser to create the corresponding charts procedurally.<br />
As a matter of fact, this could even be done in a background thread or using a separate Python script, i.e. if we wanted to ship pre-created imagery as part of fgdata.<br />
<br />
However, if the built-in Canvas system is extended to provide these charts, [[Phi]] could also be entirely self-contained by rendering the same airport charts without having to depend on external data sources.<br />
<br />
<br />
== Layers ==<br />
<br />
{{See also|Canvas_Sandbox#CanvasShapefile}}<br />
<br />
Following is the list of layers displayed by the G1000 system (see page 153 of the 190-00498-07 Rev. A), and mapping to the equivalent MapStructure Layer.<br />
Many of these would also be good to have for other avionics/GUI dialogs, including the NavDisplay framework, which is currently re-implementing this functionality separately, i.e. not yet using MapStructure.<br />
<br />
Following is the list of layers displayed by the G1000 system, based on the Garmin G1000 Integrated Flight Deck Pilot's Guide for the Cessna Nav III [http://static.garmincdn.com/pumac/190-00498-07_0A_Web.pdf Garmin Site] [https://web.archive.org/web/20170708032442/http://static.garmincdn.com/pumac/190-00498-07_0A_Web.pdf Wayback machine], page 153, and the mapping to the equivalent MapStructure Layer.<br />
<br />
Richard mentioned that if he were to implement approach plates in the EFB he'd probably use raster images provided via http and provide an http service within FG to do this, or to allow the EFB to use any other external web service. Other content for the EFB could be also provided as SVG via http.<ref>{{cite web |url = https://forum.flightgear.org/viewtopic.php?p=259194#p259194 |title = <nowiki> Re: </nowiki> |author = <nowiki> Richard </nowiki> |date = Sep 29th, 2015 |added = Sep 29th, 2015 |script_version = 0.36 }}</ref><br />
<br />
{| class="wikitable"<br />
|-<br />
! Layer !! [[Canvas MapStructure Layers|MapStructure Layer]] !! Status !! Page || Notes<br />
|-<br />
| Flight Plan Route Lines || {{MapStructure_File|name=RTE|type=lcontroller}} || Requires styling || {{PDF Link|page=190}} ||<br />
|-<br />
| Flight Plan Route Waypoints || {{MapStructure_File|name=WPT|type=lcontroller}} || Requires styling || {{PDF Link|page=190}} || <br />
|-<br />
| Rivers/Lakes || {{MapStructure_File|name=VFRChart|type=lcontroller}} || || {{PDF Link|page=148}} || Currently using downloaded raster from web. Perhaps generate similarly to Atlas<ref>{{cite web<br />
|url = https://forum.flightgear.org/viewtopic.php?p=203495#p203495 <br />
|title = <nowiki> Re: Atlas still in use ? </nowiki> <br />
|author = <nowiki> Torsten </nowiki> <br />
|date = Mar 17th, 2014 <br />
|added = Mar 17th, 2014 <br />
|script_version = 0.40 <br />
}}</ref>, or could be vector data from scenery. {{AtlasVsCanvasCameras}}<br />
|-<br />
| Topography Data || {{MapStructure_File|name=VFRChart|type=lcontroller}} || Synthetic || {{PDF Link|page=145}} || Height-map at chart-resolution. Perhaps generate similarly to Atlas? {{AtlasVsCanvasCameras}}<br />
|-<br />
| International Borders || || || {{PDF Link|page=148}} || Vector data from scenery?<br />
|-<br />
| Track Vector || || || {{PDF Link|page=156}} || Forward looking display of track. Look-ahead time selectable. <br />
|-<br />
| Navigation Range Ring || || || {{PDF Link|page=159}} || Straightforward extension of {{MapStructure_File|name=APS|type=lcontroller}}.<br />
|-<br />
| Fuel Range Ring || || || 159 || Straightforward extension of {{MapStructure_File|name=APS|type=lcontroller}}.<br />
|-<br />
| Terrain Data || || || 364 || Should be straightforward, with exception of obstacles. [[Spoken GCA|Profile view]] also required.<br />
|-<br />
| Traffic || {{MapStructure_File|name=TFC|type=lcontroller}} || || 394,423 || Various options, each with different iconography and data displayed. <br />
|-<br />
| Airways || {{MapStructure_File|name=VFRChart|type=lcontroller}} || || 154 || Needs to be replaced with vector data<br />
|-<br />
| NEXRAD || || || 282 || Heaps of weather data with complex symbology.<br />
|-<br />
| XM Lightning Data || {{MapStructure_File|name=WXR|type=lcontroller}} || Change to symbol for lightning? || 294 || Optional <br />
|-<br />
| Airports || {{MapStructure_File|name=APT|type=lcontroller}}, {{MapStructure_File|name=RWY|type=lcontroller}} || Require re-style based on size || 149, 163 ||<br />
|-<br />
| Runway Labels || {{MapStructure_File|name=RWY|type=lcontroller}} || || 148 || Needs to be added to {{MapStructure_File|name=RWY|type=symbol}}. Should be straightforward<br />
|-<br />
| Restricted || {{MapStructure_File|name=OpenAIP|type=lcontroller}} || || 182 || {{NeedVectorData}}<br />
|-<br />
| MOA (Military) || {{MapStructure_File|name=OpenAIP|type=lcontroller}} || || 182 || {{NeedVectorData}}<br />
|-<br />
| User Waypoints || || || <br />
|-<br />
| Latitude/Longitude Grid || {{MapStructure_File|name=GRID|type=lcontroller}} || || <br />
|-<br />
| NAVAIDs || {{MapStructure_File|name=APT|type=lcontroller}}, {{MapStructure_File|name=VOR|type=lcontroller}}, {{MapStructure_File|name=FIX|type=lcontroller}}, {{MapStructure_File|name=NDB|type=lcontroller}} || APT, requires styling || 162 || <br />
|-<br />
| Class B Airspaces/TMA || {{MapStructure_File|name=OpenAIP|type=lcontroller}} || || 182 || {{NeedVectorData}}<br />
|-<br />
| Class C Airspaces/TCA || {{MapStructure_File|name=OpenAIP|type=lcontroller}} || || 182 || {{NeedVectorData}}<br />
|-<br />
| Class D Airspaces || {{MapStructure_File|name=OpenAIP|type=lcontroller}} || || 182 || {{NeedVectorData}}<br />
|-<br />
| Other Airspaces/ADIZ || {{MapStructure_File|name=OpenAIP|type=lcontroller}} || || 182 || {{NeedVectorData}}<br />
|-<br />
| TFRs || || || 310 || <br />
|-<br />
| Obstacles || {{MapStructure_File|name=OpenAIP|type=lcontroller}} || || 182 || {{NeedVectorData}}<br />
|-<br />
| Land/Country Text || || || 148 || Currently using raster data from web. Replace with {{MapStructure_File|name=POI|type=lcontroller}}? <br />
|-<br />
| Cities || {{MapStructure_File|name=VFRChart|type=lcontroller}} || || 148 || Currently using raster data from web. Perhaps generate similarly to Atlas, or could be vector data from scenery. {{AtlasVsCanvasCameras}}<br />
|-<br />
| Roads || {{MapStructure_File|name=VFRChart|type=lcontroller}} || || 148 || Currently using raster data from web. Requires vector data from scenery<br />
|-<br />
| Railroads || {{MapStructure_File|name=VFRChart|type=lcontroller}} || || 148 || Currently using raster data from web. Requires vector data from scenery<br />
|-<br />
| State/Province Boundaries || {{MapStructure_File|name=VFRChart|type=lcontroller}} || || 148 || Currently using raster data from web. Requires vector data from scenery<br />
|-<br />
| River/Lake Names || {{MapStructure_File|name=VFRChart|type=lcontroller}} || || 148 || Currently using raster data from web. Replace with {{MapStructure_File|name=POI|type=lcontroller}}?<br />
|-<br />
| Selected Altitude Intercept Arc || || || 161 || Simple extention to APS<br />
|-<br />
| SafeTaxi (Optional) || {{MapStructure_File|name=RWY|type=lcontroller}}, {{MapStructure_File|name=TAXI|type=lcontroller}} || || 493 || We don't currently have the data to display taxiway identifier or holding points<br />
|-<br />
| ChartView (Optional) || || || 503 || [[Canvas_Sandbox#CanvasPDF|Rendering of PDFs.]] Might be possible to integrate with NaviGraph chart data?<br />
|-<br />
| FliteChart (Optional) || || || 521 || [[Canvas_Sandbox#CanvasPDF|Rendering of PDFs.]] Might be possible to integrate with NaviGraph chart data?<br />
|}<br />
<br />
== Existing work ==<br />
{{See also|Complex Canvas Avionics}}<br />
<br />
=== Avionics / Cockpits ===<br />
* [[User:Zakharov/zkv1000 installation guide|zkv1000]] see [https://forum.flightgear.org/viewtopic.php?f=14&t=32056]<br />
* [[Extra500]] / Avidyne Entegra R9000<br />
<br />
=== Nasal / Canvas ===<br />
* [[Canvas MFD Framework]]<br />
* MapStructure<br />
* MapStructure Layers<br />
* [[Howto:Creating a Canvas GUI Widget]]<br />
* [[Emesary]]<br />
<br />
=== C++ ===<br />
* [[Atlas]] map creation<br />
* [[Howto:Canvas View Camera Element|Synthetic Vision]] element for rendering viewmgr views to a Canvas <br />
* [[Canvas_Sandbox#CanvasPDF|Canvas PDF]] element - for rendering PDF files (think EFB functionality)<br />
<br />
== Possible Work ==<br />
<br />
=== Architectural TODO List ===<br />
This is a short list of architectural improvements I've noted during development that need to be revisited:<br />
* Use NavMap for MFD Navigation Map, DirectTo, Nearest, Information pages.<br />
* Separate out the HSI, tapes from the PFD and make them generic MFD UI Elements<br />
* Improve the performance of the maps, perhaps using a cache for queries, definitely by more aggressive clipping of the SlippyMap layers based on map size.<br />
<br />
The layers table shown above mentions a few limitations and ideas, such as:<br />
=== Nasal/Canvas ===<br />
* <image> tag support for svg.nas (patch: [http://wiki.flightgear.org/Howto:Extend_the_Canvas_SVG_module])<br />
* MapStructure: [[MapStructure_Optimizations#Allocating_selectable_ranges_into_groups|Allocating selectable ranges into Canvas groups]]<br />
<br />
=== C++ ===<br />
* fix up [[Canvas_MapStructure#Performance|projection issues]], and adopt Gijs' [[Canvas_Development#Projections|projection handling code]] for the hard-coded PUI [[Map]], to get rid of the standard Sanson-Flamsteed projection <br />
* adding a profile view, probably in conjunction with terrain sampling<br />
* using atlas code to generate heightmaps/topography<br />
* adding ESRI shapefile support to the Canvas system<br />
* adding PDF rendering support the Canvas system<br />
<br />
== Design ==<br />
<br />
The broad structure of the Nasal files in Aircaft/Instruments-3d/FG1000/Nasal is as follows:<br />
<br />
* MFD.nas - top level MFD device, loads the other Nasal files (likely to be moved elsewhere later) and pages.<br />
* PageGroupControllers.nas - controller for the Page Group display in the bottom right of the MFD, controlled by the FMS knob, and which allows selection between different page groups and individual pages.<br />
* [PageName]/[PageName].nas - MFD page, inheriting from the MFDPage.nas. Creates any required MapStructure and hierarchy of softkeys.<br />
* [PageName]/[PageName]Controller.nas - Controller for the MFD page and the MapStructure layers, inheriting from MFDPageController.nas<br />
* [PageName]/[PageName]Style.nas - Style controls for the MapStructure layers for the given Page.<br />
* [PageName]/[PageName]Options.nas - Options for the MapStructure layers for the given Page.<br />
<br />
Key design notes:<br />
* Most of the underlying Canvas [[MapStructure]] layers are now written (though they require styling, and/or would benefit from replacement with vector data). <br />
* [[Emesary]] IPC framework is used to link between the MFD and underlying simulation state. This should make it easy to run the MFD on a separate FG instance, and provides a good demarkation between the individual aircraft systems and the FG1000 itself. <br />
* Various underlying UI classes are used to handle highlighting, selection and scrolling of fields. See [[Canvas MFD Framework]] for details of the elements now supported.<br />
<br />
== Resources ==<br />
<br />
{{#ev:youtube|I0y6p0ct1m0}}<br />
<br />
== Related ==<br />
=== Commits ===<br />
This section is intended to help keep track of related fgdata commits, so that if/when the project should stall, people can more easily look up related changes.<br />
<br />
<br />
* {{fgdata commit|da252c8a18fe2ce88066c051f6df588639377792|text=Initial Direct To page}}(01/2018)<br />
* {{fgdata commit|0c4544c1e1788f3396330c86016b66df8643fd3b|text=Add Config Store and MFD Header display.}}(01/2018)<br />
* {{fgdata commit|9bd10f8273a6e64b12b9a034ca4952d87090f921|text=SVG MFD UI from miChat}}(01/2018)<br />
* {{fgdata commit|f6f5efe9f442ff058d9d425d85337139b2a9bf1f|text=Use Emesary interface rather than airportinfo()}}(01/2018)<br />
* {{fgdata commit|d306e7ba100840f5c3909123a383b19f7e7d7540|text=Set standby COM frequency from Airport pages}}(01/2018)<br />
* {{fgdata commit|cbb281759cd3f2b830bffdd12ba72d456996a13a|text=NAV/COM Radio support}}(01/2018)<br />
* {{fgdata commit|a25c66850a93f0ae7a6f7ad8769680c1fba99887|text=Add full set of hardkeys to fg1000 PUI dialog.}}(01/2018)<br />
* {{fgdata commit|ab8774a3e0aa3909ad284a65194f5d80dc097c6e|text=extend MFDPageController to handle Emesary register}}(01/2018)<br />
* {{fgdata commit|73424c1791242e053efcdac37a7dd3b66226387b|text=Update NAV/COMM frequencies from properties}}(01/2018)<br />
* {{fgdata commit|ad77dc2f9cd2a1e1ebd5efd4226cbfbf3a522008|text=Modify FG1000 EIS to use Emesary}}(01/2018)<br />
* {{fgdata commit|9eb91171b4689b29910db06757bc47767ff59d2c|text=FG1000 Nearest Airports page}}(01/2018)<br />
* {{fgdata commit|475fd505859b7841e29de725d4c1c39db7ad4ee5|text=PFD UI Elements and NearestAirports page}} (12/2017)<br />
* {{fgdata commit|d0203549e833b32b719697b3a2c2a63e16fcef16|text=Add AirportInfo and template pages for FG1000}} (12/2017)<br />
* {{fgdata commit|3d31775ff36bf3aa08a929992b70f32f2a525509|text=Initial commit of FG1000 MFD}} (11/2017)<br />
<br />
MapStructure related:<br />
<br />
* {{fgdata commit|4bd57492f454a05f725e6fe5a80dc246cb5e5e0f|text=GRID layer}} (10/2017)<br />
* {{fgdata commit|d84c527ca747dd6bbd9634507f0664ff3631bdef|text=RWY, TAXI, TWR, PARKING}} (10/2017)<br />
* {{fgdata commit|e38ec03c609b882664d0496932709aa623e486cb|text=STAMEN}} (10/2017)<br />
* {{fgdata commit|2fbc1dc491da867e0fd4f8fc810c5cddd80ced1f|text=VFRChart}} (09/2017)<br />
* {{fgdata commit|85b7665c19ebaae02d746fef53f25f8d8974eb13|text=OSM and OpenAIP}} (09/2017)<br />
<br />
=== References ===<br />
{{Appendix}}<br />
<br />
[[Category:Canvas]]</div>Clm76https://wiki.flightgear.org/w/index.php?title=FG1000&diff=116246FG10002018-09-29T16:16:37Z<p>Clm76: /* Add the GDU to the cockpit */</p>
<hr />
<div><br />
[[File:Mirrored MFD.png|thumb|FG1000 MFD being displayed (incorrectly!) in a DA-40, and mirrored to a GUI window at 50% scale (02/2018)]]<br />
[[File:FG1000 SVG UI.jpg|thumb|Stuart pushed an SVG UI for the FG1000, replacing the PUI version. (01/2018)]]<br />
<br />
{{Infobox subsystem<br />
|name = FG1000<br />
|started = 07/2017 <br />
|description = G1000-based MFD emulation<br />
|status = Under active development as of 07/2017<br />
|developers = {{Usr|Stuart}}, Richard (via [[Emesary]]), Michat (UI graphics), www2 (3D artwork) <ref>https://forum.flightgear.org/viewtopic.php?f=71&t=32764&start=60#p327229</ref><br />
|changelog = https://sourceforge.net/p/flightgear/fgdata/ci/next/log/?path=/Aircraft/Instruments-3d/FG1000<br />
|folders = https://sourceforge.net/p/flightgear/fgdata/ci/next/tree/Aircraft/Instruments-3d/FG1000/<br />
}}<br />
<br />
<br />
== Current Status ==<br />
<br />
06/04/2018:<br />
* PFD is largely complete. Transponder, NRST, ALT units and alternative units still to implement.<br />
* MFD is functional, and now includes display and editing of the current flightplan, along with moving map, engine information.<br />
* MFD and PFD can be displayed as a GUI window under Debug menu or added to an aircraft with the GDU-1045 model as part of a 3D cockpit. <br />
<br />
There's still a huge number of pages to write, and the more complex pages around route planning will likely be particularly challenging, but it should be far faster now these blocks are in place. . If anyone is interested in creating a specific page, please also get in touch with Stuart. The various ''Nearest... and ...Information'' pages should be quite easy to do based on the pages that have been written already. See the Design Notes for details.<br />
<br />
Next steps:<br />
* Writing the remaining (large) number of pages<br />
* Styling the pages - making the iconography match Garmin exactly.<br />
<br />
=== Gallery ===<br />
<gallery mode=packed widths=230px heights=230px><br />
PFD 20180406.png|FG1000 PFD showing inset map, current wind data, HSI with GPS bearing, active flightplan list<br />
MFD 20180406.png|FG1000 MFD with Cessna 182T Engine Information System (EIS), and Active Flightplan<br />
FG1000_Checklist_MFD_page.png|FG1000 MFD with Checklist page displayed<br />
</gallery><br />
<br />
== A Cheat's Guide to Using the FG1000 ==<br />
<br />
For those without the time or interest to read the G1000 User Guide, here's a very quick run-down on navigating through the MFD:<br />
<br />
General:<br />
* Click on the buttons, though some are not implemented yet.<br />
* Use the mouse wheel to scroll the knobs (NAV, HDG, ALT, COM, CRS/BARO, RANGE, FMS). For knobs with both and inner and an outer (NAV, COM, CRS/BARO, FMS), scrolling when pressing the Shift key changes the outer knob.<br />
* Use the outer FMS knob (shift-mouse wheel on the FMS knob on the bottom right) to navigate through the page groups.<br />
* Use the inner FMS knob (mouse wheel on the FMS knob on the bottom right) to navigate through the pages within the group. The currently selected page is shown in blue. If you stop moving the cursor, the page will be loaded in 0.5s.<br />
* Within a page, click on the FMS knob to activate the cursor (CRSR). You you should see some element highlighted on the page, typically flashing. You can navigate around the page using the outer and inner FMS knobs. The Outer FMS knob (shift-mouse wheel) typical moves the cursor between elements. The Inner FMS knob typically changes the selected item.<br />
* Use the RANGE knob to zoom map views in/out.<br />
<br />
Implemented function:<br />
<br />
PFD:<br />
* Artificial horizon, compass rose, altimeter and airspeed indicator<br />
* HSI that can display NAV1, NAV2, GPS deviation (press CDI)<br />
* Wind information (press PFD->WIND then select one of the options for display)<br />
* Bearings to NAV1, NAV2, GPS (press PFD then BRG1/BRG2 to cycle through the options)<br />
* Inset Map (Press INSET softkey)<br />
* Active Flight Plan (press FPL when there is an active flightplan to display)<br />
* DirectTo GPS (press DTO)<br />
<br />
MFD:<br />
* There is a two channel NAV/COM with an active and standby frequency and automatic ID of NAV frequencies at the top of the UI. They all integrate with the standard properties, so should work automatically with most aircraft.<br />
* If you have a frequency highlighted in any of the pages (e.g. WPT - AIRPORT INFORMATION) press the ENT key to load it into the standby NAV/COM frequency as appropriate.<br />
* To set up a GPS Direct To route:<br />
** Press the DTO button (D with an arrow through it on the right side of the panel, below the word "PAN"). This will bring up a Direct To window, allowing you to enter the ID of an airport, Fix etc. to navigate to.<br />
** You can enter the ID in one of two ways:<br />
*** Scroll the FMS knob backwards to bring up a sub-menu of waypoints categories (FPL, NRST, RECENT, USER, AIRWAY). Use the inner FMS knob to scroll between the different categories, and the outer FMS knob to select a specific item. <br />
*** Scroll the FMS knob forwards to enter an ID manually using the FMS knob. Use the outer FMS knob to move to the next poisition in the ID. <br />
** Once you've got an ID, press ENT which will load details into the window and highlight the ACTIVATE button.<br />
** Press ENT once more to load the Direct-to into the GPS and activate it.<br />
* To view airport information, select the WPT - AIRPORT INFORMATION page. Use the outer FMS knob to move between the AIRPORT, RUNWAYS and FREQUENCY boxes, and the inner FMS to edit the airport ID, scroll through available runways, or highlight a frequency.<br />
* To edit the current flightplan, press the FPL page, then press the CRSR and enter waypoints for DTO above.<br />
<br />
== Aircraft Installation ==<br />
<br />
Adding the FG1000 to an aircraft is intended to be fairly straightforward.<br />
<br />
=== Add the GDU to the cockpit ===<br />
<br />
Place one or more of the display (GDU) units in your model. The XML files<br />
are in GDU104X directory and are named <model>.<device-number>.xml, e.g.<br />
<br />
GDU-1045.1.xml GDU-1045.2.xml GDU-1045.3.xml GDU-1045.4.xml<br />
<br />
The <device-number> is referenced later to identify which displays to used<br />
for each PFD, MFD etc. You must only used one of each <device-number> value,<br />
though you can mix and match the GDU models.<br />
<br />
The different GDU models are as follows:<br />
<br />
* GDU-1040 - No autopilot controls<br />
* GDU-1044B - autopilot controls without VNAV<br />
* GDU-1045 - autopilot controls with VNAV<br />
<br />
=== Load the Interfaces to provide data ===<br />
<br />
This is used to provide airdata, navdata, NAV/COM settings, engine information <br />
to the GDUs. There is a<br />
generic interface (GenericInterfaceController) that uses the standard FG route<br />
manager, GPS, navigation data and NAV/COM settings, and engine data for a single<br />
piston engine.<br />
<br />
You need to load it as follows:<br />
<br />
<syntaxhighlight lang="nasal"><br />
var nasal_dir = getprop("/sim/fg-root") ~ "/Aircraft/Instruments-3d/FG1000/Nasal/";<br />
io.load_nasal(nasal_dir ~ 'Interfaces/GenericInterfaceController.nas', "fg1000");<br />
<br />
var interfaceController = fg1000.GenericInterfaceController.getOrCreateInstance();<br />
interfaceController.start();<br />
</syntaxhighlight><br />
<br />
You may want to create your own version depending on what properties you are<br />
using for the NAV/COM, and your engine configuration.<br />
<br />
Note that you should only start the interface after you've started the FG1000<br />
as they will publish information at start of day that the displays need.<br />
<br />
=== Create an EIS Display ===<br />
<br />
This is the Engine Information System and displays on the left side of the MFD.<br />
<br />
There is a generic EIS provided<br />
(see FG1000/Nasal/EIS, and FG1000/MFDPages/EIS.svg) that is intended to match<br />
a Cessna 172. If you need something different, you should create your own<br />
EIS class and SVG file.<br />
<br />
Note that you need to pass data to/from the engine using Emesary. See<br />
Interfaces/GenericEISPublisher.nas for a reference implementation.<br />
<br />
=== Load and start the FG1000 system ===<br />
<br />
See FG1000/Nasal/FG1000.nas for full details,<br />
including how to pass in the EIS. A simple FG1000 using the generic EIS, and<br />
displaying PFD on device-number 1 and an MFD on device-number 2 is as follows:<br />
<br />
<syntaxhighlight lang="nasal"><br />
var nasal_dir = getprop("/sim/fg-root") ~ "/Aircraft/Instruments-3d/FG1000/Nasal/";<br />
io.load_nasal(nasal_dir ~ 'FG1000.nas', "fg1000");<br />
<br />
# Create the FG1000<br />
var fg1000system = fg1000.FG1000.getOrCreateInstance();<br />
<br />
# Create a PFD as device 1, MFD as device 2<br />
fg1000system.addPFD(1);<br />
fg1000system.addMFD(2);<br />
<br />
# Display the devices<br />
fg1000system.display(1);<br />
fg1000system.display(2);<br />
<br />
# Display a GUI version of device 1 at 50% scale.<br />
#fg1000system.displayGUI(1, 0.5);<br />
</syntaxhighlight><br />
<br />
== Page Status ==<br />
<br />
This is the current status of the individual pages. Full progress bars indicate that they are functionally complete, though the iconography is not correct.<br />
<br />
{| class="wikitable sortable"<br />
|-<br />
! Page !! Reference !! Status !! Notes<br />
|-<br />
| {{FG1000 file|name=NavigationMap|label=Navigation Map}} || || {{progressbar|100|20}} || See Layers below<br />
|-<br />
| {{FG1000 file|name=TrafficMap|label=Traffic Map}} || || {{progressbar|100|20}} || Zoom controls unclear<br />
|-<br />
| {{FG1000 file|name=Stormscope|label=Storm Scope}} || || {{progressbar|0|20}} || <br />
|-<br />
| {{FG1000 file|name=WeatherDataLink|label=Weather Data Link}} || || {{progressbar|0|20}} || <br />
|-<br />
| {{FG1000 file|name=TAWSB|label=TAWS-B}}|| || {{progressbar|0|20}} || <br />
|-<br />
| {{FG1000 file|name=AirportInformation|label=Airport Information}} || || {{progressbar|100|20}} || Needs additional page of AOPA information, which we don't have<br />
|-<br />
| {{FG1000 file|name=IntersectionInfo|label=Intersection Information}} || || {{progressbar|100|20}} || <br />
|-<br />
| {{FG1000 file|name=NDBInfo|label=NDB Information}} || || {{progressbar|100|20}} || <br />
|-<br />
| {{FG1000 file|name=VORInfo|label=VOR Information}} || || {{progressbar|100|20}} || <br />
|-<br />
| User WPT Information || || {{progressbar|0|20}} || <br />
|-<br />
| Trip Planning || || {{progressbar|0|20}} || <br />
|-<br />
| Utility || || {{progressbar|0|20}} || <br />
|-<br />
| GPS Status || || {{progressbar|0|20}} || <br />
|-<br />
| XM Radio || || {{progressbar|0|20}} || <br />
|-<br />
| System Status || || {{progressbar|0|20}} || <br />
|-<br />
| {{FG1000 file|name=ActiveFlightPlanNarrow|label=Active Flight Plan}} || || {{progressbar|100|20}} || Viewing and editing of the active flight plan implemented. VNAV and the "wide view" not yet implemented<br />
|-<br />
| Flight Plan Catalog || || {{progressbar|0|20}} || <br />
|-<br />
| Stored Flight Plan || || {{progressbar|0|20}} || <br />
|-<br />
| {{FG1000 file|name=Checklist|label=Checklist}} || || {{progressbar|100|20}} || <br />
|-<br />
| {{FG1000 file|name=NearestAirports|label=Nearest Airports}} || || {{progressbar|100|20}} || <br />
|-<br />
| {{FG1000 file|name=NearestIntersections|label=Nearest Intersections}} || || {{progressbar|100|20}} || <br />
|-<br />
| {{FG1000 file|name=NearestNDB|label=Nearest NDB}} || || {{progressbar|100|20}} || <br />
|-<br />
| {{FG1000 file|name=NearestNDB|label=Nearest VOR}} || || {{progressbar|100|20}} || <br />
|-<br />
| Nearest User Waypoints || || {{progressbar|0|20}} || <br />
|-<br />
| Nearest Frequencies || || {{progressbar|0|20}} || <br />
|-<br />
| Nearest Airspaces || || {{progressbar|0|20}}|| <br />
|}<br />
<br />
This is the current status of the major functional elements<br />
<br />
{| class="wikitable"<br />
|-<br />
! Area !! Status !! Notes<br />
|-<br />
| Navigation - FMS || {{progressbar|100|20}} || <br />
|-<br />
| Softkeys || {{progressbar|100|20}} || <br />
|-<br />
| MENU key || {{progressbar|0|20}} || <br />
|-<br />
| NAV/COM || {{progressbar|90|20}} || Volume controls to be added<br />
|-<br />
| GPE Header || {{progressbar|0|20}} ||<br />
|}<br />
<br />
== Motivation ==<br />
{{Main article|Canvas_News#Moving_map.2FRNAV_discussion}}<br />
<br />
The enormous variety in current glass flight decks means we really need to think of a new way of defining glass cockpit layouts.<ref>{{cite web<br />
|url = https://sourceforge.net/p/flightgear/mailman/message/15602744/ <br />
|title = <nowiki> Re: [Flightgear-devel] Glass cockpit and external gauges. </nowiki> <br />
|author = <nowiki> Robin van Steenbergen </nowiki> <br />
|date = Oct 2nd, 2007 <br />
|added = Oct 2nd, 2007 <br />
|script_version = 0.40 <br />
}}</ref><br />
<br />
<br />
The airspace system is in the process of changing drastically [...] this isn't just a matter of throwing up a canvas showing some GPS waypoints and a magenta line. Modern navigators are astoundingly-complex devices — probably an order of magnitude more lines of code than FlightGear itself — and even their basic flight planning algorithms and databases (e.g. fly-by waypoints vs fly-over waypoints, open vs closed approach procedures, transitions into RNAV approaches, etc.) are far beyond the scope of anything we've tried, and we'd also need an up-to-date database far more complex than the ones we have now. Once you get to the extra features, like FIS-B weather or TIS-B traffic info over ADS-B, or TAWS (terrain alerting), we're probably in way over our heads trying to emulate even the simplest general-aviation IFR GPS.<br />
<br />
This may help folks understand what the G1000 is all about: http://static.garmincdn.com/pumac/190-00498-07_0A_Web.pdf <br />
Writing a G1000 isn't that hard. Writing a '''feature complete''' G1000 is a ton of work. <ref>{{cite web<br />
|url = https://sourceforge.net/p/flightgear/mailman/message/35925783/ <br />
|title = <nowiki> Re: [Flightgear-devel] RFD: FlightGear and the changing state of<br />
air navigation </nowiki> <br />
|author = <nowiki> geneb </nowiki> <br />
|date = Jul 3rd, 2017 <br />
|added = Jul 3rd, 2017 <br />
|script_version = 0.40 <br />
}}</ref><br />
<br />
<br />
Depending on how we deal with this challenge, the question is whether that means that the usefulness of FlightGear will also gradually taper off. <ref>{{cite web<br />
|url = https://sourceforge.net/p/flightgear/mailman/message/35924395/ <br />
|title = <nowiki> [Flightgear-devel] RFD: FlightGear and the changing state of air<br />
navigation </nowiki> <br />
|author = <nowiki> David Megginson </nowiki> <br />
|date = Jul 3rd, 2017 <br />
|added = Jul 3rd, 2017 <br />
|script_version = 0.40 <br />
}}</ref><br />
<br />
Instead of just making one-off tweaks like the consumer sims did, we (as a team) emulated entire systems like the vacuum, pitot-static, and electrical systems, so that failures would be realistic. In the RNAV age, we need to do the same thing; it's just that it's a bigger job. FlightGear will still be great for people who want to practice the mechanical parts of flying (e.g. crosswind wheel landings in a Cub), but will slip further and further behind for people who want to use it for real IFR practice.<ref>{{cite web<br />
|url = https://sourceforge.net/p/flightgear/mailman/message/35927088/ <br />
|title = <nowiki> Re: [Flightgear-devel] RFD: FlightGear and the changing state of<br />
air navigation </nowiki> <br />
|author = <nowiki> David Megginson </nowiki> <br />
|date = Jul 4th, 2017 <br />
|added = Jul 4th, 2017 <br />
|script_version = 0.40 <br />
}}</ref><br />
<br />
== Background ==<br />
{{Main article|Complex Canvas Avionics}}<br />
<br />
== Challenges ==<br />
=== Performance ===<br />
{{See also|Canvas_Development#Property_I.2FO_observations|Canvas_MapStructure#Performance}}<br />
Nasal as such is fast, and compared with the cost of rendering the terrain, rendering a canvas display is fast on the GPU (you can test by rendering but not updating a canvas display), and unless you're doing something very inefficient, calculating a display but not writing it to the property tree is fast (you can test this by disabling the write commands). It's the property I/O which you need to structure well, and then canvas will run fast. And of course the complexity of your underlying simulation costs - if you run a thermal model underneath to get real temperature reading, it costs more than inventing the numbers. But that has nothing to do with canvas. <ref>{{cite web<br />
|url = https://sourceforge.net/p/flightgear/mailman/message/35926343/ <br />
|title = <nowiki> Re: [Flightgear-devel] RFD: FlightGear and the changing state of<br />
air navigation </nowiki> <br />
|author = <nowiki> Thorsten Renk </nowiki> <br />
|date = Jul 4th, 2017 <br />
|added = Jul 4th, 2017 <br />
|script_version = 0.40 <br />
}}</ref><br />
<br />
<br />
it's a lot of work to code all these displays which someone has to do, but there's no reason to assume it'd be hopeless performance-wise.<ref>{{cite web<br />
|url = https://sourceforge.net/p/flightgear/mailman/message/35926412/ <br />
|title = <nowiki> Re: [Flightgear-devel] RFD: FlightGear and the changing state of<br />
air navigation </nowiki> <br />
|author = <nowiki> Thorsten Renk </nowiki> <br />
|date = Jul 4th, 2017 <br />
|added = Jul 4th, 2017 <br />
|script_version = 0.40 <br />
}}</ref><br />
<br />
we need to be realistic here: The G1000 is a fairly significant piece of computer hardware that we're going to emulate. It's not going to be "free" particularly for those on older hardware that's already struggling. However, hopefully we can offload a chunk of the logic (route management, autopilot/flight director) to the core, and do things like offline generation of terrain maps to minimize the impact.<ref>{{cite web<br />
|url = https://sourceforge.net/p/flightgear/mailman/message/35926745/ <br />
|title = <nowiki> Re: [Flightgear-devel] RFD: FlightGear and the changing state of<br />
air navigation </nowiki> <br />
|author = <nowiki> Stuart Buchanan </nowiki> <br />
|date = Jul 4th, 2017 <br />
|added = Jul 4th, 2017 <br />
|script_version = 0.40 <br />
}}</ref><br />
<br />
=== Route Manager ===<br />
that's exactly the kind of device James hopes the new code can support. He's read the G1000 pilot's manual, and *thinks* that nearly all the functions can be provided by the current GPS code It would be great if people could look over the current GPS features and indicate any pieces you think might be missing - additional commands, additional search features, extra data, or anything really. <ref>{{cite web<br />
|url = https://sourceforge.net/p/flightgear/mailman/message/23814733/ <br />
|title = <nowiki> Re: [Flightgear-devel] ZKV500 GPS instrument; (New?) GPS code bug </nowiki> <br />
|author = <nowiki> James Turner </nowiki> <br />
|date = Oct 22nd, 2009 <br />
|added = Oct 22nd, 2009 <br />
|script_version = 0.40 <br />
}}</ref><br />
<br />
=== tile servers ===<br />
Please keep in mind that most tile servers discourage bulk downloads. For the whole planet,oomlevel 8 is approx. 67k files, at zoomlevel 9 you have 265k, level 10 has a little over one million tiles. And one would probably want to go up to level 15 (roughly 1e9 files)<ref>{{cite web<br />
|url = https://sourceforge.net/p/flightgear/mailman/message/36057678/ <br />
|title = <nowiki> Re: [Flightgear-devel] Canvas MapLayer for OpenStreetMap, OpenAIP,<br />
VFR Sectionals </nowiki> <br />
|author = <nowiki> Torsten Dreyer </nowiki> <br />
|date = Sep 29th, 2017 <br />
|added = Sep 29th, 2017 <br />
|script_version = 0.40 <br />
}}</ref><br />
<br />
=== Offline mode ===<br />
would it be possible to provide an offline tool to pre-fetch a region, like TerraMaster, or terrasync.py? Call me old-fashioned or paranoid, but I don't want FG to go online and do stuff automatically, I prefer downloading what I need manually so that I know what gets onto my harddisk. Also - think of all the people with poor home internet which might have larger bandwidth only in a library elsewhere.<ref>{{cite web<br />
|url = https://sourceforge.net/p/flightgear/mailman/message/36057499/ <br />
|title = <nowiki> Re: [Flightgear-devel] Canvas MapLayer for OpenStreetMap, OpenAIP,<br />
VFR Sectionals </nowiki> <br />
|author = <nowiki> Thorsten Renk </nowiki> <br />
|date = Sep 29th, 2017 <br />
|added = Sep 29th, 2017 <br />
|script_version = 0.40 <br />
}}</ref><br />
<br />
that would certainly be possible - the code retrieving the data is pretty trivial and porting the Nasal code to python or some other script should be straightforward.<ref>{{cite web<br />
|url = https://sourceforge.net/p/flightgear/mailman/message/36057657/ <br />
|title = <nowiki> Re: [Flightgear-devel] Canvas MapLayer for OpenStreetMap, OpenAIP,<br />
VFR Sectionals </nowiki> <br />
|author = <nowiki> Stuart Buchanan </nowiki> <br />
|date = Sep 29th, 2017 <br />
|added = Sep 29th, 2017 <br />
|script_version = 0.40 <br />
}}</ref><br />
<br />
=== Navdata ===<br />
we need some better data sources, especially with direct routing replacing airways in many areas, and having airspace data would help the map displays, but the current API is specifically designed to support G430, G1000 and similar class devices. Adding RNAV approaches is eminently doable, see the the RNavController base class which the GPS/FMS layer uses to allow new waypoint / route segments to define how they are flown and drive CDIs <ref>{{cite web<br />
|url = https://sourceforge.net/p/flightgear/mailman/message/35927598/ <br />
|title = <nowiki> Re: [Flightgear-devel] RFD: FlightGear and the changing state of<br />
air navigation </nowiki> <br />
|author = <nowiki> James Turner </nowiki> <br />
|date = Jul 4th, 2017 <br />
|added = Jul 4th, 2017 <br />
|script_version = 0.40 <br />
}}</ref><br />
<br />
<br />
Getting the algorithms right, and keeping the data up to date every 7 weeks (we have only a tiny sliver of that data currently), is going to be much more of a challenge. I expect that it's probably an order of magnitude more complicated than our current flight dynamics (etc.), so we'd have to grow our contributor base, and find funding to pay at least Curt (and maybe a couple of others) full time to manage the project. Note that that's what has happened for other complex FOSS projects, like office suites and browsers, which generally end up working through a foundation, rather than our current relaxed circle-of-friends arrangement. The reason it's so much harder now is that the software *is* the product for GPS navigators, FMSs, etc. (unlike with older avionics, where the hardware was the main thing). That means that emulating even a simple unit like the GTN 650 or GNS 430W is almost difficult as building one, so we're trying to keep up with armies of full-time software developers at Garmin, Avidyne, etc.<ref>{{cite web<br />
|url = https://sourceforge.net/p/flightgear/mailman/message/35927243/ <br />
|title = <nowiki> Re: [Flightgear-devel] RFD: FlightGear and the changing state of<br />
air navigation </nowiki> <br />
|author = <nowiki> David Megginson </nowiki> <br />
|date = Jul 4th, 2017 <br />
|added = Jul 4th, 2017 <br />
|script_version = 0.40 <br />
}}</ref><br />
<br />
<br />
According to the Route Manager wiki page, we already have support for SID/STAR data provided from Navigraph, which is released on the AIRAC cycle, and costs a pretty small amount (9 EUR for a single download of FMS data, or 90 EUR per year) Given the relatively low cost, I don't think that we as an organiation want to get into trying to digitize data ourselves just to make it open-source or public domain. Particularly given the low cost of a download. We might want to digitize the STAR/SIDs for the default airport with each release so there are some approaches available for those who don't want to purchase the data.<ref>{{cite web<br />
|url = https://sourceforge.net/p/flightgear/mailman/message/35927426/ <br />
|title = <nowiki> Re: [Flightgear-devel] RFD: FlightGear and the changing state of<br />
air navigation </nowiki> <br />
|author = <nowiki> Stuart Buchanan </nowiki> <br />
|date = Jul 4th, 2017 <br />
|added = Jul 4th, 2017 <br />
|script_version = 0.40 <br />
}}</ref><br />
<br />
everyone agrees we would like to add airspace data - what we’re missing is a suitable data source with the correct license. Torsten found a raster-based source but for wider use in the sim we really need vector data, so we can render it ourselves directly. <ref>{{cite web |url = https://sourceforge.net/p/flightgear/mailman/message/36178857/ |title = <nowiki> Re: [Flightgear-devel] [flightgear/simgear] Nasal regex patch </nowiki> |author = <nowiki> James Turner </nowiki> |date = Jan 5th, 2018 |added = Jan 5th, 2018 |script_version = 0.36 }}</ref><br />
<br />
For airspace data we could use [https://openflightmaps.org/ https://openflightmaps.org/] . It provides community created navigation data for many countries in (currently only) Europe with a free license.<ref>{{cite web<br />
|url = https://forum.flightgear.org/viewtopic.php?p=326105#p326105 <br />
|title = <nowiki> Re: Canvas G1000 </nowiki> <br />
|author = <nowiki> TheTom </nowiki> <br />
|date = Jan 9th, 2018 <br />
|added = Jan 9th, 2018 <br />
|script_version = 0.36 <br />
}}</ref><br />
<br />
we definitely want vector data. Stuart is hoping that we might convince the source of the raster data we're using at present to provide it as raw vector data, but we haven't had any luck so far.<ref>{{cite web<br />
|url = https://forum.flightgear.org/viewtopic.php?p=326201&sid=137f64d32b770e50a3c4061be42ce28a#p326201 <br />
|title = <nowiki> Re: Canvas G1000 </nowiki> <br />
|author = <nowiki> stuart </nowiki> <br />
|date = Jan 10th, 2018 <br />
|added = Jan 10th, 2018 <br />
|script_version = 0.36 <br />
}}</ref><br />
<br />
== Airport Data (US - only )==<br />
At least for the US, all required information is available in the form of regularly updated UDFF files:<br />
* https://www.ngs.noaa.gov/AERO/aero.html<br />
* https://www.ngs.noaa.gov/AERO/uddf/WESTERN-PACIFIC/CALIFORNIA/SFO__03B.F77<br />
* https://www.ngs.noaa.gov/AERO/annof_7.pdf<br />
<br />
It would seem relatively straightforward to provide a scripted parser to create the corresponding charts procedurally.<br />
As a matter of fact, this could even be done in a background thread or using a separate Python script, i.e. if we wanted to ship pre-created imagery as part of fgdata.<br />
<br />
However, if the built-in Canvas system is extended to provide these charts, [[Phi]] could also be entirely self-contained by rendering the same airport charts without having to depend on external data sources.<br />
<br />
<br />
== Layers ==<br />
<br />
{{See also|Canvas_Sandbox#CanvasShapefile}}<br />
<br />
Following is the list of layers displayed by the G1000 system (see page 153 of the 190-00498-07 Rev. A), and mapping to the equivalent MapStructure Layer.<br />
Many of these would also be good to have for other avionics/GUI dialogs, including the NavDisplay framework, which is currently re-implementing this functionality separately, i.e. not yet using MapStructure.<br />
<br />
Following is the list of layers displayed by the G1000 system, based on the Garmin G1000 Integrated Flight Deck Pilot's Guide for the Cessna Nav III [http://static.garmincdn.com/pumac/190-00498-07_0A_Web.pdf Garmin Site] [https://web.archive.org/web/20170708032442/http://static.garmincdn.com/pumac/190-00498-07_0A_Web.pdf Wayback machine], page 153, and the mapping to the equivalent MapStructure Layer.<br />
<br />
Richard mentioned that if he were to implement approach plates in the EFB he'd probably use raster images provided via http and provide an http service within FG to do this, or to allow the EFB to use any other external web service. Other content for the EFB could be also provided as SVG via http.<ref>{{cite web |url = https://forum.flightgear.org/viewtopic.php?p=259194#p259194 |title = <nowiki> Re: </nowiki> |author = <nowiki> Richard </nowiki> |date = Sep 29th, 2015 |added = Sep 29th, 2015 |script_version = 0.36 }}</ref><br />
<br />
{| class="wikitable"<br />
|-<br />
! Layer !! [[Canvas MapStructure Layers|MapStructure Layer]] !! Status !! Page || Notes<br />
|-<br />
| Flight Plan Route Lines || {{MapStructure_File|name=RTE|type=lcontroller}} || Requires styling || {{PDF Link|page=190}} ||<br />
|-<br />
| Flight Plan Route Waypoints || {{MapStructure_File|name=WPT|type=lcontroller}} || Requires styling || {{PDF Link|page=190}} || <br />
|-<br />
| Rivers/Lakes || {{MapStructure_File|name=VFRChart|type=lcontroller}} || || {{PDF Link|page=148}} || Currently using downloaded raster from web. Perhaps generate similarly to Atlas<ref>{{cite web<br />
|url = https://forum.flightgear.org/viewtopic.php?p=203495#p203495 <br />
|title = <nowiki> Re: Atlas still in use ? </nowiki> <br />
|author = <nowiki> Torsten </nowiki> <br />
|date = Mar 17th, 2014 <br />
|added = Mar 17th, 2014 <br />
|script_version = 0.40 <br />
}}</ref>, or could be vector data from scenery. {{AtlasVsCanvasCameras}}<br />
|-<br />
| Topography Data || {{MapStructure_File|name=VFRChart|type=lcontroller}} || Synthetic || {{PDF Link|page=145}} || Height-map at chart-resolution. Perhaps generate similarly to Atlas? {{AtlasVsCanvasCameras}}<br />
|-<br />
| International Borders || || || {{PDF Link|page=148}} || Vector data from scenery?<br />
|-<br />
| Track Vector || || || {{PDF Link|page=156}} || Forward looking display of track. Look-ahead time selectable. <br />
|-<br />
| Navigation Range Ring || || || {{PDF Link|page=159}} || Straightforward extension of {{MapStructure_File|name=APS|type=lcontroller}}.<br />
|-<br />
| Fuel Range Ring || || || 159 || Straightforward extension of {{MapStructure_File|name=APS|type=lcontroller}}.<br />
|-<br />
| Terrain Data || || || 364 || Should be straightforward, with exception of obstacles. [[Spoken GCA|Profile view]] also required.<br />
|-<br />
| Traffic || {{MapStructure_File|name=TFC|type=lcontroller}} || || 394,423 || Various options, each with different iconography and data displayed. <br />
|-<br />
| Airways || {{MapStructure_File|name=VFRChart|type=lcontroller}} || || 154 || Needs to be replaced with vector data<br />
|-<br />
| NEXRAD || || || 282 || Heaps of weather data with complex symbology.<br />
|-<br />
| XM Lightning Data || {{MapStructure_File|name=WXR|type=lcontroller}} || Change to symbol for lightning? || 294 || Optional <br />
|-<br />
| Airports || {{MapStructure_File|name=APT|type=lcontroller}}, {{MapStructure_File|name=RWY|type=lcontroller}} || Require re-style based on size || 149, 163 ||<br />
|-<br />
| Runway Labels || {{MapStructure_File|name=RWY|type=lcontroller}} || || 148 || Needs to be added to {{MapStructure_File|name=RWY|type=symbol}}. Should be straightforward<br />
|-<br />
| Restricted || {{MapStructure_File|name=OpenAIP|type=lcontroller}} || || 182 || {{NeedVectorData}}<br />
|-<br />
| MOA (Military) || {{MapStructure_File|name=OpenAIP|type=lcontroller}} || || 182 || {{NeedVectorData}}<br />
|-<br />
| User Waypoints || || || <br />
|-<br />
| Latitude/Longitude Grid || {{MapStructure_File|name=GRID|type=lcontroller}} || || <br />
|-<br />
| NAVAIDs || {{MapStructure_File|name=APT|type=lcontroller}}, {{MapStructure_File|name=VOR|type=lcontroller}}, {{MapStructure_File|name=FIX|type=lcontroller}}, {{MapStructure_File|name=NDB|type=lcontroller}} || APT, requires styling || 162 || <br />
|-<br />
| Class B Airspaces/TMA || {{MapStructure_File|name=OpenAIP|type=lcontroller}} || || 182 || {{NeedVectorData}}<br />
|-<br />
| Class C Airspaces/TCA || {{MapStructure_File|name=OpenAIP|type=lcontroller}} || || 182 || {{NeedVectorData}}<br />
|-<br />
| Class D Airspaces || {{MapStructure_File|name=OpenAIP|type=lcontroller}} || || 182 || {{NeedVectorData}}<br />
|-<br />
| Other Airspaces/ADIZ || {{MapStructure_File|name=OpenAIP|type=lcontroller}} || || 182 || {{NeedVectorData}}<br />
|-<br />
| TFRs || || || 310 || <br />
|-<br />
| Obstacles || {{MapStructure_File|name=OpenAIP|type=lcontroller}} || || 182 || {{NeedVectorData}}<br />
|-<br />
| Land/Country Text || || || 148 || Currently using raster data from web. Replace with {{MapStructure_File|name=POI|type=lcontroller}}? <br />
|-<br />
| Cities || {{MapStructure_File|name=VFRChart|type=lcontroller}} || || 148 || Currently using raster data from web. Perhaps generate similarly to Atlas, or could be vector data from scenery. {{AtlasVsCanvasCameras}}<br />
|-<br />
| Roads || {{MapStructure_File|name=VFRChart|type=lcontroller}} || || 148 || Currently using raster data from web. Requires vector data from scenery<br />
|-<br />
| Railroads || {{MapStructure_File|name=VFRChart|type=lcontroller}} || || 148 || Currently using raster data from web. Requires vector data from scenery<br />
|-<br />
| State/Province Boundaries || {{MapStructure_File|name=VFRChart|type=lcontroller}} || || 148 || Currently using raster data from web. Requires vector data from scenery<br />
|-<br />
| River/Lake Names || {{MapStructure_File|name=VFRChart|type=lcontroller}} || || 148 || Currently using raster data from web. Replace with {{MapStructure_File|name=POI|type=lcontroller}}?<br />
|-<br />
| Selected Altitude Intercept Arc || || || 161 || Simple extention to APS<br />
|-<br />
| SafeTaxi (Optional) || {{MapStructure_File|name=RWY|type=lcontroller}}, {{MapStructure_File|name=TAXI|type=lcontroller}} || || 493 || We don't currently have the data to display taxiway identifier or holding points<br />
|-<br />
| ChartView (Optional) || || || 503 || [[Canvas_Sandbox#CanvasPDF|Rendering of PDFs.]] Might be possible to integrate with NaviGraph chart data?<br />
|-<br />
| FliteChart (Optional) || || || 521 || [[Canvas_Sandbox#CanvasPDF|Rendering of PDFs.]] Might be possible to integrate with NaviGraph chart data?<br />
|}<br />
<br />
== Existing work ==<br />
{{See also|Complex Canvas Avionics}}<br />
<br />
=== Avionics / Cockpits ===<br />
* [[User:Zakharov/zkv1000 installation guide|zkv1000]] see [https://forum.flightgear.org/viewtopic.php?f=14&t=32056]<br />
* [[Extra500]] / Avidyne Entegra R9000<br />
<br />
=== Nasal / Canvas ===<br />
* [[Canvas MFD Framework]]<br />
* MapStructure<br />
* MapStructure Layers<br />
* [[Howto:Creating a Canvas GUI Widget]]<br />
* [[Emesary]]<br />
<br />
=== C++ ===<br />
* [[Atlas]] map creation<br />
* [[Howto:Canvas View Camera Element|Synthetic Vision]] element for rendering viewmgr views to a Canvas <br />
* [[Canvas_Sandbox#CanvasPDF|Canvas PDF]] element - for rendering PDF files (think EFB functionality)<br />
<br />
== Possible Work ==<br />
<br />
=== Architectural TODO List ===<br />
This is a short list of architectural improvements I've noted during development that need to be revisited:<br />
* Use NavMap for MFD Navigation Map, DirectTo, Nearest, Information pages.<br />
* Separate out the HSI, tapes from the PFD and make them generic MFD UI Elements<br />
* Improve the performance of the maps, perhaps using a cache for queries, definitely by more aggressive clipping of the SlippyMap layers based on map size.<br />
<br />
The layers table shown above mentions a few limitations and ideas, such as:<br />
=== Nasal/Canvas ===<br />
* <image> tag support for svg.nas (patch: [http://wiki.flightgear.org/Howto:Extend_the_Canvas_SVG_module])<br />
* MapStructure: [[MapStructure_Optimizations#Allocating_selectable_ranges_into_groups|Allocating selectable ranges into Canvas groups]]<br />
<br />
=== C++ ===<br />
* fix up [[Canvas_MapStructure#Performance|projection issues]], and adopt Gijs' [[Canvas_Development#Projections|projection handling code]] for the hard-coded PUI [[Map]], to get rid of the standard Sanson-Flamsteed projection <br />
* adding a profile view, probably in conjunction with terrain sampling<br />
* using atlas code to generate heightmaps/topography<br />
* adding ESRI shapefile support to the Canvas system<br />
* adding PDF rendering support the Canvas system<br />
<br />
== Design ==<br />
<br />
The broad structure of the Nasal files in Aircaft/Instruments-3d/FG1000/Nasal is as follows:<br />
<br />
* MFD.nas - top level MFD device, loads the other Nasal files (likely to be moved elsewhere later) and pages.<br />
* PageGroupControllers.nas - controller for the Page Group display in the bottom right of the MFD, controlled by the FMS knob, and which allows selection between different page groups and individual pages.<br />
* [PageName]/[PageName].nas - MFD page, inheriting from the MFDPage.nas. Creates any required MapStructure and hierarchy of softkeys.<br />
* [PageName]/[PageName]Controller.nas - Controller for the MFD page and the MapStructure layers, inheriting from MFDPageController.nas<br />
* [PageName]/[PageName]Style.nas - Style controls for the MapStructure layers for the given Page.<br />
* [PageName]/[PageName]Options.nas - Options for the MapStructure layers for the given Page.<br />
<br />
Key design notes:<br />
* Most of the underlying Canvas [[MapStructure]] layers are now written (though they require styling, and/or would benefit from replacement with vector data). <br />
* [[Emesary]] IPC framework is used to link between the MFD and underlying simulation state. This should make it easy to run the MFD on a separate FG instance, and provides a good demarkation between the individual aircraft systems and the FG1000 itself. <br />
* Various underlying UI classes are used to handle highlighting, selection and scrolling of fields. See [[Canvas MFD Framework]] for details of the elements now supported.<br />
<br />
== Resources ==<br />
<br />
{{#ev:youtube|I0y6p0ct1m0}}<br />
<br />
== Related ==<br />
=== Commits ===<br />
This section is intended to help keep track of related fgdata commits, so that if/when the project should stall, people can more easily look up related changes.<br />
<br />
<br />
* {{fgdata commit|da252c8a18fe2ce88066c051f6df588639377792|text=Initial Direct To page}}(01/2018)<br />
* {{fgdata commit|0c4544c1e1788f3396330c86016b66df8643fd3b|text=Add Config Store and MFD Header display.}}(01/2018)<br />
* {{fgdata commit|9bd10f8273a6e64b12b9a034ca4952d87090f921|text=SVG MFD UI from miChat}}(01/2018)<br />
* {{fgdata commit|f6f5efe9f442ff058d9d425d85337139b2a9bf1f|text=Use Emesary interface rather than airportinfo()}}(01/2018)<br />
* {{fgdata commit|d306e7ba100840f5c3909123a383b19f7e7d7540|text=Set standby COM frequency from Airport pages}}(01/2018)<br />
* {{fgdata commit|cbb281759cd3f2b830bffdd12ba72d456996a13a|text=NAV/COM Radio support}}(01/2018)<br />
* {{fgdata commit|a25c66850a93f0ae7a6f7ad8769680c1fba99887|text=Add full set of hardkeys to fg1000 PUI dialog.}}(01/2018)<br />
* {{fgdata commit|ab8774a3e0aa3909ad284a65194f5d80dc097c6e|text=extend MFDPageController to handle Emesary register}}(01/2018)<br />
* {{fgdata commit|73424c1791242e053efcdac37a7dd3b66226387b|text=Update NAV/COMM frequencies from properties}}(01/2018)<br />
* {{fgdata commit|ad77dc2f9cd2a1e1ebd5efd4226cbfbf3a522008|text=Modify FG1000 EIS to use Emesary}}(01/2018)<br />
* {{fgdata commit|9eb91171b4689b29910db06757bc47767ff59d2c|text=FG1000 Nearest Airports page}}(01/2018)<br />
* {{fgdata commit|475fd505859b7841e29de725d4c1c39db7ad4ee5|text=PFD UI Elements and NearestAirports page}} (12/2017)<br />
* {{fgdata commit|d0203549e833b32b719697b3a2c2a63e16fcef16|text=Add AirportInfo and template pages for FG1000}} (12/2017)<br />
* {{fgdata commit|3d31775ff36bf3aa08a929992b70f32f2a525509|text=Initial commit of FG1000 MFD}} (11/2017)<br />
<br />
MapStructure related:<br />
<br />
* {{fgdata commit|4bd57492f454a05f725e6fe5a80dc246cb5e5e0f|text=GRID layer}} (10/2017)<br />
* {{fgdata commit|d84c527ca747dd6bbd9634507f0664ff3631bdef|text=RWY, TAXI, TWR, PARKING}} (10/2017)<br />
* {{fgdata commit|e38ec03c609b882664d0496932709aa623e486cb|text=STAMEN}} (10/2017)<br />
* {{fgdata commit|2fbc1dc491da867e0fd4f8fc810c5cddd80ced1f|text=VFRChart}} (09/2017)<br />
* {{fgdata commit|85b7665c19ebaae02d746fef53f25f8d8974eb13|text=OSM and OpenAIP}} (09/2017)<br />
<br />
=== References ===<br />
{{Appendix}}<br />
<br />
[[Category:Canvas]]</div>Clm76https://wiki.flightgear.org/w/index.php?title=Nasal_Flightplan&diff=112636Nasal Flightplan2017-12-03T07:17:43Z<p>Clm76: </p>
<hr />
<div>{{Systems Modeling Disclaimer}}<br />
{{Autoflight Navigation}}<br />
{{Nasal Navigation}}<br />
<br />
Because FlightGear's [[route manager]] flight plan system is exposed to [[Nasal]], '''Nasal can be used to interact with flight plans'''. Obviously, this is very useful, especially for aircraft like airliners, which have complex route managers systems. This article shows how this can be done.<br />
<br />
== Background ==<br />
The Nasal functions relating to the route manager system include:<br />
* {{func link|flightplan()}} - return the active plan.<br />
* {{func link|airwaysRoute()}}<br />
* {{func link|createFlightplan()}} - creates new empty plan. A path can be supplied to load a plan from xml.<br />
<br />
Flight plans are based on waypoints, which, in C++, inherit from the {{API Link|flightgear|class|FGPositioned}} class.<br />
<br />
== Waypoint hashes ==<br />
The following are members of a waypoint ghost, as generated by, for example, {{func link|airwaysRoute()}}:<br />
<br />
; wp_name : Name of the waypoint, returned as string.<br />
; wp_type : Waypoint type, returned as string. One of "basic," "navaid," "offset-navaid," "runway," "hdgToAlt," "dmeIntercept," "radialIntercept," or "vectors."<br />
; wp_role: Role of waypoint.<br />
; wp_lat ''or'' lat : Latitude of waypoint.<br />
; wp_lon ''or'' lon : Longitude of waypoint.<br />
; wp_parent_name : Name of waypoint's parent.<br />
; wp_parent : Waypoint's parent.<br />
; fly_type : How to waypoint should be flown over or reacted to. One of "Hold," "flyOver," or "flyBy."<br />
; heading_course : Heading of runway.<br />
<br />
== Flightplan methods and variables ==<br />
Notice that instead of passing a leg as parameter, a waypoint can be passed.<br />
; getWP(index) : Returns the leg for specified index.<br />
; currentWP() : Return current active leg.<br />
; nextWP() : Make next waypoint active.<br />
; getPlanSize() : Returns number of waypoints<br />
; appendWP(leg) : Add a leg to the end of the flightplan.<br />
; insertWP(leg, index) : Pass a leg object and its position.<br />
; deleteWP(index) : Deletes the waypoint at specified index.<br />
; insertWPAfter() : <br />
; insertWaypoints(vector, index) : Pass a vector of waypoint objects, and the position to insert.<br />
; cleanPlan() : Clears all waypoints except destination and departure.<br />
; clearWPType(type) : Supply a type string, it will clear all waypoints of the type.<br />
; clone() : Return a copy of the flightplan.<br />
; pathGeod() : <br />
; finish() : Finish the plan. (a call to delegate will be made)<br />
; indexOfWP(wp) : Returns the index of the passed waypoint/leg.<br />
; destination : airport object as destination.<br />
; destination_runway : rwy object as destination and its airport implicit.<br />
; departure : airport object as departure.<br />
; departure_runway : rwy object as departure and its airport implicit.<br />
; id : optional name of plan.<br />
; sid : procedure object for SID.<br />
; star : procedure object for STAR.<br />
; sid_trans :<br />
; star_trans :<br />
; approach : procedure object for approach.<br />
; current : Index of current waypoint.<br />
; aircraftCategory : ICAO aircraft category.<br />
; followLegTrackToFix : Specific used by some procedures. It controls whether the system will fly on an intersection course (and hence, different track) to the end of the leg, or make a corrective S-turn to get back on the leg track immediately it becomes possible.<br />
; activate() : This will make the flight plan the default (the one used in route-manager).<br />
; save(path) : Save a plan to xml. Will return true or false for success.<br />
<br />
== Leg methods and variables ==<br />
A leg is a wrapper for a waypoint, so it will have all waypoints variables and methods plus what is listed below.<br />
Notice, that a leg you have gotten from a plan, but deleted in the plan, will be invalid and should not be used or modified.<br />
A leg you have gotten from a plan, when modified, will modify the leg inside the plan you got it from.<br />
; setSpeed(speed, type) : Sets the speed restriction. Setting nil type, will crash FG.<br />
; setAltitude(altitude, type) : Sets the altitude restriction. Setting nil type, will crash FG.<br />
; path() :<br />
; courseAndDistanceFrom() :<br />
; parents :<br />
; index :<br />
; alt_cstr : Read-only. Altitude restriction.<br />
; alt_cstr_type : Read-only. Altitude restriction type. Can be "at", "above", "below", "mach", "computed", "computed-mach", "delete".<br />
; speed_cstr : Read-only. Speed restriction.<br />
; speed_cstr_type : Read-only. Speed restriction. Can be "at", "above", "below", "mach", "computed", "computed-mach", "delete".<br />
; leg_distance :<br />
; leg_bearing :<br />
; distance_along_route :<br />
<br />
== Procedure methods and variables ==<br />
; route(runway) : Returns a vector of waypoints.<br />
; transition() : Only works on STAR and SID.<br />
<br />
== Examples ==<br />
<syntaxhighlight lang="nasal"><br />
# get the active flight plan (the one being used by the route manager)<br />
var fp = flightplan();<br />
<br />
# or create one an XML file<br />
fp = flightplan('/path/to/xml');<br />
<br />
# save the active flight plan<br />
fgcommand("save-flightplan", props.Node.new({"path": 'path/to/xml'}));<br />
<br />
# duplicate a flight-plan<br />
var secondary = fp.clone();<br />
<br />
var dest = airportinfo('KSFO');<br />
var rwy = dest.runway('19L');<br />
# the the arrival runway (and airport, automatically)<br />
fp.destination_runway = rwy;<br />
<br />
# or if no runway is known/specified<br />
fp.destination = dest;<br />
</syntaxhighlight><br />
<br />
Building procedures and transitions. As mentioned above there's a couple of different ways to handle this, the examples below assume the C++ code automatically deletes and re-inserts waypoints for procedures, but that's only one possible design.<br />
<syntaxhighlight lang="nasal"><br />
var apt = airportinfo('KSFO');<br />
# example for SIDs, STARs are the same, approaches too<br />
var allSids = apt.sids();<br />
<br />
# SIDs for a specific runway - note these return SID IDs as string, for compatibility with existing code<br />
var rwySids = apt.sids('28L');<br />
</syntaxhighlight><br />
<br />
Inserting and deleting waypoints (possibly in batches)<br />
<syntaxhighlight lang="nasal"><br />
var fp = flightplan();<br />
# waypoint created from lat, lon, or a navaid, or anything else?<br />
var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 100000);<br />
var wp = createWP(pos.lat(), pos.lon(), "EPICA");<br />
<br />
# manually insert a waypoint at the end of the plan<br />
fp.insertWP(wp, fp.getPlanSize());<br />
<br />
# manually insert a waypoint at a defined position (n) into the plan<br />
fp.insertWP(wp, n);<br />
<br />
# route along airways, and insert a whole bunch of waypoints<br />
# this is needed for the route-manager dialog, maybe not for a<br />
# real FMS interface....<br />
var segment = [<waypoint object>, <waypoint object>, <waypoint object>];<br />
# segment is a vector of waypoints now<br />
fp.insertWaypoints(segment, fp.getPlanSize());<br />
</syntaxhighlight><br />
<br />
== aircraft.history() (3.2+) ==<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 length<br />
debug.dump( hist.pathForHistory(<minimum-edge-length-meter>) );<br />
</syntaxhighlight><br />
<br />
== Related content ==<br />
=== Wiki articles ===<br />
* [[Nasal library#Extension functions|Nasal library § Extension functions]]<br />
* [[Navdata cache#Accessing via Nasal|Navdata cache § Accessing via Nasal]]<br />
* [[Route Manager]]<br />
* [[Route Manager internals]]<br />
<br />
=== Documentation ===<br />
* [http://api-docs.freeflightsim.org/flightgear/NasalPositioned_8cxx_source.html#l00585 flightplanGhostSetMember] — ''Members of a flight plan object that can be set.''<br />
* [http://api-docs.freeflightsim.org/flightgear/NasalPositioned_8cxx_source.html#l00557 flightplanGhostGetMember] — ''Members of flight plan object that can be read.''<br />
* [http://api-docs.freeflightsim.org/flightgear/NasalPositioned_8cxx_source.html#l02485 initNasalPositioned] — ''Contains a list of functions that can be called on airport, flight plan, waypoint, procedure, or flight plan leg objects.''<br />
* [http://api-docs.freeflightsim.org/flightgear/route__mgr_8cxx_source.html#l00220 FGRouteMgr::FGRouteMgr] — ''List of [[fgcommands]] relating to the route manager.''<br />
<br />
=== Misc ===<br />
* https://sourceforge.net/p/flightgear/mailman/message/34688624/<br />
* https://sourceforge.net/p/flightgear/mailman/message/35164289/<br />
* https://sourceforge.net/p/flightgear/mailman/flightgear-devel/thread/BB67C9F3-028B-40E5-94E4-246CD1E0B2CC%40mac.com/#msg23708827<br />
* https://sourceforge.net/p/flightgear/mailman/message/33699574/<br />
* https://sourceforge.net/p/flightgear/mailman/message/21010010/<br />
* https://sourceforge.net/p/flightgear/mailman/message/23678747/<br />
<br />
=== Search Queries ===<br />
<br />
=== Commits ===<br />
<br />
=== Threads ===<br />
{{Appendix}}<br />
<br />
[[Category:Nasal]]</div>Clm76https://wiki.flightgear.org/w/index.php?title=Nasal_Flightplan&diff=106974Nasal Flightplan2017-02-18T15:41:44Z<p>Clm76: There was an error in fp.insertWP. Added how to insert a waypoint at a defined place into the plan.</p>
<hr />
<div>{{Systems Modeling Disclaimer}}<br />
{{Autoflight Navigation}}<br />
{{Nasal Navigation}}<br />
<br />
Because FlightGear's [[route manager]] flight plan system is exposed to [[Nasal]], '''Nasal can be used to interact with flight plans'''. Obviously, this is very useful, especially for aircraft like airliners, which have complex route managers systems. This article shows how this can be done.<br />
<br />
== Background ==<br />
The Nasal functions relating to the route manager system include:<br />
* {{func link|flightplan()}}<br />
* {{func link|airwaysRoute()}}<br />
<br />
Flight plans are based on waypoints, which, in C++, inherit from the {{API Link|flightgear|class|FGPositioned}} class.<br />
<br />
== Waypoint hashes ==<br />
The following are members of a waypoint ghost, as generated by, for example, {{func link|airwaysRoute()}}:<br />
<br />
; wp_name : Name of the waypoint, returned as string.<br />
; wp_type : Waypoint type, returned as string. One of "basic," "navaid," "offset-navaid," "runway," "hdgToAlt," "dmeIntercept," "radialIntercept," or "vectors."<br />
; wp_role: Role of waypoint.<br />
; wp_lat ''or'' lat : Latitude of waypoint.<br />
; wp_lon ''or'' lon : Longitude of waypoint.<br />
; wp_parent_name : Name of waypoint's parent.<br />
; wp_parent : Waypoint's parent.<br />
; fly_type : How to waypoint should be flown over or reacted to. One of "Hold," "flyOver," or "flyBy."<br />
; heading_course : Heading of runway.<br />
<br />
== Examples ==<br />
<syntaxhighlight lang="nasal"><br />
# get the active flight plan (the one being used by the route manager)<br />
var fp = flightplan();<br />
<br />
# or create one an XML file<br />
fp = flightplan('/path/to/xml');<br />
<br />
# save the active flight plan<br />
fgcommand("save-flightplan", props.Node.new({"path": 'path/to/xml'}));<br />
<br />
# duplicate a flight-plan<br />
var secondary = fp.clone();<br />
<br />
var dest = airportinfo('KSFO');<br />
var rwy = dest.runway('19L');<br />
# the the arrival runway (and airport, automatically)<br />
fp.destination_runway(rwy)<br />
<br />
# or if no runway is known/specified<br />
fp.destination(dest)<br />
</syntaxhighlight><br />
<br />
Building procedures and transitions. As mentioned above there's a couple of different ways to handle this, the examples below assume the C++ code automatically deletes and re-inserts waypoints for procedures, but that's only one possible design.<br />
<syntaxhighlight lang="nasal"><br />
var apt = airportinfo('KSFO');<br />
# example for SIDs, STARs are the same, approaches too<br />
var allSids = apt.sids();<br />
<br />
# SIDs for a specific runway - note these return SID IDs as string, for compatibility with existing code<br />
var rwySids = apt.sids('28L');<br />
</syntaxhighlight><br />
<br />
Inserting and deleting waypoints (possibly in batches)<br />
<syntaxhighlight lang="nasal"><br />
var fp = flightplan();<br />
# waypoint created from lat, lon, or a navaid, or anything else?<br />
var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 100000);<br />
var wp = createWP(pos.lat(), pos.lon(), "EPICA");<br />
<br />
# manually insert a waypoint at the end of the plan<br />
fp.insertWP(wp, fp.getPlanSize());<br />
<br />
# manually insert a waypoint at a defined position (n) into the plan<br />
fp.insertWP(wp, n);<br />
<br />
# route along airways, and insert a whole bunch of waypoints<br />
# this is needed for the route-manager dialog, maybe not for a<br />
# real FMS interface....<br />
var segment = [<waypoint object>, <waypoint object>, <waypoint object>];<br />
# segment is a vector of waypoints now<br />
fp.insertWaypoints(segment, fp.getPlanSize());<br />
</syntaxhighlight><br />
<br />
== aircraft.history() (3.2+) ==<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 length<br />
debug.dump( hist.pathForHistory(<minimum-edge-length-meter>) );<br />
</syntaxhighlight><br />
<br />
== Related content ==<br />
=== Wiki articles ===<br />
* [[Nasal library#Extension functions|Nasal library § Extension functions]]<br />
* [[Navdata cache#Accessing via Nasal|Navdata cache § Accessing via Nasal]]<br />
<br />
=== Documentation ===<br />
* [http://api-docs.freeflightsim.org/flightgear/NasalPositioned_8cxx_source.html#l00585 flightplanGhostSetMember] — ''Members of a flight plan object that can be set.''<br />
* [http://api-docs.freeflightsim.org/flightgear/NasalPositioned_8cxx_source.html#l00557 flightplanGhostGetMember] — ''Members of flight plan object that can be read.''<br />
* [http://api-docs.freeflightsim.org/flightgear/NasalPositioned_8cxx_source.html#l02485 initNasalPositioned] — ''Contains a list of functions that can be called on airport, flight plan, waypoint, procedure, or flight plan leg objects.''<br />
* [http://api-docs.freeflightsim.org/flightgear/route__mgr_8cxx_source.html#l00220 FGRouteMgr::FGRouteMgr] — ''List of [[fgcommands]] relating to the route manager.''<br />
<br />
[[Category:Nasal]]</div>Clm76https://wiki.flightgear.org/w/index.php?title=Canvas_snippets&diff=105438Canvas snippets2016-10-29T07:41:00Z<p>Clm76: /* Customizing MapStructure Styling */</p>
<hr />
<div>{{Stub}}<br />
{{-}}<br />
This article is meant to be a collection of self-contained code snippets for doing Nasal/Canvas coding without having to spend too much time working through APIs, documentation and existing code - the idea is to provide snippets that contain comments and explicit assumptions, so that these snippets can be easily adapted by people without necessarily having to be very familiar with Nasal/Canvas coding. In the long term, we're hoping to grow a library of useful code snippets to cover most use-cases, while also covering more complex scenarios, e.g. using Canvas-specific helper frameworks like [[Canvas MapStructure]], the [[NavDisplay]] or the recent CDU work.<br />
<br />
Canvas itself is designed to be front-end agnostic, meaning that it doesn't matter where a Canvas is used/displayed - this is accomplished by so called "placements", which determine where a Canvas texture shown. Thus, the back-end logic can remain the same usually, so that GUI dialogs may show avionics, but also so that avionics may show GUI widgets, which also applies to HUDs, liveries and even placements within the FlightGear scenery.<br />
<br />
We encourage people to use the snippets listed below to get started with Nasal/Canvas coding, but also to provide feedback on extending/improving this article to make it even more accessible and useful. Equally, if you're aware of any Canvas-related efforts that may contain useful code snippets, please do feel free to add those snippets here. Even people who don't have any interest in coding itself are encouraged to get involved by helping test the snippets listed below, for which you only need to the [[Nasal Console]], and while you're at it, please also help provide/update screen shots for each code snippet.<br />
<br />
Contributions added to this article should ideally satisfy some requirements:<br />
* be entirely self-contained<br />
* contain good/clear comments<br />
* have pointers/references to related code/use-cases<br />
* make assumptions explicit<br />
* contain screen shots for each example<br />
* avoid overloaded symbol names to ensure that examples can be merged and adapted easily<br />
* dependencies (svg files, images/textures etc) should always be chosen such that snippets always work using $FG_ROOT<br />
* hard-coded assumptions (e.g. texture dimensions in terms of width/height etc) should be encapsulated using variables<br />
<br />
{{Canvas Navigation}}<br />
<br />
== Creating a standalone Canvas ==<br />
<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[Special:UploadWizard|Upload requested]] || <br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var (width, height) = (512,512);<br />
# Create a standalone Canvas (not attached to any GUI dialog/aircraft etc) <br />
var myCanvas = canvas.new({<br />
"name": "Livery Test", # The name is optional but allow for easier identification<br />
"size": [width, height], # Size of the underlying texture (should be a power of 2, required) [Resolution]<br />
"view": [width, height], # Virtual resolution (Defines the coordinate system of the canvas [Dimensions]<br />
# which will be stretched the size of the texture, required)<br />
"mipmapping": 1 # Enable mipmapping (optional)<br />
});<br />
<br />
# set background color<br />
myCanvas.set("background", canvas.style.getColor("bg_color"));<br />
<br />
# creating the top-level/root group which will contain all other elements/group<br />
var root = myCanvas.createGroup();<br />
<br />
# OPTIONAL: Create a Canvas dialog window to hold the canvas and show that it's working<br />
# the Canvas is now standalone, i.e. continues to live once the dialog is closed!<br />
var window = canvas.Window.new([width,height],"dialog");<br />
window.setCanvas(myCanvas);<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
<br />
== Accessing the Canvas Desktop ==<br />
Sometimes you may want to render to the main screen, without creating a separate Canvas window - this can be accomplished by using the Canvas desktop, note that the following example is fully self-contained, i.e. does not require any code to be added to work:<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[Special:UploadWizard|Upload requested]] || <br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var myNode = canvas.getDesktop().createChild("text")<br />
.setText("Hello Canvas Desktop")<br />
.setFontSize(25, 1.0) # font size (in texels) and font aspect ratio<br />
.setColor(1,0,0,1) # red, fully opaque<br />
.setAlignment("center-center") # how the text is aligned to where you place it<br />
.setTranslation(160, 80); # where to place the text<br />
</syntaxhighlight><br />
|}<br />
<br />
== Creating Tooltips ==<br />
== Creating Popups ==<br />
== Creating a Canvas GUI Window ==<br />
<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Snippets-canvas-dialog.png|left|thumb|This is what the [[Nasal]]/[[Canvas]] snippet will look like once you pasted it into the [[Nasal Console]] and click "Execute".]] || {{Note|This example uses so called method chaining, if you're not familiar with the concept, please see: [[Object_Oriented_Programming_with_Nasal#More_on_methods:_Chaining|Method Chaining]].}}<br />
<br />
{{Canvas Snippets Boilerplate}}<br />
<br />
|}<br />
<br />
== Adding Raster Images ==<br />
<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code <br />
|-<br />
| [[File:Canvas Snippets-raster image.png|thumb|Canvas snippet demonstrating how to load a raster image]] ||<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
# path is relative to $FG_ROOT (base package)<br />
var path = "Textures/Splash1.png";<br />
# create an image child for the texture<br />
var child = root.createChild("image")<br />
.setFile(path)<br />
.setTranslation(100, 10)<br />
.setSize(130, 130);<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Adding Raster Images downloaded on demand ==<br />
<br />
The '''path''' could also just as well be a URL, i.e. a raster image retrieved via http - for example, the following snippet is entirely self-contained and can be pasted into the [[Nasal Console]] and directly executed "as is": <br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-raster-images-via-url.png|thumb|screen shot demonstrating how Nasal and Canvas can be used to display raster images downloaded on demand]] ||<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
# create a new window, dimensions are 400 x 200, using the dialog decoration (i.e. titlebar)<br />
var window = canvas.Window.new([400,200],"dialog");<br />
<br />
# adding a canvas to the new window and setting up background colors/transparency<br />
var myCanvas = window.createCanvas().set("background", canvas.style.getColor("bg_color"));<br />
<br />
# Using specific css colors would also be possible:<br />
# myCanvas.set("background", "#ffaac0");<br />
<br />
# creating the top-level/root group which will contain all other elements/group<br />
var root = myCanvas.createGroup();<br />
<br />
<br />
# path now a URL<br />
var url = "http://www.worldwidetelescope.org/docs/Images/MapOfEarth.jpg";<br />
<br />
# create an image child for the texture<br />
var child=root.createChild("image")<br />
.setFile( url ) <br />
.setTranslation(45,22) # centered, in relation to dialog coordinates<br />
.setSize(310,155); # image dimensions<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Clipping ==<br />
{{Note|{{FGCquote<br />
|1= Scaling or any other type of transformation or changing the coordinates of individual points is definitely more efficient than clipping (which requires to change the OpenGL clip planes for every rendered object with a different clipping rectangle).<br />
|2= {{cite web<br />
| url = http://forum.flightgear.org/viewtopic.php?p=277062#p277062<br />
| title = <nowiki>Re: Space Shuttle</nowiki><br />
| author = <nowiki>TheTom</nowiki><br />
| date = Feb 21st, 2016<br />
| added = Feb 21st, 2016<br />
| script_version = 0.25<br />
}}<br />
}}<br />
}}<br />
I would suggest to refer to api.nas and look for "clip" and/or "rect" - IIRC, you need to set up a clipping rectangle by setting some kind of "clip" property and setting it to a rect value in the form of rect(...)<br />
{{FGCquote<br />
|1= For details, see the clipping example at: [[Canvas Nasal API#set 2]] and [[Canvas Element#clip.28.29]]<br />
|2= {{cite web<br />
| url = http://forum.flightgear.org/viewtopic.php?p=276965#p276965<br />
| title = <nowiki>Re: Space Shuttle</nowiki><br />
| author = <nowiki>Hooray</nowiki><br />
| date = Feb 21st, 2016<br />
| added = Feb 21st, 2016<br />
| script_version = 0.25<br />
}}<br />
}}<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:MapStructure_dialog_with_clipping_and_event_handling_applied.png|thumb]] ||<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
# create a new window, dimensions are 400 x 200, using the dialog decoration (i.e. titlebar)<br />
var window = canvas.Window.new([400,200],"dialog");<br />
<br />
# adding a canvas to the new window and setting up background colors/transparency<br />
var myCanvas = window.createCanvas().set("background", canvas.style.getColor("bg_color"));<br />
<br />
# Using specific css colors would also be possible:<br />
# myCanvas.set("background", "#ffaac0");<br />
<br />
# creating the top-level/root group which will contain all other elements/group<br />
var root = myCanvas.createGroup();<br />
<br />
# create an image child for the texture<br />
var child=root.createChild(".........")<br />
.setFile( url ) <br />
.setTranslation(45,22) # centered, in relation to dialog coordinates<br />
.setSize(310,155); # image dimensions<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Adding OpenVG Paths ==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Openvg-via-canvas.png|thumb|screen shot showing a simple Canvas GUI dialog demonstrating how to use OpenVG-path drawing via Nasal and Canvas]] <br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root'''.}}<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var graph = root.createChild("group");<br />
<br />
var x_axis = graph.createChild("path", "x-axis")<br />
.moveTo(10, height/2)<br />
.lineTo(width-10, height/2)<br />
.setColor(1,0,0)<br />
.setStrokeLineWidth(3);<br />
<br />
var y_axis = graph.createChild("path", "y-axis")<br />
.moveTo(10, 10)<br />
.lineTo(10, height-10)<br />
.setColor(0,0,1)<br />
.setStrokeLineWidth(2);<br />
</syntaxhighlight><br />
|-<br />
|}<br />
<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-openvg-quadTo.png|thumb|screen shot showing a simple Canvas GUI dialog demonstrating how to use OpenVG-path drawing via Nasal and Canvas (Canvas/OpenVG quadTo API for drawing curves)]] <br />
| {{Note|This assumes that you are appending this to the snippet shown above.}}<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
var points = [ 60,height-20, <br />
230,height-100,<br />
];<br />
<br />
var track = graph.createChild("path", "track")<br />
.moveTo(10, height/2)<br />
.quadTo( points )<br />
.setColor(0,1,0)<br />
.setStrokeLineWidth(4);<br />
<br />
<br />
</syntaxhighlight><br />
|-<br />
|}<br />
<br />
<br />
<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-openvg-cubicTo.png|thumb|screen shot showing a simple Canvas GUI dialog demonstrating how to use OpenVG-path drawing via Nasal and Canvas (Canvas/OpenVG cubicTo API for drawing curves)]] <br />
| {{Note|This assumes that you are appending this to the snippet shown above.}}<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var points = [ 60,height-20, <br />
120,height-120,<br />
230,height-100,<br />
];<br />
<br />
var track = graph.createChild("path", "track")<br />
.moveTo(10, height/2)<br />
.cubicTo( points )<br />
.setColor(0,1,0)<br />
.setStrokeLineWidth(4);<br />
<br />
</syntaxhighlight><br />
|-<br />
|}<br />
<br />
== Adding Vector Images ==<br />
<br />
[[Category:Canvas SVG]]<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-svg-support.png|thumb|screen shot demonstrating how the scripted Nasal-based SVG parser can be used to dynamically turn SVG files into OpenVG instructions understood by Canvas]] <br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
# change the background color <br />
myCanvas.set("background", "#ffaac0");<br />
<br />
# creating the top-level/root group which will contain all other elements/group<br />
var root = myCanvas.createGroup();<br />
<br />
var filename = "/Nasal/canvas/map/Images/boeingAirplane.svg";<br />
var svg_symbol = root.createChild('group');<br />
canvas.parsesvg(svg_symbol, filename);<br />
<br />
svg_symbol.setTranslation(width/2,height/2);<br />
<br />
#svg_symbol.setScale(0.2);<br />
#svg_symbol.setRotation(radians)<br />
</syntaxhighlight><br />
|-<br />
|}<br />
<br />
== Using the SymbolCache ==<br />
Whenever a symbol may need to be shown/instanced multiple times (possibly using different styling), it makes sense to use caching - otherwise, identical symbols would be treated as separate OpenVG groups, all of which would need to be rasterized/rendedered separately (i.e. 100 identical symbols would be updated/rendered one by one). <br />
<br />
Typically, a map may display multiple instances of an otherwise identical symbol (think VOR, NDB, DME etc) - equally, a multiplayer map may showing multiple aircraft symbols at the same time. In these cases, it makes sense to use the SymbolCache framework, which will render symbols into a separate Canvas texture and provide a texture map that can be treated as a lookup map, which even supports styling for otherwise identical symbols. To learn more, please refer to [[Canvas MapStructure#The_SymbolCache|SymbolCache]]<br />
... <br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-SymbolCache-Instancing.png|thumb|Screen shot showing a Canvas based GUI dialog that is using the SymbolCache for instancing multiple symbols (including support for styling)]] <br />
| <!--{{Caution|This is currently untested code}}--><br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
##<br />
# this is the function that draws a symbol using OpenVG paths<br />
# it accepts a group to draw to and returns the rendered group <br />
# to the caller<br />
var drawVOR = func(group) {<br />
return group.createChild("path")<br />
.moveTo(-15,0)<br />
.lineTo(-7.5,12.5)<br />
.lineTo(7.5,12.5)<br />
.lineTo(15,0)<br />
.lineTo(7.5,-12.5)<br />
.lineTo(-7.5,-12.5)<br />
.close()<br />
.setStrokeLineWidth(line_width) # style-able<br />
.setColor(color); # style-able<br />
};<br />
<br />
var style = { # styling related attributes (as per the draw* function above)<br />
line_width: 3,<br />
scale_factor: 1,<br />
color: [1,0,0],<br />
};<br />
<br />
# create a new cache entry for the styled symbol<br />
var myCachedSymbol = canvas.StyleableCacheable.new(<br />
name:'myVOR', draw_func: drawVOR,<br />
cache: canvas.SymbolCache32x32, # the cache to be used<br />
draw_mode: canvas.SymbolCache.DRAW_CENTERED,<br />
relevant_keys: ['line_width', 'color'], # styling related attributes<br />
);<br />
<br />
var target = root.createChild('group');<br />
<br />
var x=0;<br />
var y=height/2;<br />
<br />
var xoffset=50;<br />
<br />
# render 5 instanced symbols using the style specified above<br />
for (var i=0;i<5;i+=1) {<br />
# look up the raster image for the symbol<br />
# render it using the passed style and adjust scaling<br />
var instanced = myCachedSymbol.render(target, style)<br />
.setScale(style.scale_factor)<br />
.setTranslation(x+=xoffset,y);<br />
}</syntaxhighlight><br />
|-<br />
|}<br />
<br />
The example shown above uses a fixed symbol/icon cache that is set up while booting Flightgear - sometimes, we may need cache for different purposes. So, let's assume, we need a new/custom cache with a different resolution for each entry in the cache (e.g. 256x256), we can easily accomplish that by setting up a new cache like this: <br />
<syntaxhighlight lang="nasal"><br />
var mySymbolCache256x256 = canvas.SymbolCache.new(1024,256);<br />
</syntaxhighlight><br />
<br />
== Adding Text Elements ==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:CanvasText-Hello-World.png|thumb|Screen shot showing the CanvasText example contributed by Necolatis]]<br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var myText = root.createChild("text")<br />
.setText("Hello world!")<br />
.setFontSize(20, 0.9) # font size (in texels) and font aspect ratio<br />
.setColor(1,0,0,1) # red, fully opaque<br />
.setAlignment("center-center") # how the text is aligned to where you place it<br />
.setTranslation(160, 80); # where to place the text<br />
</syntaxhighlight><br />
|-<br />
|}<br />
<br />
== Adding GUI Labels ==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-Layout-Label-example-by-Necolatis.png|thumb|Canvas demo: Layouts and Labels (by Necolatis)]]<br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. It also assumes you have a Layout item setup and called '''myLayoutItem'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
# create a new layout<br />
var myLayout = canvas.HBoxLayout.new();<br />
# assign it to the Canvas<br />
myCanvas.setLayout(myLayout);<br />
<br />
var label = canvas.gui.widgets.Label.new(root, canvas.style, {wordWrap: 0}); # wordwrap: 0 will disable wordwrapping, to enable it use 1 instead<br />
label.setText("Hello World!");<br />
myLayout.addItem(label);<br />
<br />
var label2 = canvas.gui.widgets.Label.new(root, canvas.style, {wordWrap: 0}); # wordwrap: 0 will disable wordwrapping, to enable it use 1 instead<br />
label2.setText("Hello FlightGear");<br />
myLayout.addItem(label2);<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Adding GUI Buttons (Layouts)==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-demo-layouts-and-buttons-by-Necolatis.png|thumb|Canvas snippet: buttons and layouts (by Necolatis)]] <br />
|<br />
<br />
{{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. It also assumes you have a Layout item setup and called '''myLayoutItem'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
# create a new layout<br />
var myLayout = canvas.HBoxLayout.new();<br />
# assign it to the Canvas<br />
myCanvas.setLayout(myLayout);<br />
<br />
# click button<br />
<br />
var button = canvas.gui.widgets.Button.new(root, canvas.style, {})<br />
.setText("Click on me")<br />
.setFixedSize(75, 25);<br />
<br />
button.listen("clicked", func {<br />
# add code here to react on click on button.<br />
print("Button clicked !");<br />
});<br />
<br />
myLayout.addItem(button);<br />
</syntaxhighlight><br />
<br />
|-<br />
| [[File:Canvas-toggle-button-snippet-by-Necolatis.png|thumb|Canvas toggle button demo by Necolatis]]<br />
| <syntaxhighlight lang="nasal" enclose="div"><br />
# create a new layout<br />
var myLayout = canvas.HBoxLayout.new();<br />
# assign it to the Canvas<br />
myCanvas.setLayout(myLayout);<br />
<br />
var button = canvas.gui.widgets.Button.new(root, canvas.style, {})<br />
.setText("Toggle me")<br />
.setCheckable(1) # this indicates that is should be a toggle button<br />
.setChecked(0) # depressed by default<br />
.setFixedSize(75, 25);<br />
<br />
button.listen("toggled", func (e) {<br />
if( e.detail.checked ) {<br />
# add code here to react on button being depressed.<br />
} else {<br />
# add code here to react on button not being depressed.<br />
}<br />
});<br />
<br />
<br />
myLayout.addItem(button);<br />
<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Canvas Input Dialog ==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
|[[File:Snippets-canvas-input-dialog.png|thumb|Canvas input dialog]]<br />
||<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
# create a new InputDialog with a title, label, and a callback<br />
canvas.InputDialog.getText("Input Dialog Title", "Please enter some text", func(btn,value) {<br />
if (value) gui.popupTip("You entered: "~value);<br />
});<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Canvas ScrollArea ==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
|[[File:Canvas-snippets-scrollArea-demo.png|thumb|Screen shot showing a Canvas ScrollArea populated with different splash screens, loaded from $FG_ROOT/Textures]]<br />
||<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var vbox = canvas.VBoxLayout.new();<br />
myCanvas.setLayout(vbox);<br />
<br />
var scroll = canvas.gui.widgets.ScrollArea.new(root, canvas.style, {size: [96, 128]}).move(20, 100);<br />
vbox.addItem(scroll, 1);<br />
<br />
var scrollContent =<br />
scroll.getContent()<br />
.set("font", "LiberationFonts/LiberationSans-Bold.ttf")<br />
.set("character-size", 16)<br />
.set("alignment", "left-center");<br />
<br />
var list = canvas.VBoxLayout.new();<br />
scroll.setLayout(list);<br />
<br />
for (var i=1;i<=5;i+=1) {<br />
var label = canvas.gui.widgets.Label.new(scrollContent, canvas.style, {wordWrap: 0}); <br />
label.setImage("Textures/Splash"~i~".png");<br />
label.setFixedSize(256,256);<br />
list.addItem(label);<br />
}<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Using Layouts ==<br />
<br />
== Using Styling ==<br />
== Adding a HUD ==<br />
== Adding a 2D Instrument ==<br />
== Adding a 2D Panel ==<br />
== Adding a PFD ==<br />
<br />
== Adding a Failure Mgmt Widget ==<br />
{{Note|This kind of widget will typically be useful for dialogs requiring a method for managing aircraft specific system failures (e.g. an instructor console).}}<br />
<br />
== Adding a MapStructure map to a Canvas ==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code <br />
|-<br />
| [[File:Snippets-canvas-mapstructure-dialog.png|thumb|[[MapStructure]] layers shown in a Canvas GUI dialog]]<br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. Equally, this snippet assumes that your canvas is named '''myCanvas'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
var TestMap = root.createChild("map");<br />
TestMap.setController("Aircraft position");<br />
TestMap.setRange(25); <br />
<br />
TestMap.setTranslation( myCanvas.get("view[0]")/2,<br />
myCanvas.get("view[1]")/2<br />
);<br />
var r = func(name,vis=1,zindex=nil) return caller(0)[0];<br />
<br />
foreach(var type; [r('APT'), r('VOR') ] )<br />
TestMap.addLayer(factory: canvas.SymbolLayer, type_arg: type.name, visible: type.vis, priority: type.zindex,);<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Customizing MapStructure Styling ==<br />
{{See also|Canvas MapStructure#Styling}}<br />
{{WIP}}<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code <br />
|-<br />
| [[File:Layers style change.png|thumb|[[MapStructure]] layers shown in a Canvas GUI dialog. Active VOR and radial in red color, inactive VOR in green color]]<br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. Equally, this snippet assumes that your canvas is named '''myCanvas'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var TestMap = root.createChild("map");<br />
TestMap.setController("Aircraft position");<br />
TestMap.setRange(25); <br />
<br />
TestMap.setTranslation( myCanvas.get("view[0]")/2,<br />
myCanvas.get("view[1]")/2<br />
);<br />
var r = func(name,vis=1,zindex=nil) return caller(0)[0];<br />
var type = r('APT');<br />
var style_apt = {<br />
scale_factor:0.5, # 50 %<br />
color_default:[0,1,0.9], # rgb<br />
line_width:4, # thickness<br />
label_font_color:[0,1,0.9], # rgb<br />
label_font_size:30 # font size<br />
};<br />
TestMap.addLayer(factory: canvas.SymbolLayer, type_arg: type.name, visible: type.vis, priority: type.zindex,style:style_apt);<br />
<br />
var type = r('VOR');<br />
var style_vor = {<br />
scale_factor:0.6,<br />
active_color:[1,0,0],<br />
inactive_color:[0,1,0],<br />
line_width:4<br />
};<br />
TestMap.addLayer(factory: canvas.SymbolLayer, type_arg: type.name, visible: type.vis, priority: type.zindex,style:style_vor);<br />
<br />
### See ...fgdata/Nasal/canvas/map/APT.symbol ...fgdata/Nasal/canvas/map/VOR.style ... for the style variables that can be configured.<br />
<br />
</syntaxhighlight><br />
|}<br />
<br />
== Using MapStructure and Overlays ==<br />
{{FGCquote<br />
|Support for overlays using geo-referenced raster images isn't too well-developed currently, so would need to work with a few hard-coded assumptions (e.g. being specific to a certain raster image and map layout) - but maybe TheTom can provide a few more ideas on how to proceed from here - otherwise, the Map is normally not aware of any non-Map items, i.e. as long as the overlay is added "outside" the Map, it isn't even aware of the raster image - and when it is added as a map element, it would probably be rotated. So there's still some work needed here. But generally, this should work well enough even in its current form (the screen shot is purely based on the Canvas Snippets article, i.e. it just displays a Canvas GUI dialog, adds the downloaded raster image and then adds the MapStructure APS layer - without the Map being aware of the overlay/geo-referencing that is needed currently).<br />
|{{cite web |url=http://forum.flightgear.org/viewtopic.php?p=238316#p238316<br />
|title=<nowiki>Re: Using Canvas for visualizing orbital flights (cont'd PM)</nowiki><br />
|author=<nowiki>Hooray</nowiki><br />
|date=<nowiki>Fri Apr 10</nowiki><br />
}}<br />
}}<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code <br />
|-<br />
| [[File:Canvas-overlay-with-mapstructure.png|thumb|Using the [[MapStructure]] framework in conjunction with raster images as overlays]]<br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. Equally, this snippet assumes that your canvas is named '''myCanvas'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
</syntaxhighlight><br />
|}<br />
<br />
== A simple tile map ==<br />
<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code <br />
|-<br />
| [[File:Canvas - Tile map demo.png|thumb|A simple, canvas based tile map which is centered around the aircraft.]]<br />
| <br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var (width,height) = (768,512);<br />
var tile_size = 256;<br />
<br />
var window = canvas.Window.new([width, height],"dialog")<br />
.set('title', "Tile map demo");<br />
var g = window.getCanvas(1)<br />
.createGroup();<br />
<br />
# Simple user interface (Buttons for zoom and label for displaying it)<br />
var zoom = 10;<br />
var type = "map";<br />
<br />
var ui_root = window.getCanvas().createGroup();<br />
var vbox = canvas.VBoxLayout.new();<br />
window.setLayout(vbox);<br />
<br />
<br />
var button_in = canvas.gui.widgets.Button.new(ui_root, canvas.style, {})<br />
.setText("+")<br />
.listen("clicked", func changeZoom(1));<br />
var button_out = canvas.gui.widgets.Button.new(ui_root, canvas.style, {})<br />
.setText("-")<br />
.listen("clicked", func changeZoom(-1));<br />
button_in.setSizeHint([32, 32]);<br />
button_out.setSizeHint([32, 32]);<br />
<br />
var label_zoom = canvas.gui.widgets.Label.new(ui_root, canvas.style, {});<br />
<br />
var button_box = canvas.HBoxLayout.new();<br />
button_box.addItem(button_in);<br />
button_box.addItem(label_zoom);<br />
button_box.addItem(button_out);<br />
button_box.addStretch(1);<br />
<br />
vbox.addItem(button_box);<br />
vbox.addStretch(1);<br />
<br />
var changeZoom = func(d)<br />
{<br />
zoom = math.max(2, math.min(19, zoom + d));<br />
label_zoom.setText("Zoom " ~ zoom);<br />
updateTiles();<br />
}<br />
<br />
# http://polymaps.org/docs/<br />
# https://github.com/simplegeo/polymaps<br />
# https://github.com/Leaflet/Leaflet<br />
<br />
var maps_base = getprop("/sim/fg-home") ~ '/cache/maps';<br />
<br />
# http://otile1.mqcdn.com/tiles/1.0.0/map<br />
# http://otile1.mqcdn.com/tiles/1.0.0/sat<br />
# (also see http://wiki.openstreetmap.org/wiki/Tile_usage_policy)<br />
var makeUrl =<br />
string.compileTemplate('http://otile1.mqcdn.com/tiles/1.0.0/{type}/{z}/{x}/{y}.jpg');<br />
var makePath =<br />
string.compileTemplate(maps_base ~ '/osm-{type}/{z}/{x}/{y}.jpg');<br />
var num_tiles = [4, 3];<br />
<br />
var center_tile_offset = [<br />
(num_tiles[0] - 1) / 2,<br />
(num_tiles[1] - 1) / 2<br />
];<br />
<br />
# simple aircraft icon at current position/center of the map<br />
g.createChild("path")<br />
.moveTo( tile_size * center_tile_offset[0] - 10,<br />
tile_size * center_tile_offset[1] )<br />
.horiz(20)<br />
.move(-10,-10)<br />
.vert(20)<br />
.set("stroke", "red")<br />
.set("stroke-width", 2)<br />
.set("z-index", 1);<br />
<br />
##<br />
# initialize the map by setting up<br />
# a grid of raster images <br />
<br />
var tiles = setsize([], num_tiles[0]);<br />
for(var x = 0; x < num_tiles[0]; x += 1)<br />
{<br />
tiles[x] = setsize([], num_tiles[1]);<br />
for(var y = 0; y < num_tiles[1]; y += 1)<br />
tiles[x][y] = g.createChild("image", "map-tile");<br />
}<br />
<br />
var last_tile = [-1,-1];<br />
var last_type = type;<br />
<br />
##<br />
# this is the callback that will be regularly called by the timer<br />
# to update the map<br />
var updateTiles = func()<br />
{<br />
# get current position<br />
var lat = getprop('/position/latitude-deg');<br />
var lon = getprop('/position/longitude-deg');<br />
<br />
var n = math.pow(2, zoom);<br />
var offset = [<br />
n * ((lon + 180) / 360) - center_tile_offset[0],<br />
(1 - math.ln(math.tan(lat * math.pi/180) + 1 / math.cos(lat * math.pi/180)) / math.pi) / 2 * n - center_tile_offset[1]<br />
];<br />
var tile_index = [int(offset[0]), int(offset[1])];<br />
<br />
var ox = tile_index[0] - offset[0];<br />
var oy = tile_index[1] - offset[1];<br />
<br />
for(var x = 0; x < num_tiles[0]; x += 1)<br />
for(var y = 0; y < num_tiles[1]; y += 1)<br />
tiles[x][y].setTranslation(int((ox + x) * tile_size + 0.5), int((oy + y) * tile_size + 0.5));<br />
<br />
if( tile_index[0] != last_tile[0]<br />
or tile_index[1] != last_tile[1]<br />
or type != last_type )<br />
{<br />
for(var x = 0; x < num_tiles[0]; x += 1)<br />
for(var y = 0; y < num_tiles[1]; y += 1)<br />
{<br />
var pos = {<br />
z: zoom,<br />
x: int(offset[0] + x),<br />
y: int(offset[1] + y),<br />
type: type<br />
};<br />
<br />
(func {<br />
var img_path = makePath(pos);<br />
var tile = tiles[x][y];<br />
<br />
if( io.stat(img_path) == nil )<br />
{ # image not found, save in $FG_HOME<br />
var img_url = makeUrl(pos);<br />
print('requesting ' ~ img_url);<br />
http.save(img_url, img_path)<br />
.done(func {print('received image ' ~ img_path); tile.set("src", img_path);})<br />
.fail(func (r) print('Failed to get image ' ~ img_path ~ ' ' ~ r.status ~ ': ' ~ r.reason));<br />
}<br />
else # cached image found, reusing<br />
{<br />
print('loading ' ~ img_path);<br />
tile.set("src", img_path)<br />
}<br />
})();<br />
}<br />
<br />
last_tile = tile_index;<br />
last_type = type;<br />
}<br />
};<br />
<br />
##<br />
# set up a timer that will invoke updateTiles at 2-second intervals<br />
var update_timer = maketimer(2, updateTiles);<br />
# actually start the timer<br />
update_timer.start();<br />
<br />
##<br />
# set up default zoom level<br />
changeZoom(0);<br />
<br />
<br />
###<br />
# The following lines were recently added and have not yet been tested<br />
# (if in doubt, remove them)<br />
window.del = func()<br />
{<br />
print("Cleaning up window:",title,"\n");<br />
update_timer.stop();<br />
# explanation for the call() technique at: http://wiki.flightgear.org/Object_oriented_programming_in_Nasal#Making_safer_base-class_calls<br />
call(canvas.Window.del, [], me);<br />
};<br />
<br />
<br />
</syntaxhighlight><br />
|}<br />
<br />
== Adding a NavDisplay ==<br />
<br />
== Adding a CDU ==<br />
<br />
== Adding a Multi-Function Display (MFD) ==</div>Clm76https://wiki.flightgear.org/w/index.php?title=Canvas_snippets&diff=105437Canvas snippets2016-10-29T07:37:33Z<p>Clm76: /* Customizing MapStructure Styling */</p>
<hr />
<div>{{Stub}}<br />
{{-}}<br />
This article is meant to be a collection of self-contained code snippets for doing Nasal/Canvas coding without having to spend too much time working through APIs, documentation and existing code - the idea is to provide snippets that contain comments and explicit assumptions, so that these snippets can be easily adapted by people without necessarily having to be very familiar with Nasal/Canvas coding. In the long term, we're hoping to grow a library of useful code snippets to cover most use-cases, while also covering more complex scenarios, e.g. using Canvas-specific helper frameworks like [[Canvas MapStructure]], the [[NavDisplay]] or the recent CDU work.<br />
<br />
Canvas itself is designed to be front-end agnostic, meaning that it doesn't matter where a Canvas is used/displayed - this is accomplished by so called "placements", which determine where a Canvas texture shown. Thus, the back-end logic can remain the same usually, so that GUI dialogs may show avionics, but also so that avionics may show GUI widgets, which also applies to HUDs, liveries and even placements within the FlightGear scenery.<br />
<br />
We encourage people to use the snippets listed below to get started with Nasal/Canvas coding, but also to provide feedback on extending/improving this article to make it even more accessible and useful. Equally, if you're aware of any Canvas-related efforts that may contain useful code snippets, please do feel free to add those snippets here. Even people who don't have any interest in coding itself are encouraged to get involved by helping test the snippets listed below, for which you only need to the [[Nasal Console]], and while you're at it, please also help provide/update screen shots for each code snippet.<br />
<br />
Contributions added to this article should ideally satisfy some requirements:<br />
* be entirely self-contained<br />
* contain good/clear comments<br />
* have pointers/references to related code/use-cases<br />
* make assumptions explicit<br />
* contain screen shots for each example<br />
* avoid overloaded symbol names to ensure that examples can be merged and adapted easily<br />
* dependencies (svg files, images/textures etc) should always be chosen such that snippets always work using $FG_ROOT<br />
* hard-coded assumptions (e.g. texture dimensions in terms of width/height etc) should be encapsulated using variables<br />
<br />
{{Canvas Navigation}}<br />
<br />
== Creating a standalone Canvas ==<br />
<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[Special:UploadWizard|Upload requested]] || <br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var (width, height) = (512,512);<br />
# Create a standalone Canvas (not attached to any GUI dialog/aircraft etc) <br />
var myCanvas = canvas.new({<br />
"name": "Livery Test", # The name is optional but allow for easier identification<br />
"size": [width, height], # Size of the underlying texture (should be a power of 2, required) [Resolution]<br />
"view": [width, height], # Virtual resolution (Defines the coordinate system of the canvas [Dimensions]<br />
# which will be stretched the size of the texture, required)<br />
"mipmapping": 1 # Enable mipmapping (optional)<br />
});<br />
<br />
# set background color<br />
myCanvas.set("background", canvas.style.getColor("bg_color"));<br />
<br />
# creating the top-level/root group which will contain all other elements/group<br />
var root = myCanvas.createGroup();<br />
<br />
# OPTIONAL: Create a Canvas dialog window to hold the canvas and show that it's working<br />
# the Canvas is now standalone, i.e. continues to live once the dialog is closed!<br />
var window = canvas.Window.new([width,height],"dialog");<br />
window.setCanvas(myCanvas);<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
<br />
== Accessing the Canvas Desktop ==<br />
Sometimes you may want to render to the main screen, without creating a separate Canvas window - this can be accomplished by using the Canvas desktop, note that the following example is fully self-contained, i.e. does not require any code to be added to work:<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[Special:UploadWizard|Upload requested]] || <br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var myNode = canvas.getDesktop().createChild("text")<br />
.setText("Hello Canvas Desktop")<br />
.setFontSize(25, 1.0) # font size (in texels) and font aspect ratio<br />
.setColor(1,0,0,1) # red, fully opaque<br />
.setAlignment("center-center") # how the text is aligned to where you place it<br />
.setTranslation(160, 80); # where to place the text<br />
</syntaxhighlight><br />
|}<br />
<br />
== Creating Tooltips ==<br />
== Creating Popups ==<br />
== Creating a Canvas GUI Window ==<br />
<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Snippets-canvas-dialog.png|left|thumb|This is what the [[Nasal]]/[[Canvas]] snippet will look like once you pasted it into the [[Nasal Console]] and click "Execute".]] || {{Note|This example uses so called method chaining, if you're not familiar with the concept, please see: [[Object_Oriented_Programming_with_Nasal#More_on_methods:_Chaining|Method Chaining]].}}<br />
<br />
{{Canvas Snippets Boilerplate}}<br />
<br />
|}<br />
<br />
== Adding Raster Images ==<br />
<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code <br />
|-<br />
| [[File:Canvas Snippets-raster image.png|thumb|Canvas snippet demonstrating how to load a raster image]] ||<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
# path is relative to $FG_ROOT (base package)<br />
var path = "Textures/Splash1.png";<br />
# create an image child for the texture<br />
var child = root.createChild("image")<br />
.setFile(path)<br />
.setTranslation(100, 10)<br />
.setSize(130, 130);<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Adding Raster Images downloaded on demand ==<br />
<br />
The '''path''' could also just as well be a URL, i.e. a raster image retrieved via http - for example, the following snippet is entirely self-contained and can be pasted into the [[Nasal Console]] and directly executed "as is": <br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-raster-images-via-url.png|thumb|screen shot demonstrating how Nasal and Canvas can be used to display raster images downloaded on demand]] ||<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
# create a new window, dimensions are 400 x 200, using the dialog decoration (i.e. titlebar)<br />
var window = canvas.Window.new([400,200],"dialog");<br />
<br />
# adding a canvas to the new window and setting up background colors/transparency<br />
var myCanvas = window.createCanvas().set("background", canvas.style.getColor("bg_color"));<br />
<br />
# Using specific css colors would also be possible:<br />
# myCanvas.set("background", "#ffaac0");<br />
<br />
# creating the top-level/root group which will contain all other elements/group<br />
var root = myCanvas.createGroup();<br />
<br />
<br />
# path now a URL<br />
var url = "http://www.worldwidetelescope.org/docs/Images/MapOfEarth.jpg";<br />
<br />
# create an image child for the texture<br />
var child=root.createChild("image")<br />
.setFile( url ) <br />
.setTranslation(45,22) # centered, in relation to dialog coordinates<br />
.setSize(310,155); # image dimensions<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Clipping ==<br />
{{Note|{{FGCquote<br />
|1= Scaling or any other type of transformation or changing the coordinates of individual points is definitely more efficient than clipping (which requires to change the OpenGL clip planes for every rendered object with a different clipping rectangle).<br />
|2= {{cite web<br />
| url = http://forum.flightgear.org/viewtopic.php?p=277062#p277062<br />
| title = <nowiki>Re: Space Shuttle</nowiki><br />
| author = <nowiki>TheTom</nowiki><br />
| date = Feb 21st, 2016<br />
| added = Feb 21st, 2016<br />
| script_version = 0.25<br />
}}<br />
}}<br />
}}<br />
I would suggest to refer to api.nas and look for "clip" and/or "rect" - IIRC, you need to set up a clipping rectangle by setting some kind of "clip" property and setting it to a rect value in the form of rect(...)<br />
{{FGCquote<br />
|1= For details, see the clipping example at: [[Canvas Nasal API#set 2]] and [[Canvas Element#clip.28.29]]<br />
|2= {{cite web<br />
| url = http://forum.flightgear.org/viewtopic.php?p=276965#p276965<br />
| title = <nowiki>Re: Space Shuttle</nowiki><br />
| author = <nowiki>Hooray</nowiki><br />
| date = Feb 21st, 2016<br />
| added = Feb 21st, 2016<br />
| script_version = 0.25<br />
}}<br />
}}<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:MapStructure_dialog_with_clipping_and_event_handling_applied.png|thumb]] ||<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
# create a new window, dimensions are 400 x 200, using the dialog decoration (i.e. titlebar)<br />
var window = canvas.Window.new([400,200],"dialog");<br />
<br />
# adding a canvas to the new window and setting up background colors/transparency<br />
var myCanvas = window.createCanvas().set("background", canvas.style.getColor("bg_color"));<br />
<br />
# Using specific css colors would also be possible:<br />
# myCanvas.set("background", "#ffaac0");<br />
<br />
# creating the top-level/root group which will contain all other elements/group<br />
var root = myCanvas.createGroup();<br />
<br />
# create an image child for the texture<br />
var child=root.createChild(".........")<br />
.setFile( url ) <br />
.setTranslation(45,22) # centered, in relation to dialog coordinates<br />
.setSize(310,155); # image dimensions<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Adding OpenVG Paths ==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Openvg-via-canvas.png|thumb|screen shot showing a simple Canvas GUI dialog demonstrating how to use OpenVG-path drawing via Nasal and Canvas]] <br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root'''.}}<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var graph = root.createChild("group");<br />
<br />
var x_axis = graph.createChild("path", "x-axis")<br />
.moveTo(10, height/2)<br />
.lineTo(width-10, height/2)<br />
.setColor(1,0,0)<br />
.setStrokeLineWidth(3);<br />
<br />
var y_axis = graph.createChild("path", "y-axis")<br />
.moveTo(10, 10)<br />
.lineTo(10, height-10)<br />
.setColor(0,0,1)<br />
.setStrokeLineWidth(2);<br />
</syntaxhighlight><br />
|-<br />
|}<br />
<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-openvg-quadTo.png|thumb|screen shot showing a simple Canvas GUI dialog demonstrating how to use OpenVG-path drawing via Nasal and Canvas (Canvas/OpenVG quadTo API for drawing curves)]] <br />
| {{Note|This assumes that you are appending this to the snippet shown above.}}<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
var points = [ 60,height-20, <br />
230,height-100,<br />
];<br />
<br />
var track = graph.createChild("path", "track")<br />
.moveTo(10, height/2)<br />
.quadTo( points )<br />
.setColor(0,1,0)<br />
.setStrokeLineWidth(4);<br />
<br />
<br />
</syntaxhighlight><br />
|-<br />
|}<br />
<br />
<br />
<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-openvg-cubicTo.png|thumb|screen shot showing a simple Canvas GUI dialog demonstrating how to use OpenVG-path drawing via Nasal and Canvas (Canvas/OpenVG cubicTo API for drawing curves)]] <br />
| {{Note|This assumes that you are appending this to the snippet shown above.}}<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var points = [ 60,height-20, <br />
120,height-120,<br />
230,height-100,<br />
];<br />
<br />
var track = graph.createChild("path", "track")<br />
.moveTo(10, height/2)<br />
.cubicTo( points )<br />
.setColor(0,1,0)<br />
.setStrokeLineWidth(4);<br />
<br />
</syntaxhighlight><br />
|-<br />
|}<br />
<br />
== Adding Vector Images ==<br />
<br />
[[Category:Canvas SVG]]<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-svg-support.png|thumb|screen shot demonstrating how the scripted Nasal-based SVG parser can be used to dynamically turn SVG files into OpenVG instructions understood by Canvas]] <br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
# change the background color <br />
myCanvas.set("background", "#ffaac0");<br />
<br />
# creating the top-level/root group which will contain all other elements/group<br />
var root = myCanvas.createGroup();<br />
<br />
var filename = "/Nasal/canvas/map/Images/boeingAirplane.svg";<br />
var svg_symbol = root.createChild('group');<br />
canvas.parsesvg(svg_symbol, filename);<br />
<br />
svg_symbol.setTranslation(width/2,height/2);<br />
<br />
#svg_symbol.setScale(0.2);<br />
#svg_symbol.setRotation(radians)<br />
</syntaxhighlight><br />
|-<br />
|}<br />
<br />
== Using the SymbolCache ==<br />
Whenever a symbol may need to be shown/instanced multiple times (possibly using different styling), it makes sense to use caching - otherwise, identical symbols would be treated as separate OpenVG groups, all of which would need to be rasterized/rendedered separately (i.e. 100 identical symbols would be updated/rendered one by one). <br />
<br />
Typically, a map may display multiple instances of an otherwise identical symbol (think VOR, NDB, DME etc) - equally, a multiplayer map may showing multiple aircraft symbols at the same time. In these cases, it makes sense to use the SymbolCache framework, which will render symbols into a separate Canvas texture and provide a texture map that can be treated as a lookup map, which even supports styling for otherwise identical symbols. To learn more, please refer to [[Canvas MapStructure#The_SymbolCache|SymbolCache]]<br />
... <br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-SymbolCache-Instancing.png|thumb|Screen shot showing a Canvas based GUI dialog that is using the SymbolCache for instancing multiple symbols (including support for styling)]] <br />
| <!--{{Caution|This is currently untested code}}--><br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
##<br />
# this is the function that draws a symbol using OpenVG paths<br />
# it accepts a group to draw to and returns the rendered group <br />
# to the caller<br />
var drawVOR = func(group) {<br />
return group.createChild("path")<br />
.moveTo(-15,0)<br />
.lineTo(-7.5,12.5)<br />
.lineTo(7.5,12.5)<br />
.lineTo(15,0)<br />
.lineTo(7.5,-12.5)<br />
.lineTo(-7.5,-12.5)<br />
.close()<br />
.setStrokeLineWidth(line_width) # style-able<br />
.setColor(color); # style-able<br />
};<br />
<br />
var style = { # styling related attributes (as per the draw* function above)<br />
line_width: 3,<br />
scale_factor: 1,<br />
color: [1,0,0],<br />
};<br />
<br />
# create a new cache entry for the styled symbol<br />
var myCachedSymbol = canvas.StyleableCacheable.new(<br />
name:'myVOR', draw_func: drawVOR,<br />
cache: canvas.SymbolCache32x32, # the cache to be used<br />
draw_mode: canvas.SymbolCache.DRAW_CENTERED,<br />
relevant_keys: ['line_width', 'color'], # styling related attributes<br />
);<br />
<br />
var target = root.createChild('group');<br />
<br />
var x=0;<br />
var y=height/2;<br />
<br />
var xoffset=50;<br />
<br />
# render 5 instanced symbols using the style specified above<br />
for (var i=0;i<5;i+=1) {<br />
# look up the raster image for the symbol<br />
# render it using the passed style and adjust scaling<br />
var instanced = myCachedSymbol.render(target, style)<br />
.setScale(style.scale_factor)<br />
.setTranslation(x+=xoffset,y);<br />
}</syntaxhighlight><br />
|-<br />
|}<br />
<br />
The example shown above uses a fixed symbol/icon cache that is set up while booting Flightgear - sometimes, we may need cache for different purposes. So, let's assume, we need a new/custom cache with a different resolution for each entry in the cache (e.g. 256x256), we can easily accomplish that by setting up a new cache like this: <br />
<syntaxhighlight lang="nasal"><br />
var mySymbolCache256x256 = canvas.SymbolCache.new(1024,256);<br />
</syntaxhighlight><br />
<br />
== Adding Text Elements ==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:CanvasText-Hello-World.png|thumb|Screen shot showing the CanvasText example contributed by Necolatis]]<br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var myText = root.createChild("text")<br />
.setText("Hello world!")<br />
.setFontSize(20, 0.9) # font size (in texels) and font aspect ratio<br />
.setColor(1,0,0,1) # red, fully opaque<br />
.setAlignment("center-center") # how the text is aligned to where you place it<br />
.setTranslation(160, 80); # where to place the text<br />
</syntaxhighlight><br />
|-<br />
|}<br />
<br />
== Adding GUI Labels ==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-Layout-Label-example-by-Necolatis.png|thumb|Canvas demo: Layouts and Labels (by Necolatis)]]<br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. It also assumes you have a Layout item setup and called '''myLayoutItem'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
# create a new layout<br />
var myLayout = canvas.HBoxLayout.new();<br />
# assign it to the Canvas<br />
myCanvas.setLayout(myLayout);<br />
<br />
var label = canvas.gui.widgets.Label.new(root, canvas.style, {wordWrap: 0}); # wordwrap: 0 will disable wordwrapping, to enable it use 1 instead<br />
label.setText("Hello World!");<br />
myLayout.addItem(label);<br />
<br />
var label2 = canvas.gui.widgets.Label.new(root, canvas.style, {wordWrap: 0}); # wordwrap: 0 will disable wordwrapping, to enable it use 1 instead<br />
label2.setText("Hello FlightGear");<br />
myLayout.addItem(label2);<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Adding GUI Buttons (Layouts)==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-demo-layouts-and-buttons-by-Necolatis.png|thumb|Canvas snippet: buttons and layouts (by Necolatis)]] <br />
|<br />
<br />
{{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. It also assumes you have a Layout item setup and called '''myLayoutItem'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
# create a new layout<br />
var myLayout = canvas.HBoxLayout.new();<br />
# assign it to the Canvas<br />
myCanvas.setLayout(myLayout);<br />
<br />
# click button<br />
<br />
var button = canvas.gui.widgets.Button.new(root, canvas.style, {})<br />
.setText("Click on me")<br />
.setFixedSize(75, 25);<br />
<br />
button.listen("clicked", func {<br />
# add code here to react on click on button.<br />
print("Button clicked !");<br />
});<br />
<br />
myLayout.addItem(button);<br />
</syntaxhighlight><br />
<br />
|-<br />
| [[File:Canvas-toggle-button-snippet-by-Necolatis.png|thumb|Canvas toggle button demo by Necolatis]]<br />
| <syntaxhighlight lang="nasal" enclose="div"><br />
# create a new layout<br />
var myLayout = canvas.HBoxLayout.new();<br />
# assign it to the Canvas<br />
myCanvas.setLayout(myLayout);<br />
<br />
var button = canvas.gui.widgets.Button.new(root, canvas.style, {})<br />
.setText("Toggle me")<br />
.setCheckable(1) # this indicates that is should be a toggle button<br />
.setChecked(0) # depressed by default<br />
.setFixedSize(75, 25);<br />
<br />
button.listen("toggled", func (e) {<br />
if( e.detail.checked ) {<br />
# add code here to react on button being depressed.<br />
} else {<br />
# add code here to react on button not being depressed.<br />
}<br />
});<br />
<br />
<br />
myLayout.addItem(button);<br />
<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Canvas Input Dialog ==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
|[[File:Snippets-canvas-input-dialog.png|thumb|Canvas input dialog]]<br />
||<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
# create a new InputDialog with a title, label, and a callback<br />
canvas.InputDialog.getText("Input Dialog Title", "Please enter some text", func(btn,value) {<br />
if (value) gui.popupTip("You entered: "~value);<br />
});<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Canvas ScrollArea ==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
|[[File:Canvas-snippets-scrollArea-demo.png|thumb|Screen shot showing a Canvas ScrollArea populated with different splash screens, loaded from $FG_ROOT/Textures]]<br />
||<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var vbox = canvas.VBoxLayout.new();<br />
myCanvas.setLayout(vbox);<br />
<br />
var scroll = canvas.gui.widgets.ScrollArea.new(root, canvas.style, {size: [96, 128]}).move(20, 100);<br />
vbox.addItem(scroll, 1);<br />
<br />
var scrollContent =<br />
scroll.getContent()<br />
.set("font", "LiberationFonts/LiberationSans-Bold.ttf")<br />
.set("character-size", 16)<br />
.set("alignment", "left-center");<br />
<br />
var list = canvas.VBoxLayout.new();<br />
scroll.setLayout(list);<br />
<br />
for (var i=1;i<=5;i+=1) {<br />
var label = canvas.gui.widgets.Label.new(scrollContent, canvas.style, {wordWrap: 0}); <br />
label.setImage("Textures/Splash"~i~".png");<br />
label.setFixedSize(256,256);<br />
list.addItem(label);<br />
}<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Using Layouts ==<br />
<br />
== Using Styling ==<br />
== Adding a HUD ==<br />
== Adding a 2D Instrument ==<br />
== Adding a 2D Panel ==<br />
== Adding a PFD ==<br />
<br />
== Adding a Failure Mgmt Widget ==<br />
{{Note|This kind of widget will typically be useful for dialogs requiring a method for managing aircraft specific system failures (e.g. an instructor console).}}<br />
<br />
== Adding a MapStructure map to a Canvas ==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code <br />
|-<br />
| [[File:Snippets-canvas-mapstructure-dialog.png|thumb|[[MapStructure]] layers shown in a Canvas GUI dialog]]<br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. Equally, this snippet assumes that your canvas is named '''myCanvas'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
var TestMap = root.createChild("map");<br />
TestMap.setController("Aircraft position");<br />
TestMap.setRange(25); <br />
<br />
TestMap.setTranslation( myCanvas.get("view[0]")/2,<br />
myCanvas.get("view[1]")/2<br />
);<br />
var r = func(name,vis=1,zindex=nil) return caller(0)[0];<br />
<br />
foreach(var type; [r('APT'), r('VOR') ] )<br />
TestMap.addLayer(factory: canvas.SymbolLayer, type_arg: type.name, visible: type.vis, priority: type.zindex,);<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Customizing MapStructure Styling ==<br />
{{See also|Canvas MapStructure#Styling}}<br />
{{WIP}}<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code <br />
|-<br />
| [[File:Layers style change.png|thumb|[[MapStructure]] layers shown in a Canvas GUI dialog. Active VOR and radial in red color, inactive VOR in green color]]<br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. Equally, this snippet assumes that your canvas is named '''myCanvas'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var TestMap = root.createChild("map");<br />
TestMap.setController("Aircraft position");<br />
TestMap.setRange(25); <br />
<br />
TestMap.setTranslation( myCanvas.get("view[0]")/2,<br />
myCanvas.get("view[1]")/2<br />
);<br />
var r = func(name,vis=1,zindex=nil) return caller(0)[0];<br />
var type = r('APT');<br />
var style_apt = {<br />
scale_factor:0.5, # 50 %<br />
color_default:[0,1,0.9], # rgb<br />
line_width:4, # thickness<br />
label_font_color:[0,1,0.9], # rgb<br />
label_font_size:30 # font size<br />
};<br />
TestMap.addLayer(factory: canvas.SymbolLayer, type_arg: type.name, visible: type.vis, priority: type.zindex,style:style_apt);<br />
<br />
var type = r('VOR');<br />
var style_vor = {<br />
scale_factor:0.6,<br />
active_color:[1,0,0],<br />
inactive_color:[0,1,0],<br />
line_width:4,<br />
};<br />
TestMap.addLayer(factory: canvas.SymbolLayer, type_arg: type.name, visible: type.vis, priority: type.zindex,style:style_vor);<br />
<br />
### See ...fgdata/Nasal/canvas/map/APT.symbol ...fgdata/Nasal/canvas/map/VOR.style ... for the style variables that can be configured.<br />
<br />
</syntaxhighlight><br />
|}<br />
<br />
== Using MapStructure and Overlays ==<br />
{{FGCquote<br />
|Support for overlays using geo-referenced raster images isn't too well-developed currently, so would need to work with a few hard-coded assumptions (e.g. being specific to a certain raster image and map layout) - but maybe TheTom can provide a few more ideas on how to proceed from here - otherwise, the Map is normally not aware of any non-Map items, i.e. as long as the overlay is added "outside" the Map, it isn't even aware of the raster image - and when it is added as a map element, it would probably be rotated. So there's still some work needed here. But generally, this should work well enough even in its current form (the screen shot is purely based on the Canvas Snippets article, i.e. it just displays a Canvas GUI dialog, adds the downloaded raster image and then adds the MapStructure APS layer - without the Map being aware of the overlay/geo-referencing that is needed currently).<br />
|{{cite web |url=http://forum.flightgear.org/viewtopic.php?p=238316#p238316<br />
|title=<nowiki>Re: Using Canvas for visualizing orbital flights (cont'd PM)</nowiki><br />
|author=<nowiki>Hooray</nowiki><br />
|date=<nowiki>Fri Apr 10</nowiki><br />
}}<br />
}}<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code <br />
|-<br />
| [[File:Canvas-overlay-with-mapstructure.png|thumb|Using the [[MapStructure]] framework in conjunction with raster images as overlays]]<br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. Equally, this snippet assumes that your canvas is named '''myCanvas'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
</syntaxhighlight><br />
|}<br />
<br />
== A simple tile map ==<br />
<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code <br />
|-<br />
| [[File:Canvas - Tile map demo.png|thumb|A simple, canvas based tile map which is centered around the aircraft.]]<br />
| <br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var (width,height) = (768,512);<br />
var tile_size = 256;<br />
<br />
var window = canvas.Window.new([width, height],"dialog")<br />
.set('title', "Tile map demo");<br />
var g = window.getCanvas(1)<br />
.createGroup();<br />
<br />
# Simple user interface (Buttons for zoom and label for displaying it)<br />
var zoom = 10;<br />
var type = "map";<br />
<br />
var ui_root = window.getCanvas().createGroup();<br />
var vbox = canvas.VBoxLayout.new();<br />
window.setLayout(vbox);<br />
<br />
<br />
var button_in = canvas.gui.widgets.Button.new(ui_root, canvas.style, {})<br />
.setText("+")<br />
.listen("clicked", func changeZoom(1));<br />
var button_out = canvas.gui.widgets.Button.new(ui_root, canvas.style, {})<br />
.setText("-")<br />
.listen("clicked", func changeZoom(-1));<br />
button_in.setSizeHint([32, 32]);<br />
button_out.setSizeHint([32, 32]);<br />
<br />
var label_zoom = canvas.gui.widgets.Label.new(ui_root, canvas.style, {});<br />
<br />
var button_box = canvas.HBoxLayout.new();<br />
button_box.addItem(button_in);<br />
button_box.addItem(label_zoom);<br />
button_box.addItem(button_out);<br />
button_box.addStretch(1);<br />
<br />
vbox.addItem(button_box);<br />
vbox.addStretch(1);<br />
<br />
var changeZoom = func(d)<br />
{<br />
zoom = math.max(2, math.min(19, zoom + d));<br />
label_zoom.setText("Zoom " ~ zoom);<br />
updateTiles();<br />
}<br />
<br />
# http://polymaps.org/docs/<br />
# https://github.com/simplegeo/polymaps<br />
# https://github.com/Leaflet/Leaflet<br />
<br />
var maps_base = getprop("/sim/fg-home") ~ '/cache/maps';<br />
<br />
# http://otile1.mqcdn.com/tiles/1.0.0/map<br />
# http://otile1.mqcdn.com/tiles/1.0.0/sat<br />
# (also see http://wiki.openstreetmap.org/wiki/Tile_usage_policy)<br />
var makeUrl =<br />
string.compileTemplate('http://otile1.mqcdn.com/tiles/1.0.0/{type}/{z}/{x}/{y}.jpg');<br />
var makePath =<br />
string.compileTemplate(maps_base ~ '/osm-{type}/{z}/{x}/{y}.jpg');<br />
var num_tiles = [4, 3];<br />
<br />
var center_tile_offset = [<br />
(num_tiles[0] - 1) / 2,<br />
(num_tiles[1] - 1) / 2<br />
];<br />
<br />
# simple aircraft icon at current position/center of the map<br />
g.createChild("path")<br />
.moveTo( tile_size * center_tile_offset[0] - 10,<br />
tile_size * center_tile_offset[1] )<br />
.horiz(20)<br />
.move(-10,-10)<br />
.vert(20)<br />
.set("stroke", "red")<br />
.set("stroke-width", 2)<br />
.set("z-index", 1);<br />
<br />
##<br />
# initialize the map by setting up<br />
# a grid of raster images <br />
<br />
var tiles = setsize([], num_tiles[0]);<br />
for(var x = 0; x < num_tiles[0]; x += 1)<br />
{<br />
tiles[x] = setsize([], num_tiles[1]);<br />
for(var y = 0; y < num_tiles[1]; y += 1)<br />
tiles[x][y] = g.createChild("image", "map-tile");<br />
}<br />
<br />
var last_tile = [-1,-1];<br />
var last_type = type;<br />
<br />
##<br />
# this is the callback that will be regularly called by the timer<br />
# to update the map<br />
var updateTiles = func()<br />
{<br />
# get current position<br />
var lat = getprop('/position/latitude-deg');<br />
var lon = getprop('/position/longitude-deg');<br />
<br />
var n = math.pow(2, zoom);<br />
var offset = [<br />
n * ((lon + 180) / 360) - center_tile_offset[0],<br />
(1 - math.ln(math.tan(lat * math.pi/180) + 1 / math.cos(lat * math.pi/180)) / math.pi) / 2 * n - center_tile_offset[1]<br />
];<br />
var tile_index = [int(offset[0]), int(offset[1])];<br />
<br />
var ox = tile_index[0] - offset[0];<br />
var oy = tile_index[1] - offset[1];<br />
<br />
for(var x = 0; x < num_tiles[0]; x += 1)<br />
for(var y = 0; y < num_tiles[1]; y += 1)<br />
tiles[x][y].setTranslation(int((ox + x) * tile_size + 0.5), int((oy + y) * tile_size + 0.5));<br />
<br />
if( tile_index[0] != last_tile[0]<br />
or tile_index[1] != last_tile[1]<br />
or type != last_type )<br />
{<br />
for(var x = 0; x < num_tiles[0]; x += 1)<br />
for(var y = 0; y < num_tiles[1]; y += 1)<br />
{<br />
var pos = {<br />
z: zoom,<br />
x: int(offset[0] + x),<br />
y: int(offset[1] + y),<br />
type: type<br />
};<br />
<br />
(func {<br />
var img_path = makePath(pos);<br />
var tile = tiles[x][y];<br />
<br />
if( io.stat(img_path) == nil )<br />
{ # image not found, save in $FG_HOME<br />
var img_url = makeUrl(pos);<br />
print('requesting ' ~ img_url);<br />
http.save(img_url, img_path)<br />
.done(func {print('received image ' ~ img_path); tile.set("src", img_path);})<br />
.fail(func (r) print('Failed to get image ' ~ img_path ~ ' ' ~ r.status ~ ': ' ~ r.reason));<br />
}<br />
else # cached image found, reusing<br />
{<br />
print('loading ' ~ img_path);<br />
tile.set("src", img_path)<br />
}<br />
})();<br />
}<br />
<br />
last_tile = tile_index;<br />
last_type = type;<br />
}<br />
};<br />
<br />
##<br />
# set up a timer that will invoke updateTiles at 2-second intervals<br />
var update_timer = maketimer(2, updateTiles);<br />
# actually start the timer<br />
update_timer.start();<br />
<br />
##<br />
# set up default zoom level<br />
changeZoom(0);<br />
<br />
<br />
###<br />
# The following lines were recently added and have not yet been tested<br />
# (if in doubt, remove them)<br />
window.del = func()<br />
{<br />
print("Cleaning up window:",title,"\n");<br />
update_timer.stop();<br />
# explanation for the call() technique at: http://wiki.flightgear.org/Object_oriented_programming_in_Nasal#Making_safer_base-class_calls<br />
call(canvas.Window.del, [], me);<br />
};<br />
<br />
<br />
</syntaxhighlight><br />
|}<br />
<br />
== Adding a NavDisplay ==<br />
<br />
== Adding a CDU ==<br />
<br />
== Adding a Multi-Function Display (MFD) ==</div>Clm76https://wiki.flightgear.org/w/index.php?title=Canvas_snippets&diff=105436Canvas snippets2016-10-29T07:35:12Z<p>Clm76: /* Customizing MapStructure Styling */</p>
<hr />
<div>{{Stub}}<br />
{{-}}<br />
This article is meant to be a collection of self-contained code snippets for doing Nasal/Canvas coding without having to spend too much time working through APIs, documentation and existing code - the idea is to provide snippets that contain comments and explicit assumptions, so that these snippets can be easily adapted by people without necessarily having to be very familiar with Nasal/Canvas coding. In the long term, we're hoping to grow a library of useful code snippets to cover most use-cases, while also covering more complex scenarios, e.g. using Canvas-specific helper frameworks like [[Canvas MapStructure]], the [[NavDisplay]] or the recent CDU work.<br />
<br />
Canvas itself is designed to be front-end agnostic, meaning that it doesn't matter where a Canvas is used/displayed - this is accomplished by so called "placements", which determine where a Canvas texture shown. Thus, the back-end logic can remain the same usually, so that GUI dialogs may show avionics, but also so that avionics may show GUI widgets, which also applies to HUDs, liveries and even placements within the FlightGear scenery.<br />
<br />
We encourage people to use the snippets listed below to get started with Nasal/Canvas coding, but also to provide feedback on extending/improving this article to make it even more accessible and useful. Equally, if you're aware of any Canvas-related efforts that may contain useful code snippets, please do feel free to add those snippets here. Even people who don't have any interest in coding itself are encouraged to get involved by helping test the snippets listed below, for which you only need to the [[Nasal Console]], and while you're at it, please also help provide/update screen shots for each code snippet.<br />
<br />
Contributions added to this article should ideally satisfy some requirements:<br />
* be entirely self-contained<br />
* contain good/clear comments<br />
* have pointers/references to related code/use-cases<br />
* make assumptions explicit<br />
* contain screen shots for each example<br />
* avoid overloaded symbol names to ensure that examples can be merged and adapted easily<br />
* dependencies (svg files, images/textures etc) should always be chosen such that snippets always work using $FG_ROOT<br />
* hard-coded assumptions (e.g. texture dimensions in terms of width/height etc) should be encapsulated using variables<br />
<br />
{{Canvas Navigation}}<br />
<br />
== Creating a standalone Canvas ==<br />
<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[Special:UploadWizard|Upload requested]] || <br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var (width, height) = (512,512);<br />
# Create a standalone Canvas (not attached to any GUI dialog/aircraft etc) <br />
var myCanvas = canvas.new({<br />
"name": "Livery Test", # The name is optional but allow for easier identification<br />
"size": [width, height], # Size of the underlying texture (should be a power of 2, required) [Resolution]<br />
"view": [width, height], # Virtual resolution (Defines the coordinate system of the canvas [Dimensions]<br />
# which will be stretched the size of the texture, required)<br />
"mipmapping": 1 # Enable mipmapping (optional)<br />
});<br />
<br />
# set background color<br />
myCanvas.set("background", canvas.style.getColor("bg_color"));<br />
<br />
# creating the top-level/root group which will contain all other elements/group<br />
var root = myCanvas.createGroup();<br />
<br />
# OPTIONAL: Create a Canvas dialog window to hold the canvas and show that it's working<br />
# the Canvas is now standalone, i.e. continues to live once the dialog is closed!<br />
var window = canvas.Window.new([width,height],"dialog");<br />
window.setCanvas(myCanvas);<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
<br />
== Accessing the Canvas Desktop ==<br />
Sometimes you may want to render to the main screen, without creating a separate Canvas window - this can be accomplished by using the Canvas desktop, note that the following example is fully self-contained, i.e. does not require any code to be added to work:<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[Special:UploadWizard|Upload requested]] || <br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var myNode = canvas.getDesktop().createChild("text")<br />
.setText("Hello Canvas Desktop")<br />
.setFontSize(25, 1.0) # font size (in texels) and font aspect ratio<br />
.setColor(1,0,0,1) # red, fully opaque<br />
.setAlignment("center-center") # how the text is aligned to where you place it<br />
.setTranslation(160, 80); # where to place the text<br />
</syntaxhighlight><br />
|}<br />
<br />
== Creating Tooltips ==<br />
== Creating Popups ==<br />
== Creating a Canvas GUI Window ==<br />
<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Snippets-canvas-dialog.png|left|thumb|This is what the [[Nasal]]/[[Canvas]] snippet will look like once you pasted it into the [[Nasal Console]] and click "Execute".]] || {{Note|This example uses so called method chaining, if you're not familiar with the concept, please see: [[Object_Oriented_Programming_with_Nasal#More_on_methods:_Chaining|Method Chaining]].}}<br />
<br />
{{Canvas Snippets Boilerplate}}<br />
<br />
|}<br />
<br />
== Adding Raster Images ==<br />
<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code <br />
|-<br />
| [[File:Canvas Snippets-raster image.png|thumb|Canvas snippet demonstrating how to load a raster image]] ||<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
# path is relative to $FG_ROOT (base package)<br />
var path = "Textures/Splash1.png";<br />
# create an image child for the texture<br />
var child = root.createChild("image")<br />
.setFile(path)<br />
.setTranslation(100, 10)<br />
.setSize(130, 130);<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Adding Raster Images downloaded on demand ==<br />
<br />
The '''path''' could also just as well be a URL, i.e. a raster image retrieved via http - for example, the following snippet is entirely self-contained and can be pasted into the [[Nasal Console]] and directly executed "as is": <br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-raster-images-via-url.png|thumb|screen shot demonstrating how Nasal and Canvas can be used to display raster images downloaded on demand]] ||<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
# create a new window, dimensions are 400 x 200, using the dialog decoration (i.e. titlebar)<br />
var window = canvas.Window.new([400,200],"dialog");<br />
<br />
# adding a canvas to the new window and setting up background colors/transparency<br />
var myCanvas = window.createCanvas().set("background", canvas.style.getColor("bg_color"));<br />
<br />
# Using specific css colors would also be possible:<br />
# myCanvas.set("background", "#ffaac0");<br />
<br />
# creating the top-level/root group which will contain all other elements/group<br />
var root = myCanvas.createGroup();<br />
<br />
<br />
# path now a URL<br />
var url = "http://www.worldwidetelescope.org/docs/Images/MapOfEarth.jpg";<br />
<br />
# create an image child for the texture<br />
var child=root.createChild("image")<br />
.setFile( url ) <br />
.setTranslation(45,22) # centered, in relation to dialog coordinates<br />
.setSize(310,155); # image dimensions<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Clipping ==<br />
{{Note|{{FGCquote<br />
|1= Scaling or any other type of transformation or changing the coordinates of individual points is definitely more efficient than clipping (which requires to change the OpenGL clip planes for every rendered object with a different clipping rectangle).<br />
|2= {{cite web<br />
| url = http://forum.flightgear.org/viewtopic.php?p=277062#p277062<br />
| title = <nowiki>Re: Space Shuttle</nowiki><br />
| author = <nowiki>TheTom</nowiki><br />
| date = Feb 21st, 2016<br />
| added = Feb 21st, 2016<br />
| script_version = 0.25<br />
}}<br />
}}<br />
}}<br />
I would suggest to refer to api.nas and look for "clip" and/or "rect" - IIRC, you need to set up a clipping rectangle by setting some kind of "clip" property and setting it to a rect value in the form of rect(...)<br />
{{FGCquote<br />
|1= For details, see the clipping example at: [[Canvas Nasal API#set 2]] and [[Canvas Element#clip.28.29]]<br />
|2= {{cite web<br />
| url = http://forum.flightgear.org/viewtopic.php?p=276965#p276965<br />
| title = <nowiki>Re: Space Shuttle</nowiki><br />
| author = <nowiki>Hooray</nowiki><br />
| date = Feb 21st, 2016<br />
| added = Feb 21st, 2016<br />
| script_version = 0.25<br />
}}<br />
}}<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:MapStructure_dialog_with_clipping_and_event_handling_applied.png|thumb]] ||<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
# create a new window, dimensions are 400 x 200, using the dialog decoration (i.e. titlebar)<br />
var window = canvas.Window.new([400,200],"dialog");<br />
<br />
# adding a canvas to the new window and setting up background colors/transparency<br />
var myCanvas = window.createCanvas().set("background", canvas.style.getColor("bg_color"));<br />
<br />
# Using specific css colors would also be possible:<br />
# myCanvas.set("background", "#ffaac0");<br />
<br />
# creating the top-level/root group which will contain all other elements/group<br />
var root = myCanvas.createGroup();<br />
<br />
# create an image child for the texture<br />
var child=root.createChild(".........")<br />
.setFile( url ) <br />
.setTranslation(45,22) # centered, in relation to dialog coordinates<br />
.setSize(310,155); # image dimensions<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Adding OpenVG Paths ==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Openvg-via-canvas.png|thumb|screen shot showing a simple Canvas GUI dialog demonstrating how to use OpenVG-path drawing via Nasal and Canvas]] <br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root'''.}}<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var graph = root.createChild("group");<br />
<br />
var x_axis = graph.createChild("path", "x-axis")<br />
.moveTo(10, height/2)<br />
.lineTo(width-10, height/2)<br />
.setColor(1,0,0)<br />
.setStrokeLineWidth(3);<br />
<br />
var y_axis = graph.createChild("path", "y-axis")<br />
.moveTo(10, 10)<br />
.lineTo(10, height-10)<br />
.setColor(0,0,1)<br />
.setStrokeLineWidth(2);<br />
</syntaxhighlight><br />
|-<br />
|}<br />
<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-openvg-quadTo.png|thumb|screen shot showing a simple Canvas GUI dialog demonstrating how to use OpenVG-path drawing via Nasal and Canvas (Canvas/OpenVG quadTo API for drawing curves)]] <br />
| {{Note|This assumes that you are appending this to the snippet shown above.}}<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
var points = [ 60,height-20, <br />
230,height-100,<br />
];<br />
<br />
var track = graph.createChild("path", "track")<br />
.moveTo(10, height/2)<br />
.quadTo( points )<br />
.setColor(0,1,0)<br />
.setStrokeLineWidth(4);<br />
<br />
<br />
</syntaxhighlight><br />
|-<br />
|}<br />
<br />
<br />
<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-openvg-cubicTo.png|thumb|screen shot showing a simple Canvas GUI dialog demonstrating how to use OpenVG-path drawing via Nasal and Canvas (Canvas/OpenVG cubicTo API for drawing curves)]] <br />
| {{Note|This assumes that you are appending this to the snippet shown above.}}<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var points = [ 60,height-20, <br />
120,height-120,<br />
230,height-100,<br />
];<br />
<br />
var track = graph.createChild("path", "track")<br />
.moveTo(10, height/2)<br />
.cubicTo( points )<br />
.setColor(0,1,0)<br />
.setStrokeLineWidth(4);<br />
<br />
</syntaxhighlight><br />
|-<br />
|}<br />
<br />
== Adding Vector Images ==<br />
<br />
[[Category:Canvas SVG]]<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-svg-support.png|thumb|screen shot demonstrating how the scripted Nasal-based SVG parser can be used to dynamically turn SVG files into OpenVG instructions understood by Canvas]] <br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
# change the background color <br />
myCanvas.set("background", "#ffaac0");<br />
<br />
# creating the top-level/root group which will contain all other elements/group<br />
var root = myCanvas.createGroup();<br />
<br />
var filename = "/Nasal/canvas/map/Images/boeingAirplane.svg";<br />
var svg_symbol = root.createChild('group');<br />
canvas.parsesvg(svg_symbol, filename);<br />
<br />
svg_symbol.setTranslation(width/2,height/2);<br />
<br />
#svg_symbol.setScale(0.2);<br />
#svg_symbol.setRotation(radians)<br />
</syntaxhighlight><br />
|-<br />
|}<br />
<br />
== Using the SymbolCache ==<br />
Whenever a symbol may need to be shown/instanced multiple times (possibly using different styling), it makes sense to use caching - otherwise, identical symbols would be treated as separate OpenVG groups, all of which would need to be rasterized/rendedered separately (i.e. 100 identical symbols would be updated/rendered one by one). <br />
<br />
Typically, a map may display multiple instances of an otherwise identical symbol (think VOR, NDB, DME etc) - equally, a multiplayer map may showing multiple aircraft symbols at the same time. In these cases, it makes sense to use the SymbolCache framework, which will render symbols into a separate Canvas texture and provide a texture map that can be treated as a lookup map, which even supports styling for otherwise identical symbols. To learn more, please refer to [[Canvas MapStructure#The_SymbolCache|SymbolCache]]<br />
... <br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-SymbolCache-Instancing.png|thumb|Screen shot showing a Canvas based GUI dialog that is using the SymbolCache for instancing multiple symbols (including support for styling)]] <br />
| <!--{{Caution|This is currently untested code}}--><br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
##<br />
# this is the function that draws a symbol using OpenVG paths<br />
# it accepts a group to draw to and returns the rendered group <br />
# to the caller<br />
var drawVOR = func(group) {<br />
return group.createChild("path")<br />
.moveTo(-15,0)<br />
.lineTo(-7.5,12.5)<br />
.lineTo(7.5,12.5)<br />
.lineTo(15,0)<br />
.lineTo(7.5,-12.5)<br />
.lineTo(-7.5,-12.5)<br />
.close()<br />
.setStrokeLineWidth(line_width) # style-able<br />
.setColor(color); # style-able<br />
};<br />
<br />
var style = { # styling related attributes (as per the draw* function above)<br />
line_width: 3,<br />
scale_factor: 1,<br />
color: [1,0,0],<br />
};<br />
<br />
# create a new cache entry for the styled symbol<br />
var myCachedSymbol = canvas.StyleableCacheable.new(<br />
name:'myVOR', draw_func: drawVOR,<br />
cache: canvas.SymbolCache32x32, # the cache to be used<br />
draw_mode: canvas.SymbolCache.DRAW_CENTERED,<br />
relevant_keys: ['line_width', 'color'], # styling related attributes<br />
);<br />
<br />
var target = root.createChild('group');<br />
<br />
var x=0;<br />
var y=height/2;<br />
<br />
var xoffset=50;<br />
<br />
# render 5 instanced symbols using the style specified above<br />
for (var i=0;i<5;i+=1) {<br />
# look up the raster image for the symbol<br />
# render it using the passed style and adjust scaling<br />
var instanced = myCachedSymbol.render(target, style)<br />
.setScale(style.scale_factor)<br />
.setTranslation(x+=xoffset,y);<br />
}</syntaxhighlight><br />
|-<br />
|}<br />
<br />
The example shown above uses a fixed symbol/icon cache that is set up while booting Flightgear - sometimes, we may need cache for different purposes. So, let's assume, we need a new/custom cache with a different resolution for each entry in the cache (e.g. 256x256), we can easily accomplish that by setting up a new cache like this: <br />
<syntaxhighlight lang="nasal"><br />
var mySymbolCache256x256 = canvas.SymbolCache.new(1024,256);<br />
</syntaxhighlight><br />
<br />
== Adding Text Elements ==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:CanvasText-Hello-World.png|thumb|Screen shot showing the CanvasText example contributed by Necolatis]]<br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var myText = root.createChild("text")<br />
.setText("Hello world!")<br />
.setFontSize(20, 0.9) # font size (in texels) and font aspect ratio<br />
.setColor(1,0,0,1) # red, fully opaque<br />
.setAlignment("center-center") # how the text is aligned to where you place it<br />
.setTranslation(160, 80); # where to place the text<br />
</syntaxhighlight><br />
|-<br />
|}<br />
<br />
== Adding GUI Labels ==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-Layout-Label-example-by-Necolatis.png|thumb|Canvas demo: Layouts and Labels (by Necolatis)]]<br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. It also assumes you have a Layout item setup and called '''myLayoutItem'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
# create a new layout<br />
var myLayout = canvas.HBoxLayout.new();<br />
# assign it to the Canvas<br />
myCanvas.setLayout(myLayout);<br />
<br />
var label = canvas.gui.widgets.Label.new(root, canvas.style, {wordWrap: 0}); # wordwrap: 0 will disable wordwrapping, to enable it use 1 instead<br />
label.setText("Hello World!");<br />
myLayout.addItem(label);<br />
<br />
var label2 = canvas.gui.widgets.Label.new(root, canvas.style, {wordWrap: 0}); # wordwrap: 0 will disable wordwrapping, to enable it use 1 instead<br />
label2.setText("Hello FlightGear");<br />
myLayout.addItem(label2);<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Adding GUI Buttons (Layouts)==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-demo-layouts-and-buttons-by-Necolatis.png|thumb|Canvas snippet: buttons and layouts (by Necolatis)]] <br />
|<br />
<br />
{{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. It also assumes you have a Layout item setup and called '''myLayoutItem'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
# create a new layout<br />
var myLayout = canvas.HBoxLayout.new();<br />
# assign it to the Canvas<br />
myCanvas.setLayout(myLayout);<br />
<br />
# click button<br />
<br />
var button = canvas.gui.widgets.Button.new(root, canvas.style, {})<br />
.setText("Click on me")<br />
.setFixedSize(75, 25);<br />
<br />
button.listen("clicked", func {<br />
# add code here to react on click on button.<br />
print("Button clicked !");<br />
});<br />
<br />
myLayout.addItem(button);<br />
</syntaxhighlight><br />
<br />
|-<br />
| [[File:Canvas-toggle-button-snippet-by-Necolatis.png|thumb|Canvas toggle button demo by Necolatis]]<br />
| <syntaxhighlight lang="nasal" enclose="div"><br />
# create a new layout<br />
var myLayout = canvas.HBoxLayout.new();<br />
# assign it to the Canvas<br />
myCanvas.setLayout(myLayout);<br />
<br />
var button = canvas.gui.widgets.Button.new(root, canvas.style, {})<br />
.setText("Toggle me")<br />
.setCheckable(1) # this indicates that is should be a toggle button<br />
.setChecked(0) # depressed by default<br />
.setFixedSize(75, 25);<br />
<br />
button.listen("toggled", func (e) {<br />
if( e.detail.checked ) {<br />
# add code here to react on button being depressed.<br />
} else {<br />
# add code here to react on button not being depressed.<br />
}<br />
});<br />
<br />
<br />
myLayout.addItem(button);<br />
<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Canvas Input Dialog ==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
|[[File:Snippets-canvas-input-dialog.png|thumb|Canvas input dialog]]<br />
||<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
# create a new InputDialog with a title, label, and a callback<br />
canvas.InputDialog.getText("Input Dialog Title", "Please enter some text", func(btn,value) {<br />
if (value) gui.popupTip("You entered: "~value);<br />
});<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Canvas ScrollArea ==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
|[[File:Canvas-snippets-scrollArea-demo.png|thumb|Screen shot showing a Canvas ScrollArea populated with different splash screens, loaded from $FG_ROOT/Textures]]<br />
||<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var vbox = canvas.VBoxLayout.new();<br />
myCanvas.setLayout(vbox);<br />
<br />
var scroll = canvas.gui.widgets.ScrollArea.new(root, canvas.style, {size: [96, 128]}).move(20, 100);<br />
vbox.addItem(scroll, 1);<br />
<br />
var scrollContent =<br />
scroll.getContent()<br />
.set("font", "LiberationFonts/LiberationSans-Bold.ttf")<br />
.set("character-size", 16)<br />
.set("alignment", "left-center");<br />
<br />
var list = canvas.VBoxLayout.new();<br />
scroll.setLayout(list);<br />
<br />
for (var i=1;i<=5;i+=1) {<br />
var label = canvas.gui.widgets.Label.new(scrollContent, canvas.style, {wordWrap: 0}); <br />
label.setImage("Textures/Splash"~i~".png");<br />
label.setFixedSize(256,256);<br />
list.addItem(label);<br />
}<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Using Layouts ==<br />
<br />
== Using Styling ==<br />
== Adding a HUD ==<br />
== Adding a 2D Instrument ==<br />
== Adding a 2D Panel ==<br />
== Adding a PFD ==<br />
<br />
== Adding a Failure Mgmt Widget ==<br />
{{Note|This kind of widget will typically be useful for dialogs requiring a method for managing aircraft specific system failures (e.g. an instructor console).}}<br />
<br />
== Adding a MapStructure map to a Canvas ==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code <br />
|-<br />
| [[File:Snippets-canvas-mapstructure-dialog.png|thumb|[[MapStructure]] layers shown in a Canvas GUI dialog]]<br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. Equally, this snippet assumes that your canvas is named '''myCanvas'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
var TestMap = root.createChild("map");<br />
TestMap.setController("Aircraft position");<br />
TestMap.setRange(25); <br />
<br />
TestMap.setTranslation( myCanvas.get("view[0]")/2,<br />
myCanvas.get("view[1]")/2<br />
);<br />
var r = func(name,vis=1,zindex=nil) return caller(0)[0];<br />
<br />
foreach(var type; [r('APT'), r('VOR') ] )<br />
TestMap.addLayer(factory: canvas.SymbolLayer, type_arg: type.name, visible: type.vis, priority: type.zindex,);<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Customizing MapStructure Styling ==<br />
{{See also|Canvas MapStructure#Styling}}<br />
{{WIP}}<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code <br />
|-<br />
| [[File:Layers style change.png|thumb|[[MapStructure]] layers shown in a Canvas GUI dialog]]<br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. Equally, this snippet assumes that your canvas is named '''myCanvas'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var TestMap = root.createChild("map");<br />
TestMap.setController("Aircraft position");<br />
TestMap.setRange(25); <br />
<br />
TestMap.setTranslation( myCanvas.get("view[0]")/2,<br />
myCanvas.get("view[1]")/2<br />
);<br />
var r = func(name,vis=1,zindex=nil) return caller(0)[0];<br />
var type = r('APT');<br />
var style_apt = {<br />
scale_factor:0.5, # 50 %<br />
color_default:[0,1,0.9], # rgb<br />
line_width:4, # thickness<br />
label_font_color:[0,1,0.9], # rgb<br />
label_font_size:30 # font size<br />
};<br />
TestMap.addLayer(factory: canvas.SymbolLayer, type_arg: type.name, visible: type.vis, priority: type.zindex,style:style_apt);<br />
<br />
var type = r('VOR');<br />
var style_vor = {<br />
scale_factor:0.6,<br />
active_color:[1,0,0],<br />
inactive_color:[0,1,0],<br />
line_width:4,<br />
};<br />
TestMap.addLayer(factory: canvas.SymbolLayer, type_arg: type.name, visible: type.vis, priority: type.zindex,style:style_vor);<br />
<br />
### See ...fgdata/Nasal/canvas/map/APT.symbol ...fgdata/Nasal/canvas/map/VOR.style ... for the style variables that can be configured.<br />
<br />
</syntaxhighlight><br />
|}<br />
<br />
== Using MapStructure and Overlays ==<br />
{{FGCquote<br />
|Support for overlays using geo-referenced raster images isn't too well-developed currently, so would need to work with a few hard-coded assumptions (e.g. being specific to a certain raster image and map layout) - but maybe TheTom can provide a few more ideas on how to proceed from here - otherwise, the Map is normally not aware of any non-Map items, i.e. as long as the overlay is added "outside" the Map, it isn't even aware of the raster image - and when it is added as a map element, it would probably be rotated. So there's still some work needed here. But generally, this should work well enough even in its current form (the screen shot is purely based on the Canvas Snippets article, i.e. it just displays a Canvas GUI dialog, adds the downloaded raster image and then adds the MapStructure APS layer - without the Map being aware of the overlay/geo-referencing that is needed currently).<br />
|{{cite web |url=http://forum.flightgear.org/viewtopic.php?p=238316#p238316<br />
|title=<nowiki>Re: Using Canvas for visualizing orbital flights (cont'd PM)</nowiki><br />
|author=<nowiki>Hooray</nowiki><br />
|date=<nowiki>Fri Apr 10</nowiki><br />
}}<br />
}}<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code <br />
|-<br />
| [[File:Canvas-overlay-with-mapstructure.png|thumb|Using the [[MapStructure]] framework in conjunction with raster images as overlays]]<br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. Equally, this snippet assumes that your canvas is named '''myCanvas'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
</syntaxhighlight><br />
|}<br />
<br />
== A simple tile map ==<br />
<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code <br />
|-<br />
| [[File:Canvas - Tile map demo.png|thumb|A simple, canvas based tile map which is centered around the aircraft.]]<br />
| <br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var (width,height) = (768,512);<br />
var tile_size = 256;<br />
<br />
var window = canvas.Window.new([width, height],"dialog")<br />
.set('title', "Tile map demo");<br />
var g = window.getCanvas(1)<br />
.createGroup();<br />
<br />
# Simple user interface (Buttons for zoom and label for displaying it)<br />
var zoom = 10;<br />
var type = "map";<br />
<br />
var ui_root = window.getCanvas().createGroup();<br />
var vbox = canvas.VBoxLayout.new();<br />
window.setLayout(vbox);<br />
<br />
<br />
var button_in = canvas.gui.widgets.Button.new(ui_root, canvas.style, {})<br />
.setText("+")<br />
.listen("clicked", func changeZoom(1));<br />
var button_out = canvas.gui.widgets.Button.new(ui_root, canvas.style, {})<br />
.setText("-")<br />
.listen("clicked", func changeZoom(-1));<br />
button_in.setSizeHint([32, 32]);<br />
button_out.setSizeHint([32, 32]);<br />
<br />
var label_zoom = canvas.gui.widgets.Label.new(ui_root, canvas.style, {});<br />
<br />
var button_box = canvas.HBoxLayout.new();<br />
button_box.addItem(button_in);<br />
button_box.addItem(label_zoom);<br />
button_box.addItem(button_out);<br />
button_box.addStretch(1);<br />
<br />
vbox.addItem(button_box);<br />
vbox.addStretch(1);<br />
<br />
var changeZoom = func(d)<br />
{<br />
zoom = math.max(2, math.min(19, zoom + d));<br />
label_zoom.setText("Zoom " ~ zoom);<br />
updateTiles();<br />
}<br />
<br />
# http://polymaps.org/docs/<br />
# https://github.com/simplegeo/polymaps<br />
# https://github.com/Leaflet/Leaflet<br />
<br />
var maps_base = getprop("/sim/fg-home") ~ '/cache/maps';<br />
<br />
# http://otile1.mqcdn.com/tiles/1.0.0/map<br />
# http://otile1.mqcdn.com/tiles/1.0.0/sat<br />
# (also see http://wiki.openstreetmap.org/wiki/Tile_usage_policy)<br />
var makeUrl =<br />
string.compileTemplate('http://otile1.mqcdn.com/tiles/1.0.0/{type}/{z}/{x}/{y}.jpg');<br />
var makePath =<br />
string.compileTemplate(maps_base ~ '/osm-{type}/{z}/{x}/{y}.jpg');<br />
var num_tiles = [4, 3];<br />
<br />
var center_tile_offset = [<br />
(num_tiles[0] - 1) / 2,<br />
(num_tiles[1] - 1) / 2<br />
];<br />
<br />
# simple aircraft icon at current position/center of the map<br />
g.createChild("path")<br />
.moveTo( tile_size * center_tile_offset[0] - 10,<br />
tile_size * center_tile_offset[1] )<br />
.horiz(20)<br />
.move(-10,-10)<br />
.vert(20)<br />
.set("stroke", "red")<br />
.set("stroke-width", 2)<br />
.set("z-index", 1);<br />
<br />
##<br />
# initialize the map by setting up<br />
# a grid of raster images <br />
<br />
var tiles = setsize([], num_tiles[0]);<br />
for(var x = 0; x < num_tiles[0]; x += 1)<br />
{<br />
tiles[x] = setsize([], num_tiles[1]);<br />
for(var y = 0; y < num_tiles[1]; y += 1)<br />
tiles[x][y] = g.createChild("image", "map-tile");<br />
}<br />
<br />
var last_tile = [-1,-1];<br />
var last_type = type;<br />
<br />
##<br />
# this is the callback that will be regularly called by the timer<br />
# to update the map<br />
var updateTiles = func()<br />
{<br />
# get current position<br />
var lat = getprop('/position/latitude-deg');<br />
var lon = getprop('/position/longitude-deg');<br />
<br />
var n = math.pow(2, zoom);<br />
var offset = [<br />
n * ((lon + 180) / 360) - center_tile_offset[0],<br />
(1 - math.ln(math.tan(lat * math.pi/180) + 1 / math.cos(lat * math.pi/180)) / math.pi) / 2 * n - center_tile_offset[1]<br />
];<br />
var tile_index = [int(offset[0]), int(offset[1])];<br />
<br />
var ox = tile_index[0] - offset[0];<br />
var oy = tile_index[1] - offset[1];<br />
<br />
for(var x = 0; x < num_tiles[0]; x += 1)<br />
for(var y = 0; y < num_tiles[1]; y += 1)<br />
tiles[x][y].setTranslation(int((ox + x) * tile_size + 0.5), int((oy + y) * tile_size + 0.5));<br />
<br />
if( tile_index[0] != last_tile[0]<br />
or tile_index[1] != last_tile[1]<br />
or type != last_type )<br />
{<br />
for(var x = 0; x < num_tiles[0]; x += 1)<br />
for(var y = 0; y < num_tiles[1]; y += 1)<br />
{<br />
var pos = {<br />
z: zoom,<br />
x: int(offset[0] + x),<br />
y: int(offset[1] + y),<br />
type: type<br />
};<br />
<br />
(func {<br />
var img_path = makePath(pos);<br />
var tile = tiles[x][y];<br />
<br />
if( io.stat(img_path) == nil )<br />
{ # image not found, save in $FG_HOME<br />
var img_url = makeUrl(pos);<br />
print('requesting ' ~ img_url);<br />
http.save(img_url, img_path)<br />
.done(func {print('received image ' ~ img_path); tile.set("src", img_path);})<br />
.fail(func (r) print('Failed to get image ' ~ img_path ~ ' ' ~ r.status ~ ': ' ~ r.reason));<br />
}<br />
else # cached image found, reusing<br />
{<br />
print('loading ' ~ img_path);<br />
tile.set("src", img_path)<br />
}<br />
})();<br />
}<br />
<br />
last_tile = tile_index;<br />
last_type = type;<br />
}<br />
};<br />
<br />
##<br />
# set up a timer that will invoke updateTiles at 2-second intervals<br />
var update_timer = maketimer(2, updateTiles);<br />
# actually start the timer<br />
update_timer.start();<br />
<br />
##<br />
# set up default zoom level<br />
changeZoom(0);<br />
<br />
<br />
###<br />
# The following lines were recently added and have not yet been tested<br />
# (if in doubt, remove them)<br />
window.del = func()<br />
{<br />
print("Cleaning up window:",title,"\n");<br />
update_timer.stop();<br />
# explanation for the call() technique at: http://wiki.flightgear.org/Object_oriented_programming_in_Nasal#Making_safer_base-class_calls<br />
call(canvas.Window.del, [], me);<br />
};<br />
<br />
<br />
</syntaxhighlight><br />
|}<br />
<br />
== Adding a NavDisplay ==<br />
<br />
== Adding a CDU ==<br />
<br />
== Adding a Multi-Function Display (MFD) ==</div>Clm76https://wiki.flightgear.org/w/index.php?title=File:Layers_style_change.png&diff=105435File:Layers style change.png2016-10-29T07:31:04Z<p>Clm76: User created page with UploadWizard</p>
<hr />
<div>=={{int:filedesc}}==<br />
{{Information<br />
|description={{en|1=MapStructure layers shown in a canvas GUI dialog}}<br />
|date=2016-10-29<br />
|source={{own}}<br />
|author=[[User:Clm76|Clm76]]<br />
|permission=<br />
|other versions=<br />
}}<br />
<br />
=={{int:license-header}}==<br />
{{self|cc-by-sa-4.0}}</div>Clm76https://wiki.flightgear.org/w/index.php?title=Canvas_snippets&diff=105427Canvas snippets2016-10-28T07:41:34Z<p>Clm76: /* Customizing MapStructure Styling */</p>
<hr />
<div>{{Stub}}<br />
{{-}}<br />
This article is meant to be a collection of self-contained code snippets for doing Nasal/Canvas coding without having to spend too much time working through APIs, documentation and existing code - the idea is to provide snippets that contain comments and explicit assumptions, so that these snippets can be easily adapted by people without necessarily having to be very familiar with Nasal/Canvas coding. In the long term, we're hoping to grow a library of useful code snippets to cover most use-cases, while also covering more complex scenarios, e.g. using Canvas-specific helper frameworks like [[Canvas MapStructure]], the [[NavDisplay]] or the recent CDU work.<br />
<br />
Canvas itself is designed to be front-end agnostic, meaning that it doesn't matter where a Canvas is used/displayed - this is accomplished by so called "placements", which determine where a Canvas texture shown. Thus, the back-end logic can remain the same usually, so that GUI dialogs may show avionics, but also so that avionics may show GUI widgets, which also applies to HUDs, liveries and even placements within the FlightGear scenery.<br />
<br />
We encourage people to use the snippets listed below to get started with Nasal/Canvas coding, but also to provide feedback on extending/improving this article to make it even more accessible and useful. Equally, if you're aware of any Canvas-related efforts that may contain useful code snippets, please do feel free to add those snippets here. Even people who don't have any interest in coding itself are encouraged to get involved by helping test the snippets listed below, for which you only need to the [[Nasal Console]], and while you're at it, please also help provide/update screen shots for each code snippet.<br />
<br />
Contributions added to this article should ideally satisfy some requirements:<br />
* be entirely self-contained<br />
* contain good/clear comments<br />
* have pointers/references to related code/use-cases<br />
* make assumptions explicit<br />
* contain screen shots for each example<br />
* avoid overloaded symbol names to ensure that examples can be merged and adapted easily<br />
* dependencies (svg files, images/textures etc) should always be chosen such that snippets always work using $FG_ROOT<br />
* hard-coded assumptions (e.g. texture dimensions in terms of width/height etc) should be encapsulated using variables<br />
<br />
{{Canvas Navigation}}<br />
<br />
== Creating a standalone Canvas ==<br />
<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[Special:UploadWizard|Upload requested]] || <br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var (width, height) = (512,512);<br />
# Create a standalone Canvas (not attached to any GUI dialog/aircraft etc) <br />
var myCanvas = canvas.new({<br />
"name": "Livery Test", # The name is optional but allow for easier identification<br />
"size": [width, height], # Size of the underlying texture (should be a power of 2, required) [Resolution]<br />
"view": [width, height], # Virtual resolution (Defines the coordinate system of the canvas [Dimensions]<br />
# which will be stretched the size of the texture, required)<br />
"mipmapping": 1 # Enable mipmapping (optional)<br />
});<br />
<br />
# set background color<br />
myCanvas.set("background", canvas.style.getColor("bg_color"));<br />
<br />
# creating the top-level/root group which will contain all other elements/group<br />
var root = myCanvas.createGroup();<br />
<br />
# OPTIONAL: Create a Canvas dialog window to hold the canvas and show that it's working<br />
# the Canvas is now standalone, i.e. continues to live once the dialog is closed!<br />
var window = canvas.Window.new([width,height],"dialog");<br />
window.setCanvas(myCanvas);<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
<br />
== Accessing the Canvas Desktop ==<br />
Sometimes you may want to render to the main screen, without creating a separate Canvas window - this can be accomplished by using the Canvas desktop, note that the following example is fully self-contained, i.e. does not require any code to be added to work:<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[Special:UploadWizard|Upload requested]] || <br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var myNode = canvas.getDesktop().createChild("text")<br />
.setText("Hello Canvas Desktop")<br />
.setFontSize(25, 1.0) # font size (in texels) and font aspect ratio<br />
.setColor(1,0,0,1) # red, fully opaque<br />
.setAlignment("center-center") # how the text is aligned to where you place it<br />
.setTranslation(160, 80); # where to place the text<br />
</syntaxhighlight><br />
|}<br />
<br />
== Creating Tooltips ==<br />
== Creating Popups ==<br />
== Creating a Canvas GUI Window ==<br />
<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Snippets-canvas-dialog.png|left|thumb|This is what the [[Nasal]]/[[Canvas]] snippet will look like once you pasted it into the [[Nasal Console]] and click "Execute".]] || {{Note|This example uses so called method chaining, if you're not familiar with the concept, please see: [[Object_Oriented_Programming_with_Nasal#More_on_methods:_Chaining|Method Chaining]].}}<br />
<br />
{{Canvas Snippets Boilerplate}}<br />
<br />
|}<br />
<br />
== Adding Raster Images ==<br />
<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code <br />
|-<br />
| [[File:Canvas Snippets-raster image.png|thumb|Canvas snippet demonstrating how to load a raster image]] ||<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
# path is relative to $FG_ROOT (base package)<br />
var path = "Textures/Splash1.png";<br />
# create an image child for the texture<br />
var child = root.createChild("image")<br />
.setFile(path)<br />
.setTranslation(100, 10)<br />
.setSize(130, 130);<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Adding Raster Images downloaded on demand ==<br />
<br />
The '''path''' could also just as well be a URL, i.e. a raster image retrieved via http - for example, the following snippet is entirely self-contained and can be pasted into the [[Nasal Console]] and directly executed "as is": <br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-raster-images-via-url.png|thumb|screen shot demonstrating how Nasal and Canvas can be used to display raster images downloaded on demand]] ||<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
# create a new window, dimensions are 400 x 200, using the dialog decoration (i.e. titlebar)<br />
var window = canvas.Window.new([400,200],"dialog");<br />
<br />
# adding a canvas to the new window and setting up background colors/transparency<br />
var myCanvas = window.createCanvas().set("background", canvas.style.getColor("bg_color"));<br />
<br />
# Using specific css colors would also be possible:<br />
# myCanvas.set("background", "#ffaac0");<br />
<br />
# creating the top-level/root group which will contain all other elements/group<br />
var root = myCanvas.createGroup();<br />
<br />
<br />
# path now a URL<br />
var url = "http://www.worldwidetelescope.org/docs/Images/MapOfEarth.jpg";<br />
<br />
# create an image child for the texture<br />
var child=root.createChild("image")<br />
.setFile( url ) <br />
.setTranslation(45,22) # centered, in relation to dialog coordinates<br />
.setSize(310,155); # image dimensions<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Clipping ==<br />
{{Note|{{FGCquote<br />
|1= Scaling or any other type of transformation or changing the coordinates of individual points is definitely more efficient than clipping (which requires to change the OpenGL clip planes for every rendered object with a different clipping rectangle).<br />
|2= {{cite web<br />
| url = http://forum.flightgear.org/viewtopic.php?p=277062#p277062<br />
| title = <nowiki>Re: Space Shuttle</nowiki><br />
| author = <nowiki>TheTom</nowiki><br />
| date = Feb 21st, 2016<br />
| added = Feb 21st, 2016<br />
| script_version = 0.25<br />
}}<br />
}}<br />
}}<br />
I would suggest to refer to api.nas and look for "clip" and/or "rect" - IIRC, you need to set up a clipping rectangle by setting some kind of "clip" property and setting it to a rect value in the form of rect(...)<br />
{{FGCquote<br />
|1= For details, see the clipping example at: [[Canvas Nasal API#set 2]] and [[Canvas Element#clip.28.29]]<br />
|2= {{cite web<br />
| url = http://forum.flightgear.org/viewtopic.php?p=276965#p276965<br />
| title = <nowiki>Re: Space Shuttle</nowiki><br />
| author = <nowiki>Hooray</nowiki><br />
| date = Feb 21st, 2016<br />
| added = Feb 21st, 2016<br />
| script_version = 0.25<br />
}}<br />
}}<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:MapStructure_dialog_with_clipping_and_event_handling_applied.png|thumb]] ||<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
# create a new window, dimensions are 400 x 200, using the dialog decoration (i.e. titlebar)<br />
var window = canvas.Window.new([400,200],"dialog");<br />
<br />
# adding a canvas to the new window and setting up background colors/transparency<br />
var myCanvas = window.createCanvas().set("background", canvas.style.getColor("bg_color"));<br />
<br />
# Using specific css colors would also be possible:<br />
# myCanvas.set("background", "#ffaac0");<br />
<br />
# creating the top-level/root group which will contain all other elements/group<br />
var root = myCanvas.createGroup();<br />
<br />
# create an image child for the texture<br />
var child=root.createChild(".........")<br />
.setFile( url ) <br />
.setTranslation(45,22) # centered, in relation to dialog coordinates<br />
.setSize(310,155); # image dimensions<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Adding OpenVG Paths ==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Openvg-via-canvas.png|thumb|screen shot showing a simple Canvas GUI dialog demonstrating how to use OpenVG-path drawing via Nasal and Canvas]] <br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root'''.}}<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var graph = root.createChild("group");<br />
<br />
var x_axis = graph.createChild("path", "x-axis")<br />
.moveTo(10, height/2)<br />
.lineTo(width-10, height/2)<br />
.setColor(1,0,0)<br />
.setStrokeLineWidth(3);<br />
<br />
var y_axis = graph.createChild("path", "y-axis")<br />
.moveTo(10, 10)<br />
.lineTo(10, height-10)<br />
.setColor(0,0,1)<br />
.setStrokeLineWidth(2);<br />
</syntaxhighlight><br />
|-<br />
|}<br />
<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-openvg-quadTo.png|thumb|screen shot showing a simple Canvas GUI dialog demonstrating how to use OpenVG-path drawing via Nasal and Canvas (Canvas/OpenVG quadTo API for drawing curves)]] <br />
| {{Note|This assumes that you are appending this to the snippet shown above.}}<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
var points = [ 60,height-20, <br />
230,height-100,<br />
];<br />
<br />
var track = graph.createChild("path", "track")<br />
.moveTo(10, height/2)<br />
.quadTo( points )<br />
.setColor(0,1,0)<br />
.setStrokeLineWidth(4);<br />
<br />
<br />
</syntaxhighlight><br />
|-<br />
|}<br />
<br />
<br />
<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-openvg-cubicTo.png|thumb|screen shot showing a simple Canvas GUI dialog demonstrating how to use OpenVG-path drawing via Nasal and Canvas (Canvas/OpenVG cubicTo API for drawing curves)]] <br />
| {{Note|This assumes that you are appending this to the snippet shown above.}}<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var points = [ 60,height-20, <br />
120,height-120,<br />
230,height-100,<br />
];<br />
<br />
var track = graph.createChild("path", "track")<br />
.moveTo(10, height/2)<br />
.cubicTo( points )<br />
.setColor(0,1,0)<br />
.setStrokeLineWidth(4);<br />
<br />
</syntaxhighlight><br />
|-<br />
|}<br />
<br />
== Adding Vector Images ==<br />
<br />
[[Category:Canvas SVG]]<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-svg-support.png|thumb|screen shot demonstrating how the scripted Nasal-based SVG parser can be used to dynamically turn SVG files into OpenVG instructions understood by Canvas]] <br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
# change the background color <br />
myCanvas.set("background", "#ffaac0");<br />
<br />
# creating the top-level/root group which will contain all other elements/group<br />
var root = myCanvas.createGroup();<br />
<br />
var filename = "/Nasal/canvas/map/Images/boeingAirplane.svg";<br />
var svg_symbol = root.createChild('group');<br />
canvas.parsesvg(svg_symbol, filename);<br />
<br />
svg_symbol.setTranslation(width/2,height/2);<br />
<br />
#svg_symbol.setScale(0.2);<br />
#svg_symbol.setRotation(radians)<br />
</syntaxhighlight><br />
|-<br />
|}<br />
<br />
== Using the SymbolCache ==<br />
Whenever a symbol may need to be shown/instanced multiple times (possibly using different styling), it makes sense to use caching - otherwise, identical symbols would be treated as separate OpenVG groups, all of which would need to be rasterized/rendedered separately (i.e. 100 identical symbols would be updated/rendered one by one). <br />
<br />
Typically, a map may display multiple instances of an otherwise identical symbol (think VOR, NDB, DME etc) - equally, a multiplayer map may showing multiple aircraft symbols at the same time. In these cases, it makes sense to use the SymbolCache framework, which will render symbols into a separate Canvas texture and provide a texture map that can be treated as a lookup map, which even supports styling for otherwise identical symbols. To learn more, please refer to [[Canvas MapStructure#The_SymbolCache|SymbolCache]]<br />
... <br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-SymbolCache-Instancing.png|thumb|Screen shot showing a Canvas based GUI dialog that is using the SymbolCache for instancing multiple symbols (including support for styling)]] <br />
| <!--{{Caution|This is currently untested code}}--><br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
##<br />
# this is the function that draws a symbol using OpenVG paths<br />
# it accepts a group to draw to and returns the rendered group <br />
# to the caller<br />
var drawVOR = func(group) {<br />
return group.createChild("path")<br />
.moveTo(-15,0)<br />
.lineTo(-7.5,12.5)<br />
.lineTo(7.5,12.5)<br />
.lineTo(15,0)<br />
.lineTo(7.5,-12.5)<br />
.lineTo(-7.5,-12.5)<br />
.close()<br />
.setStrokeLineWidth(line_width) # style-able<br />
.setColor(color); # style-able<br />
};<br />
<br />
var style = { # styling related attributes (as per the draw* function above)<br />
line_width: 3,<br />
scale_factor: 1,<br />
color: [1,0,0],<br />
};<br />
<br />
# create a new cache entry for the styled symbol<br />
var myCachedSymbol = canvas.StyleableCacheable.new(<br />
name:'myVOR', draw_func: drawVOR,<br />
cache: canvas.SymbolCache32x32, # the cache to be used<br />
draw_mode: canvas.SymbolCache.DRAW_CENTERED,<br />
relevant_keys: ['line_width', 'color'], # styling related attributes<br />
);<br />
<br />
var target = root.createChild('group');<br />
<br />
var x=0;<br />
var y=height/2;<br />
<br />
var xoffset=50;<br />
<br />
# render 5 instanced symbols using the style specified above<br />
for (var i=0;i<5;i+=1) {<br />
# look up the raster image for the symbol<br />
# render it using the passed style and adjust scaling<br />
var instanced = myCachedSymbol.render(target, style)<br />
.setScale(style.scale_factor)<br />
.setTranslation(x+=xoffset,y);<br />
}</syntaxhighlight><br />
|-<br />
|}<br />
<br />
The example shown above uses a fixed symbol/icon cache that is set up while booting Flightgear - sometimes, we may need cache for different purposes. So, let's assume, we need a new/custom cache with a different resolution for each entry in the cache (e.g. 256x256), we can easily accomplish that by setting up a new cache like this: <br />
<syntaxhighlight lang="nasal"><br />
var mySymbolCache256x256 = canvas.SymbolCache.new(1024,256);<br />
</syntaxhighlight><br />
<br />
== Adding Text Elements ==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:CanvasText-Hello-World.png|thumb|Screen shot showing the CanvasText example contributed by Necolatis]]<br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var myText = root.createChild("text")<br />
.setText("Hello world!")<br />
.setFontSize(20, 0.9) # font size (in texels) and font aspect ratio<br />
.setColor(1,0,0,1) # red, fully opaque<br />
.setAlignment("center-center") # how the text is aligned to where you place it<br />
.setTranslation(160, 80); # where to place the text<br />
</syntaxhighlight><br />
|-<br />
|}<br />
<br />
== Adding GUI Labels ==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-Layout-Label-example-by-Necolatis.png|thumb|Canvas demo: Layouts and Labels (by Necolatis)]]<br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. It also assumes you have a Layout item setup and called '''myLayoutItem'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
# create a new layout<br />
var myLayout = canvas.HBoxLayout.new();<br />
# assign it to the Canvas<br />
myCanvas.setLayout(myLayout);<br />
<br />
var label = canvas.gui.widgets.Label.new(root, canvas.style, {wordWrap: 0}); # wordwrap: 0 will disable wordwrapping, to enable it use 1 instead<br />
label.setText("Hello World!");<br />
myLayout.addItem(label);<br />
<br />
var label2 = canvas.gui.widgets.Label.new(root, canvas.style, {wordWrap: 0}); # wordwrap: 0 will disable wordwrapping, to enable it use 1 instead<br />
label2.setText("Hello FlightGear");<br />
myLayout.addItem(label2);<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Adding GUI Buttons (Layouts)==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-demo-layouts-and-buttons-by-Necolatis.png|thumb|Canvas snippet: buttons and layouts (by Necolatis)]] <br />
|<br />
<br />
{{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. It also assumes you have a Layout item setup and called '''myLayoutItem'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
# create a new layout<br />
var myLayout = canvas.HBoxLayout.new();<br />
# assign it to the Canvas<br />
myCanvas.setLayout(myLayout);<br />
<br />
# click button<br />
<br />
var button = canvas.gui.widgets.Button.new(root, canvas.style, {})<br />
.setText("Click on me")<br />
.setFixedSize(75, 25);<br />
<br />
button.listen("clicked", func {<br />
# add code here to react on click on button.<br />
print("Button clicked !");<br />
});<br />
<br />
myLayout.addItem(button);<br />
</syntaxhighlight><br />
<br />
|-<br />
| [[File:Canvas-toggle-button-snippet-by-Necolatis.png|thumb|Canvas toggle button demo by Necolatis]]<br />
| <syntaxhighlight lang="nasal" enclose="div"><br />
# create a new layout<br />
var myLayout = canvas.HBoxLayout.new();<br />
# assign it to the Canvas<br />
myCanvas.setLayout(myLayout);<br />
<br />
var button = canvas.gui.widgets.Button.new(root, canvas.style, {})<br />
.setText("Toggle me")<br />
.setCheckable(1) # this indicates that is should be a toggle button<br />
.setChecked(0) # depressed by default<br />
.setFixedSize(75, 25);<br />
<br />
button.listen("toggled", func (e) {<br />
if( e.detail.checked ) {<br />
# add code here to react on button being depressed.<br />
} else {<br />
# add code here to react on button not being depressed.<br />
}<br />
});<br />
<br />
<br />
myLayout.addItem(button);<br />
<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Canvas Input Dialog ==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
|[[File:Snippets-canvas-input-dialog.png|thumb|Canvas input dialog]]<br />
||<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
# create a new InputDialog with a title, label, and a callback<br />
canvas.InputDialog.getText("Input Dialog Title", "Please enter some text", func(btn,value) {<br />
if (value) gui.popupTip("You entered: "~value);<br />
});<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Canvas ScrollArea ==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
|[[File:Canvas-snippets-scrollArea-demo.png|thumb|Screen shot showing a Canvas ScrollArea populated with different splash screens, loaded from $FG_ROOT/Textures]]<br />
||<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var vbox = canvas.VBoxLayout.new();<br />
myCanvas.setLayout(vbox);<br />
<br />
var scroll = canvas.gui.widgets.ScrollArea.new(root, canvas.style, {size: [96, 128]}).move(20, 100);<br />
vbox.addItem(scroll, 1);<br />
<br />
var scrollContent =<br />
scroll.getContent()<br />
.set("font", "LiberationFonts/LiberationSans-Bold.ttf")<br />
.set("character-size", 16)<br />
.set("alignment", "left-center");<br />
<br />
var list = canvas.VBoxLayout.new();<br />
scroll.setLayout(list);<br />
<br />
for (var i=1;i<=5;i+=1) {<br />
var label = canvas.gui.widgets.Label.new(scrollContent, canvas.style, {wordWrap: 0}); <br />
label.setImage("Textures/Splash"~i~".png");<br />
label.setFixedSize(256,256);<br />
list.addItem(label);<br />
}<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Using Layouts ==<br />
<br />
== Using Styling ==<br />
== Adding a HUD ==<br />
== Adding a 2D Instrument ==<br />
== Adding a 2D Panel ==<br />
== Adding a PFD ==<br />
<br />
== Adding a Failure Mgmt Widget ==<br />
{{Note|This kind of widget will typically be useful for dialogs requiring a method for managing aircraft specific system failures (e.g. an instructor console).}}<br />
<br />
== Adding a MapStructure map to a Canvas ==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code <br />
|-<br />
| [[File:Snippets-canvas-mapstructure-dialog.png|thumb|[[MapStructure]] layers shown in a Canvas GUI dialog]]<br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. Equally, this snippet assumes that your canvas is named '''myCanvas'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
var TestMap = root.createChild("map");<br />
TestMap.setController("Aircraft position");<br />
TestMap.setRange(25); <br />
<br />
TestMap.setTranslation( myCanvas.get("view[0]")/2,<br />
myCanvas.get("view[1]")/2<br />
);<br />
var r = func(name,vis=1,zindex=nil) return caller(0)[0];<br />
<br />
foreach(var type; [r('APT'), r('VOR') ] )<br />
TestMap.addLayer(factory: canvas.SymbolLayer, type_arg: type.name, visible: type.vis, priority: type.zindex,);<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Customizing MapStructure Styling ==<br />
{{See also|Canvas MapStructure#Styling}}<br />
{{WIP}}<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code <br />
|-<br />
| [[File:Snippets-canvas-mapstructure-dialog.png|thumb|[[MapStructure]] layers shown in a Canvas GUI dialog]]<br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. Equally, this snippet assumes that your canvas is named '''myCanvas'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var TestMap = root.createChild("map");<br />
TestMap.setController("Aircraft position");<br />
TestMap.setRange(25); <br />
<br />
TestMap.setTranslation( myCanvas.get("view[0]")/2,<br />
myCanvas.get("view[1]")/2<br />
);<br />
var r = func(name,vis=1,zindex=nil) return caller(0)[0];<br />
var type = r('APT');<br />
var style_apt = {<br />
scale_factor:0.5,<br />
color_default:[0,1,0.9],<br />
line_width:4,<br />
label_font_color:[0,1,0.9],<br />
label_font_size:30<br />
};<br />
TestMap.addLayer(factory: canvas.SymbolLayer, type_arg: type.name, visible: type.vis, priority: type.zindex,style:style_apt);<br />
<br />
var type = r('VOR');<br />
var style_vor = {<br />
scale_factor:0.6,<br />
active_color:[1,0,0],<br />
inactive_color:[0,1,0],<br />
line_width:4,<br />
};<br />
TestMap.addLayer(factory: canvas.SymbolLayer, type_arg: type.name, visible: type.vis, priority: type.zindex,style:style_vor);<br />
<br />
### See ...fgdata/Nasal/canvas/map/APT.symbol ...fgdata/Nasal/canvas/map/VOR.style ... for the style variables that can be configured.<br />
<br />
</syntaxhighlight><br />
|}<br />
<br />
== Using MapStructure and Overlays ==<br />
{{FGCquote<br />
|Support for overlays using geo-referenced raster images isn't too well-developed currently, so would need to work with a few hard-coded assumptions (e.g. being specific to a certain raster image and map layout) - but maybe TheTom can provide a few more ideas on how to proceed from here - otherwise, the Map is normally not aware of any non-Map items, i.e. as long as the overlay is added "outside" the Map, it isn't even aware of the raster image - and when it is added as a map element, it would probably be rotated. So there's still some work needed here. But generally, this should work well enough even in its current form (the screen shot is purely based on the Canvas Snippets article, i.e. it just displays a Canvas GUI dialog, adds the downloaded raster image and then adds the MapStructure APS layer - without the Map being aware of the overlay/geo-referencing that is needed currently).<br />
|{{cite web |url=http://forum.flightgear.org/viewtopic.php?p=238316#p238316<br />
|title=<nowiki>Re: Using Canvas for visualizing orbital flights (cont'd PM)</nowiki><br />
|author=<nowiki>Hooray</nowiki><br />
|date=<nowiki>Fri Apr 10</nowiki><br />
}}<br />
}}<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code <br />
|-<br />
| [[File:Canvas-overlay-with-mapstructure.png|thumb|Using the [[MapStructure]] framework in conjunction with raster images as overlays]]<br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. Equally, this snippet assumes that your canvas is named '''myCanvas'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
</syntaxhighlight><br />
|}<br />
<br />
== A simple tile map ==<br />
<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code <br />
|-<br />
| [[File:Canvas - Tile map demo.png|thumb|A simple, canvas based tile map which is centered around the aircraft.]]<br />
| <br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var (width,height) = (768,512);<br />
var tile_size = 256;<br />
<br />
var window = canvas.Window.new([width, height],"dialog")<br />
.set('title', "Tile map demo");<br />
var g = window.getCanvas(1)<br />
.createGroup();<br />
<br />
# Simple user interface (Buttons for zoom and label for displaying it)<br />
var zoom = 10;<br />
var type = "map";<br />
<br />
var ui_root = window.getCanvas().createGroup();<br />
var vbox = canvas.VBoxLayout.new();<br />
window.setLayout(vbox);<br />
<br />
<br />
var button_in = canvas.gui.widgets.Button.new(ui_root, canvas.style, {})<br />
.setText("+")<br />
.listen("clicked", func changeZoom(1));<br />
var button_out = canvas.gui.widgets.Button.new(ui_root, canvas.style, {})<br />
.setText("-")<br />
.listen("clicked", func changeZoom(-1));<br />
button_in.setSizeHint([32, 32]);<br />
button_out.setSizeHint([32, 32]);<br />
<br />
var label_zoom = canvas.gui.widgets.Label.new(ui_root, canvas.style, {});<br />
<br />
var button_box = canvas.HBoxLayout.new();<br />
button_box.addItem(button_in);<br />
button_box.addItem(label_zoom);<br />
button_box.addItem(button_out);<br />
button_box.addStretch(1);<br />
<br />
vbox.addItem(button_box);<br />
vbox.addStretch(1);<br />
<br />
var changeZoom = func(d)<br />
{<br />
zoom = math.max(2, math.min(19, zoom + d));<br />
label_zoom.setText("Zoom " ~ zoom);<br />
updateTiles();<br />
}<br />
<br />
# http://polymaps.org/docs/<br />
# https://github.com/simplegeo/polymaps<br />
# https://github.com/Leaflet/Leaflet<br />
<br />
var maps_base = getprop("/sim/fg-home") ~ '/cache/maps';<br />
<br />
# http://otile1.mqcdn.com/tiles/1.0.0/map<br />
# http://otile1.mqcdn.com/tiles/1.0.0/sat<br />
# (also see http://wiki.openstreetmap.org/wiki/Tile_usage_policy)<br />
var makeUrl =<br />
string.compileTemplate('http://otile1.mqcdn.com/tiles/1.0.0/{type}/{z}/{x}/{y}.jpg');<br />
var makePath =<br />
string.compileTemplate(maps_base ~ '/osm-{type}/{z}/{x}/{y}.jpg');<br />
var num_tiles = [4, 3];<br />
<br />
var center_tile_offset = [<br />
(num_tiles[0] - 1) / 2,<br />
(num_tiles[1] - 1) / 2<br />
];<br />
<br />
# simple aircraft icon at current position/center of the map<br />
g.createChild("path")<br />
.moveTo( tile_size * center_tile_offset[0] - 10,<br />
tile_size * center_tile_offset[1] )<br />
.horiz(20)<br />
.move(-10,-10)<br />
.vert(20)<br />
.set("stroke", "red")<br />
.set("stroke-width", 2)<br />
.set("z-index", 1);<br />
<br />
##<br />
# initialize the map by setting up<br />
# a grid of raster images <br />
<br />
var tiles = setsize([], num_tiles[0]);<br />
for(var x = 0; x < num_tiles[0]; x += 1)<br />
{<br />
tiles[x] = setsize([], num_tiles[1]);<br />
for(var y = 0; y < num_tiles[1]; y += 1)<br />
tiles[x][y] = g.createChild("image", "map-tile");<br />
}<br />
<br />
var last_tile = [-1,-1];<br />
var last_type = type;<br />
<br />
##<br />
# this is the callback that will be regularly called by the timer<br />
# to update the map<br />
var updateTiles = func()<br />
{<br />
# get current position<br />
var lat = getprop('/position/latitude-deg');<br />
var lon = getprop('/position/longitude-deg');<br />
<br />
var n = math.pow(2, zoom);<br />
var offset = [<br />
n * ((lon + 180) / 360) - center_tile_offset[0],<br />
(1 - math.ln(math.tan(lat * math.pi/180) + 1 / math.cos(lat * math.pi/180)) / math.pi) / 2 * n - center_tile_offset[1]<br />
];<br />
var tile_index = [int(offset[0]), int(offset[1])];<br />
<br />
var ox = tile_index[0] - offset[0];<br />
var oy = tile_index[1] - offset[1];<br />
<br />
for(var x = 0; x < num_tiles[0]; x += 1)<br />
for(var y = 0; y < num_tiles[1]; y += 1)<br />
tiles[x][y].setTranslation(int((ox + x) * tile_size + 0.5), int((oy + y) * tile_size + 0.5));<br />
<br />
if( tile_index[0] != last_tile[0]<br />
or tile_index[1] != last_tile[1]<br />
or type != last_type )<br />
{<br />
for(var x = 0; x < num_tiles[0]; x += 1)<br />
for(var y = 0; y < num_tiles[1]; y += 1)<br />
{<br />
var pos = {<br />
z: zoom,<br />
x: int(offset[0] + x),<br />
y: int(offset[1] + y),<br />
type: type<br />
};<br />
<br />
(func {<br />
var img_path = makePath(pos);<br />
var tile = tiles[x][y];<br />
<br />
if( io.stat(img_path) == nil )<br />
{ # image not found, save in $FG_HOME<br />
var img_url = makeUrl(pos);<br />
print('requesting ' ~ img_url);<br />
http.save(img_url, img_path)<br />
.done(func {print('received image ' ~ img_path); tile.set("src", img_path);})<br />
.fail(func (r) print('Failed to get image ' ~ img_path ~ ' ' ~ r.status ~ ': ' ~ r.reason));<br />
}<br />
else # cached image found, reusing<br />
{<br />
print('loading ' ~ img_path);<br />
tile.set("src", img_path)<br />
}<br />
})();<br />
}<br />
<br />
last_tile = tile_index;<br />
last_type = type;<br />
}<br />
};<br />
<br />
##<br />
# set up a timer that will invoke updateTiles at 2-second intervals<br />
var update_timer = maketimer(2, updateTiles);<br />
# actually start the timer<br />
update_timer.start();<br />
<br />
##<br />
# set up default zoom level<br />
changeZoom(0);<br />
<br />
<br />
###<br />
# The following lines were recently added and have not yet been tested<br />
# (if in doubt, remove them)<br />
window.del = func()<br />
{<br />
print("Cleaning up window:",title,"\n");<br />
update_timer.stop();<br />
# explanation for the call() technique at: http://wiki.flightgear.org/Object_oriented_programming_in_Nasal#Making_safer_base-class_calls<br />
call(canvas.Window.del, [], me);<br />
};<br />
<br />
<br />
</syntaxhighlight><br />
|}<br />
<br />
== Adding a NavDisplay ==<br />
<br />
== Adding a CDU ==<br />
<br />
== Adding a Multi-Function Display (MFD) ==</div>Clm76https://wiki.flightgear.org/w/index.php?title=Canvas_snippets&diff=105420Canvas snippets2016-10-27T19:48:02Z<p>Clm76: /* Customizing MapStructure Styling */</p>
<hr />
<div>{{Stub}}<br />
{{-}}<br />
This article is meant to be a collection of self-contained code snippets for doing Nasal/Canvas coding without having to spend too much time working through APIs, documentation and existing code - the idea is to provide snippets that contain comments and explicit assumptions, so that these snippets can be easily adapted by people without necessarily having to be very familiar with Nasal/Canvas coding. In the long term, we're hoping to grow a library of useful code snippets to cover most use-cases, while also covering more complex scenarios, e.g. using Canvas-specific helper frameworks like [[Canvas MapStructure]], the [[NavDisplay]] or the recent CDU work.<br />
<br />
Canvas itself is designed to be front-end agnostic, meaning that it doesn't matter where a Canvas is used/displayed - this is accomplished by so called "placements", which determine where a Canvas texture shown. Thus, the back-end logic can remain the same usually, so that GUI dialogs may show avionics, but also so that avionics may show GUI widgets, which also applies to HUDs, liveries and even placements within the FlightGear scenery.<br />
<br />
We encourage people to use the snippets listed below to get started with Nasal/Canvas coding, but also to provide feedback on extending/improving this article to make it even more accessible and useful. Equally, if you're aware of any Canvas-related efforts that may contain useful code snippets, please do feel free to add those snippets here. Even people who don't have any interest in coding itself are encouraged to get involved by helping test the snippets listed below, for which you only need to the [[Nasal Console]], and while you're at it, please also help provide/update screen shots for each code snippet.<br />
<br />
Contributions added to this article should ideally satisfy some requirements:<br />
* be entirely self-contained<br />
* contain good/clear comments<br />
* have pointers/references to related code/use-cases<br />
* make assumptions explicit<br />
* contain screen shots for each example<br />
* avoid overloaded symbol names to ensure that examples can be merged and adapted easily<br />
* dependencies (svg files, images/textures etc) should always be chosen such that snippets always work using $FG_ROOT<br />
* hard-coded assumptions (e.g. texture dimensions in terms of width/height etc) should be encapsulated using variables<br />
<br />
{{Canvas Navigation}}<br />
<br />
== Creating a standalone Canvas ==<br />
<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[Special:UploadWizard|Upload requested]] || <br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var (width, height) = (512,512);<br />
# Create a standalone Canvas (not attached to any GUI dialog/aircraft etc) <br />
var myCanvas = canvas.new({<br />
"name": "Livery Test", # The name is optional but allow for easier identification<br />
"size": [width, height], # Size of the underlying texture (should be a power of 2, required) [Resolution]<br />
"view": [width, height], # Virtual resolution (Defines the coordinate system of the canvas [Dimensions]<br />
# which will be stretched the size of the texture, required)<br />
"mipmapping": 1 # Enable mipmapping (optional)<br />
});<br />
<br />
# set background color<br />
myCanvas.set("background", canvas.style.getColor("bg_color"));<br />
<br />
# creating the top-level/root group which will contain all other elements/group<br />
var root = myCanvas.createGroup();<br />
<br />
# OPTIONAL: Create a Canvas dialog window to hold the canvas and show that it's working<br />
# the Canvas is now standalone, i.e. continues to live once the dialog is closed!<br />
var window = canvas.Window.new([width,height],"dialog");<br />
window.setCanvas(myCanvas);<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
<br />
== Accessing the Canvas Desktop ==<br />
Sometimes you may want to render to the main screen, without creating a separate Canvas window - this can be accomplished by using the Canvas desktop, note that the following example is fully self-contained, i.e. does not require any code to be added to work:<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[Special:UploadWizard|Upload requested]] || <br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var myNode = canvas.getDesktop().createChild("text")<br />
.setText("Hello Canvas Desktop")<br />
.setFontSize(25, 1.0) # font size (in texels) and font aspect ratio<br />
.setColor(1,0,0,1) # red, fully opaque<br />
.setAlignment("center-center") # how the text is aligned to where you place it<br />
.setTranslation(160, 80); # where to place the text<br />
</syntaxhighlight><br />
|}<br />
<br />
== Creating Tooltips ==<br />
== Creating Popups ==<br />
== Creating a Canvas GUI Window ==<br />
<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Snippets-canvas-dialog.png|left|thumb|This is what the [[Nasal]]/[[Canvas]] snippet will look like once you pasted it into the [[Nasal Console]] and click "Execute".]] || {{Note|This example uses so called method chaining, if you're not familiar with the concept, please see: [[Object_Oriented_Programming_with_Nasal#More_on_methods:_Chaining|Method Chaining]].}}<br />
<br />
{{Canvas Snippets Boilerplate}}<br />
<br />
|}<br />
<br />
== Adding Raster Images ==<br />
<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code <br />
|-<br />
| [[File:Canvas Snippets-raster image.png|thumb|Canvas snippet demonstrating how to load a raster image]] ||<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
# path is relative to $FG_ROOT (base package)<br />
var path = "Textures/Splash1.png";<br />
# create an image child for the texture<br />
var child = root.createChild("image")<br />
.setFile(path)<br />
.setTranslation(100, 10)<br />
.setSize(130, 130);<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Adding Raster Images downloaded on demand ==<br />
<br />
The '''path''' could also just as well be a URL, i.e. a raster image retrieved via http - for example, the following snippet is entirely self-contained and can be pasted into the [[Nasal Console]] and directly executed "as is": <br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-raster-images-via-url.png|thumb|screen shot demonstrating how Nasal and Canvas can be used to display raster images downloaded on demand]] ||<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
# create a new window, dimensions are 400 x 200, using the dialog decoration (i.e. titlebar)<br />
var window = canvas.Window.new([400,200],"dialog");<br />
<br />
# adding a canvas to the new window and setting up background colors/transparency<br />
var myCanvas = window.createCanvas().set("background", canvas.style.getColor("bg_color"));<br />
<br />
# Using specific css colors would also be possible:<br />
# myCanvas.set("background", "#ffaac0");<br />
<br />
# creating the top-level/root group which will contain all other elements/group<br />
var root = myCanvas.createGroup();<br />
<br />
<br />
# path now a URL<br />
var url = "http://www.worldwidetelescope.org/docs/Images/MapOfEarth.jpg";<br />
<br />
# create an image child for the texture<br />
var child=root.createChild("image")<br />
.setFile( url ) <br />
.setTranslation(45,22) # centered, in relation to dialog coordinates<br />
.setSize(310,155); # image dimensions<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Clipping ==<br />
{{Note|{{FGCquote<br />
|1= Scaling or any other type of transformation or changing the coordinates of individual points is definitely more efficient than clipping (which requires to change the OpenGL clip planes for every rendered object with a different clipping rectangle).<br />
|2= {{cite web<br />
| url = http://forum.flightgear.org/viewtopic.php?p=277062#p277062<br />
| title = <nowiki>Re: Space Shuttle</nowiki><br />
| author = <nowiki>TheTom</nowiki><br />
| date = Feb 21st, 2016<br />
| added = Feb 21st, 2016<br />
| script_version = 0.25<br />
}}<br />
}}<br />
}}<br />
I would suggest to refer to api.nas and look for "clip" and/or "rect" - IIRC, you need to set up a clipping rectangle by setting some kind of "clip" property and setting it to a rect value in the form of rect(...)<br />
{{FGCquote<br />
|1= For details, see the clipping example at: [[Canvas Nasal API#set 2]] and [[Canvas Element#clip.28.29]]<br />
|2= {{cite web<br />
| url = http://forum.flightgear.org/viewtopic.php?p=276965#p276965<br />
| title = <nowiki>Re: Space Shuttle</nowiki><br />
| author = <nowiki>Hooray</nowiki><br />
| date = Feb 21st, 2016<br />
| added = Feb 21st, 2016<br />
| script_version = 0.25<br />
}}<br />
}}<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:MapStructure_dialog_with_clipping_and_event_handling_applied.png|thumb]] ||<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
# create a new window, dimensions are 400 x 200, using the dialog decoration (i.e. titlebar)<br />
var window = canvas.Window.new([400,200],"dialog");<br />
<br />
# adding a canvas to the new window and setting up background colors/transparency<br />
var myCanvas = window.createCanvas().set("background", canvas.style.getColor("bg_color"));<br />
<br />
# Using specific css colors would also be possible:<br />
# myCanvas.set("background", "#ffaac0");<br />
<br />
# creating the top-level/root group which will contain all other elements/group<br />
var root = myCanvas.createGroup();<br />
<br />
# create an image child for the texture<br />
var child=root.createChild(".........")<br />
.setFile( url ) <br />
.setTranslation(45,22) # centered, in relation to dialog coordinates<br />
.setSize(310,155); # image dimensions<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Adding OpenVG Paths ==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Openvg-via-canvas.png|thumb|screen shot showing a simple Canvas GUI dialog demonstrating how to use OpenVG-path drawing via Nasal and Canvas]] <br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root'''.}}<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var graph = root.createChild("group");<br />
<br />
var x_axis = graph.createChild("path", "x-axis")<br />
.moveTo(10, height/2)<br />
.lineTo(width-10, height/2)<br />
.setColor(1,0,0)<br />
.setStrokeLineWidth(3);<br />
<br />
var y_axis = graph.createChild("path", "y-axis")<br />
.moveTo(10, 10)<br />
.lineTo(10, height-10)<br />
.setColor(0,0,1)<br />
.setStrokeLineWidth(2);<br />
</syntaxhighlight><br />
|-<br />
|}<br />
<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-openvg-quadTo.png|thumb|screen shot showing a simple Canvas GUI dialog demonstrating how to use OpenVG-path drawing via Nasal and Canvas (Canvas/OpenVG quadTo API for drawing curves)]] <br />
| {{Note|This assumes that you are appending this to the snippet shown above.}}<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
var points = [ 60,height-20, <br />
230,height-100,<br />
];<br />
<br />
var track = graph.createChild("path", "track")<br />
.moveTo(10, height/2)<br />
.quadTo( points )<br />
.setColor(0,1,0)<br />
.setStrokeLineWidth(4);<br />
<br />
<br />
</syntaxhighlight><br />
|-<br />
|}<br />
<br />
<br />
<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-openvg-cubicTo.png|thumb|screen shot showing a simple Canvas GUI dialog demonstrating how to use OpenVG-path drawing via Nasal and Canvas (Canvas/OpenVG cubicTo API for drawing curves)]] <br />
| {{Note|This assumes that you are appending this to the snippet shown above.}}<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var points = [ 60,height-20, <br />
120,height-120,<br />
230,height-100,<br />
];<br />
<br />
var track = graph.createChild("path", "track")<br />
.moveTo(10, height/2)<br />
.cubicTo( points )<br />
.setColor(0,1,0)<br />
.setStrokeLineWidth(4);<br />
<br />
</syntaxhighlight><br />
|-<br />
|}<br />
<br />
== Adding Vector Images ==<br />
<br />
[[Category:Canvas SVG]]<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-svg-support.png|thumb|screen shot demonstrating how the scripted Nasal-based SVG parser can be used to dynamically turn SVG files into OpenVG instructions understood by Canvas]] <br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
# change the background color <br />
myCanvas.set("background", "#ffaac0");<br />
<br />
# creating the top-level/root group which will contain all other elements/group<br />
var root = myCanvas.createGroup();<br />
<br />
var filename = "/Nasal/canvas/map/Images/boeingAirplane.svg";<br />
var svg_symbol = root.createChild('group');<br />
canvas.parsesvg(svg_symbol, filename);<br />
<br />
svg_symbol.setTranslation(width/2,height/2);<br />
<br />
#svg_symbol.setScale(0.2);<br />
#svg_symbol.setRotation(radians)<br />
</syntaxhighlight><br />
|-<br />
|}<br />
<br />
== Using the SymbolCache ==<br />
Whenever a symbol may need to be shown/instanced multiple times (possibly using different styling), it makes sense to use caching - otherwise, identical symbols would be treated as separate OpenVG groups, all of which would need to be rasterized/rendedered separately (i.e. 100 identical symbols would be updated/rendered one by one). <br />
<br />
Typically, a map may display multiple instances of an otherwise identical symbol (think VOR, NDB, DME etc) - equally, a multiplayer map may showing multiple aircraft symbols at the same time. In these cases, it makes sense to use the SymbolCache framework, which will render symbols into a separate Canvas texture and provide a texture map that can be treated as a lookup map, which even supports styling for otherwise identical symbols. To learn more, please refer to [[Canvas MapStructure#The_SymbolCache|SymbolCache]]<br />
... <br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-SymbolCache-Instancing.png|thumb|Screen shot showing a Canvas based GUI dialog that is using the SymbolCache for instancing multiple symbols (including support for styling)]] <br />
| <!--{{Caution|This is currently untested code}}--><br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
##<br />
# this is the function that draws a symbol using OpenVG paths<br />
# it accepts a group to draw to and returns the rendered group <br />
# to the caller<br />
var drawVOR = func(group) {<br />
return group.createChild("path")<br />
.moveTo(-15,0)<br />
.lineTo(-7.5,12.5)<br />
.lineTo(7.5,12.5)<br />
.lineTo(15,0)<br />
.lineTo(7.5,-12.5)<br />
.lineTo(-7.5,-12.5)<br />
.close()<br />
.setStrokeLineWidth(line_width) # style-able<br />
.setColor(color); # style-able<br />
};<br />
<br />
var style = { # styling related attributes (as per the draw* function above)<br />
line_width: 3,<br />
scale_factor: 1,<br />
color: [1,0,0],<br />
};<br />
<br />
# create a new cache entry for the styled symbol<br />
var myCachedSymbol = canvas.StyleableCacheable.new(<br />
name:'myVOR', draw_func: drawVOR,<br />
cache: canvas.SymbolCache32x32, # the cache to be used<br />
draw_mode: canvas.SymbolCache.DRAW_CENTERED,<br />
relevant_keys: ['line_width', 'color'], # styling related attributes<br />
);<br />
<br />
var target = root.createChild('group');<br />
<br />
var x=0;<br />
var y=height/2;<br />
<br />
var xoffset=50;<br />
<br />
# render 5 instanced symbols using the style specified above<br />
for (var i=0;i<5;i+=1) {<br />
# look up the raster image for the symbol<br />
# render it using the passed style and adjust scaling<br />
var instanced = myCachedSymbol.render(target, style)<br />
.setScale(style.scale_factor)<br />
.setTranslation(x+=xoffset,y);<br />
}</syntaxhighlight><br />
|-<br />
|}<br />
<br />
The example shown above uses a fixed symbol/icon cache that is set up while booting Flightgear - sometimes, we may need cache for different purposes. So, let's assume, we need a new/custom cache with a different resolution for each entry in the cache (e.g. 256x256), we can easily accomplish that by setting up a new cache like this: <br />
<syntaxhighlight lang="nasal"><br />
var mySymbolCache256x256 = canvas.SymbolCache.new(1024,256);<br />
</syntaxhighlight><br />
<br />
== Adding Text Elements ==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:CanvasText-Hello-World.png|thumb|Screen shot showing the CanvasText example contributed by Necolatis]]<br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var myText = root.createChild("text")<br />
.setText("Hello world!")<br />
.setFontSize(20, 0.9) # font size (in texels) and font aspect ratio<br />
.setColor(1,0,0,1) # red, fully opaque<br />
.setAlignment("center-center") # how the text is aligned to where you place it<br />
.setTranslation(160, 80); # where to place the text<br />
</syntaxhighlight><br />
|-<br />
|}<br />
<br />
== Adding GUI Labels ==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-Layout-Label-example-by-Necolatis.png|thumb|Canvas demo: Layouts and Labels (by Necolatis)]]<br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. It also assumes you have a Layout item setup and called '''myLayoutItem'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
# create a new layout<br />
var myLayout = canvas.HBoxLayout.new();<br />
# assign it to the Canvas<br />
myCanvas.setLayout(myLayout);<br />
<br />
var label = canvas.gui.widgets.Label.new(root, canvas.style, {wordWrap: 0}); # wordwrap: 0 will disable wordwrapping, to enable it use 1 instead<br />
label.setText("Hello World!");<br />
myLayout.addItem(label);<br />
<br />
var label2 = canvas.gui.widgets.Label.new(root, canvas.style, {wordWrap: 0}); # wordwrap: 0 will disable wordwrapping, to enable it use 1 instead<br />
label2.setText("Hello FlightGear");<br />
myLayout.addItem(label2);<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Adding GUI Buttons (Layouts)==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-demo-layouts-and-buttons-by-Necolatis.png|thumb|Canvas snippet: buttons and layouts (by Necolatis)]] <br />
|<br />
<br />
{{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. It also assumes you have a Layout item setup and called '''myLayoutItem'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
# create a new layout<br />
var myLayout = canvas.HBoxLayout.new();<br />
# assign it to the Canvas<br />
myCanvas.setLayout(myLayout);<br />
<br />
# click button<br />
<br />
var button = canvas.gui.widgets.Button.new(root, canvas.style, {})<br />
.setText("Click on me")<br />
.setFixedSize(75, 25);<br />
<br />
button.listen("clicked", func {<br />
# add code here to react on click on button.<br />
print("Button clicked !");<br />
});<br />
<br />
myLayout.addItem(button);<br />
</syntaxhighlight><br />
<br />
|-<br />
| [[File:Canvas-toggle-button-snippet-by-Necolatis.png|thumb|Canvas toggle button demo by Necolatis]]<br />
| <syntaxhighlight lang="nasal" enclose="div"><br />
# create a new layout<br />
var myLayout = canvas.HBoxLayout.new();<br />
# assign it to the Canvas<br />
myCanvas.setLayout(myLayout);<br />
<br />
var button = canvas.gui.widgets.Button.new(root, canvas.style, {})<br />
.setText("Toggle me")<br />
.setCheckable(1) # this indicates that is should be a toggle button<br />
.setChecked(0) # depressed by default<br />
.setFixedSize(75, 25);<br />
<br />
button.listen("toggled", func (e) {<br />
if( e.detail.checked ) {<br />
# add code here to react on button being depressed.<br />
} else {<br />
# add code here to react on button not being depressed.<br />
}<br />
});<br />
<br />
<br />
myLayout.addItem(button);<br />
<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Canvas Input Dialog ==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
|[[File:Snippets-canvas-input-dialog.png|thumb|Canvas input dialog]]<br />
||<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
# create a new InputDialog with a title, label, and a callback<br />
canvas.InputDialog.getText("Input Dialog Title", "Please enter some text", func(btn,value) {<br />
if (value) gui.popupTip("You entered: "~value);<br />
});<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Canvas ScrollArea ==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
|[[File:Canvas-snippets-scrollArea-demo.png|thumb|Screen shot showing a Canvas ScrollArea populated with different splash screens, loaded from $FG_ROOT/Textures]]<br />
||<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var vbox = canvas.VBoxLayout.new();<br />
myCanvas.setLayout(vbox);<br />
<br />
var scroll = canvas.gui.widgets.ScrollArea.new(root, canvas.style, {size: [96, 128]}).move(20, 100);<br />
vbox.addItem(scroll, 1);<br />
<br />
var scrollContent =<br />
scroll.getContent()<br />
.set("font", "LiberationFonts/LiberationSans-Bold.ttf")<br />
.set("character-size", 16)<br />
.set("alignment", "left-center");<br />
<br />
var list = canvas.VBoxLayout.new();<br />
scroll.setLayout(list);<br />
<br />
for (var i=1;i<=5;i+=1) {<br />
var label = canvas.gui.widgets.Label.new(scrollContent, canvas.style, {wordWrap: 0}); <br />
label.setImage("Textures/Splash"~i~".png");<br />
label.setFixedSize(256,256);<br />
list.addItem(label);<br />
}<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Using Layouts ==<br />
<br />
== Using Styling ==<br />
== Adding a HUD ==<br />
== Adding a 2D Instrument ==<br />
== Adding a 2D Panel ==<br />
== Adding a PFD ==<br />
<br />
== Adding a Failure Mgmt Widget ==<br />
{{Note|This kind of widget will typically be useful for dialogs requiring a method for managing aircraft specific system failures (e.g. an instructor console).}}<br />
<br />
== Adding a MapStructure map to a Canvas ==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code <br />
|-<br />
| [[File:Snippets-canvas-mapstructure-dialog.png|thumb|[[MapStructure]] layers shown in a Canvas GUI dialog]]<br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. Equally, this snippet assumes that your canvas is named '''myCanvas'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
var TestMap = root.createChild("map");<br />
TestMap.setController("Aircraft position");<br />
TestMap.setRange(25); <br />
<br />
TestMap.setTranslation( myCanvas.get("view[0]")/2,<br />
myCanvas.get("view[1]")/2<br />
);<br />
var r = func(name,vis=1,zindex=nil) return caller(0)[0];<br />
<br />
foreach(var type; [r('APT'), r('VOR') ] )<br />
TestMap.addLayer(factory: canvas.SymbolLayer, type_arg: type.name, visible: type.vis, priority: type.zindex,);<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Customizing MapStructure Styling ==<br />
{{WIP}}<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code <br />
|-<br />
| [[File:Snippets-canvas-mapstructure-dialog.png|thumb|[[MapStructure]] layers shown in a Canvas GUI dialog]]<br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. Equally, this snippet assumes that your canvas is named '''myCanvas'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var TestMap = root.createChild("map");<br />
TestMap.setController("Aircraft position");<br />
TestMap.setRange(25); <br />
<br />
TestMap.setTranslation( myCanvas.get("view[0]")/2,<br />
myCanvas.get("view[1]")/2<br />
);<br />
var r = func(name,vis=1,zindex=nil) return caller(0)[0];<br />
var type = r('APT');<br />
var style_apt = {<br />
scale_factor:0.5,<br />
color_default:[0,1,0.9],<br />
line_width:4,<br />
label_font_color:[0,1,0.9],<br />
label_font_size:30<br />
};<br />
TestMap.addLayer(factory: canvas.SymbolLayer, type_arg: type.name, visible: type.vis, priority: type.zindex,style:style_apt);<br />
<br />
var type = r('VOR');<br />
var style_vor = {<br />
scale_factor:0.5,<br />
color:[0.1,0.9,0],<br />
line_width:4,<br />
text_color:[0.1,0.9,0]<br />
};<br />
TestMap.addLayer(factory: canvas.SymbolLayer, type_arg: type.name, visible: type.vis, priority: type.zindex,style:style_vor);<br />
<br />
### See ...fgdata/Nasal/canvas/map/APT.symbol ...fgdata/Nasal/canvas/map/VOR.style ... for the style variables that can be configured.<br />
<br />
</syntaxhighlight><br />
|}<br />
<br />
== Using MapStructure and Overlays ==<br />
{{FGCquote<br />
|Support for overlays using geo-referenced raster images isn't too well-developed currently, so would need to work with a few hard-coded assumptions (e.g. being specific to a certain raster image and map layout) - but maybe TheTom can provide a few more ideas on how to proceed from here - otherwise, the Map is normally not aware of any non-Map items, i.e. as long as the overlay is added "outside" the Map, it isn't even aware of the raster image - and when it is added as a map element, it would probably be rotated. So there's still some work needed here. But generally, this should work well enough even in its current form (the screen shot is purely based on the Canvas Snippets article, i.e. it just displays a Canvas GUI dialog, adds the downloaded raster image and then adds the MapStructure APS layer - without the Map being aware of the overlay/geo-referencing that is needed currently).<br />
|{{cite web |url=http://forum.flightgear.org/viewtopic.php?p=238316#p238316<br />
|title=<nowiki>Re: Using Canvas for visualizing orbital flights (cont'd PM)</nowiki><br />
|author=<nowiki>Hooray</nowiki><br />
|date=<nowiki>Fri Apr 10</nowiki><br />
}}<br />
}}<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code <br />
|-<br />
| [[File:Canvas-overlay-with-mapstructure.png|thumb|Using the [[MapStructure]] framework in conjunction with raster images as overlays]]<br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. Equally, this snippet assumes that your canvas is named '''myCanvas'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
</syntaxhighlight><br />
|}<br />
<br />
== A simple tile map ==<br />
<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code <br />
|-<br />
| [[File:Canvas - Tile map demo.png|thumb|A simple, canvas based tile map which is centered around the aircraft.]]<br />
| <br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var (width,height) = (768,512);<br />
var tile_size = 256;<br />
<br />
var window = canvas.Window.new([width, height],"dialog")<br />
.set('title', "Tile map demo");<br />
var g = window.getCanvas(1)<br />
.createGroup();<br />
<br />
# Simple user interface (Buttons for zoom and label for displaying it)<br />
var zoom = 10;<br />
var type = "map";<br />
<br />
var ui_root = window.getCanvas().createGroup();<br />
var vbox = canvas.VBoxLayout.new();<br />
window.setLayout(vbox);<br />
<br />
<br />
var button_in = canvas.gui.widgets.Button.new(ui_root, canvas.style, {})<br />
.setText("+")<br />
.listen("clicked", func changeZoom(1));<br />
var button_out = canvas.gui.widgets.Button.new(ui_root, canvas.style, {})<br />
.setText("-")<br />
.listen("clicked", func changeZoom(-1));<br />
button_in.setSizeHint([32, 32]);<br />
button_out.setSizeHint([32, 32]);<br />
<br />
var label_zoom = canvas.gui.widgets.Label.new(ui_root, canvas.style, {});<br />
<br />
var button_box = canvas.HBoxLayout.new();<br />
button_box.addItem(button_in);<br />
button_box.addItem(label_zoom);<br />
button_box.addItem(button_out);<br />
button_box.addStretch(1);<br />
<br />
vbox.addItem(button_box);<br />
vbox.addStretch(1);<br />
<br />
var changeZoom = func(d)<br />
{<br />
zoom = math.max(2, math.min(19, zoom + d));<br />
label_zoom.setText("Zoom " ~ zoom);<br />
updateTiles();<br />
}<br />
<br />
# http://polymaps.org/docs/<br />
# https://github.com/simplegeo/polymaps<br />
# https://github.com/Leaflet/Leaflet<br />
<br />
var maps_base = getprop("/sim/fg-home") ~ '/cache/maps';<br />
<br />
# http://otile1.mqcdn.com/tiles/1.0.0/map<br />
# http://otile1.mqcdn.com/tiles/1.0.0/sat<br />
# (also see http://wiki.openstreetmap.org/wiki/Tile_usage_policy)<br />
var makeUrl =<br />
string.compileTemplate('http://otile1.mqcdn.com/tiles/1.0.0/{type}/{z}/{x}/{y}.jpg');<br />
var makePath =<br />
string.compileTemplate(maps_base ~ '/osm-{type}/{z}/{x}/{y}.jpg');<br />
var num_tiles = [4, 3];<br />
<br />
var center_tile_offset = [<br />
(num_tiles[0] - 1) / 2,<br />
(num_tiles[1] - 1) / 2<br />
];<br />
<br />
# simple aircraft icon at current position/center of the map<br />
g.createChild("path")<br />
.moveTo( tile_size * center_tile_offset[0] - 10,<br />
tile_size * center_tile_offset[1] )<br />
.horiz(20)<br />
.move(-10,-10)<br />
.vert(20)<br />
.set("stroke", "red")<br />
.set("stroke-width", 2)<br />
.set("z-index", 1);<br />
<br />
##<br />
# initialize the map by setting up<br />
# a grid of raster images <br />
<br />
var tiles = setsize([], num_tiles[0]);<br />
for(var x = 0; x < num_tiles[0]; x += 1)<br />
{<br />
tiles[x] = setsize([], num_tiles[1]);<br />
for(var y = 0; y < num_tiles[1]; y += 1)<br />
tiles[x][y] = g.createChild("image", "map-tile");<br />
}<br />
<br />
var last_tile = [-1,-1];<br />
var last_type = type;<br />
<br />
##<br />
# this is the callback that will be regularly called by the timer<br />
# to update the map<br />
var updateTiles = func()<br />
{<br />
# get current position<br />
var lat = getprop('/position/latitude-deg');<br />
var lon = getprop('/position/longitude-deg');<br />
<br />
var n = math.pow(2, zoom);<br />
var offset = [<br />
n * ((lon + 180) / 360) - center_tile_offset[0],<br />
(1 - math.ln(math.tan(lat * math.pi/180) + 1 / math.cos(lat * math.pi/180)) / math.pi) / 2 * n - center_tile_offset[1]<br />
];<br />
var tile_index = [int(offset[0]), int(offset[1])];<br />
<br />
var ox = tile_index[0] - offset[0];<br />
var oy = tile_index[1] - offset[1];<br />
<br />
for(var x = 0; x < num_tiles[0]; x += 1)<br />
for(var y = 0; y < num_tiles[1]; y += 1)<br />
tiles[x][y].setTranslation(int((ox + x) * tile_size + 0.5), int((oy + y) * tile_size + 0.5));<br />
<br />
if( tile_index[0] != last_tile[0]<br />
or tile_index[1] != last_tile[1]<br />
or type != last_type )<br />
{<br />
for(var x = 0; x < num_tiles[0]; x += 1)<br />
for(var y = 0; y < num_tiles[1]; y += 1)<br />
{<br />
var pos = {<br />
z: zoom,<br />
x: int(offset[0] + x),<br />
y: int(offset[1] + y),<br />
type: type<br />
};<br />
<br />
(func {<br />
var img_path = makePath(pos);<br />
var tile = tiles[x][y];<br />
<br />
if( io.stat(img_path) == nil )<br />
{ # image not found, save in $FG_HOME<br />
var img_url = makeUrl(pos);<br />
print('requesting ' ~ img_url);<br />
http.save(img_url, img_path)<br />
.done(func {print('received image ' ~ img_path); tile.set("src", img_path);})<br />
.fail(func (r) print('Failed to get image ' ~ img_path ~ ' ' ~ r.status ~ ': ' ~ r.reason));<br />
}<br />
else # cached image found, reusing<br />
{<br />
print('loading ' ~ img_path);<br />
tile.set("src", img_path)<br />
}<br />
})();<br />
}<br />
<br />
last_tile = tile_index;<br />
last_type = type;<br />
}<br />
};<br />
<br />
##<br />
# set up a timer that will invoke updateTiles at 2-second intervals<br />
var update_timer = maketimer(2, updateTiles);<br />
# actually start the timer<br />
update_timer.start();<br />
<br />
##<br />
# set up default zoom level<br />
changeZoom(0);<br />
<br />
<br />
###<br />
# The following lines were recently added and have not yet been tested<br />
# (if in doubt, remove them)<br />
window.del = func()<br />
{<br />
print("Cleaning up window:",title,"\n");<br />
update_timer.stop();<br />
# explanation for the call() technique at: http://wiki.flightgear.org/Object_oriented_programming_in_Nasal#Making_safer_base-class_calls<br />
call(canvas.Window.del, [], me);<br />
};<br />
<br />
<br />
</syntaxhighlight><br />
|}<br />
<br />
== Adding a NavDisplay ==<br />
<br />
== Adding a CDU ==<br />
<br />
== Adding a Multi-Function Display (MFD) ==</div>Clm76https://wiki.flightgear.org/w/index.php?title=Canvas_snippets&diff=105419Canvas snippets2016-10-27T19:44:44Z<p>Clm76: /* Customizing MapStructure Styling */</p>
<hr />
<div>{{Stub}}<br />
{{-}}<br />
This article is meant to be a collection of self-contained code snippets for doing Nasal/Canvas coding without having to spend too much time working through APIs, documentation and existing code - the idea is to provide snippets that contain comments and explicit assumptions, so that these snippets can be easily adapted by people without necessarily having to be very familiar with Nasal/Canvas coding. In the long term, we're hoping to grow a library of useful code snippets to cover most use-cases, while also covering more complex scenarios, e.g. using Canvas-specific helper frameworks like [[Canvas MapStructure]], the [[NavDisplay]] or the recent CDU work.<br />
<br />
Canvas itself is designed to be front-end agnostic, meaning that it doesn't matter where a Canvas is used/displayed - this is accomplished by so called "placements", which determine where a Canvas texture shown. Thus, the back-end logic can remain the same usually, so that GUI dialogs may show avionics, but also so that avionics may show GUI widgets, which also applies to HUDs, liveries and even placements within the FlightGear scenery.<br />
<br />
We encourage people to use the snippets listed below to get started with Nasal/Canvas coding, but also to provide feedback on extending/improving this article to make it even more accessible and useful. Equally, if you're aware of any Canvas-related efforts that may contain useful code snippets, please do feel free to add those snippets here. Even people who don't have any interest in coding itself are encouraged to get involved by helping test the snippets listed below, for which you only need to the [[Nasal Console]], and while you're at it, please also help provide/update screen shots for each code snippet.<br />
<br />
Contributions added to this article should ideally satisfy some requirements:<br />
* be entirely self-contained<br />
* contain good/clear comments<br />
* have pointers/references to related code/use-cases<br />
* make assumptions explicit<br />
* contain screen shots for each example<br />
* avoid overloaded symbol names to ensure that examples can be merged and adapted easily<br />
* dependencies (svg files, images/textures etc) should always be chosen such that snippets always work using $FG_ROOT<br />
* hard-coded assumptions (e.g. texture dimensions in terms of width/height etc) should be encapsulated using variables<br />
<br />
{{Canvas Navigation}}<br />
<br />
== Creating a standalone Canvas ==<br />
<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[Special:UploadWizard|Upload requested]] || <br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var (width, height) = (512,512);<br />
# Create a standalone Canvas (not attached to any GUI dialog/aircraft etc) <br />
var myCanvas = canvas.new({<br />
"name": "Livery Test", # The name is optional but allow for easier identification<br />
"size": [width, height], # Size of the underlying texture (should be a power of 2, required) [Resolution]<br />
"view": [width, height], # Virtual resolution (Defines the coordinate system of the canvas [Dimensions]<br />
# which will be stretched the size of the texture, required)<br />
"mipmapping": 1 # Enable mipmapping (optional)<br />
});<br />
<br />
# set background color<br />
myCanvas.set("background", canvas.style.getColor("bg_color"));<br />
<br />
# creating the top-level/root group which will contain all other elements/group<br />
var root = myCanvas.createGroup();<br />
<br />
# OPTIONAL: Create a Canvas dialog window to hold the canvas and show that it's working<br />
# the Canvas is now standalone, i.e. continues to live once the dialog is closed!<br />
var window = canvas.Window.new([width,height],"dialog");<br />
window.setCanvas(myCanvas);<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
<br />
== Accessing the Canvas Desktop ==<br />
Sometimes you may want to render to the main screen, without creating a separate Canvas window - this can be accomplished by using the Canvas desktop, note that the following example is fully self-contained, i.e. does not require any code to be added to work:<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[Special:UploadWizard|Upload requested]] || <br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var myNode = canvas.getDesktop().createChild("text")<br />
.setText("Hello Canvas Desktop")<br />
.setFontSize(25, 1.0) # font size (in texels) and font aspect ratio<br />
.setColor(1,0,0,1) # red, fully opaque<br />
.setAlignment("center-center") # how the text is aligned to where you place it<br />
.setTranslation(160, 80); # where to place the text<br />
</syntaxhighlight><br />
|}<br />
<br />
== Creating Tooltips ==<br />
== Creating Popups ==<br />
== Creating a Canvas GUI Window ==<br />
<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Snippets-canvas-dialog.png|left|thumb|This is what the [[Nasal]]/[[Canvas]] snippet will look like once you pasted it into the [[Nasal Console]] and click "Execute".]] || {{Note|This example uses so called method chaining, if you're not familiar with the concept, please see: [[Object_Oriented_Programming_with_Nasal#More_on_methods:_Chaining|Method Chaining]].}}<br />
<br />
{{Canvas Snippets Boilerplate}}<br />
<br />
|}<br />
<br />
== Adding Raster Images ==<br />
<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code <br />
|-<br />
| [[File:Canvas Snippets-raster image.png|thumb|Canvas snippet demonstrating how to load a raster image]] ||<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
# path is relative to $FG_ROOT (base package)<br />
var path = "Textures/Splash1.png";<br />
# create an image child for the texture<br />
var child = root.createChild("image")<br />
.setFile(path)<br />
.setTranslation(100, 10)<br />
.setSize(130, 130);<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Adding Raster Images downloaded on demand ==<br />
<br />
The '''path''' could also just as well be a URL, i.e. a raster image retrieved via http - for example, the following snippet is entirely self-contained and can be pasted into the [[Nasal Console]] and directly executed "as is": <br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-raster-images-via-url.png|thumb|screen shot demonstrating how Nasal and Canvas can be used to display raster images downloaded on demand]] ||<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
# create a new window, dimensions are 400 x 200, using the dialog decoration (i.e. titlebar)<br />
var window = canvas.Window.new([400,200],"dialog");<br />
<br />
# adding a canvas to the new window and setting up background colors/transparency<br />
var myCanvas = window.createCanvas().set("background", canvas.style.getColor("bg_color"));<br />
<br />
# Using specific css colors would also be possible:<br />
# myCanvas.set("background", "#ffaac0");<br />
<br />
# creating the top-level/root group which will contain all other elements/group<br />
var root = myCanvas.createGroup();<br />
<br />
<br />
# path now a URL<br />
var url = "http://www.worldwidetelescope.org/docs/Images/MapOfEarth.jpg";<br />
<br />
# create an image child for the texture<br />
var child=root.createChild("image")<br />
.setFile( url ) <br />
.setTranslation(45,22) # centered, in relation to dialog coordinates<br />
.setSize(310,155); # image dimensions<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Clipping ==<br />
{{Note|{{FGCquote<br />
|1= Scaling or any other type of transformation or changing the coordinates of individual points is definitely more efficient than clipping (which requires to change the OpenGL clip planes for every rendered object with a different clipping rectangle).<br />
|2= {{cite web<br />
| url = http://forum.flightgear.org/viewtopic.php?p=277062#p277062<br />
| title = <nowiki>Re: Space Shuttle</nowiki><br />
| author = <nowiki>TheTom</nowiki><br />
| date = Feb 21st, 2016<br />
| added = Feb 21st, 2016<br />
| script_version = 0.25<br />
}}<br />
}}<br />
}}<br />
I would suggest to refer to api.nas and look for "clip" and/or "rect" - IIRC, you need to set up a clipping rectangle by setting some kind of "clip" property and setting it to a rect value in the form of rect(...)<br />
{{FGCquote<br />
|1= For details, see the clipping example at: [[Canvas Nasal API#set 2]] and [[Canvas Element#clip.28.29]]<br />
|2= {{cite web<br />
| url = http://forum.flightgear.org/viewtopic.php?p=276965#p276965<br />
| title = <nowiki>Re: Space Shuttle</nowiki><br />
| author = <nowiki>Hooray</nowiki><br />
| date = Feb 21st, 2016<br />
| added = Feb 21st, 2016<br />
| script_version = 0.25<br />
}}<br />
}}<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:MapStructure_dialog_with_clipping_and_event_handling_applied.png|thumb]] ||<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
# create a new window, dimensions are 400 x 200, using the dialog decoration (i.e. titlebar)<br />
var window = canvas.Window.new([400,200],"dialog");<br />
<br />
# adding a canvas to the new window and setting up background colors/transparency<br />
var myCanvas = window.createCanvas().set("background", canvas.style.getColor("bg_color"));<br />
<br />
# Using specific css colors would also be possible:<br />
# myCanvas.set("background", "#ffaac0");<br />
<br />
# creating the top-level/root group which will contain all other elements/group<br />
var root = myCanvas.createGroup();<br />
<br />
# create an image child for the texture<br />
var child=root.createChild(".........")<br />
.setFile( url ) <br />
.setTranslation(45,22) # centered, in relation to dialog coordinates<br />
.setSize(310,155); # image dimensions<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Adding OpenVG Paths ==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Openvg-via-canvas.png|thumb|screen shot showing a simple Canvas GUI dialog demonstrating how to use OpenVG-path drawing via Nasal and Canvas]] <br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root'''.}}<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var graph = root.createChild("group");<br />
<br />
var x_axis = graph.createChild("path", "x-axis")<br />
.moveTo(10, height/2)<br />
.lineTo(width-10, height/2)<br />
.setColor(1,0,0)<br />
.setStrokeLineWidth(3);<br />
<br />
var y_axis = graph.createChild("path", "y-axis")<br />
.moveTo(10, 10)<br />
.lineTo(10, height-10)<br />
.setColor(0,0,1)<br />
.setStrokeLineWidth(2);<br />
</syntaxhighlight><br />
|-<br />
|}<br />
<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-openvg-quadTo.png|thumb|screen shot showing a simple Canvas GUI dialog demonstrating how to use OpenVG-path drawing via Nasal and Canvas (Canvas/OpenVG quadTo API for drawing curves)]] <br />
| {{Note|This assumes that you are appending this to the snippet shown above.}}<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
var points = [ 60,height-20, <br />
230,height-100,<br />
];<br />
<br />
var track = graph.createChild("path", "track")<br />
.moveTo(10, height/2)<br />
.quadTo( points )<br />
.setColor(0,1,0)<br />
.setStrokeLineWidth(4);<br />
<br />
<br />
</syntaxhighlight><br />
|-<br />
|}<br />
<br />
<br />
<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-openvg-cubicTo.png|thumb|screen shot showing a simple Canvas GUI dialog demonstrating how to use OpenVG-path drawing via Nasal and Canvas (Canvas/OpenVG cubicTo API for drawing curves)]] <br />
| {{Note|This assumes that you are appending this to the snippet shown above.}}<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var points = [ 60,height-20, <br />
120,height-120,<br />
230,height-100,<br />
];<br />
<br />
var track = graph.createChild("path", "track")<br />
.moveTo(10, height/2)<br />
.cubicTo( points )<br />
.setColor(0,1,0)<br />
.setStrokeLineWidth(4);<br />
<br />
</syntaxhighlight><br />
|-<br />
|}<br />
<br />
== Adding Vector Images ==<br />
<br />
[[Category:Canvas SVG]]<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-svg-support.png|thumb|screen shot demonstrating how the scripted Nasal-based SVG parser can be used to dynamically turn SVG files into OpenVG instructions understood by Canvas]] <br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
# change the background color <br />
myCanvas.set("background", "#ffaac0");<br />
<br />
# creating the top-level/root group which will contain all other elements/group<br />
var root = myCanvas.createGroup();<br />
<br />
var filename = "/Nasal/canvas/map/Images/boeingAirplane.svg";<br />
var svg_symbol = root.createChild('group');<br />
canvas.parsesvg(svg_symbol, filename);<br />
<br />
svg_symbol.setTranslation(width/2,height/2);<br />
<br />
#svg_symbol.setScale(0.2);<br />
#svg_symbol.setRotation(radians)<br />
</syntaxhighlight><br />
|-<br />
|}<br />
<br />
== Using the SymbolCache ==<br />
Whenever a symbol may need to be shown/instanced multiple times (possibly using different styling), it makes sense to use caching - otherwise, identical symbols would be treated as separate OpenVG groups, all of which would need to be rasterized/rendedered separately (i.e. 100 identical symbols would be updated/rendered one by one). <br />
<br />
Typically, a map may display multiple instances of an otherwise identical symbol (think VOR, NDB, DME etc) - equally, a multiplayer map may showing multiple aircraft symbols at the same time. In these cases, it makes sense to use the SymbolCache framework, which will render symbols into a separate Canvas texture and provide a texture map that can be treated as a lookup map, which even supports styling for otherwise identical symbols. To learn more, please refer to [[Canvas MapStructure#The_SymbolCache|SymbolCache]]<br />
... <br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-SymbolCache-Instancing.png|thumb|Screen shot showing a Canvas based GUI dialog that is using the SymbolCache for instancing multiple symbols (including support for styling)]] <br />
| <!--{{Caution|This is currently untested code}}--><br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
##<br />
# this is the function that draws a symbol using OpenVG paths<br />
# it accepts a group to draw to and returns the rendered group <br />
# to the caller<br />
var drawVOR = func(group) {<br />
return group.createChild("path")<br />
.moveTo(-15,0)<br />
.lineTo(-7.5,12.5)<br />
.lineTo(7.5,12.5)<br />
.lineTo(15,0)<br />
.lineTo(7.5,-12.5)<br />
.lineTo(-7.5,-12.5)<br />
.close()<br />
.setStrokeLineWidth(line_width) # style-able<br />
.setColor(color); # style-able<br />
};<br />
<br />
var style = { # styling related attributes (as per the draw* function above)<br />
line_width: 3,<br />
scale_factor: 1,<br />
color: [1,0,0],<br />
};<br />
<br />
# create a new cache entry for the styled symbol<br />
var myCachedSymbol = canvas.StyleableCacheable.new(<br />
name:'myVOR', draw_func: drawVOR,<br />
cache: canvas.SymbolCache32x32, # the cache to be used<br />
draw_mode: canvas.SymbolCache.DRAW_CENTERED,<br />
relevant_keys: ['line_width', 'color'], # styling related attributes<br />
);<br />
<br />
var target = root.createChild('group');<br />
<br />
var x=0;<br />
var y=height/2;<br />
<br />
var xoffset=50;<br />
<br />
# render 5 instanced symbols using the style specified above<br />
for (var i=0;i<5;i+=1) {<br />
# look up the raster image for the symbol<br />
# render it using the passed style and adjust scaling<br />
var instanced = myCachedSymbol.render(target, style)<br />
.setScale(style.scale_factor)<br />
.setTranslation(x+=xoffset,y);<br />
}</syntaxhighlight><br />
|-<br />
|}<br />
<br />
The example shown above uses a fixed symbol/icon cache that is set up while booting Flightgear - sometimes, we may need cache for different purposes. So, let's assume, we need a new/custom cache with a different resolution for each entry in the cache (e.g. 256x256), we can easily accomplish that by setting up a new cache like this: <br />
<syntaxhighlight lang="nasal"><br />
var mySymbolCache256x256 = canvas.SymbolCache.new(1024,256);<br />
</syntaxhighlight><br />
<br />
== Adding Text Elements ==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:CanvasText-Hello-World.png|thumb|Screen shot showing the CanvasText example contributed by Necolatis]]<br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var myText = root.createChild("text")<br />
.setText("Hello world!")<br />
.setFontSize(20, 0.9) # font size (in texels) and font aspect ratio<br />
.setColor(1,0,0,1) # red, fully opaque<br />
.setAlignment("center-center") # how the text is aligned to where you place it<br />
.setTranslation(160, 80); # where to place the text<br />
</syntaxhighlight><br />
|-<br />
|}<br />
<br />
== Adding GUI Labels ==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-Layout-Label-example-by-Necolatis.png|thumb|Canvas demo: Layouts and Labels (by Necolatis)]]<br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. It also assumes you have a Layout item setup and called '''myLayoutItem'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
# create a new layout<br />
var myLayout = canvas.HBoxLayout.new();<br />
# assign it to the Canvas<br />
myCanvas.setLayout(myLayout);<br />
<br />
var label = canvas.gui.widgets.Label.new(root, canvas.style, {wordWrap: 0}); # wordwrap: 0 will disable wordwrapping, to enable it use 1 instead<br />
label.setText("Hello World!");<br />
myLayout.addItem(label);<br />
<br />
var label2 = canvas.gui.widgets.Label.new(root, canvas.style, {wordWrap: 0}); # wordwrap: 0 will disable wordwrapping, to enable it use 1 instead<br />
label2.setText("Hello FlightGear");<br />
myLayout.addItem(label2);<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Adding GUI Buttons (Layouts)==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-demo-layouts-and-buttons-by-Necolatis.png|thumb|Canvas snippet: buttons and layouts (by Necolatis)]] <br />
|<br />
<br />
{{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. It also assumes you have a Layout item setup and called '''myLayoutItem'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
# create a new layout<br />
var myLayout = canvas.HBoxLayout.new();<br />
# assign it to the Canvas<br />
myCanvas.setLayout(myLayout);<br />
<br />
# click button<br />
<br />
var button = canvas.gui.widgets.Button.new(root, canvas.style, {})<br />
.setText("Click on me")<br />
.setFixedSize(75, 25);<br />
<br />
button.listen("clicked", func {<br />
# add code here to react on click on button.<br />
print("Button clicked !");<br />
});<br />
<br />
myLayout.addItem(button);<br />
</syntaxhighlight><br />
<br />
|-<br />
| [[File:Canvas-toggle-button-snippet-by-Necolatis.png|thumb|Canvas toggle button demo by Necolatis]]<br />
| <syntaxhighlight lang="nasal" enclose="div"><br />
# create a new layout<br />
var myLayout = canvas.HBoxLayout.new();<br />
# assign it to the Canvas<br />
myCanvas.setLayout(myLayout);<br />
<br />
var button = canvas.gui.widgets.Button.new(root, canvas.style, {})<br />
.setText("Toggle me")<br />
.setCheckable(1) # this indicates that is should be a toggle button<br />
.setChecked(0) # depressed by default<br />
.setFixedSize(75, 25);<br />
<br />
button.listen("toggled", func (e) {<br />
if( e.detail.checked ) {<br />
# add code here to react on button being depressed.<br />
} else {<br />
# add code here to react on button not being depressed.<br />
}<br />
});<br />
<br />
<br />
myLayout.addItem(button);<br />
<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Canvas Input Dialog ==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
|[[File:Snippets-canvas-input-dialog.png|thumb|Canvas input dialog]]<br />
||<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
# create a new InputDialog with a title, label, and a callback<br />
canvas.InputDialog.getText("Input Dialog Title", "Please enter some text", func(btn,value) {<br />
if (value) gui.popupTip("You entered: "~value);<br />
});<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Canvas ScrollArea ==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
|[[File:Canvas-snippets-scrollArea-demo.png|thumb|Screen shot showing a Canvas ScrollArea populated with different splash screens, loaded from $FG_ROOT/Textures]]<br />
||<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var vbox = canvas.VBoxLayout.new();<br />
myCanvas.setLayout(vbox);<br />
<br />
var scroll = canvas.gui.widgets.ScrollArea.new(root, canvas.style, {size: [96, 128]}).move(20, 100);<br />
vbox.addItem(scroll, 1);<br />
<br />
var scrollContent =<br />
scroll.getContent()<br />
.set("font", "LiberationFonts/LiberationSans-Bold.ttf")<br />
.set("character-size", 16)<br />
.set("alignment", "left-center");<br />
<br />
var list = canvas.VBoxLayout.new();<br />
scroll.setLayout(list);<br />
<br />
for (var i=1;i<=5;i+=1) {<br />
var label = canvas.gui.widgets.Label.new(scrollContent, canvas.style, {wordWrap: 0}); <br />
label.setImage("Textures/Splash"~i~".png");<br />
label.setFixedSize(256,256);<br />
list.addItem(label);<br />
}<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Using Layouts ==<br />
<br />
== Using Styling ==<br />
== Adding a HUD ==<br />
== Adding a 2D Instrument ==<br />
== Adding a 2D Panel ==<br />
== Adding a PFD ==<br />
<br />
== Adding a Failure Mgmt Widget ==<br />
{{Note|This kind of widget will typically be useful for dialogs requiring a method for managing aircraft specific system failures (e.g. an instructor console).}}<br />
<br />
== Adding a MapStructure map to a Canvas ==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code <br />
|-<br />
| [[File:Snippets-canvas-mapstructure-dialog.png|thumb|[[MapStructure]] layers shown in a Canvas GUI dialog]]<br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. Equally, this snippet assumes that your canvas is named '''myCanvas'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
var TestMap = root.createChild("map");<br />
TestMap.setController("Aircraft position");<br />
TestMap.setRange(25); <br />
<br />
TestMap.setTranslation( myCanvas.get("view[0]")/2,<br />
myCanvas.get("view[1]")/2<br />
);<br />
var r = func(name,vis=1,zindex=nil) return caller(0)[0];<br />
<br />
foreach(var type; [r('APT'), r('VOR') ] )<br />
TestMap.addLayer(factory: canvas.SymbolLayer, type_arg: type.name, visible: type.vis, priority: type.zindex,);<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Customizing MapStructure Styling ==<br />
{{WIP}}<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code <br />
|-<br />
| [[File:Snippets-canvas-mapstructure-dialog.png|thumb|[[MapStructure]] layers shown in a Canvas GUI dialog]]<br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. Equally, this snippet assumes that your canvas is named '''myCanvas'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var TestMap = root.createChild("map");<br />
TestMap.setController("Aircraft position");<br />
TestMap.setRange(25); <br />
<br />
TestMap.setTranslation( myCanvas.get("view[0]")/2,<br />
myCanvas.get("view[1]")/2<br />
);<br />
var r = func(name,vis=1,zindex=nil) return caller(0)[0];<br />
var type = r('APT');<br />
var style_apt = {<br />
scale_factor:0.5,<br />
color_default:[0,1,0.9],<br />
line_width:4,<br />
label_font_color:[0,1,0.9],<br />
label_font_size:30<br />
};<br />
TestMap.addLayer(factory: canvas.SymbolLayer, type_arg: type.name, visible: type.vis, priority: type.zindex,style:style_apt);<br />
<br />
var type = r('VOR');<br />
var style_vor = {<br />
scale_factor:0.5,<br />
color:[0.1,0.9,0],<br />
line_width:4,<br />
text_color:[0.1,0.9,0]<br />
};<br />
TestMap.addLayer(factory: canvas.SymbolLayer, type_arg: type.name, visible: type.vis, priority: type.zindex,style:style_vor);<br />
<br />
### See ...fgdata/Nasal/canvas/map/APT.symbol ...fgdata/Nasal/canvas/map/VOR.style ... for the style variables that can be configured.<br />
<br />
</syntaxhighlight><br />
<br />
== Using MapStructure and Overlays ==<br />
{{FGCquote<br />
|Support for overlays using geo-referenced raster images isn't too well-developed currently, so would need to work with a few hard-coded assumptions (e.g. being specific to a certain raster image and map layout) - but maybe TheTom can provide a few more ideas on how to proceed from here - otherwise, the Map is normally not aware of any non-Map items, i.e. as long as the overlay is added "outside" the Map, it isn't even aware of the raster image - and when it is added as a map element, it would probably be rotated. So there's still some work needed here. But generally, this should work well enough even in its current form (the screen shot is purely based on the Canvas Snippets article, i.e. it just displays a Canvas GUI dialog, adds the downloaded raster image and then adds the MapStructure APS layer - without the Map being aware of the overlay/geo-referencing that is needed currently).<br />
|{{cite web |url=http://forum.flightgear.org/viewtopic.php?p=238316#p238316<br />
|title=<nowiki>Re: Using Canvas for visualizing orbital flights (cont'd PM)</nowiki><br />
|author=<nowiki>Hooray</nowiki><br />
|date=<nowiki>Fri Apr 10</nowiki><br />
}}<br />
}}<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code <br />
|-<br />
| [[File:Canvas-overlay-with-mapstructure.png|thumb|Using the [[MapStructure]] framework in conjunction with raster images as overlays]]<br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. Equally, this snippet assumes that your canvas is named '''myCanvas'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
</syntaxhighlight><br />
|}<br />
<br />
== A simple tile map ==<br />
<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code <br />
|-<br />
| [[File:Canvas - Tile map demo.png|thumb|A simple, canvas based tile map which is centered around the aircraft.]]<br />
| <br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var (width,height) = (768,512);<br />
var tile_size = 256;<br />
<br />
var window = canvas.Window.new([width, height],"dialog")<br />
.set('title', "Tile map demo");<br />
var g = window.getCanvas(1)<br />
.createGroup();<br />
<br />
# Simple user interface (Buttons for zoom and label for displaying it)<br />
var zoom = 10;<br />
var type = "map";<br />
<br />
var ui_root = window.getCanvas().createGroup();<br />
var vbox = canvas.VBoxLayout.new();<br />
window.setLayout(vbox);<br />
<br />
<br />
var button_in = canvas.gui.widgets.Button.new(ui_root, canvas.style, {})<br />
.setText("+")<br />
.listen("clicked", func changeZoom(1));<br />
var button_out = canvas.gui.widgets.Button.new(ui_root, canvas.style, {})<br />
.setText("-")<br />
.listen("clicked", func changeZoom(-1));<br />
button_in.setSizeHint([32, 32]);<br />
button_out.setSizeHint([32, 32]);<br />
<br />
var label_zoom = canvas.gui.widgets.Label.new(ui_root, canvas.style, {});<br />
<br />
var button_box = canvas.HBoxLayout.new();<br />
button_box.addItem(button_in);<br />
button_box.addItem(label_zoom);<br />
button_box.addItem(button_out);<br />
button_box.addStretch(1);<br />
<br />
vbox.addItem(button_box);<br />
vbox.addStretch(1);<br />
<br />
var changeZoom = func(d)<br />
{<br />
zoom = math.max(2, math.min(19, zoom + d));<br />
label_zoom.setText("Zoom " ~ zoom);<br />
updateTiles();<br />
}<br />
<br />
# http://polymaps.org/docs/<br />
# https://github.com/simplegeo/polymaps<br />
# https://github.com/Leaflet/Leaflet<br />
<br />
var maps_base = getprop("/sim/fg-home") ~ '/cache/maps';<br />
<br />
# http://otile1.mqcdn.com/tiles/1.0.0/map<br />
# http://otile1.mqcdn.com/tiles/1.0.0/sat<br />
# (also see http://wiki.openstreetmap.org/wiki/Tile_usage_policy)<br />
var makeUrl =<br />
string.compileTemplate('http://otile1.mqcdn.com/tiles/1.0.0/{type}/{z}/{x}/{y}.jpg');<br />
var makePath =<br />
string.compileTemplate(maps_base ~ '/osm-{type}/{z}/{x}/{y}.jpg');<br />
var num_tiles = [4, 3];<br />
<br />
var center_tile_offset = [<br />
(num_tiles[0] - 1) / 2,<br />
(num_tiles[1] - 1) / 2<br />
];<br />
<br />
# simple aircraft icon at current position/center of the map<br />
g.createChild("path")<br />
.moveTo( tile_size * center_tile_offset[0] - 10,<br />
tile_size * center_tile_offset[1] )<br />
.horiz(20)<br />
.move(-10,-10)<br />
.vert(20)<br />
.set("stroke", "red")<br />
.set("stroke-width", 2)<br />
.set("z-index", 1);<br />
<br />
##<br />
# initialize the map by setting up<br />
# a grid of raster images <br />
<br />
var tiles = setsize([], num_tiles[0]);<br />
for(var x = 0; x < num_tiles[0]; x += 1)<br />
{<br />
tiles[x] = setsize([], num_tiles[1]);<br />
for(var y = 0; y < num_tiles[1]; y += 1)<br />
tiles[x][y] = g.createChild("image", "map-tile");<br />
}<br />
<br />
var last_tile = [-1,-1];<br />
var last_type = type;<br />
<br />
##<br />
# this is the callback that will be regularly called by the timer<br />
# to update the map<br />
var updateTiles = func()<br />
{<br />
# get current position<br />
var lat = getprop('/position/latitude-deg');<br />
var lon = getprop('/position/longitude-deg');<br />
<br />
var n = math.pow(2, zoom);<br />
var offset = [<br />
n * ((lon + 180) / 360) - center_tile_offset[0],<br />
(1 - math.ln(math.tan(lat * math.pi/180) + 1 / math.cos(lat * math.pi/180)) / math.pi) / 2 * n - center_tile_offset[1]<br />
];<br />
var tile_index = [int(offset[0]), int(offset[1])];<br />
<br />
var ox = tile_index[0] - offset[0];<br />
var oy = tile_index[1] - offset[1];<br />
<br />
for(var x = 0; x < num_tiles[0]; x += 1)<br />
for(var y = 0; y < num_tiles[1]; y += 1)<br />
tiles[x][y].setTranslation(int((ox + x) * tile_size + 0.5), int((oy + y) * tile_size + 0.5));<br />
<br />
if( tile_index[0] != last_tile[0]<br />
or tile_index[1] != last_tile[1]<br />
or type != last_type )<br />
{<br />
for(var x = 0; x < num_tiles[0]; x += 1)<br />
for(var y = 0; y < num_tiles[1]; y += 1)<br />
{<br />
var pos = {<br />
z: zoom,<br />
x: int(offset[0] + x),<br />
y: int(offset[1] + y),<br />
type: type<br />
};<br />
<br />
(func {<br />
var img_path = makePath(pos);<br />
var tile = tiles[x][y];<br />
<br />
if( io.stat(img_path) == nil )<br />
{ # image not found, save in $FG_HOME<br />
var img_url = makeUrl(pos);<br />
print('requesting ' ~ img_url);<br />
http.save(img_url, img_path)<br />
.done(func {print('received image ' ~ img_path); tile.set("src", img_path);})<br />
.fail(func (r) print('Failed to get image ' ~ img_path ~ ' ' ~ r.status ~ ': ' ~ r.reason));<br />
}<br />
else # cached image found, reusing<br />
{<br />
print('loading ' ~ img_path);<br />
tile.set("src", img_path)<br />
}<br />
})();<br />
}<br />
<br />
last_tile = tile_index;<br />
last_type = type;<br />
}<br />
};<br />
<br />
##<br />
# set up a timer that will invoke updateTiles at 2-second intervals<br />
var update_timer = maketimer(2, updateTiles);<br />
# actually start the timer<br />
update_timer.start();<br />
<br />
##<br />
# set up default zoom level<br />
changeZoom(0);<br />
<br />
<br />
###<br />
# The following lines were recently added and have not yet been tested<br />
# (if in doubt, remove them)<br />
window.del = func()<br />
{<br />
print("Cleaning up window:",title,"\n");<br />
update_timer.stop();<br />
# explanation for the call() technique at: http://wiki.flightgear.org/Object_oriented_programming_in_Nasal#Making_safer_base-class_calls<br />
call(canvas.Window.del, [], me);<br />
};<br />
<br />
<br />
</syntaxhighlight><br />
|}<br />
<br />
== Adding a NavDisplay ==<br />
<br />
== Adding a CDU ==<br />
<br />
== Adding a Multi-Function Display (MFD) ==</div>Clm76https://wiki.flightgear.org/w/index.php?title=Canvas_snippets&diff=105418Canvas snippets2016-10-27T19:42:50Z<p>Clm76: /* Customizing MapStructure Styling */</p>
<hr />
<div>{{Stub}}<br />
{{-}}<br />
This article is meant to be a collection of self-contained code snippets for doing Nasal/Canvas coding without having to spend too much time working through APIs, documentation and existing code - the idea is to provide snippets that contain comments and explicit assumptions, so that these snippets can be easily adapted by people without necessarily having to be very familiar with Nasal/Canvas coding. In the long term, we're hoping to grow a library of useful code snippets to cover most use-cases, while also covering more complex scenarios, e.g. using Canvas-specific helper frameworks like [[Canvas MapStructure]], the [[NavDisplay]] or the recent CDU work.<br />
<br />
Canvas itself is designed to be front-end agnostic, meaning that it doesn't matter where a Canvas is used/displayed - this is accomplished by so called "placements", which determine where a Canvas texture shown. Thus, the back-end logic can remain the same usually, so that GUI dialogs may show avionics, but also so that avionics may show GUI widgets, which also applies to HUDs, liveries and even placements within the FlightGear scenery.<br />
<br />
We encourage people to use the snippets listed below to get started with Nasal/Canvas coding, but also to provide feedback on extending/improving this article to make it even more accessible and useful. Equally, if you're aware of any Canvas-related efforts that may contain useful code snippets, please do feel free to add those snippets here. Even people who don't have any interest in coding itself are encouraged to get involved by helping test the snippets listed below, for which you only need to the [[Nasal Console]], and while you're at it, please also help provide/update screen shots for each code snippet.<br />
<br />
Contributions added to this article should ideally satisfy some requirements:<br />
* be entirely self-contained<br />
* contain good/clear comments<br />
* have pointers/references to related code/use-cases<br />
* make assumptions explicit<br />
* contain screen shots for each example<br />
* avoid overloaded symbol names to ensure that examples can be merged and adapted easily<br />
* dependencies (svg files, images/textures etc) should always be chosen such that snippets always work using $FG_ROOT<br />
* hard-coded assumptions (e.g. texture dimensions in terms of width/height etc) should be encapsulated using variables<br />
<br />
{{Canvas Navigation}}<br />
<br />
== Creating a standalone Canvas ==<br />
<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[Special:UploadWizard|Upload requested]] || <br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var (width, height) = (512,512);<br />
# Create a standalone Canvas (not attached to any GUI dialog/aircraft etc) <br />
var myCanvas = canvas.new({<br />
"name": "Livery Test", # The name is optional but allow for easier identification<br />
"size": [width, height], # Size of the underlying texture (should be a power of 2, required) [Resolution]<br />
"view": [width, height], # Virtual resolution (Defines the coordinate system of the canvas [Dimensions]<br />
# which will be stretched the size of the texture, required)<br />
"mipmapping": 1 # Enable mipmapping (optional)<br />
});<br />
<br />
# set background color<br />
myCanvas.set("background", canvas.style.getColor("bg_color"));<br />
<br />
# creating the top-level/root group which will contain all other elements/group<br />
var root = myCanvas.createGroup();<br />
<br />
# OPTIONAL: Create a Canvas dialog window to hold the canvas and show that it's working<br />
# the Canvas is now standalone, i.e. continues to live once the dialog is closed!<br />
var window = canvas.Window.new([width,height],"dialog");<br />
window.setCanvas(myCanvas);<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
<br />
== Accessing the Canvas Desktop ==<br />
Sometimes you may want to render to the main screen, without creating a separate Canvas window - this can be accomplished by using the Canvas desktop, note that the following example is fully self-contained, i.e. does not require any code to be added to work:<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[Special:UploadWizard|Upload requested]] || <br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var myNode = canvas.getDesktop().createChild("text")<br />
.setText("Hello Canvas Desktop")<br />
.setFontSize(25, 1.0) # font size (in texels) and font aspect ratio<br />
.setColor(1,0,0,1) # red, fully opaque<br />
.setAlignment("center-center") # how the text is aligned to where you place it<br />
.setTranslation(160, 80); # where to place the text<br />
</syntaxhighlight><br />
|}<br />
<br />
== Creating Tooltips ==<br />
== Creating Popups ==<br />
== Creating a Canvas GUI Window ==<br />
<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Snippets-canvas-dialog.png|left|thumb|This is what the [[Nasal]]/[[Canvas]] snippet will look like once you pasted it into the [[Nasal Console]] and click "Execute".]] || {{Note|This example uses so called method chaining, if you're not familiar with the concept, please see: [[Object_Oriented_Programming_with_Nasal#More_on_methods:_Chaining|Method Chaining]].}}<br />
<br />
{{Canvas Snippets Boilerplate}}<br />
<br />
|}<br />
<br />
== Adding Raster Images ==<br />
<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code <br />
|-<br />
| [[File:Canvas Snippets-raster image.png|thumb|Canvas snippet demonstrating how to load a raster image]] ||<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
# path is relative to $FG_ROOT (base package)<br />
var path = "Textures/Splash1.png";<br />
# create an image child for the texture<br />
var child = root.createChild("image")<br />
.setFile(path)<br />
.setTranslation(100, 10)<br />
.setSize(130, 130);<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Adding Raster Images downloaded on demand ==<br />
<br />
The '''path''' could also just as well be a URL, i.e. a raster image retrieved via http - for example, the following snippet is entirely self-contained and can be pasted into the [[Nasal Console]] and directly executed "as is": <br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-raster-images-via-url.png|thumb|screen shot demonstrating how Nasal and Canvas can be used to display raster images downloaded on demand]] ||<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
# create a new window, dimensions are 400 x 200, using the dialog decoration (i.e. titlebar)<br />
var window = canvas.Window.new([400,200],"dialog");<br />
<br />
# adding a canvas to the new window and setting up background colors/transparency<br />
var myCanvas = window.createCanvas().set("background", canvas.style.getColor("bg_color"));<br />
<br />
# Using specific css colors would also be possible:<br />
# myCanvas.set("background", "#ffaac0");<br />
<br />
# creating the top-level/root group which will contain all other elements/group<br />
var root = myCanvas.createGroup();<br />
<br />
<br />
# path now a URL<br />
var url = "http://www.worldwidetelescope.org/docs/Images/MapOfEarth.jpg";<br />
<br />
# create an image child for the texture<br />
var child=root.createChild("image")<br />
.setFile( url ) <br />
.setTranslation(45,22) # centered, in relation to dialog coordinates<br />
.setSize(310,155); # image dimensions<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Clipping ==<br />
{{Note|{{FGCquote<br />
|1= Scaling or any other type of transformation or changing the coordinates of individual points is definitely more efficient than clipping (which requires to change the OpenGL clip planes for every rendered object with a different clipping rectangle).<br />
|2= {{cite web<br />
| url = http://forum.flightgear.org/viewtopic.php?p=277062#p277062<br />
| title = <nowiki>Re: Space Shuttle</nowiki><br />
| author = <nowiki>TheTom</nowiki><br />
| date = Feb 21st, 2016<br />
| added = Feb 21st, 2016<br />
| script_version = 0.25<br />
}}<br />
}}<br />
}}<br />
I would suggest to refer to api.nas and look for "clip" and/or "rect" - IIRC, you need to set up a clipping rectangle by setting some kind of "clip" property and setting it to a rect value in the form of rect(...)<br />
{{FGCquote<br />
|1= For details, see the clipping example at: [[Canvas Nasal API#set 2]] and [[Canvas Element#clip.28.29]]<br />
|2= {{cite web<br />
| url = http://forum.flightgear.org/viewtopic.php?p=276965#p276965<br />
| title = <nowiki>Re: Space Shuttle</nowiki><br />
| author = <nowiki>Hooray</nowiki><br />
| date = Feb 21st, 2016<br />
| added = Feb 21st, 2016<br />
| script_version = 0.25<br />
}}<br />
}}<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:MapStructure_dialog_with_clipping_and_event_handling_applied.png|thumb]] ||<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
# create a new window, dimensions are 400 x 200, using the dialog decoration (i.e. titlebar)<br />
var window = canvas.Window.new([400,200],"dialog");<br />
<br />
# adding a canvas to the new window and setting up background colors/transparency<br />
var myCanvas = window.createCanvas().set("background", canvas.style.getColor("bg_color"));<br />
<br />
# Using specific css colors would also be possible:<br />
# myCanvas.set("background", "#ffaac0");<br />
<br />
# creating the top-level/root group which will contain all other elements/group<br />
var root = myCanvas.createGroup();<br />
<br />
# create an image child for the texture<br />
var child=root.createChild(".........")<br />
.setFile( url ) <br />
.setTranslation(45,22) # centered, in relation to dialog coordinates<br />
.setSize(310,155); # image dimensions<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Adding OpenVG Paths ==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Openvg-via-canvas.png|thumb|screen shot showing a simple Canvas GUI dialog demonstrating how to use OpenVG-path drawing via Nasal and Canvas]] <br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root'''.}}<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var graph = root.createChild("group");<br />
<br />
var x_axis = graph.createChild("path", "x-axis")<br />
.moveTo(10, height/2)<br />
.lineTo(width-10, height/2)<br />
.setColor(1,0,0)<br />
.setStrokeLineWidth(3);<br />
<br />
var y_axis = graph.createChild("path", "y-axis")<br />
.moveTo(10, 10)<br />
.lineTo(10, height-10)<br />
.setColor(0,0,1)<br />
.setStrokeLineWidth(2);<br />
</syntaxhighlight><br />
|-<br />
|}<br />
<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-openvg-quadTo.png|thumb|screen shot showing a simple Canvas GUI dialog demonstrating how to use OpenVG-path drawing via Nasal and Canvas (Canvas/OpenVG quadTo API for drawing curves)]] <br />
| {{Note|This assumes that you are appending this to the snippet shown above.}}<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
var points = [ 60,height-20, <br />
230,height-100,<br />
];<br />
<br />
var track = graph.createChild("path", "track")<br />
.moveTo(10, height/2)<br />
.quadTo( points )<br />
.setColor(0,1,0)<br />
.setStrokeLineWidth(4);<br />
<br />
<br />
</syntaxhighlight><br />
|-<br />
|}<br />
<br />
<br />
<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-openvg-cubicTo.png|thumb|screen shot showing a simple Canvas GUI dialog demonstrating how to use OpenVG-path drawing via Nasal and Canvas (Canvas/OpenVG cubicTo API for drawing curves)]] <br />
| {{Note|This assumes that you are appending this to the snippet shown above.}}<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var points = [ 60,height-20, <br />
120,height-120,<br />
230,height-100,<br />
];<br />
<br />
var track = graph.createChild("path", "track")<br />
.moveTo(10, height/2)<br />
.cubicTo( points )<br />
.setColor(0,1,0)<br />
.setStrokeLineWidth(4);<br />
<br />
</syntaxhighlight><br />
|-<br />
|}<br />
<br />
== Adding Vector Images ==<br />
<br />
[[Category:Canvas SVG]]<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-svg-support.png|thumb|screen shot demonstrating how the scripted Nasal-based SVG parser can be used to dynamically turn SVG files into OpenVG instructions understood by Canvas]] <br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
# change the background color <br />
myCanvas.set("background", "#ffaac0");<br />
<br />
# creating the top-level/root group which will contain all other elements/group<br />
var root = myCanvas.createGroup();<br />
<br />
var filename = "/Nasal/canvas/map/Images/boeingAirplane.svg";<br />
var svg_symbol = root.createChild('group');<br />
canvas.parsesvg(svg_symbol, filename);<br />
<br />
svg_symbol.setTranslation(width/2,height/2);<br />
<br />
#svg_symbol.setScale(0.2);<br />
#svg_symbol.setRotation(radians)<br />
</syntaxhighlight><br />
|-<br />
|}<br />
<br />
== Using the SymbolCache ==<br />
Whenever a symbol may need to be shown/instanced multiple times (possibly using different styling), it makes sense to use caching - otherwise, identical symbols would be treated as separate OpenVG groups, all of which would need to be rasterized/rendedered separately (i.e. 100 identical symbols would be updated/rendered one by one). <br />
<br />
Typically, a map may display multiple instances of an otherwise identical symbol (think VOR, NDB, DME etc) - equally, a multiplayer map may showing multiple aircraft symbols at the same time. In these cases, it makes sense to use the SymbolCache framework, which will render symbols into a separate Canvas texture and provide a texture map that can be treated as a lookup map, which even supports styling for otherwise identical symbols. To learn more, please refer to [[Canvas MapStructure#The_SymbolCache|SymbolCache]]<br />
... <br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-SymbolCache-Instancing.png|thumb|Screen shot showing a Canvas based GUI dialog that is using the SymbolCache for instancing multiple symbols (including support for styling)]] <br />
| <!--{{Caution|This is currently untested code}}--><br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
##<br />
# this is the function that draws a symbol using OpenVG paths<br />
# it accepts a group to draw to and returns the rendered group <br />
# to the caller<br />
var drawVOR = func(group) {<br />
return group.createChild("path")<br />
.moveTo(-15,0)<br />
.lineTo(-7.5,12.5)<br />
.lineTo(7.5,12.5)<br />
.lineTo(15,0)<br />
.lineTo(7.5,-12.5)<br />
.lineTo(-7.5,-12.5)<br />
.close()<br />
.setStrokeLineWidth(line_width) # style-able<br />
.setColor(color); # style-able<br />
};<br />
<br />
var style = { # styling related attributes (as per the draw* function above)<br />
line_width: 3,<br />
scale_factor: 1,<br />
color: [1,0,0],<br />
};<br />
<br />
# create a new cache entry for the styled symbol<br />
var myCachedSymbol = canvas.StyleableCacheable.new(<br />
name:'myVOR', draw_func: drawVOR,<br />
cache: canvas.SymbolCache32x32, # the cache to be used<br />
draw_mode: canvas.SymbolCache.DRAW_CENTERED,<br />
relevant_keys: ['line_width', 'color'], # styling related attributes<br />
);<br />
<br />
var target = root.createChild('group');<br />
<br />
var x=0;<br />
var y=height/2;<br />
<br />
var xoffset=50;<br />
<br />
# render 5 instanced symbols using the style specified above<br />
for (var i=0;i<5;i+=1) {<br />
# look up the raster image for the symbol<br />
# render it using the passed style and adjust scaling<br />
var instanced = myCachedSymbol.render(target, style)<br />
.setScale(style.scale_factor)<br />
.setTranslation(x+=xoffset,y);<br />
}</syntaxhighlight><br />
|-<br />
|}<br />
<br />
The example shown above uses a fixed symbol/icon cache that is set up while booting Flightgear - sometimes, we may need cache for different purposes. So, let's assume, we need a new/custom cache with a different resolution for each entry in the cache (e.g. 256x256), we can easily accomplish that by setting up a new cache like this: <br />
<syntaxhighlight lang="nasal"><br />
var mySymbolCache256x256 = canvas.SymbolCache.new(1024,256);<br />
</syntaxhighlight><br />
<br />
== Adding Text Elements ==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:CanvasText-Hello-World.png|thumb|Screen shot showing the CanvasText example contributed by Necolatis]]<br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var myText = root.createChild("text")<br />
.setText("Hello world!")<br />
.setFontSize(20, 0.9) # font size (in texels) and font aspect ratio<br />
.setColor(1,0,0,1) # red, fully opaque<br />
.setAlignment("center-center") # how the text is aligned to where you place it<br />
.setTranslation(160, 80); # where to place the text<br />
</syntaxhighlight><br />
|-<br />
|}<br />
<br />
== Adding GUI Labels ==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-Layout-Label-example-by-Necolatis.png|thumb|Canvas demo: Layouts and Labels (by Necolatis)]]<br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. It also assumes you have a Layout item setup and called '''myLayoutItem'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
# create a new layout<br />
var myLayout = canvas.HBoxLayout.new();<br />
# assign it to the Canvas<br />
myCanvas.setLayout(myLayout);<br />
<br />
var label = canvas.gui.widgets.Label.new(root, canvas.style, {wordWrap: 0}); # wordwrap: 0 will disable wordwrapping, to enable it use 1 instead<br />
label.setText("Hello World!");<br />
myLayout.addItem(label);<br />
<br />
var label2 = canvas.gui.widgets.Label.new(root, canvas.style, {wordWrap: 0}); # wordwrap: 0 will disable wordwrapping, to enable it use 1 instead<br />
label2.setText("Hello FlightGear");<br />
myLayout.addItem(label2);<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Adding GUI Buttons (Layouts)==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
| [[File:Canvas-demo-layouts-and-buttons-by-Necolatis.png|thumb|Canvas snippet: buttons and layouts (by Necolatis)]] <br />
|<br />
<br />
{{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. It also assumes you have a Layout item setup and called '''myLayoutItem'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
# create a new layout<br />
var myLayout = canvas.HBoxLayout.new();<br />
# assign it to the Canvas<br />
myCanvas.setLayout(myLayout);<br />
<br />
# click button<br />
<br />
var button = canvas.gui.widgets.Button.new(root, canvas.style, {})<br />
.setText("Click on me")<br />
.setFixedSize(75, 25);<br />
<br />
button.listen("clicked", func {<br />
# add code here to react on click on button.<br />
print("Button clicked !");<br />
});<br />
<br />
myLayout.addItem(button);<br />
</syntaxhighlight><br />
<br />
|-<br />
| [[File:Canvas-toggle-button-snippet-by-Necolatis.png|thumb|Canvas toggle button demo by Necolatis]]<br />
| <syntaxhighlight lang="nasal" enclose="div"><br />
# create a new layout<br />
var myLayout = canvas.HBoxLayout.new();<br />
# assign it to the Canvas<br />
myCanvas.setLayout(myLayout);<br />
<br />
var button = canvas.gui.widgets.Button.new(root, canvas.style, {})<br />
.setText("Toggle me")<br />
.setCheckable(1) # this indicates that is should be a toggle button<br />
.setChecked(0) # depressed by default<br />
.setFixedSize(75, 25);<br />
<br />
button.listen("toggled", func (e) {<br />
if( e.detail.checked ) {<br />
# add code here to react on button being depressed.<br />
} else {<br />
# add code here to react on button not being depressed.<br />
}<br />
});<br />
<br />
<br />
myLayout.addItem(button);<br />
<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Canvas Input Dialog ==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
|[[File:Snippets-canvas-input-dialog.png|thumb|Canvas input dialog]]<br />
||<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
# create a new InputDialog with a title, label, and a callback<br />
canvas.InputDialog.getText("Input Dialog Title", "Please enter some text", func(btn,value) {<br />
if (value) gui.popupTip("You entered: "~value);<br />
});<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Canvas ScrollArea ==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code<br />
|-<br />
|[[File:Canvas-snippets-scrollArea-demo.png|thumb|Screen shot showing a Canvas ScrollArea populated with different splash screens, loaded from $FG_ROOT/Textures]]<br />
||<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var vbox = canvas.VBoxLayout.new();<br />
myCanvas.setLayout(vbox);<br />
<br />
var scroll = canvas.gui.widgets.ScrollArea.new(root, canvas.style, {size: [96, 128]}).move(20, 100);<br />
vbox.addItem(scroll, 1);<br />
<br />
var scrollContent =<br />
scroll.getContent()<br />
.set("font", "LiberationFonts/LiberationSans-Bold.ttf")<br />
.set("character-size", 16)<br />
.set("alignment", "left-center");<br />
<br />
var list = canvas.VBoxLayout.new();<br />
scroll.setLayout(list);<br />
<br />
for (var i=1;i<=5;i+=1) {<br />
var label = canvas.gui.widgets.Label.new(scrollContent, canvas.style, {wordWrap: 0}); <br />
label.setImage("Textures/Splash"~i~".png");<br />
label.setFixedSize(256,256);<br />
list.addItem(label);<br />
}<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Using Layouts ==<br />
<br />
== Using Styling ==<br />
== Adding a HUD ==<br />
== Adding a 2D Instrument ==<br />
== Adding a 2D Panel ==<br />
== Adding a PFD ==<br />
<br />
== Adding a Failure Mgmt Widget ==<br />
{{Note|This kind of widget will typically be useful for dialogs requiring a method for managing aircraft specific system failures (e.g. an instructor console).}}<br />
<br />
== Adding a MapStructure map to a Canvas ==<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code <br />
|-<br />
| [[File:Snippets-canvas-mapstructure-dialog.png|thumb|[[MapStructure]] layers shown in a Canvas GUI dialog]]<br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. Equally, this snippet assumes that your canvas is named '''myCanvas'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
var TestMap = root.createChild("map");<br />
TestMap.setController("Aircraft position");<br />
TestMap.setRange(25); <br />
<br />
TestMap.setTranslation( myCanvas.get("view[0]")/2,<br />
myCanvas.get("view[1]")/2<br />
);<br />
var r = func(name,vis=1,zindex=nil) return caller(0)[0];<br />
<br />
foreach(var type; [r('APT'), r('VOR') ] )<br />
TestMap.addLayer(factory: canvas.SymbolLayer, type_arg: type.name, visible: type.vis, priority: type.zindex,);<br />
</syntaxhighlight><br />
<br />
|}<br />
<br />
== Customizing MapStructure Styling ==<br />
{{WIP}}<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code <br />
|-<br />
| [[File:Snippets-canvas-mapstructure-dialog.png|thumb|[[MapStructure]] layers shown in a Canvas GUI dialog]]<br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. Equally, this snippet assumes that your canvas is named '''myCanvas'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var TestMap = root.createChild("map");<br />
TestMap.setController("Aircraft position");<br />
TestMap.setRange(25); <br />
<br />
TestMap.setTranslation( myCanvas.get("view[0]")/2,<br />
myCanvas.get("view[1]")/2<br />
);<br />
var r = func(name,vis=1,zindex=nil) return caller(0)[0];<br />
var type = r('APT');<br />
var style_apt = {<br />
scale_factor:0.5,<br />
color_default:[0,1,0.9],<br />
line_width:4,<br />
label_font_color:[0,1,0.9],<br />
label_font_size:30<br />
};<br />
TestMap.addLayer(factory: canvas.SymbolLayer, type_arg: type.name, visible: type.vis, priority: type.zindex,style:style_apt);<br />
<br />
var type = r('VOR');<br />
var style_vor = {<br />
scale_factor:0.5,<br />
color:[0.1,0.9,0],<br />
line_width:4,<br />
text_color:[0.1,0.9,0]<br />
};<br />
TestMap.addLayer(factory: canvas.SymbolLayer, type_arg: type.name, visible: type.vis, priority: type.zindex,style:style_vor);<br />
<br />
### See ...fgdata/Nasal/canvas/map/APT.symbol ...fgdata/Nasal/canvas/map/VOR.style ... for the style variables that can be configured.<br />
<br />
</syntaxhighlight><br />
<br />
|<br />
<br />
== Using MapStructure and Overlays ==<br />
{{FGCquote<br />
|Support for overlays using geo-referenced raster images isn't too well-developed currently, so would need to work with a few hard-coded assumptions (e.g. being specific to a certain raster image and map layout) - but maybe TheTom can provide a few more ideas on how to proceed from here - otherwise, the Map is normally not aware of any non-Map items, i.e. as long as the overlay is added "outside" the Map, it isn't even aware of the raster image - and when it is added as a map element, it would probably be rotated. So there's still some work needed here. But generally, this should work well enough even in its current form (the screen shot is purely based on the Canvas Snippets article, i.e. it just displays a Canvas GUI dialog, adds the downloaded raster image and then adds the MapStructure APS layer - without the Map being aware of the overlay/geo-referencing that is needed currently).<br />
|{{cite web |url=http://forum.flightgear.org/viewtopic.php?p=238316#p238316<br />
|title=<nowiki>Re: Using Canvas for visualizing orbital flights (cont'd PM)</nowiki><br />
|author=<nowiki>Hooray</nowiki><br />
|date=<nowiki>Fri Apr 10</nowiki><br />
}}<br />
}}<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code <br />
|-<br />
| [[File:Canvas-overlay-with-mapstructure.png|thumb|Using the [[MapStructure]] framework in conjunction with raster images as overlays]]<br />
| {{Note|This assumes that you already have a top-level root group set up, and named it '''root''', just change this variable if you want it to be rendered elsewhere. Equally, this snippet assumes that your canvas is named '''myCanvas'''.}}<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
<br />
</syntaxhighlight><br />
|}<br />
<br />
== A simple tile map ==<br />
<br />
{| class="wikitable"<br />
|-<br />
! Screenshot !! Code <br />
|-<br />
| [[File:Canvas - Tile map demo.png|thumb|A simple, canvas based tile map which is centered around the aircraft.]]<br />
| <br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var (width,height) = (768,512);<br />
var tile_size = 256;<br />
<br />
var window = canvas.Window.new([width, height],"dialog")<br />
.set('title', "Tile map demo");<br />
var g = window.getCanvas(1)<br />
.createGroup();<br />
<br />
# Simple user interface (Buttons for zoom and label for displaying it)<br />
var zoom = 10;<br />
var type = "map";<br />
<br />
var ui_root = window.getCanvas().createGroup();<br />
var vbox = canvas.VBoxLayout.new();<br />
window.setLayout(vbox);<br />
<br />
<br />
var button_in = canvas.gui.widgets.Button.new(ui_root, canvas.style, {})<br />
.setText("+")<br />
.listen("clicked", func changeZoom(1));<br />
var button_out = canvas.gui.widgets.Button.new(ui_root, canvas.style, {})<br />
.setText("-")<br />
.listen("clicked", func changeZoom(-1));<br />
button_in.setSizeHint([32, 32]);<br />
button_out.setSizeHint([32, 32]);<br />
<br />
var label_zoom = canvas.gui.widgets.Label.new(ui_root, canvas.style, {});<br />
<br />
var button_box = canvas.HBoxLayout.new();<br />
button_box.addItem(button_in);<br />
button_box.addItem(label_zoom);<br />
button_box.addItem(button_out);<br />
button_box.addStretch(1);<br />
<br />
vbox.addItem(button_box);<br />
vbox.addStretch(1);<br />
<br />
var changeZoom = func(d)<br />
{<br />
zoom = math.max(2, math.min(19, zoom + d));<br />
label_zoom.setText("Zoom " ~ zoom);<br />
updateTiles();<br />
}<br />
<br />
# http://polymaps.org/docs/<br />
# https://github.com/simplegeo/polymaps<br />
# https://github.com/Leaflet/Leaflet<br />
<br />
var maps_base = getprop("/sim/fg-home") ~ '/cache/maps';<br />
<br />
# http://otile1.mqcdn.com/tiles/1.0.0/map<br />
# http://otile1.mqcdn.com/tiles/1.0.0/sat<br />
# (also see http://wiki.openstreetmap.org/wiki/Tile_usage_policy)<br />
var makeUrl =<br />
string.compileTemplate('http://otile1.mqcdn.com/tiles/1.0.0/{type}/{z}/{x}/{y}.jpg');<br />
var makePath =<br />
string.compileTemplate(maps_base ~ '/osm-{type}/{z}/{x}/{y}.jpg');<br />
var num_tiles = [4, 3];<br />
<br />
var center_tile_offset = [<br />
(num_tiles[0] - 1) / 2,<br />
(num_tiles[1] - 1) / 2<br />
];<br />
<br />
# simple aircraft icon at current position/center of the map<br />
g.createChild("path")<br />
.moveTo( tile_size * center_tile_offset[0] - 10,<br />
tile_size * center_tile_offset[1] )<br />
.horiz(20)<br />
.move(-10,-10)<br />
.vert(20)<br />
.set("stroke", "red")<br />
.set("stroke-width", 2)<br />
.set("z-index", 1);<br />
<br />
##<br />
# initialize the map by setting up<br />
# a grid of raster images <br />
<br />
var tiles = setsize([], num_tiles[0]);<br />
for(var x = 0; x < num_tiles[0]; x += 1)<br />
{<br />
tiles[x] = setsize([], num_tiles[1]);<br />
for(var y = 0; y < num_tiles[1]; y += 1)<br />
tiles[x][y] = g.createChild("image", "map-tile");<br />
}<br />
<br />
var last_tile = [-1,-1];<br />
var last_type = type;<br />
<br />
##<br />
# this is the callback that will be regularly called by the timer<br />
# to update the map<br />
var updateTiles = func()<br />
{<br />
# get current position<br />
var lat = getprop('/position/latitude-deg');<br />
var lon = getprop('/position/longitude-deg');<br />
<br />
var n = math.pow(2, zoom);<br />
var offset = [<br />
n * ((lon + 180) / 360) - center_tile_offset[0],<br />
(1 - math.ln(math.tan(lat * math.pi/180) + 1 / math.cos(lat * math.pi/180)) / math.pi) / 2 * n - center_tile_offset[1]<br />
];<br />
var tile_index = [int(offset[0]), int(offset[1])];<br />
<br />
var ox = tile_index[0] - offset[0];<br />
var oy = tile_index[1] - offset[1];<br />
<br />
for(var x = 0; x < num_tiles[0]; x += 1)<br />
for(var y = 0; y < num_tiles[1]; y += 1)<br />
tiles[x][y].setTranslation(int((ox + x) * tile_size + 0.5), int((oy + y) * tile_size + 0.5));<br />
<br />
if( tile_index[0] != last_tile[0]<br />
or tile_index[1] != last_tile[1]<br />
or type != last_type )<br />
{<br />
for(var x = 0; x < num_tiles[0]; x += 1)<br />
for(var y = 0; y < num_tiles[1]; y += 1)<br />
{<br />
var pos = {<br />
z: zoom,<br />
x: int(offset[0] + x),<br />
y: int(offset[1] + y),<br />
type: type<br />
};<br />
<br />
(func {<br />
var img_path = makePath(pos);<br />
var tile = tiles[x][y];<br />
<br />
if( io.stat(img_path) == nil )<br />
{ # image not found, save in $FG_HOME<br />
var img_url = makeUrl(pos);<br />
print('requesting ' ~ img_url);<br />
http.save(img_url, img_path)<br />
.done(func {print('received image ' ~ img_path); tile.set("src", img_path);})<br />
.fail(func (r) print('Failed to get image ' ~ img_path ~ ' ' ~ r.status ~ ': ' ~ r.reason));<br />
}<br />
else # cached image found, reusing<br />
{<br />
print('loading ' ~ img_path);<br />
tile.set("src", img_path)<br />
}<br />
})();<br />
}<br />
<br />
last_tile = tile_index;<br />
last_type = type;<br />
}<br />
};<br />
<br />
##<br />
# set up a timer that will invoke updateTiles at 2-second intervals<br />
var update_timer = maketimer(2, updateTiles);<br />
# actually start the timer<br />
update_timer.start();<br />
<br />
##<br />
# set up default zoom level<br />
changeZoom(0);<br />
<br />
<br />
###<br />
# The following lines were recently added and have not yet been tested<br />
# (if in doubt, remove them)<br />
window.del = func()<br />
{<br />
print("Cleaning up window:",title,"\n");<br />
update_timer.stop();<br />
# explanation for the call() technique at: http://wiki.flightgear.org/Object_oriented_programming_in_Nasal#Making_safer_base-class_calls<br />
call(canvas.Window.del, [], me);<br />
};<br />
<br />
<br />
</syntaxhighlight><br />
|}<br />
<br />
== Adding a NavDisplay ==<br />
<br />
== Adding a CDU ==<br />
<br />
== Adding a Multi-Function Display (MFD) ==</div>Clm76https://wiki.flightgear.org/w/index.php?title=Howto:Prototyping_a_new_NavDisplay_Style&diff=104789Howto:Prototyping a new NavDisplay Style2016-10-12T15:53:57Z<p>Clm76: /* Status */</p>
<hr />
<div>{{Stub}}<br />
[[File:CanvasND development via PUI.png|thumb|Screenshot showing a [[PUI]] dialog with two embedded [[Canvas]] regions for displaying two independent [[NavDisplay]] instances.]]<br />
== Objective ==<br />
Demonstrate how a simple PUI/XML dialog can be used to easily prototype new [[NavDisplay]] styles, showing two instances for each pilot, which can be controlled/tested independently.<br />
<br />
== Approach ==<br />
This is a PUI/XML dialog with two embedded CanvasWidget areas that instantiate independent ND instances using a subset of the code commonly found in the aircraft specific ND.nas file, adapted to use the embedded Canvas region for rendering the two NDs and GUI buttons/widgets added to control the whole thing without necessarily requiring a fully developed cockpit.<br />
<br />
== Roadmap ==<br />
* add buttons for controlling each ND instance (range, zoom, centering)<br />
* use io.include to directly reload the styles stuff (for rapid prototyping)<br />
* procedurally add buttons for each switch by enhancing the myCockpit_switches hash with legends/labels for the UI use-case (use checkboxes for boolean props)<br />
* add a dropdown menu to select the position source (main aircraft vs. AI/MP traffic)<br />
<br />
== Status ==<br />
For now this is heavily based on ideas, and code, borrowed from the original [[MapStructure Debugger]] (code still available at [https://gitorious.org/fg/canvas-hackers-fgdata?p=fg:canvas-hackers-fgdata.git;a=blob_plain;f=gui/dialogs/mapstructure-debugger.xml;hb=42dbf52623c7596c7446ede439235cc0016f99c8])<br />
<br />
{{WIP}}<br />
<br />
{{Note|For testing purposes, put the following dialog into $FG_ROOT/gui/dialogs/canvas-nd.xml and use the [[Nasal Console]] to run the dialog (or extend the [[Menubar]] accordingly):<br />
<syntaxhighlight lang="nasal">fgcommand("dialog-show", props.Node.new({'dialog-name':'canvas-nd'}) );</syntaxhighlight><br />
}}<br />
<br />
<syntaxhighlight lang="xml"><br />
<?xml version="1.0" encoding="UTF-8"?><br />
<br />
<PropertyList><br />
<br />
<name>canvas-nd</name><br />
<modal>false</modal><br />
<layout>vbox</layout><br />
<text><br />
<label>Canvas ND</label><br />
</text><br />
<br />
<nasal><br />
<open><![CDATA[<br />
print("nasal/opening block");<br />
var show_canvas_id = func(c) {<br />
print("Canvas is:", c.getPath());<br />
};<br />
<br />
# to be used for shutting down each created instances upon closing the dialog (see the close block below)<br />
var MFDInstances = [];<br />
<br />
#### <br />
## an adapted version of ND.nas<br />
##<br />
<br />
var setupND = func(property_root, my_canvas) {<br />
<br />
var myCockpit_switches = {<br />
# symbolic alias : relative property (as used in bindings), initial value, type<br />
'toggle_range': {path: '/inputs/range-nm', value:40, type:'INT'},<br />
'toggle_weather': {path: '/inputs/wxr', value:0, type:'BOOL'},<br />
'toggle_airports': {path: '/inputs/arpt', value:0, type:'BOOL'},<br />
'toggle_stations': {path: '/inputs/sta', value:0, type:'BOOL'},<br />
'toggle_waypoints': {path: '/inputs/wpt', value:0, type:'BOOL'},<br />
'toggle_position': {path: '/inputs/pos', value:0, type:'BOOL'},<br />
'toggle_data': {path: '/inputs/data',value:0, type:'BOOL'},<br />
'toggle_terrain': {path: '/inputs/terr',value:0, type:'BOOL'},<br />
'toggle_traffic': {path: '/inputs/tfc',value:0, type:'BOOL'},<br />
'toggle_centered': {path: '/inputs/nd-centered',value:0, type:'BOOL'},<br />
'toggle_lh_vor_adf': {path: '/inputs/lh-vor-adf',value:0, type:'INT'},<br />
'toggle_rh_vor_adf': {path: '/inputs/rh-vor-adf',value:0, type:'INT'},<br />
'toggle_display_mode': {path: '/mfd/display-mode', value:'MAP', type:'STRING'},<br />
'toggle_display_type': {path: '/mfd/display-type', value:'LCD', type:'STRING'},<br />
'toggle_true_north': {path: '/mfd/true-north', value:0, type:'BOOL'},<br />
'toggle_rangearc': {path: '/mfd/rangearc', value:0, type:'BOOL'},<br />
'toggle_track_heading': {path: '/hdg-trk-selected', value:0, type:'BOOL'},<br />
'toggle_hdg_bug_only': {path: '/hdg-bug-only', value:0, type:'BOOL'},<br />
# add new switches here<br />
};<br />
<br />
###<br />
# entry point, this will set up an ND instance<br />
<br />
# get a handle to the NavDisplay in canvas namespace (for now), see $FG_ROOT/Nasal/canvas/map/navdisplay.mfd<br />
var ND = canvas.NavDisplay;<br />
<br />
##<br />
# set up a new ND instance, under 'instrumentation/efis' and use the<br />
# myCockpit_switches hash to map control properties<br />
# FIXME: use cmdarg() here to use a dialog specific path for all switches<br />
var myND = ND.new("instrumentation/efis", myCockpit_switches, 'Boeing');<br />
<br />
var group = my_canvas.createGroup();<br />
myND.newMFD(group, my_canvas);<br />
myND.update();<br />
# store the instance for later cleanup<br />
append(MFDInstances, myND);<br />
<br />
return myND;<br />
} # setupND()<br />
]]></open><br />
<br />
<close><![CDATA[<br />
print("nasal/closing block");<br />
foreach(var mfd; MFDInstances) {<br />
mfd.del();<br />
}<br />
]]></close><br />
</nasal><br />
<br />
<group><br />
<layout>hbox</layout><br />
<br />
<canvas><br />
<name>mfd1</name><br />
<valign>fill</valign><br />
<halign>fill</halign><br />
<stretch>true</stretch><br />
<pref-width>512</pref-width><br />
<pref-height>512</pref-height><br />
<view>1024</view><br />
<view>1024</view><br />
<nasal> <br />
<!--<br />
this is the Nasal/canvas section where you can run your own Nasal code <br />
to access the canvas section <br />
--><br />
<load><![CDATA[<br />
# you can add your canvas-specific code here<br />
var my_canvas = canvas.get(cmdarg()); # this will get a handle to the parent canvas:<br />
show_canvas_id(my_canvas);<br />
setupND(property_root: cmdarg(), my_canvas: my_canvas);<br />
]]></load><br />
</nasal><br />
</canvas><br />
<br />
<canvas><br />
<name>mfd2</name><br />
<valign>fill</valign><br />
<halign>fill</halign><br />
<stretch>true</stretch><br />
<pref-width>512</pref-width><br />
<pref-height>512</pref-height><br />
<view>1024</view><br />
<view>1024</view><br />
<nasal> <br />
<!--<br />
this is the Nasal/canvas section where you can run your own Nasal code <br />
to access the canvas section <br />
--><br />
<load><![CDATA[<br />
# you can add your canvas-specific code here<br />
var my_canvas = canvas.get(cmdarg()); # this will get a handle to the parent canvas:<br />
show_canvas_id(my_canvas);<br />
setupND(property_root: cmdarg(), my_canvas: my_canvas);<br />
]]></load><br />
</nasal><br />
</canvas><br />
<br />
</group><br />
<br />
<group><br />
<layout>hbox</layout><br />
<br />
<button><br />
<legend>Reload</legend><br />
<default>1</default><br />
<border>2</border><br />
<binding><br />
<command>reinit</command><br />
<subsystem>gui</subsystem><br />
</binding><br />
</button><br />
<br />
<button><br />
<legend>Exit</legend><br />
<equal>true</equal><br />
<key>Esc</key><br />
<binding><br />
<command>dialog-close</command><br />
</binding><br />
</button><br />
<br />
</group><br />
<br />
</PropertyList><br />
</syntaxhighlight></div>Clm76https://wiki.flightgear.org/w/index.php?title=Nasal_library&diff=85151Nasal library2015-05-30T07:29:20Z<p>Clm76: /* airportinfo() */</p>
<hr />
<div>{{Nasal Navigation}}<br />
<br />
This page documents the core library functions of FlightGear's built-in scripting language, [[Nasal]]. The relevant folders in [[Git]] are:<br />
* {{Repo link|site=s|proj=flightgear/flightgear|type=git|path=src/Scripting}}<br />
* {{Repo link|site=s|proj=flightgear/simgear|type=git|path=simgear/nasal}}<br />
<br />
{{Note|Feel free to copy & paste the examples into your [[Nasal Console]] and execute them to see what they do.}}<br />
<br />
== Core library ==<br />
This is the list of the basic core library functions that were in Nasal before its integration in to FlightGear. See also:<br />
* http://plausible.org/nasal/lib.html ([http://web.archive.org/web/20101010094553/http://plausible.org/nasal/lib.html archive])<br />
* {{Repo link|site=s|proj=flightgear/simgear|type=git|path=simgear/nasal/lib.c|lines=590}} (lines 590-619)<br />
<br />
{{Nasal doc<br />
|name = append<br />
|source = core<br />
|line = 42<br />
|syntax = <syntaxhighlight lang="nasal">append(vector, element[, element[, ...]]);</syntaxhighlight><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 />
|heading = ===<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 = <syntaxhighlight lang="nasal"><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 />
</syntaxhighlight><br />
|example2 = <syntaxhighlight lang="nasal"><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 />
</syntaxhighlight><br />
}}<br />
<br />
{{Nasal doc<br />
|name = bind<br />
|source = core<br />
|line = 502<br />
|syntax = <syntaxhighlight lang="nasal">bind(function, locals[, outer_scope]);</syntaxhighlight><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 />
|heading = ===<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 = <syntaxhighlight lang="nasal"><br />
# 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 6 from 12 by AnotherNamespace.ret()<br />
print(Namespace.key);<br />
</syntaxhighlight><br />
}}<br />
<br />
{{Nasal doc<br />
|name = call<br />
|source = core<br />
|line = 247<br />
|heading = ===<br />
|syntax = <syntaxhighlight lang="nasal">call(func[, args[, me[, locals[, error]]]);</syntaxhighlight><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=https://gitorious.org/fg/fgdata/source/master:Nasal/debug.nas#L398}}.<br />
|example1 = <syntaxhighlight lang="nasal"><br />
# prints "Called from call()"<br />
call(func {<br />
print("Called from call()");<br />
});<br />
</syntaxhighlight><br />
<br />
|example2 = <syntaxhighlight lang="nasal"><br />
# prints "a = 1 : b = 2<br />
call(func(a, b){<br />
print("a = ", a, " : b = ", b);<br />
},<br />
[1, 2]<br />
);<br />
</syntaxhighlight><br />
<br />
|example3 = <syntaxhighlight lang="nasal"><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 />
</syntaxhighlight><br />
<br />
|example4 = <syntaxhighlight lang="nasal"><br />
# prints the value of math.pi<br />
call(func {<br />
print(pi);<br />
}, nil, nil, <br />
math<br />
);<br />
</syntaxhighlight><br />
<br />
|example5 = <syntaxhighlight lang="nasal"><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 />
</syntaxhighlight><br />
}}<br />
<br />
{{Nasal doc<br />
|name = caller<br />
|source = core<br />
|line = 404<br />
|heading = ===<br />
|syntax = <syntaxhighlight lang="nasal">caller([level]);</syntaxhighlight><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 = <syntaxhighlight lang="nasal"><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 />
</syntaxhighlight><br />
<br />
|example2 = <syntaxhighlight lang="nasal"><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 />
</syntaxhighlight><br />
<br />
|example3text = This is a real example taken from <tt>''[[$FG_ROOT]]/Nasal/canvas/MapStructure.nas''</tt>. <code>r();</code> (highlighted) 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 = <syntaxhighlight lang="nasal" line start="66" highlight="13" enclose="div"><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 />
</syntaxhighlight><br />
}}<br />
<br />
{{Nasal doc<br />
|name = chr<br />
|source = core<br />
|line = 175<br />
|heading = ===<br />
|syntax = <syntaxhighlight lang="nasal">chr(code);</syntaxhighlight><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 http://en.wikipedia.org/wiki/ASCII#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 = <syntaxhighlight lang="nasal"><br />
print("Code 65 = ", chr(65)); # prints "Code 65 = A"<br />
</syntaxhighlight><br />
<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 = <syntaxhighlight lang="nasal"><br />
for(var i = 0; i <= 255; i += 1){<br />
print("Code ", i, " = >", chr(i), "<");<br />
}<br />
</syntaxhighlight><br />
}}<br />
<br />
{{Nasal doc<br />
|name = closure<br />
|source = core<br />
|line = 421<br />
|heading = ===<br />
|syntax = <syntaxhighlight lang="nasal">closure(func[, level]);</syntaxhighlight><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 = <syntaxhighlight lang="nasal" enclose="div"><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 />
</syntaxhighlight><br />
}}<br />
<br />
{{Nasal doc<br />
|name = cmp<br />
|source = core<br />
|line = 112<br />
|heading = ===<br />
|syntax = <syntaxhighlight lang="nasal">cmp(a, b);</syntaxhighlight><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 = <syntaxhighlight lang="nasal"><br />
print(cmp("1", "two")); # prints -1<br />
</syntaxhighlight><br />
|example2 = <syntaxhighlight lang="nasal"><br />
print(cmp("string", "string")); # prints 0<br />
</syntaxhighlight><br />
|example3 = <syntaxhighlight lang="nasal"><br />
print(cmp("one", "2")); # prints 1<br />
</syntaxhighlight><br />
|example4 = <syntaxhighlight lang="nasal"><br />
print(cmp("string1", "string2")); # prints -1<br />
</syntaxhighlight><br />
}}<br />
<br />
{{Nasal doc<br />
|name = compile<br />
|source = core<br />
|line = 220<br />
|heading = ===<br />
|syntax = <syntaxhighlight lang="nasal">compile(code[, filename]);</syntaxhighlight><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 = <syntaxhighlight lang="nasal"><br />
var myCode = 'print("hello");';<br />
var helloFunc = compile(myCode, "myCode");<br />
helloFunc();<br />
</syntaxhighlight><br />
<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 = <syntaxhighlight lang="nasal"><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 />
</syntaxhighlight><br />
}}<br />
<br />
{{Nasal doc<br />
|name = contains<br />
|source = core<br />
|line = 184<br />
|heading = ===<br />
|syntax = <syntaxhighlight lang="nasal">contains(hash, key);</syntaxhighlight><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 = <syntaxhighlight lang="nasal"><br />
# Initialize a hash<br />
var hash = {<br />
element: "value"<br />
};<br />
print(contains(hash, "element") ? "Yes" : "No"); # This will print "Yes"<br />
</syntaxhighlight><br />
<br />
|example2 = <syntaxhighlight lang="nasal"><br />
# Initialize a hash<br />
var hash = {<br />
element: "value"<br />
};<br />
print(contains(hash, "element2") ? "Yes" : "No"); # This will print "No"<br />
</syntaxhighlight><br />
}}<br />
<br />
{{Nasal doc<br />
|name = delete<br />
|source = core<br />
|line = 83<br />
|heading = ===<br />
|syntax = <syntaxhighlight lang="nasal">delete(hash, key);</syntaxhighlight><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 />
<br />
|example1 = <syntaxhighlight lang="nasal"><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 />
</syntaxhighlight><br />
}}<br />
<br />
{{Nasal doc<br />
|name = die<br />
|source = core<br />
|line = 288<br />
|heading = ===<br />
|syntax = <syntaxhighlight lang="nasal">die(error);</syntaxhighlight><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 />
<br />
|example1 = <syntaxhighlight lang="nasal"><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 />
</syntaxhighlight><br />
}}<br />
<br />
{{Nasal doc<br />
|name = find<br />
|source = core<br />
|line = 450<br />
|heading = ===<br />
|syntax = <syntaxhighlight lang="nasal">find(needle, haystack);</syntaxhighlight><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 />
<br />
|example1 = <syntaxhighlight lang="nasal"><br />
print(find("c", "abcdef")); # prints 2<br />
</syntaxhighlight><br />
<br />
|example2 = <syntaxhighlight lang="nasal"><br />
print(find("x", "abcdef")); # prints -1<br />
</syntaxhighlight><br />
<br />
|example3 = <syntaxhighlight lang="nasal"><br />
print(find("cd", "abcdef")); # prints 2<br />
</syntaxhighlight><br />
}}<br />
<br />
{{Nasal doc<br />
|name = ghosttype<br />
|source = core<br />
|line = 207<br />
|heading = ===<br />
|syntax = <syntaxhighlight lang="nasal">ghosttype(ghost);</syntaxhighlight><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 />
}}<br />
<br />
{{Nasal doc<br />
|name = id<br />
|source = core<br />
|line = 570<br />
|heading = ===<br />
|syntax = <syntaxhighlight lang="nasal">id(object);</syntaxhighlight><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 />
<br />
|example1 = <syntaxhighlight lang="nasal"><br />
print(id("A")); # prints "str:000000001624A590"<br />
</syntaxhighlight><br />
}}<br />
<br />
{{Nasal doc<br />
|name = int<br />
|source = core<br />
|line = 90<br />
|heading = ===<br />
|syntax = <syntaxhighlight lang="nasal">int(number);</syntaxhighlight><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 />
<br />
|example1 = <syntaxhighlight lang="nasal"><br />
print(int(23)); # prints "23"<br />
</syntaxhighlight><br />
<br />
|example2 = <syntaxhighlight lang="nasal"><br />
print(int(23.123)); # prints "23"<br />
</syntaxhighlight><br />
<br />
|example3 = <syntaxhighlight lang="nasal"><br />
debug.dump(int("string")); # prints "nil"<br />
</syntaxhighlight><br />
}}<br />
<br />
{{Nasal doc<br />
|name = keys<br />
|source = core<br />
|line = 33<br />
|heading = ===<br />
|syntax = <syntaxhighlight lang="nasal">keys(hash);</syntaxhighlight><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 />
<br />
|example1 = <syntaxhighlight lang="nasal"><br />
# Initialize a hash<br />
var hash = {<br />
element1: "value",<br />
element2: "value"<br />
};<br />
debug.dump(keys(hash)); # print the vector<br />
</syntaxhighlight><br />
}}<br />
<br />
{{Nasal doc<br />
|name = left<br />
|source = core<br />
|line = 149<br />
|version = 2.12.0+<br />
|heading = ===<br />
|syntax = <syntaxhighlight lang="nasal">left(string, length);</syntaxhighlight><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 />
<br />
|example1 = <syntaxhighlight lang="nasal"><br />
print(left("string", 2)); # prints "st"<br />
</syntaxhighlight><br />
}}<br />
<br />
{{Nasal doc<br />
|name = num<br />
|source = core<br />
|line = 102<br />
|heading = ===<br />
|syntax = <syntaxhighlight lang="nasal">num(number);</syntaxhighlight><br />
|text = Returns the numerical value of the single striing 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 />
<br />
|example1 = <syntaxhighlight lang="nasal"><br />
print(num("23")); # prints "23"<br />
</syntaxhighlight><br />
<br />
|example2 = <syntaxhighlight lang="nasal"><br />
print(num("23.123")); # prints "23.123"<br />
</syntaxhighlight><br />
<br />
|example3 = <syntaxhighlight lang="nasal"><br />
debug.dump(num("string")); # prints "nil"<br />
</syntaxhighlight><br />
}}<br />
<br />
{{Nasal doc<br />
|name = pop<br />
|source = core<br />
|line = 50<br />
|heading = ===<br />
|syntax = <syntaxhighlight lang="nasal">pop(vector);</syntaxhighlight><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 />
<br />
|example1 = <syntaxhighlight lang="nasal"><br />
var vector = [1, 2, 3];<br />
pop(vector);<br />
debug.dump(vector); # prints "[1, 2]"<br />
</syntaxhighlight><br />
<br />
|example2 = <syntaxhighlight lang="nasal"><br />
var vector = [1, 2, 3];<br />
debug.dump(pop(vector)); # prints "3"<br />
</syntaxhighlight><br />
<br />
|example3 = <syntaxhighlight lang="nasal"><br />
var vector = [];<br />
debug.dump(pop(vector)); # prints "nil"<br />
</syntaxhighlight><br />
}}<br />
<br />
{{Nasal doc<br />
|name = right<br />
|source = core<br />
|line = 161<br />
|version = 2.12.0+<br />
|heading = ===<br />
|syntax = <syntaxhighlight lang="nasal">right(string, length);</syntaxhighlight><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 />
<br />
|example1 = <syntaxhighlight lang="nasal"><br />
print(right("string", 2)); # prints "ng"<br />
</syntaxhighlight><br />
}}<br />
<br />
{{Nasal doc<br />
|name = setsize<br />
|source = core<br />
|line = 56<br />
|heading = ===<br />
|syntax = <syntaxhighlight lang="nasal">setsize(vector, size);</syntaxhighlight><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 />
<br />
|example1 = <syntaxhighlight lang="nasal"><br />
var vector = [1, 2, 3]; # Initialize a vector<br />
setsize(vector, 4);<br />
debug.dump(vector); # print the vector<br />
</syntaxhighlight><br />
<br />
|example2 = <syntaxhighlight lang="nasal"><br />
var vector = [1, 2, 3]; # Initialize a vector<br />
setsize(vector, 2);<br />
debug.dump(vector); # print the vector<br />
</syntaxhighlight><br />
}}<br />
<br />
{{Nasal doc<br />
|name = size<br />
|source = core<br />
|line = 23<br />
|heading = ===<br />
|syntax = <syntaxhighlight lang="nasal">size(object);</syntaxhighlight><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 arguent 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 />
<br />
|example1 = <syntaxhighlight lang="nasal"><br />
var string = "string";<br />
print(size(string)); # prints "6"<br />
</syntaxhighlight><br />
<br />
|example2 = <syntaxhighlight lang="nasal"><br />
var vector = [1, 2, 3];<br />
print(size(vector)); # prints "3"<br />
</syntaxhighlight><br />
<br />
|example3 = <syntaxhighlight lang="nasal"><br />
var hash = {<br />
element1: "value1",<br />
element2: "value2",<br />
element3: "value3"<br />
};<br />
print(size(hash)); # prints "3"<br />
</syntaxhighlight><br />
}}<br />
<br />
{{Nasal doc<br />
|name = sort<br />
|source = core<br />
|line = 542<br />
|heading = ===<br />
|syntax = <syntaxhighlight lang="nasal">sort(vector, function);</syntaxhighlight><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 = <syntaxhighlight lang="nasal"><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 />
</syntaxhighlight><br />
<br />
|example1text = This example sorts elements from greatest to smallest.<br />
|example2 = <syntaxhighlight lang="nasal"><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 />
</syntaxhighlight><br />
}}<br />
<br />
{{Nasal doc<br />
|name = split<br />
|source = core<br />
|line = 460<br />
|heading = ===<br />
|syntax = <syntaxhighlight lang="nasal">split(delimiter, string);</syntaxhighlight><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 />
<br />
|example1 = <syntaxhighlight lang="nasal"><br />
debug.dump(split("cd", "abcdef")); # prints "['ab', 'ef']"<br />
</syntaxhighlight><br />
<br />
|example2 = <syntaxhighlight lang="nasal"><br />
debug.dump(split(".", "3.2.0")); # prints "[3, 2, 0]"<br />
</syntaxhighlight><br />
<br />
|example3 = <syntaxhighlight lang="nasal"><br />
debug.dump(split("/", "path/to/file")); # prints "['path', 'to', 'file']"<br />
</syntaxhighlight><br />
}}<br />
<br />
{{Nasal doc<br />
|name = sprintf<br />
|source = core<br />
|line = 355<br />
|heading = ===<br />
|syntax = <syntaxhighlight lang="nasal">sprintf(format[, arg[, arg, [...]]]);</syntaxhighlight><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 = https://gitorious.org/fg/simgear/source/next:simgear/nasal/lib.c#L308<br />
|title = fg/simgear/source/next:simgear/nasal/lib.c, line 308<br />
|accessdate = February 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 supported <ref><br />
{{Cite web<br />
|url = https://gitorious.org/fg/simgear/source/next:simgear/nasal/lib.c#L389<br />
|title = fg/simgear/source/next:simgear/nasal/lib.c, line 389<br />
|accessdate = February 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 = <syntaxhighlight lang="nasal"><br />
print(sprintf("%i", 54)); # prints "54"<br />
</syntaxhighlight><br />
<br />
|example2 = <syntaxhighlight lang="nasal"><br />
print(sprintf("Pi = %+.10f", math.pi)); # prints "Pi = +3.1415926536"<br />
</syntaxhighlight><br />
<br />
|example3 = <syntaxhighlight lang="nasal"<br />
>print(sprintf("%6d", 23)); # prints " 23"<br />
print(sprintf("%06d", 23)); # prints "000023"<br />
</syntaxhighlight><br />
<br />
|example4 = <syntaxhighlight lang="nasal"><br />
var FGVer = getprop("/sim/version/flightgear");<br />
print(sprintf("You have FlightGear v%s", FGVer)); # prints "You have FlightGear v<your version>"<br />
</syntaxhighlight><br />
<br />
|example5 = <syntaxhighlight lang="nasal"><br />
print(sprintf("Hexadecimal 100000 = %X", 100000)); # prints "Hexadecimal 100000 = 186A0"<br />
print(sprintf("Hexadecimal 100000 = %x", 100000)); # prints "Hexadecimal 100000 = 186a0"<br />
</syntaxhighlight><br />
<br />
|example6 = <syntaxhighlight lang="nasal"><br />
print(sprintf("Code 65 is %c", 65)); # prints "Code 65 is A"<br />
</syntaxhighlight><br />
<br />
|example7 = <syntaxhighlight lang="nasal"><br />
print(sprintf("%e", 54)); # prints "5.400000e+001"<br />
print(sprintf("%E", 54)); # prints "5.400000E+001"<br />
</syntaxhighlight><br />
<br />
|example8 = <syntaxhighlight lang="nasal"><br />
print(sprintf("%o", 54)); # prints "66"<br />
</syntaxhighlight><br />
<br />
|example9 = <syntaxhighlight lang="nasal"><br />
print(sprintf("50%% of 100 is %i", 100 / 2)); # prints "50% of 100 is 50"<br />
</syntaxhighlight><br />
}}<br />
<br />
{{Nasal doc<br />
|name = streq<br />
|source = core<br />
|line = 107<br />
|heading = ===<br />
|syntax = <syntaxhighlight lang="nasal">streq(a, b);</syntaxhighlight><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 />
<br />
|example1 = <syntaxhighlight lang="nasal"><br />
print(streq("0", "0")); # prints "1" (True)<br />
</syntaxhighlight><br />
<br />
|example2 = <syntaxhighlight lang="nasal"><br />
print(0 == 0.0); # prints "1" (True)<br />
print(streq("0", "0.0")); # prints "0" (False)<br />
</syntaxhighlight><br />
}}<br />
<br />
{{Nasal doc<br />
|name = substr<br />
|source = core<br />
|line = 129<br />
|heading = ===<br />
|syntax = <syntaxhighlight lang="nasal">substr(string, start [, length]);</syntaxhighlight><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 />
<br />
|example1 = <syntaxhighlight lang="nasal"><br />
print(substr("abcde", 1, 3)); # prints "bcd"<br />
</syntaxhighlight><br />
<br />
|example2 = <syntaxhighlight lang="nasal"><br />
print(substr("abcde", 1)); # prints "bcde"<br />
</syntaxhighlight><br />
<br />
|example3 = <syntaxhighlight lang="nasal"><br />
print(substr("abcde", 2, 1)); # prints "c"<br />
</syntaxhighlight><br />
}}<br />
<br />
{{Nasal doc<br />
|name = subvec<br />
|source = core<br />
|line = 63<br />
|heading = ===<br />
|syntax = <syntaxhighlight lang="nasal">subvec(vector, start[, length]);</syntaxhighlight><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-vetor within the given vector.<br />
|param3 = length<br />
|param3text = Optional argument specifying the length of the sub-vector, from the starting point.<br />
<br />
|example1 = <syntaxhighlight lang="nasal"><br />
var vector = [1, 2, 3];<br />
debug.dump(subvec(vector, 0)); # prints "[1, 2, 3]"<br />
</syntaxhighlight><br />
<br />
|example2 = <syntaxhighlight lang="nasal"><br />
var vector = [1, 2, 3];<br />
debug.dump(subvec(vector, 1)); # prints "[2, 3]"<br />
</syntaxhighlight><br />
<br />
|example3 = <syntaxhighlight lang="nasal"><br />
var vector = [1, 2, 3];<br />
debug.dump(subvec(vector, 1, 1)); # prints "[2]"<br />
</syntaxhighlight><br />
}}<br />
<br />
{{Nasal doc<br />
|name = typeof<br />
|source = core<br />
|line = 193<br />
|heading = ===<br />
|syntax = <syntaxhighlight lang="nasal">typeof(object);</syntaxhighlight><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 = <syntaxhighlight lang="nasal"><br />
var object = nil;<br />
print(typeof(object)); # prints "nil"<br />
</syntaxhighlight><br />
<br />
|example2 = <syntaxhighlight lang="nasal"><br />
var object = "Hello world!";<br />
print(typeof(object)); # prints "scalar"<br />
</syntaxhighlight><br />
<br />
|example3 = <syntaxhighlight lang="nasal"><br />
var object = math.pi;<br />
print(typeof(object)); # prints "scalar"<br />
</syntaxhighlight><br />
<br />
|example4 = <syntaxhighlight lang="nasal"><br />
var object = [1, 2, 3];<br />
print(typeof(object)); # prints "vector"<br />
</syntaxhighlight><br />
<br />
|example5 = <syntaxhighlight lang="nasal"><br />
var object = {};<br />
print(typeof(object)); # prints "hash"<br />
</syntaxhighlight><br />
<br />
|example6 = <syntaxhighlight lang="nasal"><br />
var object = func {};<br />
print(typeof(object)); # prints "func"<br />
</syntaxhighlight><br />
}}<br />
<br />
== Extension functions ==<br />
<br />
=== <tt>cmdarg()</tt> ===<br />
cmdarg() is a mechanism to pass arguments to a nasal script (wrapped in properties) instead of "normal" function parameters. Note that cmdarg() should be primarily used in Nasal code embedded in XML files and should be considered depreciated otherwise (see [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg18361.html]).<br />
<br />
cmdarg() will keep working in (joystick) XML-'''bindings''' and on the top-level of embedded Nasal scripts (i.e. dialog and animation XML files).<br />
<br />
As such, the cmdarg() function is primarily used for listener callbacks declared in XML markup, cmdarg() returns the listened-to property as props.Node object, so you can use it with all its methods (see [[$FG_ROOT]]/Nasal/props.nas) for example:<br />
<br />
<syntaxhighlight lang="nasal"><br />
print(cmdarg().getPath(), " has been changed to ", cmdarg().getValue())<br />
</syntaxhighlight><br />
<br />
The cmdarg() function avoids that you have to type the exact same path twice (once here and once in the setlistener() command) and it makes clear that this is the listened to property. Also, you can use all the nice props.Node methods on cmdarg() directly:<br />
<br />
<syntaxhighlight lang="nasal"><br />
setlistener("/gear/launchbar/state", func {<br />
if (cmdarg().getValue() == "Engaged")<br />
setprop("/sim/messages/copilot", "Engaged!");<br />
}, 1, 0);<br />
</syntaxhighlight><br />
<br />
Use of cmdarg() outside of XML-bindings won't cause an error, but (still) return the last cmdarg() property. This just won't be the listened-to property anymore, but whatever the last legitimate cmdarg() user set. Most of the time it will be the property root of a joystick binding.<br />
<br />
Don't make any assumptions and use cmdarg() only in one of these cases:<br />
<br />
* binding: returns root of this binding's property branch. Needed for accessing an axis' value: cmdarg().getNode("setting").getValue()<br />
<br />
* dialog xml files: returns root of that file's property branch in memory. This can be used to let embedded Nasal change the dialog (e.g. clear and build lists) before the final layout is decided<br />
<br />
* animation xml files: returns root of this model's place in /ai/models/ when used as AI/MP model. Examples: /ai/models/multiplayer[3], /ai/models/tanker[1], etc.<ref>{{cite web |url=http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg14164.html |title=multiplayer generic properties |date=8 December 2007 |author=Melchior Franz}}</ref><br />
<br />
* AI aircraft XML files<br />
<br />
* remotely invoking Nasal code by setting properties using the built-in telnet daemon (RPC)<ref>{{cite web |url=http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg00150.html |title=Calling FG functions via network interface |author=Melchior Franz |date=2 January 2006}}</ref><ref>{{cite web |url=http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg00336.html |title=Calling FG functions via network interface |author=Melchior Franz |date=7 January 2006}}</ref>.<br />
<br />
'''In all cases, the cmdarg() call must not be delayed until later using settimer() or setlistener(). Because later it'll again return some unrelated property!<br />
'''<br />
<br />
=== <tt>fgcommand()</tt> ===<br />
<br />
Runs an internal "fgcommand", see [[Bindings]] for a full list of available items (since they are most often used in bindings for input devices). The first argument is the name of the command (e.g. "property-interpolate") and the second is a props.Node object or its ghost which is the "argument" to the fgcommand. (This ensures that fgcommands are universal since props.Node/SGPropertyNode objects can really be accessed from anywhere in FlightGear.) Each fgcommand returns 1 if it succeeded or 0 if it failed.<br />
<br />
The profiling related fgcommands '''profiler-start''' and '''profiler-stop''' are documented at [[Built-in Profiler]].<br />
<br />
=== <tt>addcommand()</tt> ===<br />
<br />
Add a fgcommand which can be used like a regular fgcommand (global scope, etc.). First argument is the name, second is the function to run. Note that this fgcommand will always return true! Inside the callback/function one can use either cmdarg() to retrieve the arguments or use the first argument passed to the function (since they will be the same).<br />
<br />
=== <tt>removecommand()</tt> ===<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 />
=== <tt>print()</tt> ===<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 />
=== <tt>logprint()</tt> ===<br />
<br />
Similar, but the first argument is reserved for number specifying the priority (i.e. matching a sgDebugPriority object: 1 for bulk, 2 for debug, 3 for info, and 4 for warn). Also see <tt>printlog()</tt> in globals.nas: it does essentially the same but with named levels ("bulk", etc.). (The latter relies on <tt>print()</tt>, however, and does not make use of the sophistication of <tt>sglog</tt> in dealing with source file and line number.)<br />
<br />
=== <tt>getprop()</tt> ===<br />
<br />
Returns the node value for a given path, or <tt>nil</tt> if the node doesn't exist or hasn't been initialized to a value yet. <br />
<br />
<syntaxhighlight lang="nasal"><br />
getprop(<path> [, <path>, [...]]);<br />
</syntaxhighlight><br />
<br />
Several arguments will be added together to produce a path, with numeric arguments specifying indexes (as of FlightGear 3.1), so<br />
<syntaxhighlight lang="nasal"><br />
getprop("canvas/by-index", "texture", 1, "name");<br />
</syntaxhighlight><br />
is the same as:<br />
<syntaxhighlight lang="nasal"><br />
getprop("canvas/by-index/texture[1]/name");<br />
</syntaxhighlight><br />
<br />
Example:<br />
<br />
<syntaxhighlight lang="nasal"><br />
print("The frame rate is ", getprop("/sim/frame-rate"), " FPS");<br />
for (var i=0; i < 10; i += 1) {<br />
print("View ", i, "'s name is: ", getprop("/sim/view", i, "name"));<br />
}<br />
</syntaxhighlight><br />
<br />
=== <tt>setprop()</tt> ===<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 />
=== <tt>interpolate()</tt> ===<br />
Give the value from a value or a source node to a destination node in given time.<br />
<br />
<syntaxhighlight lang="nasal"><br />
interpolate(<path>, <value>, <time> [, <value2>, <time2> [, ...]]);<br />
</syntaxhighlight><br />
<br />
Examples:<br />
<syntaxhighlight lang="nasal"><br />
interpolate("controls/switches/nav-lights-pos", 1, 0.25); # After 25ms, nav-lights-pos = 1<br />
interpolate("controls/gear/brake-left-pos", getprop("controls/gear/brake-left"), 1); # After 1s, brake-left-pos = brake-left<br />
</syntaxhighlight><br />
<br />
To interpolate with a constant ''speed'', use the formula <code>time = distance/speed</code>.<br />
<syntaxhighlight lang="nasal"><br />
# Apply the brakes at 20%/second<br />
var p = "controls/gear/brake-left";<br />
var current = getprop(p);<br />
var dist = 1-current;<br />
if (dist) interpolate(p, 1, dist/.2);<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 />
=== <tt>maketimer()</tt> (2.11+) ===<br />
<br />
As of 2.11, there is a new API for making a timer that allows more control over what happens in a timer – as opposed to setting one and forgetting about it.<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.0, func { <br />
print('timer called'); <br />
}<br />
);<br />
# start the timer (with 1 second inverval)<br />
timer.start();<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 />
{<br />
var m = {<br />
parents: [Tooltip]<br />
}<br />
m._hideTimer = maketimer(1.0, m, Tooltip._hideTimeout);<br />
m._hideTimer.singleShot = 1;<br />
<br />
return m;<br />
},<br />
run: func<br />
{<br />
if( !me._hideTimer.isRunning )<br />
me._hideTimer.start();<br />
}<br />
_hideTimeout: func<br />
{<br />
print('_hideTimeout');<br />
}<br />
};<br />
</syntaxhighlight><br />
<br />
=== <tt>geodinfo()</tt> ===<br />
Returns information about geodetic coordinates. Takes two arguments: lat, lon (in degree) and returns a vector with two entries, or nil if no information could be obtained because the terrain tile wasn't loaded. The first entry is the elevation (in meters) for the given point, and the second is a hash with information about the assigned material, or nil if there was no material information available, because there is, for instance, an untextured building at that spot or the scenery tile is not loaded.<br />
<br />
<syntaxhighlight lang="nasal"><br />
var lat = getprop("/position/latitude-deg");<br />
var lon = getprop("/position/longitude-deg");<br />
var info = geodinfo(lat, lon);<br />
<br />
if (info != nil) {<br />
print("the terrain under the aircraft is at elevation ", info[0], " m");<br />
if (info[1] != nil)<br />
print("and it is ", info[1].solid ? "solid ground" : "covered by water");<br />
}<br />
</syntaxhighlight><br />
<br />
A full data set looks like this:<br />
<br />
<syntaxhighlight lang="nasal"><br />
debug.dump(geodinfo(lat, lon));<br />
<br />
# outputs<br />
[ 106.9892101062052, { light_coverage : 0, bumpiness : 0.5999999999999999, load_resistance : 1e+30,<br />
solid : 0, names : [ "Lake", "Pond", "Reservoir", "Stream", "Canal" ], friction_factor : 1, <br />
rolling_friction : 1.5 } ]<br />
</syntaxhighlight><br />
<br />
Note that geodinfo is a *very* CPU intensive operation, particularly in FG 2.4.0 and earlier, so use sparingly ([http://forum.flightgear.org/viewtopic.php?f=4&p=135044#p135044 forum discussion here]).<br />
<br />
=== airportinfo() ===<br />
Function for retrieval of airport/runway information.<br />
Usage:<br />
<br />
<syntaxhighlight lang="nasal"><br />
var apt = airportinfo("KHAF"); # get info about KHAF<br />
var apt = airportinfo(lat, lon); # get info about apt closest to lat/lon<br />
var apt = airportinfo(); # get info about apt closest to aircraft <br />
</syntaxhighlight><br />
<br />
The command debug.dump(airportinfo("KHAF")) outputs this:<br />
<br />
<syntaxhighlight lang="nasal"><br />
{ lon : -122.4962626410256, lat : 37.51343502564102, has_metar : 0,<br />
runways : { 12 : { stopway2 : 0, threshold1 : 232.5624,<br />
lon : -122.5010889999999, lat : 37.513831, stopway1 : 0, width : 45.72,<br />
threshold2 : 232.5624, heading : 138.1199999999999, length : 1523.0856 } },<br />
elevation : 20.42159999999999, id : "KHAF", name : "Half Moon Bay" }<br />
</syntaxhighlight><br />
<br />
That is: a hash with elements lat/lon/elev/id/name/has_metar for the airport, and a hash with runways, each of which consists of lat/lon/length/width/heading/threshold[12]/stopway[12]. Only one side of each runway is listed -- the other can easily be deduced.<br />
<br />
To list all Runways :<br />
<syntaxhighlight lang="nasal"><br />
var rwy = airportinfo("KHAF").runways;<br />
foreach(var key;keys(rwy)) {<br />
print (key); # returns "30", "12"<br />
}<br />
</syntaxhighlight><br />
<br />
=== Positioned Object Queries ===<br />
<br />
Several functions exist to query the [[Navdb|navigation database]] of 'positioned' objects, i.e items with a defined location in the simulation world. (These objects all inherit from <tt>FGPositioned</tt> internally). The functions return either one, or a vector, of wrapped Nasal objects. These are efficient, but unlike a hash they cannot simply be <tt>debug.dump()</tt> to view all their members and methods, many of which are computed in a lazy fashion (i.e. on demand).<br />
<br />
When the query functions take a position, the default value is the current aircraft location. An alternative location can be supplied by passing two number (lat, lon), a Geo.Coord object, or any positioned object or waypoint retrieved from another query.<br />
<br />
;findAirportsWithinRange()<br />
: Find all airports within a specified range (in NM) of the current position or explicit position<br />
;findAirportsByICAO()<br />
: Find airports matching a complete or partial ICAO code. In particular this can search for all airports starting with a two or three letter prefix.<br />
;navinfo()<br />
: Return a list of navaids near a location by type and ident. Type should be 'fix', 'vor', 'ndb', 'dme'<br />
;findNavaidsWithinRange()<br />
: Search for navaids within a particular range (in NM), optionally limited by type. This provides a 'find the closest ILS' function<br />
;findNavaidByFrequency()<br />
: find the closest navaid (of a particular type) matching an exact frequency<br />
;findNavaidsByFrequency()<br />
: find all the navaids matching a particular frequency and optional type, sorted by distance from the search location.<br />
<br />
All positioned objects returned by the above methods have the following members:<br />
;id<br />
: Identifier - ICAO code for airports, published ident for navaids and fixes<br />
;lon<br />
: degrees longitude<br />
;lat<br />
: degrees latitude<br />
<br />
Depending on type, the following members are also available:<br />
;name<br />
: the full name of the airport or navaid if one is defined<br />
;elevation<br />
: the ASL elevation of the object in feet<br />
<br />
For navaids, the following members are available:<br />
;frequency<br />
: the navaid frequency in kHz<br />
;type<br />
: the navaid type as a string: vor, dme, loc, ils, ndb<br />
;course<br />
: the degrees course associated with the navaid, for localiser and ILS stations<br />
<br />
=== <tt>history() </tt> (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 />
<br />
=== <tt>flightplan()</tt> ===<br />
<br />
Function to retrieve the active flight-plan object, or load a flight plan from a file path.<br />
<br />
Usage:<br />
<syntaxhighlight lang="nasal"><br />
var fp = flightplan();<br />
var fp = flightplan('/some/path/to/a/flightplan.xml');<br />
</syntaxhighlight><br />
<br />
In advance of converting the Map and NavDisplay to use the [[Canvas]], James has improved the "flightplan()" extension function of the [[Nasal]] scripting interpreter to expose the full route-path vector for each flight plan leg as a vector on the leg.<br />
<br />
<br />
<syntaxhighlight lang="nasal"><br />
var fp = flightplan();<br />
for (var i=0; i<fp.getPlanSize(); i += 1)<br />
{<br />
var leg = fp.getWP(i);<br />
debug.dump(leg.path());<br />
}<br />
</syntaxhighlight><br />
<br />
=== <tt>systime()</tt> ===<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 />
=== <tt>carttogeod()</tt> ===<br />
Converts cartesian coordinates x/y/z to geodetic coordinates lat/lon/alt, which are returned as a vector. Units are degree and meter.<br />
<br />
<syntaxhighlight lang="nasal"><br />
var geod = carttogeod(-2737504, -4264101, 3862172);<br />
print("lat=", geod[0], " lon=", geod[1], " alt=", geod[2]);<br />
<br />
# outputs<br />
lat=37.49999782141546 lon=-122.6999914632327 alt=998.6042055172776<br />
</syntaxhighlight><br />
<br />
=== <tt>geodtocart()</tt> ===<br />
Converts geodetic coordinates lat/lon/alt to cartesian coordinates x/y/z. Units are degree and meter.<br />
<br />
<syntaxhighlight lang="nasal"><br />
var cart = geodtocart(37.5, -122.7, 1000); # lat/lon/alt(m)<br />
print("x=", cart[0], " y=", cart[1], " z=", cart[2]);<br />
<br />
# outputs<br />
x=-2737504.667684828 y=-4264101.900993474 z=3862172.834656495<br />
</syntaxhighlight><br />
<br />
=== <tt>parsexml()</tt> ===<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 />
=== <tt>resolvepath()</tt> ===<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 />
==== <tt>http.load()</tt> ====<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 />
==== <tt>http.save()</tt> ====<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 />
=== <tt>rand()</tt> ===<br />
<br />
Return a random number as generated by <tt>sg_random</tt>.<br />
<br />
=== <tt>srand()</tt> ===<br />
<br />
Seed the random number generator based upon the current time. Returns 0.<br />
<br />
=== <tt>md5()</tt> (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 />
=== <tt>abort()</tt> ===<br />
<br />
Wrapper for the C++ library abort() function – i.e. it just aborts the process without regard to what's happening. For exiting (gracefully) from FlightGear use the fgcommand "exit" instead.<br />
<br />
{{Appendix}}</div>Clm76https://wiki.flightgear.org/w/index.php?title=Nasal_library_functions&diff=85140Nasal library functions2015-05-29T17:05:01Z<p>Clm76: /* subvec() */</p>
<hr />
<div>{{Nasal Navigation}}<br />
<br />
Please first see: http://plausible.org/nasal/lib.html<br />
<br />
== size() ==<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, mod(x,y) also works...<br><br />
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 />
== 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>Clm76https://wiki.flightgear.org/w/index.php?title=Nasal_library_functions&diff=85138Nasal library functions2015-05-29T16:29:36Z<p>Clm76: /* directory() */</p>
<hr />
<div>{{Nasal Navigation}}<br />
<br />
Please first see: http://plausible.org/nasal/lib.html<br />
<br />
== size() ==<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 />
Example :<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var currentPath = "/home/xxx/yyy/";<br />
print (directory(currentPath));<br />
</syntaxhighlight><br />
returns : ".", "..", "file1", "file2", "file3"<br />
<br />
and :<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var currentPath = "/home/xxx/yyy/";<br />
print (subvec(directory(currentPath),2));<br />
</syntaxhighlight><br />
returns : "file1", "file2", "file3"<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var currentPath = "/home/xxx/yyy/";<br />
print (subvec(directory(currentPath),3));<br />
</syntaxhighlight><br />
returns : "file2", "file3"<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, mod(x,y) also works...<br><br />
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 />
== 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>Clm76https://wiki.flightgear.org/w/index.php?title=Nasal_library_functions&diff=85137Nasal library functions2015-05-29T16:28:38Z<p>Clm76: /* directory() */</p>
<hr />
<div>{{Nasal Navigation}}<br />
<br />
Please first see: http://plausible.org/nasal/lib.html<br />
<br />
== size() ==<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 />
Example :<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var currentPath = "/home/xxx/yyy/";<br />
print (directory(currentPath));<br />
</syntaxhighlight><br />
returns : ".", "..", "file1", "file2", "file3"<br />
<br />
and :<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var currentPath = "/home/xxx/yyy/";<br />
print (subvec(directory(currentPath),2));<br />
</syntaxhighlight><br />
returns : "file1", "file2", "file3"<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var currentPath = "/home/xxx/yyy/";<br />
print (subvec(directory(currentPath),3));<br />
</syntaxhighlight><br />
returns : "file2", "file3"<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, mod(x,y) also works...<br><br />
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 />
== 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 = FGRoot ~ filename;<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>Clm76https://wiki.flightgear.org/w/index.php?title=Nasal_library_functions&diff=85124Nasal library functions2015-05-29T06:44:24Z<p>Clm76: /* ceil() */</p>
<hr />
<div>{{Nasal Navigation}}<br />
<br />
Please first see: http://plausible.org/nasal/lib.html<br />
<br />
== size() ==<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 />
Example :<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var currentPath = "/home/xxx/yyy/";<br />
print (directory(currentPath));<br />
</syntaxhighlight><br />
returns : ".", "..", "file1", "file2", "file3"<br />
<br />
and :<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var currentPath = "/home/xxx/yyy/";<br />
print (subvec(directory(currentPath),2));<br />
</syntaxhighlight><br />
returns : "file1", "file2", "file3"<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var currentPath = "/home/xxx/yyy/";<br />
print (subvec(directory(currentPath),3));<br />
</syntaxhighlight><br />
returns : "file2", "file3"<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, mod(x,y) also works...<br><br />
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 />
== 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 currentPath = "/home/xxx/yyy/";<br />
print (directory(currentPath));<br />
</syntaxhighlight><br />
<br />
returns :<br />
:"."<br />
:".."<br />
:"file1"<br />
:"file2"<br />
:"file3"<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>Clm76https://wiki.flightgear.org/w/index.php?title=Nasal_library_functions&diff=85123Nasal library functions2015-05-29T06:43:15Z<p>Clm76: /* floor() */</p>
<hr />
<div>{{Nasal Navigation}}<br />
<br />
Please first see: http://plausible.org/nasal/lib.html<br />
<br />
== size() ==<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 />
Example :<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var currentPath = "/home/xxx/yyy/";<br />
print (directory(currentPath));<br />
</syntaxhighlight><br />
returns : ".", "..", "file1", "file2", "file3"<br />
<br />
and :<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var currentPath = "/home/xxx/yyy/";<br />
print (subvec(directory(currentPath),2));<br />
</syntaxhighlight><br />
returns : "file1", "file2", "file3"<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var currentPath = "/home/xxx/yyy/";<br />
print (subvec(directory(currentPath),3));<br />
</syntaxhighlight><br />
returns : "file2", "file3"<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 />
== fmod() ==<br />
A '''modulo'''-operator, mod(x,y) also works...<br><br />
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 />
== 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 currentPath = "/home/xxx/yyy/";<br />
print (directory(currentPath));<br />
</syntaxhighlight><br />
<br />
returns :<br />
:"."<br />
:".."<br />
:"file1"<br />
:"file2"<br />
:"file3"<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>Clm76https://wiki.flightgear.org/w/index.php?title=Nasal_library_functions&diff=85122Nasal library functions2015-05-29T06:40:35Z<p>Clm76: /* floor() */</p>
<hr />
<div>{{Nasal Navigation}}<br />
<br />
Please first see: http://plausible.org/nasal/lib.html<br />
<br />
== size() ==<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 />
Example :<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var currentPath = "/home/xxx/yyy/";<br />
print (directory(currentPath));<br />
</syntaxhighlight><br />
returns : ".", "..", "file1", "file2", "file3"<br />
<br />
and :<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var currentPath = "/home/xxx/yyy/";<br />
print (subvec(directory(currentPath),2));<br />
</syntaxhighlight><br />
returns : "file1", "file2", "file3"<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var currentPath = "/home/xxx/yyy/";<br />
print (subvec(directory(currentPath),3));<br />
</syntaxhighlight><br />
returns : "file2", "file3"<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 />
floor(1.2); # returns 1<br />
floor(1.6); # returns 1<br />
</syntaxhighlight><br />
<br />
== ceil() ==<br />
== fmod() ==<br />
A '''modulo'''-operator, mod(x,y) also works...<br><br />
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 />
== 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 currentPath = "/home/xxx/yyy/";<br />
print (directory(currentPath));<br />
</syntaxhighlight><br />
<br />
returns :<br />
:"."<br />
:".."<br />
:"file1"<br />
:"file2"<br />
:"file3"<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>Clm76https://wiki.flightgear.org/w/index.php?title=Nasal_library_functions&diff=85121Nasal library functions2015-05-29T06:33:28Z<p>Clm76: /* subvec() */</p>
<hr />
<div>{{Nasal Navigation}}<br />
<br />
Please first see: http://plausible.org/nasal/lib.html<br />
<br />
== size() ==<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 />
Example :<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var currentPath = "/home/xxx/yyy/";<br />
print (directory(currentPath));<br />
</syntaxhighlight><br />
returns : ".", "..", "file1", "file2", "file3"<br />
<br />
and :<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var currentPath = "/home/xxx/yyy/";<br />
print (subvec(directory(currentPath),2));<br />
</syntaxhighlight><br />
returns : "file1", "file2", "file3"<br />
<br />
<syntaxhighlight lang="nasal" enclose="div"><br />
var currentPath = "/home/xxx/yyy/";<br />
print (subvec(directory(currentPath),3));<br />
</syntaxhighlight><br />
returns : "file2", "file3"<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 />
== ceil() ==<br />
== fmod() ==<br />
A '''modulo'''-operator, mod(x,y) also works...<br><br />
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 />
== 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 currentPath = "/home/xxx/yyy/";<br />
print (directory(currentPath));<br />
</syntaxhighlight><br />
<br />
returns :<br />
:"."<br />
:".."<br />
:"file1"<br />
:"file2"<br />
:"file3"<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>Clm76https://wiki.flightgear.org/w/index.php?title=Nasal_library_functions&diff=85120Nasal library functions2015-05-29T06:18:41Z<p>Clm76: /* directory() */</p>
<hr />
<div>{{Nasal Navigation}}<br />
<br />
Please first see: http://plausible.org/nasal/lib.html<br />
<br />
== size() ==<br />
<br />
== keys() ==<br />
<br />
== append() ==<br />
<br />
== pop() ==<br />
<br />
== setsize() ==<br />
<br />
== subvec() ==<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 />
== ceil() ==<br />
== fmod() ==<br />
A '''modulo'''-operator, mod(x,y) also works...<br><br />
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 />
== 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 currentPath = "/home/xxx/yyy/";<br />
print (directory(currentPath));<br />
</syntaxhighlight><br />
<br />
returns :<br />
:"."<br />
:".."<br />
:"file1"<br />
:"file2"<br />
:"file3"<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>Clm76