diff options
Diffstat (limited to 'doc/ref')
-rw-r--r-- | doc/ref/Makefile.am | 2 | ||||
-rw-r--r-- | doc/ref/api-languages.texi | 125 | ||||
-rw-r--r-- | doc/ref/api-translation.texi | 54 | ||||
-rw-r--r-- | doc/ref/guile.texi | 4 |
4 files changed, 128 insertions, 57 deletions
diff --git a/doc/ref/Makefile.am b/doc/ref/Makefile.am index 1277216bb..df1b4e10e 100644 --- a/doc/ref/Makefile.am +++ b/doc/ref/Makefile.am @@ -42,12 +42,12 @@ guile_TEXINFOS = preface.texi \ api-io.texi \ api-foreign.texi \ api-lalr.texi \ + api-languages.texi \ api-evaluation.texi \ api-memory.texi \ api-modules.texi \ api-scheduling.texi \ api-options.texi \ - api-translation.texi \ api-i18n.texi \ api-debug.texi \ scheme-reading.texi \ diff --git a/doc/ref/api-languages.texi b/doc/ref/api-languages.texi new file mode 100644 index 000000000..7c5c7d7a2 --- /dev/null +++ b/doc/ref/api-languages.texi @@ -0,0 +1,125 @@ +@c -*-texinfo-*- +@c This is part of the GNU Guile Reference Manual. +@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2010 +@c Free Software Foundation, Inc. +@c See the file guile.texi for copying conditions. + +@page +@node Other Languages +@section Support for Other Languages + +In addition to Scheme, a user may write a Guile program in an increasing +number of other languages. Currently supported languages include Emacs +Lisp and ECMAScript. + +Guile is still fundamentally a Scheme, but it tries to support a wide +variety of language building-blocks, so that a user can implement other +languages on top of Guile. This section describes the languages that +have been implemented. + +(For details on how to implement a language, @xref{Compiling to the +Virtual Machine}.) + +@menu +* Using Other Languages:: How to use other languages. +* Emacs Lisp:: The dialect of Lisp used in Emacs. +* ECMAScript:: As seen on television. +@end menu + + +@node Using Other Languages +@subsection Using Other Languages + +There are currently only two ways to access other languages from within +Guile: at the REPL, and via @code{compile} or @code{compile-file}. + +The REPL is Guile's command prompt (@pxref{Using Guile Interactively}). +The REPL has a concept of the ``current language'', which defaults to +Scheme. The user may change that language, via the meta-command +@code{,language}. + +For example, the following meta-command enables Emacs Lisp input: + +@example +scheme@@(guile-user)> ,language elisp +Happy hacking with Emacs Lisp! To switch back, type `,L scheme'. +elisp@@(guile-user)> (eq 1 2) +$1 = #nil +@end example + +Each language has its short name: for example, @code{elisp}, for Elisp. +The same short name may be used to compile source code programmatically, +via @code{compile}: + +@example +elisp@@(guile-user)> ,L scheme +Happy hacking with Guile Scheme! To switch back, type `,L elisp'. +scheme@@(guile-user)> (compile '(eq 1 2) #:from 'elisp) +$2 = #nil +@end example + +Granted, as the input to @code{compile} is a datum, this works best for +Lispy languages, which have a straightforward datum representation. +Other languages that need more parsing are better dealt with as strings. + +The easiest way to deal with syntax-heavy language is with files, via +@code{compile-file} and friends. However it is possible to invoke a +language's reader on a port, and then compile the resulting expression +(which is a datum at that point). For more information, +@xref{Compilation}. + +For more details on introspecting aspects of different languages, +@xref{Compiler Tower}. + +@node Emacs Lisp +@subsection Emacs Lisp + +Emacs Lisp (Elisp) is a dynamically-scoped Lisp dialect used in the +Emacs editor. @xref{top,,Overview,elisp,Emacs Lisp}, for more +information on Emacs Lisp. + +We hope that eventually Guile's implementation of Elisp will be good +enough to replace Emacs' own implementation of Elisp. For that reason, +we have thought long and hard about how to support the various features +of Elisp in a performant and compatible manner. + +Readers familiar with Emacs Lisp might be curious about how exactly +these various Elisp features are supported in Guile. The rest of this +section focuses on addressing these concerns of the Elisp elect. + +@menu +* Nil:: A third boolean. +* Dynamic Binding:: Threadsafe bindings with fluids. +* Other Elisp Features:: Miscellany. +@end menu + + +@node Nil +@subsubsection Nil + +@node Dynamic Binding +@subsubsection Dynamic Binding + +@node Other Elisp Features +@subsubsection Other Elisp Features + + +@node ECMAScript +@subsection ECMAScript + +ECMAScript was not the first non-Schemey language implemented by Guile, +but it was the first implemented for Guile's bytecode compiler. The goal +was to support ECMAScript version 3.1, a relatively small language, but +the implementor was completely irresponsible and got distracted by other +things before finishing the standard library, and even some bits of the +syntax. So, ECMAScript does deserve a mention in the manual, but it +doesn't deserve an endorsement until its implementation is completed, +perhaps by some more responsible hacker. + +In the meantime, the charitable user might investigate such invocations +as @code{,L ecmascript} and @code{cat test-suite/tests/ecmascript.test}. + + +@c Local Variables: +@c TeX-master: "guile.texi" +@c End: diff --git a/doc/ref/api-translation.texi b/doc/ref/api-translation.texi deleted file mode 100644 index 8782a6fbd..000000000 --- a/doc/ref/api-translation.texi +++ /dev/null @@ -1,54 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the GNU Guile Reference Manual. -@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004 -@c Free Software Foundation, Inc. -@c See the file guile.texi for copying conditions. - -@page -@node Translation -@section Support for Translating Other Languages - -[Describe translation framework.] - -@menu -* Emacs Lisp Support:: Helper primitives for Emacs Lisp. -@end menu - - -@node Emacs Lisp Support -@subsection Emacs Lisp Support - -@deffn {Scheme Procedure} nil-car x -@deffnx {C Function} scm_nil_car (x) -Return the car of @var{x}, but convert it to LISP nil if it -is Scheme's end-of-list. -@end deffn - -@deffn {Scheme Procedure} nil-cdr x -@deffnx {C Function} scm_nil_cdr (x) -Return the cdr of @var{x}, but convert it to LISP nil if it -is Scheme's end-of-list. -@end deffn - -@deffn {Scheme Procedure} nil-cons x y -@deffnx {C Function} scm_nil_cons (x, y) -Create a new cons cell with @var{x} as the car and @var{y} as -the cdr, but convert @var{y} to Scheme's end-of-list if it is -a Lisp nil. -@end deffn - -@deffn {Scheme Procedure} nil-eq x y -Compare @var{x} and @var{y} and return Lisp's t if they are -@code{eq?}, return Lisp's nil otherwise. -@end deffn - -@deffn {Scheme Procedure} null x -@deffnx {C Function} scm_null (x) -Return Lisp's @code{t} if @var{x} is nil in the LISP sense, -return Lisp's nil otherwise. -@end deffn - - -@c Local Variables: -@c TeX-master: "guile.texi" -@c End: diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi index 91d391ed2..66584fc1b 100644 --- a/doc/ref/guile.texi +++ b/doc/ref/guile.texi @@ -309,7 +309,7 @@ available through both Scheme and C interfaces. * Foreign Function Interface:: Interacting with C procedures and data. * Scheduling:: Threads, mutexes, asyncs and dynamic roots. * Options and Config:: Configuration, features and runtime options. -* Translation:: Support for translating other languages. +* Other Languages:: Emacs Lisp, ECMAScript, and more. * Internationalization:: Support for gettext, etc. * Debugging:: Debugging infrastructure and Scheme interface. @end menu @@ -335,7 +335,7 @@ available through both Scheme and C interfaces. @include api-scheduling.texi @c object orientation support here @include api-options.texi -@include api-translation.texi +@include api-languages.texi @include api-i18n.texi @include api-debug.texi |