tabdata/README.md

   1 # Tabular Data management tools
   2
   3 Tabular Data program suit (Tabdata) is a set of CLI tools (`td-*`) to
   4 manipulate line-based data stream (text).
   5 Each line represent a data **row**, also known as **record**,
   6 which consists of some **cells**,
   7 which are just strings separated by TAB (`0x09`, `\t`) char.
   8 This way each **cell** holds the **value** of a **field**.
   9 **Field** is a bit abstract part of Tabdata,
  10 it refers to either to a **cell** in a given column position determined by field name - when speaking of it in the context of a row,
  11 or to a whole **column** when speaking about the whole data stream.
  12 So **fields** make up the **columns** labelled by the field's name in the first **row**.
  13 Which makes the first row effectively the **header**.
  14
  15 You guessed, newline and tab (`\n`, `\t`) chars can not be in the cells
  16 as raw data, but need to encode/escape somehow.
  17 See "Escaping" section below.
  18
  19 Objective of Tabdata is to provide user-friendly
  20 (guru/admin/terminal-warrior/poweruser-friendly) means to do everyday data processing
  21 tasks, complementing (not superseding) well-established toolsets:
  22 use Tabdata in combination with coreutils, moreutils, util-linux, ...
  23 tools.
  24
  25 Focus is on text as being primarily for humans, not machines.
  26 That's why control chars are not considered meaningful data.
  27 You still can encode/decode your data stream before/after piping into
  28 Tabdata tools, to process arbitrary bytestream as well.
  29
  30 # Escaping
  31
  32 Escaping rules in Tabdata:
  33
  34  | Raw char  | Tabdata escape sequence |
  35  |-----------|-------------------------|
  36  | ESC       | Backslash + "e"         |
  37  | TAB       | Backslash + "t"         |
  38  | LF        | Backslash + "n"         |
  39  | CR        | Backslash + "r"         |
  40  | Backslash | Backslash + Backslash   |
  41
  42 ## Q. Why not use ESC control code (0x1B) instead of Backslash?
  43
  44 Tabdata tools are intended to write output to file, pipes, and terminals alike.
  45 The ESC code is avoided because it's handled specially by terminals,
  46 whereas Backslash is not.
  47
  48 ## Q. Why not escape the other control characters?
  49
  50 Feel yourself rather lucky that even these chars are escaped.
  51 It would be better if you pre-filter or transform your input data
  52 before passing it forward to Tabdata tools.
  53 Tabdata does not do it for you, to prevent unneccessary computing
  54 in cases where the user knows that the input data is good to go through as-is.
  55
  56 # Tool Descriptions
  57
  58 See short description of each commands of this toolkit in [descriptions.txt](descriptions.txt).
  59 For detailed documentation of them, run `make manpages` or read the POD in the files themselves.
  60 See [index.md](index.md) for all man pages in markdown format in a single file.
  61
  62 # Compare to CSV
  63
  64 Tabdata is very similar to CSV, except it has well-defined field- and record separators
  65 and a well-defined encoding schema.
  66
  67 # Similar tools/projects
  68
  69 - GNU [datamash](https://www.gnu.org/software/datamash/) git://git.sv.gnu.org/datamash.git
  70 - [vnlog](https://github.com/dkogan/vnlog)
  71 - [tsv-utils](https://github.com/eBay/tsv-utils-dlang)
  72 - [csvkit](https://github.com/wireservice/csvkit)
  73 - [q](https://github.com/harelba/q) Run SQL directly on delimited files...
  74 - [sqawk](https://github.com/dbohdan/sqawk)
  75
  76 # Accessory tools
  77
  78 - [tabularize](../user-tools/tabularize) - to display results nicely on terminal