head 1.18;
access;
symbols
AS_CUI_0_5_0:1.17
AS_AFTER_RESTRUCTURING:1.17;
locks; strict;
comment @# @;
1.18
date 2002.12.18.11.18.20; author rse; state dead;
branches;
next 1.17;
1.17
date 2002.10.31.16.02.45; author thl; state Exp;
branches;
next 1.16;
1.16
date 2002.10.31.09.29.52; author thl; state Exp;
branches;
next 1.15;
1.15
date 2002.10.31.08.51.08; author thl; state Exp;
branches;
next 1.14;
1.14
date 2002.10.30.16.20.21; author thl; state Exp;
branches;
next 1.13;
1.13
date 2002.10.30.14.02.19; author thl; state Exp;
branches;
next 1.12;
1.12
date 2002.10.30.10.38.21; author thl; state Exp;
branches;
next 1.11;
1.11
date 2002.10.24.15.09.56; author thl; state Exp;
branches;
next 1.10;
1.10
date 2002.10.24.12.23.55; author thl; state Exp;
branches;
next 1.9;
1.9
date 2002.10.23.08.44.54; author thl; state Exp;
branches;
next 1.8;
1.8
date 2002.10.16.12.36.14; author thl; state Exp;
branches;
next 1.7;
1.7
date 2002.10.15.15.48.37; author rse; state Exp;
branches;
next 1.6;
1.6
date 2002.10.15.13.41.40; author thl; state Exp;
branches;
next 1.5;
1.5
date 2002.09.29.09.56.58; author rse; state Exp;
branches;
next 1.4;
1.4
date 2002.09.26.18.13.19; author rse; state Exp;
branches;
next 1.3;
1.3
date 2002.09.26.12.58.29; author rse; state Exp;
branches;
next 1.2;
1.2
date 2002.09.25.19.37.17; author rse; state Exp;
branches;
next 1.1;
1.1
date 2002.09.25.15.11.02; author rse; state Exp;
branches;
next ;
desc
@@
1.18
log
@polish for initial release
@
text
@##
## AS -- Accounting System
## Copyright (c) 2002 Cable & Wireless Deutschland
## Copyright (c) 2002 Ralf S. Engelschall
##
## 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 .
##
## as.pod: Unix Manual Page
##
=pod
=head1 NAME
B -- Accounting System (AS) Command-Line Client
=head1 SYNOPSIS
I
=over 4
B ... [B<-D>|B<--define> IC<=>I] [B<-v>|B<--verbose>] ...
=back
I
=over 4
=item B B<-s>|B<--setup>
=back
I
=over 4
=item B B<-d>|B<--download>
=item B B<-u>|B<--update> [I ...]
=item B B<-c>|B<--commit> [I ...]
=back
I
=over 4
=item B I I [I]
=item B B<-l>|B<--list>
=item B B<-e>|B<--edit> [I ...]
=item B B<-r>|B<--remove> I ...
=back
I
=over 4
=item B B<--export> [B<--format> I] [B<-f>|B<--file> I]
=item B B<--import> [B<--format> I] [B<-f>|B<--file> I] [B<--overwrite>]
=back
I
=over 4
=item B B<-V>|B<--version>
=item B B<-h>|B<--help>
=back
=head1 DESCRIPTION
B is the Unix command-line client to the B
(B). B is a database-backed system for accounting event time
and tasks. The B tool allows performing both online and offline event
accounting with B. The offline accounting mode also can be used
without any B backend system, too.
=head1 OPTIONS
=head2 Common Configuration Options
The following shared configuration command-line options exists:
=over 4
=item B<-D>, B<--define> IC<=>I
Set the configuration variable I to the value I.
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.
=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
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
(IC<=as/text>) or XML (IC<=as/xml>) format to F or
I.
=item B<--import>
Import the local floating event queue in either original
(IC<=as/text>) or XML (IC<=as/xml>) format from
F or I. If option B<--overwrite> is given, the events are
overwritten (instead of merged into) the local floating event queue.
=item B<--format> I
This specifies the import/export format. Default is C.
=item B<-f>, B<--file> I
This specifies a file instead of F (on B<--import>) and
F (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
Name of an account. This can be specified in either descending or
ascending notation.
B starts with the root account, ends with the leaf
account and uses the slash character as the separator. An example
is "C". 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 starts with the leaf account, ends with the root
account and uses the dot character as the separator. An example is
"C". 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 ::= B
| B
B ::= B? B (B B)* B?
B ::= B? B (B B)* B?
B ::= /\//
B ::= /\./
B ::= /[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
Specification of the event time. The syntax as a whole is very complex,
but mostly all elements are optional:
B ::= ( B? /-/ B? )? =? B*
B ::= B<24h-clock-time> || B
B ::= B<24h-clock-time> || B
B ::= B<24h-clock-time> || B
B<24h-clock-time> ::= B /:/ B (/:/ B)?
B ::= /^[01][0-9]|2[0-4]$/
B ::= /^[0-5][0-9]$/
B ::= /^[0-5][0-9]$/
B ::= B
|| B
|| B
|| B
|| B
|| B
|| B
B ::= /^\.$/
B ::= /^\.$/
B ::= /^([1-9])?(:([0-9]|[0-5][0-9])?)?$/
B ::= /^([0-9]|[01][0-9]|2[0-4])?:([0-9]|[0-5][0-9])?$/
B ::= /^[0-9]*\.[0-9]+|[0-9]+\.$/
B ::= /^[0-9]*\/[1-9][0-9]*$/
B ::= /^0[0-9]$/
B ::= /^[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
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, C and C the all schemes are
recogized which were configured in the B.
Example:
Fixed website http://www.example.com/
=item I
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 ::= B B*
B ::= /^%!AS-RC-[0-9]\.[0-9]$/
B ::= B " " B "\n"
B ::= "auth" | "pass" | "soap" |
"mode" | "user" | "date" |
"edit" | "hist"
B ::= /'[^']*'/ # 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 ::= B B
B ::= /^%!AS-LOCK-[0-9]\.[0-9]$/
B ::= [0-9]+
=head2 ${HOME}/.as/serial
The serial file contains a dezimal number which is used and incremented
when creating UUIDs.
B ::= B B
B ::= /^%!AS-SERIAL-[0-9]\.[0-9]$/
B ::= [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 ::= B B*
B ::= /^%!AS-EVENTS-[0-9]\.[0-9]$/
B ::= B B B B
B B B B
B [B] [# B]
B ::= [a-zA-Z][a-zA-Z0-9]*
B ::= B{8} ( /-/ B{4} ){3} /-/ B{12}
B ::= B{8}
B ::= [0-9]{1,5}
B ::= [2-9][0-9]{3}([0][1-9]|[1][0-2])([0][1-9]|[12][0-9]|[3][01])
B ::= B<24h-clock-time>
B ::= B<24h-clock-time>
B ::= B<24h-clock-time>
B ::= (\/[-a-zA-Z0-9]+)+
|| (\.[-a-zA-Z0-9]+)+
B ::= .*
B ::= .*
B ::= [0-9a-fA-F]
=head2 ${HOME}/.as/accounts
The accounts file contains the records of all accounts the user has
write access to.
B ::= B B*
B ::= /^%!AS-ACCOUNTS-[0-9]\.[0-9]$/
B ::= B B B
B ::= Bbstract|Beal
B ::= /sample-org/dep/vacation
B ::= "approved absence, i.e. holiday"
=back
=head1 SHELL INTEGRATION
If you are using B you can optionally use
. $HOME/.as/bashrc
in your C<$HOME/.bashrc> to get convinient command-line argument
completion for the B command. With this feature enabled, pressing
B when entering the I, I and I
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 (AS)
https://as.is.eu.cw.com/
=head1 HISTORY
The B (AS) was designed and implemented by the
I of the I division at I between September 2002 and December 2002.
=head1 AUTHORS
Ralf S. Engelschall Erse@@engelschall.comE
Thomas Lotterer Ethomas@@lotterer.netE
=cut
@
1.17
log
@implement time syntaxes and align with manual
@
text
@@
1.16
log
@slash2dot; dot2slash; accept dot in events file; remove DEBUG traces
@
text
@d277 1
a277 1
B ::= /^[0-9]|[01][0-9]|2[0-4]$/
d279 1
a279 1
B ::= /^[0-9]|[0-5][0-9]$/
d281 1
a281 1
B ::= /^[0-9]|[0-5][0-9]$/
d283 3
a285 1
B ::= B
d289 1
a289 3
|| B
|| B
|| B
d291 1
a291 1
B ::= /^([0-9]*:[0-5][0-9]|[0-9]+:)$/
d293 1
a293 1
B ::= /^([0-9]*\.[0-9]+|[0-9]+\.)$/
d295 1
a295 1
B ::= /^[0-9]*\/[1-9][0-9]*$/
d297 1
a297 1
B ::= /^0[0-9]$/
d299 1
a299 1
B ::= /^[0-9]*:[0-9]$/
d301 1
a301 1
B ::= /^[0-9]$/
d303 3
a305 1
B ::= /^[1-9][0-9]+$/
d309 9
a317 8
reference 00:06 00:15 01:30 06:00 27:00
amount-std :06 0:15 1:30 06:00 27:
amount-frac-dec 0.1 0.25 1.5 6. 27.0
amount-frac-std 1/10 1/4 3/2 - -
amount-force-min 06 - - - -
amount-abbr-min :6 - - 6:0 27:0
amount-abbr-hour - - - 6 -
amount-abbr-min - 15 90 360 1620
@
1.15
log
@calccrc32; keep a history before overwriting
@
text
@d424 1
@
1.14
log
@writeevents; do_newevent; splittimespec
@
text
@d355 1
a355 1
"edit"
d370 1
@
1.13
log
@readevents
@
text
@d275 1
a275 1
B<24h-clock-time> ::= B (/:/ B (/:/ B)?)?
d403 1
a403 1
B B B B
@
1.12
log
@implement time-spec shell completion
@
text
@d267 1
a267 1
B ::= ( B? /-/ B? )? =? B*
d269 1
a269 1
B ::= B<24h-clock-time> || B
d402 1
a402 1
B ::= B B B B
d406 1
a406 1
B ::= john.doe
d408 1
a408 1
B ::= f81d4fae-7dec-11d0-a765-00a0c91e6bf6
d410 1
a410 1
B ::= a89b389c
d412 1
a412 1
B ::= 42
d414 1
a414 1
B ::= 2002-10-01
d416 1
a416 1
B ::= 00:00
d418 1
a418 1
B ::= 24:00
d420 1
a420 1
B ::= 03:00
d422 1
a422 1
B ::= /sample-org/dep/vacation
d424 1
a424 1
B ::= "important recreation"
d426 3
a428 1
B ::= ERROR: ...
@
1.11
log
@user/date are defines only; implemented simple sanity check
@
text
@d267 1
a267 3
B ::= ( B /-/ B /=/ )* B
| B ( /-/ B )* /=/ B
| B