*** /dev/null Sat Nov 23 05:40:42 2024
--- - Sat Nov 23 05:40:48 2024
***************
*** 0 ****
--- 1,498 ----
+ ##
+ ## 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<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 lock file contains the dezimal number listing the PID of the process
+ that created the lock.
+
+ B<file> ::= B<magic> B<pid>
+
+ B<magic> ::= /^%!AS-LOCK-[0-9]\.[0-9]$/
+
+ B<pid > ::= [0-9]+
+
+ =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>]
+
+ 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}
+
+ 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]
+
+ =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 convinient 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 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
+
|
