view release on metacpan or  search on metacpan

script/ptp  view on Meta::CPAN

Keep only the given fields of each line (by default fields can be separated by
tabs or comma, they will be separated by tabs in the output, this can be
overridden with B<-F> and B<-P>).

=item B<--paste> I<filename>

Join each line of the current file with the matching line of the given filename.

=item B<--tee> I<filename>, B<--shell> I<command>

Write the content of the file to the give filename or send it to the given shell
command.

=item B<-o> I<filename>, B<-a> I<filename>, B<-i>

Write the output to the given file (instead of the standard output), or append
to the file, or write it in-place in the input files.

=back

=head1 DESCRIPTION

B<PTP> is a versatile and expressive text processor program. The core features
that it tries to provide are the following:

=over 8

=item * Provide B<grep>, B<sed>-like and other operations with a coherent
regular expression language (B<grep> has a B<-P> flag but B<sed> has nothing of
the like).

=item * Provide a powerful input/output files support, that is lacking when
using vanilla-Perl one-liner (recursion in directories, output in-place with
optional backups, etc.).

=item * Pipelining of multiple operations on multiple files (using a pipeline
made of several standard tool usually makes it difficult to process several
input files at once).

=back

See examples of B<PTP> in action below, in the L</EXAMPLES> section.

=head1 OPTIONS

All options are case sensitive and can be abbreviated down to uniqueness.
However, it is recommended to use only the variants that are documented here, in
case options are introduced in the future that render some abbreviations
ambiguous. Unless specified otherwise, the arguments to all the options are
mandatory (for brevity they are usually documented only on the short form of the
options, but they are mandatory for the long form too).

The program expects four different kinds of arguments (all described below).
They can be mixed in any order that you want. However, for some of these
arguments the order is actually meaningful (e.g. the commands are applied in the
order in which they are specified):

=over 4

=item * L</INPUT FILES> can be specified anywhere on the command line, except
between another flag and its argument.

=item * L</PIPELINE COMMANDS>, which describe what operations should be executed
on each input files. The commands are all executed, in the order in which they
are specified on the command line, and applied to all input files.

=item * L</PROGRAM BEHAVIOR> options, set global options for the program. These
flags can appear multiple times on the command line, but only the last occurrence
will be used. To avoid mistakes, the program will stop with an error when some
of these flags are specified more than once.

=item * L</PIPELINE MODES> flags, which modify how the pipeline commands behave.
These flags have effect starting at the point where they are specified for all
the pipeline commands that are specified after them. Usually, each of these
flags will have an opposite flag that allows to revert to the default behavior
if needed.

=back

=head2 INPUT FILES

Input files can be specified anywhere on the command line. They will be
processed in the order in which they appear but their position relative to other
arguments is ignored. Any command line argument that does not start with a B<->
is considered to be a filename (unless it is an argument to a preceding flag).

A single B<-> alone indicates that the standard input will be processed, this
can be mixed with reading other files. If no input files at all are specified
then the standard input is processed.

Finally, you can stop the processing of the command line arguments by
specifying a B<--> option. In that case, all remaining arguments will be
considered as input files, even if they start with a B<->.

=head2 PIPELINE COMMANDS

The options in this section specify what processing to apply on the input files.
For each input file, all of these commands are applied in the order in which
they are specified, before the next file is processed.

If the B<--merge> command is used, then all the input files are merged  at that
point and all the content processed up to that point is considered as a single
input for the rest of the pipeline (this is described below).

Many of the commands from this list are affected by the flags described in
L</PIPELINE MODES>. An overview of the most important one is given in the
description of the affected commands.

=over 8

=item B<--g> I<regex>, B<--grep>

Filter each input to keep only the lines that match the given regular
expression. That expression cannot have delimiters (e.g. /foo/) so, if you
want to pass options to the regex, you need to use the group syntax (e.g.
(?i)foo).

If you use parenthesis, you probably want to enclose the expression in single
quotes, to prevent the shell from interpreting them.

This command is much faster then manually giving a match operation to the
B<--filter> command, because the code does not need to be escaped.

This operation can be made case-insensitive with the B<-I> flag, inverted with
B<-V> and the regex can be interpreted as an exact string with B<-Q>.

=item B<-s> I<regex> I<string>, B<--substitute>

Replace all matches of the given regular expression by the given substitution
text on each line of the input. The substitution string is evaluated like a
Perl string, so it can contain references to capture group in the regular
expression using the B<$1>, B<$2>, etc. syntax.

In addition to the B<-I> and B<-Q> flags that also apply to this operation (see
the description of the B<--grep> command), this command can be made to match at
most once per line with B<-L>.

=item B<--p> I<code>, B<-perl>

Execute the given perl code for each line of the input. The content of the line