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

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

better load-localized-compiled-code doc

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