Day configuration and internationalization

Overview

Day has been designed to accommodate different locales and to take configuration parameters from a specified file. Such a file is called an appendix. All error messages and instructions, month names and abbreviations have codes to call them.1

Algorithmic configuration options are included in the appendix

The default appendix is English/Great-Britain

All appendix values can be changed on the fly or a completely fresh appendix loaded.

1Programming errors (as opposed operation errors that arise through say bad inputs) are all in English.

Appendix file

Use an existing appendix file as a template.

Use the file naming convention language-location .dax So for example en-gb.dax is English in Great Britain while en-us.dax is English for the United States.

This is a simple text file encoded in UTF-8. # is used to start comments, order is not important, values are specified as key = value.

Often keys will be of the form FOO.n Section heads explain the interpretation of the decimals. If any fields are not appropriate then leave blank.

There are nine notional sections for clarity.
0 Administration Information for editors and developers. Not used by Day code
1 Lexicon of Day specific terms Terms that will almost certainly need explaining in any 'technical' context
- .1 Full description
- .2 Display text
- .3 Shortest definite key sequence for input
2 Lexicon of general terms Terms that an application developer might need to reference. Some built-in Day functions may access these although in general sections 6 and 7 will be used for error messages.
- .1 Single
- .2 Plural
3 Month names These are important and must be tested against the test suite as there is potential for collisions of abbreviations. For example in English A can't be used as M4.4 (April) as it would clash with M8.4 (August). (M0 is provided in case a place-holder is needed.)
- .1 Full name
- .2 Three letter display
- .3 Two letter display
- .4 Shortest abbreviation for input - Case insensitive
4 Names of day of the week
- .1 Full name
- .2 Three letter display
- .3 Two letter display
5 Input parameters These tweak the acceptable input format based on locale.
- DM_ORDER
  Day-month order European style:d-m-y or American style:m-d-y. Options: DMY or MDY
- BC_INDICATOR
  How to indicate 'negative' years. This string will be at the END of any input string and is interpreted before and independently of any processing.
- INPUT_HACKS
  Special lookups for string inputs. For example in en-gb 'Jly' is the approved three letter abbreviation for July, but we want to be friendly and allow a user to type 'Jul'. These hacks translate exact matches of alternatives to 'official' ones. The format is alternative>standard,... Use upper case
6 Output user interface Common responses to common errors.
7 Explanations of common technical error messages These have the form NVRC.n for Day dates and NVIRC.n for Intervals. The n matches the error code stored in the Day or interval object.
8 Algorithm and processing configuration These play a critical role in determining how to deal with missing or slightly out of range data.
- IMPLIED_YEAR
  DAYc.ImpliedYear()
  What to do with a missing year. Developers will often want to use DAYc.TwoDigitFix() method to set this to suit their application.
  - 0
    Do not allow inputs that miss out year part
  - -1
    Use the current year as an implied substitute
  - -2
    Allow floating date input
  - nnnn
    Use the specified year if none is given
- TWO_DIGIT_FIX
  DAYc.TwoDigitFix()
  How to handle two digit years.
  - 0
    Disallow
  - 20
    convert yy to 20yy
  - 50
    Convert yy so that it lies between 50 years ago and 50 years ahead.
- ALLOW_31_TO_30
  DAYc.AllowExcessDaysInMonth()
  What to do if input is 31st for a month with only 30 days? This also applies to 29th February when not a leap year (Which is a slightly different thing but let's roll it in.)
  - 1
    Allow
  - 0
    Disallow and return a NV
- ALLOW_DAY_ONLY_INT
  DAYc.AllowOnlyDayIntervals()
  (Only applicable to Intervals) What to do if an interval is being constructed with say 45 days? Do we allow this to be represented as +0y 0m 45d (which is potentially lossless) or do we convert it into +0y 1m 15d which (because there are 30.4375 days in a month) introduces a potential error.
  - 1
    Don't convert to months and years
  - 0
    Always convert to months and years
- SMALL_YEARS_TO_DAYS
  (Only applicable to floating dates.) Does "Nov 1" mean November 0001 or 1st November? Strictly speaking in floating dates the year must come after the month, but in the scheme of things we won't be having many dates +/- 30 years of 1 AD so we will default a hack which takes the form "alpha-month number" as nth of month where n is <=31.
  - 1
    Read as days
  - 0
    Always read as years

Accessing the appendix

Loading an appendix

Always use DAYc.Initialise() before using Day. (If you don't then a default using a built-in en-gb configuration will be used.)
.Initialise takes an optional argument being text in an appendix format. This may mean you have to read the file (your job, don't forget it may be an async operation) then pass the buffer to .Initialise(). Or you could hard-code some block of text as a string and pass that.

Appendix-related methods

The DAYc module contains these methods.
None write a permanent change back to an appendix file.
See the API documentation for complete documentation.

In general, once initialised the ordinary developer shouldn't have much reason to twiddle with DAYc methods. Perhaps the most useful depending on how friendly you want to be with your users, are:

DAYc.ExtendedErrorStr() which returns section 6 texts
DAYc.ImpliedYear() which sets/gets the IMPLIED_YEAR parameter
DAYc.TwoDigitFix() which sets/gets the TWO_DIGIT_FIX parameter