locale

Provides locale operations.

locale
Documentation
Notes
Requirements
Bugs and Limitations
Author
Repository
Version history
License

Documentation

locale is a set of routines supporting locale query operations. The environment locale information is determined lazily.

locale does not interact with the C library routines setlocale or tzset, except for the with-tzset routine (see below).

locale does not provide a:

localized message service, see SRFI 29.
localized time service, see SRFI 19.
a localized collating service.

locale does not provide much of anything beyond locale identification.

Locale Components Structure

The major data structure is the locale-components object, portrayed as an extensible key+value pairing. The key is a symbol. The value is usually a string.

A locale-components object will have more properties but the following are provided for every instance:

Common Component Keys:

tag: What kind; a symbol. Examples: 'locale and 'timezone.
source: The origin for the information; either #f, a string or (string object...) (a composite-source).
name: The composite information object; source specific.

A primary source is one of the following (others are possible):

"PLATFORM": Information from the system. The name is usually a pointer.
"POSIX": Information from POSIX environment. The name is a string.
"GNU": Information from GNU environment. The name is a string.
"BUILTIN": Information from system defaults. The name is a string.

The PLATFORM source is used for information first. (Currently unavailable.)
Then the POSIX + GNU source is attempted.
When all have failed the BUILTIN source is used.

The point being locale information will be available, but without an accuracy guarantee.

The BUILTIN source creates a POSIX-style string name constructed using constants and library procedures.

When the source is from an environment variable a composite-source is created. Examples: ("POSIX" "TZ"), ("GNU" "LANGUAGE").

Usage

(import locale)

Locale Components

make-locale-components

[procedure] (make-locale-components NAME [SOURCE #f [TAG 'locale]]) -> locale-components

Returns a new locale-components object.

locale-components?

[procedure] (locale-components? OBJECT) -> boolean

Is the OBJECT a locale-components object?

error-locale-components

[procedure] (error-locale-components LOCATION OBJECT [ARGUMENT-NAME])

Raise a type-error.

check-locale-components

[procedure] (check-locale-components LOCATION OBJECT [ARGUMENT-NAME]) -> locale-components

Raise a type-error unless the OBJECT is a valid locale-components.

locale-components-exists?

[procedure] (locale-components-exists? LOCALE-COMPONENTS KEY) -> boolean

Does the specified LOCALE-COMPONENTS have a value for KEY?

locale-component-ref

[procedure] (locale-component-ref LOCALE-COMPONENTS KEY [DEFAULT #f]) -> object

Returns the KEY property of LOCALE-COMPONENTS or the DEFAULT when not found.

set-locale-component!

[procedure] (set-locale-component! LOCALE-COMPONENTS KEY VALUE)

Updates or creates the KEY property of LOCALE-COMPONENTS with the VALUE.

update-locale-components!

[procedure] (update-locale-components! LOCALE-COMPONENTS KEY VALUE ...) -> locale-components

Updates in place the LOCALE-COMPONENTS with the specified KEY+VALUE pairs.

Access to locale information. A locale object is composed of a Language, an optional Script, an optional Region, an optional Codeset, and an optional Modifier. The language should be an ISO 639-1 or ISO 639-2 name. The Script should be a RFC 3066bis name. The region should be an ISO 3166-1 name. The codeset and modifier forms are locale dependent.

Locale Properties:

language: ISO 639-1 or ISO 639-2 name string. Default "en".
script: RFC 3066bis name string.
region: ISO 3166-1 name string. Default "US".
codeset: The character code to character mapping system.
modifier: Instance data, if any.

locale-setup

[procedure] (locale-setup)

Loads the locale, including timezone, information from the primary source.

This is the procedure used to initialize the locale.

current-locale

[procedure] (current-locale) -> string
[procedure] (current-locale VALUE)

The currently defined locale. Returns the locale name string.

The specified VALUE is either a locale string value, a locale-components object or #f, indicating locale independence.

When no locale value is set the default locale is #f.

current-locale-components

[procedure] (current-locale-components) -> locale-components

Returns the locale-components object corresponding to the current-locale.

posix-locale-string->locale-components

[procedure] (posix-locale-string->locale-components STRING [SOURCE "POSIX" [TAG 'locale]]) -> locale-components

Parses a POSIX locale string specification, STRING, and returns the corresponding locale-components object.

The optional SOURCE indicates what locale system supplied the string.

posix-load-local

[procedure] (posix-load-locale)

Sets up the locale using POSIX rules. Initializes the current-locale from the MESSAGES category.

The Posix pathname locale is currently unsupported.

The "C" & "POSIX" locales are unsupported.

Timezone

Access to timezone information. A timezone object is a locale-components object with properties for Standard Time Name and Offset, and an optional Summer or Daylight Saving Time Name and Offset. The offset is seconds west (positive or east (negative of UTC. The name is some locally accepted timezone name, such as "PST". A Daylight Saving Time start rule and end rule are optional properties.

Timezone Component Properties:

std-name: The Standard timezone name.
std-offset: Seconds +/- UTC.
dst-name: The Daylight Saving Time timezone name.
dst-offset: Seconds +/- UTC.
dst-start: The start of Daylight Saving Time; a timezone-dst-rule.
dst-end: The end of Daylight Saving Time; a timezone-dst-rule.
dst?: DST in effect?

current-timezone

[procedure] (current-timezone) -> string
[procedure] (current-timezone VALUE)

The currently defined timezone. Returns the timezone name string.

The specified VALUE is either a timezone string value, a timezone-components or #f, indicating no timezone.

When no timezone value is set the default timezone is UTC.

current-timezone-component

[procedure] (current-timezone-components) -> timezone-components

Returns the timezone-components object corresponding to the current-timezone.

posix-timezone-string->timezone-components

[procedure] (posix-timezone-string->timezone-components STRING [SOURCE "POSIX"]) -> timezone-components

Parses a POSIX timezone string specification, STRING, and returns the corresponding timezone-components object.

The optional SOURCE indicates what locale system supplied the string.

posix-load-timezone

[procedure] (posix-load-timezone)

Initialize the current-timezone from the TZ environment variable.

The Posix pathname and implementation-defined timezone is currently unsupported.

Timezone Components

make-timezone-components

[procedure] (make-timezone-components NAME [SOURCE #f]) -> timezone-components

Returns a new timezone-components object.

timezone-components?

[procedure] (timezone-components? OBJECT) -> boolean

Is the specified OBJECT actually a timezone-components object?

Note that a timezone-components object is-a locale-components object.

error-timezone-components

[procedure] (error-timezone-components LOCATION OBJECT [ARGUMENT-NAME])

Raise a type-error.

check-timezone-components

[procedure] (check-timezone-components LOCATION OBJECT [ARGUMENT-NAME]) -> timezone-components

Raise a type-error unless the OBJECT is a valid timezone-components.

timezone-components-exists?

[procedure] (timezone-components-exists? TIMEZONE-COMPONENTS KEY) -> boolean

Does the specified TIMEZONE-COMPONENTS have a value for KEY?

timezone-component-ref

[procedure] (timezone-component-ref TIMEZONE-COMPONENTS KEY [DEFAULT #f])

Returns the timezone-component KEY of the TIMEZONE-COMPONENTS object, or the DEFAULT for a missing component.

set-timezone-component!

[procedure] (set-timezone-component! TIMEZONE-COMPONENTS KEY VALUE)

Sets the timezone-component KEY of the TIMEZONE-COMPONENTS object to VALUE.

update-timezone-components!

[procedure] (update-timezone-components! TIMEZONE-COMPONENTS KEY VALUE ...) -> timezone-components

Updates in place the TIMEZONE-COMPONENTS with the specified KEY+VALUE pairs.

timezone-dst-rule-julian-noleap?

[procedure] (timezone-dst-rule-julian-noleap? OBJECT) -> boolean

Is the specified OBJECT actually a daylight saving time julian day without leap seconds object?

timezone-dst-rule-julian-leap?

[procedure] (timezone-dst-rule-julian-leap? OBJECT) -> boolean

Is the specified OBJECT actually a daylight saving time julian day assuming leap seconds object?

timezone-dst-rule-mwd?

[procedure] (timezone-dst-rule-mwd? OBJECT) -> boolean

Is the specified OBJECT actually a daylight saving time month+week+day object?

timezone-dst-rule-offset

[procedure] (timezone-dst-rule-offset TIMEZONE-DST-RULE) -> INTEGER

Returns the seconds within day offset component of the specified TIMEZONE-DST-RULE object.

timezone-dst-rule-julian

[procedure] (timezone-dst-rule-julian TIMEZONE-DST-RULE) -> INTEGER

Returns the julian day component of the specified TIMEZONE-DST-RULE object.

timezone-dst-rule-month

[procedure] (timezone-dst-rule-month TIMEZONE-DST-RULE) -> INTEGER

Returns the month of year component of the specified TIMEZONE-DST-RULE object.

timezone-dst-rule-week

[procedure] (timezone-dst-rule-week TIMEZONE-DST-RULE) -> INTEGER

Returns the week of month component of the specified TIMEZONE-DST-RULE object.

timezone-dst-rule-day

[procedure] (timezone-dst-rule-day TIMEZONE-DST-RULE) -> INTEGER

Returns the day of week component of the specified TIMEZONE-DST-RULE object.

make-timezone-dst-rule-julian-leap

[procedure] (make-timezone-dst-rule-julian-leap JULIAN-DAY OFFSET) -> TIMEZONE-DST-RULE

Returns a daylight saving time julian day assuming leap seconds rule object.

make-timezone-dst-rule-julian-noleap

[procedure] (make-timezone-dst-rule-julian-noleap JULIAN-DAY OFFSET) -> TIMEZONE-DST-RULE

Returns a daylight saving time julian day without leap seconds rule object.

make-timezone-dst-rule-mwd

[procedure] (make-timezone-dst-rule-mwd MONTH WEEK DAY OFFSET) -> TIMEZONE-DST-RULE

Returns a daylight saving time month.week.day rule object.

local-timezone-name

[procedure] (local-timezone-name TV | YEAR MONTH DAY [HOUR 12 [MINUTE 0 [SECOND 0]]]) -> string

Returns the timezone for the given date as a string, (e.g. "EST").

The date maybe specified using a 10-element time-vector TV or separately as YEAR MONTH DAY [HOUR 12 [MINUTE 0 [SECOND 0]]].

YEAR will be biased by -1900, except for a TV argument. ((MONTH}} in [0 11]. DAY in [1 31]. HOUR in [0 23]. MINUTE in [0 59]. SECOND in [0 60].

local-timezone-offset

[procedure] (local-timezone-offset TV | YEAR MONTH DAY [HOUR 12 [MINUTE 0 [SECOND 0]]]) -> integer

Returns the timezone offset as seconds where positive is east of UTC & negative is west of UTC.

local-timezone-name+offset

[procedure] (local-timezone-name+offset TV | YEAR MONTH DAY [HOUR 12 [MINUTE 0 [SECOND 0]]]) -> (integer string)

Returns the timezone offset as seconds where positive is east of UTC & negative is west of UTC.

with-tzset

[procedure] (with-tzset TZ THUNK) -> object

Invoke THUNK with the TZ environment variable bound to the string TZ. Uses the C library routine tzset. Restores the original TZ value, unsets the TZ variable, as appropriate.

timezone-offset?

[procedure] (timezone-offset? OBJECT) -> boolean

Is the OBJECT a valid timezone offset in +/- seconds.

error-timezone-offset

[procedure] (error-timezone-offset LOCATION OBJECT [ARGUMENT-NAME])

Raise a type-error.

check-timezone-offset

[procedure] (check-timezone-offset LOCATION OBJECT [ARGUMENT-NAME])

Raise a type-error unless the OBJECT a valid timezone offset in +/- seconds.

Locale Category

Access to the locale information by category.

Locale Category Keys (others are possible):

current: A locale-components object.
address: A locale-components object.
collate: A locale-components object.
ctype: A locale-components object.
identification: A locale-components object.
language: A language-components object.
measurement: A locale-components object.
messages: A locale-components object.
monetary: A locale-components object.
name: A locale-components object.
numeric: A locale-components object.
paper: A locale-components object.
telephone: A locale-components object.
time: A locale-components object.
timezone: A timezone-components object.

locale-category-ref

[procedure] (locale-category-ref CATEGORY [DEFAULT #f]) -> locale-components

Returns the specified CATEGORY locale-components object, or #f if the category is not valued; not defined. Uses the (current-locale-dictionary).

set-locale-category!

[procedure] (set-locale-category! CATEGORY LOCALE-COMPONENTS)

Sets the specified CATEGORY to the specified LOCALE-COMPONENTS object. A VALUE of #f will delete the category identified by KEY. Uses the (current-locale-dictionary).

current-locale-dictionary

[parameter] (current-locale-dictionary) -> locale-categories
[parameter] (current-locale-dictionary LOCALE-CATEGORIES)

Gets and sets the current LOCALE-CATEGORIES object.

make-locale-dictionary

[procedure] (make-locale-dictionary) -> locale-categories

Returns a new locale-categories object.

locale-dictionary?

[procedure] (locale-dictionary? OBJECT) -> boolean

Is the specified OBJECT a locale-categories object?

locale-dictionary-category

[procedure] (locale-dictionary-category LOCALE-CATEGORIES KEY [DEFAULT #f]) -> object

Returns the value for KEY in the LOCALE-CATEGORIES.

set-locale-dictionary-category!

[procedure] (set-locale-dictionary-category! LOCALE-CATEGORIES KEY VALUE)

Changes the VALUE for KEY in the LOCALE-CATEGORIES. A VALUE of #f will delete the category identified by KEY.

Notes

locale-setup is performed at first use by the locale-current module.

Requirements

check-errors srfi-1 utf8

test test-utils

Bugs and Limitations

Currently only, some, Posix locale information is supported.
As stated above no collation, normalization, formatting, or any other locale specific operation one might expect to find in a component named locale.
Incomplete Posix support.
No Native support.

Author

Kon Lovett

Repository

This egg is hosted on the CHICKEN Subversion repository:

https://anonymous@code.call-cc.org/svn/chicken-eggs/release/5/locale

If you want to check out the source code repository of this egg and you are not familiar with Subversion, see this page.

Version history

0.9.4: Quicker startup.
0.9.3: Drop 'utf8 for Posix environment-variables regular-expression based parsing.
0.9.2: .
0.9.1: .
0.9.0: Add utf8 dependency. Remove srfi-13 dependency.
0.8.6: .
0.8.5: Remove regex dependency.
0.8.4: .
0.8.3: .
0.8.2: .
0.8.1: .
0.8.0: CHICKEN 5.
0.7.3: Add some TZ by name support.
0.7.2: Add Posix TZ offset name support.
0.7.1: TLS locale-setup.
0.7.0: Delay locale-setup.
0.6.12: Added 'current locale category. Dropped builtin 'language category. Deprecated local-timezone, added local-timezone-name.
0.6.11: Fix gnu-language-string->locale-components, with-tzset, and check-locale-components 'name test.
0.6.10: Fix another get-environment-variable and non-existent TZ envvar.
0.6.9: Added locale-setup.
0.6.8: Added locale-component=? & timezone-component=?.
0.6.7: Replace getenv with get-environment-variable.
0.6.6: Explicit regex dependency.
0.6.5: .
0.6.4: .
0.6.3: Fix for defaulted dst offset in TZ parsing [provided by David Murray]
0.6.2: Exported check/error- routines
0.6.1: Bug fix
0.6.0: Initial Chicken 4 release

License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the Software), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.