App::PipeFilter::Generic is a generic shell pipeline filter. It is designed to be customized by subclassing and consuming roles that implement specific behaviors.
For example, App::PipeFilter::JsonToYaml extends the generic pipeline filter with a role to read data in large chunks, a role to parse that input as a stream of JSON objects, a role that doesn't alter the data that has been read, and a role to format the output as YAML.
decode_input() accepts a reference to an input buffer containing raw octets from some input stream. It deserializes as many input records as it can from the buffer. It removes the deserialized octets from the buffer, leaving any unused data for another time. decode_input() returns an array of the deserialized data structures.
This method is usually implemented by Input roles.
encode_output() accepts an array of Perl data structures to be output. It returns an array of serialized data, one element for each input data structure.
This method is usually implemented by Output roles.
filter_file() translates one input file to output. IN_FILEHANDLE is an open filehandle to the source data. OUT_FILEHANDLE is an open filehandle to the output data sink.
filter_file() invokes read_input(), decode_input(), transform() and encode_output() until a single input file is completely filtered.
next_input_file() returns the name of the next file to read. App::PipeFilter::Generic's run() method uses it to iterate over the list of input files provided on the command line.
next_input_file() is implemented in App::PipeFilter::Role::Flags::Standard.
open_input() opens a named file and returns the opened filehandle to it. The special file name "-" opens STDIN.
App::PipeFilter::Generic's run() method uses open_input() to open the files named by next_input_file().
open_input() is implemented in Opener roles.
open_output() opens a named file and returns the opened filehandle to it. The special file name "-" opens STDOUT.
App::PipeFilter::Generic's run() method uses open_output() to open standard output for writing results.
open_output() is implemented in Opener roles.
run() opens standard output using open_output("-"). It then calls next_input_file() to iterate through all the input file names provided on the command line. Each input file is opened with open_input(). The resulting input and output file handles are passed to filter_file(), which filters the entire file.
run() is implemented in [% doc.module() %].
transform() accepts an array of data references. It returns another array of data references after performing some transformative function on each one. The resulting array may have greater or fewer items than the input array. transform() may return an empty array if all input records are to be discarded.
Common data transformations may be implemented in Transform roles. Mostly however, individual utility classes like App::PipeFilter::JsonMap define their own transformations.
You may read this module's implementation in its entirety at
perldoc -m [% doc.module() %]
App::PipeFilter::Generic::Json consumes common roles for filters that read and write streams of JSON objects.
App::PipeFilter has top-level documentation including a table of contents for all the libraries and utilities included in the project.
TODO - Standard =repository