t3.h file | source file

This header defines the t3vm intrinsic function set. These functions provide access to basic features of the Virtual Machine.

Summary of Classes

(none)

Summary of Global Functions

`t3AllocProp t3DebugTrace t3GetGlobalSymbols t3GetNamedArg t3GetNamedArgList t3GetStackTrace t3GetVMBanner t3GetVMID t3GetVMPreinitMode t3GetVMVsn t3RunGC t3SetSay`

Summary of Macros

`T3DebugBreak T3DebugCheck T3DebugLog T3GetStackDesc T3GetStackLocals T3GlobalSymbols T3MacroHasArgs T3MacroHasVarargs T3PreprocMacros T3SetSayNoFunc T3SetSayNoMethod`

Summary of Enums

(none)

Summary of Templates

(none)

Global Functions

`t3AllocProp ( )` | `t3.h[146]`

Allocate a new property. Returns a new property not yet used anywhere in the program. Note that property ID's are a somewhat limited resource - only approximately 65,000 total are available, including all of the properties that the program defines statically.

`t3DebugTrace (mode, ...)` | `t3.h[99]`

Debugger trace operations. This provides access to the interactive debugger subsystem, if the VM is running under a debugger. The 'mode' argument determines what the function does and what the additional arguments, if any, are for:

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.

`t3GetGlobalSymbols (which?)` | `t3.h[137]`

Get the global symbol table or the global macro table.

'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.

`t3GetNamedArg (name, defval?)` | `t3.h[181]`

Get a named argument. This searches for the specified named argument, and returns the value of the argument if it's defined.

'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.

`t3GetNamedArgList ( )` | `t3.h[188]`

Get a list of all named arguments currently in effect. This returns a list of strings, where each string is the name of a named argument that's currently active.

`t3GetStackTrace (level?, flags?)` | `t3.h[166]`

Get a stack trace. This returns a list of T3StackInfo objects. Each object represents a nesting level in the call stack. The first element in the list represents the currently active level (i.e., the level that called this function), the second element represents the caller of the first element, and so on.

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).

`t3GetVMBanner ( )` | `t3.h[64]`

Get the VM banner string. This returns a string with the name of the VM, the version number, and a copyright string, in a format suitable for displaying to the user to identify the VM executable.

`t3GetVMID ( )` | `t3.h[57]`

Get the VM identifier string. This returns the version number as a string, as in '3.0.10'.

`t3GetVMPreinitMode ( )` | `t3.h[71]`

Get the preinitialization mode flag. This returns true if the VM is running as part of the compiler's pre-initialization phase, nil if it's running as a normal interpreter.

`t3GetVMVsn ( )` | `t3.h[51]`

Get the VM version number. Returns the version number as an integer value, with the major version in the high-order 16 bits, the minor version number in the next 8 bits, and the patch number ("point release" number) in the low-order 8 bits. For example, version 3.0.10 is encoded as 0x0003000A.

`t3RunGC ( )` | `t3.h[28]`

Explicitly run garbage collection.

`t3SetSay (val)` | `t3.h[42]`

Set the default output function or method. The return value is the old function pointer or method, depending on which one is being set with this call. (If 'val' is a function pointer, the return value will be the old function; if 'val' is a property ID, the return value is the old method.)

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.

Macros

`T3DebugBreak` | `t3.h[200]`

`2`
break into the debugger

`T3DebugCheck` | `t3.h[197]`

`1`
check to see if the debugger is present

`T3DebugLog` | `t3.h[203]`

`3`
log a message to the system/debug log

`T3GetStackDesc` | `t3.h[226]`

`0x0002`
no description available

`T3GetStackLocals` | `t3.h[225]`

`0x0001`
t3GetStackTrace flags. These can be combined with the bitwise '|' operator.

`T3GlobalSymbols` | `t3.h[218]`

`1`
t3GetGlobalSymbols 'which' flag. One of these values can be specified as the function argument to specify which type of table is to be retrieved.

`T3MacroHasArgs` | `t3.h[231]`

`0x0001`
Macro information flags.

`T3MacroHasVarargs` | `t3.h[232]`

`0x0002`
no description available

`T3PreprocMacros` | `t3.h[219]`

`2`
no description available

`T3SetSayNoFunc` | `t3.h[210]`

`1`
t3SetSay() special values. These can be passed in lieu of a function pointer or property ID when the caller wants to remove any existing function or method rather than install a new one.

`T3SetSayNoMethod` | `t3.h[211]`

`2`
no description available

Enums

(none)

Templates

(none)

TADS 3 Library Manual
Generated on 5/16/2013 from TADS version 3.1.3