view release on metacpan or  search on metacpan

script/ptp  view on Meta::CPAN

Send all output of the program to the specified file. The file is created if
needed and its content is deleted at the beginning of the execution of the
program. So the file cannot be used as an input to the program.

You can only specify a single output file.

=item B<-a> I<output_file>, B<--append>

Same as B<--output> but append to the specified file instead of deleting its
content.

=item B<-i>, B<--in-place>

Write the output of the pipeline for each input file in-place into these files.
This cannot be used when reading from the standard input or when B<--merge> is
used in the pipeline.

=item B<-R>, B<--recursive>

Allow to specify directories instead of files on the command line. The entire
content of the specified directories will be processed, as if all the files had
been mentioned on the command line.

=item B<--input-filter> I<code>

When recursively expending a directory passed on the command line (when the
B<-R> option is active), then execute the given Perl code (that will typically
be just a regex match like I</foo.*bar/>). Only file names for which the code
returns a true value are kept. The complete file name is passed to the code in
the default B<$_> variable. You can view this option in action in the
L</EXAMPLES> sections

This option only applies on files recursively expended from a directory passed
on the command line. It does not apply on files that are explicitly listed. In
particular, this option does not apply on files that are expended by a shell
glob. It derives that this option is useless unless B<-R> is specified too.

All the functions from the Perl L<File::Spec::Functions> module are available to
the code being executed (e.g. the B<splitpath> function).

=item B<--input-encoding> I<encoding> (alias B<--in-encoding>)

Specify the encoding used to read the input files. The default is UTF-8.

=item B<--output-encoding> I<encoding> (alias B<--out-encoding>)

Specify the encoding used to write the output. The default is UTF-8.

=item B<--input-separator> I<separator> (alias B<--in-separator>)

Specify the separator that is used to split the lines in the input files. The
default is "\n" (LF). Note that currently, on windows, "\r\n" (CRLF) characters
in input files will be automatically transformed into "\n" characters.

=item B<--output-separator> I<separator> (alias B<--out-separator>)

Specify the separator that is added in-between lines in the output. The
default is "\n" (LF). Note that currently, on Windows, this is automatically
transformed into an "\r\n" (CRLF) sequence.

=item B<--eol>, B<--preserve-input-separator>

Keep the input separators in the content of each line. It is then your
responsibility to preserve (or to change) this separator when the files are
processed.

Setting this flag also sets the B<--output-separator> to the empty string. This
can be overridden if needed by passing that flag after the B<--eol> one
(this would result in each line having their initial end of line separator plus
the one specified for the output (unless the initial one is removed during the
processing).

=item B<--fix-final-separator>

If set, then the final line of each file is always terminated by a line
separator in the output (as specified by B<--output-separator>), even if it
did not have one in the input.

=item B<-0>

Set the B<--input-separator> to the null character (B<\000>) and the
B<--output-separator> to the empty string. This result in having each file read
entirely in a single logical line.

=item B<--00>

Set the B<--output-separator> to the null character (B<\000>). This produces
output compatible with B<-0> option of C<xargs>.

=item B<-h>, B<--help>

Print this help message and exit. Note: the help message will be much improved
if you have the B<perldoc> program installed (sometimes from a B<perl-doc>
package).

=item B<--cheat>

Print the cheat sheet content and exit.

=item B<--version>

Print the version of the program and exit.

=item B<-d>, B<--debug>

Send debug output on the execution of the program to the standard error output.
If you specify this option a second time, then the final output itself will be
modified to contain some debugging information too (sent on the standard output
or in any file that you specify as the output, not to the standard error).

=item B<--abort>

Abort the execution of the program after all argument have been parsed but
before the actual execution of the program. This is most useful with B<--debug>
to check that the arguments are interpreted as expected.

=item B<--preserve-perl-env>

By default, the Perl environment accessible to the commands executing user
supplied code (B<--perl>, B<-n>, B<--filter>, etc.) is reset between each input
file. When this option is passed, the environment is preserved between the
files.

=item B<--safe> [I<n>]

Switch to a safer mode of evaluating user supplied Perl code (from the command
line). The default mode (equivalent to passing B<--safe 0>) is the fastest. But
some specifically crafted user supplied code could break the behavior of the

script/ptp  view on Meta::CPAN

This variable contains the index of the file currently being processed (starting
at 1 for the first file).

=head3 B<ss> I<start>[, I<len>[, I<$var>]]

Returns the sub-string of the given I<$var>, starting at position I<start> and
of length I<len>. If I<$var> is omitted, uses the default I<$_> variable. If
I<len> is omitted or I<0>, reads the entire remaining of the string.

If I<start> is negative, starts at the end of the string. If I<len> is negative,
removes that much characters from the end of the string.

This is quite similar to the built-in B<substr> function except that B<ss> will
returns the empty-string instead of I<undef> if the specified sub-string is
outside of the input.

=head3 B<pf> I<format>[, I<args...>]

Formats the given I<args> using the I<format> string (following the standard
B<printf> format) and stores the result in the default B<$_> variable.

=head3 B<spf> I<format>[, I<args...>]

Formats the given I<args> using the I<format> string (following the standard
B<printf> format) and returns the results.

=head1 EXAMPLES

A default invocation of the program without arguments other than file names will
behave as the B<cat> program, printing the concatenated content of all its input
files:

  ptp file1 file2 file3

This next example replaces each line with the output of the B<sprintf> function
which, here, will prefix the line number to each line (similar to the B<--nl>
command). This example also demonstrates that a variable can be re-used across
the lines of an input (the B<$i> variable), but that it is reset between each
input. Using the variables and functions described in L</PERL ENVIRONMENT>:

  ptp file1 file2 -n 'spf("% 5d  %s", ++$i, $_)'

Same as the example above, but does not number empty lines (this is the default
behavior of the GNU B<nl> util). Also this uses the B<pf> function that modifies
the B<$_> variable, so it can be used directly with the B<--perl> command
instead of the B<-n> one:

  ptp file -p 'pf("%5d  %s", ++$i, $_) if $_'

Print a sorted list of the login name of all users:

  ptp /etc/passwd -F : --cut 1 --sort

Number all the lines of multiple inputs, as if they were a single file:

  ptp file1 file2 -m --nl

Join lines that end with an B<=> character with the next line. The B<chomp> Perl
command removes the end-of-line character from the current line (which was there
due to the usage of the B<--eol> flag). In this example, that command is applied
only if the line matches the given regex (which search for the B<=> character
at the end of the line):

  ptp file --eol -p 'chomp if /=$/'

Output the number of lines of comment in all the source files in a given
directory, filtering only the files that match some extensions. The
B<--input-filter> option ensures that only source file are used inside the given
directory. The B<-g> (B<--grep>) command keeps only the lines that start with a
C-style comment (or spaces followed by a comment), then the B<--lc> command
(B<--line-count>), replaces the entire content of the file with just the number
of lines that it contains (the number of comments at that point). Finally, the
B<--pfn> command (B<--prefix-file-name>) adds the name of the current file as
the first line of each file, and B<--pivot> joins the two lines of each file
(the file name and the number of lines):

  ptp dir -R --input-filter '/\.(c|h|cc)$/' -g '^\s*//' --lc --pfn --pivot

Find all the occurrences of a given regex in a file and print them, one per line.
The regex can contain capture groups (using parenthesis). In that case only the
content of the capture group is kept:

  ptp file -n 'join(",", /regex/g)' --anti-pivot --fix-final-separator

=head1 ENVIRONMENT

Some environment variables can affects default options of the program when they
are set.

=over 4

=item PTP_DEFAULT_CASE_INSENSITIVE

Setting this variable to B<1> means the the B<-I> flag is in effect at the
beginning of the parsing of the command line arguments. Setting the variable to
B<0> gives the default behavior (as if B<-S> was passed).

=item PTP_DEFAULT_QUOTE_REGEX

Setting this variable to B<1> means the the B<-Q> flag is in effect at the
beginning of the parsing of the command line arguments. Setting the variable to
B<0> gives the default behavior (as if B<-E> was passed).

=item PTP_DEFAULT_INVERSE_MATCH

Setting this variable to B<1> means that the B<-V> flag is in effect at the
beginning of the parsing of the command line arguments. Setting the variable to
B<0> gives the default behavior (as if B<-N> was passed).

=item PTP_DEFAULT_LOCAL_MATCH

Setting this variable to B<1> means the the B<-L> flag is in effect at the
beginning of the parsing of the command line arguments. Setting the variable to
B<0> gives the default behavior (as if B<-G> was passed).

=item PTP_DEFAULT_REGEX_ENGINE

Setting this variable allows to override the default regex engine used by the
program. That variable can take the same values as the B<--re> flag.

=item PTP_DEFAULT_FATAL_ERROR

Setting this variable to B<1> means that the B<-X> flag is in effect at the
beginning of the parsing of the command line arguments. Setting the variable to