Add a cheat sheet POD and improve the main documentation.

.aspelldict

@@ -1,4 +1,4 @@
-personal_ws-1.1 en 112 
+personal_ws-1.1 en 119 
 AliasVar
 CMD
 CPAN
@@ -13,6 +13,7 @@ LF
 MERCHANTABILITY
 MarkersArray
 NONINFRINGEMENT
+NUL
 PCRE
 PODNAME
 PTP
@@ -24,6 +25,8 @@ ProhibitMagicNumbers
 ProhibitNoWarnings
 ProhibitOneArgSelect
 ProhibitStringyEval
+RO
+RW
 ReadOnlyVar
 Readonly
 RequireArgUnpacking
@@ -45,6 +48,8 @@ cmd
 cmp
 coderef
 comparator
+cpanm
+cpanminus
 csv
 dir
 dirs
@@ -60,6 +65,7 @@ expressivity
 fh
 filepath
 fn
+gcc
 globaluniqstr
 gu
 guniq
@@ -99,6 +105,7 @@ sublicense
 subprocess
 subst
 substr
+sudo
 tac
 tempfile
 tsv

.gitignore

@@ -21,3 +21,6 @@
 /App-PTP-*/
 
 # End of the template. You can add custom content below this line.
+
+/ptp_cheat_sheet.html
+/ptp_cheat_sheet.pdf

Changes

@@ -1,5 +1,8 @@
 Revision history for Perl distribution App-PTP
 
+1.16 - ??
+ - Add a "cheat sheet" POD to the distribution.
+
 1.15 - 2024-09-29
  - Remove a remaining smartmatch usage from our benchmarks.
 

MANIFEST.SKIP

@@ -32,3 +32,5 @@
 .*\.bak
 
 # End of the template. You can add custom content below this line.
+
+^ptp_cheat_sheet\..*$

Makefile.PL

@@ -134,3 +134,21 @@ MAKE_FRAGMENT
 # add to the generated Makefile.
 
 # End of the template. You can add custom content below this line.
+
+sub postamble {
+  return <<"MAKE_FRAGMENT";
+cheat_sheet: ptp_cheat_sheet.html ptp_cheat_sheet.pdf
+
+ptp_cheat_sheet.pdf: lib/App/PTP/Cheat_Sheet.pod
+\tpod2pdf --left-margin 30 --right-margin 30 --top-margin 36 --bottom-margin 36 --title="PTP Cheat Sheet" --noheader --nofooter \$< | pdfjam --landscape --nup 2x1 --outfile \$@ 2>/dev/null
+
+ptp_cheat_sheet.html: lib/App/PTP/Cheat_Sheet.pod
+\tpod2html --noindex --title="PTP Cheat Sheet" \$< > \$@
+
+clean_cheat_sheet:
+\trm -f ptp_cheat_sheet.pdf ptp_cheat_sheet.html
+
+clean:: clean_cheat_sheet
+
+MAKE_FRAGMENT
+}

lib/App/PTP/Cheat_Sheet.pod

@@ -0,0 +1,218 @@
+=pod
+
+=head1 PTP Cheat Sheet
+
+=head2 SYNOPSIS
+
+Install with:
+
+  sudo apt-get install perl cpanminus perl-doc build-essential
+  # or
+  sudo yum install perl Perl-App-cpanminus perl-doc gcc make
+
+  sudo cpanm App::PTP -n -L /usr/local --man-pages --install-args \
+    'DESTINSTALLBIN=/usr/local/bin'
+
+Run with:
+
+  ptp file1 file2 ... [--grep re] [--substitute re subst] ... [-o out]
+
+=head2 INPUT FILES
+
+Input files can appear anywhere on the command line and are processed in the
+order in which they are given.
+
+=over 8
+
+=item C<F<filename>> (anywhere in the command line, not starting with a C<->)
+
+=item C<-> (reads from stdin)
+
+=item C<-- F<filename> ...> (for any filename)
+
+=back
+
+=head2 PIPELINE COMMANDS
+
+Pipeline commands are applied, in order, to all the input files.
+
+=over 8
+
+=item B<--g> I<regex> (B<--grep>), B<-s> I<regex> I<string> (B<--substitute>)
+
+=item B<--p> I<code> (B<-perl>): read and write C<$_> to modify the file
+
+=item B<-n> I<code>: read from C<$_>, write the return values
+
+=item B<-f> I<code> (B<--filter>): return I<true> to keep the line
+
+=item B<-e> I<code> (B<--execute>): execute once per input file
+
+=item B<-l> I<path> (B<--load>): execute the given file, once per input file
+
+=item B<-M> I<module>: load the given module
+
+=item B<--sort>, B<--ns> (B<--numeric-sort>), B<--ls>, (B<--locale-sort>),
+B<--cs> I<code> (B<--custom-sort>)
+
+=item B<-u> (B<--unique>), B<--gu> (B<--global-unique>)
+
+=item B<--head> [I<n>], B<--tail> [I<n>], B<--reverse> (B<--tac>), B<--shuffle>
+
+=item B<--eat>: discard the content of the file
+
+=item B<--ml> I<code> (B<--mark-line>): set the marker for the line with the
+return value
+
+=item B<--clear-markers>, B<--set-all-markers>
+
+=item B<--delete-marked>, B<--delete-before>, B<--delete-after>,
+B<--delete-at-offset> I<offset>
+
+=item B<--insert-before> I<string>, B<--insert-after> I<string>,
+B<--insert-at-offset> I<offset> I<string>: insert interpolated text next to marked
+lines (offset I<0> is just after)
+
+=item B<--cut> I<N>,I<N>,...: select fields according to B<-F> and concatenate
+them with B<-P>
+
+=item B<--paste> I<file>: paste with B<-P> line by line with the current content
+
+=item B<--pivot>: turn the file into a single line with B<-P>
+
+=item B<--anti-pivot>: split all lines according to B<-F>
+
+=item B<--transpose>: transpose lines and columns using B<-F> and B<-P>
+
+=item B<--nl> (B<--number-lines>), B<--pfn> (B<--prefix-file-name>)
+
+=item B<--fn> (B<--file-name>), B<--lc>, B<--line-count>: replace the content of
+the file
+
+=item B<-m> (B<--merge>): merge all the files in a single one
+
+=item B<--tee> I<filename>: duplicate the output
+
+=item B<--shell> I<command>: sends the content as input to the command
+
+=back
+
+=head2 PROGRAM BEHAVIOR
+
+Global option for the program execution.
+
+=over 8
+
+=item B<-o> I<output_file> (B<--output>), B<-a> I<output_file> (B<--append>),
+B<-i> (B<--in-place>): by default output to standard output
+
+=item B<-R>, B<--recursive>, B<--input-filter> I<code>: expand directories,
+optionally filter input files
+
+=item B<--input-encoding> I<encoding>, B<--output-encoding> I<encoding>: default
+is UTF-8
+
+=item B<--input-separator> I<separator>, B<--output-separator> I<separator>:
+default is C<\n>
+
+=item B<--eol> (B<--preserve-input-separator>), B<--fix-final-separator>
+
+=item B<-0>: set B<--input-separator> to C<NUL> and B<--output-separator> to the
+empty string.
+
+=item B<--00>: set B<--output-separator> to the C<NUL>, useful with C<xargs -0>
+
+=item B<-h> (B<--help>), B<--version>: remember to have B<perldoc> installed
+
+=item B<-d> (B<--debug>), B<--abort>
+
+=item B<--preserve-perl-env>: keep environment across files
+
+=item B<--safe> [I<n>]: default is I<0>, strictest is I<2>
+
+=back
+
+=head2 PIPELINE MODES
+
+Options for the pipeline commands coming after them. Most modes have a reverse
+mode to return to the default.
+
+=over 8
+
+=item B<-I> (B<--case-insensitive>), B<-S> (B<--case-sensitive>): mode for any
+I<regex> argument, B<-S> is the default
+
+=item B<-Q> (B<--quote-regexp>), B<-E> (B<--end-quote-regexp>): disable
+interpolation in any I<regex>, I<string>, I<filename> or I<command> argument,
+B<-E> is the default
+
+=item B<-V> (B<--inverse-match>), B<-N> (B<--normal-match>): inverse behavior of
+B<--grep> and B<--filter>
+
+=item B<-L> (B<--local-match>), B<-G> (B<--global-match>): apply B<--substitute>
+once per line or as much as possible (this is the default)
+
+=item B<-C> I<code> (B<--comparator>): for B<--sort>, default is C<$a cmp $b>
+
+=item B<-F> I<regex> (B<--input-field-spec>): how to split fields, default is
+B<\s*,\*s|\t>
+
+=item B<-P> I<string> (B<--output-field-spec>): how to paste fields, default is
+a tab
+
+=item B<--default>, B<--bytes>, B<--csv>, B<--tsv>, B<--none>: set the B<-F> and
+B<-P> flags
+
+=item B<--sq> I<string> (B<--single-quote-replacement>),
+B<--dq> I<string> (B<--double-quote-replacement>), B<--ds> I<string>
+(B<--dollar-sigil-replacement>): replace the given character or string by C<'>,
+C<">, or C<$> in all I<code> arguments
+
+=item B<--re> I<engine>, B<--regex-engine>: use the specified regex engine (e.g.
+I<RE2>, I<PCRE>, I<TRE>, I<GNU>, etc.) if installed
+
+=item B<-X> (B<--fatal-error>), B<--ignore-error>: dies on error in B<--perl>,
+B<-n> and B<--filter>
+
+=back
+
+=head2 PERL ENVIRONMENT
+
+Variables and functions available to I<code> arguments as well as I<regex>,
+I<string>, I<filename>, and I<command> ones (unless B<-Q> has been passed).
+
+=over 8
+
+=item B<$_>: current line content (I<RW>)
+
+=item B<$f>, B<$F>: current file name, current absolute file name (I<RO>)
+
+=item B<$n>: current line number (same as standard B<$.>)  (I<RO>)
+
+=item B<$N>: number of lines in the current file (I<RO>)
+
+=item B<$m>: marker of the current line (I<RW>)
+
+=item B<@m>: markers for all the lines, current line is at index 0 (I<RW>)
+
+=item B<$I>: 1-based index of the file being processed (I<RW>)
+
+=item B<ss> I<start>[, I<len>[, I<$var>]]: like C<substr> but returns C<''>
+instead of C<undef>.
+
+=item B<pf> I<format>[, I<args...>]: like C<$_ = sprintf I<format>, I<arg...>>
+
+=item B<spf> I<format>[, I<args...>]: like C<sprintf>
+
+=back
+
+=head2 AUTHOR AND LICENCE
+
+Copyright 2019-2024 Mathias Kende (L<mailto:[email protected]>).
+
+This program is distributed under the MIT (X11) License:
+L<http://www.opensource.org/licenses/mit-license.php>
+
+See more in the full documentation at L<https://metacpan.org/pod/ptp>.
+
+=cut