home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
ARM Club 3
/
TheARMClub_PDCD3.iso
/
hensa
/
timing
/
sensible_1
/
Docs
/
Sensible
Wrap
Text File
|
1995-05-09
|
12KB
|
283 lines
File : Sensible
Date : 10-May-95
Author : © A.Thoukydides, 1995
Description : Description of the "Sensible Time" module.
INTRODUCTION
The "Sensible Time" module allows dates to be displayed in most applications
more sensibly than with the system default format. The following table
illustrates the way in which a few dates are displayed by the Filer "Full
info" display with and without this module loaded on the 1st May 1995.
Original display New display
01 May 1995 Today
30 Apr 1995 Yesterday
26 Apr 1995 Wednesday
25 Apr 1995 Tue, 25 Apr
01 Dec 1994 01 Dec 1994
This module is FreeWare; it may be freely used and copied. However, I retain
full copyright. See the section on "LEGAL MATTERS" for more details.
USAGE
It is possible to use this module just by loading it, e.g. double-clicking on
it. This may be performed at any time, but probably the best way is to load
it automatically in your boot sequence. If you have a Risc PC then simply
place the module in the "$.!Boot.Choices.Boot.PreDesk" directory. Otherwise
add a line "RMEnsure SensibleTime 0.00 RMLoad System:modules.Sensible" to
your !Boot file, and place the module in your !System.Modules directory.
No further installation is required to use "Sensible Time". However, you may
wish to read the next section on "CUSTOMISATION" to discover how its behaviour
can be altered.
CUSTOMISATION
It is recommended that you have a look at pages 1-402/1-403 ("Format field
names") and 3-738/3-739 ("Message file format") of the "RISC OS 3
Programmer's Reference Manual" before reading this section.
This module uses a messages file accessed as "Sensible:Messages" to configure
its behaviour. The default configuration is contained in the pseudo-file
"Resources:$.Resources.Sensible.Messages", which currently contains:
# Formats that prevent substitution
STOP1:%we
STOP2:%w3
STOP3:%dy-%m3-%yr
# Wildcarded formats to replace
SRCH1:%dy#%m3#%ce%yr
SRCH2:%dy#%m3#%yr
SRCH3:%dy#%mn#%yr
# Replacement format strings *must* be NULL terminated
TMRW1:Tomorrow<0>
TODY1:Today<0>
YSTR1:Yesterday<0>
WEEK1:%we<0>
TODY2/YSTR2/WEEK2:%w3<0>
YEAR1:%w3, %dy %m3<0>
Note: "<0>" is actually a single ASCII NULL character (value 0).
An alternative configuration may be used by pointing "Sensible$Path" to a
directory containing an alternative messages file on disc.
As can be clearly seen from the default file, there are three areas of
configuration:
1) Formats that prevent substitution.
The format string is searched for any occurrence of the text
associated with tokens beginning "STOP". If any matches are found
then no substitution is performed on the format string before
conversion proceeds. This is useful to prevent the day name appearing
twice in formats that already contain the day once.
The search is not case-sensitive, and supports "#" as a single
character wild-card. Any number of "STOP<x>" tokens may be supplied
(including zero), where <x> can be any sequence of characters that
are valid in a token.
2) Formats to replace
The format string is searched for any occurrence of the text
associated with tokens beginning "SRCH". Any matches are replaced by
one of the replacement formats from the next section.
As with the "STOP" tokens any number of "SRCH<x>" tokens may be
used. The search is also case-insensitive, and "#" is supported as a
wild-card.
3) Replacement format strings
The final section specifies the replacement format strings which
should be used for different relative dates. The possible tokens are:
Principal Auxiliary
"PAST1" "PAST2" An earlier year
"YEAR1" "YEAR2" More than five days ago, if the same year
"WEEK1" "WEEK2" Two to five days ago, if the same year
"YSTR1" "YSTR2" Previous day, if the same year
"TODY1" "TODY2" Same day
"TMRW1" "TMRW2" The next day, if the same year
"FUTR1" "FUTR2" A future year, or after the next day
All of these tokens are optional. Auxiliary strings are only used if
the corresponding principal string exists but generates an error when
used, e.g. if the field width is too narrow to contain the resulting
date string. If replacement is unsuccessful the original format
string is used instead.
All replacement format strings *must* be terminated with NULL
characters to prevent spurious errors.
Note that a different year takes priority over the other choices of
substitution; this is deliberate.
The tokens may appear in any order within the Messages file. The only time
that ordering is important is when one search string ("SRCH<x>" token) could
contain part of another, in which case the first matching token is used.
LEGAL MATTERS
The "Sensible Time" module and documentation is supplied "as is"; no
warranty, express or implied, of the merchantability of this software or its
fitness for any particular purpose is given. In no circumstances shall the
author, or any provider or distributor of this software, be liable for any
damage, loss of profits, or any indirect or consequential loss arising out of
the use of this software or inability to use this software.
This module is FreeWare. Permission is granted for anyone to distribute it
unchanged and in its entirety, providing that no profit is made in the
process. The "Sensible Time" module may not be distributed if modified or
incomplete; neither may it be distributed without this documentation.
To use this module, or any part of it, as part of a system or other
application that is for sale (for however much and for whatever reasons) or
released as copyright material then the author's express permission in
writing must be obtained. The author maintains copyright on all the material
supplied and reserves the right to change these conditions at any time
without notice.
CONTACTING THE AUTHOR
I would be interested in hearing of any bugs or other unexpected features in
this module, and will endeavour to correct any such problems in future
releases. Suggestions for improvements are also most welcome. Implementation
depends upon practicability and on how much spare time I have.
If you have any comments on this program, or would like to suggest ways in
which it could be improved, I can be contacted at one of the following
addresses:
Until June 1995:
19 Museum Road
Oxford
OX1 3PX
alexander.thoukydides@lincoln.oxford.ac.uk
After June 1995:
Thalna
2 Dukes Drive
Bearwood
Bournemouth
Dorset
BH11 9SZ
If in any communication you make specific reference to the program code please:
Quote the version number and date of the module.
Refer only to the module as released.
Supply as many details as possible about the problem, including the
hardware and software configuration of the machine being used.
Please send a stamped and self addressed envelope, or give details of how to
contact via e-mail, if you would like a reply.
I hope you find this module of some use.
ACKNOWLEDGEMENTS
I would like to the thank the following people for their contributions to
the development of this module:
Acorn Computers - The Risc PC, RISC OS and the ObjAsm assembler.
Aidan Corey - Thorough testing, and good ideas for improvements.
Dominic Symes - The brilliant !Zap editor; get a copy immediately.
Colin Turnbull - Reminding me that I should be revising.
Robin Watts - !Larger, the greatest backdrop program ever.
Rob Westwood - The original idea behind this program.
and everyone at the Acorn User Group in Oxford.
THINGS TO DO
The following are changes that may be made to this module sometime in the
future:
Check for format buffer overflow - currently a 1024 byte fixed length
buffer is used whilst processing the format strings, without any checks
for overflow.
Incorporate extra %xx tokens for special purposes.
Improve the error handling. If any part of initialisation fails then the
correct point in the finalisation code should be jumped to allowing any
successful initialisation to be undone. Memory allocation and deallocation
should also be more controlled.
VERSION HISTORY
0.00 (25-Apr-95) Original development version.
0.01 (26-Apr-95) Writes to Territory Manager workspace to install as
current territory without being the configured territory.
0.02 (26-Apr-95) Format strings containing the day not replaced to correct
problem with both BASIC and the Sys$* code variables
expecting fixed width fields. Modified string padded or
truncated to original length.
0.03 (28-Apr-95) Installation routine legalised by reinitialising Territory
Manager with OS_Byte vector intercepted to pretend that
this is the configured Territory. Added replacement format
for earlier the same year. Corrected stack handling over
nested SWI calls. Only performs susbtitution if text would
not require truncation.
0.04 (29-Apr-95) Added second choice replacement formats to cope better
with small field widths. Substitutions padded individually
within each replaced section. Comparisons made case
insensitive, and wild-cards supported.
0.05 (01-May-95) Messages file generated on-the-fly for Territory Manager
to give the new territory the same name as the configured
territory to avoid problems with applications using the
name of the territory to load resources. Installs and uses
messages file for configuration.
0.06 (02-May-95) Preprocessing of configuration messages file to improve
conversion performance. Error checking during conversions
improved.
0.07 (04-May-95) Added substitutions for previous years, tomorrow and the
future. Improved handling of errors during substitution.
Preprocessed substitution messages also for even faster
conversions.
0.08 (05-May-95) Improved macros for subroutine handling, making the code
more likely to be correct and shortening the module by
32 bytes.
0.09 (07-May-95) Intercepts Territory Manager SWIs by using the same SWI
chunk number and ensuring that this module is the most
recently initialised. This has the advantage that a new
territory is not required.
1.00 (09-May-95) First official release version. Changed default
configuration to use fully wild-carded search strings
and using extra specific stop strings to obtain desired
behaviour.
1.01 (10-May-95) Corrected bug which prevented alternative substitutions
from working.