table.1.in (8704B)
1 .\" This program is licensed under the terms of GNU GPL v3 or (at your option) 2 .\" any later version. Copyright (C) 2020-2026 Страхиња Радић. 3 .\" See the file LICENSE for exact copyright and license details. 4 .Dd %DATE% 5 .Dt TABLE 1 6 .Os 7 .Sh NAME 8 .Nm table 9 .Nd Command line utility to format and display CSV and TSV 10 .Sh SYNOPSIS 11 .Nm 12 .Fl h | \-help | Fl V | \-full\-version | Fl v | \-version 13 .Nm 14 .Oo Fl a Ar alignment | Fl \-align= Ns Ar alignment Oc 15 .Oo Fl b | Fl \-border\-mode Oc 16 .Oo Fl c Ar cols | Fl \-columns= Ns Ar cols Oc 17 .Oo Fl D | Fl \-align\-dot Oc 18 .Oo Fl d Ar delim | Fl \-delimiter= Ns Ar delim Oc 19 .Oo Fl f Ar format | Fl \-format= Ns Ar format Oc 20 .Oo Fl H | Fl \-align\-header Oc 21 .Oo Fl m | Fl \-msdos Oc 22 .Oo Fl n | Fl \-no\-ansi Oc 23 .Oo Fl p | Fl \-pause Oc 24 .Oo Fl q Ar behavior | Fl \-quotes= Ns Ar behavior Oc 25 .Oo Fl s Ar set | Fl \-symbols= Ns Ar set Oc 26 .Oo Fl t | Fl \-expand\-tabs Oc 27 .Oo Fl y | Fl \-yes\-ansi Oc 28 .Op Ar pathname 29 .Sh COMMAND ALIASES 30 .Bl -column -offset 1m "123456" 31 .It Nm tablep Ta is a synonym for Ql "table -p" . 32 .It Nm tsvtable Ta is a synonym for Ql table -d Qo $(printf '\et') Qc -q ignore . 33 .El 34 . 35 .Sh DESCRIPTION 36 .Nm 37 is a command line utility to format and display CSV and TSV. 38 It parses the file given by 39 .Ar pathname 40 or standard input and prints out a table representing its contents using Unicode 41 characters for box drawing. 42 .Pp 43 When specifying multiple 44 .Ar pathname 45 arguments, 46 .Nm 47 prints a warning to stderr. 48 Only the first such argument is processed. 49 If 50 .Ar pathname 51 is omitted, 52 .Nm 53 reads standard input. 54 . 55 .Bl -tag -width Ds 56 .It Fl a Ar alignment , Fl \-align= Ns Ar alignment 57 Set column alignments. 58 .Ar alignment 59 is a string consisting of characters 60 .Cm l , 61 .Cm c 62 or 63 .Cm r , 64 which respectively set the alignment of the corresponding column to left, center 65 or right. 66 For example, 67 .Fl a Ns Cm rccc 68 sets the alignment for the first column to right, and the next three columns to 69 center. 70 .It Fl b , Fl \-border-mode 71 Border mode: force single column. 72 .It Fl c Ar cols , Fl \-columns= Ns Ar cols 73 Set maximum table width in columns (default 80). 74 .It Fl D , Fl \-align\-dot 75 Set alignment character to dot 76 .Dq "." Ns "" 77 instead of a space 78 .Dq "\ " Ns . 79 .It Fl d Ar delim , Fl \-delimiter= Ns Ar delim 80 Set field delimiter (default 81 .Do , Dc Ns ). 82 First line of the input determines the number of table columns. 83 The first character of 84 .Ar delim 85 becomes the delimiter. 86 Special characters, like 87 .Dq ";" Ns , 88 need to be quoted or escaped: 89 .Dl "$ table -d';'" 90 or 91 .Dl "$ table -d\[rs];" 92 In the examples above, 93 .Dq "'" 94 and 95 .Dq "\[rs]" 96 are parsed by the shell and are not passed to 97 .Nm , 98 so are not considered as 99 .Dq first characters 100 for the assignment. 101 .Pp 102 Note that the 103 .Fl b 104 parameter takes precedence: if it is present, 105 .Fl d 106 is ignored. 107 .It Fl f Ar format , Fl \-format= Ns Ar format 108 Set widths for individual columns as ratio. 109 Parameter 110 .Ar format 111 should be a string of weights separated by colons. 112 For example: 113 .Bd -literal 114 $ table -c 50 -s aa examples/quotes-english.csv 115 +-----------+-----------+-----------+-----------+ 116 |ID |Name |Surname |Age | 117 |001 |John |Smith |34 | 118 |002 |Steven |Watson |23 | 119 |003 |Richard |Smith |33 | 120 |007 |Bond, James|Bond |46 | 121 +-----------+-----------+-----------+-----------+ 122 $ table -f 1:2:3:4 -c 50 -s aa examples/quotes-english.csv 123 +----+---------+-------------+------------------+ 124 |ID |Name |Surname |Age | 125 |001 |John |Smith |34 | 126 |002 |Steven |Watson |23 | 127 |003 |Richard |Smith |33 | 128 |007 |Bond, Jam|Bond |46 | 129 +----+---------+-------------+------------------+ 130 $ table -f 1:5:5:1 -c 50 -s aa examples/quotes-english.csv 131 +----+------------------+------------------+----+ 132 |ID |Name |Surname |Age | 133 |001 |John |Smith |34 | 134 |002 |Steven |Watson |23 | 135 |003 |Richard |Smith |33 | 136 |007 |Bond, James |Bond |46 | 137 +----+------------------+------------------+----+ 138 .Ed 139 .It Fl H , Fl \-align\-header 140 Makes the column alignment also apply to header row. 141 The default behavior is to print header cells left\-aligned. 142 .It Fl h , Fl \-help 143 Print the usage information screen. 144 .It Fl m , Fl \-msdos 145 Ignore carriage return (\er) characters in input. 146 The default behavior is to treat them as part of the text, which can produce 147 unexpected results. 148 .It Fl n , Fl \-no\-ansi 149 Turn off ANSI SGR codes in the output. 150 By default, the header row is printed in bold using ANSI codes if the stdout is 151 a tty. 152 This switch prevents that. 153 .It Fl p , Fl \-pause 154 Presents the message 155 .Dq Press Enter to continue 156 and waits for input after outputting the table. 157 This accounts for executing 158 .Nm 159 from file managers which don't pause after executing programs or as a single 160 command from terminal emulators. 161 .It Fl q Ar behavior , Fl \-quotes= Ns Ar behavior 162 .Ar behavior 163 can be one of the following: 164 .Bl -tag -width Dsprocess 165 .It Cm process 166 Treats everything between the quotes as a single column. 167 Treats consecutive quotes within the quoted text as literal quotes. 168 This is the default. 169 .It Cm ignore 170 Ignores the special meaning of quotes (like TSV). 171 This is the default if 172 .Nm 173 is called as 174 .Nm tsvtable . 175 .El 176 .It Fl s Ar set , Fl \-symbols= Ns Ar set 177 Use table symbol set 178 .Ar set 179 for table lines, where 180 .Ar set 181 is one of the following (format: 182 .Ao Ar border Ac Ns Ao Ar inner border Ac Ns ): 183 .Bl -column -offset Ds "Literal" 184 .It Sy Literal Ta Sy Meaning 185 .It Cm aa Ta ascii-ascii, 186 .It Cm ae Ta ascii-empty, 187 .It Cm dd Ta double-double, 188 .It Cm ds Ta double-single (default), 189 .It Cm de Ta double-empty, 190 .It Cm ea Ta empty-ascii, 191 .It Cm ed Ta empty-double, 192 .It Cm ee Ta empty-empty, 193 .It Cm es Ta empty-single, 194 .It Cm sd Ta single-double, 195 .It Cm se Ta single-empty, 196 .It Cm ss Ta single-single. 197 .El 198 .Pp 199 Any other value for 200 .Ar set 201 will produce an error. 202 .It Fl t , Fl \-expand\-tabs 203 Expand tabs to spaces, honoring standard modulo 8 tab stops. 204 Default behavior is to output tab characters as\-is. 205 .Pp 206 Note that the 207 .Fl d 208 parameter takes precedence, unless 209 .Fl b 210 is also used: if the delimiter is set to the TAB character (0x09), 211 .Fl t 212 is ignored. 213 When 214 .Fl b 215 is used in addition, 216 .Fl t 217 is honored and 218 .Fl d 219 ignored. 220 .It Fl V , Fl \-full\-version 221 Print full version (like 222 .Fl v Ns ), 223 followed by copyright notice, and exit. 224 .It Fl v , Fl \-version 225 Print program version and commit date, and exit. 226 .It Fl y , Fl \-yes\-ansi 227 Explicitly turn on ANSI SGR codes in the output. 228 By default, the header row is printed in bold using ANSI codes, unless the 229 stdout is not a tty. 230 This switch enforces the output of ANSI SGR codes, even in that case. 231 .El 232 . 233 .Sh EXIT STATUS 234 .Ex -std 235 .Pp 236 For errors caused by unsuccessful calls to libc functions setting 237 .Va errno , 238 that value is returned as the exit status. 239 Otherwise, exit status is one of the following: 240 .Bl -tag -width Ds -offset indent -compact 241 .It Li 201 242 Command line option is missing a required argument. 243 .It Li 202 244 Command line argument is invalid/unsupported. 245 .It Li 203 246 Alignment specification is not valid. 247 .It Li 204 248 Numeric argument is not a valid integer. 249 .It Li 205 250 Format specification is not valid. 251 .It Li 206 252 Specified quotes literal is invalid. 253 .It Li 207 254 Set specification is invalid. 255 .It Li 208 256 File is a directory. 257 .It Li 209 258 File is not a regular file. 259 .It Li 210 260 A quote is present without its corresponding closing quote. 261 .It Li 211 262 There has been an input stream error. 263 .El 264 . 265 .Sh EXAMPLES 266 .Bl -bullet -width 0 267 .It 268 Periodically display CPU load information in a single\-line table (requires a 269 mounted Linux\-style 270 .Pa /proc 271 file system and GNU 272 .Xr watch 1 ) 273 .Bd -literal -offset 0 274 $ watch \[dq]table /proc/loadavg -d ' ' -c 50 -n -s ss\[dq] 275 .Ed 276 .It 277 Format a long list of files in the current directory in a double line table with 278 single\-line column divisors 279 .Bd -literal -offset 0 280 $ LC_ALL=C ls -l | tail -n +2 | sed -E 's/ +/ /g' | table -d ' ' -n 281 .Ed 282 .Pp 283 Caution: format of 284 .Xr ls 1 285 is not standardized, so this example might not work as intended. 286 .It 287 Print information from 288 .Pa /etc/passwd 289 in a table: 290 .Bd -literal -offset 0 291 $ table -n -d : -f 3:1:1:1:4:4:4 /etc/passwd 292 .Ed 293 .It 294 Same as above, without borders and with different column alignment: 295 .Bd -literal -offset 0 296 $ table -n -H -d: -arccclll -see -f3:1:1:1:4:4:4 /etc/passwd 297 .Ed 298 .El 299 . 300 .Sh SEE ALSO 301 .Xr awk 1 , 302 .Xr sed 1 303 . 304 .Sh AUTHORS 305 .An Strahinya Radich Aq Mt sr@strahinja.org , 306 2020\-2026 307 . 308 .Sh BUGS 309 Bugs can be reported using the ticket tracker at: 310 .Lk https://\:todo.sr.ht/\:~strahinja/\:table