Skip to main content

Step-by-step/realtime terminal debugger. It tell you what is happening on your terminal.

Project description

What is This?

trachet = tracer + ratchet(step-by-step debugging service)

This Program runs as a terminal filter process, between Terminals and Applications. It provides step-by-step debugging and formatted sequence tracing service. You can look terminal I/O sequence on realtime, and it enables you to do step-by-step execution.

http://saitoha.github.io/trachet/

https://raw.githubusercontent.com/saitoha/trachet/data/data/trachet1.png

Install

via github

$ git clone --recursive https://github.com/saitoha/trachet.git
$ cd trachet
$ python setup.py install

or via pip

$ pip install trachet

Usage

$ trachet [options] command
  • Options:

    -h, --help                  show this help message and exit
    -o OUTPUT, --output=OUTPUT  specify output device or file
    -b, --break                 "break" the program at the startup time
    -m, --monochrome            don't use color in output terminal"
    --version                   show version
  • Sequense Tracing

    If you specified TTY device by -o option, you can look I/O sequence tracing on realtime.

  • Step by Step debugging

  • <F6> Toggle trace state ON/OFF.

  • <F7> Toggle break state ON/OFF.

  • <F8> Step to next char or control sequence.

  • <F9> Step to next ESC or CSI sequence.

QuickStart

  • STEP1

    First, You need to prepare two terminal windows, debugged terminal and output terminal.

    https://raw.githubusercontent.com/saitoha/trachet/data/data/trachet_qs1.png
  • STEP2

    At the output terminal, type “tty” command.

    $ tty
    /dev/ttys002

    Now you get output terminal’s TTY device name(=/dev/ttys002).

    https://raw.githubusercontent.com/saitoha/trachet/data/data/trachet_qs2.png
  • STEP3

    At the debugged terminal, launch trachet.

    https://raw.githubusercontent.com/saitoha/trachet/data/data/trachet_qs3.png

    Run default shell and send formatted I/O sequences to output terminal

    $ trachet -o/dev/ttys002

    Run default shell and write non-colored formatted I/O sequences to a text file.

    $ trachet -o log.txt

    Run vim and send formatted I/O sequences to output terminal.

    $ trachet -o/dev/ttys002 vim

    Run emacs and send formatted I/O sequences to output terminal, and “break” emacs on startup time

    $ trachet -b -o/dev/ttys002 emacs -nw

    Replay output log created by script(1) step by step.

    $ trachet -b -o/dev/ttys002 cat ~/typescript -

How It Works

  • PTY and Normal Terminal/Application:

    +---------------------------------------------+
    |                  Terminal                   |
    +---------+-----------------------------------+
              |
    +---------|-----------------------------------+
    |  +------+-------+        +---------------+  |
    |  |    Master    |========|     Slave     |  |
    |  +--------------+        +-------+-------+  |
    +----------------------------------|----------+
                                       |
    +----------------------------------+----------+
    |                Application                  |
    +---------------------------------------------+
  • TFF (Terminal Filter Framework):

                        Scanner                    Event Driven Parser         Event Dispatcher
                        +-----+                         +-----+                     +-----+
      << I/O Stream >>  |     | << CodePoint Stream >>  |     | << Event Stream >>  |     |      << I/O Stream >>
    ------------------->|     |------------------------>|     |-------------------->|     |---||-------------------->
      (Raw Sequences)   |     |    (Unicode Points)     |     |   (Function Call)   |     |       (Raw Sequences)
                        +-----+                         +-----+                     +--+--+
                                                   ISO-2022 ISO-6429                   |
                                                   Compatible Parsing                  |
                                                                                       v
                                                                                    +-----+
                                                                     Event Observer |     |      << I/O Stream >>
                                                                      (I/O Handler) |     |---||-------------------->
                                                                                    |     |       (Raw Sequences)
                                                                                    +-----+
  • With Trachet…

    +----------------------------------------------------------+   +------------------------+
    |                                                          |   |                        |
    |                        Terminal                          |   |  Other Device or File  |
    |                                                          |   |                        |
    +----------------------------------------------------------+   +------------------------+
                         |                       ^                              ^
                         |                       |                              |
                     < input >               < output >                         |
                         |                       |                              |
                         |      +----------------+                              |
                         |      |                      [ PTY 1 ]                |
                  +------|------|-------------------------------+               |
                  |      v      |                               |               |
                  |  +----------+---+       +----------------+  |               |
                  |  |    Master    |=======|      Slave     |  |               |
                  |  +--------------+       +--+-------------+  |               |
                  |                            |        ^       |               |
                  +----------------------------|--------|-------+               |
                                               |        |                       |
                                           < input >    |                       |
                                               |        |                   < trace >
                               +---------------+    < output >                  |
                               |                        |                       |
       [ Trachet Process ]     |                        |                       |
    +--------------------------|------------------------|---------------+       |
    |                          |                        |               |       |
    |              +-----------|-------<< TFF >>--------|------------+  |       |
    |              |           v                        |            |  |       |
    |  < control > |  +-----------------+     +---------+---------+  |  |       |
    |       +----->|  |  InputHandler   |     |   OutputHandler   |  |  |       |
    |       |      |  +--+-----+----+---+     +--+----------------+  |  |       |
    |       |      |     |     |    |            |      ^            |  |       |
    |       |      +-----|-----|----|------------|------|------------+  |       |
    |       |            |     |    |            |      |               |       |
    |       |            |     |    |            |      |               |       |
    |       |            v     |    v            v      |               |       |
    |  +----+---------------+  |  +----------------+    |               |       |
    |  |  ActionController  |  |  |     Tracer     |----------------------------+
    |  +--------------------+  |  +----------------+    |               |
    |                          |                        |               |
    +--------------------------|------------------------|---------------+
                               |                        |
                           < input >                < output >
                               |                        |
                               |       +----------------+
                               |       |
                               |       | [ PTY 2 ]
                       +-------|-------|-----------------------------+
                       |       v       |                             |
                       |  +------------+--+       +---------------+  |
                       |  |    Master     |=======|     Slave     |  |
                       |  +---------------+       +----+----------+  |
                       |                               |      ^      |
                       +-------------------------------|------|------+
                                                       |      |
                                  +--------------------+      |
                                  |                           |
                              < input >                   < output >
                                  |                           |
                                  v                           |
    +---------------------------------------------------------+-----------------------------+
    |                                                                                       |
    |                                  Target Application                                   |
    |                                                                                       |
    +---------------------------------------------------------------------------------------+

Dependency

Reference

License

GNU GENERAL PUBLIC LICENSE Version 3

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

trachet-1.0.9.tar.gz (69.1 kB view hashes)

Uploaded source

Built Distributions

trachet-1.0.9-py2.7.egg (144.4 kB view hashes)

Uploaded 2 7

trachet-1.0.9-py2.6.egg (144.4 kB view hashes)

Uploaded 2 6

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page