Howto:Start using vectors and hashes in Nasal: Difference between revisions

Imagine a piece of Nasal code working with 5 different waypoints. You would need to manage the data for each waypoint. A simple version using different variables for each data set might look like this:

var wp1 = 0;

var wp1alt = 0;

Such code contains so called "code smells", another example would be code like this:

var l0 = "";

var l1 = "";

</syntaxhighlight>

The problem is, that this only gives us a list of single waypoints:

</syntaxhighlight>

To do this using a conventional for loop, you would use the size() function to get the size of the vector:

var waypoints = ["wp1","wp2","wp3","wp4","wp5"];

for(var index; index < size(waypoints); index=index+1) {

The same thing can be accomplished using the forindex loop:

var waypoints = ["wp1","wp2","wp3","wp4","wp5"];

forindex(var index; waypoints) {

Now, waypoints being a vector, we can also use a simple foreach loop, that works without a counter, to process each element easily:

var waypoints = ["wp1","wp2","wp3","wp4","wp5"];

foreach(var wpt; waypoints) {

What we really need to save all the other waypoint specific information is a new variable type that serves as the "container" for variables, so that we can save several variables for each waypoint.

var wp4 = 0;      # waypoint number

var wp4alt = 0;    # waypoint altitude

So we could be using a "main" vector to store all waypoints, while each field of the main vector is a different vector that contains all waypoint-specific data.

var wp4 = 0;      # waypoint number

var wp4alt = 0;    # waypoint altitude

So, the very first vector element would be waypoints[0] and it would point to another vector (waypoint4), the elements of waypoint4 would be also available by index:

var wp4 = 1;        # waypoint number

var wp4alt = 1000;  # waypoint altitude

Obviously, you could add a bunch of other waypoints to the "waypoints" vector, too:

var waypoint4 = [wp4,wp4alt,wp4dist,wp4angle,wp4length,wp4id, wp4brg];

var waypoint5 = [wp5,wp5alt,wp5dist,wp5angle,wp5length,wp5id, wp5brg];

The only problem with this approach is, that you'll need to set up all those wp variables - so there's a shorter version possible, by directly adding your data without using variables, i.e. "inline":

var waypoint4 = [1,1000,12,22,44,"none", 33];

var waypoint5 = [2,1500,22,42,14,"none", 133];

There's an even more succinct version possible. The next step would be to use embedded vectors directly:

var waypoints = [

  [1,1000,12,22,44,"none", 33],  

This is just formatted for clarity, the following snippet would be equivalent, but not as readable to people new to vectors:

var waypoints = [ [1,1000,12,22,44,"none", 33],  [2,1500,22,42,14,"none", 133] ];

</syntaxhighlight>

Accessing such a vector with embedded (or nested) vectors is still as simple:

var waypoints = [[1,1000,12,22,44,"none", 33], [2,1500,22,42,14,"none", 133]]

print(waypoints[0][0]) # prints 1

The only issue here is that you'll need to keep vector ordering in mind, so that you can always access the right element number. This could be simplified by using some variables with telling names as the index for each vector:

# these are used self-explanatory indices - so that you don't need to remember each field's position:

var NUMBER=0; var ALTITUDE=1; var DISTANCE=2; var ANGLE=3; var LENGTH=4; var ID=5; var BRG=6;

Now, this yields already fairly readable source code:

var NUMBER=0; var ALTITUDE=1; var DISTANCE=2; var ANGLE=3; var LENGTH=4; var ID=5; var BRG=6;

var waypoints = [[1,1000,12,22,44,"none", 33], [2,1500,22,42,14,"none", 133]]

So, this would already be much better than our original version, because we can now have an arbitrary number of waypoints. New waypoints would need to be added to the waypoints vector by using the append() library function:

var NUMBER=0; var ALTITUDE=1; var DISTANCE=2; var ANGLE=3; var LENGTH=4; var ID=5; var BRG=6;

var waypoints = [[1,1000,12,22,44,"none", 33], [2,1500,22,42,14,"none", 133]]

Next, we could come up with some helper functions to deal with the vector details transparently, using the same method as before: self-explanatory indices, which spares us having to remember the purpose of each field:

var NUMBER=0; var ALTITUDE=1; var DISTANCE=2; var ANGLE=3; var LENGTH=4; var ID=5; var BRG=6;

var waypoints = [[1,1000,12,22,44,"none", 33], [2,1500,22,42,14,"none", 133]];

You could even add some more high level helpers for each waypoint field:

var NUMBER=0; var ALTITUDE=1; var DISTANCE=2; var ANGLE=3; var LENGTH=4; var ID=5; var BRG=6;

var waypoints = [[1,1000,12,22,44,"none", 33], [2,1500,22,42,14,"none", 133]];

Consider the following empty hash:

var waypoint = {};

</syntaxhighlight>

Next, we are going to add some fields to our new variable "container". Each new field can be assigned an initial value, this is done by treating the field as a value/key pair, with a colon (:) separating both. And with multiple fields being separated by a comma (formatting only added for clarity):

# declare a new hash named waypoint

var waypoint = {

which is equivalent to this, more succinct, version:

var waypoint = {number:0,altitude:0,distance:0,angle:0,length:0,ID:0,bearing:0};

</syntaxhighlight>

Now, to access any of these fields, we would use the "dot notation" by first specifying the name of the enclosing context (which is really just a fancy word for the name of the hash) and the name of the field we are interested in. You could read this as: LOCATION.FIELD (i.e. get FIELD out of location).

var waypoint = {number:0,altitude:0,distance:0,angle:0,length:0,ID:0,bearing:0};

print ( waypoint.number );

Now, to make this is a little more interesting and to show what's happening, we are going to change the value of each field:

var waypoint = {number:1,altitude:2,distance:3,angle:4,length:5,ID:6,bearing:7};

print ( waypoint.number ); # prints 1

So, you could obviously create several different versions of this hash to store your waypoint data:

var waypoint1 = {number:1,altitude:2,distance:3,angle:4,length:5,ID:6,bearing:7};

var waypoint2 = {number:1,altitude:2,distance:3,angle:4,length:5,ID:6,bearing:7};

As you may have noticed, the code (internal structure of fields) for each waypoint is 100% identical - so we could just as well tell the Nasal engine to use an existing hash as a TEMPLATE for a new object instead of having to replicate the hash over and over again. This is accomplished using the "parents" keyword:

var Position3D = {x:1.00, y:2.00, z:3.00};

var p1 = { parents: [Position3D] };

This means, that the previously posted code could be easily abbreviated and written like this:

var waypoint1 = {number:1,altitude:2,distance:3,angle:4,length:5,ID:6,bearing:7};

var waypoint2 = {parents:[waypoint1] };

You could even introduce a new helper function to create new objects, let's call it new_waypoint:

var waypoint = {number:1,altitude:2,distance:3,angle:4,length:5,ID:6,bearing:7};

var new_waypoint = func() {

or using a vector for each object, which has the added advantage that you can easily create arbitrary amounts of waypoints on demand:

# this is our template for new waypoints

var waypoint = {number:1,altitude:2,distance:3,angle:4,length:5,ID:6,bearing:7};

A shorter version would read:

var waypoint = {number:1,altitude:2,distance:3,angle:4,length:5,ID:6,bearing:7};

var new_waypoint = func {return {parents:[waypoint] };}

Now, given that the creation of new hashes using a template class is such a common thing to do - we could just as well add a new function to the parent hash that we can use to construct new hashes. As you could see already, the fields (or members) of a hash are specified in a well-defined form using the key/value format where key and value are separated by a colon: "field_name:value".  

var waypoint1 = {

     number:1,

This isn't any different for fields that are of type "function":

var waypoint = {

     number:1,

Note that we have added a new field named "hello" to our waypoint hash. This can be easily accessed and also called:

var waypoint = {

     number:1,

On the other hand, we were just about to make construction of such hashes much simpler. This can be done by creating a new function that constructs hashes dynamically using a hash:

var make_waypoint = func {

     return { parents:[waypoint] };

Next, we are going to change the function and and embed it into the hash, so that the constructor function becomes a part of the class, renaming it to "new":

var waypoint = {

     number:1,

So, whenever we need a new hash object of type "waypoint", we can simply call this construction function (which we'll call a constructor from now on):

var wp = waypoint.new();

</syntaxhighlight>

Sometimes, you'll work with classes that do not have any custom constructor functions - but you can easily create a generic constructor, too:

var new = func(obj) {

     return {parents:obj};

As long as '''obj''' is a vector of hashes, it can be simply invoked like this:

var p = new( [Position3D] );

</syntaxhighlight>

Now, once you remember that Nasal implicitly has an '''arg''' vector for its arguments, the whole thing can be simplified like this:

var new = func {

     return {parents:arg};

To make this look a little nicer, we can also rename the default argument vector (i.e. args) to something more informative, like "classes":

var new = func(classes...) {

     return {parents:classes};

A simple generic constructor can be expressed in a very succinct fashion:

# a new function with an implicit arg parameter that simply returns a new hash with the parents field set to all arguments provided

var new = func return { parents:arg };

This can be accomplished using the "me" keyword which ensures that the member function is always referring to the currently active object (itself):

var waypoint = {

     number:1,

On the other hand, maybe you'd like to add some information (such as the number) during construction time to the object. So this would require changing the constructor function to accept a parameter, too:

var waypoint = {

     number:1,

Now, to actually set the number field during construction time to the value of n, you could create a temporary hash:

     new: func(n) {

         var t={parents:[waypoint]};

Or in its entirety:

var waypoint = {

     number:1,

var waypoint = {

     number:1,

Note how this creates a vector of 5 waypoints (0..4), each of these waypoints is a full object that can be conveniently accessed:

waypoints[0].bearing = 100;

waypoints[1].altitude = 100;

You can also use Nasal's support for looping to conveniently process these waypoints:

var waypoint = {

     number:1,

As you may remember, the parents keyword points not just to a single "class template" (hash), but instead to a vector of hashes. This makes it possible to use several different hashes as the template for a new hash:

var new = func return {parents:arg};

The difference when dealing with these relationships is that whenever something "IS" something, the right thing to do is to directly create a new object using the parent class:

var new = func return {parents:arg};

var animal = {eyes:0,ears:0};

Now, imagine we wanted to keep the number of legs for each animal, too: 4 legs for dogs and cats, 2 legs for birds and 8 legs for spiders:

var new = func return {parents:arg};

var animal = {eyes:0,ears:0,legs:0};

However, at some point we may need additional information for each leg - such as the length of each leg. That's where we use a new "leg" class (an animal HAS legs), so that the animal class no longer just contains the number of legs, but rather contains a vector of "leg" objects:

var new = func return {parents:arg};

var leg = {length:0};