Because of a bug report, I have figured out the functionality of the
Maxima function eval_when. I have written a documentation in German.
Perhaps, someone can help to translate this documentation in the English
language.
At this time, there is a lot of additionally information in the German
manual, which could be translated in English. I would appreciate any
help to translate more documentation. If someone is interested to help;
the German manual is available at
http://crategus.users.sourceforge.net/maxima.html
This is the documentation for the function eval_when in German:
-- Funktion: eval_when (<keyword>, <expr_1>, ..., <expr_n>)
-- Funktion: eval_when ([<keyword_1>, <keyword_2>, ...], <expr_1>,
..., <expr_n>)
Ein Ausdruck mit der Funktion `eval_when' wird an oberster Stelle
in einer Datei definiert und erlaubt die bedingte Auswertung von
Ausdr?cken beim Laden, ?bersetzen oder Kompilieren einer Datei.
Das Argument <keyword> ist eines der Schl?sselworte `batch',
`translate', `compile' oder `loadfile'. Das erste Argument kann
ein einzelnes Schl?sselwort oder ein Liste mit mehreren
Schl?sselworten sein. Trifft die mit dem Schl?sselwort angegebene
Bedingung zu, wird eine oder mehrere der folgenden Aktionen
ausgef?hrt:
`batch'
Wird die Datei mit einer der Funktionen `load', `batch',
`batchload' oder `demo' geladen und ist `batch' in der
Liste der Schl?sselworte enthalten, dann werden die Ausdr?cke
<expr1>, ..., <expr_n> genau einmal beim Laden der Datei
ausgewertet. Die R?ckgabe der Funktion `eval_when' ist ein
Ausdruck `evaluated_when(<result)>', wobei <result> das
Ergebnis der Auswertung ist. Ist das Schl?sselwort `batch'
nicht vorhanden, ist die R?ckgabe das Symbol
`not_evaluated_when'.
`translate'
Wird die Datei mit dem Kommando `translate_file' oder
`compile_file' geladen und ist `translate' unter den
Schl?sselworten, dann werden die Ausdr?cke <expr_1>, ...,
<expr_n> sofort ausgewertet. Seiteneffekte wie Zuweisungen
von Werten an Optionsvariablen oder Deklarationen sind f?r
die folgende ?bersetzung der Datei nach Lisp wirksam. Die
Ausdr?cke sind jedoch nicht Teil des ?bersetzten Programms.
`loadfile'
Wird die Datei mit dem Kommando `translate_file' oder dem
Kommando `compile_file' geladen und ist `loadfile' unter den
Schl?sselworten, dann werden die Ausdr?cke <expr_1>, ...,
<expr_n> nach Lisp ?bersetzt und als Block der Form `(PROGN
EXPR_1 ... EXPR_N)' in das Lisp Programm eingesetzt. Hier
sind die Anweisungen <EXPR_I> die nach Lisp ?bersetzten
Maxima-Ausdr?cke <expr_i>.
`compile'
Wird die Datei mit dem Kommando `translate_file' oder
`compile_file' geladen und ist `compile' unter den
Schl?sselworten, dann werden die Ausdr?cke <expr_1>, ...,
<expr_n> nach Lisp ?bersetzt und als eine Lisp-Anweisung in
das Lisp-Programm eingesetzt, die die Form `(EVAL-WHEN
(:COMPILE-TOPLEVEL) (EXPR_1 ... EXPR_N))' hat. Das
Schl?sselwort `compile' kann nicht mit dem Schl?sselwort
`loadfile' in einem `eval_when'-Ausdruck kombiniert werden.
In diesem Fall wird das Schl?sselwort `compile' ignoriert.
Beispiele:
F?r die folgende Beispiele ist eine Datei mit den Namen
`eval_when.mac' definiert, die verschiedene `eval_when'-Anweisungen
enth?lt.
(%i1) file: file_search("eval_when.mac");
(%o1) /home/dieter/.maxima/eval_when.mac
(%i2) printfile(file);
eval_when(batch, print("called in mode BATCH"));
eval_when(loadfile, print("called in mode LOADFILE"));
eval_when(compile, print("called in mode COMPILE"));
eval_when(translate, print("called in mode TRANSLATE"));
(%o2) /home/dieter/.maxima/eval_when.mac
Die Datei wird mit dem Kommando `load' geladen. Die Anweisung mit
dem Schl?sselwort `batch' wird beim Laden einmal ausgef?hrt.
(%i1) file: file_search("eval_when.mac");
(%o1) /home/dieter/.maxima/eval_when.mac
(%i2) load(file);
called in mode BATCH
(%o2) /home/dieter/.maxima/eval_when.mac
In diesem Fall wird die Datei mit dem Befehl `batch' geladen. Die
Anweisung mit dem Schl?sselwort `batch' wird einmal ausgef?hrt.
Die anderen `eval_when'-Anweisungen werten jeweils zum Ergebnis
`not_evaluated_when' aus.
(%i3) batch(file);
read and interpret file: /home/dieter/.maxima/eval_when.mac
(%i4) eval_when(batch, print(called in mode BATCH))
called in mode BATCH
(%o4) evaluated_when(called in mode BATCH)
(%i5) eval_when(loadfile, print(called in mode LOADFILE))
(%o5) not_evaluated_when
(%i6) eval_when(compile, print(called in mode COMPILE))
(%o6) not_evaluated_when
(%i7) eval_when(translate, print(called in mode TRANSLATE))
(%o7) not_evaluated_when
(%o7) /home/dieter/.maxima/eval_when.mac
Jetzt wird die Datei mit dem Kommando `translate_file' geladen und
nach Lisp ?bersetzt. Der Ausdruck mit dem Schl?sselwort
`translate' wird sofort ausgewertet. Das ?bersetzte Programm wird
in die Ausgabedatei `eval_when.LISP' geschrieben. Die
`eval_when'-Anweisung zum Schl?sselwort wird nicht ausgewertet.
(%i1) file: file_search("eval_when.mac");
(%o1) /home/dieter/.maxima/eval_when.mac
(%i2) translate_file(file);
translator: begin
translating /home/dieter/.maxima/eval_when.mac.
called in mode TRANSLATE
(%o2) [/home/dieter/.maxima/eval_when.mac,
/home/dieter/.maxima/eval_when.LISP,
/home/dieter/.maxima/eval_when.UNLISP]
Dies ist der Inhalt der Ausgabedatei `eval_when.LISP'. Die
Ausgabedatei enth?lt eine `PROGN'-Anweisung mit dem Ausdruck
`($print '"called in mode LOADFILE")' f?r den `eval_when'-Ausdruck
zum Schl?sselwort `loadfile' sowie eine `EVAL-WHEN'-Anweisung mit
dem Ausdruck `($print '"called in mode COMPILE")' f?r den
`eval_when'-Ausdruck mit dem Schl?sselwort `compile'.
;;; -*- Mode: Lisp; package:maxima; syntax:common-lisp ;Base: 10
-*- ;;;
;;; Translated on: 2011-10-02 13:35:37+02:00
;;; Maxima version: 5.25post
;;; Lisp implementation: SBCL
;;; Lisp version: 1.0.45
(in-package :maxima)
[...]
nil
(progn ($print '"called in mode LOADFILE"))
(eval-when (:compile-toplevel) ($print '"called in mode COMPILE"))
nil