lstinson / tagmadebug Goto Github PK

NAME
    TagmaDebug - Interactive TCL Debugger

SYNOPSIS
    tagmadebug.tcl [Options] [--] YourScript.tcl

OPTIONS
    -c        Connect to a TagmaDebug control server.

    -H HOST   Connect to HOST instead of localhost.

    -h        Display this text.

    -P PORT   Connect to PORT instead of 5444.

DESCRIPTION
    TagmaDebug is a simple interactive debugger for TCL programs.

    When TagmaDebug starts it creates a trace on "__TagmaDebugMain." This
    procedure sources the script provided on the command line. The trace on
    this procedure basically causes a break on every command. Once the
    script completes the procedure "__TagmaDebugComplete" is called. There
    is a hidden enter trace on this procedure to ensure the user gets the
    debugger prompt one last time.

    The unknown command is replaced and the original called. If the original
    unknown throws an error it is caught. The error message is displayed and
    the debugger is entered. The debugger will not step into unknown.

    All output from the debugger is written to stderr. This allows for
    redirection of the program or debugger output if desired.

PROMPT
    The prompt is composed of flags in curly brackets '{}', the level of
    execution, the procedure (if one is executing) and the name of the
    debugger.

    The flags indicate when certain features are enabled. 'B' indicates the
    body of procedures will be displayed. If disabled only the procedure
    name and arguments are printed. 'E' indicates enter will continue a
    step, the same as typing 'c Enter'. 'P' indicates packages will be
    stepped into. 'V' indicates verbose mode is enabled. This will cause
    additional output in certain places.

    Sample prompt: {E}(1 => foo)Tagma>

    This prompt indicates Enter will continue a step and execution is one
    level deep in the procedure "foo".

COMMANDS
    There are several interactive commands that control the debugger. There
    is no line editing and very little nicety.

    !           Executes a shell command.

    =           Prints the content of each variable name provided.

    a or >      Prints the command being executed.

    c or Enter  Continue execution.

    e or [..]   Evaluates TCL code. When using [..] The closing ']' is
                required.

    h or ?      Prints the help text.

    f or ff     Prints the stack frame. ff prints also prints the line and
                file, when available.

                Prints the Frame #, Level # (as in info level), Procedure
                name and command. The command is truncated if it is multiple
                lines.

    var log     Logs all modifications of a variable to stderr.

    var break   Adds breakpoint for writes to a variable.

    var info    Prints all variables being watched for.

    var clear   Clears logging and breaks for variables. Passes the variable
                to [string match ...] so globbing can be used.

    cmd enter   Set a break point for the entering of a command.

    cmd leave   Set a break point for the leaving of a command.

    cmd step    Steps through the command. Every command that is executed
                inside the command is a breakpoint.

    cmd clear   Clear break points. Passes the command to [string match ...]
                so globbing can be used.

    con         Connect to a TagmaDebug control server. Optional Host and
                port. (Default: localhost and 5444)

    p           Prints the current level & procedure. When at the top level
                '::' is printed for the procedure.

    r           Restarts the program.

    x or q      Exit the debugger. Ctrl-D should also have the same effect.

SETTINGS
    Settings to control TagmaDebug. These are reflected by the flags inside
    {} in the prompt. The flags and settings use the same letter.

    B       Toggle printing the body of procedures when they are defined.

    E       Toggle Enter acting as a shortcut to 'c Enter'.

    P       Toggle stepping into package.

    V       oggle verbosity. Print extra info, when available.

CONTROL SERVER
    NOTE: The shell does not work under Tkcon.

    The program server.tcl starts a TCP server. Tagma Debug can connect to
    this server for remote control. All debugger output and user input is
    sent to comes from the server. The server requires an event loop process
    to function. By default if the program is run it starts the server
    process, enters the remote debug shell and starts an event loop. The
    shell is designed to make debugging similar to using TagmaDebug
    directly.

    The 'tagma' command is used to control the server and interact with the
    debugger. With no options it sends its arguments to the remote debugger.

    tagma Options:

    -help     Print help for the tagma command.

    -select   Select from connected debuggers. Lists the available and
              current connections with no arguments.

    -shell    Enter an interactive shell. Simulates working directly with
              the debugger. If there is no active connection it will wait
              for a client to connect. The server must be running before the
              shell is started.

    -start    Start the Tagma server process. (Optional port)

    -verbose  Control verbose mode. (on/off) Displays the current state with
              no arguments.

    --        End option processing.

PORTABILITY
    TagmaDebug should work with any TCL version 8.4 or later. Testing has
    thus far been limited to Tcl 8.5 under Cygwin on Windows 7.

INSTALLATION
    Either copy tagmadebug.tcl where you want it or run "make install".

HOME
    <https://github.com/LStinson/TagmaDebug>

    <http://wiki.tcl.tk/28695>

COPYRIGHT
    This script is derived from "TclDebugger by S.Arnold. v0.1 2007-09-09" -
    <http://wiki.tcl.tk/19872>. What ever copyright he says his code is
    under is what applies to this one. Since it was listed publicly with no
    restrictions I am assuming it is free to modify.

AUTHOR
    Written by Lorance Stinson AT Gmail....