view release on metacpan or  search on metacpan

lib/App/JobLog/Command/info.pm  view on Meta::CPAN

==over 8

==item B<$executable>

If you invoke B<Job Log> without any arguments you will receive a list of its commands.

==item B<$executable commands>

Another way to obtain a list of commands.

==item B<--help>

Every command has a C<--help> option which will provide minimal help text and a complete list of the options the command
understands.

==item B<$executable help <command>>

The C<help> command will provide a command's full usage text.

==item B<$executable @{[__PACKAGE__->name]} --man>

This command's C<--man> option provides still more extensive help text.

==item B<perldoc>

The Perl modules of which this application is composed each have their own documentation. For example, try

  perldoc App::JobLog

==back

B<TIP:> any unambigous prefix of a command will do. All the following are equivalent:

@{[join "\n", map {"   $executable $_ doing something"} $self->_unambiguous_prefixes(App::JobLog::Command::add->name)]}

This means that for almost all commands you need only use the first letter of the command name.
END
}

sub _advanced_usage {
    my ( $self, $executable ) = (@_);
    return <<END;

==head1 Environment Variables

B<Job Log> is sensitive to a single environment variable:

==head2 @{[DIRECTORY()]}

By default B<Job Log> keeps the log and all other files in a hidden directory called F<.joblog> in your home
directory. If @{[DIRECTORY()]} is set, however, it will keep its files here. This is mostly useful for
testing, though if you find F<.joblog> already is in use by some other application you can use this variable
to prevent collisions. Collisions will only occur if the files F<log> or F<config.ini> exist in this
directory, and B<Job Log> will only alter these files if you append an event to the log or modify some
configuration parameters.

All other configuration is done through the B<@{[App::JobLog::Command::configure->name]}> command.

==head1 Time Expressions

B<Job Log> goes to considerable trouble to interpret whatever time expressions you might throw at it.
For example, it understands all of the following:

   1
   11/24 to today
   17 dec, 2024
   1 april, 2022 to 1-23-2002
   2023.6.5 - 10.26.2020
   2-22 till yesterday
   24 apr
   27 november, 1995 through 10
   3-4-2004
   3-9 - today
   4.23- 16 november, 1992
   8/1/1997 through yesterday
   june 14
   last month - 6.14
   pay period
   2010
   June 2010
   2010/6
   Feb 1 - 14
   ever

Every expression represents an interval of time. It either names an interval or defines it as the span from
the beginning of one interval to the end of another.

==head2 Time Grammar

Here is a complete BNF-style grammar of the time expressions understood by B<Job Log>. In this set of rules
C<s> represents some amount of whitespace, C<d> represents a digit, and C<\\x>, where C<x> is a number,
represents a back reference to the corresponding matched group in the same rule. After the first three
rules the remainder are alphabetized to facilitate finding them in the list. All expressions must match the
first rule.

If you find this system of rules opaque or unwieldy, you can use the B<@{[App::JobLog::Command::parse->name]}>
command to test an expression and see what time interval it is interpreted as.

@{[_bnf()]}
END
}

sub _footer {
    my ( $self, $executable ) = (@_);
    return <<END;

==head1 License etc.

 Author        David Houghton
               dfhoughton\@gmail.com
 Copyright (c) 2011
 License       Perl_5
END
}

# the complete bnf diagram for time grammar, also maintained
# in App::JobLog::TimeGrammar for lack of introspection in pod
sub _bnf {
    return <<END;
              <expression> = s* ( <ever> | <span> ) s*
                    <ever> = "all" | "always" | "ever" | [ [ "the" s ] ( "entire" | "whole" ) s ] "log"