NAME

Startup - A program flow utility.

ALPHA version as of $Date: 1998/02/21 17:39:21 $

SYNOPSIS

Have a look at demonstration utility "replace" and at more detailed description below. It might be useful to use "replace" generally as frame 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 output would 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 write trapping 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 set to 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 information like 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 parameter you can change afterwards with an extra method. Quite necessary (but this depends 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 call a 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_FILES or SUB_STREAM is needed but not defined, or if src_base or current directory 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. Parameters are (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 file path is not relative to the path provided via SRCPATH. If in relative mode and input file has a path relative to SRCPATH, $dp will get that relative part 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 now this 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, directories and 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 structure relatively 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/ would be 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 error information $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: man perlfunc). 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 to err_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 information to 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 normally always 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 calling msg_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 output line, 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 will return always an error. No logfile will be opened, no log entry being written.

log_openpat

$pat = $S -> log_openpat ([$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 overrides the default value set when calling S->init. Default is file basename($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 smaller or 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 / STDERR will 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 input if it is according to catch_output_pattern. If so, it will send STDOUT messages to $S->msg and STDERR messages to $S->msg_error.

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

If you like to get the output passed catch_output_pattern yourself rather than printing 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 when some 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, that match $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.

SEE ALSO

AUTHOR

Martin Schwartz <schwartz@cs.tu-berlin.de>

cpanm Startup

perl -MCPAN -e shell
install Startup