.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.3.
.TH DECORATE "1" "July 2022" "decorate 1.8-dirty" "User Commands"
.SH NAME
decorate - convert fields of various formats
.SH SYNOPSIS
.B decorate
[\fI\,OPTION\/\fR]... [\fI\,INPUT\/\fR]
.br
.B decorate
\fI\,--decorate \/\fR[\fI\,OPTION\/\fR]... [\fI\,INPUT\/\fR]
.br
.B decorate
\fI\,--undecorate N \/\fR[\fI\,OPTION\/\fR]... [\fI\,INPUT\/\fR]
.SH DESCRIPTION
Converts (and optionally sorts) fields of various formats
.PP
With \fB\-\-decorate\fR: adds the converted fields to the start
of each line and prints and prints it to STDOUT; does not sort.
.PP
With \fB\-\-undecorate\fR: removes the first N fields from the input;
Use as post\-processing step after sort(1).
.PP
Without \fB\-\-decorate\fR and \fB\-\-undecorate\fR: automatically decorates the input,
runs sort(1) and undecorates the result; This is the easiest method to use.
The \fBdecorate\fR program allows sorting input according to various
ordering, e.g. IP addresses, roman numerals, etc.
It works in tandem with sort(1) to perform the actual sorting.

The idea was suggested by
.UR https://lists.gnu.org/r/bug-coreutils/2015-06/msg00076.html
Pádraig Brady in https://lists.gnu.org/r/bug-coreutils/2015-06/msg00076.html:

1. Decorate: convert the input to a sortable-format as additional fields
.br
2. Sort according to the inserted fields
.br
3. Undecorate: remove the inserted fields
.SH OPTIONS
.SS "General Options:"
.TP
\fB\-\-decorate\fR
decorate/convert the specified fields and print
the output to STDOUT. Does not automatically run
sort(1) or undecorates the output
.TP
\fB\-\-header\fR=\fI\,N\/\fR
does not decorate or sort the first N lines
.TP
\fB\-H\fR
same as \fB\-\-header\fR=\fI\,N\/\fR
.TP
\fB\-k\fR, \fB\-\-key\fR=\fI\,KEYDEF\/\fR
key/field to sort; same syntax as sort(1),
optionally followed by ':method' to convert
to the field into a sortable value; see examples
and available conversion below
.TP
\fB\-t\fR, \fB\-\-field\-separator\fR=\fI\,SEP\/\fR
use SEP instead of non\-blank to blank transition
.TP
\fB\-\-print\-sort\-args\fR
print adjusted parameters for sort(1); Useful
when using \fB\-\-decorate\fR and then manually running
sort(1)
.TP
\fB\-\-undecorate\fR=\fI\,N\/\fR
removes the first N fields
.TP
\fB\-z\fR, \fB\-\-zero\-terminated\fR
line delimiter is NUL, not newline
.TP
\fB\-\-sort\-cmd=\fR/path/to/sort
Alternative sort(1) to use.
.TP
\fB\-\-help\fR
display this help and exit
.TP
\fB\-\-version\fR
output version information and exit
.PP
The following options are passed to sort as\-is (Most of them assume GNU sort):
.HP
\fB\-c\fR, \fB\-\-check\fR
.HP
\fB\-\-compress\-program\fR
.HP
\fB\-\-random\-source\fR
.HP
\fB\-s\fR, \fB\-\-stable\fR
.HP
\fB\-\-batch\-size\fR
.HP
\fB\-S\fR, \fB\-\-buffer\-size\fR
.HP
\fB\-T\fR, \fB\-\-temporary\-directory\fR
.HP
\fB\-u\fR, \fB\-\-unique\fR
.HP
\fB\-\-parallel\fR
.PP
Available conversions methods (use with \fB\-k\fR):
.TP
as\-is
copy as\-is
.TP
roman
roman numerals
.TP
strlen
length (in bytes) of the specified field
.TP
ipv4
dotted\-decimal IPv4 addresses
.TP
ipv6
IPv6 addresses
.TP
ipv4inet
number\-and\-dots IPv4 addresses (incl. octal, hex values)
.TP
ipv6v4map
IPv6 and IPv4 (as IPv4\-Mapped IPv6) addresses
.TP
ipv6v4comp
IPv6 and IPv4 (as IPv4\-Compatible IPv6) addresses
.SH EXAMPLES
Example of preparing to sort by roman numerals:
.PP
.nf
.RS
$ printf "%s\\n" C V III IX XI | \fBdecorate\fR \-k1,1:roman \-\-decorate
0000100 C
0000005 V
0000003 III
0000009 IX
0000011 XI
.RE
.fi
.PP

The output can now be sent to sort(1), followed by removing (=undecorate)
the first field.

.PP
.nf
.RS
$ printf "%s\\n" C V III IX XI \\
       | \fBdecorate\fR \-k1,1:roman \-\-decorate \\
       | sort \-k1,1 \\
       | \fBdecorate\fR \-\-undecorate 1
III
V
IX
XI
C
.RE
.fi
.PP

\fBdecorate(1)\fR can automatically combine the decorate-sort-undecorate steps
(when run without \-\-decorate or \-\-undecorate):

.PP
.nf
.RS
$ printf "%s\\n" C V III IX XI | \fBdecorate\fR \-k1,1:roman
III
V
IX
XI
C
.RE
.fi
.PP
.SH "ADDITIONAL INFORMATION"
See
.UR https://www.gnu.org/software/datamash
GNU Datamash Website (https://www.gnu.org/software/datamash)
.SH AUTHOR
Written by Assaf Gordon, Shawn Wagner and Erik Auerswald.
.SH COPYRIGHT
Copyright \(co 2022 Assaf Gordon
License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
.br
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
.SH "SEE ALSO"
The full documentation for
.B decorate
is maintained as a Texinfo manual.  If the
.B info
and
.B decorate
programs are properly installed at your site, the command
.IP
.B info decorate
.PP
should give you access to the complete manual.