MAN page from Mandrake Other perl-Startup-0.103-1.i386.rpm

Startup

Section: User Contributed Perl Documentation (3)
Updated: perl 5.004, patch 04
Index

NAME

Startup - A program flow utility.

ALPHA version as of $Date: 1998/04/28 00:38:41 $

SYNOPSIS

Have a look at demonstration utility ``replace'' and at more detaileddescription below. It might be useful to use ``replace'' generally asframe for new programs.

DESCRIPTION

As developing with perl you certainly appreciate it to write easily nifty programs. Unfortunately a bunch of boring problems makes life uncomfortable.With some of them I had to deal so often, that I created this little collection. Imagine:

-: You want to have an option to work on files recursively.
-: You want some modules to print some info during work, but this outputwould hardly be predictable and thus might destroy your program output.
-: You want to have a little logfile reporting actions.
-: You want to report errors, but not via ``die'', and you dislike to writetrapping code all the time.

This module shall contribute to solve those problems, making your your programs more valuable.

INIT METHODS

new

$S = new S

This is the modules constructor. Some basic initializations are done,as there are: msg_reset and forbid_logging are called; err_strpat,err_infopat and log_openpat are initialized and log_threshold is setto infinity.

init

1 = $S -> init ({
   SUB_FILES  => \&sub,    # no default
   SUB_STREAM => \&sub,    # no default
   PROG_DATE  => $date,    # no default
   PROG_NAME  => $name,    # no default
   PROG_VER   => $version, # no default
   DIRMODE    => $string,  # Default: ``0700''
   FILEMODE   => $string,  # Default: ``0600''
   FROM_STDIN => 1||0,     # Default: 0
   RECURSE    => 1||0,     # Default: 0
   RELATIVE   => 1||0,     # Default: 0
   DESTPATH   => $path,    # Default: `.'
   SRCPATH    => $path,    # Default: `.'
   LOGPATH    => $path,    # Default: ``$prog_name.log''})

This method you normally will have to call. Via this you pass informationlike recursive and / or relative mode, program name and version and so on.Init method will provide some default values.

Init is called with an anonymous hash as parameter list. Each parameteryou can change afterwards with an extra method. Quite necessary (but thisdepends on your wishes) is to init at least SUB_FILES and PROG_NAME.

go

1||0 = $S -> go (@pathes)

Works differently for stream mode and file mode. Anyway go will calla function in your application, that needs to return a true value (1) if successful. If your function returns a zero, go will call msg_error().

Method go normally always returns 1. Zero is returned, when SUB_FILESor SUB_STREAM is needed but not defined, or if src_base or currentdirectory is not available.

go: stream mode

Message mode is set to silent. Function provided via SUB_STREAM is called with parameter dest_path.

go: file mode

Function provided via SUB_FILES is called for each input file. Parametersare (Source_purepath $sp, Source_purefilename $sf, Destination_path$dp, $status).

Thus path for input file would be: ``$sp/$sf''. $dp will be the path provided via DESTPATH if either relative mode is unset, or the input filepath is not relative to the path provided via SRCPATH. If in relative modeand input file has a path relative to SRCPATH, $dp will get that relativepart starting from DESTPATH.

$status will be 1 if input file is a file, 0 if file doesn't exist and -1 if file is no file but a directory.

sub_stream

\&function = $S -> sub_stream ([\&function])

Returns (optionally sets) the function doing the work when in stream mode.

sub_files

\&function = $S -> sub_files ([\&function])

Returns (optionally sets) the function doing the work when in file mode.

src_base

$path = $S -> src_base ([$path])

Returns (optionally sets) the base path for source input files.

dest_base

$path = $S -> dest_base ([$path])

Returns (optionally sets) the base destination path for your output files.

from_stdin

1||0 = $S -> from_stdin ([1||0])

Returns (optionally sets) stream mode.

dir_mode

$mode_string = $S -> dir_mode ([$mode_string])

Returns (optionally sets) the owning mode when creating a new directory.Mode is evaluated as an octal number in string representation, e.g. ``0700''.

file_mode

$mode_string = $S -> file_mode ([$mode_string])

Returns (optionally sets) the owning mode when creating a file (as of nowthis is only when creating logfile). Mode is evaluated as an octal number in string representation, e.g. ``0700''.

recurse

1||0 = $S -> recurse ([1||0])

Returns (optionally sets) recurse mode. When in recurse mode, directoriesand directories in directories and ... of input file list will be scanned also.

relative

1||0 = $S -> relative ([1||0])

Returns (optionally sets) relative mode. Effects only in recurse mode. When in relative mode, output pathes will be created according to input path structurerelatively to input base path. E.g.:

Input base path is /cdrom. Scan path is /cdrom. Output path is ..Then starting at path . the same directory structure as in /cdrom/ wouldbe created and passed to sub_files function as output path.

prog_date

$date = $S -> prog_date ([$date])

Returns (optionally sets) date of application programs creation.

prog_name

$name = $S -> prog_name ([$name])

Returns (optionally sets) name of application program.

prog_ver

$ver = $S -> prog_ver ([$ver])

Returns (optionally sets) version of application program.

ERROR METHODS

Error is just a way to get around $!. It is little more than a place to store an error message. It allows you to return 0 as error indicator in a pure procedurale way over several returns and still to comprise ``last error''information.

error: 0 = $S -> error ($string, $number, $longinfo)
Saves error message $string, error number $number, extra errorinformation $longinfo and caller() info. Returns always zero.
err_caller: \@err_caller = $S -> err_caller ([caller()])
Returns (and optionally sets) a reference to a caller() array (see: manperlfunc). It has the entries (package, filename, line). It is automatically set to ``caller()'' when calling error method.
err_info: $err_info = $S -> err_info ([$err_info])
Returns (and optionally sets) error info message, formatted according toerr_infopat.
err_infopat: $err_infopat = $S -> err_infopat ([$err_infopat])
Gimmick pattern for method err_info. Defaults to '$err_info'.(See method gimmick below at misc section for details)
err_num: $err_num = $S -> err_num ([$err_num])
Returns (and optionally sets) error number.
err_str: $err_str = $S -> err_str ([$err_str])
Returns (and optionally sets) error message, formatted according to err_strpat.
err_strpat: $err_strpat = $S -> err_strpat ([$err_strpat])
Gimmick pattern for method err_str. Defaults to '$err_package: $err_str'.(See method gimmick below at misc section for details)

MESSAGE METHODS

Message is a userEss interface allowing you to pass some runtime informationto stdout.

msg: 1 = $S -> msg ($str)
Prints message $str. Appends ':' if it is 1st message, inserts ' ' if it is 2nd, appends ', ' otherwise.
msg_error: 0 = $S -> msg_error ([str])
Calls msg_nl ("error!") and then msg ("Error: " . $S-err_str())>.Latter message will be sent even in ``silent'' mode (see msg_silent).
msg_finish: 1 = $S -> msg_finish ($str)
Calls msg_nl ("$msg.") unless msg_finish is already called.
msg_nl: 1 = $S -> msg_nl ($str)
Prints message $str with a trailing newline \n. Disables internal ``continue'' mode: further messages will always be sent as msg_nl.
msg_warn: 1 = $S -> msg_warn ($str)
Appends a '!' to message $str.

MESSAGE INIT METHODS

charset: $charset_id = $S -> charset ($charset_id)
Sets standard character set to $charset_id. It defaults to $ENV{LC_CTYPE}.It's main purpose is for future releases.
msg_reset: $S = $S -> msg_reset ()
Resets message variables to default values. You will call this normallyalways when starting a new work a la: `Processing xyz'.
msg_autoindent: 1||0 = $S -> msg_autoindent ([1||0])
Defaults to 1. Returns (optionally sets) autoindent mode. When set,msg_indent will be automatically set to the position after the first whitespace in the first message. (see also msg_beauty)
msg_beauty: 1||0 = $S -> msg_beauty ([1||0])
Defaults to 1. Returns state of (optionally sets) ``beauty'' mode. When an output line gets longer than msg_maxcolumn and internal ``continue'' mode is set, a newline and an indent is inserted. Internal continue mode is unset when callingmsg_nl method.
msg_indent: $pos = $S -> msg_indent ([$pos])
Defaults to 4. Returns (optionally defines) the indent for beauty mode. This value is overridden when msg_autoindent is set.
msg_maxcolumn: $pos = $S -> msg_maxcolumn ([$pos])
Defaults to 79. Returns (optionally sets) the maximal length of an outputline, when in beauty mode.
msg_silent: 1||0 = $S -> msg_silent ([1||0])
Defaults to 0. Returns (optionally sets) silent mode. When set to 1, no message except error messages will be printed to stdout.

LOGGING METHODS

allow_logging: 1 = $S -> allow_logging ()
You have to call this to enable logging.
forbid_logging: 0 = $S -> forbid_logging ()
This is default. It forbids methods open_log and log, so that they willreturn always an error. No logfile will be opened, no log entry beingwritten.
log_openpat: $pat = $S -> log_openpat ([I<$pat])
Returns (optionally sets) the gimmick pattern used for log opening entries.Defaults to: '---------- $date, $prog_name $prog_ver '."(perl $])\n"
log_path: $path = $S -> log_path ([$path])
Returns (optionally sets) path/name of logfile to $path. This overridesthe default value set when calling S->init. Default is filebasename($prog_name).".log" in current directory.
open_log: 1||0 = $S -> open_log ()
Opens the logfile $S -> log_path.
close_log: 1 = $S -> close_log ()
Closes logfile.
log: 1||0 = $S -> log ($msg, $pri, $threshold)
Adds a log message $msg, getting the priority character $pri.If a threshold is given, log this entry only if threshold is smalleror equal $S -> log_threshold.
log_threshold: $threshold = $S -> log_threshold ([$threshold])
Defaults to 0xffffffff. Returns (optionally sets) logging threshold. If set, only log calls with a threshold smaller or equal than this threshold will be logged.

REDIRECTION METHODS

catch_output

1||0 = $S -> catch_output([$mode_path])

1||0 = $S -> catch_stdout([$mode_path])

1||0 = $S -> catch_stderr([$mode_path])

catch_output File mode

If parameter $mode_path is specified, STDOUT+STDERR / STDOUT / STDERRwill be redirected to a file. $mode_path is simply given to an open call, so you might use this like:

 $S -> catch_output(">>my_stdout_stderr.txt");

catch_output Pipe mode

If parameter $mode_path is omitted, STDOUT+STDERR / STDOUT / STDERR will be sent to the input of a child process. This will check it's inputif it is according to catch_output_pattern. If so, it will send STDOUTmessages to $S->msg and STDERR messages to $S->msg_error.

Note, that $S->msg and $S->msg_error are sending their outputto your STDOUT.

If you like to get the output passed catch_output_pattern yourself rather thanprinting it via msg or msg_error, you can pass a code reference to catch_output_sub. This function will then be called with matched output as parameter.

catch_output_sub

\&sub = $S -> catch_output_sub([\&sub])

\&sub = $S -> catch_stdout_sub([\&sub])

\&sub = $S -> catch_stderr_sub([\&sub])

Returns (optionally sets) the code reference, that will be called whensome output passed catch_output_pattern in Pipe mode.

restore_output

1||0 = $S -> restore_output()

1||0 = $S -> restore_stdout()

1||0 = $S -> restore_stderr()

Restores the output that has been redirected via catch_output.

catch_output_pattern

$pattern = $S -> catch_output_pattern([$pattern])

$pattern = $S -> catch_stdout_pattern([$pattern])

$pattern = $S -> catch_stderr_pattern([$pattern])

When output is redirected, only those output lines will be regarded, thatmatch $1 of this pattern. Default is: '^(.*)$'.

MISCELLANEOUS METHODS

gimmick

$gimicked_string = $Startup -> gimmick ($control_string)

Replaces certain strings in a control string. You can use:

   $S             Seconds   $M             Minutes   $H             Hour   $d             day   $m             month   $y             year   $date          '$d.$m.$y'   $time          '$H:$M:$S'

   $err_str       current error string   $err_num       current error number   $err_info      current error info (longer text)   $err_package   package calling error method   $err_filename  filename of package   $err_line      line in package calling error method

   $prog_name     program name (if set by application)   $prog_date     program date (if set by application)   $prog_ver      program version (if set by application)

TO DO

Lots.

AUTHOR

Martin Schwartz <schwartzAATTcs.tu-berlin.de>

This document was created byman2html,using the manual pages.