FlightGear wiki - User contributions [en]

Pl/FlightGear

2026-04-03T16:43:22Z

PlayeRom: /* Sprzęt */

{{Infobox Software
|title = FlightGear Flight Simulator
|logo = FlightGear logo.png
|logosize = 200px
|image = Boeing 777-200ER cockpit.jpg
|alt = W kokpicie [[Boeing 777-200ER]]
|developedby = Developerzy FlightGear i współtwórcy
|initialrelease = Lipec 17, 1997
|latestrelease = {{current release|full}} ({{#time: j xg Y | {{current release|fulldate}} | pl }})
|writtenin = C/C++/Nasal
|os = Windows, Linux, macOS oraz FreeBSD
|platform = wieloplatformowy
|developmentstatus = Aktywny (1996-)
|type = Symulator Lotu
|license = [[GNU General Public License]]
|website = https://www.flightgear.org/
}}

[[File:OV10A-NASA-in-action.jpg|thumb|right|270px|NASA [[OV-10]] we FlightGear 1.0]]

'''FlightGear Flight Simulator''' (w skrócie '''FlightGear''' lub '''FGFS''') to zaawansowana, darmowa i całkowicie otwarto-źródłowa platforma symulacji lotu, stworzona przez wolontariuszy. FlightGear jest wydany na zasadach licencji [[GNU General Public License]] i jest on w większości napisany przy użyciu języka programowania C++.

Coraz bardziej szczegółowe i zaawansowane wersje FlightGeara są corocznie wydawane od zapoczątkowania projektu w 1996 roku.

Najnowsze publiczne wydanie dostępne jest do pobrania na [https://www.flightgear.org/download/ www.flightgear.org/download/] wraz z wersjami dla Microsoft Windows, macOS i Linux.

== Historia ==
{{main article|FlightGear History}}

Rozwój FlightGeara rozpoczął się od propozycji stworzenia otwarto-źródłowego symulatora w 1996 roku, w oparciu o własny kod renderowania grafiki 3D. Rozwój wersji opartej na [[OpenGL]] rozpoczął Curtis Olson w 1997 roku, ale także wiele innych osób miało swój wkład w ten projekt.

FlightGear włączył inne otwarto-źródłowe zasoby, w tym model lotu LaRCsim od NASA oraz powszechnie dostępne dane o elewacji terenu. Pierwsze działające pliki binarne, wykorzystujące OpenGL dla grafiki 3D, pojawiły się w 1997 roku. Entuzjastyczny rozwój kolejnych wersji przez kilka lat zaowocował stopniowo coraz bardziej stabilnymi i zaawansowanymi wersjami. W 2001 roku zespół regularnie wydawał nowe wersje beta, a w 2005 roku dojrzałość oprogramowania doprowadziła do szerszych recenzji i wzrostu popularności. W 2007 roku nastąpiło formalne wyjście z wersji beta wraz z wydaniem wersji 1.0.0, dziesięć lat po pierwszym wydaniu FlightGeara w 1997 roku.

[[File:FG-A-10.jpg|thumb|270px|Kokpit 3D [[A-10]] w wersji 1.0.0, rok 2008]]

W 2008 roku, wersja 1.9.0 FlightGeara przeszła z biblioteki [[PLIB]] na [[OSG]], co spowodowało tymczasową utratę niektórych funkcji programu, takich jak wyświetlanie chmury 3D i cienie, za to nowo wprowadzone funkcje, takie jak cząsteczki, nadały symulacji kolejny stopień realizmu.

== Program ==

Silnik symulacji we FlightGear to [[SimGear]]. Jest on używany zarówno jako aplikacja użytkownika końcowego jak i przy pracach badawczych w środowiskach akademickich w celu rozwoju zagadnień związanych z symulacją lotu.

Przykładem na możliwość dostosowywania FlightGeara jest szeroki wachlarz modeli dostępnych statków powietrznych, od [[:Category:Gliders|szybowców]] przez [[Helicopter|śmigłowców]], [[:Category:Airliners|liniowce]], [[Military aircraft|myśliwców odrzutowych]] do [[Space Shuttle|Wahadłowca Kosmicznego]]. Modele te zostały wykonane i dodane do projektu przez wielu ochotników ze społeczności FlightGeara.

Od wersji 0.9.10 statki powietrzne we FlightGear używają jednego z trzech [[Flight Dynamics Model|modeli dynamiki lotu]] (FDM): [[JSBSim]], [[YASim]] lub [[UIUC]]. Obecnie wyłącznie jeden silnik terenu jest w użyciu, jest nim [[TerraGear]]. Dostępne efekty pogodowe to między innymi chmury 3D, efekty świetlne, pory dnia i nocy.

=== Modele Dynamiki Lotu ===
[[Flight Dynamics Models|Model dynamiki lotu]] (FDM) odpowiada za to w jaki sposób w programie jest symulowany lot statku powietrznego. FlightGear korzysta z własnych oraz zewnętrznych projektów modeli dynamiki lotu. Każdy statek powietrzny musi być tak zaprogramowany, aby korzystał z jednego z dostępnych modeli dynamiki lotu. Obecnie FlightGear jest jedynym, graficznym symulatorem lotu korzystającym ze wszystkich wspomnianych modeli dynamiki lotu, a UIUC i YASim zostały rozwinięte z myślą i w szczególności dla FlightGeara.

Wczesne wersje programu używały FDM, który był oparty na [[LaRCsim]] od NASA. W kolejnych wersjach został on zastąpiony przez bardziej elastyczne FDM.

* [[JSBSim]] - domyślny model dynamiki lotu od 2000 roku.
* [[YASim]] - inny FDM, używający odmiennych metod obliczeniowych. Wprowadzony od wersji 0.7.9 w 2002 roku.
* [[UIUC]] - kolejny FDM, rozwijany przez UIUC Applied Aerodynamics Group z Uniwersytetu w Illinois na Urbana-Champaign, bazujący na LaRCsim. Obecnie już wycofany z wersji deweloperskiej FlightGeara.
* FlightGear może być tak skonfigurowany, aby przyjmował dane z zewnętrznych źródeł FDM takich jak [[MATLAB]].
* Inne niestandardowe FDM zostały napisane dla specyficznych typów statków powietrznych jak balony i sterowce.

=== Zależności FlightGeara ===

W przeciwieństwie do komercyjnych tytułów, głównym rezultatem prac nad projektem jest publikacja kodu źródłowego. Aby skorzystać z programu, można samodzielnie skompilować udostępniony kod dla docelowej platformy.

Wykorzystywane przez FlightGeara biblioteki zmieniały się na przestrzeni czasu. Najważniejszą zależnością pozostaje SimGear, będący silnikiem symulacji dla FlightGeara. [[TerraGear]] nie stanowi bezpośredniej zależności – jest raczej nazwą domyślnego silnika odpowiedzialnego za generowanie terenu.

Do obsługi dźwięku wykorzystywany jest OpenAL (z włączonym wsparciem dla SDL od wersji 0.9.5), natomiast wcześniej w tym celu używano biblioteki PLIB, która odpowiadała również za obsługę sprzętu. Za renderowanie grafiki 3D odpowiada [[OpenGL]] – DirectX nie jest wspierany. Z FlightGearem zintegrowano także silnik graficzny [[OpenSceneGraph]]. Do kompilacji wymagane jest również użycie biblioteki Simple Direct Media Layer (SDL).

Zakres zależności może się różnić w zależności od docelowej platformy. Użytkownicy mogą samodzielnie kompilować kod lub – jeśli nie jest on dostępny bezpośrednio w ramach projektu – korzystać z gotowych wersji binarnych przygotowanych przez osoby trzecie.

== Sprzęt==

Do uruchomienia FlightGeara wymagany jest sprzęt obsługujący [[OpenGL]] oraz akcelerację 3D. Najlepsze wsparcie zapewniają karty graficzne NVIDIA. We wcześniejszych wersjach dostępna była również obsługa kart 3dfx, jednak została ona wycofana wraz ze wzrostem wymagań sprzętowych.

[[File:Fgrun-page2.jpg|thumb|left|270px|[[FlightGear Launch Control|FlightGear Launcher]]]]

== Dodatki i dostosowywanie ==

Istnieją programy, które są zintegrowane z FlightGearem (zależności) lub są programami zewnętrznymi i współpracują z nim. Oprogramowanie takie może być częścią projektu FlightGear lub może być rozwijane niezależnie, ale udostępniane przez projekt FlightGear.

Ważnym dodatkowym oprogramowaniem jest interfejs graficzny, służący do uruchomienia pliku wykonywalnego FlightGeara. We wczesnych wersjach, FlightGear mógł być uruchomiony jedynie z wykorzystaniem [[Pl/Opcje wiersza poleceń|opcji wiersza poleceń]]. Jednakże, w 2003 roku od wersji 0.9.3, został dołączony ''[[FlightGear Launch Control|FGRun]]'' - program startowy z interfejsem graficznym. Obecnie tę rolę spełnia ''[[FlightGear Qt launcher|QT Launcher]]''.
Podobną funkcję spełnia ''[[KFreeFlight]]'' dla środowiska KDE. ''FGTools'' jest alternatywnym front-endem dla środowiska Windows. ''FGKicker'' jest używany dla GTK+.

Inne znaczące programy obejmują edytory i projekty związane z terenem. ''[[Atlas]]'' jest mapą dla FlightGeara; ''[[Kelpie Flight Planner]]'' to rozwijane w Javie narzędzie do planowania lotów.
''[[FlightGear Scenery Designer]]'' to edytor scenerii, pomocny przy pracy z danymi terenu. ''[[World Custom Scenery Project]]'' to projekt pomagający koordynować wspólne wysiłki na rzecz tworzenia scenerii. Na koniec edytor ''[[TaxiDraw]]'' do tworzenia nowych pasów startowych i dróg kołowania.

=== Statki Powietrzne ===
{{Main article|Table of models}}

Na początku, FlightGear dysponował tylko jednym statkiem powietrznym, był to Navion zawarty w projekcie LaRCsim od NASA, który w 2000 roku został zastąpiony przez Cessnę 172P. Rozwój UIUC i JSBSim przyniósł ze sobą kilka kolejnych samolotów, podobnie jak rozwój YASim, który od tego czasu stał się głównym FDM używanym we FlightGear. W wersji 2.12 dostępnych jest ponad 400 samolotów w ponad 900 unikalnych malowaniach, choć tylko kilka z nich wchodzi w skład pakietu podstawowego.

[[File:EHAM.jpg|thumb|270px|[[Boeing 737-300|Boeing 733]] zaparkowany w scenerii [[EHAM]] ]]

=== Sceneria ===
{{Main article|Scenery}}

Projekt [[World Scenery]] dla FlightGeara zawiera dane o wysokości i klasie terenu całego świata.
Obiekty takie jak terminale, wiatraki i mosty są zebrane w [[FlightGear Scenery Database|bazie danych scenerii]].

=== Sieć i wiele monitorów ===

Istnieje kilka możliwości, które pozwalają komunikować się jednej instancji FlightGeara z inną. Dostępny jest protokół [[Multiplayer Howto|multiplayer]], co umożliwia lot w formacji lub symulowanie kontroli ruchu lotniczego w sieci lokalnej. Protokół Multiplayer zostanie wkrótce tak rozbudowany, aby także pozwalał na pracę w internecie. Dodatkową cechą możliwości sieciowych jest opcja podglądu innych pilotów na mapach Google.

Kilka instancji FlightGeara może zostać tak zsynchronizowana, aby korzystały z wielu monitorów. Możliwe jest uzyskanie bardzo dobrej synchronizacji między monitorami jeżeli wszystkie instancje FlightGeara będą pracowały z tą samą częstotliwością wyświetlania klatek.

== Kod FlightGeara vs wersja binarna ==

W przeciwieństwie do komercyjnego oprogramowania, data wydania dotyczy wyłącznie kodu źródłowego, a nie wersji binarnej. Aby stworzyć wykonywalny program, kod źródłowy musi zostać skompilowany, co wymaga kilku bibliotek, włączając w to kilka ogólnych oraz specyficznych dla platfory. Jednak jest to zbyt trudne zadanie dla wielu zwykłych użytkowników, dlatego ochotnicy społeczności pracują, aby udostępnić wersje binarne dla poszczególnych platform i systemów operacyjnych. Dystrybucje te różnią się poziomem stabilności, wydajnością, zależnościami, a także tym, jak aktualne są one w stosunku do kodu źródłowego. Dla przykładu, niektóre ze starszych wersji binarnych będą pracować poprawnie pod Mac OS 9, ale nowsze wydania wymagają określonych wersji Mac OS X.

For example, by late 2012 the latest code release was 2.10 (pre-release) and 2.8.0 (final). Binaries are generally available for the last final code release on all major platforms. [http://www.flightgear.org/download/main-program/ Click here to proceed to the flightgear binaries download page]

Przykładowo, pod koniec 2012 roku najnowszą wersją kodu była wersja 2.10 (przedpremierowa) i 2.8.0 (finalna). Pliki binarne są ogólnie dostępne dla ostatniego finalnego wydania kodu na wszystkich głównych platformach. Przejdź do naszej oficjalnej [https://www.flightgear.org/download/ strony pobierania] aby pobrać pliki binarne FlightGeara.

Pliki binarne dla innych platform, takich jak IRIX, nie są już obsługiwane, chociaż wydania sprzed 1.0 mogą działać i można je znaleźć w [[FlightGear Git|repozytoriach kodu źródłowego git]].

== Recenzje FlightGear ==
{{Main article|FlightGear Reviews}}

== Łącza zewnętrzne ==
{{Main article|Links}}
* {{Wikipedia|FlightGear}}
* [https://www.flightgear.org Oficjalna strona]
* {{forum link|text=Forum}}
* [https://sourceforge.net/p/flightgear/codetickets/ System śledzenia błędów]
* [http://www.flightgear.org/proposal-3.0.1 Oryginalna propozycja stworzenia FlightGear]

== Źródła ==
* [http://www.flightgear.org/proposal-3.0.1 Original Flight Gear Proposal] by David L. Murr (Revision 3.0.1)
* [http://en.wikipedia.org/wiki/FlightGear Wikipedia]

[[ca:FlightGear]]
[[de:FlightGear]]
[[en:FlightGear]]
[[es:FlightGear]]
[[fr:FlightGear]]
[[it:FlightGear]]
[[nl:FlightGear]]
[[pt:FlightGear]]

Pl/FlightGear

2026-04-03T16:41:59Z

PlayeRom: /* Zależności FlightGeara */

{{Infobox Software
|title = FlightGear Flight Simulator
|logo = FlightGear logo.png
|logosize = 200px
|image = Boeing 777-200ER cockpit.jpg
|alt = W kokpicie [[Boeing 777-200ER]]
|developedby = Developerzy FlightGear i współtwórcy
|initialrelease = Lipec 17, 1997
|latestrelease = {{current release|full}} ({{#time: j xg Y | {{current release|fulldate}} | pl }})
|writtenin = C/C++/Nasal
|os = Windows, Linux, macOS oraz FreeBSD
|platform = wieloplatformowy
|developmentstatus = Aktywny (1996-)
|type = Symulator Lotu
|license = [[GNU General Public License]]
|website = https://www.flightgear.org/
}}

[[File:OV10A-NASA-in-action.jpg|thumb|right|270px|NASA [[OV-10]] we FlightGear 1.0]]

'''FlightGear Flight Simulator''' (w skrócie '''FlightGear''' lub '''FGFS''') to zaawansowana, darmowa i całkowicie otwarto-źródłowa platforma symulacji lotu, stworzona przez wolontariuszy. FlightGear jest wydany na zasadach licencji [[GNU General Public License]] i jest on w większości napisany przy użyciu języka programowania C++.

Coraz bardziej szczegółowe i zaawansowane wersje FlightGeara są corocznie wydawane od zapoczątkowania projektu w 1996 roku.

Najnowsze publiczne wydanie dostępne jest do pobrania na [https://www.flightgear.org/download/ www.flightgear.org/download/] wraz z wersjami dla Microsoft Windows, macOS i Linux.

== Historia ==
{{main article|FlightGear History}}

Rozwój FlightGeara rozpoczął się od propozycji stworzenia otwarto-źródłowego symulatora w 1996 roku, w oparciu o własny kod renderowania grafiki 3D. Rozwój wersji opartej na [[OpenGL]] rozpoczął Curtis Olson w 1997 roku, ale także wiele innych osób miało swój wkład w ten projekt.

FlightGear włączył inne otwarto-źródłowe zasoby, w tym model lotu LaRCsim od NASA oraz powszechnie dostępne dane o elewacji terenu. Pierwsze działające pliki binarne, wykorzystujące OpenGL dla grafiki 3D, pojawiły się w 1997 roku. Entuzjastyczny rozwój kolejnych wersji przez kilka lat zaowocował stopniowo coraz bardziej stabilnymi i zaawansowanymi wersjami. W 2001 roku zespół regularnie wydawał nowe wersje beta, a w 2005 roku dojrzałość oprogramowania doprowadziła do szerszych recenzji i wzrostu popularności. W 2007 roku nastąpiło formalne wyjście z wersji beta wraz z wydaniem wersji 1.0.0, dziesięć lat po pierwszym wydaniu FlightGeara w 1997 roku.

[[File:FG-A-10.jpg|thumb|270px|Kokpit 3D [[A-10]] w wersji 1.0.0, rok 2008]]

W 2008 roku, wersja 1.9.0 FlightGeara przeszła z biblioteki [[PLIB]] na [[OSG]], co spowodowało tymczasową utratę niektórych funkcji programu, takich jak wyświetlanie chmury 3D i cienie, za to nowo wprowadzone funkcje, takie jak cząsteczki, nadały symulacji kolejny stopień realizmu.

== Program ==

Silnik symulacji we FlightGear to [[SimGear]]. Jest on używany zarówno jako aplikacja użytkownika końcowego jak i przy pracach badawczych w środowiskach akademickich w celu rozwoju zagadnień związanych z symulacją lotu.

Przykładem na możliwość dostosowywania FlightGeara jest szeroki wachlarz modeli dostępnych statków powietrznych, od [[:Category:Gliders|szybowców]] przez [[Helicopter|śmigłowców]], [[:Category:Airliners|liniowce]], [[Military aircraft|myśliwców odrzutowych]] do [[Space Shuttle|Wahadłowca Kosmicznego]]. Modele te zostały wykonane i dodane do projektu przez wielu ochotników ze społeczności FlightGeara.

Od wersji 0.9.10 statki powietrzne we FlightGear używają jednego z trzech [[Flight Dynamics Model|modeli dynamiki lotu]] (FDM): [[JSBSim]], [[YASim]] lub [[UIUC]]. Obecnie wyłącznie jeden silnik terenu jest w użyciu, jest nim [[TerraGear]]. Dostępne efekty pogodowe to między innymi chmury 3D, efekty świetlne, pory dnia i nocy.

=== Modele Dynamiki Lotu ===
[[Flight Dynamics Models|Model dynamiki lotu]] (FDM) odpowiada za to w jaki sposób w programie jest symulowany lot statku powietrznego. FlightGear korzysta z własnych oraz zewnętrznych projektów modeli dynamiki lotu. Każdy statek powietrzny musi być tak zaprogramowany, aby korzystał z jednego z dostępnych modeli dynamiki lotu. Obecnie FlightGear jest jedynym, graficznym symulatorem lotu korzystającym ze wszystkich wspomnianych modeli dynamiki lotu, a UIUC i YASim zostały rozwinięte z myślą i w szczególności dla FlightGeara.

Wczesne wersje programu używały FDM, który był oparty na [[LaRCsim]] od NASA. W kolejnych wersjach został on zastąpiony przez bardziej elastyczne FDM.

* [[JSBSim]] - domyślny model dynamiki lotu od 2000 roku.
* [[YASim]] - inny FDM, używający odmiennych metod obliczeniowych. Wprowadzony od wersji 0.7.9 w 2002 roku.
* [[UIUC]] - kolejny FDM, rozwijany przez UIUC Applied Aerodynamics Group z Uniwersytetu w Illinois na Urbana-Champaign, bazujący na LaRCsim. Obecnie już wycofany z wersji deweloperskiej FlightGeara.
* FlightGear może być tak skonfigurowany, aby przyjmował dane z zewnętrznych źródeł FDM takich jak [[MATLAB]].
* Inne niestandardowe FDM zostały napisane dla specyficznych typów statków powietrznych jak balony i sterowce.

=== Zależności FlightGeara ===

W przeciwieństwie do komercyjnych tytułów, głównym rezultatem prac nad projektem jest publikacja kodu źródłowego. Aby skorzystać z programu, można samodzielnie skompilować udostępniony kod dla docelowej platformy.

Wykorzystywane przez FlightGeara biblioteki zmieniały się na przestrzeni czasu. Najważniejszą zależnością pozostaje SimGear, będący silnikiem symulacji dla FlightGeara. [[TerraGear]] nie stanowi bezpośredniej zależności – jest raczej nazwą domyślnego silnika odpowiedzialnego za generowanie terenu.

Do obsługi dźwięku wykorzystywany jest OpenAL (z włączonym wsparciem dla SDL od wersji 0.9.5), natomiast wcześniej w tym celu używano biblioteki PLIB, która odpowiadała również za obsługę sprzętu. Za renderowanie grafiki 3D odpowiada [[OpenGL]] – DirectX nie jest wspierany. Z FlightGearem zintegrowano także silnik graficzny [[OpenSceneGraph]]. Do kompilacji wymagane jest również użycie biblioteki Simple Direct Media Layer (SDL).

Zakres zależności może się różnić w zależności od docelowej platformy. Użytkownicy mogą samodzielnie kompilować kod lub – jeśli nie jest on dostępny bezpośrednio w ramach projektu – korzystać z gotowych wersji binarnych przygotowanych przez osoby trzecie.

== Sprzęt==

Sprzęt konieczny do uruchomienia FlightGeara jest ograniczony do sprzętu, który wspiera [[OpenGL]] i akcelerację 3D, przy czym najlepiej wspierana jest NVIDIA. Wczesne wersje posiadały wsparcie dla kart 3dfx, jednak wsparcie to zostało wycofane wraz ze zwiększającymi się wymaganiami sprzętowymi.

[[File:Fgrun-page2.jpg|thumb|left|270px|[[FlightGear Launch Control|FlightGear Launcher]]]]
== Dodatki i dostosowywanie ==

Istnieją programy, które są zintegrowane z FlightGearem (zależności) lub są programami zewnętrznymi i współpracują z nim. Oprogramowanie takie może być częścią projektu FlightGear lub może być rozwijane niezależnie, ale udostępniane przez projekt FlightGear.

Ważnym dodatkowym oprogramowaniem jest interfejs graficzny, służący do uruchomienia pliku wykonywalnego FlightGeara. We wczesnych wersjach, FlightGear mógł być uruchomiony jedynie z wykorzystaniem [[Pl/Opcje wiersza poleceń|opcji wiersza poleceń]]. Jednakże, w 2003 roku od wersji 0.9.3, został dołączony ''[[FlightGear Launch Control|FGRun]]'' - program startowy z interfejsem graficznym. Obecnie tę rolę spełnia ''[[FlightGear Qt launcher|QT Launcher]]''.
Podobną funkcję spełnia ''[[KFreeFlight]]'' dla środowiska KDE. ''FGTools'' jest alternatywnym front-endem dla środowiska Windows. ''FGKicker'' jest używany dla GTK+.

Inne znaczące programy obejmują edytory i projekty związane z terenem. ''[[Atlas]]'' jest mapą dla FlightGeara; ''[[Kelpie Flight Planner]]'' to rozwijane w Javie narzędzie do planowania lotów.
''[[FlightGear Scenery Designer]]'' to edytor scenerii, pomocny przy pracy z danymi terenu. ''[[World Custom Scenery Project]]'' to projekt pomagający koordynować wspólne wysiłki na rzecz tworzenia scenerii. Na koniec edytor ''[[TaxiDraw]]'' do tworzenia nowych pasów startowych i dróg kołowania.

=== Statki Powietrzne ===
{{Main article|Table of models}}

Na początku, FlightGear dysponował tylko jednym statkiem powietrznym, był to Navion zawarty w projekcie LaRCsim od NASA, który w 2000 roku został zastąpiony przez Cessnę 172P. Rozwój UIUC i JSBSim przyniósł ze sobą kilka kolejnych samolotów, podobnie jak rozwój YASim, który od tego czasu stał się głównym FDM używanym we FlightGear. W wersji 2.12 dostępnych jest ponad 400 samolotów w ponad 900 unikalnych malowaniach, choć tylko kilka z nich wchodzi w skład pakietu podstawowego.

[[File:EHAM.jpg|thumb|270px|[[Boeing 737-300|Boeing 733]] zaparkowany w scenerii [[EHAM]] ]]

=== Sceneria ===
{{Main article|Scenery}}

Projekt [[World Scenery]] dla FlightGeara zawiera dane o wysokości i klasie terenu całego świata.
Obiekty takie jak terminale, wiatraki i mosty są zebrane w [[FlightGear Scenery Database|bazie danych scenerii]].

=== Sieć i wiele monitorów ===

Istnieje kilka możliwości, które pozwalają komunikować się jednej instancji FlightGeara z inną. Dostępny jest protokół [[Multiplayer Howto|multiplayer]], co umożliwia lot w formacji lub symulowanie kontroli ruchu lotniczego w sieci lokalnej. Protokół Multiplayer zostanie wkrótce tak rozbudowany, aby także pozwalał na pracę w internecie. Dodatkową cechą możliwości sieciowych jest opcja podglądu innych pilotów na mapach Google.

Kilka instancji FlightGeara może zostać tak zsynchronizowana, aby korzystały z wielu monitorów. Możliwe jest uzyskanie bardzo dobrej synchronizacji między monitorami jeżeli wszystkie instancje FlightGeara będą pracowały z tą samą częstotliwością wyświetlania klatek.

== Kod FlightGeara vs wersja binarna ==

W przeciwieństwie do komercyjnego oprogramowania, data wydania dotyczy wyłącznie kodu źródłowego, a nie wersji binarnej. Aby stworzyć wykonywalny program, kod źródłowy musi zostać skompilowany, co wymaga kilku bibliotek, włączając w to kilka ogólnych oraz specyficznych dla platfory. Jednak jest to zbyt trudne zadanie dla wielu zwykłych użytkowników, dlatego ochotnicy społeczności pracują, aby udostępnić wersje binarne dla poszczególnych platform i systemów operacyjnych. Dystrybucje te różnią się poziomem stabilności, wydajnością, zależnościami, a także tym, jak aktualne są one w stosunku do kodu źródłowego. Dla przykładu, niektóre ze starszych wersji binarnych będą pracować poprawnie pod Mac OS 9, ale nowsze wydania wymagają określonych wersji Mac OS X.

For example, by late 2012 the latest code release was 2.10 (pre-release) and 2.8.0 (final). Binaries are generally available for the last final code release on all major platforms. [http://www.flightgear.org/download/main-program/ Click here to proceed to the flightgear binaries download page]

Przykładowo, pod koniec 2012 roku najnowszą wersją kodu była wersja 2.10 (przedpremierowa) i 2.8.0 (finalna). Pliki binarne są ogólnie dostępne dla ostatniego finalnego wydania kodu na wszystkich głównych platformach. Przejdź do naszej oficjalnej [https://www.flightgear.org/download/ strony pobierania] aby pobrać pliki binarne FlightGeara.

Pliki binarne dla innych platform, takich jak IRIX, nie są już obsługiwane, chociaż wydania sprzed 1.0 mogą działać i można je znaleźć w [[FlightGear Git|repozytoriach kodu źródłowego git]].

== Recenzje FlightGear ==
{{Main article|FlightGear Reviews}}

== Łącza zewnętrzne ==
{{Main article|Links}}
* {{Wikipedia|FlightGear}}
* [https://www.flightgear.org Oficjalna strona]
* {{forum link|text=Forum}}
* [https://sourceforge.net/p/flightgear/codetickets/ System śledzenia błędów]
* [http://www.flightgear.org/proposal-3.0.1 Oryginalna propozycja stworzenia FlightGear]

== Źródła ==
* [http://www.flightgear.org/proposal-3.0.1 Original Flight Gear Proposal] by David L. Murr (Revision 3.0.1)
* [http://en.wikipedia.org/wiki/FlightGear Wikipedia]

[[ca:FlightGear]]
[[de:FlightGear]]
[[en:FlightGear]]
[[es:FlightGear]]
[[fr:FlightGear]]
[[it:FlightGear]]
[[nl:FlightGear]]
[[pt:FlightGear]]

Pl/FlightGear

2026-04-03T16:37:13Z

PlayeRom: /* Modele Dynamiki Lotu */

{{Infobox Software
|title = FlightGear Flight Simulator
|logo = FlightGear logo.png
|logosize = 200px
|image = Boeing 777-200ER cockpit.jpg
|alt = W kokpicie [[Boeing 777-200ER]]
|developedby = Developerzy FlightGear i współtwórcy
|initialrelease = Lipec 17, 1997
|latestrelease = {{current release|full}} ({{#time: j xg Y | {{current release|fulldate}} | pl }})
|writtenin = C/C++/Nasal
|os = Windows, Linux, macOS oraz FreeBSD
|platform = wieloplatformowy
|developmentstatus = Aktywny (1996-)
|type = Symulator Lotu
|license = [[GNU General Public License]]
|website = https://www.flightgear.org/
}}

[[File:OV10A-NASA-in-action.jpg|thumb|right|270px|NASA [[OV-10]] we FlightGear 1.0]]

'''FlightGear Flight Simulator''' (w skrócie '''FlightGear''' lub '''FGFS''') to zaawansowana, darmowa i całkowicie otwarto-źródłowa platforma symulacji lotu, stworzona przez wolontariuszy. FlightGear jest wydany na zasadach licencji [[GNU General Public License]] i jest on w większości napisany przy użyciu języka programowania C++.

Coraz bardziej szczegółowe i zaawansowane wersje FlightGeara są corocznie wydawane od zapoczątkowania projektu w 1996 roku.

Najnowsze publiczne wydanie dostępne jest do pobrania na [https://www.flightgear.org/download/ www.flightgear.org/download/] wraz z wersjami dla Microsoft Windows, macOS i Linux.

== Historia ==
{{main article|FlightGear History}}

Rozwój FlightGeara rozpoczął się od propozycji stworzenia otwarto-źródłowego symulatora w 1996 roku, w oparciu o własny kod renderowania grafiki 3D. Rozwój wersji opartej na [[OpenGL]] rozpoczął Curtis Olson w 1997 roku, ale także wiele innych osób miało swój wkład w ten projekt.

FlightGear włączył inne otwarto-źródłowe zasoby, w tym model lotu LaRCsim od NASA oraz powszechnie dostępne dane o elewacji terenu. Pierwsze działające pliki binarne, wykorzystujące OpenGL dla grafiki 3D, pojawiły się w 1997 roku. Entuzjastyczny rozwój kolejnych wersji przez kilka lat zaowocował stopniowo coraz bardziej stabilnymi i zaawansowanymi wersjami. W 2001 roku zespół regularnie wydawał nowe wersje beta, a w 2005 roku dojrzałość oprogramowania doprowadziła do szerszych recenzji i wzrostu popularności. W 2007 roku nastąpiło formalne wyjście z wersji beta wraz z wydaniem wersji 1.0.0, dziesięć lat po pierwszym wydaniu FlightGeara w 1997 roku.

[[File:FG-A-10.jpg|thumb|270px|Kokpit 3D [[A-10]] w wersji 1.0.0, rok 2008]]

W 2008 roku, wersja 1.9.0 FlightGeara przeszła z biblioteki [[PLIB]] na [[OSG]], co spowodowało tymczasową utratę niektórych funkcji programu, takich jak wyświetlanie chmury 3D i cienie, za to nowo wprowadzone funkcje, takie jak cząsteczki, nadały symulacji kolejny stopień realizmu.

== Program ==

Silnik symulacji we FlightGear to [[SimGear]]. Jest on używany zarówno jako aplikacja użytkownika końcowego jak i przy pracach badawczych w środowiskach akademickich w celu rozwoju zagadnień związanych z symulacją lotu.

Przykładem na możliwość dostosowywania FlightGeara jest szeroki wachlarz modeli dostępnych statków powietrznych, od [[:Category:Gliders|szybowców]] przez [[Helicopter|śmigłowców]], [[:Category:Airliners|liniowce]], [[Military aircraft|myśliwców odrzutowych]] do [[Space Shuttle|Wahadłowca Kosmicznego]]. Modele te zostały wykonane i dodane do projektu przez wielu ochotników ze społeczności FlightGeara.

Od wersji 0.9.10 statki powietrzne we FlightGear używają jednego z trzech [[Flight Dynamics Model|modeli dynamiki lotu]] (FDM): [[JSBSim]], [[YASim]] lub [[UIUC]]. Obecnie wyłącznie jeden silnik terenu jest w użyciu, jest nim [[TerraGear]]. Dostępne efekty pogodowe to między innymi chmury 3D, efekty świetlne, pory dnia i nocy.

=== Modele Dynamiki Lotu ===
[[Flight Dynamics Models|Model dynamiki lotu]] (FDM) odpowiada za to w jaki sposób w programie jest symulowany lot statku powietrznego. FlightGear korzysta z własnych oraz zewnętrznych projektów modeli dynamiki lotu. Każdy statek powietrzny musi być tak zaprogramowany, aby korzystał z jednego z dostępnych modeli dynamiki lotu. Obecnie FlightGear jest jedynym, graficznym symulatorem lotu korzystającym ze wszystkich wspomnianych modeli dynamiki lotu, a UIUC i YASim zostały rozwinięte z myślą i w szczególności dla FlightGeara.

Wczesne wersje programu używały FDM, który był oparty na [[LaRCsim]] od NASA. W kolejnych wersjach został on zastąpiony przez bardziej elastyczne FDM.

* [[JSBSim]] - domyślny model dynamiki lotu od 2000 roku.
* [[YASim]] - inny FDM, używający odmiennych metod obliczeniowych. Wprowadzony od wersji 0.7.9 w 2002 roku.
* [[UIUC]] - kolejny FDM, rozwijany przez UIUC Applied Aerodynamics Group z Uniwersytetu w Illinois na Urbana-Champaign, bazujący na LaRCsim. Obecnie już wycofany z wersji deweloperskiej FlightGeara.
* FlightGear może być tak skonfigurowany, aby przyjmował dane z zewnętrznych źródeł FDM takich jak [[MATLAB]].
* Inne niestandardowe FDM zostały napisane dla specyficznych typów statków powietrznych jak balony i sterowce.

=== Zależności FlightGeara ===

W przeciwieństwie do komercyjnych tytułów, głównym wynikiem pracy projektu jest wydanie zestawu kodów źródłowych. Aby użyć programu należy skompilować udostępniony kod dla docelowej platformy, na której ma pracować. Biblioteki użyte przez FlightGeara były różne w zależności od okresu. Główną biblioteką zależną jest SimGear, która jest silnikiem symulacji dla FlightGeara. [[TerraGear]] nie jest zależnością, a raczej tylko nazwą dla domyślnego silnika odpowiadającego za generowanie terenu we FlightGear. OpenAL jest używany dla obsługi dźwięku, włączając wsparcie dla SDL (od wersji 0.9.5). PLIB jest użyte do obsługi sprzętowej, także dla obsługi dźwięku przed wprowadzeniem OpenAL. [[OpenGL]] jest użyty dla swoich funkcji 3D, DirectX nie jest wspierany. Silnik graficzny [[OpenSceneGraph]] jest również zintegrowany z FlightGearem. Na koniec do kompilacji jest konieczna biblioteka Simple Direct Media Layer (SDL). Niektóre zależności mogą się różnić w zależności od tego na jaką platformę docelową jest kompilowany kod. Użytkownicy FlightGeara powinni sami kompilować kod lub jeżeli nie jest on dostępny w ramach projektu, korzystać z wersji binarnej udostępnionej przez osoby trzecie.

== Sprzęt==

Sprzęt konieczny do uruchomienia FlightGeara jest ograniczony do sprzętu, który wspiera [[OpenGL]] i akcelerację 3D, przy czym najlepiej wspierana jest NVIDIA. Wczesne wersje posiadały wsparcie dla kart 3dfx, jednak wsparcie to zostało wycofane wraz ze zwiększającymi się wymaganiami sprzętowymi.

[[File:Fgrun-page2.jpg|thumb|left|270px|[[FlightGear Launch Control|FlightGear Launcher]]]]
== Dodatki i dostosowywanie ==

Istnieją programy, które są zintegrowane z FlightGearem (zależności) lub są programami zewnętrznymi i współpracują z nim. Oprogramowanie takie może być częścią projektu FlightGear lub może być rozwijane niezależnie, ale udostępniane przez projekt FlightGear.

Ważnym dodatkowym oprogramowaniem jest interfejs graficzny, służący do uruchomienia pliku wykonywalnego FlightGeara. We wczesnych wersjach, FlightGear mógł być uruchomiony jedynie z wykorzystaniem [[Pl/Opcje wiersza poleceń|opcji wiersza poleceń]]. Jednakże, w 2003 roku od wersji 0.9.3, został dołączony ''[[FlightGear Launch Control|FGRun]]'' - program startowy z interfejsem graficznym. Obecnie tę rolę spełnia ''[[FlightGear Qt launcher|QT Launcher]]''.
Podobną funkcję spełnia ''[[KFreeFlight]]'' dla środowiska KDE. ''FGTools'' jest alternatywnym front-endem dla środowiska Windows. ''FGKicker'' jest używany dla GTK+.

Inne znaczące programy obejmują edytory i projekty związane z terenem. ''[[Atlas]]'' jest mapą dla FlightGeara; ''[[Kelpie Flight Planner]]'' to rozwijane w Javie narzędzie do planowania lotów.
''[[FlightGear Scenery Designer]]'' to edytor scenerii, pomocny przy pracy z danymi terenu. ''[[World Custom Scenery Project]]'' to projekt pomagający koordynować wspólne wysiłki na rzecz tworzenia scenerii. Na koniec edytor ''[[TaxiDraw]]'' do tworzenia nowych pasów startowych i dróg kołowania.

=== Statki Powietrzne ===
{{Main article|Table of models}}

Na początku, FlightGear dysponował tylko jednym statkiem powietrznym, był to Navion zawarty w projekcie LaRCsim od NASA, który w 2000 roku został zastąpiony przez Cessnę 172P. Rozwój UIUC i JSBSim przyniósł ze sobą kilka kolejnych samolotów, podobnie jak rozwój YASim, który od tego czasu stał się głównym FDM używanym we FlightGear. W wersji 2.12 dostępnych jest ponad 400 samolotów w ponad 900 unikalnych malowaniach, choć tylko kilka z nich wchodzi w skład pakietu podstawowego.

[[File:EHAM.jpg|thumb|270px|[[Boeing 737-300|Boeing 733]] zaparkowany w scenerii [[EHAM]] ]]

=== Sceneria ===
{{Main article|Scenery}}

Projekt [[World Scenery]] dla FlightGeara zawiera dane o wysokości i klasie terenu całego świata.
Obiekty takie jak terminale, wiatraki i mosty są zebrane w [[FlightGear Scenery Database|bazie danych scenerii]].

=== Sieć i wiele monitorów ===

Istnieje kilka możliwości, które pozwalają komunikować się jednej instancji FlightGeara z inną. Dostępny jest protokół [[Multiplayer Howto|multiplayer]], co umożliwia lot w formacji lub symulowanie kontroli ruchu lotniczego w sieci lokalnej. Protokół Multiplayer zostanie wkrótce tak rozbudowany, aby także pozwalał na pracę w internecie. Dodatkową cechą możliwości sieciowych jest opcja podglądu innych pilotów na mapach Google.

Kilka instancji FlightGeara może zostać tak zsynchronizowana, aby korzystały z wielu monitorów. Możliwe jest uzyskanie bardzo dobrej synchronizacji między monitorami jeżeli wszystkie instancje FlightGeara będą pracowały z tą samą częstotliwością wyświetlania klatek.

== Kod FlightGeara vs wersja binarna ==

W przeciwieństwie do komercyjnego oprogramowania, data wydania dotyczy wyłącznie kodu źródłowego, a nie wersji binarnej. Aby stworzyć wykonywalny program, kod źródłowy musi zostać skompilowany, co wymaga kilku bibliotek, włączając w to kilka ogólnych oraz specyficznych dla platfory. Jednak jest to zbyt trudne zadanie dla wielu zwykłych użytkowników, dlatego ochotnicy społeczności pracują, aby udostępnić wersje binarne dla poszczególnych platform i systemów operacyjnych. Dystrybucje te różnią się poziomem stabilności, wydajnością, zależnościami, a także tym, jak aktualne są one w stosunku do kodu źródłowego. Dla przykładu, niektóre ze starszych wersji binarnych będą pracować poprawnie pod Mac OS 9, ale nowsze wydania wymagają określonych wersji Mac OS X.

For example, by late 2012 the latest code release was 2.10 (pre-release) and 2.8.0 (final). Binaries are generally available for the last final code release on all major platforms. [http://www.flightgear.org/download/main-program/ Click here to proceed to the flightgear binaries download page]

Przykładowo, pod koniec 2012 roku najnowszą wersją kodu była wersja 2.10 (przedpremierowa) i 2.8.0 (finalna). Pliki binarne są ogólnie dostępne dla ostatniego finalnego wydania kodu na wszystkich głównych platformach. Przejdź do naszej oficjalnej [https://www.flightgear.org/download/ strony pobierania] aby pobrać pliki binarne FlightGeara.

Pliki binarne dla innych platform, takich jak IRIX, nie są już obsługiwane, chociaż wydania sprzed 1.0 mogą działać i można je znaleźć w [[FlightGear Git|repozytoriach kodu źródłowego git]].

== Recenzje FlightGear ==
{{Main article|FlightGear Reviews}}

== Łącza zewnętrzne ==
{{Main article|Links}}
* {{Wikipedia|FlightGear}}
* [https://www.flightgear.org Oficjalna strona]
* {{forum link|text=Forum}}
* [https://sourceforge.net/p/flightgear/codetickets/ System śledzenia błędów]
* [http://www.flightgear.org/proposal-3.0.1 Oryginalna propozycja stworzenia FlightGear]

== Źródła ==
* [http://www.flightgear.org/proposal-3.0.1 Original Flight Gear Proposal] by David L. Murr (Revision 3.0.1)
* [http://en.wikipedia.org/wiki/FlightGear Wikipedia]

[[ca:FlightGear]]
[[de:FlightGear]]
[[en:FlightGear]]
[[es:FlightGear]]
[[fr:FlightGear]]
[[it:FlightGear]]
[[nl:FlightGear]]
[[pt:FlightGear]]

Pl/FlightGear

2026-04-03T16:33:53Z

PlayeRom:

{{Infobox Software
|title = FlightGear Flight Simulator
|logo = FlightGear logo.png
|logosize = 200px
|image = Boeing 777-200ER cockpit.jpg
|alt = W kokpicie [[Boeing 777-200ER]]
|developedby = Developerzy FlightGear i współtwórcy
|initialrelease = Lipec 17, 1997
|latestrelease = {{current release|full}} ({{#time: j xg Y | {{current release|fulldate}} | pl }})
|writtenin = C/C++/Nasal
|os = Windows, Linux, macOS oraz FreeBSD
|platform = wieloplatformowy
|developmentstatus = Aktywny (1996-)
|type = Symulator Lotu
|license = [[GNU General Public License]]
|website = https://www.flightgear.org/
}}

[[File:OV10A-NASA-in-action.jpg|thumb|right|270px|NASA [[OV-10]] we FlightGear 1.0]]

'''FlightGear Flight Simulator''' (w skrócie '''FlightGear''' lub '''FGFS''') to zaawansowana, darmowa i całkowicie otwarto-źródłowa platforma symulacji lotu, stworzona przez wolontariuszy. FlightGear jest wydany na zasadach licencji [[GNU General Public License]] i jest on w większości napisany przy użyciu języka programowania C++.

Coraz bardziej szczegółowe i zaawansowane wersje FlightGeara są corocznie wydawane od zapoczątkowania projektu w 1996 roku.

Najnowsze publiczne wydanie dostępne jest do pobrania na [https://www.flightgear.org/download/ www.flightgear.org/download/] wraz z wersjami dla Microsoft Windows, macOS i Linux.

== Historia ==
{{main article|FlightGear History}}

Rozwój FlightGeara rozpoczął się od propozycji stworzenia otwarto-źródłowego symulatora w 1996 roku, w oparciu o własny kod renderowania grafiki 3D. Rozwój wersji opartej na [[OpenGL]] rozpoczął Curtis Olson w 1997 roku, ale także wiele innych osób miało swój wkład w ten projekt.

FlightGear włączył inne otwarto-źródłowe zasoby, w tym model lotu LaRCsim od NASA oraz powszechnie dostępne dane o elewacji terenu. Pierwsze działające pliki binarne, wykorzystujące OpenGL dla grafiki 3D, pojawiły się w 1997 roku. Entuzjastyczny rozwój kolejnych wersji przez kilka lat zaowocował stopniowo coraz bardziej stabilnymi i zaawansowanymi wersjami. W 2001 roku zespół regularnie wydawał nowe wersje beta, a w 2005 roku dojrzałość oprogramowania doprowadziła do szerszych recenzji i wzrostu popularności. W 2007 roku nastąpiło formalne wyjście z wersji beta wraz z wydaniem wersji 1.0.0, dziesięć lat po pierwszym wydaniu FlightGeara w 1997 roku.

[[File:FG-A-10.jpg|thumb|270px|Kokpit 3D [[A-10]] w wersji 1.0.0, rok 2008]]

W 2008 roku, wersja 1.9.0 FlightGeara przeszła z biblioteki [[PLIB]] na [[OSG]], co spowodowało tymczasową utratę niektórych funkcji programu, takich jak wyświetlanie chmury 3D i cienie, za to nowo wprowadzone funkcje, takie jak cząsteczki, nadały symulacji kolejny stopień realizmu.

== Program ==

Silnik symulacji we FlightGear to [[SimGear]]. Jest on używany zarówno jako aplikacja użytkownika końcowego jak i przy pracach badawczych w środowiskach akademickich w celu rozwoju zagadnień związanych z symulacją lotu.

Przykładem na możliwość dostosowywania FlightGeara jest szeroki wachlarz modeli dostępnych statków powietrznych, od [[:Category:Gliders|szybowców]] przez [[Helicopter|śmigłowców]], [[:Category:Airliners|liniowce]], [[Military aircraft|myśliwców odrzutowych]] do [[Space Shuttle|Wahadłowca Kosmicznego]]. Modele te zostały wykonane i dodane do projektu przez wielu ochotników ze społeczności FlightGeara.

Od wersji 0.9.10 statki powietrzne we FlightGear używają jednego z trzech [[Flight Dynamics Model|modeli dynamiki lotu]] (FDM): [[JSBSim]], [[YASim]] lub [[UIUC]]. Obecnie wyłącznie jeden silnik terenu jest w użyciu, jest nim [[TerraGear]]. Dostępne efekty pogodowe to między innymi chmury 3D, efekty świetlne, pory dnia i nocy.

=== Modele Dynamiki Lotu ===
[[Flight Dynamics Models|Model dynamiki lotu]] (FDM) odpowiada za to w jaki sposób w programie jest symulowany lot statku powietrznego. FlightGear korzysta z własnych oraz zewnętrznych projektów modeli dynamiki lotu. Każdy statek powietrzny musi być tak zaprogramowany, aby korzystał z jednego z dostępnych modeli dynamiki lotu. Obecnie FlightGear jest jedynym, graficznym symulatorem lotu korzystającym ze wszystkich wspomnianych modeli dynamiki lotu, a UIUC i YASim zostały rozwinięte z myślą i w szczególności dla FlightGeara.

Wczesne wersje programu używały FDM, który był oparty na [[LaRCsim]] od NASA. W kolejnych wersjach został on zastąpiony przez bardziej elastyczne FDM.

* [[JSBSim]] - domyślny model dynamiki lotu od 2000 roku.
* [[YASim]] - inny FDM, używający odmiennych metod obliczeniowych. Wprowadzony od wersji 0.7.9 w 2002 roku.
* [[UIUC]] - kolejny FDM, rozwinięty przez UIUC Applied Aerodynamics Group z Uniwersytetu w Illinois na Urbana-Champaign, bazujący na LaRCsim.
* FlightGear może być tak skonfigurowany tak, aby przyjmował dane z zewnętrznych źródeł FDM takich jak [[MATLAB]].
* Inne niestandardowe FDM zostały napisane dla specyficznych typów statków powietrznych jak balony i sterowce.

=== Zależności FlightGeara ===

W przeciwieństwie do komercyjnych tytułów, głównym wynikiem pracy projektu jest wydanie zestawu kodów źródłowych. Aby użyć programu należy skompilować udostępniony kod dla docelowej platformy, na której ma pracować. Biblioteki użyte przez FlightGeara były różne w zależności od okresu. Główną biblioteką zależną jest SimGear, która jest silnikiem symulacji dla FlightGeara. [[TerraGear]] nie jest zależnością, a raczej tylko nazwą dla domyślnego silnika odpowiadającego za generowanie terenu we FlightGear. OpenAL jest używany dla obsługi dźwięku, włączając wsparcie dla SDL (od wersji 0.9.5). PLIB jest użyte do obsługi sprzętowej, także dla obsługi dźwięku przed wprowadzeniem OpenAL. [[OpenGL]] jest użyty dla swoich funkcji 3D, DirectX nie jest wspierany. Silnik graficzny [[OpenSceneGraph]] jest również zintegrowany z FlightGearem. Na koniec do kompilacji jest konieczna biblioteka Simple Direct Media Layer (SDL). Niektóre zależności mogą się różnić w zależności od tego na jaką platformę docelową jest kompilowany kod. Użytkownicy FlightGeara powinni sami kompilować kod lub jeżeli nie jest on dostępny w ramach projektu, korzystać z wersji binarnej udostępnionej przez osoby trzecie.

== Sprzęt==

Sprzęt konieczny do uruchomienia FlightGeara jest ograniczony do sprzętu, który wspiera [[OpenGL]] i akcelerację 3D, przy czym najlepiej wspierana jest NVIDIA. Wczesne wersje posiadały wsparcie dla kart 3dfx, jednak wsparcie to zostało wycofane wraz ze zwiększającymi się wymaganiami sprzętowymi.

[[File:Fgrun-page2.jpg|thumb|left|270px|[[FlightGear Launch Control|FlightGear Launcher]]]]
== Dodatki i dostosowywanie ==

Istnieją programy, które są zintegrowane z FlightGearem (zależności) lub są programami zewnętrznymi i współpracują z nim. Oprogramowanie takie może być częścią projektu FlightGear lub może być rozwijane niezależnie, ale udostępniane przez projekt FlightGear.

Ważnym dodatkowym oprogramowaniem jest interfejs graficzny, służący do uruchomienia pliku wykonywalnego FlightGeara. We wczesnych wersjach, FlightGear mógł być uruchomiony jedynie z wykorzystaniem [[Pl/Opcje wiersza poleceń|opcji wiersza poleceń]]. Jednakże, w 2003 roku od wersji 0.9.3, został dołączony ''[[FlightGear Launch Control|FGRun]]'' - program startowy z interfejsem graficznym. Obecnie tę rolę spełnia ''[[FlightGear Qt launcher|QT Launcher]]''.
Podobną funkcję spełnia ''[[KFreeFlight]]'' dla środowiska KDE. ''FGTools'' jest alternatywnym front-endem dla środowiska Windows. ''FGKicker'' jest używany dla GTK+.

Inne znaczące programy obejmują edytory i projekty związane z terenem. ''[[Atlas]]'' jest mapą dla FlightGeara; ''[[Kelpie Flight Planner]]'' to rozwijane w Javie narzędzie do planowania lotów.
''[[FlightGear Scenery Designer]]'' to edytor scenerii, pomocny przy pracy z danymi terenu. ''[[World Custom Scenery Project]]'' to projekt pomagający koordynować wspólne wysiłki na rzecz tworzenia scenerii. Na koniec edytor ''[[TaxiDraw]]'' do tworzenia nowych pasów startowych i dróg kołowania.

=== Statki Powietrzne ===
{{Main article|Table of models}}

Na początku, FlightGear dysponował tylko jednym statkiem powietrznym, był to Navion zawarty w projekcie LaRCsim od NASA, który w 2000 roku został zastąpiony przez Cessnę 172P. Rozwój UIUC i JSBSim przyniósł ze sobą kilka kolejnych samolotów, podobnie jak rozwój YASim, który od tego czasu stał się głównym FDM używanym we FlightGear. W wersji 2.12 dostępnych jest ponad 400 samolotów w ponad 900 unikalnych malowaniach, choć tylko kilka z nich wchodzi w skład pakietu podstawowego.

[[File:EHAM.jpg|thumb|270px|[[Boeing 737-300|Boeing 733]] zaparkowany w scenerii [[EHAM]] ]]

=== Sceneria ===
{{Main article|Scenery}}

Projekt [[World Scenery]] dla FlightGeara zawiera dane o wysokości i klasie terenu całego świata.
Obiekty takie jak terminale, wiatraki i mosty są zebrane w [[FlightGear Scenery Database|bazie danych scenerii]].

=== Sieć i wiele monitorów ===

Istnieje kilka możliwości, które pozwalają komunikować się jednej instancji FlightGeara z inną. Dostępny jest protokół [[Multiplayer Howto|multiplayer]], co umożliwia lot w formacji lub symulowanie kontroli ruchu lotniczego w sieci lokalnej. Protokół Multiplayer zostanie wkrótce tak rozbudowany, aby także pozwalał na pracę w internecie. Dodatkową cechą możliwości sieciowych jest opcja podglądu innych pilotów na mapach Google.

Kilka instancji FlightGeara może zostać tak zsynchronizowana, aby korzystały z wielu monitorów. Możliwe jest uzyskanie bardzo dobrej synchronizacji między monitorami jeżeli wszystkie instancje FlightGeara będą pracowały z tą samą częstotliwością wyświetlania klatek.

== Kod FlightGeara vs wersja binarna ==

W przeciwieństwie do komercyjnego oprogramowania, data wydania dotyczy wyłącznie kodu źródłowego, a nie wersji binarnej. Aby stworzyć wykonywalny program, kod źródłowy musi zostać skompilowany, co wymaga kilku bibliotek, włączając w to kilka ogólnych oraz specyficznych dla platfory. Jednak jest to zbyt trudne zadanie dla wielu zwykłych użytkowników, dlatego ochotnicy społeczności pracują, aby udostępnić wersje binarne dla poszczególnych platform i systemów operacyjnych. Dystrybucje te różnią się poziomem stabilności, wydajnością, zależnościami, a także tym, jak aktualne są one w stosunku do kodu źródłowego. Dla przykładu, niektóre ze starszych wersji binarnych będą pracować poprawnie pod Mac OS 9, ale nowsze wydania wymagają określonych wersji Mac OS X.

For example, by late 2012 the latest code release was 2.10 (pre-release) and 2.8.0 (final). Binaries are generally available for the last final code release on all major platforms. [http://www.flightgear.org/download/main-program/ Click here to proceed to the flightgear binaries download page]

Przykładowo, pod koniec 2012 roku najnowszą wersją kodu była wersja 2.10 (przedpremierowa) i 2.8.0 (finalna). Pliki binarne są ogólnie dostępne dla ostatniego finalnego wydania kodu na wszystkich głównych platformach. Przejdź do naszej oficjalnej [https://www.flightgear.org/download/ strony pobierania] aby pobrać pliki binarne FlightGeara.

Pliki binarne dla innych platform, takich jak IRIX, nie są już obsługiwane, chociaż wydania sprzed 1.0 mogą działać i można je znaleźć w [[FlightGear Git|repozytoriach kodu źródłowego git]].

== Recenzje FlightGear ==
{{Main article|FlightGear Reviews}}

== Łącza zewnętrzne ==
{{Main article|Links}}
* {{Wikipedia|FlightGear}}
* [https://www.flightgear.org Oficjalna strona]
* {{forum link|text=Forum}}
* [https://sourceforge.net/p/flightgear/codetickets/ System śledzenia błędów]
* [http://www.flightgear.org/proposal-3.0.1 Oryginalna propozycja stworzenia FlightGear]

== Źródła ==
* [http://www.flightgear.org/proposal-3.0.1 Original Flight Gear Proposal] by David L. Murr (Revision 3.0.1)
* [http://en.wikipedia.org/wiki/FlightGear Wikipedia]

[[ca:FlightGear]]
[[de:FlightGear]]
[[en:FlightGear]]
[[es:FlightGear]]
[[fr:FlightGear]]
[[it:FlightGear]]
[[nl:FlightGear]]
[[pt:FlightGear]]

Bendix/King KAP140 Autopilot

2026-04-01T16:11:06Z

PlayeRom:

The '''''Bendix/King KAP 140''''' '''Two Axis/Altitude Preselect Autopilot System''' is the [[autopilot]] of the default [[Cessna 172]], controlling the [[elevator]] and [[aileron]]s.

== Quick Guide ==
[[File:KAP140.jpg|KAP140 Two Axis with Preselect Altitude]]

Normally the autopilot boots as soon as the electrical system has power<ref>newer models simulate preflight checks, so it's not immediately available after power-on.</ref>. It is commonly wired to an electrical avionics bus and secured by a dedicated breaker; if it stays dark, check power, avionics bus switches and the breaker.

# To activate the autopilot in wings level (ROL) and vertical speed (VS) modes, press and hold the AP button for 0.25 seconds<ref>for older models, just press</ref>. The autopilot will try to keep the wings level by keeping the turn rate at zero. The autopilot will also try to maintain the vertical speed at activation. Use the UP and DN buttons to set the desired vertical speed.
# With the autopilot active you can use the HDG button to toggle between wings level (ROL) and heading select (HDG) modes. In heading select mode the autopilot will try to maintain the heading selected by the heading bug on the directional gyro.
# Use NAV button to toggle between navigation mode (NAV) and wings level (ROL) mode. NAV mode is flying to NAV1 or GPS. That is one of the Heading modes in KAP140 that direction when heading bug OBS operated. Please be careful.
# Toggle other mode and approach (APR) mode when APR button pushed and following marker beacon, VOR, GPS and [[ILS]] (localizer and glide slope) for automatic approach. This mode is recommended for instrument approach.
# The REV button enables the back course mode having the autopilot flying away from the runway. This mode is like APR mode except that the direction is away from the localizer (LOC) and that glide slope (GS) is not used.
# Use the ALT button to toggle between vertical speed (VS) and altitude hold (ALT) modes. In altitude hold mode the UP and DN buttons change the altitude by 20 feet per press.
# The ARM button enables altitude preselect by the rotary knob using procedure below, pushing it again disables altitude preselect.
## Input the current atmospheric pressure using the BARO button and rotary knob
## Check that the display is showing altitude and set your desired altitude, using the rotary knob.
## Set your desired vertical speed using UP and DN button.
## Press the ARM button that is enable ARM mode.
# The BARO button sets the atmospheric pressure. When the BARO button is pushed, enter desired atmospheric pressure using the rotary dial/knob. When pushed long, it switches the setting display to hPa (and back)<ref>only on newer simulated models</ref> (hint: you can do InHG<>hPa conversion easily with this)
# Press the AP button to deactivate the autopilot. The horizontal and vertical modes can not be activated independently.

Please read the Pilot's Guide for complete instructions on the use of the KAP140 Autopilot system.

== Limits ==
* Not certified for use below 200ft [[AGL]], below 80 or above 160 knots [[IAS]] or when alternate static port is active.
* Only activate when flaps are retracted.
* Do not override the autopilot with flight controls, instead deactivate it temporarily to make manual adjustments.
* Do not activate the autopilot near the ground (takeoff, landing) or at low speeds: it will mess up and may crash you into the ground.
* It also has no autoland capability, so it can't land you based on ILS signals.
* Don't activate it when in an unstable or mistrimmed flight attitude. Tough it will try(!) to stabilize the plane, this is unsafe.
* It will not rescue you out of a stall, so watch the airspeed regularly. If the plane slows down, the autopilot will increase pitch to maintain the VS/ALT mode ordered, putting you into a stall. Disengage the autopilot and manually stabilize your flight.
* Altitude catching only works if you are flying towards the desired setting. For example, if you are at 1500ft, entered 2000ft as target and then descend, it will not intercept but fly you into the ground. Similarly, if you enter an altitude below you and accidentally climb, you will eventually reach the planes service ceiling and stall. The "ALT ARM" mode does not mean "bring me to that altitude".
* Like with altitude interception, intercepting a VOR radial or ILS will not work, if the heading bug was not aligned or if you try to intercept from a custom angle (ie. engaging NAV mode from ROL).

== Altitude alert (beeping sound) ==
A nice feature for assisting manual flights is the altitude alert. This is the aural beeping alert when you get near the selected altitude preset:
* When getting near 1000ft of the selected altitude, it starts to beep five times and show a steady "ALERT" right below the altitude.
* When intercepting the altitude, the ALERT annunciator vanishes if you get 200ft near, and will shortly flash up when crossing the selected altitude to signal it "catched on".
* When now exceeding the +-200ft band, it will alert by flashing and beeping.

This feature just needs a calibrated baro setting and a selected altitude, thus it is also active when using the modes utilizing altitude preset described below.

== Example workflow ==
This example tries to show you how to deal with the autopilot to achieve common tasks. There are more advanced techniques to achieve with the autopilot, but they are out of scope for this quick introduction. Please refer to the 'KAP 140 Pilot's Guide' which is linked below.

For better familiarization it would be good to follow trough the following guide inside flightgear.

{{note| Be aware of procedure differences when you have an [[HSI|Horizontal Situation Indicator (HSI)]] installed in the aircraft: In this case, the KAP 140 will not have an automatic 45°-Intercept for NAV/APR/REV modes when switching from HDG-mode and you need to select the desired intercept course manually by turning the heading bug to the desired intercept course. }}

=== Before-takeoff preparations ===
* For the HDG/NAV mode it is important to calibrate the [[Avionics_and_instruments#Directional_Gyro|Directional Gyro (DG)]] to the magnetic compass (with running motor, so the DG has power): read the magnetic compass and rotate the DG so its upper bearing mark reflects that course (use the red heading bug if necessary, it makes it easier at the beginning). If your DG was not calibrated, this will not be the magnetic course and you probably will not get where you wanted to.
* For the ALT mode it is important to calibrate the barometric setting of the autopilot to the one of the altimeter: read the altimeters baro setting from the Kollsman window (the small window at the altimeter), press the "BARO" key at the autopilot and rotate the right "altitude-preselect knob" so the autopilot shows the same setting. If you miss to calibrate the baro setting, you will under-/overshoot altitude presets
* You should run through the HDG and VS modes on ground as preflight check to make sure the autopilot is operating the aileron, elevator and trim wheel
* If you intend to follow the runway heading after takeoff, now is a good time to adjust the heading bug.
* If you intend to climb to a specific altitude and let the autopilot intercept it, you should now rotate the altitude preselect knob of the autopilot to the desired altitude.

=== After Takeoff: Hold heading, continue climbing ===
It is not advised to engage the autopilot immediately for takeoff as it will mess up with lower speeds. Establish a smooth climb rate and trimmed flight first.

When you achieved a stable climb rate after takeoff, engage the autopilot by pressing "AP". It will engage in ROL/VS mode: keeps the wings level and maintain climb at the current rate. The moment you engage the autopilot it will show "ROL", "VS", and at the right side the currently set climb rate for some seconds. Always visually confirm the autopilot shows the modes you expect!

If not done yet, rotate the red heading bug at the DG to the desired heading before switching to HDG mode.

Once you press the HGT button, the autopilot will switch from ROL to the HDG mode, and the plane now follows the desired course. When you change the heading bug, the plane will bank and follow the new heading (it will do this at standard turn rate).

=== Climb to Altitude, then hold it (intercept altitude) ===
The autpilot now should be in HDG/VS mode. You should check the vertical speed the autopilot automatically set to the climb rate you had when engaging it. Using the buttons "UP" and "DN" you can adjust the vertical speed setting to the desired value.

To let the autopilot intercept the desired altitude, you need to enter it using the knob on the right side. Turn in the desired altitude.
Doing this should automatically "arm" the autopilot (it shows "ALT ARM"), telling you that it waits to reach the entered altitude. If it was not arming automatically, you can arm it by manually pressing "ARM".

The plane will now climb to the altitude you requested. When you get at 1000ft near your setting, it will beep to let you know its close. Once you reach the altitude it will reduce the climb rate to zero, leveling out at the desired altitude: this is indicated by the "ALT ARM" vanishing.
If you are not at the altitude you entered, you probably forgot to calibrate the baro setting.

=== Enroute climb / descend ===
In case you want to change the currently maintained altitude, you can do so by two means:
# ''Small adjustments'' can be made by pressing just the UP/DN buttons. Each press will adjust the set altitude for 20ft.<ref>In reality you can hold the button to trigger climb/descend at 500ft/m until you release the key. Recent KAP140 simulations implement this.</ref> Note that we are in ALT mode, so we adjust absolute altiutde with UP/DN knobs, not climb rate!
# For ''larger adjustments'' you just rotate the altitude preselect knob to the new desired altitude. The autopilot will show "ALT ARM". When you are ready to climb or descend, put the autopilot to VS mode by pressing the ALT button. Now push UP/DN buttons to climb or descend, and everything else will behave like already described above. You can adjust the desired climb rate anytime. When intercepting, the autopilot will automatically enter ALT mode again (which changes the behaviour of UP/DN buttons to absolute corrections too!).
# For other cases you can also use the manual ALT mode: Put the autopilot in VS mode by pressing "ALT", adjust the climb rate to your liking and as soon as you feel the altitude is right, you can press "ALT" again. The AP will show "ALT" immediately, indicating it is holding this altitude. If your climb rate was a little higher, you probably overshoot the desired altitude, but the autopilot will soon return to it.

Note that you can use these techniques with ROL, HDG and NAV modes.

=== VOR interception (NAV mode) ===
For longer trips it is nice to let the autopilot track a [[VOR]] radial. The difference to the HDG mode is that the plane will compensate for wind drift as it seeks to keep the [https://en.wikipedia.org/wiki/Course_deviation_indicator CDI]-needle centered.

To use the NAV mode you have to tune NAV1 to the VORs frequency and select the desired radial with the OBS knob of your [https://en.wikipedia.org/wiki/Course_deviation_indicator CDI1] (which links to NAV1).
Now you can intercept the radial, and you have two options to do that:
# ''From HDG mode'': select the radial also on your DG heading bug (the plane will try to follow that now). Then engage by pressing "NAV". The autopilot will show "NAV ARM" and turn the plane to an 45° interception angle, but it will remain in HDG mode. Once you are close enough, the NAV-mode will kick in ("NAV ARM" vanishes and NAV shows) - the plane now follows the radial.
# ''From ROL mode'' (all angle intercept): It works like HDG mode, but once you push the NAV knob, the plane will intercept the radial at the angle you are currently flying. To initially bring the plane to the desired angle, use either HDG-mode with the heading bug, or fly manually, then engage ROL mode by pressing HDG.
Both modes will show a flashing "HDG" annunciator to remind you that you have to set the DG heading bug to the radial in both cases (the autopilot computes the needed course from that)!

=== ILS assisted approach (APR mode) ===
The NAV and APR modes are really similar, but the APR mode does additionally follow also the glideslope signal from an [https://en.wikipedia.org/wiki/Instrument_landing_system ILS], and the ILS has a fixed radial (so it ignores the OBS knob setting of the CDI!).

The interception works exactly as in the NAV mode described above. If you engage the APR mode knob the plane will start to intercept the signal, showing "APR ARM" and continue with the currently selected lateral mode (ROL or HDG with 45° intercept angle). Remember to set the DG heading bug to the desired approach course ("HDG" will flash to remember you of that).

As soon as the plane intercepts the localizer (that drives the CDI needle left/right), it will behave like in NAV mode. "APR ARM" will vanish and switch to "APR", showing you are in approach mode now.

When the APR mode engages, the GS mode will try to intercept the vertical glideslope beam. As long as you stay below the beam, it will show "GS ARM". When the vertical glideslope is intercepted, the plane will start to follow it downwards.

'''Attention! This mode is dangerous''', because it will drive you into the ground if you don't disengage the autopilot. It is not meant to land you automatically, just to guide you close to the runway. As soon as you are near the runway you should disengage and land manually.

=== Flying opposite direction of VOR or ILS (REV mode) ===
Using the REV mode allows you to fly away from an VOR or ILS localizer signal (note that glideslope is ignored).
It works the same as NAV or APR, just in the opposite compass direction. This is helpful if you want to fly straight away from the runway at start or to fly away from a VOR that you tuned the inbound course into the OBS.

As APR and NAV, you can intercept the radial or localizer either from ROL or HDG mode.
In either case, dial in the Front Inbound course into the OBS and the DG heading bug, and not the direction you want to fly.
Course reversal is done from the autopilot automatically.

== Related content ==
* [[Joystick Autopilot Bindings]] Snippets for joystick.xml file that allow control of most of the autopilot functions using the joystick.
: {{icaution|These joystick bindings only work with the older KAP versions, not the new one with the preflight check simulated!}}

== External links ==
*[https://bkx.bendixking.com/downloads/006-18034-0000_3.pdf Bendix/King KAP 140 Pilot's Guide download link] (PDF, 6.8 MB), Honywell, rev. 3, Nov 2005.
*[https://www.bendixking.com/content/dam/bendixking/en/documents/document-lists/downloads-and-manuals/006-18034-0000-KAP-140-Pilots-Guide.pdf Bendix/King KAP 140 Pilot's Guide], Honeywell, rev. 3, Nov 2005.

==References==

[[Category:Aircraft instruments]]

[[de:Autopilot Bendix/King KAP140]]
[[es:Piloto automático Bendix/King KAP140]]

<references />

Nasal Browser

2026-03-30T10:01:05Z

PlayeRom:

[[File:Nasal Namespace Browser Prototype.png|thumb|Screen shot showing the new [[Nasal Browser|Nasal Namespace Browser]] that is currently being worked on by Philosopher.]]

{{Nasal Navigation}}

The '''Nasal '''('''Namespace''')''' Browser''' is a dialog created by user Philosopher that allows the user to peek at the internal state of Nasal (starting from the global namespace). It displays an alphabetical list of keys mapped to values using the [[Canvas]] framework. Hashes and vectors are shown as their size and can be entered into via clicking on them; scalars' complete values are shown while ghosts and other types and represented in brackets.

The source code can be viewed [{{gitorious url
| proj = fg
| repo = canvas-hackers-fgdata
| path = Nasal/nasal_browser.nas
| branch = topics/nasal-browser-rebased
| view = raw
}} here]

{{Note|Per-update performance of the dialog (i.e. how fast it runs) is determined by how big the namespace is. On the developer's computer, it takes about 20-30 ms to update the global namespace, much less for much smaller namespaces. The dialog is automatically updated about every 0.6 seconds.|width=70%}}

== Features ==
Each entry is color-coded by type and scrollable via the Canvas scroll widget, sorted either by name or type and name. In a hash, each key is shown as either a string, a number, or a symbol, depending on what it really is (i.e. a scalar may be numeric but still a string; also, interned symbols are special cases of strings). Strings are shown in single quotes, symbols and numbers are shown without quotes. For strings, the brightness of the color is optionally reduced.

If the binary includes the <code>debug.decompile()</code> extension function (i.e. is part of [[User:Philosopher/Nasal introspection|extended-nasal]]) then functions can optionally be shown with their arguments, e.g. <code>isa = <func(obj,class)></code> and <code>_setlistener = <internal func></code> (in the sense of a function implemented in C/C++).

Values can be edited when they are clicked on; the edit bar then becomes activated and will capture key presses. A valid Nasal expression should be entered, which will be executed on {{key press|Enter}}.

== 2025 Revival ==

Since 2025, the Nasal Browser project has been revived and is now maintained as a standalone addon. As the original source code repository is no longer available, this version serves as its direct successor, updated for compatibility with modern FlightGear versions.

The new version is hosted on GitHub: {{github source|user=PlayeRom|repo=flightgear-addon-nasal-namespace-browser|text=playerom/flightgear-addon-nasal-namespace-browser}}. It is fully integrated with the FlightGear addon system, providing a modernized interface for browsing the Nasal namespace while preserving historical functionality.

Notably, the addon '''includes the original source code''', which can be optionally enabled for those who prefer the classic experience or wish to compare implementations.

* '''Modernized UI:''' Improved compatibility with recent FlightGear releases.
* '''Easy Installation:''' Fully compatible with the FlightGear Addon system.
* '''Project Homepage & Source:''' {{github source|user=PlayeRom|repo=flightgear-addon-nasal-namespace-browser|text=playerom/flightgear-addon-nasal-namespace-browser}}
* '''Compatibility:''' FlightGear 2024.1+

FlightGear Newsletter

2026-03-30T09:02:55Z

PlayeRom: /* Archive */

[[File:magagazine.png|right]]

The '''FlightGear Newsletter''' is intended to provide a collection of the latest developments from the worldwide [[FlightGear]] community. With so much development ongoing, it's almost impossible for anyone to keep up. The newsletter was started in July 2009, and is presented on a monthly basis. It is a collaborative effort that is created, edited and distributed via the [[FlightGear Wiki]], and all FlightGear users, contributors and developers are invited to contribute.

=== Archive ===
<div class="noresize">
{| class="prettytable"
! align="left" | 2026
! align="left" | 2025
! align="left" | 2024
! align="left" | 2023
! align="left" | 2022
! align="left" | 2021
! align="left" | 2020
! align="left" | 2019
! align="left" | 2018
! align="left" | 2017
! align="left" | 2016
! align="left" | 2015
! align="left" | 2014
! align="left" | 2013
! align="left" | 2012
! align="left" | 2011
! align="left" | 2010
! align="left" | 2009
|-
| valign="top" |
* [[FlightGear Newsletter January 2026|January]]
* [[FlightGear Newsletter February 2026|February]]
* [[FlightGear Newsletter March 2026|March]]
| valign="top" |
* [[FlightGear Newsletter January 2025|January]]
* [[FlightGear Newsletter February 2025|February]]
* [[FlightGear Newsletter March 2025|March]]
* [[FlightGear Newsletter April 2025|April]]
* [[FlightGear Newsletter May 2025|May]]
* [[FlightGear Newsletter June 2025|June]]
* [[FlightGear Newsletter July 2025|July]]
* [[FlightGear Newsletter August 2025|August]]
* [[FlightGear Newsletter September 2025|September]]
* [[FlightGear Newsletter October 2025|October]]
* [[FlightGear Newsletter November 2025|November]]
* [[FlightGear Newsletter December 2025|December]]
| valign="top" |
* [[FlightGear Newsletter January 2024|January]]
* [[FlightGear Newsletter February 2024|February]]
* [[FlightGear Newsletter March 2024|March]]
* [[FlightGear Newsletter April 2024|April]]
* [[FlightGear Newsletter May 2024|May]]
* [[FlightGear Newsletter June 2024|June]]
* [[FlightGear Newsletter July 2024|July]]
* [[FlightGear Newsletter August 2024|August]]
* [[FlightGear Newsletter September 2024|September]]
* [[FlightGear Newsletter October 2024|October]]
* [[FlightGear Newsletter November 2024|November]]
* [[FlightGear Newsletter December 2024|December]]
| valign="top" |
* [[FlightGear Newsletter January 2023|January]]
* [[FlightGear Newsletter February 2023|February]]
* [[FlightGear Newsletter March 2023|March]]
* [[FlightGear Newsletter April 2023|April]]
* [[FlightGear Newsletter May 2023|May]]
* [[FlightGear Newsletter June 2023|June]]
* [[FlightGear Newsletter July 2023|July]]
* [[FlightGear Newsletter August 2023|August]]
* [[FlightGear Newsletter September 2023|September]]
* [[FlightGear Newsletter October 2023|October]]
* [[FlightGear Newsletter November 2023|November]]
* [[FlightGear Newsletter December 2023|December]]
| valign="top" |
* [[FlightGear Newsletter January 2022|January]]
* [[FlightGear Newsletter February 2022|February]]
* [[FlightGear Newsletter March 2022|March]]
* [[FlightGear Newsletter April 2022|April]]
* [[FlightGear Newsletter May 2022|May]]
* June
* [[FlightGear Newsletter July 2022|July]]
* [[FlightGear Newsletter August 2022|August]]
* [[FlightGear Newsletter September 2022|September]]
* [[FlightGear Newsletter November 2022|November]]
* [[FlightGear Newsletter December 2022|December]]
| valign="top" |
* [[FlightGear Newsletter January 2021|January]]
* [[FlightGear Newsletter February 2021|February]]
* [[FlightGear Newsletter March 2021|March]]
* [[FlightGear Newsletter April 2021|April]]
* [[FlightGear Newsletter May 2021|May]]
* [[FlightGear Newsletter June 2021|June]]
* [[FlightGear Newsletter July 2021|July]]
* [[FlightGear Newsletter August 2021|August]]
* [[FlightGear Newsletter September 2021|September]]
* [[FlightGear Newsletter October 2021|October]]
* [[FlightGear Newsletter November 2021|November]]
* [[FlightGear Newsletter December 2021|December]]
| valign="top" |
* [[FlightGear Newsletter January 2020|January]]
* [[FlightGear Newsletter February 2020|February]]
* [[FlightGear Newsletter March 2020|March]]
* [[FlightGear Newsletter April 2020|April]]
* [[FlightGear Newsletter May 2020|May]]
* [[FlightGear Newsletter June 2020|June]]
* [[FlightGear Newsletter July 2020|July]]
* [[FlightGear Newsletter August 2020|August]]
* [[FlightGear Newsletter September 2020|September]]
* [[FlightGear Newsletter October 2020|October]]
* [[FlightGear Newsletter November 2020|November]]
* [[FlightGear Newsletter December 2020|December]]
| valign="top" |
* [[FlightGear Newsletter January 2019|January]]
* [[FlightGear Newsletter February 2019|February]]
* [[FlightGear Newsletter March 2019|March]]
* [[FlightGear Newsletter April 2019|April]]
* [[FlightGear Newsletter May 2019|May]]
* [[FlightGear Newsletter June 2019|June]]
* [[FlightGear Newsletter July 2019|July]]
* [[FlightGear Newsletter August 2019|August]]
* [[FlightGear Newsletter September 2019|September]]
* [[FlightGear Newsletter October 2019|October]]
* [[FlightGear Newsletter November 2019|November]]
| valign="top" |
* [[FlightGear Newsletter January 2018|January]]
* [[FlightGear Newsletter February 2018|February]]
* [[FlightGear Newsletter March 2018|March]]
* [[FlightGear Newsletter April 2018|April]]
* [[FlightGear Newsletter May 2018|May]]
* [[FlightGear Newsletter June 2018|June]]
* [[FlightGear Newsletter July 2018|July]]
* [[FlightGear Newsletter August 2018|August]]
* [[FlightGear Newsletter September 2018|September]]
* [[FlightGear Newsletter October 2018|October]]
* [[FlightGear Newsletter November 2018|November]]
* [[FlightGear Newsletter December 2018|December]]
| valign="top" |
* [[FlightGear Newsletter January 2017|January]]
* [[FlightGear Newsletter February 2017|February]]
* [[FlightGear Newsletter March 2017|March]]
* [[FlightGear Newsletter April 2017|April]]
* [[FlightGear Newsletter May 2017|May]]
* [[FlightGear Newsletter June 2017|June]]
* [[FlightGear Newsletter July 2017|July]]
* [[FlightGear Newsletter August 2017|August]]
* [[FlightGear Newsletter September 2017|September]]
* [[FlightGear Newsletter October 2017|October]]
* [[FlightGear Newsletter November 2017|November]]
* [[FlightGear Newsletter December 2017|December]]
| valign="top" |
* [[FlightGear Newsletter January 2016|January]]
* [[FlightGear Newsletter February 2016|February]]
* [[FlightGear Newsletter March 2016|March]]
* [[FlightGear Newsletter April 2016|April]]
* [[FlightGear Newsletter May 2016|May]]
* [[FlightGear Newsletter June 2016|June]]
* [[FlightGear Newsletter July 2016|July]]
* [[FlightGear Newsletter August 2016|August]]
* [[FlightGear Newsletter September 2016|September]]
* [[FlightGear Newsletter October 2016|October]]
* [[FlightGear Newsletter November 2016|November]]
* [[FlightGear Newsletter December 2016|December]]
| valign="top" |
* [[FlightGear Newsletter January 2015|January]]
* [[FlightGear Newsletter February 2015|February]]
* [[FlightGear Newsletter March 2015|March]]
* [[FlightGear Newsletter April 2015|April]]
* [[FlightGear Newsletter May 2015|May]]
* [[FlightGear Newsletter June 2015|June]]
* [[FlightGear Newsletter July 2015|July]]
* [[FlightGear Newsletter August 2015|August]]
* [[FlightGear Newsletter September 2015|September]]
* [[FlightGear Newsletter October 2015|October]]
* [[FlightGear Newsletter November 2015|November]]
* [[FlightGear Newsletter December 2015|December]]
| valign="top" |
* [[FlightGear Newsletter January 2014|January]]
* [[FlightGear Newsletter February 2014|February]]
* [[FlightGear Newsletter March 2014|March]]
* [[FlightGear Newsletter April 2014|April]]
* [[FlightGear Newsletter May 2014|May]]
* [[FlightGear Newsletter June 2014|June]]
* [[FlightGear Newsletter July 2014|July]]
* [[FlightGear Newsletter August 2014|August]]
* [[FlightGear Newsletter September 2014|September]]
* [[FlightGear Newsletter October 2014|October]]
* [[FlightGear Newsletter November 2014|November]]
* [[FlightGear Newsletter December 2014|December]]
| valign="top" |
* [[FlightGear Newsletter January 2013|January]]
* [[FlightGear Newsletter February 2013|February]]
* [[FlightGear Newsletter March 2013|March]]
* [[FlightGear Newsletter April 2013|April]]
* [[FlightGear Newsletter May 2013|May]]
* [[FlightGear Newsletter June 2013|June]]
* [[FlightGear Newsletter July 2013|July]]
* [[FlightGear Newsletter August 2013|August]]
* [[FlightGear Newsletter September 2013|September]]
* [[FlightGear Newsletter October 2013|October]]
* [[FlightGear Newsletter November 2013|November]]
* [[FlightGear Newsletter December 2013|December]]
| valign="top" |
* [[FlightGear Newsletter January 2012|January]]
* [[FlightGear Newsletter February 2012|February]]
* [[FlightGear Newsletter March 2012|March]]
* [[FlightGear Newsletter April 2012|April]]
* [[FlightGear Newsletter May 2012|May]]
* [[FlightGear Newsletter June 2012|June]]
* [[FlightGear Newsletter July 2012|July]]
* [[FlightGear Newsletter August 2012|August]]
* [[FlightGear Newsletter September 2012|September]]
* [[FlightGear Newsletter October 2012|October]]
* [[FlightGear Newsletter November 2012|November]]
* [[FlightGear Newsletter December 2012|December]]
| valign="top" |
* [[FlightGear Newsletter January 2011|January]]
* [[FlightGear Newsletter February 2011|February]]
* [[FlightGear Newsletter March 2011|March]]
* [[FlightGear Newsletter April 2011|April]]
* [[FlightGear Newsletter May 2011|May]]
* [[FlightGear Newsletter June 2011|June]]
* [[FlightGear Newsletter July 2011|July]]
* [[FlightGear Newsletter August 2011|August]]
* [[FlightGear Newsletter September 2011|September]]
* [[FlightGear Newsletter October 2011|October]]
* [[FlightGear Newsletter November 2011|November]]
* [[FlightGear Newsletter December 2011|December]]
| valign="top" |
* [[FlightGear Newsletter January 2010|January]]
* [[FlightGear Newsletter February 2010|February]]
* [[FlightGear Newsletter March 2010|March]]
* [[FlightGear Newsletter April 2010|April]]
* [[FlightGear Newsletter May 2010|May]]
* [[FlightGear Newsletter June 2010|June]]
* [[FlightGear Newsletter July 2010|July]]
* [[FlightGear Newsletter August 2010|August]]
* [[FlightGear Newsletter September 2010|September]]
* [[FlightGear Newsletter October 2010|October]]
* [[FlightGear Newsletter November 2010|November]]
* [[FlightGear Newsletter December 2010|December]]
| valign="top" |
* [[FlightGear Newsletter July 2009|July]]
* [[FlightGear Newsletter August 2009|August]]
* [[FlightGear Newsletter September 2009|September]]
* [[FlightGear Newsletter October 2009|October]]
* [[FlightGear Newsletter November 2009|November]]
* [[FlightGear Newsletter December 2009|December]]
|}
</div>

Some newsletter editions have been translated in other languages:
* [[File:De.gif|16px|link=:De:FlightGear Newsletter]] [[:De:FlightGear Newsletter|Deutsch]]
* [[File:Es.gif|16px|link=:Es:FlightGear Newsletter]] [[:Es:FlightGear Newsletter|Español]]
* [[File:Fr.gif|16px|link=:Fr:FlightGear Newsletter]] [[:Fr:FlightGear Newsletter|Français]]

=== You are invited to contribute! ===
We would like to emphasize that the monthly newsletter can not live without the contributions of FlightGear users and developers. The FlightGear Newsletter is a community-driven newsletter, which means that it is created and edited by people like ''you''. You don't need to be a long-time FlightGear user (or even a developer) to contribute to the newsletter.

In fact, helping write the monthly FlightGear newsletter is an excellent way for getting started contributing to the FlightGear community very quickly and very easily.

Even if you don't have to add anything yourself, just reviewing and improving additions by others is also highly appreciated, as are efforts to help translate newsletters or add screen shots (e.g. taken from the forum or mailing lists) to the newsletter. Screen shots can be uploaded at [[Special:Upload]].

Everyone with a wiki account (free to [[Special:UserLogin|register]]) can edit the newsletter and every contribution is welcome. So if you know about any FlightGear related projects such as for example updated scenery or aircraft, please do feel invited to add such news to the newsletter.

A simple template providing a basic structure for each upcoming newsletter can be taken from [[Talk:Next newsletter]]. This template can be copied/pasted into each new newsletter to help users getting started providing contents.

The draft for the upcoming newsletter can always be found at [[Next newsletter]].

If English is not your native language, please don't be concerned about contributing to the newsletter, you can always easily ask fellow FlightGear users to review or proof-read your changes. Also, one of the easiest ways to get started is simply copying/pasting text from forum or mailing list discussions, such as announcements (e.g., new aircraft, new scenery, etc.).

Another neat option to get started is adding links to FlightGear-related YouTube videos. For this, we have a dedicated section in each newsletter: "[[FlightGear Newsletter {{#time: F Y | last month }}#FlightGear on YouTube|FlightGear on YouTube]]."

If you want to embed a video, please see {{mediawiki|Extension:EmbedVideo#Usage}}

If you are looking for other ways to get involved, please see [[Volunteer]].

[[Category:FlightGear Newsletter| ]]
[[Category:Community|Newsletter]]
[[Category:Lists|Newsletter]]

[[de:FlightGear Newsletter]]
[[es:FlightGear Newsletter]]
[[fr:FlightGear Newsletter]]

Nasal FAQ

2026-03-26T13:29:51Z

PlayeRom: /* How to play sounds using Nasal script? */

{{Template:Nasal Navigation}}

This is meant to provide a place for '''frequently asked questions related to [[Nasal]]''' and related to using Nasal in [[FlightGear]], it's largely inspired by several related discussions on both, the FlightGear forums as well as the [[Mailing list|FlightGear mailing lists]].

== What are the major features of Nasal? ==
(Based on [http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg21428.html] and [http://plausible.org/nasal/])

=== Design ===
* Designed as an extension language, well suited for embedded applications
* Nasal can be instructed to run for only a certain number of "cycles" before returning. Later calls will automatically pick up the interpreter state where it left off.
* Small Interpreter, written in ANSI C, even smaller than lua
* Nasal's VM uses internally a stack machine model
* Nasal does not depend on any third party libraries other than the standard C library.
* Nasal provides optional bindings for libraries such as for example gtk, cairo, regex, readline, sqlite or unix
* Nasal does not depend on third party tools like (f)lex and yacc/bison.
* Nasal builds simply and easily, supports a reasonably simple extension API and cohabitates well with other code
* Nasal is threadsafe
* Nasal does not use a global interpreter lock (i.e. GIL in Python or Lua)
* Nasal is stackless for interpreted code
* Nasal has complete programmatic control over the runtime namespace for any piece of code, making "modules" a question of script coding and allowing a bunch of neat metaprogramming tricks
* Unicode Support
* Support for multiple execution contexts and subcontexts

=== Language ===
* Supported Types: Vectors, Hashes and Scalars
* Literal numbers can be decimal, exponential, or hex constants. All numbers are stored internally as IEEE double-precision values.
* Nasal supports exception handling as a first-class language feature, with built-in runtime-inspectable stack trace
* Standard OOP syntax (obj.field) using Hashes
* Nasal is a true functional language with recursion, lexical scoping, runtime binding, anonymous lambda expressions and true closures.
* Nasal has a true garbage collector.
* Nasal's data model matches what you are used to from perl, python and javascript.
* Nasal has syntax (e.g. based on concepts borrowed from ECMAScript/JavaScript) that makes sense in the modern world and to programmers exposed to other languages like Javascript.

== How to play sounds using Nasal script? ==
This works via property-fgcommands as per $FG_ROOT/Docs/README.commands:
<syntaxhighlight lang="nasal">
var sound = {
path : DIRECTORYPATH,
file : FILENAME,
volume: VOLUME,
queue : "instant", # Other optional choices, do not include queue for default, or user defined queue name
};

fgcommand("play-audio-sample", props.Node.new(sound));
</syntaxhighlight>

You'll want to adjust the capital variables with your own path/file name and volume, e.g. using a helper class :
<syntaxhighlight lang="nasal">
var Sound = {
# static
default_path: getprop("/sim/fg-root") ~ '/Sounds',

# constructor
new: func(filename, volume = 0.5, path = nil) {
var m = Props.Node.new({
path : path or default_path,
file : filename,
volume: volume,
});

return m;
},
};

fgcommand("play-audio-sample", Sound.new(filename: 'blade_vortex.wav', volume: 0.8));

# You could put your sound file in the same folder and load it from there,
# if you aren't using an existing sound:

var node = Sound.new(
filename: 'mySoundFile.wav',
volume: 0.8,
path: getprop("/sim/fg-root") ~ '/Aircraft/Foo/Sounds',
);

fgcommand("play-audio-sample", node);
</syntaxhighlight>

The same way one would do animations using Nasal:The current sound model is property-driven. You can create a new sound event (see the *-sound.xml files under Aircraft for examples) and drive it from a given set of properties. You can then set those properties from Nasal.

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

If your sounds are aircraft-specific, then the mechanism of putting it into the -sound.xml file is probably exactly what you want.
Things like playing sounds from the UI are more problematic from the current interface.

Start with a single beep.wav with an XML definition like:

<sim>
...
<fx>
...
<beep>
<name>engstart</name>
<path>Sounds/beep.wav</path>
<property>/tmp/somewhere/beep</property>
</beep>

Now you can trigger the beep by toggling the property from false to true. With a little work with settimer(), you can get it to beep with different patterns and frequencies, etc...

For additional information, you'll want to check out [[$FG_ROOT]]/Docs/README.xmlsound

=== Using cmdarg() ===
cmdarg() returns the listened-to property as props.Node object, so you can use it with all its methods (see [[$FG_ROOT]]/Nasal/props.nas),
for example:

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

[[Category:Nasal]]

Nasal FAQ

2026-03-26T13:29:17Z

PlayeRom: /* How to play sounds using Nasal script? */

Nasal library

2026-01-16T21:10:17Z

PlayeRom: /* has_member() */

{{Nasal Navigation|nocat=1}}
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:
* {{flightgear file|src/Scripting}}
* {{simgear file|simgear/nasal}}

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]].

{{tip|Copy & paste the examples into your [[Nasal Console]] and execute them to see what they do.|width=70%}}

== Core library functions ==
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:
* http://plausible.org/nasal/lib.html ([http://web.archive.org/web/20101010094553/http://plausible.org/nasal/lib.html archive])
* {{simgear file|simgear/nasal/lib.c}} ([http://sourceforge.net/p/flightgear/simgear/ci/next/log/?path=/simgear/nasal/lib.c history])

=== append() ===
{{Nasal doc
|syntax = append(vector, element[, element[, ...]]);
|source = {{simgear file|simgear/nasal/lib.c|l=45|t=Source}}
|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.
|param1 = vector
|param1text = The vector to which the arguments will be appended.
|param2 = element
|param2text = An element to be added to the vector.
|example1 =
var vector = [1, 2, 3]; # Initialize the vector
append(vector, 4); # Append the number 4 to the end of the vector
debug.dump(vector); # Print the contents of the vector
|example2 =
var vector = [1, 2, 3]; # Initialize the vector
append(vector, 4, 5, 6); # Append the numbers 4, 5, and 6 to the end of the vector
debug.dump(vector); # Print the contents of the vector
}}

=== bind() ===
{{Nasal doc
|syntax = bind(function, locals[, outer_scope]);
|source = {{simgear file|simgear/nasal/lib.c|l=638|t=Source}}
|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.
|param1 = function
|param1text = Function to evaluate.
|param2 = locals
|param2text = Hash containing values that will become the namespace (first closure) for the function.
|param3 = outer_scope
|param3text = Optional function which is bound to the next closure. This can be bound to yet another, making a linked list.
|example1 = # This is a namespace/hash with a single member, named "key," which is initialized to 12
var Namespace = {
key: 12
};

# This is different namespace/hash containing a function
# dividing a variable "key" (which is unavailable/nil in this namespace) by 2
var AnotherNamespace = {
ret: func {
key /= 2;
}
};

# To see that key is not available, try to call AnotherNamespace.ret() first
call(AnotherNamespace.ret, [], nil, nil, var errors = []);
if(size(errors)){
print("Key could not be divided/resolved!");
debug.printerror(errors);
}

# Associate the AnotherNamespace.ret() function with the first namespace
# so that "key" is now available
var function = bind(AnotherNamespace.ret, Namespace);

# Invoke the new function
function();

# Print out the value of Namespace.key
# It was changed to 12 from 6 by AnotherNamespace.ret()
print(Namespace.key);
}}

=== call() ===
{{Nasal doc
|syntax = call(func[, args[, me[, locals[, error]]]);
|source = {{simgear file|simgear/nasal/lib.c|l=376|t=Source}}
|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.
|param1 = func
|param1text = Function to execute.
|param2 = args
|param2text = Vector containing arguments to give to the called function.
|param3 = me
|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).
|param4 = locals
|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.
|param5 = error
|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}}.
|example1 =
# prints "Called from call()"
call(func {
print("Called from call()");
});
|example2 =
# prints "a = 1 : b = 2
call(func(a, b){
print("a = ", a, " : b = ", b);
},
[1, 2]
);
|example3 =
var Hash = {
new: func {
var m = { parents: [Hash] };

m.el1 = "string1";
m.el2 = "string2";

return m;
}
};

# prints "me.el1 = string1", then "me.el2 = string2" on the next line
call(func(a, b){
print("me.el", a, " = ", me["el" ~ a]);
print("me.el", b, " = ", me["el" ~ b]);
},
[1, 2],
Hash.new()
);
|example4 =
# prints the value of math.pi
call(func {
print(pi);
}, nil, nil,
math
);
|example5 =
call(func {
print(math.ip); # math.ip doesn't exist
}, nil, nil, nil,
var errs = []
);
debug.printerror(errs); # The error is caught and printed using debug.printerror()
}}

=== caller() ===
{{Nasal doc
|syntax = caller([level]);
|source = {{simgear file|simgear/nasal/lib.c|l=540|t=Source}}
|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 '''[0]''' a hash of local variables, '''[1]''' the function object, '''[2]''' the full source file name (incl. path) and '''[3]''' the line number.
|param1 = level
|param1text = Optional integer specifying the stack level to return a result from. Defaults to 1 (i.e. the caller of the currently executing function).
|example1 =
var myFunction = func(a, b) {
debug.dump(caller(0)[0]); # prints a hash of local variables, including arguments a and b
return 2 * 2;
};

print("2 x 2 = ", myFunction(2, 2));
|example2 =
var get_arg_value = func() {
print("Argument to myFunc = ", caller(1)[0]['a']); # print the value of myFunc's single argument, using caller()
};

var myFunc = func(a) {
get_arg_value();
};

myFunc(3);
|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: true, zindex: nil }</code>.
|example3 =
var MapStructure_selfTest = func() {
var temp = {};
temp.dlg = canvas.Window.new([600, 400], "dialog");
temp.canvas = temp.dlg.createCanvas().setColorBackground(1, 1, 1, 0.5);
temp.root = temp.canvas.createGroup();

var testMap = temp.root.createChild("map");
testMap.setController("Aircraft position");
testMap.setRange(25); # TODO: implement zooming/panning via mouse/wheel here, for lack of buttons :-/
testMap.setTranslation(
temp.canvas.get("view[0]") / 2,
temp.canvas.get("view[1]") / 2,
);

var r = func(name, vis = true, zindex = nil) {
return caller(0)[0];
}

# TODO: we'll need some z-indexing here, right now it's just random
# TODO: use foreach/keys to show all layers in this case by traversing SymbolLayer.registry directly ?
# maybe encode implicit z-indexing for each lcontroller ctor call ? - i.e. preferred above/below order ?
var types = [
r('TFC', false),
r('APT'),
r('DME'),
r('VOR'),
r('NDB'),
r('FIX', false),
r('RTE'),
r('WPT'),
r('FLT'),
r('WXR'),
r('APS'),
];

foreach (var type; types) {
testMap.addLayer(
factory: canvas.SymbolLayer,
type_arg: type.name,
visible: type.vis,
priority: type.zindex,
);
}
}; # MapStructure_selfTest
}}

=== chr() ===
{{Nasal doc
|syntax = chr(code);
|source = {{simgear file|simgear/nasal/lib.c|l=240|t=Source}}
|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.}}
{{{!}} class="wikitable"
! Code !! Name !! Equivalent to
{{!-}}
{{!}} 10 {{!!}} {{Wikipedia|Newline}} {{!!}} <code>\n</code>
{{!-}}
{{!}} 9 {{!!}} {{Wikipedia|Tab key#Tab characters|Horizontal tab}} {{!!}} <code>\t</code>
{{!-}}
{{!}} 13 {{!!}} {{Wikipedia|Carriage return}} {{!!}} <code>\r</code>
{{!}}}
|param1 = code
|param1text = Integer character code for the desired glyph.
|example1 = print("Code 65 = ", chr(65)); # prints "Code 65 = A"
|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.
|example2 =
for(var i = 0; i <= 255; i += 1){
print("Code ", i, " = >", chr(i), "<");
}
}}

=== closure() ===
{{Nasal doc
|syntax = closure(func[, level]);
|source = {{simgear file|simgear/nasal/lib.c|l=557|t=Source}}
|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'''.
|param1 = func
|param1text = Function to evaluate.
|param2 = level
|param2text = Optional integer specifying the scope level. Defaults to 0 (the namespace of '''func''').
|example1 =
var get_math_e = func {
return e; # return the value of math.e
}

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
debug.dump(closure(myFunction)); # print the hash of the namespace "get_math_e"

print(myFunction());
}}

=== cmp() ===
{{Nasal doc
|syntax = cmp(a, b);
|source = {{simgear file|simgear/nasal/lib.c|l=169|t=Source}}
|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'''.
|param1 = a
|param1text = First string argument for comparison.
|param2 = b
|param2text = Second string argument for comparison.
|example1 = print(cmp("1", "two")); # prints -1
|example2 = print(cmp("string", "string")); # prints 0
|example3 = print(cmp("one", "2")); # prints 1
|example4 = print(cmp("string1", "string2")); # prints -1
}}

=== compile() ===
{{Nasal doc
|syntax = compile(code[, filename]);
|source = {{simgear file|simgear/nasal/lib.c|l=349|t=Source}}
|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'''.
|param1 = code
|param1text = String containing Nasal code to be compiled.
|param2 = filename
|param2text = Optional string used for error messages/logging. Defaults to <code><compile></code>
|example1 =
var myCode = 'print("hello");';
var helloFunc = compile(myCode, "myCode");
helloFunc();
|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>.
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<PropertyList>

<nasal><![CDATA[
print("You have FlightGear v", getprop("/sim/version/flightgear"));
]]></nasal>

</PropertyList>
</syntaxhighlight>
Now, start FlightGear and execute this code in the [[Nasal Console]].
|example2 =
# Build the path
var FGRoot = getprop("/sim/fg-root");
var filename = "/gui/dialogs/test.xml";
var path = FGRoot ~ filename;

var blob = io.read_properties(path);
var script = blob.getValues().nasal; # Get the nasal string

# Compile the script. We're passing the filename here for better runtime diagnostics
var code = call(func {
compile(script, filename);
}, nil, nil, var compilation_errors = []);

if(size(compilation_errors)){
die("Error compiling code in: " ~ filename);
}

# Invoke the compiled script, equivalent to code();
# We're using call() here to detect errors:
call(code, [], nil, nil, var runtime_errors = []);

if(size(runtime_errors)){
die("Error calling code compiled loaded from: " ~ filename);
}
|example3text = The <code>compile()</code> function also allows you to parse a JSON string into a hash. Simplest example:
|example3 =
var jsonFunc = compile('{"version":"1.2.0","author":{"name":"John"} }');
var json = jsonFunc(); # return hash
logprint(LOG_ALERT, json["version"]); # print "1.2.0"
logprint(LOG_ALERT, json["author"]["name"]); # print "John"
}}

=== contains() ===
{{Nasal doc
|syntax = contains(hash, key);
|source = {{simgear file|simgear/nasal/lib.c|l=249|t=Source}}
|text = Returns 1 (True) if the hash contains the specified key, or 0 (False) if not.
|param1 = hash
|param1text = The hash to search in.
|param2 = key
|param2text = The scalar to be searched for, contained as a key in the hash.
|example1 =
# Initialize a hash
var hash = {
element: "value"
};
print(contains(hash, "element") ? "Yes" : "No"); # This will print "Yes"
print(contains(hash, "element2") ? "Yes" : "No"); # This will print "No"
}}

===contains()===
{{Requires commit|desc=Vector support|details=see {{Merge-request|project=fgdata|id=305}}|commit=ee39abbd3b70c9b6d5e3a1c4ccedddaac1a92b11|repo=Simgear}}
{{Nasal doc
|syntax = contains(vector, item);
|source = {{simgear file|simgear/nasal/lib.c|l=249|t=Source}}
|text = Returns 1 (True) if the vector contains the specified item, or 0 (False) if not.
|param1 = vector
|param1text = The vector to search in.
|param2 = item
|param2text = The object to be searched for in the vector.
|example1 =
# Initialize a vector
var vec = ["element", "foo"];
print(contains(vec, "element") ? "Yes" : "No"); # This will print "Yes"
print(contains(vec, "element2") ? "Yes" : "No"); # This will print "No"
}}

===delete() ===
{{Nasal doc
|syntax = delete(hash, key);
|source = {{simgear file|simgear/nasal/lib.c|l=118|t=Source}}
|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.
|param1 = hash
|param1text = The hash from which to delete the key.
|param2 = key
|param2text = The scalar to be deleted, contained as a key in the hash.
|example1 =
# Initialize the hash
var hash = {
element1: "value1",
element2: "value2"
};
delete(hash, "element1"); # Delete element1
debug.dump(hash); # prints the hash, which is now minus element1
}}

===die()===
{{Nasal doc
|syntax = die(error);
|source = {{simgear file|simgear/nasal/lib.c|l=417|t=Source}}
|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()}}.
|param1 = error
|param1text = String describing the error.
:{{inote|This parameter is technically optional, but it is highly recommended to use it.}}
|example1 =
print("Will print");
die("Don't go any further!");
print("Won't print"); # Will not be printed because die() stops the process
}}

=== find()===
{{Nasal doc
|syntax = find(needle, haystack);
|source = {{simgear file|simgear/nasal/lib.c|l=586|t=Source}}
|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.
|param1 = needle
|param1text = String to search for.
|param2 = haystack
|param2text = String to search in.
|example1 = print(find("c", "abcdef")); # prints 2
|example2 = print(find("x", "abcdef")); # prints -1
|example3 = print(find("cd", "abcdef")); # prints 2
}}

===ghosttype()===
{{Nasal doc
|syntax = ghosttype(ghost);
|source = {{simgear file|simgear/nasal/lib.c|l=336|t=Source}}
|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.
|param1 = ghost
|param1text = Ghost to return a description for.
|example1 = print(ghosttype(airportinfo())); # prints "airport"
}}

===id()===
{{Nasal doc
|syntax = id(object);
|source = {{simgear file|simgear/nasal/lib.c|l=706|t=Source}}
|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.
|param1 = object
|param1text = Can be either of a string, a vector, a hash, a code, a function, or a ghost.
|example1 = print(id("A")); # prints "str:000000001624A590"
}}

===int() ===
{{Nasal doc
|syntax = int(number);
|source = {{simgear file|simgear/nasal/lib.c|l=125|t=Source}}
|text = Returns the integer part of the numeric value of the single argument, or <code>'''nil'''</code> if none exists.
|param1 = number
|param1text = Number or string with just a number in it to return an integer from.
|example1 = print(int(23)); # prints "23"
|example2 = print(int(23.123)); # prints "23"
|example3 = debug.dump(int("string")); # prints "nil"
}}

===keys()===
{{Nasal doc
|syntax = keys(hash);
|source = {{simgear file|simgear/nasal/lib.c|l=36|t=Source}}
|text = Returns a vector containing the list of keys found in the single hash argument.
|param1 = hash
|param1text = The hash to return the keys from.
|example1 =
# Initialize a hash
var hash = {
element1: "value",
element2: "value"
};
debug.dump(keys(hash)); # print the vector
}}

===left()===
{{Nasal doc
|syntax = left(string, length);
|source = {{simgear file|simgear/nasal/lib.c|l=214|t=Source}}
|version = 2.12
|commit = {{simgear commit|bd7163|t=commit}}
|text = Returns a substring of '''string''', starting from the left.
|param1 = string
|param1text = String to return part of.
|param2 = length
|param2text = Integer specifying the length of the substring to return.
|example1 = print(left("string", 2)); # prints "st"
}}

=== num()===
{{Nasal doc
|syntax = num(number);
|source = {{simgear file|simgear/nasal/lib.c|l=149|t=Source}}
|text = Returns the numerical value of the single string argument, or <code>'''nil'''</code> if none exists.
|param1 = number
|param1text = String with just a number in it to return a number from.
|example1 = print(num("23")); # prints "23"
|example2 = print(num("23.123")); # prints "23.123"
|example3 = debug.dump(num("string")); # prints "nil"
}}

===pop()===
{{Nasal doc
|syntax = pop(vector);
|source = {{simgear file|simgear/nasal/lib.c|l=85|t=Source}}
|text = Removes and returns the last element of the single vector argument, or <code>'''nil'''</code> if the vector is empty.
|param1 = vector
|param1text = Vector to remove an element from.
|example1 =
var vector = [1, 2, 3];
pop(vector);
debug.dump(vector); # prints "[1, 2]"
|example2 =
var vector = [1, 2, 3];
debug.dump(pop(vector)); # prints "3"
|example3 =
var vector = [];
debug.dump(pop(vector)); # prints "nil"
}}

=== range() ===
{{Nasal doc
|syntax = range([start, ]stop[, step]);
|source = {{simgear file|simgear/nasal/lib.c|l=756|t=Source}}
|text = Creates a vector of numbers starting from <code>start</code> (default 0) up to but not including <code>stop</code>, incremented by <code>step</code> (default 1). Note: To specify <code>step</code>, you must also provide <code>start</code>; otherwise the second argument is interpreted as <code>stop</code>.
|param1 = start
|param1text = Optional. The starting number of the sequence. Defaults to 0 if omitted. Required if you want to specify <code>step</code>.
|param2 = stop
|param2text = Required. The number at which to stop the sequence (not included).
|param3 = step
|param3text = Optional. The increment between each number in the sequence. Defaults to 1. Only valid if <code>start</code> is also specified.
|example1 =
var vec = range(5); # Creates a vector [0, 1, 2, 3, 4]
var vec = range(2, 5); # Creates a vector [2, 3, 4]
var vec = range(0, 10, 2); # Creates a vector [0, 2, 4, 6, 8]
var vec = range(0, 0); # Creates an empty vector []
var vec = range(0, 1); # Creates a vector [0]
}}

=== remove() ===
{{Nasal doc
|syntax = remove(vector, value);
|source = {{simgear file|simgear/nasal/lib.c|l=53|t=Source}}
|text = Removes all elements equal to the given value from a vector and returns the modified vector.
|param1 = vector
|param1text = The vector from which elements are to be removed.
|param2 = value
|param2text = A value to remove from the vector.
|example1 =
var vector = [1, 2, 3]; # Initialize the vector.
remove(vector, 2); # Remove the value 2 from the vector.
debug.dump(vector); # Print the contents of the vector: "[1, 3]".
|example2 =
var vector = ["text", "text", "text"]; # Initialize the vector.
remove(vector, "text"); # Remove the value "text" from the vector.
debug.dump(vector); # Print the contents of the vector: "[]".
}}

=== removeat() ===
{{Nasal doc
|syntax = removeat(vector, index);
|source = {{simgear file|simgear/nasal/lib.c|l=72|t=Source}}
|text = Removes the element at the specified index from the vector and returns it.
|param1 = vector
|param1text = The vector from which the element will be removed.
|param2 = index
|param2text = Index of the item to be deleted.
|example1 =
var vector = [1, 2, 3]; # Initialize the vector.
removeat(vector, 0); # Remove the index 0 from the vector.
debug.dump(vector); # Print the contents of the vector: "[2, 3]".
}}

===right()===
{{Nasal doc
|syntax = right(string, length);
|source = {{simgear file|simgear/nasal/lib.c|l=226|t=Source}}
|version = 2.12
|commit = {{simgear commit|bd7163|t=commit}}
|text = Returns a substring of '''string''', starting from the right.
|param1 = string
|param1text = String to return part of.
|param2 = length
|param2text = Integer specifying the length of the substring to return.
|example1 = print(right("string", 2)); # prints "ng"
}}

=== setsize()===
{{Nasal doc
|syntax = setsize(vector, size);
|source = {{simgear file|simgear/nasal/lib.c|l=91|t=Source}}
|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.
|param1 = vector
|param1text = The vector to be operated on.
|param2 = size
|param2text = The desired size of the vector in number of entries.
|example1 =
var vector = [1, 2, 3]; # Initialize a vector
setsize(vector, 4);
debug.dump(vector); # print the vector "[1, 2, 3, nil]"
|example2 =
var vector = [1, 2, 3]; # Initialize a vector
setsize(vector, 2);
debug.dump(vector); # print the vector "[1, 2]"
}}

===size()===
{{Nasal doc
|syntax = size(object);
|source = {{simgear file|simgear/nasal/lib.c|l=26|t=Source}}
|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>.
|param1 = object
|param1text = Object to find the size of. Must be a string, a vector or a hash.
|example1 =
var string = "string";
print(size(string)); # prints "6"
|example2 =
var vector = [1, 2, 3];
print(size(vector)); # prints "3"
|example3 =
var hash = {
element1: "value1",
element2: "value2",
element3: "value3"
};
print(size(hash)); # prints "3"
}}

=== sort()===
{{Nasal doc
|syntax = sort(vector, function);
|source = {{simgear file|simgear/nasal/lib.c|l=678|t=Source}}
|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.
|param1 = vector
|param1text = Input vector to sort.
|param2 = function
|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.
{{{!}} class="wikitable"
! Return value !! Meaning
{{!-}}
{{!}} less than 0 {{!!}} first argument should go before second argument
{{!-}}
{{!}} 0 {{!!}} first argument equals second argument
{{!-}}
{{!}} greater than 0 {{!!}} first argument should go after second argument
{{!}}}

|example1text = This example sorts elements from smallest to greatest.
|example1 =
var sort_rules = func(a, b) {
if (a < b) {
return -1; # A should before b in the returned vector
} elsif (a == b) {
return 0; # A is equivalent to b
} else {
return 1; # A should after b in the returned vector
}
}
debug.dump(sort([3, 2, 5, 6, 4, 1], sort_rules)); # prints "[1, 2, 3, 4, 5, 6]"
|example2text = This example sorts elements from greatest to smallest.
|example2 =
# Outputs the elements in reverse order (greatest to smallest)
var sort_rules = func(a, b) {
if (a < b) {
return 1; # -1 in the above example
} elsif (a == b) {
return 0;
} else {
return -1; # 1 in the above example
}
}
debug.dump(sort([3, 2, 5, 6, 4, 1], sort_rules)); # prints "[6, 5, 4, 3, 2, 1]"
|example3text = This example sorts a vector of strings (runways for example) from smallest to greatest.
|example3 =
var runways = ["09R", "27R", "26L", "09L", "15"];
var rwy = sort(runways, func(a, b) cmp(a, b));
debug.dump(rwy); # prints ['09L', '09R', '15', '26L', '27R']
}}

=== split()===
{{Nasal doc
|syntax = split(delimiter, string);
|source = {{simgear file|simgear/nasal/lib.c|l=596|t=Source}}
|text = Splits the input string into a vector of substrings bounded by occurrences of the delimiter substring. See [[Nasal_library/string#string.join(sep,list)|string.join()]].
|param1 = delimiter
|param1text = String that will split the substrings in the returned vector.
|param2 = string
|param2text = String to split up.
|example1 = debug.dump(split("cd", "abcdef")); # prints "['ab', 'ef']"
|example2 = debug.dump(split(".", "3.2.0")); # prints "[3, 2, 0]"
|example3 = debug.dump(split("/", "path/to/file")); # prints "['path', 'to', 'file']"
}}

===sprintf()===
{{Nasal doc
|syntax = <nowiki>sprintf(format[, arg[, arg, [...]]]);</nowiki>
|source = {{simgear file|simgear/nasal/lib.c|l=491|t=Source}}
|text = Creates and returns a string formatted using ANSI C {{func link|vsnprintf()|link=http://en.cppreference.com/w/c/io/vfprintf}} <ref>
{{Cite web
|url = http://sourceforge.net/p/flightgear/simgear/ci/next/tree/simgear/nasal/lib.c#l308
|title = fgdata/simgear/simgear/nasal/lib.c, line 308
|accessdate = October 2015
}}
</ref>. Below is a table of supported format specifiers.
{{{!}} class="wikitable" width="75%"
{{!}}+ %[flags][width][.precision]specifier
! colspan="2" {{!}} Flags
{{!-}}
! Flag !! Output
{{!-}}
{{!}} <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.
{{!-}}
{{!}} ''space'' {{!!}} Prefixes non-signed numbers with a space.
{{!-}}
{{!}} <code>-</code> {{!!}} Left-align the output of this placeholder (the default is to right-align the output) when the width option is specified.
{{!-}}
{{!}} <code>0</code> {{!!}} Use 0 instead of spaces to pad a field when the width option is specified.
{{!-}}
{{!}} <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.
{{!-}}
! colspan="2" {{!}} Width
{{!-}}
{{!}} 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.
{{!-}}
! colspan="2" {{!}} Precision
{{!-}}
{{!}} colspan="2" {{!}} Integer preceded by a dot specifying the number of decimal places to be written.
{{!-}}
! colspan="2" {{!}} Specifiers
{{!-}}
! Specifier !! Output
{{!-}}
{{!}} <code>d</code>, <code>i</code> {{!!}} Signed decimal number.
{{!-}}
{{!}} <code>s</code> {{!!}} A string
{{!-}}
{{!}} <code>%</code> {{!!}} Percent (%) character.
{{!-}}
{{!}} <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.
{{!-}}
{{!}} <code>o</code> {{!!}} Unsigned integer as an octal number.
{{!-}}
{{!}} <code>u</code> {{!!}} Unsigned decimal integer.
{{!-}}
{{!}} <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.
{{!-}}
{{!}} <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.
{{!-}}
{{!}} <code>f</code> {{!!}} Floating-point number, in fixed decimal notation, by default with 6 decimal places.
{{!-}}
{{!}} <code>F</code> {{!!}} Appears to be available<ref>
{{Cite web
|url = http://sourceforge.net/p/flightgear/simgear/ci/next/tree/simgear/nasal/lib.c#l389
|title = fgdata/simgear/simgear/nasal/lib.c, line 389
|accessdate = October 2015
}}
</ref>, but doesn't work.
{{!-}}
{{!}} <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.
{{!}}}

|param1 = format
|param1text = String specifying the format. Can be used with or without a format specifiers. See below for examples.
|param2 = arg
|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.

|example1 = print(sprintf("%i", 54)); # prints "54"
|example2 = print(sprintf("Pi = %+.10f", math.pi)); # prints "Pi = +3.1415926536"
|example3 =
print(sprintf("%6d", 23)); # prints " 23"
print(sprintf("%06d", 23)); # prints "000023"
|example4 =
var FGVer = getprop("/sim/version/flightgear");
print(sprintf("You have FlightGear v%s", FGVer)); # prints "You have FlightGear v<your version>"
|example5 =
print(sprintf("Hexadecimal 100000 = %X", 100000)); # prints "Hexadecimal 100000 = 186A0"
print(sprintf("Hexadecimal 100000 = %x", 100000)); # prints "Hexadecimal 100000 = 186a0"
|example6 = print(sprintf("Code 65 is %c", 65)); # prints "Code 65 is A"
|example7 =
print(sprintf("%e", 54)); # prints "5.400000e+001"
print(sprintf("%E", 54)); # prints "5.400000E+001"
|example8 = print(sprintf("%o", 54)); # prints "66"
|example9 = print(sprintf("50%% of 100 is %i", 100 / 2)); # prints "50% of 100 is 50"
|example10 =
print(sprintf("%.2f", 1.4)); # prints "1.40"
print(sprintf("%.1f", 1.4)); # prints "1.4"
print(sprintf("% 4.1f", 1.4)); # prints " 1.4"
print(sprintf("%04.1f", 1.4)); # prints "01.4"
print(sprintf("% 6.1f", 1.4)); # prints " 1.4"
print(sprintf("%06.1f", 1.4)); # prints "0001.4"
}}

===str()===
{{Nasal doc
|syntax = str(value);
|source = {{simgear file|simgear/nasal/lib.c|l=186|t=Source}}
|text = Convert given value (scalar) to string. If <code>value</code> is a number, it will be converted to a string. If <code>value</code> is a string, the same string will be returned. If <code>value</code> is not a scalar (hash, vector, nil), <code>nil</code> will be returned.
|param1 = value
|param1text = The value to convert to string.
|example1 =
var result = str(true); # result is a string "1"
var result = str(false); # result is a string "0"
var result = str(12); # result is a string "12"
var result = str(12.5); # result is a string "12.5"
var result = str(-12.5); # result is a string "-12.5"
var result = str("12.5"); # result is a string "12.5"
var result = str([1, 2]); # result is a nil
var result = str({ x: 0 }); # result is a nil
var result = str(nil); # result is a nil
}}

===streq()===
{{Nasal doc
|syntax = streq(a, b);
|source = {{simgear file|simgear/nasal/lib.c|l=164|t=Source}}
|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.}}
|param1 = a
|param1text = First argument for testing equality.
|param2 = b
|param2text = Second argument for testing equality.
|example1 = print(streq("0", "0")); # prints "1" (True)
|example2 =
print(0 == 0.0); # prints "1" (True)
print(streq("0", "0.0")); # prints "0" (False)
}}

===substr()===
{{Nasal doc
|syntax = substr(string, start [, length]);
|source = {{simgear file|simgear/nasal/lib.c|l=194|t=Source}}
|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).
|param1 = string
|param1text = String to return a substring from.
|param2 = start
|param2text = Integer specifying the start of a substring. Negative values specify a position from the end of the string.
|param3 = length
|param3text = Optional argument specifying the length of the substring. Defaults to the end of the string.
|example1 = print(substr("abcde", 1, 3)); # prints "bcd"
|example2 = print(substr("abcde", 1)); # prints "bcde"
|example3 = print(substr("abcde", 2, 1)); # prints "c"
|example4 = print(substr("abcde", -2)); # prints "de"
|example5 = print(substr("abcde", -3, 2)); # prints "cd"
}}

===subvec()===
{{Nasal doc
|syntax = subvec(vector, start[, length]);
|source = {{simgear file|simgear/nasal/lib.c|l=98|t=Source}}
|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).
|param1 = vector
|param1text = The vector to take the sub-vector from.
|param2 = start
|param2text = The starting point of the sub-vector within the given vector.
|param3 = length
|param3text = Optional argument specifying the length of the sub-vector, from the starting point.
'''Notes:'''
* Omitting the ''vector'' and ''start'' arguments is not an error (possibly it should be) but the return value is ''nil''.
* A negative ''start'' argument ''is'' an error. This seems wrong. Perhaps the language designer could comment.
* A value of ''start'' greater than ''size(vector)'' causes an error. A value equal to ''size(vector)'' returns an empty vector.
* 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.
|example1 =
var vector = [1, 2, 3];
debug.dump(subvec(vector, 0)); # prints "[1, 2, 3]"
|example2 =
var vector = [1, 2, 3];
debug.dump(subvec(vector, 1)); # prints "[2, 3]"
|example3 =
var vector = [1, 2, 3];
debug.dump(subvec(vector, 1, 1)); # prints "[2]"
}}

=== typeof()===
{{Nasal doc
|syntax = typeof(object);
|source = {{simgear file|simgear/nasal/lib.c|l=287|t=Source}}
|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.
|param1 = object
|param1text = Object to return the type of.
|example1 =
var object = nil;
print(typeof(object)); # prints "nil"
|example2 =
var object = "Hello world!";
print(typeof(object)); # prints "scalar"
|example3 =
var object = math.pi;
print(typeof(object)); # prints "scalar"
|example4 =
var object = [1, 2, 3];
print(typeof(object)); # prints "vector"
|example5 =
var object = {};
print(typeof(object)); # prints "hash"
|example6 =
var object = func {};
print(typeof(object)); # prints "func"
|example7 =
var object = airportinfo();
print(typeof(object)); # prints "ghost"
}}



==Extension functions==
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:
*{{flightgear file|src/Scripting/NasalPositioned.cxx}}
*{{flightgear file|src/Scripting/NasalSys.cxx}}
*{{fgdata file|Nasal/globals.nas}}

===abort()===
{{Nasal doc
|syntax = abort();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=565|t=Source}}
|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).
|example1text = This example will immediately stop FlightGear with an error, such as "FlightGear has stopped working."
|example1 = abort();
|example2text = For exiting FlightGear in a better way, please use the following code:
|example2 = fgcommand("exit");
}}

=== abs() ===
{{Nasal doc
|syntax = abs(number);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = This simple function returns the {{wikipedia|absolute value|noicon=1}} of the provided number.
|param1 = number
|param1text = This argument is required and should be a number.
|example1 = print(abs(1)); # prints "1"
|example2 = print(abs(-1)); # prints "1"
}}

===aircraftToCart() ===
This new function in FG 2017.2.1 takes coordinates in aircraft structural coordinate system, and translate them into geocentric coordinates.
Example for (5,6,7):
<syntaxhighlight lang="nasal">
var pos = aircraftToCart({x: -5, y: 6, z: -7});
var coord = geo.Coord.new();
coord.set_xyz(pos.x, pos.y, pos.z);
</syntaxhighlight>
Notice: x and z is inverted sign on purpose.
if you want lat. lon, alt from that, just call: (degrees and meters)

<syntaxhighlight lang="nasal">
coord.lat()
coord.lon()
coord.alt()
</syntaxhighlight>

===addcommand() ===
{{Nasal doc
|syntax = addcommand(name, code);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=659|t=Source}}
|version = 2.12
|commit = {{flightgear commit|7b663c|t=commit}}
|text = {{see also|Howto:Add new fgcommands to FlightGear}}

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.
|param1 = name
|param1text = This will become the name of the new fgcommand. Must be a string.
|param2 = code
|param2text = The code that will be executed when the fgcommand is run. Must be a function.
|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.
|example1 = addcommand("myFGCmd", func(node) {
print("fgcommand 'myFGCmd' has been run.");
props.dump( node );
});
fgcommand("myFGCmd", props.Node.new({foo:1, bar:2}) );
|example2text = This example demonstrates how parameters are defined in a new fgcommand.
|example2 = addcommand("myFGCmd", func(node){
print(node.getNode("number").getValue()); # prints the value of "number," which is 12
});
fgcommand("myFGCmd", props.Node.new({"number": 12}));
}}

===airportinfo()===
{{Nasal doc
|syntax = airportinfo();
airportinfo(type);
airportinfo(id);
airportinfo(lat, lon[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1024|t=Source}}
|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:
* '''parents''': A vector containing a hash of various functions to access information about the runway. These functions are:
** '''findBestRunwayForPos()''' return runway as ghost by given geo position, e.g. <code>var rwy = airportinfo().findBestRunwayForPos(geo.aircraft_position());</code>.
** '''runway()''' return runway as ghost by runway ID, e.g. <code>var rwy = airportinfo().runway("18R");</code>.
** '''runwaysWithoutReciprocals()''' return vector of runways as ghost.
** '''helipad()''' return helipad as ghost by helipad ID, e.g. <code>var heli = airportinfo().helipad("H19");</code>.
** '''tower()''' return hash with <code>lat</code>, <code>lon</code>, <code>elevation</code> fields.
** '''comms()''' return vector of hashes, each hash with <code>frequency</code> and <code>ident</code> fields.
** '''sids()''' return vector of strings with SID IDs.
** '''stars()''' return vector of strings with STAR IDs.
** '''getApproachList()''' return vector of string with approaches.
** '''parking()''' return vector of hashes, each hash with <code>lat</code>, <code>lon</code>, <code>elevation</code>, <code>name</code> fields.
** '''getSid()''' return SID as ghost, e.g. <code>var sid = airportinfo().getSid("SA1A");</code>.
** '''getStar()''' return STAR as ghost, e.g. <code>var star = airportinfo().getStar("KEILA1");</code>.
** '''getIAP()''' return IAP as ghost, e.g. <code>var iap = airportinfo().getIAP("ILS02");</code>.
** '''getApproach()''' return approach as ghost, e.g. <code>var approach = airportinfo().getApproach("ILS02");</code>.
** '''tostring()''' just return string "an airport ICAO".
** See also {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1902}}.
* '''lon''': Longitude of the location.
* '''lat''': Latitude of the location.
* '''has_metar''': True or false depending whether the airport has a [[METAR]] code defined for it.
* '''elevation''': Elevation of the location in metres.
* '''id''': ICAO code of the airport (or ID of the seaplane base/heliport).
* '''name''': Name of the airport/heliport/seaplane base.
* '''runways'''
** '''<runway name>'''
*** '''id''': Name of runway.
*** '''lat''': Latitude of the runway.
*** '''lon''': Longitude of the runway.
*** '''heading''': True heading of the runway.
*** '''length''': Length of the runway in metres.
*** '''width''': Width of the runway in metres.
*** '''surface''': Runway surface type.
*** '''threshold''': Length of the runway's {{wikipedia|displaced threshold}} in metres. Will return 0 if there is none.
*** '''stopway''': Length of the runway's stopway (the area before the threshold) in metres. Will return 0 if there is none.
*** '''reciprocal''': <code>runway</code> ghost of the reciprocal runway.
*** '''ils_frequency_mhz''': ILS frequency in megahertz.
*** '''ils''': <code>navaid</code> ghost of the ILS transmitter.
* '''helipads'''
** '''<helipad name>'''
*** '''id''': Name of helipad.
*** '''lat''': Latitude of the helipad.
*** '''lon''': Longitude of the helipad.
*** '''heading''': True heading of the helipad.
*** '''length''': Length of the helipad in metres.
*** '''width''': Width of the helipad in metres.
*** '''surface''': Helipad surface type.
* '''taxiways'''
** '''<taxiway name>'''
*** '''id''': Name of taxiway.
*** '''lat''': Latitude of the taxiway.
*** '''lon''': Longitude of the taxiway.
*** '''heading''': Heading of the taxiway.
*** '''length''': Length of the taxiway in metres.
*** '''width''': Width of the taxiway in metres.
*** '''surface''': Taxiway surface type.

Information is extracted in the same way as accessing members of a Nasal hash. For example:
<syntaxhighlight lang="nasal">
# prints to lengths of the runways of the nearest airport in feet and metres
var info = airportinfo();
print("-- Lengths of the runways at ", info.name, " (", info.id, ") --");
foreach(var rwy; keys(info.runways)){
print(rwy, ": ", math.round(info.runways[rwy].length * M2FT), " ft (", info.runways[rwy].length, " m)");
}
</syntaxhighlight>

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.
|param1 = id
|param1text = The {{wikipedia|International Civil Aviation Organization airport code|ICAO code|noicon=1}} of an airport to retrieve information about.
|param2 = type
|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).
: {{inote|Running this function without any parameters is equivalent to this:
: <syntaxhighlight lang="nasal">
airportinfo("airport");
</syntaxhighlight>
}}
|param3 = lat ''and'' lon
|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.
|example1 = var info = airportinfo();
print("Nearest airport: ", info.name, " (", info.id, ")"); # prints the name and ICAO code of the nearest airport
|example2 = var info = airportinfo("heliport");
print("Elevation of the nearest heliport: ", math.round(info.elevation * M2FT), " ft"); # prints the elevation and name of the nearest heliport
|example3 = var info = airportinfo("KSQL");
print("-- Runways of ", info.name, " (", info.id, "): --");
foreach(var rwy; keys(info.runways)) {
print(rwy); # prints the runways of KSQL
}
|example4 = var info = airportinfo(37.81909385, -122.4722484);
print("Coordinates of the nearest airport: ", info.lat, ", ", info.lon); # print the name and ICAO of the nearest airport to the Golden Gate Bridge
|example5 = var info = airportinfo(37.81909385, -122.4722484, "seaport");
print("Nearest seaplane base: ", info.name, " (", info.id, ")"); # print the name and ID of the nearest seaplane base to the Golden Gate Bridge
|example6text = This example prints the all information from an <code>airportinfo()</code> call.
|example6 = var info = airportinfo("KSFO");
print(info.name);
print(info.id);
print(info.lat);
print(info.lon);
print(info.has_metar);
print(info.elevation);
foreach(var rwy; keys(info.runways)){
print("-- ", rwy, " --");
print(info.runways[rwy].lat);
print(info.runways[rwy].lon);
print(info.runways[rwy].length);
print(info.runways[rwy].width);
print(info.runways[rwy].heading);
print(info.runways[rwy].stopway);
print(info.runways[rwy].threshold);
<nowiki>}</nowiki>
}}

===airwaysRoute() ===
{{Nasal doc
|syntax = airwaysRoute(start, end[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1933|t=Source}}
|text = {{see also|Nasal Flightplan}}
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.
|param1 = start
|param1text = Start waypoint, in the form of a waypoint ghost, such as that provided by {{func link|flightplan()}}.
|param2 = end
|param2text = Same as above.
|param3 = type
|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."
|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.
|example1 = var fp = flightplan();
var start = fp.getWP(0);
var end = fp.getWP(fp.getPlanSize() - 1);
var rt = airwaysRoute(start, end);
foreach(var wp; rt){
print(wp.wp_name); # print the waypoints in the computed route
}
|example2text = Exactly the same as above, but computes a low level path.
|example2 = var fp = flightplan();
var start = fp.getWP(0);
var end = fp.getWP(fp.getPlanSize() - 1);
var rt = airwaysRoute(start, end, "lowlevel");
foreach(var wp; rt){
print(wp.wp_name); # print the waypoints in the computed route
<nowiki>}</nowiki>
}}

===airway()===

{{Nasal doc
|syntax = airway(ident [, pos]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2644|t=Source}}
|text = {{see also|Nasal Flightplan}}
This function returns a ghost containing an airway of a specified id.
|param1 = ident
|param1text = a Positioned ghost (leg, navaid, airport) and so on, passed to the search function.
|param2 = pos
}}

===assert()===
{{Nasal doc
|syntax = assert(condition[, message]);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|version = 3.2
|commit = {{fgdata commit|8b16a7|t=commit}}
|text = Returns either true if the condition evaluates as true, or aborts with a {{func link|die()}} call, which can be customised.
|param1 = condition
|param1text = Condition to evaluate.
|param2 = message
|param2text = Optional message that will be used in any {{func link|die()}} call. Defaults to "assertion failed!"
|example1 = var a = 1;
var b = 2;
print(assert(a < b)); # prints "1" (true)
|example2 = var a = 1;
var b = 2;
assert(a > b, 'a is not greater than b'); # aborts with a custom error message
}}

===carttogeod()===
{{Nasal doc
|syntax = carttogeod(x, y, z);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=945|t=Source}}
|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>
|param1 = x
|param1text = Mandatory x-axis value, in metres.
|param2 = y
|param2text = Mandatory y-axis value, in metres.
|param3 = z
|param3text = Mandatory z-axis value, in metres.
|example1 = var (lat, lon, alt) = carttogeod(6378137, 0, 0); # point is the intersection of the prime meridian and equator.
print("Latitude: ", lat); # prints lat, lon and alt, which are all zero, see above
print("Longitude: ", lon);
print("Altitude: ", alt);
}}

===cmdarg()===
{{Nasal doc
|private = _cmdarg()
|syntax = cmdarg();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=513|t=Part 1}} {{!}} {{fgdata file|Nasal/globals.nas|t=Part 2}}
|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.
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:
* Bindings: This is needed so that the value of a joystick's axis can be accessed internally.
* 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).
* 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.
* 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>

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.

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.
|example1 = fgcommand("dialog-show", {"dialog-name": "cmdarg-demo"});
|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.
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>

<PropertyList>

<name>cmdarg-demo</name>
<layout>vbox</layout>

<text>
<label>Click "Close" to activate the demonstration (a message in the console).</label>
</text>

<button>
<legend>Close</legend>
<binding>
<command>nasal</command>
<script>print("Button binding root: '" ~ cmdarg().getPath() ~ "'");</script>
</binding>
<binding>
<command>dialog-close</command>
</binding>
</button>

</PropertyList>
</syntaxhighlight>
|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!"
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>

<PropertyList>

<name>cmdarg-demo</name>
<layout>vbox</layout>

<text>
<label>Click "Click me!" to activate the demonstration (the button's label will change).</label>
</text>

<button>
<legend>Click me!</legend>
<binding>
<command>nasal</command>
<script>change_label();</script>
</binding>
</button>

<button>
<legend>Close</legend>
<binding>
<command>dialog-close</command>
</binding>
</button>

<nasal>
<open><![CDATA[
var dlg_root = cmdarg();
var dlg_name = {"dialog-name": "cmdarg-demo"};
var change_label = func {
dlg_root.getNode("button[0]/legend").setValue("I've been changed!");
fgcommand("dialog-close", dlg_name);
fgcommand("dialog-show", dlg_name);
}
]]></open>
</nasal>

</PropertyList>
</syntaxhighlight>
|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]].
}}

===courseAndDistance()===
{{Nasal doc
|syntax = courseAndDistance(to);
courseAndDistance(from, to);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1668|t=Source}}
|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:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object with geodetic coordinates (cartesian coordinates will not be accepted)
|param1 = from
|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.
|param2 = to
|param2text = Like the first parameter, but defines the second point.
|example1text = This example demonstrates the usage of the function with the <code>airport</code> ghost type.
|example1 = var from = airportinfo("KSFO");
var to = airportinfo("KSQL");
var (course, dist) = courseAndDistance(from, to);
print(course); # prints course from KSFO to KSQL
print(dist); # prints distance in nm from KSFO to KSQL
|example2text = This example demonstrates the usage of the function with hashes containing ''lat'' and ''lon''.
|example2 = var from = {lat: 0, lon: 0};
var to = {lat: 1, lon: 1};
var (course, dist) = courseAndDistance(from, to);
print(course);
print(dist);
|example3text = This example demonstrates usage of a geo.Coord object.
|example3 = var from = geo.Coord.new().set_latlon(0, 0);
var to = geo.Coord.new().set_latlon(1, 1);
var (course, dist) = courseAndDistance(from, to);
print(course);
print(dist);
|example4text = This example demonstrates usage of differing parameter types.
|example4 = var from = airportinfo("KSFO");
var to = geo.Coord.new().set_latlon(0, 0);
var (course, dist) = courseAndDistance(from, to);
print(course);
print(dist);
|example5text = The same as above, but the other way round.
|example5 = var to = {lat: 1, lon: 1};
var (course, dist) = courseAndDistance(0, 0, to);
print(course);
print(dist);
|example6text = Usage of just one parameter.
|example6 = var dest = airportinfo("KSQL");
var (course, dist) = courseAndDistance(dest);
print("Turn to heading ", math.round(course), ". You have ", sprintf("%.2f", dist), " nm to go");
}}

===createFlightplan()===
{{Nasal doc
|syntax = createFlightplan(path);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2331|t=Source}}
|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.
|param1 = path
|param1text = Optional parameter defining the file from which a flightplan will be populated.
|example1 =
var path = getprop("/sim/fg-home") ~ "/Export/test.fgfp";
var flightplan = createFlightplan(path);
debug.dump(flightplan);
}}

===createDiscontinuity()===
{{Nasal doc
|syntax = createDiscontinuity();
|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.
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2045|t=Source}}
|version = 2016.1
|commit = {{flightgear commit|caead6|t=commit}}
}}
===createViaTo()===
{{Nasal doc
|syntax = createViaTo(airway, waypoint);
|text = Returns a <code>waypoint</code> ghost object. It represents a route "via '''airway''' to '''waypoint'''".
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2009|t=Source}}
|version = 2016.1
|commit = {{flightgear commit|caead6|t=commit}}
|param1 = airway
|param1text = The name of an airway.
|param2 = waypoint
|param2text = Must be in the airway and one of:
* The name of a waypoint.
* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, or <code>fix</code> ghost object.
}}
===createWP()===
{{Nasal doc
|syntax = createWP(pos, name[, flag]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1964|t=Source}}
|text = Creates a new waypoint ghost object.
|param1 = pos
|param1text = Dictates the position of the new waypoint. It can be one of the following:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. See example 4 below.
|param2 = name
|param2text = String that will become the name of the new waypoint.
|param3 = flag
|param3text = Optional string that will tell FlightGear what type of waypoint it is. Must be one of "sid," "star," "approach," "missed," or "pseudo."
|example1text = Creates a waypoint directly in front and 1 km away and appends it to the flight plan.
|example1 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);
var wp = createWP(pos, "NEWWP");
var fp = flightplan();
fp.appendWP(wp);
|example2 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);
var wp = createWP({lat: pos.lat(), lon: pos.lon()}, "NEWWP");
var fp = flightplan();
fp.appendWP(wp);
|example3 = var apt = airportinfo();
var wp = createWP(apt, "NEWWP");
var fp = flightplan();
fp.appendWP(wp);
|example4 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);
var wp = createWP(pos.lat(), pos.lon(), "NEWWP");
var fp = flightplan();
fp.appendWP(wp);
|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.
|example5 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);
var wp = createWP(pos, "NEWWP", "pseudo");
var fp = flightplan();
fp.appendWP(wp);
print(fp.getPlanSize());
fp.clearWPType("pseudo");
print(fp.getPlanSize());
}}

===createWPFrom()===
{{Nasal doc
|syntax = createWPFrom(object[, flag]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1989|t=Source}}
|text = Creates a new waypoint object from another object.
|param1 = object
|param1text = A ghost object. Must be a ghost type that is one of "airport," "navaid," "runway," or "fix."
|param2 = flag
|param2text = Optional string that will tell FlightGear what type of waypoint it is. Must be one of "sid," "star," "approach," "missed," or "pseudo."
|example1text = Creates a new waypoint and appends it to the flight plan.
|example1 = var apt = airportinfo("KSFO");
var wp = createWPFrom(apt);
var fp = flightplan();
fp.appendWP(wp);
|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.
|example2 = var apt = airportinfo("KSFO");
var wp = createWPFrom(apt, "pseudo");
print(wp.wp_name);
var fp = flightplan();
fp.appendWP(wp);
print(fp.getPlanSize());
fp.clearWPType("pseudo");
print(fp.getPlanSize());
}}

===defined()===
{{Nasal doc
|syntax = defined(symbol);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = Returns 1 (true) or 0 (false) depending on whether a variable exists.
|param1 = symbol
|param1text = A string that will be what the function searches for.
|example1 = var number = 12;
var check_exist = func {
print("Variable 'number' ", defined("number") == 1 ? "exists" : "does not exist"); # 'number' does exist
print("Variable 'number2' ", defined("number2") == 1 ? "exists" : "does not exist"); # 'number2' does not exist
}
check_exist();
}}

===directory()===
{{Nasal doc
|syntax = directory(path);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=572|t=Source}}
|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.
{{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.}}
|param1 = path
|param1text = Absolute file path.
|example1text = Gets the folders and files in [[$FG_ROOT]], and then removes the extra first two elements (see note above).
|example1 = var dir = directory(getprop("/sim/fg-root")); # get directory
dir = subvec(dir, 2); # strips off the first two elements
debug.dump(dir); # dump the vector
}}

===fgcommand()===
{{Nasal doc
|syntax = fgcommand(cmd[, args]);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=456|t=Part 1}} {{!}} {{fgdata file|Nasal/globals.nas|t=Part 2}}
|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.
|param1 = cmd
|param1text = String that is the name of the command that is to be run.
|param2 = args
|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).
|example1 = fgcommand("null"); # does nothing
|example2 = var args = props.Node.new({'script': 'print("Running fgcommand");'});
if (fgcommand("nasal", args)) { # prints "Running fgcommand" and then one of these print statements
print("Fgcommand succeeded");
} else {
print("Fgcommand encountered a problem");
}
|example3 = var args = { 'dialog-name': 'about' };
fgcommand("dialog-show", args); # shows the 'about' dialog
}}

===findAirportsByICAO() ===
{{Nasal doc
|syntax = findAirportsByICAO(search[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1096|t=Source}}
|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.
|param1 = search
|param1text = Search string for the function. Can either be a partial or a full ICAO code.
:{{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.}}
|param2 = type
|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."
|example1 = var apts = findAirportsByICAO("KSF"); # finds all airports matching "KSF"
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")"); # prints them
}
|example2 = var apts = findAirportsByICAO("SP0", "seaport"); # finds all seaplane bases matching "SP0"
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")"); # prints them
}
|example3 = var apt = findAirportsByICAO("XBET"); # one way to check if an airport does exist"
if (size(apt) == 0) {
print("Airport does not exist"); # this one will be printed
} else {
print("Airport does exist");
<nowiki>}</nowiki>
}}

===findAirportsWithinRange()===
{{Nasal doc
|syntax = findAirportsWithinRange([pos, ]range[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1066|t=Source}}
|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.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findAirportsWithinRange(lat, lon, range, type);</code>.
|param2 = range
|param2text = Mandatory number giving the range in nautical miles within which to search for airports/heliports/seaplane bases.only airports are searched for.
|param3 = type
|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."
|example1text = Searches for airports within 10 nm of [[KSFO]].
|example1 = var pos = airportinfo("KSFO");
var apts = findAirportsWithinRange(pos, 10);
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")");
}
|example2text = Searches for seaplane bases within 15 nm of [[KSFO]].
|example2 = var pos = airportinfo("KSFO");
var apts = findAirportsWithinRange(pos, 15, "seaport");
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")");
}
|example3text = Searches for airports within 10 nm of your current position.
|example3 = var apts = findAirportsWithinRange(10);
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")");
<nowiki>}</nowiki>
}}

===findCommByFrequencyMHz()===
findCommByFrequencyMHz([pos, ]freq[, type]);
[[sourceforge:p/flightgear/flightgear/ci/next/tree/src/Scripting/NasalPositioned.cxx#l1547|source]]

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.

'''pos'''

: Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findCommByFrequencyMHz(lat, lon, freq, type);</code>.
; freq
: Frequency, in megahertz, of the station to search for.
; type
: 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)
'''Example'''
var com = findCommByFrequencyMHz(123.6);
print("ID: ", com.id); # prints info about the comm station
print("Name: ", com.name);
print("Latitude: ", com.lat);
print("Longitude: ", com.lon);
print("Type: ", com.type);
print("Frequency: ", sprintf("%.3f", com.frequency), " Mhz");

=== findFixesByID() ===
{{Nasal doc
|syntax = findFixesByID([pos, ]id);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1627|t=Source}}
|text = Returns a vector containing <code>fix</code> ghost objects matching a given ID, sorted by range from a certain position.
{{inote|Fixes are (usually) also known as waypoints.}}
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findFixesByID(lat, lon, id);</code>.
|param2 = id
|param2text = Full or partial ID of the fix to search for.
:{{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.}}
|example1 = var fixes = findFixesByID("POGIC");
foreach(var fix; fixes){
print(fix.id, " - lat: ", fix.lat, " {{!}} lon: ", fix.lon); # prints information about POGIC
}
|example2 = var fix = findFixesByID("ZUNAP");
fix = fix[0];
var (course, dist) = courseAndDistance(fix);
print("Turn to heading ", math.round(course), ". You have ", sprintf("%.2f", dist), " nm to go to reach ", fixes[0].id);
}}

===findNavaidByFrequencyMHz()===
{{Nasal doc
|syntax = findNavaidByFrequencyMHz([pos, ]freq[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1547|t=Source}}
|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.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidByFrequencyMHz(lat, lon, freq, type);</code>.
|param2 = freq
|param2text = Frequency, in megahertz, of the navaid to search for.
|param3 = type
|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}}.
|example1 = var navaid = findNavaidByFrequencyMHz(109.55);
print("ID: ", navaid.id); # prints info about the navaid
print("Name: ", navaid.name);
print("Latitude: ", navaid.lat);
print("Longitude: ", navaid.lon);
print("Elevation (AMSL): ", navaid.elevation, " m");
print("Type: ", navaid.type);
print("Frequency: ", sprintf("%.3f", navaid.frequency / 100), " Mhz");
print("Range: ", navaid.range_nm, " nm");
if(navaid.course) print("Course: ", navaid.course);
}}

=== findNavaidsByFrequencyMHz()===
{{Nasal doc
|syntax = findNavaidsByFrequencyMHz([pos, ]freq[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1572|t=Source}}
|text = Returns a vector conatining <code>navaid</code> ghost objects for navaids that match a given frequency, sorted from nearest to furthest.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidsByFrequencyMHz(lat, lon, freq, type);</code>.
|param2 = freq
|param2text = Frequency, in megahertz, of the navaid to search for.
|param3 = type
|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}}.
|example1 = var navaids = findNavaidsByFrequencyMHz(109.55);
foreach(var navaid; navaids){
print("--");
print("ID: ", navaid.id); # prints info about the navaid
print("Name: ", navaid.name);
print("Latitude: ", navaid.lat);
print("Longitude: ", navaid.lon);
print("Elevation (AMSL): ", navaid.elevation, " m");
print("Type: ", navaid.type);
print("Frequency: ", sprintf("%.3f", navaid.frequency / 100), " Mhz");
print("Range: ", navaid.range_nm, " nm");
if(navaid.course) print("Course: ", navaid.course);
print("--");
<nowiki>}</nowiki>
}}

===findNavaidsByID()===
{{Nasal doc
|syntax = findNavaidsByID([pos, ]id[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1600|t=Source}}
|text = Returns a vector containing <code>navaid</code> ghost objects matching a given ID, sorted by range from a certain position.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidsByID(lat, lon, id, type);</code>.
|param2 = id
|param2text = Full or partial ID of the fix to search for.
:{{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.}}
|param3 = type
|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}}.
|example1 = var navaid = findNavaidsByID("MXW");
navaid = navaid[0];
print("ID: ", navaid.id); # prints info about 'MXW' (a VOR station)
print("Name: ", navaid.name);
print("Latitude: ", navaid.lat);
print("Longitude: ", navaid.lon);
print("Elevation (AMSL): ", navaid.elevation, " m");
print("Type: ", navaid.type);
print("Frequency: ", sprintf("%.3f", navaid.frequency / 1000), " Mhz");
print("Range: ", navaid.range_nm, " nm");
}}

===findNavaidsWithinRange()===
{{Nasal doc
|syntax = findNavaidsWithinRange([pos, ]range[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1518|t=Source}}
|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.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidsWithinRange(lat, lon, range, type);</code>.
|param2 = range
|param2text = Mandatory number giving the range in nautical miles within which to search for navaids.
|param3 = type
|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}}.
|example1text = Searches for navaids within 10 nm of [[KSFO]].
|example1 = var pos = airportinfo("KSFO");
var navs = findNavaidsWithinRange(pos, 10);
foreach(var nav; navs){
print(nav.name, " (ID: ", nav.id, ")");
}
|example2text = Searches for navaids within 10 nm of your current position.
|example2 = var navs = findNavaidsWithinRange(10);
foreach(var nav; navs){
print(nav.name, " (ID: ", nav.id, ")");
<nowiki>}</nowiki>
}}

===finddata()===
{{Nasal doc
|syntax = finddata(path);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=603|t=Source}}
|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]].
|param1 = path
|param1text = A relative path as a string.
|example1 = var path = finddata("Aircraft/Generic");
print(path); # prints the absolute path to $FG_ROOT/Aircraft/Generic
|example2 = var path = finddata("Airports");
print(path); # prints the absolute path to <TerraSync dir>/Airports
|example3 = var path = finddata("preferences.xml");
print(path); # prints the absolute path to $FG_ROOT/preferences.xml
}}

===flightplan()===
{{Nasal doc
|syntax = flightplan([path]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1738|t=Source}}
|text = {{see also|Nasal Flightplan}}
Returns a flight plan object, either one for the current flight plan, or one loaded from a given path.
|param1 = path
|param1text = Optional path to flight plan XML file.
|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.
|example1 = var fp = flightplan();
print(fp.getWP(fp.current).id);
|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>.
|example2 = var path = getprop('/sim/fg-home') ~ '/fp-demo.xml';
var fp = flightplan(path);
for(var i = 0; i < fp.getPlanSize(); i += 1){
print(fp.getWP(i).id);
<nowiki>}</nowiki>
}}

===geodinfo()===
{{Nasal doc
|syntax = geodinfo(lat, lon[, max_alt]);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=981|t=Source}}
|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}}):
* '''light_coverage:''' The coverage of a single point of light in m<sup>2</sup>.
* '''bumpiness:''' Normalized bumpiness factor for the material.
* '''load_resistance:''' The amount of pressure in N/m<sup>2</sup> the material can withstand without deformation.
* '''solid:''' 1 (true) or false (0) depending on whether the material is solid or not.
* '''names:''' Vector of scenery types (usually generated by [[TerraGear]]) that will use this material.
* '''friction_factor:''' Normalized friction factor of the material.
* '''rolling_friction:''' The rolling friction coefficient of the material.

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.
|param1 = lat
|param1text = Latitude, inputted as a number.
|param2 = lon
|param2text = Longitude, inputted as a number.
|param3 = max_alt
|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.
|example1text = Dumps information about ground underneath the aircraft.
|example1 = var pos = geo.aircraft_position();
var info = geodinfo(pos.lat(), pos.lon());
debug.dump(info);
|example2text = Prints whether the ground underneath the aircraft is solid or is water.
|example2 = var pos = geo.aircraft_position();
var info = geodinfo(pos.lat(), pos.lon());
if (info != nil and info[1] != nil) {
print("The ground underneath the aircraft is ", info[1].solid == 1 ? "solid." : "water.");
<nowiki>}</nowiki>
}}

=== geodtocart() ===
{{Nasal doc
|syntax = geodtocart(lat, lon, alt);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=962|t=Source}}
|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.
|param1 = lat
|param1text = Latitude, in degrees.
|param2 = lon
|param2text = Longitude, in degrees.
|param3 = alt
|param3text = Altitude, in metres.
|example1 = var (x, y, z) = geodtocart(0, 0, 0); # point is the intersection of the prime meridian and equator.
print("x: ", x); # prints "x: 6378137"
print("y: ", y); # prints "y: 0"
print("z: ", z); # prints "y: 0"
}}

=== get_cart_ground_intersection()===
Introduced in 2017.2.1, see [[Terrain Detection]].

===getprop()===
{{Nasal doc
|syntax = <nowiki>getprop(path[, path[, ...]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=345|t=Source}}
|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).
|param1 = path
|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.
|example1 = print("You have FlightGear v", getprop("/sim/version/flightgear")); # prints FlightGear version
|example2text = Note that the example below will only work in FlightGear 3.2 and above.
|example2 = for(var i = 0; i < 8; i += 1){
print("View #", i + 1, " is named ", getprop("/sim/view", i, "name"));
}
|example3text = Same as above, but is supported by all versions of FlightGear.
|example3 = for(var i = 0; i < 8; i += 1){
print("View #", i + 1, " is named ", getprop("/sim/view[" ~ i ~ "]/name"));
<nowiki>}</nowiki>
}}
==== See also====
{{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:
To get a Node rather than its value, use <code>props.globals.getNode()</code> - see [[Nasal_library/props]]. }}

===greatCircleMove()===
{{Nasal doc
|syntax = greatCircleMove([pos, ]course, dist);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1681|t=Source}}
|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).
|param1 = pos
|param1text = Optional position to calculate from. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost object.
:* A hash with ''lat'' and ''lon'' members
:* A <code>geo.Coord</code> object
:* A lat/lon pair, that is, a pair of numbers (latitude followed by longitude) separated by a comma: <code>greatCircleMove(lat,lon, ...)</code>.
|param2 = course
|param2text = Course to new set of coordinates, in degrees (in the range 0–360).
|param3 = dist
|param3text = Distance in nautical miles to the new set of coordinates.
|example1 = var pos = greatCircleMove(0,0, 0, 1);
debug.dump(pos); # print hash with coordinates
|example2 = var fix = findFixesByID("POGIC");
fix = fix[0];
var pos = greatCircleMove(fix, 45, 10);
debug.dump(pos); # print hash with coordinates
}}

===interpolate()===
{{Nasal doc
|private = _interpolate()
|syntax = <nowiki>interpolate(prop, value1, time1[, value2, time2[, ...]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=522|t=Part 1}} {{!}} {{fgdata file|Nasal/globals.nas|t=Part 2}}
|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.
|param1 = prop
|param1text = String or <code>props.Node</code> object that indicates a node in the property tree to be used.
|param2 = value''n''
|param2text = Target value to change the property to in the set amount of time. This should be a number.
|param3 = time''n''
|param3text = Time in seconds, that will be taken for the interpolation.
|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.
|example1 = setprop("/test", 0); # (re-)set property
interpolate("/test",
50, 5, # interpolate to 50 in 5 seconds
10, 2, # interpolate to 10 in 2 seconds
0, 5); # interpolate to 0 in 5 seconds
|example2 = # Apply the left brake at 20% per second
var prop = "controls/gear/brake-left";
var dist = 1 - getprop(prop);
if (dist == 1) {
interpolate(prop, 1, dist / 0.2);
<nowiki>}</nowiki>
}}

===isa()===
{{Nasal doc
|syntax = isa(object, class);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|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.
|param1 = object
|param1text = Object to check.
|param2 = class
|param2text = Class/object to check that '''object''' inherits from or is an instance of.
|example1 = var coord = geo.Coord.new();
if(isa(coord, geo.Coord)){
print("Variable 'coord' is an instance of class 'geo.Coord'"); # this one will be printed
} else {
print("Variable 'coord' is not an instance of class 'geo.Coord'");
}
|example2 = var coord = geo.Coord.new();
if(isa(coord, props.Node)){
print("Variable 'coord' is an instance of class 'props.Node'");
} else {
print("Variable 'coord' is not an instance of class 'props.Node'"); # this one will be printed
}
|example3text = The example below demonstrates checking of inheritance.
|example3 = var Const = {
constant: 2,
getConst: func {
return me.constant;
}
};

var Add = {
new: func {
return { parents: [Add, Const] };
},

addToConst: func(a){
return a * me.getConst();
}
};

var m = Add.new();
print(m.addToConst(4));

if(isa(m, Add)) print("Variable 'm' is an instance of class 'Add'"); # will be printed
if(isa(m, Const)) print("Variable 'm' is an instance of class 'Const'"); # will also be printed
}}

===logprint()===
{{Nasal doc
|syntax = <nowiki>logprint(priority[, msg[, msg[, ...]]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=431|t=Source}}
|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}}.
|param1 = priority
|param1text = Number specifying the priority level of the outputted message:
:{{{!}} class="wikitable"
! Number !! Debug type
{{!-}}
{{!}} 1 {{!!}} Bulk
{{!-}}
{{!}} 2 {{!!}} Debug
{{!-}}
{{!}} 3 {{!!}} Info
{{!-}}
{{!}} 4 {{!!}} Warn
{{!-}}
{{!}} 5 {{!!}} Alert
{{!}}}
|param2 = msg
|param2text = The message. There is no limit to the arguments you give give. They will be concatenated together before logging.
|example1 = # logs the value of pi to three decimal places with log level 3
logprint(3, "pi = ", sprintf("%.3f", math.pi));
|example2 = logprint(5, "Alert! This is an important message!");
}}
{{note|
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:

LOG_BULK, LOG_WARN, LOG_DEBUG, LOG_INFO, LOG_ALERT, DEV_WARN, DEV_ALERT }}

===magvar() ===
{{Nasal doc
|syntax = magvar([pos]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1642|t=Source}}
|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.
{{{!}} class="wikitable"
! FlightGear versions !! Model !! Reference date
{{!-}}
{{!}} 3.6 and above {{!!}} {{wikipedia|World Magnetic Model}} (WMM) 2015 {{!!}} 1 January 2015
{{!-}}
{{!}} 0.9.11-pre1 to 3.4 {{!!}} WMM 2005 {{!!}} 1 January 2005
{{!-}}
{{!}} 0.7.3 to 0.9.10 {{!!}} WMM 2000 {{!!}} 1 January 2000
{{!}}}
|param1 = pos
|param1text = Optional position to calculate from. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost object.
:* A hash with ''lat'' and ''lon'' members
:* A <code>geo.Coord</code> object
:* A lat/lon pair, that is, a pair of numbers (latitude followed by longitude) separated by a comma: <code>magvar(lat,lon)</code>.
|example1 = print(magvar(0, 0)); # prints the magnetic variation at 0, 0
}}

===maketimer() ===
{{Nasal doc
|syntax = maketimer(interval[, self], function);
|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}}
|version = 2.12
|commit = {{flightgear commit|ab939f|t=commit}}
|text = Returns a timer object containing the following methods and members:
* '''start()''': Starts the timer.
* '''stop()''': Stops the timer.
* '''restart(interval)''': Restarts the timer with the given interval.
* '''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).
* '''isRunning''': Read-only bool telling whether the timer is currently running.
* '''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.
Unlike {{func link|settimer()}}, which it replaces, <code>maketimer()</code> provides more control over the timer. In addition, it can help reduce memory usage.
|param1 = interval
|param1text = Interval in seconds for the timer.
|param2 = self
|param2text = Optional parameter specifying what any <code>'''me'''</code> references in the function being called will refer to.
|param3 = function
|param3text = Function to be called at the given interval.
|example1 = var timer = maketimer(1, func(){
print("Hello, World!"); # print "Hello, World!" once every second (call timer.stop() to stop it)
});
timer.start();
|example2 = var timer = maketimer(1, math, func(){
print(me.math); # 'me' reference is the 'math' namespace
});
timer.singleShot = 1; # timer will only be run once
timer.start();
|example3 = var timer = maketimer(1, func(){
print("Hello, World!"); # print "Hello, World!" once every second (call timer.stop() to stop it)
});
timer.start();
print(timer.isRunning); # prints 1
|example4text = In the example below, "Hello, World!" will be printed after one second the first time, and after two seconds thereafter.
|example4 = var update = func(){
print("Hello, World!");
timer.restart(2); # restarts the timer with a two second interval
}

var timer = maketimer(1, update);
timer.singleShot = 1;
timer.start();
}}

===maketimestamp()===
{{Nasal doc
|syntax = maketimestamp()
|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}}
|version = 2019.2
|commit = {{flightgear commit|7db06300|t=commit}}
|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:
* '''stamp()''': Resets the timing operation. Call this first.
* '''elapsedMSec()''': returns number of milliseconds elapsed since stamp() called. Resolution may vary depending on platform but is usually at least millisecond accuracy.
* '''elapsedUSec()''': returns number of microseconds elapsed since stamp() called. Resolution may vary depending on platform but is usually at least millisecond accuracy.
|
|example1text = In the example below the number of milliseconds elapsed will be printed.
|example1 = var timestamp = maketimestamp();
timestamp.stamp();
print(timestamp.elapsedMSec(), "ms elapsed");
print(timestamp.elapsedMSec(), "ms elapsed");
}}

===md5()===
{{Nasal doc
|syntax = md5(string);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=758|t=Source}}
|version = 3.2
|commit = {{flightgear commit|cfbf9e|t=commit}}
|text = Returns a the {{wikipedia|MD5}} hash (as a string) of the inputted string.
|param1 = string
|param1text = String the generate the hash of. Mandatory.
|example1text = The below code should output <code>65a8e27d8879283831b664bd8b7f0ad4</code>.
|example1 = print(md5("Hello, World!"));
}}

===navinfo()===
{{Nasal doc
|syntax = navinfo(lat, lon, type, id);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1453|t=Source}}
|text = Returns vector <code>navaid</code> ghost objects matching the given '''type''' and '''id''' or <code>'''nil'''</code> on error.
|param1 = lat ''and'' lon
|param1text = If given, the returned navaids will be put into order of ascending distance from the location.
|param2 = type
|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."
|param3 = id
|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.
|example1 = navinfo("vor"); # returns all VORs
|example2 = navinfo("HAM"); # return all navaids whose names start with "HAM"
|example3 = navinfo("vor", "HAM"); # return all VORs whose names start with "HAM"
|example4 = navinfo(34,48,"vor","HAM"); # return all VORs whose names start with "HAM" and sorted by distance relative to 34°, 48°
}}

===parse_markdown()===
{{Nasal doc
|syntax = parse_markdown(markdown);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=745|t=Part 1}} {{!}} {{simgear file|simgear/misc/SimpleMarkdown.cxx|t=Part 2}}
|version = 3.2
|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:
* It strips whitespace from the beginning of the string.
* It supports [http://daringfireball.net/projects/markdown/syntax#p paragraphs and line breaks].
* It collapses whitespace.
* It converts unordered [http://daringfireball.net/projects/markdown/syntax#list lists] to use a bullet character (•). 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.
|param1 = markdown
|param1text = String containing Markdown to be parsed.
|example1text =
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>).
<syntaxhighlight lang="xml" highlight="41-50">
<?xml version="1.0" encoding="UTF-8"?>

<PropertyList>

<name>test</name>
<layout>vbox</layout>

<group>
<layout>hbox</layout>

<empty>
<stretch>true</stretch>
</empty>

<text>
<label>parse_markdown() test dialog</label>
</text>

<empty>
<stretch>true</stretch>
</empty>

<button>
<legend></legend>
<pref-width>16</pref-width>
<pref-height>16</pref-height>
<binding>
<command>dialog-close</command>
</binding>
</button>

</group>

<canvas>
<name>Canvas plot</name>
<stretch>true</stretch>
<pref-width>400</pref-width>
<pref-height>300</pref-height>
<nasal>
<load><![CDATA[
var text = 'Items:
* apples
* oranges
* pears

Some text.
Some more items:
* apples
* oranges
* pears';

var parsed = parse_markdown(text);

var root_canvas = canvas.get(cmdarg());
root_canvas.setColorBackground(255, 255, 255);
var root = root_canvas.createGroup();

var text_dis = root.createChild("text")
.setText(parsed)
.setTranslation(5, 5)
.setFont("LiberationFonts\LiberationSans-Regular.ttf")
.setFontSize(15)
.setColor(0, 0, 0)
.setDrawMode(canvas.Text.TEXT)
.setAlignment("left-top");
]]></load>
</nasal>
</canvas>

</PropertyList>
</syntaxhighlight>
|example1 = fgcommand("dialog-show", {"dialog-name": "test"});
|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.
|example2 = <nowiki>var markdown = 'Items:
* apples
* oranges
* pears

Some text.
Some more items:
* apples
* oranges
* pears';

var parsed = parse_markdown(markdown);

debug.dump(parsed);

var path = string.normpath(getprop("/sim/fg-home") ~ '/Export/parse_markdown()-test.html');

var file = io.open(path, "w");

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>";

io.write(file, html);
io.close(file);
print("Done, file ready for viewing (" ~ path ~ ")");</nowiki>
}}

===parsexml()===
{{Nasal doc
|syntax = <nowiki>parsexml(path[, start[, end[, data[, pro_ins]]]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=710|t=Source}}
|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.
|param1 = path
|param1text = Mandatory absolute path to the XML file to be parsed.
|param2 = start
|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.
|param3 = end
|param3text = Optional callback function that will be called for every ending tag. The function should take one argument: the tag name.
|param4 = data
|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.
|param5 = pro_ins
|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.
|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.
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>

<?xml-stylesheet type="text/xsl" href="style.xsl"?>

<foo>
<blah type="string"><![CDATA[ <sender>John Smith</sender> ]]></blah>
<blah2 type="string">Orange & lemons</blah2>
</foo>
</syntaxhighlight>
|example1 = var start = func(name, attr){
print("Starting tag: '", name, "'");
foreach(var a; keys(attr)){
print("\twith attribute ", a, '="', attr[a], '"');
}
}

var end = func(name){
print("Ending tag: '", name, "'");
}

var data = func(data){
print("Data = '", data, "'");
}

var pro_instr = func(target, data){
print("Processing instruction: target = '", target, "', data = '", data, "'");
}

parsexml(getprop("/sim/fg-home") ~ '/Export/demo.xml', start, end, data, pro_instr);
}}

===print()===
{{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.

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>}}

{{Nasal doc
|syntax = <nowiki>print(data[, data[, ...]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=415|t=Source}}
|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.
|param1 = data
|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.
|example1 = print("Just", " a ", "test"); # prints "Just a test"
|example2 = print("pi = ", math.pi); # prints "pi = 3.141592..."
}}

=== printf() ===
{{Nasal doc
|syntax = <nowiki>printf(format[, arg[, arg, [...]]]);</nowiki>
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|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>).
|example1 = printf("In hexadecimal, 100000 = %X", 186A0); # prints "In hexadecimal, 100000 = 186A0"
}}

===printlog()===
{{caution|This function is deprecated and doesn't work. Please use the new one {{func link|logprint()}}.}}
{{Nasal doc
|syntax = <nowiki>printlog(level, data[, data[, ...]]);</nowiki>
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|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.
|param1 = level
|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.
|param2 = data
|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.
|example1 = printlog("alert", "This is an alert"); # message will be printed
|example2 = printlog("info", "Just informing you about something"); # message will be printed only if log level is set to "info" or less
}}

===rand()===
{{Nasal doc
|syntax = rand();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=554|t=Source}}
|text = Returns a random floating point number between 0 (inclusive) and 1 (exclusive). It takes no arguments.
|example1 = print(rand()); # prints random number
}}

===registerFlightPlanDelegate()===
{{Nasal doc
|syntax = registerFlightPlanDelegate(init_func);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1879|t=Source}}
|text = Registers a flight plan delegate. See <tt>''{{fgdata file|Nasal/route_manager.nas|t=$FG_ROOT/Nasal/route_manager.nas}}''</tt> for examples.
|param1 = init_func
|param1text = Initialization function which will be called during FlightGear's startup.
}}
===removecommand()===
{{Nasal doc
|syntax = removecommand(cmd);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=668|t=Source}}
|text = Removes the given fgcommand. Returns <code>'''nil'''</code>.
{{caution|This will remove '''any''' [[fgcommands|fgcommand]], even those implemented in C++, so use with caution!}}
|param1 = cmd
|param1text = String specifying the name of the command to remove.
|example1 = addcommand("hello", func(){
print("Hello");
});
fgcommand("hello"); # "Hello" will be printed
removecommand("hello"); # removes it
}}

===removelistener()===
{{Nasal doc
|syntax = removelistener(id);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=1384|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=506|t=Part 2}}
|text = Removes and deactivates the given listener and returns the number of listeners left or <code>'''nil'''</code> on error.
{{note|It is good practice to remove listeners when they are not required anymore. This prevents the listeners reducing FlightGear's run performance.}}
|param1 = id
|param1text = ID of listener as returned by {{func link|setlistener()}}.
|example1 = var ls = setlistener("/sim/test", func(){
print("Property '/sim/test' has been changed");
});
setprop("/sim/test", "blah"); # trigger listener
var rem = removelistener(ls); # remove listener
print("There are ", rem, " listeners remaining");
}}

===resolvepath()===
{{Nasal doc
|syntax = resolvepath(path);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=604|t=Source}}
|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.
|param1 = path
|param1text = Relative path to be completed.
|example1 = print(resolvepath("Nasal/globals.nas")); # prints the equivalent of $FG_ROOT/Nasal/globals.nas
|example2 = print(resolvepath("blah")); # prints nothing; could not be resolved
|example3 = var file_path = resolvepath("Aircraft/SenecaII/some-file");
if (file_path != ""){
gui.popupTip("some-file found", 2);
} else {
gui.popupTip("some-file not found", 2);
<nowiki>}</nowiki>
}}

===setlistener()===
{{Nasal doc
|syntax = <nowiki>setlistener(node, code[, init[, type]]);</nowiki>
|private = _setlistener()
|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.''
|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()}}.
{{note|Listeners are known to be a source of resource leaks. To avoid this, please take measures such as:
* Using {{func link|removelistener()}} when they are not needed any more.
* Using a single initialization listener.
* Avoiding tying listeners to properties that are rapidly updated (e.g., many times per frame).
}}
|param1 = node
|param1text = Mandatory string or <code>props.Node</code> object pointing to a property in the [[Property Tree]].
|param2 = code
|param2text = Mandatory callback function to execute when the listener is triggered. The function can take up to four arguments in the following order:
* '''changed''': a <code>props.Node</code> object pointing to the changed node.
* '''listen''': a <code>props.Node</code> object pointing to the listened-to node. Note that this argument maybe different depending on the '''type'''.
* '''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.
* '''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.
|param3 = init
|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).
|param4 = type
|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.
|example1 = var prop = props.globals.initNode("/sim/test", "", "STRING"); # create property
var id = setlistener("/sim/test", func(n){ # create listener
print("Value: ", n.getValue());
});
setprop("/sim/test", "blah"); # trigger listener
removelistener(id); # remove listener
prop.remove(); # remove property
}}

===setprop()===
{{Nasal doc
|syntax = <nowiki>setprop(path[, path[, ...]], value);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=385|t=Source}}
|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.
{{note|If you want to remove a property, you will have to use one of the <code>props</code> helpers:
<syntaxhighlight lang="nasal">
props.globals.getNode("foo/bar").remove(); # take out the complete node
props.globals.getNode("foo").removeChild("bar"); # take out a certain child node
</syntaxhighlight>
}}
|param1 = path
|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.
|param2 = value
|param2text = Value to write to the given property. Must be either a string or a number.
|example1 = setprop("/sim/demo", "This is a demo");
|example2text = Note that the example below will only work in FlightGear 3.2 and above.
|example2 = for(var i = 0; i < 3; i += 1){
setprop("/sim/demo", i, "Demo #" ~ i));
}
|example3text = Same as above, but is supported by all versions of FlightGear.
|example3 = for(var i = 0; i < 3; i += 1){
setprop("/sim/demo[" ~ i ~ "]", "Demo #" ~ i));
<nowiki>}</nowiki>
}}
====See also====
{{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:
To get a Node rather than its value, use <code>props.globals.getNode()</code> - see [[Nasal_library/props]]. }}

===settimer() ===
{{Nasal doc
|syntax = settimer(function, delta[, realtime]);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=499|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=1286|t=Part 2}}
|text = Runs the given function a specified amount of seconds after the current time. Returns <code>'''nil'''</code>.
{{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.}}
|param1 = function
|param1text = Mandatory function that will be called. It may be necessary to enclose code in an anonymous function (see example).
|param2 = delta
|param2text = Mandatory amount of time in seconds after which the function will be called.
|param3 = realtime
|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.
|example1 = var myFunc = func(){
print("Hello");
}

settimer(myFunc, 2); # runs myFunc after 2 seconds
|example2 = var sqr = func(a){
return a * a;
}

settimer(func(){
print(sqr(2)); # will print 4 after 2 seconds
}, 2);
}}

===srand() ===
{{Nasal doc
|syntax = srand();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=559|t=Source}}
|text = Makes the pseudorandom number generator (see {{func link|rand()}}) generate a new {{wikipedia|random seed|noicon=1}} based on time. Returns 0.
}}
===systime()===
{{Nasal doc
|syntax = systime();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=770|t=Source}}
|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).
{{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]}}
|example1 = print("Unix time: ", systime()); # prints Unix time
|example2 = var myFunc = func(){
for(var i = 0; i <= 10; i += 1){
print("Interation #", i);
}
}
var t = systime(); # record time
myFunc(); # run function
var t2 = systime(); # record new time
print("myFunc() took ", t2 - t, " seconds"); # print result
}}

===thisfunc()===
{{Nasal doc
|syntax = thisfunc();
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = Returns the function from which this function is called. This allows a function to reliably and safely call itself from within a closure.
|example1 = var stringify_vec = func(input){
if (typeof(input) == "scalar"){
return sprintf("%s", input);
} elsif (typeof(input) == "vector") {
if (size(input) == 0) return "[]";
var this = thisfunc();
var buffer = "[";
for(var i = 0; i < size(input); i += 1){
buffer ~= this(input[i]);
if (i == size(input) - 1) {
buffer ~= "]";
} else {
buffer ~= ", ";
}
}
return buffer;
} else {
die("stringify_vec(): Error! Invalid input. Must be a vector or scalar");
}
}

var test_vec = ["a", "b", "c", [1, 2, 3], "d"];
debug.dump(stringify_vec(test_vec)); # prints "[a, b, c, [1, 2, 3], d]"
test_vec = [];
debug.dump(stringify_vec(test_vec)); # prints "[]"
test_vec = {};
debug.dump(stringify_vec(test_vec)); # will throw an error
}}

===tileIndex() ===
{{Nasal doc
|syntax = tileIndex();
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1720|t=Source}}
|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>.
|example1 = print(tileIndex()); # print index
}}

=== tilePath()===
{{Nasal doc
|syntax = tilePath();
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1712|t=Source}}
|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>.
|example1 = print(tilePath()); # print path
}}

=== values()===
{{Nasal doc
|syntax = values(hash);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = Returns a vector containing the values of the given hash.
|param1 = hash
|param1text = Mandatory hash to get the values of.
|example1 = var hash = {
"a": 1,
"b": 2,
"c": 3
};

foreach(var val; values(hash)){
print(val);
}
|example2text = The below example does exactly the same thing as the above example, but does not use <code>values()</code>:
|example2 = var hash = {
"a": 1,
"b": 2,
"c": 3
};

foreach(var key; keys(hash)){
print(hash[key]);
<nowiki>}</nowiki>
}}

==Extension functions new in FG 2020.1 ==
The following functions have been added to the nasal core library and will be released with FlightGear version 2020.1.
Before the release they are available in the development branch "next".

===isfunc()===
Returns 1 if type or argument is a function, otherwise 0.

===isghost()===
Returns 1 if type or argument is a ghost, otherwise 0.

=== ishash()===
Returns 1 if type or argument is a hash, otherwise 0.

===isint()===
{{Nasal doc
|syntax = isint(x);
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}
|text = Returns 1 if argument has a numeric value and x == floor(x), e.g. integer.
}}

===isnum()===
{{Nasal doc
|syntax = isnum(x);
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}
|text = Returns 1 if typeof(x) is "scalar" and x has a numeric value otherwise 0.
}}

===isscalar()===
{{Nasal doc
|syntax = isscalar(x);
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}
|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 "~".
|example1 = var a = "foo";
var b=42;
if (isscalar(a) and isscalar(b)) print(a~b);
if (isstr(a)) print("a is a string");
if (isint(b)) print("b is an integer");
# if (isscalar(a))... is equivalent to if (typeof(a) == "scalar")...
}}

===isstr()===
Returns 1 if type or argument is a string, otherwise 0.

===isvec()===
Returns 1 if type or argument is a vector, otherwise 0.

===vecindex()===
{{Nasal doc
|syntax = vecindex(vector, value);
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}
|text = Returns the index of value or nil, if value is not found in vector.
|example1=
var myvector = ["apple", "bananna", "coconut"];
# to check if a vector contains a certain value compare vecindex to nil
if (vecindex(myvector, "apple") != nil) {
print("found apple");
}
# WARNING: this will not work as desired because index is 0
if (vecindex(myvector, "apple")) {
print("found apple");
<nowiki>}</nowiki>

}}

==Extension functions new in "dev" version ==
The following functions have been added to the nasal core library curernty on "dev" version.

===member()===
{{Nasal doc
|syntax = member(hash, key);
|source = {{simgear file|simgear/nasal/lib.c|l=796|t=Source}}
|text = The function searches for a key in the given hash, including the <code>parents</code>. If the key is found, its value is returned; otherwise, it returns <code>nil</code>.
|param1 = hash
|param1text = The hash in which the key is searched.
|param2 = key
|param2text = Key as a string whose value we want to return.
|example1 =
var Hash = {
key: 12,
};

member(Hash, 'key'); # return 12
member(Hash, 'missing'); # return nil
|example2 = # member() also includes parents

var Base = {
key: 'text',
};

var Child = {
parents: [Base],
};

member(Child, 'key'); # return 'text'
member(Child, 'missing'); # return nil
}}

===has_member()===
{{Nasal doc
|syntax = has_member(hash, key);
|source = {{simgear file|simgear/nasal/lib.c|l=811|t=Source}}
|text = The function searches for a key in the given hash, including the <code>parents</code>. If the key is found, <code>true</code> is returned, otherwise <code>false</code>.
|param1 = hash
|param1text = The hash in which the key is searched.
|param2 = key
|param2text = Key as a string.
|example1 =
var Hash = {
key: 12,
};

has_member(Hash, 'key'); # return true
has_member(Hash, 'missing'); # return false
|example2 = # has_member() also includes parents

var Base = {
key: 'text',
};

var Child = {
parents: [Base],
};

has_member(Child, 'key'); # return true
has_member(Child, 'missing'); # return false
}}

==Variables==
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}}.

===D2R===
{{Nasal doc
|syntax = var radians = degrees * D2R;
|text = Converts an angle from degrees to radians when multiplied by the angle in degrees. Equal to <code>π / 180</code>.
}}
===FPS2KT===
{{Nasal doc
|syntax = var knots = feet_per_second * FPS2KT;
|text = Converts a velocity from feet per second to knots when multiplied by the velocity in feet per second. Approximately equal to 0.5925.
}}
===FT2M===
{{Nasal doc
|syntax = var metres = feet * FT2M;
|text = Converts a length from feet to metres when multiplied by the length in feet. Equal to 0.3048.
}}
===GAL2L ===
{{Nasal doc
|syntax = var litres = gallons * GAL2L;
|text = Converts a volume from US liquid gallons to litres when multiplied by the volume in gallons. Approximately equal to 3.7854.
}}
===IN2M===
{{Nasal doc
|syntax = var metres = inches * IN2M;
|text = Converts a length from inches to metres when multiplied by the length in inches. Equal to 0.0254.
}}
===KG2LB===
{{Nasal doc
|syntax = var pounds = kilograms * KG2LB;
|text = Converts a mass from kilograms to pounds when multiplied by the mass in kilograms. Approximately equal to 2.2046.
}}
===KT2FPS===
{{Nasal doc
|syntax = var feet_per_second = knots * KT2FPS;
|text = Converts a velocity from knots to feet per second when multiplied by the velocity in knots. Approximately equal to 1.6878.
}}
===KT2MPS===
{{Nasal doc
|syntax = var metres_per_second = knots * KT2MPS;
|text = Converts a velocity from knots to metres per second when multiplied by the velocity in knots. Approximately equal to 0.5144.
}}
===L2GAL===
{{Nasal doc
|syntax = var gallons = litres * L2GAL;
|text = Converts a volume from litres to US liquid gallons when multiplied by the volume in litres. Approximately equal to 0.2642.
}}
===LB2KG===
{{Nasal doc
|syntax = var kilograms = pounds * LB2KG;
|text = Converts a mass from pounds to kilograms when multiplied by the mass in pounds. Approximately equal to 0.4536.
}}
===M2FT ===
{{Nasal doc
|syntax = var feet = metres * M2FT;
|text = Converts a length from metres to feet when multiplied by the length in metres. Approximately equal to 3.2808.
}}
===M2IN===
{{Nasal doc
|syntax = var inches = metres * M2IN;
|text = Converts a length from metres to inches when multiplied by the length in metres. Approximately equal to 39.3701.
}}
===M2NM ===
{{Nasal doc
|syntax = var nautical_miles = metres * M2NM;
|text = Converts a length from metres to nautical miles when multiplied by the length in metres. Approximately equal to 0.00054.
}}
===MPS2KT ===
{{Nasal doc
|syntax = var knots = metres_per_second * MPS2KT;
|text = Converts a velocity from metres per second to knots when multiplied by the velocity in metres per second. Approximately equal to 1.9438.
}}
===NM2M ===
{{Nasal doc
|syntax = var metres = nautical_miles * NM2M;
|text = Converts a length from nautical miles to metres when multiplied by the length in nautical miles. Equal to 1,852.
}}
===R2D===
{{Nasal doc
|syntax = var degrees = radians * R2D;
|text = Converts an angle from radians to degrees when multiplied by the angle in radians. Equal to <code>180 / π</code>.
}}

{{Appendix}}

{{Nasal namespaces}}

Nasal library

2026-01-16T19:37:21Z

PlayeRom: /* has_member() */

{{Nasal Navigation|nocat=1}}
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:
* {{flightgear file|src/Scripting}}
* {{simgear file|simgear/nasal}}

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]].

{{tip|Copy & paste the examples into your [[Nasal Console]] and execute them to see what they do.|width=70%}}

== Core library functions ==
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:
* http://plausible.org/nasal/lib.html ([http://web.archive.org/web/20101010094553/http://plausible.org/nasal/lib.html archive])
* {{simgear file|simgear/nasal/lib.c}} ([http://sourceforge.net/p/flightgear/simgear/ci/next/log/?path=/simgear/nasal/lib.c history])

=== append() ===
{{Nasal doc
|syntax = append(vector, element[, element[, ...]]);
|source = {{simgear file|simgear/nasal/lib.c|l=45|t=Source}}
|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.
|param1 = vector
|param1text = The vector to which the arguments will be appended.
|param2 = element
|param2text = An element to be added to the vector.
|example1 =
var vector = [1, 2, 3]; # Initialize the vector
append(vector, 4); # Append the number 4 to the end of the vector
debug.dump(vector); # Print the contents of the vector
|example2 =
var vector = [1, 2, 3]; # Initialize the vector
append(vector, 4, 5, 6); # Append the numbers 4, 5, and 6 to the end of the vector
debug.dump(vector); # Print the contents of the vector
}}

=== bind() ===
{{Nasal doc
|syntax = bind(function, locals[, outer_scope]);
|source = {{simgear file|simgear/nasal/lib.c|l=638|t=Source}}
|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.
|param1 = function
|param1text = Function to evaluate.
|param2 = locals
|param2text = Hash containing values that will become the namespace (first closure) for the function.
|param3 = outer_scope
|param3text = Optional function which is bound to the next closure. This can be bound to yet another, making a linked list.
|example1 = # This is a namespace/hash with a single member, named "key," which is initialized to 12
var Namespace = {
key: 12
};

# This is different namespace/hash containing a function
# dividing a variable "key" (which is unavailable/nil in this namespace) by 2
var AnotherNamespace = {
ret: func {
key /= 2;
}
};

# To see that key is not available, try to call AnotherNamespace.ret() first
call(AnotherNamespace.ret, [], nil, nil, var errors = []);
if(size(errors)){
print("Key could not be divided/resolved!");
debug.printerror(errors);
}

# Associate the AnotherNamespace.ret() function with the first namespace
# so that "key" is now available
var function = bind(AnotherNamespace.ret, Namespace);

# Invoke the new function
function();

# Print out the value of Namespace.key
# It was changed to 12 from 6 by AnotherNamespace.ret()
print(Namespace.key);
}}

=== call() ===
{{Nasal doc
|syntax = call(func[, args[, me[, locals[, error]]]);
|source = {{simgear file|simgear/nasal/lib.c|l=376|t=Source}}
|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.
|param1 = func
|param1text = Function to execute.
|param2 = args
|param2text = Vector containing arguments to give to the called function.
|param3 = me
|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).
|param4 = locals
|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.
|param5 = error
|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}}.
|example1 =
# prints "Called from call()"
call(func {
print("Called from call()");
});
|example2 =
# prints "a = 1 : b = 2
call(func(a, b){
print("a = ", a, " : b = ", b);
},
[1, 2]
);
|example3 =
var Hash = {
new: func {
var m = { parents: [Hash] };

m.el1 = "string1";
m.el2 = "string2";

return m;
}
};

# prints "me.el1 = string1", then "me.el2 = string2" on the next line
call(func(a, b){
print("me.el", a, " = ", me["el" ~ a]);
print("me.el", b, " = ", me["el" ~ b]);
},
[1, 2],
Hash.new()
);
|example4 =
# prints the value of math.pi
call(func {
print(pi);
}, nil, nil,
math
);
|example5 =
call(func {
print(math.ip); # math.ip doesn't exist
}, nil, nil, nil,
var errs = []
);
debug.printerror(errs); # The error is caught and printed using debug.printerror()
}}

=== caller() ===
{{Nasal doc
|syntax = caller([level]);
|source = {{simgear file|simgear/nasal/lib.c|l=540|t=Source}}
|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 '''[0]''' a hash of local variables, '''[1]''' the function object, '''[2]''' the full source file name (incl. path) and '''[3]''' the line number.
|param1 = level
|param1text = Optional integer specifying the stack level to return a result from. Defaults to 1 (i.e. the caller of the currently executing function).
|example1 =
var myFunction = func(a, b) {
debug.dump(caller(0)[0]); # prints a hash of local variables, including arguments a and b
return 2 * 2;
};

print("2 x 2 = ", myFunction(2, 2));
|example2 =
var get_arg_value = func() {
print("Argument to myFunc = ", caller(1)[0]['a']); # print the value of myFunc's single argument, using caller()
};

var myFunc = func(a) {
get_arg_value();
};

myFunc(3);
|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: true, zindex: nil }</code>.
|example3 =
var MapStructure_selfTest = func() {
var temp = {};
temp.dlg = canvas.Window.new([600, 400], "dialog");
temp.canvas = temp.dlg.createCanvas().setColorBackground(1, 1, 1, 0.5);
temp.root = temp.canvas.createGroup();

var testMap = temp.root.createChild("map");
testMap.setController("Aircraft position");
testMap.setRange(25); # TODO: implement zooming/panning via mouse/wheel here, for lack of buttons :-/
testMap.setTranslation(
temp.canvas.get("view[0]") / 2,
temp.canvas.get("view[1]") / 2,
);

var r = func(name, vis = true, zindex = nil) {
return caller(0)[0];
}

# TODO: we'll need some z-indexing here, right now it's just random
# TODO: use foreach/keys to show all layers in this case by traversing SymbolLayer.registry directly ?
# maybe encode implicit z-indexing for each lcontroller ctor call ? - i.e. preferred above/below order ?
var types = [
r('TFC', false),
r('APT'),
r('DME'),
r('VOR'),
r('NDB'),
r('FIX', false),
r('RTE'),
r('WPT'),
r('FLT'),
r('WXR'),
r('APS'),
];

foreach (var type; types) {
testMap.addLayer(
factory: canvas.SymbolLayer,
type_arg: type.name,
visible: type.vis,
priority: type.zindex,
);
}
}; # MapStructure_selfTest
}}

=== chr() ===
{{Nasal doc
|syntax = chr(code);
|source = {{simgear file|simgear/nasal/lib.c|l=240|t=Source}}
|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.}}
{{{!}} class="wikitable"
! Code !! Name !! Equivalent to
{{!-}}
{{!}} 10 {{!!}} {{Wikipedia|Newline}} {{!!}} <code>\n</code>
{{!-}}
{{!}} 9 {{!!}} {{Wikipedia|Tab key#Tab characters|Horizontal tab}} {{!!}} <code>\t</code>
{{!-}}
{{!}} 13 {{!!}} {{Wikipedia|Carriage return}} {{!!}} <code>\r</code>
{{!}}}
|param1 = code
|param1text = Integer character code for the desired glyph.
|example1 = print("Code 65 = ", chr(65)); # prints "Code 65 = A"
|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.
|example2 =
for(var i = 0; i <= 255; i += 1){
print("Code ", i, " = >", chr(i), "<");
}
}}

=== closure() ===
{{Nasal doc
|syntax = closure(func[, level]);
|source = {{simgear file|simgear/nasal/lib.c|l=557|t=Source}}
|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'''.
|param1 = func
|param1text = Function to evaluate.
|param2 = level
|param2text = Optional integer specifying the scope level. Defaults to 0 (the namespace of '''func''').
|example1 =
var get_math_e = func {
return e; # return the value of math.e
}

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
debug.dump(closure(myFunction)); # print the hash of the namespace "get_math_e"

print(myFunction());
}}

=== cmp() ===
{{Nasal doc
|syntax = cmp(a, b);
|source = {{simgear file|simgear/nasal/lib.c|l=169|t=Source}}
|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'''.
|param1 = a
|param1text = First string argument for comparison.
|param2 = b
|param2text = Second string argument for comparison.
|example1 = print(cmp("1", "two")); # prints -1
|example2 = print(cmp("string", "string")); # prints 0
|example3 = print(cmp("one", "2")); # prints 1
|example4 = print(cmp("string1", "string2")); # prints -1
}}

=== compile() ===
{{Nasal doc
|syntax = compile(code[, filename]);
|source = {{simgear file|simgear/nasal/lib.c|l=349|t=Source}}
|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'''.
|param1 = code
|param1text = String containing Nasal code to be compiled.
|param2 = filename
|param2text = Optional string used for error messages/logging. Defaults to <code><compile></code>
|example1 =
var myCode = 'print("hello");';
var helloFunc = compile(myCode, "myCode");
helloFunc();
|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>.
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<PropertyList>

<nasal><![CDATA[
print("You have FlightGear v", getprop("/sim/version/flightgear"));
]]></nasal>

</PropertyList>
</syntaxhighlight>
Now, start FlightGear and execute this code in the [[Nasal Console]].
|example2 =
# Build the path
var FGRoot = getprop("/sim/fg-root");
var filename = "/gui/dialogs/test.xml";
var path = FGRoot ~ filename;

var blob = io.read_properties(path);
var script = blob.getValues().nasal; # Get the nasal string

# Compile the script. We're passing the filename here for better runtime diagnostics
var code = call(func {
compile(script, filename);
}, nil, nil, var compilation_errors = []);

if(size(compilation_errors)){
die("Error compiling code in: " ~ filename);
}

# Invoke the compiled script, equivalent to code();
# We're using call() here to detect errors:
call(code, [], nil, nil, var runtime_errors = []);

if(size(runtime_errors)){
die("Error calling code compiled loaded from: " ~ filename);
}
|example3text = The <code>compile()</code> function also allows you to parse a JSON string into a hash. Simplest example:
|example3 =
var jsonFunc = compile('{"version":"1.2.0","author":{"name":"John"} }');
var json = jsonFunc(); # return hash
logprint(LOG_ALERT, json["version"]); # print "1.2.0"
logprint(LOG_ALERT, json["author"]["name"]); # print "John"
}}

=== contains() ===
{{Nasal doc
|syntax = contains(hash, key);
|source = {{simgear file|simgear/nasal/lib.c|l=249|t=Source}}
|text = Returns 1 (True) if the hash contains the specified key, or 0 (False) if not.
|param1 = hash
|param1text = The hash to search in.
|param2 = key
|param2text = The scalar to be searched for, contained as a key in the hash.
|example1 =
# Initialize a hash
var hash = {
element: "value"
};
print(contains(hash, "element") ? "Yes" : "No"); # This will print "Yes"
print(contains(hash, "element2") ? "Yes" : "No"); # This will print "No"
}}

===contains()===
{{Requires commit|desc=Vector support|details=see {{Merge-request|project=fgdata|id=305}}|commit=ee39abbd3b70c9b6d5e3a1c4ccedddaac1a92b11|repo=Simgear}}
{{Nasal doc
|syntax = contains(vector, item);
|source = {{simgear file|simgear/nasal/lib.c|l=249|t=Source}}
|text = Returns 1 (True) if the vector contains the specified item, or 0 (False) if not.
|param1 = vector
|param1text = The vector to search in.
|param2 = item
|param2text = The object to be searched for in the vector.
|example1 =
# Initialize a vector
var vec = ["element", "foo"];
print(contains(vec, "element") ? "Yes" : "No"); # This will print "Yes"
print(contains(vec, "element2") ? "Yes" : "No"); # This will print "No"
}}

===delete() ===
{{Nasal doc
|syntax = delete(hash, key);
|source = {{simgear file|simgear/nasal/lib.c|l=118|t=Source}}
|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.
|param1 = hash
|param1text = The hash from which to delete the key.
|param2 = key
|param2text = The scalar to be deleted, contained as a key in the hash.
|example1 =
# Initialize the hash
var hash = {
element1: "value1",
element2: "value2"
};
delete(hash, "element1"); # Delete element1
debug.dump(hash); # prints the hash, which is now minus element1
}}

===die()===
{{Nasal doc
|syntax = die(error);
|source = {{simgear file|simgear/nasal/lib.c|l=417|t=Source}}
|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()}}.
|param1 = error
|param1text = String describing the error.
:{{inote|This parameter is technically optional, but it is highly recommended to use it.}}
|example1 =
print("Will print");
die("Don't go any further!");
print("Won't print"); # Will not be printed because die() stops the process
}}

=== find()===
{{Nasal doc
|syntax = find(needle, haystack);
|source = {{simgear file|simgear/nasal/lib.c|l=586|t=Source}}
|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.
|param1 = needle
|param1text = String to search for.
|param2 = haystack
|param2text = String to search in.
|example1 = print(find("c", "abcdef")); # prints 2
|example2 = print(find("x", "abcdef")); # prints -1
|example3 = print(find("cd", "abcdef")); # prints 2
}}

===ghosttype()===
{{Nasal doc
|syntax = ghosttype(ghost);
|source = {{simgear file|simgear/nasal/lib.c|l=336|t=Source}}
|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.
|param1 = ghost
|param1text = Ghost to return a description for.
|example1 = print(ghosttype(airportinfo())); # prints "airport"
}}

===id()===
{{Nasal doc
|syntax = id(object);
|source = {{simgear file|simgear/nasal/lib.c|l=706|t=Source}}
|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.
|param1 = object
|param1text = Can be either of a string, a vector, a hash, a code, a function, or a ghost.
|example1 = print(id("A")); # prints "str:000000001624A590"
}}

===int() ===
{{Nasal doc
|syntax = int(number);
|source = {{simgear file|simgear/nasal/lib.c|l=125|t=Source}}
|text = Returns the integer part of the numeric value of the single argument, or <code>'''nil'''</code> if none exists.
|param1 = number
|param1text = Number or string with just a number in it to return an integer from.
|example1 = print(int(23)); # prints "23"
|example2 = print(int(23.123)); # prints "23"
|example3 = debug.dump(int("string")); # prints "nil"
}}

===keys()===
{{Nasal doc
|syntax = keys(hash);
|source = {{simgear file|simgear/nasal/lib.c|l=36|t=Source}}
|text = Returns a vector containing the list of keys found in the single hash argument.
|param1 = hash
|param1text = The hash to return the keys from.
|example1 =
# Initialize a hash
var hash = {
element1: "value",
element2: "value"
};
debug.dump(keys(hash)); # print the vector
}}

===left()===
{{Nasal doc
|syntax = left(string, length);
|source = {{simgear file|simgear/nasal/lib.c|l=214|t=Source}}
|version = 2.12
|commit = {{simgear commit|bd7163|t=commit}}
|text = Returns a substring of '''string''', starting from the left.
|param1 = string
|param1text = String to return part of.
|param2 = length
|param2text = Integer specifying the length of the substring to return.
|example1 = print(left("string", 2)); # prints "st"
}}

=== num()===
{{Nasal doc
|syntax = num(number);
|source = {{simgear file|simgear/nasal/lib.c|l=149|t=Source}}
|text = Returns the numerical value of the single string argument, or <code>'''nil'''</code> if none exists.
|param1 = number
|param1text = String with just a number in it to return a number from.
|example1 = print(num("23")); # prints "23"
|example2 = print(num("23.123")); # prints "23.123"
|example3 = debug.dump(num("string")); # prints "nil"
}}

===pop()===
{{Nasal doc
|syntax = pop(vector);
|source = {{simgear file|simgear/nasal/lib.c|l=85|t=Source}}
|text = Removes and returns the last element of the single vector argument, or <code>'''nil'''</code> if the vector is empty.
|param1 = vector
|param1text = Vector to remove an element from.
|example1 =
var vector = [1, 2, 3];
pop(vector);
debug.dump(vector); # prints "[1, 2]"
|example2 =
var vector = [1, 2, 3];
debug.dump(pop(vector)); # prints "3"
|example3 =
var vector = [];
debug.dump(pop(vector)); # prints "nil"
}}

=== range() ===
{{Nasal doc
|syntax = range([start, ]stop[, step]);
|source = {{simgear file|simgear/nasal/lib.c|l=756|t=Source}}
|text = Creates a vector of numbers starting from <code>start</code> (default 0) up to but not including <code>stop</code>, incremented by <code>step</code> (default 1). Note: To specify <code>step</code>, you must also provide <code>start</code>; otherwise the second argument is interpreted as <code>stop</code>.
|param1 = start
|param1text = Optional. The starting number of the sequence. Defaults to 0 if omitted. Required if you want to specify <code>step</code>.
|param2 = stop
|param2text = Required. The number at which to stop the sequence (not included).
|param3 = step
|param3text = Optional. The increment between each number in the sequence. Defaults to 1. Only valid if <code>start</code> is also specified.
|example1 =
var vec = range(5); # Creates a vector [0, 1, 2, 3, 4]
var vec = range(2, 5); # Creates a vector [2, 3, 4]
var vec = range(0, 10, 2); # Creates a vector [0, 2, 4, 6, 8]
var vec = range(0, 0); # Creates an empty vector []
var vec = range(0, 1); # Creates a vector [0]
}}

=== remove() ===
{{Nasal doc
|syntax = remove(vector, value);
|source = {{simgear file|simgear/nasal/lib.c|l=53|t=Source}}
|text = Removes all elements equal to the given value from a vector and returns the modified vector.
|param1 = vector
|param1text = The vector from which elements are to be removed.
|param2 = value
|param2text = A value to remove from the vector.
|example1 =
var vector = [1, 2, 3]; # Initialize the vector.
remove(vector, 2); # Remove the value 2 from the vector.
debug.dump(vector); # Print the contents of the vector: "[1, 3]".
|example2 =
var vector = ["text", "text", "text"]; # Initialize the vector.
remove(vector, "text"); # Remove the value "text" from the vector.
debug.dump(vector); # Print the contents of the vector: "[]".
}}

=== removeat() ===
{{Nasal doc
|syntax = removeat(vector, index);
|source = {{simgear file|simgear/nasal/lib.c|l=72|t=Source}}
|text = Removes the element at the specified index from the vector and returns it.
|param1 = vector
|param1text = The vector from which the element will be removed.
|param2 = index
|param2text = Index of the item to be deleted.
|example1 =
var vector = [1, 2, 3]; # Initialize the vector.
removeat(vector, 0); # Remove the index 0 from the vector.
debug.dump(vector); # Print the contents of the vector: "[2, 3]".
}}

===right()===
{{Nasal doc
|syntax = right(string, length);
|source = {{simgear file|simgear/nasal/lib.c|l=226|t=Source}}
|version = 2.12
|commit = {{simgear commit|bd7163|t=commit}}
|text = Returns a substring of '''string''', starting from the right.
|param1 = string
|param1text = String to return part of.
|param2 = length
|param2text = Integer specifying the length of the substring to return.
|example1 = print(right("string", 2)); # prints "ng"
}}

=== setsize()===
{{Nasal doc
|syntax = setsize(vector, size);
|source = {{simgear file|simgear/nasal/lib.c|l=91|t=Source}}
|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.
|param1 = vector
|param1text = The vector to be operated on.
|param2 = size
|param2text = The desired size of the vector in number of entries.
|example1 =
var vector = [1, 2, 3]; # Initialize a vector
setsize(vector, 4);
debug.dump(vector); # print the vector "[1, 2, 3, nil]"
|example2 =
var vector = [1, 2, 3]; # Initialize a vector
setsize(vector, 2);
debug.dump(vector); # print the vector "[1, 2]"
}}

===size()===
{{Nasal doc
|syntax = size(object);
|source = {{simgear file|simgear/nasal/lib.c|l=26|t=Source}}
|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>.
|param1 = object
|param1text = Object to find the size of. Must be a string, a vector or a hash.
|example1 =
var string = "string";
print(size(string)); # prints "6"
|example2 =
var vector = [1, 2, 3];
print(size(vector)); # prints "3"
|example3 =
var hash = {
element1: "value1",
element2: "value2",
element3: "value3"
};
print(size(hash)); # prints "3"
}}

=== sort()===
{{Nasal doc
|syntax = sort(vector, function);
|source = {{simgear file|simgear/nasal/lib.c|l=678|t=Source}}
|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.
|param1 = vector
|param1text = Input vector to sort.
|param2 = function
|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.
{{{!}} class="wikitable"
! Return value !! Meaning
{{!-}}
{{!}} less than 0 {{!!}} first argument should go before second argument
{{!-}}
{{!}} 0 {{!!}} first argument equals second argument
{{!-}}
{{!}} greater than 0 {{!!}} first argument should go after second argument
{{!}}}

|example1text = This example sorts elements from smallest to greatest.
|example1 =
var sort_rules = func(a, b) {
if (a < b) {
return -1; # A should before b in the returned vector
} elsif (a == b) {
return 0; # A is equivalent to b
} else {
return 1; # A should after b in the returned vector
}
}
debug.dump(sort([3, 2, 5, 6, 4, 1], sort_rules)); # prints "[1, 2, 3, 4, 5, 6]"
|example2text = This example sorts elements from greatest to smallest.
|example2 =
# Outputs the elements in reverse order (greatest to smallest)
var sort_rules = func(a, b) {
if (a < b) {
return 1; # -1 in the above example
} elsif (a == b) {
return 0;
} else {
return -1; # 1 in the above example
}
}
debug.dump(sort([3, 2, 5, 6, 4, 1], sort_rules)); # prints "[6, 5, 4, 3, 2, 1]"
|example3text = This example sorts a vector of strings (runways for example) from smallest to greatest.
|example3 =
var runways = ["09R", "27R", "26L", "09L", "15"];
var rwy = sort(runways, func(a, b) cmp(a, b));
debug.dump(rwy); # prints ['09L', '09R', '15', '26L', '27R']
}}

=== split()===
{{Nasal doc
|syntax = split(delimiter, string);
|source = {{simgear file|simgear/nasal/lib.c|l=596|t=Source}}
|text = Splits the input string into a vector of substrings bounded by occurrences of the delimiter substring. See [[Nasal_library/string#string.join(sep,list)|string.join()]].
|param1 = delimiter
|param1text = String that will split the substrings in the returned vector.
|param2 = string
|param2text = String to split up.
|example1 = debug.dump(split("cd", "abcdef")); # prints "['ab', 'ef']"
|example2 = debug.dump(split(".", "3.2.0")); # prints "[3, 2, 0]"
|example3 = debug.dump(split("/", "path/to/file")); # prints "['path', 'to', 'file']"
}}

===sprintf()===
{{Nasal doc
|syntax = <nowiki>sprintf(format[, arg[, arg, [...]]]);</nowiki>
|source = {{simgear file|simgear/nasal/lib.c|l=491|t=Source}}
|text = Creates and returns a string formatted using ANSI C {{func link|vsnprintf()|link=http://en.cppreference.com/w/c/io/vfprintf}} <ref>
{{Cite web
|url = http://sourceforge.net/p/flightgear/simgear/ci/next/tree/simgear/nasal/lib.c#l308
|title = fgdata/simgear/simgear/nasal/lib.c, line 308
|accessdate = October 2015
}}
</ref>. Below is a table of supported format specifiers.
{{{!}} class="wikitable" width="75%"
{{!}}+ %[flags][width][.precision]specifier
! colspan="2" {{!}} Flags
{{!-}}
! Flag !! Output
{{!-}}
{{!}} <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.
{{!-}}
{{!}} ''space'' {{!!}} Prefixes non-signed numbers with a space.
{{!-}}
{{!}} <code>-</code> {{!!}} Left-align the output of this placeholder (the default is to right-align the output) when the width option is specified.
{{!-}}
{{!}} <code>0</code> {{!!}} Use 0 instead of spaces to pad a field when the width option is specified.
{{!-}}
{{!}} <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.
{{!-}}
! colspan="2" {{!}} Width
{{!-}}
{{!}} 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.
{{!-}}
! colspan="2" {{!}} Precision
{{!-}}
{{!}} colspan="2" {{!}} Integer preceded by a dot specifying the number of decimal places to be written.
{{!-}}
! colspan="2" {{!}} Specifiers
{{!-}}
! Specifier !! Output
{{!-}}
{{!}} <code>d</code>, <code>i</code> {{!!}} Signed decimal number.
{{!-}}
{{!}} <code>s</code> {{!!}} A string
{{!-}}
{{!}} <code>%</code> {{!!}} Percent (%) character.
{{!-}}
{{!}} <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.
{{!-}}
{{!}} <code>o</code> {{!!}} Unsigned integer as an octal number.
{{!-}}
{{!}} <code>u</code> {{!!}} Unsigned decimal integer.
{{!-}}
{{!}} <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.
{{!-}}
{{!}} <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.
{{!-}}
{{!}} <code>f</code> {{!!}} Floating-point number, in fixed decimal notation, by default with 6 decimal places.
{{!-}}
{{!}} <code>F</code> {{!!}} Appears to be available<ref>
{{Cite web
|url = http://sourceforge.net/p/flightgear/simgear/ci/next/tree/simgear/nasal/lib.c#l389
|title = fgdata/simgear/simgear/nasal/lib.c, line 389
|accessdate = October 2015
}}
</ref>, but doesn't work.
{{!-}}
{{!}} <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.
{{!}}}

|param1 = format
|param1text = String specifying the format. Can be used with or without a format specifiers. See below for examples.
|param2 = arg
|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.

|example1 = print(sprintf("%i", 54)); # prints "54"
|example2 = print(sprintf("Pi = %+.10f", math.pi)); # prints "Pi = +3.1415926536"
|example3 =
print(sprintf("%6d", 23)); # prints " 23"
print(sprintf("%06d", 23)); # prints "000023"
|example4 =
var FGVer = getprop("/sim/version/flightgear");
print(sprintf("You have FlightGear v%s", FGVer)); # prints "You have FlightGear v<your version>"
|example5 =
print(sprintf("Hexadecimal 100000 = %X", 100000)); # prints "Hexadecimal 100000 = 186A0"
print(sprintf("Hexadecimal 100000 = %x", 100000)); # prints "Hexadecimal 100000 = 186a0"
|example6 = print(sprintf("Code 65 is %c", 65)); # prints "Code 65 is A"
|example7 =
print(sprintf("%e", 54)); # prints "5.400000e+001"
print(sprintf("%E", 54)); # prints "5.400000E+001"
|example8 = print(sprintf("%o", 54)); # prints "66"
|example9 = print(sprintf("50%% of 100 is %i", 100 / 2)); # prints "50% of 100 is 50"
|example10 =
print(sprintf("%.2f", 1.4)); # prints "1.40"
print(sprintf("%.1f", 1.4)); # prints "1.4"
print(sprintf("% 4.1f", 1.4)); # prints " 1.4"
print(sprintf("%04.1f", 1.4)); # prints "01.4"
print(sprintf("% 6.1f", 1.4)); # prints " 1.4"
print(sprintf("%06.1f", 1.4)); # prints "0001.4"
}}

===str()===
{{Nasal doc
|syntax = str(value);
|source = {{simgear file|simgear/nasal/lib.c|l=186|t=Source}}
|text = Convert given value (scalar) to string. If <code>value</code> is a number, it will be converted to a string. If <code>value</code> is a string, the same string will be returned. If <code>value</code> is not a scalar (hash, vector, nil), <code>nil</code> will be returned.
|param1 = value
|param1text = The value to convert to string.
|example1 =
var result = str(true); # result is a string "1"
var result = str(false); # result is a string "0"
var result = str(12); # result is a string "12"
var result = str(12.5); # result is a string "12.5"
var result = str(-12.5); # result is a string "-12.5"
var result = str("12.5"); # result is a string "12.5"
var result = str([1, 2]); # result is a nil
var result = str({ x: 0 }); # result is a nil
var result = str(nil); # result is a nil
}}

===streq()===
{{Nasal doc
|syntax = streq(a, b);
|source = {{simgear file|simgear/nasal/lib.c|l=164|t=Source}}
|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.}}
|param1 = a
|param1text = First argument for testing equality.
|param2 = b
|param2text = Second argument for testing equality.
|example1 = print(streq("0", "0")); # prints "1" (True)
|example2 =
print(0 == 0.0); # prints "1" (True)
print(streq("0", "0.0")); # prints "0" (False)
}}

===substr()===
{{Nasal doc
|syntax = substr(string, start [, length]);
|source = {{simgear file|simgear/nasal/lib.c|l=194|t=Source}}
|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).
|param1 = string
|param1text = String to return a substring from.
|param2 = start
|param2text = Integer specifying the start of a substring. Negative values specify a position from the end of the string.
|param3 = length
|param3text = Optional argument specifying the length of the substring. Defaults to the end of the string.
|example1 = print(substr("abcde", 1, 3)); # prints "bcd"
|example2 = print(substr("abcde", 1)); # prints "bcde"
|example3 = print(substr("abcde", 2, 1)); # prints "c"
|example4 = print(substr("abcde", -2)); # prints "de"
|example5 = print(substr("abcde", -3, 2)); # prints "cd"
}}

===subvec()===
{{Nasal doc
|syntax = subvec(vector, start[, length]);
|source = {{simgear file|simgear/nasal/lib.c|l=98|t=Source}}
|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).
|param1 = vector
|param1text = The vector to take the sub-vector from.
|param2 = start
|param2text = The starting point of the sub-vector within the given vector.
|param3 = length
|param3text = Optional argument specifying the length of the sub-vector, from the starting point.
'''Notes:'''
* Omitting the ''vector'' and ''start'' arguments is not an error (possibly it should be) but the return value is ''nil''.
* A negative ''start'' argument ''is'' an error. This seems wrong. Perhaps the language designer could comment.
* A value of ''start'' greater than ''size(vector)'' causes an error. A value equal to ''size(vector)'' returns an empty vector.
* 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.
|example1 =
var vector = [1, 2, 3];
debug.dump(subvec(vector, 0)); # prints "[1, 2, 3]"
|example2 =
var vector = [1, 2, 3];
debug.dump(subvec(vector, 1)); # prints "[2, 3]"
|example3 =
var vector = [1, 2, 3];
debug.dump(subvec(vector, 1, 1)); # prints "[2]"
}}

=== typeof()===
{{Nasal doc
|syntax = typeof(object);
|source = {{simgear file|simgear/nasal/lib.c|l=287|t=Source}}
|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.
|param1 = object
|param1text = Object to return the type of.
|example1 =
var object = nil;
print(typeof(object)); # prints "nil"
|example2 =
var object = "Hello world!";
print(typeof(object)); # prints "scalar"
|example3 =
var object = math.pi;
print(typeof(object)); # prints "scalar"
|example4 =
var object = [1, 2, 3];
print(typeof(object)); # prints "vector"
|example5 =
var object = {};
print(typeof(object)); # prints "hash"
|example6 =
var object = func {};
print(typeof(object)); # prints "func"
|example7 =
var object = airportinfo();
print(typeof(object)); # prints "ghost"
}}



==Extension functions==
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:
*{{flightgear file|src/Scripting/NasalPositioned.cxx}}
*{{flightgear file|src/Scripting/NasalSys.cxx}}
*{{fgdata file|Nasal/globals.nas}}

===abort()===
{{Nasal doc
|syntax = abort();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=565|t=Source}}
|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).
|example1text = This example will immediately stop FlightGear with an error, such as "FlightGear has stopped working."
|example1 = abort();
|example2text = For exiting FlightGear in a better way, please use the following code:
|example2 = fgcommand("exit");
}}

=== abs() ===
{{Nasal doc
|syntax = abs(number);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = This simple function returns the {{wikipedia|absolute value|noicon=1}} of the provided number.
|param1 = number
|param1text = This argument is required and should be a number.
|example1 = print(abs(1)); # prints "1"
|example2 = print(abs(-1)); # prints "1"
}}

===aircraftToCart() ===
This new function in FG 2017.2.1 takes coordinates in aircraft structural coordinate system, and translate them into geocentric coordinates.
Example for (5,6,7):
<syntaxhighlight lang="nasal">
var pos = aircraftToCart({x: -5, y: 6, z: -7});
var coord = geo.Coord.new();
coord.set_xyz(pos.x, pos.y, pos.z);
</syntaxhighlight>
Notice: x and z is inverted sign on purpose.
if you want lat. lon, alt from that, just call: (degrees and meters)

<syntaxhighlight lang="nasal">
coord.lat()
coord.lon()
coord.alt()
</syntaxhighlight>

===addcommand() ===
{{Nasal doc
|syntax = addcommand(name, code);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=659|t=Source}}
|version = 2.12
|commit = {{flightgear commit|7b663c|t=commit}}
|text = {{see also|Howto:Add new fgcommands to FlightGear}}

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.
|param1 = name
|param1text = This will become the name of the new fgcommand. Must be a string.
|param2 = code
|param2text = The code that will be executed when the fgcommand is run. Must be a function.
|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.
|example1 = addcommand("myFGCmd", func(node) {
print("fgcommand 'myFGCmd' has been run.");
props.dump( node );
});
fgcommand("myFGCmd", props.Node.new({foo:1, bar:2}) );
|example2text = This example demonstrates how parameters are defined in a new fgcommand.
|example2 = addcommand("myFGCmd", func(node){
print(node.getNode("number").getValue()); # prints the value of "number," which is 12
});
fgcommand("myFGCmd", props.Node.new({"number": 12}));
}}

===airportinfo()===
{{Nasal doc
|syntax = airportinfo();
airportinfo(type);
airportinfo(id);
airportinfo(lat, lon[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1024|t=Source}}
|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:
* '''parents''': A vector containing a hash of various functions to access information about the runway. These functions are:
** '''findBestRunwayForPos()''' return runway as ghost by given geo position, e.g. <code>var rwy = airportinfo().findBestRunwayForPos(geo.aircraft_position());</code>.
** '''runway()''' return runway as ghost by runway ID, e.g. <code>var rwy = airportinfo().runway("18R");</code>.
** '''runwaysWithoutReciprocals()''' return vector of runways as ghost.
** '''helipad()''' return helipad as ghost by helipad ID, e.g. <code>var heli = airportinfo().helipad("H19");</code>.
** '''tower()''' return hash with <code>lat</code>, <code>lon</code>, <code>elevation</code> fields.
** '''comms()''' return vector of hashes, each hash with <code>frequency</code> and <code>ident</code> fields.
** '''sids()''' return vector of strings with SID IDs.
** '''stars()''' return vector of strings with STAR IDs.
** '''getApproachList()''' return vector of string with approaches.
** '''parking()''' return vector of hashes, each hash with <code>lat</code>, <code>lon</code>, <code>elevation</code>, <code>name</code> fields.
** '''getSid()''' return SID as ghost, e.g. <code>var sid = airportinfo().getSid("SA1A");</code>.
** '''getStar()''' return STAR as ghost, e.g. <code>var star = airportinfo().getStar("KEILA1");</code>.
** '''getIAP()''' return IAP as ghost, e.g. <code>var iap = airportinfo().getIAP("ILS02");</code>.
** '''getApproach()''' return approach as ghost, e.g. <code>var approach = airportinfo().getApproach("ILS02");</code>.
** '''tostring()''' just return string "an airport ICAO".
** See also {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1902}}.
* '''lon''': Longitude of the location.
* '''lat''': Latitude of the location.
* '''has_metar''': True or false depending whether the airport has a [[METAR]] code defined for it.
* '''elevation''': Elevation of the location in metres.
* '''id''': ICAO code of the airport (or ID of the seaplane base/heliport).
* '''name''': Name of the airport/heliport/seaplane base.
* '''runways'''
** '''<runway name>'''
*** '''id''': Name of runway.
*** '''lat''': Latitude of the runway.
*** '''lon''': Longitude of the runway.
*** '''heading''': True heading of the runway.
*** '''length''': Length of the runway in metres.
*** '''width''': Width of the runway in metres.
*** '''surface''': Runway surface type.
*** '''threshold''': Length of the runway's {{wikipedia|displaced threshold}} in metres. Will return 0 if there is none.
*** '''stopway''': Length of the runway's stopway (the area before the threshold) in metres. Will return 0 if there is none.
*** '''reciprocal''': <code>runway</code> ghost of the reciprocal runway.
*** '''ils_frequency_mhz''': ILS frequency in megahertz.
*** '''ils''': <code>navaid</code> ghost of the ILS transmitter.
* '''helipads'''
** '''<helipad name>'''
*** '''id''': Name of helipad.
*** '''lat''': Latitude of the helipad.
*** '''lon''': Longitude of the helipad.
*** '''heading''': True heading of the helipad.
*** '''length''': Length of the helipad in metres.
*** '''width''': Width of the helipad in metres.
*** '''surface''': Helipad surface type.
* '''taxiways'''
** '''<taxiway name>'''
*** '''id''': Name of taxiway.
*** '''lat''': Latitude of the taxiway.
*** '''lon''': Longitude of the taxiway.
*** '''heading''': Heading of the taxiway.
*** '''length''': Length of the taxiway in metres.
*** '''width''': Width of the taxiway in metres.
*** '''surface''': Taxiway surface type.

Information is extracted in the same way as accessing members of a Nasal hash. For example:
<syntaxhighlight lang="nasal">
# prints to lengths of the runways of the nearest airport in feet and metres
var info = airportinfo();
print("-- Lengths of the runways at ", info.name, " (", info.id, ") --");
foreach(var rwy; keys(info.runways)){
print(rwy, ": ", math.round(info.runways[rwy].length * M2FT), " ft (", info.runways[rwy].length, " m)");
}
</syntaxhighlight>

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.
|param1 = id
|param1text = The {{wikipedia|International Civil Aviation Organization airport code|ICAO code|noicon=1}} of an airport to retrieve information about.
|param2 = type
|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).
: {{inote|Running this function without any parameters is equivalent to this:
: <syntaxhighlight lang="nasal">
airportinfo("airport");
</syntaxhighlight>
}}
|param3 = lat ''and'' lon
|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.
|example1 = var info = airportinfo();
print("Nearest airport: ", info.name, " (", info.id, ")"); # prints the name and ICAO code of the nearest airport
|example2 = var info = airportinfo("heliport");
print("Elevation of the nearest heliport: ", math.round(info.elevation * M2FT), " ft"); # prints the elevation and name of the nearest heliport
|example3 = var info = airportinfo("KSQL");
print("-- Runways of ", info.name, " (", info.id, "): --");
foreach(var rwy; keys(info.runways)) {
print(rwy); # prints the runways of KSQL
}
|example4 = var info = airportinfo(37.81909385, -122.4722484);
print("Coordinates of the nearest airport: ", info.lat, ", ", info.lon); # print the name and ICAO of the nearest airport to the Golden Gate Bridge
|example5 = var info = airportinfo(37.81909385, -122.4722484, "seaport");
print("Nearest seaplane base: ", info.name, " (", info.id, ")"); # print the name and ID of the nearest seaplane base to the Golden Gate Bridge
|example6text = This example prints the all information from an <code>airportinfo()</code> call.
|example6 = var info = airportinfo("KSFO");
print(info.name);
print(info.id);
print(info.lat);
print(info.lon);
print(info.has_metar);
print(info.elevation);
foreach(var rwy; keys(info.runways)){
print("-- ", rwy, " --");
print(info.runways[rwy].lat);
print(info.runways[rwy].lon);
print(info.runways[rwy].length);
print(info.runways[rwy].width);
print(info.runways[rwy].heading);
print(info.runways[rwy].stopway);
print(info.runways[rwy].threshold);
<nowiki>}</nowiki>
}}

===airwaysRoute() ===
{{Nasal doc
|syntax = airwaysRoute(start, end[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1933|t=Source}}
|text = {{see also|Nasal Flightplan}}
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.
|param1 = start
|param1text = Start waypoint, in the form of a waypoint ghost, such as that provided by {{func link|flightplan()}}.
|param2 = end
|param2text = Same as above.
|param3 = type
|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."
|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.
|example1 = var fp = flightplan();
var start = fp.getWP(0);
var end = fp.getWP(fp.getPlanSize() - 1);
var rt = airwaysRoute(start, end);
foreach(var wp; rt){
print(wp.wp_name); # print the waypoints in the computed route
}
|example2text = Exactly the same as above, but computes a low level path.
|example2 = var fp = flightplan();
var start = fp.getWP(0);
var end = fp.getWP(fp.getPlanSize() - 1);
var rt = airwaysRoute(start, end, "lowlevel");
foreach(var wp; rt){
print(wp.wp_name); # print the waypoints in the computed route
<nowiki>}</nowiki>
}}

===airway()===

{{Nasal doc
|syntax = airway(ident [, pos]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2644|t=Source}}
|text = {{see also|Nasal Flightplan}}
This function returns a ghost containing an airway of a specified id.
|param1 = ident
|param1text = a Positioned ghost (leg, navaid, airport) and so on, passed to the search function.
|param2 = pos
}}

===assert()===
{{Nasal doc
|syntax = assert(condition[, message]);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|version = 3.2
|commit = {{fgdata commit|8b16a7|t=commit}}
|text = Returns either true if the condition evaluates as true, or aborts with a {{func link|die()}} call, which can be customised.
|param1 = condition
|param1text = Condition to evaluate.
|param2 = message
|param2text = Optional message that will be used in any {{func link|die()}} call. Defaults to "assertion failed!"
|example1 = var a = 1;
var b = 2;
print(assert(a < b)); # prints "1" (true)
|example2 = var a = 1;
var b = 2;
assert(a > b, 'a is not greater than b'); # aborts with a custom error message
}}

===carttogeod()===
{{Nasal doc
|syntax = carttogeod(x, y, z);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=945|t=Source}}
|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>
|param1 = x
|param1text = Mandatory x-axis value, in metres.
|param2 = y
|param2text = Mandatory y-axis value, in metres.
|param3 = z
|param3text = Mandatory z-axis value, in metres.
|example1 = var (lat, lon, alt) = carttogeod(6378137, 0, 0); # point is the intersection of the prime meridian and equator.
print("Latitude: ", lat); # prints lat, lon and alt, which are all zero, see above
print("Longitude: ", lon);
print("Altitude: ", alt);
}}

===cmdarg()===
{{Nasal doc
|private = _cmdarg()
|syntax = cmdarg();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=513|t=Part 1}} {{!}} {{fgdata file|Nasal/globals.nas|t=Part 2}}
|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.
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:
* Bindings: This is needed so that the value of a joystick's axis can be accessed internally.
* 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).
* 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.
* 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>

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.

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.
|example1 = fgcommand("dialog-show", {"dialog-name": "cmdarg-demo"});
|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.
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>

<PropertyList>

<name>cmdarg-demo</name>
<layout>vbox</layout>

<text>
<label>Click "Close" to activate the demonstration (a message in the console).</label>
</text>

<button>
<legend>Close</legend>
<binding>
<command>nasal</command>
<script>print("Button binding root: '" ~ cmdarg().getPath() ~ "'");</script>
</binding>
<binding>
<command>dialog-close</command>
</binding>
</button>

</PropertyList>
</syntaxhighlight>
|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!"
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>

<PropertyList>

<name>cmdarg-demo</name>
<layout>vbox</layout>

<text>
<label>Click "Click me!" to activate the demonstration (the button's label will change).</label>
</text>

<button>
<legend>Click me!</legend>
<binding>
<command>nasal</command>
<script>change_label();</script>
</binding>
</button>

<button>
<legend>Close</legend>
<binding>
<command>dialog-close</command>
</binding>
</button>

<nasal>
<open><![CDATA[
var dlg_root = cmdarg();
var dlg_name = {"dialog-name": "cmdarg-demo"};
var change_label = func {
dlg_root.getNode("button[0]/legend").setValue("I've been changed!");
fgcommand("dialog-close", dlg_name);
fgcommand("dialog-show", dlg_name);
}
]]></open>
</nasal>

</PropertyList>
</syntaxhighlight>
|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]].
}}

===courseAndDistance()===
{{Nasal doc
|syntax = courseAndDistance(to);
courseAndDistance(from, to);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1668|t=Source}}
|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:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object with geodetic coordinates (cartesian coordinates will not be accepted)
|param1 = from
|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.
|param2 = to
|param2text = Like the first parameter, but defines the second point.
|example1text = This example demonstrates the usage of the function with the <code>airport</code> ghost type.
|example1 = var from = airportinfo("KSFO");
var to = airportinfo("KSQL");
var (course, dist) = courseAndDistance(from, to);
print(course); # prints course from KSFO to KSQL
print(dist); # prints distance in nm from KSFO to KSQL
|example2text = This example demonstrates the usage of the function with hashes containing ''lat'' and ''lon''.
|example2 = var from = {lat: 0, lon: 0};
var to = {lat: 1, lon: 1};
var (course, dist) = courseAndDistance(from, to);
print(course);
print(dist);
|example3text = This example demonstrates usage of a geo.Coord object.
|example3 = var from = geo.Coord.new().set_latlon(0, 0);
var to = geo.Coord.new().set_latlon(1, 1);
var (course, dist) = courseAndDistance(from, to);
print(course);
print(dist);
|example4text = This example demonstrates usage of differing parameter types.
|example4 = var from = airportinfo("KSFO");
var to = geo.Coord.new().set_latlon(0, 0);
var (course, dist) = courseAndDistance(from, to);
print(course);
print(dist);
|example5text = The same as above, but the other way round.
|example5 = var to = {lat: 1, lon: 1};
var (course, dist) = courseAndDistance(0, 0, to);
print(course);
print(dist);
|example6text = Usage of just one parameter.
|example6 = var dest = airportinfo("KSQL");
var (course, dist) = courseAndDistance(dest);
print("Turn to heading ", math.round(course), ". You have ", sprintf("%.2f", dist), " nm to go");
}}

===createFlightplan()===
{{Nasal doc
|syntax = createFlightplan(path);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2331|t=Source}}
|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.
|param1 = path
|param1text = Optional parameter defining the file from which a flightplan will be populated.
|example1 =
var path = getprop("/sim/fg-home") ~ "/Export/test.fgfp";
var flightplan = createFlightplan(path);
debug.dump(flightplan);
}}

===createDiscontinuity()===
{{Nasal doc
|syntax = createDiscontinuity();
|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.
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2045|t=Source}}
|version = 2016.1
|commit = {{flightgear commit|caead6|t=commit}}
}}
===createViaTo()===
{{Nasal doc
|syntax = createViaTo(airway, waypoint);
|text = Returns a <code>waypoint</code> ghost object. It represents a route "via '''airway''' to '''waypoint'''".
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2009|t=Source}}
|version = 2016.1
|commit = {{flightgear commit|caead6|t=commit}}
|param1 = airway
|param1text = The name of an airway.
|param2 = waypoint
|param2text = Must be in the airway and one of:
* The name of a waypoint.
* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, or <code>fix</code> ghost object.
}}
===createWP()===
{{Nasal doc
|syntax = createWP(pos, name[, flag]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1964|t=Source}}
|text = Creates a new waypoint ghost object.
|param1 = pos
|param1text = Dictates the position of the new waypoint. It can be one of the following:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. See example 4 below.
|param2 = name
|param2text = String that will become the name of the new waypoint.
|param3 = flag
|param3text = Optional string that will tell FlightGear what type of waypoint it is. Must be one of "sid," "star," "approach," "missed," or "pseudo."
|example1text = Creates a waypoint directly in front and 1 km away and appends it to the flight plan.
|example1 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);
var wp = createWP(pos, "NEWWP");
var fp = flightplan();
fp.appendWP(wp);
|example2 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);
var wp = createWP({lat: pos.lat(), lon: pos.lon()}, "NEWWP");
var fp = flightplan();
fp.appendWP(wp);
|example3 = var apt = airportinfo();
var wp = createWP(apt, "NEWWP");
var fp = flightplan();
fp.appendWP(wp);
|example4 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);
var wp = createWP(pos.lat(), pos.lon(), "NEWWP");
var fp = flightplan();
fp.appendWP(wp);
|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.
|example5 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);
var wp = createWP(pos, "NEWWP", "pseudo");
var fp = flightplan();
fp.appendWP(wp);
print(fp.getPlanSize());
fp.clearWPType("pseudo");
print(fp.getPlanSize());
}}

===createWPFrom()===
{{Nasal doc
|syntax = createWPFrom(object[, flag]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1989|t=Source}}
|text = Creates a new waypoint object from another object.
|param1 = object
|param1text = A ghost object. Must be a ghost type that is one of "airport," "navaid," "runway," or "fix."
|param2 = flag
|param2text = Optional string that will tell FlightGear what type of waypoint it is. Must be one of "sid," "star," "approach," "missed," or "pseudo."
|example1text = Creates a new waypoint and appends it to the flight plan.
|example1 = var apt = airportinfo("KSFO");
var wp = createWPFrom(apt);
var fp = flightplan();
fp.appendWP(wp);
|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.
|example2 = var apt = airportinfo("KSFO");
var wp = createWPFrom(apt, "pseudo");
print(wp.wp_name);
var fp = flightplan();
fp.appendWP(wp);
print(fp.getPlanSize());
fp.clearWPType("pseudo");
print(fp.getPlanSize());
}}

===defined()===
{{Nasal doc
|syntax = defined(symbol);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = Returns 1 (true) or 0 (false) depending on whether a variable exists.
|param1 = symbol
|param1text = A string that will be what the function searches for.
|example1 = var number = 12;
var check_exist = func {
print("Variable 'number' ", defined("number") == 1 ? "exists" : "does not exist"); # 'number' does exist
print("Variable 'number2' ", defined("number2") == 1 ? "exists" : "does not exist"); # 'number2' does not exist
}
check_exist();
}}

===directory()===
{{Nasal doc
|syntax = directory(path);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=572|t=Source}}
|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.
{{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.}}
|param1 = path
|param1text = Absolute file path.
|example1text = Gets the folders and files in [[$FG_ROOT]], and then removes the extra first two elements (see note above).
|example1 = var dir = directory(getprop("/sim/fg-root")); # get directory
dir = subvec(dir, 2); # strips off the first two elements
debug.dump(dir); # dump the vector
}}

===fgcommand()===
{{Nasal doc
|syntax = fgcommand(cmd[, args]);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=456|t=Part 1}} {{!}} {{fgdata file|Nasal/globals.nas|t=Part 2}}
|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.
|param1 = cmd
|param1text = String that is the name of the command that is to be run.
|param2 = args
|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).
|example1 = fgcommand("null"); # does nothing
|example2 = var args = props.Node.new({'script': 'print("Running fgcommand");'});
if (fgcommand("nasal", args)) { # prints "Running fgcommand" and then one of these print statements
print("Fgcommand succeeded");
} else {
print("Fgcommand encountered a problem");
}
|example3 = var args = { 'dialog-name': 'about' };
fgcommand("dialog-show", args); # shows the 'about' dialog
}}

===findAirportsByICAO() ===
{{Nasal doc
|syntax = findAirportsByICAO(search[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1096|t=Source}}
|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.
|param1 = search
|param1text = Search string for the function. Can either be a partial or a full ICAO code.
:{{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.}}
|param2 = type
|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."
|example1 = var apts = findAirportsByICAO("KSF"); # finds all airports matching "KSF"
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")"); # prints them
}
|example2 = var apts = findAirportsByICAO("SP0", "seaport"); # finds all seaplane bases matching "SP0"
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")"); # prints them
}
|example3 = var apt = findAirportsByICAO("XBET"); # one way to check if an airport does exist"
if (size(apt) == 0) {
print("Airport does not exist"); # this one will be printed
} else {
print("Airport does exist");
<nowiki>}</nowiki>
}}

===findAirportsWithinRange()===
{{Nasal doc
|syntax = findAirportsWithinRange([pos, ]range[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1066|t=Source}}
|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.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findAirportsWithinRange(lat, lon, range, type);</code>.
|param2 = range
|param2text = Mandatory number giving the range in nautical miles within which to search for airports/heliports/seaplane bases.only airports are searched for.
|param3 = type
|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."
|example1text = Searches for airports within 10 nm of [[KSFO]].
|example1 = var pos = airportinfo("KSFO");
var apts = findAirportsWithinRange(pos, 10);
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")");
}
|example2text = Searches for seaplane bases within 15 nm of [[KSFO]].
|example2 = var pos = airportinfo("KSFO");
var apts = findAirportsWithinRange(pos, 15, "seaport");
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")");
}
|example3text = Searches for airports within 10 nm of your current position.
|example3 = var apts = findAirportsWithinRange(10);
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")");
<nowiki>}</nowiki>
}}

===findCommByFrequencyMHz()===
findCommByFrequencyMHz([pos, ]freq[, type]);
[[sourceforge:p/flightgear/flightgear/ci/next/tree/src/Scripting/NasalPositioned.cxx#l1547|source]]

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.

'''pos'''

: Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findCommByFrequencyMHz(lat, lon, freq, type);</code>.
; freq
: Frequency, in megahertz, of the station to search for.
; type
: 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)
'''Example'''
var com = findCommByFrequencyMHz(123.6);
print("ID: ", com.id); # prints info about the comm station
print("Name: ", com.name);
print("Latitude: ", com.lat);
print("Longitude: ", com.lon);
print("Type: ", com.type);
print("Frequency: ", sprintf("%.3f", com.frequency), " Mhz");

=== findFixesByID() ===
{{Nasal doc
|syntax = findFixesByID([pos, ]id);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1627|t=Source}}
|text = Returns a vector containing <code>fix</code> ghost objects matching a given ID, sorted by range from a certain position.
{{inote|Fixes are (usually) also known as waypoints.}}
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findFixesByID(lat, lon, id);</code>.
|param2 = id
|param2text = Full or partial ID of the fix to search for.
:{{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.}}
|example1 = var fixes = findFixesByID("POGIC");
foreach(var fix; fixes){
print(fix.id, " - lat: ", fix.lat, " {{!}} lon: ", fix.lon); # prints information about POGIC
}
|example2 = var fix = findFixesByID("ZUNAP");
fix = fix[0];
var (course, dist) = courseAndDistance(fix);
print("Turn to heading ", math.round(course), ". You have ", sprintf("%.2f", dist), " nm to go to reach ", fixes[0].id);
}}

===findNavaidByFrequencyMHz()===
{{Nasal doc
|syntax = findNavaidByFrequencyMHz([pos, ]freq[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1547|t=Source}}
|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.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidByFrequencyMHz(lat, lon, freq, type);</code>.
|param2 = freq
|param2text = Frequency, in megahertz, of the navaid to search for.
|param3 = type
|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}}.
|example1 = var navaid = findNavaidByFrequencyMHz(109.55);
print("ID: ", navaid.id); # prints info about the navaid
print("Name: ", navaid.name);
print("Latitude: ", navaid.lat);
print("Longitude: ", navaid.lon);
print("Elevation (AMSL): ", navaid.elevation, " m");
print("Type: ", navaid.type);
print("Frequency: ", sprintf("%.3f", navaid.frequency / 100), " Mhz");
print("Range: ", navaid.range_nm, " nm");
if(navaid.course) print("Course: ", navaid.course);
}}

=== findNavaidsByFrequencyMHz()===
{{Nasal doc
|syntax = findNavaidsByFrequencyMHz([pos, ]freq[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1572|t=Source}}
|text = Returns a vector conatining <code>navaid</code> ghost objects for navaids that match a given frequency, sorted from nearest to furthest.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidsByFrequencyMHz(lat, lon, freq, type);</code>.
|param2 = freq
|param2text = Frequency, in megahertz, of the navaid to search for.
|param3 = type
|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}}.
|example1 = var navaids = findNavaidsByFrequencyMHz(109.55);
foreach(var navaid; navaids){
print("--");
print("ID: ", navaid.id); # prints info about the navaid
print("Name: ", navaid.name);
print("Latitude: ", navaid.lat);
print("Longitude: ", navaid.lon);
print("Elevation (AMSL): ", navaid.elevation, " m");
print("Type: ", navaid.type);
print("Frequency: ", sprintf("%.3f", navaid.frequency / 100), " Mhz");
print("Range: ", navaid.range_nm, " nm");
if(navaid.course) print("Course: ", navaid.course);
print("--");
<nowiki>}</nowiki>
}}

===findNavaidsByID()===
{{Nasal doc
|syntax = findNavaidsByID([pos, ]id[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1600|t=Source}}
|text = Returns a vector containing <code>navaid</code> ghost objects matching a given ID, sorted by range from a certain position.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidsByID(lat, lon, id, type);</code>.
|param2 = id
|param2text = Full or partial ID of the fix to search for.
:{{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.}}
|param3 = type
|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}}.
|example1 = var navaid = findNavaidsByID("MXW");
navaid = navaid[0];
print("ID: ", navaid.id); # prints info about 'MXW' (a VOR station)
print("Name: ", navaid.name);
print("Latitude: ", navaid.lat);
print("Longitude: ", navaid.lon);
print("Elevation (AMSL): ", navaid.elevation, " m");
print("Type: ", navaid.type);
print("Frequency: ", sprintf("%.3f", navaid.frequency / 1000), " Mhz");
print("Range: ", navaid.range_nm, " nm");
}}

===findNavaidsWithinRange()===
{{Nasal doc
|syntax = findNavaidsWithinRange([pos, ]range[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1518|t=Source}}
|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.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidsWithinRange(lat, lon, range, type);</code>.
|param2 = range
|param2text = Mandatory number giving the range in nautical miles within which to search for navaids.
|param3 = type
|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}}.
|example1text = Searches for navaids within 10 nm of [[KSFO]].
|example1 = var pos = airportinfo("KSFO");
var navs = findNavaidsWithinRange(pos, 10);
foreach(var nav; navs){
print(nav.name, " (ID: ", nav.id, ")");
}
|example2text = Searches for navaids within 10 nm of your current position.
|example2 = var navs = findNavaidsWithinRange(10);
foreach(var nav; navs){
print(nav.name, " (ID: ", nav.id, ")");
<nowiki>}</nowiki>
}}

===finddata()===
{{Nasal doc
|syntax = finddata(path);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=603|t=Source}}
|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]].
|param1 = path
|param1text = A relative path as a string.
|example1 = var path = finddata("Aircraft/Generic");
print(path); # prints the absolute path to $FG_ROOT/Aircraft/Generic
|example2 = var path = finddata("Airports");
print(path); # prints the absolute path to <TerraSync dir>/Airports
|example3 = var path = finddata("preferences.xml");
print(path); # prints the absolute path to $FG_ROOT/preferences.xml
}}

===flightplan()===
{{Nasal doc
|syntax = flightplan([path]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1738|t=Source}}
|text = {{see also|Nasal Flightplan}}
Returns a flight plan object, either one for the current flight plan, or one loaded from a given path.
|param1 = path
|param1text = Optional path to flight plan XML file.
|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.
|example1 = var fp = flightplan();
print(fp.getWP(fp.current).id);
|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>.
|example2 = var path = getprop('/sim/fg-home') ~ '/fp-demo.xml';
var fp = flightplan(path);
for(var i = 0; i < fp.getPlanSize(); i += 1){
print(fp.getWP(i).id);
<nowiki>}</nowiki>
}}

===geodinfo()===
{{Nasal doc
|syntax = geodinfo(lat, lon[, max_alt]);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=981|t=Source}}
|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}}):
* '''light_coverage:''' The coverage of a single point of light in m<sup>2</sup>.
* '''bumpiness:''' Normalized bumpiness factor for the material.
* '''load_resistance:''' The amount of pressure in N/m<sup>2</sup> the material can withstand without deformation.
* '''solid:''' 1 (true) or false (0) depending on whether the material is solid or not.
* '''names:''' Vector of scenery types (usually generated by [[TerraGear]]) that will use this material.
* '''friction_factor:''' Normalized friction factor of the material.
* '''rolling_friction:''' The rolling friction coefficient of the material.

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.
|param1 = lat
|param1text = Latitude, inputted as a number.
|param2 = lon
|param2text = Longitude, inputted as a number.
|param3 = max_alt
|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.
|example1text = Dumps information about ground underneath the aircraft.
|example1 = var pos = geo.aircraft_position();
var info = geodinfo(pos.lat(), pos.lon());
debug.dump(info);
|example2text = Prints whether the ground underneath the aircraft is solid or is water.
|example2 = var pos = geo.aircraft_position();
var info = geodinfo(pos.lat(), pos.lon());
if (info != nil and info[1] != nil) {
print("The ground underneath the aircraft is ", info[1].solid == 1 ? "solid." : "water.");
<nowiki>}</nowiki>
}}

=== geodtocart() ===
{{Nasal doc
|syntax = geodtocart(lat, lon, alt);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=962|t=Source}}
|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.
|param1 = lat
|param1text = Latitude, in degrees.
|param2 = lon
|param2text = Longitude, in degrees.
|param3 = alt
|param3text = Altitude, in metres.
|example1 = var (x, y, z) = geodtocart(0, 0, 0); # point is the intersection of the prime meridian and equator.
print("x: ", x); # prints "x: 6378137"
print("y: ", y); # prints "y: 0"
print("z: ", z); # prints "y: 0"
}}

=== get_cart_ground_intersection()===
Introduced in 2017.2.1, see [[Terrain Detection]].

===getprop()===
{{Nasal doc
|syntax = <nowiki>getprop(path[, path[, ...]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=345|t=Source}}
|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).
|param1 = path
|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.
|example1 = print("You have FlightGear v", getprop("/sim/version/flightgear")); # prints FlightGear version
|example2text = Note that the example below will only work in FlightGear 3.2 and above.
|example2 = for(var i = 0; i < 8; i += 1){
print("View #", i + 1, " is named ", getprop("/sim/view", i, "name"));
}
|example3text = Same as above, but is supported by all versions of FlightGear.
|example3 = for(var i = 0; i < 8; i += 1){
print("View #", i + 1, " is named ", getprop("/sim/view[" ~ i ~ "]/name"));
<nowiki>}</nowiki>
}}
==== See also====
{{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:
To get a Node rather than its value, use <code>props.globals.getNode()</code> - see [[Nasal_library/props]]. }}

===greatCircleMove()===
{{Nasal doc
|syntax = greatCircleMove([pos, ]course, dist);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1681|t=Source}}
|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).
|param1 = pos
|param1text = Optional position to calculate from. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost object.
:* A hash with ''lat'' and ''lon'' members
:* A <code>geo.Coord</code> object
:* A lat/lon pair, that is, a pair of numbers (latitude followed by longitude) separated by a comma: <code>greatCircleMove(lat,lon, ...)</code>.
|param2 = course
|param2text = Course to new set of coordinates, in degrees (in the range 0–360).
|param3 = dist
|param3text = Distance in nautical miles to the new set of coordinates.
|example1 = var pos = greatCircleMove(0,0, 0, 1);
debug.dump(pos); # print hash with coordinates
|example2 = var fix = findFixesByID("POGIC");
fix = fix[0];
var pos = greatCircleMove(fix, 45, 10);
debug.dump(pos); # print hash with coordinates
}}

===interpolate()===
{{Nasal doc
|private = _interpolate()
|syntax = <nowiki>interpolate(prop, value1, time1[, value2, time2[, ...]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=522|t=Part 1}} {{!}} {{fgdata file|Nasal/globals.nas|t=Part 2}}
|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.
|param1 = prop
|param1text = String or <code>props.Node</code> object that indicates a node in the property tree to be used.
|param2 = value''n''
|param2text = Target value to change the property to in the set amount of time. This should be a number.
|param3 = time''n''
|param3text = Time in seconds, that will be taken for the interpolation.
|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.
|example1 = setprop("/test", 0); # (re-)set property
interpolate("/test",
50, 5, # interpolate to 50 in 5 seconds
10, 2, # interpolate to 10 in 2 seconds
0, 5); # interpolate to 0 in 5 seconds
|example2 = # Apply the left brake at 20% per second
var prop = "controls/gear/brake-left";
var dist = 1 - getprop(prop);
if (dist == 1) {
interpolate(prop, 1, dist / 0.2);
<nowiki>}</nowiki>
}}

===isa()===
{{Nasal doc
|syntax = isa(object, class);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|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.
|param1 = object
|param1text = Object to check.
|param2 = class
|param2text = Class/object to check that '''object''' inherits from or is an instance of.
|example1 = var coord = geo.Coord.new();
if(isa(coord, geo.Coord)){
print("Variable 'coord' is an instance of class 'geo.Coord'"); # this one will be printed
} else {
print("Variable 'coord' is not an instance of class 'geo.Coord'");
}
|example2 = var coord = geo.Coord.new();
if(isa(coord, props.Node)){
print("Variable 'coord' is an instance of class 'props.Node'");
} else {
print("Variable 'coord' is not an instance of class 'props.Node'"); # this one will be printed
}
|example3text = The example below demonstrates checking of inheritance.
|example3 = var Const = {
constant: 2,
getConst: func {
return me.constant;
}
};

var Add = {
new: func {
return { parents: [Add, Const] };
},

addToConst: func(a){
return a * me.getConst();
}
};

var m = Add.new();
print(m.addToConst(4));

if(isa(m, Add)) print("Variable 'm' is an instance of class 'Add'"); # will be printed
if(isa(m, Const)) print("Variable 'm' is an instance of class 'Const'"); # will also be printed
}}

===logprint()===
{{Nasal doc
|syntax = <nowiki>logprint(priority[, msg[, msg[, ...]]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=431|t=Source}}
|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}}.
|param1 = priority
|param1text = Number specifying the priority level of the outputted message:
:{{{!}} class="wikitable"
! Number !! Debug type
{{!-}}
{{!}} 1 {{!!}} Bulk
{{!-}}
{{!}} 2 {{!!}} Debug
{{!-}}
{{!}} 3 {{!!}} Info
{{!-}}
{{!}} 4 {{!!}} Warn
{{!-}}
{{!}} 5 {{!!}} Alert
{{!}}}
|param2 = msg
|param2text = The message. There is no limit to the arguments you give give. They will be concatenated together before logging.
|example1 = # logs the value of pi to three decimal places with log level 3
logprint(3, "pi = ", sprintf("%.3f", math.pi));
|example2 = logprint(5, "Alert! This is an important message!");
}}
{{note|
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:

LOG_BULK, LOG_WARN, LOG_DEBUG, LOG_INFO, LOG_ALERT, DEV_WARN, DEV_ALERT }}

===magvar() ===
{{Nasal doc
|syntax = magvar([pos]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1642|t=Source}}
|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.
{{{!}} class="wikitable"
! FlightGear versions !! Model !! Reference date
{{!-}}
{{!}} 3.6 and above {{!!}} {{wikipedia|World Magnetic Model}} (WMM) 2015 {{!!}} 1 January 2015
{{!-}}
{{!}} 0.9.11-pre1 to 3.4 {{!!}} WMM 2005 {{!!}} 1 January 2005
{{!-}}
{{!}} 0.7.3 to 0.9.10 {{!!}} WMM 2000 {{!!}} 1 January 2000
{{!}}}
|param1 = pos
|param1text = Optional position to calculate from. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost object.
:* A hash with ''lat'' and ''lon'' members
:* A <code>geo.Coord</code> object
:* A lat/lon pair, that is, a pair of numbers (latitude followed by longitude) separated by a comma: <code>magvar(lat,lon)</code>.
|example1 = print(magvar(0, 0)); # prints the magnetic variation at 0, 0
}}

===maketimer() ===
{{Nasal doc
|syntax = maketimer(interval[, self], function);
|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}}
|version = 2.12
|commit = {{flightgear commit|ab939f|t=commit}}
|text = Returns a timer object containing the following methods and members:
* '''start()''': Starts the timer.
* '''stop()''': Stops the timer.
* '''restart(interval)''': Restarts the timer with the given interval.
* '''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).
* '''isRunning''': Read-only bool telling whether the timer is currently running.
* '''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.
Unlike {{func link|settimer()}}, which it replaces, <code>maketimer()</code> provides more control over the timer. In addition, it can help reduce memory usage.
|param1 = interval
|param1text = Interval in seconds for the timer.
|param2 = self
|param2text = Optional parameter specifying what any <code>'''me'''</code> references in the function being called will refer to.
|param3 = function
|param3text = Function to be called at the given interval.
|example1 = var timer = maketimer(1, func(){
print("Hello, World!"); # print "Hello, World!" once every second (call timer.stop() to stop it)
});
timer.start();
|example2 = var timer = maketimer(1, math, func(){
print(me.math); # 'me' reference is the 'math' namespace
});
timer.singleShot = 1; # timer will only be run once
timer.start();
|example3 = var timer = maketimer(1, func(){
print("Hello, World!"); # print "Hello, World!" once every second (call timer.stop() to stop it)
});
timer.start();
print(timer.isRunning); # prints 1
|example4text = In the example below, "Hello, World!" will be printed after one second the first time, and after two seconds thereafter.
|example4 = var update = func(){
print("Hello, World!");
timer.restart(2); # restarts the timer with a two second interval
}

var timer = maketimer(1, update);
timer.singleShot = 1;
timer.start();
}}

===maketimestamp()===
{{Nasal doc
|syntax = maketimestamp()
|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}}
|version = 2019.2
|commit = {{flightgear commit|7db06300|t=commit}}
|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:
* '''stamp()''': Resets the timing operation. Call this first.
* '''elapsedMSec()''': returns number of milliseconds elapsed since stamp() called. Resolution may vary depending on platform but is usually at least millisecond accuracy.
* '''elapsedUSec()''': returns number of microseconds elapsed since stamp() called. Resolution may vary depending on platform but is usually at least millisecond accuracy.
|
|example1text = In the example below the number of milliseconds elapsed will be printed.
|example1 = var timestamp = maketimestamp();
timestamp.stamp();
print(timestamp.elapsedMSec(), "ms elapsed");
print(timestamp.elapsedMSec(), "ms elapsed");
}}

===md5()===
{{Nasal doc
|syntax = md5(string);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=758|t=Source}}
|version = 3.2
|commit = {{flightgear commit|cfbf9e|t=commit}}
|text = Returns a the {{wikipedia|MD5}} hash (as a string) of the inputted string.
|param1 = string
|param1text = String the generate the hash of. Mandatory.
|example1text = The below code should output <code>65a8e27d8879283831b664bd8b7f0ad4</code>.
|example1 = print(md5("Hello, World!"));
}}

===navinfo()===
{{Nasal doc
|syntax = navinfo(lat, lon, type, id);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1453|t=Source}}
|text = Returns vector <code>navaid</code> ghost objects matching the given '''type''' and '''id''' or <code>'''nil'''</code> on error.
|param1 = lat ''and'' lon
|param1text = If given, the returned navaids will be put into order of ascending distance from the location.
|param2 = type
|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."
|param3 = id
|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.
|example1 = navinfo("vor"); # returns all VORs
|example2 = navinfo("HAM"); # return all navaids whose names start with "HAM"
|example3 = navinfo("vor", "HAM"); # return all VORs whose names start with "HAM"
|example4 = navinfo(34,48,"vor","HAM"); # return all VORs whose names start with "HAM" and sorted by distance relative to 34°, 48°
}}

===parse_markdown()===
{{Nasal doc
|syntax = parse_markdown(markdown);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=745|t=Part 1}} {{!}} {{simgear file|simgear/misc/SimpleMarkdown.cxx|t=Part 2}}
|version = 3.2
|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:
* It strips whitespace from the beginning of the string.
* It supports [http://daringfireball.net/projects/markdown/syntax#p paragraphs and line breaks].
* It collapses whitespace.
* It converts unordered [http://daringfireball.net/projects/markdown/syntax#list lists] to use a bullet character (•). 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.
|param1 = markdown
|param1text = String containing Markdown to be parsed.
|example1text =
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>).
<syntaxhighlight lang="xml" highlight="41-50">
<?xml version="1.0" encoding="UTF-8"?>

<PropertyList>

<name>test</name>
<layout>vbox</layout>

<group>
<layout>hbox</layout>

<empty>
<stretch>true</stretch>
</empty>

<text>
<label>parse_markdown() test dialog</label>
</text>

<empty>
<stretch>true</stretch>
</empty>

<button>
<legend></legend>
<pref-width>16</pref-width>
<pref-height>16</pref-height>
<binding>
<command>dialog-close</command>
</binding>
</button>

</group>

<canvas>
<name>Canvas plot</name>
<stretch>true</stretch>
<pref-width>400</pref-width>
<pref-height>300</pref-height>
<nasal>
<load><![CDATA[
var text = 'Items:
* apples
* oranges
* pears

Some text.
Some more items:
* apples
* oranges
* pears';

var parsed = parse_markdown(text);

var root_canvas = canvas.get(cmdarg());
root_canvas.setColorBackground(255, 255, 255);
var root = root_canvas.createGroup();

var text_dis = root.createChild("text")
.setText(parsed)
.setTranslation(5, 5)
.setFont("LiberationFonts\LiberationSans-Regular.ttf")
.setFontSize(15)
.setColor(0, 0, 0)
.setDrawMode(canvas.Text.TEXT)
.setAlignment("left-top");
]]></load>
</nasal>
</canvas>

</PropertyList>
</syntaxhighlight>
|example1 = fgcommand("dialog-show", {"dialog-name": "test"});
|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.
|example2 = <nowiki>var markdown = 'Items:
* apples
* oranges
* pears

Some text.
Some more items:
* apples
* oranges
* pears';

var parsed = parse_markdown(markdown);

debug.dump(parsed);

var path = string.normpath(getprop("/sim/fg-home") ~ '/Export/parse_markdown()-test.html');

var file = io.open(path, "w");

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>";

io.write(file, html);
io.close(file);
print("Done, file ready for viewing (" ~ path ~ ")");</nowiki>
}}

===parsexml()===
{{Nasal doc
|syntax = <nowiki>parsexml(path[, start[, end[, data[, pro_ins]]]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=710|t=Source}}
|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.
|param1 = path
|param1text = Mandatory absolute path to the XML file to be parsed.
|param2 = start
|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.
|param3 = end
|param3text = Optional callback function that will be called for every ending tag. The function should take one argument: the tag name.
|param4 = data
|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.
|param5 = pro_ins
|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.
|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.
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>

<?xml-stylesheet type="text/xsl" href="style.xsl"?>

<foo>
<blah type="string"><![CDATA[ <sender>John Smith</sender> ]]></blah>
<blah2 type="string">Orange & lemons</blah2>
</foo>
</syntaxhighlight>
|example1 = var start = func(name, attr){
print("Starting tag: '", name, "'");
foreach(var a; keys(attr)){
print("\twith attribute ", a, '="', attr[a], '"');
}
}

var end = func(name){
print("Ending tag: '", name, "'");
}

var data = func(data){
print("Data = '", data, "'");
}

var pro_instr = func(target, data){
print("Processing instruction: target = '", target, "', data = '", data, "'");
}

parsexml(getprop("/sim/fg-home") ~ '/Export/demo.xml', start, end, data, pro_instr);
}}

===print()===
{{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.

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>}}

{{Nasal doc
|syntax = <nowiki>print(data[, data[, ...]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=415|t=Source}}
|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.
|param1 = data
|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.
|example1 = print("Just", " a ", "test"); # prints "Just a test"
|example2 = print("pi = ", math.pi); # prints "pi = 3.141592..."
}}

=== printf() ===
{{Nasal doc
|syntax = <nowiki>printf(format[, arg[, arg, [...]]]);</nowiki>
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|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>).
|example1 = printf("In hexadecimal, 100000 = %X", 186A0); # prints "In hexadecimal, 100000 = 186A0"
}}

===printlog()===
{{caution|This function is deprecated and doesn't work. Please use the new one {{func link|logprint()}}.}}
{{Nasal doc
|syntax = <nowiki>printlog(level, data[, data[, ...]]);</nowiki>
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|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.
|param1 = level
|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.
|param2 = data
|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.
|example1 = printlog("alert", "This is an alert"); # message will be printed
|example2 = printlog("info", "Just informing you about something"); # message will be printed only if log level is set to "info" or less
}}

===rand()===
{{Nasal doc
|syntax = rand();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=554|t=Source}}
|text = Returns a random floating point number between 0 (inclusive) and 1 (exclusive). It takes no arguments.
|example1 = print(rand()); # prints random number
}}

===registerFlightPlanDelegate()===
{{Nasal doc
|syntax = registerFlightPlanDelegate(init_func);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1879|t=Source}}
|text = Registers a flight plan delegate. See <tt>''{{fgdata file|Nasal/route_manager.nas|t=$FG_ROOT/Nasal/route_manager.nas}}''</tt> for examples.
|param1 = init_func
|param1text = Initialization function which will be called during FlightGear's startup.
}}
===removecommand()===
{{Nasal doc
|syntax = removecommand(cmd);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=668|t=Source}}
|text = Removes the given fgcommand. Returns <code>'''nil'''</code>.
{{caution|This will remove '''any''' [[fgcommands|fgcommand]], even those implemented in C++, so use with caution!}}
|param1 = cmd
|param1text = String specifying the name of the command to remove.
|example1 = addcommand("hello", func(){
print("Hello");
});
fgcommand("hello"); # "Hello" will be printed
removecommand("hello"); # removes it
}}

===removelistener()===
{{Nasal doc
|syntax = removelistener(id);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=1384|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=506|t=Part 2}}
|text = Removes and deactivates the given listener and returns the number of listeners left or <code>'''nil'''</code> on error.
{{note|It is good practice to remove listeners when they are not required anymore. This prevents the listeners reducing FlightGear's run performance.}}
|param1 = id
|param1text = ID of listener as returned by {{func link|setlistener()}}.
|example1 = var ls = setlistener("/sim/test", func(){
print("Property '/sim/test' has been changed");
});
setprop("/sim/test", "blah"); # trigger listener
var rem = removelistener(ls); # remove listener
print("There are ", rem, " listeners remaining");
}}

===resolvepath()===
{{Nasal doc
|syntax = resolvepath(path);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=604|t=Source}}
|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.
|param1 = path
|param1text = Relative path to be completed.
|example1 = print(resolvepath("Nasal/globals.nas")); # prints the equivalent of $FG_ROOT/Nasal/globals.nas
|example2 = print(resolvepath("blah")); # prints nothing; could not be resolved
|example3 = var file_path = resolvepath("Aircraft/SenecaII/some-file");
if (file_path != ""){
gui.popupTip("some-file found", 2);
} else {
gui.popupTip("some-file not found", 2);
<nowiki>}</nowiki>
}}

===setlistener()===
{{Nasal doc
|syntax = <nowiki>setlistener(node, code[, init[, type]]);</nowiki>
|private = _setlistener()
|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.''
|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()}}.
{{note|Listeners are known to be a source of resource leaks. To avoid this, please take measures such as:
* Using {{func link|removelistener()}} when they are not needed any more.
* Using a single initialization listener.
* Avoiding tying listeners to properties that are rapidly updated (e.g., many times per frame).
}}
|param1 = node
|param1text = Mandatory string or <code>props.Node</code> object pointing to a property in the [[Property Tree]].
|param2 = code
|param2text = Mandatory callback function to execute when the listener is triggered. The function can take up to four arguments in the following order:
* '''changed''': a <code>props.Node</code> object pointing to the changed node.
* '''listen''': a <code>props.Node</code> object pointing to the listened-to node. Note that this argument maybe different depending on the '''type'''.
* '''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.
* '''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.
|param3 = init
|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).
|param4 = type
|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.
|example1 = var prop = props.globals.initNode("/sim/test", "", "STRING"); # create property
var id = setlistener("/sim/test", func(n){ # create listener
print("Value: ", n.getValue());
});
setprop("/sim/test", "blah"); # trigger listener
removelistener(id); # remove listener
prop.remove(); # remove property
}}

===setprop()===
{{Nasal doc
|syntax = <nowiki>setprop(path[, path[, ...]], value);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=385|t=Source}}
|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.
{{note|If you want to remove a property, you will have to use one of the <code>props</code> helpers:
<syntaxhighlight lang="nasal">
props.globals.getNode("foo/bar").remove(); # take out the complete node
props.globals.getNode("foo").removeChild("bar"); # take out a certain child node
</syntaxhighlight>
}}
|param1 = path
|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.
|param2 = value
|param2text = Value to write to the given property. Must be either a string or a number.
|example1 = setprop("/sim/demo", "This is a demo");
|example2text = Note that the example below will only work in FlightGear 3.2 and above.
|example2 = for(var i = 0; i < 3; i += 1){
setprop("/sim/demo", i, "Demo #" ~ i));
}
|example3text = Same as above, but is supported by all versions of FlightGear.
|example3 = for(var i = 0; i < 3; i += 1){
setprop("/sim/demo[" ~ i ~ "]", "Demo #" ~ i));
<nowiki>}</nowiki>
}}
====See also====
{{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:
To get a Node rather than its value, use <code>props.globals.getNode()</code> - see [[Nasal_library/props]]. }}

===settimer() ===
{{Nasal doc
|syntax = settimer(function, delta[, realtime]);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=499|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=1286|t=Part 2}}
|text = Runs the given function a specified amount of seconds after the current time. Returns <code>'''nil'''</code>.
{{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.}}
|param1 = function
|param1text = Mandatory function that will be called. It may be necessary to enclose code in an anonymous function (see example).
|param2 = delta
|param2text = Mandatory amount of time in seconds after which the function will be called.
|param3 = realtime
|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.
|example1 = var myFunc = func(){
print("Hello");
}

settimer(myFunc, 2); # runs myFunc after 2 seconds
|example2 = var sqr = func(a){
return a * a;
}

settimer(func(){
print(sqr(2)); # will print 4 after 2 seconds
}, 2);
}}

===srand() ===
{{Nasal doc
|syntax = srand();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=559|t=Source}}
|text = Makes the pseudorandom number generator (see {{func link|rand()}}) generate a new {{wikipedia|random seed|noicon=1}} based on time. Returns 0.
}}
===systime()===
{{Nasal doc
|syntax = systime();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=770|t=Source}}
|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).
{{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]}}
|example1 = print("Unix time: ", systime()); # prints Unix time
|example2 = var myFunc = func(){
for(var i = 0; i <= 10; i += 1){
print("Interation #", i);
}
}
var t = systime(); # record time
myFunc(); # run function
var t2 = systime(); # record new time
print("myFunc() took ", t2 - t, " seconds"); # print result
}}

===thisfunc()===
{{Nasal doc
|syntax = thisfunc();
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = Returns the function from which this function is called. This allows a function to reliably and safely call itself from within a closure.
|example1 = var stringify_vec = func(input){
if (typeof(input) == "scalar"){
return sprintf("%s", input);
} elsif (typeof(input) == "vector") {
if (size(input) == 0) return "[]";
var this = thisfunc();
var buffer = "[";
for(var i = 0; i < size(input); i += 1){
buffer ~= this(input[i]);
if (i == size(input) - 1) {
buffer ~= "]";
} else {
buffer ~= ", ";
}
}
return buffer;
} else {
die("stringify_vec(): Error! Invalid input. Must be a vector or scalar");
}
}

var test_vec = ["a", "b", "c", [1, 2, 3], "d"];
debug.dump(stringify_vec(test_vec)); # prints "[a, b, c, [1, 2, 3], d]"
test_vec = [];
debug.dump(stringify_vec(test_vec)); # prints "[]"
test_vec = {};
debug.dump(stringify_vec(test_vec)); # will throw an error
}}

===tileIndex() ===
{{Nasal doc
|syntax = tileIndex();
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1720|t=Source}}
|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>.
|example1 = print(tileIndex()); # print index
}}

=== tilePath()===
{{Nasal doc
|syntax = tilePath();
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1712|t=Source}}
|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>.
|example1 = print(tilePath()); # print path
}}

=== values()===
{{Nasal doc
|syntax = values(hash);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = Returns a vector containing the values of the given hash.
|param1 = hash
|param1text = Mandatory hash to get the values of.
|example1 = var hash = {
"a": 1,
"b": 2,
"c": 3
};

foreach(var val; values(hash)){
print(val);
}
|example2text = The below example does exactly the same thing as the above example, but does not use <code>values()</code>:
|example2 = var hash = {
"a": 1,
"b": 2,
"c": 3
};

foreach(var key; keys(hash)){
print(hash[key]);
<nowiki>}</nowiki>
}}

==Extension functions new in FG 2020.1 ==
The following functions have been added to the nasal core library and will be released with FlightGear version 2020.1.
Before the release they are available in the development branch "next".

===isfunc()===
Returns 1 if type or argument is a function, otherwise 0.

===isghost()===
Returns 1 if type or argument is a ghost, otherwise 0.

=== ishash()===
Returns 1 if type or argument is a hash, otherwise 0.

===isint()===
{{Nasal doc
|syntax = isint(x);
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}
|text = Returns 1 if argument has a numeric value and x == floor(x), e.g. integer.
}}

===isnum()===
{{Nasal doc
|syntax = isnum(x);
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}
|text = Returns 1 if typeof(x) is "scalar" and x has a numeric value otherwise 0.
}}

===isscalar()===
{{Nasal doc
|syntax = isscalar(x);
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}
|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 "~".
|example1 = var a = "foo";
var b=42;
if (isscalar(a) and isscalar(b)) print(a~b);
if (isstr(a)) print("a is a string");
if (isint(b)) print("b is an integer");
# if (isscalar(a))... is equivalent to if (typeof(a) == "scalar")...
}}

===isstr()===
Returns 1 if type or argument is a string, otherwise 0.

===isvec()===
Returns 1 if type or argument is a vector, otherwise 0.

===vecindex()===
{{Nasal doc
|syntax = vecindex(vector, value);
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}
|text = Returns the index of value or nil, if value is not found in vector.
|example1=
var myvector = ["apple", "bananna", "coconut"];
# to check if a vector contains a certain value compare vecindex to nil
if (vecindex(myvector, "apple") != nil) {
print("found apple");
}
# WARNING: this will not work as desired because index is 0
if (vecindex(myvector, "apple")) {
print("found apple");
<nowiki>}</nowiki>

}}

==Extension functions new in "dev" version ==
The following functions have been added to the nasal core library curernty on "dev" version.

===member()===
{{Nasal doc
|syntax = member(hash, key);
|source = {{simgear file|simgear/nasal/lib.c|l=796|t=Source}}
|text = The function searches for a key in the given hash, including the <code>parents</code>. If the key is found, its value is returned; otherwise, it returns <code>nil</code>.
|param1 = hash
|param1text = The hash in which the key is searched.
|param2 = key
|param2text = Key as a string whose value we want to return.
|example1 =
var Hash = {
key: 12,
};

member(Hash, 'key'); # return 12
member(Hash, 'missing'); # return nil
|example2 = # member() also includes parents

var Base = {
key: 'text',
};

var Child = {
parents: [Base],
};

member(Child, 'key'); # return 'text'
member(Child, 'missing'); # return nil
}}

===has_member()===
{{Nasal doc
|syntax = has_member(hash, key);
|source = {{simgear file|simgear/nasal/lib.c|l=811|t=Source}}
|text = The function searches for a key in the given hash, including the <code>parents</code>. If the key is found, <code>true</code> is returned, otherwise <code>false</code>.
|param1 = hash
|param1text = The hash in which the key is searched.
|param2 = key
|param2text = Key as a string.
|example1 =
var Hash = {
key: 12,
};

member(Hash, 'key'); # return true
member(Hash, 'missing'); # return false
|example2 = # has_member() also includes parents

var Base = {
key: 'text',
};

var Child = {
parents: [Base],
};

member(Child, 'key'); # return true
member(Child, 'missing'); # return false
}}

==Variables==
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}}.

===D2R===
{{Nasal doc
|syntax = var radians = degrees * D2R;
|text = Converts an angle from degrees to radians when multiplied by the angle in degrees. Equal to <code>π / 180</code>.
}}
===FPS2KT===
{{Nasal doc
|syntax = var knots = feet_per_second * FPS2KT;
|text = Converts a velocity from feet per second to knots when multiplied by the velocity in feet per second. Approximately equal to 0.5925.
}}
===FT2M===
{{Nasal doc
|syntax = var metres = feet * FT2M;
|text = Converts a length from feet to metres when multiplied by the length in feet. Equal to 0.3048.
}}
===GAL2L ===
{{Nasal doc
|syntax = var litres = gallons * GAL2L;
|text = Converts a volume from US liquid gallons to litres when multiplied by the volume in gallons. Approximately equal to 3.7854.
}}
===IN2M===
{{Nasal doc
|syntax = var metres = inches * IN2M;
|text = Converts a length from inches to metres when multiplied by the length in inches. Equal to 0.0254.
}}
===KG2LB===
{{Nasal doc
|syntax = var pounds = kilograms * KG2LB;
|text = Converts a mass from kilograms to pounds when multiplied by the mass in kilograms. Approximately equal to 2.2046.
}}
===KT2FPS===
{{Nasal doc
|syntax = var feet_per_second = knots * KT2FPS;
|text = Converts a velocity from knots to feet per second when multiplied by the velocity in knots. Approximately equal to 1.6878.
}}
===KT2MPS===
{{Nasal doc
|syntax = var metres_per_second = knots * KT2MPS;
|text = Converts a velocity from knots to metres per second when multiplied by the velocity in knots. Approximately equal to 0.5144.
}}
===L2GAL===
{{Nasal doc
|syntax = var gallons = litres * L2GAL;
|text = Converts a volume from litres to US liquid gallons when multiplied by the volume in litres. Approximately equal to 0.2642.
}}
===LB2KG===
{{Nasal doc
|syntax = var kilograms = pounds * LB2KG;
|text = Converts a mass from pounds to kilograms when multiplied by the mass in pounds. Approximately equal to 0.4536.
}}
===M2FT ===
{{Nasal doc
|syntax = var feet = metres * M2FT;
|text = Converts a length from metres to feet when multiplied by the length in metres. Approximately equal to 3.2808.
}}
===M2IN===
{{Nasal doc
|syntax = var inches = metres * M2IN;
|text = Converts a length from metres to inches when multiplied by the length in metres. Approximately equal to 39.3701.
}}
===M2NM ===
{{Nasal doc
|syntax = var nautical_miles = metres * M2NM;
|text = Converts a length from metres to nautical miles when multiplied by the length in metres. Approximately equal to 0.00054.
}}
===MPS2KT ===
{{Nasal doc
|syntax = var knots = metres_per_second * MPS2KT;
|text = Converts a velocity from metres per second to knots when multiplied by the velocity in metres per second. Approximately equal to 1.9438.
}}
===NM2M ===
{{Nasal doc
|syntax = var metres = nautical_miles * NM2M;
|text = Converts a length from nautical miles to metres when multiplied by the length in nautical miles. Equal to 1,852.
}}
===R2D===
{{Nasal doc
|syntax = var degrees = radians * R2D;
|text = Converts an angle from radians to degrees when multiplied by the angle in radians. Equal to <code>180 / π</code>.
}}

{{Appendix}}

{{Nasal namespaces}}

Nasal library

2026-01-16T19:35:42Z

PlayeRom:

{{Nasal Navigation|nocat=1}}
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:
* {{flightgear file|src/Scripting}}
* {{simgear file|simgear/nasal}}

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]].

{{tip|Copy & paste the examples into your [[Nasal Console]] and execute them to see what they do.|width=70%}}

== Core library functions ==
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:
* http://plausible.org/nasal/lib.html ([http://web.archive.org/web/20101010094553/http://plausible.org/nasal/lib.html archive])
* {{simgear file|simgear/nasal/lib.c}} ([http://sourceforge.net/p/flightgear/simgear/ci/next/log/?path=/simgear/nasal/lib.c history])

=== append() ===
{{Nasal doc
|syntax = append(vector, element[, element[, ...]]);
|source = {{simgear file|simgear/nasal/lib.c|l=45|t=Source}}
|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.
|param1 = vector
|param1text = The vector to which the arguments will be appended.
|param2 = element
|param2text = An element to be added to the vector.
|example1 =
var vector = [1, 2, 3]; # Initialize the vector
append(vector, 4); # Append the number 4 to the end of the vector
debug.dump(vector); # Print the contents of the vector
|example2 =
var vector = [1, 2, 3]; # Initialize the vector
append(vector, 4, 5, 6); # Append the numbers 4, 5, and 6 to the end of the vector
debug.dump(vector); # Print the contents of the vector
}}

=== bind() ===
{{Nasal doc
|syntax = bind(function, locals[, outer_scope]);
|source = {{simgear file|simgear/nasal/lib.c|l=638|t=Source}}
|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.
|param1 = function
|param1text = Function to evaluate.
|param2 = locals
|param2text = Hash containing values that will become the namespace (first closure) for the function.
|param3 = outer_scope
|param3text = Optional function which is bound to the next closure. This can be bound to yet another, making a linked list.
|example1 = # This is a namespace/hash with a single member, named "key," which is initialized to 12
var Namespace = {
key: 12
};

# This is different namespace/hash containing a function
# dividing a variable "key" (which is unavailable/nil in this namespace) by 2
var AnotherNamespace = {
ret: func {
key /= 2;
}
};

# To see that key is not available, try to call AnotherNamespace.ret() first
call(AnotherNamespace.ret, [], nil, nil, var errors = []);
if(size(errors)){
print("Key could not be divided/resolved!");
debug.printerror(errors);
}

# Associate the AnotherNamespace.ret() function with the first namespace
# so that "key" is now available
var function = bind(AnotherNamespace.ret, Namespace);

# Invoke the new function
function();

# Print out the value of Namespace.key
# It was changed to 12 from 6 by AnotherNamespace.ret()
print(Namespace.key);
}}

=== call() ===
{{Nasal doc
|syntax = call(func[, args[, me[, locals[, error]]]);
|source = {{simgear file|simgear/nasal/lib.c|l=376|t=Source}}
|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.
|param1 = func
|param1text = Function to execute.
|param2 = args
|param2text = Vector containing arguments to give to the called function.
|param3 = me
|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).
|param4 = locals
|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.
|param5 = error
|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}}.
|example1 =
# prints "Called from call()"
call(func {
print("Called from call()");
});
|example2 =
# prints "a = 1 : b = 2
call(func(a, b){
print("a = ", a, " : b = ", b);
},
[1, 2]
);
|example3 =
var Hash = {
new: func {
var m = { parents: [Hash] };

m.el1 = "string1";
m.el2 = "string2";

return m;
}
};

# prints "me.el1 = string1", then "me.el2 = string2" on the next line
call(func(a, b){
print("me.el", a, " = ", me["el" ~ a]);
print("me.el", b, " = ", me["el" ~ b]);
},
[1, 2],
Hash.new()
);
|example4 =
# prints the value of math.pi
call(func {
print(pi);
}, nil, nil,
math
);
|example5 =
call(func {
print(math.ip); # math.ip doesn't exist
}, nil, nil, nil,
var errs = []
);
debug.printerror(errs); # The error is caught and printed using debug.printerror()
}}

=== caller() ===
{{Nasal doc
|syntax = caller([level]);
|source = {{simgear file|simgear/nasal/lib.c|l=540|t=Source}}
|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 '''[0]''' a hash of local variables, '''[1]''' the function object, '''[2]''' the full source file name (incl. path) and '''[3]''' the line number.
|param1 = level
|param1text = Optional integer specifying the stack level to return a result from. Defaults to 1 (i.e. the caller of the currently executing function).
|example1 =
var myFunction = func(a, b) {
debug.dump(caller(0)[0]); # prints a hash of local variables, including arguments a and b
return 2 * 2;
};

print("2 x 2 = ", myFunction(2, 2));
|example2 =
var get_arg_value = func() {
print("Argument to myFunc = ", caller(1)[0]['a']); # print the value of myFunc's single argument, using caller()
};

var myFunc = func(a) {
get_arg_value();
};

myFunc(3);
|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: true, zindex: nil }</code>.
|example3 =
var MapStructure_selfTest = func() {
var temp = {};
temp.dlg = canvas.Window.new([600, 400], "dialog");
temp.canvas = temp.dlg.createCanvas().setColorBackground(1, 1, 1, 0.5);
temp.root = temp.canvas.createGroup();

var testMap = temp.root.createChild("map");
testMap.setController("Aircraft position");
testMap.setRange(25); # TODO: implement zooming/panning via mouse/wheel here, for lack of buttons :-/
testMap.setTranslation(
temp.canvas.get("view[0]") / 2,
temp.canvas.get("view[1]") / 2,
);

var r = func(name, vis = true, zindex = nil) {
return caller(0)[0];
}

# TODO: we'll need some z-indexing here, right now it's just random
# TODO: use foreach/keys to show all layers in this case by traversing SymbolLayer.registry directly ?
# maybe encode implicit z-indexing for each lcontroller ctor call ? - i.e. preferred above/below order ?
var types = [
r('TFC', false),
r('APT'),
r('DME'),
r('VOR'),
r('NDB'),
r('FIX', false),
r('RTE'),
r('WPT'),
r('FLT'),
r('WXR'),
r('APS'),
];

foreach (var type; types) {
testMap.addLayer(
factory: canvas.SymbolLayer,
type_arg: type.name,
visible: type.vis,
priority: type.zindex,
);
}
}; # MapStructure_selfTest
}}

=== chr() ===
{{Nasal doc
|syntax = chr(code);
|source = {{simgear file|simgear/nasal/lib.c|l=240|t=Source}}
|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.}}
{{{!}} class="wikitable"
! Code !! Name !! Equivalent to
{{!-}}
{{!}} 10 {{!!}} {{Wikipedia|Newline}} {{!!}} <code>\n</code>
{{!-}}
{{!}} 9 {{!!}} {{Wikipedia|Tab key#Tab characters|Horizontal tab}} {{!!}} <code>\t</code>
{{!-}}
{{!}} 13 {{!!}} {{Wikipedia|Carriage return}} {{!!}} <code>\r</code>
{{!}}}
|param1 = code
|param1text = Integer character code for the desired glyph.
|example1 = print("Code 65 = ", chr(65)); # prints "Code 65 = A"
|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.
|example2 =
for(var i = 0; i <= 255; i += 1){
print("Code ", i, " = >", chr(i), "<");
}
}}

=== closure() ===
{{Nasal doc
|syntax = closure(func[, level]);
|source = {{simgear file|simgear/nasal/lib.c|l=557|t=Source}}
|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'''.
|param1 = func
|param1text = Function to evaluate.
|param2 = level
|param2text = Optional integer specifying the scope level. Defaults to 0 (the namespace of '''func''').
|example1 =
var get_math_e = func {
return e; # return the value of math.e
}

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
debug.dump(closure(myFunction)); # print the hash of the namespace "get_math_e"

print(myFunction());
}}

=== cmp() ===
{{Nasal doc
|syntax = cmp(a, b);
|source = {{simgear file|simgear/nasal/lib.c|l=169|t=Source}}
|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'''.
|param1 = a
|param1text = First string argument for comparison.
|param2 = b
|param2text = Second string argument for comparison.
|example1 = print(cmp("1", "two")); # prints -1
|example2 = print(cmp("string", "string")); # prints 0
|example3 = print(cmp("one", "2")); # prints 1
|example4 = print(cmp("string1", "string2")); # prints -1
}}

=== compile() ===
{{Nasal doc
|syntax = compile(code[, filename]);
|source = {{simgear file|simgear/nasal/lib.c|l=349|t=Source}}
|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'''.
|param1 = code
|param1text = String containing Nasal code to be compiled.
|param2 = filename
|param2text = Optional string used for error messages/logging. Defaults to <code><compile></code>
|example1 =
var myCode = 'print("hello");';
var helloFunc = compile(myCode, "myCode");
helloFunc();
|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>.
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<PropertyList>

<nasal><![CDATA[
print("You have FlightGear v", getprop("/sim/version/flightgear"));
]]></nasal>

</PropertyList>
</syntaxhighlight>
Now, start FlightGear and execute this code in the [[Nasal Console]].
|example2 =
# Build the path
var FGRoot = getprop("/sim/fg-root");
var filename = "/gui/dialogs/test.xml";
var path = FGRoot ~ filename;

var blob = io.read_properties(path);
var script = blob.getValues().nasal; # Get the nasal string

# Compile the script. We're passing the filename here for better runtime diagnostics
var code = call(func {
compile(script, filename);
}, nil, nil, var compilation_errors = []);

if(size(compilation_errors)){
die("Error compiling code in: " ~ filename);
}

# Invoke the compiled script, equivalent to code();
# We're using call() here to detect errors:
call(code, [], nil, nil, var runtime_errors = []);

if(size(runtime_errors)){
die("Error calling code compiled loaded from: " ~ filename);
}
|example3text = The <code>compile()</code> function also allows you to parse a JSON string into a hash. Simplest example:
|example3 =
var jsonFunc = compile('{"version":"1.2.0","author":{"name":"John"} }');
var json = jsonFunc(); # return hash
logprint(LOG_ALERT, json["version"]); # print "1.2.0"
logprint(LOG_ALERT, json["author"]["name"]); # print "John"
}}

=== contains() ===
{{Nasal doc
|syntax = contains(hash, key);
|source = {{simgear file|simgear/nasal/lib.c|l=249|t=Source}}
|text = Returns 1 (True) if the hash contains the specified key, or 0 (False) if not.
|param1 = hash
|param1text = The hash to search in.
|param2 = key
|param2text = The scalar to be searched for, contained as a key in the hash.
|example1 =
# Initialize a hash
var hash = {
element: "value"
};
print(contains(hash, "element") ? "Yes" : "No"); # This will print "Yes"
print(contains(hash, "element2") ? "Yes" : "No"); # This will print "No"
}}

===contains()===
{{Requires commit|desc=Vector support|details=see {{Merge-request|project=fgdata|id=305}}|commit=ee39abbd3b70c9b6d5e3a1c4ccedddaac1a92b11|repo=Simgear}}
{{Nasal doc
|syntax = contains(vector, item);
|source = {{simgear file|simgear/nasal/lib.c|l=249|t=Source}}
|text = Returns 1 (True) if the vector contains the specified item, or 0 (False) if not.
|param1 = vector
|param1text = The vector to search in.
|param2 = item
|param2text = The object to be searched for in the vector.
|example1 =
# Initialize a vector
var vec = ["element", "foo"];
print(contains(vec, "element") ? "Yes" : "No"); # This will print "Yes"
print(contains(vec, "element2") ? "Yes" : "No"); # This will print "No"
}}

===delete() ===
{{Nasal doc
|syntax = delete(hash, key);
|source = {{simgear file|simgear/nasal/lib.c|l=118|t=Source}}
|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.
|param1 = hash
|param1text = The hash from which to delete the key.
|param2 = key
|param2text = The scalar to be deleted, contained as a key in the hash.
|example1 =
# Initialize the hash
var hash = {
element1: "value1",
element2: "value2"
};
delete(hash, "element1"); # Delete element1
debug.dump(hash); # prints the hash, which is now minus element1
}}

===die()===
{{Nasal doc
|syntax = die(error);
|source = {{simgear file|simgear/nasal/lib.c|l=417|t=Source}}
|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()}}.
|param1 = error
|param1text = String describing the error.
:{{inote|This parameter is technically optional, but it is highly recommended to use it.}}
|example1 =
print("Will print");
die("Don't go any further!");
print("Won't print"); # Will not be printed because die() stops the process
}}

=== find()===
{{Nasal doc
|syntax = find(needle, haystack);
|source = {{simgear file|simgear/nasal/lib.c|l=586|t=Source}}
|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.
|param1 = needle
|param1text = String to search for.
|param2 = haystack
|param2text = String to search in.
|example1 = print(find("c", "abcdef")); # prints 2
|example2 = print(find("x", "abcdef")); # prints -1
|example3 = print(find("cd", "abcdef")); # prints 2
}}

===ghosttype()===
{{Nasal doc
|syntax = ghosttype(ghost);
|source = {{simgear file|simgear/nasal/lib.c|l=336|t=Source}}
|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.
|param1 = ghost
|param1text = Ghost to return a description for.
|example1 = print(ghosttype(airportinfo())); # prints "airport"
}}

===id()===
{{Nasal doc
|syntax = id(object);
|source = {{simgear file|simgear/nasal/lib.c|l=706|t=Source}}
|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.
|param1 = object
|param1text = Can be either of a string, a vector, a hash, a code, a function, or a ghost.
|example1 = print(id("A")); # prints "str:000000001624A590"
}}

===int() ===
{{Nasal doc
|syntax = int(number);
|source = {{simgear file|simgear/nasal/lib.c|l=125|t=Source}}
|text = Returns the integer part of the numeric value of the single argument, or <code>'''nil'''</code> if none exists.
|param1 = number
|param1text = Number or string with just a number in it to return an integer from.
|example1 = print(int(23)); # prints "23"
|example2 = print(int(23.123)); # prints "23"
|example3 = debug.dump(int("string")); # prints "nil"
}}

===keys()===
{{Nasal doc
|syntax = keys(hash);
|source = {{simgear file|simgear/nasal/lib.c|l=36|t=Source}}
|text = Returns a vector containing the list of keys found in the single hash argument.
|param1 = hash
|param1text = The hash to return the keys from.
|example1 =
# Initialize a hash
var hash = {
element1: "value",
element2: "value"
};
debug.dump(keys(hash)); # print the vector
}}

===left()===
{{Nasal doc
|syntax = left(string, length);
|source = {{simgear file|simgear/nasal/lib.c|l=214|t=Source}}
|version = 2.12
|commit = {{simgear commit|bd7163|t=commit}}
|text = Returns a substring of '''string''', starting from the left.
|param1 = string
|param1text = String to return part of.
|param2 = length
|param2text = Integer specifying the length of the substring to return.
|example1 = print(left("string", 2)); # prints "st"
}}

=== num()===
{{Nasal doc
|syntax = num(number);
|source = {{simgear file|simgear/nasal/lib.c|l=149|t=Source}}
|text = Returns the numerical value of the single string argument, or <code>'''nil'''</code> if none exists.
|param1 = number
|param1text = String with just a number in it to return a number from.
|example1 = print(num("23")); # prints "23"
|example2 = print(num("23.123")); # prints "23.123"
|example3 = debug.dump(num("string")); # prints "nil"
}}

===pop()===
{{Nasal doc
|syntax = pop(vector);
|source = {{simgear file|simgear/nasal/lib.c|l=85|t=Source}}
|text = Removes and returns the last element of the single vector argument, or <code>'''nil'''</code> if the vector is empty.
|param1 = vector
|param1text = Vector to remove an element from.
|example1 =
var vector = [1, 2, 3];
pop(vector);
debug.dump(vector); # prints "[1, 2]"
|example2 =
var vector = [1, 2, 3];
debug.dump(pop(vector)); # prints "3"
|example3 =
var vector = [];
debug.dump(pop(vector)); # prints "nil"
}}

=== range() ===
{{Nasal doc
|syntax = range([start, ]stop[, step]);
|source = {{simgear file|simgear/nasal/lib.c|l=756|t=Source}}
|text = Creates a vector of numbers starting from <code>start</code> (default 0) up to but not including <code>stop</code>, incremented by <code>step</code> (default 1). Note: To specify <code>step</code>, you must also provide <code>start</code>; otherwise the second argument is interpreted as <code>stop</code>.
|param1 = start
|param1text = Optional. The starting number of the sequence. Defaults to 0 if omitted. Required if you want to specify <code>step</code>.
|param2 = stop
|param2text = Required. The number at which to stop the sequence (not included).
|param3 = step
|param3text = Optional. The increment between each number in the sequence. Defaults to 1. Only valid if <code>start</code> is also specified.
|example1 =
var vec = range(5); # Creates a vector [0, 1, 2, 3, 4]
var vec = range(2, 5); # Creates a vector [2, 3, 4]
var vec = range(0, 10, 2); # Creates a vector [0, 2, 4, 6, 8]
var vec = range(0, 0); # Creates an empty vector []
var vec = range(0, 1); # Creates a vector [0]
}}

=== remove() ===
{{Nasal doc
|syntax = remove(vector, value);
|source = {{simgear file|simgear/nasal/lib.c|l=53|t=Source}}
|text = Removes all elements equal to the given value from a vector and returns the modified vector.
|param1 = vector
|param1text = The vector from which elements are to be removed.
|param2 = value
|param2text = A value to remove from the vector.
|example1 =
var vector = [1, 2, 3]; # Initialize the vector.
remove(vector, 2); # Remove the value 2 from the vector.
debug.dump(vector); # Print the contents of the vector: "[1, 3]".
|example2 =
var vector = ["text", "text", "text"]; # Initialize the vector.
remove(vector, "text"); # Remove the value "text" from the vector.
debug.dump(vector); # Print the contents of the vector: "[]".
}}

=== removeat() ===
{{Nasal doc
|syntax = removeat(vector, index);
|source = {{simgear file|simgear/nasal/lib.c|l=72|t=Source}}
|text = Removes the element at the specified index from the vector and returns it.
|param1 = vector
|param1text = The vector from which the element will be removed.
|param2 = index
|param2text = Index of the item to be deleted.
|example1 =
var vector = [1, 2, 3]; # Initialize the vector.
removeat(vector, 0); # Remove the index 0 from the vector.
debug.dump(vector); # Print the contents of the vector: "[2, 3]".
}}

===right()===
{{Nasal doc
|syntax = right(string, length);
|source = {{simgear file|simgear/nasal/lib.c|l=226|t=Source}}
|version = 2.12
|commit = {{simgear commit|bd7163|t=commit}}
|text = Returns a substring of '''string''', starting from the right.
|param1 = string
|param1text = String to return part of.
|param2 = length
|param2text = Integer specifying the length of the substring to return.
|example1 = print(right("string", 2)); # prints "ng"
}}

=== setsize()===
{{Nasal doc
|syntax = setsize(vector, size);
|source = {{simgear file|simgear/nasal/lib.c|l=91|t=Source}}
|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.
|param1 = vector
|param1text = The vector to be operated on.
|param2 = size
|param2text = The desired size of the vector in number of entries.
|example1 =
var vector = [1, 2, 3]; # Initialize a vector
setsize(vector, 4);
debug.dump(vector); # print the vector "[1, 2, 3, nil]"
|example2 =
var vector = [1, 2, 3]; # Initialize a vector
setsize(vector, 2);
debug.dump(vector); # print the vector "[1, 2]"
}}

===size()===
{{Nasal doc
|syntax = size(object);
|source = {{simgear file|simgear/nasal/lib.c|l=26|t=Source}}
|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>.
|param1 = object
|param1text = Object to find the size of. Must be a string, a vector or a hash.
|example1 =
var string = "string";
print(size(string)); # prints "6"
|example2 =
var vector = [1, 2, 3];
print(size(vector)); # prints "3"
|example3 =
var hash = {
element1: "value1",
element2: "value2",
element3: "value3"
};
print(size(hash)); # prints "3"
}}

=== sort()===
{{Nasal doc
|syntax = sort(vector, function);
|source = {{simgear file|simgear/nasal/lib.c|l=678|t=Source}}
|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.
|param1 = vector
|param1text = Input vector to sort.
|param2 = function
|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.
{{{!}} class="wikitable"
! Return value !! Meaning
{{!-}}
{{!}} less than 0 {{!!}} first argument should go before second argument
{{!-}}
{{!}} 0 {{!!}} first argument equals second argument
{{!-}}
{{!}} greater than 0 {{!!}} first argument should go after second argument
{{!}}}

|example1text = This example sorts elements from smallest to greatest.
|example1 =
var sort_rules = func(a, b) {
if (a < b) {
return -1; # A should before b in the returned vector
} elsif (a == b) {
return 0; # A is equivalent to b
} else {
return 1; # A should after b in the returned vector
}
}
debug.dump(sort([3, 2, 5, 6, 4, 1], sort_rules)); # prints "[1, 2, 3, 4, 5, 6]"
|example2text = This example sorts elements from greatest to smallest.
|example2 =
# Outputs the elements in reverse order (greatest to smallest)
var sort_rules = func(a, b) {
if (a < b) {
return 1; # -1 in the above example
} elsif (a == b) {
return 0;
} else {
return -1; # 1 in the above example
}
}
debug.dump(sort([3, 2, 5, 6, 4, 1], sort_rules)); # prints "[6, 5, 4, 3, 2, 1]"
|example3text = This example sorts a vector of strings (runways for example) from smallest to greatest.
|example3 =
var runways = ["09R", "27R", "26L", "09L", "15"];
var rwy = sort(runways, func(a, b) cmp(a, b));
debug.dump(rwy); # prints ['09L', '09R', '15', '26L', '27R']
}}

=== split()===
{{Nasal doc
|syntax = split(delimiter, string);
|source = {{simgear file|simgear/nasal/lib.c|l=596|t=Source}}
|text = Splits the input string into a vector of substrings bounded by occurrences of the delimiter substring. See [[Nasal_library/string#string.join(sep,list)|string.join()]].
|param1 = delimiter
|param1text = String that will split the substrings in the returned vector.
|param2 = string
|param2text = String to split up.
|example1 = debug.dump(split("cd", "abcdef")); # prints "['ab', 'ef']"
|example2 = debug.dump(split(".", "3.2.0")); # prints "[3, 2, 0]"
|example3 = debug.dump(split("/", "path/to/file")); # prints "['path', 'to', 'file']"
}}

===sprintf()===
{{Nasal doc
|syntax = <nowiki>sprintf(format[, arg[, arg, [...]]]);</nowiki>
|source = {{simgear file|simgear/nasal/lib.c|l=491|t=Source}}
|text = Creates and returns a string formatted using ANSI C {{func link|vsnprintf()|link=http://en.cppreference.com/w/c/io/vfprintf}} <ref>
{{Cite web
|url = http://sourceforge.net/p/flightgear/simgear/ci/next/tree/simgear/nasal/lib.c#l308
|title = fgdata/simgear/simgear/nasal/lib.c, line 308
|accessdate = October 2015
}}
</ref>. Below is a table of supported format specifiers.
{{{!}} class="wikitable" width="75%"
{{!}}+ %[flags][width][.precision]specifier
! colspan="2" {{!}} Flags
{{!-}}
! Flag !! Output
{{!-}}
{{!}} <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.
{{!-}}
{{!}} ''space'' {{!!}} Prefixes non-signed numbers with a space.
{{!-}}
{{!}} <code>-</code> {{!!}} Left-align the output of this placeholder (the default is to right-align the output) when the width option is specified.
{{!-}}
{{!}} <code>0</code> {{!!}} Use 0 instead of spaces to pad a field when the width option is specified.
{{!-}}
{{!}} <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.
{{!-}}
! colspan="2" {{!}} Width
{{!-}}
{{!}} 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.
{{!-}}
! colspan="2" {{!}} Precision
{{!-}}
{{!}} colspan="2" {{!}} Integer preceded by a dot specifying the number of decimal places to be written.
{{!-}}
! colspan="2" {{!}} Specifiers
{{!-}}
! Specifier !! Output
{{!-}}
{{!}} <code>d</code>, <code>i</code> {{!!}} Signed decimal number.
{{!-}}
{{!}} <code>s</code> {{!!}} A string
{{!-}}
{{!}} <code>%</code> {{!!}} Percent (%) character.
{{!-}}
{{!}} <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.
{{!-}}
{{!}} <code>o</code> {{!!}} Unsigned integer as an octal number.
{{!-}}
{{!}} <code>u</code> {{!!}} Unsigned decimal integer.
{{!-}}
{{!}} <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.
{{!-}}
{{!}} <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.
{{!-}}
{{!}} <code>f</code> {{!!}} Floating-point number, in fixed decimal notation, by default with 6 decimal places.
{{!-}}
{{!}} <code>F</code> {{!!}} Appears to be available<ref>
{{Cite web
|url = http://sourceforge.net/p/flightgear/simgear/ci/next/tree/simgear/nasal/lib.c#l389
|title = fgdata/simgear/simgear/nasal/lib.c, line 389
|accessdate = October 2015
}}
</ref>, but doesn't work.
{{!-}}
{{!}} <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.
{{!}}}

|param1 = format
|param1text = String specifying the format. Can be used with or without a format specifiers. See below for examples.
|param2 = arg
|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.

|example1 = print(sprintf("%i", 54)); # prints "54"
|example2 = print(sprintf("Pi = %+.10f", math.pi)); # prints "Pi = +3.1415926536"
|example3 =
print(sprintf("%6d", 23)); # prints " 23"
print(sprintf("%06d", 23)); # prints "000023"
|example4 =
var FGVer = getprop("/sim/version/flightgear");
print(sprintf("You have FlightGear v%s", FGVer)); # prints "You have FlightGear v<your version>"
|example5 =
print(sprintf("Hexadecimal 100000 = %X", 100000)); # prints "Hexadecimal 100000 = 186A0"
print(sprintf("Hexadecimal 100000 = %x", 100000)); # prints "Hexadecimal 100000 = 186a0"
|example6 = print(sprintf("Code 65 is %c", 65)); # prints "Code 65 is A"
|example7 =
print(sprintf("%e", 54)); # prints "5.400000e+001"
print(sprintf("%E", 54)); # prints "5.400000E+001"
|example8 = print(sprintf("%o", 54)); # prints "66"
|example9 = print(sprintf("50%% of 100 is %i", 100 / 2)); # prints "50% of 100 is 50"
|example10 =
print(sprintf("%.2f", 1.4)); # prints "1.40"
print(sprintf("%.1f", 1.4)); # prints "1.4"
print(sprintf("% 4.1f", 1.4)); # prints " 1.4"
print(sprintf("%04.1f", 1.4)); # prints "01.4"
print(sprintf("% 6.1f", 1.4)); # prints " 1.4"
print(sprintf("%06.1f", 1.4)); # prints "0001.4"
}}

===str()===
{{Nasal doc
|syntax = str(value);
|source = {{simgear file|simgear/nasal/lib.c|l=186|t=Source}}
|text = Convert given value (scalar) to string. If <code>value</code> is a number, it will be converted to a string. If <code>value</code> is a string, the same string will be returned. If <code>value</code> is not a scalar (hash, vector, nil), <code>nil</code> will be returned.
|param1 = value
|param1text = The value to convert to string.
|example1 =
var result = str(true); # result is a string "1"
var result = str(false); # result is a string "0"
var result = str(12); # result is a string "12"
var result = str(12.5); # result is a string "12.5"
var result = str(-12.5); # result is a string "-12.5"
var result = str("12.5"); # result is a string "12.5"
var result = str([1, 2]); # result is a nil
var result = str({ x: 0 }); # result is a nil
var result = str(nil); # result is a nil
}}

===streq()===
{{Nasal doc
|syntax = streq(a, b);
|source = {{simgear file|simgear/nasal/lib.c|l=164|t=Source}}
|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.}}
|param1 = a
|param1text = First argument for testing equality.
|param2 = b
|param2text = Second argument for testing equality.
|example1 = print(streq("0", "0")); # prints "1" (True)
|example2 =
print(0 == 0.0); # prints "1" (True)
print(streq("0", "0.0")); # prints "0" (False)
}}

===substr()===
{{Nasal doc
|syntax = substr(string, start [, length]);
|source = {{simgear file|simgear/nasal/lib.c|l=194|t=Source}}
|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).
|param1 = string
|param1text = String to return a substring from.
|param2 = start
|param2text = Integer specifying the start of a substring. Negative values specify a position from the end of the string.
|param3 = length
|param3text = Optional argument specifying the length of the substring. Defaults to the end of the string.
|example1 = print(substr("abcde", 1, 3)); # prints "bcd"
|example2 = print(substr("abcde", 1)); # prints "bcde"
|example3 = print(substr("abcde", 2, 1)); # prints "c"
|example4 = print(substr("abcde", -2)); # prints "de"
|example5 = print(substr("abcde", -3, 2)); # prints "cd"
}}

===subvec()===
{{Nasal doc
|syntax = subvec(vector, start[, length]);
|source = {{simgear file|simgear/nasal/lib.c|l=98|t=Source}}
|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).
|param1 = vector
|param1text = The vector to take the sub-vector from.
|param2 = start
|param2text = The starting point of the sub-vector within the given vector.
|param3 = length
|param3text = Optional argument specifying the length of the sub-vector, from the starting point.
'''Notes:'''
* Omitting the ''vector'' and ''start'' arguments is not an error (possibly it should be) but the return value is ''nil''.
* A negative ''start'' argument ''is'' an error. This seems wrong. Perhaps the language designer could comment.
* A value of ''start'' greater than ''size(vector)'' causes an error. A value equal to ''size(vector)'' returns an empty vector.
* 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.
|example1 =
var vector = [1, 2, 3];
debug.dump(subvec(vector, 0)); # prints "[1, 2, 3]"
|example2 =
var vector = [1, 2, 3];
debug.dump(subvec(vector, 1)); # prints "[2, 3]"
|example3 =
var vector = [1, 2, 3];
debug.dump(subvec(vector, 1, 1)); # prints "[2]"
}}

=== typeof()===
{{Nasal doc
|syntax = typeof(object);
|source = {{simgear file|simgear/nasal/lib.c|l=287|t=Source}}
|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.
|param1 = object
|param1text = Object to return the type of.
|example1 =
var object = nil;
print(typeof(object)); # prints "nil"
|example2 =
var object = "Hello world!";
print(typeof(object)); # prints "scalar"
|example3 =
var object = math.pi;
print(typeof(object)); # prints "scalar"
|example4 =
var object = [1, 2, 3];
print(typeof(object)); # prints "vector"
|example5 =
var object = {};
print(typeof(object)); # prints "hash"
|example6 =
var object = func {};
print(typeof(object)); # prints "func"
|example7 =
var object = airportinfo();
print(typeof(object)); # prints "ghost"
}}



==Extension functions==
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:
*{{flightgear file|src/Scripting/NasalPositioned.cxx}}
*{{flightgear file|src/Scripting/NasalSys.cxx}}
*{{fgdata file|Nasal/globals.nas}}

===abort()===
{{Nasal doc
|syntax = abort();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=565|t=Source}}
|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).
|example1text = This example will immediately stop FlightGear with an error, such as "FlightGear has stopped working."
|example1 = abort();
|example2text = For exiting FlightGear in a better way, please use the following code:
|example2 = fgcommand("exit");
}}

=== abs() ===
{{Nasal doc
|syntax = abs(number);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = This simple function returns the {{wikipedia|absolute value|noicon=1}} of the provided number.
|param1 = number
|param1text = This argument is required and should be a number.
|example1 = print(abs(1)); # prints "1"
|example2 = print(abs(-1)); # prints "1"
}}

===aircraftToCart() ===
This new function in FG 2017.2.1 takes coordinates in aircraft structural coordinate system, and translate them into geocentric coordinates.
Example for (5,6,7):
<syntaxhighlight lang="nasal">
var pos = aircraftToCart({x: -5, y: 6, z: -7});
var coord = geo.Coord.new();
coord.set_xyz(pos.x, pos.y, pos.z);
</syntaxhighlight>
Notice: x and z is inverted sign on purpose.
if you want lat. lon, alt from that, just call: (degrees and meters)

<syntaxhighlight lang="nasal">
coord.lat()
coord.lon()
coord.alt()
</syntaxhighlight>

===addcommand() ===
{{Nasal doc
|syntax = addcommand(name, code);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=659|t=Source}}
|version = 2.12
|commit = {{flightgear commit|7b663c|t=commit}}
|text = {{see also|Howto:Add new fgcommands to FlightGear}}

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.
|param1 = name
|param1text = This will become the name of the new fgcommand. Must be a string.
|param2 = code
|param2text = The code that will be executed when the fgcommand is run. Must be a function.
|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.
|example1 = addcommand("myFGCmd", func(node) {
print("fgcommand 'myFGCmd' has been run.");
props.dump( node );
});
fgcommand("myFGCmd", props.Node.new({foo:1, bar:2}) );
|example2text = This example demonstrates how parameters are defined in a new fgcommand.
|example2 = addcommand("myFGCmd", func(node){
print(node.getNode("number").getValue()); # prints the value of "number," which is 12
});
fgcommand("myFGCmd", props.Node.new({"number": 12}));
}}

===airportinfo()===
{{Nasal doc
|syntax = airportinfo();
airportinfo(type);
airportinfo(id);
airportinfo(lat, lon[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1024|t=Source}}
|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:
* '''parents''': A vector containing a hash of various functions to access information about the runway. These functions are:
** '''findBestRunwayForPos()''' return runway as ghost by given geo position, e.g. <code>var rwy = airportinfo().findBestRunwayForPos(geo.aircraft_position());</code>.
** '''runway()''' return runway as ghost by runway ID, e.g. <code>var rwy = airportinfo().runway("18R");</code>.
** '''runwaysWithoutReciprocals()''' return vector of runways as ghost.
** '''helipad()''' return helipad as ghost by helipad ID, e.g. <code>var heli = airportinfo().helipad("H19");</code>.
** '''tower()''' return hash with <code>lat</code>, <code>lon</code>, <code>elevation</code> fields.
** '''comms()''' return vector of hashes, each hash with <code>frequency</code> and <code>ident</code> fields.
** '''sids()''' return vector of strings with SID IDs.
** '''stars()''' return vector of strings with STAR IDs.
** '''getApproachList()''' return vector of string with approaches.
** '''parking()''' return vector of hashes, each hash with <code>lat</code>, <code>lon</code>, <code>elevation</code>, <code>name</code> fields.
** '''getSid()''' return SID as ghost, e.g. <code>var sid = airportinfo().getSid("SA1A");</code>.
** '''getStar()''' return STAR as ghost, e.g. <code>var star = airportinfo().getStar("KEILA1");</code>.
** '''getIAP()''' return IAP as ghost, e.g. <code>var iap = airportinfo().getIAP("ILS02");</code>.
** '''getApproach()''' return approach as ghost, e.g. <code>var approach = airportinfo().getApproach("ILS02");</code>.
** '''tostring()''' just return string "an airport ICAO".
** See also {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1902}}.
* '''lon''': Longitude of the location.
* '''lat''': Latitude of the location.
* '''has_metar''': True or false depending whether the airport has a [[METAR]] code defined for it.
* '''elevation''': Elevation of the location in metres.
* '''id''': ICAO code of the airport (or ID of the seaplane base/heliport).
* '''name''': Name of the airport/heliport/seaplane base.
* '''runways'''
** '''<runway name>'''
*** '''id''': Name of runway.
*** '''lat''': Latitude of the runway.
*** '''lon''': Longitude of the runway.
*** '''heading''': True heading of the runway.
*** '''length''': Length of the runway in metres.
*** '''width''': Width of the runway in metres.
*** '''surface''': Runway surface type.
*** '''threshold''': Length of the runway's {{wikipedia|displaced threshold}} in metres. Will return 0 if there is none.
*** '''stopway''': Length of the runway's stopway (the area before the threshold) in metres. Will return 0 if there is none.
*** '''reciprocal''': <code>runway</code> ghost of the reciprocal runway.
*** '''ils_frequency_mhz''': ILS frequency in megahertz.
*** '''ils''': <code>navaid</code> ghost of the ILS transmitter.
* '''helipads'''
** '''<helipad name>'''
*** '''id''': Name of helipad.
*** '''lat''': Latitude of the helipad.
*** '''lon''': Longitude of the helipad.
*** '''heading''': True heading of the helipad.
*** '''length''': Length of the helipad in metres.
*** '''width''': Width of the helipad in metres.
*** '''surface''': Helipad surface type.
* '''taxiways'''
** '''<taxiway name>'''
*** '''id''': Name of taxiway.
*** '''lat''': Latitude of the taxiway.
*** '''lon''': Longitude of the taxiway.
*** '''heading''': Heading of the taxiway.
*** '''length''': Length of the taxiway in metres.
*** '''width''': Width of the taxiway in metres.
*** '''surface''': Taxiway surface type.

Information is extracted in the same way as accessing members of a Nasal hash. For example:
<syntaxhighlight lang="nasal">
# prints to lengths of the runways of the nearest airport in feet and metres
var info = airportinfo();
print("-- Lengths of the runways at ", info.name, " (", info.id, ") --");
foreach(var rwy; keys(info.runways)){
print(rwy, ": ", math.round(info.runways[rwy].length * M2FT), " ft (", info.runways[rwy].length, " m)");
}
</syntaxhighlight>

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.
|param1 = id
|param1text = The {{wikipedia|International Civil Aviation Organization airport code|ICAO code|noicon=1}} of an airport to retrieve information about.
|param2 = type
|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).
: {{inote|Running this function without any parameters is equivalent to this:
: <syntaxhighlight lang="nasal">
airportinfo("airport");
</syntaxhighlight>
}}
|param3 = lat ''and'' lon
|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.
|example1 = var info = airportinfo();
print("Nearest airport: ", info.name, " (", info.id, ")"); # prints the name and ICAO code of the nearest airport
|example2 = var info = airportinfo("heliport");
print("Elevation of the nearest heliport: ", math.round(info.elevation * M2FT), " ft"); # prints the elevation and name of the nearest heliport
|example3 = var info = airportinfo("KSQL");
print("-- Runways of ", info.name, " (", info.id, "): --");
foreach(var rwy; keys(info.runways)) {
print(rwy); # prints the runways of KSQL
}
|example4 = var info = airportinfo(37.81909385, -122.4722484);
print("Coordinates of the nearest airport: ", info.lat, ", ", info.lon); # print the name and ICAO of the nearest airport to the Golden Gate Bridge
|example5 = var info = airportinfo(37.81909385, -122.4722484, "seaport");
print("Nearest seaplane base: ", info.name, " (", info.id, ")"); # print the name and ID of the nearest seaplane base to the Golden Gate Bridge
|example6text = This example prints the all information from an <code>airportinfo()</code> call.
|example6 = var info = airportinfo("KSFO");
print(info.name);
print(info.id);
print(info.lat);
print(info.lon);
print(info.has_metar);
print(info.elevation);
foreach(var rwy; keys(info.runways)){
print("-- ", rwy, " --");
print(info.runways[rwy].lat);
print(info.runways[rwy].lon);
print(info.runways[rwy].length);
print(info.runways[rwy].width);
print(info.runways[rwy].heading);
print(info.runways[rwy].stopway);
print(info.runways[rwy].threshold);
<nowiki>}</nowiki>
}}

===airwaysRoute() ===
{{Nasal doc
|syntax = airwaysRoute(start, end[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1933|t=Source}}
|text = {{see also|Nasal Flightplan}}
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.
|param1 = start
|param1text = Start waypoint, in the form of a waypoint ghost, such as that provided by {{func link|flightplan()}}.
|param2 = end
|param2text = Same as above.
|param3 = type
|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."
|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.
|example1 = var fp = flightplan();
var start = fp.getWP(0);
var end = fp.getWP(fp.getPlanSize() - 1);
var rt = airwaysRoute(start, end);
foreach(var wp; rt){
print(wp.wp_name); # print the waypoints in the computed route
}
|example2text = Exactly the same as above, but computes a low level path.
|example2 = var fp = flightplan();
var start = fp.getWP(0);
var end = fp.getWP(fp.getPlanSize() - 1);
var rt = airwaysRoute(start, end, "lowlevel");
foreach(var wp; rt){
print(wp.wp_name); # print the waypoints in the computed route
<nowiki>}</nowiki>
}}

===airway()===

{{Nasal doc
|syntax = airway(ident [, pos]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2644|t=Source}}
|text = {{see also|Nasal Flightplan}}
This function returns a ghost containing an airway of a specified id.
|param1 = ident
|param1text = a Positioned ghost (leg, navaid, airport) and so on, passed to the search function.
|param2 = pos
}}

===assert()===
{{Nasal doc
|syntax = assert(condition[, message]);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|version = 3.2
|commit = {{fgdata commit|8b16a7|t=commit}}
|text = Returns either true if the condition evaluates as true, or aborts with a {{func link|die()}} call, which can be customised.
|param1 = condition
|param1text = Condition to evaluate.
|param2 = message
|param2text = Optional message that will be used in any {{func link|die()}} call. Defaults to "assertion failed!"
|example1 = var a = 1;
var b = 2;
print(assert(a < b)); # prints "1" (true)
|example2 = var a = 1;
var b = 2;
assert(a > b, 'a is not greater than b'); # aborts with a custom error message
}}

===carttogeod()===
{{Nasal doc
|syntax = carttogeod(x, y, z);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=945|t=Source}}
|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>
|param1 = x
|param1text = Mandatory x-axis value, in metres.
|param2 = y
|param2text = Mandatory y-axis value, in metres.
|param3 = z
|param3text = Mandatory z-axis value, in metres.
|example1 = var (lat, lon, alt) = carttogeod(6378137, 0, 0); # point is the intersection of the prime meridian and equator.
print("Latitude: ", lat); # prints lat, lon and alt, which are all zero, see above
print("Longitude: ", lon);
print("Altitude: ", alt);
}}

===cmdarg()===
{{Nasal doc
|private = _cmdarg()
|syntax = cmdarg();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=513|t=Part 1}} {{!}} {{fgdata file|Nasal/globals.nas|t=Part 2}}
|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.
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:
* Bindings: This is needed so that the value of a joystick's axis can be accessed internally.
* 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).
* 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.
* 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>

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.

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.
|example1 = fgcommand("dialog-show", {"dialog-name": "cmdarg-demo"});
|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.
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>

<PropertyList>

<name>cmdarg-demo</name>
<layout>vbox</layout>

<text>
<label>Click "Close" to activate the demonstration (a message in the console).</label>
</text>

<button>
<legend>Close</legend>
<binding>
<command>nasal</command>
<script>print("Button binding root: '" ~ cmdarg().getPath() ~ "'");</script>
</binding>
<binding>
<command>dialog-close</command>
</binding>
</button>

</PropertyList>
</syntaxhighlight>
|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!"
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>

<PropertyList>

<name>cmdarg-demo</name>
<layout>vbox</layout>

<text>
<label>Click "Click me!" to activate the demonstration (the button's label will change).</label>
</text>

<button>
<legend>Click me!</legend>
<binding>
<command>nasal</command>
<script>change_label();</script>
</binding>
</button>

<button>
<legend>Close</legend>
<binding>
<command>dialog-close</command>
</binding>
</button>

<nasal>
<open><![CDATA[
var dlg_root = cmdarg();
var dlg_name = {"dialog-name": "cmdarg-demo"};
var change_label = func {
dlg_root.getNode("button[0]/legend").setValue("I've been changed!");
fgcommand("dialog-close", dlg_name);
fgcommand("dialog-show", dlg_name);
}
]]></open>
</nasal>

</PropertyList>
</syntaxhighlight>
|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]].
}}

===courseAndDistance()===
{{Nasal doc
|syntax = courseAndDistance(to);
courseAndDistance(from, to);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1668|t=Source}}
|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:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object with geodetic coordinates (cartesian coordinates will not be accepted)
|param1 = from
|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.
|param2 = to
|param2text = Like the first parameter, but defines the second point.
|example1text = This example demonstrates the usage of the function with the <code>airport</code> ghost type.
|example1 = var from = airportinfo("KSFO");
var to = airportinfo("KSQL");
var (course, dist) = courseAndDistance(from, to);
print(course); # prints course from KSFO to KSQL
print(dist); # prints distance in nm from KSFO to KSQL
|example2text = This example demonstrates the usage of the function with hashes containing ''lat'' and ''lon''.
|example2 = var from = {lat: 0, lon: 0};
var to = {lat: 1, lon: 1};
var (course, dist) = courseAndDistance(from, to);
print(course);
print(dist);
|example3text = This example demonstrates usage of a geo.Coord object.
|example3 = var from = geo.Coord.new().set_latlon(0, 0);
var to = geo.Coord.new().set_latlon(1, 1);
var (course, dist) = courseAndDistance(from, to);
print(course);
print(dist);
|example4text = This example demonstrates usage of differing parameter types.
|example4 = var from = airportinfo("KSFO");
var to = geo.Coord.new().set_latlon(0, 0);
var (course, dist) = courseAndDistance(from, to);
print(course);
print(dist);
|example5text = The same as above, but the other way round.
|example5 = var to = {lat: 1, lon: 1};
var (course, dist) = courseAndDistance(0, 0, to);
print(course);
print(dist);
|example6text = Usage of just one parameter.
|example6 = var dest = airportinfo("KSQL");
var (course, dist) = courseAndDistance(dest);
print("Turn to heading ", math.round(course), ". You have ", sprintf("%.2f", dist), " nm to go");
}}

===createFlightplan()===
{{Nasal doc
|syntax = createFlightplan(path);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2331|t=Source}}
|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.
|param1 = path
|param1text = Optional parameter defining the file from which a flightplan will be populated.
|example1 =
var path = getprop("/sim/fg-home") ~ "/Export/test.fgfp";
var flightplan = createFlightplan(path);
debug.dump(flightplan);
}}

===createDiscontinuity()===
{{Nasal doc
|syntax = createDiscontinuity();
|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.
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2045|t=Source}}
|version = 2016.1
|commit = {{flightgear commit|caead6|t=commit}}
}}
===createViaTo()===
{{Nasal doc
|syntax = createViaTo(airway, waypoint);
|text = Returns a <code>waypoint</code> ghost object. It represents a route "via '''airway''' to '''waypoint'''".
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2009|t=Source}}
|version = 2016.1
|commit = {{flightgear commit|caead6|t=commit}}
|param1 = airway
|param1text = The name of an airway.
|param2 = waypoint
|param2text = Must be in the airway and one of:
* The name of a waypoint.
* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, or <code>fix</code> ghost object.
}}
===createWP()===
{{Nasal doc
|syntax = createWP(pos, name[, flag]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1964|t=Source}}
|text = Creates a new waypoint ghost object.
|param1 = pos
|param1text = Dictates the position of the new waypoint. It can be one of the following:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. See example 4 below.
|param2 = name
|param2text = String that will become the name of the new waypoint.
|param3 = flag
|param3text = Optional string that will tell FlightGear what type of waypoint it is. Must be one of "sid," "star," "approach," "missed," or "pseudo."
|example1text = Creates a waypoint directly in front and 1 km away and appends it to the flight plan.
|example1 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);
var wp = createWP(pos, "NEWWP");
var fp = flightplan();
fp.appendWP(wp);
|example2 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);
var wp = createWP({lat: pos.lat(), lon: pos.lon()}, "NEWWP");
var fp = flightplan();
fp.appendWP(wp);
|example3 = var apt = airportinfo();
var wp = createWP(apt, "NEWWP");
var fp = flightplan();
fp.appendWP(wp);
|example4 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);
var wp = createWP(pos.lat(), pos.lon(), "NEWWP");
var fp = flightplan();
fp.appendWP(wp);
|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.
|example5 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);
var wp = createWP(pos, "NEWWP", "pseudo");
var fp = flightplan();
fp.appendWP(wp);
print(fp.getPlanSize());
fp.clearWPType("pseudo");
print(fp.getPlanSize());
}}

===createWPFrom()===
{{Nasal doc
|syntax = createWPFrom(object[, flag]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1989|t=Source}}
|text = Creates a new waypoint object from another object.
|param1 = object
|param1text = A ghost object. Must be a ghost type that is one of "airport," "navaid," "runway," or "fix."
|param2 = flag
|param2text = Optional string that will tell FlightGear what type of waypoint it is. Must be one of "sid," "star," "approach," "missed," or "pseudo."
|example1text = Creates a new waypoint and appends it to the flight plan.
|example1 = var apt = airportinfo("KSFO");
var wp = createWPFrom(apt);
var fp = flightplan();
fp.appendWP(wp);
|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.
|example2 = var apt = airportinfo("KSFO");
var wp = createWPFrom(apt, "pseudo");
print(wp.wp_name);
var fp = flightplan();
fp.appendWP(wp);
print(fp.getPlanSize());
fp.clearWPType("pseudo");
print(fp.getPlanSize());
}}

===defined()===
{{Nasal doc
|syntax = defined(symbol);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = Returns 1 (true) or 0 (false) depending on whether a variable exists.
|param1 = symbol
|param1text = A string that will be what the function searches for.
|example1 = var number = 12;
var check_exist = func {
print("Variable 'number' ", defined("number") == 1 ? "exists" : "does not exist"); # 'number' does exist
print("Variable 'number2' ", defined("number2") == 1 ? "exists" : "does not exist"); # 'number2' does not exist
}
check_exist();
}}

===directory()===
{{Nasal doc
|syntax = directory(path);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=572|t=Source}}
|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.
{{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.}}
|param1 = path
|param1text = Absolute file path.
|example1text = Gets the folders and files in [[$FG_ROOT]], and then removes the extra first two elements (see note above).
|example1 = var dir = directory(getprop("/sim/fg-root")); # get directory
dir = subvec(dir, 2); # strips off the first two elements
debug.dump(dir); # dump the vector
}}

===fgcommand()===
{{Nasal doc
|syntax = fgcommand(cmd[, args]);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=456|t=Part 1}} {{!}} {{fgdata file|Nasal/globals.nas|t=Part 2}}
|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.
|param1 = cmd
|param1text = String that is the name of the command that is to be run.
|param2 = args
|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).
|example1 = fgcommand("null"); # does nothing
|example2 = var args = props.Node.new({'script': 'print("Running fgcommand");'});
if (fgcommand("nasal", args)) { # prints "Running fgcommand" and then one of these print statements
print("Fgcommand succeeded");
} else {
print("Fgcommand encountered a problem");
}
|example3 = var args = { 'dialog-name': 'about' };
fgcommand("dialog-show", args); # shows the 'about' dialog
}}

===findAirportsByICAO() ===
{{Nasal doc
|syntax = findAirportsByICAO(search[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1096|t=Source}}
|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.
|param1 = search
|param1text = Search string for the function. Can either be a partial or a full ICAO code.
:{{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.}}
|param2 = type
|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."
|example1 = var apts = findAirportsByICAO("KSF"); # finds all airports matching "KSF"
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")"); # prints them
}
|example2 = var apts = findAirportsByICAO("SP0", "seaport"); # finds all seaplane bases matching "SP0"
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")"); # prints them
}
|example3 = var apt = findAirportsByICAO("XBET"); # one way to check if an airport does exist"
if (size(apt) == 0) {
print("Airport does not exist"); # this one will be printed
} else {
print("Airport does exist");
<nowiki>}</nowiki>
}}

===findAirportsWithinRange()===
{{Nasal doc
|syntax = findAirportsWithinRange([pos, ]range[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1066|t=Source}}
|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.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findAirportsWithinRange(lat, lon, range, type);</code>.
|param2 = range
|param2text = Mandatory number giving the range in nautical miles within which to search for airports/heliports/seaplane bases.only airports are searched for.
|param3 = type
|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."
|example1text = Searches for airports within 10 nm of [[KSFO]].
|example1 = var pos = airportinfo("KSFO");
var apts = findAirportsWithinRange(pos, 10);
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")");
}
|example2text = Searches for seaplane bases within 15 nm of [[KSFO]].
|example2 = var pos = airportinfo("KSFO");
var apts = findAirportsWithinRange(pos, 15, "seaport");
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")");
}
|example3text = Searches for airports within 10 nm of your current position.
|example3 = var apts = findAirportsWithinRange(10);
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")");
<nowiki>}</nowiki>
}}

===findCommByFrequencyMHz()===
findCommByFrequencyMHz([pos, ]freq[, type]);
[[sourceforge:p/flightgear/flightgear/ci/next/tree/src/Scripting/NasalPositioned.cxx#l1547|source]]

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.

'''pos'''

: Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findCommByFrequencyMHz(lat, lon, freq, type);</code>.
; freq
: Frequency, in megahertz, of the station to search for.
; type
: 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)
'''Example'''
var com = findCommByFrequencyMHz(123.6);
print("ID: ", com.id); # prints info about the comm station
print("Name: ", com.name);
print("Latitude: ", com.lat);
print("Longitude: ", com.lon);
print("Type: ", com.type);
print("Frequency: ", sprintf("%.3f", com.frequency), " Mhz");

=== findFixesByID() ===
{{Nasal doc
|syntax = findFixesByID([pos, ]id);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1627|t=Source}}
|text = Returns a vector containing <code>fix</code> ghost objects matching a given ID, sorted by range from a certain position.
{{inote|Fixes are (usually) also known as waypoints.}}
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findFixesByID(lat, lon, id);</code>.
|param2 = id
|param2text = Full or partial ID of the fix to search for.
:{{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.}}
|example1 = var fixes = findFixesByID("POGIC");
foreach(var fix; fixes){
print(fix.id, " - lat: ", fix.lat, " {{!}} lon: ", fix.lon); # prints information about POGIC
}
|example2 = var fix = findFixesByID("ZUNAP");
fix = fix[0];
var (course, dist) = courseAndDistance(fix);
print("Turn to heading ", math.round(course), ". You have ", sprintf("%.2f", dist), " nm to go to reach ", fixes[0].id);
}}

===findNavaidByFrequencyMHz()===
{{Nasal doc
|syntax = findNavaidByFrequencyMHz([pos, ]freq[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1547|t=Source}}
|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.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidByFrequencyMHz(lat, lon, freq, type);</code>.
|param2 = freq
|param2text = Frequency, in megahertz, of the navaid to search for.
|param3 = type
|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}}.
|example1 = var navaid = findNavaidByFrequencyMHz(109.55);
print("ID: ", navaid.id); # prints info about the navaid
print("Name: ", navaid.name);
print("Latitude: ", navaid.lat);
print("Longitude: ", navaid.lon);
print("Elevation (AMSL): ", navaid.elevation, " m");
print("Type: ", navaid.type);
print("Frequency: ", sprintf("%.3f", navaid.frequency / 100), " Mhz");
print("Range: ", navaid.range_nm, " nm");
if(navaid.course) print("Course: ", navaid.course);
}}

=== findNavaidsByFrequencyMHz()===
{{Nasal doc
|syntax = findNavaidsByFrequencyMHz([pos, ]freq[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1572|t=Source}}
|text = Returns a vector conatining <code>navaid</code> ghost objects for navaids that match a given frequency, sorted from nearest to furthest.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidsByFrequencyMHz(lat, lon, freq, type);</code>.
|param2 = freq
|param2text = Frequency, in megahertz, of the navaid to search for.
|param3 = type
|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}}.
|example1 = var navaids = findNavaidsByFrequencyMHz(109.55);
foreach(var navaid; navaids){
print("--");
print("ID: ", navaid.id); # prints info about the navaid
print("Name: ", navaid.name);
print("Latitude: ", navaid.lat);
print("Longitude: ", navaid.lon);
print("Elevation (AMSL): ", navaid.elevation, " m");
print("Type: ", navaid.type);
print("Frequency: ", sprintf("%.3f", navaid.frequency / 100), " Mhz");
print("Range: ", navaid.range_nm, " nm");
if(navaid.course) print("Course: ", navaid.course);
print("--");
<nowiki>}</nowiki>
}}

===findNavaidsByID()===
{{Nasal doc
|syntax = findNavaidsByID([pos, ]id[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1600|t=Source}}
|text = Returns a vector containing <code>navaid</code> ghost objects matching a given ID, sorted by range from a certain position.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidsByID(lat, lon, id, type);</code>.
|param2 = id
|param2text = Full or partial ID of the fix to search for.
:{{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.}}
|param3 = type
|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}}.
|example1 = var navaid = findNavaidsByID("MXW");
navaid = navaid[0];
print("ID: ", navaid.id); # prints info about 'MXW' (a VOR station)
print("Name: ", navaid.name);
print("Latitude: ", navaid.lat);
print("Longitude: ", navaid.lon);
print("Elevation (AMSL): ", navaid.elevation, " m");
print("Type: ", navaid.type);
print("Frequency: ", sprintf("%.3f", navaid.frequency / 1000), " Mhz");
print("Range: ", navaid.range_nm, " nm");
}}

===findNavaidsWithinRange()===
{{Nasal doc
|syntax = findNavaidsWithinRange([pos, ]range[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1518|t=Source}}
|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.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidsWithinRange(lat, lon, range, type);</code>.
|param2 = range
|param2text = Mandatory number giving the range in nautical miles within which to search for navaids.
|param3 = type
|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}}.
|example1text = Searches for navaids within 10 nm of [[KSFO]].
|example1 = var pos = airportinfo("KSFO");
var navs = findNavaidsWithinRange(pos, 10);
foreach(var nav; navs){
print(nav.name, " (ID: ", nav.id, ")");
}
|example2text = Searches for navaids within 10 nm of your current position.
|example2 = var navs = findNavaidsWithinRange(10);
foreach(var nav; navs){
print(nav.name, " (ID: ", nav.id, ")");
<nowiki>}</nowiki>
}}

===finddata()===
{{Nasal doc
|syntax = finddata(path);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=603|t=Source}}
|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]].
|param1 = path
|param1text = A relative path as a string.
|example1 = var path = finddata("Aircraft/Generic");
print(path); # prints the absolute path to $FG_ROOT/Aircraft/Generic
|example2 = var path = finddata("Airports");
print(path); # prints the absolute path to <TerraSync dir>/Airports
|example3 = var path = finddata("preferences.xml");
print(path); # prints the absolute path to $FG_ROOT/preferences.xml
}}

===flightplan()===
{{Nasal doc
|syntax = flightplan([path]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1738|t=Source}}
|text = {{see also|Nasal Flightplan}}
Returns a flight plan object, either one for the current flight plan, or one loaded from a given path.
|param1 = path
|param1text = Optional path to flight plan XML file.
|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.
|example1 = var fp = flightplan();
print(fp.getWP(fp.current).id);
|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>.
|example2 = var path = getprop('/sim/fg-home') ~ '/fp-demo.xml';
var fp = flightplan(path);
for(var i = 0; i < fp.getPlanSize(); i += 1){
print(fp.getWP(i).id);
<nowiki>}</nowiki>
}}

===geodinfo()===
{{Nasal doc
|syntax = geodinfo(lat, lon[, max_alt]);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=981|t=Source}}
|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}}):
* '''light_coverage:''' The coverage of a single point of light in m<sup>2</sup>.
* '''bumpiness:''' Normalized bumpiness factor for the material.
* '''load_resistance:''' The amount of pressure in N/m<sup>2</sup> the material can withstand without deformation.
* '''solid:''' 1 (true) or false (0) depending on whether the material is solid or not.
* '''names:''' Vector of scenery types (usually generated by [[TerraGear]]) that will use this material.
* '''friction_factor:''' Normalized friction factor of the material.
* '''rolling_friction:''' The rolling friction coefficient of the material.

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.
|param1 = lat
|param1text = Latitude, inputted as a number.
|param2 = lon
|param2text = Longitude, inputted as a number.
|param3 = max_alt
|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.
|example1text = Dumps information about ground underneath the aircraft.
|example1 = var pos = geo.aircraft_position();
var info = geodinfo(pos.lat(), pos.lon());
debug.dump(info);
|example2text = Prints whether the ground underneath the aircraft is solid or is water.
|example2 = var pos = geo.aircraft_position();
var info = geodinfo(pos.lat(), pos.lon());
if (info != nil and info[1] != nil) {
print("The ground underneath the aircraft is ", info[1].solid == 1 ? "solid." : "water.");
<nowiki>}</nowiki>
}}

=== geodtocart() ===
{{Nasal doc
|syntax = geodtocart(lat, lon, alt);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=962|t=Source}}
|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.
|param1 = lat
|param1text = Latitude, in degrees.
|param2 = lon
|param2text = Longitude, in degrees.
|param3 = alt
|param3text = Altitude, in metres.
|example1 = var (x, y, z) = geodtocart(0, 0, 0); # point is the intersection of the prime meridian and equator.
print("x: ", x); # prints "x: 6378137"
print("y: ", y); # prints "y: 0"
print("z: ", z); # prints "y: 0"
}}

=== get_cart_ground_intersection()===
Introduced in 2017.2.1, see [[Terrain Detection]].

===getprop()===
{{Nasal doc
|syntax = <nowiki>getprop(path[, path[, ...]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=345|t=Source}}
|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).
|param1 = path
|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.
|example1 = print("You have FlightGear v", getprop("/sim/version/flightgear")); # prints FlightGear version
|example2text = Note that the example below will only work in FlightGear 3.2 and above.
|example2 = for(var i = 0; i < 8; i += 1){
print("View #", i + 1, " is named ", getprop("/sim/view", i, "name"));
}
|example3text = Same as above, but is supported by all versions of FlightGear.
|example3 = for(var i = 0; i < 8; i += 1){
print("View #", i + 1, " is named ", getprop("/sim/view[" ~ i ~ "]/name"));
<nowiki>}</nowiki>
}}
==== See also====
{{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:
To get a Node rather than its value, use <code>props.globals.getNode()</code> - see [[Nasal_library/props]]. }}

===greatCircleMove()===
{{Nasal doc
|syntax = greatCircleMove([pos, ]course, dist);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1681|t=Source}}
|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).
|param1 = pos
|param1text = Optional position to calculate from. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost object.
:* A hash with ''lat'' and ''lon'' members
:* A <code>geo.Coord</code> object
:* A lat/lon pair, that is, a pair of numbers (latitude followed by longitude) separated by a comma: <code>greatCircleMove(lat,lon, ...)</code>.
|param2 = course
|param2text = Course to new set of coordinates, in degrees (in the range 0–360).
|param3 = dist
|param3text = Distance in nautical miles to the new set of coordinates.
|example1 = var pos = greatCircleMove(0,0, 0, 1);
debug.dump(pos); # print hash with coordinates
|example2 = var fix = findFixesByID("POGIC");
fix = fix[0];
var pos = greatCircleMove(fix, 45, 10);
debug.dump(pos); # print hash with coordinates
}}

===interpolate()===
{{Nasal doc
|private = _interpolate()
|syntax = <nowiki>interpolate(prop, value1, time1[, value2, time2[, ...]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=522|t=Part 1}} {{!}} {{fgdata file|Nasal/globals.nas|t=Part 2}}
|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.
|param1 = prop
|param1text = String or <code>props.Node</code> object that indicates a node in the property tree to be used.
|param2 = value''n''
|param2text = Target value to change the property to in the set amount of time. This should be a number.
|param3 = time''n''
|param3text = Time in seconds, that will be taken for the interpolation.
|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.
|example1 = setprop("/test", 0); # (re-)set property
interpolate("/test",
50, 5, # interpolate to 50 in 5 seconds
10, 2, # interpolate to 10 in 2 seconds
0, 5); # interpolate to 0 in 5 seconds
|example2 = # Apply the left brake at 20% per second
var prop = "controls/gear/brake-left";
var dist = 1 - getprop(prop);
if (dist == 1) {
interpolate(prop, 1, dist / 0.2);
<nowiki>}</nowiki>
}}

===isa()===
{{Nasal doc
|syntax = isa(object, class);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|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.
|param1 = object
|param1text = Object to check.
|param2 = class
|param2text = Class/object to check that '''object''' inherits from or is an instance of.
|example1 = var coord = geo.Coord.new();
if(isa(coord, geo.Coord)){
print("Variable 'coord' is an instance of class 'geo.Coord'"); # this one will be printed
} else {
print("Variable 'coord' is not an instance of class 'geo.Coord'");
}
|example2 = var coord = geo.Coord.new();
if(isa(coord, props.Node)){
print("Variable 'coord' is an instance of class 'props.Node'");
} else {
print("Variable 'coord' is not an instance of class 'props.Node'"); # this one will be printed
}
|example3text = The example below demonstrates checking of inheritance.
|example3 = var Const = {
constant: 2,
getConst: func {
return me.constant;
}
};

var Add = {
new: func {
return { parents: [Add, Const] };
},

addToConst: func(a){
return a * me.getConst();
}
};

var m = Add.new();
print(m.addToConst(4));

if(isa(m, Add)) print("Variable 'm' is an instance of class 'Add'"); # will be printed
if(isa(m, Const)) print("Variable 'm' is an instance of class 'Const'"); # will also be printed
}}

===logprint()===
{{Nasal doc
|syntax = <nowiki>logprint(priority[, msg[, msg[, ...]]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=431|t=Source}}
|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}}.
|param1 = priority
|param1text = Number specifying the priority level of the outputted message:
:{{{!}} class="wikitable"
! Number !! Debug type
{{!-}}
{{!}} 1 {{!!}} Bulk
{{!-}}
{{!}} 2 {{!!}} Debug
{{!-}}
{{!}} 3 {{!!}} Info
{{!-}}
{{!}} 4 {{!!}} Warn
{{!-}}
{{!}} 5 {{!!}} Alert
{{!}}}
|param2 = msg
|param2text = The message. There is no limit to the arguments you give give. They will be concatenated together before logging.
|example1 = # logs the value of pi to three decimal places with log level 3
logprint(3, "pi = ", sprintf("%.3f", math.pi));
|example2 = logprint(5, "Alert! This is an important message!");
}}
{{note|
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:

LOG_BULK, LOG_WARN, LOG_DEBUG, LOG_INFO, LOG_ALERT, DEV_WARN, DEV_ALERT }}

===magvar() ===
{{Nasal doc
|syntax = magvar([pos]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1642|t=Source}}
|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.
{{{!}} class="wikitable"
! FlightGear versions !! Model !! Reference date
{{!-}}
{{!}} 3.6 and above {{!!}} {{wikipedia|World Magnetic Model}} (WMM) 2015 {{!!}} 1 January 2015
{{!-}}
{{!}} 0.9.11-pre1 to 3.4 {{!!}} WMM 2005 {{!!}} 1 January 2005
{{!-}}
{{!}} 0.7.3 to 0.9.10 {{!!}} WMM 2000 {{!!}} 1 January 2000
{{!}}}
|param1 = pos
|param1text = Optional position to calculate from. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost object.
:* A hash with ''lat'' and ''lon'' members
:* A <code>geo.Coord</code> object
:* A lat/lon pair, that is, a pair of numbers (latitude followed by longitude) separated by a comma: <code>magvar(lat,lon)</code>.
|example1 = print(magvar(0, 0)); # prints the magnetic variation at 0, 0
}}

===maketimer() ===
{{Nasal doc
|syntax = maketimer(interval[, self], function);
|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}}
|version = 2.12
|commit = {{flightgear commit|ab939f|t=commit}}
|text = Returns a timer object containing the following methods and members:
* '''start()''': Starts the timer.
* '''stop()''': Stops the timer.
* '''restart(interval)''': Restarts the timer with the given interval.
* '''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).
* '''isRunning''': Read-only bool telling whether the timer is currently running.
* '''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.
Unlike {{func link|settimer()}}, which it replaces, <code>maketimer()</code> provides more control over the timer. In addition, it can help reduce memory usage.
|param1 = interval
|param1text = Interval in seconds for the timer.
|param2 = self
|param2text = Optional parameter specifying what any <code>'''me'''</code> references in the function being called will refer to.
|param3 = function
|param3text = Function to be called at the given interval.
|example1 = var timer = maketimer(1, func(){
print("Hello, World!"); # print "Hello, World!" once every second (call timer.stop() to stop it)
});
timer.start();
|example2 = var timer = maketimer(1, math, func(){
print(me.math); # 'me' reference is the 'math' namespace
});
timer.singleShot = 1; # timer will only be run once
timer.start();
|example3 = var timer = maketimer(1, func(){
print("Hello, World!"); # print "Hello, World!" once every second (call timer.stop() to stop it)
});
timer.start();
print(timer.isRunning); # prints 1
|example4text = In the example below, "Hello, World!" will be printed after one second the first time, and after two seconds thereafter.
|example4 = var update = func(){
print("Hello, World!");
timer.restart(2); # restarts the timer with a two second interval
}

var timer = maketimer(1, update);
timer.singleShot = 1;
timer.start();
}}

===maketimestamp()===
{{Nasal doc
|syntax = maketimestamp()
|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}}
|version = 2019.2
|commit = {{flightgear commit|7db06300|t=commit}}
|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:
* '''stamp()''': Resets the timing operation. Call this first.
* '''elapsedMSec()''': returns number of milliseconds elapsed since stamp() called. Resolution may vary depending on platform but is usually at least millisecond accuracy.
* '''elapsedUSec()''': returns number of microseconds elapsed since stamp() called. Resolution may vary depending on platform but is usually at least millisecond accuracy.
|
|example1text = In the example below the number of milliseconds elapsed will be printed.
|example1 = var timestamp = maketimestamp();
timestamp.stamp();
print(timestamp.elapsedMSec(), "ms elapsed");
print(timestamp.elapsedMSec(), "ms elapsed");
}}

===md5()===
{{Nasal doc
|syntax = md5(string);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=758|t=Source}}
|version = 3.2
|commit = {{flightgear commit|cfbf9e|t=commit}}
|text = Returns a the {{wikipedia|MD5}} hash (as a string) of the inputted string.
|param1 = string
|param1text = String the generate the hash of. Mandatory.
|example1text = The below code should output <code>65a8e27d8879283831b664bd8b7f0ad4</code>.
|example1 = print(md5("Hello, World!"));
}}

===navinfo()===
{{Nasal doc
|syntax = navinfo(lat, lon, type, id);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1453|t=Source}}
|text = Returns vector <code>navaid</code> ghost objects matching the given '''type''' and '''id''' or <code>'''nil'''</code> on error.
|param1 = lat ''and'' lon
|param1text = If given, the returned navaids will be put into order of ascending distance from the location.
|param2 = type
|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."
|param3 = id
|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.
|example1 = navinfo("vor"); # returns all VORs
|example2 = navinfo("HAM"); # return all navaids whose names start with "HAM"
|example3 = navinfo("vor", "HAM"); # return all VORs whose names start with "HAM"
|example4 = navinfo(34,48,"vor","HAM"); # return all VORs whose names start with "HAM" and sorted by distance relative to 34°, 48°
}}

===parse_markdown()===
{{Nasal doc
|syntax = parse_markdown(markdown);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=745|t=Part 1}} {{!}} {{simgear file|simgear/misc/SimpleMarkdown.cxx|t=Part 2}}
|version = 3.2
|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:
* It strips whitespace from the beginning of the string.
* It supports [http://daringfireball.net/projects/markdown/syntax#p paragraphs and line breaks].
* It collapses whitespace.
* It converts unordered [http://daringfireball.net/projects/markdown/syntax#list lists] to use a bullet character (•). 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.
|param1 = markdown
|param1text = String containing Markdown to be parsed.
|example1text =
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>).
<syntaxhighlight lang="xml" highlight="41-50">
<?xml version="1.0" encoding="UTF-8"?>

<PropertyList>

<name>test</name>
<layout>vbox</layout>

<group>
<layout>hbox</layout>

<empty>
<stretch>true</stretch>
</empty>

<text>
<label>parse_markdown() test dialog</label>
</text>

<empty>
<stretch>true</stretch>
</empty>

<button>
<legend></legend>
<pref-width>16</pref-width>
<pref-height>16</pref-height>
<binding>
<command>dialog-close</command>
</binding>
</button>

</group>

<canvas>
<name>Canvas plot</name>
<stretch>true</stretch>
<pref-width>400</pref-width>
<pref-height>300</pref-height>
<nasal>
<load><![CDATA[
var text = 'Items:
* apples
* oranges
* pears

Some text.
Some more items:
* apples
* oranges
* pears';

var parsed = parse_markdown(text);

var root_canvas = canvas.get(cmdarg());
root_canvas.setColorBackground(255, 255, 255);
var root = root_canvas.createGroup();

var text_dis = root.createChild("text")
.setText(parsed)
.setTranslation(5, 5)
.setFont("LiberationFonts\LiberationSans-Regular.ttf")
.setFontSize(15)
.setColor(0, 0, 0)
.setDrawMode(canvas.Text.TEXT)
.setAlignment("left-top");
]]></load>
</nasal>
</canvas>

</PropertyList>
</syntaxhighlight>
|example1 = fgcommand("dialog-show", {"dialog-name": "test"});
|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.
|example2 = <nowiki>var markdown = 'Items:
* apples
* oranges
* pears

Some text.
Some more items:
* apples
* oranges
* pears';

var parsed = parse_markdown(markdown);

debug.dump(parsed);

var path = string.normpath(getprop("/sim/fg-home") ~ '/Export/parse_markdown()-test.html');

var file = io.open(path, "w");

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>";

io.write(file, html);
io.close(file);
print("Done, file ready for viewing (" ~ path ~ ")");</nowiki>
}}

===parsexml()===
{{Nasal doc
|syntax = <nowiki>parsexml(path[, start[, end[, data[, pro_ins]]]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=710|t=Source}}
|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.
|param1 = path
|param1text = Mandatory absolute path to the XML file to be parsed.
|param2 = start
|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.
|param3 = end
|param3text = Optional callback function that will be called for every ending tag. The function should take one argument: the tag name.
|param4 = data
|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.
|param5 = pro_ins
|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.
|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.
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>

<?xml-stylesheet type="text/xsl" href="style.xsl"?>

<foo>
<blah type="string"><![CDATA[ <sender>John Smith</sender> ]]></blah>
<blah2 type="string">Orange & lemons</blah2>
</foo>
</syntaxhighlight>
|example1 = var start = func(name, attr){
print("Starting tag: '", name, "'");
foreach(var a; keys(attr)){
print("\twith attribute ", a, '="', attr[a], '"');
}
}

var end = func(name){
print("Ending tag: '", name, "'");
}

var data = func(data){
print("Data = '", data, "'");
}

var pro_instr = func(target, data){
print("Processing instruction: target = '", target, "', data = '", data, "'");
}

parsexml(getprop("/sim/fg-home") ~ '/Export/demo.xml', start, end, data, pro_instr);
}}

===print()===
{{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.

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>}}

{{Nasal doc
|syntax = <nowiki>print(data[, data[, ...]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=415|t=Source}}
|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.
|param1 = data
|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.
|example1 = print("Just", " a ", "test"); # prints "Just a test"
|example2 = print("pi = ", math.pi); # prints "pi = 3.141592..."
}}

=== printf() ===
{{Nasal doc
|syntax = <nowiki>printf(format[, arg[, arg, [...]]]);</nowiki>
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|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>).
|example1 = printf("In hexadecimal, 100000 = %X", 186A0); # prints "In hexadecimal, 100000 = 186A0"
}}

===printlog()===
{{caution|This function is deprecated and doesn't work. Please use the new one {{func link|logprint()}}.}}
{{Nasal doc
|syntax = <nowiki>printlog(level, data[, data[, ...]]);</nowiki>
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|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.
|param1 = level
|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.
|param2 = data
|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.
|example1 = printlog("alert", "This is an alert"); # message will be printed
|example2 = printlog("info", "Just informing you about something"); # message will be printed only if log level is set to "info" or less
}}

===rand()===
{{Nasal doc
|syntax = rand();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=554|t=Source}}
|text = Returns a random floating point number between 0 (inclusive) and 1 (exclusive). It takes no arguments.
|example1 = print(rand()); # prints random number
}}

===registerFlightPlanDelegate()===
{{Nasal doc
|syntax = registerFlightPlanDelegate(init_func);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1879|t=Source}}
|text = Registers a flight plan delegate. See <tt>''{{fgdata file|Nasal/route_manager.nas|t=$FG_ROOT/Nasal/route_manager.nas}}''</tt> for examples.
|param1 = init_func
|param1text = Initialization function which will be called during FlightGear's startup.
}}
===removecommand()===
{{Nasal doc
|syntax = removecommand(cmd);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=668|t=Source}}
|text = Removes the given fgcommand. Returns <code>'''nil'''</code>.
{{caution|This will remove '''any''' [[fgcommands|fgcommand]], even those implemented in C++, so use with caution!}}
|param1 = cmd
|param1text = String specifying the name of the command to remove.
|example1 = addcommand("hello", func(){
print("Hello");
});
fgcommand("hello"); # "Hello" will be printed
removecommand("hello"); # removes it
}}

===removelistener()===
{{Nasal doc
|syntax = removelistener(id);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=1384|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=506|t=Part 2}}
|text = Removes and deactivates the given listener and returns the number of listeners left or <code>'''nil'''</code> on error.
{{note|It is good practice to remove listeners when they are not required anymore. This prevents the listeners reducing FlightGear's run performance.}}
|param1 = id
|param1text = ID of listener as returned by {{func link|setlistener()}}.
|example1 = var ls = setlistener("/sim/test", func(){
print("Property '/sim/test' has been changed");
});
setprop("/sim/test", "blah"); # trigger listener
var rem = removelistener(ls); # remove listener
print("There are ", rem, " listeners remaining");
}}

===resolvepath()===
{{Nasal doc
|syntax = resolvepath(path);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=604|t=Source}}
|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.
|param1 = path
|param1text = Relative path to be completed.
|example1 = print(resolvepath("Nasal/globals.nas")); # prints the equivalent of $FG_ROOT/Nasal/globals.nas
|example2 = print(resolvepath("blah")); # prints nothing; could not be resolved
|example3 = var file_path = resolvepath("Aircraft/SenecaII/some-file");
if (file_path != ""){
gui.popupTip("some-file found", 2);
} else {
gui.popupTip("some-file not found", 2);
<nowiki>}</nowiki>
}}

===setlistener()===
{{Nasal doc
|syntax = <nowiki>setlistener(node, code[, init[, type]]);</nowiki>
|private = _setlistener()
|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.''
|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()}}.
{{note|Listeners are known to be a source of resource leaks. To avoid this, please take measures such as:
* Using {{func link|removelistener()}} when they are not needed any more.
* Using a single initialization listener.
* Avoiding tying listeners to properties that are rapidly updated (e.g., many times per frame).
}}
|param1 = node
|param1text = Mandatory string or <code>props.Node</code> object pointing to a property in the [[Property Tree]].
|param2 = code
|param2text = Mandatory callback function to execute when the listener is triggered. The function can take up to four arguments in the following order:
* '''changed''': a <code>props.Node</code> object pointing to the changed node.
* '''listen''': a <code>props.Node</code> object pointing to the listened-to node. Note that this argument maybe different depending on the '''type'''.
* '''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.
* '''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.
|param3 = init
|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).
|param4 = type
|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.
|example1 = var prop = props.globals.initNode("/sim/test", "", "STRING"); # create property
var id = setlistener("/sim/test", func(n){ # create listener
print("Value: ", n.getValue());
});
setprop("/sim/test", "blah"); # trigger listener
removelistener(id); # remove listener
prop.remove(); # remove property
}}

===setprop()===
{{Nasal doc
|syntax = <nowiki>setprop(path[, path[, ...]], value);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=385|t=Source}}
|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.
{{note|If you want to remove a property, you will have to use one of the <code>props</code> helpers:
<syntaxhighlight lang="nasal">
props.globals.getNode("foo/bar").remove(); # take out the complete node
props.globals.getNode("foo").removeChild("bar"); # take out a certain child node
</syntaxhighlight>
}}
|param1 = path
|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.
|param2 = value
|param2text = Value to write to the given property. Must be either a string or a number.
|example1 = setprop("/sim/demo", "This is a demo");
|example2text = Note that the example below will only work in FlightGear 3.2 and above.
|example2 = for(var i = 0; i < 3; i += 1){
setprop("/sim/demo", i, "Demo #" ~ i));
}
|example3text = Same as above, but is supported by all versions of FlightGear.
|example3 = for(var i = 0; i < 3; i += 1){
setprop("/sim/demo[" ~ i ~ "]", "Demo #" ~ i));
<nowiki>}</nowiki>
}}
====See also====
{{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:
To get a Node rather than its value, use <code>props.globals.getNode()</code> - see [[Nasal_library/props]]. }}

===settimer() ===
{{Nasal doc
|syntax = settimer(function, delta[, realtime]);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=499|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=1286|t=Part 2}}
|text = Runs the given function a specified amount of seconds after the current time. Returns <code>'''nil'''</code>.
{{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.}}
|param1 = function
|param1text = Mandatory function that will be called. It may be necessary to enclose code in an anonymous function (see example).
|param2 = delta
|param2text = Mandatory amount of time in seconds after which the function will be called.
|param3 = realtime
|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.
|example1 = var myFunc = func(){
print("Hello");
}

settimer(myFunc, 2); # runs myFunc after 2 seconds
|example2 = var sqr = func(a){
return a * a;
}

settimer(func(){
print(sqr(2)); # will print 4 after 2 seconds
}, 2);
}}

===srand() ===
{{Nasal doc
|syntax = srand();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=559|t=Source}}
|text = Makes the pseudorandom number generator (see {{func link|rand()}}) generate a new {{wikipedia|random seed|noicon=1}} based on time. Returns 0.
}}
===systime()===
{{Nasal doc
|syntax = systime();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=770|t=Source}}
|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).
{{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]}}
|example1 = print("Unix time: ", systime()); # prints Unix time
|example2 = var myFunc = func(){
for(var i = 0; i <= 10; i += 1){
print("Interation #", i);
}
}
var t = systime(); # record time
myFunc(); # run function
var t2 = systime(); # record new time
print("myFunc() took ", t2 - t, " seconds"); # print result
}}

===thisfunc()===
{{Nasal doc
|syntax = thisfunc();
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = Returns the function from which this function is called. This allows a function to reliably and safely call itself from within a closure.
|example1 = var stringify_vec = func(input){
if (typeof(input) == "scalar"){
return sprintf("%s", input);
} elsif (typeof(input) == "vector") {
if (size(input) == 0) return "[]";
var this = thisfunc();
var buffer = "[";
for(var i = 0; i < size(input); i += 1){
buffer ~= this(input[i]);
if (i == size(input) - 1) {
buffer ~= "]";
} else {
buffer ~= ", ";
}
}
return buffer;
} else {
die("stringify_vec(): Error! Invalid input. Must be a vector or scalar");
}
}

var test_vec = ["a", "b", "c", [1, 2, 3], "d"];
debug.dump(stringify_vec(test_vec)); # prints "[a, b, c, [1, 2, 3], d]"
test_vec = [];
debug.dump(stringify_vec(test_vec)); # prints "[]"
test_vec = {};
debug.dump(stringify_vec(test_vec)); # will throw an error
}}

===tileIndex() ===
{{Nasal doc
|syntax = tileIndex();
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1720|t=Source}}
|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>.
|example1 = print(tileIndex()); # print index
}}

=== tilePath()===
{{Nasal doc
|syntax = tilePath();
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1712|t=Source}}
|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>.
|example1 = print(tilePath()); # print path
}}

=== values()===
{{Nasal doc
|syntax = values(hash);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = Returns a vector containing the values of the given hash.
|param1 = hash
|param1text = Mandatory hash to get the values of.
|example1 = var hash = {
"a": 1,
"b": 2,
"c": 3
};

foreach(var val; values(hash)){
print(val);
}
|example2text = The below example does exactly the same thing as the above example, but does not use <code>values()</code>:
|example2 = var hash = {
"a": 1,
"b": 2,
"c": 3
};

foreach(var key; keys(hash)){
print(hash[key]);
<nowiki>}</nowiki>
}}

==Extension functions new in FG 2020.1 ==
The following functions have been added to the nasal core library and will be released with FlightGear version 2020.1.
Before the release they are available in the development branch "next".

===isfunc()===
Returns 1 if type or argument is a function, otherwise 0.

===isghost()===
Returns 1 if type or argument is a ghost, otherwise 0.

=== ishash()===
Returns 1 if type or argument is a hash, otherwise 0.

===isint()===
{{Nasal doc
|syntax = isint(x);
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}
|text = Returns 1 if argument has a numeric value and x == floor(x), e.g. integer.
}}

===isnum()===
{{Nasal doc
|syntax = isnum(x);
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}
|text = Returns 1 if typeof(x) is "scalar" and x has a numeric value otherwise 0.
}}

===isscalar()===
{{Nasal doc
|syntax = isscalar(x);
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}
|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 "~".
|example1 = var a = "foo";
var b=42;
if (isscalar(a) and isscalar(b)) print(a~b);
if (isstr(a)) print("a is a string");
if (isint(b)) print("b is an integer");
# if (isscalar(a))... is equivalent to if (typeof(a) == "scalar")...
}}

===isstr()===
Returns 1 if type or argument is a string, otherwise 0.

===isvec()===
Returns 1 if type or argument is a vector, otherwise 0.

===vecindex()===
{{Nasal doc
|syntax = vecindex(vector, value);
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}
|text = Returns the index of value or nil, if value is not found in vector.
|example1=
var myvector = ["apple", "bananna", "coconut"];
# to check if a vector contains a certain value compare vecindex to nil
if (vecindex(myvector, "apple") != nil) {
print("found apple");
}
# WARNING: this will not work as desired because index is 0
if (vecindex(myvector, "apple")) {
print("found apple");
<nowiki>}</nowiki>

}}

==Extension functions new in "dev" version ==
The following functions have been added to the nasal core library curernty on "dev" version.

===member()===
{{Nasal doc
|syntax = member(hash, key);
|source = {{simgear file|simgear/nasal/lib.c|l=796|t=Source}}
|text = The function searches for a key in the given hash, including the <code>parents</code>. If the key is found, its value is returned; otherwise, it returns <code>nil</code>.
|param1 = hash
|param1text = The hash in which the key is searched.
|param2 = key
|param2text = Key as a string whose value we want to return.
|example1 =
var Hash = {
key: 12,
};

member(Hash, 'key'); # return 12
member(Hash, 'missing'); # return nil
|example2 = # member() also includes parents

var Base = {
key: 'text',
};

var Child = {
parents: [Base],
};

member(Child, 'key'); # return 'text'
member(Child, 'missing'); # return nil
}}

===has_member()===
{{Nasal doc
|syntax = has_member(hash, key);
|source = {{simgear file|simgear/nasal/lib.c|l=811|t=Source}}
|text = The function searches for a key in the given hash, including the <code>parents</code>. If the key is found, <code>trur</code> is returned; otherwise <code>false</code>.
|param1 = hash
|param1text = The hash in which the key is searched.
|param2 = key
|param2text = Key as a string.
|example1 =
var Hash = {
key: 12,
};

member(Hash, 'key'); # return true
member(Hash, 'missing'); # return false
|example2 = # has_member() also includes parents

var Base = {
key: 'text',
};

var Child = {
parents: [Base],
};

member(Child, 'key'); # return true
member(Child, 'missing'); # return false
}}

==Variables==
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}}.

===D2R===
{{Nasal doc
|syntax = var radians = degrees * D2R;
|text = Converts an angle from degrees to radians when multiplied by the angle in degrees. Equal to <code>π / 180</code>.
}}
===FPS2KT===
{{Nasal doc
|syntax = var knots = feet_per_second * FPS2KT;
|text = Converts a velocity from feet per second to knots when multiplied by the velocity in feet per second. Approximately equal to 0.5925.
}}
===FT2M===
{{Nasal doc
|syntax = var metres = feet * FT2M;
|text = Converts a length from feet to metres when multiplied by the length in feet. Equal to 0.3048.
}}
===GAL2L ===
{{Nasal doc
|syntax = var litres = gallons * GAL2L;
|text = Converts a volume from US liquid gallons to litres when multiplied by the volume in gallons. Approximately equal to 3.7854.
}}
===IN2M===
{{Nasal doc
|syntax = var metres = inches * IN2M;
|text = Converts a length from inches to metres when multiplied by the length in inches. Equal to 0.0254.
}}
===KG2LB===
{{Nasal doc
|syntax = var pounds = kilograms * KG2LB;
|text = Converts a mass from kilograms to pounds when multiplied by the mass in kilograms. Approximately equal to 2.2046.
}}
===KT2FPS===
{{Nasal doc
|syntax = var feet_per_second = knots * KT2FPS;
|text = Converts a velocity from knots to feet per second when multiplied by the velocity in knots. Approximately equal to 1.6878.
}}
===KT2MPS===
{{Nasal doc
|syntax = var metres_per_second = knots * KT2MPS;
|text = Converts a velocity from knots to metres per second when multiplied by the velocity in knots. Approximately equal to 0.5144.
}}
===L2GAL===
{{Nasal doc
|syntax = var gallons = litres * L2GAL;
|text = Converts a volume from litres to US liquid gallons when multiplied by the volume in litres. Approximately equal to 0.2642.
}}
===LB2KG===
{{Nasal doc
|syntax = var kilograms = pounds * LB2KG;
|text = Converts a mass from pounds to kilograms when multiplied by the mass in pounds. Approximately equal to 0.4536.
}}
===M2FT ===
{{Nasal doc
|syntax = var feet = metres * M2FT;
|text = Converts a length from metres to feet when multiplied by the length in metres. Approximately equal to 3.2808.
}}
===M2IN===
{{Nasal doc
|syntax = var inches = metres * M2IN;
|text = Converts a length from metres to inches when multiplied by the length in metres. Approximately equal to 39.3701.
}}
===M2NM ===
{{Nasal doc
|syntax = var nautical_miles = metres * M2NM;
|text = Converts a length from metres to nautical miles when multiplied by the length in metres. Approximately equal to 0.00054.
}}
===MPS2KT ===
{{Nasal doc
|syntax = var knots = metres_per_second * MPS2KT;
|text = Converts a velocity from metres per second to knots when multiplied by the velocity in metres per second. Approximately equal to 1.9438.
}}
===NM2M ===
{{Nasal doc
|syntax = var metres = nautical_miles * NM2M;
|text = Converts a length from nautical miles to metres when multiplied by the length in nautical miles. Equal to 1,852.
}}
===R2D===
{{Nasal doc
|syntax = var degrees = radians * R2D;
|text = Converts an angle from radians to degrees when multiplied by the angle in radians. Equal to <code>180 / π</code>.
}}

{{Appendix}}

{{Nasal namespaces}}

FlightGear Newsletter November 2025

2025-12-11T22:41:32Z

PlayeRom: /* Multiplayer events */

{{User:Skybike/Template:Newsletter-header-translate|2025-11}}
{{TOC_right|limit=2}}

''We would like to emphasize that the monthly newsletter cannot live without the contributions of FlightGear users and developers. Everyone with a wiki account (free to register) is welcome to contribute to the newsletter. If you know about any FlightGear related news or projects such as for example updated scenery or aircraft, please do feel invited to add such news to the newsletter.''

''The new Visual Editor makes editing the wiki as simple as using a Word-processor, and even easier than using the forum as you don't even need to know the syntax for a url. Just hit the 'edit' link and start.''

== Development news ==



== Related Software tools and projects ==
=== Julia photoscenery generator GUI ===
==== Photoscenery-GUI ====

[[File:Photoscenery-GUI-20251113-202721.jpg|thumb|Photoscenery-GUI Beta]]

Adriano Bassignana has begun writing the manual for the Photoscenery GUI, which has been published at the following link:
https://wiki.flightgear.org/Julia_photoscenery_generator_GUI
The manual currently contains the essential information for correct installation.

New features in the latest version include:

The tool, which already managed the rational downloading of tiles in various resolutions, now includes additional features accessible via its web interface to increase operational utility. The program's initialization has been modified to enable faster startup.

A new functionality has been introduced to read airports and radio navigation aids from files updated weekly—the same data sources used by FlightGear itself. This resolves the previous issue of airport misalignment between the tool and the simulator.

Route management has been improved. When loading a route for display on the map, the system now simultaneously loads data on local scenery to prevent unnecessary downloads. For users with a fast internet connection, real-time image downloading is possible. A fast, low-resolution preload feature also provides a valid overview of the surrounding area's coverage.

The interface allows users to view radio navigation aids and airports, along with their key information.

The [create route] mode enables users to generate a flight path by clicking on map points, airports, and navigation aids. Created routes can be saved and later imported into FlightGear for use.

Many other features will be documented on the Wiki in the future.

https://github.com/abassign/Photoscenery-GUI.git

For more information, see the discussion on the FG Forum: https://forum.flightgear.org/viewtopic.php?f=5&t=39066&start=390

=== Framework for Canvas Add-on ===

Roman Ludwicki (PlayeRom on the forum) created a [https://github.com/PlayeRom/flightgear-addon-framework Framework] for creating add-ons based on Canvas dialog boxes. After creating numerous add-ons, he realized he needed to separate the common code base. This led to the creation of a separate Framework project that could be attached to any add-on. The framework includes the following features:

# Automatic recognition and loading of add-on Nasal files into the appropriate namespaces (with an exclusion list if necessary).
# Ability to add a menu for restarting add-on Nasal files without having to change repository files.
# Ability to define keys for the multi-key command to restart add-on Nasal files without having to change repository files.
# A mechanism for checking whether there is a new version of your add-on to inform users about it.
# Base classes for Canvas windows that are created and destroyed on demand (Transient dialog), as well as created once during simulator startup (Persistent dialog).
# Ability to create Nasal unit tests and run them using multi-key command.

An example project using the Framework is the [https://github.com/PlayeRom/flightgear-addon-canvas-skeleton Canvas Skeleton] project, which can be used as a basis for creating a new add-on.

You can also see how his other add-ons are written, all based on the Framework (main branches):
# [https://github.com/PlayeRom/flightgear-addon-aerotow-everywhere Aerotow Everywhere]
# [https://github.com/PlayeRom/flightgear-addon-logbook Logbook]
# [https://github.com/PlayeRom/flightgear-addon-which-runway Which Runway]
# [https://github.com/PlayeRom/flightgear-addon-nasal-namespace-browser Nasal Namespace Browser]
# [https://github.com/PlayeRom/flightgear-addon-menu-aggregator Add-on Menu Aggregator]

=== Add-ons Menu Aggregator ===

Roman Ludwicki has created a new "[https://github.com/PlayeRom/flightgear-addon-menu-aggregator Add-ons Menu Aggregator]" add-on. The "Add-ons Menu Aggregator" add-on solves the problem of increasing menu clutter in FlightGear, which occurs after installing multiple add-ons. Each add-on can add its own items to the main menu, causing it to become very large and, at low resolutions, extend beyond the screen. This makes it difficult for users to find functions related to specific add-ons, and the menu itself becomes unreadable.

The "Add-ons Menu Aggregator" automatically aggregates menu entries from all installed add-ons and places them into one common menu item – "Add-ons." Each add-on receives its own submenu here, containing its original items while maintaining full functionality and layout.

{{#ev:youtube|gNH3MBpRxjo|480px||Add-ons Menu Aggregator - Polish audio}}

== In the hangar ==






=== Aircraft reviews ===
==== Laminar 13 Hang Glider for FlightGear ====
==== Flight Test & Personal Tweaks by Vons ====

Having recently become interested in gliding and soaring in FG, I thought I'd go a (simpler) step further and merely strap a wing to myself (or me to a wing). That of course was also a good opportunity to harmonize further a few of the control inputs on the Laminar 13 for my rig/setup, as well as (subtly) to modify some of the weight shifts, drag and lift values, etc. Representative clip below for those who enjoy hang gliders, both real ones and in the world of FG.

{{#ev:youtube|tHQqhl3Sf5w|||Flight Test & Tweaks Laminar 13 Hang Glider for FlightGear|frame}}

If you're interested in seeing the flight test results and accessing the tweaks, visit the forum page at: https://forum.flightgear.org/viewtopic.php?f=19&t=42893&start=45#p436600

== Scenery corner ==




















== Community news ==









== Multiplayer events ==


=== Finished events ===
==== Independence Day Event 2025 ====
To celebrate Poland's Independence Day, the Polish Discord channel organized an Air Show with several performances. Clips are included in the video:

{{#ev:youtube|ekiLpbSXAmU|480px||Independence Day Event 2025}}






== Screenshot of the Month ==

If you want to participate in the screenshot contest, you can submit your candidate to the {{forum link|title=this|f=88|t=}}. Be sure to see the first post for participation rules. For purposes of convenience and organization, at the end of the month or after 20 entries have been submitted, a new forum topic will be started containing all shots in an easy-to-view layout. The voting will then take place there.

{{Appendix}}



[[Category:FlightGear Newsletter|2025 11]]

Howto:Add aerotow hitch to an AI-aircraft

2025-12-09T13:18:19Z

PlayeRom:

For the visualization of the tow rope, it is advantageous if a hitch position is defined for the AI tow plane.

To set the hitch position for the AI aircraft, add the following code to the top of the <tt>{aircraft}-ai.xml</tt> file:

<syntaxhighlight lang="xml">

<?xml version="1.0"?>
<PropertyList>

<nasal>
<load>
var acNode = cmdarg(); # "/ai/models/aircraft"
acNode.getNode("sim/hitches/aerotow/local-pos-x", true).setValue(x); # forward
acNode.getNode("sim/hitches/aerotow/local-pos-y", true).setValue(y); # left
acNode.getNode("sim/hitches/aerotow/local-pos-z", true).setValue(z); # up
</load>
<unload>
acNode.getNode("sim/hitches").remove();
</unload>
</nasal>



</PropertyList>

</syntaxhighlight>

In place of x, y, z, enter appropriate values for the hitch position.
Coordinate system: x forward, y to the left, and z up. The units are meters.

That's it! The tow rope ends at the defined position.

== Related content ==
* [[Soaring]]
* [[Improving Glider Realism]]
* [[Howto:Setup winch and aerotowing for JSBSim-aircraft]]

[[Category:Howto]]
[[Category:Aircraft enhancement]]

FlightGear Newsletter December 2025

2025-12-09T11:35:54Z

PlayeRom:

FlightGear Newsletter November 2025

2025-12-09T11:35:35Z

PlayeRom:

{{User:Skybike/Template:Newsletter-header-translate|2025-11}}
{{TOC_right|limit=2}}

''We would like to emphasize that the monthly newsletter cannot live without the contributions of FlightGear users and developers. Everyone with a wiki account (free to register) is welcome to contribute to the newsletter. If you know about any FlightGear related news or projects such as for example updated scenery or aircraft, please do feel invited to add such news to the newsletter.''

''The new Visual Editor makes editing the wiki as simple as using a Word-processor, and even easier than using the forum as you don't even need to know the syntax for a url. Just hit the 'edit' link and start.''

== Development news ==



== Related Software tools and projects ==
=== Julia photoscenery generator GUI ===
==== Photoscenery-GUI ====

[[File:Photoscenery-GUI-20251113-202721.jpg|thumb|Photoscenery-GUI Beta]]

Adriano Bassignana has begun writing the manual for the Photoscenery GUI, which has been published at the following link:
https://wiki.flightgear.org/Julia_photoscenery_generator_GUI
The manual currently contains the essential information for correct installation.

New features in the latest version include:

The tool, which already managed the rational downloading of tiles in various resolutions, now includes additional features accessible via its web interface to increase operational utility. The program's initialization has been modified to enable faster startup.

A new functionality has been introduced to read airports and radio navigation aids from files updated weekly—the same data sources used by FlightGear itself. This resolves the previous issue of airport misalignment between the tool and the simulator.

Route management has been improved. When loading a route for display on the map, the system now simultaneously loads data on local scenery to prevent unnecessary downloads. For users with a fast internet connection, real-time image downloading is possible. A fast, low-resolution preload feature also provides a valid overview of the surrounding area's coverage.

The interface allows users to view radio navigation aids and airports, along with their key information.

The [create route] mode enables users to generate a flight path by clicking on map points, airports, and navigation aids. Created routes can be saved and later imported into FlightGear for use.

Many other features will be documented on the Wiki in the future.

https://github.com/abassign/Photoscenery-GUI.git

For more information, see the discussion on the FG Forum: https://forum.flightgear.org/viewtopic.php?f=5&t=39066&start=390

=== Framework for Canvas Add-on ===

Roman Ludwicki (PlayeRom on the forum) created a [https://github.com/PlayeRom/flightgear-addon-framework Framework] for creating add-ons based on Canvas dialog boxes. After creating numerous add-ons, he realized he needed to separate the common code base. This led to the creation of a separate Framework project that could be attached to any add-on. The framework includes the following features:

# Automatic recognition and loading of add-on Nasal files into the appropriate namespaces (with an exclusion list if necessary).
# Ability to add a menu for restarting add-on Nasal files without having to change repository files.
# Ability to define keys for the multi-key command to restart add-on Nasal files without having to change repository files.
# A mechanism for checking whether there is a new version of your add-on to inform users about it.
# Base classes for Canvas windows that are created and destroyed on demand (Transient dialog), as well as created once during simulator startup (Persistent dialog).
# Ability to create Nasal unit tests and run them using multi-key command.

An example project using the Framework is the [https://github.com/PlayeRom/flightgear-addon-canvas-skeleton Canvas Skeleton] project, which can be used as a basis for creating a new add-on.

You can also see how his other add-ons are written, all based on the Framework (main branches):
# [https://github.com/PlayeRom/flightgear-addon-aerotow-everywhere Aerotow Everywhere]
# [https://github.com/PlayeRom/flightgear-addon-logbook Logbook]
# [https://github.com/PlayeRom/flightgear-addon-which-runway Which Runway]
# [https://github.com/PlayeRom/flightgear-addon-nasal-namespace-browser Nasal Namespace Browser]
# [https://github.com/PlayeRom/flightgear-addon-menu-aggregator Add-on Menu Aggregator]

=== Add-ons Menu Aggregator ===

Roman Ludwicki has created a new "[https://github.com/PlayeRom/flightgear-addon-menu-aggregator Add-ons Menu Aggregator]" add-on. The "Add-ons Menu Aggregator" add-on solves the problem of increasing menu clutter in FlightGear, which occurs after installing multiple add-ons. Each add-on can add its own items to the main menu, causing it to become very large and, at low resolutions, extend beyond the screen. This makes it difficult for users to find functions related to specific add-ons, and the menu itself becomes unreadable.

The "Add-ons Menu Aggregator" automatically aggregates menu entries from all installed add-ons and places them into one common menu item – "Add-ons." Each add-on receives its own submenu here, containing its original items while maintaining full functionality and layout.

{{#ev:youtube|gNH3MBpRxjo|480px||Add-ons Menu Aggregator - Polish audio}}

== In the hangar ==









== Scenery corner ==




















== Community news ==









== Multiplayer events ==









== Screenshot of the Month ==

If you want to participate in the screenshot contest, you can submit your candidate to the {{forum link|title=this|f=88|t=}}. Be sure to see the first post for participation rules. For purposes of convenience and organization, at the end of the month or after 20 entries have been submitted, a new forum topic will be started containing all shots in an easy-to-view layout. The voting will then take place there.

{{Appendix}}

[[Category:Changes after 2024.1]]
[[Category:FlightGear Newsletter|2025 05]]

FlightGear Newsletter October 2025

2025-12-09T11:35:21Z

PlayeRom:

FlightGear Newsletter September 2025

2025-12-09T11:35:05Z

PlayeRom:

FlightGear Newsletter August 2025

2025-12-09T11:34:52Z

PlayeRom:

FlightGear Newsletter July 2025

2025-12-09T11:34:36Z

PlayeRom:

FlightGear Newsletter June 2025

2025-12-09T11:34:21Z

PlayeRom:

FlightGear Newsletter October 2025

2025-12-09T11:28:18Z

PlayeRom: /* Development news */

FlightGear Newsletter November 2025

2025-12-09T11:16:56Z

PlayeRom: /* Add-ons Menu Aggregator */

{{User:Skybike/Template:Newsletter-header-translate|2025-05}}
{{TOC_right|limit=2}}

''We would like to emphasize that the monthly newsletter cannot live without the contributions of FlightGear users and developers. Everyone with a wiki account (free to register) is welcome to contribute to the newsletter. If you know about any FlightGear related news or projects such as for example updated scenery or aircraft, please do feel invited to add such news to the newsletter.''

''The new Visual Editor makes editing the wiki as simple as using a Word-processor, and even easier than using the forum as you don't even need to know the syntax for a url. Just hit the 'edit' link and start.''

== Development news ==



== Related Software tools and projects ==
=== Julia photoscenery generator GUI ===
==== Photoscenery-GUI ====

[[File:Photoscenery-GUI-20251113-202721.jpg|thumb|Photoscenery-GUI Beta]]

Adriano Bassignana has begun writing the manual for the Photoscenery GUI, which has been published at the following link:
https://wiki.flightgear.org/Julia_photoscenery_generator_GUI
The manual currently contains the essential information for correct installation.

New features in the latest version include:

The tool, which already managed the rational downloading of tiles in various resolutions, now includes additional features accessible via its web interface to increase operational utility. The program's initialization has been modified to enable faster startup.

A new functionality has been introduced to read airports and radio navigation aids from files updated weekly—the same data sources used by FlightGear itself. This resolves the previous issue of airport misalignment between the tool and the simulator.

Route management has been improved. When loading a route for display on the map, the system now simultaneously loads data on local scenery to prevent unnecessary downloads. For users with a fast internet connection, real-time image downloading is possible. A fast, low-resolution preload feature also provides a valid overview of the surrounding area's coverage.

The interface allows users to view radio navigation aids and airports, along with their key information.

The [create route] mode enables users to generate a flight path by clicking on map points, airports, and navigation aids. Created routes can be saved and later imported into FlightGear for use.

Many other features will be documented on the Wiki in the future.

https://github.com/abassign/Photoscenery-GUI.git

For more information, see the discussion on the FG Forum: https://forum.flightgear.org/viewtopic.php?f=5&t=39066&start=390

=== Framework for Canvas Add-on ===

Roman Ludwicki (PlayeRom on the forum) created a [https://github.com/PlayeRom/flightgear-addon-framework Framework] for creating add-ons based on Canvas dialog boxes. After creating numerous add-ons, he realized he needed to separate the common code base. This led to the creation of a separate Framework project that could be attached to any add-on. The framework includes the following features:

# Automatic recognition and loading of add-on Nasal files into the appropriate namespaces (with an exclusion list if necessary).
# Ability to add a menu for restarting add-on Nasal files without having to change repository files.
# Ability to define keys for the multi-key command to restart add-on Nasal files without having to change repository files.
# A mechanism for checking whether there is a new version of your add-on to inform users about it.
# Base classes for Canvas windows that are created and destroyed on demand (Transient dialog), as well as created once during simulator startup (Persistent dialog).
# Ability to create Nasal unit tests and run them using multi-key command.

An example project using the Framework is the [https://github.com/PlayeRom/flightgear-addon-canvas-skeleton Canvas Skeleton] project, which can be used as a basis for creating a new add-on.

You can also see how his other add-ons are written, all based on the Framework (main branches):
# [https://github.com/PlayeRom/flightgear-addon-aerotow-everywhere Aerotow Everywhere]
# [https://github.com/PlayeRom/flightgear-addon-logbook Logbook]
# [https://github.com/PlayeRom/flightgear-addon-which-runway Which Runway]
# [https://github.com/PlayeRom/flightgear-addon-nasal-namespace-browser Nasal Namespace Browser]
# [https://github.com/PlayeRom/flightgear-addon-menu-aggregator Add-on Menu Aggregator]

=== Add-ons Menu Aggregator ===

Roman Ludwicki has created a new "[https://github.com/PlayeRom/flightgear-addon-menu-aggregator Add-ons Menu Aggregator]" add-on. The "Add-ons Menu Aggregator" add-on solves the problem of increasing menu clutter in FlightGear, which occurs after installing multiple add-ons. Each add-on can add its own items to the main menu, causing it to become very large and, at low resolutions, extend beyond the screen. This makes it difficult for users to find functions related to specific add-ons, and the menu itself becomes unreadable.

The "Add-ons Menu Aggregator" automatically aggregates menu entries from all installed add-ons and places them into one common menu item – "Add-ons." Each add-on receives its own submenu here, containing its original items while maintaining full functionality and layout.

{{#ev:youtube|gNH3MBpRxjo|480px||Add-ons Menu Aggregator - Polish audio}}

== In the hangar ==









== Scenery corner ==




















== Community news ==









== Multiplayer events ==









== Screenshot of the Month ==

If you want to participate in the screenshot contest, you can submit your candidate to the {{forum link|title=this|f=88|t=}}. Be sure to see the first post for participation rules. For purposes of convenience and organization, at the end of the month or after 20 entries have been submitted, a new forum topic will be started containing all shots in an easy-to-view layout. The voting will then take place there.

{{Appendix}}

[[Category:Changes after 2024.1]]
[[Category:FlightGear Newsletter|2025 05]]

FlightGear Newsletter November 2025

2025-12-09T11:14:10Z

PlayeRom: /* Related Software tools and projects */

{{User:Skybike/Template:Newsletter-header-translate|2025-05}}
{{TOC_right|limit=2}}

''We would like to emphasize that the monthly newsletter cannot live without the contributions of FlightGear users and developers. Everyone with a wiki account (free to register) is welcome to contribute to the newsletter. If you know about any FlightGear related news or projects such as for example updated scenery or aircraft, please do feel invited to add such news to the newsletter.''

''The new Visual Editor makes editing the wiki as simple as using a Word-processor, and even easier than using the forum as you don't even need to know the syntax for a url. Just hit the 'edit' link and start.''

== Development news ==



== Related Software tools and projects ==
=== Julia photoscenery generator GUI ===
==== Photoscenery-GUI ====

[[File:Photoscenery-GUI-20251113-202721.jpg|thumb|Photoscenery-GUI Beta]]

Adriano Bassignana has begun writing the manual for the Photoscenery GUI, which has been published at the following link:
https://wiki.flightgear.org/Julia_photoscenery_generator_GUI
The manual currently contains the essential information for correct installation.

New features in the latest version include:

The tool, which already managed the rational downloading of tiles in various resolutions, now includes additional features accessible via its web interface to increase operational utility. The program's initialization has been modified to enable faster startup.

A new functionality has been introduced to read airports and radio navigation aids from files updated weekly—the same data sources used by FlightGear itself. This resolves the previous issue of airport misalignment between the tool and the simulator.

Route management has been improved. When loading a route for display on the map, the system now simultaneously loads data on local scenery to prevent unnecessary downloads. For users with a fast internet connection, real-time image downloading is possible. A fast, low-resolution preload feature also provides a valid overview of the surrounding area's coverage.

The interface allows users to view radio navigation aids and airports, along with their key information.

The [create route] mode enables users to generate a flight path by clicking on map points, airports, and navigation aids. Created routes can be saved and later imported into FlightGear for use.

Many other features will be documented on the Wiki in the future.

https://github.com/abassign/Photoscenery-GUI.git

For more information, see the discussion on the FG Forum: https://forum.flightgear.org/viewtopic.php?f=5&t=39066&start=390

=== Framework for Canvas Add-on ===

Roman Ludwicki (PlayeRom on the forum) created a [https://github.com/PlayeRom/flightgear-addon-framework Framework] for creating add-ons based on Canvas dialog boxes. After creating numerous add-ons, he realized he needed to separate the common code base. This led to the creation of a separate Framework project that could be attached to any add-on. The framework includes the following features:

# Automatic recognition and loading of add-on Nasal files into the appropriate namespaces (with an exclusion list if necessary).
# Ability to add a menu for restarting add-on Nasal files without having to change repository files.
# Ability to define keys for the multi-key command to restart add-on Nasal files without having to change repository files.
# A mechanism for checking whether there is a new version of your add-on to inform users about it.
# Base classes for Canvas windows that are created and destroyed on demand (Transient dialog), as well as created once during simulator startup (Persistent dialog).
# Ability to create Nasal unit tests and run them using multi-key command.

An example project using the Framework is the [https://github.com/PlayeRom/flightgear-addon-canvas-skeleton Canvas Skeleton] project, which can be used as a basis for creating a new add-on.

You can also see how his other add-ons are written, all based on the Framework (main branches):
# [https://github.com/PlayeRom/flightgear-addon-aerotow-everywhere Aerotow Everywhere]
# [https://github.com/PlayeRom/flightgear-addon-logbook Logbook]
# [https://github.com/PlayeRom/flightgear-addon-which-runway Which Runway]
# [https://github.com/PlayeRom/flightgear-addon-nasal-namespace-browser Nasal Namespace Browser]
# [https://github.com/PlayeRom/flightgear-addon-menu-aggregator Add-on Menu Aggregator]

=== Add-ons Menu Aggregator ===

Roman Ludwicki has created a new "[https://github.com/PlayeRom/flightgear-addon-menu-aggregator Add-ons Menu Aggregator]" add-on. The "Add-ons Menu Aggregator" add-on solves the problem of increasing menu clutter in FlightGear, which occurs after installing multiple add-ons. Each add-on can add its own items to the main menu, causing it to become very large and, at low resolutions, extend beyond the screen. This makes it difficult for users to find functions related to specific add-ons, and the menu itself becomes unreadable.

The "Add-ons Menu Aggregator" automatically aggregates menu entries from all installed add-ons and places them into one common menu item – "Add-ons." Each add-on receives its own submenu here, containing its original items while maintaining full functionality and layout.

== In the hangar ==









== Scenery corner ==




















== Community news ==









== Multiplayer events ==









== Screenshot of the Month ==

If you want to participate in the screenshot contest, you can submit your candidate to the {{forum link|title=this|f=88|t=}}. Be sure to see the first post for participation rules. For purposes of convenience and organization, at the end of the month or after 20 entries have been submitted, a new forum topic will be started containing all shots in an easy-to-view layout. The voting will then take place there.

{{Appendix}}

[[Category:Changes after 2024.1]]
[[Category:FlightGear Newsletter|2025 05]]

FlightGear Newsletter September 2025

2025-12-09T11:09:50Z

PlayeRom: /* Related Software tools and projects */

FlightGear Newsletter

2025-12-09T11:03:02Z

PlayeRom:

[[File:magagazine.png|right]]

The '''FlightGear Newsletter''' is intended to provide a collection of the latest developments from the worldwide [[FlightGear]] community. With so much development ongoing, it's almost impossible for anyone to keep up. The newsletter was started in July 2009, and is presented on a monthly basis. It is a collaborative effort that is created, edited and distributed via the [[FlightGear Wiki]], and all FlightGear users, contributors and developers are invited to contribute.

=== Archive ===
<div class="noresize">
{| class="prettytable"
! align="left" | 2025
! align="left" | 2024
! align="left" | 2023
! align="left" | 2022
! align="left" | 2021
! align="left" | 2020
! align="left" | 2019
! align="left" | 2018
! align="left" | 2017
! align="left" | 2016
! align="left" | 2015
! align="left" | 2014
! align="left" | 2013
! align="left" | 2012
! align="left" | 2011
! align="left" | 2010
! align="left" | 2009
|-
| valign="top" |
* [[FlightGear Newsletter January 2025|January]]
* [[FlightGear Newsletter February 2025|February]]
* [[FlightGear Newsletter March 2025|March]]
* [[FlightGear Newsletter April 2025|April]]
* [[FlightGear Newsletter May 2025|May]]
* [[FlightGear Newsletter June 2025|June]]
* [[FlightGear Newsletter July 2025|July]]
* [[FlightGear Newsletter August 2025|August]]
* [[FlightGear Newsletter September 2025|September]]
* [[FlightGear Newsletter October 2025|October]]
* [[FlightGear Newsletter November 2025|November]]
* [[FlightGear Newsletter December 2025|December]]
| valign="top" |
* [[FlightGear Newsletter January 2024|January]]
* [[FlightGear Newsletter February 2024|February]]
* [[FlightGear Newsletter March 2024|March]]
* [[FlightGear Newsletter April 2024|April]]
* [[FlightGear Newsletter May 2024|May]]
* [[FlightGear Newsletter June 2024|June]]
* [[FlightGear Newsletter July 2024|July]]
* [[FlightGear Newsletter August 2024|August]]
* [[FlightGear Newsletter September 2024|September]]
* [[FlightGear Newsletter October 2024|October]]
* [[FlightGear Newsletter November 2024|November]]
* [[FlightGear Newsletter December 2024|December]]
| valign="top" |
* [[FlightGear Newsletter January 2023|January]]
* [[FlightGear Newsletter February 2023|February]]
* [[FlightGear Newsletter March 2023|March]]
* [[FlightGear Newsletter April 2023|April]]
* [[FlightGear Newsletter May 2023|May]]
* [[FlightGear Newsletter June 2023|June]]
* [[FlightGear Newsletter July 2023|July]]
* [[FlightGear Newsletter August 2023|August]]
* [[FlightGear Newsletter September 2023|September]]
* [[FlightGear Newsletter October 2023|October]]
* [[FlightGear Newsletter November 2023|November]]
* [[FlightGear Newsletter December 2023|December]]
| valign="top" |
* [[FlightGear Newsletter January 2022|January]]
* [[FlightGear Newsletter February 2022|February]]
* [[FlightGear Newsletter March 2022|March]]
* [[FlightGear Newsletter April 2022|April]]
* [[FlightGear Newsletter May 2022|May]]
* June
* [[FlightGear Newsletter July 2022|July]]
* [[FlightGear Newsletter August 2022|August]]
* [[FlightGear Newsletter September 2022|September]]
* [[FlightGear Newsletter November 2022|November]]
* [[FlightGear Newsletter December 2022|December]]
| valign="top" |
* [[FlightGear Newsletter January 2021|January]]
* [[FlightGear Newsletter February 2021|February]]
* [[FlightGear Newsletter March 2021|March]]
* [[FlightGear Newsletter April 2021|April]]
* [[FlightGear Newsletter May 2021|May]]
* [[FlightGear Newsletter June 2021|June]]
* [[FlightGear Newsletter July 2021|July]]
* [[FlightGear Newsletter August 2021|August]]
* [[FlightGear Newsletter September 2021|September]]
* [[FlightGear Newsletter October 2021|October]]
* [[FlightGear Newsletter November 2021|November]]
* [[FlightGear Newsletter December 2021|December]]
| valign="top" |
* [[FlightGear Newsletter January 2020|January]]
* [[FlightGear Newsletter February 2020|February]]
* [[FlightGear Newsletter March 2020|March]]
* [[FlightGear Newsletter April 2020|April]]
* [[FlightGear Newsletter May 2020|May]]
* [[FlightGear Newsletter June 2020|June]]
* [[FlightGear Newsletter July 2020|July]]
* [[FlightGear Newsletter August 2020|August]]
* [[FlightGear Newsletter September 2020|September]]
* [[FlightGear Newsletter October 2020|October]]
* [[FlightGear Newsletter November 2020|November]]
* [[FlightGear Newsletter December 2020|December]]
| valign="top" |
* [[FlightGear Newsletter January 2019|January]]
* [[FlightGear Newsletter February 2019|February]]
* [[FlightGear Newsletter March 2019|March]]
* [[FlightGear Newsletter April 2019|April]]
* [[FlightGear Newsletter May 2019|May]]
* [[FlightGear Newsletter June 2019|June]]
* [[FlightGear Newsletter July 2019|July]]
* [[FlightGear Newsletter August 2019|August]]
* [[FlightGear Newsletter September 2019|September]]
* [[FlightGear Newsletter October 2019|October]]
* [[FlightGear Newsletter November 2019|November]]
| valign="top" |
* [[FlightGear Newsletter January 2018|January]]
* [[FlightGear Newsletter February 2018|February]]
* [[FlightGear Newsletter March 2018|March]]
* [[FlightGear Newsletter April 2018|April]]
* [[FlightGear Newsletter May 2018|May]]
* [[FlightGear Newsletter June 2018|June]]
* [[FlightGear Newsletter July 2018|July]]
* [[FlightGear Newsletter August 2018|August]]
* [[FlightGear Newsletter September 2018|September]]
* [[FlightGear Newsletter October 2018|October]]
* [[FlightGear Newsletter November 2018|November]]
* [[FlightGear Newsletter December 2018|December]]
| valign="top" |
* [[FlightGear Newsletter January 2017|January]]
* [[FlightGear Newsletter February 2017|February]]
* [[FlightGear Newsletter March 2017|March]]
* [[FlightGear Newsletter April 2017|April]]
* [[FlightGear Newsletter May 2017|May]]
* [[FlightGear Newsletter June 2017|June]]
* [[FlightGear Newsletter July 2017|July]]
* [[FlightGear Newsletter August 2017|August]]
* [[FlightGear Newsletter September 2017|September]]
* [[FlightGear Newsletter October 2017|October]]
* [[FlightGear Newsletter November 2017|November]]
* [[FlightGear Newsletter December 2017|December]]
| valign="top" |
* [[FlightGear Newsletter January 2016|January]]
* [[FlightGear Newsletter February 2016|February]]
* [[FlightGear Newsletter March 2016|March]]
* [[FlightGear Newsletter April 2016|April]]
* [[FlightGear Newsletter May 2016|May]]
* [[FlightGear Newsletter June 2016|June]]
* [[FlightGear Newsletter July 2016|July]]
* [[FlightGear Newsletter August 2016|August]]
* [[FlightGear Newsletter September 2016|September]]
* [[FlightGear Newsletter October 2016|October]]
* [[FlightGear Newsletter November 2016|November]]
* [[FlightGear Newsletter December 2016|December]]
| valign="top" |
* [[FlightGear Newsletter January 2015|January]]
* [[FlightGear Newsletter February 2015|February]]
* [[FlightGear Newsletter March 2015|March]]
* [[FlightGear Newsletter April 2015|April]]
* [[FlightGear Newsletter May 2015|May]]
* [[FlightGear Newsletter June 2015|June]]
* [[FlightGear Newsletter July 2015|July]]
* [[FlightGear Newsletter August 2015|August]]
* [[FlightGear Newsletter September 2015|September]]
* [[FlightGear Newsletter October 2015|October]]
* [[FlightGear Newsletter November 2015|November]]
* [[FlightGear Newsletter December 2015|December]]
| valign="top" |
* [[FlightGear Newsletter January 2014|January]]
* [[FlightGear Newsletter February 2014|February]]
* [[FlightGear Newsletter March 2014|March]]
* [[FlightGear Newsletter April 2014|April]]
* [[FlightGear Newsletter May 2014|May]]
* [[FlightGear Newsletter June 2014|June]]
* [[FlightGear Newsletter July 2014|July]]
* [[FlightGear Newsletter August 2014|August]]
* [[FlightGear Newsletter September 2014|September]]
* [[FlightGear Newsletter October 2014|October]]
* [[FlightGear Newsletter November 2014|November]]
* [[FlightGear Newsletter December 2014|December]]
| valign="top" |
* [[FlightGear Newsletter January 2013|January]]
* [[FlightGear Newsletter February 2013|February]]
* [[FlightGear Newsletter March 2013|March]]
* [[FlightGear Newsletter April 2013|April]]
* [[FlightGear Newsletter May 2013|May]]
* [[FlightGear Newsletter June 2013|June]]
* [[FlightGear Newsletter July 2013|July]]
* [[FlightGear Newsletter August 2013|August]]
* [[FlightGear Newsletter September 2013|September]]
* [[FlightGear Newsletter October 2013|October]]
* [[FlightGear Newsletter November 2013|November]]
* [[FlightGear Newsletter December 2013|December]]
| valign="top" |
* [[FlightGear Newsletter January 2012|January]]
* [[FlightGear Newsletter February 2012|February]]
* [[FlightGear Newsletter March 2012|March]]
* [[FlightGear Newsletter April 2012|April]]
* [[FlightGear Newsletter May 2012|May]]
* [[FlightGear Newsletter June 2012|June]]
* [[FlightGear Newsletter July 2012|July]]
* [[FlightGear Newsletter August 2012|August]]
* [[FlightGear Newsletter September 2012|September]]
* [[FlightGear Newsletter October 2012|October]]
* [[FlightGear Newsletter November 2012|November]]
* [[FlightGear Newsletter December 2012|December]]
| valign="top" |
* [[FlightGear Newsletter January 2011|January]]
* [[FlightGear Newsletter February 2011|February]]
* [[FlightGear Newsletter March 2011|March]]
* [[FlightGear Newsletter April 2011|April]]
* [[FlightGear Newsletter May 2011|May]]
* [[FlightGear Newsletter June 2011|June]]
* [[FlightGear Newsletter July 2011|July]]
* [[FlightGear Newsletter August 2011|August]]
* [[FlightGear Newsletter September 2011|September]]
* [[FlightGear Newsletter October 2011|October]]
* [[FlightGear Newsletter November 2011|November]]
* [[FlightGear Newsletter December 2011|December]]
| valign="top" |
* [[FlightGear Newsletter January 2010|January]]
* [[FlightGear Newsletter February 2010|February]]
* [[FlightGear Newsletter March 2010|March]]
* [[FlightGear Newsletter April 2010|April]]
* [[FlightGear Newsletter May 2010|May]]
* [[FlightGear Newsletter June 2010|June]]
* [[FlightGear Newsletter July 2010|July]]
* [[FlightGear Newsletter August 2010|August]]
* [[FlightGear Newsletter September 2010|September]]
* [[FlightGear Newsletter October 2010|October]]
* [[FlightGear Newsletter November 2010|November]]
* [[FlightGear Newsletter December 2010|December]]
| valign="top" |
* [[FlightGear Newsletter July 2009|July]]
* [[FlightGear Newsletter August 2009|August]]
* [[FlightGear Newsletter September 2009|September]]
* [[FlightGear Newsletter October 2009|October]]
* [[FlightGear Newsletter November 2009|November]]
* [[FlightGear Newsletter December 2009|December]]
|}
</div>

Some newsletter editions have been translated in other languages:
* [[File:De.gif|16px|link=:De:FlightGear Newsletter]] [[:De:FlightGear Newsletter|Deutsch]]
* [[File:Es.gif|16px|link=:Es:FlightGear Newsletter]] [[:Es:FlightGear Newsletter|Español]]
* [[File:Fr.gif|16px|link=:Fr:FlightGear Newsletter]] [[:Fr:FlightGear Newsletter|Français]]

=== You are invited to contribute! ===
We would like to emphasize that the monthly newsletter can not live without the contributions of FlightGear users and developers. The FlightGear Newsletter is a community-driven newsletter, which means that it is created and edited by people like ''you''. You don't need to be a long-time FlightGear user (or even a developer) to contribute to the newsletter.

In fact, helping write the monthly FlightGear newsletter is an excellent way for getting started contributing to the FlightGear community very quickly and very easily.

Even if you don't have to add anything yourself, just reviewing and improving additions by others is also highly appreciated, as are efforts to help translate newsletters or add screen shots (e.g. taken from the forum or mailing lists) to the newsletter. Screen shots can be uploaded at [[Special:Upload]].

Everyone with a wiki account (free to [[Special:UserLogin|register]]) can edit the newsletter and every contribution is welcome. So if you know about any FlightGear related projects such as for example updated scenery or aircraft, please do feel invited to add such news to the newsletter.

A simple template providing a basic structure for each upcoming newsletter can be taken from [[Talk:Next newsletter]]. This template can be copied/pasted into each new newsletter to help users getting started providing contents.

The draft for the upcoming newsletter can always be found at [[Next newsletter]].

If English is not your native language, please don't be concerned about contributing to the newsletter, you can always easily ask fellow FlightGear users to review or proof-read your changes. Also, one of the easiest ways to get started is simply copying/pasting text from forum or mailing list discussions, such as announcements (e.g., new aircraft, new scenery, etc.).

Another neat option to get started is adding links to FlightGear-related YouTube videos. For this, we have a dedicated section in each newsletter: "[[FlightGear Newsletter {{#time: F Y | last month }}#FlightGear on YouTube|FlightGear on YouTube]]."

If you want to embed a video, please see {{mediawiki|Extension:EmbedVideo#Usage}}

If you are looking for other ways to get involved, please see [[Volunteer]].

[[Category:FlightGear Newsletter| ]]
[[Category:Community|Newsletter]]
[[Category:Lists|Newsletter]]

[[de:FlightGear Newsletter]]
[[es:FlightGear Newsletter]]
[[fr:FlightGear Newsletter]]

FlightGear Newsletter November 2025

2025-12-09T11:00:54Z

PlayeRom: /* Related Software tools and projects */

{{User:Skybike/Template:Newsletter-header-translate|2025-05}}
{{TOC_right|limit=2}}

''We would like to emphasize that the monthly newsletter cannot live without the contributions of FlightGear users and developers. Everyone with a wiki account (free to register) is welcome to contribute to the newsletter. If you know about any FlightGear related news or projects such as for example updated scenery or aircraft, please do feel invited to add such news to the newsletter.''

''The new Visual Editor makes editing the wiki as simple as using a Word-processor, and even easier than using the forum as you don't even need to know the syntax for a url. Just hit the 'edit' link and start.''

== Development news ==



== Related Software tools and projects ==
=== Julia photoscenery generator GUI ===
==== Photoscenery-GUI ====

[[File:Photoscenery-GUI-20251113-202721.jpg|thumb|Photoscenery-GUI Beta]]

Adriano Bassignana has begun writing the manual for the Photoscenery GUI, which has been published at the following link:
https://wiki.flightgear.org/Julia_photoscenery_generator_GUI
The manual currently contains the essential information for correct installation.

New features in the latest version include:

The tool, which already managed the rational downloading of tiles in various resolutions, now includes additional features accessible via its web interface to increase operational utility. The program's initialization has been modified to enable faster startup.

A new functionality has been introduced to read airports and radio navigation aids from files updated weekly—the same data sources used by FlightGear itself. This resolves the previous issue of airport misalignment between the tool and the simulator.

Route management has been improved. When loading a route for display on the map, the system now simultaneously loads data on local scenery to prevent unnecessary downloads. For users with a fast internet connection, real-time image downloading is possible. A fast, low-resolution preload feature also provides a valid overview of the surrounding area's coverage.

The interface allows users to view radio navigation aids and airports, along with their key information.

The [create route] mode enables users to generate a flight path by clicking on map points, airports, and navigation aids. Created routes can be saved and later imported into FlightGear for use.

Many other features will be documented on the Wiki in the future.

https://github.com/abassign/Photoscenery-GUI.git

For more information, see the discussion on the FG Forum: https://forum.flightgear.org/viewtopic.php?f=5&t=39066&start=390

=== Framework for Canvas Add-on ===

Roman Ludwicki (PlayeRom on the forum) created a [https://github.com/PlayeRom/flightgear-addon-framework Framework] for creating add-ons based on Canvas dialog boxes. After creating numerous add-ons, he realized he needed to separate the common code base. This led to the creation of a separate Framework project that could be attached to any add-on. The framework includes the following features:

# Automatic recognition and loading of add-on Nasal files into the appropriate namespaces (with an exclusion list if necessary).
# Ability to add a menu for restarting add-on Nasal files without having to change repository files.
# Ability to define keys for the multi-key command to restart add-on Nasal files without having to change repository files.
# A mechanism for checking whether there is a new version of your add-on to inform users about it.
# Base classes for Canvas windows that are created and destroyed on demand (Transient dialog), as well as created once during simulator startup (Persistent dialog).
# Ability to create Nasal unit tests and run them using multi-key command.

An example project using the Framework is the [https://github.com/PlayeRom/flightgear-addon-canvas-skeleton Canvas Skeleton] project, which can be used as a basis for creating a new add-on.

You can also see how his other add-ons are written, all based on the Framework (main branches):
# [https://github.com/PlayeRom/flightgear-addon-aerotow-everywhere Aerotow Everywhere]
# [https://github.com/PlayeRom/flightgear-addon-logbook Logbook]
# [https://github.com/PlayeRom/flightgear-addon-which-runway Which Runway]
# [https://github.com/PlayeRom/flightgear-addon-nasal-namespace-browser Nasal Namespace Browser]
# [https://github.com/PlayeRom/flightgear-addon-menu-aggregator Add-on Menu Aggregator]

== In the hangar ==









== Scenery corner ==




















== Community news ==









== Multiplayer events ==









== Screenshot of the Month ==

If you want to participate in the screenshot contest, you can submit your candidate to the {{forum link|title=this|f=88|t=}}. Be sure to see the first post for participation rules. For purposes of convenience and organization, at the end of the month or after 20 entries have been submitted, a new forum topic will be started containing all shots in an easy-to-view layout. The voting will then take place there.

{{Appendix}}

[[Category:Changes after 2024.1]]
[[Category:FlightGear Newsletter|2025 05]]

Nasal library/props

2025-12-04T18:40:20Z

PlayeRom: /* copy() */

{{Nasal Navigation|nocat=1}}
This page contains documentation for the '''<code>props</code> namespace''' in [[Nasal]]. This namespace provides APIs for working with property trees (including the main [[Property Tree]]) via {{API Link|simgear|class|SGPropertyNode}}. The <code>props</code> namespace is sourced from {{fgdata source|Nasal/props.nas}} and {{flightgear source|src/Scripting/nasal-props.cxx}}.

== Class ==
=== Node ===
{{Nasal doc
|mode = class
|text = The main class, used widely for manipulating property trees.
}}
==== new() ====
{{Nasal doc
|syntax = props.Node.new([values]);
|text = Constructor function. Returns a new <code>props.Node</code> instance.
|param1 = values
|param1text = An optional hash that will be the initial property structure.
|example1 = var node = props.Node.new();
props.dump(node);
|example2 = var tree = {
a: 1,
b: ["a", "b", "c"],
c: {
d: 1 * 4
}
};

var node = props.Node.new(tree);
props.dump(node);
}}

==== addChild() ====
{{Nasal doc
|syntax = props.Node.addChild(name[, min_idx[, append]]);
|version = 2.10
|commit = {{fgdata commit|a15d5829379864c7138edff621d6864c5f426d0b|t=commit}}
|text = Add a new, blank child to the node. Returns the newly-created node.
|param1 = name
|param1text = The name of the node as a string.
|param2 = min_idx
|param2text = This specifies the minimum index to add the new one to. This takes precedence over '''append'''. Defaults to 0.
|param3 = append
|param3text = If there is already one or more children with the same name and this argument is true (1), the new child will be added after the child with the highest index. If false (0), the new child will be added at the lowest available index with the limit of '''min_idx'''. Defaults to true (1).
|example1 = var node = props.Node.new();
node.addChild("a");
props.dump(node);
|example2 = var node = props.Node.new();
node.addChild("a", 1);
props.dump(node); # a[1]
|example3 = var node = props.Node.new();
node.addChild("a", 1);
props.dump(node); # a[1]
node.addChild("a", 0, false);
props.dump(node); # a[1] and a[0]
|example4 = var node = props.Node.new();
node.addChild("a", 1);
props.dump(node); # a[1]
node.addChild("a", 0, true);
props.dump(node); # a[1] and a[2]
}}

==== addChildren() ====
{{Nasal doc
|syntax = props.Node.addChildren(name, count[, min_idx[, append]]);
|version = 2.10
|commit = {{fgdata commit|7f1117a5374beabb045fb76fbb6dd8bfb0128100|t=commit}}
|text = Adds multiple children with the same name to this node. Returns <code>'''nil</code>.
|param1 = name
|param1text = The name of the nodes as a string.
|param2 = count
|param2text = Number of new children to add.
|param3 = min_idx
|param3text = Performs the same function as in <code>[[#addChild.28.29|Node.addChild()]]</code>.
|param4 = append
|param4text = Performs the same function as in <code>[[#addChild.28.29|Node.addChild()]]</code>.
|example1 = var node = props.Node.new();
node.addChildren("a", 2);
props.dump(node); # a[0] and a[1]
|example2 = var node = props.Node.new();
node.addChildren("a", 2, 1);
props.dump(node); # a[1] and a[2]
|example3 = var node = props.Node.new();
node.addChild("a", 2);
props.dump(node); # a[2]
node.addChildren("a", 2, 0, 0);
props.dump(node); # a[2], a[0], and a[1]
}}

==== adjustValue() (since FG 2020.1) ====
{{Nasal doc
|syntax = props.Node.adjustValue(delta);
|text = Adds delta (numeric) to current value respecting the node type.
|param1 = delta
|param1text = Numeric value (can be negative) to add to current node value.
}}

==== alias() ====
{{Nasal doc
|syntax = props.Node.alias(node, chainListener=0);
|text = Aliases this node to another one. Returns 1 on success and 0 on failure.
|param1 = node
|param1text = The node to alias to. Can be one of:
* A path to a property in the [[Property Tree]] as a string.
* A <code>prop</code> ghost.
* A <code>props.Node</code> object.
|example1 = var node = props.Node.new();
node.alias("/position/altitude-ft");
props.dump(node); # equals the current altitude
|example2 = var node1 = props.Node.new();
node1.setDoubleValue(2.34);
var node2 = props.Node.new();
node2.alias(node1);
props.dump(node2); # equals 2.34
|param2=chainListener|param2text=Specify if listeners should work on aliased properties or not. Current default is false forbackwards compatability.}}

==== clearValue() ====
{{Nasal doc
|syntax = props.Node.clearValue();
|text = Clears the value and type of the node.
|example1 = var node = props.Node.new();
node.setDoubleValue(2.34);
props.dump(node); # prints "{DOUBLE} = 2.35"
node.clearValue();
props.dump(node); # prints "{NONE} = nil"
}}

==== decrement() (since FG 2020.1) ====
{{Nasal doc
|syntax = props.Node.decrement(n = 1);
|text = Decrements integer property by n (default: n = 1)
|param1 = n
|param1text = Value to subtract, will be converted to int, defaults to 1
}}

==== equals() ====
{{Nasal doc
|syntax = props.Node.equals(node);
|version = 2.12
|commit = {{fgdata commit|d80722065f3c11e0511fa888b1f5f310dd0183e3|t=commit}}
|text = Checks whether the node refers to the same one as another. Returns 1 (true) if it is, and 0 (false) if otherwise.
|param1 = node
|param1text = Node to check against. May be either a <code>prop</code> ghost or a <code>props.Node</code> object.
|example1 = var n = props.Node.new();
var a = n;
print(a.equals(n)); # prints "1" (true)
}}

==== getAliasTarget() ====
{{Nasal doc
|syntax = props.Node.getAliasTarget();
|text = Returns the alias target of a node as another <code>props.Node</code> instance.
|example1 = setprop("/test", 2.35);
var node = props.Node.new();
node.alias("/test");
var tgt = node.getAliasTarget();
print(tgt.getPath()); # prints "/test"
}}

==== getAttribute() ====
{{Nasal doc
|syntax = props.Node.getAttribute([rel_path, ]name);
props.Node.getAttribute();
|text = Returns an attribute. If no arguments are given, the function will return an integer specifying the attributes set for the node (see {{simgear source|simgear/props/props.hxx|l=767}} for a list). A list of attributes are below
{{{!}} class="wikitable"
! String !! Return value
{{!-}}
{{!}} last {{!!}} The highest used attribute code (should be 128). See for {{simgear source|simgear/props/props.hxx|l=767}} the codes.
{{!-}}
{{!}} children {{!!}} Number of child nodes.
{{!-}}
{{!}} listeners {{!!}} Number of listeners connected to this node.
{{!-}}
{{!}} references {{!!}} Number of times the node has previously been referenced.
{{!-}}
{{!}} tied {{!!}} Whether the node is tied.
{{!-}}
{{!}} alias {{!!}} Whether the node is aliased.
{{!-}}
{{!}} readable {{!!}} Whether the node can be read.
{{!-}}
{{!}} writable {{!!}} Whether the node can be written to.
{{!-}}
{{!}} archive {{!!}} Whether the node will be saved when the "save" [[fgcommands|fgcommand]] is triggered.
{{!-}}
{{!}} trace-read {{!!}} Whether the reading of the node will be logged when <code>--log-level=info</code>.
{{!-}}
{{!}} trace-write {{!!}} Whether the writing to the node will be logged when <code>--log-level=info</code>.
{{!-}}
{{!}} userarchive {{!!}} Whether the node will be saved to the [[FlightGear configuration via XML#autosave.xml|autosave file]] (only works for actual properties).
{{!-}}
{{!}} preserve {{!!}} Whether the value of node will be preserved during resets (only works for actual properties).
{{!}}}
|param1 = rel_path
|param1text = Optional relative path as a string.
|param2 = name
|param2text = Attribute as a string. See the above table for a full list.
|example1 = var node = props.Node.new();
var child = node.addChild("a");
print(node.getAttribute("children")); # prints "1"
|example2text = Example using relative path
|example2 = var node = props.Node.new();
var child = node.addChild("a");
print(node.getAttribute("a", "readable")); # prints "1" (node can be read from)
|example3 = var node = props.Node.new();
var node2 = props.Node.new();
node2.alias(node);
print(node2.getAttribute("alias")); # prints "1" (true)
|example4 = print(props.globals.getNode("/sim/signals/fdm-initialized").getAttribute("listeners")); # prints the number of listeners
|example5 = print(props.globals.getNode("/sim/time/elapsed-sec").getAttribute("tied")); # prints "1" (true), meaning it is tied
|example6 = var node = props.Node.new();
print(node.getAttribute("writable")); # prints "1" (true), meaning the node can be written to
|example7text = Example using no arguments
|example7 = var node = props.Node.new();
print(node.getAttribute()); # prints "3" (true), meaning the node can be read from (1) and written to (2)
}}

==== getBoolValue() ====
{{Nasal doc
|syntax = props.Node.getBoolValue();
|text = Returns the value of a node converted to a boolean. If the node is a number type, 0 will return false, while 1 will return true. If the node is a string or unspecified type and the value is <code>"false"</code>, false will be returned. Otherwise, true will be returned. Remember that boolean values are represented in Nasal as 1 (true) and 0 (false).
|example1 = var node = props.Node.new();
node.setBoolValue(1);
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setBoolValue(0);
print(node.getBoolValue() ? "true" : "false"); # prints "false"
|example2 = var node = props.Node.new();
node.setDoubleValue(1.23);
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setDoubleValue(-1.23);
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setDoubleValue(0.0);
print(node.getBoolValue() ? "true" : "false"); # prints "false"
|example3 = var node = props.Node.new();
node.setIntValue(2);
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setIntValue(-2);
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setIntValue(0);
print(node.getBoolValue() ? "true" : "false"); # prints "false"
|example4 = var node = props.Node.new();
node.setValue("Hello, World!");
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setValue("false");
print(node.getBoolValue() ? "true" : "false"); # prints "false"
}}

==== getChild() ====
{{Nasal doc
|syntax = props.Node.getChild(rel_path[, idx[, create]]);
|text = Returns a child of a node as another <code>props.Node</code> instance.
|param1 = rel_path
|param1text = Relative path to the child node as a string.
|param2 = idx
|param2text = Optional index for the child node as an integer.
|param3 = create
|param3text = If set to true (1), a new child will be created if it does not exist. If set to false (0), the function will not create a new child and the function will return <code>'''nil'''</code> if no child exists. Defaults to false.
|example1 = var node = props.Node.new();
node.addChild("a");
var c = node.getChild("a");
|example2 = var node = props.Node.new();
node.addChildren("a", 3);
node.getNode("a[1]").setDoubleValue(2.35);
var c = node.getChild("a", 1);
print(c.getValue()); # prints "2.35"
|example3 = var node = props.Node.new();
var c = node.getChild("a", 1, true);
props.dump(node); # new child a[1] will have appeared
}}

==== getChildren() ====
{{Nasal doc
|syntax = props.Node.getChildren([name]);
|text = Returns a vector of child nodes, optionally those with a certain name, as <code>props.Node</code> instances.
|param1 = name
|param1text = Optional name of the child nodes as a string. If not given, all children will be returned.
|example1 = var node = props.Node.new();
node.addChildren("a", 3);
node.addChildren("b", 3);
debug.dump(node.getChildren()); # all child nodes in the vector
|example2 = var node = props.Node.new();
node.addChildren("a", 3);
node.addChildren("b", 3);
debug.dump(node.getChildren("b")); # only children with the name "b" in the vector
}}

==== getIndex() ====
{{Nasal doc
|syntax = props.Node.getIndex();
|text = Returns the index of a node as an integer.
|example1 = var node = props.Node.new();
node.addChildren("a", 3);
print(node.getChild("a", 1).getIndex()); # prints "1"
|example2 = var node = props.Node.new();
node.addChild("b");
print(node.getChild("b").getIndex()); # prints "0"
}}

==== getName() ====
{{Nasal doc
|syntax = props.Node.getName();
|text = Returns the name of the node as a string.
|example1 = var node = props.Node.new();
var c = node.addChild("a");
debug.dump(c.getName()); # prints "a"
|example2 = var node = props.Node.new();
node.addChildren("a", 3);
debug.dump(node.getChild("a", 2).getName()); # prints "a"
}}

==== getNode() ====
{{Nasal doc
|syntax = props.Node.getNode(rel_path[, create]);
|text = Returns a subnode as another <code>props.Node</code> instance.
|param1 = rel_path
|param1text = Relative path to the subnode as a string.
|param2 = create
|param2text = If true (1), the node will be created if it does not exist. If false (0) and the node does not exist, the function will return <code>'''nil'''</code>. Default to false (0).
|example1 = var tree = {
"a": 1,
"b": "Hi",
"c": {
"d": "Hello, World!"
}
};
var node = props.Node.new(tree);
print(node.getNode("c/d").getValue()); # prints "Hello, World!"
|example2 = var tree = {
"a": 1,
"b": "Hi",
"c": {}
};
var node = props.Node.new(tree);
node.getNode("c/d", true).setDoubleValue(2.35);
props.dump(node); # c/d now exists
|example3 = var ac = props.globals.getNode("sim/aircraft");
print("Current aircraft is: ", ac.getValue());
}}

==== getParent() ====
{{Nasal doc
|syntax = props.Node.getParent();
|text = Returns the parent of a node, or <code>'''nil'''</code> if there is no parent.
|example1 = var tree = {
"a": 1,
"b": "Hi",
"c": {
"d": "Hello, World!"
}
};
var node = props.Node.new(tree);
props.dump(node.getNode("c/d").getParent()); # dumps "c"
|example2 = var node = props.Node.new();
debug.dump(node.getParent()); # prints nil
}}

==== getPath() ====
{{Nasal doc
|syntax = props.Node.getPath();
|text = Returns the path of the node as a string.
|example1 = var tree = {
"a": 1,
"b": "Hi",
"c": {
"d": "Hello, World!"
}
};
var node = props.Node.new(tree);
print(node.getNode("c/d").getPath()); # prints "/c/d"
}}

==== getType() ====
{{Nasal doc
|syntax = props.Node.getType();
|text = Returns node's type as a string. It should be one of "NONE", "ALIAS", "BOOL", "INT", "LONG" (long integer), "FLOAT", "DOUBLE", "STRING", "VEC3D", "VEC4D", "UNSPECIFIED".
|example1 = var node = props.Node.new();
print(node.getType()); # prints "NONE"
|example2 = var node = props.Node.new();
node.setIntValue(12);
print(node.getType()); # prints "INT"
|example3 = var node = props.Node.new();
node.setValue([0.4, 0.2, 1]);
debug.dump(node.getValue()); # prints "[0.4, 0.2, 1]"
print(node.getType()); # prints "VEC3D"
}}

==== getValue() ====
{{Nasal doc
|syntax = props.Node.getValue([rel_path]);
|text = {{hatnote|See also {{func link|getBoolValue()|page=this}}.}}

Returns the value of the node.
|param1 = rel_path
|param1text = Optional relative path to a subnode as a string, which may contain '/' characters. If the subnode does not exist, we return nil.
|example1 = var node = props.Node.new();
node.setDoubleValue(2.35);
print(node.getValue()); # prints "2.35"
|example2 = var node = props.Node.new();
node.setValue("Hi");
print(node.getValue()); # prints "Hi"
|example3 = var node = props.Node.new();
node.addChild("a").setValue("Hi");
print(node.getValue("a")); # prints "Hi"
|example4 = var node = props.Node.new();
node.setValue([0, 0.5, 1]);
debug.dump(node.getValue()); # prints "[0, 0.5, 1]"
}}

==== getValues() ====
{{Nasal doc
|syntax = props.Node.getValues();
|text = Returns the node tree as a hash, with all the various subnodes, etc. If the node has no children, the result is equivalent to {{func link|getValue()|page=this}}. Subnodes that are indexed will be combined into one key and their values placed in a vector (see example 2).
|example1 = var tree = {
"string": "Hi",
"number": 1.2,
"subnode": {
"idx-node": [1, 2, 3]
}
};
var node = props.Node.new(tree);
node.addChild("bool").setBoolValue(1);
props.dump(node); # dump to node tree
debug.dump(node.getValues()); # dump the node converted to hash
|example2 = var tree = {
"a": [1, 2, 3]
};
var node = props.Node.new(tree);
props.dump(node); # a[0] = 1, a[1] = 2, a[2] = 3
debug.dump(node.getValues()); # a: [1, 2, 3]
}}

==== increment() (since FG 2020.1) ====
{{Nasal doc
|syntax = props.Node.increment(n = 1);
|text = Increments integer property by n (default: n = 1)
|param1 = n
|param1text = Value to add, will be converted to int, defaults to 1
}}

==== initNode() ====
{{Nasal doc
|syntax = props.Node.initNode([path[, value[, type[, force]]]]);
|text = Initializes a node if it doesn't exist and returns that node as a <code>props.Node</code> object.
|param1 = path
|param1text = Optional path to a subnode as a string. If not given, the node itself will be initialized.
|param2 = value
|param2text = Optional default value to initialize the node with.
|param3 = type
|param3text = Optional string that will set the type of the node. Must be one of <code>"DOUBLE"</code>, <code>"INT"</code>, <code>"BOOL"</code>, or <code>"STRING"</code>.
|param4 = force
|param4text = If set to true (1), the node's type will be forced to change.
|example1 = var node = props.Node.new();
var a = node.initNode("a");
props.dump(a);
|example2 = var node = props.Node.new();
var a = node.initNode("a", "Hi");
props.dump(a);
|example3 = var node = props.Node.new();
var a = node.initNode("a", 1.25, "INT");
props.dump(a); # a = 1
|example4 = var node = props.Node.new();
node.addChild("a").setBoolValue(0);
props.dump(node.getChild("a")); # a = 0 (type: bool)
var a = node.initNode("a", 1.25, "INT", true);
props.dump(a); # a = 0 (type: int)
}}

==== isInt() (since FG 2020.1) ====
{{Nasal doc
|syntax = props.Node.isInt();
|text = Returns true (1) if node '''type''' is "INT" or "LONG" (long integer) otherwise false (0).
}}

==== isNumeric() (since FG 2020.1) ====
{{Nasal doc
|syntax = props.Node.isNumeric();
|text = Returns true (1) if node '''type''' is "INT", "LONG", "FLOAT" or "DOUBLE" otherwise false (0).
}}

==== remove() ====
{{Nasal doc
|syntax = props.Node.remove();
|text = Removes the node and returns the removed node.
|example1 = var node = props.Node.new();
node.addChild("a");
props.dump(node);
node.getChild("a").remove();
props.dump(node); # child "a" does not exist anymore
}}

==== removeAllChildren() ====
{{Caution|Be careful when using this API in conjunction with the Canvas system and element specific properties, for details please see [[Howto:Canvas Path Benchmarking]]}}
{{Nasal doc
|syntax = props.Node.removeAllChildren();
|version = 3.2
|commit = {{fgdata commit|4766ed21a68230c0c15265e5604a74f4d99e0f5d|t=commit}}
|text = Removes all child nodes and returns the node.
|example1 = var tree = {
"a": 1,
"b": 2,
"c": 3
};
var node = props.Node.new(tree);
props.dump(node);
node.removeAllChildren();
props.dump(node); # all children have been removed
}}

==== removeChild() ====
{{Nasal doc
|syntax = props.Node.removeChild(rel_path, idx);
|text = Removes a given child node child nodes and returns the node.
|param1 = rel_path
|param1text = Relative path to a subnode as a string.
|param2 = idx
|param2text = Index of the subnode to remove as an integer.
|example1 = var node = props.Node.new();
node.addChild("a");
props.dump(node);
node.removeChild("a", 0);
props.dump(node); # child "a" has been removed
|example2 = var node = props.Node.new();
node.addChildren("a", 2);
props.dump(node);
node.removeChild("a", 0);
props.dump(node); # just a[1] remains
}}

==== removeChildren() ====
{{Nasal doc
|syntax = props.Node.removeChildren([name]);
|text = Removes all children with a specified name. If no arguments are given, all children will be removed (see also {{func link|removeAllChildren()|page=this}}).
|param1 = name
|param1text = Optional name of children to remove as a string.
|example1 = var node = props.Node.new();
node.addChildren("a", 2);
node.addChildren("b", 2);
props.dump(node);
node.removeChildren("a");
props.dump(node); # just children named "b" remain
|example2 = var node = props.Node.new();
node.addChildren("a", 2);
node.addChildren("b", 2);
props.dump(node);
node.removeChildren();
props.dump(node); # all children removed
}}

==== setAttribute() ====
{{Nasal doc
|syntax = props.Node.setAttribute([rel_path, ]attr, value);
props.Node.setAttribute(attrs);
|text = Sets an attribute or multiple attributes. A list of attributes and their codes are below. For a brand new node, the default attributes are ''readable'' and ''writable''. Returns an integer specifying the old attributes.
{{{!}} class="wikitable"
! String !! Description
{{!-}}
{{!}} readable {{!!}} Whether the node can be read.
{{!-}}
{{!}} writable {{!!}} Whether the node can be written to.
{{!-}}
{{!}} archive {{!!}} Whether the node will be saved when the "save" [[fgcommands|fgcommand]] is triggered.
{{!-}}
{{!}} trace-read {{!!}} Whether the reading of the node will be logged when <code>--log-level=info</code>.
{{!-}}
{{!}} trace-write {{!!}} Whether the writing to the node will be logged when <code>--log-level=info</code>.
{{!-}}
{{!}} userarchive {{!!}} Whether the node will be saved to the [[FlightGear configuration via XML#autosave.xml|autosave file]] (only works for actual properties).
{{!-}}
{{!}} preserve {{!!}} Whether the value of node will be preserved during resets (only works for actual properties).
{{!}}}
|param1 = rel_path
|param1text = Optional relative path as a string.
|param2 = attr
|param2text = Name of attribute to set as a string. See above.
|param3 = value
|param3text = Boolean value to set the property to.
|param4 = attrs
|param4text = When the function is used in its second form, this argument is used. This argument should be an integer specifying which arguments are set to true. See {{simgear source|simgear/props/props.hxx|l=767}} for the full list of codes. Simply add codes of the desired attributes together.
|example1 = var node = props.Node.new();
node.setAttribute("trace-write", 1);
node.setIntValue(12); # will be traced
|example2 = var node = props.Node.new();
node.setAttribute("readable", 0);
var val = node.getValue();
debug.dump(val); # prints "nil"
|example3 = var node = props.Node.new();
node.addChild("a");
node.setAttribute("a", "trace-write", 1);
node.getChild("a").setIntValue(12); # will be traced
|example4 = var node = props.Node.new();
node.setAttribute(35); # read + write + trace-write
node.setIntValue(12); # will be traced
}}

==== setBoolValue() ====
{{Nasal doc
|syntax = props.Node.setBoolValue([rel_path, ]value);
|text = {{note|For setting the values of [[Property Tree]] nodes, it is recommended to use {{func link|setprop()}} if possible, due to performance differences.}}

Sets a node to a boolean value. If the node has no type, it will be set to a bool type. If the node is already a number type, it will be set to either 1 or 0. If it is a string, it will be set to either "true" or "false". Returns 1 (true) if the operation was successful.
|param1 = rel_path
|param1text = Optional relative path as a string.
|param2 = value
|param2text = Value to set the node to, will be interpreted into a boolean. If it is <code>'''nil'''</code>, it will be false. If it is a string, it will be false. If it is a number, 0 will be false, while other numbers will be true. All other cases will be interpreted as 0.
|example1 = var node = props.Node.new();
node.setBoolValue(nil);
props.dump(node); # node = 0 (false)
|example2 = var node = props.Node.new();
node.setBoolValue("Hi");
props.dump(node); # node = 1 (true)
|example3 = var node = props.Node.new();
node.setBoolValue(0);
props.dump(node); # node = 0 (false)
node.setBoolValue(1.25);
props.dump(node); # node = 1 (true)
|example4 = var node = props.Node.new();
node.setValue("String");
props.dump(node); # node = "String" (type: string)
node.setBoolValue(1);
props.dump(node); # node = "true"
|example5 = var node = props.Node.new();
node.setDoubleValue(12.32);
props.dump(node); # node = 12.32 (type: double)
node.setBoolValue(1);
props.dump(node); # node = 1
|example6 = var node = props.Node.new();
node.addChild("a");
node.setBoolValue("a", 1);
props.dump(node); # /a = 1
}}

==== setDoubleValue() ====
{{Nasal doc
|syntax = props.Node.setDoubleValue([rel_path, ]value);
|text = {{note|For setting the values of [[Property Tree]] nodes, it is recommended to use {{func link|setprop()}} if possible, due to performance differences.}}

Sets a node to a double value. If the node has no type, it will be set to a double type. If the node is a bool, values different from zero will be interpreted as true. If the node is a string, the value will be converted to a string. If the node is an integer type, it will be truncated to the closest integer to zero. Returns 1 (true) if the operation was successful.
|param1 = rel_path
|param1text = Optional relative path as a string.
|param2 = value
|param2text = Value to set the node to, will be interpreted into a double number. It must be a valid number or a string that can be converted to a number.
|example1 = var node = props.Node.new();
node.setDoubleValue(1.1);
props.dump(node); # node = 1.1 (type: double)
|example2 = var node = props.Node.new();
node.setDoubleValue("1.1");
props.dump(node); # node = 1.1 (type: double)
|example3 = var node = props.Node.new();
node.setBoolValue(1);
node.setDoubleValue("1.1");
props.dump(node); # node = 1 (type: bool)
node.setDoubleValue(0.0);
props.dump(node); # node = 0 (type: bool)
|example4 = var node = props.Node.new();
node.setIntValue(1);
node.setDoubleValue(1.1);
props.dump(node); # node = 1 (type: int)
node.setDoubleValue("-1.1");
props.dump(node); # node = -1 (type: int)
|example5 = var node = props.Node.new();
node.addChild("a");
node.setDoubleValue("a", 12.2);
props.dump(node); # /a = 12.2
}}

==== setIntValue() ====
{{Nasal doc
|syntax = props.Node.setIntValue([rel_path, ]value);
|text = {{note|For setting the values of [[Property Tree]] nodes, it is recommended to use {{func link|setprop()}} if possible, due to performance differences.}}

Sets a node to an integer value. If the node has no type, it will be set to a integer type. If the node is a bool, values different from zero will be interpreted as true. If the node is a string, the value will be converted to a string. Returns 1 (true) if the operation was successful.
|param1 = rel_path
|param1text = Optional relative path as a string.
|param2 = value
|param2text = Value to set the node to, will be interpreted into a integer. It must be a valid number or a string that can be converted to a number. If the number is a double, it will be truncated to the closest integer to zero.
|example1 = var node = props.Node.new();
node.setIntValue(12);
props.dump(node); # node = 12
node.setIntValue("6");
props.dump(node); # node = 6
|example2 = var node = props.Node.new();
node.setIntValue(12.2);
props.dump(node); # node = 12
node.setIntValue(-12.2);
props.dump(node); # node = 12
|example3 = var node = props.Node.new();
node.setBoolValue(1);
node.setIntValue(12.5);
props.dump(node); # node = 1 (type: bool)
node.setIntValue(0);
props.dump(node); # node = 0 (type: bool)
|example4 = var node = props.Node.new();
node.setValue("Hi");
node.setIntValue(12);
props.dump(node); # node = "12" (type: string)
|example5 = var node = props.Node.new();
node.addChild("a");
node.setIntValue("a", 12);
props.dump(node); # /a = 12
}}

==== setValue() ====
{{Nasal doc
|syntax = props.Node.setValue([rel_path, ]value);
|text = {{hatnote|See also {{func link|setBoolValue()|page=this}}, {{func link|setDoubleValue()|page=this}}, and {{func link|setIntValue()|page=this}}.}}

{{note|For setting the values of [[Property Tree]] nodes, it is recommended to use {{func link|setprop()}} if possible, due to performance differences.}}

Sets a node to a given value. See table below for conversions and effects. Note that vec3d and vec4d types are not fully integrated into SGPropertyNode. Returns 1 (true) if the operation was successful.

{{{!}} class="wikitable"
{{!}} colspan="2" style="text-align:right" {{!}} '''value''' type →
! rowspan="2" {{!}} Number
! rowspan="2" {{!}} String
! rowspan="2" {{!}} Vector
{{!-}}
{{!}} style="text-align:left" {{!}} Current node<br>type ↓
{{!}} style="text-align:right" {{!}} Result ↘
{{!-}}
! colspan="2" {{!}} None/unspecified
{{!}}
* Type set to <code>double</code>
* Node set to '''value'''.
{{!}}
* Type set to <code>string</code>
* Node set to '''value'''.
{{!}}
* Type set to <code>vec*d</code>
* Node set to '''value'''.
{{!-}}
! colspan="2" {{!}} Bool
{{!}}
* If '''value''' != 0, node set to true.
* If '''value''' == 0, node set to false.
{{!}}
* If '''value''' == "true", node set to true.
* If '''value''' can be converted to an integer,<br>and != 0, node set to true.
{{!}} Node set to true.
{{!-}}
! colspan="2" {{!}} Integer
{{!}} Node set to truncated '''value'''
{{!}} Node set to '''value ''' converted and truncated to an integer.
{{!}} Node set to 1.
{{!-}}
! colspan="2" {{!}} Double
{{!}} Node set to '''value'''.
{{!}} Node set to '''value''' converted to number.
{{!}} Throws an error (vector is not a number).
{{!-}}
! colspan="2" {{!}} String
{{!}} Node set to '''value''' converted to string. {{!!}} Node set to '''value'''. {{!!}} Node not set.
{{!}}}
|param1 = rel_path
|param1text = Optional relative path as a string.
|param2 = value
|param2text = Value to set the node to. Must be a string, a valid number, or a vector consisting of 3 or 4 numbers. See table above for conversions and effects.
|example1 = var node = props.Node.new();
node.setValue("Hi");
props.dump(node); # node = "Hi"
|example2 = var node = props.Node.new();
node.addChild("a");
node.setValue("a", "Hi");
props.dump(node); # \a = "Hi"
|example3 = var node = props.Node.new();
node.setValue([0.4, 0.2, 1]);
debug.dump(node.getValue()); # prints "[0.4, 0.2, 1]"
print(node.getType()); # prints "VEC3D"
}}

==== setValues() ====
{{Nasal doc
|syntax = props.Node.setValues(val);
|text = {{hatnote|See also {{func link|getValues()|page=this}}.}}

Sets the nodes property tree from a Nasal hash. Scalars will become nodes in the tree and hashes will become named subnodes. Vectors will be converted into indexed nodes, with the values in the vector becoming their values (see examples below).
|param1 = val
|param1text = A hash that will become the property tree.
|example1 = var val = {
"a": 100 # "a" will become the subnode's name, and 100 its value
};
var node = props.Node.new();
node.setValues(val);
props.dump(node); # dump tree
|example2 = var val = {
"a": 1,
"b": "Hi",
"c": {
"d": [1, 2, 3]
}
};
var node = props.Node.new();
node.setValues(val);
props.dump(node); # dump tree
}}

==== unalias() ====
{{Nasal doc
|syntax = props.Node.unalias();
|text = Un-aliases the node and returns it to a blank state. Returns 1 on success and 0 on failure (e.g., when used on a tied property).
|example2 = var node1 = props.Node.new();
node1.setDoubleValue(2.35);
var node2 = props.Node.new();
node2.alias(node1);

props.dump(node2); # equals 2.35
node2.unalias();
props.dump(node2); # no value or type
}}

==== toggleBoolValue() (since FG 2020.1) ====
{{Nasal doc
|syntax = toggleBoolValue();
|text = Toggle a boolean property. You have to make sure the property is of type bool!
|example1 = var b = props.Node.new().initNode("/_test/bool", 1, "BOOL");
print("bool ", b.getValue());
b.toggleBoolValue();
print("after toggleBoolValue ", b.getValue());

}}

== Functions ==
=== compileCondition() ===
{{see also|Conditions}}

{{Nasal doc
|syntax = props.compileCondition(node);
|version = 3.2
|commit = {{fgdata commit|43f8ce08706629e69984b1cc34e5e979d03ef09a|t=commit}}
|text = Compiles a [[conditions|condition]] property branch and returns a <code>Condition</code> ghost object or <code>'''nil'''</code> on error. This ghost will contain a <code>test()</code> function that will return the result of the condition as either 1 (true) or 0 (false).
|param1 = node
|param1text = Either a props.Node containing the condition, or a string specifying a place in the [[Property Tree]] where there is a condition branch.
|example1 = var tree = {
"equals": {
"property": '/test',
"value": 12
}
};
var node = props.Node.new(tree);
setprop("/test", 12);

var cond = props.compileCondition(node);
print(cond.test()); # prints "1" (true)
setprop("/test", 15);
print(cond.test()); # prints "0" (false)
|example2 = var tree = {
"equals": {
"property": '/test',
"value": 12
}
};
props.globals.getNode("test2/condition", 1).setValues(tree); # place it in the Property Tree
setprop("/test", 12);

var cond = props.compileCondition(node);
print(cond.test()); # prints "1" (true)
setprop("/test", 15);
print(cond.test()); # prints "0" (false)
}}

=== condition() ===
{{Nasal doc
|syntax = props.condition(node);
|text = Evaluates a [[conditions|condition]] property branch and returns the result as a boolean.
|param1 = node
|param1text = Either a props.Node containing the condition, or a string specifying a place in the [[Property Tree]] where there is a condition branch.
|example1 = var tree = {
"equals": {
"property": '/test',
"value": 12
}
};
var node = props.Node.new(tree);
setprop("/test", 12);

print(props.condition(node)); # prints "1" (true)
setprop("/test", 15);
print(props.condition(node)); # prints "0" (false)
|example2 = var tree = {
"equals": {
"property": '/test',
"value": 12
}
};
props.globals.getNode("test2/condition", 1).setValues(tree); # place it in the Property Tree
setprop("/test", 12);

print(props.condition(node)); # prints "1" (true)
setprop("/test", 15);
print(props.condition(node)); # prints "0" (false)
}}

=== copy() ===
{{Nasal doc
|syntax = props.copy(src, dest[, attr]);
|text = Copies the property tree of the source into the destination node. Note that aliased properties will not be copied.
|param1 = src
|param1text = Source <code>props.Node object</code> to copy from.
|param2 = dest
|param2text = Destination <code>props.Node object</code> to copy to.
|param3 = attr
|param3text = If set to true (1), attributes will also be copied. Defaults to false (0).
|example1 = var tree = {
"a": 1.5,
"b": "Hi",
"c": {
"d": [1, 2, 3]
}
};
var src = props.Node.new(tree);
var dest = props.Node.new();
props.copy(src, dest);
props.dump(dest);
|example2 = var src = props.Node.new();
var a = src.addChild("a");
a.setAttribute("trace-write", 1);
a.setIntValue(12);
var dest = props.Node.new();
props.copy(src, dest, true);
print(dest.getNode("a").getAttribute("trace-write")); # prints "1" (true)
}}

=== dump() ===
{{Nasal doc
|syntax = props.dump(node);
|text = Recursively dump the state of a node into the console, showing value and type of each node. Note that as of 10/2016, the value of vec*d type nodes cannot be dumped.
|param1 = node
|param1text = Node to dump.
|example1 = var node = var tree = {
"a": 12,
"b": "Hi",
"c": {
"d": [1, 2, 3]
}
};
var node = props.Node.new(tree);
props.dump(node); # dump into console
|example2 = # Dump the entire Property Tree
# Warning! This is an intensive operation!
props.dump(props.globals);
}}

=== getNode() ===
{{Nasal doc
|syntax = props.getNode();
|version = 3.2
|commit = {{fgdata commit|807062d0b6f858885547f27325e829c2bf42a12b|t=commit}}
|text = Shortcut for <syntaxhighlight lang="nasal" inline>props.globals.getNode()</syntaxhighlight>. See {{func link|getNode()||Node|page=this}} for full documentation.
|example1 = print("Current aircraft is: ", props.getNode("/sim/aircraft").getValue());
}}

=== nodeList() ===
{{Nasal doc
|syntax = props.nodeList(arg[, arg[, ...]]);
|text = Converts its arguments into a vector of node objects if possible and returns that vector.
|param1 = arg
|param1text = Object to operate on. Must be a node object, string, vector, hash, function, or <code>prop</code> ghost. Vectors and hashes must contain any of the other acceptable types, functions must return any of the other types, strings will be assumed to be paths to global properties, and ghosts will be converted into node objects. There may be any number of arguments.
|example1 = var node = props.Node.new();
var f = func(){
var n = props.Node.new();
return n._g;
}
var list = props.nodeList(node,
"/sim/aircraft",
["/sim/fg-root"],
{ "path": "/sim/fg-home" },
f
);
debug.dump(list); # dump list
|example2 = var root = "/sim/version/";
var info = [
root ~ "build-id",
root ~ "build-number",
root ~ "flightgear",
root ~ "hla-support",
root ~ "openscenegraph",
root ~ "revision",
root ~ "simgear"
];
info = props.nodeList(info); # turn into list of nodes
foreach(var n; info){
print(n.getValue()); # dump info
}
}}

=== runBinding() ===
{{Nasal doc
|syntax = props.runBinding(node[, module]);
|text = Runs a [[Bindings|binding]] element in a node object. Returns 1 (true) on success and 0 (false) on failure.
|param1 = node
|param1text = A {{tag|binding}} element as a node object.
|param2 = module
|param2text = Optional string specifying a module to run Nasal scripts in if the command is <code>nasal</code>. This argument will not override any {{tag|module}} element in the '''node'''
|example1 = var tree = {
"command": "dialog-show",
"dialog-name": "map" # open map
};
var binding = props.Node.new(tree);
props.runBinding(binding);
|example2 = var tree = {
"command": "nasal",
"script": 'print(pi)' # prints value of math.pi
};
var binding = props.Node.new(tree);
props.runBinding(binding, "math");
|example3 = var tree = {
"command": "nasal",
"script": 'print(pi)', # prints value of math.pi
"module": "math" # this is used
};
var binding = props.Node.new(tree);
props.runBinding(binding, "debug");
}}

=== setAll() ===
{{Nasal doc
|syntax = props.setAll(base, child, value);
|text = Sets indexed subnodes in the Property Tree with the same name to the same value.
|param1 = base
|param1text = Base path to the nodes.
|param2 = child
|param2text = Path to child nodes.
|param3 = value
|param3text = Value to set the subnodes to.
|example1 = # apply 50% throttle to all engines
props.setAll("/controls/engines/engine", "throttle", 0.5);
|example2 = var nodes = props.globals.addChildren("/test", 3);
foreach(var node; nodes){
node.addChild("a");
}
props.setAll("/test", "a", "Hi"); # set all children (test[*]/a) to "Hi"
}}

=== wrap() ===
{{Nasal doc
|syntax = props.wrap(node);
|text = Turns <code>prop</code> ghosts, either in a vector or single, into <code>props.Node</code> objects.
|param1 = node
|param1text = <code>prop</code> ghost or vector of such ghosts.
|example1 = var ghost = canvas._newCanvasGhost();
var node = props.wrap(ghost._node_ghost);
props.dump(node);
|example2 = var vector = [canvas._newCanvasGhost()._node_ghost, props.Node.new()._g];
var nodes = props.wrap(vector);
foreach(var node; nodes){
props.dump(node);
print("----");
}
}}

=== wrapNode() ===
{{Nasal doc
|syntax = props.wrapNode(node);
|text = Turns a <code>prop</code> ghost into a <code>props.Node</code> object.
|param1 = node
|param1text = <code>prop</code> ghost to convert.
|example1 = var ghost = canvas._newCanvasGhost();
var node = props.wrapNode(ghost._node_ghost);
props.dump(node);
}}

== Variable ==
=== globals ===
{{Nasal doc
|syntax = props.globals;
|text = Exposes the [[Property Tree]] as a <code>props.Node</code> object.

|example1 = print("Current aircraft: ", props.globals.getNode("/sim/aircraft").getValue());
|example2text = Alternative using {{func link|getprop()}}.
|example2 = print("Current aircraft: ", getprop("/sim/aircraft"));
}}

{{Nasal namespaces}}

Nasal library/props

2025-12-04T18:36:10Z

PlayeRom: /* getChild() */

{{Nasal Navigation|nocat=1}}
This page contains documentation for the '''<code>props</code> namespace''' in [[Nasal]]. This namespace provides APIs for working with property trees (including the main [[Property Tree]]) via {{API Link|simgear|class|SGPropertyNode}}. The <code>props</code> namespace is sourced from {{fgdata source|Nasal/props.nas}} and {{flightgear source|src/Scripting/nasal-props.cxx}}.

== Class ==
=== Node ===
{{Nasal doc
|mode = class
|text = The main class, used widely for manipulating property trees.
}}
==== new() ====
{{Nasal doc
|syntax = props.Node.new([values]);
|text = Constructor function. Returns a new <code>props.Node</code> instance.
|param1 = values
|param1text = An optional hash that will be the initial property structure.
|example1 = var node = props.Node.new();
props.dump(node);
|example2 = var tree = {
a: 1,
b: ["a", "b", "c"],
c: {
d: 1 * 4
}
};

var node = props.Node.new(tree);
props.dump(node);
}}

==== addChild() ====
{{Nasal doc
|syntax = props.Node.addChild(name[, min_idx[, append]]);
|version = 2.10
|commit = {{fgdata commit|a15d5829379864c7138edff621d6864c5f426d0b|t=commit}}
|text = Add a new, blank child to the node. Returns the newly-created node.
|param1 = name
|param1text = The name of the node as a string.
|param2 = min_idx
|param2text = This specifies the minimum index to add the new one to. This takes precedence over '''append'''. Defaults to 0.
|param3 = append
|param3text = If there is already one or more children with the same name and this argument is true (1), the new child will be added after the child with the highest index. If false (0), the new child will be added at the lowest available index with the limit of '''min_idx'''. Defaults to true (1).
|example1 = var node = props.Node.new();
node.addChild("a");
props.dump(node);
|example2 = var node = props.Node.new();
node.addChild("a", 1);
props.dump(node); # a[1]
|example3 = var node = props.Node.new();
node.addChild("a", 1);
props.dump(node); # a[1]
node.addChild("a", 0, false);
props.dump(node); # a[1] and a[0]
|example4 = var node = props.Node.new();
node.addChild("a", 1);
props.dump(node); # a[1]
node.addChild("a", 0, true);
props.dump(node); # a[1] and a[2]
}}

==== addChildren() ====
{{Nasal doc
|syntax = props.Node.addChildren(name, count[, min_idx[, append]]);
|version = 2.10
|commit = {{fgdata commit|7f1117a5374beabb045fb76fbb6dd8bfb0128100|t=commit}}
|text = Adds multiple children with the same name to this node. Returns <code>'''nil</code>.
|param1 = name
|param1text = The name of the nodes as a string.
|param2 = count
|param2text = Number of new children to add.
|param3 = min_idx
|param3text = Performs the same function as in <code>[[#addChild.28.29|Node.addChild()]]</code>.
|param4 = append
|param4text = Performs the same function as in <code>[[#addChild.28.29|Node.addChild()]]</code>.
|example1 = var node = props.Node.new();
node.addChildren("a", 2);
props.dump(node); # a[0] and a[1]
|example2 = var node = props.Node.new();
node.addChildren("a", 2, 1);
props.dump(node); # a[1] and a[2]
|example3 = var node = props.Node.new();
node.addChild("a", 2);
props.dump(node); # a[2]
node.addChildren("a", 2, 0, 0);
props.dump(node); # a[2], a[0], and a[1]
}}

==== adjustValue() (since FG 2020.1) ====
{{Nasal doc
|syntax = props.Node.adjustValue(delta);
|text = Adds delta (numeric) to current value respecting the node type.
|param1 = delta
|param1text = Numeric value (can be negative) to add to current node value.
}}

==== alias() ====
{{Nasal doc
|syntax = props.Node.alias(node, chainListener=0);
|text = Aliases this node to another one. Returns 1 on success and 0 on failure.
|param1 = node
|param1text = The node to alias to. Can be one of:
* A path to a property in the [[Property Tree]] as a string.
* A <code>prop</code> ghost.
* A <code>props.Node</code> object.
|example1 = var node = props.Node.new();
node.alias("/position/altitude-ft");
props.dump(node); # equals the current altitude
|example2 = var node1 = props.Node.new();
node1.setDoubleValue(2.34);
var node2 = props.Node.new();
node2.alias(node1);
props.dump(node2); # equals 2.34
|param2=chainListener|param2text=Specify if listeners should work on aliased properties or not. Current default is false forbackwards compatability.}}

==== clearValue() ====
{{Nasal doc
|syntax = props.Node.clearValue();
|text = Clears the value and type of the node.
|example1 = var node = props.Node.new();
node.setDoubleValue(2.34);
props.dump(node); # prints "{DOUBLE} = 2.35"
node.clearValue();
props.dump(node); # prints "{NONE} = nil"
}}

==== decrement() (since FG 2020.1) ====
{{Nasal doc
|syntax = props.Node.decrement(n = 1);
|text = Decrements integer property by n (default: n = 1)
|param1 = n
|param1text = Value to subtract, will be converted to int, defaults to 1
}}

==== equals() ====
{{Nasal doc
|syntax = props.Node.equals(node);
|version = 2.12
|commit = {{fgdata commit|d80722065f3c11e0511fa888b1f5f310dd0183e3|t=commit}}
|text = Checks whether the node refers to the same one as another. Returns 1 (true) if it is, and 0 (false) if otherwise.
|param1 = node
|param1text = Node to check against. May be either a <code>prop</code> ghost or a <code>props.Node</code> object.
|example1 = var n = props.Node.new();
var a = n;
print(a.equals(n)); # prints "1" (true)
}}

==== getAliasTarget() ====
{{Nasal doc
|syntax = props.Node.getAliasTarget();
|text = Returns the alias target of a node as another <code>props.Node</code> instance.
|example1 = setprop("/test", 2.35);
var node = props.Node.new();
node.alias("/test");
var tgt = node.getAliasTarget();
print(tgt.getPath()); # prints "/test"
}}

==== getAttribute() ====
{{Nasal doc
|syntax = props.Node.getAttribute([rel_path, ]name);
props.Node.getAttribute();
|text = Returns an attribute. If no arguments are given, the function will return an integer specifying the attributes set for the node (see {{simgear source|simgear/props/props.hxx|l=767}} for a list). A list of attributes are below
{{{!}} class="wikitable"
! String !! Return value
{{!-}}
{{!}} last {{!!}} The highest used attribute code (should be 128). See for {{simgear source|simgear/props/props.hxx|l=767}} the codes.
{{!-}}
{{!}} children {{!!}} Number of child nodes.
{{!-}}
{{!}} listeners {{!!}} Number of listeners connected to this node.
{{!-}}
{{!}} references {{!!}} Number of times the node has previously been referenced.
{{!-}}
{{!}} tied {{!!}} Whether the node is tied.
{{!-}}
{{!}} alias {{!!}} Whether the node is aliased.
{{!-}}
{{!}} readable {{!!}} Whether the node can be read.
{{!-}}
{{!}} writable {{!!}} Whether the node can be written to.
{{!-}}
{{!}} archive {{!!}} Whether the node will be saved when the "save" [[fgcommands|fgcommand]] is triggered.
{{!-}}
{{!}} trace-read {{!!}} Whether the reading of the node will be logged when <code>--log-level=info</code>.
{{!-}}
{{!}} trace-write {{!!}} Whether the writing to the node will be logged when <code>--log-level=info</code>.
{{!-}}
{{!}} userarchive {{!!}} Whether the node will be saved to the [[FlightGear configuration via XML#autosave.xml|autosave file]] (only works for actual properties).
{{!-}}
{{!}} preserve {{!!}} Whether the value of node will be preserved during resets (only works for actual properties).
{{!}}}
|param1 = rel_path
|param1text = Optional relative path as a string.
|param2 = name
|param2text = Attribute as a string. See the above table for a full list.
|example1 = var node = props.Node.new();
var child = node.addChild("a");
print(node.getAttribute("children")); # prints "1"
|example2text = Example using relative path
|example2 = var node = props.Node.new();
var child = node.addChild("a");
print(node.getAttribute("a", "readable")); # prints "1" (node can be read from)
|example3 = var node = props.Node.new();
var node2 = props.Node.new();
node2.alias(node);
print(node2.getAttribute("alias")); # prints "1" (true)
|example4 = print(props.globals.getNode("/sim/signals/fdm-initialized").getAttribute("listeners")); # prints the number of listeners
|example5 = print(props.globals.getNode("/sim/time/elapsed-sec").getAttribute("tied")); # prints "1" (true), meaning it is tied
|example6 = var node = props.Node.new();
print(node.getAttribute("writable")); # prints "1" (true), meaning the node can be written to
|example7text = Example using no arguments
|example7 = var node = props.Node.new();
print(node.getAttribute()); # prints "3" (true), meaning the node can be read from (1) and written to (2)
}}

==== getBoolValue() ====
{{Nasal doc
|syntax = props.Node.getBoolValue();
|text = Returns the value of a node converted to a boolean. If the node is a number type, 0 will return false, while 1 will return true. If the node is a string or unspecified type and the value is <code>"false"</code>, false will be returned. Otherwise, true will be returned. Remember that boolean values are represented in Nasal as 1 (true) and 0 (false).
|example1 = var node = props.Node.new();
node.setBoolValue(1);
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setBoolValue(0);
print(node.getBoolValue() ? "true" : "false"); # prints "false"
|example2 = var node = props.Node.new();
node.setDoubleValue(1.23);
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setDoubleValue(-1.23);
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setDoubleValue(0.0);
print(node.getBoolValue() ? "true" : "false"); # prints "false"
|example3 = var node = props.Node.new();
node.setIntValue(2);
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setIntValue(-2);
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setIntValue(0);
print(node.getBoolValue() ? "true" : "false"); # prints "false"
|example4 = var node = props.Node.new();
node.setValue("Hello, World!");
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setValue("false");
print(node.getBoolValue() ? "true" : "false"); # prints "false"
}}

==== getChild() ====
{{Nasal doc
|syntax = props.Node.getChild(rel_path[, idx[, create]]);
|text = Returns a child of a node as another <code>props.Node</code> instance.
|param1 = rel_path
|param1text = Relative path to the child node as a string.
|param2 = idx
|param2text = Optional index for the child node as an integer.
|param3 = create
|param3text = If set to true (1), a new child will be created if it does not exist. If set to false (0), the function will not create a new child and the function will return <code>'''nil'''</code> if no child exists. Defaults to false.
|example1 = var node = props.Node.new();
node.addChild("a");
var c = node.getChild("a");
|example2 = var node = props.Node.new();
node.addChildren("a", 3);
node.getNode("a[1]").setDoubleValue(2.35);
var c = node.getChild("a", 1);
print(c.getValue()); # prints "2.35"
|example3 = var node = props.Node.new();
var c = node.getChild("a", 1, true);
props.dump(node); # new child a[1] will have appeared
}}

==== getChildren() ====
{{Nasal doc
|syntax = props.Node.getChildren([name]);
|text = Returns a vector of child nodes, optionally those with a certain name, as <code>props.Node</code> instances.
|param1 = name
|param1text = Optional name of the child nodes as a string. If not given, all children will be returned.
|example1 = var node = props.Node.new();
node.addChildren("a", 3);
node.addChildren("b", 3);
debug.dump(node.getChildren()); # all child nodes in the vector
|example2 = var node = props.Node.new();
node.addChildren("a", 3);
node.addChildren("b", 3);
debug.dump(node.getChildren("b")); # only children with the name "b" in the vector
}}

==== getIndex() ====
{{Nasal doc
|syntax = props.Node.getIndex();
|text = Returns the index of a node as an integer.
|example1 = var node = props.Node.new();
node.addChildren("a", 3);
print(node.getChild("a", 1).getIndex()); # prints "1"
|example2 = var node = props.Node.new();
node.addChild("b");
print(node.getChild("b").getIndex()); # prints "0"
}}

==== getName() ====
{{Nasal doc
|syntax = props.Node.getName();
|text = Returns the name of the node as a string.
|example1 = var node = props.Node.new();
var c = node.addChild("a");
debug.dump(c.getName()); # prints "a"
|example2 = var node = props.Node.new();
node.addChildren("a", 3);
debug.dump(node.getChild("a", 2).getName()); # prints "a"
}}

==== getNode() ====
{{Nasal doc
|syntax = props.Node.getNode(rel_path[, create]);
|text = Returns a subnode as another <code>props.Node</code> instance.
|param1 = rel_path
|param1text = Relative path to the subnode as a string.
|param2 = create
|param2text = If true (1), the node will be created if it does not exist. If false (0) and the node does not exist, the function will return <code>'''nil'''</code>. Default to false (0).
|example1 = var tree = {
"a": 1,
"b": "Hi",
"c": {
"d": "Hello, World!"
}
};
var node = props.Node.new(tree);
print(node.getNode("c/d").getValue()); # prints "Hello, World!"
|example2 = var tree = {
"a": 1,
"b": "Hi",
"c": {}
};
var node = props.Node.new(tree);
node.getNode("c/d", true).setDoubleValue(2.35);
props.dump(node); # c/d now exists
|example3 = var ac = props.globals.getNode("sim/aircraft");
print("Current aircraft is: ", ac.getValue());
}}

==== getParent() ====
{{Nasal doc
|syntax = props.Node.getParent();
|text = Returns the parent of a node, or <code>'''nil'''</code> if there is no parent.
|example1 = var tree = {
"a": 1,
"b": "Hi",
"c": {
"d": "Hello, World!"
}
};
var node = props.Node.new(tree);
props.dump(node.getNode("c/d").getParent()); # dumps "c"
|example2 = var node = props.Node.new();
debug.dump(node.getParent()); # prints nil
}}

==== getPath() ====
{{Nasal doc
|syntax = props.Node.getPath();
|text = Returns the path of the node as a string.
|example1 = var tree = {
"a": 1,
"b": "Hi",
"c": {
"d": "Hello, World!"
}
};
var node = props.Node.new(tree);
print(node.getNode("c/d").getPath()); # prints "/c/d"
}}

==== getType() ====
{{Nasal doc
|syntax = props.Node.getType();
|text = Returns node's type as a string. It should be one of "NONE", "ALIAS", "BOOL", "INT", "LONG" (long integer), "FLOAT", "DOUBLE", "STRING", "VEC3D", "VEC4D", "UNSPECIFIED".
|example1 = var node = props.Node.new();
print(node.getType()); # prints "NONE"
|example2 = var node = props.Node.new();
node.setIntValue(12);
print(node.getType()); # prints "INT"
|example3 = var node = props.Node.new();
node.setValue([0.4, 0.2, 1]);
debug.dump(node.getValue()); # prints "[0.4, 0.2, 1]"
print(node.getType()); # prints "VEC3D"
}}

==== getValue() ====
{{Nasal doc
|syntax = props.Node.getValue([rel_path]);
|text = {{hatnote|See also {{func link|getBoolValue()|page=this}}.}}

Returns the value of the node.
|param1 = rel_path
|param1text = Optional relative path to a subnode as a string, which may contain '/' characters. If the subnode does not exist, we return nil.
|example1 = var node = props.Node.new();
node.setDoubleValue(2.35);
print(node.getValue()); # prints "2.35"
|example2 = var node = props.Node.new();
node.setValue("Hi");
print(node.getValue()); # prints "Hi"
|example3 = var node = props.Node.new();
node.addChild("a").setValue("Hi");
print(node.getValue("a")); # prints "Hi"
|example4 = var node = props.Node.new();
node.setValue([0, 0.5, 1]);
debug.dump(node.getValue()); # prints "[0, 0.5, 1]"
}}

==== getValues() ====
{{Nasal doc
|syntax = props.Node.getValues();
|text = Returns the node tree as a hash, with all the various subnodes, etc. If the node has no children, the result is equivalent to {{func link|getValue()|page=this}}. Subnodes that are indexed will be combined into one key and their values placed in a vector (see example 2).
|example1 = var tree = {
"string": "Hi",
"number": 1.2,
"subnode": {
"idx-node": [1, 2, 3]
}
};
var node = props.Node.new(tree);
node.addChild("bool").setBoolValue(1);
props.dump(node); # dump to node tree
debug.dump(node.getValues()); # dump the node converted to hash
|example2 = var tree = {
"a": [1, 2, 3]
};
var node = props.Node.new(tree);
props.dump(node); # a[0] = 1, a[1] = 2, a[2] = 3
debug.dump(node.getValues()); # a: [1, 2, 3]
}}

==== increment() (since FG 2020.1) ====
{{Nasal doc
|syntax = props.Node.increment(n = 1);
|text = Increments integer property by n (default: n = 1)
|param1 = n
|param1text = Value to add, will be converted to int, defaults to 1
}}

==== initNode() ====
{{Nasal doc
|syntax = props.Node.initNode([path[, value[, type[, force]]]]);
|text = Initializes a node if it doesn't exist and returns that node as a <code>props.Node</code> object.
|param1 = path
|param1text = Optional path to a subnode as a string. If not given, the node itself will be initialized.
|param2 = value
|param2text = Optional default value to initialize the node with.
|param3 = type
|param3text = Optional string that will set the type of the node. Must be one of <code>"DOUBLE"</code>, <code>"INT"</code>, <code>"BOOL"</code>, or <code>"STRING"</code>.
|param4 = force
|param4text = If set to true (1), the node's type will be forced to change.
|example1 = var node = props.Node.new();
var a = node.initNode("a");
props.dump(a);
|example2 = var node = props.Node.new();
var a = node.initNode("a", "Hi");
props.dump(a);
|example3 = var node = props.Node.new();
var a = node.initNode("a", 1.25, "INT");
props.dump(a); # a = 1
|example4 = var node = props.Node.new();
node.addChild("a").setBoolValue(0);
props.dump(node.getChild("a")); # a = 0 (type: bool)
var a = node.initNode("a", 1.25, "INT", true);
props.dump(a); # a = 0 (type: int)
}}

==== isInt() (since FG 2020.1) ====
{{Nasal doc
|syntax = props.Node.isInt();
|text = Returns true (1) if node '''type''' is "INT" or "LONG" (long integer) otherwise false (0).
}}

==== isNumeric() (since FG 2020.1) ====
{{Nasal doc
|syntax = props.Node.isNumeric();
|text = Returns true (1) if node '''type''' is "INT", "LONG", "FLOAT" or "DOUBLE" otherwise false (0).
}}

==== remove() ====
{{Nasal doc
|syntax = props.Node.remove();
|text = Removes the node and returns the removed node.
|example1 = var node = props.Node.new();
node.addChild("a");
props.dump(node);
node.getChild("a").remove();
props.dump(node); # child "a" does not exist anymore
}}

==== removeAllChildren() ====
{{Caution|Be careful when using this API in conjunction with the Canvas system and element specific properties, for details please see [[Howto:Canvas Path Benchmarking]]}}
{{Nasal doc
|syntax = props.Node.removeAllChildren();
|version = 3.2
|commit = {{fgdata commit|4766ed21a68230c0c15265e5604a74f4d99e0f5d|t=commit}}
|text = Removes all child nodes and returns the node.
|example1 = var tree = {
"a": 1,
"b": 2,
"c": 3
};
var node = props.Node.new(tree);
props.dump(node);
node.removeAllChildren();
props.dump(node); # all children have been removed
}}

==== removeChild() ====
{{Nasal doc
|syntax = props.Node.removeChild(rel_path, idx);
|text = Removes a given child node child nodes and returns the node.
|param1 = rel_path
|param1text = Relative path to a subnode as a string.
|param2 = idx
|param2text = Index of the subnode to remove as an integer.
|example1 = var node = props.Node.new();
node.addChild("a");
props.dump(node);
node.removeChild("a", 0);
props.dump(node); # child "a" has been removed
|example2 = var node = props.Node.new();
node.addChildren("a", 2);
props.dump(node);
node.removeChild("a", 0);
props.dump(node); # just a[1] remains
}}

==== removeChildren() ====
{{Nasal doc
|syntax = props.Node.removeChildren([name]);
|text = Removes all children with a specified name. If no arguments are given, all children will be removed (see also {{func link|removeAllChildren()|page=this}}).
|param1 = name
|param1text = Optional name of children to remove as a string.
|example1 = var node = props.Node.new();
node.addChildren("a", 2);
node.addChildren("b", 2);
props.dump(node);
node.removeChildren("a");
props.dump(node); # just children named "b" remain
|example2 = var node = props.Node.new();
node.addChildren("a", 2);
node.addChildren("b", 2);
props.dump(node);
node.removeChildren();
props.dump(node); # all children removed
}}

==== setAttribute() ====
{{Nasal doc
|syntax = props.Node.setAttribute([rel_path, ]attr, value);
props.Node.setAttribute(attrs);
|text = Sets an attribute or multiple attributes. A list of attributes and their codes are below. For a brand new node, the default attributes are ''readable'' and ''writable''. Returns an integer specifying the old attributes.
{{{!}} class="wikitable"
! String !! Description
{{!-}}
{{!}} readable {{!!}} Whether the node can be read.
{{!-}}
{{!}} writable {{!!}} Whether the node can be written to.
{{!-}}
{{!}} archive {{!!}} Whether the node will be saved when the "save" [[fgcommands|fgcommand]] is triggered.
{{!-}}
{{!}} trace-read {{!!}} Whether the reading of the node will be logged when <code>--log-level=info</code>.
{{!-}}
{{!}} trace-write {{!!}} Whether the writing to the node will be logged when <code>--log-level=info</code>.
{{!-}}
{{!}} userarchive {{!!}} Whether the node will be saved to the [[FlightGear configuration via XML#autosave.xml|autosave file]] (only works for actual properties).
{{!-}}
{{!}} preserve {{!!}} Whether the value of node will be preserved during resets (only works for actual properties).
{{!}}}
|param1 = rel_path
|param1text = Optional relative path as a string.
|param2 = attr
|param2text = Name of attribute to set as a string. See above.
|param3 = value
|param3text = Boolean value to set the property to.
|param4 = attrs
|param4text = When the function is used in its second form, this argument is used. This argument should be an integer specifying which arguments are set to true. See {{simgear source|simgear/props/props.hxx|l=767}} for the full list of codes. Simply add codes of the desired attributes together.
|example1 = var node = props.Node.new();
node.setAttribute("trace-write", 1);
node.setIntValue(12); # will be traced
|example2 = var node = props.Node.new();
node.setAttribute("readable", 0);
var val = node.getValue();
debug.dump(val); # prints "nil"
|example3 = var node = props.Node.new();
node.addChild("a");
node.setAttribute("a", "trace-write", 1);
node.getChild("a").setIntValue(12); # will be traced
|example4 = var node = props.Node.new();
node.setAttribute(35); # read + write + trace-write
node.setIntValue(12); # will be traced
}}

==== setBoolValue() ====
{{Nasal doc
|syntax = props.Node.setBoolValue([rel_path, ]value);
|text = {{note|For setting the values of [[Property Tree]] nodes, it is recommended to use {{func link|setprop()}} if possible, due to performance differences.}}

Sets a node to a boolean value. If the node has no type, it will be set to a bool type. If the node is already a number type, it will be set to either 1 or 0. If it is a string, it will be set to either "true" or "false". Returns 1 (true) if the operation was successful.
|param1 = rel_path
|param1text = Optional relative path as a string.
|param2 = value
|param2text = Value to set the node to, will be interpreted into a boolean. If it is <code>'''nil'''</code>, it will be false. If it is a string, it will be false. If it is a number, 0 will be false, while other numbers will be true. All other cases will be interpreted as 0.
|example1 = var node = props.Node.new();
node.setBoolValue(nil);
props.dump(node); # node = 0 (false)
|example2 = var node = props.Node.new();
node.setBoolValue("Hi");
props.dump(node); # node = 1 (true)
|example3 = var node = props.Node.new();
node.setBoolValue(0);
props.dump(node); # node = 0 (false)
node.setBoolValue(1.25);
props.dump(node); # node = 1 (true)
|example4 = var node = props.Node.new();
node.setValue("String");
props.dump(node); # node = "String" (type: string)
node.setBoolValue(1);
props.dump(node); # node = "true"
|example5 = var node = props.Node.new();
node.setDoubleValue(12.32);
props.dump(node); # node = 12.32 (type: double)
node.setBoolValue(1);
props.dump(node); # node = 1
|example6 = var node = props.Node.new();
node.addChild("a");
node.setBoolValue("a", 1);
props.dump(node); # /a = 1
}}

==== setDoubleValue() ====
{{Nasal doc
|syntax = props.Node.setDoubleValue([rel_path, ]value);
|text = {{note|For setting the values of [[Property Tree]] nodes, it is recommended to use {{func link|setprop()}} if possible, due to performance differences.}}

Sets a node to a double value. If the node has no type, it will be set to a double type. If the node is a bool, values different from zero will be interpreted as true. If the node is a string, the value will be converted to a string. If the node is an integer type, it will be truncated to the closest integer to zero. Returns 1 (true) if the operation was successful.
|param1 = rel_path
|param1text = Optional relative path as a string.
|param2 = value
|param2text = Value to set the node to, will be interpreted into a double number. It must be a valid number or a string that can be converted to a number.
|example1 = var node = props.Node.new();
node.setDoubleValue(1.1);
props.dump(node); # node = 1.1 (type: double)
|example2 = var node = props.Node.new();
node.setDoubleValue("1.1");
props.dump(node); # node = 1.1 (type: double)
|example3 = var node = props.Node.new();
node.setBoolValue(1);
node.setDoubleValue("1.1");
props.dump(node); # node = 1 (type: bool)
node.setDoubleValue(0.0);
props.dump(node); # node = 0 (type: bool)
|example4 = var node = props.Node.new();
node.setIntValue(1);
node.setDoubleValue(1.1);
props.dump(node); # node = 1 (type: int)
node.setDoubleValue("-1.1");
props.dump(node); # node = -1 (type: int)
|example5 = var node = props.Node.new();
node.addChild("a");
node.setDoubleValue("a", 12.2);
props.dump(node); # /a = 12.2
}}

==== setIntValue() ====
{{Nasal doc
|syntax = props.Node.setIntValue([rel_path, ]value);
|text = {{note|For setting the values of [[Property Tree]] nodes, it is recommended to use {{func link|setprop()}} if possible, due to performance differences.}}

Sets a node to an integer value. If the node has no type, it will be set to a integer type. If the node is a bool, values different from zero will be interpreted as true. If the node is a string, the value will be converted to a string. Returns 1 (true) if the operation was successful.
|param1 = rel_path
|param1text = Optional relative path as a string.
|param2 = value
|param2text = Value to set the node to, will be interpreted into a integer. It must be a valid number or a string that can be converted to a number. If the number is a double, it will be truncated to the closest integer to zero.
|example1 = var node = props.Node.new();
node.setIntValue(12);
props.dump(node); # node = 12
node.setIntValue("6");
props.dump(node); # node = 6
|example2 = var node = props.Node.new();
node.setIntValue(12.2);
props.dump(node); # node = 12
node.setIntValue(-12.2);
props.dump(node); # node = 12
|example3 = var node = props.Node.new();
node.setBoolValue(1);
node.setIntValue(12.5);
props.dump(node); # node = 1 (type: bool)
node.setIntValue(0);
props.dump(node); # node = 0 (type: bool)
|example4 = var node = props.Node.new();
node.setValue("Hi");
node.setIntValue(12);
props.dump(node); # node = "12" (type: string)
|example5 = var node = props.Node.new();
node.addChild("a");
node.setIntValue("a", 12);
props.dump(node); # /a = 12
}}

==== setValue() ====
{{Nasal doc
|syntax = props.Node.setValue([rel_path, ]value);
|text = {{hatnote|See also {{func link|setBoolValue()|page=this}}, {{func link|setDoubleValue()|page=this}}, and {{func link|setIntValue()|page=this}}.}}

{{note|For setting the values of [[Property Tree]] nodes, it is recommended to use {{func link|setprop()}} if possible, due to performance differences.}}

Sets a node to a given value. See table below for conversions and effects. Note that vec3d and vec4d types are not fully integrated into SGPropertyNode. Returns 1 (true) if the operation was successful.

{{{!}} class="wikitable"
{{!}} colspan="2" style="text-align:right" {{!}} '''value''' type →
! rowspan="2" {{!}} Number
! rowspan="2" {{!}} String
! rowspan="2" {{!}} Vector
{{!-}}
{{!}} style="text-align:left" {{!}} Current node<br>type ↓
{{!}} style="text-align:right" {{!}} Result ↘
{{!-}}
! colspan="2" {{!}} None/unspecified
{{!}}
* Type set to <code>double</code>
* Node set to '''value'''.
{{!}}
* Type set to <code>string</code>
* Node set to '''value'''.
{{!}}
* Type set to <code>vec*d</code>
* Node set to '''value'''.
{{!-}}
! colspan="2" {{!}} Bool
{{!}}
* If '''value''' != 0, node set to true.
* If '''value''' == 0, node set to false.
{{!}}
* If '''value''' == "true", node set to true.
* If '''value''' can be converted to an integer,<br>and != 0, node set to true.
{{!}} Node set to true.
{{!-}}
! colspan="2" {{!}} Integer
{{!}} Node set to truncated '''value'''
{{!}} Node set to '''value ''' converted and truncated to an integer.
{{!}} Node set to 1.
{{!-}}
! colspan="2" {{!}} Double
{{!}} Node set to '''value'''.
{{!}} Node set to '''value''' converted to number.
{{!}} Throws an error (vector is not a number).
{{!-}}
! colspan="2" {{!}} String
{{!}} Node set to '''value''' converted to string. {{!!}} Node set to '''value'''. {{!!}} Node not set.
{{!}}}
|param1 = rel_path
|param1text = Optional relative path as a string.
|param2 = value
|param2text = Value to set the node to. Must be a string, a valid number, or a vector consisting of 3 or 4 numbers. See table above for conversions and effects.
|example1 = var node = props.Node.new();
node.setValue("Hi");
props.dump(node); # node = "Hi"
|example2 = var node = props.Node.new();
node.addChild("a");
node.setValue("a", "Hi");
props.dump(node); # \a = "Hi"
|example3 = var node = props.Node.new();
node.setValue([0.4, 0.2, 1]);
debug.dump(node.getValue()); # prints "[0.4, 0.2, 1]"
print(node.getType()); # prints "VEC3D"
}}

==== setValues() ====
{{Nasal doc
|syntax = props.Node.setValues(val);
|text = {{hatnote|See also {{func link|getValues()|page=this}}.}}

Sets the nodes property tree from a Nasal hash. Scalars will become nodes in the tree and hashes will become named subnodes. Vectors will be converted into indexed nodes, with the values in the vector becoming their values (see examples below).
|param1 = val
|param1text = A hash that will become the property tree.
|example1 = var val = {
"a": 100 # "a" will become the subnode's name, and 100 its value
};
var node = props.Node.new();
node.setValues(val);
props.dump(node); # dump tree
|example2 = var val = {
"a": 1,
"b": "Hi",
"c": {
"d": [1, 2, 3]
}
};
var node = props.Node.new();
node.setValues(val);
props.dump(node); # dump tree
}}

==== unalias() ====
{{Nasal doc
|syntax = props.Node.unalias();
|text = Un-aliases the node and returns it to a blank state. Returns 1 on success and 0 on failure (e.g., when used on a tied property).
|example2 = var node1 = props.Node.new();
node1.setDoubleValue(2.35);
var node2 = props.Node.new();
node2.alias(node1);

props.dump(node2); # equals 2.35
node2.unalias();
props.dump(node2); # no value or type
}}

==== toggleBoolValue() (since FG 2020.1) ====
{{Nasal doc
|syntax = toggleBoolValue();
|text = Toggle a boolean property. You have to make sure the property is of type bool!
|example1 = var b = props.Node.new().initNode("/_test/bool", 1, "BOOL");
print("bool ", b.getValue());
b.toggleBoolValue();
print("after toggleBoolValue ", b.getValue());

}}

== Functions ==
=== compileCondition() ===
{{see also|Conditions}}

{{Nasal doc
|syntax = props.compileCondition(node);
|version = 3.2
|commit = {{fgdata commit|43f8ce08706629e69984b1cc34e5e979d03ef09a|t=commit}}
|text = Compiles a [[conditions|condition]] property branch and returns a <code>Condition</code> ghost object or <code>'''nil'''</code> on error. This ghost will contain a <code>test()</code> function that will return the result of the condition as either 1 (true) or 0 (false).
|param1 = node
|param1text = Either a props.Node containing the condition, or a string specifying a place in the [[Property Tree]] where there is a condition branch.
|example1 = var tree = {
"equals": {
"property": '/test',
"value": 12
}
};
var node = props.Node.new(tree);
setprop("/test", 12);

var cond = props.compileCondition(node);
print(cond.test()); # prints "1" (true)
setprop("/test", 15);
print(cond.test()); # prints "0" (false)
|example2 = var tree = {
"equals": {
"property": '/test',
"value": 12
}
};
props.globals.getNode("test2/condition", 1).setValues(tree); # place it in the Property Tree
setprop("/test", 12);

var cond = props.compileCondition(node);
print(cond.test()); # prints "1" (true)
setprop("/test", 15);
print(cond.test()); # prints "0" (false)
}}

=== condition() ===
{{Nasal doc
|syntax = props.condition(node);
|text = Evaluates a [[conditions|condition]] property branch and returns the result as a boolean.
|param1 = node
|param1text = Either a props.Node containing the condition, or a string specifying a place in the [[Property Tree]] where there is a condition branch.
|example1 = var tree = {
"equals": {
"property": '/test',
"value": 12
}
};
var node = props.Node.new(tree);
setprop("/test", 12);

print(props.condition(node)); # prints "1" (true)
setprop("/test", 15);
print(props.condition(node)); # prints "0" (false)
|example2 = var tree = {
"equals": {
"property": '/test',
"value": 12
}
};
props.globals.getNode("test2/condition", 1).setValues(tree); # place it in the Property Tree
setprop("/test", 12);

print(props.condition(node)); # prints "1" (true)
setprop("/test", 15);
print(props.condition(node)); # prints "0" (false)
}}

=== copy() ===
{{Nasal doc
|syntax = props.copy(src, dest[, attr]);
|text = Copies the property tree of the source into the destination node. Note that aliased properties will not be copied.
|param1 = src
|param1text = Source <code>props.Node object</code> to copy from.
|param2 = dest
|param2text = Destination <code>props.Node object</code> to copy to.
|param3 = attr
|param3text = If set to 1 (true), attributes will also be copied. Defaults to 0 (false).
|example1 = var tree = {
"a": 1.5,
"b": "Hi",
"c": {
"d": [1, 2, 3]
}
};
var src = props.Node.new(tree);
var dest = props.Node.new();
props.copy(src, dest);
props.dump(dest);
|example2 = var src = props.Node.new();
var a = src.addChild("a");
a.setAttribute("trace-write", 1);
a.setIntValue(12);
var dest = props.Node.new();
props.copy(src, dest, 1);
print(dest.getNode("a").getAttribute("trace-write")); # prints "1" (true)
}}

=== dump() ===
{{Nasal doc
|syntax = props.dump(node);
|text = Recursively dump the state of a node into the console, showing value and type of each node. Note that as of 10/2016, the value of vec*d type nodes cannot be dumped.
|param1 = node
|param1text = Node to dump.
|example1 = var node = var tree = {
"a": 12,
"b": "Hi",
"c": {
"d": [1, 2, 3]
}
};
var node = props.Node.new(tree);
props.dump(node); # dump into console
|example2 = # Dump the entire Property Tree
# Warning! This is an intensive operation!
props.dump(props.globals);
}}

=== getNode() ===
{{Nasal doc
|syntax = props.getNode();
|version = 3.2
|commit = {{fgdata commit|807062d0b6f858885547f27325e829c2bf42a12b|t=commit}}
|text = Shortcut for <syntaxhighlight lang="nasal" inline>props.globals.getNode()</syntaxhighlight>. See {{func link|getNode()||Node|page=this}} for full documentation.
|example1 = print("Current aircraft is: ", props.getNode("/sim/aircraft").getValue());
}}

=== nodeList() ===
{{Nasal doc
|syntax = props.nodeList(arg[, arg[, ...]]);
|text = Converts its arguments into a vector of node objects if possible and returns that vector.
|param1 = arg
|param1text = Object to operate on. Must be a node object, string, vector, hash, function, or <code>prop</code> ghost. Vectors and hashes must contain any of the other acceptable types, functions must return any of the other types, strings will be assumed to be paths to global properties, and ghosts will be converted into node objects. There may be any number of arguments.
|example1 = var node = props.Node.new();
var f = func(){
var n = props.Node.new();
return n._g;
}
var list = props.nodeList(node,
"/sim/aircraft",
["/sim/fg-root"],
{ "path": "/sim/fg-home" },
f
);
debug.dump(list); # dump list
|example2 = var root = "/sim/version/";
var info = [
root ~ "build-id",
root ~ "build-number",
root ~ "flightgear",
root ~ "hla-support",
root ~ "openscenegraph",
root ~ "revision",
root ~ "simgear"
];
info = props.nodeList(info); # turn into list of nodes
foreach(var n; info){
print(n.getValue()); # dump info
}
}}

=== runBinding() ===
{{Nasal doc
|syntax = props.runBinding(node[, module]);
|text = Runs a [[Bindings|binding]] element in a node object. Returns 1 (true) on success and 0 (false) on failure.
|param1 = node
|param1text = A {{tag|binding}} element as a node object.
|param2 = module
|param2text = Optional string specifying a module to run Nasal scripts in if the command is <code>nasal</code>. This argument will not override any {{tag|module}} element in the '''node'''
|example1 = var tree = {
"command": "dialog-show",
"dialog-name": "map" # open map
};
var binding = props.Node.new(tree);
props.runBinding(binding);
|example2 = var tree = {
"command": "nasal",
"script": 'print(pi)' # prints value of math.pi
};
var binding = props.Node.new(tree);
props.runBinding(binding, "math");
|example3 = var tree = {
"command": "nasal",
"script": 'print(pi)', # prints value of math.pi
"module": "math" # this is used
};
var binding = props.Node.new(tree);
props.runBinding(binding, "debug");
}}

=== setAll() ===
{{Nasal doc
|syntax = props.setAll(base, child, value);
|text = Sets indexed subnodes in the Property Tree with the same name to the same value.
|param1 = base
|param1text = Base path to the nodes.
|param2 = child
|param2text = Path to child nodes.
|param3 = value
|param3text = Value to set the subnodes to.
|example1 = # apply 50% throttle to all engines
props.setAll("/controls/engines/engine", "throttle", 0.5);
|example2 = var nodes = props.globals.addChildren("/test", 3);
foreach(var node; nodes){
node.addChild("a");
}
props.setAll("/test", "a", "Hi"); # set all children (test[*]/a) to "Hi"
}}

=== wrap() ===
{{Nasal doc
|syntax = props.wrap(node);
|text = Turns <code>prop</code> ghosts, either in a vector or single, into <code>props.Node</code> objects.
|param1 = node
|param1text = <code>prop</code> ghost or vector of such ghosts.
|example1 = var ghost = canvas._newCanvasGhost();
var node = props.wrap(ghost._node_ghost);
props.dump(node);
|example2 = var vector = [canvas._newCanvasGhost()._node_ghost, props.Node.new()._g];
var nodes = props.wrap(vector);
foreach(var node; nodes){
props.dump(node);
print("----");
}
}}

=== wrapNode() ===
{{Nasal doc
|syntax = props.wrapNode(node);
|text = Turns a <code>prop</code> ghost into a <code>props.Node</code> object.
|param1 = node
|param1text = <code>prop</code> ghost to convert.
|example1 = var ghost = canvas._newCanvasGhost();
var node = props.wrapNode(ghost._node_ghost);
props.dump(node);
}}

== Variable ==
=== globals ===
{{Nasal doc
|syntax = props.globals;
|text = Exposes the [[Property Tree]] as a <code>props.Node</code> object.

|example1 = print("Current aircraft: ", props.globals.getNode("/sim/aircraft").getValue());
|example2text = Alternative using {{func link|getprop()}}.
|example2 = print("Current aircraft: ", getprop("/sim/aircraft"));
}}

{{Nasal namespaces}}

Nasal library/props

2025-12-04T18:34:22Z

PlayeRom: /* addChild() */

{{Nasal Navigation|nocat=1}}
This page contains documentation for the '''<code>props</code> namespace''' in [[Nasal]]. This namespace provides APIs for working with property trees (including the main [[Property Tree]]) via {{API Link|simgear|class|SGPropertyNode}}. The <code>props</code> namespace is sourced from {{fgdata source|Nasal/props.nas}} and {{flightgear source|src/Scripting/nasal-props.cxx}}.

== Class ==
=== Node ===
{{Nasal doc
|mode = class
|text = The main class, used widely for manipulating property trees.
}}
==== new() ====
{{Nasal doc
|syntax = props.Node.new([values]);
|text = Constructor function. Returns a new <code>props.Node</code> instance.
|param1 = values
|param1text = An optional hash that will be the initial property structure.
|example1 = var node = props.Node.new();
props.dump(node);
|example2 = var tree = {
a: 1,
b: ["a", "b", "c"],
c: {
d: 1 * 4
}
};

var node = props.Node.new(tree);
props.dump(node);
}}

==== addChild() ====
{{Nasal doc
|syntax = props.Node.addChild(name[, min_idx[, append]]);
|version = 2.10
|commit = {{fgdata commit|a15d5829379864c7138edff621d6864c5f426d0b|t=commit}}
|text = Add a new, blank child to the node. Returns the newly-created node.
|param1 = name
|param1text = The name of the node as a string.
|param2 = min_idx
|param2text = This specifies the minimum index to add the new one to. This takes precedence over '''append'''. Defaults to 0.
|param3 = append
|param3text = If there is already one or more children with the same name and this argument is true (1), the new child will be added after the child with the highest index. If false (0), the new child will be added at the lowest available index with the limit of '''min_idx'''. Defaults to true (1).
|example1 = var node = props.Node.new();
node.addChild("a");
props.dump(node);
|example2 = var node = props.Node.new();
node.addChild("a", 1);
props.dump(node); # a[1]
|example3 = var node = props.Node.new();
node.addChild("a", 1);
props.dump(node); # a[1]
node.addChild("a", 0, false);
props.dump(node); # a[1] and a[0]
|example4 = var node = props.Node.new();
node.addChild("a", 1);
props.dump(node); # a[1]
node.addChild("a", 0, true);
props.dump(node); # a[1] and a[2]
}}

==== addChildren() ====
{{Nasal doc
|syntax = props.Node.addChildren(name, count[, min_idx[, append]]);
|version = 2.10
|commit = {{fgdata commit|7f1117a5374beabb045fb76fbb6dd8bfb0128100|t=commit}}
|text = Adds multiple children with the same name to this node. Returns <code>'''nil</code>.
|param1 = name
|param1text = The name of the nodes as a string.
|param2 = count
|param2text = Number of new children to add.
|param3 = min_idx
|param3text = Performs the same function as in <code>[[#addChild.28.29|Node.addChild()]]</code>.
|param4 = append
|param4text = Performs the same function as in <code>[[#addChild.28.29|Node.addChild()]]</code>.
|example1 = var node = props.Node.new();
node.addChildren("a", 2);
props.dump(node); # a[0] and a[1]
|example2 = var node = props.Node.new();
node.addChildren("a", 2, 1);
props.dump(node); # a[1] and a[2]
|example3 = var node = props.Node.new();
node.addChild("a", 2);
props.dump(node); # a[2]
node.addChildren("a", 2, 0, 0);
props.dump(node); # a[2], a[0], and a[1]
}}

==== adjustValue() (since FG 2020.1) ====
{{Nasal doc
|syntax = props.Node.adjustValue(delta);
|text = Adds delta (numeric) to current value respecting the node type.
|param1 = delta
|param1text = Numeric value (can be negative) to add to current node value.
}}

==== alias() ====
{{Nasal doc
|syntax = props.Node.alias(node, chainListener=0);
|text = Aliases this node to another one. Returns 1 on success and 0 on failure.
|param1 = node
|param1text = The node to alias to. Can be one of:
* A path to a property in the [[Property Tree]] as a string.
* A <code>prop</code> ghost.
* A <code>props.Node</code> object.
|example1 = var node = props.Node.new();
node.alias("/position/altitude-ft");
props.dump(node); # equals the current altitude
|example2 = var node1 = props.Node.new();
node1.setDoubleValue(2.34);
var node2 = props.Node.new();
node2.alias(node1);
props.dump(node2); # equals 2.34
|param2=chainListener|param2text=Specify if listeners should work on aliased properties or not. Current default is false forbackwards compatability.}}

==== clearValue() ====
{{Nasal doc
|syntax = props.Node.clearValue();
|text = Clears the value and type of the node.
|example1 = var node = props.Node.new();
node.setDoubleValue(2.34);
props.dump(node); # prints "{DOUBLE} = 2.35"
node.clearValue();
props.dump(node); # prints "{NONE} = nil"
}}

==== decrement() (since FG 2020.1) ====
{{Nasal doc
|syntax = props.Node.decrement(n = 1);
|text = Decrements integer property by n (default: n = 1)
|param1 = n
|param1text = Value to subtract, will be converted to int, defaults to 1
}}

==== equals() ====
{{Nasal doc
|syntax = props.Node.equals(node);
|version = 2.12
|commit = {{fgdata commit|d80722065f3c11e0511fa888b1f5f310dd0183e3|t=commit}}
|text = Checks whether the node refers to the same one as another. Returns 1 (true) if it is, and 0 (false) if otherwise.
|param1 = node
|param1text = Node to check against. May be either a <code>prop</code> ghost or a <code>props.Node</code> object.
|example1 = var n = props.Node.new();
var a = n;
print(a.equals(n)); # prints "1" (true)
}}

==== getAliasTarget() ====
{{Nasal doc
|syntax = props.Node.getAliasTarget();
|text = Returns the alias target of a node as another <code>props.Node</code> instance.
|example1 = setprop("/test", 2.35);
var node = props.Node.new();
node.alias("/test");
var tgt = node.getAliasTarget();
print(tgt.getPath()); # prints "/test"
}}

==== getAttribute() ====
{{Nasal doc
|syntax = props.Node.getAttribute([rel_path, ]name);
props.Node.getAttribute();
|text = Returns an attribute. If no arguments are given, the function will return an integer specifying the attributes set for the node (see {{simgear source|simgear/props/props.hxx|l=767}} for a list). A list of attributes are below
{{{!}} class="wikitable"
! String !! Return value
{{!-}}
{{!}} last {{!!}} The highest used attribute code (should be 128). See for {{simgear source|simgear/props/props.hxx|l=767}} the codes.
{{!-}}
{{!}} children {{!!}} Number of child nodes.
{{!-}}
{{!}} listeners {{!!}} Number of listeners connected to this node.
{{!-}}
{{!}} references {{!!}} Number of times the node has previously been referenced.
{{!-}}
{{!}} tied {{!!}} Whether the node is tied.
{{!-}}
{{!}} alias {{!!}} Whether the node is aliased.
{{!-}}
{{!}} readable {{!!}} Whether the node can be read.
{{!-}}
{{!}} writable {{!!}} Whether the node can be written to.
{{!-}}
{{!}} archive {{!!}} Whether the node will be saved when the "save" [[fgcommands|fgcommand]] is triggered.
{{!-}}
{{!}} trace-read {{!!}} Whether the reading of the node will be logged when <code>--log-level=info</code>.
{{!-}}
{{!}} trace-write {{!!}} Whether the writing to the node will be logged when <code>--log-level=info</code>.
{{!-}}
{{!}} userarchive {{!!}} Whether the node will be saved to the [[FlightGear configuration via XML#autosave.xml|autosave file]] (only works for actual properties).
{{!-}}
{{!}} preserve {{!!}} Whether the value of node will be preserved during resets (only works for actual properties).
{{!}}}
|param1 = rel_path
|param1text = Optional relative path as a string.
|param2 = name
|param2text = Attribute as a string. See the above table for a full list.
|example1 = var node = props.Node.new();
var child = node.addChild("a");
print(node.getAttribute("children")); # prints "1"
|example2text = Example using relative path
|example2 = var node = props.Node.new();
var child = node.addChild("a");
print(node.getAttribute("a", "readable")); # prints "1" (node can be read from)
|example3 = var node = props.Node.new();
var node2 = props.Node.new();
node2.alias(node);
print(node2.getAttribute("alias")); # prints "1" (true)
|example4 = print(props.globals.getNode("/sim/signals/fdm-initialized").getAttribute("listeners")); # prints the number of listeners
|example5 = print(props.globals.getNode("/sim/time/elapsed-sec").getAttribute("tied")); # prints "1" (true), meaning it is tied
|example6 = var node = props.Node.new();
print(node.getAttribute("writable")); # prints "1" (true), meaning the node can be written to
|example7text = Example using no arguments
|example7 = var node = props.Node.new();
print(node.getAttribute()); # prints "3" (true), meaning the node can be read from (1) and written to (2)
}}

==== getBoolValue() ====
{{Nasal doc
|syntax = props.Node.getBoolValue();
|text = Returns the value of a node converted to a boolean. If the node is a number type, 0 will return false, while 1 will return true. If the node is a string or unspecified type and the value is <code>"false"</code>, false will be returned. Otherwise, true will be returned. Remember that boolean values are represented in Nasal as 1 (true) and 0 (false).
|example1 = var node = props.Node.new();
node.setBoolValue(1);
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setBoolValue(0);
print(node.getBoolValue() ? "true" : "false"); # prints "false"
|example2 = var node = props.Node.new();
node.setDoubleValue(1.23);
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setDoubleValue(-1.23);
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setDoubleValue(0.0);
print(node.getBoolValue() ? "true" : "false"); # prints "false"
|example3 = var node = props.Node.new();
node.setIntValue(2);
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setIntValue(-2);
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setIntValue(0);
print(node.getBoolValue() ? "true" : "false"); # prints "false"
|example4 = var node = props.Node.new();
node.setValue("Hello, World!");
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setValue("false");
print(node.getBoolValue() ? "true" : "false"); # prints "false"
}}

==== getChild() ====
{{Nasal doc
|syntax = props.Node.getChild(rel_path[, idx[, create]]);
|text = Returns a child of a node as another <code>props.Node</code> instance.
|param1 = rel_path
|param1text = Relative path to the child node as a string.
|param2 = idx
|param2text = Optional index for the child node as an integer.
|param3 = create
|param3text = If set to 1 (true), a new child will be created if it does not exist. If set to 0 (false), the function will not create a new child and the function will return <code>'''nil'''</code> if no child exists. Defaults to 0.
|example1 = var node = props.Node.new();
node.addChild("a");
var c = node.getChild("a");
|example2 = var node = props.Node.new();
node.addChildren("a", 3);
node.getNode("a[1]").setDoubleValue(2.35);
var c = node.getChild("a", 1);
print(c.getValue()); # prints "2.35"
|example3 = var node = props.Node.new();
var c = node.getChild("a", 1, 1);
props.dump(node); # new child a[1] will have appeared
}}

==== getChildren() ====
{{Nasal doc
|syntax = props.Node.getChildren([name]);
|text = Returns a vector of child nodes, optionally those with a certain name, as <code>props.Node</code> instances.
|param1 = name
|param1text = Optional name of the child nodes as a string. If not given, all children will be returned.
|example1 = var node = props.Node.new();
node.addChildren("a", 3);
node.addChildren("b", 3);
debug.dump(node.getChildren()); # all child nodes in the vector
|example2 = var node = props.Node.new();
node.addChildren("a", 3);
node.addChildren("b", 3);
debug.dump(node.getChildren("b")); # only children with the name "b" in the vector
}}

==== getIndex() ====
{{Nasal doc
|syntax = props.Node.getIndex();
|text = Returns the index of a node as an integer.
|example1 = var node = props.Node.new();
node.addChildren("a", 3);
print(node.getChild("a", 1).getIndex()); # prints "1"
|example2 = var node = props.Node.new();
node.addChild("b");
print(node.getChild("b").getIndex()); # prints "0"
}}

==== getName() ====
{{Nasal doc
|syntax = props.Node.getName();
|text = Returns the name of the node as a string.
|example1 = var node = props.Node.new();
var c = node.addChild("a");
debug.dump(c.getName()); # prints "a"
|example2 = var node = props.Node.new();
node.addChildren("a", 3);
debug.dump(node.getChild("a", 2).getName()); # prints "a"
}}

==== getNode() ====
{{Nasal doc
|syntax = props.Node.getNode(rel_path[, create]);
|text = Returns a subnode as another <code>props.Node</code> instance.
|param1 = rel_path
|param1text = Relative path to the subnode as a string.
|param2 = create
|param2text = If true (1), the node will be created if it does not exist. If false (0) and the node does not exist, the function will return <code>'''nil'''</code>. Default to false (0).
|example1 = var tree = {
"a": 1,
"b": "Hi",
"c": {
"d": "Hello, World!"
}
};
var node = props.Node.new(tree);
print(node.getNode("c/d").getValue()); # prints "Hello, World!"
|example2 = var tree = {
"a": 1,
"b": "Hi",
"c": {}
};
var node = props.Node.new(tree);
node.getNode("c/d", true).setDoubleValue(2.35);
props.dump(node); # c/d now exists
|example3 = var ac = props.globals.getNode("sim/aircraft");
print("Current aircraft is: ", ac.getValue());
}}

==== getParent() ====
{{Nasal doc
|syntax = props.Node.getParent();
|text = Returns the parent of a node, or <code>'''nil'''</code> if there is no parent.
|example1 = var tree = {
"a": 1,
"b": "Hi",
"c": {
"d": "Hello, World!"
}
};
var node = props.Node.new(tree);
props.dump(node.getNode("c/d").getParent()); # dumps "c"
|example2 = var node = props.Node.new();
debug.dump(node.getParent()); # prints nil
}}

==== getPath() ====
{{Nasal doc
|syntax = props.Node.getPath();
|text = Returns the path of the node as a string.
|example1 = var tree = {
"a": 1,
"b": "Hi",
"c": {
"d": "Hello, World!"
}
};
var node = props.Node.new(tree);
print(node.getNode("c/d").getPath()); # prints "/c/d"
}}

==== getType() ====
{{Nasal doc
|syntax = props.Node.getType();
|text = Returns node's type as a string. It should be one of "NONE", "ALIAS", "BOOL", "INT", "LONG" (long integer), "FLOAT", "DOUBLE", "STRING", "VEC3D", "VEC4D", "UNSPECIFIED".
|example1 = var node = props.Node.new();
print(node.getType()); # prints "NONE"
|example2 = var node = props.Node.new();
node.setIntValue(12);
print(node.getType()); # prints "INT"
|example3 = var node = props.Node.new();
node.setValue([0.4, 0.2, 1]);
debug.dump(node.getValue()); # prints "[0.4, 0.2, 1]"
print(node.getType()); # prints "VEC3D"
}}

==== getValue() ====
{{Nasal doc
|syntax = props.Node.getValue([rel_path]);
|text = {{hatnote|See also {{func link|getBoolValue()|page=this}}.}}

Returns the value of the node.
|param1 = rel_path
|param1text = Optional relative path to a subnode as a string, which may contain '/' characters. If the subnode does not exist, we return nil.
|example1 = var node = props.Node.new();
node.setDoubleValue(2.35);
print(node.getValue()); # prints "2.35"
|example2 = var node = props.Node.new();
node.setValue("Hi");
print(node.getValue()); # prints "Hi"
|example3 = var node = props.Node.new();
node.addChild("a").setValue("Hi");
print(node.getValue("a")); # prints "Hi"
|example4 = var node = props.Node.new();
node.setValue([0, 0.5, 1]);
debug.dump(node.getValue()); # prints "[0, 0.5, 1]"
}}

==== getValues() ====
{{Nasal doc
|syntax = props.Node.getValues();
|text = Returns the node tree as a hash, with all the various subnodes, etc. If the node has no children, the result is equivalent to {{func link|getValue()|page=this}}. Subnodes that are indexed will be combined into one key and their values placed in a vector (see example 2).
|example1 = var tree = {
"string": "Hi",
"number": 1.2,
"subnode": {
"idx-node": [1, 2, 3]
}
};
var node = props.Node.new(tree);
node.addChild("bool").setBoolValue(1);
props.dump(node); # dump to node tree
debug.dump(node.getValues()); # dump the node converted to hash
|example2 = var tree = {
"a": [1, 2, 3]
};
var node = props.Node.new(tree);
props.dump(node); # a[0] = 1, a[1] = 2, a[2] = 3
debug.dump(node.getValues()); # a: [1, 2, 3]
}}

==== increment() (since FG 2020.1) ====
{{Nasal doc
|syntax = props.Node.increment(n = 1);
|text = Increments integer property by n (default: n = 1)
|param1 = n
|param1text = Value to add, will be converted to int, defaults to 1
}}

==== initNode() ====
{{Nasal doc
|syntax = props.Node.initNode([path[, value[, type[, force]]]]);
|text = Initializes a node if it doesn't exist and returns that node as a <code>props.Node</code> object.
|param1 = path
|param1text = Optional path to a subnode as a string. If not given, the node itself will be initialized.
|param2 = value
|param2text = Optional default value to initialize the node with.
|param3 = type
|param3text = Optional string that will set the type of the node. Must be one of <code>"DOUBLE"</code>, <code>"INT"</code>, <code>"BOOL"</code>, or <code>"STRING"</code>.
|param4 = force
|param4text = If set to true (1), the node's type will be forced to change.
|example1 = var node = props.Node.new();
var a = node.initNode("a");
props.dump(a);
|example2 = var node = props.Node.new();
var a = node.initNode("a", "Hi");
props.dump(a);
|example3 = var node = props.Node.new();
var a = node.initNode("a", 1.25, "INT");
props.dump(a); # a = 1
|example4 = var node = props.Node.new();
node.addChild("a").setBoolValue(0);
props.dump(node.getChild("a")); # a = 0 (type: bool)
var a = node.initNode("a", 1.25, "INT", true);
props.dump(a); # a = 0 (type: int)
}}

==== isInt() (since FG 2020.1) ====
{{Nasal doc
|syntax = props.Node.isInt();
|text = Returns true (1) if node '''type''' is "INT" or "LONG" (long integer) otherwise false (0).
}}

==== isNumeric() (since FG 2020.1) ====
{{Nasal doc
|syntax = props.Node.isNumeric();
|text = Returns true (1) if node '''type''' is "INT", "LONG", "FLOAT" or "DOUBLE" otherwise false (0).
}}

==== remove() ====
{{Nasal doc
|syntax = props.Node.remove();
|text = Removes the node and returns the removed node.
|example1 = var node = props.Node.new();
node.addChild("a");
props.dump(node);
node.getChild("a").remove();
props.dump(node); # child "a" does not exist anymore
}}

==== removeAllChildren() ====
{{Caution|Be careful when using this API in conjunction with the Canvas system and element specific properties, for details please see [[Howto:Canvas Path Benchmarking]]}}
{{Nasal doc
|syntax = props.Node.removeAllChildren();
|version = 3.2
|commit = {{fgdata commit|4766ed21a68230c0c15265e5604a74f4d99e0f5d|t=commit}}
|text = Removes all child nodes and returns the node.
|example1 = var tree = {
"a": 1,
"b": 2,
"c": 3
};
var node = props.Node.new(tree);
props.dump(node);
node.removeAllChildren();
props.dump(node); # all children have been removed
}}

==== removeChild() ====
{{Nasal doc
|syntax = props.Node.removeChild(rel_path, idx);
|text = Removes a given child node child nodes and returns the node.
|param1 = rel_path
|param1text = Relative path to a subnode as a string.
|param2 = idx
|param2text = Index of the subnode to remove as an integer.
|example1 = var node = props.Node.new();
node.addChild("a");
props.dump(node);
node.removeChild("a", 0);
props.dump(node); # child "a" has been removed
|example2 = var node = props.Node.new();
node.addChildren("a", 2);
props.dump(node);
node.removeChild("a", 0);
props.dump(node); # just a[1] remains
}}

==== removeChildren() ====
{{Nasal doc
|syntax = props.Node.removeChildren([name]);
|text = Removes all children with a specified name. If no arguments are given, all children will be removed (see also {{func link|removeAllChildren()|page=this}}).
|param1 = name
|param1text = Optional name of children to remove as a string.
|example1 = var node = props.Node.new();
node.addChildren("a", 2);
node.addChildren("b", 2);
props.dump(node);
node.removeChildren("a");
props.dump(node); # just children named "b" remain
|example2 = var node = props.Node.new();
node.addChildren("a", 2);
node.addChildren("b", 2);
props.dump(node);
node.removeChildren();
props.dump(node); # all children removed
}}

==== setAttribute() ====
{{Nasal doc
|syntax = props.Node.setAttribute([rel_path, ]attr, value);
props.Node.setAttribute(attrs);
|text = Sets an attribute or multiple attributes. A list of attributes and their codes are below. For a brand new node, the default attributes are ''readable'' and ''writable''. Returns an integer specifying the old attributes.
{{{!}} class="wikitable"
! String !! Description
{{!-}}
{{!}} readable {{!!}} Whether the node can be read.
{{!-}}
{{!}} writable {{!!}} Whether the node can be written to.
{{!-}}
{{!}} archive {{!!}} Whether the node will be saved when the "save" [[fgcommands|fgcommand]] is triggered.
{{!-}}
{{!}} trace-read {{!!}} Whether the reading of the node will be logged when <code>--log-level=info</code>.
{{!-}}
{{!}} trace-write {{!!}} Whether the writing to the node will be logged when <code>--log-level=info</code>.
{{!-}}
{{!}} userarchive {{!!}} Whether the node will be saved to the [[FlightGear configuration via XML#autosave.xml|autosave file]] (only works for actual properties).
{{!-}}
{{!}} preserve {{!!}} Whether the value of node will be preserved during resets (only works for actual properties).
{{!}}}
|param1 = rel_path
|param1text = Optional relative path as a string.
|param2 = attr
|param2text = Name of attribute to set as a string. See above.
|param3 = value
|param3text = Boolean value to set the property to.
|param4 = attrs
|param4text = When the function is used in its second form, this argument is used. This argument should be an integer specifying which arguments are set to true. See {{simgear source|simgear/props/props.hxx|l=767}} for the full list of codes. Simply add codes of the desired attributes together.
|example1 = var node = props.Node.new();
node.setAttribute("trace-write", 1);
node.setIntValue(12); # will be traced
|example2 = var node = props.Node.new();
node.setAttribute("readable", 0);
var val = node.getValue();
debug.dump(val); # prints "nil"
|example3 = var node = props.Node.new();
node.addChild("a");
node.setAttribute("a", "trace-write", 1);
node.getChild("a").setIntValue(12); # will be traced
|example4 = var node = props.Node.new();
node.setAttribute(35); # read + write + trace-write
node.setIntValue(12); # will be traced
}}

==== setBoolValue() ====
{{Nasal doc
|syntax = props.Node.setBoolValue([rel_path, ]value);
|text = {{note|For setting the values of [[Property Tree]] nodes, it is recommended to use {{func link|setprop()}} if possible, due to performance differences.}}

Sets a node to a boolean value. If the node has no type, it will be set to a bool type. If the node is already a number type, it will be set to either 1 or 0. If it is a string, it will be set to either "true" or "false". Returns 1 (true) if the operation was successful.
|param1 = rel_path
|param1text = Optional relative path as a string.
|param2 = value
|param2text = Value to set the node to, will be interpreted into a boolean. If it is <code>'''nil'''</code>, it will be false. If it is a string, it will be false. If it is a number, 0 will be false, while other numbers will be true. All other cases will be interpreted as 0.
|example1 = var node = props.Node.new();
node.setBoolValue(nil);
props.dump(node); # node = 0 (false)
|example2 = var node = props.Node.new();
node.setBoolValue("Hi");
props.dump(node); # node = 1 (true)
|example3 = var node = props.Node.new();
node.setBoolValue(0);
props.dump(node); # node = 0 (false)
node.setBoolValue(1.25);
props.dump(node); # node = 1 (true)
|example4 = var node = props.Node.new();
node.setValue("String");
props.dump(node); # node = "String" (type: string)
node.setBoolValue(1);
props.dump(node); # node = "true"
|example5 = var node = props.Node.new();
node.setDoubleValue(12.32);
props.dump(node); # node = 12.32 (type: double)
node.setBoolValue(1);
props.dump(node); # node = 1
|example6 = var node = props.Node.new();
node.addChild("a");
node.setBoolValue("a", 1);
props.dump(node); # /a = 1
}}

==== setDoubleValue() ====
{{Nasal doc
|syntax = props.Node.setDoubleValue([rel_path, ]value);
|text = {{note|For setting the values of [[Property Tree]] nodes, it is recommended to use {{func link|setprop()}} if possible, due to performance differences.}}

Sets a node to a double value. If the node has no type, it will be set to a double type. If the node is a bool, values different from zero will be interpreted as true. If the node is a string, the value will be converted to a string. If the node is an integer type, it will be truncated to the closest integer to zero. Returns 1 (true) if the operation was successful.
|param1 = rel_path
|param1text = Optional relative path as a string.
|param2 = value
|param2text = Value to set the node to, will be interpreted into a double number. It must be a valid number or a string that can be converted to a number.
|example1 = var node = props.Node.new();
node.setDoubleValue(1.1);
props.dump(node); # node = 1.1 (type: double)
|example2 = var node = props.Node.new();
node.setDoubleValue("1.1");
props.dump(node); # node = 1.1 (type: double)
|example3 = var node = props.Node.new();
node.setBoolValue(1);
node.setDoubleValue("1.1");
props.dump(node); # node = 1 (type: bool)
node.setDoubleValue(0.0);
props.dump(node); # node = 0 (type: bool)
|example4 = var node = props.Node.new();
node.setIntValue(1);
node.setDoubleValue(1.1);
props.dump(node); # node = 1 (type: int)
node.setDoubleValue("-1.1");
props.dump(node); # node = -1 (type: int)
|example5 = var node = props.Node.new();
node.addChild("a");
node.setDoubleValue("a", 12.2);
props.dump(node); # /a = 12.2
}}

==== setIntValue() ====
{{Nasal doc
|syntax = props.Node.setIntValue([rel_path, ]value);
|text = {{note|For setting the values of [[Property Tree]] nodes, it is recommended to use {{func link|setprop()}} if possible, due to performance differences.}}

Sets a node to an integer value. If the node has no type, it will be set to a integer type. If the node is a bool, values different from zero will be interpreted as true. If the node is a string, the value will be converted to a string. Returns 1 (true) if the operation was successful.
|param1 = rel_path
|param1text = Optional relative path as a string.
|param2 = value
|param2text = Value to set the node to, will be interpreted into a integer. It must be a valid number or a string that can be converted to a number. If the number is a double, it will be truncated to the closest integer to zero.
|example1 = var node = props.Node.new();
node.setIntValue(12);
props.dump(node); # node = 12
node.setIntValue("6");
props.dump(node); # node = 6
|example2 = var node = props.Node.new();
node.setIntValue(12.2);
props.dump(node); # node = 12
node.setIntValue(-12.2);
props.dump(node); # node = 12
|example3 = var node = props.Node.new();
node.setBoolValue(1);
node.setIntValue(12.5);
props.dump(node); # node = 1 (type: bool)
node.setIntValue(0);
props.dump(node); # node = 0 (type: bool)
|example4 = var node = props.Node.new();
node.setValue("Hi");
node.setIntValue(12);
props.dump(node); # node = "12" (type: string)
|example5 = var node = props.Node.new();
node.addChild("a");
node.setIntValue("a", 12);
props.dump(node); # /a = 12
}}

==== setValue() ====
{{Nasal doc
|syntax = props.Node.setValue([rel_path, ]value);
|text = {{hatnote|See also {{func link|setBoolValue()|page=this}}, {{func link|setDoubleValue()|page=this}}, and {{func link|setIntValue()|page=this}}.}}

{{note|For setting the values of [[Property Tree]] nodes, it is recommended to use {{func link|setprop()}} if possible, due to performance differences.}}

Sets a node to a given value. See table below for conversions and effects. Note that vec3d and vec4d types are not fully integrated into SGPropertyNode. Returns 1 (true) if the operation was successful.

{{{!}} class="wikitable"
{{!}} colspan="2" style="text-align:right" {{!}} '''value''' type →
! rowspan="2" {{!}} Number
! rowspan="2" {{!}} String
! rowspan="2" {{!}} Vector
{{!-}}
{{!}} style="text-align:left" {{!}} Current node<br>type ↓
{{!}} style="text-align:right" {{!}} Result ↘
{{!-}}
! colspan="2" {{!}} None/unspecified
{{!}}
* Type set to <code>double</code>
* Node set to '''value'''.
{{!}}
* Type set to <code>string</code>
* Node set to '''value'''.
{{!}}
* Type set to <code>vec*d</code>
* Node set to '''value'''.
{{!-}}
! colspan="2" {{!}} Bool
{{!}}
* If '''value''' != 0, node set to true.
* If '''value''' == 0, node set to false.
{{!}}
* If '''value''' == "true", node set to true.
* If '''value''' can be converted to an integer,<br>and != 0, node set to true.
{{!}} Node set to true.
{{!-}}
! colspan="2" {{!}} Integer
{{!}} Node set to truncated '''value'''
{{!}} Node set to '''value ''' converted and truncated to an integer.
{{!}} Node set to 1.
{{!-}}
! colspan="2" {{!}} Double
{{!}} Node set to '''value'''.
{{!}} Node set to '''value''' converted to number.
{{!}} Throws an error (vector is not a number).
{{!-}}
! colspan="2" {{!}} String
{{!}} Node set to '''value''' converted to string. {{!!}} Node set to '''value'''. {{!!}} Node not set.
{{!}}}
|param1 = rel_path
|param1text = Optional relative path as a string.
|param2 = value
|param2text = Value to set the node to. Must be a string, a valid number, or a vector consisting of 3 or 4 numbers. See table above for conversions and effects.
|example1 = var node = props.Node.new();
node.setValue("Hi");
props.dump(node); # node = "Hi"
|example2 = var node = props.Node.new();
node.addChild("a");
node.setValue("a", "Hi");
props.dump(node); # \a = "Hi"
|example3 = var node = props.Node.new();
node.setValue([0.4, 0.2, 1]);
debug.dump(node.getValue()); # prints "[0.4, 0.2, 1]"
print(node.getType()); # prints "VEC3D"
}}

==== setValues() ====
{{Nasal doc
|syntax = props.Node.setValues(val);
|text = {{hatnote|See also {{func link|getValues()|page=this}}.}}

Sets the nodes property tree from a Nasal hash. Scalars will become nodes in the tree and hashes will become named subnodes. Vectors will be converted into indexed nodes, with the values in the vector becoming their values (see examples below).
|param1 = val
|param1text = A hash that will become the property tree.
|example1 = var val = {
"a": 100 # "a" will become the subnode's name, and 100 its value
};
var node = props.Node.new();
node.setValues(val);
props.dump(node); # dump tree
|example2 = var val = {
"a": 1,
"b": "Hi",
"c": {
"d": [1, 2, 3]
}
};
var node = props.Node.new();
node.setValues(val);
props.dump(node); # dump tree
}}

==== unalias() ====
{{Nasal doc
|syntax = props.Node.unalias();
|text = Un-aliases the node and returns it to a blank state. Returns 1 on success and 0 on failure (e.g., when used on a tied property).
|example2 = var node1 = props.Node.new();
node1.setDoubleValue(2.35);
var node2 = props.Node.new();
node2.alias(node1);

props.dump(node2); # equals 2.35
node2.unalias();
props.dump(node2); # no value or type
}}

==== toggleBoolValue() (since FG 2020.1) ====
{{Nasal doc
|syntax = toggleBoolValue();
|text = Toggle a boolean property. You have to make sure the property is of type bool!
|example1 = var b = props.Node.new().initNode("/_test/bool", 1, "BOOL");
print("bool ", b.getValue());
b.toggleBoolValue();
print("after toggleBoolValue ", b.getValue());

}}

== Functions ==
=== compileCondition() ===
{{see also|Conditions}}

{{Nasal doc
|syntax = props.compileCondition(node);
|version = 3.2
|commit = {{fgdata commit|43f8ce08706629e69984b1cc34e5e979d03ef09a|t=commit}}
|text = Compiles a [[conditions|condition]] property branch and returns a <code>Condition</code> ghost object or <code>'''nil'''</code> on error. This ghost will contain a <code>test()</code> function that will return the result of the condition as either 1 (true) or 0 (false).
|param1 = node
|param1text = Either a props.Node containing the condition, or a string specifying a place in the [[Property Tree]] where there is a condition branch.
|example1 = var tree = {
"equals": {
"property": '/test',
"value": 12
}
};
var node = props.Node.new(tree);
setprop("/test", 12);

var cond = props.compileCondition(node);
print(cond.test()); # prints "1" (true)
setprop("/test", 15);
print(cond.test()); # prints "0" (false)
|example2 = var tree = {
"equals": {
"property": '/test',
"value": 12
}
};
props.globals.getNode("test2/condition", 1).setValues(tree); # place it in the Property Tree
setprop("/test", 12);

var cond = props.compileCondition(node);
print(cond.test()); # prints "1" (true)
setprop("/test", 15);
print(cond.test()); # prints "0" (false)
}}

=== condition() ===
{{Nasal doc
|syntax = props.condition(node);
|text = Evaluates a [[conditions|condition]] property branch and returns the result as a boolean.
|param1 = node
|param1text = Either a props.Node containing the condition, or a string specifying a place in the [[Property Tree]] where there is a condition branch.
|example1 = var tree = {
"equals": {
"property": '/test',
"value": 12
}
};
var node = props.Node.new(tree);
setprop("/test", 12);

print(props.condition(node)); # prints "1" (true)
setprop("/test", 15);
print(props.condition(node)); # prints "0" (false)
|example2 = var tree = {
"equals": {
"property": '/test',
"value": 12
}
};
props.globals.getNode("test2/condition", 1).setValues(tree); # place it in the Property Tree
setprop("/test", 12);

print(props.condition(node)); # prints "1" (true)
setprop("/test", 15);
print(props.condition(node)); # prints "0" (false)
}}

=== copy() ===
{{Nasal doc
|syntax = props.copy(src, dest[, attr]);
|text = Copies the property tree of the source into the destination node. Note that aliased properties will not be copied.
|param1 = src
|param1text = Source <code>props.Node object</code> to copy from.
|param2 = dest
|param2text = Destination <code>props.Node object</code> to copy to.
|param3 = attr
|param3text = If set to 1 (true), attributes will also be copied. Defaults to 0 (false).
|example1 = var tree = {
"a": 1.5,
"b": "Hi",
"c": {
"d": [1, 2, 3]
}
};
var src = props.Node.new(tree);
var dest = props.Node.new();
props.copy(src, dest);
props.dump(dest);
|example2 = var src = props.Node.new();
var a = src.addChild("a");
a.setAttribute("trace-write", 1);
a.setIntValue(12);
var dest = props.Node.new();
props.copy(src, dest, 1);
print(dest.getNode("a").getAttribute("trace-write")); # prints "1" (true)
}}

=== dump() ===
{{Nasal doc
|syntax = props.dump(node);
|text = Recursively dump the state of a node into the console, showing value and type of each node. Note that as of 10/2016, the value of vec*d type nodes cannot be dumped.
|param1 = node
|param1text = Node to dump.
|example1 = var node = var tree = {
"a": 12,
"b": "Hi",
"c": {
"d": [1, 2, 3]
}
};
var node = props.Node.new(tree);
props.dump(node); # dump into console
|example2 = # Dump the entire Property Tree
# Warning! This is an intensive operation!
props.dump(props.globals);
}}

=== getNode() ===
{{Nasal doc
|syntax = props.getNode();
|version = 3.2
|commit = {{fgdata commit|807062d0b6f858885547f27325e829c2bf42a12b|t=commit}}
|text = Shortcut for <syntaxhighlight lang="nasal" inline>props.globals.getNode()</syntaxhighlight>. See {{func link|getNode()||Node|page=this}} for full documentation.
|example1 = print("Current aircraft is: ", props.getNode("/sim/aircraft").getValue());
}}

=== nodeList() ===
{{Nasal doc
|syntax = props.nodeList(arg[, arg[, ...]]);
|text = Converts its arguments into a vector of node objects if possible and returns that vector.
|param1 = arg
|param1text = Object to operate on. Must be a node object, string, vector, hash, function, or <code>prop</code> ghost. Vectors and hashes must contain any of the other acceptable types, functions must return any of the other types, strings will be assumed to be paths to global properties, and ghosts will be converted into node objects. There may be any number of arguments.
|example1 = var node = props.Node.new();
var f = func(){
var n = props.Node.new();
return n._g;
}
var list = props.nodeList(node,
"/sim/aircraft",
["/sim/fg-root"],
{ "path": "/sim/fg-home" },
f
);
debug.dump(list); # dump list
|example2 = var root = "/sim/version/";
var info = [
root ~ "build-id",
root ~ "build-number",
root ~ "flightgear",
root ~ "hla-support",
root ~ "openscenegraph",
root ~ "revision",
root ~ "simgear"
];
info = props.nodeList(info); # turn into list of nodes
foreach(var n; info){
print(n.getValue()); # dump info
}
}}

=== runBinding() ===
{{Nasal doc
|syntax = props.runBinding(node[, module]);
|text = Runs a [[Bindings|binding]] element in a node object. Returns 1 (true) on success and 0 (false) on failure.
|param1 = node
|param1text = A {{tag|binding}} element as a node object.
|param2 = module
|param2text = Optional string specifying a module to run Nasal scripts in if the command is <code>nasal</code>. This argument will not override any {{tag|module}} element in the '''node'''
|example1 = var tree = {
"command": "dialog-show",
"dialog-name": "map" # open map
};
var binding = props.Node.new(tree);
props.runBinding(binding);
|example2 = var tree = {
"command": "nasal",
"script": 'print(pi)' # prints value of math.pi
};
var binding = props.Node.new(tree);
props.runBinding(binding, "math");
|example3 = var tree = {
"command": "nasal",
"script": 'print(pi)', # prints value of math.pi
"module": "math" # this is used
};
var binding = props.Node.new(tree);
props.runBinding(binding, "debug");
}}

=== setAll() ===
{{Nasal doc
|syntax = props.setAll(base, child, value);
|text = Sets indexed subnodes in the Property Tree with the same name to the same value.
|param1 = base
|param1text = Base path to the nodes.
|param2 = child
|param2text = Path to child nodes.
|param3 = value
|param3text = Value to set the subnodes to.
|example1 = # apply 50% throttle to all engines
props.setAll("/controls/engines/engine", "throttle", 0.5);
|example2 = var nodes = props.globals.addChildren("/test", 3);
foreach(var node; nodes){
node.addChild("a");
}
props.setAll("/test", "a", "Hi"); # set all children (test[*]/a) to "Hi"
}}

=== wrap() ===
{{Nasal doc
|syntax = props.wrap(node);
|text = Turns <code>prop</code> ghosts, either in a vector or single, into <code>props.Node</code> objects.
|param1 = node
|param1text = <code>prop</code> ghost or vector of such ghosts.
|example1 = var ghost = canvas._newCanvasGhost();
var node = props.wrap(ghost._node_ghost);
props.dump(node);
|example2 = var vector = [canvas._newCanvasGhost()._node_ghost, props.Node.new()._g];
var nodes = props.wrap(vector);
foreach(var node; nodes){
props.dump(node);
print("----");
}
}}

=== wrapNode() ===
{{Nasal doc
|syntax = props.wrapNode(node);
|text = Turns a <code>prop</code> ghost into a <code>props.Node</code> object.
|param1 = node
|param1text = <code>prop</code> ghost to convert.
|example1 = var ghost = canvas._newCanvasGhost();
var node = props.wrapNode(ghost._node_ghost);
props.dump(node);
}}

== Variable ==
=== globals ===
{{Nasal doc
|syntax = props.globals;
|text = Exposes the [[Property Tree]] as a <code>props.Node</code> object.

|example1 = print("Current aircraft: ", props.globals.getNode("/sim/aircraft").getValue());
|example2text = Alternative using {{func link|getprop()}}.
|example2 = print("Current aircraft: ", getprop("/sim/aircraft"));
}}

{{Nasal namespaces}}

Nasal library/props

2025-12-04T18:32:33Z

PlayeRom: /* initNode() */

{{Nasal Navigation|nocat=1}}
This page contains documentation for the '''<code>props</code> namespace''' in [[Nasal]]. This namespace provides APIs for working with property trees (including the main [[Property Tree]]) via {{API Link|simgear|class|SGPropertyNode}}. The <code>props</code> namespace is sourced from {{fgdata source|Nasal/props.nas}} and {{flightgear source|src/Scripting/nasal-props.cxx}}.

== Class ==
=== Node ===
{{Nasal doc
|mode = class
|text = The main class, used widely for manipulating property trees.
}}
==== new() ====
{{Nasal doc
|syntax = props.Node.new([values]);
|text = Constructor function. Returns a new <code>props.Node</code> instance.
|param1 = values
|param1text = An optional hash that will be the initial property structure.
|example1 = var node = props.Node.new();
props.dump(node);
|example2 = var tree = {
a: 1,
b: ["a", "b", "c"],
c: {
d: 1 * 4
}
};

var node = props.Node.new(tree);
props.dump(node);
}}

==== addChild() ====
{{Nasal doc
|syntax = props.Node.addChild(name[, min_idx[, append]]);
|version = 2.10
|commit = {{fgdata commit|a15d5829379864c7138edff621d6864c5f426d0b|t=commit}}
|text = Add a new, blank child to the node. Returns the newly-created node.
|param1 = name
|param1text = The name of the node as a string.
|param2 = min_idx
|param2text = This specifies the minimum index to add the new one to. This takes precedence over '''append'''. Defaults to 0.
|param3 = append
|param3text = If there is already one or more children with the same name and this argument is 1 (true), the new child will be added after the child with the highest index. If 0 (false), the new child will be added at the lowest available index with the limit of '''min_idx'''. Defaults to 1 (true).
|example1 = var node = props.Node.new();
node.addChild("a");
props.dump(node);
|example2 = var node = props.Node.new();
node.addChild("a", 1);
props.dump(node); # a[1]
|example3 = var node = props.Node.new();
node.addChild("a", 1);
props.dump(node); # a[1]
node.addChild("a", 0, 0);
props.dump(node); # a[1] and a[0]
|example4 = var node = props.Node.new();
node.addChild("a", 1);
props.dump(node); # a[1]
node.addChild("a", 0, 1);
props.dump(node); # a[1] and a[2]
}}

==== addChildren() ====
{{Nasal doc
|syntax = props.Node.addChildren(name, count[, min_idx[, append]]);
|version = 2.10
|commit = {{fgdata commit|7f1117a5374beabb045fb76fbb6dd8bfb0128100|t=commit}}
|text = Adds multiple children with the same name to this node. Returns <code>'''nil</code>.
|param1 = name
|param1text = The name of the nodes as a string.
|param2 = count
|param2text = Number of new children to add.
|param3 = min_idx
|param3text = Performs the same function as in <code>[[#addChild.28.29|Node.addChild()]]</code>.
|param4 = append
|param4text = Performs the same function as in <code>[[#addChild.28.29|Node.addChild()]]</code>.
|example1 = var node = props.Node.new();
node.addChildren("a", 2);
props.dump(node); # a[0] and a[1]
|example2 = var node = props.Node.new();
node.addChildren("a", 2, 1);
props.dump(node); # a[1] and a[2]
|example3 = var node = props.Node.new();
node.addChild("a", 2);
props.dump(node); # a[2]
node.addChildren("a", 2, 0, 0);
props.dump(node); # a[2], a[0], and a[1]
}}

==== adjustValue() (since FG 2020.1) ====
{{Nasal doc
|syntax = props.Node.adjustValue(delta);
|text = Adds delta (numeric) to current value respecting the node type.
|param1 = delta
|param1text = Numeric value (can be negative) to add to current node value.
}}

==== alias() ====
{{Nasal doc
|syntax = props.Node.alias(node, chainListener=0);
|text = Aliases this node to another one. Returns 1 on success and 0 on failure.
|param1 = node
|param1text = The node to alias to. Can be one of:
* A path to a property in the [[Property Tree]] as a string.
* A <code>prop</code> ghost.
* A <code>props.Node</code> object.
|example1 = var node = props.Node.new();
node.alias("/position/altitude-ft");
props.dump(node); # equals the current altitude
|example2 = var node1 = props.Node.new();
node1.setDoubleValue(2.34);
var node2 = props.Node.new();
node2.alias(node1);
props.dump(node2); # equals 2.34
|param2=chainListener|param2text=Specify if listeners should work on aliased properties or not. Current default is false forbackwards compatability.}}

==== clearValue() ====
{{Nasal doc
|syntax = props.Node.clearValue();
|text = Clears the value and type of the node.
|example1 = var node = props.Node.new();
node.setDoubleValue(2.34);
props.dump(node); # prints "{DOUBLE} = 2.35"
node.clearValue();
props.dump(node); # prints "{NONE} = nil"
}}

==== decrement() (since FG 2020.1) ====
{{Nasal doc
|syntax = props.Node.decrement(n = 1);
|text = Decrements integer property by n (default: n = 1)
|param1 = n
|param1text = Value to subtract, will be converted to int, defaults to 1
}}

==== equals() ====
{{Nasal doc
|syntax = props.Node.equals(node);
|version = 2.12
|commit = {{fgdata commit|d80722065f3c11e0511fa888b1f5f310dd0183e3|t=commit}}
|text = Checks whether the node refers to the same one as another. Returns 1 (true) if it is, and 0 (false) if otherwise.
|param1 = node
|param1text = Node to check against. May be either a <code>prop</code> ghost or a <code>props.Node</code> object.
|example1 = var n = props.Node.new();
var a = n;
print(a.equals(n)); # prints "1" (true)
}}

==== getAliasTarget() ====
{{Nasal doc
|syntax = props.Node.getAliasTarget();
|text = Returns the alias target of a node as another <code>props.Node</code> instance.
|example1 = setprop("/test", 2.35);
var node = props.Node.new();
node.alias("/test");
var tgt = node.getAliasTarget();
print(tgt.getPath()); # prints "/test"
}}

==== getAttribute() ====
{{Nasal doc
|syntax = props.Node.getAttribute([rel_path, ]name);
props.Node.getAttribute();
|text = Returns an attribute. If no arguments are given, the function will return an integer specifying the attributes set for the node (see {{simgear source|simgear/props/props.hxx|l=767}} for a list). A list of attributes are below
{{{!}} class="wikitable"
! String !! Return value
{{!-}}
{{!}} last {{!!}} The highest used attribute code (should be 128). See for {{simgear source|simgear/props/props.hxx|l=767}} the codes.
{{!-}}
{{!}} children {{!!}} Number of child nodes.
{{!-}}
{{!}} listeners {{!!}} Number of listeners connected to this node.
{{!-}}
{{!}} references {{!!}} Number of times the node has previously been referenced.
{{!-}}
{{!}} tied {{!!}} Whether the node is tied.
{{!-}}
{{!}} alias {{!!}} Whether the node is aliased.
{{!-}}
{{!}} readable {{!!}} Whether the node can be read.
{{!-}}
{{!}} writable {{!!}} Whether the node can be written to.
{{!-}}
{{!}} archive {{!!}} Whether the node will be saved when the "save" [[fgcommands|fgcommand]] is triggered.
{{!-}}
{{!}} trace-read {{!!}} Whether the reading of the node will be logged when <code>--log-level=info</code>.
{{!-}}
{{!}} trace-write {{!!}} Whether the writing to the node will be logged when <code>--log-level=info</code>.
{{!-}}
{{!}} userarchive {{!!}} Whether the node will be saved to the [[FlightGear configuration via XML#autosave.xml|autosave file]] (only works for actual properties).
{{!-}}
{{!}} preserve {{!!}} Whether the value of node will be preserved during resets (only works for actual properties).
{{!}}}
|param1 = rel_path
|param1text = Optional relative path as a string.
|param2 = name
|param2text = Attribute as a string. See the above table for a full list.
|example1 = var node = props.Node.new();
var child = node.addChild("a");
print(node.getAttribute("children")); # prints "1"
|example2text = Example using relative path
|example2 = var node = props.Node.new();
var child = node.addChild("a");
print(node.getAttribute("a", "readable")); # prints "1" (node can be read from)
|example3 = var node = props.Node.new();
var node2 = props.Node.new();
node2.alias(node);
print(node2.getAttribute("alias")); # prints "1" (true)
|example4 = print(props.globals.getNode("/sim/signals/fdm-initialized").getAttribute("listeners")); # prints the number of listeners
|example5 = print(props.globals.getNode("/sim/time/elapsed-sec").getAttribute("tied")); # prints "1" (true), meaning it is tied
|example6 = var node = props.Node.new();
print(node.getAttribute("writable")); # prints "1" (true), meaning the node can be written to
|example7text = Example using no arguments
|example7 = var node = props.Node.new();
print(node.getAttribute()); # prints "3" (true), meaning the node can be read from (1) and written to (2)
}}

==== getBoolValue() ====
{{Nasal doc
|syntax = props.Node.getBoolValue();
|text = Returns the value of a node converted to a boolean. If the node is a number type, 0 will return false, while 1 will return true. If the node is a string or unspecified type and the value is <code>"false"</code>, false will be returned. Otherwise, true will be returned. Remember that boolean values are represented in Nasal as 1 (true) and 0 (false).
|example1 = var node = props.Node.new();
node.setBoolValue(1);
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setBoolValue(0);
print(node.getBoolValue() ? "true" : "false"); # prints "false"
|example2 = var node = props.Node.new();
node.setDoubleValue(1.23);
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setDoubleValue(-1.23);
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setDoubleValue(0.0);
print(node.getBoolValue() ? "true" : "false"); # prints "false"
|example3 = var node = props.Node.new();
node.setIntValue(2);
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setIntValue(-2);
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setIntValue(0);
print(node.getBoolValue() ? "true" : "false"); # prints "false"
|example4 = var node = props.Node.new();
node.setValue("Hello, World!");
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setValue("false");
print(node.getBoolValue() ? "true" : "false"); # prints "false"
}}

==== getChild() ====
{{Nasal doc
|syntax = props.Node.getChild(rel_path[, idx[, create]]);
|text = Returns a child of a node as another <code>props.Node</code> instance.
|param1 = rel_path
|param1text = Relative path to the child node as a string.
|param2 = idx
|param2text = Optional index for the child node as an integer.
|param3 = create
|param3text = If set to 1 (true), a new child will be created if it does not exist. If set to 0 (false), the function will not create a new child and the function will return <code>'''nil'''</code> if no child exists. Defaults to 0.
|example1 = var node = props.Node.new();
node.addChild("a");
var c = node.getChild("a");
|example2 = var node = props.Node.new();
node.addChildren("a", 3);
node.getNode("a[1]").setDoubleValue(2.35);
var c = node.getChild("a", 1);
print(c.getValue()); # prints "2.35"
|example3 = var node = props.Node.new();
var c = node.getChild("a", 1, 1);
props.dump(node); # new child a[1] will have appeared
}}

==== getChildren() ====
{{Nasal doc
|syntax = props.Node.getChildren([name]);
|text = Returns a vector of child nodes, optionally those with a certain name, as <code>props.Node</code> instances.
|param1 = name
|param1text = Optional name of the child nodes as a string. If not given, all children will be returned.
|example1 = var node = props.Node.new();
node.addChildren("a", 3);
node.addChildren("b", 3);
debug.dump(node.getChildren()); # all child nodes in the vector
|example2 = var node = props.Node.new();
node.addChildren("a", 3);
node.addChildren("b", 3);
debug.dump(node.getChildren("b")); # only children with the name "b" in the vector
}}

==== getIndex() ====
{{Nasal doc
|syntax = props.Node.getIndex();
|text = Returns the index of a node as an integer.
|example1 = var node = props.Node.new();
node.addChildren("a", 3);
print(node.getChild("a", 1).getIndex()); # prints "1"
|example2 = var node = props.Node.new();
node.addChild("b");
print(node.getChild("b").getIndex()); # prints "0"
}}

==== getName() ====
{{Nasal doc
|syntax = props.Node.getName();
|text = Returns the name of the node as a string.
|example1 = var node = props.Node.new();
var c = node.addChild("a");
debug.dump(c.getName()); # prints "a"
|example2 = var node = props.Node.new();
node.addChildren("a", 3);
debug.dump(node.getChild("a", 2).getName()); # prints "a"
}}

==== getNode() ====
{{Nasal doc
|syntax = props.Node.getNode(rel_path[, create]);
|text = Returns a subnode as another <code>props.Node</code> instance.
|param1 = rel_path
|param1text = Relative path to the subnode as a string.
|param2 = create
|param2text = If true (1), the node will be created if it does not exist. If false (0) and the node does not exist, the function will return <code>'''nil'''</code>. Default to false (0).
|example1 = var tree = {
"a": 1,
"b": "Hi",
"c": {
"d": "Hello, World!"
}
};
var node = props.Node.new(tree);
print(node.getNode("c/d").getValue()); # prints "Hello, World!"
|example2 = var tree = {
"a": 1,
"b": "Hi",
"c": {}
};
var node = props.Node.new(tree);
node.getNode("c/d", true).setDoubleValue(2.35);
props.dump(node); # c/d now exists
|example3 = var ac = props.globals.getNode("sim/aircraft");
print("Current aircraft is: ", ac.getValue());
}}

==== getParent() ====
{{Nasal doc
|syntax = props.Node.getParent();
|text = Returns the parent of a node, or <code>'''nil'''</code> if there is no parent.
|example1 = var tree = {
"a": 1,
"b": "Hi",
"c": {
"d": "Hello, World!"
}
};
var node = props.Node.new(tree);
props.dump(node.getNode("c/d").getParent()); # dumps "c"
|example2 = var node = props.Node.new();
debug.dump(node.getParent()); # prints nil
}}

==== getPath() ====
{{Nasal doc
|syntax = props.Node.getPath();
|text = Returns the path of the node as a string.
|example1 = var tree = {
"a": 1,
"b": "Hi",
"c": {
"d": "Hello, World!"
}
};
var node = props.Node.new(tree);
print(node.getNode("c/d").getPath()); # prints "/c/d"
}}

==== getType() ====
{{Nasal doc
|syntax = props.Node.getType();
|text = Returns node's type as a string. It should be one of "NONE", "ALIAS", "BOOL", "INT", "LONG" (long integer), "FLOAT", "DOUBLE", "STRING", "VEC3D", "VEC4D", "UNSPECIFIED".
|example1 = var node = props.Node.new();
print(node.getType()); # prints "NONE"
|example2 = var node = props.Node.new();
node.setIntValue(12);
print(node.getType()); # prints "INT"
|example3 = var node = props.Node.new();
node.setValue([0.4, 0.2, 1]);
debug.dump(node.getValue()); # prints "[0.4, 0.2, 1]"
print(node.getType()); # prints "VEC3D"
}}

==== getValue() ====
{{Nasal doc
|syntax = props.Node.getValue([rel_path]);
|text = {{hatnote|See also {{func link|getBoolValue()|page=this}}.}}

Returns the value of the node.
|param1 = rel_path
|param1text = Optional relative path to a subnode as a string, which may contain '/' characters. If the subnode does not exist, we return nil.
|example1 = var node = props.Node.new();
node.setDoubleValue(2.35);
print(node.getValue()); # prints "2.35"
|example2 = var node = props.Node.new();
node.setValue("Hi");
print(node.getValue()); # prints "Hi"
|example3 = var node = props.Node.new();
node.addChild("a").setValue("Hi");
print(node.getValue("a")); # prints "Hi"
|example4 = var node = props.Node.new();
node.setValue([0, 0.5, 1]);
debug.dump(node.getValue()); # prints "[0, 0.5, 1]"
}}

==== getValues() ====
{{Nasal doc
|syntax = props.Node.getValues();
|text = Returns the node tree as a hash, with all the various subnodes, etc. If the node has no children, the result is equivalent to {{func link|getValue()|page=this}}. Subnodes that are indexed will be combined into one key and their values placed in a vector (see example 2).
|example1 = var tree = {
"string": "Hi",
"number": 1.2,
"subnode": {
"idx-node": [1, 2, 3]
}
};
var node = props.Node.new(tree);
node.addChild("bool").setBoolValue(1);
props.dump(node); # dump to node tree
debug.dump(node.getValues()); # dump the node converted to hash
|example2 = var tree = {
"a": [1, 2, 3]
};
var node = props.Node.new(tree);
props.dump(node); # a[0] = 1, a[1] = 2, a[2] = 3
debug.dump(node.getValues()); # a: [1, 2, 3]
}}

==== increment() (since FG 2020.1) ====
{{Nasal doc
|syntax = props.Node.increment(n = 1);
|text = Increments integer property by n (default: n = 1)
|param1 = n
|param1text = Value to add, will be converted to int, defaults to 1
}}

==== initNode() ====
{{Nasal doc
|syntax = props.Node.initNode([path[, value[, type[, force]]]]);
|text = Initializes a node if it doesn't exist and returns that node as a <code>props.Node</code> object.
|param1 = path
|param1text = Optional path to a subnode as a string. If not given, the node itself will be initialized.
|param2 = value
|param2text = Optional default value to initialize the node with.
|param3 = type
|param3text = Optional string that will set the type of the node. Must be one of <code>"DOUBLE"</code>, <code>"INT"</code>, <code>"BOOL"</code>, or <code>"STRING"</code>.
|param4 = force
|param4text = If set to true (1), the node's type will be forced to change.
|example1 = var node = props.Node.new();
var a = node.initNode("a");
props.dump(a);
|example2 = var node = props.Node.new();
var a = node.initNode("a", "Hi");
props.dump(a);
|example3 = var node = props.Node.new();
var a = node.initNode("a", 1.25, "INT");
props.dump(a); # a = 1
|example4 = var node = props.Node.new();
node.addChild("a").setBoolValue(0);
props.dump(node.getChild("a")); # a = 0 (type: bool)
var a = node.initNode("a", 1.25, "INT", true);
props.dump(a); # a = 0 (type: int)
}}

==== isInt() (since FG 2020.1) ====
{{Nasal doc
|syntax = props.Node.isInt();
|text = Returns true (1) if node '''type''' is "INT" or "LONG" (long integer) otherwise false (0).
}}

==== isNumeric() (since FG 2020.1) ====
{{Nasal doc
|syntax = props.Node.isNumeric();
|text = Returns true (1) if node '''type''' is "INT", "LONG", "FLOAT" or "DOUBLE" otherwise false (0).
}}

==== remove() ====
{{Nasal doc
|syntax = props.Node.remove();
|text = Removes the node and returns the removed node.
|example1 = var node = props.Node.new();
node.addChild("a");
props.dump(node);
node.getChild("a").remove();
props.dump(node); # child "a" does not exist anymore
}}

==== removeAllChildren() ====
{{Caution|Be careful when using this API in conjunction with the Canvas system and element specific properties, for details please see [[Howto:Canvas Path Benchmarking]]}}
{{Nasal doc
|syntax = props.Node.removeAllChildren();
|version = 3.2
|commit = {{fgdata commit|4766ed21a68230c0c15265e5604a74f4d99e0f5d|t=commit}}
|text = Removes all child nodes and returns the node.
|example1 = var tree = {
"a": 1,
"b": 2,
"c": 3
};
var node = props.Node.new(tree);
props.dump(node);
node.removeAllChildren();
props.dump(node); # all children have been removed
}}

==== removeChild() ====
{{Nasal doc
|syntax = props.Node.removeChild(rel_path, idx);
|text = Removes a given child node child nodes and returns the node.
|param1 = rel_path
|param1text = Relative path to a subnode as a string.
|param2 = idx
|param2text = Index of the subnode to remove as an integer.
|example1 = var node = props.Node.new();
node.addChild("a");
props.dump(node);
node.removeChild("a", 0);
props.dump(node); # child "a" has been removed
|example2 = var node = props.Node.new();
node.addChildren("a", 2);
props.dump(node);
node.removeChild("a", 0);
props.dump(node); # just a[1] remains
}}

==== removeChildren() ====
{{Nasal doc
|syntax = props.Node.removeChildren([name]);
|text = Removes all children with a specified name. If no arguments are given, all children will be removed (see also {{func link|removeAllChildren()|page=this}}).
|param1 = name
|param1text = Optional name of children to remove as a string.
|example1 = var node = props.Node.new();
node.addChildren("a", 2);
node.addChildren("b", 2);
props.dump(node);
node.removeChildren("a");
props.dump(node); # just children named "b" remain
|example2 = var node = props.Node.new();
node.addChildren("a", 2);
node.addChildren("b", 2);
props.dump(node);
node.removeChildren();
props.dump(node); # all children removed
}}

==== setAttribute() ====
{{Nasal doc
|syntax = props.Node.setAttribute([rel_path, ]attr, value);
props.Node.setAttribute(attrs);
|text = Sets an attribute or multiple attributes. A list of attributes and their codes are below. For a brand new node, the default attributes are ''readable'' and ''writable''. Returns an integer specifying the old attributes.
{{{!}} class="wikitable"
! String !! Description
{{!-}}
{{!}} readable {{!!}} Whether the node can be read.
{{!-}}
{{!}} writable {{!!}} Whether the node can be written to.
{{!-}}
{{!}} archive {{!!}} Whether the node will be saved when the "save" [[fgcommands|fgcommand]] is triggered.
{{!-}}
{{!}} trace-read {{!!}} Whether the reading of the node will be logged when <code>--log-level=info</code>.
{{!-}}
{{!}} trace-write {{!!}} Whether the writing to the node will be logged when <code>--log-level=info</code>.
{{!-}}
{{!}} userarchive {{!!}} Whether the node will be saved to the [[FlightGear configuration via XML#autosave.xml|autosave file]] (only works for actual properties).
{{!-}}
{{!}} preserve {{!!}} Whether the value of node will be preserved during resets (only works for actual properties).
{{!}}}
|param1 = rel_path
|param1text = Optional relative path as a string.
|param2 = attr
|param2text = Name of attribute to set as a string. See above.
|param3 = value
|param3text = Boolean value to set the property to.
|param4 = attrs
|param4text = When the function is used in its second form, this argument is used. This argument should be an integer specifying which arguments are set to true. See {{simgear source|simgear/props/props.hxx|l=767}} for the full list of codes. Simply add codes of the desired attributes together.
|example1 = var node = props.Node.new();
node.setAttribute("trace-write", 1);
node.setIntValue(12); # will be traced
|example2 = var node = props.Node.new();
node.setAttribute("readable", 0);
var val = node.getValue();
debug.dump(val); # prints "nil"
|example3 = var node = props.Node.new();
node.addChild("a");
node.setAttribute("a", "trace-write", 1);
node.getChild("a").setIntValue(12); # will be traced
|example4 = var node = props.Node.new();
node.setAttribute(35); # read + write + trace-write
node.setIntValue(12); # will be traced
}}

==== setBoolValue() ====
{{Nasal doc
|syntax = props.Node.setBoolValue([rel_path, ]value);
|text = {{note|For setting the values of [[Property Tree]] nodes, it is recommended to use {{func link|setprop()}} if possible, due to performance differences.}}

Sets a node to a boolean value. If the node has no type, it will be set to a bool type. If the node is already a number type, it will be set to either 1 or 0. If it is a string, it will be set to either "true" or "false". Returns 1 (true) if the operation was successful.
|param1 = rel_path
|param1text = Optional relative path as a string.
|param2 = value
|param2text = Value to set the node to, will be interpreted into a boolean. If it is <code>'''nil'''</code>, it will be false. If it is a string, it will be false. If it is a number, 0 will be false, while other numbers will be true. All other cases will be interpreted as 0.
|example1 = var node = props.Node.new();
node.setBoolValue(nil);
props.dump(node); # node = 0 (false)
|example2 = var node = props.Node.new();
node.setBoolValue("Hi");
props.dump(node); # node = 1 (true)
|example3 = var node = props.Node.new();
node.setBoolValue(0);
props.dump(node); # node = 0 (false)
node.setBoolValue(1.25);
props.dump(node); # node = 1 (true)
|example4 = var node = props.Node.new();
node.setValue("String");
props.dump(node); # node = "String" (type: string)
node.setBoolValue(1);
props.dump(node); # node = "true"
|example5 = var node = props.Node.new();
node.setDoubleValue(12.32);
props.dump(node); # node = 12.32 (type: double)
node.setBoolValue(1);
props.dump(node); # node = 1
|example6 = var node = props.Node.new();
node.addChild("a");
node.setBoolValue("a", 1);
props.dump(node); # /a = 1
}}

==== setDoubleValue() ====
{{Nasal doc
|syntax = props.Node.setDoubleValue([rel_path, ]value);
|text = {{note|For setting the values of [[Property Tree]] nodes, it is recommended to use {{func link|setprop()}} if possible, due to performance differences.}}

Sets a node to a double value. If the node has no type, it will be set to a double type. If the node is a bool, values different from zero will be interpreted as true. If the node is a string, the value will be converted to a string. If the node is an integer type, it will be truncated to the closest integer to zero. Returns 1 (true) if the operation was successful.
|param1 = rel_path
|param1text = Optional relative path as a string.
|param2 = value
|param2text = Value to set the node to, will be interpreted into a double number. It must be a valid number or a string that can be converted to a number.
|example1 = var node = props.Node.new();
node.setDoubleValue(1.1);
props.dump(node); # node = 1.1 (type: double)
|example2 = var node = props.Node.new();
node.setDoubleValue("1.1");
props.dump(node); # node = 1.1 (type: double)
|example3 = var node = props.Node.new();
node.setBoolValue(1);
node.setDoubleValue("1.1");
props.dump(node); # node = 1 (type: bool)
node.setDoubleValue(0.0);
props.dump(node); # node = 0 (type: bool)
|example4 = var node = props.Node.new();
node.setIntValue(1);
node.setDoubleValue(1.1);
props.dump(node); # node = 1 (type: int)
node.setDoubleValue("-1.1");
props.dump(node); # node = -1 (type: int)
|example5 = var node = props.Node.new();
node.addChild("a");
node.setDoubleValue("a", 12.2);
props.dump(node); # /a = 12.2
}}

==== setIntValue() ====
{{Nasal doc
|syntax = props.Node.setIntValue([rel_path, ]value);
|text = {{note|For setting the values of [[Property Tree]] nodes, it is recommended to use {{func link|setprop()}} if possible, due to performance differences.}}

Sets a node to an integer value. If the node has no type, it will be set to a integer type. If the node is a bool, values different from zero will be interpreted as true. If the node is a string, the value will be converted to a string. Returns 1 (true) if the operation was successful.
|param1 = rel_path
|param1text = Optional relative path as a string.
|param2 = value
|param2text = Value to set the node to, will be interpreted into a integer. It must be a valid number or a string that can be converted to a number. If the number is a double, it will be truncated to the closest integer to zero.
|example1 = var node = props.Node.new();
node.setIntValue(12);
props.dump(node); # node = 12
node.setIntValue("6");
props.dump(node); # node = 6
|example2 = var node = props.Node.new();
node.setIntValue(12.2);
props.dump(node); # node = 12
node.setIntValue(-12.2);
props.dump(node); # node = 12
|example3 = var node = props.Node.new();
node.setBoolValue(1);
node.setIntValue(12.5);
props.dump(node); # node = 1 (type: bool)
node.setIntValue(0);
props.dump(node); # node = 0 (type: bool)
|example4 = var node = props.Node.new();
node.setValue("Hi");
node.setIntValue(12);
props.dump(node); # node = "12" (type: string)
|example5 = var node = props.Node.new();
node.addChild("a");
node.setIntValue("a", 12);
props.dump(node); # /a = 12
}}

==== setValue() ====
{{Nasal doc
|syntax = props.Node.setValue([rel_path, ]value);
|text = {{hatnote|See also {{func link|setBoolValue()|page=this}}, {{func link|setDoubleValue()|page=this}}, and {{func link|setIntValue()|page=this}}.}}

{{note|For setting the values of [[Property Tree]] nodes, it is recommended to use {{func link|setprop()}} if possible, due to performance differences.}}

Sets a node to a given value. See table below for conversions and effects. Note that vec3d and vec4d types are not fully integrated into SGPropertyNode. Returns 1 (true) if the operation was successful.

{{{!}} class="wikitable"
{{!}} colspan="2" style="text-align:right" {{!}} '''value''' type →
! rowspan="2" {{!}} Number
! rowspan="2" {{!}} String
! rowspan="2" {{!}} Vector
{{!-}}
{{!}} style="text-align:left" {{!}} Current node<br>type ↓
{{!}} style="text-align:right" {{!}} Result ↘
{{!-}}
! colspan="2" {{!}} None/unspecified
{{!}}
* Type set to <code>double</code>
* Node set to '''value'''.
{{!}}
* Type set to <code>string</code>
* Node set to '''value'''.
{{!}}
* Type set to <code>vec*d</code>
* Node set to '''value'''.
{{!-}}
! colspan="2" {{!}} Bool
{{!}}
* If '''value''' != 0, node set to true.
* If '''value''' == 0, node set to false.
{{!}}
* If '''value''' == "true", node set to true.
* If '''value''' can be converted to an integer,<br>and != 0, node set to true.
{{!}} Node set to true.
{{!-}}
! colspan="2" {{!}} Integer
{{!}} Node set to truncated '''value'''
{{!}} Node set to '''value ''' converted and truncated to an integer.
{{!}} Node set to 1.
{{!-}}
! colspan="2" {{!}} Double
{{!}} Node set to '''value'''.
{{!}} Node set to '''value''' converted to number.
{{!}} Throws an error (vector is not a number).
{{!-}}
! colspan="2" {{!}} String
{{!}} Node set to '''value''' converted to string. {{!!}} Node set to '''value'''. {{!!}} Node not set.
{{!}}}
|param1 = rel_path
|param1text = Optional relative path as a string.
|param2 = value
|param2text = Value to set the node to. Must be a string, a valid number, or a vector consisting of 3 or 4 numbers. See table above for conversions and effects.
|example1 = var node = props.Node.new();
node.setValue("Hi");
props.dump(node); # node = "Hi"
|example2 = var node = props.Node.new();
node.addChild("a");
node.setValue("a", "Hi");
props.dump(node); # \a = "Hi"
|example3 = var node = props.Node.new();
node.setValue([0.4, 0.2, 1]);
debug.dump(node.getValue()); # prints "[0.4, 0.2, 1]"
print(node.getType()); # prints "VEC3D"
}}

==== setValues() ====
{{Nasal doc
|syntax = props.Node.setValues(val);
|text = {{hatnote|See also {{func link|getValues()|page=this}}.}}

Sets the nodes property tree from a Nasal hash. Scalars will become nodes in the tree and hashes will become named subnodes. Vectors will be converted into indexed nodes, with the values in the vector becoming their values (see examples below).
|param1 = val
|param1text = A hash that will become the property tree.
|example1 = var val = {
"a": 100 # "a" will become the subnode's name, and 100 its value
};
var node = props.Node.new();
node.setValues(val);
props.dump(node); # dump tree
|example2 = var val = {
"a": 1,
"b": "Hi",
"c": {
"d": [1, 2, 3]
}
};
var node = props.Node.new();
node.setValues(val);
props.dump(node); # dump tree
}}

==== unalias() ====
{{Nasal doc
|syntax = props.Node.unalias();
|text = Un-aliases the node and returns it to a blank state. Returns 1 on success and 0 on failure (e.g., when used on a tied property).
|example2 = var node1 = props.Node.new();
node1.setDoubleValue(2.35);
var node2 = props.Node.new();
node2.alias(node1);

props.dump(node2); # equals 2.35
node2.unalias();
props.dump(node2); # no value or type
}}

==== toggleBoolValue() (since FG 2020.1) ====
{{Nasal doc
|syntax = toggleBoolValue();
|text = Toggle a boolean property. You have to make sure the property is of type bool!
|example1 = var b = props.Node.new().initNode("/_test/bool", 1, "BOOL");
print("bool ", b.getValue());
b.toggleBoolValue();
print("after toggleBoolValue ", b.getValue());

}}

== Functions ==
=== compileCondition() ===
{{see also|Conditions}}

{{Nasal doc
|syntax = props.compileCondition(node);
|version = 3.2
|commit = {{fgdata commit|43f8ce08706629e69984b1cc34e5e979d03ef09a|t=commit}}
|text = Compiles a [[conditions|condition]] property branch and returns a <code>Condition</code> ghost object or <code>'''nil'''</code> on error. This ghost will contain a <code>test()</code> function that will return the result of the condition as either 1 (true) or 0 (false).
|param1 = node
|param1text = Either a props.Node containing the condition, or a string specifying a place in the [[Property Tree]] where there is a condition branch.
|example1 = var tree = {
"equals": {
"property": '/test',
"value": 12
}
};
var node = props.Node.new(tree);
setprop("/test", 12);

var cond = props.compileCondition(node);
print(cond.test()); # prints "1" (true)
setprop("/test", 15);
print(cond.test()); # prints "0" (false)
|example2 = var tree = {
"equals": {
"property": '/test',
"value": 12
}
};
props.globals.getNode("test2/condition", 1).setValues(tree); # place it in the Property Tree
setprop("/test", 12);

var cond = props.compileCondition(node);
print(cond.test()); # prints "1" (true)
setprop("/test", 15);
print(cond.test()); # prints "0" (false)
}}

=== condition() ===
{{Nasal doc
|syntax = props.condition(node);
|text = Evaluates a [[conditions|condition]] property branch and returns the result as a boolean.
|param1 = node
|param1text = Either a props.Node containing the condition, or a string specifying a place in the [[Property Tree]] where there is a condition branch.
|example1 = var tree = {
"equals": {
"property": '/test',
"value": 12
}
};
var node = props.Node.new(tree);
setprop("/test", 12);

print(props.condition(node)); # prints "1" (true)
setprop("/test", 15);
print(props.condition(node)); # prints "0" (false)
|example2 = var tree = {
"equals": {
"property": '/test',
"value": 12
}
};
props.globals.getNode("test2/condition", 1).setValues(tree); # place it in the Property Tree
setprop("/test", 12);

print(props.condition(node)); # prints "1" (true)
setprop("/test", 15);
print(props.condition(node)); # prints "0" (false)
}}

=== copy() ===
{{Nasal doc
|syntax = props.copy(src, dest[, attr]);
|text = Copies the property tree of the source into the destination node. Note that aliased properties will not be copied.
|param1 = src
|param1text = Source <code>props.Node object</code> to copy from.
|param2 = dest
|param2text = Destination <code>props.Node object</code> to copy to.
|param3 = attr
|param3text = If set to 1 (true), attributes will also be copied. Defaults to 0 (false).
|example1 = var tree = {
"a": 1.5,
"b": "Hi",
"c": {
"d": [1, 2, 3]
}
};
var src = props.Node.new(tree);
var dest = props.Node.new();
props.copy(src, dest);
props.dump(dest);
|example2 = var src = props.Node.new();
var a = src.addChild("a");
a.setAttribute("trace-write", 1);
a.setIntValue(12);
var dest = props.Node.new();
props.copy(src, dest, 1);
print(dest.getNode("a").getAttribute("trace-write")); # prints "1" (true)
}}

=== dump() ===
{{Nasal doc
|syntax = props.dump(node);
|text = Recursively dump the state of a node into the console, showing value and type of each node. Note that as of 10/2016, the value of vec*d type nodes cannot be dumped.
|param1 = node
|param1text = Node to dump.
|example1 = var node = var tree = {
"a": 12,
"b": "Hi",
"c": {
"d": [1, 2, 3]
}
};
var node = props.Node.new(tree);
props.dump(node); # dump into console
|example2 = # Dump the entire Property Tree
# Warning! This is an intensive operation!
props.dump(props.globals);
}}

=== getNode() ===
{{Nasal doc
|syntax = props.getNode();
|version = 3.2
|commit = {{fgdata commit|807062d0b6f858885547f27325e829c2bf42a12b|t=commit}}
|text = Shortcut for <syntaxhighlight lang="nasal" inline>props.globals.getNode()</syntaxhighlight>. See {{func link|getNode()||Node|page=this}} for full documentation.
|example1 = print("Current aircraft is: ", props.getNode("/sim/aircraft").getValue());
}}

=== nodeList() ===
{{Nasal doc
|syntax = props.nodeList(arg[, arg[, ...]]);
|text = Converts its arguments into a vector of node objects if possible and returns that vector.
|param1 = arg
|param1text = Object to operate on. Must be a node object, string, vector, hash, function, or <code>prop</code> ghost. Vectors and hashes must contain any of the other acceptable types, functions must return any of the other types, strings will be assumed to be paths to global properties, and ghosts will be converted into node objects. There may be any number of arguments.
|example1 = var node = props.Node.new();
var f = func(){
var n = props.Node.new();
return n._g;
}
var list = props.nodeList(node,
"/sim/aircraft",
["/sim/fg-root"],
{ "path": "/sim/fg-home" },
f
);
debug.dump(list); # dump list
|example2 = var root = "/sim/version/";
var info = [
root ~ "build-id",
root ~ "build-number",
root ~ "flightgear",
root ~ "hla-support",
root ~ "openscenegraph",
root ~ "revision",
root ~ "simgear"
];
info = props.nodeList(info); # turn into list of nodes
foreach(var n; info){
print(n.getValue()); # dump info
}
}}

=== runBinding() ===
{{Nasal doc
|syntax = props.runBinding(node[, module]);
|text = Runs a [[Bindings|binding]] element in a node object. Returns 1 (true) on success and 0 (false) on failure.
|param1 = node
|param1text = A {{tag|binding}} element as a node object.
|param2 = module
|param2text = Optional string specifying a module to run Nasal scripts in if the command is <code>nasal</code>. This argument will not override any {{tag|module}} element in the '''node'''
|example1 = var tree = {
"command": "dialog-show",
"dialog-name": "map" # open map
};
var binding = props.Node.new(tree);
props.runBinding(binding);
|example2 = var tree = {
"command": "nasal",
"script": 'print(pi)' # prints value of math.pi
};
var binding = props.Node.new(tree);
props.runBinding(binding, "math");
|example3 = var tree = {
"command": "nasal",
"script": 'print(pi)', # prints value of math.pi
"module": "math" # this is used
};
var binding = props.Node.new(tree);
props.runBinding(binding, "debug");
}}

=== setAll() ===
{{Nasal doc
|syntax = props.setAll(base, child, value);
|text = Sets indexed subnodes in the Property Tree with the same name to the same value.
|param1 = base
|param1text = Base path to the nodes.
|param2 = child
|param2text = Path to child nodes.
|param3 = value
|param3text = Value to set the subnodes to.
|example1 = # apply 50% throttle to all engines
props.setAll("/controls/engines/engine", "throttle", 0.5);
|example2 = var nodes = props.globals.addChildren("/test", 3);
foreach(var node; nodes){
node.addChild("a");
}
props.setAll("/test", "a", "Hi"); # set all children (test[*]/a) to "Hi"
}}

=== wrap() ===
{{Nasal doc
|syntax = props.wrap(node);
|text = Turns <code>prop</code> ghosts, either in a vector or single, into <code>props.Node</code> objects.
|param1 = node
|param1text = <code>prop</code> ghost or vector of such ghosts.
|example1 = var ghost = canvas._newCanvasGhost();
var node = props.wrap(ghost._node_ghost);
props.dump(node);
|example2 = var vector = [canvas._newCanvasGhost()._node_ghost, props.Node.new()._g];
var nodes = props.wrap(vector);
foreach(var node; nodes){
props.dump(node);
print("----");
}
}}

=== wrapNode() ===
{{Nasal doc
|syntax = props.wrapNode(node);
|text = Turns a <code>prop</code> ghost into a <code>props.Node</code> object.
|param1 = node
|param1text = <code>prop</code> ghost to convert.
|example1 = var ghost = canvas._newCanvasGhost();
var node = props.wrapNode(ghost._node_ghost);
props.dump(node);
}}

== Variable ==
=== globals ===
{{Nasal doc
|syntax = props.globals;
|text = Exposes the [[Property Tree]] as a <code>props.Node</code> object.

|example1 = print("Current aircraft: ", props.globals.getNode("/sim/aircraft").getValue());
|example2text = Alternative using {{func link|getprop()}}.
|example2 = print("Current aircraft: ", getprop("/sim/aircraft"));
}}

{{Nasal namespaces}}

Nasal library/props

2025-12-04T18:31:17Z

PlayeRom: /* getNode() */

{{Nasal Navigation|nocat=1}}
This page contains documentation for the '''<code>props</code> namespace''' in [[Nasal]]. This namespace provides APIs for working with property trees (including the main [[Property Tree]]) via {{API Link|simgear|class|SGPropertyNode}}. The <code>props</code> namespace is sourced from {{fgdata source|Nasal/props.nas}} and {{flightgear source|src/Scripting/nasal-props.cxx}}.

== Class ==
=== Node ===
{{Nasal doc
|mode = class
|text = The main class, used widely for manipulating property trees.
}}
==== new() ====
{{Nasal doc
|syntax = props.Node.new([values]);
|text = Constructor function. Returns a new <code>props.Node</code> instance.
|param1 = values
|param1text = An optional hash that will be the initial property structure.
|example1 = var node = props.Node.new();
props.dump(node);
|example2 = var tree = {
a: 1,
b: ["a", "b", "c"],
c: {
d: 1 * 4
}
};

var node = props.Node.new(tree);
props.dump(node);
}}

==== addChild() ====
{{Nasal doc
|syntax = props.Node.addChild(name[, min_idx[, append]]);
|version = 2.10
|commit = {{fgdata commit|a15d5829379864c7138edff621d6864c5f426d0b|t=commit}}
|text = Add a new, blank child to the node. Returns the newly-created node.
|param1 = name
|param1text = The name of the node as a string.
|param2 = min_idx
|param2text = This specifies the minimum index to add the new one to. This takes precedence over '''append'''. Defaults to 0.
|param3 = append
|param3text = If there is already one or more children with the same name and this argument is 1 (true), the new child will be added after the child with the highest index. If 0 (false), the new child will be added at the lowest available index with the limit of '''min_idx'''. Defaults to 1 (true).
|example1 = var node = props.Node.new();
node.addChild("a");
props.dump(node);
|example2 = var node = props.Node.new();
node.addChild("a", 1);
props.dump(node); # a[1]
|example3 = var node = props.Node.new();
node.addChild("a", 1);
props.dump(node); # a[1]
node.addChild("a", 0, 0);
props.dump(node); # a[1] and a[0]
|example4 = var node = props.Node.new();
node.addChild("a", 1);
props.dump(node); # a[1]
node.addChild("a", 0, 1);
props.dump(node); # a[1] and a[2]
}}

==== addChildren() ====
{{Nasal doc
|syntax = props.Node.addChildren(name, count[, min_idx[, append]]);
|version = 2.10
|commit = {{fgdata commit|7f1117a5374beabb045fb76fbb6dd8bfb0128100|t=commit}}
|text = Adds multiple children with the same name to this node. Returns <code>'''nil</code>.
|param1 = name
|param1text = The name of the nodes as a string.
|param2 = count
|param2text = Number of new children to add.
|param3 = min_idx
|param3text = Performs the same function as in <code>[[#addChild.28.29|Node.addChild()]]</code>.
|param4 = append
|param4text = Performs the same function as in <code>[[#addChild.28.29|Node.addChild()]]</code>.
|example1 = var node = props.Node.new();
node.addChildren("a", 2);
props.dump(node); # a[0] and a[1]
|example2 = var node = props.Node.new();
node.addChildren("a", 2, 1);
props.dump(node); # a[1] and a[2]
|example3 = var node = props.Node.new();
node.addChild("a", 2);
props.dump(node); # a[2]
node.addChildren("a", 2, 0, 0);
props.dump(node); # a[2], a[0], and a[1]
}}

==== adjustValue() (since FG 2020.1) ====
{{Nasal doc
|syntax = props.Node.adjustValue(delta);
|text = Adds delta (numeric) to current value respecting the node type.
|param1 = delta
|param1text = Numeric value (can be negative) to add to current node value.
}}

==== alias() ====
{{Nasal doc
|syntax = props.Node.alias(node, chainListener=0);
|text = Aliases this node to another one. Returns 1 on success and 0 on failure.
|param1 = node
|param1text = The node to alias to. Can be one of:
* A path to a property in the [[Property Tree]] as a string.
* A <code>prop</code> ghost.
* A <code>props.Node</code> object.
|example1 = var node = props.Node.new();
node.alias("/position/altitude-ft");
props.dump(node); # equals the current altitude
|example2 = var node1 = props.Node.new();
node1.setDoubleValue(2.34);
var node2 = props.Node.new();
node2.alias(node1);
props.dump(node2); # equals 2.34
|param2=chainListener|param2text=Specify if listeners should work on aliased properties or not. Current default is false forbackwards compatability.}}

==== clearValue() ====
{{Nasal doc
|syntax = props.Node.clearValue();
|text = Clears the value and type of the node.
|example1 = var node = props.Node.new();
node.setDoubleValue(2.34);
props.dump(node); # prints "{DOUBLE} = 2.35"
node.clearValue();
props.dump(node); # prints "{NONE} = nil"
}}

==== decrement() (since FG 2020.1) ====
{{Nasal doc
|syntax = props.Node.decrement(n = 1);
|text = Decrements integer property by n (default: n = 1)
|param1 = n
|param1text = Value to subtract, will be converted to int, defaults to 1
}}

==== equals() ====
{{Nasal doc
|syntax = props.Node.equals(node);
|version = 2.12
|commit = {{fgdata commit|d80722065f3c11e0511fa888b1f5f310dd0183e3|t=commit}}
|text = Checks whether the node refers to the same one as another. Returns 1 (true) if it is, and 0 (false) if otherwise.
|param1 = node
|param1text = Node to check against. May be either a <code>prop</code> ghost or a <code>props.Node</code> object.
|example1 = var n = props.Node.new();
var a = n;
print(a.equals(n)); # prints "1" (true)
}}

==== getAliasTarget() ====
{{Nasal doc
|syntax = props.Node.getAliasTarget();
|text = Returns the alias target of a node as another <code>props.Node</code> instance.
|example1 = setprop("/test", 2.35);
var node = props.Node.new();
node.alias("/test");
var tgt = node.getAliasTarget();
print(tgt.getPath()); # prints "/test"
}}

==== getAttribute() ====
{{Nasal doc
|syntax = props.Node.getAttribute([rel_path, ]name);
props.Node.getAttribute();
|text = Returns an attribute. If no arguments are given, the function will return an integer specifying the attributes set for the node (see {{simgear source|simgear/props/props.hxx|l=767}} for a list). A list of attributes are below
{{{!}} class="wikitable"
! String !! Return value
{{!-}}
{{!}} last {{!!}} The highest used attribute code (should be 128). See for {{simgear source|simgear/props/props.hxx|l=767}} the codes.
{{!-}}
{{!}} children {{!!}} Number of child nodes.
{{!-}}
{{!}} listeners {{!!}} Number of listeners connected to this node.
{{!-}}
{{!}} references {{!!}} Number of times the node has previously been referenced.
{{!-}}
{{!}} tied {{!!}} Whether the node is tied.
{{!-}}
{{!}} alias {{!!}} Whether the node is aliased.
{{!-}}
{{!}} readable {{!!}} Whether the node can be read.
{{!-}}
{{!}} writable {{!!}} Whether the node can be written to.
{{!-}}
{{!}} archive {{!!}} Whether the node will be saved when the "save" [[fgcommands|fgcommand]] is triggered.
{{!-}}
{{!}} trace-read {{!!}} Whether the reading of the node will be logged when <code>--log-level=info</code>.
{{!-}}
{{!}} trace-write {{!!}} Whether the writing to the node will be logged when <code>--log-level=info</code>.
{{!-}}
{{!}} userarchive {{!!}} Whether the node will be saved to the [[FlightGear configuration via XML#autosave.xml|autosave file]] (only works for actual properties).
{{!-}}
{{!}} preserve {{!!}} Whether the value of node will be preserved during resets (only works for actual properties).
{{!}}}
|param1 = rel_path
|param1text = Optional relative path as a string.
|param2 = name
|param2text = Attribute as a string. See the above table for a full list.
|example1 = var node = props.Node.new();
var child = node.addChild("a");
print(node.getAttribute("children")); # prints "1"
|example2text = Example using relative path
|example2 = var node = props.Node.new();
var child = node.addChild("a");
print(node.getAttribute("a", "readable")); # prints "1" (node can be read from)
|example3 = var node = props.Node.new();
var node2 = props.Node.new();
node2.alias(node);
print(node2.getAttribute("alias")); # prints "1" (true)
|example4 = print(props.globals.getNode("/sim/signals/fdm-initialized").getAttribute("listeners")); # prints the number of listeners
|example5 = print(props.globals.getNode("/sim/time/elapsed-sec").getAttribute("tied")); # prints "1" (true), meaning it is tied
|example6 = var node = props.Node.new();
print(node.getAttribute("writable")); # prints "1" (true), meaning the node can be written to
|example7text = Example using no arguments
|example7 = var node = props.Node.new();
print(node.getAttribute()); # prints "3" (true), meaning the node can be read from (1) and written to (2)
}}

==== getBoolValue() ====
{{Nasal doc
|syntax = props.Node.getBoolValue();
|text = Returns the value of a node converted to a boolean. If the node is a number type, 0 will return false, while 1 will return true. If the node is a string or unspecified type and the value is <code>"false"</code>, false will be returned. Otherwise, true will be returned. Remember that boolean values are represented in Nasal as 1 (true) and 0 (false).
|example1 = var node = props.Node.new();
node.setBoolValue(1);
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setBoolValue(0);
print(node.getBoolValue() ? "true" : "false"); # prints "false"
|example2 = var node = props.Node.new();
node.setDoubleValue(1.23);
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setDoubleValue(-1.23);
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setDoubleValue(0.0);
print(node.getBoolValue() ? "true" : "false"); # prints "false"
|example3 = var node = props.Node.new();
node.setIntValue(2);
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setIntValue(-2);
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setIntValue(0);
print(node.getBoolValue() ? "true" : "false"); # prints "false"
|example4 = var node = props.Node.new();
node.setValue("Hello, World!");
print(node.getBoolValue() ? "true" : "false"); # prints "true"
node.setValue("false");
print(node.getBoolValue() ? "true" : "false"); # prints "false"
}}

==== getChild() ====
{{Nasal doc
|syntax = props.Node.getChild(rel_path[, idx[, create]]);
|text = Returns a child of a node as another <code>props.Node</code> instance.
|param1 = rel_path
|param1text = Relative path to the child node as a string.
|param2 = idx
|param2text = Optional index for the child node as an integer.
|param3 = create
|param3text = If set to 1 (true), a new child will be created if it does not exist. If set to 0 (false), the function will not create a new child and the function will return <code>'''nil'''</code> if no child exists. Defaults to 0.
|example1 = var node = props.Node.new();
node.addChild("a");
var c = node.getChild("a");
|example2 = var node = props.Node.new();
node.addChildren("a", 3);
node.getNode("a[1]").setDoubleValue(2.35);
var c = node.getChild("a", 1);
print(c.getValue()); # prints "2.35"
|example3 = var node = props.Node.new();
var c = node.getChild("a", 1, 1);
props.dump(node); # new child a[1] will have appeared
}}

==== getChildren() ====
{{Nasal doc
|syntax = props.Node.getChildren([name]);
|text = Returns a vector of child nodes, optionally those with a certain name, as <code>props.Node</code> instances.
|param1 = name
|param1text = Optional name of the child nodes as a string. If not given, all children will be returned.
|example1 = var node = props.Node.new();
node.addChildren("a", 3);
node.addChildren("b", 3);
debug.dump(node.getChildren()); # all child nodes in the vector
|example2 = var node = props.Node.new();
node.addChildren("a", 3);
node.addChildren("b", 3);
debug.dump(node.getChildren("b")); # only children with the name "b" in the vector
}}

==== getIndex() ====
{{Nasal doc
|syntax = props.Node.getIndex();
|text = Returns the index of a node as an integer.
|example1 = var node = props.Node.new();
node.addChildren("a", 3);
print(node.getChild("a", 1).getIndex()); # prints "1"
|example2 = var node = props.Node.new();
node.addChild("b");
print(node.getChild("b").getIndex()); # prints "0"
}}

==== getName() ====
{{Nasal doc
|syntax = props.Node.getName();
|text = Returns the name of the node as a string.
|example1 = var node = props.Node.new();
var c = node.addChild("a");
debug.dump(c.getName()); # prints "a"
|example2 = var node = props.Node.new();
node.addChildren("a", 3);
debug.dump(node.getChild("a", 2).getName()); # prints "a"
}}

==== getNode() ====
{{Nasal doc
|syntax = props.Node.getNode(rel_path[, create]);
|text = Returns a subnode as another <code>props.Node</code> instance.
|param1 = rel_path
|param1text = Relative path to the subnode as a string.
|param2 = create
|param2text = If true (1), the node will be created if it does not exist. If false (0) and the node does not exist, the function will return <code>'''nil'''</code>. Default to false (0).
|example1 = var tree = {
"a": 1,
"b": "Hi",
"c": {
"d": "Hello, World!"
}
};
var node = props.Node.new(tree);
print(node.getNode("c/d").getValue()); # prints "Hello, World!"
|example2 = var tree = {
"a": 1,
"b": "Hi",
"c": {}
};
var node = props.Node.new(tree);
node.getNode("c/d", true).setDoubleValue(2.35);
props.dump(node); # c/d now exists
|example3 = var ac = props.globals.getNode("sim/aircraft");
print("Current aircraft is: ", ac.getValue());
}}

==== getParent() ====
{{Nasal doc
|syntax = props.Node.getParent();
|text = Returns the parent of a node, or <code>'''nil'''</code> if there is no parent.
|example1 = var tree = {
"a": 1,
"b": "Hi",
"c": {
"d": "Hello, World!"
}
};
var node = props.Node.new(tree);
props.dump(node.getNode("c/d").getParent()); # dumps "c"
|example2 = var node = props.Node.new();
debug.dump(node.getParent()); # prints nil
}}

==== getPath() ====
{{Nasal doc
|syntax = props.Node.getPath();
|text = Returns the path of the node as a string.
|example1 = var tree = {
"a": 1,
"b": "Hi",
"c": {
"d": "Hello, World!"
}
};
var node = props.Node.new(tree);
print(node.getNode("c/d").getPath()); # prints "/c/d"
}}

==== getType() ====
{{Nasal doc
|syntax = props.Node.getType();
|text = Returns node's type as a string. It should be one of "NONE", "ALIAS", "BOOL", "INT", "LONG" (long integer), "FLOAT", "DOUBLE", "STRING", "VEC3D", "VEC4D", "UNSPECIFIED".
|example1 = var node = props.Node.new();
print(node.getType()); # prints "NONE"
|example2 = var node = props.Node.new();
node.setIntValue(12);
print(node.getType()); # prints "INT"
|example3 = var node = props.Node.new();
node.setValue([0.4, 0.2, 1]);
debug.dump(node.getValue()); # prints "[0.4, 0.2, 1]"
print(node.getType()); # prints "VEC3D"
}}

==== getValue() ====
{{Nasal doc
|syntax = props.Node.getValue([rel_path]);
|text = {{hatnote|See also {{func link|getBoolValue()|page=this}}.}}

Returns the value of the node.
|param1 = rel_path
|param1text = Optional relative path to a subnode as a string, which may contain '/' characters. If the subnode does not exist, we return nil.
|example1 = var node = props.Node.new();
node.setDoubleValue(2.35);
print(node.getValue()); # prints "2.35"
|example2 = var node = props.Node.new();
node.setValue("Hi");
print(node.getValue()); # prints "Hi"
|example3 = var node = props.Node.new();
node.addChild("a").setValue("Hi");
print(node.getValue("a")); # prints "Hi"
|example4 = var node = props.Node.new();
node.setValue([0, 0.5, 1]);
debug.dump(node.getValue()); # prints "[0, 0.5, 1]"
}}

==== getValues() ====
{{Nasal doc
|syntax = props.Node.getValues();
|text = Returns the node tree as a hash, with all the various subnodes, etc. If the node has no children, the result is equivalent to {{func link|getValue()|page=this}}. Subnodes that are indexed will be combined into one key and their values placed in a vector (see example 2).
|example1 = var tree = {
"string": "Hi",
"number": 1.2,
"subnode": {
"idx-node": [1, 2, 3]
}
};
var node = props.Node.new(tree);
node.addChild("bool").setBoolValue(1);
props.dump(node); # dump to node tree
debug.dump(node.getValues()); # dump the node converted to hash
|example2 = var tree = {
"a": [1, 2, 3]
};
var node = props.Node.new(tree);
props.dump(node); # a[0] = 1, a[1] = 2, a[2] = 3
debug.dump(node.getValues()); # a: [1, 2, 3]
}}

==== increment() (since FG 2020.1) ====
{{Nasal doc
|syntax = props.Node.increment(n = 1);
|text = Increments integer property by n (default: n = 1)
|param1 = n
|param1text = Value to add, will be converted to int, defaults to 1
}}

==== initNode() ====
{{Nasal doc
|syntax = props.Node.initNode([path[, value[, type[, force]]]]);
|text = Initializes a node if it doesn't exist and returns that node as a <code>props.Node</code> object.
|param1 = path
|param1text = Optional path to a subnode as a string. If not given, the node itself will be initialized.
|param2 = value
|param2text = Optional default value to initialize the node with.
|param3 = type
|param3text = Optional string that will set the type of the node. Must be one of <code>"DOUBLE"</code>, <code>"INT"</code>, <code>"BOOL"</code>, or <code>"STRING"</code>.
|param4 = force
|param4text = If set to 1 (true), the node's type will be forced to change.
|example1 = var node = props.Node.new();
var a = node.initNode("a");
props.dump(a);
|example2 = var node = props.Node.new();
var a = node.initNode("a", "Hi");
props.dump(a);
|example3 = var node = props.Node.new();
var a = node.initNode("a", 1.25, "INT");
props.dump(a); # a = 1
|example4 = var node = props.Node.new();
node.addChild("a").setBoolValue(0);
props.dump(node.getChild("a")); # a = 0 (type: bool)
var a = node.initNode("a", 1.25, "INT", 1);
props.dump(a); # a = 0 (type: int)
}}

==== isInt() (since FG 2020.1) ====
{{Nasal doc
|syntax = props.Node.isInt();
|text = Returns true (1) if node '''type''' is "INT" or "LONG" (long integer) otherwise false (0).
}}

==== isNumeric() (since FG 2020.1) ====
{{Nasal doc
|syntax = props.Node.isNumeric();
|text = Returns true (1) if node '''type''' is "INT", "LONG", "FLOAT" or "DOUBLE" otherwise false (0).
}}

==== remove() ====
{{Nasal doc
|syntax = props.Node.remove();
|text = Removes the node and returns the removed node.
|example1 = var node = props.Node.new();
node.addChild("a");
props.dump(node);
node.getChild("a").remove();
props.dump(node); # child "a" does not exist anymore
}}

==== removeAllChildren() ====
{{Caution|Be careful when using this API in conjunction with the Canvas system and element specific properties, for details please see [[Howto:Canvas Path Benchmarking]]}}
{{Nasal doc
|syntax = props.Node.removeAllChildren();
|version = 3.2
|commit = {{fgdata commit|4766ed21a68230c0c15265e5604a74f4d99e0f5d|t=commit}}
|text = Removes all child nodes and returns the node.
|example1 = var tree = {
"a": 1,
"b": 2,
"c": 3
};
var node = props.Node.new(tree);
props.dump(node);
node.removeAllChildren();
props.dump(node); # all children have been removed
}}

==== removeChild() ====
{{Nasal doc
|syntax = props.Node.removeChild(rel_path, idx);
|text = Removes a given child node child nodes and returns the node.
|param1 = rel_path
|param1text = Relative path to a subnode as a string.
|param2 = idx
|param2text = Index of the subnode to remove as an integer.
|example1 = var node = props.Node.new();
node.addChild("a");
props.dump(node);
node.removeChild("a", 0);
props.dump(node); # child "a" has been removed
|example2 = var node = props.Node.new();
node.addChildren("a", 2);
props.dump(node);
node.removeChild("a", 0);
props.dump(node); # just a[1] remains
}}

==== removeChildren() ====
{{Nasal doc
|syntax = props.Node.removeChildren([name]);
|text = Removes all children with a specified name. If no arguments are given, all children will be removed (see also {{func link|removeAllChildren()|page=this}}).
|param1 = name
|param1text = Optional name of children to remove as a string.
|example1 = var node = props.Node.new();
node.addChildren("a", 2);
node.addChildren("b", 2);
props.dump(node);
node.removeChildren("a");
props.dump(node); # just children named "b" remain
|example2 = var node = props.Node.new();
node.addChildren("a", 2);
node.addChildren("b", 2);
props.dump(node);
node.removeChildren();
props.dump(node); # all children removed
}}

==== setAttribute() ====
{{Nasal doc
|syntax = props.Node.setAttribute([rel_path, ]attr, value);
props.Node.setAttribute(attrs);
|text = Sets an attribute or multiple attributes. A list of attributes and their codes are below. For a brand new node, the default attributes are ''readable'' and ''writable''. Returns an integer specifying the old attributes.
{{{!}} class="wikitable"
! String !! Description
{{!-}}
{{!}} readable {{!!}} Whether the node can be read.
{{!-}}
{{!}} writable {{!!}} Whether the node can be written to.
{{!-}}
{{!}} archive {{!!}} Whether the node will be saved when the "save" [[fgcommands|fgcommand]] is triggered.
{{!-}}
{{!}} trace-read {{!!}} Whether the reading of the node will be logged when <code>--log-level=info</code>.
{{!-}}
{{!}} trace-write {{!!}} Whether the writing to the node will be logged when <code>--log-level=info</code>.
{{!-}}
{{!}} userarchive {{!!}} Whether the node will be saved to the [[FlightGear configuration via XML#autosave.xml|autosave file]] (only works for actual properties).
{{!-}}
{{!}} preserve {{!!}} Whether the value of node will be preserved during resets (only works for actual properties).
{{!}}}
|param1 = rel_path
|param1text = Optional relative path as a string.
|param2 = attr
|param2text = Name of attribute to set as a string. See above.
|param3 = value
|param3text = Boolean value to set the property to.
|param4 = attrs
|param4text = When the function is used in its second form, this argument is used. This argument should be an integer specifying which arguments are set to true. See {{simgear source|simgear/props/props.hxx|l=767}} for the full list of codes. Simply add codes of the desired attributes together.
|example1 = var node = props.Node.new();
node.setAttribute("trace-write", 1);
node.setIntValue(12); # will be traced
|example2 = var node = props.Node.new();
node.setAttribute("readable", 0);
var val = node.getValue();
debug.dump(val); # prints "nil"
|example3 = var node = props.Node.new();
node.addChild("a");
node.setAttribute("a", "trace-write", 1);
node.getChild("a").setIntValue(12); # will be traced
|example4 = var node = props.Node.new();
node.setAttribute(35); # read + write + trace-write
node.setIntValue(12); # will be traced
}}

==== setBoolValue() ====
{{Nasal doc
|syntax = props.Node.setBoolValue([rel_path, ]value);
|text = {{note|For setting the values of [[Property Tree]] nodes, it is recommended to use {{func link|setprop()}} if possible, due to performance differences.}}

Sets a node to a boolean value. If the node has no type, it will be set to a bool type. If the node is already a number type, it will be set to either 1 or 0. If it is a string, it will be set to either "true" or "false". Returns 1 (true) if the operation was successful.
|param1 = rel_path
|param1text = Optional relative path as a string.
|param2 = value
|param2text = Value to set the node to, will be interpreted into a boolean. If it is <code>'''nil'''</code>, it will be false. If it is a string, it will be false. If it is a number, 0 will be false, while other numbers will be true. All other cases will be interpreted as 0.
|example1 = var node = props.Node.new();
node.setBoolValue(nil);
props.dump(node); # node = 0 (false)
|example2 = var node = props.Node.new();
node.setBoolValue("Hi");
props.dump(node); # node = 1 (true)
|example3 = var node = props.Node.new();
node.setBoolValue(0);
props.dump(node); # node = 0 (false)
node.setBoolValue(1.25);
props.dump(node); # node = 1 (true)
|example4 = var node = props.Node.new();
node.setValue("String");
props.dump(node); # node = "String" (type: string)
node.setBoolValue(1);
props.dump(node); # node = "true"
|example5 = var node = props.Node.new();
node.setDoubleValue(12.32);
props.dump(node); # node = 12.32 (type: double)
node.setBoolValue(1);
props.dump(node); # node = 1
|example6 = var node = props.Node.new();
node.addChild("a");
node.setBoolValue("a", 1);
props.dump(node); # /a = 1
}}

==== setDoubleValue() ====
{{Nasal doc
|syntax = props.Node.setDoubleValue([rel_path, ]value);
|text = {{note|For setting the values of [[Property Tree]] nodes, it is recommended to use {{func link|setprop()}} if possible, due to performance differences.}}

Sets a node to a double value. If the node has no type, it will be set to a double type. If the node is a bool, values different from zero will be interpreted as true. If the node is a string, the value will be converted to a string. If the node is an integer type, it will be truncated to the closest integer to zero. Returns 1 (true) if the operation was successful.
|param1 = rel_path
|param1text = Optional relative path as a string.
|param2 = value
|param2text = Value to set the node to, will be interpreted into a double number. It must be a valid number or a string that can be converted to a number.
|example1 = var node = props.Node.new();
node.setDoubleValue(1.1);
props.dump(node); # node = 1.1 (type: double)
|example2 = var node = props.Node.new();
node.setDoubleValue("1.1");
props.dump(node); # node = 1.1 (type: double)
|example3 = var node = props.Node.new();
node.setBoolValue(1);
node.setDoubleValue("1.1");
props.dump(node); # node = 1 (type: bool)
node.setDoubleValue(0.0);
props.dump(node); # node = 0 (type: bool)
|example4 = var node = props.Node.new();
node.setIntValue(1);
node.setDoubleValue(1.1);
props.dump(node); # node = 1 (type: int)
node.setDoubleValue("-1.1");
props.dump(node); # node = -1 (type: int)
|example5 = var node = props.Node.new();
node.addChild("a");
node.setDoubleValue("a", 12.2);
props.dump(node); # /a = 12.2
}}

==== setIntValue() ====
{{Nasal doc
|syntax = props.Node.setIntValue([rel_path, ]value);
|text = {{note|For setting the values of [[Property Tree]] nodes, it is recommended to use {{func link|setprop()}} if possible, due to performance differences.}}

Sets a node to an integer value. If the node has no type, it will be set to a integer type. If the node is a bool, values different from zero will be interpreted as true. If the node is a string, the value will be converted to a string. Returns 1 (true) if the operation was successful.
|param1 = rel_path
|param1text = Optional relative path as a string.
|param2 = value
|param2text = Value to set the node to, will be interpreted into a integer. It must be a valid number or a string that can be converted to a number. If the number is a double, it will be truncated to the closest integer to zero.
|example1 = var node = props.Node.new();
node.setIntValue(12);
props.dump(node); # node = 12
node.setIntValue("6");
props.dump(node); # node = 6
|example2 = var node = props.Node.new();
node.setIntValue(12.2);
props.dump(node); # node = 12
node.setIntValue(-12.2);
props.dump(node); # node = 12
|example3 = var node = props.Node.new();
node.setBoolValue(1);
node.setIntValue(12.5);
props.dump(node); # node = 1 (type: bool)
node.setIntValue(0);
props.dump(node); # node = 0 (type: bool)
|example4 = var node = props.Node.new();
node.setValue("Hi");
node.setIntValue(12);
props.dump(node); # node = "12" (type: string)
|example5 = var node = props.Node.new();
node.addChild("a");
node.setIntValue("a", 12);
props.dump(node); # /a = 12
}}

==== setValue() ====
{{Nasal doc
|syntax = props.Node.setValue([rel_path, ]value);
|text = {{hatnote|See also {{func link|setBoolValue()|page=this}}, {{func link|setDoubleValue()|page=this}}, and {{func link|setIntValue()|page=this}}.}}

{{note|For setting the values of [[Property Tree]] nodes, it is recommended to use {{func link|setprop()}} if possible, due to performance differences.}}

Sets a node to a given value. See table below for conversions and effects. Note that vec3d and vec4d types are not fully integrated into SGPropertyNode. Returns 1 (true) if the operation was successful.

{{{!}} class="wikitable"
{{!}} colspan="2" style="text-align:right" {{!}} '''value''' type →
! rowspan="2" {{!}} Number
! rowspan="2" {{!}} String
! rowspan="2" {{!}} Vector
{{!-}}
{{!}} style="text-align:left" {{!}} Current node<br>type ↓
{{!}} style="text-align:right" {{!}} Result ↘
{{!-}}
! colspan="2" {{!}} None/unspecified
{{!}}
* Type set to <code>double</code>
* Node set to '''value'''.
{{!}}
* Type set to <code>string</code>
* Node set to '''value'''.
{{!}}
* Type set to <code>vec*d</code>
* Node set to '''value'''.
{{!-}}
! colspan="2" {{!}} Bool
{{!}}
* If '''value''' != 0, node set to true.
* If '''value''' == 0, node set to false.
{{!}}
* If '''value''' == "true", node set to true.
* If '''value''' can be converted to an integer,<br>and != 0, node set to true.
{{!}} Node set to true.
{{!-}}
! colspan="2" {{!}} Integer
{{!}} Node set to truncated '''value'''
{{!}} Node set to '''value ''' converted and truncated to an integer.
{{!}} Node set to 1.
{{!-}}
! colspan="2" {{!}} Double
{{!}} Node set to '''value'''.
{{!}} Node set to '''value''' converted to number.
{{!}} Throws an error (vector is not a number).
{{!-}}
! colspan="2" {{!}} String
{{!}} Node set to '''value''' converted to string. {{!!}} Node set to '''value'''. {{!!}} Node not set.
{{!}}}
|param1 = rel_path
|param1text = Optional relative path as a string.
|param2 = value
|param2text = Value to set the node to. Must be a string, a valid number, or a vector consisting of 3 or 4 numbers. See table above for conversions and effects.
|example1 = var node = props.Node.new();
node.setValue("Hi");
props.dump(node); # node = "Hi"
|example2 = var node = props.Node.new();
node.addChild("a");
node.setValue("a", "Hi");
props.dump(node); # \a = "Hi"
|example3 = var node = props.Node.new();
node.setValue([0.4, 0.2, 1]);
debug.dump(node.getValue()); # prints "[0.4, 0.2, 1]"
print(node.getType()); # prints "VEC3D"
}}

==== setValues() ====
{{Nasal doc
|syntax = props.Node.setValues(val);
|text = {{hatnote|See also {{func link|getValues()|page=this}}.}}

Sets the nodes property tree from a Nasal hash. Scalars will become nodes in the tree and hashes will become named subnodes. Vectors will be converted into indexed nodes, with the values in the vector becoming their values (see examples below).
|param1 = val
|param1text = A hash that will become the property tree.
|example1 = var val = {
"a": 100 # "a" will become the subnode's name, and 100 its value
};
var node = props.Node.new();
node.setValues(val);
props.dump(node); # dump tree
|example2 = var val = {
"a": 1,
"b": "Hi",
"c": {
"d": [1, 2, 3]
}
};
var node = props.Node.new();
node.setValues(val);
props.dump(node); # dump tree
}}

==== unalias() ====
{{Nasal doc
|syntax = props.Node.unalias();
|text = Un-aliases the node and returns it to a blank state. Returns 1 on success and 0 on failure (e.g., when used on a tied property).
|example2 = var node1 = props.Node.new();
node1.setDoubleValue(2.35);
var node2 = props.Node.new();
node2.alias(node1);

props.dump(node2); # equals 2.35
node2.unalias();
props.dump(node2); # no value or type
}}

==== toggleBoolValue() (since FG 2020.1) ====
{{Nasal doc
|syntax = toggleBoolValue();
|text = Toggle a boolean property. You have to make sure the property is of type bool!
|example1 = var b = props.Node.new().initNode("/_test/bool", 1, "BOOL");
print("bool ", b.getValue());
b.toggleBoolValue();
print("after toggleBoolValue ", b.getValue());

}}

== Functions ==
=== compileCondition() ===
{{see also|Conditions}}

{{Nasal doc
|syntax = props.compileCondition(node);
|version = 3.2
|commit = {{fgdata commit|43f8ce08706629e69984b1cc34e5e979d03ef09a|t=commit}}
|text = Compiles a [[conditions|condition]] property branch and returns a <code>Condition</code> ghost object or <code>'''nil'''</code> on error. This ghost will contain a <code>test()</code> function that will return the result of the condition as either 1 (true) or 0 (false).
|param1 = node
|param1text = Either a props.Node containing the condition, or a string specifying a place in the [[Property Tree]] where there is a condition branch.
|example1 = var tree = {
"equals": {
"property": '/test',
"value": 12
}
};
var node = props.Node.new(tree);
setprop("/test", 12);

var cond = props.compileCondition(node);
print(cond.test()); # prints "1" (true)
setprop("/test", 15);
print(cond.test()); # prints "0" (false)
|example2 = var tree = {
"equals": {
"property": '/test',
"value": 12
}
};
props.globals.getNode("test2/condition", 1).setValues(tree); # place it in the Property Tree
setprop("/test", 12);

var cond = props.compileCondition(node);
print(cond.test()); # prints "1" (true)
setprop("/test", 15);
print(cond.test()); # prints "0" (false)
}}

=== condition() ===
{{Nasal doc
|syntax = props.condition(node);
|text = Evaluates a [[conditions|condition]] property branch and returns the result as a boolean.
|param1 = node
|param1text = Either a props.Node containing the condition, or a string specifying a place in the [[Property Tree]] where there is a condition branch.
|example1 = var tree = {
"equals": {
"property": '/test',
"value": 12
}
};
var node = props.Node.new(tree);
setprop("/test", 12);

print(props.condition(node)); # prints "1" (true)
setprop("/test", 15);
print(props.condition(node)); # prints "0" (false)
|example2 = var tree = {
"equals": {
"property": '/test',
"value": 12
}
};
props.globals.getNode("test2/condition", 1).setValues(tree); # place it in the Property Tree
setprop("/test", 12);

print(props.condition(node)); # prints "1" (true)
setprop("/test", 15);
print(props.condition(node)); # prints "0" (false)
}}

=== copy() ===
{{Nasal doc
|syntax = props.copy(src, dest[, attr]);
|text = Copies the property tree of the source into the destination node. Note that aliased properties will not be copied.
|param1 = src
|param1text = Source <code>props.Node object</code> to copy from.
|param2 = dest
|param2text = Destination <code>props.Node object</code> to copy to.
|param3 = attr
|param3text = If set to 1 (true), attributes will also be copied. Defaults to 0 (false).
|example1 = var tree = {
"a": 1.5,
"b": "Hi",
"c": {
"d": [1, 2, 3]
}
};
var src = props.Node.new(tree);
var dest = props.Node.new();
props.copy(src, dest);
props.dump(dest);
|example2 = var src = props.Node.new();
var a = src.addChild("a");
a.setAttribute("trace-write", 1);
a.setIntValue(12);
var dest = props.Node.new();
props.copy(src, dest, 1);
print(dest.getNode("a").getAttribute("trace-write")); # prints "1" (true)
}}

=== dump() ===
{{Nasal doc
|syntax = props.dump(node);
|text = Recursively dump the state of a node into the console, showing value and type of each node. Note that as of 10/2016, the value of vec*d type nodes cannot be dumped.
|param1 = node
|param1text = Node to dump.
|example1 = var node = var tree = {
"a": 12,
"b": "Hi",
"c": {
"d": [1, 2, 3]
}
};
var node = props.Node.new(tree);
props.dump(node); # dump into console
|example2 = # Dump the entire Property Tree
# Warning! This is an intensive operation!
props.dump(props.globals);
}}

=== getNode() ===
{{Nasal doc
|syntax = props.getNode();
|version = 3.2
|commit = {{fgdata commit|807062d0b6f858885547f27325e829c2bf42a12b|t=commit}}
|text = Shortcut for <syntaxhighlight lang="nasal" inline>props.globals.getNode()</syntaxhighlight>. See {{func link|getNode()||Node|page=this}} for full documentation.
|example1 = print("Current aircraft is: ", props.getNode("/sim/aircraft").getValue());
}}

=== nodeList() ===
{{Nasal doc
|syntax = props.nodeList(arg[, arg[, ...]]);
|text = Converts its arguments into a vector of node objects if possible and returns that vector.
|param1 = arg
|param1text = Object to operate on. Must be a node object, string, vector, hash, function, or <code>prop</code> ghost. Vectors and hashes must contain any of the other acceptable types, functions must return any of the other types, strings will be assumed to be paths to global properties, and ghosts will be converted into node objects. There may be any number of arguments.
|example1 = var node = props.Node.new();
var f = func(){
var n = props.Node.new();
return n._g;
}
var list = props.nodeList(node,
"/sim/aircraft",
["/sim/fg-root"],
{ "path": "/sim/fg-home" },
f
);
debug.dump(list); # dump list
|example2 = var root = "/sim/version/";
var info = [
root ~ "build-id",
root ~ "build-number",
root ~ "flightgear",
root ~ "hla-support",
root ~ "openscenegraph",
root ~ "revision",
root ~ "simgear"
];
info = props.nodeList(info); # turn into list of nodes
foreach(var n; info){
print(n.getValue()); # dump info
}
}}

=== runBinding() ===
{{Nasal doc
|syntax = props.runBinding(node[, module]);
|text = Runs a [[Bindings|binding]] element in a node object. Returns 1 (true) on success and 0 (false) on failure.
|param1 = node
|param1text = A {{tag|binding}} element as a node object.
|param2 = module
|param2text = Optional string specifying a module to run Nasal scripts in if the command is <code>nasal</code>. This argument will not override any {{tag|module}} element in the '''node'''
|example1 = var tree = {
"command": "dialog-show",
"dialog-name": "map" # open map
};
var binding = props.Node.new(tree);
props.runBinding(binding);
|example2 = var tree = {
"command": "nasal",
"script": 'print(pi)' # prints value of math.pi
};
var binding = props.Node.new(tree);
props.runBinding(binding, "math");
|example3 = var tree = {
"command": "nasal",
"script": 'print(pi)', # prints value of math.pi
"module": "math" # this is used
};
var binding = props.Node.new(tree);
props.runBinding(binding, "debug");
}}

=== setAll() ===
{{Nasal doc
|syntax = props.setAll(base, child, value);
|text = Sets indexed subnodes in the Property Tree with the same name to the same value.
|param1 = base
|param1text = Base path to the nodes.
|param2 = child
|param2text = Path to child nodes.
|param3 = value
|param3text = Value to set the subnodes to.
|example1 = # apply 50% throttle to all engines
props.setAll("/controls/engines/engine", "throttle", 0.5);
|example2 = var nodes = props.globals.addChildren("/test", 3);
foreach(var node; nodes){
node.addChild("a");
}
props.setAll("/test", "a", "Hi"); # set all children (test[*]/a) to "Hi"
}}

=== wrap() ===
{{Nasal doc
|syntax = props.wrap(node);
|text = Turns <code>prop</code> ghosts, either in a vector or single, into <code>props.Node</code> objects.
|param1 = node
|param1text = <code>prop</code> ghost or vector of such ghosts.
|example1 = var ghost = canvas._newCanvasGhost();
var node = props.wrap(ghost._node_ghost);
props.dump(node);
|example2 = var vector = [canvas._newCanvasGhost()._node_ghost, props.Node.new()._g];
var nodes = props.wrap(vector);
foreach(var node; nodes){
props.dump(node);
print("----");
}
}}

=== wrapNode() ===
{{Nasal doc
|syntax = props.wrapNode(node);
|text = Turns a <code>prop</code> ghost into a <code>props.Node</code> object.
|param1 = node
|param1text = <code>prop</code> ghost to convert.
|example1 = var ghost = canvas._newCanvasGhost();
var node = props.wrapNode(ghost._node_ghost);
props.dump(node);
}}

== Variable ==
=== globals ===
{{Nasal doc
|syntax = props.globals;
|text = Exposes the [[Property Tree]] as a <code>props.Node</code> object.

|example1 = print("Current aircraft: ", props.globals.getNode("/sim/aircraft").getValue());
|example2text = Alternative using {{func link|getprop()}}.
|example2 = print("Current aircraft: ", getprop("/sim/aircraft"));
}}

{{Nasal namespaces}}

Nasal library

2025-12-04T12:52:53Z

PlayeRom: /* range() */

{{Nasal Navigation|nocat=1}}
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:
* {{flightgear file|src/Scripting}}
* {{simgear file|simgear/nasal}}

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]].

{{tip|Copy & paste the examples into your [[Nasal Console]] and execute them to see what they do.|width=70%}}

== Core library functions ==
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:
* http://plausible.org/nasal/lib.html ([http://web.archive.org/web/20101010094553/http://plausible.org/nasal/lib.html archive])
* {{simgear file|simgear/nasal/lib.c}} ([http://sourceforge.net/p/flightgear/simgear/ci/next/log/?path=/simgear/nasal/lib.c history])

=== append() ===
{{Nasal doc
|syntax = append(vector, element[, element[, ...]]);
|source = {{simgear file|simgear/nasal/lib.c|l=45|t=Source}}
|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.
|param1 = vector
|param1text = The vector to which the arguments will be appended.
|param2 = element
|param2text = An element to be added to the vector.
|example1 =
var vector = [1, 2, 3]; # Initialize the vector
append(vector, 4); # Append the number 4 to the end of the vector
debug.dump(vector); # Print the contents of the vector
|example2 =
var vector = [1, 2, 3]; # Initialize the vector
append(vector, 4, 5, 6); # Append the numbers 4, 5, and 6 to the end of the vector
debug.dump(vector); # Print the contents of the vector
}}

=== bind() ===
{{Nasal doc
|syntax = bind(function, locals[, outer_scope]);
|source = {{simgear file|simgear/nasal/lib.c|l=638|t=Source}}
|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.
|param1 = function
|param1text = Function to evaluate.
|param2 = locals
|param2text = Hash containing values that will become the namespace (first closure) for the function.
|param3 = outer_scope
|param3text = Optional function which is bound to the next closure. This can be bound to yet another, making a linked list.
|example1 = # This is a namespace/hash with a single member, named "key," which is initialized to 12
var Namespace = {
key: 12
};

# This is different namespace/hash containing a function
# dividing a variable "key" (which is unavailable/nil in this namespace) by 2
var AnotherNamespace = {
ret: func {
key /= 2;
}
};

# To see that key is not available, try to call AnotherNamespace.ret() first
call(AnotherNamespace.ret, [], nil, nil, var errors = []);
if(size(errors)){
print("Key could not be divided/resolved!");
debug.printerror(errors);
}

# Associate the AnotherNamespace.ret() function with the first namespace
# so that "key" is now available
var function = bind(AnotherNamespace.ret, Namespace);

# Invoke the new function
function();

# Print out the value of Namespace.key
# It was changed to 12 from 6 by AnotherNamespace.ret()
print(Namespace.key);
}}

=== call() ===
{{Nasal doc
|syntax = call(func[, args[, me[, locals[, error]]]);
|source = {{simgear file|simgear/nasal/lib.c|l=376|t=Source}}
|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.
|param1 = func
|param1text = Function to execute.
|param2 = args
|param2text = Vector containing arguments to give to the called function.
|param3 = me
|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).
|param4 = locals
|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.
|param5 = error
|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}}.
|example1 =
# prints "Called from call()"
call(func {
print("Called from call()");
});
|example2 =
# prints "a = 1 : b = 2
call(func(a, b){
print("a = ", a, " : b = ", b);
},
[1, 2]
);
|example3 =
var Hash = {
new: func {
var m = { parents: [Hash] };

m.el1 = "string1";
m.el2 = "string2";

return m;
}
};

# prints "me.el1 = string1", then "me.el2 = string2" on the next line
call(func(a, b){
print("me.el", a, " = ", me["el" ~ a]);
print("me.el", b, " = ", me["el" ~ b]);
},
[1, 2],
Hash.new()
);
|example4 =
# prints the value of math.pi
call(func {
print(pi);
}, nil, nil,
math
);
|example5 =
call(func {
print(math.ip); # math.ip doesn't exist
}, nil, nil, nil,
var errs = []
);
debug.printerror(errs); # The error is caught and printed using debug.printerror()
}}

=== caller() ===
{{Nasal doc
|syntax = caller([level]);
|source = {{simgear file|simgear/nasal/lib.c|l=540|t=Source}}
|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 '''[0]''' a hash of local variables, '''[1]''' the function object, '''[2]''' the full source file name (incl. path) and '''[3]''' the line number.
|param1 = level
|param1text = Optional integer specifying the stack level to return a result from. Defaults to 1 (i.e. the caller of the currently executing function).
|example1 =
var myFunction = func(a, b) {
debug.dump(caller(0)[0]); # prints a hash of local variables, including arguments a and b
return 2 * 2;
};

print("2 x 2 = ", myFunction(2, 2));
|example2 =
var get_arg_value = func() {
print("Argument to myFunc = ", caller(1)[0]['a']); # print the value of myFunc's single argument, using caller()
};

var myFunc = func(a) {
get_arg_value();
};

myFunc(3);
|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: true, zindex: nil }</code>.
|example3 =
var MapStructure_selfTest = func() {
var temp = {};
temp.dlg = canvas.Window.new([600, 400], "dialog");
temp.canvas = temp.dlg.createCanvas().setColorBackground(1, 1, 1, 0.5);
temp.root = temp.canvas.createGroup();

var testMap = temp.root.createChild("map");
testMap.setController("Aircraft position");
testMap.setRange(25); # TODO: implement zooming/panning via mouse/wheel here, for lack of buttons :-/
testMap.setTranslation(
temp.canvas.get("view[0]") / 2,
temp.canvas.get("view[1]") / 2,
);

var r = func(name, vis = true, zindex = nil) {
return caller(0)[0];
}

# TODO: we'll need some z-indexing here, right now it's just random
# TODO: use foreach/keys to show all layers in this case by traversing SymbolLayer.registry directly ?
# maybe encode implicit z-indexing for each lcontroller ctor call ? - i.e. preferred above/below order ?
var types = [
r('TFC', false),
r('APT'),
r('DME'),
r('VOR'),
r('NDB'),
r('FIX', false),
r('RTE'),
r('WPT'),
r('FLT'),
r('WXR'),
r('APS'),
];

foreach (var type; types) {
testMap.addLayer(
factory: canvas.SymbolLayer,
type_arg: type.name,
visible: type.vis,
priority: type.zindex,
);
}
}; # MapStructure_selfTest
}}

=== chr() ===
{{Nasal doc
|syntax = chr(code);
|source = {{simgear file|simgear/nasal/lib.c|l=240|t=Source}}
|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.}}
{{{!}} class="wikitable"
! Code !! Name !! Equivalent to
{{!-}}
{{!}} 10 {{!!}} {{Wikipedia|Newline}} {{!!}} <code>\n</code>
{{!-}}
{{!}} 9 {{!!}} {{Wikipedia|Tab key#Tab characters|Horizontal tab}} {{!!}} <code>\t</code>
{{!-}}
{{!}} 13 {{!!}} {{Wikipedia|Carriage return}} {{!!}} <code>\r</code>
{{!}}}
|param1 = code
|param1text = Integer character code for the desired glyph.
|example1 = print("Code 65 = ", chr(65)); # prints "Code 65 = A"
|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.
|example2 =
for(var i = 0; i <= 255; i += 1){
print("Code ", i, " = >", chr(i), "<");
}
}}

=== closure() ===
{{Nasal doc
|syntax = closure(func[, level]);
|source = {{simgear file|simgear/nasal/lib.c|l=557|t=Source}}
|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'''.
|param1 = func
|param1text = Function to evaluate.
|param2 = level
|param2text = Optional integer specifying the scope level. Defaults to 0 (the namespace of '''func''').
|example1 =
var get_math_e = func {
return e; # return the value of math.e
}

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
debug.dump(closure(myFunction)); # print the hash of the namespace "get_math_e"

print(myFunction());
}}

=== cmp() ===
{{Nasal doc
|syntax = cmp(a, b);
|source = {{simgear file|simgear/nasal/lib.c|l=169|t=Source}}
|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'''.
|param1 = a
|param1text = First string argument for comparison.
|param2 = b
|param2text = Second string argument for comparison.
|example1 = print(cmp("1", "two")); # prints -1
|example2 = print(cmp("string", "string")); # prints 0
|example3 = print(cmp("one", "2")); # prints 1
|example4 = print(cmp("string1", "string2")); # prints -1
}}

=== compile() ===
{{Nasal doc
|syntax = compile(code[, filename]);
|source = {{simgear file|simgear/nasal/lib.c|l=349|t=Source}}
|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'''.
|param1 = code
|param1text = String containing Nasal code to be compiled.
|param2 = filename
|param2text = Optional string used for error messages/logging. Defaults to <code><compile></code>
|example1 =
var myCode = 'print("hello");';
var helloFunc = compile(myCode, "myCode");
helloFunc();
|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>.
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<PropertyList>

<nasal><![CDATA[
print("You have FlightGear v", getprop("/sim/version/flightgear"));
]]></nasal>

</PropertyList>
</syntaxhighlight>
Now, start FlightGear and execute this code in the [[Nasal Console]].
|example2 =
# Build the path
var FGRoot = getprop("/sim/fg-root");
var filename = "/gui/dialogs/test.xml";
var path = FGRoot ~ filename;

var blob = io.read_properties(path);
var script = blob.getValues().nasal; # Get the nasal string

# Compile the script. We're passing the filename here for better runtime diagnostics
var code = call(func {
compile(script, filename);
}, nil, nil, var compilation_errors = []);

if(size(compilation_errors)){
die("Error compiling code in: " ~ filename);
}

# Invoke the compiled script, equivalent to code();
# We're using call() here to detect errors:
call(code, [], nil, nil, var runtime_errors = []);

if(size(runtime_errors)){
die("Error calling code compiled loaded from: " ~ filename);
}
|example3text = The <code>compile()</code> function also allows you to parse a JSON string into a hash. Simplest example:
|example3 =
var jsonFunc = compile('{"version":"1.2.0","author":{"name":"John"} }');
var json = jsonFunc(); # return hash
logprint(LOG_ALERT, json["version"]); # print "1.2.0"
logprint(LOG_ALERT, json["author"]["name"]); # print "John"
}}

=== contains() ===
{{Nasal doc
|syntax = contains(hash, key);
|source = {{simgear file|simgear/nasal/lib.c|l=249|t=Source}}
|text = Returns 1 (True) if the hash contains the specified key, or 0 (False) if not.
|param1 = hash
|param1text = The hash to search in.
|param2 = key
|param2text = The scalar to be searched for, contained as a key in the hash.
|example1 =
# Initialize a hash
var hash = {
element: "value"
};
print(contains(hash, "element") ? "Yes" : "No"); # This will print "Yes"
print(contains(hash, "element2") ? "Yes" : "No"); # This will print "No"
}}

===contains()===
{{Requires commit|desc=Vector support|details=see {{Merge-request|project=fgdata|id=305}}|commit=ee39abbd3b70c9b6d5e3a1c4ccedddaac1a92b11|repo=Simgear}}
{{Nasal doc
|syntax = contains(vector, item);
|source = {{simgear file|simgear/nasal/lib.c|l=249|t=Source}}
|text = Returns 1 (True) if the vector contains the specified item, or 0 (False) if not.
|param1 = vector
|param1text = The vector to search in.
|param2 = item
|param2text = The object to be searched for in the vector.
|example1 =
# Initialize a vector
var vec = ["element", "foo"];
print(contains(vec, "element") ? "Yes" : "No"); # This will print "Yes"
print(contains(vec, "element2") ? "Yes" : "No"); # This will print "No"
}}

===delete() ===
{{Nasal doc
|syntax = delete(hash, key);
|source = {{simgear file|simgear/nasal/lib.c|l=118|t=Source}}
|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.
|param1 = hash
|param1text = The hash from which to delete the key.
|param2 = key
|param2text = The scalar to be deleted, contained as a key in the hash.
|example1 =
# Initialize the hash
var hash = {
element1: "value1",
element2: "value2"
};
delete(hash, "element1"); # Delete element1
debug.dump(hash); # prints the hash, which is now minus element1
}}

===die()===
{{Nasal doc
|syntax = die(error);
|source = {{simgear file|simgear/nasal/lib.c|l=417|t=Source}}
|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()}}.
|param1 = error
|param1text = String describing the error.
:{{inote|This parameter is technically optional, but it is highly recommended to use it.}}
|example1 =
print("Will print");
die("Don't go any further!");
print("Won't print"); # Will not be printed because die() stops the process
}}

=== find()===
{{Nasal doc
|syntax = find(needle, haystack);
|source = {{simgear file|simgear/nasal/lib.c|l=586|t=Source}}
|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.
|param1 = needle
|param1text = String to search for.
|param2 = haystack
|param2text = String to search in.
|example1 = print(find("c", "abcdef")); # prints 2
|example2 = print(find("x", "abcdef")); # prints -1
|example3 = print(find("cd", "abcdef")); # prints 2
}}

===ghosttype()===
{{Nasal doc
|syntax = ghosttype(ghost);
|source = {{simgear file|simgear/nasal/lib.c|l=336|t=Source}}
|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.
|param1 = ghost
|param1text = Ghost to return a description for.
|example1 = print(ghosttype(airportinfo())); # prints "airport"
}}

===id()===
{{Nasal doc
|syntax = id(object);
|source = {{simgear file|simgear/nasal/lib.c|l=706|t=Source}}
|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.
|param1 = object
|param1text = Can be either of a string, a vector, a hash, a code, a function, or a ghost.
|example1 = print(id("A")); # prints "str:000000001624A590"
}}

===int() ===
{{Nasal doc
|syntax = int(number);
|source = {{simgear file|simgear/nasal/lib.c|l=125|t=Source}}
|text = Returns the integer part of the numeric value of the single argument, or <code>'''nil'''</code> if none exists.
|param1 = number
|param1text = Number or string with just a number in it to return an integer from.
|example1 = print(int(23)); # prints "23"
|example2 = print(int(23.123)); # prints "23"
|example3 = debug.dump(int("string")); # prints "nil"
}}

===keys()===
{{Nasal doc
|syntax = keys(hash);
|source = {{simgear file|simgear/nasal/lib.c|l=36|t=Source}}
|text = Returns a vector containing the list of keys found in the single hash argument.
|param1 = hash
|param1text = The hash to return the keys from.
|example1 =
# Initialize a hash
var hash = {
element1: "value",
element2: "value"
};
debug.dump(keys(hash)); # print the vector
}}

===left()===
{{Nasal doc
|syntax = left(string, length);
|source = {{simgear file|simgear/nasal/lib.c|l=214|t=Source}}
|version = 2.12
|commit = {{simgear commit|bd7163|t=commit}}
|text = Returns a substring of '''string''', starting from the left.
|param1 = string
|param1text = String to return part of.
|param2 = length
|param2text = Integer specifying the length of the substring to return.
|example1 = print(left("string", 2)); # prints "st"
}}

=== num()===
{{Nasal doc
|syntax = num(number);
|source = {{simgear file|simgear/nasal/lib.c|l=149|t=Source}}
|text = Returns the numerical value of the single string argument, or <code>'''nil'''</code> if none exists.
|param1 = number
|param1text = String with just a number in it to return a number from.
|example1 = print(num("23")); # prints "23"
|example2 = print(num("23.123")); # prints "23.123"
|example3 = debug.dump(num("string")); # prints "nil"
}}

===pop()===
{{Nasal doc
|syntax = pop(vector);
|source = {{simgear file|simgear/nasal/lib.c|l=85|t=Source}}
|text = Removes and returns the last element of the single vector argument, or <code>'''nil'''</code> if the vector is empty.
|param1 = vector
|param1text = Vector to remove an element from.
|example1 =
var vector = [1, 2, 3];
pop(vector);
debug.dump(vector); # prints "[1, 2]"
|example2 =
var vector = [1, 2, 3];
debug.dump(pop(vector)); # prints "3"
|example3 =
var vector = [];
debug.dump(pop(vector)); # prints "nil"
}}

=== range() ===
{{Nasal doc
|syntax = range([start, ]stop[, step]);
|source = {{simgear file|simgear/nasal/lib.c|l=756|t=Source}}
|text = Creates a vector of numbers starting from <code>start</code> (default 0) up to but not including <code>stop</code>, incremented by <code>step</code> (default 1). Note: To specify <code>step</code>, you must also provide <code>start</code>; otherwise the second argument is interpreted as <code>stop</code>.
|param1 = start
|param1text = Optional. The starting number of the sequence. Defaults to 0 if omitted. Required if you want to specify <code>step</code>.
|param2 = stop
|param2text = Required. The number at which to stop the sequence (not included).
|param3 = step
|param3text = Optional. The increment between each number in the sequence. Defaults to 1. Only valid if <code>start</code> is also specified.
|example1 =
var vec = range(5); # Creates a vector [0, 1, 2, 3, 4]
var vec = range(2, 5); # Creates a vector [2, 3, 4]
var vec = range(0, 10, 2); # Creates a vector [0, 2, 4, 6, 8]
var vec = range(0, 0); # Creates an empty vector []
var vec = range(0, 1); # Creates a vector [0]
}}

=== remove() ===
{{Nasal doc
|syntax = remove(vector, value);
|source = {{simgear file|simgear/nasal/lib.c|l=53|t=Source}}
|text = Removes all elements equal to the given value from a vector and returns the modified vector.
|param1 = vector
|param1text = The vector from which elements are to be removed.
|param2 = value
|param2text = A value to remove from the vector.
|example1 =
var vector = [1, 2, 3]; # Initialize the vector.
remove(vector, 2); # Remove the value 2 from the vector.
debug.dump(vector); # Print the contents of the vector: "[1, 3]".
|example2 =
var vector = ["text", "text", "text"]; # Initialize the vector.
remove(vector, "text"); # Remove the value "text" from the vector.
debug.dump(vector); # Print the contents of the vector: "[]".
}}

=== removeat() ===
{{Nasal doc
|syntax = removeat(vector, index);
|source = {{simgear file|simgear/nasal/lib.c|l=72|t=Source}}
|text = Removes the element at the specified index from the vector and returns it.
|param1 = vector
|param1text = The vector from which the element will be removed.
|param2 = index
|param2text = Index of the item to be deleted.
|example1 =
var vector = [1, 2, 3]; # Initialize the vector.
removeat(vector, 0); # Remove the index 0 from the vector.
debug.dump(vector); # Print the contents of the vector: "[2, 3]".
}}

===right()===
{{Nasal doc
|syntax = right(string, length);
|source = {{simgear file|simgear/nasal/lib.c|l=226|t=Source}}
|version = 2.12
|commit = {{simgear commit|bd7163|t=commit}}
|text = Returns a substring of '''string''', starting from the right.
|param1 = string
|param1text = String to return part of.
|param2 = length
|param2text = Integer specifying the length of the substring to return.
|example1 = print(right("string", 2)); # prints "ng"
}}

=== setsize()===
{{Nasal doc
|syntax = setsize(vector, size);
|source = {{simgear file|simgear/nasal/lib.c|l=91|t=Source}}
|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.
|param1 = vector
|param1text = The vector to be operated on.
|param2 = size
|param2text = The desired size of the vector in number of entries.
|example1 =
var vector = [1, 2, 3]; # Initialize a vector
setsize(vector, 4);
debug.dump(vector); # print the vector "[1, 2, 3, nil]"
|example2 =
var vector = [1, 2, 3]; # Initialize a vector
setsize(vector, 2);
debug.dump(vector); # print the vector "[1, 2]"
}}

===size()===
{{Nasal doc
|syntax = size(object);
|source = {{simgear file|simgear/nasal/lib.c|l=26|t=Source}}
|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>.
|param1 = object
|param1text = Object to find the size of. Must be a string, a vector or a hash.
|example1 =
var string = "string";
print(size(string)); # prints "6"
|example2 =
var vector = [1, 2, 3];
print(size(vector)); # prints "3"
|example3 =
var hash = {
element1: "value1",
element2: "value2",
element3: "value3"
};
print(size(hash)); # prints "3"
}}

=== sort()===
{{Nasal doc
|syntax = sort(vector, function);
|source = {{simgear file|simgear/nasal/lib.c|l=678|t=Source}}
|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.
|param1 = vector
|param1text = Input vector to sort.
|param2 = function
|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.
{{{!}} class="wikitable"
! Return value !! Meaning
{{!-}}
{{!}} less than 0 {{!!}} first argument should go before second argument
{{!-}}
{{!}} 0 {{!!}} first argument equals second argument
{{!-}}
{{!}} greater than 0 {{!!}} first argument should go after second argument
{{!}}}

|example1text = This example sorts elements from smallest to greatest.
|example1 =
var sort_rules = func(a, b) {
if (a < b) {
return -1; # A should before b in the returned vector
} elsif (a == b) {
return 0; # A is equivalent to b
} else {
return 1; # A should after b in the returned vector
}
}
debug.dump(sort([3, 2, 5, 6, 4, 1], sort_rules)); # prints "[1, 2, 3, 4, 5, 6]"
|example2text = This example sorts elements from greatest to smallest.
|example2 =
# Outputs the elements in reverse order (greatest to smallest)
var sort_rules = func(a, b) {
if (a < b) {
return 1; # -1 in the above example
} elsif (a == b) {
return 0;
} else {
return -1; # 1 in the above example
}
}
debug.dump(sort([3, 2, 5, 6, 4, 1], sort_rules)); # prints "[6, 5, 4, 3, 2, 1]"
|example3text = This example sorts a vector of strings (runways for example) from smallest to greatest.
|example3 =
var runways = ["09R", "27R", "26L", "09L", "15"];
var rwy = sort(runways, func(a, b) cmp(a, b));
debug.dump(rwy); # prints ['09L', '09R', '15', '26L', '27R']
}}

=== split()===
{{Nasal doc
|syntax = split(delimiter, string);
|source = {{simgear file|simgear/nasal/lib.c|l=596|t=Source}}
|text = Splits the input string into a vector of substrings bounded by occurrences of the delimiter substring. See [[Nasal_library/string#string.join(sep,list)|string.join()]].
|param1 = delimiter
|param1text = String that will split the substrings in the returned vector.
|param2 = string
|param2text = String to split up.
|example1 = debug.dump(split("cd", "abcdef")); # prints "['ab', 'ef']"
|example2 = debug.dump(split(".", "3.2.0")); # prints "[3, 2, 0]"
|example3 = debug.dump(split("/", "path/to/file")); # prints "['path', 'to', 'file']"
}}

===sprintf()===
{{Nasal doc
|syntax = <nowiki>sprintf(format[, arg[, arg, [...]]]);</nowiki>
|source = {{simgear file|simgear/nasal/lib.c|l=491|t=Source}}
|text = Creates and returns a string formatted using ANSI C {{func link|vsnprintf()|link=http://en.cppreference.com/w/c/io/vfprintf}} <ref>
{{Cite web
|url = http://sourceforge.net/p/flightgear/simgear/ci/next/tree/simgear/nasal/lib.c#l308
|title = fgdata/simgear/simgear/nasal/lib.c, line 308
|accessdate = October 2015
}}
</ref>. Below is a table of supported format specifiers.
{{{!}} class="wikitable" width="75%"
{{!}}+ %[flags][width][.precision]specifier
! colspan="2" {{!}} Flags
{{!-}}
! Flag !! Output
{{!-}}
{{!}} <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.
{{!-}}
{{!}} ''space'' {{!!}} Prefixes non-signed numbers with a space.
{{!-}}
{{!}} <code>-</code> {{!!}} Left-align the output of this placeholder (the default is to right-align the output) when the width option is specified.
{{!-}}
{{!}} <code>0</code> {{!!}} Use 0 instead of spaces to pad a field when the width option is specified.
{{!-}}
{{!}} <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.
{{!-}}
! colspan="2" {{!}} Width
{{!-}}
{{!}} 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.
{{!-}}
! colspan="2" {{!}} Precision
{{!-}}
{{!}} colspan="2" {{!}} Integer preceded by a dot specifying the number of decimal places to be written.
{{!-}}
! colspan="2" {{!}} Specifiers
{{!-}}
! Specifier !! Output
{{!-}}
{{!}} <code>d</code>, <code>i</code> {{!!}} Signed decimal number.
{{!-}}
{{!}} <code>s</code> {{!!}} A string
{{!-}}
{{!}} <code>%</code> {{!!}} Percent (%) character.
{{!-}}
{{!}} <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.
{{!-}}
{{!}} <code>o</code> {{!!}} Unsigned integer as an octal number.
{{!-}}
{{!}} <code>u</code> {{!!}} Unsigned decimal integer.
{{!-}}
{{!}} <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.
{{!-}}
{{!}} <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.
{{!-}}
{{!}} <code>f</code> {{!!}} Floating-point number, in fixed decimal notation, by default with 6 decimal places.
{{!-}}
{{!}} <code>F</code> {{!!}} Appears to be available<ref>
{{Cite web
|url = http://sourceforge.net/p/flightgear/simgear/ci/next/tree/simgear/nasal/lib.c#l389
|title = fgdata/simgear/simgear/nasal/lib.c, line 389
|accessdate = October 2015
}}
</ref>, but doesn't work.
{{!-}}
{{!}} <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.
{{!}}}

|param1 = format
|param1text = String specifying the format. Can be used with or without a format specifiers. See below for examples.
|param2 = arg
|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.

|example1 = print(sprintf("%i", 54)); # prints "54"
|example2 = print(sprintf("Pi = %+.10f", math.pi)); # prints "Pi = +3.1415926536"
|example3 =
print(sprintf("%6d", 23)); # prints " 23"
print(sprintf("%06d", 23)); # prints "000023"
|example4 =
var FGVer = getprop("/sim/version/flightgear");
print(sprintf("You have FlightGear v%s", FGVer)); # prints "You have FlightGear v<your version>"
|example5 =
print(sprintf("Hexadecimal 100000 = %X", 100000)); # prints "Hexadecimal 100000 = 186A0"
print(sprintf("Hexadecimal 100000 = %x", 100000)); # prints "Hexadecimal 100000 = 186a0"
|example6 = print(sprintf("Code 65 is %c", 65)); # prints "Code 65 is A"
|example7 =
print(sprintf("%e", 54)); # prints "5.400000e+001"
print(sprintf("%E", 54)); # prints "5.400000E+001"
|example8 = print(sprintf("%o", 54)); # prints "66"
|example9 = print(sprintf("50%% of 100 is %i", 100 / 2)); # prints "50% of 100 is 50"
|example10 =
print(sprintf("%.2f", 1.4)); # prints "1.40"
print(sprintf("%.1f", 1.4)); # prints "1.4"
print(sprintf("% 4.1f", 1.4)); # prints " 1.4"
print(sprintf("%04.1f", 1.4)); # prints "01.4"
print(sprintf("% 6.1f", 1.4)); # prints " 1.4"
print(sprintf("%06.1f", 1.4)); # prints "0001.4"
}}

===str()===
{{Nasal doc
|syntax = str(value);
|source = {{simgear file|simgear/nasal/lib.c|l=186|t=Source}}
|text = Convert given value (scalar) to string. If <code>value</code> is a number, it will be converted to a string. If <code>value</code> is a string, the same string will be returned. If <code>value</code> is not a scalar (hash, vector, nil), <code>nil</code> will be returned.
|param1 = value
|param1text = The value to convert to string.
|example1 =
var result = str(true); # result is a string "1"
var result = str(false); # result is a string "0"
var result = str(12); # result is a string "12"
var result = str(12.5); # result is a string "12.5"
var result = str(-12.5); # result is a string "-12.5"
var result = str("12.5"); # result is a string "12.5"
var result = str([1, 2]); # result is a nil
var result = str({ x: 0 }); # result is a nil
var result = str(nil); # result is a nil
}}

===streq()===
{{Nasal doc
|syntax = streq(a, b);
|source = {{simgear file|simgear/nasal/lib.c|l=164|t=Source}}
|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.}}
|param1 = a
|param1text = First argument for testing equality.
|param2 = b
|param2text = Second argument for testing equality.
|example1 = print(streq("0", "0")); # prints "1" (True)
|example2 =
print(0 == 0.0); # prints "1" (True)
print(streq("0", "0.0")); # prints "0" (False)
}}

===substr()===
{{Nasal doc
|syntax = substr(string, start [, length]);
|source = {{simgear file|simgear/nasal/lib.c|l=194|t=Source}}
|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).
|param1 = string
|param1text = String to return a substring from.
|param2 = start
|param2text = Integer specifying the start of a substring. Negative values specify a position from the end of the string.
|param3 = length
|param3text = Optional argument specifying the length of the substring. Defaults to the end of the string.
|example1 = print(substr("abcde", 1, 3)); # prints "bcd"
|example2 = print(substr("abcde", 1)); # prints "bcde"
|example3 = print(substr("abcde", 2, 1)); # prints "c"
|example4 = print(substr("abcde", -2)); # prints "de"
|example5 = print(substr("abcde", -3, 2)); # prints "cd"
}}

===subvec()===
{{Nasal doc
|syntax = subvec(vector, start[, length]);
|source = {{simgear file|simgear/nasal/lib.c|l=98|t=Source}}
|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).
|param1 = vector
|param1text = The vector to take the sub-vector from.
|param2 = start
|param2text = The starting point of the sub-vector within the given vector.
|param3 = length
|param3text = Optional argument specifying the length of the sub-vector, from the starting point.
'''Notes:'''
* Omitting the ''vector'' and ''start'' arguments is not an error (possibly it should be) but the return value is ''nil''.
* A negative ''start'' argument ''is'' an error. This seems wrong. Perhaps the language designer could comment.
* A value of ''start'' greater than ''size(vector)'' causes an error. A value equal to ''size(vector)'' returns an empty vector.
* 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.
|example1 =
var vector = [1, 2, 3];
debug.dump(subvec(vector, 0)); # prints "[1, 2, 3]"
|example2 =
var vector = [1, 2, 3];
debug.dump(subvec(vector, 1)); # prints "[2, 3]"
|example3 =
var vector = [1, 2, 3];
debug.dump(subvec(vector, 1, 1)); # prints "[2]"
}}

=== typeof()===
{{Nasal doc
|syntax = typeof(object);
|source = {{simgear file|simgear/nasal/lib.c|l=287|t=Source}}
|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.
|param1 = object
|param1text = Object to return the type of.
|example1 =
var object = nil;
print(typeof(object)); # prints "nil"
|example2 =
var object = "Hello world!";
print(typeof(object)); # prints "scalar"
|example3 =
var object = math.pi;
print(typeof(object)); # prints "scalar"
|example4 =
var object = [1, 2, 3];
print(typeof(object)); # prints "vector"
|example5 =
var object = {};
print(typeof(object)); # prints "hash"
|example6 =
var object = func {};
print(typeof(object)); # prints "func"
|example7 =
var object = airportinfo();
print(typeof(object)); # prints "ghost"
}}



==Extension functions==
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:
*{{flightgear file|src/Scripting/NasalPositioned.cxx}}
*{{flightgear file|src/Scripting/NasalSys.cxx}}
*{{fgdata file|Nasal/globals.nas}}

===abort()===
{{Nasal doc
|syntax = abort();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=565|t=Source}}
|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).
|example1text = This example will immediately stop FlightGear with an error, such as "FlightGear has stopped working."
|example1 = abort();
|example2text = For exiting FlightGear in a better way, please use the following code:
|example2 = fgcommand("exit");
}}

=== abs() ===
{{Nasal doc
|syntax = abs(number);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = This simple function returns the {{wikipedia|absolute value|noicon=1}} of the provided number.
|param1 = number
|param1text = This argument is required and should be a number.
|example1 = print(abs(1)); # prints "1"
|example2 = print(abs(-1)); # prints "1"
}}

===aircraftToCart() ===
This new function in FG 2017.2.1 takes coordinates in aircraft structural coordinate system, and translate them into geocentric coordinates.
Example for (5,6,7):
<syntaxhighlight lang="nasal">
var pos = aircraftToCart({x: -5, y: 6, z: -7});
var coord = geo.Coord.new();
coord.set_xyz(pos.x, pos.y, pos.z);
</syntaxhighlight>
Notice: x and z is inverted sign on purpose.
if you want lat. lon, alt from that, just call: (degrees and meters)

<syntaxhighlight lang="nasal">
coord.lat()
coord.lon()
coord.alt()
</syntaxhighlight>

===addcommand() ===
{{Nasal doc
|syntax = addcommand(name, code);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=659|t=Source}}
|version = 2.12
|commit = {{flightgear commit|7b663c|t=commit}}
|text = {{see also|Howto:Add new fgcommands to FlightGear}}

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.
|param1 = name
|param1text = This will become the name of the new fgcommand. Must be a string.
|param2 = code
|param2text = The code that will be executed when the fgcommand is run. Must be a function.
|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.
|example1 = addcommand("myFGCmd", func(node) {
print("fgcommand 'myFGCmd' has been run.");
props.dump( node );
});
fgcommand("myFGCmd", props.Node.new({foo:1, bar:2}) );
|example2text = This example demonstrates how parameters are defined in a new fgcommand.
|example2 = addcommand("myFGCmd", func(node){
print(node.getNode("number").getValue()); # prints the value of "number," which is 12
});
fgcommand("myFGCmd", props.Node.new({"number": 12}));
}}

===airportinfo()===
{{Nasal doc
|syntax = airportinfo();
airportinfo(type);
airportinfo(id);
airportinfo(lat, lon[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1024|t=Source}}
|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:
* '''parents''': A vector containing a hash of various functions to access information about the runway. These functions are:
** '''findBestRunwayForPos()''' return runway as ghost by given geo position, e.g. <code>var rwy = airportinfo().findBestRunwayForPos(geo.aircraft_position());</code>.
** '''runway()''' return runway as ghost by runway ID, e.g. <code>var rwy = airportinfo().runway("18R");</code>.
** '''runwaysWithoutReciprocals()''' return vector of runways as ghost.
** '''helipad()''' return helipad as ghost by helipad ID, e.g. <code>var heli = airportinfo().helipad("H19");</code>.
** '''tower()''' return hash with <code>lat</code>, <code>lon</code>, <code>elevation</code> fields.
** '''comms()''' return vector of hashes, each hash with <code>frequency</code> and <code>ident</code> fields.
** '''sids()''' return vector of strings with SID IDs.
** '''stars()''' return vector of strings with STAR IDs.
** '''getApproachList()''' return vector of string with approaches.
** '''parking()''' return vector of hashes, each hash with <code>lat</code>, <code>lon</code>, <code>elevation</code>, <code>name</code> fields.
** '''getSid()''' return SID as ghost, e.g. <code>var sid = airportinfo().getSid("SA1A");</code>.
** '''getStar()''' return STAR as ghost, e.g. <code>var star = airportinfo().getStar("KEILA1");</code>.
** '''getIAP()''' return IAP as ghost, e.g. <code>var iap = airportinfo().getIAP("ILS02");</code>.
** '''getApproach()''' return approach as ghost, e.g. <code>var approach = airportinfo().getApproach("ILS02");</code>.
** '''tostring()''' just return string "an airport ICAO".
** See also {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1902}}.
* '''lon''': Longitude of the location.
* '''lat''': Latitude of the location.
* '''has_metar''': True or false depending whether the airport has a [[METAR]] code defined for it.
* '''elevation''': Elevation of the location in metres.
* '''id''': ICAO code of the airport (or ID of the seaplane base/heliport).
* '''name''': Name of the airport/heliport/seaplane base.
* '''runways'''
** '''<runway name>'''
*** '''id''': Name of runway.
*** '''lat''': Latitude of the runway.
*** '''lon''': Longitude of the runway.
*** '''heading''': True heading of the runway.
*** '''length''': Length of the runway in metres.
*** '''width''': Width of the runway in metres.
*** '''surface''': Runway surface type.
*** '''threshold''': Length of the runway's {{wikipedia|displaced threshold}} in metres. Will return 0 if there is none.
*** '''stopway''': Length of the runway's stopway (the area before the threshold) in metres. Will return 0 if there is none.
*** '''reciprocal''': <code>runway</code> ghost of the reciprocal runway.
*** '''ils_frequency_mhz''': ILS frequency in megahertz.
*** '''ils''': <code>navaid</code> ghost of the ILS transmitter.
* '''helipads'''
** '''<helipad name>'''
*** '''id''': Name of helipad.
*** '''lat''': Latitude of the helipad.
*** '''lon''': Longitude of the helipad.
*** '''heading''': True heading of the helipad.
*** '''length''': Length of the helipad in metres.
*** '''width''': Width of the helipad in metres.
*** '''surface''': Helipad surface type.
* '''taxiways'''
** '''<taxiway name>'''
*** '''id''': Name of taxiway.
*** '''lat''': Latitude of the taxiway.
*** '''lon''': Longitude of the taxiway.
*** '''heading''': Heading of the taxiway.
*** '''length''': Length of the taxiway in metres.
*** '''width''': Width of the taxiway in metres.
*** '''surface''': Taxiway surface type.

Information is extracted in the same way as accessing members of a Nasal hash. For example:
<syntaxhighlight lang="nasal">
# prints to lengths of the runways of the nearest airport in feet and metres
var info = airportinfo();
print("-- Lengths of the runways at ", info.name, " (", info.id, ") --");
foreach(var rwy; keys(info.runways)){
print(rwy, ": ", math.round(info.runways[rwy].length * M2FT), " ft (", info.runways[rwy].length, " m)");
}
</syntaxhighlight>

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.
|param1 = id
|param1text = The {{wikipedia|International Civil Aviation Organization airport code|ICAO code|noicon=1}} of an airport to retrieve information about.
|param2 = type
|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).
: {{inote|Running this function without any parameters is equivalent to this:
: <syntaxhighlight lang="nasal">
airportinfo("airport");
</syntaxhighlight>
}}
|param3 = lat ''and'' lon
|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.
|example1 = var info = airportinfo();
print("Nearest airport: ", info.name, " (", info.id, ")"); # prints the name and ICAO code of the nearest airport
|example2 = var info = airportinfo("heliport");
print("Elevation of the nearest heliport: ", math.round(info.elevation * M2FT), " ft"); # prints the elevation and name of the nearest heliport
|example3 = var info = airportinfo("KSQL");
print("-- Runways of ", info.name, " (", info.id, "): --");
foreach(var rwy; keys(info.runways)) {
print(rwy); # prints the runways of KSQL
}
|example4 = var info = airportinfo(37.81909385, -122.4722484);
print("Coordinates of the nearest airport: ", info.lat, ", ", info.lon); # print the name and ICAO of the nearest airport to the Golden Gate Bridge
|example5 = var info = airportinfo(37.81909385, -122.4722484, "seaport");
print("Nearest seaplane base: ", info.name, " (", info.id, ")"); # print the name and ID of the nearest seaplane base to the Golden Gate Bridge
|example6text = This example prints the all information from an <code>airportinfo()</code> call.
|example6 = var info = airportinfo("KSFO");
print(info.name);
print(info.id);
print(info.lat);
print(info.lon);
print(info.has_metar);
print(info.elevation);
foreach(var rwy; keys(info.runways)){
print("-- ", rwy, " --");
print(info.runways[rwy].lat);
print(info.runways[rwy].lon);
print(info.runways[rwy].length);
print(info.runways[rwy].width);
print(info.runways[rwy].heading);
print(info.runways[rwy].stopway);
print(info.runways[rwy].threshold);
<nowiki>}</nowiki>
}}

===airwaysRoute() ===
{{Nasal doc
|syntax = airwaysRoute(start, end[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1933|t=Source}}
|text = {{see also|Nasal Flightplan}}
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.
|param1 = start
|param1text = Start waypoint, in the form of a waypoint ghost, such as that provided by {{func link|flightplan()}}.
|param2 = end
|param2text = Same as above.
|param3 = type
|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."
|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.
|example1 = var fp = flightplan();
var start = fp.getWP(0);
var end = fp.getWP(fp.getPlanSize() - 1);
var rt = airwaysRoute(start, end);
foreach(var wp; rt){
print(wp.wp_name); # print the waypoints in the computed route
}
|example2text = Exactly the same as above, but computes a low level path.
|example2 = var fp = flightplan();
var start = fp.getWP(0);
var end = fp.getWP(fp.getPlanSize() - 1);
var rt = airwaysRoute(start, end, "lowlevel");
foreach(var wp; rt){
print(wp.wp_name); # print the waypoints in the computed route
<nowiki>}</nowiki>
}}

===airway()===

{{Nasal doc
|syntax = airway(ident [, pos]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2644|t=Source}}
|text = {{see also|Nasal Flightplan}}
This function returns a ghost containing an airway of a specified id.
|param1 = ident
|param1text = a Positioned ghost (leg, navaid, airport) and so on, passed to the search function.
|param2 = pos
}}

===assert()===
{{Nasal doc
|syntax = assert(condition[, message]);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|version = 3.2
|commit = {{fgdata commit|8b16a7|t=commit}}
|text = Returns either true if the condition evaluates as true, or aborts with a {{func link|die()}} call, which can be customised.
|param1 = condition
|param1text = Condition to evaluate.
|param2 = message
|param2text = Optional message that will be used in any {{func link|die()}} call. Defaults to "assertion failed!"
|example1 = var a = 1;
var b = 2;
print(assert(a < b)); # prints "1" (true)
|example2 = var a = 1;
var b = 2;
assert(a > b, 'a is not greater than b'); # aborts with a custom error message
}}

===carttogeod()===
{{Nasal doc
|syntax = carttogeod(x, y, z);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=945|t=Source}}
|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>
|param1 = x
|param1text = Mandatory x-axis value, in metres.
|param2 = y
|param2text = Mandatory y-axis value, in metres.
|param3 = z
|param3text = Mandatory z-axis value, in metres.
|example1 = var (lat, lon, alt) = carttogeod(6378137, 0, 0); # point is the intersection of the prime meridian and equator.
print("Latitude: ", lat); # prints lat, lon and alt, which are all zero, see above
print("Longitude: ", lon);
print("Altitude: ", alt);
}}

===cmdarg()===
{{Nasal doc
|private = _cmdarg()
|syntax = cmdarg();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=513|t=Part 1}} {{!}} {{fgdata file|Nasal/globals.nas|t=Part 2}}
|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.
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:
* Bindings: This is needed so that the value of a joystick's axis can be accessed internally.
* 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).
* 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.
* 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>

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.

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.
|example1 = fgcommand("dialog-show", {"dialog-name": "cmdarg-demo"});
|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.
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>

<PropertyList>

<name>cmdarg-demo</name>
<layout>vbox</layout>

<text>
<label>Click "Close" to activate the demonstration (a message in the console).</label>
</text>

<button>
<legend>Close</legend>
<binding>
<command>nasal</command>
<script>print("Button binding root: '" ~ cmdarg().getPath() ~ "'");</script>
</binding>
<binding>
<command>dialog-close</command>
</binding>
</button>

</PropertyList>
</syntaxhighlight>
|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!"
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>

<PropertyList>

<name>cmdarg-demo</name>
<layout>vbox</layout>

<text>
<label>Click "Click me!" to activate the demonstration (the button's label will change).</label>
</text>

<button>
<legend>Click me!</legend>
<binding>
<command>nasal</command>
<script>change_label();</script>
</binding>
</button>

<button>
<legend>Close</legend>
<binding>
<command>dialog-close</command>
</binding>
</button>

<nasal>
<open><![CDATA[
var dlg_root = cmdarg();
var dlg_name = {"dialog-name": "cmdarg-demo"};
var change_label = func {
dlg_root.getNode("button[0]/legend").setValue("I've been changed!");
fgcommand("dialog-close", dlg_name);
fgcommand("dialog-show", dlg_name);
}
]]></open>
</nasal>

</PropertyList>
</syntaxhighlight>
|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]].
}}

===courseAndDistance()===
{{Nasal doc
|syntax = courseAndDistance(to);
courseAndDistance(from, to);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1668|t=Source}}
|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:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object with geodetic coordinates (cartesian coordinates will not be accepted)
|param1 = from
|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.
|param2 = to
|param2text = Like the first parameter, but defines the second point.
|example1text = This example demonstrates the usage of the function with the <code>airport</code> ghost type.
|example1 = var from = airportinfo("KSFO");
var to = airportinfo("KSQL");
var (course, dist) = courseAndDistance(from, to);
print(course); # prints course from KSFO to KSQL
print(dist); # prints distance in nm from KSFO to KSQL
|example2text = This example demonstrates the usage of the function with hashes containing ''lat'' and ''lon''.
|example2 = var from = {lat: 0, lon: 0};
var to = {lat: 1, lon: 1};
var (course, dist) = courseAndDistance(from, to);
print(course);
print(dist);
|example3text = This example demonstrates usage of a geo.Coord object.
|example3 = var from = geo.Coord.new().set_latlon(0, 0);
var to = geo.Coord.new().set_latlon(1, 1);
var (course, dist) = courseAndDistance(from, to);
print(course);
print(dist);
|example4text = This example demonstrates usage of differing parameter types.
|example4 = var from = airportinfo("KSFO");
var to = geo.Coord.new().set_latlon(0, 0);
var (course, dist) = courseAndDistance(from, to);
print(course);
print(dist);
|example5text = The same as above, but the other way round.
|example5 = var to = {lat: 1, lon: 1};
var (course, dist) = courseAndDistance(0, 0, to);
print(course);
print(dist);
|example6text = Usage of just one parameter.
|example6 = var dest = airportinfo("KSQL");
var (course, dist) = courseAndDistance(dest);
print("Turn to heading ", math.round(course), ". You have ", sprintf("%.2f", dist), " nm to go");
}}

===createFlightplan()===
{{Nasal doc
|syntax = createFlightplan(path);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2331|t=Source}}
|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.
|param1 = path
|param1text = Optional parameter defining the file from which a flightplan will be populated.
|example1 =
var path = getprop("/sim/fg-home") ~ "/Export/test.fgfp";
var flightplan = createFlightplan(path);
debug.dump(flightplan);
}}

===createDiscontinuity()===
{{Nasal doc
|syntax = createDiscontinuity();
|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.
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2045|t=Source}}
|version = 2016.1
|commit = {{flightgear commit|caead6|t=commit}}
}}
===createViaTo()===
{{Nasal doc
|syntax = createViaTo(airway, waypoint);
|text = Returns a <code>waypoint</code> ghost object. It represents a route "via '''airway''' to '''waypoint'''".
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2009|t=Source}}
|version = 2016.1
|commit = {{flightgear commit|caead6|t=commit}}
|param1 = airway
|param1text = The name of an airway.
|param2 = waypoint
|param2text = Must be in the airway and one of:
* The name of a waypoint.
* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, or <code>fix</code> ghost object.
}}
===createWP()===
{{Nasal doc
|syntax = createWP(pos, name[, flag]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1964|t=Source}}
|text = Creates a new waypoint ghost object.
|param1 = pos
|param1text = Dictates the position of the new waypoint. It can be one of the following:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. See example 4 below.
|param2 = name
|param2text = String that will become the name of the new waypoint.
|param3 = flag
|param3text = Optional string that will tell FlightGear what type of waypoint it is. Must be one of "sid," "star," "approach," "missed," or "pseudo."
|example1text = Creates a waypoint directly in front and 1 km away and appends it to the flight plan.
|example1 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);
var wp = createWP(pos, "NEWWP");
var fp = flightplan();
fp.appendWP(wp);
|example2 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);
var wp = createWP({lat: pos.lat(), lon: pos.lon()}, "NEWWP");
var fp = flightplan();
fp.appendWP(wp);
|example3 = var apt = airportinfo();
var wp = createWP(apt, "NEWWP");
var fp = flightplan();
fp.appendWP(wp);
|example4 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);
var wp = createWP(pos.lat(), pos.lon(), "NEWWP");
var fp = flightplan();
fp.appendWP(wp);
|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.
|example5 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);
var wp = createWP(pos, "NEWWP", "pseudo");
var fp = flightplan();
fp.appendWP(wp);
print(fp.getPlanSize());
fp.clearWPType("pseudo");
print(fp.getPlanSize());
}}

===createWPFrom()===
{{Nasal doc
|syntax = createWPFrom(object[, flag]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1989|t=Source}}
|text = Creates a new waypoint object from another object.
|param1 = object
|param1text = A ghost object. Must be a ghost type that is one of "airport," "navaid," "runway," or "fix."
|param2 = flag
|param2text = Optional string that will tell FlightGear what type of waypoint it is. Must be one of "sid," "star," "approach," "missed," or "pseudo."
|example1text = Creates a new waypoint and appends it to the flight plan.
|example1 = var apt = airportinfo("KSFO");
var wp = createWPFrom(apt);
var fp = flightplan();
fp.appendWP(wp);
|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.
|example2 = var apt = airportinfo("KSFO");
var wp = createWPFrom(apt, "pseudo");
print(wp.wp_name);
var fp = flightplan();
fp.appendWP(wp);
print(fp.getPlanSize());
fp.clearWPType("pseudo");
print(fp.getPlanSize());
}}

===defined()===
{{Nasal doc
|syntax = defined(symbol);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = Returns 1 (true) or 0 (false) depending on whether a variable exists.
|param1 = symbol
|param1text = A string that will be what the function searches for.
|example1 = var number = 12;
var check_exist = func {
print("Variable 'number' ", defined("number") == 1 ? "exists" : "does not exist"); # 'number' does exist
print("Variable 'number2' ", defined("number2") == 1 ? "exists" : "does not exist"); # 'number2' does not exist
}
check_exist();
}}

===directory()===
{{Nasal doc
|syntax = directory(path);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=572|t=Source}}
|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.
{{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.}}
|param1 = path
|param1text = Absolute file path.
|example1text = Gets the folders and files in [[$FG_ROOT]], and then removes the extra first two elements (see note above).
|example1 = var dir = directory(getprop("/sim/fg-root")); # get directory
dir = subvec(dir, 2); # strips off the first two elements
debug.dump(dir); # dump the vector
}}

===fgcommand()===
{{Nasal doc
|syntax = fgcommand(cmd[, args]);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=456|t=Part 1}} {{!}} {{fgdata file|Nasal/globals.nas|t=Part 2}}
|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.
|param1 = cmd
|param1text = String that is the name of the command that is to be run.
|param2 = args
|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).
|example1 = fgcommand("null"); # does nothing
|example2 = var args = props.Node.new({'script': 'print("Running fgcommand");'});
if (fgcommand("nasal", args)) { # prints "Running fgcommand" and then one of these print statements
print("Fgcommand succeeded");
} else {
print("Fgcommand encountered a problem");
}
|example3 = var args = { 'dialog-name': 'about' };
fgcommand("dialog-show", args); # shows the 'about' dialog
}}

===findAirportsByICAO() ===
{{Nasal doc
|syntax = findAirportsByICAO(search[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1096|t=Source}}
|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.
|param1 = search
|param1text = Search string for the function. Can either be a partial or a full ICAO code.
:{{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.}}
|param2 = type
|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."
|example1 = var apts = findAirportsByICAO("KSF"); # finds all airports matching "KSF"
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")"); # prints them
}
|example2 = var apts = findAirportsByICAO("SP0", "seaport"); # finds all seaplane bases matching "SP0"
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")"); # prints them
}
|example3 = var apt = findAirportsByICAO("XBET"); # one way to check if an airport does exist"
if (size(apt) == 0) {
print("Airport does not exist"); # this one will be printed
} else {
print("Airport does exist");
<nowiki>}</nowiki>
}}

===findAirportsWithinRange()===
{{Nasal doc
|syntax = findAirportsWithinRange([pos, ]range[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1066|t=Source}}
|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.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findAirportsWithinRange(lat, lon, range, type);</code>.
|param2 = range
|param2text = Mandatory number giving the range in nautical miles within which to search for airports/heliports/seaplane bases.only airports are searched for.
|param3 = type
|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."
|example1text = Searches for airports within 10 nm of [[KSFO]].
|example1 = var pos = airportinfo("KSFO");
var apts = findAirportsWithinRange(pos, 10);
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")");
}
|example2text = Searches for seaplane bases within 15 nm of [[KSFO]].
|example2 = var pos = airportinfo("KSFO");
var apts = findAirportsWithinRange(pos, 15, "seaport");
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")");
}
|example3text = Searches for airports within 10 nm of your current position.
|example3 = var apts = findAirportsWithinRange(10);
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")");
<nowiki>}</nowiki>
}}

===findCommByFrequencyMHz()===
findCommByFrequencyMHz([pos, ]freq[, type]);
[[sourceforge:p/flightgear/flightgear/ci/next/tree/src/Scripting/NasalPositioned.cxx#l1547|source]]

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.

'''pos'''

: Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findCommByFrequencyMHz(lat, lon, freq, type);</code>.
; freq
: Frequency, in megahertz, of the station to search for.
; type
: 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)
'''Example'''
var com = findCommByFrequencyMHz(123.6);
print("ID: ", com.id); # prints info about the comm station
print("Name: ", com.name);
print("Latitude: ", com.lat);
print("Longitude: ", com.lon);
print("Type: ", com.type);
print("Frequency: ", sprintf("%.3f", com.frequency), " Mhz");

=== findFixesByID() ===
{{Nasal doc
|syntax = findFixesByID([pos, ]id);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1627|t=Source}}
|text = Returns a vector containing <code>fix</code> ghost objects matching a given ID, sorted by range from a certain position.
{{inote|Fixes are (usually) also known as waypoints.}}
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findFixesByID(lat, lon, id);</code>.
|param2 = id
|param2text = Full or partial ID of the fix to search for.
:{{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.}}
|example1 = var fixes = findFixesByID("POGIC");
foreach(var fix; fixes){
print(fix.id, " - lat: ", fix.lat, " {{!}} lon: ", fix.lon); # prints information about POGIC
}
|example2 = var fix = findFixesByID("ZUNAP");
fix = fix[0];
var (course, dist) = courseAndDistance(fix);
print("Turn to heading ", math.round(course), ". You have ", sprintf("%.2f", dist), " nm to go to reach ", fixes[0].id);
}}

===findNavaidByFrequencyMHz()===
{{Nasal doc
|syntax = findNavaidByFrequencyMHz([pos, ]freq[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1547|t=Source}}
|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.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidByFrequencyMHz(lat, lon, freq, type);</code>.
|param2 = freq
|param2text = Frequency, in megahertz, of the navaid to search for.
|param3 = type
|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}}.
|example1 = var navaid = findNavaidByFrequencyMHz(109.55);
print("ID: ", navaid.id); # prints info about the navaid
print("Name: ", navaid.name);
print("Latitude: ", navaid.lat);
print("Longitude: ", navaid.lon);
print("Elevation (AMSL): ", navaid.elevation, " m");
print("Type: ", navaid.type);
print("Frequency: ", sprintf("%.3f", navaid.frequency / 100), " Mhz");
print("Range: ", navaid.range_nm, " nm");
if(navaid.course) print("Course: ", navaid.course);
}}

=== findNavaidsByFrequencyMHz()===
{{Nasal doc
|syntax = findNavaidsByFrequencyMHz([pos, ]freq[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1572|t=Source}}
|text = Returns a vector conatining <code>navaid</code> ghost objects for navaids that match a given frequency, sorted from nearest to furthest.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidsByFrequencyMHz(lat, lon, freq, type);</code>.
|param2 = freq
|param2text = Frequency, in megahertz, of the navaid to search for.
|param3 = type
|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}}.
|example1 = var navaids = findNavaidsByFrequencyMHz(109.55);
foreach(var navaid; navaids){
print("--");
print("ID: ", navaid.id); # prints info about the navaid
print("Name: ", navaid.name);
print("Latitude: ", navaid.lat);
print("Longitude: ", navaid.lon);
print("Elevation (AMSL): ", navaid.elevation, " m");
print("Type: ", navaid.type);
print("Frequency: ", sprintf("%.3f", navaid.frequency / 100), " Mhz");
print("Range: ", navaid.range_nm, " nm");
if(navaid.course) print("Course: ", navaid.course);
print("--");
<nowiki>}</nowiki>
}}

===findNavaidsByID()===
{{Nasal doc
|syntax = findNavaidsByID([pos, ]id[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1600|t=Source}}
|text = Returns a vector containing <code>navaid</code> ghost objects matching a given ID, sorted by range from a certain position.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidsByID(lat, lon, id, type);</code>.
|param2 = id
|param2text = Full or partial ID of the fix to search for.
:{{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.}}
|param3 = type
|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}}.
|example1 = var navaid = findNavaidsByID("MXW");
navaid = navaid[0];
print("ID: ", navaid.id); # prints info about 'MXW' (a VOR station)
print("Name: ", navaid.name);
print("Latitude: ", navaid.lat);
print("Longitude: ", navaid.lon);
print("Elevation (AMSL): ", navaid.elevation, " m");
print("Type: ", navaid.type);
print("Frequency: ", sprintf("%.3f", navaid.frequency / 1000), " Mhz");
print("Range: ", navaid.range_nm, " nm");
}}

===findNavaidsWithinRange()===
{{Nasal doc
|syntax = findNavaidsWithinRange([pos, ]range[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1518|t=Source}}
|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.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidsWithinRange(lat, lon, range, type);</code>.
|param2 = range
|param2text = Mandatory number giving the range in nautical miles within which to search for navaids.
|param3 = type
|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}}.
|example1text = Searches for navaids within 10 nm of [[KSFO]].
|example1 = var pos = airportinfo("KSFO");
var navs = findNavaidsWithinRange(pos, 10);
foreach(var nav; navs){
print(nav.name, " (ID: ", nav.id, ")");
}
|example2text = Searches for navaids within 10 nm of your current position.
|example2 = var navs = findNavaidsWithinRange(10);
foreach(var nav; navs){
print(nav.name, " (ID: ", nav.id, ")");
<nowiki>}</nowiki>
}}

===finddata()===
{{Nasal doc
|syntax = finddata(path);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=603|t=Source}}
|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]].
|param1 = path
|param1text = A relative path as a string.
|example1 = var path = finddata("Aircraft/Generic");
print(path); # prints the absolute path to $FG_ROOT/Aircraft/Generic
|example2 = var path = finddata("Airports");
print(path); # prints the absolute path to <TerraSync dir>/Airports
|example3 = var path = finddata("preferences.xml");
print(path); # prints the absolute path to $FG_ROOT/preferences.xml
}}

===flightplan()===
{{Nasal doc
|syntax = flightplan([path]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1738|t=Source}}
|text = {{see also|Nasal Flightplan}}
Returns a flight plan object, either one for the current flight plan, or one loaded from a given path.
|param1 = path
|param1text = Optional path to flight plan XML file.
|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.
|example1 = var fp = flightplan();
print(fp.getWP(fp.current).id);
|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>.
|example2 = var path = getprop('/sim/fg-home') ~ '/fp-demo.xml';
var fp = flightplan(path);
for(var i = 0; i < fp.getPlanSize(); i += 1){
print(fp.getWP(i).id);
<nowiki>}</nowiki>
}}

===geodinfo()===
{{Nasal doc
|syntax = geodinfo(lat, lon[, max_alt]);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=981|t=Source}}
|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}}):
* '''light_coverage:''' The coverage of a single point of light in m<sup>2</sup>.
* '''bumpiness:''' Normalized bumpiness factor for the material.
* '''load_resistance:''' The amount of pressure in N/m<sup>2</sup> the material can withstand without deformation.
* '''solid:''' 1 (true) or false (0) depending on whether the material is solid or not.
* '''names:''' Vector of scenery types (usually generated by [[TerraGear]]) that will use this material.
* '''friction_factor:''' Normalized friction factor of the material.
* '''rolling_friction:''' The rolling friction coefficient of the material.

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.
|param1 = lat
|param1text = Latitude, inputted as a number.
|param2 = lon
|param2text = Longitude, inputted as a number.
|param3 = max_alt
|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.
|example1text = Dumps information about ground underneath the aircraft.
|example1 = var pos = geo.aircraft_position();
var info = geodinfo(pos.lat(), pos.lon());
debug.dump(info);
|example2text = Prints whether the ground underneath the aircraft is solid or is water.
|example2 = var pos = geo.aircraft_position();
var info = geodinfo(pos.lat(), pos.lon());
if (info != nil and info[1] != nil) {
print("The ground underneath the aircraft is ", info[1].solid == 1 ? "solid." : "water.");
<nowiki>}</nowiki>
}}

=== geodtocart() ===
{{Nasal doc
|syntax = geodtocart(lat, lon, alt);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=962|t=Source}}
|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.
|param1 = lat
|param1text = Latitude, in degrees.
|param2 = lon
|param2text = Longitude, in degrees.
|param3 = alt
|param3text = Altitude, in metres.
|example1 = var (x, y, z) = geodtocart(0, 0, 0); # point is the intersection of the prime meridian and equator.
print("x: ", x); # prints "x: 6378137"
print("y: ", y); # prints "y: 0"
print("z: ", z); # prints "y: 0"
}}

=== get_cart_ground_intersection()===
Introduced in 2017.2.1, see [[Terrain Detection]].

===getprop()===
{{Nasal doc
|syntax = <nowiki>getprop(path[, path[, ...]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=345|t=Source}}
|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).
|param1 = path
|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.
|example1 = print("You have FlightGear v", getprop("/sim/version/flightgear")); # prints FlightGear version
|example2text = Note that the example below will only work in FlightGear 3.2 and above.
|example2 = for(var i = 0; i < 8; i += 1){
print("View #", i + 1, " is named ", getprop("/sim/view", i, "name"));
}
|example3text = Same as above, but is supported by all versions of FlightGear.
|example3 = for(var i = 0; i < 8; i += 1){
print("View #", i + 1, " is named ", getprop("/sim/view[" ~ i ~ "]/name"));
<nowiki>}</nowiki>
}}
==== See also====
{{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:
To get a Node rather than its value, use <code>props.globals.getNode()</code> - see [[Nasal_library/props]]. }}

===greatCircleMove()===
{{Nasal doc
|syntax = greatCircleMove([pos, ]course, dist);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1681|t=Source}}
|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).
|param1 = pos
|param1text = Optional position to calculate from. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost object.
:* A hash with ''lat'' and ''lon'' members
:* A <code>geo.Coord</code> object
:* A lat/lon pair, that is, a pair of numbers (latitude followed by longitude) separated by a comma: <code>greatCircleMove(lat,lon, ...)</code>.
|param2 = course
|param2text = Course to new set of coordinates, in degrees (in the range 0–360).
|param3 = dist
|param3text = Distance in nautical miles to the new set of coordinates.
|example1 = var pos = greatCircleMove(0,0, 0, 1);
debug.dump(pos); # print hash with coordinates
|example2 = var fix = findFixesByID("POGIC");
fix = fix[0];
var pos = greatCircleMove(fix, 45, 10);
debug.dump(pos); # print hash with coordinates
}}

===interpolate()===
{{Nasal doc
|private = _interpolate()
|syntax = <nowiki>interpolate(prop, value1, time1[, value2, time2[, ...]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=522|t=Part 1}} {{!}} {{fgdata file|Nasal/globals.nas|t=Part 2}}
|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.
|param1 = prop
|param1text = String or <code>props.Node</code> object that indicates a node in the property tree to be used.
|param2 = value''n''
|param2text = Target value to change the property to in the set amount of time. This should be a number.
|param3 = time''n''
|param3text = Time in seconds, that will be taken for the interpolation.
|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.
|example1 = setprop("/test", 0); # (re-)set property
interpolate("/test",
50, 5, # interpolate to 50 in 5 seconds
10, 2, # interpolate to 10 in 2 seconds
0, 5); # interpolate to 0 in 5 seconds
|example2 = # Apply the left brake at 20% per second
var prop = "controls/gear/brake-left";
var dist = 1 - getprop(prop);
if (dist == 1) {
interpolate(prop, 1, dist / 0.2);
<nowiki>}</nowiki>
}}

===isa()===
{{Nasal doc
|syntax = isa(object, class);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|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.
|param1 = object
|param1text = Object to check.
|param2 = class
|param2text = Class/object to check that '''object''' inherits from or is an instance of.
|example1 = var coord = geo.Coord.new();
if(isa(coord, geo.Coord)){
print("Variable 'coord' is an instance of class 'geo.Coord'"); # this one will be printed
} else {
print("Variable 'coord' is not an instance of class 'geo.Coord'");
}
|example2 = var coord = geo.Coord.new();
if(isa(coord, props.Node)){
print("Variable 'coord' is an instance of class 'props.Node'");
} else {
print("Variable 'coord' is not an instance of class 'props.Node'"); # this one will be printed
}
|example3text = The example below demonstrates checking of inheritance.
|example3 = var Const = {
constant: 2,
getConst: func {
return me.constant;
}
};

var Add = {
new: func {
return { parents: [Add, Const] };
},

addToConst: func(a){
return a * me.getConst();
}
};

var m = Add.new();
print(m.addToConst(4));

if(isa(m, Add)) print("Variable 'm' is an instance of class 'Add'"); # will be printed
if(isa(m, Const)) print("Variable 'm' is an instance of class 'Const'"); # will also be printed
}}

===logprint()===
{{Nasal doc
|syntax = <nowiki>logprint(priority[, msg[, msg[, ...]]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=431|t=Source}}
|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}}.
|param1 = priority
|param1text = Number specifying the priority level of the outputted message:
:{{{!}} class="wikitable"
! Number !! Debug type
{{!-}}
{{!}} 1 {{!!}} Bulk
{{!-}}
{{!}} 2 {{!!}} Debug
{{!-}}
{{!}} 3 {{!!}} Info
{{!-}}
{{!}} 4 {{!!}} Warn
{{!-}}
{{!}} 5 {{!!}} Alert
{{!}}}
|param2 = msg
|param2text = The message. There is no limit to the arguments you give give. They will be concatenated together before logging.
|example1 = # logs the value of pi to three decimal places with log level 3
logprint(3, "pi = ", sprintf("%.3f", math.pi));
|example2 = logprint(5, "Alert! This is an important message!");
}}
{{note|
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:

LOG_BULK, LOG_WARN, LOG_DEBUG, LOG_INFO, LOG_ALERT, DEV_WARN, DEV_ALERT }}

===magvar() ===
{{Nasal doc
|syntax = magvar([pos]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1642|t=Source}}
|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.
{{{!}} class="wikitable"
! FlightGear versions !! Model !! Reference date
{{!-}}
{{!}} 3.6 and above {{!!}} {{wikipedia|World Magnetic Model}} (WMM) 2015 {{!!}} 1 January 2015
{{!-}}
{{!}} 0.9.11-pre1 to 3.4 {{!!}} WMM 2005 {{!!}} 1 January 2005
{{!-}}
{{!}} 0.7.3 to 0.9.10 {{!!}} WMM 2000 {{!!}} 1 January 2000
{{!}}}
|param1 = pos
|param1text = Optional position to calculate from. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost object.
:* A hash with ''lat'' and ''lon'' members
:* A <code>geo.Coord</code> object
:* A lat/lon pair, that is, a pair of numbers (latitude followed by longitude) separated by a comma: <code>magvar(lat,lon)</code>.
|example1 = print(magvar(0, 0)); # prints the magnetic variation at 0, 0
}}

===maketimer() ===
{{Nasal doc
|syntax = maketimer(interval[, self], function);
|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}}
|version = 2.12
|commit = {{flightgear commit|ab939f|t=commit}}
|text = Returns a timer object containing the following methods and members:
* '''start()''': Starts the timer.
* '''stop()''': Stops the timer.
* '''restart(interval)''': Restarts the timer with the given interval.
* '''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).
* '''isRunning''': Read-only bool telling whether the timer is currently running.
* '''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.
Unlike {{func link|settimer()}}, which it replaces, <code>maketimer()</code> provides more control over the timer. In addition, it can help reduce memory usage.
|param1 = interval
|param1text = Interval in seconds for the timer.
|param2 = self
|param2text = Optional parameter specifying what any <code>'''me'''</code> references in the function being called will refer to.
|param3 = function
|param3text = Function to be called at the given interval.
|example1 = var timer = maketimer(1, func(){
print("Hello, World!"); # print "Hello, World!" once every second (call timer.stop() to stop it)
});
timer.start();
|example2 = var timer = maketimer(1, math, func(){
print(me.math); # 'me' reference is the 'math' namespace
});
timer.singleShot = 1; # timer will only be run once
timer.start();
|example3 = var timer = maketimer(1, func(){
print("Hello, World!"); # print "Hello, World!" once every second (call timer.stop() to stop it)
});
timer.start();
print(timer.isRunning); # prints 1
|example4text = In the example below, "Hello, World!" will be printed after one second the first time, and after two seconds thereafter.
|example4 = var update = func(){
print("Hello, World!");
timer.restart(2); # restarts the timer with a two second interval
}

var timer = maketimer(1, update);
timer.singleShot = 1;
timer.start();
}}

===maketimestamp()===
{{Nasal doc
|syntax = maketimestamp()
|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}}
|version = 2019.2
|commit = {{flightgear commit|7db06300|t=commit}}
|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:
* '''stamp()''': Resets the timing operation. Call this first.
* '''elapsedMSec()''': returns number of milliseconds elapsed since stamp() called. Resolution may vary depending on platform but is usually at least millisecond accuracy.
* '''elapsedUSec()''': returns number of microseconds elapsed since stamp() called. Resolution may vary depending on platform but is usually at least millisecond accuracy.
|
|example1text = In the example below the number of milliseconds elapsed will be printed.
|example1 = var timestamp = maketimestamp();
timestamp.stamp();
print(timestamp.elapsedMSec(), "ms elapsed");
print(timestamp.elapsedMSec(), "ms elapsed");
}}

===md5()===
{{Nasal doc
|syntax = md5(string);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=758|t=Source}}
|version = 3.2
|commit = {{flightgear commit|cfbf9e|t=commit}}
|text = Returns a the {{wikipedia|MD5}} hash (as a string) of the inputted string.
|param1 = string
|param1text = String the generate the hash of. Mandatory.
|example1text = The below code should output <code>65a8e27d8879283831b664bd8b7f0ad4</code>.
|example1 = print(md5("Hello, World!"));
}}

===navinfo()===
{{Nasal doc
|syntax = navinfo(lat, lon, type, id);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1453|t=Source}}
|text = Returns vector <code>navaid</code> ghost objects matching the given '''type''' and '''id''' or <code>'''nil'''</code> on error.
|param1 = lat ''and'' lon
|param1text = If given, the returned navaids will be put into order of ascending distance from the location.
|param2 = type
|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."
|param3 = id
|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.
|example1 = navinfo("vor"); # returns all VORs
|example2 = navinfo("HAM"); # return all navaids whose names start with "HAM"
|example3 = navinfo("vor", "HAM"); # return all VORs whose names start with "HAM"
|example4 = navinfo(34,48,"vor","HAM"); # return all VORs whose names start with "HAM" and sorted by distance relative to 34°, 48°
}}

===parse_markdown()===
{{Nasal doc
|syntax = parse_markdown(markdown);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=745|t=Part 1}} {{!}} {{simgear file|simgear/misc/SimpleMarkdown.cxx|t=Part 2}}
|version = 3.2
|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:
* It strips whitespace from the beginning of the string.
* It supports [http://daringfireball.net/projects/markdown/syntax#p paragraphs and line breaks].
* It collapses whitespace.
* It converts unordered [http://daringfireball.net/projects/markdown/syntax#list lists] to use a bullet character (•). 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.
|param1 = markdown
|param1text = String containing Markdown to be parsed.
|example1text =
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>).
<syntaxhighlight lang="xml" highlight="41-50">
<?xml version="1.0" encoding="UTF-8"?>

<PropertyList>

<name>test</name>
<layout>vbox</layout>

<group>
<layout>hbox</layout>

<empty>
<stretch>true</stretch>
</empty>

<text>
<label>parse_markdown() test dialog</label>
</text>

<empty>
<stretch>true</stretch>
</empty>

<button>
<legend></legend>
<pref-width>16</pref-width>
<pref-height>16</pref-height>
<binding>
<command>dialog-close</command>
</binding>
</button>

</group>

<canvas>
<name>Canvas plot</name>
<stretch>true</stretch>
<pref-width>400</pref-width>
<pref-height>300</pref-height>
<nasal>
<load><![CDATA[
var text = 'Items:
* apples
* oranges
* pears

Some text.
Some more items:
* apples
* oranges
* pears';

var parsed = parse_markdown(text);

var root_canvas = canvas.get(cmdarg());
root_canvas.setColorBackground(255, 255, 255);
var root = root_canvas.createGroup();

var text_dis = root.createChild("text")
.setText(parsed)
.setTranslation(5, 5)
.setFont("LiberationFonts\LiberationSans-Regular.ttf")
.setFontSize(15)
.setColor(0, 0, 0)
.setDrawMode(canvas.Text.TEXT)
.setAlignment("left-top");
]]></load>
</nasal>
</canvas>

</PropertyList>
</syntaxhighlight>
|example1 = fgcommand("dialog-show", {"dialog-name": "test"});
|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.
|example2 = <nowiki>var markdown = 'Items:
* apples
* oranges
* pears

Some text.
Some more items:
* apples
* oranges
* pears';

var parsed = parse_markdown(markdown);

debug.dump(parsed);

var path = string.normpath(getprop("/sim/fg-home") ~ '/Export/parse_markdown()-test.html');

var file = io.open(path, "w");

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>";

io.write(file, html);
io.close(file);
print("Done, file ready for viewing (" ~ path ~ ")");</nowiki>
}}

===parsexml()===
{{Nasal doc
|syntax = <nowiki>parsexml(path[, start[, end[, data[, pro_ins]]]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=710|t=Source}}
|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.
|param1 = path
|param1text = Mandatory absolute path to the XML file to be parsed.
|param2 = start
|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.
|param3 = end
|param3text = Optional callback function that will be called for every ending tag. The function should take one argument: the tag name.
|param4 = data
|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.
|param5 = pro_ins
|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.
|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.
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>

<?xml-stylesheet type="text/xsl" href="style.xsl"?>

<foo>
<blah type="string"><![CDATA[ <sender>John Smith</sender> ]]></blah>
<blah2 type="string">Orange & lemons</blah2>
</foo>
</syntaxhighlight>
|example1 = var start = func(name, attr){
print("Starting tag: '", name, "'");
foreach(var a; keys(attr)){
print("\twith attribute ", a, '="', attr[a], '"');
}
}

var end = func(name){
print("Ending tag: '", name, "'");
}

var data = func(data){
print("Data = '", data, "'");
}

var pro_instr = func(target, data){
print("Processing instruction: target = '", target, "', data = '", data, "'");
}

parsexml(getprop("/sim/fg-home") ~ '/Export/demo.xml', start, end, data, pro_instr);
}}

===print()===
{{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.

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>}}

{{Nasal doc
|syntax = <nowiki>print(data[, data[, ...]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=415|t=Source}}
|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.
|param1 = data
|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.
|example1 = print("Just", " a ", "test"); # prints "Just a test"
|example2 = print("pi = ", math.pi); # prints "pi = 3.141592..."
}}

=== printf() ===
{{Nasal doc
|syntax = <nowiki>printf(format[, arg[, arg, [...]]]);</nowiki>
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|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>).
|example1 = printf("In hexadecimal, 100000 = %X", 186A0); # prints "In hexadecimal, 100000 = 186A0"
}}

===printlog()===
{{caution|This function is deprecated and doesn't work. Please use the new one {{func link|logprint()}}.}}
{{Nasal doc
|syntax = <nowiki>printlog(level, data[, data[, ...]]);</nowiki>
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|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.
|param1 = level
|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.
|param2 = data
|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.
|example1 = printlog("alert", "This is an alert"); # message will be printed
|example2 = printlog("info", "Just informing you about something"); # message will be printed only if log level is set to "info" or less
}}

===rand()===
{{Nasal doc
|syntax = rand();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=554|t=Source}}
|text = Returns a random floating point number between 0 (inclusive) and 1 (exclusive). It takes no arguments.
|example1 = print(rand()); # prints random number
}}

===registerFlightPlanDelegate()===
{{Nasal doc
|syntax = registerFlightPlanDelegate(init_func);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1879|t=Source}}
|text = Registers a flight plan delegate. See <tt>''{{fgdata file|Nasal/route_manager.nas|t=$FG_ROOT/Nasal/route_manager.nas}}''</tt> for examples.
|param1 = init_func
|param1text = Initialization function which will be called during FlightGear's startup.
}}
===removecommand()===
{{Nasal doc
|syntax = removecommand(cmd);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=668|t=Source}}
|text = Removes the given fgcommand. Returns <code>'''nil'''</code>.
{{caution|This will remove '''any''' [[fgcommands|fgcommand]], even those implemented in C++, so use with caution!}}
|param1 = cmd
|param1text = String specifying the name of the command to remove.
|example1 = addcommand("hello", func(){
print("Hello");
});
fgcommand("hello"); # "Hello" will be printed
removecommand("hello"); # removes it
}}

===removelistener()===
{{Nasal doc
|syntax = removelistener(id);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=1384|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=506|t=Part 2}}
|text = Removes and deactivates the given listener and returns the number of listeners left or <code>'''nil'''</code> on error.
{{note|It is good practice to remove listeners when they are not required anymore. This prevents the listeners reducing FlightGear's run performance.}}
|param1 = id
|param1text = ID of listener as returned by {{func link|setlistener()}}.
|example1 = var ls = setlistener("/sim/test", func(){
print("Property '/sim/test' has been changed");
});
setprop("/sim/test", "blah"); # trigger listener
var rem = removelistener(ls); # remove listener
print("There are ", rem, " listeners remaining");
}}

===resolvepath()===
{{Nasal doc
|syntax = resolvepath(path);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=604|t=Source}}
|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.
|param1 = path
|param1text = Relative path to be completed.
|example1 = print(resolvepath("Nasal/globals.nas")); # prints the equivalent of $FG_ROOT/Nasal/globals.nas
|example2 = print(resolvepath("blah")); # prints nothing; could not be resolved
|example3 = var file_path = resolvepath("Aircraft/SenecaII/some-file");
if (file_path != ""){
gui.popupTip("some-file found", 2);
} else {
gui.popupTip("some-file not found", 2);
<nowiki>}</nowiki>
}}

===setlistener()===
{{Nasal doc
|syntax = <nowiki>setlistener(node, code[, init[, type]]);</nowiki>
|private = _setlistener()
|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.''
|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()}}.
{{note|Listeners are known to be a source of resource leaks. To avoid this, please take measures such as:
* Using {{func link|removelistener()}} when they are not needed any more.
* Using a single initialization listener.
* Avoiding tying listeners to properties that are rapidly updated (e.g., many times per frame).
}}
|param1 = node
|param1text = Mandatory string or <code>props.Node</code> object pointing to a property in the [[Property Tree]].
|param2 = code
|param2text = Mandatory callback function to execute when the listener is triggered. The function can take up to four arguments in the following order:
* '''changed''': a <code>props.Node</code> object pointing to the changed node.
* '''listen''': a <code>props.Node</code> object pointing to the listened-to node. Note that this argument maybe different depending on the '''type'''.
* '''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.
* '''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.
|param3 = init
|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).
|param4 = type
|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.
|example1 = var prop = props.globals.initNode("/sim/test", "", "STRING"); # create property
var id = setlistener("/sim/test", func(n){ # create listener
print("Value: ", n.getValue());
});
setprop("/sim/test", "blah"); # trigger listener
removelistener(id); # remove listener
prop.remove(); # remove property
}}

===setprop()===
{{Nasal doc
|syntax = <nowiki>setprop(path[, path[, ...]], value);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=385|t=Source}}
|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.
{{note|If you want to remove a property, you will have to use one of the <code>props</code> helpers:
<syntaxhighlight lang="nasal">
props.globals.getNode("foo/bar").remove(); # take out the complete node
props.globals.getNode("foo").removeChild("bar"); # take out a certain child node
</syntaxhighlight>
}}
|param1 = path
|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.
|param2 = value
|param2text = Value to write to the given property. Must be either a string or a number.
|example1 = setprop("/sim/demo", "This is a demo");
|example2text = Note that the example below will only work in FlightGear 3.2 and above.
|example2 = for(var i = 0; i < 3; i += 1){
setprop("/sim/demo", i, "Demo #" ~ i));
}
|example3text = Same as above, but is supported by all versions of FlightGear.
|example3 = for(var i = 0; i < 3; i += 1){
setprop("/sim/demo[" ~ i ~ "]", "Demo #" ~ i));
<nowiki>}</nowiki>
}}
====See also====
{{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:
To get a Node rather than its value, use <code>props.globals.getNode()</code> - see [[Nasal_library/props]]. }}

===settimer() ===
{{Nasal doc
|syntax = settimer(function, delta[, realtime]);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=499|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=1286|t=Part 2}}
|text = Runs the given function a specified amount of seconds after the current time. Returns <code>'''nil'''</code>.
{{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.}}
|param1 = function
|param1text = Mandatory function that will be called. It may be necessary to enclose code in an anonymous function (see example).
|param2 = delta
|param2text = Mandatory amount of time in seconds after which the function will be called.
|param3 = realtime
|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.
|example1 = var myFunc = func(){
print("Hello");
}

settimer(myFunc, 2); # runs myFunc after 2 seconds
|example2 = var sqr = func(a){
return a * a;
}

settimer(func(){
print(sqr(2)); # will print 4 after 2 seconds
}, 2);
}}

===srand() ===
{{Nasal doc
|syntax = srand();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=559|t=Source}}
|text = Makes the pseudorandom number generator (see {{func link|rand()}}) generate a new {{wikipedia|random seed|noicon=1}} based on time. Returns 0.
}}
===systime()===
{{Nasal doc
|syntax = systime();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=770|t=Source}}
|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).
{{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]}}
|example1 = print("Unix time: ", systime()); # prints Unix time
|example2 = var myFunc = func(){
for(var i = 0; i <= 10; i += 1){
print("Interation #", i);
}
}
var t = systime(); # record time
myFunc(); # run function
var t2 = systime(); # record new time
print("myFunc() took ", t2 - t, " seconds"); # print result
}}

===thisfunc()===
{{Nasal doc
|syntax = thisfunc();
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = Returns the function from which this function is called. This allows a function to reliably and safely call itself from within a closure.
|example1 = var stringify_vec = func(input){
if (typeof(input) == "scalar"){
return sprintf("%s", input);
} elsif (typeof(input) == "vector") {
if (size(input) == 0) return "[]";
var this = thisfunc();
var buffer = "[";
for(var i = 0; i < size(input); i += 1){
buffer ~= this(input[i]);
if (i == size(input) - 1) {
buffer ~= "]";
} else {
buffer ~= ", ";
}
}
return buffer;
} else {
die("stringify_vec(): Error! Invalid input. Must be a vector or scalar");
}
}

var test_vec = ["a", "b", "c", [1, 2, 3], "d"];
debug.dump(stringify_vec(test_vec)); # prints "[a, b, c, [1, 2, 3], d]"
test_vec = [];
debug.dump(stringify_vec(test_vec)); # prints "[]"
test_vec = {};
debug.dump(stringify_vec(test_vec)); # will throw an error
}}

===tileIndex() ===
{{Nasal doc
|syntax = tileIndex();
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1720|t=Source}}
|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>.
|example1 = print(tileIndex()); # print index
}}

=== tilePath()===
{{Nasal doc
|syntax = tilePath();
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1712|t=Source}}
|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>.
|example1 = print(tilePath()); # print path
}}

=== values()===
{{Nasal doc
|syntax = values(hash);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = Returns a vector containing the values of the given hash.
|param1 = hash
|param1text = Mandatory hash to get the values of.
|example1 = var hash = {
"a": 1,
"b": 2,
"c": 3
};

foreach(var val; values(hash)){
print(val);
}
|example2text = The below example does exactly the same thing as the above example, but does not use <code>values()</code>:
|example2 = var hash = {
"a": 1,
"b": 2,
"c": 3
};

foreach(var key; keys(hash)){
print(hash[key]);
<nowiki>}</nowiki>
}}

==Extension functions new in FG 2020.1 ==
The following functions have been added to the nasal core library and will be released with FlightGear version 2020.1.
Before the release they are available in the development branch "next".

===isfunc()===
Returns 1 if type or argument is a function, otherwise 0.

===isghost()===
Returns 1 if type or argument is a ghost, otherwise 0.

=== ishash()===
Returns 1 if type or argument is a hash, otherwise 0.

===isint()===
{{Nasal doc
|syntax = isint(x);
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}
|text = Returns 1 if argument has a numeric value and x == floor(x), e.g. integer.
}}

===isnum()===
{{Nasal doc
|syntax = isnum(x);
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}
|text = Returns 1 if typeof(x) is "scalar" and x has a numeric value otherwise 0.
}}

===isscalar()===
{{Nasal doc
|syntax = isscalar(x);
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}
|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 "~".
|example1 = var a = "foo";
var b=42;
if (isscalar(a) and isscalar(b)) print(a~b);
if (isstr(a)) print("a is a string");
if (isint(b)) print("b is an integer");
# if (isscalar(a))... is equivalent to if (typeof(a) == "scalar")...
}}

===isstr()===
Returns 1 if type or argument is a string, otherwise 0.

===isvec()===
Returns 1 if type or argument is a vector, otherwise 0.

===vecindex()===
{{Nasal doc
|syntax = vecindex(vector, value);
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}
|text = Returns the index of value or nil, if value is not found in vector.
|example1=
var myvector = ["apple", "bananna", "coconut"];
# to check if a vector contains a certain value compare vecindex to nil
if (vecindex(myvector, "apple") != nil) {
print("found apple");
}
# WARNING: this will not work as desired because index is 0
if (vecindex(myvector, "apple")) {
print("found apple");
<nowiki>}</nowiki>

}}

==Variables==
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}}.

===D2R===
{{Nasal doc
|syntax = var radians = degrees * D2R;
|text = Converts an angle from degrees to radians when multiplied by the angle in degrees. Equal to <code>π / 180</code>.
}}
===FPS2KT===
{{Nasal doc
|syntax = var knots = feet_per_second * FPS2KT;
|text = Converts a velocity from feet per second to knots when multiplied by the velocity in feet per second. Approximately equal to 0.5925.
}}
===FT2M===
{{Nasal doc
|syntax = var metres = feet * FT2M;
|text = Converts a length from feet to metres when multiplied by the length in feet. Equal to 0.3048.
}}
===GAL2L ===
{{Nasal doc
|syntax = var litres = gallons * GAL2L;
|text = Converts a volume from US liquid gallons to litres when multiplied by the volume in gallons. Approximately equal to 3.7854.
}}
===IN2M===
{{Nasal doc
|syntax = var metres = inches * IN2M;
|text = Converts a length from inches to metres when multiplied by the length in inches. Equal to 0.0254.
}}
===KG2LB===
{{Nasal doc
|syntax = var pounds = kilograms * KG2LB;
|text = Converts a mass from kilograms to pounds when multiplied by the mass in kilograms. Approximately equal to 2.2046.
}}
===KT2FPS===
{{Nasal doc
|syntax = var feet_per_second = knots * KT2FPS;
|text = Converts a velocity from knots to feet per second when multiplied by the velocity in knots. Approximately equal to 1.6878.
}}
===KT2MPS===
{{Nasal doc
|syntax = var metres_per_second = knots * KT2MPS;
|text = Converts a velocity from knots to metres per second when multiplied by the velocity in knots. Approximately equal to 0.5144.
}}
===L2GAL===
{{Nasal doc
|syntax = var gallons = litres * L2GAL;
|text = Converts a volume from litres to US liquid gallons when multiplied by the volume in litres. Approximately equal to 0.2642.
}}
===LB2KG===
{{Nasal doc
|syntax = var kilograms = pounds * LB2KG;
|text = Converts a mass from pounds to kilograms when multiplied by the mass in pounds. Approximately equal to 0.4536.
}}
===M2FT ===
{{Nasal doc
|syntax = var feet = metres * M2FT;
|text = Converts a length from metres to feet when multiplied by the length in metres. Approximately equal to 3.2808.
}}
===M2IN===
{{Nasal doc
|syntax = var inches = metres * M2IN;
|text = Converts a length from metres to inches when multiplied by the length in metres. Approximately equal to 39.3701.
}}
===M2NM ===
{{Nasal doc
|syntax = var nautical_miles = metres * M2NM;
|text = Converts a length from metres to nautical miles when multiplied by the length in metres. Approximately equal to 0.00054.
}}
===MPS2KT ===
{{Nasal doc
|syntax = var knots = metres_per_second * MPS2KT;
|text = Converts a velocity from metres per second to knots when multiplied by the velocity in metres per second. Approximately equal to 1.9438.
}}
===NM2M ===
{{Nasal doc
|syntax = var metres = nautical_miles * NM2M;
|text = Converts a length from nautical miles to metres when multiplied by the length in nautical miles. Equal to 1,852.
}}
===R2D===
{{Nasal doc
|syntax = var degrees = radians * R2D;
|text = Converts an angle from radians to degrees when multiplied by the angle in radians. Equal to <code>180 / π</code>.
}}

{{Appendix}}

{{Nasal namespaces}}

Nasal library

2025-12-04T12:46:17Z

PlayeRom: /* closure() */

{{Nasal Navigation|nocat=1}}
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:
* {{flightgear file|src/Scripting}}
* {{simgear file|simgear/nasal}}

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]].

{{tip|Copy & paste the examples into your [[Nasal Console]] and execute them to see what they do.|width=70%}}

== Core library functions ==
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:
* http://plausible.org/nasal/lib.html ([http://web.archive.org/web/20101010094553/http://plausible.org/nasal/lib.html archive])
* {{simgear file|simgear/nasal/lib.c}} ([http://sourceforge.net/p/flightgear/simgear/ci/next/log/?path=/simgear/nasal/lib.c history])

=== append() ===
{{Nasal doc
|syntax = append(vector, element[, element[, ...]]);
|source = {{simgear file|simgear/nasal/lib.c|l=45|t=Source}}
|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.
|param1 = vector
|param1text = The vector to which the arguments will be appended.
|param2 = element
|param2text = An element to be added to the vector.
|example1 =
var vector = [1, 2, 3]; # Initialize the vector
append(vector, 4); # Append the number 4 to the end of the vector
debug.dump(vector); # Print the contents of the vector
|example2 =
var vector = [1, 2, 3]; # Initialize the vector
append(vector, 4, 5, 6); # Append the numbers 4, 5, and 6 to the end of the vector
debug.dump(vector); # Print the contents of the vector
}}

=== bind() ===
{{Nasal doc
|syntax = bind(function, locals[, outer_scope]);
|source = {{simgear file|simgear/nasal/lib.c|l=638|t=Source}}
|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.
|param1 = function
|param1text = Function to evaluate.
|param2 = locals
|param2text = Hash containing values that will become the namespace (first closure) for the function.
|param3 = outer_scope
|param3text = Optional function which is bound to the next closure. This can be bound to yet another, making a linked list.
|example1 = # This is a namespace/hash with a single member, named "key," which is initialized to 12
var Namespace = {
key: 12
};

# This is different namespace/hash containing a function
# dividing a variable "key" (which is unavailable/nil in this namespace) by 2
var AnotherNamespace = {
ret: func {
key /= 2;
}
};

# To see that key is not available, try to call AnotherNamespace.ret() first
call(AnotherNamespace.ret, [], nil, nil, var errors = []);
if(size(errors)){
print("Key could not be divided/resolved!");
debug.printerror(errors);
}

# Associate the AnotherNamespace.ret() function with the first namespace
# so that "key" is now available
var function = bind(AnotherNamespace.ret, Namespace);

# Invoke the new function
function();

# Print out the value of Namespace.key
# It was changed to 12 from 6 by AnotherNamespace.ret()
print(Namespace.key);
}}

=== call() ===
{{Nasal doc
|syntax = call(func[, args[, me[, locals[, error]]]);
|source = {{simgear file|simgear/nasal/lib.c|l=376|t=Source}}
|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.
|param1 = func
|param1text = Function to execute.
|param2 = args
|param2text = Vector containing arguments to give to the called function.
|param3 = me
|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).
|param4 = locals
|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.
|param5 = error
|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}}.
|example1 =
# prints "Called from call()"
call(func {
print("Called from call()");
});
|example2 =
# prints "a = 1 : b = 2
call(func(a, b){
print("a = ", a, " : b = ", b);
},
[1, 2]
);
|example3 =
var Hash = {
new: func {
var m = { parents: [Hash] };

m.el1 = "string1";
m.el2 = "string2";

return m;
}
};

# prints "me.el1 = string1", then "me.el2 = string2" on the next line
call(func(a, b){
print("me.el", a, " = ", me["el" ~ a]);
print("me.el", b, " = ", me["el" ~ b]);
},
[1, 2],
Hash.new()
);
|example4 =
# prints the value of math.pi
call(func {
print(pi);
}, nil, nil,
math
);
|example5 =
call(func {
print(math.ip); # math.ip doesn't exist
}, nil, nil, nil,
var errs = []
);
debug.printerror(errs); # The error is caught and printed using debug.printerror()
}}

=== caller() ===
{{Nasal doc
|syntax = caller([level]);
|source = {{simgear file|simgear/nasal/lib.c|l=540|t=Source}}
|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 '''[0]''' a hash of local variables, '''[1]''' the function object, '''[2]''' the full source file name (incl. path) and '''[3]''' the line number.
|param1 = level
|param1text = Optional integer specifying the stack level to return a result from. Defaults to 1 (i.e. the caller of the currently executing function).
|example1 =
var myFunction = func(a, b) {
debug.dump(caller(0)[0]); # prints a hash of local variables, including arguments a and b
return 2 * 2;
};

print("2 x 2 = ", myFunction(2, 2));
|example2 =
var get_arg_value = func() {
print("Argument to myFunc = ", caller(1)[0]['a']); # print the value of myFunc's single argument, using caller()
};

var myFunc = func(a) {
get_arg_value();
};

myFunc(3);
|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: true, zindex: nil }</code>.
|example3 =
var MapStructure_selfTest = func() {
var temp = {};
temp.dlg = canvas.Window.new([600, 400], "dialog");
temp.canvas = temp.dlg.createCanvas().setColorBackground(1, 1, 1, 0.5);
temp.root = temp.canvas.createGroup();

var testMap = temp.root.createChild("map");
testMap.setController("Aircraft position");
testMap.setRange(25); # TODO: implement zooming/panning via mouse/wheel here, for lack of buttons :-/
testMap.setTranslation(
temp.canvas.get("view[0]") / 2,
temp.canvas.get("view[1]") / 2,
);

var r = func(name, vis = true, zindex = nil) {
return caller(0)[0];
}

# TODO: we'll need some z-indexing here, right now it's just random
# TODO: use foreach/keys to show all layers in this case by traversing SymbolLayer.registry directly ?
# maybe encode implicit z-indexing for each lcontroller ctor call ? - i.e. preferred above/below order ?
var types = [
r('TFC', false),
r('APT'),
r('DME'),
r('VOR'),
r('NDB'),
r('FIX', false),
r('RTE'),
r('WPT'),
r('FLT'),
r('WXR'),
r('APS'),
];

foreach (var type; types) {
testMap.addLayer(
factory: canvas.SymbolLayer,
type_arg: type.name,
visible: type.vis,
priority: type.zindex,
);
}
}; # MapStructure_selfTest
}}

=== chr() ===
{{Nasal doc
|syntax = chr(code);
|source = {{simgear file|simgear/nasal/lib.c|l=240|t=Source}}
|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.}}
{{{!}} class="wikitable"
! Code !! Name !! Equivalent to
{{!-}}
{{!}} 10 {{!!}} {{Wikipedia|Newline}} {{!!}} <code>\n</code>
{{!-}}
{{!}} 9 {{!!}} {{Wikipedia|Tab key#Tab characters|Horizontal tab}} {{!!}} <code>\t</code>
{{!-}}
{{!}} 13 {{!!}} {{Wikipedia|Carriage return}} {{!!}} <code>\r</code>
{{!}}}
|param1 = code
|param1text = Integer character code for the desired glyph.
|example1 = print("Code 65 = ", chr(65)); # prints "Code 65 = A"
|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.
|example2 =
for(var i = 0; i <= 255; i += 1){
print("Code ", i, " = >", chr(i), "<");
}
}}

=== closure() ===
{{Nasal doc
|syntax = closure(func[, level]);
|source = {{simgear file|simgear/nasal/lib.c|l=557|t=Source}}
|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'''.
|param1 = func
|param1text = Function to evaluate.
|param2 = level
|param2text = Optional integer specifying the scope level. Defaults to 0 (the namespace of '''func''').
|example1 =
var get_math_e = func {
return e; # return the value of math.e
}

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
debug.dump(closure(myFunction)); # print the hash of the namespace "get_math_e"

print(myFunction());
}}

=== cmp() ===
{{Nasal doc
|syntax = cmp(a, b);
|source = {{simgear file|simgear/nasal/lib.c|l=169|t=Source}}
|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'''.
|param1 = a
|param1text = First string argument for comparison.
|param2 = b
|param2text = Second string argument for comparison.
|example1 = print(cmp("1", "two")); # prints -1
|example2 = print(cmp("string", "string")); # prints 0
|example3 = print(cmp("one", "2")); # prints 1
|example4 = print(cmp("string1", "string2")); # prints -1
}}

=== compile() ===
{{Nasal doc
|syntax = compile(code[, filename]);
|source = {{simgear file|simgear/nasal/lib.c|l=349|t=Source}}
|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'''.
|param1 = code
|param1text = String containing Nasal code to be compiled.
|param2 = filename
|param2text = Optional string used for error messages/logging. Defaults to <code><compile></code>
|example1 =
var myCode = 'print("hello");';
var helloFunc = compile(myCode, "myCode");
helloFunc();
|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>.
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<PropertyList>

<nasal><![CDATA[
print("You have FlightGear v", getprop("/sim/version/flightgear"));
]]></nasal>

</PropertyList>
</syntaxhighlight>
Now, start FlightGear and execute this code in the [[Nasal Console]].
|example2 =
# Build the path
var FGRoot = getprop("/sim/fg-root");
var filename = "/gui/dialogs/test.xml";
var path = FGRoot ~ filename;

var blob = io.read_properties(path);
var script = blob.getValues().nasal; # Get the nasal string

# Compile the script. We're passing the filename here for better runtime diagnostics
var code = call(func {
compile(script, filename);
}, nil, nil, var compilation_errors = []);

if(size(compilation_errors)){
die("Error compiling code in: " ~ filename);
}

# Invoke the compiled script, equivalent to code();
# We're using call() here to detect errors:
call(code, [], nil, nil, var runtime_errors = []);

if(size(runtime_errors)){
die("Error calling code compiled loaded from: " ~ filename);
}
|example3text = The <code>compile()</code> function also allows you to parse a JSON string into a hash. Simplest example:
|example3 =
var jsonFunc = compile('{"version":"1.2.0","author":{"name":"John"} }');
var json = jsonFunc(); # return hash
logprint(LOG_ALERT, json["version"]); # print "1.2.0"
logprint(LOG_ALERT, json["author"]["name"]); # print "John"
}}

=== contains() ===
{{Nasal doc
|syntax = contains(hash, key);
|source = {{simgear file|simgear/nasal/lib.c|l=249|t=Source}}
|text = Returns 1 (True) if the hash contains the specified key, or 0 (False) if not.
|param1 = hash
|param1text = The hash to search in.
|param2 = key
|param2text = The scalar to be searched for, contained as a key in the hash.
|example1 =
# Initialize a hash
var hash = {
element: "value"
};
print(contains(hash, "element") ? "Yes" : "No"); # This will print "Yes"
print(contains(hash, "element2") ? "Yes" : "No"); # This will print "No"
}}

===contains()===
{{Requires commit|desc=Vector support|details=see {{Merge-request|project=fgdata|id=305}}|commit=ee39abbd3b70c9b6d5e3a1c4ccedddaac1a92b11|repo=Simgear}}
{{Nasal doc
|syntax = contains(vector, item);
|source = {{simgear file|simgear/nasal/lib.c|l=249|t=Source}}
|text = Returns 1 (True) if the vector contains the specified item, or 0 (False) if not.
|param1 = vector
|param1text = The vector to search in.
|param2 = item
|param2text = The object to be searched for in the vector.
|example1 =
# Initialize a vector
var vec = ["element", "foo"];
print(contains(vec, "element") ? "Yes" : "No"); # This will print "Yes"
print(contains(vec, "element2") ? "Yes" : "No"); # This will print "No"
}}

===delete() ===
{{Nasal doc
|syntax = delete(hash, key);
|source = {{simgear file|simgear/nasal/lib.c|l=118|t=Source}}
|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.
|param1 = hash
|param1text = The hash from which to delete the key.
|param2 = key
|param2text = The scalar to be deleted, contained as a key in the hash.
|example1 =
# Initialize the hash
var hash = {
element1: "value1",
element2: "value2"
};
delete(hash, "element1"); # Delete element1
debug.dump(hash); # prints the hash, which is now minus element1
}}

===die()===
{{Nasal doc
|syntax = die(error);
|source = {{simgear file|simgear/nasal/lib.c|l=417|t=Source}}
|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()}}.
|param1 = error
|param1text = String describing the error.
:{{inote|This parameter is technically optional, but it is highly recommended to use it.}}
|example1 =
print("Will print");
die("Don't go any further!");
print("Won't print"); # Will not be printed because die() stops the process
}}

=== find()===
{{Nasal doc
|syntax = find(needle, haystack);
|source = {{simgear file|simgear/nasal/lib.c|l=586|t=Source}}
|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.
|param1 = needle
|param1text = String to search for.
|param2 = haystack
|param2text = String to search in.
|example1 = print(find("c", "abcdef")); # prints 2
|example2 = print(find("x", "abcdef")); # prints -1
|example3 = print(find("cd", "abcdef")); # prints 2
}}

===ghosttype()===
{{Nasal doc
|syntax = ghosttype(ghost);
|source = {{simgear file|simgear/nasal/lib.c|l=336|t=Source}}
|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.
|param1 = ghost
|param1text = Ghost to return a description for.
|example1 = print(ghosttype(airportinfo())); # prints "airport"
}}

===id()===
{{Nasal doc
|syntax = id(object);
|source = {{simgear file|simgear/nasal/lib.c|l=706|t=Source}}
|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.
|param1 = object
|param1text = Can be either of a string, a vector, a hash, a code, a function, or a ghost.
|example1 = print(id("A")); # prints "str:000000001624A590"
}}

===int() ===
{{Nasal doc
|syntax = int(number);
|source = {{simgear file|simgear/nasal/lib.c|l=125|t=Source}}
|text = Returns the integer part of the numeric value of the single argument, or <code>'''nil'''</code> if none exists.
|param1 = number
|param1text = Number or string with just a number in it to return an integer from.
|example1 = print(int(23)); # prints "23"
|example2 = print(int(23.123)); # prints "23"
|example3 = debug.dump(int("string")); # prints "nil"
}}

===keys()===
{{Nasal doc
|syntax = keys(hash);
|source = {{simgear file|simgear/nasal/lib.c|l=36|t=Source}}
|text = Returns a vector containing the list of keys found in the single hash argument.
|param1 = hash
|param1text = The hash to return the keys from.
|example1 =
# Initialize a hash
var hash = {
element1: "value",
element2: "value"
};
debug.dump(keys(hash)); # print the vector
}}

===left()===
{{Nasal doc
|syntax = left(string, length);
|source = {{simgear file|simgear/nasal/lib.c|l=214|t=Source}}
|version = 2.12
|commit = {{simgear commit|bd7163|t=commit}}
|text = Returns a substring of '''string''', starting from the left.
|param1 = string
|param1text = String to return part of.
|param2 = length
|param2text = Integer specifying the length of the substring to return.
|example1 = print(left("string", 2)); # prints "st"
}}

=== num()===
{{Nasal doc
|syntax = num(number);
|source = {{simgear file|simgear/nasal/lib.c|l=149|t=Source}}
|text = Returns the numerical value of the single string argument, or <code>'''nil'''</code> if none exists.
|param1 = number
|param1text = String with just a number in it to return a number from.
|example1 = print(num("23")); # prints "23"
|example2 = print(num("23.123")); # prints "23.123"
|example3 = debug.dump(num("string")); # prints "nil"
}}

===pop()===
{{Nasal doc
|syntax = pop(vector);
|source = {{simgear file|simgear/nasal/lib.c|l=85|t=Source}}
|text = Removes and returns the last element of the single vector argument, or <code>'''nil'''</code> if the vector is empty.
|param1 = vector
|param1text = Vector to remove an element from.
|example1 =
var vector = [1, 2, 3];
pop(vector);
debug.dump(vector); # prints "[1, 2]"
|example2 =
var vector = [1, 2, 3];
debug.dump(pop(vector)); # prints "3"
|example3 =
var vector = [];
debug.dump(pop(vector)); # prints "nil"
}}

=== range() ===
{{Nasal doc
|syntax = range([start, ]stop[, step]);
|source = {{simgear file|simgear/nasal/lib.c|l=756|t=Source}}
|text = Creates a vector of numbers starting from <code>start</code> (default 0) up to but not including <code>stop</code>, incremented by <code>step</code> (default 1). Note: To specify <code>step</code>, you must also provide <code>start</code>; otherwise the second argument is interpreted as <code>stop</code>.
|param1 = start
|param1text = Optional. The starting number of the sequence. Defaults to 0 if omitted. Required if you want to specify <code>step</code>.
|param2 = stop
|param2text = Required. The number at which to stop the sequence (not included).
|param3 = step
|param3text = Optional. The increment between each number in the sequence. Defaults to 1. Only valid if <code>start</code> is also specified.
|example1 =
var vec = range(5); # Creates a vector [0, 1, 2, 3, 4]
var vec = range(2, 5); # Creates a vector [2, 3, 4]
var vec = range(0, 10, 2); # Creates a vector [0, 2, 4, 6, 8]
var vec = range(0, 0); # Creates an empty vector []
var vec = range(0, 1); # Creates a vector [0]
}}

=== remove() ===
{{Nasal doc
|syntax = remove(vector, value);
|source = {{simgear file|simgear/nasal/lib.c|l=53|t=Source}}
|text = Removes all elements equal to the given value from a vector and returns the modified vector.
|param1 = vector
|param1text = The vector from which elements are to be removed.
|param2 = value
|param2text = A value to remove from the vector.
|example1 =
var vector = [1, 2, 3]; # Initialize the vector.
remove(vector, 2); # Remove the value 2 from the vector.
debug.dump(vector); # Print the contents of the vector: "[1, 3]".
|example2 =
var vector = ["text", "text", "text"]; # Initialize the vector.
remove(vector, "text"); # Remove the value "text" from the vector.
debug.dump(vector); # Print the contents of the vector: "[]".
}}

=== removeat() ===
{{Nasal doc
|syntax = removeat(vector, index);
|source = {{simgear file|simgear/nasal/lib.c|l=72|t=Source}}
|text = Removes the element at the specified index from the vector and returns it.
|param1 = vector
|param1text = The vector from which the element will be removed.
|param2 = index
|param2text = Index of the item to be deleted.
|example1 =
var vector = [1, 2, 3]; # Initialize the vector.
removeat(vector, 0); # Remove the index 0 from the vector.
debug.dump(vector); # Print the contents of the vector: "[2, 3]".
}}

===right()===
{{Nasal doc
|syntax = right(string, length);
|source = {{simgear file|simgear/nasal/lib.c|l=226|t=Source}}
|version = 2.12
|commit = {{simgear commit|bd7163|t=commit}}
|text = Returns a substring of '''string''', starting from the right.
|param1 = string
|param1text = String to return part of.
|param2 = length
|param2text = Integer specifying the length of the substring to return.
|example1 = print(right("string", 2)); # prints "ng"
}}

=== setsize()===
{{Nasal doc
|syntax = setsize(vector, size);
|source = {{simgear file|simgear/nasal/lib.c|l=91|t=Source}}
|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.
|param1 = vector
|param1text = The vector to be operated on.
|param2 = size
|param2text = The desired size of the vector in number of entries.
|example1 =
var vector = [1, 2, 3]; # Initialize a vector
setsize(vector, 4);
debug.dump(vector); # print the vector "[1, 2, 3, nil]"
|example2 =
var vector = [1, 2, 3]; # Initialize a vector
setsize(vector, 2);
debug.dump(vector); # print the vector "[1, 2]"
}}

===size()===
{{Nasal doc
|syntax = size(object);
|source = {{simgear file|simgear/nasal/lib.c|l=26|t=Source}}
|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>.
|param1 = object
|param1text = Object to find the size of. Must be a string, a vector or a hash.
|example1 =
var string = "string";
print(size(string)); # prints "6"
|example2 =
var vector = [1, 2, 3];
print(size(vector)); # prints "3"
|example3 =
var hash = {
element1: "value1",
element2: "value2",
element3: "value3"
};
print(size(hash)); # prints "3"
}}

=== sort()===
{{Nasal doc
|syntax = sort(vector, function);
|source = {{simgear file|simgear/nasal/lib.c|l=678|t=Source}}
|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.
|param1 = vector
|param1text = Input vector to sort.
|param2 = function
|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.
{{{!}} class="wikitable"
! Return value !! Meaning
{{!-}}
{{!}} less than 0 {{!!}} first argument should go before second argument
{{!-}}
{{!}} 0 {{!!}} first argument equals second argument
{{!-}}
{{!}} greater than 0 {{!!}} first argument should go after second argument
{{!}}}

|example1text = This example sorts elements from smallest to greatest.
|example1 =
var sort_rules = func(a, b) {
if (a < b) {
return -1; # A should before b in the returned vector
} elsif (a == b) {
return 0; # A is equivalent to b
} else {
return 1; # A should after b in the returned vector
}
}
debug.dump(sort([3, 2, 5, 6, 4, 1], sort_rules)); # prints "[1, 2, 3, 4, 5, 6]"
|example2text = This example sorts elements from greatest to smallest.
|example2 =
# Outputs the elements in reverse order (greatest to smallest)
var sort_rules = func(a, b) {
if (a < b) {
return 1; # -1 in the above example
} elsif (a == b) {
return 0;
} else {
return -1; # 1 in the above example
}
}
debug.dump(sort([3, 2, 5, 6, 4, 1], sort_rules)); # prints "[6, 5, 4, 3, 2, 1]"
|example3text = This example sorts a vector of strings (runways for example) from smallest to greatest.
|example3 =
var runways = ["09R", "27R", "26L", "09L", "15"];
var rwy = sort(runways, func(a, b) cmp(a, b));
debug.dump(rwy); # prints ['09L', '09R', '15', '26L', '27R']
}}

=== split()===
{{Nasal doc
|syntax = split(delimiter, string);
|source = {{simgear file|simgear/nasal/lib.c|l=596|t=Source}}
|text = Splits the input string into a vector of substrings bounded by occurrences of the delimiter substring. See [[Nasal_library/string#string.join(sep,list)|string.join()]].
|param1 = delimiter
|param1text = String that will split the substrings in the returned vector.
|param2 = string
|param2text = String to split up.
|example1 = debug.dump(split("cd", "abcdef")); # prints "['ab', 'ef']"
|example2 = debug.dump(split(".", "3.2.0")); # prints "[3, 2, 0]"
|example3 = debug.dump(split("/", "path/to/file")); # prints "['path', 'to', 'file']"
}}

===sprintf()===
{{Nasal doc
|syntax = <nowiki>sprintf(format[, arg[, arg, [...]]]);</nowiki>
|source = {{simgear file|simgear/nasal/lib.c|l=491|t=Source}}
|text = Creates and returns a string formatted using ANSI C {{func link|vsnprintf()|link=http://en.cppreference.com/w/c/io/vfprintf}} <ref>
{{Cite web
|url = http://sourceforge.net/p/flightgear/simgear/ci/next/tree/simgear/nasal/lib.c#l308
|title = fgdata/simgear/simgear/nasal/lib.c, line 308
|accessdate = October 2015
}}
</ref>. Below is a table of supported format specifiers.
{{{!}} class="wikitable" width="75%"
{{!}}+ %[flags][width][.precision]specifier
! colspan="2" {{!}} Flags
{{!-}}
! Flag !! Output
{{!-}}
{{!}} <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.
{{!-}}
{{!}} ''space'' {{!!}} Prefixes non-signed numbers with a space.
{{!-}}
{{!}} <code>-</code> {{!!}} Left-align the output of this placeholder (the default is to right-align the output) when the width option is specified.
{{!-}}
{{!}} <code>0</code> {{!!}} Use 0 instead of spaces to pad a field when the width option is specified.
{{!-}}
{{!}} <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.
{{!-}}
! colspan="2" {{!}} Width
{{!-}}
{{!}} 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.
{{!-}}
! colspan="2" {{!}} Precision
{{!-}}
{{!}} colspan="2" {{!}} Integer preceded by a dot specifying the number of decimal places to be written.
{{!-}}
! colspan="2" {{!}} Specifiers
{{!-}}
! Specifier !! Output
{{!-}}
{{!}} <code>d</code>, <code>i</code> {{!!}} Signed decimal number.
{{!-}}
{{!}} <code>s</code> {{!!}} A string
{{!-}}
{{!}} <code>%</code> {{!!}} Percent (%) character.
{{!-}}
{{!}} <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.
{{!-}}
{{!}} <code>o</code> {{!!}} Unsigned integer as an octal number.
{{!-}}
{{!}} <code>u</code> {{!!}} Unsigned decimal integer.
{{!-}}
{{!}} <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.
{{!-}}
{{!}} <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.
{{!-}}
{{!}} <code>f</code> {{!!}} Floating-point number, in fixed decimal notation, by default with 6 decimal places.
{{!-}}
{{!}} <code>F</code> {{!!}} Appears to be available<ref>
{{Cite web
|url = http://sourceforge.net/p/flightgear/simgear/ci/next/tree/simgear/nasal/lib.c#l389
|title = fgdata/simgear/simgear/nasal/lib.c, line 389
|accessdate = October 2015
}}
</ref>, but doesn't work.
{{!-}}
{{!}} <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.
{{!}}}

|param1 = format
|param1text = String specifying the format. Can be used with or without a format specifiers. See below for examples.
|param2 = arg
|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.

|example1 = print(sprintf("%i", 54)); # prints "54"
|example2 = print(sprintf("Pi = %+.10f", math.pi)); # prints "Pi = +3.1415926536"
|example3 =
print(sprintf("%6d", 23)); # prints " 23"
print(sprintf("%06d", 23)); # prints "000023"
|example4 =
var FGVer = getprop("/sim/version/flightgear");
print(sprintf("You have FlightGear v%s", FGVer)); # prints "You have FlightGear v<your version>"
|example5 =
print(sprintf("Hexadecimal 100000 = %X", 100000)); # prints "Hexadecimal 100000 = 186A0"
print(sprintf("Hexadecimal 100000 = %x", 100000)); # prints "Hexadecimal 100000 = 186a0"
|example6 = print(sprintf("Code 65 is %c", 65)); # prints "Code 65 is A"
|example7 =
print(sprintf("%e", 54)); # prints "5.400000e+001"
print(sprintf("%E", 54)); # prints "5.400000E+001"
|example8 = print(sprintf("%o", 54)); # prints "66"
|example9 = print(sprintf("50%% of 100 is %i", 100 / 2)); # prints "50% of 100 is 50"
|example10 =
print(sprintf("%.2f", 1.4)); # prints "1.40"
print(sprintf("%.1f", 1.4)); # prints "1.4"
print(sprintf("% 4.1f", 1.4)); # prints " 1.4"
print(sprintf("%04.1f", 1.4)); # prints "01.4"
print(sprintf("% 6.1f", 1.4)); # prints " 1.4"
print(sprintf("%06.1f", 1.4)); # prints "0001.4"
}}

===str()===
{{Nasal doc
|syntax = str(value);
|source = {{simgear file|simgear/nasal/lib.c|l=186|t=Source}}
|text = Convert given value (scalar) to string. If <code>value</code> is a number, it will be converted to a string. If <code>value</code> is a string, the same string will be returned. If <code>value</code> is not a scalar (hash, vector, nil), <code>nil</code> will be returned.
|param1 = value
|param1text = The value to convert to string.
|example1 =
var result = str(true); # result is a string "1"
var result = str(false); # result is a string "0"
var result = str(12); # result is a string "12"
var result = str(12.5); # result is a string "12.5"
var result = str(-12.5); # result is a string "-12.5"
var result = str("12.5"); # result is a string "12.5"
var result = str([1, 2]); # result is a nil
var result = str({ x: 0 }); # result is a nil
var result = str(nil); # result is a nil
}}

===streq()===
{{Nasal doc
|syntax = streq(a, b);
|source = {{simgear file|simgear/nasal/lib.c|l=164|t=Source}}
|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.}}
|param1 = a
|param1text = First argument for testing equality.
|param2 = b
|param2text = Second argument for testing equality.
|example1 = print(streq("0", "0")); # prints "1" (True)
|example2 =
print(0 == 0.0); # prints "1" (True)
print(streq("0", "0.0")); # prints "0" (False)
}}

===substr()===
{{Nasal doc
|syntax = substr(string, start [, length]);
|source = {{simgear file|simgear/nasal/lib.c|l=194|t=Source}}
|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).
|param1 = string
|param1text = String to return a substring from.
|param2 = start
|param2text = Integer specifying the start of a substring. Negative values specify a position from the end of the string.
|param3 = length
|param3text = Optional argument specifying the length of the substring. Defaults to the end of the string.
|example1 = print(substr("abcde", 1, 3)); # prints "bcd"
|example2 = print(substr("abcde", 1)); # prints "bcde"
|example3 = print(substr("abcde", 2, 1)); # prints "c"
|example4 = print(substr("abcde", -2)); # prints "de"
|example5 = print(substr("abcde", -3, 2)); # prints "cd"
}}

===subvec()===
{{Nasal doc
|syntax = subvec(vector, start[, length]);
|source = {{simgear file|simgear/nasal/lib.c|l=98|t=Source}}
|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).
|param1 = vector
|param1text = The vector to take the sub-vector from.
|param2 = start
|param2text = The starting point of the sub-vector within the given vector.
|param3 = length
|param3text = Optional argument specifying the length of the sub-vector, from the starting point.
'''Notes:'''
* Omitting the ''vector'' and ''start'' arguments is not an error (possibly it should be) but the return value is ''nil''.
* A negative ''start'' argument ''is'' an error. This seems wrong. Perhaps the language designer could comment.
* A value of ''start'' greater than ''size(vector)'' causes an error. A value equal to ''size(vector)'' returns an empty vector.
* 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.
|example1 =
var vector = [1, 2, 3];
debug.dump(subvec(vector, 0)); # prints "[1, 2, 3]"
|example2 =
var vector = [1, 2, 3];
debug.dump(subvec(vector, 1)); # prints "[2, 3]"
|example3 =
var vector = [1, 2, 3];
debug.dump(subvec(vector, 1, 1)); # prints "[2]"
}}

=== typeof()===
{{Nasal doc
|syntax = typeof(object);
|source = {{simgear file|simgear/nasal/lib.c|l=287|t=Source}}
|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.
|param1 = object
|param1text = Object to return the type of.
|example1 =
var object = nil;
print(typeof(object)); # prints "nil"
|example2 =
var object = "Hello world!";
print(typeof(object)); # prints "scalar"
|example3 =
var object = math.pi;
print(typeof(object)); # prints "scalar"
|example4 =
var object = [1, 2, 3];
print(typeof(object)); # prints "vector"
|example5 =
var object = {};
print(typeof(object)); # prints "hash"
|example6 =
var object = func {};
print(typeof(object)); # prints "func"
|example7 =
var object = airportinfo();
print(typeof(object)); # prints "ghost"
}}



==Extension functions==
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:
*{{flightgear file|src/Scripting/NasalPositioned.cxx}}
*{{flightgear file|src/Scripting/NasalSys.cxx}}
*{{fgdata file|Nasal/globals.nas}}

===abort()===
{{Nasal doc
|syntax = abort();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=565|t=Source}}
|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).
|example1text = This example will immediately stop FlightGear with an error, such as "FlightGear has stopped working."
|example1 = abort();
|example2text = For exiting FlightGear in a better way, please use the following code:
|example2 = fgcommand("exit");
}}

=== abs() ===
{{Nasal doc
|syntax = abs(number);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = This simple function returns the {{wikipedia|absolute value|noicon=1}} of the provided number.
|param1 = number
|param1text = This argument is required and should be a number.
|example1 = print(abs(1)); # prints "1"
|example2 = print(abs(-1)); # prints "1"
}}

===aircraftToCart() ===
This new function in FG 2017.2.1 takes coordinates in aircraft structural coordinate system, and translate them into geocentric coordinates.
Example for (5,6,7):
<syntaxhighlight lang="nasal">
var pos = aircraftToCart({x: -5, y: 6, z: -7});
var coord = geo.Coord.new();
coord.set_xyz(pos.x, pos.y, pos.z);
</syntaxhighlight>
Notice: x and z is inverted sign on purpose.
if you want lat. lon, alt from that, just call: (degrees and meters)

<syntaxhighlight lang="nasal">
coord.lat()
coord.lon()
coord.alt()
</syntaxhighlight>

===addcommand() ===
{{Nasal doc
|syntax = addcommand(name, code);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=659|t=Source}}
|version = 2.12
|commit = {{flightgear commit|7b663c|t=commit}}
|text = {{see also|Howto:Add new fgcommands to FlightGear}}

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.
|param1 = name
|param1text = This will become the name of the new fgcommand. Must be a string.
|param2 = code
|param2text = The code that will be executed when the fgcommand is run. Must be a function.
|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.
|example1 = addcommand("myFGCmd", func(node) {
print("fgcommand 'myFGCmd' has been run.");
props.dump( node );
});
fgcommand("myFGCmd", props.Node.new({foo:1, bar:2}) );
|example2text = This example demonstrates how parameters are defined in a new fgcommand.
|example2 = addcommand("myFGCmd", func(node){
print(node.getNode("number").getValue()); # prints the value of "number," which is 12
});
fgcommand("myFGCmd", props.Node.new({"number": 12}));
}}

===airportinfo()===
{{Nasal doc
|syntax = airportinfo();
airportinfo(type);
airportinfo(id);
airportinfo(lat, lon[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1024|t=Source}}
|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:
* '''parents''': A vector containing a hash of various functions to access information about the runway. These functions are:
** '''findBestRunwayForPos()''' return runway as ghost by given geo position, e.g. <code>var rwy = airportinfo().findBestRunwayForPos(geo.aircraft_position());</code>.
** '''runway()''' return runway as ghost by runway ID, e.g. <code>var rwy = airportinfo().runway("18R");</code>.
** '''runwaysWithoutReciprocals()''' return vector of runways as ghost.
** '''helipad()''' return helipad as ghost by helipad ID, e.g. <code>var heli = airportinfo().helipad("H19");</code>.
** '''tower()''' return hash with <code>lat</code>, <code>lon</code>, <code>elevation</code> fields.
** '''comms()''' return vector of hashes, each hash with <code>frequency</code> and <code>ident</code> fields.
** '''sids()''' return vector of strings with SID IDs.
** '''stars()''' return vector of strings with STAR IDs.
** '''getApproachList()''' return vector of string with approaches.
** '''parking()''' return vector of hashes, each hash with <code>lat</code>, <code>lon</code>, <code>elevation</code>, <code>name</code> fields.
** '''getSid()''' return SID as ghost, e.g. <code>var sid = airportinfo().getSid("SA1A");</code>.
** '''getStar()''' return STAR as ghost, e.g. <code>var star = airportinfo().getStar("KEILA1");</code>.
** '''getIAP()''' return IAP as ghost, e.g. <code>var iap = airportinfo().getIAP("ILS02");</code>.
** '''getApproach()''' return approach as ghost, e.g. <code>var approach = airportinfo().getApproach("ILS02");</code>.
** '''tostring()''' just return string "an airport ICAO".
** See also {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1902}}.
* '''lon''': Longitude of the location.
* '''lat''': Latitude of the location.
* '''has_metar''': True or false depending whether the airport has a [[METAR]] code defined for it.
* '''elevation''': Elevation of the location in metres.
* '''id''': ICAO code of the airport (or ID of the seaplane base/heliport).
* '''name''': Name of the airport/heliport/seaplane base.
* '''runways'''
** '''<runway name>'''
*** '''id''': Name of runway.
*** '''lat''': Latitude of the runway.
*** '''lon''': Longitude of the runway.
*** '''heading''': True heading of the runway.
*** '''length''': Length of the runway in metres.
*** '''width''': Width of the runway in metres.
*** '''surface''': Runway surface type.
*** '''threshold''': Length of the runway's {{wikipedia|displaced threshold}} in metres. Will return 0 if there is none.
*** '''stopway''': Length of the runway's stopway (the area before the threshold) in metres. Will return 0 if there is none.
*** '''reciprocal''': <code>runway</code> ghost of the reciprocal runway.
*** '''ils_frequency_mhz''': ILS frequency in megahertz.
*** '''ils''': <code>navaid</code> ghost of the ILS transmitter.
* '''helipads'''
** '''<helipad name>'''
*** '''id''': Name of helipad.
*** '''lat''': Latitude of the helipad.
*** '''lon''': Longitude of the helipad.
*** '''heading''': True heading of the helipad.
*** '''length''': Length of the helipad in metres.
*** '''width''': Width of the helipad in metres.
*** '''surface''': Helipad surface type.
* '''taxiways'''
** '''<taxiway name>'''
*** '''id''': Name of taxiway.
*** '''lat''': Latitude of the taxiway.
*** '''lon''': Longitude of the taxiway.
*** '''heading''': Heading of the taxiway.
*** '''length''': Length of the taxiway in metres.
*** '''width''': Width of the taxiway in metres.
*** '''surface''': Taxiway surface type.

Information is extracted in the same way as accessing members of a Nasal hash. For example:
<syntaxhighlight lang="nasal">
# prints to lengths of the runways of the nearest airport in feet and metres
var info = airportinfo();
print("-- Lengths of the runways at ", info.name, " (", info.id, ") --");
foreach(var rwy; keys(info.runways)){
print(rwy, ": ", math.round(info.runways[rwy].length * M2FT), " ft (", info.runways[rwy].length, " m)");
}
</syntaxhighlight>

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.
|param1 = id
|param1text = The {{wikipedia|International Civil Aviation Organization airport code|ICAO code|noicon=1}} of an airport to retrieve information about.
|param2 = type
|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).
: {{inote|Running this function without any parameters is equivalent to this:
: <syntaxhighlight lang="nasal">
airportinfo("airport");
</syntaxhighlight>
}}
|param3 = lat ''and'' lon
|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.
|example1 = var info = airportinfo();
print("Nearest airport: ", info.name, " (", info.id, ")"); # prints the name and ICAO code of the nearest airport
|example2 = var info = airportinfo("heliport");
print("Elevation of the nearest heliport: ", math.round(info.elevation * M2FT), " ft"); # prints the elevation and name of the nearest heliport
|example3 = var info = airportinfo("KSQL");
print("-- Runways of ", info.name, " (", info.id, "): --");
foreach(var rwy; keys(info.runways)) {
print(rwy); # prints the runways of KSQL
}
|example4 = var info = airportinfo(37.81909385, -122.4722484);
print("Coordinates of the nearest airport: ", info.lat, ", ", info.lon); # print the name and ICAO of the nearest airport to the Golden Gate Bridge
|example5 = var info = airportinfo(37.81909385, -122.4722484, "seaport");
print("Nearest seaplane base: ", info.name, " (", info.id, ")"); # print the name and ID of the nearest seaplane base to the Golden Gate Bridge
|example6text = This example prints the all information from an <code>airportinfo()</code> call.
|example6 = var info = airportinfo("KSFO");
print(info.name);
print(info.id);
print(info.lat);
print(info.lon);
print(info.has_metar);
print(info.elevation);
foreach(var rwy; keys(info.runways)){
print("-- ", rwy, " --");
print(info.runways[rwy].lat);
print(info.runways[rwy].lon);
print(info.runways[rwy].length);
print(info.runways[rwy].width);
print(info.runways[rwy].heading);
print(info.runways[rwy].stopway);
print(info.runways[rwy].threshold);
<nowiki>}</nowiki>
}}

===airwaysRoute() ===
{{Nasal doc
|syntax = airwaysRoute(start, end[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1933|t=Source}}
|text = {{see also|Nasal Flightplan}}
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.
|param1 = start
|param1text = Start waypoint, in the form of a waypoint ghost, such as that provided by {{func link|flightplan()}}.
|param2 = end
|param2text = Same as above.
|param3 = type
|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."
|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.
|example1 = var fp = flightplan();
var start = fp.getWP(0);
var end = fp.getWP(fp.getPlanSize() - 1);
var rt = airwaysRoute(start, end);
foreach(var wp; rt){
print(wp.wp_name); # print the waypoints in the computed route
}
|example2text = Exactly the same as above, but computes a low level path.
|example2 = var fp = flightplan();
var start = fp.getWP(0);
var end = fp.getWP(fp.getPlanSize() - 1);
var rt = airwaysRoute(start, end, "lowlevel");
foreach(var wp; rt){
print(wp.wp_name); # print the waypoints in the computed route
<nowiki>}</nowiki>
}}

===airway()===

{{Nasal doc
|syntax = airway(ident [, pos]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2644|t=Source}}
|text = {{see also|Nasal Flightplan}}
This function returns a ghost containing an airway of a specified id.
|param1 = ident
|param1text = a Positioned ghost (leg, navaid, airport) and so on, passed to the search function.
|param2 = pos
}}

===assert()===
{{Nasal doc
|syntax = assert(condition[, message]);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|version = 3.2
|commit = {{fgdata commit|8b16a7|t=commit}}
|text = Returns either true if the condition evaluates as true, or aborts with a {{func link|die()}} call, which can be customised.
|param1 = condition
|param1text = Condition to evaluate.
|param2 = message
|param2text = Optional message that will be used in any {{func link|die()}} call. Defaults to "assertion failed!"
|example1 = var a = 1;
var b = 2;
print(assert(a < b)); # prints "1" (true)
|example2 = var a = 1;
var b = 2;
assert(a > b, 'a is not greater than b'); # aborts with a custom error message
}}

===carttogeod()===
{{Nasal doc
|syntax = carttogeod(x, y, z);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=945|t=Source}}
|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>
|param1 = x
|param1text = Mandatory x-axis value, in metres.
|param2 = y
|param2text = Mandatory y-axis value, in metres.
|param3 = z
|param3text = Mandatory z-axis value, in metres.
|example1 = var (lat, lon, alt) = carttogeod(6378137, 0, 0); # point is the intersection of the prime meridian and equator.
print("Latitude: ", lat); # prints lat, lon and alt, which are all zero, see above
print("Longitude: ", lon);
print("Altitude: ", alt);
}}

===cmdarg()===
{{Nasal doc
|private = _cmdarg()
|syntax = cmdarg();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=513|t=Part 1}} {{!}} {{fgdata file|Nasal/globals.nas|t=Part 2}}
|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.
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:
* Bindings: This is needed so that the value of a joystick's axis can be accessed internally.
* 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).
* 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.
* 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>

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.

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.
|example1 = fgcommand("dialog-show", {"dialog-name": "cmdarg-demo"});
|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.
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>

<PropertyList>

<name>cmdarg-demo</name>
<layout>vbox</layout>

<text>
<label>Click "Close" to activate the demonstration (a message in the console).</label>
</text>

<button>
<legend>Close</legend>
<binding>
<command>nasal</command>
<script>print("Button binding root: '" ~ cmdarg().getPath() ~ "'");</script>
</binding>
<binding>
<command>dialog-close</command>
</binding>
</button>

</PropertyList>
</syntaxhighlight>
|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!"
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>

<PropertyList>

<name>cmdarg-demo</name>
<layout>vbox</layout>

<text>
<label>Click "Click me!" to activate the demonstration (the button's label will change).</label>
</text>

<button>
<legend>Click me!</legend>
<binding>
<command>nasal</command>
<script>change_label();</script>
</binding>
</button>

<button>
<legend>Close</legend>
<binding>
<command>dialog-close</command>
</binding>
</button>

<nasal>
<open><![CDATA[
var dlg_root = cmdarg();
var dlg_name = {"dialog-name": "cmdarg-demo"};
var change_label = func {
dlg_root.getNode("button[0]/legend").setValue("I've been changed!");
fgcommand("dialog-close", dlg_name);
fgcommand("dialog-show", dlg_name);
}
]]></open>
</nasal>

</PropertyList>
</syntaxhighlight>
|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]].
}}

===courseAndDistance()===
{{Nasal doc
|syntax = courseAndDistance(to);
courseAndDistance(from, to);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1668|t=Source}}
|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:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object with geodetic coordinates (cartesian coordinates will not be accepted)
|param1 = from
|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.
|param2 = to
|param2text = Like the first parameter, but defines the second point.
|example1text = This example demonstrates the usage of the function with the <code>airport</code> ghost type.
|example1 = var from = airportinfo("KSFO");
var to = airportinfo("KSQL");
var (course, dist) = courseAndDistance(from, to);
print(course); # prints course from KSFO to KSQL
print(dist); # prints distance in nm from KSFO to KSQL
|example2text = This example demonstrates the usage of the function with hashes containing ''lat'' and ''lon''.
|example2 = var from = {lat: 0, lon: 0};
var to = {lat: 1, lon: 1};
var (course, dist) = courseAndDistance(from, to);
print(course);
print(dist);
|example3text = This example demonstrates usage of a geo.Coord object.
|example3 = var from = geo.Coord.new().set_latlon(0, 0);
var to = geo.Coord.new().set_latlon(1, 1);
var (course, dist) = courseAndDistance(from, to);
print(course);
print(dist);
|example4text = This example demonstrates usage of differing parameter types.
|example4 = var from = airportinfo("KSFO");
var to = geo.Coord.new().set_latlon(0, 0);
var (course, dist) = courseAndDistance(from, to);
print(course);
print(dist);
|example5text = The same as above, but the other way round.
|example5 = var to = {lat: 1, lon: 1};
var (course, dist) = courseAndDistance(0, 0, to);
print(course);
print(dist);
|example6text = Usage of just one parameter.
|example6 = var dest = airportinfo("KSQL");
var (course, dist) = courseAndDistance(dest);
print("Turn to heading ", math.round(course), ". You have ", sprintf("%.2f", dist), " nm to go");
}}

===createFlightplan()===
{{Nasal doc
|syntax = createFlightplan(path);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2331|t=Source}}
|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.
|param1 = path
|param1text = Optional parameter defining the file from which a flightplan will be populated.
|example1 =
var path = getprop("/sim/fg-home") ~ "/Export/test.fgfp";
var flightplan = createFlightplan(path);
debug.dump(flightplan);
}}

===createDiscontinuity()===
{{Nasal doc
|syntax = createDiscontinuity();
|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.
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2045|t=Source}}
|version = 2016.1
|commit = {{flightgear commit|caead6|t=commit}}
}}
===createViaTo()===
{{Nasal doc
|syntax = createViaTo(airway, waypoint);
|text = Returns a <code>waypoint</code> ghost object. It represents a route "via '''airway''' to '''waypoint'''".
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2009|t=Source}}
|version = 2016.1
|commit = {{flightgear commit|caead6|t=commit}}
|param1 = airway
|param1text = The name of an airway.
|param2 = waypoint
|param2text = Must be in the airway and one of:
* The name of a waypoint.
* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, or <code>fix</code> ghost object.
}}
===createWP()===
{{Nasal doc
|syntax = createWP(pos, name[, flag]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1964|t=Source}}
|text = Creates a new waypoint ghost object.
|param1 = pos
|param1text = Dictates the position of the new waypoint. It can be one of the following:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. See example 4 below.
|param2 = name
|param2text = String that will become the name of the new waypoint.
|param3 = flag
|param3text = Optional string that will tell FlightGear what type of waypoint it is. Must be one of "sid," "star," "approach," "missed," or "pseudo."
|example1text = Creates a waypoint directly in front and 1 km away and appends it to the flight plan.
|example1 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);
var wp = createWP(pos, "NEWWP");
var fp = flightplan();
fp.appendWP(wp);
|example2 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);
var wp = createWP({lat: pos.lat(), lon: pos.lon()}, "NEWWP");
var fp = flightplan();
fp.appendWP(wp);
|example3 = var apt = airportinfo();
var wp = createWP(apt, "NEWWP");
var fp = flightplan();
fp.appendWP(wp);
|example4 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);
var wp = createWP(pos.lat(), pos.lon(), "NEWWP");
var fp = flightplan();
fp.appendWP(wp);
|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.
|example5 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);
var wp = createWP(pos, "NEWWP", "pseudo");
var fp = flightplan();
fp.appendWP(wp);
print(fp.getPlanSize());
fp.clearWPType("pseudo");
print(fp.getPlanSize());
}}

===createWPFrom()===
{{Nasal doc
|syntax = createWPFrom(object[, flag]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1989|t=Source}}
|text = Creates a new waypoint object from another object.
|param1 = object
|param1text = A ghost object. Must be a ghost type that is one of "airport," "navaid," "runway," or "fix."
|param2 = flag
|param2text = Optional string that will tell FlightGear what type of waypoint it is. Must be one of "sid," "star," "approach," "missed," or "pseudo."
|example1text = Creates a new waypoint and appends it to the flight plan.
|example1 = var apt = airportinfo("KSFO");
var wp = createWPFrom(apt);
var fp = flightplan();
fp.appendWP(wp);
|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.
|example2 = var apt = airportinfo("KSFO");
var wp = createWPFrom(apt, "pseudo");
print(wp.wp_name);
var fp = flightplan();
fp.appendWP(wp);
print(fp.getPlanSize());
fp.clearWPType("pseudo");
print(fp.getPlanSize());
}}

===defined()===
{{Nasal doc
|syntax = defined(symbol);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = Returns 1 (true) or 0 (false) depending on whether a variable exists.
|param1 = symbol
|param1text = A string that will be what the function searches for.
|example1 = var number = 12;
var check_exist = func {
print("Variable 'number' ", defined("number") == 1 ? "exists" : "does not exist"); # 'number' does exist
print("Variable 'number2' ", defined("number2") == 1 ? "exists" : "does not exist"); # 'number2' does not exist
}
check_exist();
}}

===directory()===
{{Nasal doc
|syntax = directory(path);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=572|t=Source}}
|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.
{{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.}}
|param1 = path
|param1text = Absolute file path.
|example1text = Gets the folders and files in [[$FG_ROOT]], and then removes the extra first two elements (see note above).
|example1 = var dir = directory(getprop("/sim/fg-root")); # get directory
dir = subvec(dir, 2); # strips off the first two elements
debug.dump(dir); # dump the vector
}}

===fgcommand()===
{{Nasal doc
|syntax = fgcommand(cmd[, args]);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=456|t=Part 1}} {{!}} {{fgdata file|Nasal/globals.nas|t=Part 2}}
|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.
|param1 = cmd
|param1text = String that is the name of the command that is to be run.
|param2 = args
|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).
|example1 = fgcommand("null"); # does nothing
|example2 = var args = props.Node.new({'script': 'print("Running fgcommand");'});
if (fgcommand("nasal", args)) { # prints "Running fgcommand" and then one of these print statements
print("Fgcommand succeeded");
} else {
print("Fgcommand encountered a problem");
}
|example3 = var args = { 'dialog-name': 'about' };
fgcommand("dialog-show", args); # shows the 'about' dialog
}}

===findAirportsByICAO() ===
{{Nasal doc
|syntax = findAirportsByICAO(search[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1096|t=Source}}
|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.
|param1 = search
|param1text = Search string for the function. Can either be a partial or a full ICAO code.
:{{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.}}
|param2 = type
|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."
|example1 = var apts = findAirportsByICAO("KSF"); # finds all airports matching "KSF"
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")"); # prints them
}
|example2 = var apts = findAirportsByICAO("SP0", "seaport"); # finds all seaplane bases matching "SP0"
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")"); # prints them
}
|example3 = var apt = findAirportsByICAO("XBET"); # one way to check if an airport does exist"
if (size(apt) == 0) {
print("Airport does not exist"); # this one will be printed
} else {
print("Airport does exist");
<nowiki>}</nowiki>
}}

===findAirportsWithinRange()===
{{Nasal doc
|syntax = findAirportsWithinRange([pos, ]range[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1066|t=Source}}
|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.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findAirportsWithinRange(lat, lon, range, type);</code>.
|param2 = range
|param2text = Mandatory number giving the range in nautical miles within which to search for airports/heliports/seaplane bases.only airports are searched for.
|param3 = type
|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."
|example1text = Searches for airports within 10 nm of [[KSFO]].
|example1 = var pos = airportinfo("KSFO");
var apts = findAirportsWithinRange(pos, 10);
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")");
}
|example2text = Searches for seaplane bases within 15 nm of [[KSFO]].
|example2 = var pos = airportinfo("KSFO");
var apts = findAirportsWithinRange(pos, 15, "seaport");
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")");
}
|example3text = Searches for airports within 10 nm of your current position.
|example3 = var apts = findAirportsWithinRange(10);
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")");
<nowiki>}</nowiki>
}}

===findCommByFrequencyMHz()===
findCommByFrequencyMHz([pos, ]freq[, type]);
[[sourceforge:p/flightgear/flightgear/ci/next/tree/src/Scripting/NasalPositioned.cxx#l1547|source]]

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.

'''pos'''

: Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findCommByFrequencyMHz(lat, lon, freq, type);</code>.
; freq
: Frequency, in megahertz, of the station to search for.
; type
: 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)
'''Example'''
var com = findCommByFrequencyMHz(123.6);
print("ID: ", com.id); # prints info about the comm station
print("Name: ", com.name);
print("Latitude: ", com.lat);
print("Longitude: ", com.lon);
print("Type: ", com.type);
print("Frequency: ", sprintf("%.3f", com.frequency), " Mhz");

=== findFixesByID() ===
{{Nasal doc
|syntax = findFixesByID([pos, ]id);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1627|t=Source}}
|text = Returns a vector containing <code>fix</code> ghost objects matching a given ID, sorted by range from a certain position.
{{inote|Fixes are (usually) also known as waypoints.}}
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findFixesByID(lat, lon, id);</code>.
|param2 = id
|param2text = Full or partial ID of the fix to search for.
:{{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.}}
|example1 = var fixes = findFixesByID("POGIC");
foreach(var fix; fixes){
print(fix.id, " - lat: ", fix.lat, " {{!}} lon: ", fix.lon); # prints information about POGIC
}
|example2 = var fix = findFixesByID("ZUNAP");
fix = fix[0];
var (course, dist) = courseAndDistance(fix);
print("Turn to heading ", math.round(course), ". You have ", sprintf("%.2f", dist), " nm to go to reach ", fixes[0].id);
}}

===findNavaidByFrequencyMHz()===
{{Nasal doc
|syntax = findNavaidByFrequencyMHz([pos, ]freq[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1547|t=Source}}
|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.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidByFrequencyMHz(lat, lon, freq, type);</code>.
|param2 = freq
|param2text = Frequency, in megahertz, of the navaid to search for.
|param3 = type
|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}}.
|example1 = var navaid = findNavaidByFrequencyMHz(109.55);
print("ID: ", navaid.id); # prints info about the navaid
print("Name: ", navaid.name);
print("Latitude: ", navaid.lat);
print("Longitude: ", navaid.lon);
print("Elevation (AMSL): ", navaid.elevation, " m");
print("Type: ", navaid.type);
print("Frequency: ", sprintf("%.3f", navaid.frequency / 100), " Mhz");
print("Range: ", navaid.range_nm, " nm");
if(navaid.course) print("Course: ", navaid.course);
}}

=== findNavaidsByFrequencyMHz()===
{{Nasal doc
|syntax = findNavaidsByFrequencyMHz([pos, ]freq[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1572|t=Source}}
|text = Returns a vector conatining <code>navaid</code> ghost objects for navaids that match a given frequency, sorted from nearest to furthest.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidsByFrequencyMHz(lat, lon, freq, type);</code>.
|param2 = freq
|param2text = Frequency, in megahertz, of the navaid to search for.
|param3 = type
|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}}.
|example1 = var navaids = findNavaidsByFrequencyMHz(109.55);
foreach(var navaid; navaids){
print("--");
print("ID: ", navaid.id); # prints info about the navaid
print("Name: ", navaid.name);
print("Latitude: ", navaid.lat);
print("Longitude: ", navaid.lon);
print("Elevation (AMSL): ", navaid.elevation, " m");
print("Type: ", navaid.type);
print("Frequency: ", sprintf("%.3f", navaid.frequency / 100), " Mhz");
print("Range: ", navaid.range_nm, " nm");
if(navaid.course) print("Course: ", navaid.course);
print("--");
<nowiki>}</nowiki>
}}

===findNavaidsByID()===
{{Nasal doc
|syntax = findNavaidsByID([pos, ]id[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1600|t=Source}}
|text = Returns a vector containing <code>navaid</code> ghost objects matching a given ID, sorted by range from a certain position.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidsByID(lat, lon, id, type);</code>.
|param2 = id
|param2text = Full or partial ID of the fix to search for.
:{{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.}}
|param3 = type
|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}}.
|example1 = var navaid = findNavaidsByID("MXW");
navaid = navaid[0];
print("ID: ", navaid.id); # prints info about 'MXW' (a VOR station)
print("Name: ", navaid.name);
print("Latitude: ", navaid.lat);
print("Longitude: ", navaid.lon);
print("Elevation (AMSL): ", navaid.elevation, " m");
print("Type: ", navaid.type);
print("Frequency: ", sprintf("%.3f", navaid.frequency / 1000), " Mhz");
print("Range: ", navaid.range_nm, " nm");
}}

===findNavaidsWithinRange()===
{{Nasal doc
|syntax = findNavaidsWithinRange([pos, ]range[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1518|t=Source}}
|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.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidsWithinRange(lat, lon, range, type);</code>.
|param2 = range
|param2text = Mandatory number giving the range in nautical miles within which to search for navaids.
|param3 = type
|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}}.
|example1text = Searches for navaids within 10 nm of [[KSFO]].
|example1 = var pos = airportinfo("KSFO");
var navs = findNavaidsWithinRange(pos, 10);
foreach(var nav; navs){
print(nav.name, " (ID: ", nav.id, ")");
}
|example2text = Searches for navaids within 10 nm of your current position.
|example2 = var navs = findNavaidsWithinRange(10);
foreach(var nav; navs){
print(nav.name, " (ID: ", nav.id, ")");
<nowiki>}</nowiki>
}}

===finddata()===
{{Nasal doc
|syntax = finddata(path);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=603|t=Source}}
|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]].
|param1 = path
|param1text = A relative path as a string.
|example1 = var path = finddata("Aircraft/Generic");
print(path); # prints the absolute path to $FG_ROOT/Aircraft/Generic
|example2 = var path = finddata("Airports");
print(path); # prints the absolute path to <TerraSync dir>/Airports
|example3 = var path = finddata("preferences.xml");
print(path); # prints the absolute path to $FG_ROOT/preferences.xml
}}

===flightplan()===
{{Nasal doc
|syntax = flightplan([path]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1738|t=Source}}
|text = {{see also|Nasal Flightplan}}
Returns a flight plan object, either one for the current flight plan, or one loaded from a given path.
|param1 = path
|param1text = Optional path to flight plan XML file.
|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.
|example1 = var fp = flightplan();
print(fp.getWP(fp.current).id);
|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>.
|example2 = var path = getprop('/sim/fg-home') ~ '/fp-demo.xml';
var fp = flightplan(path);
for(var i = 0; i < fp.getPlanSize(); i += 1){
print(fp.getWP(i).id);
<nowiki>}</nowiki>
}}

===geodinfo()===
{{Nasal doc
|syntax = geodinfo(lat, lon[, max_alt]);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=981|t=Source}}
|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}}):
* '''light_coverage:''' The coverage of a single point of light in m<sup>2</sup>.
* '''bumpiness:''' Normalized bumpiness factor for the material.
* '''load_resistance:''' The amount of pressure in N/m<sup>2</sup> the material can withstand without deformation.
* '''solid:''' 1 (true) or false (0) depending on whether the material is solid or not.
* '''names:''' Vector of scenery types (usually generated by [[TerraGear]]) that will use this material.
* '''friction_factor:''' Normalized friction factor of the material.
* '''rolling_friction:''' The rolling friction coefficient of the material.

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.
|param1 = lat
|param1text = Latitude, inputted as a number.
|param2 = lon
|param2text = Longitude, inputted as a number.
|param3 = max_alt
|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.
|example1text = Dumps information about ground underneath the aircraft.
|example1 = var pos = geo.aircraft_position();
var info = geodinfo(pos.lat(), pos.lon());
debug.dump(info);
|example2text = Prints whether the ground underneath the aircraft is solid or is water.
|example2 = var pos = geo.aircraft_position();
var info = geodinfo(pos.lat(), pos.lon());
if (info != nil and info[1] != nil) {
print("The ground underneath the aircraft is ", info[1].solid == 1 ? "solid." : "water.");
<nowiki>}</nowiki>
}}

=== geodtocart() ===
{{Nasal doc
|syntax = geodtocart(lat, lon, alt);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=962|t=Source}}
|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.
|param1 = lat
|param1text = Latitude, in degrees.
|param2 = lon
|param2text = Longitude, in degrees.
|param3 = alt
|param3text = Altitude, in metres.
|example1 = var (x, y, z) = geodtocart(0, 0, 0); # point is the intersection of the prime meridian and equator.
print("x: ", x); # prints "x: 6378137"
print("y: ", y); # prints "y: 0"
print("z: ", z); # prints "y: 0"
}}

=== get_cart_ground_intersection()===
Introduced in 2017.2.1, see [[Terrain Detection]].

===getprop()===
{{Nasal doc
|syntax = <nowiki>getprop(path[, path[, ...]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=345|t=Source}}
|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).
|param1 = path
|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.
|example1 = print("You have FlightGear v", getprop("/sim/version/flightgear")); # prints FlightGear version
|example2text = Note that the example below will only work in FlightGear 3.2 and above.
|example2 = for(var i = 0; i < 8; i += 1){
print("View #", i + 1, " is named ", getprop("/sim/view", i, "name"));
}
|example3text = Same as above, but is supported by all versions of FlightGear.
|example3 = for(var i = 0; i < 8; i += 1){
print("View #", i + 1, " is named ", getprop("/sim/view[" ~ i ~ "]/name"));
<nowiki>}</nowiki>
}}
==== See also====
{{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:
To get a Node rather than its value, use <code>props.globals.getNode()</code> - see [[Nasal_library/props]]. }}

===greatCircleMove()===
{{Nasal doc
|syntax = greatCircleMove([pos, ]course, dist);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1681|t=Source}}
|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).
|param1 = pos
|param1text = Optional position to calculate from. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost object.
:* A hash with ''lat'' and ''lon'' members
:* A <code>geo.Coord</code> object
:* A lat/lon pair, that is, a pair of numbers (latitude followed by longitude) separated by a comma: <code>greatCircleMove(lat,lon, ...)</code>.
|param2 = course
|param2text = Course to new set of coordinates, in degrees (in the range 0–360).
|param3 = dist
|param3text = Distance in nautical miles to the new set of coordinates.
|example1 = var pos = greatCircleMove(0,0, 0, 1);
debug.dump(pos); # print hash with coordinates
|example2 = var fix = findFixesByID("POGIC");
fix = fix[0];
var pos = greatCircleMove(fix, 45, 10);
debug.dump(pos); # print hash with coordinates
}}

===interpolate()===
{{Nasal doc
|private = _interpolate()
|syntax = <nowiki>interpolate(prop, value1, time1[, value2, time2[, ...]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=522|t=Part 1}} {{!}} {{fgdata file|Nasal/globals.nas|t=Part 2}}
|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.
|param1 = prop
|param1text = String or <code>props.Node</code> object that indicates a node in the property tree to be used.
|param2 = value''n''
|param2text = Target value to change the property to in the set amount of time. This should be a number.
|param3 = time''n''
|param3text = Time in seconds, that will be taken for the interpolation.
|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.
|example1 = setprop("/test", 0); # (re-)set property
interpolate("/test",
50, 5, # interpolate to 50 in 5 seconds
10, 2, # interpolate to 10 in 2 seconds
0, 5); # interpolate to 0 in 5 seconds
|example2 = # Apply the left brake at 20% per second
var prop = "controls/gear/brake-left";
var dist = 1 - getprop(prop);
if (dist == 1) {
interpolate(prop, 1, dist / 0.2);
<nowiki>}</nowiki>
}}

===isa()===
{{Nasal doc
|syntax = isa(object, class);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|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.
|param1 = object
|param1text = Object to check.
|param2 = class
|param2text = Class/object to check that '''object''' inherits from or is an instance of.
|example1 = var coord = geo.Coord.new();
if(isa(coord, geo.Coord)){
print("Variable 'coord' is an instance of class 'geo.Coord'"); # this one will be printed
} else {
print("Variable 'coord' is not an instance of class 'geo.Coord'");
}
|example2 = var coord = geo.Coord.new();
if(isa(coord, props.Node)){
print("Variable 'coord' is an instance of class 'props.Node'");
} else {
print("Variable 'coord' is not an instance of class 'props.Node'"); # this one will be printed
}
|example3text = The example below demonstrates checking of inheritance.
|example3 = var Const = {
constant: 2,
getConst: func {
return me.constant;
}
};

var Add = {
new: func {
return { parents: [Add, Const] };
},

addToConst: func(a){
return a * me.getConst();
}
};

var m = Add.new();
print(m.addToConst(4));

if(isa(m, Add)) print("Variable 'm' is an instance of class 'Add'"); # will be printed
if(isa(m, Const)) print("Variable 'm' is an instance of class 'Const'"); # will also be printed
}}

===logprint()===
{{Nasal doc
|syntax = <nowiki>logprint(priority[, msg[, msg[, ...]]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=431|t=Source}}
|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}}.
|param1 = priority
|param1text = Number specifying the priority level of the outputted message:
:{{{!}} class="wikitable"
! Number !! Debug type
{{!-}}
{{!}} 1 {{!!}} Bulk
{{!-}}
{{!}} 2 {{!!}} Debug
{{!-}}
{{!}} 3 {{!!}} Info
{{!-}}
{{!}} 4 {{!!}} Warn
{{!-}}
{{!}} 5 {{!!}} Alert
{{!}}}
|param2 = msg
|param2text = The message. There is no limit to the arguments you give give. They will be concatenated together before logging.
|example1 = # logs the value of pi to three decimal places with log level 3
logprint(3, "pi = ", sprintf("%.3f", math.pi));
|example2 = logprint(5, "Alert! This is an important message!");
}}
{{note|
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:

LOG_BULK, LOG_WARN, LOG_DEBUG, LOG_INFO, LOG_ALERT, DEV_WARN, DEV_ALERT }}

===magvar() ===
{{Nasal doc
|syntax = magvar([pos]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1642|t=Source}}
|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.
{{{!}} class="wikitable"
! FlightGear versions !! Model !! Reference date
{{!-}}
{{!}} 3.6 and above {{!!}} {{wikipedia|World Magnetic Model}} (WMM) 2015 {{!!}} 1 January 2015
{{!-}}
{{!}} 0.9.11-pre1 to 3.4 {{!!}} WMM 2005 {{!!}} 1 January 2005
{{!-}}
{{!}} 0.7.3 to 0.9.10 {{!!}} WMM 2000 {{!!}} 1 January 2000
{{!}}}
|param1 = pos
|param1text = Optional position to calculate from. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost object.
:* A hash with ''lat'' and ''lon'' members
:* A <code>geo.Coord</code> object
:* A lat/lon pair, that is, a pair of numbers (latitude followed by longitude) separated by a comma: <code>magvar(lat,lon)</code>.
|example1 = print(magvar(0, 0)); # prints the magnetic variation at 0, 0
}}

===maketimer() ===
{{Nasal doc
|syntax = maketimer(interval[, self], function);
|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}}
|version = 2.12
|commit = {{flightgear commit|ab939f|t=commit}}
|text = Returns a timer object containing the following methods and members:
* '''start()''': Starts the timer.
* '''stop()''': Stops the timer.
* '''restart(interval)''': Restarts the timer with the given interval.
* '''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).
* '''isRunning''': Read-only bool telling whether the timer is currently running.
* '''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.
Unlike {{func link|settimer()}}, which it replaces, <code>maketimer()</code> provides more control over the timer. In addition, it can help reduce memory usage.
|param1 = interval
|param1text = Interval in seconds for the timer.
|param2 = self
|param2text = Optional parameter specifying what any <code>'''me'''</code> references in the function being called will refer to.
|param3 = function
|param3text = Function to be called at the given interval.
|example1 = var timer = maketimer(1, func(){
print("Hello, World!"); # print "Hello, World!" once every second (call timer.stop() to stop it)
});
timer.start();
|example2 = var timer = maketimer(1, math, func(){
print(me.math); # 'me' reference is the 'math' namespace
});
timer.singleShot = 1; # timer will only be run once
timer.start();
|example3 = var timer = maketimer(1, func(){
print("Hello, World!"); # print "Hello, World!" once every second (call timer.stop() to stop it)
});
timer.start();
print(timer.isRunning); # prints 1
|example4text = In the example below, "Hello, World!" will be printed after one second the first time, and after two seconds thereafter.
|example4 = var update = func(){
print("Hello, World!");
timer.restart(2); # restarts the timer with a two second interval
}

var timer = maketimer(1, update);
timer.singleShot = 1;
timer.start();
}}

===maketimestamp()===
{{Nasal doc
|syntax = maketimestamp()
|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}}
|version = 2019.2
|commit = {{flightgear commit|7db06300|t=commit}}
|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:
* '''stamp()''': Resets the timing operation. Call this first.
* '''elapsedMSec()''': returns number of milliseconds elapsed since stamp() called. Resolution may vary depending on platform but is usually at least millisecond accuracy.
* '''elapsedUSec()''': returns number of microseconds elapsed since stamp() called. Resolution may vary depending on platform but is usually at least millisecond accuracy.
|
|example1text = In the example below the number of milliseconds elapsed will be printed.
|example1 = var timestamp = maketimestamp();
timestamp.stamp();
print(timestamp.elapsedMSec(), "ms elapsed");
print(timestamp.elapsedMSec(), "ms elapsed");
}}

===md5()===
{{Nasal doc
|syntax = md5(string);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=758|t=Source}}
|version = 3.2
|commit = {{flightgear commit|cfbf9e|t=commit}}
|text = Returns a the {{wikipedia|MD5}} hash (as a string) of the inputted string.
|param1 = string
|param1text = String the generate the hash of. Mandatory.
|example1text = The below code should output <code>65a8e27d8879283831b664bd8b7f0ad4</code>.
|example1 = print(md5("Hello, World!"));
}}

===navinfo()===
{{Nasal doc
|syntax = navinfo(lat, lon, type, id);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1453|t=Source}}
|text = Returns vector <code>navaid</code> ghost objects matching the given '''type''' and '''id''' or <code>'''nil'''</code> on error.
|param1 = lat ''and'' lon
|param1text = If given, the returned navaids will be put into order of ascending distance from the location.
|param2 = type
|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."
|param3 = id
|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.
|example1 = navinfo("vor"); # returns all VORs
|example2 = navinfo("HAM"); # return all navaids whose names start with "HAM"
|example3 = navinfo("vor", "HAM"); # return all VORs whose names start with "HAM"
|example4 = navinfo(34,48,"vor","HAM"); # return all VORs whose names start with "HAM" and sorted by distance relative to 34°, 48°
}}

===parse_markdown()===
{{Nasal doc
|syntax = parse_markdown(markdown);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=745|t=Part 1}} {{!}} {{simgear file|simgear/misc/SimpleMarkdown.cxx|t=Part 2}}
|version = 3.2
|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:
* It strips whitespace from the beginning of the string.
* It supports [http://daringfireball.net/projects/markdown/syntax#p paragraphs and line breaks].
* It collapses whitespace.
* It converts unordered [http://daringfireball.net/projects/markdown/syntax#list lists] to use a bullet character (•). 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.
|param1 = markdown
|param1text = String containing Markdown to be parsed.
|example1text =
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>).
<syntaxhighlight lang="xml" highlight="41-50">
<?xml version="1.0" encoding="UTF-8"?>

<PropertyList>

<name>test</name>
<layout>vbox</layout>

<group>
<layout>hbox</layout>

<empty>
<stretch>true</stretch>
</empty>

<text>
<label>parse_markdown() test dialog</label>
</text>

<empty>
<stretch>true</stretch>
</empty>

<button>
<legend></legend>
<pref-width>16</pref-width>
<pref-height>16</pref-height>
<binding>
<command>dialog-close</command>
</binding>
</button>

</group>

<canvas>
<name>Canvas plot</name>
<stretch>true</stretch>
<pref-width>400</pref-width>
<pref-height>300</pref-height>
<nasal>
<load><![CDATA[
var text = 'Items:
* apples
* oranges
* pears

Some text.
Some more items:
* apples
* oranges
* pears';

var parsed = parse_markdown(text);

var root_canvas = canvas.get(cmdarg());
root_canvas.setColorBackground(255, 255, 255);
var root = root_canvas.createGroup();

var text_dis = root.createChild("text")
.setText(parsed)
.setTranslation(5, 5)
.setFont("LiberationFonts\LiberationSans-Regular.ttf")
.setFontSize(15)
.setColor(0, 0, 0)
.setDrawMode(canvas.Text.TEXT)
.setAlignment("left-top");
]]></load>
</nasal>
</canvas>

</PropertyList>
</syntaxhighlight>
|example1 = fgcommand("dialog-show", {"dialog-name": "test"});
|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.
|example2 = <nowiki>var markdown = 'Items:
* apples
* oranges
* pears

Some text.
Some more items:
* apples
* oranges
* pears';

var parsed = parse_markdown(markdown);

debug.dump(parsed);

var path = string.normpath(getprop("/sim/fg-home") ~ '/Export/parse_markdown()-test.html');

var file = io.open(path, "w");

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>";

io.write(file, html);
io.close(file);
print("Done, file ready for viewing (" ~ path ~ ")");</nowiki>
}}

===parsexml()===
{{Nasal doc
|syntax = <nowiki>parsexml(path[, start[, end[, data[, pro_ins]]]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=710|t=Source}}
|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.
|param1 = path
|param1text = Mandatory absolute path to the XML file to be parsed.
|param2 = start
|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.
|param3 = end
|param3text = Optional callback function that will be called for every ending tag. The function should take one argument: the tag name.
|param4 = data
|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.
|param5 = pro_ins
|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.
|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.
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>

<?xml-stylesheet type="text/xsl" href="style.xsl"?>

<foo>
<blah type="string"><![CDATA[ <sender>John Smith</sender> ]]></blah>
<blah2 type="string">Orange & lemons</blah2>
</foo>
</syntaxhighlight>
|example1 = var start = func(name, attr){
print("Starting tag: '", name, "'");
foreach(var a; keys(attr)){
print("\twith attribute ", a, '="', attr[a], '"');
}
}

var end = func(name){
print("Ending tag: '", name, "'");
}

var data = func(data){
print("Data = '", data, "'");
}

var pro_instr = func(target, data){
print("Processing instruction: target = '", target, "', data = '", data, "'");
}

parsexml(getprop("/sim/fg-home") ~ '/Export/demo.xml', start, end, data, pro_instr);
}}

===print()===
{{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.

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>}}

{{Nasal doc
|syntax = <nowiki>print(data[, data[, ...]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=415|t=Source}}
|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.
|param1 = data
|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.
|example1 = print("Just", " a ", "test"); # prints "Just a test"
|example2 = print("pi = ", math.pi); # prints "pi = 3.141592..."
}}

=== printf() ===
{{Nasal doc
|syntax = <nowiki>printf(format[, arg[, arg, [...]]]);</nowiki>
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|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>).
|example1 = printf("In hexadecimal, 100000 = %X", 186A0); # prints "In hexadecimal, 100000 = 186A0"
}}

===printlog()===
{{caution|This function is deprecated and doesn't work. Please use the new one {{func link|logprint()}}.}}
{{Nasal doc
|syntax = <nowiki>printlog(level, data[, data[, ...]]);</nowiki>
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|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.
|param1 = level
|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.
|param2 = data
|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.
|example1 = printlog("alert", "This is an alert"); # message will be printed
|example2 = printlog("info", "Just informing you about something"); # message will be printed only if log level is set to "info" or less
}}

===rand()===
{{Nasal doc
|syntax = rand();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=554|t=Source}}
|text = Returns a random floating point number between 0 (inclusive) and 1 (exclusive). It takes no arguments.
|example1 = print(rand()); # prints random number
}}

===registerFlightPlanDelegate()===
{{Nasal doc
|syntax = registerFlightPlanDelegate(init_func);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1879|t=Source}}
|text = Registers a flight plan delegate. See <tt>''{{fgdata file|Nasal/route_manager.nas|t=$FG_ROOT/Nasal/route_manager.nas}}''</tt> for examples.
|param1 = init_func
|param1text = Initialization function which will be called during FlightGear's startup.
}}
===removecommand()===
{{Nasal doc
|syntax = removecommand(cmd);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=668|t=Source}}
|text = Removes the given fgcommand. Returns <code>'''nil'''</code>.
{{caution|This will remove '''any''' [[fgcommands|fgcommand]], even those implemented in C++, so use with caution!}}
|param1 = cmd
|param1text = String specifying the name of the command to remove.
|example1 = addcommand("hello", func(){
print("Hello");
});
fgcommand("hello"); # "Hello" will be printed
removecommand("hello"); # removes it
}}

===removelistener()===
{{Nasal doc
|syntax = removelistener(id);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=1384|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=506|t=Part 2}}
|text = Removes and deactivates the given listener and returns the number of listeners left or <code>'''nil'''</code> on error.
{{note|It is good practice to remove listeners when they are not required anymore. This prevents the listeners reducing FlightGear's run performance.}}
|param1 = id
|param1text = ID of listener as returned by {{func link|setlistener()}}.
|example1 = var ls = setlistener("/sim/test", func(){
print("Property '/sim/test' has been changed");
});
setprop("/sim/test", "blah"); # trigger listener
var rem = removelistener(ls); # remove listener
print("There are ", rem, " listeners remaining");
}}

===resolvepath()===
{{Nasal doc
|syntax = resolvepath(path);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=604|t=Source}}
|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.
|param1 = path
|param1text = Relative path to be completed.
|example1 = print(resolvepath("Nasal/globals.nas")); # prints the equivalent of $FG_ROOT/Nasal/globals.nas
|example2 = print(resolvepath("blah")); # prints nothing; could not be resolved
|example3 = var file_path = resolvepath("Aircraft/SenecaII/some-file");
if (file_path != ""){
gui.popupTip("some-file found", 2);
} else {
gui.popupTip("some-file not found", 2);
<nowiki>}</nowiki>
}}

===setlistener()===
{{Nasal doc
|syntax = <nowiki>setlistener(node, code[, init[, type]]);</nowiki>
|private = _setlistener()
|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.''
|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()}}.
{{note|Listeners are known to be a source of resource leaks. To avoid this, please take measures such as:
* Using {{func link|removelistener()}} when they are not needed any more.
* Using a single initialization listener.
* Avoiding tying listeners to properties that are rapidly updated (e.g., many times per frame).
}}
|param1 = node
|param1text = Mandatory string or <code>props.Node</code> object pointing to a property in the [[Property Tree]].
|param2 = code
|param2text = Mandatory callback function to execute when the listener is triggered. The function can take up to four arguments in the following order:
* '''changed''': a <code>props.Node</code> object pointing to the changed node.
* '''listen''': a <code>props.Node</code> object pointing to the listened-to node. Note that this argument maybe different depending on the '''type'''.
* '''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.
* '''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.
|param3 = init
|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).
|param4 = type
|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.
|example1 = var prop = props.globals.initNode("/sim/test", "", "STRING"); # create property
var id = setlistener("/sim/test", func(n){ # create listener
print("Value: ", n.getValue());
});
setprop("/sim/test", "blah"); # trigger listener
removelistener(id); # remove listener
prop.remove(); # remove property
}}

===setprop()===
{{Nasal doc
|syntax = <nowiki>setprop(path[, path[, ...]], value);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=385|t=Source}}
|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.
{{note|If you want to remove a property, you will have to use one of the <code>props</code> helpers:
<syntaxhighlight lang="nasal">
props.globals.getNode("foo/bar").remove(); # take out the complete node
props.globals.getNode("foo").removeChild("bar"); # take out a certain child node
</syntaxhighlight>
}}
|param1 = path
|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.
|param2 = value
|param2text = Value to write to the given property. Must be either a string or a number.
|example1 = setprop("/sim/demo", "This is a demo");
|example2text = Note that the example below will only work in FlightGear 3.2 and above.
|example2 = for(var i = 0; i < 3; i += 1){
setprop("/sim/demo", i, "Demo #" ~ i));
}
|example3text = Same as above, but is supported by all versions of FlightGear.
|example3 = for(var i = 0; i < 3; i += 1){
setprop("/sim/demo[" ~ i ~ "]", "Demo #" ~ i));
<nowiki>}</nowiki>
}}
====See also====
{{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:
To get a Node rather than its value, use <code>props.globals.getNode()</code> - see [[Nasal_library/props]]. }}

===settimer() ===
{{Nasal doc
|syntax = settimer(function, delta[, realtime]);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=499|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=1286|t=Part 2}}
|text = Runs the given function a specified amount of seconds after the current time. Returns <code>'''nil'''</code>.
{{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.}}
|param1 = function
|param1text = Mandatory function that will be called. It may be necessary to enclose code in an anonymous function (see example).
|param2 = delta
|param2text = Mandatory amount of time in seconds after which the function will be called.
|param3 = realtime
|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.
|example1 = var myFunc = func(){
print("Hello");
}

settimer(myFunc, 2); # runs myFunc after 2 seconds
|example2 = var sqr = func(a){
return a * a;
}

settimer(func(){
print(sqr(2)); # will print 4 after 2 seconds
}, 2);
}}

===srand() ===
{{Nasal doc
|syntax = srand();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=559|t=Source}}
|text = Makes the pseudorandom number generator (see {{func link|rand()}}) generate a new {{wikipedia|random seed|noicon=1}} based on time. Returns 0.
}}
===systime()===
{{Nasal doc
|syntax = systime();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=770|t=Source}}
|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).
{{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]}}
|example1 = print("Unix time: ", systime()); # prints Unix time
|example2 = var myFunc = func(){
for(var i = 0; i <= 10; i += 1){
print("Interation #", i);
}
}
var t = systime(); # record time
myFunc(); # run function
var t2 = systime(); # record new time
print("myFunc() took ", t2 - t, " seconds"); # print result
}}

===thisfunc()===
{{Nasal doc
|syntax = thisfunc();
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = Returns the function from which this function is called. This allows a function to reliably and safely call itself from within a closure.
|example1 = var stringify_vec = func(input){
if (typeof(input) == "scalar"){
return sprintf("%s", input);
} elsif (typeof(input) == "vector") {
if (size(input) == 0) return "[]";
var this = thisfunc();
var buffer = "[";
for(var i = 0; i < size(input); i += 1){
buffer ~= this(input[i]);
if (i == size(input) - 1) {
buffer ~= "]";
} else {
buffer ~= ", ";
}
}
return buffer;
} else {
die("stringify_vec(): Error! Invalid input. Must be a vector or scalar");
}
}

var test_vec = ["a", "b", "c", [1, 2, 3], "d"];
debug.dump(stringify_vec(test_vec)); # prints "[a, b, c, [1, 2, 3], d]"
test_vec = [];
debug.dump(stringify_vec(test_vec)); # prints "[]"
test_vec = {};
debug.dump(stringify_vec(test_vec)); # will throw an error
}}

===tileIndex() ===
{{Nasal doc
|syntax = tileIndex();
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1720|t=Source}}
|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>.
|example1 = print(tileIndex()); # print index
}}

=== tilePath()===
{{Nasal doc
|syntax = tilePath();
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1712|t=Source}}
|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>.
|example1 = print(tilePath()); # print path
}}

=== values()===
{{Nasal doc
|syntax = values(hash);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = Returns a vector containing the values of the given hash.
|param1 = hash
|param1text = Mandatory hash to get the values of.
|example1 = var hash = {
"a": 1,
"b": 2,
"c": 3
};

foreach(var val; values(hash)){
print(val);
}
|example2text = The below example does exactly the same thing as the above example, but does not use <code>values()</code>:
|example2 = var hash = {
"a": 1,
"b": 2,
"c": 3
};

foreach(var key; keys(hash)){
print(hash[key]);
<nowiki>}</nowiki>
}}

==Extension functions new in FG 2020.1 ==
The following functions have been added to the nasal core library and will be released with FlightGear version 2020.1.
Before the release they are available in the development branch "next".

===isfunc()===
Returns 1 if type or argument is a function, otherwise 0.

===isghost()===
Returns 1 if type or argument is a ghost, otherwise 0.

=== ishash()===
Returns 1 if type or argument is a hash, otherwise 0.

===isint()===
{{Nasal doc
|syntax = isint(x);
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}
|text = Returns 1 if argument has a numeric value and x == floor(x), e.g. integer.
}}

===isnum()===
{{Nasal doc
|syntax = isnum(x);
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}
|text = Returns 1 if typeof(x) is "scalar" and x has a numeric value otherwise 0.
}}

===isscalar()===
{{Nasal doc
|syntax = isscalar(x);
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}
|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 "~".
|example1 = var a = "foo";
var b=42;
if (isscalar(a) and isscalar(b)) print(a~b);
if (isstr(a)) print("a is a string");
if (isint(b)) print("b is an integer");
# if (isscalar(a))... is equivalent to if (typeof(a) == "scalar")...
}}

===isstr()===
Returns 1 if type or argument is a string, otherwise 0.

===isvec()===
Returns 1 if type or argument is a vector, otherwise 0.

===vecindex()===
{{Nasal doc
|syntax = vecindex(vector, value);
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}
|text = Returns the index of value or nil, if value is not found in vector.
|example1=
var myvector = ["apple", "bananna", "coconut"];
# to check if a vector contains a certain value compare vecindex to nil
if (vecindex(myvector, "apple") != nil) {
print("found apple");
}
# WARNING: this will not work as desired because index is 0
if (vecindex(myvector, "apple")) {
print("found apple");
<nowiki>}</nowiki>

}}

==Variables==
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}}.

===D2R===
{{Nasal doc
|syntax = var radians = degrees * D2R;
|text = Converts an angle from degrees to radians when multiplied by the angle in degrees. Equal to <code>π / 180</code>.
}}
===FPS2KT===
{{Nasal doc
|syntax = var knots = feet_per_second * FPS2KT;
|text = Converts a velocity from feet per second to knots when multiplied by the velocity in feet per second. Approximately equal to 0.5925.
}}
===FT2M===
{{Nasal doc
|syntax = var metres = feet * FT2M;
|text = Converts a length from feet to metres when multiplied by the length in feet. Equal to 0.3048.
}}
===GAL2L ===
{{Nasal doc
|syntax = var litres = gallons * GAL2L;
|text = Converts a volume from US liquid gallons to litres when multiplied by the volume in gallons. Approximately equal to 3.7854.
}}
===IN2M===
{{Nasal doc
|syntax = var metres = inches * IN2M;
|text = Converts a length from inches to metres when multiplied by the length in inches. Equal to 0.0254.
}}
===KG2LB===
{{Nasal doc
|syntax = var pounds = kilograms * KG2LB;
|text = Converts a mass from kilograms to pounds when multiplied by the mass in kilograms. Approximately equal to 2.2046.
}}
===KT2FPS===
{{Nasal doc
|syntax = var feet_per_second = knots * KT2FPS;
|text = Converts a velocity from knots to feet per second when multiplied by the velocity in knots. Approximately equal to 1.6878.
}}
===KT2MPS===
{{Nasal doc
|syntax = var metres_per_second = knots * KT2MPS;
|text = Converts a velocity from knots to metres per second when multiplied by the velocity in knots. Approximately equal to 0.5144.
}}
===L2GAL===
{{Nasal doc
|syntax = var gallons = litres * L2GAL;
|text = Converts a volume from litres to US liquid gallons when multiplied by the volume in litres. Approximately equal to 0.2642.
}}
===LB2KG===
{{Nasal doc
|syntax = var kilograms = pounds * LB2KG;
|text = Converts a mass from pounds to kilograms when multiplied by the mass in pounds. Approximately equal to 0.4536.
}}
===M2FT ===
{{Nasal doc
|syntax = var feet = metres * M2FT;
|text = Converts a length from metres to feet when multiplied by the length in metres. Approximately equal to 3.2808.
}}
===M2IN===
{{Nasal doc
|syntax = var inches = metres * M2IN;
|text = Converts a length from metres to inches when multiplied by the length in metres. Approximately equal to 39.3701.
}}
===M2NM ===
{{Nasal doc
|syntax = var nautical_miles = metres * M2NM;
|text = Converts a length from metres to nautical miles when multiplied by the length in metres. Approximately equal to 0.00054.
}}
===MPS2KT ===
{{Nasal doc
|syntax = var knots = metres_per_second * MPS2KT;
|text = Converts a velocity from metres per second to knots when multiplied by the velocity in metres per second. Approximately equal to 1.9438.
}}
===NM2M ===
{{Nasal doc
|syntax = var metres = nautical_miles * NM2M;
|text = Converts a length from nautical miles to metres when multiplied by the length in nautical miles. Equal to 1,852.
}}
===R2D===
{{Nasal doc
|syntax = var degrees = radians * R2D;
|text = Converts an angle from radians to degrees when multiplied by the angle in radians. Equal to <code>180 / π</code>.
}}

{{Appendix}}

{{Nasal namespaces}}

Nasal library

2025-12-04T12:39:58Z

PlayeRom: /* str() */

{{Nasal Navigation|nocat=1}}
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:
* {{flightgear file|src/Scripting}}
* {{simgear file|simgear/nasal}}

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]].

{{tip|Copy & paste the examples into your [[Nasal Console]] and execute them to see what they do.|width=70%}}

== Core library functions ==
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:
* http://plausible.org/nasal/lib.html ([http://web.archive.org/web/20101010094553/http://plausible.org/nasal/lib.html archive])
* {{simgear file|simgear/nasal/lib.c}} ([http://sourceforge.net/p/flightgear/simgear/ci/next/log/?path=/simgear/nasal/lib.c history])

=== append() ===
{{Nasal doc
|syntax = append(vector, element[, element[, ...]]);
|source = {{simgear file|simgear/nasal/lib.c|l=45|t=Source}}
|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.
|param1 = vector
|param1text = The vector to which the arguments will be appended.
|param2 = element
|param2text = An element to be added to the vector.
|example1 =
var vector = [1, 2, 3]; # Initialize the vector
append(vector, 4); # Append the number 4 to the end of the vector
debug.dump(vector); # Print the contents of the vector
|example2 =
var vector = [1, 2, 3]; # Initialize the vector
append(vector, 4, 5, 6); # Append the numbers 4, 5, and 6 to the end of the vector
debug.dump(vector); # Print the contents of the vector
}}

=== bind() ===
{{Nasal doc
|syntax = bind(function, locals[, outer_scope]);
|source = {{simgear file|simgear/nasal/lib.c|l=638|t=Source}}
|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.
|param1 = function
|param1text = Function to evaluate.
|param2 = locals
|param2text = Hash containing values that will become the namespace (first closure) for the function.
|param3 = outer_scope
|param3text = Optional function which is bound to the next closure. This can be bound to yet another, making a linked list.
|example1 = # This is a namespace/hash with a single member, named "key," which is initialized to 12
var Namespace = {
key: 12
};

# This is different namespace/hash containing a function
# dividing a variable "key" (which is unavailable/nil in this namespace) by 2
var AnotherNamespace = {
ret: func {
key /= 2;
}
};

# To see that key is not available, try to call AnotherNamespace.ret() first
call(AnotherNamespace.ret, [], nil, nil, var errors = []);
if(size(errors)){
print("Key could not be divided/resolved!");
debug.printerror(errors);
}

# Associate the AnotherNamespace.ret() function with the first namespace
# so that "key" is now available
var function = bind(AnotherNamespace.ret, Namespace);

# Invoke the new function
function();

# Print out the value of Namespace.key
# It was changed to 12 from 6 by AnotherNamespace.ret()
print(Namespace.key);
}}

=== call() ===
{{Nasal doc
|syntax = call(func[, args[, me[, locals[, error]]]);
|source = {{simgear file|simgear/nasal/lib.c|l=376|t=Source}}
|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.
|param1 = func
|param1text = Function to execute.
|param2 = args
|param2text = Vector containing arguments to give to the called function.
|param3 = me
|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).
|param4 = locals
|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.
|param5 = error
|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}}.
|example1 =
# prints "Called from call()"
call(func {
print("Called from call()");
});
|example2 =
# prints "a = 1 : b = 2
call(func(a, b){
print("a = ", a, " : b = ", b);
},
[1, 2]
);
|example3 =
var Hash = {
new: func {
var m = { parents: [Hash] };

m.el1 = "string1";
m.el2 = "string2";

return m;
}
};

# prints "me.el1 = string1", then "me.el2 = string2" on the next line
call(func(a, b){
print("me.el", a, " = ", me["el" ~ a]);
print("me.el", b, " = ", me["el" ~ b]);
},
[1, 2],
Hash.new()
);
|example4 =
# prints the value of math.pi
call(func {
print(pi);
}, nil, nil,
math
);
|example5 =
call(func {
print(math.ip); # math.ip doesn't exist
}, nil, nil, nil,
var errs = []
);
debug.printerror(errs); # The error is caught and printed using debug.printerror()
}}

=== caller() ===
{{Nasal doc
|syntax = caller([level]);
|source = {{simgear file|simgear/nasal/lib.c|l=540|t=Source}}
|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 '''[0]''' a hash of local variables, '''[1]''' the function object, '''[2]''' the full source file name (incl. path) and '''[3]''' the line number.
|param1 = level
|param1text = Optional integer specifying the stack level to return a result from. Defaults to 1 (i.e. the caller of the currently executing function).
|example1 =
var myFunction = func(a, b) {
debug.dump(caller(0)[0]); # prints a hash of local variables, including arguments a and b
return 2 * 2;
};

print("2 x 2 = ", myFunction(2, 2));
|example2 =
var get_arg_value = func() {
print("Argument to myFunc = ", caller(1)[0]['a']); # print the value of myFunc's single argument, using caller()
};

var myFunc = func(a) {
get_arg_value();
};

myFunc(3);
|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: true, zindex: nil }</code>.
|example3 =
var MapStructure_selfTest = func() {
var temp = {};
temp.dlg = canvas.Window.new([600, 400], "dialog");
temp.canvas = temp.dlg.createCanvas().setColorBackground(1, 1, 1, 0.5);
temp.root = temp.canvas.createGroup();

var testMap = temp.root.createChild("map");
testMap.setController("Aircraft position");
testMap.setRange(25); # TODO: implement zooming/panning via mouse/wheel here, for lack of buttons :-/
testMap.setTranslation(
temp.canvas.get("view[0]") / 2,
temp.canvas.get("view[1]") / 2,
);

var r = func(name, vis = true, zindex = nil) {
return caller(0)[0];
}

# TODO: we'll need some z-indexing here, right now it's just random
# TODO: use foreach/keys to show all layers in this case by traversing SymbolLayer.registry directly ?
# maybe encode implicit z-indexing for each lcontroller ctor call ? - i.e. preferred above/below order ?
var types = [
r('TFC', false),
r('APT'),
r('DME'),
r('VOR'),
r('NDB'),
r('FIX', false),
r('RTE'),
r('WPT'),
r('FLT'),
r('WXR'),
r('APS'),
];

foreach (var type; types) {
testMap.addLayer(
factory: canvas.SymbolLayer,
type_arg: type.name,
visible: type.vis,
priority: type.zindex,
);
}
}; # MapStructure_selfTest
}}

=== chr() ===
{{Nasal doc
|syntax = chr(code);
|source = {{simgear file|simgear/nasal/lib.c|l=240|t=Source}}
|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.}}
{{{!}} class="wikitable"
! Code !! Name !! Equivalent to
{{!-}}
{{!}} 10 {{!!}} {{Wikipedia|Newline}} {{!!}} <code>\n</code>
{{!-}}
{{!}} 9 {{!!}} {{Wikipedia|Tab key#Tab characters|Horizontal tab}} {{!!}} <code>\t</code>
{{!-}}
{{!}} 13 {{!!}} {{Wikipedia|Carriage return}} {{!!}} <code>\r</code>
{{!}}}
|param1 = code
|param1text = Integer character code for the desired glyph.
|example1 = print("Code 65 = ", chr(65)); # prints "Code 65 = A"
|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.
|example2 =
for(var i = 0; i <= 255; i += 1){
print("Code ", i, " = >", chr(i), "<");
}
}}

=== closure() ===
{{Nasal doc
|syntax = closure(func[, level]);
|source = {{simgear file|simgear/nasal/lib.c|l=557|t=Source}}
|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'''.
|param1 = func
|param1text = Function to evaluate.
|param2 = level
|param2text = Optional integer specifying the scope level. Defaults to 0 (the namespace of '''func''').
|example1 =
var get_math_e = func {
return e; # return the value of math.e
}

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
debug.dump(closure(myFunction)); # print the namespace of get_math_e

print(myFunction());
}}

=== cmp() ===
{{Nasal doc
|syntax = cmp(a, b);
|source = {{simgear file|simgear/nasal/lib.c|l=169|t=Source}}
|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'''.
|param1 = a
|param1text = First string argument for comparison.
|param2 = b
|param2text = Second string argument for comparison.
|example1 = print(cmp("1", "two")); # prints -1
|example2 = print(cmp("string", "string")); # prints 0
|example3 = print(cmp("one", "2")); # prints 1
|example4 = print(cmp("string1", "string2")); # prints -1
}}

=== compile() ===
{{Nasal doc
|syntax = compile(code[, filename]);
|source = {{simgear file|simgear/nasal/lib.c|l=349|t=Source}}
|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'''.
|param1 = code
|param1text = String containing Nasal code to be compiled.
|param2 = filename
|param2text = Optional string used for error messages/logging. Defaults to <code><compile></code>
|example1 =
var myCode = 'print("hello");';
var helloFunc = compile(myCode, "myCode");
helloFunc();
|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>.
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<PropertyList>

<nasal><![CDATA[
print("You have FlightGear v", getprop("/sim/version/flightgear"));
]]></nasal>

</PropertyList>
</syntaxhighlight>
Now, start FlightGear and execute this code in the [[Nasal Console]].
|example2 =
# Build the path
var FGRoot = getprop("/sim/fg-root");
var filename = "/gui/dialogs/test.xml";
var path = FGRoot ~ filename;

var blob = io.read_properties(path);
var script = blob.getValues().nasal; # Get the nasal string

# Compile the script. We're passing the filename here for better runtime diagnostics
var code = call(func {
compile(script, filename);
}, nil, nil, var compilation_errors = []);

if(size(compilation_errors)){
die("Error compiling code in: " ~ filename);
}

# Invoke the compiled script, equivalent to code();
# We're using call() here to detect errors:
call(code, [], nil, nil, var runtime_errors = []);

if(size(runtime_errors)){
die("Error calling code compiled loaded from: " ~ filename);
}
|example3text = The <code>compile()</code> function also allows you to parse a JSON string into a hash. Simplest example:
|example3 =
var jsonFunc = compile('{"version":"1.2.0","author":{"name":"John"} }');
var json = jsonFunc(); # return hash
logprint(LOG_ALERT, json["version"]); # print "1.2.0"
logprint(LOG_ALERT, json["author"]["name"]); # print "John"
}}

=== contains() ===
{{Nasal doc
|syntax = contains(hash, key);
|source = {{simgear file|simgear/nasal/lib.c|l=249|t=Source}}
|text = Returns 1 (True) if the hash contains the specified key, or 0 (False) if not.
|param1 = hash
|param1text = The hash to search in.
|param2 = key
|param2text = The scalar to be searched for, contained as a key in the hash.
|example1 =
# Initialize a hash
var hash = {
element: "value"
};
print(contains(hash, "element") ? "Yes" : "No"); # This will print "Yes"
print(contains(hash, "element2") ? "Yes" : "No"); # This will print "No"
}}

===contains()===
{{Requires commit|desc=Vector support|details=see {{Merge-request|project=fgdata|id=305}}|commit=ee39abbd3b70c9b6d5e3a1c4ccedddaac1a92b11|repo=Simgear}}
{{Nasal doc
|syntax = contains(vector, item);
|source = {{simgear file|simgear/nasal/lib.c|l=249|t=Source}}
|text = Returns 1 (True) if the vector contains the specified item, or 0 (False) if not.
|param1 = vector
|param1text = The vector to search in.
|param2 = item
|param2text = The object to be searched for in the vector.
|example1 =
# Initialize a vector
var vec = ["element", "foo"];
print(contains(vec, "element") ? "Yes" : "No"); # This will print "Yes"
print(contains(vec, "element2") ? "Yes" : "No"); # This will print "No"
}}

===delete() ===
{{Nasal doc
|syntax = delete(hash, key);
|source = {{simgear file|simgear/nasal/lib.c|l=118|t=Source}}
|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.
|param1 = hash
|param1text = The hash from which to delete the key.
|param2 = key
|param2text = The scalar to be deleted, contained as a key in the hash.
|example1 =
# Initialize the hash
var hash = {
element1: "value1",
element2: "value2"
};
delete(hash, "element1"); # Delete element1
debug.dump(hash); # prints the hash, which is now minus element1
}}

===die()===
{{Nasal doc
|syntax = die(error);
|source = {{simgear file|simgear/nasal/lib.c|l=417|t=Source}}
|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()}}.
|param1 = error
|param1text = String describing the error.
:{{inote|This parameter is technically optional, but it is highly recommended to use it.}}
|example1 =
print("Will print");
die("Don't go any further!");
print("Won't print"); # Will not be printed because die() stops the process
}}

=== find()===
{{Nasal doc
|syntax = find(needle, haystack);
|source = {{simgear file|simgear/nasal/lib.c|l=586|t=Source}}
|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.
|param1 = needle
|param1text = String to search for.
|param2 = haystack
|param2text = String to search in.
|example1 = print(find("c", "abcdef")); # prints 2
|example2 = print(find("x", "abcdef")); # prints -1
|example3 = print(find("cd", "abcdef")); # prints 2
}}

===ghosttype()===
{{Nasal doc
|syntax = ghosttype(ghost);
|source = {{simgear file|simgear/nasal/lib.c|l=336|t=Source}}
|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.
|param1 = ghost
|param1text = Ghost to return a description for.
|example1 = print(ghosttype(airportinfo())); # prints "airport"
}}

===id()===
{{Nasal doc
|syntax = id(object);
|source = {{simgear file|simgear/nasal/lib.c|l=706|t=Source}}
|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.
|param1 = object
|param1text = Can be either of a string, a vector, a hash, a code, a function, or a ghost.
|example1 = print(id("A")); # prints "str:000000001624A590"
}}

===int() ===
{{Nasal doc
|syntax = int(number);
|source = {{simgear file|simgear/nasal/lib.c|l=125|t=Source}}
|text = Returns the integer part of the numeric value of the single argument, or <code>'''nil'''</code> if none exists.
|param1 = number
|param1text = Number or string with just a number in it to return an integer from.
|example1 = print(int(23)); # prints "23"
|example2 = print(int(23.123)); # prints "23"
|example3 = debug.dump(int("string")); # prints "nil"
}}

===keys()===
{{Nasal doc
|syntax = keys(hash);
|source = {{simgear file|simgear/nasal/lib.c|l=36|t=Source}}
|text = Returns a vector containing the list of keys found in the single hash argument.
|param1 = hash
|param1text = The hash to return the keys from.
|example1 =
# Initialize a hash
var hash = {
element1: "value",
element2: "value"
};
debug.dump(keys(hash)); # print the vector
}}

===left()===
{{Nasal doc
|syntax = left(string, length);
|source = {{simgear file|simgear/nasal/lib.c|l=214|t=Source}}
|version = 2.12
|commit = {{simgear commit|bd7163|t=commit}}
|text = Returns a substring of '''string''', starting from the left.
|param1 = string
|param1text = String to return part of.
|param2 = length
|param2text = Integer specifying the length of the substring to return.
|example1 = print(left("string", 2)); # prints "st"
}}

=== num()===
{{Nasal doc
|syntax = num(number);
|source = {{simgear file|simgear/nasal/lib.c|l=149|t=Source}}
|text = Returns the numerical value of the single string argument, or <code>'''nil'''</code> if none exists.
|param1 = number
|param1text = String with just a number in it to return a number from.
|example1 = print(num("23")); # prints "23"
|example2 = print(num("23.123")); # prints "23.123"
|example3 = debug.dump(num("string")); # prints "nil"
}}

===pop()===
{{Nasal doc
|syntax = pop(vector);
|source = {{simgear file|simgear/nasal/lib.c|l=85|t=Source}}
|text = Removes and returns the last element of the single vector argument, or <code>'''nil'''</code> if the vector is empty.
|param1 = vector
|param1text = Vector to remove an element from.
|example1 =
var vector = [1, 2, 3];
pop(vector);
debug.dump(vector); # prints "[1, 2]"
|example2 =
var vector = [1, 2, 3];
debug.dump(pop(vector)); # prints "3"
|example3 =
var vector = [];
debug.dump(pop(vector)); # prints "nil"
}}

=== range() ===
{{Nasal doc
|syntax = range([start, ]stop[, step]);
|source = {{simgear file|simgear/nasal/lib.c|l=756|t=Source}}
|text = Creates a vector of numbers starting from <code>start</code> (default 0) up to but not including <code>stop</code>, incremented by <code>step</code> (default 1). Note: To specify <code>step</code>, you must also provide <code>start</code>; otherwise the second argument is interpreted as <code>stop</code>.
|param1 = start
|param1text = Optional. The starting number of the sequence. Defaults to 0 if omitted. Required if you want to specify <code>step</code>.
|param2 = stop
|param2text = Required. The number at which to stop the sequence (not included).
|param3 = step
|param3text = Optional. The increment between each number in the sequence. Defaults to 1. Only valid if <code>start</code> is also specified.
|example1 =
var vec = range(5); # Creates a vector [0, 1, 2, 3, 4]
var vec = range(2, 5); # Creates a vector [2, 3, 4]
var vec = range(0, 10, 2); # Creates a vector [0, 2, 4, 6, 8]
var vec = range(0, 0); # Creates an empty vector []
var vec = range(0, 1); # Creates a vector [0]
}}

=== remove() ===
{{Nasal doc
|syntax = remove(vector, value);
|source = {{simgear file|simgear/nasal/lib.c|l=53|t=Source}}
|text = Removes all elements equal to the given value from a vector and returns the modified vector.
|param1 = vector
|param1text = The vector from which elements are to be removed.
|param2 = value
|param2text = A value to remove from the vector.
|example1 =
var vector = [1, 2, 3]; # Initialize the vector.
remove(vector, 2); # Remove the value 2 from the vector.
debug.dump(vector); # Print the contents of the vector: "[1, 3]".
|example2 =
var vector = ["text", "text", "text"]; # Initialize the vector.
remove(vector, "text"); # Remove the value "text" from the vector.
debug.dump(vector); # Print the contents of the vector: "[]".
}}

=== removeat() ===
{{Nasal doc
|syntax = removeat(vector, index);
|source = {{simgear file|simgear/nasal/lib.c|l=72|t=Source}}
|text = Removes the element at the specified index from the vector and returns it.
|param1 = vector
|param1text = The vector from which the element will be removed.
|param2 = index
|param2text = Index of the item to be deleted.
|example1 =
var vector = [1, 2, 3]; # Initialize the vector.
removeat(vector, 0); # Remove the index 0 from the vector.
debug.dump(vector); # Print the contents of the vector: "[2, 3]".
}}

===right()===
{{Nasal doc
|syntax = right(string, length);
|source = {{simgear file|simgear/nasal/lib.c|l=226|t=Source}}
|version = 2.12
|commit = {{simgear commit|bd7163|t=commit}}
|text = Returns a substring of '''string''', starting from the right.
|param1 = string
|param1text = String to return part of.
|param2 = length
|param2text = Integer specifying the length of the substring to return.
|example1 = print(right("string", 2)); # prints "ng"
}}

=== setsize()===
{{Nasal doc
|syntax = setsize(vector, size);
|source = {{simgear file|simgear/nasal/lib.c|l=91|t=Source}}
|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.
|param1 = vector
|param1text = The vector to be operated on.
|param2 = size
|param2text = The desired size of the vector in number of entries.
|example1 =
var vector = [1, 2, 3]; # Initialize a vector
setsize(vector, 4);
debug.dump(vector); # print the vector "[1, 2, 3, nil]"
|example2 =
var vector = [1, 2, 3]; # Initialize a vector
setsize(vector, 2);
debug.dump(vector); # print the vector "[1, 2]"
}}

===size()===
{{Nasal doc
|syntax = size(object);
|source = {{simgear file|simgear/nasal/lib.c|l=26|t=Source}}
|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>.
|param1 = object
|param1text = Object to find the size of. Must be a string, a vector or a hash.
|example1 =
var string = "string";
print(size(string)); # prints "6"
|example2 =
var vector = [1, 2, 3];
print(size(vector)); # prints "3"
|example3 =
var hash = {
element1: "value1",
element2: "value2",
element3: "value3"
};
print(size(hash)); # prints "3"
}}

=== sort()===
{{Nasal doc
|syntax = sort(vector, function);
|source = {{simgear file|simgear/nasal/lib.c|l=678|t=Source}}
|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.
|param1 = vector
|param1text = Input vector to sort.
|param2 = function
|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.
{{{!}} class="wikitable"
! Return value !! Meaning
{{!-}}
{{!}} less than 0 {{!!}} first argument should go before second argument
{{!-}}
{{!}} 0 {{!!}} first argument equals second argument
{{!-}}
{{!}} greater than 0 {{!!}} first argument should go after second argument
{{!}}}

|example1text = This example sorts elements from smallest to greatest.
|example1 =
var sort_rules = func(a, b) {
if (a < b) {
return -1; # A should before b in the returned vector
} elsif (a == b) {
return 0; # A is equivalent to b
} else {
return 1; # A should after b in the returned vector
}
}
debug.dump(sort([3, 2, 5, 6, 4, 1], sort_rules)); # prints "[1, 2, 3, 4, 5, 6]"
|example2text = This example sorts elements from greatest to smallest.
|example2 =
# Outputs the elements in reverse order (greatest to smallest)
var sort_rules = func(a, b) {
if (a < b) {
return 1; # -1 in the above example
} elsif (a == b) {
return 0;
} else {
return -1; # 1 in the above example
}
}
debug.dump(sort([3, 2, 5, 6, 4, 1], sort_rules)); # prints "[6, 5, 4, 3, 2, 1]"
|example3text = This example sorts a vector of strings (runways for example) from smallest to greatest.
|example3 =
var runways = ["09R", "27R", "26L", "09L", "15"];
var rwy = sort(runways, func(a, b) cmp(a, b));
debug.dump(rwy); # prints ['09L', '09R', '15', '26L', '27R']
}}

=== split()===
{{Nasal doc
|syntax = split(delimiter, string);
|source = {{simgear file|simgear/nasal/lib.c|l=596|t=Source}}
|text = Splits the input string into a vector of substrings bounded by occurrences of the delimiter substring. See [[Nasal_library/string#string.join(sep,list)|string.join()]].
|param1 = delimiter
|param1text = String that will split the substrings in the returned vector.
|param2 = string
|param2text = String to split up.
|example1 = debug.dump(split("cd", "abcdef")); # prints "['ab', 'ef']"
|example2 = debug.dump(split(".", "3.2.0")); # prints "[3, 2, 0]"
|example3 = debug.dump(split("/", "path/to/file")); # prints "['path', 'to', 'file']"
}}

===sprintf()===
{{Nasal doc
|syntax = <nowiki>sprintf(format[, arg[, arg, [...]]]);</nowiki>
|source = {{simgear file|simgear/nasal/lib.c|l=491|t=Source}}
|text = Creates and returns a string formatted using ANSI C {{func link|vsnprintf()|link=http://en.cppreference.com/w/c/io/vfprintf}} <ref>
{{Cite web
|url = http://sourceforge.net/p/flightgear/simgear/ci/next/tree/simgear/nasal/lib.c#l308
|title = fgdata/simgear/simgear/nasal/lib.c, line 308
|accessdate = October 2015
}}
</ref>. Below is a table of supported format specifiers.
{{{!}} class="wikitable" width="75%"
{{!}}+ %[flags][width][.precision]specifier
! colspan="2" {{!}} Flags
{{!-}}
! Flag !! Output
{{!-}}
{{!}} <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.
{{!-}}
{{!}} ''space'' {{!!}} Prefixes non-signed numbers with a space.
{{!-}}
{{!}} <code>-</code> {{!!}} Left-align the output of this placeholder (the default is to right-align the output) when the width option is specified.
{{!-}}
{{!}} <code>0</code> {{!!}} Use 0 instead of spaces to pad a field when the width option is specified.
{{!-}}
{{!}} <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.
{{!-}}
! colspan="2" {{!}} Width
{{!-}}
{{!}} 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.
{{!-}}
! colspan="2" {{!}} Precision
{{!-}}
{{!}} colspan="2" {{!}} Integer preceded by a dot specifying the number of decimal places to be written.
{{!-}}
! colspan="2" {{!}} Specifiers
{{!-}}
! Specifier !! Output
{{!-}}
{{!}} <code>d</code>, <code>i</code> {{!!}} Signed decimal number.
{{!-}}
{{!}} <code>s</code> {{!!}} A string
{{!-}}
{{!}} <code>%</code> {{!!}} Percent (%) character.
{{!-}}
{{!}} <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.
{{!-}}
{{!}} <code>o</code> {{!!}} Unsigned integer as an octal number.
{{!-}}
{{!}} <code>u</code> {{!!}} Unsigned decimal integer.
{{!-}}
{{!}} <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.
{{!-}}
{{!}} <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.
{{!-}}
{{!}} <code>f</code> {{!!}} Floating-point number, in fixed decimal notation, by default with 6 decimal places.
{{!-}}
{{!}} <code>F</code> {{!!}} Appears to be available<ref>
{{Cite web
|url = http://sourceforge.net/p/flightgear/simgear/ci/next/tree/simgear/nasal/lib.c#l389
|title = fgdata/simgear/simgear/nasal/lib.c, line 389
|accessdate = October 2015
}}
</ref>, but doesn't work.
{{!-}}
{{!}} <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.
{{!}}}

|param1 = format
|param1text = String specifying the format. Can be used with or without a format specifiers. See below for examples.
|param2 = arg
|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.

|example1 = print(sprintf("%i", 54)); # prints "54"
|example2 = print(sprintf("Pi = %+.10f", math.pi)); # prints "Pi = +3.1415926536"
|example3 =
print(sprintf("%6d", 23)); # prints " 23"
print(sprintf("%06d", 23)); # prints "000023"
|example4 =
var FGVer = getprop("/sim/version/flightgear");
print(sprintf("You have FlightGear v%s", FGVer)); # prints "You have FlightGear v<your version>"
|example5 =
print(sprintf("Hexadecimal 100000 = %X", 100000)); # prints "Hexadecimal 100000 = 186A0"
print(sprintf("Hexadecimal 100000 = %x", 100000)); # prints "Hexadecimal 100000 = 186a0"
|example6 = print(sprintf("Code 65 is %c", 65)); # prints "Code 65 is A"
|example7 =
print(sprintf("%e", 54)); # prints "5.400000e+001"
print(sprintf("%E", 54)); # prints "5.400000E+001"
|example8 = print(sprintf("%o", 54)); # prints "66"
|example9 = print(sprintf("50%% of 100 is %i", 100 / 2)); # prints "50% of 100 is 50"
|example10 =
print(sprintf("%.2f", 1.4)); # prints "1.40"
print(sprintf("%.1f", 1.4)); # prints "1.4"
print(sprintf("% 4.1f", 1.4)); # prints " 1.4"
print(sprintf("%04.1f", 1.4)); # prints "01.4"
print(sprintf("% 6.1f", 1.4)); # prints " 1.4"
print(sprintf("%06.1f", 1.4)); # prints "0001.4"
}}

===str()===
{{Nasal doc
|syntax = str(value);
|source = {{simgear file|simgear/nasal/lib.c|l=186|t=Source}}
|text = Convert given value (scalar) to string. If <code>value</code> is a number, it will be converted to a string. If <code>value</code> is a string, the same string will be returned. If <code>value</code> is not a scalar (hash, vector, nil), <code>nil</code> will be returned.
|param1 = value
|param1text = The value to convert to string.
|example1 =
var result = str(true); # result is a string "1"
var result = str(false); # result is a string "0"
var result = str(12); # result is a string "12"
var result = str(12.5); # result is a string "12.5"
var result = str(-12.5); # result is a string "-12.5"
var result = str("12.5"); # result is a string "12.5"
var result = str([1, 2]); # result is a nil
var result = str({ x: 0 }); # result is a nil
var result = str(nil); # result is a nil
}}

===streq()===
{{Nasal doc
|syntax = streq(a, b);
|source = {{simgear file|simgear/nasal/lib.c|l=164|t=Source}}
|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.}}
|param1 = a
|param1text = First argument for testing equality.
|param2 = b
|param2text = Second argument for testing equality.
|example1 = print(streq("0", "0")); # prints "1" (True)
|example2 =
print(0 == 0.0); # prints "1" (True)
print(streq("0", "0.0")); # prints "0" (False)
}}

===substr()===
{{Nasal doc
|syntax = substr(string, start [, length]);
|source = {{simgear file|simgear/nasal/lib.c|l=194|t=Source}}
|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).
|param1 = string
|param1text = String to return a substring from.
|param2 = start
|param2text = Integer specifying the start of a substring. Negative values specify a position from the end of the string.
|param3 = length
|param3text = Optional argument specifying the length of the substring. Defaults to the end of the string.
|example1 = print(substr("abcde", 1, 3)); # prints "bcd"
|example2 = print(substr("abcde", 1)); # prints "bcde"
|example3 = print(substr("abcde", 2, 1)); # prints "c"
|example4 = print(substr("abcde", -2)); # prints "de"
|example5 = print(substr("abcde", -3, 2)); # prints "cd"
}}

===subvec()===
{{Nasal doc
|syntax = subvec(vector, start[, length]);
|source = {{simgear file|simgear/nasal/lib.c|l=98|t=Source}}
|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).
|param1 = vector
|param1text = The vector to take the sub-vector from.
|param2 = start
|param2text = The starting point of the sub-vector within the given vector.
|param3 = length
|param3text = Optional argument specifying the length of the sub-vector, from the starting point.
'''Notes:'''
* Omitting the ''vector'' and ''start'' arguments is not an error (possibly it should be) but the return value is ''nil''.
* A negative ''start'' argument ''is'' an error. This seems wrong. Perhaps the language designer could comment.
* A value of ''start'' greater than ''size(vector)'' causes an error. A value equal to ''size(vector)'' returns an empty vector.
* 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.
|example1 =
var vector = [1, 2, 3];
debug.dump(subvec(vector, 0)); # prints "[1, 2, 3]"
|example2 =
var vector = [1, 2, 3];
debug.dump(subvec(vector, 1)); # prints "[2, 3]"
|example3 =
var vector = [1, 2, 3];
debug.dump(subvec(vector, 1, 1)); # prints "[2]"
}}

=== typeof()===
{{Nasal doc
|syntax = typeof(object);
|source = {{simgear file|simgear/nasal/lib.c|l=287|t=Source}}
|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.
|param1 = object
|param1text = Object to return the type of.
|example1 =
var object = nil;
print(typeof(object)); # prints "nil"
|example2 =
var object = "Hello world!";
print(typeof(object)); # prints "scalar"
|example3 =
var object = math.pi;
print(typeof(object)); # prints "scalar"
|example4 =
var object = [1, 2, 3];
print(typeof(object)); # prints "vector"
|example5 =
var object = {};
print(typeof(object)); # prints "hash"
|example6 =
var object = func {};
print(typeof(object)); # prints "func"
|example7 =
var object = airportinfo();
print(typeof(object)); # prints "ghost"
}}



==Extension functions==
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:
*{{flightgear file|src/Scripting/NasalPositioned.cxx}}
*{{flightgear file|src/Scripting/NasalSys.cxx}}
*{{fgdata file|Nasal/globals.nas}}

===abort()===
{{Nasal doc
|syntax = abort();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=565|t=Source}}
|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).
|example1text = This example will immediately stop FlightGear with an error, such as "FlightGear has stopped working."
|example1 = abort();
|example2text = For exiting FlightGear in a better way, please use the following code:
|example2 = fgcommand("exit");
}}

=== abs() ===
{{Nasal doc
|syntax = abs(number);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = This simple function returns the {{wikipedia|absolute value|noicon=1}} of the provided number.
|param1 = number
|param1text = This argument is required and should be a number.
|example1 = print(abs(1)); # prints "1"
|example2 = print(abs(-1)); # prints "1"
}}

===aircraftToCart() ===
This new function in FG 2017.2.1 takes coordinates in aircraft structural coordinate system, and translate them into geocentric coordinates.
Example for (5,6,7):
<syntaxhighlight lang="nasal">
var pos = aircraftToCart({x: -5, y: 6, z: -7});
var coord = geo.Coord.new();
coord.set_xyz(pos.x, pos.y, pos.z);
</syntaxhighlight>
Notice: x and z is inverted sign on purpose.
if you want lat. lon, alt from that, just call: (degrees and meters)

<syntaxhighlight lang="nasal">
coord.lat()
coord.lon()
coord.alt()
</syntaxhighlight>

===addcommand() ===
{{Nasal doc
|syntax = addcommand(name, code);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=659|t=Source}}
|version = 2.12
|commit = {{flightgear commit|7b663c|t=commit}}
|text = {{see also|Howto:Add new fgcommands to FlightGear}}

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.
|param1 = name
|param1text = This will become the name of the new fgcommand. Must be a string.
|param2 = code
|param2text = The code that will be executed when the fgcommand is run. Must be a function.
|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.
|example1 = addcommand("myFGCmd", func(node) {
print("fgcommand 'myFGCmd' has been run.");
props.dump( node );
});
fgcommand("myFGCmd", props.Node.new({foo:1, bar:2}) );
|example2text = This example demonstrates how parameters are defined in a new fgcommand.
|example2 = addcommand("myFGCmd", func(node){
print(node.getNode("number").getValue()); # prints the value of "number," which is 12
});
fgcommand("myFGCmd", props.Node.new({"number": 12}));
}}

===airportinfo()===
{{Nasal doc
|syntax = airportinfo();
airportinfo(type);
airportinfo(id);
airportinfo(lat, lon[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1024|t=Source}}
|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:
* '''parents''': A vector containing a hash of various functions to access information about the runway. These functions are:
** '''findBestRunwayForPos()''' return runway as ghost by given geo position, e.g. <code>var rwy = airportinfo().findBestRunwayForPos(geo.aircraft_position());</code>.
** '''runway()''' return runway as ghost by runway ID, e.g. <code>var rwy = airportinfo().runway("18R");</code>.
** '''runwaysWithoutReciprocals()''' return vector of runways as ghost.
** '''helipad()''' return helipad as ghost by helipad ID, e.g. <code>var heli = airportinfo().helipad("H19");</code>.
** '''tower()''' return hash with <code>lat</code>, <code>lon</code>, <code>elevation</code> fields.
** '''comms()''' return vector of hashes, each hash with <code>frequency</code> and <code>ident</code> fields.
** '''sids()''' return vector of strings with SID IDs.
** '''stars()''' return vector of strings with STAR IDs.
** '''getApproachList()''' return vector of string with approaches.
** '''parking()''' return vector of hashes, each hash with <code>lat</code>, <code>lon</code>, <code>elevation</code>, <code>name</code> fields.
** '''getSid()''' return SID as ghost, e.g. <code>var sid = airportinfo().getSid("SA1A");</code>.
** '''getStar()''' return STAR as ghost, e.g. <code>var star = airportinfo().getStar("KEILA1");</code>.
** '''getIAP()''' return IAP as ghost, e.g. <code>var iap = airportinfo().getIAP("ILS02");</code>.
** '''getApproach()''' return approach as ghost, e.g. <code>var approach = airportinfo().getApproach("ILS02");</code>.
** '''tostring()''' just return string "an airport ICAO".
** See also {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1902}}.
* '''lon''': Longitude of the location.
* '''lat''': Latitude of the location.
* '''has_metar''': True or false depending whether the airport has a [[METAR]] code defined for it.
* '''elevation''': Elevation of the location in metres.
* '''id''': ICAO code of the airport (or ID of the seaplane base/heliport).
* '''name''': Name of the airport/heliport/seaplane base.
* '''runways'''
** '''<runway name>'''
*** '''id''': Name of runway.
*** '''lat''': Latitude of the runway.
*** '''lon''': Longitude of the runway.
*** '''heading''': True heading of the runway.
*** '''length''': Length of the runway in metres.
*** '''width''': Width of the runway in metres.
*** '''surface''': Runway surface type.
*** '''threshold''': Length of the runway's {{wikipedia|displaced threshold}} in metres. Will return 0 if there is none.
*** '''stopway''': Length of the runway's stopway (the area before the threshold) in metres. Will return 0 if there is none.
*** '''reciprocal''': <code>runway</code> ghost of the reciprocal runway.
*** '''ils_frequency_mhz''': ILS frequency in megahertz.
*** '''ils''': <code>navaid</code> ghost of the ILS transmitter.
* '''helipads'''
** '''<helipad name>'''
*** '''id''': Name of helipad.
*** '''lat''': Latitude of the helipad.
*** '''lon''': Longitude of the helipad.
*** '''heading''': True heading of the helipad.
*** '''length''': Length of the helipad in metres.
*** '''width''': Width of the helipad in metres.
*** '''surface''': Helipad surface type.
* '''taxiways'''
** '''<taxiway name>'''
*** '''id''': Name of taxiway.
*** '''lat''': Latitude of the taxiway.
*** '''lon''': Longitude of the taxiway.
*** '''heading''': Heading of the taxiway.
*** '''length''': Length of the taxiway in metres.
*** '''width''': Width of the taxiway in metres.
*** '''surface''': Taxiway surface type.

Information is extracted in the same way as accessing members of a Nasal hash. For example:
<syntaxhighlight lang="nasal">
# prints to lengths of the runways of the nearest airport in feet and metres
var info = airportinfo();
print("-- Lengths of the runways at ", info.name, " (", info.id, ") --");
foreach(var rwy; keys(info.runways)){
print(rwy, ": ", math.round(info.runways[rwy].length * M2FT), " ft (", info.runways[rwy].length, " m)");
}
</syntaxhighlight>

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.
|param1 = id
|param1text = The {{wikipedia|International Civil Aviation Organization airport code|ICAO code|noicon=1}} of an airport to retrieve information about.
|param2 = type
|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).
: {{inote|Running this function without any parameters is equivalent to this:
: <syntaxhighlight lang="nasal">
airportinfo("airport");
</syntaxhighlight>
}}
|param3 = lat ''and'' lon
|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.
|example1 = var info = airportinfo();
print("Nearest airport: ", info.name, " (", info.id, ")"); # prints the name and ICAO code of the nearest airport
|example2 = var info = airportinfo("heliport");
print("Elevation of the nearest heliport: ", math.round(info.elevation * M2FT), " ft"); # prints the elevation and name of the nearest heliport
|example3 = var info = airportinfo("KSQL");
print("-- Runways of ", info.name, " (", info.id, "): --");
foreach(var rwy; keys(info.runways)) {
print(rwy); # prints the runways of KSQL
}
|example4 = var info = airportinfo(37.81909385, -122.4722484);
print("Coordinates of the nearest airport: ", info.lat, ", ", info.lon); # print the name and ICAO of the nearest airport to the Golden Gate Bridge
|example5 = var info = airportinfo(37.81909385, -122.4722484, "seaport");
print("Nearest seaplane base: ", info.name, " (", info.id, ")"); # print the name and ID of the nearest seaplane base to the Golden Gate Bridge
|example6text = This example prints the all information from an <code>airportinfo()</code> call.
|example6 = var info = airportinfo("KSFO");
print(info.name);
print(info.id);
print(info.lat);
print(info.lon);
print(info.has_metar);
print(info.elevation);
foreach(var rwy; keys(info.runways)){
print("-- ", rwy, " --");
print(info.runways[rwy].lat);
print(info.runways[rwy].lon);
print(info.runways[rwy].length);
print(info.runways[rwy].width);
print(info.runways[rwy].heading);
print(info.runways[rwy].stopway);
print(info.runways[rwy].threshold);
<nowiki>}</nowiki>
}}

===airwaysRoute() ===
{{Nasal doc
|syntax = airwaysRoute(start, end[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1933|t=Source}}
|text = {{see also|Nasal Flightplan}}
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.
|param1 = start
|param1text = Start waypoint, in the form of a waypoint ghost, such as that provided by {{func link|flightplan()}}.
|param2 = end
|param2text = Same as above.
|param3 = type
|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."
|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.
|example1 = var fp = flightplan();
var start = fp.getWP(0);
var end = fp.getWP(fp.getPlanSize() - 1);
var rt = airwaysRoute(start, end);
foreach(var wp; rt){
print(wp.wp_name); # print the waypoints in the computed route
}
|example2text = Exactly the same as above, but computes a low level path.
|example2 = var fp = flightplan();
var start = fp.getWP(0);
var end = fp.getWP(fp.getPlanSize() - 1);
var rt = airwaysRoute(start, end, "lowlevel");
foreach(var wp; rt){
print(wp.wp_name); # print the waypoints in the computed route
<nowiki>}</nowiki>
}}

===airway()===

{{Nasal doc
|syntax = airway(ident [, pos]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2644|t=Source}}
|text = {{see also|Nasal Flightplan}}
This function returns a ghost containing an airway of a specified id.
|param1 = ident
|param1text = a Positioned ghost (leg, navaid, airport) and so on, passed to the search function.
|param2 = pos
}}

===assert()===
{{Nasal doc
|syntax = assert(condition[, message]);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|version = 3.2
|commit = {{fgdata commit|8b16a7|t=commit}}
|text = Returns either true if the condition evaluates as true, or aborts with a {{func link|die()}} call, which can be customised.
|param1 = condition
|param1text = Condition to evaluate.
|param2 = message
|param2text = Optional message that will be used in any {{func link|die()}} call. Defaults to "assertion failed!"
|example1 = var a = 1;
var b = 2;
print(assert(a < b)); # prints "1" (true)
|example2 = var a = 1;
var b = 2;
assert(a > b, 'a is not greater than b'); # aborts with a custom error message
}}

===carttogeod()===
{{Nasal doc
|syntax = carttogeod(x, y, z);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=945|t=Source}}
|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>
|param1 = x
|param1text = Mandatory x-axis value, in metres.
|param2 = y
|param2text = Mandatory y-axis value, in metres.
|param3 = z
|param3text = Mandatory z-axis value, in metres.
|example1 = var (lat, lon, alt) = carttogeod(6378137, 0, 0); # point is the intersection of the prime meridian and equator.
print("Latitude: ", lat); # prints lat, lon and alt, which are all zero, see above
print("Longitude: ", lon);
print("Altitude: ", alt);
}}

===cmdarg()===
{{Nasal doc
|private = _cmdarg()
|syntax = cmdarg();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=513|t=Part 1}} {{!}} {{fgdata file|Nasal/globals.nas|t=Part 2}}
|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.
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:
* Bindings: This is needed so that the value of a joystick's axis can be accessed internally.
* 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).
* 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.
* 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>

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.

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.
|example1 = fgcommand("dialog-show", {"dialog-name": "cmdarg-demo"});
|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.
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>

<PropertyList>

<name>cmdarg-demo</name>
<layout>vbox</layout>

<text>
<label>Click "Close" to activate the demonstration (a message in the console).</label>
</text>

<button>
<legend>Close</legend>
<binding>
<command>nasal</command>
<script>print("Button binding root: '" ~ cmdarg().getPath() ~ "'");</script>
</binding>
<binding>
<command>dialog-close</command>
</binding>
</button>

</PropertyList>
</syntaxhighlight>
|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!"
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>

<PropertyList>

<name>cmdarg-demo</name>
<layout>vbox</layout>

<text>
<label>Click "Click me!" to activate the demonstration (the button's label will change).</label>
</text>

<button>
<legend>Click me!</legend>
<binding>
<command>nasal</command>
<script>change_label();</script>
</binding>
</button>

<button>
<legend>Close</legend>
<binding>
<command>dialog-close</command>
</binding>
</button>

<nasal>
<open><![CDATA[
var dlg_root = cmdarg();
var dlg_name = {"dialog-name": "cmdarg-demo"};
var change_label = func {
dlg_root.getNode("button[0]/legend").setValue("I've been changed!");
fgcommand("dialog-close", dlg_name);
fgcommand("dialog-show", dlg_name);
}
]]></open>
</nasal>

</PropertyList>
</syntaxhighlight>
|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]].
}}

===courseAndDistance()===
{{Nasal doc
|syntax = courseAndDistance(to);
courseAndDistance(from, to);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1668|t=Source}}
|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:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object with geodetic coordinates (cartesian coordinates will not be accepted)
|param1 = from
|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.
|param2 = to
|param2text = Like the first parameter, but defines the second point.
|example1text = This example demonstrates the usage of the function with the <code>airport</code> ghost type.
|example1 = var from = airportinfo("KSFO");
var to = airportinfo("KSQL");
var (course, dist) = courseAndDistance(from, to);
print(course); # prints course from KSFO to KSQL
print(dist); # prints distance in nm from KSFO to KSQL
|example2text = This example demonstrates the usage of the function with hashes containing ''lat'' and ''lon''.
|example2 = var from = {lat: 0, lon: 0};
var to = {lat: 1, lon: 1};
var (course, dist) = courseAndDistance(from, to);
print(course);
print(dist);
|example3text = This example demonstrates usage of a geo.Coord object.
|example3 = var from = geo.Coord.new().set_latlon(0, 0);
var to = geo.Coord.new().set_latlon(1, 1);
var (course, dist) = courseAndDistance(from, to);
print(course);
print(dist);
|example4text = This example demonstrates usage of differing parameter types.
|example4 = var from = airportinfo("KSFO");
var to = geo.Coord.new().set_latlon(0, 0);
var (course, dist) = courseAndDistance(from, to);
print(course);
print(dist);
|example5text = The same as above, but the other way round.
|example5 = var to = {lat: 1, lon: 1};
var (course, dist) = courseAndDistance(0, 0, to);
print(course);
print(dist);
|example6text = Usage of just one parameter.
|example6 = var dest = airportinfo("KSQL");
var (course, dist) = courseAndDistance(dest);
print("Turn to heading ", math.round(course), ". You have ", sprintf("%.2f", dist), " nm to go");
}}

===createFlightplan()===
{{Nasal doc
|syntax = createFlightplan(path);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2331|t=Source}}
|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.
|param1 = path
|param1text = Optional parameter defining the file from which a flightplan will be populated.
|example1 =
var path = getprop("/sim/fg-home") ~ "/Export/test.fgfp";
var flightplan = createFlightplan(path);
debug.dump(flightplan);
}}

===createDiscontinuity()===
{{Nasal doc
|syntax = createDiscontinuity();
|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.
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2045|t=Source}}
|version = 2016.1
|commit = {{flightgear commit|caead6|t=commit}}
}}
===createViaTo()===
{{Nasal doc
|syntax = createViaTo(airway, waypoint);
|text = Returns a <code>waypoint</code> ghost object. It represents a route "via '''airway''' to '''waypoint'''".
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2009|t=Source}}
|version = 2016.1
|commit = {{flightgear commit|caead6|t=commit}}
|param1 = airway
|param1text = The name of an airway.
|param2 = waypoint
|param2text = Must be in the airway and one of:
* The name of a waypoint.
* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, or <code>fix</code> ghost object.
}}
===createWP()===
{{Nasal doc
|syntax = createWP(pos, name[, flag]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1964|t=Source}}
|text = Creates a new waypoint ghost object.
|param1 = pos
|param1text = Dictates the position of the new waypoint. It can be one of the following:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. See example 4 below.
|param2 = name
|param2text = String that will become the name of the new waypoint.
|param3 = flag
|param3text = Optional string that will tell FlightGear what type of waypoint it is. Must be one of "sid," "star," "approach," "missed," or "pseudo."
|example1text = Creates a waypoint directly in front and 1 km away and appends it to the flight plan.
|example1 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);
var wp = createWP(pos, "NEWWP");
var fp = flightplan();
fp.appendWP(wp);
|example2 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);
var wp = createWP({lat: pos.lat(), lon: pos.lon()}, "NEWWP");
var fp = flightplan();
fp.appendWP(wp);
|example3 = var apt = airportinfo();
var wp = createWP(apt, "NEWWP");
var fp = flightplan();
fp.appendWP(wp);
|example4 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);
var wp = createWP(pos.lat(), pos.lon(), "NEWWP");
var fp = flightplan();
fp.appendWP(wp);
|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.
|example5 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);
var wp = createWP(pos, "NEWWP", "pseudo");
var fp = flightplan();
fp.appendWP(wp);
print(fp.getPlanSize());
fp.clearWPType("pseudo");
print(fp.getPlanSize());
}}

===createWPFrom()===
{{Nasal doc
|syntax = createWPFrom(object[, flag]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1989|t=Source}}
|text = Creates a new waypoint object from another object.
|param1 = object
|param1text = A ghost object. Must be a ghost type that is one of "airport," "navaid," "runway," or "fix."
|param2 = flag
|param2text = Optional string that will tell FlightGear what type of waypoint it is. Must be one of "sid," "star," "approach," "missed," or "pseudo."
|example1text = Creates a new waypoint and appends it to the flight plan.
|example1 = var apt = airportinfo("KSFO");
var wp = createWPFrom(apt);
var fp = flightplan();
fp.appendWP(wp);
|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.
|example2 = var apt = airportinfo("KSFO");
var wp = createWPFrom(apt, "pseudo");
print(wp.wp_name);
var fp = flightplan();
fp.appendWP(wp);
print(fp.getPlanSize());
fp.clearWPType("pseudo");
print(fp.getPlanSize());
}}

===defined()===
{{Nasal doc
|syntax = defined(symbol);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = Returns 1 (true) or 0 (false) depending on whether a variable exists.
|param1 = symbol
|param1text = A string that will be what the function searches for.
|example1 = var number = 12;
var check_exist = func {
print("Variable 'number' ", defined("number") == 1 ? "exists" : "does not exist"); # 'number' does exist
print("Variable 'number2' ", defined("number2") == 1 ? "exists" : "does not exist"); # 'number2' does not exist
}
check_exist();
}}

===directory()===
{{Nasal doc
|syntax = directory(path);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=572|t=Source}}
|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.
{{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.}}
|param1 = path
|param1text = Absolute file path.
|example1text = Gets the folders and files in [[$FG_ROOT]], and then removes the extra first two elements (see note above).
|example1 = var dir = directory(getprop("/sim/fg-root")); # get directory
dir = subvec(dir, 2); # strips off the first two elements
debug.dump(dir); # dump the vector
}}

===fgcommand()===
{{Nasal doc
|syntax = fgcommand(cmd[, args]);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=456|t=Part 1}} {{!}} {{fgdata file|Nasal/globals.nas|t=Part 2}}
|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.
|param1 = cmd
|param1text = String that is the name of the command that is to be run.
|param2 = args
|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).
|example1 = fgcommand("null"); # does nothing
|example2 = var args = props.Node.new({'script': 'print("Running fgcommand");'});
if (fgcommand("nasal", args)) { # prints "Running fgcommand" and then one of these print statements
print("Fgcommand succeeded");
} else {
print("Fgcommand encountered a problem");
}
|example3 = var args = { 'dialog-name': 'about' };
fgcommand("dialog-show", args); # shows the 'about' dialog
}}

===findAirportsByICAO() ===
{{Nasal doc
|syntax = findAirportsByICAO(search[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1096|t=Source}}
|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.
|param1 = search
|param1text = Search string for the function. Can either be a partial or a full ICAO code.
:{{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.}}
|param2 = type
|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."
|example1 = var apts = findAirportsByICAO("KSF"); # finds all airports matching "KSF"
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")"); # prints them
}
|example2 = var apts = findAirportsByICAO("SP0", "seaport"); # finds all seaplane bases matching "SP0"
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")"); # prints them
}
|example3 = var apt = findAirportsByICAO("XBET"); # one way to check if an airport does exist"
if (size(apt) == 0) {
print("Airport does not exist"); # this one will be printed
} else {
print("Airport does exist");
<nowiki>}</nowiki>
}}

===findAirportsWithinRange()===
{{Nasal doc
|syntax = findAirportsWithinRange([pos, ]range[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1066|t=Source}}
|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.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findAirportsWithinRange(lat, lon, range, type);</code>.
|param2 = range
|param2text = Mandatory number giving the range in nautical miles within which to search for airports/heliports/seaplane bases.only airports are searched for.
|param3 = type
|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."
|example1text = Searches for airports within 10 nm of [[KSFO]].
|example1 = var pos = airportinfo("KSFO");
var apts = findAirportsWithinRange(pos, 10);
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")");
}
|example2text = Searches for seaplane bases within 15 nm of [[KSFO]].
|example2 = var pos = airportinfo("KSFO");
var apts = findAirportsWithinRange(pos, 15, "seaport");
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")");
}
|example3text = Searches for airports within 10 nm of your current position.
|example3 = var apts = findAirportsWithinRange(10);
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")");
<nowiki>}</nowiki>
}}

===findCommByFrequencyMHz()===
findCommByFrequencyMHz([pos, ]freq[, type]);
[[sourceforge:p/flightgear/flightgear/ci/next/tree/src/Scripting/NasalPositioned.cxx#l1547|source]]

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.

'''pos'''

: Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findCommByFrequencyMHz(lat, lon, freq, type);</code>.
; freq
: Frequency, in megahertz, of the station to search for.
; type
: 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)
'''Example'''
var com = findCommByFrequencyMHz(123.6);
print("ID: ", com.id); # prints info about the comm station
print("Name: ", com.name);
print("Latitude: ", com.lat);
print("Longitude: ", com.lon);
print("Type: ", com.type);
print("Frequency: ", sprintf("%.3f", com.frequency), " Mhz");

=== findFixesByID() ===
{{Nasal doc
|syntax = findFixesByID([pos, ]id);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1627|t=Source}}
|text = Returns a vector containing <code>fix</code> ghost objects matching a given ID, sorted by range from a certain position.
{{inote|Fixes are (usually) also known as waypoints.}}
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findFixesByID(lat, lon, id);</code>.
|param2 = id
|param2text = Full or partial ID of the fix to search for.
:{{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.}}
|example1 = var fixes = findFixesByID("POGIC");
foreach(var fix; fixes){
print(fix.id, " - lat: ", fix.lat, " {{!}} lon: ", fix.lon); # prints information about POGIC
}
|example2 = var fix = findFixesByID("ZUNAP");
fix = fix[0];
var (course, dist) = courseAndDistance(fix);
print("Turn to heading ", math.round(course), ". You have ", sprintf("%.2f", dist), " nm to go to reach ", fixes[0].id);
}}

===findNavaidByFrequencyMHz()===
{{Nasal doc
|syntax = findNavaidByFrequencyMHz([pos, ]freq[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1547|t=Source}}
|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.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidByFrequencyMHz(lat, lon, freq, type);</code>.
|param2 = freq
|param2text = Frequency, in megahertz, of the navaid to search for.
|param3 = type
|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}}.
|example1 = var navaid = findNavaidByFrequencyMHz(109.55);
print("ID: ", navaid.id); # prints info about the navaid
print("Name: ", navaid.name);
print("Latitude: ", navaid.lat);
print("Longitude: ", navaid.lon);
print("Elevation (AMSL): ", navaid.elevation, " m");
print("Type: ", navaid.type);
print("Frequency: ", sprintf("%.3f", navaid.frequency / 100), " Mhz");
print("Range: ", navaid.range_nm, " nm");
if(navaid.course) print("Course: ", navaid.course);
}}

=== findNavaidsByFrequencyMHz()===
{{Nasal doc
|syntax = findNavaidsByFrequencyMHz([pos, ]freq[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1572|t=Source}}
|text = Returns a vector conatining <code>navaid</code> ghost objects for navaids that match a given frequency, sorted from nearest to furthest.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidsByFrequencyMHz(lat, lon, freq, type);</code>.
|param2 = freq
|param2text = Frequency, in megahertz, of the navaid to search for.
|param3 = type
|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}}.
|example1 = var navaids = findNavaidsByFrequencyMHz(109.55);
foreach(var navaid; navaids){
print("--");
print("ID: ", navaid.id); # prints info about the navaid
print("Name: ", navaid.name);
print("Latitude: ", navaid.lat);
print("Longitude: ", navaid.lon);
print("Elevation (AMSL): ", navaid.elevation, " m");
print("Type: ", navaid.type);
print("Frequency: ", sprintf("%.3f", navaid.frequency / 100), " Mhz");
print("Range: ", navaid.range_nm, " nm");
if(navaid.course) print("Course: ", navaid.course);
print("--");
<nowiki>}</nowiki>
}}

===findNavaidsByID()===
{{Nasal doc
|syntax = findNavaidsByID([pos, ]id[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1600|t=Source}}
|text = Returns a vector containing <code>navaid</code> ghost objects matching a given ID, sorted by range from a certain position.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidsByID(lat, lon, id, type);</code>.
|param2 = id
|param2text = Full or partial ID of the fix to search for.
:{{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.}}
|param3 = type
|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}}.
|example1 = var navaid = findNavaidsByID("MXW");
navaid = navaid[0];
print("ID: ", navaid.id); # prints info about 'MXW' (a VOR station)
print("Name: ", navaid.name);
print("Latitude: ", navaid.lat);
print("Longitude: ", navaid.lon);
print("Elevation (AMSL): ", navaid.elevation, " m");
print("Type: ", navaid.type);
print("Frequency: ", sprintf("%.3f", navaid.frequency / 1000), " Mhz");
print("Range: ", navaid.range_nm, " nm");
}}

===findNavaidsWithinRange()===
{{Nasal doc
|syntax = findNavaidsWithinRange([pos, ]range[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1518|t=Source}}
|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.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidsWithinRange(lat, lon, range, type);</code>.
|param2 = range
|param2text = Mandatory number giving the range in nautical miles within which to search for navaids.
|param3 = type
|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}}.
|example1text = Searches for navaids within 10 nm of [[KSFO]].
|example1 = var pos = airportinfo("KSFO");
var navs = findNavaidsWithinRange(pos, 10);
foreach(var nav; navs){
print(nav.name, " (ID: ", nav.id, ")");
}
|example2text = Searches for navaids within 10 nm of your current position.
|example2 = var navs = findNavaidsWithinRange(10);
foreach(var nav; navs){
print(nav.name, " (ID: ", nav.id, ")");
<nowiki>}</nowiki>
}}

===finddata()===
{{Nasal doc
|syntax = finddata(path);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=603|t=Source}}
|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]].
|param1 = path
|param1text = A relative path as a string.
|example1 = var path = finddata("Aircraft/Generic");
print(path); # prints the absolute path to $FG_ROOT/Aircraft/Generic
|example2 = var path = finddata("Airports");
print(path); # prints the absolute path to <TerraSync dir>/Airports
|example3 = var path = finddata("preferences.xml");
print(path); # prints the absolute path to $FG_ROOT/preferences.xml
}}

===flightplan()===
{{Nasal doc
|syntax = flightplan([path]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1738|t=Source}}
|text = {{see also|Nasal Flightplan}}
Returns a flight plan object, either one for the current flight plan, or one loaded from a given path.
|param1 = path
|param1text = Optional path to flight plan XML file.
|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.
|example1 = var fp = flightplan();
print(fp.getWP(fp.current).id);
|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>.
|example2 = var path = getprop('/sim/fg-home') ~ '/fp-demo.xml';
var fp = flightplan(path);
for(var i = 0; i < fp.getPlanSize(); i += 1){
print(fp.getWP(i).id);
<nowiki>}</nowiki>
}}

===geodinfo()===
{{Nasal doc
|syntax = geodinfo(lat, lon[, max_alt]);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=981|t=Source}}
|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}}):
* '''light_coverage:''' The coverage of a single point of light in m<sup>2</sup>.
* '''bumpiness:''' Normalized bumpiness factor for the material.
* '''load_resistance:''' The amount of pressure in N/m<sup>2</sup> the material can withstand without deformation.
* '''solid:''' 1 (true) or false (0) depending on whether the material is solid or not.
* '''names:''' Vector of scenery types (usually generated by [[TerraGear]]) that will use this material.
* '''friction_factor:''' Normalized friction factor of the material.
* '''rolling_friction:''' The rolling friction coefficient of the material.

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.
|param1 = lat
|param1text = Latitude, inputted as a number.
|param2 = lon
|param2text = Longitude, inputted as a number.
|param3 = max_alt
|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.
|example1text = Dumps information about ground underneath the aircraft.
|example1 = var pos = geo.aircraft_position();
var info = geodinfo(pos.lat(), pos.lon());
debug.dump(info);
|example2text = Prints whether the ground underneath the aircraft is solid or is water.
|example2 = var pos = geo.aircraft_position();
var info = geodinfo(pos.lat(), pos.lon());
if (info != nil and info[1] != nil) {
print("The ground underneath the aircraft is ", info[1].solid == 1 ? "solid." : "water.");
<nowiki>}</nowiki>
}}

=== geodtocart() ===
{{Nasal doc
|syntax = geodtocart(lat, lon, alt);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=962|t=Source}}
|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.
|param1 = lat
|param1text = Latitude, in degrees.
|param2 = lon
|param2text = Longitude, in degrees.
|param3 = alt
|param3text = Altitude, in metres.
|example1 = var (x, y, z) = geodtocart(0, 0, 0); # point is the intersection of the prime meridian and equator.
print("x: ", x); # prints "x: 6378137"
print("y: ", y); # prints "y: 0"
print("z: ", z); # prints "y: 0"
}}

=== get_cart_ground_intersection()===
Introduced in 2017.2.1, see [[Terrain Detection]].

===getprop()===
{{Nasal doc
|syntax = <nowiki>getprop(path[, path[, ...]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=345|t=Source}}
|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).
|param1 = path
|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.
|example1 = print("You have FlightGear v", getprop("/sim/version/flightgear")); # prints FlightGear version
|example2text = Note that the example below will only work in FlightGear 3.2 and above.
|example2 = for(var i = 0; i < 8; i += 1){
print("View #", i + 1, " is named ", getprop("/sim/view", i, "name"));
}
|example3text = Same as above, but is supported by all versions of FlightGear.
|example3 = for(var i = 0; i < 8; i += 1){
print("View #", i + 1, " is named ", getprop("/sim/view[" ~ i ~ "]/name"));
<nowiki>}</nowiki>
}}
==== See also====
{{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:
To get a Node rather than its value, use <code>props.globals.getNode()</code> - see [[Nasal_library/props]]. }}

===greatCircleMove()===
{{Nasal doc
|syntax = greatCircleMove([pos, ]course, dist);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1681|t=Source}}
|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).
|param1 = pos
|param1text = Optional position to calculate from. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost object.
:* A hash with ''lat'' and ''lon'' members
:* A <code>geo.Coord</code> object
:* A lat/lon pair, that is, a pair of numbers (latitude followed by longitude) separated by a comma: <code>greatCircleMove(lat,lon, ...)</code>.
|param2 = course
|param2text = Course to new set of coordinates, in degrees (in the range 0–360).
|param3 = dist
|param3text = Distance in nautical miles to the new set of coordinates.
|example1 = var pos = greatCircleMove(0,0, 0, 1);
debug.dump(pos); # print hash with coordinates
|example2 = var fix = findFixesByID("POGIC");
fix = fix[0];
var pos = greatCircleMove(fix, 45, 10);
debug.dump(pos); # print hash with coordinates
}}

===interpolate()===
{{Nasal doc
|private = _interpolate()
|syntax = <nowiki>interpolate(prop, value1, time1[, value2, time2[, ...]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=522|t=Part 1}} {{!}} {{fgdata file|Nasal/globals.nas|t=Part 2}}
|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.
|param1 = prop
|param1text = String or <code>props.Node</code> object that indicates a node in the property tree to be used.
|param2 = value''n''
|param2text = Target value to change the property to in the set amount of time. This should be a number.
|param3 = time''n''
|param3text = Time in seconds, that will be taken for the interpolation.
|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.
|example1 = setprop("/test", 0); # (re-)set property
interpolate("/test",
50, 5, # interpolate to 50 in 5 seconds
10, 2, # interpolate to 10 in 2 seconds
0, 5); # interpolate to 0 in 5 seconds
|example2 = # Apply the left brake at 20% per second
var prop = "controls/gear/brake-left";
var dist = 1 - getprop(prop);
if (dist == 1) {
interpolate(prop, 1, dist / 0.2);
<nowiki>}</nowiki>
}}

===isa()===
{{Nasal doc
|syntax = isa(object, class);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|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.
|param1 = object
|param1text = Object to check.
|param2 = class
|param2text = Class/object to check that '''object''' inherits from or is an instance of.
|example1 = var coord = geo.Coord.new();
if(isa(coord, geo.Coord)){
print("Variable 'coord' is an instance of class 'geo.Coord'"); # this one will be printed
} else {
print("Variable 'coord' is not an instance of class 'geo.Coord'");
}
|example2 = var coord = geo.Coord.new();
if(isa(coord, props.Node)){
print("Variable 'coord' is an instance of class 'props.Node'");
} else {
print("Variable 'coord' is not an instance of class 'props.Node'"); # this one will be printed
}
|example3text = The example below demonstrates checking of inheritance.
|example3 = var Const = {
constant: 2,
getConst: func {
return me.constant;
}
};

var Add = {
new: func {
return { parents: [Add, Const] };
},

addToConst: func(a){
return a * me.getConst();
}
};

var m = Add.new();
print(m.addToConst(4));

if(isa(m, Add)) print("Variable 'm' is an instance of class 'Add'"); # will be printed
if(isa(m, Const)) print("Variable 'm' is an instance of class 'Const'"); # will also be printed
}}

===logprint()===
{{Nasal doc
|syntax = <nowiki>logprint(priority[, msg[, msg[, ...]]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=431|t=Source}}
|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}}.
|param1 = priority
|param1text = Number specifying the priority level of the outputted message:
:{{{!}} class="wikitable"
! Number !! Debug type
{{!-}}
{{!}} 1 {{!!}} Bulk
{{!-}}
{{!}} 2 {{!!}} Debug
{{!-}}
{{!}} 3 {{!!}} Info
{{!-}}
{{!}} 4 {{!!}} Warn
{{!-}}
{{!}} 5 {{!!}} Alert
{{!}}}
|param2 = msg
|param2text = The message. There is no limit to the arguments you give give. They will be concatenated together before logging.
|example1 = # logs the value of pi to three decimal places with log level 3
logprint(3, "pi = ", sprintf("%.3f", math.pi));
|example2 = logprint(5, "Alert! This is an important message!");
}}
{{note|
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:

LOG_BULK, LOG_WARN, LOG_DEBUG, LOG_INFO, LOG_ALERT, DEV_WARN, DEV_ALERT }}

===magvar() ===
{{Nasal doc
|syntax = magvar([pos]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1642|t=Source}}
|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.
{{{!}} class="wikitable"
! FlightGear versions !! Model !! Reference date
{{!-}}
{{!}} 3.6 and above {{!!}} {{wikipedia|World Magnetic Model}} (WMM) 2015 {{!!}} 1 January 2015
{{!-}}
{{!}} 0.9.11-pre1 to 3.4 {{!!}} WMM 2005 {{!!}} 1 January 2005
{{!-}}
{{!}} 0.7.3 to 0.9.10 {{!!}} WMM 2000 {{!!}} 1 January 2000
{{!}}}
|param1 = pos
|param1text = Optional position to calculate from. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost object.
:* A hash with ''lat'' and ''lon'' members
:* A <code>geo.Coord</code> object
:* A lat/lon pair, that is, a pair of numbers (latitude followed by longitude) separated by a comma: <code>magvar(lat,lon)</code>.
|example1 = print(magvar(0, 0)); # prints the magnetic variation at 0, 0
}}

===maketimer() ===
{{Nasal doc
|syntax = maketimer(interval[, self], function);
|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}}
|version = 2.12
|commit = {{flightgear commit|ab939f|t=commit}}
|text = Returns a timer object containing the following methods and members:
* '''start()''': Starts the timer.
* '''stop()''': Stops the timer.
* '''restart(interval)''': Restarts the timer with the given interval.
* '''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).
* '''isRunning''': Read-only bool telling whether the timer is currently running.
* '''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.
Unlike {{func link|settimer()}}, which it replaces, <code>maketimer()</code> provides more control over the timer. In addition, it can help reduce memory usage.
|param1 = interval
|param1text = Interval in seconds for the timer.
|param2 = self
|param2text = Optional parameter specifying what any <code>'''me'''</code> references in the function being called will refer to.
|param3 = function
|param3text = Function to be called at the given interval.
|example1 = var timer = maketimer(1, func(){
print("Hello, World!"); # print "Hello, World!" once every second (call timer.stop() to stop it)
});
timer.start();
|example2 = var timer = maketimer(1, math, func(){
print(me.math); # 'me' reference is the 'math' namespace
});
timer.singleShot = 1; # timer will only be run once
timer.start();
|example3 = var timer = maketimer(1, func(){
print("Hello, World!"); # print "Hello, World!" once every second (call timer.stop() to stop it)
});
timer.start();
print(timer.isRunning); # prints 1
|example4text = In the example below, "Hello, World!" will be printed after one second the first time, and after two seconds thereafter.
|example4 = var update = func(){
print("Hello, World!");
timer.restart(2); # restarts the timer with a two second interval
}

var timer = maketimer(1, update);
timer.singleShot = 1;
timer.start();
}}

===maketimestamp()===
{{Nasal doc
|syntax = maketimestamp()
|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}}
|version = 2019.2
|commit = {{flightgear commit|7db06300|t=commit}}
|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:
* '''stamp()''': Resets the timing operation. Call this first.
* '''elapsedMSec()''': returns number of milliseconds elapsed since stamp() called. Resolution may vary depending on platform but is usually at least millisecond accuracy.
* '''elapsedUSec()''': returns number of microseconds elapsed since stamp() called. Resolution may vary depending on platform but is usually at least millisecond accuracy.
|
|example1text = In the example below the number of milliseconds elapsed will be printed.
|example1 = var timestamp = maketimestamp();
timestamp.stamp();
print(timestamp.elapsedMSec(), "ms elapsed");
print(timestamp.elapsedMSec(), "ms elapsed");
}}

===md5()===
{{Nasal doc
|syntax = md5(string);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=758|t=Source}}
|version = 3.2
|commit = {{flightgear commit|cfbf9e|t=commit}}
|text = Returns a the {{wikipedia|MD5}} hash (as a string) of the inputted string.
|param1 = string
|param1text = String the generate the hash of. Mandatory.
|example1text = The below code should output <code>65a8e27d8879283831b664bd8b7f0ad4</code>.
|example1 = print(md5("Hello, World!"));
}}

===navinfo()===
{{Nasal doc
|syntax = navinfo(lat, lon, type, id);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1453|t=Source}}
|text = Returns vector <code>navaid</code> ghost objects matching the given '''type''' and '''id''' or <code>'''nil'''</code> on error.
|param1 = lat ''and'' lon
|param1text = If given, the returned navaids will be put into order of ascending distance from the location.
|param2 = type
|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."
|param3 = id
|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.
|example1 = navinfo("vor"); # returns all VORs
|example2 = navinfo("HAM"); # return all navaids whose names start with "HAM"
|example3 = navinfo("vor", "HAM"); # return all VORs whose names start with "HAM"
|example4 = navinfo(34,48,"vor","HAM"); # return all VORs whose names start with "HAM" and sorted by distance relative to 34°, 48°
}}

===parse_markdown()===
{{Nasal doc
|syntax = parse_markdown(markdown);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=745|t=Part 1}} {{!}} {{simgear file|simgear/misc/SimpleMarkdown.cxx|t=Part 2}}
|version = 3.2
|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:
* It strips whitespace from the beginning of the string.
* It supports [http://daringfireball.net/projects/markdown/syntax#p paragraphs and line breaks].
* It collapses whitespace.
* It converts unordered [http://daringfireball.net/projects/markdown/syntax#list lists] to use a bullet character (•). 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.
|param1 = markdown
|param1text = String containing Markdown to be parsed.
|example1text =
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>).
<syntaxhighlight lang="xml" highlight="41-50">
<?xml version="1.0" encoding="UTF-8"?>

<PropertyList>

<name>test</name>
<layout>vbox</layout>

<group>
<layout>hbox</layout>

<empty>
<stretch>true</stretch>
</empty>

<text>
<label>parse_markdown() test dialog</label>
</text>

<empty>
<stretch>true</stretch>
</empty>

<button>
<legend></legend>
<pref-width>16</pref-width>
<pref-height>16</pref-height>
<binding>
<command>dialog-close</command>
</binding>
</button>

</group>

<canvas>
<name>Canvas plot</name>
<stretch>true</stretch>
<pref-width>400</pref-width>
<pref-height>300</pref-height>
<nasal>
<load><![CDATA[
var text = 'Items:
* apples
* oranges
* pears

Some text.
Some more items:
* apples
* oranges
* pears';

var parsed = parse_markdown(text);

var root_canvas = canvas.get(cmdarg());
root_canvas.setColorBackground(255, 255, 255);
var root = root_canvas.createGroup();

var text_dis = root.createChild("text")
.setText(parsed)
.setTranslation(5, 5)
.setFont("LiberationFonts\LiberationSans-Regular.ttf")
.setFontSize(15)
.setColor(0, 0, 0)
.setDrawMode(canvas.Text.TEXT)
.setAlignment("left-top");
]]></load>
</nasal>
</canvas>

</PropertyList>
</syntaxhighlight>
|example1 = fgcommand("dialog-show", {"dialog-name": "test"});
|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.
|example2 = <nowiki>var markdown = 'Items:
* apples
* oranges
* pears

Some text.
Some more items:
* apples
* oranges
* pears';

var parsed = parse_markdown(markdown);

debug.dump(parsed);

var path = string.normpath(getprop("/sim/fg-home") ~ '/Export/parse_markdown()-test.html');

var file = io.open(path, "w");

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>";

io.write(file, html);
io.close(file);
print("Done, file ready for viewing (" ~ path ~ ")");</nowiki>
}}

===parsexml()===
{{Nasal doc
|syntax = <nowiki>parsexml(path[, start[, end[, data[, pro_ins]]]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=710|t=Source}}
|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.
|param1 = path
|param1text = Mandatory absolute path to the XML file to be parsed.
|param2 = start
|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.
|param3 = end
|param3text = Optional callback function that will be called for every ending tag. The function should take one argument: the tag name.
|param4 = data
|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.
|param5 = pro_ins
|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.
|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.
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>

<?xml-stylesheet type="text/xsl" href="style.xsl"?>

<foo>
<blah type="string"><![CDATA[ <sender>John Smith</sender> ]]></blah>
<blah2 type="string">Orange & lemons</blah2>
</foo>
</syntaxhighlight>
|example1 = var start = func(name, attr){
print("Starting tag: '", name, "'");
foreach(var a; keys(attr)){
print("\twith attribute ", a, '="', attr[a], '"');
}
}

var end = func(name){
print("Ending tag: '", name, "'");
}

var data = func(data){
print("Data = '", data, "'");
}

var pro_instr = func(target, data){
print("Processing instruction: target = '", target, "', data = '", data, "'");
}

parsexml(getprop("/sim/fg-home") ~ '/Export/demo.xml', start, end, data, pro_instr);
}}

===print()===
{{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.

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>}}

{{Nasal doc
|syntax = <nowiki>print(data[, data[, ...]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=415|t=Source}}
|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.
|param1 = data
|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.
|example1 = print("Just", " a ", "test"); # prints "Just a test"
|example2 = print("pi = ", math.pi); # prints "pi = 3.141592..."
}}

=== printf() ===
{{Nasal doc
|syntax = <nowiki>printf(format[, arg[, arg, [...]]]);</nowiki>
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|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>).
|example1 = printf("In hexadecimal, 100000 = %X", 186A0); # prints "In hexadecimal, 100000 = 186A0"
}}

===printlog()===
{{caution|This function is deprecated and doesn't work. Please use the new one {{func link|logprint()}}.}}
{{Nasal doc
|syntax = <nowiki>printlog(level, data[, data[, ...]]);</nowiki>
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|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.
|param1 = level
|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.
|param2 = data
|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.
|example1 = printlog("alert", "This is an alert"); # message will be printed
|example2 = printlog("info", "Just informing you about something"); # message will be printed only if log level is set to "info" or less
}}

===rand()===
{{Nasal doc
|syntax = rand();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=554|t=Source}}
|text = Returns a random floating point number between 0 (inclusive) and 1 (exclusive). It takes no arguments.
|example1 = print(rand()); # prints random number
}}

===registerFlightPlanDelegate()===
{{Nasal doc
|syntax = registerFlightPlanDelegate(init_func);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1879|t=Source}}
|text = Registers a flight plan delegate. See <tt>''{{fgdata file|Nasal/route_manager.nas|t=$FG_ROOT/Nasal/route_manager.nas}}''</tt> for examples.
|param1 = init_func
|param1text = Initialization function which will be called during FlightGear's startup.
}}
===removecommand()===
{{Nasal doc
|syntax = removecommand(cmd);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=668|t=Source}}
|text = Removes the given fgcommand. Returns <code>'''nil'''</code>.
{{caution|This will remove '''any''' [[fgcommands|fgcommand]], even those implemented in C++, so use with caution!}}
|param1 = cmd
|param1text = String specifying the name of the command to remove.
|example1 = addcommand("hello", func(){
print("Hello");
});
fgcommand("hello"); # "Hello" will be printed
removecommand("hello"); # removes it
}}

===removelistener()===
{{Nasal doc
|syntax = removelistener(id);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=1384|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=506|t=Part 2}}
|text = Removes and deactivates the given listener and returns the number of listeners left or <code>'''nil'''</code> on error.
{{note|It is good practice to remove listeners when they are not required anymore. This prevents the listeners reducing FlightGear's run performance.}}
|param1 = id
|param1text = ID of listener as returned by {{func link|setlistener()}}.
|example1 = var ls = setlistener("/sim/test", func(){
print("Property '/sim/test' has been changed");
});
setprop("/sim/test", "blah"); # trigger listener
var rem = removelistener(ls); # remove listener
print("There are ", rem, " listeners remaining");
}}

===resolvepath()===
{{Nasal doc
|syntax = resolvepath(path);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=604|t=Source}}
|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.
|param1 = path
|param1text = Relative path to be completed.
|example1 = print(resolvepath("Nasal/globals.nas")); # prints the equivalent of $FG_ROOT/Nasal/globals.nas
|example2 = print(resolvepath("blah")); # prints nothing; could not be resolved
|example3 = var file_path = resolvepath("Aircraft/SenecaII/some-file");
if (file_path != ""){
gui.popupTip("some-file found", 2);
} else {
gui.popupTip("some-file not found", 2);
<nowiki>}</nowiki>
}}

===setlistener()===
{{Nasal doc
|syntax = <nowiki>setlistener(node, code[, init[, type]]);</nowiki>
|private = _setlistener()
|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.''
|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()}}.
{{note|Listeners are known to be a source of resource leaks. To avoid this, please take measures such as:
* Using {{func link|removelistener()}} when they are not needed any more.
* Using a single initialization listener.
* Avoiding tying listeners to properties that are rapidly updated (e.g., many times per frame).
}}
|param1 = node
|param1text = Mandatory string or <code>props.Node</code> object pointing to a property in the [[Property Tree]].
|param2 = code
|param2text = Mandatory callback function to execute when the listener is triggered. The function can take up to four arguments in the following order:
* '''changed''': a <code>props.Node</code> object pointing to the changed node.
* '''listen''': a <code>props.Node</code> object pointing to the listened-to node. Note that this argument maybe different depending on the '''type'''.
* '''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.
* '''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.
|param3 = init
|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).
|param4 = type
|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.
|example1 = var prop = props.globals.initNode("/sim/test", "", "STRING"); # create property
var id = setlistener("/sim/test", func(n){ # create listener
print("Value: ", n.getValue());
});
setprop("/sim/test", "blah"); # trigger listener
removelistener(id); # remove listener
prop.remove(); # remove property
}}

===setprop()===
{{Nasal doc
|syntax = <nowiki>setprop(path[, path[, ...]], value);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=385|t=Source}}
|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.
{{note|If you want to remove a property, you will have to use one of the <code>props</code> helpers:
<syntaxhighlight lang="nasal">
props.globals.getNode("foo/bar").remove(); # take out the complete node
props.globals.getNode("foo").removeChild("bar"); # take out a certain child node
</syntaxhighlight>
}}
|param1 = path
|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.
|param2 = value
|param2text = Value to write to the given property. Must be either a string or a number.
|example1 = setprop("/sim/demo", "This is a demo");
|example2text = Note that the example below will only work in FlightGear 3.2 and above.
|example2 = for(var i = 0; i < 3; i += 1){
setprop("/sim/demo", i, "Demo #" ~ i));
}
|example3text = Same as above, but is supported by all versions of FlightGear.
|example3 = for(var i = 0; i < 3; i += 1){
setprop("/sim/demo[" ~ i ~ "]", "Demo #" ~ i));
<nowiki>}</nowiki>
}}
====See also====
{{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:
To get a Node rather than its value, use <code>props.globals.getNode()</code> - see [[Nasal_library/props]]. }}

===settimer() ===
{{Nasal doc
|syntax = settimer(function, delta[, realtime]);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=499|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=1286|t=Part 2}}
|text = Runs the given function a specified amount of seconds after the current time. Returns <code>'''nil'''</code>.
{{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.}}
|param1 = function
|param1text = Mandatory function that will be called. It may be necessary to enclose code in an anonymous function (see example).
|param2 = delta
|param2text = Mandatory amount of time in seconds after which the function will be called.
|param3 = realtime
|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.
|example1 = var myFunc = func(){
print("Hello");
}

settimer(myFunc, 2); # runs myFunc after 2 seconds
|example2 = var sqr = func(a){
return a * a;
}

settimer(func(){
print(sqr(2)); # will print 4 after 2 seconds
}, 2);
}}

===srand() ===
{{Nasal doc
|syntax = srand();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=559|t=Source}}
|text = Makes the pseudorandom number generator (see {{func link|rand()}}) generate a new {{wikipedia|random seed|noicon=1}} based on time. Returns 0.
}}
===systime()===
{{Nasal doc
|syntax = systime();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=770|t=Source}}
|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).
{{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]}}
|example1 = print("Unix time: ", systime()); # prints Unix time
|example2 = var myFunc = func(){
for(var i = 0; i <= 10; i += 1){
print("Interation #", i);
}
}
var t = systime(); # record time
myFunc(); # run function
var t2 = systime(); # record new time
print("myFunc() took ", t2 - t, " seconds"); # print result
}}

===thisfunc()===
{{Nasal doc
|syntax = thisfunc();
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = Returns the function from which this function is called. This allows a function to reliably and safely call itself from within a closure.
|example1 = var stringify_vec = func(input){
if (typeof(input) == "scalar"){
return sprintf("%s", input);
} elsif (typeof(input) == "vector") {
if (size(input) == 0) return "[]";
var this = thisfunc();
var buffer = "[";
for(var i = 0; i < size(input); i += 1){
buffer ~= this(input[i]);
if (i == size(input) - 1) {
buffer ~= "]";
} else {
buffer ~= ", ";
}
}
return buffer;
} else {
die("stringify_vec(): Error! Invalid input. Must be a vector or scalar");
}
}

var test_vec = ["a", "b", "c", [1, 2, 3], "d"];
debug.dump(stringify_vec(test_vec)); # prints "[a, b, c, [1, 2, 3], d]"
test_vec = [];
debug.dump(stringify_vec(test_vec)); # prints "[]"
test_vec = {};
debug.dump(stringify_vec(test_vec)); # will throw an error
}}

===tileIndex() ===
{{Nasal doc
|syntax = tileIndex();
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1720|t=Source}}
|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>.
|example1 = print(tileIndex()); # print index
}}

=== tilePath()===
{{Nasal doc
|syntax = tilePath();
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1712|t=Source}}
|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>.
|example1 = print(tilePath()); # print path
}}

=== values()===
{{Nasal doc
|syntax = values(hash);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = Returns a vector containing the values of the given hash.
|param1 = hash
|param1text = Mandatory hash to get the values of.
|example1 = var hash = {
"a": 1,
"b": 2,
"c": 3
};

foreach(var val; values(hash)){
print(val);
}
|example2text = The below example does exactly the same thing as the above example, but does not use <code>values()</code>:
|example2 = var hash = {
"a": 1,
"b": 2,
"c": 3
};

foreach(var key; keys(hash)){
print(hash[key]);
<nowiki>}</nowiki>
}}

==Extension functions new in FG 2020.1 ==
The following functions have been added to the nasal core library and will be released with FlightGear version 2020.1.
Before the release they are available in the development branch "next".

===isfunc()===
Returns 1 if type or argument is a function, otherwise 0.

===isghost()===
Returns 1 if type or argument is a ghost, otherwise 0.

=== ishash()===
Returns 1 if type or argument is a hash, otherwise 0.

===isint()===
{{Nasal doc
|syntax = isint(x);
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}
|text = Returns 1 if argument has a numeric value and x == floor(x), e.g. integer.
}}

===isnum()===
{{Nasal doc
|syntax = isnum(x);
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}
|text = Returns 1 if typeof(x) is "scalar" and x has a numeric value otherwise 0.
}}

===isscalar()===
{{Nasal doc
|syntax = isscalar(x);
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}
|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 "~".
|example1 = var a = "foo";
var b=42;
if (isscalar(a) and isscalar(b)) print(a~b);
if (isstr(a)) print("a is a string");
if (isint(b)) print("b is an integer");
# if (isscalar(a))... is equivalent to if (typeof(a) == "scalar")...
}}

===isstr()===
Returns 1 if type or argument is a string, otherwise 0.

===isvec()===
Returns 1 if type or argument is a vector, otherwise 0.

===vecindex()===
{{Nasal doc
|syntax = vecindex(vector, value);
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}
|text = Returns the index of value or nil, if value is not found in vector.
|example1=
var myvector = ["apple", "bananna", "coconut"];
# to check if a vector contains a certain value compare vecindex to nil
if (vecindex(myvector, "apple") != nil) {
print("found apple");
}
# WARNING: this will not work as desired because index is 0
if (vecindex(myvector, "apple")) {
print("found apple");
<nowiki>}</nowiki>

}}

==Variables==
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}}.

===D2R===
{{Nasal doc
|syntax = var radians = degrees * D2R;
|text = Converts an angle from degrees to radians when multiplied by the angle in degrees. Equal to <code>π / 180</code>.
}}
===FPS2KT===
{{Nasal doc
|syntax = var knots = feet_per_second * FPS2KT;
|text = Converts a velocity from feet per second to knots when multiplied by the velocity in feet per second. Approximately equal to 0.5925.
}}
===FT2M===
{{Nasal doc
|syntax = var metres = feet * FT2M;
|text = Converts a length from feet to metres when multiplied by the length in feet. Equal to 0.3048.
}}
===GAL2L ===
{{Nasal doc
|syntax = var litres = gallons * GAL2L;
|text = Converts a volume from US liquid gallons to litres when multiplied by the volume in gallons. Approximately equal to 3.7854.
}}
===IN2M===
{{Nasal doc
|syntax = var metres = inches * IN2M;
|text = Converts a length from inches to metres when multiplied by the length in inches. Equal to 0.0254.
}}
===KG2LB===
{{Nasal doc
|syntax = var pounds = kilograms * KG2LB;
|text = Converts a mass from kilograms to pounds when multiplied by the mass in kilograms. Approximately equal to 2.2046.
}}
===KT2FPS===
{{Nasal doc
|syntax = var feet_per_second = knots * KT2FPS;
|text = Converts a velocity from knots to feet per second when multiplied by the velocity in knots. Approximately equal to 1.6878.
}}
===KT2MPS===
{{Nasal doc
|syntax = var metres_per_second = knots * KT2MPS;
|text = Converts a velocity from knots to metres per second when multiplied by the velocity in knots. Approximately equal to 0.5144.
}}
===L2GAL===
{{Nasal doc
|syntax = var gallons = litres * L2GAL;
|text = Converts a volume from litres to US liquid gallons when multiplied by the volume in litres. Approximately equal to 0.2642.
}}
===LB2KG===
{{Nasal doc
|syntax = var kilograms = pounds * LB2KG;
|text = Converts a mass from pounds to kilograms when multiplied by the mass in pounds. Approximately equal to 0.4536.
}}
===M2FT ===
{{Nasal doc
|syntax = var feet = metres * M2FT;
|text = Converts a length from metres to feet when multiplied by the length in metres. Approximately equal to 3.2808.
}}
===M2IN===
{{Nasal doc
|syntax = var inches = metres * M2IN;
|text = Converts a length from metres to inches when multiplied by the length in metres. Approximately equal to 39.3701.
}}
===M2NM ===
{{Nasal doc
|syntax = var nautical_miles = metres * M2NM;
|text = Converts a length from metres to nautical miles when multiplied by the length in metres. Approximately equal to 0.00054.
}}
===MPS2KT ===
{{Nasal doc
|syntax = var knots = metres_per_second * MPS2KT;
|text = Converts a velocity from metres per second to knots when multiplied by the velocity in metres per second. Approximately equal to 1.9438.
}}
===NM2M ===
{{Nasal doc
|syntax = var metres = nautical_miles * NM2M;
|text = Converts a length from nautical miles to metres when multiplied by the length in nautical miles. Equal to 1,852.
}}
===R2D===
{{Nasal doc
|syntax = var degrees = radians * R2D;
|text = Converts an angle from radians to degrees when multiplied by the angle in radians. Equal to <code>180 / π</code>.
}}

{{Appendix}}

{{Nasal namespaces}}

Nasal library

2025-12-04T12:39:51Z

PlayeRom: /* str() */

{{Nasal Navigation|nocat=1}}
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:
* {{flightgear file|src/Scripting}}
* {{simgear file|simgear/nasal}}

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]].

{{tip|Copy & paste the examples into your [[Nasal Console]] and execute them to see what they do.|width=70%}}

== Core library functions ==
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:
* http://plausible.org/nasal/lib.html ([http://web.archive.org/web/20101010094553/http://plausible.org/nasal/lib.html archive])
* {{simgear file|simgear/nasal/lib.c}} ([http://sourceforge.net/p/flightgear/simgear/ci/next/log/?path=/simgear/nasal/lib.c history])

=== append() ===
{{Nasal doc
|syntax = append(vector, element[, element[, ...]]);
|source = {{simgear file|simgear/nasal/lib.c|l=45|t=Source}}
|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.
|param1 = vector
|param1text = The vector to which the arguments will be appended.
|param2 = element
|param2text = An element to be added to the vector.
|example1 =
var vector = [1, 2, 3]; # Initialize the vector
append(vector, 4); # Append the number 4 to the end of the vector
debug.dump(vector); # Print the contents of the vector
|example2 =
var vector = [1, 2, 3]; # Initialize the vector
append(vector, 4, 5, 6); # Append the numbers 4, 5, and 6 to the end of the vector
debug.dump(vector); # Print the contents of the vector
}}

=== bind() ===
{{Nasal doc
|syntax = bind(function, locals[, outer_scope]);
|source = {{simgear file|simgear/nasal/lib.c|l=638|t=Source}}
|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.
|param1 = function
|param1text = Function to evaluate.
|param2 = locals
|param2text = Hash containing values that will become the namespace (first closure) for the function.
|param3 = outer_scope
|param3text = Optional function which is bound to the next closure. This can be bound to yet another, making a linked list.
|example1 = # This is a namespace/hash with a single member, named "key," which is initialized to 12
var Namespace = {
key: 12
};

# This is different namespace/hash containing a function
# dividing a variable "key" (which is unavailable/nil in this namespace) by 2
var AnotherNamespace = {
ret: func {
key /= 2;
}
};

# To see that key is not available, try to call AnotherNamespace.ret() first
call(AnotherNamespace.ret, [], nil, nil, var errors = []);
if(size(errors)){
print("Key could not be divided/resolved!");
debug.printerror(errors);
}

# Associate the AnotherNamespace.ret() function with the first namespace
# so that "key" is now available
var function = bind(AnotherNamespace.ret, Namespace);

# Invoke the new function
function();

# Print out the value of Namespace.key
# It was changed to 12 from 6 by AnotherNamespace.ret()
print(Namespace.key);
}}

=== call() ===
{{Nasal doc
|syntax = call(func[, args[, me[, locals[, error]]]);
|source = {{simgear file|simgear/nasal/lib.c|l=376|t=Source}}
|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.
|param1 = func
|param1text = Function to execute.
|param2 = args
|param2text = Vector containing arguments to give to the called function.
|param3 = me
|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).
|param4 = locals
|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.
|param5 = error
|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}}.
|example1 =
# prints "Called from call()"
call(func {
print("Called from call()");
});
|example2 =
# prints "a = 1 : b = 2
call(func(a, b){
print("a = ", a, " : b = ", b);
},
[1, 2]
);
|example3 =
var Hash = {
new: func {
var m = { parents: [Hash] };

m.el1 = "string1";
m.el2 = "string2";

return m;
}
};

# prints "me.el1 = string1", then "me.el2 = string2" on the next line
call(func(a, b){
print("me.el", a, " = ", me["el" ~ a]);
print("me.el", b, " = ", me["el" ~ b]);
},
[1, 2],
Hash.new()
);
|example4 =
# prints the value of math.pi
call(func {
print(pi);
}, nil, nil,
math
);
|example5 =
call(func {
print(math.ip); # math.ip doesn't exist
}, nil, nil, nil,
var errs = []
);
debug.printerror(errs); # The error is caught and printed using debug.printerror()
}}

=== caller() ===
{{Nasal doc
|syntax = caller([level]);
|source = {{simgear file|simgear/nasal/lib.c|l=540|t=Source}}
|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 '''[0]''' a hash of local variables, '''[1]''' the function object, '''[2]''' the full source file name (incl. path) and '''[3]''' the line number.
|param1 = level
|param1text = Optional integer specifying the stack level to return a result from. Defaults to 1 (i.e. the caller of the currently executing function).
|example1 =
var myFunction = func(a, b) {
debug.dump(caller(0)[0]); # prints a hash of local variables, including arguments a and b
return 2 * 2;
};

print("2 x 2 = ", myFunction(2, 2));
|example2 =
var get_arg_value = func() {
print("Argument to myFunc = ", caller(1)[0]['a']); # print the value of myFunc's single argument, using caller()
};

var myFunc = func(a) {
get_arg_value();
};

myFunc(3);
|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: true, zindex: nil }</code>.
|example3 =
var MapStructure_selfTest = func() {
var temp = {};
temp.dlg = canvas.Window.new([600, 400], "dialog");
temp.canvas = temp.dlg.createCanvas().setColorBackground(1, 1, 1, 0.5);
temp.root = temp.canvas.createGroup();

var testMap = temp.root.createChild("map");
testMap.setController("Aircraft position");
testMap.setRange(25); # TODO: implement zooming/panning via mouse/wheel here, for lack of buttons :-/
testMap.setTranslation(
temp.canvas.get("view[0]") / 2,
temp.canvas.get("view[1]") / 2,
);

var r = func(name, vis = true, zindex = nil) {
return caller(0)[0];
}

# TODO: we'll need some z-indexing here, right now it's just random
# TODO: use foreach/keys to show all layers in this case by traversing SymbolLayer.registry directly ?
# maybe encode implicit z-indexing for each lcontroller ctor call ? - i.e. preferred above/below order ?
var types = [
r('TFC', false),
r('APT'),
r('DME'),
r('VOR'),
r('NDB'),
r('FIX', false),
r('RTE'),
r('WPT'),
r('FLT'),
r('WXR'),
r('APS'),
];

foreach (var type; types) {
testMap.addLayer(
factory: canvas.SymbolLayer,
type_arg: type.name,
visible: type.vis,
priority: type.zindex,
);
}
}; # MapStructure_selfTest
}}

=== chr() ===
{{Nasal doc
|syntax = chr(code);
|source = {{simgear file|simgear/nasal/lib.c|l=240|t=Source}}
|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.}}
{{{!}} class="wikitable"
! Code !! Name !! Equivalent to
{{!-}}
{{!}} 10 {{!!}} {{Wikipedia|Newline}} {{!!}} <code>\n</code>
{{!-}}
{{!}} 9 {{!!}} {{Wikipedia|Tab key#Tab characters|Horizontal tab}} {{!!}} <code>\t</code>
{{!-}}
{{!}} 13 {{!!}} {{Wikipedia|Carriage return}} {{!!}} <code>\r</code>
{{!}}}
|param1 = code
|param1text = Integer character code for the desired glyph.
|example1 = print("Code 65 = ", chr(65)); # prints "Code 65 = A"
|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.
|example2 =
for(var i = 0; i <= 255; i += 1){
print("Code ", i, " = >", chr(i), "<");
}
}}

=== closure() ===
{{Nasal doc
|syntax = closure(func[, level]);
|source = {{simgear file|simgear/nasal/lib.c|l=557|t=Source}}
|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'''.
|param1 = func
|param1text = Function to evaluate.
|param2 = level
|param2text = Optional integer specifying the scope level. Defaults to 0 (the namespace of '''func''').
|example1 =
var get_math_e = func {
return e; # return the value of math.e
}

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
debug.dump(closure(myFunction)); # print the namespace of get_math_e

print(myFunction());
}}

=== cmp() ===
{{Nasal doc
|syntax = cmp(a, b);
|source = {{simgear file|simgear/nasal/lib.c|l=169|t=Source}}
|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'''.
|param1 = a
|param1text = First string argument for comparison.
|param2 = b
|param2text = Second string argument for comparison.
|example1 = print(cmp("1", "two")); # prints -1
|example2 = print(cmp("string", "string")); # prints 0
|example3 = print(cmp("one", "2")); # prints 1
|example4 = print(cmp("string1", "string2")); # prints -1
}}

=== compile() ===
{{Nasal doc
|syntax = compile(code[, filename]);
|source = {{simgear file|simgear/nasal/lib.c|l=349|t=Source}}
|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'''.
|param1 = code
|param1text = String containing Nasal code to be compiled.
|param2 = filename
|param2text = Optional string used for error messages/logging. Defaults to <code><compile></code>
|example1 =
var myCode = 'print("hello");';
var helloFunc = compile(myCode, "myCode");
helloFunc();
|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>.
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<PropertyList>

<nasal><![CDATA[
print("You have FlightGear v", getprop("/sim/version/flightgear"));
]]></nasal>

</PropertyList>
</syntaxhighlight>
Now, start FlightGear and execute this code in the [[Nasal Console]].
|example2 =
# Build the path
var FGRoot = getprop("/sim/fg-root");
var filename = "/gui/dialogs/test.xml";
var path = FGRoot ~ filename;

var blob = io.read_properties(path);
var script = blob.getValues().nasal; # Get the nasal string

# Compile the script. We're passing the filename here for better runtime diagnostics
var code = call(func {
compile(script, filename);
}, nil, nil, var compilation_errors = []);

if(size(compilation_errors)){
die("Error compiling code in: " ~ filename);
}

# Invoke the compiled script, equivalent to code();
# We're using call() here to detect errors:
call(code, [], nil, nil, var runtime_errors = []);

if(size(runtime_errors)){
die("Error calling code compiled loaded from: " ~ filename);
}
|example3text = The <code>compile()</code> function also allows you to parse a JSON string into a hash. Simplest example:
|example3 =
var jsonFunc = compile('{"version":"1.2.0","author":{"name":"John"} }');
var json = jsonFunc(); # return hash
logprint(LOG_ALERT, json["version"]); # print "1.2.0"
logprint(LOG_ALERT, json["author"]["name"]); # print "John"
}}

=== contains() ===
{{Nasal doc
|syntax = contains(hash, key);
|source = {{simgear file|simgear/nasal/lib.c|l=249|t=Source}}
|text = Returns 1 (True) if the hash contains the specified key, or 0 (False) if not.
|param1 = hash
|param1text = The hash to search in.
|param2 = key
|param2text = The scalar to be searched for, contained as a key in the hash.
|example1 =
# Initialize a hash
var hash = {
element: "value"
};
print(contains(hash, "element") ? "Yes" : "No"); # This will print "Yes"
print(contains(hash, "element2") ? "Yes" : "No"); # This will print "No"
}}

===contains()===
{{Requires commit|desc=Vector support|details=see {{Merge-request|project=fgdata|id=305}}|commit=ee39abbd3b70c9b6d5e3a1c4ccedddaac1a92b11|repo=Simgear}}
{{Nasal doc
|syntax = contains(vector, item);
|source = {{simgear file|simgear/nasal/lib.c|l=249|t=Source}}
|text = Returns 1 (True) if the vector contains the specified item, or 0 (False) if not.
|param1 = vector
|param1text = The vector to search in.
|param2 = item
|param2text = The object to be searched for in the vector.
|example1 =
# Initialize a vector
var vec = ["element", "foo"];
print(contains(vec, "element") ? "Yes" : "No"); # This will print "Yes"
print(contains(vec, "element2") ? "Yes" : "No"); # This will print "No"
}}

===delete() ===
{{Nasal doc
|syntax = delete(hash, key);
|source = {{simgear file|simgear/nasal/lib.c|l=118|t=Source}}
|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.
|param1 = hash
|param1text = The hash from which to delete the key.
|param2 = key
|param2text = The scalar to be deleted, contained as a key in the hash.
|example1 =
# Initialize the hash
var hash = {
element1: "value1",
element2: "value2"
};
delete(hash, "element1"); # Delete element1
debug.dump(hash); # prints the hash, which is now minus element1
}}

===die()===
{{Nasal doc
|syntax = die(error);
|source = {{simgear file|simgear/nasal/lib.c|l=417|t=Source}}
|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()}}.
|param1 = error
|param1text = String describing the error.
:{{inote|This parameter is technically optional, but it is highly recommended to use it.}}
|example1 =
print("Will print");
die("Don't go any further!");
print("Won't print"); # Will not be printed because die() stops the process
}}

=== find()===
{{Nasal doc
|syntax = find(needle, haystack);
|source = {{simgear file|simgear/nasal/lib.c|l=586|t=Source}}
|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.
|param1 = needle
|param1text = String to search for.
|param2 = haystack
|param2text = String to search in.
|example1 = print(find("c", "abcdef")); # prints 2
|example2 = print(find("x", "abcdef")); # prints -1
|example3 = print(find("cd", "abcdef")); # prints 2
}}

===ghosttype()===
{{Nasal doc
|syntax = ghosttype(ghost);
|source = {{simgear file|simgear/nasal/lib.c|l=336|t=Source}}
|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.
|param1 = ghost
|param1text = Ghost to return a description for.
|example1 = print(ghosttype(airportinfo())); # prints "airport"
}}

===id()===
{{Nasal doc
|syntax = id(object);
|source = {{simgear file|simgear/nasal/lib.c|l=706|t=Source}}
|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.
|param1 = object
|param1text = Can be either of a string, a vector, a hash, a code, a function, or a ghost.
|example1 = print(id("A")); # prints "str:000000001624A590"
}}

===int() ===
{{Nasal doc
|syntax = int(number);
|source = {{simgear file|simgear/nasal/lib.c|l=125|t=Source}}
|text = Returns the integer part of the numeric value of the single argument, or <code>'''nil'''</code> if none exists.
|param1 = number
|param1text = Number or string with just a number in it to return an integer from.
|example1 = print(int(23)); # prints "23"
|example2 = print(int(23.123)); # prints "23"
|example3 = debug.dump(int("string")); # prints "nil"
}}

===keys()===
{{Nasal doc
|syntax = keys(hash);
|source = {{simgear file|simgear/nasal/lib.c|l=36|t=Source}}
|text = Returns a vector containing the list of keys found in the single hash argument.
|param1 = hash
|param1text = The hash to return the keys from.
|example1 =
# Initialize a hash
var hash = {
element1: "value",
element2: "value"
};
debug.dump(keys(hash)); # print the vector
}}

===left()===
{{Nasal doc
|syntax = left(string, length);
|source = {{simgear file|simgear/nasal/lib.c|l=214|t=Source}}
|version = 2.12
|commit = {{simgear commit|bd7163|t=commit}}
|text = Returns a substring of '''string''', starting from the left.
|param1 = string
|param1text = String to return part of.
|param2 = length
|param2text = Integer specifying the length of the substring to return.
|example1 = print(left("string", 2)); # prints "st"
}}

=== num()===
{{Nasal doc
|syntax = num(number);
|source = {{simgear file|simgear/nasal/lib.c|l=149|t=Source}}
|text = Returns the numerical value of the single string argument, or <code>'''nil'''</code> if none exists.
|param1 = number
|param1text = String with just a number in it to return a number from.
|example1 = print(num("23")); # prints "23"
|example2 = print(num("23.123")); # prints "23.123"
|example3 = debug.dump(num("string")); # prints "nil"
}}

===pop()===
{{Nasal doc
|syntax = pop(vector);
|source = {{simgear file|simgear/nasal/lib.c|l=85|t=Source}}
|text = Removes and returns the last element of the single vector argument, or <code>'''nil'''</code> if the vector is empty.
|param1 = vector
|param1text = Vector to remove an element from.
|example1 =
var vector = [1, 2, 3];
pop(vector);
debug.dump(vector); # prints "[1, 2]"
|example2 =
var vector = [1, 2, 3];
debug.dump(pop(vector)); # prints "3"
|example3 =
var vector = [];
debug.dump(pop(vector)); # prints "nil"
}}

=== range() ===
{{Nasal doc
|syntax = range([start, ]stop[, step]);
|source = {{simgear file|simgear/nasal/lib.c|l=756|t=Source}}
|text = Creates a vector of numbers starting from <code>start</code> (default 0) up to but not including <code>stop</code>, incremented by <code>step</code> (default 1). Note: To specify <code>step</code>, you must also provide <code>start</code>; otherwise the second argument is interpreted as <code>stop</code>.
|param1 = start
|param1text = Optional. The starting number of the sequence. Defaults to 0 if omitted. Required if you want to specify <code>step</code>.
|param2 = stop
|param2text = Required. The number at which to stop the sequence (not included).
|param3 = step
|param3text = Optional. The increment between each number in the sequence. Defaults to 1. Only valid if <code>start</code> is also specified.
|example1 =
var vec = range(5); # Creates a vector [0, 1, 2, 3, 4]
var vec = range(2, 5); # Creates a vector [2, 3, 4]
var vec = range(0, 10, 2); # Creates a vector [0, 2, 4, 6, 8]
var vec = range(0, 0); # Creates an empty vector []
var vec = range(0, 1); # Creates a vector [0]
}}

=== remove() ===
{{Nasal doc
|syntax = remove(vector, value);
|source = {{simgear file|simgear/nasal/lib.c|l=53|t=Source}}
|text = Removes all elements equal to the given value from a vector and returns the modified vector.
|param1 = vector
|param1text = The vector from which elements are to be removed.
|param2 = value
|param2text = A value to remove from the vector.
|example1 =
var vector = [1, 2, 3]; # Initialize the vector.
remove(vector, 2); # Remove the value 2 from the vector.
debug.dump(vector); # Print the contents of the vector: "[1, 3]".
|example2 =
var vector = ["text", "text", "text"]; # Initialize the vector.
remove(vector, "text"); # Remove the value "text" from the vector.
debug.dump(vector); # Print the contents of the vector: "[]".
}}

=== removeat() ===
{{Nasal doc
|syntax = removeat(vector, index);
|source = {{simgear file|simgear/nasal/lib.c|l=72|t=Source}}
|text = Removes the element at the specified index from the vector and returns it.
|param1 = vector
|param1text = The vector from which the element will be removed.
|param2 = index
|param2text = Index of the item to be deleted.
|example1 =
var vector = [1, 2, 3]; # Initialize the vector.
removeat(vector, 0); # Remove the index 0 from the vector.
debug.dump(vector); # Print the contents of the vector: "[2, 3]".
}}

===right()===
{{Nasal doc
|syntax = right(string, length);
|source = {{simgear file|simgear/nasal/lib.c|l=226|t=Source}}
|version = 2.12
|commit = {{simgear commit|bd7163|t=commit}}
|text = Returns a substring of '''string''', starting from the right.
|param1 = string
|param1text = String to return part of.
|param2 = length
|param2text = Integer specifying the length of the substring to return.
|example1 = print(right("string", 2)); # prints "ng"
}}

=== setsize()===
{{Nasal doc
|syntax = setsize(vector, size);
|source = {{simgear file|simgear/nasal/lib.c|l=91|t=Source}}
|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.
|param1 = vector
|param1text = The vector to be operated on.
|param2 = size
|param2text = The desired size of the vector in number of entries.
|example1 =
var vector = [1, 2, 3]; # Initialize a vector
setsize(vector, 4);
debug.dump(vector); # print the vector "[1, 2, 3, nil]"
|example2 =
var vector = [1, 2, 3]; # Initialize a vector
setsize(vector, 2);
debug.dump(vector); # print the vector "[1, 2]"
}}

===size()===
{{Nasal doc
|syntax = size(object);
|source = {{simgear file|simgear/nasal/lib.c|l=26|t=Source}}
|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>.
|param1 = object
|param1text = Object to find the size of. Must be a string, a vector or a hash.
|example1 =
var string = "string";
print(size(string)); # prints "6"
|example2 =
var vector = [1, 2, 3];
print(size(vector)); # prints "3"
|example3 =
var hash = {
element1: "value1",
element2: "value2",
element3: "value3"
};
print(size(hash)); # prints "3"
}}

=== sort()===
{{Nasal doc
|syntax = sort(vector, function);
|source = {{simgear file|simgear/nasal/lib.c|l=678|t=Source}}
|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.
|param1 = vector
|param1text = Input vector to sort.
|param2 = function
|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.
{{{!}} class="wikitable"
! Return value !! Meaning
{{!-}}
{{!}} less than 0 {{!!}} first argument should go before second argument
{{!-}}
{{!}} 0 {{!!}} first argument equals second argument
{{!-}}
{{!}} greater than 0 {{!!}} first argument should go after second argument
{{!}}}

|example1text = This example sorts elements from smallest to greatest.
|example1 =
var sort_rules = func(a, b) {
if (a < b) {
return -1; # A should before b in the returned vector
} elsif (a == b) {
return 0; # A is equivalent to b
} else {
return 1; # A should after b in the returned vector
}
}
debug.dump(sort([3, 2, 5, 6, 4, 1], sort_rules)); # prints "[1, 2, 3, 4, 5, 6]"
|example2text = This example sorts elements from greatest to smallest.
|example2 =
# Outputs the elements in reverse order (greatest to smallest)
var sort_rules = func(a, b) {
if (a < b) {
return 1; # -1 in the above example
} elsif (a == b) {
return 0;
} else {
return -1; # 1 in the above example
}
}
debug.dump(sort([3, 2, 5, 6, 4, 1], sort_rules)); # prints "[6, 5, 4, 3, 2, 1]"
|example3text = This example sorts a vector of strings (runways for example) from smallest to greatest.
|example3 =
var runways = ["09R", "27R", "26L", "09L", "15"];
var rwy = sort(runways, func(a, b) cmp(a, b));
debug.dump(rwy); # prints ['09L', '09R', '15', '26L', '27R']
}}

=== split()===
{{Nasal doc
|syntax = split(delimiter, string);
|source = {{simgear file|simgear/nasal/lib.c|l=596|t=Source}}
|text = Splits the input string into a vector of substrings bounded by occurrences of the delimiter substring. See [[Nasal_library/string#string.join(sep,list)|string.join()]].
|param1 = delimiter
|param1text = String that will split the substrings in the returned vector.
|param2 = string
|param2text = String to split up.
|example1 = debug.dump(split("cd", "abcdef")); # prints "['ab', 'ef']"
|example2 = debug.dump(split(".", "3.2.0")); # prints "[3, 2, 0]"
|example3 = debug.dump(split("/", "path/to/file")); # prints "['path', 'to', 'file']"
}}

===sprintf()===
{{Nasal doc
|syntax = <nowiki>sprintf(format[, arg[, arg, [...]]]);</nowiki>
|source = {{simgear file|simgear/nasal/lib.c|l=491|t=Source}}
|text = Creates and returns a string formatted using ANSI C {{func link|vsnprintf()|link=http://en.cppreference.com/w/c/io/vfprintf}} <ref>
{{Cite web
|url = http://sourceforge.net/p/flightgear/simgear/ci/next/tree/simgear/nasal/lib.c#l308
|title = fgdata/simgear/simgear/nasal/lib.c, line 308
|accessdate = October 2015
}}
</ref>. Below is a table of supported format specifiers.
{{{!}} class="wikitable" width="75%"
{{!}}+ %[flags][width][.precision]specifier
! colspan="2" {{!}} Flags
{{!-}}
! Flag !! Output
{{!-}}
{{!}} <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.
{{!-}}
{{!}} ''space'' {{!!}} Prefixes non-signed numbers with a space.
{{!-}}
{{!}} <code>-</code> {{!!}} Left-align the output of this placeholder (the default is to right-align the output) when the width option is specified.
{{!-}}
{{!}} <code>0</code> {{!!}} Use 0 instead of spaces to pad a field when the width option is specified.
{{!-}}
{{!}} <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.
{{!-}}
! colspan="2" {{!}} Width
{{!-}}
{{!}} 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.
{{!-}}
! colspan="2" {{!}} Precision
{{!-}}
{{!}} colspan="2" {{!}} Integer preceded by a dot specifying the number of decimal places to be written.
{{!-}}
! colspan="2" {{!}} Specifiers
{{!-}}
! Specifier !! Output
{{!-}}
{{!}} <code>d</code>, <code>i</code> {{!!}} Signed decimal number.
{{!-}}
{{!}} <code>s</code> {{!!}} A string
{{!-}}
{{!}} <code>%</code> {{!!}} Percent (%) character.
{{!-}}
{{!}} <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.
{{!-}}
{{!}} <code>o</code> {{!!}} Unsigned integer as an octal number.
{{!-}}
{{!}} <code>u</code> {{!!}} Unsigned decimal integer.
{{!-}}
{{!}} <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.
{{!-}}
{{!}} <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.
{{!-}}
{{!}} <code>f</code> {{!!}} Floating-point number, in fixed decimal notation, by default with 6 decimal places.
{{!-}}
{{!}} <code>F</code> {{!!}} Appears to be available<ref>
{{Cite web
|url = http://sourceforge.net/p/flightgear/simgear/ci/next/tree/simgear/nasal/lib.c#l389
|title = fgdata/simgear/simgear/nasal/lib.c, line 389
|accessdate = October 2015
}}
</ref>, but doesn't work.
{{!-}}
{{!}} <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.
{{!}}}

|param1 = format
|param1text = String specifying the format. Can be used with or without a format specifiers. See below for examples.
|param2 = arg
|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.

|example1 = print(sprintf("%i", 54)); # prints "54"
|example2 = print(sprintf("Pi = %+.10f", math.pi)); # prints "Pi = +3.1415926536"
|example3 =
print(sprintf("%6d", 23)); # prints " 23"
print(sprintf("%06d", 23)); # prints "000023"
|example4 =
var FGVer = getprop("/sim/version/flightgear");
print(sprintf("You have FlightGear v%s", FGVer)); # prints "You have FlightGear v<your version>"
|example5 =
print(sprintf("Hexadecimal 100000 = %X", 100000)); # prints "Hexadecimal 100000 = 186A0"
print(sprintf("Hexadecimal 100000 = %x", 100000)); # prints "Hexadecimal 100000 = 186a0"
|example6 = print(sprintf("Code 65 is %c", 65)); # prints "Code 65 is A"
|example7 =
print(sprintf("%e", 54)); # prints "5.400000e+001"
print(sprintf("%E", 54)); # prints "5.400000E+001"
|example8 = print(sprintf("%o", 54)); # prints "66"
|example9 = print(sprintf("50%% of 100 is %i", 100 / 2)); # prints "50% of 100 is 50"
|example10 =
print(sprintf("%.2f", 1.4)); # prints "1.40"
print(sprintf("%.1f", 1.4)); # prints "1.4"
print(sprintf("% 4.1f", 1.4)); # prints " 1.4"
print(sprintf("%04.1f", 1.4)); # prints "01.4"
print(sprintf("% 6.1f", 1.4)); # prints " 1.4"
print(sprintf("%06.1f", 1.4)); # prints "0001.4"
}}

===str()===
{{Nasal doc
|syntax = str(value);
|source = {{simgear file|simgear/nasal/lib.c|l=186|t=Source}}
|text = Convert given value (scalar) to string. If <code>value</code> is a number, it will be converted to a string. If <code>value</code> is a string, the same string will be returned. If <code>value</code> is not a scalar (hash, vector, nil), <code>nil</code> will be returned.
|param1 = value
|param1text = The value to convert to string.
|example1 =
var result = str(true); # result is a string "1"
var result = str(false); # result is a string "0"
var result = str(12); # result is a string "12"
var result = str(12.5); # result is a string "12.5"
var result = str(-12.5); # result is a string "-12.5"
var result = str("12.5"); # result is a string "12.5"
var result = str([1, 2]); # result is a nil
var result = str({ x: 0 }); # result is a nil
var result = str(nil); # result is a nil
}}

===streq()===
{{Nasal doc
|syntax = streq(a, b);
|source = {{simgear file|simgear/nasal/lib.c|l=164|t=Source}}
|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.}}
|param1 = a
|param1text = First argument for testing equality.
|param2 = b
|param2text = Second argument for testing equality.
|example1 = print(streq("0", "0")); # prints "1" (True)
|example2 =
print(0 == 0.0); # prints "1" (True)
print(streq("0", "0.0")); # prints "0" (False)
}}

===substr()===
{{Nasal doc
|syntax = substr(string, start [, length]);
|source = {{simgear file|simgear/nasal/lib.c|l=194|t=Source}}
|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).
|param1 = string
|param1text = String to return a substring from.
|param2 = start
|param2text = Integer specifying the start of a substring. Negative values specify a position from the end of the string.
|param3 = length
|param3text = Optional argument specifying the length of the substring. Defaults to the end of the string.
|example1 = print(substr("abcde", 1, 3)); # prints "bcd"
|example2 = print(substr("abcde", 1)); # prints "bcde"
|example3 = print(substr("abcde", 2, 1)); # prints "c"
|example4 = print(substr("abcde", -2)); # prints "de"
|example5 = print(substr("abcde", -3, 2)); # prints "cd"
}}

===subvec()===
{{Nasal doc
|syntax = subvec(vector, start[, length]);
|source = {{simgear file|simgear/nasal/lib.c|l=98|t=Source}}
|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).
|param1 = vector
|param1text = The vector to take the sub-vector from.
|param2 = start
|param2text = The starting point of the sub-vector within the given vector.
|param3 = length
|param3text = Optional argument specifying the length of the sub-vector, from the starting point.
'''Notes:'''
* Omitting the ''vector'' and ''start'' arguments is not an error (possibly it should be) but the return value is ''nil''.
* A negative ''start'' argument ''is'' an error. This seems wrong. Perhaps the language designer could comment.
* A value of ''start'' greater than ''size(vector)'' causes an error. A value equal to ''size(vector)'' returns an empty vector.
* 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.
|example1 =
var vector = [1, 2, 3];
debug.dump(subvec(vector, 0)); # prints "[1, 2, 3]"
|example2 =
var vector = [1, 2, 3];
debug.dump(subvec(vector, 1)); # prints "[2, 3]"
|example3 =
var vector = [1, 2, 3];
debug.dump(subvec(vector, 1, 1)); # prints "[2]"
}}

=== typeof()===
{{Nasal doc
|syntax = typeof(object);
|source = {{simgear file|simgear/nasal/lib.c|l=287|t=Source}}
|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.
|param1 = object
|param1text = Object to return the type of.
|example1 =
var object = nil;
print(typeof(object)); # prints "nil"
|example2 =
var object = "Hello world!";
print(typeof(object)); # prints "scalar"
|example3 =
var object = math.pi;
print(typeof(object)); # prints "scalar"
|example4 =
var object = [1, 2, 3];
print(typeof(object)); # prints "vector"
|example5 =
var object = {};
print(typeof(object)); # prints "hash"
|example6 =
var object = func {};
print(typeof(object)); # prints "func"
|example7 =
var object = airportinfo();
print(typeof(object)); # prints "ghost"
}}



==Extension functions==
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:
*{{flightgear file|src/Scripting/NasalPositioned.cxx}}
*{{flightgear file|src/Scripting/NasalSys.cxx}}
*{{fgdata file|Nasal/globals.nas}}

===abort()===
{{Nasal doc
|syntax = abort();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=565|t=Source}}
|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).
|example1text = This example will immediately stop FlightGear with an error, such as "FlightGear has stopped working."
|example1 = abort();
|example2text = For exiting FlightGear in a better way, please use the following code:
|example2 = fgcommand("exit");
}}

=== abs() ===
{{Nasal doc
|syntax = abs(number);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = This simple function returns the {{wikipedia|absolute value|noicon=1}} of the provided number.
|param1 = number
|param1text = This argument is required and should be a number.
|example1 = print(abs(1)); # prints "1"
|example2 = print(abs(-1)); # prints "1"
}}

===aircraftToCart() ===
This new function in FG 2017.2.1 takes coordinates in aircraft structural coordinate system, and translate them into geocentric coordinates.
Example for (5,6,7):
<syntaxhighlight lang="nasal">
var pos = aircraftToCart({x: -5, y: 6, z: -7});
var coord = geo.Coord.new();
coord.set_xyz(pos.x, pos.y, pos.z);
</syntaxhighlight>
Notice: x and z is inverted sign on purpose.
if you want lat. lon, alt from that, just call: (degrees and meters)

<syntaxhighlight lang="nasal">
coord.lat()
coord.lon()
coord.alt()
</syntaxhighlight>

===addcommand() ===
{{Nasal doc
|syntax = addcommand(name, code);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=659|t=Source}}
|version = 2.12
|commit = {{flightgear commit|7b663c|t=commit}}
|text = {{see also|Howto:Add new fgcommands to FlightGear}}

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.
|param1 = name
|param1text = This will become the name of the new fgcommand. Must be a string.
|param2 = code
|param2text = The code that will be executed when the fgcommand is run. Must be a function.
|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.
|example1 = addcommand("myFGCmd", func(node) {
print("fgcommand 'myFGCmd' has been run.");
props.dump( node );
});
fgcommand("myFGCmd", props.Node.new({foo:1, bar:2}) );
|example2text = This example demonstrates how parameters are defined in a new fgcommand.
|example2 = addcommand("myFGCmd", func(node){
print(node.getNode("number").getValue()); # prints the value of "number," which is 12
});
fgcommand("myFGCmd", props.Node.new({"number": 12}));
}}

===airportinfo()===
{{Nasal doc
|syntax = airportinfo();
airportinfo(type);
airportinfo(id);
airportinfo(lat, lon[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1024|t=Source}}
|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:
* '''parents''': A vector containing a hash of various functions to access information about the runway. These functions are:
** '''findBestRunwayForPos()''' return runway as ghost by given geo position, e.g. <code>var rwy = airportinfo().findBestRunwayForPos(geo.aircraft_position());</code>.
** '''runway()''' return runway as ghost by runway ID, e.g. <code>var rwy = airportinfo().runway("18R");</code>.
** '''runwaysWithoutReciprocals()''' return vector of runways as ghost.
** '''helipad()''' return helipad as ghost by helipad ID, e.g. <code>var heli = airportinfo().helipad("H19");</code>.
** '''tower()''' return hash with <code>lat</code>, <code>lon</code>, <code>elevation</code> fields.
** '''comms()''' return vector of hashes, each hash with <code>frequency</code> and <code>ident</code> fields.
** '''sids()''' return vector of strings with SID IDs.
** '''stars()''' return vector of strings with STAR IDs.
** '''getApproachList()''' return vector of string with approaches.
** '''parking()''' return vector of hashes, each hash with <code>lat</code>, <code>lon</code>, <code>elevation</code>, <code>name</code> fields.
** '''getSid()''' return SID as ghost, e.g. <code>var sid = airportinfo().getSid("SA1A");</code>.
** '''getStar()''' return STAR as ghost, e.g. <code>var star = airportinfo().getStar("KEILA1");</code>.
** '''getIAP()''' return IAP as ghost, e.g. <code>var iap = airportinfo().getIAP("ILS02");</code>.
** '''getApproach()''' return approach as ghost, e.g. <code>var approach = airportinfo().getApproach("ILS02");</code>.
** '''tostring()''' just return string "an airport ICAO".
** See also {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1902}}.
* '''lon''': Longitude of the location.
* '''lat''': Latitude of the location.
* '''has_metar''': True or false depending whether the airport has a [[METAR]] code defined for it.
* '''elevation''': Elevation of the location in metres.
* '''id''': ICAO code of the airport (or ID of the seaplane base/heliport).
* '''name''': Name of the airport/heliport/seaplane base.
* '''runways'''
** '''<runway name>'''
*** '''id''': Name of runway.
*** '''lat''': Latitude of the runway.
*** '''lon''': Longitude of the runway.
*** '''heading''': True heading of the runway.
*** '''length''': Length of the runway in metres.
*** '''width''': Width of the runway in metres.
*** '''surface''': Runway surface type.
*** '''threshold''': Length of the runway's {{wikipedia|displaced threshold}} in metres. Will return 0 if there is none.
*** '''stopway''': Length of the runway's stopway (the area before the threshold) in metres. Will return 0 if there is none.
*** '''reciprocal''': <code>runway</code> ghost of the reciprocal runway.
*** '''ils_frequency_mhz''': ILS frequency in megahertz.
*** '''ils''': <code>navaid</code> ghost of the ILS transmitter.
* '''helipads'''
** '''<helipad name>'''
*** '''id''': Name of helipad.
*** '''lat''': Latitude of the helipad.
*** '''lon''': Longitude of the helipad.
*** '''heading''': True heading of the helipad.
*** '''length''': Length of the helipad in metres.
*** '''width''': Width of the helipad in metres.
*** '''surface''': Helipad surface type.
* '''taxiways'''
** '''<taxiway name>'''
*** '''id''': Name of taxiway.
*** '''lat''': Latitude of the taxiway.
*** '''lon''': Longitude of the taxiway.
*** '''heading''': Heading of the taxiway.
*** '''length''': Length of the taxiway in metres.
*** '''width''': Width of the taxiway in metres.
*** '''surface''': Taxiway surface type.

Information is extracted in the same way as accessing members of a Nasal hash. For example:
<syntaxhighlight lang="nasal">
# prints to lengths of the runways of the nearest airport in feet and metres
var info = airportinfo();
print("-- Lengths of the runways at ", info.name, " (", info.id, ") --");
foreach(var rwy; keys(info.runways)){
print(rwy, ": ", math.round(info.runways[rwy].length * M2FT), " ft (", info.runways[rwy].length, " m)");
}
</syntaxhighlight>

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.
|param1 = id
|param1text = The {{wikipedia|International Civil Aviation Organization airport code|ICAO code|noicon=1}} of an airport to retrieve information about.
|param2 = type
|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).
: {{inote|Running this function without any parameters is equivalent to this:
: <syntaxhighlight lang="nasal">
airportinfo("airport");
</syntaxhighlight>
}}
|param3 = lat ''and'' lon
|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.
|example1 = var info = airportinfo();
print("Nearest airport: ", info.name, " (", info.id, ")"); # prints the name and ICAO code of the nearest airport
|example2 = var info = airportinfo("heliport");
print("Elevation of the nearest heliport: ", math.round(info.elevation * M2FT), " ft"); # prints the elevation and name of the nearest heliport
|example3 = var info = airportinfo("KSQL");
print("-- Runways of ", info.name, " (", info.id, "): --");
foreach(var rwy; keys(info.runways)) {
print(rwy); # prints the runways of KSQL
}
|example4 = var info = airportinfo(37.81909385, -122.4722484);
print("Coordinates of the nearest airport: ", info.lat, ", ", info.lon); # print the name and ICAO of the nearest airport to the Golden Gate Bridge
|example5 = var info = airportinfo(37.81909385, -122.4722484, "seaport");
print("Nearest seaplane base: ", info.name, " (", info.id, ")"); # print the name and ID of the nearest seaplane base to the Golden Gate Bridge
|example6text = This example prints the all information from an <code>airportinfo()</code> call.
|example6 = var info = airportinfo("KSFO");
print(info.name);
print(info.id);
print(info.lat);
print(info.lon);
print(info.has_metar);
print(info.elevation);
foreach(var rwy; keys(info.runways)){
print("-- ", rwy, " --");
print(info.runways[rwy].lat);
print(info.runways[rwy].lon);
print(info.runways[rwy].length);
print(info.runways[rwy].width);
print(info.runways[rwy].heading);
print(info.runways[rwy].stopway);
print(info.runways[rwy].threshold);
<nowiki>}</nowiki>
}}

===airwaysRoute() ===
{{Nasal doc
|syntax = airwaysRoute(start, end[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1933|t=Source}}
|text = {{see also|Nasal Flightplan}}
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.
|param1 = start
|param1text = Start waypoint, in the form of a waypoint ghost, such as that provided by {{func link|flightplan()}}.
|param2 = end
|param2text = Same as above.
|param3 = type
|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."
|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.
|example1 = var fp = flightplan();
var start = fp.getWP(0);
var end = fp.getWP(fp.getPlanSize() - 1);
var rt = airwaysRoute(start, end);
foreach(var wp; rt){
print(wp.wp_name); # print the waypoints in the computed route
}
|example2text = Exactly the same as above, but computes a low level path.
|example2 = var fp = flightplan();
var start = fp.getWP(0);
var end = fp.getWP(fp.getPlanSize() - 1);
var rt = airwaysRoute(start, end, "lowlevel");
foreach(var wp; rt){
print(wp.wp_name); # print the waypoints in the computed route
<nowiki>}</nowiki>
}}

===airway()===

{{Nasal doc
|syntax = airway(ident [, pos]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2644|t=Source}}
|text = {{see also|Nasal Flightplan}}
This function returns a ghost containing an airway of a specified id.
|param1 = ident
|param1text = a Positioned ghost (leg, navaid, airport) and so on, passed to the search function.
|param2 = pos
}}

===assert()===
{{Nasal doc
|syntax = assert(condition[, message]);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|version = 3.2
|commit = {{fgdata commit|8b16a7|t=commit}}
|text = Returns either true if the condition evaluates as true, or aborts with a {{func link|die()}} call, which can be customised.
|param1 = condition
|param1text = Condition to evaluate.
|param2 = message
|param2text = Optional message that will be used in any {{func link|die()}} call. Defaults to "assertion failed!"
|example1 = var a = 1;
var b = 2;
print(assert(a < b)); # prints "1" (true)
|example2 = var a = 1;
var b = 2;
assert(a > b, 'a is not greater than b'); # aborts with a custom error message
}}

===carttogeod()===
{{Nasal doc
|syntax = carttogeod(x, y, z);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=945|t=Source}}
|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>
|param1 = x
|param1text = Mandatory x-axis value, in metres.
|param2 = y
|param2text = Mandatory y-axis value, in metres.
|param3 = z
|param3text = Mandatory z-axis value, in metres.
|example1 = var (lat, lon, alt) = carttogeod(6378137, 0, 0); # point is the intersection of the prime meridian and equator.
print("Latitude: ", lat); # prints lat, lon and alt, which are all zero, see above
print("Longitude: ", lon);
print("Altitude: ", alt);
}}

===cmdarg()===
{{Nasal doc
|private = _cmdarg()
|syntax = cmdarg();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=513|t=Part 1}} {{!}} {{fgdata file|Nasal/globals.nas|t=Part 2}}
|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.
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:
* Bindings: This is needed so that the value of a joystick's axis can be accessed internally.
* 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).
* 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.
* 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>

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.

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.
|example1 = fgcommand("dialog-show", {"dialog-name": "cmdarg-demo"});
|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.
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>

<PropertyList>

<name>cmdarg-demo</name>
<layout>vbox</layout>

<text>
<label>Click "Close" to activate the demonstration (a message in the console).</label>
</text>

<button>
<legend>Close</legend>
<binding>
<command>nasal</command>
<script>print("Button binding root: '" ~ cmdarg().getPath() ~ "'");</script>
</binding>
<binding>
<command>dialog-close</command>
</binding>
</button>

</PropertyList>
</syntaxhighlight>
|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!"
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>

<PropertyList>

<name>cmdarg-demo</name>
<layout>vbox</layout>

<text>
<label>Click "Click me!" to activate the demonstration (the button's label will change).</label>
</text>

<button>
<legend>Click me!</legend>
<binding>
<command>nasal</command>
<script>change_label();</script>
</binding>
</button>

<button>
<legend>Close</legend>
<binding>
<command>dialog-close</command>
</binding>
</button>

<nasal>
<open><![CDATA[
var dlg_root = cmdarg();
var dlg_name = {"dialog-name": "cmdarg-demo"};
var change_label = func {
dlg_root.getNode("button[0]/legend").setValue("I've been changed!");
fgcommand("dialog-close", dlg_name);
fgcommand("dialog-show", dlg_name);
}
]]></open>
</nasal>

</PropertyList>
</syntaxhighlight>
|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]].
}}

===courseAndDistance()===
{{Nasal doc
|syntax = courseAndDistance(to);
courseAndDistance(from, to);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1668|t=Source}}
|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:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object with geodetic coordinates (cartesian coordinates will not be accepted)
|param1 = from
|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.
|param2 = to
|param2text = Like the first parameter, but defines the second point.
|example1text = This example demonstrates the usage of the function with the <code>airport</code> ghost type.
|example1 = var from = airportinfo("KSFO");
var to = airportinfo("KSQL");
var (course, dist) = courseAndDistance(from, to);
print(course); # prints course from KSFO to KSQL
print(dist); # prints distance in nm from KSFO to KSQL
|example2text = This example demonstrates the usage of the function with hashes containing ''lat'' and ''lon''.
|example2 = var from = {lat: 0, lon: 0};
var to = {lat: 1, lon: 1};
var (course, dist) = courseAndDistance(from, to);
print(course);
print(dist);
|example3text = This example demonstrates usage of a geo.Coord object.
|example3 = var from = geo.Coord.new().set_latlon(0, 0);
var to = geo.Coord.new().set_latlon(1, 1);
var (course, dist) = courseAndDistance(from, to);
print(course);
print(dist);
|example4text = This example demonstrates usage of differing parameter types.
|example4 = var from = airportinfo("KSFO");
var to = geo.Coord.new().set_latlon(0, 0);
var (course, dist) = courseAndDistance(from, to);
print(course);
print(dist);
|example5text = The same as above, but the other way round.
|example5 = var to = {lat: 1, lon: 1};
var (course, dist) = courseAndDistance(0, 0, to);
print(course);
print(dist);
|example6text = Usage of just one parameter.
|example6 = var dest = airportinfo("KSQL");
var (course, dist) = courseAndDistance(dest);
print("Turn to heading ", math.round(course), ". You have ", sprintf("%.2f", dist), " nm to go");
}}

===createFlightplan()===
{{Nasal doc
|syntax = createFlightplan(path);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2331|t=Source}}
|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.
|param1 = path
|param1text = Optional parameter defining the file from which a flightplan will be populated.
|example1 =
var path = getprop("/sim/fg-home") ~ "/Export/test.fgfp";
var flightplan = createFlightplan(path);
debug.dump(flightplan);
}}

===createDiscontinuity()===
{{Nasal doc
|syntax = createDiscontinuity();
|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.
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2045|t=Source}}
|version = 2016.1
|commit = {{flightgear commit|caead6|t=commit}}
}}
===createViaTo()===
{{Nasal doc
|syntax = createViaTo(airway, waypoint);
|text = Returns a <code>waypoint</code> ghost object. It represents a route "via '''airway''' to '''waypoint'''".
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2009|t=Source}}
|version = 2016.1
|commit = {{flightgear commit|caead6|t=commit}}
|param1 = airway
|param1text = The name of an airway.
|param2 = waypoint
|param2text = Must be in the airway and one of:
* The name of a waypoint.
* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, or <code>fix</code> ghost object.
}}
===createWP()===
{{Nasal doc
|syntax = createWP(pos, name[, flag]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1964|t=Source}}
|text = Creates a new waypoint ghost object.
|param1 = pos
|param1text = Dictates the position of the new waypoint. It can be one of the following:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. See example 4 below.
|param2 = name
|param2text = String that will become the name of the new waypoint.
|param3 = flag
|param3text = Optional string that will tell FlightGear what type of waypoint it is. Must be one of "sid," "star," "approach," "missed," or "pseudo."
|example1text = Creates a waypoint directly in front and 1 km away and appends it to the flight plan.
|example1 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);
var wp = createWP(pos, "NEWWP");
var fp = flightplan();
fp.appendWP(wp);
|example2 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);
var wp = createWP({lat: pos.lat(), lon: pos.lon()}, "NEWWP");
var fp = flightplan();
fp.appendWP(wp);
|example3 = var apt = airportinfo();
var wp = createWP(apt, "NEWWP");
var fp = flightplan();
fp.appendWP(wp);
|example4 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);
var wp = createWP(pos.lat(), pos.lon(), "NEWWP");
var fp = flightplan();
fp.appendWP(wp);
|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.
|example5 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);
var wp = createWP(pos, "NEWWP", "pseudo");
var fp = flightplan();
fp.appendWP(wp);
print(fp.getPlanSize());
fp.clearWPType("pseudo");
print(fp.getPlanSize());
}}

===createWPFrom()===
{{Nasal doc
|syntax = createWPFrom(object[, flag]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1989|t=Source}}
|text = Creates a new waypoint object from another object.
|param1 = object
|param1text = A ghost object. Must be a ghost type that is one of "airport," "navaid," "runway," or "fix."
|param2 = flag
|param2text = Optional string that will tell FlightGear what type of waypoint it is. Must be one of "sid," "star," "approach," "missed," or "pseudo."
|example1text = Creates a new waypoint and appends it to the flight plan.
|example1 = var apt = airportinfo("KSFO");
var wp = createWPFrom(apt);
var fp = flightplan();
fp.appendWP(wp);
|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.
|example2 = var apt = airportinfo("KSFO");
var wp = createWPFrom(apt, "pseudo");
print(wp.wp_name);
var fp = flightplan();
fp.appendWP(wp);
print(fp.getPlanSize());
fp.clearWPType("pseudo");
print(fp.getPlanSize());
}}

===defined()===
{{Nasal doc
|syntax = defined(symbol);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = Returns 1 (true) or 0 (false) depending on whether a variable exists.
|param1 = symbol
|param1text = A string that will be what the function searches for.
|example1 = var number = 12;
var check_exist = func {
print("Variable 'number' ", defined("number") == 1 ? "exists" : "does not exist"); # 'number' does exist
print("Variable 'number2' ", defined("number2") == 1 ? "exists" : "does not exist"); # 'number2' does not exist
}
check_exist();
}}

===directory()===
{{Nasal doc
|syntax = directory(path);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=572|t=Source}}
|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.
{{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.}}
|param1 = path
|param1text = Absolute file path.
|example1text = Gets the folders and files in [[$FG_ROOT]], and then removes the extra first two elements (see note above).
|example1 = var dir = directory(getprop("/sim/fg-root")); # get directory
dir = subvec(dir, 2); # strips off the first two elements
debug.dump(dir); # dump the vector
}}

===fgcommand()===
{{Nasal doc
|syntax = fgcommand(cmd[, args]);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=456|t=Part 1}} {{!}} {{fgdata file|Nasal/globals.nas|t=Part 2}}
|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.
|param1 = cmd
|param1text = String that is the name of the command that is to be run.
|param2 = args
|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).
|example1 = fgcommand("null"); # does nothing
|example2 = var args = props.Node.new({'script': 'print("Running fgcommand");'});
if (fgcommand("nasal", args)) { # prints "Running fgcommand" and then one of these print statements
print("Fgcommand succeeded");
} else {
print("Fgcommand encountered a problem");
}
|example3 = var args = { 'dialog-name': 'about' };
fgcommand("dialog-show", args); # shows the 'about' dialog
}}

===findAirportsByICAO() ===
{{Nasal doc
|syntax = findAirportsByICAO(search[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1096|t=Source}}
|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.
|param1 = search
|param1text = Search string for the function. Can either be a partial or a full ICAO code.
:{{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.}}
|param2 = type
|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."
|example1 = var apts = findAirportsByICAO("KSF"); # finds all airports matching "KSF"
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")"); # prints them
}
|example2 = var apts = findAirportsByICAO("SP0", "seaport"); # finds all seaplane bases matching "SP0"
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")"); # prints them
}
|example3 = var apt = findAirportsByICAO("XBET"); # one way to check if an airport does exist"
if (size(apt) == 0) {
print("Airport does not exist"); # this one will be printed
} else {
print("Airport does exist");
<nowiki>}</nowiki>
}}

===findAirportsWithinRange()===
{{Nasal doc
|syntax = findAirportsWithinRange([pos, ]range[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1066|t=Source}}
|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.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findAirportsWithinRange(lat, lon, range, type);</code>.
|param2 = range
|param2text = Mandatory number giving the range in nautical miles within which to search for airports/heliports/seaplane bases.only airports are searched for.
|param3 = type
|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."
|example1text = Searches for airports within 10 nm of [[KSFO]].
|example1 = var pos = airportinfo("KSFO");
var apts = findAirportsWithinRange(pos, 10);
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")");
}
|example2text = Searches for seaplane bases within 15 nm of [[KSFO]].
|example2 = var pos = airportinfo("KSFO");
var apts = findAirportsWithinRange(pos, 15, "seaport");
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")");
}
|example3text = Searches for airports within 10 nm of your current position.
|example3 = var apts = findAirportsWithinRange(10);
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")");
<nowiki>}</nowiki>
}}

===findCommByFrequencyMHz()===
findCommByFrequencyMHz([pos, ]freq[, type]);
[[sourceforge:p/flightgear/flightgear/ci/next/tree/src/Scripting/NasalPositioned.cxx#l1547|source]]

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.

'''pos'''

: Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findCommByFrequencyMHz(lat, lon, freq, type);</code>.
; freq
: Frequency, in megahertz, of the station to search for.
; type
: 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)
'''Example'''
var com = findCommByFrequencyMHz(123.6);
print("ID: ", com.id); # prints info about the comm station
print("Name: ", com.name);
print("Latitude: ", com.lat);
print("Longitude: ", com.lon);
print("Type: ", com.type);
print("Frequency: ", sprintf("%.3f", com.frequency), " Mhz");

=== findFixesByID() ===
{{Nasal doc
|syntax = findFixesByID([pos, ]id);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1627|t=Source}}
|text = Returns a vector containing <code>fix</code> ghost objects matching a given ID, sorted by range from a certain position.
{{inote|Fixes are (usually) also known as waypoints.}}
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findFixesByID(lat, lon, id);</code>.
|param2 = id
|param2text = Full or partial ID of the fix to search for.
:{{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.}}
|example1 = var fixes = findFixesByID("POGIC");
foreach(var fix; fixes){
print(fix.id, " - lat: ", fix.lat, " {{!}} lon: ", fix.lon); # prints information about POGIC
}
|example2 = var fix = findFixesByID("ZUNAP");
fix = fix[0];
var (course, dist) = courseAndDistance(fix);
print("Turn to heading ", math.round(course), ". You have ", sprintf("%.2f", dist), " nm to go to reach ", fixes[0].id);
}}

===findNavaidByFrequencyMHz()===
{{Nasal doc
|syntax = findNavaidByFrequencyMHz([pos, ]freq[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1547|t=Source}}
|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.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidByFrequencyMHz(lat, lon, freq, type);</code>.
|param2 = freq
|param2text = Frequency, in megahertz, of the navaid to search for.
|param3 = type
|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}}.
|example1 = var navaid = findNavaidByFrequencyMHz(109.55);
print("ID: ", navaid.id); # prints info about the navaid
print("Name: ", navaid.name);
print("Latitude: ", navaid.lat);
print("Longitude: ", navaid.lon);
print("Elevation (AMSL): ", navaid.elevation, " m");
print("Type: ", navaid.type);
print("Frequency: ", sprintf("%.3f", navaid.frequency / 100), " Mhz");
print("Range: ", navaid.range_nm, " nm");
if(navaid.course) print("Course: ", navaid.course);
}}

=== findNavaidsByFrequencyMHz()===
{{Nasal doc
|syntax = findNavaidsByFrequencyMHz([pos, ]freq[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1572|t=Source}}
|text = Returns a vector conatining <code>navaid</code> ghost objects for navaids that match a given frequency, sorted from nearest to furthest.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidsByFrequencyMHz(lat, lon, freq, type);</code>.
|param2 = freq
|param2text = Frequency, in megahertz, of the navaid to search for.
|param3 = type
|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}}.
|example1 = var navaids = findNavaidsByFrequencyMHz(109.55);
foreach(var navaid; navaids){
print("--");
print("ID: ", navaid.id); # prints info about the navaid
print("Name: ", navaid.name);
print("Latitude: ", navaid.lat);
print("Longitude: ", navaid.lon);
print("Elevation (AMSL): ", navaid.elevation, " m");
print("Type: ", navaid.type);
print("Frequency: ", sprintf("%.3f", navaid.frequency / 100), " Mhz");
print("Range: ", navaid.range_nm, " nm");
if(navaid.course) print("Course: ", navaid.course);
print("--");
<nowiki>}</nowiki>
}}

===findNavaidsByID()===
{{Nasal doc
|syntax = findNavaidsByID([pos, ]id[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1600|t=Source}}
|text = Returns a vector containing <code>navaid</code> ghost objects matching a given ID, sorted by range from a certain position.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidsByID(lat, lon, id, type);</code>.
|param2 = id
|param2text = Full or partial ID of the fix to search for.
:{{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.}}
|param3 = type
|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}}.
|example1 = var navaid = findNavaidsByID("MXW");
navaid = navaid[0];
print("ID: ", navaid.id); # prints info about 'MXW' (a VOR station)
print("Name: ", navaid.name);
print("Latitude: ", navaid.lat);
print("Longitude: ", navaid.lon);
print("Elevation (AMSL): ", navaid.elevation, " m");
print("Type: ", navaid.type);
print("Frequency: ", sprintf("%.3f", navaid.frequency / 1000), " Mhz");
print("Range: ", navaid.range_nm, " nm");
}}

===findNavaidsWithinRange()===
{{Nasal doc
|syntax = findNavaidsWithinRange([pos, ]range[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1518|t=Source}}
|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.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidsWithinRange(lat, lon, range, type);</code>.
|param2 = range
|param2text = Mandatory number giving the range in nautical miles within which to search for navaids.
|param3 = type
|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}}.
|example1text = Searches for navaids within 10 nm of [[KSFO]].
|example1 = var pos = airportinfo("KSFO");
var navs = findNavaidsWithinRange(pos, 10);
foreach(var nav; navs){
print(nav.name, " (ID: ", nav.id, ")");
}
|example2text = Searches for navaids within 10 nm of your current position.
|example2 = var navs = findNavaidsWithinRange(10);
foreach(var nav; navs){
print(nav.name, " (ID: ", nav.id, ")");
<nowiki>}</nowiki>
}}

===finddata()===
{{Nasal doc
|syntax = finddata(path);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=603|t=Source}}
|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]].
|param1 = path
|param1text = A relative path as a string.
|example1 = var path = finddata("Aircraft/Generic");
print(path); # prints the absolute path to $FG_ROOT/Aircraft/Generic
|example2 = var path = finddata("Airports");
print(path); # prints the absolute path to <TerraSync dir>/Airports
|example3 = var path = finddata("preferences.xml");
print(path); # prints the absolute path to $FG_ROOT/preferences.xml
}}

===flightplan()===
{{Nasal doc
|syntax = flightplan([path]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1738|t=Source}}
|text = {{see also|Nasal Flightplan}}
Returns a flight plan object, either one for the current flight plan, or one loaded from a given path.
|param1 = path
|param1text = Optional path to flight plan XML file.
|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.
|example1 = var fp = flightplan();
print(fp.getWP(fp.current).id);
|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>.
|example2 = var path = getprop('/sim/fg-home') ~ '/fp-demo.xml';
var fp = flightplan(path);
for(var i = 0; i < fp.getPlanSize(); i += 1){
print(fp.getWP(i).id);
<nowiki>}</nowiki>
}}

===geodinfo()===
{{Nasal doc
|syntax = geodinfo(lat, lon[, max_alt]);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=981|t=Source}}
|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}}):
* '''light_coverage:''' The coverage of a single point of light in m<sup>2</sup>.
* '''bumpiness:''' Normalized bumpiness factor for the material.
* '''load_resistance:''' The amount of pressure in N/m<sup>2</sup> the material can withstand without deformation.
* '''solid:''' 1 (true) or false (0) depending on whether the material is solid or not.
* '''names:''' Vector of scenery types (usually generated by [[TerraGear]]) that will use this material.
* '''friction_factor:''' Normalized friction factor of the material.
* '''rolling_friction:''' The rolling friction coefficient of the material.

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.
|param1 = lat
|param1text = Latitude, inputted as a number.
|param2 = lon
|param2text = Longitude, inputted as a number.
|param3 = max_alt
|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.
|example1text = Dumps information about ground underneath the aircraft.
|example1 = var pos = geo.aircraft_position();
var info = geodinfo(pos.lat(), pos.lon());
debug.dump(info);
|example2text = Prints whether the ground underneath the aircraft is solid or is water.
|example2 = var pos = geo.aircraft_position();
var info = geodinfo(pos.lat(), pos.lon());
if (info != nil and info[1] != nil) {
print("The ground underneath the aircraft is ", info[1].solid == 1 ? "solid." : "water.");
<nowiki>}</nowiki>
}}

=== geodtocart() ===
{{Nasal doc
|syntax = geodtocart(lat, lon, alt);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=962|t=Source}}
|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.
|param1 = lat
|param1text = Latitude, in degrees.
|param2 = lon
|param2text = Longitude, in degrees.
|param3 = alt
|param3text = Altitude, in metres.
|example1 = var (x, y, z) = geodtocart(0, 0, 0); # point is the intersection of the prime meridian and equator.
print("x: ", x); # prints "x: 6378137"
print("y: ", y); # prints "y: 0"
print("z: ", z); # prints "y: 0"
}}

=== get_cart_ground_intersection()===
Introduced in 2017.2.1, see [[Terrain Detection]].

===getprop()===
{{Nasal doc
|syntax = <nowiki>getprop(path[, path[, ...]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=345|t=Source}}
|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).
|param1 = path
|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.
|example1 = print("You have FlightGear v", getprop("/sim/version/flightgear")); # prints FlightGear version
|example2text = Note that the example below will only work in FlightGear 3.2 and above.
|example2 = for(var i = 0; i < 8; i += 1){
print("View #", i + 1, " is named ", getprop("/sim/view", i, "name"));
}
|example3text = Same as above, but is supported by all versions of FlightGear.
|example3 = for(var i = 0; i < 8; i += 1){
print("View #", i + 1, " is named ", getprop("/sim/view[" ~ i ~ "]/name"));
<nowiki>}</nowiki>
}}
==== See also====
{{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:
To get a Node rather than its value, use <code>props.globals.getNode()</code> - see [[Nasal_library/props]]. }}

===greatCircleMove()===
{{Nasal doc
|syntax = greatCircleMove([pos, ]course, dist);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1681|t=Source}}
|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).
|param1 = pos
|param1text = Optional position to calculate from. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost object.
:* A hash with ''lat'' and ''lon'' members
:* A <code>geo.Coord</code> object
:* A lat/lon pair, that is, a pair of numbers (latitude followed by longitude) separated by a comma: <code>greatCircleMove(lat,lon, ...)</code>.
|param2 = course
|param2text = Course to new set of coordinates, in degrees (in the range 0–360).
|param3 = dist
|param3text = Distance in nautical miles to the new set of coordinates.
|example1 = var pos = greatCircleMove(0,0, 0, 1);
debug.dump(pos); # print hash with coordinates
|example2 = var fix = findFixesByID("POGIC");
fix = fix[0];
var pos = greatCircleMove(fix, 45, 10);
debug.dump(pos); # print hash with coordinates
}}

===interpolate()===
{{Nasal doc
|private = _interpolate()
|syntax = <nowiki>interpolate(prop, value1, time1[, value2, time2[, ...]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=522|t=Part 1}} {{!}} {{fgdata file|Nasal/globals.nas|t=Part 2}}
|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.
|param1 = prop
|param1text = String or <code>props.Node</code> object that indicates a node in the property tree to be used.
|param2 = value''n''
|param2text = Target value to change the property to in the set amount of time. This should be a number.
|param3 = time''n''
|param3text = Time in seconds, that will be taken for the interpolation.
|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.
|example1 = setprop("/test", 0); # (re-)set property
interpolate("/test",
50, 5, # interpolate to 50 in 5 seconds
10, 2, # interpolate to 10 in 2 seconds
0, 5); # interpolate to 0 in 5 seconds
|example2 = # Apply the left brake at 20% per second
var prop = "controls/gear/brake-left";
var dist = 1 - getprop(prop);
if (dist == 1) {
interpolate(prop, 1, dist / 0.2);
<nowiki>}</nowiki>
}}

===isa()===
{{Nasal doc
|syntax = isa(object, class);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|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.
|param1 = object
|param1text = Object to check.
|param2 = class
|param2text = Class/object to check that '''object''' inherits from or is an instance of.
|example1 = var coord = geo.Coord.new();
if(isa(coord, geo.Coord)){
print("Variable 'coord' is an instance of class 'geo.Coord'"); # this one will be printed
} else {
print("Variable 'coord' is not an instance of class 'geo.Coord'");
}
|example2 = var coord = geo.Coord.new();
if(isa(coord, props.Node)){
print("Variable 'coord' is an instance of class 'props.Node'");
} else {
print("Variable 'coord' is not an instance of class 'props.Node'"); # this one will be printed
}
|example3text = The example below demonstrates checking of inheritance.
|example3 = var Const = {
constant: 2,
getConst: func {
return me.constant;
}
};

var Add = {
new: func {
return { parents: [Add, Const] };
},

addToConst: func(a){
return a * me.getConst();
}
};

var m = Add.new();
print(m.addToConst(4));

if(isa(m, Add)) print("Variable 'm' is an instance of class 'Add'"); # will be printed
if(isa(m, Const)) print("Variable 'm' is an instance of class 'Const'"); # will also be printed
}}

===logprint()===
{{Nasal doc
|syntax = <nowiki>logprint(priority[, msg[, msg[, ...]]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=431|t=Source}}
|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}}.
|param1 = priority
|param1text = Number specifying the priority level of the outputted message:
:{{{!}} class="wikitable"
! Number !! Debug type
{{!-}}
{{!}} 1 {{!!}} Bulk
{{!-}}
{{!}} 2 {{!!}} Debug
{{!-}}
{{!}} 3 {{!!}} Info
{{!-}}
{{!}} 4 {{!!}} Warn
{{!-}}
{{!}} 5 {{!!}} Alert
{{!}}}
|param2 = msg
|param2text = The message. There is no limit to the arguments you give give. They will be concatenated together before logging.
|example1 = # logs the value of pi to three decimal places with log level 3
logprint(3, "pi = ", sprintf("%.3f", math.pi));
|example2 = logprint(5, "Alert! This is an important message!");
}}
{{note|
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:

LOG_BULK, LOG_WARN, LOG_DEBUG, LOG_INFO, LOG_ALERT, DEV_WARN, DEV_ALERT }}

===magvar() ===
{{Nasal doc
|syntax = magvar([pos]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1642|t=Source}}
|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.
{{{!}} class="wikitable"
! FlightGear versions !! Model !! Reference date
{{!-}}
{{!}} 3.6 and above {{!!}} {{wikipedia|World Magnetic Model}} (WMM) 2015 {{!!}} 1 January 2015
{{!-}}
{{!}} 0.9.11-pre1 to 3.4 {{!!}} WMM 2005 {{!!}} 1 January 2005
{{!-}}
{{!}} 0.7.3 to 0.9.10 {{!!}} WMM 2000 {{!!}} 1 January 2000
{{!}}}
|param1 = pos
|param1text = Optional position to calculate from. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost object.
:* A hash with ''lat'' and ''lon'' members
:* A <code>geo.Coord</code> object
:* A lat/lon pair, that is, a pair of numbers (latitude followed by longitude) separated by a comma: <code>magvar(lat,lon)</code>.
|example1 = print(magvar(0, 0)); # prints the magnetic variation at 0, 0
}}

===maketimer() ===
{{Nasal doc
|syntax = maketimer(interval[, self], function);
|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}}
|version = 2.12
|commit = {{flightgear commit|ab939f|t=commit}}
|text = Returns a timer object containing the following methods and members:
* '''start()''': Starts the timer.
* '''stop()''': Stops the timer.
* '''restart(interval)''': Restarts the timer with the given interval.
* '''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).
* '''isRunning''': Read-only bool telling whether the timer is currently running.
* '''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.
Unlike {{func link|settimer()}}, which it replaces, <code>maketimer()</code> provides more control over the timer. In addition, it can help reduce memory usage.
|param1 = interval
|param1text = Interval in seconds for the timer.
|param2 = self
|param2text = Optional parameter specifying what any <code>'''me'''</code> references in the function being called will refer to.
|param3 = function
|param3text = Function to be called at the given interval.
|example1 = var timer = maketimer(1, func(){
print("Hello, World!"); # print "Hello, World!" once every second (call timer.stop() to stop it)
});
timer.start();
|example2 = var timer = maketimer(1, math, func(){
print(me.math); # 'me' reference is the 'math' namespace
});
timer.singleShot = 1; # timer will only be run once
timer.start();
|example3 = var timer = maketimer(1, func(){
print("Hello, World!"); # print "Hello, World!" once every second (call timer.stop() to stop it)
});
timer.start();
print(timer.isRunning); # prints 1
|example4text = In the example below, "Hello, World!" will be printed after one second the first time, and after two seconds thereafter.
|example4 = var update = func(){
print("Hello, World!");
timer.restart(2); # restarts the timer with a two second interval
}

var timer = maketimer(1, update);
timer.singleShot = 1;
timer.start();
}}

===maketimestamp()===
{{Nasal doc
|syntax = maketimestamp()
|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}}
|version = 2019.2
|commit = {{flightgear commit|7db06300|t=commit}}
|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:
* '''stamp()''': Resets the timing operation. Call this first.
* '''elapsedMSec()''': returns number of milliseconds elapsed since stamp() called. Resolution may vary depending on platform but is usually at least millisecond accuracy.
* '''elapsedUSec()''': returns number of microseconds elapsed since stamp() called. Resolution may vary depending on platform but is usually at least millisecond accuracy.
|
|example1text = In the example below the number of milliseconds elapsed will be printed.
|example1 = var timestamp = maketimestamp();
timestamp.stamp();
print(timestamp.elapsedMSec(), "ms elapsed");
print(timestamp.elapsedMSec(), "ms elapsed");
}}

===md5()===
{{Nasal doc
|syntax = md5(string);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=758|t=Source}}
|version = 3.2
|commit = {{flightgear commit|cfbf9e|t=commit}}
|text = Returns a the {{wikipedia|MD5}} hash (as a string) of the inputted string.
|param1 = string
|param1text = String the generate the hash of. Mandatory.
|example1text = The below code should output <code>65a8e27d8879283831b664bd8b7f0ad4</code>.
|example1 = print(md5("Hello, World!"));
}}

===navinfo()===
{{Nasal doc
|syntax = navinfo(lat, lon, type, id);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1453|t=Source}}
|text = Returns vector <code>navaid</code> ghost objects matching the given '''type''' and '''id''' or <code>'''nil'''</code> on error.
|param1 = lat ''and'' lon
|param1text = If given, the returned navaids will be put into order of ascending distance from the location.
|param2 = type
|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."
|param3 = id
|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.
|example1 = navinfo("vor"); # returns all VORs
|example2 = navinfo("HAM"); # return all navaids whose names start with "HAM"
|example3 = navinfo("vor", "HAM"); # return all VORs whose names start with "HAM"
|example4 = navinfo(34,48,"vor","HAM"); # return all VORs whose names start with "HAM" and sorted by distance relative to 34°, 48°
}}

===parse_markdown()===
{{Nasal doc
|syntax = parse_markdown(markdown);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=745|t=Part 1}} {{!}} {{simgear file|simgear/misc/SimpleMarkdown.cxx|t=Part 2}}
|version = 3.2
|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:
* It strips whitespace from the beginning of the string.
* It supports [http://daringfireball.net/projects/markdown/syntax#p paragraphs and line breaks].
* It collapses whitespace.
* It converts unordered [http://daringfireball.net/projects/markdown/syntax#list lists] to use a bullet character (•). 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.
|param1 = markdown
|param1text = String containing Markdown to be parsed.
|example1text =
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>).
<syntaxhighlight lang="xml" highlight="41-50">
<?xml version="1.0" encoding="UTF-8"?>

<PropertyList>

<name>test</name>
<layout>vbox</layout>

<group>
<layout>hbox</layout>

<empty>
<stretch>true</stretch>
</empty>

<text>
<label>parse_markdown() test dialog</label>
</text>

<empty>
<stretch>true</stretch>
</empty>

<button>
<legend></legend>
<pref-width>16</pref-width>
<pref-height>16</pref-height>
<binding>
<command>dialog-close</command>
</binding>
</button>

</group>

<canvas>
<name>Canvas plot</name>
<stretch>true</stretch>
<pref-width>400</pref-width>
<pref-height>300</pref-height>
<nasal>
<load><![CDATA[
var text = 'Items:
* apples
* oranges
* pears

Some text.
Some more items:
* apples
* oranges
* pears';

var parsed = parse_markdown(text);

var root_canvas = canvas.get(cmdarg());
root_canvas.setColorBackground(255, 255, 255);
var root = root_canvas.createGroup();

var text_dis = root.createChild("text")
.setText(parsed)
.setTranslation(5, 5)
.setFont("LiberationFonts\LiberationSans-Regular.ttf")
.setFontSize(15)
.setColor(0, 0, 0)
.setDrawMode(canvas.Text.TEXT)
.setAlignment("left-top");
]]></load>
</nasal>
</canvas>

</PropertyList>
</syntaxhighlight>
|example1 = fgcommand("dialog-show", {"dialog-name": "test"});
|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.
|example2 = <nowiki>var markdown = 'Items:
* apples
* oranges
* pears

Some text.
Some more items:
* apples
* oranges
* pears';

var parsed = parse_markdown(markdown);

debug.dump(parsed);

var path = string.normpath(getprop("/sim/fg-home") ~ '/Export/parse_markdown()-test.html');

var file = io.open(path, "w");

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>";

io.write(file, html);
io.close(file);
print("Done, file ready for viewing (" ~ path ~ ")");</nowiki>
}}

===parsexml()===
{{Nasal doc
|syntax = <nowiki>parsexml(path[, start[, end[, data[, pro_ins]]]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=710|t=Source}}
|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.
|param1 = path
|param1text = Mandatory absolute path to the XML file to be parsed.
|param2 = start
|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.
|param3 = end
|param3text = Optional callback function that will be called for every ending tag. The function should take one argument: the tag name.
|param4 = data
|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.
|param5 = pro_ins
|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.
|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.
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>

<?xml-stylesheet type="text/xsl" href="style.xsl"?>

<foo>
<blah type="string"><![CDATA[ <sender>John Smith</sender> ]]></blah>
<blah2 type="string">Orange & lemons</blah2>
</foo>
</syntaxhighlight>
|example1 = var start = func(name, attr){
print("Starting tag: '", name, "'");
foreach(var a; keys(attr)){
print("\twith attribute ", a, '="', attr[a], '"');
}
}

var end = func(name){
print("Ending tag: '", name, "'");
}

var data = func(data){
print("Data = '", data, "'");
}

var pro_instr = func(target, data){
print("Processing instruction: target = '", target, "', data = '", data, "'");
}

parsexml(getprop("/sim/fg-home") ~ '/Export/demo.xml', start, end, data, pro_instr);
}}

===print()===
{{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.

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>}}

{{Nasal doc
|syntax = <nowiki>print(data[, data[, ...]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=415|t=Source}}
|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.
|param1 = data
|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.
|example1 = print("Just", " a ", "test"); # prints "Just a test"
|example2 = print("pi = ", math.pi); # prints "pi = 3.141592..."
}}

=== printf() ===
{{Nasal doc
|syntax = <nowiki>printf(format[, arg[, arg, [...]]]);</nowiki>
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|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>).
|example1 = printf("In hexadecimal, 100000 = %X", 186A0); # prints "In hexadecimal, 100000 = 186A0"
}}

===printlog()===
{{caution|This function is deprecated and doesn't work. Please use the new one {{func link|logprint()}}.}}
{{Nasal doc
|syntax = <nowiki>printlog(level, data[, data[, ...]]);</nowiki>
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|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.
|param1 = level
|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.
|param2 = data
|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.
|example1 = printlog("alert", "This is an alert"); # message will be printed
|example2 = printlog("info", "Just informing you about something"); # message will be printed only if log level is set to "info" or less
}}

===rand()===
{{Nasal doc
|syntax = rand();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=554|t=Source}}
|text = Returns a random floating point number between 0 (inclusive) and 1 (exclusive). It takes no arguments.
|example1 = print(rand()); # prints random number
}}

===registerFlightPlanDelegate()===
{{Nasal doc
|syntax = registerFlightPlanDelegate(init_func);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1879|t=Source}}
|text = Registers a flight plan delegate. See <tt>''{{fgdata file|Nasal/route_manager.nas|t=$FG_ROOT/Nasal/route_manager.nas}}''</tt> for examples.
|param1 = init_func
|param1text = Initialization function which will be called during FlightGear's startup.
}}
===removecommand()===
{{Nasal doc
|syntax = removecommand(cmd);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=668|t=Source}}
|text = Removes the given fgcommand. Returns <code>'''nil'''</code>.
{{caution|This will remove '''any''' [[fgcommands|fgcommand]], even those implemented in C++, so use with caution!}}
|param1 = cmd
|param1text = String specifying the name of the command to remove.
|example1 = addcommand("hello", func(){
print("Hello");
});
fgcommand("hello"); # "Hello" will be printed
removecommand("hello"); # removes it
}}

===removelistener()===
{{Nasal doc
|syntax = removelistener(id);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=1384|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=506|t=Part 2}}
|text = Removes and deactivates the given listener and returns the number of listeners left or <code>'''nil'''</code> on error.
{{note|It is good practice to remove listeners when they are not required anymore. This prevents the listeners reducing FlightGear's run performance.}}
|param1 = id
|param1text = ID of listener as returned by {{func link|setlistener()}}.
|example1 = var ls = setlistener("/sim/test", func(){
print("Property '/sim/test' has been changed");
});
setprop("/sim/test", "blah"); # trigger listener
var rem = removelistener(ls); # remove listener
print("There are ", rem, " listeners remaining");
}}

===resolvepath()===
{{Nasal doc
|syntax = resolvepath(path);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=604|t=Source}}
|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.
|param1 = path
|param1text = Relative path to be completed.
|example1 = print(resolvepath("Nasal/globals.nas")); # prints the equivalent of $FG_ROOT/Nasal/globals.nas
|example2 = print(resolvepath("blah")); # prints nothing; could not be resolved
|example3 = var file_path = resolvepath("Aircraft/SenecaII/some-file");
if (file_path != ""){
gui.popupTip("some-file found", 2);
} else {
gui.popupTip("some-file not found", 2);
<nowiki>}</nowiki>
}}

===setlistener()===
{{Nasal doc
|syntax = <nowiki>setlistener(node, code[, init[, type]]);</nowiki>
|private = _setlistener()
|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.''
|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()}}.
{{note|Listeners are known to be a source of resource leaks. To avoid this, please take measures such as:
* Using {{func link|removelistener()}} when they are not needed any more.
* Using a single initialization listener.
* Avoiding tying listeners to properties that are rapidly updated (e.g., many times per frame).
}}
|param1 = node
|param1text = Mandatory string or <code>props.Node</code> object pointing to a property in the [[Property Tree]].
|param2 = code
|param2text = Mandatory callback function to execute when the listener is triggered. The function can take up to four arguments in the following order:
* '''changed''': a <code>props.Node</code> object pointing to the changed node.
* '''listen''': a <code>props.Node</code> object pointing to the listened-to node. Note that this argument maybe different depending on the '''type'''.
* '''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.
* '''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.
|param3 = init
|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).
|param4 = type
|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.
|example1 = var prop = props.globals.initNode("/sim/test", "", "STRING"); # create property
var id = setlistener("/sim/test", func(n){ # create listener
print("Value: ", n.getValue());
});
setprop("/sim/test", "blah"); # trigger listener
removelistener(id); # remove listener
prop.remove(); # remove property
}}

===setprop()===
{{Nasal doc
|syntax = <nowiki>setprop(path[, path[, ...]], value);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=385|t=Source}}
|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.
{{note|If you want to remove a property, you will have to use one of the <code>props</code> helpers:
<syntaxhighlight lang="nasal">
props.globals.getNode("foo/bar").remove(); # take out the complete node
props.globals.getNode("foo").removeChild("bar"); # take out a certain child node
</syntaxhighlight>
}}
|param1 = path
|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.
|param2 = value
|param2text = Value to write to the given property. Must be either a string or a number.
|example1 = setprop("/sim/demo", "This is a demo");
|example2text = Note that the example below will only work in FlightGear 3.2 and above.
|example2 = for(var i = 0; i < 3; i += 1){
setprop("/sim/demo", i, "Demo #" ~ i));
}
|example3text = Same as above, but is supported by all versions of FlightGear.
|example3 = for(var i = 0; i < 3; i += 1){
setprop("/sim/demo[" ~ i ~ "]", "Demo #" ~ i));
<nowiki>}</nowiki>
}}
====See also====
{{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:
To get a Node rather than its value, use <code>props.globals.getNode()</code> - see [[Nasal_library/props]]. }}

===settimer() ===
{{Nasal doc
|syntax = settimer(function, delta[, realtime]);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=499|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=1286|t=Part 2}}
|text = Runs the given function a specified amount of seconds after the current time. Returns <code>'''nil'''</code>.
{{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.}}
|param1 = function
|param1text = Mandatory function that will be called. It may be necessary to enclose code in an anonymous function (see example).
|param2 = delta
|param2text = Mandatory amount of time in seconds after which the function will be called.
|param3 = realtime
|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.
|example1 = var myFunc = func(){
print("Hello");
}

settimer(myFunc, 2); # runs myFunc after 2 seconds
|example2 = var sqr = func(a){
return a * a;
}

settimer(func(){
print(sqr(2)); # will print 4 after 2 seconds
}, 2);
}}

===srand() ===
{{Nasal doc
|syntax = srand();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=559|t=Source}}
|text = Makes the pseudorandom number generator (see {{func link|rand()}}) generate a new {{wikipedia|random seed|noicon=1}} based on time. Returns 0.
}}
===systime()===
{{Nasal doc
|syntax = systime();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=770|t=Source}}
|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).
{{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]}}
|example1 = print("Unix time: ", systime()); # prints Unix time
|example2 = var myFunc = func(){
for(var i = 0; i <= 10; i += 1){
print("Interation #", i);
}
}
var t = systime(); # record time
myFunc(); # run function
var t2 = systime(); # record new time
print("myFunc() took ", t2 - t, " seconds"); # print result
}}

===thisfunc()===
{{Nasal doc
|syntax = thisfunc();
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = Returns the function from which this function is called. This allows a function to reliably and safely call itself from within a closure.
|example1 = var stringify_vec = func(input){
if (typeof(input) == "scalar"){
return sprintf("%s", input);
} elsif (typeof(input) == "vector") {
if (size(input) == 0) return "[]";
var this = thisfunc();
var buffer = "[";
for(var i = 0; i < size(input); i += 1){
buffer ~= this(input[i]);
if (i == size(input) - 1) {
buffer ~= "]";
} else {
buffer ~= ", ";
}
}
return buffer;
} else {
die("stringify_vec(): Error! Invalid input. Must be a vector or scalar");
}
}

var test_vec = ["a", "b", "c", [1, 2, 3], "d"];
debug.dump(stringify_vec(test_vec)); # prints "[a, b, c, [1, 2, 3], d]"
test_vec = [];
debug.dump(stringify_vec(test_vec)); # prints "[]"
test_vec = {};
debug.dump(stringify_vec(test_vec)); # will throw an error
}}

===tileIndex() ===
{{Nasal doc
|syntax = tileIndex();
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1720|t=Source}}
|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>.
|example1 = print(tileIndex()); # print index
}}

=== tilePath()===
{{Nasal doc
|syntax = tilePath();
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1712|t=Source}}
|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>.
|example1 = print(tilePath()); # print path
}}

=== values()===
{{Nasal doc
|syntax = values(hash);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = Returns a vector containing the values of the given hash.
|param1 = hash
|param1text = Mandatory hash to get the values of.
|example1 = var hash = {
"a": 1,
"b": 2,
"c": 3
};

foreach(var val; values(hash)){
print(val);
}
|example2text = The below example does exactly the same thing as the above example, but does not use <code>values()</code>:
|example2 = var hash = {
"a": 1,
"b": 2,
"c": 3
};

foreach(var key; keys(hash)){
print(hash[key]);
<nowiki>}</nowiki>
}}

==Extension functions new in FG 2020.1 ==
The following functions have been added to the nasal core library and will be released with FlightGear version 2020.1.
Before the release they are available in the development branch "next".

===isfunc()===
Returns 1 if type or argument is a function, otherwise 0.

===isghost()===
Returns 1 if type or argument is a ghost, otherwise 0.

=== ishash()===
Returns 1 if type or argument is a hash, otherwise 0.

===isint()===
{{Nasal doc
|syntax = isint(x);
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}
|text = Returns 1 if argument has a numeric value and x == floor(x), e.g. integer.
}}

===isnum()===
{{Nasal doc
|syntax = isnum(x);
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}
|text = Returns 1 if typeof(x) is "scalar" and x has a numeric value otherwise 0.
}}

===isscalar()===
{{Nasal doc
|syntax = isscalar(x);
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}
|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 "~".
|example1 = var a = "foo";
var b=42;
if (isscalar(a) and isscalar(b)) print(a~b);
if (isstr(a)) print("a is a string");
if (isint(b)) print("b is an integer");
# if (isscalar(a))... is equivalent to if (typeof(a) == "scalar")...
}}

===isstr()===
Returns 1 if type or argument is a string, otherwise 0.

===isvec()===
Returns 1 if type or argument is a vector, otherwise 0.

===vecindex()===
{{Nasal doc
|syntax = vecindex(vector, value);
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}
|text = Returns the index of value or nil, if value is not found in vector.
|example1=
var myvector = ["apple", "bananna", "coconut"];
# to check if a vector contains a certain value compare vecindex to nil
if (vecindex(myvector, "apple") != nil) {
print("found apple");
}
# WARNING: this will not work as desired because index is 0
if (vecindex(myvector, "apple")) {
print("found apple");
<nowiki>}</nowiki>

}}

==Variables==
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}}.

===D2R===
{{Nasal doc
|syntax = var radians = degrees * D2R;
|text = Converts an angle from degrees to radians when multiplied by the angle in degrees. Equal to <code>π / 180</code>.
}}
===FPS2KT===
{{Nasal doc
|syntax = var knots = feet_per_second * FPS2KT;
|text = Converts a velocity from feet per second to knots when multiplied by the velocity in feet per second. Approximately equal to 0.5925.
}}
===FT2M===
{{Nasal doc
|syntax = var metres = feet * FT2M;
|text = Converts a length from feet to metres when multiplied by the length in feet. Equal to 0.3048.
}}
===GAL2L ===
{{Nasal doc
|syntax = var litres = gallons * GAL2L;
|text = Converts a volume from US liquid gallons to litres when multiplied by the volume in gallons. Approximately equal to 3.7854.
}}
===IN2M===
{{Nasal doc
|syntax = var metres = inches * IN2M;
|text = Converts a length from inches to metres when multiplied by the length in inches. Equal to 0.0254.
}}
===KG2LB===
{{Nasal doc
|syntax = var pounds = kilograms * KG2LB;
|text = Converts a mass from kilograms to pounds when multiplied by the mass in kilograms. Approximately equal to 2.2046.
}}
===KT2FPS===
{{Nasal doc
|syntax = var feet_per_second = knots * KT2FPS;
|text = Converts a velocity from knots to feet per second when multiplied by the velocity in knots. Approximately equal to 1.6878.
}}
===KT2MPS===
{{Nasal doc
|syntax = var metres_per_second = knots * KT2MPS;
|text = Converts a velocity from knots to metres per second when multiplied by the velocity in knots. Approximately equal to 0.5144.
}}
===L2GAL===
{{Nasal doc
|syntax = var gallons = litres * L2GAL;
|text = Converts a volume from litres to US liquid gallons when multiplied by the volume in litres. Approximately equal to 0.2642.
}}
===LB2KG===
{{Nasal doc
|syntax = var kilograms = pounds * LB2KG;
|text = Converts a mass from pounds to kilograms when multiplied by the mass in pounds. Approximately equal to 0.4536.
}}
===M2FT ===
{{Nasal doc
|syntax = var feet = metres * M2FT;
|text = Converts a length from metres to feet when multiplied by the length in metres. Approximately equal to 3.2808.
}}
===M2IN===
{{Nasal doc
|syntax = var inches = metres * M2IN;
|text = Converts a length from metres to inches when multiplied by the length in metres. Approximately equal to 39.3701.
}}
===M2NM ===
{{Nasal doc
|syntax = var nautical_miles = metres * M2NM;
|text = Converts a length from metres to nautical miles when multiplied by the length in metres. Approximately equal to 0.00054.
}}
===MPS2KT ===
{{Nasal doc
|syntax = var knots = metres_per_second * MPS2KT;
|text = Converts a velocity from metres per second to knots when multiplied by the velocity in metres per second. Approximately equal to 1.9438.
}}
===NM2M ===
{{Nasal doc
|syntax = var metres = nautical_miles * NM2M;
|text = Converts a length from nautical miles to metres when multiplied by the length in nautical miles. Equal to 1,852.
}}
===R2D===
{{Nasal doc
|syntax = var degrees = radians * R2D;
|text = Converts an angle from radians to degrees when multiplied by the angle in radians. Equal to <code>180 / π</code>.
}}

{{Appendix}}

{{Nasal namespaces}}

Nasal library

2025-12-04T12:38:35Z

PlayeRom: /* str() */

{{Nasal Navigation|nocat=1}}
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:
* {{flightgear file|src/Scripting}}
* {{simgear file|simgear/nasal}}

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]].

{{tip|Copy & paste the examples into your [[Nasal Console]] and execute them to see what they do.|width=70%}}

== Core library functions ==
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:
* http://plausible.org/nasal/lib.html ([http://web.archive.org/web/20101010094553/http://plausible.org/nasal/lib.html archive])
* {{simgear file|simgear/nasal/lib.c}} ([http://sourceforge.net/p/flightgear/simgear/ci/next/log/?path=/simgear/nasal/lib.c history])

=== append() ===
{{Nasal doc
|syntax = append(vector, element[, element[, ...]]);
|source = {{simgear file|simgear/nasal/lib.c|l=45|t=Source}}
|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.
|param1 = vector
|param1text = The vector to which the arguments will be appended.
|param2 = element
|param2text = An element to be added to the vector.
|example1 =
var vector = [1, 2, 3]; # Initialize the vector
append(vector, 4); # Append the number 4 to the end of the vector
debug.dump(vector); # Print the contents of the vector
|example2 =
var vector = [1, 2, 3]; # Initialize the vector
append(vector, 4, 5, 6); # Append the numbers 4, 5, and 6 to the end of the vector
debug.dump(vector); # Print the contents of the vector
}}

=== bind() ===
{{Nasal doc
|syntax = bind(function, locals[, outer_scope]);
|source = {{simgear file|simgear/nasal/lib.c|l=638|t=Source}}
|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.
|param1 = function
|param1text = Function to evaluate.
|param2 = locals
|param2text = Hash containing values that will become the namespace (first closure) for the function.
|param3 = outer_scope
|param3text = Optional function which is bound to the next closure. This can be bound to yet another, making a linked list.
|example1 = # This is a namespace/hash with a single member, named "key," which is initialized to 12
var Namespace = {
key: 12
};

# This is different namespace/hash containing a function
# dividing a variable "key" (which is unavailable/nil in this namespace) by 2
var AnotherNamespace = {
ret: func {
key /= 2;
}
};

# To see that key is not available, try to call AnotherNamespace.ret() first
call(AnotherNamespace.ret, [], nil, nil, var errors = []);
if(size(errors)){
print("Key could not be divided/resolved!");
debug.printerror(errors);
}

# Associate the AnotherNamespace.ret() function with the first namespace
# so that "key" is now available
var function = bind(AnotherNamespace.ret, Namespace);

# Invoke the new function
function();

# Print out the value of Namespace.key
# It was changed to 12 from 6 by AnotherNamespace.ret()
print(Namespace.key);
}}

=== call() ===
{{Nasal doc
|syntax = call(func[, args[, me[, locals[, error]]]);
|source = {{simgear file|simgear/nasal/lib.c|l=376|t=Source}}
|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.
|param1 = func
|param1text = Function to execute.
|param2 = args
|param2text = Vector containing arguments to give to the called function.
|param3 = me
|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).
|param4 = locals
|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.
|param5 = error
|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}}.
|example1 =
# prints "Called from call()"
call(func {
print("Called from call()");
});
|example2 =
# prints "a = 1 : b = 2
call(func(a, b){
print("a = ", a, " : b = ", b);
},
[1, 2]
);
|example3 =
var Hash = {
new: func {
var m = { parents: [Hash] };

m.el1 = "string1";
m.el2 = "string2";

return m;
}
};

# prints "me.el1 = string1", then "me.el2 = string2" on the next line
call(func(a, b){
print("me.el", a, " = ", me["el" ~ a]);
print("me.el", b, " = ", me["el" ~ b]);
},
[1, 2],
Hash.new()
);
|example4 =
# prints the value of math.pi
call(func {
print(pi);
}, nil, nil,
math
);
|example5 =
call(func {
print(math.ip); # math.ip doesn't exist
}, nil, nil, nil,
var errs = []
);
debug.printerror(errs); # The error is caught and printed using debug.printerror()
}}

=== caller() ===
{{Nasal doc
|syntax = caller([level]);
|source = {{simgear file|simgear/nasal/lib.c|l=540|t=Source}}
|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 '''[0]''' a hash of local variables, '''[1]''' the function object, '''[2]''' the full source file name (incl. path) and '''[3]''' the line number.
|param1 = level
|param1text = Optional integer specifying the stack level to return a result from. Defaults to 1 (i.e. the caller of the currently executing function).
|example1 =
var myFunction = func(a, b) {
debug.dump(caller(0)[0]); # prints a hash of local variables, including arguments a and b
return 2 * 2;
};

print("2 x 2 = ", myFunction(2, 2));
|example2 =
var get_arg_value = func() {
print("Argument to myFunc = ", caller(1)[0]['a']); # print the value of myFunc's single argument, using caller()
};

var myFunc = func(a) {
get_arg_value();
};

myFunc(3);
|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: true, zindex: nil }</code>.
|example3 =
var MapStructure_selfTest = func() {
var temp = {};
temp.dlg = canvas.Window.new([600, 400], "dialog");
temp.canvas = temp.dlg.createCanvas().setColorBackground(1, 1, 1, 0.5);
temp.root = temp.canvas.createGroup();

var testMap = temp.root.createChild("map");
testMap.setController("Aircraft position");
testMap.setRange(25); # TODO: implement zooming/panning via mouse/wheel here, for lack of buttons :-/
testMap.setTranslation(
temp.canvas.get("view[0]") / 2,
temp.canvas.get("view[1]") / 2,
);

var r = func(name, vis = true, zindex = nil) {
return caller(0)[0];
}

# TODO: we'll need some z-indexing here, right now it's just random
# TODO: use foreach/keys to show all layers in this case by traversing SymbolLayer.registry directly ?
# maybe encode implicit z-indexing for each lcontroller ctor call ? - i.e. preferred above/below order ?
var types = [
r('TFC', false),
r('APT'),
r('DME'),
r('VOR'),
r('NDB'),
r('FIX', false),
r('RTE'),
r('WPT'),
r('FLT'),
r('WXR'),
r('APS'),
];

foreach (var type; types) {
testMap.addLayer(
factory: canvas.SymbolLayer,
type_arg: type.name,
visible: type.vis,
priority: type.zindex,
);
}
}; # MapStructure_selfTest
}}

=== chr() ===
{{Nasal doc
|syntax = chr(code);
|source = {{simgear file|simgear/nasal/lib.c|l=240|t=Source}}
|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.}}
{{{!}} class="wikitable"
! Code !! Name !! Equivalent to
{{!-}}
{{!}} 10 {{!!}} {{Wikipedia|Newline}} {{!!}} <code>\n</code>
{{!-}}
{{!}} 9 {{!!}} {{Wikipedia|Tab key#Tab characters|Horizontal tab}} {{!!}} <code>\t</code>
{{!-}}
{{!}} 13 {{!!}} {{Wikipedia|Carriage return}} {{!!}} <code>\r</code>
{{!}}}
|param1 = code
|param1text = Integer character code for the desired glyph.
|example1 = print("Code 65 = ", chr(65)); # prints "Code 65 = A"
|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.
|example2 =
for(var i = 0; i <= 255; i += 1){
print("Code ", i, " = >", chr(i), "<");
}
}}

=== closure() ===
{{Nasal doc
|syntax = closure(func[, level]);
|source = {{simgear file|simgear/nasal/lib.c|l=557|t=Source}}
|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'''.
|param1 = func
|param1text = Function to evaluate.
|param2 = level
|param2text = Optional integer specifying the scope level. Defaults to 0 (the namespace of '''func''').
|example1 =
var get_math_e = func {
return e; # return the value of math.e
}

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
debug.dump(closure(myFunction)); # print the namespace of get_math_e

print(myFunction());
}}

=== cmp() ===
{{Nasal doc
|syntax = cmp(a, b);
|source = {{simgear file|simgear/nasal/lib.c|l=169|t=Source}}
|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'''.
|param1 = a
|param1text = First string argument for comparison.
|param2 = b
|param2text = Second string argument for comparison.
|example1 = print(cmp("1", "two")); # prints -1
|example2 = print(cmp("string", "string")); # prints 0
|example3 = print(cmp("one", "2")); # prints 1
|example4 = print(cmp("string1", "string2")); # prints -1
}}

=== compile() ===
{{Nasal doc
|syntax = compile(code[, filename]);
|source = {{simgear file|simgear/nasal/lib.c|l=349|t=Source}}
|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'''.
|param1 = code
|param1text = String containing Nasal code to be compiled.
|param2 = filename
|param2text = Optional string used for error messages/logging. Defaults to <code><compile></code>
|example1 =
var myCode = 'print("hello");';
var helloFunc = compile(myCode, "myCode");
helloFunc();
|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>.
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<PropertyList>

<nasal><![CDATA[
print("You have FlightGear v", getprop("/sim/version/flightgear"));
]]></nasal>

</PropertyList>
</syntaxhighlight>
Now, start FlightGear and execute this code in the [[Nasal Console]].
|example2 =
# Build the path
var FGRoot = getprop("/sim/fg-root");
var filename = "/gui/dialogs/test.xml";
var path = FGRoot ~ filename;

var blob = io.read_properties(path);
var script = blob.getValues().nasal; # Get the nasal string

# Compile the script. We're passing the filename here for better runtime diagnostics
var code = call(func {
compile(script, filename);
}, nil, nil, var compilation_errors = []);

if(size(compilation_errors)){
die("Error compiling code in: " ~ filename);
}

# Invoke the compiled script, equivalent to code();
# We're using call() here to detect errors:
call(code, [], nil, nil, var runtime_errors = []);

if(size(runtime_errors)){
die("Error calling code compiled loaded from: " ~ filename);
}
|example3text = The <code>compile()</code> function also allows you to parse a JSON string into a hash. Simplest example:
|example3 =
var jsonFunc = compile('{"version":"1.2.0","author":{"name":"John"} }');
var json = jsonFunc(); # return hash
logprint(LOG_ALERT, json["version"]); # print "1.2.0"
logprint(LOG_ALERT, json["author"]["name"]); # print "John"
}}

=== contains() ===
{{Nasal doc
|syntax = contains(hash, key);
|source = {{simgear file|simgear/nasal/lib.c|l=249|t=Source}}
|text = Returns 1 (True) if the hash contains the specified key, or 0 (False) if not.
|param1 = hash
|param1text = The hash to search in.
|param2 = key
|param2text = The scalar to be searched for, contained as a key in the hash.
|example1 =
# Initialize a hash
var hash = {
element: "value"
};
print(contains(hash, "element") ? "Yes" : "No"); # This will print "Yes"
print(contains(hash, "element2") ? "Yes" : "No"); # This will print "No"
}}

===contains()===
{{Requires commit|desc=Vector support|details=see {{Merge-request|project=fgdata|id=305}}|commit=ee39abbd3b70c9b6d5e3a1c4ccedddaac1a92b11|repo=Simgear}}
{{Nasal doc
|syntax = contains(vector, item);
|source = {{simgear file|simgear/nasal/lib.c|l=249|t=Source}}
|text = Returns 1 (True) if the vector contains the specified item, or 0 (False) if not.
|param1 = vector
|param1text = The vector to search in.
|param2 = item
|param2text = The object to be searched for in the vector.
|example1 =
# Initialize a vector
var vec = ["element", "foo"];
print(contains(vec, "element") ? "Yes" : "No"); # This will print "Yes"
print(contains(vec, "element2") ? "Yes" : "No"); # This will print "No"
}}

===delete() ===
{{Nasal doc
|syntax = delete(hash, key);
|source = {{simgear file|simgear/nasal/lib.c|l=118|t=Source}}
|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.
|param1 = hash
|param1text = The hash from which to delete the key.
|param2 = key
|param2text = The scalar to be deleted, contained as a key in the hash.
|example1 =
# Initialize the hash
var hash = {
element1: "value1",
element2: "value2"
};
delete(hash, "element1"); # Delete element1
debug.dump(hash); # prints the hash, which is now minus element1
}}

===die()===
{{Nasal doc
|syntax = die(error);
|source = {{simgear file|simgear/nasal/lib.c|l=417|t=Source}}
|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()}}.
|param1 = error
|param1text = String describing the error.
:{{inote|This parameter is technically optional, but it is highly recommended to use it.}}
|example1 =
print("Will print");
die("Don't go any further!");
print("Won't print"); # Will not be printed because die() stops the process
}}

=== find()===
{{Nasal doc
|syntax = find(needle, haystack);
|source = {{simgear file|simgear/nasal/lib.c|l=586|t=Source}}
|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.
|param1 = needle
|param1text = String to search for.
|param2 = haystack
|param2text = String to search in.
|example1 = print(find("c", "abcdef")); # prints 2
|example2 = print(find("x", "abcdef")); # prints -1
|example3 = print(find("cd", "abcdef")); # prints 2
}}

===ghosttype()===
{{Nasal doc
|syntax = ghosttype(ghost);
|source = {{simgear file|simgear/nasal/lib.c|l=336|t=Source}}
|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.
|param1 = ghost
|param1text = Ghost to return a description for.
|example1 = print(ghosttype(airportinfo())); # prints "airport"
}}

===id()===
{{Nasal doc
|syntax = id(object);
|source = {{simgear file|simgear/nasal/lib.c|l=706|t=Source}}
|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.
|param1 = object
|param1text = Can be either of a string, a vector, a hash, a code, a function, or a ghost.
|example1 = print(id("A")); # prints "str:000000001624A590"
}}

===int() ===
{{Nasal doc
|syntax = int(number);
|source = {{simgear file|simgear/nasal/lib.c|l=125|t=Source}}
|text = Returns the integer part of the numeric value of the single argument, or <code>'''nil'''</code> if none exists.
|param1 = number
|param1text = Number or string with just a number in it to return an integer from.
|example1 = print(int(23)); # prints "23"
|example2 = print(int(23.123)); # prints "23"
|example3 = debug.dump(int("string")); # prints "nil"
}}

===keys()===
{{Nasal doc
|syntax = keys(hash);
|source = {{simgear file|simgear/nasal/lib.c|l=36|t=Source}}
|text = Returns a vector containing the list of keys found in the single hash argument.
|param1 = hash
|param1text = The hash to return the keys from.
|example1 =
# Initialize a hash
var hash = {
element1: "value",
element2: "value"
};
debug.dump(keys(hash)); # print the vector
}}

===left()===
{{Nasal doc
|syntax = left(string, length);
|source = {{simgear file|simgear/nasal/lib.c|l=214|t=Source}}
|version = 2.12
|commit = {{simgear commit|bd7163|t=commit}}
|text = Returns a substring of '''string''', starting from the left.
|param1 = string
|param1text = String to return part of.
|param2 = length
|param2text = Integer specifying the length of the substring to return.
|example1 = print(left("string", 2)); # prints "st"
}}

=== num()===
{{Nasal doc
|syntax = num(number);
|source = {{simgear file|simgear/nasal/lib.c|l=149|t=Source}}
|text = Returns the numerical value of the single string argument, or <code>'''nil'''</code> if none exists.
|param1 = number
|param1text = String with just a number in it to return a number from.
|example1 = print(num("23")); # prints "23"
|example2 = print(num("23.123")); # prints "23.123"
|example3 = debug.dump(num("string")); # prints "nil"
}}

===pop()===
{{Nasal doc
|syntax = pop(vector);
|source = {{simgear file|simgear/nasal/lib.c|l=85|t=Source}}
|text = Removes and returns the last element of the single vector argument, or <code>'''nil'''</code> if the vector is empty.
|param1 = vector
|param1text = Vector to remove an element from.
|example1 =
var vector = [1, 2, 3];
pop(vector);
debug.dump(vector); # prints "[1, 2]"
|example2 =
var vector = [1, 2, 3];
debug.dump(pop(vector)); # prints "3"
|example3 =
var vector = [];
debug.dump(pop(vector)); # prints "nil"
}}

=== range() ===
{{Nasal doc
|syntax = range([start, ]stop[, step]);
|source = {{simgear file|simgear/nasal/lib.c|l=756|t=Source}}
|text = Creates a vector of numbers starting from <code>start</code> (default 0) up to but not including <code>stop</code>, incremented by <code>step</code> (default 1). Note: To specify <code>step</code>, you must also provide <code>start</code>; otherwise the second argument is interpreted as <code>stop</code>.
|param1 = start
|param1text = Optional. The starting number of the sequence. Defaults to 0 if omitted. Required if you want to specify <code>step</code>.
|param2 = stop
|param2text = Required. The number at which to stop the sequence (not included).
|param3 = step
|param3text = Optional. The increment between each number in the sequence. Defaults to 1. Only valid if <code>start</code> is also specified.
|example1 =
var vec = range(5); # Creates a vector [0, 1, 2, 3, 4]
var vec = range(2, 5); # Creates a vector [2, 3, 4]
var vec = range(0, 10, 2); # Creates a vector [0, 2, 4, 6, 8]
var vec = range(0, 0); # Creates an empty vector []
var vec = range(0, 1); # Creates a vector [0]
}}

=== remove() ===
{{Nasal doc
|syntax = remove(vector, value);
|source = {{simgear file|simgear/nasal/lib.c|l=53|t=Source}}
|text = Removes all elements equal to the given value from a vector and returns the modified vector.
|param1 = vector
|param1text = The vector from which elements are to be removed.
|param2 = value
|param2text = A value to remove from the vector.
|example1 =
var vector = [1, 2, 3]; # Initialize the vector.
remove(vector, 2); # Remove the value 2 from the vector.
debug.dump(vector); # Print the contents of the vector: "[1, 3]".
|example2 =
var vector = ["text", "text", "text"]; # Initialize the vector.
remove(vector, "text"); # Remove the value "text" from the vector.
debug.dump(vector); # Print the contents of the vector: "[]".
}}

=== removeat() ===
{{Nasal doc
|syntax = removeat(vector, index);
|source = {{simgear file|simgear/nasal/lib.c|l=72|t=Source}}
|text = Removes the element at the specified index from the vector and returns it.
|param1 = vector
|param1text = The vector from which the element will be removed.
|param2 = index
|param2text = Index of the item to be deleted.
|example1 =
var vector = [1, 2, 3]; # Initialize the vector.
removeat(vector, 0); # Remove the index 0 from the vector.
debug.dump(vector); # Print the contents of the vector: "[2, 3]".
}}

===right()===
{{Nasal doc
|syntax = right(string, length);
|source = {{simgear file|simgear/nasal/lib.c|l=226|t=Source}}
|version = 2.12
|commit = {{simgear commit|bd7163|t=commit}}
|text = Returns a substring of '''string''', starting from the right.
|param1 = string
|param1text = String to return part of.
|param2 = length
|param2text = Integer specifying the length of the substring to return.
|example1 = print(right("string", 2)); # prints "ng"
}}

=== setsize()===
{{Nasal doc
|syntax = setsize(vector, size);
|source = {{simgear file|simgear/nasal/lib.c|l=91|t=Source}}
|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.
|param1 = vector
|param1text = The vector to be operated on.
|param2 = size
|param2text = The desired size of the vector in number of entries.
|example1 =
var vector = [1, 2, 3]; # Initialize a vector
setsize(vector, 4);
debug.dump(vector); # print the vector "[1, 2, 3, nil]"
|example2 =
var vector = [1, 2, 3]; # Initialize a vector
setsize(vector, 2);
debug.dump(vector); # print the vector "[1, 2]"
}}

===size()===
{{Nasal doc
|syntax = size(object);
|source = {{simgear file|simgear/nasal/lib.c|l=26|t=Source}}
|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>.
|param1 = object
|param1text = Object to find the size of. Must be a string, a vector or a hash.
|example1 =
var string = "string";
print(size(string)); # prints "6"
|example2 =
var vector = [1, 2, 3];
print(size(vector)); # prints "3"
|example3 =
var hash = {
element1: "value1",
element2: "value2",
element3: "value3"
};
print(size(hash)); # prints "3"
}}

=== sort()===
{{Nasal doc
|syntax = sort(vector, function);
|source = {{simgear file|simgear/nasal/lib.c|l=678|t=Source}}
|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.
|param1 = vector
|param1text = Input vector to sort.
|param2 = function
|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.
{{{!}} class="wikitable"
! Return value !! Meaning
{{!-}}
{{!}} less than 0 {{!!}} first argument should go before second argument
{{!-}}
{{!}} 0 {{!!}} first argument equals second argument
{{!-}}
{{!}} greater than 0 {{!!}} first argument should go after second argument
{{!}}}

|example1text = This example sorts elements from smallest to greatest.
|example1 =
var sort_rules = func(a, b) {
if (a < b) {
return -1; # A should before b in the returned vector
} elsif (a == b) {
return 0; # A is equivalent to b
} else {
return 1; # A should after b in the returned vector
}
}
debug.dump(sort([3, 2, 5, 6, 4, 1], sort_rules)); # prints "[1, 2, 3, 4, 5, 6]"
|example2text = This example sorts elements from greatest to smallest.
|example2 =
# Outputs the elements in reverse order (greatest to smallest)
var sort_rules = func(a, b) {
if (a < b) {
return 1; # -1 in the above example
} elsif (a == b) {
return 0;
} else {
return -1; # 1 in the above example
}
}
debug.dump(sort([3, 2, 5, 6, 4, 1], sort_rules)); # prints "[6, 5, 4, 3, 2, 1]"
|example3text = This example sorts a vector of strings (runways for example) from smallest to greatest.
|example3 =
var runways = ["09R", "27R", "26L", "09L", "15"];
var rwy = sort(runways, func(a, b) cmp(a, b));
debug.dump(rwy); # prints ['09L', '09R', '15', '26L', '27R']
}}

=== split()===
{{Nasal doc
|syntax = split(delimiter, string);
|source = {{simgear file|simgear/nasal/lib.c|l=596|t=Source}}
|text = Splits the input string into a vector of substrings bounded by occurrences of the delimiter substring. See [[Nasal_library/string#string.join(sep,list)|string.join()]].
|param1 = delimiter
|param1text = String that will split the substrings in the returned vector.
|param2 = string
|param2text = String to split up.
|example1 = debug.dump(split("cd", "abcdef")); # prints "['ab', 'ef']"
|example2 = debug.dump(split(".", "3.2.0")); # prints "[3, 2, 0]"
|example3 = debug.dump(split("/", "path/to/file")); # prints "['path', 'to', 'file']"
}}

===sprintf()===
{{Nasal doc
|syntax = <nowiki>sprintf(format[, arg[, arg, [...]]]);</nowiki>
|source = {{simgear file|simgear/nasal/lib.c|l=491|t=Source}}
|text = Creates and returns a string formatted using ANSI C {{func link|vsnprintf()|link=http://en.cppreference.com/w/c/io/vfprintf}} <ref>
{{Cite web
|url = http://sourceforge.net/p/flightgear/simgear/ci/next/tree/simgear/nasal/lib.c#l308
|title = fgdata/simgear/simgear/nasal/lib.c, line 308
|accessdate = October 2015
}}
</ref>. Below is a table of supported format specifiers.
{{{!}} class="wikitable" width="75%"
{{!}}+ %[flags][width][.precision]specifier
! colspan="2" {{!}} Flags
{{!-}}
! Flag !! Output
{{!-}}
{{!}} <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.
{{!-}}
{{!}} ''space'' {{!!}} Prefixes non-signed numbers with a space.
{{!-}}
{{!}} <code>-</code> {{!!}} Left-align the output of this placeholder (the default is to right-align the output) when the width option is specified.
{{!-}}
{{!}} <code>0</code> {{!!}} Use 0 instead of spaces to pad a field when the width option is specified.
{{!-}}
{{!}} <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.
{{!-}}
! colspan="2" {{!}} Width
{{!-}}
{{!}} 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.
{{!-}}
! colspan="2" {{!}} Precision
{{!-}}
{{!}} colspan="2" {{!}} Integer preceded by a dot specifying the number of decimal places to be written.
{{!-}}
! colspan="2" {{!}} Specifiers
{{!-}}
! Specifier !! Output
{{!-}}
{{!}} <code>d</code>, <code>i</code> {{!!}} Signed decimal number.
{{!-}}
{{!}} <code>s</code> {{!!}} A string
{{!-}}
{{!}} <code>%</code> {{!!}} Percent (%) character.
{{!-}}
{{!}} <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.
{{!-}}
{{!}} <code>o</code> {{!!}} Unsigned integer as an octal number.
{{!-}}
{{!}} <code>u</code> {{!!}} Unsigned decimal integer.
{{!-}}
{{!}} <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.
{{!-}}
{{!}} <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.
{{!-}}
{{!}} <code>f</code> {{!!}} Floating-point number, in fixed decimal notation, by default with 6 decimal places.
{{!-}}
{{!}} <code>F</code> {{!!}} Appears to be available<ref>
{{Cite web
|url = http://sourceforge.net/p/flightgear/simgear/ci/next/tree/simgear/nasal/lib.c#l389
|title = fgdata/simgear/simgear/nasal/lib.c, line 389
|accessdate = October 2015
}}
</ref>, but doesn't work.
{{!-}}
{{!}} <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.
{{!}}}

|param1 = format
|param1text = String specifying the format. Can be used with or without a format specifiers. See below for examples.
|param2 = arg
|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.

|example1 = print(sprintf("%i", 54)); # prints "54"
|example2 = print(sprintf("Pi = %+.10f", math.pi)); # prints "Pi = +3.1415926536"
|example3 =
print(sprintf("%6d", 23)); # prints " 23"
print(sprintf("%06d", 23)); # prints "000023"
|example4 =
var FGVer = getprop("/sim/version/flightgear");
print(sprintf("You have FlightGear v%s", FGVer)); # prints "You have FlightGear v<your version>"
|example5 =
print(sprintf("Hexadecimal 100000 = %X", 100000)); # prints "Hexadecimal 100000 = 186A0"
print(sprintf("Hexadecimal 100000 = %x", 100000)); # prints "Hexadecimal 100000 = 186a0"
|example6 = print(sprintf("Code 65 is %c", 65)); # prints "Code 65 is A"
|example7 =
print(sprintf("%e", 54)); # prints "5.400000e+001"
print(sprintf("%E", 54)); # prints "5.400000E+001"
|example8 = print(sprintf("%o", 54)); # prints "66"
|example9 = print(sprintf("50%% of 100 is %i", 100 / 2)); # prints "50% of 100 is 50"
|example10 =
print(sprintf("%.2f", 1.4)); # prints "1.40"
print(sprintf("%.1f", 1.4)); # prints "1.4"
print(sprintf("% 4.1f", 1.4)); # prints " 1.4"
print(sprintf("%04.1f", 1.4)); # prints "01.4"
print(sprintf("% 6.1f", 1.4)); # prints " 1.4"
print(sprintf("%06.1f", 1.4)); # prints "0001.4"
}}

===str()===
{{Nasal doc
|syntax = str(value);
|source = {{simgear file|simgear/nasal/lib.c|l=186|t=Source}}
|text = Convert given value (scalar) to string. If <code>value</code> is a number, it will be converted to a string. If <code>value</code> is a string, the same string will be returned. If <code>value</code> is not a scalar (hash, vector, nil), <code>nil</code> will be returned.
|param1 = value
|param1text = The value to convert to string.
|example1 =
var result = str(true); # result is a string "1"
var result = str(false); # result is a string "0"
var result = str(12); # result is a string "12"
var result = str(12.5); # result is a string "12.5"
var result = str("12.5"); # result is a string "12.5"
var result = str([1, 2]); # result is a nil
var result = str({ x: 0 }); # result is a nil
var result = str(nil); # result is a nil
}}

===streq()===
{{Nasal doc
|syntax = streq(a, b);
|source = {{simgear file|simgear/nasal/lib.c|l=164|t=Source}}
|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.}}
|param1 = a
|param1text = First argument for testing equality.
|param2 = b
|param2text = Second argument for testing equality.
|example1 = print(streq("0", "0")); # prints "1" (True)
|example2 =
print(0 == 0.0); # prints "1" (True)
print(streq("0", "0.0")); # prints "0" (False)
}}

===substr()===
{{Nasal doc
|syntax = substr(string, start [, length]);
|source = {{simgear file|simgear/nasal/lib.c|l=194|t=Source}}
|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).
|param1 = string
|param1text = String to return a substring from.
|param2 = start
|param2text = Integer specifying the start of a substring. Negative values specify a position from the end of the string.
|param3 = length
|param3text = Optional argument specifying the length of the substring. Defaults to the end of the string.
|example1 = print(substr("abcde", 1, 3)); # prints "bcd"
|example2 = print(substr("abcde", 1)); # prints "bcde"
|example3 = print(substr("abcde", 2, 1)); # prints "c"
|example4 = print(substr("abcde", -2)); # prints "de"
|example5 = print(substr("abcde", -3, 2)); # prints "cd"
}}

===subvec()===
{{Nasal doc
|syntax = subvec(vector, start[, length]);
|source = {{simgear file|simgear/nasal/lib.c|l=98|t=Source}}
|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).
|param1 = vector
|param1text = The vector to take the sub-vector from.
|param2 = start
|param2text = The starting point of the sub-vector within the given vector.
|param3 = length
|param3text = Optional argument specifying the length of the sub-vector, from the starting point.
'''Notes:'''
* Omitting the ''vector'' and ''start'' arguments is not an error (possibly it should be) but the return value is ''nil''.
* A negative ''start'' argument ''is'' an error. This seems wrong. Perhaps the language designer could comment.
* A value of ''start'' greater than ''size(vector)'' causes an error. A value equal to ''size(vector)'' returns an empty vector.
* 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.
|example1 =
var vector = [1, 2, 3];
debug.dump(subvec(vector, 0)); # prints "[1, 2, 3]"
|example2 =
var vector = [1, 2, 3];
debug.dump(subvec(vector, 1)); # prints "[2, 3]"
|example3 =
var vector = [1, 2, 3];
debug.dump(subvec(vector, 1, 1)); # prints "[2]"
}}

=== typeof()===
{{Nasal doc
|syntax = typeof(object);
|source = {{simgear file|simgear/nasal/lib.c|l=287|t=Source}}
|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.
|param1 = object
|param1text = Object to return the type of.
|example1 =
var object = nil;
print(typeof(object)); # prints "nil"
|example2 =
var object = "Hello world!";
print(typeof(object)); # prints "scalar"
|example3 =
var object = math.pi;
print(typeof(object)); # prints "scalar"
|example4 =
var object = [1, 2, 3];
print(typeof(object)); # prints "vector"
|example5 =
var object = {};
print(typeof(object)); # prints "hash"
|example6 =
var object = func {};
print(typeof(object)); # prints "func"
|example7 =
var object = airportinfo();
print(typeof(object)); # prints "ghost"
}}



==Extension functions==
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:
*{{flightgear file|src/Scripting/NasalPositioned.cxx}}
*{{flightgear file|src/Scripting/NasalSys.cxx}}
*{{fgdata file|Nasal/globals.nas}}

===abort()===
{{Nasal doc
|syntax = abort();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=565|t=Source}}
|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).
|example1text = This example will immediately stop FlightGear with an error, such as "FlightGear has stopped working."
|example1 = abort();
|example2text = For exiting FlightGear in a better way, please use the following code:
|example2 = fgcommand("exit");
}}

=== abs() ===
{{Nasal doc
|syntax = abs(number);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = This simple function returns the {{wikipedia|absolute value|noicon=1}} of the provided number.
|param1 = number
|param1text = This argument is required and should be a number.
|example1 = print(abs(1)); # prints "1"
|example2 = print(abs(-1)); # prints "1"
}}

===aircraftToCart() ===
This new function in FG 2017.2.1 takes coordinates in aircraft structural coordinate system, and translate them into geocentric coordinates.
Example for (5,6,7):
<syntaxhighlight lang="nasal">
var pos = aircraftToCart({x: -5, y: 6, z: -7});
var coord = geo.Coord.new();
coord.set_xyz(pos.x, pos.y, pos.z);
</syntaxhighlight>
Notice: x and z is inverted sign on purpose.
if you want lat. lon, alt from that, just call: (degrees and meters)

<syntaxhighlight lang="nasal">
coord.lat()
coord.lon()
coord.alt()
</syntaxhighlight>

===addcommand() ===
{{Nasal doc
|syntax = addcommand(name, code);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=659|t=Source}}
|version = 2.12
|commit = {{flightgear commit|7b663c|t=commit}}
|text = {{see also|Howto:Add new fgcommands to FlightGear}}

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.
|param1 = name
|param1text = This will become the name of the new fgcommand. Must be a string.
|param2 = code
|param2text = The code that will be executed when the fgcommand is run. Must be a function.
|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.
|example1 = addcommand("myFGCmd", func(node) {
print("fgcommand 'myFGCmd' has been run.");
props.dump( node );
});
fgcommand("myFGCmd", props.Node.new({foo:1, bar:2}) );
|example2text = This example demonstrates how parameters are defined in a new fgcommand.
|example2 = addcommand("myFGCmd", func(node){
print(node.getNode("number").getValue()); # prints the value of "number," which is 12
});
fgcommand("myFGCmd", props.Node.new({"number": 12}));
}}

===airportinfo()===
{{Nasal doc
|syntax = airportinfo();
airportinfo(type);
airportinfo(id);
airportinfo(lat, lon[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1024|t=Source}}
|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:
* '''parents''': A vector containing a hash of various functions to access information about the runway. These functions are:
** '''findBestRunwayForPos()''' return runway as ghost by given geo position, e.g. <code>var rwy = airportinfo().findBestRunwayForPos(geo.aircraft_position());</code>.
** '''runway()''' return runway as ghost by runway ID, e.g. <code>var rwy = airportinfo().runway("18R");</code>.
** '''runwaysWithoutReciprocals()''' return vector of runways as ghost.
** '''helipad()''' return helipad as ghost by helipad ID, e.g. <code>var heli = airportinfo().helipad("H19");</code>.
** '''tower()''' return hash with <code>lat</code>, <code>lon</code>, <code>elevation</code> fields.
** '''comms()''' return vector of hashes, each hash with <code>frequency</code> and <code>ident</code> fields.
** '''sids()''' return vector of strings with SID IDs.
** '''stars()''' return vector of strings with STAR IDs.
** '''getApproachList()''' return vector of string with approaches.
** '''parking()''' return vector of hashes, each hash with <code>lat</code>, <code>lon</code>, <code>elevation</code>, <code>name</code> fields.
** '''getSid()''' return SID as ghost, e.g. <code>var sid = airportinfo().getSid("SA1A");</code>.
** '''getStar()''' return STAR as ghost, e.g. <code>var star = airportinfo().getStar("KEILA1");</code>.
** '''getIAP()''' return IAP as ghost, e.g. <code>var iap = airportinfo().getIAP("ILS02");</code>.
** '''getApproach()''' return approach as ghost, e.g. <code>var approach = airportinfo().getApproach("ILS02");</code>.
** '''tostring()''' just return string "an airport ICAO".
** See also {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1902}}.
* '''lon''': Longitude of the location.
* '''lat''': Latitude of the location.
* '''has_metar''': True or false depending whether the airport has a [[METAR]] code defined for it.
* '''elevation''': Elevation of the location in metres.
* '''id''': ICAO code of the airport (or ID of the seaplane base/heliport).
* '''name''': Name of the airport/heliport/seaplane base.
* '''runways'''
** '''<runway name>'''
*** '''id''': Name of runway.
*** '''lat''': Latitude of the runway.
*** '''lon''': Longitude of the runway.
*** '''heading''': True heading of the runway.
*** '''length''': Length of the runway in metres.
*** '''width''': Width of the runway in metres.
*** '''surface''': Runway surface type.
*** '''threshold''': Length of the runway's {{wikipedia|displaced threshold}} in metres. Will return 0 if there is none.
*** '''stopway''': Length of the runway's stopway (the area before the threshold) in metres. Will return 0 if there is none.
*** '''reciprocal''': <code>runway</code> ghost of the reciprocal runway.
*** '''ils_frequency_mhz''': ILS frequency in megahertz.
*** '''ils''': <code>navaid</code> ghost of the ILS transmitter.
* '''helipads'''
** '''<helipad name>'''
*** '''id''': Name of helipad.
*** '''lat''': Latitude of the helipad.
*** '''lon''': Longitude of the helipad.
*** '''heading''': True heading of the helipad.
*** '''length''': Length of the helipad in metres.
*** '''width''': Width of the helipad in metres.
*** '''surface''': Helipad surface type.
* '''taxiways'''
** '''<taxiway name>'''
*** '''id''': Name of taxiway.
*** '''lat''': Latitude of the taxiway.
*** '''lon''': Longitude of the taxiway.
*** '''heading''': Heading of the taxiway.
*** '''length''': Length of the taxiway in metres.
*** '''width''': Width of the taxiway in metres.
*** '''surface''': Taxiway surface type.

Information is extracted in the same way as accessing members of a Nasal hash. For example:
<syntaxhighlight lang="nasal">
# prints to lengths of the runways of the nearest airport in feet and metres
var info = airportinfo();
print("-- Lengths of the runways at ", info.name, " (", info.id, ") --");
foreach(var rwy; keys(info.runways)){
print(rwy, ": ", math.round(info.runways[rwy].length * M2FT), " ft (", info.runways[rwy].length, " m)");
}
</syntaxhighlight>

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.
|param1 = id
|param1text = The {{wikipedia|International Civil Aviation Organization airport code|ICAO code|noicon=1}} of an airport to retrieve information about.
|param2 = type
|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).
: {{inote|Running this function without any parameters is equivalent to this:
: <syntaxhighlight lang="nasal">
airportinfo("airport");
</syntaxhighlight>
}}
|param3 = lat ''and'' lon
|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.
|example1 = var info = airportinfo();
print("Nearest airport: ", info.name, " (", info.id, ")"); # prints the name and ICAO code of the nearest airport
|example2 = var info = airportinfo("heliport");
print("Elevation of the nearest heliport: ", math.round(info.elevation * M2FT), " ft"); # prints the elevation and name of the nearest heliport
|example3 = var info = airportinfo("KSQL");
print("-- Runways of ", info.name, " (", info.id, "): --");
foreach(var rwy; keys(info.runways)) {
print(rwy); # prints the runways of KSQL
}
|example4 = var info = airportinfo(37.81909385, -122.4722484);
print("Coordinates of the nearest airport: ", info.lat, ", ", info.lon); # print the name and ICAO of the nearest airport to the Golden Gate Bridge
|example5 = var info = airportinfo(37.81909385, -122.4722484, "seaport");
print("Nearest seaplane base: ", info.name, " (", info.id, ")"); # print the name and ID of the nearest seaplane base to the Golden Gate Bridge
|example6text = This example prints the all information from an <code>airportinfo()</code> call.
|example6 = var info = airportinfo("KSFO");
print(info.name);
print(info.id);
print(info.lat);
print(info.lon);
print(info.has_metar);
print(info.elevation);
foreach(var rwy; keys(info.runways)){
print("-- ", rwy, " --");
print(info.runways[rwy].lat);
print(info.runways[rwy].lon);
print(info.runways[rwy].length);
print(info.runways[rwy].width);
print(info.runways[rwy].heading);
print(info.runways[rwy].stopway);
print(info.runways[rwy].threshold);
<nowiki>}</nowiki>
}}

===airwaysRoute() ===
{{Nasal doc
|syntax = airwaysRoute(start, end[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1933|t=Source}}
|text = {{see also|Nasal Flightplan}}
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.
|param1 = start
|param1text = Start waypoint, in the form of a waypoint ghost, such as that provided by {{func link|flightplan()}}.
|param2 = end
|param2text = Same as above.
|param3 = type
|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."
|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.
|example1 = var fp = flightplan();
var start = fp.getWP(0);
var end = fp.getWP(fp.getPlanSize() - 1);
var rt = airwaysRoute(start, end);
foreach(var wp; rt){
print(wp.wp_name); # print the waypoints in the computed route
}
|example2text = Exactly the same as above, but computes a low level path.
|example2 = var fp = flightplan();
var start = fp.getWP(0);
var end = fp.getWP(fp.getPlanSize() - 1);
var rt = airwaysRoute(start, end, "lowlevel");
foreach(var wp; rt){
print(wp.wp_name); # print the waypoints in the computed route
<nowiki>}</nowiki>
}}

===airway()===

{{Nasal doc
|syntax = airway(ident [, pos]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2644|t=Source}}
|text = {{see also|Nasal Flightplan}}
This function returns a ghost containing an airway of a specified id.
|param1 = ident
|param1text = a Positioned ghost (leg, navaid, airport) and so on, passed to the search function.
|param2 = pos
}}

===assert()===
{{Nasal doc
|syntax = assert(condition[, message]);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|version = 3.2
|commit = {{fgdata commit|8b16a7|t=commit}}
|text = Returns either true if the condition evaluates as true, or aborts with a {{func link|die()}} call, which can be customised.
|param1 = condition
|param1text = Condition to evaluate.
|param2 = message
|param2text = Optional message that will be used in any {{func link|die()}} call. Defaults to "assertion failed!"
|example1 = var a = 1;
var b = 2;
print(assert(a < b)); # prints "1" (true)
|example2 = var a = 1;
var b = 2;
assert(a > b, 'a is not greater than b'); # aborts with a custom error message
}}

===carttogeod()===
{{Nasal doc
|syntax = carttogeod(x, y, z);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=945|t=Source}}
|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>
|param1 = x
|param1text = Mandatory x-axis value, in metres.
|param2 = y
|param2text = Mandatory y-axis value, in metres.
|param3 = z
|param3text = Mandatory z-axis value, in metres.
|example1 = var (lat, lon, alt) = carttogeod(6378137, 0, 0); # point is the intersection of the prime meridian and equator.
print("Latitude: ", lat); # prints lat, lon and alt, which are all zero, see above
print("Longitude: ", lon);
print("Altitude: ", alt);
}}

===cmdarg()===
{{Nasal doc
|private = _cmdarg()
|syntax = cmdarg();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=513|t=Part 1}} {{!}} {{fgdata file|Nasal/globals.nas|t=Part 2}}
|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.
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:
* Bindings: This is needed so that the value of a joystick's axis can be accessed internally.
* 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).
* 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.
* 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>

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.

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.
|example1 = fgcommand("dialog-show", {"dialog-name": "cmdarg-demo"});
|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.
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>

<PropertyList>

<name>cmdarg-demo</name>
<layout>vbox</layout>

<text>
<label>Click "Close" to activate the demonstration (a message in the console).</label>
</text>

<button>
<legend>Close</legend>
<binding>
<command>nasal</command>
<script>print("Button binding root: '" ~ cmdarg().getPath() ~ "'");</script>
</binding>
<binding>
<command>dialog-close</command>
</binding>
</button>

</PropertyList>
</syntaxhighlight>
|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!"
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>

<PropertyList>

<name>cmdarg-demo</name>
<layout>vbox</layout>

<text>
<label>Click "Click me!" to activate the demonstration (the button's label will change).</label>
</text>

<button>
<legend>Click me!</legend>
<binding>
<command>nasal</command>
<script>change_label();</script>
</binding>
</button>

<button>
<legend>Close</legend>
<binding>
<command>dialog-close</command>
</binding>
</button>

<nasal>
<open><![CDATA[
var dlg_root = cmdarg();
var dlg_name = {"dialog-name": "cmdarg-demo"};
var change_label = func {
dlg_root.getNode("button[0]/legend").setValue("I've been changed!");
fgcommand("dialog-close", dlg_name);
fgcommand("dialog-show", dlg_name);
}
]]></open>
</nasal>

</PropertyList>
</syntaxhighlight>
|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]].
}}

===courseAndDistance()===
{{Nasal doc
|syntax = courseAndDistance(to);
courseAndDistance(from, to);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1668|t=Source}}
|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:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object with geodetic coordinates (cartesian coordinates will not be accepted)
|param1 = from
|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.
|param2 = to
|param2text = Like the first parameter, but defines the second point.
|example1text = This example demonstrates the usage of the function with the <code>airport</code> ghost type.
|example1 = var from = airportinfo("KSFO");
var to = airportinfo("KSQL");
var (course, dist) = courseAndDistance(from, to);
print(course); # prints course from KSFO to KSQL
print(dist); # prints distance in nm from KSFO to KSQL
|example2text = This example demonstrates the usage of the function with hashes containing ''lat'' and ''lon''.
|example2 = var from = {lat: 0, lon: 0};
var to = {lat: 1, lon: 1};
var (course, dist) = courseAndDistance(from, to);
print(course);
print(dist);
|example3text = This example demonstrates usage of a geo.Coord object.
|example3 = var from = geo.Coord.new().set_latlon(0, 0);
var to = geo.Coord.new().set_latlon(1, 1);
var (course, dist) = courseAndDistance(from, to);
print(course);
print(dist);
|example4text = This example demonstrates usage of differing parameter types.
|example4 = var from = airportinfo("KSFO");
var to = geo.Coord.new().set_latlon(0, 0);
var (course, dist) = courseAndDistance(from, to);
print(course);
print(dist);
|example5text = The same as above, but the other way round.
|example5 = var to = {lat: 1, lon: 1};
var (course, dist) = courseAndDistance(0, 0, to);
print(course);
print(dist);
|example6text = Usage of just one parameter.
|example6 = var dest = airportinfo("KSQL");
var (course, dist) = courseAndDistance(dest);
print("Turn to heading ", math.round(course), ". You have ", sprintf("%.2f", dist), " nm to go");
}}

===createFlightplan()===
{{Nasal doc
|syntax = createFlightplan(path);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2331|t=Source}}
|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.
|param1 = path
|param1text = Optional parameter defining the file from which a flightplan will be populated.
|example1 =
var path = getprop("/sim/fg-home") ~ "/Export/test.fgfp";
var flightplan = createFlightplan(path);
debug.dump(flightplan);
}}

===createDiscontinuity()===
{{Nasal doc
|syntax = createDiscontinuity();
|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.
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2045|t=Source}}
|version = 2016.1
|commit = {{flightgear commit|caead6|t=commit}}
}}
===createViaTo()===
{{Nasal doc
|syntax = createViaTo(airway, waypoint);
|text = Returns a <code>waypoint</code> ghost object. It represents a route "via '''airway''' to '''waypoint'''".
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2009|t=Source}}
|version = 2016.1
|commit = {{flightgear commit|caead6|t=commit}}
|param1 = airway
|param1text = The name of an airway.
|param2 = waypoint
|param2text = Must be in the airway and one of:
* The name of a waypoint.
* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, or <code>fix</code> ghost object.
}}
===createWP()===
{{Nasal doc
|syntax = createWP(pos, name[, flag]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1964|t=Source}}
|text = Creates a new waypoint ghost object.
|param1 = pos
|param1text = Dictates the position of the new waypoint. It can be one of the following:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. See example 4 below.
|param2 = name
|param2text = String that will become the name of the new waypoint.
|param3 = flag
|param3text = Optional string that will tell FlightGear what type of waypoint it is. Must be one of "sid," "star," "approach," "missed," or "pseudo."
|example1text = Creates a waypoint directly in front and 1 km away and appends it to the flight plan.
|example1 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);
var wp = createWP(pos, "NEWWP");
var fp = flightplan();
fp.appendWP(wp);
|example2 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);
var wp = createWP({lat: pos.lat(), lon: pos.lon()}, "NEWWP");
var fp = flightplan();
fp.appendWP(wp);
|example3 = var apt = airportinfo();
var wp = createWP(apt, "NEWWP");
var fp = flightplan();
fp.appendWP(wp);
|example4 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);
var wp = createWP(pos.lat(), pos.lon(), "NEWWP");
var fp = flightplan();
fp.appendWP(wp);
|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.
|example5 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);
var wp = createWP(pos, "NEWWP", "pseudo");
var fp = flightplan();
fp.appendWP(wp);
print(fp.getPlanSize());
fp.clearWPType("pseudo");
print(fp.getPlanSize());
}}

===createWPFrom()===
{{Nasal doc
|syntax = createWPFrom(object[, flag]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1989|t=Source}}
|text = Creates a new waypoint object from another object.
|param1 = object
|param1text = A ghost object. Must be a ghost type that is one of "airport," "navaid," "runway," or "fix."
|param2 = flag
|param2text = Optional string that will tell FlightGear what type of waypoint it is. Must be one of "sid," "star," "approach," "missed," or "pseudo."
|example1text = Creates a new waypoint and appends it to the flight plan.
|example1 = var apt = airportinfo("KSFO");
var wp = createWPFrom(apt);
var fp = flightplan();
fp.appendWP(wp);
|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.
|example2 = var apt = airportinfo("KSFO");
var wp = createWPFrom(apt, "pseudo");
print(wp.wp_name);
var fp = flightplan();
fp.appendWP(wp);
print(fp.getPlanSize());
fp.clearWPType("pseudo");
print(fp.getPlanSize());
}}

===defined()===
{{Nasal doc
|syntax = defined(symbol);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = Returns 1 (true) or 0 (false) depending on whether a variable exists.
|param1 = symbol
|param1text = A string that will be what the function searches for.
|example1 = var number = 12;
var check_exist = func {
print("Variable 'number' ", defined("number") == 1 ? "exists" : "does not exist"); # 'number' does exist
print("Variable 'number2' ", defined("number2") == 1 ? "exists" : "does not exist"); # 'number2' does not exist
}
check_exist();
}}

===directory()===
{{Nasal doc
|syntax = directory(path);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=572|t=Source}}
|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.
{{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.}}
|param1 = path
|param1text = Absolute file path.
|example1text = Gets the folders and files in [[$FG_ROOT]], and then removes the extra first two elements (see note above).
|example1 = var dir = directory(getprop("/sim/fg-root")); # get directory
dir = subvec(dir, 2); # strips off the first two elements
debug.dump(dir); # dump the vector
}}

===fgcommand()===
{{Nasal doc
|syntax = fgcommand(cmd[, args]);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=456|t=Part 1}} {{!}} {{fgdata file|Nasal/globals.nas|t=Part 2}}
|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.
|param1 = cmd
|param1text = String that is the name of the command that is to be run.
|param2 = args
|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).
|example1 = fgcommand("null"); # does nothing
|example2 = var args = props.Node.new({'script': 'print("Running fgcommand");'});
if (fgcommand("nasal", args)) { # prints "Running fgcommand" and then one of these print statements
print("Fgcommand succeeded");
} else {
print("Fgcommand encountered a problem");
}
|example3 = var args = { 'dialog-name': 'about' };
fgcommand("dialog-show", args); # shows the 'about' dialog
}}

===findAirportsByICAO() ===
{{Nasal doc
|syntax = findAirportsByICAO(search[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1096|t=Source}}
|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.
|param1 = search
|param1text = Search string for the function. Can either be a partial or a full ICAO code.
:{{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.}}
|param2 = type
|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."
|example1 = var apts = findAirportsByICAO("KSF"); # finds all airports matching "KSF"
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")"); # prints them
}
|example2 = var apts = findAirportsByICAO("SP0", "seaport"); # finds all seaplane bases matching "SP0"
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")"); # prints them
}
|example3 = var apt = findAirportsByICAO("XBET"); # one way to check if an airport does exist"
if (size(apt) == 0) {
print("Airport does not exist"); # this one will be printed
} else {
print("Airport does exist");
<nowiki>}</nowiki>
}}

===findAirportsWithinRange()===
{{Nasal doc
|syntax = findAirportsWithinRange([pos, ]range[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1066|t=Source}}
|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.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findAirportsWithinRange(lat, lon, range, type);</code>.
|param2 = range
|param2text = Mandatory number giving the range in nautical miles within which to search for airports/heliports/seaplane bases.only airports are searched for.
|param3 = type
|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."
|example1text = Searches for airports within 10 nm of [[KSFO]].
|example1 = var pos = airportinfo("KSFO");
var apts = findAirportsWithinRange(pos, 10);
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")");
}
|example2text = Searches for seaplane bases within 15 nm of [[KSFO]].
|example2 = var pos = airportinfo("KSFO");
var apts = findAirportsWithinRange(pos, 15, "seaport");
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")");
}
|example3text = Searches for airports within 10 nm of your current position.
|example3 = var apts = findAirportsWithinRange(10);
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")");
<nowiki>}</nowiki>
}}

===findCommByFrequencyMHz()===
findCommByFrequencyMHz([pos, ]freq[, type]);
[[sourceforge:p/flightgear/flightgear/ci/next/tree/src/Scripting/NasalPositioned.cxx#l1547|source]]

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.

'''pos'''

: Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findCommByFrequencyMHz(lat, lon, freq, type);</code>.
; freq
: Frequency, in megahertz, of the station to search for.
; type
: 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)
'''Example'''
var com = findCommByFrequencyMHz(123.6);
print("ID: ", com.id); # prints info about the comm station
print("Name: ", com.name);
print("Latitude: ", com.lat);
print("Longitude: ", com.lon);
print("Type: ", com.type);
print("Frequency: ", sprintf("%.3f", com.frequency), " Mhz");

=== findFixesByID() ===
{{Nasal doc
|syntax = findFixesByID([pos, ]id);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1627|t=Source}}
|text = Returns a vector containing <code>fix</code> ghost objects matching a given ID, sorted by range from a certain position.
{{inote|Fixes are (usually) also known as waypoints.}}
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findFixesByID(lat, lon, id);</code>.
|param2 = id
|param2text = Full or partial ID of the fix to search for.
:{{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.}}
|example1 = var fixes = findFixesByID("POGIC");
foreach(var fix; fixes){
print(fix.id, " - lat: ", fix.lat, " {{!}} lon: ", fix.lon); # prints information about POGIC
}
|example2 = var fix = findFixesByID("ZUNAP");
fix = fix[0];
var (course, dist) = courseAndDistance(fix);
print("Turn to heading ", math.round(course), ". You have ", sprintf("%.2f", dist), " nm to go to reach ", fixes[0].id);
}}

===findNavaidByFrequencyMHz()===
{{Nasal doc
|syntax = findNavaidByFrequencyMHz([pos, ]freq[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1547|t=Source}}
|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.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidByFrequencyMHz(lat, lon, freq, type);</code>.
|param2 = freq
|param2text = Frequency, in megahertz, of the navaid to search for.
|param3 = type
|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}}.
|example1 = var navaid = findNavaidByFrequencyMHz(109.55);
print("ID: ", navaid.id); # prints info about the navaid
print("Name: ", navaid.name);
print("Latitude: ", navaid.lat);
print("Longitude: ", navaid.lon);
print("Elevation (AMSL): ", navaid.elevation, " m");
print("Type: ", navaid.type);
print("Frequency: ", sprintf("%.3f", navaid.frequency / 100), " Mhz");
print("Range: ", navaid.range_nm, " nm");
if(navaid.course) print("Course: ", navaid.course);
}}

=== findNavaidsByFrequencyMHz()===
{{Nasal doc
|syntax = findNavaidsByFrequencyMHz([pos, ]freq[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1572|t=Source}}
|text = Returns a vector conatining <code>navaid</code> ghost objects for navaids that match a given frequency, sorted from nearest to furthest.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidsByFrequencyMHz(lat, lon, freq, type);</code>.
|param2 = freq
|param2text = Frequency, in megahertz, of the navaid to search for.
|param3 = type
|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}}.
|example1 = var navaids = findNavaidsByFrequencyMHz(109.55);
foreach(var navaid; navaids){
print("--");
print("ID: ", navaid.id); # prints info about the navaid
print("Name: ", navaid.name);
print("Latitude: ", navaid.lat);
print("Longitude: ", navaid.lon);
print("Elevation (AMSL): ", navaid.elevation, " m");
print("Type: ", navaid.type);
print("Frequency: ", sprintf("%.3f", navaid.frequency / 100), " Mhz");
print("Range: ", navaid.range_nm, " nm");
if(navaid.course) print("Course: ", navaid.course);
print("--");
<nowiki>}</nowiki>
}}

===findNavaidsByID()===
{{Nasal doc
|syntax = findNavaidsByID([pos, ]id[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1600|t=Source}}
|text = Returns a vector containing <code>navaid</code> ghost objects matching a given ID, sorted by range from a certain position.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidsByID(lat, lon, id, type);</code>.
|param2 = id
|param2text = Full or partial ID of the fix to search for.
:{{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.}}
|param3 = type
|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}}.
|example1 = var navaid = findNavaidsByID("MXW");
navaid = navaid[0];
print("ID: ", navaid.id); # prints info about 'MXW' (a VOR station)
print("Name: ", navaid.name);
print("Latitude: ", navaid.lat);
print("Longitude: ", navaid.lon);
print("Elevation (AMSL): ", navaid.elevation, " m");
print("Type: ", navaid.type);
print("Frequency: ", sprintf("%.3f", navaid.frequency / 1000), " Mhz");
print("Range: ", navaid.range_nm, " nm");
}}

===findNavaidsWithinRange()===
{{Nasal doc
|syntax = findNavaidsWithinRange([pos, ]range[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1518|t=Source}}
|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.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidsWithinRange(lat, lon, range, type);</code>.
|param2 = range
|param2text = Mandatory number giving the range in nautical miles within which to search for navaids.
|param3 = type
|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}}.
|example1text = Searches for navaids within 10 nm of [[KSFO]].
|example1 = var pos = airportinfo("KSFO");
var navs = findNavaidsWithinRange(pos, 10);
foreach(var nav; navs){
print(nav.name, " (ID: ", nav.id, ")");
}
|example2text = Searches for navaids within 10 nm of your current position.
|example2 = var navs = findNavaidsWithinRange(10);
foreach(var nav; navs){
print(nav.name, " (ID: ", nav.id, ")");
<nowiki>}</nowiki>
}}

===finddata()===
{{Nasal doc
|syntax = finddata(path);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=603|t=Source}}
|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]].
|param1 = path
|param1text = A relative path as a string.
|example1 = var path = finddata("Aircraft/Generic");
print(path); # prints the absolute path to $FG_ROOT/Aircraft/Generic
|example2 = var path = finddata("Airports");
print(path); # prints the absolute path to <TerraSync dir>/Airports
|example3 = var path = finddata("preferences.xml");
print(path); # prints the absolute path to $FG_ROOT/preferences.xml
}}

===flightplan()===
{{Nasal doc
|syntax = flightplan([path]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1738|t=Source}}
|text = {{see also|Nasal Flightplan}}
Returns a flight plan object, either one for the current flight plan, or one loaded from a given path.
|param1 = path
|param1text = Optional path to flight plan XML file.
|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.
|example1 = var fp = flightplan();
print(fp.getWP(fp.current).id);
|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>.
|example2 = var path = getprop('/sim/fg-home') ~ '/fp-demo.xml';
var fp = flightplan(path);
for(var i = 0; i < fp.getPlanSize(); i += 1){
print(fp.getWP(i).id);
<nowiki>}</nowiki>
}}

===geodinfo()===
{{Nasal doc
|syntax = geodinfo(lat, lon[, max_alt]);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=981|t=Source}}
|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}}):
* '''light_coverage:''' The coverage of a single point of light in m<sup>2</sup>.
* '''bumpiness:''' Normalized bumpiness factor for the material.
* '''load_resistance:''' The amount of pressure in N/m<sup>2</sup> the material can withstand without deformation.
* '''solid:''' 1 (true) or false (0) depending on whether the material is solid or not.
* '''names:''' Vector of scenery types (usually generated by [[TerraGear]]) that will use this material.
* '''friction_factor:''' Normalized friction factor of the material.
* '''rolling_friction:''' The rolling friction coefficient of the material.

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.
|param1 = lat
|param1text = Latitude, inputted as a number.
|param2 = lon
|param2text = Longitude, inputted as a number.
|param3 = max_alt
|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.
|example1text = Dumps information about ground underneath the aircraft.
|example1 = var pos = geo.aircraft_position();
var info = geodinfo(pos.lat(), pos.lon());
debug.dump(info);
|example2text = Prints whether the ground underneath the aircraft is solid or is water.
|example2 = var pos = geo.aircraft_position();
var info = geodinfo(pos.lat(), pos.lon());
if (info != nil and info[1] != nil) {
print("The ground underneath the aircraft is ", info[1].solid == 1 ? "solid." : "water.");
<nowiki>}</nowiki>
}}

=== geodtocart() ===
{{Nasal doc
|syntax = geodtocart(lat, lon, alt);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=962|t=Source}}
|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.
|param1 = lat
|param1text = Latitude, in degrees.
|param2 = lon
|param2text = Longitude, in degrees.
|param3 = alt
|param3text = Altitude, in metres.
|example1 = var (x, y, z) = geodtocart(0, 0, 0); # point is the intersection of the prime meridian and equator.
print("x: ", x); # prints "x: 6378137"
print("y: ", y); # prints "y: 0"
print("z: ", z); # prints "y: 0"
}}

=== get_cart_ground_intersection()===
Introduced in 2017.2.1, see [[Terrain Detection]].

===getprop()===
{{Nasal doc
|syntax = <nowiki>getprop(path[, path[, ...]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=345|t=Source}}
|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).
|param1 = path
|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.
|example1 = print("You have FlightGear v", getprop("/sim/version/flightgear")); # prints FlightGear version
|example2text = Note that the example below will only work in FlightGear 3.2 and above.
|example2 = for(var i = 0; i < 8; i += 1){
print("View #", i + 1, " is named ", getprop("/sim/view", i, "name"));
}
|example3text = Same as above, but is supported by all versions of FlightGear.
|example3 = for(var i = 0; i < 8; i += 1){
print("View #", i + 1, " is named ", getprop("/sim/view[" ~ i ~ "]/name"));
<nowiki>}</nowiki>
}}
==== See also====
{{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:
To get a Node rather than its value, use <code>props.globals.getNode()</code> - see [[Nasal_library/props]]. }}

===greatCircleMove()===
{{Nasal doc
|syntax = greatCircleMove([pos, ]course, dist);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1681|t=Source}}
|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).
|param1 = pos
|param1text = Optional position to calculate from. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost object.
:* A hash with ''lat'' and ''lon'' members
:* A <code>geo.Coord</code> object
:* A lat/lon pair, that is, a pair of numbers (latitude followed by longitude) separated by a comma: <code>greatCircleMove(lat,lon, ...)</code>.
|param2 = course
|param2text = Course to new set of coordinates, in degrees (in the range 0–360).
|param3 = dist
|param3text = Distance in nautical miles to the new set of coordinates.
|example1 = var pos = greatCircleMove(0,0, 0, 1);
debug.dump(pos); # print hash with coordinates
|example2 = var fix = findFixesByID("POGIC");
fix = fix[0];
var pos = greatCircleMove(fix, 45, 10);
debug.dump(pos); # print hash with coordinates
}}

===interpolate()===
{{Nasal doc
|private = _interpolate()
|syntax = <nowiki>interpolate(prop, value1, time1[, value2, time2[, ...]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=522|t=Part 1}} {{!}} {{fgdata file|Nasal/globals.nas|t=Part 2}}
|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.
|param1 = prop
|param1text = String or <code>props.Node</code> object that indicates a node in the property tree to be used.
|param2 = value''n''
|param2text = Target value to change the property to in the set amount of time. This should be a number.
|param3 = time''n''
|param3text = Time in seconds, that will be taken for the interpolation.
|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.
|example1 = setprop("/test", 0); # (re-)set property
interpolate("/test",
50, 5, # interpolate to 50 in 5 seconds
10, 2, # interpolate to 10 in 2 seconds
0, 5); # interpolate to 0 in 5 seconds
|example2 = # Apply the left brake at 20% per second
var prop = "controls/gear/brake-left";
var dist = 1 - getprop(prop);
if (dist == 1) {
interpolate(prop, 1, dist / 0.2);
<nowiki>}</nowiki>
}}

===isa()===
{{Nasal doc
|syntax = isa(object, class);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|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.
|param1 = object
|param1text = Object to check.
|param2 = class
|param2text = Class/object to check that '''object''' inherits from or is an instance of.
|example1 = var coord = geo.Coord.new();
if(isa(coord, geo.Coord)){
print("Variable 'coord' is an instance of class 'geo.Coord'"); # this one will be printed
} else {
print("Variable 'coord' is not an instance of class 'geo.Coord'");
}
|example2 = var coord = geo.Coord.new();
if(isa(coord, props.Node)){
print("Variable 'coord' is an instance of class 'props.Node'");
} else {
print("Variable 'coord' is not an instance of class 'props.Node'"); # this one will be printed
}
|example3text = The example below demonstrates checking of inheritance.
|example3 = var Const = {
constant: 2,
getConst: func {
return me.constant;
}
};

var Add = {
new: func {
return { parents: [Add, Const] };
},

addToConst: func(a){
return a * me.getConst();
}
};

var m = Add.new();
print(m.addToConst(4));

if(isa(m, Add)) print("Variable 'm' is an instance of class 'Add'"); # will be printed
if(isa(m, Const)) print("Variable 'm' is an instance of class 'Const'"); # will also be printed
}}

===logprint()===
{{Nasal doc
|syntax = <nowiki>logprint(priority[, msg[, msg[, ...]]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=431|t=Source}}
|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}}.
|param1 = priority
|param1text = Number specifying the priority level of the outputted message:
:{{{!}} class="wikitable"
! Number !! Debug type
{{!-}}
{{!}} 1 {{!!}} Bulk
{{!-}}
{{!}} 2 {{!!}} Debug
{{!-}}
{{!}} 3 {{!!}} Info
{{!-}}
{{!}} 4 {{!!}} Warn
{{!-}}
{{!}} 5 {{!!}} Alert
{{!}}}
|param2 = msg
|param2text = The message. There is no limit to the arguments you give give. They will be concatenated together before logging.
|example1 = # logs the value of pi to three decimal places with log level 3
logprint(3, "pi = ", sprintf("%.3f", math.pi));
|example2 = logprint(5, "Alert! This is an important message!");
}}
{{note|
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:

LOG_BULK, LOG_WARN, LOG_DEBUG, LOG_INFO, LOG_ALERT, DEV_WARN, DEV_ALERT }}

===magvar() ===
{{Nasal doc
|syntax = magvar([pos]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1642|t=Source}}
|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.
{{{!}} class="wikitable"
! FlightGear versions !! Model !! Reference date
{{!-}}
{{!}} 3.6 and above {{!!}} {{wikipedia|World Magnetic Model}} (WMM) 2015 {{!!}} 1 January 2015
{{!-}}
{{!}} 0.9.11-pre1 to 3.4 {{!!}} WMM 2005 {{!!}} 1 January 2005
{{!-}}
{{!}} 0.7.3 to 0.9.10 {{!!}} WMM 2000 {{!!}} 1 January 2000
{{!}}}
|param1 = pos
|param1text = Optional position to calculate from. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost object.
:* A hash with ''lat'' and ''lon'' members
:* A <code>geo.Coord</code> object
:* A lat/lon pair, that is, a pair of numbers (latitude followed by longitude) separated by a comma: <code>magvar(lat,lon)</code>.
|example1 = print(magvar(0, 0)); # prints the magnetic variation at 0, 0
}}

===maketimer() ===
{{Nasal doc
|syntax = maketimer(interval[, self], function);
|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}}
|version = 2.12
|commit = {{flightgear commit|ab939f|t=commit}}
|text = Returns a timer object containing the following methods and members:
* '''start()''': Starts the timer.
* '''stop()''': Stops the timer.
* '''restart(interval)''': Restarts the timer with the given interval.
* '''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).
* '''isRunning''': Read-only bool telling whether the timer is currently running.
* '''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.
Unlike {{func link|settimer()}}, which it replaces, <code>maketimer()</code> provides more control over the timer. In addition, it can help reduce memory usage.
|param1 = interval
|param1text = Interval in seconds for the timer.
|param2 = self
|param2text = Optional parameter specifying what any <code>'''me'''</code> references in the function being called will refer to.
|param3 = function
|param3text = Function to be called at the given interval.
|example1 = var timer = maketimer(1, func(){
print("Hello, World!"); # print "Hello, World!" once every second (call timer.stop() to stop it)
});
timer.start();
|example2 = var timer = maketimer(1, math, func(){
print(me.math); # 'me' reference is the 'math' namespace
});
timer.singleShot = 1; # timer will only be run once
timer.start();
|example3 = var timer = maketimer(1, func(){
print("Hello, World!"); # print "Hello, World!" once every second (call timer.stop() to stop it)
});
timer.start();
print(timer.isRunning); # prints 1
|example4text = In the example below, "Hello, World!" will be printed after one second the first time, and after two seconds thereafter.
|example4 = var update = func(){
print("Hello, World!");
timer.restart(2); # restarts the timer with a two second interval
}

var timer = maketimer(1, update);
timer.singleShot = 1;
timer.start();
}}

===maketimestamp()===
{{Nasal doc
|syntax = maketimestamp()
|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}}
|version = 2019.2
|commit = {{flightgear commit|7db06300|t=commit}}
|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:
* '''stamp()''': Resets the timing operation. Call this first.
* '''elapsedMSec()''': returns number of milliseconds elapsed since stamp() called. Resolution may vary depending on platform but is usually at least millisecond accuracy.
* '''elapsedUSec()''': returns number of microseconds elapsed since stamp() called. Resolution may vary depending on platform but is usually at least millisecond accuracy.
|
|example1text = In the example below the number of milliseconds elapsed will be printed.
|example1 = var timestamp = maketimestamp();
timestamp.stamp();
print(timestamp.elapsedMSec(), "ms elapsed");
print(timestamp.elapsedMSec(), "ms elapsed");
}}

===md5()===
{{Nasal doc
|syntax = md5(string);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=758|t=Source}}
|version = 3.2
|commit = {{flightgear commit|cfbf9e|t=commit}}
|text = Returns a the {{wikipedia|MD5}} hash (as a string) of the inputted string.
|param1 = string
|param1text = String the generate the hash of. Mandatory.
|example1text = The below code should output <code>65a8e27d8879283831b664bd8b7f0ad4</code>.
|example1 = print(md5("Hello, World!"));
}}

===navinfo()===
{{Nasal doc
|syntax = navinfo(lat, lon, type, id);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1453|t=Source}}
|text = Returns vector <code>navaid</code> ghost objects matching the given '''type''' and '''id''' or <code>'''nil'''</code> on error.
|param1 = lat ''and'' lon
|param1text = If given, the returned navaids will be put into order of ascending distance from the location.
|param2 = type
|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."
|param3 = id
|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.
|example1 = navinfo("vor"); # returns all VORs
|example2 = navinfo("HAM"); # return all navaids whose names start with "HAM"
|example3 = navinfo("vor", "HAM"); # return all VORs whose names start with "HAM"
|example4 = navinfo(34,48,"vor","HAM"); # return all VORs whose names start with "HAM" and sorted by distance relative to 34°, 48°
}}

===parse_markdown()===
{{Nasal doc
|syntax = parse_markdown(markdown);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=745|t=Part 1}} {{!}} {{simgear file|simgear/misc/SimpleMarkdown.cxx|t=Part 2}}
|version = 3.2
|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:
* It strips whitespace from the beginning of the string.
* It supports [http://daringfireball.net/projects/markdown/syntax#p paragraphs and line breaks].
* It collapses whitespace.
* It converts unordered [http://daringfireball.net/projects/markdown/syntax#list lists] to use a bullet character (•). 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.
|param1 = markdown
|param1text = String containing Markdown to be parsed.
|example1text =
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>).
<syntaxhighlight lang="xml" highlight="41-50">
<?xml version="1.0" encoding="UTF-8"?>

<PropertyList>

<name>test</name>
<layout>vbox</layout>

<group>
<layout>hbox</layout>

<empty>
<stretch>true</stretch>
</empty>

<text>
<label>parse_markdown() test dialog</label>
</text>

<empty>
<stretch>true</stretch>
</empty>

<button>
<legend></legend>
<pref-width>16</pref-width>
<pref-height>16</pref-height>
<binding>
<command>dialog-close</command>
</binding>
</button>

</group>

<canvas>
<name>Canvas plot</name>
<stretch>true</stretch>
<pref-width>400</pref-width>
<pref-height>300</pref-height>
<nasal>
<load><![CDATA[
var text = 'Items:
* apples
* oranges
* pears

Some text.
Some more items:
* apples
* oranges
* pears';

var parsed = parse_markdown(text);

var root_canvas = canvas.get(cmdarg());
root_canvas.setColorBackground(255, 255, 255);
var root = root_canvas.createGroup();

var text_dis = root.createChild("text")
.setText(parsed)
.setTranslation(5, 5)
.setFont("LiberationFonts\LiberationSans-Regular.ttf")
.setFontSize(15)
.setColor(0, 0, 0)
.setDrawMode(canvas.Text.TEXT)
.setAlignment("left-top");
]]></load>
</nasal>
</canvas>

</PropertyList>
</syntaxhighlight>
|example1 = fgcommand("dialog-show", {"dialog-name": "test"});
|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.
|example2 = <nowiki>var markdown = 'Items:
* apples
* oranges
* pears

Some text.
Some more items:
* apples
* oranges
* pears';

var parsed = parse_markdown(markdown);

debug.dump(parsed);

var path = string.normpath(getprop("/sim/fg-home") ~ '/Export/parse_markdown()-test.html');

var file = io.open(path, "w");

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>";

io.write(file, html);
io.close(file);
print("Done, file ready for viewing (" ~ path ~ ")");</nowiki>
}}

===parsexml()===
{{Nasal doc
|syntax = <nowiki>parsexml(path[, start[, end[, data[, pro_ins]]]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=710|t=Source}}
|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.
|param1 = path
|param1text = Mandatory absolute path to the XML file to be parsed.
|param2 = start
|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.
|param3 = end
|param3text = Optional callback function that will be called for every ending tag. The function should take one argument: the tag name.
|param4 = data
|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.
|param5 = pro_ins
|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.
|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.
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>

<?xml-stylesheet type="text/xsl" href="style.xsl"?>

<foo>
<blah type="string"><![CDATA[ <sender>John Smith</sender> ]]></blah>
<blah2 type="string">Orange & lemons</blah2>
</foo>
</syntaxhighlight>
|example1 = var start = func(name, attr){
print("Starting tag: '", name, "'");
foreach(var a; keys(attr)){
print("\twith attribute ", a, '="', attr[a], '"');
}
}

var end = func(name){
print("Ending tag: '", name, "'");
}

var data = func(data){
print("Data = '", data, "'");
}

var pro_instr = func(target, data){
print("Processing instruction: target = '", target, "', data = '", data, "'");
}

parsexml(getprop("/sim/fg-home") ~ '/Export/demo.xml', start, end, data, pro_instr);
}}

===print()===
{{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.

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>}}

{{Nasal doc
|syntax = <nowiki>print(data[, data[, ...]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=415|t=Source}}
|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.
|param1 = data
|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.
|example1 = print("Just", " a ", "test"); # prints "Just a test"
|example2 = print("pi = ", math.pi); # prints "pi = 3.141592..."
}}

=== printf() ===
{{Nasal doc
|syntax = <nowiki>printf(format[, arg[, arg, [...]]]);</nowiki>
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|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>).
|example1 = printf("In hexadecimal, 100000 = %X", 186A0); # prints "In hexadecimal, 100000 = 186A0"
}}

===printlog()===
{{caution|This function is deprecated and doesn't work. Please use the new one {{func link|logprint()}}.}}
{{Nasal doc
|syntax = <nowiki>printlog(level, data[, data[, ...]]);</nowiki>
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|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.
|param1 = level
|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.
|param2 = data
|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.
|example1 = printlog("alert", "This is an alert"); # message will be printed
|example2 = printlog("info", "Just informing you about something"); # message will be printed only if log level is set to "info" or less
}}

===rand()===
{{Nasal doc
|syntax = rand();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=554|t=Source}}
|text = Returns a random floating point number between 0 (inclusive) and 1 (exclusive). It takes no arguments.
|example1 = print(rand()); # prints random number
}}

===registerFlightPlanDelegate()===
{{Nasal doc
|syntax = registerFlightPlanDelegate(init_func);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1879|t=Source}}
|text = Registers a flight plan delegate. See <tt>''{{fgdata file|Nasal/route_manager.nas|t=$FG_ROOT/Nasal/route_manager.nas}}''</tt> for examples.
|param1 = init_func
|param1text = Initialization function which will be called during FlightGear's startup.
}}
===removecommand()===
{{Nasal doc
|syntax = removecommand(cmd);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=668|t=Source}}
|text = Removes the given fgcommand. Returns <code>'''nil'''</code>.
{{caution|This will remove '''any''' [[fgcommands|fgcommand]], even those implemented in C++, so use with caution!}}
|param1 = cmd
|param1text = String specifying the name of the command to remove.
|example1 = addcommand("hello", func(){
print("Hello");
});
fgcommand("hello"); # "Hello" will be printed
removecommand("hello"); # removes it
}}

===removelistener()===
{{Nasal doc
|syntax = removelistener(id);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=1384|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=506|t=Part 2}}
|text = Removes and deactivates the given listener and returns the number of listeners left or <code>'''nil'''</code> on error.
{{note|It is good practice to remove listeners when they are not required anymore. This prevents the listeners reducing FlightGear's run performance.}}
|param1 = id
|param1text = ID of listener as returned by {{func link|setlistener()}}.
|example1 = var ls = setlistener("/sim/test", func(){
print("Property '/sim/test' has been changed");
});
setprop("/sim/test", "blah"); # trigger listener
var rem = removelistener(ls); # remove listener
print("There are ", rem, " listeners remaining");
}}

===resolvepath()===
{{Nasal doc
|syntax = resolvepath(path);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=604|t=Source}}
|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.
|param1 = path
|param1text = Relative path to be completed.
|example1 = print(resolvepath("Nasal/globals.nas")); # prints the equivalent of $FG_ROOT/Nasal/globals.nas
|example2 = print(resolvepath("blah")); # prints nothing; could not be resolved
|example3 = var file_path = resolvepath("Aircraft/SenecaII/some-file");
if (file_path != ""){
gui.popupTip("some-file found", 2);
} else {
gui.popupTip("some-file not found", 2);
<nowiki>}</nowiki>
}}

===setlistener()===
{{Nasal doc
|syntax = <nowiki>setlistener(node, code[, init[, type]]);</nowiki>
|private = _setlistener()
|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.''
|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()}}.
{{note|Listeners are known to be a source of resource leaks. To avoid this, please take measures such as:
* Using {{func link|removelistener()}} when they are not needed any more.
* Using a single initialization listener.
* Avoiding tying listeners to properties that are rapidly updated (e.g., many times per frame).
}}
|param1 = node
|param1text = Mandatory string or <code>props.Node</code> object pointing to a property in the [[Property Tree]].
|param2 = code
|param2text = Mandatory callback function to execute when the listener is triggered. The function can take up to four arguments in the following order:
* '''changed''': a <code>props.Node</code> object pointing to the changed node.
* '''listen''': a <code>props.Node</code> object pointing to the listened-to node. Note that this argument maybe different depending on the '''type'''.
* '''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.
* '''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.
|param3 = init
|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).
|param4 = type
|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.
|example1 = var prop = props.globals.initNode("/sim/test", "", "STRING"); # create property
var id = setlistener("/sim/test", func(n){ # create listener
print("Value: ", n.getValue());
});
setprop("/sim/test", "blah"); # trigger listener
removelistener(id); # remove listener
prop.remove(); # remove property
}}

===setprop()===
{{Nasal doc
|syntax = <nowiki>setprop(path[, path[, ...]], value);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=385|t=Source}}
|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.
{{note|If you want to remove a property, you will have to use one of the <code>props</code> helpers:
<syntaxhighlight lang="nasal">
props.globals.getNode("foo/bar").remove(); # take out the complete node
props.globals.getNode("foo").removeChild("bar"); # take out a certain child node
</syntaxhighlight>
}}
|param1 = path
|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.
|param2 = value
|param2text = Value to write to the given property. Must be either a string or a number.
|example1 = setprop("/sim/demo", "This is a demo");
|example2text = Note that the example below will only work in FlightGear 3.2 and above.
|example2 = for(var i = 0; i < 3; i += 1){
setprop("/sim/demo", i, "Demo #" ~ i));
}
|example3text = Same as above, but is supported by all versions of FlightGear.
|example3 = for(var i = 0; i < 3; i += 1){
setprop("/sim/demo[" ~ i ~ "]", "Demo #" ~ i));
<nowiki>}</nowiki>
}}
====See also====
{{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:
To get a Node rather than its value, use <code>props.globals.getNode()</code> - see [[Nasal_library/props]]. }}

===settimer() ===
{{Nasal doc
|syntax = settimer(function, delta[, realtime]);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=499|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=1286|t=Part 2}}
|text = Runs the given function a specified amount of seconds after the current time. Returns <code>'''nil'''</code>.
{{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.}}
|param1 = function
|param1text = Mandatory function that will be called. It may be necessary to enclose code in an anonymous function (see example).
|param2 = delta
|param2text = Mandatory amount of time in seconds after which the function will be called.
|param3 = realtime
|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.
|example1 = var myFunc = func(){
print("Hello");
}

settimer(myFunc, 2); # runs myFunc after 2 seconds
|example2 = var sqr = func(a){
return a * a;
}

settimer(func(){
print(sqr(2)); # will print 4 after 2 seconds
}, 2);
}}

===srand() ===
{{Nasal doc
|syntax = srand();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=559|t=Source}}
|text = Makes the pseudorandom number generator (see {{func link|rand()}}) generate a new {{wikipedia|random seed|noicon=1}} based on time. Returns 0.
}}
===systime()===
{{Nasal doc
|syntax = systime();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=770|t=Source}}
|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).
{{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]}}
|example1 = print("Unix time: ", systime()); # prints Unix time
|example2 = var myFunc = func(){
for(var i = 0; i <= 10; i += 1){
print("Interation #", i);
}
}
var t = systime(); # record time
myFunc(); # run function
var t2 = systime(); # record new time
print("myFunc() took ", t2 - t, " seconds"); # print result
}}

===thisfunc()===
{{Nasal doc
|syntax = thisfunc();
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = Returns the function from which this function is called. This allows a function to reliably and safely call itself from within a closure.
|example1 = var stringify_vec = func(input){
if (typeof(input) == "scalar"){
return sprintf("%s", input);
} elsif (typeof(input) == "vector") {
if (size(input) == 0) return "[]";
var this = thisfunc();
var buffer = "[";
for(var i = 0; i < size(input); i += 1){
buffer ~= this(input[i]);
if (i == size(input) - 1) {
buffer ~= "]";
} else {
buffer ~= ", ";
}
}
return buffer;
} else {
die("stringify_vec(): Error! Invalid input. Must be a vector or scalar");
}
}

var test_vec = ["a", "b", "c", [1, 2, 3], "d"];
debug.dump(stringify_vec(test_vec)); # prints "[a, b, c, [1, 2, 3], d]"
test_vec = [];
debug.dump(stringify_vec(test_vec)); # prints "[]"
test_vec = {};
debug.dump(stringify_vec(test_vec)); # will throw an error
}}

===tileIndex() ===
{{Nasal doc
|syntax = tileIndex();
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1720|t=Source}}
|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>.
|example1 = print(tileIndex()); # print index
}}

=== tilePath()===
{{Nasal doc
|syntax = tilePath();
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1712|t=Source}}
|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>.
|example1 = print(tilePath()); # print path
}}

=== values()===
{{Nasal doc
|syntax = values(hash);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = Returns a vector containing the values of the given hash.
|param1 = hash
|param1text = Mandatory hash to get the values of.
|example1 = var hash = {
"a": 1,
"b": 2,
"c": 3
};

foreach(var val; values(hash)){
print(val);
}
|example2text = The below example does exactly the same thing as the above example, but does not use <code>values()</code>:
|example2 = var hash = {
"a": 1,
"b": 2,
"c": 3
};

foreach(var key; keys(hash)){
print(hash[key]);
<nowiki>}</nowiki>
}}

==Extension functions new in FG 2020.1 ==
The following functions have been added to the nasal core library and will be released with FlightGear version 2020.1.
Before the release they are available in the development branch "next".

===isfunc()===
Returns 1 if type or argument is a function, otherwise 0.

===isghost()===
Returns 1 if type or argument is a ghost, otherwise 0.

=== ishash()===
Returns 1 if type or argument is a hash, otherwise 0.

===isint()===
{{Nasal doc
|syntax = isint(x);
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}
|text = Returns 1 if argument has a numeric value and x == floor(x), e.g. integer.
}}

===isnum()===
{{Nasal doc
|syntax = isnum(x);
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}
|text = Returns 1 if typeof(x) is "scalar" and x has a numeric value otherwise 0.
}}

===isscalar()===
{{Nasal doc
|syntax = isscalar(x);
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}
|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 "~".
|example1 = var a = "foo";
var b=42;
if (isscalar(a) and isscalar(b)) print(a~b);
if (isstr(a)) print("a is a string");
if (isint(b)) print("b is an integer");
# if (isscalar(a))... is equivalent to if (typeof(a) == "scalar")...
}}

===isstr()===
Returns 1 if type or argument is a string, otherwise 0.

===isvec()===
Returns 1 if type or argument is a vector, otherwise 0.

===vecindex()===
{{Nasal doc
|syntax = vecindex(vector, value);
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}
|text = Returns the index of value or nil, if value is not found in vector.
|example1=
var myvector = ["apple", "bananna", "coconut"];
# to check if a vector contains a certain value compare vecindex to nil
if (vecindex(myvector, "apple") != nil) {
print("found apple");
}
# WARNING: this will not work as desired because index is 0
if (vecindex(myvector, "apple")) {
print("found apple");
<nowiki>}</nowiki>

}}

==Variables==
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}}.

===D2R===
{{Nasal doc
|syntax = var radians = degrees * D2R;
|text = Converts an angle from degrees to radians when multiplied by the angle in degrees. Equal to <code>π / 180</code>.
}}
===FPS2KT===
{{Nasal doc
|syntax = var knots = feet_per_second * FPS2KT;
|text = Converts a velocity from feet per second to knots when multiplied by the velocity in feet per second. Approximately equal to 0.5925.
}}
===FT2M===
{{Nasal doc
|syntax = var metres = feet * FT2M;
|text = Converts a length from feet to metres when multiplied by the length in feet. Equal to 0.3048.
}}
===GAL2L ===
{{Nasal doc
|syntax = var litres = gallons * GAL2L;
|text = Converts a volume from US liquid gallons to litres when multiplied by the volume in gallons. Approximately equal to 3.7854.
}}
===IN2M===
{{Nasal doc
|syntax = var metres = inches * IN2M;
|text = Converts a length from inches to metres when multiplied by the length in inches. Equal to 0.0254.
}}
===KG2LB===
{{Nasal doc
|syntax = var pounds = kilograms * KG2LB;
|text = Converts a mass from kilograms to pounds when multiplied by the mass in kilograms. Approximately equal to 2.2046.
}}
===KT2FPS===
{{Nasal doc
|syntax = var feet_per_second = knots * KT2FPS;
|text = Converts a velocity from knots to feet per second when multiplied by the velocity in knots. Approximately equal to 1.6878.
}}
===KT2MPS===
{{Nasal doc
|syntax = var metres_per_second = knots * KT2MPS;
|text = Converts a velocity from knots to metres per second when multiplied by the velocity in knots. Approximately equal to 0.5144.
}}
===L2GAL===
{{Nasal doc
|syntax = var gallons = litres * L2GAL;
|text = Converts a volume from litres to US liquid gallons when multiplied by the volume in litres. Approximately equal to 0.2642.
}}
===LB2KG===
{{Nasal doc
|syntax = var kilograms = pounds * LB2KG;
|text = Converts a mass from pounds to kilograms when multiplied by the mass in pounds. Approximately equal to 0.4536.
}}
===M2FT ===
{{Nasal doc
|syntax = var feet = metres * M2FT;
|text = Converts a length from metres to feet when multiplied by the length in metres. Approximately equal to 3.2808.
}}
===M2IN===
{{Nasal doc
|syntax = var inches = metres * M2IN;
|text = Converts a length from metres to inches when multiplied by the length in metres. Approximately equal to 39.3701.
}}
===M2NM ===
{{Nasal doc
|syntax = var nautical_miles = metres * M2NM;
|text = Converts a length from metres to nautical miles when multiplied by the length in metres. Approximately equal to 0.00054.
}}
===MPS2KT ===
{{Nasal doc
|syntax = var knots = metres_per_second * MPS2KT;
|text = Converts a velocity from metres per second to knots when multiplied by the velocity in metres per second. Approximately equal to 1.9438.
}}
===NM2M ===
{{Nasal doc
|syntax = var metres = nautical_miles * NM2M;
|text = Converts a length from nautical miles to metres when multiplied by the length in nautical miles. Equal to 1,852.
}}
===R2D===
{{Nasal doc
|syntax = var degrees = radians * R2D;
|text = Converts an angle from radians to degrees when multiplied by the angle in radians. Equal to <code>180 / π</code>.
}}

{{Appendix}}

{{Nasal namespaces}}

Nasal library

2025-12-04T12:35:48Z

PlayeRom: /* sprintf() */

{{Nasal Navigation|nocat=1}}
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:
* {{flightgear file|src/Scripting}}
* {{simgear file|simgear/nasal}}

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]].

{{tip|Copy & paste the examples into your [[Nasal Console]] and execute them to see what they do.|width=70%}}

== Core library functions ==
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:
* http://plausible.org/nasal/lib.html ([http://web.archive.org/web/20101010094553/http://plausible.org/nasal/lib.html archive])
* {{simgear file|simgear/nasal/lib.c}} ([http://sourceforge.net/p/flightgear/simgear/ci/next/log/?path=/simgear/nasal/lib.c history])

=== append() ===
{{Nasal doc
|syntax = append(vector, element[, element[, ...]]);
|source = {{simgear file|simgear/nasal/lib.c|l=45|t=Source}}
|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.
|param1 = vector
|param1text = The vector to which the arguments will be appended.
|param2 = element
|param2text = An element to be added to the vector.
|example1 =
var vector = [1, 2, 3]; # Initialize the vector
append(vector, 4); # Append the number 4 to the end of the vector
debug.dump(vector); # Print the contents of the vector
|example2 =
var vector = [1, 2, 3]; # Initialize the vector
append(vector, 4, 5, 6); # Append the numbers 4, 5, and 6 to the end of the vector
debug.dump(vector); # Print the contents of the vector
}}

=== bind() ===
{{Nasal doc
|syntax = bind(function, locals[, outer_scope]);
|source = {{simgear file|simgear/nasal/lib.c|l=638|t=Source}}
|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.
|param1 = function
|param1text = Function to evaluate.
|param2 = locals
|param2text = Hash containing values that will become the namespace (first closure) for the function.
|param3 = outer_scope
|param3text = Optional function which is bound to the next closure. This can be bound to yet another, making a linked list.
|example1 = # This is a namespace/hash with a single member, named "key," which is initialized to 12
var Namespace = {
key: 12
};

# This is different namespace/hash containing a function
# dividing a variable "key" (which is unavailable/nil in this namespace) by 2
var AnotherNamespace = {
ret: func {
key /= 2;
}
};

# To see that key is not available, try to call AnotherNamespace.ret() first
call(AnotherNamespace.ret, [], nil, nil, var errors = []);
if(size(errors)){
print("Key could not be divided/resolved!");
debug.printerror(errors);
}

# Associate the AnotherNamespace.ret() function with the first namespace
# so that "key" is now available
var function = bind(AnotherNamespace.ret, Namespace);

# Invoke the new function
function();

# Print out the value of Namespace.key
# It was changed to 12 from 6 by AnotherNamespace.ret()
print(Namespace.key);
}}

=== call() ===
{{Nasal doc
|syntax = call(func[, args[, me[, locals[, error]]]);
|source = {{simgear file|simgear/nasal/lib.c|l=376|t=Source}}
|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.
|param1 = func
|param1text = Function to execute.
|param2 = args
|param2text = Vector containing arguments to give to the called function.
|param3 = me
|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).
|param4 = locals
|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.
|param5 = error
|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}}.
|example1 =
# prints "Called from call()"
call(func {
print("Called from call()");
});
|example2 =
# prints "a = 1 : b = 2
call(func(a, b){
print("a = ", a, " : b = ", b);
},
[1, 2]
);
|example3 =
var Hash = {
new: func {
var m = { parents: [Hash] };

m.el1 = "string1";
m.el2 = "string2";

return m;
}
};

# prints "me.el1 = string1", then "me.el2 = string2" on the next line
call(func(a, b){
print("me.el", a, " = ", me["el" ~ a]);
print("me.el", b, " = ", me["el" ~ b]);
},
[1, 2],
Hash.new()
);
|example4 =
# prints the value of math.pi
call(func {
print(pi);
}, nil, nil,
math
);
|example5 =
call(func {
print(math.ip); # math.ip doesn't exist
}, nil, nil, nil,
var errs = []
);
debug.printerror(errs); # The error is caught and printed using debug.printerror()
}}

=== caller() ===
{{Nasal doc
|syntax = caller([level]);
|source = {{simgear file|simgear/nasal/lib.c|l=540|t=Source}}
|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 '''[0]''' a hash of local variables, '''[1]''' the function object, '''[2]''' the full source file name (incl. path) and '''[3]''' the line number.
|param1 = level
|param1text = Optional integer specifying the stack level to return a result from. Defaults to 1 (i.e. the caller of the currently executing function).
|example1 =
var myFunction = func(a, b) {
debug.dump(caller(0)[0]); # prints a hash of local variables, including arguments a and b
return 2 * 2;
};

print("2 x 2 = ", myFunction(2, 2));
|example2 =
var get_arg_value = func() {
print("Argument to myFunc = ", caller(1)[0]['a']); # print the value of myFunc's single argument, using caller()
};

var myFunc = func(a) {
get_arg_value();
};

myFunc(3);
|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: true, zindex: nil }</code>.
|example3 =
var MapStructure_selfTest = func() {
var temp = {};
temp.dlg = canvas.Window.new([600, 400], "dialog");
temp.canvas = temp.dlg.createCanvas().setColorBackground(1, 1, 1, 0.5);
temp.root = temp.canvas.createGroup();

var testMap = temp.root.createChild("map");
testMap.setController("Aircraft position");
testMap.setRange(25); # TODO: implement zooming/panning via mouse/wheel here, for lack of buttons :-/
testMap.setTranslation(
temp.canvas.get("view[0]") / 2,
temp.canvas.get("view[1]") / 2,
);

var r = func(name, vis = true, zindex = nil) {
return caller(0)[0];
}

# TODO: we'll need some z-indexing here, right now it's just random
# TODO: use foreach/keys to show all layers in this case by traversing SymbolLayer.registry directly ?
# maybe encode implicit z-indexing for each lcontroller ctor call ? - i.e. preferred above/below order ?
var types = [
r('TFC', false),
r('APT'),
r('DME'),
r('VOR'),
r('NDB'),
r('FIX', false),
r('RTE'),
r('WPT'),
r('FLT'),
r('WXR'),
r('APS'),
];

foreach (var type; types) {
testMap.addLayer(
factory: canvas.SymbolLayer,
type_arg: type.name,
visible: type.vis,
priority: type.zindex,
);
}
}; # MapStructure_selfTest
}}

=== chr() ===
{{Nasal doc
|syntax = chr(code);
|source = {{simgear file|simgear/nasal/lib.c|l=240|t=Source}}
|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.}}
{{{!}} class="wikitable"
! Code !! Name !! Equivalent to
{{!-}}
{{!}} 10 {{!!}} {{Wikipedia|Newline}} {{!!}} <code>\n</code>
{{!-}}
{{!}} 9 {{!!}} {{Wikipedia|Tab key#Tab characters|Horizontal tab}} {{!!}} <code>\t</code>
{{!-}}
{{!}} 13 {{!!}} {{Wikipedia|Carriage return}} {{!!}} <code>\r</code>
{{!}}}
|param1 = code
|param1text = Integer character code for the desired glyph.
|example1 = print("Code 65 = ", chr(65)); # prints "Code 65 = A"
|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.
|example2 =
for(var i = 0; i <= 255; i += 1){
print("Code ", i, " = >", chr(i), "<");
}
}}

=== closure() ===
{{Nasal doc
|syntax = closure(func[, level]);
|source = {{simgear file|simgear/nasal/lib.c|l=557|t=Source}}
|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'''.
|param1 = func
|param1text = Function to evaluate.
|param2 = level
|param2text = Optional integer specifying the scope level. Defaults to 0 (the namespace of '''func''').
|example1 =
var get_math_e = func {
return e; # return the value of math.e
}

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
debug.dump(closure(myFunction)); # print the namespace of get_math_e

print(myFunction());
}}

=== cmp() ===
{{Nasal doc
|syntax = cmp(a, b);
|source = {{simgear file|simgear/nasal/lib.c|l=169|t=Source}}
|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'''.
|param1 = a
|param1text = First string argument for comparison.
|param2 = b
|param2text = Second string argument for comparison.
|example1 = print(cmp("1", "two")); # prints -1
|example2 = print(cmp("string", "string")); # prints 0
|example3 = print(cmp("one", "2")); # prints 1
|example4 = print(cmp("string1", "string2")); # prints -1
}}

=== compile() ===
{{Nasal doc
|syntax = compile(code[, filename]);
|source = {{simgear file|simgear/nasal/lib.c|l=349|t=Source}}
|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'''.
|param1 = code
|param1text = String containing Nasal code to be compiled.
|param2 = filename
|param2text = Optional string used for error messages/logging. Defaults to <code><compile></code>
|example1 =
var myCode = 'print("hello");';
var helloFunc = compile(myCode, "myCode");
helloFunc();
|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>.
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<PropertyList>

<nasal><![CDATA[
print("You have FlightGear v", getprop("/sim/version/flightgear"));
]]></nasal>

</PropertyList>
</syntaxhighlight>
Now, start FlightGear and execute this code in the [[Nasal Console]].
|example2 =
# Build the path
var FGRoot = getprop("/sim/fg-root");
var filename = "/gui/dialogs/test.xml";
var path = FGRoot ~ filename;

var blob = io.read_properties(path);
var script = blob.getValues().nasal; # Get the nasal string

# Compile the script. We're passing the filename here for better runtime diagnostics
var code = call(func {
compile(script, filename);
}, nil, nil, var compilation_errors = []);

if(size(compilation_errors)){
die("Error compiling code in: " ~ filename);
}

# Invoke the compiled script, equivalent to code();
# We're using call() here to detect errors:
call(code, [], nil, nil, var runtime_errors = []);

if(size(runtime_errors)){
die("Error calling code compiled loaded from: " ~ filename);
}
|example3text = The <code>compile()</code> function also allows you to parse a JSON string into a hash. Simplest example:
|example3 =
var jsonFunc = compile('{"version":"1.2.0","author":{"name":"John"} }');
var json = jsonFunc(); # return hash
logprint(LOG_ALERT, json["version"]); # print "1.2.0"
logprint(LOG_ALERT, json["author"]["name"]); # print "John"
}}

=== contains() ===
{{Nasal doc
|syntax = contains(hash, key);
|source = {{simgear file|simgear/nasal/lib.c|l=249|t=Source}}
|text = Returns 1 (True) if the hash contains the specified key, or 0 (False) if not.
|param1 = hash
|param1text = The hash to search in.
|param2 = key
|param2text = The scalar to be searched for, contained as a key in the hash.
|example1 =
# Initialize a hash
var hash = {
element: "value"
};
print(contains(hash, "element") ? "Yes" : "No"); # This will print "Yes"
print(contains(hash, "element2") ? "Yes" : "No"); # This will print "No"
}}

===contains()===
{{Requires commit|desc=Vector support|details=see {{Merge-request|project=fgdata|id=305}}|commit=ee39abbd3b70c9b6d5e3a1c4ccedddaac1a92b11|repo=Simgear}}
{{Nasal doc
|syntax = contains(vector, item);
|source = {{simgear file|simgear/nasal/lib.c|l=249|t=Source}}
|text = Returns 1 (True) if the vector contains the specified item, or 0 (False) if not.
|param1 = vector
|param1text = The vector to search in.
|param2 = item
|param2text = The object to be searched for in the vector.
|example1 =
# Initialize a vector
var vec = ["element", "foo"];
print(contains(vec, "element") ? "Yes" : "No"); # This will print "Yes"
print(contains(vec, "element2") ? "Yes" : "No"); # This will print "No"
}}

===delete() ===
{{Nasal doc
|syntax = delete(hash, key);
|source = {{simgear file|simgear/nasal/lib.c|l=118|t=Source}}
|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.
|param1 = hash
|param1text = The hash from which to delete the key.
|param2 = key
|param2text = The scalar to be deleted, contained as a key in the hash.
|example1 =
# Initialize the hash
var hash = {
element1: "value1",
element2: "value2"
};
delete(hash, "element1"); # Delete element1
debug.dump(hash); # prints the hash, which is now minus element1
}}

===die()===
{{Nasal doc
|syntax = die(error);
|source = {{simgear file|simgear/nasal/lib.c|l=417|t=Source}}
|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()}}.
|param1 = error
|param1text = String describing the error.
:{{inote|This parameter is technically optional, but it is highly recommended to use it.}}
|example1 =
print("Will print");
die("Don't go any further!");
print("Won't print"); # Will not be printed because die() stops the process
}}

=== find()===
{{Nasal doc
|syntax = find(needle, haystack);
|source = {{simgear file|simgear/nasal/lib.c|l=586|t=Source}}
|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.
|param1 = needle
|param1text = String to search for.
|param2 = haystack
|param2text = String to search in.
|example1 = print(find("c", "abcdef")); # prints 2
|example2 = print(find("x", "abcdef")); # prints -1
|example3 = print(find("cd", "abcdef")); # prints 2
}}

===ghosttype()===
{{Nasal doc
|syntax = ghosttype(ghost);
|source = {{simgear file|simgear/nasal/lib.c|l=336|t=Source}}
|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.
|param1 = ghost
|param1text = Ghost to return a description for.
|example1 = print(ghosttype(airportinfo())); # prints "airport"
}}

===id()===
{{Nasal doc
|syntax = id(object);
|source = {{simgear file|simgear/nasal/lib.c|l=706|t=Source}}
|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.
|param1 = object
|param1text = Can be either of a string, a vector, a hash, a code, a function, or a ghost.
|example1 = print(id("A")); # prints "str:000000001624A590"
}}

===int() ===
{{Nasal doc
|syntax = int(number);
|source = {{simgear file|simgear/nasal/lib.c|l=125|t=Source}}
|text = Returns the integer part of the numeric value of the single argument, or <code>'''nil'''</code> if none exists.
|param1 = number
|param1text = Number or string with just a number in it to return an integer from.
|example1 = print(int(23)); # prints "23"
|example2 = print(int(23.123)); # prints "23"
|example3 = debug.dump(int("string")); # prints "nil"
}}

===keys()===
{{Nasal doc
|syntax = keys(hash);
|source = {{simgear file|simgear/nasal/lib.c|l=36|t=Source}}
|text = Returns a vector containing the list of keys found in the single hash argument.
|param1 = hash
|param1text = The hash to return the keys from.
|example1 =
# Initialize a hash
var hash = {
element1: "value",
element2: "value"
};
debug.dump(keys(hash)); # print the vector
}}

===left()===
{{Nasal doc
|syntax = left(string, length);
|source = {{simgear file|simgear/nasal/lib.c|l=214|t=Source}}
|version = 2.12
|commit = {{simgear commit|bd7163|t=commit}}
|text = Returns a substring of '''string''', starting from the left.
|param1 = string
|param1text = String to return part of.
|param2 = length
|param2text = Integer specifying the length of the substring to return.
|example1 = print(left("string", 2)); # prints "st"
}}

=== num()===
{{Nasal doc
|syntax = num(number);
|source = {{simgear file|simgear/nasal/lib.c|l=149|t=Source}}
|text = Returns the numerical value of the single string argument, or <code>'''nil'''</code> if none exists.
|param1 = number
|param1text = String with just a number in it to return a number from.
|example1 = print(num("23")); # prints "23"
|example2 = print(num("23.123")); # prints "23.123"
|example3 = debug.dump(num("string")); # prints "nil"
}}

===pop()===
{{Nasal doc
|syntax = pop(vector);
|source = {{simgear file|simgear/nasal/lib.c|l=85|t=Source}}
|text = Removes and returns the last element of the single vector argument, or <code>'''nil'''</code> if the vector is empty.
|param1 = vector
|param1text = Vector to remove an element from.
|example1 =
var vector = [1, 2, 3];
pop(vector);
debug.dump(vector); # prints "[1, 2]"
|example2 =
var vector = [1, 2, 3];
debug.dump(pop(vector)); # prints "3"
|example3 =
var vector = [];
debug.dump(pop(vector)); # prints "nil"
}}

=== range() ===
{{Nasal doc
|syntax = range([start, ]stop[, step]);
|source = {{simgear file|simgear/nasal/lib.c|l=756|t=Source}}
|text = Creates a vector of numbers starting from <code>start</code> (default 0) up to but not including <code>stop</code>, incremented by <code>step</code> (default 1). Note: To specify <code>step</code>, you must also provide <code>start</code>; otherwise the second argument is interpreted as <code>stop</code>.
|param1 = start
|param1text = Optional. The starting number of the sequence. Defaults to 0 if omitted. Required if you want to specify <code>step</code>.
|param2 = stop
|param2text = Required. The number at which to stop the sequence (not included).
|param3 = step
|param3text = Optional. The increment between each number in the sequence. Defaults to 1. Only valid if <code>start</code> is also specified.
|example1 =
var vec = range(5); # Creates a vector [0, 1, 2, 3, 4]
var vec = range(2, 5); # Creates a vector [2, 3, 4]
var vec = range(0, 10, 2); # Creates a vector [0, 2, 4, 6, 8]
var vec = range(0, 0); # Creates an empty vector []
var vec = range(0, 1); # Creates a vector [0]
}}

=== remove() ===
{{Nasal doc
|syntax = remove(vector, value);
|source = {{simgear file|simgear/nasal/lib.c|l=53|t=Source}}
|text = Removes all elements equal to the given value from a vector and returns the modified vector.
|param1 = vector
|param1text = The vector from which elements are to be removed.
|param2 = value
|param2text = A value to remove from the vector.
|example1 =
var vector = [1, 2, 3]; # Initialize the vector.
remove(vector, 2); # Remove the value 2 from the vector.
debug.dump(vector); # Print the contents of the vector: "[1, 3]".
|example2 =
var vector = ["text", "text", "text"]; # Initialize the vector.
remove(vector, "text"); # Remove the value "text" from the vector.
debug.dump(vector); # Print the contents of the vector: "[]".
}}

=== removeat() ===
{{Nasal doc
|syntax = removeat(vector, index);
|source = {{simgear file|simgear/nasal/lib.c|l=72|t=Source}}
|text = Removes the element at the specified index from the vector and returns it.
|param1 = vector
|param1text = The vector from which the element will be removed.
|param2 = index
|param2text = Index of the item to be deleted.
|example1 =
var vector = [1, 2, 3]; # Initialize the vector.
removeat(vector, 0); # Remove the index 0 from the vector.
debug.dump(vector); # Print the contents of the vector: "[2, 3]".
}}

===right()===
{{Nasal doc
|syntax = right(string, length);
|source = {{simgear file|simgear/nasal/lib.c|l=226|t=Source}}
|version = 2.12
|commit = {{simgear commit|bd7163|t=commit}}
|text = Returns a substring of '''string''', starting from the right.
|param1 = string
|param1text = String to return part of.
|param2 = length
|param2text = Integer specifying the length of the substring to return.
|example1 = print(right("string", 2)); # prints "ng"
}}

=== setsize()===
{{Nasal doc
|syntax = setsize(vector, size);
|source = {{simgear file|simgear/nasal/lib.c|l=91|t=Source}}
|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.
|param1 = vector
|param1text = The vector to be operated on.
|param2 = size
|param2text = The desired size of the vector in number of entries.
|example1 =
var vector = [1, 2, 3]; # Initialize a vector
setsize(vector, 4);
debug.dump(vector); # print the vector "[1, 2, 3, nil]"
|example2 =
var vector = [1, 2, 3]; # Initialize a vector
setsize(vector, 2);
debug.dump(vector); # print the vector "[1, 2]"
}}

===size()===
{{Nasal doc
|syntax = size(object);
|source = {{simgear file|simgear/nasal/lib.c|l=26|t=Source}}
|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>.
|param1 = object
|param1text = Object to find the size of. Must be a string, a vector or a hash.
|example1 =
var string = "string";
print(size(string)); # prints "6"
|example2 =
var vector = [1, 2, 3];
print(size(vector)); # prints "3"
|example3 =
var hash = {
element1: "value1",
element2: "value2",
element3: "value3"
};
print(size(hash)); # prints "3"
}}

=== sort()===
{{Nasal doc
|syntax = sort(vector, function);
|source = {{simgear file|simgear/nasal/lib.c|l=678|t=Source}}
|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.
|param1 = vector
|param1text = Input vector to sort.
|param2 = function
|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.
{{{!}} class="wikitable"
! Return value !! Meaning
{{!-}}
{{!}} less than 0 {{!!}} first argument should go before second argument
{{!-}}
{{!}} 0 {{!!}} first argument equals second argument
{{!-}}
{{!}} greater than 0 {{!!}} first argument should go after second argument
{{!}}}

|example1text = This example sorts elements from smallest to greatest.
|example1 =
var sort_rules = func(a, b) {
if (a < b) {
return -1; # A should before b in the returned vector
} elsif (a == b) {
return 0; # A is equivalent to b
} else {
return 1; # A should after b in the returned vector
}
}
debug.dump(sort([3, 2, 5, 6, 4, 1], sort_rules)); # prints "[1, 2, 3, 4, 5, 6]"
|example2text = This example sorts elements from greatest to smallest.
|example2 =
# Outputs the elements in reverse order (greatest to smallest)
var sort_rules = func(a, b) {
if (a < b) {
return 1; # -1 in the above example
} elsif (a == b) {
return 0;
} else {
return -1; # 1 in the above example
}
}
debug.dump(sort([3, 2, 5, 6, 4, 1], sort_rules)); # prints "[6, 5, 4, 3, 2, 1]"
|example3text = This example sorts a vector of strings (runways for example) from smallest to greatest.
|example3 =
var runways = ["09R", "27R", "26L", "09L", "15"];
var rwy = sort(runways, func(a, b) cmp(a, b));
debug.dump(rwy); # prints ['09L', '09R', '15', '26L', '27R']
}}

=== split()===
{{Nasal doc
|syntax = split(delimiter, string);
|source = {{simgear file|simgear/nasal/lib.c|l=596|t=Source}}
|text = Splits the input string into a vector of substrings bounded by occurrences of the delimiter substring. See [[Nasal_library/string#string.join(sep,list)|string.join()]].
|param1 = delimiter
|param1text = String that will split the substrings in the returned vector.
|param2 = string
|param2text = String to split up.
|example1 = debug.dump(split("cd", "abcdef")); # prints "['ab', 'ef']"
|example2 = debug.dump(split(".", "3.2.0")); # prints "[3, 2, 0]"
|example3 = debug.dump(split("/", "path/to/file")); # prints "['path', 'to', 'file']"
}}

===sprintf()===
{{Nasal doc
|syntax = <nowiki>sprintf(format[, arg[, arg, [...]]]);</nowiki>
|source = {{simgear file|simgear/nasal/lib.c|l=491|t=Source}}
|text = Creates and returns a string formatted using ANSI C {{func link|vsnprintf()|link=http://en.cppreference.com/w/c/io/vfprintf}} <ref>
{{Cite web
|url = http://sourceforge.net/p/flightgear/simgear/ci/next/tree/simgear/nasal/lib.c#l308
|title = fgdata/simgear/simgear/nasal/lib.c, line 308
|accessdate = October 2015
}}
</ref>. Below is a table of supported format specifiers.
{{{!}} class="wikitable" width="75%"
{{!}}+ %[flags][width][.precision]specifier
! colspan="2" {{!}} Flags
{{!-}}
! Flag !! Output
{{!-}}
{{!}} <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.
{{!-}}
{{!}} ''space'' {{!!}} Prefixes non-signed numbers with a space.
{{!-}}
{{!}} <code>-</code> {{!!}} Left-align the output of this placeholder (the default is to right-align the output) when the width option is specified.
{{!-}}
{{!}} <code>0</code> {{!!}} Use 0 instead of spaces to pad a field when the width option is specified.
{{!-}}
{{!}} <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.
{{!-}}
! colspan="2" {{!}} Width
{{!-}}
{{!}} 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.
{{!-}}
! colspan="2" {{!}} Precision
{{!-}}
{{!}} colspan="2" {{!}} Integer preceded by a dot specifying the number of decimal places to be written.
{{!-}}
! colspan="2" {{!}} Specifiers
{{!-}}
! Specifier !! Output
{{!-}}
{{!}} <code>d</code>, <code>i</code> {{!!}} Signed decimal number.
{{!-}}
{{!}} <code>s</code> {{!!}} A string
{{!-}}
{{!}} <code>%</code> {{!!}} Percent (%) character.
{{!-}}
{{!}} <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.
{{!-}}
{{!}} <code>o</code> {{!!}} Unsigned integer as an octal number.
{{!-}}
{{!}} <code>u</code> {{!!}} Unsigned decimal integer.
{{!-}}
{{!}} <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.
{{!-}}
{{!}} <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.
{{!-}}
{{!}} <code>f</code> {{!!}} Floating-point number, in fixed decimal notation, by default with 6 decimal places.
{{!-}}
{{!}} <code>F</code> {{!!}} Appears to be available<ref>
{{Cite web
|url = http://sourceforge.net/p/flightgear/simgear/ci/next/tree/simgear/nasal/lib.c#l389
|title = fgdata/simgear/simgear/nasal/lib.c, line 389
|accessdate = October 2015
}}
</ref>, but doesn't work.
{{!-}}
{{!}} <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.
{{!}}}

|param1 = format
|param1text = String specifying the format. Can be used with or without a format specifiers. See below for examples.
|param2 = arg
|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.

|example1 = print(sprintf("%i", 54)); # prints "54"
|example2 = print(sprintf("Pi = %+.10f", math.pi)); # prints "Pi = +3.1415926536"
|example3 =
print(sprintf("%6d", 23)); # prints " 23"
print(sprintf("%06d", 23)); # prints "000023"
|example4 =
var FGVer = getprop("/sim/version/flightgear");
print(sprintf("You have FlightGear v%s", FGVer)); # prints "You have FlightGear v<your version>"
|example5 =
print(sprintf("Hexadecimal 100000 = %X", 100000)); # prints "Hexadecimal 100000 = 186A0"
print(sprintf("Hexadecimal 100000 = %x", 100000)); # prints "Hexadecimal 100000 = 186a0"
|example6 = print(sprintf("Code 65 is %c", 65)); # prints "Code 65 is A"
|example7 =
print(sprintf("%e", 54)); # prints "5.400000e+001"
print(sprintf("%E", 54)); # prints "5.400000E+001"
|example8 = print(sprintf("%o", 54)); # prints "66"
|example9 = print(sprintf("50%% of 100 is %i", 100 / 2)); # prints "50% of 100 is 50"
|example10 =
print(sprintf("%.2f", 1.4)); # prints "1.40"
print(sprintf("%.1f", 1.4)); # prints "1.4"
print(sprintf("% 4.1f", 1.4)); # prints " 1.4"
print(sprintf("%04.1f", 1.4)); # prints "01.4"
print(sprintf("% 6.1f", 1.4)); # prints " 1.4"
print(sprintf("%06.1f", 1.4)); # prints "0001.4"
}}

===str()===
{{Nasal doc
|syntax = str(value);
|source = {{simgear file|simgear/nasal/lib.c|l=186|t=Source}}
|text = Convert given value (scalar) to string. If <code>value</code> is a number, it will be converted to a string. If <code>value</code> is a string, the same string will be returned. If <code>value</code> is not a scalar (hash, vector, nil), <code>nil</code> will be returned.
|param1 = value
|param1text = The value to convert to string.
|example1 =
var result = str(12); # result is a string "12"
var result = str(12.5); # result is a string "12.5"
var result = str("12.5"); # result is a string "12.5"
var result = str([1, 2]); # result is a nil
var result = str({ x: 0 }); # result is a nil
var result = str(nil); # result is a nil
}}

===streq()===
{{Nasal doc
|syntax = streq(a, b);
|source = {{simgear file|simgear/nasal/lib.c|l=164|t=Source}}
|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.}}
|param1 = a
|param1text = First argument for testing equality.
|param2 = b
|param2text = Second argument for testing equality.
|example1 = print(streq("0", "0")); # prints "1" (True)
|example2 =
print(0 == 0.0); # prints "1" (True)
print(streq("0", "0.0")); # prints "0" (False)
}}

===substr()===
{{Nasal doc
|syntax = substr(string, start [, length]);
|source = {{simgear file|simgear/nasal/lib.c|l=194|t=Source}}
|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).
|param1 = string
|param1text = String to return a substring from.
|param2 = start
|param2text = Integer specifying the start of a substring. Negative values specify a position from the end of the string.
|param3 = length
|param3text = Optional argument specifying the length of the substring. Defaults to the end of the string.
|example1 = print(substr("abcde", 1, 3)); # prints "bcd"
|example2 = print(substr("abcde", 1)); # prints "bcde"
|example3 = print(substr("abcde", 2, 1)); # prints "c"
|example4 = print(substr("abcde", -2)); # prints "de"
|example5 = print(substr("abcde", -3, 2)); # prints "cd"
}}

===subvec()===
{{Nasal doc
|syntax = subvec(vector, start[, length]);
|source = {{simgear file|simgear/nasal/lib.c|l=98|t=Source}}
|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).
|param1 = vector
|param1text = The vector to take the sub-vector from.
|param2 = start
|param2text = The starting point of the sub-vector within the given vector.
|param3 = length
|param3text = Optional argument specifying the length of the sub-vector, from the starting point.
'''Notes:'''
* Omitting the ''vector'' and ''start'' arguments is not an error (possibly it should be) but the return value is ''nil''.
* A negative ''start'' argument ''is'' an error. This seems wrong. Perhaps the language designer could comment.
* A value of ''start'' greater than ''size(vector)'' causes an error. A value equal to ''size(vector)'' returns an empty vector.
* 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.
|example1 =
var vector = [1, 2, 3];
debug.dump(subvec(vector, 0)); # prints "[1, 2, 3]"
|example2 =
var vector = [1, 2, 3];
debug.dump(subvec(vector, 1)); # prints "[2, 3]"
|example3 =
var vector = [1, 2, 3];
debug.dump(subvec(vector, 1, 1)); # prints "[2]"
}}

=== typeof()===
{{Nasal doc
|syntax = typeof(object);
|source = {{simgear file|simgear/nasal/lib.c|l=287|t=Source}}
|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.
|param1 = object
|param1text = Object to return the type of.
|example1 =
var object = nil;
print(typeof(object)); # prints "nil"
|example2 =
var object = "Hello world!";
print(typeof(object)); # prints "scalar"
|example3 =
var object = math.pi;
print(typeof(object)); # prints "scalar"
|example4 =
var object = [1, 2, 3];
print(typeof(object)); # prints "vector"
|example5 =
var object = {};
print(typeof(object)); # prints "hash"
|example6 =
var object = func {};
print(typeof(object)); # prints "func"
|example7 =
var object = airportinfo();
print(typeof(object)); # prints "ghost"
}}



==Extension functions==
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:
*{{flightgear file|src/Scripting/NasalPositioned.cxx}}
*{{flightgear file|src/Scripting/NasalSys.cxx}}
*{{fgdata file|Nasal/globals.nas}}

===abort()===
{{Nasal doc
|syntax = abort();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=565|t=Source}}
|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).
|example1text = This example will immediately stop FlightGear with an error, such as "FlightGear has stopped working."
|example1 = abort();
|example2text = For exiting FlightGear in a better way, please use the following code:
|example2 = fgcommand("exit");
}}

=== abs() ===
{{Nasal doc
|syntax = abs(number);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = This simple function returns the {{wikipedia|absolute value|noicon=1}} of the provided number.
|param1 = number
|param1text = This argument is required and should be a number.
|example1 = print(abs(1)); # prints "1"
|example2 = print(abs(-1)); # prints "1"
}}

===aircraftToCart() ===
This new function in FG 2017.2.1 takes coordinates in aircraft structural coordinate system, and translate them into geocentric coordinates.
Example for (5,6,7):
<syntaxhighlight lang="nasal">
var pos = aircraftToCart({x: -5, y: 6, z: -7});
var coord = geo.Coord.new();
coord.set_xyz(pos.x, pos.y, pos.z);
</syntaxhighlight>
Notice: x and z is inverted sign on purpose.
if you want lat. lon, alt from that, just call: (degrees and meters)

<syntaxhighlight lang="nasal">
coord.lat()
coord.lon()
coord.alt()
</syntaxhighlight>

===addcommand() ===
{{Nasal doc
|syntax = addcommand(name, code);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=659|t=Source}}
|version = 2.12
|commit = {{flightgear commit|7b663c|t=commit}}
|text = {{see also|Howto:Add new fgcommands to FlightGear}}

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.
|param1 = name
|param1text = This will become the name of the new fgcommand. Must be a string.
|param2 = code
|param2text = The code that will be executed when the fgcommand is run. Must be a function.
|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.
|example1 = addcommand("myFGCmd", func(node) {
print("fgcommand 'myFGCmd' has been run.");
props.dump( node );
});
fgcommand("myFGCmd", props.Node.new({foo:1, bar:2}) );
|example2text = This example demonstrates how parameters are defined in a new fgcommand.
|example2 = addcommand("myFGCmd", func(node){
print(node.getNode("number").getValue()); # prints the value of "number," which is 12
});
fgcommand("myFGCmd", props.Node.new({"number": 12}));
}}

===airportinfo()===
{{Nasal doc
|syntax = airportinfo();
airportinfo(type);
airportinfo(id);
airportinfo(lat, lon[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1024|t=Source}}
|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:
* '''parents''': A vector containing a hash of various functions to access information about the runway. These functions are:
** '''findBestRunwayForPos()''' return runway as ghost by given geo position, e.g. <code>var rwy = airportinfo().findBestRunwayForPos(geo.aircraft_position());</code>.
** '''runway()''' return runway as ghost by runway ID, e.g. <code>var rwy = airportinfo().runway("18R");</code>.
** '''runwaysWithoutReciprocals()''' return vector of runways as ghost.
** '''helipad()''' return helipad as ghost by helipad ID, e.g. <code>var heli = airportinfo().helipad("H19");</code>.
** '''tower()''' return hash with <code>lat</code>, <code>lon</code>, <code>elevation</code> fields.
** '''comms()''' return vector of hashes, each hash with <code>frequency</code> and <code>ident</code> fields.
** '''sids()''' return vector of strings with SID IDs.
** '''stars()''' return vector of strings with STAR IDs.
** '''getApproachList()''' return vector of string with approaches.
** '''parking()''' return vector of hashes, each hash with <code>lat</code>, <code>lon</code>, <code>elevation</code>, <code>name</code> fields.
** '''getSid()''' return SID as ghost, e.g. <code>var sid = airportinfo().getSid("SA1A");</code>.
** '''getStar()''' return STAR as ghost, e.g. <code>var star = airportinfo().getStar("KEILA1");</code>.
** '''getIAP()''' return IAP as ghost, e.g. <code>var iap = airportinfo().getIAP("ILS02");</code>.
** '''getApproach()''' return approach as ghost, e.g. <code>var approach = airportinfo().getApproach("ILS02");</code>.
** '''tostring()''' just return string "an airport ICAO".
** See also {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1902}}.
* '''lon''': Longitude of the location.
* '''lat''': Latitude of the location.
* '''has_metar''': True or false depending whether the airport has a [[METAR]] code defined for it.
* '''elevation''': Elevation of the location in metres.
* '''id''': ICAO code of the airport (or ID of the seaplane base/heliport).
* '''name''': Name of the airport/heliport/seaplane base.
* '''runways'''
** '''<runway name>'''
*** '''id''': Name of runway.
*** '''lat''': Latitude of the runway.
*** '''lon''': Longitude of the runway.
*** '''heading''': True heading of the runway.
*** '''length''': Length of the runway in metres.
*** '''width''': Width of the runway in metres.
*** '''surface''': Runway surface type.
*** '''threshold''': Length of the runway's {{wikipedia|displaced threshold}} in metres. Will return 0 if there is none.
*** '''stopway''': Length of the runway's stopway (the area before the threshold) in metres. Will return 0 if there is none.
*** '''reciprocal''': <code>runway</code> ghost of the reciprocal runway.
*** '''ils_frequency_mhz''': ILS frequency in megahertz.
*** '''ils''': <code>navaid</code> ghost of the ILS transmitter.
* '''helipads'''
** '''<helipad name>'''
*** '''id''': Name of helipad.
*** '''lat''': Latitude of the helipad.
*** '''lon''': Longitude of the helipad.
*** '''heading''': True heading of the helipad.
*** '''length''': Length of the helipad in metres.
*** '''width''': Width of the helipad in metres.
*** '''surface''': Helipad surface type.
* '''taxiways'''
** '''<taxiway name>'''
*** '''id''': Name of taxiway.
*** '''lat''': Latitude of the taxiway.
*** '''lon''': Longitude of the taxiway.
*** '''heading''': Heading of the taxiway.
*** '''length''': Length of the taxiway in metres.
*** '''width''': Width of the taxiway in metres.
*** '''surface''': Taxiway surface type.

Information is extracted in the same way as accessing members of a Nasal hash. For example:
<syntaxhighlight lang="nasal">
# prints to lengths of the runways of the nearest airport in feet and metres
var info = airportinfo();
print("-- Lengths of the runways at ", info.name, " (", info.id, ") --");
foreach(var rwy; keys(info.runways)){
print(rwy, ": ", math.round(info.runways[rwy].length * M2FT), " ft (", info.runways[rwy].length, " m)");
}
</syntaxhighlight>

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.
|param1 = id
|param1text = The {{wikipedia|International Civil Aviation Organization airport code|ICAO code|noicon=1}} of an airport to retrieve information about.
|param2 = type
|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).
: {{inote|Running this function without any parameters is equivalent to this:
: <syntaxhighlight lang="nasal">
airportinfo("airport");
</syntaxhighlight>
}}
|param3 = lat ''and'' lon
|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.
|example1 = var info = airportinfo();
print("Nearest airport: ", info.name, " (", info.id, ")"); # prints the name and ICAO code of the nearest airport
|example2 = var info = airportinfo("heliport");
print("Elevation of the nearest heliport: ", math.round(info.elevation * M2FT), " ft"); # prints the elevation and name of the nearest heliport
|example3 = var info = airportinfo("KSQL");
print("-- Runways of ", info.name, " (", info.id, "): --");
foreach(var rwy; keys(info.runways)) {
print(rwy); # prints the runways of KSQL
}
|example4 = var info = airportinfo(37.81909385, -122.4722484);
print("Coordinates of the nearest airport: ", info.lat, ", ", info.lon); # print the name and ICAO of the nearest airport to the Golden Gate Bridge
|example5 = var info = airportinfo(37.81909385, -122.4722484, "seaport");
print("Nearest seaplane base: ", info.name, " (", info.id, ")"); # print the name and ID of the nearest seaplane base to the Golden Gate Bridge
|example6text = This example prints the all information from an <code>airportinfo()</code> call.
|example6 = var info = airportinfo("KSFO");
print(info.name);
print(info.id);
print(info.lat);
print(info.lon);
print(info.has_metar);
print(info.elevation);
foreach(var rwy; keys(info.runways)){
print("-- ", rwy, " --");
print(info.runways[rwy].lat);
print(info.runways[rwy].lon);
print(info.runways[rwy].length);
print(info.runways[rwy].width);
print(info.runways[rwy].heading);
print(info.runways[rwy].stopway);
print(info.runways[rwy].threshold);
<nowiki>}</nowiki>
}}

===airwaysRoute() ===
{{Nasal doc
|syntax = airwaysRoute(start, end[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1933|t=Source}}
|text = {{see also|Nasal Flightplan}}
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.
|param1 = start
|param1text = Start waypoint, in the form of a waypoint ghost, such as that provided by {{func link|flightplan()}}.
|param2 = end
|param2text = Same as above.
|param3 = type
|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."
|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.
|example1 = var fp = flightplan();
var start = fp.getWP(0);
var end = fp.getWP(fp.getPlanSize() - 1);
var rt = airwaysRoute(start, end);
foreach(var wp; rt){
print(wp.wp_name); # print the waypoints in the computed route
}
|example2text = Exactly the same as above, but computes a low level path.
|example2 = var fp = flightplan();
var start = fp.getWP(0);
var end = fp.getWP(fp.getPlanSize() - 1);
var rt = airwaysRoute(start, end, "lowlevel");
foreach(var wp; rt){
print(wp.wp_name); # print the waypoints in the computed route
<nowiki>}</nowiki>
}}

===airway()===

{{Nasal doc
|syntax = airway(ident [, pos]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2644|t=Source}}
|text = {{see also|Nasal Flightplan}}
This function returns a ghost containing an airway of a specified id.
|param1 = ident
|param1text = a Positioned ghost (leg, navaid, airport) and so on, passed to the search function.
|param2 = pos
}}

===assert()===
{{Nasal doc
|syntax = assert(condition[, message]);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|version = 3.2
|commit = {{fgdata commit|8b16a7|t=commit}}
|text = Returns either true if the condition evaluates as true, or aborts with a {{func link|die()}} call, which can be customised.
|param1 = condition
|param1text = Condition to evaluate.
|param2 = message
|param2text = Optional message that will be used in any {{func link|die()}} call. Defaults to "assertion failed!"
|example1 = var a = 1;
var b = 2;
print(assert(a < b)); # prints "1" (true)
|example2 = var a = 1;
var b = 2;
assert(a > b, 'a is not greater than b'); # aborts with a custom error message
}}

===carttogeod()===
{{Nasal doc
|syntax = carttogeod(x, y, z);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=945|t=Source}}
|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>
|param1 = x
|param1text = Mandatory x-axis value, in metres.
|param2 = y
|param2text = Mandatory y-axis value, in metres.
|param3 = z
|param3text = Mandatory z-axis value, in metres.
|example1 = var (lat, lon, alt) = carttogeod(6378137, 0, 0); # point is the intersection of the prime meridian and equator.
print("Latitude: ", lat); # prints lat, lon and alt, which are all zero, see above
print("Longitude: ", lon);
print("Altitude: ", alt);
}}

===cmdarg()===
{{Nasal doc
|private = _cmdarg()
|syntax = cmdarg();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=513|t=Part 1}} {{!}} {{fgdata file|Nasal/globals.nas|t=Part 2}}
|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.
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:
* Bindings: This is needed so that the value of a joystick's axis can be accessed internally.
* 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).
* 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.
* 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>

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.

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.
|example1 = fgcommand("dialog-show", {"dialog-name": "cmdarg-demo"});
|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.
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>

<PropertyList>

<name>cmdarg-demo</name>
<layout>vbox</layout>

<text>
<label>Click "Close" to activate the demonstration (a message in the console).</label>
</text>

<button>
<legend>Close</legend>
<binding>
<command>nasal</command>
<script>print("Button binding root: '" ~ cmdarg().getPath() ~ "'");</script>
</binding>
<binding>
<command>dialog-close</command>
</binding>
</button>

</PropertyList>
</syntaxhighlight>
|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!"
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>

<PropertyList>

<name>cmdarg-demo</name>
<layout>vbox</layout>

<text>
<label>Click "Click me!" to activate the demonstration (the button's label will change).</label>
</text>

<button>
<legend>Click me!</legend>
<binding>
<command>nasal</command>
<script>change_label();</script>
</binding>
</button>

<button>
<legend>Close</legend>
<binding>
<command>dialog-close</command>
</binding>
</button>

<nasal>
<open><![CDATA[
var dlg_root = cmdarg();
var dlg_name = {"dialog-name": "cmdarg-demo"};
var change_label = func {
dlg_root.getNode("button[0]/legend").setValue("I've been changed!");
fgcommand("dialog-close", dlg_name);
fgcommand("dialog-show", dlg_name);
}
]]></open>
</nasal>

</PropertyList>
</syntaxhighlight>
|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]].
}}

===courseAndDistance()===
{{Nasal doc
|syntax = courseAndDistance(to);
courseAndDistance(from, to);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1668|t=Source}}
|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:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object with geodetic coordinates (cartesian coordinates will not be accepted)
|param1 = from
|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.
|param2 = to
|param2text = Like the first parameter, but defines the second point.
|example1text = This example demonstrates the usage of the function with the <code>airport</code> ghost type.
|example1 = var from = airportinfo("KSFO");
var to = airportinfo("KSQL");
var (course, dist) = courseAndDistance(from, to);
print(course); # prints course from KSFO to KSQL
print(dist); # prints distance in nm from KSFO to KSQL
|example2text = This example demonstrates the usage of the function with hashes containing ''lat'' and ''lon''.
|example2 = var from = {lat: 0, lon: 0};
var to = {lat: 1, lon: 1};
var (course, dist) = courseAndDistance(from, to);
print(course);
print(dist);
|example3text = This example demonstrates usage of a geo.Coord object.
|example3 = var from = geo.Coord.new().set_latlon(0, 0);
var to = geo.Coord.new().set_latlon(1, 1);
var (course, dist) = courseAndDistance(from, to);
print(course);
print(dist);
|example4text = This example demonstrates usage of differing parameter types.
|example4 = var from = airportinfo("KSFO");
var to = geo.Coord.new().set_latlon(0, 0);
var (course, dist) = courseAndDistance(from, to);
print(course);
print(dist);
|example5text = The same as above, but the other way round.
|example5 = var to = {lat: 1, lon: 1};
var (course, dist) = courseAndDistance(0, 0, to);
print(course);
print(dist);
|example6text = Usage of just one parameter.
|example6 = var dest = airportinfo("KSQL");
var (course, dist) = courseAndDistance(dest);
print("Turn to heading ", math.round(course), ". You have ", sprintf("%.2f", dist), " nm to go");
}}

===createFlightplan()===
{{Nasal doc
|syntax = createFlightplan(path);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2331|t=Source}}
|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.
|param1 = path
|param1text = Optional parameter defining the file from which a flightplan will be populated.
|example1 =
var path = getprop("/sim/fg-home") ~ "/Export/test.fgfp";
var flightplan = createFlightplan(path);
debug.dump(flightplan);
}}

===createDiscontinuity()===
{{Nasal doc
|syntax = createDiscontinuity();
|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.
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2045|t=Source}}
|version = 2016.1
|commit = {{flightgear commit|caead6|t=commit}}
}}
===createViaTo()===
{{Nasal doc
|syntax = createViaTo(airway, waypoint);
|text = Returns a <code>waypoint</code> ghost object. It represents a route "via '''airway''' to '''waypoint'''".
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2009|t=Source}}
|version = 2016.1
|commit = {{flightgear commit|caead6|t=commit}}
|param1 = airway
|param1text = The name of an airway.
|param2 = waypoint
|param2text = Must be in the airway and one of:
* The name of a waypoint.
* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, or <code>fix</code> ghost object.
}}
===createWP()===
{{Nasal doc
|syntax = createWP(pos, name[, flag]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1964|t=Source}}
|text = Creates a new waypoint ghost object.
|param1 = pos
|param1text = Dictates the position of the new waypoint. It can be one of the following:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. See example 4 below.
|param2 = name
|param2text = String that will become the name of the new waypoint.
|param3 = flag
|param3text = Optional string that will tell FlightGear what type of waypoint it is. Must be one of "sid," "star," "approach," "missed," or "pseudo."
|example1text = Creates a waypoint directly in front and 1 km away and appends it to the flight plan.
|example1 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);
var wp = createWP(pos, "NEWWP");
var fp = flightplan();
fp.appendWP(wp);
|example2 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);
var wp = createWP({lat: pos.lat(), lon: pos.lon()}, "NEWWP");
var fp = flightplan();
fp.appendWP(wp);
|example3 = var apt = airportinfo();
var wp = createWP(apt, "NEWWP");
var fp = flightplan();
fp.appendWP(wp);
|example4 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);
var wp = createWP(pos.lat(), pos.lon(), "NEWWP");
var fp = flightplan();
fp.appendWP(wp);
|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.
|example5 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);
var wp = createWP(pos, "NEWWP", "pseudo");
var fp = flightplan();
fp.appendWP(wp);
print(fp.getPlanSize());
fp.clearWPType("pseudo");
print(fp.getPlanSize());
}}

===createWPFrom()===
{{Nasal doc
|syntax = createWPFrom(object[, flag]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1989|t=Source}}
|text = Creates a new waypoint object from another object.
|param1 = object
|param1text = A ghost object. Must be a ghost type that is one of "airport," "navaid," "runway," or "fix."
|param2 = flag
|param2text = Optional string that will tell FlightGear what type of waypoint it is. Must be one of "sid," "star," "approach," "missed," or "pseudo."
|example1text = Creates a new waypoint and appends it to the flight plan.
|example1 = var apt = airportinfo("KSFO");
var wp = createWPFrom(apt);
var fp = flightplan();
fp.appendWP(wp);
|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.
|example2 = var apt = airportinfo("KSFO");
var wp = createWPFrom(apt, "pseudo");
print(wp.wp_name);
var fp = flightplan();
fp.appendWP(wp);
print(fp.getPlanSize());
fp.clearWPType("pseudo");
print(fp.getPlanSize());
}}

===defined()===
{{Nasal doc
|syntax = defined(symbol);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = Returns 1 (true) or 0 (false) depending on whether a variable exists.
|param1 = symbol
|param1text = A string that will be what the function searches for.
|example1 = var number = 12;
var check_exist = func {
print("Variable 'number' ", defined("number") == 1 ? "exists" : "does not exist"); # 'number' does exist
print("Variable 'number2' ", defined("number2") == 1 ? "exists" : "does not exist"); # 'number2' does not exist
}
check_exist();
}}

===directory()===
{{Nasal doc
|syntax = directory(path);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=572|t=Source}}
|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.
{{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.}}
|param1 = path
|param1text = Absolute file path.
|example1text = Gets the folders and files in [[$FG_ROOT]], and then removes the extra first two elements (see note above).
|example1 = var dir = directory(getprop("/sim/fg-root")); # get directory
dir = subvec(dir, 2); # strips off the first two elements
debug.dump(dir); # dump the vector
}}

===fgcommand()===
{{Nasal doc
|syntax = fgcommand(cmd[, args]);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=456|t=Part 1}} {{!}} {{fgdata file|Nasal/globals.nas|t=Part 2}}
|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.
|param1 = cmd
|param1text = String that is the name of the command that is to be run.
|param2 = args
|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).
|example1 = fgcommand("null"); # does nothing
|example2 = var args = props.Node.new({'script': 'print("Running fgcommand");'});
if (fgcommand("nasal", args)) { # prints "Running fgcommand" and then one of these print statements
print("Fgcommand succeeded");
} else {
print("Fgcommand encountered a problem");
}
|example3 = var args = { 'dialog-name': 'about' };
fgcommand("dialog-show", args); # shows the 'about' dialog
}}

===findAirportsByICAO() ===
{{Nasal doc
|syntax = findAirportsByICAO(search[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1096|t=Source}}
|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.
|param1 = search
|param1text = Search string for the function. Can either be a partial or a full ICAO code.
:{{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.}}
|param2 = type
|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."
|example1 = var apts = findAirportsByICAO("KSF"); # finds all airports matching "KSF"
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")"); # prints them
}
|example2 = var apts = findAirportsByICAO("SP0", "seaport"); # finds all seaplane bases matching "SP0"
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")"); # prints them
}
|example3 = var apt = findAirportsByICAO("XBET"); # one way to check if an airport does exist"
if (size(apt) == 0) {
print("Airport does not exist"); # this one will be printed
} else {
print("Airport does exist");
<nowiki>}</nowiki>
}}

===findAirportsWithinRange()===
{{Nasal doc
|syntax = findAirportsWithinRange([pos, ]range[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1066|t=Source}}
|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.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findAirportsWithinRange(lat, lon, range, type);</code>.
|param2 = range
|param2text = Mandatory number giving the range in nautical miles within which to search for airports/heliports/seaplane bases.only airports are searched for.
|param3 = type
|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."
|example1text = Searches for airports within 10 nm of [[KSFO]].
|example1 = var pos = airportinfo("KSFO");
var apts = findAirportsWithinRange(pos, 10);
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")");
}
|example2text = Searches for seaplane bases within 15 nm of [[KSFO]].
|example2 = var pos = airportinfo("KSFO");
var apts = findAirportsWithinRange(pos, 15, "seaport");
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")");
}
|example3text = Searches for airports within 10 nm of your current position.
|example3 = var apts = findAirportsWithinRange(10);
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")");
<nowiki>}</nowiki>
}}

===findCommByFrequencyMHz()===
findCommByFrequencyMHz([pos, ]freq[, type]);
[[sourceforge:p/flightgear/flightgear/ci/next/tree/src/Scripting/NasalPositioned.cxx#l1547|source]]

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.

'''pos'''

: Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findCommByFrequencyMHz(lat, lon, freq, type);</code>.
; freq
: Frequency, in megahertz, of the station to search for.
; type
: 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)
'''Example'''
var com = findCommByFrequencyMHz(123.6);
print("ID: ", com.id); # prints info about the comm station
print("Name: ", com.name);
print("Latitude: ", com.lat);
print("Longitude: ", com.lon);
print("Type: ", com.type);
print("Frequency: ", sprintf("%.3f", com.frequency), " Mhz");

=== findFixesByID() ===
{{Nasal doc
|syntax = findFixesByID([pos, ]id);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1627|t=Source}}
|text = Returns a vector containing <code>fix</code> ghost objects matching a given ID, sorted by range from a certain position.
{{inote|Fixes are (usually) also known as waypoints.}}
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findFixesByID(lat, lon, id);</code>.
|param2 = id
|param2text = Full or partial ID of the fix to search for.
:{{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.}}
|example1 = var fixes = findFixesByID("POGIC");
foreach(var fix; fixes){
print(fix.id, " - lat: ", fix.lat, " {{!}} lon: ", fix.lon); # prints information about POGIC
}
|example2 = var fix = findFixesByID("ZUNAP");
fix = fix[0];
var (course, dist) = courseAndDistance(fix);
print("Turn to heading ", math.round(course), ". You have ", sprintf("%.2f", dist), " nm to go to reach ", fixes[0].id);
}}

===findNavaidByFrequencyMHz()===
{{Nasal doc
|syntax = findNavaidByFrequencyMHz([pos, ]freq[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1547|t=Source}}
|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.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidByFrequencyMHz(lat, lon, freq, type);</code>.
|param2 = freq
|param2text = Frequency, in megahertz, of the navaid to search for.
|param3 = type
|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}}.
|example1 = var navaid = findNavaidByFrequencyMHz(109.55);
print("ID: ", navaid.id); # prints info about the navaid
print("Name: ", navaid.name);
print("Latitude: ", navaid.lat);
print("Longitude: ", navaid.lon);
print("Elevation (AMSL): ", navaid.elevation, " m");
print("Type: ", navaid.type);
print("Frequency: ", sprintf("%.3f", navaid.frequency / 100), " Mhz");
print("Range: ", navaid.range_nm, " nm");
if(navaid.course) print("Course: ", navaid.course);
}}

=== findNavaidsByFrequencyMHz()===
{{Nasal doc
|syntax = findNavaidsByFrequencyMHz([pos, ]freq[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1572|t=Source}}
|text = Returns a vector conatining <code>navaid</code> ghost objects for navaids that match a given frequency, sorted from nearest to furthest.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidsByFrequencyMHz(lat, lon, freq, type);</code>.
|param2 = freq
|param2text = Frequency, in megahertz, of the navaid to search for.
|param3 = type
|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}}.
|example1 = var navaids = findNavaidsByFrequencyMHz(109.55);
foreach(var navaid; navaids){
print("--");
print("ID: ", navaid.id); # prints info about the navaid
print("Name: ", navaid.name);
print("Latitude: ", navaid.lat);
print("Longitude: ", navaid.lon);
print("Elevation (AMSL): ", navaid.elevation, " m");
print("Type: ", navaid.type);
print("Frequency: ", sprintf("%.3f", navaid.frequency / 100), " Mhz");
print("Range: ", navaid.range_nm, " nm");
if(navaid.course) print("Course: ", navaid.course);
print("--");
<nowiki>}</nowiki>
}}

===findNavaidsByID()===
{{Nasal doc
|syntax = findNavaidsByID([pos, ]id[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1600|t=Source}}
|text = Returns a vector containing <code>navaid</code> ghost objects matching a given ID, sorted by range from a certain position.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidsByID(lat, lon, id, type);</code>.
|param2 = id
|param2text = Full or partial ID of the fix to search for.
:{{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.}}
|param3 = type
|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}}.
|example1 = var navaid = findNavaidsByID("MXW");
navaid = navaid[0];
print("ID: ", navaid.id); # prints info about 'MXW' (a VOR station)
print("Name: ", navaid.name);
print("Latitude: ", navaid.lat);
print("Longitude: ", navaid.lon);
print("Elevation (AMSL): ", navaid.elevation, " m");
print("Type: ", navaid.type);
print("Frequency: ", sprintf("%.3f", navaid.frequency / 1000), " Mhz");
print("Range: ", navaid.range_nm, " nm");
}}

===findNavaidsWithinRange()===
{{Nasal doc
|syntax = findNavaidsWithinRange([pos, ]range[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1518|t=Source}}
|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.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidsWithinRange(lat, lon, range, type);</code>.
|param2 = range
|param2text = Mandatory number giving the range in nautical miles within which to search for navaids.
|param3 = type
|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}}.
|example1text = Searches for navaids within 10 nm of [[KSFO]].
|example1 = var pos = airportinfo("KSFO");
var navs = findNavaidsWithinRange(pos, 10);
foreach(var nav; navs){
print(nav.name, " (ID: ", nav.id, ")");
}
|example2text = Searches for navaids within 10 nm of your current position.
|example2 = var navs = findNavaidsWithinRange(10);
foreach(var nav; navs){
print(nav.name, " (ID: ", nav.id, ")");
<nowiki>}</nowiki>
}}

===finddata()===
{{Nasal doc
|syntax = finddata(path);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=603|t=Source}}
|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]].
|param1 = path
|param1text = A relative path as a string.
|example1 = var path = finddata("Aircraft/Generic");
print(path); # prints the absolute path to $FG_ROOT/Aircraft/Generic
|example2 = var path = finddata("Airports");
print(path); # prints the absolute path to <TerraSync dir>/Airports
|example3 = var path = finddata("preferences.xml");
print(path); # prints the absolute path to $FG_ROOT/preferences.xml
}}

===flightplan()===
{{Nasal doc
|syntax = flightplan([path]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1738|t=Source}}
|text = {{see also|Nasal Flightplan}}
Returns a flight plan object, either one for the current flight plan, or one loaded from a given path.
|param1 = path
|param1text = Optional path to flight plan XML file.
|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.
|example1 = var fp = flightplan();
print(fp.getWP(fp.current).id);
|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>.
|example2 = var path = getprop('/sim/fg-home') ~ '/fp-demo.xml';
var fp = flightplan(path);
for(var i = 0; i < fp.getPlanSize(); i += 1){
print(fp.getWP(i).id);
<nowiki>}</nowiki>
}}

===geodinfo()===
{{Nasal doc
|syntax = geodinfo(lat, lon[, max_alt]);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=981|t=Source}}
|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}}):
* '''light_coverage:''' The coverage of a single point of light in m<sup>2</sup>.
* '''bumpiness:''' Normalized bumpiness factor for the material.
* '''load_resistance:''' The amount of pressure in N/m<sup>2</sup> the material can withstand without deformation.
* '''solid:''' 1 (true) or false (0) depending on whether the material is solid or not.
* '''names:''' Vector of scenery types (usually generated by [[TerraGear]]) that will use this material.
* '''friction_factor:''' Normalized friction factor of the material.
* '''rolling_friction:''' The rolling friction coefficient of the material.

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.
|param1 = lat
|param1text = Latitude, inputted as a number.
|param2 = lon
|param2text = Longitude, inputted as a number.
|param3 = max_alt
|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.
|example1text = Dumps information about ground underneath the aircraft.
|example1 = var pos = geo.aircraft_position();
var info = geodinfo(pos.lat(), pos.lon());
debug.dump(info);
|example2text = Prints whether the ground underneath the aircraft is solid or is water.
|example2 = var pos = geo.aircraft_position();
var info = geodinfo(pos.lat(), pos.lon());
if (info != nil and info[1] != nil) {
print("The ground underneath the aircraft is ", info[1].solid == 1 ? "solid." : "water.");
<nowiki>}</nowiki>
}}

=== geodtocart() ===
{{Nasal doc
|syntax = geodtocart(lat, lon, alt);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=962|t=Source}}
|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.
|param1 = lat
|param1text = Latitude, in degrees.
|param2 = lon
|param2text = Longitude, in degrees.
|param3 = alt
|param3text = Altitude, in metres.
|example1 = var (x, y, z) = geodtocart(0, 0, 0); # point is the intersection of the prime meridian and equator.
print("x: ", x); # prints "x: 6378137"
print("y: ", y); # prints "y: 0"
print("z: ", z); # prints "y: 0"
}}

=== get_cart_ground_intersection()===
Introduced in 2017.2.1, see [[Terrain Detection]].

===getprop()===
{{Nasal doc
|syntax = <nowiki>getprop(path[, path[, ...]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=345|t=Source}}
|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).
|param1 = path
|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.
|example1 = print("You have FlightGear v", getprop("/sim/version/flightgear")); # prints FlightGear version
|example2text = Note that the example below will only work in FlightGear 3.2 and above.
|example2 = for(var i = 0; i < 8; i += 1){
print("View #", i + 1, " is named ", getprop("/sim/view", i, "name"));
}
|example3text = Same as above, but is supported by all versions of FlightGear.
|example3 = for(var i = 0; i < 8; i += 1){
print("View #", i + 1, " is named ", getprop("/sim/view[" ~ i ~ "]/name"));
<nowiki>}</nowiki>
}}
==== See also====
{{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:
To get a Node rather than its value, use <code>props.globals.getNode()</code> - see [[Nasal_library/props]]. }}

===greatCircleMove()===
{{Nasal doc
|syntax = greatCircleMove([pos, ]course, dist);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1681|t=Source}}
|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).
|param1 = pos
|param1text = Optional position to calculate from. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost object.
:* A hash with ''lat'' and ''lon'' members
:* A <code>geo.Coord</code> object
:* A lat/lon pair, that is, a pair of numbers (latitude followed by longitude) separated by a comma: <code>greatCircleMove(lat,lon, ...)</code>.
|param2 = course
|param2text = Course to new set of coordinates, in degrees (in the range 0–360).
|param3 = dist
|param3text = Distance in nautical miles to the new set of coordinates.
|example1 = var pos = greatCircleMove(0,0, 0, 1);
debug.dump(pos); # print hash with coordinates
|example2 = var fix = findFixesByID("POGIC");
fix = fix[0];
var pos = greatCircleMove(fix, 45, 10);
debug.dump(pos); # print hash with coordinates
}}

===interpolate()===
{{Nasal doc
|private = _interpolate()
|syntax = <nowiki>interpolate(prop, value1, time1[, value2, time2[, ...]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=522|t=Part 1}} {{!}} {{fgdata file|Nasal/globals.nas|t=Part 2}}
|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.
|param1 = prop
|param1text = String or <code>props.Node</code> object that indicates a node in the property tree to be used.
|param2 = value''n''
|param2text = Target value to change the property to in the set amount of time. This should be a number.
|param3 = time''n''
|param3text = Time in seconds, that will be taken for the interpolation.
|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.
|example1 = setprop("/test", 0); # (re-)set property
interpolate("/test",
50, 5, # interpolate to 50 in 5 seconds
10, 2, # interpolate to 10 in 2 seconds
0, 5); # interpolate to 0 in 5 seconds
|example2 = # Apply the left brake at 20% per second
var prop = "controls/gear/brake-left";
var dist = 1 - getprop(prop);
if (dist == 1) {
interpolate(prop, 1, dist / 0.2);
<nowiki>}</nowiki>
}}

===isa()===
{{Nasal doc
|syntax = isa(object, class);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|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.
|param1 = object
|param1text = Object to check.
|param2 = class
|param2text = Class/object to check that '''object''' inherits from or is an instance of.
|example1 = var coord = geo.Coord.new();
if(isa(coord, geo.Coord)){
print("Variable 'coord' is an instance of class 'geo.Coord'"); # this one will be printed
} else {
print("Variable 'coord' is not an instance of class 'geo.Coord'");
}
|example2 = var coord = geo.Coord.new();
if(isa(coord, props.Node)){
print("Variable 'coord' is an instance of class 'props.Node'");
} else {
print("Variable 'coord' is not an instance of class 'props.Node'"); # this one will be printed
}
|example3text = The example below demonstrates checking of inheritance.
|example3 = var Const = {
constant: 2,
getConst: func {
return me.constant;
}
};

var Add = {
new: func {
return { parents: [Add, Const] };
},

addToConst: func(a){
return a * me.getConst();
}
};

var m = Add.new();
print(m.addToConst(4));

if(isa(m, Add)) print("Variable 'm' is an instance of class 'Add'"); # will be printed
if(isa(m, Const)) print("Variable 'm' is an instance of class 'Const'"); # will also be printed
}}

===logprint()===
{{Nasal doc
|syntax = <nowiki>logprint(priority[, msg[, msg[, ...]]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=431|t=Source}}
|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}}.
|param1 = priority
|param1text = Number specifying the priority level of the outputted message:
:{{{!}} class="wikitable"
! Number !! Debug type
{{!-}}
{{!}} 1 {{!!}} Bulk
{{!-}}
{{!}} 2 {{!!}} Debug
{{!-}}
{{!}} 3 {{!!}} Info
{{!-}}
{{!}} 4 {{!!}} Warn
{{!-}}
{{!}} 5 {{!!}} Alert
{{!}}}
|param2 = msg
|param2text = The message. There is no limit to the arguments you give give. They will be concatenated together before logging.
|example1 = # logs the value of pi to three decimal places with log level 3
logprint(3, "pi = ", sprintf("%.3f", math.pi));
|example2 = logprint(5, "Alert! This is an important message!");
}}
{{note|
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:

LOG_BULK, LOG_WARN, LOG_DEBUG, LOG_INFO, LOG_ALERT, DEV_WARN, DEV_ALERT }}

===magvar() ===
{{Nasal doc
|syntax = magvar([pos]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1642|t=Source}}
|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.
{{{!}} class="wikitable"
! FlightGear versions !! Model !! Reference date
{{!-}}
{{!}} 3.6 and above {{!!}} {{wikipedia|World Magnetic Model}} (WMM) 2015 {{!!}} 1 January 2015
{{!-}}
{{!}} 0.9.11-pre1 to 3.4 {{!!}} WMM 2005 {{!!}} 1 January 2005
{{!-}}
{{!}} 0.7.3 to 0.9.10 {{!!}} WMM 2000 {{!!}} 1 January 2000
{{!}}}
|param1 = pos
|param1text = Optional position to calculate from. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost object.
:* A hash with ''lat'' and ''lon'' members
:* A <code>geo.Coord</code> object
:* A lat/lon pair, that is, a pair of numbers (latitude followed by longitude) separated by a comma: <code>magvar(lat,lon)</code>.
|example1 = print(magvar(0, 0)); # prints the magnetic variation at 0, 0
}}

===maketimer() ===
{{Nasal doc
|syntax = maketimer(interval[, self], function);
|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}}
|version = 2.12
|commit = {{flightgear commit|ab939f|t=commit}}
|text = Returns a timer object containing the following methods and members:
* '''start()''': Starts the timer.
* '''stop()''': Stops the timer.
* '''restart(interval)''': Restarts the timer with the given interval.
* '''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).
* '''isRunning''': Read-only bool telling whether the timer is currently running.
* '''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.
Unlike {{func link|settimer()}}, which it replaces, <code>maketimer()</code> provides more control over the timer. In addition, it can help reduce memory usage.
|param1 = interval
|param1text = Interval in seconds for the timer.
|param2 = self
|param2text = Optional parameter specifying what any <code>'''me'''</code> references in the function being called will refer to.
|param3 = function
|param3text = Function to be called at the given interval.
|example1 = var timer = maketimer(1, func(){
print("Hello, World!"); # print "Hello, World!" once every second (call timer.stop() to stop it)
});
timer.start();
|example2 = var timer = maketimer(1, math, func(){
print(me.math); # 'me' reference is the 'math' namespace
});
timer.singleShot = 1; # timer will only be run once
timer.start();
|example3 = var timer = maketimer(1, func(){
print("Hello, World!"); # print "Hello, World!" once every second (call timer.stop() to stop it)
});
timer.start();
print(timer.isRunning); # prints 1
|example4text = In the example below, "Hello, World!" will be printed after one second the first time, and after two seconds thereafter.
|example4 = var update = func(){
print("Hello, World!");
timer.restart(2); # restarts the timer with a two second interval
}

var timer = maketimer(1, update);
timer.singleShot = 1;
timer.start();
}}

===maketimestamp()===
{{Nasal doc
|syntax = maketimestamp()
|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}}
|version = 2019.2
|commit = {{flightgear commit|7db06300|t=commit}}
|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:
* '''stamp()''': Resets the timing operation. Call this first.
* '''elapsedMSec()''': returns number of milliseconds elapsed since stamp() called. Resolution may vary depending on platform but is usually at least millisecond accuracy.
* '''elapsedUSec()''': returns number of microseconds elapsed since stamp() called. Resolution may vary depending on platform but is usually at least millisecond accuracy.
|
|example1text = In the example below the number of milliseconds elapsed will be printed.
|example1 = var timestamp = maketimestamp();
timestamp.stamp();
print(timestamp.elapsedMSec(), "ms elapsed");
print(timestamp.elapsedMSec(), "ms elapsed");
}}

===md5()===
{{Nasal doc
|syntax = md5(string);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=758|t=Source}}
|version = 3.2
|commit = {{flightgear commit|cfbf9e|t=commit}}
|text = Returns a the {{wikipedia|MD5}} hash (as a string) of the inputted string.
|param1 = string
|param1text = String the generate the hash of. Mandatory.
|example1text = The below code should output <code>65a8e27d8879283831b664bd8b7f0ad4</code>.
|example1 = print(md5("Hello, World!"));
}}

===navinfo()===
{{Nasal doc
|syntax = navinfo(lat, lon, type, id);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1453|t=Source}}
|text = Returns vector <code>navaid</code> ghost objects matching the given '''type''' and '''id''' or <code>'''nil'''</code> on error.
|param1 = lat ''and'' lon
|param1text = If given, the returned navaids will be put into order of ascending distance from the location.
|param2 = type
|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."
|param3 = id
|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.
|example1 = navinfo("vor"); # returns all VORs
|example2 = navinfo("HAM"); # return all navaids whose names start with "HAM"
|example3 = navinfo("vor", "HAM"); # return all VORs whose names start with "HAM"
|example4 = navinfo(34,48,"vor","HAM"); # return all VORs whose names start with "HAM" and sorted by distance relative to 34°, 48°
}}

===parse_markdown()===
{{Nasal doc
|syntax = parse_markdown(markdown);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=745|t=Part 1}} {{!}} {{simgear file|simgear/misc/SimpleMarkdown.cxx|t=Part 2}}
|version = 3.2
|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:
* It strips whitespace from the beginning of the string.
* It supports [http://daringfireball.net/projects/markdown/syntax#p paragraphs and line breaks].
* It collapses whitespace.
* It converts unordered [http://daringfireball.net/projects/markdown/syntax#list lists] to use a bullet character (•). 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.
|param1 = markdown
|param1text = String containing Markdown to be parsed.
|example1text =
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>).
<syntaxhighlight lang="xml" highlight="41-50">
<?xml version="1.0" encoding="UTF-8"?>

<PropertyList>

<name>test</name>
<layout>vbox</layout>

<group>
<layout>hbox</layout>

<empty>
<stretch>true</stretch>
</empty>

<text>
<label>parse_markdown() test dialog</label>
</text>

<empty>
<stretch>true</stretch>
</empty>

<button>
<legend></legend>
<pref-width>16</pref-width>
<pref-height>16</pref-height>
<binding>
<command>dialog-close</command>
</binding>
</button>

</group>

<canvas>
<name>Canvas plot</name>
<stretch>true</stretch>
<pref-width>400</pref-width>
<pref-height>300</pref-height>
<nasal>
<load><![CDATA[
var text = 'Items:
* apples
* oranges
* pears

Some text.
Some more items:
* apples
* oranges
* pears';

var parsed = parse_markdown(text);

var root_canvas = canvas.get(cmdarg());
root_canvas.setColorBackground(255, 255, 255);
var root = root_canvas.createGroup();

var text_dis = root.createChild("text")
.setText(parsed)
.setTranslation(5, 5)
.setFont("LiberationFonts\LiberationSans-Regular.ttf")
.setFontSize(15)
.setColor(0, 0, 0)
.setDrawMode(canvas.Text.TEXT)
.setAlignment("left-top");
]]></load>
</nasal>
</canvas>

</PropertyList>
</syntaxhighlight>
|example1 = fgcommand("dialog-show", {"dialog-name": "test"});
|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.
|example2 = <nowiki>var markdown = 'Items:
* apples
* oranges
* pears

Some text.
Some more items:
* apples
* oranges
* pears';

var parsed = parse_markdown(markdown);

debug.dump(parsed);

var path = string.normpath(getprop("/sim/fg-home") ~ '/Export/parse_markdown()-test.html');

var file = io.open(path, "w");

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>";

io.write(file, html);
io.close(file);
print("Done, file ready for viewing (" ~ path ~ ")");</nowiki>
}}

===parsexml()===
{{Nasal doc
|syntax = <nowiki>parsexml(path[, start[, end[, data[, pro_ins]]]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=710|t=Source}}
|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.
|param1 = path
|param1text = Mandatory absolute path to the XML file to be parsed.
|param2 = start
|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.
|param3 = end
|param3text = Optional callback function that will be called for every ending tag. The function should take one argument: the tag name.
|param4 = data
|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.
|param5 = pro_ins
|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.
|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.
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>

<?xml-stylesheet type="text/xsl" href="style.xsl"?>

<foo>
<blah type="string"><![CDATA[ <sender>John Smith</sender> ]]></blah>
<blah2 type="string">Orange & lemons</blah2>
</foo>
</syntaxhighlight>
|example1 = var start = func(name, attr){
print("Starting tag: '", name, "'");
foreach(var a; keys(attr)){
print("\twith attribute ", a, '="', attr[a], '"');
}
}

var end = func(name){
print("Ending tag: '", name, "'");
}

var data = func(data){
print("Data = '", data, "'");
}

var pro_instr = func(target, data){
print("Processing instruction: target = '", target, "', data = '", data, "'");
}

parsexml(getprop("/sim/fg-home") ~ '/Export/demo.xml', start, end, data, pro_instr);
}}

===print()===
{{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.

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>}}

{{Nasal doc
|syntax = <nowiki>print(data[, data[, ...]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=415|t=Source}}
|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.
|param1 = data
|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.
|example1 = print("Just", " a ", "test"); # prints "Just a test"
|example2 = print("pi = ", math.pi); # prints "pi = 3.141592..."
}}

=== printf() ===
{{Nasal doc
|syntax = <nowiki>printf(format[, arg[, arg, [...]]]);</nowiki>
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|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>).
|example1 = printf("In hexadecimal, 100000 = %X", 186A0); # prints "In hexadecimal, 100000 = 186A0"
}}

===printlog()===
{{caution|This function is deprecated and doesn't work. Please use the new one {{func link|logprint()}}.}}
{{Nasal doc
|syntax = <nowiki>printlog(level, data[, data[, ...]]);</nowiki>
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|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.
|param1 = level
|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.
|param2 = data
|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.
|example1 = printlog("alert", "This is an alert"); # message will be printed
|example2 = printlog("info", "Just informing you about something"); # message will be printed only if log level is set to "info" or less
}}

===rand()===
{{Nasal doc
|syntax = rand();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=554|t=Source}}
|text = Returns a random floating point number between 0 (inclusive) and 1 (exclusive). It takes no arguments.
|example1 = print(rand()); # prints random number
}}

===registerFlightPlanDelegate()===
{{Nasal doc
|syntax = registerFlightPlanDelegate(init_func);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1879|t=Source}}
|text = Registers a flight plan delegate. See <tt>''{{fgdata file|Nasal/route_manager.nas|t=$FG_ROOT/Nasal/route_manager.nas}}''</tt> for examples.
|param1 = init_func
|param1text = Initialization function which will be called during FlightGear's startup.
}}
===removecommand()===
{{Nasal doc
|syntax = removecommand(cmd);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=668|t=Source}}
|text = Removes the given fgcommand. Returns <code>'''nil'''</code>.
{{caution|This will remove '''any''' [[fgcommands|fgcommand]], even those implemented in C++, so use with caution!}}
|param1 = cmd
|param1text = String specifying the name of the command to remove.
|example1 = addcommand("hello", func(){
print("Hello");
});
fgcommand("hello"); # "Hello" will be printed
removecommand("hello"); # removes it
}}

===removelistener()===
{{Nasal doc
|syntax = removelistener(id);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=1384|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=506|t=Part 2}}
|text = Removes and deactivates the given listener and returns the number of listeners left or <code>'''nil'''</code> on error.
{{note|It is good practice to remove listeners when they are not required anymore. This prevents the listeners reducing FlightGear's run performance.}}
|param1 = id
|param1text = ID of listener as returned by {{func link|setlistener()}}.
|example1 = var ls = setlistener("/sim/test", func(){
print("Property '/sim/test' has been changed");
});
setprop("/sim/test", "blah"); # trigger listener
var rem = removelistener(ls); # remove listener
print("There are ", rem, " listeners remaining");
}}

===resolvepath()===
{{Nasal doc
|syntax = resolvepath(path);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=604|t=Source}}
|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.
|param1 = path
|param1text = Relative path to be completed.
|example1 = print(resolvepath("Nasal/globals.nas")); # prints the equivalent of $FG_ROOT/Nasal/globals.nas
|example2 = print(resolvepath("blah")); # prints nothing; could not be resolved
|example3 = var file_path = resolvepath("Aircraft/SenecaII/some-file");
if (file_path != ""){
gui.popupTip("some-file found", 2);
} else {
gui.popupTip("some-file not found", 2);
<nowiki>}</nowiki>
}}

===setlistener()===
{{Nasal doc
|syntax = <nowiki>setlistener(node, code[, init[, type]]);</nowiki>
|private = _setlistener()
|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.''
|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()}}.
{{note|Listeners are known to be a source of resource leaks. To avoid this, please take measures such as:
* Using {{func link|removelistener()}} when they are not needed any more.
* Using a single initialization listener.
* Avoiding tying listeners to properties that are rapidly updated (e.g., many times per frame).
}}
|param1 = node
|param1text = Mandatory string or <code>props.Node</code> object pointing to a property in the [[Property Tree]].
|param2 = code
|param2text = Mandatory callback function to execute when the listener is triggered. The function can take up to four arguments in the following order:
* '''changed''': a <code>props.Node</code> object pointing to the changed node.
* '''listen''': a <code>props.Node</code> object pointing to the listened-to node. Note that this argument maybe different depending on the '''type'''.
* '''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.
* '''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.
|param3 = init
|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).
|param4 = type
|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.
|example1 = var prop = props.globals.initNode("/sim/test", "", "STRING"); # create property
var id = setlistener("/sim/test", func(n){ # create listener
print("Value: ", n.getValue());
});
setprop("/sim/test", "blah"); # trigger listener
removelistener(id); # remove listener
prop.remove(); # remove property
}}

===setprop()===
{{Nasal doc
|syntax = <nowiki>setprop(path[, path[, ...]], value);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=385|t=Source}}
|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.
{{note|If you want to remove a property, you will have to use one of the <code>props</code> helpers:
<syntaxhighlight lang="nasal">
props.globals.getNode("foo/bar").remove(); # take out the complete node
props.globals.getNode("foo").removeChild("bar"); # take out a certain child node
</syntaxhighlight>
}}
|param1 = path
|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.
|param2 = value
|param2text = Value to write to the given property. Must be either a string or a number.
|example1 = setprop("/sim/demo", "This is a demo");
|example2text = Note that the example below will only work in FlightGear 3.2 and above.
|example2 = for(var i = 0; i < 3; i += 1){
setprop("/sim/demo", i, "Demo #" ~ i));
}
|example3text = Same as above, but is supported by all versions of FlightGear.
|example3 = for(var i = 0; i < 3; i += 1){
setprop("/sim/demo[" ~ i ~ "]", "Demo #" ~ i));
<nowiki>}</nowiki>
}}
====See also====
{{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:
To get a Node rather than its value, use <code>props.globals.getNode()</code> - see [[Nasal_library/props]]. }}

===settimer() ===
{{Nasal doc
|syntax = settimer(function, delta[, realtime]);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=499|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=1286|t=Part 2}}
|text = Runs the given function a specified amount of seconds after the current time. Returns <code>'''nil'''</code>.
{{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.}}
|param1 = function
|param1text = Mandatory function that will be called. It may be necessary to enclose code in an anonymous function (see example).
|param2 = delta
|param2text = Mandatory amount of time in seconds after which the function will be called.
|param3 = realtime
|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.
|example1 = var myFunc = func(){
print("Hello");
}

settimer(myFunc, 2); # runs myFunc after 2 seconds
|example2 = var sqr = func(a){
return a * a;
}

settimer(func(){
print(sqr(2)); # will print 4 after 2 seconds
}, 2);
}}

===srand() ===
{{Nasal doc
|syntax = srand();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=559|t=Source}}
|text = Makes the pseudorandom number generator (see {{func link|rand()}}) generate a new {{wikipedia|random seed|noicon=1}} based on time. Returns 0.
}}
===systime()===
{{Nasal doc
|syntax = systime();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=770|t=Source}}
|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).
{{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]}}
|example1 = print("Unix time: ", systime()); # prints Unix time
|example2 = var myFunc = func(){
for(var i = 0; i <= 10; i += 1){
print("Interation #", i);
}
}
var t = systime(); # record time
myFunc(); # run function
var t2 = systime(); # record new time
print("myFunc() took ", t2 - t, " seconds"); # print result
}}

===thisfunc()===
{{Nasal doc
|syntax = thisfunc();
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = Returns the function from which this function is called. This allows a function to reliably and safely call itself from within a closure.
|example1 = var stringify_vec = func(input){
if (typeof(input) == "scalar"){
return sprintf("%s", input);
} elsif (typeof(input) == "vector") {
if (size(input) == 0) return "[]";
var this = thisfunc();
var buffer = "[";
for(var i = 0; i < size(input); i += 1){
buffer ~= this(input[i]);
if (i == size(input) - 1) {
buffer ~= "]";
} else {
buffer ~= ", ";
}
}
return buffer;
} else {
die("stringify_vec(): Error! Invalid input. Must be a vector or scalar");
}
}

var test_vec = ["a", "b", "c", [1, 2, 3], "d"];
debug.dump(stringify_vec(test_vec)); # prints "[a, b, c, [1, 2, 3], d]"
test_vec = [];
debug.dump(stringify_vec(test_vec)); # prints "[]"
test_vec = {};
debug.dump(stringify_vec(test_vec)); # will throw an error
}}

===tileIndex() ===
{{Nasal doc
|syntax = tileIndex();
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1720|t=Source}}
|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>.
|example1 = print(tileIndex()); # print index
}}

=== tilePath()===
{{Nasal doc
|syntax = tilePath();
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1712|t=Source}}
|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>.
|example1 = print(tilePath()); # print path
}}

=== values()===
{{Nasal doc
|syntax = values(hash);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = Returns a vector containing the values of the given hash.
|param1 = hash
|param1text = Mandatory hash to get the values of.
|example1 = var hash = {
"a": 1,
"b": 2,
"c": 3
};

foreach(var val; values(hash)){
print(val);
}
|example2text = The below example does exactly the same thing as the above example, but does not use <code>values()</code>:
|example2 = var hash = {
"a": 1,
"b": 2,
"c": 3
};

foreach(var key; keys(hash)){
print(hash[key]);
<nowiki>}</nowiki>
}}

==Extension functions new in FG 2020.1 ==
The following functions have been added to the nasal core library and will be released with FlightGear version 2020.1.
Before the release they are available in the development branch "next".

===isfunc()===
Returns 1 if type or argument is a function, otherwise 0.

===isghost()===
Returns 1 if type or argument is a ghost, otherwise 0.

=== ishash()===
Returns 1 if type or argument is a hash, otherwise 0.

===isint()===
{{Nasal doc
|syntax = isint(x);
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}
|text = Returns 1 if argument has a numeric value and x == floor(x), e.g. integer.
}}

===isnum()===
{{Nasal doc
|syntax = isnum(x);
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}
|text = Returns 1 if typeof(x) is "scalar" and x has a numeric value otherwise 0.
}}

===isscalar()===
{{Nasal doc
|syntax = isscalar(x);
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}
|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 "~".
|example1 = var a = "foo";
var b=42;
if (isscalar(a) and isscalar(b)) print(a~b);
if (isstr(a)) print("a is a string");
if (isint(b)) print("b is an integer");
# if (isscalar(a))... is equivalent to if (typeof(a) == "scalar")...
}}

===isstr()===
Returns 1 if type or argument is a string, otherwise 0.

===isvec()===
Returns 1 if type or argument is a vector, otherwise 0.

===vecindex()===
{{Nasal doc
|syntax = vecindex(vector, value);
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}
|text = Returns the index of value or nil, if value is not found in vector.
|example1=
var myvector = ["apple", "bananna", "coconut"];
# to check if a vector contains a certain value compare vecindex to nil
if (vecindex(myvector, "apple") != nil) {
print("found apple");
}
# WARNING: this will not work as desired because index is 0
if (vecindex(myvector, "apple")) {
print("found apple");
<nowiki>}</nowiki>

}}

==Variables==
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}}.

===D2R===
{{Nasal doc
|syntax = var radians = degrees * D2R;
|text = Converts an angle from degrees to radians when multiplied by the angle in degrees. Equal to <code>π / 180</code>.
}}
===FPS2KT===
{{Nasal doc
|syntax = var knots = feet_per_second * FPS2KT;
|text = Converts a velocity from feet per second to knots when multiplied by the velocity in feet per second. Approximately equal to 0.5925.
}}
===FT2M===
{{Nasal doc
|syntax = var metres = feet * FT2M;
|text = Converts a length from feet to metres when multiplied by the length in feet. Equal to 0.3048.
}}
===GAL2L ===
{{Nasal doc
|syntax = var litres = gallons * GAL2L;
|text = Converts a volume from US liquid gallons to litres when multiplied by the volume in gallons. Approximately equal to 3.7854.
}}
===IN2M===
{{Nasal doc
|syntax = var metres = inches * IN2M;
|text = Converts a length from inches to metres when multiplied by the length in inches. Equal to 0.0254.
}}
===KG2LB===
{{Nasal doc
|syntax = var pounds = kilograms * KG2LB;
|text = Converts a mass from kilograms to pounds when multiplied by the mass in kilograms. Approximately equal to 2.2046.
}}
===KT2FPS===
{{Nasal doc
|syntax = var feet_per_second = knots * KT2FPS;
|text = Converts a velocity from knots to feet per second when multiplied by the velocity in knots. Approximately equal to 1.6878.
}}
===KT2MPS===
{{Nasal doc
|syntax = var metres_per_second = knots * KT2MPS;
|text = Converts a velocity from knots to metres per second when multiplied by the velocity in knots. Approximately equal to 0.5144.
}}
===L2GAL===
{{Nasal doc
|syntax = var gallons = litres * L2GAL;
|text = Converts a volume from litres to US liquid gallons when multiplied by the volume in litres. Approximately equal to 0.2642.
}}
===LB2KG===
{{Nasal doc
|syntax = var kilograms = pounds * LB2KG;
|text = Converts a mass from pounds to kilograms when multiplied by the mass in pounds. Approximately equal to 0.4536.
}}
===M2FT ===
{{Nasal doc
|syntax = var feet = metres * M2FT;
|text = Converts a length from metres to feet when multiplied by the length in metres. Approximately equal to 3.2808.
}}
===M2IN===
{{Nasal doc
|syntax = var inches = metres * M2IN;
|text = Converts a length from metres to inches when multiplied by the length in metres. Approximately equal to 39.3701.
}}
===M2NM ===
{{Nasal doc
|syntax = var nautical_miles = metres * M2NM;
|text = Converts a length from metres to nautical miles when multiplied by the length in metres. Approximately equal to 0.00054.
}}
===MPS2KT ===
{{Nasal doc
|syntax = var knots = metres_per_second * MPS2KT;
|text = Converts a velocity from metres per second to knots when multiplied by the velocity in metres per second. Approximately equal to 1.9438.
}}
===NM2M ===
{{Nasal doc
|syntax = var metres = nautical_miles * NM2M;
|text = Converts a length from nautical miles to metres when multiplied by the length in nautical miles. Equal to 1,852.
}}
===R2D===
{{Nasal doc
|syntax = var degrees = radians * R2D;
|text = Converts an angle from radians to degrees when multiplied by the angle in radians. Equal to <code>180 / π</code>.
}}

{{Appendix}}

{{Nasal namespaces}}

Nasal library

2025-12-04T12:32:42Z

PlayeRom: /* streq() */

{{Nasal Navigation|nocat=1}}
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:
* {{flightgear file|src/Scripting}}
* {{simgear file|simgear/nasal}}

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]].

{{tip|Copy & paste the examples into your [[Nasal Console]] and execute them to see what they do.|width=70%}}

== Core library functions ==
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:
* http://plausible.org/nasal/lib.html ([http://web.archive.org/web/20101010094553/http://plausible.org/nasal/lib.html archive])
* {{simgear file|simgear/nasal/lib.c}} ([http://sourceforge.net/p/flightgear/simgear/ci/next/log/?path=/simgear/nasal/lib.c history])

=== append() ===
{{Nasal doc
|syntax = append(vector, element[, element[, ...]]);
|source = {{simgear file|simgear/nasal/lib.c|l=45|t=Source}}
|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.
|param1 = vector
|param1text = The vector to which the arguments will be appended.
|param2 = element
|param2text = An element to be added to the vector.
|example1 =
var vector = [1, 2, 3]; # Initialize the vector
append(vector, 4); # Append the number 4 to the end of the vector
debug.dump(vector); # Print the contents of the vector
|example2 =
var vector = [1, 2, 3]; # Initialize the vector
append(vector, 4, 5, 6); # Append the numbers 4, 5, and 6 to the end of the vector
debug.dump(vector); # Print the contents of the vector
}}

=== bind() ===
{{Nasal doc
|syntax = bind(function, locals[, outer_scope]);
|source = {{simgear file|simgear/nasal/lib.c|l=638|t=Source}}
|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.
|param1 = function
|param1text = Function to evaluate.
|param2 = locals
|param2text = Hash containing values that will become the namespace (first closure) for the function.
|param3 = outer_scope
|param3text = Optional function which is bound to the next closure. This can be bound to yet another, making a linked list.
|example1 = # This is a namespace/hash with a single member, named "key," which is initialized to 12
var Namespace = {
key: 12
};

# This is different namespace/hash containing a function
# dividing a variable "key" (which is unavailable/nil in this namespace) by 2
var AnotherNamespace = {
ret: func {
key /= 2;
}
};

# To see that key is not available, try to call AnotherNamespace.ret() first
call(AnotherNamespace.ret, [], nil, nil, var errors = []);
if(size(errors)){
print("Key could not be divided/resolved!");
debug.printerror(errors);
}

# Associate the AnotherNamespace.ret() function with the first namespace
# so that "key" is now available
var function = bind(AnotherNamespace.ret, Namespace);

# Invoke the new function
function();

# Print out the value of Namespace.key
# It was changed to 12 from 6 by AnotherNamespace.ret()
print(Namespace.key);
}}

=== call() ===
{{Nasal doc
|syntax = call(func[, args[, me[, locals[, error]]]);
|source = {{simgear file|simgear/nasal/lib.c|l=376|t=Source}}
|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.
|param1 = func
|param1text = Function to execute.
|param2 = args
|param2text = Vector containing arguments to give to the called function.
|param3 = me
|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).
|param4 = locals
|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.
|param5 = error
|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}}.
|example1 =
# prints "Called from call()"
call(func {
print("Called from call()");
});
|example2 =
# prints "a = 1 : b = 2
call(func(a, b){
print("a = ", a, " : b = ", b);
},
[1, 2]
);
|example3 =
var Hash = {
new: func {
var m = { parents: [Hash] };

m.el1 = "string1";
m.el2 = "string2";

return m;
}
};

# prints "me.el1 = string1", then "me.el2 = string2" on the next line
call(func(a, b){
print("me.el", a, " = ", me["el" ~ a]);
print("me.el", b, " = ", me["el" ~ b]);
},
[1, 2],
Hash.new()
);
|example4 =
# prints the value of math.pi
call(func {
print(pi);
}, nil, nil,
math
);
|example5 =
call(func {
print(math.ip); # math.ip doesn't exist
}, nil, nil, nil,
var errs = []
);
debug.printerror(errs); # The error is caught and printed using debug.printerror()
}}

=== caller() ===
{{Nasal doc
|syntax = caller([level]);
|source = {{simgear file|simgear/nasal/lib.c|l=540|t=Source}}
|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 '''[0]''' a hash of local variables, '''[1]''' the function object, '''[2]''' the full source file name (incl. path) and '''[3]''' the line number.
|param1 = level
|param1text = Optional integer specifying the stack level to return a result from. Defaults to 1 (i.e. the caller of the currently executing function).
|example1 =
var myFunction = func(a, b) {
debug.dump(caller(0)[0]); # prints a hash of local variables, including arguments a and b
return 2 * 2;
};

print("2 x 2 = ", myFunction(2, 2));
|example2 =
var get_arg_value = func() {
print("Argument to myFunc = ", caller(1)[0]['a']); # print the value of myFunc's single argument, using caller()
};

var myFunc = func(a) {
get_arg_value();
};

myFunc(3);
|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: true, zindex: nil }</code>.
|example3 =
var MapStructure_selfTest = func() {
var temp = {};
temp.dlg = canvas.Window.new([600, 400], "dialog");
temp.canvas = temp.dlg.createCanvas().setColorBackground(1, 1, 1, 0.5);
temp.root = temp.canvas.createGroup();

var testMap = temp.root.createChild("map");
testMap.setController("Aircraft position");
testMap.setRange(25); # TODO: implement zooming/panning via mouse/wheel here, for lack of buttons :-/
testMap.setTranslation(
temp.canvas.get("view[0]") / 2,
temp.canvas.get("view[1]") / 2,
);

var r = func(name, vis = true, zindex = nil) {
return caller(0)[0];
}

# TODO: we'll need some z-indexing here, right now it's just random
# TODO: use foreach/keys to show all layers in this case by traversing SymbolLayer.registry directly ?
# maybe encode implicit z-indexing for each lcontroller ctor call ? - i.e. preferred above/below order ?
var types = [
r('TFC', false),
r('APT'),
r('DME'),
r('VOR'),
r('NDB'),
r('FIX', false),
r('RTE'),
r('WPT'),
r('FLT'),
r('WXR'),
r('APS'),
];

foreach (var type; types) {
testMap.addLayer(
factory: canvas.SymbolLayer,
type_arg: type.name,
visible: type.vis,
priority: type.zindex,
);
}
}; # MapStructure_selfTest
}}

=== chr() ===
{{Nasal doc
|syntax = chr(code);
|source = {{simgear file|simgear/nasal/lib.c|l=240|t=Source}}
|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.}}
{{{!}} class="wikitable"
! Code !! Name !! Equivalent to
{{!-}}
{{!}} 10 {{!!}} {{Wikipedia|Newline}} {{!!}} <code>\n</code>
{{!-}}
{{!}} 9 {{!!}} {{Wikipedia|Tab key#Tab characters|Horizontal tab}} {{!!}} <code>\t</code>
{{!-}}
{{!}} 13 {{!!}} {{Wikipedia|Carriage return}} {{!!}} <code>\r</code>
{{!}}}
|param1 = code
|param1text = Integer character code for the desired glyph.
|example1 = print("Code 65 = ", chr(65)); # prints "Code 65 = A"
|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.
|example2 =
for(var i = 0; i <= 255; i += 1){
print("Code ", i, " = >", chr(i), "<");
}
}}

=== closure() ===
{{Nasal doc
|syntax = closure(func[, level]);
|source = {{simgear file|simgear/nasal/lib.c|l=557|t=Source}}
|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'''.
|param1 = func
|param1text = Function to evaluate.
|param2 = level
|param2text = Optional integer specifying the scope level. Defaults to 0 (the namespace of '''func''').
|example1 =
var get_math_e = func {
return e; # return the value of math.e
}

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
debug.dump(closure(myFunction)); # print the namespace of get_math_e

print(myFunction());
}}

=== cmp() ===
{{Nasal doc
|syntax = cmp(a, b);
|source = {{simgear file|simgear/nasal/lib.c|l=169|t=Source}}
|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'''.
|param1 = a
|param1text = First string argument for comparison.
|param2 = b
|param2text = Second string argument for comparison.
|example1 = print(cmp("1", "two")); # prints -1
|example2 = print(cmp("string", "string")); # prints 0
|example3 = print(cmp("one", "2")); # prints 1
|example4 = print(cmp("string1", "string2")); # prints -1
}}

=== compile() ===
{{Nasal doc
|syntax = compile(code[, filename]);
|source = {{simgear file|simgear/nasal/lib.c|l=349|t=Source}}
|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'''.
|param1 = code
|param1text = String containing Nasal code to be compiled.
|param2 = filename
|param2text = Optional string used for error messages/logging. Defaults to <code><compile></code>
|example1 =
var myCode = 'print("hello");';
var helloFunc = compile(myCode, "myCode");
helloFunc();
|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>.
<syntaxhighlight lang="xml">
<?xml version="1.0"?>

<PropertyList>

<nasal><![CDATA[
print("You have FlightGear v", getprop("/sim/version/flightgear"));
]]></nasal>

</PropertyList>
</syntaxhighlight>
Now, start FlightGear and execute this code in the [[Nasal Console]].
|example2 =
# Build the path
var FGRoot = getprop("/sim/fg-root");
var filename = "/gui/dialogs/test.xml";
var path = FGRoot ~ filename;

var blob = io.read_properties(path);
var script = blob.getValues().nasal; # Get the nasal string

# Compile the script. We're passing the filename here for better runtime diagnostics
var code = call(func {
compile(script, filename);
}, nil, nil, var compilation_errors = []);

if(size(compilation_errors)){
die("Error compiling code in: " ~ filename);
}

# Invoke the compiled script, equivalent to code();
# We're using call() here to detect errors:
call(code, [], nil, nil, var runtime_errors = []);

if(size(runtime_errors)){
die("Error calling code compiled loaded from: " ~ filename);
}
|example3text = The <code>compile()</code> function also allows you to parse a JSON string into a hash. Simplest example:
|example3 =
var jsonFunc = compile('{"version":"1.2.0","author":{"name":"John"} }');
var json = jsonFunc(); # return hash
logprint(LOG_ALERT, json["version"]); # print "1.2.0"
logprint(LOG_ALERT, json["author"]["name"]); # print "John"
}}

=== contains() ===
{{Nasal doc
|syntax = contains(hash, key);
|source = {{simgear file|simgear/nasal/lib.c|l=249|t=Source}}
|text = Returns 1 (True) if the hash contains the specified key, or 0 (False) if not.
|param1 = hash
|param1text = The hash to search in.
|param2 = key
|param2text = The scalar to be searched for, contained as a key in the hash.
|example1 =
# Initialize a hash
var hash = {
element: "value"
};
print(contains(hash, "element") ? "Yes" : "No"); # This will print "Yes"
print(contains(hash, "element2") ? "Yes" : "No"); # This will print "No"
}}

===contains()===
{{Requires commit|desc=Vector support|details=see {{Merge-request|project=fgdata|id=305}}|commit=ee39abbd3b70c9b6d5e3a1c4ccedddaac1a92b11|repo=Simgear}}
{{Nasal doc
|syntax = contains(vector, item);
|source = {{simgear file|simgear/nasal/lib.c|l=249|t=Source}}
|text = Returns 1 (True) if the vector contains the specified item, or 0 (False) if not.
|param1 = vector
|param1text = The vector to search in.
|param2 = item
|param2text = The object to be searched for in the vector.
|example1 =
# Initialize a vector
var vec = ["element", "foo"];
print(contains(vec, "element") ? "Yes" : "No"); # This will print "Yes"
print(contains(vec, "element2") ? "Yes" : "No"); # This will print "No"
}}

===delete() ===
{{Nasal doc
|syntax = delete(hash, key);
|source = {{simgear file|simgear/nasal/lib.c|l=118|t=Source}}
|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.
|param1 = hash
|param1text = The hash from which to delete the key.
|param2 = key
|param2text = The scalar to be deleted, contained as a key in the hash.
|example1 =
# Initialize the hash
var hash = {
element1: "value1",
element2: "value2"
};
delete(hash, "element1"); # Delete element1
debug.dump(hash); # prints the hash, which is now minus element1
}}

===die()===
{{Nasal doc
|syntax = die(error);
|source = {{simgear file|simgear/nasal/lib.c|l=417|t=Source}}
|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()}}.
|param1 = error
|param1text = String describing the error.
:{{inote|This parameter is technically optional, but it is highly recommended to use it.}}
|example1 =
print("Will print");
die("Don't go any further!");
print("Won't print"); # Will not be printed because die() stops the process
}}

=== find()===
{{Nasal doc
|syntax = find(needle, haystack);
|source = {{simgear file|simgear/nasal/lib.c|l=586|t=Source}}
|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.
|param1 = needle
|param1text = String to search for.
|param2 = haystack
|param2text = String to search in.
|example1 = print(find("c", "abcdef")); # prints 2
|example2 = print(find("x", "abcdef")); # prints -1
|example3 = print(find("cd", "abcdef")); # prints 2
}}

===ghosttype()===
{{Nasal doc
|syntax = ghosttype(ghost);
|source = {{simgear file|simgear/nasal/lib.c|l=336|t=Source}}
|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.
|param1 = ghost
|param1text = Ghost to return a description for.
|example1 = print(ghosttype(airportinfo())); # prints "airport"
}}

===id()===
{{Nasal doc
|syntax = id(object);
|source = {{simgear file|simgear/nasal/lib.c|l=706|t=Source}}
|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.
|param1 = object
|param1text = Can be either of a string, a vector, a hash, a code, a function, or a ghost.
|example1 = print(id("A")); # prints "str:000000001624A590"
}}

===int() ===
{{Nasal doc
|syntax = int(number);
|source = {{simgear file|simgear/nasal/lib.c|l=125|t=Source}}
|text = Returns the integer part of the numeric value of the single argument, or <code>'''nil'''</code> if none exists.
|param1 = number
|param1text = Number or string with just a number in it to return an integer from.
|example1 = print(int(23)); # prints "23"
|example2 = print(int(23.123)); # prints "23"
|example3 = debug.dump(int("string")); # prints "nil"
}}

===keys()===
{{Nasal doc
|syntax = keys(hash);
|source = {{simgear file|simgear/nasal/lib.c|l=36|t=Source}}
|text = Returns a vector containing the list of keys found in the single hash argument.
|param1 = hash
|param1text = The hash to return the keys from.
|example1 =
# Initialize a hash
var hash = {
element1: "value",
element2: "value"
};
debug.dump(keys(hash)); # print the vector
}}

===left()===
{{Nasal doc
|syntax = left(string, length);
|source = {{simgear file|simgear/nasal/lib.c|l=214|t=Source}}
|version = 2.12
|commit = {{simgear commit|bd7163|t=commit}}
|text = Returns a substring of '''string''', starting from the left.
|param1 = string
|param1text = String to return part of.
|param2 = length
|param2text = Integer specifying the length of the substring to return.
|example1 = print(left("string", 2)); # prints "st"
}}

=== num()===
{{Nasal doc
|syntax = num(number);
|source = {{simgear file|simgear/nasal/lib.c|l=149|t=Source}}
|text = Returns the numerical value of the single string argument, or <code>'''nil'''</code> if none exists.
|param1 = number
|param1text = String with just a number in it to return a number from.
|example1 = print(num("23")); # prints "23"
|example2 = print(num("23.123")); # prints "23.123"
|example3 = debug.dump(num("string")); # prints "nil"
}}

===pop()===
{{Nasal doc
|syntax = pop(vector);
|source = {{simgear file|simgear/nasal/lib.c|l=85|t=Source}}
|text = Removes and returns the last element of the single vector argument, or <code>'''nil'''</code> if the vector is empty.
|param1 = vector
|param1text = Vector to remove an element from.
|example1 =
var vector = [1, 2, 3];
pop(vector);
debug.dump(vector); # prints "[1, 2]"
|example2 =
var vector = [1, 2, 3];
debug.dump(pop(vector)); # prints "3"
|example3 =
var vector = [];
debug.dump(pop(vector)); # prints "nil"
}}

=== range() ===
{{Nasal doc
|syntax = range([start, ]stop[, step]);
|source = {{simgear file|simgear/nasal/lib.c|l=756|t=Source}}
|text = Creates a vector of numbers starting from <code>start</code> (default 0) up to but not including <code>stop</code>, incremented by <code>step</code> (default 1). Note: To specify <code>step</code>, you must also provide <code>start</code>; otherwise the second argument is interpreted as <code>stop</code>.
|param1 = start
|param1text = Optional. The starting number of the sequence. Defaults to 0 if omitted. Required if you want to specify <code>step</code>.
|param2 = stop
|param2text = Required. The number at which to stop the sequence (not included).
|param3 = step
|param3text = Optional. The increment between each number in the sequence. Defaults to 1. Only valid if <code>start</code> is also specified.
|example1 =
var vec = range(5); # Creates a vector [0, 1, 2, 3, 4]
var vec = range(2, 5); # Creates a vector [2, 3, 4]
var vec = range(0, 10, 2); # Creates a vector [0, 2, 4, 6, 8]
var vec = range(0, 0); # Creates an empty vector []
var vec = range(0, 1); # Creates a vector [0]
}}

=== remove() ===
{{Nasal doc
|syntax = remove(vector, value);
|source = {{simgear file|simgear/nasal/lib.c|l=53|t=Source}}
|text = Removes all elements equal to the given value from a vector and returns the modified vector.
|param1 = vector
|param1text = The vector from which elements are to be removed.
|param2 = value
|param2text = A value to remove from the vector.
|example1 =
var vector = [1, 2, 3]; # Initialize the vector.
remove(vector, 2); # Remove the value 2 from the vector.
debug.dump(vector); # Print the contents of the vector: "[1, 3]".
|example2 =
var vector = ["text", "text", "text"]; # Initialize the vector.
remove(vector, "text"); # Remove the value "text" from the vector.
debug.dump(vector); # Print the contents of the vector: "[]".
}}

=== removeat() ===
{{Nasal doc
|syntax = removeat(vector, index);
|source = {{simgear file|simgear/nasal/lib.c|l=72|t=Source}}
|text = Removes the element at the specified index from the vector and returns it.
|param1 = vector
|param1text = The vector from which the element will be removed.
|param2 = index
|param2text = Index of the item to be deleted.
|example1 =
var vector = [1, 2, 3]; # Initialize the vector.
removeat(vector, 0); # Remove the index 0 from the vector.
debug.dump(vector); # Print the contents of the vector: "[2, 3]".
}}

===right()===
{{Nasal doc
|syntax = right(string, length);
|source = {{simgear file|simgear/nasal/lib.c|l=226|t=Source}}
|version = 2.12
|commit = {{simgear commit|bd7163|t=commit}}
|text = Returns a substring of '''string''', starting from the right.
|param1 = string
|param1text = String to return part of.
|param2 = length
|param2text = Integer specifying the length of the substring to return.
|example1 = print(right("string", 2)); # prints "ng"
}}

=== setsize()===
{{Nasal doc
|syntax = setsize(vector, size);
|source = {{simgear file|simgear/nasal/lib.c|l=91|t=Source}}
|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.
|param1 = vector
|param1text = The vector to be operated on.
|param2 = size
|param2text = The desired size of the vector in number of entries.
|example1 =
var vector = [1, 2, 3]; # Initialize a vector
setsize(vector, 4);
debug.dump(vector); # print the vector "[1, 2, 3, nil]"
|example2 =
var vector = [1, 2, 3]; # Initialize a vector
setsize(vector, 2);
debug.dump(vector); # print the vector "[1, 2]"
}}

===size()===
{{Nasal doc
|syntax = size(object);
|source = {{simgear file|simgear/nasal/lib.c|l=26|t=Source}}
|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>.
|param1 = object
|param1text = Object to find the size of. Must be a string, a vector or a hash.
|example1 =
var string = "string";
print(size(string)); # prints "6"
|example2 =
var vector = [1, 2, 3];
print(size(vector)); # prints "3"
|example3 =
var hash = {
element1: "value1",
element2: "value2",
element3: "value3"
};
print(size(hash)); # prints "3"
}}

=== sort()===
{{Nasal doc
|syntax = sort(vector, function);
|source = {{simgear file|simgear/nasal/lib.c|l=678|t=Source}}
|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.
|param1 = vector
|param1text = Input vector to sort.
|param2 = function
|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.
{{{!}} class="wikitable"
! Return value !! Meaning
{{!-}}
{{!}} less than 0 {{!!}} first argument should go before second argument
{{!-}}
{{!}} 0 {{!!}} first argument equals second argument
{{!-}}
{{!}} greater than 0 {{!!}} first argument should go after second argument
{{!}}}

|example1text = This example sorts elements from smallest to greatest.
|example1 =
var sort_rules = func(a, b) {
if (a < b) {
return -1; # A should before b in the returned vector
} elsif (a == b) {
return 0; # A is equivalent to b
} else {
return 1; # A should after b in the returned vector
}
}
debug.dump(sort([3, 2, 5, 6, 4, 1], sort_rules)); # prints "[1, 2, 3, 4, 5, 6]"
|example2text = This example sorts elements from greatest to smallest.
|example2 =
# Outputs the elements in reverse order (greatest to smallest)
var sort_rules = func(a, b) {
if (a < b) {
return 1; # -1 in the above example
} elsif (a == b) {
return 0;
} else {
return -1; # 1 in the above example
}
}
debug.dump(sort([3, 2, 5, 6, 4, 1], sort_rules)); # prints "[6, 5, 4, 3, 2, 1]"
|example3text = This example sorts a vector of strings (runways for example) from smallest to greatest.
|example3 =
var runways = ["09R", "27R", "26L", "09L", "15"];
var rwy = sort(runways, func(a, b) cmp(a, b));
debug.dump(rwy); # prints ['09L', '09R', '15', '26L', '27R']
}}

=== split()===
{{Nasal doc
|syntax = split(delimiter, string);
|source = {{simgear file|simgear/nasal/lib.c|l=596|t=Source}}
|text = Splits the input string into a vector of substrings bounded by occurrences of the delimiter substring. See [[Nasal_library/string#string.join(sep,list)|string.join()]].
|param1 = delimiter
|param1text = String that will split the substrings in the returned vector.
|param2 = string
|param2text = String to split up.
|example1 = debug.dump(split("cd", "abcdef")); # prints "['ab', 'ef']"
|example2 = debug.dump(split(".", "3.2.0")); # prints "[3, 2, 0]"
|example3 = debug.dump(split("/", "path/to/file")); # prints "['path', 'to', 'file']"
}}

===sprintf()===
{{Nasal doc
|syntax = <nowiki>sprintf(format[, arg[, arg, [...]]]);</nowiki>
|source = {{simgear file|simgear/nasal/lib.c|l=491|t=Source}}
|text = Creates and returns a string formatted using ANSI C {{func link|vsnprintf()|link=http://en.cppreference.com/w/c/io/vfprintf}} <ref>
{{Cite web
|url = http://sourceforge.net/p/flightgear/simgear/ci/next/tree/simgear/nasal/lib.c#l308
|title = fgdata/simgear/simgear/nasal/lib.c, line 308
|accessdate = October 2015
}}
</ref>. Below is a table of supported format specifiers.
{{{!}} class="wikitable" width="75%"
{{!}}+ %[flags][width][.precision]specifier
! colspan="2" {{!}} Flags
{{!-}}
! Flag !! Output
{{!-}}
{{!}} <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.
{{!-}}
{{!}} ''space'' {{!!}} Prefixes non-signed numbers with a space.
{{!-}}
{{!}} <code>-</code> {{!!}} Left-align the output of this placeholder (the default is to right-align the output) when the width option is specified.
{{!-}}
{{!}} <code>0</code> {{!!}} Use 0 instead of spaces to pad a field when the width option is specified.
{{!-}}
{{!}} <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.
{{!-}}
! colspan="2" {{!}} Width
{{!-}}
{{!}} 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.
{{!-}}
! colspan="2" {{!}} Precision
{{!-}}
{{!}} colspan="2" {{!}} Integer preceded by a dot specifying the number of decimal places to be written.
{{!-}}
! colspan="2" {{!}} Specifiers
{{!-}}
! Specifier !! Output
{{!-}}
{{!}} <code>d</code>, <code>i</code> {{!!}} Signed decimal number.
{{!-}}
{{!}} <code>s</code> {{!!}} A string
{{!-}}
{{!}} <code>%</code> {{!!}} Percent (%) character.
{{!-}}
{{!}} <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.
{{!-}}
{{!}} <code>o</code> {{!!}} Unsigned integer as an octal number.
{{!-}}
{{!}} <code>u</code> {{!!}} Unsigned decimal integer.
{{!-}}
{{!}} <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.
{{!-}}
{{!}} <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.
{{!-}}
{{!}} <code>f</code> {{!!}} Floating-point number, in fixed decimal notation, by default with 6 decimal places.
{{!-}}
{{!}} <code>F</code> {{!!}} Appears to be available<ref>
{{Cite web
|url = http://sourceforge.net/p/flightgear/simgear/ci/next/tree/simgear/nasal/lib.c#l389
|title = fgdata/simgear/simgear/nasal/lib.c, line 389
|accessdate = October 2015
}}
</ref>, but doesn't work.
{{!-}}
{{!}} <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.
{{!}}}

|param1 = format
|param1text = String specifying the format. Can be used with or without a format specifiers. See below for examples.
|param2 = arg
|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.

|example1 = print(sprintf("%i", 54)); # prints "54"
|example2 = print(sprintf("Pi = %+.10f", math.pi)); # prints "Pi = +3.1415926536"
|example3 =
print(sprintf("%6d", 23)); # prints " 23"
print(sprintf("%06d", 23)); # prints "000023"
|example4 =
var FGVer = getprop("/sim/version/flightgear");
print(sprintf("You have FlightGear v%s", FGVer)); # prints "You have FlightGear v<your version>"
|example5 =
print(sprintf("Hexadecimal 100000 = %X", 100000)); # prints "Hexadecimal 100000 = 186A0"
print(sprintf("Hexadecimal 100000 = %x", 100000)); # prints "Hexadecimal 100000 = 186a0"
|example6 = print(sprintf("Code 65 is %c", 65)); # prints "Code 65 is A"
|example7 =
print(sprintf("%e", 54)); # prints "5.400000e+001"
print(sprintf("%E", 54)); # prints "5.400000E+001"
|example8 = print(sprintf("%o", 54)); # prints "66"
|example9 = print(sprintf("50%% of 100 is %i", 100 / 2)); # prints "50% of 100 is 50"
|example10 =
print(sprintf("%.2f", 1.4)); #prints "1.40"
print(sprintf("%.1f", 1.4)); #prints "1.4"
print(sprintf("% 4.1f", 1.4)); #prints " 1.4"
print(sprintf("%04.1f", 1.4)); #prints "01.4"
print(sprintf("% 6.1f", 1.4)); #prints " 1.4"
print(sprintf("%06.1f", 1.4)); #prints "0001.4"
}}

===str()===
{{Nasal doc
|syntax = str(value);
|source = {{simgear file|simgear/nasal/lib.c|l=186|t=Source}}
|text = Convert given value (scalar) to string. If <code>value</code> is a number, it will be converted to a string. If <code>value</code> is a string, the same string will be returned. If <code>value</code> is not a scalar (hash, vector, nil), <code>nil</code> will be returned.
|param1 = value
|param1text = The value to convert to string.
|example1 =
var result = str(12); # result is a string "12"
var result = str(12.5); # result is a string "12.5"
var result = str("12.5"); # result is a string "12.5"
var result = str([1, 2]); # result is a nil
var result = str({ x: 0 }); # result is a nil
var result = str(nil); # result is a nil
}}

===streq()===
{{Nasal doc
|syntax = streq(a, b);
|source = {{simgear file|simgear/nasal/lib.c|l=164|t=Source}}
|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.}}
|param1 = a
|param1text = First argument for testing equality.
|param2 = b
|param2text = Second argument for testing equality.
|example1 = print(streq("0", "0")); # prints "1" (True)
|example2 =
print(0 == 0.0); # prints "1" (True)
print(streq("0", "0.0")); # prints "0" (False)
}}

===substr()===
{{Nasal doc
|syntax = substr(string, start [, length]);
|source = {{simgear file|simgear/nasal/lib.c|l=194|t=Source}}
|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).
|param1 = string
|param1text = String to return a substring from.
|param2 = start
|param2text = Integer specifying the start of a substring. Negative values specify a position from the end of the string.
|param3 = length
|param3text = Optional argument specifying the length of the substring. Defaults to the end of the string.
|example1 = print(substr("abcde", 1, 3)); # prints "bcd"
|example2 = print(substr("abcde", 1)); # prints "bcde"
|example3 = print(substr("abcde", 2, 1)); # prints "c"
|example4 = print(substr("abcde", -2)); # prints "de"
|example5 = print(substr("abcde", -3, 2)); # prints "cd"
}}

===subvec()===
{{Nasal doc
|syntax = subvec(vector, start[, length]);
|source = {{simgear file|simgear/nasal/lib.c|l=98|t=Source}}
|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).
|param1 = vector
|param1text = The vector to take the sub-vector from.
|param2 = start
|param2text = The starting point of the sub-vector within the given vector.
|param3 = length
|param3text = Optional argument specifying the length of the sub-vector, from the starting point.
'''Notes:'''
* Omitting the ''vector'' and ''start'' arguments is not an error (possibly it should be) but the return value is ''nil''.
* A negative ''start'' argument ''is'' an error. This seems wrong. Perhaps the language designer could comment.
* A value of ''start'' greater than ''size(vector)'' causes an error. A value equal to ''size(vector)'' returns an empty vector.
* 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.
|example1 =
var vector = [1, 2, 3];
debug.dump(subvec(vector, 0)); # prints "[1, 2, 3]"
|example2 =
var vector = [1, 2, 3];
debug.dump(subvec(vector, 1)); # prints "[2, 3]"
|example3 =
var vector = [1, 2, 3];
debug.dump(subvec(vector, 1, 1)); # prints "[2]"
}}

=== typeof()===
{{Nasal doc
|syntax = typeof(object);
|source = {{simgear file|simgear/nasal/lib.c|l=287|t=Source}}
|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.
|param1 = object
|param1text = Object to return the type of.
|example1 =
var object = nil;
print(typeof(object)); # prints "nil"
|example2 =
var object = "Hello world!";
print(typeof(object)); # prints "scalar"
|example3 =
var object = math.pi;
print(typeof(object)); # prints "scalar"
|example4 =
var object = [1, 2, 3];
print(typeof(object)); # prints "vector"
|example5 =
var object = {};
print(typeof(object)); # prints "hash"
|example6 =
var object = func {};
print(typeof(object)); # prints "func"
|example7 =
var object = airportinfo();
print(typeof(object)); # prints "ghost"
}}



==Extension functions==
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:
*{{flightgear file|src/Scripting/NasalPositioned.cxx}}
*{{flightgear file|src/Scripting/NasalSys.cxx}}
*{{fgdata file|Nasal/globals.nas}}

===abort()===
{{Nasal doc
|syntax = abort();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=565|t=Source}}
|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).
|example1text = This example will immediately stop FlightGear with an error, such as "FlightGear has stopped working."
|example1 = abort();
|example2text = For exiting FlightGear in a better way, please use the following code:
|example2 = fgcommand("exit");
}}

=== abs() ===
{{Nasal doc
|syntax = abs(number);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = This simple function returns the {{wikipedia|absolute value|noicon=1}} of the provided number.
|param1 = number
|param1text = This argument is required and should be a number.
|example1 = print(abs(1)); # prints "1"
|example2 = print(abs(-1)); # prints "1"
}}

===aircraftToCart() ===
This new function in FG 2017.2.1 takes coordinates in aircraft structural coordinate system, and translate them into geocentric coordinates.
Example for (5,6,7):
<syntaxhighlight lang="nasal">
var pos = aircraftToCart({x: -5, y: 6, z: -7});
var coord = geo.Coord.new();
coord.set_xyz(pos.x, pos.y, pos.z);
</syntaxhighlight>
Notice: x and z is inverted sign on purpose.
if you want lat. lon, alt from that, just call: (degrees and meters)

<syntaxhighlight lang="nasal">
coord.lat()
coord.lon()
coord.alt()
</syntaxhighlight>

===addcommand() ===
{{Nasal doc
|syntax = addcommand(name, code);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=659|t=Source}}
|version = 2.12
|commit = {{flightgear commit|7b663c|t=commit}}
|text = {{see also|Howto:Add new fgcommands to FlightGear}}

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.
|param1 = name
|param1text = This will become the name of the new fgcommand. Must be a string.
|param2 = code
|param2text = The code that will be executed when the fgcommand is run. Must be a function.
|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.
|example1 = addcommand("myFGCmd", func(node) {
print("fgcommand 'myFGCmd' has been run.");
props.dump( node );
});
fgcommand("myFGCmd", props.Node.new({foo:1, bar:2}) );
|example2text = This example demonstrates how parameters are defined in a new fgcommand.
|example2 = addcommand("myFGCmd", func(node){
print(node.getNode("number").getValue()); # prints the value of "number," which is 12
});
fgcommand("myFGCmd", props.Node.new({"number": 12}));
}}

===airportinfo()===
{{Nasal doc
|syntax = airportinfo();
airportinfo(type);
airportinfo(id);
airportinfo(lat, lon[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1024|t=Source}}
|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:
* '''parents''': A vector containing a hash of various functions to access information about the runway. These functions are:
** '''findBestRunwayForPos()''' return runway as ghost by given geo position, e.g. <code>var rwy = airportinfo().findBestRunwayForPos(geo.aircraft_position());</code>.
** '''runway()''' return runway as ghost by runway ID, e.g. <code>var rwy = airportinfo().runway("18R");</code>.
** '''runwaysWithoutReciprocals()''' return vector of runways as ghost.
** '''helipad()''' return helipad as ghost by helipad ID, e.g. <code>var heli = airportinfo().helipad("H19");</code>.
** '''tower()''' return hash with <code>lat</code>, <code>lon</code>, <code>elevation</code> fields.
** '''comms()''' return vector of hashes, each hash with <code>frequency</code> and <code>ident</code> fields.
** '''sids()''' return vector of strings with SID IDs.
** '''stars()''' return vector of strings with STAR IDs.
** '''getApproachList()''' return vector of string with approaches.
** '''parking()''' return vector of hashes, each hash with <code>lat</code>, <code>lon</code>, <code>elevation</code>, <code>name</code> fields.
** '''getSid()''' return SID as ghost, e.g. <code>var sid = airportinfo().getSid("SA1A");</code>.
** '''getStar()''' return STAR as ghost, e.g. <code>var star = airportinfo().getStar("KEILA1");</code>.
** '''getIAP()''' return IAP as ghost, e.g. <code>var iap = airportinfo().getIAP("ILS02");</code>.
** '''getApproach()''' return approach as ghost, e.g. <code>var approach = airportinfo().getApproach("ILS02");</code>.
** '''tostring()''' just return string "an airport ICAO".
** See also {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1902}}.
* '''lon''': Longitude of the location.
* '''lat''': Latitude of the location.
* '''has_metar''': True or false depending whether the airport has a [[METAR]] code defined for it.
* '''elevation''': Elevation of the location in metres.
* '''id''': ICAO code of the airport (or ID of the seaplane base/heliport).
* '''name''': Name of the airport/heliport/seaplane base.
* '''runways'''
** '''<runway name>'''
*** '''id''': Name of runway.
*** '''lat''': Latitude of the runway.
*** '''lon''': Longitude of the runway.
*** '''heading''': True heading of the runway.
*** '''length''': Length of the runway in metres.
*** '''width''': Width of the runway in metres.
*** '''surface''': Runway surface type.
*** '''threshold''': Length of the runway's {{wikipedia|displaced threshold}} in metres. Will return 0 if there is none.
*** '''stopway''': Length of the runway's stopway (the area before the threshold) in metres. Will return 0 if there is none.
*** '''reciprocal''': <code>runway</code> ghost of the reciprocal runway.
*** '''ils_frequency_mhz''': ILS frequency in megahertz.
*** '''ils''': <code>navaid</code> ghost of the ILS transmitter.
* '''helipads'''
** '''<helipad name>'''
*** '''id''': Name of helipad.
*** '''lat''': Latitude of the helipad.
*** '''lon''': Longitude of the helipad.
*** '''heading''': True heading of the helipad.
*** '''length''': Length of the helipad in metres.
*** '''width''': Width of the helipad in metres.
*** '''surface''': Helipad surface type.
* '''taxiways'''
** '''<taxiway name>'''
*** '''id''': Name of taxiway.
*** '''lat''': Latitude of the taxiway.
*** '''lon''': Longitude of the taxiway.
*** '''heading''': Heading of the taxiway.
*** '''length''': Length of the taxiway in metres.
*** '''width''': Width of the taxiway in metres.
*** '''surface''': Taxiway surface type.

Information is extracted in the same way as accessing members of a Nasal hash. For example:
<syntaxhighlight lang="nasal">
# prints to lengths of the runways of the nearest airport in feet and metres
var info = airportinfo();
print("-- Lengths of the runways at ", info.name, " (", info.id, ") --");
foreach(var rwy; keys(info.runways)){
print(rwy, ": ", math.round(info.runways[rwy].length * M2FT), " ft (", info.runways[rwy].length, " m)");
}
</syntaxhighlight>

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.
|param1 = id
|param1text = The {{wikipedia|International Civil Aviation Organization airport code|ICAO code|noicon=1}} of an airport to retrieve information about.
|param2 = type
|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).
: {{inote|Running this function without any parameters is equivalent to this:
: <syntaxhighlight lang="nasal">
airportinfo("airport");
</syntaxhighlight>
}}
|param3 = lat ''and'' lon
|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.
|example1 = var info = airportinfo();
print("Nearest airport: ", info.name, " (", info.id, ")"); # prints the name and ICAO code of the nearest airport
|example2 = var info = airportinfo("heliport");
print("Elevation of the nearest heliport: ", math.round(info.elevation * M2FT), " ft"); # prints the elevation and name of the nearest heliport
|example3 = var info = airportinfo("KSQL");
print("-- Runways of ", info.name, " (", info.id, "): --");
foreach(var rwy; keys(info.runways)) {
print(rwy); # prints the runways of KSQL
}
|example4 = var info = airportinfo(37.81909385, -122.4722484);
print("Coordinates of the nearest airport: ", info.lat, ", ", info.lon); # print the name and ICAO of the nearest airport to the Golden Gate Bridge
|example5 = var info = airportinfo(37.81909385, -122.4722484, "seaport");
print("Nearest seaplane base: ", info.name, " (", info.id, ")"); # print the name and ID of the nearest seaplane base to the Golden Gate Bridge
|example6text = This example prints the all information from an <code>airportinfo()</code> call.
|example6 = var info = airportinfo("KSFO");
print(info.name);
print(info.id);
print(info.lat);
print(info.lon);
print(info.has_metar);
print(info.elevation);
foreach(var rwy; keys(info.runways)){
print("-- ", rwy, " --");
print(info.runways[rwy].lat);
print(info.runways[rwy].lon);
print(info.runways[rwy].length);
print(info.runways[rwy].width);
print(info.runways[rwy].heading);
print(info.runways[rwy].stopway);
print(info.runways[rwy].threshold);
<nowiki>}</nowiki>
}}

===airwaysRoute() ===
{{Nasal doc
|syntax = airwaysRoute(start, end[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1933|t=Source}}
|text = {{see also|Nasal Flightplan}}
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.
|param1 = start
|param1text = Start waypoint, in the form of a waypoint ghost, such as that provided by {{func link|flightplan()}}.
|param2 = end
|param2text = Same as above.
|param3 = type
|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."
|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.
|example1 = var fp = flightplan();
var start = fp.getWP(0);
var end = fp.getWP(fp.getPlanSize() - 1);
var rt = airwaysRoute(start, end);
foreach(var wp; rt){
print(wp.wp_name); # print the waypoints in the computed route
}
|example2text = Exactly the same as above, but computes a low level path.
|example2 = var fp = flightplan();
var start = fp.getWP(0);
var end = fp.getWP(fp.getPlanSize() - 1);
var rt = airwaysRoute(start, end, "lowlevel");
foreach(var wp; rt){
print(wp.wp_name); # print the waypoints in the computed route
<nowiki>}</nowiki>
}}

===airway()===

{{Nasal doc
|syntax = airway(ident [, pos]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2644|t=Source}}
|text = {{see also|Nasal Flightplan}}
This function returns a ghost containing an airway of a specified id.
|param1 = ident
|param1text = a Positioned ghost (leg, navaid, airport) and so on, passed to the search function.
|param2 = pos
}}

===assert()===
{{Nasal doc
|syntax = assert(condition[, message]);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|version = 3.2
|commit = {{fgdata commit|8b16a7|t=commit}}
|text = Returns either true if the condition evaluates as true, or aborts with a {{func link|die()}} call, which can be customised.
|param1 = condition
|param1text = Condition to evaluate.
|param2 = message
|param2text = Optional message that will be used in any {{func link|die()}} call. Defaults to "assertion failed!"
|example1 = var a = 1;
var b = 2;
print(assert(a < b)); # prints "1" (true)
|example2 = var a = 1;
var b = 2;
assert(a > b, 'a is not greater than b'); # aborts with a custom error message
}}

===carttogeod()===
{{Nasal doc
|syntax = carttogeod(x, y, z);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=945|t=Source}}
|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>
|param1 = x
|param1text = Mandatory x-axis value, in metres.
|param2 = y
|param2text = Mandatory y-axis value, in metres.
|param3 = z
|param3text = Mandatory z-axis value, in metres.
|example1 = var (lat, lon, alt) = carttogeod(6378137, 0, 0); # point is the intersection of the prime meridian and equator.
print("Latitude: ", lat); # prints lat, lon and alt, which are all zero, see above
print("Longitude: ", lon);
print("Altitude: ", alt);
}}

===cmdarg()===
{{Nasal doc
|private = _cmdarg()
|syntax = cmdarg();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=513|t=Part 1}} {{!}} {{fgdata file|Nasal/globals.nas|t=Part 2}}
|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.
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:
* Bindings: This is needed so that the value of a joystick's axis can be accessed internally.
* 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).
* 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.
* 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>

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.

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.
|example1 = fgcommand("dialog-show", {"dialog-name": "cmdarg-demo"});
|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.
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>

<PropertyList>

<name>cmdarg-demo</name>
<layout>vbox</layout>

<text>
<label>Click "Close" to activate the demonstration (a message in the console).</label>
</text>

<button>
<legend>Close</legend>
<binding>
<command>nasal</command>
<script>print("Button binding root: '" ~ cmdarg().getPath() ~ "'");</script>
</binding>
<binding>
<command>dialog-close</command>
</binding>
</button>

</PropertyList>
</syntaxhighlight>
|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!"
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>

<PropertyList>

<name>cmdarg-demo</name>
<layout>vbox</layout>

<text>
<label>Click "Click me!" to activate the demonstration (the button's label will change).</label>
</text>

<button>
<legend>Click me!</legend>
<binding>
<command>nasal</command>
<script>change_label();</script>
</binding>
</button>

<button>
<legend>Close</legend>
<binding>
<command>dialog-close</command>
</binding>
</button>

<nasal>
<open><![CDATA[
var dlg_root = cmdarg();
var dlg_name = {"dialog-name": "cmdarg-demo"};
var change_label = func {
dlg_root.getNode("button[0]/legend").setValue("I've been changed!");
fgcommand("dialog-close", dlg_name);
fgcommand("dialog-show", dlg_name);
}
]]></open>
</nasal>

</PropertyList>
</syntaxhighlight>
|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]].
}}

===courseAndDistance()===
{{Nasal doc
|syntax = courseAndDistance(to);
courseAndDistance(from, to);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1668|t=Source}}
|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:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object with geodetic coordinates (cartesian coordinates will not be accepted)
|param1 = from
|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.
|param2 = to
|param2text = Like the first parameter, but defines the second point.
|example1text = This example demonstrates the usage of the function with the <code>airport</code> ghost type.
|example1 = var from = airportinfo("KSFO");
var to = airportinfo("KSQL");
var (course, dist) = courseAndDistance(from, to);
print(course); # prints course from KSFO to KSQL
print(dist); # prints distance in nm from KSFO to KSQL
|example2text = This example demonstrates the usage of the function with hashes containing ''lat'' and ''lon''.
|example2 = var from = {lat: 0, lon: 0};
var to = {lat: 1, lon: 1};
var (course, dist) = courseAndDistance(from, to);
print(course);
print(dist);
|example3text = This example demonstrates usage of a geo.Coord object.
|example3 = var from = geo.Coord.new().set_latlon(0, 0);
var to = geo.Coord.new().set_latlon(1, 1);
var (course, dist) = courseAndDistance(from, to);
print(course);
print(dist);
|example4text = This example demonstrates usage of differing parameter types.
|example4 = var from = airportinfo("KSFO");
var to = geo.Coord.new().set_latlon(0, 0);
var (course, dist) = courseAndDistance(from, to);
print(course);
print(dist);
|example5text = The same as above, but the other way round.
|example5 = var to = {lat: 1, lon: 1};
var (course, dist) = courseAndDistance(0, 0, to);
print(course);
print(dist);
|example6text = Usage of just one parameter.
|example6 = var dest = airportinfo("KSQL");
var (course, dist) = courseAndDistance(dest);
print("Turn to heading ", math.round(course), ". You have ", sprintf("%.2f", dist), " nm to go");
}}

===createFlightplan()===
{{Nasal doc
|syntax = createFlightplan(path);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2331|t=Source}}
|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.
|param1 = path
|param1text = Optional parameter defining the file from which a flightplan will be populated.
|example1 =
var path = getprop("/sim/fg-home") ~ "/Export/test.fgfp";
var flightplan = createFlightplan(path);
debug.dump(flightplan);
}}

===createDiscontinuity()===
{{Nasal doc
|syntax = createDiscontinuity();
|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.
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2045|t=Source}}
|version = 2016.1
|commit = {{flightgear commit|caead6|t=commit}}
}}
===createViaTo()===
{{Nasal doc
|syntax = createViaTo(airway, waypoint);
|text = Returns a <code>waypoint</code> ghost object. It represents a route "via '''airway''' to '''waypoint'''".
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=2009|t=Source}}
|version = 2016.1
|commit = {{flightgear commit|caead6|t=commit}}
|param1 = airway
|param1text = The name of an airway.
|param2 = waypoint
|param2text = Must be in the airway and one of:
* The name of a waypoint.
* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, or <code>fix</code> ghost object.
}}
===createWP()===
{{Nasal doc
|syntax = createWP(pos, name[, flag]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1964|t=Source}}
|text = Creates a new waypoint ghost object.
|param1 = pos
|param1text = Dictates the position of the new waypoint. It can be one of the following:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. See example 4 below.
|param2 = name
|param2text = String that will become the name of the new waypoint.
|param3 = flag
|param3text = Optional string that will tell FlightGear what type of waypoint it is. Must be one of "sid," "star," "approach," "missed," or "pseudo."
|example1text = Creates a waypoint directly in front and 1 km away and appends it to the flight plan.
|example1 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);
var wp = createWP(pos, "NEWWP");
var fp = flightplan();
fp.appendWP(wp);
|example2 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);
var wp = createWP({lat: pos.lat(), lon: pos.lon()}, "NEWWP");
var fp = flightplan();
fp.appendWP(wp);
|example3 = var apt = airportinfo();
var wp = createWP(apt, "NEWWP");
var fp = flightplan();
fp.appendWP(wp);
|example4 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);
var wp = createWP(pos.lat(), pos.lon(), "NEWWP");
var fp = flightplan();
fp.appendWP(wp);
|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.
|example5 = var pos = geo.aircraft_position().apply_course_distance(getprop("/orientation/heading-deg"), 1000);
var wp = createWP(pos, "NEWWP", "pseudo");
var fp = flightplan();
fp.appendWP(wp);
print(fp.getPlanSize());
fp.clearWPType("pseudo");
print(fp.getPlanSize());
}}

===createWPFrom()===
{{Nasal doc
|syntax = createWPFrom(object[, flag]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1989|t=Source}}
|text = Creates a new waypoint object from another object.
|param1 = object
|param1text = A ghost object. Must be a ghost type that is one of "airport," "navaid," "runway," or "fix."
|param2 = flag
|param2text = Optional string that will tell FlightGear what type of waypoint it is. Must be one of "sid," "star," "approach," "missed," or "pseudo."
|example1text = Creates a new waypoint and appends it to the flight plan.
|example1 = var apt = airportinfo("KSFO");
var wp = createWPFrom(apt);
var fp = flightplan();
fp.appendWP(wp);
|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.
|example2 = var apt = airportinfo("KSFO");
var wp = createWPFrom(apt, "pseudo");
print(wp.wp_name);
var fp = flightplan();
fp.appendWP(wp);
print(fp.getPlanSize());
fp.clearWPType("pseudo");
print(fp.getPlanSize());
}}

===defined()===
{{Nasal doc
|syntax = defined(symbol);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = Returns 1 (true) or 0 (false) depending on whether a variable exists.
|param1 = symbol
|param1text = A string that will be what the function searches for.
|example1 = var number = 12;
var check_exist = func {
print("Variable 'number' ", defined("number") == 1 ? "exists" : "does not exist"); # 'number' does exist
print("Variable 'number2' ", defined("number2") == 1 ? "exists" : "does not exist"); # 'number2' does not exist
}
check_exist();
}}

===directory()===
{{Nasal doc
|syntax = directory(path);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=572|t=Source}}
|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.
{{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.}}
|param1 = path
|param1text = Absolute file path.
|example1text = Gets the folders and files in [[$FG_ROOT]], and then removes the extra first two elements (see note above).
|example1 = var dir = directory(getprop("/sim/fg-root")); # get directory
dir = subvec(dir, 2); # strips off the first two elements
debug.dump(dir); # dump the vector
}}

===fgcommand()===
{{Nasal doc
|syntax = fgcommand(cmd[, args]);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=456|t=Part 1}} {{!}} {{fgdata file|Nasal/globals.nas|t=Part 2}}
|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.
|param1 = cmd
|param1text = String that is the name of the command that is to be run.
|param2 = args
|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).
|example1 = fgcommand("null"); # does nothing
|example2 = var args = props.Node.new({'script': 'print("Running fgcommand");'});
if (fgcommand("nasal", args)) { # prints "Running fgcommand" and then one of these print statements
print("Fgcommand succeeded");
} else {
print("Fgcommand encountered a problem");
}
|example3 = var args = { 'dialog-name': 'about' };
fgcommand("dialog-show", args); # shows the 'about' dialog
}}

===findAirportsByICAO() ===
{{Nasal doc
|syntax = findAirportsByICAO(search[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1096|t=Source}}
|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.
|param1 = search
|param1text = Search string for the function. Can either be a partial or a full ICAO code.
:{{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.}}
|param2 = type
|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."
|example1 = var apts = findAirportsByICAO("KSF"); # finds all airports matching "KSF"
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")"); # prints them
}
|example2 = var apts = findAirportsByICAO("SP0", "seaport"); # finds all seaplane bases matching "SP0"
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")"); # prints them
}
|example3 = var apt = findAirportsByICAO("XBET"); # one way to check if an airport does exist"
if (size(apt) == 0) {
print("Airport does not exist"); # this one will be printed
} else {
print("Airport does exist");
<nowiki>}</nowiki>
}}

===findAirportsWithinRange()===
{{Nasal doc
|syntax = findAirportsWithinRange([pos, ]range[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1066|t=Source}}
|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.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findAirportsWithinRange(lat, lon, range, type);</code>.
|param2 = range
|param2text = Mandatory number giving the range in nautical miles within which to search for airports/heliports/seaplane bases.only airports are searched for.
|param3 = type
|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."
|example1text = Searches for airports within 10 nm of [[KSFO]].
|example1 = var pos = airportinfo("KSFO");
var apts = findAirportsWithinRange(pos, 10);
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")");
}
|example2text = Searches for seaplane bases within 15 nm of [[KSFO]].
|example2 = var pos = airportinfo("KSFO");
var apts = findAirportsWithinRange(pos, 15, "seaport");
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")");
}
|example3text = Searches for airports within 10 nm of your current position.
|example3 = var apts = findAirportsWithinRange(10);
foreach(var apt; apts){
print(apt.name, " (", apt.id, ")");
<nowiki>}</nowiki>
}}

===findCommByFrequencyMHz()===
findCommByFrequencyMHz([pos, ]freq[, type]);
[[sourceforge:p/flightgear/flightgear/ci/next/tree/src/Scripting/NasalPositioned.cxx#l1547|source]]

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.

'''pos'''

: Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findCommByFrequencyMHz(lat, lon, freq, type);</code>.
; freq
: Frequency, in megahertz, of the station to search for.
; type
: 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)
'''Example'''
var com = findCommByFrequencyMHz(123.6);
print("ID: ", com.id); # prints info about the comm station
print("Name: ", com.name);
print("Latitude: ", com.lat);
print("Longitude: ", com.lon);
print("Type: ", com.type);
print("Frequency: ", sprintf("%.3f", com.frequency), " Mhz");

=== findFixesByID() ===
{{Nasal doc
|syntax = findFixesByID([pos, ]id);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1627|t=Source}}
|text = Returns a vector containing <code>fix</code> ghost objects matching a given ID, sorted by range from a certain position.
{{inote|Fixes are (usually) also known as waypoints.}}
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findFixesByID(lat, lon, id);</code>.
|param2 = id
|param2text = Full or partial ID of the fix to search for.
:{{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.}}
|example1 = var fixes = findFixesByID("POGIC");
foreach(var fix; fixes){
print(fix.id, " - lat: ", fix.lat, " {{!}} lon: ", fix.lon); # prints information about POGIC
}
|example2 = var fix = findFixesByID("ZUNAP");
fix = fix[0];
var (course, dist) = courseAndDistance(fix);
print("Turn to heading ", math.round(course), ". You have ", sprintf("%.2f", dist), " nm to go to reach ", fixes[0].id);
}}

===findNavaidByFrequencyMHz()===
{{Nasal doc
|syntax = findNavaidByFrequencyMHz([pos, ]freq[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1547|t=Source}}
|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.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidByFrequencyMHz(lat, lon, freq, type);</code>.
|param2 = freq
|param2text = Frequency, in megahertz, of the navaid to search for.
|param3 = type
|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}}.
|example1 = var navaid = findNavaidByFrequencyMHz(109.55);
print("ID: ", navaid.id); # prints info about the navaid
print("Name: ", navaid.name);
print("Latitude: ", navaid.lat);
print("Longitude: ", navaid.lon);
print("Elevation (AMSL): ", navaid.elevation, " m");
print("Type: ", navaid.type);
print("Frequency: ", sprintf("%.3f", navaid.frequency / 100), " Mhz");
print("Range: ", navaid.range_nm, " nm");
if(navaid.course) print("Course: ", navaid.course);
}}

=== findNavaidsByFrequencyMHz()===
{{Nasal doc
|syntax = findNavaidsByFrequencyMHz([pos, ]freq[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1572|t=Source}}
|text = Returns a vector conatining <code>navaid</code> ghost objects for navaids that match a given frequency, sorted from nearest to furthest.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidsByFrequencyMHz(lat, lon, freq, type);</code>.
|param2 = freq
|param2text = Frequency, in megahertz, of the navaid to search for.
|param3 = type
|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}}.
|example1 = var navaids = findNavaidsByFrequencyMHz(109.55);
foreach(var navaid; navaids){
print("--");
print("ID: ", navaid.id); # prints info about the navaid
print("Name: ", navaid.name);
print("Latitude: ", navaid.lat);
print("Longitude: ", navaid.lon);
print("Elevation (AMSL): ", navaid.elevation, " m");
print("Type: ", navaid.type);
print("Frequency: ", sprintf("%.3f", navaid.frequency / 100), " Mhz");
print("Range: ", navaid.range_nm, " nm");
if(navaid.course) print("Course: ", navaid.course);
print("--");
<nowiki>}</nowiki>
}}

===findNavaidsByID()===
{{Nasal doc
|syntax = findNavaidsByID([pos, ]id[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1600|t=Source}}
|text = Returns a vector containing <code>navaid</code> ghost objects matching a given ID, sorted by range from a certain position.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidsByID(lat, lon, id, type);</code>.
|param2 = id
|param2text = Full or partial ID of the fix to search for.
:{{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.}}
|param3 = type
|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}}.
|example1 = var navaid = findNavaidsByID("MXW");
navaid = navaid[0];
print("ID: ", navaid.id); # prints info about 'MXW' (a VOR station)
print("Name: ", navaid.name);
print("Latitude: ", navaid.lat);
print("Longitude: ", navaid.lon);
print("Elevation (AMSL): ", navaid.elevation, " m");
print("Type: ", navaid.type);
print("Frequency: ", sprintf("%.3f", navaid.frequency / 1000), " Mhz");
print("Range: ", navaid.range_nm, " nm");
}}

===findNavaidsWithinRange()===
{{Nasal doc
|syntax = findNavaidsWithinRange([pos, ]range[, type]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1518|t=Source}}
|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.
|param1 = pos
|param1text = Optional position to search around. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost type
:* A hash with ''lat'' and ''lon'' members
:* A geo.Coord object
:* Two numbers separated by a comma, as if the function is taking three arguments. Example: <code>findNavaidsWithinRange(lat, lon, range, type);</code>.
|param2 = range
|param2text = Mandatory number giving the range in nautical miles within which to search for navaids.
|param3 = type
|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}}.
|example1text = Searches for navaids within 10 nm of [[KSFO]].
|example1 = var pos = airportinfo("KSFO");
var navs = findNavaidsWithinRange(pos, 10);
foreach(var nav; navs){
print(nav.name, " (ID: ", nav.id, ")");
}
|example2text = Searches for navaids within 10 nm of your current position.
|example2 = var navs = findNavaidsWithinRange(10);
foreach(var nav; navs){
print(nav.name, " (ID: ", nav.id, ")");
<nowiki>}</nowiki>
}}

===finddata()===
{{Nasal doc
|syntax = finddata(path);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=603|t=Source}}
|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]].
|param1 = path
|param1text = A relative path as a string.
|example1 = var path = finddata("Aircraft/Generic");
print(path); # prints the absolute path to $FG_ROOT/Aircraft/Generic
|example2 = var path = finddata("Airports");
print(path); # prints the absolute path to <TerraSync dir>/Airports
|example3 = var path = finddata("preferences.xml");
print(path); # prints the absolute path to $FG_ROOT/preferences.xml
}}

===flightplan()===
{{Nasal doc
|syntax = flightplan([path]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1738|t=Source}}
|text = {{see also|Nasal Flightplan}}
Returns a flight plan object, either one for the current flight plan, or one loaded from a given path.
|param1 = path
|param1text = Optional path to flight plan XML file.
|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.
|example1 = var fp = flightplan();
print(fp.getWP(fp.current).id);
|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>.
|example2 = var path = getprop('/sim/fg-home') ~ '/fp-demo.xml';
var fp = flightplan(path);
for(var i = 0; i < fp.getPlanSize(); i += 1){
print(fp.getWP(i).id);
<nowiki>}</nowiki>
}}

===geodinfo()===
{{Nasal doc
|syntax = geodinfo(lat, lon[, max_alt]);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=981|t=Source}}
|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}}):
* '''light_coverage:''' The coverage of a single point of light in m<sup>2</sup>.
* '''bumpiness:''' Normalized bumpiness factor for the material.
* '''load_resistance:''' The amount of pressure in N/m<sup>2</sup> the material can withstand without deformation.
* '''solid:''' 1 (true) or false (0) depending on whether the material is solid or not.
* '''names:''' Vector of scenery types (usually generated by [[TerraGear]]) that will use this material.
* '''friction_factor:''' Normalized friction factor of the material.
* '''rolling_friction:''' The rolling friction coefficient of the material.

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.
|param1 = lat
|param1text = Latitude, inputted as a number.
|param2 = lon
|param2text = Longitude, inputted as a number.
|param3 = max_alt
|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.
|example1text = Dumps information about ground underneath the aircraft.
|example1 = var pos = geo.aircraft_position();
var info = geodinfo(pos.lat(), pos.lon());
debug.dump(info);
|example2text = Prints whether the ground underneath the aircraft is solid or is water.
|example2 = var pos = geo.aircraft_position();
var info = geodinfo(pos.lat(), pos.lon());
if (info != nil and info[1] != nil) {
print("The ground underneath the aircraft is ", info[1].solid == 1 ? "solid." : "water.");
<nowiki>}</nowiki>
}}

=== geodtocart() ===
{{Nasal doc
|syntax = geodtocart(lat, lon, alt);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=962|t=Source}}
|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.
|param1 = lat
|param1text = Latitude, in degrees.
|param2 = lon
|param2text = Longitude, in degrees.
|param3 = alt
|param3text = Altitude, in metres.
|example1 = var (x, y, z) = geodtocart(0, 0, 0); # point is the intersection of the prime meridian and equator.
print("x: ", x); # prints "x: 6378137"
print("y: ", y); # prints "y: 0"
print("z: ", z); # prints "y: 0"
}}

=== get_cart_ground_intersection()===
Introduced in 2017.2.1, see [[Terrain Detection]].

===getprop()===
{{Nasal doc
|syntax = <nowiki>getprop(path[, path[, ...]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=345|t=Source}}
|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).
|param1 = path
|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.
|example1 = print("You have FlightGear v", getprop("/sim/version/flightgear")); # prints FlightGear version
|example2text = Note that the example below will only work in FlightGear 3.2 and above.
|example2 = for(var i = 0; i < 8; i += 1){
print("View #", i + 1, " is named ", getprop("/sim/view", i, "name"));
}
|example3text = Same as above, but is supported by all versions of FlightGear.
|example3 = for(var i = 0; i < 8; i += 1){
print("View #", i + 1, " is named ", getprop("/sim/view[" ~ i ~ "]/name"));
<nowiki>}</nowiki>
}}
==== See also====
{{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:
To get a Node rather than its value, use <code>props.globals.getNode()</code> - see [[Nasal_library/props]]. }}

===greatCircleMove()===
{{Nasal doc
|syntax = greatCircleMove([pos, ]course, dist);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1681|t=Source}}
|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).
|param1 = pos
|param1text = Optional position to calculate from. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost object.
:* A hash with ''lat'' and ''lon'' members
:* A <code>geo.Coord</code> object
:* A lat/lon pair, that is, a pair of numbers (latitude followed by longitude) separated by a comma: <code>greatCircleMove(lat,lon, ...)</code>.
|param2 = course
|param2text = Course to new set of coordinates, in degrees (in the range 0–360).
|param3 = dist
|param3text = Distance in nautical miles to the new set of coordinates.
|example1 = var pos = greatCircleMove(0,0, 0, 1);
debug.dump(pos); # print hash with coordinates
|example2 = var fix = findFixesByID("POGIC");
fix = fix[0];
var pos = greatCircleMove(fix, 45, 10);
debug.dump(pos); # print hash with coordinates
}}

===interpolate()===
{{Nasal doc
|private = _interpolate()
|syntax = <nowiki>interpolate(prop, value1, time1[, value2, time2[, ...]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=522|t=Part 1}} {{!}} {{fgdata file|Nasal/globals.nas|t=Part 2}}
|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.
|param1 = prop
|param1text = String or <code>props.Node</code> object that indicates a node in the property tree to be used.
|param2 = value''n''
|param2text = Target value to change the property to in the set amount of time. This should be a number.
|param3 = time''n''
|param3text = Time in seconds, that will be taken for the interpolation.
|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.
|example1 = setprop("/test", 0); # (re-)set property
interpolate("/test",
50, 5, # interpolate to 50 in 5 seconds
10, 2, # interpolate to 10 in 2 seconds
0, 5); # interpolate to 0 in 5 seconds
|example2 = # Apply the left brake at 20% per second
var prop = "controls/gear/brake-left";
var dist = 1 - getprop(prop);
if (dist == 1) {
interpolate(prop, 1, dist / 0.2);
<nowiki>}</nowiki>
}}

===isa()===
{{Nasal doc
|syntax = isa(object, class);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|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.
|param1 = object
|param1text = Object to check.
|param2 = class
|param2text = Class/object to check that '''object''' inherits from or is an instance of.
|example1 = var coord = geo.Coord.new();
if(isa(coord, geo.Coord)){
print("Variable 'coord' is an instance of class 'geo.Coord'"); # this one will be printed
} else {
print("Variable 'coord' is not an instance of class 'geo.Coord'");
}
|example2 = var coord = geo.Coord.new();
if(isa(coord, props.Node)){
print("Variable 'coord' is an instance of class 'props.Node'");
} else {
print("Variable 'coord' is not an instance of class 'props.Node'"); # this one will be printed
}
|example3text = The example below demonstrates checking of inheritance.
|example3 = var Const = {
constant: 2,
getConst: func {
return me.constant;
}
};

var Add = {
new: func {
return { parents: [Add, Const] };
},

addToConst: func(a){
return a * me.getConst();
}
};

var m = Add.new();
print(m.addToConst(4));

if(isa(m, Add)) print("Variable 'm' is an instance of class 'Add'"); # will be printed
if(isa(m, Const)) print("Variable 'm' is an instance of class 'Const'"); # will also be printed
}}

===logprint()===
{{Nasal doc
|syntax = <nowiki>logprint(priority[, msg[, msg[, ...]]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=431|t=Source}}
|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}}.
|param1 = priority
|param1text = Number specifying the priority level of the outputted message:
:{{{!}} class="wikitable"
! Number !! Debug type
{{!-}}
{{!}} 1 {{!!}} Bulk
{{!-}}
{{!}} 2 {{!!}} Debug
{{!-}}
{{!}} 3 {{!!}} Info
{{!-}}
{{!}} 4 {{!!}} Warn
{{!-}}
{{!}} 5 {{!!}} Alert
{{!}}}
|param2 = msg
|param2text = The message. There is no limit to the arguments you give give. They will be concatenated together before logging.
|example1 = # logs the value of pi to three decimal places with log level 3
logprint(3, "pi = ", sprintf("%.3f", math.pi));
|example2 = logprint(5, "Alert! This is an important message!");
}}
{{note|
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:

LOG_BULK, LOG_WARN, LOG_DEBUG, LOG_INFO, LOG_ALERT, DEV_WARN, DEV_ALERT }}

===magvar() ===
{{Nasal doc
|syntax = magvar([pos]);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1642|t=Source}}
|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.
{{{!}} class="wikitable"
! FlightGear versions !! Model !! Reference date
{{!-}}
{{!}} 3.6 and above {{!!}} {{wikipedia|World Magnetic Model}} (WMM) 2015 {{!!}} 1 January 2015
{{!-}}
{{!}} 0.9.11-pre1 to 3.4 {{!!}} WMM 2005 {{!!}} 1 January 2005
{{!-}}
{{!}} 0.7.3 to 0.9.10 {{!!}} WMM 2000 {{!!}} 1 January 2000
{{!}}}
|param1 = pos
|param1text = Optional position to calculate from. If not given, the aircraft's current position will be used. Can be one of:
:* An <code>airport</code>, <code>navaid</code>, <code>runway</code>, <code>taxiway</code>, <code>fix</code>, or <code>waypoint</code> ghost object.
:* A hash with ''lat'' and ''lon'' members
:* A <code>geo.Coord</code> object
:* A lat/lon pair, that is, a pair of numbers (latitude followed by longitude) separated by a comma: <code>magvar(lat,lon)</code>.
|example1 = print(magvar(0, 0)); # prints the magnetic variation at 0, 0
}}

===maketimer() ===
{{Nasal doc
|syntax = maketimer(interval[, self], function);
|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}}
|version = 2.12
|commit = {{flightgear commit|ab939f|t=commit}}
|text = Returns a timer object containing the following methods and members:
* '''start()''': Starts the timer.
* '''stop()''': Stops the timer.
* '''restart(interval)''': Restarts the timer with the given interval.
* '''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).
* '''isRunning''': Read-only bool telling whether the timer is currently running.
* '''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.
Unlike {{func link|settimer()}}, which it replaces, <code>maketimer()</code> provides more control over the timer. In addition, it can help reduce memory usage.
|param1 = interval
|param1text = Interval in seconds for the timer.
|param2 = self
|param2text = Optional parameter specifying what any <code>'''me'''</code> references in the function being called will refer to.
|param3 = function
|param3text = Function to be called at the given interval.
|example1 = var timer = maketimer(1, func(){
print("Hello, World!"); # print "Hello, World!" once every second (call timer.stop() to stop it)
});
timer.start();
|example2 = var timer = maketimer(1, math, func(){
print(me.math); # 'me' reference is the 'math' namespace
});
timer.singleShot = 1; # timer will only be run once
timer.start();
|example3 = var timer = maketimer(1, func(){
print("Hello, World!"); # print "Hello, World!" once every second (call timer.stop() to stop it)
});
timer.start();
print(timer.isRunning); # prints 1
|example4text = In the example below, "Hello, World!" will be printed after one second the first time, and after two seconds thereafter.
|example4 = var update = func(){
print("Hello, World!");
timer.restart(2); # restarts the timer with a two second interval
}

var timer = maketimer(1, update);
timer.singleShot = 1;
timer.start();
}}

===maketimestamp()===
{{Nasal doc
|syntax = maketimestamp()
|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}}
|version = 2019.2
|commit = {{flightgear commit|7db06300|t=commit}}
|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:
* '''stamp()''': Resets the timing operation. Call this first.
* '''elapsedMSec()''': returns number of milliseconds elapsed since stamp() called. Resolution may vary depending on platform but is usually at least millisecond accuracy.
* '''elapsedUSec()''': returns number of microseconds elapsed since stamp() called. Resolution may vary depending on platform but is usually at least millisecond accuracy.
|
|example1text = In the example below the number of milliseconds elapsed will be printed.
|example1 = var timestamp = maketimestamp();
timestamp.stamp();
print(timestamp.elapsedMSec(), "ms elapsed");
print(timestamp.elapsedMSec(), "ms elapsed");
}}

===md5()===
{{Nasal doc
|syntax = md5(string);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=758|t=Source}}
|version = 3.2
|commit = {{flightgear commit|cfbf9e|t=commit}}
|text = Returns a the {{wikipedia|MD5}} hash (as a string) of the inputted string.
|param1 = string
|param1text = String the generate the hash of. Mandatory.
|example1text = The below code should output <code>65a8e27d8879283831b664bd8b7f0ad4</code>.
|example1 = print(md5("Hello, World!"));
}}

===navinfo()===
{{Nasal doc
|syntax = navinfo(lat, lon, type, id);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1453|t=Source}}
|text = Returns vector <code>navaid</code> ghost objects matching the given '''type''' and '''id''' or <code>'''nil'''</code> on error.
|param1 = lat ''and'' lon
|param1text = If given, the returned navaids will be put into order of ascending distance from the location.
|param2 = type
|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."
|param3 = id
|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.
|example1 = navinfo("vor"); # returns all VORs
|example2 = navinfo("HAM"); # return all navaids whose names start with "HAM"
|example3 = navinfo("vor", "HAM"); # return all VORs whose names start with "HAM"
|example4 = navinfo(34,48,"vor","HAM"); # return all VORs whose names start with "HAM" and sorted by distance relative to 34°, 48°
}}

===parse_markdown()===
{{Nasal doc
|syntax = parse_markdown(markdown);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=745|t=Part 1}} {{!}} {{simgear file|simgear/misc/SimpleMarkdown.cxx|t=Part 2}}
|version = 3.2
|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:
* It strips whitespace from the beginning of the string.
* It supports [http://daringfireball.net/projects/markdown/syntax#p paragraphs and line breaks].
* It collapses whitespace.
* It converts unordered [http://daringfireball.net/projects/markdown/syntax#list lists] to use a bullet character (•). 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.
|param1 = markdown
|param1text = String containing Markdown to be parsed.
|example1text =
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>).
<syntaxhighlight lang="xml" highlight="41-50">
<?xml version="1.0" encoding="UTF-8"?>

<PropertyList>

<name>test</name>
<layout>vbox</layout>

<group>
<layout>hbox</layout>

<empty>
<stretch>true</stretch>
</empty>

<text>
<label>parse_markdown() test dialog</label>
</text>

<empty>
<stretch>true</stretch>
</empty>

<button>
<legend></legend>
<pref-width>16</pref-width>
<pref-height>16</pref-height>
<binding>
<command>dialog-close</command>
</binding>
</button>

</group>

<canvas>
<name>Canvas plot</name>
<stretch>true</stretch>
<pref-width>400</pref-width>
<pref-height>300</pref-height>
<nasal>
<load><![CDATA[
var text = 'Items:
* apples
* oranges
* pears

Some text.
Some more items:
* apples
* oranges
* pears';

var parsed = parse_markdown(text);

var root_canvas = canvas.get(cmdarg());
root_canvas.setColorBackground(255, 255, 255);
var root = root_canvas.createGroup();

var text_dis = root.createChild("text")
.setText(parsed)
.setTranslation(5, 5)
.setFont("LiberationFonts\LiberationSans-Regular.ttf")
.setFontSize(15)
.setColor(0, 0, 0)
.setDrawMode(canvas.Text.TEXT)
.setAlignment("left-top");
]]></load>
</nasal>
</canvas>

</PropertyList>
</syntaxhighlight>
|example1 = fgcommand("dialog-show", {"dialog-name": "test"});
|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.
|example2 = <nowiki>var markdown = 'Items:
* apples
* oranges
* pears

Some text.
Some more items:
* apples
* oranges
* pears';

var parsed = parse_markdown(markdown);

debug.dump(parsed);

var path = string.normpath(getprop("/sim/fg-home") ~ '/Export/parse_markdown()-test.html');

var file = io.open(path, "w");

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>";

io.write(file, html);
io.close(file);
print("Done, file ready for viewing (" ~ path ~ ")");</nowiki>
}}

===parsexml()===
{{Nasal doc
|syntax = <nowiki>parsexml(path[, start[, end[, data[, pro_ins]]]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=710|t=Source}}
|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.
|param1 = path
|param1text = Mandatory absolute path to the XML file to be parsed.
|param2 = start
|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.
|param3 = end
|param3text = Optional callback function that will be called for every ending tag. The function should take one argument: the tag name.
|param4 = data
|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.
|param5 = pro_ins
|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.
|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.
<syntaxhighlight lang="xml">
<?xml version="1.0" encoding="UTF-8"?>

<?xml-stylesheet type="text/xsl" href="style.xsl"?>

<foo>
<blah type="string"><![CDATA[ <sender>John Smith</sender> ]]></blah>
<blah2 type="string">Orange & lemons</blah2>
</foo>
</syntaxhighlight>
|example1 = var start = func(name, attr){
print("Starting tag: '", name, "'");
foreach(var a; keys(attr)){
print("\twith attribute ", a, '="', attr[a], '"');
}
}

var end = func(name){
print("Ending tag: '", name, "'");
}

var data = func(data){
print("Data = '", data, "'");
}

var pro_instr = func(target, data){
print("Processing instruction: target = '", target, "', data = '", data, "'");
}

parsexml(getprop("/sim/fg-home") ~ '/Export/demo.xml', start, end, data, pro_instr);
}}

===print()===
{{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.

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>}}

{{Nasal doc
|syntax = <nowiki>print(data[, data[, ...]]);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=415|t=Source}}
|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.
|param1 = data
|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.
|example1 = print("Just", " a ", "test"); # prints "Just a test"
|example2 = print("pi = ", math.pi); # prints "pi = 3.141592..."
}}

=== printf() ===
{{Nasal doc
|syntax = <nowiki>printf(format[, arg[, arg, [...]]]);</nowiki>
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|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>).
|example1 = printf("In hexadecimal, 100000 = %X", 186A0); # prints "In hexadecimal, 100000 = 186A0"
}}

===printlog()===
{{caution|This function is deprecated and doesn't work. Please use the new one {{func link|logprint()}}.}}
{{Nasal doc
|syntax = <nowiki>printlog(level, data[, data[, ...]]);</nowiki>
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|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.
|param1 = level
|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.
|param2 = data
|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.
|example1 = printlog("alert", "This is an alert"); # message will be printed
|example2 = printlog("info", "Just informing you about something"); # message will be printed only if log level is set to "info" or less
}}

===rand()===
{{Nasal doc
|syntax = rand();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=554|t=Source}}
|text = Returns a random floating point number between 0 (inclusive) and 1 (exclusive). It takes no arguments.
|example1 = print(rand()); # prints random number
}}

===registerFlightPlanDelegate()===
{{Nasal doc
|syntax = registerFlightPlanDelegate(init_func);
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1879|t=Source}}
|text = Registers a flight plan delegate. See <tt>''{{fgdata file|Nasal/route_manager.nas|t=$FG_ROOT/Nasal/route_manager.nas}}''</tt> for examples.
|param1 = init_func
|param1text = Initialization function which will be called during FlightGear's startup.
}}
===removecommand()===
{{Nasal doc
|syntax = removecommand(cmd);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=668|t=Source}}
|text = Removes the given fgcommand. Returns <code>'''nil'''</code>.
{{caution|This will remove '''any''' [[fgcommands|fgcommand]], even those implemented in C++, so use with caution!}}
|param1 = cmd
|param1text = String specifying the name of the command to remove.
|example1 = addcommand("hello", func(){
print("Hello");
});
fgcommand("hello"); # "Hello" will be printed
removecommand("hello"); # removes it
}}

===removelistener()===
{{Nasal doc
|syntax = removelistener(id);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=1384|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=506|t=Part 2}}
|text = Removes and deactivates the given listener and returns the number of listeners left or <code>'''nil'''</code> on error.
{{note|It is good practice to remove listeners when they are not required anymore. This prevents the listeners reducing FlightGear's run performance.}}
|param1 = id
|param1text = ID of listener as returned by {{func link|setlistener()}}.
|example1 = var ls = setlistener("/sim/test", func(){
print("Property '/sim/test' has been changed");
});
setprop("/sim/test", "blah"); # trigger listener
var rem = removelistener(ls); # remove listener
print("There are ", rem, " listeners remaining");
}}

===resolvepath()===
{{Nasal doc
|syntax = resolvepath(path);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=604|t=Source}}
|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.
|param1 = path
|param1text = Relative path to be completed.
|example1 = print(resolvepath("Nasal/globals.nas")); # prints the equivalent of $FG_ROOT/Nasal/globals.nas
|example2 = print(resolvepath("blah")); # prints nothing; could not be resolved
|example3 = var file_path = resolvepath("Aircraft/SenecaII/some-file");
if (file_path != ""){
gui.popupTip("some-file found", 2);
} else {
gui.popupTip("some-file not found", 2);
<nowiki>}</nowiki>
}}

===setlistener()===
{{Nasal doc
|syntax = <nowiki>setlistener(node, code[, init[, type]]);</nowiki>
|private = _setlistener()
|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.''
|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()}}.
{{note|Listeners are known to be a source of resource leaks. To avoid this, please take measures such as:
* Using {{func link|removelistener()}} when they are not needed any more.
* Using a single initialization listener.
* Avoiding tying listeners to properties that are rapidly updated (e.g., many times per frame).
}}
|param1 = node
|param1text = Mandatory string or <code>props.Node</code> object pointing to a property in the [[Property Tree]].
|param2 = code
|param2text = Mandatory callback function to execute when the listener is triggered. The function can take up to four arguments in the following order:
* '''changed''': a <code>props.Node</code> object pointing to the changed node.
* '''listen''': a <code>props.Node</code> object pointing to the listened-to node. Note that this argument maybe different depending on the '''type'''.
* '''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.
* '''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.
|param3 = init
|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).
|param4 = type
|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.
|example1 = var prop = props.globals.initNode("/sim/test", "", "STRING"); # create property
var id = setlistener("/sim/test", func(n){ # create listener
print("Value: ", n.getValue());
});
setprop("/sim/test", "blah"); # trigger listener
removelistener(id); # remove listener
prop.remove(); # remove property
}}

===setprop()===
{{Nasal doc
|syntax = <nowiki>setprop(path[, path[, ...]], value);</nowiki>
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=385|t=Source}}
|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.
{{note|If you want to remove a property, you will have to use one of the <code>props</code> helpers:
<syntaxhighlight lang="nasal">
props.globals.getNode("foo/bar").remove(); # take out the complete node
props.globals.getNode("foo").removeChild("bar"); # take out a certain child node
</syntaxhighlight>
}}
|param1 = path
|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.
|param2 = value
|param2text = Value to write to the given property. Must be either a string or a number.
|example1 = setprop("/sim/demo", "This is a demo");
|example2text = Note that the example below will only work in FlightGear 3.2 and above.
|example2 = for(var i = 0; i < 3; i += 1){
setprop("/sim/demo", i, "Demo #" ~ i));
}
|example3text = Same as above, but is supported by all versions of FlightGear.
|example3 = for(var i = 0; i < 3; i += 1){
setprop("/sim/demo[" ~ i ~ "]", "Demo #" ~ i));
<nowiki>}</nowiki>
}}
====See also====
{{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:
To get a Node rather than its value, use <code>props.globals.getNode()</code> - see [[Nasal_library/props]]. }}

===settimer() ===
{{Nasal doc
|syntax = settimer(function, delta[, realtime]);
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=499|t=Part 1}} {{!}} {{flightgear file|src/Scripting/NasalSys.cxx|l=1286|t=Part 2}}
|text = Runs the given function a specified amount of seconds after the current time. Returns <code>'''nil'''</code>.
{{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.}}
|param1 = function
|param1text = Mandatory function that will be called. It may be necessary to enclose code in an anonymous function (see example).
|param2 = delta
|param2text = Mandatory amount of time in seconds after which the function will be called.
|param3 = realtime
|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.
|example1 = var myFunc = func(){
print("Hello");
}

settimer(myFunc, 2); # runs myFunc after 2 seconds
|example2 = var sqr = func(a){
return a * a;
}

settimer(func(){
print(sqr(2)); # will print 4 after 2 seconds
}, 2);
}}

===srand() ===
{{Nasal doc
|syntax = srand();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=559|t=Source}}
|text = Makes the pseudorandom number generator (see {{func link|rand()}}) generate a new {{wikipedia|random seed|noicon=1}} based on time. Returns 0.
}}
===systime()===
{{Nasal doc
|syntax = systime();
|source = {{flightgear file|src/Scripting/NasalSys.cxx|l=770|t=Source}}
|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).
{{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]}}
|example1 = print("Unix time: ", systime()); # prints Unix time
|example2 = var myFunc = func(){
for(var i = 0; i <= 10; i += 1){
print("Interation #", i);
}
}
var t = systime(); # record time
myFunc(); # run function
var t2 = systime(); # record new time
print("myFunc() took ", t2 - t, " seconds"); # print result
}}

===thisfunc()===
{{Nasal doc
|syntax = thisfunc();
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = Returns the function from which this function is called. This allows a function to reliably and safely call itself from within a closure.
|example1 = var stringify_vec = func(input){
if (typeof(input) == "scalar"){
return sprintf("%s", input);
} elsif (typeof(input) == "vector") {
if (size(input) == 0) return "[]";
var this = thisfunc();
var buffer = "[";
for(var i = 0; i < size(input); i += 1){
buffer ~= this(input[i]);
if (i == size(input) - 1) {
buffer ~= "]";
} else {
buffer ~= ", ";
}
}
return buffer;
} else {
die("stringify_vec(): Error! Invalid input. Must be a vector or scalar");
}
}

var test_vec = ["a", "b", "c", [1, 2, 3], "d"];
debug.dump(stringify_vec(test_vec)); # prints "[a, b, c, [1, 2, 3], d]"
test_vec = [];
debug.dump(stringify_vec(test_vec)); # prints "[]"
test_vec = {};
debug.dump(stringify_vec(test_vec)); # will throw an error
}}

===tileIndex() ===
{{Nasal doc
|syntax = tileIndex();
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1720|t=Source}}
|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>.
|example1 = print(tileIndex()); # print index
}}

=== tilePath()===
{{Nasal doc
|syntax = tilePath();
|source = {{flightgear file|src/Scripting/NasalPositioned.cxx|l=1712|t=Source}}
|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>.
|example1 = print(tilePath()); # print path
}}

=== values()===
{{Nasal doc
|syntax = values(hash);
|source = {{fgdata file|Nasal/globals.nas|t=Source}}
|text = Returns a vector containing the values of the given hash.
|param1 = hash
|param1text = Mandatory hash to get the values of.
|example1 = var hash = {
"a": 1,
"b": 2,
"c": 3
};

foreach(var val; values(hash)){
print(val);
}
|example2text = The below example does exactly the same thing as the above example, but does not use <code>values()</code>:
|example2 = var hash = {
"a": 1,
"b": 2,
"c": 3
};

foreach(var key; keys(hash)){
print(hash[key]);
<nowiki>}</nowiki>
}}

==Extension functions new in FG 2020.1 ==
The following functions have been added to the nasal core library and will be released with FlightGear version 2020.1.
Before the release they are available in the development branch "next".

===isfunc()===
Returns 1 if type or argument is a function, otherwise 0.

===isghost()===
Returns 1 if type or argument is a ghost, otherwise 0.

=== ishash()===
Returns 1 if type or argument is a hash, otherwise 0.

===isint()===
{{Nasal doc
|syntax = isint(x);
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}
|text = Returns 1 if argument has a numeric value and x == floor(x), e.g. integer.
}}

===isnum()===
{{Nasal doc
|syntax = isnum(x);
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}
|text = Returns 1 if typeof(x) is "scalar" and x has a numeric value otherwise 0.
}}

===isscalar()===
{{Nasal doc
|syntax = isscalar(x);
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}
|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 "~".
|example1 = var a = "foo";
var b=42;
if (isscalar(a) and isscalar(b)) print(a~b);
if (isstr(a)) print("a is a string");
if (isint(b)) print("b is an integer");
# if (isscalar(a))... is equivalent to if (typeof(a) == "scalar")...
}}

===isstr()===
Returns 1 if type or argument is a string, otherwise 0.

===isvec()===
Returns 1 if type or argument is a vector, otherwise 0.

===vecindex()===
{{Nasal doc
|syntax = vecindex(vector, value);
|source = {{simgear file|simgear/nasal/lib.c|t=Source}}
|text = Returns the index of value or nil, if value is not found in vector.
|example1=
var myvector = ["apple", "bananna", "coconut"];
# to check if a vector contains a certain value compare vecindex to nil
if (vecindex(myvector, "apple") != nil) {
print("found apple");
}
# WARNING: this will not work as desired because index is 0
if (vecindex(myvector, "apple")) {
print("found apple");
<nowiki>}</nowiki>

}}

==Variables==
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}}.

===D2R===
{{Nasal doc
|syntax = var radians = degrees * D2R;
|text = Converts an angle from degrees to radians when multiplied by the angle in degrees. Equal to <code>π / 180</code>.
}}
===FPS2KT===
{{Nasal doc
|syntax = var knots = feet_per_second * FPS2KT;
|text = Converts a velocity from feet per second to knots when multiplied by the velocity in feet per second. Approximately equal to 0.5925.
}}
===FT2M===
{{Nasal doc
|syntax = var metres = feet * FT2M;
|text = Converts a length from feet to metres when multiplied by the length in feet. Equal to 0.3048.
}}
===GAL2L ===
{{Nasal doc
|syntax = var litres = gallons * GAL2L;
|text = Converts a volume from US liquid gallons to litres when multiplied by the volume in gallons. Approximately equal to 3.7854.
}}
===IN2M===
{{Nasal doc
|syntax = var metres = inches * IN2M;
|text = Converts a length from inches to metres when multiplied by the length in inches. Equal to 0.0254.
}}
===KG2LB===
{{Nasal doc
|syntax = var pounds = kilograms * KG2LB;
|text = Converts a mass from kilograms to pounds when multiplied by the mass in kilograms. Approximately equal to 2.2046.
}}
===KT2FPS===
{{Nasal doc
|syntax = var feet_per_second = knots * KT2FPS;
|text = Converts a velocity from knots to feet per second when multiplied by the velocity in knots. Approximately equal to 1.6878.
}}
===KT2MPS===
{{Nasal doc
|syntax = var metres_per_second = knots * KT2MPS;
|text = Converts a velocity from knots to metres per second when multiplied by the velocity in knots. Approximately equal to 0.5144.
}}
===L2GAL===
{{Nasal doc
|syntax = var gallons = litres * L2GAL;
|text = Converts a volume from litres to US liquid gallons when multiplied by the volume in litres. Approximately equal to 0.2642.
}}
===LB2KG===
{{Nasal doc
|syntax = var kilograms = pounds * LB2KG;
|text = Converts a mass from pounds to kilograms when multiplied by the mass in pounds. Approximately equal to 0.4536.
}}
===M2FT ===
{{Nasal doc
|syntax = var feet = metres * M2FT;
|text = Converts a length from metres to feet when multiplied by the length in metres. Approximately equal to 3.2808.
}}
===M2IN===
{{Nasal doc
|syntax = var inches = metres * M2IN;
|text = Converts a length from metres to inches when multiplied by the length in metres. Approximately equal to 39.3701.
}}
===M2NM ===
{{Nasal doc
|syntax = var nautical_miles = metres * M2NM;
|text = Converts a length from metres to nautical miles when multiplied by the length in metres. Approximately equal to 0.00054.
}}
===MPS2KT ===
{{Nasal doc
|syntax = var knots = metres_per_second * MPS2KT;
|text = Converts a velocity from metres per second to knots when multiplied by the velocity in metres per second. Approximately equal to 1.9438.
}}
===NM2M ===
{{Nasal doc
|syntax = var metres = nautical_miles * NM2M;
|text = Converts a length from nautical miles to metres when multiplied by the length in nautical miles. Equal to 1,852.
}}
===R2D===
{{Nasal doc
|syntax = var degrees = radians * R2D;
|text = Converts an angle from radians to degrees when multiplied by the angle in radians. Equal to <code>180 / π</code>.
}}

{{Appendix}}

{{Nasal namespaces}}