NAME

IPTables::IPv4::DBTarpit::Inst - support for installation

SYNOPSIS

  use IPTables::IPv4::DBTarpit::Inst qw(
        soft_fail
        hard_fail
        ask_yesno
        ask_confirm
        ask_choice
        make_text
        cpfromto
        write_conf
        dialog
        verify
        osname
        :all
  }

  $zero = soft_fail($msg);
  (exits) hard_fail($msg);
  $rv = ask_yesno($question, $default);
  ask_confirm($description,$ref_to_setting);
  $option=ask_choice($question,["opt1","opt2"],"default");
  $text = make_text(\%hash);
  $rv = cpfromto($fromfile,$tofile);
  $rv = write_conf($file,$hashref,$prefix);
  dialog($name,$CONFIG,@defaults);
  verify($CONFIG);

DESCRIPTION

This module exports function used by the installation system scripts.

$zero = soft_fail($msg);
Prints out an error message and returns 0. Usually used to soft-fail a test like:
```
  return soft_fail("Couldn't find Postgres...") unless ...;
```
This is saves a few lines since the alternative would be:
```
  unless(...) {
    print "Couldn't find Postgres...\n";
    return 0;
  }
```
(exits) hard_fail($msg);
Prints out an error message surrounded by lines of hash marks and exits with code 1.
$rv = ask_yesno($question, $default);
Asks the user a yes/no question. Default to $default if they just press [return]. Returns 1 for a yes answer and 0 for no, where $default is set to 1 or 0;
ask_confirm($description,$ref_to_setting);
Asks the user to confirm a setting. If they enter a new value asks ``are you sure.'' Directly updates the setting and returns when done.
A default setting of ``NONE'' will force the user to enter a value.
$option=ask_choice($question,[``opt1'',``opt2''],``default'');
Asks the user to choose from a list of options. Returns the option selected.

$text = make_text(\%hash);
Returns a text string suitable of inclusion in a Makefile.

        i.e.

  %hash = (
        VALUE1  => '/some/path',
        VALUE2  => 'constant data',
        VALUE3  => '$(OTHERVAR)',
  );

  returns a text string containing:

  VALUE1 = /some/path
  VALUE2 = constant data
  VALUE3 = $(OTHERVAR)


=cut

sub make_text { my $hp = shift; my $text = ''; foreach(sort keys %$hp) { $text .= ``$_ = $hp->{$_}\n''; } return $text; }

$rv = cpfromto($fromfile,$tofile);
Copies a file ``from'' ``to''. Returns false on success. On failure it returns the name of the offending file that could not be opened with the reason append as `` write'' or `` read''.
$rv = write_conf($file,$hashref,$prefix);
Writes the contents of $hashref to $file. Returns false on success, else an error string describing the problem is returned. If $prefix is present then any ``key'' written must start with $prefix``.
```
  i.e. Takes a hash ref of the form below and writes a file.
```
```
  $hashref = {
        VALUE1  => 'something',
        VALUE2  => 'something else',
  };
```
```
  results are in a file that looks like:
```
# [file name] date & time # This file was automatically generated by [caller file name] # # Don't edit this file, edit [caller file name] instead. # my $CONFIG = { VALUE1 => 'something', VALUE2 => 'something else', }; $CONFIG;
dialog($name,$CONFIG,@defaults);
Updates %$CONFIG by engaging in a dialog with the user about module $name (only used a prompt). The user is asked to confirm or enter a new value for the @default array.
```
  input:        $name,          text string
                $CONFIG,        hash ref
                @defaults
```
```
  $CONFIG = {
        VALUE1  => 'something',
        VALUE2  => 'something else',
  };
```
```
  @defaults = (
        # key           
        'VALUE1',  'new thing', 'prompt for new',
        'VALUEA',  'new A',     'prompt for A',
  }
```
```
  returns:      nothing
```
VALUE1 is overwritten and the user prompted for new. VALUE2 is left untouched, VALUEA is prompted for A. %$CONFIG is updated.

For SpamCannibal users, warns if SPMCNBL_DAEMON_DIR and DBTP_DAEMON_DIR are not the same.
verify($CONFIG);
Verifies that conflicting parameters are not present in the configuration.
```
  input:        $CONFIG a hashref
  returns:      nothing
```
Aborts on invalid configuration.
$rv = osname();
Returns the operating system name in upper case letters. One or more spaces in the OS name are replaced with underscore.

EXPORT

        none by default

EXPORT_OK

        soft_fail
        hard_fail
        ask_yesno
        ask_confirm
        ask_choice
        make_text
        cpfromto
        write_conf
        dialog
        verify
        osname
        :all

ACKNOWLEDGEMENTS

Portions of this module were originally written by Sam Tregar <stregar@about-inc.com> as part of the Bricolage distribution. Nice work Sam, thanks!

AUTHORS

Sam Tregar <stregar@about-inc.com> Michael Robinton <michael@bizsystems.com>

COPYRIGHT & LICENSE

    Copyright 2003, Michael Robinton <michael@bizsystems.com>

    Copyright (c) 2001-2003 About.com

    All rights reserved.

    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions are
    met:

    *   Redistributions of source code must retain the above copyright
        notice, this list of conditions and the following disclaimer.

    *   Redistributions in binary form must reproduce the above copyright
        notice, this list of conditions and the following disclaimer in the
        documentation and/or other materials provided with the distribution.

    *   Neither the name of the About.com nor the names of its contributors
        may be used to endorse or promote products derived from this
        software without specific prior written permission.

    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
    IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
    TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
    PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR
    CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
    PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
    LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.