Explicitly write out inference rule for .c.o
[tabular.git] / README.md
blob9140a116aeba90dfeb19afc07895199a41a30cac
1 # tabular
2 The **tabular** utility reads files containing tabular data sequentially and pretty prints them as a table.
3 The file operands are processed in command-line order. If the file is a single dash (‘-’) or absent, **tabular**
4 reads from the standard input. The separator character(s) of each column in the data set can be specified at run-time,
5 which defaults to `','`.
7 ## Features
8 * Quality
9     * Compiled with security hardening flags.
10     * Static analysis integrated using clang's `scan-build` using checkers `alpha.security`, `alpha.core.CastSize`,
11     `alpha.core.CastToStruct`, `alpha.core.IdenticalExpr`, `alpha.core.PointerArithm`, `alpha.core.PointerSub`,
12     `alpha.core.SizeofPtr`, `alpha.core.TestAfterDivZero`, `alpha.unix`.
13     * Follows [FreeBSD coding style](https://www.freebsd.org/cgi/man.cgi?query=style&sektion=9).
14     * [RFC4180](https://datatracker.ietf.org/doc/html/rfc4180) compliant:
15         * handles `\n`, `\r` and `\r\n` as new line
16         * if double-quotes are used to enclose fields it handles double quotes appearing inside a field only if
17         escaped by preceding it with another double quote. For example `"x""y"` is equivalent to `x"y`
18         * handles the precence of the separator character inside a quoted field.
19 * Portable
20     * C99 compliant *and* may be built in an environment which provides POSIX.1-2001 system interfaces.
21     * Self-contained, no external dependencies
22     * Easy to compile and uses POSIX make.
24 ## Limitations
25 * Input lines are limited to `LINE_MAX` bytes in lenght.
26 * Only single character separators are allowed for now.
27 * The program presumes the locale is UTF-8.
29 ## Build dependencies
30 The only dependency is a toolchain supporting the following flags:
32 ```
33 CFLAGS = -std=c99 -O2 -Wall -Wextra -Wpedantic \
34         -Walloca -Wcast-qual -Wconversion -Wformat=2 -Wformat-security \
35         -Wnull-dereference -Wstack-protector -Wvla -Warray-bounds \
36         -Wbad-function-cast -Wconversion -Wshadow -Wstrict-overflow=4 -Wundef \
37         -Wstrict-prototypes -Wswitch-default -Wfloat-equal -Wimplicit-fallthrough \
38         -Wpointer-arith -Wswitch-enum \
39         -D_FORTIFY_SOURCE=2 \
40         -fstack-protector-strong -fPIE -fstack-clash-protection
42 LDFLAGS = -Wl,-z,relro -Wl,-z,now -Wl,-z,noexecstack -Wl,-z,separate-code
43 ```
45 Otherwise you can just remove the security flags and compile it with
46 ```
47 CFLAGS = -std=c99 -O2 -Wall -Wextra -Wpedantic
48 LDFLAGS =
49 ```
51 or pass your own flags to make
52 ```sh
53 make CC=gcc CFLAGS=... LDFLAGS=...
54 ```
56 ## Installation
57 Clone this repository then
59 ```sh
60 $ make PREFIX=/usr install
61 ```
63 This will install the compiled binary under `PREFIX` (`/usr/bin`) in this case, if not specified `PREFIX` will default
64 to `/usr/local`. For staged installs, `DESTDIR` is also supported. As the binary does not have any dependency it does
65 not have to be installed before use.
67 ## Usage
68 **tabular** receives as input one or more files to print as a table. The files however, can be omitted, in this case
69 the program takes the input from the standard input until `EOF` or `^D` is reached. If a file is a single dash (‘-’),
70 **tabular** reads from standard input.
72 The options are as follows:
74 * **-s** Specify a character to be used to delimit the columns and each field. If omitted `','` is used.
76 ### Examples
77 Example CSVs are taken from [https://people.sc.fsu.edu/~jburkardt/data/csv/csv.html](https://people.sc.fsu.edu/~jburkardt/data/csv/csv.html)
79 ```sh
80 $ cat addresses.csv
81 John,Doe,120 jefferson st.,Riverside, NJ, 08075
82 Jack,McGinnis,220 hobo Av.,Phila, PA,09119
83 "John ""Da Man""",Repici,120 Jefferson St.,Riverside, NJ,08075
84 Stephen,Tyler,"7452 Terrace ""At the Plaza"" road",SomeTown,SD, 91234
85 ,Blankman,,SomeTown, SD, 00298
86 "Joan ""the bone"", Anne",Jet,"9th, at Terrace plc",Desert City,CO,00123
88 $ tabular addresses.csv
89 John                   Doe       120 jefferson st.                 Riverside     NJ   08075
90 Jack                   McGinnis  220 hobo Av.                      Phila         PA  09119
91 John "Da Man"          Repici    120 Jefferson St.                 Riverside     NJ  08075
92 Stephen                Tyler     7452 Terrace "At the Plaza" road  SomeTown     SD    91234
93                        Blankman                                    SomeTown      SD   00298
94 Joan "the bone", Anne  Jet       9th, at Terrace plc               Desert City  CO   00123
95 ```
97 ```sh
98 $ tabular tally_cab.csv - addresses.csv <<EOF
99 foo,bar,baz
100 a,b,c,
103 Distance (miles)   "Fare ($)"
104  4.5                 18.00
105 26.7                 73.75
106  6.7                 23.00
107 16.4                 56.00
108 32.7                 83.25
109  5.7                 17.50
110 77.0                190.50
111  8.3                 19.65
112 foo  bar  baz
113 a    b    c
114 John                   Doe       120 jefferson st.                 Riverside     NJ   08075
115 Jack                   McGinnis  220 hobo Av.                      Phila         PA  09119
116 John "Da Man"          Repici    120 Jefferson St.                 Riverside     NJ  08075
117 Stephen                Tyler     7452 Terrace "At the Plaza" road  SomeTown     SD    91234
118                        Blankman                                    SomeTown      SD   00298
119 Joan "the bone", Anne  Jet       9th, at Terrace plc               Desert City  CO   00123
122 ```sh
123 $ cat names.csv | tabular -s ';'
124 ID     NAME                  AGE
125 23434  Norris, Chuck         24
126 34343  Bond, James "master"  57
129 ### Static analysis
130 Static analysis on the code base is done by using clang's static analyzer run through `scan-build.sh` which wraps the
131 `scan-build` utility. The checkers used are part of the
132 [Experimental Checkers](https://releases.llvm.org/12.0.0/tools/clang/docs/analyzer/checkers.html#alpha-checkers)
133 (aka *alpha* checkers):
135 * `alpha.security`
136 * `alpha.core.CastSize`
137 * `alpha.core.CastToStruct`
138 * `alpha.core.IdenticalExpr`
139 * `alpha.core.PointerArithm`
140 * `alpha.core.PointerSub`
141 * `alpha.core.SizeofPtr`
142 * `alpha.core.TestAfterDivZero`
143 * `alpha.unix`
145 ## Contributing
146 Send patches on the [mailing list](https://www.freelists.org/list/tabular-dev), report bugs using [git-bug](https://github.com/MichaelMure/git-bug/). 
148 ## License
149 BSD 2-Clause FreeBSD License, see LICENSE.