Importing from IO handles

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

Basic usage

        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

        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

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

        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

        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

        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

        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".