guile18/doc/sources/old-intro.texi

   1 @node Introduction
   2 @chapter Introduction
   3
   4 Guile is an interpreter for Scheme, a clean, economical programming
   5 language in the Lisp family.  You can invoke Guile from the shell to
   6 evaluate Scheme expressions interactively, or use it as an interpreter
   7 for script files.  However, Guile is also packaged as a library, to be
   8 embedded as an extension language into other applications.  The
   9 application can supplement the base language with special-purpose
  10 functions and datatypes, allowing the user to customize and extend it by
  11 writing Scheme code.
  12
  13 In its simplest form, Guile is an ordinary interpreter.  The
  14 @code{guile} program can read and evaluate Scheme expressions entered
  15 from the terminal.  Here is a sample interaction between Guile and a
  16 user; the user's input appears after the @code{$} and @code{guile>}
  17 prompts:
  18
  19 @example
  20 $ guile
  21 guile> (+ 1 2 3)                ; add some numbers
  22 6
  23 guile> (define (factorial n)    ; define a function
  24          (if (zero? n) 1 (* n (factorial (- n 1)))))
  25 guile> (factorial 20)
  26 2432902008176640000
  27 guile> (getpwnam "jimb")        ; find my entry in /etc/passwd
  28 #("jimb" ".0krIpK2VqNbU" 4008 10 "Jim Blandy" "/u/jimb"
  29   "/usr/local/bin/bash")
  30 guile> @kbd{C-d}
  31 $
  32 @end example
  33
  34 Guile can also interpret script files.  For example, here is a Guile script
  35 containing a script which displays the
  36
  37
  38 application can
  39 supplement the base language with its own functions, datatypes and
  40 syntax, allowing the user to extend and
  41
  42
  43  Guile interpret
  44
  45 .  An
  46 application the Guile interpreter to allow
  47
  48
  49 , allowing
  50 applications to incorporate the Scheme interpreter for customization
  51
  52 [[interactive]]
  53 [[script interpreter]]
  54 [[embedded]]
  55
  56 [[other languages]]
  57 The concept of an extension language library does not originate with
  58 Guile.  However, Guile is the first to offer users a choice of languages
  59 to program in.
  60
  61
  62 Guile currently supports Scheme and Ctax , and we expect to support Emacs Lisp in the near future.
  63
  64
  65 Scheme is powerful enough that other languages can be
  66 conveniently translated into it,
  67
  68 However, unlike other extension packages, Guile gives users a choice of
  69 languages to program in.  Guile can
  70
  71
  72 In this sense, Guile resembles the Tcl and Python packages, providing
  73 both an ordinary interpreter and an extension language library.
  74 However, unlike those packages, Guile supports more than one programming
  75 language.
  76
  77 ; users can
  78 write Scheme code to control and customize applications which
  79 incorporate Guile
  80
  81 , adding their own functions,
  82 datatypes, and syntax, to allow the user to programm
  83
  84
  85 link it into your own programs to make them
  86
  87
  88
  89 Guile is a library containing an interpreter for Scheme, a complete but
  90 economical programming language, which the developer can customize to
  91 suit the application at hand by adding new functions, data types, and
  92 control structures.  These may be implemented in C, and then
  93 ``exported'' for use by the interpreted code.  Because Guile already
  94 provides a full-featured interpreter, the developer need not neglect the
  95 language's design in order to concentrate on code relevant to the task.
  96 In this way, Guile provides a framework for the construction of
  97 domain-specific languages.
  98
  99 Guile provides first-class functions, a rich set of data types,
 100 exception handling, a module system, and a powerful macro facility.
 101 Guile also supports dynamic linking and direct access to Unix system
 102 calls.  Releases in the near future will support a source-level
 103 debugger and bindings for the Tk user interface toolkit.
 104
 105
 106
 107 Guile is a framework for writing applications controlled by specialized
 108 languages.  In its simplest form, Guile is an interpreter for Scheme, a
 109 clean, economical programming language in the Lisp family.  However,
 110 Guile is packaged as a library, allowing applications to link against it
 111 and use Scheme as their extension language.  The application can add
 112 primitive functions to the language, implement new data types, and even
 113 adjust the language's syntax.
 114
 115
 116
 117 [the introduction is probably not what Jim has in mind; I just took the
 118 one I had in earlier, since the file had the same name intro.texi]
 119
 120 Guile is an implementation of the Scheme programming language, but, like
 121 other modern implementations of Scheme, it adds many features that the
 122 community of Scheme programmers considers necessary for an ``industrial
 123 strength'' language.
 124
 125 Examples of extensions to Scheme are the module system
 126 (@pxref{Modules}), the Unix system programming tools (@pxref{POSIX
 127 system calls and networking} and @pxref{The Scheme shell (scsh)}), an
 128 interface to @emph{libtool} to make it easier to add C libraries as
 129 primitives (@pxref{Linking Guile with your code}), and (FIXME add more).
 130
 131 On top of these extensions, which many other Scheme implementations
 132 provide, Guile also offers the possibility of writing routines in other
 133 languages and running them simultaneously with Scheme.  The desire to
 134 implement other languages (in particular Emacs Lisp) on top of Scheme is
 135 responsible for Guile's only deviation from the R4RS @footnote{R4RS is
 136 the Revised^4 Report on the Algorithmic Language Scheme, the closest
 137 thing to a standard Scheme specification today} Scheme standard
 138 (@cite{r4rs}): Guile is case sensitive, whereas ``standard'' Scheme is
 139 not.
 140
 141 But even more fundamentally, Guile is meant to be an @emph{embeddable}
 142 Scheme interpreter.  This means that a lot of work has gone into
 143 packaging the interpreter as a C library (@pxref{A Portable C to Scheme Interface} and @pxref{Scheme data representation}).
 144
 145 This reference manual is mainly driven by the need to document all the
 146 features that go beyond standard Scheme.
 147
 148 @menu
 149 * Getting started::
 150 * Guile feature list::
 151 * What you need to use Guile::
 152 * Roadmap to the Manual::
 153 * Motivation for Guile::
 154 * History of Guile::
 155 @end menu
 156
 157 @node Getting started
 158 @section Getting started
 159
 160 We assume that you know how to program in Scheme, although we do not
 161 assume advanced knowledge.  If you don't know Scheme, there are many
 162 good books on Scheme at all levels, and the Guile Tutorial might give
 163 you a good enough feel for the language.  We also assume that you know
 164 how to program in C, since there will be many examples of how to program
 165 in C using Guile as a library.
 166
 167 Many diverse topics from the world of Unix hacking will be covered here,
 168 such as shared libraries, socket programming, garbage collection, and so
 169 forth.  If at any time you feel you don't have enough background on a
 170 given topic, just go up a level or two in the manual, and you will find
 171 that the chapter begins with a few paragraphs that introduce the topic.
 172 If you are still lost, read through the Guile tutorial and then come
 173 back to this reference manual.
 174
 175 To run the core Guile interpreter and extension library you need no more
 176 than a basically configured GNU/Unix system and the Guile sources.  You
 177 should download and install the Guile sources (@pxref{Obtaining and
 178 Installing Guile}).
 179
 180
 181 @node Guile feature list
 182 @section Guile feature list
 183
 184 In a reductionist view, Guile could be regarded as:
 185 @itemize @bullet
 186 @item
 187 An R4RS-compliant Scheme interpreter.
 188
 189 @item
 190 Some Scheme features that go beyond the R4RS standard, notably a module
 191 system, exception handling primitives and an interface to Aubrey
 192 Jaffer's SLIB.
 193
 194 @item
 195 A symbolic debugger for Scheme, and gdb extensions to facilitate
 196 debugging libguile programs.
 197
 198 @item
 199 An embeddable version of the same interpreter, called @emph{libguile}.
 200
 201 @item
 202 A portable high level API on top of libguile (the @code{gh_} interface).
 203
 204 @item
 205 A collection of bundled C libraries with a Guile API.  As we write, this
 206 list includes:
 207
 208 @table @strong
 209 @item Rx
 210 a regular expression library.
 211
 212 @item Unix
 213 a low-level interface to the POSIX system calls, socket library
 214 and other Unix system services.
 215
 216 @item Tk
 217 an interface to John Ousterhout's Tk toolkit.
 218
 219 @end table
 220
 221 @item
 222 A set of tools for implementing other languages @emph{on top of Scheme},
 223 and an example implementation of a language called @emph{Ctax}.
 224
 225
 226 @end itemize
 227
 228
 229 @node What you need to use Guile
 230 @section What you need to use Guile
 231
 232
 233 @node Roadmap to the Manual
 234 @section Roadmap to the Manual
 235
 236 @node Motivation for Guile
 237 @section Motivation for Guile
 238
 239 @node History of Guile
 240 @section History of Guile
 241
 242 @page
 243 @node Using Guile
 244 @chapter Using Guile
 245
 246 [I think that this might go in the appendix in Jim's view of the manual]
 247
 248 @page
 249 @node Invoking Guile
 250 @appendix Invoking Guile
 251         --- mentions read-eval-print loops
 252         --- both the SCSH and GAWK manuals relegate invocation details
 253             to an appendix.  We can give examples in the introduction.
 254
 255 @table @samp
 256 @item -h
 257 @itemx --help
 258 Display a helpful message.
 259 @item -v
 260 @item --version
 261 Display the current version.
 262 @item --emacs
 263 To be used for emacs editing support.
 264 @item -s @var{file}
 265 Process @var{file} as a script then quit.  This is a terminating option:
 266 any further command line arguments can be accessed by the script using
 267 the @code{(program-arguments)} procedure.
 268
 269 An executable script can start with the following:
 270
 271 @smallexample
 272 #!/usr/bin/guile -s
 273 !#
 274 @end smallexample
 275
 276 Note the @code{!#} token on the second line.  It is very important
 277 to include this token when writing Guile scripts.  Guile and SCSH,
 278 the Scheme shell, share the convention that @code{#!}  and
 279 @code{!#} may be used to mark block comments (@pxref{Block
 280 comments and interpreter triggers}).  If the closing @code{!#}
 281 token is not included, then Guile will consider the block comment
 282 to be unclosed, and the script will probably not compile
 283 correctly.
 284
 285 It is also important to include the @samp{-s} option at the
 286 beginning of the Guile script, so that Guile knows not to behave
 287 in an interactive fashion.
 288
 289 @end table
 290