getbytecode

Bytecode disassemby command, introduced in Tcl 8.6.3, intended to produce machine-readable disassembly of Tcl's bytecode. The machine-readable format is a dict.

: tcl::unsupported::getbytecode proc procName
: tcl::unsupported::getbytecode lambda lambdaTerm
: tcl::unsupported::getbytecode script script
: tcl::unsupported::getbytecode method class method
: tcl::unsupported::getbytecode objmethod object method

The different arguments control how the command looks up the bytecode to take apart.

WARNING!
The output format of this command, beyond being a dictionary, is not defined.
Future releases of Tcl may change it at any time.

Description of output

Main dictionary

In 8.6.3, the following keys are in the dict:

literals: list of literal values
variables: list of descriptions of variables in the local variable table. Each variable is a pair, where the first element is a collection of flags (e.g., arg for “argument to procedure”, scalar for “simple non-array variable”, temp for “a temporary variable without name”), and the second is the name of the variable (omitted for temporaries).
exception: list of dicts describing the exception ranges.
instructions: dict of instructions, indexed by address (which is monotonically increasing, but not contiguous; bytecodes are not all the same). Each instruction is described by a list where the first element is the opcode and the subsequent elements are the arguments.
auxiliary: list of auxiliary metadata for instructions, used to store additional information for foreach, switch (in jump-table form), and dict update. Each entry in the auxiliary metadata is represented by a dict where name maps to a description of what sort of metadata it is, and other elements are defined by the type.
commands: list of dicts describing the commands found in the script that caused the bytecode to be generated.
script: The whole Tcl script that was parsed to generate the bytecode.
namespace: The namespace that the script is bound to. (Note that TclOO methods mutate this.)
stackdepth: The depth of value stack required to evaluate the bytecode.
exceptdepth: The depth of exception handler stack required to evaluate the bytecode.
initiallinenumber: The line number of the first line of the procedure body (typically the line of the proc call — or equivalent — and typically blank) within the file described by **sourcefile**. Not available for procedures with dynamically-generated bodies.
sourcefile: The name of the file that the proc — or equivalent — was sourced from, just as can be found with info frame when the procedure is executing. Not available for procedures with dynamically-generated bodies.

Variable meaning flags

scalar: This variable holds a single value.
array: This variable is an array.
link: This variable is a link (e.g., local variable bound for global, variable or upvar).
arg: This variable is an argument to the procedure or method.
temp: This variable is an unnamed temporary.
resolved: This variable is controlled by a variable resolver.

Exception dictionary entries

type: Type of exception range being described: loop or catch.
level: How deep in the stack of exception ranges is this one?
from: Instruction address at which this range starts.
to: Instruction address at which this range ends.
break: Location to jump to on TCL_BREAK. Only present for loop exception ranges.
catch: Location to jump to on any exception (including both TCL_BREAK and TCL_CONTINUE). Only present for catch exception ranges.
continue: Location to jump to on TCL_CONTINUE. Only present for loop exception ranges.

Argument meaning flags

Arguments may be:

an immediate integer (may be an index into the exception table if the instruction is beginCatch4),
a @ followed by an integer index into the literals list,
a % followed by an index into the variables list,
a . followed by an immediate list index (may be end-relative),
a = followed by an index into the table of string is classes,
a ? followed by an index into the auxiliary list, or
pc followed by an address (for jump-like instructions).

Auxiliary metadata types

The first pair in the dictionary defines the name key, which describes the meaning of the other elements

ForeachInfo

Old-style foreach information. Should not normally be seen.

data: List of variables used to store lists being iterated over.
loop: Loop counter variable.
assign: List of lists of indices of variables to be assigned each step around the loop.

NewForeachInfo

jumpOffset: Offset of the start of the foreach loop (instruction after foreach_start) relative to the end of the foreach loop (foreach_step).
assign: List of lists of indices of variables to be assigned each step around the loop.

DictUpdateInfo

variables: List of indices into the variables list of variables to be written (matching order for arguments to dict update).

JumptableInfo

mapping: Dictionary mapping the value to match to the jump offset to use (i.e., relative to the jumptable instruction).

Command dictionary entries

codefrom: The index into the instructions of the start of the command.
codeto: The index into the instructions of the end of the command.
scriptfrom: The index into the script of the start of the command.
scriptto: The index into the script of the end of the command.
script: The section of script defining the command, as a string.