Howto:Extend Nasal: Difference between revisions

{{Nasal Internals}}

This article is dedicated to describing how to write custom C/C++ extension functions in order to ''extend the [[Nasal]] scripting interpreter'' in FlightGear, for example in order to expose new or existing FlightGear APIs to the Nasal scripting engine, so that Nasal scripts can access additional FlightGear internals.

As of 03/2013, this article should be considered depreciated, we have [[Nasal/CppBind]], a new C++-based API for exposing C/C++ functions/data structures to Nasal and vice versa in {{simgear file|simgear/nasal/cppbind}}. Usually, there should be no need to use the bare Nasal APIs anymore for exposing functions/data to Nasal or Nasal-space types to C++, except for people working on the '''cppbind''' framework itself.  

All Nasal related articles can be found in [[:Category:Nasal]].

{{Note|FlightGear's version of the Nasal interpreter is maintained in the SimGear git repository, inside the {{simgear file|simgear/nasal}} folder, the most important header file detailing the internal Nasal API is [http://api-docs.freeflightsim.org/simgear/nasal_8h.html nasal.h], you will want to check this out for the latest changes and information.}}

You will probably also want to check out the {{simgear file|simgear/nasal}} folder for specific examples on using the various Nasal APIs that are not yet covered here completely.

In FlightGear, the simplest way to add new extension functions is to look at the existing functions at {{flightgear file|src/Scripting/NasalSys.cxx|l=747}}.

There is a static table of function pointers (named funcs[]) referencing extension functions, along with their corresponding names in Nasal: {{flightgear file|src/Scripting/NasalSys.cxx|l=482}}.

(Note, as of 06/2012, some of these functions have meanwhile been moved to a different file and are initialized there: {{flightgear file|src/Scripting/NasalPositioned.cxx|t=NasalPositioned.cxx}})  

// The function signature for an extension function:

typedef naRef (*naCFunction)(naContext ctx, naRef me, int argc, naRef* args);

If your extension functions are likely to be fairly low level, and will thus be provided with a more abstract wrapper in Nasal space, these functions should use a prepended undercore ("_"), such as the {{func link|_fgcommand}}, {{func link|_setlistener}}, {{func link|_cmdarg}} and {{func link|_interpolate}} functions.

static naRef f_your_function(naContext c, naRef me, int argc, naRef* args)

{

    // ...

}

static naRef f_cool (naContext c, naRef me, int argc, naRef* args)

{

    SG_LOG(SG_GENERAL, SG_ALERT, "Nasal:cool() got executed!");

    return naNil();

}

The naRef objects can be manipulated using the functions in [http://api-docs.freeflightsim.org/simgear/nasal_8h.html nasal.h].

For the latest copy of the file, see {{simgear file|simgear/nasal/nasal.h}}

Please see: {{simgear file|simgear/nasal/cppbind}}

For the time being, it's a good idea to take a look at the FGPositioned wrappers for the navdb to see how this is done in Nasal, see {{flightgear file|src/Scripting/NasalPositioned.cxx}}.

Also, the implementation of the SGPropertyNode bindings in {{flightgear file|src/Scripting/nasal-props.cxx}} contains additional examples.