source: project/wiki/eggref/4/srfi-29 @ 15714

Last change on this file since 15714 was 15714, checked in by Kon Lovett, 10 years ago

Rel 1.9.1 of lookup-table.

File size: 7.0 KB
Line 
1[[tags: egg]]
2
3== srfi-29
4
5A Chicken implementation of
6[[http://srfi.schemers.org/srfi-29/srfi-29.html|SRFI 29]].
7
8[[toc:]]
9
10
11== Documentation
12
13Bundles are assumed stored in the system bundle directory, {{(repository-path)
14"srfi-29-bundles"}}.
15
16Within a bundle directory the structure is ({{[LANGUAGE [COUNTRY [SCRIPT
17[CODESET [MODIFIER]]]]] PACKAGE-NAME}}.
18
19Any object which can be returned by {{(read)}} and tested for equality with
20{{equal?}} is acceptable as a {{TEMPLATE-NAME}}. So strings are a valid
21{{TEMPLATE-NAME}}. Further, {{(localized-template...)}} will return any object
22which can be returned by {{(read)}}, not just a string.
23
24=== Parameters
25
26==== current-language
27
28<parameter>(current-language [LANGUAGE])</parameter>
29
30Gets or sets the {{LANGUAGE}} symbol.
31
32==== current-country
33
34<parameter>(current-country [COUNTRY])</parameter>
35
36Gets or sets the {{COUNTRY}} symbol.
37
38==== current-locale-details
39
40<parameter>(current-locale-details [LOCALE-DETAILS])</parameter>
41
42Gets or sets the {{LOCALE-DETAILS}} list.
43
44==== current-locale-format-function
45
46<parameter>(current-locale-format-function [FORMAT-PROCEDURE])
47
48Gets or sets the {{FORMAT-PROCEDURE}}. This procedure must have the signature
49{{(port | string | boolean string [object]...)}}.
50
51==== reset-locale-parameter
52
53<procedure>(reset-locale-parameters)</procedure>
54
55When the {{current-locale}} is changed, (see the [[eggs/locale.html|locale
56egg]]), the {{current-*}} parameters need not be set individually. This will
57update those parameters to the values in the new locale. (Reset as in set
58anew.)
59
60=== Procedures
61
62==== most-specific-bundle-specifier
63
64<procedure>(most-specific-bundle-specifier PACKAGE-NAME)</procedure>
65
66Returns the most specific bundle specifier for the current language, country,
67and locale details.
68
69==== declare-bundle!
70
71<procedure>(declare-bundle! BUNDLE-SPECIFIER BUNDLE-ALIST)</procedure>
72
73Creates a bundle.
74
75==== undeclare-bundle!
76
77<procedure>(undeclare-bundle! BUNDLE-SPECIFIER)</procedure>
78
79Removes the bundle specified by {{BUNDLE-SPECIFIER}} from the active bundles.
80
81==== store-bundle!
82
83<procedure>(store-bundle! BUNDLE-SPECIFIER [ALTERNATE-DIRECTORY])</procedure>
84
85Writes the bundle.
86
87Uses the {{ALTERNATE-DIRECTORY}} if specified.
88
89==== load-bundle!
90
91<procedure>(load-bundle! BUNDLE-SPECIFIER [ALTERNATE-DIRECTORY])</procedure>
92
93Reads the bundle.
94
95Uses the {{ALTERNATE-DIRECTORY}} if specified.
96
97==== load-best-available-bundle!
98
99<procedure>(load-best-available-bundle! BUNDLE-SPECIFIER [ALTERNATE-DIRECTORY])</procedure>
100
101Attempts {{(load-bundle! BUNDLE-SPECIFIER [ALTERNATE-DIRECTORY])}}, from most
102to least specific.
103
104==== remove-bundle!
105
106<procedure>(remove-bundle! BUNDLE-SPECIFIER [ALTERNATE-DIRECTORY])</procedure>
107
108Removes the bundle specified by {{BUNDLE-SPECIFIER}} from the active bundles,
109and from the filesystem. The bundle directory is {{ALTERNATE-DIRECTORY}},
110unless missing. Then the system bundle directory is used.
111
112Will not remove the locale directory hierarchy created by
113{{(store-bundle!...)}}.
114
115==== remove-bundle-directory!
116
117<procedure>(remove-bundle-directory! BUNDLE-SPECIFIER [ALTERNATE-DIRECTORY])</procedure>
118
119Removes the bundle directory hierarchy created by {{(store-bundle!...)}}. Will
120only remove empty directories. Returns {{#t}} if operation succeeded, {{#f}}
121when a non-empty directory encountered.
122
123Does not remove the bundle, if any, from the active bundles. A filesystem only
124operation.
125
126This procedure should be used with caution.
127
128==== localized-template
129
130<procedure>(localized-template PACKAGE-NAME TEMPLATE-NAME [NOT-FOUND #f])</procedure>
131
132Returns the object for the {{TEMPLATE-NAME}} in {{PACKAGE-NAME}}, when found,
133otherwise the {{NOT-FOUND}} value.
134
135==== localized-template-set!
136
137<procedure>(localized-template-set! PACKAGE-NAME TEMPLATE-NAME VALUE)</procedure>
138
139Creates or updates the {{VALUE}} for the {{TEMPLATE-NAME}} in {{PACKAGE-NAME}}
140and returns {{#t}}, when the package exists. Otherwise returns {{#f}}.
141
142This can be used to extend the meaning of a package template at runtime. For
143example: caching the actual closure for a named procedure.
144
145==== localized-template/default
146
147<procedure>(localized-template/default PACKAGE-NAME TEMPLATE-NAME [NOT-FOUND TEMPLATE-NAME])</procedure>
148
149Returns {{(localized-template PACKAGE-NAME TEMPLATE-NAME NOT-FOUND)}}.
150
151Somewhat like the Posix 'gettext' routine.
152
153==== localized-format
154
155<procedure>(localized-format PACKAGE-NAME TEMPLATE-NAME PORT ARG0...)</procedure>
156
157Formats the arguments {{ARG0...}} to the {{PORT}} using the
158{{(current-locale-format-function)}} and the format string
159{{(localized-template PACKAGE-NAME TEMPLATE-NAME)}}.
160
161When a localized-template is not found and the {{TEMPLATE-NAME}} is a
162{{string}} then it is used a the format-string.
163
164A representation is always displayed, even when no template is found. Just not
165a localized one.
166
167=== Exceptions
168
169Extension error conditions are signaled with a composite condition of {{(exn
170srfi-29)}}.
171
172The property-condition {{exn}} has properties {{location}}, {{message}}, and,
173optionally, {{arguments}}.
174
175An invalid bundle-specification raises the composite-condition {{(exn srfi-29
176insufficient)}}.
177
178An unknown bundle-specification raises the composite-condition {{(exn srfi-29
179undefined)}}.
180
181
182== Usage
183
184<enscript language=scheme>
185(require-extension srfi-29)
186</enscript>
187
188
189== Examples
190
191
192== Notes
193
194* Possible race condition creating a bundle file or directory.
195
196* The locale symbols must have a lowercase printname! As such they do not truly
197reflect ISO 639-1/2 & ISO 3166-1 standard names. This is a SRFI 29 restriction.
198
199* {{(current-locale-details)}} is ill-defined by SRFI 29. Which symbol means
200what? This implementation defines locale details as a 3 element list {{(SCRIPT
201CODESET MODIFIER)}} where the elements are symbols or {{#f}}.
202
203* The SRFI 29 document uses the term "country" for what the locale extension
204knows as "region".
205
206
207== Requirements
208
209[[lookup-table|lookup-table]]
210[[miscmacros|miscmacros]]
211[[locale|locale]]
212[[check-errors|check-errors]]
213
214
215== Bugs and Limitations
216
217
218== Author
219
220[[kon lovett]]
221
222
223== Version history
224
225; 2.0.0 : Intitial Chicken 4 release
226
227
228== License
229
230Copyright (C) 2009 Kon Lovett.  All rights reserved.
231
232Permission is hereby granted, free of charge, to any person obtaining a
233copy of this software and associated documentation files (the Software),
234to deal in the Software without restriction, including without limitation
235the rights to use, copy, modify, merge, publish, distribute, sublicense,
236and/or sell copies of the Software, and to permit persons to whom the
237Software is furnished to do so, subject to the following conditions:
238
239The above copyright notice and this permission notice shall be included
240in all copies or substantial portions of the Software.
241
242THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
243IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
244FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
245THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
246OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
247ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
248OTHER DEALINGS IN THE SOFTWARE.
Note: See TracBrowser for help on using the repository browser.