Howto:Extend Nasal: Difference between revisions

The following is a copy of the extension function list, taken in 05/2009:

   // Table of extension functions.  Terminate with zeros.

   static struct { const char* name; naCFunction func; } funcs[] = {

     { 0, 0 }

   };

So, the basic format is "name" (string), function_pointer - whereas "name" refers to the internal name used by Nasal and its scripts, and "function_pointer" has to use the right function signature and is a pointer to the implementation of the Nasal function in C/C++ code space:

  // The function signature for an extension function:

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

You will need to add your new extension function to this list of static functions, preferably following the existing naming convention (i.e. "f_" prefix).

These extension functions look like:

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

   {

       // ...

   }

So, this is basically the boilerplate that you'll need to use in order to expose a new function (i.e. you can just copy & paste this into the NasalSys.cxx file and change the function's name accordingly).

If you don't have anything else to return, you can just return naNil(), so that a function named "f_cool" looks like this:

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

   {

       return naNil();

   }

In order to make this function known to the Nasal interpreter, you'll want to extend the previously mentioned list of Nasal extension functions (in src/Scripting/NasalSys.cxx), to read:

Once you have made these modifications and rebuilt FlightGear, you can simply invoke your new function, of course it will not yet do anything useful, though:

  #cooltest.nas (to be saved in $FG_ROOT/Nasal)

  cool();

So, in order to make it slightly more interesting, we are going to change the return statement to return something else, instead of nil:

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

   {

       return retval;

   }

So, after rebuilding the FlightGear binary, whenever you call the new "cool" API function, it will always return a "cool" string, which you could for example print out using a script like the following:

  #cooltest.nas (to be saved in $FG_ROOT/Nasal)

  var result=cool();

  print(result);

= Argument Processing =

Consider the callback signature:

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

The arguments to the function are passed in in the args array. The number of arguments is passed via the argc parameter (this is basically consistent with the standard signature of main in C/C++).

So, if you know that you require a certain number of arguments, you can also directly check argc to to match your requirements and show an error message, return nil, or throw an exception using naRuntimeError():

  // Throw an error from the current call stack.  This function makes a

  // longjmp call to a handler in naCall() and DOES NOT RETURN.  It is

  // printf().

  void naRuntimeError(naContext c, const char* fmt, ...);

The "me" reference is set if the function was called as a method call on an object (e.g. object.your_function() instead of just your_function(), in which case "me" would be set to the object).

Basically, you can check the type of the reference with the following naIs*() functions:

  int naIsNil(naRef r);

  int naIsNum(naRef r);

  int naIsFunc(naRef r);

  int naIsCCode(naRef r);

And then get the appropriate value out with things like naNumValue(), naStr_data(), etc...

So, if we're now to change the interface of our earlier "cool" function in the example, to only return "cool" if we are passed at least one numerical parameter, and otherwise return "uncool", it could look like this:

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

  {

     return naStr_fromdata(retval, result, strlen(result) );

  }

You can test this, by running a simple Nasal script like the following:

  # test new cool() function:

  print( cool("foo") );  

  print( cool(100)  );

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

     naRef param1 = argc > 0 ? args[0] : naNil();

     return naNil;

  }

This will basically look for 3 parameters, and assign them accordingly - if they are not available, they will just be assigned nil using the naNil() calls (the next step would be to check if the parameters have the right types using the naIs* helpers mentioned above).

There are also functions to create Nasal data structures (hash tables, vectors, etc...) which you can return to the caller simply by returning the resulting naRef:

  naRef naNil();

  naRef naNum(double num);

  naRef naNewFunc(naContext c, naRef code);

  naRef naNewCCode(naContext c, naCFunction fptr);

== String Manipulation API ==