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.

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.

    flushstate
        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 flushstate to true (false by default) will force any of
        these shared states to be reset before the processing run starts.

    before_file
        The optional "before_file" callback, provided as a CODE reference,
        will be passed the relative and full filenames immediately before
        the file is processed.

        The file will be skipped if the callback returns false.

    after_file
        The optional "after_file" callback, provided as a CODE reference,
        will be passed the relative and full filenames immediately after the
        file is processed.

        The return value is ignored.

    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.

  flushstore
    The "flushstore" accessor method returns the setting for the argument of
    the same name provided to the constructor.

  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.

  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