.TH TEIP 1 "FEB 2023" "User Commands" "" .SH NAME .PP teip \- Masking tape to help commands "do one thing well" .SH SYNOPSIS .PP \fB\fCteip\fR \-g <\fIpattern\fP> [\-oGsvz] [\-\-] [<\fIcommand\fP>...] .PP \fB\fCteip\fR \-f <\fIlist\fP> [\-d <\fIdelimiter\fP> | \-D <\fIpattern\fP> | \-\-csv] [\-svz] [\-\-] [<\fIcommand\fP>...] .PP \fB\fCteip\fR \-c <\fIlist\fP> [\-svz] [\-\-] [<\fIcommand\fP>...] .PP \fB\fCteip\fR \-l <\fIlist\fP> [\-svz] [\-\-] [<\fIcommand\fP>...] .PP \fB\fCteip\fR \-e <\fIstring\fP> [\-svz] [\-\-] [<\fIcommand\fP>...] .PP \fB\fCteip\fR \-\-help | \-\-version .SH DESCRIPTION .PP Bypassing a partial range of standard input to any command whatever you want .SH OPTIONS .TP \fB\fC\-\-help\fR Display this help and exit .TP \fB\fC\-V\fR, \fB\fC\-\-version\fR Show version and exit .TP \fB\fC\-g\fR <\fIpattern\fP> Bypassing lines that match the regular expression <\fIpattern\fP> .TP \fB\fC\-o\fR \-g bypasses only matched parts .TP \fB\fC\-G\fR \-g adopts Oniguruma regular expressions .TP \fB\fC\-f\fR <\fIlist\fP> Bypassing these white\-space separated fields .TP \fB\fC\-d\fR <\fIdelimiter\fP> Use <\fIdelimiter\fP> for field delimiter of \-f .TP \fB\fC\-D\fR <\fIpattern\fP> Use a regular expression <\fIpattern\fP> for field delimiter of \-f .TP \fB\fC\-c\fR <\fIlist\fP> Select only these characters .TP \fB\fC\-e\fR <\fIstring\fP> Execute <\fIstring\fP> on another process that will receive identical standard input as the teip, and numbers given by the result are used as line numbers for bypassing .TP \fB\fC\-l\fR <\fIlist\fP> Bypassing these lines .TP \fB\fC\-\-csv\fR \-f interprets as field number of a CSV according to RFC 4180, instead of white\-space separated fields .TP \fB\fC\-s\fR Execute new command for each bypassed chunk .TP \fB\fC\-\-chomp\fR Command spawned by \-s receives standard input without trailing newlines .TP \fB\fC\-v\fR Invert the sense of selecting .TP \fB\fC\-z\fR NUL is used as line delimiter instead of the newline .TP \-A <\fInumber\fP> Use together with \fB\fC\-g \fR\&. Alias of \fB\fC\-e 'grep \-n \-A '\fR .TP \-B <\fInumber\fP> Use together with \fB\fC\-g \fR\&. Alias of \fB\fC\-e 'grep \-n \-B '\fR .TP \-C <\fInumber\fP> Use together with \fB\fC\-g \fR\&. Alias of \fB\fC\-e 'grep \-n \-C '\fR .TP \-\-sed <\fIpattern\fP> Alias of \fB\fC\-e 'sed \-n "="'\fR See also .BR sed (1) .TP \-\-awk <\fIpattern\fP> Alias of \fB\fC\-e 'awk "{print NR}"'\fR See also .BR awk (1) .SS \fIcommand\fP .PP \fIcommand\fP is the command and its arguments that \fB\fCteip\fR executes. \fIcommand\fP must print a single line of result for each line of the input. In the simplest example, the .BR cat (1) command always succeeds. Because the cat prints the same number of lines against the input. .PP .RS .nf $ echo ABCDEF | teip \-og . \-\- cat ABCDEF .fi .RE .PP .BR sed (1) works with the typical pattern. .PP .RS .nf $ echo ABCDEF | teip \-og . \-\- sed 's/[ADF]/@/' @BC@E@ .fi .RE .PP If the rule is not satisfied, the result will be inconsistent. For example, the .BR grep (1) may fail. Here is an example. .PP .RS .nf $ echo ABCDEF | teip \-og . \-\- grep '[ABC]' ABC teip: Output of given command is exhausted .fi .RE .PP \fB\fCteip\fR could not get the result corresponding to D, E, and F. That is why the example fails. If such the inconsistency occurs, \fB\fCteip\fR will exit with the error message. Then, the exit status will be 1. .PP .RS .nf $ echo $? 1 .fi .RE .PP If \fIcommand\fP is not given, \fB\fCteip\fR shows how standard input will be devided into chunks. .PP .RS .nf $ echo ABCDEF | teip \-og . [A][B][C][D][E][F] .fi .RE .SS \fIlist\fP .PP \fIlist\fP is an expression to specify the range of fields or characters. The notation is compatible with the one used in .BR cut (1). Refer to the .BR cut (1) manual in detail. Here are some examples. .PP Select 1st, 3rd, and 5th fields. .PP .RS .nf $ echo 1 2 3 4 5 | teip \-f 1,3,5 \-\- sed 's/./@/' @ 2 @ 4 @ .fi .RE .PP Select fields between 2nd and 4th. .PP .RS .nf $ echo 1 2 3 4 5 | teip \-f 2\-4 \-\- sed 's/./@/' 1 @ @ @ 5 .fi .RE .PP Select all the fields after 3rd. .PP .RS .nf $ echo 1 2 3 4 5 | teip \-f 3\- \-\- sed 's/./@/' 1 2 @ @ @ .fi .RE .PP Select all the fields before 4th. .PP .RS .nf $ echo 1 2 3 4 5 | teip \-f \-4 \-\- sed 's/./@/' @ @ @ @ 5 .fi .RE .SS \fIpattern\fP .PP \fIpattern\fP is a regular expression whose grammar follows "regex crate". Refer to the link in \fISEE ALSO\fP about the details. .SS Necessity of \fB\-\-\fP .PP \fB\fCteip\fR interprets arguments after \fB\fC\-\-\fR as \fIcommand\fP and its argument. .PP If \fB\-\-\fP is omitted, the command fails in this example. .PP .RS .nf $ echo "100 200 300 400" | teip \-f 3 cut \-c 1 teip: Invalid arguments. .fi .RE .PP This is because the \fB\fCcut\fR uses the \fB\fC\-c\fR option. The option of the same name is also provided by \fB\fCteip\fR, which is confusing. .PP .RS .nf $ echo "100 200 300 400" | teip \-f 3 \-\- cut \-c 1 100 200 3 400 .fi .RE .SS External execution for match offloading (\fB\fC\-e\fR) .PP With \fB\fC\-e\fR, you can use the external commands you are familiar with to specify the range of holes. \fB\fC\-e\fR allows you to specify the shell pipeline as a string. This pipeline is executed in \fB\fC/bin/sh\fR\&. .PP For example, with a pipeline \fB\fCecho 3\fR that outputs \fB\fC3\fR, then only the third line will be bypassed. .PP .RS .nf $ echo \-e 'AAA\\nBBB\\nCCC' | teip \-e 'echo 3' AAA BBB [CCC] .fi .RE .PP It works even if the output is somewhat 'dirty'. For example, if any spaces or tab characters are included at the beginning of a line, they are ignored. Also, once a number is given, it does not matter if there are non\-numerical characters to the right of the number. .PP .RS .nf $ echo \-e 'AAA\\nBBB\\nCCC' | teip \-e 'echo " 3"' AAA BBB [CCC] $ echo \-e 'AAA\\nBBB\\nCCC' | teip \-e 'echo " 3:testtest"' AAA BBB [CCC] .fi .RE .PP Technically, the first captured group in the regular expression \fB\fC^\\s*([0\-9]+)\fR is interpreted as a line number. \fB\fC\-e\fR will also recognize multiple numbers if the pipeline provides multiple lines of numbers. .PP .RS .nf $ echo \-e 'AAA\\nBBB\\nCCC\\nDDD\\nEEE\\nFFF' | teip \-e 'seq 1 2 10' \-\- sed 's/. /@/g' @@@ BBB @@@ DDD @@@ FFF .fi .RE .PP Note that the order of the numbers must be in ascending order. .PP The pipeline obtains identical standard input as \fB\fCteip\fR\&. The following command is a \fB\fCgrep\fR command that prints \fBthe line numbers of the line containing the string "CCC" and the two lines after it\fP\&. .PP .RS .nf $ echo \-e 'AAA\\nBBB\\nCCC\\nDDD\\nEEE\\nFFF' | grep \-n \-A 2 CCC 3:CCC 4\-DDD 5\-EEE .fi .RE .PP If you give this command to \fB\fC\-e\fR, you can punch holes in \fBthe line containing the string "CCC" and the two lines after it\fP\&. .PP .RS .nf $ echo \-e 'AAA\\nBBB\\nCCC\\nDDD\\nEEE\\nFFF' | teip \-e 'grep \-n \-A 2 CCC' AAA BBB [CCC] [DDD] [EEE] FFF .fi .RE .PP GNU \fB\fCsed\fR has \fB\fC=\fR, which prints the line number being processed. Below is an example of how to drill from the line containing "BBB" to the line containing "EEE". .PP .RS .nf $ echo \-e 'AAA\\nBBB\\nCCC\\nDDD\\nEEE\\nFFF' | teip \-e 'sed \-n "/BBB/,/EEE/="' AAA [BBB] [CCC] [DDD] [EEE] FFF .fi .RE .PP Of course, similar operations can also be done with \fB\fCawk\fR\&. .PP .RS .nf $ echo \-e 'AAA\\nBBB\\nCCC\\nDDD\\nEEE\\nFFF' | teip \-e 'awk "/BBB/,/EEE/{print NR}"' .fi .RE .PP The following is an example of combining the commands \fB\fCnl\fR and \fB\fCtail\fR\&. You can only make holes in the last three lines of input. .PP .RS .nf $ echo \-e 'AAA\\nBBB\\nCCC\\nDDD\\nEEE\\nFFF' | teip \-e 'nl \-ba | tail \-n 3' AAA BBB CCC [DDD] [EEE] [FFF] .fi .RE .PP The \fB\fC\-e\fR argument is a single string. Therefore, pipe \fB\fC|\fR and other symbols can be used as it is. .SH EXAMPLES .PP Replace 'WORLD' to 'EARTH' on lines containing 'HELLO' .PP .RS .nf $ cat file | teip \-g HELLO \-\- sed 's/WORLD/EARTH/' .fi .RE .PP Edit 2nd field of the CSV file .PP .RS .nf $ cat file.csv | teip \-\-csv \-f 2 \-\- tr a\-z A\-Z .fi .RE .PP Edit 2nd, 3rd and 4th fields of TSV file .PP .RS .nf $ cat file.tsv | teip \-D '\\t' \-f 2\-4 \-\- tr a\-z A\-Z .fi .RE .PP Convert timestamps in /var/log/secure to UNIX time .PP .RS .nf $ cat /var/log/secure | teip \-c 1\-15 \-\- date \-f\- +%s .fi .RE .PP Edit lines containing 'hello' and the three lines before and after it .PP .RS .nf $ cat access.log | teip \-e 'grep \-n \-C 3 hello' \-\- sed 's/./@/g' .fi .RE .SH SEE ALSO .SS Manual pages .PP .BR cut (1), .BR sed (1), .BR awk (1), .BR grep (1) .SS Full documentation .PP \[la]https://github.com/greymd/teip\[ra] .SS Regular expression .PP \[la]https://docs.rs/regex/\[ra] .SS Regular expression (Oniguruma) .PP \[la]https://github.com/kkos/oniguruma/blob/master/doc/RE\[ra] .SS RFC 4180: Common Format and MIME Type for Comma\-Separated Values (CSV) Files .PP \[la]https://www.rfc-editor.org/rfc/rfc4180\[ra] .SH AUTHOR AND COPYRIGHT .PP Copyright (c) 2023 Yamada, Yasuhiro \[la]yamada@gr3.ie\[ra] Released under the MIT License.