#pod The software engineering concept known as a pipeline is a chain of processing segments, arranged such that the output of each segment is the input of the next.
#pod Additionally, a single hashref of attributes for the container/parent segment may be included as an argument to the constructor (anywhere in the argument list). See the L section for a description of attributes available for both parent and child segments.
#pod For such pairs, the C<$segment> can be any of the above segment types, and C<$label> is a simple scalar which will be used as C<$segment>'s label.
#pod Piper segments were designed to be easily reusable. Prior to initialization, L and L objects do not process data; they simply contain the blueprint for creating the pipeline. As such, blueprints for commonly-used pipeline segments can be stored in package libraries and imported wherever needed.
#pod To create a functioning pipeline from one such blueprint, simply call the C method on the outermost segment. The C method returns a L object of the outermost segment, which is the realization of the pipeline design, and which contains L objects created from all its contained segments.
#pod Initialization fuses the pipeline segments together, establishes the relationships between the segments, and initializes the dataflow infrastructure.
#pod Any arguments passed to the C method will be cached and made available to each handler in the pipeline (see the L section for full description of handlers). This is a great way to share a resource (such as a database handle) among process handlers.
#pod In its simplest form, the process handler takes input from the previous pipeline segment, processes it, and passes it on to the next segment; but handlers also have built-in support for non-linear and recursive dataflow (see L).
#pod Send C<@data> to the next segment in the pipeline. If the instance is the last in the pipeline, emits to the drain, making the C<@data> ready for C.
#pod For each of the above methods, C<$location> must be the label of a segment in the pipeline or a path-like representation of an hierarchy of labels.
#pod If a label is unique within the pipeline, only the label is required. For non-unique labels, searches are performed in a nearest-neighbor, depth-first manner.
#pod For example, in the following pipeline, searching for C from the handler of C would find C, not C. So to reach C from C, the handler would need to search for C.
#pod A star (*) indicates that the attribute is writable, and can be modified at runtime by passing a value as an argument to the method of the same name.
#pod All writable attributes (indicated by *) can be cleared by passing an explicit C to the writer method or by calling the appropriate clearer method called C.
#pod The coderef executes on each item attempting to queue to the segment. If it returns true, the item is queued. Otherwise, the item skips the segment and proceeds to the next adjacent segment.
#pod Once initialized (see L), a segment inherits the C of any existing parent(s) if not provided. If the segment has no parents, or if none of the parents have a C defined, the default C will be used. The default C is 200, but can be configured in the import statement (see the L section).
#pod Once initialized (see L), a segment inherits the debug level of any existing parent(s) if not specified. The default level is 0, but can be globally overridden by the environment variable C.
#pod Labels are necessary for certain types of L (for example, L or L). For pipelines that do not utilize L features, labels are primarily useful for L.
#pod Once initialized (see L), a segment inherits the verbosity level of any existing parent(s) if not specified. The default level is 0, but can be globally overridden by the environment variable C.
#pod For all instances in the pipeline except the outermost container (C), this attribute holds a reference to the instance's immediate container segment.
#pod The full path to the instance, built as the concatenation of all the parent(s) labels and the instance's label, joined by C. Instances stringify to this attribute.
#pod Find and return the segment instance according to C<$location>, which can be a label or a path-like hierarchy of labels. See L for a detailed description of C<$location>.
#pod Warnings and errors are issued regardless of debug and verbosity levels via C and C from the L module, and are therefore configurable with any of L's global options or environment variables.
#pod Debugging and/or informational messages are printed to STDERR if debug and/verbosity levels have been set. There are three levels used by L for each of C/C: S<0, 1, or 2>. The default is S<0 (off)>.
#pod Levels can be set by any of the following mechanisms: at construction of the L/L objects, dynamically via the C and C methods of segments, or with the environment variables C and C.
#pod Levels set via the environment variables C and C are global. If set, these environment variables override any and all settings defined in the source code.
#pod Existing informational (C or S<< C > 0 >>) messages describe data processing steps, such as noting when items are queueing or being processed by specific segments. Increasing S 1> simply adds more detail to the printed messages.
#pod Existing debug messages describe the decision actions of the pipeline engine itself. Examples include logging its search steps when locating a named segment or explaining how it chooses which batch to process. Increasing the debug S<< level > 1 >> simply adds more detail to the printed messages.
#pod The first argument passed to a L is the L object associated with that segment, which has the below-described methods available for logging, debugging, warning, or throwing errors.
#pod In each of the below methods, the C<@items> are optional and only printed if the verbosity level for the segment S<< is > 1 >>. They can be used to pass additional context or detail about the data being processed or which caused the message to print (for conditional messages).
#pod The built-in messaging only uses debug/verbosity levels S<1 and 2>, but there are no explicit rules enforced on maximum debug/verbosity levels, so users may explicitly require higher levels for custom messages to heighten the required levels for any custom message.