NAME

POE::Component::Archive::Any - a non-blocking wrapper around Archive::Any

SYNOPSIS

    use strict;
    use warnings;
    
    use POE qw(Component::Archive::Any);

    my $poco = POE::Component::Archive::Any->spawn;

    POE::Session->create(
        package_states => [
            main => [ qw( _start  extracted ) ],
        ],
    );

    $poe_kernel->run;

    sub _start {
        $poco->extract( {
                event => 'extracted',
                file  => 'archive.tar.gz',
            }
        );
    }

    sub extracted {
        my $in = $_[ARG0];

        if ( $in->{error} ) {
            print "Error: $in->{error}\n";
        }
        else {
            print "The archive extracts itself to outside directory\n"
                if $in->{is_naughty};
            print "The archive extracts itself to the current directory\n"
                if $in->{is_impolite};

            print "Extracted $in->{file} archive which is of type "
                    . "$in->{type} and contains the following files:\n";

            print "$_\n" for @{ $in->{files} };
        }
        $poco->shutdown;
    }

Using the event-based interface is also possible, of course.

DESCRIPTION

CONSTRUCTOR

spawn

    my $poco = POE::Component::Archive::Any->spawn;

    POE::Component::Archive::Any->spawn(
        alias => 'arch',
        options => {
            debug => 1,
            trace => 1,
            # POE::Session arguments for the component
        },
        debug => 1, # output some debug info
    );

The spawn method returns a POE::Component::Archive::Any object. It takes a few arguments, all of which are optional. The possible arguments are as follows:

alias

    POE::Component::Archive::Any->spawn(
        alias => 'arch'
    );

Optional. Specifies a POE Kernel alias for the component.

options

    my $poco = POE::Component::Archive::Any->spawn(
        options => {
            trace => 1,
            default => 1,
        },
    );

Optioanl. A hashref of POE Session options to pass to the component's session.

debug

    my $poco = POE::Component::Archive::Any->spawn(
        debug => 1
    );

When set to a true value turns on output of debug messages. Defaults to: 0.

METHODS

These are the object-oriented methods of the components.

extract

    $poco->extract( {
            event       => 'results_event',     # mandatory
            file        => 'archive.tar.gz',    # mandatory
            type        => 'tar.gz',            # optional
            just_info   => 1,                   # optional
            dir         => 'exctract_dir',      # optional
            session     => 'other_session',     # optional
            _user       => 'random',            # optional
        }
    );

Instructs the component to get archive's information as well as extract it (the extraction step can be omited). Takes a hashref of options. See extract event description for more information.

session_id

    my $poco_id = $poco->session_id;

Takes no arguments. Returns component's session ID.

shutdown

    $poco->shutdown;

Takes no arguments. Shuts down the component.

ACCEPTED EVENTS

extract

    $poe_kernel->post( arch => extract => {
            event       => 'results_event',     # mandatory
            file        => 'archive.tar.gz',    # mandatory
            type        => 'tar.gz',            # optional
            just_info   => 1,                   # optional
            dir         => 'exctract_dir',      # optional
            session     => 'other_session',     # optional
            _user       => 'random',            # optional
        }
    );

Instructs the component to get archive's information as well as extract it (the extraction step can be omited). Takes a hashref of options. The possible keys/values of that hashref are as follows:

event

    { event => 'results_event', }

Mandatory. Specifies the name of the event to emit when results are ready. See OUTPUT section for more information.

file

    { file => 'archive.tar.gz' }

Mandatory. Specifies the filename of the archive to get information about or exctract.

type

    { type => 'tar.gz' }

Optional. Specifies the type of the archive. If not specified Archive::Any will work its magic to try to figure it out on its own.

just_info

Optional. When just_info key's value is set to a true value component will NOT extract the archive or create archive extraction directory (see dir argument below). This is useful when you just want to get information about the archive, such as what files it contains without actually extracting anything. Defaults to: 0 (meaning the component will exctract the archive).

dir

    { dir => 'exctract_dir' }

Optional. Specifies the directory into which the archive should be extracted. Unless just_info argument (see above) is set to a true value, the directory will be created if it doesn't exist. Defaults to: current working directory.

session

    { session => $some_other_session_ref }
    
    { session => 'some_alias' }
    
    { session => $session->ID }

Optional. An alternative session alias, reference or ID that the response should be sent to. Defaults to: sending session.

user defined

    {
        _user    => 'random',
        _another => 'more',
    }

Optional. Any keys starting with _ (underscore) will not affect the component and will be passed back in the result intact.

shutdown

    $poe_kernel->post( arch => 'shutdown' );

Takes no arguments. Tells the component to shut itself down.

OUTPUT

    $VAR1 = {
        'is_naughty' => 0,
        'is_impolite' => 0,
        'files' => [
            'POE-Component-WWW-WebDevout-BrowserSupportInfo-0.01/',
            'POE-Component-WWW-WebDevout-BrowserSupportInfo-0.01/README',
        ],
        'dir'  => '/tmp',
        'file' => 't.tar.gz',
        'type' => 'application/x-gzip',
        _user  => 'random',
    };

The event handler set up to handle the event which you've specified in the event argument to extract() method/event will recieve input in the $_[ARG0] in a form of a hashref. The possible keys/value of that hashref are as follows:

is_naughty

    { 'is_naughty' => 0 }

Will be set to a true value if archive is going to unpack outside the current directory (or dir if specified; see extract() method/event description), otherwise will be set to a false value.

is_impolite

    { 'is_impolite' => 0 }

Will be set to a true value if archive is going to unpack into the current directory (or dir if specified; see extract() method/event description) rather than create its own; otherwise is_impolite key will be set to a false value.

files

    {
        'files' => [
            'POE-Component-WWW-WebDevout-BrowserSupportInfo-0.01/',
            'POE-Component-WWW-WebDevout-BrowserSupportInfo-0.01/README',
        ],
    }

Will contain an arrayref elements of which are files that the archive contains.

dir

    { dir => '/tmp' }

The dir key will contain the directory into which the archive was (or could have been, depending on the just_info option to extract()) extracted. This will be whatever you have provided to the extract() event/method.

file

The file key will contain the filename of the archive which was processed by extract(). This will be whatever you've provided to the extract() event/method.

type

    { 'type' => 'application/x-gzip' }

The type key will contain the mime-type of the archive.

user defined

    { '_user' => 'random' }

Any arguments beginning with _ (underscore) passed into the extract() event/method will be present intact in the result.

AUTHOR

Zoffix Znet, <zoffix at cpan.org> (http://zoffix.com, http://haslayout.net)

BUGS

Please report any bugs or feature requests to bug-poe-component-archive-any at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=POE-Component-Archive-Any. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc POE::Component::Archive::Any

You can also look for information at:

• RT: CPAN's request tracker

  http://rt.cpan.org/NoAuth/Bugs.html?Dist=POE-Component-Archive-Any

• AnnoCPAN: Annotated CPAN documentation

  http://annocpan.org/dist/POE-Component-Archive-Any

• CPAN Ratings

  http://cpanratings.perl.org/d/POE-Component-Archive-Any

• Search CPAN

  http://search.cpan.org/dist/POE-Component-Archive-Any

COPYRIGHT & LICENSE

Copyright 2008 Zoffix Znet, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm POE::Component::Archive::Any

perl -MCPAN -e shell
install POE::Component::Archive::Any