Why not adopt me?
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
CPAN Ratings
Search CPAN
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.