+As mentioned above, when Guile searches the @code{%load-path} for a
+source file, it will also search the @code{%load-compiled-path} for a
+corresponding compiled file. If the compiled file is as new or newer
+than the source file, it will be loaded instead of the source file,
+using @code{load-compiled}.
+
+@defvar %load-compiled-path
+Like @code{%load-path}, but for compiled files. By default, this path
+has two entries: one for compiled files from Guile itself, and one for
+site packages. The @env{GUILE_LOAD_COMPILED_PATH} environment variable
+can be used to prepend or append additional directories
+(@pxref{Environment Variables}).
+@end defvar
+
+When @code{primitive-load-path} searches the @code{%load-compiled-path}
+for a corresponding compiled file for a relative path it does so by
+appending @code{.go} to the relative path. For example, searching for
+@code{ice-9/popen} could find
+@code{/usr/lib/guile/2.0/ccache/ice-9/popen.go}, and use it instead of
+@code{/usr/share/guile/2.0/ice-9/popen.scm}.
+
+If @code{primitive-load-path} does not find a corresponding @code{.go}
+file in the @code{%load-compiled-path}, or the @code{.go} file is out of
+date, it will search for a corresponding auto-compiled file in the
+fallback path, possibly creating one if one does not exist.
+
+@xref{Installing Site Packages}, for more on how to correctly install
+site packages. @xref{Modules and the File System}, for more on the
+relationship between load paths and modules. @xref{Compilation}, for
+more on the fallback path and auto-compilation.
+
+Finally, there are a couple of helper procedures for general path
+manipulation.
+
+@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} parse-path-with-ellipsis path base
+@deffnx {C Function} scm_parse_path_with_ellipsis (path, base)
+Parse @var{path}, which is expected to be a colon-separated string, into
+a list and return the resulting list with @var{base} (a list) spliced in
+place of the @code{...} path component, if present, or else @var{base}
+is added to the end. If @var{path} is @code{#f}, @var{base} 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
+
+
+@node Character Encoding of Source Files
+@subsection Character Encoding of Source Files
+
+@cindex source file encoding
+@cindex primitive-load
+@cindex load
+Scheme source code files are usually encoded in ASCII or UTF-8, but the
+built-in reader can interpret other character encodings as well. When
+Guile loads Scheme source code, it uses the @code{file-encoding}
+procedure (described below) to try to guess the encoding of the file.
+In the absence of any hints, UTF-8 is assumed. One way to provide a
+hint about the encoding of a source file is to place a coding
+declaration in the top 500 characters of the file.
+
+A coding declaration has the form @code{coding: XXXXXX}, where
+@code{XXXXXX} is the name of a character encoding in which the source
+code file has been encoded. The coding declaration must appear in a
+scheme comment. It can either be a semicolon-initiated comment, or the
+first block @code{#!} comment in the file.
+
+The name of the character encoding in the coding declaration is
+typically lower case and containing only letters, numbers, and hyphens,
+as recognized by @code{set-port-encoding!} (@pxref{Ports,
+@code{set-port-encoding!}}). Common examples of character encoding
+names are @code{utf-8} and @code{iso-8859-1},
+@url{http://www.iana.org/assignments/character-sets, as defined by
+IANA}. Thus, the coding declaration is mostly compatible with Emacs.
+
+However, there are some differences in encoding names recognized by
+Emacs and encoding names defined by IANA, the latter being essentially a
+subset of the former. For instance, @code{latin-1} is a valid encoding
+name for Emacs, but it's not according to the IANA standard, which Guile
+follows; instead, you should use @code{iso-8859-1}, which is both
+understood by Emacs and dubbed by IANA (IANA writes it uppercase but
+Emacs wants it lowercase and Guile is case insensitive.)
+
+For source code, only a subset of all possible character encodings can
+be interpreted by the built-in source code reader. Only those
+character encodings in which ASCII text appears unmodified can be
+used. This includes @code{UTF-8} and @code{ISO-8859-1} through
+@code{ISO-8859-15}. The multi-byte character encodings @code{UTF-16}
+and @code{UTF-32} may not be used because they are not compatible with
+ASCII.
+
+@cindex read
+@cindex encoding
+@cindex port encoding
+@findex set-port-encoding!
+There might be a scenario in which one would want to read non-ASCII
+code from a port, such as with the function @code{read}, instead of
+with @code{load}. If the port's character encoding is the same as the
+encoding of the code to be read by the port, not other special
+handling is necessary. The port will automatically do the character
+encoding conversion. The functions @code{setlocale} or by
+@code{set-port-encoding!} are used to set port encodings
+(@pxref{Ports}).
+
+If a port is used to read code of unknown character encoding, it can
+accomplish this in three steps. First, the character encoding of the
+port should be set to ISO-8859-1 using @code{set-port-encoding!}.
+Then, the procedure @code{file-encoding}, described below, is used to
+scan for a coding declaration when reading from the port. As a side
+effect, it rewinds the port after its scan is complete. After that,
+the port's character encoding should be set to the encoding returned
+by @code{file-encoding}, if any, again by using
+@code{set-port-encoding!}. Then the code can be read as normal.
+
+Alternatively, one can use the @code{#:guess-encoding} keyword argument
+of @code{open-file} and related procedures. @xref{File Ports}.
+
+@deffn {Scheme Procedure} file-encoding port
+@deffnx {C Function} scm_file_encoding (port)
+Attempt to scan the first few hundred bytes from the @var{port} for
+hints about its character encoding. Return a string containing the
+encoding name or @code{#f} if the encoding cannot be determined. The
+port is rewound.
+
+Currently, the only supported method is to look for an Emacs-like
+character coding declaration (@pxref{Recognize Coding, how Emacs
+recognizes file encoding,, emacs, The GNU Emacs Reference Manual}). The
+coding declaration is of the form @code{coding: XXXXX} and must appear
+in a Scheme comment. Additional heuristics may be added in the future.
+@end deffn
+
HCoop / bpt / guile.git / blobdiff