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)
  	

• $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.