Nasal library/debug: Difference between revisions
Red Leader (talk | contribs) (Doc rank()) |
Red Leader (talk | contribs) (→string(): Doc) |
||
Line 292: | Line 292: | ||
=== string() === | === string() === | ||
{{Nasal doc | {{Nasal doc | ||
|syntax = debug.string(); | |syntax = debug.string(o[, color]); | ||
|text = | |text = Converts its argument to a string and returns it. | ||
|param1 = | |param1 = o | ||
|param1text = | |param1text = Thing to return as a string. | ||
|example1 = | |param2 = color | ||
|param2text = Optional bool specifying whether to output the string with an {{wikipedia|ANSI escape code#Colors|ANSI color code}}. Defaults to <code>'''nil'''</code>. | |||
|example1 = print(debug.string(nil)); # prints "nil" | |||
print(debug.string(1.25)); # prints "1.25" | |||
print(debug.string("Hello, World!")); # prints 'Hello, World!' | |||
print(debug.string(["a", "b", "c"])); # prints "['a', 'b', 'c']" | |||
print(debug.string({ "a": 1, "b": 2, "c": 3 })); # prints "{ a: 1, c: 3, b: 2 }" | |||
print(debug.string(props.globals.getNode("/sim/time/gmt"))); # prints "</sim/time/gmt = '2016-12-04T18:58:18' (STRING, AT, #1)>" (value may be different) | |||
print(debug.string(airportinfo())); # prints "<airport>" | |||
print(debug.string(func(){})); # prints "<func>" | |||
}} | }} | ||
Revision as of 20:50, 4 December 2016
Work in progress This article or section will be worked on in the upcoming hours or days. See history for the latest developments. |
The FlightGear forum has a subforum related to: Nasal Scripting |
Nasal scripting |
---|
Nasal internals |
---|
Memory Management (GC) |
This page contains documentation for the debug
namespace in Nasal. This namespace provides various useful APIs for debugging Nasal code. The debug
namespace is sourced from fgdata/Nasal/debug.nas.
Functions
attributes()
debug.attributes(p[, verbose[, color]]);
Returns a string showing the attributes of the node, in the form (type[, attr[, Lnum[, #refs]])
. See the table below for explanation.
Data | Meaning |
---|---|
type | Type of node as returned by props.Node.getType() .
|
attr | Various attribute flags, see props.Node.getAttribute() . "r" = read protected, "w" = write protected, "R" = trace read, "W" = trace write, "A" = archive, "U" = userarchive, "P" = preserve, and "T" = tied.
|
num | Number of listeners, if any. |
refs | This argument will be shown if verbose is true. Tells the number of references to the node. Note that all nodes have two references by default, but this tells the number of extra references. |
- p
- Mandatory
props.Node
object. - verbose
- Optional bool specifying whether to show the number of times the node is referenced. Defaults to 1 (true).
- color
- Optional bool specifying whether to output the string with an ANSI color code . Defaults to
nil
.
Examples
var node = props.globals.getNode("/sim/time/gmt");
print(debug.attributes(node)); # prints "(STRING, AT, #1)" - string, archive, tied, 1 extra ref
var node = props.Node.new();
node.setIntValue(12);
node.setAttribute(17);
print(debug.attributes(node)); # prints "(INT, wR)" - integer, write protected, trace read
var node = props.globals.getNode("/sim/signals/fdm-initialized");
print(debug.attributes(node)); # prints "(BOOL, L6, #16)" - bool, 6 listeners, 16 extra refs
backtrace()
debug.backtrace([desc]);
When called, this function prints the backtrace , also printing the local variables at each level.
- desc
- Optional extra description to add.
Examples
var myFunc = func(a){
multiply(a, 2);
}
var multiply = func(x, y){
debug.backtrace();
}
myFunc(2);
var myFunc = func(a){
multiply(a, 2);
}
var multiply = func(x, y){
debug.backtrace("multiply() function");
}
myFunc(2);
bt()
debug.bt([desc]);
Shortcut for backtrace()
. See doc there
benchmark()
debug.benchmark(label, fn[, repeat[, output]]);
Analyses the amount of time a function takes to run. If repeat is given and output is not, the time taken to repeat the function the given amount off times will be printed. If both are given, the return value of each repeat of the function will be returned in a vector output.
- label
- Label to add to the output.
- fn
- Function to call.
- repeat
- Optional integer specifying how many times the function is to be run. If not given, the function will be run once.
- output
- Optional vector that will be returned with the return value of each function.
Examples
var test = func(){
var children = props.globals.getNode("sim").getChildren();
var vec = [];
foreach(var child; children){
append(vec, child.getChildren());
}
return vec;
}
var result = debug.benchmark("test()", test);
debug.dump(result);
var test = func(){
var children = props.globals.getNode("sim").getChildren();
var vec = [];
foreach(var child; children){
append(vec, child.getChildren());
}
return vec;
}
debug.benchmark("test()", test, 10);
var test = func(){
var children = props.globals.getNode("sim").getChildren();
var vec = [];
foreach(var child; children){
append(vec, child.getChildren());
}
return vec;
}
var result = debug.benchmark("test()", test, 10, []); # this example may cause a small pause
debug.dump(result);
benchmark_time()
debug.benchmark_time(fn[, repeat[, output]]);
Behaves in exactly the same way as benchmark()
, but returns the amount of time taken, rather than printing it out.
- fn
- Function to call.
- repeat
- Optional integer specifying how many times the function is to be run. If not given, the function will be run once.
- output
- Optional vector that will be returned with the return value of each function.
Examples
var test = func(){
var children = props.globals.getNode("sim").getChildren();
var vec = [];
foreach(var child; children){
append(vec, child.getChildren());
}
return vec;
}
print(debug.benchmark_time(test));
var test = func(){
var children = props.globals.getNode("sim").getChildren();
var vec = [];
foreach(var child; children){
append(vec, child.getChildren());
}
return vec;
}
print(debug.benchmark_time(test, 10));
var test = func(){
return getprop("/sim/time/gmt");
}
print(debug.benchmark_time(test, 1000, var res = []));
debug.dump(res);
dump()
debug.dump([arg[, arg[, ...]]]);
Dumps the given arguments in the console. If no arguments of given, the local namespace will be dumped.
- arg
- Anything. Literally, anything. There may be as may arguments as you like. If more than one argument is given, each will be dumped separately with an index.
Examples
var x = nil;
debug.dump(); # prints "{ x: nil, arg: [] }"
debug.dump("Hello, World!"); # 'Hello, World!'
debug.dump(1234); # 1234
debug.dump(nil); # nil
debug.dump(["a", "b", "c"]); # ['a', 'b', 'c']
debug.dump({ a: 1, b: 2, c: 3 }); # { a: 1, b: 2, c: 3 }
debug.dump(props.Node.new()); # < = nil (NONE)>
debug.dump(airportinfo()); # <airport>
debug.dump(func(a){ print(a); }); # <func>
debug.dump( # dump, showing the index of each argument
"Hello, World!",
1234,
nil,
["a", "b", "c"],
{ a: 1, b: 2, c: 3 },
props.Node.new(),
airportinfo(),
func(a){ print(a); },
);
isnan()
debug.isnan(num);
Checks whether a number actually is a valid number and returns 0 (false) if it is and 1 (true) if it is not.
- num
- Number to check.
Examples
print(debug.isnan(1.234)); # prints "0" (1.234 is valid)
print(debug.isnan(1/0)); # prints "1" (division by 0 is undefined)
local()
debug.local([frame]);
Prints and also returns a hash containing all the local variables.
- frame
- Optional integer specifying the frame. Corresponds to the argument given to
caller()
.
Examples
var n = 12;
debug.local(); # prints "{ n: 12, arg: [] }"
var sqr = func(a){
debug.local(); # prints "{ a: 16 }"
debug.local(1); # prints "{ sqr: <func>, arg: [] }"
return a * a;
}
print(sqr(16));
print_rank()
debug.print_rank(label, list, names);
Formats and prints results from rank()
. It will show them in order of fastest to slowest, the time taken in milliseconds, and what percentage of time each took relative to the slowest.
- label
- Label to add to the results header.
- list
- Results vector from
rank()
. - names
- Either a vector or hash that will supply the names of the functions. If a hash, it must have the structure of
{ name: func, ... }
. If a vector, its structure can be either[[name, func], ...]
or[[func, name], ...]
Example
var getElev = func(){
var pos = geo.aircraft_position();
return geo.elevation(pos.lat(), pos.lon());
}
var getTime = func(){
return getprop("/sim/time/gmt");
}
var list = [getElev, getTime];
var result = debug.rank(list, 1000);
var names = [["getElev", getElev], ["getTime", getTime]];
#var names = [[getElev, "getElev"], [getTime, "getTime"]]; # other option
#var names = { # third option
# "getElev": getElev,
# "getTime": getTime
#};
debug.print_rank("getElev() and getTime()", result, names);
printerror()
debug.printerror(err);
Prints out errors from call()
.
- err
- Error vector from
call()
.
Example
call(func {
print(math.ip); # should be math.pi, not math.ip
}, [], nil, nil, var err = []);
debug.printerror(err); # prints "no such member" error
print("Hello again"); # this will still print
propify()
debug.propify(p[, create]);
Attempts to turn its argument into a props.Node
object and return it. If it can't, it will return nil
.
- p
- Thing to turn into a node. May be a
props.Node
object, aprop
ghost, or a string pointing to a property. - create
- If the above argument is a string, this specifies whether to create the property. Defaults to 0 (false).
Examples
var p = canvas._newCanvasGhost()._node_ghost;
debug.dump(debug.propify(p));
var p = "/sim/time/gmt";
debug.dump(debug.propify(p));
var p = "/demo";
debug.dump(debug.propify(p, 1));
var p = func(){ print("Hello, World!"); }
debug.dump(debug.propify(p)); # prints "nil"
proptrace()
debug.proptrace([root[, frames]]);
Traces changes to a given part of the property tree. It flags up when a child node is added, the value of a node is set, and a node is deleted.
- root
- Optional
props.Node
object, aprop
ghost, or a string, all pointing to a property. Defaults to the root of the property tree. - frames
- Optional number of frames to trace for. Defaults to 2.
Example
var n = props.globals.getNode("/demo", 1);
debug.proptrace("/demo", 10);
var c = n.addChild("foo")
c.setIntValue(12)
c.remove();
rank()
debug.rank(list[, repeat]);
Benchmarks a given list of functions and returns them in a vector with them sorted from fastest to slowest. The result vector will be in the form of [[func, time], ...]
. This result vector can be processed by print_rank()
.
- list
- Vector containing the functions to
benchmark()
. - repeat
- Number of times to repeat each function.
Example
var getElev = func(){
var pos = geo.aircraft_position();
return geo.elevation(pos.lat(), pos.lon());
}
var getTime = func(){
return getprop("/sim/time/gmt");
}
var list = [getElev, getTime];
var result = debug.rank(list, 1000); # repeat 1,000 times
debug.dump(result); # getTime() will be first
string()
debug.string(o[, color]);
Converts its argument to a string and returns it.
- o
- Thing to return as a string.
- color
- Optional bool specifying whether to output the string with an ANSI color code . Defaults to
nil
.
Example
print(debug.string(nil)); # prints "nil"
print(debug.string(1.25)); # prints "1.25"
print(debug.string("Hello, World!")); # prints 'Hello, World!'
print(debug.string(["a", "b", "c"])); # prints "['a', 'b', 'c']"
print(debug.string({ "a": 1, "b": 2, "c": 3 })); # prints "{ a: 1, c: 3, b: 2 }"
print(debug.string(props.globals.getNode("/sim/time/gmt"))); # prints "</sim/time/gmt = '2016-12-04T18:58:18' (STRING, AT, #1)>" (value may be different)
print(debug.string(airportinfo())); # prints "<airport>"
print(debug.string(func(){})); # prints "<func>"
tree()
debug.tree();
warn()
debug.warn();