Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Tell you what is happening on your terminal
Python Makefile
Failed to load latest commit information.
test Add some tests
tools Strip trailing spaces
trachet Bump version
.gitignore +
.gitmodules Handle SS2/SS3 events
COPYING First commit
COPYING.tff Add COPYING for TFF
ChangeLog Update ChangeLog
MANIFEST.in Update MANIFEST file
Makefile Update seqdb
README.rst Update README
TODO Update TODO
requirements.txt Style fix
setup.py Strip trailing spaces

README.rst

trachet

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
Something went wrong with that request. Please try again.