console-flat-table-viewer 1 user commands nosh console-flat-table-viewer TUI viewer for flat file tables of several kinds 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 --inversescreen boolean --tui-level level filename(s) 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. The table data are read from the command's standard input, or from the list of files denoted by filename(s). The output is suitable for display on a terminal that is configured to treat its received character stream as UTF-8. 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 unvis3. 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.passwd5, the old obsolete /etc/inittab5, and /etc/pf.os5. 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 unvis3. 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/fstab5 (as well as /etc/services5, /etc/crontab5, /etc/phones5, /etc/ttys5, /etc/hosts5, /etc/protocols5, and /proc/mounts for some other examples). This is the default format. Some of the aforementioned can be better treated as the tabbed format if the administrator has been strict about only using TAB characters. 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 unvis3 (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 unvis3 (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 unvis3 (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 vis3 format, where every octet of the UTF-8 encoding is further encoded into the 7-bit always-graphic subset guaranteed by vis3; partly encoded, where only some of the UTF-8 octets are further encoded by vis3; or not further encoded and occupying the full 8-bit character range of UTF-8. All three will end up as the same decoded 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, alongside vis encoded text (an encoded space that is not a field separator), both in straight UTF-8 and further encoded in vis form: ITEM PRICE Cola\040bottle \M-B\M-#\0401.50 Cherry\040tomatoes £\0407.50 Both will display as the £ character. 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. 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 TERM7 environment variable, it does not use terminfo3 or termcap3. It instead uses TerminalCapabilities3. 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 vi1, 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 --header-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. Direct RGB colours can be specified by # followed by the RGB value in hexadecimal, such as #00B0E815. Indexed colours can be specified by their index numbers, such as 188. Hexadecimal and octal numbers are permitted in indexes, so care must be taken with leading zeroes. 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 column headings to otherwise headerless data is a straightforward exercise in the use of printf1: $ ( printf '%s\t' line getty type state comment ; printf '\n' ; cat /etc/ttys ) | > console-flat-table-viewer --header-count 1 --format tabbed $ ( printf '%s\t' device on type options dumpfrequency fsckpassnumber ; printf '\n' ; cat /etc/fstab ) | > console-flat-table-viewer --header-count 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 has two uses. First, it allows one to retain visibility of displayed information after the program has exited (although setterm1 provides access to the alternative screen buffer). Second, it 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. The --inversescreen command-line option instructs console-flat-table-viewer to switch the DECSCNM ("light"/"dark" screen mode) private mode on or off. The --tui-level command-line option constrains the use of MouseText or Unicode block graphics and line drawing characters in TUI widgets; currently none. 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_ctl2, whereas one can pass the file descriptors of regular files to kevent2 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 cat1 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. Jonathan de Boyne Pollard