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

Last change on this file since 34214 was 34214, checked in by kon, 15 months ago

rel 2.4

File size: 13.5 KB
Line 
1[[tags: egg]]
2
3== srfi-29
4
5[[toc:]]
6
7
8== Documentation
9
10A Chicken implementation of
11[[http://srfi.schemers.org/srfi-29/srfi-29.html|SRFI 29]].
12
13The addition of the escape code {{~[n]@*}} to the SRFI 28 {{format}} is
14'''not''' part of this extension.
15
16=== Conditions
17
18==== undefined-condition?
19
20<procedure>(undefined-condition? OBJECT) => boolean</procedure>
21
22Is the {{OBJECT}} an instance of the SRFI 29 {{undefined-condition}}.
23
24A {{composite-property-condition}} of {{(exn srfi-29 undefined)}}.
25
26==== unbound-variable-condition?
27
28<procedure>(unbound-variable-condition? OBJECT) => boolean</procedure>
29
30Is the {{OBJECT}} an instance of the SRFI 29 {{unbound-variable-condition}}.
31
32A {{composite-property-condition}} of {{(exn srfi-29 unbound)}}.
33
34=== Parameters
35
36==== current-language
37
38<parameter>(current-language [LANGUAGE])</parameter>
39
40Gets or sets the {{LANGUAGE}} symbol.
41
42==== current-country
43
44<parameter>(current-country [COUNTRY])</parameter>
45
46Gets or sets the {{COUNTRY}} symbol.
47
48==== current-locale-details
49
50<parameter>(current-locale-details [LOCALE-DETAILS])</parameter>
51
52Gets or sets the {{LOCALE-DETAILS}} list.
53
54==== current-locale-format-function
55
56<parameter>(current-locale-format-function [FORMAT-PROCEDURE])</parameter>
57
58Gets or sets the {{FORMAT-PROCEDURE}}.
59
60This procedure must at least have the signature of a SRFI 28 {{format}}
61procedure. The default is the Chicken {{extras#format}} procedure.
62
63==== reset-locale-parameters
64
65<procedure>(reset-locale-parameters)</procedure>
66
67When the {{current-locale}} is changed, (see the [[locale|locale egg]]),
68the {{current-*}} parameters need not be set individually. This will
69update those parameters to the values in the new locale. (Reset as in set
70anew.)
71
72=== Bundle Operations
73
74* A {{BUNDLE-SPECIFIER}} is a list of symbols of the form
75{{(PACKAGE-NAME [LANGUAGE] [COUNTRY] [DETAILS...])}}.
76
77* A {{BUNDLE-ALIST}} is an association-list over with key {{TEMPLATE-NAME}} &
78value {{TEMPLATE-VALUE}}. The association-list elements must be of the form
79{{(TEMPLATE-NAME . TEMPLATE-VALUE)}}.
80
81That is {{(cons 'template-example 'value-example)}} is legal, whereas {{(list
82'template-example 'value-example)}} is not. The form {{(list 'template-example
83'value-example)}} will have the value {{(list 'value-example)}}, and not
84{{'value-example}}, as expected.
85
86* A {{TEMPLATE-NAME}} is something suitable as a key, such as a {{symbol}} or
87{{string}}, but can be any {{object}} with a readable printname.
88
89* A {{TEMPLATE-VALUE}} maybe any object, but should have a readable printname.
90
91==== declare-bundle!
92
93<procedure>(declare-bundle! BUNDLE-SPECIFIER BUNDLE-ALIST)</procedure>
94
95Creates a bundle.
96
97==== undeclare-bundle!
98
99<procedure>(undeclare-bundle! BUNDLE-SPECIFIER)</procedure>
100
101Removes the bundle specified by {{BUNDLE-SPECIFIER}} from the active bundles.
102
103
104=== Bundle Database Operations
105
106SRFI 29 does not specify how bundles are stored. This extension uses the
107filesystem for the bundle database.
108
109Bundles are stored in the {{system-bundle-directory}}, unless an {{ALTERNATE}}
110directory is specified.
111
112Within a bundle directory the structure is {{(directory [LANGUAGE] [COUNTRY] [SCRIPT]
113[CODESET] [MODIFIER] PACKAGE-NAME)}}.
114
115==== system-bundle-directory
116
117<parameter>(system-bundle-directory [DIRECTORY-PATHNAME])</parameter>
118
119Initially {{DIRECTORY-PATHNAME}} is {{(make-pathname (repository-path)
120"srfi-29-bundles")}}.
121
122==== store-bundle!
123
124<procedure>(store-bundle! BUNDLE-SPECIFIER [ALTERNATE])</procedure>
125
126Stores the bundle using the {{write}} procedure.
127
128==== load-bundle!
129
130<procedure>(load-bundle! BUNDLE-SPECIFIER [ALTERNATE])</procedure>
131
132Loads the bundle using the {{read}} procedure.
133
134==== load-best-available-bundle!
135
136<procedure>(load-best-available-bundle! BUNDLE-SPECIFIER [ALTERNATE])</procedure>
137
138Attempts {{(load-bundle! BUNDLE-SPECIFIER [ALTERNATE])}}, from most
139to least specific.
140
141See {{most-specific-bundle-specifier}}.
142
143==== remove-bundle!
144
145<procedure>(remove-bundle! BUNDLE-SPECIFIER [ALTERNATE])</procedure>
146
147Removes the bundle specified by {{BUNDLE-SPECIFIER}} from the active bundles,
148and from the filesystem.
149
150Will not remove the locale directory hierarchy created by
151{{(store-bundle!...)}}.
152
153==== remove-bundle-directory!
154
155<procedure>(remove-bundle-directory! BUNDLE-SPECIFIER [ALTERNATE])</procedure>
156
157Removes the bundle directory hierarchy created by {{(store-bundle!...)}}. Will
158only remove empty directories. Returns {{#t}} if operation succeeded, {{#f}}
159when a non-empty directory encountered.
160
161Does not remove the bundle, if any, from the active bundles. A filesystem only
162operation.
163
164This procedure should be used with caution.
165
166==== declared-bundle-specifiers
167
168<procedure>(declared-bundle-specifiers) => list</procedure>
169
170Returns a list of all the declared {{BUNDLE-SPECIFIER}}s.
171
172==== declared-bundle-templates
173
174<procedure>(declared-bundle-templates BUNDLE-SPECIFIER) => list</procedure>
175
176Returns an association-list of all the templates for the {{BUNDLE-SPECIFIER}}.
177
178==== most-specific-bundle-specifier
179
180<procedure>(most-specific-bundle-specifier PACKAGE-NAME) => bundle-specifier</procedure>
181
182Returns the most specific bundle specifier for the current locale.
183
184The current locale is composed of the {{(current-language)}},
185{{(current-country)}}, and {{(current-locale-details)}}.
186
187Note that the {{most-specific-bundle-specifier}} may not be a declared bundle.
188
189
190=== Bundle Template Operations
191
192These routines will use the most specific declared bundle for the package
193{{PACKAGE-NAME}} in the current locale.
194
195==== required-localized-template
196
197<procedure>(required-localized-template PACKAGE-NAME TEMPLATE-NAME) => *</procedure>
198
199Returns the object for the {{TEMPLATE-NAME}} in {{PACKAGE-NAME}}. Otherwise a
200{{undefined-condition}} exception is raised.
201
202==== localized-template
203
204<procedure>(localized-template PACKAGE-NAME TEMPLATE-NAME [PACKAGE-NOT-FOUND [TEMPLATE-NOT-FOUND]]) => *</procedure>
205
206Returns the object for the {{TEMPLATE-NAME}} in {{PACKAGE-NAME}}. Otherwise the
207appropriate {{...-NOT-FOUND}} value.
208
209{{PACKAGE-NOT-FOUND}} and {{TEMPLATE-NOT-FOUND}} have default {{#t}},
210
211==== localized-template/default
212
213<procedure>(localized-template/default PACKAGE-NAME TEMPLATE-NAME [PACKAGE-NOT-FOUND [TEMPLATE-NOT-FOUND]]) => *</procedure>
214
215Returns {{(localized-template PACKAGE-NAME TEMPLATE-NAME PACKAGE-NOT-FOUND TEMPLATE-NOT-FOUND)}}.
216
217{{PACKAGE-NOT-FOUND}} and {{TEMPLATE-NOT-FOUND}} have default {{TEMPLATE-NAME}}.
218
219Somewhat like the Posix 'gettext' routine.
220
221==== make-localized-template
222
223<procedure>(make-localized-template PACKAGE-NAME) => (procedure (symbol #!optional * *) *)</procedure>
224
225Returns a {{localized-template}}-like procedure curried upon the
226{{PACKAGE-NAME}}.
227
228==== make-localized-template/default
229
230<procedure>(make-localized-template/default PACKAGE-NAME) => (procedure (symbol #!optional * *) *)</procedure>
231
232Returns a {{localized-template/default}}-like procedure curried upon the
233{{PACKAGE-NAME}}.
234
235==== make-required-localized-template
236
237<procedure>(make-required-localized-template PACKAGE-NAME) => (procedure (symbol) *)</procedure>
238
239Like {{make-localized-template}} but raises an {{undefined-condition}}
240exception should the package or template be missing.
241
242==== localized-format
243
244<procedure>(localized-format PACKAGE-NAME TEMPLATE-NAME ARG0...) => string</procedure>
245
246Returns the formatted string using the {{(current-locale-format-function)}} and
247the format string {{(localized-template PACKAGE-NAME TEMPLATE-NAME)}} on the
248arguments {{ARG0...}}.
249
250When a localized-template is not found and the {{TEMPLATE-NAME}} is a
251{{string}} then it is used a the format-string.
252
253A representation is always displayed, even when no template is found. Just not
254a localized one.
255
256==== localized-template-set!
257
258<procedure>(localized-template-set! PACKAGE-NAME TEMPLATE-NAME VALUE) => boolean</procedure>
259
260Creates or updates the {{VALUE}} for the {{TEMPLATE-NAME}} in {{PACKAGE-NAME}}
261and returns {{#t}}, when the package exists. Otherwise returns {{#f}}.
262
263This can be used to extend the meaning of a package template at runtime. For
264example: caching the actual closure for a named procedure.
265
266==== localized-templates
267
268<procedure>(localized-templates PACKAGE-NAME) => list</procedure>
269
270Returns an association-list of all the templates for the {{PACKAGE-NAME}}.
271
272==== load-localized-compiled-code
273
274<procedure>(load-localized-compiled-code LIBRARY PACKAGE-NAME TEMPLATE-NAMES)</procedure>
275
276Loads a Scheme code library and replaces the toplevel variable references from
277the templates with the actual value. Each item {{package-name+template-name}}
278has a variable reference upon entry. Upon exit this is replaced with the
279variable value after load.
280
281Every item {{package-name+template-name}} referenced '''must''' be defined.
282Otherwise a {{(exn srfi-29 undefined)}} exception if raised.
283
284{{LIBRARY}} is an absolute {{pathname}}, relative {{pathname}}, or {{(unitname
285pathname)}}. The corresponding load call is {{load-relative}},
286{{load-relative}}, and {{load-library}}. (See [[Unit eval]].)
287
288{{TEMPLATE-NAMES}} is a {{list}} of {{template-name}}.
289
290A {{variable-reference}} is a {{symbol}} or {{(symbol symbol)}}. The later is a
291{{module}} import reference; this is a ''brittle'' feature as it relies upon
292knowledge of implementation details.
293
294''Note'' that only {{load-relative}} is used for a library {{pathname}}. Be sure
295to provide an {{absolute-pathname}} when a {{current-directory}} relative
296{{pathname}} is needed.
297
298This is an experimental API.
299
300
301=== Exceptions
302
303* {{undefined-condition}} Signaled for unknown bundle-specification, package,
304template.
305
306* {{unbound-variable-condition}} Signaled for an unbound reference during
307''localized code'' resolution.
308
309* {{(exn type)}} Signaled for argument type errors.
310
311* {{(exn) message = "invalid library load specificiation" arguments = LIBSPEC}}
312Signaled during ''localized code'' resolution for a bad library load name form.
313
314
315=== Thread Local Storage
316
317Just as the [[locale]] extension supports per thread locale information so
318does this extension support per thread bundles. However, localized information
319is probably accessed more frequently than locale information. So the support
320for per thread bundles is delayed until runtime. Setting the environment
321variable {{SRFI29_TLS}} to {{[Yy1]}} before loading the runtime will activate
322the feature.
323
324When active each thread may have a different bundle for a package; i.e. a user
325of [[SRFI 19|srfi-19] can have a different language in each thread.
326
327
328== Usage
329
330<enscript language=scheme>
331(require-extension srfi-29)
332</enscript>
333
334
335== Notes
336
337* Possible race condition exists creating a bundle file or directory should
338another thread be performing the same action.
339
340* The locale symbols must have a lowercase printname! As such they do not truly
341reflect ISO 639-1/2 & ISO 3166-1 standard names. This is a SRFI 29 restriction.
342
343* {{(current-locale-details)}} is ill-defined by the SRFI 29 document. Which
344symbol means what? This implementation defines locale details as a 3 element
345{{list}} {{(SCRIPT CODESET MODIFIER)}} where the elements are {{symbols}} or {{#f}}.
346
347* The SRFI 29 document uses the term {{country}} for what the [[locale]]
348extension knows as {{region}}.
349
350
351== Requirements
352
353[[miscmacros|miscmacros]]
354[[lookup-table|lookup-table]]
355[[posix-utils|posix-utils]]
356[[locale|locale]]
357[[check-errors|check-errors]]
358[[condition-utils|condition-utils]]
359
360
361== Bugs and Limitations
362
363* Currently there is no support for source-form code. Such is considered an
364even worse security-hole than loading compiled code. However, a possibility is
365use of the [[sandbox]].
366
367* {{store-bundle!}} does not ensure filemode of 'a+rx' for the created directory tree.
368
369
370== Author
371
372[[/users/kon-lovett|Kon Lovett]]
373
374
375== Version history
376
377; 2.4.0 : Changed {{current-locale-format-function}} to {{parameter}}. Documented {{system-bundle-directory}}.
378; 2.3.3 :
379; 2.3.2 : Ensures filemode of 'a+rx' for bundles directory.
380; 2.3.1 :
381; 2.2.0 : Added runtime support for package per thread. Removed deprecated identifiers.
382; 2.1.3 : Added {{unbound-variable-condition?}}. Deprecated {{!localized-template}} & {{make-!localized-template}} in favor of {{required-localized-template}} & {{make-required-localized-template}}.
383; 2.1.2 :
384; 2.1.1 :
385; 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.
386; 2.0.1 : Fixs for {{bundle-specifier?}} and {{load-best-available-bundle!}}
387; 2.0.0 : Intitial Chicken 4 release. Added introspection routines. Removed {{PORT}} parameter for {{localized-format}}.
388
389
390== License
391
392Copyright (C) 2010-2017 Kon Lovett.  All rights reserved.
393
394Permission is hereby granted, free of charge, to any person obtaining a copy of
395this software and associated documentation files (the Software), to deal in the
396Software without restriction, including without limitation the rights to use,
397copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
398Software, and to permit persons to whom the Software is furnished to do so,
399subject to the following conditions:
400
401The above copyright notice and this permission notice shall be included in all
402copies or substantial portions of the Software.
403
404THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
405IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
406FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
407AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
408LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
409OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
410SOFTWARE.
Note: See TracBrowser for help on using the repository browser.