((section 2 "Outdated egg!" (p "This is an egg for CHICKEN 4, the unsupported old release.  You're almost certainly looking for " (int-link "/eggref/5/locale" "the CHICKEN 5 version of this egg") ", if it exists.") (p "If it does not exist, there may be equivalent functionality provided by another egg; have a look at the " (link "https://wiki.call-cc.org/chicken-projects/egg-index-5.html" "egg index") ". Otherwise, please consider porting this egg to the current version of CHICKEN.") (tags "egg")) (section 2 "locale" (p "Provides locale operations.") (toc)) (section 2 "Documentation" (p (tt "locale") " is a set of routines supporting locale query operations. The environment locale information is determined lazily.") (p (tt "locale") " does not interact with the C library routines " (tt "setlocale") " or " (tt "tzset") ", except for the " (tt "with-tzset") " routine (see below).") (p (tt "locale") " does not provide a:") (ul (li "localized message service, see " (int-link "srfi-29" "SRFI 29") ".") (li "localized time service, see " (int-link "srfi-19" "SRFI 19") ".") (li "a localized collating service.")) (p (tt "locale") " does not provide much of anything beyond locale identification.") (section 3 "Locale Components Structure" (p "The major data structure is the " (tt "locale-components") " object, portrayed as an extensible " (tt "key+value") " pairing. The " (tt "key") " is a " (tt "symbol") ". The " (tt "value") " is usually a " (tt "string") ".") (p "A " (tt "locale-components") " object will have more properties but the following are provided for every instance:") (p "Common Component Keys:") (dl (dt (tt "tag")) (dd "What kind; a " (tt "symbol") ". Examples: 'locale and 'timezone.") (dt (tt "source")) (dd "The origin for the information; either " (tt "#f") ", a " (tt "string") " or " (tt "(string object...)") " (a " (tt "composite-source") ").") (dt (tt "name")) (dd "The composite information object; source specific.")) (p "A primary " (tt "source") " is one of the following (others are possible):") (dl (dt (tt "\"PLATFORM\"")) (dd "Information from the system. The " (tt "name") " is usually a " (tt "pointer") ".") (dt (tt "\"POSIX\"")) (dd "Information from POSIX environment. The " (tt "name") " is a " (tt "string") ".") (dt (tt "\"GNU\"")) (dd "Information from GNU environment. The " (tt "name") " is a " (tt "string") ".") (dt (tt "\"BUILTIN\"")) (dd "Information from system defaults. The " (tt "name") " is a " (tt "string") ".")) (ul (li "The " (tt "PLATFORM") " source is used for information first. (Currently unavailable.)") (li "Then the " (tt "POSIX") " + " (tt "GNU") " source is attempted.") (li "When all have failed the " (tt "BUILTIN") " source is used.")) (p "The point being locale information will be available, but without an accuracy guarantee.") (p "The " (tt "BUILTIN") " source creates a POSIX-style " (tt "string") " " (tt "name") " constructed using constants and library procedures.") (p "When the " (tt "source") " is from an environment variable a " (tt "composite-source") " is created. Examples: " (tt "(\"POSIX\" \"TZ\")") ", " (tt "(\"GNU\" \"LANGUAGE\")") ".")) (section 3 "Locale Components" (section 4 "make-locale-components" (def (sig (procedure "(make-locale-components NAME [SOURCE #f [TAG 'locale]]) -> locale-components" (id make-locale-components))) (p "Returns a new " (tt "locale-components") " object."))) (section 4 "locale-components?" (def (sig (procedure "(locale-components? OBJECT) -> boolean" (id locale-components?))) (p "Is the " (tt "OBJECT") " a " (tt "locale-components") " object?"))) (section 4 "error-locale-components" (def (sig (procedure "(error-locale-components LOCATION OBJECT [ARGUMENT-NAME])" (id error-locale-components))) (p "Raise a type-error."))) (section 4 "check-locale-components" (def (sig (procedure "(check-locale-components LOCATION OBJECT [ARGUMENT-NAME]) -> locale-components" (id check-locale-components))) (p "Raise a type-error unless the " (tt "OBJECT") " is a valid locale-components."))) (section 4 "locale-components-exists?" (def (sig (procedure "(locale-components-exists? LOCALE-COMPONENTS KEY) -> boolean" (id locale-components-exists?))) (p "Does the specified " (tt "LOCALE-COMPONENTS") " have a value for " (tt "KEY") "?"))) (section 4 "locale-component-ref" (def (sig (procedure "(locale-component-ref LOCALE-COMPONENTS KEY [DEFAULT #f]) -> object" (id locale-component-ref))) (p "Returns the " (tt "KEY") " property of " (tt "LOCALE-COMPONENTS") " or the " (tt "DEFAULT") " when not found."))) (section 4 "set-locale-component!" (def (sig (procedure "(set-locale-component! LOCALE-COMPONENTS KEY VALUE)" (id set-locale-component!))) (p "Updates or creates the " (tt "KEY") " property of " (tt "LOCALE-COMPONENTS") " with the " (tt "VALUE") "."))) (section 4 "update-locale-components!" (def (sig (procedure "(update-locale-components! LOCALE-COMPONENTS KEY VALUE ...) -> locale-components" (id update-locale-components!))) (p "Updates in place the " (tt "LOCALE-COMPONENTS") " with the specified " (tt "KEY+VALUE") " pairs.")))) (section 3 "Locale" (p "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.") (p "Locale Properties:") (dl (dt "language") (dd "ISO 639-1 or ISO 639-2 name string. Default \"en\".") (dt "script") (dd "RFC 3066bis name string.") (dt "region") (dd "ISO 3166-1 name string. Default \"US\".") (dt "codeset") (dd "The character code to character mapping system.") (dt "modifier") (dd "Instance data, if any.")) (section 4 "locale-setup" (def (sig (procedure "(locale-setup)" (id locale-setup))) (p "Loads the locale, including timezone, information from the primary " (tt "source") ".") (p "This is the procedure used to initialize the locale."))) (section 4 "current-locale" (def (sig (procedure "(current-locale) -> string" (id current-locale)) (procedure "(current-locale VALUE)" (id current-locale))) (p "The currently defined locale. Returns the locale name string.") (p "The specified " (tt "VALUE") " is either a locale string value, a " (tt "locale-components") " object or " (tt "#f") ", indicating locale independence.") (p "When no locale value is set the default locale is " (tt "#f") "."))) (section 4 "current-locale-component" (def (sig (procedure "(current-locale-components) -> locale-components" (id current-locale-components))) (p "Returns the " (tt "locale-components") " object corresponding to the current-locale."))) (section 4 "posix-locale-string->locale-components" (def (sig (procedure "(posix-locale-string->locale-components STRING [SOURCE \"POSIX\" [TAG 'locale]]) -> locale-components" (id posix-locale-string->locale-components))) (p "Parses a POSIX locale string specification, " (tt "STRING") ", and returns the corresponding locale-components object.") (p "The optional " (tt "SOURCE") " indicates what locale system supplied the string."))) (section 4 "posix-load-local" (def (sig (procedure "(posix-load-locale)" (id posix-load-locale))) (p "Sets up the locale using POSIX rules. Initializes the " (tt "current-locale") " from the " (tt "MESSAGES") " category.") (p "The Posix pathname locale is currently unsupported.") (p "The \"C\" & \"POSIX\" locales are unsupported.")))) (section 3 "Timezone" (p "Access to timezone information. A timezone object is a " (tt "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.") (p "Timezone Component Properties:") (dl (dt "std-name") (dd "The Standard timezone name.") (dt "std-offset") (dd "Seconds +/- UTC.") (dt "dst-name") (dd "The Daylight Saving Time timezone name.") (dt "dst-offset") (dd "Seconds +/- UTC.") (dt "dst-start") (dd "The start of Daylight Saving Time; a timezone-dst-rule.") (dt "dst-end") (dd "The end of Daylight Saving Time; a timezone-dst-rule.") (dt "dst?") (dd "DST in effect?")) (section 4 "current-timezone" (def (sig (procedure "(current-timezone) -> string" (id current-timezone)) (procedure "(current-timezone VALUE)" (id current-timezone))) (p "The currently defined timezone. Returns the timezone name string.") (p "The specified " (tt "VALUE") " is either a timezone string value, a " (tt "timezone-components") " or " (tt "#f") ", indicating no timezone.") (p "When no timezone value is set the default timezone is UTC."))) (section 4 "current-timezone-component" (def (sig (procedure "(current-timezone-components) -> timezone-components" (id current-timezone-components))) (p "Returns the timezone-components object corresponding to the current-timezone."))) (section 4 "posix-timezone-string->timezone-components" (def (sig (procedure "(posix-timezone-string->timezone-components STRING [SOURCE \"POSIX\"]) -> timezone-components" (id posix-timezone-string->timezone-components))) (p "Parses a POSIX timezone string specification, " (tt "STRING") ", and returns the corresponding timezone-components object.") (p "The optional " (tt "SOURCE") " indicates what locale system supplied the string."))) (section 4 "posix-load-timezone" (def (sig (procedure "(posix-load-timezone)" (id posix-load-timezone))) (p "Initialize the current-timezone from the TZ environment variable.") (p "The Posix pathname and implementation-defined timezone is currently unsupported.")))) (section 3 "Timezone Components" (section 4 "make-timezone-components" (def (sig (procedure "(make-timezone-components NAME [SOURCE #f]) -> timezone-components" (id make-timezone-components))) (p "Returns a new " (tt "timezone-components") " object."))) (section 4 "timezone-components?" (def (sig (procedure "(timezone-components? OBJECT) -> boolean" (id timezone-components?))) (p "Is the specified " (tt "OBJECT") " actually a timezone-components object?") (p "Note that a " (tt "timezone-components") " object is-a " (tt "locale-components") " object."))) (section 4 "error-timezone-components" (def (sig (procedure "(error-timezone-components LOCATION OBJECT [ARGUMENT-NAME])" (id error-timezone-components))) (p "Raise a type-error."))) (section 4 "check-timezone-components" (def (sig (procedure "(check-timezone-components LOCATION OBJECT [ARGUMENT-NAME]) -> timezone-components" (id check-timezone-components))) (p "Raise a type-error unless the " (tt "OBJECT") " is a valid timezone-components."))) (section 4 "timezone-components-exists?" (def (sig (procedure "(timezone-components-exists? TIMEZONE-COMPONENTS KEY) -> boolean" (id timezone-components-exists?))) (p "Does the specified " (tt "TIMEZONE-COMPONENTS") " have a value for " (tt "KEY") "?"))) (section 4 "timezone-component-ref" (def (sig (procedure "(timezone-component-ref TIMEZONE-COMPONENTS KEY [DEFAULT #f])" (id timezone-component-ref))) (p "Returns the timezone-component " (tt "KEY") " of the " (tt "TIMEZONE-COMPONENTS") " object, or the " (tt "DEFAULT") " for a missing component."))) (section 4 "set-timezone-component!" (def (sig (procedure "(set-timezone-component! TIMEZONE-COMPONENTS KEY VALUE)" (id set-timezone-component!))) (p "Sets the timezone-component " (tt "KEY") " of the " (tt "TIMEZONE-COMPONENTS") " object to " (tt "VALUE") "."))) (section 4 "update-timezone-components!" (def (sig (procedure "(update-timezone-components! TIMEZONE-COMPONENTS KEY VALUE ...) -> timezone-components" (id update-timezone-components!))) (p "Updates in place the " (tt "TIMEZONE-COMPONENTS") " with the specified " (tt "KEY+VALUE") " pairs."))) (section 4 "timezone-dst-rule-julian-noleap?" (def (sig (procedure "(timezone-dst-rule-julian-noleap? OBJECT) -> boolean" (id timezone-dst-rule-julian-noleap?))) (p "Is the specified " (tt "OBJECT") " actually a daylight saving time julian day without leap seconds object?"))) (section 4 "timezone-dst-rule-julian-leap?" (def (sig (procedure "(timezone-dst-rule-julian-leap? OBJECT) -> boolean" (id timezone-dst-rule-julian-leap?))) (p "Is the specified " (tt "OBJECT") " actually a daylight saving time julian day assuming leap seconds object?"))) (section 4 "timezone-dst-rule-mwd?" (def (sig (procedure "(timezone-dst-rule-mwd? OBJECT) -> boolean" (id timezone-dst-rule-mwd?))) (p "Is the specified " (tt "OBJECT") " actually a daylight saving time month+week+day object?"))) (section 4 "timezone-dst-rule-offset" (def (sig (procedure "(timezone-dst-rule-offset TIMEZONE-DST-RULE) -> INTEGER" (id timezone-dst-rule-offset))) (p "Returns the seconds within day offset component of the specified " (tt "TIMEZONE-DST-RULE") " object."))) (section 4 "timezone-dst-rule-julian" (def (sig (procedure "(timezone-dst-rule-julian TIMEZONE-DST-RULE) -> INTEGER" (id timezone-dst-rule-julian))) (p "Returns the julian day component of the specified " (tt "TIMEZONE-DST-RULE") " object."))) (section 4 "timezone-dst-rule-month" (def (sig (procedure "(timezone-dst-rule-month TIMEZONE-DST-RULE) -> INTEGER" (id timezone-dst-rule-month))) (p "Returns the month of year component of the specified " (tt "TIMEZONE-DST-RULE") " object."))) (section 4 "timezone-dst-rule-week" (def (sig (procedure "(timezone-dst-rule-week TIMEZONE-DST-RULE) -> INTEGER" (id timezone-dst-rule-week))) (p "Returns the week of month component of the specified " (tt "TIMEZONE-DST-RULE") " object."))) (section 4 "timezone-dst-rule-day" (def (sig (procedure "(timezone-dst-rule-day TIMEZONE-DST-RULE) -> INTEGER" (id timezone-dst-rule-day))) (p "Returns the day of week component of the specified " (tt "TIMEZONE-DST-RULE") " object."))) (section 4 "make-timezone-dst-rule-julian-leap" (def (sig (procedure "(make-timezone-dst-rule-julian-leap JULIAN-DAY OFFSET) -> TIMEZONE-DST-RULE" (id make-timezone-dst-rule-julian-leap))) (p "Returns a daylight saving time julian day assuming leap seconds rule object."))) (section 4 "make-timezone-dst-rule-julian-noleap" (def (sig (procedure "(make-timezone-dst-rule-julian-noleap JULIAN-DAY OFFSET) -> TIMEZONE-DST-RULE" (id make-timezone-dst-rule-julian-noleap))) (p "Returns a daylight saving time julian day without leap seconds rule object."))) (section 4 "make-timezone-dst-rule-mwd" (def (sig (procedure "(make-timezone-dst-rule-mwd MONTH WEEK DAY OFFSET) -> TIMEZONE-DST-RULE" (id make-timezone-dst-rule-mwd))) (p "Returns a daylight saving time month.week.day rule object."))) (section 4 "local-timezone-name" (def (sig (procedure "(local-timezone-name TV | YEAR MONTH DAY [HOUR 12 [MINUTE 0 [SECOND 0]]]) -> string" (id #f))) (p "Returns the timezone for the given date as a string, (e.g. \"EST\").") (p "The date maybe specified using a 10-element time-vector " (tt "TV") " or separately as " (tt "YEAR MONTH DAY [HOUR 12 [MINUTE 0 [SECOND 0]]]") ".") (p (tt "YEAR") " will be biased by " (tt "-1900") ", except for a " (tt "TV") " argument. ((MONTH}} in [0 11]. " (tt "DAY") " in [1 31]. " (tt "HOUR") " in [0 23]. " (tt "MINUTE") " in [0 59]. " (tt "SECOND") " in [0 60].") (p (tt "local-timezone") " is " (b "deprecated") "."))) (section 4 "local-timezone-offset" (def (sig (procedure "(local-timezone-offset TV | YEAR MONTH DAY [HOUR 12 [MINUTE 0 [SECOND 0]]]) -> integer" (id #f))) (p "Returns the timezone offset as seconds where positive is east of UTC & negative is west of UTC."))) (section 4 "local-timezone-name+offset" (def (sig (procedure "(local-timezone-name+offset TV | YEAR MONTH DAY [HOUR 12 [MINUTE 0 [SECOND 0]]]) -> (integer string)" (id #f))) (p "Returns the timezone offset as seconds where positive is east of UTC & negative is west of UTC."))) (section 4 "with-tzset" (def (sig (procedure "(with-tzset TZ THUNK) -> object" (id with-tzset))) (p "Invoke " (tt "THUNK") " with the TZ environment variable bound to the string " (tt "TZ") ". Uses the C library routine " (tt "tzset") ". Restores the original TZ value, unsets the TZ variable, as appropriate."))) (section 4 "timezone-offset?" (def (sig (procedure "(timezone-offset? OBJECT) -> boolean" (id timezone-offset?))) (p "Is the " (tt "OBJECT") " a valid timezone offset in +/- seconds."))) (section 4 "error-timezone-offset" (def (sig (procedure "(error-timezone-offset LOCATION OBJECT [ARGUMENT-NAME])" (id error-timezone-offset))) (p "Raise a type-error."))) (section 4 "check-timezone-offset" (def (sig (procedure "(check-timezone-offset LOCATION OBJECT [ARGUMENT-NAME])" (id check-timezone-offset))) (p "Raise a type-error unless the " (tt "OBJECT") " a valid timezone offset in +/- seconds.")))) (section 3 "Locale Category" (p "Access to the locale information by category.") (p "Locale Category Keys (others are possible):") (dl (dt "current") (dd "A {{locale-components} object.") (dt "address") (dd "A {{locale-components} object.") (dt "collate") (dd "A {{locale-components} object.") (dt "ctype") (dd "A {{locale-components} object.") (dt "identification") (dd "A {{locale-components} object.") (dt "language") (dd "A {{language-components} object.") (dt "measurement") (dd "A {{locale-components} object.") (dt "messages") (dd "A {{locale-components} object.") (dt "monetary") (dd "A {{locale-components} object.") (dt "name") (dd "A {{locale-components} object.") (dt "numeric") (dd "A {{locale-components} object.") (dt "paper") (dd "A {{locale-components} object.") (dt "telephone") (dd "A {{locale-components} object.") (dt "time") (dd "A {{locale-components} object.") (dt "timezone") (dd "A {{timezone-components} object.")) (section 4 "locale-category-ref" (def (sig (procedure "(locale-category-ref CATEGORY [DEFAULT #f]) -> locale-components" (id locale-category-ref))) (p "Returns the specified " (tt "CATEGORY") " locale-components object, or " (tt "#f") " if the category is not valued; not defined. Uses the " (tt "(current-locale-dictionary)") "."))) (section 4 "set-locale-category!" (def (sig (procedure "(set-locale-category! CATEGORY LOCALE-COMPONENTS)" (id set-locale-category!))) (p "Sets the specified " (tt "CATEGORY") " to the specified " (tt "LOCALE-COMPONENTS") " object. A " (tt "VALUE") " of " (tt "#f") " will delete the category identified by " (tt "KEY") ". Uses the " (tt "(current-locale-dictionary)") "."))) (section 4 "current-locale-dictionary" (def (sig (parameter "(current-locale-dictionary) -> locale-categories" (id current-locale-dictionary)) (parameter "(current-locale-dictionary LOCALE-CATEGORIES)" (id current-locale-dictionary))) (p "Gets and sets the current " (tt "LOCALE-CATEGORIES") " object."))) (section 4 "make-locale-dictionary" (def (sig (procedure "(make-locale-dictionary) -> locale-categories" (id make-locale-dictionary))) (p "Returns a new " (tt "locale-categories") " object."))) (section 4 "locale-dictionary?" (def (sig (procedure "(locale-dictionary? OBJECT) -> boolean" (id locale-dictionary?))) (p "Is the specified " (tt "OBJECT") " a " (tt "locale-categories") " object?"))) (section 4 "locale-dictionary-category" (def (sig (procedure "(locale-dictionary-category LOCALE-CATEGORIES KEY [DEFAULT #f]) -> object" (id locale-dictionary-category))) (p "Returns the value for " (tt "KEY") " in the " (tt "LOCALE-CATEGORIES") "."))) (section 4 "set-locale-dictionary-category!" (def (sig (procedure "(set-locale-dictionary-category! LOCALE-CATEGORIES KEY VALUE)" (id set-locale-dictionary-category!))) (p "Changes the " (tt "VALUE") " for " (tt "KEY") " in the " (tt "LOCALE-CATEGORIES") ". A " (tt "VALUE") " of " (tt "#f") " will delete the category identified by " (tt "KEY") "."))))) (section 2 "Usage" (highlight scheme "(require-extension locale)")) (section 2 "Notes" (ul (li "Currently only, some, Posix locale information is supported.") (li (tt "locale-setup") " is performed at first use by the " (tt "locale-current") " module."))) (section 2 "Requirements" (p (int-link "lookup-table" "lookup-table") " " (int-link "miscmacros" "miscmacros") " " (int-link "check-errors" "check-errors") " " (int-link "regex")) (p (int-link "setup-helper"))) (section 2 "Bugs and Limitations" (ul (li "As stated above no collation, normalization, formatting, or any other locale specific operation one might expect to find in a component named " (i "locale") ".") (li "Incomplete Posix support.") (li "No Native support."))) (section 2 "Author" (p (int-link "/users/kon-lovett" "Kon Lovett"))) (section 2 "Version history" (dl (dt "0.7.3") (dd "Add some TZ by name support.") (dt "0.7.2") (dd "Add Posix TZ offset name support.") (dt "0.7.1") (dd "TLS " (tt "locale-setup") ".") (dt "0.7.0") (dd "Delay " (tt "locale-setup") ".") (dt "0.6.12") (dd "Added " (tt "'current") " locale category. Dropped " (i "builtin") " " (tt "'language") " category. Deprecated " (tt "local-timezone") ", added " (tt "local-timezone-name") ".") (dt "0.6.11") (dd "Fix " (tt "gnu-language-string->locale-components") ", " (tt "with-tzset") ", and " (tt "check-locale-components") " " (tt "'name") " test.") (dt "0.6.10") (dd "Fix another " (tt "get-environment-variable") " and non-existent TZ envvar.") (dt "0.6.9") (dd "Added " (tt "locale-setup") ".") (dt "0.6.8") (dd "Added " (tt "locale-component=?") " & " (tt "timezone-component=?") ".") (dt "0.6.7") (dd "Replace " (tt "getenv") " with " (tt "get-environment-variable") ".") (dt "0.6.6") (dd "Explicit " (tt "regex") " dependency.") (dt "0.6.5") (dt "0.6.4") (dt "0.6.3") (dd "Fix for defaulted dst offset in TZ parsing [provided by David Murray]") (dt "0.6.2") (dd "Exported check/error- routines") (dt "0.6.1") (dd "Bug fix") (dt "0.6.0") (dd "Initial Chicken 4 release"))) (section 2 "License" (p "Copyright (C) 2009-2010 Kon Lovett.  All rights reserved.") (p "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:") (p "The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.") (p "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.")))