######################################################################
    Sysadm::Install 0.08
######################################################################

NAME
    Sysadm::Install - Typical installation tasks for system administrators

SYNOPSIS
      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) = tap("ls -R");

DESCRIPTION
    Have you ever wished for your installation shell scripts to run
    reproducably, without much programming fuzz, and even with optional
    logging enabled? Then give up shell programming, use Perl.

    "Sysadm::Install" executes shell-like commands performing typical
    installation tasks: Copying files, extracting tarballs, calling "make".
    It has a "fail once and die" policy, meticulously checking the result of
    every operation and calling "die()" immeditatly if anything fails.

  FUNCTIONS
    "cp($source, $target)"
        Copy a file from $source to $target. "target" can be a directory.
        Note that "cp" doesn't copy file permissions. If you want the target
        file to reflect the source file's user rights, use "perm_cp()" shown
        below.

    "mv($source, $target)"
        Move a file from $source to $target. "target" can be a directory.

    "download($url)"
        Download a file specified by $url and store it under the name
        returned by "basename($url)".

    "untar($tgz_file)"
        Untar the tarball in $tgz_file, which typically adheres to the
        "someproject-X.XX.tgz" convention. But regardless of whether the
        archive actually contains a top directory "someproject-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.

    "untar_in($tar_file, $dir)"
        Untar the tarball in $tgz_file in directory $dir. Create $dir if it
        doesn't exist yet.

    "pick($prompt, $options, $default)"
        Ask the user to pick an item from a displayed list. $prompt is the
        text displayed, $options is a referenc to an array of choices, and
        $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 1, 2 or 3, the corresponding text string
        ("apple", "pear", "pineapple" will be returned by "pick()".

    "ask($prompt, $default)"
        Ask the user to either hit *Enter* and select the displayed default
        or to type in another string.

    "mkd($dir)"
        Create a directory of arbitrary depth, just like
        "File::Path::mkpath".

    "rmf($dir)"
        Delete a directory and all of its descendents, just like "rm -rf" in
        the shell.

    "cd($dir)"
        chdir to the given directory.

    "cdback()"
        chdir back to the last directory before a previous "cd".

    "make()"
        Call "make" in the shell.

    "pie($coderef, $filename, ...)"
        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 $filename line by line and calls the subroutine
        setting a localized $_ 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.

    "plough($coderef, $filename, ...)"
        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.

    "my $data = slurp($file)"
        Slurps in the file and returns a scalar with the file's content.

    "blurt($data, $file, $append)"
        Opens a new file, prints the data in $data to it and closes the
        file. If $append is set to a true value, data will be appended to
        the file. Default is false, existing files will be overwritten.

    "($stdout, $stderr) = tap($cmd)"
        Rund a command $cmd in the shell, capture STDOUT and STDERR, and
        return them as strings.

    "$quoted_string = qquote($string, [$metachars])"
        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

        "qquote()" 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 "somehost" without hickup and prints "foobar!".

    "perm_cp($src, $dst, ...)"
        Read the $src file's user permissions and modify all $dst files to
        reflect the same permissions.

    "sysrun($cmd)"
        Run a shell command via "system()" and die() if it fails.

AUTHOR
    Mike Schilli, <m@perlmeister.com>

COPYRIGHT AND LICENSE
    Copyright (C) 2004 by Mike Schilli

    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself, either Perl version 5.8.3 or, at
    your option, any later version of Perl 5 you may have available.