trowser.pod

NAME

trowser - Browser for line-oriented text files with color highlighting

SYNOPSIS

trowser [{-t|-h} limit] [-r path] [file|-]

trowser -help

DESCRIPTION

Trowser is a graphical 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 files (or "trace files", as they are often called in embedded software world - hence the name).

Trowser has a graphical interface, but is designed to allow browsing via the keyboard at least to the same extent as less. Additional key bindings and the cursor positioning concept are derived from the Vim text editor.

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 a complete line of text.

When you start trowser for the first time, you'll have to create highlight patterns for your type of file. To do this, first enter a search pattern and verify that it matches the intended lines. Then open the Edit highlight patterns dialog in the Search menu, press the right mouse button to open the context menu and select Add current search. You can change the highlight color or select a different kind of mark-up by double-clicking on the new entry in the dialog, or by selecting Edit markup in the context menu. To define new colors, click on Edit color palette at the bottom of the markup editor dialog.

There are several ways to quickly navigate in the file to lines matching search patterns: Firstly, you can search forwards or backwards to any sub-string or pattern you enter in the Find: field. Secondly, you can repeat previous searches by opening the search history dialog and double-clicking on an entry, or by clicking Next or Previous. Third, you can assign bookmarks to selected text lines and jump in-between those lines by clicking on them in the bookmark list dialog or via '+ and '- key bindings (not in vim.) Fourth, you can search for patterns defined in the color highlight list by selecting a pattern in the list and then clicking on Next or Previous in the pattern list dialog. Fifth, you can open the Search result list (via the Search menu or by clicking on List all in any dialog or by entering ALT-a) to display all text lines which match a set of patterns and click on an entry in this list to jump to the respective line in the main window. Sixth, you can manually copy arbitrary lines from the main text window into the search result window via the 'i' key (not in vim.)

The search filter list is one of the main features of the trace browser, as it allows to consecutively build an arbitrary sub-set of text lines in the main window. You can not only use one or more search patterns to add text, but also add selected text lines from the main text window via the i key binding and remove individual lines again, either manually or by use of a search pattern. Additionally you can use bookmarks in the search result window. When searching in the main window, the search result list will scroll to show the same region of text. Thus you effectively can navigate the text on three levels: Bookmarks > Search list > Main text.

Both the bookmark and search result lists support prefixing all entries with a "frame number". This is useful when your input file does not have time-stamp prefixes on each line. In this case trowser can search for a preceding time-stamp and automatically prefix bookmarked lines with this number. Additionally trowser allows to fetch a "frame number" which is not printed in the same line as the frame interval start line. In this case trowser searches the next frame start lines in forward and backward direction and then inside of that range for a line containing the frame number value. Note for the search result list this feature is disabled by default for performance reasons. It must be enabled in the dialog's Options menu. The search patterns used to locate time-stamps currently have to be inserted into the RC file manually.

For performance reasons most search-related commands are executed as background processes, so that the GUI remains responsive during search. For example, this applies to the initial color highlighting, global search highlighting, incremental search while editing search patterns and filling the search result list. Such background activity is indicated by display of a progress bar and switching the mouse cursor to a watch or hourglass image. You still can use trowser as usual during this time though. The background activity is automatically aborted or restarted when a conflicting command is entered (e.g. when the search pattern is modified during global search highlighting.)

KEY BINDINGS

Generally, keyboard focus can be moved between control elements (e.g. buttons, check-boxes and text containers) using the TAB or Shift-TAB. The widget with the keyboard focus is marked by a black border. After start-up, keyboard focus is in the main text window. Functions which are bound to mouse clicks on buttons etc. can be activated via the keyboard using the Space bar. Many functions can also be activated via shortcuts: Press the ALT key plus the character which is underlines in the button description (e.g. Press ALT-c to open the Control menu, or ALT-a to simulate a mouse-click on the All button at the bottom of the main window.)

In the following descriptions, ^X means Control-X, i.e. holding the Control key pressed while pressing the X key. ALT refers to the key to the left of the Space bar. Enclosing quotes must be typed.

Key Bindings in the Main Window

The commands in this section can be used when the keyboard focus is in the main window.

Commands to move the cursor or change the view:

Up, Down, Left, Right

Move the cursor in the respective direction. When the cursor hits the end of the visible area (i.e. the view), the text is scrolled vertically by a line or horizontally by a character (same as in vim, except for the smoother horizontal scrolling)

Control-Up, Control-Down, Control-Left, Control-Right

Scroll the view by a line or character in the respective direction (not in vim - unless you have added "map <C-Down> ^E" etc. in .vimrc)

h, l, k, j

Move the cursor left, right, up or down (same as in vim)

Return, +, -

Move the cursor to the start of the following or preceding line (to be exact: the first non-blank character) (same as in vim)

Space, BackSpace

Move the cursor to the next or preceding character (same as in vim)

Home, End, 0, $, ^

Move the cursor to the first or last character of the current line (same as in vim)

Control-Home, Control-End, G, gg

Move the cursor to the start or end of the file (same as in vim) Note an equivalent alternative to gg is 1g.

H, M, L

Move the cursor to the start of the line at the top, middle or bottom of the view (same as in vim)

w, e, b, W, E, B, ge, gE

Move the cursor to the start or end of the next or preceding word (same as in vim)

^e, ^y, ^d, ^u, ^f, ^b

Scroll the screen by a single line, half a screen or a full screen forwards or backwards (same as in vim)

zReturn, z., z-

Adjusts the view vertically so that the current line is at the top, middle or bottom of the screen and places the cursor on the first non-blank character (same as in vim) The horizontal view is set to start at the left border.

zt, zz, zb

Adjusts the view so that the current line is at the top, middle or bottom of the screen; the cursor position is unchanged (same as in vim)

zl, zh, zL, zH

Move the view horizontally to the left or right (same as in vim)

zs, ze

Scroll the view horizontally so that the current cursor column is placed at the left or the right side of the screen (as far as possible); in any case the cursor position remains unchanged (same as in vim)

f, F

Search for the following character in the same line to the right or left respectively (same as in vim)

;, , (semicolon, comma)

Repeat a previous in-line search (f or F) in the same or opposite direction respectively (same as in vim)

'' (two apostrophes)

Moves the cursor to the position before the latest jump (same as in vim and less.) A "jump" is one of the following commands: ', G, /, ?, n, N, L, M and H (same as in vim.) Note movements controlled via the GUI, such as the bookmark list or search result list, do not modify the jump list.

'+, '-

Moves the cursor to the next or previous bookmark (not in vim)

'^, '$

Moves the cursor to the start or end of file (same as in less; not in vim)

^o, ^i

Moves the cursor to the next older (or newer respectively) position in the jump list (same as in vim; note TAB which is identical to ^i in vim has a different meaning here.) See '' for a list of commands which are considered jumps and add pre-jump cursor positions to the list.

1, 2, ... 9

A number without leading zeroes can be used to repeat the subsequent key command or place the cursor on a given line or column (same as in vim)

For example: 1G places the cursor in the first line of the file; 10| places the cursor in the tenth column of the current line (line and column numbering starts at 1.) Note the number cannot start with zero, as 0 is treated specially (immediately moves the cursor into the first column, same as in vim.)

Searching and repeating:

/, ?

Search for the following pattern (same as in vim.) Similar to vim, the keyboard focus is moved from the main text into a small text entry field (command line in vim) Note the previous search pattern is always cleared when re-entering the entry field, but all previously used patterns are still available in the history which can be accessed with the cursor up/down keys like in vim. Note in addition, you can use ^d in the search field to copy the text under the cursor in the main window into the search field, word by word.

As soon as a search expression is typed into the field, an incremental search is started and matching lines are highlighted. The cursor in the main text isn't actually moved there until the search is completed by pressing Return. The search can be aborted by ^C or Escape. For more details see "Key Bindings in the Search Entry Field"" in "KEY BINDINGS.

n, N

Repeats the previous search in forward or backwards direction respectively (similar to vim - however in contrary to vim n always searches forward and N always backwards because the standard vim behavior of remembering and reversing the search direction with N is very confusing.)

*, #

Searches for the word under the cursor in forward or backwards direction respectively (same as in vim) Note when regular expression search mode is not enabled, this command performs a plain sub-string text search. Else, word boundary matches are placed around the search text, as done by vim.

&

Remove the highlighting of previous search matches (not in vim as such, but can be added via map & :nohlsearch^M in .vimrc) Note this does not disable highlighting in subsequent searches.

ALT- f

Moves the focus in the search search entry field. This is equivalent to / or ? but without changing the search direction (not in vim) This is equivalent to clicking into the "Find:" entry field with the mouse button.

ALT- n, ALT- p

Repeat a previous search, equivalent to n and N (not in vim)

ALT- h

Enable the "Highlight all" option, i.e. highlight all lines in the text where the current search pattern matches (not in vim)

ALT- a

Open the search result window and fill it with all text lines which match the current search pattern (not in vim)

ALT- N, ALT- P

Open the search result window and fill it with all text lines below or above the current cursor position respectively which match the current search pattern (not in vim)

The following commands can be used to change the selection.

Note that selected text is automatically exported and can be pasted into other applications.

Shift-Left, Shift-Right, Shift-Up, Shift-Down

Starts or extends the selection in the respective direction (not in vim) Note that trowser only supports the character-wise selection mode (like v in vim)

Shift-Home, Shift-End

Starts or extends the selection from the current cursor position to the start or end of the current line (not in vim)

Control-Shift-Home, Control-Shift-End

Starts or extends the selection from the current cursor position to the start or end of the file (not in vim)

^c

Copies the currently selected text to the clipboard. (Note that this command is actually superfluous as the text is copied as soon as some text is selected.)

Misc. commands (none of these are in vim):

m

This key, or double-clicking into a text line, toggles a bookmark in the respective line (different from vim; note setting named bookmarks is not supported.) Additionally the view of the search result list, if open, will be centered around the line (even if the marked line is not included in the search results.)

i

Insert (i.e. copy) the text line holding the cursor into the search result window. If a selection exists and is currently visible, the selected lines are copied instead. (Note the restriction to visibility of the selection exists to avoid confusion about i not working on the current text line.)

u, ^r

Undo or redo respectively the last addition or removal of text lines in the search list done by i or "Search All" (different from vim.)

ALT- +, ALT- -

Increases or decreases the font size for the text content. Note the behavior when reaching the maximum or minimum font size is undefined.

ALT- w

Toggle line-wrap for text in the main window (i.e. text lines which are longer than the window width will wrap into the next line.)

Key Bindings in the Search Entry Field

The following commands can be used when the keyboard focus is in the search entry field at the bottom of the main window:

Return

Store the current pattern in the search history and return focus to the main window with the cursor on the next match (same as vim) Note the cursor is already moved via incremental search when entering the text (including the highlighting of adjacent matches) so the search and cursor movement need not be done again here. This command is equivalent to leaving the search field by clicking with the mouse outside or switching keyboard focus via TAB or Shift-TAB.

Escape, ^c

Abort the current search, i.e. return focus to the main window and place the cursor on the previous position. The search pattern in the entry field is still pushed onto the history (same as in vim.)

^a, ^e

Move the insertion cursor to the start or end of the search text entry field (^e is same as in vim; ^a is not in vim.) Note: movement and selection via cursor keys works in the same way as described for the main text.

^n, ^N

Jump to the next or previous match respectively for the current pattern using incremental search. Note these commands do not affect the fall-back cursor position, i.e. when the search is aborted or the pattern is changed, the cursor returns to the original start position (not in vim)

Up, Down

Copies the previous or next pattern in the search history into the entry field. If the entry field already contains some text, the search is restricted to patterns with the same prefix.

^d, ^D

Complete the search text with the text to the right or left of the current match in the main text (i.e. right or left of the text marked with green background color.)

^x

Remove the currently used pattern in the search history, if the current pattern was copied by use of Up or Down (not in vim)

ALT- n, ALT- p

Same as pressing the Next or Previous buttons respectively, i.e. search for the current pattern in forward or backwards direction and add the pattern to the search history. Keyboard focus remains in the search entry field.

ALT- a

Open the search result window and fill it with all text lines which match the current search pattern (not in vim) Additionally, keyboard focus is moved back into the main window.

ALT- N, ALT- P

Open the search result window and fill it with all text lines below or above the current cursor position respectively which match the current search pattern (not in vim) Additionally, the keyboard focus is moved back into the main window.

ALT- c

Toggle the "match case" option, i.e. equivalent to clicking on Match case (not in vim)

ALT- e

Toggle the regular expression search option, i.e. equivalent to clicking on button Reg.Exp. (not in vim.) When this option is enabled, special characters are parsed according to re_syntax Tcl manual page; the syntax is almost identical to Perl with few exceptions (notably \m and \M to match beginning and end of words) When the option is not enabled, no characters have a special meaning (i.e. even "*") and a simple sub-string search is started.

Note: for performance reasons it's recommended to use case-sensitive sub-string searches for color highlighting, especially if you have many patterns. This is usually faster than combining multiple patterns with | in a regular expression.

Key Bindings in the Search Result Window

The following commands can be used in the search result window (i.e. the list filled by "Search All" and lines copied from the main window via the i key binding.)

For users who prefer controls via the mouse it should be noted that there's a context menu which opens via a click with the right mouse button into a line, which has equivalent commands to the ones listed below.

m

Bookmark the currently selected line. The line will be marked both in the search result window and the main window.

Delete

Remove the selected lines from the search result list.

u

Undo the last addition or removal.

^r

Redo the last addition or removal (if previously undone.)

/, ?

Moves the keyboard focus in the search entry field in the main window for entering a search expression. The behavior of the search is the same as in the main window. When leaving the search entry field via Return or Escape, the keyboard focus returns to the search list.

n, N

Repeat the last search in downwards or upwards direction respectively. The search is restricted to lines in the search result window.

Escape

Abort an ongoing search. Lines which were already found and added to the search result window will remain. (You can still remove these lines using "undo".)

&

Same as in the main window: Remove the highlighting of previous search matches (same as :nohlsearch in vim) and of lines highlighted in the main window by positioning via selections in the search result list.

In addition to the above, the general selection dialog key bindings in the next section also work in the search result window.

Key Bindings in Dialogs

The following commands can be used to manipulate the selection cursor in all dialogs which display lists (i.e. search result list, search history, bookmarks, highlight pattern editor) Note there's no distinction between selection and cursor in these dialogs. This means you cannot move the selection cursor from line A to D using the keyboard without temporarily selecting lines B and C in-between.

Of course you can also manipulate the selection via the mouse in the usual ways, i.e. clicking on single entries, or dragging the mouse to select multiple elements, or pressing the mouse while holding Control or Shift keys pressed to add or remove single elements or extend the selection respectively.

Up, Down

Move the selection cursor one line up or down respectively, scrolling the view if necessary. If no line is selected yet, the cursor is placed on the first or last line; if the previously selected line is still in the visible area, the cursor is placed there instead.

Home, End

Move the selection cursor on the first or last item in the list.

Shift-Up, Shift-Down, Shift-Home, Shift-End

Extend or reduce the selection in the given direction, or to the start or end of the list.

Page-Up, Page-Down

Scroll the view up or down by a page. These commands remove the selection cursor.

OPTIONS

The following command line options are available:

-h limit, --head=limit

This option specifies the maximum number of bytes to load from input file or stream for display. When loading from a stream via STDIN, it's possible to continue reading more data later via command Continue loading STDIN.

The limit value is remembered in the configuration file and used as default the next time data is loaded from STDIN. When loading from a file, default is to load the complete file.

When neither option -h or -t are specified and data is loaded from a stream via STDIN, a small dialog window pops up when the buffer limit is exceeded. This allows the user to select between head and tail modes manually.

-t limit, --tail=limit

This option specifies to load only the given maximum number of bytes into the display from the end of the file or input stream. This means when reading from a file, data from the beginning is skipped if the file is larger than the limit. If the input is a STDIN stream, data is read into a ring buffer of the given size. Once the end-of-stream is reached, the last content of the ring buffer is loaded into the display.

The limit value is remembered in the configuration file equivalently as described for the "head" option.

-r path, --rcfile=path

This option can be used to specify an alternate configuration file. When this option is not present, the configuration file is stored in system directories, see "FILES".

ENVIRONMENT

trowser only evaluates the standard variables DISPLAY (X11 display address) and HOME (home directory, for storing the configuration file.)

FILES

$HOME/.config/trowser/trowser.py.rc

UNIX: Configuration file where all personal settings and the search history are stored. The path may be overriden via environment variable XDG_CONFIG_HOME. A different file name can be specified with the --rcfile option (see "OPTIONS").

During updates to this file, trowser temporarily creates a new file the same directory, where "XXXXX" is a random number. The old file is then replaced with this new file. This procedure will obviously fail if the target directory (not the file itself!) is not writable.

MS Windows: On the MS Windows platform, the configuration file is created in the hidden application data directory in your user home. The specific path depends on your operating system version. (The path is qeried via a system API.)

CAVEATS

Currently only one pattern list for color highlighting is supported. Hence different highlighting for different file types can only be done by choosing different configuration files when starting trowser (see the --rcfile option.)

Vim compatibility: Not all vim navigation commands are implemented; Command repetition is supported only for a small sub-set of commands; Some commands behave slightly differently from vim (most notably the bookmark related commands.) vim's range and selection commands are not supported at all.

Search repetition by pressing "Next" or "Previous" or the search history dialog is currently not interruptable and may take quite a while if the next match is several MB away. (This can be avoided by repeating the search via the entry field's internal search history, i.e. / and Up)

Searching with regular expressions is very slow in large files. This is unfortunately a property of the "text" Tk widget. Thus use of regular expressions for highlighting is not recommended. (As a work-around, trowser automatically falls back to plain string search if there are no control characters in the search expression.)

Some GUI activity (e.g. selecting a range on text with the mouse) will render active background tasks uninteruptable, i.e. the GUI will become unresponsive until the background task has completed.

File store and load dialogs do not maintain a history of previously used files or directories. (This is so because it's expected that these features will not be used very often.)

The pipe load and search result list dialogs are not designed very well yet (i.e. even more so than the other dialogs). Suggestions for improvements are welcome.

Some configuration options cannot be modified via the GUI and require manually editing the configuration file.

SEE ALSO

vim(1), less(1), head(1), tail(1), egrep(1), wish(1), tclsh(1), re_syntax(3tcl), perlre(1)

AUTHOR

Written by T. Zoerner mailto:tomzo@users.sourceforge.net

COPYRIGHT

Copyright 2007-2009,2019-2020,2023 T. Zoerner. All rights reserved.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.