Guile-DSV

Guile-DSV is a GNU Guile module for working with the delimiter-separated values (DSV) data format.

Guile-DSV supports the Unix-style DSV format and RFC 4180 format.

Also Guile-DSV ships with a program named dsv (source code is here: utils/dsv.in) that allows to read and process DSV format (including delimiter change and conversion from one standard to another.)

Note that if you want to use Guile-DSV from an environment where syslog is unavailable, then you must set the log-driver option for dsv->scm to “file” or “none” to prevent it from trying to log messages to the syslog. See the Texinfo documentation for details.

Requirements

• GNU Guile 2.0.12+
• Guile Library 0.1.9+
• Guile-SMC 0.6.2+

Build dependencies

• Texinfo (contains makeinfo tool that is required for making the documentation in Texinfo format)
• Texlive (also is needed for documentation.)
• help2man

Installation

GNU Guix

$ guix install guile-dsv

Manual

$ git clone https://github.com/artyom-poptsov/guile-dsv.git
$ cd guile-dsv
$ autoreconf -vif
$ ./configure --prefix=/usr
$ make -j$(nproc)
$ sudo make install

For a basic explanation of the installation of the package, see the INSTALL file.

Please note that you will need Automake 1.12 or later to run self-tests with make check (but the library itself can be built with older Automake version such as 1.11).

important You probably want to call configure with the --with-guilesitedir option so that this package is installed in Guile’s default path. But, if you don’t know where your Guile site directory is, run configure without the option, and it will give you a suggestion.

dsv CLI tool

Guile-DSV includes a command-line interface (CLI) tool named dsv which allows to use Guile-DSV facilities in console.

Options

The default behavior of dsv program is to print a formatted table from a <file> to stdout. The options listed below can be used to change or modify this behavior.

--help, -h

Print the help message and exit.

--summary, -s

Print summary information for a file.

--delimiter, -D <delim>

Set a delimiter.

--guess-delimiter, -d

Guess a file delimiter and print the result.

--number, -n

Number rows and columns.

--width, -w <width>

Wrap long lines of text inside cells to fit the table into the specified width. If with is specified as “auto” (default value) then current terminal width is used. When the required width is too small for the table wrapping, an error will be issued. Zero width means no wrapping so the table might not fit into the screen.

--map-cell, -m <code>

Apply an arbitrary Scheme code on each cell value before printing. There are three variables that can be used in the code:

• $value – current cell value.
• $row – current row number.
• $col – current column number.

Code examples:

--map-cell '(if (> $value 0) $value 0)'
--map-cell '(string-append "\"" $value "\"")'

Note that the code must return a string, that in turn will be printed in a cell.

--filter-row, -f <code>

Keep only rows for which CODE returns #t.

There are two variables that can be used in the code:

• $value – current row content.
• $row – current row number.

For example with this code Guile-DSV keeps only rows that are 5 columns in length:

--filter-row '(= (length $value) 5)'

--filter-column, -c <procedure>

Keep only columns for which PROCEDURE returns #t. There are two variables that can be used in the code:

• $value – current column content as a list.
• $row – current column number.

For example with this code Guile-DSV keeps only the 2nd column from the input data:

--filter-column '(= $col 2)'

--file-format, -F <fmt>

Set a file format. Possible formats are: “unix” (default), “rfc4180”

--with-header, -H

Use the first row of a table as a header when printing the table to the screen.

--table-borders, -b <spec>

Set table borders for printing. The value can be either a borders specification or a preset name.

Spec can be a comma-separated list of key=value pairs that specify the table style. The list of possible keys can be found below (see “Table parameters”.)

Also a table preset name can be used as the value. See “Tables” section below.

Table preset parameters can be overridden by specifying extra parameters after the preset name. E.g.:

--table-borders "graphic,bs=3;31"

More examples:

--table-borders "v=|,h=-,j=+"
--table-borders org

--table-presets-path <path>

Set the table preset path. This option can be also set by GUILE_DSV_TABLE_PRESETS_PATH environment variable. See “Tables” section below.

The default value depends on the Guile-DSV installation path.

--to, -t <fmt>

Convert a file to a specified format, write the result to stdout.

--to-delimiter, -T <delim>

Convert delimiters to the specified variant. When this option is not used, default delimiters for the chosen output format will be used.

--version

Print information about Guile-DSV version.

--debug

Enable the state machine debugging.

Tables

Table parameters

Short name	Long name	Description
bt	border-top	The top border.
btl	border-top-left	The top left corner.
btr	border-top-right	The top right corner.
btj	border-top-joint	The top border joint.
bl	border-left	The left table border.
blj	border-left-joint	The left table border joint.
br	border-right	The right table border.
brj	border-right-joint	The right table border joint.
bb	border-bottom	The bottom border.
bbl	border-bottom-left	The left corner of the bottom border.
bbr	border-bottom-right	The right corner of the bottom border.
bbj	border-bottom-joint	The bottom border joint.
bs	border-style	The style of the borders (“fg;bg”.)
ts	text-style	The text style (“fg;bg”.)
s	shadow	The table shadow.
so	shadow-offset	The table shadow offset in format “x;y” (e.g. “2;2”.)
ss	shadow-style	The style of the shadow (“fg;bg”.)
rs	row-separator	The table row separator.
rj	row-joint	The row joint.
cs	column-separator	The table column separator.
hs	header-style	The header style (“fg;bg”.)
ht	header-top	The header top border.
htl	header-top-left	The header top left border.
htr	header-top-right	The header top right border.
htj	header-top-joint	The header top joint.
hl	header-left	The header left border.
hr	header-right	The header right border.
hcs	header-column-separator	The header column separator.
hb	header-bottom	The header bottom border.
hbl	header-bottom-left	The header bottom left corner.
hbr	header-bottom-right	The header bottom right border.
hbj	header-bottom-joint	The header bottom joint.

Table presets

• ascii
• graphic-bold
• graphic-double
• graphic
• graphic-with-shadow
• markdown
• org

Common use cases

Printing DSV files

To show DSV files (Unix-style) in human-readable manner, just invoke the tool like this:

$ head -4 /etc/passwd | dsv
 root    x  0  0  root    /root      /bin/bash         
 daemon  x  1  1  daemon  /usr/sbin  /usr/sbin/nologin 
 bin     x  2  2  bin     /bin       /usr/sbin/nologin 
 sys     x  3  3  sys     /dev       /usr/sbin/nologin

Show a DSV file as a fancy table with custom borders:

$ head -4 /etc/passwd | dsv -b "rs=-,cs=|,rj=+"
 root   | x | 0 | 0 | root   | /root     | /bin/bash         
--------+---+---+---+--------+-----------+-------------------
 daemon | x | 1 | 1 | daemon | /usr/sbin | /usr/sbin/nologin 
--------+---+---+---+--------+-----------+-------------------
 bin    | x | 2 | 2 | bin    | /bin      | /usr/sbin/nologin 
--------+---+---+---+--------+-----------+-------------------
 sys    | x | 3 | 3 | sys    | /dev      | /usr/sbin/nologin

The same output but with box-drawing characters:

$ head -4 /etc/passwd | dsv -b "rs=─,cs=│,rj=┼"
 root   │ x │ 0 │ 0 │ root   │ /root     │ /bin/bash         
────────┼───┼───┼───┼────────┼───────────┼───────────────────
 daemon │ x │ 1 │ 1 │ daemon │ /usr/sbin │ /usr/sbin/nologin 
────────┼───┼───┼───┼────────┼───────────┼───────────────────
 bin    │ x │ 2 │ 2 │ bin    │ /bin      │ /usr/sbin/nologin 
────────┼───┼───┼───┼────────┼───────────┼───────────────────
 sys    │ x │ 3 │ 3 │ sys    │ /dev      │ /usr/sbin/nologin

Printing tables

There are table presets that can be used to draw tables with specified border styles. Some examples:

ascii

$ echo -e "a,b,c\na1,b1,c1\na2,b2,c2\n" | dsv -b "ascii"
.--------------.
| a  | b  | c  |
|----+----+----|
| a1 | b1 | c1 |
|----+----+----|
| a2 | b2 | c2 |
'--------------'

$ echo -e "a,b,c\na1,b1,c1\na2,b2,c2\n" | dsv -b "ascii" --with-header
.--------------.
| a  | b  | c  |
|====+====+====|
| a1 | b1 | c1 |
|----+----+----|
| a2 | b2 | c2 |
'--------------'

graphic

$ echo -e "a,b,c\na1,b1,c1\na2,b2,c2\n" | dsv -b "graphic"
┌────┬────┬────┐
│ a  │ b  │ c  │
├────┼────┼────┤
│ a1 │ b1 │ c1 │
├────┼────┼────┤
│ a2 │ b2 │ c2 │
└────┴────┴────┘
$ echo -e "a,b,c\na1,b1,c1\na2,b2,c2\n" | dsv -b "graphic-bold"
┏━━━━┳━━━━┳━━━━┓
┃ a  ┃ b  ┃ c  ┃
┣━━━━╋━━━━╋━━━━┫
┃ a1 ┃ b1 ┃ c1 ┃
┣━━━━╋━━━━╋━━━━┫
┃ a2 ┃ b2 ┃ c2 ┃
┗━━━━┻━━━━┻━━━━┛
$ echo -e "a,b,c\na1,b1,c1\na2,b2,c2\n" | dsv -b "graphic-double"
╔════╦════╦════╗
║ a  ║ b  ║ c  ║
╠════╬════╬════╣
║ a1 ║ b1 ║ c1 ║
╠════╬════╬════╣
║ a2 ║ b2 ║ c2 ║
╚════╩════╩════╝

org

This is the preset that allows to generate org-mode tables from CSV/DSV data.

$ echo -e "a,b,c\na1,b1,c1\na2,b2,c2\n" | dsv -b "org"
| a  | b  | c  |
| a1 | b1 | c1 |
| a2 | b2 | c2 |
$ echo -e "a,b,c\na1,b1,c1\na2,b2,c2\n" | dsv -b "org" --with-header
| a  | b  | c  |
|----+----+----|
| a1 | b1 | c1 |
| a2 | b2 | c2 |

Guessing the delimiter for a file

$ dsv -d /etc/passwd
:

Getting the summary for a CSV/DSV file

$ dsv -s /etc/passwd
File:      /etc/passwd
Format:    unix
Delimiter: ':' (0x3a)
Records:   50

column       width       
1            19          
2            1           
3            5           
4            5           
5            34          
6            26          
7            17

Converting files between formats

From Unix DSV to RFC4180:

$ dsv -t rfc4180 /etc/passwd | head -4
root,x,0,0,root,/root,/bin/bash
daemon,x,1,1,daemon,/usr/sbin,/usr/sbin/nologin
bin,x,2,2,bin,/bin,/usr/sbin/nologin
sys,x,3,3,sys,/dev,/usr/sbin/nologin

Convert delimiters:

$ dsv -t unix -T "|" /etc/passwd | head -4
root|x|0|0|root|/root|/bin/bash
daemon|x|1|1|daemon|/usr/sbin|/usr/sbin/nologin
bin|x|2|2|bin|/bin|/usr/sbin/nologin
sys|x|3|3|sys|/dev|/usr/sbin/nologin

Apply an arbitrary Scheme code to each cell of a table

Wrap each table value in double quotes:

dsv -m '(string-append "\"" $value "\"")' /etc/group

Table filtering

Remove 2nd row from a table:

$ dsv -f '(not (= $row 1))' /etc/passwd

Remove 2nd column from a table:

$ dsv -f '(not (= $col 1))' /etc/passwd