view release on metacpan or  search on metacpan

lib/Scriptalicious.pod  view on Meta::CPAN

=item B<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.

=item B<moan "weather is miserable">

Prints a warning to standard error.  It is preceded with the text
C<warning:>.  The program does not exit.

=item B<protest "don't know the weather report">

Prints an error message to standard error.  It is preceded with the
text C<error:>.  The program does not exit.

=item B<barf "hit an iceberg">

Prints a warning to standard error.  It is preceded with the text
C<warning:>.  The program does not exit.

=item B<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.

C<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!\n" },
       -out => "/tmp/outfile",
       -out2 => "/dev/null",
       @command );

This will connect the child process' standard input (C<-in>) to a
closure that is printing "C<Hello, world!\n>".  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 (C<-out>) to
C</tmp/outfile>, and its standard error (filehandle 2) to C</dev/null>
(the traditional way of junking error output).

If you wanted to connect two filehandles to the same place, you could
pass in C<GLOB> references instead;

  run( -out => \*MYOUT,
       -out2 => \*MYOUT,
       @command );

Any filehandle can be opened in any mode; C<-in> merely defaults to
meaning C<-in0>, and C<-out> defaults to meaning C<-out1>.  There is
no C<-err>; use C<-out2>.  C<-rw> exists (defaulting to C<-rw0>), but
is probably of limited use.

Here is an example of using C<prompt_passwd()> to hijack C<gpg>'s
password grabbing;

  my $password = prompt_passwd("Encryption password: ");
  my $encrypted = run( -in4 => sub { print "$password\n" },
                       "gpg", "--passphrase-fd", "4", "-c", $file )

=item B<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.

=item B<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.

=item B<capture_err("command", "foo")>

Works as B<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, @output) = capture_err("somecommand", @args);

=item B<hush_exec()>

=item B<unhush_exec()>

C<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 C<-vv> (double verbose) or C<-d> (debug, which is the same
thing).

=item B<start_timer()>

=item B<show_delta()>

=item B<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.

=item B<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 L<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.

=item B<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: