Nasal library: Difference between revisions

{{Nasal doc

|syntax = append(vector, element[, element[, ...]]);

|text = This function appends, or adds, the given element(s) to the end of the vector given in the first argument.  Returns the vector operated on.

|param1 = vector

{{Nasal doc

|syntax = bind(function, locals[, outer_scope]);

|text = This creates a new function object. A function in Nasal is three things: the actual code, a hash/namespace of local variables available to the function namespace, and the closure object of that namespace. These correspond to the three arguments respectively.

|param1 = function

{{Nasal doc

|syntax = call(func[, args[, me[, locals[, error]]]);

|text = Calls the given function with the given arguments and returns the result.  This function is very useful as it allows much more control over function calls and catches any errors or {{func link|die()}} calls that would normally trigger run-time errors cancelling execution of the script otherwise.  

|param1 = func

{{Nasal doc

|syntax = caller([level]);

|text = Returns a vector containing a record from the current call stack.  The level numbering starts from the currently executing function (level 0).  Level 1 (the default) is the caller of the current function, and so on.

{{Nasal doc

|syntax = chr(code);

|text = Returns a character as per the single argument. Extended ASCII is supported (see http://www.asciitable.com/ for a list of supported characters), although this may vary between different systems.  For a list of the most commonly used characters, see the {{wikipedia|ASCII#ASCII printable code chart|ASCII printable code chart}} ('''Dec''' column). The following table lists supported control characters, along with their equivalent control characters in Nasal strings.  {{Note|In Nasal, only strings enclosed with double-quotes (<code>"string"</code>) supports control chracters.  Strings in single quotes (<code>'string'</code>) do not.}}

{{{!}} class="wikitable"

{{Nasal doc

|syntax = closure(func[, level]);

|text = Returns the hash table containing the lexical namespace of the given function. The level numbering start with level 0 being the namespace of '''func'''.  

|param1 = func

{{Nasal doc

|syntax = cmp(a, b);

|text = Compares two strings, returning -1 if '''a''' is less than '''b''', 0 if they are identical and 1 if '''a''' is greater than '''b'''.  

|param1 = a

{{Nasal doc

|syntax = compile(code[, filename]);

|text = Compiles the specified code string and returns a function object bound to the current lexical context.  If there is an error, the function dies, with the argument to {{func link|die()}} being '''filename'''.

|param1 = code

{{Nasal doc

|syntax = contains(hash, key);

|text = Returns 1 (True) if the hash contains the specified key, or 0 (False) if not.

|param1 = hash

{{Nasal doc

|syntax = contains(vector, item);

|text = Returns 1 (True) if the vector contains the specified item, or 0 (False) if not.

|param1 = vector

{{Nasal doc

|syntax = delete(hash, key);

|text = Deletes the key from the hash if it exists. Operationally, this is NOT identical to setting the hash value specified by the key to <code>'''nil'''</code> as the key will stay in the hash (at least for a while). This variant potentially frees storage by deleting the reference to the key and by shrinking the hash.  Returns the hash that has been operated on.

|param1 = hash

{{Nasal doc

|syntax = die(error);

|text = Terminates execution and unwinds the stack.  The place and the line will be added to the '''error'''.  This invokes the same internal exception handler used for internal runtime errors. Use this to signal fatal errors, or to implement exception handling. The error thrown (including internal runtime errors) can be caught with {{func link|call()}}.

|param1 = error

{{Nasal doc

|syntax = find(needle, haystack);

|text = Finds and returns the index of the first occurrence of the string '''needle''' in the string '''haystack''', or -1 if no such occurrence was found.

|param1 = needle

{{Nasal doc

|syntax = ghosttype(ghost);

|text = Returns a string containing either a descriptive name of a ghost (a raw C/C++ object), or a unique id (the pointer to the C/C++ <code>naGhostType</code> instance) if no name has been set.  Ghost is an acronym that stands for '''G'''arbage-collected '''H'''andle to '''O'''ut'''S'''ide '''T'''hingy.

|param1 = ghost

{{Nasal doc

|syntax = id(object);

|text = Returns a string containing information on the type and ID of the object provided in the single argument.  The information is returned in the form of <code>'''<type>''':'''<id>'''</code>, where '''<type>''' is the type of object, and '''<id>''' is the ID.

|param1 = object

{{Nasal doc

|syntax = int(number);

|text = Returns the integer part of the numeric value of the single argument, or <code>'''nil'''</code> if none exists.

|param1 = number

{{Nasal doc

|syntax = keys(hash);

|text = Returns a vector containing the list of keys found in the single hash argument.  

|param1 = hash

{{Nasal doc

|syntax = left(string, length);

|version = 2.12

|commit = {{simgear commit|bd7163|t=commit}}

{{Nasal doc

|syntax = num(number);

|text = Returns the numerical value of the single string argument, or <code>'''nil'''</code> if none exists.  

|param1 = number

{{Nasal doc

|syntax = pop(vector);

|text = Removes and returns the last element of the single vector argument, or <code>'''nil'''</code> if the vector is empty.  

|param1 = vector

{{Nasal doc

|syntax = range([start, ]stop[, step]);

|text = Creates a vector of numbers starting from <code>start</code> (default 0) up to but not including <code>stop</code>, incremented by <code>step</code> (default 1). Note: To specify <code>step</code>, you must also provide <code>start</code>; otherwise the second argument is interpreted as <code>stop</code>.

|param1 = start

{{Nasal doc

|syntax = removeat(vector, index);

|text = Removes the element at the specified index from the vector and returns it.

|param1 = vector

{{Nasal doc

|syntax = right(string, length);

|version = 2.12

|commit = {{simgear commit|bd7163|t=commit}}

{{Nasal doc

|syntax = setsize(vector, size);

|text = Sets the size of a vector. The first argument specifies a vector, the second a number representing the desired size of that vector. If the vector is currently larger than the specified size, it is truncated. If it is smaller, it is padded with <code>'''nil'''</code> entries. Returns the vector operated upon.  

|param1 = vector

{{Nasal doc

|syntax = size(object);

|text = Returns the size of the single argument. For strings, this is the length in bytes. For vectors, this is the number of elements. For hashes, it is the number of key/value pairs. If the argument is <code>'''nil'''</code> or a number, this error will be thrown: <code>object has no size()</code>.

|param1 = object

{{Nasal doc

|syntax = sort(vector, function);

|text = Returns a vector containing the elements in the input '''vector''' sorted in according to the rule given by '''function'''. Implemented with the ANSI C {{func link|qsort()|link=http://www.cplusplus.com/reference/cstdlib/qsort/}}, <code>sort()</code> is stable.  This means that if the rules in the first example are used, equal elements in the output vector will appear in the same relative order as they do in the input.  It is run in a loop, so '''function''' is run several times.

|param1 = vector

{{Nasal doc

|syntax = split(delimiter, string);

|text = Splits the input string into a vector of substrings bounded by occurrences of the delimiter substring. See [[Nasal_library/string#string.join(sep,list)|string.join()]].

|param1 = delimiter

{{Nasal doc

|syntax = <nowiki>sprintf(format[, arg[, arg, [...]]]);</nowiki>

|text = Creates and returns a string formatted using ANSI C {{func link|vsnprintf()|link=http://en.cppreference.com/w/c/io/vfprintf}} <ref>

{{Cite web

{{Nasal doc

|syntax = streq(a, b);

|text = Tests the string values of the two arguments for equality. This function is needed because the <code>'''=='''</code> operator (see [[Nasal_Operators#Equality|Nasal Operators]]) tests for numeric equality first.  If either or both the arguments are not strings, 0 (False) will be returned.  Returns either 0 (False) or 1 (True).  {{Note|This function is rarely required in typical code.}}

|param1 = a

{{Nasal doc

|syntax = substr(string, start [, length]);

|text = Similar the {{func link|subvec()}}, but operates on strings. Computes and returns a substring. The first argument specifies a string, the second is the index of the start of a substring, the optional third argument specifies a length (the default is to return the rest of the string from the start).

|param1 = string

{{Nasal doc

|syntax = subvec(vector, start[, length]);

|text = Returns a sub-range of a vector. The first argument specifies a vector, the second a starting index, and the optional third argument indicates a length (the default is to the end of the vector).  

|param1 = vector

{{Nasal doc

|syntax = typeof(object);

|text = Returns a string indicating the whether the object is <code>'''nil'''</code>, a scalar (number or string), a vector, a hash, a function, or a ghost.

|param1 = object