mirror of
https://codeberg.org/scip/tablizer.git
synced 2025-12-17 12:31:06 +01:00
318 lines
9.4 KiB
Plaintext
318 lines
9.4 KiB
Plaintext
=head1 NAME
|
|
|
|
tablizer - Manipulate tabular output of other programs
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
Usage:
|
|
tablizer [regex] [file, ...] [flags]
|
|
|
|
Operational Flags:
|
|
-c, --columns string Only show the speficied columns (separated by ,)
|
|
-v, --invert-match select non-matching rows
|
|
-n, --no-numbering Disable header numbering
|
|
-N, --no-color Disable pattern highlighting
|
|
-s, --separator string Custom field separator
|
|
-k, --sort-by int Sort by column (default: 1)
|
|
|
|
Output Flags (mutually exclusive):
|
|
-X, --extended Enable extended output
|
|
-M, --markdown Enable markdown table output
|
|
-O, --orgtbl Enable org-mode table output
|
|
-S, --shell Enable shell evaluable ouput
|
|
-Y, --yaml Enable yaml output
|
|
-C, --csv Enable CSV output
|
|
-A, --ascii Default output mode, ascii tabular
|
|
|
|
Sort Mode Flags (mutually exclusive):
|
|
-a, --sort-age sort according to age (duration) string
|
|
-D, --sort-desc Sort in descending order (default: ascending)
|
|
-i, --sort-numeric sort according to string numerical value
|
|
-t, --sort-time sort according to time string
|
|
|
|
Other Flags:
|
|
--completion <shell> Generate the autocompletion script for <shell>
|
|
-d, --debug Enable debugging
|
|
-h, --help help for tablizer
|
|
-m, --man Display manual page
|
|
-v, --version Print program version
|
|
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
Many programs generate tabular output. But sometimes you need to
|
|
post-process these tables, you may need to remove one or more columns
|
|
or you may want to filter for some pattern (See L<PATTERNS>) or you
|
|
may need the output in another program and need to parse it somehow.
|
|
Standard unix tools such as awk(1), grep(1) or column(1) may help, but
|
|
sometimes it's a tedious business.
|
|
|
|
Let's take the output of the tool kubectl. It contains cells with
|
|
withespace and they do not separate columns by TAB characters. This is
|
|
not easy to process.
|
|
|
|
You can use B<tablizer> to do these and more things.
|
|
|
|
B<tablizer> analyses the header fields of a table, registers the
|
|
column positions of each header field and separates columns by those
|
|
positions.
|
|
|
|
Without any options it reads its input from C<STDIN>, but you can also
|
|
specify a file as a parameter. If you want to reduce the output by
|
|
some regular expression, just specify it as its first parameter. You
|
|
may also use the B<-v> option to exclude all rows which match the
|
|
pattern. Hence:
|
|
|
|
# read from STDIN
|
|
kubectl get pods | tablizer
|
|
|
|
# read a file
|
|
tablizer filename
|
|
|
|
# search for pattern in a file (works like grep)
|
|
tablizer regex filename
|
|
|
|
# search for pattern in STDIN
|
|
kubectl get pods | tablizer regex
|
|
|
|
The output looks like the original one but every header field will
|
|
have a numer associated with it, e.g.:
|
|
|
|
NAME(1) READY(2) STATUS(3) RESTARTS(4) AGE(5)
|
|
|
|
These numbers denote the column and you can use them to specify which
|
|
columns you want to have in your output (see L<COLUMNS>:
|
|
|
|
kubectl get pods | tablizer -c1,3
|
|
|
|
You can specify the numbers in any order but output will always follow
|
|
the original order.
|
|
|
|
The numbering can be suppressed by using the B<-n> option.
|
|
|
|
By default, if a B<pattern> has been speficied, matches will be
|
|
highlighted. You can disable this behavior with the B<-N> option.
|
|
|
|
Use the B<-k> option to specify by which column to sort the tabular
|
|
data (as in GNU sort(1)). The default sort column is the first one. To
|
|
disable sorting at all, supply 0 (Zero) to -k. The default sort order
|
|
is ascending. You can change this to descending order using the option
|
|
B<-D>. The default sort order is by string, but there are other sort
|
|
modes:
|
|
|
|
=over
|
|
|
|
=item B<-a --sort-age>
|
|
|
|
Sorts duration strings like "1d4h32m51s".
|
|
|
|
=item B<-i --sort-numeric>
|
|
|
|
Sorts numeric fields.
|
|
|
|
=item B<-t --sort-time>
|
|
|
|
Sorts timestamps.
|
|
|
|
=back
|
|
|
|
Finally the B<-d> option enables debugging output which is mostly
|
|
useful for the developer.
|
|
|
|
=head2 PATTERNS
|
|
|
|
You can reduce the rows being displayed by using a regular expression
|
|
pattern. The regexp is PCRE compatible, refer to the syntax cheat
|
|
sheet here: L<https://github.com/google/re2/wiki/Syntax>. If you want
|
|
to read a more comprehensive documentation about the topic and have
|
|
perl installed you can read it with:
|
|
|
|
perldoc perlre
|
|
|
|
Or read it online: L<https://perldoc.perl.org/perlre>.
|
|
|
|
A note on modifiers: the regexp engine used in tablizer uses another
|
|
modifier syntax:
|
|
|
|
(?MODIFIER)
|
|
|
|
The most important modifiers are:
|
|
|
|
C<i> ignore case
|
|
C<m> multiline mode
|
|
C<s> single line mode
|
|
|
|
Example for a case insensitive search:
|
|
|
|
kubectl get pods -A | tablizer "(?i)account"
|
|
|
|
|
|
=head2 COLUMNS
|
|
|
|
The parameter B<-c> can be used to specify, which columns to
|
|
display. By default tablizer numerizes the header names and these
|
|
numbers can be used to specify which header to display, see example
|
|
above.
|
|
|
|
However, beside numbers, you can also use regular expressions with
|
|
B<-c>, also separated by comma. And you can mix column numbers with
|
|
regexps.
|
|
|
|
Lets take this table:
|
|
|
|
PID TTY TIME CMD
|
|
14001 pts/0 00:00:00 bash
|
|
42871 pts/0 00:00:00 ps
|
|
42872 pts/0 00:00:00 sed
|
|
|
|
We want to see only the CMD column and use a regex for this:
|
|
|
|
ps | tablizer -s '\s+' -c C
|
|
CMD(4)
|
|
bash
|
|
ps
|
|
tablizer
|
|
sed
|
|
|
|
where "C" is our regexp which matches CMD.
|
|
|
|
=head2 OUTPUT MODES
|
|
|
|
There might be cases when the tabular output of a program is way too
|
|
large for your current terminal but you still need to see every
|
|
column. In such cases the B<-o extended> or B<-X> option can be
|
|
useful which enables I<extended mode>. In this mode, each row will be
|
|
printed vertically, header left, value right, aligned by the field
|
|
widths. Here's an example:
|
|
|
|
kubectl get pods | ./tablizer -o extended
|
|
NAME: repldepl-7bcd8d5b64-7zq4l
|
|
READY: 1/1
|
|
STATUS: Running
|
|
RESTARTS: 1 (71m ago)
|
|
AGE: 5h28m
|
|
|
|
You can of course still use a regex to reduce the number of rows
|
|
displayed.
|
|
|
|
The option B<-o shell> can be used if the output has to be processed
|
|
by the shell, it prints variable assignments for each cell, one line
|
|
per row:
|
|
|
|
kubectl get pods | ./tablizer -o extended ./tablizer -o shell
|
|
NAME="repldepl-7bcd8d5b64-7zq4l" READY="1/1" STATUS="Running" RESTARTS="9 (47m ago)" AGE="4d23h"
|
|
NAME="repldepl-7bcd8d5b64-m48n8" READY="1/1" STATUS="Running" RESTARTS="9 (47m ago)" AGE="4d23h"
|
|
NAME="repldepl-7bcd8d5b64-q2bf4" READY="1/1" STATUS="Running" RESTARTS="9 (47m ago)" AGE="4d23h"
|
|
|
|
You can use this in an eval loop.
|
|
|
|
Beside normal ascii mode (the default) and extended mode there are
|
|
more output modes available: B<orgtbl> which prints an Emacs org-mode
|
|
table and B<markdown> which prints a Markdown table, B<yaml>, which
|
|
prints yaml encoding and CSV mode, which prints a comma separated
|
|
value file.
|
|
|
|
=head2 ENVIRONMENT VARIABLES
|
|
|
|
B<tablizer> supports certain environment variables which use can use
|
|
to influence program behavior. Commandline flags have always
|
|
precedence over environment variables.
|
|
|
|
=over
|
|
|
|
=item <T_NO_HEADER_NUMBERING> - disable numbering of header fields, like B<-n>.
|
|
|
|
=item <T_COLUMNS> - comma separated list of columns to output, like B<-c>
|
|
|
|
=item <NO_COLORS> - disable colorization of matches, like B<-N>
|
|
|
|
=back
|
|
|
|
=head2 COMPLETION
|
|
|
|
Shell completion for command line options can be enabled by using the
|
|
B<--completion> flag. The required parameter is the name of your
|
|
shell. Currently supported are: bash, zsh, fish and powershell.
|
|
|
|
Detailed instructions:
|
|
|
|
=over
|
|
|
|
=item Bash:
|
|
|
|
source <(tablizer --completion bash)
|
|
|
|
To load completions for each session, execute once:
|
|
|
|
# Linux:
|
|
$ tablizer --completion bash > /etc/bash_completion.d/tablizer
|
|
|
|
# macOS:
|
|
$ tablizer --completion bash > $(brew --prefix)/etc/bash_completion.d/tablizer
|
|
|
|
=item Zsh:
|
|
|
|
If shell completion is not already enabled in your environment,
|
|
you will need to enable it. You can execute the following once:
|
|
|
|
echo "autoload -U compinit; compinit" >> ~/.zshrc
|
|
|
|
To load completions for each session, execute once:
|
|
|
|
$ tablizer --completion zsh > "${fpath[1]}/_tablizer"
|
|
|
|
You will need to start a new shell for this setup to take effect.
|
|
|
|
=item fish:
|
|
|
|
tablizer --completion fish | source
|
|
|
|
To load completions for each session, execute once:
|
|
|
|
tablizer --completion fish > ~/.config/fish/completions/tablizer.fish
|
|
|
|
=item PowerShell:
|
|
|
|
tablizer --completion powershell | Out-String | Invoke-Expression
|
|
|
|
To load completions for every new session, run:
|
|
|
|
tablizer --completion powershell > tablizer.ps1
|
|
|
|
and source this file from your PowerShell profile.
|
|
|
|
=back
|
|
|
|
=head1 BUGS
|
|
|
|
In order to report a bug, unexpected behavior, feature requests
|
|
or to submit a patch, please open an issue on github:
|
|
L<https://github.com/TLINDEN/tablizer/issues>.
|
|
|
|
=head1 LICENSE
|
|
|
|
This software is licensed under the GNU GENERAL PUBLIC LICENSE version 3.
|
|
|
|
Copyright (c) 2022 by Thomas von Dein
|
|
|
|
This software uses the following GO libraries:
|
|
|
|
=over 4
|
|
|
|
=item repr (https://github.com/alecthomas/repr)
|
|
|
|
Released under the MIT License, Copyright (c) 2016 Alec Thomas
|
|
|
|
=item cobra (https://github.com/spf13/cobra)
|
|
|
|
Released under the Apache 2.0 license, Copyright 2013-2022 The Cobra Authors
|
|
|
|
=back
|
|
|
|
=head1 AUTHORS
|
|
|
|
Thomas von Dein B<tom AT vondein DOT org>
|
|
|
|
=cut
|
|
|