tuc.1

.\" Automatically generated by Pandoc 3.1.3
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "tuc" "1" "Jan 01, 2024" "Tuc 1.2.0" "Tuc Manual"
.hy
.SH NAME
.PP
\f[B]tuc\f[R] \[em] cut text or bytes and keep what you need
.SH SYNOPSIS
.PP
\f[B]tuc\f[R] [FLAGS]\&...
[OPTIONS]\&...
.SH DESCRIPTION
.PP
Cut text (or bytes) where a delimiter matches, then keep the desired
parts.
.PP
The data is read from standard input.
.SH FLAGS
.TP
.B \-g, --greedy-delimiter
Match consecutive delimiters as if it was one
.TP
.B \-p, --compress-delimiter
Print only the first delimiter of a sequence
.TP
.B \-s, --only-delimited
Print only lines containing the delimiter
.TP
.B \-V, --version
Print version information
.TP
.B \-z, --zero-terminated
Line delimiter is NUL (\[rs]0), not LF (\[rs]n)
.TP
.B \-h, --help
Print this help and exit
.TP
.B \-m, --complement
Invert fields (e.g.\ \[aq]2\[aq] becomes \[aq]1,3:\[aq])
.TP
.B \-j, --(no-)join
Print selected parts with delimiter in between
.TP
.B --json
Print fields as a JSON array of strings
.SH OPTIONS
.PP
\f[B]-f\f[R], \f[B]--fields\f[R] [bounds]
.PD 0
.P
.PD
\ \ \ \ \ \ \ Fields to keep, 1-indexed, comma separated.
.PD 0
.P
.PD
\ \ \ \ \ \ \ Use colon (:) to match a range (inclusive).
.PD 0
.P
.PD
\ \ \ \ \ \ \ Use equal (=) to apply out of bound fallback.
.PD 0
.P
.PD
\ \ \ \ \ \ \ Fields can be negative (-1 is the last field).
.PP
\ \ \ \ \ \ \ [default 1:]
.PP
\ \ \ \ \ \ \ e.g.\ cutting the string \[aq]a-b-c-d\[aq] on \[aq]-\[aq]
.PD 0
.P
.PD
\ \ \ \ \ \ \ \ \ \f[V]-f 1     => a\f[R]
.PD 0
.P
.PD
\ \ \ \ \ \ \ \ \ \f[V]-f 1:    => a-b-c-d\f[R]
.PD 0
.P
.PD
\ \ \ \ \ \ \ \ \ \f[V]-f 1:3   => a-b-c\f[R]
.PD 0
.P
.PD
\ \ \ \ \ \ \ \ \ \f[V]-f 3,2   => cb\f[R]
.PD 0
.P
.PD
\ \ \ \ \ \ \ \ \ \f[V]-f 3,1:2 => ca-b\f[R]
.PD 0
.P
.PD
\ \ \ \ \ \ \ \ \ \f[V]-f -3:-2 => b-c\f[R]
.PD 0
.P
.PD
\ \ \ \ \ \ \ \ \ \f[V]-f 1,8=fallback => afallback\f[R]
.PP
\ \ \ \ \ \ \ To re-apply the delimiter add -j, to replace
.PD 0
.P
.PD
\ \ \ \ \ \ \ it add -r (followed by the new delimiter)
.PP
\ \ \ \ \ \ \ You can also format the output using {} syntax
.PD 0
.P
.PD
\ \ \ \ \ \ \ e.g.
.PD 0
.P
.PD
\ \ \ \ \ \ \ \ \ \f[V]-f \[aq]({1}, {2})\[aq] => (a, b)\f[R]
.PP
\ \ \ \ \ \ \ You can escape { and } using {{ and }}.
.PP
\f[B]-b\f[R], \f[B]--bytes\f[R] [bounds]
.PD 0
.P
.PD
\ \ \ \ \ \ \ Same as --fields, but it keeps bytes
.PP
\f[B]-c\f[R], \f[B]--characters\f[R] [bounds]
.PD 0
.P
.PD
\ \ \ \ \ \ \ Same as --fields, but it keeps characters
.PP
\f[B]-l\f[R], \f[B]--lines\f[R] [bounds]
.PD 0
.P
.PD
\ \ \ \ \ \ \ Same as --fields, but it keeps lines
.PD 0
.P
.PD
\ \ \ \ \ \ \ Implies --join.
To merge lines, use --no-join
.PP
\f[B]-d\f[R], \f[B]--delimiter\f[R] [delimiter]
.PD 0
.P
.PD
\ \ \ \ \ \ \ Delimiter used by --fields to cut the text
.PD 0
.P
.PD
\ \ \ \ \ \ \ [default: \[rs]t]
.PP
\f[B]-e\f[R], \f[B]--regex\f[R] [some regex]
.PD 0
.P
.PD
\ \ \ \ \ \ \ Use a regular expression as delimiter
.PP
\f[B]-r\f[R], \f[B]--replace-delimiter\f[R] [new delimiter]
.PD 0
.P
.PD
\ \ \ \ \ \ \ Replace the delimiter with the provided text
.PP
\f[B]-t\f[R], \f[B]--trim\f[R] [type]
.PD 0
.P
.PD
\ \ \ \ \ \ \ Trim the delimiter (greedy).
.PD 0
.P
.PD
\ \ \ \ \ \ \ Valid values are (l|L)eft, (r|R)ight, (b|B)oth
.PP
\ \ \ \ \f[B]--fallback-oob\f[R] [fallback]
.PD 0
.P
.PD
\ \ \ \ \ \ \ Generic fallback output for any field that
.PD 0
.P
.PD
\ \ \ \ \ \ \ cannot be found (oob stands for out of bound).
.PD 0
.P
.PD
\ \ \ \ \ \ \ It\[cq]s overridden by any fallback assigned to a
.PD 0
.P
.PD
\ \ \ \ \ \ \ specific field (see -f for help)
.SH OPTIONS PRECEDENCE
.PP
--trim and --compress-delimiter are applied before --fields or similar
.SH MEMORY CONSUMPTION
.PP
--characters and --fields read and allocate memory one line at a time
.PP
--lines allocate memory one line at a time as long as the requested
fields are
.PD 0
.P
.PD
ordered and non-negative (e.g.\ -l 1,3:4,4,7), otherwise it allocates
.PD 0
.P
.PD
the whole input in memory (it also happens when -p or -m are being used)
.PP
--bytes allocate the whole input in memory
.SH COLORS
.PP
Help is displayed using colors.
Colors will be suppressed in the
.PD 0
.P
.PD
following circumstances:
.IP \[bu] 2
when the TERM environment variable is not set or set to \[lq]dumb\[rq]
.IP \[bu] 2
when the NO_COLOR environment variable is set (regardless of value)
.SH BUGS
.PP
See GitHub Issues: <https://github.com/riquito/tuc/issues>
.SH AUTHOR
.PP
Riccardo Attilio Galli <riccardo@sideralis.org>
.SH SEE ALSO
.PP
\f[B]cut(1)\f[R], \f[B]sed(1)\f[R], \f[B]awk(1)\f[R]