IO-ReadPreProcess

This is a pre-processor that lives in your Perl program's input stream.
Your program does not need code to conditionally discard some input, include
files and substitute values.

An easy way of reading input where some lines are read conditionally and other
files included: .if/.else/.elseif/.fi, do: .include .let .print, loops: .while
.for; subroutine definition & call; write to other streams - and more.

Few changes are needed to your program, just open a file with this
module and use C<< <$fh> >> and C<< $fh->getline >>, etc.

    use IO::ReadPreProcess;

    my $fh = new IO::ReadPreProcess(File => './input.file') or
        die "Startup error: $IO::ReadPreProcess::errstr\n";

    $fh->{Math}->VarSetScalar('items', 20); # var used in input stream

    while(<$fh>) {
        print $_;    # Or other processing of input
    }

    die($IO::ReadPreProcess::errstr . "\n")
        if($fn->error);

    # Use pre-processor variable
    print "Sum output " . $fh->{Math}->ParseToScalar('sum') . "\n";

The input file contains text with lines of control directives, eg:

    A line of text
    .let sum = sum - 2
    .if sum < 20
    .echo Only \v{sum} items
    .elsif sum > 40
    There is plenty of stock
    .fi
    .# This is a comment
    .for i := 0 ;; i < items ;; i++
    .echo Item \v{i} is \v{stock[i]}
    .done
    .include $IncPath/report-footer.inc

Within input you may:

* evaluate expressions, assign variables

* conditions: .if/.unless/.elseif

* loops: while/until/for

* include other files and from pipes

* define subroutines that may take arguments and return a value that
  can be used in if/loop conditions

* log to stdout and stderr

* write to named streams opened by the main Perl script; these can transparently
  call Perl functions or write to arrays.

* read lines to pre-processor variables

The advantage over a separate pre-processor is that the application can share
state (variables) with the pre-processor.

The lead in character (C<.>) can be changed.

INSTALLATION

To install this module, run the following commands:

	perl Makefile.PL
	make
	make test
	make install

SUPPORT AND DOCUMENTATION

After installing, you can find documentation for this module with the
perldoc command.

    perldoc IO::ReadPreProcess

You can also look for information at:

    RT, CPAN's request tracker (report bugs here)
        http://rt.cpan.org/NoAuth/Bugs.html?Dist=Text-ReadConditionally

    AnnoCPAN, Annotated CPAN documentation
        http://annocpan.org/dist/Text-ReadConditionally

    CPAN Ratings
        http://cpanratings.perl.org/d/Text-ReadConditionally

    Search CPAN
        http://search.cpan.org/dist/Text-ReadConditionally/


LICENSE AND COPYRIGHT

Copyright (C) 2016-2017 Alain Williams - addw@phcomp.co.uk

This program is free software; you can redistribute it and/or modify it
under the terms of either: the GNU General Public License (version 2 or later)
as published by the Free Software Foundation; or the Artistic License.

See L<http://dev.perl.org/licenses/> for more information.

This was, to begin with, called Text::ReadConditionally - renamed to what seems
to be a more descriptive name.

SCCS: @(#)README	1.4 08/15/17 23:24:46