filter-heredoc - Search and filter embedded here documents
filter-heredoc [--debug] [--interactive] [--list] [--list-unique] [--match=delimiter] [--quiet] [--rules] [--syntax=rule] [--version] input
filter-heredoc search and extracts here documents from POSIX IEEE Std 1003.1-2008 compliant shell scripts and is the front-end for Filter::Heredoc.
filter-heredoc input is given by the input text file.
If input isn't given,
it defaults to
The extracted heredoc is written to
Several files can be processed in the same filter-heredoc invocation by providing multiple of input files or wild cards on the command line.
--list and --list-unique can be used to find what delimiters exist in the input file. When --match=delimiter is specified, only lines that match the delimiter region of the here document is printed.
Perl and other scripting languages have derived a similar syntax as POSIX but is at the same time different in many details.
--syntax=rule adds rules to enhance the here document extraction. To list available rules, use --rules. Perls simple to use markup documentation language (i.e. POD) can be embedded in shell scripts in the form of a here document (SEE ALSO).
The option --quiet removes printed file information when e.g. the output is piped for spell checking in an external program such as hunspell, aspell or ispell.
Prints out the complete file with each line prefixed with a label code to indicate what context filter-heredoc has assigned it to.
S] Source script line which is outside the here document region.
I] Ingress line (i.e. the line with the opening delimiter).
H] Here document line which is printed (inside region).
E] The line which have the closing delimiter.
Print out usage information.
Enter interactive mode. This is only used to debug filter-heredoc internals. To terminate this mode use Ctrl-D (*nix-like systems).
List all delimiters in the input file.
List all unique delimiters in the input file.
Print only the here documents that is enclosed by the specified delimiter.
filter-heredoc prepend the file name and the line number before the here document line is printed,
for each file processed.
This option suppress this information to reduce screen clutter or when piping
STDOUT to an external program.
Rules can be added to enhance extraction of here documents.
pod is a helper rule when POD is embedded in shell scripts
If the word
none is given as a rule all rules are deactivated.
pod is enabled by default.
Perl scripts with embedded here documents that uses a near POSIX like coding constructs may print correct.
perl is planned to address Perls variations in syntax.
Display the version information.
If filter-heredoc fails with fatal errors, see Filter::Heredoc for information about what those errors might mean. Please, improve filter-heredoc by sending a Bug report and how to reproduce the error.
Prints the here document from files:
filter-heredoc *.sh filter-heredoc --quiet < file.sh
Spell checking here documents with e.g. ispell:
cat file.sh | filter-heredoc --quiet | ispell -l
To spell check when multiple delimiters exist, find the delimiters:
filter-heredoc --list file.sh
Now match the script verbatim output with option --match (-m):
filter-heredoc -q -m END_MAIL file.sh | hunspell -d sv_SE -l
If POD text have been embedded it can be extracted with podspell:
podspell diskusage | aspell list -l en podspell diskusage | ispell -a | grep \&
<bkron at cpan.org>
Please report any bugs or feature requests to http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Filter-Heredoc or at
<bug-filter-heredoc at rt.cpan.org>.
The IEEE Std 1003.1-2008 standards can be found here: http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html
Filter::Heredoc::Cookbook discuss e.g. how to embed POD as here documents in shell scripts to carry their own documentation.
Copyright 2011-12, Bertil Kronlund
This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.
See http://dev.perl.org/licenses/ for more information.
THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
The version of filter-heredoc described by this manual page is Version 0.02.