*** /dev/null Sat Nov 23 05:40:13 2024
--- - Sat Nov 23 05:40:20 2024
***************
*** 0 ****
--- 1,678 ----
+ ##
+ ## 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
+
|
