NAME
    Class::AutoGenerate - Automatically generate code upon require or use

SYNOPSIS
      # Create a customized class loader (auto-generator)
      package My::ClassLoader;
      use Class::AutoGenerate -base;

      # Define a matching rule that generates some code...
      requiring 'Some::**::Class' => generates { qq{
          sub print_my_middle_names { print $1,"\n" }
      } };

      # In some other file, let's use the class loader
      package main;

      # Create the class loader, which adds itself to @INC
      use My::ClassLoader;
      BEGIN { My::ClassLoader->new; }

      # These class will be generated on the fly...
      use Some::Freaking::Class;
      use Some::Other::Freaking::Class;

      Some::Freaking::Class->print_my_middle_names;
      Some::Other::Freaking::Class->print_my_middle_names;

      # Output is:
      #   Freaking
      #   Other::Freaking

DESCRIPTION
    EXPERIMENTAL. I'm trying this idea out. Please let me know what you
    think by contacting me using the information listed under "AUTHOR". This
    is an experiment and any and all aspects of the API are up for revision
    at this point and I'm not even sure I'll maintain it, but I hope it will
    be found useful to myself and others.

    Sometimes it's nice to be able to generate code on the fly. This tool
    does just that. You declare a few rules that can be used to define the
    class names you want to auto-generate and then the code that is to be
    built from it. Later you create your auto-generator object and start
    using the auto-generated classes.

    This is a generalization baed upon Jifty::ClassLoader. If this
    experiment is successful in the way I'm testing it out for, it may be
    used to re-implement that class.

METHODS
  import
    When you are creating a new auto-generating class loader, you will
    include this statement in your package definition:

      package My::ClassLoader;
      use Class::AutoGenerate -base;

    This statement tells Class::AutoGenerate to import all the subroutines
    in Class::AutoGenerate::Declare into the current package so that a new
    class loader can be declared.

    Later, when you use your class loader, you will use the undecorated
    form:

      use My::ClassLoader;

    In this case, the import method does nothing special.

  new
    Creates a new instance of the auto-generating class loader object you've
    built. The class loader automatically adds itself to the @INC array to
    start loading classes.

    If you want to immediately start using the class loader at compile time,
    you may wish to call this method within a "BEGIN" block:

      use My::Custom::ClassLoader;
      BEGIN { My::Custom::ClassLoader->new };

  INC
    This is the subroutine called by Perl during a perlfunc/require or
    perlfunc/use and evaluates the rules defined in your class loader. See
    perlfunc/require (towards the end) to see how this works.

    It should be noted, however, that we cheat the system a little bit.
    According ot the require hook API, this method should return either a
    filehandle containing the code to be read or "undef" indicating that the
    hook does not know about the file being required.

    This is done, except that only an empty stub package like this is ever
    returned when a class is auto-generated:

      use strict;
      use warnings;

      package The::Included::Package::Name;

      1;

    Instead of having the import mechanism within Perl compile the code,
    most of the work is handled through symbol table manipulations and code
    evaluation before the file handle is returned. This allows for some
    earlier compile-time checking via closures and the like.

  _match_and_generate MODULE
    This method is used internally to match "requiring" in
    Class::AutoGenerate::Declare statements and automatically generate code
    upon a match.

  _rules
    Used internally to reference the rules declared in the auto-generating
    class loader.

  _match_requiring MODULE, PATTERN
    Used internally to match a "requiring" in Class::AutoGenerate::Declare
    declaration to a package name. Returns true if there's a match, or false
    otherwise.

  _autogenerate MODULE, PATTERN, GENERATES
    This method performs the action of taking the work in the generates
    declration and stuffing that work into the named package.

  _stub_file_handle MODULE
    Returns a basic stub class that is handed off to the import
    infrastructure of Perl to let it know that we succeeded, even though we
    already did most of the work for it.

SEE ALSO
    Class::AutoGenerate::Declare

AUTHOR
    Andrew Sterling Hanenkamp "<hanenkamp@cpan.org>"

COPYRIGHT AND LICENSE
    Copyright 2007 Boomer Consulting, Inc. All Rights Reserved.

    This program is free software and may be modified and distributed under
    the same terms as Perl itself.