NAME
    Class::Handle - Supply object methods to classes

SYNOPSIS
      # Create a class handle
      use Class::Handle;
      my $class = Class::Handle->new( 'Foo::Class' );
      my $name = $class->name;
      
      # UNIVERSAL type methods
      $class->VERSION();
      $class->isa( 'Foo:Bar' );
      $class->can( 'blah' );
      
      # Class::Inspector type methods
      $class->installed();
      $class->loaded();
      $class->filename();
      $class->resolved_filename();
      $class->functions();
      $class->function_refs();
      $class->function_exists( 'function' );
      $class->methods( 'public', 'full' );
      
      # Class::ISA type methods
      $class->super_path();
      $class->self_and_super_path();
      $class->full_path();
      
      # Loading and unloading
      $class->load();

DESCRIPTION
    Class related functionality in Perl is broken up into a variety
    of different modules. Class::Handle attempts to provide a
    convenient object wrapper around the various different types of
    functions that can be performed on a class.

    Please note that this is an initial non-production quality
    release, and should be used as such. Functionality and API are
    subject to change without notice.

    Currently, Class::Handle provies what is effectively a combined
    API from `UNIVERSAL', `Class::ISA' and `Class::Inspector' for
    obtaining information about a Class, and some additional task
    methods, such as `load' to common tasks relating to classes.

UNIVERSAL API
    To ensure we maintain compliance with other classes that rely on
    methods provided by `UNIVERSAL', Class::Handle acts in the
    normal way when something like `Class::Handle-'VERSION> is
    called. That is, it returns the version of Class::Handle itself.
    When `UNIVERSAL' methods are called on an instantiation the
    method is changed to act on the class we have a handle to. For
    example, the two following statements are equivalent.

      # Getting the version directly
      print Foo::Bar->VERSION();
      
      # Getting the version via Class::Handle
      my $class = Class::Handle->new( 'Foo::Bar' );
      print $class->VERSION();

    This also applies to the `isa' and `can' methods.

METHODS
  new( $class )

    The `new' constructor will create a new handle to a class or
    unknown existance or status. That is, it won't check that the
    class actually exists at this time. It WILL however check to
    make sure that your class name is legal.

      Returns a new Class::Handle object on success
      Returns undef if the class name is illegal
    =head2 name()

    The c<name> method returns the name of the class as original
    specified in the constructor.

  VERSION()

    Find the version for the class. Does not check that the class is
    loaded ( at this time ). Returns the version on success. Returns
    undef if the class does not defined a `$VERSION', or the class
    is not loaded.

  isa( $class )

    Checks to see if the class is a subclass of another class. Does
    not check that the class is loaded ( at this time ). Returns
    true/false as for `UNIVERSAL::isa'

  can( $method )

    Checks to see if a particular method is defined for the class.
    Returns a `CODE' ref to the function is the method is available.
    Returns false if the class does not have that method available.

  installed()

    Checks to see if a particular class is installed on the machine,
    or at least that the class is available to perl. In this case,
    "class" really means "module". This methods cannot detect a
    class that is not a module. ( Has it's own file ). Returns true
    if the class is installed and available. Returns false
    otherwise.

  loaded()

    Checks to see if a class is loaded. In this case, "class" does
    NOT mean "module". The `loaded' method will return true for
    classes that do not have their own file.

    For example, if a module `Foo' contains the classes `Foo',
    `Foo::Bar' and `Foo::Buffy', the `loaded' method will return
    true for all of the classes.

    Returns true if the class is loaded. Returns false otherwise.

  filename()

    Returns the base filename for a class. For example, for the
    class `Foo::Bar', `loaded' would return `"Foo/Bar.pm"'. The
    `filename' method is platform neutral, it should always return
    the filename in the correct format for your platform.

  resolved_filename( @extra_paths )

    The `resolved_filename' will attempt to find the real file on
    your system that will be used when a class is loaded. If
    additional paths are provided as argument, they will be tried
    first, before the contents of the @INC array. If a file cannot
    be found to match the class, returns false.

  loaded_filename()

    If the class is loaded, returns the name of the file that it was
    originally loaded from. Returns false if the class is not
    loaded, or did not have it's own file.

  functions()

    Returns a list of the names of all the functions in the classes
    immediate namespace. Note that this is not the METHODS of the
    class, just the functions. Returns a reference to an array of
    the function names on success. Returns undef on error or if the
    class is not loaded.

  function_refs()

    Returns a list of references to all the functions in the classes
    immediate namespace. Returns a reference to an array of CODE
    refs of the functions on success. Returns undef on error or if
    the class is not loaded.

  function_exists( $function )

    Checks to see if the function exists in the class. Note that
    this is as a function, not as a method. To see if a method
    exists for a class, use the `can' method in UNIVERSAL, and hence
    to every other class. Returns 1 if the function exists. Returns
    0 if the function does not exist. Returns undef on error, or if
    the class is not loaded.

  methods( @options )

    Attempts to find the methods available to the class. This
    includes everything in the classes super path up to, but NOT
    including, UNIVERSAL. Returns a reference to an array of the
    names of all the available methods on success. Returns undef if
    the class is not loaded.

    Any provided options are passed through, and alter the response
    in the same way as for the options to `Class::Inspector-
    'methods()>, that is, 'public', 'private', 'full' and
    'expanded', and combinations thereof.

  super_path()

    The `super_path' method is a straight pass through to the
    `Class::ISA-'super_path> method. Returns an ordered list of
    class names, with no duplicates. The list does NOT include the
    class itself, or the UNIVERSAL class.

  self_and_super_path()

    As above, but includes ourself at the beginning of the path.
    Directly passes through to Class::ISA.

  full_super_path()

    The `full_super_path' method is an additional method not in
    `Class::ISA'. It returns as for `super_path', except that it
    also contains BOTH the class itself, and `UNIVERSAL'. This full
    list is more technically accurate, but less commonly used, and
    as such isn't available from Class::ISA itself.

BUGS
    No known bugs. Additional feature requests are being taken.

SUPPORT
    Contact the author

AUTHOR
            Adam Kennedy
            cpan@ali.as
            http://ali.as/

SEE ALSO
    `UNIVERSAL', `Class::ISA', and `Class::Inspector', which provide
    most of the functionality for this class.

COPYRIGHT
    Copyright (c) 2002 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.

