NAME
Archive::Rar::Passthrough - Thinnest possible wrapper around 'rar'
SYNOPSIS
use Archive::Rar::Passthrough;
my $rar = Archive::Rar::Passthrough->new();
if (not $rar) {
print "Could not find your 'rar' command'.\n";
}
my $errorcode = $rar->run(
command => 'a',
switches => ['-cl'], # optional
archive => 'my.rar',
filelist_files => [ 'some_text_file_with_file_names' ],
files => ['file1.txt', 'file2.txt'],
path => 'some_path_for_extraction', # optional
);
if ($errorcode) {
print "There was an error running 'rar': " . $rar->explain_error($retval) . "\n";
my $output = $rar->get_stdout();
my $errors = $rar->get_stderr();
print "The 'rar' command said (if anything):\n" . $output
. "\nAnd spammed on STDERR:\n" . $errors . "\n";
}DESCRIPTION
This module is a very, very thin wrapper around running the rar command. If you have ever dealed with running external programs with command line parameters from your code portably, you most certainly know that it is a lot of pain. This module uses IPC::Cmd to run rar, so it should be reasonably portable.
Unlike Archive::Rar, this just takes a small bit of the pain out of running rar directly. You still have to know the interface. But it should not be necessary to escape your file names of the contain funny characters. Note that Archive::Rar does not currently help you with this.
The module tries to locate the rar command (from PATH or from regedit for Win32). You may specify the 'rar' instance to use with the rar parameter to the constructor:
my $rar = Archive::Rar::Passthrough->new(rar => 'path/to/rar');The constructor returns the empty list (i.e. false) instead of an object if the rar binary was not found.
The object returned from new() has very little state. It does not remember things like the previous archive it worked on. It only knows what 'rar' binary to use and the output (STDOUT and STDERR) of the previous invocation 'rar'.
METHODS
new
The constructor returns a new Archive::Rar::Passthrough object if it found a rar binary to use. Takes a single named, optional parameter: rar = 'path/to/rar'>.
You can also use $obj-new()> to clone an Archive::Rar::Passthrough object.
run
Runs the rar binary. Takes named arguments which correspond to the rar usage: (from RAR 3.70)
Usage: rar <command> -<switch 1> -<switch N> <archive> <files...>
<@listfiles...> <path_to_extract\>Mandatory arguments:
command: string indicating the command (example 'e' for extraction)
archive: string indicating the RAR archive file to operate onOptional arguments:
switches: array reference to array of command line options.
Defaults to ['-y'].
files: list of files to add/whatever. Array reference
filelist_files: list of files to use as file list input.
Array reference
path: path to extract toPlease note that by default, the -y switch is passed to rar. That means all interactive questions from rar are answered with yes as there is no way to for the user to communicate with rar. However, this also means that files will be overwritten by default!
explain_error
Given an error code / number as return by the run() method, this method will return an explanation of the error. It's the same text as that in the "RAR RETURN CODES" section below.
get_binary
Returns the path of the rar binary that's being used.
set_binary
Set the path of the rar binary to use.
get_stdout
Returns the output (STDOUT) of the previous invocation of rar.
get_stderr
Returns the error output (STDERR) of the previous invocation of rar.
clear_buffers
Clears the STDOUT and STDERR buffers of the object. You really only need to call this if you're paranoid about memery usage.
RAR RETURN CODES
The run() method returns a numerical code indicating the success or failure type of the command. Quoting the documentation of RAR 3.70 beta 1:
RAR exits with a zero code (0) in case of successful operation. The exit
code of non-zero means the operation was cancelled due to an error:
255 USER BREAK User stopped the process
9 CREATE ERROR Create file error
8 MEMORY ERROR Not enough memory for operation
7 USER ERROR Command line option error
6 OPEN ERROR Open file error
5 WRITE ERROR Write to disk error
4 LOCKED ARCHIVE Attempt to modify an archive previously locked
by the 'k' command
3 CRC ERROR A CRC error occurred when unpacking
2 FATAL ERROR A fatal error occurred
1 WARNING Non fatal error(s) occurred
0 SUCCESS Successful operationThere may be other codes in future versions of 'rar'. Error 9 - CREATE ERROR, for example, was not present in version 2.80.
The explanations above can be accessed by your code through the explain_error($errno) method.
AUTHORS
Steffen Mueller <smueller@cpan.org>
The code for finding a rar instance in the Windows registry stems from Archive::Rar, written by jean-marc boulade <jmbperl@hotmail.com>.
COPYRIGHT AND LICENSE
Copyright (c) 2008 Steffen Mueller.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
The code for testing an executable is from Module::Install::Can. It is carries: Copyright 2002, 2003, 2004, 2005, 2006 by Brian Ingerson, Audrey Tang, Adam Kennedy.
The code for determination of the rar binary from the Windows registry is copyright (c) 2002-2006 jean-marc boulade.
Both of these contributions carry the same license that is stated above.
RAR DOCUMENTATION
This is the help message of the rar command as found on my computer. Your milage may vary!
RAR 3.70 beta 1 Copyright (c) 1993-2007 Alexander Roshal 8 Jan 2007
Shareware version Type RAR -? for help
Usage: rar <command> -<switch 1> -<switch N> <archive> <files...>
<@listfiles...> <path_to_extract\>
<Commands>
a Add files to archive
c Add archive comment
cf Add files comment
ch Change archive parameters
cw Write archive comment to file
d Delete files from archive
e Extract files to current directory
f Freshen files in archive
i[par]=<str> Find string in archives
k Lock archive
l[t,b] List archive [technical, bare]
m[f] Move to archive [files only]
p Print file to stdout
r Repair archive
rc Reconstruct missing volumes
rn Rename archived files
rr[N] Add data recovery record
rv[N] Create recovery volumes
s[name|-] Convert archive to or from SFX
t Test archive files
u Update files in archive
v[t,b] Verbosely list archive [technical,bare]
x Extract files with full path
<Switches>
- Stop switches scanning
ad Append archive name to destination path
ag[format] Generate archive name using the current date
ap<path> Set path inside archive
as Synchronize archive contents
av Put authenticity verification (registered versions only)
av- Disable authenticity verification check
c- Disable comments show
cfg- Disable read configuration
cl Convert names to lower case
cu Convert names to upper case
df Delete files after archiving
dh Open shared files
ds Disable name sort for solid archive
e[+]<attr> Set file exclude and include attributes
ed Do not add empty directories
en Do not put 'end of archive' block
ep Exclude paths from names
ep1 Exclude base directory from names
ep3 Expand paths to full including the drive letter
f Freshen files
hp[password] Encrypt both file data and headers
id[c,d,p,q] Disable messages
ierr Send all messages to stderr
ilog[name] Log errors to file (registered versions only)
inul Disable all messages
isnd Enable sound
k Lock archive
kb Keep broken extracted files
m<0..5> Set compression level (0-store...3-default...5-maximal)
mc<par> Set advanced compression parameters
md<size> Dictionary size in KB (64,128,256,512,1024,2048,4096 or A-G)
ms[ext;ext] Specify file types to store
n<file> Include only specified file
n@ Read file names to include from stdin
n@<list> Include files in specified list file
o+ Overwrite existing files
o- Do not overwrite existing files
ol Save symbolic links as the link instead of the file
or Rename files automatically
ow Save or restore file owner and group
p[password] Set password
p- Do not query password
r Recurse subdirectories
r0 Recurse subdirectories for wildcard names only
rr[N] Add data recovery record
rv[N] Create recovery volumes
s[<N>,v[-],e] Create solid archive
s- Disable solid archiving
sc<chr><obj> Specify the character set
sfx[name] Create SFX archive
si[name] Read data from standard input (stdin)
sl<size> Process files with size less than specified
sm<size> Process files with size more than specified
t Test files after archiving
ta<date> Process files modified after <date> in YYYYMMDDHHMMSS format
tb<date> Process files modified before <date> in YYYYMMDDHHMMSS format
tk Keep original archive time
tl Set archive time to latest file
tn<time> Process files newer than <time>
to<time> Process files older than <time>
ts<m,c,a>[N] Save or restore file time (modification, creation, access)
u Update files
v Create volumes with size autodetection or list all volumes
v<size>[k,b] Create volumes with size=<size>*1000 [*1024, *1]
ver[n] File version control
vn Use the old style volume naming scheme
vp Pause before each volume
w<path> Assign work directory
x<file> Exclude specified file
x@ Read file names to exclude from stdin
x@<list> Exclude files in specified list file
y Assume Yes on all queries
z[file] Read archive comment from file