You can edit this page using wiki syntax for markup.

Article contents:[[tags: egg]] == srfi-29 [[toc:]] == Documentation A Chicken implementation of [[http://srfi.schemers.org/srfi-29/srfi-29.html|SRFI 29]]. The addition of the escape code {{~[n]@*}} to the SRFI 28 {{format}} is '''not''' part of this extension. === Conditions ==== undefined-condition? <procedure>(undefined-condition? OBJECT) -> boolean</procedure> Is the {{OBJECT}} an instance of the SRFI 29 {{undefined-condition}}. A {{composite-property-condition}} of {{(exn srfi-29 undefined)}}. ==== unbound-variable-condition? <procedure>(unbound-variable-condition? OBJECT) -> boolean</procedure> Is the {{OBJECT}} an instance of the SRFI 29 {{unbound-variable-condition}}. A {{composite-property-condition}} of {{(exn srfi-29 unbound)}}. === Parameters ==== current-language <parameter>(current-language [LANGUAGE]) -> symbol</parameter> Gets or sets the {{LANGUAGE}} symbol. ==== current-country <parameter>(current-country [COUNTRY]) -> symbol</parameter> Gets or sets the {{COUNTRY}} symbol. ==== current-locale-details <parameter>(current-locale-details [LOCALE-DETAILS]) -> list</parameter> Gets or sets the {{LOCALE-DETAILS}} list. ==== current-locale-format-function <parameter>(current-locale-format-function [FORMAT-PROCEDURE]) -> procedure</parameter> Gets or sets the {{FORMAT-PROCEDURE}}. This procedure must at least have the signature of a SRFI 28 {{format}} procedure. The default is the Chicken {{extras#format}} procedure. ==== reset-locale-parameters <procedure>(reset-locale-parameters)</procedure> When the {{current-locale}} is changed (see the [[locale|locale egg]]) the {{current-*}} parameters need not be set individually. This will update those parameters to the values in the new locale. ''Reset'' as in set anew. === Bundle Operations * A {{BUNDLE-SPECIFIER}} is a list of symbols of the form {{(PACKAGE-NAME [LANGUAGE] [COUNTRY] [DETAILS...])}}. * A {{TEMPLATE-NAME}} is something suitable as a key, such as a {{symbol}} or {{string}}, but can be any {{object}} with a readable printname. * A {{TEMPLATE-VALUE}} maybe any object, but should have a readable printname. * A {{BUNDLE-ALIST}} is an alist with key {{TEMPLATE-NAME}} & value {{TEMPLATE-VALUE}}. So {{(cons 'template-example 'value-example)}} is legal, whereas {{(list 'template-example 'value-example)}} is not. The form {{(list 'template-example 'value-example)}} will have the value {{(list 'value-example)}}, and not {{'value-example}}, as expected. ==== declare-bundle! <procedure>(declare-bundle! BUNDLE-SPECIFIER BUNDLE-ALIST)</procedure> Creates a bundle. ==== undeclare-bundle! <procedure>(undeclare-bundle! BUNDLE-SPECIFIER)</procedure> Removes the bundle specified by {{BUNDLE-SPECIFIER}} from the active bundles. === Bundle Database Operations SRFI 29 does not specify how bundles are stored. This extension uses the filesystem for the bundle database. Bundles are stored in the {{system-bundle-directory}}, unless an {{ALTERNATE}} directory is specified. Within a bundle directory the structure is {{(directory [LANGUAGE] [COUNTRY] [SCRIPT] [CODESET] [MODIFIER] PACKAGE-NAME)}}. ==== system-bundle-directory <parameter>(system-bundle-directory [DIRECTORY-PATHNAME])</parameter> Initially {{DIRECTORY-PATHNAME}} is {{(make-pathname (repository-path) "srfi-29-bundles")}}. ==== existing-bundle? <procedure>existing-bundle? BUNDLE-SPECIFIER [ALTERNATE])</procedure> Does the bundle specified by {{BUNDLE-SPECIFIER}} exist in the active bundles, and the filesystem. ==== store-bundle! <procedure>(store-bundle! BUNDLE-SPECIFIER [ALTERNATE])</procedure> Stores the bundle using the {{write}} procedure. ==== load-bundle! <procedure>(load-bundle! BUNDLE-SPECIFIER [ALTERNATE])</procedure> Loads the bundle using the {{read}} procedure. ==== load-best-available-bundle! <procedure>(load-best-available-bundle! BUNDLE-SPECIFIER [ALTERNATE])</procedure> Attempts {{(load-bundle! BUNDLE-SPECIFIER [ALTERNATE])}}, from most to least specific. See {{most-specific-bundle-specifier}}. ==== remove-bundle! <procedure>(remove-bundle! BUNDLE-SPECIFIER [ALTERNATE])</procedure> Removes the bundle specified by {{BUNDLE-SPECIFIER}} from the active bundles, and from the filesystem. Will not remove the locale directory hierarchy created by {{(store-bundle!...)}}. ==== remove-bundle-directory! <procedure>(remove-bundle-directory! BUNDLE-SPECIFIER [ALTERNATE])</procedure> Removes the bundle directory hierarchy created by {{(store-bundle!...)}}. Will only remove empty directories. Returns {{#t}} if operation succeeded, {{#f}} when a non-empty directory encountered. Does not remove the bundle, if any, from the active bundles. A filesystem only operation. This procedure should be used with caution. ==== declared-bundle-specifiers <procedure>(declared-bundle-specifiers) -> list</procedure> Returns a list of all the declared {{BUNDLE-SPECIFIER}}s. ==== declared-bundle-templates <procedure>(declared-bundle-templates BUNDLE-SPECIFIER) -> list</procedure> Returns an alist of all the templates for the {{BUNDLE-SPECIFIER}}. ==== most-specific-bundle-specifier <procedure>(most-specific-bundle-specifier PACKAGE-NAME) -> bundle-specifier</procedure> Returns the most specific bundle specifier for the current locale. The current locale is composed of the {{(current-language)}}, {{(current-country)}}, and {{(current-locale-details)}}. Note that the {{most-specific-bundle-specifier}} may not be a declared bundle. === Bundle Template Operations These routines will use the most specific declared bundle for the package {{PACKAGE-NAME}} in the current locale. ==== required-localized-template <procedure>(required-localized-template PACKAGE-NAME TEMPLATE-NAME) -> *</procedure> Returns the object for the {{TEMPLATE-NAME}} in {{PACKAGE-NAME}}. Otherwise a {{undefined-condition}} exception is raised. ==== localized-template <procedure>(localized-template PACKAGE-NAME TEMPLATE-NAME [PACKAGE-NOT-FOUND [TEMPLATE-NOT-FOUND]]) -> *</procedure> Returns the object for the {{TEMPLATE-NAME}} in {{PACKAGE-NAME}}. Otherwise the appropriate {{...-NOT-FOUND}} value. {{PACKAGE-NOT-FOUND}} and {{TEMPLATE-NOT-FOUND}} have default {{#t}}, ==== localized-template/default <procedure>(localized-template/default PACKAGE-NAME TEMPLATE-NAME [PACKAGE-NOT-FOUND [TEMPLATE-NOT-FOUND]]) -> *</procedure> Returns {{(localized-template PACKAGE-NAME TEMPLATE-NAME PACKAGE-NOT-FOUND TEMPLATE-NOT-FOUND)}}. {{PACKAGE-NOT-FOUND}} and {{TEMPLATE-NOT-FOUND}} have default {{TEMPLATE-NAME}}. Somewhat like the Posix 'gettext' routine. ==== make-localized-template <procedure>(make-localized-template PACKAGE-NAME) -> (procedure (symbol #!optional * *) *)</procedure> Returns a {{localized-template}}-like procedure curried upon the {{PACKAGE-NAME}}. ==== make-localized-template/default <procedure>(make-localized-template/default PACKAGE-NAME) -> (procedure (symbol #!optional * *) *)</procedure> Returns a {{localized-template/default}}-like procedure curried upon the {{PACKAGE-NAME}}. ==== make-required-localized-template <procedure>(make-required-localized-template PACKAGE-NAME) -> (procedure (symbol) *)</procedure> Like {{make-localized-template}} but raises an {{undefined-condition}} exception should the package or template be missing. ==== localized-format <procedure>(localized-format PACKAGE-NAME TEMPLATE-NAME ARG0...) -> string</procedure> Returns the formatted string using the {{(current-locale-format-function)}} and the format string {{(localized-template PACKAGE-NAME TEMPLATE-NAME)}} on the arguments {{ARG0...}}. When a localized-template is not found and the {{TEMPLATE-NAME}} is a {{string}} then it is used a the format-string. A representation is always displayed, even when no template is found. Just not a localized one. ==== localized-template-set! <procedure>(localized-template-set! PACKAGE-NAME TEMPLATE-NAME VALUE) -> boolean</procedure> Creates or updates the {{VALUE}} for the {{TEMPLATE-NAME}} in {{PACKAGE-NAME}} and returns {{#t}}, when the package exists. Otherwise returns {{#f}}. This can be used to extend the meaning of a package template at runtime. For example: caching the actual closure for a named procedure. ==== localized-templates <procedure>(localized-templates PACKAGE-NAME) -> list</procedure> Returns an alist of all the templates for the {{PACKAGE-NAME}}. ==== load-localized-compiled-code <procedure>(load-localized-compiled-code LIBRARY PACKAGE-NAME TEMPLATE-NAMES)</procedure> Loads a Scheme code library and replaces the toplevel variable references from the templates with the actual value. Each item {{package-name template-name}} has a variable reference upon entry. Upon exit this is replaced with the variable value after load. Every item {{package-name template-name}} referenced '''must''' be defined. Otherwise a {{(exn srfi-29 undefined)}} exception if raised. ; {{LIBRARY}} : {{pathname}}, {{unitname}}, or {{(unitname pathname)}} ; {{TEMPLATE-NAMES}} : {{(list-of template-name)}}. ; {{template-name}} : {{(or TEMPLATE-NAME variable-reference)}}. ; {{variable-reference}} : {{(or symbol (symbol symbol))}}. The corresponding load call for a {{LIBRARY}} form is {{load-relative}}, {{load-library}}, and {{load-library}}. (See [[http://wiki.call-cc.org/man/4/Unit%20eval|Unit eval]].) '''Notes''' * {{(symbol symbol)}} in {{variable-reference}} is a {{module}} import reference; this is a ''brittle'' feature as it relies upon knowledge of implementation details. * only {{load-relative}} is used for a library {{pathname}}. Be sure to provide an {{absolute-pathname}} when a {{current-directory}} relative {{pathname}} is needed. * ''This is an experimental API.'' === Exceptions * {{undefined-condition}} Signaled for unknown bundle-specification, package, template. * {{unbound-variable-condition}} Signaled for an unbound reference during ''localized code'' resolution. * {{(exn type)}} Signaled for argument type errors. * {{(exn) message = "invalid library load specificiation" arguments = LIBSPEC}} Signaled during ''localized code'' resolution for a bad library load name form. === Thread Local Storage Just as the [[locale]] extension supports per thread locale information so does this extension support per thread bundles. However, localized information is probably accessed more frequently than locale information. So the support for per thread bundles is delayed until runtime. Setting the environment variable {{SRFI29_TLS}} to {{[Yy1]}} before loading the runtime will activate the feature. When active each thread may have a different bundle for a package; i.e. a user of [[SRFI 19|srfi-19]] can have a different language in each thread. == Usage <enscript language=scheme> (import srfi-29) </enscript> == Notes * Possible race condition exists creating a bundle file or directory should another thread be performing the same action. * The locale symbols must have a lowercase printname! As such they do not truly reflect ISO 639-1/2 & ISO 3166-1 standard names. This is a SRFI 29 restriction. * {{(current-locale-details)}} is ill-defined by the SRFI 29 document. Which symbol means what? This implementation understands: ; {{locale-details}} : {{(list SCRIPT CODESET MODIFIER)}} ; SCRIPT : {{(or symbol #f)}} ; CODESET : {{(or symbol #f)}} ; MODIFIER : {{(or symbol #f)}} * The SRFI 29 document uses the term {{country}} for what the [[locale]] extension knows as {{region}}. == Requirements [[srfi-1|srfi-1]] [[srfi-69|srfi-69]] [[miscmacros|miscmacros]] [[moremacros|moremacros]] [[posix-utils|posix-utils]] [[locale|locale]] [[check-errors|check-errors]] [[condition-utils|condition-utils]] [[test|test]] [[test|test-utils]] == Bugs and Limitations * {{store-bundle!}} does not ensure filemode of 'a+rx' for the created directory tree. == Author [[/users/kon-lovett|Kon Lovett]] == Repository This egg is hosted on the CHICKEN Subversion repository: [[https://anonymous@code.call-cc.org/svn/chicken-eggs/release/5/srfi-29|https://anonymous@code.call-cc.org/svn/chicken-eggs/release/5/srfi-29]] If you want to check out the source code repository of this egg and you are not familiar with Subversion, see [[/egg-svn-checkout|this page]]. == Version history ; 3.1.0 : Add {{existing-bundle?}}. Fix {{current-language/country/locale-details}} cache invalidation. ; 3.0.11 : Remove ''sub-feature'' registration. ; 3.0.10 : Another attempt at compatibility w/ ''chicken-install''. ; 3.0.9 : Locate bundle directory along include path. ; 3.0.8 : Handle {{CHICKEN_INSTALL_PREFIX}} environment variable per ''chicken-install''. ; 3.0.7 : . ; 3.0.6 : . ; 3.0.5 : . ; 3.0.4 : Add strong typing. ; 3.0.3 : . ; 3.0.2 : . ; 3.0.1 : . ; 3.0.0 : C5 release. ; 2.5.0 : Added dependency on {{moremacros}}. ; 2.4.0 : Changed {{current-locale-format-function}} to {{parameter}}. Documented {{system-bundle-directory}}. ; 2.3.3 : ; 2.3.2 : Ensures filemode of 'a+rx' for bundles directory. ; 2.3.1 : ; 2.2.0 : Added runtime support for package per thread. Removed deprecated identifiers. ; 2.1.3 : Added {{unbound-variable-condition?}}. Deprecated {{!localized-template}} & {{make-!localized-template}} in favor of {{required-localized-template}} & {{make-required-localized-template}}. ; 2.1.2 : ; 2.1.1 : ; 2.1.0 : Added {{undefined-condition?}}, {{!localized-template}}, {{make-localized-template}}, {{make-localized-template/default}}, {{load-localized-compiled-code}}. {{localized-template}} & {{localized-template/default}} now distinguish an undefined template from an undefined package. ; 2.0.1 : Fixs for {{bundle-specifier?}} and {{load-best-available-bundle!}} ; 2.0.0 : Intitial Chicken 4 release. Added introspection routines. Removed {{PORT}} parameter for {{localized-format}}. == License Copyright (C) 2010-2024 Kon Lovett. All rights reserved. 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. Description of your changes:

I would like to authenticate

Spam control

What do you get when you multiply 2 by 0?