Nasal library functions

It has been suggested that this article or section be merged with Nasal library.

Please first see: http://plausible.org/nasal/lib.html

A better and more complete description of these functions can also be found at http://wiki.flightgear.org/Nasal_library and in $FG_ROOT/Docs

size()

Usage:

size(object);

where object may be a string, a vector or a hash.

Return value

An intger equal to the number of characters in a string argument or the number of elements in a vector or hash.

If the argument is a non-string scalar then the error object has no size() will be generated.

setsize()

Usage:

setsize(vect, new_size)

where vect is an expression which evaluates to a vector and new_size is an expression that evaluates to a non-negative number.

Action:

Changes the number of elements in the vetor v to the value of s.

Return value:

The resized vector.

Notes

Elements that exist in both the original and the resized vector retain their values. When the vector is enlarged newly created elements are set to nil. When the size is reduced the values of all elements beyond the new size are permanently lost.

The new_size argument may be any non-negative number. Non-integer values are rounded down.

The vect argument need not be a named variable. The expression:

var v1 = setsize([], n);

Is a convenient way to allocate an empty vector of a specific size.

subvec()

Create a new vector comprising elements from a contiguous range of elements of an existing vector.

Usage:

subvec([vect, [start, [count]]])

vect

The original vector

start

The zero-based index in the original vector of the first element to be copied.

count

The number of elements to copy. If this argument is omitted then size(vect) - start is assumed.

Return value

A new vector containing the specified range from the original vector, or nil.

Notes:

1. Omitting the vect and start arguments is not an error (possibly it should be) but the return value is nil.
2. A negative start argument is an error. This seems wrong. Perhaps the language designer could comment.
3. A value of start greater than size(vect) causes an error. A value equal to size(vect) returns an empty vector.
4. If the value of count is greater than size(vect) - start then it is ignored. That is, all elements from start to the end of vect are returned. If count is zero then an empty vector is returned. A negative value of count causes an error.

Example :

var FGRoot = getprop("/sim/fg-root");
var filename = "/Aircraft";
var path_files = directory(FGRoot ~ filename);

foreach(var key; path_files) {
print(key);
}

returns : "." , ".." , "Generic", "Instruments", "Instruments-3d", "c172p", "ufo"

With subvec():

var FGRoot = getprop("/sim/fg-root");
var filename = "/Aircraft";
var path_files = subvec(directory(FGRoot ~ filename),2);

foreach(var key; path_files) {
print(key);
}

returns : "Generic", "Instruments", "Instruments-3d", "c172p", "ufo"

var FGRoot = getprop("/sim/fg-root");
var filename = "/Aircraft";
var path_files = subvec(directory(FGRoot ~ filename),3);

foreach(var key; path_files) {
print(key);
}

returns : "Instruments", "Instruments-3d", "c172p", "ufo"

delete()

Remove an element from a hash.

Usage

delete(hash, key)

Remove the element with key key from the hash hash. If the key is not present then the hash is unaltered.

num(str)

Convert string to number. Returns nil if str is nil, empty string, string with no number.

ghosttype(ghost)

Returns a string containing either a descriptive name as passed to naNewGhost or naNewGhost2 in C/C++ while creating the ghost or a unique id (aka the pointer to the C/C++ naGhostType instance) if no name has been set.

math

Trigonometric_functions

Caution: All trigonometric functions works with Radian-values - not with Degree!

To convert this:
radians = degree * math.pi / 180
degree = radians * 180 / math.pi

floor()

Returns the value rounded downward

Example:

math.floor(1.2); # returns 1
math.floor(1.6); # returns 1

ceil()

Returns the value rounded upward

Example:

math.ceil(1.2); # returns 2
math.ceil(1.6); # returns 2

fmod()

A modulo-operator. The modulo-operation finds the remainder of division of one number by another (sometimes called modulus).

fmod(x , y) may be negative if x < 0, whereas mod() seems to guarantee that 0 ≤ mod(x,y) < y, according to tests made with x and y integers, y > 0, x positive or negative.

io

• SEEK_SET
• SEEK_CUR
• SEEK_END
• stdin
• stdout
• stderr

directory()

returns the files in a given directory

e.g. chatter_list = directory( chatter_dir );

Example :

var FGRoot = getprop("/sim/fg-root");
var filename = "/Aircraft";
var path_files = directory(FGRoot ~ filename);

foreach(var key; path_files) {
print(key);
}

returns : "." , ".." , "Generic", "Instruments", "Instruments-3d", "c172p", "ufo"

To delete the "." and ".." see the subvec() function.