Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/tomzox/trowser

Trowser is a browser for large line-oriented text files, implemented in 3 alternate programming languages: Tcl/Tk, Python and C++/Qt
https://github.com/tomzox/trowser

color-highlighter cpp14 graphical-user-interface less python qt5-gui tcl tcl-tk text-browser text-search tkinter-gui vim

Last synced: 8 months ago
JSON representation

Trowser is a browser for large line-oriented text files, implemented in 3 alternate programming languages: Tcl/Tk, Python and C++/Qt

Awesome Lists containing this project

README 

          
# Trowser



Trowser is a browser for large line-oriented text files with color highlighting

and a highly flexible search and cherry-picking window.  Trowser was developed

as an alternative to tools such as "less" (UNIX) or "Notepad++" (Windows)

when analyzing debug log/trace files

created by other applications. Trowser integrates well with

[GtestGui test-runner](http://github.com/tomzox/gtest_gui) as viewer for

text output of test applications using GoogleTest (GTest) framework.



Compared to plain text viewers, trowser adds color highlighting, a persistent

search history, graphical bookmarking and a separate search result window. The

search window is especially designed to be main facility for performing trace

analysis: Using multiple consecutive searches, manual additions or removals,

undo/redo and subtractive searches, it can be filled with a condensed view of

the trace file, holding only the lines relevant to the issue under analysis.



Trowser has a graphical interface, but is designed to allow browsing via the

keyboard at least to the same extent as less. Key bindings and the cursor

positioning concept are derived mainly from vim.



Note: In this context "line-oriented" denotes that each line of text is

considered a data unit.  Color highlighting (including search matches)

will always apply the highlight to the complete text line.



Due to historical evolution, implementations of trowser are available in three

different programming languages: [Tcl/Tk](http://tcl.tk/),

[Python](https://www.python.org/), and C++ using [Qt5](https://www.qt.io/).

The three versions are largely equivalent, however the C++/Qt version has best

performance, looks prettier and has a new "column configuration" dialog for the

search list, thus it's recommended to use this version. Currently you'd have to

compile it yourself from the sources in the [src_qt/](src_qt/) sub-directory of

the repository. If you're not up to this, use one of the other versions which

don't need compilation (due to using interpreted languages).



## Screenshots



screenshot main window screenshot highlighting editor dialog screenshot search/filter list window screenshot custom column configuration dialog screenshot bookmarks list dialog screenshot search history dialog screenshot loading from pipe



The screenshots, taken from the C++/Qt implementation, show some of the main features

(click the images to see larger versions):



    

  • The first screenshot shows the main window with a text which has color

    highlighting applied and an ongoing incremental search initiated via the

    "Find" toolbar at the bottom of the window.
    


    • 

  • The second screenshot shows the highlight pattern editor dialog (holding

    the patterns used for the previous screenshot) at the top, and the mark-up

    editor sub-dialog at the bottom (which opens when double-clicking on any

    "sample text" in the list).
    


    • 

  • The third screenshot shows the search result list, populated by "search

    all" in the main window, or via the search highlight and history dialogues, or

    by manually inserting selected lines from the main window. In the example

    screenshot, two lines are bookmarked and thus shown with a leading blue dot. The

    "Date" column is filled with content parsed from the document based on the

    configuration shown in the next screenshot.
    


    • 

  • The fourth screenshot shows the "custom column configuration dialog", which

    allows adding columns to the search list: In this example, it is used to extract

    the sending date from an email for each line of the email that appears in the

    search list. The "Test" dialog shown at the bottom of the image allows debugging

    the column configuration by showing results when running it on a selected line.
    


    • 

  • The fifth screenshot shows the bookmark list, which are lines that are

    individually marked by the user and appear in special mark-up in the main

    window and search list.
    


    • 

  • The sixth screenshot shows the search history dialog (i.e. a list of

    previously used search patterns) which can be used to quickly repeat one or

    more previous searches.
    


    • 

  • The last screenshot shows the pipe load dialog which pops up when loading

    text from standard input. This is used mainly for monitoring progress while

    piping output from another application directly into trowser.

    • 




## Documentation



For a detailed description of features please refer to the [manual page](doc/trowser.pod)



## Rationale



trowser was developed for sifting through debug output files written

by software under development. Such debug files can get very large;

in the extreme, there could be a line of trace written for every

entered function (e.g. documenting the call and actual parameters)

and one more line every time a function is left. When debugging

complex exceptions, it's often necessary to analyze several hundreds

or thousands of lines of debug trace to understand the cause.



Such analysis usually start by first looking at top-level events

(e.g. stimuli by the environment) and then digging down into the details.

trowser was developed to facilitate this process. Of course one could

also use standard tools such as "grep" or "awk" and "less" or "vim" to tackle

this task, but this way lots of repetitive manual hacking on the command

line is required. For an every-day task, it seems worth to invest some

time into automating the process in a specialized tool.



Additionally, trowser has the capability to automatically parse data out

of the trace file which can be included in custom columns of the search

results list. This can be used for example in traces for event-driven

applications to show a common timestamp or ID for each trace line

generated while processing the same event. If the pre-existing custom

configuration doesn't allow your use-case, it is fairly straight-forward

extending it by adding a new sub-class in `src_qt/parse_frame.cc`



With less than 9k lines of Tcl/Tk code, or 16k lines C++ respectively,

trowser still is a relatively small application (in large part thanks to

the powerful "text" widgets both Tk and Qt) so there's only a low barrier

of getting familiar with the source code to allow extending or adapting

the functionality for your own needs.



## Installing C++ version



The C++ version is only tested on Linux so far. Pre-requisite for building the

C++ version is installing Qt5 developer packages (qtbase5-dev, qttools5-dev,

qt5-default). On some platforms, you may additionally need package

`libqt5serialport5-dev`.



To build the C++ version, change into sub-directory `src_qt`, then run

`qmake` and then `make`. If all works well, an executable `build/trowser`

is generated as a result. You can copy this executable file anywhere you want

or just run it directly.



Usage: Name the file to open on the command line, or "-" to read from a pipe.



First steps when running trowser for the first time usually is selection of an

appropriate font and configuring expressions for syntax highlighting under menu

"Search / Edit highlight patterns". Then adjust the window and dialog sizes and

locations. trowser will remember these settings in its configuration file

stored in `$HOME/.config/trowser/`.



## Installing Tcl/Tk & Python versions



The Python variant is available as a package on

[PyPi](https://pypi.org/project/trowser/)



Software Requirements: trowser can be used on all platforms which are supported

by either the Tcl/Tk or Python interpreters. This means all UNIX variants,

Linux, Mac, and even MS Windows. On the other hand, this means a prerequisite

is installing either [Tcl/Tk](http://tcl.tk/) (version 8.5 or later) or

[Python](https://www.python.org/). The latter can be done semi-automatically

when creating packages using the scripts described below.



trowser can be used without installation, if you copy the script simply in

the same directory as the files you want to open with it. Note trowser

expects to be given the name of the file you want to open on the command line.



The Python version is best installed using `pip3 install trowser`. This will

automatically download the latest release of the package from pypi.org (plus

dependency "appdirs" on the Win32 platform) and install them.



Alternatively, or if you want to install the latest code found here on GitHub,

Python and Tcl/Tk versions can be installed as a system package if you're using

a Debian, Ubuntu or a compatible Linux distribution: You can create a Debian

package for using script `create_deb.sh` for Tcl/Tk, or using script

`create_deb_py.sh` for Python respectively. The scripts will copy the required

files into a local sub-directory `deb` and then create a package which can be

installed using the generated package file. Example:



```console

    bash create_deb.sh

    dpkg -i deb/trowser_1.3-3_all.deb

```



The software is released under the

[GNU General Public License, version 3](http://www.fsf.org/copyleft/gpl.html)



## Troubleshooting (Tcl/Tk version)



If trowser fails to start or aborts with an interpreter error, you should

check if Tcl/Tk is installed and has the required version by entering the

following command line in a terminal window (i.e. in a shell):



```console

    echo 'puts $tcl_patchLevel;exit' | wish

```

In some Tcl/Tk installations "wish" as such may not exist, but instead the

major and minor version are appended to the executable name (e.g."wish8.5".)

In this case, change the third line in the trowser.tcl script file accordingly.



Current version of trowser is tested against Tcl/Tk version 8.6, but it should

also still work with predecessor Tcl/Tk versions 8.5 and 8.4. If the above

command returns an even older version, you'll have to upgrade your Tcl/Tk

library for using trowser. In Python, you can determine the version of

underlying Tcl/Tk simply by running `python -m tkinter`.