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

Last change on this file since 35296 was 35296, checked in by Kon Lovett, 2 years ago

=> -> ->, parameter result type

File size: 13.7 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]) -> symbol</parameter>
39
40Gets or sets the {{LANGUAGE}} symbol.
41
42==== current-country
43
44<parameter>(current-country [COUNTRY]) -> symbol</parameter>
45
46Gets or sets the {{COUNTRY}} symbol.
47
48==== current-locale-details
49
50<parameter>(current-locale-details [LOCALE-DETAILS]) -> list</parameter>
51
52Gets or sets the {{LOCALE-DETAILS}} list.
53
54==== current-locale-format-function
55
56<parameter>(current-locale-format-function [FORMAT-PROCEDURE]) -> 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.
70
71''Reset'' as in set anew.
72
73=== Bundle Operations
74
75* A {{BUNDLE-SPECIFIER}} is a list of symbols of the form
76{{(PACKAGE-NAME [LANGUAGE] [COUNTRY] [DETAILS...])}}.
77
78* A {{TEMPLATE-NAME}} is something suitable as a key, such as a {{symbol}} or
79{{string}}, but can be any {{object}} with a readable printname.
80
81* A {{TEMPLATE-VALUE}} maybe any object, but should have a readable printname.
82
83* A {{BUNDLE-ALIST}} is an alist with key {{TEMPLATE-NAME}} & value
84{{TEMPLATE-VALUE}}.
85
86So {{(cons 'template-example 'value-example)}} is legal, whereas {{(list
87'template-example 'value-example)}} is not. The form {{(list 'template-example
88'value-example)}} will have the value {{(list 'value-example)}}, and not
89{{'value-example}}, as expected.
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 alist 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 alist 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}} : {{absolute-pathname}}, {{relative-pathname}}, or {{(unitname pathname)}}
285; {{TEMPLATE-NAMES}} : {{(list-of template-name)}}.
286; {{template-name}} : {{(or TEMPLATE-NAME variable-reference)}}.
287; {{variable-reference}} : {{(or symbol (symbol symbol))}}.
288
289The corresponding load call for a {{LIBRARY}} form is {{load-relative}},
290{{load-relative}}, and {{load-library}}. (See
291[[http://wiki.call-cc.org/man/4/Unit%20eval|Unit eval]].)
292
293'''Notes'''
294
295* {{(symbol symbol)}} in {{variable-reference}} is a {{module}} import
296reference; this is a ''brittle'' feature as it relies upon knowledge of
297implementation details.
298
299* only {{load-relative}} is used for a library {{pathname}}. Be sure to
300provide an {{absolute-pathname}} when a {{current-directory}} relative
301{{pathname}} is needed.
302
303* ''This is an experimental API.''
304
305
306=== Exceptions
307
308* {{undefined-condition}} Signaled for unknown bundle-specification, package,
309template.
310
311* {{unbound-variable-condition}} Signaled for an unbound reference during
312''localized code'' resolution.
313
314* {{(exn type)}} Signaled for argument type errors.
315
316* {{(exn) message = "invalid library load specificiation" arguments = LIBSPEC}}
317Signaled during ''localized code'' resolution for a bad library load name form.
318
319
320=== Thread Local Storage
321
322Just as the [[locale]] extension supports per thread locale information so
323does this extension support per thread bundles. However, localized information
324is probably accessed more frequently than locale information. So the support
325for per thread bundles is delayed until runtime. Setting the environment
326variable {{SRFI29_TLS}} to {{[Yy1]}} before loading the runtime will activate
327the feature.
328
329When active each thread may have a different bundle for a package; i.e. a user
330of [[SRFI 19|srfi-19] can have a different language in each thread.
331
332
333== Usage
334
335<enscript language=scheme>
336(require-extension srfi-29)
337</enscript>
338
339
340== Notes
341
342* Possible race condition exists creating a bundle file or directory should
343another thread be performing the same action.
344
345* The locale symbols must have a lowercase printname! As such they do not truly
346reflect ISO 639-1/2 & ISO 3166-1 standard names. This is a SRFI 29 restriction.
347
348* {{(current-locale-details)}} is ill-defined by the SRFI 29 document. Which
349symbol means what? This implementation understands:
350
351; {{locale-details}} : {{(list SCRIPT CODESET MODIFIER)}}
352; SCRIPT : {{(or symbol #f)}}
353; CODESET : {{(or symbol #f)}}
354; MODIFIER : {{(or symbol #f)}}
355
356* The SRFI 29 document uses the term {{country}} for what the [[locale]]
357extension knows as {{region}}.
358
359
360== Requirements
361
362[[miscmacros|miscmacros]]
363[[moremacros|moremacros]]
364[[lookup-table|lookup-table]]
365[[posix-utils|posix-utils]]
366[[locale|locale]]
367[[check-errors|check-errors]]
368[[condition-utils|condition-utils]]
369
370[[test|test]]
371
372[[setup-helper|setup-helper]]
373
374
375== Bugs and Limitations
376
377* Currently there is no support for source-form code. Such is considered an
378even worse security-hole than loading compiled code. However, a possibility is
379use of the [[sandbox]].
380
381* {{store-bundle!}} does not ensure filemode of 'a+rx' for the created directory tree.
382
383
384== Author
385
386[[/users/kon-lovett|Kon Lovett]]
387
388
389== Version history
390
391; 2.5.0 : Added dependency on {{moremacros}}.
392; 2.4.0 : Changed {{current-locale-format-function}} to {{parameter}}. Documented {{system-bundle-directory}}.
393; 2.3.3 :
394; 2.3.2 : Ensures filemode of 'a+rx' for bundles directory.
395; 2.3.1 :
396; 2.2.0 : Added runtime support for package per thread. Removed deprecated identifiers.
397; 2.1.3 : Added {{unbound-variable-condition?}}. Deprecated {{!localized-template}} & {{make-!localized-template}} in favor of {{required-localized-template}} & {{make-required-localized-template}}.
398; 2.1.2 :
399; 2.1.1 :
400; 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.
401; 2.0.1 : Fixs for {{bundle-specifier?}} and {{load-best-available-bundle!}}
402; 2.0.0 : Intitial Chicken 4 release. Added introspection routines. Removed {{PORT}} parameter for {{localized-format}}.
403
404
405== License
406
407Copyright (C) 2010-2018 Kon Lovett.  All rights reserved.
408
409Permission is hereby granted, free of charge, to any person obtaining a copy of
410this software and associated documentation files (the Software), to deal in the
411Software without restriction, including without limitation the rights to use,
412copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the
413Software, and to permit persons to whom the Software is furnished to do so,
414subject to the following conditions:
415
416The above copyright notice and this permission notice shall be included in all
417copies or substantial portions of the Software.
418
419THE SOFTWARE IS PROVIDED ASIS, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
420IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
421FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
422AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
423LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
424OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
425SOFTWARE.
Note: See TracBrowser for help on using the repository browser.