Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Class::Autouse(3)     User Contributed Perl Documentation    Class::Autouse(3)

NAME
       Class::Autouse -	Run-time load a	class the first	time you call a	method
       in it.

SYNOPSIS
	   ##################################################################
	   # SAFE FEATURES

	   # Debugging (if you go that way) must be set	before the first use
	   BEGIN {
	       $Class::Autouse::DEBUG =	1;
	   }

	   # Turn on developer mode (always load immediately)
	   use Class::Autouse qw{:devel};

	   # Load a class on method call
	   use Class::Autouse;
	   Class::Autouse->autouse( 'CGI' );
	   print CGI->b('Wow!');

	   # Use as a pragma
	   use Class::Autouse qw{CGI};

	   # Use a whole module	tree
	   Class::Autouse->autouse_recursive('Acme');

	   # Disable module-existance check, and thus one additional 'stat'
	   # per module, at autouse-time if loading modules off	a remote
	   # network drive such	as NFS or SMB.
	   # (See below	for other performance optimizations.)
	   use Class::Autouse qw{:nostat};

	   ##################################################################
	   # UNSAFE FEATURES

	   # Turn on the Super Loader (load all	classes	on demand)
	   use Class::Autouse qw{:superloader};

	   # Autouse classes matching a	given regular expression
	   use Class::Autouse qr/::Test$/;

	   # Install a class generator (instead	of overriding UNIVERSAL::AUTOLOAD)
	   # (See below	for a detailed example)
	   use Class::Autouse \&my_class_generator;

	   # Add a manual callback to UNIVERSAL::AUTOLOAD for syntactic	sugar
	   Class::Autouse->sugar(\&my_magic);

DESCRIPTION
       Class::Autouse is a runtime class loader	that allows you	to specify
       classes that will only load when	a method of that class is called.

       For large classes or class trees	that might not be used during the
       running of a program, such as Date::Manip, this can save	you large
       amounts of memory, and decrease the script load time a great deal.

       Class::Autouse also provides a number of	"unsafe" features for runtime
       generation of classes and implementation	of syntactic sugar. These
       features	make use of (evil) UNIVERSAL::AUTOLOAD hooking,	and are
       implemented in this class because these hooks can only be done by a one
       module, and Class::Autouse serves as a useful place to centralise this
       kind of evil :)

   Class, not Module
       The terminology "class loading" instead of "module loading" is used
       intentionally. Modules will only	be loaded if they are acting as	a
       class.

       That is,	they will only be loaded during	a Class->method	call. If you
       try to use a subroutine directly, say with "Class::method()", the class
       will not	be loaded and a	fatal error will mostly	likely occur.

       This limitation is made to allow	more powerfull features	in other
       areas, because we can focus on just loading the modules,	and not	have
       to deal with importing.

       And really, if you are doing OO Perl, you should	be avoiding importing
       wherever	possible.

   Use as a pragma
       Class::Autouse can be used as a pragma, specifying a list of classes to
       load as the arguments. For example

	  use Class::Autouse qw{CGI Data::Manip	This::That};

       is equivalent to

	  use Class::Autouse;
	  Class::Autouse->autouse( 'CGI'	 );
	  Class::Autouse->autouse( 'Data::Manip' );
	  Class::Autouse->autouse( 'This::That'	 );

   Developer Mode
       "Class::Autouse"	features a developer mode. In developer	mode, classes
       are loaded immediately, just like they would be with a normal 'use'
       statement (although the import sub isn't	called).

       This allows error checking to be	done while developing, at the expense
       of a larger memory overhead. Developer mode is turned on	either with
       the "devel" method, or using :devel in any of the pragma	arguments.
       For example, this would load CGI.pm immediately

	   use Class::Autouse qw{:devel	CGI};

       While developer mode is roughly equivalent to just using	a normal use
       command,	for a large number of modules it lets you use autoloading
       notation, and just comment or uncomment a single	line to	turn developer
       mode on or off. You can leave it	on during development, and turn	it off
       for speed reasons when deploying.

   Recursive Loading
       As an alternative to the	super loader, the "autouse_recursive" and
       "load_recursive"	methods	can be used to autouse or load an entire tree
       of classes.

       For example, the	following would	give you access	to all the URI related
       classes installed on the	machine.

	   Class::Autouse->autouse_recursive( 'URI' );

       Please note that	the loadings will only occur down a single branch of
       the include path, whichever the top class is located in.

   No-Stat Mode
       For situations where a module exists on a remote	disk or	another
       relatively expensive location, you can call "Class::Autouse" with the
       :nostat param to	disable	initial	file existance checking	at hook	time.

	 # Disable autoload-time file existance	checking
	 use Class::Autouse qw{:nostat};

   Super Loader	Mode
       Turning on the "Class::Autouse" super loader allows you to
       automatically load ANY class without specifying it first. Thus, the
       following will work and is completely legal.

	   use Class::Autouse qw{:superloader};

	   print CGI->b('Wow!');

       The super loader	can be turned on with either the
       "Class::Autouse->"superloader> method, or the ":superloader" pragma
       argument.

       Please note that	unlike the normal one-at-a-time	autoloading, the
       super-loader makes global changes, and so is not	completely self-
       contained.

       It has the potential to cause unintended	effects	at a distance. If you
       encounter unusual behaviour, revert to autousing	one-at-a-time, or use
       the recursive loading.

       Use of the Super	Loader is highly discouraged for widely	distributed
       public applications or modules unless unavoidable. Do not use just to
       be lazy and save	a few lines of code.

   Loading with	Regular	Expressions
       As another alternative to the superloader and recursive loading,	a
       compiled	regular	expression (qr//) can be supplied as a loader.	Note
       that this loader	implements UNIVERSAL::AUTOLOAD,	and has	the same side
       effects as the superloader.

   Registering a Callback for Dynamic Class Creation
       If none of the above are	sufficient, a CODE reference can be given to
       Class::Autouse.	Any attempt to call a method on	a missing class	will
       launch each registered callback until one returns true.

       Since overriding	UNIVERSAL::AUTOLOAD can	be done	only once in a given
       Perl application, this feature allows UNIVERSAL::AUTOLOAD to be shared.
       Please use this instead of implementing your own	UNIVERSAL::AUTOLOAD.

       See the warnings	under the "Super Loader	Module"	above which apply to
       all of the features which override UNIVERSAL::AUTOLOAD.

       It is up	to the callback	to define the class, the details of which are
       beyond the scope	of this	document.   See	the example below for a	quick
       reference:

       Callback	Example

       Any use of a class like Foo::Wrapper autogenerates that class as	a
       proxy around Foo.

	   use Class::Autouse sub {
	       my ($class) = @_;
	       if ($class =~ /(^.*)::Wrapper/) {
		   my $wrapped_class = $1;
		   eval	"package $class; use Class::AutoloadCAN;";
		   die $@ if $@;
		   no strict 'refs';
		   *{$class . '::new' }	= sub {
		       my $class = shift;
		       my $proxy = $wrapped_class->new(@_);
		       my $self	= bless({proxy => $proxy},$class);
		       return $self;
		   };
		   *{$class . '::CAN' }	= sub {
		       my ($obj,$method) = @_;
		       my $delegate = $wrapped_class->can($method);
		       return unless $delegate;
		       my $delegator = sub {
			   my $self = shift;
			   if (ref($self)) {
			       return $self->{proxy}->$method(@_);
			   }
			   else	{
			       return $wrapped_class->$method(@_);
			   }
		       };
		       return *{ $class	. '::' . $method } = $delegator;
		   };

		   return 1;
	       }
	       return;
	   };

	   package Foo;
	   sub new { my	$class = shift;	bless({@_},$class); }
	   sub class_method { 123 }
	   sub instance_method {
	       my ($self,$v) = @_;
	       return $v * $self->some_property
	   }
	   sub some_property { shift->{some_property} }

	   package main;
	   my $x = Foo::Wrapper->new(
	       some_property =>	111,
	   );
	   print $x->some_property,"\n";
	   print $x->instance_method(5),"\n";
	   print Foo::Wrapper->class_method,"\n";

   sugar
       This method is provided to support "syntactic sugar": allowing the
       developer to put	things into Perl which do not look like	regular	Perl.
       There are several ways to do this in Perl.  Strategies which require
       overriding UNIVERSAL::AUTOLOAD can use this interface instead to	share
       that method with	the superloader, and with class	gnerators.

       When Perl is unable to find a subroutine/method,	and all	of the class
       loaders are exhausted, callbacks	registered via sugar() are called.
       The callbacks recieve the class name, method name, and parameters of
       the call.

       If the callback returns nothing,	Class::Autouse will continue to
       iterate through other callbacks.	 The first callback which returns a
       true value will end iteration.  That value is expected to be a CODE
       reference which will respond to the AUTOLOAD call.

       Note: The sugar callback(s) will	only be	fired by UNIVERSAL::AUTOLOAD
       after all other attempts	at loading the class are done, and after
       attempts	to use regular AUTOLOAD	to handle the method call.  It is
       never fired by isa() or can().  It will fire repatedly for the same
       class.  To generate classes, use	the regular CODE ref support in
       autouse().

       Syntactic Sugar Example

	   use Class::Autouse;
	   Class::Autouse->sugar(
	       sub {
		   my $caller =	caller(1);
		   my ($class,$method,@params) = @_;
		   shift @params;
		   my @words = ($method,$class,@params);
		   my $sentence	= join(" ",@words);
		   return sub {	$sentence };
	       }
	   );

	   $x =	trolls have big	ugly hairy feet;

	   print $x,"\n";
	   # trolls have big ugly hairy	feet

   mod_perl
       The mechanism that "Class::Autouse" uses	is not compatible with
       mod_perl.  In particular	with reloader modules like Apache::Reload.
       "Class::Autouse"	detects	the presence of	mod_perl and acts as normal,
       but will	always load all	classes	immediately, equivalent	to having
       developer mode enabled.

       This is actually	beneficial, as under mod_perl classes should be
       preloaded in the	parent mod_perl	process	anyway,	to prevent them	having
       to be loaded by the Apache child	classes. It also saves HUGE amounts of
       memory.

       Note that dynamically generated classes and classes loaded via regex
       CANNOT be pre-loaded automatically before forking child processes.
       They will still be loaded on demand, often in the child process.	 See
       prefork below.

   prefork
       As with mod_perl, "Class::Autouse" is compatible	with the prefork
       module, and all modules specifically autoloaded will be loaded before
       forking correctly, when requested by prefork.

       Since modules generated via callback or regex cannot be loaded
       automatically by	prefork	in a generic way, it's advised to use prefork
       directly	to load/generate classes when using mod_perl.

   Performance Optimizatons
       :nostat
	   Described above, this option	is useful when the module in question
	   is on remote	disk.

       :noprebless
	   When	set, Class::Autouse presumes that objects which	are already
	   blessed have	their class loaded.

	   This	is true	in most	cases, but will	break if the developer intends
	   to reconstitute serialized objects from Data::Dumper, FreezeThaw or
	   its cousins,	and has	configured Class::Autouse to load the involved
	   classes just-in-time.

       :staticisa
	   When	set, presumes that @ISA	will not change	for a class once it is
	   loaded.  The	greatest grandparent of	a class	will be	given back the
	   original can/isa implementations which are faster than those
	   Class::Autouse installs into	UNIVERSAL.  This is a performance
	   tweak useful	in most	cases, but is left off by default to prevent
	   obscure bugs.

   The Internal	Debugger
       Class::Autouse provides an internal debugger, which can be used to
       debug any weird edge cases you might encounter when using it.

       If the $Class::Autouse::DEBUG variable is true when "Class::Autouse" is
       first loaded, debugging will be compiled	in. This debugging prints
       output like the following to STDOUT.

	   Class::Autouse::autouse_recursive( 'Foo' )
	       Class::Autouse::_recursive( 'Foo', 'load' )
		   Class::Autouse::load( 'Foo' )
		   Class::Autouse::_children( 'Foo' )
		   Class::Autouse::load( 'Foo::Bar' )
		       Class::Autouse::_file_exists( 'Foo/Bar.pm' )
		       Class::Autouse::load -> Loading in Foo/Bar.pm
		   Class::Autouse::load( 'Foo::More' )
		       etc...

       Please note that	because	this is	optimised out if not used, you can no
       longer (since 1.20) enable debugging at run-time. This decision was
       made to remove a	large number of	unneeded branching and speed up
       loading.

METHODS
   autouse $class, ...
       The autouse method sets one or more classes to be loaded	as required.

   load	$class
       The load	method loads one or more classes into memory. This is
       functionally equivalent to using	require	to load	the class list in,
       except that load	will detect and	remove the autoloading hook from a
       previously autoused class, whereas as use effectively ignore the	class,
       and not load it.

   devel
       The devel method	sets development mode on (argument of 1) or off
       (argument of 0).

       If any classes have previously been autouse'd and not loaded when this
       method is called, they will be loaded immediately.

   superloader
       The superloader method turns on the super loader.

       Please note that	once you have turned the superloader on, it cannot be
       turned off. This	is due to code that might be relying on	it being there
       not being able to autoload its classes when another piece of code
       decides they don't want it any more, and	turns the superloader off.

   class_exists	$class
       Handy method when doing the sort	of jobs	that "Class::Autouse" does.
       Given a class name, it will return true if the class can	be loaded (
       i.e. in @INC ), false if	the class can't	be loaded, and undef if	the
       class name is invalid.

       Note that this does not actually	load the class,	just tests to see if
       it can be loaded. Loading can still fail. For a more comprehensive set
       of methods of this nature, see Class::Inspector.

   autouse_recursive $class
       The same	as the "autouse" method, but autouses recursively.

   load_recursive $class
       The same	as the "load" method, but loads	recursively. Great for
       checking	that a large class tree	that might not always be loaded	will
       load correctly.

SUPPORT
       Bugs should be always be	reported via the CPAN bug tracker at

       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Class-Autouse>

       For other issues, or commercial enhancement or support, contact the
       author.

AUTHORS
       Adam Kennedy <cpan@ali.as>

       Scott Smith <sakoht@cpan.org>

       Rob Napier <rnapier@employees.org>

SEE ALSO
       autoload, autoclass

COPYRIGHT
       Copyright 2002 -	2012 Adam Kennedy.

       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.

perl v5.24.1			  2012-02-03		     Class::Autouse(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | SUPPORT | AUTHORS | SEE ALSO | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Class::Autouse&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help