The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

filter-heredoc - Search and filter embedded here documents

SYNOPSIS

filter-heredoc [--debug] [--interactive] [--list] [--list-unique] [--match=delimiter] [--quiet] [--rules] [--syntax=rule] [--version] input

filter-heredoc --help

DESCRIPTION

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 STDIN. The extracted heredoc is written to STDOUT. 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.

OPTIONS

-d, --debug

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.

-h, --help

Print out usage information.

-i|-, --interactive

Enter interactive mode. This is only used to debug filter-heredoc internals. To terminate this mode use Ctrl-D (*nix-like systems).

-l, --list

List all delimiters in the input file.

-u, --list-unique

List all unique delimiters in the input file.

-m delimiter, --match=delimiter

Print only the here documents that is enclosed by the specified delimiter.

-q, --quiet

By default, 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.

-r, --rules

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. The rule pod is enabled by default. Perl scripts with embedded here documents that uses a near POSIX like coding constructs may print correct. A rule perl is planned to address Perls variations in syntax.

-v, --version

Display the version information.

DIAGNOSTICS

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.

EXAMPLES

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 \&

AUTHOR

Bertil Kronlund, <bkron at cpan.org>

BUGS AND LIMITATIONS

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>.

SEE ALSO

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.

Filter::Heredoc, perlpod(1), podspell(1), aspell(1), ispell(1), hunspell(1).

On Debian systems, find international hunspell dictionaries at http://packages.debian.org/stable/hunspell

LICENSE AND COPYRIGHT

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.

DISCLAIMER OF WARRANTY

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.

VERSION

The version of filter-heredoc described by this manual page is Version 0.02.