Nasal Namespaces in-depth: Difference between revisions

= Nasal Namespaces: in-depth =

I am not an expert in scripting languages, but I do claim that Nasal has a unique notion of namespaces. Rather than dwell on that, I'll tell you how they work in Nasal (and FlightGear) and leave you to decide for yourself.

If you look at the graph on the right, you will see a representation of how namespaces look in FlightGear. At the top there is the global namespace, called "globals", and various other namespaces branch down from there. On the left there are the namespaces created from the modules in [[$FG_ROOT]] and [[$FG_HOME]], e.g. controls.nas makes the namespace "controls". In the center there are the ‘special’ namespaces, for the joystick(s) and the keyboard (there is only support for one keyboard hence only one namespace). Everything found in the joystick or keyboard files are executed in their respective namespaces – the <nasal><script> section at the top and all of the <binding>s. Next are the GUI dialogs, which have "__dialog:" as a prefix in front of the dialog's name (which I believe comes from the filename).

== Hands-on example ==

The "controls" means that namespace and the "[dot] gearDown" means that we want to access it's member "gearDown" (and then call it with the parenthesis). But how does this work? There clearly isn't a line between __js0 and controls that could take us there! But the key here is the other lines – we can first go up to globals from __js0 and then back down to controls, then we search for "gearDown" there. With this in mind, let me tell you what happens when Nasal interprets the above script:

Nasal starts looking for the leftmost side of the name – "controls." First it checks our current namespace, __js0, and since it doesn't find it there (we hope!) it then has to recurse up into the "parent" namespace, which is globals. It finds a controls namespace there and goes into it and looks for "gearDown." Upon finding it, Nasal then executes that script with "1" as an argument, and the gear lowers. Thus it is really two separate lookups – Nasal looks for controls and then gearDown inside that. For the first lookup, it is looking for a variable and can recurse into higher namespaces, for the second it can only go down from the namespace it found. This recursion into other namespaces is kind of like the lookup into hashes' "parents" vector, any "get" operations go look in the hash proper, then into the first "parent" index (though namespaces only have one parent), and any parents of the parents, etc., until something is found. Unlike hashes, however, "set" operations do not always stay in the actual hash, Nasal first tries to find the variable the same way as it does with "get" operations, but then if it isn't found it creates one in the current namespace. With the 'var' keyword, however, it doesn't look anywhere but just creates a new one in the current namespace. Namespaces also resemble hashes in another way – they in fact are hashes! Nasal thinks of namespaces as just another hash, and this challenges a common notion of programmers, that of "lvalues." Typically (I think?), programmers can only declare named variables that are legal lvalues – that is, they have to fit a certain pattern. The pattern is usually something like this: a name can start with an underscore or alpha character and all remaining characters must be an underscore or an alphanumeric character. The lvalue ends at the first character that doesn't fit that pattern, e.g. a punctuation mark. But in Nasal hashes, one can use arbitrary scalars (strings and/or numbers) as indexes:

a_hash["(foo)"] = 78;

This means that namespaces can contain ‘variables’ that aren't valid lvalues and thus can't be used in typical code. Also notice that the dialog's namespaces are not lvalues as they have a colon and thus can't be used like the controls namespace can. Instead, one must use various methods to access non-lvalues. For more, see the "Doing more with your namespace – Nasal style" section.

Every single namespace in Nasal is just a hash. The most common namespaces are the ones inside the Nasal modules ([[$FG_ROOT]]/Nasal) and the globals namespace, these are probably the easiest to understand. In fact everything needs to run in namespace, and that includes joystick bindings. But less understood is the fact that every function creates it's own anonymous namespace to run in, e.g. gearDown in controls.nas has its own namespace that it runs in. These namespaces are not assigned a name like the controls namespace is. Instead, they simply exist as a part of the function and can only be fetched using closure() level 0. Anyways, this has the obvious implications that any variables created inside the function stay in that function (and get destroyed after the function returns). A function can also modify variables in the outer scope, either by leaving out the 'var' qualifier or by using caller(). Local variables cannot be accessed from the outer scope, as far as I know, though I am not sure what closure returns for such things. This notion of functions creating new namespaces has some interesting implications, see "Advanced namespace hacking: security wrappers".

== Dealing with Different Namespaces at Once ==

Anyways, back to the graph. Each portion of the graph has its own variables, some of which might be functions with their own namespaces, and some are hashes that are used as objects – not namespaces. We learned that the Nasal parser looks first at the current namespace for a symbol, then the next higher namespace, until it reaches the top. But what if we define a variable in this scope and we want to access another variable that has the same name but lives in a different namespace? This is what happens in debug.nas; it defines a string function which obscures the string namespace (in computer science this is called [[en.wikipedia.org/Variable_Shadowing_|shadowing]]). To use the string namespace, there are two options: use caller() to manually "hop" up the namespace tree or prefix "globals[dot]" to the symbol like this:

Since it is recursive, one can prefix globals as many times as they want to without any change, it also leads to a stack overflow when debug.dump() tries to dump the global namespace (there are a couple hacks to fix this, though).

It redefines the removelistener() function inside of an anonymous namespace. It first copies the function that was previously defined, whether it was implemented in C or if it was another wrapper. Notice how this cannot be accessed outside of the namespace. It then defines a function (which is implicitly returned) that checks some conditions and either passes the argument and returns the result of the call to the original removelistener function, or it dies and denies access to the original function. This cleverly removes any access to the original function but it still allows access to it – after adding a layer of security.

== Doing more with your namespaces, Nasal style. ==

These all deal with namespaces is some way, shape, or form. The functions caller() and closure() are the most alike, to illustrate their relationship, one can say the first argument to closure() is the second index (the function) or what is returned by caller() and the return of closure() is the first index of caller() with a level one greater than the previous evaluation. In other words (FIXME):

closure(caller(0)[1], level) == caller(level)[0];

The function call() gives enormous control over how a function is executed, from the 'me' variable and the arguments to the namespace it will be executed in. The ‘official’ prototype given is this:

And it goes on and on. What if you could just do it automatically? Your first attempt might go like this:<syntaxhighlight lang="php">

The advantage of the second is that you can use it for any new() method without duplicating code, it also has less symbols it has to avoid.