Changeset 13894 in project


Ignore:
Timestamp:
03/24/09 17:42:19 (11 years ago)
Author:
Kon Lovett
Message:

Updated doc for rel 0.4.0

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/3/locale

    r13853 r13894  
    1010== Documentation
    1111
    12 ''locale'' is a set of routines supporting locale query operations. The environment
    13 locale information is determined upon module load and the corresponding
    14 parameters are set.
     12''locale'' is a set of routines supporting locale query operations. The
     13environment locale information is determined upon module load and the
     14corresponding parameters are set.
     15
     16''locale'' does not interact with the C library routines {{setlocale}} or
     17{{tzset}}.
     18
     19''locale'' does not provide a localized message service, see [[srfi-27|SRFI 27]].
     20
     21''locale'' does not provide a localized time service, see [[srfi-19|SRFI 19]].
     22
     23''locale'' does not provide a localized collating service.
     24
     25''locale'' does not provide anything beyond locale identification.
    1526
    1627=== Locale Components
    1728
    18 The major data structure is the {{locale-components}} type, portrayed as an
     29The major data structure is the {{locale-components}} object, portrayed as an
    1930extensible {{key+value}} pairing. The {{key}} is a {{symbol}}. The {{value}} is
    2031usually a {{string}}.
     
    2536Common Component Keys:
    2637
    27 ; tag : What kind.
     38; tag : What kind. Examples: 'locale and 'timezone.
    2839; name : The composite information object, source specific.
    2940; source : The origin for the information.
    3041
    31 The {{source}} property is one of the following (others are possible):
    32 
     42A primary source is one of the following (others are possible):
     43
     44; PLATFORM : Information from the system.
    3345; POSIX : Information from POSIX environment. The "name" is a string.
    34 ; PLATFORM : Information from the system.
     46; GNU : Information from GNU environment.
    3547; BUILTIN : Information from system defaults.
    3648
    37 The {{PLATFORM}} source is used for information first. Then the {{POSIX}}
    38 source is attempted. When all have failed the {{BUILTIN}} source is used. The
    39 point being locale information will be available, but without an accuracy
     49* The {{PLATFORM}} source is used for information first. (Currently unavailable.)
     50
     51* Then the {{POSIX/GNU}} source is attempted.
     52
     53* When all have failed the {{BUILTIN}} source is used.
     54
     55The point being locale information will be available, but without an accuracy
    4056guarantee.
    4157
     
    4359constants and library procedures.
    4460
    45 === Generic Locale Components Property Access
     61The {{source}} is either a {{string}} or a {{(string object...)}}:
     62
     63; POSIX : ("POSIX" "<environment variable name>"). Example: {{("POSIX" "TZ")}}.
     64; GNU : ("GNU" "<environment variable name>"). Example: {{("GNU" "LANGUAGE")}}.
     65
     66=== Locale Components
     67
     68==== make-locale-components
     69
     70<procedure>(make-locale-components NAME [SOURCE #f [TAG 'locale]]) => LOCALE-COMPONENTS</procedure>
     71
     72Returns a new {{locale-components}} object.
    4673
    4774==== locale-components?
    4875
    49 <procedure>(locale-components? OBJECT)</procedure>
     76<procedure>(locale-components? OBJECT) => BOOLEAN</procedure>
    5077
    5178Is the {{OBJECT}} a {{locale-compenents}} object?
    5279
     80==== locale-components-exists?
     81
     82<procedure>(locale-components-exists? LOCALE-COMPONENTS KEY) => BOOLEAN</procedure>
     83
     84Does the specified {{LOCALE-COMPONENTS}} have a value for {{KEY}}?
     85
    5386==== locale-component-ref
    5487
    55 <procedure>(locale-component-ref LOCALE-COMPONENTS KEY [DEFAULT #f])</procedure>
     88<procedure>(locale-component-ref LOCALE-COMPONENTS KEY [DEFAULT #f]) => OBJECT</procedure>
    5689
    5790Returns the {{KEY}} property of {{LOCALE-COMPONENTS}} or the {{DEFAULT}} when
     
    6497Updates or creates the {{KEY}} property of {{LOCALE-COMPONENTS}} with the
    6598{{VALUE}}.
     99
     100==== update-locale-components!
     101
     102<procedure>(update-locale-components! LOCALE-COMPONENTS KEY VALUE ...) => LOCALE-COMPONENTS</procedure>
     103
     104Updates in place the {{LOCALE-COMPONENTS}} with the specified {{KEY+VALUE}} pairs.
     105
     106=== Locale
     107
     108Access to locale information. A locale object is composed of a Language, an
     109optional Script, an optional Region, an optional Codeset, and an optional
     110Modifier. The language should be an ISO 639-1 or ISO 639-2 name. The Script
     111should be a RFC 3066bis name. The region should be an ISO 3166-1 name. The
     112codeset and modifier forms are locale dependent.
     113
     114Locale Properties:
     115
     116; language : ISO 639-1 or ISO 639-2 name string. Default "en".
     117; script : RFC 3066bis name string.
     118; region : ISO 3166-1 name string. Default "US".
     119; codeset : The character code to character mapping system.
     120; modifier : Instance data, if any.
     121
     122==== current-locale
     123
     124<procedure>(current-locale) => STRING</procedure>
     125<procedure>(current-locale VALUE)</procedure>
     126
     127The currently defined locale. Returns the locale name string.
     128
     129The specified {{VALUE}} is either a locale string value, a
     130{{locale-components}} object or {{#f}}, indicating locale independence.
     131
     132When no locale value is set the default locale is {{#f}}.
     133
     134==== current-locale-component
     135
     136<procedure>(current-locale-components) => LOCALE-COMPONENTS</procedure>
     137
     138Returns the {{locale-components}} object corresponding to the current-locale.
     139
     140==== posix-locale-string->locale-components
     141
     142<procedure>(posix-locale-string->locale-components STRING [SOURCE "POSIX" [TAG 'locale]]) => LOCALE-COMPONENTS</procedure>
     143
     144Parses a POSIX locale string specification, {{STRING}}, and returns the
     145corresponding locale-components object, or {{#f}} when a parse error occurs. A
     146{{#f}} or empty string value is mapped to the default locale. The optional
     147{{SOURCE}} indicates what locale system supplied the string.
     148
     149==== posix-load-local
     150
     151<procedure>(posix-load-locale)</procedure>
     152
     153Sets up the locale using POSIX rules. Initializes the {{current-locale}} from
     154the {{MESSAGES}} category.
     155
     156The Posix pathname locale is currently unsupported.
     157
     158The "C" & "POSIX" locales are unsupported.
    66159
    67160=== Timezone
     
    85178==== current-timezone
    86179
    87 <parameter>(current-timezone [VALUE])</parameter>
    88 
    89 The currently defined timezone. The specified {{VALUE}} is either a timezone
    90 string value, or {{#f}} , indicating no timezone. When no timezone value is set
    91 the default timezone is UTC.
     180<procedure>(current-timezone) => STRING</procedure>
     181<procedure>(current-timezone VALUE)</procedure>
     182
     183The currently defined timezone. Retruns the timezone name string.
     184
     185The specified {{VALUE}} is either a timezone string value, a
     186{{timezone-components}} or {{#f}}, indicating no timezone.
     187
     188When no timezone value is set the default timezone is UTC.
    92189
    93190==== current-timezone-component
    94191
    95 <procedure>(current-timezone-components)</procedure>
     192<procedure>(current-timezone-components) => TIMEZONE-COMPONENTS</procedure>
    96193
    97194Returns the timezone-components object corresponding to the current-timezone.
    98195
    99 ==== timezone-components?
    100 
    101 <procedure>(timezone-components? TIMEZONE-COMPONENTS)</procedure>
    102 
    103 Is the specified {{TIMEZONE-COMPONENTS}} object actually a timezone-components
    104 object?
    105 
    106 ==== timezone-component-ref
    107 
    108 <procedure>(timezone-component-ref TIMEZONE-COMPONENTS KEY [DEFAULT #f])</procedure>
    109 
    110 Returns the timezone-component {{KEY}} of the {{TIMEZONE-COMPONENTS}} object,
    111 or the {{DEFAULT}} for a missing component.
    112 
    113 ==== set-timezone-component!
    114 
    115 <procedure>(set-timezone-component! TIMEZONE-COMPONENTS KEY VALUE)</procedure>
    116 
    117 Sets the timezone-component {{KEY}} of the {{TIMEZONE-COMPONENTS}} object to
    118 {{VALUE}}.
    119 
    120 ==== timezone-dst-rule-julian-noleap?
    121 
    122 <procedure>(timezone-dst-rule-julian-noleap? TIMEZONE-DST-RULE)</procedure>
    123 
    124 Is the specified {{TIMEZONE-DST-RULE}} object actually a
    125 daylight saving time julian day without leap seconds object?
    126 
    127 ==== timezone-dst-rule-julian-leap?
    128 
    129 <procedure>(timezone-dst-rule-julian-leap? TIMEZONE-DST-RULE)</procedure>
    130 
    131 Is the specified {{TIMEZONE-DST-RULE}} object actually a daylight saving time
    132 julian day assuming leap seconds object?
    133 
    134 ==== timezone-dst-rule-mwd?
    135 
    136 <procedure>(timezone-dst-rule-mwd? TIMEZONE-DST-RULE)</procedure>
    137 
    138 Is the specified {{TIMEZONE-DST-RULE}} object actually a daylight saving time
    139 month+week+day object?
    140 
    141 ==== timezone-dst-rule-offset
    142 
    143 <procedure>(timezone-dst-rule-offset TIMEZONE-DST-RULE)</procedure>
    144 
    145 Returns the seconds within day offset component of the specified
    146 {{TIMEZONE-DST-RULE}} object.
    147 
    148 ==== timezone-dst-rule-julian
    149 
    150 <procedure>(timezone-dst-rule-julian TIMEZONE-DST-RULE)</procedure>
    151 
    152 Returns the julian day component of the specified {{TIMEZONE-DST-RULE}} object.
    153 
    154 ==== timezone-dst-rule-month
    155 
    156 <procedure>(timezone-dst-rule-month TIMEZONE-DST-RULE)</procedure>
    157 
    158 Returns the month of year component of the specified {{TIMEZONE-DST-RULE}}
    159 object.
    160 
    161 ==== timezone-dst-rule-week
    162 
    163 <procedure>(timezone-dst-rule-week TIMEZONE-DST-RULE)</procedure>
    164 
    165 Returns the week of month component of the specified {{TIMEZONE-DST-RULE}}
    166 object.
    167 
    168 ==== timezone-dst-rule-day
    169 
    170 <procedure>(timezone-dst-rule-day TIMEZONE-DST-RULE)</procedure>
    171 
    172 Returns the day of week component of the specified {{TIMEZONE-DST-RULE}}
    173 object.
    174 
    175 ==== make-timezone-dst-rule-julian-leap
    176 
    177 <procedure>(make-timezone-dst-rule-julian-leap JULIAN-DAY OFFSET)</procedure>
    178 
    179 Returns a daylight saving time julian day assuming leap seconds rule object.
    180 
    181 ==== make-timezone-dst-rule-julian-noleap
    182 
    183 <procedure>(make-timezone-dst-rule-julian-noleap JULIAN-DAY OFFSET)</procedure>
    184 
    185 Returns a daylight saving time julian day without leap seconds rule object.
    186 
    187 ==== make-timezone-dst-rule-mwd
    188 
    189 <procedure>(make-timezone-dst-rule-mwd MONTH WEEK DAY OFFSET)</procedure>
    190 
    191 Returns a daylight saving time month.week.day rule object.
    192 
    193196==== posix-timezone-string->timezone-components
    194197
    195 <procedure>(posix-timezone-string->timezone-components STRING [SOURCE "POSIX"])</procedure>
    196 
    197 Parses a POSIX timezone string specification, {{STRING}} , and returns the
     198<procedure>(posix-timezone-string->timezone-components STRING [SOURCE "POSIX"]) => TIMEZONE-COMPONENTS</procedure>
     199
     200Parses a POSIX timezone string specification, {{STRING}}, and returns the
    198201corresponding timezone-components object, or {{#f}} when a parse error occurs.
    199202A {{#f}} or empty string value is mapped to the default timezone. The optional
    200203{{SOURCE}} indicates what locale system supplied the string.
    201204
    202 ==== posix-load-timezon
     205==== posix-load-timezone
    203206
    204207<procedure>(posix-load-timezone)</procedure>
     
    206209Initialize the current-timezone from the TZ environment variable.
    207210
    208 === Locale
    209 
    210 Access to locale information. A locale object is composed of a Language, an
    211 optional Script, an optional Region, an optional Codeset, and an optional
    212 Modifier. The language should be an ISO 639-1 or ISO 639-2 name. The Script
    213 should be a RFC 3066bis name. The region should be an ISO 3166-1 name. The
    214 codeset and modifier forms are locale dependent.
    215 
    216 Locale Properties:
    217 
    218 ; language : ISO 639-1 or ISO 639-2 name string. Default "en".
    219 ; script : RFC 3066bis name string.
    220 ; region : ISO 3166-1 name string. Default "US".
    221 ; codeset : The character code to character mapping system.
    222 ; modifier : Instance data, if any.
    223 
    224 ==== current-locale
    225 
    226 <parameter>(current-locale [VALUE])</parameter>
    227 
    228 The currently defined locale. The specified {{VALUE}} is either a locale string
    229 value, or {{#f}} , indicating locale independence. When no locale value is set
    230 the default locale is {{#f}}.
    231 
    232 ==== current-locale-component
    233 
    234 <procedure>(current-locale-components)</procedure>
    235 
    236 Returns the locale-components object corresponding to the current-locale.
    237 
    238 ==== locale-components?
    239 
    240 <procedure>(locale-components? LOCALE-COMPONENTS)</procedure>
    241 
    242 Is the specified {{LOCALE-COMPONENTS}} object actually a locale-components
     211The Posix pathname and implementation-defined timezone is currently
     212unsupported.
     213
     214=== Timezone Components
     215
     216==== make-timezone-components
     217
     218<procedure>(make-timezone-components NAME [SOURCE #f]) => TIMEZONE-COMPONENTS</procedure>
     219
     220Returns a new {{timezone-components}} object.
     221
     222==== timezone-components?
     223
     224<procedure>(timezone-components? OBJECT) => BOOLEAN</procedure>
     225
     226Is the specified {{OBJECT}} actually a timezone-components object?
     227
     228Note that a {{timezone-components}} object is-a {{locale-compenents}} object.
     229
     230==== timezone-components-exists?
     231
     232<procedure>(timezone-components-exists? TIMEZONE-COMPONENTS KEY) => BOOLEAN</procedure>
     233
     234Does the specified {{TIMEZONE-COMPONENTS}} have a value for {{KEY}}?
     235
     236==== timezone-component-ref
     237
     238<procedure>(timezone-component-ref TIMEZONE-COMPONENTS KEY [DEFAULT #f])</procedure>
     239
     240Returns the timezone-component {{KEY}} of the {{TIMEZONE-COMPONENTS}} object,
     241or the {{DEFAULT}} for a missing component.
     242
     243==== set-timezone-component!
     244
     245<procedure>(set-timezone-component! TIMEZONE-COMPONENTS KEY VALUE)</procedure>
     246
     247Sets the timezone-component {{KEY}} of the {{TIMEZONE-COMPONENTS}} object to
     248{{VALUE}}.
     249
     250==== update-timezone-components!
     251
     252<procedure>(update-timezone-components! TIMEZONE-COMPONENTS KEY VALUE ...) => TIMEZONE-COMPONENTS</procedure>
     253
     254Updates in place the {{TIMEZONE-COMPONENTS}} with the specified {{KEY+VALUE}} pairs.
     255
     256==== timezone-dst-rule-julian-noleap?
     257
     258<procedure>(timezone-dst-rule-julian-noleap? OBJECT) => BOOLEAN</procedure>
     259
     260Is the specified {{OBJECT}} actually a daylight saving time julian day without
     261leap seconds object?
     262
     263==== timezone-dst-rule-julian-leap?
     264
     265<procedure>(timezone-dst-rule-julian-leap? OBJECT) => BOOLEAN</procedure>
     266
     267Is the specified {{OBJECT}} actually a daylight saving time julian day assuming
     268leap seconds object?
     269
     270==== timezone-dst-rule-mwd?
     271
     272<procedure>(timezone-dst-rule-mwd? OBJECT) => BOOLEAN</procedure>
     273
     274Is the specified {{OBJECT}} actually a daylight saving time month+week+day
    243275object?
    244276
    245 ==== locale-component-ref
    246 
    247 <procedure>(locale-component-ref LOCALE-COMPONENTS KEY [DEFAULT #f])</procedure>
    248 
    249 Returns the locale-component {{KEY}} of the {{LOCALE-COMPONENTS}} object, or
    250 the {{DEFAULT}} for a missing component.
    251 
    252 ==== set-locale-component!
    253 
    254 <procedure>(set-locale-component! LOCALE-COMPONENTS KEY VALUE)</procedure>
    255 
    256 Sets the locale-component {{KEY}} of the {{LOCALE-COMPONENTS}} object to
    257 {{VALUE}}.
    258 
    259 ==== posix-locale-string->locale-components
    260 
    261 <procedure>(posix-locale-string->locale-components STRING [SOURCE "POSIX"])</procedure>
    262 
    263 Parses a POSIX locale string specification, {{STRING}} , and returns the
    264 corresponding locale-components object, or {{#f}} when a parse error occurs. A
    265 {{#f}} or empty string value is mapped to the default locale. The optional
    266 {{SOURCE}} indicates what locale system supplied the string.
    267 
    268 ==== posix-load-local
    269 
    270 <procedure>(posix-load-locale)</procedure>
    271 
    272 Sets up the locale using POSIX rules. Initializes the {{current-locale}} from
    273 the {{MESSAGES}} category.
     277==== timezone-dst-rule-offset
     278
     279<procedure>(timezone-dst-rule-offset TIMEZONE-DST-RULE) => INTEGER</procedure>
     280
     281Returns the seconds within day offset component of the specified
     282{{TIMEZONE-DST-RULE}} object.
     283
     284==== timezone-dst-rule-julian
     285
     286<procedure>(timezone-dst-rule-julian TIMEZONE-DST-RULE) => INTEGER</procedure>
     287
     288Returns the julian day component of the specified {{TIMEZONE-DST-RULE}} object.
     289
     290==== timezone-dst-rule-month
     291
     292<procedure>(timezone-dst-rule-month TIMEZONE-DST-RULE) => INTEGER</procedure>
     293
     294Returns the month of year component of the specified {{TIMEZONE-DST-RULE}}
     295object.
     296
     297==== timezone-dst-rule-week
     298
     299<procedure>(timezone-dst-rule-week TIMEZONE-DST-RULE) => INTEGER</procedure>
     300
     301Returns the week of month component of the specified {{TIMEZONE-DST-RULE}}
     302object.
     303
     304==== timezone-dst-rule-day
     305
     306<procedure>(timezone-dst-rule-day TIMEZONE-DST-RULE) => INTEGER</procedure>
     307
     308Returns the day of week component of the specified {{TIMEZONE-DST-RULE}}
     309object.
     310
     311==== make-timezone-dst-rule-julian-leap
     312
     313<procedure>(make-timezone-dst-rule-julian-leap JULIAN-DAY OFFSET) => TIMEZONE-DST-RULE</procedure>
     314
     315Returns a daylight saving time julian day assuming leap seconds rule object.
     316
     317==== make-timezone-dst-rule-julian-noleap
     318
     319<procedure>(make-timezone-dst-rule-julian-noleap JULIAN-DAY OFFSET) => TIMEZONE-DST-RULE</procedure>
     320
     321Returns a daylight saving time julian day without leap seconds rule object.
     322
     323==== make-timezone-dst-rule-mwd
     324
     325<procedure>(make-timezone-dst-rule-mwd MONTH WEEK DAY OFFSET) => TIMEZONE-DST-RULE</procedure>
     326
     327Returns a daylight saving time month.week.day rule object.
    274328
    275329=== Locale Category
     
    277331Access to the locale information by category.
    278332
    279 Locale Category Keys:
    280 
    281 ; ADDRESS :
    282 ; COLLATE :
    283 ; CTYPE :
    284 ; IDENTIFICATION :
    285 ; LANGUAGE :
    286 ; MEASUREMENT :
    287 ; MESSAGES :
    288 ; MONETARY :
    289 ; NAME :
    290 ; NUMERIC :
    291 ; PAPER :
    292 ; TELEPHONE :
    293 ; TIME :
    294 
    295 ==== set-locale-category!
    296 
    297 <procedure>(set-locale-category! CATEGORY LOCALE-COMPONENTS)</procedure>
    298 
    299 Sets the specified {{CATEGORY}} to the specified {{LOCALE-COMPONENTS}} object.
     333Locale Category Keys (others are possible):
     334
     335; address : A {{locale-components} object.
     336; collate : A {{locale-components} object.
     337; ctype : A {{locale-components} object.
     338; identification : A {{locale-components} object.
     339; language : A {{language-components} object.
     340; measurement : A {{locale-components} object.
     341; messages : A {{locale-components} object.
     342; monetary : A {{locale-components} object.
     343; name : A {{locale-components} object.
     344; numeric : A {{locale-components} object.
     345; paper : A {{locale-components} object.
     346; telephone : A {{locale-components} object.
     347; time : A {{locale-components} object.
     348; timezone : A {{timezone-components} object.
     349
     350==== make-locale-dictionary
     351
     352<procedure>(make-locale-dictionary) => LOCALE-CATEGORIES</procedure>
     353
     354Returns a new {{locale-categories}} object.
     355
     356==== locale-dictionary?
     357
     358<procedure>(locale-dictionary? OBJECT) => BOOLEAN</procedure>
     359
     360Is the specified {{OBJECT}} a {{locale-categories}} object?
     361
     362==== locale-dictionary-category
     363
     364<procedure>(locale-dictionary-category LOCALE-CATEGORIES KEY [DEFAULT #f]) => OBJECT</procedure>
     365
     366Returns the value for {{KEY}} in the {{LOCALE-CATEGORIES}}.
     367
     368==== set-locale-dictionary-category!
     369
     370<procedure>(set-locale-dictionary-category! LOCALE-CATEGORIES KEY VALUE)</procedure>
     371
     372Changes the {{VALUE}} for {{KEY}} in the {{LOCALE-CATEGORIES}}. A {{VALUE}} of
     373{{#f}} will delete the category identified by {{KEY}}.
     374
     375==== current-locale-dictionary
     376
     377<parameter>(current-locale-dictionary) => LOCALE-CATEGORIES</parameter>
     378<parameter>(current-locale-dictionary LOCALE-CATEGORIES)</parameter>
     379
     380Gets and sets the current {{locale-categories}} object.
    300381
    301382==== locale-category-ref
    302383
    303 <procedure>(locale-category-ref CATEGORY)</procedure>
     384<procedure>(locale-category-ref CATEGORY [DEFAULT #f])</procedure>
    304385
    305386Returns the specified {{CATEGORY}} locale-components object, or {{#f}} if the
    306387category is not valued.
     388
     389==== set-locale-category!
     390
     391<procedure>(set-locale-category! CATEGORY LOCALE-COMPONENTS)</procedure>
     392
     393Sets the specified {{CATEGORY}} to the specified {{LOCALE-COMPONENTS}} object.
    307394
    308395
     
    321408* This is a work in progress. Currently only the Posix locale information is
    322409supported. Plans are to support the native MacOS X and Windows locale APIs.
    323 Changes to this API are almost certain.
    324410
    325411
     
    340426== Version history
    341427
    342 ; 0.4.0 : Added "default" timezone & locale
     428; 0.4.0 : Added "buitlin" timezone & locale. Added categories.
    343429; 0.3.3 : Removed use of 'critical-section'
    344430; 0.3.2 : Dropped :optional
Note: See TracChangeset for help on using the changeset viewer.