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

Last change on this file since 15723 was 15723, checked in by Kon Lovett, 11 years ago

Rel 2.0.0

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