xsv.1.txt

   1 XSV(1)
   2 ======
   3 :man source: XSV
   4 :man version: {xsvversion}
   5 :man manual: The Swiss-Army Knife for CSV
   6
   7 NAME
   8 ----
   9 xsv - manipulate CSV-like text files
  10
  11 SYNOPSIS
  12 --------
  13 *xsv* 'input-format' ['output-format'] 'options' ['fields']
  14
  15 DESCRIPTION
  16 -----------
  17 *xsv* is a utility for manipulating text files, whose lines are divided into fields.
  18 This includes popular formats for textual databases like CSV (Comma-Separated Values),
  19 TSV (Tab-Separated Values), formats with other separators (like `/etc/passwd`), and
  20 many other formats.
  21
  22 *xsv* reads lines from the standard input. Each line is split into fields
  23 according to a specified file format. The fields are then written to the
  24 standard output in a possibly different format. Additionally, the fields can
  25 be re-ordered, trimmed, and otherwise manipulated.
  26
  27 FORMATS
  28 -------
  29 If a single file format is selected, it is used for both the input and the output.
  30 If two file formats are given, the former applies to the input, the latter to the
  31 output. If no format is given, *--tsv* is assumed.
  32
  33 *-t, --tsv*::
  34         Tab-separated values, or more generally fields separated by a single
  35         occurrence of a delimiter character. By default, the delimiter is the TAB
  36         character, but it can be changed by the *-d* option.
  37 *-c, --csv*::
  38         Comma-separated values -- the traditional CSV format as defined in RFC 4180.
  39         Fields are separated by a single comma. When a field contains a comma, it is
  40         enclosed in double quotes. When it contains double quotes, they are repeated.
  41         The only deviations from the RFC are that we do not put a CR at the end of a line
  42         (although we accept it on the input) and that each line can have a different
  43         number of fields.
  44 *-w, --ws*::
  45         The fields are separated by arbitrary sequence of whitespace characters
  46         (spaces, tabs and form-feeds). Leading or trailing whitespace is interpreted
  47         as an empty field (this can be overridden by *--sloppy*). When used for output,
  48         exactly one space is used.
  49 *-r, --regex=*'regex'::
  50         The fields are separated by sequences of characters satisfying the given
  51         Perl-compatible regular expression (see *pcrepattern*(3) for a full description
  52         of their syntax). For example, `--regex='#+'` separates fields by an arbitrary
  53         number of hashes. Leading or trailing separators are interpreted as empty
  54         fields (this can be overridden by *--sloppy*). This format can be used only
  55         for input.
  56 *--table*::
  57         An output-only format, which displays the data in form of a table. Data in each
  58         column are justified to the width of the longest item. With *--grid*, an ASCII-art
  59         grid is added. Please note that this requires two passes over the data,
  60         so pre-formatted data are stored in a temporary file.
  61
  62 FORMAT PARAMETERS
  63 -----------------
  64 Each format option can be followed by parameters specific to that format:
  65
  66 *-d, --fs=*'character'::
  67         Use the specified character as a field separator (delimiter).
  68         Applies to *--csv* and *--tsv*.
  69 *-f, --fields=*'name'*,*'name'*,*...::
  70         Assign names to fields. The names can be then used to refer to fields
  71         instead of numbers.
  72 *-h, --header*::
  73         The file starts with a header line, which contains field names.
  74         It can be combined with *--fields*, if you want to override the names.
  75 *-q, --quiet*::
  76         By default, *xsv* prints warnings when something suspicious happens
  77         (e.g., an unterminated quote in CSV, or when we attempt to print a field,
  78         which contains the separator character). If the warnings are too noisy,
  79         use *--quiet* to silence them.
  80 *--always-quote*::
  81         When writing CSV files, quote all fields, even if it is not needed.
  82 *--table-sep=*'n'::
  83         Separate table columns by 'n' spaces. When not given, two spaces are used.
  84         Applies to *--table* only.
  85 *--grid*::
  86         Decorate the table by an ASCII-art grid of vertical lines. The lines sit
  87         in the middle of inter-column spaces.
  88         Applies to *--table* only.
  89 *-s, --sloppy*::
  90         Ignore separators at the beginning or at the end of a line. Otherwise,
  91         they are interpreted as empty fields.
  92         Applies to *--ws* and *--regex*.
  93
  94 OTHER OPTIONS
  95 -------------
  96 There are several options, which do not apply to the file format. Instead, they
  97 specify how the data should be transformed between the input and the output.
  98
  99 *--trim*::
 100         Delete leading and trailing spaces in each field.
 101 *--equalize*::
 102         When different lines contain a different number of fields, pad the short
 103         ones with empty fields. Please note that this requires two passes over the
 104         data, possibly storing the data to a temporary file in between.
 105
 106 SELECTION OF FIELDS
 107 -------------------
 108 By default, *xsv* copies all fields from the input to the output. Instead of that,
 109 you can specify a list of fields or field ranges to copy. Unlike *cut*(1), the fields
 110 are copied in the given order.
 111
 112 A field can be identified by its number (starting with 1), or by its name when
 113 *--fields* or *--header* is given. A field range has the form 'field'-'field';
 114 either 'field' can be omitted, which refers to the first/last field of the line.
 115
 116 EXAMPLES
 117 --------
 118 `xsv </etc/passwd -d: 3 1` prints the UID and the login name of each user.
 119
 120 `xsv </etc/passwd -d: --tsv 3 1` prints the same, but separated by a tabulator.
 121
 122 `xsv </etc/passwd -d: -flogin,passwd,uid,gid,full --tsv uid login` does the same
 123 using column names.
 124
 125 `xsv --csv --table --grid` formats a given CSV file as a nice table.
 126
 127 CAVEATS
 128 -------
 129 In most cases, *xsv* does not assume anything about the character set -- the files
 130 are treated as sequences of bytes. The only exception is formatting of tables, which
 131 needs to account for on-screen space. In this case, the character set specified by
 132 the system locale is assumed. However, all characters are considered of the same
 133 width, including potential combining Unicode characters.
 134
 135 LICENSE
 136 -------
 137 *xsv* was written by Martin Mares <mj@ucw.cz>.
 138 It can be distributed and used under the terms of the GNU
 139 General Public License version 2.