Changeset 9773 in project

03/15/08 21:31:51 (12 years ago)

Changes applied for rlpowell ( through svnwiki:

1 edited


  • wiki/caketext

    r9755 r9773  
     1== Overview And Requirements
     3This egg is a Chicken Scheme port of Locale::MakeText; see
    3 [[]]
     6If you have any problems with this egg, or would like to suggest
     7changes/additions to the documentation, please e-mail
     10This is the general documentation, containing examples, background, and so on.
     11The function documentation is generated from the source using mole, and can be
     12found at
     15=== Differences From Locale::MakeText
     17Because of the history behind Common Lisp's format function, which Scheme has
     18inherited, we don't use the same escape sequences.
     20Strings are not turned into code at all, because with the 2-pass setup I'd need
     21to be able to get code back from format-modular, and I can't.  This is a
     22possible target for future optimization, if this module causes performance
     25caketext can write out auto-generated language packs; nah-nah, our language has
     26code/data isomorphism and yooooours doesn't!  :) (More to the point, all
     27Schemes can read/write almost all Scheme objects on the fly; it's a basic part
     28of the language.)
     30=== Requirements
     32Also because of wanting to use a CL-style format, this egg requires
     33format-modular (also, format-modular has some nice modularity this egg takes
     34advantage of).  If you want to compile it yourself and run the test
     35suite, you'll need testbase-driver and all of its requirements.
     37=== Configuration Values
     39; onmiss:                Function to run when a miss occurs on this pack. Arguments passed are the language pack and the text key.  No other packs are checked.  The value returned is used as the translated text.
     41; auto-add:      Boolean; if true and there's a miss on this pack, add the string here.  No other packs are checked.
     43Neither of these have any kind of fall-through options because I
     44couldn't think of a case where that would be useful.  If you have a
     45real-world examples, please let me know.
     47=== Escape Sequences
     49We use format-modular, and the processing of escapes is done in 2
     50passes.  The first pass is a regular format-modular "format" pass,
     51and all those escapes apply and are dealt with.
     53The second pass uses our own function escapes, which are like so:
     55<enscript highlight=scheme>
     56 %(function[%,argument1[%,argument2...]]%)
     59(the [...] are indicating optionality; they are not literal)
     63> "This is a test string: %(test%,~A%,~A%)."
     65Given a function stored with the name 'test in the appropriate
     66language pack, this would run that test function on the next two
     67caketext-translate arguments, i.e. ~A and ~A, which have already
     68been substituted by the first pass, and replace the whole %(...%)
     69string with the results.
     71== Dumping And Loading
     73At any time, the strings in a language pack can be dumped out to a
     74file using dump-language-pack.  Unlike srfi-29, no attempt is made
     75to decide what the file should be named; that's up to you.
     77Also at any time, a file full of an alist of strings can be loaded
     78back into a language pack using load-language-pack.  If you do so,
     79it completely replaces the pack's current strings.
     81Similarily, you can load a file full of an alist of symbols and
     82function definitons to replace the function definitions of a pack.
     83The performance implications of doing so are non-trivial; see the
     84documentation for the load-language-pack function for alternatives.
     86=== Examples
     88A lot of examples can be found by looking at caketext-spec.scm,
     89which is the test suite.  Here's an example of normal usage; please
     90e-mail me ( if it is insufficient for
     93<enscript highlight=scheme>
     95 (define english-pack (new-language-pack))
     97 (set-language-pack-config! english-pack 'auto-add #t)
     99 ...
     101 (output-func
     102   (caketext-translate english-pack #f "You found ~A files." number))
     106This will render the output unchanged; that is, at this point you
     107might as well have used (format ...), except that the string has
     108been stored for future translation, which is yay.
     110<enscript highlight=scheme>
     111 ...
     113 (dump-language-pack "/tmp/english-strings.dump")
     116In that file your translator will find something like this (we
     117pretty-print; lucky you):
     119<enscript highlight=scheme>
     120 (("You found ~A files."
     121   .
     122   "You found ~A files."))
     125Your translator should edit that file, perhaps to look something
     126like this:
     128<enscript highlight=scheme>
     129 (("You found ~A files."
     130   .
     131   "You found ~A files, eh?"))
     134and saves it to a file named, say, /tmp/canadian-strings.dump
     136After this is done, to localize your program to Canadian English
     137you'd put statements like this at the top:
     139<enscript highlight=scheme>
     140 (define canadian-pack (new-language-pack))
     142 (load-language-pack canadian-pack "/tmp/canadian-strings.dump" "")
     144 ...
     146 (output-func
     147   (caketext-translate english-pack #f "You found ~A files." number))
     150Given the number 5, this will output:
     152> You found 5 files, eh?
     154=== License And Copyright
     156This entire egg (this file, the test cases, and the documentation)
     157are all explicitely placed in the public domain by me, Robin Lee
     158Powell, on 10 March 2008.  If you like the software, I'd sure
     159appreciate a note, or a line of thanks in your own code or whatever,
     160but if you do so be sure to thank Andy Lester, the Locale::Maketext
     161guy, as well, as this is basically copycat work.
Note: See TracChangeset for help on using the changeset viewer.