NAME
    PPI::Processor - Implement a PPI Document processing engine

DESCRIPTION
    PPI::Processir provides a base class for implementing PPI-based Perl
    Document Proccessing Engine.

    This base class both provides a standard interface, and implements a
    complete single-node engine.

    By extending this class, it is intended to later implement a SMP,
    cluster, and/or distributed parrelel processing engine as well, using
    the same basic API.

EXTENDING
    At this time the API is still drifting a little bit.

    If you wish to write Tasks or extensions, please stay in touch with the
    maintainer while doing so.

METHODS
  new %args
    The "new" constructor creates a new Processor object. It takes as
    argument a set of name => value pairs. The base class accepts two named
    parameters.

    source
        The required "source" param identifies the source directory for the
        perl files to be processed. It must be a directory that exists and
        for which we have read permissions.

    find
        The optional "find" parameter lets you pass a File::Find::Rule
        object that will be used to find the set of files within the source
        directory that are to be processed.

        If not provided, a default File::Find::Rule object will be used that
        processes all .pm files contained in the source directory.

    trace
        The "trace" option (disabled by default) causes trace/debugging
        messages to be printed to STDOUT as the processing run processes.

    trace_summary
        For large and very long running processes, enabling the
        "trace_summary" option (disabled by default) will cause an addition
        job summary to be printed at roughly minute interval summarising the
        current status of the processing job.

    flush_results
        Some Task classes (generally the parellel-capable ones that generate
        information on a per-file basis) support incremental state.

        That is, they are able to determine if they have previously
        calculated a result for a file, and skip it.

        Setting flush_results to true (false by default) will force any of
        these shared states to be reset before the processing run starts.

    limit
        The "limit" option is an integer value indicating the maximum number
        of files to be processed in a single process (mainly to mitigate any
        potential leaks in PPI).

        If set to default, will parse any number.

    Returns a new PPI::Processor object, or "undef" on error.

  source
    The "source" accessor method returns the source directory that the
    object was created with.

  add_task $Task
    The "add_task" method is used to add a Task to the Processor object
    before processing commences.

    The parameter should be either an instantiated PPI::Processor::Task
    object, or the same of a sub-class which is autoconstructable.

    If passed a class name, the class will be loaded, the "autoconstruct"
    method will be checked, and an object will be created if the Task class
    supports autoconstruct.

    While adding the Task object, the Processor will also initialize the
    store for the Task.

    Returns true if the Task is added, or "undef" on error.

  run
    The "run" method starts the main processor loop. It takes no arguments,
    and the function will continue to load and process documents until it
    has completed all matching documents within the document source.

    Returns the total number of matching files, regardless of whether or not
    they were skipped or actually processed by the various Tasks. Returns
    "undef" if a fatal processing error occured during the run.

  init
    Given the size and complexity of many document processing tasks, the
    "init" provides a convenient mechanism to prepare various things for the
    main processing loop.

    By default, this includes determining and storing the full list of files
    to be processed, setting some state flags, and other tasks.

    Returns true on success, or "undef" on error.

  trace $message
    Prints out a trace/debug message, if they are enabled

  errstr
    For any error that occurs, you can use the "errstr", as either a static
    or object method, to access the error message.

    If no error occurs for any particular action, "errstr" will return
    false.

SUPPORT
    Bugs should always be submitted via the CPAN bug tracker

    <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=PPI%3A%3AProcessor>

    For other issues, contact the maintainer

AUTHOR
    Adam Kennedy (Maintainer), <http://ali.as/>, cpan@ali.as

    Funding provided by The Perl Foundation

COPYRIGHT
    Copyright (c) 2004 - 2005 Adam Kennedy. All rights reserved. This
    program is free software; you can redistribute it and/or modify it under
    the same terms as Perl itself.

    The full text of the license can be found in the LICENSE file included
    with this module.

SEE ALSO
    PPI::Processor::Task, PPI