view release on metacpan or  search on metacpan

lib/Text/ASCIIPipe.pm  view on Meta::CPAN

		,end    => \&end_hook
		,allend => \&allend_hook
	);

	# Processes given file handle.
	my $fh;
	open($fh, '<', $dump_of_a_text_data_stream);
	Text::ASCIIPipe::process
	(
		 in     => $fh
		,out    => \*STDOUT # or undef, or some other file
		,pre    => \&prefilter_hook
		,begin  => \&begin_hook
		,line   => \&line_hook
		,end    => \&end_hook
		,allend => \&allend_hook
		,flush  => 0  # Default is 1 (see below).
	);

	# The other side of the pipe can push serveral files...
	# Per default to STDOUT.

	# Just shove one whole file through (default: STDIN -> STDOUT).
	my $from
	my $to;
	open($from, '<', $some_filename);
	open($to, '|-', $some_command); # A pipe is what makes most sense...
	# Remember: $to can always be undef for STDOUT.
	Text::ASCIIPipe::push_file($from, $to);

	# Pull a file from Pipe (STDIN in this case) into given handle.
	open(my $out_fh, '>', $some_filename);
	my $fetch_count = Text::ASCIIPipe::pull_file(undef, $out_fh);
	print "Seems like something came through.\n" if($fetch_count > 0);

	# Detailed API.
	Text::ASCIIPipe::file_begin($to); # Send begin marker.
	# Send line(s) of file.
	Text::ASCIIPipe::file_lines($to, "#header\n", "1 2 3\n");
	Text::ASCIIPipe::file_end($to);   # Send end marker.

	# After sending all files, send total end marker (allend).
	# Just closing the sink does the  trick, too.
	Text::ASCIIPipe::done($to);

	# If you wrap your stuff into an objet, you can provide its instance
	# as context and have the handlers work as methods on this.
	Text::ASCIIPipe::process
	(
		,handle => $my_object_instance
		# The hooks are methods of the above!
		# (or just any sub that wants it as first argument)
		,begin  => \&begin_hook
		,line   => \&line_hook
		,end    => \&end_hook
		,allend => \&allend_hook
	);

=head1 DESCRIPTION

A lot of the speed penalty of Perl when processing multiple smallish data sets from/to text form in a shell loop consists of the repeated perl compiler startup / script compilation, which accumulates when looping over a set of files. This process can...

When dealing with ASCII-based text files (or UTF-8, if you please), there are some control characters that just make sense for pushing several files as a stream, separated by these characters. These are character codes 2 (STX, start of text), 3 (EOT,...
All this module does is provide a wrapper for inserting these control characters for the sender and parsing them for the receiver. Nothing fancy, really. I just got fed up writing the same loop over and over again. It works with all textual data that...

The process() function itself tries to employ a bit of smartness regarding buffering of the output. Since the actual operation of multiple ASCIIPipe-using programs in a, well, pipe, might conflict with the default buffering of the output stream (STDO...

The callback hooks get handed in the optional configured handle and, as primary argument, the current line to process. Also, the current line end is given as following argument to help constructing additional lines properly, if you wish to do so:

	sub hook
	{
		$_[0] .= 'appended another line with proper ending'.$_[1];
	}

=head1 FUNCTIONS

This module offers a simple procedural interface built by the following stateless functions:

=over 4

=item B<fetch>

	$state = Text::ASCIIPipe::fetch($in_handle, $line);

Tries to fetch a line of text from given input handle (STDIN if undef), storing data in $line. Return value corresponds to one of those states: undef for no data being there (unannounced EOF), $Text::ASCIIPipe::begin for file begin marker, $Text::ASC...

=item B<plaintext>

	$not_special = Text::ASCIIPipe::plaintext($line);

Returns 1 if the given data does not start with one of the control codes that Text::ASCIIPipe interprets (could contain other control codes, though).

=item B<process>

Proccess a text file pipe, slurping through a stream of files. See SYNOPSYS for usage.

=item B<pull_file>

Pull a single file from the pipe. See SYNOPSYS for usage.

=item B<push_file>

Push a single file to the pipe. See SYNOPSYS for usage.

=item B<file_begin>

Send file begin marker. See SYNOPSYS for usage.

=item B<file_lines>

Send file contents. See SYNOPSYS for usage.

=item B<file_end>

Send file end marker. See SYNOPSYS for usage.

=item B<done>

Send overall end marker.  See SYNOPSYS for usage.

=back