From b8059eb676dc3de48631b190edf8f6411e7ba790 Mon Sep 17 00:00:00 2001 From: Thomas von Dein Date: Thu, 29 Sep 2022 16:50:36 +0200 Subject: [PATCH] Various additions: - added a man page - added build and install code to the Makefile - enhanced the README --- Makefile | 22 +++++++--- README.md | 28 +++++++++++- tablizer.pod | 121 +++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 162 insertions(+), 9 deletions(-) create mode 100644 tablizer.pod diff --git a/Makefile b/Makefile index cde47a7..993a386 100644 --- a/Makefile +++ b/Makefile @@ -3,16 +3,24 @@ tool = tablizer version = $(shell egrep "^var version = " cmd/root.go | cut -d'=' -f2 | cut -d'"' -f 2) archs = android darwin freebsd linux netbsd openbsd windows +PREFIX = /usr/local +UID = root +GID = 0 -all: - @echo "Type 'make install' to install $(tool)" +all: buildlocal man -install: - install -m 755 -d $(bindir) - install -m 755 -d $(linkdir) - install -m 755 $(tool) $(bindir)/$(tool)-$(version) - ln -sf $(bindir)/$(tool)-$(version) $(linkdir)/$(tool) +man: + pod2man -c "User Commands" -r 1 -s 1 $(tool).pod > $(tool).1 + +buildlocal: + go build release: mkdir -p releases $(foreach arch,$(archs), GOOS=$(arch) GOARCH=amd64 go build -x -o releases/$(tool)-$(arch)-amd64-$(version); sha256sum releases/$(tool)-$(arch)-amd64-$(version) | cut -d' ' -f1 > releases/$(tool)-$(arch)-amd64-$(version).sha256sum;) + +install: buildlocal + install -d -o $(UID) -g $(GID) $(PREFIX)/bin + install -d -o $(UID) -g $(GID) $(PREFIX)/man/man1 + install -o $(UID) -g $(GID) -m 555 $(tool) $(PREFIX)/sbin/ + install -o $(UID) -g $(GID) -m 444 $(tool).1 $(PREFIX)/man/man1/ diff --git a/README.md b/README.md index a8f6ae1..34f9c03 100644 --- a/README.md +++ b/README.md @@ -68,8 +68,32 @@ repldepl-7bcd8d5b64-q2bf4 1/1 Running 1 (69m ago) 5h26m ## Installation -Download the latest release file for your architecture and put it into -a directory within your `$PATH`. +There are multiple ways to install **tablizer**: + +- Go to the [latest release page](https://github.com/muesli/mango/releases/latest), + locate the binary for your operating system and platform. + + Download it and put it into some directory within your `$PATH` variable. + +- You can also install from source. Issue the following commands in your shell: + ``` + git clone https://github.com/TLINDEN/tablizer.git + cd tablizer + make + sudo make install + ``` + +## Documentation + +The documentation is provided as a unix man-page. It will be +automatically installed if you install from source. However, you can +read the man-page online: + +https://github.com/TLINDEN/tablizer/tablizer.pod + +Or if you cloned the repository you can read it this way (perl needs +to be installed though): `perldoc tablizer.pod`. + ## Getting help diff --git a/tablizer.pod b/tablizer.pod new file mode 100644 index 0000000..5b3752a --- /dev/null +++ b/tablizer.pod @@ -0,0 +1,121 @@ +=head1 NAME + +tablizer - Manipulate tabular output of other programs + +=head1 SYNOPSIS + + Usage: + tablizer [regex] [file, ...] [flags] + + Flags: + -c, --columns string Only show the speficied columns (separated by ,) + -d, --debug Enable debugging + -x, --extended Enable extended output + -h, --help help for tablizer + -n, --no-numbering Disable header numbering + -s, --separator string Custom field separator + -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 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 to do these and more things. + +B analyses the header fiels 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, 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 +parameters. 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: + + 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. + +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<-x> can be usefull which enables +I. 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 -x + 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. + +Finally the B<-d> options enables debugging output which is mostly +usefull for the developer. + +=head1 BUGS + +In order to report a bug, unexpected behavior, feature requests +or to submit a patch, please open an issue on github: +L. + +=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 (github.com/spf13/cobra) + +Released under the Apache 2.0 license, Copyright 2013-2022 The Cobra Authors + +=back + +=head1 AUTHORS + +Thomas von Dein B + +=cut +