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 on

Optional 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 to

Please 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 operation

There 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

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

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