use Sysadm::Install qw(:all);

  my $INST_DIR = '/home/me/install/';

  cd($INST_DIR);
  cp("/deliver/someproj.tgz", ".");
  untar("someproj.tgz");
  cd("someproj");

     # Write out ...
  blurt("Builder: Mike\nDate: Today\n", "build.dat");

     # Slurp back in ...
  my $data = slurp("build.dat");

     # or edit in place ...
  pie(sub { s/Today/scalar localtime()/ge; $_; }, "build.dat");

  make("test install");

     # run a cmd and tap into stdout and stderr
  my($stdout, $stderr, $exit_code) = tap("ls", "-R");

Copy a file from CW$source to CW$target. CWtarget can be a directory. Note that CWcp doesn't copy file permissions. If you want the target file to reflect the source file's user rights, use CWperm_cp() shown below. Move a file from CW$source to CW$target. CWtarget can be a directory. Download a file specified by CW$url and store it under the name returned by CWbasename($url). Untar the tarball in CW$tarball, which typically adheres to the CWsomeproject-X.XX.tgz convention. But regardless of whether the archive actually contains a top directory CWsomeproject-X.XX, this function will behave if it had one. If it doesn't have one, a new directory is created before the unpacking takes place. Unpacks the tarball into the current directory, no matter where the tarfile is located. Please note that if you're using a compressed tarball (.tar.gz or .tgz), you'll need IO::Zlib installed. Untar the tarball in CW$tgz_file in directory CW$dir. Create CW$dir if it doesn't exist yet. Ask the user to pick an item from a displayed list. CW$prompt is the text displayed, CW$options is a referenc to an array of choices, and CW$default is the number (starting from 1, not 0) of the default item. For example,

    pick("Pick a fruit", ["apple", "pear", "pineapple"], 3);

will display the following:

    [1] apple
    [2] pear
    [3] pineapple
    Pick a fruit [3]>

If the user just hits Enter, pineapple (the default value) will be returned. Note that 3 marks the 3rd element of the list, and is not an index value into the array. If the user enters CW1, CW2 or CW3, the corresponding text string (CW"apple", CW"pear", CW"pineapple" will be returned by CWpick(). Ask the user to either hit Enter and select the displayed default or to type in another string. Create a directory of arbitrary depth, just like CWFile::Path::mkpath. Delete a directory and all of its descendents, just like CWrm -rf in the shell. chdir to the given directory. chdir back to the last directory before a previous CWcd. Call CWmake in the shell. Simulate perl -pie 'do something' file. Edits files in-place. Expects a reference to a subroutine as its first argument. It will read out the file CW$filename line by line and calls the subroutine setting a localized CW$_ to the current line. The return value of the subroutine will replace the previous value of the line. Example:

    # Replace all 'foo's by 'bar' in test.dat
        pie(sub { s/foo/bar/g; $_; }, "test.dat");

Works with one or more file names. Simulate perl -ne 'do something' file. Iterates over all lines of all input files and calls the subroutine provided as the first argument. Example:

    # Print all lines containing 'foobar'
        plough(sub { print if /foobar/ }, "test.dat");

Works with one or more file names. Slurps in the file and returns a scalar with the file's content. If called without argument, data is slurped from STDIN or from any files provided on the command line (like <> operates). Opens a new file, prints the data in CW$data to it and closes the file. If CW$append is set to a true value, data will be appended to the file. Default is false, existing files will be overwritten. Run a command CW$cmd in the shell, and pass it CW@args as args. Capture STDOUT and STDERR, and return them as strings. If CW$exit_code is 0, the command succeeded. If it is different, the command failed and CW$exit_code holds its exit code. Please note that CWtap() is limited to single shell commands, it won't work with output redirectors (CWls >/tmp/foo 2>&1). In default mode, CWtap() will concatenate the command and args given and create a shell command line by redirecting STDERR to a temporary file. CWtap("ls", "/tmp"), for example, will result in

    'ls' '/tmp' 2>/tmp/sometempfile |

Note that all commands are protected by single quotes to make sure arguments containing spaces are processed as singles, and no globbing happens on wildcards. Arguments containing single quotes or backslashes are escaped properly. If quoting is undesirable, CWtap() accepts an option hash as its first parameter,

    tap({no_quotes => 1}, "ls", "/tmp/*");

which will suppress any quoting:

    ls /tmp/* 2>/tmp/sometempfile |

Or, if you prefer double quotes, use

    tap({double_quotes => 1}, "ls", "/tmp/$VAR");

wrapping all args so that shell variables are interpolated properly:

    "ls" "/tmp/$VAR" 2>/tmp/sometempfile |

Put a string in double quotes and escape all sensitive characters so there's no unwanted interpolation. E.g., if you have something like

   print "foo!\n";

and want to put it into a double-quoted string, it will look like

    "print \"foo!\\n\""

Sometimes, not only backslashes and double quotes need to be escaped, but also the target environment's meta chars. A string containing

    print "$<\n";

needs to have the '$' escaped like

    "print \"\$<\\n\";"

if you want to reuse it later in a shell context:

    $ perl -le "print \"\$<\\n\";"
    1212

CWqquote() supports escaping these extra characters with its second, optional argument, consisting of a string listing all escapable characters:

    my $script  = 'print "$< rocks!\\n";';
    my $escaped = qquote($script, '!$'); # Escape for shell use
    system("perl -e $escaped");

    => 1212 rocks!

And there's a shortcut for shells: By specifying ':shell' as the metacharacters string, qquote() will actually use '!$`'. For example, if you wanted to run the perl code

    print "foobar\n";

via

    perl -e ...

on a box via ssh, you would use

    use Sysadm::Install qw(qquote);

    my $cmd = 'print "foobar!\n"';
       $cmd = "perl -e " . qquote($cmd, ':shell');
       $cmd = "ssh somehost " . qquote($cmd, ':shell');

    print "$cmd\n";
    system($cmd);

and get

    ssh somehost "perl -e \"print \\\"foobar\\\!\\\\n\\\"\""

which runs on CWsomehost without hickup and prints CWfoobar!. Sysadm::Install comes with a script CWone-liner (installed in bin), which takes arbitrary perl code on STDIN and transforms it into a one-liner:

    $ one-liner
    Type perl code, terminate by CTRL-D
    print "hello\n";
    print "world\n";
    ^D
    perl -e "print \"hello\\n\"; print \"world\\n\"; "

Similar to CWqquote(), just puts a string in single quotes. Read the CW$src file's user permissions and modify all CW$dst files to reflect the same permissions. Read the CW$filename's user permissions and owner/group. Returns an array ref to be used later when calling CWperm_set($filename, $perms). Set file permissions and owner of CW$filename according to CW$perms, which was previously acquired by calling CWperm_get($filename). Run a shell command via CWsystem() and die() if it fails. Also works with a list of arguments, which are then interpreted as program name plus arguments, just like CWsystem() does it. Run a command in the shell and simulate a user hammering the ENTER key to accept defaults on prompts. Alias for CWprint ..., "\n", just like Perl6 is going to provide it. Check if the current script is running as root. If yes, continue. If not, restart the current script with all command line arguments is restarted under sudo:

    sudo scriptname args ...

Make sure to call this before any CW@ARGV-modifying functions like CWgetopts() have kicked in. Search all directories in CW$PATH (the ENV variable) for an executable named CW$program and return the full path of the first hit. Returns CWundef if the program can't be found. Opens a file handle to read the output of the following process:

    cd $dir; find ./ -xdev -print0 | cpio -o0 |

This can be used to capture a file system structure. Opens a file handle to write to a

    | (cd $dir; cpio -i0)

process to restore a file system structure. To be used in conjunction with fs_read_open. Reads from CW$in and writes to CW$out, using sysread and syswrite. The buffer size used defaults to 4096, but can be set explicitely. Format the data string in CW$data so that it's only (roughly) CW$maxlen characters long and only contains printable characters. If CW$data contains unprintable character's they are replaced by . (the dot). If CW$data is longer than CW$maxlen, it will be formatted like

    (22)[abcdef[snip=11]stuvw]

indicating the length of the original string, the beginning, the end, and the number of 'snipped' characters.