Name

console-flat-table-viewer — TUI viewer for flat file tables of several kinds

Synopsis

console-flat-table-viewer [--format format] [--header-colour colour] [--body-colour colour] [--header-count number] [--cursor-keypad-application-mode] [--calculator-keypad-application-mode] [--no-alternate-screen-buffer]

Description

console-flat-table-viewer is a simple TUI viewer for several common kinds of flat file tables. A flat file database contains no indexes; does not have a relational, hierarchical, or networked structure; and contains exactly one table in one file. Its only access method is sequential.

Table formats

This tool deals in flat file tables whose records are variable length, with fields and records separated from one another by specific characters. The particular kind of table is selectable via format:

ascii

Original ASCII style using the original ASCII characters.

Fields are separated by US (U+001F), records by RS (U+001E). GS (U+001D) is treated as a record separator. FS (U+001C) clears the table and starts afresh.

There are no comments, and field data are not decoded by unvis(3).

Empty fields are allowed; multiple consecutive field separators denoting a series of empty fields. Empty records are also allowed; multiple consecutive record separators denoting a series of empty records.

colon

UNIX colon-separated format, as used by many files such as /etc/master.passwd(5), the old obsolete /etc/inittab(5), and /etc/pf.os(5).

Fields are separated by colon, records by LF (U+000A). There are no file or group separators, and all other characters are field data. Field data are not decoded by unvis(3).

A # where a field would begin is a line-comment that extends to the end of the record. The capability for these files to have comments comes from the BSD C library. The GNU C library generally does not support comments in these tables.

Empty records are not allowed; blank records and records comprising solely a comment being discarded and discounted. But empty fields are allowed; multiple consecutive field separators denoting a series of empty fields.

space

UNIX whitespace-separated format, as used by many files such as /etc/fstab(5) (as well as /etc/services, /etc/crontab, /etc/phones, /etc/ttys, /etc/hosts, /etc/protocols, and /proc/mounts for some other examples). This is the default format.

Fields are separated by TAB (U+0009) or SPC (U+0020), records by LF (U+000A). FF (U+000C) clears the table and starts afresh. There are no group separators, and all other characters are field data. This includes, in particular, CR (U+000D) which is not a separator character.

Field data are decoded with unvis(3) (or an equivalent on non-BSD operating systems), per the BSD convention for such files. A # where a field would begin is a line-comment that extends to the end of the record.

Empty fields are not allowed and are simply discarded and discounted. Empty records are similarly not allowed; blank records and records comprising solely a comment being discarded and discounted.

tabbed

Strict TAB-separated format.

Fields are separated by TAB (U+0009) alone, records by LF (U+000A). FF (U+000C) clears the table and starts afresh. There are no group separators, and all other characters are field data. This includes, in particular, CR (U+000D) and SPC (U+0020) which are not separator characters.

Field data are decoded with unvis(3) (or an equivalent on non-BSD operating systems). A # where a field would begin is a line-comment that extends to the end of the record.

Empty records are not allowed; blank records and records comprising solely a comment being discarded and discounted. But empty fields are allowed; multiple consecutive field separators denoting a series of empty fields.

The table data are read from the command's standard input, and the display is updated progressively as the input is read. The existence of file separators in several of these formats thus permits a "live" form of display, where a command (that generates output data in these forms) can run indefinitely with its output piped to console-flat-table-viewer, generating file separators at the beginning of every table-ful. A file separator causes console-flat-table-viewer to clear all table data so far and start afresh.

Field data, after any decoding with unvis(3) (or an equivalent on non-BSD operating systems), are treated as UTF-8 encoded characters for display purposes. Control characters in the C0 and C1 ranges are converted to blanks, but otherwise characters are treated as-is, with overlong encodings normalized and erroneous encodings discarded.

Potentially a UTF-8 encoding can be in three forms: completely encoded in vis(3) format, where every octet of the UTF-8 encoding is further encoded; partly encoded, where only some of the UTF-8 octets are further encoded; or not further encoded. All three will end up as the same encoded Unicode code point. This is by design, as people do sometimes create an admixture of the first and third forms when they edit table files. The second form is a consequence of allowing such an admixture; albeit one that is difficult to create with UTF-8 tools, because it requires writing invalid octet sequences that are not UTF-8.

For example, this shows U+00A3 both in straight UTF-8 alongside vis encoded text (an encoded space that is not a field separator) and itself further encoded in vis form:

ITEM    PRICE
Cola\040bottle     \M-B\M-#\0401.50
Cherry\040tomatoes £\0407.50

A part vis encoding is hard to show here. It would have \M-B and followed by octet 0xA3 . Or octet 0xC2 followed by \M-# . Neither can be properly rendered in a manual document.

User interface

console-flat-table-viewer is not a text file viewer. It displays the decoded contents of tables as tables, with the fields and records presented in a rectangular grid. Comments are discarded. Decoded and normalized characters are output in UTF-8 form.

It opens its controlling terminal via /dev/tty and uses that for its user interface, both input and output. If its standard input is also its controlling terminal, odd behaviour may result, determined by how the operating system kernel decides to route input. (This is not a sensible usage of the program; so simply do not do this.)

Although its behaviour is controlled by the TERM(7) environment variable, it does not use terminfo(3) or termcap(3). It instead uses TerminalCapabilities(3). The terminal type determines a few terminal capabilities (such as whether the terminal can actually handle DEC private mode control sequences at all, and its degree of ISO 8613-6/ITU T.416 support), but most processing adheres to the ECMA-48 and ISO 8613-6 de jure standard control sequences and the DEC VT, DTTerm, and AIXTerm de facto standard ones.

The user interface responds to actual arrow keys, HJKL navigation in the style of vi(1), and WASD navigation. (The command only knows about characters and escape/control sequences coming from the terminal. Thus the latter two are not particularly ergonomic on several countries' standard keyboard layouts.) Various common control characters with conventional special meanings may be used to quit, although the simplest way of quitting is simply q.

Colours may be changed with the --heading-colour and --body-colour command-line options. The 16 standard colours can be specified by RGBCMYK names such as bright red , white , and yellow . Colour 7 is white or bright grey . Colour 8 is grey or bright black . Indexed colours can be specified by their index numbers, such as 188 . Note that hexadecimal and octal numbers are permitted, so care must be taken with leading zeroes. Direct RGB colours can be specified by # followed by the RGB value in hexadecimal, such as #00B0E815 .

Column sizes are automatically chosen to encompass the widest field in that column from any record. They may be manually resized with the + and - keys.

The --header-count command-line option specifies that the first number records should be considered to be column headings. Header rows are displayed in a fixed position on the screen and are unaffected by vertical scrolling. (Adding a row of headings to otherwise headerless data is a straightforward exercise in the use of printf(1).)

Fields are displayed right-justified if they are not in header rows and contain only digits. Otherwise they are displayed left-justified.

The --cursor-keypad-application-mode and --calculator-keypad-application-mode command-line options instruct console-flat-table-viewer to switch, respectively, the cursor keypad and the calculator keypad of the realizing terminal into their "application" modes. Otherwise it switches them into their "normal" modes. "application" mode is generally not useful to console-flat-table-viewer, since it makes cursor and calculator keys indistinguishable from accelerator keys. The --no-alternate-screen-buffer command-line option instructs console-flat-table-viewer to not switch to the alternative screen buffer. This works around problems with some (yet more!) broken terminal emulators that attempt to be and fail at being like XTerm, which forcibly change cursor and editing keys into application mode when the alternative screen buffer is active.

Compatibility

The user interface is event driven, reacting to control input and data input as they occur. On Linux, regular files are not pollable with epoll_ctl(2), whereas one can pass the file descriptors of regular files to kevent(2) on the BSDs. So on Linux in order to make its standard input something that is pollable, console-flat-table-viewer spawns a sub-process running cat(1) reading from the original standard input and writing into a pipe, when it finds that its standard input was not a character device, socket, or pipe.

Author

Jonathan de Boyne Pollard