This header defines the t3vm intrinsic function set. These functions provide access to basic features of the Virtual Machine.
T3DebugCheck - checks to see if an interactive debugger is present. No additional arguments; returns true if a debugger is present, nil if not.
T3DebugBreak - breaks into the interactive debugger, pausing execution at the current code location so that the user can inspect the current machine state and determine how to proceed. No additional arguments; after the user proceeds with execution, the function returns true to indicate that a debugger is present. If no debugger is present, the function simply returns nil, and has no other effect.
T3DebugLog - writes a message to the debug log. The second argument is a string with the text of the message to write. When running under an interactive debugger, the log is usually displayed as a window in the UI, or something similar. When running in a regular interpreter, the log is stored as a text file called tadslog.txt, in a directory location that varies by system. When a log file is used, the system automatically adds a timestamp to each message.
'which' specifies which table to retrieve:
T3GlobalSymbols - return the global symbol table
T3PreprocMacros - return the preprocessor macro table
If 'which' is omitted, the global symbol table is returned by default.
If the requested symbol table is available, this returns a LookupTable object; otherwise, it returns nil.
The symbol tables are available under two conditions. First, while pre-initialization is running during the program build (compiling) process, regardless of the debug/release mode being used for compilation. Second, during normal "t3run" execution, but only when the program has been compiled for debugging. When you compile in release mode, the compiler omits the debugging symbols from the .t3 image file to save space, so the symbol tables won't be available when running a release build under the interpreter.
If you want to access the symbol tables under normal execution (i.e., after preinit) in a release build, you can do it, but it requires an extra manual step. The trick is to call this function during preinit, when the symbol tables are definitely available regardless of the debug/release mode, and then save a reference to each desired table in an object property. This will ensure that the final image file saved after preinit completes includes the tables, because the object property reference ensures that the garbage collector won't delete them. Now, you *still* can't access the tables again at run-time by calling t3GetGlobalSymbols(), but you can instead get the same information from your saved object property.
'name' is a string giving the name of the argument to search for. This must exactly match the name of an argument passed by a caller with the "name: value" syntax. The match is case-sensitive.
'defval' is an optional default value to return if the argument doesn't exist. If 'deval' is specified, and the argument doesn't exist, the function returns 'defval'. If 'defval' is omitted, and the argument doesn't exist, the function throws an error.
If 'level' is an integer, we'll return a single T3StackInfo object giving the context at the given stack level - 1 is the active level, 2 is its caller, and so on, so 'level' would simply be the index in the returned list when this argument is omitted. If 'level' is omitted or nil, we return a list of T3StackInfo objects giving the entire stack trace.
If 'flags' is specified, it's a combination of T3GetStackXxx flags specifying additional options. If this isn't included, the default is 0 (i.e., all flags turned off).
The special values T3SetSayNoFunc and T3SetSayNoMethod can be passed to the function to remove any existing function or method, respectively, and are returned when appropriate to indicate that there was no previous setting.