source: project/wiki/eggref/5/locale @ 37636

Last change on this file since 37636 was 37387, checked in by Kon Lovett, 10 months ago

C5 port

File size: 17.7 KB
Line 
1[[tags: egg]]
2
3== locale
4
5Provides locale operations.
6
7[[toc:]]
8
9== Documentation
10
11{{locale}} is a set of routines supporting locale query operations. The
12environment locale information is determined lazily.
13
14{{locale}} does not interact with the C library routines {{setlocale}} or
15{{tzset}}, except for the {{with-tzset}} routine (see below).
16
17{{locale}} does not provide a:
18
19* localized message service, see [[srfi-29|SRFI 29]].
20* localized time service, see [[srfi-19|SRFI 19]].
21* a localized collating service.
22
23{{locale}} does not provide much of anything beyond locale identification.
24
25=== Locale Components Structure
26
27The major data structure is the {{locale-components}} object, portrayed as an
28extensible {{key+value}} pairing. The {{key}} is a {{symbol}}. The {{value}} is
29usually a {{string}}.
30
31A {{locale-components}} object will have more properties but the following are
32provided for every instance:
33
34Common Component Keys:
35
36; {{tag}} : What kind; a {{symbol}}. Examples: 'locale and 'timezone.
37; {{source}} : The origin for the information; either {{#f}}, a {{string}} or {{(string object...)}} (a {{composite-source}}).
38; {{name}} : The composite information object; source specific.
39
40A primary {{source}} is one of the following (others are possible):
41
42; {{"PLATFORM"}} : Information from the system. The {{name}} is usually a {{pointer}}.
43; {{"POSIX"}} : Information from POSIX environment. The {{name}} is a {{string}}.
44; {{"GNU"}} : Information from GNU environment. The {{name}} is a {{string}}.
45; {{"BUILTIN"}} : Information from system defaults. The {{name}} is a {{string}}.
46
47* The {{PLATFORM}} source is used for information first. (Currently unavailable.)
48
49* Then the {{POSIX}} + {{GNU}} source is attempted.
50
51* When all have failed the {{BUILTIN}} source is used.
52
53The point being locale information will be available, but without an accuracy
54guarantee.
55
56The {{BUILTIN}} source creates a POSIX-style {{string}} {{name}} constructed using
57constants and library procedures.
58
59When the {{source}} is from an environment variable a {{composite-source}} is created.
60Examples: {{("POSIX" "TZ")}}, {{("GNU" "LANGUAGE")}}.
61
62=== Locale Components
63
64==== make-locale-components
65
66<procedure>(make-locale-components NAME [SOURCE #f [TAG 'locale]]) -> locale-components</procedure>
67
68Returns a new {{locale-components}} object.
69
70==== locale-components?
71
72<procedure>(locale-components? OBJECT) -> boolean</procedure>
73
74Is the {{OBJECT}} a {{locale-components}} object?
75
76==== error-locale-components
77
78<procedure>(error-locale-components LOCATION OBJECT [ARGUMENT-NAME])</procedure>
79
80Raise a type-error.
81
82==== check-locale-components
83
84<procedure>(check-locale-components LOCATION OBJECT [ARGUMENT-NAME]) -> locale-components</procedure>
85
86Raise a type-error unless the {{OBJECT}} is a valid locale-components.
87
88==== locale-components-exists?
89
90<procedure>(locale-components-exists? LOCALE-COMPONENTS KEY) -> boolean</procedure>
91
92Does the specified {{LOCALE-COMPONENTS}} have a value for {{KEY}}?
93
94==== locale-component-ref
95
96<procedure>(locale-component-ref LOCALE-COMPONENTS KEY [DEFAULT #f]) -> object</procedure>
97
98Returns the {{KEY}} property of {{LOCALE-COMPONENTS}} or the {{DEFAULT}} when
99not found.
100
101==== set-locale-component!
102
103<procedure>(set-locale-component! LOCALE-COMPONENTS KEY VALUE)</procedure>
104
105Updates or creates the {{KEY}} property of {{LOCALE-COMPONENTS}} with the
106{{VALUE}}.
107
108==== update-locale-components!
109
110<procedure>(update-locale-components! LOCALE-COMPONENTS KEY VALUE ...) -> locale-components</procedure>
111
112Updates in place the {{LOCALE-COMPONENTS}} with the specified {{KEY+VALUE}} pairs.
113
114=== Locale
115
116Access to locale information. A locale object is composed of a Language, an
117optional Script, an optional Region, an optional Codeset, and an optional
118Modifier. The language should be an ISO 639-1 or ISO 639-2 name. The Script
119should be a RFC 3066bis name. The region should be an ISO 3166-1 name. The
120codeset and modifier forms are locale dependent.
121
122Locale Properties:
123
124; language : ISO 639-1 or ISO 639-2 name string. Default "en".
125; script : RFC 3066bis name string.
126; region : ISO 3166-1 name string. Default "US".
127; codeset : The character code to character mapping system.
128; modifier : Instance data, if any.
129
130==== locale-setup
131
132<procedure>(locale-setup)</procedure>
133
134Loads the locale, including timezone, information from the primary {{source}}.
135
136This is the procedure used to initialize the locale.
137
138==== current-locale
139
140<procedure>(current-locale) -> string</procedure>
141<procedure>(current-locale VALUE)</procedure>
142
143The currently defined locale. Returns the locale name string.
144
145The specified {{VALUE}} is either a locale string value, a
146{{locale-components}} object or {{#f}}, indicating locale independence.
147
148When no locale value is set the default locale is {{#f}}.
149
150==== current-locale-components
151
152<procedure>(current-locale-components) -> locale-components</procedure>
153
154Returns the {{locale-components}} object corresponding to the current-locale.
155
156==== posix-locale-string->locale-components
157
158<procedure>(posix-locale-string->locale-components STRING [SOURCE "POSIX" [TAG 'locale]]) -> locale-components</procedure>
159
160Parses a POSIX locale string specification, {{STRING}}, and returns the
161corresponding locale-components object.
162
163The optional {{SOURCE}} indicates what locale system supplied the string.
164
165==== posix-load-local
166
167<procedure>(posix-load-locale)</procedure>
168
169Sets up the locale using POSIX rules. Initializes the {{current-locale}} from
170the {{MESSAGES}} category.
171
172The Posix pathname locale is currently unsupported.
173
174The "C" & "POSIX" locales are unsupported.
175
176=== Timezone
177
178Access to timezone information. A timezone object is a {{locale-components}}
179object with properties for Standard Time Name and Offset, and an optional
180Summer or Daylight Saving Time Name and Offset. The offset is seconds west
181(positive or east (negative of UTC. The name is some locally accepted timezone
182name, such as "PST". A Daylight Saving Time start rule and end rule are
183optional properties.
184
185Timezone Component Properties:
186
187; std-name : The Standard timezone name.
188; std-offset : Seconds +/- UTC.
189; dst-name : The Daylight Saving Time timezone name.
190; dst-offset : Seconds +/- UTC.
191; dst-start : The start of Daylight Saving Time; a timezone-dst-rule.
192; dst-end : The end of Daylight Saving Time; a timezone-dst-rule.
193; dst? : DST in effect?
194
195==== current-timezone
196
197<procedure>(current-timezone) -> string</procedure>
198<procedure>(current-timezone VALUE)</procedure>
199
200The currently defined timezone. Returns the timezone name string.
201
202The specified {{VALUE}} is either a timezone string value, a
203{{timezone-components}} or {{#f}}, indicating no timezone.
204
205When no timezone value is set the default timezone is UTC.
206
207==== current-timezone-component
208
209<procedure>(current-timezone-components) -> timezone-components</procedure>
210
211Returns the timezone-components object corresponding to the current-timezone.
212
213==== posix-timezone-string->timezone-components
214
215<procedure>(posix-timezone-string->timezone-components STRING [SOURCE "POSIX"]) -> timezone-components</procedure>
216
217Parses a POSIX timezone string specification, {{STRING}}, and returns the
218corresponding timezone-components object.
219
220The optional {{SOURCE}} indicates what locale system supplied the string.
221
222==== posix-load-timezone
223
224<procedure>(posix-load-timezone)</procedure>
225
226Initialize the current-timezone from the TZ environment variable.
227
228The Posix pathname and implementation-defined timezone is currently
229unsupported.
230
231=== Timezone Components
232
233==== make-timezone-components
234
235<procedure>(make-timezone-components NAME [SOURCE #f]) -> timezone-components</procedure>
236
237Returns a new {{timezone-components}} object.
238
239==== timezone-components?
240
241<procedure>(timezone-components? OBJECT) -> boolean</procedure>
242
243Is the specified {{OBJECT}} actually a timezone-components object?
244
245Note that a {{timezone-components}} object is-a {{locale-components}} object.
246
247==== error-timezone-components
248
249<procedure>(error-timezone-components LOCATION OBJECT [ARGUMENT-NAME])</procedure>
250
251Raise a type-error.
252
253==== check-timezone-components
254
255<procedure>(check-timezone-components LOCATION OBJECT [ARGUMENT-NAME]) -> timezone-components</procedure>
256
257Raise a type-error unless the {{OBJECT}} is a valid timezone-components.
258
259==== timezone-components-exists?
260
261<procedure>(timezone-components-exists? TIMEZONE-COMPONENTS KEY) -> boolean</procedure>
262
263Does the specified {{TIMEZONE-COMPONENTS}} have a value for {{KEY}}?
264
265==== timezone-component-ref
266
267<procedure>(timezone-component-ref TIMEZONE-COMPONENTS KEY [DEFAULT #f])</procedure>
268
269Returns the timezone-component {{KEY}} of the {{TIMEZONE-COMPONENTS}} object,
270or the {{DEFAULT}} for a missing component.
271
272==== set-timezone-component!
273
274<procedure>(set-timezone-component! TIMEZONE-COMPONENTS KEY VALUE)</procedure>
275
276Sets the timezone-component {{KEY}} of the {{TIMEZONE-COMPONENTS}} object to
277{{VALUE}}.
278
279==== update-timezone-components!
280
281<procedure>(update-timezone-components! TIMEZONE-COMPONENTS KEY VALUE ...) -> timezone-components</procedure>
282
283Updates in place the {{TIMEZONE-COMPONENTS}} with the specified {{KEY+VALUE}} pairs.
284
285==== timezone-dst-rule-julian-noleap?
286
287<procedure>(timezone-dst-rule-julian-noleap? OBJECT) -> boolean</procedure>
288
289Is the specified {{OBJECT}} actually a daylight saving time julian day without
290leap seconds object?
291
292==== timezone-dst-rule-julian-leap?
293
294<procedure>(timezone-dst-rule-julian-leap? OBJECT) -> boolean</procedure>
295
296Is the specified {{OBJECT}} actually a daylight saving time julian day assuming
297leap seconds object?
298
299==== timezone-dst-rule-mwd?
300
301<procedure>(timezone-dst-rule-mwd? OBJECT) -> boolean</procedure>
302
303Is the specified {{OBJECT}} actually a daylight saving time month+week+day
304object?
305
306==== timezone-dst-rule-offset
307
308<procedure>(timezone-dst-rule-offset TIMEZONE-DST-RULE) -> INTEGER</procedure>
309
310Returns the seconds within day offset component of the specified
311{{TIMEZONE-DST-RULE}} object.
312
313==== timezone-dst-rule-julian
314
315<procedure>(timezone-dst-rule-julian TIMEZONE-DST-RULE) -> INTEGER</procedure>
316
317Returns the julian day component of the specified {{TIMEZONE-DST-RULE}} object.
318
319==== timezone-dst-rule-month
320
321<procedure>(timezone-dst-rule-month TIMEZONE-DST-RULE) -> INTEGER</procedure>
322
323Returns the month of year component of the specified {{TIMEZONE-DST-RULE}}
324object.
325
326==== timezone-dst-rule-week
327
328<procedure>(timezone-dst-rule-week TIMEZONE-DST-RULE) -> INTEGER</procedure>
329
330Returns the week of month component of the specified {{TIMEZONE-DST-RULE}}
331object.
332
333==== timezone-dst-rule-day
334
335<procedure>(timezone-dst-rule-day TIMEZONE-DST-RULE) -> INTEGER</procedure>
336
337Returns the day of week component of the specified {{TIMEZONE-DST-RULE}}
338object.
339
340==== make-timezone-dst-rule-julian-leap
341
342<procedure>(make-timezone-dst-rule-julian-leap JULIAN-DAY OFFSET) -> TIMEZONE-DST-RULE</procedure>
343
344Returns a daylight saving time julian day assuming leap seconds rule object.
345
346==== make-timezone-dst-rule-julian-noleap
347
348<procedure>(make-timezone-dst-rule-julian-noleap JULIAN-DAY OFFSET) -> TIMEZONE-DST-RULE</procedure>
349
350Returns a daylight saving time julian day without leap seconds rule object.
351
352==== make-timezone-dst-rule-mwd
353
354<procedure>(make-timezone-dst-rule-mwd MONTH WEEK DAY OFFSET) -> TIMEZONE-DST-RULE</procedure>
355
356Returns a daylight saving time month.week.day rule object.
357
358==== local-timezone-name
359
360<procedure>(local-timezone-name TV | YEAR MONTH DAY [HOUR 12 [MINUTE 0 [SECOND 0]]]) -> string</procedure>
361
362Returns the timezone for the given date as a string, (e.g. "EST").
363
364The date maybe specified using a 10-element time-vector {{TV}} or separately as
365{{YEAR MONTH DAY [HOUR 12 [MINUTE 0 [SECOND 0]]]}}.
366
367{{YEAR}} will be biased by {{-1900}}, except for a {{TV}} argument.
368((MONTH}} in [0 11].
369{{DAY}} in [1 31].
370{{HOUR}} in [0 23].
371{{MINUTE}} in [0 59].
372{{SECOND}} in [0 60].
373
374==== local-timezone-offset
375
376<procedure>(local-timezone-offset TV | YEAR MONTH DAY [HOUR 12 [MINUTE 0 [SECOND 0]]]) -> integer</procedure>
377
378Returns the timezone offset as seconds where positive is east of UTC & negative
379is west of UTC.
380
381==== local-timezone-name+offset
382
383<procedure>(local-timezone-name+offset TV | YEAR MONTH DAY [HOUR 12 [MINUTE 0 [SECOND 0]]]) -> (integer string)</procedure>
384
385Returns the timezone offset as seconds where positive is east of UTC & negative
386is west of UTC.
387
388==== with-tzset
389
390<procedure>(with-tzset TZ THUNK) -> object</procedure>
391
392Invoke {{THUNK}} with the TZ environment variable bound to the string {{TZ}}.
393Uses the C library routine {{tzset}}. Restores the original TZ value,
394unsets the TZ variable, as appropriate.
395
396==== timezone-offset?
397
398<procedure>(timezone-offset? OBJECT) -> boolean</procedure>
399
400Is the {{OBJECT}} a valid timezone offset in +/- seconds.
401
402==== error-timezone-offset
403
404<procedure>(error-timezone-offset LOCATION OBJECT [ARGUMENT-NAME])</procedure>
405
406Raise a type-error.
407
408==== check-timezone-offset
409
410<procedure>(check-timezone-offset LOCATION OBJECT [ARGUMENT-NAME])</procedure>
411
412Raise a type-error unless the {{OBJECT}} a valid timezone offset in +/- seconds.
413
414=== Locale Category
415
416Access to the locale information by category.
417
418Locale Category Keys (others are possible):
419
420; current : A {{locale-components} object.
421
422; address : A {{locale-components} object.
423; collate : A {{locale-components} object.
424; ctype : A {{locale-components} object.
425; identification : A {{locale-components} object.
426; language : A {{language-components} object.
427; measurement : A {{locale-components} object.
428; messages : A {{locale-components} object.
429; monetary : A {{locale-components} object.
430; name : A {{locale-components} object.
431; numeric : A {{locale-components} object.
432; paper : A {{locale-components} object.
433; telephone : A {{locale-components} object.
434; time : A {{locale-components} object.
435; timezone : A {{timezone-components} object.
436
437==== locale-category-ref
438
439<procedure>(locale-category-ref CATEGORY [DEFAULT #f]) -> locale-components</procedure>
440
441Returns the specified {{CATEGORY}} locale-components object, or {{#f}}
442if the category is not valued; not defined. Uses the
443{{(current-locale-dictionary)}}.
444
445==== set-locale-category!
446
447<procedure>(set-locale-category! CATEGORY LOCALE-COMPONENTS)</procedure>
448
449Sets the specified {{CATEGORY}} to the specified {{LOCALE-COMPONENTS}}
450object. A {{VALUE}} of {{#f}} will delete the category identified by
451{{KEY}}. Uses the {{(current-locale-dictionary)}}.
452
453==== current-locale-dictionary
454
455<parameter>(current-locale-dictionary) -> locale-categories</parameter>
456<parameter>(current-locale-dictionary LOCALE-CATEGORIES)</parameter>
457
458Gets and sets the current {{LOCALE-CATEGORIES}} object.
459
460==== make-locale-dictionary
461
462<procedure>(make-locale-dictionary) -> locale-categories</procedure>
463
464Returns a new {{locale-categories}} object.
465
466==== locale-dictionary?
467
468<procedure>(locale-dictionary? OBJECT) -> boolean</procedure>
469
470Is the specified {{OBJECT}} a {{locale-categories}} object?
471
472==== locale-dictionary-category
473
474<procedure>(locale-dictionary-category LOCALE-CATEGORIES KEY [DEFAULT #f]) -> object</procedure>
475
476Returns the value for {{KEY}} in the {{LOCALE-CATEGORIES}}.
477
478==== set-locale-dictionary-category!
479
480<procedure>(set-locale-dictionary-category! LOCALE-CATEGORIES KEY VALUE)</procedure>
481
482Changes the {{VALUE}} for {{KEY}} in the {{LOCALE-CATEGORIES}}. A
483{{VALUE}} of {{#f}} will delete the category identified by {{KEY}}.
484
485
486== Usage
487
488<enscript language=scheme>
489(require-extension locale)
490</enscript>
491
492
493== Notes
494
495* Currently only, some, Posix locale information is supported.
496
497* {{locale-setup}} is performed at first use by the {{locale-current}} module.
498
499
500== Requirements
501
502[[lookup-table|lookup-table]]
503[[miscmacros|miscmacros]]
504[[check-errors|check-errors]]
505[[regex]]
506
507[[setup-helper]]
508
509
510== Bugs and Limitations
511
512* As stated above no collation, normalization, formatting, or any other locale
513specific operation one might expect to find in a component named ''locale''.
514
515* Incomplete Posix support.
516
517* No Native support.
518
519
520== Author
521
522[[/users/kon-lovett|Kon Lovett]]
523
524
525== Version history
526
527; 0.8.0 : CHICKEN 5.
528; 0.7.3 : Add some TZ by name support.
529; 0.7.2 : Add Posix TZ offset name support.
530; 0.7.1 : TLS {{locale-setup}}.
531; 0.7.0 : Delay {{locale-setup}}.
532; 0.6.12 : Added {{'current}} locale category. Dropped ''builtin'' {{'language}} category. Deprecated {{local-timezone}}, added {{local-timezone-name}}.
533; 0.6.11 : Fix {{gnu-language-string->locale-components}}, {{with-tzset}}, and {{check-locale-components}} {{'name}} test.
534; 0.6.10 : Fix another {{get-environment-variable}} and non-existent TZ envvar.
535; 0.6.9 : Added {{locale-setup}}.
536; 0.6.8 : Added {{locale-component=?}} & {{timezone-component=?}}.
537; 0.6.7 : Replace {{getenv}} with {{get-environment-variable}}.
538; 0.6.6 : Explicit {{regex}} dependency.
539; 0.6.5 :
540; 0.6.4 :
541; 0.6.3 : Fix for defaulted dst offset in TZ parsing [provided by David Murray]
542; 0.6.2 : Exported check/error- routines
543; 0.6.1 : Bug fix
544; 0.6.0 : Initial Chicken 4 release
545
546
547== License
548
549Copyright (C) 2009-2019 Kon Lovett.  All rights reserved.
550
551Permission is hereby granted, free of charge, to any person obtaining a
552copy of this software and associated documentation files (the Software),
553to deal in the Software without restriction, including without limitation
554the rights to use, copy, modify, merge, publish, distribute, sublicense,
555and/or sell copies of the Software, and to permit persons to whom the
556Software is furnished to do so, subject to the following conditions:
557
558The above copyright notice and this permission notice shall be included
559in all copies or substantial portions of the Software.
560
561THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
562IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
563FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
564THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
565OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
566ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
567OTHER DEALINGS IN THE SOFTWARE.
Note: See TracBrowser for help on using the repository browser.