Description :
This module helps you write scripts that conform to best common practices,
quickly. Just include the above as a template, and your script will accept
all of the options that are included in the manual page, as well as
summarising them when you use the \'-h\' option.
(Unfortunately, it is not possible to have a `use\' dependency automatically
add structure to your POD yet, so you have to include the above manually.
If you want your help message and Perldoc to be meaningful, that is.)
Shortcuts are provided to help you abort or die with various error
conditions; all of which print the name of the program running (taken from
\'$0\' if not passed). The motive for this is that \"small\" scripts tend to
just get written and forgotten; so, when you have a larger system that is
built out of lots of these pieces it is sometimes guesswork figuring out
which script a printed message comes from!
For instance, if your program is called with invalid arguments, you may
simply call \'abort\' with a one-line message saying what the particular
problem was. When the script is run, it will invite the person running the
script to try to use the \'--help\' option, which gives them a summary and in
turn invites them to read the Perldoc. So, it reads well in the source;
AATTARGV and abort \"unexpected arguments: AATTARGV\";
$file or abort \"no filename supplied\";
And in the output;
somescript: no filename supplied!
Try `somescript --help\' for a summary of options
On the other hand, if you call \'barf\', then it is considered to be a hard
run-time failure, and the invitation to read the \'--help\' page to get usage
not given. Also, the messages are much tidier than you get with \'die\' et
al.
open FOO, \"< $file\" or barf \"failed to open $file; $!\";
Which will print:
somescript: failed to open somefile; Permission denied
Scriptalicious has no _hard_ dependancies; all the methods, save reading
passwords from the user, will work in the absence of extra installed
modules on all versions of Perl from 5.6.0 onwards.
To avoid unnecessary explicit importing of symbols, the following symbols
and functions are exported into the caller\'s namespace:
* \'$VERBOSE\'
Set to 0 by default, and 1 if \'-v\' or \'--verbose\' was found during the call
to \'getopt()\'. Extra \'-v\'\'s or \'--debug\' will push this variable higher. If
\'-q\' or \'--quiet\' is specified, this will be less than one.
* \'$PROGNAME\'
It is recommended that you only ever read this variable, and pass it in via
the import. This is not automatically extracted from the POD for
performance reasons.
* \'$CONFIG\'
Name of the configuration file. Set before a call to \'getconf\', or read
afterwards to see if a config file was used. New in Scriptalicious 1.16
* *getopt(AATTgetopt_args)*
Fetch arguments via \'Getopt::Long::GetOptions\'. The \'bundling\' option is
enabled by default - which differs from the standard configuration of
*Getopt::Long*. To alter the configuration, simply call
\'Getopt::Long::config\'. See Getopt::Long for more information.
* *getopt_lenient(AATTgetopt_args)*
Just like \'getopt()\', but doesn\'t cause a fatal error if there are any
unknown options.
* *getconf(AATTgetopt_args)*
Fetches configuration, takes arguments in the same form as *getopt()*..
The configuration file is expected to be in _~/.PROGNAMErc_,
_/etc/perl/PROGNAME.conf_, or _/etc/PROGNAME.conf_. Only the first found
file is read, and unknown options are ignored for the time being.
The file is expected to be in YAML format, with the top entity being a
hash, and the keys of the hash being the same as specifying options on the
command line. Using YAML as a format allows some simplificiations to
getopt-style processing - \'=s%\' and \'=sAATT\' style options are expected to be
in a real hash or list format in the config file, and boolean options must
be set to \'true\' or \'false\' (or some common equivalents).
Returns the configuration file as Load()\'ed by YAML in scalar context, or
the argument list it was passed in list context.
For example, this minimal script (missing the documentation, but hey at
least it\'s a start);
getopt getconf
( \"something|s\" => \\$foo,
\"invertable|I!\" => \\$invertable,
\"integer|i=i\" => \\$bar,
\"string|s=s\" => \\$cheese,
\"list|l=sAATT\" => \\AATTlist,
\"hash|H=s%\" => \\%hash, );
Will accept the following invocation styles;
foo.pl --help
foo.pl --version
foo.pl --verbose
foo.pl --debug
foo.pl --quiet
foo.pl --something
foo.pl --invertable
foo.pl --no-invertable < === FORM DIFFERS IN CONFIG FILE
foo.pl --integer=7
foo.pl --string=anything
foo.pl --list one --list two --list three
foo.pl --hash foo=bar --hash baz=cheese
Equivalent config files:
something: 1
invertable: on
invertable: off
integer: 7
string: anything
list:
- one
- two
- three
list: [ one, two, three ]
hash:
foo: bar
baz: cheese
Note that more complex and possibly arcane usages of Getopt::Long features
may not work with getconf (patches welcome).
This can be handy for things like database connection strings; all you have
to do is make an option for them, and then the user of the script, or a
SysAdmin can set up their own config file for the script to automatically
set the options.
* *getconf_f($filename, AATTgetopt_args)*
As *getconf()*, but specify a filename.
* *say \"something\"*
Prints a message to standard output, unless quiet mode (\'-q\' or \'--quiet\')
was specified. For normal program messages.
* *mutter \"progress\"*
Prints a message to standard output, if verbose mode (\'-v\') or debug mode
(\'-d\') is enabled (ie, if \'$VERBOSE > 0\'). For messages designed to help a
_user of the script_ to see more information about what is going on.
* *whisper \"detail\"*
Prints a message to standard output, if debug mode (\'-d\') is enabled or
multiple verbose options were passed (ie, if \'$VERBOSE > 1\'). For messages
designed to help a _person debugging the script_ to see more information
about what is going on internally to the script.
* *abort \"won\'t go to sea in a storm\"*
Prints a short program usage message (extracted from the POD synopsis) and
exits with an error code.
* *moan \"weather is miserable\"*
Prints a warning to standard error. It is preceded with the text
\'warning:\'. The program does not exit.
* *protest \"don\'t know the weather report\"*
Prints an error message to standard error. It is preceded with the text
\'error:\'. The program does not exit.
* *barf \"hit an iceberg\"*
Prints a warning to standard error. It is preceded with the text
\'warning:\'. The program does not exit.
* *run(\"command\", \"arg1\", \"arg2\")*
Runs a command or closure, barf\'s with a relevant error message if there is
a problem. Program output is suppressed unless running in verbose mode.
\'run()\' and the three alternatives listed below may perform arbitrary
filehandle redirection before executing the command. This can be a very
convenient way to do shell-like filehandle plumbing.
For example;
run( -in => sub { print \"Hello, world!\
\" },
-out => \"/tmp/outfile\",
-out2 => \"/dev/null\",
AATTcommand );
This will connect the child process\' standard input (\'-in\') to a closure
that is printing \"\'Hello, world!\
\'\". The output from the closure will
appear on standard input of the run command. Note that the closure is run
in a sub-process and so will not be able to set variables in the calling
program.
It will also connect the program\'s standard output (\'-out\') to
\'/tmp/outfile\', and its standard error (filehandle 2) to \'/dev/null\' (the
traditional way of junking error output).
If you wanted to connect two filehandles to the same place, you could pass
in \'GLOB\' references instead;
run( -out => \\*MYOUT,
-out2 => \\*MYOUT,
AATTcommand );
Any filehandle can be opened in any mode; \'-in\' merely defaults to meaning
\'-in0\', and \'-out\' defaults to meaning \'-out1\'. There is no \'-err\'; use
\'-out2\'. \'-rw\' exists (defaulting to \'-rw0\'), but is probably of limited
use.
Here is an example of using \'prompt_passwd()\' to hijack \'gpg\'\'s password
grabbing;
my $password = prompt_passwd(\"Encryption password: \");
my $encrypted = run( -in4 => sub { print \"$password\
\" },
\"gpg\", \"--passphrase-fd\", \"4\", \"-c\", $file )
* *run_err(\"command\", \"arg2\", \"arg1\")*
Same as run, but returns the error code rather than assuming that the
command will successfully complete. Again, output it suppressed.
* *capture(\"command\", \"1gra\", \"2gra\")*
runs a command, capturing its output, barfs if there is a problem. Returns
the output of the command as a list or a scalar.
* *capture_err(\"command\", \"foo\")*
Works as *capture*, but the first returned item is the error code of the
command ($?) rather than the first line of its output. Also, it only ever
returns the output as a list.
Usage:
my ($rc, AATToutput) = capture_err(\"somecommand\", AATTargs);
* *hush_exec()*
* *unhush_exec()*
\'hush_exec\' is used to indicate that the programs you are running are only
of interest to someone debugging the script. So, the messages showing
commands run and giving execution timings will not be printed without \'-vv\'
(double verbose) or \'-d\' (debug, which is the same thing).
* *start_timer()*
* *show_delta()*
* *show_elapsed()*
These three little functions are for printing run times in your scripts.
Times are displayed for running external programs with verbose mode
normally, but this will let you display running times for your main program
easily.
* *sci_unit($num, [$unit, $precision])*
Returns a number, scaled using normal scientific prefixes (from atto to
exa). Optionally specify a precision which is passed to sprintf() (see
perldoc/sprintf). The default is three significant figures.
From Scriptalicious 1.08, the \"u\" character is used in place of the Greek
\"mu\" due to encoding compatibility issues.
* *time_unit($num, [$precision])*
Converts a floating point number of seconds to a human-readable time, the
precision specifies the number of significant decimal digits, which is used
to compute a \"quanta\" for the value given, values below which are not
displayed. $precision defaults to 4.
examples:
time_unit(10.1) => \"10.10s\"
time_unit(1) => \"1.000s\"
time_unit(0.1) => \"100ms\"
time_unit(86401,2) => \"1d 0h\"
time_unit(86401,3) => \"1d 0h\"
time_unit(86401) => \"1d 0h:0m\"
time_unit(86400+3600/2) => \"1d 0h:30m\"
time_unit(86401,5) => \"1d 0h:0m:1s\"
time_unit(7*86400) => \"1w0d 0h\"
time_unit(-0.0002) => \"-200us\"
* *prompt_regex($prompt, qr/(.*)/)*
Prompts for something, using the prompt \"\'$prompt\'\", matching the entered
value (sans trailing linefeed) against the passed regex.
Note that this differs from the previous behaviour of prompt_regex, which
took a sub.
* *prompt_sub($prompt, sub { /(.*)/ && $1 })*
Prompts for something, using the prompt \"\'$prompt\'\", feeding the sub with
the entered value (sans trailing linefeed), to use a default, the passed
sub should simply return it with empty input.
* *prompt_passwd([$prompt])*
Same as \'prompt_regex\', but turns off echo. \'$prompt\' defaults to
\"\'Password: \'\" for this function.
* *prompt_string([$prompt])*
Prompt for a string.
* *prompt_int([$prompt])*
get an integer
* *prompt_for([ [$type =*] $what])>
Prompts for a value for \'$what\'. This constructs a prompt saying, eg
\"\'Enter value for $what\'\". Calls the equivalent \'prompt_foo()\' method.
* *prompt_yn([$prompt])*
prompts for yes or no, presuming neither
* *prompt_Yn([$prompt])*
* *prompt_yN([$prompt])*
prompts for yes or no, presuming yes and no, respectively.
You can also spell these as \'prompt_nY\' and \'prompt_Ny\'.
* *anydump($ref)*
Dump \'$ref\' via \'YAML\', falling back to \'Data::Dumper\' if YAML fails to
load (or dies during the dump). Returns a string.
* *tsay($template, $vars)*
Prints the template \'$template\' with \'$vars\'. \'$template\' may be included
at the end of the file as a data section, for instance:
use Scriptalicious;
tsay hello => { name => \"Bernie\" };
__END__
__hello__
Hello, [% name %]
[% INCLUDE yomomma %]
__yomomma__
Yo momma\'s so fat your family portrait has stretchmarks.
This will print:
Hello, Bernie
Yo momma\'s so fat your family portrait has stretchmarks.
Note that the script goes to lengths to make sure that the information is
always printed whether or not Template Toolkit is installed. This gets
pretty verbose, but at least solves the \"argh! that script failed, but I
don\'t know why because it needed this huge dependancy to tell me\" problem.
For example, the above would be printed as:
scriptname:
* *foo()*
If you\'ve got a short little Perl function that implements something useful
for people writing Shell scripts in Perl, then please feel free to
contribute it. And if it really is scriptalicious, you can bet your momma
on it getting into this module!
|
