source: project/wiki/eggref/3/locale @ 13957

Last change on this file since 13957 was 13957, checked in by Kon Lovett, 11 years ago

Release.

File size: 14.6 KB
Line 
1[[tags: egg]]
2
3== locale
4
5Provides locale operations.
6
7[[toc:]]
8
9
10== Documentation
11
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-29|SRFI 29]].
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.
26
27=== Locale Components
28
29The major data structure is the {{locale-components}} object, portrayed as an
30extensible {{key+value}} pairing. The {{key}} is a {{symbol}}. The {{value}} is
31usually a {{string}}.
32
33A {{locale-components}} object will have more properties but the following are
34provided for every instance:
35
36Common Component Keys:
37
38; tag : What kind. Examples: 'locale and 'timezone.
39; name : The composite information object, source specific.
40; source : The origin for the information.
41
42A primary source is one of the following (others are possible):
43
44; PLATFORM : Information from the system.
45; POSIX : Information from POSIX environment. The "name" is a string.
46; GNU : Information from GNU environment.
47; BUILTIN : Information from system defaults.
48
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
56guarantee.
57
58The {{BUILTIN}} source creates a POSIX-style string "name" constructed using
59constants and library procedures.
60
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.
73
74==== locale-components?
75
76<procedure>(locale-components? OBJECT) => BOOLEAN</procedure>
77
78Is the {{OBJECT}} a {{locale-compenents}} object?
79
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
86==== locale-component-ref
87
88<procedure>(locale-component-ref LOCALE-COMPONENTS KEY [DEFAULT #f]) => OBJECT</procedure>
89
90Returns the {{KEY}} property of {{LOCALE-COMPONENTS}} or the {{DEFAULT}} when
91not found.
92
93==== set-locale-component!
94
95<procedure>(set-locale-component! LOCALE-COMPONENTS KEY VALUE)</procedure>
96
97Updates or creates the {{KEY}} property of {{LOCALE-COMPONENTS}} with the
98{{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.
159
160=== Timezone
161
162Access to timezone information. A timezone object is a {{locale-components}}
163object with properties for Standard Time Name and Offset, and an optional
164Summer or Daylight Saving Time Name and Offset. The offset is seconds west
165(positive or east (negative of UTC. The name is some locally accepted timezone
166name, such as "PST". A Daylight Saving Time start rule and end rule are
167optional properties.
168
169Timezone Component Properties:
170
171; std-name : The Standard timezone name.
172; std-offset : Seconds +/- UTC.
173; dst-name : The Daylight Saving Time timezone name.
174; dst-offset : Seconds +/- UTC.
175; dst-start : The start of Daylight Saving Time; a timezone-dst-rule.
176; dst-end : The end of Daylight Saving Time; a timezone-dst-rule.
177
178==== current-timezone
179
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.
189
190==== current-timezone-component
191
192<procedure>(current-timezone-components) => TIMEZONE-COMPONENTS</procedure>
193
194Returns the timezone-components object corresponding to the current-timezone.
195
196==== posix-timezone-string->timezone-components
197
198<procedure>(posix-timezone-string->timezone-components STRING [SOURCE "POSIX"]) => TIMEZONE-COMPONENTS</procedure>
199
200Parses a POSIX timezone string specification, {{STRING}}, and returns the
201corresponding timezone-components object, or {{#f}} when a parse error occurs.
202A {{#f}} or empty string value is mapped to the default timezone. The optional
203{{SOURCE}} indicates what locale system supplied the string.
204
205==== posix-load-timezone
206
207<procedure>(posix-load-timezone)</procedure>
208
209Initialize the current-timezone from the TZ environment variable.
210
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
275object?
276
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.
328
329==== local-timezone
330
331<procedure>(local-timezone YEAR MONTH DAY [HOUR 12 [MINUTE 0]] [#:offset? OFFSET? #f]) => STRING</procedure>
332
333Returns the timezone for the given date as a string, (e.g. "EST"). If
334{{OFFSET?}} is {{#t}}, then return it in RFC-822 format (e.g. "-0500").
335
336==== local-timezone-offset
337
338<procedure>(local-timezone-offset YEAR MONTH DAY [HOUR 12 [MINUTE 0]]) => FIXNUM</procedure>
339
340Returns the timezone offset as seconds where positive is east of UTC & negative
341is west of UTC.
342
343
344=== Locale Category
345
346Access to the locale information by category.
347
348Locale Category Keys (others are possible):
349
350; address : A {{locale-components} object.
351; collate : A {{locale-components} object.
352; ctype : A {{locale-components} object.
353; identification : A {{locale-components} object.
354; language : A {{language-components} object.
355; measurement : A {{locale-components} object.
356; messages : A {{locale-components} object.
357; monetary : A {{locale-components} object.
358; name : A {{locale-components} object.
359; numeric : A {{locale-components} object.
360; paper : A {{locale-components} object.
361; telephone : A {{locale-components} object.
362; time : A {{locale-components} object.
363; timezone : A {{timezone-components} object.
364
365==== make-locale-dictionary
366
367<procedure>(make-locale-dictionary) => LOCALE-CATEGORIES</procedure>
368
369Returns a new {{locale-categories}} object.
370
371==== locale-dictionary?
372
373<procedure>(locale-dictionary? OBJECT) => BOOLEAN</procedure>
374
375Is the specified {{OBJECT}} a {{locale-categories}} object?
376
377==== locale-dictionary-category
378
379<procedure>(locale-dictionary-category LOCALE-CATEGORIES KEY [DEFAULT #f]) => OBJECT</procedure>
380
381Returns the value for {{KEY}} in the {{LOCALE-CATEGORIES}}.
382
383==== set-locale-dictionary-category!
384
385<procedure>(set-locale-dictionary-category! LOCALE-CATEGORIES KEY VALUE)</procedure>
386
387Changes the {{VALUE}} for {{KEY}} in the {{LOCALE-CATEGORIES}}. A {{VALUE}} of
388{{#f}} will delete the category identified by {{KEY}}.
389
390==== current-locale-dictionary
391
392<parameter>(current-locale-dictionary) => LOCALE-CATEGORIES</parameter>
393<parameter>(current-locale-dictionary LOCALE-CATEGORIES)</parameter>
394
395Gets and sets the current {{locale-categories}} object.
396
397==== locale-category-ref
398
399<procedure>(locale-category-ref CATEGORY [DEFAULT #f])</procedure>
400
401Returns the specified {{CATEGORY}} locale-components object, or {{#f}} if the
402category is not valued.
403
404==== set-locale-category!
405
406<procedure>(set-locale-category! CATEGORY LOCALE-COMPONENTS)</procedure>
407
408Sets the specified {{CATEGORY}} to the specified {{LOCALE-COMPONENTS}} object.
409
410
411== Usage
412
413<enscript language=scheme>
414(require-extension locale)
415</enscript>
416
417
418== Examples
419
420
421== Notes
422
423* This is a work in progress. Currently only the Posix locale information is
424supported. Plans are to support the native MacOS X and Windows locale APIs.
425
426
427== Requirements
428
429[[lookup-table|lookup-table]]
430[[miscmacros|miscmacros]]
431
432
433== Bugs and Limitations
434
435
436== Author
437
438[[kon lovett]]
439
440
441== Version history
442
443; 0.5.0 : Added 'local-timezone' & 'local-timezone-offset'.
444; 0.4.0 : Added "buitlin" timezone & locale. Added categories.
445; 0.3.3 : Removed use of 'critical-section'
446; 0.3.2 : Dropped :optional
447; 0.3.1 : Bug fix for default dst offset
448; 0.3 : Reverts to defaults for timezone & locale when parse errors
449; 0.2 : Exports
450; 0.1 : Initial release
451
452
453== License
454
455Copyright (C 2009 Kon Lovett.  All rights reserved.
456
457Permission is hereby granted, free of charge, to any person obtaining a
458copy of this software and associated documentation files (the Software,
459to deal in the Software without restriction, including without limitation
460the rights to use, copy, modify, merge, publish, distribute, sublicense,
461and/or sell copies of the Software, and to permit persons to whom the
462Software is furnished to do so, subject to the following conditions:
463
464The above copyright notice and this permission notice shall be included
465in all copies or substantial portions of the Software.
466
467THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
468IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
469FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
470THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
471OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
472ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
473OTHER DEALINGS IN THE SOFTWARE.
Note: See TracBrowser for help on using the repository browser.