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

FreeBSD Manual Pages

  
 
  

home | help
Object::Import(3)     User Contributed Perl Documentation    Object::Import(3)

NAME
       Object::Import -	import methods of an object as functions to a package

SYNOPSIS
	       use Object::Import $object;
	       foo(@bar); # now	means $object->foo(@bar);

DESCRIPTION
       This module lets	you call methods of a certain object more easily by
       exporting them as functions to a	package.  The exported functions are
       not called as methods and do not	receive	an object argument, but
       instead the object is fixed at the time you import them with this
       module.

       You use the module with the following syntax:

	       use Object::Import $object, %options;

       Here, $object is	the object from	which you want to import the methods.
       This can	be a perl object (blessed reference), or the name of a package
       that has	class methods.

       As usual, a "use" statement is executed in compile time,	so you should
       take care not to	use values that	you compute only in run-time, eg.

	       my $object = Foo::Bar->new();
	       use Object::Import $object; # WRONG: $object is not yet initialized

       Instead,	you have to create the object before you import, such as

	       use Object::Import Foo::Bar->new();

       You can also call import	in run-time, eg.

	       use Object::Import ();
	       my $object = Foo::Bar->new();
	       import Object::Import $object;

       but in that case, you can't call	the imported functions without
       parenthesis.

       If you don't give an explicit list of methods to	export,	Object::Import
       tries to	find out what callable methods the object has and import all
       of them.	 Some methods are excluded from	exporting in this case,	namely
       any methods where exporting would overwrite a function existing in the
       target package or would override	a builtin function, also any methods
       with names that are special to perl, such as "DESTROY", and any methods
       whose name starts with an underscore.  This automatic search for
       methods is quite	fragile	because	of the way perl	OO works, so it	can
       find subroutines	that shouldn't actually	be called as methods, or not
       find methods that can actually be called.  In particular, even if you
       import an object	from a purely object oriented module, it can find non-
       method subs imported from other (non-OO)	modules.

       If you do give a	list of	methods	to export, Object::Import trusts you
       know what you mean, so it exports all those subs	even if	it has to
       replace existing	subs or	break something	else.

OPTIONS
       The following import options can	be passed to the module.

       "list =>" $arrayref
	   Sets	the list of methods to export, instead of the module deciding
	   automatically.  $arrayref must be a reference to an array
	   containing method names.  Eg.

		   use Object::Import LWP::UserAgent->new, list	=>
			   [qw"get post	head mirror request simple_request"];

       "target =>" $package_name
	   Export the sub names	to the given namespace.	 Default is the
	   package from	where you call import.

       "deref => 1"
	   Signals that	the first import argument, instead of being the	object
	   itself, is a	reference to a scalar that contains the	object.

	   The content of this scalar may later	be changed, and	the imported
	   functions will be called on the new contents.  (The scalar may even
	   be filled with undef, as long as you	don't call the functions at
	   that	time.)	If you don't pass the list of methods explicitly, the
	   content of the scalar at the	time of	the import is used for
	   determining the methods as a	template to determine the methods.
	   If, however,	you give the list of methods, the content of the
	   scalar is not examined at the time of the import.

       "prefix =>" $string
	   Prepends a string to	the names of functions imported.  This is
	   useful if some of the method	names are the same as existing subs or
	   builtins.  Eg.

		   use Object::Import $object, prefix => "foo";
		   foo_bar(); #	calls $object->bar();

       "suffix =>" $string
	   Like	the prefix option, only	the string is appended.

       "underscore => 1"
	   Consider a method for automatic inclusion even if its name starts
	   with	an underscore.	Such methods are normally excluded, because
	   they	are usually used as private subs.

       "exclude_methods	=>" $hashref
	   Sets	a list of additional methods that are not automatically
	   imported.  The argument must	be a reference to a hash whose keys
	   are potential method	names.	Ignored	if you use the "list" option.

       "exclude_imports	=>" $hashref
	   Sets	a list of additional sub names which the module	must never use
	   as names of imported	subs.  These names are thus compared not with
	   the original	method names, but the names possibly transformed by
	   adding prefixes and suffixes.  This applies even if you give	an
	   explicit "list" of methods to import.

       "savenames =>" $hashref
	   Save	the (unqualified) names	of the functions exported by adding
	   them	as a key to a hash (the	value is incremented with the ++
	   operator).  This could be useful if you wanted to reexport them
	   with	Exporter.  $arrayref must be a real reference to a hash, not
	   an undef.

       "nowarn_redefine	=> 1"
	   Do not warn when an existing	sub is redefined.  That	is currently
	   only	possible if you	give the list of methods to be exported
	   explicitly with the "list" option, because if the module chooses
	   automatically then it will not redefine subs.

       "nowarn_nomethod	=> 1"
	   Suppress the	warning	when you try to	import methods from an object
	   you might have passed in by mistake.	 Namely	the object could be
	   the name of a nonexistent package, a	string that is not a valid
	   package name, an unblessed object, or undef.	 Such values either
	   don't currently have	any methods, or	calling	methods	on them	is
	   impossible.	That warning often indicates that you passed the wrong
	   value to Object::Import or forgot to	require	a package.

       "debug => 1"
	   Print debugging messages about what the module exports.

NOTES
   Importing from IO handles
       It is possible to use an	IO handle as the object	to export methods
       from.  If you do	this, you should require IO::Handle first so that the
       handle actually has methods.  You should	probably also use the prefix
       or suffix option	in such	a case,	because	many methods of	handles	have
       the same	name as	a builtin function.

       The handle must not be a	symbolic reference, whether qualified or
       unqualified, eg.

	       open FOO, "<", "somefile" or die;
	       use Object::Import "FOO"; # WRONG

       You can pass a handle as	a glob,	reference to glob, or an IO::Handle
       object, so any of these would work as the object	after the above	open
       statement: *FOO,	"\*FOO", *FOO{IO}.  Another way	to pass	an IO::Handle
       object would be like this:

	       use IO::File;
	       use Object::Import IO::File->new("somefile", "<");

   Changing the	object
       The "deref" option deserves special mention.  This option adds a	level
       of indirection to the imported functions: instead of them calling
       methods on an object passed to import, the methods are called on	the
       object currently	contained by a scalar to which a reference is passed
       in to import.  This can be useful for various reasons: operating	on
       multiple	objects	throughout the course of the program, being able to
       import the functions at compile time before you create the object, or
       being able to destroy the object.  The first of this use	is
       straightforward,	but you	may need to know the following for the other
       two uses.

       The list	of methods imported is decided at the time you call import,
       and will	not be changed later, no matter	how the	object is changed or
       methods the object supports are changed.	 You thus have to do extra
       loops if	you want to call import	before the object is available.	 The
       simplest	solution is to pass the	list of	methods	you want explicitly
       using the list option.  If for some reason you don't want to do this,
       you need	to fill	the scalar with	a suitable prototype object that has
       all the methods of the actual object you	want to	use.  In many cases,
       the package name	the object will	be blessed to is a suitable prototype,
       but note	that if	you do not control the module implementing the object,
       then that module	may not	guarantee what package the object will
       actually	be blessed to: the package may depend on some run-time
       parameters and the details about	this could change in future versions
       of the module.  This is,	of course, not specific	to the deref option,
       but true	to a lesser extent to any case when you're using
       Object::Import without an explicit list of methods: a future version of
       the module could	create the methods of the class	in runtime or AUTOLOAD
       them without declaring them, or it could	add new	private	methods	that
       will clash with function	names you're using.  Nevertheless, using the
       classname as a prototype	can be a useful	trick in quick and dirty
       programs, or if you are in control of the implementation	of the object.

       Now let's hear about destroying an object that may hold resources you
       want to free.  Object::Import guarantees	that if	you use	the deref
       option, it does not hold	references to the object other than through
       the one scalar, so if undef the contents	of that	scalar,	the object
       will be freed unless there are references from somewhere	else.

       Finally,	there's	one thing you don't want to know but I must document
       it for completeness: if a method	called through Object::Import changes
       its invocant (zeroth argument), that will also change the object	the
       imported	functions refer	to, whether you	use the	deref option or	not,
       and will	change the contents of the scalar if you use the deref option.

EXAMPLES
       Our examples assume the following declarations:

	       use feature "say";

   Basic usage
       First a simple example of importing class methods.

	       use Math::BigInt;
	       use Object::Import Math::BigInt::;
	       say new("0x100");

       This prints 256,	because	Math::BigInt->new("0x100") creates a big
       integer equal to	256.

       Now let's see a simple example of importing object methods.

	       use Math::BigInt;
	       use Object::Import Math::BigInt->new("100");
	       say bmul(2);
	       say as_hex();

       This prints 200 (2 multiplied by	100), then 0xc8	(100 as	hexadecimal).

   Multiple imports
       Now let's see a more complicated	example.  This prints the leading news
       from the	English	Wikinews website.

	       use warnings; use strict;
	       use LWP::UserAgent;
	       use XML::Twig;
	       use Object::Import LWP::UserAgent->new;
	       my $response = get "http://en.wikinews.org/wiki/Special:Export?".
		       "pages=Template:Lead_article_1&limit=1";
	       import Object::Import $response;
	       if (is_success()) {
		       use Object::Import XML::Twig->new;
		       parse content();
		       for my $parmname	(qw"title summary") {
			       first_elt("text")->text =~ /\|\s*$parmname\s*=([^\|\}]+)/ or die;
			       print $1;
		       }
	       } else {
		       die message();
	       }

       For example, as I am writing this (2010-09-05), this outputs

	   Magnitude 7.0 earthquake hits New Zealand

	   An earthquake with magnitude	7.0 occurred near South	Island,	New
	   Zealand at Saturday 04:35:44	AM local time (16:35:44	UTC). The
	   earthquake occurred at a depth of 16.1 kilometers (10.0 miles). The
	   earthquake was reported to have caused widespread damage and	power
	   outages. Several aftershocks	were also reported.

       In this,	"get" refers to	the useragent object; "is_success", "content"
       and "message" refers to the response object (and	these must be called
       with a parenthesis); while "parse" and "first_elt" refer	to the twig
       object.	This is	not a good example to follow: it's quite fragile, and
       not only	because	of the simple regex used to parse out the right	parts,
       but because if a	new sub	is added to a future version of	the
       LWP::UserAgent or HTTP::Response	classes, they might suddenly get
       imported	and would shadow the methods we're supposed to import later.

   Suffix
       Now let's see an	example	of using a suffix.

	       use File::Temp;
	       use Object::Import scalar(File::Temp->new()), suffix => "temp";
	       printtemp "hello, world\nhidden";
	       seektemp	0, 0;
	       print getlinetemp;
	       say filenametemp;

       Here we need the	suffix because print and seek are names	of builtin
       functions.

   Creating the	object later
       Let's see how we	can import methods before we create an object.

	       use Math::BigInt;
	       our $number;
	       use Object::Import \$number, deref => 1,	list =>	["bmul"];
	       sub double { bmul 2 }
	       $number = Math::BigInt->new("100");
	       say double;

       This will output	200.  Notice how here we're using the bmul function
       without parenthesis, so we must import it compile time for the code to
       parse correctly,	but the	object is not created till later.

   Prototype object
       This code is the	same as	above, except that instead of supplying	a list
       of methods, we use a prototype object, namely the Math::BigInt package.
       At least	one of the two is needed, for otherwise	Object::Import would
       have no way to know what	methods	to import.

	       use Math::BigInt;
	       our $number;
	       use Object::Import \($number = Math::BigInt::), deref =>	1;
	       sub double { bmul 2 }
	       $number = Math::BigInt->new("100");
	       say double;

   Exporting to	other package
       This example shows how to export	to a different namespace.  This	is
       useful if you want to write your	own sugar module that provides a
       procedural syntax:

	       package My::Object::DSL;
	       use Object::Import;
	       use My::Object;

	       sub import {
		   my ($class, %options);
		   if (@_ == 2)	{
		       ($class,	$options{ name }) = @_;
		   } else {
		       ($class,	%options) = @_;
		   };
		   my $target =	delete $options{ target	} || caller;
		   my $name = delete $options{ name } || '$obj';
		   my $obj = My::Object->new(%options);

		   $name =~ s/^[\$]//
		       or croak	'Variable name must start with $';
		   {
		       no strict 'refs';
		       *{"$target\::$name"} = \$obj;
		       # Now install in	$target::
		       import Object::Import \${"$target\::$name"},
					     deref => 1,
					     target => $target;
		   }
	       }

       You can use the module "My::Object::DSL"	as follows:

	       use My::Object::DSL '$obj';

       If you want to pass more	options, you can use

	       use My::Object::DSL name	=> '$obj', foo => 'bar';

       Implementing a small "::DSL" module instead of using "Object::Import"
       directly	has the	advantage that you can add defaults in "DSL.pm".

SEE ALSO
       Class::Exporter,	Scope::With, Sub::Exporter, Acme::Nooo

BUGS
       Please report bugs using	the CPAN bug tracker (under the	distribution
       name Object-Import), or,	failing	that, to "ambrus@math.bme.hu".

CREDITS
       The primary author and maintainer of this module	is Zsban Ambrus
       "ambrus@math.bme.hu".  Some of the code was written by Max Maischein,
       who also	gave the motivation to turn a prototype	to the full module you
       see.  Thanks to exussum0	for the	original inspiration.

COPYING
       Copyright (C) Zsban Ambrus 2010

       This program is free software: you can redistribute it and/or modify it
       under the terms of either the GNU General Public	License	version	3, as
       published by the	Free Software Foundation; or the "Artistic License"
       which comes with	perl.

       This program is distributed in the hope that it will be useful, but
       WITHOUT ANY WARRANTY; without even the implied warranty of
       MERCHANTABILITY or FITNESS FOR A	PARTICULAR PURPOSE.  See the GNU
       General Public License for more details.

       A copy of the GNU General Public	License	can be found in	the source
       tree of this module under the name "GPL", or else see
       "http://www.gnu.org/licenses/".	A copy of the Artistic License can be
       found in	the source tree	under the name "ARTISTIC", or else see
       "http://search.cpan.org/~rjbs/perl-5.16.1/pod/perlartistic.pod".

perl v5.24.1			  2012-10-17		     Object::Import(3)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | NOTES | EXAMPLES | SEE ALSO | BUGS | CREDITS | COPYING

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

home | help