/ 
App-Greple-tee-1.01
River stage zero No dependents
/ App::Greple::tee

NAME

App::Greple::tee - module to replace matched text by the external command result

SYNOPSIS

greple -Mtee command -- ...

VERSION

Version 1.01

DESCRIPTION

Greple's -Mtee module sends matched text part to the given filter command, and replace them by the command result. The idea is derived from the command called teip. It is like bypassing partial data to the external filter command.

Filter command follows module declaration (-Mtee) and terminates by two dashes (--). For example, next command call command tr command with a-z A-Z arguments for the matched word in the data.

greple -Mtee tr a-z A-Z -- '\w+' ...

Above command convert all matched words from lower-case to upper-case. Actually this example itself is not so useful because greple can do the same thing more effectively with --cm option.

By default, the command is executed as a single process, and all matched data is sent to the process mixed together. If the matched text does not end with newline, it is added before sending and removed after receiving. Input and output data are mapped line by line, so the number of lines of input and output must be identical.

Using --discrete option, individual command is called for each matched text area. You can tell the difference by following commands.

greple -Mtee cat -n -- copyright LICENSE
greple -Mtee cat -n -- copyright LICENSE --discrete

Lines of input and output data do not have to be identical when used with --discrete option.

OPTIONS

--discrete

Invoke new command individually for every matched part.

--bulkmode

With the <--discrete> option, each command is executed on demand. The <--bulkmode> option causes all conversions to be performed at once.

--crmode

This option replaces all newline characters in the middle of each block with carriage return characters. Carriage returns contained in the result of executing the command are reverted back to the newline character. Thus, blocks consisting of multiple lines can be processed in batches without using the --discrete option.

--fillup

Combine a sequence of non-blank lines into a single line before passing them to the filter command. Newline characters between wide width characters are deleted, and other newline characters are replaced with spaces.

--squeeze

Combines two or more consecutive newline characters into one.

-Mline --offload command

teip(1)'s --offload option is implemented in the different module -Mline.

greple -Mtee cat -n -- -Mline --offload 'seq 10 20'

You can also use the line module to process only even-numbered lines as follows.

greple -Mtee cat -n -- -Mline 2::2

LEGACIES

The --blocks option is no longer needed now that the --stretch (-S) option has been implemented in greple. You can simply perform the following.

greple -Mtee cat -n -- --all -SE foo

It is not recommended to use --blocks as it may be deprecated in the future.

--blocks

Normally, the area matching the specified search pattern is sent to the external command. If this option is specified, not the matched area but the entire block containing it will be processed.

For example, to send lines containing the pattern foo to the external command, you need to specify the pattern which matches to entire line:

greple -Mtee cat -n -- '^.*foo.*\n' --all

But with the --blocks option, it can be done as simply as follows:

greple -Mtee cat -n -- foo --blocks

With --blocks option, this module behave more like teip(1)'s -g option. Otherwise, the behavior is similar to teip(1) with the -o option.

Do not use the --blocks with the --all option, since the block will be the entire data.

WHY DO NOT USE TEIP

First of all, whenever you can do it with the teip command, use it. It is an excellent tool and much faster than greple.

Because greple is designed to process document files, it has many features that are appropriate for it, such as match area controls. It might be worth using greple to take advantage of those features.

Also, teip cannot handle multiple lines of data as a single unit, while greple can execute individual commands on a data chunk consisting of multiple lines.

EXAMPLE

Next command will find text blocks inside perlpod(1) style document included in Perl module file.

greple --inside '^=(?s:.*?)(^=cut|\z)' --re '^([\w\pP].+\n)+' tee.pm

You can translate them by DeepL service by executing the above command convined with -Mtee module which calls deepl command like this:

greple -Mtee deepl text --to JA - -- --fillup ...

The dedicated module App::Greple::xlate::deepl is more effective for this purpose, though. In fact, the implementation hint of tee module came from xlate module.

EXAMPLE 2

Next command will find some indented part in LICENSE document.

greple --re '^[ ]{2}[a-z][)] .+\n([ ]{5}.+\n)*' -C LICENSE

  a) distribute a Standard Version of the executables and library files,
     together with instructions (in the manual page or equivalent) on where to
     get the Standard Version.

  b) accompany the distribution with the machine-readable source of the Package
     with your modifications.

You can reformat this part by using tee module with ansifold command:

greple -Mtee ansifold -rsw40 --prefix '     ' -- --discrete --re ...

  a) distribute a Standard Version of
     the executables and library files,
     together with instructions (in the
     manual page or equivalent) on where
     to get the Standard Version.

  b) accompany the distribution with the
     machine-readable source of the
     Package with your modifications.

The --discrete option will start multiple processes, so the process will take longer to execute. So you can use --separate '\r' option with ansifold which produce single line using CR character instead of NL.

greple -Mtee ansifold -rsw40 --prefix '     ' --separate '\r' --

Then convert CR char to NL after by tr(1) command or some.

... | tr '\r' '\n'

EXAMPLE 3

Consider a situation where you want to grep for strings from non-header lines. For example, you may want to search for Docker image names from the docker image ls command, but leave the header line. You can do it by following command.

greple -Mtee grep perl -- -Mline -L 2: --discrete --all

Option -Mline -L 2: retrieves the second to last lines and sends them to the grep perl command. The option --discrete is required because the number of lines of input and output changes, but since the command is only executed once, there is no performance drawback.

If you try to do the same thing with the teip command, teip -l 2- -- grep will give an error because the number of output lines is less than the number of input lines. However, there is no problem with the result obtained.

INSTALL

CPANMINUS

$ cpanm App::Greple::tee

SEE ALSO

App::Greple::tee, https://github.com/kaz-utashiro/App-Greple-tee

https://github.com/greymd/teip

App::Greple, https://github.com/kaz-utashiro/greple

https://github.com/tecolicom/Greple

App::Greple::xlate

BUGS

The --fillup option will remove spaces between Hangul characters when concatenating Korean text.

AUTHOR

Kazumasa Utashiro

LICENSE

Copyright © 2023-2024 Kazumasa Utashiro.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.