The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Object-Import-1.001
River stage one • 2 direct dependents • 6 total dependents
1 ++
/ Object::Import

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 usualy, 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.

This is useful not only for applying methods to multiple objects, but for being able to free the object when it's no longer needed. If you don't use this option, then any imported function will forever reference the object.

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 that is either the name of a nonexistent package, or a string that is not a valid package name, or an unblessed object. Such values don't have any methods. 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. Also warns when the object is an empty string, undef, an unblessed reference, or other value on which calling methods does not make sense.

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", "<");

EXAMPLES

First a simple example of importing class methods.

        use Math::BigInt; 
        use Object::Import Math::BigInt::; 
        warn 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"); 
        warn bmul(2); 
        warn as_hex();

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

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.

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; 
        warn filenametemp;

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

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

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://cpansearch.perl.org/src/JESSE/perl-5.12.2/pod/perlartistic.pod".