document -q, repl options

[bpt/guile.git] / doc / ref / api-options.texi

@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2008, 2009, 2010, 2011
@c   Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.

@node Options and Config
@section Configuration, Features and Runtime Options

Why is my Guile different from your Guile?  There are three kinds of
possible variation:

@itemize @bullet
@item
build differences --- different versions of the Guile source code,
installation directories, configuration flags that control pieces of
functionality being included or left out, etc.

@item
differences in dynamically loaded code --- behaviour and features
provided by modules that can be dynamically loaded into a running Guile

@item
different runtime options --- some of the options that are provided for
controlling Guile's behaviour may be set differently.
@end itemize

Guile provides ``introspective'' variables and procedures to query all
of these possible variations at runtime.  For runtime options, it also
provides procedures to change the settings of options and to obtain
documentation on what the options mean.

@menu
* Build Config::                Build and installation configuration.
* Feature Tracking::            Available features in the Guile process.
* Runtime Options::             Controlling Guile's runtime behaviour.
@end menu


@node Build Config
@subsection Configuration, Build and Installation

The following procedures and variables provide information about how
Guile was configured, built and installed on your system.

@deffn {Scheme Procedure} version
@deffnx {Scheme Procedure} effective-version
@deffnx {Scheme Procedure} major-version
@deffnx {Scheme Procedure} minor-version
@deffnx {Scheme Procedure} micro-version
@deffnx {C Function} scm_version ()
@deffnx {C Function} scm_effective_version ()
@deffnx {C Function} scm_major_version ()
@deffnx {C Function} scm_minor_version ()
@deffnx {C Function} scm_micro_version ()
Return a string describing Guile's full version number, effective
version number, major, minor or micro version number, respectively.
The @code{effective-version} function returns the version name that
should remain unchanged during a stable series.  Currently that means
that it omits the micro version.  The effective version should be used
for items like the versioned share directory name
i.e.@: @file{/usr/share/guile/1.6/}

@lisp
(version) @result{} "1.6.0"
(effective-version) @result{} "1.6"
(major-version) @result{} "1"
(minor-version) @result{} "6"
(micro-version) @result{} "0"
@end lisp
@end deffn

@deffn {Scheme Procedure} %package-data-dir
@deffnx {C Function} scm_sys_package_data_dir ()
Return the name of the directory under which Guile Scheme files in
general are stored.  On Unix-like systems, this is usually
@file{/usr/local/share/guile} or @file{/usr/share/guile}.
@end deffn

@deffn {Scheme Procedure} %library-dir
@deffnx {C Function} scm_sys_library_dir ()
Return the name of the directory where the Guile Scheme files that
belong to the core Guile installation (as opposed to files from a 3rd
party package) are installed.  On Unix-like systems this is usually
@file{/usr/local/share/guile/@var{GUILE_EFFECTIVE_VERSION}} or
@file{/usr/share/guile/@var{GUILE_EFFECTIVE_VERSION}};

@noindent
for example @file{/usr/local/share/guile/1.6}.
@end deffn

@deffn {Scheme Procedure} %site-dir
@deffnx {C Function} scm_sys_site_dir ()
Return the name of the directory where Guile Scheme files specific to
your site should be installed.  On Unix-like systems, this is usually
@file{/usr/local/share/guile/site} or @file{/usr/share/guile/site}.
@end deffn

@cindex @env{GUILE_LOAD_PATH}
@defvar %load-path
List of directories which should be searched for Scheme modules and
libraries.  @code{%load-path} is initialized when Guile starts up to
@code{(list (%site-dir) (%library-dir) (%package-data-dir))},
prepended with the contents of the @env{GUILE_LOAD_PATH} environment variable,
if it is set.
@end defvar

@deffn {Scheme Procedure} parse-path path [tail]
@deffnx {C Function} scm_parse_path (path, tail)
Parse @var{path}, which is expected to be a colon-separated
string, into a list and return the resulting list with
@var{tail} appended. If @var{path} is @code{#f}, @var{tail}
is returned.
@end deffn

@deffn {Scheme Procedure} search-path path filename [extensions [require-exts?]]
@deffnx {C Function} scm_search_path (path, filename, rest)
Search @var{path} for a directory containing a file named
@var{filename}. The file must be readable, and not a directory.
If we find one, return its full filename; otherwise, return
@code{#f}.  If @var{filename} is absolute, return it unchanged.
If given, @var{extensions} is a list of strings; for each
directory in @var{path}, we search for @var{filename}
concatenated with each @var{extension}.  If @var{require-exts?}
is true, require that the returned file name have one of the
given extensions; if @var{require-exts?} is not given, it
defaults to @code{#f}.

For compatibility with Guile 1.8 and earlier, the C function takes only
three arguments
@end deffn

@defvar %guile-build-info
Alist of information collected during the building of a particular
Guile.  Entries can be grouped into one of several categories:
directories, env vars, and versioning info.

Briefly, here are the keys in @code{%guile-build-info}, by group:

@cindex @code{srcdir}
@cindex @code{top_srcdir}
@cindex @code{prefix}
@cindex @code{exec_prefix}
@cindex @code{bindir}
@cindex @code{sbindir}
@cindex @code{libexecdir}
@cindex @code{datadir}
@cindex @code{sysconfdir}
@cindex @code{sharedstatedir}
@cindex @code{localstatedir}
@cindex @code{libdir}
@cindex @code{infodir}
@cindex @code{mandir}
@cindex @code{includedir}
@cindex @code{pkgdatadir}
@cindex @code{pkglibdir}
@cindex @code{pkgincludedir}
@table @asis
@item   directories
srcdir, top_srcdir, prefix, exec_prefix, bindir, sbindir, libexecdir,
datadir, sysconfdir, sharedstatedir, localstatedir, libdir, infodir,
mandir, includedir, pkgdatadir, pkglibdir, pkgincludedir
@cindex @code{LIBS}
@item   env vars
LIBS
@cindex @code{guileversion}
@cindex @code{libguileinterface}
@cindex @code{buildstamp}
@item   versioning info
guileversion, libguileinterface, buildstamp
@end table

Values are all strings.  The value for @code{LIBS} is typically found
also as a part of @code{pkg-config --libs
guile-@value{EFFECTIVE-VERSION}} output.  The value for
@code{guileversion} has form X.Y.Z, and should be the same as returned
by @code{(version)}.  The value for @code{libguileinterface} is libtool
compatible and has form CURRENT:REVISION:AGE (@pxref{Versioning,,
Library interface versions, libtool, GNU Libtool}).  The value for
@code{buildstamp} is the output of the command @samp{date -u +'%Y-%m-%d
%T'} (UTC).

In the source, @code{%guile-build-info} is initialized from
libguile/libpath.h, which is completely generated, so deleting this file
before a build guarantees up-to-date values for that build.
@end defvar

@cindex GNU triplet
@cindex canonical host type

@defvar %host-type
The canonical host type (GNU triplet) of the host Guile was configured
for, e.g., @code{"x86_64-unknown-linux-gnu"} (@pxref{Canonicalizing,,,
autoconf, The GNU Autoconf Manual}).
@end defvar

@node Feature Tracking
@subsection Feature Tracking

Guile has a Scheme level variable @code{*features*} that keeps track to
some extent of the features that are available in a running Guile.
@code{*features*} is a list of symbols, for example @code{threads}, each
of which describes a feature of the running Guile process.

@defvar *features*
A list of symbols describing available features of the Guile process.
@end defvar

You shouldn't modify the @code{*features*} variable directly using
@code{set!}.  Instead, see the procedures that are provided for this
purpose in the following subsection.

@menu
* Feature Manipulation::        Checking for and advertising features.
* Common Feature Symbols::      Commonly available features.
@end menu


@node Feature Manipulation
@subsubsection Feature Manipulation

To check whether a particular feature is available, use the
@code{provided?} procedure:

@deffn {Scheme Procedure} provided? feature
@deffnx {Deprecated Scheme Procedure} feature? feature
Return @code{#t} if the specified @var{feature} is available, otherwise
@code{#f}.
@end deffn

To advertise a feature from your own Scheme code, you can use the
@code{provide} procedure:

@deffn {Scheme Procedure} provide feature
Add @var{feature} to the list of available features in this Guile
process.
@end deffn

For C code, the equivalent function takes its feature name as a
@code{char *} argument for convenience:

@deftypefn {C Function} void scm_add_feature (const char *str)
Add a symbol with name @var{str} to the list of available features in
this Guile process.
@end deftypefn


@node Common Feature Symbols
@subsubsection Common Feature Symbols

In general, a particular feature may be available for one of two
reasons.  Either because the Guile library was configured and compiled
with that feature enabled --- i.e.@: the feature is built into the library
on your system.  Or because some C or Scheme code that was dynamically
loaded by Guile has added that feature to the list.

In the first category, here are the features that the current version of
Guile may define (depending on how it is built), and what they mean.

@table @code
@item array
Indicates support for arrays (@pxref{Arrays}).

@item array-for-each
Indicates availability of @code{array-for-each} and other array mapping
procedures (@pxref{Arrays}).

@item char-ready?
Indicates that the @code{char-ready?} function is available
(@pxref{Reading}).

@item complex
Indicates support for complex numbers.

@item current-time
Indicates availability of time-related functions: @code{times},
@code{get-internal-run-time} and so on (@pxref{Time}).

@item debug-extensions
Indicates that the debugging evaluator is available, together with the
options for controlling it.

@item delay
Indicates support for promises (@pxref{Delayed Evaluation}).

@item EIDs
Indicates that the @code{geteuid} and @code{getegid} really return
effective user and group IDs (@pxref{Processes}).

@item inexact
Indicates support for inexact numbers.

@item i/o-extensions
Indicates availability of the following extended I/O procedures:
@code{ftell}, @code{redirect-port}, @code{dup->fdes}, @code{dup2},
@code{fileno}, @code{isatty?}, @code{fdopen},
@code{primitive-move->fdes} and @code{fdes->ports} (@pxref{Ports and
File Descriptors}).

@item net-db
Indicates availability of network database functions:
@code{scm_gethost}, @code{scm_getnet}, @code{scm_getproto},
@code{scm_getserv}, @code{scm_sethost}, @code{scm_setnet}, @code{scm_setproto},
@code{scm_setserv}, and their `byXXX' variants (@pxref{Network
Databases}).

@item posix
Indicates support for POSIX functions: @code{pipe}, @code{getgroups},
@code{kill}, @code{execl} and so on (@pxref{POSIX}).

@item random
Indicates availability of random number generation functions:
@code{random}, @code{copy-random-state}, @code{random-uniform} and so on
(@pxref{Random}).

@item reckless
Indicates that Guile was built with important checks omitted --- you
should never see this!

@item regex
Indicates support for POSIX regular expressions using
@code{make-regexp}, @code{regexp-exec} and friends (@pxref{Regexp
Functions}).

@item socket
Indicates availability of socket-related functions: @code{socket},
@code{bind}, @code{connect} and so on (@pxref{Network Sockets and
Communication}).

@item sort
Indicates availability of sorting and merging functions
(@pxref{Sorting}).

@item system
Indicates that the @code{system} function is available
(@pxref{Processes}).

@item threads
Indicates support for multithreading (@pxref{Threads}).

@item values
Indicates support for multiple return values using @code{values} and
@code{call-with-values} (@pxref{Multiple Values}).
@end table

Available features in the second category depend, by definition, on what
additional code your Guile process has loaded in.  The following table
lists features that you might encounter for this reason.

@table @code
@item defmacro
Indicates that the @code{defmacro} macro is available (@pxref{Macros}).

@item describe
Indicates that the @code{(oop goops describe)} module has been loaded,
which provides a procedure for describing the contents of GOOPS
instances.

@item readline
Indicates that Guile has loaded in Readline support, for command line
editing (@pxref{Readline Support}).

@item record
Indicates support for record definition using @code{make-record-type}
and friends (@pxref{Records}).
@end table

Although these tables may seem exhaustive, it is probably unwise in
practice to rely on them, as the correspondences between feature symbols
and available procedures/behaviour are not strictly defined.  If you are
writing code that needs to check for the existence of some procedure, it
is probably safer to do so directly using the @code{defined?} procedure
than to test for the corresponding feature using @code{provided?}.


@node Runtime Options
@subsection Runtime Options

There are a number of runtime options available for paramaterizing
built-in procedures, like @code{read}, and built-in behavior, like what
happens on an uncaught error.

For more information on reader options, @xref{Scheme Read}.

For more information on print options, @xref{Scheme Write}.

Finally, for more information on debugger options, @xref{Debug
Options}.

@subsubsection Examples of option use

Here is an example of a session in which some read and debug option
handling procedures are used.  In this example, the user

@enumerate
@item
Notices that the symbols @code{abc} and @code{aBc} are not the same
@item
Examines the @code{read-options}, and sees that @code{case-insensitive}
is set to ``no''.
@item
Enables @code{case-insensitive}
@item
Quits the recursive prompt
@item
Verifies that now @code{aBc} and @code{abc} are the same
@end enumerate

@smalllisp
scheme@@(guile-user)> (define abc "hello")
scheme@@(guile-user)> abc
$1 = "hello"
scheme@@(guile-user)> aBc
<unknown-location>: warning: possibly unbound variable `aBc'
ERROR: In procedure module-lookup:
ERROR: Unbound variable: aBc
Entering a new prompt.  Type `,bt' for a backtrace or `,q' to continue.
scheme@@(guile-user) [1]> (read-options 'help)
copy              no    Copy source code expressions.
positions         yes   Record positions of source code expressions.
case-insensitive  no    Convert symbols to lower case.
keywords          #f    Style of keyword recognition: #f, 'prefix or 'postfix.
r6rs-hex-escapes  no    Use R6RS variable-length character and string hex escapes.
square-brackets   yes   Treat `[' and `]' as parentheses, for R6RS compatibility.
hungry-eol-escapes no   In strings, consume leading whitespace after an
                        escaped end-of-line.
scheme@@(guile-user) [1]> (read-enable 'case-insensitive)
$2 = (square-brackets keywords #f case-insensitive positions)
scheme@@(guile-user) [1]> ,q
scheme@@(guile-user)> aBc
$3 = "hello"
@end smalllisp


@c Local Variables:
@c TeX-master: "guile.texi"
@c End: