view release on metacpan or  search on metacpan

script/ptp  view on Meta::CPAN

=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
is in the B<$_> variable. That variable can be modified to change the content of
the line. If the variable is undefined then the line is removed.

Note that if you introduce new-line characters (or whatever characters specified
by the B<--input-separator> flag), the resulting line will not be split again by
the program and will be considered as a single line for the rest of the
pipeline.

See also the L</PERL ENVIRONMENT> section for details on variables and functions
available to your Perl code.

An error in the Perl code will result in a message printed to the standard
output but the processing will continue. The current line may or may not be
modified.

=item B<-n> I<code>

Execute the given perl code for each line of the input. Replace each line with
the return value from the code. The input line is in the B<$_> variable. If the
return value is B<undef> then the line is removed.

See the note on new-line characters given in the description of the B<--perl>
command.

An error in the Perl code will result in a message printed to the standard
output but the processing will continue. The current line will not be modified.

=item B<-f> I<code>, B<--filter>

Execute the given perl code for each line of the input and keep the lines where
the return value from the code is true. The input line is in the the B<$_>
variable. Note that you can modify that variable, but you probably should avoid
doing it.

An error in the Perl code will result in a message printed to the standard
output but the processing will continue. The current line will not be removed.

=item B<-e> I<code>, B<--execute>

Execute the given code. As other command, this will be executed once per input
file being processed. This command can be used to initialize variables or
functions used in B<--perl> or B<-n> commands.