##
##  AS -- Accounting System
##  Copyright (c) 2002 Cable & Wireless Deutschland <http://www.cw.com/de/>
##  Copyright (c) 2002 Ralf S. Engelschall <rse@engelschall.com>
##
##  This file is part of AS, an accounting system which can be
##  found at http://as.is.eu.cw.com/
##
##  This program is free software; you can redistribute it and/or
##  modify it under the terms of the GNU General Public License
##  as published by the Free Software Foundation; either version
##  2.0 of the License, or (at your option) any later version.
##
##  This program is distributed in the hope that it will be useful,
##  but WITHOUT ANY WARRANTY; without even the implied warranty of
##  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
##  General Public License for more details.
##
##  You should have received a copy of the GNU General Public License
##  along with this program; if not, write to the Free Software
##  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
##  USA, or contact The OSSP Project <ossp@ossp.org>.
##
##  as-cui.pod: Unix Manual Page
##

=pod

=head1 NAME

B<as-cui> -- Accounting System (AS) Command-Line Client

=head1 SYNOPSIS

I<Common Configuration Options:>

=over 4

B<as-cui> ... [B<-D>|B<--define> I<opt-name>C<=>I<opt-value>] [B<-v>|B<--verbose>] ...

=back

I<Curses User Interface:>

=over 4

If none of the options below are used the program enters a character
based user inferface mode.  See section CUI to understand the operation
and key bindings used in this interactive mode.

I<Initial Setup:>

=over 4

=item B<as-cui> B<-s>|B<--setup>

=back

I<Server Communication:>

=over 4

=item B<as-cui> B<-d>|B<--download>

=item B<as-cui> B<-u>|B<--update> [I<uuid> ...]

=item B<as-cui> B<-c>|B<--commit> [I<uuid> ...]

=back

I<Floating Event Queue Manual Processing:>

=over 4

=item B<as-cui> I<time-spec> I<account> [I<remark>]

=item B<as-cui> B<-l>|B<--list>

=item B<as-cui> B<-e>|B<--edit> [I<uuid> ...]

=item B<as-cui> B<-r>|B<--remove> I<uuid> ...

=back

I<Floating Event Queue Batch Processing:>

=over 4

=item B<as-cui> B<--export> [B<--format> I<format>] [B<-f>|B<--file> I<file>]

=item B<as-cui> B<--import> [B<--format> I<format>] [B<-f>|B<--file> I<file>] [B<--overwrite>] 

=back

I<General Commands:>

=over 4

=item B<as-cui> B<-V>|B<--version>

=item B<as-cui> B<-h>|B<--help>

=back

=head1 DESCRIPTION

B<as-cui> is the Unix command-line client to the B<Accounting System>
(B<AS>). B<AS> is a database-backed system for accounting event time
and tasks. The B<as> tool allows performing both online and offline event
accounting with B<AS>. The offline accounting mode also can be used
without any B<AS> backend system, too.

=head1 OPTIONS

=head2 Common Configuration Options

The following shared configuration command-line options exists:

=over 4

=item B<-D>, B<--define> I<opt-name>C<=>I<opt-value>

Set the configuration variable I<opt-name> to the value I<opt-value>.
This temporarily (or persistently on option B<-s>|B<--setup>) overrides a
possibly existing variable definition in C<$HOME/.as/rc>.

=item B<-v>, B<--verbose>

Enable printing of verbose message on F<stdout>.

=back

=head2 Operation Options

The following mutual exclusive operation command-line options exists:

=over 4

=item B<-s>, B<--setup>

This is for the (optional) initial setup of the program environment. It
creates the directory C<$HOME/.as/> and the initial contents of the
files C<$HOME/.as/rc>, C<$HOME/.as/serial>, C<$HOME/.as/events>, 
C<$HOME/.as/accounts> and C<$HOME/.as/bashrc>.

=item B<-d>, B<--download>

This updates the list of available accounts in C<$HOME/.as/accounts>.
Keep in mind that only accounts are available to which the I<Username>
has write access.

=item B<-u>, B<--update>

This merges in server information about floating events into
C<$HOME/.as/events> and removes comitted events from C<$HOME/.as/events>
which the server now declared fixed. If local event modifications
conflict with the comitted server state, the event is locally tagged
with a corresponding error message.

=item B<-c>, B<--commit>

Commit still pending events from local floating event queue to server.

=item B<-l>, B<--list>

List all events in local floating event queue.

=item B<-e>, B<--edit>

Edit all or a set of particular events in local floating event queue.

=item B<-r>, B<--remove>

Delete a set of particular events from local floating event queue.

=item B<--export> 

Export the local floating event queue in either original
(I<format>C<=as/text>) or XML (I<format>C<=as/xml>) format to F<stdout> or
I<file>.

=item B<--import> 

Import the local floating event queue in either original
(I<format>C<=as/text>) or XML (I<format>C<=as/xml>) format from
F<stdout> or I<file>. If option B<--overwrite> is given, the events are
overwritten (instead of merged into) the local floating event queue.

=item B<--format> I<format>

This specifies the import/export format. Default is C<as/text>.

=item B<-f>, B<--file> I<file>

This specifies a file instead of F<stdin> (on B<--import>) and
F<stdout> (on B<--export>).

=item B<--overwrite>

Indicates an overwriting (instead of merging) operation on B<--import>.

=item B<-V>, B<--version>

Just print the program version.

=item B<-h>, B<--help>

Just print the program command line usage.

=back

=head1 ARGUMENTS

The following command-line arguments exist:

=over 4

=item I<account>

Name of an account. This can be specified in either descending or
ascending notation.

B<Descending notation> starts with the root account, ends with the leaf
account and uses the slash character as the separator. An example
is "C<is/dev/prj/openpkg/pmod>". Descending notation resembles the
Unix filesystem hierarchy. The advantage is that it is the more
intuitive notation for humans when searching for unknown accounts. The
disadvantage is that command-line argument auto-completion usually has
to be applied multiple times in order to reach the account.

B<Ascending notation> starts with the leaf account, ends with the root
account and uses the dot character as the separator. An example is
"C<pmod.openpkg.prj.dev.is>". Ascending notation resembles the DNS zone
hierarchy. The advantage is that command-line argument auto-completion
usually has to be applied only once (if the leaf account names are
unique) or twice in order to reach the account. This way it allows fast
searching for known accounts. The disadvantage is that it is the less
intuitive notation and especially does not allow searching for unknown
accounts.

For command-line completion reasons, in both notations the separator
character can be present as a leading and/or trailing character, too.

The syntax in grammatical description follows:

B<account-name>    ::= B<name-descending>
                  | B<name-ascending>

B<name-descending> ::= B<dsep>? B<part> (B<dsep> B<part>)* B<dsep>?

B<name-ascending>  ::= B<asep>? B<part> (B<asep> B<part>)* B<asep>?

B<dsep>            ::= /\//

B<asep>            ::= /\./

B<part>            ::= /[a-zA-Z0-9_-]+/

Examples:

 is/dev/prj/openpkg/pmod
 /is/dev/prj/openpkg/pmod
  is/dev/prj/openpkg/pmod/
 /is/dev/prj/openpkg/pmod/
 pmod.openpkg.prj.dev.is
 .pmod.openpkg.prj.dev.is
  pmod.openpkg.prj.dev.is.
 .pmod.openpkg.prj.dev.is.

=item I<time-spec>

Specification of the event time. The syntax as a whole is very complex,
but mostly all elements are optional:

B<time-spec>        ::= ( B<begin>? /-/ B<end>? )? =? B<amount>*

B<begin>            ::= B<24h-clock-time> || B<guess>

B<end>              ::= B<24h-clock-time> || B<guess>
 
B<amount>           ::= B<24h-clock-time> || B<guess>

B<24h-clock-time>   ::= B<hour> /:/ B<minute> (/:/ B<second>)?

B<hour>             ::= /^[01][0-9]|2[0-4]$/

B<min>              ::= /^[0-5][0-9]$/

B<sec>              ::= /^[0-5][0-9]$/

B<guess>            ::= B<dot>
                 || B<dotdot>
                 || B<short>
                 || B<frac-dec>
                 || B<frac-std>
                 || B<force-min>
                 || B<short-min>

B<dot>              ::= /^\.$/

B<dotdot>           ::= /^\.$/

B<short>            ::= /^([1-9])?(:([0-9]|[0-5][0-9])?)?$/

B<short-hour>       ::= /^([0-9]|[01][0-9]|2[0-4])?:([0-9]|[0-5][0-9])?$/

B<frac-dec>         ::= /^[0-9]*\.[0-9]+|[0-9]+\.$/   

B<frac-std>         ::= /^[0-9]*\/[1-9][0-9]*$/         

B<force-min>        ::= /^0[0-9]$/                      

B<short-min>        ::= /^[1-9][0-9]+$/                 

Examples:

 reference  | 00:06 00:15 01:30 06:00 10:00
 -----------+------------------------------
 short      |   :06   :15  1:30 6:    10:
 short      |   :6   0:15 -     6:0   10:0
 short-hour | -     -     -     6     -
 frac-dec   |  .1    .25  1.5   6.    10.0
 frac-std   | 1/10  1/4   3/2   -     -
 force-min  | 06    -     -     -     - 
 short-min  | -     15    90    360   600 

=item I<remark>

Optional prose text annotating an event. The only special semantic
recognized in this text are hyperlinks in URI notation. Beside the
standard URI schemes C<http>, C<https> and C<ftp> the all schemes are
recogized which were configured in the B<AS>.

Example:

 Fixed website http://www.example.com/

=item I<uuid> 

Auto-generated ISO-11578 Universally Unique Identifier (UUID) of an
event.

Example:

 f81d4fae-7dec-11d0-a765-00a0c91e6bf6 

=back

=head1 FILES

=head2 ${HOME}/.as/rc:

=over 4

The runtime configuration file contains settings describing the
communication between this frontend and the central database.

B<file>         ::= B<magic> B<entry>*

B<magic>        ::= /^%!AS-RC-[0-9]\.[0-9]$/

B<entry>        ::= B<opt-name> " " B<opt-value> "\n"

B<opt-name>     ::= "auth" | "pass" | "soap" |
                  "mode" | "user" | "date" |
                  "edit" | "hist"

B<opt-value>    ::= /'[^']*'/  # single-quoted string
               | /"[^"]*"/    # double-quoted string
               | /[^\n]+/

Example:

 auth as-john.doe
 pass mysecret
 soap http://as.example.com/soap
 mode commit
 user jd         #if ommited, ${LOGNAME} is used
 date 20021024   #if ommited, local time is used
 edit /usr/bin/vi
 hist 9          #number of historic files being kept

=head2 ${HOME}/.as/lock

The existence of the lock file alone identifies a mutual exclusive lock.
The application will not start if a lock file from any previous run is
dangling around.  To identify who created the lock, where the lock was
created and to allow verification of obsolete locks, additional
information is stored in the file. It is assumed that upon detection of
a foreign lock the application at least prints the human readable "text"
field to give some hint about what's going on before it terminates.

B<file>         ::= B<magic> B<entry>*

B<magic>        ::= /^%!AS-LOCK-[0-9]\.[0-9]$/

B<entry>        ::= B<opt-name> " " B<opt-value> "\n"

B<opt-name>     ::= "nodename" | "user" | "pid" |
                  "pwname" | "uid" | "text" |
                  "date" | "time"

B<opt-value>    ::= /'[^']*'/  # single-quoted string
               | /"[^"]*"/    # double-quoted string
               | /[^\n]+/

B<date> the lock files was created (format see B<date> in ${HOME}/.as/events)
Example: 2002-02-28

B<time> the lock file was created (format see B<24h-clock-time> in ${HOME}/.as/events)
Example: 12:30

B<user> who created the lock (format see B<user> in ${HOME}/.as/events)
Example: joe

B<nodename> from struct utsname.nodename returned by uname(2); same as shell "uname -n"
Example: dv1.dev.de.cw.net

B<pid> from getpid(2)
Example: 8923

B<uid> value comes from struct passwd.pw_uid returned by getpwent(2) or, alternativly by getuid(2)
Example: 2378

B<pwname> from struct passwd.pw_name returned by getpwent(2)
Example: as-ui

B<text> is created by the application and contains any printable
information useful by a second caller to understand why execution is
aborted. Example: "Killroy was here before you!".

=head2 ${HOME}/.as/serial

The serial file contains a dezimal number which is used and incremented
when creating UUIDs.

B<file>         ::= B<magic> B<count>

B<magic>        ::= /^%!AS-SERIAL-[0-9]\.[0-9]$/

B<count>        ::= [0-9]+

=head2 ${HOME}/.as/events

The events file contains the records of all events collected over time
and not yet locked in the central database. 

B<file>         ::= B<magic> B<entry>*

B<magic>        ::= /^%!AS-EVENTS-[0-9]\.[0-9]$/

B<entry>        ::= B<user> B<uuid> B<crc32> B<revision>
                 B<date> B<begin> B<end> B<amount>
                 B<account> B<remark> [# B<sysfeedback>]

Common rules for all fields in B<entry> for optional quoting: If field
is not empty and contains neither backslash, doublequote nor whitespace
keep verbatim.  Otherwise escape backslash and doublequotes with
backslash and put doublequotes around result.

B<user>         ::= [a-zA-Z][a-zA-Z0-9]*

B<uuid>         ::= B<hex>{8} ( /-/ B<hex>{4} ){3} /-/ B<hex>{12}

B<crc32>        ::= B<hex>{8}

calculated over the fields "user uuid revision date begin end amount account remark"

B<revision>     ::= [0-9]{1,5}

B<date>         ::= [2-9][0-9]{3}-([0][1-9]|[1][0-2])-([0][1-9]|[12][0-9]|[3][01])

B<begin>        ::= B<24h-clock-time>
                
B<end>          ::= B<24h-clock-time>
                
B<amount>       ::= B<24h-clock-time>

B<account>      ::= (\/[-a-zA-Z0-9]+)+
              || (\.[-a-zA-Z0-9]+)+

B<remark>       ::= .*

B<sysfeedback>  ::= .*

B<hex>          ::= [0-9a-fA-F]

The entries are sorted by the following critera:

 - by date
 - by begin time
 - by line number which was seen when read, new entries to the end
 - by uuid

=head2 ${HOME}/.as/accounts

The accounts file contains the records of all accounts the user has
write access to.

B<file>         ::= B<magic> B<entry>*

B<magic>        ::= /^%!AS-ACCOUNTS-[0-9]\.[0-9]$/

B<entry>        ::= B<type> B<name> B<description>

B<type>         ::= B<A>bstract|B<R>eal

B<name>         ::= /sample-org/dep/vacation

B<description>  ::= "approved absence, i.e. holiday"

=back

=head1 SHELL INTEGRATION

If you are using B<GNU bash> you can optionally use 

 . $HOME/.as/bashrc

in your C<$HOME/.bashrc> to get convenient command-line argument
completion for the B<as> command. With this feature enabled, pressing
B<TAB> when entering the I<account-name>, I<time-spec> and I<event-id>
arguments allows you to quickly complete the argument and convert it
into a canonical format.

=head1 EXAMPLE

 $ as --setup
 User foo
 Pass bar
 SOAP https://as.is.eu.cw.com/soap
 Mode commit
 $ as --update

 $ as 1:30 is/dev/meeting/weekly
 $ as 1/2 is/dev/prj/as/dev
 $ as -l
 $ as -c

=head1 CUI

The character based user interface is organized as a spreadsheet. Each
row resembles an event and every data field has a column. Due to screen
size limitations it is unlikely that all columns are visible at one
time.

Column headings at the top show the name of each data field. Column
headings stay at the top of the screen and don't scroll off.

Row headings on the left show status information about the entry encoded
into a single character. Row headings stay on the left side of the
screen and don't scroll off.


 Row/Entry status

=over 4

 " " event is in good shape
 "R" event was just read in and no status was ever computed (never shown)
 "E" event has one or more errors
 "M" event was modified outside CUI (crc32 fails)
 "N" event is new
 "Y" event is in yank buffer
 "y" one data field of this event is in yank buffer
 "D" event has been deleted (never shown)
 "U" event was deleted and deletion was "undo"ed

=back

The navigation and operation is loosely based on vi(1) concepts and
keystrokes. There are two modes of operation, cursor movement and data
cell editing. The CUI starts in cursor movement mode which can be
identified by the active cell being displayed reverse. Some keybindings
enter data cell editing mode which can be identified by the active cell
being displayed normal with the cursor prominently visible.

 Key bindings in cursor movement mode (loosely based on vi)

=over 4

 SPACE clears the data and enters cell editing mode
 "i" or F2 or RETURN enters cell editing mode 
 "A" enters cell editing mode with cursor on the end of the line
 "." for date field put current date cell
 "." for begin and end fields put current time into the cell
 "." for amount field recalculate end - begin
 "=" for a time field recalculates time based on the other two
 "~" for a time field rounds to the closest quarter
 "+" for a date or time field increments value
 "-" for a date or time field decrements value
 ESC exits from popups/editing and cancel action/input; call menu
 CURSOR_LEFT  or "h" moves to the cell on the left
 CURSOR_RIGHT or "l" moves to the cell on the right
 CURSOR_UP    or "k" moves to the cell above
 CURSOR_DOWN  or "j" moves to the cell below
 PAGE_UP   moves 1/3 of the screen height up
 PAGE_DOWN moves 1/3 of the screen height down
 CTRL-U scrolls 1/3 of the screen height up
 CTRL-D scrolls 1/3 of the screen height down
 CTRL-B scrolls one screen height up
 CTRL-F scrolls one screen height down
 HOME moves to the upper left visible cell
 END  moves to the bottom right visible cell
 "w" or TAB jumps to the next set destination
 "b" or BACKTAB jumps to the previous set destination
 "0" jumps to the leftmost set destination
 "^" moves to the leftmost cell in the row
 "$" moves to the rightmost cell in the row
 "1" moves to the first row
 "G" moves to the last row
 "o" creates and places the cursor on a new line below
     the current cursor position and enters cell editing mode
 "O" creates and places the cursor on a new line at
     the current cursor position and enters cell editing mode
 "Y" yank the current row into the clipboard
 "y" yank the current cell into the clipboard
 "p" if the clipboard contains a cell, paste the cell if the clipboard
     contains a row, place the cursor on a new line below the current
     cursor position, paste non-uniq data from the clipboard into the
     line and enter cell editing mode
 "P" the clipboard must contain a row; place the cursor on a new line at
     the current cursor position, paste non-uniq data from the clipboard
     into the line and enter cell editing mode
 ":" copy the data from the cell in the previous row
 ";" copy the data from the cell in the successor row
 "d" delete a row
 "u" multilevel undo of last row deletion
 "s" save and continue editing
 "q" quit without saving
 "x" or "Z" save and exit
 F1 shows this help
 F6 pops up a menu which allows to set jump destinations
 F7 pops up a menu which allows to hide columns or bring them back
 F8 pops up a menu which allows sorting rows; underlines on primary key
 F9  shrink column size to the minimum
 F10 shrink column size one character width
 F11 grow column size one character width
 F12 grow column size to the maximum

=back

 Key bindings in cursor movement mode (loosely based on bash)

=over 4

 F2 or RETURN leaves cell editing mode and enters movement mode
 CURSOR_LEFT  or CTRL-B moves one character to the left
 CURSOR_RIGHT or CTRL-F moves one character to the right
 HOME or CTRL-A moves cursor to the begin of the line
 END  or CTRL-E moves cursor to the end of the line
 CTRL-T toggle line overflow flagging
 CTRL-K kill line from cursor to end
 CTRL-U kill line completely
 CTRL-Z multilevel undo
 TAB input completion on date, time or account cells

=back

=head1 SEE ALSO

B<Accounting System> (AS)
https://as.is.eu.cw.com/

=head1 HISTORY

The B<Accounting System> (AS) was designed and implemented by the
I<Development Team> of the I<Internet Services> division at I<Cable &
Wireless Germany> between September 2002 and December 2002.

=head1 AUTHORS

Ralf S. Engelschall E<lt>rse@engelschall.comE<gt>

Thomas Lotterer E<lt>thomas@lotterer.netE<gt>

=cut