### ----------------------------------------------------
### -- GNU::Time
### -- Licenses: Artistic-2.0
### -- Authors: Tom Browder <tbrowder@acm.org>
### -- File: docs/sto/readme.pod
### ----------------------------------------------------
=begin pod

=item C<time-command>

This module provides an easy interface to the GNU C<time> command (usually installed as
'/usr/bin/time') to time user commands.

=SYNOPSIS

=begin code
    use GNU::Time;
    my $cmd = "some-user-prog arg1 arg2";
    my $user-time = time-command $cmd;
    say $user-time; # output: 42.70 # seconds
=end code

Note: This module replaces module `Proc::More` which is deprecated.

=head2 Getting the C<time> command

On Debian hosts the C<time> command may not be installed by default, but
it is available in package C<time>.  It can also be built from source
available at the I<Free Software Foundation>'s git site.  Clone the
source repository:

=begin code :lang<raku>
    $ git clone https://git.savannah.gnu.org/git/time.git
=end code

The build and install instructions are in the repository along with the source code.

Unfortunately, there is no equivalent command available for Windows
unless you install Cygwin or an equivalent system.

=head2 The GNU C<time> command

The details for running C<time> are described in C<time>'s man page which can be viewed by
running C<man 1 time> at the command line.

This module will look for time in the following locations and order:

=item The location defined by the C<GNU_TIME> environment variable
=item C</usr/local/bin/time>
=item C</usr/bin/time>

If the C<time> command is not found, an exception will be thrown.
Likewise, if the C<time> command returns an exit code other than
zero, an exception will be thrown.

# The B<Proc::More> module

The routines are described in detail in
[ALL-SUBS](https://github.com/tbrowder/Proc-More/blob/master/docs/ALL-SUBS.md)
which shows a short description of each exported routine along with
its complete signature.

## The C<:$typ> and C<:$fmt> named parameters

The two named parameters control the type and format of the output
from the time-command.  (Note there is a fourth format which is used
if the C<:$fmt> variable is not used or defined.  In that case only
the raw time in seconds is shown without any other formatting.)  The
allowed values and a short description are described in the source
code and are repeated here:

=begin code :lang<raku>
my token typ { ^ :i             # the desired time(s) to return:
                    a|all|      # show all three times:
                                #   "Real: [time in desired format]; User: [ditto]; Sys: [ditto]"
                    r|real|     # show only the real (wall clock) time
                    u|user|     # show only the user time (default)
                    s|sys       # show only the system time
             $ }
my token fmt { ^ :i             # the desired format for the returned time(s)
                    s|seconds|  # time in seconds with an appended 's': "30.42s"
                    h|hms|      # time in hms format: "0h00m30.42s"
                    ':'|'h:m:s' # time in h:m:s format: "0:00:30.42"
             $ }
=end code

=head1 Contributing

Interested users are encouraged to contribute improvements and
corrections to this module, and pull requests, bug reports, and
suggestions are always welcome.

=head1 AUTHOR

Tom Browder (tbrowder@cpan.org)

=head1 COPYRIGHT and LICENSE

Copyright © 2017-2021 Tom rowder

This library is free software; you may redistribute or modify it under the Artistic License 2.0.

=end pod


