\input texinfo    @c -*- mode: texinfo; coding: utf-8; -*-
@c %**start of header
@documentencoding UTF-8
@setfilename gauche-refe.info
@settitle Gauche Users' Reference
@afourpaper
@dircategory The Algorithmic Language Scheme
@direntry
* Gauche: (gauche-refe.info).	        An R7RS Scheme implementation.
@end direntry
@documentlanguage en
@c %**end of header

@c module, class and lexical-syntax index
@defcodeindex md
@defcodeindex cl
@defcodeindex lx

@titlepage
@title Gauche Users' Reference
@subtitle version 0.9.10
@author Shiro Kawai (shiro@@acm.org)

@page
@vskip 0pt plus 1filll
Copyright @copyright{} 2001-2020 Shiro Kawai (shiro@@acm.org)

@end titlepage

@node Top, Introduction, (dir), (dir)

@ifnottex
This is a reference manual of Gauche, an R7RS Scheme implementation.
@ifnothtml
This manual is for version 0.9.10.
@end ifnothtml
@end ifnottex

@menu
* Introduction::                
* Concepts::                    
* Programming in Gauche::       
* Core syntax::                 
* Macros::                      
* Core library::                
* Object system::               
* Library modules - Overview::  
* Library modules - Gauche extensions::  
* Library modules - R7RS standard libraries::  
* Library modules - SRFIs::     
* Library modules - Utilities::  
* C to Scheme mapping::         
* Function and Syntax Index::   
* Module Index::                
* Lexical syntax index::        
* Class Index::                 
* Variable Index::              
@end menu

@contents

@node Introduction, Concepts, Top, Top
@chapter Introduction
@c NODE はじめに

This is a users' guide and reference manual of
the Gauche Scheme.
Here I tried to describe the implementation precisely,
sometimes referring to background design choices.

The target readers are those who already know Scheme and
want to write useful programs in Gauche.
For those who are new to Scheme, it'll be easier to start
from some kind of tutorial.  I'm planning to write one.

This manual only deals with Scheme side of things.  Gauche has
another face, a C interface.   Details of it will be discussed
in a separate document.  See @file{gauche-dev.texi} in the source
distribution for the work-in-progress of such document.
Those who want to use Gauche as an embedded language, or want
to write an extension, need that volume.

For the Scheme side, I tried to make this manual self-contained
for the reader's convenience, i.e. as far as you want to look up
Gauche's features you don't need to refer to other documents.
For example, description of functions defined in the standard
documents are included in this manual, instead of saying
``see the standard document''.   However, this document is not a verbatim
copy of the standard documents; sometimes I omit detailed
discussions for brevity.
I put pointers to the original documents, so please consult them if you
need to refer to the standards.

If you're reading this document off-line, you may find the most
recent version on the web:
@example
@uref{https://practical-scheme.net/gauche/}.
@end example


@menu
* Overview of Gauche::          
* Notations::                   
@end menu

@node Overview of Gauche, Notations, Introduction, Introduction
@section Overview of Gauche
@c NODE  Gaucheの概要

Gauche is a Scheme script engine; it reads Scheme programs,
compiles it on-the-fly and executes it on a virtual machine.
Gauche conforms the language standard
"Revised^7 Report on the Algorithmic Language Scheme"
(@uref{https://bitbucket.org/cowan/r7rs/raw/tip/rnrs/r7rs.pdf}),
and supports various common libraries defined in SRFIs
(@uref{https://srfi.schemers.org}).

The goal of Gauche is to provide a handy tool for
programmers and system administrators to handle
daily works conveniently and efficiently in the production environment.

There are lots of Scheme implementations available, and each
of them has its design emphasis and weaknesses.  Gauche is
designed with emphasis on the following criteria.

@table @b
@item Quick startup
One of the situation Gauche is aiming at is in the production
environment, where you write ten-lines throw-away script that
may invoked very frequently.  This includes CGI scripts as well.
Gauche provides frequently used common features as a part of rich built-in
functions or precompiled Scheme libraries that can be loaded very quickly.

@item Fully utilizing multi-core
Gauche supports native threads on most platforms.
The internals are fully aware of preemptive/concurrent threads
(that is, no ``giant global lock''),
so that you can utilize multiple cores on your machine.

@item Multibyte strings
We can no longer live happily in ASCII-only or 1-byte-per-character world.
The practical language implementations are required to handle
multibyte (wide) characters.
Gauche supports multibyte strings natively, providing robust and
consistent support than @i{ad hoc} library-level implementation.
@xref{Multibyte strings}, for details.

@item Integrated object system
A powerful CLOS-like object system with MetaObject protocol
(mostly compatible with STklos and Guile) is provided.

@item System interface
Although Scheme abstracts lots of details of the machine,
sometimes you have to bypass these high-level layers and
go down to the basement to make things work.
Gauche has built-in support of most of POSIX.1 system calls.
Other modules, such as networking module, usually provide
both high-level abstract interface and low-level interface
close to system calls.

@item Enhanced I/O
No real application can be written without dealing with I/O.
Scheme neatly abstracts I/O as a port, but defines least operations on it.
Gauche uses a port object as a unified abstraction, providing
utility functions to operate on the underlying I/O system.
@xref{Input and output}, for the basic I/O support.

@item Extended language
Gauche is not just an implementation of Scheme; it has some
language-level enhancements.  For example, @emph{lazy sequences}
allows you to have lazy data structures that behaves as if
they're ordinary lists (except that they're realized lazily).
It is different from library-level lazy structure implementation such as
streams (srfi-41), in a sense that you can use any list-processing
procedures on lazy sequences.  It enables programs to use
lazy algorithms more liberally.
@end table


@node Notations,  , Overview of Gauche, Introduction
@section Notations
@c NODE 表記について

@menu
* Entry format::                
* Names and namespaces::        
@end menu

@node Entry format, Names and namespaces, Notations, Notations
@subsection Entry format
@c NODE 項目の形式

In this manual, each entry is represented like this:

@deftp {Category} foo arg1 arg2
[spec]@{module@} Description of foo @dots{}
@end deftp

@var{Category} denotes the category of the entry @b{foo}.
The following categories will appear in this manual:

@multitable @columnfractions .4 .6
@item Function
@tab A Scheme function.
@item Special Form
@tab A special form (in the R7RS term, ``syntax'').
@item Macro
@tab A macro.
@item Module
@tab A module
@item Class
@tab A class.
@item Generic Function
@tab A generic function
@item Method
@tab A method
@item Reader Syntax
@tab A lexical syntax that is interpreted by the reader.
@item Parameter
@tab A parameter, which is a procedure that follows a certain
protocol and used to manipulate the dynamic environment.  
@xref{Parameters}, for the details.
@item Generic application
@tab In Gauche, you can ``apply'' a non-procedure object to arguments
as if it is a procedure (@pxref{Applicable objects}, for the details).
This entry explains the behavior of an object applied to arguments.
@item Subprocess argument
@tab This appears in @code{do-process} and @code{run-process} to explain
their keyword argument (@pxref{Running subprocess})
@item EC Qualifier
@tab This is for SRFI-42 Eager Comprehension qualifiers.
(@pxref{Eager comprehensions}).
@end multitable

For functions, special forms and macros, the entry may be followed
by one or more arguments.  In the argument list, the following notations
may appear:

@table @code
@item arg @dots{}
Indicates zero or more arguments.
@item :optional @var{x} @var{y} @var{z}
@itemx :optional (@var{x} @var{x-default}) (@var{y} @var{y-default}) @var{z}
Indicates it may take up to three optional arguments.
The second form specifies default values to @var{x} and @var{y}.
This is Gauche's enhancement to Scheme; see @ref{Making procedures}
for the definition of complete argument list syntax.
@item :key @var{x} @var{y} @var{z}
@itemx :key (@var{x} @var{x-default}) (@var{y} @var{y-default}) @var{z}
Indicates it may take keyword arguments @var{x}, @var{y} and @var{z.}
The second form shows the default values for @var{x} and @var{y}.
This is also Gauche's enhancement to Scheme; see @ref{Making procedures}
for the definition of complete argument list syntax.
@item :rest @var{args}
Indicates it may take rest arguments.
This is also Gauche's enhancement to Scheme; see @ref{Making procedures}
for the definition of complete argument list syntax.
@end table

Following the entry line, we may indicate the specification the
entry comes from, and/or the module the entry is provided when
it's not built-in.

The specification is shown in brackets.  You'll see the following variations.

@table @asis
@item [R7RS], [R7RS @i{library}]
It is defined in R7RS.  If the entry is about a procedure, a syntax or a
macro, @i{library} is also shown to indicate
the name is exported from the @code{scheme.@i{library}} module
(or the @code{(scheme @i{library})} library, in R7RS terms).
@item [R7RS+], [R7RS+ @i{library}]
It is defined in R7RS, but extended by Gauche, e.g. accepting more
optional arguments or different type of arguments.
The description
contains how it is extended from R7RS.  When you're writing a portable
program, you need to be careful not to use Gauche-specific features.
@item [R6RS], [R6RS+], [R5RS], [R5RS+]
It is defined in R6RS or R5RS.  The plus sign means it has extended by Gauche.
Since R7RS is mostly upward-compatible to R5RS, and has a lot
in common with R6RS, we mark an entry as R5RS or R6RS only if
it is not a part of R7RS.
@item [SRFI-@var{n}], [SRFI-@var{n}+]
The entry works as specified in SRFI-@var{n}.  If it is marked as
"[SRFI-@var{n}+]", the entry has additional functionality.
@item [POSIX]
The API of the entry reflects the API specified in POSIX.
@end table

The module is shown in curly-braces.  If the module isn't shown,
it is built-in for Gauche.  (Note: When you're writing R7RS code,
Gauche built-ins are available through @code{(gauche base)} module,
@pxref{Importing gauche built-ins}).

Some entries may be available from more than one modules through
re-exporting or module inheritance.  We only list the primary module
in that case.

Here's an actual entry for an example:

@example
 -- Function: utf8->string u8vector :optional start end
     [R7RS base] @{gauche.unicode@} Converts a sequence of utf8 octets in
     U8VECTOR to a string.  Optional START and/or END argument(s) will
     limit the range of the input.
@end example

This shows the function @code{utf8->string} is specified by R7RS, in
@code{(scheme base)} library.  Gauche originally provides it from
@code{gauche.unicode} module.  You can import the function from either
one, but in general, it's good to use @code{(import (scheme base))}
when writing R7RS code, and @code{(use gauche.unicode)} when writing
Gauche code.  @xref{R7RS integration}, for the details of differences
in writing in R7RS and Gauche.


@node Names and namespaces,  , Entry format, Notations
@subsection Names and namespaces
@c NODE 名前と名前空間

Since R6RS, you can split toplevel definitions of Scheme programs
into multiple namespaces.  In the standards such namespaces are called
@emph{libraries}.  Gauche predates R6RS and has been calling
them @emph{modules}, and we use the latter throughout this manual.

(Note: RnRS libraries are more abstract concept than Gauche's
modules; RnRS defines libraries in a way that they can be implemented
in various ways, and it just happens that Gauche realises the library
semantics using modules.  When you write a portable R7RS library,
be aware not to rely on Gauche-specific module semantics.  Especially,
RnRS libraries are more static than Gauche modules; you cannot
add definitions to exiting libraries within RnRS, for example.)

Sometimes the same name is used for multiple definitions in
different modules.  If we need to distinguish those names,
we prefix the name with the module name and a hash sign.
For example, @code{gauche#lambda} means @code{lambda}
defined in @code{gauche} module.  This does not mean
you can write @code{gauche#lambda} in the source code,
though: This notation is just for explanation.


@c @node Structure of this document,  , Notations, Introduction
@c @section Structure of this document
@c @c NODE 本書の構成

@c @c EN

@c @c JP
@c @c COMMON

@c Local variables:
@c mode: texinfo
@c coding: utf-8
@c end:
@node Concepts, Programming in Gauche, Introduction, Top
@chapter Concepts
@c NODE 主要な概念

In this chapter I describe a few Gauche's design concepts
that help you to understand how Gauche works.

@menu
* Standard conformance::
* Multibyte strings::
* Multibyte scripts::
* Case-sensitivity::
* Integrated object system::
* Module system::
* Compilation::
@end menu

@node Standard conformance, Multibyte strings, Concepts, Concepts
@section Standard conformance
@c NODE 標準への準拠

Gauche conforms ``Revised^7 Report of Algorithmic Language Scheme,''
(R7RS)
including optional syntax and procedures.  We cover R7RS small language
(@pxref{R7RS small language}), as well as part of R7RS large libraries
(@pxref{R7RS large}).

@itemize @bullet
@item
Gauche has a special kind of symbols, called keywords.
They're symbols with its name beginning with a colon
(e.g. @code{:key}), but behaves as if it is automatically bound to
itself.  @xref{Keywords}, for the details.
Keywords are used extensively when
passing so-called keyword arguments (@pxref{Making procedures}).

@item
Continuations created in a certain situation
(specifically, inside a Scheme code that is called from external
C routine) have limited extent (@xref{Continuations}, for details).

@item
Full numeric tower (integer, rational, real and complex numbers) are supported,
but rationals are only exact, and complex numbers are always inexact.
@end itemize

Note that, since Gauche predates R7RS, most existing Gauche source
code doesn't follow the R7RS program/library structure.  Gauche can
read both traditional Gauche modules/scripts and R7RS programs/libraries
seamlessly.
@xref{Library modules - R7RS standard libraries}, for the details of how R7RS
is integrated into Gauche.


Gauche also supports the following SRFIs (Scheme Request for Implementation).

@table @asis
@c -*- coding:utf-8 -*-

@item SRFI-0, Feature-based conditional expansion construct.
This has become a part of R7RS small.  Gauche supports this as
Built-in.   @xref{Feature conditional}.

@item SRFI-1, List library (R7RS lists)
This has become a part of R7RS large.  @xref{R7RS lists}.
(Some of SRFI-1 procedures are built-in).

@item SRFI-2, AND-LET*: an AND with local bindings, a guarded LET* special form.
Supported natively.  @xref{Binding constructs}.

@item SRFI-4, Homogeneous numeric vector datatypes.
The module @code{gauche.uvector} provides a superset of
@code{srfi-4} procedures, including arithmetic operations and
generic interface on the SRFI-4 vectors.  @xref{Uniform vectors}.

@item SRFI-5, A compatible let form with signatures and rest arguments
Supported by the module @code{srfi-5}.
@xref{A compatible let form with signatures and rest arguments}.

@item SRFI-6, Basic String Ports.
This has become a part of R7RS small.
Gauche supports this as built-in.  @xref{String ports}.

@item SRFI-7, Feature-based program configuration language
Supported as an autoloaded macro.
@xref{Feature-based program configuration language}.

@item SRFI-8, receive: Binding to multiple values.
Syntax @code{receive} is built-in.  @xref{Binding constructs}.

@item SRFI-9, Defining record types.
Supported by the module @code{gauche.record}.  @xref{Record types}.

@item SRFI-10, Sharp-comma external form.
Built-in.  @xref{Read-time constructor}.

@item SRFI-11, Syntax for receiving multiple values.
This has become a part of R7RS small.  Gauche supports it
as built-in.  @xref{Binding constructs}.

@item SRFI-13, String library
Supported by the module @code{srfi-13}.  @xref{String library}.
(Some of SRFI-13 procedures are built-in).

@item SRFI-14, Character-set library
This has become a part of R7RS large.
Character-set object and a few procedures are built-in.
@xref{Character sets}.
Complete set of SRFI-14 is supported by the module @code{scheme.charset}.
@xref{R7RS character sets}.

@item SRFI-16, Syntax for procedures of variable arity (case-lambda)
This has become a part of R7RS small.
Built-in.  @xref{Making procedures}.

@item SRFI-17, Generalized set!
Built-in.  @xref{Assignments}.

@item SRFI-18, Multithreading support
Some SRFI-18 features are built-in, and the rest is in @code{gauche.threads}
module.  @xref{Threads}.

@item SRFI-19, Time Data Types and Procedures.
Time data type is Gauche built-in (@pxref{Time}).
Complete set of SRFI-19 is supported by the module @code{srfi-19}.
@xref{Time data types and procedures}.

@item SRFI-22, Running Scheme scripts on Unix
Supported.  @xref{Writing Scheme scripts}.

@item SRFI-23, Error reporting mechanism.
This has become a part of R7RS small.
Built-in.   @xref{Signaling exceptions}.

@item SRFI-25, Multi-dimensional array primitives.
Supported by the module @code{gauche.array}, which defines
superset of SRFI-25.  @xref{Arrays}.

@item SRFI-26, Notation for specializing parameters without currying.
Built-in.  @xref{Making procedures}.

@item SRFI-27, Sources of Random Bits.
Supported by the module @code{srfi-27}.  @xref{Sources of random bits}.

@item SRFI-28, Basic format strings.
Gauche's built-in @code{format} procedure is a superset of
SRFI-28 @code{format}.  @xref{Output}.

@item SRFI-29, Localization
Supported by the module @code{srfi-29}.
@xref{Localization}.

@item SRFI-30, Nested multi-line comments.
This has become a part of R7RS small.
Supported by the native reader.  @xref{Lexical structure}.

@item SRFI-31, A special form rec for recursive evaluation.  Built-in.
@xref{Binding constructs}.

@item SRFI-34, Exception Handling for Programs
This has become a part of R7RS small.
Built-in.  @xref{Exceptions}.
(However, Gauche implements srfi-18's semantics of @code{raise} literally,
which differs slightly from srfi-34's.  This may be changed in future.)

@item SRFI-35, Conditions
Built-in.  @xref{Conditions}.

@item SRFI-36, I/O Conditions
Partly supported.  @xref{Conditions}.

@item SRFI-37, args-fold: a program argument processor
Supported by the module @code{srfi-37}.
@xref{A program argument processor}.

@item SRFI-38, External Representation for Data With Shared Structure
Built-in.  See @ref{Reading data} and @ref{Output}.

@item SRFI-39, Parameter objects
This has become a part of R7RS small.
Built-in (@pxref{Parameters}).

@item SRFI-40, A Library of Streams
Supported by the module @code{util.stream}.
@xref{Stream library}.

@item SRFI-41, Streams
This has become a part of R7RS large.  @xref{R7RS stream}.
Most of stream procedures are also in @code{util.stream}
(@pxref{Stream library}).

@item SRFI-42, Eager comprehensions
Supported by the module @code{srfi-42}.
@xref{Eager comprehensions}.

@item SRFI-43, Vector library
Supported by the module @code{srfi-43}.
@xref{Vector library (Legacy)}.
Note that this srfi is superseded by R7RS @code{scheme.vector}
library (formerly known as @code{srfi-133}).  @xref{R7RS vectors}.

@item SRFI-45, Primitives for Expressing Iterative Lazy Algorithms
Built-in.
@xref{Lazy evaluation}.

@item SRFI-46, Basic Syntax-rules Extensions
This has become a part of R7RS small.
Built-in.
@xref{Hygienic macros}.

@item SRFI-55, require-extension
Supported as an autoloaded macro.
@xref{Requiring extensions}.

@item SRFI-60, Integers as bits
Most procedures are built-in: @xref{R7RS bitwise operations}.
The complete support is in @code{srfi-60} module: @xref{Integers as bits}.

@item SRFI-61, A more general @code{cond} clause
Supported natively.  @xref{Conditionals}.

@item SRFI-62, S-expression comments
This has become a part of R7RS small.
Supported by the native reader.  @xref{Lexical structure}.

@item SRFI-64, A Scheme API for test suites
Supported by the module @code{srfi-64}. @xref{A Scheme API for test suites}.

@item SRFI-66, Octet vectors
Supported by the module @code{srfi-66} (@pxref{Octet vectors}).
This is mostly a subset of @code{gauche.uvector}, but has one
slight difference.

@item SRFI-69, Basic hash tables
Supported by the module @code{srfi-69} (@pxref{Basic hash tables}).
Note that this srfi is superseded by R7RS @code{scheme.hash-table}
library (formerly known as @code{srfi-125}).
@xref{R7RS hash tables}.

@item SRFI-74, Octet-addressed binary blocks
Supported by the module @code{srfi-74} (@pxref{Octet-addressed binary blocks}).

@item SRFI-78, Lightweight testing
Supported by the module @code{srfi-78}.
It can work with @code{gauche.test}.  @xref{Lightweight testing}.

@item SRFI-87, @code{=>} in case clauses
This has become a part of R7RS small.
Supported natively.  @xref{Conditionals}.

@item SRFI-95, Sorting and merging
Supported natively.  @xref{Sorting and merging}.

@item SRFI-96, SLIB Prerequisites
This srfi is not exactly a library, but
rather a description of features the platform should provide
to support SLIB.  In order to load this module, SLIB must be
already installed.  @xref{SLIB}, for the details.  

@item SRFI-98, An interface to access environment variables
Supported by the module @code{srfi-98}.  @xref{Accessing environment variables}.

@item SRFI-99, ERR5RS Records
Supported by the module @code{gauche.record}.  @xref{Record types}.

@item SRFI-101, Purely functional random-access pairs and lists
This has become a part of R7RS large.
Supported by the module @code{scheme.rlist}.

@item SRFI-106, Basic socket interface
Supported by the module @code{srfi-106}.  @xref{Basic socket interface}.

@item SRFI-111, Boxes
This has become a part of R7RS large as @code{scheme.box}.
Gauche has it as built-in.  @xref{Boxes}.

@item SRFI-112, Environment inquiry
Supported by the module @code{srfi-112}.
@xref{Portable runtime environment inquiry}.

@item SRFI-113, Sets and Bags
This has become a part of R7RS large.
Supported by the module @code{scheme.set}.  @xref{R7RS sets}.

@item SRFI-114, Comparators
Some of the features are built-in (@pxref{Basic comparators}).  Full srfi spec is supported by the module @code{srfi-114} (@pxref{Comparators}).

@item SRFI-115, Scheme Regular Expressions
This has become a part of R7RS large.
Supported by the module @code{scheme.regex}.  @xref{R7RS regular expressions}.

@item SRFI-116, Immutable List Library
This has become a part of R7RS large.
Immutable pairs are supported natively (@pxref{Mutable and immutable pairs}).
Full set of APIs are available
in the module @code{scheme.ilist} (@pxref{R7RS immutable lists}).

@item SRFI-117, Queues based on lists.
This has become a part of R7RS large.
Supported by the module @code{scheme.list-queue}, which is implemented on top
of @code{data.queue}.
(@pxref{R7RS list queues})

@item SRFI-118, Simple adjustable-size strings
Supported by the module @code{srfi-118}.
(@pxref{Simple adjustable-size strings})

@item SRFI-121, Generators
This has become a part of R7RS large.
Gauche's @code{gauche.generator} is superset of srfi-121
(@pxref{Generators}).

@item SRFI-124, Ephemerons
This has become a part of R7RS large.
Supported by @code{scheme.ephemeron}.
Note: Current Gauche's implementation isn't optimal.
@xref{R7RS ephemerons}.

@item SRFI-125, Intermediate hash tables
This has become a part of R7RS large.
Supported by @code{scheme.hash-table}
(@pxref{R7RS hash tables}).
Note that Gauche's native interface provides the same functionalities, but
under slightly different names for the backward compatibility.
@xref{Hashtables}.

@item SRFI-127, Lazy sequences
This has become a part of R7RS large.
Supported by @code{scheme.lseq} (@pxref{R7RS lazy sequences}).

@item SRFI-128, Comparators (reduced)
This has become a part of R7RS large.
Built-in.  @xref{Basic comparators}, for the details.

@item SRFI-129, Titlecase procedures
The procedures @code{char-title-case?} and @code{char-titlecase} are
built-in, and @code{string-titlecase} is in @code{gauche.unicode}.
For the compatibility, you can @code{(use srfi-129)} or
@code{(import (srfi 129))} to get these three procedures.

@item SRFI-130, Cursor-based string library
String cursors are supported natively (@pxref{String cursors}).
Most of built-in and srfi-13 string procedures accept cursors in addition
to indexes.  The module srfi-130 provides several procedures that
has the same name as srfi-13 but returns a string cursor instead
of an index (@pxref{Cursor-based string library}).

@item SRFI-131, ERR5RS Record Syntax (reduced)
This srfi is a pure subset of srfi-99, and @code{gauche.record}'s
@code{define-record-type} covers it.  @xref{Record types}.

@item SRFI-132, Sort libraries
This has become a part of R7RS large.
Supported by the module @code{scheme.sort}.
@xref{R7RS sort}.

@item SRFI-133, Vector library (R7RS-compatible)
This has become a part of R7RS large.
Supported by the module @code{scheme.vector}.  @xref{R7RS vectors}.

@item SRFI-134, Immutable Deques
This has become a part of R7RS large.
The module @code{data.ideque} is compatible to srfi-134.
@xref{Immutable deques}.

@item SRFI-135, Immutable Texts
This has become a part of R7RS large.
In Gauche, the text type is not disjoint from the string type.  Instead,
a text is simply an immutable and indexed string.
@xref{String indexing}, for the detail of indexed string.
The API is described in @ref{R7RS immutable texts}.

@item SRFI-141, Integer division
This has become a part of R7RS large.
Supported by the module @code{scheme.division}.  @xref{R7RS integer division}.

@item SRFI-143, Finxums
This has become a part of R7RS large.
Supported by the module @code{scheme.fixnum}.  @xref{R7RS fixnum}.

@item SRFI-144, Flonums
This has become a part of R7RS large.
Supported by the module @code{scheme.flonum}.  @xref{R7RS flonum}.

@item SRFI-145, Assumptions
Built-in.  @xref{Conditionals}.

@item SRFI-146, Mappings
This has become a part of R7RS large.
Supported by the module @code{scheme.mapping}.
@xref{R7RS mappings}.

@item SRFI-149, Basic syntax-rules template extensions
The built-in @code{syntax-rules} support @code{srfi-149}.

@item SRFI-151, Bitwise operations
Supported by the module @code{srfi-151} (@pxref{R7RS bitwise operations}).
Note that many equivalent procedures are provided built-in
(@pxref{Basic bitwise operations}).

@item SRFI-152, String library (reduced)
Supported by the module @code{srfi-152} (@pxref{String library (reduced)}).

@item SRFI-154, First-class dynamic extents
Suppored by the module @code{srfi-154}.  (@pxref{First-class dynamic extents}).

@item SRFI-158, Generators and accumulators
This has become a part of R7RS large.
Supported by the module @code{scheme.generator}
(@pxref{R7RS generators}).
Note that most of generator procedures are supported by @code{gauche.generator}
(@pxref{Generators}).

@item SRFI-159, Combinator Formatting
This has become a part of R7RS large.  @xref{R7RS combinator formatting}.

@item SRFI-160, Homogeneous numeric vector libraries
This has become a part of R7RS large,
supported by the module @code{scheme.vector.@@} where
@code{@@} is one of @code{base},
@code{u8}, @code{s8}, @code{u16}, @code{s16},
@code{u32}, @code{s32}, @code{u64}, @code{s64}, @code{f32}, @code{f64},
@code{c64}, or @code{c128} (@pxref{R7RS uniform vectors}).

@item SRFI-162, Comparators sublibrary
Supported by the module @code{srfi-162}.  @xref{Comparator sublibrary}.

@item SRFI-170, POSIX API
Supported by the module @code{srfi-170}.  @xref{POSIX API}.

@item SRFI-173, Hooks
Supported by the module @code{srfi-173} (@pxref{Hooks (srfi)}),
which is a thin layer on top of @code{gauche.hook} (@pxref{Hooks})

@item SRFI-174, POSIX Timespecs
Supported by the module @code{srfi-174} (@pxref{POSIX timespecs}).
In Gauche, the timespec type is the same as built-in @code{<time>}
object, which is also the same as srfi-19 time.

@item SRFI-175, ASCII character library
Supported by the module @code{srfi-175} (@pxref{ASCII character library}).

@item SRFI-176, Version flag
Supported as a command-line flag of @code{gosh}.
The @code{version-alist} procedure is built-in.

@item SRFI-178, Bitvector library
The basic support is built-in (@pxref{Bitvectors}).
Complete support is in the module @code{srfi-178} (@pxref{Bitvector library}.

@item SRFI-180, JSON
Supported by the module @code{srfi-180} (@pxref{JSON}).
Note that Gauche also has @code{rfc.json},
and @code{srfi-180} is implemented on top of it.

@item SRFI-181, Custom ports
Supported by the module @code{srfi-181} (@pxref{Custom ports}).
Gauche has an original custom port mechanism (@pxref{Virtual ports}), and
This srfi is built in top of it.

@item SRFI-185, Linear adjustable-length strings
Supported by the module @code{srfi-185}.
@xref{Linear adjustable-length strings}.

@item SRFI-189, Maybe and Either: optional container types
Supported by the module @code{srfi-189}.

@item SRFI-192, Port positioning
Gauche's port already has positining mechanism, so main procedures
are built-in (@pxref{Common port operations}).
A few additional procedures are provided by the module @code{srfi-192}
(@pxref{Port positioning}).

@item SRFI-193, Command line
Two procedures, @code{command-line} and @code{script-file}, are
built-in.  Other APIs are provided by the module @code{srfi-193}
(@pxref{Command line}).

@item SRFI-195, Multiple-value boxes
Built-in.  @xref{Boxes}.

@end table

@node Multibyte strings, Multibyte scripts, Standard conformance, Concepts
@section Multibyte strings
@c NODE マルチバイト文字列

Traditionally, a string is considered as a simple array of bytes.
Programmers tend to imagine a string as a simple
array of characters (though a character may occupy more than one byte).
It's not the case in Gauche.

Gauche supports @emph{multibyte string} natively,
which means characters are represented by variable number of bytes
in a string.   Gauche retains semantic compatibility of
Scheme string, so such details can be hidden, but it'll be helpful
if you know a few points.

A string object keeps a type tag and a pointer to the storage
of the string body.  The storage of the body is managed in a sort of
``copy-on-write''
way---if you take substring, e.g. using directly by @code{substring}
or using regular expression matcher, or even if you copy a string
by @code{copy-string}, the underlying storage is shared
(the ``anchor'' of the string is different, so the copied string
is not @code{eq?} to the original string).
The actual string is copied only if you destructively modify it.

Consequently the algorithm like pre-allocating a string by
@code{make-string} and filling it with @code{string-set!}
becomes @emph{extremely} inefficient in Gauche.  Don't do it.
(It doesn't work with mulitbyte strings anyway).
Sequential access of string is much more efficient
using @emph{string ports} (@pxref{String ports}).

String search primitives such as @code{string-scan} (@pxref{String utilities})
and regular expression matcher (@pxref{Regular expressions})
can return a matched string directly, without
using index access at all.

You can choose @emph{internal} encoding scheme at the time of compiling
Gauche.
At runtime, a procedure @code{gauche-character-encoding}
can be used to query the internal encoding.  At compile time,
you can use a feature identifier to check the internal encoding.
(@pxref{Platform-dependent features}.)
Currently, the following
internal encodings are supported.

@table @code
@item utf-8
UTF-8 encoding of Unicode.  This is the default.
The feature identifier @code{gauche.ces.utf8} indicates Gauche is compiled
with this internal encoding.
@item euc-jp
EUC-JP encoding of ASCII, JIS X 0201 kana, JIS X 0212 and JIS X 0213:2000
Japanese character set.
The feature identifier @code{gauche.ces.eucjp} indicates Gauche is compiled
with this internal encoding.
@item sjis
Shift-JIS encoding of JIS X 0201 kana and JIS X 0213:2000
Japanese character set.  For source-code compatibility, the character
code between 0 and 0x7f is mapped to ASCII.
The feature identifier @code{gauche.ces.sjis} indicates Gauche is compiled
with this internal encoding.
@item none
8-bit fixed-length character encoding, with the code between 0 and 0x7f
matches ASCII.  It's up to the application to interpret the string
with certain character encodings.
The feature identifier @code{gauche.ces.none} indicates Gauche is compiled
with this internal encoding.
@end table

Conversions from other encoding scheme is provided
as a special port. @xref{Character code conversion}, for details.

The way to specify the encoding of source programs will be
explained in the next section.

@node Multibyte scripts, Case-sensitivity, Multibyte strings, Concepts
@section Multibyte scripts
@c NODE マルチバイトスクリプト

You can use characters other than @code{us-ascii} not only in
literal strings and characters, but in comments, symbol names,
literal regular expressions, and so on.

By default, Gauche assumes a Scheme program is written in
its internal character encoding.   It is fine as far as you're writing
scripts to use your own environment, but it becomes a problem if
somebody else tries to use your script and finds out you're using
different character encoding than his/hers.

So, if Gauche finds a comment something like the following within
the first two lines of the program source, it assumes the rest of
the source code is written in @code{<encoding-name>}, and does
the appropriate character encoding conversion to read the source code:
@example
;; coding: <encoding-name>
@end example

More precisely, a comment in either first or second line that matches
a regular expression @code{#/coding[:=]\s*([\w.-]+)/} is recognized,
and the first submatch is taken as an encoding name.
If there are multiple matches, only the first one is effective.
The first two lines must not contain characters other than us-ascii
in order for this mechanism to work.

The following example tells Gauche that the script is written
in EUC-JP encoding.   Note that the string "@code{-*-}" around the coding
would be recognized by Emacs to select the buffer's encoding
appropriately.

@example
#!/usr/bin/gosh
;; -*- coding: euc-jp -*-

... script written in euc-jp ...
@end example

Internally, the handling of this @emph{magic comment} is done by
a special type of port.  See @ref{Coding-aware ports} for the
details.  See also @ref{Loading Scheme file} for how to disable
this feature.

@node Case-sensitivity, Integrated object system, Multibyte scripts, Concepts
@section Case-sensitivity
@c NODE 大文字小文字の区別

Historically, most Lisp-family languages are case-insensitive
for symbols.  Scheme departed from this tradition since R6RS, and
the symbols are read in case-sensitive way.
(Note that symbols have been case-sensitive internally even in R5RS Scheme;
case-insensitivity is about readers.)

Gauche reads and writes symbols in case-sensitive manner by default, too.
However, to support legacy code, you can set the reader to case-insensitive
mode, in the following ways:

@table @asis
@item Use @code{#!fold-case} reader directive
When Gauche sees a token @code{#!fold-case} during reading a program,
the reader switches to case-insensitive mode.  A token
@code{#!no-fold-case} has an opposite effect---to make the
reader case-sensitive.  These tokens affect the port
from which they are read, and are in effect until EOF
or another instance of these tokens are read.
See @ref{Lexical structure} for more details on @code{#!} syntax.
This is the way defined in R6RS and R7RS.

@item Use @code{-fcase-fold} command-line argument
Alternatively, you can give a command-line argument @code{-fcase-fold}
to the @code{gosh} command (@pxref{Invoking Gosh}).
In this mode, the reader folds uppercase characters in symbols to lowercase
ones.  If a symbol name contains uppercase characters, it is written
out using |-escape (@pxref{Symbols}).
@end table


@node Integrated object system, Module system, Case-sensitivity, Concepts
@section Integrated object system
@c NODE 統合されたオブジェクトシステム

Gauche has a STklos-style object system, similar to CLOS.
If you have used some kind of object oriented (OO) languages,
you'll find it easy to understand the basic usage:

@example
;; @r{Defines a class point, that has x and y coordinate}
(define-class point ()
  ((x :init-value 0)
   (y :init-value 0))
  )

(define-method move ((p point) dx dy)
  (inc! (slot-ref p 'x) dx)
  (inc! (slot-ref p 'y) dy))

(define-method write-object ((p point) port)
  (format port "[point ~a ~a]"
          (slot-ref p 'x)
          (slot-ref p 'y)))
@end example

However, if you are familiar with mainstream OO languages but new to CLOS-style
object system, Gauche's object system may look strange
when you look deeper into it.
Here I describe several characteristics of Gauche object system quickly.
@xref{Object system}, for details.

@table @emph
@item Everything is an object (if you care)
You have seen this tagline for the other languages.
And yes, in Gauche, everything is an object in the sense that you can
query its class, and get various meta information of
the object at run time.  You can also define a new method
on any class, including built-in ones.

Note that, however, in CLOS-like paradigm it doesn't really matter
whether everything is an object or not, because of the following
characteristics:

@item Method is dispatched by all of its arguments.
Unlike other object-oriented languages such as C++, Objective-C,
Python, Ruby, etc., in which a method always belong to a single
class, a Gauche method doesn't belong to a specific class.

For example, suppose you define a numeric vector class
@code{<num-vector>} and a numeric matrix class @code{<num-matrix>}.
You can define a method @code{product} with all possible combinations
of those type of arguments:

@example
  (product <num-vector> <num-matrix>)
  (product <num-matrix> <num-vector>)
  (product <num-vector> <num-vector>)
  (product <num-matrix> <num-matrix>)
  (product <number>     <num-vector>)
  (product <number>     <num-matrix>)
  (product <number>     <number>)
@end example

Each method belongs to neither @code{<num-vector>} class nor
@code{<num-matrix>} class.

Since a method is not owned by a class, you can always define your
own method on the existing class (except a few cases
that the system prohibits altering pre-defined methods).  The above
example already shows it; you can make @code{product} method work
on the built-in class @code{<number>}.   That is why I said
it doesn't make much sense to discuss whether everything is object
or not in CLOS-style object system.

To step into the details a bit, the methods are belong to a
@emph{generic function}, which is responsible for dispatching
appropriate methods.

@item Class is also an instance.
By default, a class is also an instance of class
@code{<class>}, and a generic function is an instance of class
@code{<generic>}.  You can subclass @code{<class>} to customize
how a class is initialized or how its slots are accessed.
You can subclass @code{<generic>} to customize how the
applicable methods are selected, which order those methods are
called, etc.   The mechanism is called @emph{metaobject protocol}.
Metaobject protocol allows you to extend the language by
the language itself.

To find examples, see the files @code{lib/gauche/singleton.scm} and
@code{lib/gauche/mop/validator.scm} included in the distribution.
You can also read @code{lib/gauche/mop/object.scm}, which actually
defines how a class is defined in Gauche.
For more details about metaobject protocol, see
Gregor Kiczales, Jim Des Rivieres, Daniel Bobrow,
The Art of Metaobject Protocol,
The MIT Press.

@item Class doesn't create namespace
In the mainstream OO language, a class often creates its own namespace.
This isn't the case in CLOS-style object system.
In Gauche, a namespace is managed by the module system
which is orthogonal to the object system.

@end table

@node Module system, Compilation, Integrated object system, Concepts
@section Module system
@c NODE モジュールシステム

Gauche has a simple module system that allows
modularized development of large software.

A higher level interface is simple enough from the user's point
of view.   It works like this:
When you want to use the features provided by module
@code{foo}, you just need to say @code{(use foo)} in your code.
This form is a macro and interpreted at compile time.
Usually it loads the files that defines @code{foo}'s features,
and imports the external APIs into the calling module.

The @code{use} mechanism is built on top of two independent
lower mechanisms, namespace separation and file loading mechanism.
Those two lower mechanisms can be used separately, although it is much more
convenient when used together.

The @code{use} mechanism is not transitive; that is,
if a module B uses a module A, and a module C uses the module B,
C doesn't see the bindings in A.  It is because B and A is not in the
@code{is-a} relationship.
Suppose the module A implements a low-level functionality and
the module B implements a high-level abstraction; if C is using
B, what C wants to see is just a high-level abstraction, and
doesn't concern how B implements such functionality.  If C wants
to access low-level stuff, C has to @code{use} A explicitly.

There is another type of relationship, though.  You might want to
take an exiting module A, and add some interface to it and provide
the resulting module B as an extension of A.  In such a case,
B is-a A, and it'd be natural that the module that uses B can also
see A's bindings.   In Gauche, it is called @emph{module inheritance}
and realized by @code{extend} form.

The following sections in this manual describes
modules in details.
@itemize @bullet
@item
@ref{Writing Gauche modules} explains the convention of
writing modules.
@item
@ref{Modules} describes special forms and macros to
define and to use modules, along the built-in functions
to introspect module internals.
@end itemize

@node Compilation,  , Module system, Concepts
@section Compilation
@c NODE コンパイル

By default, Gauche reads toplevel Scheme forms one at a time,
compile it immediately to intermediate form and execute it on the VM.
As long as you use Gauche interactively, it looks like an
interpreter.
(There's an experimental ahead-of-time compiler as well.
See @file{HOWTO-precompile.txt} if you want to give a try.)

The fact that we have separate compilation/execution phase, even
interleaved, may lead a subtle surprise if you think Gauche as an interpreter.
Here's a few points to keep in mind:

@table @emph
@item load is done at run time.
@code{load} is a procedure in Gauche, therefore evaluated at run time.
If the loaded program defines a macro, which is available for the compiler
after the toplevel form containing @code{load} is evaluated.  So, suppose
@code{foo.scm} defines a macro @code{foo}, and you use the macro
like this:
@example
;; @r{in ``foo.scm''}
(define-syntax foo
  (syntax-rules () ((_ arg) (quote arg))))

;; @r{in your program}
(begin (load "foo") (foo (1 2 3)))
  @result{} @r{error, bad procedure: `1'}

(load "foo")
(foo (1 2 3)) @result{} '(1 2 3)
@end example
The @code{(begin (load ...))} form fails,  because the compiler
doesn't know @code{foo} is a special form at the compilation time
and compiles @code{(1 2 3)} as if it is a normal procedure call.
The latter example works, however, since the execution
of the toplevel form @code{(load "foo")} is done before
@code{(foo (1 2 3))} is compiled.

To avoid this kind of subtleties, use @code{require} or @code{use}
to load a program fragments.  Those are recognized by the compiler.

@item require is done at compile time
On the other hand, since @code{require} and @code{use} is recognized
by the compiler, the specified file is loaded even if the form
is in the conditional expression.   If you really need to load
a file on certain condition, use @code{load} or do dispatch in macro
(e.g. @code{cond-expand} form (@pxref{Feature conditional}).)
@end table

@c Local variables:
@c mode: texinfo
@c coding: utf-8
@c end:
@node Programming in Gauche, Core syntax, Concepts, Top
@chapter  Programming in Gauche
@c NODE Gaucheでのプログラミング

@menu
* Invoking Gosh::
* Interactive development::
* Writing Scheme scripts::
* Debugging::
* Platform-dependent features::
* Profiling and tuning::
* Writing Gauche modules::
* Using extension packages::
* Building standalone executables::
@end menu

@node Invoking Gosh, Interactive development, Programming in Gauche, Programming in Gauche
@section Invoking Gosh
@c NODE Gaucheを起動する

Gauche can be used either as an independent Scheme scripting engine
or as an embedded Scheme library.   An interactive interpreter
which comes with Gauche distribution is a program named @code{gosh}.

@deftp {Program} gosh [options] [scheme-file arg @dots{}]
Gauche's interpreter.   Without @var{scheme-file}, @code{gosh} works
interactively, i.e. it reads a Scheme expression from the standard input,
evaluates it, and prints the result, and repeat that until it reads EOF or
is terminated.

If @code{gosh} is invoked without @var{scheme-file}, but the input
is not a terminal, it enters read-eval-print loop but not writes
out a prompt while waiting input form.  This is useful when you
pipe Scheme program into @code{gosh}.  You can force this behavior
or suppress this behavior by @code{-b} and @code{-i} options.

If @var{scheme-file} is specified, @code{gosh} runs it as a
Scheme program and exit.
@xref{Writing Scheme scripts}, for details.
@end deftp

@subheading Command-line options

The following command line options are recognized by @code{gosh}.
The first command line argument which doesn't begin with `@minus{}'
is recognized as the script file.  If you want to specify a file
that begins with a minus sign, use a dummy option `@code{--}'.

@deftp {Command Option} -I path
Prepends @var{path} to the load path list.
You can specify this option more than once to add multiple paths.
@end deftp

@deftp {Command Option} -A path
Appends @var{path} to the tail of the load path list.
You can specify this option more than once to add multiple paths.
@end deftp

@deftp {Command Option} -q
Makes @code{gosh} not to load the default initialization file.
@end deftp

@deftp {Command Option} -V
Prints the @code{gosh} version and exits.
@end deftp

@deftp {Command Option} -v version
If @var{version} is not the running @code{gosh}'s version, execute the 
specified version of @code{gosh} instead if it is installed.
This is useful when you want to invoke specific version of Gauche.
Note that @var{version} must be 0.9.6 or later.
@end deftp


@deftp {Command Option} -u module
Use @var{module}.  Before starting execution of @var{scheme-file} or entering
the read-eval-print loop, the specified module is @var{use}d, i.e.
it is loaded and imported (@xref{Defining and selecting modules}, for details of @code{use}).
You can specify this option more than once to use multiple modules.
@end deftp

@deftp {Command Option} -l file
Load @var{file} before starting execution of @var{scheme-file} or entering
the read-eval-print loop.   The file is loaded in the same way as
@code{load} (@pxref{Loading Scheme file}).
You can specify this option more than once to load multiple files.
@end deftp

@deftp {Command Option} -L file
Load @var{file} like @code{-l}, but if @var{file} does not exist,
this silently ignores it instead of reporting an error.
This option can also be specified multiple times.
@end deftp

@deftp {Command Option} -e scheme-expression
Evaluate @var{scheme-expression}
before starting execution of @var{scheme-file} or entering
the read-eval-print loop.   Evaluation is done in the
@var{interaction-environment} (@pxref{Eval and repl}).
You can specify this option more than once to evaluate multiple expressions.
@end deftp

@deftp {Command Option} -E scheme-expression
Same as -e, except the @var{scheme-expression} is read
as if it is surrounded by parenthesis.  For example:
@example
% gosh -umath.const -E"print (sin (* pi/180 15))" -Eexit
0.25881904510252074
@end example
@end deftp

@deftp {Command Option} -b
Batch. Does not print prompts even if the input is a terminal.
@end deftp

@deftp {Command Option} -i
Interactive. Print prompts even if the input is not a terminal.
@end deftp

@deftp {Command Option} -m module
When a script file is given,
this option makes the module named @var{module} in which
the @code{main} procedure is looked for, instead of the @code{user} module.
See @ref{Writing Scheme scripts} for the details of executing scripts.

If the named module doesn't exist after loading the script,
an error is signaled.

This is useful to write a Scheme module that can also be executed
as a script.
@end deftp

@deftp {Command Option} -f compiler-option
This option controls compiler and runtime behavior.  For now we have
following options available:
@table @asis
@item case-fold
Ignore case for symbols.
@item include-verbose
Reports whenever a file is included.
Useful to check precisely which files are included in what order.

@item load-verbose
Reports whenever a file is loaded.
Useful to check precisely which files are loaded in what order.
@item no-inline
Prohibits the compiler from inlining procedures and constants. Equivalent to
no-inline-globals, no-inline-locals, no-inline-constants
and no-inline-setters combined.
@item no-inline-constants
Prohibits the compiler from inlining constants.
@item no-inline-globals
Prohibits the compiler from inlining global procedures.
@item no-inline-locals
Prohibits the compiler from inlining local procedures.
@item no-inline-setters
Prohibits the compiler from inlining setters.
@item no-lambda-lifting-pass
Prohibits the compiler from running lambda-lifting pass.
@item no-post-inline-pass
Prohibits the compiler from running post-inline optimization pass.
@item no-source-info
Don't keep source information for debugging.  Consumes less memory.
@item safe-string-cursors
String cursors used on wrong strings will raise an error. This may
cause performance problems because all cursors will be allocated on
heap. @xref{String cursors}.
@item test
Adds "@code{../src}" and "@code{../lib}" to the load path before loading
initialization file.  This is useful when you want to test the
compiled @code{gosh} REPL without installing it.
@item warn-legacy-syntax
Warns if the reader sees legacy hex-escape syntax in string literals.
@xref{Reader lexical mode}.
@xref{Case-sensitivity}.
@end table
@end deftp

@deftp {Command Option} -p profiler-option
Turn on the profiler.  The following @var{profiler-option} is recognized:

@table @code
@item time
Records and reports time spent on function calls and number of times
each function is called.
@item load
Records and reports time spent on loading each modules.
Useful to tune start-up time of the scripts.
(Results are in elapsed time).
@end table

See @ref{Using profiler} for the details of the profiler.
@end deftp

@deftp {Command Option} -r standard-revision
Start @code{gosh} with an environment of the specified revision
of Scheme standard.  Currently only 7 is supported as
@var{standar-revision}.

By default, @code{gosh} starts with @code{user} module, which inherits
@code{gauche} module.  That means you can use whole Gauche core
procedures by default without explicitly declaring it.

Proper R7RS code always begins with either @code{define-library}
or R7RS-style @code{import} form, and Gauche recognizes it and
automatically switch to R7RS environments so that R7RS scripts and libraries
can be executed by Gauche without special options.
However, users who are learning R7RS Scheme may be confused
when the initial environment doesn't look like R7RS.

By giving @code{-r7} option, @code{gosh} starts with @code{r7rs.user} module
that extends the @code{r7rs} module, which defines two R7RS forms,
@code{import} and @code{define-library}.

If you invoke @code{gosh} into an interactive REPL mode with @code{-r7} option,
all standard R7RS-small libraries (except @code{(scheme r5rs)}) are already
imported for your convenience.

@xref{Library modules - R7RS standard libraries}, for the details on
how Gauche supports R7RS.

(Note: The @code{-r7} option doesn't change reader lexical mode
(@pxref{Reader lexical mode}) to @code{strict-r7}.  That's because
using @code{strict-r7} mode by default prevents many Gauche code
from being loaded.)
@end deftp


@deftp {Command Option} @code{--}
When @code{gosh} sees this option, it stops processing the options
and takes next command line argument as a script file.  It is useful
in case if you have a script file that begins with a minus sign,
although it is not generally recommended.
@end deftp

The options -I, -A, -l, -u, -e and -E are processes in the order
of appearance.  For example, adding a load path by -I affects the
-l and -u option after it but not before it.

@subheading Environment variables

The following environment variables are recognized:

@deftp {Environment variable} GAUCHE_AVAILABLE_PROCESSORS
You can get the number of system's processors by
@code{sys-available-processors} (@pxref{Environment inquiry});
libraries/programs may use this info to optimize number of
parallel threads.  But you might change that, for testing
and benchmarking---e.g. a program automatically uses
8 threads if there are 8 cores, but you might want to run it
with 1, 2, 4 threads as well to see the effect of parallelization.
This environment variable overrides
the return value of @code{sys-available-processors}.
@end deftp

@deftp {Environment variable} GAUCHE_CHECK_UNDEFINED_TEST
Warn if @code{#<undef>} is used in the test expression of branch.

In boolean context, @code{#<undef>} counts true.  It is also
often the case that a procedure returns @code{#<undef>} when
the return value doesn't matter, and you shouldn't rely on
the value that is supposed not to matter--the procedure may
change the return value in future (which should be ok, since
the value shouldn't have mattered), which can cause unintentional
and hard-to-track bugs.
@xref{Undefined values}, for the details.

We strongly recommend users to turn on this warning.  In future,
we plan to make this default.
@end deftp


@deftp {Environment variable} GAUCHE_DYNLOAD_PATH
You can specify additional load paths for dynamically loaded
objects by this environment variable, delimiting the paths by '@code{:}'.
The paths are appended before the system default load paths.

@xref{Loading dynamic library}, for the details of how Gauche
finds dynamically loadable objects.
@end deftp

@deftp {Environment variable} GAUCHE_EDITOR
@deftpx {Environment variable} EDITOR
This is used by @code{ed} procedure in @code{gauche.interactive} module.
@xref{Interactive session}, for the details.
@end deftp

@deftp {Environment variable} GAUCHE_HISTORY_FILE
If Gauche is invoked with @code{GAUCHE_READ_EDIT} enabled (see below),
the REPL history is kept in @file{~/.gosh_history} by default.
This environment variable overrides the history file.
To prohibit saving history, set an empty string to this variable.
If the process is suid/sgid-ed, history won't be saved.
@end deftp

@deftp {Environment variable} GAUCHE_KEYWORD_DISJOINT
@deftpx {Environment variable} GAUCHE_KEYWORD_IS_SYMBOL
These two environment variables affect whether keywords are treated
as symbols or not.  @xref{Keywords}, for the details.
@end deftp

@deftp {Environment variable} GAUCHE_LEGACY_DEFINE
Make the behavior of toplevel @code{define} the same as
0.9.8 and before.
It allows certain legacy programs that aren't valid R7RS.
@xref{Into the Scheme-Verse}, for the details.
@end deftp

@deftp {Environment variable} GAUCHE_LOAD_PATH
You can specify additional load paths by this environment
variable, delimiting the paths by '@code{:}'.
The paths are appended before the system default load paths.

@xref{Loading Scheme file}, for the details of how Gauche finds
files to load.
@end deftp

@deftp {Environment variable} GAUCHE_MUTABLE_LITERALS
Allow literal lists and vectors to be mutated.  Such code isn't a
valid Scheme program and causes an error,
but Gauche didn't enforce the restriction
on 0.9.9 and before, so some legacy code may accidentally mutates
literals.  Set this environment variables to run such old programs.
@xref{Literals}, for the details.
@end deftp

@deftp {Environment variable} GAUCHE_QUASIRENAME_MODE
This affects @code{quasirename} behavior, to keep the backward
compatibility with 0.9.7 and before.
@xref{Explicit-renaming macro transformer}, for the details.
@end deftp


@deftp {Environment variable} GAUCHE_READ_EDIT
This is used by @code{gauche.interactive} module to enable line-editor
on REPL prompt.  @xref{Interactive development}, for the details.
@end deftp

@deftp {Environment variable} GAUCHE_REPL_NO_PPRINT
This is used by @code{gauche.interactive} module to suppress
pretty-printing on REPL prompt.
@xref{Interactive development}, for the details.
@end deftp

@deftp {Environment variable} GAUCHE_SUPPRESS_WARNING
Suppress system warnings (@code{WARNING: ...}).  Not generally recommended;
use only if you absolutely need to.
@end deftp

@deftp {Environment variable} GAUCHE_TEST_RECORD_FILE
This is used by @code{gauche.test} module (@pxref{Unit testing}).
If defined, names a file the test processes
keep the total statistics.
@end deftp

@deftp {Environment variable} GAUCHE_TEST_REPORT_ERROR
This is used by @code{gauche.test} module (@pxref{Unit testing}).
If defined, reports stack trace to stderr
when the test thunk raises an error (even when it is expected).
Useful for diagnosis of unexpected errors.
@end deftp


@deftp {Environment variable} TMP
@deftpx {Environment variable} TMPDIR
@deftpx {Environment variable} TEMP
@deftpx {Environment variable} USERPROFILE
These may affect the return value of @code{sys-tmpdir}.
Different environment variables may be used on different platforms.
@xref{Pathnames}, for the details.
@end deftp


@subheading Windows-specific executable

On Windows-native platforms (mingw), two interpreter executables are
installed.  @code{gosh.exe} is compiled as a Windows console
application and works just like ordinary @code{gosh}; that is,
it primarily uses standard i/o for communication.
Another executable, @code{gosh-noconsole.exe}, is compiled
as a Windows no-console (GUI) application.  It is not attached
to a console when it is started.  Its standard input is connected
to the @code{NUL} device.  Its standard output and standard error
output are special ports which open a new console when something
is written to them for the first time.  (NB: This magic only works
for output via Scheme ports; direct output from low-level C libraries
will be discarded.)

The main purpose of @code{gosh-noconsole.exe} is for Windows
scripting.   If a Scheme script were associated to @code{gosh.exe}
and invoked from Explorer, it would always open a new
console window, which is extremely annoying.
If you associate Scheme scripts to @code{gosh-noconsole.exe} instead,
you can avoid console from popping up.

If you're using the official Windows installer, Scheme scripts
(@file{*.scm}) have already associated to @code{gosh-noconsole.exe}
and you can invoke them by double-clicking on Explorer.
Check out some examples under @file{C:\Program Files\Gauche\examples}.

@c ----------------------------------------------------------------------
@node Interactive development, Writing Scheme scripts, Invoking Gosh, Programming in Gauche
@section Interactive development
@c NODE  インタラクティブな開発

When @code{gosh} is invoked without any script files,
it goes into interactive read-eval-print loop (REPL).

To exit the interpreter, type EOF (usually Control-D in Unix terminals)
or evaluate @code{(exit)}.

In the interactive session, @code{gosh} loads and
imports @code{gauche.interactive}
module (@pxref{Interactive session}) into @code{user} module, for the
convenience.  Also, if there's a file @file{.gaucherc} under
the user's home directory.
You may put settings there that would help interactive debugging.
(As of Gauche release 0.7.3,
@file{.gaucherc} is no longer loaded when @code{gosh} is run
in script mode.)

Note that @file{.gaucherc} is always loaded in the @code{user} module,
even if @code{gosh} is invoked with @code{-r7} option.  The file
itself is a Gauche-specific feature, so you don't need to consider
portability in it.

I recommend you to run @code{gosh} inside Emacs, for it has
rich features useful to interact with internal Scheme process.
Put the following line to your @file{.emacs} file:
@example
(setq scheme-program-name "gosh -i")
@end example
And you can run @code{gosh} by @key{M-x run-scheme}.

You can turn on input-editing by an
environment variable @code{GAUCHE_READ_EDIT} or a command-line option
@code{-fread-edit}.  @xref{Input editing}, for the details.

If you want to use multibyte characters in the interaction,
make sure your terminal's settings is in sync with @code{gosh}'s
internal character encodings.

@menu
* Working in REPL::
* Input editing::
@end menu

@node Working in REPL, Input editing, Interactive development, Interactive development
@subsection Working in REPL
@c NODE REPLでの開発

When you enter REPL, Gauche prompts you to enter a Scheme expression:

@example
gosh>
@end example

(If you enable input editing, the prompt shows @code{gosh$} instead
of @code{gosh>}.  @xref{Input editing}, for the details.)

After you complete a Scheme expression and type ENTER,
the result of evaluation is printed.

@example
gosh> @i{(+ 1 2)}
3
gosh> 
@end example

The REPL session binds the last three results of evaluation
in the global variables @code{*1}, @code{*2} and @code{*3}.
You can use the previous results via those history variables
in subsequent expressions.

@example
gosh> @i{*1}
3
gosh> @i{(+ *2 3)}
6
@end example

If the Scheme expression yields multiple values
(@pxref{Multiple values}), they are printed one by one.

@example
gosh> @i{(min&max 1 -1 8 3)}
-1
8
gosh> 
@end example

The history variable @code{*1}, @code{*2} and @code{*3} only
binds the first value.  A list of all values are bound to
@code{*1+}, @code{*2+} and @code{*3+}.

@example
gosh> @i{*1}
-1
gosh> @i{*2+}
(-1 8)
@end example

(Note that, when you evaluate @code{*1} in the above example, the
history is shifted---so you need to use @code{*2+} to refer to the
result of @code{(min&max 1 -1 8 3)}.)

The @code{*history} procedure shows the value of history variables:

@example
gosh> @i{(*history)}
*1: (-1 8)
*2: -1
*3: -1
gosh> 
@end example

As a special case, if an evaluation yields zero values, history
isn't updated.   The @code{*history} procedure returns
no values, so merely looking at the history won't change the history
itself.

@example
gosh> @i{(*history)}
*1: (-1 8)
*2: -1
*3: -1
gosh> (values)
gosh> @i{(*history)}
*1: (-1 8)
*2: -1
*3: -1
@end example


Finally, a global variable @code{*e} is bound to the last uncaught
error condition object.

@example
gosh> @i{(filter odd? '(1 2 x 4 5))}
*** ERROR: integer required, but got x
Stack Trace:
_______________________________________
  0  (eval expr env)
        At line 173 of "/usr/share/gauche-0.9/0.9.3.3/lib/gauche/interactive.scm"
gosh> @i{*e}
#<error "integer required, but got x">
@end example

(The error stack trace may differ depending on your installation.)

In REPL prompt, you can also enter special @emph{top-level commands}
for common tasks.  Top-level commands are not Scheme
expressions, not even S-expressions.
They work like traditional line-oriented shell commands instead.

Top-level commands are prefixed by comma to be distinguished from
ordinary Scheme expressions.  To see what commands are available,
just type @code{,help} and return.

@example
gosh> ,help
You're in REPL (read-eval-print-loop) of Gauche shell.
Type a Scheme expression to evaluate.
A word preceded with comma has special meaning.  Type ,help <cmd> 
to see the detailed help for <cmd>.
Commands can be abbreviated as far as it is not ambiguous.

 ,apropos|a  Show the names of global bindings that match the regexp.
 ,cd         Change the current directory.
 ,describe|d Describe the object.
 ,help|h     Show the help message of the command.
 ,history    Show REPL history.
 ,info|doc   Show info document for an entry of NAME, or search entries by REGEXP.
 ,load|l     Load the specified file.
 ,print-all|pa
             Print previous result (*1) without abbreviation.
 ,print-mode|pm
             View/set print-mode of REPL.
 ,pwd        Print working directory.
 ,reload|r   Reload the specified module, using gauche.reload.
 ,sh         Run command via shell.
 ,source     Show source code of the procedure if it's available.
 ,use|u      Use the specified module.  Same as (use module option ...).
@end example

To see the help of each individual commands, give the command name
(without comma) to the @code{help} command:

@example
gosh> ,help d
Usage: d|describe [object]
Describe the object.
Without arguments, describe the last REPL result.
@end example

The @code{,d} (or @code{,describe}) top-level command describes
the given Scheme object
or the last result if no object is given.  Let's try some:

@example
gosh> (sys-stat "/home")
#<<sys-stat> 0x2d6adc0>
gosh> ,d
#<<sys-stat> 0x2d6adc0> is an instance of class <sys-stat>
slots:
  type      : directory
  perm      : 493
  mode      : 16877
  ino       : 2
  dev       : 2081
  rdev      : 0
  nlink     : 9
  uid       : 0
  gid       : 0
  size      : 208
  atime     : 1459468837
  mtime     : 1401239524
  ctime     : 1401239524
@end example

In the above example, first we evaluated @code{(sys-stat "/home")},
which returns @code{<sys-stat>} object.  The subsequent @code{,d} top-level
command describes the returned @code{<sys-stat>} object.

The description depends on the type of objects.  Some types of
objects shows extra information.  If you describe an exact integer,
it shows alternative interpretations of the number:

@example
gosh> ,d 1401239524
1401239524 is an instance of class <integer>
  (#x538537e4, ~ 1.3Gi, 2014-05-28T01:12:04Z as unix-time)
gosh> ,d 48
48 is an instance of class <integer>
  (#x30, #\0 as char, 1970-01-01T00:00:48Z as unix-time)
@end example

If you describe a symbol, its known bindings is shown.

@example
gosh> ,d 'filter
filter is an instance of class <symbol>
Known bindings for variable filter:
  In module `gauche':
    #<closure (filter pred lis)>
  In module `gauche.collection':
    #<generic filter (2)>
@end example

If you describe a procedure, and its source code location is known,
that is also shown (see the @code{Defined at...} line):

@example
gosh> ,d string-interpolate
#<closure (string-interpolate str :optional (legacy? #f))> is an
instance of class <procedure>
Defined at "../lib/gauche/interpolate.scm":64
slots:
  required  : 1
  optional  : #t
  optcount  : 1
  locked    : #f
  currying  : #f
  constant  : #f
  info      : (string-interpolate str :optional (legacy? #f))
  setter    : #f
@end example

Let's see a couple of other top-level commands.  The @code{,info}
command shows the manual entry of the given procedure, variable, syntax,
module or a class.  (The text is searched from the installed
info document of Gauche.  If you get an error, check if the
info document is properly installed.)

@example
gosh> ,info append
 -- Function: append list ...
     [R7RS] Returns a list consisting of the elements of the first LIST
     followed by the elements of the other lists.  The resulting list is
     always newly allocated, except that it shares structure with the
     last list argument.  The last argument may actually be any object;
     an improper list results if the last argument is not a proper list.

gosh> ,info srfi-19
 -- Module: srfi-19
     This SRFI defines various representations of time and date, and
     conversion methods among them.

     On Gauche, time object is supported natively by '<time>' class
     (*note Time::).  Date object is supported by '<date>' class
     described below.

gosh> ,info <list>
 -- Builtin Class: <list>
     An abstract class represents lists.  A parent class of '<null>' and
     '<pair>'.  Inherits '<sequence>'.

     Note that a circular list is also an instance of the '<list>'
     class, while 'list?' returns false on the circular lists and dotted
     lists.
          (use srfi-1)
          (list? (circular-list 1 2)) => #f
          (is-a? (circular-list 1 2) <list>) => #t
@end example

You can also give a regexp pattern to @code{,info} command
(@pxref{Regular expressions}).
It shows the entries in the document that match the pattern.

@example
gosh> ,info #/^string-.*\?/
string-ci<=?             Full string case conversion:44
                         String comparison:19
string-ci<?              Full string case conversion:43
                         String comparison:18
string-ci=?              Full string case conversion:42
                         String comparison:17
string-ci>=?             Full string case conversion:46
                         String comparison:21
string-ci>?              Full string case conversion:45
                         String comparison:20
string-immutable?        String Predicates:9
string-incomplete?       String Predicates:12
string-null?             SRFI-13 String predicates:6
string-prefix-ci?        SRFI-13 String prefixes & suffixes:28
string-prefix?           SRFI-13 String prefixes & suffixes:26
string-suffix-ci?        SRFI-13 String prefixes & suffixes:29
string-suffix?           SRFI-13 String prefixes & suffixes:27
@end example

The @code{,a} command (or @code{,apropos}) shows the global identifiers
matches the given name or regexp:

@example
gosh> ,a filter
filter                         (gauche)
filter!                        (gauche)
filter$                        (gauche)
filter-map                     (gauche)
@end example

Note: The @code{apropos} command looks for symbols from the
current process---that is, it only shows names that have been loaded
and imported.
But it also mean it can show any name as far as it exists in the
current process, regardless of whether it's a documented API or an
internal entry.

On the other hand, the @code{info}
command searches info document, regardless of the named entity
has loaded into the current process or not.  It doesn't show
undocumented APIs.

You can think that @code{apropos} is an introspection tool,
while @code{info} is a document browsing tool.

When the result of evaluation is a huge nested structure,
it may take too long to display the result.  Gauche actually set
a limit of length and depth in displaying structures, so you might
occasionally see the very long or deep list is trucated, with
@dots{} to show there are more items, or @code{#} to show a subtree
is omitted
(Try evaluating @code{(make-list 100)} on REPL).

You can type @code{,pa} (or @code{,print-all}) toplevel REPL command
to fully redisplay the previous result without omission.

By default, REPL prints out the result using @emph{pretty print}:

@example
gosh> ,u sxml.ssax
gosh> (call-with-input-file "src/Info.plist" (cut ssax:xml->sxml <> '()))
(*TOP*
 (*PI* xml "version=\"1.0\" encoding=\"UTF-8\"")
 (plist
  (|@@| (version "1.0"))
  (dict (key "CFBundleDevelopmentRegion") (string "English")
   (key "CFBundleExecutable") (string "Gauche") (key "CFBundleIconFile")
   (string) (key "CFBundleIdentifier") (string "com.schemearts.gauche")
   (key "CFBundleInfoDictionaryVersion") (string "6.0")
   (key "CFBundlePackageType") (string "FMWK") (key "CFBundleSignature")
   (string "????") (key "CFBundleVersion") (string "1.0")
   (key "NSPrincipalClass") (string))))
@end example

If you want to turn off pretty printing for some reason,
type @code{,pm pretty #f} (or @code{,print-mode pretty #f}) on the
toplevel prompt, or start @code{gosh} with the environment variable
@code{GAUCHE_REPL_NO_PPRINT} set.

Type @code{,pm default} to make print mode back to default.
For more details, type @code{,help pm}.

Note: If you invoke @code{gosh} with @code{-q} option, which tells
@code{gosh} not to load the initialization files, you still get
a REPL prompt but no fancy features such as history variables
are available.  Those convenience features are implemented in
@code{gauche.interactive} module, which isn't loaded with @code{-q}
option.

@node Input editing,  , Working in REPL, Interactive development
@subsection Input editing
@c NODE 入力の編集

Gauche provides input editing feature on REPL.  Currently it is
an experimental feature and isn't turn on by default, but you can
try it by setting @code{GAUCHE_READ_EDIT} environment variable,
or give @code{-fread-edit} flag to @code{gosh}.

If input editing mode is on, the REPL prompt ends with @code{$}, such
as @code{gosh$}, instead of @code{gosh>}.

(NB: Even if you set @code{GAUCHE_READ_EDIT} or give @code{-fread-edit},
input editing may not be turned on if the terminal is not capable to do it.
For example, if you run @code{gosh} inside Emacs, you'll get @code{gosh>}
prompt even you have @code{GAUCHE_READ_EDIT} set.  Of course, you can
use Emacs editing features in such a case instead.)

The key binding is similar to Emacs.  Eventually we'll provide customization
feature.  Before going into details, here's a few quick useful tips.

@itemize @bullet
@item
If the screen is garbled somehow, type @code{C-l} (control+l) to clear and
redisplay.
@item
If you want to turn off editing during REPL session, use @code{,edit off}
toplevel command.
@item
The input editor only sends a complete S-expression to the evaluator.  If
somehow you want to send the current input as-is (or, in case the editor
has a bug and don't allow you to send a complete S-expression), type
@code{C-M-x} (control-meta-x) to force sending the current input to the
evaluator.
@item
You can type @code{M-h h} to see a brief summary of editor features,
@code{M-h b} to see the list of keymap, or
@code{M-h k} + keystroke to see the help of the key.
(@code{C-h} is the same as backspace).
@item
If you suspend @code{gosh}, then resume it by shell's job control feature
(e.g. @code{C-z}, then @code{fg}).
type ENTER to regain editing screen.
@end itemize

@subsubheading Cursor movement

@code{C-f} (forward) and @code{C-b} (backward) moves the cursor forward
and backward character-wise.  @code{C-p} (previous) and @code{C-n} (next)
moves character to previous or next line, if the input already has
multiple lines, or moves to previous or next history.

@code{M-f} and @code{M-b} move the cursor forward and backward, word-wise.

@code{C-a} and @code{C-e} to move to the beginning and end of the line,
@code{M-<} and @code{M->} to move to the beginning and end of of the input.

@subsubheading Undo

@code{C-_} is undo the edit.  You can keep typing @code{C-_} to
undo the edits you've made.
We follow the Emacs model of undo
semantics, which allows ``undoing undoes''.
For the detailed algorithm, see the comment at the bottom of
@file{lib/text/line-edit.scm}
in the source tree.

@subsubheading Kill and yank

@code{C-k} removes characters from the cursor to the end of line.
If the cursor is at the end of the line though, it removes the newline
character (so that next line is combined to the current line).

@code{M-d} removes a word that contains the cursor, or a word
immediately after the cursor if it is not on a word.

@code{C-@@} set a mark to the current cursor position.  @code{C-w} removes
chracters between the cursor and the mark.

The characters removed by those commands are saved
in the buffer called ``kill-ring''.
They can be recalled at the cursor position by @code{C-y} (yank).
If you press @code{M-y} immediately followed by @code{C-y}, you can
go back to the older killed characters.

@subsubheading Finishing input

@code{RET} (or @code{C-m}) inserts a newline if the input isn't
a complete S-expresson.  If the input is already a complete S-expression,
however, it sends the entire input to the evaluator, no matter where
the cursor is.  If you want to insert a newline in a complete S-expression,
you can use @code{C-j}.

@code{M-C-x} sends the current input regardless that the input is
a complete S-expression or not.

@subsubheading History

Input history is remembered and recalled by @code{M-p} (prev-history)
and @code{M-n} (next-history).
The cursor movement command @code{C-p} and @code{C-n} also moves to
the previous or next history if it is pressed when the cursor is
at the beginning or the end of the input lines.

The input interrupted by @code{C-c} isn't remembered.

By default, the input is saved to a file @file{~/.gosh_history} when the
REPL is terminated normally, and reloaded when the next REPL is invoked.
The name of the history file can be changed by the environment variable
@code{GAUCHE_HISTORY_FILE}.  If the environment variable is defined to an
empty string, however, the history won't be saved.

@subsubheading Miscellaneous

@code{C-g} cancels the current multi-key sequences.

@code{C-c} cancels the current input.

@code{C-t} transpose characters at and before the cursor.

@code{C-q} reads the next keystroke and insert it into the input as is.

@code{M-(} inserts a pair of parentheses, and locate a cursor inside them.

@code{C-l} clears the screen and redraws the current input buffer.

@c ----------------------------------------------------------------------
@node Writing Scheme scripts, Debugging, Interactive development, Programming in Gauche
@section Writing Scheme scripts
@c NODE Schemeスクリプトを書く

When a Scheme program file is given to @code{gosh}, it
makes the @code{user} module as the current module,
binds a global variable @code{*argv*} to the list of the remaining
command-line arguments, and then loads the Scheme program.
If the first line of @var{scheme-file} begins with two character
sequence ``@code{#!}'', the entire line is ignored by @code{gosh}.
This is useful to write a Scheme program that works as an executable
script in unix-like systems.

Typical Gauche script has the first
line like these

@example
#!/usr/local/bin/gosh
  @r{or,}
#!/usr/bin/env gosh
  @r{or,}
#!/bin/sh
:; exec gosh -- $0 "$@@"
@end example

The second and third form uses a ``shell trampoline'' technique
so that the script works as far as @code{gosh} is in the PATH.
The third form is useful when you want to pass extra arguments
to @code{gosh}, for typically @code{#!}-magic of executable scripts
has limitations for the number of arguments to pass the interpreter.

After the file is successfully loaded, @code{gosh} calls a
procedure named `@code{main}' if it is defined in the user module.
@code{Main} receives a single argument, a list of command line
arguments.  Its first element is the script name itself.

When @code{main} returns, and its value is an integer, @code{gosh}
uses it for exit code of the program.
Otherwise, @code{gosh} exits with exit code 70 (@code{EX_SOFTWARE}).
This behavior is compatible with the SRFI-22.

If the @code{main} procedure is not defined, @code{gosh} exits
after loading the script file.

Although you can still write the program
main body as toplevel expressions, like shell scripts or Perl scripts,
it is much convenient to use this `@code{main}' convention, for
you can load the script file interactively to debug.

Using @code{-m} command-line option, you can make @code{gosh} call
@code{main} procedure defined in a module other than the @code{user}
module.  It is sometimes handy to write a Scheme module that can
also be executed as a script.

For example, you write a Scheme module @code{foo}
and @emph{within it}, you define the @code{main} procedure.
You don't need to export it.  If the file is loaded as a module,
the @code{main} procedure doesn't do anything.  But if you
specify @code{-m foo} option and give the file as a Scheme script
to @code{gosh}, then
the @code{main} procedure is invoked after loading the script.
You can code tests or small example application in such an
alternate main procedure.

@emph{Note on R7RS Scripts}: If the script is written in R7RS Scheme
(which can be distinguished by the first @code{import} declaration,
@pxref{Three forms of import}), it is read into @code{r7rs.user}
module and its @code{main} isn't called.
You can give @code{-mr7rs.main} command-line argument to call
the @code{main} function in R7RS script.
Alternatively, as specified in SRFI-22, if the script interpreter's
basename is @file{scheme-r7rs}, we assume the script is R7RS SRFI-22 script
and calls @code{main} in @code{r7rs.user} module rather than @code{user}
module.  We don't install such an alias, but you can manually
make symbolic link or just copy @file{gosh} binary as @file{scheme-r7rs}.

Although the argument of the @code{main} procedure is the standard way
to receive the command-line arguments, there are a couple of other
ways to access to the info.  @xref{Command-line arguments}, for the
details.

Now I show several simple examples below.
First, this script works like @code{cat(1)}, without any command-line
option processing and error handling.

@example
#!/usr/bin/env gosh

(define (main args)   ;@r{entry point}
  (if (null? (cdr args))
      (copy-port (current-input-port) (current-output-port))
      (for-each (lambda (file)
                  (call-with-input-file file
                    (lambda (in)
                      (copy-port in (current-output-port)))))
                (cdr args)))
  0)
@end example

The following script is a simple grep command.

@example
#!/usr/bin/env gosh

(define (usage program-name)
  (format (current-error-port)
          "Usage: ~a regexp file ...\n" program-name)
  (exit 2))

(define (grep rx port)
  (with-input-from-port port
    (lambda ()
      (port-for-each
       (lambda (line)
         (when (rxmatch rx line)
           (format #t "~a:~a: ~a\n"
                   (port-name port)
                   (- (port-current-line port) 1)
                   line)))
       read-line))))

(define (main args)
  (if (null? (cdr args))
      (usage (car args))
      (let ((rx (string->regexp (cadr args))))
        (if (null? (cddr args))
            (grep rx (current-input-port))
            (for-each (lambda (f)
                        (call-with-input-file f
                          (lambda (p) (grep rx p))))
                      (cddr args)))))
  0)
@end example

See also @ref{Parsing command-line options}, for a convenient way to
parse command-line options.

@c ----------------------------------------------------------------------
@node Debugging, Platform-dependent features, Writing Scheme scripts, Programming in Gauche
@section Debugging
@c NODE デバッグ

Gauche doesn't have much support for debugging yet.
The idea of good debugging interfaces are welcome.

For now, the author uses the classic 'debug print stub' technique
when necessary.  Gauche's reader supports special syntaxes
beginning with @code{#?}, to print the intermediate value.

The syntax @code{#?=@var{expr}} shows @var{expr} itself before
evaluating it, and prints its result(s) after evaluation.  

@example
gosh> #?=(+ 2 3)
#?="(stdin)":1:(+ 2 3)
#?-    5
5
gosh> #?=(begin (print "foo") (values 'a 'b 'c))
#?="(stdin)":2:(begin (print "foo") (values 'a 'b 'c))
foo
#?-    a
#?+    b
#?+    c
a
b
c
@end example

Note: If the debug stub is evaluated in a thread other than
the primordial thread (@pxref{Threads}), the output
includes a number to distinguish which thread it is generated.
In the following example, @code{#<thread ...>} and the prompt
is the output of REPL in the primordial thread,
but following @code{#?=[1]...} and @code{#?-[1]...} are
the debug output from the thread created by @code{make-thread}.
The number is for debugging only---
they differ for each thread, but other than that there's no meaning.

@example
gosh> (use gauche.threads)
gosh> (thread-start! (make-thread (^[] #?=(+ 2 3))))
#<thread #f (1) runnable 0xf51400>
gosh> #?=[1]"(standard input)":1:(+ 2 3)
#?-[1]    5
@end example

The syntax @code{#?,(@var{proc} @var{arg} @dots{})} is specifically
for procedure call; it prints the value of arguments right before
calling @var{proc}, and prints the result(s) of call afterwards.

@example
gosh> (define (fact n)
        (if (zero? n)
            1
            (* n #?,(fact (- n 1)))))
fact
#?,"(standard input)":4:calling `fact' with args:
#?,> 4
#?,"(standard input)":4:calling `fact' with args:
#?,> 3
#?,"(standard input)":4:calling `fact' with args:
#?,> 2
#?,"(standard input)":4:calling `fact' with args:
#?,> 1
#?,"(standard input)":4:calling `fact' with args:
#?,> 0
#?-    1
#?-    1
#?-    2
#?-    6
#?-    24
120
@end example

Internally, the syntax @code{#?=@var{x}} and @code{#?,@var{x}} are read
as @code{(debug-print @var{x})} and @code{(debuf-funcall @var{x})},
respectively, and the macros @code{debug-print} and @code{debug-funcall}
handles the actual printing.  @xref{Debugging aid}, for more details.

The reasons of special syntax are: (1) It's easy to insert the
debug stub, for you don't need to enclose the target expression by
extra parenthesis, and
(2) It's easy to find and remove those stabs within the editor.

@c ----------------------------------------------------------------------
@node Platform-dependent features, Profiling and tuning, Debugging, Programming in Gauche
@section Using platform-dependent features
@c NODE プラットフォーム依存の機能

Gauche tries to provide low-level APIs close to what the underlying
system provides, but sometimes they vary among systems.  For example,
POSIX does not require @code{symlink}, so some systems may lack
@code{sys-symlink} (@pxref{Directory manipulation}).  Quite a few
unix-specific system functions are not available on Windows platform.
To allow writing a portable program across those platforms, Gauche
uses @code{cond-expand} (@pxref{Feature conditional}) extensively.
A set of extended @emph{feature-identifier}s is provided to check
availability of specific features.  For example, on systems that
has @code{symlink}, a feature identifier @code{gauche.sys.symlink}
is defined.   So you can write a code that can switch based on
the availability of @code{sys-symlink} as follows:

@example
(cond-expand
 (gauche.sys.symlink
   ... code that uses sys-symlink ...)
 (else
   ... alternative code ...)
 )
@end example

If you're familiar with system programming in C, you can think
it equivalent to the following C idiom:

@example
#if defined(HAVE_SYMLINK)
... code that uses symlink ...
#else
... alternative code ...
#endif
@end example

There are quite a few such feature identifiers; each identifier is
explained in the manual entry of the procedures that depend on the feature.
Here we list a few important ones:

@table @code
@item gauche
This feature identifier is always defined.  It is useful when you
write Scheme code portable across multiple implementations.
@item gauche.os.windows
Defined on Windows native platform.  Note that cygwin does not define
this feature identifier (but see below).
@item gauche.os.cygwin
Defined on Cygwin.
@item gauche.sys.threads
Defined if Gauche is compiled with thread support.
@xref{Threads}.
@item gauche.sys.pthreads
@itemx gauche.sys.wthreads
Defined to indicate the underlying thread implementation
when Gauche has thread support.
@xref{Threads}.
@item gauche.net.ipv6
Defined if Gauche is compiled with IPv6 support.
@item gauche.ces.utf8
@itemx gauche.ces.eucjp
@itemx gauche.ces.sjis
@itemx gauche.ces.none
Either one of these feature identifiers is defined, according to the
compile-time option of Gauche's internal character encoding.
@xref{Multibyte strings}, for the details of the internal character encoding.
@end table

Because @code{cond-expand} is a macro, the body of clauses
are expanded into toplevel if @code{cond-expand} itself is in
toplevel.  That means you can switch toplevel definitions:

@example
(cond-expand
 (gauche.os.windows
  (define (get-current-user)
    ... get current username ...))
 (else
  (define (get-current-user)
    (sys-uid->user-name (sys-getuid)))))
@end example

Or even conditionally "use" the modules:

@example
(cond-expand
 (gauche.os.windows
   (use "my-windows-compatibility-module"))
 (else))
@end example

The traditional technique of testing a toplevel binding
(using @code{global-variable-bound?}, @pxref{Module introspection})
doesn't work well in this case, since
the @code{use} form takes effect at compile time.  
It is strongly recommended to use @code{cond-expand} whenever possible.

Currently the set of feature identifiers are fixed at the build
time of Gauche, so it's less flexible than C preprocessor conditionals.
We have a plan to extend this feature to enable adding new feature
identifiers; but such feature can complicate semantics when compilation
and execution is interleaved, so we're carefully assessing the effects now.

A couple of notes:

Feature identifiers are not variables.  They can only be used
within the @var{feature-requirement} part of @code{cond-expand}
(see @ref{Feature conditional} for the complete definition of
feature requirements).

By the definition of @code{srfi-0}, @code{cond-expand} raises an error
if no feature requirements are satisfied and there's no @code{else}
clause.  A rule of thumb is to provide @code{else} clause always,
even it does nothing (like the above example that has empty @code{else}
clause).

@c ----------------------------------------------------------------------
@node Profiling and tuning, Writing Gauche modules, Platform-dependent features, Programming in Gauche
@section Profiling and tuning
@c NODE プロファイリングとチューニング

If you find your script isn't running fast enough,
there are several possibilities to improve its performance.

It is always a good idea to begin with finding which part
of the code is consuming the execution time.   Gauche has
a couple of basic tools to help it.  A built-in sampling profiler,
explained in the following subsection, can show how much time
is spent in each procedure, and how many times it is called.
The @code{gauche.time} module (@ref{Measure timings}) provides
APIs to measure execution time of specific parts of the code.

Optimization is specialization---you look for the most common
patterns of execution, and put a special path to support those
patterns efficiently.  Gauche itself is no exception, so there
are some patterns Gauche can handle very efficiently, while
some patterns it cannot.  The next subsection, @ref{Performance tips},
will give you some tips of how to adapt your code to fit
the patterns Gauche can execute well.

@menu
* Using profiler::
* Performance tips::
@end menu

@node Using profiler, Performance tips, Profiling and tuning, Profiling and tuning
@subsection Using profiler
@c NODE プロファイラを使う

As of 0.8.4, Gauche has a built-in profiler.  It is still experimental
quality and only be tested on Linux.  It isn't available for all
platforms.   It works only in single-thread applications for now.

To use the profiler non-interactively, give @code{-ptime}
command-line option to gosh.

@example
% gosh -ptime your-script.scm
@end example

After the execution of @file{your-script.scm} is completed, Gauche prints
out the table of functions with its call count and its consumed time,
sorted by the total consumed time.

@smallexample
Profiler statistics (total 1457 samples, 14.57 seconds)
                                                    num    time/    total
Name                                                calls  call(ms) samples
---------------------------------------------------+------+-------+-----------
combinations*                                       237351  0.0142   337( 23%)
(lset-difference #f)                               1281837  0.0020   256( 17%)
(make-anchor make-anchor)                          3950793  0.0005   198( 13%)
member                                             4627246  0.0004   190( 13%)
filter                                              273238  0.0030    81(  5%)
every                                              1315131  0.0004    59(  4%)
(lset-difference #f #f)                            1281837  0.0004    54(  3%)
(make-entry make-entry)                             730916  0.0005    40(  2%)
(clear? #f)                                         730884  0.0005    33(  2%)
(initialize #f)                                     599292  0.0005    32(  2%)
fold                                                237307  0.0013    30(  2%)
acons                                               806406  0.0004    29(  1%)
clear?                                               33294  0.0084    28(  1%)
(combinations* #f)                                  805504  0.0002    15(  1%)
(make-exit make-exit)                               730884  0.0002    15(  1%)
lset-difference                                     237318  0.0006    15(  1%)
reverse!                                            475900  0.0001     6(  0%)
(fold <top> <top> <list>)                           237323  0.0003     6(  0%)
procedure?                                          238723  0.0002     4(  0%)
pair?                                               237307  0.0001     3(  0%)
 :
 :
@end smallexample

Note that the time profiler uses statistic sampling.  Every 10ms
the profiler interrupts the process and records the function that is
executed then.   Compared to the individual execution time per
function call, which is the order of nanoseconds, this sampling rate
is very sparse.  However, if we run the program long enough,
we can expect the distribution of samples per each function
approximately reflects the distribution of time spent in each function.

Keep in mind that the number is only approximation; the number
of sample counts for a function may easily vary if the program deals
with different data sets.   It should also be noted that, for now, GC
time is included in the function in which GC is triggered.
This sometimes causes a less important function to "float up" to
near-top of the list.
To know the general pattern, it is a good custom to run the program
with several different data sets.

On the other hand, the call count is accurate since Gauche actually
counts each call.

Because all functions are basically anonymous in Scheme, the 'name' field of
the profiler result is only a hint.  The functions bound at toplevel
is generally printed with the global variable name it is bound at
the first time.  Internal functions are printed as a list of names,
reflecting the nesting of functions.  Methods are also printed as a
list of the name and specializers.

The profiler has its own overhead; generally the total
process time will increase 20-30%.
If you want to turn on the profiler selectively, or you're running
a non-stop server program and want to obtain the statistics without
exiting the server, you can call the profiler API from your program;
see @ref{Profiler API}, for the details.

@node Performance tips,  , Using profiler, Profiling and tuning
@subsection Performance tips
@c NODE パフォーマンスに関するヒント

Don't guess, just benchmark.  It is the first rule of
performance tuning.  Especially for the higher-level languages
like Scheme, what impacts on performance greatly depends on
the implementation.  Certain operations that are very cheap
on an implementation may be costly on others.
Gauche has such implementation-specific characteristics, and
to know some of them would help to see what to look out in
the benchmark results.

"80% of execution time is spent in 20% of the code" is another
old saying.  Don't obscure your code by "potential" optimization
that has little impact on the actual execution.  We describe some
tips below, but it doesn't mean you need to watch them all the time.
It is better to keep most of the code clean and easy to understand,
and only do tricks on the innermost loop.

@strong{Ports}: To satisfy the specification of SRFI-18 (Threading),
every call to I/O primitives of Gauche locks the port.
This overhead may be visible if the application does a lot of I/O
with smaller units (e.g. every bytes).   The primitives that deals
with larger unit, such as @code{read} and @code{read-uvector}, are less
problematic, since usually they just lock the port once per call and do
all the low-level I/O without the lock overhead.
(Note: this doesn't mean those primitives @emph{guarantee}
to lock the port throughout the execution of the function;
furthermore, the port locking feature is optimized for the case
that port accesses rarely collide.  If you know it is possible that
more than one threads read from or write to the same port, it is
your responsibility to use mutex explicitly to avoid the collision.)

If you find out the locking is indeed a bottleneck, there are couple
of things you can consider: (1) Try using the larger-unit primitives,
instead of calling the smaller-unit ones.  (2) Use @code{with-port-locking}
(see @ref{Port and threads}) to lock the port in larger context.

@strong{Strings}: Because of the multibyte strings, two operations
are particularly heavy in Gauche: string mutation and indexed string access.
It is a design choice; we encourage the programming style that
avoids those operations.  When you sequentially access the string,
string ports (see @ref{String ports}) provide a cleaner and
more efficient way.
When you search and retrieve a substring, there are various
higher-level primitives are provided (see @ref{String utilities},
@ref{Regular expressions}, and @ref{String library}, for example).
If you're using strings to represent an octet sequence, use uniform
vectors (see @ref{Uniform vectors}) instead.

@strong{Deep recursion}: Gauche's VM uses a stack for efficient
local frame allocation.  If recursion goes very deep (depending on
the code, but usually several hundreds to a thousand), the stack
overflows and Gauche moves the content of the stack into the heap.
This incurs some overhead.  If you observe a performance degradation
beyond a certain amount of data, check out this possibility.

@strong{Generic functions}: Because of its dynamic nature, generic
function calls are slower than procedure calls.  Not only because
of the runtime dispatch overhead, but also because Gauche's compile-time
optimizer can't do much optimization for generic function calls.
You don't need to avoid generic functions because of performance
reasons in general, but if you do find single function call consuming
a large part of execution time and it is calling a generic
function in its inner loop---then it may be worth to modify it.

@strong{Redefining builtin functions}: Gauche inlines some builtin
functions if they are not redefined.  Although sometimes it is useful
to redefine basic functions, you may want to limit the effect.
For example, put redefined functions in a separate module and
use the module in the code that absolutely needs those functions
replaced.

@strong{Closure creation}: When you create a closure, its closing environment
is copied to the heap.  This overhead is small, but it still may be
visible when a closure is created within an innermost loop that is
called millions of times.   If you suspect this is a problem,
try disassemble the function.   Gauche's compiler uses some basic
techniques of closure analysis to avoid creating closures for
typical cases, in which case you see the local function's bodies
are inlined.  If you see a @code{CLOSURE} instruction, though, it
means a closure is created.

This list isn't complete, and may change when Gauche's implementation
is improved, so don't take this as fixed features.
We'll adjust it occasionally.

@c ----------------------------------------------------------------------
@node Writing Gauche modules, Using extension packages, Profiling and tuning, Programming in Gauche
@section Writing Gauche modules
@c NODE Gaucheのモジュールを書く

Gauche's libraries are organized by modules.   Although Gauche
can load any valid Scheme programs, there is a convention that
Gauche's libraries follow.    When you write a chunk of Scheme
code for Gauche, it is convenient to make it a module,
so that it can be shared and/or reused.

Usually a module is contained in a file, but you can make
a multi-file module.
First I explain the structure of a single-file module.
The following template is the convention used in Gauche's libraries.

@example
;; Define the module interface
(define-module foo
  (use xxx)
  (use yyy)
  (export foo1 foo2 foo3)
  )
;; Enter the module
(select-module foo)

@dots{} module body @dots{}

@end example

This file must be saved as ``foo.scm'' in some directory in the
@code{*load-path*}.

The @code{define-module} form creates a module @code{foo}.
It also loads and imports some other modules by `@code{use}' macros,
and declares which symbols the @code{foo} module exports, by `@code{export}'
syntax.
(See section @ref{Defining and selecting modules}, for detailed specification of those
syntaxes).

Those @code{use} forms or @code{export} forms are not required to appear
in the @code{define-module} form, but it is a good convention to keep
them in there at the head of the file so that it is visually recognizable
which modules @code{foo} depends and which symbols it exports.

The second form, `@code{select-module}',
specifies the rest of the file is evaluated in the
module @code{foo} you just defined.   Again, this is just a
convention; you can write entire module body inside @code{define-module}.
However, I think it is error-prone, for the closing parenthesis
can be easily forgotten or the automatic indentation mechanism of
editor will be confused.

After @code{select-module} you can write whatever Scheme expression.
It is evaluated in the selected module, @code{foo}.   Only the bindings
of the exported symbols will be directly accessible from outside.

So, that's it.   Other programs can use your module by just saying
`@code{(use foo)}'.   If you want to make your module available on your site,
you can put it to the site library location, which can be obtained by
@example
(gauche-site-library-directory)
@end example
in gosh, or
@example
gauche-config --sitelibdir
@end example
from shell.

If you feel like to conserve global module name space, you can organize
modules hierarchically.   Some Gauche libraries already does so.
@xref{Library modules - Overview}, for examples.
For example, @code{text.tr} module is implemented in ``text/tr.scm'' file.
Note that the pathname separator `/' in the file becomes a period in the
module name.

@c ----------------------------------------------------------------------
@node Using extension packages, Building standalone executables, Writing Gauche modules, Programming in Gauche
@section Using extension packages
@c NODE 拡張パッケージの使用

@subheading Building and installing packages

Gauche comes with some amount of libraries, but they aren't
enough at all to use Gauche in the production environment.
There are number of additional libraries available.   We call them
@emph{extension packages}, or simply packages.  Each package
usually provides one or more modules that adds extra
functionality.   Most of the packages provide
binding to other C libraries, such as graphics libraries
or database clients.   If the package has some C code,
it is likely that you need to compile it on your machine with
the installed Gauche system.

Usually a package is in the form of compressed tarball, and the standard
"ungzip + untar + configure + make + make install" sequence does the job.
Read the package's document, for you may be able to tailor
the library for your own needs by giving command-line options
to the @code{configure} script.

From Gauche 0.8, an utility script called @code{gauche-package} is
installed for the convenience.  It automates the build and install
process of packages.

Suppose you have downloaded a package @file{Package-1.0.tar.gz}.
If the package follows the convention, all you have to do is
to type this:

@example
$ gauche-package install Package-1.0.tar.gz
@end example

It ungzips and untars the package, @code{cd} into the @file{Package-1.0}
subdirectory, run configure, make, and make install.
By default, @code{gauche-package} untars the tarball in the current
working directory.  You can change it by a customization file; see below.

If you need a special privilege to install the files, you can
use @code{--install-as} option which runs @code{make install} part via
the @code{sudo} program.

@example
$ gauche-package install --install-as=root Package-1.0.tar.gz
@end example

If it doesn't work for you, you can just build the package
by @code{gauche-package build Package-1.0.tar.gz}, then
manually cd to the @file{Package-1.0} directory and run
@code{make install}.

You can give configuration options via @code{-C} or @code{--configure-options}
command-line argument, like this:

@example
$ gauche-package install -C "--prefix=/usr/local" Package-1.0.tar.gz
@end example

If the package has adopted the new package description file,
it can remember the configuration options you have specified, and
it will automatically reuse them when you install the package
again.  (If you're a package developer, check out
@file{examples/spigot/README} file in the Gauche source tree
to see how to cooperate with Gauche's package management system.)

If you don't have a tarball in your local directory, but you know
the URL where you can download it, you can directly give the URL
to @code{gauche-package}.  It understands @code{http} and @code{ftp},
and uses either @code{wget} or @code{ncftpget} to download the tarball,
then runs configure and make.

@example
$ gauche-package install http://www.example.com/Package-1.0.tar.gz
@end example

@subheading Customizing @code{gauche-package}

The @code{gauche-package} program reads @file{~/.gauche-package} if
it exists.  It must contain an associative list of parameters.
It may look like this:

@example
(
 (build-dir . "/home/shiro/tmp")
 (gzip      . "/usr/local/bin/gzip")
 (bzip2     . "/usr/local/bin/bzip2")
 (tar       . "/usr/local/bin/gtar")
)
@end example

The following is a list of recognized parameters.
If the program isn't given in the configuration file, @code{gauche-package}
searches @code{PATH} to find one.

@table @code
@item build-dir
A directory where the tarball is extracted.  If URL is given,
the downloaded file is also placed in this directory.
@item bzip2
Path to the program @code{bzip2}.
@item cat
Path to the program @code{cat}.
@item make
Path to the program @code{make}.
@item ncftpget
Path to the program @code{ncftpget}.
@item rm
Path to the program @code{rm}.
@item sudo
Path to the program @code{sudo}.
@item tar
Path to the program @code{tar}.
@item wget
Path to the program @code{wget}.
@end table

@c ----------------------------------------------------------------------
@node Building standalone executables,  , Using extension packages, Programming in Gauche
@section Building standalone executables
@c NODE スタンドアロン実行可能ファイルの作成

When you want to distribute your Gauche scripts or applications,
the users need to install Gauche runtime on their machine.
Although it is always the case for any language implementations---you need
Java runtime to run Java applications, or C runtime to run
C applications---it may be an extra effort to ask users to install
not-so-standard language runtimes.

To ease distribution of Gauche applications, you can create a
stand-alone executable.  It statically links entire Gauche system
so that it runs by just copying the executable file.

@subheading Quick recipe

To generate a standalone executable, just give your script file
to the @file{build-standalone} script, which is installed as a
part of Gauche.

@example
gosh build-standalone yourscript.scm
@end example

It will create an executable file @code{yourscript} (or @code{yourscript.exe}
on Windows) in the current directory.

To specify the output name different from the script name,
give @code{-o} option:

@example
gosh build-standalone -o yourcommand yourscript.scm
@end example

When your script needs supporting library files, you should list
those files as well:

@example
gosh build-standalone yourscript.scm lib/library1.scm lib/library2.scm
@end example

The library file paths need to be relative to the respective load path.
See the explanation of @code{-I} option below.

@subheading Catches

There are a few things you should be aware of.

@itemize
@item
The size of the binary tend to be large, since it contains the entire
Gauche system regardless of whether your application use it or not.
You can strip down the size if you need to, but you need to rebuild
Gauche library to do so.  See @file{doc/HOWTO-standalone.txt} in the
source tree for the details.

@item
The generated binary still depends on external dynamically linked
libraries, such as libpthread.  The exact dependency may differ
how Gauche is configured, and can be checked
by running system-provided tools, 
such as @code{ldd} on most Unix systems and MinGW or @code{otool -L} on OSX,
on the generated standalone binaries.
You may want to ensure the users have required libraries.

@item
Currently we don't yet have a convenient way to statically link
extension libraries.  We're working on it.

@item
If Gauche is configured to use gdbm, it is linked to the standalone binary
by default, hence the binary itself is covered by GPL.  In case if you
need to distribute binaries under BSD license, you need to give
@code{-D GAUCHE_STATIC_EXCLUDE_GDBM} flag to @code{build-standalone}.
It makes @code{build-standalone} not to link gdbm (and your script won't
be able to use it).

@item
If you build Gauche with mbedTLS support (if you have libmbedtls on
your machine, Gauche include its support by default), the resulting standalone
binary also depends on libmbedtls DSO files.  If you're not sure mbedTLS
DSO files are available on target machines, you can exclude 
@code{rfc.tls.mbed} module by giving 
@code{-D GAUCHE_STATIC_EXCLUDE_MBED} flag to @code{build-standalone}.

@end itemize

@subheading Using build-standalone

@deftp {Program} {gosh build-standalone} [options] script-file [library-file @dots{}]
Create a stand-alone binary to execute a Gauche program in @var{script-file}.
It is executed as if it is run as @code{gosh script-file}, with a few
differences.

The main thing is that since @var{script-file} is no longer
loaded from file, code that references paths relative to @var{script-file} won't
work.  One example is @code{(add-load-path dir :relative)}
(@pxref{Loading Scheme file}).  Auxiliary library files required by
@var{script-file} must be explicitly
listed as @var{library-file} @dots{}, so that
they are bundled together into the executable.
@end deftp

The following command-line options are recognized.

@deftp {Command Option} -o outfile
Specifies output executable filename.  When omitted, the basename of
@var{script-file} without extension is used.
(Or, on Windows, swapping extension with @code{.exe}).
@end deftp

@deftp {Command Option} -D var[=val]
Add C preprocessor definitions while compiling the generated C code.
An important use case of this option is to exclude gdbm dependency
from the generated binaries, by specifying
@code{-D GAUCHE_STATIC_EXCLUDE_GDBM}.  Note that you need a whitespace
between @code{-D} and @var{var}.

This option can be specified multiple times.
@end deftp

@deftp {Command Option} -I load-path
Specifies the load path where @var{library-file} @dots{} are searched.
The names given to @var{library-file} must match how they are @code{load}ed
or @code{use}d.  If such paths are not relative to the directory
you run @code{build-standalone}, you have to tell where to find
those libraries with this option.

For example, suppose you have this structure:

@example
project/src/
    +----- main.scm 
    |          (use myscript.util)
    +----- myscript/util.scm
               (define-module myscript.util ...)
@end example

If you run @code{build-standalone} in the directory as @file{src},
you can just say this:

@example
gosh build-standalone main.scm myscript/util.scm
@end example

But if you run it under @file{project}, you need to say this:

@example
gosh build-standalone -I src src/main.scm myscript/util.scm
@end example

Another example; you have a separate library directory:

@example
project/
    +----- src/main.scm 
    |          (use myscript.util)
    +----- lib/myscript/util.scm
               (define-module myscript.util ...)
@end example

If you run @code{build-standalone} in @file{src}, you say this:

@example
gosh build-standalone -I ../lib main.scm myscript/util.scm
@end example

Or, if you run it in @file{project}, you say this:

@example
gosh build-standalone -I lib src/main.scm myscript/util.scm
@end example

This option can be specified multiple times.
Note that a whitespace is required between @code{-I} and @var{load-path}.
@end deftp

@deftp {Command Option} --header-dir dir
@deftpx {Command Option} --library-dir dir
These tells @code{build-standalone} where to find Gauche C headers
and static libraries.

If you've installed Gauche on your system, @code{build-standalone}
automatically finds these from the installed directory and you don't
need to worry about them.   Use these option only when
you need to use Gauche runtime that's not installed.
@end deftp

@c Local variables:
@c mode: texinfo
@c coding: utf-8
@c end:
@node Core syntax, Macros, Programming in Gauche, Top
@chapter Core syntax
@c NODE 基本的な構文

@c ----------------------------------------------------------------------
@menu
* Lexical structure::
* Literals::
* Making procedures::
* Assignments::
* Conditionals::
* Binding constructs::
* Sequencing::
* Iteration::
* Quasiquotation::
* Definitions::
* Inclusions::
* Feature conditional::
* Modules::
@end menu

@node Lexical structure, Literals, Core syntax, Core syntax
@section Lexical structure
@c NODE 字句構造

Gauche extends R7RS Scheme lexical parser in some ways.
Besides, because of historical reasons, a few of the default
lexical syntax may conflict R7RS specification.
You can set a reader mode to make it R7RS compliant.

@table @emph
@item Hash-bang directives 
Tokens beginning with @code{#!} may have special meanings to
the reader.  R7RS defines two of such directives---@code{#!fold-case}
and @code{#!no-fold-case}, which switches whether symbols
are read in case-folding or non-case-folding mode, respectively.

@pxref{Hash-bang token} below, for all the directives
Gauche has.

@item Square brackets
@lxindex [
Gauche adopts the R6RS syntax that regards @code{[]} the same
as @code{()}.  Both kind of parentheses are equivalent,
but the kind of corresponding open and close parentheses must match.
Some seasoned Lisper may frown on them, but it
helps visually distinguish different roles of parentheses.

A general convention is to use @code{[]} for groupings other than
function and macro application.  If such grouping nests, however, use @code{()}
for outer groupings.  Examples:

@example
(cond [(test1 x) (y z)]
      [(test2 x) (s t)]
      [else (u v)])

(let ([x (foo a b)]
      [y (bar c d)])
  (baz x y))
@end example

It is purely optional, so you don't need to use them if you don't like them.
R7RS doesn't adopt this syntax and leaves @code{[]} for extensions,
so it is safe to stick to @code{()} in portable R7RS programs.
(If the reader is in @code{strict-r7} mode, an error is signalled
when @code{[]} is used.  @xref{Reader lexical mode}, for the details.)

Scheme-specific modes of some editors (e.g. Quack on Emacs) allows
you to type just @code{)} and inserts either @code{]} or @code{)}
depending on which kind parenthesis it is closing.  We recommend
using such modes if you use this convention.

@item Symbol names
Symbol names are case sensitive by default (@pxref{Case-sensitivity}).
Symbol name can begin with digits, '@code{+}' or '@code{-}', as long as
the entire token doesn't consist valid number syntax.
Other weird characters can be included in a symbol name by surrounding
it with '|', e.g. '@code{|this is a symbol|}'.
@xref{Symbols}, for details.

@item Numeric literals
Either integral part or fraction part of inexact real numbers can be omitted
if it is zero, i.e. @code{30.}, @code{.25}, @code{-.4} are read as
real numbers.
The number reader recognizes '@code{#}' as insignificant digits.
Complex numbers can be written both in the rectangular format
(e.g. @code{1+0.3i}) and in the polar format (e.g. @code{3.0@@1.57}).
Inexact real numbers include
the positive infinity, the negative infinity, and NaN,
which are represented as @code{+inf.0}, @code{-inf.0} and @code{+nan.0},
respectively.  (@code{-nan.0} is also read as NaN.)

As an extension of Gauche, a character @code{_} can be inserted
in or around a sequence of digits in number literals, as far as
the literal is explicitly prefixed (@code{#e}, @code{#x}, etc).
Those @code{_}'s are just ignored.
It is to improve readability, e.g. @code{#b1100_1010_1111_1110}.

Gauche also adopts Common-Lisp style radix prefixed numeric literals,
e.g. @code{#3r120} (@code{120} in base-3, 15 in decimal).  Radix between
2 and 36 are recognized; alphabetic letters @code{a-zA-Z}
are used beyond decimal.

For the polar notation of complex numbers, Gauche allows the suffix @code{pi}
to denote the phase by multiples of pi.  The Scheme syntax use radians for
the phase, but you can only approximate pi with the floating point numbers,
so it can't represent round numbers except zero angle.
@example
gosh> 2@@3.141592653589793
-2.0+2.4492935982947064e-16i
@end example
With the @code{pi} suffix, you can get a round numbers.
@example
gosh> 2@@1pi
-2.0
gosh> 2@@0.5pi
0.0+2.0i
gosh> 2@@-0.5pi
0.0-2.0i
@end example

@item Hex character escapes
@lxindex \x
You can denote a character using hexadecimal
notation of the character code in some literals; specifically,
character literals, charcter set literals, string literals,
symbols, regular expression literals.

R7RS adopted a hex escape notation @code{\xNNNN;} for strings
and symbols surrounded by vertical bars, and @code{#\xNNNN} for
characters.  The number of digits is variable, and
the character code is Unicode codepoint.

Gauche had been using two types of escapes; @code{\u}
and @code{\x}.  In general, @code{u} is for Unicode
codepoint, while @code{x} is for the character code in the internal
encoding.  Besides, except character literals, we used fixed number
of digits, instead of using the terminator @code{;} as in R7RS.

Since 0.9.4, we interpret @code{\x}-escape as R7RS whenever if
it consists a valid R7RS hex-escape, and if not,
try to interpret it as legacy Gauche hex-escape.

Although rarely, there are cases that can interpreted
both in R7RS syntax and legacy Gauche syntax, but yielding different
characters.  Reading legacy files with such literals in
the current Gauche may cause unexpected behavior.
You can switch the reader mode so that it becomes
backward-compatible.  @xref{Reader lexical mode}, for the details.

@item Extended sharp syntax
Many more special tokens begins with '@code{#}' are defined.
See the table below.
@end table

@menu
* Sharp syntax::
* Hash-bang token::
@end menu

@node Sharp syntax, Hash-bang token, Lexical structure, Lexical structure
@subsection Sharp syntax
@c NODE #構文

The table below lists sharp-syntaxes.

@multitable {aaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
@item @code{#!}
 @tab [R6RS][R7RS][SRFI-22] It is either a beginning of an interpreter line
      (shebang) of a script, or a special token that affects the mode
      of the reader.  See `hash-bang token' section below.
@item @code{#"}
 @tab Introduces an interpolated string.  @xref{String interpolation}.
@item @code{##}, @code{#$}, @code{#%}, @code{#&}, @code{#'}
 @tab Unused.
@item @code{#(}
 @tab [R7RS] Introduces a vector.
@item @code{#)}
 @tab Unused.
@item @code{#*}
 @tab Bitvector or an incomplete string.  @xref{Strings}.
@item @code{#+}
 @tab Unused.
@item @code{#,}
 @tab [SRFI-10] Introduces reader constructor syntax.
@item @code{#-}, @code{#.}
 @tab Unused.
@item @code{#/}
 @tab Introduces a literal regular expression.  @xref{Regular expressions}.
@item @code{#0} @dots{} @code{#9}
 @tab @code{#@var{n}#}, @code{#@var{n}=}: [SRFI-38] Shared substructure definition and reference.@*
@code{#@var{n}R}, @code{#@var{n}r}: Radix prefixed numeric literals.
@item @code{#:}
 @tab Uninterned symbol.  @xref{Symbols}.
@item @code{#;}
 @tab [SRFI-62] S-expression comment.  Reads next one S-expression and
      discard it.
@item @code{#<}
 @tab Introduces an unreadable object.
@item @code{#=}, @code{#>}
 @tab Unused.
@item @code{#?}
 @tab Introduces debug macros.  @xref{Debugging}.
@item @code{#@@}
 @tab Unused.
@item @code{#a}
 @tab Unused.
@item @code{#b}
 @tab [R7RS] Binary number prefix.
@item @code{#c}
 @tab Unused.
@item @code{#d}
 @tab [R7RS] Decimal number prefix.
@item @code{#e}
 @tab [R7RS] Exact number prefix.
@item @code{#f}
 @tab [R7RS] Boolean false, or
      introducing R7RS uniform vector.  @xref{Uniform vectors}.
      R7RS defines both @code{#f} and @code{#false} as a boolean false value.
@item @code{#g}, @code{#h}
 @tab Unused.
@item @code{#i}
 @tab [R7RS] Inexact number prefix.
@item @code{#j}, @code{#k}, @code{#l}, @code{#m}, @code{#n}
 @tab Unused.
@item @code{#o}
 @tab [R7RS] Octal number prefix.
@item @code{#p}, @code{#q}, @code{#r}
 @tab Unused.
@item @code{#s}
 @tab [R7RS vector.@@] introducing R7RS uniform vector.  @xref{Uniform vectors}.
@item @code{#t}
 @tab [R7RS] Boolean true.  R7RS defines @code{#t} and @code{#true}
      as a boolean true value.
@item @code{#u}
 @tab [R7RS vector.@@] introducing R7RS uniform vector.  @xref{Uniform vectors}.
 R7RS uses @code{#u8} prefix for bytevectors, which is compatible to
 @code{u8} uniform vectors.
@item @code{#v}, @code{#w}
 @tab Unused.
@item @code{#x}
 @tab [R7RS] Hexadecimal number prefix.
@item @code{#y}, @code{#z}
 @tab Unused.
@item @code{#[}
 @tab Introduces a literal character set.  @xref{Character sets}.
@item @code{#\}
 @tab [R7RS] Introduces a literal character.  @xref{Characters}.
@item @code{#]}, @code{#^}, @code{#_}
 @tab Unused.
@item @code{#`}
 @tab Legacy syntax for string interpolation, superseded by @code{#"}.
@item @code{#@{}
 @tab Unused.
@item @code{#|}
 @tab [SRFI-30] Introduces a block comment.  Comment ends by matching '@code{|#}'.
@item @code{#@}}, @code{#~}
 @tab Unused.
@end multitable

@menu
* Hash-bang token::             
@end menu

@node Hash-bang token,  , Sharp syntax, Lexical structure
@subsection Hash-bang token
@c NODE Hash-bangトークン
@lxindex #!

A character sequence @code{#!} has two completely different
semantics, depending on how and where it occurs.

If a file begins with @code{#!/} or @code{#! } (hash, bang, and a
space), then the reader assumes it is an interpreter line (shebang) of
a script and ignores the rest of characters until the end of line.
(Actually the source doesn't need to be a file.  The reader checks
whether it is the beginning of a port.)

Other than the above case, @code{#!@var{identifier}} is read as
a token with special meanings.  This kind token can be a special
directive for the reader, instead of read as a datum.

By default, the following tokens are recognized.

@table @code
@item #!fold-case
@itemx #!no-fold-case
Switches the reader's case sensitivity;
@code{#!fold-case} makes the reader case insensitive, and
@code{#!no-fold-case} makes it case sensitive.  (Also see
@ref{Case-sensitivity}).
@item #!r6rs
This token is introduced in R6RS and used to indicate the
program strictly conforms R6RS.  Gauche doesn't conform R6RS, but
currently it just issues warning when it sees @code{#!r6rs} token, and
it keeps reading on.
@item #!r7rs
Make the reader @code{strict-r7} mode, that complies R7RS.
@xref{Reader lexical mode}, for the details.
@c TODO: Describe concrete details
@item #!gauche-legacy
Make the reader @code{legacy} mode, that is
compatible to Gauche 0.9.3 and before.
@xref{Reader lexical mode}, for the details.
@end table

@c ----------------------------------------------------------------------
@node Literals, Making procedures, Lexical structure, Core syntax
@section Literals
@c NODE リテラル

@defspec quote datum
[R7RS base]
Evaluates to @var{datum}.
@example
(quote x) @result{} x
(quote (1 2 3)) @result{} (1 2 3)
@end example
@end defspec

@deftp {Reader Syntax} @code{'@var{datum}}
@lxindex '
[R7RS]
Equivalent to @code{(quote datum)}.
@example
'x @result{} x
'(1 2 3) @result{} (1 2 3)
@end example
@end deftp

@emph{Note:}  Literals are immutable.  You'll get an error
if you try to change, for example, a quoted pair with @code{set-car!}
or a literal string with @code{string-set!}.
Mutability may be managed differently for each type, so some object
may not raise an error even if it appears in a part of literals
(it is often the case with user-defined class with read-time constructor,
@pxref{Read-time constructor}.  However, if you ever modify a literal
data, it is not guaranteed that the program runs correctly.

@c ----------------------------------------------------------------------
@node Making procedures, Assignments, Literals, Core syntax
@section Making procedures
@c NODE  手続きを作る

@defspec lambda formals body @dots{}
@defspecx ^ formals body @dots{}
[R7RS+]
Evaluates to a procedure.  The environment in effect when this expression
is evaluated is stored in the procedure.   When the procedure
is called, @var{body} is evaluated sequentially in the
stored environment extended by the bindings of the formal arguments,
and returns the value(s) of the last expression in the body.

@code{^} is a concise alias of @code{lambda}.  It is Gauche's extension.

@example
(lambda (a b) (+ a b))
  @result{} @r{procedure that adds two arguments}

((lambda (a b) (+ a b)) 1 2) @result{} 3

((^(a b) (+ a b)) 1 2)       @result{} 3
@end example

Gauche also extends R7RS @code{lambda} to take extended syntax in
@var{formals} to specify optional and keyword arguments easily.
The same functionality can be written in pure R7RS, with parsing
variable-length arguments explicitly, but the code tends
to be longer and verbose.   It is recommended to use extended syntax
unless you're writing portable code.

@var{Formals} should have one of the following forms:
@itemize @bullet
@item
@code{(@var{variable} @dots{})} :
The procedure takes a fixed number of arguments.
The actual arguments are bound to the corresponding variables.

@example
((lambda (a) a) 1)    @result{} 1

((lambda (a) a) 1 2)  @result{} @i{error - wrong number of arguments}
@end example

@item
@code{@var{variable}} :
The procedure takes any number of arguments.
The actual arguments are collected to form a new list and bound to
the variable.

@example
((lambda a a) 1 2 3)  @result{} (1 2 3)
@end example

@item
@code{(@var{variable_0} @dots{} @var{variable_N-1} . @var{variable_N})} :
The procedure takes at least @var{N} arguments.  The actual arguments
up to @var{N} is bound to the corresponding variables.
If more than @var{N} arguments are given, the rest arguments are
collected to form a new list and bound to @var{variable_N}.

@example
((lambda (a b . c) (print "a=" a " b=" b " c=" c)) 1 2 3 4 5)
 @result{} @r{prints} a=1 b=2 c=(3 4 5)
@end example

@item
@code{(@var{variable} @dots{} @var{extended-spec} @dots{})} :
Extended argument specification.  Zero or more variables that
specifies required formal arguments, followed
by an @emph{extended spec}, a list beginning with
a keyword @code{:optional}, @code{:key} or @code{:rest}.

The @var{extended-spec} part consists of the optional argument spec,
the keyword argument spec and the rest argument spec.  They can
appear in any combinations.

@table @code
@item :optional @var{optspec} @dots{}
Specifies optional arguments.  Each @var{optspec} can be either
one of the following forms:

@example
@var{variable}
(@var{variable} @var{init-expr})
@end example

The @var{variable} names the formal argument, which is bound to
the value of the actual argument if given, or the value of
the expression @var{init-expr} otherwise.   If @var{optspec} is just
a variable, and the actual argument is not given to it, then
@var{variable} will be bound to @code{#<undef>} (@pxref{Undefined values}).

The expression @var{init-expr} is only evaluated if the actual
argument for @var{variable} is not given.  The scope in which
@var{init-expr} is evaluated includes the preceding formal arguments.

@example
((lambda (a b :optional (c (+ a b))) (list a b c))
 1 2)    @result{} (1 2 3)

((lambda (a b :optional (c (+ a b))) (list a b c))
 1 2 -1) @result{} (1 2 -1)

((lambda (a b :optional c) (list a b c))
 1 2)    @result{} (1 2 #<undef>)

((lambda (:optional (a 0) (b (+ a 1))) (list a b))
 )       @result{} (0 1)
@end example

The procedure signals an error if more actual arguments than
the number of required and optional arguments are given, unless it also has
@code{:key} or @code{:rest} argument spec.

@example
((lambda (:optional a b) (list a b)) 1 2 3)
 @result{} @i{error - too many arguments}

((lambda (:optional a b :rest r) (list a b r)) 1 2 3)
 @result{} (1 2 (3))
@end example

@item :key @var{keyspec} @dots{} [:allow-other-keys [@var{variable}]]
Specifies keyword arguments.  Each @var{keyspec} can be
either one of the following forms.

@example
@var{variable}
(@var{variable} @var{init-expr})
((@var{keyword} @var{variable}) @var{init-expr})
@end example

The @var{variable} names the formal argument, which is bound to the
actual argument given with the keyword of the same name as @var{variable}.
When the actual argument is not given, @var{init-expr} is evaluated
and the result is bound to @var{variable} in the second and third form,
or @code{#<undef>} is bound in the first form.

@example
(define f (lambda (a :key (b (+ a 1)) (c (+ b 1)))
            (list a b c)))

(f 10)            @result{} (10 11 12)
(f 10 :b 4)       @result{} (10 4 5)
(f 10 :c 8)       @result{} (10 11 8)
(f 10 :c 1 :b 3)  @result{} (10 3 1)
@end example

With the third form you can name the formal argument differently from
the keyword to specify the argument.

@example
((lambda (:key ((:aa a) -1)) a) :aa 2)
  @result{} 2
@end example

By default, the procedure with keyword argument spec raises an
error if a keyword argument with an unrecognized keyword is given.
Giving @code{:allow-other-keys} in the formals suppresses this behavior.
If you give @var{variable} after @code{:allow-other-keys},
the list of unrecognized keywords and their arguments are bound to it.
Again, see the example below will help to understand the behavior.

@example
((lambda (:key a) a)
 :a 1 :b 2)  @result{} @i{error - unknown keyword :b}

((lambda (:key a :allow-other-keys) a)
 :a 1 :b 2)  @result{} 1

((lambda (:key a :allow-other-keys z) (list a z))
 :a 1 :b 2)  @result{} (1 (:b 2))
@end example

When used with @code{:optional} argument spec, the keyword arguments
are searched after all the optional arguments are bound.

@example
((lambda (:optional a b :key c) (list a b c))
 1 2 :c 3)  @result{} (1 2 3)

((lambda (:optional a b :key c) (list a b c))
 :c 3)      @result{} (:c 3 #<undef>)

((lambda (:optional a b :key c) (list a b c))
 1 :c 3)     @result{} @i{error - keyword list not even}
@end example


@item :rest @var{variable}

Specifies the rest argument.   If specified without @code{:optional}
argument spec, a list of remaining arguments after required arguments are
taken is bound to @var{variable}.  If specified with @code{:optional}
argument spec, the actual arguments are first bound to required and
all optional arguments, and the remaining arguments are bound to @var{variable}.

@example
((lambda (a b :rest z) (list a b z))
 1 2 3 4 5)  @result{} (1 2 (3 4 5))

((lambda (a b :optional c d :rest z) (list a b c d z))
 1 2 3 4 5)  @result{} (1 2 3 4 (5))

((lambda (a b :optional c d :rest z) (list a b c d z))
 1 2 3)      @result{} (1 2 3 #<undef> ())
@end example

When the rest argument spec is used with the keyword argument spec,
both accesses the same list of actual argument---the remaining arguments
after required and optional arguments are taken.

@example
((lambda (:optional a :rest r :key k) (list a r k))
 1 :k 3)  @result{} (1 (:k 3) 3)
@end example

@end table

See also @code{let-optionals*}, @code{let-keywords} and
@code{let-keywords*} macros in @ref{Optional argument parsing}
for an alternative way to receive optional/keyword arguments
within the spec of R7RS.

@end itemize

@end defspec

@defmac ^c body @dots{}
@findex ^_
@findex ^a
@findex ^b
@findex ^d
@findex ^e
@findex ^f
@findex ^g
@findex ^h
@findex ^i
@findex ^j
@findex ^k
@findex ^l
@findex ^m
@findex ^n
@findex ^o
@findex ^p
@findex ^q
@findex ^r
@findex ^s
@findex ^t
@findex ^u
@findex ^v
@findex ^w
@findex ^x
@findex ^y
@findex ^z
A shorthand notation of @code{(lambda (@var{c}) @var{body} @dots{})}.
where @var{c} can be any character in @code{#[_a-z]}.

@example
(map (^x (* x x)) '(1 2 3 4 5)) @result{} (1 4 9 16 25)
@end example
@end defmac


@defmac cut expr-or-slot expr-or-slot2 @dots{}
@defmacx cute expr-or-slot expr-or-slot2 @dots{}
[SRFI-26]
Convenience macros to notate a procedure compactly.
This form can be used to realize partial application,
a.k.a sectioning or projection.

Each @var{expr-or-slot} must be either an expression or a symbol @code{<>},
indicating a 'slot'.
The last @var{expr-or-slot} can be a symbol @code{<...>},
indicating a 'rest-slot'.
@code{Cut} expands into a @code{lambda} form that takes as many arguments
as the number of slots in the given form, and
whose body is an expression
@example
  (@var{expr-or-slot} @var{expr-or-slot2} @dots{})
@end example
where each occurrence of @code{<>} is replaced to the corresponding
argument.
In case there is a rest-slot symbol, the resulting procedure is also
of variable arity, and all the extra arguments are passed
to the call of @var{expr-or-slot}.  See the fourth example below.

@example
(cut cons (+ a 1) <>)  @equiv{} (lambda (x2) (cons (+ a 1) x2))
(cut list 1 <> 3 <> 5) @equiv{} (lambda (x2 x4) (list 1 x2 3 x4 5))
(cut list)             @equiv{} (lambda () (list))
(cut list 1 <> 3 <...>)
   @equiv{} (lambda (x2 . xs) (apply list 1 x2 3 xs))
(cut <> a b)           @equiv{} (lambda (f) (f a b))

;; Usage
(map (cut * 2 <>) '(1 2 3 4))
(for-each (cut write <> port) exprs)
@end example

@code{Cute} is a variation of @code{cut} that evaluates @var{expr-or-slot}s
before creating the procedure.

@example
(cute cons (+ a 1) <>)
   @equiv{} (let ((xa (+ a 1))) (lambda (x2) (cons xa x2)))
@end example

Gauche provides a couple of different ways to write partial
applications concisely; see the @code{$} macro below, and also
the @code{pa$} procedure (@pxref{Combinators}).
@end defmac

@defmac $ arg @dots{}
A macro to chain applications, hinted from Haskell's @code{$} operator
(although the meaning is different).
Within the macro arguments @var{arg} @dots{}, @code{$} delimits
the last argument.  For example, the following code makes
the last argument for the procedure @code{f} to be @code{(g c d @dots{})}
@example
  ($ f a b $ g c d ...)
  @equiv{} (f a b (g c d ...))
@end example

The @code{$} notation can be chained.

@example
  ($ f a b $ g c d $ h e f ...)
  @equiv{} (f a b (g c d (h e f ...)))
@end example

If @code{$*} appears in the argument list instead of @code{$},
it fills the rest of the arguments, instead of just the last argument.

@example
  ($ f a b $* g c d ...)
  @equiv{} (apply f a b (g c d ...))

  ($ f a b $* g $ h $* hh ...)
  @equiv{} (apply f a b (g (apply h (hh ...))))
@end example

Furthermore, if the argument list ends with @code{$} or @code{$*},
the whole expression becomes a procedure expecting the last argument(s).

@example
  ($ f a b $ g c d $ h e f $)
  @equiv{} (lambda (arg) (f a b (g c d (h e f arg))))
  @equiv{} (.$ (cut f a b <>) (cut g c d <>) (cut h e f <>))

  ($ f a b $ g c d $ h e f $*)
  @equiv{} (lambda args (f a b (g c d (apply h e f args))))
  @equiv{} (.$ (cut f a b <>) (cut g c d <>) (cut h e f <...>))
@end example

The more functional the code becomes, the more you
tempted to write it as a chain of nested function calls.
Scheme's syntax can get awkward in such code.  Close
parentheses tend to clutter at the end of expressions.
Inner applications tends to pushed toward right columns
with the standard indentation rules.  Compare the
following two code functionally equivalent to each other:

@example
(intersperse ":"
             (map transform-it
                  (delete-duplicates (map cdr
                                          (group-sequence input)))))

($ intersperse ":"
   $ map transform-it
   $ delete-duplicates
   $ map cdr $ group-sequence input)
@end example

It is purely a matter of taste, and also this kind of syntax sugars
can be easily abused.  Use with care, but it may work well if used
sparingly, like spices.

As a corner case, if neither @code{$} nor @code{$*} appear in the
argument list, it just calls the function.

@example
  ($ f a b c) @equiv{} (f a b c)
@end example
@end defmac

@defmac case-lambda clause @dots{}
[R7RS case-lambda]
Each @var{clause} should have the form (@var{formals} @var{expr} @dots{}),
where @var{formals} is a formal arguments list as for @code{lambda}.

This expression evaluates to a procedure that accepts a variable
number of arguments and is lexically scoped in the same manner as
procedures resulting from @code{lambda} expressions.
When the procedure is called with some arguments,
then the first @var{clause} for which the arguments agree with
@var{formals} is selected, where agreement is specified as for
the @var{formals} of a @code{lambda} expression.
The variables of @code{formals} are bound to the given
arguments, and the @var{expr} @dots{} are evaluated within the environment.

It is an error for the arguments not to agree with
the @var{formals} of any @var{clause}.

@example
(define f
  (case-lambda
    [() 'zero]
    [(a) `(one ,a)]
    [(a b) `(two ,a ,b)]))

(f)       @result{} zero
(f 1)     @result{} (one 1)
(f 1 2)   @result{} (two 1 2)
(f 1 2 3) @result{} @r{Error: wrong number of arguments to case lambda}

(define g
  (case-lambda
    [() 'zero]
    [(a) `(one ,a)]
    [(a . b) `(more ,a ,@@b)]))

(g)       @result{} zero
(g 1)     @result{} (one 1)
(g 1 2 3) @result{} (more 1 2 3)
@end example

Note that the clauses are examined sequentially to match the number of
arguments, so in the following example @code{g2} never returns @code{(one ...)}.

@example
(define g2
  (case-lambda
    [() 'zero]
    [(a . b) `(more ,a ,@@b)]
    [(a) `(one ,a)]))

(g2 1)    @result{} (more 1)
@end example
@end defmac

@c ----------------------------------------------------------------------
@node Assignments, Conditionals, Making procedures, Core syntax
@section Assignments
@c NODE  代入

@defspec set! symbol expression
@defspecx set! (proc arg @dots{}) expression
[R7RS+ base][SRFI-17]
First, @var{expression} is evaluated.
In the first form, the binding of @var{symbol} is modified
so that next reference of @var{symbol} will return
the result of @var{expression}.
If @var{symbol} is not locally bound, the global variable named @var{symbol}
must already exist, or an error is signaled.

The second form is a ``generalized set!'' specified in SRFI-17.
It is a syntactic sugar of the following form.
@example
((setter @var{proc}) @var{arg} @dots{} @var{expression})
@end example
Note the order of the arguments of the setter method
differs from CommonLisp's @code{setf}.

Some examples:

@example
(define x 3)
(set! x (list 1 2))
x                    @result{} (1 2)

(set! (car x) 5)
x                    @result{} (5 2)
@end example
@end defspec

@defmac set!-values (var @dots{}) expr
Sets values of multiple variables at once.  @var{Expr} must yield
as many values as @var{var} @dots{}.  Each value is set to
the corresponding @var{var}.
@example
(define a 0)
(define b 1)
(set!-values (a b) (values 3 4))
a @result{} 3
b @result{} 4
(set!-values (a b) (values b a))
a @result{} 4
b @result{} 3
@end example
@end defmac

@defun setter proc
[SRFI-17]
Returns a setter procedure associated to the procedure @var{proc}.
If no setter is associated to @var{proc}, its behavior is undefined.

A setter procedure @var{g} of a procedure @var{f} is such that when used
as @code{(g a b @dots{} v)}, the next evaluation of @code{(f a b @dots{})}
returns @var{v}.

To associate a setter procedure to another procedure, you can use
the setter of @code{setter}, like this:
@example
(set! (setter @var{f}) @var{g})
@end example

A procedure's setter can be ``locked'' to it.  System default setters,
like @code{set-car!} for @code{car}, is locked and can't be set by
the above way.   In order to lock a setter to a user defined procedure,
use @code{getter-with-setter} below.

If @var{proc} is not a procedure, a setter generic function
of @code{object-apply} is returned;
it allows the applicable object extension to work
seamlessly with the generalized @code{set!}.
@xref{Applicable objects}, for the details.
@end defun

@defun has-setter? proc
Returns @code{#t} if a setter is associated to @var{proc}.
@end defun

@defun getter-with-setter get set
[SRFI-17]
Takes two procedure @var{get} and @var{set}.  Returns a new
procedure which does the same thing as @var{get}, and its setter is
locked to @var{set}.

The intention of this procedure is, according to the SRFI-17 document,
to allow implementations to inline setters efficiently.  Gauche
hasn't implement such optimization yet.
@end defun

A few macros that adopts the same semantics of generalized @code{set!}
are also provided.  They are built on top of @code{set!}.

@defmac push! place item
Conses @var{item}
and the value of @var{place}, then sets the result to @var{place}.
@var{place} is either a variable or a form
@code{(@var{proc} @var{arg} @dots{})},
as the second argument of @code{set!}.   The result of this form
is undefined.

@example
(define x (list 2))
(push! x 3)
x @result{} (3 2)

(push! (cdr x) 4)
x @result{} (3 4 2)
@end example

When @var{place} is a list, it roughly expands like the following.

@example
(push! (foo x y) item)
 @equiv{}
 (let ((tfoo foo)
       (tx x)
       (ty y))
   ((setter tfoo) tx ty (cons item (tfoo tx ty))))
@end example

Note: Common Lisp's @code{push} macro takes its argument reverse
order.   I adopted this order since it is consistent with other
destructive operations.  Perl's @code{push} function takes the same
argument order, but it appends @var{item} at the end of the array
(Perl's @code{unshift} is closer to @code{push!}).
You can use a queue (@pxref{Queue}) if you need a behavior of Perl's
@code{push}.
@end defmac

@defmac pop! place
Retrieves the value of @var{place}, sets its @code{cdr} back to @var{place}
and returns its @code{car}.

@example
(define x (list 1 2 3))
(pop! x) @result{} 1
x @result{} (2 3)

(define x (vector (list 1 2 3)))
x @result{} #((1 2 3))
(pop! (vector-ref x 0)) @result{} 1
x @result{} #((2 3))
@end example

Note: This works the same as Common Lisp's @code{pop}.
Perl's @code{pop} pops value from the end of the sequence;
its @code{shift} does the same thing as @code{pop!}.
@end defmac


@defmac inc! place :optional delta
@defmacx dec! place :optional delta
Evaluates the value of @var{place}.  It should be a number.
Adds (@code{inc!}) or subtracts (@code{dec!}) @var{delta} to/from it,
and then stores the result to @var{place}.  The default value of
@var{delta} is 1.

This is like Common Lisp's @code{incf} and @code{decf}, except
that you can't use the result of @code{inc!} and @code{dec!}.
@end defmac

@defmac update! place proc
Generalized form of @code{push!} etc.  @var{Proc} must be a procedure
which takes one argument and returns one value.   The original value of
@var{place} is passed to the @var{proc}, then its result is set to
@var{place}.
@example
(define a (cons 2 3))
(update! (car a) (lambda (v) (* v 3)))
a @result{} (6 . 3)

(update! (cdr a) (cut - <> 3))
a @result{} (6 . 0)
@end example
@end defmac

@c ----------------------------------------------------------------------
@node Conditionals, Binding constructs, Assignments, Core syntax
@section Conditionals
@c NODE 条件式

@defspec if test consequent alternative
@defspecx if test consequent
[R7RS base]
@var{Test} is evaluated.  If it yields a true value,
@var{consequent} is evaluated.  Otherwise, @var{alternative} is
evaluated.  If @var{alternative} is not provided, it results undefined value.

@example
(if (number? 3) 'yes 'no) @result{} yes
(if (number? #f) 'yes 'no) @result{} no

(let ((x '(1 . 2)))
  (if (pair? x)
      (values (car x) (cdr x))
      (values #f #f)))
  @result{} 1 @r{and} 2
@end example
@end defspec

@defspec cond clause1 clause2 @dots{}
[R7RS+ base][SRFI-61]
Each @var{clause} must be the form
@example
(@var{test} @var{expr} @dots{})
(@var{test} => @var{expr})
(@var{test} @var{guard} => @var{expr})
(else @var{expr} @var{expr2} @dots{})
@end example
The last form can appear only as the last clause.

@code{cond} evaluates @var{test} of each clauses in order, until
it yields a true value.   Once it yields true, if the clause
is the first form,  the corresponding @var{expr}s are evaluated
and the result(s) of last @var{expr} is(are) returned; if the clause
is the second form, the @var{expr} is evaluated and it must yield
a procedure that takes one argument.  Then the result of @var{test}
is passed to it, and the result(s) it returns will be returned.

The third form is specified in SRFI-61.  In this form, @var{test}
can yield arbitrary number of values.  The result(s)
of @var{test} is(are) passed to @var{guard}; if it returns a true value,
@var{expr} is applied with an equivalent argument list, and its
result(s) is(are) returned.  If @var{guard} returns @code{#f},
the evaluation proceeds to the next clause.

If no test yields true, and the last clause is not the fourth form
(else clause), an undefined value is returned.

If the last clause is else clause and all tests are failed,
@var{expr}s in the else clause are evaluated, and its last
@var{expr}'s result(s) is(are) returned.

@example
(cond ((> 3 2) 'greater)
      ((< 3 2) 'less)) @result{} greater
(cond ((> 3 3) 'greater)
      ((< 3 3) 'less)
      (else 'equal)) @result{} equal
(cond ((assv 'b '((a 1) (b 2))) => cadr)
      (else #f)) @result{} 2
@end example
@end defspec


@defspec case key clause1 clause2 @dots{}
[R7RS+ base][SRFI-87]
@var{Key} may be any expression.
Each @var{clause} should have the form
@example
((@var{datum} ...) @var{expr} @var{expr2} @dots{})
((@var{datum} ...) => @var{proc})
@end example
where each @var{datum} is an external representation of some object.
All the @var{datum}s must be distinct. The last @var{clause}
may be an ``else clause,'' which has the form
@example
(else @var{expr} @var{expr2} @dots{})
(else => @var{proc})
@end example

First, @var{key} is evaluated and its result is compared against each
@var{datum}.  If the result of evaluating @var{key} is equivalent
(using @code{eqv?}, @pxref{Equality}), to a @var{datum},
then the expressions in the corresponding clause are evaluated
sequentially, and the result(s) of the last expression in the
@var{clause} is(are) returned from the case expression.
The forms containing @code{=>} are specified in SRFI-87.  In these
forms, the result of @var{key} is passed to @var{proc}, and its
result(s) is(are) returned from the case expression.

If the result of evaluating @var{key} is different from every @var{datum},
then if there is an else clause its expressions are evaluated and
the result(s) of the last is(are) the result(s) of the case expression;
otherwise the result of the case expression is undefined.
@c skimu このファイルの他の場所では undefined なのでそれに合わせました。
@example
(case (* 2 3)
  ((2 3 5 7) 'prime)
  ((1 4 6 8 9) 'composite)) @result{} composite

(case (car '(c d))
  ((a) 'a)
  ((b) 'b)) @result{} @r{undefined}

(case (car '(c d))
  ((a e i o u) 'vowel)
  ((w y) 'semivowel)
  (else 'consonant)) @result{} consonant

(case 6
  ((2 4 6 8) => (cut + <> 1))
  (else => (cut - <> 1))) @result{} 7

(case 5
  ((2 4 6 8) => (cut + <> 1))
  (else => (cut - <> 1))) @result{} 4
@end example
@end defspec


@defmac ecase key clause1 clause2 @dots{}
This works exactly like @code{case}, except when there's
no @code{else} clause and the value of @var{key} expression
doesn't match any of @var{datum}s provided in @var{clause}s.
While @code{case} form returns undefined value for such case,
@var{ecase} raises an error.

It is taken from Common Lisp.  It's a convenient form when
you want to detect when unexpected value is passed just in case.

@smallexample
(ecase 5 ((1) 'a) ((2 3) 'b) ((4) 'c))
 @result{} ERROR: ecase test fell through: got 5, expecting one of (1 2 3 4)
@end smallexample
@end defmac

@defspec and test @dots{}
[R7RS base]
The @var{test} expressions are evaluated from left to right,
and the value of the first expression that evaluates to a false
value is returned.
Any remaining expressions are not evaluated.
If all the expressions evaluate to true values,
the value of the last expression is returned.
If there are no expressions then @code{#t} is returned.

@example
(and (= 2 2) (> 2 1)) @result{} #t
(and (= 2 2) (< 2 1)) @result{} #f
(and 1 2 'c '(f g))   @result{} (f g)
(and)                 @result{} #t
@end example
@end defspec


@defspec or test @dots{}
[R7RS base]
The @var{test} expressions are evaluated from left to right,
and the value of the first expression that evaluates to a true
value is returned. Any remaining expressions are not evaluated.
If all expressions evaluate to false values, the value of the
last expression is returned. If there are no expressions then
@code{#f} is returned.

@example
(or (= 2 2) (> 2 1)) @result{} #t
(or (= 2 2) (< 2 1)) @result{} #t
(or #f #f #f)        @result{} #f
(or (memq 'b '(a b c))
    (/ 3 0)) @result{} (b c)
@end example
@end defspec

@defspec when test expr1 expr2 @dots{}
@defspecx unless test expr1 expr2 @dots{}
[R7RS base]
Evaluates @var{test}.  If it yields true value (or false in case of
@code{unless}), @var{expr1} and @var{expr2} @dots{} are evaluated
sequentially, and the result(s) of the last evaluation is(are) returned.
Otherwise, undefined value is returned.
@end defspec

@defmac assume test-expr message @dots{}
[SRFI-145]
Evaluates @var{text-expr} and returns its value.

Also, this form declares the programmer's intent that the code following
this path always satisfy @var{test-expr}.

Currently, Gauche always signals an error with @var{message} @dots{}
if @var{text-expr} evaluates to @code{#f}.

@example
(define (real-sqrt x)
  (assume (and (real? x) (>= x 0)))
  (sqrt x))

gosh> (real-sqrt -1)
*** ERROR: Invalid assumption: (and (real? x) (>= x 0))
@end example

Note: This form is advisory---it isn't guaranteed for an error to be 
signaled when @var{test-expr} fails.  
For example, we may add an optimization
option that omits testing in speed-optimized code in future.
We may also enhance the compiler to generate better code using the
given information---for example, in the above @code{real-sqrt} code,
the compiler could theoretically deduce that @code{(sqrt x)} only needs to
work as real functions, so it would be able to generate specialized code.
Use this form to inform the compiler and the reader your intention.
@end defmac

@defmac assume-type expr type
Evaluates @var{expr}, and Checks if the value has type @var{type}.
If not, raises an error.  The result of @var{expr} is returned.

As @var{type}, you can specify a Gauche class.  The value is of type
if it satisfies @code{(is-a? value type)}
(@pxref{Types and classes}).

Note: Like @code{assume}, this form is advisory; it is not guaranteed
that the check is performed, nor @var{expr} is evaluated.

On the other hand, the type assumption may be used by the compiler
future compilers for optimizations.
@end defmac

@node Binding constructs, Sequencing, Conditionals, Core syntax
@section Binding constructs
@c NODE 変数束縛

@defspec let ((var expr) @dots{}) body @dots{}
@defspecx let* ((var expr) @dots{}) body @dots{}
@defspecx letrec ((var expr) @dots{}) body @dots{}
@defspecx letrec* ((var expr) @dots{}) body @dots{}
[R7RS base]
Creates a local scope where @var{var} @dots{} are bound to the
value of @var{expr} @dots{}, then evaluates @var{body} @dots{}.
@var{Var}s must be symbols, and there shouldn't be duplicates.
The value(s) of the last expression of @var{body} @dots{} becomes
the value(s) of this form.

The four forms differ in terms of the scope and the order 
@var{expr}s are evaluated.
@code{Let} evaluates @var{expr}s before (outside of) @code{let} form.
The order of evaluation of @var{expr}s is undefined, and the compiler
may reorder those @var{expr}s freely for optimization.
@code{Let*} evaluates @var{expr}s, in the order they appears,
and each @var{expr} is evaluated in the scope 
where @var{var}s before it are bound.

@code{Letrec} evaluates @var{expr}s, in an undefined order,
in the environment where @var{var}s are already bound
(to an undefined value, initially).
@code{letrec} is necessary to define mutually recursive local procedures.
Finally, @code{letrec*} uses the same scope rule as @code{letrec},
and it evaluates @var{expr} in the order of appearance.

@example
(define x 'top-x)

(let  ((x 3) (y x)) (cons x y)) @result{} (3 . top-x)
(let* ((x 3) (y x)) (cons x y)) @result{} (3 . 3)

(let ((cons (lambda (a b) (+ a b)))
      (list (lambda (a b) (cons a (cons b 0)))))
  (list 1 2))  @result{} (1 2 . 0)

(letrec ((cons (lambda (a b) (+ a b)))
         (list (lambda (a b) (cons a (cons b 0)))))
  (list 1 2))  @result{} 3
@end example

You need to use @code{letrec*} if evaluation of one @var{expr} requires
the value of @var{var} that appears before the @var{expr}.  In the following
example, calculating the value of @var{a} and @var{b} requires the value
of @var{cube}, so you need @code{letrec*}.   (Note the difference from
the above example, where @emph{calculating} the value of @var{list}
doesn't need to take the value of @var{cons} bound in the same @code{letrec}.
The value of @var{cons} isn't required until @var{list} is actually applied.)

@example
(letrec* ((cube (lambda (x) (* x x x)))
          (a (+ (cube 1) (cube 12)))
          (b (+ (cube 9) (cube 10))))
  (= a b)) @result{} #t
@end example

This example happens to work with @code{letrec} in the current Gauche, but
it is not guaranteed to keep working in future.  You just should not
rely on evaluation order when you use @code{letrec}.
In retrospect, it would be a lot simpler if we only had @code{letrec*}.
Unfortunately @code{letrec} preceded for long time in Scheme history
and it's hard to remove that.  Besides, @code{letrec} does have more
opportunities to optimize than @code{letrec*}.
@end defspec

@defmac let1 var expr body @dots{}
A convenient macro when you have only one variable.
Expanded as follows.

@example
(let ((@var{var} @var{expr})) @var{body} @dots{})
@end example
@end defmac

@defmac if-let1 var expr then
@defmacx if-let1 var expr then else
This macro simplifies the following idiom:
@example
(let1 @var{var} @var{expr}
  (if @var{var} @var{then} @var{else}))
@end example
@end defmac

@defmac rlet1 var expr body @dots{}
This macro simplifies the following idiom:
@example
(let1 @var{var} @var{expr}
  @var{body} @dots{}
  @var{var})
@end example
@end defmac

@defmac and-let* (binding @dots{}) body @dots{}
[SRFI-2]
In short, it works like @code{let*}, but returns @code{#f} immediately
whenever the expression in @var{binding}s evaluates to @code{#f}.

Each @var{binding} should be one of the following form:
@table @code
@item (@var{variable} @var{expression})
The @var{expression} is evaluated; if it yields true value, the value
is bound to @var{variable}, then proceed to the next binding.  If
no more bindings, evaluates @var{body} @dots{}.   If @var{expression}
yields @code{#f}, stops evaluation and returns @code{#f} from @code{and-let*}.
@item (@var{expression}x)
In this form, @var{variable} is omitted.  @var{Expression} is evaluated
and the result is used just to determine whether we continue or
stop further evaluation.
@item @var{bound-variable}
In this form, @var{bound-variable} should be an identifier denoting
a bound variable.  If its value is not @code{#f}, we continue
the evaluation of the clauses.
@end table

Let's see some examples.  The following code searches @var{key}
from an assoc-list @var{alist} and returns its value if found.
@example
(and-let* ((entry (assoc key alist))) (cdr entry))
@end example

If @var{arg} is a string representation of an exact integer, returns its value;
otherwise, returns 0:
@example
(or (and-let* ((num (string->number arg))
               ( (exact? num) )
               ( (integer? num) ))
      num)
    0)
@end example

The following is a hypothetical code that searches a certain server port
number from a few possibilities (environment variable, configuration file,
...)
@example
(or (and-let* ((val (sys-getenv "SERVER_PORT")))
      (string->number val))
    (and-let* ((portfile (expand-path "~/.server_port"))
               ( (file-exists? portfile) )
               (val (call-with-input-string portfile port->string)))
      (string->number val))
    8080) ; default
@end example

@end defmac

@defmac and-let1 var test exp1 exp2 @dots{}
Evaluates @var{test}, and if it isn't @code{#f}, binds @var{var} to it
and evaluates @var{exp1} @var{exp2} @dots{}.  Returns the result(s) of
the last expression.  If @var{test} evaluates to @code{#f}, returns @code{#f}.

This can be easily written by @code{and-let*} or @code{if-let1} as follows.
However, we've written this idiom so many times that it deserves
another macro.

@example
(and-let1 var test
  exp1
  exp2 @dots{})

@equiv{}

(and-let* ([var test])
  exp1
  exp2 @dots{})

@equiv{}

(if-let1 var test
  (begin exp1 exp2 @dots{})
  #f)
@end example
@end defmac

@defmac fluid-let ((var val) @dots{}) body @dots{}
A macro that emulates dynamic scoped variables.
@var{Var}s must be variables bound in the scope including
@code{fluid-let} form.  @var{Val}s are expressions.
@code{Fluid-let} first evaluates @var{val}s, then
evaluates @var{body} @dots{}, with binding
@var{var}s to the corresponding values during the dynamic
scope of @var{body} @dots{}.

Note that, in multithreaded environment,
the change of the value of @var{var}s are visible from
all the threads.   This form is provided mainly for
the porting convenience.   Use parameter objects instead
(@pxref{Parameters}) for thread-local dynamic state.
@example
(define x 0)

(define (print-x) (print x))

(fluid-let ((x 1))
  (print-x))  @result{} ;; prints 1
@end example
@end defmac

@defspec receive formals expression body @dots{}
[SRFI-8]
This is the way to receive multiple values.
@var{Formals} can be a (maybe-improper) list of symbols.
@var{Expression} is evaluated, and the returned value(s)
are bound to @var{formals} like the binding of lambda formals,
then @var{body} @dots{} are evaluated.

@example
(define (divrem n m)
  (values (quotient n m) (remainder n m)))

(receive (q r) (divrem 13 4) (list q r))
  @result{} (3 1)

(receive all (divrem 13 4) all)
  @result{} (3 1)

(receive (q . rest) (divrem 13 4) (list q rest))
  @result{} (3 (1))
@end example

See also @code{call-with-values} in @ref{Multiple values}
which is the procedural equivalent of @code{receive}.
You can use @code{define-values} (@pxref{Definitions}) to
bind multiple values to variables simultaneously.
Also @code{let-values} and @code{let*-values} below
provides @code{let}-like syntax with multiple values.
@end defspec

@defmac let-values ((vars expr) @dots{}) body @dots{}
[R7RS base]
@var{vars} are a list of variables. @var{expr} is evaluated, and
its first return value is bound to the first variable in @var{vars},
its second return value to the second variable, and so on, then
@var{body} is evaluated.
The scope of @var{expr}s are the outside of @code{let-values} form,
like @code{let}.

@example
(let-values (((a b) (values 1 2))
             ((c d) (values 3 4)))
  (list a b c d)) @result{} (1 2 3 4)

(let ((a 1) (b 2) (c 3) (d 4))
  (let-values (((a b) (values c d))
               ((c d) (values a b)))
    (list a b c d))) @result{} (3 4 1 2)
@end example

@var{vars} can be a dotted list or a single symbol, like the
lambda parameters.

@example
(let-values (((x . y) (values 1 2 3 4)))
  y) @result{} (2 3 4)

(let-values ((x (values 1 2 3 4)))
  x) @result{} (1 2 3 4)
@end example

If the number of values returned by @var{expr} doesn't match
what @var{vars} expects, an error is signaled.
@end defmac

@defmac let*-values ((vars expr) @dots{}) body @dots{}
[R7RS base]
Same as @code{let-values}, but each @var{expr}'s scope includes
the preceding @var{vars}.

@example
(let ((a 1) (b 2) (c 3) (d 4))
  (let*-values (((a b) (values c d))
                ((c d) (values a b)))
    (list a b c d))) @result{} (3 4 3 4)
@end example
@end defmac


@defmac rec var expr
@defmacx rec (name . vars) expr @dots{}
[SRFI-31]
A macro to evaluate an expression with recursive reference.

In the first form, evaluates expr while @var{var} in @var{expr} is
bound to the result of @var{expr}.
The second form is equivalent to the followings.
@example
(rec @var{name} (lambda @var{vars} @var{expr} @dots{}))
@end example

Some examples:

@example
;; constant infinite stream
(rec s (cons 1 (delay s)))

;; factorial function
(rec (f n)
  (if (zero? n)
      1
      (* n (f (- n 1)))))
@end example
@end defmac

@node Sequencing, Iteration, Binding constructs, Core syntax
@section Sequencing
@c NODE 順次実行


@defspec begin form @dots{}
[R7RS base]
Evaluates @var{form}s sequentially, and returns the last result(s).

@code{Begin} doesn't introduce new scope like @code{let}, that is,
you can't place "internal define" at the beginning of @var{form}s
generally.   Semantically @code{begin} behaves as if @var{form}s
are spliced into the surrounding context.
For example, toplevel expression like the following is the same
as two toplevel definitions:

@example
(begin (define x 1) (define y 2))
@end example

Here's a trickier example:

@example
(let ()
  (begin
    (define x 2)
    (begin
      (define y 3)
    ))
  (+ x y))

  @equiv{}

(let ()
  (define x 2)
  (define y 3)
  (+ x y))
@end example
@end defspec

@defmac begin0 exp0 exp1 @dots{}
Evaluates @var{exp0}, @var{exp1}, @dots{}, then returns the result(s)
of @var{exp0}.   The name is taken from MzScheme.
This is called @code{prog1} in CommonLisp.

Unlike @code{begin}, this @emph{does} creates a new scope,
for the @code{begin0} form is expanded as follows.

@example
(receive tmp @var{exp0}
  @var{exp1} @dots{}
  (apply values tmp))
@end example
@end defmac


@node Iteration, Quasiquotation, Sequencing, Core syntax
@section Iteration
@c NODE 繰り返し

@defspec do ((variable init [step]) @dots{}) (test expr @dots{}) body @dots{}
[R7RS base]
@enumerate
@item
Evaluates @var{init} @dots{} and binds @var{variable} @dots{} to each result.
The following steps are evaluated under the environment where
@var{variables} are bound.
@item
Evaluate @var{test}.  If it yields true, evaluates
@var{expr} @dots{} and returns the result(s) of last @var{expr}.
@item
Otherwise, evaluates @var{body} @dots{} for side effects.
@item
Then evaluates @var{step} @dots{} and binds each result
to a fresh @var{variable} @dots{}, and repeat from the step 2.
@end enumerate

The following example loops 10 times while accumulating each
value of @var{i} to @var{j} and returns it.

@example
(do ((i 0 (+ i 1))
     (j 0 (+ i j)))
    ((= i 10) j)
  (print j))
 @result{} 45 ; @r{also prints intermediate values of j}
@end example

If @var{step} is omitted, the previous value of @var{variable}
is carried over.   When there's no @var{expr}, the non-false
value returned by @var{test} becomes the value of the @code{do} expression.

Since @code{do} syntax uses many parentheses, some prefer using
square brackets as well as parentheses to visually distinguish
the groupings.  A common way is to group each variable binding,
and the test clause, by square brackets.

@example
(do ([i 0 (+ i 1)]
     [j 0 (+ i j)])
    [(= i 10) j]
  (print j))
@end example

Note: Unlike Common Lisp (and ``for loops'' in many languages),
@var{variable} is freshly bound for each iteration.
The following example loops 5 times and creates a list of
closures, each of which closes the variable @var{i}.
When you call each closures, you can see that each of them
closes different @var{i} at the time of the iteration they were
created.

@example
(define closures
  (do ([i 0 (+ i 1)]
       [c '() (cons (^[] i) c)])
      [(= i 5) (reverse c)]
    ))

((car closures))  @result{} 0
((cadr closures)) @result{} 1
@end example

@end defspec


@defspec let name ((var init) @dots{}) body @dots{}
[R7RS base]
This variation of @code{let} is called ``named let''.  It creates
the following procedure and binds it to @var{name}, then calls
it with @var{init} @dots{}.

@example
(lambda (var @dots{}) body @dots{})
@end example

This syntax itself isn't necessarily related to iteration.  However,
the whole point of named let is that the above lambda expression is within the
scope of @var{name}---that is, you can call @var{name} recursively
within @var{body}.  Hence this is used very often to write
a loop by recursion (thus,
often the procedure is named @var{loop}, as in the following example.)

@example
(let loop ([x 0] [y '()])
  (if (= x 10)
    y
    (loop (+ x 1) (cons x y))))
 @result{} (9 8 7 6 5 4 3 2 1 0)
@end example

Of course you don't need to loop with a named let; you can call @var{name}
in non-tail position, pass @var{name} to other higher-order procedure, etc.
Named let exists since it captures a very common pattern of local recursive
procedures.  
Some Schemers even prefer named let to @code{do}, for the better
flexibility.

The following rewrite rule precisely explains the named let semantics.
The tricky use of @code{letrec} in the expansion is to make
@var{proc} visible from @var{body} @dots{} but not from @var{init} @dots{}.

@example
(let proc ((var init) @dots{}) body @dots{})
 @equiv{}
((letrec ((proc (lambda (var @dots{}) body @dots{})))
   proc)
 init @dots{})
@end example

@end defspec


@defmac dotimes ([variable] num-expr [result]) body @dots{}
@defmacx dolist ([variable] list-expr [result]) body @dots{}
Convenience loop syntaxes, imported from Common Lisp.
They are not very Scheme-y, in a sense that these
rely on some side-effects in @var{body} @dots{}.  Nevertheless these
capture some common pattern in day-to-day scripting.

You can use @code{dotimes} to repeat @var{body} @dots{} for a number
of times given by @var{num-expr},
and @code{dolist} to repeat @var{body} @dots{}
while traversing a list given by @var{list-expr}.  While @var{body} @dots{}
is evaluated,
@var{variable} is bound to the current iteration count (in @code{dotimes}),
or the current element in the list (in @code{dolist}).

@example
(dotimes (n 5) (write n))
 @result{} @r{writes "01234"}

(dolist (v '(a b c d e)) (write v))
 @result{} @r{writes "abcde"}
@end example

If you don't need to refer to @var{variable}, you can omit it.
For example, the following example prints @code{year!} 10 times:

@example
(dotimes (10) (print "yeah!"))
@end example

If the third element (@var{result}) is given in @code{dotimes} or
@code{dolist}, it is evaluated after all repetition is done, and its result
becomes the result of @code{dotimes}/@code{dolist}.  While @var{result}
is evaluated, @var{variable} is bound to the number of repetitions 
(in @code{dotimes}) or @code{()} (in @code{dolist}).
It is supported because Common Lisp has it.

Note that a fresh @var{variable} is bound for each iteration,
as opposed to Common Lisp where @var{variable} is mutated.
So if you create a closure closing @var{variable}, it won't be
overwritten by the subsequent iteration.

If you need more than simple iteration, you can use @code{do} form,
named @code{let}, or @ref{Eager comprehensions}, which provides
rich way to iterate.
@end defmac

@c @defmac do-plist ((kvar vvar) plist-expr [default]) body @dots{}
@c @c EN
@c A @emph{plist} is a list alternating key and values.  This macro
@c provides a convenient way to loop over a plist.

@c @example
@c ;; example of a plist, associating a => 1 and b => 2.
@c (a 1 b 2)
@c @end example
@c @c JP
@c @emph{plist}とは、キーと値が交互に現れるリストです。
@c このマクロはplistに対する繰り返しを簡単にするものです。

@c @example
@c ;; plistの例。a => 1、 b => 2 という関係を示す。
@c (a 1 b 2)
@c @end example
@c @c COMMON

@c @c EN
@c The @var{plist-expr} form must evaluate to a plist.
@c It evaluates @code{body} @dots{} while binding
@c @var{kvar} and @var{vvar} to each key and value.
@c @c JP
@c @var{plist-expr}はplistを返す式です。
@c @var{kvar}と@var{vvar}にそれぞれキーと値に束縛された環境で
@c @code{body} @dots{}が評価されます。
@c @c COMMON

@c @example
@c (doplist ((k v) '(a 1 b 2 c 3)) (print k " => " v))
@c  @result{} @r{prints:}
@c  a => 1
@c  b => 2
@c  c => 3
@c @end example

@c @c EN
@c By default, an error is signalled if @var{plist-expr} isn't even
@c (we only detect the error when we reach to the end of the list).
@c If you give @var{default} argument, however, it is used as the missing
@c value for the last key.
@c @c JP
@c デフォルトでは、@var{plist-expr}の生成するリストの要素が偶数個でなければ
@c エラーが報告されます(エラーはリストを最後までループした段階で検出されます)。
@c しかし、@var{default}引数が与えられていれば、要素が奇数個の場合は@var{default}の
@c 値が最後のキーに対応する値として使われます。
@c @c COMMON

@c @example
@c (doplist ((k v) '(a 1 b 2 c)) (print k " => " v))
@c   @result{} @r{Error, after printing} a => 1 @r{and} b => 2

@c (doplist ((k v) '(a 1 b 2 c) #f) (print k " => " v))
@c   @result{} @r{prints:}
@c  a => 1
@c  b => 2
@c  c => #f
@c @end example
@c @end defmac

@defmac while expr body @dots{}
@defmacx while expr @code{=>} var body @dots{}
@defmacx while expr guard @code{=>} var body @dots{}
@var{Var} is an identifier and @var{guard} is a procedure
that takes one argument.

In the first form, @var{expr} is evaluated, and if it yields a true
value, @var{body} @dots{} are evaluated.  It is repeated while
@var{expr} yields true value.

In the second form, @var{var} is bound to a result of @var{expr}
in the scope of @var{body} @dots{}.

In the third form, the value @var{expr} yields are passed to
@var{guard}, and the execution of @var{body} @dots{} is repeated
while @var{guard} returns a true value.  @var{var} is bound
to the result of @var{expr}.

The return value of @code{while} form itself isn't specified.

@example
(let ((a '(0 1 2 3 4)))
  (while (pair? a)
    (write (pop! a)))) @result{} @r{prints "01234"}

(let ((a '(0 1 2 3 #f 5 6)))
  (while (pop! a) integer? => var
    (write var))) @result{} @r{prints "0123"}
@end example
@end defmac

@defmac until expr body @dots{}
@defmacx until expr guard @code{=>} var body @dots{}
Like @code{while}, but the condition is reversed.  That is,
the first form repeats evaluation of @var{expr} and @var{body} @dots{}
until @var{expr} yields true.  In the second form,
the result of @var{expr} is passed to @var{guard}, and the
execution is repeated until it returns true.  @var{Var} is bound
to the result of @var{expr}.

(The second form without @var{guard} isn't useful in @code{until}, since
@var{var} would always be bound to @code{#f}).

The return value of @code{until} form itself isn't specified.

@example
(let ((a '(0 1 2 3 4)))
  (until (null? a)
    (write (pop! a)))) @result{} @r{prints "01234"}

(until (read-char) eof-object? => ch
  (write-char ch))
 @result{} @r{reads from stdin and writes char until EOF is read}
@end example
@end defmac


@c ----------------------------------------------------------------------
@node Quasiquotation, Definitions, Iteration, Core syntax
@section Quasiquotation
@c NODE 準クオート, 準クオート(Quasiquote)

@defspec quasiquote template
[R7RS base]
Quasiquotation is a convenient way to build a structure that has
some fixed parts and some variable parts.  See the explanation below.
@end defspec

@deftp {Reader Syntax} @code{`@var{template}}
@lxindex `
[R7RS]
The syntax @code{`x} is read as @code{(quasiquote x)}.
@end deftp

@defspec unquote datum @dots{}
@defspecx unquote-splicing datum @dots{}
[R7RS base]
These syntaxes have meaning only when they appear in the @var{template}
of quasiquoted form.  R5RS says nothing about these syntaxes
appear outside of quasiquote.  Gauche signals an error in such case,
for it usually indicates you forget quasiquote somewhere.

R5RS only allows @code{unquote} and @code{unquote-splicing} to take
a single argument; it is undefined if you have @code{(unquote)} or
@code{(unquote x y)} inside quasiquoted form.  R6RS allows zero
or multi-arguments, and Gauche follows that.
@end defspec

@deftp {Reader Syntax} @code{,@var{datum}}
@deftpx {Reader Syntax} @code{,@@@var{datum}}
@lxindex ,
@lxindex ,@@
[R7RS]
The syntaxes @code{,x} and @code{,@@x} are read as @code{(unquote x)}
and @code{(unquote-splicing x)}, respectively.
@end deftp

@subheading Quasiquote basics

Suppose you want to create a list @code{(foo bar @var{x} @var{y})},
where @code{foo} and @code{bar} are symbols, and @var{x} and @var{y}
are the value determined at runtime.  (For the sake of explanation,
let's assume we have variables @var{x} and @var{y} that provides those
values.)  One way to do that is to call the function @code{list}
explicitly.

@example
(let ((x 0) (y 1))
  (list 'foo 'bar x y)) @result{} (foo bar 0 1)
@end example

You can do the same thing with quasiquote, like this:

@example
(let ((x 0) (y 1))
  `(foo bar ,x ,y))  @result{} (foo bar 0 1)
@end example

The difference between the two notations is that the explicit version
quotes the parts that you want to insert literally into the result,
while the quasiquote version @emph{unquotes} the parts that you
don't want to quote.

The quasiquote version gets simpler and more readable when you
have lots of static parts with scattered variable parts in your
structure.

That's why quasiquote is frequently used with
legacy macros, which are basically a procedure that
create program fragments from variable parts provided as
macro arguments.  See the simple-minded @code{my-if} macro
that expands to @code{cond} form:

@example
(define-macro (my-if test then else)
  `(cond (,test ,then)
         (else ,else)))

(macroexpand '(my-if (< n 0) n (- n)))
  @result{} (cond ((< n 0) n) (else (- n)))
@end example

Note the two @code{else}s in the macro definition; one isn't unquoted,
thus appears literally in the output, while another is unquoted and
the corresponding macro argument is inserted in its place.

Of course you can use quasiquotes unrelated to macros.  It is a general
way to construct structures.  Some even prefer using quasiquote to
explicit construction even most of the structure is variable, for
quasiquoted form can be more concise.  Gauche also tries to minimize
runtime allocation for quasiquoted forms, so it may potentially
be more efficient; see "How static are quasiquoted forms?" below.

@subheading Splicing

When @code{(unquote-splicing @var{expr})} appears in a quasiquoted form,
@var{expr} must evaluate to a list, which is @emph{spliced} into the
surrounding context.  It's easier to see examples:

@example
(let ((x '(1 2 3)))
  `(a ,@@x b)) @result{} (a 1 2 3 b)

(let ((x '(1 2 3)))
  `(a ,x b)) @result{} (a (1 2 3) b)

(let ((x '(1 2 3)))
  `#(a ,@@x b)) @result{} #(a 1 2 3 b)
@end example

Compare the unquote version and unquote-splicing version.  Splicing
also works within a vector.

@subheading Multi-argument unquotes

If @code{unquote} or @code{unquote-splicing} takes multiple arguments,
they are interpreted as if each of its arguments are unquoted
or unquote-spliced.

@smallexample
;; This is the same result as `(,(+ 1 2) ,(+ 2 3) ,(+ 3 4))
`((unquote (+ 1 2) (+ 2 3) (+ 3 4)))
  @result{} (3 5 7)

;; This is the same result as
;;   `(,@@(list 1 2) ,@@(list 2 3) ,@@(list 3 4))
`((unquote-splicing (list 1 2) (list 2 3) (list 3 4)))
  @result{} (1 2 2 3 3 4)

;; Edge cases
`((unquote))          @result{} ()
`((unquote-splicing)) @result{} ()
@end smallexample

It is an error for zero or multiple argument
@code{unquote}/@code{unquote-splicing} forms appear
which you cannot splice multiple forms into.

@smallexample
;; Multiple arguments unquotes are error in non-splicing context
`(unquote 1 2)          @result{} @r{error}
`(unquote-splicing 1 2) @result{} @r{error}
@end smallexample

Note that the abbreviated notations @code{,x} and @code{,@@x} are
only for single-argument forms.  You have to write @code{unquote}
or @code{unquote-splicing} explicitly for zero or multiple argument
forms; thus you don't usually need to use them.  These forms
are supported mainly to make the nested unquoting forms such
as @code{,,@@} and @code{,@@,@@}---R5RS cannot handle
the case the inner unquote-splicing
form expands into zero or multiple forms.

@subheading How static are quasiquoted forms?

When quasiquoted form contains variable parts, what happens at
runtime is just the same as when an explicit form is used:
@code{`(,x ,y)} is evaluated exactly like @code{(list x y)}.
However, Gauche tries to minimize runtime allocation when
a quasiquoted form has static parts.

First of all, if there's no variable parts in quasiquoted
form, like @code{`(a b c)}, the entire form is allocated statically.
If there is a static tail in the structure, it is also allocated
statically; e.g. @code{`((,x a b) (,y c d))} works like
@code{(list (cons x '(a b)) (cons y '(c d)))}.

Furthermore, when an unquoted expression is a
constant expression, Gauche embeds it into the static
form.  If you've defined a constant like
@code{(define-constant x 3)}, then the form
@code{`(,x ,(+ x 1))} is compiled as the constant @code{'(3 4)}.
(See @ref{Definitions}, for the explanation of @code{define-constant} form.)

In general it is hard to say which part of quasiquoted form is
compiled as a static datum and which part is not, so you shouldn't
write a code that assumes some parts of the structure returned from
quasiquote are freshly allocated.  In other words, you better avoid
mutating such structures.

@c ----------------------------------------------------------------------
@node Definitions, Inclusions, Quasiquotation, Core syntax
@section Definitions
@c NODE 定義

@defspec define variable expression
@defspecx define (variable . formals) body @dots{}
@defspecx define variable
[R7RS+]
This form has different meanings in the toplevel (without no
local bindings) or inside a local scope.

On toplevel, it defines a global binding to a symbol @var{variable}.
In the first form, it globally binds a symbol @var{variable}
to the value of @var{expression}, in the current module.
@example
(define x (+ 1 2))
x @result{} 3
(define y (lambda (a) (* a 2)))
(y 8) @result{} 16
@end example

If @var{variable} is already bound @emph{in the same module}, the subsequent
definitions work just like assignments.

@example
(define x 3)
(define (value-of-x) x)

(value-of-x x) @result{} 3

(define x 4)

(value-of-x x) @result{} 4
@end example

If @var{variable} is not bound in the current module, but has an
imported bindings, things get interesting but complicated.
@xref{Into the Scheme-Verse}, for the details.

The second form is a syntactic sugar of defining a procedure.
It is equivalent to the following form.
@example
(define (@var{name} . @var{args}) @var{body} @dots{})
  @equiv{} (define @var{name} (lambda @var{args} @var{body} @dots{}))
@end example

The third form is a shorthand of @code{(define variable (undefined))}.
It is introduced in R6RS (but not a part of R7RS).  You can use that
form to indicate the initial value doesn't matter.

If the form appears inside a local scope (internal define),
this introduce a local binding of the variable.

Internal defines can appear in the beginning of body of @code{lambda}
or other forms that introduces local bindings.  They are equivalent
to a @code{letrec*} form, as shown below.

@example
(lambda (a b)
  (define (cube x) (* x x x))
  (define (square x) (* x x))
  (+ (cube a) (square b)))

 @equiv{}

(lambda (a b)
  (letrec* ([cube (lambda (x) (* x x x))]
            [square (lambda (x) (* x x))])
    (+ (cube a) (square b))))
@end example

Since internal defines are essentially a @code{letrec*} form,
you can write mutually recursive local functions, and you can
use preceding bindings introduced in the same scope to calculate
the value to be defined.  However, you can't use a binding that is introduced
after an internal define form to calculate its value; if you do so,
Gauche may not report an error immediately, but you may get strange
errors later on.

@example
(lambda (a)
  (define x (* a 2))
  (define y (+ x 1))  ; ok to use x to calculate y
  (* a y))

(lambda (a)
  ;; You can refer to even? in odd?, since the value of even?
  ;; isn't used at the time odd? is defined; it is only used
  ;; when odd? is called.
  (define (odd? x) (or (= x 1) (not (even? (- x 1)))))
  (define (even? x) (or (= x 0) (not (odd? (- x 1)))))
  (odd? a))

(lambda (a)
  ;; This is not ok, for defining y needs to use the value
  ;; of x.  However, you may not get an error immediately.
  (define y (+ x 1))
  (define x (* a 2))
  (* a y))
@end example

Inside the body of binding constructs, internal defines must appear
before any expression of the same level.   The following code isn't allowed, for
an expression @code{(print a)} precedes the @code{define} form.

@example
(lambda (a)
  (print a)
  (define (cube x) (* x x x))  ; error!
  (cube a))
@end example

It is also invalid to put no expressions but internal defines
inside the body of binding constructs, although Gauche don't report
an error.

Note that @code{begin} (@pxref{Sequencing}) doesn't introduce a new scope.
@code{Define}s in the @code{begin} act as if @code{begin} and surrounding
parenthesis are not there.  Thus these two forms are equivalent.
@example
(let ((x 0))
  (begin
    (define (foo y) (+ x y)))
  (foo 3))
 @equiv{}
(let ((x 0))
  (define (foo y) (+ x y))
  (foo 3))
@end example
@end defspec

@defmac define-values (var @dots{}) expr
@defmacx define-values (var var1 @dots{} . var2) expr
@defmacx define-values var expr
[R7RS base]
@var{Expr} is evaluated, and each value of the result
is bound to each @var{var}s.  In the first form, it is an error
unless @var{expr} yields the same number of values as @var{var}s.
@example
(define-values (lo hi) (min&max 3 -1 15 2))

lo @result{} -1
hi @result{} 15
@end example

In the second form, @var{expr} may yield as many values as
@var{var} @var{var1} @dots{} or more; the excess values are
made into a list and bound to @var{var2}.

@example
(define-values (a b . c) (values 1 2 3 4))

a @result{} 1
b @result{} 2
c @result{} (3 4)
@end example

In the last form, all the values yielded by @var{expr} are gathered
to a list and bound to @var{var}.

@example
(define-values qr (quotient&remainder 23 5))

qr @result{} (4 3)
@end example

You can use @code{define-values} wherever @code{define} is allowed;
that is, you can mix @code{define-values} in internal defines.

@example
(define (foo . args)
  (define-values (lo hi) (apply min&max args))
  (define len (length args))
  (list len lo hi))

(foo 1 4 9 3 0 7)
 @result{} (6 0 9)
@end example
@end defmac

@defspec define-constant variable expression
@defspecx define-constant (variable . formals) body @dots{}
This form is only effective in toplevel.

Like top-level @code{define}, it defines a top-level definition
of @var{variable} with the value of @var{expression}, but additionally
tells the compiler that (1) the binding won't change, and
(2) the value of @var{expression} won't change from
the one computed at the compile time.
So the compiler can replace references of @var{variable} 
with the compile-time value of @var{expression}.

An error is signaled when you use @code{set!} to change the value
of @var{variable}.   It is allowed to redefine @var{variable},
but a warning is printed.

The difference from @code{define-inline} below is that the value of
@var{expression} is computed at the compile time and treated as a literal.
Suppose you define @var{x} as follows:

@example
(define-constant x (vector 1 2 3))
@end example

Then, the code @code{(list x)} is compiled to the same code
as @code{(list '#(1 2 3))}.

This distinction is especially important when you do AOT (ahead of time)
compilation.

There's no ``internal @code{define-constant}'', since the compiler
can figure out whether a local binding is mutated,
and optimize code accordingly, without a help of declarations.
@end defspec

@defspec define-inline variable expression
@defspecx define-inline (variable . formals) body @dots{}
The second form is a shorthand of @code{(define-inline variable (lambda formals body @dots{}))}.

If this appears in the position of internal defines, it is the same
as internal defines.

If it appears in the toplevel, it defines an @emph{inlinable} binding.
An inlinable binding promises the compiler that the binding won't
change, but unlike constant bindings introduced by @code{define-constant},
the actual value of @var{expression} may be computed at runtime.  
Hence the compiler cannot
simply replace the references of @var{variable} with the compile-time
value of @var{expression}.

However, if the compiler can determine that the value of @var{expression} 
is to be a procedure, it may inline the procedure where it is invoked.

In the example below, the body of @code{dot3} is inlined where @code{dot3}
is called.  Furthermore, since the second argument of @code{dot3} is
a constant vector, you can see @code{vector-ref} on it is computed at
compile time (e.g. @code{CONST -1.0} etc.)

@example
gosh> (define-inline (dot3 a b)
        (+ (* (vector-ref a 0) (vector-ref b 0))
           (* (vector-ref a 1) (vector-ref b 1))
           (* (vector-ref a 2) (vector-ref b 2))))
dot3
gosh> (disasm (^[] (dot3 x '#(-1.0 -2.0 -3.0))))
CLOSURE #<closure (#f)>
=== main_code (name=#f, code=0x28524e0, size=26, const=4 stack=6):
signatureInfo: ((#f))
     0 GREF-PUSH #<identifier user#x.20d38e0>; x
     2 LOCAL-ENV(1)             ; (dot3 x (quote #(-1.0 -2.0 -3.0)))
     3 LREF0                    ; a
     4 VEC-REFI(0)              ; (vector-ref a 0)
     5 PUSH 
     6 CONST -1.0
     8 NUMMUL2                  ; (* (vector-ref a 0) (vector-ref b 0))
     9 PUSH 
    10 LREF0                    ; a
    11 VEC-REFI(1)              ; (vector-ref a 1)
    12 PUSH 
    13 CONST -2.0
    15 NUMMUL2                  ; (* (vector-ref a 1) (vector-ref b 1))
    16 NUMADD2                  ; (+ (* (vector-ref a 0) (vector-ref b 0))
    17 PUSH 
    18 LREF0                    ; a
    19 VEC-REFI(2)              ; (vector-ref a 2)
    20 PUSH 
    21 CONST -3.0
    23 NUMMUL2                  ; (* (vector-ref a 2) (vector-ref b 2))
    24 NUMADD2                  ; (+ (* (vector-ref a 0) (vector-ref b 0))
    25 RET 
@end example

As an extreme case, if both arguments are compile-time constant,
@code{dot3} is completely computed at compile time:

@example
gosh> (disasm (^[] (dot3 '#(1 2 3) '#(4 5 6))))
CLOSURE #<closure (#f)>
=== main_code (name=#f, code=0x2a2b8e0, size=2, const=0 stack=0):
signatureInfo: ((#f))
     0 CONSTI(32) 
     1 RET 
@end example

The same inlining behavior may be achieved by making @code{dot3} a macro,
but if you use @code{define-inline}, @code{dot3} can be used as procedures
when needed:

@example
(map dot3 list-of-vectors1 list-of-vectors2)
@end example

If @code{dot3} is a macro you can't pass it as a higher-order procedure.

The inline expansion pass is run top-to-bottom.  Inlinable procedure must
be defined before used in order to be inlined.

If you redefine an inlinable binding, Gauche warns you, since
the redefinition won't affect already inlined call sites.  So it should
be used with care---either use it internal to the module, or use it
for procedures that won't change in future.  Inlining is effective for
performance-critical parts.  If a procedure is called sparingly,
there's no point to define it inlinable.
@end defspec


@defspec define-in-module module variable expression
@defspecx define-in-module module (variable . formals) body @dots{}
This form must appear in the toplevel.
It creates a global binding of @var{variable} in
@var{module}, which must be either a symbol of the module name or
a module object.  If @var{module} is a symbol, the named module
must exist.

@var{Expression} is evaluated in the current module.

The second form is merely a syntactic sugar of:
@example
(define-in-module module variable (lambda formals body @dots{}))
@end example
@end defspec

Note: to find out if a symbol has definition (global binding) in
the current module, you can use @code{global-variable-bound?}
(@pxref{Module introspection}).

@menu
* Into the Scheme-Verse::
@end menu

@node Into the Scheme-Verse,  , Definitions, Definitions
@subsection Into the Scheme-Verse
@c NODE Scheme多世界へようこそ

@subsubheading Multiple toplevels are multiple scopes

One upon a time, the Scheme world was simple.  We had one single global
space we called the toplevel.  Toplevel definitions can be understood
as side-effects to this global space; if the name hasn't been exist
there yet, create a new binding, otherwise, overwrite existing one.

The problem was that it was hard to scale, thus many implementations
introduced their own module systems.  One of the main agenda of R6RS
was to have a module system (which is called ``library'' in RnRS)
consistent with the design of Scheme.
Especially, since Scheme's hygienic macro system captures lexical scope,
it is desirable that it interacts with the module system in the same way.

In modern Scheme, ``toplevel'' of each module creates its own lexical
scope, and the definitions are understood in @code{letrec*} semantics.
Hence, macro systems can consistently treat identifiers as
a name associated with a scope.

Suppose you see these toplevel definitions:

@example
(define (odd? n)  (if (zero? x) #f (even? (- n 1))))
(define (even? n) (if (zero? x) #t (odd? (- n 1))))
@end example

The first appearance of @code{even?} in the first line 
is understood as the one defined in the second line.  It becomes
apparent when we compare it with internal defines:

@example
(let ((even? error))
  (define (odd? n)  (if (zero? x) #f (even? (- n 1))))
  (define (even? n) (if (zero? x) #t (odd? (- n 1))))
  ...)
@end example

The @code{even?} in the definition of @code{odd?} refers to the
one defined in the next line, never to the one bound by @code{let}.

So far, so good.

Now, consider the following toplevel code:

@example
;; Invalid in RnRS, n >= 6
(import (scheme base) (scheme write))
(define orig-error error)
(define (error . args)
  (write args) (newline)
  (apply orig-error args))
@end example

The intention is to save the @emph{original} value of @code{error},
which is imported from @code{(scheme base)}, into a variable
@code{orig-error}, then redefine @code{error} to add logging feature.
This technique was popular in pre-R6RS Scheme.

However, with our new toplevel-as-a-scope Scheme, the @code{error}
in @code{(define orig-error error)} @emph{must} refer to the one defined
in the same scope, which is the new definition below; otherwise lexical
scoping gets broken.  The value of inner @code{error} hasn't been calculated
when @code{orig-error}'s value is calculated, so the above form is
an invalid program in terms of RnRS.

In fact, to avoid confusion, R6RS prohibits defining a toplevel variable
that conflicts with the imported name (in R7RS the behavior of such program
is undefined).  In the example above,
the name @code{error} is imported from @code{(scheme base)} and also
defined in the toplevel, hence it's a violation.

The modern way of such augumentation is to use renaming import:

@example
(import (except (scheme base) error)
        (rename (scheme base) (error r7rs:error))
        (scheme write))
(define (error . args)
  (write args) (newline)
  (apply r7rs:error args))
@end example

@subsubheading Gauche's take

Gauche's module system predates R6RS and R7RS, and it regards a module
as a first-class entity and suppors class-like inheritance.  It is 
upper-compatible to R7RS libraries, but we take freedom in interpreting
R7RS undefined behaviors.

First, you can define toplevel variables that conflict with
imported or inherited bindings.  The new definition simply shadows the
old one.

Second, if multiple toplevel forms are processed at once
e.g. it is enclosed in @code{begin} or the file is read by @code{include},
we treat them in one scope.  That is, if the above @code{orig-error} example
is read by @code{include}, the first @code{error} refers to the to-be-defined
@code{error} below.  Since the value of @code{error} hasn't been calculated
by the time it's used, you'll get the following error:

@example
*** ERROR: uninitialized variable: error
@end example

Third, Gauche compiles and executes each individual toplevel forms
(the forms that's not enclosed in other S-expressions).  It is the
same as REPL semantics.  If each form of @code{orig-error} example
appears individually on the toplevel, the @code{(define orig-error error)}
line actually refers to the R7RS @code{error} and assign it to
@code{orig-error}, since @emph{we don't know yet if @code{error} will be
defined in the same scope}.

The third rule is necessary to support REPL semantics, but note that
the result would differ when the same file is @code{include}d.  If
you can, avoid writing such ambiguous code.

Note: The second behavior is clarified in release 0.9.9 for the
better compatibility with R7RS.  Before that,
the behavior of such case is undefined, but some code might have
expected that it works in REPL semantics (the third rule).

In order to support the transition, if you set an enviornment
variable @code{GAUCHE_LEGACY_DEFINE}, Gauche treats definitions
in the same way as 0.9.8 and before.
Note that if you that, you may see Gauche can't include some valid R7RS 
code that has multiple libraries in one file.

@c ----------------------------------------------------------------------
@node Inclusions, Feature conditional, Definitions, Core syntax
@section Inclusions
@c NODE インクルード

@defspec include filename @dots{}
@defspecx include-ci filename @dots{}
[R7RS base]
Reads @var{filename} @dots{} at compile-time, and insert their
contents as if the forms are placed in the includer's source file,
surrounded by @code{begin}.  The @code{include} form reads files
as is, while @code{include-ci} reads files in case-insensitive
way, as if @code{#!fold-case} is specified in the beginning of the
file (@pxref{Case-sensitivity}).

The coding magic comment in each file is honored while reading
that file (@pxref{Multibyte scripts}).

If @var{filename} is absolute, the file is just searched.  If it
is relative, the file
is first searched relative to the file containing the @code{include}
form, then the directories in @code{*load-path*} are tried.

Example: Suppose a file @file{a.scm} contains the following code:

@example
(define x 0)
(define y 1)
@end example

You can include this file into another source, like this:

@example
(define (foo)
  (include "a.scm")
  (list x y))
@end example

It works as if the source is written as follows:

@example
(define (foo)
  (begin
   (define x 0)
   (define y 1))
  (list x y))
@end example

(Note: In version 0.9.4, @code{include} behaved differently when
pathname begins with either @code{./} or @code{../}---in which case
the file is searched relative to the current working directory of the
compiler.  It is rather an artifact of @code{include} sharing file
search routine with @code{load}.  But unlike @code{load}, which is
a run-time operation, using relative path to the current directory
won't make much sense for @code{include}, so we changed the behavior
in 0.9.5.)

@end defspec

Gauche has other means to incorporate source code from
another files.  Here's the comparison.

@table @asis
@item @code{require} (@code{use} and @code{extend} calls @code{require} internally)
@itemize
@item
Both @code{require} and @code{include} work at compile-time.
@item
@code{Require}
works only in toplevel context, while @code{include} can be
anywhere.
@item
@code{Require} reads the file only once (second and later @code{require} on the
same file becomes no-op), while @code{include} reads the file
every place it appears.
@item
The file is searched from @code{*load-path*}.  The location
of the file @code{require} form appears doesn't matter.
(You can add directories relative to the requiring file
using the @code{:relative} flag in @code{add-load-path}, though).
@item
Even if the current module is changed by @code{select-module}
inside the required file, it is only effective while the
required file is read.  On the other hand, @code{include}
inserts any S-expressions in the included file to the
place @code{include} appears, so the effect of @code{select-module}
persists after @code{include} form (Note: Encoding magic comment
and @code{#!fold-case}/@code{#!no-fold-case} are dealt with by
the reader, so those effect is contained in the file even with
@code{include}).
@item
It is forbidden to the file loaded by @code{require} to insert
a toplevel binding without specifying a module.  In other words,
the file you require should generally use @code{define-module},
@code{select-module} or @code{define-library}.
@xref{Require and provide}, for further discussion.
On the other hand, @code{include} has no such restrictions.
@end itemize

@item @code{load}
@itemize
@item
Works at runtime, while @code{include} works at compile-time.
@item
Works only in toplevel context, while @code{include} can be
anywhere.
@item
The file is searched from @code{*load-path*}, except when the
file begins with @code{./} or @code{../}, in which case it is
first tried relative to the current directory before being searched
from @code{*load-path*}.
@item
As the case with @code{require}, change of the current module
won't persist after @code{load}.
@end itemize

@end table

Usually, @code{require} (or @code{use} and @code{extend}) are
better way to incorporate sources in other files.  The @code{include}
form is mainly for the tricks that can't be achieved with
@code{require}.  For example, you have a third-party R5RS code
and you want to wrap it with Gauche module system.  Using @code{include},
you place the following small source file along the third-party code,
and you can load the code with @code{(use third-party-module)} without
changing the original code at all.

@example
(define-module third-party-module
  (export proc ...)
  (include "third-party-source.scm"))
@end example

@c ----------------------------------------------------------------------
@node Feature conditional, Modules, Inclusions, Core syntax
@section Feature conditional
@c NODE 機能条件式

@subheading The @code{cond-expand} macro

Sometimes you need to have a different piece of code
depending on available features provided by the
implementation and/or platform.  For example,
you may want to switch behavior depending on whether
networking is available, or to embed an
implementation specific procedures in otherwise-portable code.

In C, you use preprocessor directives such as @code{#ifdef}.
In Common Lisp, you use reader macro @code{#+} and @code{#-}.
In Scheme, you have @code{cond-expand}:

@defmac cond-expand (feature-requirement command-or-definition @dots{}) @dots{}
[R7RS base]
This macro expands to @var{command-or-definition} @dots{} if
@var{feature-requirement} is supported by the current platform.

@var{feature-requirement} must be in the following syntax:
@example
@var{feature-requirement}
  : @var{feature-identifier}
  | (and @var{feature-requirement} @dots{})
  | (or  @var{feature-requirement} @dots{})
  | (not @var{feature-requirement})
  | (library @var{library-name})
@end example

The macro tests each @var{feature-requirement} in order, and
if one is satisfied, the macro itself expands to the
corresponding @var{command-or-definition} @dots{}.

The last clause may have @code{else} in the position of
@var{feature-requirement}, to make the clause expanded
if none of the previous feature requirement is fulfilled.

If there's neither a satisfying clause nor @code{else} clause,
@code{cond-expand} form throws an error.  It is to detect the case early
that the platform doesn't have required features.   If the feature
you're testing is optional, that is, your program works without the
feature as well, add empty @code{else} clause as follows.

@example
(cond-expand
  [feature expr]  ; some optional feature
  [else])
@end example


@var{feature-identifier} is a symbol that indicates a feature.
If such a feature is supported in the current platform, it satisfies the
@var{feature-requirement}.  You can do boolean combination
of @var{feature-requirement}s to compose more complex conditions.

The form @code{(library @var{library-name})} is added in R7RS,
and it is fulfilled when the named library is available.  Since
this is R7RS construct, you have to use R7RS-style library name---
list of symbols/integers, e.g. @code{(gauche net)} instead of
@code{gauche.net}.

Here's a typical example: Suppose you want to have implementation-specific
part for Gauche, Chicken Scheme and ChibiScheme.  Most modern Scheme
implementations defines a feature-identifier to identify itself.
You can write the conditional part as follows:

@example
(cond-expand
 [gauche  (gauche-specific-code)]
 [(or chicken chibi) (chicken-chibi-specific-code)]
 [else    (fallback-code)]
 )
@end example

It is important that the conditions of @code{cond-expand} is
purely examined at the macro-expansion time, and
unfulfilled clauses are discarded.
Thus, for example, you can include macro calls or language extensions
that may not be recognized on some implementations.  You can also
conditionally define global bindings.

Compare that to @code{cond}, which examines conditions at runtime.
If you include unsupported macro call in one of the conditions, it
may raise an error at macro expansion time, even if that clause
will never be executed on the platform.  Also, it is not possible
to conditionally define global bindings using @code{cond}.

There's a caveat, though.  Suppose you want to save the result of macro
expansion, and run the expanded result later on other platforms.
The result code is based on the features of the platform the macro
expansion takes place, which may not agree with the features
of the platform the code will run.  (This issue always arises
in cross-compiling situation in general.)

@c Gauche has @emph{ahead-of-time compilation} feature, which is only
@c used internally now, but will eventually be made for public use.

See below for the list of feature identifiers defined in Gauche.
@end defmac

@subheading Gauche-specific feature identifiers

@table @code
@item gauche
@itemx gauche-X.X.X
Indicates you're running on Gauche.  It is useful to put Gauche-specific
code in a portable program.
@code{X.X.X} is the gauche's version
(e.g. @code{gauche-0.9.4}), in case you want to have code
for specific Gauche version.  (Such feature identifier is suggested by
R7RS; but it might not be useful if we don't have means to compare versions.
Something to consider in future versions.)

@item gauche.os.windows
@itemx gauche.os.cygwin
Defined on Windows-native platform and Cygwin/Windows platform, respectively.
If neither is defined you can assume it's a unix variant.
(Cygwin is supposedly
unix variant, but corners are different enough to deserve it's own
feature identifier.)

@item gauche.ces.utf8
@itemx gauche.ces.eucjp
@itemx gauche.ces.sjis
@itemx gauche.ces.none
Either one of these is defined based on Gauche's native character
encoding scheme.  @xref{Multibyte strings}, for the details.

@item gauche.net.tls
@itemx gauche.net.tls.axtls
@itemx gauche.net.tls.mbedtls
Defined if the runtime supports TLS in networking.
The two sub feature identifiers, @code{gauche.net.tls.axtls} and
@code{gauche.net.tls.mbedtls}, are defined if each subsystem
@code{axTLS} and @code{mbedTLS} is supported, respectively.

@item gauche.net.ipv6
Defined if the runtime supports IPv6.
Note that this only indicates Gauche has been built with IPv6 support;
the OS may not allow IPv6 features, in that case you'll get system error
when you try to use IPv6.

@item gauche.sys.threads
@itemx gauche.sys.pthreads
@itemx gauche.sys.wthreads
If the runtime supports multithreading, @code{gauche.sys.threads} is
defined (@pxref{Threads}).  Multithreading is based on either POSIX pthreads
or Windows threads.  The former defines @code{gauche.sys.pthreads},
and the latter defines @code{gauche.sys.wthreads}.

@item gauche.sys.sigwait
@itemx gauche.sys.setenv
@itemx gauche.sys.unsetenv
@itemx gauche.sys.clearenv
@itemx gauche.sys.getloadavg
@itemx gauche.sys.getrlimit
@itemx gauche.sys.lchown
@itemx gauche.sys.getpgid
@itemx gauche.sys.nanosleep
@itemx gauche.sys.crypt
@itemx gauche.sys.symlink
@itemx gauche.sys.readlink
@itemx gauche.sys.select
@itemx gauche.sys.fcntl
@itemx gauche.sys.syslog
@itemx gauche.sys.setlogmask
@itemx gauche.sys.openpty
@itemx gauche.sys.forkpty
Those are defined based on the availability of these system features
of the platform.
@end table


@subheading R7RS feature identifiers

@table @code
@item r7rs
Indicates the implementation complies r7rs.

@item exact-closed
Exact arithmetic operations are closed; that is, dividing
an exact number by a non-zero exact number always yields an exact
number.

@item ieee-float
Using IEEE floating-point number internally.

@item full-unicode
Full unicode support.

@item ratios
Rational number support

@item posix
@itemx windows
Either one is defined, according to the platform.

@item big-endian
@itemx little-endian
Either one is defined, according to the platform.
@end table



@c ----------------------------------------------------------------------
@node Modules,  , Feature conditional, Core syntax
@section Modules
@c NODE モジュール

This section describes the semantics of Gauche modules and its API.
See also @ref{Writing Gauche modules}, for the conventions
Gauche is using for its modules.

For R7RS programs, they are called ``libraries'' and have different
syntax than Gauche modules.  @xref{R7RS library form}, for the details.

@menu
* Module semantics::
* Modules and libraries::
* Defining and selecting modules::
* Using modules::
* Module inheritance::
* Module introspection::
* Predefined modules::
@end menu

@node Module semantics, Modules and libraries, Modules, Modules
@subsection Module semantics
@c NODE モジュールのセマンティクス

Module is an object that maps symbols onto @emph{bindings},
and affects the resolution of global variable reference.

Unlike CommonLisp's packages, which map names to symbols,
in Gauche symbols are @code{eq?} in principle if two have the
same name (except uninterned symbols; @pxref{Symbols}).
However, Gauche's symbol doesn't have a 'value'
slot in it.  From a given symbol, a module finds its binding that
keeps a value.
Different modules can associate different bindings
to the same symbol, that yield different values.

@example
;; Makes two modules A and B, and defines a global variable 'x' in them
(define-module A (define x 3))
(define-module B (define x 4))

;;  #<symbol 'x'> ---[module A]--> #<binding that has 3>
(with-module A x) @result{} 3

;;  #<symbol 'x'> ---[module B]--> #<binding that has 4>
(with-module B x) @result{} 4
@end example

A module can @emph{export} a part or all of its bindings
for other module to use.
A module can @emph{import} other modules, and their exported
bindings become visible to the module.
A module can import any number of modules.

@example
(define-module A
  (export pi)
  (define pi 3.1416))

(define-module B
  (export e)
  (define e 2.71828))

(define-module C
  (import A B))

(select-module C)
(* pi e) @result{} 8.539748448
@end example

A module can also be @emph{inherited}, that is, you can extend
the existing module by inheriting it and adding new bindings
and exports.   From the new module, all ancestor's bindings (including
non-exported bindings) are visible.
(A new module inherits the @code{gauche} module by default, which is why
the built-in procedures and syntax of @code{gauche} are available
in the new module).
From outside, the new module looks like having
all exported bindings of the original module plus the newly
defined and exported bindings.

@example
;; Module A defines and exports deg->rad.
;; A binding of pi is not exported.
(define-module A
  (export deg->rad)
  (define pi 3.1416)   ;; not exported
  (define (deg->rad deg) (* deg (/ pi 180))))

;; Module Aprime defines and exports rad->deg.
;; The binding of pi is visible from inside Aprime.
(define-module Aprime
  (extend A)
  (export rad->deg)
  (define (rad->deg rad) (* rad (/ 180 pi))))

;; Module C imports Aprime.
(define-module C
  (import Aprime)
  ;; Here, both deg->rad and rad->deg are visible,
  ;; but pi is not visible.
  )
@end example

At any moment of the compilation, there is one "current module" available,
and the global variable reference is looked for from the module.
If there is a visible binding of the variable, the variable
reference is compiled to the access of the binding.
If the compiler can't find a visible binding,
it marks the variable reference with the current module, and
delays the resolution of binding at the time the variable is
actually used.  That is, when the variable is referenced
at run time, the binding is again looked for from the marked module
(@emph{not} the current module at the run time) and if found,
the variable reference code is replaced for the the code to
access the binding.  If the variable reference is not found even
at run time, an 'undefined variable' error is signaled.

Once the appropriate binding is found for the global variable,
the access to the binding is hard-wired in the compiled code
and the global variable resolution will never take place again.

The definition special form such as @code{define} and @code{define-syntax}
inserts the binding to the current module.   Thus it may shadow
the binding of imported or inherited modules.

The resolution of binding of a global variable happens like this.
First, the current module is searched.  Then, each
imported module is taken in the reverse order of import, and searched,
including each module's ancestors.
Note that import is not transitive; imported module list is not
chased recursively.
Finally, ancestors of the current module are searched in order.

This order is important when more than one modules
defines the same name and your module imports both.
Assuming your module don't define that name,
if you first import a module @code{A} then a module @code{B},
you'll see @code{B}'s binding.

If you import @code{A}, then @code{B}, then @code{A} again,
the last import takes precedence; that is, you'll see @code{A}'s
binding.

If two modules you want to use exports bindings of the same name
and you want to access both, you can add prefix to either one
(or both).  @xref{Using modules}, for the details.

@node Modules and libraries, Defining and selecting modules, Module semantics, Modules
@subsection Modules and libraries
@c NODE モジュールとライブラリ

Modules are run-time data structure; you can procedurally
create modules with arbitrary names at run-time.

However, most libraries use modules to create their own
namespace, so that they can control which bindings to be
visible from library users.   (This ``library'' is a general
term, broader than R7RS ``library'').

Usually a library is provided in the form of one or more Scheme
source file(s), so it is convenient to have a convention to map
module names to file names, and vice versa; then, you can load a
library file and import its module by one action with @code{use}
macro, for example.

For the time being, Gauche uses a simple rules for this mapping:
Module names are organized hierarchically, using period `@code{.}'
for separator, e.g. @code{gauche.mop.validator}.  If such a
module is requested and doesn't exist in the current running
environment, Gauche maps the module name to a pathname by
replacing periods to directory separator, i.e.
@code{gauche/mop/validator}, and look for
@code{gauche/mop/validator.scm} in the load paths.

Note that this is just a default behavior.
Theoretically, one Scheme source file may contain multiple
modules, or one module implementation may span to multiple files.
In future, there may be some hook to customize this mapping
for special cases.  So, when you are writing routines that
deal with modules and library files, do not apply the above
default rule blindly.   Gauche provides two procedures,
@code{module-name->path} and @code{path->module-name},
to do mapping for you (see @ref{Module introspection}, for details).

@node Defining and selecting modules, Using modules, Modules and libraries, Modules
@subsection Defining and selecting modules
@c NODE モジュールの定義と選択

@defspec define-module name body @dots{}
@var{Name} must be a symbol.
If a module named @var{name} does not exist, create one.
Then evaluates @var{body} sequentially in the module.
@end defspec

@defspec select-module name
Makes a module named @var{name} as the current module.
It is an error if no module named @var{name} exists.

If @code{select-module} is used in the Scheme file, its effect is
limited inside the file, i.e. even if you load/require a file that uses
@code{select-module} internally, the current module of requirer is
not affected.
@end defspec

@defspec with-module name body @dots{}
Evaluates @var{body} sequentially in the module
named @var{name}.  Returns the last result(s).
If no module named @var{name}, an error is signaled.
@end defspec

@defspec current-module
Evaluates to the current module in the compile context.
Note that this is a special form, not a function.
Module in Gauche is statically determined at compile time.

@example
(define-module foo
  (export get-current-module)
  (define (get-current-module) (module-name (current-module))))

(define-module bar
  (import foo)
  (get-current-module)) @result{} foo @r{; not bar}
@end example
@end defspec


@node Using modules, Module inheritance, Defining and selecting modules, Modules
@subsection Using modules
@c NODE モジュールの使用

@defspec export spec @dots{}
[R7RS base]
Makes bindings specified by each @var{spec} available
to modules that imports the current module.

Each @var{spec} can be either one of the following forms,
where @var{name} and @var{exported-name} are symbols.

@table @code
@item @var{name}
The binding with @var{name} is exported.
@item (rename @var{name} @var{exported-name})
The binding with @var{name} is exported under an alias @var{exported-name}.
@end table

Note: In Gauche, @code{export} is just a special form
you can put in the middle of the program, whereas
R7RS defines @code{export} as a library declaration,
that can only appear immediately below @code{define-library} form.
@xref{R7RS library form}, for the details.
@end defspec

@defspec export-all
Makes all bindings in the current module available to modules
that imports it.
@end defspec

@defspec import import-spec @dots{}
Makes all or some exported bindings in the module specified by
@var{import-spec} available in the current module.
The syntax of @var{import-spec} is as follows.

@example
<import-spec> : <module-name>
              | (<module-name> <import-option> ...)

<import-option> : :only (<symbol> ...)
                | :except (<symbol> ...)
                | :rename ((<symbol> <symbol>) ...)
                | :prefix <symbol>

<module-name> : <symbol>
@end example

The module named by @var{module-name} should exist
when the compiler sees this special form.

Imports are not transitive.  The modules that @var{module-name}s
are importing are not automatically imported to the current module.
This keeps modules' modularity; a library module can import whatever
modules it needs without worrying about polluting the namespace of
the user of the module.

@var{import-option} can be used to change how the bindings
are imported.   With @code{:only}, only the bindings with
the names listed in @code{<symbol> @dots{}} are imported.
With @code{:except}, the exported bindings except the ones
with the listed names are imported.
With @code{:rename}, the binding of each name in the first
of two-symbol list is renamed to the second of it.
With @code{:prefix}, the exported bindings are visible with
the names that are prefixed by the symbol to the original names.
Without import options, all the exported bindings are imported
without a prefix.

@example
(define-module M (export x y)
  (define x 1)
  (define y 2)
  (define z 3))

(import M)

x @result{} 1
z @result{} @r{error.  z is not exported from M}

(import (M :only (y)))

x @result{} @r{error.  x is not in :only list.}

(import (M :except (y)))

y @result{} @r{error.  y is excluded by :except.}

(import (M :prefix M:))

x @result{} @r{error}
M:x @result{} 1
M:y @result{} 2
@end example

If more than one import option are given, it is processed
as the order of appearance.  That is, if @code{:prefix}
comes first, then @code{:only} or @code{:except} has to
list the name with prefix.

Note: R7RS has @code{import} form, which has slightly different
syntax and semantics.  @xref{Three forms of import}, for the details.
@end defspec

@defmac use name :key only except rename prefix
A convenience macro that combines module imports and on-demand
file loading.  Basically, @code{(use foo)} is equivalent
to the following two forms:
@example
(require "foo")
(import foo)
@end example
That is, it loads the library file named ``@code{foo}'' (if not yet
loaded) which defines a module named @code{foo} in it,
and then import the module
@code{foo} into the current module.

The keyword argument @var{only}, @var{except}, and @var{prefix}
are passed to @code{import} as the import options.

@example
(use srfi-1 :only (iota) :prefix srfi-1:)

(srfi-1:iota 3) @result{} (0 1 2)
@end example


Although the files and modules are orthogonal concept,
it is practically convenient to separate files by modules.
Gauche doesn't force you to do so, and you can always use
@code{require} and @code{import} separately.  However, all
modules provided with Gauche are arranged so that they can be
used by @code{use} macro.

If a module is too big to fit in one file, you can split them
into several subfiles and one main file.  The main file defines
the module, and either loads, requires, or autoloads subfiles.

Actually, the file pathname of the given module name is
obtained by the procedure @code{module-name->path} below.
The default rule is to replace periods `@code{.}' in the @var{name}
for `@code{/}';  for example,
@code{(use foo.bar.baz)} is expanded to:
@example
(require "foo/bar/baz")
(import foo.bar.baz)
@end example
This is not very Scheme-ish way, but nevertheless convenient.
In future, there may be some mechanism to customize this mapping.

The file to be @code{use}'d must have explicit module selection
to have any toplevel definitions
(usually via @code{define-module}/@code{select-module} pair
or @code{define-library}).  If you get an error saying
``Attempted to create a binding in a sealed module:
module: #<module gauche.require-base>'', that's because the file
lacks module selection.  @xref{Require and provide}, for further
discussion.
@end defmac

@node Module inheritance, Module introspection, Using modules, Modules
@subsection Module inheritance
@c NODE モジュールの継承

The export-import mechanism doesn't work well in some cases, such as:

@itemize @bullet
@item You want to create a module that is mostly the same as the
existing one, but adding or altering some definitions.
@item You wrote a bunch of related modules that are often used together,
and not want your users to repeat a bunch of 'use' forms every time
they use your module.
@end itemize

You can use module inheritance in these cases.

@defmac extend module-name @dots{}
Makes the current module inherit from named modules.
The current inheritance information is altered by the
inheritance information calculated from given modules.

A new module inherits from @code{gauche} module when created.
If you put @code{(extend scheme)} in that module, for example,
the module resets to inherit directly from @code{scheme} module
that has only bindings defined in R5RS, hence, after the export
form, you can't use 'import' or any other @code{gauche}-specific
bindings in the module.

If a named module is not defined yet, @code{extend}
tries to load it, using the same convention @code{use} macro does.

A module can inherit multiple modules, exactly the same way as
a class can inherit from multiple classes.  The resolution of
order of inheritance needs to be explained a bit.

Each module has a @emph{module precedence list}, which lists
modules in the order of how they are searched.  When the module
inherits multiple modules, module precedence lists of inherited
modules are merged into a single list, keeping the constraints
that: (1) if a module A appears before module B in some module
precedence list, A has to appear before B in the resulting module
precedence list; and (2) if a module A appears before module B
in @code{extend} form, A has to appear before B in the resulting
module precedence list.   If no precedence list can be constructed
with these constraints, an error is signaled.
@end defmac

For example, suppose you wrote a library in modules
@code{mylib.base}, @code{mylib.util} and @code{mylib.system}.
You can bundle those modules into one module by creating
a module @code{mylib}, as follows:

@example
(define-module mylib
  (extend mylib.system mylib.util mylib.base))
@end example

The user of your module just says @code{(use mylib)} and
all exported symbols from three submodules become available.

@node Module introspection, Predefined modules, Module inheritance, Modules
@subsection Module introspection
@c NODE モジュールイントロスペクション

This subsection lists procedures that operates on modules at run-time.
With these procedures you can introspect the modules, create new modules
procedurally, or check the existence of certain modules/libraries, for
example.  However, don't forget that modules are primarily
compile-time structures.  Tweaking modules at run-time is only
for those who know what they are doing.

@deftp {Builtin Class} <module>
@clindex module
A module class.
@end deftp

@defun module? obj
Returns true if @var{obj} is a module.
@end defun

@defun find-module name
Returns a module object whose name is a symbol @var{name}.
If the named module doesn't exist, @code{#f} is returned.
@end defun

@defun make-module name :key if-exists
Creates and returns a module that has symbol @var{name}.
If the named module already exists, the behavior is specified by
@var{if-exists} keyword argument.  If it is @code{:error} (default),
an error is signaled.  If it is @code{#f}, @code{#f} is returned.

Note that creating modules on-the-fly isn't usually necessary
for ordinal scripts, since to execute already written program requires modules
to be specified by name, i.e. syntax @code{define-module}, @code{import},
@code{extend}, @code{with-module} all take module names, not
module objects.
It is because module are inherently compile-time structures.
However, there are some cases that dynamically created modules
are useful, especially the program itself is dynamically created.
You can pass a module to @code{eval} to compile and
evaluate such dynamically created
programs in it (@pxref{Eval and repl}).

You can also pass @code{#f} to @var{name} to create
@emph{anonymous} module.   Anonymous modules can't be
looked up by @code{find-module}, nor can be imported
or inherited (since @code{import} and @code{extend} take
module names, not modules).
It is useful when you want to have a temporary, segregated namespace
dynamically---for example, you can create an anonymous module
to evaluate code fragments sent from other program, and
discards the module when the connection is terminated.
Anonymous modules are not registered in the system dictionary
and are garbage collected when nobody keeps reference to it.

R7RS provides another way to create a transient module
with @code{environment} procedure.  @pxref{R7RS eval} for the
details.
@end defun

@defun all-modules
Returns a list of all named modules.
Anonymous modules are not included.
@end defun

@defun module-name module
@defunx module-imports module
@defunx module-exports module
@defunx module-table module
Accessors of a module object.  Returns the name of the module (a symbol),
list of imported modules, list of exported symbols, and a hash table
that maps symbols to bindings, of the @var{module} are returned,
respectively.

If the @var{module} exports all symbols, @code{module-exports} returns
@code{#t}.

It is an error to pass a non-module object.
@end defun

@defun module-parents module
@defunx module-precedence-list module
Returns the information of module inheritance.
@code{Module-parents} returns the modules @var{module} directly inherits
from.  @code{Module-precedence-list} returns the module precedence
list of @var{module} (@pxref{Module inheritance}).
@end defun

@defun global-variable-bound? module symbol
Returns true if @var{symbol}'s global binding is visible
from @var{module}.  @var{Module} must be a module object or
a symbol name of an existing module.

Note: there used to be the @code{symbol-bound?} procedure to
check whether a global variable is bound.  It is deprecated and
the new code should use @code{global-variable-bound?} instead.
The reason of change is that because of the name @code{symbol-bound?} and
the fact that it assumes current-module by default, it gives
an illusion as if a global bound value is somewhat 'stored'
in a symbol itself (like CommonLisp's model).  It caused a lot
of confusion when the current module differs between
compile-time and runtime.  The new name and API made it clear
that you are querying module's property.
@end defun

@defun global-variable-ref module symbol :optional default
Returns a value globally bound to the @var{symbol} visible
from @var{module}.  @var{Module} must be a module object or
a symbol name of an existing module.  If there's no visible
global binding from @var{module} for @var{symbol},
an error is signaled, unless the @var{default} argument is
provided, in which case it is returned instead.
@end defun

@defun module-name->path symbol
Converts a module name @var{symbol} to a fragment of pathname string
(which you use for @code{require} and @code{provide}).
@end defun

@defun path->module-name string
Reverse function of @code{module-name->path}.
@end defun

If you want to find out
specific libraries and/or modules are installed in the system and
available from the program, see @ref{Operations on libraries}.

@node Predefined modules,  , Module introspection, Modules
@subsection Predefined modules
@c NODE 組み込みモジュール

Several modules are predefined in Gauche.

@deftp {Builtin Module} null
@mdindex null
This module corresponds to the null environment referred in R5RS.
This module contains only syntactic bindings of R5RS syntax.
@end deftp

@deftp {Builtin Module} scheme
@mdindex scheme
This module contains all the binding of @code{null} module,
and the binding of procedures defined in R5RS.
@end deftp

Note that if you change the current module to @code{null} or
@code{scheme} by @code{select-module}, there will be no way
to switch back to other modules, since module-related syntaxes
and procedures are not visible from @code{null} and @code{scheme}
modules.

@deftp {Builtin Module} gauche
@mdindex gauche
This module contains all the bindings of @code{scheme} module,
plus Gauche specific built-in procedures.
@end deftp

@deftp {Builtin Module} user
@mdindex user
This module is the default module the user code is compiled.
all the bindings of @code{gauche} module is imported.
@end deftp

@deftp {Builtin Module} gauche.keyword
@deftpx {Builtin Module} keyword
@mdindex gauche.keyword
@mdindex keyword
When Gauche is running with @code{GAUCHE_KEYWORD_IS_SYMBOL} mode (default)
keywords (symbols beginning with @code{:}) is automatically bound
to itself in these modules.
(@pxref{Keywords}, for the details.)

The @code{keyword} module doesn't export those bindings, while
@code{gauche.keyword} does.  The former is intended to be
used internally; the programmer need to know the latter.

If you use the default module inheritance,
you don't need to use this module, since
the @code{keyword} module is included in the inheritance chain.
If you don't inherit @code{gauche} module, however, importing the
@code{gauche.keyword} module gives you access to the keywords without quotes.
For example, R7RS programs
and libraries would require either @code{(import (gauche keyword))}
or @code{(import (gauche base))} (the latter inherits
@code{gauche.keyword}), or you have to quote all keywords.

The following R7RS program imports @code{gauche.base}; it makes gauche
built-in identifiers, @emph{and} all self-bound keywords, available:

@example
;; R7RS program
(import (scheme base)
        (gauche base))  ; import gauche builtins and keywords

;; You can use :directory without quote, for it is bound to itself.
(sys-exec "ls" '("ls" "-l") :directory "/")
@end example

If you use more sophisticated import tricks, however, keep in mind
that keywords are just imported symbols by default.
The following code imports
Gauche builtin identifiers with prefix @code{gauche/}.  That causes
keywords, imported via inheritance, also get the same prefix; if
you don't want to bother adding prefix to all keywords or
quote them, import @code{gauche.keyword} separately.

@example
;; R7RS program
(import (scheme base)
        (prefix (gauche base) gauche/) ; use gauche builtin with gauche/ prefix
        (gauche keyword))              ; imports keywords

;; Without importing gauche.keyword,
;; you need to write ':directory
(gauche/sys-exec "ls" '("ls" "-l") :directory "/")
@end example


@end deftp


@c Local variables:
@c mode: texinfo
@c coding: utf-8
@c end:
@node Macros, Core library, Core syntax, Top
@chapter Macros
@c NODE マクロ

Macro of Lisp-family language is very different feature from
ones of other languages, such as C preprocessor macros.
It allows you to extend the original language syntax.
You can use macros to change Gauche syntax
so that you can run a Scheme program written to other Scheme
implementations, and you can even design your own mini-language
to solve your problem easily.

Gauche supports hygienic macros, which allows to write safe macros
by avoiding name collisions.  If you know traditional Lisp macros
but new to hygienic macros, they might seem confusing at first.
We have an introductory section (@ref{Why hygienic?}) for those who
are not familiar with hygienic macros; if you know what they are,
you can skip the section.

@menu
* Why hygienic?::
* Hygienic macros::
* Traditional macros::
* Hybrid macros::
* Identifiers::
* Debugging macros::
* Macro utilities::
@end menu

@node Why hygienic?, Hygienic macros, Macros, Macros
@section Why hygienic?
@c NODE なぜ衛生的マクロか

Lisp macro is a programmatic transformation of source code.
A @emph{macro transformer} is a procedure that takes a subtree of
source code, and returns a reconstructed tree of source code.

The traditional Lisp macros take the input source code as
an S-expression, and returns the output as another S-expression.
Gauche supports that type of macro, too, with @code{define-macro} form.
Here's the simple definition of @code{when} with the traditional macro.

@example
(define-macro (when test . body)
  `(if ,test (begin ,@@body)))
@end example

For example,
if the macro is used as @code{(when (zero? x) (print "zero") 'zero)},
the above macro transformer rewrites it to
@code{(if (zero? x) (begin (print "zero") 'zero))}.  So far, so good.

But what if the @code{when} macro is used in an environment
where the names @code{begin} or @code{if} is bound to nonstandard values?

@example
(let ([begin list])
  (when (zero? x) (print "zero") 'zero))
@end example

The expanded result would be as follows:

@example
(let ([begin list])
  (if (zero? x) (begin (print "zero") 'zero)))
@end example

This obviously won't work as the macro writer intended, since
@code{begin} in the expanded code refers to the locally bound name.

This is a form of @emph{variable capture}.  Note that, when Lisp
people talk about variable capture of macros, it often means
another form of capture, where the temporary variables inserted
by a macro would unintentionally capture the variables passed to
the macro.   That kind of variable capture can be avoided easily
by naming the temporary variables something that never conflict,
using @code{gensym}.

On the other hand, the kind of variable capture in the above example
can't be avoided by @code{gensym}, because @code{(let ([begin list]) ...)}
part isn't under macro writer's control.  As a macro writer, you can
do nothing to prevent the conflict, just hoping the
macro user won't do such a thing.  Sure, rebinding @code{begin} is
a crazy idea that nobody perhaps wants to do, but it can happen on
@emph{any} global variable, even the ones you define for your library.

Various Lisp dialects have tried to address this issue in different
ways.  Common Lisp somewhat relies on the common sense of the
programmer---you can use separate packages to reduce the chance
of accidental conflict but can't prevent the user from binding
the name in the same package.
(The Common Lisp spec says it is undefined if you locally rebind
names of CL standard symbols; but it doesn't prevent you from locally
rebinding symbols that are provided by user libraries.)

Clojure introduced a way to directly refer to the toplevel variables
by a namespace prefix, so it can bypass whatever local bindings of
the same name (also, it has a sophisticated quasiquote form that
automatically renames free variables to refer to the toplevel ones).
It works, as far as there are no local macros.  With
local macros, you need a way to distinguish different local bindings
of the same name, as we see in the later examples.  Clojure's way
can only distinguish between local and toplevel bindings.
It's ok for Clojure which doesn't have local macros,
but in Scheme, we prefer uniform and orthogonal axioms---if functions
can be defined locally with lexical scope, why not macros?

Let's look at the local macro with lexical scope.  For the sake of
explanation, suppose we have
@emph{hypothetical} local macro binding form, @code{let-macro},
that binds a local identifiers to a macro transformer.
(We don't actually have @code{let-macro}; what we have is
@code{let-syntax} and @code{letrec-syntax}, which have slightly
different way to call macro transformers.  But here @code{let-macro} may
be easier to understand as it is similar to @code{define-macro}.)

@example
(let ([f (^x (* x x))])
  (let-macro ([m (^[expr1 expr2] `(+ (f ,expr1) (f ,expr2)))])
    (let ([f (^x (+ x x))])
      (m 3 4))))    ; [1]
@end example

The local identifier @var{m} is bound to a macro transformer
that takes two expressions, and returns an S-expression.
So, the @code{(m 3 4)} form [1] would be expanded into
@code{(+ (f 3) (f 4))}.  Let's rewrite the above expression
with the expanded form.  (After expansion, we no longer
need @code{let-macro} form, so we don't include it.)

@example
(let ([f (^x (* x x))])
  (let ([f (^x (+ x x))])
    (+ (f 3) (f 4))))  ; [2]
@end example

Now, the question.  Which binding @code{f} in the expanded form [2]
should refer?  If we literally interpret the expansion,
it would refer to the inner binding @code{(^x (+ x x))}.
However, following the Scheme's scoping principle, the outer
code should be fully understood regardless of inner code:

@example
(let ([f (^x (* x x))])
  (let-macro ([m (^[expr1 expr2] `(+ (f ,expr1) (f ,expr2)))])
    ;; The code here isn't expected to accidentally alter
    ;; the behavior defined outside.
    ))
@end example

The macro writer may not know the inner @code{let} shadows
the binding of @code{f} (the inner forms may be @code{include}d,
or may be changed by other person who didn't fully realize
the macro expansion needs to refer outer @code{f}).

To ensure the local macro to work regardless of what's placed
inside @code{let-macro}, we need a sure way to refer the outer
@code{f} in the result of macro expansion.  The basic idea is
to ``mark''
the names inserted by the macro transformer @code{m}---which are
@code{f} and @code{+}---so that we can distinguish two @code{f}'s.

For example, if we would rewrite the entire form and @emph{renames}
corresponding local identifiers as follows:

@example
(let ([f_1 (^x (* x x))])
  (let-macro ([m (^[expr1 expr2] `(+ (f_1 ,expr1) (f_1 ,expr2)))])
    (let ([f_2 (^x (+ x x))])
      (m 3 4))))
@end example

Then the naive expansion would correctly preserve scopes; that is,
expansion of @code{m} refers @code{f_1}, which wouldn't conflict
with inner name @code{f_2}:

@example
(let ([f_1 (^x (* x x))])
  (let ([f_2 (^x (+ x x))])
    (+ (f_1 3) (f_1 4))))
@end example

(You may notice that this is similar to lambda calculus treating
lexical bindings with higher order functions.)

The above example deal with avoiding @code{f} referred from the
macro @emph{definition} (which is, in fact, @code{f_1}) from being
shadowed
by the binding of @code{f} at the macro @emph{use} (which is @code{f_2}).

Another type of variable capture (the one most often talked about,
and can be avoided by @code{gensym})
is that a variable in macro use site is shadowed by the binding introduced
by a macro definition.  We can apply the same renaming strategy to
avoid that type of capture, too.  Let's see the following example:

@example
(let ([f (^x (* x x))])
  (let-macro ([m (^[expr1] `(let ([f (^x (+ x x))]) (f ,expr1)))])
    (m (f 3))))
@end example

The local macro inserts binding of @code{f} into the expansion.  
The macro use @code{(m (f 3))} also contains a reference to @code{f},
which should be the outer @code{f},
since the macro use is lexically outside of the @code{let} inserted
by the macro.

We could rename @code{f}'s according to its lexical scope:

@example
(let ([f_1 (^x (* x x))])
  (let-macro ([m (^[expr1] `(let ([f_2 (^x (+ x x))]) (f_2 ,expr1)))])
    (m (f_1 3))))
@end example

Then expansion unambiguously distinguish two @code{f}'s.

@example
(let ([f_1 (^x (* x x))])
  (let ([f_2 (^x (+ x x))])
    (f_2 (f_1 3))))
@end example

This is, in principle, what hygienic macro is about (well, almost).
In reality, we don't rename everything in batch.
One caveat is in the latter example---we statically renamed
@code{f} to @code{f_2}, but it is possible that the macro
recursively calls itself, and we have to distinguish @code{f}'s 
introduced in every individual expansion of @code{m}.
So macro expansion and renaming should work together.

There are multiple strategies to implement it, and the
Scheme standard doesn't want to bind implementations to single
specific strategy.  The standard only states the properties
the macro system should satisfy, in two concise sentences:

@quotation
If a macro transformer inserts a binding for an
identifier (variable or keyword), the identifier will in effect be
renamed throughout its scope to avoid conflicts with
other identifiers.

If a macro transformer inserts a free reference to an
identifier, the reference refers to the binding that was
visible where the transformer was specified,
regardless of any local bindings that surround the use of the macro.
@end quotation

Just from reading this,
it may not be obvious @emph{how} to realize those properties, and
the existing hygienic macro mechanisms (e.g. @code{syntax-rules}) hide
the ``how'' part.  That's probably one of the reason some people
feel hygienic macros are difficult to grasp.  It's like
continuations---its description is concise but at first
you have no idea how it works; then, through experience,
you become familiarized yourself to it, and then you reread
the original description and understand it says exactly what it is.

This introduction may not answer @emph{how} the hygienic macro
realizes those properties, but I hope it showed @emph{what} it does
and @emph{why} it is needed.  In the following chapters we introduce
a couple of hygienic macro mechanisms Gauche supports, with examples,
so that you can familiarize yourself to the concept.


@node Hygienic macros, Traditional macros, Why hygienic?, Macros
@section Hygienic macros
@c NODE 衛生的マクロ

@subheading Macro bindings

The following forms establish bindings of @var{name} and
a macro transformer created by @var{transformer-spec}.  The
binding introduced by these forms shadows
a binding of @var{name} established in outer scope, if there's any.

For toplevel bindings, it will shadow bindings of @var{name} imported
or inherited from other modules (@pxref{Modules}).
(Note: This toplevel shadowing behavior is Gauche's extension;
in R7RS, you shouldn't redefine imported bindings, so the portable
code should avoid it.)

The effect is undefined if you bind the same name more than once
in the same scope.

The @var{transformer-spec} can be either one of @code{syntax-rules}
form, @code{er-macro-transformer} form, or another macro keyword
or syntactic keyword.  We'll explain them later.

@defspec define-syntax name transformer-spec
[R7RS base]
If this form appears in toplevel, it binds toplevel @var{name} to
a macro transformer defined by @var{transformer-spec}.

If this form appears in the @emph{declaration} part of
body of @code{lambda} (internal define-syntax), @code{let} and
other similar forms, it binds @var{name} locally within that body.
Internal @code{define-syntax}es are converted to @code{letrec-syntax},
just like internal @code{define}s are converted to @code{letrec*}.
@end defspec

@defspec let-syntax ((name transformer-spec) @dots{}) body
@defspecx letrec-syntax ((name transformer-spec) @dots{}) body
[R7RS base]
Defines local macros.  Each @var{name} is bound to a macro
transformer as specified by the corresponding @var{transformer-spec},
then @code{body} is expanded.  With @code{let-syntax},
@var{transformer-spec} is evaluated with the scope
surrounding @code{let-syntax}, while with @code{letrec-syntax}
the bindings of @var{name}s are included in the scope where
@var{transformer-spec} is evaluated.  Thus @code{letrec-syntax}
allows mutually recursive macros.
@end defspec

@subheading Transformer specs

The @var{transformer-spec} is a special expression that evaluates
to a macro transformer.  It is evaluated in a different phase
than the other expressions, since macro transformers must be
executed during compiling.  So there are some restrictions.

At this moment, only one of the following expressions are allowed:

@enumerate
@item
A @code{syntax-rules} form.   This is called ``high-level'' macro,
for it uses pattern matching entirely, which is basically a
different declarative language from Scheme, thus putting the
complication of the phasing and hygiene issues completely under the hood.
Some kind of macros are easier to write in @code{syntax-rules}.
@xref{Syntax-rules macro transformer}, for further description.

@item
An @code{er-macro-transformer} form.  This employs @emph{explicit-renaming}
(ER) macro, where you can use arbitrary Scheme code to transform
the program, with required renaming to keep hygienity.  The legacy
Lisp macro can also be written with ER macro if you don't use
renaming.  @xref{Explicit-renaming macro transformer}, for the details.

@item
Macro or syntax keyword.  This is Gauche's extension, and can be
used to define alias of existing macro or syntax keyword.
@example
(define-syntax si if)
(define écrivez write)

(si (< 2 3) (écrivez "oui"))
@end example
@end enumerate



@menu
* Syntax-rules macro transformer::
* Explicit-renaming macro transformer::
@end menu

@node Syntax-rules macro transformer, Explicit-renaming macro transformer, Hygienic macros, Hygienic macros
@subsection Syntax-rules macro transformer
@c NODe Syntax-rulesマクロ変換器

@defspec syntax-rules (literal @dots{}) clause clause2 @dots{}
@defspecx syntax-rules ellipsis (literal @dots{}) clause clause2 @dots{}
[R7RS base]
This form creates a macro transformer by pattern matching.

Each @var{clause} has the following form:

@example
(@var{pattern} @var{template})
@end example

A @var{pattern} denotes a pattern to be matched to the macro call.
It is an S-expression that matches if the macro call has the same
structure, except that symbols in @var{pattern} can match a whole subtree
of the input; the matched symbol is called a @emph{pattern variable},
and can be referenced in the @var{template}.

For example, if a pattern is @code{(_ "foo" (a b))}, it can match the
macro call @code{(x "foo" (1 2))}, or @code{(x "foo" (1 (2 3)))}, but does
not match @code{(x "bar" (1 2))}, @code{(x "foo" (1))} or
@code{(x "foo" (1 2) 3)}.  You can also match repeating structure or
literal symbols; we'll discuss it fully later.

Clauses are examined in order to see if the macro call form matches
its pattern.  If matching pattern is found, the corresponding @var{template}
replaces the macro call form.  A pattern variable in the template is
replaced with the subtree of input that is bound to the pattern variable.

Here's a definition of @code{when} macro in @ref{Why hygienic?},
using @code{syntax-rules}:

@example
(define-syntax when
  (syntax-rules ()
    [(_ test body ...) (if test (begin body ...))]))
@end example

The pattern is @code{(_ test body ...)}, and the template is
@code{(if test (begin body ...))}.
The ellipsis @code{...} is a symbol; we're not omitting code here.
It denotes that the previous pattern (@code{body}) may
repeat zero or more times.

So, if the @code{when} macro is called as
@code{(when (zero? x) (print "huh?") (print "we got zero!"))},
the macro expander first check if the input matches the pattern.

@itemize @bullet
@item
The @var{test} in pattern matches the input @code{(zero? x)}.
@item
The @var{body} in pattern matches the input @code{(print "huh?")} 
@emph{and} @code{(print "we got zero!")}.
@end itemize

The matching of @var{body} is a bit tricky; as a pattern variable,
you may think that @var{body} works like an array variable, each element
holds each match---and you can use them in similarly
repeating substructures in template.
Let's see the template, now that the input fully matched the pattern.

@itemize @bullet
@item
In the template, @code{if} and @code{begin} are not pattern variable,
since they are not appeared in the pattern.
So they are inserted as identifiers---that is, hygienic symbols effectively
renamed to make sure to refer to the global @code{if} and @code{begin},
and will be unaffected by the macro use environment.
@item
The @var{test} in the template is a pattern variable, so it is replaced
for the matched value, @code{(zero? x)}.
@item
The @var{body} is also a pattern variable.  The important point is
that it is also followed by ellipsis.  So we repeat @var{body} as many
times as the number of matched values.
The first value, @code{(print "huh?")}, and the second value,
@code{(print "we got zero!")}, are expanded here.
@item
Hence, we get
@code{(if (zero? x) (begin (print "huh?") (print "we got zero!")))}
as the result of expansion.  (With the note that @code{if} and @code{begin}
refers to the identifiers visible from the macro definition environment.)
@end itemize

The expansion of ellipses is quite powerful.  In the template,
the ellipses don't need to follow the sequence-valued pattern variable
immediately; the variable can be in a substructure, as long as the
substructure itself is followed by an ellipsis.
See the following example:

@example
(define show
  (syntax-rules ()
    [(_ expr ...)
     (begin 
       (begin (write 'expr) (display "=") (write expr) (newline)) 
       ...)]))
@end example

If you call this macro as follows:

@example
(show (+ 1 2) (/ 3 4))
@end example

It is expanded to the following form, modulo hygienity:

@example
(begin
  (begin (write '(+ 1 2)) (display "=") (write (+ 1 2)) (newline))
  (begin (write '(/ 3 4)) (display "=") (write (/ 3 4)) (newline)))
@end example

So you'll get this output.

@example
(+ 1 2)=3
(/ 3 4)=3/4
@end example

You can also match with a repetition of substructures in the pattern.
The following example is a simplified @code{let} that expands to
@code{lambda}:

@example
(define-syntax my-let
  (syntax-rules ()
    [(_ ((var init) ...) body ...)
     ((lambda (var ...) body ...) init ...)]))
@end example

If you call it as @code{(my-let ((a expr1) (b expr2)) foo)},
then @var{var} is matched to @code{a} and @code{b},
while @var{init} is matched to @code{expr1} and @code{expr2}, respectively.
They can be used separately in the template.

Suppose ``level'' of a pattern variable
means the number of nested ellipses that designate repetition of the pattern
variable.
A subtemplate can be followed as many ellipses as the maximum level of
pattern variables in the subtemplate.
In the following example, the level of pattern variable @code{a} is 1
(it is repeated by the last ellipsis in the pattern),
while the level of @code{b} is 2 (repeated by the last two ellipses),
and the level of @code{c} is 3 (repeated by all the ellipses).

@example
(define-syntax ellipsis-test
  (syntax-rules ()
    [(_ (a (b c ...) ...) ...)
     '((a ...)
       (((a b) ...) ...)
       ((((a b c) ...) ...) ...))]))
@end example

In this case, the subtemplate @code{a} must be repeated by one level
of ellipsis, @code{(a b)} must be repeated by two,
and @code{(a b c)} must be repeated by three.

@example
(ellipsis-test (1 (2 3 4) (5 6)) (7 (8 9 10 11)))
 @result{} ((1 7)
    (((1 2) (1 5)) ((7 8)))
    ((((1 2 3) (1 2 4)) ((1 5 6))) (((7 8 9) (7 8 10) (7 8 11)))))
@end example

In the template, more than one ellipsis directly follow a subtemplate,
splicing the leaves into the surrounding list:

@example
(define-syntax my-append
  (syntax-rules ()
    [(_ (a ...) ...)
     '(a ... ...)]))

(my-append (1 2 3) (4) (5 6))
  @result{} (1 2 3 4 5 6)

(define-syntax my-append2
  (syntax-rules ()
    [(_ ((a ...) ...) ...)
     '(a ... ... ...)]))

(my-append2 ((1 2) (3 4)) ((5) (6 7 8)))
  @result{} (1 2 3 4 5 6 7 8)
@end example

Note: Allowing multiple ellipses to directly follow a subtemplate,
and a pattern variable in a subtemplate to be enclosed within more
than the variable's level of nesting of ellipses, are extension to
R7RS, and defined in SRFI-149.  In the above examples, 
@code{ellipsis-test}, @code{my-append} and @code{my-append2} are
outside of R7RS.

Identifiers in a pattern is treated as pattern variables.  But sometimes
you want to match a specific identifier in the input.  For example,
the built-in @code{cond} and @code{case} detects an identifier @code{else}
as a special identifier.  You can use @var{literal} @dots{} for that.
See the following example.

@example
(define-syntax if+
  (syntax-rules (then else)
    [(_ test then expr1 else expr2) (if test expr1 expr2)]))
@end example

The identifiers listed as the literals don't become pattern variables,
but literally match the input.  If the input doesn't have the same identifier
in the position, match fails.

@example
(if+ (even? x) then (/ x 2) else (/ (+ x 1) 2))
 @r{expands into} (if (even? x) (/ x 2) (/ (+ x 1) 2))

(if+ (even? x) foo (/ x 2) bar (/ (+ x 1) 2))
 @result{} ERROR: malformed if+
@end example

We've been saying identifiers instead of symbols.  Roughly speaking,
an identifier is a symbol with the surrounding syntactic environment,
so that they can keep identity under renaming of hygiene macro.

The following example fails, because the @code{else} passed to the
@code{if+} macro is the one locally bound by @code{let}, which is
different from the global @code{else} when @code{if+} was defined,
hence they don't match.

@example
(let ((else #f))
  (if+ (even? x) then (/ x 2) else (/ (+ x 1) 2))
  @result{} ERROR: malformed if+
@end example
@end defspec

@node Explicit-renaming macro transformer,  , Syntax-rules macro transformer, Hygienic macros
@subsection Explicit-renaming macro transformer
@c NODE Explicit-renamingマクロ変換器

@defspec er-macro-transformer procedure-expr
Creates a macro transformer from the given @var{procedure-expr}.
The created macro transformer has to be bound to the syntactic keyword
by @code{define-syntax}, @code{let-syntax} or @code{letrec-syntax}.
Other use of macro transformers is undefined.

The @var{procedure-expr} must evaluate to a procedure that takes
three arguments; @var{form}, @var{rename} and @var{id=?}.

The @var{form} argument receives the S-expression of
the macro call.  The @var{procedure-expr} must return an
S-expression as the result of macro expansion.  This part is pretty much
like the traditional lisp macro.  In fact, if you ignore @var{rename}
and @var{id=?}, the semantics is the same as the traditional
(unhygienic) macro.  See the following example
(Note the use of @code{match}; it is a good
tool to decompose macro input):

@example
(use util.match)

;; Unhygienic 'when-not' macro
(define-syntax when-not
  (er-macro-transformer
    (^[form rename id=?]
      (match form
        [(_ test expr1 expr ...)
         `(if (not ,test) (begin ,expr1 ,@@expr))]
        [_ (error "malformed when-not:" form)]))))

(macroexpand '(when-not (foo) (print "a") 'boo))
  @result{} (if (not (foo)) (begin (print "a") 'boo))
@end example

This is ok as long as you know you don't need hygiene---e.g. when
you only use this macro locally in your code, knowing all the
macro call site won't contain name conflicts.  However, if you
provide your @code{when-not} macro for general use,
you have to protect namespace pollution around the macro use.
For example, you want to make sure your macro work even if it is
used as follows:

@example
(let ((not values))
  (when-not #t (print "This shouldn't be printed")))
@end example

The @var{rename} argument passed to @var{procedure-expr} is
a procedure that takes a symbol (or, to be precise, a symbol or
an identifier) and @emph{effectively renames} it to a unique 
identifier that keeps identity within the macro definition environment and
won't be affected in the macro use environment.

As a rule of thumb, you have to pass
@emph{all new identifiers you insert into macro output} to the
@var{rename} procedure to keep hygiene.  In our @code{when-not} macro,
we insert @code{if}, @code{not} and @code{begin} into the macro output,
so our hygienic macro would look like this:

@example
(define-syntax when-not
  (er-macro-transformer
    (^[form rename id=?]
      (match form
        [(_ test expr1 expr ...)
         `(,(rename 'if) (,(rename 'not) ,test)
            (,(rename 'begin) ,expr1 ,@@expr))]
        [_ (error "malformed when-not:" form)]))))
@end example

This is cumbersome and makes it hard to read the macro, so Gauche
provides an auxiliary macro @code{quasirename}, which works like
@code{quasiquote} but renaming identifiers in the form.  See the
entry of @code{quasirename} below for the details.  You can write
the hygienic @code{when-not} as follows:

@example
(define-syntax when-not
  (er-macro-transformer
    (^[form rename id=?]
      (match form
        [(_ test expr1 expr ...)
         (quasirename rename
           `(if (not ,test) (begin ,expr1 ,@@expr)))]
        [_ (error "malformed when-not:" form)]))))
@end example

You can intentionally break hygiene by inserting a symbol
without renaming.  The following code implements
@emph{anaphoric} @code{when}, meaning the result of the
test expression is available in the @var{expr1} @var{exprs} @dots{}
with the name @code{it}.  Since the binding of the identifier @code{it}
does not exist in the macro use site, but rather injected into
the macro use site by the macro expander, it is unhygienic.

@example
(define-syntax awhen
  (er-macro-transformer
    (^[form rename id=?]
      (match form
        [(_ test expr1 expr ...)
         `(,(rename 'let1) it ,test     ; 'it' is not renamed
             (,(rename 'begin) ,expr1 ,@@expr))]))))
@end example

If you use @code{quasirename}, you can write @code{,'it} to prevent
@code{it} from being renamed:

@example
(define-syntax awhen
  (er-macro-transformer
    (^[form rename id=?]
      (match form
        [(_ test expr1 expr ...)
         (quasirename rename
           `(let1 ,'it ,test
              (begin ,expr1 ,@@expr)))]))))
@end example

Here's an example:

@example
(awhen (find odd? '(0 2 8 7 4))
  (print "Found odd number:" it))
 @result{} @r{prints} Found odd number:7
@end example

Finally, the @var{id=?} argument to the @var{procedure-expr} is
a procedure that takes two arguments, and returns @code{#t} iff
both are identifiers and either both are referring to the same binding
or both are free.  It can be used to compare literal syntactic keyword
(e.g. @code{else} in @code{cond} and @code{case} forms) hygienically.

The following @code{if=>} macro behaves like @code{if}, except that
it accepts @code{(if=> test => procedure)} syntax,
in which @code{procedure} is called with the value of @code{test}
if it is not false (similar to @code{(cond [test => procedure])} syntax).
The symbol @code{=>} must match hygienically,
that is, it must refer to the same binding as in the macro definition.

@example
(define-syntax if=>
  (er-macro-transformer
    (^[form rename id=?]
      (match form
        [(_ test a b)
         (if (id=? (rename '=>) a)
           (quasirename rename
             `(let ((t ,test))
                (if t (,b t))))
           (quasirename rename
             `(if ,test ,a ,b)))]))))
@end example

The call @code{(rename '=>)} returns an identifier that captures
the binding of @code{=>} in the macro definition, and using
@code{id=?} with the thing passed to the macro argument
checks if both refer to the same binding.

@example
(if=> 3 => list)  @result{} (3)
(if=> #f => list) @result{} #<undef>

;; If the second argument isn't =>, if=> behaves like ordinary if:
(if=> #t 1 2)     @result{} 1

;; The binding of => in macro use environment differs from
;; the macro definition environment, so this if=> behaves like
;; ordinary if, instead of recognizing literal =>.
(let ((=> 'oof)) (if=> 3 => list)) @result{} oof
@end example
@end defspec

@defmac quasirename renamer quasiquoted-form
It works like quasiquote, except that the symbols and identifiers
that appear in the ``literal'' portion of @var{form} (i.e. outside
of @code{unquote} and @code{unquote-splicing}) are replaced
by the result of applying @var{rename} on themselves.

The @var{quasiquote-form} argument must be a quasiquoted form.
The outermost quasiquote @code{`} is consumed by @code{quasirename} and 
won't appear in the output.
The reason we require it is to make nested quasiquotes/quasirenames work.

For example, a form:
@example
(quasirename r `(a ,b c "d"))
@end example
would be equivalent to write:
@example
(list (r 'a) b (r 'c) "d")
@end example

This is not specifically tied to macros; the @var{renamer} can
be any procedure that takes one symbol or identifier argument:

@example
(quasirename (^[x] (symbol-append 'x: x)) `(+ a ,(+ 1 2) 5))
  @result{} (x:+ x:a 3 5)
@end example

However, it comes pretty handy to construct the result form
in ER macros.  Compare the following two:

@example
(use util.match)

;; using quasirename
(define-syntax swap
  (er-macro-transformer
    (^[f r c]
      (match f
        [(_ a b) (quasirename r
                   `(let ((tmp ,a))
                      (set! ,a ,b)
                      (set! ,b tmp)))]))))

;; not using quasirename
(define-syntax swap
  (er-macro-transformer
    (^[f r c]
      (match f
        [(_ a b) `((r'let) (((r'tmp) ,a))
                     ((r'set!) ,a ,b)
                     ((r'set!) ,b (r'tmp)))]))))
@end example

Note: In Gauche 0.9.7 and before, @code{quasirename} didn't use
quasiquoted form as the second argument; you can write
@code{(quasirename r form)} instead of
@code{(quasirename r `form)}.

For the backward compatibility,
we support the form without quasiquote by default for a while.

If you already have a quasirename form that does intend to produce
a quasiquoted form, you have to rewrite it with double quasiquote:
@code{(quasirename r ``form)}.

To help transition, the handling of quasiquote in of @code{quasirename}
can be customized with the environment variable
@code{GAUCHE_QUASIRENAME_MODE}.  It can have one of the following
values:

@table @code
@item legacy
@code{Quasirename} behaves the same way as
0.9.7 and before; use this to run code for 0.9.7 without any change.
@item compatible
@code{Quasirename} behaves as described in this entry; if
@var{form} lacks a quasiquote, it silently assumes one.
Existing code should work, except the rare case when you intend
to return a quasiquoted form.
@item warn
@code{Quasirename} behaves as described in this entry, but
warns if @var{form} lacks a quasiquote.
@item strict
@code{Quasirename} raises an error if @var{form} lacks a quasiquote.
This will be the default behavior in future.
@end table
@end defmac

@node Traditional macros, Hybrid macros, Hygienic macros, Macros
@section Traditional macros
@c NODE 伝統的なマクロ

@defspec define-macro name procedure
@defspecx define-macro (name . formals) body @dots{}
Defines @var{name} to be a global macro whose transformer is @var{procedure}.
The second form is a shorthand notation of the following form:
@example
(define-macro name (lambda formals body @dots{}))
@end example

When a form @code{(name @var{arg} @dots{})} is seen by the compiler,
it calls @var{procedure} with @var{arg} @dots{}.  When @var{procedure}
returns, the compiler inserts the returned form in place of the original
form, and compile it again.

To avoid name conflict with the bindings inserted by the macro,
you can use @code{gensym}, just like traditional Lisp macros
(@pxref{Symbols}).

@example
(define-macro (if-let1 var test then else)
  (let1 tmp (gensym)
    `(let ((,tmp ,test))
       (if ,tmp ,then ,else))))

(macroexpand '(if-let1 v (find odd? '(2 4 6 7 8))
                 (* v v)
                 #f))
  @result{} (let ((#:G1013 (find odd? (quote (2 4 6 7 8)))))
              (if #:G1013 (* v v) #f))
@end example

Note that @code{gensym} can't protect name conflict with
global bindings inserted by the macro.
@ref{Why hygienic?} discusses this issue.
@end defspec

@node Hybrid macros, Identifiers, Traditional macros, Macros
@section Hybrid macros
@c NODE ハイブリッドマクロ

A hybrid macro is both a macro and a procedure simultaneously.
If a symbol bound to a hybrid macro appears in the first position
of a form, it behaves like a macro and the form is expanded accodring
to its macro expander.  If a symbol appears other places, it is evaluated
to a procedure at runtime.

It can realize so-called ``compiler macros''---at a compile time,
the macro part examines the arguments and can transform the form as
desired.  In all other circumstances, it behaves like a normal procedure
binding, so you can pass the procedure to @code{map}, for example.

@defmac define-hybrid-syntax variable expr transformer-spec
Binds @var{variable} to both an ordinary Scheme value and a macro
simultaneously.  At the compile time, @var{transformer-spec} is evaluated;
it must yield a macro in the the compile-time environment, and bound
to @var{variable} to be used at macro expansion.  At the execution time,
@var{expr} is evaluated and bound to @var{variable} to be used as
a run-time value.

The macro transformer can return the input form as is (that is, returns
an object @code{eq?} to the input form), to indicate that it doesn't
need to expand it.  In that case, Gauche compiles the form as an ordinary
procedure call, to use the value of @var{expr} at run-time.
@end defmac

@node Identifiers, Debugging macros, Hybrid macros, Macros
@section Identifiers
@c NODE 識別子

In the discussion of hygienic macros, we keep saying the symbols are
@emph{effectively renamed}.  What it means is that we don't actually create
a new symbol with a new name. We have to remember the origin of
the renamed symbol to resolve the scope of the variable, and having a separate
table to keep track of renamed symbols would be costly.  Instead, the ``rename''
procedure wraps the symbols in the input with syntactic information.

When you play with macro internals, you'll see an object
that is printed something like @code{#<identifier user#foo.fb4ca828>}.
That's the wrapped symbol.

If one macro output is passed to another macro expander, the wrapped symbol
may further be wrapped.

The macro expander must assume that symbols in the input are already
wrapped by another macro expander.  So, instead of calling it a ``symbol'',
we call it an ``identifier''.   An identifier is something that usually
works as a variable or a syntactic keyword in the prorgam.  It may be
a symbol or a wrapped identifier.
(Note that symbols in quoted literals are bare symbols, for the @code{quote}
form strips wrappers.)

Legacy Lisp macros sometimes examines the symbols in the input form.
In Scheme, you have to treat the input program as
a tree of identifiers and other objects.  You can test whether an object
is an identifier or not by @code{identifier?}, where traditional Lisp
macor would have used @code{symbol?}.  To compare identifiers, you need
to use the ``compare'' procedure passed to the er-macro expander,
or @code{free-identifier=?}.

@deftp {Builtin Class} <identifier>
@clindex identifier
A class of wrapped identifier.  It is created as a result of
``renaming'' in the hygienic macro expander.

A wrapped identifier contains transient information about the program
source, and cannot be portably saved or passed around; it is only valid
in the macro expansion phase.

For the details of identifier, @pxref{Identifiers}.
@end deftp

@defun identifier? obj
Returns @code{#t} if @var{obj} is either a symbol or a wrapped
identifier.  Returns @code{#f} otherwise.

Note: In R6RS, @code{identifier?} only returns @code{#t} for an
identifier object, which is of a disjoint type from symbols.
You can use @code{wrapped-identifier?} below to check if an object
is an identifier other than a symbol.
@end defun

@defun wrapped-identifier? obj
Returns @code{#t} iff @var{obj} is a wrapped identifier.

This is R6RS's @code{identifier?}.
@end defun


@defun identifier->symbol obj
Returns the symbol that is the origin of the @var{obj}, which must
be either a symbol or a wrapped identifier.
@end defun

@defun free-identifier=? id1 id2
When both arguments @var{id1} and @var{id2} are wrapped identifiers,
returns @code{#t} if either (1) @var{id1} and @var{id2} both refer to
the same binding, or (2) @var{id1} and @var{id2} are both unbound.
Otherwise, @code{#f} is returned.

If at least one of @var{id1} or @var{id2} is not a wrapped identifier,
@code{#f} is returned.  Note that bare symbols can't be compared
with this procedure, for they lack the necessary lexical information.
To obtain a wrapped identifier, you need to pass a bare symbol
to the ``rename'' procedure passed to the er-macro transformer.

Usually you don't need to use this procedure directly, for
the compare procedure passed to the er-macro transformer is suffice.
@end defun

@defun unwrap-syntax form
Returns a copy of @var{form}, except
removing wrappings of identifiers in it.
The output of macro expanders contain wrapped identifiers,
which is bothersome to see.  This procedure traverses @var{form}
and replaces any wrapped identifiers with its original symbol,
retrieved by @code{identifier->symbol}.

Note that, although the result is an ordinary S-expression easier to read,
syntactic information is completely lost.  For example, distinct identifiers
can become indistinguishable if they happen to have the same name
(it happens often when you generate temporary variables via
recursive calls of @code{syntax-rules}).
If you distinguish newly inserted
identifiers with the same name, use @code{unravel-syntax}.
@end defun

@defun unravel-syntax form
Returns a copy of @var{form} while
removing wrappings of identifiers in it, but attach suffix
if two distinct identifiers have the same name, so that they won't
be confused.

For example, a common idiom of @code{syntax-rules} to generate
temporary variables with recursions create all variables with
the same name, although each variable is different because they are
inserted by the different invocation of the expander.  If you pass
its output to @code{unwrap-syntax}, all syntactic information is stripped
and these variables can't be distinguished from one another.

This procedure is automatically called with some macro utilities;
@xref{Tracing macro expansion}, and @pxref{Expanding macros manually},
for the example of output of @code{unravel-syntax}.

Note that the global identifiers becomes bare symbols, so you are still
unable to tell which module the global identifiers refer to.
@end defun



@node Debugging macros, Macro utilities, Identifiers, Macros
@section Debugging macros
@c NODE マクロのデバッグ

Macro expansion happens at the compile time, which makes it difficult
to debug.  The best way to avoid headache of macro debugging is
not to write macros unless they're absolutely necessary, and
keep them as simple as possible if you need to write ones.

However, if you find yourself in an unfortunate situation that
you have to untangle hairy macros, 
Gauche has some tools to help.

@menu
* Tracing macro expansion::
* Expanding macros manually::
@end menu

@node Tracing macro expansion, Expanding macros manually, Debugging macros, Debugging macros
@subsection Tracing macro expansion
@c NODE マクロ展開をトレースする

Macro tracing shows the input to the macro expander and the result of
its expansion on selected macros.  Suppose you have the following
macro definition.  It's essentially the same as shown in the definition
of @code{letrec} in R7RS section 7.3:

@example
(define-syntax my-letrec
  (syntax-rules ()
    [(_ ((var init) ...) body ...)
     (my-letrec "tmps" (var ...) () ((var init) ...) body ...)]
    [(_ "tmps" () (tmp ...) ((var init) ...) body ...)
     (let ((var 'undefined) ...)
       (let ((tmp init) ...)
         (set! var tmp) ...
         body ...))]
    [(_ "tmps" (x y ...) (tmp ...) binds body ...)
     (my-letrec "tmps" (y ...) (newtmp tmp ...) binds body ...)]))
@end example

The @code{my-letrec} macro uses an idiom to generate temporary
variables by looping with @code{"tmps"} tag.  You can see how
the macro is expanded step by step, by tracing @code{my-letrec}:

@example
gosh> (trace-macro 'my-letrec)
(my-letrec)
gosh> (my-letrec [(ev? (^n (if (= n 0) #t (od? (- n 1)))))
                  (od? (^n (if (= n 0) #f (ev? (- n 1)))))]
        (ev? 3))
Macro input>>>
(my-letrec
 ((ev? (^n (if (= n 0) #t (od? (- n 1)))))
  (od? (^n (if (= n 0) #f (ev? (- n 1))))))
 (ev? 3))

Macro output<<<
(my-letrec
 "tmps"
 (ev? od?)
 ()
 ((ev? (^n (if (= n 0) #t (od? (- n 1)))))
  (od? (^n (if (= n 0) #f (ev? (- n 1))))))
 (ev? 3))

Macro input>>>
(my-letrec
 "tmps"
 (ev? od?)
 ()
 ((ev? (^n (if (= n 0) #t (od? (- n 1)))))
  (od? (^n (if (= n 0) #f (ev? (- n 1))))))
 (ev? 3))

Macro output<<<
(my-letrec
 "tmps"
 (od?)
 (newtmp.0)
 ((ev? (^n (if (= n 0) #t (od? (- n 1)))))
  (od? (^n (if (= n 0) #f (ev? (- n 1))))))
 (ev? 3))

Macro input>>>
(my-letrec
 "tmps"
 (od?)
 (newtmp.0)
 ((ev? (^n (if (= n 0) #t (od? (- n 1)))))
  (od? (^n (if (= n 0) #f (ev? (- n 1))))))
 (ev? 3))

Macro output<<<
(my-letrec
 "tmps"
 ()
 (newtmp.1 newtmp.0)
 ((ev? (^n (if (= n 0) #t (od? (- n 1)))))
  (od? (^n (if (= n 0) #f (ev? (- n 1))))))
 (ev? 3))

Macro input>>>
(my-letrec
 "tmps"
 ()
 (newtmp.0 newtmp.1)
 ((ev? (^n (if (= n 0) #t (od? (- n 1)))))
  (od? (^n (if (= n 0) #f (ev? (- n 1))))))
 (ev? 3))

Macro output<<<
(let
 ((ev? (quote undefined)) (od? (quote undefined)))
 (let
  ((newtmp.0 (^n (if (= n 0) #t (od? (- n 1)))))
   (newtmp.1 (^n (if (= n 0) #f (ev? (- n 1))))))
  (set! ev? newtmp.0)
  (set! od? newtmp.1)
  (ev? 3)))

#f
@end example

In the above example, the S-expressions
after @code{gosh>} prompt is what you type; all other things are
Gauche's answer, including @code{Macro input} and @code{Macro output}
S-expressions.

The S-expression shown with @code{Macro input} is the input of
the macro expander, and the one with @code{Macro output} is the
expanded result.   Actual macro output has syntactic information
attached, but the tracer strips them off for the legibility.

Note that the loop introduces new temporary variables with the same
name (@code{newtemp}), but they are treated as different identifiers
in the macro expansion.

Once you're done debugging,
don't forget to call @code{untrace-macro} with no arguments
to remove macro traces.  If there's a macro trace set, all macro expansions
get some overhead, so don't leave macro traces.

@example
gosh> (untrace-macro)
#f
@end example


@defun trace-macro
@defunx trace-macro boolean
@defunx trace-macro name-or-pattern @dots{}
Get/set current macro trace setting.  Macro trace setting can be
one of the following values:

@table @asis
@item @code{#f}
Macro tracing is off.  This is the default setting.
@item @code{#t}
All macro expansions are traced.
@item @code{(@var{name-or-pattern} @dots{})}
Trace macros that match any one of @var{name-or-pattern}, which
is either a symbol or a regexp.  If it's a symbol, a macro whose name
is the same as the symbol is traced.  If it's a regexp, macros whose
name match the regexp are traced.
@end table

When called without arguments, @code{trace-macro} doesn't change
the setting; it returns the current setting.

When called with single boolean value, it sets the current setting
to that value.  Returns the updated setting.

When called with one or more @var{name-or-pattern}, it @emph{adds} them
to the current setting.  Note that if the current setting is @code{#t},
it remains @code{#t}, for all macros are already traced.
Returns the updated setting.

If macro trace settings is not @code{#f}, it incurs overhead for
every macro expansion.  Be careful not to leave macro trace set.

The trace information is output to the current trace port.
(@pxref{Common port operations}).
@end defun

@defun untrace-macro
@defunx untrace-macro name-or-pattern @dots{}
When called without arguments, it turns macro trace off.

When called with one or more @var{name-or-pattern}, which is either
a symbol or a regexp, @code{untrace-macro} removes them from
the currently traced macros.  Note that if the current macro trace setting
is @code{#t} (trace all macros), you can't remove traced macro individually.

It returns the updated macro trace setting.
@end defun


@node Expanding macros manually,  , Tracing macro expansion, Debugging macros
@subsection Expanding macros manually
@c NODE マクロを自分で展開する


@defun macroexpand form :optional env
@defunx macroexpand-1 form :optional env
If @var{form} is a list and its first element is a variable
globally bound to a macro, @code{macroexpand-1}
invokes its macro transformer and
returns the expanded form.  Otherwise, returns @var{form} as is.

@code{macroexpand} repeats @code{macroexpand-1} until the
outermost expression of @var{form} can't be expanded.
(It doesn't expand macros other than outermost one.  If you want
to expand all the macros within @var{form}, use @code{macroexpand-all}).

These procedures can be used to expand globally defined macros.

Internally, hygienic macro expansion wraps symbols in @var{form}
with syntactic information to keep hygiene.  However, such information
is hard to read, and not suitable when you just want to expand a macro
in REPL to check its result.  So, by default, these procedures
strips syntactic information.  For the identifiers introduced in the
macro, it renames them to avoid name conflicts.

The following example expands @code{my-letrec} macro
(@pxref{Tracing macro expansion}, for the definition) and
results shows temporary variable introduced by the macro (@var{newtemp})
to be renamed.

@example
(macroexpand
  '(my-letrec [(ev? (^n (if (= n 0) #t (od? (- n 1)))))
               (od? (^n (if (= n 0) #f (ev? (- n 1)))))]
     (ev? 3)))

@result{} 

(let
 ((ev? (quote undefined)) (od? (quote undefined)))
 (let
  ((newtmp.0 (^n (if (= n 0) #t (od? (- n 1)))))
   (newtmp.1 (^n (if (= n 0) #f (ev? (- n 1))))))
  (set! ev? newtmp.0)
  (set! od? newtmp.1)
  (ev? 3)))
@end example

If you pass a module to the @var{env} argument, it is used as the
macro use environment.  You can also pass @code{#t} to let it use
the current @emph{runtime} environment as the macro use environment.
In those cases, syntactic information in the output won't be
stripped.

If you want to use the output of @code{macroexpand} as a program,
e.g. embed it into another macro expansion, you need syntactic
information preserved.
@end defun

@defun macroexpand-all form :optional env
Fully expand macros inside @var{form}.  The result only contains
function calls and Gauche's built-in syntax.

By default, or @code{#t} is passed to @var{env},
the @var{form} is assumed to be a toplevel form within the current runtime
module.
You can also pass a module to @var{env} to specify
the alternative toplevel environment.

Any local variables introduced in @var{form} is renamed to avoid collision.
Since each local variable has unique name, all @code{let} forms become
@code{letrec} forms (we can safely replace @code{let} with @code{letrec}
if no bindings introduced by @code{let} shadows outer bindings.)

NB: If a macro in @var{form} inserts a reference to a global variable
which belongs to other module, the information is lost in the current
implementation.  There are a few ways to address this issue; we may
leave such reference as an identifier object, convert it to
@code{with-module} form, or introduce a special syntax to represent
such case.  It's undecided currently, so do not rely too much on
the current behavior.  For the time being, it's best to use this
feature only for interactive macro testing.

@example
(macroexpand-all
 '(letrec-syntax
      [(when-not (syntax-rules ()
                   [(_ test . body) (if test #f (begin . body))]))]
    (let ([if list])
      (define x (expt foo))
      (let1 x 3
        (when-not (bar) (if x))))))
 @result{} (letrec ((if.0 list)) 
     (letrec ((x.1 (expt foo)))
       (letrec ((x.2 '3)) 
        (if (bar) '#f (if.0 x.2)))))
@end example
@end defun


@defspec %macroexpand form
@defspecx %macroexpand-1 form
@end defspec

@node Macro utilities,  , Debugging macros, Macros
@section Macro utilities
@c NODE マクロユーティリティ

@defmac syntax-error msg arg @dots{}
@defmacx syntax-errorf fmt arg @dots{}
Signal an error.  They are same as
@code{error} and @code{errorf} (@pxref{Signaling exceptions}),
except that the error is signaled at macro-expansion time
(i.e. compile time) rather than run time.

They are useful to tell the user the wrong usage of macro in
the comprehensive way, instead of the cryptic error from the macro
transformer.   Because of the purpose, @var{arg} @dots{} are first
passed to @code{unwrap-syntax}  to strip off
the internal syntactic binding informations (@pxref{Identifiers}).

@example
(define-syntax my-macro
  (syntax-rules ()
    ((_ a b)   (foo2 a b))
    ((_ a b c) (foo3 a b c))
    ((_ . ?)
     (syntax-error "malformed my-macro" (my-macro . ?)))))

(my-macro 1 2 3 4)
  @result{} @r{error: "malformed my-macro: (my-macro 1 2 3 4)"}
@end example
@end defmac
@c Local variables:
@c mode: texinfo
@c coding: utf-8
@c end:
@node Core library, Object system, Macros, Top
@chapter Core library
@c NODE 組み込みライブラリ

@c ----------------------------------------------------------------------
@menu
* Types and classes::
* Equality and comparison::
* Numbers::
* Booleans::
* Undefined values::
* Pairs and lists::
* Symbols::
* Keywords::
* Characters::
* Character sets::
* Strings::
* Regular expressions::
* Vector family::
* Dictionaries::
* Procedures and continuations::
* Parameters::
* Boxes::
* Lazy evaluation::
* Exceptions::
* Eval and repl::
* Input and output::
* Loading Programs::
* Sorting and merging::
* System interface::
* Development helper API::
@end menu

@node Types and classes, Equality and comparison, Core library, Core library
@section Types and classes
@c NODE 型とクラス

Scheme is a dynamically and strongly typed language.  That is,
every value @emph{knows} its type at run-time, and the type
determines what kind of operations can be applied on the value.

In Gauche, @emph{classes} are used to describe types.
A class is also an object you can handle at runtime.
You can also create a new class in order to have objects
with distinct types.

Since R6RS, Scheme got a standard way to define a new type,
through @code{define-record-type}.  You can use record types
in Gauche as well, via @code{gauche.record} module.
@xref{Record types}.  Internally a record type is implemented
as a class.

In this section we introduce the most basic interface
to the Gauche's type system.
@xref{Object system}, for the details of
how to define your own classes and creates values (instances).

Predefined classes are bound to a global variable; Gauche's
convention is to name the variable that holds a class
with brackets @code{<} and @code{>}, e.g. @code{<string>}.
(It's nothing syntactically special with these brackets; they're valid
characters to consist of variable names).
We'll introduce classes for each built-in type as we go through
this chapter.  Here are a few basic classes to start with:

@deftp {Builtin Class} <top>
@clindex top
This class represents the supertype of all the types in Gauche.
That is, for any class @code{X}, @code{(subtype? X <top>)} is @code{#t},
and for any object @code{x}, @code{(is-a? x <top>)} is @code{#t}.
@end deftp

@deftp {Builtin Class} <bottom>
@clindex bottom
This class represents the subtype of all the types in Gauche.
For any class @code{X}, @code{(subtype? <bottom> X)} is @code{#t},
and for any object @code{x}, @code{(is-a? x <bottom>)} is @code{#f}.

There's no instance of @code{<bottom>}.

Note: Although @code{<bottom>} is subtype of other types,
the class precedence list (CPL) of @code{<bottom>} only contains
@code{<bottom>} and @code{<top>}.  It's because it isn't
always possible to calculate a linear list of all the types.
Even if it is possible, it would be expensive to check and update the
CPL of @code{<bottom>} every time a new class is defined or
an existing class is redefined.   Procedures @code{subtype?} and
@code{is-a?} treat @code{<bottom>} specially.

One of use case of @code{<bottom>} is @code{applicable?} procedure.
@xref{Procedure class and applicability}.
@end deftp

@deftp {Builtin Class} <object>
@clindex object
This class represents a supertype of all user-defined classes.
@end deftp

@defun class-of obj
Returns a class metaobject of @var{obj}.

@example
(class-of 3)         @result{} #<class <integer>>
(class-of "foo")     @result{} #<class <string>>
(class-of <integer>) @result{} #<class <class>>
@end example

Note: In Gauche, you can redefine existing user-defined classes.
If the new definition has different configuration of the instance,
@code{class-of} on existing instance triggers instance updates;
@pxref{Class redefinition} for the details.  Using
@code{current-class-of} suppresses instance updates
(@pxref{Accessing instance}).
@end defun

@defun is-a? obj class
Returns true if @var{obj} is an instance of @var{class} or an instance
of descendants of @var{class}.

@example
(is-a? 3 <integer>)   @result{} #t
(is-a? 3 <real>)      @result{} #t
(is-a? 5+3i <real>)   @result{} #f
(is-a? :foo <symbol>) @result{} #f
@end example

Note: If @var{obj}'s class has been redefined, @code{is-a?} also
triggers instance update.
See @ref{Class redefinition} for the details.
@end defun

@defun subtype? sub super
Returns @code{#t} if a class @var{sub} is a subclass of a class @var{super}
(includes the case that @var{sub} is @var{super}).
Otherwise, returns @code{#f}.

(The name @code{subtype?} is taken from Common Lisp's procedure
@code{subtypep}.)
@end defun

@node Equality and comparison, Numbers, Types and classes, Core library
@section Equality and comparison
@c NODE 等価性と比較

Comparing two objects seems trivial, but if you look into deeper,
there are lots of subtleties hidden in the corners.  What should it
mean if two procedures are equal to each other?  How to order two
complex numbers?  It all depends on your purpose; there's no single
generic answer.  So Scheme (and Gauche) provides several options,
as well as the way to make your own.

@menu
* Equality::
* Comparison::
* Hashing::
* Basic comparators::
@end menu

@node Equality, Comparison, Equality and comparison, Equality and comparison
@subsection Equality
@c NODE 等価

Scheme has three different general equality test predicates.
Other than these, some types have their own comparison predicates.

@defun eq? obj1 obj2
[R7RS base]
This is the fastest and finest predicate.
Returns @code{#t} if @var{obj1} and @var{obj2} are identical
objects---that is, if they represents the same object on memory
or in a register.  Notably, you can compare two symbols or two keywords with
@code{eq?} to check if they are the same or not.
You can think @code{eq?} as a pointer comparison for
any heap-allocated objects.

Booleans can be compared with @code{eq?}, but you can't
compare characters and numbers reliably---objects with the same
numerical value may or may not @code{eq?} to each other.
If you identity comparison needs to include those objects,
use @code{eqv?} below.

@example
(eq? #t #t)               @result{} #t
(eq? #t #f)               @result{} #f
(eq? 'a 'a)               @result{} #t
(eq? 'a 'b)               @result{} #f
(eq? (list 'a) (list 'a)) @result{} #f
(let ((x (list 'a)))
  (eq? x x))              @result{} #t
@end example
@end defun

@defun eqv? obj1 obj2
[R7RS base]
When @var{obj1} and @var{obj2} are both exact or both inexact numbers
(except NaN),
@code{eqv?} returns @code{#t} iff @code{(= @var{obj1} @var{obj2})} is true.
When @var{obj1} and @var{obj2} are both characters,
@code{eqv?} returns @code{#t} iff @code{(char=? @var{obj1} @var{obj2})} is true.
Otherwise, @code{eqv?} is the same as @code{eq?} on Gauche.

@example
(eqv? #\a #\a)             @result{} #t
(eqv? #\a #\b)             @result{} #f
(eqv? 1.0 1.0)             @result{} #t
(eqv? 1 1)                 @result{} #t
(eqv? 1 1.0)               @result{} #f
(eqv? (list 'a) (list 'a)) @result{} #f
(let ((x (list 'a)))
  (eqv? x x))              @result{} #t
@end example

Note that comparison of NaNs has some peculiarity.
Any numeric comparison fails if there's at least one NaN in its argument.
Therefore, @code{(= +nan.0 +nan.0)} is always @code{#f}.   However,
Gauche @emph{may} return @code{#t} for @code{(eq? +nan.0 +nan.0)}
or @code{(eqv? +nan.0 +nan.0)}.
@end defun

@defun equal? obj1 obj2
[R7RS+]
If @var{obj1} and @var{obj2} are both aggregate types,
@code{equal?} compares its elements recursively.
Otherwise, @code{equal?} behaves the same as @code{eqv?}.

If @var{obj1} and @var{obj2} are not @code{eqv?} to each other,
not of builtin types, and the class of both
objects are the same, @code{equal?} calls the generic
function @code{object-equal?}.
By defining the method, users can extend the behavior of @code{equal?}
for user-defined classes.

@example
(equal? (list 1 2) (list 1 2)) @result{} #t
(equal? "abc" "abc")           @result{} #t
(equal? 100 100)               @result{} #t
(equal? 100 100.0)             @result{} #f
@end example

Note: This procedure correctly handles the case when
both @var{obj1} and @var{obj2} have cycles through pairs and vectors,
as required by R6RS and R7RS.  However, if the cycle involves
user-defined classes, @code{equal?} may fail to terminate.
@end defun

@deffn {Generic Function} object-equal? obj1 obj2
This generic function is called when @code{equal?} is called on the objects
it doesn't know about.  You can define this method on your class
so that @code{equal?} can check equivalence.   This method is supposed
to return @code{#t} if @var{obj1} is equal to @var{obj2}, @code{#f}
otherwise.  If you want to check equivalence of elements recursively,
do not call @code{object-equal?} directly; call @code{equal?} on each element.

@example
(define-class <foo> ()
  ((x :init-keyword :x)
   (y :init-keyword :y)))

(define-method object-equal? ((a <foo>) (b <foo>))
  (and (equal? (slot-ref a 'x) (slot-ref b 'x))
       (equal? (slot-ref a 'y) (slot-ref b 'y))))

(equal? (make <foo> :x 1 :y (list 'a 'b))
        (make <foo> :x 1 :y (list 'a 'b)))
  @result{} #t

(equal? (make <foo> :x 1 :y (make <foo> :x 3 :y 4))
        (make <foo> :x 1 :y (make <foo> :x 3 :y 4)))
  @result{} #t
@end example
@end deffn

@deffn {Method} object-equal? (obj1 <top>) (obj2 <top>)
This method catches @code{equal?} between two objects of a user-defined
class, in case the user doesn't define a specialized method for the class.

When called, it scans the registered default comparators that can handle
both @var{obj1} and @var{obj2},
and if it finds one, use the comparator's equality
predicate to see if two arguments are equal to each other.  When no
matching comparators are found, it just returns @code{#f}.
@xref{Predefined comparators}, about the default comparators:
Look for the entries of
@code{default-comparator} and @code{comparator-register-default!}.

Note: If you define @code{object-equal?} with exactly the same
specializers of this method,
you'll replace it and that breaks
@code{default-comparator} operation.  Future versions of Gauche
will prohibit such redefinition.  For now, be careful not to redefine
it accidentally.
@end deffn

Sometimes you want to test if two aggregate structures
are topologically equal, i.e., if one has a shared substructure,
the other has a shared substructure in the same way.
@code{Equal?} can't handle it; module @code{util.isomorph}
provides a procedure @code{isomorphic?} which does the job
(@pxref{Determine isomorphism}).

@node Comparison, Hashing, Equality, Equality and comparison
@subsection Comparison
@c NODE 比較

Equality only concern about whether two objects are equivalent or not.
However, sometimes we want to see the order among objects.  Again,
there's no single ``universal order''.  It doesn't make mathematical
sense to ask if one complex number is greater than another, but 
having some artificial order is useful when you want a consistent
result of sorting a list of objects including numbers.

@defun compare obj1 obj2
A general comparison procedure.  Returns -1 if @var{obj1} is less than
@var{obj2}, 0 if @var{obj1} is equal to @var{obj2}, and 1 if @var{obj1}
is greater than @var{obj2}. 

If @var{obj1} and @var{obj2} are incomparable, an error is signalled.
However, @code{compare} defines total order between most Scheme objects,
so that you can use it on wide variety of objects.  The definition is
upper-compatible to the order defined in @code{srfi-114}.

Some built-in types are handled by this procedure reflecting
``natural'' order of comparison if any (e.g. real numbers are compared
by numeric values, characters are compared by @code{char<} etc.)
For convenience,
it also defines superficial order between objects that doesn't have
natural order; complex numbers are ordered first by their real part,
then their imaginary part, for example.  That is,
@code{1+i} comes before @code{2-i},
which comes before @code{2}, which comes before @code{2+i}.

Boolean false comes before boolean true.

Lists are ordered by dictionary order: Take the common prefix.
If either one is @code{()} and the other is not, @code{()} comes first.
If both tails are not empty, compare the heads of the tails.
(This makes empty list the ``smallest'' of all lists).

Vectors (including uniform vectors) are compared first by their
lengths, and if they are the same, elements are compared from left to right.
Note that it's different from lists and strings.

@example
(compare '(1 2 3) '(1 3))
  @result{} -1  ; (1 2 3) is smaller
(compare '#(1 2 3) '#(1 3))
  @result{} 1   ; #(1 3) is smaller
(compare "123" "13")
  @result{} -1  ; "123" is smaller
@end example

If two objects are of subclasses of @code{<object>}, 
a generic function @code{object-compare} is called.

If two objects are of different types and at least one of them
isn't @code{<object>}, then they are ordered by their types.
@code{Srfi-114} defines the order of builtin types as follows:

@enumerate 
@item
Empty list.
@item
Pairs.
@item
Booleans.
@item
Characters.
@item
Strings.
@item
Symbols.
@item
Numbers.
@item 
Vectors.
@item 
Uniform vectors
(u8 < s8 < u16 < s16 < u32 < s32 < u64 < s64 < f16 < f32 < f64)
@item
All other objects.
@end enumerate
@end defun

@deffn {Generic Function} object-compare obj1 obj2
Specializing this generic function extends @code{compare} procedure
for user-defined classes.

This method must return either @code{-1} (@var{obj1} precedes @var{obj2}),
@code{0} (@var{obj1} equals to @var{obj2}),
@code{1} (@var{obj1} succeeds @var{obj2}),
or @code{#f} (@var{obj1} and @var{obj2} cannot be ordered).
@end deffn

@deffn {Method} object-compare (obj1 <top>) (obj2 <top>)
This method catches @code{compare} between two objects of a 
user-defined class, in case the user doesn't define a specialized
method for the class.

When called, it scans the registered default comparators that can
handle both @var{obj1} and @var{obj2},
and if it finds one, use the comparator's compare procedure
to determine the order of @var{obj1} and @var{obj2}.
When no matching comparators are found, it returns @code{#f}, meaning
two objects can't be ordered.
@xref{Predefined comparators}, about the default comparators:
Look for the entries of
@code{default-comparator} and @code{comparator-register-default!}.

Note: If you define @code{object-compare} with exactly the same
specializers of this method,
you'll replace it and that breaks
@code{default-comparator} operation.  Future versions of Gauche
will prohibit such redefinition.  For now, be careful not to redefine
it accidentally.
@end deffn


@defun eq-compare obj1 obj2
Returns -1 (less than), 0 (equal to) or 1 (greater than) 
according to a certain total ordering of
@var{obj1} and @var{obj2}.   Both arguments can be any Scheme
objects, and can be different type of objects.
The following properties are guaranteed.

@itemize @bullet
@item
@code{(eq-compare x y)} is 0 iff @code{(eq? x y)} is @code{#t}.
@item
The result is consistent within a single run of the process
(but may differ between runs).
@end itemize

Other than these, no actual semantics are given to the ordering.

This procedure is useful when you need to order arbitrary Scheme
objects, but you don't care the actual order as far as it's consistent.
@end defun

@node Hashing, Basic comparators, Comparison, Equality and comparison
@subsection Hashing
@c NODE ハッシュ

Hash functions have close relationship with equality predicate,
so we list them here.


@defun eq-hash obj
@defunx eqv-hash obj
These are hash functions suitable to be used
with @code{eq?} and @code{eqv?}, respectively.
The returned hash value is system- and process-dependent,
and can't be carried over the boundary of the running process.

Note: don't hash numbers by @code{eq-hash}.  Two numbers
are not guaranteed to be @code{eq?} even if they are numerically equal.
@end defun

@defun default-hash obj
[R7RS+]
This is a hash function suitable to be used with @code{equal?}.
In R7RS, this is defined in @code{scheme.comparator} (originally
in @code{srfi-128}).

If @var{obj} is either a number, a boolean, a character,
a symbol, a keyword, a string, a list, a vector or a uniform vector,
internal hash function is used to calculate the hash value.
If @var{obj} is other than that,
a generic function @code{object-hash} is called to calculate the hash value
(see below).

The hash value also depends on @code{hash-salt}, which differs
for every run of the process.
@end defun

@defun portable-hash obj salt
Sometimes you need to calculate a hash value that's ``portable'',
in a sense that the value won't change across multiple runs of
the process, nor between different platforms.  Such hash value can
be used with storing objects externally to share among processes.

This procedure calculates a hash value of @var{obj} with such
characteristics; the hash value is the same for the same
object and the same salt value.
Here ``same object'' roughly means having
the same external representation.  Objects @code{equal?} to each
other are same.  If you write out an object with @code{write},
and read it back, they are also the same objects in this sense.

This means objects without read/write invariance, such as
ports, can't be handled with @code{portable-hash}.  It is caller's
responsibility that @var{obj} won't contain such objects.

The @var{salt} argument is a nonnegative fixnum and gives variations
in the hash function.  You have to use the same salt to get consistent
results.

If @var{obj} is other than a number, a boolean, a character,
a symbol, a keyword, a string, a list, a vector, or a uniform vector,
this procedure calls 
a generic function @code{object-hash} is called to calculate the hash value
(see below).
@end defun

@defun legacy-hash obj
Up to 0.9.4, Gauche had a hash function called @code{hash}
that was used in both @code{equal?}-hashtable @emph{and}
for the portable hash function.  It had a problem, though.

@enumerate
@item
There was no way to salt the hash function, which makes the
hashtables storing externally provided data vulnerable
to collision attack.
@item
The hash function behaves poorly, especially on flonums.
@item
There are bugs in bignum and flonum hashing code that
have produced different results on different architectures.
@end enumerate

Since there are existing hash values calculated with
the old hash function, we preserve the behavior of the
original @code{hash} function as @code{legacy-hash}.
Use this when you need to access old data.
(The @code{hash} function also behaves as @code{legacy-hash}
by default, but it has tweaks; see below.)

The new code that needs portable hash value should use
@code{portable-hash} instead.
@end defun

@deffn {Generic Function} object-hash obj rec-hash
By defining a method for this generic function, objects of
user-defined types can have a hash value and can be used
in a @code{equal?} hash table.

The method has to return an exact non-negative integer,
and must return the same value for two object which are @code{equal?}.
Furthermore, the returned value must not rely on the platform
or state of the process, if @var{obj} is a portable object
(see @code{portable-hash} above for what is portable.)

If the method needs to get hash value of @var{obj}'s elements,
it has to call @var{rec-hash} on them.  It guarantees that
the proper hash function is called recursively.  So you can
count on @var{rec-hash} to calculate a portable hash value
when @code{object-hash} itself is called from @code{portable-hash}.

If @var{obj} has several elements,
you can call @code{combine-hash-value} on the elements'
hash values.
@example
(define-class <myclass> () (x y))

;; user-defined equality function
(define-method object-equal? ((a <myclass>) (b <myclass>))
  (and (equal? (ref a 'x) (ref b 'x))
       (= (abs (ref a 'y)) (abs (ref b 'y)))))

;; user-defined hash function
(define-method object-hash ((a <myclass>) rec-hash)
  (combine-hash-value (rec-hash (ref a 'x))
                      (rec-hash (abs (ref a 'y)))))
@end example

Note: The base method of @code{object-hash} hashes any object
to a single hash value (the actual value depends on @code{hash-salt}
if @code{object-hash} is called from @code{default-hash},
and a fixed constant value otherwise.
It's because object's equality semantics can be customized separately,
and we can't compute a non-constant hash value without knowing the
equality semantics.

This behavior is the last ``safety net''; in general, you should define
@code{object-hash} method on your class if the instances of your class
can ever be hashed.
@end deffn

@deffn {Method} object-hash (obj <top>) rec-hash
@deffnx {Method} object-hash (obj <top>)
These two methods are defined by the system and ensures the
backward compatibility and the behavior of @code{default-comparator}.
Be careful not to replace these methods by defining the exactly same
specializers.  In future versions of Gauche, attempts to replace
these methods will raise an error.
@end deffn

@defun combine-hash-value ha hb
Returns a hash value which is a combination of two hash
values, @var{ha} and @var{hb}.  The guaranteed invariance
is that if @code{(= ha1 ha2)} and @code{(= hb1 hb2)}
then @code{(= (combine-hash-value ha1 hb1) (combine-hash-value ha2 hb2))}.
This is useful to write user-defined @code{object-hash} method.
@end defun

@defun hash obj
This function is deprecated.

Calculate a hash value of @var{obj} suitable for @code{equal?} hash.
By default, it returns the same value as @code{legacy-hash}.  However,
if this is called from @code{default-hash} or @code{portable-hash}
(via @code{object-hash} method), it recurses to the calling hash
function.

The behavior is to keep the legacy code work.  Until 0.9.5,
@code{hash} is the only hash function to be used for both portable
hash and @code{equal?}-hash, and @code{object-hash} method takes single
argument (an object to hash) and calls @code{hash} recursively whenever it
needs to get a hash value of other objects pointed from the argument.

As of 0.9.5 we have more than one hash functions that calls
@code{object-hash}, so the method takes the hash function as
the second argument to recurse.  However, we can't just break
the legacy code; so there's a default method defined in
@code{object-hash} which is invoked when no two-arg method
is defined for the given object, and dispatches to one-arg method.
As far as the legacy @code{object-hash}
code calls @code{hash}, it calls proper function.
The new code shouldn't rely on this behavior, and must use
the second argument of @code{object-hash} instead.
@end defun


@defun boolean-hash bool
@defunx char-hash char
@defunx char-ci-hash char
@defunx string-hash str
@defunx string-ci-hash str
@defunx symbol-hash sym
@defunx number-hash num
[R7RS comparator]
These are hash functions for specific type of objects,
defined in R7RS @code{scheme.comparator}.
In Gauche, these procedures are just a wrapper of @code{default-hash}
with type checks (and case folding when relevant).  These are
mainly provided to conform @code{scheme.comparator}; in your code you might
just want to use @code{default-hash} (or @code{eq-hash}/@code{eqv-hash},
depending on the equality predicate).

The case-folding versions, @code{char-ci-hash} and
@code{string-ci-hash}, calls @code{char-foldcase} and
@code{string-foldcase} respectively, on the argument before
passing it to @code{hash}.
(@xref{Characters}, for @code{char-foldcase}.
@xref{Full string case conversion}, for @code{string-foldcase}).
@end defun

@defun hash-bound
@defunx hash-salt
[R7RS comparator]
Both evaluates to an exact nonnegative integers.  In R7RS,
these are defined in @code{scheme.comparator}.

(Note: @code{scheme.comparator}
defines these as macros, in order to allow
implementations optimize runtime overhead.  In Gauche we use
procedures but the overhead is negligible.)

User-defined hash functions can limit the range of the result between
0 and @code{(hash-bound)}, respectively, without worrying to lose
quality of hash function.  (User-defined hash functions don't need
to honor @code{(hash-bound)} at all; hashtables takes modulo when
necessary.)

User-defined hash function can also take into account of the
value @code{(hash-salt)} into hash calculation; the salt value may
differ between runs of the Scheme processes, or even between
hash table instances.  It is to avoid collision attack.
Built-in hash functions already takes the salt value into account,
so if your hash function is combining the hash values of
primitive types, you don't need to worry about salt values.
@end defun


@node Basic comparators,  , Hashing, Equality and comparison
@subsection Basic comparators
@c NODE 基本的な比較器

Equality and comparison procedures are parameters in various
data structures.   A treemap needs to order its keys;
a hashtable needs to see if the keys are the same or not,
and it also need a hash function consistent with the equality predicate.

If we want to work on generic data structures, we need to abstract those
variations of comparison schemes.  So here comes the comparator,
a record that bundles closely-related comparison procedures together.

There are two SRFIs that define comparators.  The one that was originally
called @code{srfi-128} has now become a part of R7RS large as 
@code{scheme.comparator}, and we recommend new code to use it.
Gauche has all of @code{scheme.comparator}
procedures built-in.  The older, and rather complex one is @code{srfi-114};
Gauche also supports it mainly for the backward compatibility.
Importantly, Gauche's native @code{<comparator>} object is compatible
to both @code{scheme.comparator} and @code{srfi-114}
comparators.

@menu
* Comparator class and constructors::
* Comparator predicates and accessors::
* Predefined comparators::
* Combining comparators::
@end menu

@node Comparator class and constructors, Comparator predicates and accessors, Basic comparators, Basic comparators
@subsubsection Comparator class and constructors
@c NODE 比較器クラスとコンストラクタ

@deftp {Builtin Class} <comparator>
A comparator record that bundles the following procedures:

@table @emph
@item Type test predicate
Checks if an object can be compared with this comparator.
@item Equality predicate
See if given two objects
are equal to each other; returns a boolean value.
@item Ordering predicate
Compare given two objects, and returns true iff the first one is
strictly precedes the second one.  That is, this is a less-than predicate.
@item Comparison procedure
Compare given two objects, and returns either -1 (the first one is less
than the second), 0 (they are equal), or 1 (the first one is greater
than the second).
@item Hash function
Returns a hash value of the given object.
@end table

@code{Scheme.comparator}'s
comparators use the ordering predicate, 
while SRFI-114 comparators use the comparison procedure.
Gauche's @code{<comparator>} supports both by automatically
generating the missing one; that is, if you create a comparator
with @code{scheme.comparator} interface, by giving an ordering predicate,
Gauche automatically fills the comparison procedure, and
if you create one with SRFI-114 interface by giving a comparison
procedure, Gauche generates the ordering predicate.

A comparator may not have an ordering predicate / comparison procedure,
and/or a hash function.  You can check if the comparator
can be used for ordering or hashing by
@code{comparator-ordered?} and
@code{comparator-hashable?}, respectively.

Some built-in data types such as hashtables (@pxref{Hashtables})
and treemaps (@pxref{Treemaps}), take a comparator in their constructors.
The sort and merge procedures also accept comparators
(@pxref{Sorting and merging}).
@end deftp

@defun make-comparator type-test equal order hash :optional name
[R7RS comparator]
Creates a new comparator form the given @var{type-test}, 
@var{equal}, @var{order} and @var{hash} functions, and returns it.
In R7RS, this is defined in @code{scheme.comparator}

See the description of @code{<comparator>} above for the role of
those procedures.

Note: Both @code{scheme.comparator}
and @code{srfi-114} defines @code{make-comparator},
but where @code{scheme.comparator} takes @var{order} argument,
@code{srfi-114} takes @var{compare} argument.
Since @code{scheme.comparator} is preferable, we adopt
it for the built-in interface, and give a different name
(@code{make-comparator/compare}) for SRFI-114 constructor.

Actually, some arguments can be non-procedures, to use predefined
procedures, for the convenience.  Even if non-procedure arguments
are passed, the corresponding accessors (e.g.
@code{comparator-type-test-procedure} for the @code{type-test}
procedure) always return a procedure---either the given one
or the predefined one.

The @var{type-test} argument must be either @code{#t} or
a predicate taking one argument to test suitability of
the object for comparing by the resulting comparator.
If it is @code{#t}, 
a procedure that always return @code{#t} is used.

The @var{equal} argument must
a predicate taking two arguments to test equality.

the @var{order} argument must be either @code{#f} or
a procedure taking two arguments and returning a boolean value.
It must return @code{#t} iff the first argument strictly precedes
the second one.  If @code{#f} is passed, the comparator can not be
used for ordering.

The @var{hash} argument must be either @code{#f}, or
a procedure taking one argument and returning nonnegative exact
integer.  If @code{#f} is given, it indicates the comparator
can't hash objects; the predefined procedure just throws an error.

The fifth, optional argument @var{name}, is Gauche's extension.
It can be any object but usually a symbol; it is only used when
printing the comparator, to help debugging.
@end defun

@defun make-comparator/compare type-test equal compare hash :optional name
This is SRFI-114 comparator constructor.  In SRFI-114, this is called
@code{make-comparator}.  Avoiding name conflict, we renamed it.
If you @code{(use srfi-114)} you get the original name @code{make-comparator}
(and the built-in @code{make-comparator} is shadowed).
This is provided for the backward
compatibility, and new code should use built-in @code{make-comparator} above.

It's mostly the same as @code{make-comparator} above, except
the following:

@itemize
@item
The third argument (@var{compare}) is a comparison procedure
instead of an ordering predicate.
It must be either @code{#f}, or a procedure taking two arguments
and returning either -1, 0, or 1, depending on whether the
first argument is less than, equal to,
or greater than the second argument.
If it is @code{#f}, it indicates the comparator can't order objects.
@item
You can pass @code{#t} to the @var{equal} argument when you give
a comparison procedure.  In that case, equality is determined
by calling the comparison procedure and see if the result is 0.
@end itemize
@end defun

@node Comparator predicates and accessors, Predefined comparators, Comparator class and constructors, Basic comparators
@subsubsection Comparator predicates and accessors
@c NODE 比較器にまつわる述語とアクセサ


@defun comparator? obj
[R7RS comparator]
Returns true iff @var{obj} is a comparator.
In R7RS, this is provided from @code{scheme.comparator}.
@end defun

@deffn {Method} object-equal? (a <comparator>) (b <comparator>)
Comparing two comparators by @code{equal?} compares their contents,
via this method.  Even @var{a} and @var{b} are comparators created
separately, they can be @code{equal?} if all of their slots are
the same.

This is Gauche's extension.  The standard says nothing about
equality of comparators, but it is sometimes useful if you can compare
two.

@example
(equal? (make-comparator #t equal? #f hash 'foo)
        (make-comparator #t equal? #f hash 'foo))
  @result{} #t

;; The following may be #t or #f, depending on how the anonymous
;; procedure is allocated.
(equal? (make-comparator (^x x) eq? #f #f)
        (make-comparator (^x x) eq? #f #f))
@end example
@end deffn

@defun comparator-flavor cmpr
Returns a symbol @code{ordering} if @var{cmpr} is created with
@code{scheme.comparator} constructor, and
returns @code{comparison} if @var{cmpr}
is created with SRFI-114 constructor.

Usually applications don't need to distinguish these two kinds of
comparators, for either kind of comparators can behave just as another
kind.  This procedure is for some particular cases when one
wants to optimize for the underlying comparator implementation.
@end defun

@defun comparator-ordered? cmpr
@defunx comparator-hashable? cmpr
[R7RS comparator]
Returns true iff a comparator @var{cmpr} can be used to order
objects, or to hash them, respectively.
In R7RS, this is provided from @code{scheme.comparator}.
@end defun

@defun comparator-type-test-procedure cmpr
@defunx comparator-equality-predicate cmpr
@defunx comparator-ordering-predicate cmpr
@defunx comparator-hash-function cmpr
[R7RS comparator]
Returns type test procedure, equality predicate, ordering procedure
and hash function of comparator @var{cmpr}, respectively.
In R7RS, this is provided from @code{scheme.comparator}.

These accessors always return procedures; if you give @code{#f}
to the @var{order} or @var{hash} argument of the constructor,
@code{comparator-ordering-predicate} and
@code{comparator-hash-function} still return a procedure,
which will just raise an error.
@end defun

@defun comparator-comparison-procedure cmpr
[SRFI-114]
This is a SRFI-114 procedure, but sometimes handy with
@code{scheme.comparator} comparators.
Returns a procedure that takes two objects
that satisfy the type predicates of @var{cmpr}.  The procedure
returns either -1, 0 or 1, depending on whether the first object
is less than, equal to, or greater than the second.  The comparator
must be ordered, that is, it must have an ordering predicate
(or a comparison procedure, if it is created by SRFI-114 constructor).
@end defun

@defun comparator-test-type cmpr obj
@defunx comparator-check-type cmpr obj
[R7RS comparator]
Test whether @var{obj} can be handled by a comparator @var{cmpr},
by applying @var{cmpr}'s type test predicate.
The former (@code{comparator-test-type}) returns a boolean
values, while the latter (@code{comparator-check-type})
signals an error when @var{obj} can't be handled.

In R7RS, this is provided from @code{scheme.comparator}.
@end defun

@defun =? cmpr obj obj2 obj3 @dots{}
@defunx <? cmpr obj obj2 obj3 @dots{}
@defunx <=? cmpr obj obj2 obj3 @dots{}
@defunx >? cmpr obj obj2 obj3 @dots{}
@defunx >=? cmpr obj obj2 obj3 @dots{}
[R7RS comparator]
Compare objects using a comparator @var{cmpr}.  All of
@var{obj}, @var{obj2}, @var{obj3} @dots{} must satisfy
the type predicate of @var{cmpr}.  When more than two objects
are given, the order of comparison is undefined.

In order to use @code{<?}, @code{<=?}, @code{>?} and @code{>=?},
comparator must be ordered.

In R7RS, this is provided from @code{scheme.comparator}.
@end defun

@defun comparator-hash cmpr obj
[R7RS comparator]
Returns a hash value of @var{obj} with the hash function of
a comparator @var{cmpr}.  The comparator must be hashable,
and @var{obj} must satisfy comparator's type test predicate.

In R7RS, this is provided from @code{scheme.comparator}.
@end defun

@defun comparator-compare cmpr a b
[SRFI-114]
Order two objects @var{a} and @var{b}
using @var{cmpr}, and returns either one of 
-1 (@var{a} is less than @var{b}),
0 (@var{a} equals to @var{b}), or
1 (@var{a} is greater than @var{b}).
Objects must satisfy @var{cmpr}'s type test predicate.

A simple comparison can be done by @code{<?} etc, but sometimes
three-way comparison comes handy.  So we adopt this procedure
from srfi-114.
@end defun

@node Predefined comparators, Combining comparators, Comparator predicates and accessors, Basic comparators
@subsubsection Predefined comparators
@c NODE 用意されている比較器

@defvar default-comparator
[SRFI-114]
This variable bounds to a comparator that is used by default in
many context.

It can compare most of Scheme objects, even between objects with
different types.  In fact, it is defined as follows:

@example
(define default-comparator
  (make-comparator/compare #t equal? compare default-hash
                           'default-comparator))
@end example

As you see in the definition, equality, ordering and hashing are
handled by @code{equal?}, @code{compare} and @code{default-hash},
respectively.  They takes care of builtin objects, and
also @code{equal?} and @code{compare} handle the case
when two objects () are of different types.

For objects of user-defined classes,
those procedures call generic functions
@code{object-equal?}, @code{object-compare}, and @code{object-hash},
respectively.   Defining methods for them automatically extended
the domain of @code{default-comparator}.

@code{Scheme.comparator} defines another way to extend @code{default-comparator}.
See @code{comparator-register-default!} below for the details.
@end defvar

@defun comparator-register-default! comparator
[R7RS comparator]
In R7RS, this is provided from @code{scheme.comparator}.
This is the @code{scheme.comparator} way for user
programs to extend the behavior of
the @code{default-comparator}
(which is what @code{make-default-comparator} returns).

Note that, in Gauche, you can also extend default comparator's behavior
by defining specialized methods for @code{object-equal?}, 
@code{object-compare} and @code{object-hash}.
See the description of @code{default-comparator} above, for the details.

In fact, Gauche uses those generic functions to
handle the registered comparators; methods specialized for
@code{<top>} are defined for these generic functions, which
catches the case when @code{default-comparator} is applied
on object(s) of user-defined classes that don't have specialized
methods defined for those generic functions.
The catching method examines registered comparators to find
one that can handle passed argument(s), and if it finds one,
use it.

You might frown at this procedure having a global side-effect.
Well, @code{scheme.comparator} explicitly prohibits comparators registered
by this procedure alters the behavior of the default comparator
in the existing domain---it is only allowed to handle objects that
aren't already handled by the system's original default comparator
and other already registered comparators.  So, the only effect of
adding new comparator should make the default comparator
work on objects that had been previously raised an error.

In reality, it is impossible to enforce the condition.  If you
register a comparator whose domain overlaps overlaps the domain
the default comparator (and its extensions via Gauche's methods),
the program becomes non-portable at that moment.  In the current version,
the comparators registered by @code{comparator-register-default!} has
the lowest precedence on the dispatch mechanism, but you shouldn't count
on that.
@end defun

@defvar eq-comparator
@defvarx eqv-comparator
@defvarx equal-comparator
[SRFI-114]
Built-in comparators that uses @code{eq?}, @code{eqv?} and @code{equal?}
for the equality predicate, respectively.  They accept any kind of
Scheme objects.  Each has corresponding hash functions
(i.e. @code{eq-hash} for @code{eq-comparator},
@code{eqv-hash} for @code{eqv-comparator} and
@code{default-hash} for @code{equal-comparator}).
Only @code{eq-comparator} is ordered, using @code{eq-compare} to
order the objects
(@pxref{Comparison}, for @code{eq-compare}).

Note that @code{eq-comparator} and @code{eqv-comparator} are not
equivalent from what @code{make-eq-comparator} and @code{make-eqv-comparator}
return, respectively.  The latter two are defined in @code{scheme.comparator}
and specified to use @code{default-hash} for the hash function.  It is
heavier than @code{eq-hash}/@code{eqv-hash}, and it can't be used
for circular objects, nor for the mutable objects with which you want
to hash them by identity.  We provide @code{eq-comparator} and
@code{eqv-comparator} in case you want to avoid limitations of
@code{default-hash}.
@end defvar

@defvar boolean-comparator
@defvarx char-comparator
@defvarx char-ci-comparator
@defvarx string-comparator
@defvarx string-ci-comparator
[SRFI-114]
Compare booleans, characters, and strings, respectively.
The @code{*-ci-*} variants uses case-insensitive comparison.
All have appropriate hash functions, too.

The string case-insensitive comparison uses Unicode full-string case
conversion (@pxref{Full string case conversion}).
@end defvar

@defvar exact-integer-comparator
@defvarx integer-comparator
@defvarx rational-comparator
@defvarx real-comparator
@defvarx complex-comparator
@defvarx number-comparator
[SRFI-114]
Compare exact integers, integers, rational numbers, real numbers,
complex numbers and general numbers, respectively.
In Gauche @code{number-comparator} is the same as @code{complex-comparator}.

The equality are determined by @code{=}.
For exact integer, integer, rational and real comparators,
the order is the numerical order.  Two complex numbers are
compared first by their real components, and then their imaginary
components only if the real components are the same.

Note that those comparator rejects NaN.
You need @code{make-inexact-real-comparator} in @code{srfi-114} module
to compare NaNs with your own discretion. 
@xref{Comparators}, for the details.
@end defvar

@defvar pair-comparator
@defvarx list-comparator
@defvarx vector-comparator
@defvarx uvector-comparator
@defvarx bytevector-comparator
[SRFI-114]
The default comparators to compare pairs, lists, vectors, uniform
vectors and bytevectors (which is synonym to @code{u8vector}).
Their respective elements are compared with the default comparators.

Note that lists are compared by dictionary order (@code{(1 2 3)} comes
before @code{(1 3)}), while in vector-families
shorter ones are ordered first (
@code{#(1 3)} comes before @code{#(1 2 3)}).
@end defvar

@node Combining comparators,  , Predefined comparators, Basic comparators
@subsubsection Combining comparators
@c NODE 比較器を組み合わせる

@defun make-default-comparator
[R7RS comparator]
Returns a default comparator.  In Gauche, this returns the
@code{default-comparator} object.
In R7RS, this is provided from @code{scheme.comparator}.
@end defun

@defun make-eq-comparator
@defunx make-eqv-comparator
[R7RS comparator]
Returns comparators that use @code{eq?} and @code{eqv?} for its
equality predicate, respectively.  Note that they use @code{default-hash}
for hash functions, as specified by @code{scheme.comparator},
which has a few drawbacks:
You can't use it if you want to hash based on identity of mutable objects,
it diverges on circular objects, and it is slow if applied on a large
structures.  We recommend to use @code{eq-comparator} or
@code{eqv-comparator} if possible (@pxref{Predefined comparators}).

In R7RS, this is provided from @code{scheme.comparator}.
@end defun

@defun make-reverse-comparator cmpr
[SRFI-114]
Returns a comparator with the same type test predicate,
equality procedure, and hash function as the given comparator,
but the comparison procedure is flipped.
@end defun

@defun make-key-comparator cmpr test key
Suppose you have some kind of structure, but you only need to look
at one part of it to compare them.

Returns a new comparator that uses @var{test} as type test predicate.
Its equality predicate, comparison procedure and hash function are
constructed by applying @var{key} to the argument(s) then passing
the result to the corresponding procedure of @var{cmpr}.  If @var{cmpr}
lacks comparison procedure and/or hash function, so does the returned
comparator.

In the following example, the tree-map @code{users} compares
the given user records only by the @code{username} slots:

@example
(use gauche.record)

(define-record-type user #t #t
  username      ; string
  password-hash ; string
  comment)      ; string

(define users   ; table of users, managed by tree-map
  (make-tree-map
    (make-key-comparator string-comparator user? user-username)))
@end example
@end defun

@defun make-tuple-comparator cmpr1 cmpr2 @dots{}
Creates a comparator that compares lists of the form @code{(x1 x2 @dots{})},
where each element is compared with the corresponding comparator.
For example, @code{(make-tuple-comparator c1 c2 c3)} will compare
three-element list, whose first elements are compared by @var{c1},
second elements by @var{c2} and third elements by @var{c3}.
@end defun

@c ----------------------------------------------------------------------
@node Numbers, Booleans, Equality and comparison, Core library
@section Numbers
@c NODE 数値

Gauche supports the following types of numbers
@table @asis
@item multi-precision exact integer
There's no limit of the size of number except the memory of the machine.
@item multi-precision exact non-integral rational numbers.
Both denominator and numerator are represented by exact integers.
There's no limit of the size of number except the memory of the machine.
@item inexact floating-point real numbers
Using @code{double}-type of underlying C compiler, usually IEEE 64-bit
floating point number.
@item inexact floating-point complex numbers
Real part and imaginary part are represented by inexact floating-point
real numbers.
@end table

@menu
* Number classes::
* Numerical predicates::
* Numerical comparison::
* Arithmetics::
* Numerical conversions::
* Basic bitwise operations::
* Endianness::
@end menu

@node Number classes, Numerical predicates, Numbers, Numbers
@subsection Number classes
@c NODE 数値クラス

@deftp {Builtin Class} <number>
@deftpx {Builtin Class} <complex>
@deftpx {Builtin Class} <real>
@deftpx {Builtin Class} <rational>
@deftpx {Builtin Class} <integer>
@clindex number
@clindex complex
@clindex real
@clindex rational
@clindex integer
These classes consist a class hierarchy of number objects.
@code{<complex>} inherits @code{<number>}, @code{<real>} inherits
@code{<complex>},@code{<rational>} inherits @code{<real>}
 and @code{<integer>} inherits @code{<rational>}.

Note that these classes do not exactly correspond to the
number hierarchy defined in R7RS.  Especially,
only exact integers are the instances of the @code{<integer>}
class.  That is,
@lisp
(integer? 1)        @result{} #t
(is-a? 1 <integer>) @result{} #t
(is-a? 1 <real>)    @result{} #t

(integer? 1.0)        @result{} #t
(is-a? 1.0 <integer>) @result{} #f
(is-a? 1.0 <real>)    @result{} #t

(class-of (expt 2 100)) @result{} #<class <integer>>
(class-of (sqrt -3)) @result{} #<class <complex>>
@end lisp
@end deftp

@node Numerical predicates, Numerical comparison, Number classes, Numbers
@subsection Numerical predicates
@c NODE 数値に関する述語

@defun number? obj
@defunx complex? obj
@defunx real? obj
@defunx rational? obj
@defunx integer? obj
[R7RS base]
Returns @code{#t} if @var{obj} is a number, a complex number, a real number,
a rational number or an integer, respectively.   In Gauche, a set of
numbers is the same as a set of complex numbers.
A set of rational numbers is the same as a set of real numbers,
except @code{+inf.0}, @code{-inf.0} and @code{+nan.0}
(since we have only limited-precision floating numbers).

@example
(complex? 3+4i)   @result{} #t
(complex? 3)      @result{} #t
(real? 3)         @result{} #t
(real? -2.5+0.0i) @result{} #t
(real? #e1e10)    @result{} #t
(integer? 3+0i)   @result{} #t
(integer? 3.0)    @result{} #t

(real? +inf.0)     @result{} #t
(real? +nan.0)     @result{} #t
(rational? +inf.0) @result{} #f
(rational? +nan.0) @result{} #f
@end example

Note: R6RS adopts more strict definition on exactness,
and notably, it defines a complex number with non-exact zero imaginary
part is not a real number.   Currently Gauche doesn't have
exact complex numbers, and automatically coerces complex
numbers with zero imaginary part to a real number.
Thus R6RS code that relies on the fact that @code{(real? 1+0.0i)} is
@code{#f} won't work with Gauche.
@end defun

@defun real-valued? obj
@defunx rational-valued? obj
@defunx integer-valued? obj
[R6RS]
In Gauche these are just an alias of @code{real?}, @code{rational?}
and @code{integer?}.  They are provided for R6RS compatibility.

The difference of those and non @code{-valued} versions in R6RS is
that these returns @code{#t} if @var{obj} is a complex number
with nonexact zero imaginary part.   Since Gauche doesn't distinguish
complex numbers with zero imaginary part and real numbers, we don't
have the difference.
@end defun

@defun exact? obj
@defunx inexact? obj
[R7RS base]
Returns @code{#t} if @var{obj} is an exact number and an inexact number,
respectively.

@example
(exact? 1)       @result{} #t
(exact? 1.0)     @result{} #f
(inexact? 1)     @result{} #f
(inexact? 1.0)   @result{} #t

(exact? (modulo 5 3)) @result{} #t
(inexact? (modulo 5 3.0)) @result{} #f
@end example
@end defun

@defun exact-integer? obj
[R7RS base]
Same as @code{(and (exact? obj) (integer? obj))}, but more efficient.
@end defun

@defun zero? z
[R7RS base]
Returns @code{#t} if a number @var{z} equals to zero.

@example
(zero? 1)        @result{} #f
(zero? 0)        @result{} #t
(zero? 0.0)      @result{} #t
(zero? 0.0+0.0i) @result{} #t
@end example
@end defun

@defun positive? x
@defunx negative? x
[R7RS base]
Returns @code{#t} if a real number @var{x} is positive and negative,
respectively.  It is an error to pass a non-real number.
@end defun

@defun finite? z
@defunx infinite? z
@defunx nan? z
[R7RS inexact]
For real numbers, returns @code{#f} iff the given number
is finite, infinite, or NaN, respectively.

For non-real complex numbers, @code{finite?} returns @code{#t} iff
both real and imaginary components are finite, @code{infinite?}
returns @code{#t} if at least either real or imaginary component
is infinite, and @code{nan?} returns @code{#t} if at least either
real or imaginary component is NaN.  (Note: It is incompatible
to R6RS, in which these procedures must raise an error if
the given argument is non-real number.)

In R7RS, these procedures are in @code{(scheme inexact)} library.
@end defun

@defun odd? n
@defunx even? n
[R7RS base]
Returns @code{#t} if an integer @var{n} is odd and even,
respectively.  It is an error to pass a non-integral number.

@example
(odd? 3)     @result{} #t
(even? 3)    @result{} #f
(odd? 3.0)   @result{} #t
@end example
@end defun

@defun fixnum? n
@defunx bignum? n
[R7RS fixnum]
Returns @code{#t} iff @var{n} is an exact integer whose internal
representation is @emph{fixnum} and @emph{bignum}, respectively.
R7RS-large defines @code{fixnum?} in @code{scheme.fixnum} library;
@code{bignum?} is Gauche's extension.
Portable Scheme programs don't need to care about the internal
representation of integer.   These are for certain low-level
routines that does particular optimization.

@xref{R7RS fixnum}, for the comprehensive fixnum library.
@end defun

@defun flonum? x
[R7RS flonum]
Returns @code{#t} if @var{x} is a number represented by a floating-point
number, @code{#f} otherwise.  In Gauche, inexact real numbers
are flonums.

@xref{R7RS flonum}, for comprehensive flonum library.
@end defun


@node Numerical comparison, Arithmetics, Numerical predicates, Numbers
@subsection Numerical comparison
@c NODE 数値の比較

@defun = z1 z2 z3 @dots{}
[R7RS base]
If all the numbers @var{z} are equal, returns @code{#t}.

@example
(= 2 2)          @result{} #t
(= 2 3)          @result{} #f
(= 2 2.0)        @result{} #t
(= 2 2.0 2.0+0i) @result{} #t
(= 2/4 1/2)      @result{} #t
@end example
@end defun

@defun < x1 x2 x3 @dots{}
@defunx <= x1 x2 x3 @dots{}
@defunx > x1 x2 x3 @dots{}
@defunx >= x1 x2 x3 @dots{}
[R7RS base]
Returns @code{#t} If all the real numbers @var{x} are
monotonically increasing,
monotonically nondecreasing, monotonically decreasing, or monotonically
nonincreasing, respectively.
@end defun


@defun max x1 x2 @dots{}
@defunx min x1 x2 @dots{}
[R7RS base]
Returns a maximum or minimum number in the given real numbers, respectively.
If any of the arguments are NaN, NaN is returned.

See also @code{find-min} and @code{find-max} in
@ref{Selection and searching in collection}.
@end defun

@defun min&max x1 x2 @dots{}
Returns a maximum and minimum number in the given real numbers.

See also @code{find-min&max} in
@ref{Selection and searching in collection}.
@end defun

@defun approx=? x y :optional relative-tolerance absolute-tolerance
Returns @code{#t} iff two numbers are approximately equal within
the given error tolerance.

@itemize @bullet
@item
If at least one of @var{x} or @var{y} is NaN, returns @code{#f}.
@item
If either one is infinity, returns @code{#t} iff the other one is also
infinity of the same sign.
@item
Otherwise, return a boolean value computed as follows:
@example
(<= (abs (- x y))
    (max (* (max (abs x) (abs y)) relative-tolerance)
         absolute-tolerance))
@end example
@end itemize

If at least one of @var{x} or @var{y} are non-real complex
number, @code{magnitude} is used in place of @code{abs}.

When omitted, @var{relative-tolerance} is assumed to be
@code{(flonum-epsilon)}, and @var{absolute-tolerance} is
@code{(flonum-min-denormalized)}.
That is, by default, @code{approx=?} tolerates
1 ULP (unit in the last place) error.

The @var{absolute-tolerance} argument is useful when arguments are
close to zero, in which case relative tolerance becomes too small.
@end defun

@defun flonum-epsilon
@defunx flonum-min-normalized
@defunx flonum-min-denormalized
Returns flonums with the following characteristics, respectively:
@table @code
@item flonum-epsilon
Returns the least positive flonum e such that, for a normalized
flonum @code{x}, @code{x} and @code{(* x (+ 1.0 e))} are distinguishable.
@item flonum-min-normalized
Returns the least positive flonum representable as normalized floating-point
number.
@item flonum-min-denormalized
Returns the least positive flonum representable as denormalized floating-point
number.  If the platform doesn't support denormalized flonum,
it returns the least positive normalized floating number.
@end table
@end defun


@node Arithmetics, Numerical conversions, Numerical comparison, Numbers
@subsection Arithmetics
@c NODE 数値の演算

@defun + z @dots{}
@defunx * z @dots{}
[R7RS base]
Returns the sum or the product of given numbers, respectively.
If no argument is given, @code{(+)} yields 0 and @code{(*)} yields 1.
@end defun

@defun - z1 z2 @dots{}
@defunx / z1 z2 @dots{}
[R7RS base]
If only one number @var{z1} is given, returns its
negation and reciprocal, respectively.

If more than one number are given, returns:
@example
@var{z1} - @var{z2} - @var{z3} @dots{}
@var{z1} / @var{z2} / @var{z3} @dots{}
@end example
respectively.

@example
(- 3)       @result{} -3
(- -3.0)    @result{} 3.0
(- 5+2i)    @result{} -5.0-2.0i
(/ 3)       @result{} 1/3
(/ 5+2i)    @result{} 0.172413793103448-0.0689655172413793i

(- 5 2 1)     @result{} 2
(- 5 2.0 1)   @result{} 2.0
(- 5+3i -i)   @result{} 5.0+2.0i
(/ 14 6)      @result{} 7/3
(/ 6+2i 2)    @result{} 3.0+1.0i
@end example

Note: Gauche didn't have exact rational number support until 0.8.8;
before that, @code{/} coerced the result to inexact even if both
divisor and dividend were exact numbers, when the result wasn't
a whole number.  It is not the case anymore.

If the existing code relies on the old behavior, it runs
very slowly on the newer versions of Gauche, since the calculation
proceeds with exact rational arithmetics that is much slower than
floating point arithmetics.  You want to use @code{/.} below
to use fast inexact arithmetics (unless you
need exact results).
@end defun

@defun +. z @dots{}
@defunx *. z @dots{}
@defunx -. z1 z2 @dots{}
@defunx /. z1 z2 @dots{}
Like @code{+}, @code{*}, @code{-}, and @code{/}, but the arguments
are coerced to inexact number.  So they always return inexact number.
These are useful when you know you don't need exact calculation
and want to avoid accidental overhead of bignums and/or exact
rational numbers.
@end defun

@defun abs z
[R7RS+]
For real number @var{z}, returns an absolute value of it.
For complex number @var{z}, returns the magnitude of the number.
The complex part is Gauche extension.
@example
(abs -1)   @result{} 1
(abs -1.0) @result{} 1.0
(abs 1+i)  @result{} 1.4142135623731
@end example
@end defun

@defun quotient n1 n2
@defunx remainder n1 n2
@defunx modulo n1 n2
[R7RS base]
Returns the quotient, remainder and modulo of dividing an integer @var{n1}
by an integer @var{n2}.   The result is an exact number only if
both @var{n1} and @var{n2} are exact numbers.

Remainder and modulo differ when either one of the arguments is negative.
Remainder @var{R} and quotient @var{Q} have the following relationship.
@example
  @var{n1} = @var{Q} * @var{n2} + @var{R}
@end example
where @code{abs(@var{Q}) = floor(abs(@var{n1})/abs(@var{n2}))}.
Consequently, @var{R}'s sign is always the same as @var{n1}'s.

On the other hand, modulo works as expected for positive @var{n2},
regardless of the sign of @var{n1}
(e.g. @code{(modulo -1 @var{n2}) == @var{n2} - 1}).
If @var{n2} is negative, it is mapped to the positive case by
the following relationship.
@example
  modulo(@var{n1}, @var{n2}) = @minus{}modulo(@minus{}@var{n1}, @minus{}@var{n2})
@end example
Consequently, @var{modulo}'s sign is always the same as @var{n2}'s.
@example
(remainder 10 3)    @result{} 1
(modulo 10 3)       @result{} 1

(remainder -10 3)   @result{} -1
(modulo -10 3)      @result{} 2

(remainder 10 -3)   @result{} 1
(modulo 10 -3)      @result{} -2

(remainder -10 -3)  @result{} -1
(modulo -10 -3)     @result{} -1
@end example
@end defun

@defun quotient&remainder n1 n2
Calculates the quotient and the remainder of dividing integer @var{n1}
by integer @var{n2} simultaneously, and returns them as two values.
@end defun

@defun div x y
@defunx mod x y
@defunx div-and-mod x y
@defunx div0 x y
@defunx mod0 x y
@defunx div0-and-mod0 x y
[R6RS]
These are integer division procedures introduced in R6RS.
Unlike @code{quotient}, @code{modulo} and @code{remainder},
these procedures can take non-integral values.
The dividend @var{x} can be an arbitrary real number,
and the divisor @var{y} can be non-zero real number.

@code{div} returns an integer @var{n}, and @code{mod} returns
a real number @var{m}, such that:

@itemize @bullet
@item
@var{x} = @var{n} @var{y} + @var{m}, and
@item
0 <= @var{m} < |@var{y}|.
@end itemize

Examples:
@example
(div 123 10)     @result{} 12
(mod 123 10)     @result{} 3

(div 123 -10)    @result{} -12
(mod 123 -10)    @result{} 3

(div -123 10)    @result{} -13
(mod -123 10)    @result{} 7

(div -123 -10)   @result{} 13
(mod -123 -10)   @result{} 7

(div 123/7 10/9) @result{} 15
(mod 123/7 10/9) @result{} 19/21
;; 123/7 = 10/9 * 15 + 19/21

(div 14.625 3.75) @result{} 3.0
(mod 14.625 3.75) @result{} 3.375
;; 14.625 = 3.75 * 3.0 + 3.375
@end example

For a nonnegative integer @var{x} and an integer @var{y},
The results of @code{div} and @code{mod} matches
those of @code{quotient} and @code{remainder}.  If @var{x}
is negative, they differ, though.

@code{div-and-mod} calculates both @code{div} and @code{mod}
and returns their results in two values.

@var{div0} and @var{mod0} are similar, except the range of @var{m}:

@itemize @bullet
@item
@var{x} = @var{n} @var{y} + @var{m}
@item
-|@var{y}|/2 <= @var{m} < |@var{y}|/2
@end itemize

@example
(div0 123 10)   @result{} 12
(mod0 123 10)   @result{} 3

(div0 127 10)   @result{} 13
(mod0 127 10)   @result{} -3

(div0 127 -10)  @result{} -13
(mod0 127 -10)  @result{} -3

(div0 -127 10)  @result{} -13
(mod0 -127 10)  @result{} 3

(div0 -127 -10) @result{} 13
(mod0 -127 -10) @result{} 3
@end example

@code{div0-and-mod0} calculates both @code{div0} and @code{mod0}
and returns their results in two values.

Here's a visualization of R6RS and R7RS division and modulo operations:
@url{http://blog.practical-scheme.net/gauche/20100618-integer-divisions}
It might help to grasp how they works.
@end defun

@defun floor-quotient n d
@defunx floor-remainder n d
@defunx floor/ n d
@defunx truncate-quotient n d
@defunx truncate-remainder n d
@defunx truncate/ n d
[R7RS base]
These are integer division operators introduced in R7RS.  The names
explicitly indicate how they behave when numerator and/or denominator
is/are negative.

The arguments @var{n} and @var{d} must be an integer.  If any of them are
inexact, the result is inexact.  If all of them are exact, the result is
exact.  Also, @var{d} must not be zero.

Given numerator @var{n}, denominator @var{d}, quotient @var{q} and
remainder @var{r}, the following relations are always kept.

@example
r = n - dq
abs(r) < abs(d)
@end example

Now, @code{(floor-quotient n d)} and @code{(truncate-quotient n d)}
are the same as @code{(floor (/ n d))} and
@code{(truncate (/ n d))}, respectively.
The @code{*-remainder} counterparts are
derived from the above relation.

The @code{/}-suffixed version, @code{floor/} and @code{truncate/},
returns corresponding quotient and remainder as two values.

@example
(floor-quotient 10 -3)     @result{} -4
(floor-remainder 10 -3)    @result{} -2
(truncate-quotient 10 -3)  @result{} -3
(truncate-remainder 10 -3) @result{} 1
@end example

R7RS division library (@code{scheme.division}) introduces
other variation of integer divisions
(@pxref{R7RS integer division}).
@end defun

@defun gcd n @dots{}
@defunx lcm n @dots{}
[R7RS base]
Returns the greatest common divisor or the least common multiplier
of the given integers, respectively

Arguments must be integers, but doesn't need to be exact.
If any of arguments is inexact, the result is inexact.
@end defun

@defun continued-fraction x
Returns a lazy sequence of regular continued fraction expansion of
finite real number @var{x}.  An error is raised if @var{x} is infinite or
NaN, or not a real number.
The returned sequence is lazy, so the terms are calculated as needed.

@example
(continued-fraction 13579/2468)
  @result{} (5 1 1 122 1 9)

(+ 5 (/ (+ 1 (/ (+ 1 (/ (+ 122 (/ (+ 1 (/ 9))))))))))
  @result{} 13579/2468

(continued-fraction (exact 3.141592653589793))
  @result{} (3 7 15 1 292 1 1 1 2 1 3 1 14 3 3 2 1 3 3 7 2 1 1 3 2 42 2)

(continued-fraction 1.5625)
  @result{} (1.0 1.0 1.0 3.0 2.0)
@end example
@end defun


@defun numerator q
@defunx denominator q
[R7RS base]
Returns the numerator and denominator of a rational number @var{q}.
@end defun

@defun rationalize x ebound
[R7RS base]
Returns the simplest rational approximation @var{q} of a real number @var{x},
such that the difference between @var{x} and @var{q} is no more than
the error bound @var{ebound}.

Note that Gauche doesn't have inexact rational number, so if @var{x}
and/or @var{ebound} is inexact, the result is coerced to
floating point representation.  If you want an exact result,
coerce the arguments to exact number first.

@example
(rationalize 1234/5678 1/1000) @result{} 5/23

(rationalize 3.141592653589793 1/10000)
  @result{} 3.141509433962264
(rationalize (exact 3.141592653589793) 1/10000)
  @result{} 333/106
(rationalize (exact 3.141592653589793) 1/10000000)
  @result{} 75948/24175

;; Some edge cases
(rationalize 2 +inf.0) @result{} 0
(rationalize +inf.0 0) @result{} +inf.0
(rationalize +inf.0 +inf.0) @result{} +nan.0
@end example
@end defun


@defun floor x
@defunx ceiling x
@defunx truncate x
@defunx round x
[R7RS base]
The argument @var{x} must be a real number.
@code{Floor} and @code{ceiling} return a maximum integer that
isn't greater than @var{x} and a minimum integer that isn't less
than @var{x}, respectively.
@code{Truncate} returns an integer that truncates
@var{x} towards zero.  @code{Round} returns an integer that is closest
to @var{x}.  If fractional part of @var{x} is exactly 0.5, @code{round}
returns the closest even integer.

Following Scheme's general rule, the result is inexact if @var{x} is an
inexact number; e.g. @code{(round 2.3)} is @code{2.0}.  If you need
an exact integer by rounding an inexact number, you have to use @code{exact}
on the result, or use one of the following procedure (@code{(floor->exact} etc).
@end defun

@defun floor->exact x
@defunx ceiling->exact x
@defunx truncate->exact x
@defunx round->exact x
These are convenience procedures of the popular
phrase @code{(exact (floor x))} etc.
@end defun

@defun clamp x :optional min max
Returns
@example
 @var{min} @r{if} @var{x} @code{<} @var{min}
 @var{x}   @r{if} @var{min} @code{<=} @var{x} @code{<=} @var{max}
 @var{max} @r{if} @var{max} @code{<} @var{x}
@end example
If @var{min} or @var{max} is omitted or @code{#f}, it is regarded
as @code{-inf.0} or @code{+inf.0}, respectively.
Returns an exact integer only if all the given numbers are exact integers.
@example
(clamp 3.1 0.0 1.0) @result{} 1.0
(clamp 0.5 0.0 1.0) @result{} 0.5
(clamp -0.3 0.0 1.0) @result{} 0.0
(clamp -5 0)        @result{} 0
(clamp 3724 #f 256) @result{} 256
@end example
@end defun


@defun exp z
@defunx log z
@defunx log z1 z2
@defunx sin z
@defunx cos z
@defunx tan z
@defunx asin z
@defunx acos z
@defunx atan z
@defunx atan y x
[R7RS inexact]
Transcendental functions.  Work for complex numbers as well.
In R7RS, these procedures are in the @code{(scheme inexact)} module.

The two-argument version of @code{log} is added in R6RS, and returns
base-@var{z2} logarithm of @var{z1}.

The two-argument version of @code{atan} returns
@code{(angle (make-rectangular x y))} for the real numbers @code{x} and @code{y}.
@end defun

@defun sinh z
@defunx cosh z
@defunx tanh z
@defunx asinh z
@defunx acosh z
@defunx atanh z
Hyperbolic trigonometric functions.  Work for complex numbers as well.
@end defun

@defun sqrt z
[R7RS inexact]
Returns a square root of a complex number @var{z}.
The branch cut scheme is the same as Common Lisp.
For real numbers, it returns a positive root.

If @var{z} is the square of an exact real number, the return value
is also an exact number.

@example
(sqrt 2)      @result{} 1.4142135623730951
(sqrt -2)     @result{} 0.0+1.4142135623730951i
(sqrt 256)    @result{} 16
(sqrt 256.0)  @result{} 16.0
(sqrt 81/169) @result{} 9/13
@end example
@end defun

@defun exact-integer-sqrt k
[R7RS base]
Given an exact nonnegative integer @var{k},
returns two exact nonnegative integer @var{s} and @var{r}
that satisfy the following equations:

@example
@var{k} = (+ (* @var{s} @var{s}) @var{r})
@var{k} < (* (+ @var{s} 1) (+ @var{s} 1))
@end example

@example
(exact-integer-sqrt 782763574)
  @result{} 27977 @r{and} 51045
@end example
@end defun


@defun square z
[R7RS base]
Returns @code{(* z z)}.
@end defun

@defun expt z1 z2
[R7RS base]
Returns @var{z1}^@var{z2} (@var{z1} powered by @var{z2}),
where @var{z1} and @var{z2} are complex numbers.

Scheme standard defines @code{(expt 0 0)} as 1 for convenience.
@end defun

@defun expt-mod base exponent mod
Calculates @code{(modulo (expt base exponent) mod)} efficiently.

The next example shows the last 10 digits of a mersenne prime
M_74207281 (2^74207281 - 1)

@example
(- (expt-mod 2 74207281 #e1e10) 1)
 @result{} 1086436351
@end example
@end defun


@defun gamma x
@defunx lgamma x
Gamma function and natural logarithmic of absolute value of Gamma function.

NB: Mathematically these functions are defined in complex domain, but
currently we only support real number argument.
@end defun

@c NB: These should be moved to a separate subsection once we got
@c more fixnum-specific operation support.

@defun fixnum-width
@defunx greatest-fixnum
@defunx least-fixnum
[R6RS]
These procedures return the width of fixnum (@var{w}),
the greatest integer representable by fixnum (@code{2^(@var{w}-1) - 1}),
and the least integer representable by fixnum (@code{- 2^(@var{w}-1)}),
respectively.  You might want to care the fixnum range when
you are writing a performance-critical section.

These names are defined in R6RS.  Common Lisp and ChezScheme have
@code{most-positive-fixnum} and @code{most-negative-fixnum}.

NB: Before 0.9.5, @code{fixnum-width} had a bug
to return one smaller than the supposed value.
@end defun

@node Numerical conversions, Basic bitwise operations, Arithmetics, Numbers
@subsection Numerical conversions
@c NODE 数値の変換

@defun make-rectangular x1 x2
@defunx make-polar x1 x2
[R7RS complex]
Creates a complex number from two real numbers, @var{x1} and @var{x2}.
@code{make-rectangular} returns @var{x1} + @b{i}@var{x2}.
@code{make-polar} returns @var{x1}@b{e}^(@b{i}@var{x2}).

In R7RS, these procedures are in the @code{(scheme complex)} library.
@end defun

@defun real-part z
@defunx imag-part z
@defunx magnitude z
@defunx angle z
[R7RS complex]
Decompose a complex number @var{z} and returns a real number.
@code{real-part} and @code{imag-part} return @var{z}'s real and imaginary
part, respectively.  @code{magnitude} and @code{angle} return
@var{z}'s magnitude and angle, respectively.

In R7RS, these procedures are in the @code{(scheme complex)} library.
@end defun

@defun decode-float x
For a given finite floating-point number, returns
a vector of three exact integers, @code{#(@var{m}, @var{e}, @var{sign})},
where
@example
  @var{x} = (* @var{sign} @var{m} (expt 2.0 @var{e}))
  @var{sign} is either 1, 0 or -1.
@end example

If @var{x} is @code{+inf.0} or @code{-inf.0}, @var{m} is @code{#t}.
If @var{x} is @code{+nan.0}, @var{m} is @code{#f}.

The API is taken from ChezScheme.

@example
(decode-float 3.1415926)
 @result{} #(7074237631354954 -51 1)
(* 7074237631354954 (expt 2.0 -51))
 @result{} 3.1415926

(decode-float +nan.0)
 @result{} #(#f 0 -1)
@end example
@end defun

@defun encode-float vector
This is an inverse of @code{decode-float}.  @var{Vector} must be
a three-element vector as returned from @code{decode-float}.

@example
(encode-float '#(7074237631354954 -51 1))
 @result{} 3.1415926

(encode-float '#(#t 0 1))
 @result{} +inf.0
@end example
@end defun


@defun fmod x y
@defunx modf x
@defunx frexp x
@defunx ldexp x n
[POSIX]
These procedures can be used to compose and decompose floating
point numbers.  @code{Fmod} computes the remainder of dividing @var{x}
by @var{y}, that is, it returns @var{x}-@var{n}*@var{y} where
@var{n} is the quotient of @var{x}/@var{y} rounded towards zero
to an integer.   @code{Modf} returns two values; a fractional
part of @var{x} and an integral part of @var{x}.   @code{Frexp}
returns two values, @var{fraction} and @var{exponent} of @var{x},
where @var{x} = @var{fraction} * 2^@var{exponent}, and
0.5 <= |@var{fraction}| < 1.0, unless @var{x} is zero.  
(When @var{x} is zero, both @var{fraction} and @var{exponent} are zero).
@var{Ldexp} is a reverse operation of
@code{frexp}; it returns a real number @var{x} * 2^@var{n}.

@example
(fmod 32.1 10.0)  @result{} 2.1
(fmod 1.5 1.4)    @result{} 0.1
(modf 12.5)       @result{} 0.5 @r{and} 12.0
(frexp 3.14)      @result{} 0.785 @r{and} 2
(ldexp 0.785 2)   @result{} 3.14
@end example
@end defun

@c @defun logb x
@c @defunx ilogb x
@c [POSIX]
@c @c EN
@c These procedure returns exponent of flonum @var{x}.  The return value
@c of @code{logb} is a flonum, whereas the return value of @code{ilogb} is
@c an exact integer.

@c If @var{x} is 0, infinity, or NaN, @code{logb} returns @code{-inf.0},
@c @code{+inf.0} and @code{+nan.0}, respectively.  What @code{ilogb} returns
@c in those cases are platform-dependent, but it's consistent in one platform,
@c @c JP
@c 浮動小数点数@var{x}の指数部を返します。@code{logb}の戻り値は浮動小数点数、
@c @code{ilogb}の戻り値は正確な整数です。

@c @var{x}が0、±無限大、NaNの場合、@code{logb}はそれぞれ@code{-inf.0}、
@c @code{+inf.0}、@code{+nan.0}を返します。これらの場合に@code{ilogb}が返す値は
@c プラットフォームに依存しますが、一つのプラットフォームの上では一貫しています。
@c @c COMMON

@c @example
@c (logb 1)  @result{} 0.0
@c (ilogb 1) @result{} 0

@c (logb  2) @result{} 1.0
@c (logb -2) @result{} 1.0
@c (logb -0.5) @result{} -1.0

@c (logb 5.0e-324) @result{} -1074.0
@c (logb 1.7976931348623157e308) @result{} 1023.0

@c (logb 0) @result{} -inf.0
@c (logb +inf.0) @result{} +inf.0
@c (logb -inf.0) @result{} +inf.0
@c (logb +nan.0) @result{} +nan.0

@c (ilogb 0) @result{} -2147483648 ;; platform dependent
@c (ilogb +inf.0) @result{} 2147483647 ;; platform dependent
@c (ilogb +nan.0) @result{} -2147483648 ;; platform dependent
@c @end example
@c @end defun


@defun exact z
@defunx inexact z
[R7RS base]
Returns an exact or an inexact representation of the
given number @var{z}, respectively.  Passing an exact number
to @code{exact}, and an inexact number to @code{inexact}, are no-op.

Gauche doesn't have exact complex number with non-zero imaginary part,
nor exact infinites and NaNs, so passing those to @code{exact} raises
an error.

@example
(inexact 1)    @result{} 1.0
(inexact 1/10) @result{} 0.1
@end example

If an inexact finite real number is passed to @code{exact},
the simplest exact rational number within the precision of the
floating point representation is returned.

@example
(exact 1.0)     @result{} 1
(exact 0.1)     @result{} 1/10
(exact (/ 3.0)) @result{} 1/3
@end example

For all finite inexact real number @var{x}, 
@code{(inexact (exact @var{x}))} is always @code{eqv?} to
the original number @var{x}.

(Note that the inverse doesn't hold, that is, an exact number @var{n}
and @code{(exact (inexact @var{n}))} aren't necessarily the same.
It's because many (actually, infinite number of) exact numbers
can be mapped to one inexact number.)

To specify the error tolerance when converting inexact real numbers
to exact rational numbers, use @code{rationalize} or @code{real->rational}.
@end defun

@defun exact->inexact z
@defunx inexact->exact z
[R5RS]
Converts exact number to inexact one, and vice versa.

In fact, @code{exact->inexact} returns the argument as is
if an inexact number is passed, and @code{inexact->exact}
returns the argument if an exact number is passed, so
in Gauche they are equivalent to @code{inexact} and @code{exact},
respectively.  Note that other R5RS implementation may raise
an error if passing an inexact number to @code{exact->inexact},
for example.

Generally @code{exact} and @code{inexact} are preferred,
for they are more concise, and you don't need to care
whether the argument is exact or inexact numbers.
These procedures are for compatibility with R5RS programs.
@end defun

@defun real->rational x :optional hi lo open?
Find the simplest rational representation of a finite real
number @var{x} within the specified error bounds.  This is the low-level
routine called by @code{rationalize} and @code{exact}.
Typically you want to use @code{rationalize} (@pxref{Arithmetics})
for this purpose.  Use @code{real->rational} only when you need finer
control of error bounds.

The result
rational value @var{r} satisfies the following condition:

@example
(<= (- x lo) r (+ x hi))   ; when open? is #f
(<  (- x lo) r (+ x hi))   ; otherwise
@end example

Note that both @var{hi} and @var{lo} must be nonnegative.

If @var{hi} and/or @var{lo} is omitted, it is determined by @var{x}:
if @var{x} is exact, @var{hi} and @var{lo} are defaulted to zero; if
@var{x} is inexact, @var{hi} and @var{lo} depend on
the precision of the floating point representation of @var{x}.
In the latter case, the @var{open?} also depends on @var{x}---it is true
if the mantissa of @var{x} is odd, and false otherwise, reflecting
the round-to-even rule.   So, if you call @code{real->rational} with
one finite number, you'll get the same result as @code{exact}:

@example
(real->rational 0.1) @result{} 1/10
@end example

Passing zeros to the error bounds makes it return the exact
conversion of the floating number itself (that is, the exact
calculation of @code{(* sign mantissa (expt 2 exponent))}).

@example
(real->rational 0.1 0 0) @result{} 3602879701896397/36028797018963968
@end example

(If you give both @var{hi} and @var{lo}, but omit @var{open?}, 
we assume closed range.)
@end defun

@defun number->string z :optional radix use-upper?
@defunx string->number string :optional radix default-exactness
[R7RS+]
These procedures convert a number and its string representation
in radix @var{radix} system.
@var{radix} must be between 2 and 36 inclusive.
If @var{radix} is omitted, 10 is assumed.

@code{Number->string} takes a number @var{z} and returns a string.
If @var{z} is not an exact integer, @var{radix} must be 10.
For the numbers with radix more than 10, lower case alphabet
character is used for digits, unless the optional argument
@var{use-upper?} is true, in that case upper case characters are used.
The argument @var{use-upper?} is Gauche's extension.

@code{String->number} takes a string @var{string} and parses it
as a number in radix @var{radix} system.  If the number contains
a decimal point, only radix 10 is allowed.  If the given string
can't be a number, @code{#f} is returned.

The @var{default-exactness} optional argument of @code{string->number}
is Gauche's extension, and it must be either @code{#f} (default),
a symbol @code{exact}, or a symbol @code{inexact}.
If it is either symbol, it sets the exactness of the number if
no exactness prefix (@code{#e} or @code{#i}) is given.

@example
(string->number "2.718281828459045" 10 'exact)
  @result{} 543656365691809/200000000000000
(string->number "#i2.718281828459045" 10 'exact)
  @result{} 2.718281828459045
(string->number "1/3" 10 'inexact)
  @result{} 0.3333333333333333
(string->number "#e1/3" 10 'inexact)
  @result{} 1/3
@end example
@end defun

@deffn {Generic Function} x->number obj
@deffnx {Generic Function} x->integer obj
Generic coercion functions.  Returns `natural' interpretation of @var{obj}
as a number or an exact integer, respectively.
The default methods are defined for numbers and strings; a string is
interpreted by @code{string->number}, and if the string can't be
interpreted as a number, 0 is returned.
Other @var{obj} is simply converted to 0.
If @var{obj} is naturally interpreted
as a number that is not an exact integer, @code{x->integer} uses
@code{round} and @code{inexact->exact} to obtain an integer.

Other class may provide a method to customize the behavior.
@end deffn

@node Basic bitwise operations, Endianness, Numerical conversions, Numbers
@subsection Basic bitwise operations
@c NODE 基本的なビット演算

These procedures treat integers as half-open bit vectors.
If an integer is positive, it is regarded as if infinite number
of zeros are padded to the left.  If an integer is negative,
it is regarded in 2's complement form, and infinite number of
1's are padded to the left.

In regard to the names of those operations, there are two groups
in the Scheme world; Gauche follows the names of the
original SLIB's ``logical'' module, which was rooted in CL.
Another group uses a bit long but descriptive name such as
@code{arithmetic-shift}.

R7RS bitwise library
(@pxref{R7RS bitwise operations}) provides additional bitwise operations.

@defun ash n count
[SRFI-60]
Shifts integer @var{n} left with @var{count} bits.
If @var{count} is negative, @code{ash} shifts @var{n} right with
@minus{}@var{count} bits.

@example
; @r{Note: 6  @equiv{} [...00110], and}
; @r{      -6 @equiv{} [...11010]}
(ash 6 2)   @result{} 24  ;@r{[...0011000]}
(ash 6 -2)  @result{} 1   ;@r{[...0000001]}
(ash -6 2)  @result{} -24 ;@r{[...1101000]}
(ash -6 -2) @result{} -2  ;@r{[...1111110]}
@end example
@end defun

@defun logand n1 @dots{}
@defunx logior n1 @dots{}
@defunx logxor n1 @dots{}
[SRFI-60]
Returns bitwise and, bitwise inclusive or and bitwise exclusive or
of integers @var{n1} @dots{}.   If no arguments are given, @code{logand}
returns @code{-1}, and @code{logior} and @code{logxor} returns @code{0}.
@end defun

@defun lognot n
[SRFI-60]
Returns bitwise not of an integer @var{n}.
@end defun

@defun logtest n1 n2 @dots{}
[SRFI-60]
@equiv{} @code{(not (zero? (logand @var{n1} @var{n2} @dots{})))}
@end defun

@defun logbit? index n
[SRFI-60]
Returns @code{#t} if @var{index}-th bit of integer @var{n} is 1,
@code{#f} otherwise.
@end defun

@defun bit-field n start end
[R7RS bitwise]
Extracts @var{start}-th bit (inclusive) to @var{end}-th bit (exclusive) from
an exact integer @var{n}, where @var{start} < @var{end}.
@end defun

@defun copy-bit index n bit
[R7RS bitwise]
If @var{bit} is true, sets @var{index}-th bit of an exact integer @var{n}.
If @var{bit} is false, resets @var{index}-th bit of an exact integer @var{n}.
@end defun

@defun copy-bit-field n from start end
[SRFI-60]
Returns an exact integer, each bit of which is the same as
@var{n} except the @var{start}-th bit (inclusive) to @var{end}-th
bit (exclusive), which is a copy of the lower
@code{(@var{end}-@var{start})}-th bits of an exact
integer @var{from}.

@example
(number->string (copy-bit-field #b10000000 -1 1 5) 2)
  @result{} "10011110"

(number->string (copy-bit-field #b10000000 #b010101010 1 7) 2)
  @result{} "11010100"
@end example

Note: The API of this procedure was originally taken from SLIB,
and at that time,
the argument order was @code{(copy-bit-field n start end from)}.
During the discussion of SRFI-60 the argument order was changed
for the consistency, and the new versions of SLIB followed it.
We didn't realize the change until recently - before 0.9.4, 
@emph{this procedure had the old argument order}.  Code that is using
this procedure needs to be fixed.  If you need your code to work
with both versions of Gauche, have the following definition
in your code.

@example
(define (copy-bit-field to from start end)
  (if (< start end)
    (let1 mask (- (ash 1 (- end start)) 1)
      (logior (logand to (lognot (ash mask start)))
              (ash (logand from mask) start)))
    from))
@end example

@end defun

@defun logcount n
[SRFI-60]
If @var{n} is positive, returns the number of @code{1}'s in the
bits of @var{n}.  If @var{n} is negative,
returns the number of @code{0}'s in the bits of 2's complement
representation of @var{n}.

@example
(logcount 0)      @result{} 0
(logcount #b0010) @result{} 1
(logcount #b0110) @result{} 2
(logcount #b1111) @result{} 4

(logcount #b-0001) @result{} 0  ;; 2's complement:  ....111111
(logcount #b-0010) @result{} 1  ;; 2's complement:  ....111110
(logcount #b-0011) @result{} 1  ;; 2's complement:  ....111101
(logcount #b-0100) @result{} 2  ;; 2's complement:  ....111100
@end example
@end defun

@defun integer-length n
[R7RS bitwise]
Returns the minimum number of bits required to represent an
exact integer @var{n}.  Negative integer is assumed to be in
2's complement form.  A sign bit is not considered.

@example
(integer-length 255)  @result{} 8
(integer-length 256)  @result{} 9

(integer-length -256)  @result{} 8
(integer-length -257)  @result{} 9
@end example
@end defun

@defun twos-exponent n
If @var{n} is a power of two, that is, @code{(expt 2 k)} and @code{k >= 0}, 
then returns @code{k}.  Returns @code{#f} if @var{n} is not a power of two.
@end defun

@defun twos-exponent-factor n
Returns maximum @var{k} such that @code{(expt 2 k)} is a factor of @var{n}.
In other words, returns the number of consecutive zero bits from LSB
of @var{n}.  When @var{n} is zero, we return @code{-1} for the
consistency of the following equivalent expression.

This can be calculated by the following expression; this procedure
is for speed to save creating intermediate numbers when @var{n} is bignum.
@example
(- (integer-length (logxor n (- n 1))) 1)
@end example

This procedure is also equivalent to srfi-60's @code{log2-binary-factors} and
@code{first-set-bit} (@pxref{Integers as bits}).
@end defun

@node Endianness,  , Basic bitwise operations, Numbers
@subsection Endianness
@c NODE エンディアンネス

In the Scheme world you rarely need to know about how the numbers
are represented inside the machine.  However, it matters
when you have to exchange data to/from the outer world in
binary representation.

Gauche's binary I/O procedures, such as in
the @code{binary.io} module (@pxref{Binary I/O}) and
@code{write-uvector}/@code{read-uvector!}
(@pxref{Uniform vectors}), take optional @var{endian} argument
to specify the endianness.

Currently Gauche recognizes the following endiannesses.

@table @code
@item big-endian
@itemx big
Big-endian.  With this endianness, a 32-bit integer @code{#x12345678}
will be written out as an octet sequence @code{#x12 #x34 #x56 #x78}.

Gauche has been using @code{big-endian}, but @code{scheme.bytevector}
incorporated in R7RS uses @code{big}, so we recognize both.
@item little-endian
@itemx little
Little-endian.  With this endianness, a 32-bit integer @code{#x12345678}
is written out as an octet sequence @code{#x78 #x56 #x34 #x12}.

Gauche has been using @code{little-endian}, but @code{scheme.bytevector}
incorporated in R7RS uses @code{little}, so we recognize both.
@item arm-little-endian
This is a variation of @code{little-endian}, and used in ARM
processors in some specific modes.  It works just like @code{little-endian},
except reading/writing double-precision floating point number (@code{f64}),
which is written as two little-endian 32bit words ordered by big-endian
(e.g. If machine register's representation is @code{#x0102030405060708},
it is written as @code{#x04 #x03 #x02 #x01 #x08 #x07 #x06 #x05}.
@end table

When the @var{endian} argument is omitted, those procedures
use the parameter @code{default-endian}:

@deffn {Parameter} default-endian
This is a dynamic parameter (@pxref{Parameters}) to specify
the endianness the binary I/O routines use when its @var{endian}
argument is omitted.  The initial value of this parameter is
the system's native endianness.
@end deffn

The system's native endianness can be queried with the following
procedure:

@defun native-endian
Returns a symbol representing the system's endianness.
@end defun


@c ----------------------------------------------------------------------
@node Booleans, Undefined values, Numbers, Core library
@section Booleans
@c NODE 論理値

@deftp {Builtin Class} <boolean>
@clindex boolean
A boolean class.  Only @code{#t} and @code{#f} belong to this class.
@end deftp

@defun not obj
[R7RS base]
Returns @code{#t} if and only if @var{obj} is @code{#f},
and returns @code{#f} otherwise.
@end defun

@defun boolean? obj
[R7RS base]
Returns @code{#t} if @var{obj} is a boolean value.
@end defun

@defun boolean obj
Returns @code{#f} iff @var{obj} is @code{#f}, and returns @code{#t}
otherwise.  Convenient to coerce a value to boolean.
@end defun

@defun boolean=? a b c @dots{}
[R7RS base]
Every argument must be a boolean value.  Returns @code{#t} iff all
values are the same, @code{#f} otherwise.
@end defun

@c ----------------------------------------------------------------------
@node Undefined values, Pairs and lists, Booleans, Core library
@section Undefined values
@c NODE 未定義値

While working with Gauche, sometimes you encounter
a value printed as @code{#<undef>}, an @emph{undefined} value.

@example
gosh> (if #f #t)
#<undef>
@end example

It is a value used as a filler where the actual value doesn't matter,
or there's no other suitable value, or the binding hasn't been calculated.

Do not confuse undefined values with unbound variables;
A variable can be bound to @code{#<undef>}, for it is just
an ordinary first-class value.  On the other hand, an
unbound variable means there's no value associated with the variable.

However, @code{#<undef>} may be used in certain
occasions to indicate that a value is not provided for
the variable.  For example, 
the toplevel variable can be bound to @code{#<undef>} if it is
defined by @code{(define variable)} form (@pxref{Definitions}).
An optional procedure parameter
without default value is bound to @code{#<undef>} if an
actual argument is not given (@pxref{Making procedures}).

Note that it cannot be distinguished from the case
a value is actually provided, and the value just happens
to be @code{#<undef>}.  If you get an @code{#<undef>},
you can say at most is that the value doesn't matter.
You shouldn't let it carry too much meanings.

The @code{#<undef>} value is counted as true value in generalized 
boolean context,
since it is not @code{#f}.  However, branching based on @code{#<undef>}
is dangerous---a procedure that is defined to return unspecified value
may merely returning @code{#<undef>} as a provisional value; it will 
change the return value in future.  Since the return value isn't specified,
no one should be using it.  The code that tests such result value as
a generalized boolean may break if the procedure changes the return value.

In fact, we've found that there are quite a few code that accidentally tests
@code{#<undef>} return value in conditionals.  They can be seeds
for future bugs, so we added a feature to warn when @code{#<undef>} value
is used in the test of branches.  You can turn it on with
setting the environment variable @code{GAUCHE_CHECK_UNDEFINED_TEST}.
In future, we may turn it on while testing.

One typical case of such accidental use of @code{#<undef>} branching
is in @code{and-let*}; the following code assumes @code{print} always return
@code{#<undef>}, which is counted as a true value, and expects the control
to proceeed to the next clause.  It'll break if @code{print} ever changes
so that it may return @code{#f} in some cases.

@example
(and-let* ([var (foo x y z)]
           [ (print var) ]    ;; branch on #<undef>
           [baz (bar var)])
  ...)
@end example

Being said that, there are a couple of procedures
to deal with undefined values.

@defun undefined? obj
Returns @code{#t} iff @var{obj} is an undefined value.
@end defun

@defun undefined
Returns an undefined value.
@end defun

@c ----------------------------------------------------------------------
@node Pairs and lists, Symbols, Undefined values, Core library
@section Pairs and lists
@c NODE ペアとリスト

Pairs and lists are one of the most fundamental data structure in Scheme.
Gauche core provides all standard list procedures, plus some useful
procedures that are commonly supported in lots of implementations.
If they are not enough, you can find more procedures in the modules
described in @ref{R7RS lists} and
@ref{Combination library}.
See also @ref{Collection framework} and
@ref{Sequence framework} for generic collection/sequence
operations.

@menu
* Pair and null class::
* Mutable and immutable pairs::
* List predicates::
* List constructors::
* List accessors and modifiers::
* Walking over lists::
* Other list procedures::
* Association lists::
@end menu

@node Pair and null class, Mutable and immutable pairs, Pairs and lists, Pairs and lists
@subsection Pair and null class
@c NODE pairクラスとnullクラス

@deftp {Builtin Class} <list>
@clindex list
An abstract class represents lists.   A parent class of @code{<null>}
and @code{<pair>}.   Inherits @code{<sequence>}.

Note that a circular list is also an instance of the @code{<list>} class,
while @code{list?} returns false on the circular lists and
dotted lists.
@lisp
(use srfi-1)
(list? (circular-list 1 2)) @result{} #f
(is-a? (circular-list 1 2) <list>) @result{} #t
@end lisp
@end deftp

@deftp {Builtin Class} <null>
@clindex null
A class of empty list.  @code{()} is the only instance.
@end deftp

@deftp {Builtin Class} <pair>
@clindex pair
A class of pairs.
@end deftp

@node Mutable and immutable pairs, List predicates, Pair and null class, Pairs and lists
@subsection Mutable and immutable pairs
@c NODE 変更可能なペアと変更不可なペア

A pair may be either mutable or immutable.  You can desctructively
modify mutable pairs with @code{set-car!}, @code{set-cdr!}, or other
destructive procedures (usually they have @code{!} at the end).
An error is signaled when you try to modify an immutable pair.

In Gauche, both type of pairs can be treated the same unless you try 
to modify them.  Both satisfies the predicate @code{pair?}.  If you
need to test specifically if a pair is immutable, use @code{ipair?}
(@pxref{List predicates}).
The traditional constructor @code{cons} creates a mutable pair; you
can create an immutable pair with @code{ipair} (@pxref{List constructors}).
More procedures that use immutable pairs are defined in
R7RS-large @code{scheme.ilist} module (@pxref{R7RS immutable lists}).

Note that quoted literals are immutable.
Old versions of Gauche wasn't supported immutable pairs and quoted literal lists
were mutable.  If your code accidentally mutate such pairs, you'll get an
error.  If you need to run such code without tracking down the error,
you can define the environment variable
@code{GAUCHE_MUTABLE_LITERALS}.


@node List predicates, List constructors, Mutable and immutable pairs, Pairs and lists
@subsection List predicates
@c NODE リストに関する述語

@defun pair? obj
[R7RS base]
Returns @code{#t} if @var{obj} is a pair, @code{#f} otherwise.
@end defun

@defun ipair? obj
[R7RS ilist]
Returns @code{#t} iff @var{obj} is an immutable pair, @code{#f} otherwise.

An immutable pair is indistinguishable from a mutable pair except using
this predicate, or when you attempt to modify it.
@xref{Mutable and immutable pairs}.
@end defun

@defun null? obj
[R7RS base]
Returns @code{#t} if @var{obj} is an empty list, @code{#f} otherwise.
@end defun

@defun null-list? obj
[R7RS list]
Returns @code{#t} if @var{obj} is an empty list,
@code{#f} if @var{obj} is a pair.  If @var{obj} is neither
a pair nor an empty list, an error is signaled.

This can be used instead of @code{null?} to check the end-of-list
condition when you want to be more picky about non-proper lists.
@end defun

@defun list? obj
[R7RS base]
Returns @code{#t} if @var{obj} is a proper list, @code{#f} otherwise.
This function returns @code{#f} if @var{obj} is a dotted or circular list.

See also @code{proper-list?}, @code{circular-list?} and
@code{dotted-list?} below.
@end defun


@defun proper-list? x
[R7RS list]
Returns @code{#t} fif x is a proper list, that is, a finite list
terminated by @code{()}.
@end defun

@defun circular-list? x
[R7RS list]
Returns @code{#t} if x is a circular list.  A list is circular if
you follow @code{cdr} of the pairs you'll eventually get to a pair
you already visited.  It doesn't necessary that the head of the list
@var{x} is a part of the circle.  A list isn't circular by the
cycle that involves @var{car} of the paris.
@end defun

@defun dotted-list? x
[R7RS list]
Returns @code{#t} if x is a finite, non-nil-terminated list.
This includes non-pair, non-() values (e.g. symbols, numbers),
which are considered to be dotted lists of length 0.
@end defun


@node List constructors, List accessors and modifiers, List predicates, Pairs and lists
@subsection List constructors
@c NODE リストの作成

@defun cons obj1 obj2
[R7RS base]
Constructs a mutable pair of @var{obj1} and @var{obj2} and returns it.
@lisp
(cons 'a 'b) @result{} (a . b)
@end lisp
@end defun

@defun ipair obj1 obj2
[R7RS ilist]
Constructs an immutable pair of @var{obj1} and @var{obj2} and returns it.
@lisp
(ipair 'a 'b) @result{} (a . b)
@end lisp
@end defun

@defun make-list len :optional fill
[R7RS base]
Makes a proper list of length @var{len}.  If optional argument
@var{fill} is provided, each element is initialized by it.  Otherwise
each element is undefined.

@lisp
(make-list 5 #t) @result{} (#t #t #t #t #t)
@end lisp
@end defun

@defun list obj @dots{}
[R7RS base]
Makes a list, whose elements are @var{obj} @dots{}.
@lisp
(list 1 2 3) @result{} (1 2 3)
(list) @result{} ()
@end lisp
@end defun

@defun ilist obj @dots{}
[R7RS ilist]
Makes a list, whose elements are @var{obj} @dots{},
and which consists of immutable pairs.
@lisp
(ilist 1 2 3) @result{} (1 2 3)
(ilist) @result{} ()

(list-set! (ilist 1 2 3) 1 'a)
  @result{} ERROR: Attempt to modify an immutable pair: (2 3)
@end lisp
@end defun

@defun list* obj1 obj2 @dots{}
@defunx cons* obj1 obj2 @dots{}
[R7RS list]
Like @code{list}, but the last argument becomes cdr of the last pair.
Two procedures are exactly the same.  Gauche originally had @code{list*},
and SRFI-1 (R7RS @code{(scheme list)})defines @code{cons*}.
@lisp
(list* 1 2 3) @result{} (1 2 . 3)
(list* 1) @result{} 1
@end lisp
@end defun

@defun list-copy list
[R7RS base]
Shallow copies @var{list}.  
If @var{list} is circular, an error is thrown.
(Detecting circular list is Gauche's extension; R7RS allows
the procedure to diverge.)
@end defun

@defun iota count :optional (start 0) (step 1)
[R7RS list]
Returns a list of @var{count} numbers, starting from @var{start},
increasing by @var{step}.   @var{Count} must be a nonnegative
integer.  If both @var{start} and @var{step} are exact,
the result is a list of exact numbers; otherwise, it is a list
of inexact numbers.
@example
(iota 5)        @result{} (0 1 2 3 4)
(iota 5 1 3/7)  @result{} (1 10/7 13/7 16/7 19/7)
(iota 5 0 -0.1) @result{} (0 -0.1 -0.2 -0.3 -0.4)
@end example

This creates a list eagerly.  If the list is short it is fast
enough, but if you want to count tens of thousands of numbers,
you may want to do so lazily.  See @code{liota} (@pxref{Lazy sequences}).
@end defun

@defmac cond-list clause @dots{}
Construct a list by conditionally adding entries.
Each @var{clause} has a test and expressions.  When its test
yields true, the result of associated expression is used to
construct the resulting list.  When the
test yields false, nothing is inserted.

@var{Clause} must be either one of the following form:
@table @code
@item (@var{test} @var{expr} @dots{})
@var{Test} is evaluated, and when it is true,
@var{expr} @dots{} are evaluated, and the return value
becomes a part of the result.  If no @var{expr} is given,
the result of @var{test} is used if it is not false.
@item (@var{test} => @var{proc})
@var{Test} is evaluated, and when it is true,
@var{proc} is called with the value, and the return
value is used to construct the result.
@item (@var{test} @@ @var{expr} @dots{})
Like @code{(test expr @dots{})}, except that the result of
the last @var{expr} must be a list, and it is spliced into
the resulting list, like unquote-splicing.
@item (@var{test} => @@ @var{proc})
Like @code{(test => proc)}, except that the result of
@var{proc} must be a list, and and it is spliced into
the resulting list, like unquote-splicing.
@end table

@example
(let ((alist '((x 3) (y -1) (z 6))))
 (cond-list ((assoc 'x alist) 'have-x)
            ((assoc 'w alist) 'have-w)
            ((assoc 'z alist) => cadr)))
  @result{} (have-x 6)

(let ((x 2) (y #f) (z 5))
  (cond-list (x @@ `(:x ,x))
             (y @@ `(:y ,y))
             (z @@ `(:z ,z))))
  @result{} (:x 2 :z 5)
@end example
@end defmac


@node List accessors and modifiers, Walking over lists, List constructors, Pairs and lists
@subsection List accessors and modifiers
@c NODE リストへのアクセスと変更

@defun car pair
@defunx cdr pair
[R7RS base]
Returns car and cdr of @var{pair}, respectively.
@end defun

@defun set-car! pair obj
@defunx set-cdr! pair obj
[R7RS base]
Modifies car and cdr of @var{pair}, by @var{obj}, respectively.

Note: @code{(setter car)} @equiv{} @code{set-car!}, and
@code{(setter cdr)} @equiv{} @code{set-cdr!}.
@end defun

@defun caar pair
@defunx cadr pair
@findex cdar
@findex cddr
@findex caaar
@findex caadr
@findex cadar
@findex caddr
@findex cdaar
@findex cdadr
@findex cddar
@findex cdddr
@findex caaaar
@findex caaadr
@findex caadar
@findex caaddr
@findex cadaar
@findex cadadr
@findex caddar
@findex cadddr
@findex cdaaar
@findex cdaadr
@findex cdadar
@findex cdaddr
@findex cddaar
@findex cddadr
@dots{}
@end defun
@defun cdddar pair
@defunx cddddr pair
[R7RS base][R7RS cxr]
@code{caar} @equiv{} @code{(car (car x))},
@code{cadr} @equiv{} @code{(car (cdr x))}, and so on.

In R7RS, more than two-level of accessors are defined in the
@code{(scheme cxr)} library.

The corresponding setters are also defined.
@example
(let ((x (list 1 2 3 4 5)))
  (set! (caddr x) -1)
  x)
  @result{} (1 2 -1 4 5)
@end example
@end defun

@defun length list
[R7RS base]
Returns the length of a proper list @var{list}.
If @var{list} is a dotted list, an error is signaled.
If @var{list} is a circular list, this function diverges.
@end defun

@defun length+ x
[R7RS list]
If @var{x} is a proper list, returns its length.
For all other @var{x}, including a circular list,
it returns @code{#f}.
@end defun

@defun length=? x k
@defunx length<? x k
@defunx length<=? x k
@defunx length>? x k
@defunx length>=? x k
Returns @code{#t} iff @var{x} is a (possibly improper) list whose length is
equal to, less than, less than or equal to, greater than, or greater than
or equal to an exact integer @var{k}, respectively.
This procedure only follows the list up to the @var{k} items, so
it doesn't realize elements of lazy sequence more than
needed (@xref{Lazy sequences}, for the lazy sequences).

Dotted lists and circular lists are allowed.  For the dotted list,
the cdr of the last pair isn't counted; that is, a non-pair object
has length 0, and @code{(a . b)} has length 1.
A circular list is treated as if it has infinite length.

@example
(length<=? '(a b) 2)  @result{} #t
(length<=? '(a b) 1)  @result{} #f
(length<=? '()    0)  @result{} #t

;; dotted list cases
(length<=? 'a       0)  @result{} #t
(length<=? '(a . b) 0)  @result{} #f
(length<=? '(a . b) 1)  @result{} #t
@end example

NB: The name of these procedures might be misleading, for other procedures
with the name @code{something<=?} etc. usually takes objects of the same type.
We don't have any better idea now, unfortunately.
@end defun


@defun take x i
@defunx drop x i
[R7RS list]
@code{take} returns the first i elements of list x.
@code{drop} returns all but the first i elements of list x.
@example
(take '(a b c d e) 2) => (a b)
(drop '(a b c d e) 2) => (c d e)
@end example
@var{x} may be any value:
@example
(take '(1 2 3 . d) 2) => (1 2)
(drop '(1 2 3 . d) 2) => (3 . d)
(drop '(1 2 3 . d) 3) => d
@end example
@code{drop} is exactly equivalent to performing @var{i} cdr operations
on @var{x}.  The returned value shares a common tail with @var{x}.
On the other hand, take always allocates a new list
for result if the argument is a list of non-zero length.

An error is signaled if @var{i} is past the end of list @var{x}.
See @code{take*} and @code{drop*} below for more tolerant version.

For generic subsequence extraction from any sequence, see @code{subseq}
in @ref{Slicing sequence}.
@end defun

@defun take* list k :optional (fill? #f) (padding #f)
@defunx drop* list k
More tolerant version of @code{take} and @code{drop}.
They won't raise an error even if @var{k} is larger than the size
of the given list.

If the list is shorter than @var{k} elements,
@code{take*} returns a copy of @var{list}
by default.   If @var{fill?} is true, @var{padding} is added
to the result to make its length @var{k}.

On the other hand, @code{drop*} just returns an empty list
when the input list is shorter than @var{k} elements.

@example
(take* '(a b c d) 3)       @result{} (a b c)
(take* '(a b c d) 6)       @result{} (a b c d)
(take* '(a b c d) 6 #t)    @result{} (a b c d #f #f)
(take* '(a b c d) 6 #t 'z) @result{} (a b c d z z)
(drop* '(a b c d) 3)       @result{} (d)
(drop* '(a b c d) 5)       @result{} ()
@end example

Note: For generic subsequence extraction from any sequence,
see @code{subseq} in @ref{Slicing sequence}.
@end defun

@defun take-right lis k
@defunx drop-right lis k
[R7RS list]
@code{take-right} returns the last @var{k} elements of @var{lis}.
@code{drop-right} returns all but the last @var{k} elements of @var{lis}.
@example
(take-right '(a b c d e) 2) => (d e)
(drop-right '(a b c d e) 2) => (a b c)
@end example
@var{lis} may be any finite list.
@example
(take-right '(1 2 3 . d) 2) => (2 3 . d)
(drop-right '(1 2 3 . d) 2) => (1)
(take-right '(1 2 3 . d) 0) => d
(drop-right '(1 2 3 . d) 0) => (1 2 3)
@end example
@code{take-right}'s return value always shares a common
tail with @var{lis}.
@code{drop-right} always allocates a new list
if the argument is a list of non-zero length.

An error is signaled if @var{k} is larger than the length of @var{lis}.
See @code{take-right*} and @code{drop-right*} below, for more tolerant
version.
@end defun

@defun take-right* list k :optional (fill? #f) (padding #f)
@defunx drop-right* list k
Like @code{take*} and @code{drop*}, but counts from right of @var{list}.
If @var{list} is shorter than @var{k} elements, they won't raise
an error.  Instead, @code{drop-right*} just returns an empty list,
and @code{take-right*} returns @var{list} itself by default.
If @var{fill?} is true for @code{take-right*},
@var{padding} is added on the left of the result to make its length @var{k}.
The result still shares the @var{list}.
@end defun

@defun take! lis k
@defunx drop-right! lis k
[R7RS list]
Linear update variants of @code{take} and @code{drop-right}.
Those procedures may destructively modifies @var{lis}.

If @var{lis} is circular, @code{take!} may return a list
shorter than expected.
@end defun

@defun list-tail list k :optional fallback
[R7RS base]
Returns @var{k}-th cdr of @var{list}.
@var{list} can be a proper, dotted or circular list.
(If @var{list} is a dotted list, its last @code{cdr} is simply ignored).

If @var{k} is negative or larger than the length of @var{list},
the behavior depends on whether the optional @var{fallback} argument
is given or not.  If @var{fallback} is given, it is returned.
Otherwise, an error is signaled.
@end defun

@defun list-ref list k :optional fallback
[R7RS+]
Returns @var{k}-th element of @var{list}.
@var{list} can be a proper, dotted or circular list.

By default, @code{list-ref} signals an error if @var{k} is
negative, or greater than or equal to the length of @var{list}.
However, if an optional argument @var{fallback} is given,
it is returned for such case.  This is an extension of Gauche.
@end defun

@defun list-set! list k v
[R7RS base]
Modifies the @var{k}-th element of a @var{list} by @var{v}.
It is an error unless @var{k} is an exact integer between 0 and
one minus the length of @var{k}.  If @var{list} is immutable,
no error is signalled but the behavior is undefined.
@end defun


@defun last-pair list
[R7RS list]
Returns the last pair of @var{list}.
@var{list} can be a proper or dotted list.

@example
(last-pair '(1 2 3))   @result{} (3)
(last-pair '(1 2 . 3)) @result{} (2 . 3)
(last-pair 1)          @result{} @i{error}
@end example
@end defun

@defun last pair
[R7RS list]
Returns the last element of the non-empty, finite list @var{pair}.
It is equivalent to @code{(car (last-pair pair))}.

@example
(last '(1 2 3))   @result{} 3
(last '(1 2 . 3)) @result{} 2
@end example
@end defun

@defun split-at x i
@defunx split-at! x i
[R7RS list]
@code{split-at} splits the list @var{x} at index @var{i},
returning a list of the first @var{i} elements, and the remaining tail.
@example
(split-at '(a b c d e) 2) @result{} (a b) (c d e)
@end example
@code{split-at!} is the linear-update variant. It may destructively
modifies @var{x} to produce the result.
@end defun

@defun split-at* list k :optional (fill? #f) (padding #f)
More tolerant version of @code{split-at}.
Returns the results of @code{take*} and @code{drop*}.

@example
(split-at* '(a b c d) 6 #t 'z)
  @result{} (a b c d z z) @r{and} ()
@end example
@end defun

@defun slices list k :optional fill? padding
Splits @var{list} into the sublists (slices) where the length of
each slice is @var{k}.
If the length of @var{list} is not a multiple of @var{k},
the last slice is dealt in the same way as @code{take*}; that is,
it is shorter than @var{k} by default, or added @var{padding} if
@var{fill?} is true.

@example
(slices '(a b c d e f g) 3)
  @result{} ((a b c) (d e f) (g))
(slices '(a b c d e f g) 3 #t 'z)
  @result{} ((a b c) (d e f) (g z z))
@end example
@end defun

@defun intersperse item list
Inserts @var{item} between elements in the @var{list}.
(The order of arguments is taken from Haskell's intersperse).

@example
(intersperse '+ '(1 2 3))  @result{} (1 + 2 + 3)
(intersperse '+ '(1))      @result{} (1)
(intersperse '+ '())       @result{} ()
@end example
@end defun

@node Walking over lists, Other list procedures, List accessors and modifiers, Pairs and lists
@subsection Walking over lists
@c NODE リストをたどる手続き

@defun map proc list1 list2 @dots{}
[R7RS+]
Applies @var{proc} for each element(s) of given list(s),
and returns a list of the results.  R7RS doesn't specify
the application order of @code{map}, but Gauche guarantees
@var{proc} is always applied in order of the list(s).
Gauche's @code{map} also terminates as soon as one of
the list is exhausted.

@example
(map car '((a b) (c d) (e f))) @result{} (a c e)

(map cons '(a b c) '(d e f))
  @result{} ((a . d) (b . e) (c . f))
@end example

Note that the @code{gauche.collection} module (@pxref{Collection framework})
extends @code{map} to work on any type of collection.
@end defun

@defun append-map f clist1 clist2 @dots{}
@defunx append-map! f clist1 clist2 @dots{}
[R7RS list]
Functionally equivalent to the followings, though a bit more efficient:

@example
  (apply append (map @var{f} @var{clist1} @var{clist2} @dots{}))
  (apply append! (map @var{f} @var{clist1} @var{clist2} @dots{}))
@end example
At least one of the list arguments must be finite.
@end defun


@defun map* proc tail-proc list1 list2 @dots{}
Like @code{map}, except that @var{tail-proc} is applied to the @code{cdr}
of the last pair in the argument(s) to get the @code{cdr} of
the last pair of the result list.  This procedure allows improper
list to appear in the arguments.   If a single list is given,
@var{tail-proc} always receives a non-pair object.

@example
(map* - / '(1 2 3 . 4)) @result{} (-1 -2 -3 . 1/4)

(define (proper lis)
  (map* values
        (lambda (p) (if (null? p) '() (list p)))
        lis))

(proper '(1 2 3))     @result{} (1 2 3)
(proper '(1 2 3 . 4)) @result{} (1 2 3 4)
@end example

If more than one list are given, the shortest one determines
how @var{tail-proc} is called.  When @code{map*} reaches the
last pair of the shortest list, @var{tail-proc} is called with
cdrs of the current pairs.

@example
(map* + vector '(1 2 3 4) '(1 2 . 3))
  @result{} (2 4 . #((3 4) 3))
@end example

Note: The name @code{map*} is along the line of
@code{list*}/@code{cons*} that can produce improper list
(@xref{List constructors}, @pxref{R7RS lists}).
@end defun

@defun for-each proc list1 list2 @dots{}
[R7RS base]
Applies @var{proc} for each element(s) of given list(s) in order.
The results of @var{proc} are discarded.  The return value of
@code{for-each} is undefined.  When more than one list is given,
@code{for-each} terminates as soon as one of the list is exhausted.

Note that the @code{gauche.collection} module (@pxref{Collection framework})
extends @code{for-each} to work on any type of collection.
@end defun

@defun fold kons knil clist1 clist2 @dots{}
[R7RS list]
The fundamental list iterator.
When it is given a single list
@var{clist1} = (@var{e1} @var{e2} @dots{} @var{en}),
then this procedure returns
@example
(@var{kons} @var{en} @dots{} (@var{kons} @var{e2} (@var{kons} @var{e1} @var{knil})) @dots{} )
@end example

If @var{n} list arguments are provided, then the @var{kons}
function must take @var{n}+1 parameters: one element from each list, and
the "seed" or fold state, which is initially @var{knil}.
The fold operation terminates when the shortest list runs out of values.
At least one of the list arguments must be finite.

Examples:
@example
(fold + 0 '(3 1 4 1 5 9)) @result{} 23 ;@r{sum up the elements}
(fold cons '() '(a b c d e)) @result{} (e d c b a) ;@r{reverse}
(fold cons* '() '(a b c) '(1 2 3 4 5))
    @result{} (c 3 b 2 a 1) ;@r{n-ary case}
@end example
@end defun

@defun fold-right kons knil clist1 clist2 @dots{}
[R7RS list]
The fundamental list recursion operator.
When it is given a single list
@var{clist1} = (@var{e1} @var{e2} @dots{} @var{en}),
then this procedure returns
@example
(@var{kons} @var{e1} (@var{kons} @var{e2} @dots{} (@var{kons} @var{en} @var{knil})))
@end example

If @var{n} list arguments are provided, then the @var{kons} function
must take @var{n}+1 parameters: one element from each list, and
the "seed" or fold state, which is initially @var{knil}.
The fold operation terminates when the shortest list runs out of values.
At least one of the list arguments must be finite.

Examples:
@example
(fold-right cons '() '(a b c d e))
   @result{} (a b c d e) ;@r{copy list}
(fold-right cons* '() '(a b c) '(1 2 3 4 5))
   @result{} (a 1 b 2 c 3) ;@r{n-ary case}
@end example
@end defun

@defun fold-left snok knil clist1 clist2 @dots{}
[R6RS]
This is another variation of left-associative folding.
When it is given a single list
@var{clist1} = (@var{e1} @var{e2} @dots{} @var{en}),
then this procedure returns:
@example
(@var{snok} (@dots{} (@var{snok} (@var{snok} @var{knil} @var{e1}) @var{e2}) @dots{}) @var{en})
@end example

Compare this with @code{fold} above; association is the same, but the order
of arguments passed to the procedure @var{snok} is reversed from the way
arguments are passed to @var{kons} in @code{fold}.   If @var{snok} is
commutative, @code{fold} and @code{fold-left} produces the same result.

@example
(fold-left + 0 '(1 2 3 4 5) @result{} 15

(fold-left cons 'z '(a b c d))
  @result{} ((((z . a) . b) . c) . d)

(fold-left (^[a b] (cons b a)) 'z '(a b c d))
  @result{} (a b c d z)
@end example

If more than one lists are given, @var{snok} is called with
the current seed value @var{knil} and each corresponding
element of the input lists
@code{clist1} @code{clist2} @dots{}.

@example
(fold-left list 'z '(a b c) '(A B C))
  @result{} (((z a A) b B) c C)
@end example

Note: Most functional languages have left- and right- associative
fold operations, which correspond to @code{fold-left} and @code{fold-right},
respectively.
(e.g. Haskell's @code{foldl} and @code{foldr}).  In Scheme, @code{SRFI-1}
first introduced @code{fold} and @code{fold-right}.  R6RS introduced
@code{fold-left}.  (However, in R6RS the behavior is undefined if the lengths of
@code{clist1} @code{clist2} @dots{} aren't the same, while in Gauche
@code{fold-left} terminates as soon as any one of the lists terminates.)
@end defun

@defun reduce f ridentity list
@defunx reduce-right f ridentity list
[R7RS list]
Variant of @code{fold} and @code{fold-right}.   @var{f} must be a
binary operator, and @var{ridentity} is the value such that for
any value @var{x} that is valid as @var{f}'s input,
@example
 (f x ridentity) @equiv{} x
@end example

These functions effectively do the same thing as @code{fold} or
@code{fold-right}, respectively, but omit the first
application of @var{f} to @var{ridentity}, using the above nature.
So @var{ridentity} is used only when @var{list} is empty.
@end defun



@defun filter pred list
@defunx filter! pred list
[R7RS list]
A procedure @var{pred} is applied on each element of @var{list},
and a list of elements that @var{pred} returned true on it is returned.
@example
(filter odd? '(3 1 4 5 9 2 6)) @result{} (3 1 5 9)
@end example
@code{filter!} is the linear-update variant.  It may destructively
modifies @var{list} to produce the result.
@end defun

@defun filter-map  f clist1 clist2 @dots{}
[R7RS list]
Like @code{map}, but only true values are saved.
At least one of the list arguments must be finite.
@example
(filter-map (lambda (x) (and (number? x) (* x x)))
            '(a 1 b 3 c 7))
  @result{} (1 9 49)
@end example
@end defun

@defun remove pred list
@defunx remove! pred list
[R7RS list]
A procedure @var{pred} is applied on each element of @var{list},
and a list of elements that @var{pred} returned false on it is returned.
@example
(remove odd? '(3 1 4 5 9 2 6)) @result{} (4 2 6)
@end example
@code{remove!} is the linear-update variant.  It may destructively
modifies @var{list} to produce the result.
@end defun

@defun find pred clist
[R7RS list]
Applies @var{pred} for each element of @var{clist}, from
left to right, and returns the first element that @var{pred} returns
true on.  If no element satisfies @var{pred}, @code{#f} is returned.
@end defun

@defun find-tail pred clist
[R7RS list]
Applies @var{pred} for each element of @var{clist}, from left to right,
and when @var{pred} returns a true value, returns the pair whose car
is the element.  If no element satisfies @var{pred}, @code{#f} is returned.
@end defun

@defun any pred clist1 clist2 @dots{}
[R7RS list]
Applies @var{pred} across each element of @var{clist}s, and
returns as soon as @var{pred} returns a non-false value.
The return value of @code{any} is the non-false value @var{pred} returned.
If @var{clist}s are exhausted before @var{pred} returns a non-false
value, @code{#f} is returned.
@end defun

@defun every pred clist1 clist2 @dots{}
[R7RS list]
Applies @var{pred} across each element of @var{clist}s, and
returns @code{#f} as soon as @var{pred} returns @code{#f}.
If all application of @var{pred} return a non-false value,
@code{every} returns the last result of the applications.
@end defun

@defun count pred clist1 clist2 @dots{}
[R7RS list]
A procedure @var{pred} is applied to the @var{n}-th element
of given lists, from @var{n} is zero to the length of the
the shortest finite list in the given lists,
and the count of times @var{pred} returned true is returned.

@example
(count even? '(3 1 4 1 5 9 2 5 6)) @result{} 3
(count < '(1 2 4 8) '(2 4 6 8 10 12 14 16)) @result{} 3
@end example

At least one of the argument lists must be finite:

@example
(count < '(3 1 4 1) (circular-list 1 10)) @result{} 2
@end example
@end defun


@defun delete x list :optional elt=
@defunx delete! x list :optional elt=
[R7RS list]
Equivalent to
@example
  (remove (lambda (y) (elt= x y)) list)
  (remove! (lambda (y) (elt= x y)) list)
@end example
The comparison procedure, @var{elt=}, defaults to @code{equal?}.
@end defun

@defun delete-duplicates list :optional elt=
@defunx delete-duplicates! list :optional elt=
[R7RS list]
Removes duplicate elements from @var{list}.
If there are multiple equal elements in @var{list},
the result list only contains the first or leftmost of these
elements in the result. The order of these surviving elements
is the same as in the original list.
The comparison procedure, @var{elt=}, defaults to @code{equal?}.
@end defun

@node Other list procedures, Association lists, Walking over lists, Pairs and lists
@subsection Other list procedures
@c NODE 他のリスト手続き

@defun append list @dots{}
[R7RS base]
Returns a list consisting of the elements of the first @var{list} followed by
the elements of the other lists.  The resulting list is always newly
allocated, except that it shares structure with the last list argument.
The last argument may actually be any object; an improper list results
if the last argument is not a proper list.
@end defun

@defun append! list @dots{}
[R7RS list]
Returns a list consisting of the elements of the first @var{list} followed by
the elements of the other lists.  The cells in the lists except the last
one may be reused to construct the result.   The last argument may be
any object.
@end defun

@defun concatenate list-of-lists
@defunx concatenate! list-of-lists!
[R7RS list]
Equivalent to @code{(apply append @var{list-of-lists})} and
@code{(apply append! @var{list-of-lists})}, respectively, but this
can be a bit efficient by skipping overhead of @code{apply}.
@end defun

@defun reverse list :optional (tail '())
@defunx reverse! list :optional (tail '())
[R7RS+]
Returns a list consisting of the elements of @var{list}
in the reverse order.
While @code{reverse} always returns
a newly allocated list, @code{reverse!} may reuse the cells
of @var{list}.  Even @var{list} is destructively modified
by @code{reverse!}, you should use its return value, for
the first cell of @var{list} may not be the first cell
of the returned list.

If an optional argument @var{tail} is given, it becomes
the tail of the returned list (@var{tail} isn't copied).
It is useful in the idiom to prepend the processed results
on top of already existing results.

@example
(reverse '(1 2 3 4 5)) @result{} (5 4 3 2 1)
(reverse '(1 2 3) '(a b)) @result{} (3 2 1 a b)
@end example

The @var{tail} argument is Gauche's extension,
and it isn't in the traditional Scheme's @code{reverse}.
The rationale is the following correspondence:

@example
(reverse xs)      @equiv{} (fold cons xs '())
(reverse xs tail) @equiv{} (fold cons xs tail)
@end example
@end defun

@defun append-reverse rev-head tail
@defunx append-reverse! rev-head tail
[R7RS list]
Equivalent to the two-argument @code{reverse} and @code{reverse!}.
Provided for srfi-1 (R7RS @code{(scheme list)}) compatibility.
@end defun


@defun memq obj list
@defunx memv obj list
@defunx member obj list :optional obj=
[R7RS base]
Searches @var{obj} in the @var{list}.  If @code{n}-th element of
@var{list} equals to @var{obj} (in the sense of @code{eq?} for @code{memq},
@code{eqv?} for @code{memv}, and @code{equal?} for @code{member}),
@code{(list-tail @var{list} @var{n})} is returned.
Otherwise, @code{#f} is returned.

If the optional @var{obj=} argument of @code{member} is given, 
it is used as a equivalence predicate
instead of @code{equal?}.
@example
(memq 'a '(a b c))          @result{} (a b c)
(memq 'b '(a b c))          @result{}  (b c)
(memq 'a '(b c d))          @result{} #f
(memq (list 'a) '(b (a) c)) @result{} #f
(memv 101 '(100 101 102))   @result{} (101 102)
@end example
@end defun

@node Association lists,  , Other list procedures, Pairs and lists
@subsection Association lists
@c NODE 連想リスト

@defun acons obj1 obj2 obj3
Returns @code{(cons (cons @var{obj1} @var{obj2}) @var{obj3})}.
Useful to put an entry at the head of an associative list.

(This procedure is defined in SRFI-1 (R7RS @code{(scheme list)}) as @code{alist-cons}; @pxref{R7RS lists}).

@lisp
(acons 'a 'b '((c . d))) @result{} ((a . b) (c . d))
@end lisp
@end defun

@defun alist-copy alist
[R7RS list]
Returns a fresh copy of @var{alist}.
The spine of @var{alist} and each cell that points a key and a value
is copied.
@example
(define a (list (cons 'a 'b) (cons 'c 'd)))
a @result{} ((a . b) (c . d))

(define b (alist-copy a))
b @result{} ((a . b) (c . d))

(set-cdr! (car a) 'z)
a @result{} ((a . z) (c . d))
b @result{} ((a . b) (c . d))
@end example
@end defun

@defun assq obj list
@defunx assv obj list
@defunx assoc obj list :optional key=
[R7RS base]
Each element in @var{list} should be a pair
(Gauche ignores non-pair element in @var{list}, but other R7RS
implementation may raise an error, so be aware of it when you're
writing a portable code).
These procedures search a pair whose car matches @var{obj}
(in the sense of @code{eq?} for @code{assq},
@code{eqv?} for @code{assv}, and @code{equal?} for @code{assoc})
from left to right, and return the leftmost matched pair if any.
If no pair matches, these return @code{#f}.

If the optional argument of @code{assoc} is given,
it is called instead of @code{equal?}
to check the equivalence of @var{obj} and each key.
@end defun

@defun alist-delete key alist :optional key=
@defunx alist-delete! key alist :optional key=
[R7RS list]
Deletes all cells in @var{alist} whose key is the same as @var{key}.
Comparison is done by a procedure @var{key=}.  The default is @code{eqv?}.

The linear-update version @code{alist-delete!} may or may not modify
@var{alist}.
@end defun

@defun rassoc key alist :optional eq-fn
@defunx rassq key alist
@defunx rassv key alist
Reverse associations---given @var{key} is matched to the @emph{cdr}
of each element in @var{alist}, instead of the @emph{car}.
Handy to realize bidirectional associative list.
@code{Rassoc} takes an optional comparison function, whose default is
@code{equal?}.  @code{Rassq} and @code{rassv} uses @code{eq?} and @code{eqv?}.
@end defun

@defun assoc-ref alist key :optional default eq-fn
@defunx assq-ref alist key :optional default
@defunx assv-ref alist key :optional default
These procedures provide the access to the assoc list
symmetric with other @code{*-ref} procedures.
(Note that the argument order is different from @code{assoc}, @code{assq}
and @code{assv} -- @code{*-ref} procedures take a container first,
and an item second.)

This captures the common pattern of alist access:
@example
(assoc-ref alist key default eq-fn)
 @equiv{}
  (cond [(assoc key alist eq-fn) => cdr]
        [else default])))
@end example

If @var{default} is omitted, @code{#f} is used.

@code{Assoc-ref} takes an optional comparison function @var{eq-fn},
whose default is @code{equal?}.  @code{Assq-ref} and @code{assv-ref}
uses @code{eq?} and @code{eqv?}, respectively.
@end defun

@defun rassoc-ref alist key :optional default eq-fn
@defunx rassq-ref alist key :optional default
@defunx rassv-ref alist key :optional default
Reverse association version of @code{assoc-ref}.
@example
(rassoc-ref alist key default eq-fn)
 @equiv{}
  (cond ((rassoc key alist eq-fn) => car)
        (else default))))
@end example
The meanings of optional arguments are the same as @code{assoc-ref}.
@end defun

@defun assoc-set! alist key val :optional eq-fn
@defunx assq-set! alist key val
@defunx assv-set! alist key val
Returns an alist who has @code{(key . val)} pair added to the @code{alist}.
If @code{alist} already has an element with @var{key}, the element's
@emph{cdr} is destructively modified for @var{val}.
If @var{alist} doesn't have an element with @var{key}, a new pair
is created and appended in front of @var{alist}; so you should use
the return value to guarantee @var{key}-@var{val} pair is added.

@code{Assoc-set!} takes optional comparison function @var{eq-fn},
whose default is @code{equal?}.  @code{Assq-set!} and @code{assv-set!}
uses @code{eq?} and @code{eqv?}, respectively.
@end defun

@defun assoc-adjoin alist key val :optional eq-fn
If @var{alist} contains an entry with @var{key}, returns a new associative list
where the value of the @var{key} is replaced for @var{val}. The order
of entries in @var{alist} is preserved.  If @var{alist} doesn't contain
the entry, it returns @code{(acons @var{key} @var{val} @var{alist})}.

The original @var{alist} is left unmodified.  The returned associative list may
share a part of its tail with the original @var{alist}, however.

The optional @var{eq-fn} argument is a procedure with two arguments
to be used to compare the keys; the default is @code{equal?}.

Note the order of arguments; we have @var{alist} first, just as @code{assoc-ref}
and @code{assoc-set!}, and other @code{-adjoin} procedures.
It is not the same as @code{alist-delete} and @code{assoc}, which takes
the key first.
@end defun

@defun assoc-update-in alist keys proc :optional default eq-fn
This procedure allows to update a nested associative list.
The @var{alist} argument is a (possibly nested) associative list,
@var{keys} are a list of keys, and @var{proc} is a procedure
that takes one argument.  First, the keys are looked up
recursively in @var{alist}; then its value is passed to @var{proc}.
The return value is a new (nested) associative list where the value
pointed by @var{keys} is replaced with the return value of @var{proc}.

@example
(assoc-update-in '((a (b . 1) (c . 2))) '(a c) (cut + <> 1))
  @result{} ((a (b . 1) (c . 3))
@end example

The order of entries are preserved.  The original @var{alist}
is left unmodified, but the returned value may share a part of
the structure with @var{alist}.

If @var{alist} doesn't have the entry specified by @var{keys},
a new entry is added.  A new entry is added at the beginning of
the sequence where specified key didn't exist.

@example
(assoc-update-in '((a (b . 1) (c . 2))) '(a d e) (^_ 99))
  @result{} ((a (d (e . 99)) (b . 1) (c . 3)))
@end example

The @var{default} argument is passed to @var{proc} when there's
no entry with specified keys.  If omitted, @code{#f} is assumed.

The optional @var{eq-fn} argument is a procedure with two arguments
to be used to compare the keys; the default is @code{equal?}.

Note the order of arguments; we have @var{alist} first, just as @code{assoc-ref}
and @code{assoc-set!}, and other @code{-adjoin} procedures.
It is not the same as @code{alist-delete} and @code{assoc}, which takes
the key first.

Note: For destructively updating general nested aggregate structures,
setter of @code{~} is handy (@pxref{Universal accessor}).  You can modify
an entry in a hashtable in a vector in a list, for example.  Associative
list is a bit special, since you can't distinguish it from lists
(thus @code{~} can't be used), and it is mostly used in functional way.
So we added a special update procedure.
@end defun


@c ----------------------------------------------------------------------
@node Symbols, Keywords, Pairs and lists, Core library
@section Symbols
@c NODE シンボル

@deftp {Builtin Class} <symbol>
@clindex symbol
A class for symbols.
@end  deftp

@deftp {Reader Syntax} @code{|@i{name}|}
@lxindex |
[R7RS]
Denotes a symbol that has weird name, including the characters
that are not usually allowed in symbols.  It can also include
hex-escaped characters.

@example
;; @r{A symbol with spaces in its name}
'|this is a symbol| @result{} |this is a symbol|

;; @r{Unicode codepoint can be used following backslash-x escape,}
;; @r{and terminated by semicolon.}
'|\x3bb;| @result{} λ
@end example

If the interpreter is running in case-insensitive mode, this syntax
can be used to include uppercase characters in a symbol
(@pxref{Case-sensitivity}).
@end deftp

@deftp {Reader Syntax} @code{#:@i{name}}
Denotes @emph{uninterned} symbol.  Uninterned symbols can be created
by @code{gensym} or @code{string->uninterned-symbol}.

Uninterned symbols are mainly for legacy macros to avoid
variable conflicts.   They are not registered in the internal
dictionary, so such symbols with the same name can't be @code{eq?}.

@example
(eq? '#:foo '#:foo) @result{} #f
(eq? '#:foo 'foo) @result{} #f
@end example

When an S-expression including uninterned symbols are printed,
the srfi-38 syntax is used to indicate which uninterned symbol
is the same (@code{eq?}) to which.

@example
(let1 s '#:foo (list s s))
  @result{} @r{prints} (#0=#:foo #0#)

(let ((s '#:foo) (t '#:foo)) (list s t s t))
  @result{} @r{prints} (#0=#:foo #1=#:foo #0# #1#)
@end example
@end deftp


@defun symbol? obj
[R7RS base]
Returns true if and only if @var{obj} is a symbol.
@example
(symbol? 'abc)     @result{} #t
(symbol? 0)        @result{} #f
(symbol? 'i)       @result{} #t
(symbol? '-i)      @result{} #f
(symbol? '|-i|)    @result{} #t
@end example
@end defun

@defun symbol-interned? symbol
Returns @code{#t} if @var{symbol} is an interned symbol,
@code{#f} if it is an uninterned symbol.   An error is signaled
if @var{symbol} is not a symbol.
@end defun

@defun symbol=? a b c @dots{}
[R7RS base]
Every argument must be a symbol.  Returns @code{#t} iff
every pair of arguments are @code{eq?} to each other.
@end defun

@defun symbol->string symbol
[R7RS base]
Returns the name of @var{symbol} in a string.  Returned
string is immutable.

@example
(symbol->string 'foo) @result{} foo
@end example
@end defun

@defun string->symbol string
[R7RS base]
Returns a symbol whose name is a string @var{string}.
@var{String} may contain weird characters.

@example
(string->symbol "a") @result{} a
(string->symbol "A") @result{} A
(string->symbol "weird symbol name") @result{} |weird symbol name|
@end example
@end defun

@defun string->uninterned-symbol string
Like @code{string->symbol}, but the created symbol is uninterned.

@example
(string->uninterned-symbol "a") @result{} #:a
@end example
@end defun


@defun gensym :optional prefix
Returns a fresh, uninterned symbol.  The returned symbol can never
be @code{eq?} to other symbol within the process.
If @var{prefix} is given, which must be a string, it is used
as a prefix of the name of the generated symbol.  It is mainly for
the convenience of debugging.
@end defun

@defun symbol-sans-prefix symbol prefix
Both @var{symbol} and @var{prefix} must be symbols.
If the name of @var{prefix} matches the beginning part of the
name of @var{symbol}, this procedure returns a symbol whose
name is the name of @var{symbol} without the matched prefix.
Otherwise, it returns @code{#f}.

@example
(symbol-sans-prefix 'foo:bar 'foo:) @result{} bar
(symbol-sans-prefix 'foo:bar 'baz:) @result{} #f
@end example
@end defun

@defun symbol-append interned? objs @dots{}
@defunx symbol-append objs @dots{}
Returns a symbol with the name which is a concatenation of
string representation of @var{objs}.

If the first argument is a boolean, it is recognized as the
first form; the first argument specifies whether the resulting
symbol is interned or not.

Each other argument is converted to a string as follows:
If it is a keyword, its name (with the preceding @code{:}) is used.
For all other objects, @code{x->string} is used.  (The special treatment
of keyword is to keep the consistency before and after
keyword-symbol integration.  @xref{Keyword and symbol integration}, for
the details.)

This is upper-compatible to Bigloo's same name procedure, which
only allows symbols as the arguments and the result is always interned.

@example
(symbol-append 'ab 'cd) @result{} abcd
(symbol-append 'ab ':c 30) @result{} ab:c30
(symbol-append #f 'g 100) @result{} #:g100
@end example
@end defun


@c ----------------------------------------------------------------------
@node Keywords, Characters, Symbols, Core library
@section Keywords
@c NODE キーワード

@deftp {Builtin Class} <keyword>
@clindex keyword
Keywords are a subtype of symbols that are automatically bound
to itself.
It is extensively used in named arguments (keyword arguments),
and keyword-value list.

See @ref{Making procedures} for how Gauche supports keyword
arguments, and @code{let-keywords} macro (@ref{Optional argument parsing})
for parsing keyword-value list manually.

Keywords used to be a disjoint type from symbols.
Since it isn't conformant to R7RS, in which symbols can begin
with @code{:}, we've introduced two modes since 0.9.5; keywords
can be a disjoint type of its own, or it can be a subtype of symbols.

The behavior can be switched by environment variables.  If the environment
variable @code{GAUCHE_KEYWORD_DISJOINT} is defined when @code{gosh} starts
up, keywords and symbols are disjoint.  Otherwise, if the environment
variable @code{GAUCHE_KEYWORD_IS_SYMBOL} is defined, keywords are
a subtype of symbols.

The default behavior when neither environment variables are defined
has been switched since 0.9.8.  @code{GAUCHE_KEYWORD_DISJOINT} was assumed
in 0.9.7 and before, while @code{GAUCHE_KEYWORD_IS_SYMBOL} is assumed
in 0.9.8 and after.

Most typical code run in either mode, but there can be some code
that behaves differently.  @xref{Keyword and symbol integration},
for effect of the change.

In future we'll stop supporting @code{GAUCHE_KEYWORD_DISJOINT},
so we recommend you to ensure applications to run on the current
default mode.
@end  deftp

@deftp {Reader Syntax} @code{:@var{name}}
Read to a keyword whose name is @var{:name}.
@end deftp

@defun keyword? obj
Returns @code{#t} if @var{obj} is a keyword.
@end defun

@defun make-keyword name
Returns a keyword whose name is @var{name} prepended by @code{:}.
The @var{name} argument can be a string or a symbol.
@example
(make-keyword "foo")  @result{} :foo

(make-keyword 'foo)   @result{} :foo
@end example
@end defun

@defun keyword->string keyword
Returns the name (without the initial @code{:}) of the keyword @var{keyword}, in a string.
@example
(keyword->string :foo) @result{} "foo"
@end example
@end defun

@defun get-keyword key kv-list :optional fallback
A useful procedure to extract a value from key-value list.
A key-value list @var{kv-list} must contains even number of elements;
the first, third, fifth @dots{} elements are regarded as keys,
and the second, fourth, sixth @dots{} elements are the values of
the preceding keys.

This procedure looks for @var{key} from the keys, and if it finds one,
it returns the corresponding value.
If there are more than one matching keys, the leftmost one is taken.
If there is no matching key, it returns @var{fallback} if provided,
or signals an error otherwise.

It is an error if @var{kv-list} is not a proper, even-number element list.

Actually, `keywords' in the keyword-value list and the @var{key} argument
need not be a keyword---it can be any Scheme object.  Key comparison
is done by @code{eq?}.

This procedure is taken from STk.

@example
(get-keyword :y '(:x 1 :y 2 :z 3))
  @result{} 2
(get-keyword 'z '(x 1 y 2 z 3))
  @result{} 3

(get-keyword :t '(:x 1 :y 2 :z 3))
  @result{} #<error>
(get-keyword :t '(:x 1 :y 2 :z 3) #f)
  @result{} #f
@end example
@end defun

@defmac get-keyword* key kv-list :optional fallback
Like @code{get-keyword}, but @var{fallback} is evaluated only
if @var{kv-list} does not have @var{key}.
@end defmac

@defun delete-keyword key kv-list
@defunx delete-keyword! key kv-list
Removes all the keys and values from @var{kv-list} for
keys that are @code{eq?} to @var{key}.

@code{delete-keyword} doesn't change @var{kv-list}, but the returned
list may share the common tail of it.

@code{delete-keyword!} doesn't allocate, and @emph{may} destructively
changes @var{kv-list}.  You still have to use the returned value,
for the original list may not be changed if its first key matches
@var{key}.

If there's no key that matches @var{key}, @var{kv-list} is returned.

@example
(delete-keyword :y '(:x 1 :y 2 :z 3 :y 4))
 @result{} (:x 1 :z 3)
@end example

@end defun

@defun delete-keywords keys kv-list
@defunx delete-keywords! keys kv-list
Similar to @code{delete-keyword} and @code{delete-keyword!}, but
you can specify a list of objects in @var{keys};
when a key in @var{kv-list} matches any of @var{keys},
the key and the following value is removed from @var{kv-list}.

@example
(delete-keywords '(:x :y) '(:x 1 :y 2 :z 3 :y 4))
 @result{} (:z 3)
@end example

@end defun

@menu
* Keyword and symbol integration::
@end menu

@node Keyword and symbol integration,  , Keywords, Keywords
@subsection Keyword and symbol integration
@c NODE キーワードとシンボルの統合

In older versions of Gauche, keywords are of disjoint type
from symbols, and they are self-evaluating objects.
To maintain the compatibility, the current Gauche makes
symbols that begins with @code{:} automatically bound to itself.

On the surface it won't make much difference;
you can write a keyword @code{:key}, which evaluates to itself; so you
can pass and receive keyword arguments just as they used to be.
If you use @code{:key} as variables, however, e.g. @code{(define :key 3)},
the value of @code{:key} in your module changes
(it won't affect other modules, which refer to the binding of @code{:key}
in @code{gauche.keyword} module).

However, there are several subtle points that do make difference, that
breaks compatibility of legacy code.
We explain here how to change the code that works in both ways.

If you find a problem in new mode and want to get the old behavior
until you change the code, you can set the environment variable
@code{GAUCHE_KEYWORD_DISJOINT.}

@subsubheading @code{(symbol? :key)} used to return @code{#f}, now returns @code{#t}

@code{keyword?} always returns @code{#t} on keywords, but
if you need to switch behavior depending whether an object is a symbol
or a keyword, you should test keyword-ness first.

@example
;; behaved differently in 0.9.7 and before
(cond
  [(symbol? x) (x-is-symbol)]
  [(keyword? x) (x-is-keyword)])

;; works on all versions
(cond
  [(keyword? x) (x-is-keyword)]
  [(symbol? x) (x-is-symbol)])
@end example

@subsubheading Literal keywords in pattern matching

In the old versions,
when keywords appear in a pattern of @code{util.match}
or @code{syntax-rules}, they only matched to themselves.
In the current version, such keywords in
a pattern are treated as pattern variables, since they are symbols.

@example
;; In the old versions
(match '(a b) [(:key z) (list :key z)] [_ "nope"])
   @result{} "nope"

;; In the current version
;; :key is treated just as a pattern variable
(match '(a b) [(:key z) (list :key z)] [_ "nope"])
   @result{} (a b)
@end example

The same thing happens to the patterns in @code{syntax-rules}.

To make the code work in both versions, explicitly mark the keywords
as literals.  

@itemize @bullet
@item
For @code{match}, quote the keywords you want to be treated as literals.
@example
(match '(a b) [(':key z) (list :key z)] [_ "nope"])
   @result{} "nope"
@end example

@item
For @code{syntax-rules}, list the keywords as literals.
@example
(syntax-rules (:key)
  [(_ :key z) (list :key z)])  ;etc.
@end example
@end itemize

As of Gauche 0.9.5, @code{match} warns if you have unquoted
keywords in match patterns.

@subsubheading Displaying keywords

@code{(display :key)} used to print @code{key} (no colon), while it now
prints @code{:key}.

You can use @code{(display (keyword->string :key))} which prints @code{key}
in both versions.

@subsubheading For R7RS code, quote them or import Gauche modules

Keywords (symbols beginning with @code{:}) are automatically bound to itself
in the @code{gauche.keyword} module.

Gauche code inherits the @code{gauche} module by default, which inherits
@code{keyword}, so you can see the binding of the keyword by default.

In R7RS code, however, you don't inherit @code{gauche},
so symbols beginning with @code{:} are just ordinary symbols by default.
Usually you do @code{(import (gauche base))} to use Gauche built-ins,
and that makes binding of @code{gauche.keyword} available in your
code, too (since @code{gauche.base} inherits @code{gauche.keyword}).
But keep this in mind just in case you want to handle keywords in
your R7RS code separate from Gauche procedures---you have to either say
@code{(import (gauche keyword))} to get just the self-bound keywords,
or quote them.

@example
(import (scheme base))

:foo @result{} @r{ERROR: unbound variable: :foo}

(import (gauche base))

:foo @result{} :foo
@end example

In the following example, the R7RS library @code{foo} imports only
@code{copy-port} from @code{(gauche base)}; in that case,
you have to import @code{(gauche keyword)} separately
in order to use @code{:size} keyword without quoting.
(Or add @code{:size} explicitly in the imported symbol
list of @code{(gauche base)}.)

@example
(define-library (foo)
  (import (scheme base)
          (only (gauche base) copy-port)
          (gauche keyword))
  (export cat)        

  (begin
    (define (cat)
      (copy-port (current-input-port)
                 (current-output-port)
                 :size 4096))))
@end example


@c ----------------------------------------------------------------------
@node Characters, Character sets, Keywords, Core library
@section Characters
@c NODE 文字

@deftp {Builtin Class} <char>
@clindex char
@end  deftp

@deftp {Reader Syntax} @code{#\@i{charname}}
@lxindex #\
[R7RS+]
Denotes a literal character.

When the reader reads @code{#\}, it fetches a subsequent character.
If it is one of @code{()[]@{@}" \|;#}, this is a character literal of itself.
Otherwise, the reader reads subsequent characters until it sees
a non word-constituent character.  If only one character is read,
it is the character.  Otherwise, the reader matches the read characters
with predefined character names.  If it doesn't match any, an error
is signaled.

The following character names are recognized.
These character names are case insensitive.
@table @code
@item space
Whitespace (ASCII #x20)
@item newline, nl, lf
Newline (ASCII #x0a)
@item return, cr
Carriage return (ASCII #x0d)
@item tab, ht
Horizontal tab (ASCII #x09)
@item page
Form feed (ASCII #x0c)
@item alarm
Bell (ASCII #x07)
@item backspace
Backspace (ASCII #x08)
@item escape, esc
Escape (ASCII #x1b)
@item delete, del
Delete (ASCII #x7f)
@item null
NUL character (ASCII #x00)
@item x@var{N}
A character whose Unicode codepoint is the integer @var{N},
when @var{N} is a hexadecimal integer.
This is R7RS lexical syntax. (See the compatibility note below).
@item u@var{N}
A character whose Unicode codepoint is the integer @var{N},
where @var{N} is 4-digit or 8-digit hexadecimal number.

This is legacy Gauche lexical syntax.  Use @code{\xN} syntax for
the new code. (See the compatibility note below).
@end table

@example
#\newline @result{} #\newline ; @r{newline character}
#\x0a     @result{} #\newline ; @r{ditto}
#\x41     @result{} #\A       ; @r{ASCII letter 'A'}
#\x3042   @result{} ; @r{Hiragana letter A}
#\x2a6b2  @result{} ; @r{JISX0213 Kanji 2-94-86}
@end example
@end deftp

@b{Compatibility note}:
Before 0.9.4, @code{\xNN} syntax uses Gauche's internal
character encoding as opposed to Unicode codepoint.  Both are
the same if Gauche is compiled with internal encoding @code{utf-8}
or @code{none} (if it's @code{none}, only characters up to U+00ff
is supported and in this range the characters are the same as 
Unicode characters.)   If Gauche is compiled with encoding
@code{euc-jp} or @code{sjis}, the meaning of @code{\xNN} beyond 
ASCII range differs from 0.9.3.3 or before.

If you set the reader mode to @code{legacy} (@pxref{Reader lexical mode}),
@code{#\xNN} is read as before, keeping the compatibility
(but it isn't compatible to R7RS).  Alternatively,
you can use @code{#\uNNNN}, or a character itself, to
make the code work in both new and old versions of Gauche.

@defun char? obj
[R7RS base]
Returns @code{#t} if @var{obj} is a character, @code{#f} otherwise.
@end defun

@defun char=? char1 char2 char3 @dots{}
@defunx char<? char1 char2 char3 @dots{}
@defunx char<=? char1 char2 char3 @dots{}
@defunx char>? char1 char2 char3 @dots{}
@defunx char>=? char1 char2 char3 @dots{}
[R7RS base]
Compares characters.  Character comparison is done in internal
character encoding.
@end defun

@defun char-ci=? char1 char2 char3 @dots{}
@defunx char-ci<? char1 char2 char3 @dots{}
@defunx char-ci<=? char1 char2 char3 @dots{}
@defunx char-ci>? char1 char2 char3 @dots{}
@defunx char-ci>=? char1 char2 char3 @dots{}
[R7RS char]
Compares characters in case-insensitive way.
The comparison is done in the internal character code
of the foldcase of the each character; see @code{char-foldcase} below.

In R7RS, these procedures are in the @code{(scheme char)} library.
@end defun

@defun char-alphabetic? char
@defunx char-numeric? char
@defunx char-whitespace? char
@defunx char-upper-case? char
@defunx char-lower-case? char
[R7RS char]
Returns true if a character @var{char} is an alphabetic character
(Unicode character category @code{Lu}, @code{Ll}, @code{Lt},
@code{Lm}, @code{Lo}, @code{Nl}),
a numeric character
(Unicode character category @code{Nd}),
a whitespace character,
(Unicode character category @code{Zs}, @code{Zp}, @code{Zl}),
an upper case character
(Unicode character category @code{Lu}),
or a lower case character
(Unicode character category @code{Ll}), respectively.

In R7RS, these procedures are in the @code{(scheme char)} library.
@end defun

@defun char-general-category char
[R6RS]
Returns one of the following symbols, representing the Unicode general category of @var{char}.

@multitable {aaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
@item @code{Cc} @tab Other, Control
@item @code{Cf} @tab Other, Format
@item @code{Cn} @tab Other, Not Assigned
@item @code{Co} @tab Other, Private Use
@item @code{Cs} @tab Other, Surrogate
@item @code{Ll} @tab Letter, Lowercase
@item @code{Lm} @tab Letter, Modifier
@item @code{Lo} @tab Letter, Other
@item @code{Lt} @tab Letter, Titlecase
@item @code{Lu} @tab Letter, Uppercase
@item @code{Mc} @tab Mark, Spacing Combining
@item @code{Me} @tab Mark, Enclosing
@item @code{Mn} @tab Mark, Nonspacing
@item @code{Nd} @tab Number, Decimal Digit
@item @code{Nl} @tab Number, Letter
@item @code{No} @tab Number, Other
@item @code{Pc} @tab Punctuation, Connector
@item @code{Pd} @tab Punctuation, Dash
@item @code{Pe} @tab Punctuation, Close
@item @code{Pf} @tab Punctuation, Final quote
@item @code{Pi} @tab Punctuation, Initial quote
@item @code{Po} @tab Punctuation, Other
@item @code{Ps} @tab Punctuation, Open
@item @code{Sc} @tab Symbol, Currency
@item @code{Sk} @tab Symbol, Modifier
@item @code{Sm} @tab Symbol, Math
@item @code{So} @tab Symbol, Other
@item @code{Zl} @tab Separator, Line
@item @code{Zp} @tab Separator, Paragraph
@item @code{Zs} @tab Separator, Space
@end multitable

If Gauche is compiled with euc-jp or shift_jis encoding,
there are characters that don't have corresponding Unicode codepoint
(each of them are represented by one unicode character plus one
unicode modifier character).  A provisional category is assigned
to those characters.  If future versions of Unicode incorporates
these characters, the category may be reassigned.

@multitable {aaaa} {aaaa} {aaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa} 
@item SJIS @tab EUC @tab Cat  @tab Unicode
@item @code{82F5} @tab @code{A4F7} @tab @code{Lo} @tab @code{U+304B U+309A} (Semi-voiced Hiragana KA)
@item @code{82F6} @tab @code{A4F8} @tab @code{Lo} @tab @code{U+304D U+309A} (Semi-voiced Hiragana KI)
@item @code{82F7} @tab @code{A4F9} @tab @code{Lo} @tab @code{U+304F U+309A} (Semi-voiced Hiragana KU)
@item @code{82F8} @tab @code{A4FA} @tab @code{Lo} @tab @code{U+3051 U+309A} (Semi-voiced Hiragana KE)
@item @code{82F9} @tab @code{A4FB} @tab @code{Lo} @tab @code{U+3053 U+309A} (Semi-voiced Hiragana KO)
@item @code{8397} @tab @code{A5F7} @tab @code{Lo} @tab @code{U+30AB U+309A} (Semi-voiced Katakana KA)
@item @code{8398} @tab @code{A5F8} @tab @code{Lo} @tab @code{U+30AD U+309A} (Semi-voiced Katakana KI)
@item @code{8399} @tab @code{A5F9} @tab @code{Lo} @tab @code{U+30AF U+309A} (Semi-voiced Katakana KU)
@item @code{839A} @tab @code{A5FA} @tab @code{Lo} @tab @code{U+30B1 U+309A} (Semi-voiced Katakana KE)
@item @code{839B} @tab @code{A5FB} @tab @code{Lo} @tab @code{U+30B3 U+309A} (Semi-voiced Katakana KO)
@item @code{839C} @tab @code{A5FC} @tab @code{Lo} @tab @code{U+30BB U+309A} (Semi-voiced Katakana SE)
@item @code{839D} @tab @code{A5FD} @tab @code{Lo} @tab @code{U+30C4 U+309A} (Semi-voiced Katakana TSU)
@item @code{839E} @tab @code{A5FE} @tab @code{Lo} @tab @code{U+30C8 U+309A} (Semi-voiced Katakana TO)
@item @code{83F6} @tab @code{A6F8} @tab @code{Lo} @tab @code{U+31F7 U+309A} (Semi-voiced small Katakana FU)
@item @code{8663} @tab @code{ABC4} @tab @code{Ll} @tab @code{U+00E6 U+0300} (Accented latin small ae)
@item @code{8667} @tab @code{ABC8} @tab @code{Ll} @tab @code{U+0254 U+0300} (Accented latin small open o)
@item @code{8668} @tab @code{ABC9} @tab @code{Ll} @tab @code{U+0254 U+0301} (Accented latin small open o)
@item @code{8669} @tab @code{ABCA} @tab @code{Ll} @tab @code{U+028C U+0300} (Accented latin small turned v)
@item @code{866A} @tab @code{ABCB} @tab @code{Ll} @tab @code{U+028C U+0301} (Accented latin small turned v)
@item @code{866B} @tab @code{ABCC} @tab @code{Ll} @tab @code{U+0259 U+0300} (Accented latin small schwa)
@item @code{866C} @tab @code{ABCD} @tab @code{Ll} @tab @code{U+0259 U+0301} (Accented latin small schwa)
@item @code{866D} @tab @code{ABCE} @tab @code{Ll} @tab @code{U+025A U+0300} (Accented latin small schwa w/hook)
@item @code{866E} @tab @code{ABCF} @tab @code{Ll} @tab @code{U+025A U+0301} (Accented latin small schwa w/hook)
@item @code{8685} @tab @code{ABE5} @tab @code{Sk} @tab @code{U+02E9 U+02E5}
@item @code{8686} @tab @code{ABE6} @tab @code{Sk} @tab @code{U+02E5 U+02E9}
@end multitable
@end defun

@defun char->integer char
@defunx integer->char n
[R7RS base]
@code{char->integer} returns an exact integer that represents
internal encoding of the character @var{char}.
@code{integer->char} returns a character whose internal encoding
is an exact integer @var{n}.  The following expression is always
true for valid character @var{char}:
@example
(eq? char (integer->char (char->integer char)))
@end example

Note: R7RS defines these procedures to deal with Unicode
codepoints.  Gauche complies it when compiled with @code{utf-8}
or @code{none} internal encoding (for the latter, only characters
up to U+00ff are supported).  If Gauche is compiled with
@code{euc-jp} or @code{sjis} internal encoding, you need to use
@code{char->ucs}/@code{ucs->char} below to convert between Unicode
codepoints and characters.

The result is undefined if you pass @var{n} to @code{integer->char}
that doesn't have a corresponding character.
@end defun

@defun char->ucs char
@defunx ucs->char n
Converts a character @var{char} to integer UCS codepoint,
and integer UCS codepoint @var{n} to a character, respectively.

If Gauche is compiled with UTF-8 encoding, these procedures are the
same as @code{char->integer} and @code{integer->char}.

When Gauche's internal encoding differs from UTF-8, these procedures
implicitly loads @code{gauche.charconv} module to convert internal
character code to UCS or vice versa (@pxref{Character code conversion}).
If @var{char} doesn't have corresponding UCS codepoint,
@code{char->ucs} returns @code{#f}.  If UCS codepoint @var{n} can't
be represented in the internal character encoding, @code{ucs->char}
returns @code{#f}, unless the conversion routine provides a substitution
character.
@end defun

@defun char-upcase char
@defunx char-downcase char
@defunx char-titlecase char
@defunx char-foldcase char
[R7RS char]
Returns the upper case, lower case, title case and folded case of
@var{char}, respectively.

The mapping is done according to Unicode-defined character-by-character
case mapping whenever possible.  If the native encoding doesn't support
the mapped character defined in Unicode, the operation becomes no-op.
If the native encoding is 'none', we treat the characters as if they
are Latin-1 (ISO-8859-1) characters.  So, upcasing Latin-1 character
small y with diaresis (U+00ff) maps to capital y with diaeresis
(U+0178) if the internal encoding is utf-8, but it is no-op if
the internal encoding is none.

R7RS doesn't have @code{char-titlecase}; other three procedures are
defined in the @code{(scheme char)} library.  R6RS defines all of them.

The character-by-character case mapping doesn't consider a character
that may map to more than one characters; a notable example is
eszett (latin small letter sharp S, U+00df), which is
is mapped to two capital S's in string context,
but @code{char-upcase #\ß} returns #\ß.  To get a full mapping,
use @code{string-upcase} etc. in @code{gauche.unicode} module
(@pxref{Full string case conversion}).
@end defun

@defun digit->integer char :optional (radix 10) (extended-range? #f)
If given character @var{char} is a valid digit character in radix
@var{radix} number, the corresponding integer is returned.  Otherwise
@code{#f} is returned.
@example
(digit->integer #\4) @result{} 4
(digit->integer #\e 16) @result{} 14
(digit->integer #\9 8) @result{} #f
@end example

If the optional @var{extended-range?} argument is true,
this procedure recognizes not only ASCII digits, but also
all characters with @code{Nd} general category---such as
FULLWIDTH DIGIT ZERO to NINE (U+ff10 - U+ff19).

R7RS has @code{digit-value}, which is equivalent to
@code{(digit->integer char 10 #t)}.

Note: CommonLisp has a similar function in rather confusing name,
@code{digit-char-p}.
@end defun

@defun integer->digit integer :optional (radix 10) (basechar1 #\0) (basechar2 #\a)
Reverse operation of @code{digit->integer}.  Returns a character that
represents the number @var{integer} in the radix @var{radix} system.
If @var{integer} is out of the valid range, @code{#f} is returned.
@example
(integer->digit 13 16) @result{} #\d
(integer->digit 10) @result{} #f
@end example

The optional @var{basechar1} argument specifies the character
that stands for zero; by default, it's @code{#\0}.  You can give
alternative character, for example, U+0660 (ARABIC-INDIC DIGIT ZERO)
to convert an integer to a arabic-indic digit character.

Another optional @var{basechar2} argument is used for integers over 10.
The default value is @code{#\a}.  You can pass @code{#\A} to get
upper-case hex digits, for example.

Note: CommonLisp's @code{digit-char}.
@end defun

@defun gauche-character-encoding
Returns a symbol designates the native character encoding, selected
at the compile time.
The possible return values are those:
@table @code
@item euc-jp
EUC-JP
@item utf-8
UTF-8
@item sjis
Shift JIS
@item none
No multibyte character support (8-bit fixed-length character).
@end table

To switch code at compile time according to the internal encoding,
you can use feature identifiers @code{gauche.ces.*}--see
@ref{Platform-dependent features}.
@end defun

@defun supported-character-encodings
Returns a list of string names of character encoding schemes
that are supported in the native multibyte encoding scheme.
@end defun



@c ----------------------------------------------------------------------
@node Character sets, Strings, Characters, Core library
@section Character Sets
@c NODE 文字集合

@deftp {Builtin Class} <char-set>
@clindex char-set
Character set class.  Character set object represents a set of characters.
Gauche provides built-in support of character set creation and
a predicate that tests whether a character is in the set or not.

The class implements the collection protocol (@pxref{Collection framework}),
so that the standard collection methods provided in the 
@code{gauche.collection} module can be used.

An instance of @code{<char-set>} is applicable to a character,
and works as a membership predicate; see @code{char-set-contains?} below.

Further operations, such as set algebra, is defined in SRFI-14
module (@pxref{R7RS character sets}).
@end deftp

@menu
* Character set literals::
* Predefined character sets::
* Character set operations::
@end menu

@node Character set literals, Predefined character sets, Character sets, Character sets
@subsection Character set literals
@c NODE 文字集合リテラル

@deftp {Reader Syntax} @code{#[@i{char-set-spec}]}
@lxindex #[
You can write a literal character set in this syntax.
@i{char-set-spec} is a sequence of characters to be included
in the set.  You can include the following special sequences:
@table @code
@item @var{x}-@var{y}
Characters between @var{x} and @var{y}, inclusive.
@var{x} must be smaller than @var{y} in the internal encoding.
@item ^
If @i{char-set-spec} begins with caret, the actual character set
is a complement of what the rest of @i{char-set-spec} indicates.
@item \x@var{N};
A character whose Unicode codepoint is a hexadecimal number @var{N}.
@item \u@var{XXXX}
@itemx \U@var{XXXXXXXX}
This is a legacy Gauche syntax, for a unicode character
whose Unicode codepoint is represented by 4-digit and 8-digit hexadecimal
numbers, respectively.  
@item \s
Whitespace characters
(space, newline, tab, form feed, vertical tab, carriage return).
Members of @code{char-set:ascii-whitespace}.
@item \S
Complement of whitespace characters.
@item \d
Decimal digit characters.  Members of
@code{char-set:ascii-digits}.
@item \D
Complement of decimal digit characters.
@item \w
Word constituent characters (@code{#[A-Za-z0-9_]}).
Members of @code{char-set:ascii-word}.
@item \W
Complement of word constituent characters.
@item \\
A backslash character.
@item \-
A minus character.
@item \^
A caret character.
@item [:alnum:] @dots{}
Character set a la POSIX.  See the table below for the complete list of
recognized character set names.  The set name must be in all lower cases.
This notation only includes characters in ASCII range.  
@item [:^alnum:] @dots{}
Complement set of @code{[:alnum:]} etc.
@item [:ALNUM:] @dots{}
Gauche's extension of character set a la POSIX; the name must be
all in upper cases, and includes full Unicode range.  See the table below
for the recognized names.
@item [:^ALNUM:] @dots{}
Complement set of @code{[:ALNUM:]} etc.
@end table

Here's the list of POSIX-style character class names:

@multitable @columnfractions .15 .85
@item @code{:alpha:} @tab ASCII alphabets.  @code{char-set:ascii-letter}, @code{#[A-Za-z]}
@item @code{:alnum:} @tab ASCII alphabets and digits.  @code{char-set:ascii-letter+digits}, @code{#[0-9A-Za-z]}.
@item @code{:blank:} @tab ASCII blanks.  @code{char-set:ascii-blank}, tab and space.
@item @code{:cntrl:} @tab ASCII control characters.  @code{char-set:ascii-control}, U+0000 to U+001f and U+007f.
@item @code{:digit:} @tab ASCII digits.  @code{char-set:ascii-digit}, @code{#[0-9]}.
@item @code{:graph:} @tab ASCII graphic characters.  @code{char-set:ascii-graphic}.
@item @code{:lower:} @tab ASCII lower-case alphabets.  @code{char-set:ascii-lower-case}, @code{#[a-z]}.
@item @code{:print:} @tab ASCII printing characters.  @code{char-set:ascii-printing}.
@item @code{:punct:} @tab ASCII punctuation characters.  @code{char-set:ascii-punctuation}.
@item @code{:space:} @tab ASCII whitespaces. @code{char-set:ascii-whitespace}.
@item @code{:upper:} @tab ASCII upper-case characters.  @code{char-set:ascii-upper-case}, @code{#[A-Z]}.
@item @code{:word:} @tab ASCII word characters (not POSIX).  @code{char-set:ascii-word}, @code{#[0-9A-Za-z_]}.
@item @code{:xdigit:} @tab Hexadecimal digits.  @code{char-set:hex-digit}, @code{#[0-9a-fA-F]}.
@item @code{:ascii:} @tab ASCII characters (not POSIX).  @code{char-set:ascii}.
@item @code{:ALPHA:} @tab Unicode letters (category @code{L*}). @code{char-set:letter}.
@item @code{:ALNUM:} @tab Unicode letters and digits.  @code{char-set:letter+digits}.
@item @code{:BLANK:} @tab Unicode blanks (tab and category @code{Zs}).  @code{char-set:blank}.
@item @code{:CNTRL:} @tab Unicode control characters (category @code{Cc}).  @code{char-set:iso-control}.
@item @code{:DIGIT:} @tab Unicode digits (category @code{Nd}).  @code{char-set:digit}.
@item @code{:GRAPH:} @tab Unicode graphic characters (letter, digits, punctuation, symbol, and category @code{Nl} and @code{No}).  @code{char-set:graphic}.
@item @code{:LOWER:} @tab Unicode lower-case letters (category @code{Ll}).  @code{char-set:lower-case}, @code{#[a-z]}.
@item @code{:PRINT:} @tab Unicode printing characters (graphic and whitespace).  @code{char-set:printing}.
@item @code{:PUNCT:} @tab Unicode punctuation characters (category @code{P*}).  @code{char-set:punctuation}.
@item @code{:SPACE:} @tab Unicode whitespaces (tab, LF, vertical tab, FF, CR, and category @code{Z*}). @code{char-set:whitespace}.
@item @code{:TITLE:} @tab Unicode titlecase letters (category @code{Lt}).  @code{char-set:title-case}.
@item @code{:UPPER:} @tab Unicode upper-case letters (category @code{Lu}).  @code{char-set:upper-case}, @code{#[A-Z]}.
@item @code{:WORD:} @tab Unicode word characters.  @code{char-set:word}.
@item @code{:XDIGIT:} @tab Hexadecimal digits (same as @code{:xdigit:}).
@end multitable

Here are some examples:

@example
#[aeiou]       ; @r{a character set consists of vowels}
#[a-zA-Z]      ; @r{alphabet}
#[[:alpha:]]   ; @r{alphabet (using POSIX notation)}
#[\\\-]        ; @r{backslash and minus}
#[]            ; @r{empty charset}
#[\x0d;\x0a;\x3000;] ; @r{carriage return, newline, and ideographic space}
@end example

Literal character sets are immutable, as other literal data.  An error
is signalled when you attempt to modify an immutable character set.

@b{Note for the compatibility}:
We used to recognize a syntax @code{\xNN} (two-digit hexadecimal number,
without semicolon terminator) as a character; for example,
@code{#[\x0d\x0a]} as a return and a newline.  We still support it
when we don't see the terminating semicolon, for the compatibility.
There are ambiguous cases: @code{#[\x0a;]} means only a newline
in the current syntax, but a newline and a semicolon in legacy syntax.

Setting the reader mode to @code{legacy} restores the old behavior.
Setting the reader mode to @code{warn-legacy} makes it work like the default
behavior, but prints warning when it finds legacy syntax.
@xref{Reader lexical mode}, for the details.

To write code that can work both in new and old syntax, use @code{\u} escape.
@end deftp

@node Predefined character sets, Character set operations, Character set literals, Character sets
@subsection Predefined character sets
@c NODE 定義済み文字集合

We provide a bunch of predefined character sets, including the ones
defined in R7RS charset library (@pxref{R7RS character sets}).
Those character sets are immutable.

@defvar char-set:letter
[R7RS charset]
Letters (Unicode general category @code{Lu}, @code{Ll}, @code{Lt},
@code{Lm} and @code{Lo}).
@end defvar


@defvar char-set:lower-case
@defvarx char-set:upper-case
@defvarx char-set:title-case
[R7RS charset]
Lower case, upper case and title case letters
(Unicode general category @code{Ll}, @code{Lu} and @code{Lt}, respectively).
@end defvar

@defvar char-set:digit
[R7RS charset]
Digit characters (Unicode general category @code{Nd}).  Note that this
contains many more characters than ASCII @code{0} to @code{9}.  If you
need @code{#[0-9]}, use @code{char-set:ascii-digit}.
@end defvar

@defvar char-set:hex-digit
[R7RS charset]
Digit characters used for hexadecimal, i.e. @code{#[0-9A-Fa-f]}.  This does
not contain other Unicode digit characters, for it isn't practical
to mix non-ascii digit characters with hexadecimal notation.
@end defvar

@defvar char-set:letter+digit
[R7RS charset]
Union of @code{char-set:letter} and @code{char-set:digit}.
@end defvar

@defvar char-set:graphic
[R7RS charset]
Characters that has some glyph.  Union of letters, numbers, punctuations
and symbols.
@end defvar

@defvar char-set:printing
[R7RS charset]
Union of @code{char-set:graphic} and @code{char-set:whitespace}.
@end defvar

@defvar char-set:whitespace
@defvarx char-set:blank
[R7RS charset]
Whitespace and blank characters; @code{char-set:whitespace}
includes @code{#\tab}, @code{#\newline}, @code{#\u000B} (vertical tab),
@code{#\page}, @code{#\return}, and all characters in general category
@code{Zs}, @code{Zl}, @code{Zp}, while @code{char-set:blank}
includes @code{#\tab} and all characters in general category @code{Zs}.
Note that @code{char-set:whitespace} is the same set of characters
that Scheme reader treats as whitespace characters.
@end defvar

@defvar char-set:iso-control
[R7RS charset]
Control characters (Unicode general category @code{Cc}).
@end defvar


@defvar char-set:punctuation
[R7RS charset]
Punctuation characters (Unicode general category
@code{Pc}, @code{Pd}, @code{Ps}, @code{Pe}, @code{Pi}, @code{Pf}
and @code{Po}).
@end defvar

@defvar char-set:symbol
[R7RS charset]
Symbol characters (Unicode general category @code{Sm}, @code{Sc},
@code{Sk} and @code{So}).
@end defvar

@defvar char-set:ascii
[R7RS charset]
Contains all ASCII characters (U+0000 to U+007f).
@end defvar

@defvar char-set:empty
[R7RS charset]
An empty character set.
@end defvar

@defvar char-set:full
[R7RS charset]
A character set that includes all characters.
@end defvar

@defvar char-set:word
A word constituent characters.  In the current version,
it is equivalent to @code{char-set:ascii-word} (@code{#[0-9A-Za-z_]})
but in future versions we may extend this to other Unicode characters.
If you intend to mean ASCII-only words, use @code{char-set:ascii-word}.
@end defvar


@defvar char-set:ascii-letter
@defvarx char-set:ascii-lower-case
@defvarx char-set:ascii-upper-case
@defvarx char-set:ascii-digit
@defvarx char-set:ascii-letter+digit
@defvarx char-set:ascii-graphic
@defvarx char-set:ascii-printing
@defvarx char-set:ascii-whitespace
@defvarx char-set:ascii-blank
@defvarx char-set:ascii-control
@defvarx char-set:ascii-punctuation
@defvarx char-set:ascii-symbol
@defvarx char-set:ascii-word
These are intersection of @code{char-set:ascii} and
the corresponding char set without @code{ascii-}.
(@code{char-set:ascii-control} corresponds to @code{char-set:iso-control}).

The @code{\d}, @code{\s} and @code{\w} notation in the char-set literal 
and regexp literal corresponds to @code{char-set:ascii-digit},
@code{char-set:ascii-whitespace}, and @code{char-set:ascii-word},
respectively (not the Unicode set).

The POSIX character class notation, such as @code{[:alpha:]} in
char-set literal and regexp literal, refers to these ASCII-only
charsets.

Note: We don't have @code{char-set:ascii-title-case} and
@code{char-set:ascii-hex-digit}.  There's no titlecase letter
in ASCII range.  And @code{char-set:hex-digit} is limited to ASCII
by definition.
@end defvar

@defvar char-set:Lu
@defvarx char-set:Ll
@defvarx char-set:Lt
@defvarx char-set:Lm
@defvarx char-set:Lo
@defvarx char-set:Mn
@defvarx char-set:Mc
@defvarx char-set:Me
@defvarx char-set:Nd
@defvarx char-set:Nl
@defvarx char-set:No
@defvarx char-set:Pc
@defvarx char-set:Pd
@defvarx char-set:Ps
@defvarx char-set:Pe
@defvarx char-set:Pi
@defvarx char-set:Pf
@defvarx char-set:Po
@defvarx char-set:Sm
@defvarx char-set:Sc
@defvarx char-set:Sk
@defvarx char-set:So
@defvarx char-set:Zs
@defvarx char-set:Zl
@defvarx char-set:Zp
@defvarx char-set:Cc
@defvarx char-set:Cf
@defvarx char-set:Cs
@defvarx char-set:Co
@defvarx char-set:Cn
Each character set contains the corresponding Unicode characters with
the given general category; e.g. @code{char-set:Lu} contains all characters
of the general category @code{Lu}.
@end defvar

@defvar char-set:L
@defvarx char-set:LC
@defvarx char-set:M
@defvarx char-set:N
@defvarx char-set:P
@defvarx char-set:S
@defvarx char-set:Z
@defvarx char-set:C
Each character set contains the Unicode characters with the general
category starting with the letter; e.g. @code{char-set:L} is union
of @code{char-set:Lu}, @code{char-set:Ll}, @code{char-set:Lt},
@code{char-set:Lm} and @code{char-set:Lo}.

@code{char-set:LC} is for cased-letters, the union of
@code{char-set:Lt}, @code{char-set:Ll}, @code{char-set:Lu}.
@end defvar

@node Character set operations,  , Predefined character sets, Character sets
@subsection Character set operations
@c NODE 文字集合の操作

See also @ref{R7RS character sets} for the comprehensive character set
operations.


@defun char-set? obj
[R7RS charset]
Returns true if and only if @var{obj} is a character set object.
@end defun

@defun char-set-immutable? char-set
Returns @code{#t} if @var{char-set} is an immutable char-set,
@code{#f} if it's a mutable char-set.
@end defun

@defun char-set-contains? char-set char
[R7RS charset]
Returns true if and only if a character set object
@var{char-set} contains a character @var{char}.
@example
(char-set-contains? #[a-z] #\y) @result{} #t
(char-set-contains? #[a-z] #\3) @result{} #f

(char-set-contains? #[^ABC] #\A) @result{} #f
(char-set-contains? #[^ABC] #\D) @result{} #t

@end example
@end defun

@deffn {Generic application} @var{char-set} @var{char}
A char-set object can be applied to a character, and it
works just like @code{(char-set-contains? char-set char)}.

@example
(#[a-z] #\a) @result{} #t
(#[a-z] #\A) @result{} #f

(use gauche.collection)
(filter #[a-z] "CharSet") @result{} (#\h #\a #\r #\e #\t)
@end example
@end deffn

@defun char-set char @dots{}
[R7RS charset]
Creates a character set that contains @var{char} @dots{}.
@example
(char-set #\a #\b #\c)   @result{} #[a-c]
@end example
@end defun

@defun char-set-size char-set
[R7RS charset]
Returns a number of characters in the given charset.

@example
gosh> (char-set-size #[])
0
gosh> (char-set-size #[[:alnum:]])
62
@end example
@end defun

@defun char-set-copy char-set
[R7RS charset]
Copies a character set @var{char-set}.
@end defun

@defun char-set-complement char-set
@defunx char-set-complement! char-set
[R7RS charset]
Returns a complement set of @var{char-set}.  The former always
returns a new set, while the latter may reuse the given charset.
@end defun


@c ----------------------------------------------------------------------
@node Strings, Regular expressions, Character sets, Core library
@section Strings
@c NODE 文字列

@deftp {Builtin Class} <string>
@clindex string
A string class.
@end deftp

It should be emphasized that Gauche's @emph{internal} string object,
@emph{string body}, is immutable.
To comply R7RS in which strings are mutable, a Scheme-level
string object is an indirect pointer to a string body.
Mutating a string means that Gauche creates a new immutable
string body that reflects the changes, then swap the pointer
in the Scheme-level string object.

This may affect some assumptions on the cost of string operations.

@itemize
@item
Copying string is O(1), no matter how long the string is, since
the same string body is shared.
@item
Taking substring usually is also O(1), for the resulting string
shares the substring of the original string body.  Gauche may copy
a part of the string for better memory management, but the visible
cost should stay pretty close to O(1).  (However, note that accessing
to a specific point by index within the original string may cost
O(N) because of multibyte string; which is a different story).
@item
On the other hand, mutating a string cost O(N) where N is the length
of string, even for replacing a character.
@end itemize

Gauche does not attempt to make string mutation faster;
@code{(string-set! s k c)} is exactly as slow as to take
two substrings, before and after of k-th character, and
concatenate them with a single-character string inbetween.
So, just avoid string mutations; we believe it's a better practice.
See also @ref{String constructors}.

R7RS string operations are very minimal.  Gauche supports some
extra built-in operations, and also a rich string library
defined in SRFI-13.   @xref{String library}, for details about SRFI-13.

@menu
* String syntax::
* String predicates::
* String constructors::
* String interpolation::
* String cursors::
* String indexing::
* String accessors & modifiers::
* String comparison::
* String utilities::
* Incomplete strings::
@end menu

@node String syntax, String predicates, Strings, Strings
@subsection String syntax
@c NODE 文字列の表記

@deftp {Reader Syntax} @code{"}@dots{}@code{"}
[R7RS+]
Denotes a literal string.  Inside the double quotes, the following
backslash escape sequences are recognized.

@table @code
@item \"
[R7RS] Double-quote character
@item \\
[R7RS] Backslash character
@item \n
[R7RS] Newline character (ASCII 0x0a).
@item \r
[R7RS] Return character (ASCII 0x0d).
@item \f
Form-feed character (ASCII 0x0c).
@item \t
[R7RS] Tab character (ASCII 0x09)
@item \a
[R7RS] Alarm character (ASCII 0x07).
@item \b
[R7RS] Backspace character (ASCII 0x08).
@item \0
ASCII NUL character (ASCII 0x00).
@item \<whitespace>*<newline><whitespace>*
[R7RS] Ignored.  This can be used to break a long string literal for readability.
This escape sequence is introduced in R6RS.
@item \x@var{N};
[R7RS] A character whose Unicode codepoint is represented by
hexadecimal number @var{N}, which is any number of hexadecimal digits.
(See the compatibility notes below.)
@item \u@var{NNNN}
A character whose UCS2 code is represented by four-digit
hexadecimal number @var{NNNN}.
@item \U@var{NNNNNNNN}
A character whose UCS4 code is represented by eight-digit
hexadecimal number @var{NNNNNNNN}.
@end table

The following code is an example of backslash-newline escape sequence:
@example
(define *message* "\
  This is a long message \
  in a literal string.")

*message*
  @result{} "This is a long message in a literal string."
@end example

Note the whitespace just after `message'.   Since any whitespaces
before `in' is eaten by the reader, you have to put a whitespace
between `message' and the following backslash.  If you want to include
an actual newline character in a string, and any indentation after it,
you can put '\n' in the next line like this:

@example
(define *message/newline* "\
  This is a long message, \
  \n   with a line break.")
@end example

@b{Note for the compatibility}:
We used to recognize a syntax @code{\xNN} (two-digit hexadecimal number,
without semicolon terminator) as a character in a string; for example,
@code{"\x0d\x0a"} was the same as @code{"\r\n"}.  We still support it
when we don't see the terminating semicolon, for the compatibility.
There are ambiguous cases: @code{"\0x0a;"} means @code{"\n"} in the
current syntax, while @code{"\n;"} in the legacy syntax.

Setting the reader mode to @code{legacy} restores the old behavior.
Setting the reader mode to @code{warn-legacy} makes it work like the default
behavior, but prints warning when it finds legacy syntax.
@xref{Reader lexical mode}, for the details.
@end deftp


@node String predicates, String constructors, String syntax, Strings
@subsection String predicates
@c NODE 文字列に関する述語

@defun string? obj
[R7RS base]
Returns @code{#t} if @var{obj} is a string, @code{#f} otherwise.
@end defun

@defun string-immutable? obj
Returns @code{#t} if @var{obj} is an immutable string, @code{#f} otherwise

String literals, and the strings returned from certain procedures such
as @code{symbol->string} are immutable.  To ensure you get
an immutable string in a program, you can use @code{string-copy-immutable}.
@end defun

@defun string-incomplete? obj
Returns @code{#t} if @var{obj} is an incomplete string, @code{#f} otherwise
@end defun

@node String constructors, String interpolation, String predicates, Strings
@subsection String constructors
@c NODE 文字列の作成

@defun make-string k :optional char
[R7RS base]
Returns a string of length @var{k}.  If optional @var{char} is given,
the new string is filled with it.  Otherwise, the string is filled with
a whitespace.  The result string is always complete.

@example
(make-string 5 #\x) @result{} "xxxxx"
@end example

Note that the algorithm to allocate a string by @code{make-string} and
then fills it one character at a time is @emph{extremely} inefficient
in Gauche, and should be avoided. 

In Gauche, a string is simply a pointer to an immutable string content.
If you mutate a string by, e.g. @code{string-set!}, Gauche allocates
whole new immutable string content, copies the original content with
modification, then swap the pointer of the original string.  It is no
more efficient than making a new copy.

You can use an output string port for a string construction
(@pxref{String ports}).
Even creating a list of characters and
using @code{list->string} is faster than using @code{make-string} and
@code{string-set!}.
@end defun

@defun make-byte-string k :optional byte
Creates and returns an incomplete string o size @var{k}.
If @var{byte} is given,
which must be an exact integer, and its lower 8 bits
are used to initialize every byte in the created string.
@end defun

@defun string char @dots{}
[R7RS base]
Returns a string consisted by @var{char} @dots{}.
@end defun

@deffn {Generic Function} x->string obj
A generic coercion function.
Returns a string representation of @var{obj}.
The default methods are defined as follows: strings are returned
as is, numbers are converted by @code{number->string}, symbols are
converted by @code{symbol->string}, and other objects are
converted by @code{display}.

Other class may provide a method to customize the behavior.
@end deffn

@node String interpolation, String cursors, String constructors, Strings
@subsection String interpolation
@c NODE 文字列の補間

The term "string interpolation" is used in various scripting languages
such as Perl and Python to refer to the feature to embed expressions
in a string literal, which are evaluated and then their results are
inserted into the string literal at run time.

Scheme doesn't define such a feature, but Gauche implements it as a
reader macro.

@deftp {Reader Syntax} @code{#}@var{string-literal}
@lxindex #"
Evaluates to a string.  If @var{string-literal} contains the
character sequence @code{~@var{expr}}, where
@var{expr} is a valid external representation
of a Scheme expression, @var{expr} is evaluated and
its result is inserted in the original place (by using @code{x->string},
see @ref{String constructors}).

The tilde and the following expression must be adjacent (without containing
any whitespace characters), or it is not recognized as a special sequence.

To include a tilde itself immediately followed by non-delimiting
character, use @code{~~}.

Other characters in the @var{string-literal} are copied as is.

If you use a variable as @var{expr} and need to delimit it from the
subsequent string, you can use the symbol escape syntax
using `|' character, as shown in the last two examples below.

@example
#"This is Gauche, version ~(gauche-version)."
 @result{} "This is Gauche, version 0.9.10."

#"Date: ~(sys-strftime \"%Y/%m/%d\" (sys-localtime (sys-time)))"
 @result{} "Date: 2002/02/18"

(let ((a "AAA")
      (b "BBB"))
 #"xxx ~a ~b zzz")
 @result{} "xxx AAA BBB zzz"

#"123~~456~~789"
 @result{} "123~456~789"

(let ((n 7)) #"R~|n|RS")
 @result{} "R7RS"

(let ((x "bar")) #"foo~|x|.")
 @result{} "foobar"
@end example

In fact, the reader expands this syntax into a macro call,
which is then expanded into a call of @code{string-append}
as follows:
@example
#"This is Gauche, version ~(gauche-version)."
 @equiv{}
(string-interpolate* ("This is Gauche, version "
                      (gauche-version)
                      "."))

;; then, it expands to...

(string-append "This is Gauche, version "
               (x->string (gauche-version))
               ".")
@end example

(NB: The exact spec of @code{string-interpolate*} might change in future,
so do not rely on the current behavior.)

Since the @code{#"..."} syntax is equivalent to a macro call
of @code{string-interpolate*}, which is provided in the Gauche module,
it must be visible from where you use the interpolation syntax.
When you write Gauche code, typically you implicitly inherit the Gauche
module so you don't need to worry; however, if you start from R7RS code,
make sure you import @code{string-interpolate*}
(by @code{(import (gauche base))}, for example) whenever you use
string interpolation syntax.  Also be careful not to shadow
@code{string-interpolate*} locally.
@end deftp

@deftp {Reader Syntax} @code{#`}@var{string-literal}
@lxindex #`
This is the old style of string-interpolation.  It is still recognized,
but discouraged for the new code.

Inside @var{string-literal}, you can use @code{,@var{expr}} 
(instead of @code{~@var{expr}}) to
evaluate @var{expr}.  If comma isn't immediately followed by a
character starting an expression, it loses special meaning.

@example
#`"This is Gauche, version ,(gauche-version)"
@end example
@end deftp


@emph{Rationale of the syntax:}
There are wide variation of string interpolation syntax among scripting
languages.  They are usually linked with other syntax of the language
(e.g. prefixing @code{$} to mark evaluating place is in sync with variable
reference syntax in some languages).

The old style of string interpolation syntax was taken from quasiquote
syntax, because those two are conceptually 
similar operations (@pxref{Quasiquotation}).
However, since comma character is frequently used in string literals,
it was rather awkward.

We decided that tilde is more suitable as the unquote character for
the following reasons.

@itemize
@item
Traditionally, Lisp's string formatter @code{format} uses @code{~} to introduce
format directives (@pxref{Formatting output}).  Lispers are used to
scan @code{~}'s in a string as variable portions.
@item
Gauche's @code{~} is a universal accessor, and the operator has a nuance
of ``taking something out of it''
(@pxref{Universal accessor}).
@item
Clojure, a new Lisp dialect, adopted @code{~} as the unquote character in
the quasiquote syntax, instead of commas.
@end itemize

Note that Scheme allows wider range of characters for valid identifier names
than usual scripting languages.
Consequently, you will almost always need to use `|' delimiters
when you interpolate the value of a variable.
For example, while you can write
@code{"$year/$month/$day $hour:$minutes:$seconds"} in Perl,
you should write @code{#"~|year|/~|month|/~day ~|hour|:~|minutes|:~seconds"}.
It may be better always to delimit direct variable references
in this syntax to avoid confusion.


@node String cursors, String indexing, String interpolation, Strings
@subsection String cursors
@c NODE 文字列カーソル

String cursors are opaque objects that point into strings, similar to
indexes. Cursors however are more efficient. For example, to get a
character with @code{string-ref} using an index on a multibyte string,
Gauche needs to iterate from the beginning of the string until that
position, or @code{O(n)}. Using cursors you can access in @code{O(1)}
(for singlebyte (ASCII) strings or an indexed string,
Gauche does it in @code{O(1)} even with index.  @xref{String indexing},
for the details of indexed string.)

For a string of length n, there can be n+1 cursors. The
last cursor at the end of the string does not point to any valid
character, it's usually used to determine if nothing is found.

A string cursor is associated with a specific string and should not be
used with another string. A string cursor also becomes invalid when
the associated string is modified. Accessing an invalid cursor does
not always fail though. Running @code{gosh} with @code{-fsafe-string-cursors}
could help catch these issues, with some performance overhead.
@xref{Invoking Gosh}.

Most of the time, string cursors aren't heap-allocated.  It is only
allocated in heap either (1) when it points at a huge byte index,
or (2) when you use @code{-fsafe-string-cursors} to enable extra
run-time check.

The threashold of byte index to cause a string cursor to be heap-allocated
is 2^56 on 64bit systems, and 2^24 on 32bit systems, in the current
implementation.  On 64bit systems you will never hit the threashold practically.
On 32bit systems you may, if you have a huge string, but you may want to
consider using other data structure rather than keeping such data in
one string object.

Most procedures that take indexes in Gauche can also take
cursors. Relying on this though is unportable. For example, the
@code{substring} procedure in RnRS standards does not mention anything
about cursors even though the Gauche version accepts cursors. For
portable programs, you should only use cursors on procedures from
srfi-130 module (@pxref{Cursor-based string library}).

@deftp {Builtin Class} <string-cursor>
Represents a cursor. When printed out, you'll see the
@emph{byte offset} from the beginning of the string, not the character index.

@example
(string-index->cursor "あかさたな" 2)
 @result{} #<string-cursor 6>
@end example
@end deftp

@defun string-cursor? @var{obj}
[SRFI-130]
Returns @code{#t} if @var{obj} is a string cursor, @code{#f} otherwise.
@end defun

@defun string-cursor-start @var{str}
[SRFI-130]
Returns a cursor pointing to the start of
a string @var{str}. It returns a valid cursor on an
empty string too. It's the same as @code{string-cursor-end} in that
case.
@end defun

@defun string-cursor-end @var{str}
[SRFI-130]
Returns a cursor pointing to the end of @var{str} (the point after
the last character.)  If @var{str} is empty, it is the same
as @code{string-cursor-start}.
This cursor does not point to any valid character of the string.
@end defun

@defun string-cursor-next @var{str} @var{cur}
[SRFI-130]
Returns the cursor into @var{str} following @var{cur}. @var{cur} can
also be an index.  An error is signaled if @var{cur} points to the end
of the string.
@end defun

@defun string-cursor-prev @var{str} @var{cur}
[SRFI-130]
Returns the cursor into @var{str} preceding @var{cur}. @var{cur} can
also be an index.  An error is signaled if @var{cur} points to the
beginning of the string.
@end defun

@defun string-cursor-forward @var{str} @var{cur} @var{n}
[SRFI-130]
Returns the cursor into @var{str} following @var{cur} by @var{n}
characters. @var{cur} can also be an index.
@end defun

@defun string-cursor-back @var{str} @var{cur} @var{n}
[SRFI-130]
Returns the cursor into @var{str} preceding @var{cur} by @var{n}
characters. @var{cur} can also be an index.
@end defun

@defun string-index->cursor @var{str} @var{index}
[SRFI-130]
Convert an @var{index} to a cursor. If @var{index} is a cursor it will
be returned as-is.
@end defun

@defun string-cursor->index @var{str} @var{cur}
[SRFI-130]
Convert a cursor to an index. If @var{cur} is a an index it will be
returned as-is.
@end defun

@defun string-cursor-diff @var{str} @var{start} @var{end}
[SRFI-130]
Returns the number of characters between @var{start} and @var{end}. It
should be non-negative if @var{start} precedes @var{end}, non-positive
otherwise. @var{start} and @var{end} also accept index.
@end defun

@defun string-cursor=? @var{cur1} @var{cur2}
@defunx string-cursor<? @var{cur1} @var{cur2}
@defunx string-cursor<=? @var{cur1} @var{cur2}
@defunx string-cursor>? @var{cur1} @var{cur2}
@defunx string-cursor>=? @var{cur1} @var{cur2}
[SRFI-130]
Compares two cursors or two indexes (but not a cursor and an index)
and returns @code{#t} or @code{#f} accordingly.
@end defun

@node String indexing, String accessors & modifiers, String cursors, Strings
@subsection String indexing
@c NODE 文字列索引

Since Gauche stores strings in multibyte encoding, random access
requires O(N) by default.  In most cases, string access is either
sequential or search-and-extract pattern, and Gauche provides direct
means for these operations, so you don't need to deal with indexed access.
However, there may be a case that you have need more efficient random
access string (mostly when porting third-party code, we imagine).

There are a couple of ways to achieve O(1) random access.

First, instead of integer character indexes,
you can use string cursors (@pxref{String cursors}).  It is defined
by @code{srfi-130}, and you can use the code that's using srfi-130
as is, without worring about slow access.  However, if external interface
gives you integer character index, converting index to cursor and vice versa
takes O(N) after all.

There's another way.  You can precompute @emph{string index}, mapping from
integer character index to the position in the multibyte string.  It costs
O(N) of time and space to compute it, but once computed, you have
O(1) random access.  (We store positions for every K characters, where K
is between 16 to 256, so it won't take up as large storage as the
actual string body).

For portability, srfi-135 Immutable Texts provides O(1) accessible string
as ``texts''.  On Gauche, a text is just an immutable string with
index attached.

@defun string-build-index! str
Computes and attaches index to a string @var{str}, and returns @var{str}
itself.  The operation doesn't alter the content of @var{str}, and you can
pass immutable string as well.

If @var{str} is a single-byte string (ASCII-only, or incomplete),
or a short one (less than 64 octets), no index is attached.
It is ok to pass a string which already has an index; then index computation
is skipped.

The index is attached to the string's content.  If you alter @var{str}
by e.g. @code{string-set!}, the index is discarded.
@end defun

@defun string-fast-indexable? str
Returns @code{#t} iff index access of a string @var{str} is effectively O(1),
that is, @var{str} is either a single-byte string,
a short string, or a long multibyte string with index computed.
@end defun


@node String accessors & modifiers, String comparison, String indexing, Strings
@subsection String accessors & modifiers
@c NODE 文字列のアクセスと変更

@defun string-length string
[R7RS base]
Returns a length of (possibly incomplete) string @var{string}.
@end defun

@defun string-size string
Returns a size of (possibly incomplete) @var{string}.
A size of string is a number of bytes @var{string} occupies on memory.
The same string may have different sizes if the native encoding scheme
differs.

For incomplete string, its length and its size always match.
@end defun

@defun string-ref cstring k :optional fallback
[R7RS+]
Returns @var{k}-th character of a complete string @var{cstring}.
It is an error to pass an incomplete string.

By default, an error is signaled if @code{k} is out of range
(negative, or greater than or equal to the length of @var{cstring}).
However, if an optional argument @var{fallback} is given,
it is returned in such case.  This is Gauche's extension.

If @var{cstring} is a multibyte string without index attached,
this procedure takes O(@var{k}) time.  @xref{String indexing}, for
ensuring O(1) access.

@var{k} can also be a string cursor (also Gauche's extension).
Cursor acccess is O(1).
@end defun

@defun string-byte-ref string k
Returns @var{k-th} byte of a (possibly incomplete) string @var{string}.
Returned value is an integer in the range between 0 and 255.
@var{k} must be greater than or equal to zero, and less than
@code{(string-size @var{string})}.
@end defun

@defun string-set! string k char
[R7RS base]
Substitute @var{string}'s @var{k}-th character by @var{char}.
@var{k} must be greater than or equal to zero, and less than
@code{(string-length @var{string})}.
Return value is undefined.

If @var{string} is an incomplete string, integer value of the lower 8 bits
of @var{char} is used to set @var{string}'s @var{k}-th byte.

See the notes in @code{make-string} about performance consideration.
@end defun

@defun string-byte-set! string k byte
Substitute @var{string}'s @var{k}-th byte by integer @var{byte}.
@var{byte} must be in the range between 0 to 255, inclusive.
@var{k} must be greater than or equal to zero, and less than
@code{(string-size @var{string})}.
If @var{string} is a complete string, it is turned to incomplete string
by this operation.
Return value is undefined.
@end defun

@node String comparison, String utilities, String accessors & modifiers, Strings
@subsection String comparison
@c NODE 文字列の比較

@defun string=? string1 string2 string3 @dots{}
[R7RS base]
Returns @code{#t} iff all arguments are strings with the same content.

If any of arguments is incomplete string, it returns @code{#t} iff
all arguments are incomplete and have exactly the same content.
In other words, a complete string and an incomplete string never equal
to each other.
@end defun

@defun string<? string1 string2 string3 @dots{}
@defunx string<=? string1 string2 string3 @dots{}
@defunx string>? string1 string2 string3 @dots{}
@defunx string>=? string1 string2 string3 @dots{}
[R7RS base]
Compares strings in codepoint order.  Returns @code{#t} iff
all the arguments are ordered.

Comparison between an incomplete string and a complete string, or between
two incomplete strings, are done by octet-to-octet comparison.  If a
complete string and an incomplete string have exactly the same binary
representation of the content, a complete string is smaller.
@end defun

@defun string-ci=? string1 string2 string3 @dots{}
@defunx string-ci<? string1 string2 string3 @dots{}
@defunx string-ci<=? string1 string2 string3 @dots{}
@defunx string-ci>? string1 string2 string3 @dots{}
@defunx string-ci>=? string1 string2 string3 @dots{}
Case-insensitive string comparison.

These procedures fold argument character-wise, according to
Unicode-defined character-by-character case mapping.  See
@code{char-foldcase} for the details (@ref{Characters}).
Character-wise case folding doesn't handles the case like
German eszett:

@example
(string-ci=? "\u00df" "SS") @result{} #f
@end example

R7RS requires @code{string-ci}* procedures to use string case folding.
Gauche provides R7RS-conformant case insensitive comparison procedures
in @code{gauche.unicode} (@pxref{Full string case conversion}).
If you write in R7RS, importing
@code{(scheme char)} library, you'll use @code{gauche.unicode}'s
@code{string-ci}* procedures.
@end defun

@node String utilities, Incomplete strings, String comparison, Strings
@subsection String utilities
@c NODE 文字列を扱うその他の手続き

@defun substring string start end
[R7RS+ base]
Returns a substring of @var{string}, starting from @var{start}-th
character (inclusive) and ending at @var{end}-th character (exclusive).
The @var{start} and @var{end} arguments must satisfy
@code{0 <= @var{start} < @var{N}},
@code{0 <= @var{end} <= @var{N}}, and
@code{@var{start} <= @var{end}}, where @var{N} is the length of the
string.

@var{start} and @var{end} can also be string cursors, but this is an
extension of Gauche.

When @var{start} is zero and @var{end} is @var{N}, this procedure
returns a copy of @var{string}.

Actually, extended @code{string-copy} explained below
is a superset of @code{substring}.  This procedure is
kept mostly for compatibility of R7RS programs.
See also @code{subseq} in @ref{Sequence framework},
for the generic version.
@end defun

@defun string-append string @dots{}
[R7RS base]
Returns a newly allocated string whose content is concatenation of
@var{string} @dots{}.

See also @code{string-concatenate} in @ref{SRFI-13 String reverse & append}.
@end defun

@defun string->list string :optional start end
@defunx list->string list
[R7RS base]
Converts a string to a list of characters or vice versa.

You can give an optional start/end indexes to @code{string->list}.

For @code{list->string}, every elements of @var{list} must be
a character, or an error is signaled.  If you want to build
a string out of a mixed list of strings and characters, you
may want to use @code{tree->string} in @ref{Lazy text construction}.
@end defun

@defun string-copy string :optional start end
[R7RS base]
Returns a copy of @var{string}.  You can give @var{start} and/or
@var{end} index to extract the part of the original string
(it makes @code{string-copy} a superset of @code{substring} effectively).

If only @var{start} argument is given, a substring beginning from
@var{start}-th character (inclusive) to the end of @var{string} is
returned.  If both @var{start} and @var{end} argument are given,
a substring from @var{start}-th character (inclusive) to
@var{end}-th character (exclusive) is returned.
See @code{substring} above for the condition that @var{start} and
@var{end} should satisfy.

Node: R7RS's destructive version @code{string-copy!} is provided
by @code{srfi-13} module (@pxref{String library}).
@end defun

@defun string-copy-immutable string :optional start end
If @var{string} is immutable, return it as is.  Otherwise, returns
an immutable copy of @var{string}.  It is a dual of @code{string-copy}
which always returns a mutable copy.

The optional @var{start} and @var{end} argument may be a nonnegative
integer character index and/or string cursors to restrict the range
of @var{string} to be copied.
@end defun


@defun string-fill! string char :optional start end
[R7RS base]
Fills @var{string} by @var{char}.  Optional
@var{start} and @var{end} limits the effective area.
@example
(string-fill! "orange" #\X)
  @result{} "XXXXXX"
(string-fill! "orange" #\X 2 4)
  @result{} "orXXge"
@end example

See the notes in @code{make-string} about performance consideration.
@end defun

@defun string-join strs :optional delim grammar
[SRFI-13] Concatenate strings in the list @var{strs},
with a string @var{delim} as `glue'.

The argument @var{grammar} may be one of the following symbol
to specify how the strings are concatenated.
@table @code
@item infix
Use @var{delim} between each string.  This mode is default.
Note that this mode introduce ambiguity when @var{strs}
is an empty string or a list with a null string.
@example
(string-join '("apple" "mango" "banana") ", ")
  @result{} "apple, mango, banana"
(string-join '() ":")
  @result{} ""
(string-join '("") ":")
  @result{} ""
@end example
@item strict-infix
Works like @code{infix}, but empty list is not allowed to @var{strs},
thus avoiding ambiguity.
@item prefix
Use @var{delim} before each string.
@example
(string-join '("usr" "local" "bin") "/" 'prefix)
  @result{} "/usr/local/bin"
(string-join '() "/" 'prefix)
  @result{} ""
(string-join '("") "/" 'prefix)
  @result{} "/"
@end example
@item suffix
Use @var{delim} after each string.
@example
(string-join '("a" "b" "c") "&" 'suffix)
  @result{} "a&b&c&"
(string-join '() "&" 'suffix)
  @result{} ""
(string-join '("") "&" 'suffix)
  @result{} "&"
@end example
@end table
@end defun

@defun string-scan string item :optional return
@defunx string-scan-right string item :optional return
Scan @var{item} (either a string or a character) in @var{string}.
While @code{string-scan} finds the leftmost match, @code{string-scan-right}
finds the rightmost match.

The @var{return} argument specifies what value should be returned
when @var{item} is found in @var{string}.  It must be one of the
following symbols.

@table @code
@item index
Returns the index in @var{string} if @var{item} is found, or @code{#f}.
This is the default behavior.
@example
(string-scan "abracadabra" "ada") @result{} 5
(string-scan "abracadabra" #\c) @result{} 4
(string-scan "abracadabra" "aba") @result{} #f
@end example
@item before
Returns a substring of @var{string} before @var{item}, or
@code{#f} if @var{item} is not found.
@example
(string-scan "abracadabra" "ada" 'before) @result{} "abrac"
(string-scan "abracadabra" #\c 'before) @result{} "abra"
@end example
@item after
Returns a substring of @var{string} after @var{item}, or
@code{#f} if @var{item} is not found.
@example
(string-scan "abracadabra" "ada" 'after) @result{} "bra"
(string-scan "abracadabra" #\c 'after) @result{} "adabra"
@end example
@item before*
Returns a substring of @var{string} before @var{item}, and
the substring after it.  If @var{item} is not found, returns
@code{(values #f #f)}.
@example
(string-scan "abracadabra" "ada" 'before*)
  @result{} "abrac" @r{and} "adabra"
(string-scan "abracadabra" #\c 'before*)
  @result{} "abra" @r{and} "cadabra"
@end example
@item after*
Returns a substring of @var{string} up to the end of @var{item},
and the rest.  If @var{item} is not found, returns
@code{(values #f #f)}.
@example
(string-scan "abracadabra" "ada" 'after*)
  @result{} "abracada" @r{and} "bra"
(string-scan "abracadabra" #\c 'after*)
  @result{} "abrac" @r{and} "adabra"
@end example
@item both
Returns a substring of @var{string} before @var{item} and
after @var{item}.  If @var{item} is not found, returns
@code{(values #f #f)}.
@example
(string-scan "abracadabra" "ada" 'both)
  @result{} "abrac" @r{and} "bra"
(string-scan "abracadabra" #\c 'both)
  @result{} "abra" @r{and} "adabra"
@end example
@end table
@end defun

@defun string-split string splitter :optional grammar limit start end
@defunx string-split string splitter :optional limit start end
[SRFI-152+]
Splits @var{string} by @var{splitter} and returns a list of strings.
@var{splitter} can be a character, a character set, a string,
a regexp, or a procedure.

If @var{splitter} is a character or a string, it is
used as a delimiter.  Note that srfi-152's @code{string-split}
only allows strings for @var{splitter} (it also interprets the first
optional argument as a grammar; see below for the compatibility note.)

If @var{splitter} is a character set, any consecutive characters
that are member of the character set are used as a delimiter.

If a procedure is given to @var{splitter}, it is called for each
character in @var{string}, and the consecutive characters that caused
@var{splitter} to return a true value are used as a delimiter.

@example
(string-split "/aa/bb//cc" #\/)    @result{} ("" "aa" "bb" "" "cc")
(string-split "/aa/bb//cc" "/")    @result{} ("" "aa" "bb" "" "cc")
(string-split "/aa/bb//cc" "//")   @result{} ("/aa/bb" "cc")
(string-split "/aa/bb//cc" #[/])   @result{} ("" "aa" "bb" "cc")
(string-split "/aa/bb//cc" #/\/+/) @result{} ("" "aa" "bb" "cc")
(string-split "/aa/bb//cc" #[\w])  @result{} ("/" "/" "//" "")
(string-split "/aa/bb//cc" char-alphabetic?) @result{} ("/" "/" "//" "")

;; some boundary cases
(string-split "abc" #\/) @result{} ("abc")
(string-split ""    #\/) @result{} ("")
@end example

The @var{grammar} argument is the same as @code{string-join} above; it
must be one of symbols @code{infix}, @code{strict-infix}, @code{prefix}
or @code{suffix}.  When omitted, @code{infix} is assumed.

@example
(string-split "/a/b/c/" "/" 'infix)  @result{} ("" "a" "b" "c" "")
(string-split "/a/b/c/" "/" 'prefix) @result{} ("a" "b" "c" "")
(string-split "/a/b/c/" "/" 'suffix) @result{} ("" "a" "b" "c")
@end example

In general, the following relationship holds:

@example
(string-join XS DELIM GRAMMAR) @result{} S
(string-split S DELIM GRAMMAR) @result{} XS
@end example

If @var{limit} is given and not @code{#f}, it must be a nonnegative
integer and specifies the maximum number of match to the @var{splitter}.
Once the limit is reached, the rest of string is included in the result
as is.

@example
(string-split "a.b..c" "." 'infix 0)   @result{} ("a.b..c")
(string-split "a.b..c" "." 'infix 1)   @result{} ("a" "b..c")
(string-split "a.b..c" "." 'infix 2)   @result{} ("a" "b" ".c")
@end example

Compatibility note:
The @var{grammar} argument is added for the consistency of srfis
(srfi-130, srfi-152, @pxref{String library (reduced)}).
However, for the backward compatibility and
the convenience, it also accepts @var{limit} without @var{grammar} argument;
it is distinguishable since @var{grammar} is a symbol and
@var{limit} is an integer.
For the code that's compatible to srfi-152, use the first form that takes
@var{grammar} argument.

@example
(string-split "a.b..c" "." 2)   @result{} ("a" "b" ".c")
@end example

The @var{start} and @var{end} arguments limits input string
in the given range before splitting.

See also @code{string-tokenize} in
(@pxref{SRFI-13 Other string operations}).
@end defun

@defun string-map proc str str2 @dots{}
@defunx string-map proc str :optional start end
[R7RS base][SRFI-13]
Applies @var{proc} over each character in the input string, and
gathers the characters returned from @var{proc} into a string and
returns it.  It is an error if @var{proc} returns non-character.

Because of historical reasons, this procedure has two interfaces.
The first one takes one or more input strings, and @var{proc} receives
as many characters as the number of input strings, each character
being taken from each string.  Iteration stops on the shortest string.
This is defined in R7RS-small, and consistent with @code{map},
@code{vector-map}, etc.

The second one takes only one string argument, and optional start/end
arguments, which may be nonnegative integer indexes or string cursors
to limit the input range of the string.  This is defined in srfi-13,
string library.

The order in which @var{proc} is applied is not guaranteed to be left to right.
You shouldn't depend on the order.

If @var{proc} saves a continuation and it is invoked later, the result
already returned from @code{string-map} won't be affected 
(as specified in R7RS).

@example
(string-map char-upcate "apple") @result{} "APPLE"
(string-map (^[a b] (if (char>? a b) a b)) "orange" "apple") @result{} "orpng"
(string-map char-upcase "pineapple" 0 4) @result{} "PINE"
@end example
@end defun


@defun string-for-each proc str str2 @dots{}
@defunx string-for-each proc str :optional start end
[R7RS base][SRFI-13]
Applies @var{proc} over each character in the input string in left-to-right
order.  The results of @var{proc} is discarded.

Because of historical reasons, this procedure has two interfaces,
first one defined in R7RS and second one defined in srfi-13.
See @code{string-map} above for the explanation.
@end defun


@node Incomplete strings,  , String utilities, Strings
@subsection Incomplete strings
@c NODE 不完全文字列

A string can be flagged as "incomplete" if it may contain
byte sequences that do not consist of a valid multibyte character
in the Gauche's native encoding.

Incomplete strings may be generated in several circumstances;
reading binary data as a string, reading a string data that has
been 'chopped' in middle of a multibyte character, or
concatenating a string with other incomplete strings, for example.

Incomplete strings should be regarded as an exceptional case.
It used to be a way to handle byte strings, but now we have
u8vector (@pxref{Uniform vectors}) for that purpose.
In fact, we're planning to remove it in the future releases.

Just in case, if you happen to get an incomplete string,
you can convert it to a complete string by @code{string-incomplete->complete}.

@deftp {Reader Syntax} @code{#**"}@dots{}@code{"}
@lxindex #**
Denotes incomplete string.  The same escape sequences as the complete
string syntax are recognized.

Rationale of the syntax: @code{#*} is used for bit vectors.
Since an incomplete strings is really a byte vector,
it has similarity.

Note: We used @code{#*"...."} for an incomplete string on 0.9.9 and
before.  It turned out that it couldn't coexist with bitvectors, for
@code{#*} is a valid bitvector literal (zero-length vector), and
@code{"} is a delimiter, so @code{#*"...."} can be parsed as
a zero-length bitvector followed by a string.  From 0.9.10, we changed
the incomplete string literal to @code{#**"..."}.  It's a bit lengthy,
but incomplete strings are anomalies and shouldn't be used often anyway.

For the backward compatibility, @code{#*"..."} is still read as an
incomplete string literal, unless the reader lexical mode
is @code{strict-r7} (@pxref{Reader lexical mode}, for the details).
If the reader lexical mode is @code{warn-legacy}, it is read as
an incomplete string, but a warning is issued.
If the mode is @code{strict-r7}, it is read as a zero-length
bitvector followed by a string.

In future releasers, @code{#*"..."} would be warned by default,
and later we'll gradually move to @code{strict-r7} behavior.
@end deftp


@defun string-incomplete->complete str :optional handling filler
Reinterpret the content of an incomplete string @var{str}
and returns a newly created complete string from it.
The @var{handling} argument specifies how to handle the illegal
byte sequences in @var{str}.
@table @asis
@item @code{#f}
If @var{str} contains an illegal byte sequence, give up the
conversion and returns @code{#f}.  This is the default behavior.
@item @code{:omit}
Omit any illegal byte sequences.
@item @code{:replace}
Replace each byte in illegal byte sequences by a character given
in @var{filler} argument, defaulted to @code{?}.
@item @code{:escape}
Replace each byte in illegal byte sequences by a sequence of
@var{filler} @code{<hexdigit>} @code{<hexdigit>}.
Besides, the @var{filler} characters in the original string is replaced with
@var{filler} @var{filler}.
@end table

If @var{str} is already a complete string, its copy is returned.

The procedure always returns a complete string, except when
the @var{handling} argument is @code{#f} (default) and the input is an
incomplete string, in which case @code{#f} is returned.

When Gauche's internal encoding is utf-8, the procedure works as follows:

@example
(string-incomplete->complete #*"_abc")
  @result{} "_abc"     ; can be represented as a complete string

(string-incomplete->complete #*"_ab\x80;c")
  @result{} #f        ; can't be represented as a complete string

(string-incomplete->complete #*"_ab\x80;c" :omit)
  @result{} "_abc"     ; omit the illegal bytes

(string-incomplete->complete #*"_ab\x80;c" :replace #\_)
  @result{} "_ab_c"    ; replace the illegal bytes

(string-incomplete->complete #*"_ab\x80;c" :escape #\_)
  @result{} "__ab_80c" ; escape the illegal bytes and escape char itself
@end example
@end defun

@c ----------------------------------------------------------------------
@node Regular expressions, Vector family, Strings, Core library
@section Regular expressions
@c NODE 正規表現

Gauche has a built-in regular expression engine which is mostly
upper-compatible of POSIX extended regular expression, plus
some extensions from Perl 5 regexp.

A special syntax is provided for literal regular expressions.
Also regular expressions are applicable, that is,
it works like procedures that match the given string to itself.
Combining with these two features enables writing some
string matching idioms compact.

@example
(find #/pattern/ list-of-strings)
  @result{} @i{match object} or #f
@end example

@menu
* Regular expression syntax::
* Using regular expressions::
* Inspecting and assembling regular expressions::
@end menu

@node Regular expression syntax, Using regular expressions, Regular expressions, Regular expressions
@subsection Regular expression syntax
@c NODE 正規表現の構文

@deftp {Reader Syntax} @code{#/@i{regexp-spec}/}
@deftpx {Reader Syntax} @code{#/@i{regexp-spec}/i}
@lxindex #/
Denotes literal regular expression object.  When read, it becomes
an instance of @code{<regexp>}.

If a letter '@code{i}' is given at the end, the created regexp
becomes @emph{case-folding regexp}, i.e. it matches in the case-insensitive
way.

The advantage of using this syntax over @code{string->regexp} is
that the regexp is compiled only once.  You can use literal regexp
inside loop without worrying about regexp compilation overhead.
If you want to construct regexp on-the-fly, however, use @code{string->regexp}.
@end deftp

Gauche's built-in regexp syntax follows POSIX extended regular
expression, with a bit of extensions taken from Perl.
(Scheme Regulare Expression (SRE) is also supported as an alternative
syntax; @pxref{R7RS regular expressions}, for the details of SRE.)

@table @code
@item @i{re}*
Matches zero or more repetition of @i{re}.

@item @i{re}+
Matches one or more repetition of @i{re}.

@item @i{re}?
Matches zero or one occurrence of @i{re}.

@item @i{re}@{@i{n}@}
@itemx @i{re}@{@i{n},@i{m}@}
Bounded repetition.  @code{@i{re}@{@i{n}@}} matches exactly @i{n}
occurrences of @i{re}.
@code{@i{re}@{@i{n},@i{m}@}} matches at least @var{n} and at most
@var{m} occurrences of @i{re}, where @var{n} <= @var{m}.
In the latter form, either @var{n} or @var{m} can be omitted; omitted @var{n}
is assumed as 0, and omitted @var{m} is assumed infinity.

@item @i{re}*?
@itemx @i{re}+?
@itemx @i{re}??
@itemx @i{re}@{@i{n},@i{m}@}?
Same as the above repetition construct, but these syntaxes
use "non-greedy" or "lazy" match strategy.  That is, they try to match
the minimum number of occurrences of @i{re} first, then retry
longer ones only if it fails.  In the last form
either @var{n} or @var{m} can be omitted.
Compare the following examples:

@example
(rxmatch-substring (#/<.*>/ "<tag1><tag2><tag3>") 0)
  @result{} "<tag1><tag2><tag3>"

(rxmatch-substring (#/<.*?>/ "<tag1><tag2><tag3>") 0)
  @result{} "<tag1>"
@end example

@item (@i{re}@dots{})
Clustering with capturing.  The regular expression enclosed
by parenthesis works as a single @i{re}.  Besides, the string
that matches @i{re} @dots{} is saved as a @emph{submatch}.

@item (?:@i{re}@dots{})
Clustering without capturing.   @code{@i{re} @dots{}} works as
a single @i{re}, but the matched string isn't saved.

@item (?<@i{name}>@i{re}@dots{})
Named capture and clustering.  Like @code{(@i{re}@dots{})},
but adds the name @i{name} to the matched substring.
You can refer to the matched substring by both index number
and the name.

When the same name appears more than once in a regular
expression, it is undefined which matched substring is
returned as the submatch of the named capture.

@item (?i:@i{re}@dots{})
@itemx (?-i:@i{re}@dots{})
Lexical case sensitivity control.
@code{(?i:@i{re}@dots{})} makes @i{re}@dots{} matches case-insensitively,
while @code{(?-i:@i{re}@dots{})} makes
@i{re}@dots{} matches case-sensitively.

Perl's regexp allows several more flags to appear between '?' and ':'.
Gauche only supports above two, for now.

@item @i{pattern1}|@i{pattern2}|@dots{}
Alternation.  Matches either one of patterns, where each
pattern is @i{re} @dots{}.

@item \@i{n}
Backreference.  @i{n} is an integer.
Matches the substring captured by the @i{n}-th capturing group.
(counting from 1).  When capturing groups are nested, groups
are counted by their beginnings.
If the @i{n}-th capturing group is in a repetition and has matched
more than once, the last matched substring is used.

@item \k<@i{name}>
Named backreference.  Matches the substring captured by
the capturing group with the name @i{name}.
If the named capturing group is in a repetition and has matched
more than once, the last matched substring is used.
If there are more than one capturing group with @i{name},
matching will succeed if the input matches either one of the substrings
captured by those groups.

@item .
Matches any character (including newline).

@item [@i{char-set-spec}]
Matches any of the character set specified by @i{char-set-spec}.
@xref{Character sets}, for the details of @i{char-set-spec}.

@item \s, \d, \w
Matches a whitespace character (@code{char-set:ascii-whitespace}, 
@code{#[\u0009-\u000d ]}),
a digit character(@code{char-set:ascii-digit}, @code{#[0-9])}, or
a word-constituent character (@code{char-set:ascii-word}, @code{#[A-Za-z0-9_]}),
respectively.
Note that they don't include characters outside ASCII range.

Can be used both inside and outside of character set.

@item \S, \D, \W
Matches the complement character set of @code{\s}, @code{\d} and
@code{\w}, respectively.

@item ^, $
Beginning and end of string assertion, when appears at the beginning
or end of the pattern, or optionally, beginning and end of line in
multi-line mode.

These characters loses special meanings and matches the characters
themselves if they appear in the position
other than the beginning of the pattern (for @code{^}) or the end
(for @code{$}).  For the sake of recognizing those characters,
lookahead/lookbehind
assertions (@code{(?=...)}, @code{(?!...)}, @code{(?<=...)},
@code{(?<!...)}) and atomic clustering (@code{(?>...)}) are
treated as if they are a whole pattern.  That is, @code{^} at the
beginning of those groupings are beginning-of-string assertion
no matter where these group appear in the containing regexp.
So as @code{$} at the end of these groupings.

@item \b, \B
Word boundary and non word boundary assertion, respectively.
That is, @code{\b} matches an empty string between
word-constituent character and non-word-constituent character,
and @code{\B} matches an empty string elsewhere.

@item \;
@itemx \"
@itemx \#
These are the same as @code{;}, @code{"}, and @code{#}, respectively,
and can be used to avoid confusing Emacs or other syntax-aware editors
that are not familiar with Gauche's extension.

@item (?=@i{pattern})
@itemx (?!@i{pattern})
Positive/negative lookahead assertion.
Match succeeds if @i{pattern} matches (or does not match)
the input string from the current position, but this doesn't
move the current position itself, so that the following
regular expression is applied again from the current position.

For example, the following expression matches strings
that might be a phone number, except the numbers in Japan
(i.e. ones that begin with "81").

@example
\+(?!81)\d@{9,@}
@end example

@item (?<=@i{pattern})
@itemx (?<!@i{pattern})
Positive/negative lookbehind assertion.
If the input string immediately before the current
input position matches @var{pattern}, this pattern
succeeds or fails, respectively.   Like lookahead
assertion, the input position isn't changed.

Internally, this match is tried by reversing
@var{pattern} and applies it to the backward
of input character sequence.  So you can
write any regexp in @var{pattern}, but if the
submatches depend on the matching order,
you may get different submatches from when
you match @var{pattern} from left to right.

@item (?>@i{pattern})
Atomic clustering.  Once @i{pattern} matches,
the match is fixed; even if the following pattern fails,
the engine won't backtrack to try the
alternative match in @i{pattern}.

@item @i{re}*+
@itemx @i{re}++
@itemx @i{re}?+
They are the same as (?>@i{re}*), (?>@i{re}+), (?>@i{re}?), respectively.

@item (?@i{test-pattern} @i{then-pattern})
@itemx (?@i{test-pattern} @i{then-pattern}|@i{else-pattern})
Conditional matching.   If @var{test-pattern} counts
true, @var{then-pattern} is tried; otherwise
@var{else-pattern} is tried when provided.

@var{test-pattern} can be either one of the following:

@table @code
@item (@i{integer})
Backreference.  If @var{integer}-th capturing group has a match,
this test counts true.

@item (?=@i{pattern})
@itemx (?!@i{pattern})
Positive/negative lookahead assertion.  It tries @var{pattern}
from the current input position without consuming input,
and if the match succeeds or fails, respectively, this
test counts true.

@item (?<=@i{pattern})
@itemx (?<!@i{pattern})
Positive/negative lookbehind assertion.  It tries @var{pattern}
backward from the left size of the current input position,
and if the match succeeds or fails, respectively, this
test counts true.
@end table
@end table

@node Using regular expressions, Inspecting and assembling regular expressions, Regular expression syntax, Regular expressions
@subsection Using regular expressions
@c NODE 正規表現を使う

@subsubheading Regexp object and rxmatch object

@deftp {Builtin Class} <regexp>
@clindex regexp
Regular expression object.  You can construct a regexp object
from a string by @code{string->regexp} or @code{sre->regexp}
at run time.  Gauche also
has a special syntax to denote regexp literals, which construct
regexp object at loading time.

Gauche's regexp engine is fully aware of multibyte characters.
@end deftp

@deftp {Builtin Class} <regmatch>
@clindex regmatch
Regexp match object.  A regexp matcher @code{rxmatch} returns
this object if match.  This object contains all the information
about the match, including submatches.

The advantage of using match object, rather than substrings or
list of indices, is efficiency.  The regmatch object keeps internal
state of match, and computes indices and/or substrings only when
requested.  This is particularly effective for multibyte strings,
for index access is slow on them.
@end deftp

@defun string->regexp string :key case-fold multi-line
Takes @var{string} as a regexp specification, and constructs
an instance of @code{<regexp>} object.

If a true value is given to the keyword argument @var{case-fold},
the created regexp object becomes case-folding regexp.
(See the above explanation about case-folding regexp).

If a true value is given to the keyword argument @var{multi-line},
@code{^} and @code{$} will assert the beginning and end of line in
addition to beginning and end of string. Popular line terminators (LF
only, CRLF and CR only) are recognized.
@end defun

@defun sre->regexp sre :key multi-line
Takes a scheme regexp @var{sre} and returns a @code{<regexp>} object. The
zero-th group is always captured.

If a false value is given to the keyword argument @var{multi-line},
which is the default,
@code{bol} and @code{eol} behave like @code{bos} and @code{eos}
(i.e. only match at the beginning or end of string).
@end defun

@defun regexp? @var{obj}
Returns true iff @var{obj} is a regexp object.
@end defun

@defun regexp->string @var{regexp}
Returns a source string describing the regexp @var{regexp}.
The returned string is immutable.
@end defun

@defun regexp->sre @var{regexp}
Returns a scheme regexp (SRE) describing the regexp @var{regexp}.
@xref{R7RS regular expressions}, for the details of SRE.
@end defun

@defun regexp-num-groups regexp
@defunx regexp-named-groups regexp
Queries the number of capturing groups, and an alist of named capturing
groups, in the given @var{regexp}, respectively.

The number of capturing groups corresponds to the number of matches
returned by @code{rxmatch-num-matches}.  Note that the entire regexp
forms a group, so the number is always positive.

The alist returned from @code{regexp-named-groups} has the group name
(symbol) in @code{car}, and its subgroup number in @code{cdr}.
Note that the order of groups in the alist isn't fixed.

@example
(regexp-num-groups #/abc(?<foo>def)(ghi(?<bar>jkl)(mno))/)
  @result{} 5
(regexp-named-groups #/abc(?<foo>def)(ghi(?<bar>jkl)(mno))/)
  @result{} ((bar . 3) (foo . 1))
@end example
@end defun


@subsubheading Trying a match

@defun rxmatch regexp string :optional start end
@var{Regexp} is a regular expression object.
A string @var{string} is matched by
@var{regexp}.  If it matches, the function returns a @code{<regmatch>}
object.  Otherwise it returns @code{#f}.

If @var{start} and/or @var{end} are given, only the substring between
@var{start} (inclusive) and @var{end} (exclusive) is searched.

This is called @code{match}, @code{regexp-search} or @code{string-match}
in some other Scheme implementations.

Internally, Gauche uses backtracking for regexp match.
When regexp has multiple match possibilities, Gauche saves
an intermediate result in a stack and try one choice, and if it fails
try another.  Depending on regexp, the saved results may grow linear
to the input.  Gauche allocates a fixed amount of memory for that,
and if there are too many saved results, you'll get the following
error:

@example
ERROR: Ran out of stack during matching regexp #/.../. Too many retries?
@end example

If you get this error, consider using hybrid parsing approach.
Our regexp engine isn't made to do everything-in-one-shot parsing;
in most cases, the effect of complex regexp can be achieved better
with more powerful grammar than regular grammar.

To apply the match repeatedly on the input string, or to match
from the input stream (such as the data from the port),
you may want to check @code{grxmatch} in @code{gauche.generator}
(@pxref{Generator operations}).
@end defun

@deffn {Generic application} @var{regexp} @var{string}
A regular expression object can be applied directly to the string.
This works the same as @code{(rxmatch @var{regexp} @var{string})},
but allows shorter notation.   @xref{Applicable objects}, for
generic mechanism used to implement this.
@end deffn

@subsubheading Accessing the match result

@defun rxmatch-start match :optional (i 0)
@defunx rxmatch-end match :optional (i 0)
@defunx rxmatch-substring match :optional (i 0)
@var{Match} is a match object returned by @code{rxmatch}.
If @var{i} equals to zero, the functions return
start, end or the substring of entire match, respectively.
With positive integer @var{I}, it returns those of @var{I}-th
submatches.  It is an error to pass other values to @var{I}.

It is allowed to pass @code{#f} to @var{match} for convenience.
The functions return @code{#f} in such case.

These functions correspond to scsh's @code{match:start}, @code{match:end}
and @code{match:substring}.
@end defun

@defun rxmatch-after match :optional (i 0)
@defunx rxmatch-before match :optional (i 0)
Returns substring of the input string after or before @var{match}.
If optional argument is given, the @var{i}-th submatch is used
(0-th submatch is the entire match).

@example
(define match (rxmatch #/(\d+)\.(\d+)/ "pi=3.14..."))

(rxmatch-after match) @result{} "..."
(rxmatch-after match 1) @result{} ".14..."

(rxmatch-before match) @result{} "pi="
(rxmatch-before match 2) @result{} "pi=3."
@end example
@end defun

@defun rxmatch-substrings match :optional start end
@defunx rxmatch-positions match :optional start end
Retrieves multiple submatches (again, 0-th match is the entire match),
in substrings and in a cons of start and end position, respectively.

@example
(rxmatch-substrings (#/(\d+):(\d+):(\d+)/ "12:34:56"))
  @result{} ("12:34:56" "12" "34" "56")

(rxmatch-positions (#/(\d+):(\d+):(\d+)/ "12:34:56"))
  @result{} ((0 . 8) (0 . 2) (3 . 5) (6 . 8))
@end example

For the convenience, you can pass @code{#f} to @var{match}; those
procedures returns @code{()} in that case.

The optional @var{start} and @var{end} arguments specify the
range of submatch index.  If omitted, @var{start} defaults to 0 and
@var{end} defaults to @code{(rxmatch-num-matches match)}.
For example, if you don't need the whole match, you can give @code{1}
to @var{start} as follows:

@example
(rxmatch-substrings (#/(\d+):(\d+):(\d+)/ "12:34:56") 1)
  @result{} ("12" "34" "56")
@end example
@end defun


@defun rxmatch->string regexp string :optional selector @dots{}
A convenience procedure to match a string to the given regexp,
then returns the matched substring, or @code{#f} if it doesn't match.

If no @var{selector} is given, it is the same as this:

@example
(rxmatch-substring (rxmatch @var{regexp} @var{string}))
@end example

If an integer is given as a selector, it returns the substring
of the numbered submatch.

If a symbol @code{after} or @code{before} is given, it returns
the substring after or before the match.  You can give these symbols
and an integer to extract a substring before or after the numbered
submatch.

@example
gosh> (rxmatch->string #/\d+/ "foo314bar")
"314"
gosh> (rxmatch->string #/(\w+)@@([\w.]+)/ "foo@@example.com" 2)
"example.com"
gosh> (rxmatch->string #/(\w+)@@([\w.]+)/ "foo@@example.com" 'before 2)
"foo@@"
@end example
@end defun

@deffn {Generic application} @var{regmatch} :optional @var{index}
@deffnx {Generic application} @var{regmatch} @code{'before} :optional @var{index}
@deffnx {Generic application} @var{regmatch} @code{'after} :optional @var{index}
A regmatch object can be applied directly to the integer index,
or a symbol @code{before} or @code{after}.
They works the same as @code{(rxmatch-substring @var{regmatch} @var{index})},
@code{(rxmatch-before @var{regmatch})}, and
@code{(rxmatch-after @var{regmatch})}, respectively.
This allows shorter notation.  @xref{Applicable objects}, for
generic mechanism used to implement this.

@example
(define match (#/(\d+)\.(\d+)/ "pi=3.14..."))

  (match)           @result{} "3.14"
  (match 1)         @result{} "3"
  (match 2)         @result{} "14"

  (match 'after)    @result{} "..."
  (match 'after 1)  @result{} ".14..."

  (match 'before)   @result{} "pi="
  (match 'before 2) @result{} "pi=3."

(define match (#/(?<integer>\d+)\.(?<fraction>\d+)/ "pi=3.14..."))

  (match 1)         @result{} "3"
  (match 2)         @result{} "14"

  (match 'integer)  @result{} "3"
  (match 'fraction) @result{} "14"

  (match 'after 'integer)   @result{} ".14..."
  (match 'before 'fraction) @result{} "pi=3."
@end example
@end deffn

@defun rxmatch-num-matches match
@defunx rxmatch-named-groups match
Returns the number of matches, and an alist of named groups and whose
indices, in @var{match}.
This corresponds @code{regexp-num-groups} and @code{regexp-named-groups}
on a regular expression that has been used to generate @var{match}.
These procedures are useful to inspect @var{match} object without having
the original regexp object.

The number of matches includes the "whole match", so it is always a positive
integer for a @code{<regmatch>} object.  The number also includes
the submatches that don't have value (see the examples below).
The result of @code{rxmatch-named-matches} also includes all the
named groups in the original regexp, not only the matched ones.

For the convenience, @code{rxmatch-num-matches} returns 0
and @code{rxmatch-named-groups} returns @code{()}
if @var{match} is @code{#f}.

@example
(rxmatch-num-matches (rxmatch #/abc/ "abc")) @result{} 1
(rxmatch-num-matches (rxmatch #/(a(.))|(b(.))/ "ba")) @result{} 5
(rxmatch-num-matches #f) @result{} 0

(rxmatch-named-groups
 (rxmatch #/(?<h>\d\d):(?<m>\d\d)(:(?<s>\d\d))?/ "12:34"))
 @result{} ((s . 4) (m . 2) (h . 1))
@end example
@end defun

@subsubheading Convenience utilities

@defun regexp-replace regexp string substitution
@defunx regexp-replace-all regexp string substitution
Replaces the part of @var{string} that matched to @var{regexp}
for @var{substitution}.  @code{regexp-replace} just replaces
the first match of @var{regexp}, while @code{regexp-replace-all}
repeats the replacing throughout entire @var{string}.

@var{substitution} may be a string or a procedure.  If it is a string,
it can contain references to the submatches by
digits preceded by a backslash (e.g. @code{\2})
or the named submatch reference (e.g. @code{\k<@var{name}>}.
@code{\0} refers to the
entire match.  Note that you need two backslashes to include
backslash character in the literal string; if you want to include a backslash
character itself in the @var{substitution}, you need four backslashes.

@example
(regexp-replace #/def|DEF/ "abcdefghi" "...")
  @result{} "abc...ghi"
(regexp-replace #/def|DEF/ "abcdefghi" "|\\0|")
  @result{} "abc|def|ghi"
(regexp-replace #/def|DEF/ "abcdefghi" "|\\\\0|")
  @result{} "abc|\\0|ghi"
(regexp-replace #/c(.*)g/ "abcdefghi" "|\\1|")
  @result{} "ab|def|hi"
(regexp-replace #/c(?<match>.*)g/ "abcdefghi" "|\\k<match>|")
  @result{} "ab|def|hi"
@end example

If @var{substitution} is a procedure, for every match in @var{string}
it is called with one argument, regexp-match object.  The returned
value from the procedure is inserted to the output string using
@code{display}.

@example
(regexp-replace #/c(.*)g/ "abcdefghi"
                (lambda (m)
                  (list->string
                   (reverse
                    (string->list (rxmatch-substring m 1))))))
 @result{} "abfedhi"
@end example

Note: @code{regexp-replace-all} applies itself recursively to the remaining
of the string after match.  So the beginning of string assertion
in @var{regexp} doesn't only mean the beginning of input string.

Note: If you want to operate on multiple matches in the string
instead of replacing it, you can use @code{lrxmatch} in @code{gauche.lazy}
module or @code{grxmatch} in @code{gauche.generator} module.  Both can
match a regexp @emph{repeatedly} and @emph{lazily} to the given string,
and @code{lrxmatch}
returns a lazy sequence of @code{regmatch}es, while @code{grxmatch}
returns a generator that yields @code{regmatch}es.

@example
(map rxmatch-substring (lrxmatch #/\w+/ "a quick brown fox!?"))
 @result{} ("a" "quick" "brown" "fox")
@end example
@end defun

@defun regexp-replace* string rx1 sub1 rx2 sub2 @dots{}
@defunx regexp-replace-all* string rx1 sub1 rx2 sub2 @dots{}
First applies @code{regexp-replace} or @code{regexp-replace-all} to
@var{string} with a regular expression @var{rx1} substituting for
@var{sub1}, then applies the function on the result string
with a regular expression @var{rx2} substituting for @var{sub2}, and
so on.  These functions are handy when you want to apply
multiple substitutions sequentially on a string.
@end defun

@defun regexp-quote string
Returns a string with the characters that are special to regexp escaped.

@example
(regexp-quote "[2002/10/12] touched foo.h and *.c")
 @result{} "\\[2002/10/12\\] touched foo\\.h and \\*\\.c"
@end example
@end defun


In the following macros, @var{match-expr} is an expression
which produces a match object or @code{#f}. Typically
it is a call of @code{rxmatch}, but it can be any expression.

@defmac rxmatch-let match-expr (var @dots{}) form @dots{}

Evaluates @var{match-expr}, and if matched, binds @var{var @dots{}}
to the matched strings, then evaluates @var{form}s.
The first @var{var} receives the entire match, and subsequent
variables receive submatches.  If the number of submatches are
smaller than the number of variables to receive them, the rest
of variables will get @code{#f}.

It is possible to put @code{#f} in variable position, which says
you don't care that match.

@example
(rxmatch-let (rxmatch #/(\d+):(\d+):(\d+)/
                      "Jan  1 23:59:58, 2001")
   (time hh mm ss)
  (list time hh mm ss))
 @result{} ("23:59:58" "23" "59" "58")

(rxmatch-let (rxmatch #/(\d+):(\d+):(\d+)/
                      "Jan  1 23:59:58, 2001")
   (#f hh mm)
  (list hh mm))
 @result{} ("23" "59")
@end example

This macro corresponds to scsh's @code{let-match}.
@end defmac

@defmac rxmatch-if match-expr (var @dots{}) then-form else-form
Evaluates @var{match-expr}, and if matched, binds @var{var} @dots{}
to the matched strings and evaluate @var{then-form}.
Otherwise evaluates @var{else-form}.
The rule of binding @var{var}s is the same as @code{rxmatch-let}.

@example
(rxmatch-if (rxmatch #/(\d+:\d+)/ "Jan 1 11:22:33")
    (time)
  (format #f "time is ~a" time)
  "unknown time")
 @result{} "time is 11:22"

(rxmatch-if (rxmatch #/(\d+:\d+)/ "Jan 1 11-22-33")
    (time)
  (format #f "time is ~a" time)
  "unknown time")
 @result{} "unknown time"
@end example

This macro corresponds to scsh's @code{if-match}.
@end defmac

@defmac rxmatch-cond clause @dots{}
Evaluate condition in @var{clause}s one by one.
If a condition of a clause satisfies, rest portion of the clause
is evaluated and becomes the result of @code{rxmatch-cond}.
@var{Clause} may be one of the following pattern.

@table @code
@item (@var{match-expr} (@var{var} @dots{}) @var{form} @dots{})
Evaluate @var{match-expr}, which may return a regexp match
object or @code{#f}.  If it returns a match object, the matches
are bound to @var{var}s, like @var{rxmatch-let}, and @var{form}s
are evaluated.

@item (test @var{expr} @var{form} @dots{})
Evaluates @var{expr}.  If it yields true, evaluates @var{form}s.

@item (test @var{expr} => @var{proc})
Evaluates @var{expr} and if it is true,
calls @var{proc} with the result of @var{expr} as the only argument.

@item (else @var{form} @dots{})
If this clause exists, it must be the last clause.
If other clauses fail, @var{form}s are evaluated.
@end table

If no @code{else} clause exists, and all the other clause fail,
an undefined value is returned.

@example
;; @r{parses several possible date format}
(define (parse-date str)
  (rxmatch-cond
    ((rxmatch #/^(\d\d?)\/(\d\d?)\/(\d\d\d\d)$/ str)
        (#f mm dd yyyy)
      (map string->number (list yyyy mm dd)))
    ((rxmatch #/^(\d\d\d\d)\/(\d\d?)\/(\d\d?)$/ str)
        (#f yyyy mm dd)
      (map string->number (list yyyy mm dd)))
    ((rxmatch #/^\d+\/\d+\/\d+$/ str)
        (#f)
     (errorf "ambiguous: ~s" str))
    (else (errorf "bogus: ~s" str))))

(parse-date "2001/2/3") @result{} (2001 2 3)
(parse-date "12/25/1999") @result{} (1999 12 25)
@end example

This macro corresponds to scsh's @code{match-cond}.
@end defmac

@defmac rxmatch-case string-expr clause @dots{}
@var{String-expr} is evaluated, and @var{clause}s are interpreted
one by one.  A @var{clause} may be one of the following pattern.

@table @code
@item (@var{re} (@var{var} @dots{}) @var{form} @dots{})
@var{Re} must be a literal regexp object (@pxref{Regular expressions}).
If the result of @var{string-expr} matches @var{re},
the match result is bound to @var{var}s
and @var{form}s are evaluated, and @code{rxmatch-case} returns
the result of the last @var{form}.

If @var{re} doesn't match the result of @var{string-expr},
@var{string-expr} yields non-string value, the interpretation proceeds
to the next clause.

@item (test @var{proc} @var{form} @dots{})
A procedure @var{proc} is applied on the result of @var{string-expr}.
If it yields true value, @var{form}s are evaluated, and
@code{rxmatch-case} returns the result of the last @var{form}.

If @var{proc} yields @code{#f}, the interpretation proceeds
to the next clause.

@item (test @var{proc} => @var{proc2})
A procedure @var{proc} is applied on the result of @var{string-expr}.
If it yields true value, @var{proc2} is applied on the result,
and its result is returned as the result of @code{rxmatch-case}.

If @var{proc} yields @code{#f}, the interpretation proceeds
to the next clause.

@item (else @var{form} @dots{})
This form must appear at the end of @var{clause}s, if any.
If other clauses fail, @var{form}s are evaluated,
and the result of the last @var{form} becomes the result of
@code{rxmatch-case}.

@item (else => @var{proc})
This form must appear at the end of @var{clause}s, if any.
If other clauses fail, @var{proc} is evaluated, which should
yield a procedure taking one argument.  The value of @var{string-expr}
is passed to @var{proc}, and its return values become the
return values of @code{rxmatch-case}.
@code{rx}
@end table

If no @code{else} clause exists, and all other clause fail,
an undefined value is returned.

The @code{parse-date} example above becomes simpler if you use
@code{rxmatch-case}

@example
(define (parse-date2 str)
  (rxmatch-case str
    (test (lambda (s) (not (string? s))) #f)
    (#/^(\d\d?)\/(\d\d?)\/(\d\d\d\d)$/ (#f mm dd yyyy)
     (map string->number (list yyyy mm dd)))
    (#/^(\d\d\d\d)\/(\d\d?)\/(\d\d?)$/ (#f yyyy mm dd)
     (map string->number (list yyyy mm dd)))
    (#/^\d+\/\d+\/\d+$/                (#f)
     (errorf "ambiguous: ~s" str))
    (else (errorf "bogus: ~s" str))))
@end example
@end defmac

@node Inspecting and assembling regular expressions,  , Using regular expressions, Regular expressions
@subsection Inspecting and assembling regular expressions
@c NODE 正規表現の調査と合成

When Gauche reads a string representation of regexp, first it parses
the string and construct an abstract
syntax tree (AST), performs some optimizations on it,
then compiles it into an instruction sequence to be
executed by the regexp engine.

The following procedures expose this process to
user programs.  It may be easier for programs to
manipulate an AST than a string representation.

@defun regexp-parse string :key case-fold multi-line
Parses a string specification of regexp in @var{string}
and returns its AST, represented in S-expression.
See below for the spec of AST.

When a true value is given to the keyword argument @var{case-fold},
returned AST will match case-insensitively.
(Case insensitive regexp is handled in parser level,
not by the engine).
@end defun

@defun regexp-parse-sre sre
Parses @var{sre} as a Scheme Regular Expression (SRE) as described in
SRFI-115 and returns its AST.
@xref{R7RS regular expressions}
@pxref{R7RS regular expressions}.
@end defun

@defun regexp-optimize ast
Performs some rudimental optimization on the regexp AST,
returning regexp AST.

Currently it only optimizes some trivial cases.  The plan is
to make it cleverer in future.
@end defun

@defun regexp-compile ast :key multi-line
Takes a regexp @var{ast} and returns a regexp object.
Currently the outermost form of @var{ast} must be
the zero-th capturing group.  (That is, @var{ast}
should have the form @code{(0 #f @var{x} @dots{})}.)
The outer grouping is always added
by @code{regexp-parse} to capture the entire regexp.

Note: The function does some basic check to see the given AST
is valid, but it may not reject invalid ASTs.  In such case,
the returned regexp object doesn't work properly.  It is
caller's responsibility to provide a properly constructed AST.
(Even if it rejects an AST, error messages are often
incomprehensible.  So, don't use this procedure as a AST validness checker.)
@end defun

@defun regexp-ast regexp
Returns AST used for the regexp object @var{regexp}.
@end defun

@defun regexp-unparse ast :key (on-error :error)
From the regexp's @var{ast}, reconstruct the string representation
of the regexp.  The keyword argument @var{on-error} can be
a keyword @code{:error} (default) or @code{#f}.  If it's the former,
an error is signaled when @var{ast} isn't valid regexp AST.
If it's the latter, @code{regexp-unparse} just returns @code{#f}.
@end defun

This is the structure of AST.  Note that this is originally
developed only for internal use, and not very convenient to manipulate
from the code (e.g. if you insert or delete a subtree, you have to
renumber capturing groups to make them consistent.) 

@smallexample
<ast> : <clause>   ; special clause
      | <item>     ; matches <item>

<item> : <char>       ; matches char
       | <char-set>   ; matches char set
       | (comp . <char-set>) ; matches complement of char set
       | any          ; matches any char
       | bos | eos    ; beginning/end of string assertion
       | bol | eol    ; beginning/end of line assertion
       | bow | eow | wb | nwb ; word-boundary/negative word boundary assertion
       | bog | eog    ; beginning/end of grapheme assertion

<clause> : (seq <ast> ...)       ; sequence
       | (seq-uncase <ast> ...)  ; sequence (case insensitive match)
       | (seq-case <ast> ...)    ; sequence (case sensitive match)
       | (alt <ast> ...)         ; alternative
       | (rep <m> <n> <ast> ...) ; repetition at least <m> up to <n> (greedy)
                               ; <n> may be `#f'
       | (rep-min <m> <n> <ast> ...)
                               ; repetition at least <m> up to <n> (lazy)
                               ; <n> may be `#f'
       | (rep-while <m> <n> <ast> ...)
                               ; like rep, but no backtrack
       | (<integer> <symbol> <ast> ...)
                               ; capturing group.  <symbol> may be #f.
       | (cpat <condition> (<ast> ...) (<ast> ...))
                               ; conditional expression
       | (backref . <integer>) ; backreference by group number
       | (backref . <symbol>)  ; backreference by name
       | (once <ast> ...)      ; standalone pattern.  no backtrack
       | (assert . <asst>)     ; positive lookahead assertion
       | (nassert . <asst>)    ; negative lookahead assertion

<condition> : <integer>     ; (?(1)yes|no) style conditional expression
       | (assert . <asst>)  ; (?(?=condition)...) or (?(?<=condition)...)
       | (nassert . <asst>) ; (?(?!condition)...) or (?(?<!condition)...)

<asst> : <ast> ...
       | ((lookbehind <ast> ...))
@end smallexample

@c ----------------------------------------------------------------------
@node Vector family, Dictionaries, Regular expressions, Core library
@section Vector family
@c NODE ベクタの仲間

Vectors are fixed-size, O(1) accessible sequence of values.
Scheme has traditionally offered a vector of arbitrary objects, which is
described in @ref{Vectors}.

In R7RS-large, there're also homogeneous numeric vectors (uvectors),
which can contain fixed range of numeric objects efficiently.
We explain them in @ref{Uniform vectors}.

Gauche also supports bitvectors, which can contain sequence of bits.
@xref{Bitvectors}, for the details.

Finally, weak vectors are a vector of arbitrary objects using
weak pointers.  @xref{Weak vectors}.

@menu
* Vectors::
* Uniform vectors::
* Bitvectors::
* Weak vectors::
@end menu

@node Vectors, Uniform vectors, Vector family, Vector family
@subsection Vectors
@c NODE ベクタ

@deftp {Builtin Class} <vector>
@clindex vector
A vector is a simple 1-dimensional array of Scheme objects.
You can access its element by index in constant time.
Once created, a vector can't be resized.

Class @code{<vector>} inherits @code{<sequence>} and
you can use various generic functions such as @code{map} and @code{fold}
on it.   @xref{Collection framework}, and @xref{Sequence framework}.

If you keep only a homogeneous numeric type, you may be able
to use SRFI-4 homogeneous vectors (@pxref{Homogeneous vectors}).

R7RS defines bytevectors; in Gauche, they're just @code{u8vector}s
in @code{gauche.uvector} module (r7rs modules defines aliases.
@pxref{R7RS base library}).

@xref{R7RS vectors}, for additional operations on vectors.
@end deftp

@defun vector? obj
[R7RS base]
Returns @code{#t} if @var{obj} is a vector, @code{#f} otherwise.
@end defun

@defun make-vector k :optional fill
[R7RS base]
Creates and returns a vector with length @var{k}.
If optional argument @var{fill} is given, each element of the vector
is initialized by it.  Otherwise, the initial value of each element
is undefined.
@end defun

@defun vector obj @dots{}
[R7RS base]
Creates a vector whose elements are @var{obj} @dots{}.
@end defun

@defun vector-tabulate len proc
Creates a vector of length @var{len}, 
initializing @var{i}-th
element of which by @code{(@var{proc} @var{i})}
for all @var{i} between @code{0} and @var{len}

@example
(vector-tabulate 5 (^x (* x x)))
  @result{} #(0 1 4 9 16)
@end example
@end defun

@defun vector-length vector
[R7RS base]
Returns the length of a vector @var{vector}.

With @code{gauche.collection} module,
you can also use a method @code{size-of}.
@end defun

@defun vector-ref vector k :optional fallback
[R7RS+]
Returns @var{k}-th element of vector @var{vector}.

By default, @code{vector-ref} signals an error if @var{k} is
negative, or greater than or equal to the length of @var{vector}.
However, if an optional argument @var{fallback} is given,
it is returned for such case.  This is an extension of Gauche.

With @code{gauche.sequence} module,
you can also use a method @code{ref}.
@end defun

@defun vector-set! vector k obj
[R7RS base]
Sets @var{k}-th element of the vector @var{vector} to @var{obj}.
It is an error if @var{k} is negative or greater than or equal to the
length of @var{vector}.

With @code{gauche.sequence} module, you can also use
a setter method of @code{ref}.
@end defun

@defun vector->list vector :optional start end
@defunx list->vector list :optional start end
[R7RS+]
Converts a vector to a list, or vice versa.

The optional @var{start} and @var{end} arguments
limit the range of the source.
(R7RS don't define @var{start} and @var{end} arguments
for @code{list->vector}.)
@example
(vector->list '#(1 2 3 4 5))     @result{} (1 2 3 4 5)
(list->vector '(1 2 3 4 5))      @result{} #(1 2 3 4 5)
(vector->list '#(1 2 3 4 5) 2 4) @result{} (3 4)
(list->vector (circular-list 'a 'b 'c) 1 6)
  @result{} #(b c a b c)
@end example

With @var{gauche.collection} module, you can use
@code{(coerce-to <list> @var{vector})} and
@code{(coerce-to <vector> @var{list})} as well.
@end defun

@defun reverse-list->vector list :optional start end
[R7RS vector]
Without optional arguments, it returns the same thing as
@code{(list->vector (reverse list))}, but does not
allocate the intermediate list.   The optional @var{start} and
@var{end} argument limits the range of the input list.
@example
(reverse-list->vector '(a b c d e f g) 1 5)
  @result{} #(e d c b)
@end example
@end defun

@defun vector->string vector :optional start end
@defunx string->vector string :optional start end
[R7RS base]
Converts a vector of characters to a string, or vice versa.
It is an error to pass a vector that contains other than characters
to @code{vector->string}.

The optional @var{start} and @var{end} arguments
limit the range of the source.
@example
(vector->string '#(#\a #\b #\c #\d #\e))     @result{} "abcde"
(string->vector "abcde")                     @result{} #(#\a #\b #\c #\d #\e)
(vector->string '#(#\a #\b #\c #\d #\e) 2 4) @result{} ("cd")
@end example

With @var{gauche.collection} module, you can use
@code{(coerce-to <string> @var{vector})} and
@code{(coerce-to <vector> @var{string})} as well.
@end defun

@defun vector-fill! vector fill :optional start end
[R7RS base]
Sets all elements in a vector @var{vector} to @var{fill}.

Optional @var{start} and @var{end} limits the range
of effect between @var{start}-th index (inclusive) to
@var{end}-th index (exclusive).  @var{Start} defaults to
zero, and @var{end} defaults to the length of @var{vector}.
@end defun

@defun vector-copy vector :optional start end fill
[R7RS base]
Copies a vector @var{vector}.  Optional @var{start} and @var{end}
arguments can be used to limit the range of @var{vector} to be copied.
If the range specified by @var{start} and @var{end} falls outside of
the original @var{vector}, the @var{fill} value is used to fill
the result vector.

@example
(vector-copy '#(1 2 3 4 5))     @result{} #(1 2 3 4 5)
(vector-copy '#(1 2 3 4 5) 2 4) @result{} #(3 4)
(vector-copy '#(1 2 3 4 5) 3 7 #f) @result{} #(4 5 #f #f)
@end example
@end defun

@defun vector-copy! target tstart source :optional sstart send
[R7RS base]
Copies the content of @var{source} vector into the @var{target} vector
starting from @var{tstart} in the target.  The @var{target} vector
must be mutable.
Optional @var{sstart} and @var{send} limits the range of source
vector.

@example
(rlet1 v (vector 'a 'b 'c 'd 'e)
  (vector-copy! v 2 '#(1 2)))
  @result{} #(a b 1 2 e)
(rlet1 v (vector 'a 'b 'c 'd 'e)
  (vector-copy! v 2 '#(1 2 3 4) 1 3))
  @result{} #(a b 2 3 e)
@end example

An error is raised if the portion to be copied is greater than
the room in the target (that is, between @var{tstart} to the end).

It is ok to pass the same vector to @var{target} and @var{source};
it always works even if the regions of source and destination are
overlapping.
@end defun

@defun vector-append vec @dots{}
[R7RS base]
Returns a newly allocated vector whose contents are concatenation
of elements of @var{vec} in order.

@example
(vector-append '#(1 2 3) '#(a b)) @result{} #(1 2 3 a b)
(vector-append) @result{} #()
@end example
@end defun

@defun vector-map proc vec1 vec2 @dots{}
[R7RS base]
Returns a new vector, @var{i}-th of which is calculated
by applying @var{proc} on the list of each @var{i}-th element
of @var{vec1} @var{vec2} @dots{}.
The length of the result vector is the same as the shortest vector
of the arguments.

@example
(vector-map + '#(1 2 3) '#(4 5 6 7))
 @result{} #(5 7 9)
@end example

The actual order @var{proc} is called is undefined, and may change
in the future versions, so @var{proc} shouldn't use side effects
affected by the order.

Note: If you use @code{gauche.collection}, you can get the same
function by @code{(map-to <vector> proc vec1 vec2 @dots{})}.
@end defun

@defun vector-map-with-index proc vec1 vec2 @dots{}
Like @code{vector-map}, but @var{proc} receives the current index
as the first argument.

@example
(vector-map-with-index list '#(a b c d e) '#(A B C))
 @result{} #((0 a A) (1 b B) (2 c C))
@end example

This is what SRFI-43 calls @code{vector-map}.  @xref{Vector library (Legacy)}.

Note: If you use @code{gauche.collection}, you can get the same
function by @code{(map-to-with-index <vector> proc vec1 vec2 @dots{})}.
@end defun

@defun vector-map! proc vec1 vec2 @dots{}
[R7RS vector]
For each index @var{i}, calls @var{proc} with @var{i}-th index
of @var{vec1} @var{vec2} @dots{}, and set the result back to
@var{vec1}.  The value is calculated up to the minimum
length of input vectors.

@example
(rlet1 v (vector 1 2 3)
  (vector-map! ($ + 1 $) v))
  @result{} #(2 3 4)

(rlet1 v (vector 1 2 3 4)
  (vector-map! + v '#(10 20)))
  @result{} #(11 22 3 4)
@end example
@end defun

@defun vector-map-with-index! proc vec1 vec2 @dots{}
Like @code{vector-map!}, but @var{proc} receives the current
index as the first argument.  This is equivalent to SRFI-43's
@code{vector-map!} (@pxref{Vector library (Legacy)}).

@example
(rlet1 v (vector 'a 'b 'c)
  (vector-map-with-index! list v))
  @result{} #((0 a) (1 b) (2 c))
@end example

@end defun

@defun vector-for-each proc vec1 vec2 @dots{}
[R7RS base]
For all @var{i} below the minimum length of input vectors,
calls @var{proc} with @var{i}-th elements of @var{vec1} @var{vec2}
@dots{}, in increasing order of @var{i}.

@example
(vector-for-each print '#(a b c))
 @result{} @r{prints @code{a}, @code{b} and @code{c}}.
@end example
@end defun

@defun vector-for-each-with-index proc vec1 vec2 @dots{}
Like @code{vector-for-each}, but @var{proc} receives the current index
in the first argument.

This is equivalent to SRFI-43's @code{vector-for-each}.
@xref{Vector library (Legacy)}.
@end defun

@node Uniform vectors, Bitvectors, Vectors, Vector family
@subsection Uniform vectors
@c NODE ユニフォームベクタ

Uniform vectors, or homogeneous numeric vectors, are a special
type of vectors whose elements are of the same numeric type.
It was introduced originally as srfi-4, revised by srfi-160,
and now a part of R7RS large (as @code{scheme.vector.@@}).

The @code{@@} part is actually one of the following tags, indicating
the type of elements:

@table @code
@item u8
Unsigned 8-bit integer - an exact integer between 0 and 255.
@item s8
Signed 8-bit integer - an exact integer between -128 and 127.
@item u16
Unsigned 16-bit integer - an exact integer between 0 and 65535.
@item s16
Signed 16-bit integer - an exact integer between -32678 and 32767.
@item u32
Unsigned 32-bit integer - an exact integer between 0 and 2^32 - 1.
@item s32
Signed 32-bit integer - an exact integer between -(2^31) and 2^31 - 1.
@item u64
Unsigned 64-bit integer - an exact integer between 0 and 2^64 - 1.
@item s64
Signed 64-bit integer - an exact integer between -(2^63) and 2^63 - 1.
@item f16
16-bit floating point number (10-bit mantissa and 5-bit exponent),
as inexact real.
@item f32
IEEE single-precision floating point number
as inexact real.
@item f64
IEEE double-precision floating point number
as inexact real.
@item c32
Inexact complex, consists of a pair of 16-bit floating point numbers.
@item c64
Inexact complex, consists of a pair of IEEE single-precision floating
point numbers.
@item c128
Inexact complex, consists of a pair of IEEE double-precision floating
point numbers.
@end table

There are some advantages of using uniform vectors over normal
(heterogeneous) vectors.  It may be more compact than the normal
vectors.  Some operations (especially Gauche's extension of vector
arithmetic operations) can bypass type check and conversion of
individual elements, thus be more efficient.  And it is much easier
and efficient to communicate with external libraries that require
homogeneous array of numbers; for example, OpenGL binding of Gauche
uses uniform vectors extensively.

Gauche has only a handful primitive operations on uniform vectors
as a built-in, but the @code{gauche.uvector} module, or
@code{scheme.vector.@@} module (@code{(scheme vector @@)} library
in R7RS programs), provide a complehensive set of operations.
@xref{Uniform vector library}, and @pxref{R7RS uniform vectors}.

@subsubheading Uvector classes

@deftp {Abstract Class} <uvector>
The base class of uniform vector classes.  It inherits @code{<sequence>}
(@pxref{Sequence framework}).
@end deftp


@deftp {Builtin Class} <@@vector>
@clindex s8vector
@clindex u8vector
@clindex s16vector
@clindex u16vector
@clindex s32vector
@clindex u32vector
@clindex s64vector
@clindex u64vector
@clindex f16vector
@clindex f32vector
@clindex f64vector
@clindex c32vector
@clindex c64vector
@clindex c128vector
@{@t{gauche.uvector}@}
A class for @@vector, where @code{@@} is one of the uvector tags
(@code{u8}, @code{s8}, @dots{}).
It inherits @code{<uvector>}.

It implements sequence protocol (@pxref{Sequence framework})), 
so you can convert a sequence of
real numbers into a uvector using @code{coerce-to}, 
if every elements is valid for the uvector.

@example
(use gauche.sequence)
(coerce-to <u8vector> '(1 2 3)) @result{} #u8(1 2 3)
@end example
@end deftp

@subsubheading Uvector literals

@deftp {Reader Syntax} @code{#u8(@var{n} @dots{})}
@deftpx {Reader Syntax} @code{#s8(@var{n} @dots{})}
@deftpx {Reader Syntax} @code{#u16(@var{n} @dots{})}
@deftpx {Reader Syntax} @code{#s16(@var{n} @dots{})}
@deftpx {Reader Syntax} @code{#u32(@var{n} @dots{})}
@deftpx {Reader Syntax} @code{#s32(@var{n} @dots{})}
@deftpx {Reader Syntax} @code{#u64(@var{n} @dots{})}
@deftpx {Reader Syntax} @code{#s64(@var{n} @dots{})}
@deftpx {Reader Syntax} @code{#f16(@var{n} @dots{})}
@deftpx {Reader Syntax} @code{#f32(@var{n} @dots{})}
@deftpx {Reader Syntax} @code{#f64(@var{n} @dots{})}
@deftpx {Reader Syntax} @code{#c32(@var{n} @dots{})}
@deftpx {Reader Syntax} @code{#c64(@var{n} @dots{})}
@deftpx {Reader Syntax} @code{#c128(@var{n} @dots{})}
@lxindex #s8
@lxindex #u8
@lxindex #s16
@lxindex #u16
@lxindex #s32
@lxindex #u32
@lxindex #s64
@lxindex #u64
@lxindex #f16
@lxindex #f32
@lxindex #f64
@lxindex #c32
@lxindex #c64
@lxindex #c128
Denotes a literal homogeneous vector.

(Note: R7RS bytevector is the same as u8vector, and can be written
as @code{#u8(@dots{})}.)
@example
#s8(3 -2 4)
#u32(4154 88357 2 323)
#f32(3.14 0.554525 -3.342)
@end example
@end deftp

@subsubheading Uvector generic operations

@defun uvector? obj
Returns @code{#t} iff @var{obj} is one of the uniform vectors.
See below for predicates for specific type of uvector.
@end defun

@defun uvector-length uv
Returns the length (the number of elements) of uvector @var{uv}.
An error is raised if @var{uv} is not a uvector.

Type specific length procedures are provided in @code{scheme.vector.@@}
and @code{gauche.uvector} (@pxref{Uniform vector library}).

To get the size of the binary data the content of the uvector actually
occupies, use @code{uvector-size} in @code{gauche.uvector}.
@end defun

@defun uvector-ref uv k :optional fallback
Generic uvector accessor.  Returns @var{k}-th element of a uniform
vector @var{uv}.  If @var{k} is out-of-range, @var{fallback} is
returned if provided, or an error is thrown otherwise.

This is handy to write a generic code that works on any kind of
uniform vector, but this is slower than the specific versions.
Gauche's compiler recognizes the specific versions of referencer and
generate very efficient code for them, while this generic version
becomes a normal procedure call.   In inner-loop it can make a big
difference.

See below for the type-specific accessors.

@code{(setter uvector-ref)} is @code{uvector-set!}.
@end defun

@defun uvector-set! uv k val :optional clamp
@{@t{gauche.uvector}@}
Generic uvector setter.  Mutate @var{k}-th element of
uvector @var{uv} with @var{val}.
An error is thrown if @var{k} is out-of-range, or @var{uv} is immutable.

Optional @var{clamp} argument specifies the behavior when
@var{val} is out of valid range.  It can be @code{#f} or
one of the symbols @code{low}, @code{high}, or @code{both}.
@xref{Uniform vector library}, for the meanings of the clamp argument.
The default is @code{#f}, which raises an error on out-of-range value.
@end defun


@subsubheading Uvector type-specific operations

Type-specific predicates, accessors and modifiers are provided in the core
library; all the rest are in @code{scheme.vector.@@} or @code{gauche.uvector}
(@pxref{Uniform vector library}).

@deffn {Function} @@vector? obj
@findex s8vector?
@findex u8vector?
@findex s16vector?
@findex u16vector?
@findex s32vector?
@findex u32vector?
@findex s64vector?
@findex u64vector?
@findex f16vector?
@findex f32vector?
@findex f64vector?
@findex c32vector?
@findex c64vector?
@findex c128vector?
[R7RS vector.@@]
@{@t{gauche.uvector}@}
Returns @code{#t} iff @var{obj} is a @@vector, @code{#f} otherwise.
The @code{@@} part is one of the uvector tags (@code{u8} etc.).
@end deffn

@deffn {Function} @@vector-ref vec k :optional fallback
@findex u8vector-ref
@findex s8vector-ref
@findex u16vector-ref
@findex s16vector-ref
@findex u32vector-ref
@findex s32vector-ref
@findex u64vector-ref
@findex s64vector-ref
@findex f16vector-ref
@findex f32vector-ref
@findex f64vector-ref
@findex c32vector-ref
@findex c64vector-ref
@findex c128vector-ref
[R7RS vector.@@]
@{@t{gauche.uvector}@}
Returns the @var{k}-th element of @@vector @var{vec}.
The @code{@@} part is one of the uvector tags (@code{u8} etc.).

If the index @var{k} is out of the valid range, an error is signaled
unless an optional argument @var{fallback} is given; in that case,
@var{fallback} is returned.

Note that the generic function @code{ref} can be used as well,
if you import @code{gauche.collection}.

@example
(u16vector-ref '#u16(111 222 333) 1) @result{} 222

(use gauche.collection)
(ref '#u16(111 222 333) 1) @result{} 222
@end example

Setter of @code{@@vector-ref} is @code{@@vector-set!}.

@example
(use gauche.uvector)
(define v (u8vector 1 2 3))
(set! (u8vector-ref v 1) 99)

v @result{} #u8(1 99 3)
@end example
@end deffn

@deffn {Function} @@vector-set! vec k n :optional clamp
@findex u8vector-set!
@findex s8vector-set!
@findex u16vector-set!
@findex s16vector-set!
@findex u32vector-set!
@findex s32vector-set!
@findex u64vector-set!
@findex s64vector-set!
@findex f16vector-set!
@findex f32vector-set!
@findex f64vector-set!
@findex c32vector-set!
@findex c64vector-set!
@findex c128vector-set!
[R7RS vector.@@]
@{@t{gauche.uvector}@}
Sets a number @var{n} to the @var{k}-th element of @@vector @var{vec}.
The @code{@@} part is one of the uvector tags (@code{u8} etc.).

Optional @var{clamp} argument specifies the behavior when
@var{n} is out of valid range.   It can be @code{#f} or
one of the symbols @code{low}, @code{high}, or @code{both}.
@xref{Uniform vector library}, for the meanings of the clamp argument.
The default is @code{#f}, which raises an error on out-of-range value.

Note that the setter of the generic function @code{ref} can be used as well,
if you import @code{gauche.collection}.
@example
(let ((v (s32vector -439 852 8933)))
  (s32vector-set! v 1 4)
  v)
 @result{} #s32vector(-439 4 8933)

(use gauche.collection)
(let ((v (s32vector -439 852 8933)))
  (set! (ref v 1) 4)
  v)
 @result{} #s32vector(-439 4 8933)
@end example
@end deffn


@node Bitvectors, Weak vectors, Uniform vectors, Vector family
@subsection Bitvectors
@c NODE ビットベクタ

A bitvector is a sequence of bits.  Each bit can be considered either
an exact integer 0/1, or a boolean values @code{#f}/@code{#t}.
In the former view, it is similar to a uniform vector, but it has the 
interface sufficiently different from uvectors and we provided it as
a disjoint type.

Gauche provides a handful of procedures in the core.
SRFI-178 provides comprehensive bitvector library.
@xref{Bitvector library}, for the details.

@deftp {Builtin class} <bitvector>
@clindex bitvector
Bitvector class.  Inherits @code{<sequence>}, so generic sequence opertaions
can be used.  (Generic @code{ref} uses @code{bitvector-ref/int}, for
it matches the external representation of a bitvector.)
@end deftp

@deftp {Reader Syntax} @code{#*@var{b}@dots{}}
@lxindex #*
[SRFI-178]
A bitvector literal is @code{#*} followed by zero or more binary digits
@code{0} or @code{1}.

@example
#*10010010           ; bitvector of length 8
#*                   ; bitvector of length 0
@end example

A bitvector literal is delimited by one of delimiter character or an EOF.

@example
#*10010abc           ; error
#*10001(a b c)       ; a bitvector, followed by a list
@end example

Note: With this rule, @code{#*"..."} should be read as a zero-length
bitvector followed by a string, for @code{"} is a delimiter.  However,
Gauche used that syntax for incomplete strings (our overlook!).
Since incomplete string literals is rare (incomplete strings are
something that unexpectedly happen in the practical situation, but
not to be used actively), we changed incomplete string literals to
@code{#**"..."} since 0.9.10 (@pxref{Incomplete strings}).

For the backward compatibility, the current version reads @code{#*"..."}
is read as an incomplete string.  If the reader lexical mode is
@code{warn-legacy} (@pxref{Reader lexical mode}), such literals are
warned.  We'll gradually migrate to make @code{#*"..."} read
as a bytevector followed by a string.
@end deftp

@defun bit->integer bit
@defunx bit->boolean bit
[SRFI-178]
Many bitvector operations can accept bit as a boolean (@code{#f}/@code{#t})
or an exact integer (0/1).  These are utility procedures to obtain
desired type.  The @var{bit} argument must be either one of @code{#f}, @code{#t},
0 or 1.  They return 0/1 and @code{#f}/@code{#t}, respectively.
An error is signalled if @var{bit} is other than those values.
@end defun

@defun bitvector b @dots{}
[SRFI-178]
Creates and returns a bitvector whose elements are @var{b} @dots{}.
Each argument must be a bit (boolean or 0 or 1).

@example
(bitvector 0 1 0 0 1 0 0 0 1) @result{} #*010010001
(bitvector) @result{} #*
@end example
@end defun

@defun make-bitvector len :optional init
[SRFI-178]
Creates and returns a bitvector with length @var{len}, and all elements
being initialized by @var{init}, which must be a bit
(boolean or 0 or 1).

If @var{init} is omitted, the content of the bitvector is undefined
(currently we fill it with 0, but don't count on it.)

@example
(make-bitvector 5 #f)  @result{} #*00000
(make-bitvector 7 1)   @result{} #*1111111
@end example
@end defun

@defun list->bitvector lis
[SRFI-178]
@var{Lis} must be a list of bits (0, 1 or booleans).  Returns a bitvector
whose elements consist of elements of @var{lis}.

@example
(list->bitvector '(#t #f #t #t #f))  @result{} #*10110
(list->bitvector '(0 1 1 1 0 1 0 1)) @result{} #*01110101
@end example
@end defun

@defun string->bitvector s
[SRFI-178]
If @var{s} is a valid bitvector literal (@code{#*@var{b}...} where @var{b}
is either @code{0} or @code{1}), returns a bitvector represented by
the string.  Otherwise, @code{#f} is returned.

@example
(string->bitvector "#*1010001") @result{} #*1010001
(string->bitvector "#*1001020") @result{} #f
@end example

Note that this isn't a sequence-conversion, but rather a conversion from
external representation.
@end defun

@defun bitvector->string bv
[SRFI-178]
Convert a bitvector @var{bv} to a string representation @code{#*@var{b}...}.

@example
(bitvector->string #*1001010) @result{} "#*1001010"
@end example

Note that this isn't a sequence-conversion, but rather a conversion to
external representation.
@end defun

@defun bitvector-ref/int bv k :optional fallback
@defunx bitvector-ref/bool bv k :optional fallback
[SRFI-178+]
Retrieves the @var{k}-th bit of a bitvector @var{bv} as an integer or
a boolean value, respectively.  If @var{k} is out of range,
@var{fallback} is returned if it is given, or an error is raised otherwise.
The @var{fallback} argument is Gauche's extension.

@example
(bitvector-ref/int #*1010001 0)  @result{} 1
(bitvector-ref/bool #*1010001 0) @result{} #t
@end example

If you use a universal accessor @code{ref}/@code{~}, it returns
the bit value as an integer (@pxref{Universal accessor}).

@example
(~ #*11001001 1) @result{} 1
@end example
@end defun

@defun bitvector-set! bv k bit
[SRFI-178]
Sets the @var{k}-th bit of a bitvector @var{bv} with @var{bit}, which must
be either one of 0, 1, @code{#f} or @code{#t}.  An error is raised
if @var{k} is out of range.

This procedure is set as the setter of @code{bitvector-ref/int} and
@code{bitvector-ref/bool}.
Since a bitvector is a sequence, you can also use
@code{(setter ref)}/@code{(setter ~)}:

@example
(rlet1 z (make-bitvector 5 0)
  (set! (~ z 2) #t))
  @result{} #00100
@end example
@end defun

@defun bitvector-copy bv :optional start end
[SRFI-178]
Returns a copy of a bitvector @var{bv}.  If optional @var{start} and
@var{end} indexes are given, the copy is limited in that range,
where @var{start} is inclusive and @var{end} is exclusive.

@example
(bitvector-copy #*101001000 3)   @result{} #*001000
(bitvector-copy #*100101000 2 7) @result{} #*01010
@end example
@end defun

@defun bitvector-copy! target tstart src :optional sstart send
[SRFI-178]
Copy a bitvector @var{src} into a mutable bitvector @var{target} starting
from @var{tstart}, mutating @var{target}.  Optional @var{sstart} and
@var{send} delimits the range in @var{src}.

@example
(rlet1 v (make-bitvector 10 0)
  (bitvector-copy! v 3 #*101101110 2 6))
  @result{} #*0001101000
@end example
@end defun

@node Weak vectors,  , Bitvectors, Vector family
@subsection Weak vectors
@c NODE Weakベクタ

A weak pointer is a reference to an object that doesn't prevent
the object from being garbage-collected.
Gauche provides weak pointers as a @emph{weak vector} object.
A weak vector is like a vector of objects, except each object
can be garbage collected if it is not referenced from objects
other than weak vectors.   If the object is collected, the
entry of the weak vector is replaced for @code{#f.}
@example
gosh> (define v (make-weak-vector 1))
v
gosh> (weak-vector-ref v 0)
#f
gosh> (weak-vector-set! v 0 (cons 1 1))
#<undef>
gosh> (weak-vector-ref v 0)
(1 . 1)
gosh> (gc)
#<undef>
gosh> (gc)
#<undef>
gosh> (weak-vector-ref v 0)
#f
@end example

@xref{R7RS ephemerons}, for R7RS-large way of weak pointers.

@deftp {Builtin Class} <weak-vector>
@clindex weak-vector
The weak vector class.  Inherits @code{<sequence>} and @code{<collection>},
so you can use
@code{gauche.collection} (@pxref{Collection framework}) and
@code{gauche.sequence} (@pxref{Sequence framework}).
@example
(coerce-to <weak-vector> '(1 2 3 4))
  @result{} a weak vector with four elements
@end example
@end deftp

@defun make-weak-vector size
Creates and returns a weak vector of size @var{size}.
@end defun

@defun weak-vector-length wvec
Returns the length of a weak vector @var{wvec}.
@end defun

@defun weak-vector-ref wvec k :optional fallback
Returns @var{k}-th element of a weak vector @var{wvec}.

By default, @code{weak-vector-ref} signals an error if @var{k} is
negative, or greater than or equal to the size of @var{wvec}.
However, if an optional argument @var{fallback} is given,
it is returned for such case.

If the element has been garbage collected, this procedure returns
@var{fallback} if it is provided,  @code{#f} otherwise.

With @code{gauche.sequence} module,
you can also use a method @code{ref}.
@end defun

@defun weak-vector-set! wvec k obj
Sets @var{k}-th element of the weak vector @var{wvec} to @var{obj}.
It is an error if @var{k} is negative or greater than or equal to the
size of @var{wec}.
@end defun

@c ----------------------------------------------------------------------
@node Dictionaries, Procedures and continuations, Vector family, Core library
@section Dictionaries
@c NODE ディクショナリ

A dictionary is a data structure that associates key to value.
Gauche provides hashtables (@pxref{Hashtables}) and treemaps (@pxref{Treemaps})
as the built-in dictionaries.  Some additional libraries provide more
dictionary-type data structures.

A generic interface is defined as a dictionary framework 
(@pxref{Dictionary framework}), by which you can use dictionaries without
knowing its details. 

R7RS also defines an abstract dictionary interface as @emph{mapping};
@pxref{R7RS mappings}, for the details.

@menu
* Hashtables::
* Treemaps::
@end menu

@node Hashtables, Treemaps, Dictionaries, Dictionaries
@subsection Hashtables
@c NODE ハッシュテーブル

R7RS-large defines hashtable (@code{scheme.hash-table} module,
@pxref{R7RS hash tables}) but its API is not completely consistent
with Gauche's original hashtables and other native APIs.

Rather than mixing different flavor of APIs, we keep Gauche's native 
API consistent, and provide R7RS procedures that are inconsistent
with aliases---specifically, those procedures are suffixed with @code{-r7}
in @code{gauche} module.  For portable programs, you can import
@code{scheme.hash-table} to get R7RS names.

@deftp {Builtin Class} <hash-table>
@clindex hash-table
Hash table class.  Inherits @code{<collection>} and @code{<dictionary>}.

Gauche doesn't provide immutable hash tables for now.
(If you need immutable maps, @pxref{Immutable map}).
@end deftp

@subheading Hash table properties

@defun hash-table? obj
[R7RS hash-table]
Returns @code{#t} iff @var{obj} is a hash table.
@end defun

@defun hash-table-mutable? ht
[R7RS hash-table]
Returns @code{#t} iff a hash table @var{ht} is mutable.
Gauche doesn't have immutable hash tables, so this procedure always
returns @code{#t} for any hash tables.
@end defun

@defun hash-table-comparator ht
Returns a comparator used in the hashtable @var{ht}.
@end defun

@defun hash-table-type ht
This is an old API, superseded by @code{hash-table-comparator}.

Returns one of symbols @code{eq?}, @code{eqv?}, @code{equal?},
@code{string=?}, @code{general}, indicating the type of the hash table @var{ht}.
@end defun

@defun hash-table-num-entries ht
@defunx hash-table-size ht
[R7RS hash-table]
Return the number of entries in the hash table @var{ht}.
R7RS name is @code{hash-table-size}.
@end defun


@subheading Hash table constructors and converters

@defun make-hash-table :optional comparator
[R7RS+ hash-table]
Creates a hash table.  The @var{comparator} argument
specifies key equality and hash function using a comparator
(@pxref{Basic comparators}).  If omitted, @code{eq-comparator}
is used.  Note that in R7RS, @var{comparator}
argument can't be omitted.

As Gauche's extension, the @var{comparator} argument can also
be one of the symbols
@code{eq?}, @code{eqv?}, @code{equal?} or @code{string=?}.
If it is one of those symbols, @code{eq-comparator},
@code{eqv-comparator}, @code{equal-comparator} and
@code{string-comparator} will be used, respectively.

The comparator must have hash function, of course.  @xref{Hashing},
for the built-in hash functions.  In general, comparators derived from
other comparators having hash functions also have appropriate
hash functions.
@end defun

@defun hash-table-from-pairs comparator key&value @dots{}
Constructs and returns a hash table from given
list of arguments.
The @var{comparator} argument is the same as of @code{make-hash-table}.
Each @var{key&value} must be a pair, and its car is used as a key
and its cdr is used as a value.

Note: This is called @code{hash-table} by 0.9.5.  R7RS introduced 
a procedure with the same name, but different interface.
We see R7RS version makes more sense, so we'll eventually switch to it,
but the transition will take long time.
The R7RS interface is available as
@code{hash-table-r7}, and we urge you to use it in the new code,
and replace existing @code{hash-table} with @code{hash-table-from-pairs}.

@example
(hash-table-from-pairs 'eq? '(a . 1) '(b . 2))
  @equiv{}
  (rlet1 h (make-hash-table 'eq?)
     (hash-table-put! h 'a 1)
     (hash-table-put! h 'b 2))
@end example
@end defun

@defun hash-table comparator key&value @dots{}
An alias of @code{hash-table-from-pairs} above.  R7RS introduced the same name
procedure with different interface (see @code{hash-table-r7} below), and
we'd like to switch to it in future.  For now, use either
@code{hash-table-from-pairs} or @code{hash-table-r7},
or import @code{scheme.hash-table} and write in R7RS.
@end defun

@defun hash-table-r7 comparator args @dots{}
Create and returns a hash table using @var{comparator}.
The @var{args} @dots{} are the contents, alternating keys and values.

This is defined as @code{hash-table} in R7RS @code{scheme.hash-table}
(@pxref{R7RS hash tables}).

@example
(hash-table-r7 'eq? 'a 1 'b 2)
  @equiv{}
  (rlet1 h (make-hash-table 'eq?)
     (hash-table-put! h 'a 1)
     (hash-table-put! h 'b 2))
@end example

Note: An R7RS compliant implementation of @code{hash-table}
may return an immutable hash table.  Since Gauche doesn't have
immutable hash tables (we have immutable maps instead; @pxref{Immutable map}),
we return mutable hash tables.  However, the portable program should
refrain from mutating the returned hash tables.
@end defun

@defun hash-table-unfold p f g seed comparator :rest args
[R7RS hash-table]
Constructs and returns a new hash table with those repetitive steps.
Each iteration keeps the current seed value, whose initial value is @var{seed}.
@enumerate
@item
Apply a stop predicate @var{p} to the current seed value.  If it returns
a true value, stop.
@item
Apply a value producer @var{f} to the current seed value.  It must return
two values, which are used as a key and the corresponding value, of the
hash table.
@item
Apply a next procedure @var{g} to the current seed value.  The value
it returns becomes the next seed value.
@end enumerate
@end defun

@defun hash-table-copy ht :optional mutable?
[R7RS hash-table]
Returns a new copy of a hash table @var{ht}.

R7RS defines this procedure to return an immutable hash table if
the implementation supports one, unless the optional @var{mutable?}
argument is provided and not false.  Gauche doesn't have immutable
hash tables so it ignores the optional argument and
always returns a mutable hash table.  But when you write
a portable programs, keep it in mind.
@end defun

@defun hash-table-empty-copy ht
[R7RS hash-table]
Returns a new mutable empty hash table that has the same properties as
the given hash table @var{ht}.
@end defun

@defun alist->hash-table alist :optional comparator
[R7RS+ hash-table]
Creates and returns a hash table that has entries of
each element in alist, using its car as the key and
its cdr as the value.  The @var{comparator} argument
is the same as in @code{make-hash-table}.  The default value
of @var{comparator} is @code{eq-comparator}.

R7RS doesn't allow to omit @var{comparator}.
@end defun

@defun hash-table->alist hash-table
[R7RS hash-table]
@example
  (hash-table-map h cons)
@end example
@end defun

@subheading Hash table lookup and mutation

@defun hash-table-get ht key :optional default
Search @var{key} from a hash table @var{ht}, and returns its value
if found.  If the key is not found in the table and @var{default} is
given, it is returned.  Otherwise an error is signaled.
@end defun

@defun hash-table-put! ht key value
Puts a key @var{key} with a value @var{value} to the hash table @var{ht}.
@end defun

@deffn {Method} ref (ht <hash-table>) key :optional default
@deffnx {Method} {(setter ref)} (ht <hash-table>) key value
Method versions of @code{hash-table-get} and @code{hash-table-put!}.
@end deffn

@defun hash-table-ref ht key :optional failure success
[R7RS hash-table]
This is R7RS way to look up a hash table.

Look up a value associated to the @var{key} in the table @var{ht},
then pass it to a procedure @var{success}, and returns its value.
If @var{success} is omitted, an identity function is used.

If there's no association for @var{key} in @var{ht},
a thunk @var{failure} is called and its result is returned.
The default value of @var{failure} throws an error.

It is more general than Gauche's @code{hash-table-get}, but if you
need to simply return a fallback value in case of failure, you need
to wrap it with a clojure, which is annoying.  In R7RS, you can
use @code{hash-table-ref/default} below.
@end defun

@defun hash-table-ref/default ht key default
[R7RS hash-table]
Looks up @var{key} in a hash table @var{ht} and returns the associated
value.  If there's no @var{key} in the table, returns @var{default}.

This is same as Gauche's @code{hash-table-get}, except that
@var{default} is not optional.  We provide both, for
@code{hash-table-get} is short and handy.
@end defun

@defun hash-table-set! ht args @dots{}
[R7RS hash-table]
This is R7RS version to put associations into a hash table.
The @var{args} @dots{} is a list of alternating keys and values; so,
unlike Gauche's @code{hash-table-put!}, you can insert more than
one associations at once.  It is an error if @var{args} @dots{} have
odd number of arguments.

@example
(hash-table-set! ht 'a 1 'b 2)
  @equiv{}
  (begin (hash-table-put! ht 'a 1)
         (hash-table-put! ht 'b 2))
@end example
@end defun

@defun hash-table-intern!-r7 ht key failure
This is defined in R7RS as @code{hash-table-intern!}.  We add @code{-r7}
suffix to remind that it takes a failure thunk,
which is consistent with R7RS hash-table interface but not Gauche's way.

Lookup @var{key} in @var{ht}.  If there's already an entry, it just returns
the value.
Otherwise, it calls a thunk @var{failure}, and insert the association
of @var{key} and the return value of @var{failure} into @var{ht},
and returns the value.
@end defun

@defun hash-table-exists? ht key
@defunx hash-table-contains? ht key
[R7RS hash-table]
Returns @code{#t} if a hash table @var{ht} has a key @var{key}.

R7RS name is @code{hash-table-contains?}.
@end defun

@defun hash-table-delete! ht key
Deletes an entry that has a key @var{key} from the hash table @var{ht}.
Returns @code{#t} if the entry has exist, or @code{#f} if the entry
hasn't exist.   The same function is called @code{hash-table-remove!} in STk
(except that it returns an undefined value); I use `delete' for consistency
to SRFI-1, SRFI-13 and other parts of the libraries.

Note: This is different from R7RS @code{hash-table-delete!}, so we provide
R7RS interface with an alias @code{hash-table-delete!-r7}.
@end defun

@defun hash-table-delete!-r7 ht key @dots{}
Delets entries that have @var{key} @dots{} from the hash table @var{ht}.
The @var{key} which isn't in @var{ht} has no effect.  Returns the number
of entries actually deleted.

This is called @code{hash-table-delete!} in R7RS, and so as in
@code{scheme.hash-table}.  We provide this under different name,
for Gauche's @code{hash-table-delete!} returns a boolean value.
@end defun

@defun hash-table-clear! ht
[R7RS hash-table]
Removes all entries in the hash table @var{ht}.
@end defun

@defun hash-table-push! ht key value
Conses @var{value} to the existing value for the key @var{key} in the
hash table @var{ht} and makes it the new value for @var{key}.
If there's no entry for @var{key}, an entry
is created with the value @code{(list @var{value})}.

Works the same as the following code, except that this function
only looks up the @var{key} once, thus it's more efficient.
@example
(hash-table-put! @var{ht} @var{key}
    (cons @var{value} (hash-table-get @var{ht} @var{key} '())))
@end example
@end defun

@defun hash-table-pop! ht key :optional default
Looks for the value for the key @var{key} in the hash table @var{ht}.
If found and it is a pair, replaces the value for its cdr and returns
car of the original value.  If no entry for @var{key} is in the table,
or the value is not a pair, the table is not modified and
the procedure returns @var{default} if given, or signals an error otherwise.

During the operation the key is looked for only once, thus runs
efficiently.

Note: R7RS has @code{hash-table-pop!} but its totally different.
We provide R7RS version as an alias @code{hash-table-pop!-r7}
@end defun

@defun hash-table-pop!-r7 ht
Removes one arbitrary entry from @var{ht}, and returns the removed
entry's key and value as two values.  If @var{ht} is empty, an error
is thrown.

This is called @code{hash-table-pop!} in R7RS, and so as in
@code{scheme.hash-table}.
@end defun

@defun hash-table-update! ht key proc :optional default
A more general version of @code{hash-table-push!} etc.
It works basically as the following code piece,
except that the lookup of @var{key} is only done once.
@example
(let ((tmp (@var{proc} (hash-table-get @var{ht} @var{key} @var{default}))))
  (hash-table-put! @var{ht} @var{key} tmp)
  tmp)
@end example

For example, when you use a hash table to count the occurrences
of items, the following line is suffice to increment the counter
of the item, regardless of whether @var{item} has already appeared or not.

@example
(hash-table-update! ht item (cut + 1 <>) 0))
@end example

R7RS provides @code{hash-table-update!} with different interface,
so we provide R7RS version as an alias @code{hash-table-update!-r7}.
@end defun

@defun hash-table-update!-r7 ht key updater :optional failure success
This is R7RS version of @code{hash-table-update!}.  With no optional
arguments, it works like Gauche's @code{hash-table-update!}.  But in
practice you often needs to specify the behavior when @var{key} hasn't
been in @var{ht}, in which case R7RS differs from Gauche.

The R7RS version works like this but potentially more efficiently:

@example
(hash-table-put! ht key (updater (hash-table-ref ht key failure success)))
@end example
@end defun

@defun hash-table-update!/default ht key updater default
[R7RS hash-table]
This is the same as Gauche's @code{hash-table-default!}, except that
the default value can't be omitted.
@end defun

@subheading Hash table scanners

@defun hash-table-for-each ht proc
@defunx hash-table-map ht proc
A procedure @var{proc} is called with two arguments, a key and its associated
value, over all the entries in the hash table @var{ht}.
@end defun

@defun hash-table-fold ht kons knil
For all entries in the hash table @var{ht},
a procedure @var{kons} is called with three arguments;
a key, its associated value, and the previous return value of @var{kons}.
The first call of @var{kons} receives @var{knil} as the third argument.
The return value of the last call of @var{kons} is returned
from @code{hash-table-fold}.
@end defun

@defun hash-table-find ht pred :optional failure
Apply @var{pred} with each key and value in the hash table @var{ht}.
Once @var{pred} returns a true value, that return value is immediately returned
from @code{hash-table-find}.
If no key-value satisfies @var{pred}, a thunk @var{failure} is
invoked and its result is returned.  If @var{failure} is
omitted, @code{(lambda () #f)} is assumed.

Note: The convention starting from srfi-1 is that
@code{*-find} returns an item in the collection that
satisfy the predicate, while @code{*-any} returns a non-false
value the predicate returns.  SRFI-125 broke the convention.
The justification given in SRFI-125 discussion
was that the ``any'' semantics is strictly upper-compatible to the
``find'' semantics so we can combine two.  So far, though, SRFI-125
is the only exception of this convention.

@example
;; Find if hash tables ha and hb has a common key.
(hash-table-find ha (^[k v] (hash-table-exists? hb k)))
@end example
@end defun

@defun hash-table-keys ht
@defunx hash-table-values ht
Returns all the keys or values of hash table @var{ht} in a list,
 respectively.
@end defun

@subheading Hash table as sets

@defun hash-table-compare-as-sets ht1 ht2 :optional value=? fallback
A hash table can be viewed as a set of pairs of key and value.
This procedure compares two hash tables @var{ht1} and @var{ht2} as such
sets.

The key comparators of two tables must match (in terms of @code{equal?}
of the comparators).  Otherwise, an error is signaled.

Two elements of the set are equal to each other iff their keys match
with the equality predicate of the key comparator, and their values
match with @var{value=?} procedure.  If omitted, @code{equal?} is
used for @var{value=?}

There can be four cases.
@itemize
@item
If @var{ht1} is a pure subset of @var{ht2}, returns -1 (@var{ht1} is smaller
than @var{ht2}).
@item
If @var{ht2} is a pure subset of @var{ht1}, returns 1 (@var{ht1} is greater
than @var{ht2}).
@item
If @var{ht1} and @var{ht2} contains exactly the same elements,
returns 0 (@var{ht1} equals to @var{ht2}).
@item
Neither @var{ht1} nor @var{ht2} is a subset of another.  In this case,
@var{fallback} is returned if it is given, or an error is thrown.
@end itemize
@end defun

@defun hash-table=? value-cmpr ht1 ht2
[R7RS hash-table]
This also compares two hash tables @var{ht1} and @var{ht2} as sets,
and returns true iff two are the same.  That is, every element in @var{ht1}
is also in @var{ht2} and vice versa.

Two element are the same iff their keys are the same in terms of
the equality predicate of the tables' key comparator, and their values
are the same in terms of the equality predicate of a comparator
@var{value-cmpr}.

It is an error if @var{ht1} and @var{ht2} has different key comparators.
See also @code{hash-table-compare-as-sets} above.
@end defun

@defun hash-table-union! ht1 ht2
@defunx hash-table-intersection! ht1 ht2
@defunx hash-table-difference! ht1 ht2
@defunx hash-table-xor! ht1 ht2
[R7RS hash-table]
Perform set operations on two hashtables @var{ht1} and @var{ht2},
and modify @var{ht1} to store the result.
Note that these procedures only look at the keys for operation; if
the values of the same key differ between @var{ht1} and @var{ht2},
the value in @var{ht1} is taken.

@itemize
@item
The union operation picks each entry that is in at least one of @var{ht1}
or @var{ht2}.
@item
The intersection operation picks each entry that is both in @var{ht1} and
@var{ht2}.
@item
The difference operation picks each entry that is in @var{ht1} but
not in @var{ht2}.
@item
The xor operation picks each entry that is in only one of @var{ht1} or
@var{ht2}, but not in both.
@end itemize
@end defun


@c ----------------------------------------------------------------------
@node Treemaps,  , Hashtables, Dictionaries
@subsection Treemaps
@c NODE ツリーマップ

@deftp {Builtin Class} <tree-map>
@clindex tree-map
Tree map class.   Tree maps are a data structure that maps key objects
to value objects.  It's like hash tables except tree maps uses
balanced tree internally.  Insertion and lookup is O(log n).

Unlike hashtables, a tree map keeps the order of the keys, so
it is easy to traverse entries in the order of keys, to find
minimum/maximum keys, or to find a key closest to the given value.

The @code{<tree-map>} class inherits @code{<sequence>} and
@code{<ordered-dictionary>}.
@end deftp

@defun make-tree-map :optional comparator
@defunx make-tree-map key=? key<?
Creates and returns an instance of @code{<tree-map>}.
The keys are compared by @var{comparator},
whose default is @code{default-comparator}.
The comparator must have a comparison procedure, for
we need a total order in the keys.
@xref{Basic comparators}, for the details.

For the backward compatibility, @code{make-tree-map} also
accepts a procedure as a @var{comparator}; the procedure must
take two keys and returns either @code{-1}, @code{0}, or @code{1},
depending on whether the first key is less than, equal to, or
greater than the second key, respectively.  In other words, it
is a comparison procedure of a comparator.

The second form of @code{make-tree-map} is also for the 
backward compatibility; it takes two procedures, each must
be a procedure that takes two keys; the first one returns
@code{#t} iff two keys are equal, and the second one returns
@code{#t} iff the first key is strictly smaller than the second.
@end defun

@defun tree-map-comparator tree-map
Returns the comparator used in the tree map.
@end defun

@defun tree-map-copy tree-map
Copies and returns  @var{tree-map}.  Modification
on the returned tree doesn't affect the original tree.
@end defun

@defun tree-map-empty? tree-map
Returns @code{#t} if @var{tree-map} doesn't have any elements,
or @code{#f} otherwise.
@end defun

@defun tree-map-num-entries tree-map
Returns the number of elements in @var{tree-map}.
@end defun

@defun tree-map-exists? tree-map key
Returns @code{#t} if @var{tree-map} has an entry with @var{key},
or @code{#f} otherwise.
@end defun

@defun tree-map-get tree-map key :optional fallback
Looks for @var{key} in @var{tree-map}.  If the entry is found,
returns a value corresponding to the key.  Otherwise, returns
@var{fallback} if it is provided, or signals an error.
@end defun

@defun tree-map-put! tree-map key value
Inserts an entry with a @var{key} and corresponding @var{value}
into @var{tree-map}.  If there already exists an entry with a
key which is equivalent (under @var{key=?}), the entry is modified
to have @var{value}.
@end defun

@defun tree-map-delete! tree-map key
Deletes an entry with @var{key} from @var{tree-map} if such an entry
exists, and returns @code{#t}.
If @var{tree-map} doesn't have such an entry, @code{#f} is returned.
@end defun

@defun tree-map-clear! tree-map
Removes all entries in @var{tree-map}.
@end defun

@defun tree-map-update! tree-map key proc :optional fallback
A generalized version of @code{tree-map-push!} etc.
It works like the following code, except that searching
for the key is done only once.
@example
(let ((tmp (proc (tree-map-get @var{tree-map} @var{key} @var{fallback}))))
  (tree-map-put! @var{tree-map} @var{key} tmp)
  tmp)
@end example
@end defun

@defun tree-map-push! tree-map key value
Looks for an entry with @var{key} in @var{tree-map}.  If it exists,
the procedure conses @var{value} to the original value and makes
it as a new value.
Otherwise, the procedure creates a new entry for the @var{key}
and makes @code{(list @var{value})} its value.
@end defun

@defun tree-map-pop! tree-map key :optional fallback
Looks for an entry with @var{key} in @var{tree-map}.  If it exists
and its value is a pair, then the procedure updates
its value with @code{cdr} of the original value, and returns
@code{car} of the original entry.   If such an entry does not
exist, or has a non-pair value, the procedure doesn't
modify @var{tree-map} and returns @var{fallback} if it is given,
otherwise reports an error.
@end defun

@defun tree-map-min tree-map
@defunx tree-map-max tree-map
Returns a pair of a key and its value with the minimum
or maximum key, respectively.   If @var{tree-map} is empty,
@code{#f} is returned.
@end defun

@defun tree-map-pop-min! tree-map
@defunx tree-map-pop-max! tree-map
Looks for an entry with minimum or maximum key, respectively,
then deletes the entry from @var{tree-map} and returns
a pair of the key and its value of the original entry.
If @var{tree-map} is empty, @code{#f} is returned.
@end defun

@defun tree-map-fold tree-map proc seed
@defunx tree-map-fold-right tree-map proc seed
Iterate over elements in @var{tree-map}, applying
@var{proc} which has a type @code{(key, value, seed) -> seed}.
The difference of @code{tree-map-fold} and @code{tree-map-fold-right}
is the associative order of applying @var{proc},
just like the difference between @code{fold} and @code{fold-right}.
@example
tree-map-fold:
  (proc Kn Vn (proc Kn-1 Vn-1 ... (proc K0 V0 seed)))

tree-map-fold-right
  (proc K0 V0 (proc K1 V1 ... (proc Kn Vn seed)))
@end example

Some examples:
@example
(define tree (alist->tree-map '((3 . a) (7 . b) (5 . c)) = <))

(tree-map-fold tree list* '())
   @result{} (7 b 5 c 3 a)
(tree-map-fold-right tree list* '())
   @result{} (3 a 5 c 7 b)
@end example
@end defun

@defun tree-map-map tree-map proc
Calls @var{proc}, which must take two arguments,
with each key/value pair in @var{tree-map},
and collect the results into a list and returns it.  The order
of results corresponds to the order of keys---that is, the first element
of the result list is what @var{proc} returns with minimum key and its value,
and the last element of the result list is what @var{proc} returns
with the maximum key and its value.
(Note: Like @code{map}, the order that @var{proc} is actually called
is unspecified; @var{proc} is better to be side-effect free.)
@end defun

@defun tree-map-for-each tree-map proc
Calls @var{proc}, which must take two arguments,
with each key/value pair in @var{tree-map},
in the increasing order of the keys.  @var{proc} is called purely
for side effects; the returned values are discarded.
@end defun

@defun tree-map-floor tree-map probe :optional fallback-key fallback-value
@defunx tree-map-ceiling tree-map probe :optional fallback-key fallback-value
@defunx tree-map-predecessor tree-map probe :optional fallback-key fallback-value
@defunx tree-map-successor tree-map probe :optional fallback-key fallback-value
These procedures search the entry which has the closest key
to the given @var{probe}.  If such an entry is found, returns
two values, its key and its value.  Otherwise, returns two values,
@var{fallback-key} and @var{fallback-value}, both defaulted to @code{#f}.

The criteria of ``closest'' differ slightly among these procedures;
@code{tree-map-floor} finds the maximum key which is no greater than
@var{probe}; @code{tree-map-ceiling} finds the minimum key which is
no less than @var{probe}; @code{tree-map-predecessor} finds the
maximum key which is strictly less than @var{probe};
and @code{tree-map-successor} finds the minimum key which
is strictly greater than @var{probe}.
@end defun

@defun tree-map-floor-key tree-map probe @var{optional} fallback-key
@defunx tree-map-ceiling-key tree-map probe @var{optional} fallback-key
@defunx tree-map-predecessor-key tree-map probe @var{optional} fallback-key
@defunx tree-map-successor-key tree-map probe @var{optional} fallback-key
Like @code{tree-map-floor} etc., but only returns the key of
the found entry (or @var{fallback-key} if there's no entry which satisfies
the criteria).
@end defun

@defun tree-map-floor-value tree-map probe @var{optional} fallback-value
@defunx tree-map-ceiling-value tree-map probe @var{optional} fallback-value
@defunx tree-map-predecessor-value tree-map probe @var{optional} fallback-value
@defunx tree-map-successor-value tree-map probe @var{optional} fallback-value
Like @code{tree-map-floor} etc., but only returns the value of
the found entry (or @var{fallback-value} if there's no entry which satisfies
the criteria).
@end defun

@defun tree-map-keys tree-map
@defunx tree-map-values tree-map
Returns a list of all keys and all values, respectively.
The keys and values are in ascending order of the keys.
@end defun

@defun tree-map->alist tree-map
Returns a list of pairs of keys and values for all entries.
The pairs are in ascending order of the keys.
@end defun

@defun alist->tree-map alist :optional comparator
@defunx alist->tree-map alist key=? key<?
Creates a new tree map with the @var{comparator} or
@var{key=?}/@var{key<?} procedures, then
populates it with @var{alist}, each pair in which are
interpreted as a cons of a key and its value.
The meaning of @var{comparator}, @var{key=?} and @var{key<?} are
the same as @code{make-tree-map}.
@end defun

The following two procedures compares two tree maps with slightly different
views.

@defun tree-map-compare-as-sets tree-map1 tree-map2 :optional value=? fallback
Compares two tree maps as sets of entries.  If we look at tree maps
as sets of entries, we can define a partial order between two maps;
they are equal to each other if they have exactly the same entries,
and tree-map A is smaller than tree-map B if A us a strict subset of B.

If @var{tree-map1} and @var{tree-map2} are the same, 0 is
returned.  If @var{tree-map1} is smaller than @var{tree-map2}, -1
is returned.  If @var{tree-map1} is greater than @var{tree-map2}, 1
is returned.

If one argument isn't subset of the other, we can't determine the order.
In such a case, if @var{fallback} is given, it is returned.  Otherwise,
an error is signalled.

The comparators of @var{tree-map1} and @var{tree-map2} must be
the same (@code{equal?}), otherwise an error is signalled.
@xref{Basic comparators}, about the comparators.

An entry is equal to another entry if their keys match in terms
of the comparator of the tree-map, and also their values match
with the provided @var{value=?} predicate, which is defaulted to
@code{equal?}.

@example
(tree-map-compare-as-sets
 (alist->tree-map '((1 . a) (2 . b) (3 . c)) default-comparator)
 (alist->tree-map '((3 . c) (1 . a) (2 . b)) default-comparator))
 @result{} 0

(tree-map-compare-as-sets
 (alist->tree-map '((1 . a) (3 . c)) default-comparator)
 (alist->tree-map '((3 . c) (1 . a) (2 . b)) default-comparator))
 @result{} -1

(tree-map-compare-as-sets
 (alist->tree-map '((1 . a) (3 . c) (4 . d) (2 . b)) default-comparator)
 (alist->tree-map '((3 . c) (1 . a) (2 . b)) default-comparator))
 @result{} 1

(tree-map-compare-as-sets
 (alist->tree-map '((1 . a) (3 . c) (4 . d)) default-comparator)
 (alist->tree-map '((3 . c) (1 . a) (2 . b)) default-comparator))
 @result{} ERROR: tree-maps can't be ordered

(tree-map-compare-as-sets
 (alist->tree-map '((1 . a) (3 . c) (4 . d)) default-comparator)
 (alist->tree-map '((3 . c) (1 . a) (2 . b)) default-comparator)
 eq?
 #f)
 @result{} #f
@end example
@end defun

@defun tree-map-compare-as-sequences tree-map1 tree-map2 :optional value-cmp
Compares two tree maps as sequence of entries, ordered by keys.
If both maps have entries with the same key, we use a comparator
@var{value-cmp} to break the tie (naturally, @var{value-cmp} must
have ordering predicate.)
If @var{value-cmp} is omitted, @code{default-comparator} is used.

The comparators of @var{tree-map1} and @var{tree-map2} must be
the same (@code{equal?}), otherwise an error is signalled.
@xref{Basic comparators}, about the comparators.

If @var{tree-map1} and @var{tree-map2} are the same, 0 is
returned.  If @var{tree-map1} is smaller than @var{tree-map2}, -1
is returned.  If @var{tree-map1} is greater than @var{tree-map2}, 1
is returned.

Unlike @code{tree-map-compare-as-sets}, this procedure defines total order
of tree maps which share the same comparator.

@example
(tree-map-compare-as-sequences
 (alist->tree-map '((1 . a) (3 . c)) default-comparator)
 (alist->tree-map '((3 . c) (2 . b)) default-comparator))
 @result{} -1

(tree-map-compare-as-sequences
 (alist->tree-map '((2 . b) (3 . d)) default-comparator)
 (alist->tree-map '((3 . c) (2 . b)) default-comparator))
 @result{} 1
 @end example
@end defun

@c ----------------------------------------------------------------------
@node Procedures and continuations, Parameters, Dictionaries, Core library
@section Procedures and continuations
@c NODE 手続きと継続

In Scheme, @emph{procedures} are fundamental blocks to build
a program (@pxref{Making procedures}).
A procedure represents a certain computation,
possibly parameterized, and can be @emph{applied} to the actual
arguments to execute the computation.  Scheme also provides
the means to extract the continuation of the current computation
and wraps it in a procedure (@pxref{Continuations}).

Gauche extends the concept of procedure application, allowing
you to apply any object as if it's a procedure; 
for example, you can set up Gauche to
accept @code{("abc" 2)} can be a valid application syntax.
@xref{Applicable objects}, for the details.

@menu
* Procedure class and applicability::
* Universal accessor::
* Combinators::
* Optional argument parsing::
* Procedure arity::
* Applicable objects::
* Continuations::
* Multiple values::
* Folding generated values::
@end menu

@node Procedure class and applicability, Universal accessor, Procedures and continuations, Procedures and continuations
@subsection Procedure class and applicability

@deftp {Builtin Class} <procedure>
@clindex procedure
Represents a procedure.  Ordinary Scheme procedures created by @code{lambda}
is an instance of this class, as well as built-in primitive procedures
written in C.  Note that, in Gauche, other type of objects can behave
as a procedure; so checking whether an object is a procedure or not doesn't
mean much unless you want to mess around with Gauche internals.
@end deftp

@defun procedure? obj
[R7RS base]
Returns @code{#t} if @var{obj} is @emph{inherently} applicable
objects, @code{#f} otherwise.  By @emph{inherently} applicable
we mean Gauche unconditionally understands that @var{obj} can be called
as a procedure; an instance of @code{<procedure>} is so,
as well as generic functions (@code{<generic>}) and methods (@code{<method>}).
@xref{Generic function and method}, for the details.

Since you can make any type of objects applicable at any time
(@pxref{Applicable objects}), the fact that @code{procedure?} returned
@code{#f} doesn't mean that the object cannot be applied.
To check if an object can be applied or not, use @code{applicable?} below.
@end defun

@defun apply proc arg1 @dots{} args
[R7RS base]
Calls a procedure @var{proc} with a list of arguments,
@code{(@var{arg1} @dots{} . @var{args})}.
The last argument @var{args} must be a proper list.
Returns (a) value(s) @var{proc} returns.
@example
(apply list 'a 'b '(c d e)) @result{} (a b c d e)

(apply + 1 2 '(3 4 5))      @result{} 15
@end example
@end defun

@defun applicable? obj class @dots{}
Checks if @var{obj} can be called with the types of arguments
listed in @var{class} @dots{}.  That is,
when @code{(applicable? foo <string> <integer>)} returns @code{#t},
then you can call @code{foo} as @code{(foo "x" -2)}, for example.
(It doesn't mean you won't get an error; @code{foo} may be accept
only nonnegative integers, which you cannot tell from the result of
@code{applicable?}.  But if @code{applicable?} returns @code{#t},
Gauche won't complain ``foo is not applicable'' when you call @code{foo}.

This procedure takes applicable objects into account.  So, for example,
@code{(applicable? #/a/ <string>)} returns @code{#t}, for the regular
expressions are applicable to a string (@pxref{Regular expressions}).

For generic functions, @code{applicable?} returns @code{#t} if it has
at least one method such that each of its specifiers is a superclass
of the corresponding @var{class} argument given to @code{applicable?}.

@example
(define-method foo ((x <sequence>) (y <integer>)) #f)

(applicable? foo <sequence> <integer>) @result{} #t
(applicable? foo <string> <integer>) @result{} #t
(applicable? foo <hash-table> <integer>) @result{} #f
(applicable? foo <string> <real>) @result{} #f
@end example

The second example returns @code{#t} since @code{<string>} is
a subclass of @code{<sequence>}, while
the third example returns @code{#f} since @code{<hash-table>}
isn't a subclass of @code{<sequence>}.  The fourth example
returns @code{#f} since @code{<real>} isn't a subclass of @code{<integer>}.

Traditional Scheme procedures (such as ones created by @code{lambda})
only cares the number of arguments but not their types; it accepts
any type as far as the number of arguments matches.  To check such
a condition, pass @code{<top>} as the argument class.  (@code{<top>} is
a superclass of all classes.)

@example
(applicable? cons <top> <top>) @result{} #t
@end example

If you want to check an object is applicable to a certain
number of @emph{some} class of arguments, you can pass @code{<bottom>}
as the argument class instead.   (@code{<bottom>} is a subclass of all
classes.)

@example
(define-method foo ((x <sequence>) (y <integer>)) #f)

(applicable? foo <top> <top>) @result{} #f
(applicable? foo <bottom> <bottom>) @result{} #t
@end example

@xref{Types and classes}, for the details of @code{<top>}, @code{<bottom>} and
Gauche's type handling.
@end defun

@node Universal accessor, Combinators, Procedure class and applicability, Procedures and continuations
@subsection Universal accessor
@c NODE 万能アクセサ

@defun ~ obj key keys @dots{}
@defunx {(setter ~)} obj key keys @dots{}
The procedure @code{~} can be used to access a part of various
aggregate types.

@example
;; Access to an element of a sequence by index
(~ '(a b c) 0)       @result{} a
(~ '#(a b c) 2)      @result{} c
(~ "abc" 1)          @result{} #\b
(~ '#u8(10 20 30) 1) @result{} 20

;; Access to an element of a collection by key
(~ (hash-table 'eq? '(a . 1) '(b . 2)) 'a)
  @result{} 1

;; Access to a slot of an object by slot name
(~ (sys-localtime (sys-time)) 'hour)
  @result{} 20
@end example

The access can be chained:

@example
(~ '#((a b c) (d e f) (g h i)) 1 2) @result{} f

(~ (hash-table 'eq? '(a . "abc") '(d . "def")) 'a 2)
  @result{} #\c
@end example

You can think @code{~} as left-associative, that is,
@example
(~ x k j) @equiv{} (~ (~ x k) j)
@end example
and so on.

The generalized setter @code{set!} can be used with @code{~} to
replace the specified element.

@example
(define z (vector 'a 'b 'c))
(set! (~ z 1) 'Z)

z @result{} #(a Z c)

(define z (vector (list (vector 'a 'b 'c)
                        (vector 'd 'e 'f)
                        (vector 'g 'h 'i))
                  (list (vector 'a 'b 'c)
                        (vector 'd 'e 'f)
                        (vector 'g 'h 'i))))

z @result{} #((#(a b c) #(d e f) #(g h i))
     (#(a b c) #(d e f) #(g h i)))

(set! (~ z 1 2 0) 'Z)
z @result{}  #((#(a b c) #(d e f) #(g h i))
     (#(a b c) #(d e f) #(Z h i)))
@end example
@end defun

Internally, a call to @code{~} is implemented by a generic
function @code{ref}.  See @ref{Object system} for more about
generic functions.

@deffn {Generic function} ref object key :optional args @dots{}
@deffnx {Generic function} {(setter ref)} object key value
Many aggregate types defines a specialized method of these
to provide uniform access and mutation.   Meaning of
optional arguments @var{args} of @code{ref} depends
on each specialized method,
but it is common that the first optional argument of @code{ref}
is a @emph{fallback} value, which is to be returned when
@var{object} doesn't have a meaningful association with @var{key}.

The manual entry of each aggregate type shows the specialized
method and its semantics in detail.
@end deffn

Conceptually, @code{~} can be understood as follows:

@example
(define ~
  (getter-with-setter
   (case-lambda
     [(obj selector) (ref obj selector)]
     [(obj selector . more) (apply ~ (ref obj selector) more)])
   (case-lambda
     [(obj selector val) ((setter ref) obj selector val)]
     [(obj selector selector2 . rest)
      (apply (setter ~) (ref obj selector) selector2 rest)])))
@end example

(Gauche may use some short-cut for optimization, though,
so this code may not reflect the actual implementation.)

@node Combinators, Optional argument parsing, Universal accessor, Procedures and continuations
@subsection Combinators
@c NODE コンビネータ

Gauche has some primitive procedures that allows combinatory programming.

@defun pa$ proc arg @dots{}
Partial application.  Returns a procedure, and when it is
called with arguments @var{m} @dots{}, it is equivalent to call
@code{(proc arg @dots{} m @dots{})}.

@example
(define add3 (pa$ + 3))
(add3 4) @result{} 7

(map (pa$ * 2) '(1 2 3)) @result{} (2 4 6)
@end example

Macros @code{cut} and @code{cute} defined in SRFI-26 provide
a similar abstraction, with a bit more flexible but less compact
notation.  @xref{Making procedures}.
@end defun

@defun apply$ proc
@defunx map$ proc
@defunx for-each$ proc
Partial application versions of @code{apply}, @code{map} and @code{for-each}.

@example
(define map2* (map$ (pa$ * 2)))
(map2* '(1 2 3)) @result{} (2 4 6)
@end example

@end defun

@defun count$ pred
@defunx fold$ kons :optional knil
@defunx fold-right$ kons :optional knil
@defunx reduce$ f :optional ridentity
@defunx reduce-right$ f :optional ridentity
@defunx filter$ pred
@defunx remove$ pred
@defunx partition$ pred
@defunx member$ item
@defunx find$ pred
@defunx find-tail$ pred
@defunx any$ pred
@defunx every$ pred
@defunx delete$ pred
@defunx assoc$ item
Partial application versions of some srfi-1 (R7RS @code{(scheme list)})
procedures (@pxref{R7RS lists}).
@end defun

@defun .$ f @dots{}
@defunx compose f @dots{}
Combine procedures.  All arguments must be procedures.
When two procedures are given, @code{(.$ f g)} is equivalent to
the following code:
@example
(lambda args (call-with-values (lambda () (apply g args)) f))
@end example

When more than two arguments are passed, they are composed
as follows:
@example
(.$ f g h ...) @equiv{} (.$ (.$ f g) h ...)
@end example

Some examples:

@example
(define not-zero? (.$ not zero?))
(not-zero? 3) @result{} #t
(not-zero? 0) @result{} #f

(define dot-product (.$ (apply$ +) (map$ *)))
(dot-product '(1 2 3) '(4 5 6)) @result{} 32
@end example

A couple of edge cases: if only one argument is given, the argument
itself is returned.  If no arguments are given, the procedure @code{values}
is returned.

Note: The name @code{.$} comes from the fact that @code{.} is
commonly used for function composition in literatures and some
programming languages, and that Gauche uses suffix @code{$} to
indicate combinators.   However, since it is not a valid R7RS
identifier, portable programs may want to use the alias @code{compose},
with which you can easily add a portable definition using @code{srfi-0},
for example.
@end defun

@defun identity obj
Returns @var{obj}.
@end defun

@defun constantly obj
Returns a procedure that takes arbitrary number of arguments, discards
them, and returns @var{obj}.  Same as @code{(^ _ obj)}.
@end defun

@defun complement pred
Returns a procedure that reverses the meaning of the predicate @var{pred}.
That is, for the arguments for which @var{pred} returns true return
false, and vice versa.

@example
(map (complement even?) '(1 2 3)) @result{} '(#t #f #t)
(map (complement =) '(1 2 3) '(1 1 3)) @result{} '(#f #t #f)
((complement (lambda () #f))) @result{} #t
@end example
@end defun

@defun any-pred pred @dots{}
Returns a procedure which applies given argument(s) to
each predicate @var{pred}.  If any @var{pred} returns
a non-@code{#f} value, the value is returned.  If all the @var{pred}s
return @code{#f}, @code{#f} is returned.

@example
(define string-or-symbol? (any-pred string? symbol?))
(string-or-symbol? "abc") @result{} #t
(string-or-symbol? 'abc)  @result{} #t
(string-or-symbol? 3)     @result{} #f

(define <> (any-pred < >))
(<> 3 4) @result{} #t
(<> 3 3) @result{} #f

((any-pred (cut memq <> '(a b c))
           (cut memq <> '(1 2 3)))
 'b)  @result{} '(b c)
@end example
@end defun

@defun every-pred pred @dots{}
Returns a procedure which applies given argument(s) to
each predicate @var{pred}.  If every @var{pred} returns
a non-@code{#f} value, the value returned by the last @var{pred}
is returned.  If any @var{pred} returns @code{#f}, @code{every-pred}
returns @code{#f} without calling further @var{pred}s.

@example
((every-pred odd? positive?) 3)  @result{} #t
((every-pred odd? positive?) 4)  @result{} #f
((every-pred odd? positive?) -3) @result{} #f

(define safe-length (every-pred list? length))
(safe-length '(a b c))  @result{} 3
(safe-length "aaa")     @result{} #f
@end example
@end defun

@node Optional argument parsing, Procedure arity, Combinators, Procedures and continuations
@subsection Optional argument parsing
@c NODE 省略可能引数のパージング

Gauche supports optional and keyword arguments in extended
lambda syntax (@pxref{Making procedures}).  However, you can
also use the following macros to parse optional and keyword
arguments, without relying Gauche's extension.

@example
(define (foo a b :optional (c #f) (d 'none))
  body ...)

;; is roughly equivalent to ...

(define (foo a b . args)
  (let-optionals* args ((c #f) (d 'none))
    body ...))
@end example

Explicitly parsing the extended arguments may be useful for
portable programs, since it is rather straightforward to
implement those macros rather than extend lambda syntax.

Those macros can also be useful to factor out common
argument parsing routines.

@defmac let-optionals* restargs (var-spec @dots{}) body @dots{}
@defmacx let-optionals* restargs (var-spec @dots{} . restvar) body @dots{}
Given a list of values @var{restargs}, binds variables according
to @var{var-spec}, then evaluates @var{body}.

@var{Var-spec} can be either a symbol, or a list of two elements
and its car is a symbol.  The symbol is the bound variable name.
The values in @var{restargs} are bound to the symbol in order.
If there are not as many values in @var{restargs} as @var{var-spec},
the rest of @var{symbol}s are bound to the default values, determined
as follows: If @var{var-spec} is just a symbol, the default value is
undefined.  If @var{var-spec} is a list, the default value is
the result of evaluation of the second element of the list.
In the latter case the second
element is only evaluated when there are not enough arguments.
The binding proceeds in the order of @var{var-spec}, so the second
element may refer to the bindings of previous @var{var-spec}.

In the second form, @var{restvar} must be a symbol and bound to
the list of values whatever left from @var{restargs} after binding
to @var{var-spec}.

It is not an error if @var{restarg} has more values than @var{var-spec}s.
The extra values are simply ignored in the first form.

@example
(define (proc x . args)
  (let-optionals* args ((a 'a)
                        (b 'b)
                        (c 'c))
    (list x a b c)))

(proc 0)         @result{} (0 a b c)
(proc 0 1)       @result{} (0 1 b c)
(proc 0 1 2)     @result{} (0 1 2 c)
(proc 0 1 2 3)   @result{} (0 1 2 3)

(define (proc2 . args)
  (let-optionals* args ((a 'a) . b)
    (list a b)))

(proc2)          @result{} (a ())
(proc2 0)        @result{} (0 ())
(proc2 0 1)      @result{} (0 (1))
(proc2 0 1 2)    @result{} (0 (1 2))

(define (proc3 . args)
  (let-optionals* args ((a 0)
                        (b (+ a 1))
                        (c (+ b 1)))
    (list a b c)))

(proc3)          @result{} (0 1 2)
(proc3 8)        @result{} (8 9 10)
(proc3 8 2)      @result{} (8 2 3)
(proc3 8 2 -1)   @result{} (8 2 -1)
@end example
@end defmac

@defmac get-optional restargs default
This is a short version of @code{let-optionals*} where you have only
one optional argument.  Given the optional argument list @var{restargs},
this macro returns the value of optional argument if one is given,
or the result of @var{default} otherwise.  @var{Default} is not
evaluated unless @var{restargs} is an empty list.

@example
(define (proc x . maybe-opt)
  (let ((option (get-optional maybe-opt #f)))
    (list x option)))

(proc 0)         @result{} (0 #f)
(proc 0 1)       @result{} (0 1)
@end example
@end defmac

@defmac let-keywords restarg (var-spec @dots{}) body @dots{}
@defmacx let-keywords restarg (var-spec @dots{} . restvar) body @dots{}
This macro is for keyword arguments.  @var{Var-spec} can be
one of the following forms:

@table @code
@item (@var{symbol} @var{expr})
If the @var{restarg} contains keyword which has the same name as @var{symbol},
binds @var{symbol} to the corresponding value.  If such a keyword doesn't
appear in @var{restarg}, binds @var{symbol} to the result of @var{expr}.
@item (@var{symbol} @var{keyword} @var{expr})
If the @var{restarg} contains keyword @var{keyword},
binds @var{symbol} to the corresponding value.  If such a keyword doesn't
appear in @var{restarg}, binds @var{symbol} to the result of @var{expr}.
@end table

The default value @var{expr} is only evaluated when the keyword is
not given to the @var{restarg}.

If you use the first form, @code{let-keyword} throws an error
when @code{restarg} contains a keyword argument that is not listed
in @var{var-spec}s.
When you want to allow keyword arguments other than listed in
@var{var-spec}s, use the second form.

In the second form, @var{restvar} must be either a symbol or @code{#f}.
If it is a symbol, it is bound to a list of keyword arguments
that are not processed by @var{var-spec}s.  If it is @code{#f},
such keyword arguments are just ignored.

@example
(define (proc x . options)
  (let-keywords options ((a 'a)
                         (b :beta 'b)
                         (c 'c)
                         . rest)
    (list x a b c rest)))

(proc 0)         @result{} (0 a b c ())
(proc 0 :a 1)    @result{} (0 1 b c ())
(proc 0 :beta 1) @result{} (0 a 1 c ())
(proc 0 :beta 1 :c 3 :unknown 4) @result{} (0 a 1 3 (:unknown 4))
@end example
@end defmac

@defmac let-keywords* restarg (var-spec @dots{}) body @dots{}
@defmacx let-keywords* restarg (var-spec @dots{} . restvar) body @dots{}
Like @code{let-keywords}, but the binding is done in the order of
@var{var-spec}s.  So each @var{expr} can refer to the variables bound by
preceding @var{var-spec}s.
@end defmac

@node Procedure arity, Applicable objects, Optional argument parsing, Procedures and continuations
@subsection Procedure arity
@c NODE 手続きのアリティ

Interface to query procedure's arity.
The API is taken from MzScheme (PLT Scheme).

@defun arity @var{proc}
Given procedure @var{proc},
returns an integer, an @emph{arity-at-least} object, or
a list of integer(s) and @emph{arity-at-least} objects.

An integer result indicates @var{proc} takes exactly that number
of arguments.  An @emph{arity-at-least} indicates @var{proc} takes
at least @code{(arity-at-least-value @emph{arity-at-least})}
arguments.   The list indicates there are multiple procedures
with different arities.

Since one can add methods to an existing procedure or generic function
at any moment in Gauche, the value returned by @code{arity} only
indicates the current state of the procedure.  It will change
if new method is added to the procedure/generic-function.

@example
(arity cons) @result{} 2
(arity list) @result{} #<arity-at-least 0>
(arity make) @result{} (#<arity-at-least 1>)
@end example
@end defun

@defun arity-at-least? @var{obj}
Returns true if @var{obj} is an arity-at-least object.
@end defun

@defun arity-at-least-value @var{arity-at-least}
Returns the number of required arguments the arity-at-least object
indicates.
@end defun

@defun procedure-arity-includes? @var{proc} @var{k}
If a procedure @var{proc} can take @var{k} arguments, returns @code{#t}.
Otherwise returns @code{#f}.
@end defun


@node Applicable objects, Continuations, Procedure arity, Procedures and continuations
@subsection Applicable objects
@c NODE 適用可能なオブジェクト

Gauche has a special hook to make an arbitrary object @emph{applicable}.

@deffn {Generic Function} object-apply @var{object} @var{arg} @dots{}
If an object that is neither a procedure nor a generic function
is applied to some arguments,
the object and the arguments are passed to a generic function
@code{object-apply}.

This can be explained better by examples.
@end deffn

For example, suppose you try to evaluate the
following expression:

@example
("abcde" 2)
@end example

The operator evaluates to a string, which is neither a procedure
nor a generic function.  So Gauche interprets the expression
as if it were like this:

@example
(object-apply "abcde" 2)
@end example

Gauche doesn't define a method of @code{object-apply} that takes
@code{<string>} and @code{<integer>} by default, so this signals an error.
However, if you define such a method:

@example
(define-method object-apply ((s <string>) (i <integer>))
  (string-ref s i))
@end example

Then the first expression works as if a string is @emph{applied} on
the integer:

@example
("abcde" 2) @result{} #\c
@end example

This mechanism works on almost all occasions where a procedure is allowed.

@example
(apply "abcde" '(1))   @result{} (#\b)
(map "abcde" '(3 2 1)) @result{} (#\d #\c #\b)
@end example

Among Gauche built-in objects, @code{<regexp>} object and
@code{<regmatch>} object have @code{object-apply} defined.
@xref{Regular expressions}.

Note: Defining @code{object-apply} method affect globally.  Although it is cool
to define @code{object-apply} on strings as in the above example,
it is not recommended as a general trick, for
it'll change the behavior of string across the entire program.

Keep the above example personal experiments.  In general, you should
only define @code{object-apply} on your own classes.


@deffn {Generic Function} {(setter object-apply)} @var{object} @var{arg} @dots{} @var{value}
If a form of applying an applicable object appears in the first position
of @code{set!} form, this method is called, that is:
@example
(set! (@var{object} @var{arg} @dots{}) @var{value})
 @result{} ((setter object-apply) @var{object} @var{arg} @dots{} @var{value})
@end example
@end deffn




@node Continuations, Multiple values, Applicable objects, Procedures and continuations
@subsection Continuations
@c NODE 継続


@defun call-with-current-continuation proc
@defunx call/cc proc
[R7RS base]
Encapsulates the current continuation to a procedure
(``continuation procedure''), and calls @var{proc} with it.
When @var{proc} returns, its value becomes @code{call/cc}'s value.
When the continuation procedure is invoked with zero or more arguments
somewhere, the further calculation is abandoned and @code{call/cc} returns
with the arguments given to the continuation procedure.

First class continuation is one of the most distinct feature of Scheme, but
this margin is too small to contain explanation.
Please consult to the appropriate documents.

There's a nontrivial interaction between C language runtime and
Scheme continuation.   Suppose the following scenario:

@enumerate
@item
An application's C runtime calls back a Scheme routine.  For example,
GUI framework calls back a draw routine written in Scheme.
@item
A continuation is captured in the Scheme routine.
@item
The Scheme routine returns to the C runtime.
@item
The continuation captured in 2 is invoked.
@end enumerate

It is no problem to invoke the continuation, but if the control
is about to return to the Scheme routine to the C runtime (that is,
to execute step 3 again), an error is signaled as follows.

@example
*** ERROR: attempt to return from a ghost continuation.
@end example

This is because C routines don't expect the calling function to return
more than once.  The C stack frame on which the Scheme callback was
originally called
is likely to be deallocated or modified at the time the continuation
is invoked.

If you think of a continuation as a chain of control
frames, growing from root towards upward,
you can imagine that, once a control returns to the C world, the chain is
cut at the boundary.  You can still execute such rootless
continuations, but you have to move the control away from it before it tries
to return to its root that no longer exists.
You can call another continuation, or raise an exception, for example.

Using partial continuations (or delimited continuations) is another
way to avoid such complications.
@xref{Partial continuations}.
@end defun

@defmac let/cc var body @dots{}
This macro expands to :
@code{(call/cc (lambda (@var{var}) @var{body} @dots{}))}.
The API is taken from PLT Scheme.
@end defmac


@defun dynamic-wind before body after
[R7RS base]
This is a primitive to manage @emph{dynamic environment}.
Dynamic environment is a set of states which are kept during execution
of a certain expression.  For example, the current output ports
are switched @emph{during} execution of @code{with-output-to-port}.
They can be nested dynamically, as opposed to
the lexical environment, in which nesting is determined statically
from the program source.

@var{Before}, @var{body} and @var{after} are all procedures with
no arguments.
In normal situation, @code{dynamic-wind} calls @var{before}, then @var{body},
then @var{after}, then returns whatever value(s) @var{body} returned.

The intention is that the @var{before} thunk sets up the dynamic
environment for execution of @var{body}, and the @var{after} thunk
restores it to the previous state.

If a control flow goes out from @var{body} by invoking a continuation
captured outside of the dynamic scope of @code{dynamic-wind}
(for example, an error is signaled in @var{body}),
@var{after} is called.

If a control flow goes into @var{body} by invoking a continuation
captured inside @var{body} from outside of the dynamic
scope of @code{dynamic-wind}, @var{before} is called.
@example
(letrec ((paths '())
         (c #f)
         (add (lambda (s) (push! paths s))))
  (dynamic-wind
   (lambda () (add 'connect))
   (lambda ()
     (add (call/cc (lambda (c0) (set! c c0) 'talk1))))
   (lambda () (add 'disconnect)))
  (if (< (length paths) 4)
      (c 'talk2)
      (reverse paths)))
 @result{} (connect talk1 disconnect connect talk2 disconnect)
@end example

Note: Since @var{after} is guaranteed to be called when
an error causes @var{body} to abort, it may appear tempting
to use @code{dynamic-wind} to use resource clean-up, just like
@code{try-catch} construct in Java.  It's @emph{not} for that.
Since the control may return to @var{body}, the situation
@code{dynamic-wind} handles should be considered more like
a context switch.

For resource clean-up, you can use exception handling mechanism
such as @code{guard} and @code{unwind-protect} (@pxref{Handling exceptions}),
which is built on top of @code{dynamic-wind}.

As a rule of thumb, @var{after} should do things that can be
reverted by @var{before}, such as manipulating error handler stack
(instead of actually handling errors).
@end defun


@node Multiple values, Folding generated values, Continuations, Procedures and continuations
@subsection Multiple values
@c NODE 多値

@defun values obj @dots{}
[R7RS base]
Returns @var{obj} @dots{} as multiple values.
Caller can capture multiple values by a built-in syntax
@code{receive} or @code{let-values}
(@ref{Binding constructs}), or the R7RS procedure
@code{call-with-values} described below.
@example
(values 1 2) @result{} 1 @r{and} 2
@end example
@end defun

@defun call-with-values producer consumer
[R7RS base]
Call a procedure @var{producer} with no argument.
Then applies a procedure @var{consumer} on the
value(s) @var{producer} returned.  Returns the value(s) @var{consumer}
returns.
@example
(call-with-values (lambda () (values 1 2)) cons)
  @result{} (1 . 2)
@end example
@end defun

@defmac values-ref mv-expr k
Returns @var{k}-th value of what @var{mv-expr} returns.
Conceptually, it is the same as the following code.
@example
(call-with-values (lambda () mv-expr) (lambda r (list-ref r k)))
@end example
This macro uses shortcuts for the typical cases like @var{k} is zero.

Similar to Common Lisp's @code{nth-value}, but the argument order
is flipped to match other Scheme's @code{*-ref} procedures.
@end defmac

@defmac values->list mv-expr
Evaluates @var{mv-expr}, puts all the results into a list
and returns it.   It is called @code{multiple-value-list} in
Common Lisp.

@example
(values->list (div-and-mod 10 3)) @result{} (3 1)

(values->list 1) @result{} (1)
@end example
@end defmac

@node Folding generated values,  , Multiple values, Procedures and continuations
@subsection Folding generated values
@c NODE 生成された値の畳み込み

Sometimes a procedure is used as a @emph{generator} of a series
of values, by yielding one value at a time.  Customary an EOF
object is used to mark the end of the series.  For example,
@code{read-char} is such a procedure that yields a series
of characters, terminated by EOF.

Since it is such a handy abstraction, Gauche provides a
set of utilities (see @ref{Generators}) to construct and generators
out of various sources, including other generators.

The generated values needs to be consumed eventually.  Here we
provide several procedures to do that.  These are useful
when combined with input procedures like @code{read}, so we
have them built-in instead of putting them in a separate module.

@defun generator-fold proc seed gen gen2 @dots{}
[R7RS generator]
Works like @code{fold} on the generated values by generator
procedures @var{gen} @var{gen2} @dots{} (@xref{Walking over lists},
for the details of @code{fold}).

When one generator is given, for each value @var{v} generated by @var{gen},
@var{proc} is called as @code{(@var{proc} @var{v} @var{r})}, where
@var{r} is the current accumulated result; the initial value of the
accumulated result is @var{seed},
and the return value from @var{proc} becomes the next accumulated result.
When @var{gen} returns EOF, the accumulated result at that time is returned
from @code{generator-fold}.

When more than one generator is given, @var{proc} is
called as @code{(@var{proc} @var{v1} @var{v2} @dots{} @var{r})},
where @var{v1}, @var{v2} @dots{} are the values yielded from
@var{gen}, @var{gen2}, @dots{}, respectively, and @var{r} is
the current accumulated result.  The iteration terminates when
any one of the generators returns EOF.

@example
(with-input-from-string "a b c d e"
  (cut generator-fold cons 'z read))
  @result{} (e d c b a . z)
@end example
@end defun

@defun generator-fold-right proc seed gen gen2 @dots{}
Works like @code{fold-right} on the generated values by generator
procedures @var{gen} @var{gen2} @dots{} (@pxref{Walking over lists},
for the details of @code{fold-right}).

This is provided for completeness, but it isn't a good way to
handle generators; in order to combine values right-associatively,
we should read all the values from the generators (until any one
of the generator returns EOF), then start
calling @var{proc} as
@example
(proc v0_0 v1_0 ... (proc v0_1 v1_1 ... (proc v0_n v1_n ... seed) ...))
@end example
where @var{vn_m} is the @var{m}-th value yielded by @var{n}-th generator.

@example
(with-input-from-string "a b c d e"
  (cut generator-fold-right cons 'z read))
  @result{} (a b c d e . z)
@end example

As you see, keeping all intermediate values kind of defeats the
benefit of generators.
@end defun

@defun generator-for-each proc gen gen2 @dots{}
[R7RS generator]
A generator version of @code{for-each}.  Repeatedly applies @var{proc} on
the values yielded by @var{gen}, @var{gen2} @dots{} until any one of
the generators yields EOF.  The values returned from @var{proc} are discarded.

This is a handy procedure to consume generated values with side effects.
@end defun

@defun generator-map proc gen gen2 @dots{}
A generator version of @code{map}.  Repeatedly applies @var{proc} on
the values yielded by @var{gen}, @var{gen2} @dots{} until any one of
the generators yields EOF.   The values returned from @var{proc}
are collected into a list and returned.

@example
(with-input-from-string "a b c d e"
  (cut generator-map symbol->string read))
  @result{} ("a" "b" "c" "d" "e")
@end example

The same effects can be achieved by combining @code{generator->list}
and @code{gmap} (@pxref{Generator operations}).  This procedure
is provided for the backward compatibility.

@example
(generator->list (gmap proc gen gen2 @dots{}))
@end example
@end defun

@defun generator-find pred gen
[R7RS generator]
Returns the first item from the generator @var{gen} that satisfies
the predicate @var{pred}.

The following example returns the first line matching the regexp
@code{#/XYZ/} from the file @file{foo.txt}.

@example
(with-input-from-file "foo.txt"
  (cut generator-find #/XYZ/ read-line))
@end example

Note: If you want to pick all the lines matching the regexp,
like the @code{grep} command, 
you can use @code{gfilter} and @code{generator->list}.
@end defun

@c ----------------------------------------------------------------------
@node Parameters, Boxes, Procedures and continuations, Core library
@section Parameters
@c NODE パラメータ

A @emph{parameter} is Scheme's way to implement dynamically scoped states.
In Gauche, it also realizes thread-local storage.
It is codified in srfi-39 and incorporated into R7RS.

It is a special procedure created by @code{make-parameter}.  It accepts
zero or one argument.  When called without an argument, it returns the
current value.  If an argument is passed, it alters its current value
with the given value, and returns the previous value.

Using @code{parameterize} macro, which is similar to @code{let} syntactially,
rebinds the parameters' value during execution of its body, dynamically
rather than lexically.

@example
(define var (make-parameter 0))

(define (show-var) (print (var)))

(show-var)  ; prints 0

(parameterize ((var 1))
  (show-var))    ; prints 1


(define f)

(parameterize ((var 2))
  (set! f (lambda () (show-var))))

(f) ; prints 0, since its out of the dynamic extent of var=2
@end example

If a control trasfers from or to @code{parameterize}'s body by
continuations,
the parameter refers to the value corresponding the dynamic envrionment
it is accessed.

Gauche enhances R7RS parameters in a few ways.

@itemize @bullet
@item
It is thread-local.  A parameter created in one thread can be used
from other threads, but the storage is independent.  When a new thread
is created, it inherits the values of existing parameters.
@item
You can attach observer procedures to a parameter, which is invoked
whenever the value of the parameter is altered, either directly
or by @code{parameterize}.   (This feature is only available
when you use @code{gauche.parameter} module, @pxref{Parameters (extra)}).
@item
You can use generaized @code{set!} with parameters.
@example
(define p (make-parameter 'a))
(p) @result{} a
(set! (p) 'b)
(p) @result{} b
@end example
@end itemize

@defun make-parameter value :optional filter
[R7RS base]
Creates a parameter whose initial value is @var{value}.
If an optional argument @var{filter} is given, it must be
a procedure that takes one argument and returns one value;
whenever the parameter's value is about to change, the procedure
is called with the given value, and the value the procedure
returns will be the parameter's value.  The filter procedure
can raise an error or reject to change the parameter's value.

NB: In 0.9.9 and before, this procedure returns a parameter
object, and we used @code{object-apply} method to make it behave
like a procedure.  However, R7RS explicitly defines the return
values to be a procedure; notably, portable code expects
@code{(procedure? (make-parameter 'z))} returns @code{#t}.

As of 0.9.10, we switched @code{make-procedure} to return
a procedure.  It won't change the external behavior, except
when you test the parameter @var{p} with
@code{(is-a? p <parameter>)}; you have to use @code{parameter?} instead.
@end defun

@defmac parameterize ((param value) @dots{}) body @dots{}
[R7RS base]
Evaluates @var{body} @dots{}, with
change parameter @var{param}'s value to the given @var{value} within
the dynamic scope of @var{body} @dots{}.
Returns the value(s) of the result of the last @var{body}.
@end defmac

Some examples:
@example
(define a (make-parameter 1))
(a) @result{} 1
(a 2) @result{} 1
(a) @result{} 2
(parameterize ((a 3))
  (a)) @result{} 3
(a) @result{} 2
@end example

@defun parameter? obj
Returns @code{#t} iff @var{obj} is an object created by
@code{make-parameter}.

Note: Some built-in procedures such as @code{current-input-port}
behaves like parameters.  They aren't created by @code{make-parameter},
though, and returns @code{#f} for @code{parameter?}.
@end defun

@c ------------------------------------------------------------
@node Boxes, Lazy evaluation, Parameters, Core library
@section  Boxes
@c NODE ボックス

A box is a mutable container that can hold (possibly multiple) values.
It can be used as a minimal data storage, or a sort of mutable indirect
``pointer''.

Traditionally, a list or a vector has been used for this purpose.
However, such datatypes imply sequences of objects,   Using boxes
emphasizes your intention is just for indirection, and not so much for
sequencing.

It is originally introduced by srfi-111, which was later adopted in
R7RS-large as @code{scheme.box}.  Srfi-195 enhances it to deal with
multiple values.

The srfis leaves some details to implementations.  Here are our choices:
@itemize
@item
We don't support autoboxing; that is, it is an error to pass non-box
value to the procedure expecting boxed value and vice versa.
@item
Comparing two boxes with @code{equal?} compares their contents when
two are not @code{eqv?}.  In the spec, when two boxes are @code{eqv?}
then they must also be @code{equal?} to each other, but it's up
to the implementation when two are not @code{eqv?}.
@end itemize

When you're writing portable code, be careful not to depend on the
@code{equal?} behavior.

@defun box val @dots{}
[R7RS box][SRFI-195]
Returns a fresh box object that contains the value @code{val} @dots{}.
@end defun

@defun box? obj
[R7RS box]
Returns @code{#t} iff @var{obj} is a box object.
@end defun

@defun box-arity box
[SRFI-195]
Returns the number of values @var{box} holds.
@end defun

@defun unbox box
[R7RS box]
Returns @var{box}'s content.  If @var{box} has @var{n} values,
it returns @var{n} values.
@end defun

@defun unbox-value box i
[SRFI-195]
Returns @var{i}-th value held in @var{box}.
@end defun

@defun set-box! box val @dots{}
[R7RS box][SRFI-195]
Alters the content of @var{box} with @var{val} @dots{}.
The numer of values must match the arity of the box.
Returns unspecified value.
@end defun

@defun set-box-value! box i val
[SRFI-195]
Alters @var{i}-th value of @var{box} with @var{val}.
Returns unspecified value.
@end defun

@c ------------------------------------------------------------
@node Lazy evaluation, Exceptions, Boxes, Core library
@section  Lazy evaluation
@c NODE 遅延評価

Gauche has two primitive lazy evaluation mechanisms.

The first one is an explicit mechanism, defined in the Scheme
standard: You mark
an expression to be evaluated lazily by @code{delay},
and you use @code{force} to make the evaluation happen when
needed.  Gauche also support another primitive @code{lazy},
as defined in srfi-45, for space-efficient tail-recursive
lazy algorithms.

The second one is a lazy sequence, in which evaluation happens
implicitly.  From a Scheme program, a lazy sequence just looks
as a list---you can take its @code{car} and @code{cdr}, and
you can apply @code{map} or other list procedures on it.  However,
internally, its element isn't calculated until it is required.

@menu
* Delay force and lazy::
* Lazy sequences::
@end menu


@node Delay force and lazy, Lazy sequences, Lazy evaluation, Lazy evaluation
@subsection  Delay, force and lazy
@c NODE Delayとforceとlazy

Scheme has traditionally provided an explicit delayed evaluation mechanism
using @code{delay} and @code{force}.  After R5RS, however,
it is found that it didn't mix well with tail-recursive
algorithms: It required unbound memory, despite that the
body of the algorithm could be expressed in iterative manner.
Srfi-45 showed that introducing another primitive syntax @code{lazy}
addresses the issue.
For the detailed explanation please look at the srfi-45 document.
Here we explain how to use those primitives.

@defspec delay expression
@defspecx lazy expression
[R7RS lazy][SRFI-45]
These forms creates a @emph{promise} that delays the evaluation
of @var{expression}.  @var{Expression} will be evaluated
when the promise is passed to @code{force}.

If @var{expression} itself is expected to yield a promise,
you should use @code{lazy}.  Otherwise, you should use @code{delay}.
If you can think in types, the difference may be clearer.

@example
lazy  : Promise a -> Promise a
delay : a -> Promise a
@end example

Since we don't have static typing, we can't enforce this usage.
The programmer has to choose appropriate one from the context.
Generally, @code{lazy} appears only to surround the entire
body of function that express a lazy algorithm.

NB: In R7RS, @code{lazy} is called @code{delay-force}, for the operation
is conceptually similar to @code{(delay (force expr))} (note that the
type of @code{force} is @code{Promise a -> a}).

For the real-world example of use of @code{lazy},
you may want to check the implementation of @code{util.stream}
(@pxref{Stream library}).
@end defspec

@defun eager obj
[SRFI-45]
Returns a promise that returns the value of @var{obj}.
Since that @code{eager} is a procedure, @var{obj} is evaluated
before @var{eager} is called; so it works as a type converter
(<code>a -> Promise a</code>) without delaying the evaluation.
Used mainly to construct promise-returning functions.
@end defun

@defun force promise
[R7RS lazy]
If @var{promise} is not a promise, it is just returned.

Otherwise, if @var{promise}'s value hasn't been computed,
@code{force} makes @var{promise}'s encapsulated expression
be evaluated, and returns the result.

Once @var{promise}'s value is computed, it is memorized in it
so that subsequent @code{force} on it won't cause the computation.
@end defun

@defun promise? obj
[R7RS lazy]
Returns @code{#t} iff @var{obj} is a promise object.
@end defun

@c TODO example - use lazy tarai function

@node Lazy sequences,  , Delay force and lazy, Lazy evaluation
@subsection  Lazy sequences
@c NODE 遅延シーケンス

@subsubheading Introduction

A lazy sequence is a list-like structure
whose elements are calculated lazily.
Internally we have a special type of pairs, whose @code{cdr}
is evaluated on demand.
However, in Scheme level, you'll never see a distinct
``lazy-pair'' type.   As soon as you try to access a
lazy pair, Gauche automatically @emph{force} the delayed
calculation, and the lazy pair turns into an ordinary pair.

It means you can pass lazy sequences to ordinary list-processing
procedures such as @code{car}, @code{cdr} or @code{map}.

Look at the following example; @code{generator->lseq}
takes a procedure that generates one value at a time, and
returns a lazy sequence that consists of those values.

@example
(with-input-from-file "file"
  (^[] (let loop ([cs (generator->lseq read-char)] [i 0])
         (match cs
           [() #f]
           [(#\c (or #\a #\d) #\r . _) i]
           [(c . cs) (loop cs (+ i 1))]))))
@end example

It returns the position of the first occurrence of
character sequence ``car'' or ``cdr'' in the file @file{file}.
The loop treats the lazy sequence just like an ordinary list, but
characters are read as needed, so once the sequence is
found, the rest of the file won't be read.  If we do
it eagerly, we would have to read the entire file first no matter how
big it is, or to give up using the mighty @code{match} macro and
to write a basic state machine that reads one character one at a time.

Other than implicit forcing, Gauche's lazy sequences are
slightly different than the typical lazy stream implementations in Scheme
in the following ways:

@enumerate
@item
When you construct a lazy sequence in an iterative lazy algorithm,
only @code{cdr} side of the lazy pair is lazily evaluated;
the @code{car} side is evaluated immediately.  On the other hand, with
@code{stream-cons} in @code{util.stream} (@pxref{Stream library}),
both @code{car} and @code{cdr} sides won't be evaluated until
it is absolutely needed.
@item
Gauche's lazy sequence always evaluates @emph{one item ahead}.
Once you get a lazy pair, its @code{car} part is already
calculated, even if you don't use it.  In most cases
you don't need to care, for calculating one item more
is a negligible overhead.  However, when you create
a self-referential lazy structure, in which the earlier
elements of a sequence is used to calculate the latter
elements of itself, a bit of caution is needed;
a valid code for fully lazy circular structure may not
terminate in Gauche's lazy sequences.  We'll show a
concrete example later.  This bit of eagerness
is also visible when side effects are involved;
for example, lazy character sequence reading from a port
may read one character ahead.
@end enumerate

Note: R7RS @code{scheme.lseq} (srfi-127)
provides a portable alternative of lazy sequence
(@pxref{R7RS lazy sequences}).  It uses
dedicated APIs (e.g. @code{lseq-cdr}) to operate on lazy sequences
so that portable implementation is possible.  In Gauche, we just
use our built-in lazy sequence as srfi-127 lazy sequence; if you
want your code to be portable, consider using srfi-127, but be careful
not to mix lazy sequences and ordinary lists; Gauche won't complain,
but other Scheme implementation may choke on it.

@subsubheading Primitives

@defun generator->lseq generator
@defunx generator->lseq item @dots{} generator
[R7RS lseq]
Creates a lazy sequence that consists of items produced
by @var{generator}, which is just a procedure with zero arguments that yields
an item at a time.  Returning EOF marks the end of the sequence
(EOF itself isn't included in the sequence).
For example, @code{read-char} can work as a generator.
Gauche has a set of convenient utilities to deal with generators
(@pxref{Generators}).

In the second form, the returned lazy sequence is prepended by
@var{item} @dots{}.  Since there's no way to distinguish lazy
pairs and ordinary pairs, you can write it as
@code{(cons* item @dots{} (generator->lseq generator))},
but that's more verbose.

Internally, Gauche's lazy sequence is optimized to be built
on top of generators, so this procedure is the most efficient
way to build lazy sequences.

Note: Srfi-127 also has @code{generator->lseq}, which is exactly
the same as this in Gauche.
@end defun

@defmac lcons car cdr
Returns a lazy pair consists of @var{car} and @var{cdr}.
The expression @var{car} is evaluated at the call of @code{lcons},
but evaluation of @var{cdr} is delayed.

You can't distinguish a lazy pair from an ordinary pair.  If you
access either its @code{car} or @code{cdr}, or even you ask @code{pair?}
to it, its cdr part is implicitly forced and you get an ordinary pair.

Unlike @code{cons}, @var{cdr} should be an expression that yields
a (lazy or ordinary) list, including an empty list.
In other words, lazy sequences can always be a null-terminated list
when entirely forced; there are no ``improper lazy sequences''.
(Since Scheme isn't statically typed, we can't force the @var{cdr}
expression to be a proper list before actually evaluating it.
Currently if @var{cdr} expression yields non-list, we just ignore
it and treat as if it yielded an empty list.)

@example
(define z (lcons (begin (print 1) 'a) (begin (print 2) '())))
 @result{} ; prints '1', since the car part is evaluated eagerly.

(cdr z) @result{} () ;; and prints '2'

;; This also prints '2', for accessing car of a lazy pair forces
;; its cdr, even the cdr part isn't used.
(car (lcons 'a (begin (print 2) '()))) @result{} a

;; So as this; asking pair? to a lazy pair causes forcing its cdr.
(pair? (lcons 'a (begin (print 2) '()))) @result{} #t

;; To clarify: This doesn't print '2', because the second lazy
;; pair never be accessed, so its cdr isn't evaluated.
(pair? (lcons 'a (lcons 'b (begin (print 2) '())))) @result{} #t
@end example

Now, let me show you a case where ``one item ahead'' evaluation becomes
an issue.  The following is an elegant definition of infinite
Fibonacci sequence using self-referential lazy structure
(@code{lmap} is a lazy map, defined in @code{gauche.lazy} module):

@example
(use gauche.lazy)  ;; for lmap
(define *fibs* (lcons* 0 1 (lmap + *fibs* (cdr *fibs*)))) ;; BUGGY
@end example

Unfortunately, Gauche can't handle it well.

@example
(car *fibs*)
 @result{} 0
(cadr *fibs*)
 @result{} *** ERROR: Attempt to recursively force a lazy pair.
@end example

When we want to access the second argument (@code{cadr}) of @code{*fibs*},
we take the car of the second pair, 
which is a lazy pair of @code{1} and @code{(lmap ...)}.  The lazy pair
is forced and its cdr part needs to be calculated.  The first thing
@code{lmap} returns needs to see the first and second element of @code{*fibs*},
but the second element of @code{*fibs*} is what we're calculating now!

We can workaround this issue by 
avoiding accessing the immediately preceding value.
Fibonacci numbers F(n) = F(n-1) + F(n-2) = 2*F(n-2) + F(n-3), so we
can write our sequence as follows.

@example
(define *fibs*
  (lcons* 0 1 1 (lmap (^[a b] (+ a (* b 2))) *fibs* (cdr *fibs*))))
@end example

And this works!

@example
(take *fibs* 20)
  @result{} (0 1 1 2 3 5 8 13 21 34 55 89 144 233
     377 610 987 1597 2584 4181)
@end example

Many lazy algorithms are defined in terms of fully-lazy cons
at the bottom.  When you port such algorithms to Gauche using @code{lcons},
keep this bit of eagerness in mind.

Note also that @code{lcons} needs to create a thunk to delay
the evaluation.  So the algorithm to construct lazy list using
@code{lcons} has an overhead of making closure for each item.
For performance-critical part,
you want to use @code{generator->lseq} whenever possible.
@end defmac

@subsubheading Utilities

@defmac lcons* x @dots{} tail
@defmacx llist* x @dots{} tail
A lazy version of @code{cons*} (@pxref{List constructors}).
Both @code{lcons*} and @code{llist*} do the same thing; both
names are provided for the symmetry to @code{cons*}/@code{list*}.

The @var{tail} argument should be an expression that yields a 
(possibly lazy) list.   It is evaluated lazily.  Note that
the preceding elements @var{x} @dots{} are evaluated eagerly.
The following equivalences hold.

@example
(lcons* a)           @equiv{} a
(lcons* a b)         @equiv{} (lcons a b)
(lcons* a b ... y z) @equiv{} (cons* a b @dots{} (lcons y z))
@end example
@end defmac

@defun lrange start :optional end step
Creates a lazy sequence of numbers starting from @var{start},
increasing by @var{step} (default 1), to the maximum value that doesn't
exceed @var{end}.  The default of @var{end} is @code{+inf.0},
so it creates an infinite list.  (Don't type just
@code{(lrange 0)} in REPL, or it won't terminate!)

If any of @var{start} or @code{step} is inexact, the resulting sequence
has inexact numbers.

@example
(take (lrange -1) 3) @result{} (-1 0 1)

(lrange 0.0 5 0.5)
  @result{} (0.0 0.5 1.0 1.5 2.0 2.5 3.0 3.5 4.0 4.5)

(lrange 1/4 1 1/8)
  @result{} (1/4 3/8 1/2 5/8 3/4 7/8)
@end example
@end defun

@defun liota :optional (count +inf.0) (start 0) (step 1)
A lazy version of @code{iota} (@pxref{List constructors}); returns
a lazy sequence of @var{count} integers (default: positive infinity),
starting from @var{start} (default: 0), stepping by @var{step} (default: 1).

Just like @code{iota}, the result consists of exact numbers
if and only if both @var{start} and @var{step} are exact; otherwise
the result consists of inexact numbers.
@end defun

@defun port->char-lseq :optional port
@defunx port->byte-lseq :optional port
@defunx port->string-lseq :optional port
@defunx port->sexp-lseq :optional port
These are the same as the following expressions, respectively.
They are provided for the convenience, since this pattern appears
frequently.

@example
(generator->lseq (cut read-char port))
(generator->lseq (cut read-byte port))
(generator->lseq (cut read-line port))
(generator->lseq (cut read port))
@end example

If @var{port} is omitted, the current input port is used.

Note that the lazy sequence may buffer some items, so 
once you make an lseq from a port, only use the resulting lseq
and don't ever read from @var{port} directly.

Note that the lazy sequence terminates when EOF is read from the port,
but the port isn't closed.  The port should be managed in larger
dynamic extent where the lazy sequence is used.

You can also convert input data into various lists by
the following expressions (@pxref{Input utility functions}).
Those procedures read the port eagerly until EOF and returns
the whole data in a list, while @code{lseq} versions read
the port lazily.

@example
(port->list read-char port)
(port->list read-byte port)
(port->string-list port)
(port->sexp-list port)
@end example

Those procedures make (lazy) lists out of ports.  The opposite can be
done by @code{open-input-char-list} and @code{open-input-byte-list};
@xref{Virtual ports}, for the details.
@end defun


See also @ref{Lazy sequence utilities}, for more utility procedures
that creates lazy sequences.

@subsubheading Examples

Let's consider calculating an infinite sequence of prime numbers.
(Note: If you need prime numbers in your application, you don't
need to write one; just use @code{math.prime}. @pxref{Prime numbers}).

Just pretend we already have some prime numbers
calculated in a variable @code{*primes*}, and you need
to find a prime number equal to or grater than @var{n}
(for simplicity, we assume @var{n} is an odd number).

@example
(define (next-prime n)
  (let loop ([ps *primes*])
    (let1 p (car ps)
      (cond [(> (* p p) n) n]
            [(zero? (modulo n p)) (next-prime (+ n 2))]
            [else (loop (cdr ps))]))))
@end example

This procedure loops over the list of prime numbers, and
if no prime number @var{p} less than or equal to @code{(sqrt n)}
divides @var{n}, we can say @var{n} is prime.  (Actual test
is done by @code{(> (* p p) n)} instead of @code{(> p (sqrt n))},
for the former is faster.)
If we find some @var{p} divides @var{n}, we try a new value
@code{(+ n 2)} with @code{next-prime}.

Using @code{next-prime}, we can make a generator that keeps generating
prime numbers.  The following procedure returns a generator
that returns primes above @var{last}.

@example
(define (gen-primes-above last)
  (^[] (set! last (next-prime (+ last 2))) last))
@end example

Using @code{generator->lseq}, we can turn the generator returned
by @code{gen-primes-above} into a lazy list, which can be used
as the value of @code{*prime*}.  The only caveat is that we need
to have some pre-calculated prime numbers:

@example
(define *primes* (generator->lseq 2 3 5 (gen-primes-above 5)))
@end example

Be careful not to evaluate @code{*primes*} directly on REPL,
since it contains an infinite list and it'll blow up your REPL.
You can look the first 20 prime numbers instead:

@example
(take *primes* 20)
 @result{} (2 3 5 7 11 13 17 19 23 29 31 37 41 43 47 53 59 61 67 71)
@end example

Or find what the 10000-th prime number is:

@example
(~ *primes* 10000)
 @result{} 104743
@end example

Or count how many prime numbers there are below 1000000:

@example
(any (^[p i] (and (>= p 1000000) i)) *primes* (lrange 0))
 @result{} 78498
@end example

Note: If you're familiar with the lazy functional approach, this example
may look strange.  Why do we use side-effecting generators
while we can define a sequence of prime numbers in
pure functional way, as follows?

@example
(use gauche.lazy)

(define (prime? n)
  (not (any (^p (zero? (mod n p)))
            (ltake-while (^k (<= (* k k) n)) *primes*))))

(define (primes-from k)
  (if (prime? k)
    (lcons k (primes-from (+ k 2)))
    (primes-from (+ k 2))))

(define *primes* (llist* 2 3 5 (primes-from 7)))
@end example

(The module @code{gauche.lazy} provides @code{ltake-while}, which
is a lazy version of @code{take-while}.  We don't need lazy version
of @code{any}, since it immediately stops when the predicate returns
a true value.)

The use of @code{lcons} and co-recursion in @code{primes-from}
is a typical idiom in functional programming.  It's perfectly ok
to do so in Gauche; except that the generator version is @emph{much} faster
(when you take first 5000 primes, generator version ran 17 times faster
than co-recursion version on the author's machine).

It doesn't mean you should avoid co-recursive code; if an algorithm
can be expressed nicely in co-recursion, it's perfectly ok.  However,
watch out the subtle semantic difference from lazy functional
languages---straightforward porting may or may not work.

@c ----------------------------------------------------------------------
@node Exceptions, Eval and repl, Lazy evaluation, Core library
@section Exceptions
@c NODE 例外

Gauche's exception system consists of three components;
(1) the way to signal an exceptional case has occurred,
(2) the way to specify how to handle such a case,
and (3) the standard objects (@emph{conditions})
to communicate the code that
signals an exceptional case and the code that handles it.

Those three components are typically used together, so first
we explain the typical usage patterns using examples.  Then
we describe each feature in detail.

Note for terminology: some languages use the word @emph{exception}
to refer to an object used to communicate the code that encountered
an exceptional situation with a handler that deals with it.
Gauche uses a term @emph{condition} to refer to such objects,
following SRFI-35.  @emph{Exception} is the situation, and
@emph{condition} is a runtime object that describes it.

@menu
* Exception handling overview::
* Signaling exceptions::
* Handling exceptions::
* Conditions::
@end menu

@node Exception handling overview, Signaling exceptions, Exceptions, Exceptions
@subsection Exception handling overview
@c NODE 例外処理の概要

@subsubheading Catching specific errors

One of the most typical exception handling is to catch a
specific error raised by some built-in or library procedures.
A macro @code{guard} can be used for such a purpose.  The code
looks like this:

@example
(guard (exc [(condition-has-type? exc <read-error>)
             (format #t "read error!")
             'read-error]
            [else 'other-error])
  (read-from-string "(abc"))
@end example

The cadr of @code{guard} clause is a form of
@code{(@var{variable} @var{clause} @dots{})}.  In this example,
the variable is @code{exc}, and it has two clauses.
Each @var{clause} has the form like the one in @code{cond}.

The cddr of @code{guard} is the body, a list of expressions.  This
example has only one expression, @code{(read-from-string "(abc")}.

@code{guard} starts executing its body.
@code{read-from-string} raises an error of type @code{<read-error>}
when it encounters syntactic errors.  The form @code{guard} intercepts
the error, and binds the condition object to the variable @var{exc},
then checks the clauses following @var{exc} in a similar manner
to @code{cond}---in this case, the thrown condition is of type
@code{<read-error>}, so the test of the first clause is satisfied,
and the rest of clause is executed, i.e. @code{"read error!"} is
printed and a symbol @code{read-error} is returned.

If you're familiar with other languages, you may recognize the
pattern.  The cddr of @code{guard} form is like @var{try} clause
of C++/Java or the cadr of @code{handler-case} of Common Lisp;
and the cdadr of @code{guard} form is like @code{catch} clauses
or the cddr of @code{handler-case}.

In the test expressions it is common to check the type of
thrown condition.  The function @code{condition-has-type?} is
defined in SRFI-35 but it's rather lengthy.  Gauche's condition
classes can also work like a predicate, so you can write the
above expression like this.

@example
(guard (exc [(<read-error> exc)
             (format #t "read error!")
             'read-error]
            [else 'other-error])
  (read-from-string "(abc"))
@end example

@emph{Note:} Generally you can't use @code{is-a?} to test if
the thrown condition is of a specific type, since a condition
may be @emph{compound}.  See @ref{Conditions} about compound
conditions.

If no tests of @var{clause}s satisfy and no @code{else} clause is given,
the exception `falls off' the @code{guard} construct, i.e.
it will be handled by the outer level of @code{guard} form or
top-level.  For example, the following @code{guard} form
only handles @code{<read-error>} and @code{<system-error>};
if the body throws other type of conditions, it must be handled
by outer level.

@example
(guard (exc [(<read-error> exc) (handle-read-error)]
            [(<system-error> exc) (handle-system-error)])
  body @dots{})
@end example

See @ref{Handling exceptions} for more details on @code{guard} and
other lower-level exception handling constructs.


@subsubheading Signaling exceptions from your code

The generic way to signal an exception is to use @code{raise} procedure.

@example
(raise @var{condition})
@end example

You can pass any object to @var{condition}; its interpretation
solely depends on the exception handler.  If you know the code
raises an integer as a condition, you can catch it by @code{guard}
as this:

@example
(guard (exc [(integer? exc) 'raised])
  (raise 3))
@end example

However, as a convention, it is preferable to use an instance
of @code{<condition>} or one of its subclasses.  A macro @code{condition}
can be used to create a condition object.  The following examples
show how to create a condition with some slot values and then raise it.

@example
;; create and raise an error condition
(raise (condition
        (<error> (message "An error occurred."))))

;; create and raise a system error condition
(raise (condition
        (<system-error> (message "A system error occurred.")
                        (errno EINTR))))
@end example

See @ref{Conditions} for the details of @code{condition} macro
and what kind of condition classes are provided.

The most common type of condition is an error condition, so
a convenience procedure @code{error} and @code{errorf} are
provided.  They create an error condition with a message and
raise it.

@example
;; `error' concatenates the arguments into a message.
(unless (integer? obj)
  (error "Integer expected, but got:" obj))

;; `errorf' uses format to create a message.
(unless (equal? x y)
  (errorf "~s and ~s don't match" x y))
@end example

Unlike the exception throwing constructs in some languages,
such as @code{throw} of C++/Java, which abandons its continuation,
Scheme's @code{raise} may return to its caller.   If you don't
want @code{raise} to return, a rule of thumb is always to pass
one of error conditions to it; then Gauche guarantees @code{raise}
wont return.   See the description of @code{raise} in
@ref{Signaling exceptions} for more details.

Note: R7RS adopted slightly different semantics; it splits
@code{raise} and @code{raise-continuable}, the former is for
noncontinuable exception (if the exception handler returns,
it raises another error), and the latter is for continuable
exception.  When you're in R7RS environment, R7RS-compatible
@code{raise} will be used instead of this @code{raise}.

@subsubheading Defining your own condition

You can also define your own condition classes
to pass application-specific information from the point of
raising exception to the handlers.

To fit to Gauche's framework (SRFI-35), it is desirable that
the new condition class inherits a built-in @code{<condition>} class
or one of its descendants, and also is an instance of a metaclass
@code{<condition-meta>}.

One way of ensuring the above convention as well as increasing
portability is to use @code{define-condition-type} macro, defined
in @code{SRFI-35}.

@example
(define-condition-type <myapp-error> <error>
  myapp-error?
  (debug-info myapp-error-debug-info)
  (reason myapp-error-reason))
@end example

This defines a condition type (which is a class in Gauche)
@code{<myapp-error>}, with a predicate @code{myapp-error?}
and slots with accessors.   Then you can use the new
condition type like the following code:

@example
(guard (exc
         [(myapp-error? exc)
          (let ([debug-info (myapp-error-debug-info exc)]
                [reason (myapp-error-reason exc)])
            ... handle myapp-error ...)])
  ...
  ...
  (if (something-went-wrong)
    (raise (condition
             (<myapp-error> (debug-info "during processing xxx")
                            (reason "something went wrong")))))
  ...
  ...
  )
@end example

If you don't mind to lose srfi compatibility, you can use
Gauche's extended @code{error} and @code{errorf} procedures to write
more concise code to raise a condition of subtype of @code{<error>}:

@example
  (if (something-went-wrong)
    (error <myapp-error>
           :debug-info "during processing xxx"
           :reason "something went wrong"))
@end example


See the description of @code{define-condition-type} macro
for how the condition type is implemented in Gauche's object system.

@node Signaling exceptions, Handling exceptions, Exception handling overview, Exceptions
@subsection Signaling exceptions
@c NODE 例外の通知

@subsubheading Signaling errors

The most common case of exceptions is an error.
Two convenience functions to signal an error condition
in simple cases are provided.
To signal a compound condition, you can use @code{raise} as explained below.

@defun error string arg @dots{}
@defunx error condition-type keyword-arg @dots{} string arg @dots{}
[R7RS+][SRFI-23+] 
Signals an error.  The first form creates an @code{<error>}
condition, with a message consists of @var{string} and @var{arg} @dots{},
and raises it.  It is compatible to R7RS and SRFI-23's @code{error} behavior.

@example
gosh> (define (check-integer x)
        (unless (integer? x)
           (error "Integer required, but got:" x)))
check-integer
gosh> (check-integer "a")
*** ERROR: Integer required, but got: "a"
Stack Trace:
_______________________________________
@end example

The second form can be used to raise an error other than the
@code{<error>} condition.  @var{condition-type} must be
a condition type (see @ref{Conditions} for more explanation of
condition types).  It may be followed by keyword-value list
to initialize the condition slots, and then optionally followed by
a string and other objects that becomes an error message.

@example
(define-condition-type <my-error> <error> #f
  (reason)
  (priority))

...
  (unless (memq operation *supported-operations*)
    (error <my-error>
           :reason 'not-supported :priority 'urgent
           "Operation not supported:" operation))
...
@end example
@end defun

@defun errorf fmt-string arg @dots{}
@defunx errorf condition-type keyword-arg @dots{} fmt-string arg @dots{}
Similar to @code{error}, but the error message is formatted by
@code{format}, i.e. the first form is equivalent to:
@example
(define (errorf fmt . args)
  (error (apply format #f fmt args)))
@end example

The second form can be used to raise an error other than an
@code{<error>} condition.  Meaning of @var{condition-type} and
@var{keyword-arg}s are the same as @code{error}.
@end defun

@subsubheading Signaling generic conditions

@defun raise condition
[SRFI-18][R7RS base]
This is the base mechanism of signaling exceptions.

The procedure invokes the current exception handler.
The argument @var{condition} represents the nature of the exception,
and passed to the exception handler.
Gauche's built-in and library functions always use
an instance of @code{<condition>} or one of its subclasses as @var{condition},
but you can pass any Scheme object to @code{raise}.  The interpretation
of @var{condition} is up to the exception handler.

@emph{Note:} Unlike some of the mainstream languages in which
"throwing" an exception never returns, you can set up an exception
handler in the way that @code{raise} may return.  The details
are explained in @ref{Handling exceptions}.

If you don't want @code{raise} to return, the best way is to
pass a condition which is an instance of @code{<serious-condition>}
or one of its subclasses.  Gauche's internal mechanism
guarantees raising such an exception won't return.
See @ref{Conditions} for the hierarchy of built-in conditions.

R7RS adopted slightly different semantics regarding returning from
@code{raise}; in R7RS, @code{raise} never returns---if the exception
handler returns, another exception is raised.
R7RS has @code{raise-continuable} to explicitly allow returning from
the exception handler.  For portable programs, always
pass @code{<serious-condition>} or its subclasses to @code{raise}.
@end defun


@node Handling exceptions, Conditions, Signaling exceptions, Exceptions
@subsection Handling exceptions
@c NODE 例外の処理

@subsubheading High-level exception handling mechanism

@defmac guard (var clause @dots{}) body @dots{}
[R7RS base]
This is @emph{the} high-level form to handle errors in Gauche.

@var{var} is a symbol, and @var{clause}s are the same form as
@code{cond}'s clauses, i.e. each clause can be either one of
the following forms:
@enumerate
@item
@code{(@var{test} @var{expr} @dots{})}
@item
@code{(@var{test} => @var{proc})}
@end enumerate

The last @var{clause} may be @code{(else @var{expr} @dots{})}.

This form evaluates @var{body} @dots{} and returns the value(s) of
the last @var{body} expression in normal case.
If an exception is raised during the evaluation of body expressions,
the raised exception is bound to a variable @var{var}, then
evaluates @var{test} expression of each clause.  If one of @var{test}
expressions returns true value, then the corresponding @var{expr}s
are evaluated if the clause is the first form above, or an @var{proc}
is evaluated and the result of @var{test} is passed to the procedure
@var{proc} if the clause is the second form.

When the @var{test}(s) and @var{expr}(s) in the clauses are evaluated,
the exception handler that is in effect of the caller of @code{guard} are
installed; that is, if an exception is raised again within @var{clause}s,
it is handled by the @emph{outer} exception handler or @code{guard} form.

If no @var{test} returns true value and the last @code{clause} is
@code{else} clause, then the associated @var{expr}s are evaluated.
If no @var{test} returns true value and there's no @code{else} clause,
the raised exception is re-raised, to be handled by the outer exception
handler.

When the exception is handled by one of @code{clause}s, @code{guard}
returns the value(s) of the last @var{expr} in the handling clause.

The @var{clause}s are evaluated in the same dynamic environment as
the @code{guard} form, i.e. any @code{dynamic-wind}s inside @code{body}
are unwound before evaluation of the @var{clause}s.  It is different
from the lower level forms
@code{with-error-handler} and @code{with-exception-handler}, whose
handler is evaluated before the dynamic environment are unwound.

@example
(let ([z '()])
  (guard (e [else (push! z 'caught)])
    (dynamic-wind (lambda () (push! z 'pre))
                  (lambda () (error "foo"))
                  (lambda () (push! z 'post))))
  (reverse z))
 @result{} (pre post caught)

(guard (e [else (print 'OUTER) #f])
  (with-output-to-string
    (lambda ()
      (print 'INNER)
      (error "foo"))))
 @result{} prints OUTER to the current output port of guard,
      not to the string port.
@end example
@end defmac

@defmac unwind-protect expr cleanup @dots{}
Executes @var{expr}, then executes @var{cleanup}s, and
returns the result(s) of @var{expr}.  If an uncontinuable exception is raised
within @var{expr}, @var{cleanup}s are executed before the
exception escapes from the @code{unwind-protect} form.
For example, the following code calls @code{start-motor},
@code{drill-a-hole}, and @code{stop-motor} in order if
everything goes ok, and if anything goes wrong in @code{start-motor}
or @code{drill-a-hole}, @code{stop-motor} is still called
before the exception escapes @code{unwind-protect}.

@example
(unwind-protect
  (begin (start-motor)
         (drill-a-hole))
  (stop-motor))
@end example

The @var{cleanup} forms are evaluated in the same dynamic environment
as @code{unwind-protect}.
If an exception is thrown within @var{cleanup}, it will be
handled outside of the @code{unwind-protect} form.

Although this form looks similar to @code{dynamic-wind}, they
work at different layers and should not be confused.
@code{dynamic-wind} is the bottom-level
building block and used to manage current exception handlers,
current i/o ports, parameters, etc.
@code{dynamic-wind}'s @var{before} and @var{after} thunks are
called whenever any of those control flow transition occurs.
On the other hand, @code{unwind-protect} only cares about
the Gauche's exception system.  @code{unwind-protect}'s @var{cleanup}
is called only when @var{expr} exits normally or
throws Gauche's exception.
In the above example, if control escapes from @code{drill-a-hole}
by calling a continuation captured outside of @code{unwind-protect},
@var{cleanup} is not called; because the control may return to
@code{drill-a-hole} again.  It can happen if user-level thread
system is implemented by @code{call/cc}, for example.

You can go back to the body @var{expr}
from outside of @code{unwind-protect} by invoking continuations
captured within @var{expr}.

However, keep in mind that once @var{cleanup} are executed,
some resources might not be available in @var{expr}.
We still allow it since the reexecuted part of @var{expr} may not
depend on the resources cleaned up with @var{cleanup}.

Even if @var{expr} returns (normally or abnormally),
@var{cleanup} only executed once, in the first time.

The name of this form is taken from Common Lisp.  Some Scheme
systems have similar macros in different names, such as
@code{try-finally}.
@end defmac


@defun with-error-handler handler thunk
Makes @var{handler} the active error handler and executes @var{thunk}.
If @var{thunk} returns normally, the result(s) will be returned.
If an error is signaled during execution of @var{thunk},
@var{handler} is called with one argument, an exception object
representing the error, with the continuation of @code{with-error-handler}.
That is, @code{with-error-handler} returns whatever value(s) @var{handler}
returns.

If @var{handler} signals an error, it will be handled by the
handler installed when @code{with-error-handler} called.

The dynamic environment where @var{handler} is executed is
the same as the error occurs.  If @code{dynamic-wind} is used
in @var{thunk}, its @var{after} method is called after @var{handler}
has returned, and before @code{with-error-handler} returns.

Note: Using this procedure directly is @emph{no longer recommended}, since
@code{guard} is more safe and portable.  We'll keep this for
a while for the backward compatibility, but we recommend to rewrite
code to use @code{guard} instead of this.
The common idiom of "cleanup on error"
code:
@example
(with-error-handler (lambda (e) (cleanup) (raise e))
  (lambda () body @dots{}))
@end example
should be written like this:
@example
(guard (e [else (cleanup) (raise e)])
  body @dots{})
@end example
@end defun


@subsubheading Behavior of unhandled exception

If an exception is raised where no program-defined exception handler is
installed, the following action is taken.

@enumerate
If an unhandled exception occurs within a thread other than the primordial
one, it terminates the thread, and the thrown condition 
is wrapped by @code{<uncaught-exception>} condition and stored in the
thread object.  If other thread calls @code{thread-join!} to retrieve
result, the the @code{<uncaught-exception>} is thrown in that thread.
Note that no messages are displayed when the original uncaught exception
is thrown.  @xref{Thread programming tips}, for the details.
@item
Otherwise,
if the program is running interactively (in repl), the information
of the thrown exception and stack trace are displayed, and
the program returns to the toplevel prompt.
@item
If the program is running non-interactively, the information
of the thrown exception and stack trace are displayed, then
the program exits with an exit status @code{EX_SOFTWARE} (70).
@end enumerate

The default error message and stack trace in the above case 2 and case 3
is printed by @code{report-error} procedure.  You can use it
in your error handler if you need the same information.

@defun report-error exn :optional sink
Prints type and message of a thrown condition object @var{exn},
then print the current stack trace.  This is the procedure
the system calls when you see an error reported on REPL.

Since you can @code{raise} any object, @var{exn} can be any
object; it's not needed to be an instance of @code{<condition>}. 
A suitable message is chosen by @code{report-error}.

You can specify where the output goes by the optional @var{sink}
argument: If it is an output port, the output goes there; you can
also pass @code{#t} for the current output port and @code{#f} for
the output string port, just like @code{format}.  That is, when
you pass @code{#f}, the message goes to a temporary output string
port, and gathered string is returned.  For all the other cases,
an undefined value is returned.  If @var{sink} is omitted or
any other object listed above, the current error port is used.

Note: As of 0.9.5, this procedure prints stack trace of
the context where @code{report-error} is called, rather than
the context where @var{exn} is thrown.  It doesn't matter much
as far as you call @code{report-error} directly inside the
error handler, but in general what
you want to print is the latter, and we have a plan to
attach stack trace info to @code{<condition>} object in future.
@end defun


@subsubheading Low-level exception handling mechanism

This layer provides SRFI-18 compatible simple exception mechanism.
You can override the behavior of higher-level constructs such as
@code{with-error-handler} by using @code{with-exception-handler}.

Note that it is a double-edged sword.  You'll get a freedom to
construct your own exception handling semantics, but the Gauche
system won't save if something goes wrong.   Use these primitives
when you want to customize the system's higher-level semantics
or you are porting from other SRFI-18 code.

@defun current-exception-handler
[SRFI-18]
Returns the current exception handler.
@end defun

@defun with-exception-handler handler thunk
[SRFI-18]
A procedure @var{handler} must take one argument.  This procedure
sets @var{handler} to the current exception handler and calls
@var{thunk}.
(Note that this slightly differs from R7RS @code{with-exception-handler};
we'll explain it below.)
@end defun

When an exception is raised by @code{raise} or @code{error},
@var{handler} is called with the thrown condition in the
exactly same dynamic environment of @code{raise} or @code{error}.
It means the exception handler is also the same,
so calling @code{raise} in @var{handler} reinvokes @var{handler} again.
It also means that when @var{handler} returns, it returns from
@var{raise}.

The behavior is specified in SRFI-18, intending this procedure
to be the most primitive building block of exception handling mechanism.
If you need to switch handlers, you can do it by yourself.

If you need the typical semantics where raising exception in
the exception handler is handled by outer handler, you should use @code{guard}.
Use this procedure only when you want to play with the most
primitive layer of exception handling.

R7RS has a procedure with the same name, but has one difference---it
changes the active exception handler to the ``outer'' handler before
calling @var{handler}.  @xref{R7RS base library}, for the description
of R7RS's @code{with-exception-handler}.

If an exception is raised by @code{error}, or the thrown condition
inherits @code{<serious-condition>}, it is prohibited to return from
@var{handler}.  If @var{handler} ever returns in such cases, another
error is signaled, with replacing the current exception handler to the
outer handler.  So the caller of @code{error}, or the caller of @code{raise}
with @code{<serious-condition>}, can assume it never returns.

The behavior of those procedures can be explained in
the following conceptual Scheme code.

@example
;; @r{Conceptual implementation of low-level exception mechanism.}
;; @r{Suppose %xh is a list of exception handlers}

(define (current-exception-handler) (car %xh))

(define (raise exn)
  (receive r ((car %xh) exn)
    (when (uncontinuable-exception? exn)
      (set! %xh (cdr %xh))
      (raise (@r{@i{make-error}} "returned from uncontinuable exception")))
    (apply values r)))

(define (with-exception-handler handler thunk)
  (let ((prev %xh))
    (dynamic-wind
      (lambda () (set! %xh (cons handler %xh)))
      thunk
      (lambda () (set! %xh prev)))))
@end example


@node Conditions,  , Handling exceptions, Exceptions
@subsection Conditions
@c NODE コンディション

@subsubheading Built-in Condition classes

Gauche currently has the following hierarchy of built-in condition
classes.  It approximately reflects SRFI-35 and SRFI-36 condition hierarchy,
although they have Gauche-style class names.  If there's a corresponding
SRFI condition type, the class has the SRFI name as well.

@example
  <condition>
    +- <compound-condition>
    +- <serious-condition>
    |    +- <serious-compound-condition> ; also inherits <compound-condition>
    +- <message-condition>
         +- <error>                      ; also inherits <serious-condition>
              +- <system-error>
              +- <unhandled-signal-error>
              +- <read-error>
              +- <io-error>
                   +- <port-error>
                        +- <io-read-error>
                        |    +- <io-decoding-error>
                        +- <io-write-error>
                        |    +- <io-encoding-error>
                        +- <io-closed-error>
                        +- <io-unit-error>
                        +- <io-invalid-position-error>
@end example

Note that some conditions may occur simultaneously; for example,
error during reading from a file because of device failure may consist
both @code{<system-error>} @emph{and} @code{<io-read-error>}.
In such cases, a @emph{compound condition} is raised.
So you can't just use, for instance, @code{(is-a? obj <io-read-error>)}
to check if @code{<io-read-error>} is thrown.
See the "Condition API" section below.

@deftp {Metaclass} <condition-meta>
@clindex condition-meta
Every condition class is an instance of this class.
This class defines @code{object-apply} so that you can use
a condition class as a predicate, e.g.:

@example
(<error> obj) @equiv{} (condition-has-type? obj <error>)
@end example
@end deftp


@deftp {Class} <condition>
@deftpx {Condition Type} &condition
@clindex condition
@vindex &condition
[SRFI-35]
The root class of the condition hierarchy.
@end deftp

@deftp {Class} <compound-condition>
@clindex compound-condition
Represents a compound condition.  A compound condition can be
created from one or more conditions by @code{make-compound-condition}.
Don't use this class directly.

A compound condition returns @code{#t} for @code{condition-has-type?}
if any of the original conditions has the given type.
@end deftp

@deftp {Class} <serious-condition>
@deftpx {Condition Type} &serious
@clindex serious-condition
@vindex &serious
[SRFI-35]
Conditions of this class are for the situations that are too serious
to ignore or continue.  Particularly, you can safely assume that
if you @code{raise} this type of condition, it never returns.
@end deftp

@deftp {Class} <serious-compound-condition>
@clindex serious-compound-condition
This is an internal class to represent a compound condition
with any of its component condition is serious.   Inherits both
@code{<compound-condition>} and @code{<serious-condition>}.
@code{make-compound-condition} uses this class if the passed
conditions includes a serious one.
Don't use this class directly.
@end deftp

@deftp {Class} <message-condition>
@deftpx {Condition Type} &message
@clindex message-condition
[SRFI-35]
This class represents a condition with a message.  It has one slot.

@defivar {<message-condition>} message
A message.

@end defivar
@end deftp

@deftp {Class} <error>
@deftpx {Condition Type} &error
@clindex error
@vindex &error
[SRFI-35]
Indicates an error.  Inherits @code{<serious-condition>}
and @code{<message-condition>}, thus has @code{message} slot.

Note: SRFI-35 @code{&error} condition only inherits @code{&serious}
and not @code{&message}, so you have to use compound condition
to attach a message to the error condition.  Gauche uses multiple
inheritance here, largely because of backward compatibility.
To write a portable code, an error condition should be used
with a message condition, like this:

@example
(condition
  (&message (message "Error message"))
  (&error))
@end example
@end deftp

@deftp {Class} <system-error>
@clindex system-error
A subclass of @code{<error>}.
When a system call returns an error, this type of exception is
thrown.  The @code{message} slot usually contains the description
of the error (like the one from @code{strerror(3)}).
Besides that, this class has one more instance slot:

@defivar {<system-error>} errno
Contains an integer value of system's error number.

Error numbers may differ among systems.  Gauche defines
constants for typical Unix error values (e.g. @code{EACCES}, @code{EBADF},
etc), so it is desirable to use them instead of literal numbers.
See the description of @code{sys-strerror} in @ref{System inquiry}
for available constants.
@end defivar

This class doesn't have corresponding SRFI condition type,
but important to obtain OS's raw error code.  In some cases,
this type of condition is compounded with other condition
types, like @code{<io-read-error>}.
@end deftp

@deftp {Class} <unhandled-signal-error>
@clindex unhandled-signal-error
A subclass of @code{<error>}.  The default handler of most of
signals raises this condition.   See @ref{Handling signals} for
the details.
@defivar {<unhandled-signal-error>} signal
An integer indicating the received signal number.
There are constants defined for typical signal numbers; see
@ref{Signals and signal sets}.
@end defivar
@end deftp

@deftp {Class} <read-error>
@deftpx {Condition Type} &read-error
@clindex read-error
@vindex &read-error
[SRFI-36]
A subclass of @code{<error>}.
When the reader detects a lexical or syntactic error during
reading an S-expression, this type of condition is raised.

@defivar {<read-error>} port
A port from which the reader is reading.
(NB: SRFI-36's @code{&read-error} doesn't have this slot.  Portable
program shouldn't rely on this slot).
@end defivar

@defivar {<read-error>} line
A line count (1-base) of the input where the reader raised this error.
It may be -1 if the reader is reading from a port that doesn't keep
track of line count.
@end defivar

@defivar {<read-error>} column
@defivarx {<read-error>} position
@defivarx {<read-error>} span
These slots are defined in SRFI-36's @code{&read-error}.
For the time being, these slots always hold @code{#f}.
@end defivar

@end deftp

@deftp {Class} <io-error>
@deftpx {Condition Type} &io-error
@clindex io-error
@vindex &io-error
[SRFI-36]
A base class of I/O errors.  Inherits @code{<error>}.
@end deftp

@deftp {Class} <port-error>
@deftpx {Condition Type} &io-port-error
@clindex port-error
@vindex &io-port-error
[SRFI-36]
An I/O error related to a port.   Inherits @code{<io-error>}.

@defivar <port-error> port
Holds the port where the error occurred.
@end defivar
@end deftp

@deftp {Class} <io-read-error>
@deftpx {Condition Type} &io-read-error
@clindex io-read-error
@vindex &io-read-error
[SRFI-36]
An I/O error during reading from a port.  Inherits @code{<port-error>}.
@end deftp

@deftp {Class} <io-write-error>
@deftpx {Condition Type} &io-write-error
@clindex io-write-error
@vindex &io-write-error
[SRFI-36]
An I/O error during writing to a port.  Inherits @code{<port-error>}.
@end deftp

@deftp {Class} <io-closed-error>
@deftpx {Condition Type} &io-closed-error
@clindex io-closed-error
@vindex &io-closed-error
[SRFI-36]
An I/O error when read/write is attempted on a closed port.
Inherits @code{<port-error>}.
@end deftp

@deftp {Class} <io-unit-error>
@clindex io-unit-error
An I/O error when the read/write is requested with a unit
that is not supported by the port (e.g. a binary I/O is requested
on a character-only port).   Inherits @code{<port-error>}.
@end deftp


@subsubheading Condition API

@defmac define-condition-type name supertype predicate field-spec @dots{}
[SRFI-35+]
Defines a new condition type.  In Gauche, a condition type is
a class, whose metaclass is @code{<condition-meta>}.

@var{Name} becomes the name of the new type, and also the variable
of that name is bound to the created condition type.
@var{Supertype} is the name of the supertype (direct superclass)
of this condition type.  A condition type must inherit from
@code{<condition>} or its descendants.
(Multiple inheritance can't be specified by this form, and generally
should be avoided in condition type hierarchy.  Instead, you
can use compound conditions, which don't introduce multiple inheritance.)

A variable @var{predicate} is bound to a predicate procedure for
this condition type.

Each @code{field-spec} is a form of @code{(field-name accessor-name)},
and the condition will have fields named by @var{field-name}, and
a variable @var{accessor-name} will be bound to a procedure that
accesses the field.   In Gauche, each field becomes a slot of
the created class.

Gauche extends srfi-35 to allow @var{predicate} and/or @code{accessor-name}
to be @code{#f}, or @code{accessor-name} to be omitted,
if you don't need to them to be defined.

When @code{define-condition-type} is expanded into a class
definition, each slot gets a @code{:init-keyword} slot option
with the keyword whose name is the same as the slot name.
@end defmac

@defun condition-type? obj
[SRFI-35]
Returns @code{#t} iff @var{obj} is a condition type.  In Gauche,
it means @code{(is-a? obj <condition-meta>)}.
@end defun

@defun make-condition-type name parent field-names
[SRFI-35]
A procedural version to create a new condition type.
@end defun

@defun make-condition type field-name value @dots{}
[SRFI-35]
Creates a new condition of condition-type @var{type}, and
initializes its fields as specified by @code{field-name} and @code{value}
pairs.
@end defun

@defun condition? obj
[SRFI-35]
Returns @code{#t} iff @var{obj} is a condition.  In Gauche,
it means @code{(is-a? obj <condition>)}.
@end defun

@defun condition-has-type? obj type
[SRFI-35]
Returns @code{#t} iff @var{obj} belongs to a condition type @var{type}.
Because of compound conditions, this is not equivalent to @code{is-a?}.
@end defun

@defun condition-ref condition field-name
[SRFI-35]
Retrieves the value of field @var{field-name} of @var{condition}.
If @var{condition} is a compound condition, you can access to the
field of its original conditions; if more than one original condition
have @var{field-name}, the first one passed to @code{make-compound-condition}
has precedence.

You can use @code{slot-ref} and/or @code{ref} to access to the field
of conditions; compound conditions define a @code{slot-missing} method
so that @code{slot-ref} behaves as if the compound conditions have all the
slots of the original conditions.  Using @code{condition-ref} increases
portability, though.
@end defun

@defun condition-message condition :optional fallback
This is a convenience procedure to retrieve a message if
@var{condition} has a type @code{<message-condition>},
and returns @var{fallback} otherwise.  If @var{fallback}
is omitted, @code{#f} is assumed.

Often, in a generic routine you want to intercept a raised
condition and retrieve a message for logging or user feedback.
Since any object can be raised in Scheme, an exception may not
contain the message slot, and you need to check the type
of the condition.  We've written such code enough so that we
add this procedure.
@end defun

@defun make-compound-condition condition0 condition1 @dots{}
[SRFI-35]
Returns a compound condition that has all @var{condition0} @var{condition1}
@dots{}.  The returned condition's fields are the union of all the fields
of given conditions; if any conditions have the same name of fields,
the first one takes precedence.   The returned condition also has
condition-type of all the types of given conditions.
(This is not a multiple inheritance.  See @code{<compound-condition>} above.)
@end defun

@defun extract-condition condition condition-type
[SRFI-35]
@var{Condition} must be a condition and have type @var{condition-type}.
This procedure returns a condition of @var{condition-type},
with field values extracted from @var{condition}.
@end defun

@defmac condition type-field-binding @dots{}
[SRFI-35]
A convenience macro to create a (possibly compound) condition.
@var{Type-field-binding} is a form of
@code{(@var{condition-type} (@var{field-name} @var{value-expr}) @dots{})}.

@example
(condition
  (type0 (field00 value00) ...)
  (type1 (field10 value10) ...)
  ...)
 @equiv{}
(make-compound-condition
  (make-condition type0 'field00 value00 ...)
  (make-condition type1 'field10 value10 ...)
  ...)
@end example
@end defmac


@c ----------------------------------------------------------------------
@node Eval and repl, Input and output, Exceptions, Core library
@section Eval and repl
@c NODE eval と repl

@defun eval expr env
[R7RS eval]
Evaluate @var{expr} under the environment @var{env}.
In Gauche, @var{env} is just a @code{<module>} object.
@end defun

R5RS and R7RS provide a portable way to obtain environment.
R5RS way is described below.  R7RS way is
described in @ref{R7RS eval}.

@defun null-environment version
@defunx scheme-report-environment version
@defunx interaction-environment
[R5RS]
Returns an environment specifier which can be used as the second
argument of @code{eval}.   Right now an environment specifier
is just a module.  @code{(null-environment 5)} returns
a @code{null} module, which contains just the syntactic bindings
specified in R5RS, @code{(scheme-report-environment 5)}
returns a @code{scheme} module, which contains syntactic and procedure
bindings in R5RS, and @code{(interaction-environment)} returns
a @code{user} module that contains all the Gauche built-ins plus
whatever the user defined.
It is possible that the Gauche adopts a first-class environment object
in future, so do not rely on the fact that the environment specifier
is just a module.

An error is signaled if a value other than 5 is passed as @var{version}
argument.
@end defun

@defun read-eval-print-loop :optional reader evaluator printer prompter
This exports @code{Gosh}'s default read-eval-print loop to applications.
Each argument can be @code{#f}, which indicates it to use Gauche's
default procedure(s), or a procedure that satisfies the
following conditions.

@table @emph
@item reader
A procedure that takes no arguments.  It is supposed to read an expression
and returns it.
@item evaluator
A procedure that takes two arguments, an expression and an environment
specifier.  It is supposed to evaluate the expression and returns zero or
more value(s).
@item printer
A procedure that takes zero or more arguments.   It is supposed to
print out these values.   The result of this procedure is discarded.
@item prompter
A procedure that takes no arguments.  It is supposed to print
out the prompt.   The result of this procedure is discarded.
@end table

Given those procedures, @code{read-eval-print-loop} runs as follows:

@enumerate
@item
Prints the prompt by calling @var{prompter}.
@item
Reads an expression by calling @var{reader}.  If it returns EOF,
exits the loop and returns from @code{read-eval-print-loop}.
@item
Evaluates an expression by calling @var{evaluator}
@item
Prints the result by calling @var{printer}, then repeats from 1.
@end enumerate

When an error is signaled from one of those procedures, it is
captured and reported by the default escape handler, then
the loop restarts from 1.

It is OK to capture a continuation within those procedures
and re-invoke them afterwards.
@end defun

@c ----------------------------------------------------------------------
@node Input and output, Loading Programs, Eval and repl, Core library
@section Input and Output
@c NODE 入出力

@menu
* Ports::
* Port and threads::
* Common port operations::
* File ports::
* String ports::
* Coding-aware ports::
* Input::
* Output::
@end menu

@node Ports, Port and threads, Input and output, Input and output
@subsection Ports
@c NODE ポート

@deftp {Builtin Class} <port>
@clindex port
A port class.   A port is Scheme's way of abstraction of I/O channel.
Gauche extends a port in number of ways so that it can be used
in wide range of applications.  

@table @asis
@item Textual and binary I/O
R7RS defines textual and binary ports.  In Gauche, most ports
can mix both text I/O and binary I/O.  It is cleaner to think
the two is distinct, for they are sources/sinks of different types of
objects and you don't need to mix textual and binary I/O.

In practice, however, a port is often a tap to an
untyped pool of bytes and you may want to decide
interpret it later.  One example is the standard I/O; in Unix-like
environment, it's up to the program to use pre-opened ports
for textual or binary I/O.  R7RS defines the initial ports
for @code{current-input-port} etc. are textual ports; in Gauche,
you can use either way.

@item Conversion
Some ports can be used to convert a data stream from one format
to another; one of such applications is character code conversion
ports, provided by @code{gauche.charconv} module
(@pxref{Character code conversion}, for details).

@item Extra features
There are also a ports with special functionality.
A coding-aware port (@pxref{Coding-aware ports}) recognizes a special
"magic comment" in the file to know which character encoding the
file is written.
Virtual ports (@pxref{Virtual ports}) allows you to program the
behavior of the port in Scheme.
@end table

@end deftp

@node Port and threads, Common port operations, Ports, Input and output
@subsection Port and threads
@c NODE ポートとスレッド

When Gauche is compiled with thread support,
the builtin port operations locks the port, so that port access
from multiple threads will be serialized.
(It is required by SRFI-18, BTW).
Here, "builtin port operations" are the port access functions
that takes a port and does some I/O or query on it,
such as @code{read}/@code{write}, @code{read-char}/@code{write-char},
@code{port->string}, etc.
Note that @code{call-with-*} and @code{with-*} procedures do not
lock the port during calling the given procedures, since the
procedure may pass the reference of the port to the other thread,
and Gauche wouldn't know if that's the case.

This means you don't need to be too paranoia to worry about
ports under multithreaded environment.  However, keep it in
mind that this locking mechanism is meant to be a safety net
from breaking the port's internal state, and not to be
a general mutex mechanism.  It assumes port accesses rarely
conflict, and uses spin lock to reduce the overhead of majority
cases.  If you know there will be more than one thread accessing
the same port, you should use explicit mutex to avoid conflicts.

@defun with-port-locking port thunk
Executes @var{thunk}, while making the calling thread
hold the exclusive lock of @var{port} during the dynamic extent
of @var{thunk}.

Calls of the builtin port functions during the lock is held
would bypass mutex operations and yield better performance.

Note that the lock is held during the dynamic extent of @var{thunk};
so, if @var{thunk} invokes a continuation captured outside of
@code{with-port-locking}, the lock is released.  If the continuation
captured within @var{thunk} is invoked afterwards, the lock is re-acquired.

@code{With-port-locking} may be nested.  The lock is valid during
the outermost call of @code{with-port-locking}.

Note that this procedure uses the port's built-in lock mechanism
which uses busy wait when port access conflicts.  It should be
used only for avoiding fine-grain lock overhead; use explicit
mutex if you know there will be conflicts.
@end defun

@node Common port operations, File ports, Port and threads, Input and output
@subsection Common port operations
@c NODE ポート共通の操作

@defun port? obj
@defunx input-port? obj
@defunx output-port? obj
[R7RS base]
Returns true if @var{obj} is a port, an input port and an output port,
respectively.  @code{Port?} is not listed in the
R5RS standard procedures, but mentioned in the "Disjointness of Types"
section.
@end defun

@defun port-closed? port
Returns true if @var{obj} is a port and it is already closed.
A closed port can't be reopened.
@end defun

@deffn {Parameter} current-input-port
@deffnx {Parameter} current-output-port
@deffnx {Parameter} current-error-port
[R7RS base]
Returns the current input, output and error output port, respectively.

R7RS defines that the initial values of these ports are textual ports.
In Gauche, initial ports can handle both textual and binary I/O.

Values of the current ports can be temporarily changed by @code{parameterize}
(@pxref{Parameters}), though you might want the convenience procedures
such as @code{with-output-to-string} or @code{with-input-from-file}
in typical cases.

@example
(use gauche.parameter)
(let1 os (open-output-string)
  (parameterize ((current-output-port os))
    (display "foo"))
  (get-output-string os))
 @result{} "foo"
@end example
@end deffn

@deffn {Parameter} current-trace-port
A paremeter that holds an output port which debug trace goes to.
The initial value is the same as the initial value of @code{current-error-port}.

The @code{debug-print} feature (@pxref{Debugging aid}) and
the macro trace feature (@pxref{Tracing macro expansion}) uses
this port.
@end deffn


@deffn {Parameter} standard-input-port
@deffnx {Parameter} standard-output-port
@deffnx {Parameter} standard-error-port
Returns standard i/o ports at the time the program started.
These ports are the default values
of @code{current-input-port}, @code{current-output-port}
and @code{current-error-port}, respectively.

You can also change value of these procedures by @code{parameterize},
but note that (1) @code{current-*-port}s are initialized before
the program execution, so changing values of @code{standard-*-port}
won't affect them, and (2) changing values these procedures only affect
Scheme-world, and does not change system-level stdio file descriptors
low-level libraries referring.
@end deffn

@defun with-input-from-port port thunk
@defunx with-output-to-port port thunk
@defunx with-error-to-port port thunk
Calls @var{thunk}.  During evaluation of thunk, the current input port, current
output port and current error port are set to @var{port}, respectively.
Note that @var{port} won't be closed after thunk is executed.
@end defun

@defun with-ports iport oport eport thunk
Does the above three functions at once.
Calls @var{thunk} while the current input, output, and error ports are
set to @var{iport}, @var{oport}, and @var{eport}, respectively.
You may pass @code{#f} to any port argument(s) if you don't need
to alter the port(s).

Note that @var{port} won't be closed after thunk is executed.
(Unfortunately, recent Scheme standards added a similar
named procedure, @code{call-with-port},
which does close the port.  See below.)
@end defun

@defun close-port port
@defunx close-input-port port
@defunx close-output-port port
[R7RS base]
Closes the port.  @code{Close-port} works both input and
output ports, while @code{close-input-port} and @code{close-output-port}
work only for the respective ports and throws an error if another type
of port is passed.

Theoretically, only @code{close-port} would suffice; having those three
is merely for historical reason.
R5RS has @code{close-input-port} and @code{close-output-port};
R6RS and R7RS support all three.
@end defun


@defun call-with-port port proc
[R7RS base]
Calls @var{proc} with one argument, @var{port}.  After @var{proc} returns,
or it throws an uncaptured error, @var{port} is closed.  Value(s) returned
from @var{proc} will be the return value(s) of @code{call-with-port}.

@end defun

@defun port-type port
Returns the type of @var{port} in one of the symbols @code{file},
@code{string} or @code{proc}.
@end defun

@defun port-name port
Returns the name of @var{port}.  If the port is associated to a file,
it is the name of the file.   Otherwise, it is some description of the port.
@end defun

@defun port-buffering port
@defunx {(setter port-buffering)} port buffering-mode
If @var{port} is type of file port (i.e. @code{(port-type @var{port})}
returns @code{file}), these procedures gets and sets the port's
buffering mode.  For input ports, the port buffering mode may be
either one of @code{:full}, @code{:modest} or @code{:none}.
For output ports, @code{port-buffering}, it may be
one of @code{:full}, @code{:line} or @code{:none}.
@xref{File ports}, for explanation of those modes.

If @code{port-buffering} is applied to ports other than file ports,
it returns @code{#f}.  If the setter of port-buffering is
applied to ports other than file ports, it signals an error.
@end defun

@defun port-current-line port
Returns the current line count of @var{port}.  This information is
only available on file-based port, and as long as you're doing
sequential character I/O on it.  Otherwise, this returns -1.
@end defun

@defun port-file-number port :optional dup?
Returns an integer file descriptor, if the @var{port} is associated
to the system file I/O.  Returns @code{#f} otherwise.

If a true value is passed to @var{dup?}, the procedure calls @code{dup(2)}
and returns a duplicated file descriptor.  In such case, the returned
file descriptor can be closed independently with the port, and it is
caller's responsibility to close it (by @code{sys-close}) once it's done.
@end defun

@defun port-position port
[SRFI-192]
Returns the current position of @var{port}.  For the input port,
the current position is where the next data will be read from,
and for the output port, it is where the next data will be written to.
(Note that @code{peek-char}/@code{peek-byte} won't move the current position).

If @var{port} is a simple file port or a string port, the position is
represented as an integer byte offset from the top of the stream.
If it is more complicated ports, such as the one doing the character encoding
conversion, the port position may not be available, or returned
object may not correspond to the byte offset.
If @var{port} is a procedural (virtual) port (@pxref{Virtual ports}), 
the returned value can
be an arbitrary Scheme object, it can only
be valid to be used for @code{set-port-position!}.

An error is thrown if @var{port} doesn't support port positions.
You can use @code{port-has-port-position?} to check if the port supports
port positions.

For portable code: srfi-192 defines the following conditions.

@itemize @bullet
@item
Return value is an arbitrary Scheme object and you should treat it as an
opaque object.  In general, it is only
safe to pass it to the @code{set-port-position!} on the same port.
@item
If the port is a binary port and the returned position is a nonnegative
exact integer, it represents the byte offset of the position.
@end itemize
@end defun

@defun port-has-port-position? port
[SRFI-192]
Returns @code{#t} iff the port supports @code{port-position} procedure.
@end defun

@defun set-port-position! port pos
[SRFI-192]
Sets the current position of @var{port} to @var{pos}.  For the input port,
the current position is where the next data will be read from,
and for the output port, it is where the next data will be written to.

Interpretation of @var{pos} is up to the @var{port},
and generally it  must be an object returned previously
by @code{port-position} on the same port.  If @var{port} is a simple
file port (a port opened on file, without CES conversion) or
an input string port, you may pass a nonnegative exact integer as the byte
offset.

An error is signaled if the position is not settable, or @var{pos} is
not acceptable as a position for @var{port}.  You can check if position
of @var{port} is settable by @code{port-has-set-port-position!?}.
@end defun

@defun port-has-set-port-position!? port
[SRFI-192]
Returns @code{#t} iff the port supports @code{set-port-position!} procedure.
@end defun


@defun port-seek port offset :optional whence
(This procedure is deprecated.  Use @code{port-position} and
@code{set-port-position!} for the new code.

If the given @var{port} allows random access, this procedure sets
the read/write pointer of the @var{port} according to the given @var{offset}
and @var{whence}, then returns the updated offset (number of bytes
from the beginning of the data).  If @var{port} is not random-accessible,
@code{#f} is returned.  In the current version, file ports and
input string ports are fully random-accessible.  You can only query
the current byte offset of output string ports.

Note that port position is represented by byte count, not character count.

It is allowed to seek after the data if @var{port} is an output
file port.  See POSIX lseek(2) document for details of the behavior.
For input file port and input string port, you can't seek after the data.

The @var{whence} argument must be a small integer that represents
from where @var{offset} should be counted.   The following constant
values are defined.

@table @code
@item SEEK_SET
@var{Offset} represents the byte count from the beginning of the data.
This is the default behavior when @var{whence} is omitted.

@item SEEK_CUR
@var{Offset} represents the byte count relative to the current read/write
pointer.  If you pass 0 to @var{offset}, you can get the current
port position without changing it.

@item SEEK_END
@var{Offset} represents the byte count relative to the end of the data.
@end table
@end defun

@defun port-tell port
Returns the current read/write pointer of @var{port} in byte count,
if @var{port} is random-accessible.   Returns @code{#f} otherwise.
This is equivalent to the following call:
@example
(port-seek @var{port} 0 SEEK_CUR)
@end example
@end defun

@emph{Note on the names}:  @code{Port-seek} is called
@code{seek}, @code{file-position} or @code{input-port-position}/
@code{output-port-position} on some implementations.
@code{Port-tell} is called @code{tell}, @code{ftell} or
@code{set-file-position!}.   Some implementations have
@code{port-position} for different functionality.
CommonLisp has @code{file-position}, but it is not suitable
for us since @var{port} need not be a file port.  @code{Seek} and
@code{tell} reflects POSIX name, and with Gauche naming convention
we could use @code{sys-seek} and @code{sys-tell}; however, @var{port}
deals with higher level of abstraction than system calls, so I dropped
those names, and adopted new names.

@defun copy-port src dst :key (unit 0) (size #f)
Copies data from an input port @var{src} to an output port @var{dst},
until eof is read from @var{src}.

The keyword argument @var{unit} may be zero, a positive exact integer,
a symbol @code{byte} or a symbol @code{char}, to specify the unit
of copying.  If it is an integer, a buffer of the size
(in case of zero, a system default size) is used to copy,
using block I/O.  Generally it is the fastest if you copy
between normal files.   If @var{unit} is a symbol @code{byte},
the copying is done byte by byte, using C-version of @code{read-byte}
and @code{write-byte}.  If @var{unit} is a symbol @code{char},
the copying is done character by character, using C-version of
@code{read-char} and @code{write-char}.

If nonnegative integer is given to the keyword argument @var{size},
it specifies the maximum amount of data to be copied.  If @var{unit}
is a symbol @code{char}, @var{size} specifies the number of characters.
Otherwise, @var{size} specifies the number of bytes.

Returns number of characters copied when @var{unit} is a symbol
@code{char}.  Otherwise, returns number of bytes copied.
@end defun

@node File ports, String ports, Common port operations, Input and output
@subsection File ports
@c NODE ファイルポート

@defun open-input-file filename :key if-does-not-exist buffering element-type encoding conversion-buffer-size conversion-illegal-output
@defunx open-output-file filename :key if-does-not-exist if-exists buffering element-type encoding conversion-buffer-size conversion-illegal-output
[R7RS+]
Opens a file @var{filename} for input or output, and
returns an input or output port associated with it, respectively.

The keyword arguments specify precise behavior.

@table @code
@item :if-exists
This keyword argument can be specified only for @code{open-output-file}, and
specifies the action when the @var{filename} already exists.
One of the following value can be given.
@table @code
@item :supersede
The existing file is truncated.  This is the default behavior.
@item :append
The output data will be appended to the existing file.
@item :overwrite
The output data will overwrite the existing content.
If the output data is shorter than the existing file, the rest of
existing file remains.
@item :error
An error is signaled.
@item #f
No action is taken, and the function returns @code{#f}.
@end table

@item :if-does-not-exist
This keyword argument specifies the action when @var{filename} does not exist.
@table @code
@item :error
An error is signaled.  This is the default behavior of
@code{open-input-file}.
@item :create
A file is created.  This is the default behavior of @code{open-output-file}.
The check of file existence and creation is done atomically; you can
exclusively create the file by specifying @code{:error} or @code{#f} to
@var{if-exists}, along this option.
You can't specify this value for @code{open-input-file}.
@item #f
No action is taken, and the function returns @code{#f}.
@end table

@item :buffering
This argument specifies the buffering mode.  The following values are
allowed.
The port's buffering mode can be get/set by @code{port-buffering}.
(@pxref{Common port operations}).
@table @code
@item :full
Buffer the data as much as possible.  This is the default mode.
@item :none
No buffering is done.  Every time the data is written (to an output port)
or read (from an input port), the underlying system call is used.
Process's standard error port is opened in this mode by default.
@item :line
This is valid only for output ports.  The written data is buffered, but
the buffer is flushed whenever a newline character is written.
This is suitable for interactive output port.  Process's standard
output port is opened in this mode by default.
(Note that this differs from the line buffering mode of C stdio, which
flushes the buffer as well when input is requested from the same file
descriptor.)
@item :modest
This is valid only for input ports.  This is almost the same as the mode
@code{:full}, except that @code{read-uvector} may return less data
than requested if the requested amount of data is not immediately available.
(In the @code{:full} mode, @code{read-uvector} waits the entire data to be
read).   This is suitable for the port connected to a pipe or network.
@end table

@item :element-type
This argument specifies the type of the file.
@table @code
@item :binary
The file is opened in "binary" mode. (This is the default)
@item :character
The file is opened in "character" (or "text") mode.
@end table
Note: This flag makes difference only on Windows-native platforms,
and only affect the treatment of line terminators.  In character
mode, writing @code{#\newline} on the output causes CR + LF characters to be
written, instead of just LF.  And reading CR + LF sequence returns
just @code{#\newline}.

On Unix, both mode are the same.

Note that Gauche doesn't distinguish character (textual) port and
binary port.  So this flag really matters only on Windows line
terminators.

@item :encoding
This argument specifies character encoding of the file.   The argument
is a string or a symbol that names a character encoding scheme (CES).

For @code{open-input-file}, it can be a wildcard CES (e.g. @code{*jp})
to guess the file's encoding heuristically
(@pxref{Autodetecting the encoding scheme}),
or @code{#t}, in which case we assume the input file itself has magic
encoding comment and use @code{open-coding-aware-port}
(@pxref{Coding-aware ports}).

If this argument is given, Gauche automatically loads
@code{gauche.charconv} module and converts the input/output characters
as you read to or write from the port.
See @ref{Supported character encoding schemes}, for the details of
character encoding schemes.

@item :conversion-buffer-size
This argument may be used with the @var{encoding} argument to specify
the buffer size of character encoding conversion.  It is passed as
a @var{buffer-size} argument of the conversion port constructors
(@pxref{Conversion ports}).

Usually you don't need to give this argument; but if you need to guess
the input file encoding, larger buffer size may work better since guessing
routine can have more data before deciding the encoding.

@item :conversion-illegal-output
This argument may be used with the @var{encoding} argument to specify
the behavior when the source character can't be mapped to the destination
character.  It must be either a symbol @code{raise} or a symbol
@code{replace}, and is passed as @var{illegal-output} argument to the
conversion port.  @xref{Conversion ports}, for the details.
@end table

By combination of @var{if-exists} and @var{if-does-not-exist} flags,
you can implement various actions:
@example
(open-output-file "foo" :if-exists :error)
 @result{} ;@r{opens "foo" exclusively, or error}

(open-output-file "foo" :if-exists #f)
 @result{} ;@r{opens "foo" exclusively, or returns} #f

(open-output-file "foo" :if-exists :append
                        :if-does-not-exist :error)
 @result{} ;@r{opens "foo" for append only if it already exists}
@end example

To check the existence of a file without opening it,
use @code{sys-access} or @code{file-exists?} (@pxref{File stats}).

Note for portability: Some Scheme implementations (e.g. STk) allows
you to specify a command to @var{filename} and reads from, or
writes to, the subprocess standard input/output.  Some other scripting
languages (e.g. Perl) have similar features.  In Gauche,
@code{open-input-file} and @code{open-output-file} strictly operates
on files (what the underlying OS thinks as files).
However, you can use ``process ports'' to invoke
other command in a subprocess and to communicate it.
@xref{Process ports}, for details.
@end defun

@defun call-with-input-file string proc :key if-does-not-exist buffering element-type encoding conversion-buffer-size
@defunx call-with-output-file string proc :key if-does-not-exist if-exists buffering element-type encoding conversion-buffer-size
[R7RS+]
Opens a file specified by @var{string} for input/output,
and call @var{proc} with one argument, the file port.  When @var{proc}
returns, or an error is signaled from @var{proc} that is not captured
within @var{proc}, the file is closed.

The keyword arguments have the same meanings of
@code{open-input-file} and @code{open-output-file}'s.  Note that
if you specify @code{#f} to @var{if-exists} and/or @var{if-does-not-exist},
@var{proc} may receive @code{#f} instead of a port object when
the file is not opened.

Returns the value(s) @code{proc} returned.
@end defun

@defun with-input-from-file string thunk :key if-does-not-exist buffering element-type encoding conversion-buffer-size
@defunx with-output-to-file string thunk :key if-does-not-exist if-exists buffering element-type encoding conversion-buffer-size
[R7RS file]
Opens a file specified by @var{string} for input or output
and makes the opened port as the current input or output port,
then calls @var{thunk}.  The file is closed when @var{thunk}
returns or an error is signaled from @var{thunk} that is not
captured within @var{thunk}.

Returns the value(s) @code{thunk} returns.

The keyword arguments have the same
meanings of @code{open-input-file} and @code{open-output-file}'s,
except that when @code{#f} is given to @var{if-exists} and
@var{if-does-not-exist} and the opening port is failed,
@var{thunk} isn't called at all and @code{#f} is returned
as the result of @code{with-input-from-file} and
@code{with-output-to-file}.
@end defun

@emph{Notes on semantics of closing file ports:}
R7RS states, in the description of @code{call-with-port} et al.,
that @emph{"If @emph{proc} does not return, then the port will
not be closed automatically unless it is possible
to prove that the port will never again be used for read or write
operation."}

Gauche's implementation slightly misses this criteria; the mere fact
that an uncaptured error is thrown in @var{proc} does not prove
the port will never be used.  Nevertheless, it is very difficult
to think the situation that you can do meaningful operation on
the port after such an error is signaled; you'd have no idea
what kind of state the port is in.  In practical programs, you
should capture error explicitly inside @var{proc} if you still want
to do some meaningful operation with the port.

Note that if a continuation captured outside @code{call-with-input-file}
et al. is invoked inside @var{proc}, the port is not closed.
It is possible that the control returns later into the @var{proc},
if a continuation is captured in it (e.g. coroutines).
The low-level exceptions (@pxref{Handling exceptions})
also doesn't ensure closing the port.


@defun open-input-fd-port fd :key buffering name owner?
@defunx open-output-fd-port fd :key buffering name owner?
Creates and returns an input or output port on top of the given
file descriptor.  @var{Buffering} specifies the buffering mode
as described in @code{open-input-file} entry above; the default
is @code{:full}.  @var{Name} is used for the created port's name
and returned by @code{port-name}.

A boolean flag @code{owner?} specifies whether @var{fd} should be
closed when the port is closed.  If it is @code{#f}, closing port
doesn't close @var{fd}.  If it s @code{#t}, closing port automatically
closes @code{fd}.  It can also be a symbol @code{dup}, in which case
@code{fd} is duplicated (by @code{dup(2)} system call) and the
resulting port owns the new fd which will be closed automatically--but
@var{fd} itself remains open, and can be closed independently.
@end defun

@defun port-fd-dup! toport fromport
Interface to the system call @code{dup2(2)}.
Atomically closes the file descriptor associated to @var{toport},
creates a copy of the file descriptor associated to @var{fromport},
and sets the new file descriptor to @var{toport}.
Both @var{toport} and @var{fromport} must be file ports.
Before the original file descriptor of @var{toport} is closed,
any buffered output (when @var{toport} is an output port) is flushed,
and any buffered input (when @var{toport} is an input port) is discarded.

`Copy' means that, even the two file descriptors differ in their values,
they both point to the same system's open file table entry.  For example
they share the current file position; after @var{port-fd-dup!},
if you call @code{port-seek} on @var{fromport}, the change is also visible
from @var{toport}, and vice versa.  Note that this 'sharing' is in the
system-level; if either @var{toport} or @var{fromport} is buffered,
the buffered contents are not shared.

This procedure is mainly intended for programs that needs to control
open file descriptors explicitly; e.g. a daemon process would want to redirect
its I/O to a harmless device such as @file{/dev/null}, and a shell process
would want to set up file descriptors before executing the child process.
@end defun

@node String ports, Coding-aware ports, File ports, Input and output
@subsection String ports
@c NODE 文字列ポート

String ports are the ports that you can read from or write to
memory.

@defun open-input-string string :key name
[R7RS base][SRFI-6]
Creates an input string port that has the content @var{string}.
This is a more efficient way to access a string in order
rather than using @code{string-ref} with incremental index.

@example
(define p (open-input-string "foo x"))
(read p) @result{} foo
(read-char p) @result{} #\space
(read-char p) @result{} #\x
(read-char p) @result{} #<eof>
(read-char p) @result{} #<eof>
@end example

The @var{name} keyword argument is a Gauche extension.
By default, the created port is named as @code{(input string port)}.
It is mainly used for debugging.  You can specify alternative name with
this argument.
As Gauche's convention, file ports has the source file path as its name,
so port names for debugging information should be parenthesized
not to be taken as pathnames.

@example
gosh> (open-input-string "")
#<iport (input string port) 0x215c0c0>
gosh> (open-input-string "" :name "(user input)")
#<iport (user input) 0x22a4e40>
@end example
@end defun

@defun get-remaining-input-string port
@var{Port} must be an input string port.
Returns the remaining content of the input port.
The internal pointer of @var{port} isn't moved, so the
subsequent read from @var{port} isn't affected.
If @var{port} has already reached to EOF, a null string is returned.

@example
(define p (open-input-string "abc\ndef"))
(read-line p)                  @result{} "abc"
(get-remaining-input-string p) @result{} "def"
(read-char p)                  @result{} #\d
(read-line p)                  @result{} "ef"
(get-remaining-input-string p) @result{} ""
@end example
@end defun


@defun open-output-string :key name
[R7RS base][SRFI-6]
Creates an output string port.   Anything written to the
port is accumulated in the buffer, and can be obtained
as a string by @code{get-output-string}.
This is a far more efficient way to construct a string
sequentially than pre-allocate a string and fill it with
@code{string-set!}.

The @var{name} keyword argument is a Gauche extension.
By default, the created port is named as @code{(output string port)}.
It is mainly used for debugging.  You can specify alternative name with
this argument.
As Gauche's convention, file ports has the source file path as its name,
so port names for debugging information should be parenthesized
not to be taken as pathnames.

@example
gosh> (open-output-string)
#<oport (output string port) 0x22a4c00>
gosh> (open-output-string :name "(temporary output)")
#<oport (temporary output) 0x22a49c0>
@end example
@end defun

@defun get-output-string port
[R7RS base][SRFI-6]
Takes an output string port @code{port} and returns a string
that has been accumulated to @code{port} so far.
If a byte data has been written to the port, this function
re-scans the buffer to see if it can consist a complete string;
if not, an incomplete string is returned.

This doesn't affect the @var{port}'s operation, so you can keep
accumulating content to @var{port} after calling @code{get-output-string}.
@end defun

@defun call-with-input-string string proc
@defunx call-with-output-string proc
@defunx with-input-from-string string thunk
@defunx with-output-to-string thunk
These utility functions are trivially defined as follows.
The interface is parallel to the file port version.
@example
(define (call-with-output-string proc)
  (let ((out (open-output-string)))
    (proc out)
    (get-output-string out)))

(define (call-with-input-string str proc)
  (let ((in (open-input-string str)))
    (proc in)))

(define (with-output-to-string thunk)
  (let ((out (open-output-string)))
    (with-output-to-port out thunk)
    (get-output-string out)))

(define (with-input-from-string str thunk)
  (with-input-from-port (open-input-string str) thunk))
@end example
@end defun

@defun call-with-string-io str proc
@defunx with-string-io str thunk
@example
(define (call-with-string-io str proc)
  (let ((out (open-output-string))
        (in  (open-input-string str)))
    (proc in out)
    (get-output-string out)))

(define (with-string-io str thunk)
  (with-output-to-string
    (lambda ()
      (with-input-from-string str
        thunk))))
@end example
@end defun

@defun write-to-string obj :optional writer
@defunx read-from-string string :optional start end
These convenience functions cover common idioms using string ports.
@example
(write-to-string obj writer)
  @equiv{}
  (with-output-to-string (lambda () (writer obj)))

(read-from-string string)
  @equiv{}
  (with-input-from-string string read)
@end example
The default value of @var{writer} is the procedure @code{write}.
The default values of @var{start} and @var{end} is 0 and
the length of @var{string}.

Portability note: Common Lisp has these functions, with
different optional arguments.
STk has @code{read-from-string} without optional argument.
@end defun

@node Coding-aware ports, Input, String ports, Input and output
@subsection Coding-aware ports
@c NODE コーディング認識ポート

A coding-aware port is a special type of procedural input port that
is used by @code{load} to read a program source.  The port recognizes
the magic comment to specify the character encoding of the
program source, such as @code{;; -*- coding: utf-8 -*-}, and makes
an appropriate character encoding conversion.
See @ref{Multibyte scripts} for the details of coding magic comment.

@defun open-coding-aware-port iport
Takes an input port and returns an input coding aware port,
which basically just pass through the data from @var{iport} to
its reader.  However, if a magic comment appears within the
first two lines of data from @var{iport}, the coding aware port
applies the necessary character encoding conversion to the rest of the
data as they are read.

The passed port, @var{iport}, is "owned" by the created coding-aware
port.  That is, when the coding-aware port is closed, @var{iport} is
also closed.  The content read from @var{iport} is buffered in the
coding-aware port, so other code shouldn't read from @var{iport}.

By default, Gauche's @code{load} uses a coding aware port to read
the program source, so that the coding magic comment works for
the Gauche source programs (see @ref{Loading Scheme file}).
However, since the mechanism itself
is independent from @code{load}, you can use this port for
other purposes; it is particularly useful to write a function
that processes Scheme source programs which may have the coding
magic comment.
@end defun

@node Input, Output, Coding-aware ports, Input and output
@subsection Input
@c NODE 入力

For the input-related procedures, the optional @var{iport} argument must be
an input port, and when omitted, the current input port is assumed.

@menu
* Reading data::
* Reader lexical mode::
* Read-time constructor::
* Input utility functions::
@end menu

@node Reading data, Reader lexical mode, Input, Input
@subsubsection Reading data
@c NODE データの読み込み

@defun read :optional iport
[R7RS base]
Reads an S-expression from @var{iport} and returns it.
Gauche recognizes the lexical structure specified in R7RS,
and some additional lexical structures listed in @ref{Lexical structure}.

If @var{iport} has already reached to the end of file,
an eof object is returned.

The procedure reads up to the last character that consists the S-expression,
and leaves the rest in the port.  It's not like CommonLisp's @code{read},
which consumes whitespaces after S-expression by default.
@end defun

@defun read-with-shared-structure :optional iport
@defunx read/ss :optional iport
[SRFI-38]
These procedures are defined in srfi-38 to recognize shared substructure
notation (@code{#n=}, @code{#n#}).   Gauche's builtin @code{read} recognizes
the srfi-38 notation, so these are just synonyms to @code{read}; these
are only provided for srfi-38 compatibility.
@end defun

@defun read-char :optional iport
[R7RS base]
Reads one character from @var{iport} and returns it.
If @var{iport} has already
reached to the end, returns an eof object.
If the byte stream in @var{iport} doesn't consist a valid character,
the behavior is undefined.  (In future, a port will have a option
to deal with invalid characters).
@end defun

@defun peek-char :optional iport
[R7RS base]
Reads one character in @var{iport} and returns it, keeping the character
in the @var{port}.
If the byte stream in @var{iport} doesn't consist a valid character,
the behavior is undefined.  (In future, a port will have a option
to deal with invalid characters).
@end defun

@defun read-byte :optional iport
@defunx read-u8 :optional iport
[R7RS base]
Reads one byte from an input port @var{iport}, and returns it as an integer
in the range between 0 and 255.
If @var{iport} has already reached EOF, an eof object is returned.

This is traditionally called @code{read-byte}, and
R7RS calls it @code{read-u8}.  You can use either.
@end defun

@defun peek-byte :optional iport
@defunx peek-u8  :optional iport
[R7RS base]
Peeks one byte at the head of an input port @var{iport}, and returns
it as an integer in the range between 0 and 255.
If @var{iport} has already reached EOF, an eof object is returned.

This is traditionally called @code{peek-byte}, and
R7RS calls it @code{peek-u8}.  You can use either.
@end defun

@defun read-line :optional iport allow-byte-string?
[R7RS base]
Reads one line (a sequence of characters terminated by newline or EOF)
and returns a string.  The terminating newline is not included.
This function recognizes popular line terminators (LF only, CRLF, and CR only).
If @var{iport} has already reached EOF, an eof object is returned.

If a byte sequence is read from @var{iport}
which doesn't constitute a valid character in the native encoding,
@code{read-line} signals an error by default.  However, if a true value
is given to the argument @var{allow-byte-string?},
@code{read-line} returns a byte string (incomplete string) in such case,
without reporting an error.
It is particularly useful if you read from a source whose
character encoding is not yet known; for example, to read XML document,
you need to check the first line to see if there is a charset parameter
so that you can then use an appropriate character conversion port.
This optional argument is Gauche's extension to R7RS.
@end defun

@defun read-string nchars :optional iport
[R7RS base]
Read @var{nchars} characters, or as many characters as available
before EOF, and returns a string that consists of those characters.
If the input has already reached EOF, an eof object is returned.
@end defun

@defun read-block nbytes :optional iport
This procedure is deprecated - use @code{read-uvector} instead
(@pxref{Uvector block I/O}).

Reads @var{nbytes} bytes from @var{iport}, and returns an incomplete
string consisted by those bytes.  The size of returned string may
shorter than @var{nbytes} when @var{iport} doesn't have enough bytes
to fill.
If @var{nbytes} is zero, a null string is always returned.

If @var{iport} has already reached EOF, an eof object is returned.

If @var{iport} is a file port, the behavior of @code{read-block}
differs by the buffering mode of the port (@xref{File ports}, for
the detail explanation of buffering modes).
@itemize @bullet
@item
If the buffering mode is @code{:full}, @code{read-block} waits
until @var{nbytes} data is read, except it reads EOF.
@item
If the buffering mode is @code{:modest} or @code{:none}, @code{read-block}
returns shorter string than @var{nbytes} even if it doesn't reach EOF,
but the entire data is not available immediately.
@end itemize

If you want to write a chunk of bytes to a port,
you can use either @code{display} if the data is in string,
or @code{write-uvector} in @code{gauche.uvector} (@pxref{Uvector block I/O})
if the data is in uniform vector.
@end defun

@defun eof-object
[R7RS base]
Returns an EOF object.
@end defun


@defun eof-object? obj
[R7RS base]
Returns true if @var{obj} is an EOF object.
@end defun

@defun char-ready? :optional port
[R7RS base]
If a character is ready to be read from @var{port}, returns @code{#t}.

For now, this procedure actually checks only if next @emph{byte} is
immediately available from @var{port}.   If the next byte is a part of
a multibyte character, the attempt to read the whole character may block,
even if @code{char-ready?} returns @code{#t} on the port.
(It is unlikely to happen in usual situation, but theoretically it can.
If you concern, use @code{read-uvector} to read the input as a byte
sequence, then use input string port to read characters.)
@end defun

@defun byte-ready? :optional port
@defunx u8-ready?  :optional port
[R7RS base]
If one byte (octet) is ready to be read from @var{port}, returns
@code{#t}.

This is traditionally called @code{byte-ready?}, and
R7RS calls it @code{u8-ready?}.  You can use either.
@end defun

@node Reader lexical mode, Read-time constructor, Reading data, Input
@subsubsection Reader lexical mode
@c NODE リーダー字句モード

@deffn {Parameter} reader-lexical-mode
Get/set the reader lexical mode.  Changing this parameter
switches behavior of the reader concerning some corner cases
of the lexical syntax, where legacy Gauche syntax and R7RS syntax
aren't compatible.

In general, you don't need to change this parameter directly.
The lexical syntax matters at the read-time, while changing this parameter
happens at the execution-time; unless you know the exact timing when
each phase occurs, you might not get what you want.

The hash-bang directive @code{#!gauche-legacy} and @code{#!r7rs}
indirectly affects this parameter; the first one sets the reader
mode to @code{legacy}, and the second one to @code{strict-r7}.

The command-line argument @code{-fwarn-legacy} sets the default
reader mode to @code{warn-legacy}.

Change to this parameter during @code{load} is delimited within that @code{load};
once @code{load} is done, the value of this parameter is reset
to the value when @code{load} is started.

The parameter takes one of the following symbols as a value.

@table @code
@item permissive
This is the default mode.  It tries to find a reasonable
compromise between two syntax.

In string literals, hex escape sequence
is first interpreted as R7RS lexical syntax.  If the syntax doesn't
conform R7RS hex escape, it is interpreted as legacy Gauche hex escape
syntax.  For example, @code{"\x30;a"} is read as @code{"0a"}, for
the hex escape sequence including the terminating semicolon is read
as R7RS hex escape sequence.  It also reads @code{"\x30a"} as
@code{"0a"}, for the legacy Gauche hex escape always takes two hexadecimal
digits without the terminator.  With this mode, you can use R7RS
hex escape syntax for the new code, and yet almost all legacy Gauche
code can be read without a problem.
However, if the legacy code has a semicolon followed by hex escape,
it is interpreted as R7RS syntax and the incompatibility arises.

@item strict-r7
Strict R7RS compatible mode.
When the reader encounters the hash-bang directive @code{#!r7rs},
the rest of file is read with this mode.

In this mode, Gauche's extended lexical syntax will raise an error.

Use this mode to ensure the code can be read on other R7RS implementations.

@item legacy
The reader works as the legacy Gauche (version 0.9.3.3 and before).
When the reader encounters the hash-bang directive @code{#!gauche-legacy},
the rest of file is read with this mode.

This only matters when you want to read two-digit hex escape
followed by semicolon as a character plus a semicolon, e.g.
@code{"\x30;a"} as @code{"0;a"} instead of @code{"0a"}.
We expect such a sequence rarely appears in the code,
but if you dump a data in a string literal format, you may
have such sequence (especially in incomplete string literals).

@item warn-legacy
The reader works as the @code{permissive} mode,
but warns if it reads legacy hex-escape syntax.
This mode is default when @code{-fwarn-legacy} command-line
argument is given to @code{gosh}.

This is useful to check if you have any incompatible escape sequence
in your code.
@end table
@end deffn


@node Read-time constructor, Input utility functions, Reader lexical mode, Input
@subsubsection Read-time constructor
@c NODE 読み込み時コンストラクタ

Read-time constructor, defined in SRFI-10, provides an easy way
to create an external representation of user-defined structures.

@deftp {Reader Syntax} @code{#,(@var{tag} @var{arg} @dots{})}
@lxindex #,
[SRFI-10]
Gauche maintains a global table that associates a @var{tag} (symbol)
to @emph{a constructor procedure}.

When the reader encounters this syntax, it reads @var{arg} @dots{},
finds a reader constructor associated with @var{tag}, and
calls the constructor with @var{arg} @dots{} as arguments,
then inserts the value returned by the constructor as the result
of reading the syntax.

Note that this syntax is processed inside the reader---the
evaluator doesn't see any of @var{arg}s, but only sees the object
the reader returns.
@end deftp

@defun define-reader-ctor @var{tag} @var{procedure}
[SRFI-10]
Associates a reader constructor @var{procedure} with @var{tag}.

Examples:
@example
(define-reader-ctor 'pi (lambda () (* (atan 1) 4)))

#,(pi) @result{} 3.141592653589793

'(#,(pi)) @result{} (3.141592653589793)

(define-reader-ctor 'hash
  (lambda (type . pairs)
    (let ((tab (make-hash-table type)))
      (for-each (lambda (pair)
                  (hash-table-put! tab (car pair) (cdr pair)))
                pairs)
      tab)))

(define table
 #,(hash eq? (foo . bar) (duh . dah) (bum . bom)))

table @result{} #<hash-table eq? 0x80f9398>
(hash-table-get table 'duh) @result{} dah
@end example

Combined with @code{write-object} method (@pxref{Output}),
it is easy to make a user-defined class written in the form
it can be read back:

@example
(define-class <point> ()
  ((x :init-value 0 :init-keyword :x)
   (y :init-value 0 :init-keyword :y)))

(define-method write-object ((p <point>) out)
  (format out "#,(<point> ~s ~s)" (ref p 'x) (ref p 'y)))

(define-reader-ctor '<point>
  (lambda (x y) (make <point> :x x :y y)))
@end example

@end defun

@emph{NOTE:} The extent of the effect of @code{define-reader-ctor}
is not specified in SRFI-10, and might pose a compatibility problem
among implementations that support SRFI-10.
(In fact, the very existence of @code{define-reader-ctor} is
up to an implementation choice.)

In Gauche, at least for the time being, @code{define-reader-ctor}
take effects as soon as the form is compiled and evaluated.  Since
Gauche compiles and evaluates each toplevel form in order, @var{tag}
specified in @code{define-reader-ctor} can be used immediately after that.
However, it doesn't work if the call of @code{define-reader-ctor} and
the use of @var{tag} is enclosed in a @code{begin} form, for the entire
@code{begin} form is compiled at once before being evaluated.

Other implementations may require to read the entire file before
making its @code{define-reader-ctor} call effective.  If so, it
effectively prevents one from using @code{define-reader-ctor} and
the defined @var{tag} in the same file.   It is desirable to separate
the call of @code{define-reader-ctor} and the use of @var{tag}
in the different files if possible.

Another issue about the current @code{define-reader-ctor} is that
it modifies the global table of Gauche system, hence it is not modular.
The code written by different people might use the same tags,
and yield an unexpected result.   In future versions, Gauche may
have some way to encapsulate the scope of @var{tag}, although
the author doesn't have clear idea yet.


@node Input utility functions,  , Read-time constructor, Input
@subsubsection Input utility functions
@c NODE 入力ユーティリティ手続き

@defun port->string port
@defunx port->list reader port
@defunx port->string-list port
@defunx port->sexp-list port
Generally useful input procedures.  The API is taken from
scsh and STk.

@code{port->string} reads @var{port}
until EOF and returns the accumulated data as a string.

@code{port->list} applies @var{reader} on @var{port} repeatedly, until
@var{reader} returns an EOF, then returns the list of objects
@var{reader} returned.
Note that @var{port} isn't closed.

@code{port->string-list} is a @code{port->list} specialized
by @code{read-line}, and
@code{port->sexp-list} is a @code{port->list} specialized
by @code{read}.

If the input contains an octet sequence that's not form a valid
character in the Gauche's native character encoding,
@code{port->string} and @code{port->string-list} may return
incomplete string(s).
If you want to deal with binary data, consider using
@code{port->uvector} in @code{gauche.uvector} (@pxref{Uvector block I/O}).
@end defun

@defun port-fold fn knil reader
@defunx port-fold-right fn knil reader
@defunx port-for-each fn reader
@defunx port-map fn reader
Convenient iterators over the input read by @var{reader}.

Since these procedures are not really about ports,
they are superseded by @code{generator-fold},
@code{generator-fold-right}, @code{generator-for-each}
and @code{generator-map}, respectively.  @xref{Folding generated values},
for the details.

We provide these only for the backward compatibility.
@end defun

@node Output,  , Input, Input and output
@subsection Output
@c NODE 出力

@menu
* Layers of output routines::
* Output controls::
* Object output::
* Formatting output::
* Low-level output::
@end menu

@node Layers of output routines, Output controls, Output, Output
@subsubsection Layers of output routines
@c NODE 出力ルーチンの階層

Gauche has quite a few output procedures which may confuse newcomers.
The following table will help to understand how to use those procedures:

@table @asis
@item Object writers
Procedures that write out Scheme objects.
Although there exist more low-level procedures,
these are regarded as a basic layer of output routines, 
since it works on a generic Scheme object as a single unit.
They come in two flavors:

@itemize @bullet
@item
Write-family procedures: @code{write}, @code{write-shared}, @code{write-simple}--these are to produce @emph{external representation} of Scheme objects, 
which can be generally read back by @code{read} without losing
information as much as possible@footnote{In a sense, this is somewhat similar to
what is called ``serialization'' or ``marshalling'' in other programming
language; you can @code{write} out a generic Scheme object on disk or
to wire, and @code{read} it to get an object equivalent to the original
one.  In Lisp-family languages, this is called @emph{read/write invariance}
and is a built-in feature.
Note that some objects do not have this invariance
in nature, so sometimes you need to make your own serializer/marshaller.}.
The external representation of most Scheme objects
are the ones you write literal data in program, so this is the default way
of writing Scheme objects out.
@item
Display-family procedures: 
@code{display}, @code{print}, @code{newline}.
These are to produce plain-text output suitable for human readers.
@end itemize

@item High-level formatting output
To produce output in specific width, alignment, etc: @code{format}.
This corresponds to C's @code{printf}.

@item Low-level type-specific output
Procedures that deal with raw data.
@itemize @bullet
@item
To output a character or a byte: @code{write-char}, @code{write-byte}.
@item
To output a string or an array of binary data: @code{write-string},
@code{write-uvector}.
@item
To flush the output buffer: @code{flush}, @code{flush-all-ports}.
@end itemize
@end table

@node Output controls, Object output, Layers of output routines, Output
@subsubsection Output controls
@c NODE 出力制御

@deftp {Class} <write-controls>
@clindex write-controls
You can control several aspects of Lisp structure output via
@code{<write-controls>} object.  The object output routines
(e.g. @code{write, display}) and the high-level output routines
(e.g. @code{format}) can take optional write-controls.

The following example may give you some ideas on what
write controls can do:

@example
(write '(1 10 100 1000)
       (make-write-controls :base 16 :radix #t))
 @r{prints} (#x1 #xa #x64 #x3e8)

(write (iota 100)
       (make-write-controls :length 5))
 @r{prints} (0 1 2 3 4 ...)
@end example

The @code{make-write-controls} procedure returns a write-controls object,
which has the following slots (those slot names are taken from Common Lisp's
print control variables):

@defivar <write-controls> length
If this slot has a nonnegative integer, it determines the maximum number
of items displayed for lists and vectors (including uniform vectors).
If the sequence has more elements than the limit, @code{...} is printed
in place.  If this slot is @code{#f} (default), sequence will be written
out fully.
@end defivar

@defivar <write-controls> level
If this slot has a nonnegative integer, it determines the maximum depth
of the structure (lists and vectors) to be displayed.  If the structure
has deeper node, it will be printed as @code{#}.
If this slot is @code{#f} (default), no depth limit is enforced.
@end defivar

@defivar <write-controls> base
This slot must have an integer between 2 and 36, inclusive, and specifies
the radix used to print exact numbers.  The default value is 10.
@end defivar

@defivar <write-controls> radix
This slot must have a boolean value.  If it is true, radix prefix
is always printed before exact numbers.  The default value is @code{#f}.
@end defivar

@defivar <write-controls> pretty
If this slot has true value,
@emph{pretty printing} is used, that is, newlines and indentations are
inserted
to show nested data structures fit in the specified width of columns.
@end defivar

@defivar <write-controls> width
If this slot has a nonnegative integer, it specifies the display
column width used for pretty printing.
@end defivar

A write-controls object is immutable.  If you need a controls object
with a slight variation of an existing controls object, 
use @code{write-controls-copy}.

Note: When we introduced @code{<write-controls>} object in 0.9.5,
we used slot names as @code{print-length}, @code{print-pretty} etc.,
mirroring Common Lisp's special variables.  However, the @code{print-} part
is redundant, as it is a part of a class dedicated to print control.  So
we changed the slot names as of 0.9.6.
The procedures @code{make-write-controls} and @code{write-controls-copy}
accepts both old and new names for the backward compatibility.  The old
code that directly refers to the slots needs to be rewritten (we think
there're a not a lot).  We'll drop the old name support in 1.0 release.
@end deftp

@defun make-write-controls :key length level base radix pretty width
Creates and returns a write-controls object.
@end defun

@defun write-controls-copy controls :key length level base radix pretty width
Returns a copy of another write-controls object @var{controls}.
If keyword arguments are given, those values override the
original values.
@end defun

Note: The high-level output procedures can be recursively called
via @code{write-object} method.  In that case, the write controls
of the root output call will be automatically inherited to the
recursive output calls to the same port.

@node Object output, Formatting output, Output controls, Output
@subsubsection Object output
@c NODE オブジェクトの出力

For the following procedures, the optional @var{port} argument must be
an output port, and when omitted, the current output port is assumed.

Some procedures take @var{port/controls} argument, which can be either
an output port or @code{<write-controls>} object.  For example, @code{write}
takes up to two such optional arguments; that is, you can call it
as @code{(write obj)}, @code{(write obj port)}, 
@code{(write obj controls)}, @code{(write obj port controls)}
or @code{(write obj controls port)}.  When omitted, the port is assumed
to be the current output port, and the controls is assumed to be the default
controls.

@defun write obj :optional port/controls1 port/controls2
@defunx write-shared obj :optional port/controls1 port/controls2
@defunx write-simple obj :optional port/controls1 port/controls2
[R7RS+ write]
The @code{write}-family procedures are used to write an
external representation of Scheme object,
which can be read back by @code{read} procedure.  The three
procedures differ in a way to handle shared or circular structures.

@code{Write} is circular-safe; that is, it uses datum label notation
(@code{#n=} and @code{#n#}) to show cycles.  It does not use datum label
notation for non-circular structures that are merely shared 
(see the second example).

@example
(let1 x (list 1)
  (set-cdr! x x)   ; create a cycle
  (write x))
 @result{} @r{shows} #0=(1 . #0#)

(let1 x (list 1)
  (write (list x x)))
 @result{} @r{shows} ((1) (1))
@end example

@code{Write-shared} is also circular-safe, and it also shows
shared structures using datum labels.  Use this if you need
to preserve topology of a graph structure.

@example
(let1 x (list 1)
  (write-shared (list x x)))
 @result{} @r{shows} (#0=(1) #0#)
@end example

Finally, @code{write-simple} writes out the object recursively
without taking account of shared or circular structures.  This is fast,
for it doesn't need to scan the structure before actually writing out.
However, it won't stop when a circular structure is passed.

When these procedures encounter an object of
a user-defined class, they call the generic function @code{write-object}.

Historical context: @code{Write} has been in Scheme standards, but
handling of circular structures hasn't been specified until R7RS.
In fact, until Gauche 0.9.4,
@code{write} diverged for circular structures.
SRFI-38 introduced the datum-label notation and
@code{write-with-shared-structure} and @code{write/ss} procedures
to produce such notation, and Gauche supported it.
R7RS clarified this issue, and Gauche 0.9.4 followed.
@end defun


@defun write-with-shared-structure obj :optional port
@defunx write/ss obj :optional port
@defunx write* obj :optional port
[SRFI-38]
These are aliases of @code{write-shared} above.

Gauche has been used the name @code{write*} for long, which is
taken from STklos.  SRFI-38 defines @code{write-with-shared-structure}
and @code{write/ss}.  These names are kept for the backward compatibility.
New code should use @code{write-shared}.
@end defun


@defun display obj :optional port/controls1 port/controls2
[R7RS write]
Produces a human-friendly representation of an object @var{obj} 
to the output port.

If @var{obj} contains cycles, @code{display} uses datum-label notation.

When @code{display} encounters an object of
a user-defined class, it calls the generic function @code{write-object}.

@example
(display "\"Mahalo\", he said.")
 @result{} @r{shows} "Mahalo", he said.

(let ((x (list "imua")))
  (set-cdr! x x)
  (display x))
 @result{} @r{shows} #0=(imua . #0#)
@end example
@end defun


@defun print expr @dots{}
Displays @var{expr}s (using @code{display}) to the current output port,
then writes a newline.
@end defun

@defun pprint obj :key port controls width length level newline
Pretty prints @var{obj} to @var{port}, which is defaulted to the current
output port.  The same effect is achieved by passing the @code{write} procedure
a write control with @code{pretty} slot setting to @code{#t}
(in fact, it is how @code{pprint} is implemented), but this procedure
provides more convenient interface when you want to play with the
pretty printer.

By default, @code{pprint} prints a newline after writing @var{obj}.
You can suppress this newline by passing @code{#f} to @var{newline} keyword
argument.

To customize pretty printing, you can pass a write control object
to the @var{controls} keyword argument (the @code{pretty} slot of
@var{controls} is ignored; it'll always printed prettily).
Furthermore, you can override @code{width}, @code{length} and @code{level}
slots of @var{controls}.  If you omit @var{controls}, a reasonable default
value is assumed.
@xref{Output controls}, for the detail of write controls.

@example
(pprint (make-list 6 '(gauche droite)))
 @result{} @r{prints}
  ((gauche droite) (gauche droite) (gauche droite) (gauche droite)
   (gauche droite) (gauche droite))

(pprint (make-list 6 '(gauche droite)) :width 20)
 @result{} @r{prints}
  ((gauche droite)
   (gauche droite)
   (gauche droite)
   (gauche droite)
   (gauche droite)
   (gauche droite))

(pprint (make-list 6 '(gauche droite)) :length 3)
 @result{} @r{prints}
  ((gauche droite) (gauche droite) (gauche droite) ....)

(pprint (make-list 6 '(gauche droite)) :level 1)
 @result{} @r{prints}
  (# # # # # #) 
@end example
@end defun

@deffn {Method} write-object (obj <object>) port
You can customize how the object is printed out by this method.
@end deffn

@defun newline :optional port
[R7RS base]
Writes a newline character to @var{port}.
This is equivalent to @code{(write-char #\newline port)},
@code{(display "\n" port)}.  It is kept for a historical reason.
@end defun


@node Formatting output, Low-level output, Object output, Output
@subsubsection Formatting output
@c NODE フォーマット出力



@defun format dest controls string arg @dots{}
@defunx format controls dest string arg @dots{}
@defunx format dest string arg @dots{}
@defunx format controls string arg @dots{}
@defunx format string arg @dots{}
[SRFI-28+]
Format @var{arg} @dots{} according to @var{string}.
This function is a subset of CommonLisp's @code{format} function,
with a bit of extension.  It is also a superset of SRFI-28,
Basic format strings (@uref{https://srfi.schemers.org/srfi-28/srfi-28.html}).

The @var{dest} argument specifies the destination; if it is an output port, the
formatted result is written to it; if it is @code{#t},
the result is written to the current output port;
if it is @code{#f}, the formatted result is returned as a string.
@var{Dest} can be omitted, as SRFI-28 @code{format};
it has the same effects as giving @code{#f} to the @var{dest}.

The @var{controls} argument is @code{<write-controls>} object
(@pxref{Output controls}), which affects the output of @code{~s} and
@code{~a}.  This is Gauche's extension.

(The unusual function signature of @code{format}
is for the convenience; both @var{dest}
and @var{controls} are optional and they can appear in either order.)

@var{string} is a string that contains format directives.
A format directive is a character sequence begins with tilde, `@code{~}',
and ends with some specific characters.  A format directive takes
the corresponding @var{arg} and formats it.  The rest of string is
copied to the output as is.

@example
(format #f "the answer is ~s" 42)
  @result{} "the answer is 42"
@end example

The format directive can take one or more @var{parameters}, separated
by comma characters.  A parameter may be an integer or a character;
if it is a character, it should be preceded by a quote character.
Parameter can be omitted, in such case the system default value is
used.  The interpretation of the parameters depends on the
format directive.

Furthermore, a format directive can take two
additional flags: atmark `@code{@@}' and colon `@code{:}'.  One or
both of them may modify the behavior of the format directive.
Those flags must be placed immediately before the directive
character.

If a character `@code{v}' or `@code{V}' is in the place of the
parameter, the value of the parameter is taken from the format's
argument.  The argument must be either an integer, a character, or
@code{#f} (indicating that the parameter is effectively omitted).

Some examples:

@table @code
@item ~10,2s
A format directive @code{~s}, with two parameters, 10 and 2.
@item ~12,,,'*A
A format directive @code{~a}, with 12 for the first parameter and
a character `@code{*}' for the fourth parameter.  The second and
third parameters are omitted.
@item ~10@@d
A format directive @code{~d}, with 10 for the first parameter and
`@code{@@}' flag.
@item ~v,vx
A format directive @code{~x}, whose first and second parameter will
be taken from the arguments.
@end table

The following is a complete list of the supported format directives.
Either upper case or lower case character can be used for the format
directive; usually they have no distinction, except noted.

@table @asis
@item @b{~A}
Parameters: @var{mincol},@var{colinc},@var{minpad},@var{padchar},@var{maxcol}

Ascii output.  The corresponding argument is printed by @code{display}.
If an integer @var{mincol} is given, it specifies the minimum number
of characters to be output; if the formatted result is shorter than
@var{mincol}, a whitespace is padded to the right (i.e. the result
is left justified).

The @var{colinc}, @var{minpad} and @var{padchar} parameters
control, if given, further padding.  A character @var{padchar} replaces
the padding character for the whitespace.  If an integer @var{minpad}
is given and greater than 0, at least @var{minpad} padding character
is used, regardless of the resulting width.  If an integer @var{colinc}
is given, the padding character is added (after @var{minpad}) in chunk
of @var{colinc} characters, until the entire width exceeds @var{mincol}.

If atmark-flag is given, the format result is right justified, i.e.
padding is added to the left.

The @var{maxcol} parameter, if given, limits the maximum number of characters
to be written.  If the length of formatted string exceeds
@var{maxcol}, only @var{maxcol} characters are written.
If colon-flag is given as well and the length of formatted string
exceeds @var{maxcol}, @var{maxcol} - 4 characters are written and
a string ``@code{ ...}'' is attached after it.

@example
(format #f "|~a|" "oops")
  @result{} "|oops|"
(format #f "|~10a|" "oops")
  @result{} "|oops      |"
(format #f "|~10@@a|" "oops")
  @result{} "|      oops|"
(format #f "|~10,,,'*@@a|" "oops")
  @result{} "|******oops|"

(format #f "|~,,,,10a|" '(abc def ghi jkl))
  @result{} "|(abc def gh|"
(format #f "|~,,,,10:a|" '(abc def ghi jkl))
  @result{} "|(abc de ...|"
@end example

@item @b{~S}
Parameters: @var{mincol},@var{colinc},@var{minpad},@var{padchar},@var{maxcol}

S-expression output.  The corresponding argument is printed
by @code{write}.  The semantics of parameters and flags are the same
as @code{~A} directive.

@example
(format #f "|~s|" "oops")
  @result{} "|\"oops\"|"
(format #f "|~10s|" "oops")
  @result{} "|\"oops\"    |"
(format #f "|~10@@s|" "oops")
  @result{} "|    \"oops\"|"
(format #f "|~10,,,'*@@s|" "oops")
  @result{} "|****\"oops\"|"
@end example

@item @b{~C}
Parameters: None

Character output.  The argument must be a character, or an error is
signaled.  If no flags are given, the character is printed with @code{display}.
If atmark-flag is given, the character is printed with @code{write}.

@item @b{~D}
Parameters: @var{mincol},@var{padchar},@var{commachar},@var{interval}

Decimal output.  The argument is formatted as an decimal integer.
If the argument is not an integer, all parameters are ignored
(after processing `@code{v}' parameters) and
it is formatted by @code{~A} directive.

If an integer parameter @var{mincol} is given, it specifies minimum
width of the formatted result; if the result is shorter than it,
@var{padchar} is padded on the left (i.e. the result is right
justified).  The default of @var{padchar} is a whitespace.

@example
(format #f "|~d|" 12345)
  @result{} "|12345|"
(format #f "|~10d|" 12345)
  @result{} "|     12345|"
(format #f "|~10,'0d|" 12345)
  @result{} "|0000012345|"
@end example

If atmark-flag is given, the sign `@code{+}' is printed for the
positive argument.

If colon-flag is given, every @var{interval}-th digit of
the result is grouped and @var{commachar} is inserted between them.
The default of @var{commachar} is `@code{,}', and the default of
@var{interval} is 3.

@example
(format #f "|~:d|" 12345)
  @result{} "|12,345|"
(format #f "|~,,'_,4:d|" -12345678)
  @result{} "|-1234_5678|"
@end example

@item @b{~B}
Parameters: @var{mincol},@var{padchar},@var{commachar},@var{interval}

Binary output.  The argument is formatted as a binary integer.
The semantics of parameters and flags are the same as
the @code{~D} directive.

@item @b{~O}
Parameters: @var{mincol},@var{padchar},@var{commachar},@var{interval}

Octal output.  The argument is formatted as an octal integer.
The semantics of parameters and flags are the same as
the @code{~D} directive.

@item @b{~X}
@itemx @b{~x}
Parameters: @var{mincol},@var{padchar},@var{commachar},@var{interval}

Hexadecimal output.
The argument is formatted as a hexadecimal integer.
If `@code{X}' is used, upper case alphabets are used for
the digits larger than 10.  If `@code{x}' is used, lower case
alphabets are used.
The semantics of parameters and flags are the same as
the @code{~D} directive.

@example
(format #f "~8,'0x" 259847592)
  @result{} "0f7cf5a8"
(format #f "~8,'0X" 259847592)
  @result{} "0F7CF5A8"
@end example

@item @b{~F}
Parameters: @var{width},@var{digis},@var{scale},@var{ovfchar},@var{padchar}

Floating-number output.
If the argument is a real number, it is formatted as a decimal floating number.
The @var{width} parameter defines the width of the field; the number is
written out right-justified, with the left room padded with @var{padchar},
whose default is @code{#\space}.  When the formatted output can't fit
in @var{width}, @var{ovfchar} is output @var{width} times if it is given,
or the entire output is shown if @var{ovfchar} is omitted.

@example
(format "~6f" 3.14)          @result{} "  3.14"
(format "~6f" 3.141592)      @result{} "3.141592"
(format "~6,,,'#f" 3.141592) @result{} "######"
(format "~6,,,,'*f" 3.14)    @result{} "**3.14"
@end example

The @var{digits} parameter specifies number of digits shown below the
decimal point.  Must be nonnegative integer.  When omitted, enough digits
to identify the flonum uniquely is generated (same as using
@code{write} and @code{display}---when you read back the number, you'll
get exactly the same flonum.)

@example
(format "~6,3f" 3.141592)    @result{} " 3.142"
(format "~6,0f" 3.141592)    @result{} "    3."
(format "~10,4f" 355/113)    @result{} "    3.1416"
(format "~10,4f" 3)          @result{} "    3.0000"
@end example

If the @var{scale} parameter is given, the argument is multiplied by
@code{(expt 10 scale)} before printing.

If the @code{@@} flag is given, plus sign is printed before the non-negative
number.

@example
(format "~8,3@@f" 3.141592)   @result{} "  +3.142"
@end example

When @var{digits} is smaller than the digits required to represent
the flonum unambiguously, we round at @var{digits}+1 position.  By default,
it is done based on the value the flonum represents---that is, we choose
the rounded value closer to the actual value of the flonum.
It can sometimes lead to unintuitive results, however.  Suppose you want
to round 1.15 at 100ths (that is, round to nearest 10ths).  Unlike
elementary math class, it gives you 1.1.  That's because the flonum
represented by 1.15 is actually tiny bit smaller than 1.15, so it's closer to
1.1 than 1.2.  We show it as 1.15 since no other flonums are closer to
1.15.

But in casual applications, users may perplexed with this behavior.
So we support another rounding mode, which we call notational rounding.
It is based on the notation used for the flonum.  In that mode,
rounding 1.15 to nearest 10ths yields 1.2.  You can get it by
adding @code{:} flag.

@example
(format "~6,1f" 1.15)  @result{} "   1.1"
(format "~6,1:f" 1.15) @result{} "   1.2"
@end example

@item @b{~$}
Parameters: @var{digits},@var{idigits},@var{width},@var{padchar}

Floating-point formatting suitable for currency display.  The @var{digits}
parameter specifies the number of digits after the decimal point (default 2).
The @var{idigits} parameter specifies the minimum number of digits before
the decimal point (default 1).  The @var{width} parameter specifies the 
mininum number of characters for the entire display, 
and if the number of printed characters are smaller than it,
@var{padchar} is displayed on the left to fill the blank.  The default
of @var{width} is 0, and the default of @var{padchar} is @code{#\space}.

If @code{@@} flag is given and the argument is nonnegative, @code{+} is
displayed.

If @code{:} flag is given, the sign is displayed first, before any
padding characters.

If the argument isn't a real number, the object is formatted as if
@code{~wD} directive is given (where @var{w} is @var{width}).

Gauche specific: The number is rounded with notational rounding (see the
description of @code{~F} above for the rounding mode).

@example
(map (cut format "~$" <>) '(1.23 4.5 6))
  @result{} '("1.23" "4.50" "6.00")
@end example


@item @b{~?}
Recursive formatting.  The argument for this directive must be a string
which is interpreted as a format string.  The arguments for the given directive
should be given in the next argument, as a list.

@example
(format "~s~?~s" '< "~s ~s" '(a b) '>)
  @result{} "<a b>"
@end example

If @code{@@} flag is given, the arguments for the given directive
is taken from the following arguments.

@example
(format "~s~@@?~s" '< "~s ~s" 'a 'b '>)
  @result{} "<a b>"
@end example

@item @b{~*}
Parameter: @var{count}

Moves the argument counter @var{count} times forward, effectively skips
next @var{count} arguments.  The default value of @var{count} is 1,
hence skip the next argument.  If a colon-flag is given, moves the argument
counter backwards, e.g. @code{~:*} makes the next directive to process
last argument again.  If an atmark-flag is given, @var{count} specifies
absolute position of the arguments, starting from 0.

@item @b{~~}
@itemx @b{~%}
@itemx @b{~t}
@itemx @b{~|}
Parameter: @var{count}

Output a @code{#\~}, @code{#\newline}, @code{#\tab} and @code{#\page}, 
respectively.    If @var{count} is given, output the specified number
of characters.

@end table
@end defun


@node Low-level output,  , Formatting output, Output
@subsubsection Low-level output
@c NODE 低レベル出力

@defun write-char char :optional port
[R7RS base]
Write a single character @var{char} to the output port @var{port}.
@end defun

@defun write-byte byte :optional port
@defunx write-u8 byte :optional port
[R7RS base]
Write a byte @var{byte} to the port.
@var{byte} must be an exact integer in range between 0 and 255.

This is traditionally called @code{write-byte}, and
R7RS calls it @code{write-u8}.  You can use either.
@end defun

@defun write-string string :optional oport start end
[R7RS base]
If the optional @var{start} and @var{end} arguments are omitted,
it is the same as @code{(display string oport)}.  The optional
arguments restricts the range of @var{string} to be written.
@end defun


@defun flush :optional port
@defunx flush-all-ports
Output the buffered data in @var{port}, or all ports, respectively.

The function "flush" is called in variety of ways on the various
Scheme implementations: @code{force-output} (Scsh, SCM),
@code{flush-output} (Gambit), or @code{flush-output-port} (Bigloo).
The name @code{flush} is taken from STk and STklos.
R7RS calls this @code{flush-output-port}
@end defun


@c ----------------------------------------------------------------------
@node Loading Programs, Sorting and merging, Input and output, Core library
@section Loading Programs
@c NODE プログラムのロード

@menu
* Loading Scheme file::
* Loading dynamic library::
* Require and provide::
* Autoload::
* Operations on libraries::
@end menu

@node Loading Scheme file, Loading dynamic library, Loading Programs, Loading Programs
@subsection Loading Scheme file
@c NODE Schemeファイルのロード

@defun load file :key paths (error-if-not-found #t) environment ignore-coding
[R7RS+]
Loads @var{file}, that is, read Scheme expressions in @var{file} and
evaluates them.
An extension ``@code{.scm}'' may be omitted from @var{file}.

If @var{file} doesn't begin with ``/'' or ``./'' or ``../'',
it is searched from the system file search list,
stored in a variable @code{*load-path*}.
Or you can explicitly specify the search path by passing
a list of directory names to the keyword argument @var{paths}.

On success, @code{load} returns @code{#t}.
If the specified file is not found, an error is signaled unless
the keyword argument @var{error-if-not-found} is @code{#f}, in
which case @code{load} returns @code{#f}.

By default, @code{load} uses a coding-aware port
(@pxref{Coding-aware ports}) so that the "@code{coding:}" magic
comment at the beginning of the source file is effective.
(See @ref{Multibyte scripts}, for the details of
the coding magic comment).  If a true value is given to the
keyword argument @var{ignore-coding}, @code{load} doesn't
create the coding-aware port and directly reads from the
file port.

If a module is given to the keyword argument @var{environment},
@code{load} works as if the given module is selected at the beginning
of the loaded file.

The current module is preserved; even @code{select-module} is
called in @var{file}, the module in which @code{load} is called
is restored afterwards.

Gauche's @code{load} is upper-compatible to R5RS @code{load}, but
R7RS @code{load} differs in optional arguments; @pxref{R7RS load}.

If you want to load a library file, it's better to use `@code{use}'
(@pxref{Defining and selecting modules}), or `@code{require}' described below.
@xref{Compilation}, for difference between @code{load} and @code{require}.
@end defun

@defvar *load-path*
Keeps a list of directories that are searched by @code{load} and
@code{require}.

If you want to add other directories to the search path,
do not modify this variable directly; use @code{add-load-path},
described below, instead.
@end defvar

@defspec add-load-path path flag @dots{}
Adds a path @var{path} to the library load path list.
@var{Path} must be a literal string, for load paths must be
known at compilation time.
If @var{path} is a relative path, it is resolved relative to
the current working directory, unless @code{:relative} flag is given.

@var{Path} doesn't need to exist; nonexisting paths in load path list
are simply ignored.  However, if @var{path} does exist, @code{add-load-path}
searches for architecture-dependent paths; see below.

Each @var{flag} argument may be one of the followings.

@table @code
@item :after
Append @var{path} to the end of the current list of load paths.
By default, @var{path} is added in front of the load path list.
@item #t
The same as @code{:after}.  This is for the backward compatibility.
@item :relative
Interpret @var{path} as a relative path to the directory of
the current file, instead of the current working directory.
If the current file can't be determined (e.g. evaluated in REPL, or
the expression is read from a socket), this flag is ignored.
@end table

Use this form instead of changing @code{*load-path*} directly.
This form is a special form and recognized by the compiler;
if you change @code{*load-path*}, it is in effect at run time,
and that may be too late for ``use'' or ``require''.

Furthermore,
@code{add-load-path} looks for the architecture dependent directories
under the specified path and if it exists, sets up the internal
path list for dynamic loading correctly.   Suppose you have
your Scheme module in @code{/home/yours/lib}, and that requires
a dynamic loadable library.  You can put the library under
@code{/home/yours/lib/@var{ARCH}/}, where @var{ARCH} is
the value @code{(gauche-architecture)} returns (@pxref{Environment inquiry}).
Then you can have compiled libraries for multiple platforms and
Gauche can still find the right library.
@end defspec

@defun load-from-port port
Reads Scheme expressions from an input port @var{port} and evaluates
them, until EOF is read.

Note that unless you pass a coding-aware port to @var{port},
the "@code{coding:}" magic comment won't be handled.
@end defun

@defun current-load-port
@defunx current-load-path
@defunx current-load-history
@defunx current-load-next
These procedures allows you to query the current context of loading.
They returns the following values when called inside a file being loaded:
@table @code
@item current-load-port
Returns the port object from which this form is being loaded.
@item current-load-path
Returns the pathname of the file from which this form is being loaded.
Note that this may return @code{#f} if the source of @code{load} is
not a file.
@item current-load-history
Returns a list of pairs of a port and a line number (integer),
representing the nesting of loads.  Suppose you load
@file{foo.scm}, and from its line 7 it loads @file{bar.scm},
and from its line 18 it loads @file{baz.scm}.   If you call
@code{current-load-history} in the file @file{baz.scm}, you'll get
@example
((#<port "foo.scm"> . 7) (#<port "bar.scm"> . 18))
@end example
@item current-load-next
Returns a list of remaining directories to be searched
at the time this file is found.   Suppose the @code{*load-path*}
is @code{("." "../lib" "/home/gauche/lib" "/share/gauche/lib")}
and you load @file{foo.scm}, which happens to be in @file{../lib/}.
Then, inside @file{foo.scm}, @code{current-load-next} returns:
@example
("/home/gauche/lib" "/share/gauche/lib")
@end example
@end table

When called outside of @code{load}, these procedures returns
@code{#f}, @code{#f}, @code{()} and @code{()}, respectively.
@end defun


@node Loading dynamic library, Require and provide, Loading Scheme file, Loading Programs
@subsection Load dynamic library
@c NODE ダイナミックライブラリのロード

@defun dynamic-load file :key init-function
Loads and links a dynamic loadable library (shared library) @var{file}.
@var{File} shouldn't contain the suffix (``.so'' on most systems);
@code{dynamic-load} adds it, for it may differ among platforms.

The keyword argument @var{init-function} specifies the initialization
function name of the library in a string.  By default, if the file
basename (without extension) is ``foo'', the initialization function
name is ``Scm_Init_foo''.

Usually a dynamic loadable library is provided with wrapping Scheme
module, so the user doesn't have to call this function directly.

There's no way to unload the loaded libraries.
@end defun


@node Require and provide, Autoload, Loading dynamic library, Loading Programs
@subsection Require and provide
@c NODE requireとprovide

@code{Require} and @code{provide} are a traditional Lisp way to ensure
loading a library file only once.  If you require a @emph{feature}
for the first time, a library file that provides it is loaded
and the fact that the @emph{feature} is provided is memorized.
Subsequent request of the same feature doesn't need to load the file.

In Gauche, the @code{use} syntax (@pxref{Using modules}) hides
the require mechanism under the hood so you hardly need to see
these forms.  These are provided just in case if you want to
do some non-trivial management of libraries and thus want to
bypass Gauche's standard mechanism.

@defspec require feature
If @var{feature} is not loaded, load it.  @var{Feature} must be a string,
and it is taken as a file name (without suffix) to be loaded.
This loading takes place at compile time.

If you load SLIB module, @code{require} is extended.  @pxref{SLIB} for
details.

If the loaded file does not contain @code{provide} form at all,
the @var{feature} is automatically provided, as if
@code{(provide @var{feature})} is called at the end of the loaded
file.  We call this @emph{autoprovide} feature.

Note that @code{require} first sets the current module to
an immutable module called @code{gauche.require-base}
and then load the file.  The files
loaded by @code{require} usually have @code{define-module}/@code{select-module}
or @code{define-library} for the first thing, so you rarely notice the
@code{gauche.require-base} module.  However, if the loaded file
has toplevel defines or imports (@code{use}'s) without specifying
a module, you'll get an error like the following:

@example
*** ERROR: Attempted to create a binding (a) in a sealed
module: #<module gauche.require-base>
@end example

Rationale: Generally it's difficult to guarantee 
when the specified file is loaded by @code{require} (because some other
module may already have required it).  If we just used the caller's current
module, there would be a couple of issues: The form @code{define-module} or
@code{define-library} may not be visible from the current module, and
you can't guarantee if the toplevel defines without specifying modules
in the loaded file inserts the caller's current module, since they may
have been loaded into a different module.
It is just a bad idea to insert
toplevel definitions or to import other modules without specifying which
module you put them in.  So we made them an error.
@end defspec

@defun provide feature
Adds @var{feature} to the system's provided feature list, so that
the subsequent @code{require} won't load the same file again.

Because of the autoproviding, i.e. @code{require}
automatically provides the required feature, you hardly need to
use a @code{provide} form explicitly.   There are a couple of scenarios that
you may want to use a @code{provide} form:

@itemize
@item
To provide a feature (or features) that is/are different from
the one that caused loading the file.

Suppose feature X supersedes feature Y and providing
compatible APIs of Y but with different implementation.
Once @file{X.scm} is loaded, you don't want @file{Y.scm} to be loaded;
so you want to tell the user that @file{X.scm} also provides the feature Y.
Adding @code{(provide "X")} and @code{(provide "Y")} at the end of
@file{X.scm} accomplish that.  (Note: If you add a provide form,
@code{require} no longer autoprovides the feature, so you need
to specify @code{(provide "X")} in @file{X.scm} explicitly to
provide X as well.)

Of course, this doesn't prevent users from loading @file{Y.scm} by
specifying @code{(require "Y")} before @code{(require "X")}.
It should be considered just as a workaround in a production
where other solutions are costly, instead of a permanent solution.

@item
To provide no features at all.  Passing @code{#f} as @var{feature}
prevents autoproviding by @code{require} without providing any
feature.

This should also be a temporary solution.  One possible scenario is
that you are changing @file{X.scm} very frequently during
development and you want @code{(require "X")} always causes loading
the file.  Don't forget to remove @code{(provide #f)} when you release
the file, though.  Besides, for interactive reloading, consider
using @code{gauche.reload} (@pxref{Reloading modules}) instead.
@end itemize

@end defun

@defun provided? feature
Returns @code{#t} if @var{feature} is already provided.
@end defun

@node Autoload, Operations on libraries, Require and provide, Loading Programs
@subsection Autoload

@defmac autoload file/module item @dots{}
Sets up @var{item} @dots{} to be autoloaded.
That is, when an @var{item} is referenced for the first time,
@var{file/module} is loaded before the @var{item} is evaluated.
This delays the loading of @var{file/module} until it is needed.

You can specify either a string file name or a symbol module name
to @var{file/module}.  If it is a string, the named file is
loaded.  If it is a symbol, the named module is loaded (using the
same rule as of @code{use}), then the binding of @var{item} in the
@var{file/module} is imported to the module used the autoload
(@xref{Defining and selecting modules}, for details of @code{use}).

@var{Item} can be either a variable name (symbol),
or a form @code{(:macro @var{symbol})}.  If it is a variable,
the named file/module is loaded when the variable is
about to be evaluated.  If it is the latter form,
the named file/module is loaded when a form
@code{(@var{symbol} arg @dots{})} is about to be @emph{compiled},
which enables autoloading macros.

@var{file/module} must define @var{symbol} in it, or an error is signaled
when @var{file/module} is autoloaded.

The following is an example of autoloading procedures.
@example
(autoload "foo" foo0 foo1)
(autoload "bar" bar0 bar1)

(define (foobar x)
  (if (list? x)
      (map bar0 x)
      (foo0)))

(foobar '(1 2)) ; @r{"bar" is loaded at this moment}

(foobar #f)     ; @r{"foo" is loaded at this moment}
@end example

Note that if you set to autoload macro, the file/module is loaded
immediately when such form that uses the macro is compiled,
regardless of the piece of
the code is executed or not.
@end defmac

@node Operations on libraries,  , Autoload, Loading Programs
@subsection Operations on libraries
@c NODE ライブラリの操作

There are several procedures you can use to check if
certain libraries and/or modules are installed in the system.

In the following descriptions, @var{pattern} is either a
symbol or a string.  If it is a symbol, it specifies
a module name (e.g. @code{foo.bar}).  If it is
a string, it specifies a partial pathname of the library
(e.g. @code{"foo/bar"}), which will be searched under
library search paths.
You can also use glob-like metacharacters @code{*} and
@code{?} in @var{pattern}.

@defun library-fold pattern proc seed :key paths strict? allow-duplicates?
A basic iterator for library/module files.
This procedure searches Scheme program files which matches
@var{pattern}, under directories listed in @var{paths}
(the default is the standard file load paths, @code{*load-path*}).
For each matched file, it calls @var{proc} with three arguments:
the matched module or library name, the full path of the program
file, and the state value.  @var{Seed} is used as the initial
state value, and the value @var{proc} returns is used as the state
value for the next call of @var{proc}.  The value returned from
the last @var{proc} becomes the return value of @code{library-fold}.



If @var{pattern} is a symbol and the keyword argument @var{strict?}
is @code{#t} (which is the default), this procedure calls
@code{library-has-module?} on the files whose name seems to
match the given pattern of module name, in order to find out
the file really implements the module.  It can be a time consuming
process if you try to match large number of modules; you can pass
@code{#f} to @var{strict?} to avoid the extra check.
If @var{pattern} is a string, matching is done only for file names
so @var{strict?} is ignored.

By default, if there are more than one files that have the same name
that matches @var{pattern} in @var{paths}, only the first
one appears in @var{paths} is taken.  This gives you
the file you'll get if you use @code{require} or @code{use}
for that library.  If you want to iterate all of matching files,
pass @code{#t} to the @var{allow-duplicates?} keyword argument.

Here are some examples (the result may differ in your environment).
@example
(library-fold 'srfi-1 acons '())
 @result{} ((srfi-1 . "../lib/srfi-1.scm"))

(library-fold "srfi-1" acons '())
 @result{} (("srfi-1" . "../lib/srfi-1.scm"))

;; Note the returned list is in a reverse order of
;; how @code{acons} is called.
(library-fold 'srfi-1 acons '() :allow-duplicates? #t)
 @result{} ((srfi-1 . "/usr/share/gauche/0.7.1/lib/srfi-1.scm")
   (srfi-1 . "../lib/srfi-1.scm"))

;; In the following cases, the module name doesn't match,
;; but the filename does.
(library-fold 'srfi-19.* acons '())
 @result{} ()

(library-fold "srfi-19/*" acons '())
 @result{} (("srfi-19/read-tai" . "../lib/srfi-19/read-tai.scm")
   ("srfi-19/format" . "../lib/srfi-19/format.scm"))

;; Finds available dbm implementations
(library-fold 'dbm.* acons '())
 @result{} ((dbm.cdb . "/usr/share/gauche/0.7.1/lib/dbm/cdb.scm")
   (dbm.gdbm . "../lib/dbm/gdbm.scm")
   (dbm.ndbm . "../lib/dbm/ndbm.scm")
   (dbm.odbm . "../lib/dbm/odbm.scm"))
@end example
@end defun

@defun library-map pattern proc :key paths allow-duplicates? strict?
@defunx library-for-each pattern proc :key paths allow-duplicates? strict?
@code{Map} and @code{for-each} version of iterator over matched
libraries/modules.  See @code{library-fold} above for detailed
operation of matching and the meanings of keyword arguments.

@var{Proc} receives two arguments, the matched module/library name
and full path of the file.  @code{Library-map} returns a list
of results of @var{proc}.  @code{Library-for-each} discards
the results.

@example
(library-map 'srfi-4 list :allow-duplicates? #t)
 @result{} ((srfi-4 "../lib/srfi-4.scm")
            (srfi-4 "/usr/share/gauche/0.7.1/lib/srfi-4.scm"))

(library-map 'dbm.* (lambda (m p) m))
 @result{} (dbm.odbm dbm.ndbm dbm.gdbm dbm.cdb)
@end example
@end defun

@defun library-exists? mod/path :key paths force-search? strict?
Search a library or a module specified by @var{mod/path},
and returns a true value if it finds one.  @var{Paths} and @var{strict?}
keyword arguments have the same meaning as @code{library-fold}.

Unlike the iterator procedures above, this procedure first
checks loaded libraries and modules in the calling process,
and returns true if it finds @var{mod/path} in it,
without looking into the filesystem.   Passing @code{#t} to
@var{force-search?} keyword arguments skips the checking of
loaded libraries and modules.
@end defun


@defun library-has-module? path module
Returns @code{#t} iff a file specified by @var{path} exists and
appears to implement a module named by @code{module}.  @var{path} must be
an actual filename.

@example
(library-has-module? "./test/foo/bar.scm" 'foo.bar)
 @result{} #t ;; @r{if ./test/foo/bar.scm implements module foo.bar}.
@end example

This procedure assumes a typical layout of the source code
to determine if the given file implements the module, i.e.,
it reads the first form of the code and see if it is a
@code{define-module} form that is defining the given module.
@end defun

@c ----------------------------------------------------------------------
@node Sorting and merging, System interface, Loading Programs, Core library
@section Sorting and merging
@c NODE ソートとマージ

The interface of sorting and merging API complies SRFI-95, with the
following extensions:

@itemize @bullet
@item
You can sort not only lists, vectors and strings, but
any sequence (an instance of @code{<sequence>}).
@item
You can use both comparison procedures
and comparators (@pxref{Basic comparators}) to specify the order.
@item
You can omit comparison procedure; in that case,
elements are compared with @code{default-comparator}.
@end itemize

@defun sort seq :optional cmp keyfn
@defunx sort! seq :optional cmp keyfn
[SRFI-95+]
Sorts elements in a sequence @var{seq}
in ascending order and returns the sorted sequence.
@code{sort!} destructively reuses the original sequence.

You can pass an instance of any @code{<sequence>} as @var{seq};
the same type of sequence will be returned.  For @code{sort}, the
sequence type must have builder interface so that @code{sort} can
build a new sequence of the same type (See @ref{Fundamental iterator creators}, 
for the builder interface).
For @code{sort!}, @var{seq} must be mutable.

The sorting order is specified by @code{cmp}.  It must be
either a procedure or a comparator.
If it is a procedure, it
must take two elements of @var{seq}, and returns @code{#t}
if the first argument strictly precedes the second.
If it is a comparator, it must have the comparison procedure.
If omitted, @code{default-comparator} is used.

If the optional argument @var{keyfn} is given, the elements are
first passed to it and the results are used for comparison.
It is guaranteed that @var{keyfn} is called at most once per
element.

@example
(sort '(("Chopin" "Frederic")
        ("Liszt" "Franz")
        ("Alkan" "Charles-Valentin"))
      string<?
      car)
  @result{} (("Alkan" "Charles-Valentin")
      ("Chopin" "Frederic")
      ("Liszt" "Franz"))
@end example

In the current implementation, quicksort and heapsort
algorithm is used when both @var{cmp} and @var{keyfn} is omitted,
and merge sort algorithm is used otherwise.  That is, the sort
is stable if you pass at least @var{cmp} (note that to guarantee
stability, @var{cmp} must return @code{#f} when given identical arguments.)
SRFI-95 requires stability, but also requires @var{cmp} argument,
so those procedures are upper-compatible to SRFI-95.

If you want to keep a sorted set of objects to which you
add objects one at at time, you can also use treemaps
(@pxref{Treemaps}).  If you only need to find out 
a few maximum or minimum elements instead of sorting
all the elements, heaps can be used (@pxref{Heap}).
@end defun

@defun sorted? seq :optional cmp keyfn
[SRFI-95+]
Returns @code{#t} iff elements in @var{seq} are in sorted order.
You can pass any sequence to @var{seq}.
The optional argument @var{cmp} and @var{keyfn} are the same as
@code{sort}.

In SRFI-95, @var{cmp} can't be omitted.
@end defun


@defun merge a b :optional cmp keyfn
@defunx merge! a b :optional cmp keyfn
[SRFI-95+]
Arguments @var{a} and @var{b} are lists, and their elements are
sorted using a compare function or a comparator @var{cmp}.  These procedures
merges two list and returns a list, whose elements are sorted
using @var{cmp}.  The destructive version @code{merge!} reuses
cells in @var{a} and @var{b}; the returned list is @code{eq?} to
either @var{a} or @var{b}.

In SRFI-95, @var{cmp} can't be omitted.
@end defun

The following procedures are for the backward compatibility.  Their
features are already covered by extended @code{sort} and @code{sort!}.


@defun stable-sort seq :optional cmp keyfn
@defunx stable-sort! seq :optional cmp keyfn
Sort a sequence @var{seq}, using stable sort algorithm.
Arguments @var{cmp} and @var{keyfn} are the same as @code{sort}
and @code{sort!}.

In fact, @code{sort} and @code{sort!} now uses stable algorithm
when @var{cmp} is provided, so these procedures are redundant,
unless you want to omit @var{cmp} and yet guarantee stable sort.
@end defun

@defun sort-by seq keyfn :optional cmp
@defunx sort-by! seq keyfn :optional cmp
@defunx stable-sort-by seq keyfn :optional cmp
@defunx stable-sort-by! seq keyfn :optional cmp
Variations of sort procedures that takes a key extracting function.
These are redundant now, for @code{sort} etc. takes optional @var{keyfn}.
@end defun


@c ----------------------------------------------------------------------
@node System interface, Development helper API, Sorting and merging, Core library
@section System interface
@c NODE システムインタフェース

Gauche supports most of POSIX.1 functions and other system functions
popular among Unix variants as built-in procedures.

Lots of Scheme implementations provide some sort of system interface
under various APIs.  Some are just called by different names
(e.g, @code{delete-file} or @code{remove-file} or @code{unlink} to delete
a file), some do more abstraction introducing new Scheme objects.
Instead of just picking one of such interfaces, I decided to implement
Gauche's system interface API in two layers; the lower level layer,
described in this section, follows the operating system's API
as close as possible.  On top of that, the higher-level APIs are
provided, with considering compatibility to the existing systems.

The low level system interface has the name @code{sys-}@var{name}
and usually correspond to the system call @var{name}.
I tried to keep the interface similar whenever reasonable.

Gauche restarts a system call after it is interrupted by a signal by default.
See @ref{Signal} for the details.

If you are familiar with system programming in C,
see also @ref{C to Scheme mapping}, which shows
correspondence between C standard library functions
and Gauche procedures.

@menu
* Program termination::
* Command-line arguments::
* Environment inquiry::
* Filesystems::
* Unix groups and users::
* Locale::
* Signal::
* System inquiry::
* Time::
* Process management::
* I/O multiplexing::
* Garbage collection::
* Miscellaneous system calls::
@end menu

@node Program termination, Command-line arguments, System interface, System interface
@subsection Program termination
@c NODE プログラムの終了

Gauche has a few ways to terminate itself (other than returning
from @code{main}).  The @code{exit} procedure is a graceful way
with all proper cleanups.  @code{sys-exit} and @code{sys-abort}
may be used in emergency where proper cleanup is impossible.


@defun exit :optional (code 0) (fmtstr #f) args @dots{}
[R7RS+]
Terminates the current process with the exit code @var{code}.
@var{Code} must be zero or positive exact integer.
When a string is given to @var{fmtstr}, it is passed to
@code{format} (@pxref{Output}), with the rest arguments @var{args},
to produce a message to the standard error port
(@emph{not} the current error port; see @ref{Common port operations}).

In fact, the exiting procedure is a bit more complicated.
The precise steps of exiting is as follow.

@enumerate
@item
The value of parameter @code{exit-handler} is checked.
If it is not @code{#f}, the value is called as a procedure
with three arguments: @var{code}, @var{fmtstr}, and a list of rest
arguments.  It is the default procedure of @code{exit-handler}
that prints out the message to the standard error port.
If an error occurs within exit handler, it is captured and
discarded.  Other exceptions are not caught.

@item
The @var{after} thunks of the active dynamic winds are invoked.
Any exceptions raised in @var{after} thunks are captured and discarded.

@item
The clean-up handlers registered via C API @code{Scm_AddCleanupHandler}
are invoked.  These are usually responsible for under-the-hood cleanup
jobs for each application that embeds Gauche.  From the Scheme world
there's not much to care.

@item
The unclosed output buffered ports are flushed.

@item
The process exits with @var{code} as an exit code, via @code{exit(3)}.
@end enumerate

The @code{exit-handler} mechanism allows the application to hook its
exit operation.   Note that it is not for simple cleanup jobs;
@code{dynamic-wind}, @code{guard} or @code{unwind-protect} are more appropriate.
@code{exit-handler} is for more specific use just upon application exit.
For example, GUI applications may want to post a dialog
instead of printing to stderr.

For this reason, the library code shouldn't change @code{exit-handler};
only the application knows what to do when it exits.

Another useful case is when you
want to call a third-party code which calls @code{exit} inside.  In
that case you may swap the @code{exit-handler} for the one
that raises a non-error exception while calling the third-party code.
Non-error exception isn't caught in @code{exit}, effectively
interrupts the steps explained above.   (Yet the @var{after} thunks
of dynamic handlers are processed just like normal exception
handling case.)
Your application code can then capture the exception.
You can use @code{parameterize}
to swap @code{exit-handler} dynamically
and thread-safely (@pxref{Parameters}).

@example
(guard (e [(eq? e 'exit-called) (handle-exit-as-desired)])
  (parameterize ((exit-handler (lambda (c f a) (raise 'exit-called))))
    (call-third-party-library)))
@end example

Generally, calling @code{exit} while other threads are running
should be avoided, since it only rewinds the dynamic handlers active
in the calling threads, and other threads will be killed abruptly.
If you have to do so for some reason,
you may be able to use @code{exit-handler} to tell to other threads
that the application is exiting.  (There's no general way, and
Gauche doesn't even have a list of all running threads; it's application's
responsibility).

Note on design: Some languages integrates exit handling
into exception handling, treating exit as a kind of exception.
It is a tempting idea, so much that we've tried it.  It didn't
work out well in Gauche; a big annoyance was that when
an @var{after} thunk raised an exception during
rewinding @code{dynamic-wind}s, it shadowed the original
@emph{exit} exception.
@end defun

@defun exit-handler :optional new-handler
When called without argument, returns the value of the current exit
handler.  When called with an argument, sets @var{new-handler} as the
value of the exit handler, and returns the previous value of the
exit handler.    @var{new-handler} must be a procedure that takes
three arguments, or @code{#f}.

The value of exit handler is thread-specific, and the default value
is inherited from the value of the current exit handler of the parent
thread.  @code{exit-handler} can be used as if it's a parameter
in the @code{parameterize} macro (@pxref{Parameters}).
@end defun



@defun sys-exit code
[POSIX]
Terminates the current process with the exit code @var{code}.
@var{Code} must be zero or positive exact integer.
This procedure calls @code{_exit(2)} directly.
No cleanup is done.  Unflushed file output is discarded.
@end defun

@defun sys-abort
[POSIX]
Calls POSIX abort().  This usually terminates the running process
and dumps core.  No cleanup is done.
@end defun

@node Command-line arguments, Environment inquiry, Program termination, System interface
@subsection Command-line arguments
@c NODE コマンドライン引数

The recommended way to get command-line arguments passed to a
Scheme script is the argument to the @code{main} procedure
(@pxref{Writing Scheme scripts}).  For the convenience,
there are a few ways to access to the command-line arguments
globally.

Note that a Scheme code may not always be called with a command-line
argument---for example, an application-embedded Scheme scriptlet may
not have the concept of command-line at all.  That's why the @code{main}
argument is preferred, since it is an explicit interface; if @code{main}
is called, the caller is responsible to pass in something.

That said, here are how to access the command-line arguments:

@deffn {Parameter} command-line
[R7RS+][SRFI-193]
When called without arguments, it returns a list of command-line arguments,
including the program name in the first element, as a list of strings.

When Gauche is used as an embedded language, it is application's discretion
to set up this parameter.  If the application does nothing, this parameter
will have an empty list.  When you use this parameter in the library
you have to deal with that situation.

When called with one argument, a list of string, it will become the
new value of the parameter.  You can use @code{parameterize} to
switch the value of @code{command-line} dynamically
(@pxref{Parameters}).  Note that R7RS only defines zero-argument
@code{command-line}.
@end deffn

@deffn {Parameter} script-file
[SRFI-193]
While a Scheme program is run as a @emph{script}, this parameter holds
the absolute path of the Scheme source file being run.  Run as a script
means either it is passed as the script file to @code{gosh}, or
the file is directly @code{load}ed from the toplevel REPL.

If this function is called from the context outside of script execution,
@code{#f} is returned.
@end deffn


@defvar *program-name*
@defvarx *argv*
These variables are bound to the program name and the list of command-line
arguments, respectively.  In Gauche scripts that are invoked by @code{gosh}
command, @code{*program-name*} is usually the name of the script, as
given to @code{gosh}.  When @code{gosh} is invoked interactively,
@code{*program-name*} is @code{gosh} itself.

These variables exist in @code{user} module.

They are mainly kept for the backward compatibility.
These names are compatible to STk, but other Scheme implementation uses
different conventions.  The @code{command-line} parameter above is
preferred.

When Gauche is used as an embedded language, it's the host application's
discretion to set up these variables.  Generally, you can't count on
those variables to exist.  That's another reason you should avoid
using them.
@end defvar


@node Environment inquiry, Filesystems, Command-line arguments, System interface
@subsection Environment inquiry
@c NODE 環境の問い合わせ

@defun sys-getenv name
[POSIX]
Returns the value of the environment variable @var{name} as a string,
or @code{#f} if the environment variable is not defined.

For the portable code, you may want to use SRFI-98's
@code{get-environment-variable} (@pxref{Accessing environment variables}),
which is also in R7RS.

Note: Most systems doesn't guarantee thread-safety of @code{getenv} while
environment is being modified; however, Gauche mutexes environment
accessing/mutating APIs internally, so you don't need to worry
about the race condition as far as you use Gauche procedures.
@end defun

@defun sys-environ
Returns the current environment as a list of strings.  Each string
is a form of @code{NAME=VALUE}, where @code{NAME} is the name of
the environment variable and @code{VALUE} is its value.  @code{NAME}
never contains a character @code{#\=}.  This is useful when you want
to obtain the all environment variables of the current process.
Use @code{sys-getenv} if you want to query a specific environment
variable.
@end defun

@defun sys-environ->alist :optional envlist
A convenience procedure for @code{sys-environ}.  When the list of
environment strings (like what @code{sys-environ} returns) is given
to @var{envlist}, this procedure splits name and value of
each environment variable and returns an assoc list.

When @var{envlist} is omitted, this procedure calls @code{sys-environ}
to get the current environment variables.

For the portable code, you may want to use SRFI-98's
@code{get-environment-variables} (@pxref{Accessing environment variables}),
which is also in R7RS.

@example
(sys-environ->alist '("A=B" "C=D=E"))
  => (("A" . "B") ("C" . "D=E"))
@end example
@end defun


@defun sys-setenv name value :optional overwrite
@defunx sys-putenv name=value
@var{sys-setenv} inserts an environment variable @var{name} with
the value @var{value}.
Both @var{name} and @var{value} must be a string.
If the optional argument @var{overwrite} is @code{#f} (default),
the environment is untouched if a variable with @var{name} already
exists.   If @var{overwrite} is true, the variable is overwritten.

For @code{sys-putenv}, you have to give a single string
with the form of @code{NAME=VALUE}, that is, concatenating @var{name}
and @var{value} with @code{#\=}.  If the environment variable with
the same name exists, it will be overwritten.

These API reflects POSIX @code{setenv(3)} and @code{putenv(3)}.
However, unlike @code{putenv(3)}, modifying the string passed
to @code{sys-putenv} afterwards won't affect the environment.

These procedures are only available when a feature identifier
@code{gauche.sys.setenv} exists.  Use @code{cond-expand}
(@pxref{Feature conditional}) to check their availability.

@example
(cond-expand
 [gauche.sys.setenv
   ... use sys-setenv or sys-putenv ... ]
 [else
   ... fallback code ...])
@end example

These procedures are thread-safe as far as you access and modify
the environment through Gauche API.
@end defun

@defun sys-unsetenv name
@defunx sys-clearenv
Remove the environment variable with @var{name} (@code{sys-unsetenv}),
or all environment variables.  @code{sys-clearenv} is handy
when you need to run subprocess, but you cannot trust the inherited
environment.

These procedures are only available when a feature identifier
@code{gauche.sys.unsetenv} exists.  Use @code{cond-expand}
(@pxref{Feature conditional}) to check their availability.

@example
(cond-expand
 [gauche.sys.unsetenv
   ... use sys-unsetenv or sys-clearenv ... ]
 [else
   ... fallback code ...])
@end example
@end defun


SRFI-98 (@pxref{Accessing environment variables}) also defines
a subset of above procedures to access to the environment variables.
Portable programs may want to use them instead.


@defun gauche-version
@defunx gauche-architecture
@defunx gauche-library-directory
@defunx gauche-architecture-directory
@defunx gauche-site-library-directory
@defunx gauche-site-architecture-directory
These functions returns a string that tells information about Gauche
runtime itself.
@end defun

@defun version-alist
[SRFI-176]
Returns an alist of various runtime information.
The information is the same as what displayed with @code{gosh -V}.
@end defun

@defun sys-available-processors
Returns the number of available processors on the running platform.
Return value is always a positive exact integer.  If Gauche can't
get the information, 1 is returned.

However,
If an environment variable @code{GAUCHE_AVAILABLE_PROCESSORS} is
defined and its value can be interpreted as a positive integer,
then the value is returned regardless of what the hardware/OS tells.
@end defun

@node Filesystems, Unix groups and users, Environment inquiry, System interface
@subsection Filesystems
@c NODE ファイルシステム

System calls that deal with filesystems.
See also @ref{Filesystem utilities}, which defines high-level APIs
on top of the procedures described here.

@menu
* Directories::
* Directory manipulation::
* Pathnames::
* File stats::
* Other file operations::
@end menu

@node Directories, Directory manipulation, Filesystems, Filesystems
@subsubsection Directories
@c NODE ディレクトリ

See also @ref{Directory utilities} for high-level API.

@defun sys-readdir path
@var{path} must be a string that denotes valid pathname of an existing
directory.  This function returns a list of strings of the directory
entries.  The returned list is not sorted.  An error is signaled
if @var{path} doesn't exists or is not a directory.
@end defun

@defun glob pattern :key separator folder sorter
@defunx sys-glob pattern :key separator folder sorter
Provides a traditional Unix glob(3) functionality;
returns a list of pathnames that matches the given @var{pattern}.

This feature used to be a wrapper of system-provided @code{glob} function,
hence it was named @code{sys-glob}.  However, as of Gauche version 0.8.12,
it was reimplemented in Scheme on top of other system calls, to overcome
incompatibilities between platforms and for the opportunity to put
more functionalities.  So we renamed it @code{glob}.
The old name @code{sys-glob} is kept for compatibility, but new
programs should use @code{glob}.

The @var{pattern} argument may be a single @emph{glob pattern}, or
a list of glob patterns.  If a list is given, pathnames that matches
any one of the pattern are returned.  If you're a unix user,
you already know how it works.

@example
gosh> (glob "*.scm")
("ext.scm" "test.scm")
gosh> (glob "src/*.[ch]")
("src/ext.c" "src/ext.h")
gosh> (glob '("*.scm" "src/*.c"))
("ext.scm" "src/ext.c" "test.scm")
@end example

Unlike shell's glob, if there's no matching pathnames, @code{()} is returned.

By default, the result is sorted using built-in @code{sort} procedure
(@pxref{Sorting and merging}).  You can pass alternative procedure
to @var{sorter} argument; it should be a procedure that takes single
list, and returns a sorted list.  It can also be @code{#f}, in which
case the result isn't sorted at all.

In fact, globbing is a very useful tool to search hierarchical
data structure in general, not limited to the filesystems.
So the @code{glob} function is implemented separately from
the filesystem.  Using keyword arguments,
you can glob from any kind of tree data structure.
It is just that their default values are set to look at
the filesystems.

The @var{separator} argument should be a char-set, and used
to split the @var{pattern} into components.  Its default is
@code{#[/]}.  It is not used to the actual pathnames to match.

The @var{folder} is a procedure that walks through the data
structure.  It is called with five arguments:

@example
(folder @var{proc} @var{seed} @var{parent} @var{regexp} @var{non-leaf?})
@end example

@var{proc} is a procedure that takes two arguments.  The @var{folder}
should call @var{proc} with every node in the @var{parent} whose
component name matches @var{regexp}, passing around the seed value
just like @code{fold}.  It should return the final value returned
by @var{proc}.  For example, if @code{cons} is given to @var{proc}
and @code{()} is given to @var{seed}, the return value of the folder
is a list of nodes that matches the @var{regexp}.

The representation of a node is up to the implementation of
@var{folder}.  It can be a
pathname, or some sort of objects, or anything.  The @code{glob}
procedure does not care what it is; the @code{glob} procedure
merely passes the node to subsequent call to @code{folder} as
@var{parent} argument, or returns a list of nodes as the result.

The @var{parent} argument is basically a node, and
@var{folder} traverses its children to find the match.
The exception is the initial call of @var{folder}---
at the beginning @code{glob} knows nothing about each node.
When @code{glob} needs to match an absolute path, it
passes @code{#t}, and when @code{glob} needs to match a relative path,
it passes @code{#f}, as the initial @var{parent} value.

The @var{regexp} argument is used to filter the child nodes.
It should be matched against the component name of the child,
not including its directory names.  As a special case, it can
be a symbol @code{dir}; if that's the case, the folder should
return @var{node} itself, but it may indicate @var{node}
@emph{as a directory}; e.g. if @var{node} is represented as a pathname,
the folder returns a pathname with trailing directory separator.
As special cases,
if @var{node} is a boolean value and @var{regexp} is @code{dir},
the folder should return the node representing root node or
current node, respectively; e.g. if @var{node} is represented
as a pathname, the folder may return @code{"/"} and @code{"./"}
for those cases.

The @var{non-leaf} argument is a boolean flag.  If it is true,
the filter should omit the leaf nodes from the result (e.g. only
include the directories).

Now, here's the precise spec of glob pattern matching.

Each glob pattern is a string to match pathname-like strings.

A pathname-like string is a string consists of one or more
@emph{components}, separated by @emph{separator}s.
The default separator is @code{#[/]}; you can change it
with @var{separator} keyword argument.
A component cannot contain separators, and cannot
be a null string.  Consecutive separators are
regarded as a single separator.  A pathname-like
string optionally begins with, and/or ends with a separator character.

A glob pattern also consists of components and separator
characters.  In a component, following characters/syntax have special
meanings.

@table @code
@item *
When it appears at the beginning of a component, it matches
zero or more characters except a period (@code{.}).  And it
won't match if the component of the input string begins with
a period.

Otherwise, it matches zero or more sequence of any characters.

@item **
If a component is just @code{**}, it matches zero or more
number of components that match @code{*}.  For example, @code{src/**/*.h}
matches all of the following patterns.
@example
src/*.h
src/*/*.h
src/*/*/*.h
src/*/*/*/*.h
...
@end example

@item ?
When it appears at the beginning of a component, it matches
a character except a period (@code{.}).  Otherwise, it matches
any single character.

@item [@i{chars}]
Specifies a character set.  Matches any one of the set.
The syntax of @i{chars} is the same as Gauche's character set
syntax (@pxref{Character sets}).  For the compatibility of the
traditional glob, the @code{!} character can be used to complement
the character set, e.g. @code{[!abc]} is the same as @code{[^abc]}.
@end table
@end defun

@defun glob-fold pattern proc seed :key separator folder sorter
This is actually a low-level construct of the glob function.
Actually, @var{glob} is simply written like this:
@example
(define (glob patterns . opts)
  (apply glob-fold patterns cons '() opts))
@end example

The meaning of @var{pattern}, @var{separator}, @var{folder} and
@var{sorter}
is the same as explained above.

For each pathname that matches @var{pattern}, @code{glob-fold}
calls @var{proc} with the pathname and a seed value.  The initial
seed value is @var{seed}, and the value @var{proc} returns becomes
the next seed value.  The result of the last call to @var{proc}
becomes the result of @code{glob-fold}.  If there's no matching
pathnames, @var{proc} is never called and @var{seed} is returned.
@end defun

@defun make-glob-fs-fold :key root-path current-path
This is a utility function to generate a procedure suitable to
pass the @var{folder} keyword argument of @code{glob-fold} and @code{glob}.
Without arguments, this returns the same procedure which is used
in @code{glob-fold} and @code{glob} by default.

The keyword arguments @var{root-path} and @var{current-path} specify
the paths where @code{glob-fold} starts to search.

@example
gosh> (glob "/tmp/*.scm")
("/tmp/x.scm" "/tmp/y.scm")
gosh> (glob "/*.scm"
            :folder (make-glob-fs-fold :root-path "/tmp"))
("/tmp/x.scm" "/tmp/y.scm")
gosh> (glob "*.scm"
            :folder (make-glob-fs-fold :current-path "/tmp"))
("/tmp/x.scm" "/tmp/y.scm")
@end example
@end defun

@xref{File stats}, to check if a path is actually a directory.

@node Directory manipulation, Pathnames, Directories, Filesystems
@subsubsection Directory manipulation
@c NODE ディレクトリ操作

@defun sys-remove filename
[POSIX]
If @var{filename} is a file it is removed.
On some systems this may also work on an empty directory,
but portable scripts shouldn't depend on it.
@end defun

@defun sys-rename old new
[POSIX]
Renames a file @var{old} to @var{new}.  The new name
can be in different directory from the old name, but both paths
must be on the same device.
@end defun

@defun sys-tmpnam
[POSIX]
Creates a file name which is supposedly unique, and returns it.
This is in POSIX, but its use is discouraged because of potential
security risk.  Use @code{sys-mkstemp} below if possible.
@end defun

@defun sys-mkstemp template
Creates and opens a file that has unique name, and returns two values;
opened port and the created filename.  The file is created exclusively,
avoiding race conditions.   @var{template} is used as the prefix
of the file.  Unlike Unix's mkstemp, you don't need padding characters.
The file is opened for writing, and its permission is set to 600.
@end defun

@defun sys-mkdtemp template
Creates a directory that has unique name, and returns the name.
@var{template} is used as the prefix of the directory.  Unlike Unix's
mkdtemp, you don't need padding characters.  The directory's
permission is set to 700.
@end defun

@defun sys-link existing new
[POSIX]
Creates a hard link named @var{new} to the existing file @var{existing}.
@end defun

@defun sys-unlink pathname
[POSIX]
Removes @var{pathname}.  It can't be a directory.
Returns @code{#t} if it is successfully removed, or
@code{#f} if @var{pathname} doesn't exist.
An error is signaled otherwise.

There are similar procedures, @code{delete-file}/@code{remove-file}
in @code{file.util} module, while they raises an error when the
named pathname doesn't exist (@pxref{File operations}).

R7RS defines @code{delete-file}, which you may want to use in portable
programs.
@end defun

@defun sys-symlink existing new
Creates a symbolic link named @var{new} to the pathname @var{existing}.
On systems that doesn't support symbolic links,
this function is unbound.
@end defun

@defun sys-readlink path
If a file specified by @var{path} is a symbolic link, its content is
returned.  If @var{path} doesn't exist or is not a symbolic link, an
error is signaled.
On systems that don't support symbolic links,
this function is unbound.
@end defun

@defun sys-mkdir pathname mode
[POSIX]
Makes a directory @var{pathname} with mode @var{mode}.
(Note that @var{mode} is masked by the current umask;
see @code{sys-umask} below).
The parent directory of @var{pathname} must exist and be writable
by the process.  To create intermediate directories at once, use
@code{make-directory*} in @code{file.util} (@ref{Directory utilities}).
@end defun

@defun sys-rmdir pathname
[POSIX]
Removes a directory @var{pathname}.  The directory must be empty.
To remove a directory with its contents, use @code{remove-directory*}
in @code{file.util} (@ref{Directory utilities}).
@end defun

@defun sys-umask :optional mode
[POSIX]
Sets umask setting to @var{mode}.  Returns previous umask setting.
If @var{mode} is omitted or @code{#f}, just returns the current umask without
changing it.
See @code{man umask} for more details.
@end defun

@node Pathnames, File stats, Directory manipulation, Filesystems
@subsubsection Pathnames
@c NODE パス名

See also @ref{Pathname utilities}, for high-level APIs.

@defun sys-normalize-pathname pathname :key absolute expand canonicalize
Converts @var{pathname} according to the way specified by keyword arguments.
More than one keyword argument can be specified.
@table @code
@item absolute
  If this keyword argument is given and true, and @var{pathname} is not
  an absolute pathname, it is converted to an absolute pathname by
  appending the current working directory in front of @var{pathname}.
@item expand
  If this keyword argument is given and true, and @var{pathname} begins
  with `@code{~}', it is expanded as follows:
@itemize @bullet
@item
    If @var{pathname} is consisted entirely by ``@code{~}'', or begins
    with ``@code{~/}'', then the character ``@code{~}'' is replaced
    for the pathname of the current user's home directory.
@item
    Otherwise, characters following `@code{~}' until either `@code{/}' or
    the end of @var{pathname} are taken as a user name, and the user's
    home directory is replaced in place of it.  If there's no such
    user, an error is signaled.
@end itemize
@item canonicalize
  Tries to remove pathname components ``@code{.}'' and ``@code{..}''.
  The pathname interpretation is done purely in textural level, i.e.
  it doesn't access filesystem to see the conversion reflects the
  real files.  It may be a problem if there's a symbolic links to
  other directory in the path.
@end table
@end defun

@defun sys-basename pathname
@defunx sys-dirname pathname
@code{sys-basename} returns a basename, that is the last component of
@var{pathname}.  @code{sys-dirname} returns the components of @var{pathname}
but the last one.   If @var{pathname} has a trailing `@code{/}',
it is simply ignored.
@example
(sys-basename "foo/bar/bar.z") @result{} "bar.z"
(sys-basename "coo.scm") @result{} "coo.scm"
(sys-basename "x/y/") @result{} "y"
(sys-dirname "foo/bar/bar.z") @result{} "foo/bar"
(sys-dirname "coo.scm") @result{} "."
(sys-dirname "x/y/") @result{} "x"
@end example
These functions doesn't check if @var{pathname} really exists.

Some boundary cases:
@example
(sys-basename "") @result{} ""
(sys-dirname "") @result{} "."

(sys-basename "/") @result{} ""
(sys-dirname "/") @result{} "/"
@end example
Note: The above behavior is the same as Perl's @code{basename} and
@code{dirname}.   On some systems, the command @code{basename}
may return @code{"/"} for the argument @code{"/"}, and
@code{"."} for the argument @code{"."}.
@end defun

@defun sys-realpath pathname
@code{sys-realpath} returns an absolute pathname of @var{pathname}
that does not include ``@code{.}'', ``@code{..}'' or symbolic links.
If @var{pathname} does not exist, it includes a dangling symbolic
link, or the caller doesn't have enough permission to access to
the path, an error is signaled.

Note: the POSIX @code{realpath(3)} function is known to be unsafe, so
Gauche avoids using it and implements @code{sys-realpath} in its own.
@end defun

@defun sys-tmpdir
Returns the default directory name suitable to put temporary files.

On Unix-like systems, the environment variable @code{TMPDIR} and @code{TMP}
are first checked, then falls back to @code{/tmp}.

On Windows-native systems, it uses @code{GetTempPath} Windows API.
It checks environment variables @code{TMP}, @code{TEMP}, and
@code{USERPROFILE} in this order, and falls back to Windows system
directory.

On both platforms, the returned pathname may not exist, or
may not be writable by the calling process.

In general, user programs and libraries are recommended to use
@code{temporary-directory} (@pxref{Directory utilities}) instead;
@code{sys-tmpdir} should be used only
if you now the raw value the platform provides.
@end defun

@node File stats, Other file operations, Pathnames, Filesystems
@subsubsection File stats
@c NODE ファイルの状態

See also @ref{File attribute utilities}, for high-level APIs.

@defun file-exists? path
[R7RS file]
Returns true if @var{path} exists.
@end defun

@defun file-is-regular? path
@defunx file-is-directory? path
Returns true if @var{path} is a regular file, or is a directory,
respectively.   They return false if @var{path} doesn't
exist at all.
@end defun

@deftp {Builtin Class} <sys-stat>
@clindex sys-stat
An object that represents @code{struct stat}, attributes of an
entry in the filesystem.   It has the following read-only slots.

@defivar <sys-stat> type
A symbol represents the type of the file.
@multitable {aaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
@item @code{regular} @tab a regular file
@item @code{directory} @tab a directory
@item @code{character} @tab a character device
@item @code{block} @tab a block device
@item @code{fifo} @tab a fifo
@item @code{symlink} @tab a symbolic link
@item @code{socket} @tab a socket
@end multitable
If the file type is none of the above, @code{#f} is returned.

Note: Some operating systems don't have the @code{socket} file type
and returns @code{fifo} for socket files.   Portable programs should
check both possibilities to see if the given file is a socket.
@end defivar

@defivar <sys-stat> perm
An exact integer for permission bits of @code{struct stat}.
It is the same as lower 9-bits of "mode" slot; provided for the convenience.
@end defivar

@defivar <sys-stat> mode
@defivarx <sys-stat> ino
@defivarx <sys-stat> dev
@defivarx <sys-stat> rdev
@defivarx <sys-stat> nlink
@defivarx <sys-stat> uid
@defivarx <sys-stat> gid
@defivarx <sys-stat> size
An exact integer for those information of @code{struct stat}.
@end defivar

@defivar <sys-stat> atime
@defivarx <sys-stat> mtime
@defivarx <sys-stat> ctime
A number of seconds since Unix Epoch for those information of @code{struct stat}.
@end defivar

@defivar <sys-stat> atim
@defivarx <sys-stat> mtim
@defivarx <sys-stat> ctim
Timestamps represented in @code{<time>} object (@pxref{Time}).
If the system supports it, this allows up to nanosecond precision.
@end defivar

@end deftp

@defun sys-stat path
@defunx sys-fstat port-or-fd
[POSIX]
Returns a @code{<sys-stat>} object of @var{path}, or
the underlying file of @var{port-or-fd}, which
may be a port or a positive exact integer file descriptor, respectively.

If @var{path} is a symbolic link, a stat of the file the link points
to is returned from @code{sys-stat}.

If @var{port-or-fd} is not associated to a file, @code{sys-fstat} returns
@code{#f}.
@end defun

@defun sys-lstat path
Like @code{sys-stat}, but it returns a stat of a symbolic link
if @var{path} is a symbolic link.
@end defun

@example
gosh> (describe (sys-stat "gauche.h"))
#<<sys-stat> 0x815af70> is an instance of class <sys-stat>
slots:
  type      : regular
  perm      : 420
  mode      : 33188
  ino       : 845140
  dev       : 774
  rdev      : 0
  nlink     : 1
  uid       : 400
  gid       : 100
  size      : 79549
  atime     : 1020155914
  mtime     : 1020152005
  ctime     : 1020152005
@end example

@defun sys-stat->mode stat
@defunx sys-stat->ino stat
@defunx sys-stat->dev stat
@defunx sys-stat->rdev stat
@defunx sys-stat->nlink stat
@defunx sys-stat->size stat
@defunx sys-stat->uid stat
@defunx sys-stat->gid stat
@defunx sys-stat->atime stat
@defunx sys-stat->mtime stat
@defunx sys-stat->ctime stat
@defunx sys-stat->file-type stat
@strong{Deprecated}.
Use @code{slot-ref} to access information of @code{<sys-stat>} object.
@end defun

@defun sys-access pathname amode
[POSIX]
Returns a boolean value of indicating whether access of @var{pathname}
is allowed in @var{amode}.   This procedure signals an error
if used in a suid/sgid program (see the note below).
@var{amode} can be a combinations (logical or) of
following predefined flags.
@table @code
@item R_OK
@vindex R_OK
Checks whether @var{pathname} is readable by the current user.
@item W_OK
@vindex W_OK
Checks whether @var{pathname} is writable by the current user.
@item X_OK
@vindex X_OK
Checks whether @var{pathname} is executable (or searchable in case
@var{pathname} is a directory) by the current user.
@item F_OK
@vindex F_OK
Checks whether @var{pathname} exists or not, regardless of
the access permissions of @var{pathname}.  (But you need to have
access permissions of the directories containing @var{pathname}).
@end table

@emph{Note:} Access(2) is known to be a security hole if used
in suid/sgid program to check the real user's privilege of
accessing the file.
@end defun

@defun sys-chmod path mode
@defunx sys-fchmod port-or-fd mode
Change the mode of the file named @var{path} or an opened
file specified by @var{port-or-fd} to @var{mode}.
@var{mode} must be a small positive integer whose lower 9 bits
specifies POSIX style permission.
@end defun

@defun sys-chown path owner-id group-id
Change the owner and/or group of the file named @var{path}
to @var{owner-id} and @var{group-id} respectively.
@var{owner-id} and @var{group-id} must be an exact integer.
If either of them is -1, the corresponding ownership is not changed.
@end defun

@defun sys-utime path :optional atime mtime
Change the file's access time and modification time to @var{atime}
and @var{mtime}, respectively.   The arguments can be either @code{#f}
(indicating the current time), @code{#t} (do not change),
a real numebr (number of seconds from Epoch),
or @code{<time>} object (@xref{Time}).

See also @code{touch-file} (@pxref{File operations}).
@end defun

@node Other file operations,  , File stats, Filesystems
@subsubsection Other file operations
@c NODE 他のファイル操作

@defun sys-chdir dir
[POSIX]
An interface to @code{chdir(2)}.
See also @code{current-directory} (@pxref{Directory utilities}).
@end defun

@defun sys-pipe :key (buffering :line)
[POSIX] Creates a pipe, and returns two ports.
The first returned port is an input port and the second is an output port.
The data put to the output port can be read from the input port.

@var{Buffering} can be @code{:full}, @code{:line} or @code{:none},
and specifies the buffering mode of the ports opened on the pipe.
@xref{File ports}, for details of the buffering mode.
The default mode is sufficient for typical cases.

@example
(receive (in out) (sys-pipe)
  (display "abc\n" out)
  (flush out)
  (read-line in)) @result{} "abc"
@end example

Note: the returned value is changed from version 0.3.15, in which
@code{sys-pipe} returned a list of two ports.
@end defun

@defun sys-mkfifo path mode
[POSIX] creates a fifo (named pipe) with a name @var{path} and mode
@var{mode}.  @var{Mode} must be a positive exact integer to represent
the file mode.
@end defun

@defun sys-isatty port-or-fd
[POSIX] @var{port-or-fd} may be a port or an integer file descriptor.
Returns @code{#t} if the port is connected to the console, @code{#f}
otherwise.
@end defun

@defun sys-ttyname port-or-fd
[POSIX] @var{port-or-fd} may be a port or an integer file descriptor.
Returns the name of the terminal connected to the port,
or @code{#f} if the port is not connected to a terminal.
@end defun

@defun sys-truncate path length
@defunx sys-ftruncate port-or-fd length
[POSIX]
Truncates a regular file named by @var{path} or referenced by @var{port-or-fd}
to a size of @var{length} bytes.
If the file is larger than @var{length} bytes, the extra data is discarded.
If the file is smaller than that, zero is padded.
@end defun

@node Unix groups and users, Locale, Filesystems, System interface
@subsection Unix groups and users
@c NODE Unixのグループとユーザ

@subsubheading Unix groups

@deftp {Builtin Class} <sys-group>
@clindex sys-group
Unix group information.  Has following slots.

@defivar <sys-group> name
Group name.
@end defivar

@defivar <sys-group> gid
Group id.
@end defivar

@defivar <sys-group> passwd
Group password.
@end defivar

@defivar <sys-group> mem
List of user names who are in this group.
@end defivar

@end deftp

@defun sys-getgrgid gid
@defunx sys-getgrnam name
[POSIX]
Returns @code{<sys-group>} object from an integer group id @var{gid}
or a group name @var{name}, respectively.
If the specified group doesn't exist, @code{#f} is returned.
@end defun

@defun sys-gid->group-name gid
@defunx sys-group-name->gid name
Convenience function to convert between group id and group name.
@end defun

@subsubheading Unix users

@deftp {Builtin Class} <sys-passwd>
@clindex sys-passwd
Unix user information.  Has following slots.

@defivar <sys-passwd> name
User name.
@end defivar

@defivar <sys-passwd> uid
User ID.
@end defivar

@defivar <sys-passwd> gid
User's primary group id.
@end defivar

@defivar <sys-passwd> passwd
User's (encrypted) password.  If the system uses the shadow password file,
you just get obscure string like "x".
@end defivar

@defivar <sys-passwd> gecos
Gecos field.
@end defivar

@defivar <sys-passwd> dir
User's home directory.
@end defivar

@defivar <sys-passwd> shell
User's login shell.
@end defivar

@defivar <sys-passwd> class
User's class (only available on some systems).
@end defivar

@end deftp

@defun sys-getpwuid uid
@defunx sys-getpwnam name
[POSIX]
Returns @code{<sys-passwd>} object from an integer user id @var{uid}
or a user name @var{name}, respectively.
If the specified user doesn't exist, @code{#f} is returned.
@end defun

@defun sys-uid->user-name uid
@defunx sys-user-name->uid name
Convenience functions to convert between user id and user name.
@end defun


@subsubheading Password encryption

@defun sys-crypt key salt
This is the interface to @code{crypt(3)}.   @var{Key} and @var{salt}
must be a string, and an encrypted string is returned.
On systems where @code{crypt(3)} is not available, call to this
function signals an error.

This routine is only for the code that needs to check password
against the system's password database.
If you are building user database on your own, you @emph{must} use
@code{crypt.bcrypt} module (@pxref{Password hashing}) instead of
this routine.
@end defun

@node Locale, Signal, Unix groups and users, System interface
@subsection Locale
@c NODE ロケール

@defun sys-setlocale category locale
[POSIX]
Sets the locale of the category @var{category} to the locale @var{locale}.
@var{category} must be an exact integer; the following pre-defined
variables are available.  @var{locale} must be a string locale name.
Returns the locale name on success, or @code{#f} if the system
couldn't change the locale.
@end defun

@defvar  LC_ALL
@defvarx LC_COLLATE
@defvarx LC_CTYPE
@defvarx LC_MONETARY
@defvarx LC_NUMERIC
@defvarx LC_TIME
Predefined variables for possible @var{category} value of
@code{sys-setlocale}.
@end defvar

@defun sys-localeconv
[POSIX]
Returns an assoc list of various information for formatting numbers
in the current locale.
@end defun

An example session.  It may differ on your system settings.
@example
(sys-localeconv)
 @result{}
   ((decimal_point . ".") (thousands_sep . "")
    (grouping . "") (int_curr_symbol . "")
    (currency_symbol . "") (mon_decimal_point . "")
    (mon_thousands_sep . "") (mon_grouping . "")
    (positive_sign . "") (negative_sign . "")
    (int_frac_digits . 127) (frac_digits . 127)
    (p_cs_precedes . #t) (p_sep_by_space . #t)
    (n_cs_precedes . #t) (n_sep_by_space . #t)
    (p_sign_posn . 127) (n_sign_posn . 127))

(sys-setlocale LC_ALL "fr_FR")
 @result{} "fr_FR"

(sys-localeconv)
 @result{}
  ((decimal_point . ",") (thousands_sep . "")
   (grouping . "") (int_curr_symbol . "FRF ")
   (currency_symbol . "F") (mon_decimal_point . ",")
   (mon_thousands_sep . " ") (mon_grouping . "\x03\x03")
   (positive_sign . "") (negative_sign . "-")
   (int_frac_digits . 2) (frac_digits . 2)
   (p_cs_precedes . #f) (p_sep_by_space . #t)
   (n_cs_precedes . #f) (n_sep_by_space . #t)
   (p_sign_posn . 1) (n_sign_posn . 1))
@end example

@node Signal, System inquiry, Locale, System interface
@subsection Signal
@c NODE  シグナル

Gauche can send out operating system's signals to the other processes
(including itself) and can handle the incoming signals.

In multithread environment, all threads share the signal
handlers, and each thread has its own signal mask.
See @ref{Signals and threads}, for details.

When a system call is interrupted by a signal,
and a programmer defines a handler for the signal that doesn't transfer
control to other context, the system call is restarted after
the handler returns by default.

Here are some calls that are not simply restarted by signal interruption.

@table @code
@item close
This may be called through @code{sys-close}, @code{close-port}, or even
implicitly when the underlying file is closed.   When a signal interrupts
this call, the passed fd is no longer in use.  Simply restarting it can
be a race if another thread just grabs the fd.

@item dup2
This is called via @code{port-fd-dup!}.  When @code{dup2} returns
@code{EINTR}, the @var{newfd} is no longer in use and some other thread
may grab it before restarting it.

@item sleep
@itemx nanosleep
These calls tells the remaining time when they are interrupted.
We restart them with that remaining time, not the original argument,
so that the total sleep time would be close to what was given originally.
@end table

On Windows native platforms, signals don't work except
some limited support of @code{sys-kill}.

@menu
* Signals and signal sets::
* Sending signals::
* Handling signals::
* Masking and waiting signals::
* Signals and threads::
@end menu

@node Signals and signal sets, Sending signals, Signal, Signal
@subsubsection Signals and signal sets
@c NODE シグナルとシグナルセット

Each signal is referred by its signal number (a small integer)
defined on the underlying operating system.
Variables are pre-defined to the system's signal number.
System's signal numbers may be architecture dependent, so you should
use those variables rather than using literal integers.

@defvar  SIGABRT
@defvarx SIGALRM
@defvarx SIGCHLD
@defvarx SIGCONT
@defvarx SIGFPE
@defvarx SIGHUP
@defvarx SIGILL
@defvarx SIGINT
@defvarx SIGKILL
@defvarx SIGPIPE
@defvarx SIGQUIT
@defvarx SIGSEGV
@defvarx SIGSTOP
@defvarx SIGTERM
@defvarx SIGTSTP
@defvarx SIGTTIN
@defvarx SIGTTOU
@defvarx SIGUSR1
@defvarx SIGUSR2
These variables are bound to the signal numbers of POSIX signals.
@end defvar

@defvar  SIGTRAP
@defvarx SIGIOT
@defvarx SIGBUS
@defvarx SIGSTKFLT
@defvarx SIGURG
@defvarx SIGXCPU
@defvarx SIGXFSZ
@defvarx SIGVTALRM
@defvarx SIGPROF
@defvarx SIGWINCH
@defvarx SIGPOLL
@defvarx SIGIO
@defvarx SIGPWR
These variables are bound to the signal numbers of system-dependent
signals.  Not all of them may be defined on some systems.
@end defvar

Besides each signal numbers, you can refer to a set of signals
using a @code{<sys-sigset>} object.
It can be used to manipulate the signal mask, and to install a signal
handler to a set of signals at once.

@deftp {Class} <sys-sigset>
@clindex sys-sigset
A set of signals.   An empty sigset can be created by
@example
(make <sys-sigset>) @result{} #<sys-sigset []>
@end example
@end deftp

@defun sys-sigset signal @dots{}
Creates and returns an instance of @code{<sys-sigset>}
with members @var{signal} @dots{}.  Each @var{signal}
may be either a signal number, another @code{<sys-sigset>}
object, or @code{#t} for all available signals.

@example
(sys-sigset SIGHUP SIGINT) @result{} #<sys-sigset [HUP|INT]>
@end example
@end defun

@defun sys-sigset-add! sigset signal @dots{}
@defunx sys-sigset-delete! sigset signal @dots{}
@var{Sigset} must be a @code{<sys-sigset>} object.
Those procedures adds and removes the specified signals from
@var{sigset} respectively, and returns the result.  @var{sigset} itself
is also modified.

@var{signal} may be either a signal number, another @code{<sys-sigset>}
object, or @code{#t} for all available signals.
@end defun

@defun sys-sigset-fill! sigset
@defunx sys-sigset-empty! sigset
Fills @var{sigset} by all available signals, or empties @var{sigset}.
@end defun

@defun sys-signal-name signal
Returns the human-readable name of the given signal number.
(Note that signal numbers are system-dependent.)

@example
(sys-signal-name 2) @result{} "SIGINT"
@end example
@end defun

@node Sending signals, Handling signals, Signals and signal sets, Signal
@subsubsection Sending signals
@c NODE シグナルの送出

To send a signal, you can use @code{sys-kill} which works like
@code{kill(2)}.

@defun sys-kill pid sig
[POSIX]
Sends a signal @var{sig} to the specified process(es).  @var{Sig}
must be a positive exact integer.  @var{pid} is an exact integer and
specifies the target process(es):
@itemize @bullet
@item
If @var{pid} is positive, it is the target process id.
@item
If @var{pid} is zero, the signal is sent to every process in the process
group of the current process.
@item
If @var{pid} is less than -1, the signal is sent to every process in
the process group @var{-pid}.
@end itemize

On Windows native platforms, @code{sys-kill} may take positive integer
or a process handle (@code{<win:handle>} instance) as @var{pid}.
Only @code{SIGKILL}, @code{SIGINT} and @code{SIGABRT} are allowed
as @var{sig}; Gauche uses @code{TerminateProcess} to terminate
the target process for @code{SIGKILL},
and sends the target process
@code{CTRL_C_EVENT} and @code{CTRL_BREAK_EVENT} for
@code{SIGINT} and @code{SIGABRT}, respectively.
@end defun

There's no Scheme equivalence for @code{raise()}, but you can use
@code{(sys-kill (sys-getpid) @var{sig})}.

@node Handling signals, Masking and waiting signals, Sending signals, Signal
@subsubsection Handling signals
@c NODE シグナルの処理

You can register signal handling procedures in Scheme.
(In multithread environment, signal handlers are shared by all
threads; see @ref{Signals and threads} for details).

When a signal is delivered to the Scheme process, the VM just records it
and processes it later at a 'safe point' where the state of VM is consistent.
We call the signal is @emph{pending} when it is registered by the VM
but not processed yet.

(Note that this makes handling of some signals such as @code{SIGILL}
useless, for the process can't continue sensible execution after
recording the signal).

If the same signal is delivered more than once before VM processes
the first one, the second one and later have no effect.  (This is consistent
to the traditional Unix signal model.)  In other words,
for each VM loop a signal handler can be invoked at most once per
each signal.

When too many signals of the same kind are pending,
Gauche assumes something has
gone wrong (e.g. infinite loop inside C-routine) and aborts the
process.  The default of this limit is set rather low (3), to allow
unresponsive interactive script to be terminated by typing Ctrl-C
three times.  Note that the counter is individual for each signal;
Gauche won't abort if one @code{SIGHUP} and two @code{SIGINT}s are
pending, for example.  You can change this limit by
@code{set-signal-pending-limit} described below.

When you're using the @code{gosh} interpreter, the default
behavior for each signal is as in the following table.

@table @code
@item SIGABRT, SIGILL, SIGKILL, SIGSTOP, SIGSEGV, SIGBUS
Cannot be handled in Scheme.  @code{Gosh} follows the system's
default behavior.
@item SIGCHLD, SIGTSTP, SIGTTIN, SIGTTOU, SIGWINCH
No signal handles are installed for these signals by @code{gosh},
so the process follows the system's default behavior.
A Scheme programs can install its own signal handler if necessary.
@item SIGCONT
If @code{gosh} is running with input editing mode, a signal handler
is installed to restore terminal status.  Otherwise, no signal
handler is installed by default, and a Scheme program can
install its own signal handler if necessary.
@item SIGHUP, SIGQUIT, SIGTERM
@code{Gosh} installs a signal handler for these signals
       that exits from the application with code 0.
@item SIGPIPE
@code{Gosh} installs a signal handler that does nothing---that is,
this signal is effectively ignored by default.

It is a design choice.  Since Gauche delays actual handling
of signals, @code{SIGPIPE} would be handled after the system call
that tries to write to a broken pipe returns with @code{EPIPE}.
That makes the signal a lot less useful, for we can handle the
situation with error handlers for @code{<system-error>} with @code{EPIPE}.

The default Unix behavior of @code{SIGPIPE} is to terminate
the process.  It is useful for the traditional command-line tools
that are often piped together---if one of downstream commands fails,
the upstream process receives @code{SIGPIPE} and the entire
command chain is shut down without a fuss.  The signal is, however, rather an
annoyance for other types of output such as sockets.

Gauche does support this ``exit when pipe gets stuck'' convention
by ports.   A port can be configured as @emph{sigpipe sensitive};
if writing to that port caused @code{EPIPE}, it terminates the
process.  By default, standard output and standard error output
are configured in that way.
@c TODO: In the port section, explain how to configure so.
@item SIGPWR, SIGXCPU, SIGUSR1, SIGUSR2
On Linux platforms with thread support, these signals are used
       by the system and not available for Scheme.  On other systems,
       these signals behaves the same as described below.
@item other signals
@code{Gosh} installs the default signal handler, which raises
@code{<unhandled-signal-error>} condition (see @ref{Conditions}).
Scheme programs can override it by its own signal handler.
@end table

If you're using Gauche embedded in some other application,
it may redefine the default behavior.

Use the following procedures to get/set signal handlers from Scheme.

@defun set-signal-handler! signals handler :optional sigmask
@var{Signals} may be a single signal number or a @code{<sys-sigset>}
object, and @var{handler} should be either @code{#t}, @code{#f},
@code{#<undef>}, or a procedure that takes one argument.
If @var{handler} is a procedure, it will be called when the process
receives one of specified signal(s), with the received signal
number as an argument.

By default, the signals in @var{signals} are blocked
(in addition to the signal mask in effect at that time) during
@var{handler} is executed, so that @var{handler} won't be
reentered by the same signal(s).  You can provide
a @code{<sys-sigset>} object to the @var{sigmask} arg
to specify the signals to be blocked explicitly.
Note that the signal mask
is per-thread; if more than one thread unblocks a signal, the handler
may still be invoked during execution of the handler (in other thread)
even if you specify @var{sigmask}.  You have to set the threads'
signal mask properly to avoid such situation.

It is safe to do anything in @var{handler}, including throwing
an error or invoking continuation captured elsewhere.  (However,
continuations captured inside @var{handler} will be invalid
once you return from @var{handler}).

If @var{handler} is @code{#t}, the operating system's default
behavior is set to the specified signal(s).  If @var{handler}
is @code{#f}, the specified signals(s) will be ignored.

If @var{handler} is @code{#<undef>} (@pxref{Undefined values}),
it indicates Gauche to leave the current OS's signal handler as it is.
This value isn't as much use in @code{set-signal-handler!} as
in @code{get-signal-handler}: If @code{#<undef>} is passed
to @code{set-signal-handler!}, it immediately returns without
modifying anything.   However, if you get @code{#<undef>}
from @code{get-signal-handler}, you can know that the
signal handler behavior hasn't been modified by Gauche.
(Note that once Gauche ever installs a signal handler,
there is no way to revert back to make @code{get-signal-handler}
return @code{#<undef>}).

Note that signal handler setting is shared among threads in
multithread environment.  The handler is called from the thread
which is received the signal.  See @ref{Signals and threads}
for details.
@end defun

@defun get-signal-handler signum
@defunx get-signal-handler-mask signum
Returns the handler setting, or signal mask setting, of a signal @var{signum},
respectively.  See @code{set-signal-handler!} for the meaning of
the return value of @code{get-signal-handler}.
@end defun

@defun get-signal-handlers
Returns an associative list of all signal handler settings.
Car of each element of returned list is a @code{<sys-sigset>} object,
and cdr of it is the handler (a procedure or a boolean value)
of the signals in the set.
@end defun

@defun get-signal-pending-limit
@defunx set-signal-pending-limit limit
Gets/sets the maximum number of pending signals per each signal type.
If the number of pending signals exceeds this limit, Gauche aborts
the process.  See the explanation at the beginning of this section
for the details.  @var{Limit} must be a nonnegative exact integer.
In the current implementation the maximum number of @var{limit} is 255.
Setting limit to zero makes the number of pending signals unlimited.
@end defun


@defmac with-signal-handlers (handler-clause @dots{}) thunk
A convenience macro to install signal handlers temporarily
during execution of @var{thunk}.
(Note: though this is convenient, this has certain dangerous
properties described below.  Use with caution.)

Each @var{Handler-clause} may be one of the following forms.
@table @code
@item (@var{signals} @var{expr} @dots{})
@var{Signals} must be an expression that will yield either a signal,
a list of signals, or a @code{<sys-sigset>} object.
Installs a signal handler for @var{signals} that evaluates
@var{expr} @dots{} when one of the signals in @var{signals} is delivered.

@item (@var{signals} => @var{handler})
This form sets the handler of @var{signals} to @var{handler},
where @var{handler} should be either @code{#t}, @code{#f}
or a procedure that takes one argument.

If @var{handler} is a procedure, it will be called when the process
receives one of specified signal(s), with the received signal
number as an argument.
If @var{handler} is @code{#t}, the operating system's default
behavior is set to the specified signal(s).  If @var{handler}
is @code{#f}, the specified signals(s) will be ignored.
@end table

When the control exits from @var{thunk}, the signal handler setting
before @code{with-signal-handlers} are recovered.

@emph{CAVEAT:} If you're setting more than one signal handlers,
they are installed in serial.  If a signal is delivered before
all the handlers are installed, the signal handler state may be
left inconsistent.  Also note that the handler setting is a global state;
you can't set "thread local" handler by @code{with-signal-handlers},
although the form may be misleading.
@end defmac

@node Masking and waiting signals, Signals and threads, Handling signals, Signal
@subsubsection Masking and waiting signals
@c NODE シグナルのマスクと待機

A Scheme program can set a signal mask, which is a set of signals
to be blocked from delivery.   If a signal is delivered
which is completely blocked in the process, the signal becomes
"pending".  The pending signal may be delivered once the signal
mask is changed not to block the specified signal.
(However, it depends on the operating system whether the pending
signals are queued or not.)

In multithread environment, each thread has its own signal mask.

@defun sys-sigmask how mask
Modifies the current thread's signal mask, and returns the previous
signal mask.   @var{Mask} should be a @code{<sys-sigset>} object
to specify the new mask, or @code{#f} if you just want to query
the current mask without modifying one.

If you give @code{<sys-sigset>} object to @var{mask},
@var{how} argument should be one of the following
integer constants:
@table @code
@item SIG_SETMASK
Sets @var{mask} as the thread's signal mask.
@item SIG_BLOCK
Adds signals in @var{mask} to the thread's signal mask.
@item SIG_UNBLOCK
Removes signals in @var{mask} from the thread's signal mask.
@end table
@end defun

@defun sys-sigsuspend mask
Atomically sets thread's signal mask to @var{mask} and
suspends the calling thread.  When a signal that is not blocked
and has a signal handler installed is delivered, the associated
handler is called, then @code{sys-sigsuspend} returns.
@end defun

@defun sys-sigwait mask
[POSIX]
@var{Mask} must be a @code{<sys-sigset>} object.
If any of signals in @var{mask} is/are pending in the OS,
atomically clears one of them and returns the signal number
of the cleared one.   If there's no signal in @var{mask}
pending, @code{sys-sigwait} blocks until any of the signals
in @var{mask} arrives.

You have to block all signals in @var{mask} in all threads
before calling @code{sys-sigwait}.  If there's a thread
that doesn't block the signals, the behavior of
@code{sys-sigwait} is undefined.

Note: @code{Sys-sigwait} uses system's @code{sigwait} function,
whose behavior is not defined if there's a signal
handler on the signals it waits.  To avoid complication,
@code{sys-sigwait} resets the handlers set to the signals
included in @var{mask} before calling @code{sigwait} to @code{SIG_DFL},
and restores them after @code{sigwait} returns.  If another thread
changes signal handlers while @code{sys-sigwait} is waiting,
the behavior is undefined; you shouldn't do that.
@end defun

@node Signals and threads,  , Masking and waiting signals, Signal
@subsubsection Signals and threads
@c NODE シグナルとスレッド

The semantics of signals looks a bit complicated in the multithread
environment.   Nevertheless, it is pretty comprehensible once
you remember a small number of rules.  Besides,
Gauche sets up the default behavior easy to use,
while allowing programmers to do tricky stuff.

If you don't want to be bothered by the details, just remember
one thing, with one sidenote.
@strong{By default}, signals are handled by the
primordial (main) thread.  However, if the main thread
is suspended on mutex or condition variable,
the signal may not be handled at all, so be careful.

Now, if you are curious about the details, here are the rules:
@itemize @bullet
@item
The signal handler setting is shared by all threads.
@item
The signal mask is thread-specific.
@item
If a process receives an asynchronous signal (think it as a signal
delivered from other processes), one thread is chosen, out of
threads which don't block that signal.
@item
The signal handler is run on the chosen thread.
However, if the chosen thread is waiting for acquiring a mutex lock
or a condition variable, the handling of signal will be delayed
until the thread is restarted.   Signal delivery itself doesn't
restart the thread.
@end itemize

Now, these rules have several implications.

If there are more than one thread that don't block a particular
signal, you can't know which thread receives the signal.
Such a situation is much less useful in Gauche than C programs
because of the fact that the signal handling can be delayed indefinitely
if the receiver thread is waiting on mutex or condition variable.
So, it is recommended to make sure, for each signal, there is only one
thread that can receive it.

In Gauche, all threads created by @code{make-thread}
(@pxref{Thread procedures}) blocks all the signals by default
(except the reserved ones).   This lets all the signals
to be directed to the primordial (main) thread.

Another strategy is to create a thread dedicated for handling
signals.  To do so, you have to block the signals in the
primordial thread, then create the signal-handling thread,
and within that thread you unblock all the signals.
Such a thread can just loop on @code{sys-pause}.

@example
(thread-start!
  (make-thread
    (lambda ()
      (sys-sigmask SIG_SETMASK (make <sys-sigset>)) ;;empty mask
      (let loop () (sys-pause) (loop)))))
@end example

Complicated application may want to control per-thread signal
handling precisely.   You can do so, just make sure that
at any moment only the designated thread unblocks the desired
signal.

@node System inquiry, Time, Signal, System interface
@subsection System inquiry
@c NODE システムへの問い合わせ

@defun sys-uname
[POSIX] Returns a list of five elements,
@code{(@var{sysname} @var{nodename} @var{release} @var{version} @var{machine})}.
@end defun

@defun sys-gethostname
Returns the host name.  If the system doesn't have gethostname(),
the second element of the list returned by @code{sys-uname} is used.
@end defun

@defun sys-getdomainname
Returns the domain name.  If the system doesn't have getdomainname(),
@code{"localdomain"} is returned.
@end defun

@defun sys-getcwd
[POSIX] Returns the current working directory by a string.
If the current working directory couldn't be obtained from the system,
an error is signaled.   See also @code{sys-chdir}
 (@pxref{Other file operations}), @code{current-directory}
(@pxref{Directory utilities}).
@end defun

@defun sys-getgid
@defunx sys-getegid
[POSIX] Returns integer value of real and effective group id of the
current process, respectively.
Use @code{sys-gid->group-name} or @code{sys-getgrgid} to obtain
the group's name and other information associated to the returned
group id (@pxref{Unix groups and users}).
@end defun

@defun sys-setgid gid
[POSIX] Sets the effective group id of the current process.
@end defun

@defun sys-getuid
@defunx sys-geteuid
[POSIX]
Returns integer value of real and effective user id of the
current process, respectively.
Use @code{sys-uid->user-name} or @code{sys-getpwuid} to obtain
the user's name and other information associated to the returned
user id (@pxref{Unix groups and users}).
@end defun

@defun sys-setuid uid
[POSIX]
Sets the effective user id of the current process.
@end defun

@defun sys-setugid?
Returns true iff the process is running with suid/sgid-ed (that is,
the program's suid and/or sgid bit is set.)

Note: If the platform has @code{issetugid()} call, we use it.
Otherwise, we remember the if real (user|group) id and
effective (user|group) id differ or not at the initialization time.
(In the latter case, we can't detect the case that the process 
changes [e]uid/[e]gid before initializing Gauche; keep it in mind if
libgauche is used as an embedded Scheme engine).
@end defun

@defun sys-getgroups
[POSIX] Returns a list of integer ids of supplementary groups.
@end defun

@defun sys-setgroups gids
Sets the current process's groups to the given
list of integer group ids.
The caller must have the appropriate privilege.

This procedure is only available when the feature id
@code{gauche.sys.setgroups} exists.  Use @code{cond-expand} for
the portable program:

@example
(cond-expand
  [gauche.sys.setgroups (sys-setgroups '(0 1))]
  [else])
@end example
@end defun

@defun sys-getlogin
[POSIX] Returns a string of the name of the user logged in on the
controlling terminal of the current process.
If the system can't determine the information, @code{#f} is returned.
@end defun

@defun sys-getpgrp
[POSIX] Returns a process group id of the current process.
@end defun

@c @defun sys-setpgrp
@c Sets the process group id of the current process to the current
@c process id.   Equivalent to @code{sys-setpgid(0, 0)}.
@c @end defun

@defun sys-getpgid pid
Returns a process group id of the process specified by @var{pid}.
If @var{pid} is zero, the current process is used.

Note that @code{getpgid()} call is not in POSIX.  If the system
doesn't have @code{getpgid()}, @code{sys-getpgid} still works if
@var{pid} is zero (it just calls @code{sys-getpgrp}), but signals
an error if @var{pid} is not zero.
@end defun

@defun sys-setpgid pid pgid
[POSIX] Sets the process group id of the process @var{pid} to @var{pgid}.
If @var{pid} is zero, the process ID of the
current process is used.  If @var{pgid} is zero, the process ID
of the process specified by @code{pid} is used.  (Hence
@code{sys-setpgid(0, 0)} sets the process group id of the
current process to the current process id).
@end defun

@defun sys-setsid
[POSIX] Creates a new session if the calling process is
not a process group leader.
@end defun

@defun sys-getpid
@defunx sys-getppid
[POSIX] Returns the current process id and the parent process id,
respectively.
@end defun

@defun sys-times
[POSIX]
@end defun

@defun sys-ctermid
[POSIX]  Returns the name of the controlling terminal of the process.
This may be just a @code{"/dev/tty"}.   See also @code{sys-ttyname}.
@end defun

@defun sys-getrlimit resource
@defunx sys-setrlimit resource current :optional maximum
[POSIX] 
Get and set resource limits respectively.
@var{Resource} is an integer constant to specify the resource
of concern.  The following constants are defined.
(The constants marked as bsd and/or linux indicates that they
are not defined in POSIX but defined in BSD and/or Linux.
Other systems may or may not have them.  Consult @code{getrlimit}
manpage of your system for the details.)

@example
RLIMIT_AS                      RLIMIT_CORE
RLIMIT_CPU                     RLIMIT_DATA
RLIMIT_FSIZE                   RLIMIT_LOCKS
RLIMIT_MEMLOCK (bsd/linux)     RLIMIT_MSGQUEUE (linux)
RLIMIT_NICE (linux)            RLIMIT_NOFILE
RLIMIT_NPROC (bsd/linux)       RLIMIT_RSS (bsd/linux)
RLIMIT_RTPRIO (linux)          RLIMIT_SIGPENDING (linux)
RLIMIT_SBSIZE                  RLIMIT_STACK
RLIMIT_OFILE
@end example
@end defun

@defun sys-nice inc
[POSIX]
Adds @var{inc}, which must be an exact integer, to the current process's
nice value.  Only the root user can specify negative @var{inc} value.
Returns the new nice value.
@end defun

@defun sys-strerror errno
@var{Errno} must be an exact nonnegative integer representing
a system error number.  This function returns a string describing
the error.

To represent @var{errno}, the following constants are defined.
Each constant is bound to an exact integer representing the system's
error number.  Note that the actual value may differ among systems,
and some of these constants may not be defined on some systems.

@example
E2BIG             EHOSTDOWN         ENETDOWN          ENXIO
EACCES            EHOSTUNREACH      ENETRESET         EOPNOTSUPP
EADDRINUSE        EIDRM             ENETUNREACH       EOVERFLOW
EADDRNOTAVAIL     EILSEQ            ENFILE            EPERM
EADV              EINPROGRESS       ENOANO            EPFNOSUPPORT
EAFNOSUPPORT      EINTR             ENOBUFS           EPIPE
EAGAIN            EINVAL            ENOCSI            EPROTO
EALREADY          EIO               ENODATA           EPROTONOSUPPORT
EBADE             EISCONN           ENODEV            EPROTOTYPE
EBADF             EISDIR            ENOENT            ERANGE
EBADFD            EISNAM            ENOEXEC           EREMCHG
EBADMSG           EKEYEXPIRED       ENOKEY            EREMOTE
EBADR             EKEYREJECTED      ENOLCK            EREMOTEIO
EBADRQC           EKEYREVOKED       ENOLINK           ERESTART
EBADSLT           EL2HLT            ENOMEDIUM         EROFS
EBFONT            EL2NSYNC          ENOMEM            ESHUTDOWN
EBUSY             EL3HLT            ENOMSG            ESOCKTNOSUPPORT
ECANCELED         EL3RST            ENONET            ESPIPE
ECHILD            ELIBACC           ENOPKG            ESRCH
ECHRNG            ELIBBAD           ENOPROTOOPT       ESRMNT
ECOMM             ELIBEXEC          ENOSPC            ESTALE
ECONNABORTED      ELIBMAX           ENOSR             ESTRPIPE
ECONNREFUSED      ELIBSCN           ENOSTR            ETIME
ECONNRESET        ELNRNG            ENOSYS            ETIMEDOUT
EDEADLK           ELOOP             ENOTBLK           ETOOMANYREFS
EDEADLOCK         EMEDIUMTYPE       ENOTCONN          ETXTBSY
EDESTADDRREQ      EMFILE            ENOTDIR           EUCLEAN
EDOM              EMLINK            ENOTEMPTY         EUNATCH
EDOTDOT           EMSGSIZE          ENOTNAM           EUSERS
EDQUOT            EMULTIHOP         ENOTSOCK          EWOULDBLOCK
EEXIST            ENAMETOOLONG      ENOTTY            EXDEV
EFAULT            ENAVAIL           ENOTUNIQ          EXFULL
EFBIG
@end example
@end defun

@defun sys-errno->symbol k
@defunx sys-symbol->errno symbol
These procedures convert between integer error number and the symbol
of its unix name (e.g. @code{EINTR}).

If the given error number or name isn't available on the running
platform, those procedures return @code{#f}.  See @code{sys-strerror} 
above for potentially available error names.

Valid error names and their actual values differ among platforms.
These procedures make it easy to write portable meta-code that deal
with system errors.

@c TODO: Note about Windows platforms.
@end defun

@node Time, Process management, System inquiry, System interface
@subsection Time
@c NODE 時間

Gauche has two representations of time, one is compatible to POSIX API,
and the other is compatible to SRFI-18, SRFI-19 and SRFI-21.
Most procedures accept both representations; if not, the representation
the procedure accepts is indicated as either 'POSIX time' or 'SRFI time'.

POSIX time is represented by a real number which is a number of seconds
since Unix Epoch (Jan 1, 1970, 0:00:00GMT).
Procedure @code{sys-time}, which corresponds to POSIX @code{time(2)},
returns this time representation.

SRFI-compatible time is represented by an object of @code{<time>} class,
which keeps seconds and nanoseconds, as well as the type of the time
(UTC, TAI, duration, process time, etc).
@code{Current-time} returns this representation.

@subsubheading POSIX time

@defun sys-time
[POSIX] Returns the current time in POSIX time
(the time since Epoch (00:00:00 UTC, January 1, 1970),
measured in seconds).  It may be a non-integral number, depending on
the architecture.

Note that POSIX's definition of ``seconds since the Epoch'' doesn't
take leap seconds into account.
@end defun

@defun sys-gettimeofday
Returns two values.  The first value is a number of seconds,
and the second value is a fraction in a number of microseconds,
since 1970/1/1 0:00:00 UTC.   If the system doesn't have
@code{gettimeofday} call, this function calls @code{time()};
in that case, microseconds portion is always zero.
@end defun

@deftp {Builtin Class} <sys-tm>
@clindex sys-tm
Represents @code{struct tm}, a calendar date.  It has the following slots.
@defivar <sys-tm> sec
Seconds. 0-61.
@end defivar
@defivar <sys-tm> min
Minutes. 0-59.
@end defivar
@defivar <sys-tm> hour
Hours.  0-23.
@end defivar
@defivar <sys-tm> mday
Day of the month, counting from 1.  1-31.
@end defivar
@defivar <sys-tm> mon
Month, counting from 0.  0-11.
@end defivar
@defivar <sys-tm> year
Years since 1900, e.g. 102 for the year 2002.
@end defivar
@defivar <sys-tm> wday
Day of the week.  Sunday = 0 .. Saturday = 6.
@end defivar
@defivar <sys-tm> yday
Day of the year.  January 1 = 0 .. December 31 = 364 or 365.
@end defivar
@defivar <sys-tm> isdst
A flag that indicates if the daylight saving time is in effect.
Positive if DST is in effect, zero if not, or negative if unknown.
@end defivar
@end deftp

@defun sys-gmtime time
@defunx sys-localtime time
[POSIX] Converts @var{time} to @code{<sys-tm>} object, represented in GMT
or local timezone, respectively.   @var{Time} can be either POSIX-time or
SRFI-time.
@end defun

@defun sys-ctime time
[POSIX] Converts @var{time} to it string representation, using POSIX ctime().
@var{Time} can be either POSIX-time or SRFI-time.
@end defun

@defun sys-difftime time1 time0
[POSIX] Returns the difference of two times in the real number of seconds.
@var{Time0} and @var{time1} can be either POSIX-time or SRFI-time.
@end defun

@defun sys-asctime tm
[POSIX] Converts @code{<sys-tm>} object @var{tm} to a string representation.
@end defun

@defun sys-strftime format tm
[POSIX] Converts @code{<sys-tm>} object @var{tm} to a string representation,
according to a format string @var{format}.
@end defun

@defun sys-mktime tm
[POSIX] Converts @code{<sys-tm>} object @var{tm}, expressed as local time,
to the POSIX-time (number of seconds since Epoch).
@end defun

@defun sys-tm->alist tm
(Deprecated function)
@end defun


@subsubheading SRFI time

@deftp {Builtin Class} <time>
@clindex time
The @code{<time>} object also represents a point of time.

@clindex time
@defivar <time> type
Indicates time type.  @code{time-utc} is the default, and that
represents the number of seconds since Unix Epoch.
SRFI-19 (@pxref{Time data types and procedures}) adds more types.
@end defivar
@defivar <time> second
Second part of the time.
@end defivar
@defivar <time> nanosecond
Nanosecond part of the time.
@end defivar
@end deftp

@defun current-time
[SRFI-18][SRFI-21]
Returns the @code{<time>} object representing the current time in
@code{time-utc}.   @xref{Time data types and procedures}, for
it redefines @code{current-time} to allow optional argument to
specify time type.
@end defun

@defun time? obj
[SRFI-18][SRFI-19][SRFI-21]
Returns @code{#t} if @var{obj} is a time object.
@end defun

@defun time->seconds time
@defunx seconds->time seconds
[SRFI-18][SRFI-21]
Converts between time object and the number of seconds (POSIX-time).
@var{Time} argument of @code{time->seconds} has to be a @code{<time>} object.
@end defun


@node Process management, I/O multiplexing, Time, System interface
@subsection Process management
@c NODE プロセス管理

The following procedures provide pretty raw, direct interface
to the system calls.
See also @ref{High-level process interface}, which provides
more convenient process handling on top of these primitives.

@subsubheading Fork and exec

@defun sys-system command
[POSIX]
Runs @var{command} in a subprocess.   @var{command} is usually passed
to @code{sh}, so the shell metacharacters are interpreted.

This function returns an integer value @code{system()} returned.
Since POSIX doesn't define what @code{system()} returns, you can't
interpret the returned value in a portable way.

On Windows native platforms this will pass the argument to @code{cmd.exe}.
@end defun

@defun sys-fork
[POSIX]
Fork the current process.  Returns 0 if you're in the child process,
and a child process' pid if you're in the parent process.
All the opened file descriptors are shared between the parent and
the child.  See @code{fork(2)} of your system for details.

If the child process runs some Scheme code and exits instead of
calling @code{sys-exec}, it should call @code{sys-exit}
instead of @code{exit} to terminate itself.
Normal exit call tries to flush the file
buffers, and on some OS it messes up the parent's file buffers.

It should be noted that @code{sys-fork} is not safe when
multiple threads are running.  Because @code{fork(2)} copies
the process' memory image which includes any mutex state,
a mutex which is locked by another thread at the time of @code{sys-fork}
remains locked in the child process, nevertheless the child process
doesn't have the thread that unlock it!
(This applies to the internal mutexes as well, so even you don't
use Scheme mutex explicitly, this situation can always happen.)

If what you want is to spawn another program in a multi-threaded application,
use @code{sys-fork-and-exec} explained below.
If you absolutely need to run Scheme code in the
child process, a typical technique is that you fork a manager process
at the beginning of application, and whenever you need a new process
you ask the manager process to fork one for you.

This procedure is not available on Windows native platforms.
@end defun

@defun sys-exec command args :key directory iomap sigmask
[POSIX+]
Execute @var{command} with @var{args}, a list of arguments.
The current process image is replaced by @var{command},
so this function never returns.

All elements of @var{args} must be strings.  The first element of
@var{args} is used as @code{argv[0]}, i.e. the program name.

The keyword argument @var{directory} must be a string of a
directory name or @code{#f}.
If it is a string, @code{sys-exec} change current working directory
there before executing the program.

The @var{iomap} keyword argument, when provided, specifies how the
open file descriptors are treated.  It must be the following format:
@example
((@i{to-fd} . @i{from-port-or-fd}) @dots{})
@end example
@i{To-fd} must be an integer,
and @i{from-port-or-fd} must be an integer file descriptor or a port.
Each element of the list makes the file descriptor of @i{from-port-or-fd}
of the current process be mapped to the file descriptor @i{to-fd}
in the executed process.

If @var{iomap} is provided,
any file descriptors other than specified in the iomap list will be closed
before @code{exec()}.  Otherwise, all file descriptors in the current
process remain open.

@example
(sys-exec "ls" '("ls" "-l")) @result{} ;; ls is executed.

(let ((out (open-output-file "ls.out")))
  (sys-exec "ls" '("ls" "-l") :iomap `((2 . 1) (1 . ,out)))
   @result{}
  ;; ls is executed, with its stderr redirected
  ;; to the current process's stdout, and its
  ;; stdout redirected to the file "ls.out".
@end example

The @var{sigmask} keyword argument can be an instance of @code{<sys-sigset>}
or @code{#f} (@xref{Signal}, for the details of signal masks).
If it is an instance of @code{<sys-sigset>}, the signal mask of calling
thread is replaced by it just before @code{exec(2)} is called.
It is useful, for example, to run an external program from a thread where
all signals are blocked (which is the default; see @ref{Signals and threads}).
Without setting @var{sigmask}, the @code{exec}ed process inherits
calling thread's signal mask and become a process that blocks all signals,
which is not very convenient in most cases.

When @code{sys-exec}
encounters an error, most of the time it raises an error condition.
Once the file descriptors are permuted, however, it would be impractical
to handle errors in reasonable way (you don't even know stderr is still
available!), so Gauche simply exits on the error.

On Windows native platforms, only redirections of stdin, stdout and stderr
are handled.   Singal mask is ignored, for Windows doesn't have
signals as the means of interprocess communication.
@end defun

@defun sys-fork-and-exec command args :key directory iomap sigmask detached
Like @code{sys-exec}, but executes @code{fork(2)} just before
remapping I/O, altering signal mask and call @code{execvp(2)}.
Returns child's process id.  The meanings of arguments are
the same as @code{sys-exec}.

It is strongly recommended to use this procedure instead of
@code{sys-fork} and @code{sys-exec} combination when you need
to spawn another program while other threads are running.
No memory allocation nor lock acquisition is done between
@code{fork(2)} and @code{execvp(2)},
so it's pretty safe in the multithreaded environment.

On Windows native platforms, this procedure returns a
Windows handle object (@code{<win:handle>}) of the created
process instead of an integer process ID.  See below for
Windows process handle specific API.

Like @code{sys-exec}, only redirections of stdin, stdout and stderr
are handled on Windows native platforms.

When a true value is given to the @var{detached} keyword argument,
the executed process is detached from the current process group
and belongs to its own group.
That is, it won't be affected to the signal sent to the process group
the caller process currently belongs to.
It is a part of the common idioms to start a daemon process.

On Unix platforms, besides the executed process gets its own session
by @code{setsid(2)}, it performs extra @code{fork(2)} to make its
parent be the @code{init} process (pid=1).
(Note: It means the running process is actually a grandchild of the
calling process, although that relationship isn't preserved.
The returned pid is the running process's one,
not the intermediate process that exits immediately.)

On Windows native platforms,
this flag causes the new process to be
created with the @code{CREATE_NEW_PROCESS_GROUP} creation flag.
@end defun

@subsubheading Wait

@defun sys-wait
[POSIX] Calls system's @code{wait(2)}.  The process suspends its execution
until one of the child terminates.  Returns two exact integer values,
the first one is the child's process id, and the second is a status code.
The status code can be interpreted by the following functions.
@end defun

@defun sys-waitpid pid :key nohang untraced
[POSIX] This is an interface to @code{waitpid(3)}, an extended version of
wait.

@var{pid} is an exact integer specifying which child(ren) to be waited.
If it is a positive integer,
it waits for that specific child.  If it is zero, it waits for any
member of this process group.  If it is -1, it waits for any child process.
If it is less than -1, it waits for any child process whose process group
id is equal to the absolute value of @var{pid}.

If there's no child process to wait, or a specific @var{pid} is
given but it's not a child process of the current process,
an error (@code{<system-error>}, @code{ECHILD}) is signaled.


The calling process suspends until one of those child process is terminated,
unless true is specified to the keyword argument @var{nohang}.

If true is specified to the keyword argument @var{untraced},
the status of stopped child process can be also returned.

The return values are two exact integers, the first one is the child
process id, and the second is a status code.  If @var{nohang} is true and
no child process status is available, the first value is zero.

On Windows native platforms, this procedure may also accept
a Windows process handle (@code{<win:handle>}) object as @var{pid} to
wait the specific process.  You can pass @code{-1} as @var{pid}
to wait for any children, but you cannot wait for a specific
process group.
@end defun

@defun sys-wait-exited? status
@defunx sys-wait-exit-status status
[POSIX]
The argument is an exit status returned as a second value
from @code{sys-wait} or @code{sys-waitpid}.
@code{sys-wait-exited?} returns @code{#t} if the child process is
terminated normally.   @code{sys-wait-exit-status} returns the exit
code the child process passed to @code{exit(2)}, or the return value
of @code{main()}.
@end defun

@defun sys-wait-signaled? status
@defunx sys-wait-termsig status
[POSIX]
The argument is an exit status returned as a second value
from @code{sys-wait} or @code{sys-waitpid}.
@code{sys-wait-signaled?} returns @code{#t} if the child process
is terminated by an uncaught signal.
@code{sys-wait-termsig} returns the signal number that terminated the child.
@end defun

@defun sys-wait-stopped? status
@defunx sys-wait-stopsig status
[POSIX]
The argument is an exit status returned as a second value
from @code{sys-waitpid}.
@code{sys-wait-stopped?} returns @code{#t} if the child process is
stopped.   This status can be caught only by @code{sys-waitpid} with
true @var{untraced} argument.  @code{sys-wait-stopsig} returns the
signum number that stopped the child.
@end defun

On Windows native platforms, exit code is not structured as on Unix.
You cannot distinguish a process being exited voluntarily or
by forced termination.  Gauche uses exit code @code{#xff09} to
terminate other process with @code{sys-kill},
and the above @code{sys-wait-*} procedures are adjusted accordingly,
so that @code{sys-wait-signaled?} can likely to be used to check
whether if the child process is terminated by Gauche.
(@xref{Signal}, for the details of signal support on Windows.)
@code{Sys-wait-stopped?} never returns true
on Windows native platforms (yet).

@subsubheading Windows specific utilities

The following procedures are to access Windows process handle.
They are only available on Windows native platforms.

@defun sys-win-process? obj
[Windows] 
Returns @code{#t} iff @var{obj} is a Windows process handle object.
@end defun

@defun sys-win-process-pid handle
[Windows] 
Returns an integer PID of the process represented by
a Windows process handle @var{handle}.  An error is signaled
if @var{handle} is not a valid Windows process handle.

Note that the API to get a pid from a process handle is only
provided on or after Windows XP SP1.  If you call this
procedure on Windows version before that, @code{-1} will be
returned.
@end defun


@node I/O multiplexing, Garbage collection, Process management, System interface
@subsection I/O multiplexing
@c NODE I/Oの多重化

The interface functions for @code{select(2)}.
The higher level interface is provided on top of these
primitives; see @ref{Simple dispatcher}.

@deftp {Builtin Class} <sys-fdset>
@clindex sys-fdset
Represents @code{fd_set}, a set of file descriptors.  You can make
an empty file descriptor set by make method:
@example
(make <sys-fdset>)
@end example
@end deftp

@defun sys-fdset elt @dots{}
Creates a new @code{<sys-fdset>} instance with file descriptors
specified by @var{elt} @dots{}.  Each @var{elt} can be an
integer file descriptor, a port, or a @code{<sys-fdset>} instance.
In the last case, the descriptors in the given fdset is copied
to the new fdset.
@end defun

@defun sys-fdset-ref fdset port-or-fd
@defunx sys-fdset-set! fdset port-or-fd flag
Gets and sets specific file descriptor bit of @var{fdset}.
@var{port-or-fd} may be a port or an integer file descriptor.
If @var{port-or-fd} is a port that doesn't have associated file descriptor,
@code{sys-fdset-ref} returns @code{#f}, and @code{sys-fdset-set!} doesn't
modify @var{fdset}.  @var{flag} must be a boolean value.

You can use generic setter of @code{sys-fdset-ref} as this:
@example
(set! (sys-fdset-ref fdset port-or-fd) flag)
  @equiv{} (sys-fdset-set! fdset port-or-fd flag)
@end example
@end defun

@defun sys-fdset-copy! dest-fdset src-fdset
Copies the content of @var{src-fdset} into @var{dest-fdset}.
Returns @var{dest-fdset}.
@end defun

@defun sys-fdset-clear! fdset
Empties and returns @var{fdset}.
@end defun

@defun sys-fdset->list fdset
@defunx list->sys-fdset fds
Converts an fdset to a list of integer file descriptors and vice versa.
In fact, @code{list->sys-fdset} works just like
@code{(lambda (fds) (apply sys-fdset fds))}, so it accepts ports
and other fdsets as well as integer file descriptors.
@end defun

@defun sys-fdset-max-fd fdset
Returns the maximum file descriptor number in @var{fdset}.
@end defun

@defun sys-select readfds writefds exceptfds :optional timeout
@defunx sys-select! readfds writefds exceptfds :optional timeout
Waits for a set of file descriptors to change status.
@var{readfds}, @var{writefds}, and @var{exceptfds} are @code{<fdset>}
objects to represent a set of file descriptors to watch.
File descriptors in @var{readfds} are watched to see if characters
are ready to be read.   File descriptors in @var{writefds} are
watched if writing to them is ok.  File descriptors in @var{exceptfds}
are watched for exceptions.  You can pass @code{#f} to one or more
of those arguments if you don't care about watching the condition.

@var{timeout} specifies maximum time @code{sys-select} waits for
the condition change.  It can be a real number, for number of microseconds,
or a list of two integers, the first is the number of seconds and
the second is the number of microseconds.  If you pass @code{#f},
@code{sys-select} waits indefinitely.

@code{sys-select} returns four values.  The first value is a number
of descriptors it detected status change.  It may be zero if
timeout expired.  The second, third and fourth values are @code{<fdset>}
object that contains a set of descriptors that changed status
for reading, writing, and exception, respectively.
If you passed @code{#f} to one or more of @var{readfds},
@var{writefds} and @var{exceptfds}, the corresponding return value
is @code{#f}.

@code{sys-select!} variant works the same as @code{sys-select}, except
it modifies the passed @code{<fdset>} arguments.
@code{sys-select} creates new @code{<fdset>} objects and
doesn't modify its arguments.
@end defun


@node Garbage collection, Miscellaneous system calls, I/O multiplexing, System interface
@subsection Garbage collection
@c NODE ガベージコレクション

The garbage collector runs implicitly whenever it is necessary,
and you don't usually need to worry about it.  However, in case
if you do need to worry, here are a few procedures you can use.

@defun gc
Trigger a full GC.  It may be useful if you want to reduce
interference of GC in certain parts of code by calling this
immediately before that.
@end defun

@defun gc-stat
Returns a list of lists, each inner list contains a keyword and
related statistics. Current statistics include @code{:total-heap-size},
@code{:free-bytes}, @code{:bytes-since-gc} and @code{:total-bytes}.
@end defun

@node Miscellaneous system calls,  , Garbage collection, System interface
@subsection Miscellaneous system calls
@c NODE その他のシステムコール

@defun sys-pause
[POSIX]
Suspends the process until it receives a signal whose
action is to either execute a signal-catching function or to terminate
the process.  This function only returns when the signal-catching
function returns.  The returned value is undefined.

Note that just calling @code{pause()} doesn't suffice the above semantics
in Scheme-level.  Internally this procedure calls @code{sigsuspend()}
with the current signal mask.
@end defun

@defun sys-alarm seconds
[POSIX] Arranges a SIGALRM signal to be delivered after @var{seconds}.
The previous settings of the alarm clock is canceled.  Passing zero
to @var{seconds} doesn't schedule new alarm.
Returns the number of seconds remaining until previously scheduled
alarm was due to be delivered (or zero if no alarm is active).
@end defun

@defun sys-sleep seconds :optional (no-retry #f)
[POSIX]
Suspends the calling thread until the specified number of seconds elapses.

Note that libc's @code{sleep(3)} could return before the specified interval
if the calling thread receives a signal; in that case,
@code{sys-sleep} automatically restarts @code{sleep(3)} again with
remaining time interval
(after invoking Scheme signal handlers if there's any) by default.
So you can count on the thread does sleep at least the specified
amount of time.

If you do want @code{sys-sleep} to return prematurely upon receiving
a signal, you can give a true value to an optional argument @var{no-retry}.

The reason that we retries by default is that Gauche's GC may use
signals to synchronize between threads.   If GC is invoked by one thread
While another thread is sleeping on @code{sleep(3)}, it may return
prematurely.  It could happen often if other threads allocate a lot,
which could make @code{sys-sleep} unreliable.

Returns zero if it sleeps well (which is always the case if @var{no-retry}
is false), or the number of unslept seconds if it is woke up by a signal.

To be portable across POSIX implementation, keep @var{seconds} less than
65536.

Some systems may be using @code{alarm(2)} to implement @code{sleep(3)},
so you shouldn't mix @code{sys-sleep} and @code{sys-alarm}.
@end defun

@defun sys-nanosleep nanoseconds :optional (no-retry #f)
[POSIX]
Suspends the calling thread until the specified number of nanoseconds elapses.
The argument @var{nanoseconds} can be
a @code{<time>} object (@pxref{Time}), or a real number.

The system's @code{nanosleep(2)} could return before the specified interval
if the calling thread receives a signal; in that case,
@code{sys-nanosleep} automatically restarts @code{nanosleep(2)} again with
remaining time interval
(after invoking Scheme signal handlers if there's any) by default.
So you can count on the thread does sleep at least the specified
amount of time.

The reason that we retries by default is that Gauche's GC may use
signals to synchronize between threads.   If GC is invoked by one thread
while another thread is sleeping on @code{nanosleep(2)}, it may return
prematurely.  It could happen often if other threads allocate a lot,
which could make @code{sys-nanosleep} unreliable.

Returns @code{#f} if @var{nanoseconds} elapsed (which is always
the case if @code{no-retry} is @code{#f}),
or a @code{<time>}
object that indicates the remaining time if @code{sys-nanosleep}
is interrupted by a signal.

@example
;@r{wait for 0.5 sec}
(sys-nanosleep 500000000)

;@r{wait for 1.3 sec}
(sys-nanosleep (make <time> :second 1 :nanosecond 300000000))
@end example

Note: On Windows native platforms, this function is emulated using
@code{Sleep}.  The argument is rounded up to millisecond resolution,
and it won't be interrupted by a signal.
@end defun

@defun sys-random
@defunx sys-srandom seed
A pseudo random number generator.
@code{sys-random} returns a random number between 0 and a positive
integer @var{rand_max}, inclusive.  This is a straightforward
interface to @code{random(3)}.  If the underlying system doesn't have
@code{random(3)}, @code{lrand48(3)} is used.

@code{sys-srandom} sets the seed of the random number generator.
It uses either @code{srandom(3)} or @code{srand48(3)}, depending on
the system.

The intention of these functions are to provide an off-the-stock handy
random number generator (RNG) for applications that doesn't
sensitive to the quality and/or speed of RNG.  For serious statistics
analysis, use Mersenne Twister RNG in @code{math.mt-random}
module (@pxref{Mersenne-Twister random number generator}).
@end defun

@defvar RAND_MAX
Bound to a positive integer that @code{sys-random} may return.
@end defvar

@defun sys-get-osfhandle port-or-fd
[Windows] 
This procedure is only available on Windows native platforms.
Returns a Windows file handle associated to the given port or
integer file descriptor.   Throws an error if the given argument
does not have associated file handle.
@end defun


@c ----------------------------------------------------------------------
@node Development helper API,  , System interface, Core library
@section Development helper API
@c NODE 開発補助API

Gauche has some basic built-in APIs to help developers
to analyze the program.

@menu
* Debugging aid::
* Profiler API::
@end menu

@node Debugging aid, Profiler API, Development helper API, Development helper API
@subsection Debugging aid
@c NODE デバッグ補助

@defmac debug-print expr
This macro prints @var{expr} in a source form, then evaluates it,
then prints out the result(s), and returns them.

The output goes to the current trace port
(@pxref{Common port operations}).

The special reader syntax @code{#?=@var{expr}} is expanded into
@code{(debug-print @var{expr})}.  See @ref{Debugging}, for the
details.
@end defmac

@deffn {Parameter} debug-print-width
This parameter specifies the maximum width of information to be
printed by @code{debug-print}.  If the information takes more
columns than the value of this parameter, it is truncated.

To show all the information, set @code{#f} to this parameter.
@end deffn

@defmac debug-funcall (proc arg ...)
This macro prints the value of @var{arg}s right before calling
@var{proc} and the result(s) of the call afterwards.

The output goes to the current trace port
(@pxref{Common port operations}).

The special reader syntax @code{#?,@var{expr}} is expanded into
@code{(debug-funcall @var{expr})}.  See @ref{Debugging}, for the
details.
@end defmac

@defun debug-source-info obj
Retrieves source information attached to @var{obj}.
The source information is returned as a list of source file name
and an integer line number.  If no source information is available
in @var{obj}, @code{#f} is returned.
@end defun

@defun source-code closure
Returns the source code of @var{closure}, if available.
Otherwise, @code{#f} is returned.

Currently, only the code that's directly read from Scheme source
is available; if the Scheme code is precompiled, the source code
isn't saved.   It may be changed in future.
@end defun

@defun source-location closure
Returns the location (a list of filename and line number) where @var{closure}
is defined, if available.  Otherwise, @code{#f} is returned.

@example
gosh> (use rfc.http)
gosh> (source-location http-get)
("/usr/share/gauche-0.9/0.9.5/lib/rfc/http.scm" 443)
@end example
@end defun

@defun disasm closure
Disassemble the compiled body of @var{closure} and print it.
It may not be very useful unless you're tracking a compiler bug,
or trying to tune the program to its limit.

If you're reading the disassembler output, keep in mind that
the compiled code vector may have some dead code; they are produced
by the jump optimization, but the compiler doesn't bother to eliminate
them.
@end defun

@defun debug-label obj
This returns a string that is quasi-unique to an object @var{obj}.
``Quasi-unique'' means the label is unique to the @var{obj}---
the same (@code{eq?}) objs returns the same string, and
if two objs return different string they aren't @code{eq?} to each other---
@emph{until next GC occurs}.

This is mostly for printing out anonymous objects that doesn't
have any other good way to distinguish each other.
Note that uniqueness isn't guaranteed
across GCs, you shouldn't use the returned value as the key to identify
the objects.
@end defun


@node Profiler API,  , Debugging aid, Development helper API
@subsection Profiler API
@c NODE プロファイラAPI

These are the functions to control Gauche's built-in profiler.
See @ref{Using profiler} for the explanation of the profiler.

Note that the profiler isn't guaranteed to work correctly yet in
multi-threaded program, since the interaction between @code{setitimer}
and threads are platform-dependent.

@defun profiler-start
Starts the sampling profiler.   If the profiler is already started,
nothing is done.
@end defun

@defun profiler-stop
Stop the sampling profiler, and save the sampled data into
the internal structure.   If there are already saved sampled data,
the newly obtained data is added to it.
If the profiler isn't running, nothing is done.
@end defun

@defun profiler-reset
Stop the profiler if it is running.  Then discard the
saved sampled data.
@end defun

@defun profiler-show :key sort-by max-rows
Show the saved sampled data.

The keyword argument @var{sort-by} may be one of the symbols
@code{time}, @code{count}, or @code{time-per-call}, to specify
how the result should be sorted.  The default is @code{time}.

The keyword argument @var{max-rows} specifies the max number of
rows to be shown.  If it is @code{#f}, all the data is shown.
@end defun

@defun with-profiler thunk
A convenience procedure.
Call @var{thunk} with the sampling profiler running,
and show the result to the current output port afterwards.
Returns value(s) thunk yields.
The profiler is reset after the result is shown.

You can't nest this construct; the innermost @code{with-profiler}
will reset the profiler, invalidates any outer @code{with-profiler}.
@end defun



@c Local variables:
@c mode: texinfo
@c coding: utf-8
@c end:
@node Object system, Library modules - Overview, Core library, Top
@chapter Object system
@c NODE オブジェクトシステム

Gauche's object system design is largely inspired by
STklos, whose design has come from TinyCLOS.
It supports multiple inheritance, multimethods,
and metaobject protocol.

The type system is integrated to the object system,
that is, a string is an instance of the class @code{<string>},
and so on.

@c ----------------------------------------------------------------------
@menu
* Introduction to the object system::
* Class::
* Instance::
* Generic function and method::
* Metaobject protocol::
@end menu

@node Introduction to the object system, Class, Object system, Object system
@section  Introduction to the object system
@c NODE オブジェクトシステムの紹介

This section briefly explains the basic structure of
Gauche's object system.   It is strongly influenced
by CLOS (Common-Lisp Object System).
If you have experience in CLOS or related systems
such as TinyCLOS, STklos or Guile's object system,
you may skip to the next section.

Three concepts play the central role in CLOS-like object systems:
A @emph{class}, a @emph{generic function}, and a @emph{method}.

A @emph{class} specifies a structure of object.
It also defines a datatype (strictly speaking,
it's not the same thing as a datatype,
but let's skip the complicated part for now).

For example, a point in 2D space can be represented by
x and y coordinates.
A point class can be defined using @code{define-class} macro.
In the shortest form, it can be defined like this:

@example
(define-class <2d-point> () (x y))
@end example

(You can find the code of definitions in the examples of this section
in @code{examples/oointro.scm} of Gauche's source distribution.)

The symbol @code{<2d-point>} is the name of the class, and also
the global variable @code{<2d-point>} is bound to a class object.
Surrounding a class name by @code{<} and @code{>} is just a
convention; you can pass any symbol to @code{define-class}.

The second argument of @code{define-class} is a list of
direct superclasses, which specifies inheritance of the class.
We'll come back to it later.

The third argument of @code{define-class} is a list of
@emph{slots}.  A slot is a storage space, usually in each object,
where you can store a value.  It is something similar to
what is called a field or an instance variable in other
object-oriented languages; but slots can be configured more
than just a per-object storage space.

Now we defined a 2D point class, so we can create an instance
of a point.  You can pass a class to a generic function @code{make}
to create an instance.  (Don't worry about what generic function
is---think it as a special type of function, just for now).

@example
(define a-point (make <2d-point>))

a-point  @result{} #<<2d-point> 0x8117570>
@end example

If you are using @code{gosh} interactively, you can use
a generic function @code{describe} to inspect the internal
of an instance.
A short alias, @code{d}, is defined to @code{describe} for
the convenience.  (See @ref{Interactive session}
for the details).

@example
gosh> (d a-point)
#<<2d-point> 0x8117570> is an instance of class <2d-point>
slots:
  x         : #<unbound>
  y         : #<unbound>
@end example

In order to access or modify the value of the slot, you can use
@code{slot-ref} and @code{slot-set!}, respectively.
These names are taken from STklos.

@example
(slot-ref a-point 'x)  ;; access to the slot x of a-point
  @result{} @r{error, since slot 'x doesn't have a value yet}

(slot-set! a-point 'x 10.0)  ;; set 10.0 to the slot x of a-point

(slot-ref a-point 'x)
  @result{} 10.0
@end example

Gauche also provides a shorter name, @code{ref}, which can also
be used in srfi-17's generalized @code{set!} syntax:
@example
(ref a-point 'x) @result{} 10.0

(set! (ref a-point 'y) 20.0)

(ref a-point 'y) @result{} 20.0
@end example

Now you can see slot values are set.
@example
gosh> (d a-point)
#<<2d-point> 0x8117570> is an instance of class <2d-point>
slots:
  x         : 10.0
  y         : 20.0
@end example

In practice, it is usually convenient if you can specify the default
value for a slot, or give values for slots when you create an instance.
Such information can be specified by @emph{slot options}.
Let's modify the definition of @code{<2d-point>} like this:

@example
(define-class <2d-point> ()
  ((x :init-value 0.0 :init-keyword :x :accessor x-of)
   (y :init-value 0.0 :init-keyword :y :accessor y-of)))
@end example

Note that each slot specification is now a list, instead of just
a symbol as in the previous example.
The list's car now specifies the slot name, and its cdr
gives various information.   The value after @code{:init-value}
defines the default value of the slot.  The keyword after @code{:init-keyword}
defines the keyword argument which can be passed to @code{make} to
initialize the slot at creation time.
The name after keyword @code{:accessor} is bound to a generic
function that can be used to access/modify the slot, instead of
using @code{slot-ref}/@code{slot-set!}.

Let's see some interactive session.  You create an instance
of the new @code{<2d-point>} class, and you can see the slots are
initialized by the default values.
@example
gosh> (define a-point (make <2d-point>))
a-point
gosh> (d a-point)
#<<2d-point> 0x8148680> is an instance of class <2d-point>
slots:
  x         : 0.0
  y         : 0.0
@end example

You create another instance, this time giving initialization values
by keyword arguments.
@example
gosh> (define b-point (make <2d-point> :x 50.0 :y -10.0))
b-point
gosh> (d b-point)
#<<2d-point> 0x8155b80> is an instance of class <2d-point>
slots:
  x         : 50.0
  y         : -10.0
@end example

Accessors are less verbose than @code{slot-ref}/@code{slot-set!}, thus
convenient.
@example
gosh> (x-of a-point)
0.0
gosh> (x-of b-point)
50.0
gosh> (set! (y-of a-point) 3.33)
#<undef>
gosh> (y-of a-point)
3.33
@end example

The full list of available slot options is described in
@ref{Defining class}.  At a first glance,
the declarations of such slot options may look verbose.
The system might have provide a static way to define
init-keywords or accessor names automatically; however,
CLOS-like systems prefer flexibility.
Using a mechanism called metaobject protocol, you can customize
how these slot options are interpreted, and you can add
your own slot options as well.
See @ref{Metaobject protocol}, for details.

We can also have @code{<2d-vector>} class in similar fashion.

@example
(define-class <2d-vector> ()
  ((x :init-value 0.0 :init-keyword :x :accessor x-of)
   (y :init-value 0.0 :init-keyword :y :accessor y-of)))
@end example

Yes, we can use the same accessor name like @code{x-of}, and
it is effectively overloaded.

If you are familiar with mainstream object-oriented languages,
you may wonder where methods are.  Here they are.
The following form defines a method @code{move-by!} of
three arguments, @var{pt}, @var{dx}, @var{dy}, where @var{pt} is
an instance of @code{<2d-point>}.

@example
(define-method move-by! ((pt <2d-point>) dx dy)
  (inc! (x-of pt) dx)
  (inc! (y-of pt) dy))
@end example

The second argument of @code{define-method} macro specifies a
@emph{method specializer list}.  It indicates the first argument must be
an instance of @code{<2d-point>}, and the second and third
can be any type.   The syntax to call a method is just like
the one to call an ordinary function.

@example
gosh> (move-by! b-point 1.4 2.5)
#<undef>
gosh> (d b-point)
#<<2d-point> 0x8155b80> is an instance of class <2d-point>
slots:
  x         : 51.4
  y         : -7.5
@end example

You can overload the method by different specializers; here
you can move a point using a vector.
@example
(define-method move-by! ((pt <2d-point>) (delta <2d-vector>))
  (move-by! pt (x-of delta) (y-of delta)))
@end example

Specialization isn't limited to a user-defined classes.
You can also specialize a method using Gauche's built-in type.
@example
(define-method move-by! ((pt <2d-point>) (c <complex>))
  (move-by! pt (real-part c) (imag-part c)))
@end example

And here's the example session:
@example
gosh> (define d-vector (make <2d-vector> :x -9.0 :y 7.25))
d-vector
gosh> (move-by! b-point d-vector)
#<undef>
gosh> (d b-point)
#<<2d-point> 0x8155b80> is an instance of class <2d-point>
slots:
  x         : 42.4
  y         : -0.25
gosh> (move-by! b-point 3+2i)
#<undef>
gosh> (d b-point)
#<<2d-point> 0x8155b80> is an instance of class <2d-point>
slots:
  x         : 45.4
  y         : -2.25
@end example

You see that a method is dispatched not only by its primary
receiver (@code{<2d-point>}), but also other arguments.
In fact, the first argument is no more special than the rest.
In CLOS-like system a method does not belong to
a particular class.

So what is actually a method?  Inspecting @code{move-by!}
reveals that it is an instance of @code{<generic>}, a generic function.
(Note that @code{describe} truncates the printed value in @code{methods}
slot for the sake of readability).
@example
gosh> move-by!
#<generic move-by! (3)>
gosh> (d move-by!)
#<generic move-by! (3)> is an instance of class <generic>
slots:
  name      : move-by!
  methods   : (#<method (move-by! <2d-point> <complex>)> #<method (move-
gosh> (ref move-by! 'methods)
(#<method (move-by! <2d-point> <complex>)>
 #<method (move-by! <2d-point> <2d-vector>)>
 #<method (move-by! <2d-point> <top> <top>)>)
@end example

I said a generic function is a special type of function.
It is recognized by Gauche as an applicable object, but
when applied, it selects appropriate method(s) according to
its arguments and calls the selected method(s).

What the @code{define-method} macro actually does is (1) to create
a generic function of the given name if it does not exist yet,
(2) to create a method object with the given specializers
and the body, and (3) to add the method object to the generic function.

The accessors are also generic functions, created implicitly by the
@code{define-class} macro.
@example
gosh> (d x-of)
#<generic x-of (2)> is an instance of class <generic>
slots:
  name      : x-of
  methods   : (#<method (x-of <2d-vector>)> #<method (x-of <2d-point>)>)
@end example

In the mainstream dynamic object-oriented languages, a class
has many roles; it defines a structure and a type, creates a
namespace for its slots and methods, and is responsible for
method dispatch.  In Gauche, namespace is managed by modules,
and method dispatch is handled by generic functions.

The default printed representation of object is not very user-friendly.
Gauche's @code{write} and @code{display} function call a generic
function @code{write-object} when they encounter an instance
they don't know how to print.  You can define its method
specialized to your class to customize how the instance is
printed.
@example
(define-method write-object ((pt <2d-point>) port)
  (format port "[[~a, ~a]]" (x-of pt) (y-of pt)))

(define-method write-object ((vec <2d-vector>) port)
  (format port "<<~a, ~a>>" (x-of vec) (y-of vec)))
@end example

And what you'll get is:
@example
gosh> a-point
[[0.0, 3.33]]
gosh> d-vector
<<-9.0, 7.25>>
@end example

If you customize the printed representation to conform srfi-10
format, and define a corresponding read-time constructor,
you can make your instances to be written-out and read-back
just like built-in objects.  See @ref{Read-time constructor} for
the details.

Several built-in functions have similar way to extend their
functionality for user-defined objects.  For example, if
you specialize a generic function @code{object-equal?},
you can compare the instances by @code{equal?}:
@example
(define-method object-equal? ((a <2d-point>) (b <2d-point>))
  (and (equal? (x-of a) (x-of b))
       (equal? (y-of a) (y-of b))))

(equal? (make <2d-point> :x 1 :y 2) (make <2d-point> :x 1 :y 2))
  @result{} #t

(equal? (make <2d-point> :x 1 :y 2) (make <2d-point> :x 2 :y 1))
  @result{} #f

(equal? (make <2d-point> :x 1 :y 2) 'a)
  @result{} #f

(equal? (list (make <2d-point> :x 1 :y 2)
              (make <2d-point> :x 3 :y 4))
        (list (make <2d-point> :x 1 :y 2)
              (make <2d-point> :x 3 :y 4)))
  @result{} #t
@end example

Let's proceed to more interesting examples.
Think of a class @code{<shape>},
which is an entity that can be drawn.
As a base class, it keeps
common attributes such as a color and line thickness in its slots.
@example
(define-class <shape> ()
  ((color     :init-value '(0 0 0) :init-keyword :color)
   (thickness :init-value 2 init-keyword :thickness)))
@end example

When an instance is created, @code{make} calls a generic function
@code{initialize}, which takes care of initializing slots
such as processing init-keywords and init-values.
You can customize the initialization behavior by specializing
the @code{initialize} method.   The @code{initialize} method
is called with two arguments, one is a newly created instance,
and another is a list of arguments passed to @code{make}.

We define a @code{initialize} method for @code{<shape>} class,
so that the created shape will be automatically recorded in a global
list.   Note that we don't want to replace system's
@code{initialize} behavior completely,
since we still need the init-keywords to be handled.

@example
(define *shapes* '())  ;; global shape list

(define-method initialize ((self <shape>) initargs)
  (next-method)  ;; let the system to handle slot initialization
  (push! *shapes* self)) ;; record myself to the global list
@end example
The trick is a special method, @code{next-method}.  It can only be
used inside a method body, and calls @emph{less specific method}
of the same generic function---typically, it means you call the
same method of superclass.
Most object-oriented languages have the concept of calling
superclass's method.  Because of multiple-argument
dispatching and multiple inheritance, @code{next-method} is
a little bit more complicated, but the basic idea is the same.

So, what's the superclass of @code{<shape>}?  In fact, all
Scheme-defined class inherits a class called @code{<object>}.
And it is @code{<object>}'s initialize method which takes care
of slot initialization.  After calling @code{next-method}
within your @code{initialize} method, you can assume all
the slots are properly initialized.  So it is generally the
first thing in your @code{initialize} method to call @code{next-method}.

Let's inspect the above code.  When you call
@code{(make <shape> args @dots{})}, the system allocates
memory for an instance of @code{<shape>}, and calls
@code{initialize} generic function with the instance and
@code{args @dots{}}.  It is dispatched to the @code{initialize}
method you just defined.  In it, you call @code{next-method},
which in turn calls @code{<object>} class's @code{initialize}
method.  It initializes the instance with init-values and init-keywords.
After it returns, you register the new @code{<shape>} instance
to the global shape list @code{*shapes*}.

The @code{<shape>} class represents just an abstract concept of
shape.  Now we define some concrete drawable shapes, by
@emph{subclassing} the @code{<shape>} class.
@example
(define-class <point-shape> (<shape>)
  ((point  :init-form (make <2d-point>) :init-keyword :point)))

(define-class <polyline-shape> (<shape>)
  ((points :init-value '() :init-keyword :points)
   (closed :init-value #f  :init-keyword :closed)))
@end example

Note the second argument passed to @code{define-class}.
It indicates that @code{<point-shape>} and @code{<polyline-shape>}
inherit slots of @code{<shape>} class, and also instances of
those subclasses can be accepted wherever an instance of
@code{<shape>} class is accepted.

The @code{<point-shape>} adds one slot, @code{point}, which
contains an instance of @code{<2d-point>} defined in the beginning
of this section.  The @code{<polyline-shape>} class stores
a list of points, and a flag, which specifies whether the end
point of the polyline is connected to its starting point or not.

Inheritance is a powerful mechanism that should be used with care,
or it easily result a code which is untractable
("Object-oriented programming offers a sustainable way to
write spaghetti code.", as Paul Graham says in his article
"The Hundred-Year Language").
The rule of thumb is to make a subclass when you need a subtype.
The inheritance of slots is just something that comes with,
but it shouldn't be the main reason to do subclassing.
You can always "include" the substructure, as is done in
@code{<point-shape>} class.

There appeared a new slot option in @code{<point-shape>} class.
The @code{:init-form} slot option specifies the default value of
the slot when init-keyword is not given to @code{make} method.
However, unlike @code{:init-value}, with which the value is
evaluated at the time the class is defined,
the value with @code{:init-form} is evaluated when the system
actually needs the value.  So, in the @code{<point-shape>} instance,
the default @code{<2d-point>} instance is only created if the
@code{<point-shape>} instance is created without having @code{:point}
init-keyword argument.

A shape may be drawn in different formats for different devices.
For now, we just consider a PostScript output.  To make the @code{draw}
method polymorphic, we define a postscript output device class,
@code{<ps-device>}.

@example
(define-class <ps-device> () ())
@end example

Then we can write a @code{draw} method, specialized for
both @code{<shape>} and @code{<ps-device>}.
@example
(define-method draw ((self <shape>) (device <ps-device>))
  (format #t "gsave\n")
  (draw-path self device)
  (apply format #t "~a ~a ~a setrgbcolor\n" (ref self 'color))
  (format #t "~a setlinewidth\n" (ref self 'thickness))
  (format #t "stroke\n")
  (format #t "grestore\n"))
@end example

In this code, the @var{device} argument isn't
used within the method body.  It is just used for method dispatching.
If we eventually have different output devices, we can add
a @code{draw} method that is specialized for such devices.

The above @code{draw} method does the common work, but actual
drawing must be done in specialized way for each subclasses.
@example
(define-method draw-path ((self <point-shape>) (device <ps-device>))
  (apply format #t "newpath ~a ~a 1 0 360 arc closepath\n"
         (point->list (ref self 'point))))

(define-method draw-path ((self <polyline-shape>) (device <ps-device>))
  (let ((pts (ref self 'points)))
    (when (>= (length pts) 2)
      (format #t "newpath\n")
      (apply format #t "~a ~a moveto\n" (point->list (car pts)))
      (for-each (lambda (pt)
                  (apply format #t "~a ~a lineto\n" (point->list pt)))
                (cdr pts))
      (when (ref self 'closed)
        (apply format #t "~a ~a lineto\n" (point->list (car pts))))
      (format #t "closepath\n"))))

;; utility method
(define-method point->list ((pt <2d-point>))
  (list (x-of pt) (y-of pt)))
@end example

Finally, we do a little hack.  Let @code{draw} method work on
the list of shapes, so that we can draw multiple shapes within a page
in batch.
@example
(define-method draw ((shapes <list>) (device <ps-device>))
  (format #t "%%\n")
  (for-each (cut draw <> device) shapes)
  (format #t "showpage\n"))
@end example

Then we can write some simple figures @dots{}.
@example
(use srfi-1)      ;; for iota
(use math.const)  ;; for constant pi

(define (shape-sample)

  ;; creates 5 corner points of pentagon
  (define (make-corners scale)
    (map (lambda (i)
           (let ((pt (make <2d-point>)))
             (move-by! pt (make-polar scale (* i 2/5 pi)))
             (move-by! pt 200 200)
             pt))
         (iota 5)))

  (set! *shapes* '())  ;; clear the shape list
  (let* ((corners (make-corners 100)))
    ;; a pentagon in green
    (make <polyline-shape>
      :color '(0 1 0) :closed #t
      :points corners)
    ;; a star-shape in red
    (make <polyline-shape>
      :color '(1 0 0) :closed #t
      :points (list (list-ref corners 0)
                    (list-ref corners 2)
                    (list-ref corners 4)
                    (list-ref corners 1)
                    (list-ref corners 3)))
    ;; put dots in each corner of the star
    (for-each (cut make <point-shape> :point <>)
              (make-corners 90))
    ;; draw the shapes
    (draw *shapes* (make <ps-device>)))
  )
@end example

The function @code{shape-sample} writes out a PostScript code of
simple drawing to the current output port.  You can write it out
to file by the following expression, and then view the result
by PostScript viewer such as GhostScript.
@example
(with-output-to-file "oointro.ps" shape-sample)
@end example

@c ----------------------------------------------------------------------
@node Class, Instance, Introduction to the object system, Object system
@section Class
@c NODE クラス

In this section, a class in Gauche is explained in detail.

@menu
* Defining class::
* Inheritance::
* Class object::
* Slot definition object::
* Class redefinition::
* Class definition examples::
@end menu

@node Defining class, Inheritance, Class, Class
@subsection Defining class
@c NODE クラスの定義

To define a class, use a macro @code{define-class}.

@defmac define-class name supers (slot-spec @dots{}) option @dots{}
Creates a class object according to the arguments, and globally
bind it to a variable @var{name}.   This macro should be used at toplevel.

@var{Supers} is a list of direct superclasses from which this class
inherits.   You can use multiple inheritance.
All Scheme-defined classes implicitly inherits @code{<object>}.
It is implicitly added to the right of @var{supers} list, so you
don't need to specify it.
See @ref{Inheritance}, for the details about inheritance.

@var{Slot-spec} is a specification of a "slot", sometimes known as
a "field" or an "instance variable" (but you can specify "class variable"
in @var{slot-spec} as well).
The simplest form of @var{slot-spec} is just a symbol, which names
the slot.  Or you can give a list, whose first element is a symbol
and whose rest is an interleaved list of keywords and values.
The list form not only defines a name of the slot but specifies
behavior of the slot.  It is explained below.

Finally, @var{option} @dots{} is an interleaved list of keywords
and values, specifies how class object should be created.
This macro recognizes one keyword, @code{:metaclass}, whose
corresponding value is used for metaclass (class that instantiates
another class).   Other options are passed to the @code{make}
method to create the class object.  @xref{Class instantiation},
for the usage of metaclass.
@end defmac

If a slot specification is a list, it should be in the following form:

@example
(@var{slot-name} :option1 value1 :option2 value2 @dots{})
@end example

Each keyword (@code{option1} etc.) gives a @emph{slot option}.
By default, the following slot options are recognized.
You can add more slot options by defining metaclass.

@table @code

@item :allocation
Specifies an allocation type of this slot, which specifies how the
value for this slot is stored.  The following keyword values are
recognized by the standard class.  A programmer can define his own
metaclass to extend the class to recognize other allocation types.

@table @code
@item :instance
A slot is allocated for each instance, so that every instance can have
distinct value.  This realizes so-called "instance variable" behavior.
If @code{:allocation} slot option is omitted, this is the default.
@item :class
A slot is allocated in this class object, so that every instance will
share the same value for this slot.  This realizes so-called
"class variable" behavior.  The slot value is also shared by all
subclasses (unless a subclass definition shadows the slot).
@item :each-subclass
Similar to @code{class} allocation, but a slot is allocated for each
class; that is, it is shared by every instance of the class, but
not shared by the instances of its subclasses.
@item :virtual
No storage is allocated for this type of slot.  Accessing the slot
calls procedures given in @code{:slot-ref} and @code{:slot-set!} options
described below.  In other words, you can make a procedural slot.
If a slot's allocation is specified as virtual, at least
@code{:slot-ref} option has to be specified as well, or @code{define-class}
raises an error.
@item :builtin
This type of allocation only appears in built-in classes, and
you can't specify it in Scheme-defined class.
@end table

@item :init-keyword
A keyword value given to this slot option can be used to pass an
initial value to @code{make} method when an instance is created.

@item :init-value
Gives an initial value of the slot, if the slot is not initialized
by the keyword argument at the creation time.   The value is
evaluated when @code{define-class} is evaluated.

@item :init-form
Like @code{init-value}, but the value given is wrapped in a thunk,
and evaluated each time when the value is required.
If both @code{init-value} and @code{init-form} are given, @code{init-form}
is ignored.   Actually, @code{:init-form @var{expr}} is converted
to @code{:init-thunk (lambda () @var{expr})} by @code{define-class} macro.

@item :initform
A synonym of @code{init-form}.  This is kept for compatibility to
STk, and shouldn't be used in the new code.

@item :init-thunk
Gives a thunk, which will be evaluated to obtain an initial value
of the slot, if the slot is not initialized by the keyword argument
at the creation time.  To give a value to @code{:init-form}
is equivalent to give @code{(lambda () value)} to @code{:init-thunk}.

@item :getter
Takes a symbol, and a getter method is created and bound to the
generic function of that name.  The getter method takes an instance
of the class and returns the value of the slot.

@item :setter
Takes a symbol, and a setter method is created and bound to
the generic function of that name.  The setter method takes an instance
of the class and a value, and sets the value to the slot of the instance.

@item :accessor
Takes a symbol, and create two methods; a getter method and a setter method.
A getter method is bound to the generic function of the given name,
and a setter method is added as the @emph{setter} of that generic function
(see @ref{Assignments} for generic setters).

@item :slot-ref
Specifies a value that evaluates to a procedure which takes one argument,
an instance.  This slot option must be specified if the allocation of
the slot is @code{virtual}.  Whenever a program tries to get the value
of the slot, either using @code{slot-ref} or the getter method,
the specified procedure is called, and its result is returned as
the value of the slot.  The procedure can return an undef value
(the return value of @code{undefined}) to indicate the slot doesn't
have a value.
If the slot allocation is not @code{virtual} this slot option is ignored.

@item :slot-set!
Specifies a value that evaluates to a procedure which takes two arguments,
an instance and a value.  Whenever a program tries
to set the value of the slot, either using @code{slot-set!} or the
setter method, the specified procedure is called with the value to be set.
If the slot allocation is not @code{virtual} this slot option is ignored.
If this option isn't given to a virtual slot, the slot becomes read-only.

@item :slot-bound?
Specifies a value that evaluates to a procedure which takes one argument,
an instance.  This slot option is only meaningful when the slot allocation
is @code{virtual}.  Whenever a program tries to determine whether
the slot has a value, this procedure is called.  It should return
a true value if the slot has a value, or @code{#f} otherwise.
If this slot option is omitted for a virtual slot, the system
calls the procedure given to @code{slot-ref} instead, and see whether
its return value is @code{#<undef>} or not.
@end table

@node Inheritance, Class object, Defining class, Class
@subsection Inheritance
@c NODE 継承

Inheritance has two roles.  First, you can @emph{extend} the existing
class by adding more slots.  Second, you can @emph{specialize} the
methods related to the existing class so that those methods will
do a little more specific task than the original methods.

Let's define some terms.  When a class @code{<T>} inherits a
class @code{<S>}, we call @code{<T>} a @emph{subclass} of @code{<S>},
and @code{<S>} a @emph{superclass} of @code{<T>}.  This relation
is transitive: @code{<T>}'s subclasses are also @code{<S>}'s subclasses,
and @code{<S>}'s superclasses are also @code{<T>}'s superclasses.
Specifically, if @code{<T>} directly inherits @code{<S>}, that is,
@code{<S>} appeared in the superclass list when @code{<T>} is defined,
then @code{<S>} is a @emph{direct superclass} of @code{<T>},
and @code{<T>} is a @emph{direct subclass} of @code{<S>}.

When a class is defined, it and its superclasses are ordered from
subclasses to superclasses, and a list of classes is created in such
order.   It is called @emph{class precedence list}, or CPL.
Every class has its own CPL.
A CPL of a class always begins with the class itself, and ends with
@code{<top>}.

You can query a class's CPL by a procedure @code{class-precedence-list}:

@example
gosh> (class-precedence-list <boolean>)
(#<class <boolean>> #<class <top>>)
gosh> (class-precedence-list <string>)
(#<class <string>> #<class <sequence>> #<class <collection>> #<class <top>>)
@end example

As you see, all classes inherits a class named @code{<top>}.
Some built-in classes have several abstract classes in its CPL
between itself and @code{<top>}; the above example shows @code{<string>}
class inherits @code{<sequence>} and @code{<collection>}.
That means a string can behave both as a sequence and a collection.

@example
gosh> (is-a? "abc" <string>)
#t
gosh> (is-a? "abc" <sequence>)
#t
gosh> (is-a? "abc" <collection>)
#t
@end example

How about inheritance of Scheme-defined classes?
If there's only single inheritance, its CPL is straightforward:
you can just follow the class's super, its super's super, its
super's super's super, @dots{}, until you reach @code{<top>}.
See the example:

@example
gosh> (define-class <a> () ())
<a>
gosh> (define-class <b> (<a>) ())
<b>
gosh> (class-precedence-list <b>)
(#<class <b>> #<class <a>> #<class <object>> #<class <top>>)
@end example

Scheme-defined class always inherits @code{<object>}.
It is automatically inserted by the system.

When multiple inheritance is involved, a story becomes a bit
complicated.  We have to merge multiple CPLs of the superclasses
into one CPL.  It is called @emph{linearization}, and there are
several known linearization strategies.  By default, Gauche uses
an algorithm called @emph{C3 linearization},
which is consistent with the local precedence order,
monotonicity, and the extended precedence graph.
We don't go into the details here; as a general rule,
the order of superclasses in a class's CPL is always
consistent to the order of direct superclasses of
the class, the order of CPL of each superclasses,
and the order of direct superclasses of each superclass,
and so on.   For the precise description, see
Kim Barrett, Bob Cassels, Paul Haahr,
David A. Moon, Keith Playford, P. Tucker Withington,
A Monotonic Superclass Linearization for Dylan,
in @i{Proceedings of OOPSLA 96}, October 1996.

If a class inherits superclasses in a way that its CPL can't
be constructed with satisfying consistencies, an error is reported.

Here's a simple example of multiple inheritance.

@example
(define-class <grid-layout> () ())

(define-class <horizontal-grid> (<grid-layout>) ())

(define-class <vertical-grid> (<grid-layout>) ())

(define-class <hv-grid> (<horizontal-grid> <vertical-grid>) ())

(map class-name (class-precedence-list <hv-grid>))
 @result{} (<hv-grid> <horizontal-grid> <vertical-grid>
     <grid-layout> <object> <top>)
@end example

Note that the order of direct superclasses of @code{<hv-grid>}
(@code{<horizontal-grid>} and @code{<vertical-grid>}) is kept.

The following is a little twisted example:

@example
(define-class <pane> () ())

(define-class <scrolling-mixin> () ())

(define-class <scrollable-pane> (<pane> <scrolling-mixin>) ())

(define-class <editing-mixin> () ())

(define-class <editable-pane> (<pane> <editing-mixin>) ())

(define-class <editable-scrollable-pane>
   (<scrollable-pane> <editable-pane>) ())

(map class-name (class-precedence-list <editable-scrollable-pane>))
 @result{} (<editable-scrollable-pane> <scrollable-pane>
     <editable-pane> <pane> <scrolling-mixin> <editing-mixin>
     <object> <top>)
@end example

Once the class precedence order is determined,
the slots of defined class is calculated as follows:
the slot definitions are collected in the direction from superclasss
to subclass in CPL.  If a subclass has a slot definition of the same
name of the one in superclass, then the slot definition of the subclass
is taken and superclass's is discarded.    Suppose a class @code{<S>}
defines slots @code{a}, @code{b}, and @code{c}, a class @code{<T>}
defines slots @code{c}, @code{d}, and @code{e}, and a class @code{<U>}
defines slots @code{b} and @code{e}.  When @code{<U>}'s CPL is
@code{(<U> <T> <S> <object> <top>)}, then @code{<U>}'s slots is
calculated as the chart below; that is, @code{<U>} gets five slots,
of which @code{b} and @code{e}'s definitions come from @code{<U>}'s
definitions, @code{c} and @code{d}'s come from @code{<T>}, and
@code{a}'s comes from @code{<S>}.

@example
   CPL      | slot definitions
            |  () indicates shadowed slot
 -----------+-------------------
   <top>    |
   <object> |
   <S>      | a  (b) (c)
   <T>      |         c   d  (e)
   <U>      |     b           e
 -----------+--------------------
 <U>'s slots| a   b   c   d   e
@end example

You can get a list of slot definitions of a class object using
@code{class-slots} function.

Note that the behavior described above is mere a default behavior.
You can customize how the CPL is computed, or how slot definitions
are inherited, by defining metaclass.  For example,
you can write a metaclass that allows you to merge slot options
of the same slot names, instead of the one shadowing the other.
Or you can write a metaclass that forbids a subclass shadows
the superclass's slot.

@node Class object, Slot definition object, Inheritance, Class
@subsection Class object
@c NODE クラスオブジェクト

What is a class?  In Gauche, a class is just an object that implements
a specific feature: to instantiate an object.
Because of that, you can introspect the class by just
looking into the slot values.  There are some procedures provided
for the convenience of such introspection.
Note that if those procedures return a list, it belongs to
the class and you shouldn't modify it.

@defun class-name class
Returns the name of @var{class}.

@example
(class-name <string>) @result{} <string>
@end example
@end defun

@defun class-precedence-list class
Returns the class precedence list of @var{class}.

@example
(class-precedence-list <string>)
  @result{} (#<class <string>>
      #<class <sequence>>
      #<class <collection>>
      #<class <top>>)
@end example
@end defun

@defun class-direct-supers class
Returns a list of direct superclasses of @var{class}.
A direct superclass is a class from which
@var{class} inherits directly.

@example
(class-direct-supers <string>)
  @result{} (#<class <sequence>>)
@end example
@end defun

@defun class-direct-subclasses class
Returns a list of direct subclasses of @var{class}.
A direct subclass is a class that directly inherits
@var{class}.  If @code{<T>} is a direct subclass of @code{<S>},
then @code{<S>} is a direct superclass of @code{<T>}.
@end defun

@defun class-slots class
Returns a list of @emph{slot definitions} of @var{class}.
A slot definition is a list whose car is the name of the slot
and whose cdr is a keyword-value list that specifies slot options.
You can further inspect a slot definition to know what characteristics
the slot has.  See @ref{Slot definition object} for the details.

The standard way to get a list of slot names of a given class
is @code{(map slot-definition-name (class-slots class))}.
@end defun

@defun class-slot-definition class slot-name
Returns a slot definition of a slot specified by @var{slot-name} in
a class @var{class}.  If @var{class} doesn't have a named slot,
@code{#f} is returned.
@end defun

@defun class-direct-slots class
Returns a list of slot definitions that are directly defined
in this class (i.e. not inherited from superclasses).
This information is used to calculate slot inheritance
during class initialization.
@end defun

@defun class-direct-methods class
Returns a list of methods that has @var{class} in its specializer.
@end defun

@defun class-slot-accessor class slot-name
Returns a slot accessor object of the slot specified by @var{slot-name}
in @var{class}.
A slot accessor object is an internal object that encapsulates
the information how to access, modify, and initialize the given slot.

You don't usually need to deal with slot accessor objects unless
you are defining some special slots using metaobject protocol.
@end defun

@node Slot definition object, Class redefinition, Class object, Class
@subsection Slot definition object
@c NODE スロット定義オブジェクト

A slot definition object, returned by @code{class-slots},
@code{class-direct-slots} and @code{class-slot-definition},
keeps information about a slot.
Currently Gauche uses a list to represent the slot definition,
as STklos and TinyCLOS do.  However, it is not guaranteed that
Gauche keeps such a structure in future; you should use the
following dedicated accessor methods to obtain information
of a slot definition object.

@defun slot-definition-name slot-def
Returns the name of a slot given by a slot definition object @var{slot-def}.
@end defun

@defun slot-definition-options slot-def
Returns a keyword-value list of slot options of @var{slot-def}.
@end defun

@defun slot-definition-allocation slot-def
Returns the value of @code{:allocation} option of @var{slot-def}.
@end defun

@defun slot-definition-getter slot-def
@defunx slot-definition-setter slot-def
@defunx slot-definition-accessor slot-def
Returns the value of @code{:getter}, @code{:setter} and @code{:accessor}
slot options of @var{slot-def}, respectively.
@end defun

@defun slot-definition-option slot-def option :optional default
Returns the value of slot option @var{option} of @var{slot-def}.
If there's no such an option, @var{default} is returned
if given, or an error is signaled otherwise.
@end defun

@node Class redefinition, Class definition examples, Slot definition object, Class
@subsection Class redefinition
@c NODE クラスの再定義

If the specified class name is bound to a class when @code{define-class}
is used, it is regarded as @emph{redefinition} of the original class.

Redefinition of a class means the following operations:
@itemize @bullet
@item
A new class object is created based on the new definition,
and bound to the variable given to @code{define-class}.

@item
Methods defined on the original class (i.e. methods that have
the original class in their specializers) are changed so that
they are defined on the new class.

@item
The direct-subclasses link of the direct superclasses of the
original class is modified so that they will point to the new class.

@item
All the subclasses of the original class are redefined recursively
so that they reflect the changes of the class.
Each class remembers its initialization arguments, and
each redefined subclass gets the same initialization arguments
as the original subclass.

@item
The original class is marked @emph{redefined}.
@end itemize

Note that the original class and the new class are different objects.
The original class object remembers which variable in which module
it is originally bound, and replaces the binding to a new class.
If you keep the direct reference to the original class somewhere else,
it still refers to the original class; you might want to take extra
care.  You can customize class redefinition behavior by
defining the @code{class-redefinition} method; see
@ref{Metaobject protocol} for the details.

If there are instances of the original class, such instances
are automatically @emph{updated} when it is about to be accessed or modified
via @code{class-of}, @code{is-a?}, @code{slot-ref},
@code{slot-set!}, @code{ref}, a getter method, or a setter method.

Updating an instance means that the class of the instance
is changed (from the old class to the new class).
By default, the values of the slots that are common in the original
class and the new class are carried over, and the slots added
by the new class are initialized according to the slot specification
of the new class, and the values of the slots that are
removed from the original class are discarded.
You can customize this behavior by writing the @code{change-class} method.
See @ref{Changing classes}, for the details.

@subsubheading Notes on thread safety

Class redefinition process is non-local operation with full of side-effects.
It is difficult to guarantee that two threads safely run
class redefinition protocol simultaneously.   So Gauche uses
a process-wide lock to limit only one thread to enter the
class redefinition protocol at a time.

If a thread tries to redefine a class while another thread is in
the redefinition protocol, the thread is blocked, even if
it is redefining a class different from the one that are
being redefined; because redefinition affects all the
subclasses, and all the methods and generic functions that
are related to the class and subclasses, it is not trivial
to determine two classes are completely independent or not.

If a thread tries to access an instance whose class
is being redefined by another thread, also the thread
is blocked until the redefinition is finished.

Note that the instance update protocol isn't serialized.
If two threads try to access an instance whose
class has been redefined, both trigger the instance
update protocol, which would cause an undesired race condition.
It is the application's responsibility to ensure
such a case won't happen.  It is natural since the
instance access isn't serialized by the system anyway.
However, an extra care is required to have mutex within
an instance; just accessing the mutex in it may trigger
the instance update protocol.

@subsubheading Notes on compatibility

Class redefinition protocols subtlety differ among CLOS-like
Scheme systems.   Gauche's is very similar to STklos's, except
that STklos 0.56 doesn't replace bindings of redefined subclasses,
and also it doesn't remember initialization arguments so the
redefined subclass may lose some of the information that the original
subclass has.  Guile's object system swaps identities of the original
class and the redefined class at the end of class redefinition
protocol, so the reference to the original class object
will turn to the redefined class.
As far as the author knows, class redefinition is not thread-safe
in both STklos 0.56 and Guile 1.6.4.

@node Class definition examples,  , Class redefinition, Class
@subsection Class definition examples
@c NODE クラスの定義例

Let's see some examples.  Suppose you are defining a graphical
toolkit.  A @code{<window>} is a rectangle region on
the screen, so it has width and height.  It can be organized
hierarchically, i.e. a window can be placed within another window;
so it has a pointer to the parent window.  And we specify the
window's position, x, y, by the coordinate relative to its
parent window.  Finally, we create a "root" window that
covers entire screen.  It also serves the default parent window.
So far, what we get is something like this:

@example
;; The first version
(define-class <window> ()
  (;; Pointer to the parent window.
   (parent      :init-keyword :parent :init-form *root-window*)
   ;; Sizes of the window
   (width       :init-keyword :width  :init-value 1)
   (height      :init-keyword :height :init-value 1)
   ;; Position of the window relative to the parent.
   (x           :init-keyword :x :init-value 0)
   (y           :init-keyword :y :init-value 0)
   ))

(define *screen-width* 1280)
(define *screen-height* 1024)

(define *root-window*
  (make <window> :parent #f :width *screen-width* :height *screen-height*))
@end example

Note the usage of @code{:init-value} and @code{:init-form}.
When the @code{<window>} class is defined, we haven't bound
@code{*root-window*} yet, so we can't use @code{:init-value} here.

@example
gosh> *root-window*
#<<window> 0x80db1d0>
gosh> (define window-a (make <window> :width 100 :height 100))
window-a
gosh> (d window-a)
#<<window> 0x80db1b0> is an instance of class <window>
slots:
  parent    : #<<window> 0x80db1d0>
  width     : 100
  height    : 100
  x         : 0
  y         : 0
gosh> (define window-b
        (make <window> :parent window-a :width 50 :height 20 :x 10 :y 5))
window-b
gosh> (d window-b)
#<<window> 0x80db140> is an instance of class <window>
slots:
  parent    : #<<window> 0x80db1b0>
  width     : 50
  height    : 20
  x         : 10
  y         : 5
@end example

If you're like me, you don't want to expose a global variable
such as @code{*root-window*} for users of your toolkit.
One way to encapsulate it (to certain extent) is to keep
the pointer to the root window in a class variable.
Add the following slot option to the definition of @code{<window>},
and the slot @code{root-window} of the @code{<window>} class
refers to the same storage space.

@example
(define-class <window> ()
  (...
   ...
   (root-window :allocation :class)
   ...))
@end example

You can use @code{slot-ref} and @code{slot-set!} on an instance
of @code{<window>},
or use @code{class-slot-ref} and @code{class-slot-set!} on the
@code{<window>} class itself,
to get/set the value of the @code{root-window} slot.

The users of the toolkit may want to get the absolute position
of the window (the coordinates in the root window) instead of
the relative position.  You may provide virtual slots that
returns the absolute positions, like the following:

@example
(define-class <window> ()
  (...
   ...
   (root-x :allocation :virtual
           :slot-ref  (lambda (o)
                        (if (ref o 'parent)
                            (+ (ref (ref o 'parent) 'root-x)
                               (ref o 'x))
                            (ref o 'x)))
           :slot-set! (lambda (o v)
                        (set! (ref o 'x)
                              (if (ref o 'parent)
                                  (- v (ref (ref o 'parent) 'root-x))
                                  v)))
            )
    ...))
@end example

Whether providing such interface via methods or virtual slots is
somewhat a matter of taste.   Using virtual slots has an advantage
of being able to hide the change of implementation, i.e. you can
change to keep @code{root-x} in a real slot and make @code{x} a virtual
slot later without breaking the code using @code{<window>}.
(In the mainstream object-oriented languages,
such kind of "hiding implementation" is usually achieved
by hiding instance variables and exposing methods.  In Gauche
and other CLOS-like systems, slots are always visible to the
users, so the situation is a bit different.

@c ----------------------------------------------------------------------
@node Instance, Generic function and method, Class, Object system
@section Instance
@c NODE インスタンス

In this section, we explain how to create and use an instance.

@menu
* Creating instance::
* Accessing instance::
* Changing classes::
@end menu

@node Creating instance, Accessing instance, Instance, Instance
@subsection Creating instance
@c NODE インスタンスの作成

Using class object, you can create an instance of the class
by a generic function @code{make}.
A specialized method for standard @code{<class>} is defined:

@deffn {Generic Function} make
@deffnx {Method} make (class <class>) arg @dots{}
Creates an instance of @var{class} and returns it.
@var{Arg} @dots{} is typically a keyword-value list
to initialize the instance.
@end deffn

Conceptually, the default @code{make} method is defined
as follows:

@example
(define-method make ((class <class>) . initargs)
  (let ((obj (allocate-instance class initargs)))
    (initialize obj initargs)
    obj))
@end example

That is, first it allocates memory for @var{class}'s instance,
then initialize it with the @code{initialize} method.

@deffn {Generic Function} allocate-instance
@deffnx {Method} allocate-instance (class <class>) initargs
Returns a newly-allocated uninitialized instance of @var{class}.
@end deffn

@deffn {Generic Function} initialize
@deffnx {Method} initialize (obj <object>) initargs
The default initialize method for @code{<object>} works as follows:

@itemize @bullet
@item
For each initializable slot of the class
@itemize @bullet
@item
If (the slot has the :init-keyword slot option
AND the keyword appears in @var{initargs}):
Then the corresponding value is used to initialize the slot
@item
Else if the slot has :init-value slot option:
Then the value given to the slot option is used to initialize the slot
@item
Else if the slot has :init-thunk slot option:
Then the thunk is called, and the returned value is used to initialize
the slot.
@item
Else: The slot is left unbound.
@end itemize
@end itemize

Among the default slot allocation classes, only
instance-allocated slots are initializable and are handled by
the above sequence.   Class-allocated slots (e.g. its
slot allocation is either @code{:class} or @code{:each-subclass})
are initialized when the class object is created, if
@code{:init-value} or @code{:init-form} slot option is given.
Virtual slots aren't initialized at all.

An user-defined allocation class can be
configured either initializable or not initializable; see
@ref{Metaobject protocol} for the details.

If you specialize @code{initialize} method, make sure to call
@code{next-method} so that the slots are properly initialized
by the default sequence, before accessing any slot of the
newly created instance.
@end deffn

Typically you specialize @code{initialize} method for
your class to customize how the instance is initialized.

It is not common to specialize @code{allocate-instance} method.
However, knowing that how @code{make} works, you can specialize
@code{make} itself to avoid allocation of instance in
some circumstances (e.g. using pre-allocated instances).

@node Accessing instance, Changing classes, Creating instance, Instance
@subsection Accessing instance
@c NODE インスタンスへのアクセス

@subsubheading Standard accessors

@defun slot-ref obj slot
Returns a value of the slot @var{slot} of object @var{obj}.

If the specified slot is not bound to any value, a generic function
@code{slot-unbound} is called with three arguments, @var{obj}'s class,
@var{obj}, and @var{slot}.  The default behavior of @code{slot-unbound}
is to signal an error.

If the object doesn't have the specified slot,
a generic function @code{slot-missing} is called with three
arguments, @var{obj}'s class,
@var{obj}, and @var{slot}.  The default behavior of @code{slot-missing}
is to signal an error.
@end defun

@defun slot-set! obj slot value
Alters the value of the slot @var{slot} of object @var{obj} to
the value @var{value}.

If the object doesn't have the specified slot, a generic function
@code{slot-missing} is called with four arguments,
@var{obj}'s class, @var{obj}, @var{slot}, @var{value}.
@end defun

@defun slot-bound? obj slot
Returns true if object @var{obj}'s slot @var{slot} is bound,
otherwise returns false.

If the object doesn't have the specified slot, a generic function
@code{slot-missing} is called with three arguments,
@var{obj}'s class, @var{obj}, @var{slot}.
@end defun

@defun slot-exists? obj slot
Returns true if @var{obj} has the slot named @var{slot}.
@end defun

@defun slot-push! obj slot value
This function implements the common idiom.
It can be defined like the following code
(but it may be optimized in the future versions).
@example
(define (slot-push! obj slot value)
  (slot-set! obj slot (cons value (slot-ref obj slot))))
@end example
@end defun

@defun slot-pop! obj slot :optional fallback
Reverse operation of @code{slot-push!}.
If the value of @var{slot} of @var{obj}
is a pair, removes its car and returns the removed item.

When the value of @var{slot} is not a pair, or the @var{slot} is unbound,
@var{fallback} is returned if it is provided, otherwise an error is
signaled.
@end defun

@deffn {Method} ref (obj <object>) (slot <symbol>)
@deffnx {Method} {(setter ref)} (obj <object>) (slot <symbol>) value
These methods just calls @code{slot-ref} and @code{slot-set!}, respectively.
They are slightly less efficient than directly calling @code{slot-ref}
and @code{slot-set!}, but more compact in the program code.
@end deffn

@subsubheading Fallback methods

@deffn {Generic Function} slot-unbound
@deffnx {Method} slot-unbound (class <class>) obj slot
This generic function is called when an unbound slot value is
retrieved.  The return value of this generic function will be
returned to the caller that tried to get the value.

The default method just signals an error.
@end deffn

@deffn {Generic Function} slot-missing
@deffnx {Method} slot-missing (class <class>) obj slot :optional value
This generic function is called when a non-existent slot
value is retrieved or set.  The return value of this generic
function will be returned to the caller that tried to get the value.

The default method just signals an error.
@end deffn

@subsubheading Special accessors

@defun current-class-of obj
Returns a class metaobject of @var{obj}.  If @var{obj}'s class
has been redefined, but @var{obj} is not updated for the change,
then this procedure returns the original class of @var{obj}
without updating @var{obj}.

You need this procedure in rare occasions, such as within
@code{change-class} method, in which you don't want to trigger
updating @var{obj} (which would cause infinite loop).
@end defun

@defun class-slot-ref class slot-name
@defunx class-slot-set! class slot-name obj
@defunx class-slot-bound? class slot-name obj
When slot's @code{:allocation} option is either @code{:class}
or @code{:each-subclass}, these procedures allow you to
get/set the value of the slot without having an instance.
@end defun

@deffn {Method} slot-ref-using-class (class <class>) (obj <object>) slot-name
@deffnx {Method} slot-set-using-class! (class <class>) (obj <object>) slot-name value
@deffnx {Method} slot-bound-using-class? (class <class>) (obj <object>) slot-name
Generic function version of @code{slot-ref}, @code{slot-set!} and
@code{slot-bound?}.   @var{Class} must be the class of @var{obj}.

Besides being generic, these functions are different from
their procedural versions that they don't trigger class
redefinition when @var{obj}'s class has been redefined
(i.e. in which case, @var{class} should be the original class
of @var{obj}).

Note: Unlike CLOS, @code{slot-ref} etc. don't call the generic
function version in it, so you can't customize the behavior
of @code{slot-ref} by specializing @code{slot-ref-using-class}.
So the primary purpose of those generic functions are to be
used within @code{change-class} method; especially, @code{slot-ref} etc.
can't be used during @var{obj}'s being redefined, since they
trigger class redefinition again (see @ref{Changing classes} for details).
@end deffn

@node Changing classes,  , Accessing instance, Instance
@subsection Changing classes
@c NODE クラスの変更

@subsubheading Class change protocol

An unique feature of CLOS-family object system is that
you can change classes of an existing instance.  The two
classes doesn't need to be related; you can change a sewing
machine into an umbrella, if you like.

@deffn {Generic Function} change-class
@deffnx {Method} change-class (obj <object>) (new-class <class>)
Changes an object @var{obj}'s class to @var{new-class}.
The default method just calls @code{change-object-class} procedure.
@end deffn

@defun change-object-class obj orig-class new-class
Changes an object @var{obj}'s class from @var{orig-class} to
@var{new-class}.  This isn't a generic function---changing object's
class needs some secret magic, and this procedure encapsulates it.

The precise steps of changing class are as follow:

@enumerate
@item
A new instance of @var{new-class} is allocated by @code{allocate-instance}.

@item
For each slot of @var{new-class}:
@enumerate
@item
If the slot also exists in @var{old-class}, and is bound in @var{obj},
the value is retrieved from @var{obj} and set to the new instance.
(The slot is @emph{carried over}).
@item
Otherwise, the slot of the new instance is initialized by standard
slot initialization protocol, as described in @ref{Creating instance}.
@end enumerate

@item
Finally, the content of the new instance is @emph{transplanted} to
the @var{obj}---that is, @var{obj} becomes the instance of @var{new-class}
without changing its identity.
@end enumerate

Note that @code{initialize} method of @var{new-class}
isn't called on @var{obj}.
If you desire, you can call it by your own @code{change-class} method.

@code{Change-object-class} returns @var{obj}.
@end defun

Usually a user is not supposed to call @code{change-object-class} directly.
Instead, she can define a specialized @code{change-class}.  For example,
if she wants to carry over the slot @code{x} of old class to the
slot @code{y} of new class, she may write something like this:

@example
(define-method change-class ((obj <old-class>) <new-class>)
  (let ((old-val (slot-ref obj 'x)))
    (next-method)               ;; calls default change-class
    (slot-set! obj 'y old-val)  ;; here, obj's class is already <new-class>.
    obj))
@end example

@subsubheading Customizing instance update

Updating an instance for a redefined class is also handled
as class change.  When an object is accessed via normal
slot accessor/modifier, its class is checked whether
it has been redefined.  And if it has indeed been redefined,
@code{change-class} is called with the
redefined class as @var{new-class}; that is, updating
an instance is regarded as changing object's class from
the original one to the redefined one.

By specializing @code{change-class}, you can customize the
way an instance is updated for a redefined class.
However, you need a special care to write @code{change-class}
for class redefinition.

First, the redefinition changes global binding of the class object.
So you need to keep the reference to the old class before
redefining the class, and use the old class to specialize
@code{change-class} method:

@example
;; save old <myclass>
(define <old-myclass> <myclass>)

;; redefine <myclass>
(define-class <myclass> ()
  ...)

;; define customized change-class method
(define-method change-class ((obj <old-myclass>) <myclass>)
  ...
  (next-method)
  ...)
@end example

Next, note that the above @code{change-class} method may be
triggered implicitly when you access to @var{obj} via
@code{slot-ref}, @code{slot-set!}, @code{class-of}, etc.
If you use such procedures like @code{slot-ref} on @var{obj}
again within @code{change-class}, it would trigger the
instance update protocol recursively, which would cause
an infinite loop.
You can only use the methods that doesn't trigger
instance update, that is, @code{slot-ref-using-class},
@code{slot-set-using-class!}, @code{slot-bound-using-class?}
and @code{current-class-of}.

If you want to carry over a slot whose value is calculated
procedurally, such as a virtual slot, then @code{slot-ref} etc.
might be called implicitly on @var{obj} during calculating the
slot value.  Actually @code{change-object-class} has a
special protection to detect such a recursion.  If that
happens, @code{change-object-class} gives up to retrieve
the slot value and just initializes the slot of the new instance
as if the old slot were unbound.

Customizing instance update is highly tricky business,
although very powerful.   You can find some nontrivial
cases in the test program of Gauche source code;
take a look at @code{test/object.scm}.

@c ----------------------------------------------------------------------
@node Generic function and method, Metaobject protocol, Instance, Object system
@section Generic function and method
@c NODE ジェネリックファンクションとメソッド

@subheading Defining methods

@defmac define-generic name :key class
Creates a generic function and bind it to @var{name}.

You don't usually need to use this, since the @code{define-method}
macro implicitly creates a generic function if it doesn't exist yet.

You can pass a subclass of @code{<generic>} to the @var{class}
keyword argument so that the created generic function will be the
instance of the passed class, instead of the default @code{<generic>} class.
It is useful when you defined a subclass of @code{<generic>} to customize
generic function application behavior.
@end defmac

@defmac define-method name [qualifier @dots{}] specs body
Defines a method whose name is @var{name}.  If there's already
a generic function object globally bound to @var{name}, the created
method is added to the generic function.  If @var{name} is unbound,
or bound to an object except a generic function, then a new generic
function is created, bound to @var{name}, then a new method is
added to it.

The name can be followed by optional @var{qualifiers}, each of
which is a keyword.  Currently, only the following qualifier is
valid.

@table @code
@item :locked
Declares that you won't redefine
the method with the same specifiers.  Attempt to redefine it
will raise an error.  (You can still define methods with
different specifiers.)

Most methods concerning basic operations on built-in objects
are locked, for redefining them would case Gauche's infrastracture
unstable.  It also allows Gauche to perform certain optimizations.
@end table

@var{Specs} specifies the arguments and their types for this method.
It's like the argument list of lambda form, except you can specify
the type of each argument.

@example
@i{specs} : ( @i{arg} @dots{} )
      | ( @i{arg} @dots{} . @i{symbol} )
      | ( @i{arg} @dots{} @i{extended-spec} @dots{})
      | @i{symbol}

@i{arg}   : ( @i{symbol} @i{class} )
      | @i{symbol}
@end example

@i{Class} specifies the class that the argument has to belong to.
If @code{@i{arg}} is just a symbol, it is equivalent to
@code{(@i{arg} <top>)}.  You can't specify the type for
the ``rest'' argument, for it is always bound to a list.

You can use extended argument specifications such as
@code{:optional}, @code{:key} and @code{:rest} as well.
(@xref{Making procedures}, for the explanation of extended
argument specifications).  Those extended arguments are treated
as if a single ``rest'' argument in terms of dispatching; they
aren't used for method dispatch, and you can't specify classes for
these optional and keyword arguments.

The list of classes of the argument list is called
@emph{method specializer list}, based on which the generic
function will select appropriate methods(s).
Here are some examples of @var{specs} and the corresponding
specializer list (note that the rest argument isn't considered
as a part of specializer list; we know it's always a list.)
The @code{optional} item indicates whether the method takes
rest arguments or not.

@example
specs:        ((self <myclass>) (index <integer>) value)
specializers: (<myclass> <integer> <top>)
optional:     #f

specs:        (obj (attr <string>))
specializers: (<top> <string>)
optional:     #f

specs:        ((self <myclass>) obj . options)
specializers: (<myclass> <top>)
optional:     #t

specs:        ((self <myclass>) obj :optional (a 0) (b 1) :key (c 2))
specializers: (<myclass> <top>)
optional:     #t

specs:        args
specializers: ()
optional:     #t
@end example

If you define a method on @var{name} whose specializer list,
and whether it takes rest arguments,
match with one in the generic function's methods,
then the existing method is
replaced by the newly defined one, unless the original method is locked.

Note: If you're running Gauche with keyword-symbol integrated
mode (@pxref{Keyword and symbol integration}), there's an ambiguity
if you specify a keyword as the sole @var{specs} (to receive entire
arguments in a single variable).
Gauche parses keywords following @var{name}
as qualifiers, so avoid using a keyword as such a variable.
@end defmac

@subheading Applying generic function

When a generic function is applied, first it selects
methods whose specializer list matches the given arguments.
For example, suppose a generic function @code{foo} has
three methods, whose specializer lists are
@code{(<string> <top>)}, @code{(<string> <string>)},
and @code{(<top> <top>)}, respectively.
When @code{foo} is applied like @code{(foo "abc" 3)},
the first and the third method will be selected.

Then the selected methods are sorted from the most
@emph{specific} method to the least specific method.
It is calculated as follows:

@itemize
@item
Suppose we have a method @code{a} that has
specializers @code{(A1 A2 @dots{})}, and
a method @code{b} that has @code{(B1 B2 @dots{})}.

@item
Find the minimum @var{n} where the classes @code{An} and @code{Bn}
differ.   Then the class of @var{n}-th argument is taken,
and its class precedence list is checked.
If @code{An} comes before @code{Bn} in the CPL, then
method @code{a} is more specific than @code{b}.
Otherwise, @code{b} is more specific than @code{a}.

@item
If all the specializers of @code{a} and @code{b} are the same,
except that one has an improper tail ("rest" argument)
and another doesn't, then the method that doesn't have an improper
tail is more specific than the one that has.
@end itemize

Once methods are sorted, the body of the first method is
called with the actual argument.

Within the method body, a special local variable @code{next-method}
is bound implicitly.

@deffn {Next method} next-method
@deffnx {Next method} next-method args @dots{}
This variable is bound within a method body
to a special object that encapsulates
the next method in the sorted method list.

Calling without arguments invokes the next method with
the same arguments as this method is called with.
Passing @var{args} @dots{} explicitly invokes the next method
with the passed arguments.

If @code{next-method} is called in the least specific method,
i.e. there's no "next method", an error is signaled.
@end deffn

@c ----------------------------------------------------------------------
@node Metaobject protocol,  , Generic function and method, Object system
@section Metaobject protocol
@c NODE メタオブジェクトプロトコル

In CLOS-like object systems, the object system is built on
top of itself---that is, things such as the structure of the class,
how a class is created, how an instance is created and initialized,
and how a method is dispatched and called, are all defined in terms
of the object system.  For example, a class is just an instance of
the class @code{<class>} that defines a generic structure and behavior
of standard classes.  If you subclass @code{<class>}, then you can
create your own set of classes that behaves differently than the
default behavior; in effect, you are creating your own object system.

@emph{Metaobject protocols} are the definitions of APIs concerning
about how the object systems are built---building-block classes,
and the names and orders of generic functions to be called
during operations of the object system.  Subclassing these classes
and specializing these methods are the means of customizing object
system behaviors.

@menu
* Class instantiation::
* Customizing slot access::
* Method instantiation::
* Customizing method application::
* Customizing class redefinition::
@end menu


@node Class instantiation, Customizing slot access, Metaobject protocol, Metaobject protocol
@subsection Class instantiation
@c NODE クラスのインスタンシエーション

Every class is an instance of a group of special classes.
A class that can be a class of another class is called @emph{metaclass}.
In Gauche, only the @code{<class>} class or its subclasses
can be a metaclass.

@subsubheading Expansion of @code{define-class}

The @code{define-class} macro is basically a wrapper of
the code that creates an instance of @code{<class>}
(or specified metaclass) and bind it to the given name.
Suppose you have the following @code{define-class} form.
@example
(define-class @var{name} (@var{supers})
  @var{slot-specs}
  @var{options} @dots{})
@end example

It is expanded into a form like this (you can see the exact form
by looking at the definition of @code{define-class} macro in
@code{src/libobj.scm} of the source code tree.
@example
(define @var{name}
  (let ((tmp1 (make @var{metaclass}
                 :name '@var{name} :supers (list @var{supers})
                 :slots (map @var{process-slot-definitions}
                             @var{slot-specs})
                 :defined-modules (list (current-module))
                 @var{options} @dots{})))
    @dots{} @var{check class redefinition} @dots{}
    @dots{} @var{registering accessor methods} @dots{}
    tmp1))
@end example

The created class's class, i.e. @var{metaclass},
is determined by the following rules.

@enumerate
@item
If @code{:metaclass} option is given to the @code{define-class}
macro, its value is used.  The value must be the @code{<class>}
class or its descendants.
@item
Otherwise, the metaclasses of the classes in the class precedence list
is examined.
@itemize @bullet
@item
If all the metaclasses are @code{<class>}, then
the created class's metaclass is also @code{<class>}.
@item
If all the metaclasses are either @code{<class>} or another metaclass
@code{A}, then the created class' metaclass is @code{A}.
@item
If the set of metaclasses contains more than one metaclass
(@code{A}, @code{B}, @code{C} @dots{}) other than @code{<class>},
then the created class' metaclass
is a metaclass that inherits all of those metaclasses
@code{A}, @code{B}, @code{C} @dots{}.
@end itemize
@end enumerate

The class's name, superclasses, and slot definitions are passed
as the initialization arguments to the @code{make} generic function,
with other arguments passed to @code{define-class}.
The initialization argument @code{defined-modules} is passed to
remember which module the class is defined, for the redefinition of
this class.

The slot specifications @var{slot-specs} are processed
by internal method @var{process-slot-definitions}
(which can't be directly called) to be turned
into slot definitions.  Specifically, an @code{:init-form} slot
option is turned into an @code{:init-thunk} option, and
@code{:getter}, @code{:setter} and @code{:accessor} slot
options are quoted.

After the class (an instance of @var{metaclass}) is created,
the global binding of @var{name} is checked.  If it is bound
to a class, then the class redefinition protocol is invoked
(see @ref{Class redefinition}).

Then, the methods given to @code{:getter}, @code{:setter}
and @code{:accessor} slot options in @var{slot-spec} are
collected and registered to the corresponding generic functions.

@subsubheading Class structure

@deftp {Class} <class>
@clindex class
The base class of all metaclasses, @code{<class>}, has
the following slots.  Note that these slots are for internal management,
and users can't change those information freely once the class is
initialized.

It is recommended to obtain information
about a class by procedures described in @ref{Class object}, instead
of directly accessing those slots.


@defivar <class> name
The name of the class; the symbol given to @code{define-class} macro.
@code{class-name} returns this value.
@end defivar

@defivar <class> cpl
Class precedence list.  @code{class-precedence-list} returns this value.
@end defivar

@defivar <class> direct-supers
The list of direct superclasses.
@code{class-direct-supers} returns this value.
@end defivar

@defivar <class> accessors
An assoc list of slot accessors---it encapsulates how each slot
should be accessed.
@end defivar

@defivar <class> slots
A list of slot definitions.  @code{class-slots} returns this value.
See @ref{Slot definition object}, for the details of slot definitions.
@end defivar

@defivar <class> direct-slots
A list of slot definitions that is directly specified in this
class definition (i.e. not inherited).
@code{class-direct-slots} returns this value.
@end defivar

@defivar <class> num-instance-slots
The number of instance allocated slots.
@end defivar

@defivar <class> direct-subclasses
A list of classes that directly inherits this class.
@code{class-direct-subclasses} returns this value.
@end defivar

@defivar <class> direct-methods
A list of methods that has this class in its specializer list.
@code{class-direct-methods} returns this value.
@end defivar

@defivar <class> initargs
The initialization argument list when this class is created.
The information is used to initialize redefined class
(see @ref{Class redefinition}).
@end defivar

@defivar <class> defined-modules
A list of modules where this class has a global binding.
@end defivar

@defivar <class> redefined
If this class has been redefined, this slot contains a reference
to the new class.  Otherwise, this slot has @code{#f}.
@end defivar

@defivar <class> category
The value of this slot indicates how this class is created.
Scheme defined class has a symbol @code{scheme}.  Other values
are for internal use.
@end defivar
@end deftp

@subsubheading The initialize method for @code{<class>}

@deffn {Method} initialize (class <class>) initargs
The @code{define-class} macro expands into a call of
@code{(make <class> @dots{})}, which allocates a class metaobject
and calls @code{initialize} method.   This method takes care of
computing inheritance order (class precedence list) and calculate slots,
and set up various internal slots.  Then, at the very end of
this method, it @emph{freezes} the essential class slots; they became
immutable.

Calculation of inheritance and slots are handle by generic
functions.  If you define a metaclass, you can define methods
for them to customize how those calculations are done.
Class inheritance is calculated by @code{compute-cpl} defined below.
Slot calculation is a bit involved, and explained in the 
next subsection (@pxref{Customizing slot access}).

If your class needs to initialize auxiliary slots, you can
define your own @code{initialize} method on its metaclass, in which you call
@code{next-method} first to set up the core part of the
@code{<class>} structure, then you sets up class-specific part.  
One caveat is that, after @code{next-method} handles
initialization of the core @code{<class>} part, you can no longer
modify essential class slots.  If you need to tweak those slots,
you can override @code{class-post-initialize} method, which
is called right before the core class slots are frozen.
@end deffn

@deffn {Generic function} compute-cpl class
This generic function is called from @code{initialize} method
on @code{<class>}, and responsible to compute the class
precedence list (CPL).

At the time this generic function is called,
only @code{name} and @code{direct-supers} slots of @var{class}
are set.  The @code{direct-supers} slot contains a list of
classes @var{class} directly inherits from.  All classes in
it is already initialized.

It must return a list of classes, starting with @var{class}
itself and ending with @code{<top>}, representing the order
of precedence with which methods are searched.  The method
defined for @code{<class>} uses C3 linearlization, which
topologically sorts all the classes involved in the inheritance.

Override this method if you need to change how CPL is computed.
You might not want to change the actual algorithm unless you emulate
different object system, but you can use the method to ensure
certain class is always inherited, for example.
@end deffn

@deffn {Generic function} class-post-initialize class initargs
This generic function is called after all core initialization of @var{class}
is finished, but before the class is ``freezed'', that is, the essential
parts of @var{class} becomes immutable.  If you want to trick
object system in some weird way, override this method.

We assume you know what you are doing, for object system assumes the essential
parts are computed in the standard way.  Messing with them
can easily break the system.
@end deffn


@node Customizing slot access, Method instantiation, Class instantiation, Metaobject protocol
@subsection Customizing slot access
@c NODE スロットアクセスのカスタマイズ


@deffn {Generic Function} compute-slots class
@deffnx {Generic Function} compute-get-n-set class slot-definition
These two generic functions are responsible to determine
what slots a class has, and how each slot is accessed.

In the @code{initialize} method of a class,
@code{compute-slots} is called after the class's
@code{direct-supers}, @code{cpl} and @code{direct-slots} are set.
It must decide what slots the class should have, and what
slot options each slot should have, based on those three piece
of information.  The returned value should have the following
form, and it is used as the value of the @code{slots} slot of the class.

@example
<slots> : (<slot-definition> ...)
<slot-definition> : (<slot-name> . <slot-options>)
<slot-name> : symbol
<slot-options> : keyword-value alternating list.
@end example

After the @code{slots} slot of the class is set by the returned
value from @code{compute-slots},
@code{compute-get-n-set} is called for each slot
to calculate how to access and modify the slot.
The class and the slot definition are the arguments.
It must return either one of the followings:

@table @asis
@item an integer @var{n}
This slot becomes @var{n}-th instance slot.  This is the only way to
allocate a slot per instance.

The base method of @var{compute-get-n-set} keeps track of the current
number of allocated instance slots in the class's @code{num-instance-slots}
slot.  It is not recommended for other specialized methods to use or
change the value of this slot, unless you know a very good reason to
override the object system behavior in deep down.  Usually it is suffice
to call @code{next-method} to let the base method reserve an instance
slot for you.

See the examples below for modifying instance slot access behaviors.

@item a list @code{(@var{get-proc} @var{set-proc} @var{bound?-proc} @var{initializable})}
The @var{get-proc}, @var{set-proc} and @var{bound?-proc} elements are procedures
invoked when this slot of an instance is accessed (either via
@code{slot-ref}/@code{slot-set!}/@code{slot-bound?},
or an accessor method specified by @code{:getter}/@code{:setter} slot options).
The value other than @var{get-proc} may be @code{#f}, and can be omitted
if all the values after it is also @code{#f}.  That is, the simplest
form of this type of return value is a list of one element,
@var{get-proc}.

@itemize @bullet
@item
When this slot is about to be read, @var{get-proc} is called with
an argument, the instance.  The returned value of @var{get-proc} is
the value of the slot.

The procedure may return @code{#<undef>} to indicate the slot is
unbound.  It triggers the @code{slot-unbound} generic function.
(That is, this type of slot cannot have @code{#<undef>} as its value.)

@item
When this slot is about to be written, @var{set-proc} is called
with two arguments, the instance and the new value.  It is called
purely for the side effect; the procedure may change the value
of other slot of the instance, for example.

If this element is @code{#f} or omitted, the slot becomes read-only;
any attempt to write to the slot will raise an error.

@item
When @code{slot-bound?} is called to check whether the slot of
an instance is bound, @var{bound?-proc} is called with
an argument, the instance.  It should return a boolean value
which will be the result of @code{slot-bound?}.

If this element is @code{#f} or omitted, @code{slot-bound?} will
call @var{get-proc} and returns true if it returns
@code{#<undef>}.

@item
The last element, @var{initializable}, is a flag that indicates
whether this slot should be initialized when @code{:init-value}
or @code{:init-form}.
@end itemize

@item A @code{<slot-accessor>} object
Access to this slot is redirected through the returned
slot-accessor object.   See below for more on @code{<slot-accessor>}.
@end table

The value returned by @code{compute-get-n-set} is immediately passed
to @code{compute-slot-accessor} to create a @emph{slot accessor} object,
which encapsulates how to access and modify the slot.

After all slot definitions are processed by @code{compute-get-n-set}
and @code{compute-slot-accessor}, an assoc list of
slot names and @code{<slot-accessor>} objects are stored in the
class's @code{accessors} slot.
@end deffn

@deffn {Generic Function} compute-slot-accessor
@deffnx {Method} compute-slot-accessor (class <class>) slot access-specifier
@var{Access-specifier} is a value returned from
@code{compute-get-n-set}.  The base method creates an instance
of @code{<slot-accessor>} that encapsulates how to
access the given slot.

Created slot accessor objects are stored (as an assoc list using
slot names as keys) in the class's @code{accessors} slot.
Standard slot accessors and mutators, such as @code{slot-ref},
@code{slot-set!}, @code{slot-bound?}, and the slot accessor
methods specified in @code{:getter}, @code{:setter} and @code{:accessor}
slot options, all go through slot accessor object eventually.
Specifically, those functions and methods first looks up
the slot accessor object of the desired slot, then calls
@code{slot-ref-using-accessor} etc.
@end deffn

@deffn {Method} compute-slots (class <class>)
The standard method walks CPL of @var{class} and gathers
all direct slots.  If slots with the same name are found,
the one of a class closer to @var{class} in CPL takes precedence.
@end deffn

@deffn {Method} compute-get-n-set (class <class>) slot
The standard processes the slot definition with the following
slot allocations: @code{:instance}, @code{:class},
@code{each-subclass} and @code{:virtual}.
@end deffn

@defun slot-ref-using-accessor obj slot-accessor
@defunx slot-set-using-accessor! obj slot-accessor value
@defunx slot-bound-using-accessor? obj slot-accessor
@defunx slot-initialize-using-accessor! obj slot-accessor initargs
The low-level slot accessing mechanism.  Every function or
method that needs to read or write to a slot eventually comes
down to one of these functions.

Ordinary programs need not call these functions directly.
If you ever need to call them, you have to be careful not
to grab the reference to @var{slot-accessor} too long; if
@var{obj}'s class is changed or redefined, @var{slot-accessor}
can no longer be used.
@end defun

Here we show a couple of small examples to illustrate how slot access
protocol can be customized.  You can also look at @code{gauche.mop.*}
modules (in the source tree, look under @code{lib/gauche/mop/})
for more examples.

The first example implements the same functionality of
@code{:virtual} slot allocation.  We add @code{:procedural}
slot allocation, which adds @code{:ref}, @code{:set!} and @code{:bound?}
slot options.

@example
(define-class <procedural-slot-meta> (<class>) ())

(define-method compute-get-n-set ((class <procedural-slot-meta>) slot)
  (if (eqv? (slot-definition-allocation slot) :procedural)
    (let ([get-proc   (slot-definition-option slot :ref)]
          [set-proc   (slot-definition-option slot :set!)]
          [bound-proc (slot-definition-option slot :bound?)])
      (list get-proc set-proc bound-proc))
    (next-method)))
@end example

A specialized @code{compute-get-n-set} is defined on a metaclass
@code{<procedural-slot-meta>}.  It checks the slot allocation,
handles it if it is @code{:procedural}, and delegates other
slot allocation cases to @code{next-method}.  This is a typical
way to add new slot allocation by layering.

To use this @code{:procedural} slot, give @code{<procedural-slot-meta>}
to a @code{:metaclass} argument of @code{define-class}:

@example
(define-class <temp> ()
  ((temp-c :init-keyword :temp-c :init-value 0)
   (temp-f :allocation :procedural
           :ref   (lambda (o) (+ (*. (ref o 'temp-c) 9/5) 32))
           :set!  (lambda (o v)
                    (set! (ref o 'temp-c) (*. (- v 32) 5/9)))
           :bound? (lambda (o) (slot-bound? o 'temp-c))))
  :metaclass <procedural-slot-meta>)
@end example

An instance of @code{<temp>} keeps a temperature in both
Celsius and Fahrenheit.  Here's an example interaction.

@example
gosh> (define T (make <temp>))
T
gosh> (d T)
#<<temp> 0xb6b5c0> is an instance of class <temp>
slots:
  temp-c    : 0
  temp-f    : 32.0
gosh> (set! (ref T 'temp-c) 100)
#<undef>
gosh> (d T)
#<<temp> 0xb6b5c0> is an instance of class <temp>
slots:
  temp-c    : 100
  temp-f    : 212.0
gosh> (set! (ref T 'temp-f) 450)
#<undef>
gosh> (d T)
#<<temp> 0xb6b5c0> is an instance of class <temp>
slots:
  temp-c    : 232.22222222222223
  temp-f    : 450.0
@end example

Our next example is a simpler version of @code{gauche.mop.validator}.
We add a slot option @code{:filter}, which takes a procedure
that is applied to a value to be set to the slot.

@example
(define-class <filter-meta> (<class>) ())

(define-method compute-get-n-set ((class <filter-meta>) slot)
  (cond [(slot-definition-option slot :filter #f)
         => (lambda (f)
              (let1 acc (compute-slot-accessor class slot (next-method))
                (list (lambda (o) (slot-ref-using-accessor o acc))
                      (lambda (o v) (slot-set-using-accessor! o acc (f v)))
                      (lambda (o) (slot-bound-using-accessor? o acc))
                      #t)))]
        [else (next-method)]))
@end example

The trick here is to call @code{next-method} and
@code{compute-slot-accessor} to calculate the slot accessor
and wrap it.  See how this metaclass works:

@example
(define-class <foo> ()
  ((v :init-value 0 :filter x->number))
  :metaclass <filter-meta>)

gosh> (define foo (make <foo>))
foo
gosh> (ref foo'v)
0
gosh> (set! (ref foo'v) "123")
#<undef>
gosh> (ref foo'v)
123
@end example





@node Method instantiation, Customizing method application, Customizing slot access, Metaobject protocol
@subsection Method instantiation
@c NODE メソッドのインスタンシエーション

@deffn {Method} make (class <method>) :rest initargs
@end deffn

@node Customizing method application, Customizing class redefinition, Method instantiation, Metaobject protocol
@subsection Customizing method application
@c NODE メソッド適用のカスタマイズ

@deffn {Generic Function} apply-generic gf args
@end deffn

@deffn {Generic Function} sort-applicable-methods gf methods args
@end deffn

@deffn {Generic Function} method-more-specific? method1 method2 classes
@end deffn

@deffn {Generic Function} apply-methods gf methods args
@end deffn

@deffn {Generic Function} apply-method gf method build-next args
@end deffn

@node Customizing class redefinition,  , Customizing method application, Metaobject protocol
@subsection Customizing class redefinition
@c NODE クラスの再定義のカスタマイズ

@deffn {Generic Function} class-redefinition old-class new-class
When a class is redefined (@pxref{Class redefinition}), 
a new class metaobject is instantiated by 
@code{(make @var{metaclass} @var{initargs} @dots{})},
then generic function is called with the old class metaobject and
new class metaobject.  It should transform the information in the
old class into the new class.

The default method, @code{(class-redefinition @var{<class>} @var{<class>})},
takes care of updating all the methods referencing to the old class,
and propagate changes to the superclasses and subclasses.  If you
customize this method, you should call the default method
with @code{next-method} to make sure those basic bookkeeping is done,
or unexpected things can happen.

Class redefinition mutates lots of structures.  If you throw an error
in middle of it, the internal state can be left inconsistent.

Internally, the system uses a single mutex dedicated for the class redefition
so that only one thread can execute it at a time.  You don't need to worry
about other thread stepping on during @code{class-redefinition} method
(Other thread can still be running for other operations, though, so
if you touch objects that can be touched from outside of class redefinition,
you should mutex it.)
@end deffn



@c Local variables:
@c mode: texinfo
@c coding: utf-8
@c end:
@node Library modules - Overview, Library modules - Gauche extensions, Object system, Top
@chapter Library modules - Overview
@c NODE ライブラリモジュール - 概要

In the following chapters, we explain library modules bundled with Gauche's
distribution.
These modules should generally be loaded and imported (usually using @code{use}
- @xref{Using modules}, for details), unless otherwise noted.

Some modules are described as "autoloaded".  That means you don't need
to @code{load} or @code{use} the module explicitly; at the first time
the bindings are used in the program, the module is automatically
loaded and imported.  See @ref{Autoload}, for the details of autoloading.

As the number of bundled libraries grows, it becomes harder
to find the one you need.  If you feel lost, check
out the section @ref{Finding libraries you need}, in which
we categorize libraries by their purposes.

The following four chapters describe bundled modules,
grouped by their names.

@itemize
@item
@ref{Library modules - Gauche extensions} contains a description of
@code{gauche.*} modules, which are more or less considered
the core features of Gauche but separated since less frequently used.
(Some modules are rather ad-hoc, but here for historical reasons).

@item
@ref{Library modules - R7RS standard libraries} explains how Gauche
integrates R7RS into existing Gauche structures.  If you want to
write R7RS-compliant portable programs, you definitely want to
check the first two sections of this chapter.  What follows is
the description of R7RS modules.  The ``small'' part of R7RS
has been frozen, but the ``large'' part--additional libraries--are
still growing.

@item
@ref{Library modules - SRFIs} describes the modules which
provide SRFI functionalities.  They have the names beginning
with @code{srfi-}.
Note that some of SRFI features are built in Gauche core and
not listed here.  @xref{Standard conformance}, for the entire list
of supported SRFIs.

@item
@ref{Library modules - Utilities} describes other modules
---including database interface, filesystem utilities,
network protocol utilities, and more.
@end itemize


There are a few procedures that help your program to check
the existence of certain modules or libraries at run-time.
See @ref{Operations on libraries}, for the details.

@menu
* Finding libraries you need::
* Naming convention of libraries::
* Obsolete and superseded modules::
@end menu

@node Finding libraries you need, Naming convention of libraries, Library modules - Overview, Library modules - Overview
@section Finding libraries you need
@c NODE 必要なライブラリの探し方

Each module is named more or less after what it implements
rather than what it is implemented @emph{for}.  If the module solves
one problem, both are the same.  However, sometimes there
are multiple ways to solve a problem, or one implementation
of an algorithm can solve multiple different problems; thus
it is difficult to name the modules in problem-oriented
(or purpose-oriented) way.

Because of this, it may not be straightforward for a newcomer
to Gauche to find an appropriate Gauche module to solve her problem,
since there may be multiple algorithms to do the job,
and each algorithm can be implemented in different modules.

The modules are also designed in layers; some low-level modules
provide direct interface to the system calls, while some
higher-level ones provide more abstract, easy-to-use interface, possibly
built on top of more than one low-level modules.   Which one
should you use?  Generally you want to use the highest level,
for the very purpose of libraries are to provide easy, abstract
interface.  However there are times that you have to break
the abstraction and to go down to tweak the machinery in
the basement; then you need to use low-level modules directly.

The purpose of this section is to group the libraries by
their purposes.  Each category lists relevant modules with
brief descriptions.

@menu
* Library directory - data containers::
* Library directory - strings and characters::
* Library directory - data exchange::
* Library directory - files::
* Library directory - processes and threads::
* Library directory - networking::
* Library directory - input and output::
* Library directory - time::
* Library directory - bits and bytes::
@end menu

@node Library directory - data containers, Library directory - strings and characters, Finding libraries you need, Finding libraries you need
@subsection Library directory - data containers
@c NODE ライブラリディレクトリ - データコンテナ

@subsubheading Generic container operations

Some data containers have similar properties; for example,
lists, vectors and hash tables can be seen as a collection
of data.  So it is handy to have generic operators, such
as applying a procedure to all the elements.

Gauche provides such mechanism to a certain degree, mainly using
its object system.

@itemize @bullet
@item
@emph{Collection} - Generic functions applicable for unordered
set of values.  @xref{Collection framework}.
@item
@emph{Sequence} - Generic functions applicable for ordered set
of values.  @xref{Sequence framework}.
@item
@emph{Dictionary} - Generic functions to handle dictionary, that is,
a mapping from keys to values.  @xref{Dictionary framework}.
@item
@emph{Relation} - Generic functions to handle relations
(in a sense of Codd's definition).  @xref{Relation framework}.
@item
@emph{Comprehension} - This is a collection of macros very handy
to construct and traverse collections/sequences in concise code.
@xref{Eager comprehensions}.
@end itemize

@subsubheading Container implementations

@itemize @bullet
@item
@emph{List} - the universal data structure.  You want to check
@ref{Pairs and lists} and @ref{R7RS lists}
@item
@emph{Vector} - a one-dimensional array of arbitrary Scheme values.
See @ref{Vectors} and @ref{R7RS vectors}.
If you need a wide range of index, but the actual data
is sparse, you might want to look at @ref{Sparse vectors}.
@item
@emph{Uniform vector} - a special kind of vectors that can hold
limited types of values (e.g. integers representable in 8bits).
It tends to be used in performance
sensitive applications, such as graphics.  See @ref{Uniform vectors}.
@item
@emph{Array} - multi-dimensional arrays that can hold
arbitrary Scheme values.  See @ref{Arrays}.
@item
@emph{Uniform array} - multi-dimensional arrays that can hold
limited types of values.  This is also supported by @ref{Arrays}.
@item
@emph{String} - a sequence of characters.  See @ref{Strings}
and @ref{String library}.  Gauche handles multibyte strings---
see @ref{Multibyte strings} for the details.
@item
@emph{Character set} - a set of characters.  See @ref{Character sets}
and @ref{R7RS character sets}.
@item
@emph{Hash table} - hash tables.  See @ref{Hashtables}.
For very large hash tables (millions of entries),
@ref{Sparse tables} may provide better memory footprint.
@item
@emph{Balanced tree} - If you need to order keys in a dictionary,
you can use treemaps.  See @ref{Treemaps}.
@item
@emph{Immutable map} - Sometimes immutable dictionary is handy.  Internally
it implements a functional balanced tree.  See @ref{Immutable map}.
@item
@emph{Queue} - Both fast and thread-safe queues are provided in
@ref{Queue}.  Thread-safe queues can also be used as synchronized
messaging channel.
@item
@emph{Heap} - See @ref{Heap}.
@item
@emph{Ring buffer} - Space-efficient ring buffer.  See @ref{Ring buffer}.
@item
@emph{Cache} - Various cache algorithm implementations.
See @ref{Cache}.
@item
@emph{Record} - a simple data structure.  Although Gauche's object
system can be used to define arbitrary data structures, you might
want to look at @ref{Record types} and @ref{SLIB-compatible record type},
for they are more portable and potentially more efficient.
@item
@emph{Stream} - you can implement cool lazy algorithms with it.
See @ref{Stream library}.
@item
@emph{Trie} - Another tree structure for efficient common-prefix
search.  See @ref{Trie}.
@item
@emph{Database interface} - dbm interface can be used as a
persistent hash table; see @ref{Generic DBM interface}.
For generic RDBMS interface, see @ref{Database independent access layer}.
@end itemize

@node Library directory - strings and characters, Library directory - data exchange, Library directory - data containers, Finding libraries you need
@subsection Library directory - string and character
@c NODE ライブラリディレクトリ - 文字列と文字

Basic string operations are covered in
@ref{Strings} and @ref{String library}.
A string is also a sequence of characters, so you can
apply methods in @ref{Collection framework} and
@ref{Sequence framework}.

Character and character set operations are covered in
@ref{Characters}, @ref{Character sets}, and @ref{R7RS character sets}.

If you scan or build strings sequentially, do not use index
access.  String ports (see @ref{String ports}) provides more efficient,
and elegant way.

You can use regular expressions to search and extract
character sequences from strings; see @ref{Regular expressions}.

If you need to deal with low-level (i.e. byte-level)
representation of strings, @ref{Uniform vectors} has some
tools to convert strings and byte vectors back and forth.

Are you dealing with a structure higher than a mere sequence
of characters?  Then take a look at  @code{text.*} modules.
@ref{Parsing input stream} has some basic
scanners.  @ref{Transliterate characters} implements a
feature similar to Unix's @code{tr(1)}.
You can take @code{diff} of two texts; see
@ref{Calculate difference of text streams}.
And if you want to construct large text from string fragments,
do not use @code{string-append}---see @ref{Lazy text construction}.

Last but not least, Gauche has support of various character
encoding schemes.  See @ref{Character code conversion} for
the basic utilities.  Most higher-level functions such as
@code{open-input-file} can take @code{:encoding} keyword argument
to perform character conversion implicitly.  Also see
@ref{Multibyte scripts} if you write Scheme program in
non-ASCII characters.  If you want to process Gauche source code
which may contain "encoding" magic comment, see @ref{Coding-aware ports}.
Gauche also has GNU gettext compatible module (@ref{Localized messages})
if you need localization.


@node Library directory - data exchange, Library directory - files, Library directory - strings and characters, Finding libraries you need
@subsection Library directory - data exchange
@c NODE ライブラリディレクトリ - データ交換

Most useful programs need to communicate with outside world
(other programs or humans).  That involves reading the external data
into your program understanding whatever format the data is in, and
also writing the data in the format the others can understand.

Lots of network-related external formats are defined in RFC,
and there are corresponding @code{rfc.*} module that handle
some of them.  See @ref{RFC822 message parsing}, for example,
to handle the pervasive RFC2822 message format.
Or, JSON can be handled by @ref{JSON parsing and construction}.

When you exchange table-formatted data, one of the easiest way
may be the plain text, one row per line, and columns are separated
by some specific characters (e.g. comma).  See @ref{CSV tables} for
basic parser/writer for them.

Oh, and nowadays every business user wants XML, right?  You know
they are just S-expressions with extra redundancy and pointy
parentheses.  So why don't you read XML as if they're S-exprs,
process them with familiar cars and cdrs and maps, then write them
out with extra redundancy and pointy parens?
Module @code{sxml.ssax} (@ref{Functional XML parser})
implements SAX XML parser, with which you
can parse XML and process them on the fly, or convert it to
SXML, S-expression XML.  You can query SXML using
SXPath, an XPath counterparts of S-expression (@ref{SXML query language}).
You can output all kinds of XML and HTML using the SXML serializer
(@ref{Serializing XML and HTML from SXML}).

(But you know most web services nowadays also talks JSON,
and that's much lighter and handier than XML.
See @ref{JSON parsing and construction}).

It is planned that various file format handling routines would
be available as @code{file.*} modules, though we have none ready
yet.  If you plan to write one, please go ahead and let us know!

@node Library directory - files, Library directory - processes and threads, Library directory - data exchange, Finding libraries you need
@subsection Library directory - files
@c NODE ライブラリディレクトリ - ファイル

Files and directories.  Roughly speaking, there are two places
you want to look at.

@ref{Filesystems}, in the core, has
routines close to the underlying OS provides.  If you have
experience with Unix system programming you'll find familiar
function names there.   The @code{fcntl} functionality is
splitted to @code{gauche.fcntl} (@ref{Low-level file operations}), FYI.

Also you definitely want to look at @code{file.util}
(@ref{Filesystem utilities}), which implements higher-level
routines on top of system-level ones.


@node Library directory - processes and threads, Library directory - networking, Library directory - files, Finding libraries you need
@subsection Library directory - processes and threads
@c NODE ライブラリディレクトリ - プロセスとスレッド

Process-related routines also come in two levels.

The @code{gauche.process} module provides
high-level routines (@ref{High-level process interface});
you can pipe the data into and out of child processes easily, for example.

Gauche core provides the primitive @code{fork} and @code{exec} interface
as well as the convenient @code{system} call
(see @ref{Process management}).  Use them when you want a precise
control over what you're doing.

Gauche has preemptive threads on most Unix platforms including OSX.
Check out @ref{Threads} for the basic thread support, including
primitive mutexes.  The @code{data.queue} module (@pxref{Queue})
provides thread-safe queue that can also be handy for synchronization.
Thread pool is available in @code{control.thread-pool} (@pxref{Thread pools}).


@node Library directory - networking, Library directory - input and output, Library directory - processes and threads, Finding libraries you need
@subsection Library directory - networking
@c NODE ライブラリディレクトリ - ネットワーク

We have multi-layer abstraction here.  At the bottom, we have
APIs corresponding to socket-level system calls.  In the middle,
a convenience library that automates host name lookups, connection
and shutdown, etc.  On top of them we have several modules that
handles specific protocols (e.g. http).

The @code{gauche.net} module (@ref{Networking}) provides the bottom
and middle layer.  For the top layer, look for @code{rfc.*} modules,
e.g. @code{rfc.http} (@ref{HTTP}).
More protocol support is coming (there are @code{rfc.ftp} and
@code{rfc.imap4} written by users, which are waiting for being
integrated into Gauche---maybe in next release).

There's a plan of even higher level of libraries, under the name
@code{net.*}, which will abstract more than one network protocols.
The planned ones include sending emails, or
universal resource access by uri.  Code contributions are welcome.

@node Library directory - input and output, Library directory - time, Library directory - networking, Finding libraries you need
@subsection Library directory - input and output
@c NODE ライブラリディレクトリ - 入出力

@node Library directory - time, Library directory - bits and bytes, Library directory - input and output, Finding libraries you need
@subsection Library directory - time
@c NODE ライブラリディレクトリ - 時間

@node Library directory - bits and bytes,  , Library directory - time, Finding libraries you need
@subsection Library directory - bits and bytes
@c NODE ライブラリディレクトリ - ビットとバイト

@subsubheading Binary I/O

As the bottom level,
Gauche includes primitive byte I/O (@code{read-byte}, @code{write-byte})
as well as block I/O (@code{read-uvector}, @code{read-uvector!}, @code{write-uvector}) in its core.
(See @ref{Reading data}, @ref{Output}, and @ref{Uvector block I/O}).

As the middle level, the module @code{binary.io}
(@ref{Binary I/O}) has routines to retrieve specific datatype
with optional endian specification.

And as the top level, the module @code{binary.pack}
(@ref{Packing binary data}) allows packing and unpacking structured
binary data, a la Perl's @code{pack}/@code{unpack}.

@subsubheading Bit manipulation

Gauche core provides basic bitshift and mask operations
(@pxref{Basic bitwise operations}).
SRFI-151 has comprehensive bitwise operations
(@pxref{R7RS bitwise operations}).

@node Naming convention of libraries, Obsolete and superseded modules, Finding libraries you need, Library modules - Overview
@section Naming convention of libraries
@c NODE ライブラリの命名規則

The following table summarizes naming categories of the modules,
including external ones and planned ones.

@table @code
@item binary.*
Utilities to treat binary data.

@item compat.*
Provides compatibility layers.

@item data.*
Implementations of various data structures.

@item dbi.*, dbd.*
Database independent interface layer and drivers.

@item dbm.*
DBM interface

@item gauche.*
Stuffs more or less considered as Gauche core features.

@item gl.*
OpenGL binding and related libraries (external package).

@item gtk.*
GTk+ binding and related libraries (external package).

@item file.*
Manipulating files and directories.

@item lang.*
Language-related libraries, artificial and/or natural (planned).

@item math.*
Mathematics.

@item os.*
Features for specific OSes.

@item rfc.*
Implementations of net protocols defined in RFC's.

@item srfi-*
SRFI implementations.

@item sxml.*
SXML libraries.

@item text.*
Libraries dealing with text data.

@item util.*
Generic implementations of various algorithms.

@item www.*
Implementations of various protocols and formats mainly used in WWW.
@end table

@node Obsolete and superseded modules,  , Naming convention of libraries, Library modules - Overview
@section Obsolete and superseded modules
@c NODE 廃止あるいは置き換えられたモジュール

During the course of development of Gauche,
some modules have been renamed, merged, or dissolved into the core.
Also, some SRFI libraries become standard and given a new name,
or superseded with a newer SRFI library.

We list such modules here for the reference.
New code shouldn't use these modules, although they are kept in
the distribution so that legacy code can keep running.

@subheading Obsolete modules

@deftp {Module} text.unicode
@mdindex text.unicode
Renamed to @code{gauche.unicode}.  @xref{Unicode utilities}.
@end deftp


@deftp {Module} util.list
@mdindex util.list
Dissolved into the core.  No longer needed.
@end deftp

@deftp {Module} util.queue
@mdindex util.queue
Renamed to @code{data.queue}.  @xref{Queue}.
@end deftp

@deftp {Module} util.rbtree
@mdindex util.rbtree
@clindex rbtree
@findex make-rbtree
@findex rbtree?
@findex rbtree-copy
@findex rbtree-empty?
@findex rbtree-num-entries
@findex rbtree-exists?
@findex rbtree-get
@findex rbtree-put!
@findex rbtree-delete!
@findex rbtree-update!
@findex rbtree-push!
@findex rbtree-pop!
@findex rbtree-min
@findex rbtree-max
@findex rbtree-extract-min!
@findex rbtree-extract-max!
@findex rbtree-fold
@findex rbtree-fold-right
@findex rbtree-keys
@findex rbtree-values
@findex rbtree->alist
@findex alist->rbtree
Incorporated into the core as built-in object @code{<tree-map>}.
@xref{Treemaps}.

The following procedures are aliases of the ones with replacing
@code{rbtree} for @code{tree-map}, e.g. @code{rbtree-get} is
the same as @code{tree-map-get}.

@example
make-rbtree       rbtree?           rbtree-get        rbtree-put!
rbtree-delete!    rbtree-exists?    rbtree-empty?     rbtree-update!
rbtree-push!      rbtree-pop!       rbtree-num-entries rbtree->alist
alist->rbtree     rbtree-keys       rbtree-values     rbtree-copy
rbtree-fold       rbtree-fold-right
@end example

The following procedures are similar to @code{tree-map-min},
@code{tree-map-max}, @code{tree-map-pop-min!} and @code{tree-map-pop-max!},
respectively, except that the @code{rbtree-*} version takes an optional
default argument and returns it when the tree is empty, and raise an
error if no default argument is provided and tree is empty.  (The tree-map
version just returns @code{#f} for the empty tree.)

@example
rbtree-min           rbtree-max
rbtree-extract-min!  rbtree-extract-max!
@end example

The following procedure doesn't have corresponding API in tree-map.
It checks internal consistency of the given tree-map.

@example
rbtree-check
@end example
@end deftp

@deftp {Module} util.sparse
@mdindex util.sparse
Renamed to @code{data.sparse}.  @xref{Sparse data containers}.
@end deftp

@deftp {Module} util.trie
@mdindex util.trie
Renamed to @code{data.trie}.  @xref{Trie}.
@end deftp

@subheading Superseded modules

@c Note: Don't use mdindex below, for the entries of these modules
@c are still in the modsrfi.texi.

@deftp {Module} srfi-1
SRFI-1 (List library) has become a part of R7RS large, as @code{scheme.list}.
@xref{R7RS lists}.
@end deftp

@deftp {Module} srfi-14
SRFI-14 (Character-set library) has become a part of R7RS large,
as @code{scheme.charset}.
@xref{R7RS character sets}.
@end deftp

@deftp {Module} srfi-43
Vector library (Legacy) - 
this module is effectively superseded by R7RS and @code{srfi-133}.
@xref{Vectors}, and @pxref{R7RS vectors}.
@end deftp

@deftp {Module} srfi-60
Integers as bits - this module is superseded by @code{srfi-151}.
@xref{R7RS bitwise operations}.
@end deftp

@deftp {Module} srfi-69
Basic hash tables - this module is superseded by R7RS @code{scheme.hash-table}.
@xref{R7RS hash tables}.
@end deftp

@deftp {Module} srfi-111
SRFI-111 (Boxes) has become a part of R7RS @code{scheme.box} module.
@xref{R7RS boxes}.
@end deftp

@deftp {Module} srfi-113
SRFI-113 (Sets and bags) has become a part of R7RS @code{scheme.set}.
@xref{R7RS sets}.
@end deftp

@deftp {Module} srfi-114
Comparators - R7RS favored srfi-128 over this srfi
to make @code{scheme.comparator} (@ref{R7RS comparators}),
so adoption of this srfi may not be as wide.

Note that, in Gauche, a native comparator object can be used for
srfi-114 procedures, and this module provides some useful additional
utilities.  It's ok to use this module if portability isn't a big issue.
@end deftp

@deftp {Module} srfi-117
SRFI-117 has become R7RS's @code{scheme.list-queue}.
@xref{R7RS list queues}.
@end deftp

@deftp {Module} srfi-127
SRFI-127 has become R7RS's @code{scheme.lseq}.
@xref{R7RS lazy sequences}.
@end deftp

@deftp {Module} srfi-132
@mdindex srfi-132
SRFI-132 has become R7RS's @code{scheme.sort}.
@xref{R7RS sort}.
@end deftp

@deftp {Module} srfi-133
SRFI-133 has become R7RS's @code{scheme.vector}.
@xref{R7RS vectors}.
@end deftp

@c Local variables:
@c mode: texinfo
@c coding: utf-8
@c end:
@node Library modules - Gauche extensions, Library modules - R7RS standard libraries, Library modules - Overview, Top
@chapter Library modules - Gauche extensions
@c NODE ライブラリモジュール - Gauche拡張モジュール

@c ----------------------------------------------------------------------
@menu
* Arrays::                      gauche.array
* Importing gauche built-ins::  gauche.base
* Generating C code::           gauche.cgen
* Character code conversion::   gauche.charconv
* Collection framework::        gauche.collection
* Configuration parameters::    gauche.config
* Generating build files::      gauche.configure
* Connection framework::        gauche.connection
* Dictionary framework::        gauche.dictionary
* Low-level file operations::   gauche.fcntl
* Generators::                  gauche.generator
* Hooks::                       gauche.hook
* Interactive session::         gauche.interactive
* Lazy sequence utilities::     gauche.lazy
* Listener::                    gauche.listener
* User-level logging::          gauche.logger
* Propagating slot access::     gauche.mop.propagate
* Singleton::                   gauche.mop.singleton
* Slot with validator::         gauche.mop.validator
* Networking::                  gauche.net
* Package metainformation::     gauche.package
* Parameters (extra)::          gauche.parameter
* Parsing command-line options::  gauche.parseopt
* Partial continuations::       gauche.partcont
* High-level process interface::  gauche.process
* Record types::                gauche.record
* Reloading modules::           gauche.reload
* Simple dispatcher::           gauche.selector
* Sequence framework::          gauche.sequence
* Syslog::                      gauche.syslog
* Terminal control::            gauche.termios
* Unit testing::                gauche.test
* Threads::                     gauche.threads
* Measure timings::             gauche.time
* Unicode utilities::           gauche.unicode
* Uniform vector library::      gauche.uvector
* Comparing version numbers::   gauche.version
* Virtual ports::               gauche.vport
@end menu

@node Arrays, Importing gauche built-ins, Library modules - Gauche extensions, Library modules - Gauche extensions
@section @code{gauche.array} - Arrays
@c NODE 配列, @code{gauche.array} - 配列

@deftp {Module} gauche.array
@mdindex gauche.array
This module provides multi-dimensional array data type and operations.
The primitive API follows SRFI-25.
Besides a generic srfi-25 array that can store any Scheme objects,
this module also provides array classes that stores numeric objects
efficiently, backed up by
homogeneous numeric vectors (@pxref{Uniform vectors}).
An external representation of arrays, using SRFI-10 mechanism,
is also provided.

Each element of an @var{N}-dimensional array can be accessed
by @var{N} integer indices,
@code{[ @var{i_0} @var{i_1} @dots{} @var{i_N-1} ]}.
An array has associated @var{shape} that knows lower-bound @var{s_k} and
upper-bound @var{e_k} of index of each dimension, where
@var{s_k} <= @var{e_k}, and the index @var{i_k} must satisfy
@var{s_k} <= @var{i_k} < @var{e_k}.
(Note: it is allowed to have @var{s_k} == @var{e_k}, but such array can't
store any data.  It is also allowed to have zero-dimensional array,
that can store a single data.).
The shape itself is a [ @var{D} x 2 ] array, where @var{D} is the
dimension of the array which the shape represents.

You can pass index(es) to array access primitives in a few ways;
each index can be passed as individual argument,
or can be 'packed' in a vector or one-dimensional array.
In the latter case, such a vector or an array is called an "index object".
Using a vector is efficient in Gauche when you iterate over the elements
by changing the vector elements, for it won't involve memory allocation.

Arrays can be compared by the @code{equal?} procedure.
@code{Equal?} returns @code{#t} if two arrays have the same
shape and their corresponding elements are the same
in the sense of @code{equal?}.

Internally, an array consists of a backing storage and a mapping procedure.
A backing storage is an object of aggregate type that can be accessed
by an integer index.  A mapping procedure takes
multi-dimensional indices (or index object) and
returns a scalar index into the backing storage.
@end deftp

@deftp {Class} <array-base>
@clindex array-base
@{@t{gauche.array}@}
An abstract base class of array types, that implements generic operations
on the array.   To create an array instance,
you should use one of the following concrete array classes.
@end deftp

@deftp {Class} <array>
@deftpx {Class} <u8array>
@deftpx {Class} <s8array>
@deftpx {Class} <u16array>
@deftpx {Class} <s16array>
@deftpx {Class} <u32array>
@deftpx {Class} <s32array>
@deftpx {Class} <u64array>
@deftpx {Class} <s64array>
@deftpx {Class} <f16array>
@deftpx {Class} <f32array>
@deftpx {Class} <f64array>
@clindex array
@clindex u8array
@clindex s8array
@clindex u16array
@clindex s16array
@clindex u32array
@clindex s32array
@clindex u64array
@clindex s64array
@clindex f16array
@clindex f32array
@clindex f64array
@{@t{gauche.array}@}
Concrete array classes.  The @code{<array>} class implements srfi-25
compatible array, i.e. an array that can store any Scheme objects.
The @code{<u8array>} class through @code{<f64array>} classes uses
a @code{<u8vector>} through @code{<f64vector>} as a backing storage,
and can only store a limited range of integers or inexact real numbers,
but they are space efficient.
@end deftp


@deftp {Reader Syntax} @code{#,(<array> @var{shape} @var{obj} @dots{})}
An array is written out in this format.  (Substitute @code{<array>} for
@code{<u8array>} if the array is @code{<u8array>}, etc.)
@var{shape} is a list
of even number of integers, and each 2@var{n}-th integer
and 2@var{n}+1-th integer specifies the
inclusive lower-bound and exclusive upper-bound of @var{n}-th dimension,
respectively.  The following @var{obj} @dots{} are the values in the array
listed in row-major order.

When read back, this syntax is read as an array with the same shape
and content, so it is @code{equal?} to the original array.

@example
; an array such that:
;   8 3 4
;   1 5 9
;   6 7 2
#,(<array> (0 3 0 3) 8 3 4 1 5 9 6 7 2)

; a 4x4 identity matrix
#,(<array> (0 4 0 4) 1 0 0 0 0 1 0 0 0 0 1 0 0 0 0 1)
@end example
@end deftp

@defun array? obj
[SRFI-25]
@{@t{gauche.array}@}
Returns @code{#t} if @var{obj} is an array, @code{#f} otherwise.
It is equivalent to @code{(is-a? obj <array-base>)}.
@end defun

@defun make-array shape :optional init
[SRFI-25]
@{@t{gauche.array}@}
Creates an array of shape @var{shape}.
@var{Shape} must be a [ @var{D} x 2 ] array, and for each @var{k}
(0 <= @var{k} < @var{D}), the [ @var{k} 0 ] element must be less than or
equal to the [ @var{k} 1] element.
If @var{init} is given, all the elements are initialized by it.
Otherwise, the initial value of the elements are undefined.

@example
(make-array (shape 0 2 0 2 0 2) 5)
 @result{} #,(<array> (0 2 0 2 0 2) 5 5 5 5 5 5 5 5)
@end example
@end defun

@defun make-u8array shape :optional init
@defunx make-s8array shape :optional init
@findex make-u16array
@findex make-s16array
@findex make-u32array
@findex make-s32array
@findex make-u64array
@findex make-s64array
@findex make-f16array
@dots{}
@end defun
@defun make-f32array shape :optional init
@defunx make-f64array shape :optional init
@{@t{gauche.array}@}
Like @code{make-array}, but creates and returns an uniform numeric array.
@end defun

@defun array-copy array
@{@t{gauche.array}@}
Returns a copy of @var{array}, with the same class, shape and
content.
@end defun

@defun shape bound @dots{}
[SRFI-25]
@{@t{gauche.array}@}
Takes even number of exact integer arguments, and returns
a two-dimensional array that is suitable for representing the shape
of an array.

@example
(shape 0 2 1 3 3 5)
 @result{} #,(<array> (0 3 0 2) 0 2 1 3 3 5)

(shape)
 @result{} #,(<array> (0 0 0 2))
@end example
@end defun

@defun array shape init @dots{}
[SRFI-25]
@{@t{gauche.array}@}
Creates an array of shape @var{shape}, initializing its elements by
@var{init} @dots{}.

@example
(array (shape 0 2 1 3) 'a 'b 'c 'd)
 @result{} #,(<array> (0 2 1 3) a b c d)
@end example
@end defun

@defun u8array shape init @dots{}
@defunx s8array shape init @dots{}
@findex u16array
@findex s16array
@findex u32array
@findex s32array
@findex u64array
@findex s64array
@findex f16array
@dots{}
@end defun
@defun f32array shape init @dots{}
@defunx f64array shape init @dots{}
@{@t{gauche.array}@}
Like @code{array}, but creates and returns an uniform numeric array
initialized by @var{init} @dots{}.

@example
(u8array (shape 0 2 0 2) 1 2 3 4)
 @result{} #,(<u8array> (0 2 0 2) 1 2 3 4)
@end example
@end defun

@defun array-rank array
[SRFI-25]
@{@t{gauche.array}@}
Returns the number of dimensions of an array @var{array}.

@example
(array-rank (make-array (shape 0 2 0 2 0 2))) @result{} 3
(array-rank (make-array (shape))) @result{} 0
@end example
@end defun

@defun array-shape array
@{@t{gauche.array}@}
Returns a shape array of @var{array}.
@end defun

@defun array-start array dim
@defunx array-end array dim
@defunx array-length array dim
[SRFI-25+]
@{@t{gauche.array}@}
@code{Array-start} returns the inclusive lower bound of index of
@var{dim}-th dimension of an array @var{array}.
@code{Array-end} returns the exclusive upper bound.
And @code{array-length} returns the difference between two.
@code{Array-start} and @code{array-end} are defined in SRFI-25.

@example
(define a (make-array (shape 1 5 0 2)))

(array-start a 0)  @result{} 1
(array-end a 0)    @result{} 5
(array-length a 0) @result{} 4
(array-start a 1)  @result{} 0
(array-end a 1)    @result{} 2
(array-length a 1) @result{} 2
@end example
@end defun

@defun array-size array
@{@t{gauche.array}@}
Returns the total number of elements in the array @var{array}.

@example
(array-size (make-array (shape 5 9 1 3))) @result{} 8
(array-size (make-array (shape))) @result{} 1
(array-size (make-array (shape 0 0 0 2))) @result{} 0
@end example
@end defun

@defun array-ref array k @dots{}
@defunx array-ref array index
[SRFI-25]
@{@t{gauche.array}@}
Gets the element of array @code{array}.  In the first form,
the element is specified by indices @var{k} @dots{}.
In the second form, the element is specified by an index object
@var{index}, which must be a vector or an one-dimensional array.
@end defun

@defun array-set! array k @dots{} value
@defunx array-set! array index value
[SRFI-25]
@{@t{gauche.array}@}
Sets the element of array @var{array} to @var{value}.  In the first form,
the element is specified by indices @var{k} @dots{}.
In the second form, the element is specified by an index object
@var{index}, which must be a vector or an one-dimensional array.
@end defun

@defun share-array array shape proc
[SRFI-25]
@{@t{gauche.array}@}
Creates and returns a new array of shape @var{shape}, that shares
the backing storage with the given array @var{array}.
The procedure @var{proc} maps the indices of the new array to
the indices to the original array, i.e. @var{proc} must be a @var{n}-ary
procedure that returns @var{m} values, where @var{n} is the dimension
of the new array and @var{m} is the one of the original array.
Furthermore, @var{proc} must be an affine function; each mapping
has to be a linear combination of input arguments plus optional constant.
(@code{Share-array} optimizes the mapping function based on the affinity
assumption, so @var{proc} won't be called every time the new array
is accessed).
@end defun

@defun array-for-each-index array proc :optional index
@{@t{gauche.array}@}
Calls @var{proc} with every index of @var{array}.
If no @var{index} argument is provided, @var{proc} is called
as @code{(@var{proc} @var{i} @var{j} @var{k} @dots{})}, in which
(@var{i},@var{j},@var{k},@dots{}) walks over the index.
It begins from the least index value of each dimension, and
latter dimension is incremented faster.

@example
gosh> (define a (array (shape 0 2 0 2) 1 2 3 4))
a
gosh> a
#,(<array> (0 2 0 2) 1 2 3 4)
gosh> (array-for-each-index a (^(i j) (print i","j)))
0,0
0,1
1,0
1,1
@end example

This form of passing indexes is simple but not very efficient, though.
For better performance,
you can pass an index object to an optional
argument @var{index},
which is modified for each index and passed to @var{proc}.
The index object must be mutable, and
either a vector, an one-dimensional array, an s8vector, an s16vector
or an s32vector.  The length of the index object must match the
rank of the array.  Using index object is efficient since the loop
won't allocate.  Don't forget that the index object is destructively
modified within the loop.

@example
gosh> (array-for-each-index a (cut format #t "~s\n" <>) (vector 0 0))
#(0 0)
#(0 1)
#(1 0)
#(1 1)

gosh> (array-for-each-index a (cut format #t "~s\n" <>) (s8vector 0 0))
#s8(0 0)
#s8(0 1)
#s8(1 0)
#s8(1 1)
@end example

The procedure returns an unspecified value.
@end defun

@defun shape-for-each shape proc :optional index
@{@t{gauche.array}@}
Calls @var{proc} with all possible indexes represented by the shape
@var{shape}.
The optional @var{index} argument works the same
way as @code{array-for-each-index}.  Returns an unspecified value.

@example
gosh> (shape-for-each (shape 0 2 0 2) (^(i j) (print i","j)))
0,0
0,1
1,0
1,1
@end example
@end defun

@defun tabulate-array shape proc :optional index
@{@t{gauche.array}@}
Calls @var{proc} over each index represented by the shape @var{shape},
and creates an array from the result of @var{proc}.  The optional
index object can be used in the same way as @code{array-for-each-index}.
The following example creates an identity matrix of the given shape:

@example
(tabulate-array (shape 0 3 0 3) (^(i j) (if (= i j) 1 0)))
  @result{} #,(<array> (0 3 0 3) 1 0 0 0 1 0 0 0 1)
@end example
@end defun

@defun array-retabulate! array proc :optional index
@defunx array-retabulate! array shape proc :optional index
@{@t{gauche.array}@}
Calls @var{proc} over each index of the given @var{array}, and
modifies the array's element by the returned value of @var{proc}.
The optional index object can be used in
the same way as @code{array-for-each-index}.
The second form takes a shape; it must match
the @var{array}'s shape.  It is redundant, but may allow some
optimization in future in case @var{shape} is a literal.
Returns an unspecified value.
@end defun

@defun array-map proc array0 array1 @dots{}
@defunx array-map shape proc array0 array1 @dots{}
@{@t{gauche.array}@}
The arguments @var{array0}, @var{array1}, @dots{} must be arrays
with the same shape.  For each set of corresponding elements of
the input arrays, @var{proc} is called, and a new array of the
same shape is created by the returned values.
The second form takes a shape argument, which must match the
shape of input array(s).  It is redundant, but may allow some
optimization in future in case @var{shape} is a literal.

@example
(array-map - (array (shape 0 2 0 2) 1 2 3 4))
  @result{} #,(<array> (0 2 0 2) -1 -2 -3 -4)
@end example
@end defun

@defun array-map! array proc array0 array1 @dots{}
@defunx array-map! array shape proc array0 array1 @dots{}
@{@t{gauche.array}@}
Like @code{array-map}, but the results of @var{proc} are stored by the
given @var{array}, whose shape must match the shape of input array(s).
Returns unspecified value.
@end defun

@defun array->vector array
@defunx array->list array
@{@t{gauche.array}@}
Returns a fresh vector or a fresh list of all elements in @var{array}.

@example
(array->vector
 (tabulate-array (shape 1 3 1 4)
                 (^(i j) (+ (* 10 i) j))))
 @result{} #(11 12 13 21 22 23)
@end example
@end defun

@defun array-concatenate a b :optional dimension
@{@t{gauche.array}@}
Concatenates arrays at the specified dimension.  The sizes of the
specified dimension of two arrays must match, although the shapes
can be different.   Arrays can be of any ranks, but two ranks must
match.

@example
;;  [a b]              [a b]
;;  [c d] (+)       => [c d]
;;            [e f]    [e f]
(array-concatenate
 (array (shape 0 2 0 2) 'a 'b 'c 'd)
 (array (shape 0 1 0 2) 'e 'f))
 @result{} #,(<array> (0 3 0 2) a b c d e f)

;;  [a b]     [e]    [a b e]
;;  [c d] (+) [f] => [c d f]
(array-concatenate
 (array (shape 0 2 0 2) 'a 'b 'c 'd)
 (array (shape 0 2 0 1) 'e 'f)
 1)
 @result{} #,(<array> (0 2 0 3) a b e c d f)

;; The index range can differ, as far as the sizes match
(array-concatenate
 (array (shape 0 2 0 2) 'a 'b 'c 'd)
 (array (shape 1 3 0 1) 'e 'f) 1)
 @result{} #,(<array> (0 2 0 3) a b e c d f)
@end example
@end defun

@defun array-transpose array :optional dim1 dim2
@{@t{gauche.array}@}
The given array must have a rank greater than or equal to 2.
Transpose the array's @var{dim1}-th dimension and
@var{dim2}-th dimension.  The default is 0 and 1.
@end defun

@defun array-rotate-90 array :optional dim1 dim2
@{@t{gauche.array}@}
The given array must have a rank greater than or equal to 2.
We regard the array as a matrix with @var{dim1}-th dimension
as rows and @var{dim2}-th dimension as columns, and returns
a fresh array whose content is filled by @emph{rotating}
@var{array} 90 degree clockwise.   The defaults of
@var{dim1} and @var{dim2} are 0 and 1, respectively.

@example
;; [1 2 3]      [4 1]
;; [4 5 6]  =>  [5 2]
;;              [6 3]
(array-rotate-90 (array (shape 0 2 0 3) 1 2 3 4 5 6))
 @result{} #,(<array> (0 3 0 2) 4 1 5 2 6 3)
@end example

If @var{array} has a rank greater than 2, the array is
treated as a matrix of subarrays.
@end defun

@defun array-flip array :optional dimension
@defunx array-flip! array :optional dimension
@{@t{gauche.array}@}
Flips the content of the array across the @var{dimension}-th dimension.
(default is 0).   @code{array-flip!} modifies the content of @var{array}
and return it.  @code{array-flip} doesn't modify @var{array} but creates
a fresh array with the flipped content and returns it.

@example
;; [1 2 3]  =>  [4 5 6]
;; [4 5 6]      [1 2 3]
(array-flip (array (shape 0 2 0 3) 1 2 3 4 5 6))
 @result{} #,(<array> (0 2 0 3) 4 5 6 1 2 3)

;; [1 2 3]  =>  [3 2 1]
;; [4 5 6]      [6 5 4]
(array-flip (array (shape 0 2 0 3) 1 2 3 4 5 6) 1)
 @result{} #,(<array> (0 2 0 3) 3 2 1 6 5 4)
@end example
@end defun

@defun identity-array dimension :optional class
@{@t{gauche.array}@}
Returns a fresh identity array of rank 2, with the given dimension.
You can pass one of array classes to @var{class} to make the result
the instance of the class; the default class is @code{<array>}.

@example
(identity-array 3)
 @result{} #,(<array> (0 3 0 3) 1 0 0 0 1 0 0 0 1)

(identity-array 3 <f32array>)
 @result{} #,(<f32array> (0 3 0 3) 1.0 0.0 0.0 0.0 1.0 0.0 0.0 0.0 1.0)
@end example
@end defun

@defun array-inverse array
@{@t{gauche.array}@}
Regards the @var{array} as a matrix, and returns its inverse matrix;
@var{array} must be 2-dimensional, and must have square shape.  If
@var{array} doesn't satisfy these conditions, an error is thrown.

If @var{array} isn't a regular matrix, @code{#f} is returned.
@end defun

@defun determinant array
@defunx determinant! array
@{@t{gauche.array}@}
Regards the @var{array} as a matrix, and calculates its determinant;
@var{array} must be 2-dimensional, and must have square shape.  If
@var{array} doesn't satisfy these conditions, an error is thrown.

@code{determinant!} destructively modifies the given array during
calculation.  It is faster than @code{determinant}, which copies
@var{array} before calculation to preserve it.
@end defun

@defun array-mul a b
@{@t{gauche.array}@}
Arrays @var{a} and @var{b} must be rank 2.   Regarding them
as matrices, multiply them together.  The number of rows of @var{a}
and the number of columns of @var{b} must match.

@example
;;           [6 5]
;; [1 2 3] x [4 3] => [20 14]
;; [4 5 6]   [2 1]    [56 41]

(array-mul (array (shape 0 2 0 3) 1 2 3 4 5 6)
           (array (shape 0 3 0 2) 6 5 4 3 2 1))
 @result{} #,(<array> (0 2 0 2) 20 14 56 41)
@end example
@end defun

@defun array-expt array pow
@{@t{gauche.array}@}
Raises @var{array} to the power of @var{pow}; @var{array} must be
a square matrix, and @var{pow} must be a nonnegative exact integer.
@end defun

@defun array-div-left a b
@defunx array-div-right a b
@{@t{gauche.array}@}
Inverse of @code{array-mul}; @code{array-div-left}
returns a matrix @code{M} such that @code{(array-mul B M)}
equals to @code{A}, and @code{array-div-right} returns
a matrix @code{M} such that @code{(array-mul M B)} equals to @code{A}.
@var{A} and @var{B} must be a 2-dimensional square matrix.
If @code{B} isn't regular, an error is thrown.
@end defun

@defun array-add-elements array array-or-scalar @dots{}
@defunx array-add-elements! array array-or-scalar @dots{}
@defunx array-sub-elements array array-or-scalar @dots{}
@defunx array-sub-elements! array array-or-scalar @dots{}
@defunx array-mul-elements array array-or-scalar @dots{}
@defunx array-mul-elements! array array-or-scalar @dots{}
@defunx array-div-elements array array-or-scalar @dots{}
@defunx array-div-elements! array array-or-scalar @dots{}
@{@t{gauche.array}@}
Element-wise arithmetics.  The second argument and after must
be an array of the same shape of the first argument, or a number;
if it is a number, it is interpreted as an array of the same shape
of the first argument, and each element of which is the given number.

Returns an array of the same shape of the first argument,
where each element is the result of addition, subtraction, multiplication
or division of the corresponding elements of the arguments.

The linear-update version (procedures whose name ends with @code{!})
may reuse the storage of the first array to calculate the result.
The first array must be mutable.  The caller must still use the returned
value instead of counting on the side effects.

@example
(array-add-elements (array (shape 0 2 0 2) 1 2 3 4) 
                    (array (shape 0 2 0 2) 5 6 7 8) 
                    10)
 @result{} #,(<array> (0 2 0 2) 16 18 20 22)

(array-div-elements (array (shape 0 2 0 2) 1 3 5 7)
                    100
                    (array (shape 0 2 0 2) 2 4 6 8))
 @result{} #,(<array> (0 2 0 2) 1/200 3/400 1/120 7/800)
@end example

If only one argument is passed, these procedures
returns the argument itself.

You can mix different types of arrays as long as their shapes are
the same.  The result is the same type as the first argument.

@example
(array-mul-elements (make-u8array (shape 0 2 0 2) 3)
                    (array (shape 0 2 0 2) 1 3 5 7))
 @result{} #,(<u8array> (0 2 0 2) 3 9 15 21)
@end example
@end defun


@defun array-negate-elements array
@defunx array-negate-elements! array
Returns an array with the same type of the shape of @var{array},
but each element is a negation of the corresponding
elements in the original array.

@example
(array-negate-elements (array (shape 0 2 0 2) 1 2 3 4))
  @result{} #,(<array> (0 2 0 2) -1 -2 -3 -4)
@end example
@end defun

@defun array-reciprocate-elements array
@defunx array-reciprocate-elements! array
Returns an array with the same type of the shape of @var{array},
but each element is a reciprocal of the corresponding
elements in the original array.

@example
(array-reciprocate-elements (array (shape 0 2 0 2) 1 2 3 4))
  @result{} #,(<array> (0 2 0 2) 1 1/2 1/3 1/4)
@end example
@end defun

@c ----------------------------------------------------------------------
@node Importing gauche built-ins, Generating C code, Arrays, Library modules - Gauche extensions
@section @code{gauche.base} - Importing gauche built-ins
@c NODE Gauche組み込み関数のインポート, @code{gauche.base} - Gauche組み込み関数のインポート

@deftp {Module} gauche.base
@mdindex gauche.base
This module exports Gauche built-in procedures and syntaxes, so that
they can be imported to other modules that don't inherit @code{gauche} module.

All the bindings available in the @code{gauche} module are exported,
except @code{import}, which is renamed to @code{gauche:import} to
avoid conflict with R7RS @code{import}.

The module extends @code{gauche.keyword}, so 
also exports all the keywords---the bindings from @code{gauche.keyword}---
so that the code imports @code{gauche.base} can access to self-bound keywords
without inheriting the keyword module.  
@end deftp

Typical Gauche code doesn't need this module, for built-ins are available
by default through inheritance.
A newly created module @emph{inherits} the @code{gauche} module by default.
(@xref{Module inheritance}, for the details.)

Sometimes you need a module that doesn't inherit the @code{gauche} module,
yet you want to use Gauche built-in features.  Particularly, R7RS libraries
and programs require any bindings to be explicitly imported,
so R7RS's @code{import} and @code{define-library} sets up the module not
to inherit the @code{gauche} module.   In R7RS code, you need
@code{(import (gauche base))} to use Gauche's built-in features.

Another use case is to eliminate some built-in bindings, yet
keep the rest of bindings accessible, in your module.
For example, the following setup creates @code{almost-gauche} module
that has almost all default bindings except @code{string-scan}
and @code{string-split}:

@example
(define-module almost-gauche
  (use scheme.r5rs)
  (use gauche.base :except (string-scan string-split)
                   :rename ((gauche:import import)))
  (extend)
  )
(select-module almost-gauche)

;; your code here
@end example

Note the empty @code{extend}; it empties the module's inheritance.
(The @code{:rename} option of @code{gauche.base} is just to get
the original name of @code{import} back in @code{almost-gauche} module;
if you don't use @code{import} directly, you won't need it.)

@c ----------------------------------------------------------------------
@node Generating C code, Character code conversion, Importing gauche built-ins, Library modules - Gauche extensions
@section @code{gauche.cgen} - Generating C code
@c NODE Cコードの生成, @code{gauche.cgen} - Cコードの生成

Significant part of Gauche is written in Gauche or S-expression
based DSL.  During the building process, they are converted
into C sources and then compiled by C compiler.
The @code{gauche.cgen} module and its submodules expose
the functionality Gauche build process is using to the general use.

Required features for a C code generator differ greatly among
applications, and too much scaffolding could be a constraint
for the module users.  So, instead of providing a single
solid framework, we provide a set of loosely coupled modules
so that you can combine necessary features freely.  In fact,
some of Gauche build process only use @code{gauche.cgen.unit}
and @code{gauche.cgen.literal} (see @file{src/builtin-syms.scm},
for example).

@deftp {Module} gauche.cgen
@mdindex gauche.cgen
This is a convenience module that extends
@code{gauche.cgen.unit}, @code{gauche.cgen.literal},
@code{gauche.cgen.type} and @code{gauche.cgen.cise} together.
@end deftp

Usually you can just use @code{gauche.cgen} and don't need
to think about individual submodules.
The following subsections are organized by submodules
only for the convenience of explanation.

@menu
* Generating C source files::   gauche.cgen.unit
* Generating Scheme literals::  gauche.cgen.literals
* Conversions between Scheme and C::  gauche.cgen.type
* C in S expression::           gauche.cgen.cise
* Stub generation::             gauche.cgen.stub
@end menu

@node Generating C source files, Generating Scheme literals, Generating C code, Generating C code
@subsection Generating C source files
@c NODE Cソースファイルを生成する

One of the tricky issues about generating C source is that
you have to put several fragments of code in different
parts of the source file, even you want to say just one thing---that is,
sometimes you have to put declaration before the actual definition,
plus some setup code that needs to be run at initialization time.

@subsubheading Creating a frame

@deftp {Class} <cgen-unit>
@clindex cgen-unit
@{@t{gauche.cgen}@}
A @emph{cgen-unit} is a unit of C source generation.
It corresponds to one .c file, and optionally one .h file.
During the processing, a "current unit" is kept in a parameter
@code{cgen-current-unit}, and most cgen APIs implicitly work to it.

The following slot are for public use.  They are used to tailor
the output.  Usually you set those slots at initialization time.
The effect is undefined if you change them in the middle of
the code generation process.

@defivar {<cgen-unit>} name
A string to name this unit.  This is used for the default name
of the generated files (@file{@var{name}.c} and @file{@var{name}.h})
and the suffix of the default name of initialization function.
Other cgen modules may use this to generate names.  Avoid using
characters that are not valid for C identifiers.

You can override those default names by setting the other slots.
@end defivar

@defivar {<cgen-unit>} c-file
@defivarx {<cgen-unit>} h-file
The name of the C source file and header file, in strings.
If they are @code{#f} (by default), the value of name slot
is used as the file name, with extension @code{.c} or @code{.h}
is attached, respectively.

To get the file names to be generated, use @code{cgen-unit-c-file}
and @code{cgen-unit-h-file} generic functions, instead of reading
these slots.
@end defivar

@defivar {<cgen-unit>} preamble
A list of strings to be inserted at the top of the generated sources.
The default value is @code{("/* Generated by gauche.cgen */")}.
Each string appears in its own line.
@end defivar

@defivar {<cgen-unit>} init-prologue
@defivarx {<cgen-init>} init-epilogue
A string to start or to end the initialization function, respectively.
The default value of @code{init-prologue} is
@code{"void Scm_Init_NAME(void) @{"} where @code{NAME} is the
value of the @code{name} slot.  The default value of @code{init-epilogue}
is just @code{"@}"}.  Each string appears in its own line.

To get the default initialization function name, use @code{cgen-unit-init-name}
generic function.

To customize initialization function name, arguments and/or return type,
set @code{init-prologue}.

The content of initialization function is filled by the code
fragments registered by @code{cgen-init}.
@end defivar
@end deftp

@deffn {Parameter} cgen-current-unit
A parameter to keep the current cgen-unit.
@end deffn

A typical flow of generating C code is as follows:

@enumerate
@item
Create a @code{<cgen-unit>} and make it the current unit.
@item
Call code insertion APIs with code fragments.  Fragments are accumulated
in the current unit.
@item
Call @emph{emit} method on the unit, which generates a C file
and optionally a header file.
@end enumerate

@deffn {Generic Function} cgen-emit-c cgen-unit
@deffnx {Generic Function} cgen-emit-h cgen-unit
@{@t{gauche.cgen}@}
Write the accumulated code fragments in @var{cgen-unit} to a
C source file and C header file.  The name of the files are
determined by calling @code{cgen-unit-c-file} and @code{cgen-unit-h-file},
respectively.  If the files already exist, its content is overwritten;
you can't gradually write to the files.
So, usually these procedures are called at the last step of the code
generation.

We'll explain the details of how each file is organized under
``Filling the content'' section below.
@end deffn

@deffn {Generic Function} cgen-unit-c-file cgen-unit
@deffnx {Generic Function} cgen-unit-h-file cgen-unit
@{@t{gauche.cgen}@}
Returns a string that names C source and header file for
@var{cgen-unit}, respectively.  The default method first
looks at @code{c-file} or @code{h-file} slot of the
@var{cgen-unit}, and if it is @code{#f}, use the value of @code{name}
slot and appends an extension @code{.c} or @code{.h}.
@end deffn

@deffn {Generic Function} cgen-unit-init-name cgen-unit
@{@t{gauche.cgen}@}
Returns a string that names the initialization function
generated to C.  It is used to create the default
@code{init-prologue} value.
@end deffn

@subsubheading Filling the content

There are four parts to which you can add C code
fragment.  Within each part, code fragments are rendered in the
same order as added.

@table @asis
@item extern
This part is put into the header file, if exists.
@item decl
Placed at the beginning of the C source, after the standard
prologue.
@item body
Placed in the C source, following the 'decl' part.
@item init
Placed inside the initialization function, which appears at
the end of the C source.
@end table

The following procedures are the simple way to put a source
code fragments in an appropriate part:

@defun cgen-extern code @dots{}
@defunx cgen-decl code @dots{}
@defunx cgen-body code @dots{}
@defunx cgen-init code @dots{}
@{@t{gauche.cgen}@}
Put code fragments @var{code} @dots{} to the appropriate parts.
Each fragment must be a string.
@end defun

This is a minimal example to show the typical usage.
After running this code you'll get @code{my-cfile.c} and
@code{my-cfile.h} in the current directory.

@example
(use gauche.cgen)

(define *unit* (make <cgen-unit> :name "my-cfile"))

(parameterize ([cgen-current-unit *unit*])
  (cgen-decl "#include <stdio.h>")
  (cgen-init "printf(stderr, \"initialization function\\n\");")
  (cgen-body "void foo(int n) @{ printf(stderr, \"got %d\\n\", n); @}")
  (cgen-extern "void foo(int n);")
  )

(cgen-emit-c *unit*)
(cgen-emit-h *unit*)
@end example

These are handy escaping procedures; they are useful even
if you don't use other parts of the @code{cgen} modules.

@defun cgen-safe-name string
@defunx cgen-safe-name-friendly string
@defunx cgen-safe-string string
@defunx cgen-safe-comment string
@{@t{gauche.cgen}@}
Escapes characters invalid in C identifiers, C string literals or C comments.

With @code{cgen-safe-name}, characters other than ASCII alphabets
and digits are converted to a form @code{_XX}, where @code{XX} is
hexadecimal notation of the character code.  (Note that the character
@code{_} is also converted.)  So the returned string can be used
safely as a C identifier.  The mapping is injective, that is,
if the source strings differ, the result string always differ.

On the other hand, @code{cgen-safe-name-friendly} converts
the input string into more readable C identifier.  @code{->} becomes
@code{_TO} (e.g. @code{char->integer} becomes @code{char_TOinteger}),
other @code{-} and @code{_} become @code{_},
@code{?} becomes @code{P} (e.g. @code{char?} becomes @code{charP}),
@code{!} becomes @code{X} (e.g. @code{set!} becomes @code{setX}),
@code{<} and @code{>} become @code{_LT} and @code{_GT} respectively.
Other special characters except @code{_} are converted to @code{_XX}
as in @code{cgen-safe-name}.  The mapping is not injective; e.g.
both @code{read-line} and @code{read_line} map to @code{read_line}.
Use this only when you think some human needs to read the generated
C code (which is not recommended, by the way.)

If you want to write out a Scheme string as a C string literal,
you can use @code{cgen-safe-string}.  It escapes control
characters and non-ascii characters.  If the Scheme string contains
a character beyond ASCII, it is encoded in Gauche's native encoding.
(NB: It also escapes @code{?}, to avoid accidenal formation of
C trigraphs).

Much simpler is @code{cgen-safe-comment}, which just converts
@code{/*} and @code{*/} into @code{/ *} and @code{* /} (a space
between those two characters), so that it won't terminate the
comment inadvertently.  (Technically, escaping only @code{*/} suffice,
but some simple-minded C parser might be confused by @code{/*} in the
comments).   The conversion isn't injective as well.

@example
(cgen-safe-name "char-alphabetic?")
  @result{} "char_2dalphabetic_3f"
(cgen-safe-name-friendly "char-alphabetic?")
  @result{} "char_alphabeticP"
(cgen-safe-string "char-alphabetic?")
  @result{} "\"char-alphabetic\\077\""

(cgen-safe-comment "*/*"
  @result{} "* / *"
@end example
@end defun


If you want to conditionalize a fragment by C preprocessor
@code{#ifdef}s, use the following macro:

@defmac cgen-with-cpp-condition cpp-expr body @dots{}
@{@t{gauche.cgen}@}
Code fragments submitted in @var{body} @dots{} are protected
by @code{#if @var{cpp-expr}} and @code{#endif}.

If @var{cpp-expr} is a string, it is emitted literally:

@example
(cgen-with-cpp-condition "defined(FOO)"
  (cgen-init "foo();"))

;; will generate:
#if defined(FOO)
foo();
#endif /* defined(FOO) */
@end example

You can also construct @var{cpp-expr} by S-expr.

@example
<cpp-expr> : <string>
           | (defined <cpp-expr>)
           | (not <cpp-expr>)
           | (<n-ary-op> <cpp-expr> <cpp-expr> ...)
           | (<binary-op> <cpp-expr> <cpp-expr>)

<n-ary-op> : and | or | + | * | - | /

<binary-op> : > | >= | == | < | <= | !=
            | logand | logior | lognot | >> | <<
@end example

Example:

@example
(cgen-with-cpp-condition '(and (defined FOO)
                               (defined BAR))
  (cgen-init "foo();"))

;; will generate:
#if ((defined FOO)&&(defined BAR))
foo();
#endif /* ((defined FOO)&&(defined BAR)) */
@end example

You can nest @code{cgen-with-cpp-condition}.
@end defmac

@subsubheading Submitting code fragments for more than one parts

When you try to abstract code generation process,
calling individual procedures for each parts (e.g. @code{cgen-body}
or @code{cgen-init}) becomes tedious, since such higher-level
constructs are likely to require generating code fragments
to various parts.  Instead, you can create a customized class
that handles submission of fragments to appropriate parts.

@deftp {Class} <cgen-node>
@clindex cgen-node
@{@t{gauche.cgen}@}
A base class to represent a set of code fragments.

The state of C preprocessor condition (set by @code{with-cgen-cpp-condition})
is captured when an instance of the subclass of this class is
created, so generating appropriate @code{#if}s and @code{#endif}s are
automatically handled.
@end deftp

You subclass @code{<cgen-node>}, then define method(s) to
one or more of the following generic functions:

@deffn {Generic Function} cgen-emit-xtrn cgen-node
@deffnx {Generic Function} cgen-emit-decl cgen-node
@deffnx {Generic Function} cgen-emit-body cgen-node
@deffnx {Generic Function} cgen-emit-init cgen-node
@{@t{gauche.cgen}@}
These generic functions are called during writing out
the C source within @code{cgen-emit-c} and @code{cgen-emit-h}.
Inside these methods, anything written out to the
current output port goes into the output file.

While generating @code{.h} file by @code{cgen-emit-h},
@code{cgen-emit-xtrn} method for all submitted nodes are
called in order of submission.

While generating @code{.c} file by @code{cgen-emit-c},
@code{cgen-emit-decl} method for all submitted nodes are
called first, then @code{cgen-emit-body} method, then
@code{cgen-emit-init} method.

If you don't specialize any one of these method, it doesn't
generate code in that part.
@end deffn

Once you define your subclass and create an instance,
you can submit it to the current cgen unit by this procedure:

@defun cgen-add! cgen-node
@{@t{gauche.cgen}@}
Submit @var{cgen-node} to the current cgen unit.
If the current unit is not set, @var{cgen-node} is simply ignored.
@end defun

In fact, the procedures @code{cgen-extern}, @code{cgen-decl},
@code{cgen-body} and @code{cgen-init} are just a convenience
wrapper to create an internal subclass specialized to generate
code fragment only to the designated part.


@node Generating Scheme literals, Conversions between Scheme and C, Generating C source files, Generating C code
@subsection Generating Scheme literals
@c NODE Schemeリテラルを生成する

Sometimes you want to refer to a Scheme constant value in C code.
It is trivial if the value is a simple thing like Scheme boolean
(@code{SCM_TRUE}, @code{SCM_FALSE}), characters (@code{SCM_MAKE_CHAR(code)}),
small integers (@code{SCM_MAKE_INT(value)}), etc.  You can directly
write it in C code.  However, once you step outside of these simple
values, it gets tedious quickly, involving static data declarations
and/or runtime initialization code.

For example, to get a Scheme value of a list of symbols @code{(a b c)},
you have to (1) create @code{ScmString}s for the names of the symbols,
(2) pass them to @code{Scm_Intern} to get Scheme symbols, then
(3) call @code{Scm_Cons}es (or a convenience macro @code{SCM_LIST3}) to
build a list.

With @code{gauche.cgen}, those code can be generated automatically.

NOTE: If you use @code{cgen-literal}, make sure you call
@code{(cgen-decl "#include <gauche.h>")} to include @file{gauche.h}
before the first call of @code{cgen-literal}, which may insert
declarations that needs @file{gauche.h}.

@defun cgen-literal obj
@{@t{gauche.cgen}@}
Returns an @code{<cgen-literal>} object for a Scheme object @var{obj},
and submit necessary declarations and initialization code to the
current cgen unit.
@end defun

For the above example, you can just call @code{(cgen-literal '(a b c))}
and the C code to set up the Scheme literal of the list of three
symbols will be generated.

The result of @code{cgen-literal} is an instance of @code{<cgen-literal>};
the detail of the class isn't for public use, but you can use it
to refer the created literal in C code.

@deffn {Generic Function} cgen-cexpr cgen-literal
@{@t{gauche.cgen}@}
Returns a C code expression fragment of type @code{ScmObj},
which represents the Scheme literal value.

The following example creates a C function @code{printabc} that prints
the literal value @code{(a b c)}, created by @code{cgen-literal}.

@example
(define *unit* (make <cgen-unit> :name "foo"))
(parameterize ((cgen-current-unit *unit*))
  (let1 lit (cgen-literal '(a b c))
    (cgen-body
     (format "void printabc() @{ Scm_Printf(SCM_CUROUT, \"%S\", ~a); @}"
             (cgen-c-name lit)))))
(cgen-emit-c *unit*)
@end example

If you examine the generated file @file{foo.c}, you'll get a
general idea of how it is handled.
@end deffn

One advantage of @code{cgen-literal} is that it tries to share
the same literal whenever possible.  If you call
@code{(cgen-literal '(a b c))} twice in the same cgen unit,
you'll get one instance of cgen-literal.  If you call
@code{(cgen-literal '(b c))} then, it will share the tail
of the original list @code{(a b c)}.  So you can just use
@code{cgen-literal} whenever you need to have Scheme literal
values, without worrying about generating excessive amount of
duplicated code.

Certain Scheme objects cannot be generated as a literal; for example,
an opened port can't, since it carries lots of runtime information.

(There's a machinery to allow programmers to extend the cgen-literal
behavior for new types.  The API isn't fixed yet, though.)


@node Conversions between Scheme and C, C in S expression, Generating Scheme literals, Generating C code
@subsection Conversions between Scheme and C
@c NODE SchemeとCの間の変換

In the C world, any Scheme object is uniformly of type @code{ScmObj}.
But it is often the case that you need to narrow down to the
specific type and convert it to a C value.  Gauche maintains
a database of how to typecheck and map Scheme value to C value and
vice versa.

Note that the mapping isn't one-to-one: Scheme @code{<integer>}
can be mapped to C's @code{short}, @code{long}, @code{unsigned int},
or even just @code{ScmObj} if the C routine wants to cover bignums.
So each mapping has its own name.  For historical reasons, each
mapping is called @emph{stub type}.  The names of stub types look
like Scheme type but its semantics differ from Scheme type.
Remember: Each stub type represents a specific mapping between a
Scheme type and a C type.

Each stub type has a @emph{C-predicate},
a @emph{boxer} and an @emph{unboxer}, each of them is a Scheme
string for the name of a C function or C macro.
A C-predicate takes @code{ScmObj} object and returns C boolean
value that if the given object has a valid type and range for the
stub type.
A boxer takes C object and converts it to a Scheme object; it
usually involves wrapping or @emph{boxing} the C value in a
tagged pointer or object, hence the name.
An unboxer does the opposite: takes a Scheme object and convert
it to a C value.  The Scheme object must be checked by the C-predicate
before being passed to the unboxer.

The following table shows the predefined stub types.
Note that the most of aggregate types has one to one mappings.
The difficult ones are numeric types and strings.
Scheme numbers can represent much wider range of numbers
than C, so you have to narrow down according to the capability
of C routine.  Scheme strings have byte size and character length,
and the body may not be NULL-terminated; so the @code{<string>}
stub type maps Scheme string to @code{ScmString*}.  For the convenience,
you can use @code{<const-cstring>}, which creates NUL-terminated
C string; beware that it may incur some copying cost.

@example
Stub type    Scheme       C           Notes
-----------------------------------------------------------------
<fixnum>     <integer>    int         Integers within fixnum range
<integer>    <integer>    ScmObj      Any exact integers
<real>       <real>       double      Value converted to double
<number>     <number>     ScmObj      Any numbers

<int>        <integer>    int         Integers representable in C
<int8>       <integer>    int
<int16>      <integer>    int
<int32>      <integer>    int
<short>      <integer>    short
<long>       <integer>    long
<uint>       <integer>    uint        Integers representable in C
<uint8>      <integer>    uint
<uint16>     <integer>    uint
<uint32>     <integer>    uint
<ushort>     <integer>    ushort
<ulong>      <integer>    ulong
<float>      <real>       float       Unboxed value casted to float
<double>     <real>       double      Alias of <real>

<boolean>    <boolean>    int         Boolean value
<char>       <char>       ScmChar     Note: not a C char

<void>       -            void        (Used only as a return type.
                                        Scheme function returns #<undef>)

<string>     <string>     ScmString*  Note: not a C string

<const-cstring> <string>  const char* For arguments, string is unboxed
                                      by Scm_GetStringConst.
                                      For return values, C string is boxed
                                      by SCM_MAKE_STR_COPYING.

<const-cstring-safe> <string> const char*  Like <const-cstring>,
                                      but when converting from Scheme,
                                      reject a string with NUL chars in it.

<pair>       <pair>       ScmPair*
<list>       <list>       ScmObj
<string>     <string>     ScmString*
<symbol>     <symbol>     ScmSymbol*
<keyword>    <keyword>    ScmKeyword*
<vector>     <vector>     ScmVector*
<uvector>    <uvector>    ScmUVector*
<s8vector>   <s8vector>   ScmS8Vector*
<u8vector>   <u8vector>   ScmU8Vector*
<s16vector>  <s16vector>  ScmS16Vector*
<u16vector>  <u16vector>  ScmU16Vector*
<s32vector>  <s32vector>  ScmS32Vector*
<u32vector>  <u32vector>  ScmU32Vector*
<s64vector>  <s64vector>  ScmS64Vector*
<u64vector>  <u64vector>  ScmU64Vector*
<f16vector>  <f16vector>  ScmF16Vector*
<f32vector>  <f32vector>  ScmF32Vector*
<f64vector>  <f64vector>  ScmF64Vector*
<c32vector>  <c32vector>  ScmC32Vector*
<c64vector>  <c64vector>  ScmC64Vector*
<c128vector> <c128vector> ScmC128Vector*

<hash-table> <hash-table> ScmHashTable*
<tree-map>   <tree-map>   ScmTreeMap*

<char-set>   <char-set>   ScmCharSet*
<regexp>     <regexp>     ScmRegexp*
<regmatch>   <regmatch>   ScmRegMatch*
<port>       <port>       ScmPort*
<input-port>  <input-port> ScmPort*
<output-port> <output-port> ScmPort*
<procedure>  <procedure>  ScmProcedure*
<closure>    <closure>    ScmClosure*
<promise>    <promise>    ScmPromise*

<class>      <class>      ScmClass*
<method>     <method>     ScmMethod*
<module>     <module>     ScmModule*
<thread>     <thread>     ScmVM*
<mutex>      <mutex>      ScmMutex*
<condition-variable> <condition-variable> ScmConditionVariable*
@end example

A stub type can have a @emph{maybe} variation, denoted by
@code{?} suffix; e.g. @code{<string>?}.  It is a union type of
the base type and boolean false (for @code{<string>?}, it
can be either @code{<string>} or @code{#f}.)   In the C world,
boolean false is mapped to @code{NULL} pointer.  It is convenient
to pass a C value that allowed to be NULL back and forth---if
you pass @code{#f} from the Scheme world it comes out @code{NULL} to
the C world, and vice versa.   The maybe variation is only
meaningful when the C type is a pointer type.

@deftp {Class} <cgen-type>
@clindex cgen-type
@{@t{gauche.cgen}@}
An instance of this class represents a stub type.
It can be looked up by name such as @code{<const-cstring>} by
@code{cgen-type-from-name}.
@end deftp

@defun cgen-type-from-name name
@{@t{gauche.cgen}@}
Returns an instance of @code{<cgen-type>} that has @var{name}.
If the name is unknown, @code{#f} is returned.
@end defun

@defun cgen-box-expr cgen-type c-expr
@defunx cgen-unbox-expr cgen-type c-expr
@defunx cgen-pred-expr cgen-type c-expr
@{@t{gauche.cgen}@}
@var{c-expr} is a string denotes a C expression.
Returns a string of C expression that boxes, unboxes, or
typechecks the @var{c-expr} according to the @var{cgen-type}.

@example
;; suppose foo() returns char*
(cgen-box-expr
 (cgen-type-from-name '<const-cstring>)
 "foo()")
 @result{} "SCM_MAKE_STR_COPYING(foo())"
@end example
@end defun


@node C in S expression, Stub generation, Conversions between Scheme and C, Generating C code
@subsection CiSE - C in S expression
@c NODE S式で書くC, CiSE - S式で書くC

Some low-level routines in Gauche are implemented in C, but they're
written in S-expression.  We call it ``C in S expression'', or @emph{CiSE}.

The advantage of using S-expression is its readability, obviously.
Another advantage is that it allows us to write macros as
S-expr to S-expr translation, just like the legacy Scheme macros.
That's a powerful feature---effectively you can extend C language
to suit your needs.

The @code{gauche.cgen.cise} module provides a set of tools to convert
CiSE code into C code to be passed to the C compiler.  It also has
some support to overcome C quirks, such as preparing forward
declarations.

Currently, we don't do rigorous check for CiSE; you can pass a
CiSE expression to the translator that yields invalid C code, which will
cause the C compiler
to emit errors.  The translator inserts line directives by default so the
C compiler error message points to the location of original (CiSE) source
instead of generated code; however, sometimes you need to look at
the generated code to figure out what went wrong.  We hope this
will be improved in future.

In Gauche source code, CiSE is extensively used in precompiled Scheme
files and recognized by the precompiler (@code{precomp}).  However,
@code{gauche.cgen.cise} is an independent module only relies
on @code{gauche.cgen} basic features, so you can plug it
to your own C code generating programs.

@menu
* CiSE overview::
* CiSE syntax::
* CiSE procedures::
@end menu

@node CiSE overview, CiSE syntax, C in S expression, C in S expression
@subsubsection CiSE overview

Before diving into the details, it's easier to grasp
some basic concepts.

A @emph{CiSE fragment} is an S-expression that follows
CiSE syntax (@pxref{CiSE syntax}).  A CiSE fragment can be
translated to a C code fragment by @code{cise-render}.
Note that some translation may not be local, e.g. it may
want to emit forward declarations before other C code fragments.
So, the full translation requires buffering---you process all
the CiSE fragments and save output, emit forward declarations,
then emit the saved C code fragments.  We have a wrapper procedure,
@code{cise-translate}, to take care of it, but for your purpose
you may want to roll your own wrapper.

A @emph{CiSE macro} is a Scheme code that translates a CiSE
fragment to another CiSE fragment.  There are number of
predefined CiSE macros.  You can add your own CiSE macros by
utilities such as
@code{define-cise-stmt} and @code{define-cise-expr}.

A @emph{CiSE ambient} is a bundle of information that affects
fragment translation.  It contains CiSE macro definitions,
and also it keeps track of forward declarations.

@node CiSE syntax, CiSE procedures, CiSE overview, C in S expression
@subsubsection CiSE syntax

In this section, we lists basic CiSE syntax.  They are just data from
the viewpoint of Gauche---so you can build and manipulate them like
any S-expression (quasiquote comes pretty handy).

@subsubheading CiSE types

C types can be written either as a symbol (e.g. @code{int}) or
a list (e.g. @code{(const char *)}.  When used in definition, it is
preceded by @code{::}.  The following example shows types
are used in local variable definitions:

@example
(let* ([a :: int 0]
       [b :: (const char *) "abc"])
  ...)
@end example

For the convenience and readability, you can write the variable name,
separating double-colon and type name concatenated.  You can also concatenate
point suffixes (@code{char*} instead of @code{char *} in the following example):

@example
(let* ([a::int 0]
       [b::(const char*) "abc"])
  ...)
@end example

CiSE translater first breaks up these concatenated forms, then
deal with types.

At this moment, CiSE does @emph{not} check if type is valid C type.
It just pass along whatever given.

There are a few special type notations for more complex types.
These can appear in middle of the type; for example, you can write
@code{(const .struct x (a::int b::double) *)} to produce
@code{const struct x @{int a; double b;@} *}.

@deffn {CiSE Type} .array elt-type (dim @dots{})
@end deffn

@deffn {CiSE Type} .struct [tag] [(field-spec @dots{})]
@deffnx {CiSE Type} .union [tag] [(field-spec @dots{})]
@end deffn

@deffn {CiSE Type} .function (arg-spec @dots{}) ret-type
@end deffn


@subsubheading CiSE statements

@deffn {CiSE Statement} begin stmt @dots{}
Code grouping with @code{@{} and @code{@}}
@end deffn

@deffn {CiSE Statement} let* ((name [@code{::} type] [init-expr]) @dots{}) stmt @dots{}
Declare and optionally assign initial values to local variables.

@var{type} should be a CiSE type.
If @var{type} is omitted, the default type is @code{ScmObj}. Note that
array initialization is not supported yet.
@end deffn

@deffn {CiSE Statement} if test-expr then-stmt [else-stmt]
@deffnx {CiSE Statement} when test-expr stmt @dots{}
@deffnx {CiSE Statement} unless test-expr stmt @dots{}
@deffnx {CiSE Statement} cond (cond1 stmt1 @dots{}) @dots{} [ (@code{else} else-stmt @dots{}) ]
Conditional statements.
@end deffn

@deffn {CiSE Statement} case expr ((val1 @dots{}) stmt1 @dots{}) @dots{} [ (@code{else} else-stmt @dots{}) ]
@deffnx {CiSE Statement} case/fallthrough expr ((val1 @dots{}) stmt1 @dots{}) @dots{} [ (@code{else} else-stmt @dots{}) ]
Switch-case statement. @code{case} does not fall through between 'case'
blocks while @code{case/fallthrough} does.
@end deffn

@deffn {CiSE Statement} for (start-expr test-expr update-expr) stmt @dots{}
@deffnx {CiSE Statement} for () stmt @dots{}
@deffnx {CiSE Statement} loop stmt @dots{}
@deffnx {CiSE Statement} while test-expr body @dots{}
Loop statements.
@end deffn

@deffn {CiSE Statement} for-each (@code{lambda} (var) stmt @dots{}) expr
@deffnx {CiSE Statement} dolist [var expr] stmt @dots{}
@var{expr} must yield a list. Traverse the list, binding each element to @var{var}
and executing @var{stmt} @dots{}. The lambda form is a fake; you don't
really create a closure.
@end deffn

@deffn {CiSE Statement} pair-for-each (@code{lambda} (var) stmt @dots{}) expr
Like @code{for-each}, but @var{var} is bound to each 'spine' cell instead of each
element of the list.
@end deffn

@deffn {CiSE Statement} dopairs [var expr] stmt @dots{}
@end deffn

@deffn {CiSE Statement} dotimes (var expr) stmt @dots{}
@var{expr} must yield an integer, @var{n}.  Repeat @var{stmt} @dots{} by binding @var{var} from 0
to (@var{n}-1).
@end deffn

@deffn {CiSE Statement} return [expr]
@deffnx {CiSE Statement} break
@deffnx {CiSE Statement} continue
Return, break and continue statements.
@end deffn

@deffn {CiSE Statement} label name
@deffnx {CiSE Statement} goto name
Label and goto statements. We always add a null statement after the
label so that we can place @code{(label @var{name})} at the end of a compound
statement.
@end deffn

@deffn {CiSE Statement} .if @var{expr} @var{stmt} [@var{stmt}]
@deffnx {CiSE Statement} .when @var{expr} @var{stmt} @dots{}
@deffnx {CiSE Statement} .unless @var{expr} @var{stmt} @dots{}
@deffnx {CiSE Statement} .cond @var{clause} @dots{}
@deffnx {CiSE Statement} .define @var{name}[(@var{arg} @dots{})] [@var{expr}]
@deffnx {CiSE Statement} .undef @var{name}
@deffnx {CiSE Statement} .include @var{path}
Preprocessor directives.

@var{expr} could be
a string, a symbol, a number or one of the following forms:
@itemize
@item
@code{(defined @var{c})}
@item
@code{(not @var{c})}
@item
@code{(and @var{c})}
@item
@code{(or @var{c})}
@item
@code{(@var{op} @var{c} @dots{})} where @var{op} is either @code{+} or
@code{*}.
@item
@code{(@var{op} @var{c} @var{c} @dots{})} where @var{op} is either
@code{-} or @code{/}.
@item
@code{(@var{op} @var{c} @var{c})} where @var{op} is either @code{>},
@code{>=}, @code{==}, @code{<}, @code{<=}, @code{!=}, @code{logand},
@code{logior}, @code{lognot}, @code{<<} or @code{>>}.
@end itemize

Note that defining a macro function without value
@example
#define foo(abc)
@end example
is not supported because it's ambiguous with
@example
#define foo abc()
@end example
when written in CiSE syntax. @code{(.define foo (abc))} always
generates the latter.

@code{.include} could take a symbol. This is used for including system
header files, e.g. @code{(.include <stdint.h>)}.
@end deffn

@deffn {CiSE Statement} define-cfn name (arg [@code{::} type] @dots{}) [ret-type [qualifier @dots{}]] stmt @dots{}
Defines a C function.

If @var{type} or @var{ret-type} is omitted, the default type is
@code{ScmObj}.

Supported qualifiers are @code{:static} and @code{:inline}, corresponding
to C's @code{static} and @code{inline} keywords.  If @code{:static} is
specified, forward declaration is automatically generated.
@end deffn

@deffn {CiSE Statement} define-cvar name [@code{::} type] [qualifier @dots{}] [<init-expr>]
Defines a global C variable. Supported qualifier is
@code{:static}. Note that array initialization is not supported yet.
@end deffn

@deffn {CiSE Statement} define-ctype name [@code{::} type]
Defines a new type using @code{typedef}
@end deffn

@deffn {CiSE Statement} declare-cfn name (arg [@code{::} type] @dots{}) [ret-type]
@deffnx {CiSE Statement} declare-cvar name [@code{::} type]
Declares an external C function or variable.
@end deffn


@deffn {CiSE Statement} .static-decls

Produce declarations of static functions before function bodies.

@end deffn

@deffn {CiSE Statement} .raw-c-code body @dots{}

@end deffn

@subsubheading CiSE expressions

@deffn {CiSE Expression} + expr @dots{}
@deffnx {CiSE Expression} - expr @dots{}
@deffnx {CiSE Expression} * expr @dots{}
@deffnx {CiSE Expression} / expr @dots{}
@deffnx {CiSE Expression} % expr1 expr2
Arithmetic operations.
@end deffn

@deffn {CiSE Expression} and expr @dots{}
@deffnx {CiSE Expression} or expr @dots{}
@deffnx {CiSE Expression} not expr
Boolean operations.
@end deffn

@deffn {CiSE Expression} logand expr1 expr2 @dots{}
@deffnx {CiSE Expression} logior expr1 expr2 @dots{}
@deffnx {CiSE Expression} logxor expr1 expr2 @dots{}
@deffnx {CiSE Expression} lognot expr
@deffnx {CiSE Expression} << expr1 expr2
@deffnx {CiSE Expression} >> expr1 expr2
Bitwise operations.
@end deffn

@deffn {CiSE Expression} * expr
@deffnx {CiSE Expression} -> expr1 expr2 @dots{}
@deffnx {CiSE Expression} ref expr1 expr2 @dots{}
@deffnx {CiSE Expression} aref expr1 expr2 @dots{}
@deffnx {CiSE Expression} & expr
Dereference, reference and address operations. @code{ref} is C's
@code{.}. @code{aref} is array reference.
@end deffn

@deffn {CiSE Expression} pre++ expr
@deffnx {CiSE Expression} post++ expr
@deffnx {CiSE Expression} pre-- expr
@deffnx {CiSE Expression} post-- expr
Pre/Post increment or decrement.
@end deffn

@deffn {CiSE Expression} < expr1 expr2
@deffnx {CiSE Expression} <= expr1 expr2
@deffnx {CiSE Expression} > expr1 expr2
@deffnx {CiSE Expression} >= expr1 expr2
@deffnx {CiSE Expression} == expr1 expr2
@deffnx {CiSE Expression} != expr1 expr2
Comparison.
@end deffn

@deffn {CiSE Expression} set! lvalue1 expr1 lvalue2 expr2 @dots{}
@deffnx {CiSE Expression} = lvalue1 expr1 lvalue2 expr2 @dots{}
@deffnx {CiSE Expression} += lvalue expr
@deffnx {CiSE Expression} -= lvalue expr
@deffnx {CiSE Expression} *= lvalue expr
@deffnx {CiSE Expression} /= lvalue expr
@deffnx {CiSE Expression} %= lvalue expr
@deffnx {CiSE Expression} <<= lvalue expr
@deffnx {CiSE Expression} >>= lvalue expr
@deffnx {CiSE Expression} logand= lvalue expr
@deffnx {CiSE Expression} logior= lvalue expr
@deffnx {CiSE Expression} logxor= lvalue expr
Assignment expressions.
@end deffn

@deffn {CiSE Expression} cast type expr
Type casting.
@end deffn

@deffn {CiSE Expression} ?: test-expr then-expr else-expr
Conditional expression.
@end deffn

@deffn {CiSE Expression} .type type
Useful to  place a type name, e.g. an argument of sizeof operator.
@end deffn


@node CiSE procedures,  , CiSE syntax, C in S expression
@subsubsection CiSE procedures


@deftp {Parameter} cise-ambient
@{@t{gauche.cgen}@}
@end deftp

@defun cise-default-ambient
@{@t{gauche.cgen}@}
@end defun

@defun cise-ambient-copy ambient
@{@t{gauche.cgen}@}
@end defun

@defun cise-ambient-decl-strings ambient
@{@t{gauche.cgen}@}
@end defun

@deftp {Parameter} cise-emit-source-line
@{@t{gauche.cgen}@}
@end deftp

@defun cise-render cise-fragment :optional port context
@{@t{gauche.cgen}@}
@end defun

@defun cise-render-to-string cise-fragment :optional context
@{@t{gauche.cgen}@}
@end defun

@defun cise-render-rec cise-fragment stmt/expr env
@{@t{gauche.cgen}@}
@end defun

@defun cise-translate inp outp :key environment
@{@t{gauche.cgen}@}
@end defun


@defun cise-register-macro! name expander :optional ambient
@{@t{gauche.cgen}@}
@end defun

@defun cise-lookup-macro name :optional ambient
@{@t{gauche.cgen}@}
@end defun

@defmac define-cise-stmt name [env] clause @dots{} [:where definition @dots{}]
@defmacx define-cise-expr name [env] clause @dots{} [:where definition @dots{}]
@defmacx define-cise-toplevel name [env] clause @dots{} [:where definition @dots{}]
@{@t{gauche.cgen}@}
@end defmac

@defmac define-cise-macro (name form env) body @dots{}
@defmacx define-cise-macro name name2
@{@t{gauche.cgen}@}
@end defmac

@node Stub generation,  , C in S expression, Generating C code
@subsection Stub generation
@c NODE スタブの生成

@deffn {Stub Form} define-type NAME C-TYPE [DESC C-PREDICATE UNBOXER BOXER]
Register a new type to be recognized.  This is rather a declaration
than definition; no C code will be generated directly by this form.
@end deffn

@deffn {Stub Form} define-cproc name (args @dots{}) [ret-type] [flag @dots{}] [qualifier @dots{}] stmt @dots{}
Create Scheme procedure.

@var{args} specifies arguments:
@itemize
@item
@code{@var{arg} @dots{} [:rest @var{var}]} :
Each @var{arg} is variable name or @var{var::type}, specifies required
argument. If @code{:rest} is given, list of excessive arguments are
passed to @var{var}.

@item
@code{@var{arg} @dots{} :optional @var{spec} @dots{} [:rest @var{rest-var}]} :
Optional arguments. @var{spec} is @var{var} or (@var{var}
@var{default}). If no @var{default} is given, @var{var} receives
@code{SCM_UNBOUND}---if @var{var} isn't a type of @code{ScmObj} it will
raise an error.

@item
@code{ARG @dots{} :key @var{spec} @dots{} [:allow-other-keys [:rest @var{rest-var}]]} :
Keyword arguments. @var{spec} is @var{var} or (@var{var}
@var{default}).  If no @var{default} is given, @var{var} receives
@code{SCM_UNBOUND}---if @var{var} isn't a type of @code{ScmObj} it will raise
an error.

@item
@code{arg @dots{} :optarray (@var{var} @var{cnt} @var{max}) [:rest @var{rest-var}]} :
A special syntax to receive optional arguments as a C array.
@var{var} is a C variable of type @code{ScmObj*}. @var{cnt} is a C
variable of type @code{int}, which receives the number of optional
argument in the ScmObj array.  @var{max} specifies the maximum number
of optional arguments that can be passed in the array form.  If more
than @var{max} args are given, a list of excessive arguments are
passed to the @var{rest-var} if it is specified
@end itemize

@var{ret-type} specifies the return type of function. It could be
either @code{:: @var{typespec}} or @code{::@var{typespec}} where
@var{typespec} is a valid stub type, or @code{(@var{type} @dots{})} when
multiple values are returned. When omitted, the procedure is assumed
to return @code{<top>}.

@var{flag} is a keyword to modify some aspects of the procedure.
Supported flags are as follows:

@itemize
@item
@code{:fast-flonum} - indicates that the procedure accepts flonum
arguments and it won't retain the reference to them. The VM can pass
flonums on VM registers to the procedure with this flag. (This
improves floating-point number handling, but it's behavior is highly
VM-specific; ordinary stub writers shouldn't need to care about this
flag at all.)

@item
@code{:constant} - indicates that this procedure returns a constant
value if all args are compile-time constants. The compiler may replace
the call to this proc with the value, if it determines all arguments
are known at the compile time. The resulting value should be
serializable to the precompiled file.

NB: Since this procedure may be called at compile time, a subr that
may return a different value for batch/cross compilation shouldn't
have this flag.
@end itemize

@var{qualifier} is a list to adds auxiliary information to the
procedure. Currently the following qualifiers are officially
supported.

@itemize
@item
@code{(setter @var{setter-name})} : specify setter. @var{setter-name} should
be a cproc name defined in the same stub file

@item
@code{(setter (@var{args} @dots{}) @var{body} @dots{})} : specify setter
anonymously.

@item
@code{(catch (@var{decl} @var{c-stmt} @dots{}) @dots{})} : when writing a stub
for C++ function that may throw an exception, use this spec to ensure
the exception will be caught and converted to Gauche error condition.

@item
@code{(inliner @var{insn-name})} : only used in Gauche core procedures that
can be inlined into an VM instruction.
@end itemize

@var{stmt} is a cise expression.  Inside the expression, a cise macro
@code{(result expr @dots{})} can be used to assign the value(s) to
return from the cproc. As a special case, if @var{stmt} is a single
symbol, it names a C function to be called with the same argument (mod
unboxing) as the cproc.
@end deffn

@deffn {Stub Form} define-cgeneric @var{name} @var{c-name} @var{property-clause} @dots{}
Defines generic function. @var{c-name} specifies a C variable name
that keeps the generic function structure. One or more of the
following clauses can appear in @var{property-clause} @dots{}:

@itemize
@item
@code{(extern)} : makes @var{c-name} visible from other file (i.e. do
not define the structure as @code{static}).

@item
@code{(fallback "fallback")} : specifies the fallback function.

@item
@code{(setter . @var{setter-spec})} : specifies the setter.
@end itemize
@end deffn

@deffn {Stub Form} define-cmethod @var{name} (@var{arg} @dots{}) @var{body} @dots{}
@end deffn

@deffn {Stub Form} define-cclass @var{scheme-name} [@var{qualifier} @dots{}] @var{c-type-name} @var{c-class-name} @var{cpa} (@var{slot-spec} @dots{}) @var{property} @dots{}
Generates C stub for static class definition, slot accessors and
initialization. Corresponding C struct has to be defined elsewhere.

The following qualifiers are supported:
@itemize
@item
@code{:base} generates a base class definition (inheritable from
Scheme code).
@item
@code{:built-in} generates a built-in class definition (not
inheritable from Scheme code). This is the default if neither
@code{:base} nor @code{:built-in} are specified.
@item
@code{:private} - the class declaration and standard macro definitions
are also generated (which needs to be in the separate header file if
you want the C-level structure to be used from other C code. If the
extension is small enough to be contained in one C file, this option
is convenient.)
@end itemize

@var{cpa} lists ancestor classes in precedence order. They need to be
C identifiers of Scheme class @code{Scm_*Class}, for the time being.
@code{Scm_TopClass} is added at the end automatically.

@var{slot-spec} is defined as @code{(@var{slot-name} [@var{qualifier}
@dots{}])} or @code{@var{slot-name}}. The following qualifiers are
supported:

@itemize
@item
@code{:type @var{cgen-type}}
@item
@code{:c-name @var{c-name}} specifies the C field name if the
autogenerated name from @var{slot-name} is not accurate.
@item
@code{:c-spec @var{c-spec}}
@item
@code{:getter @var{proc-spec}}
specifies how to create the slot getter. @var{proc-spec} could be
@itemize
@item
@code{#f} to omit the getter
@item
@code{#t} to generate a default one with type conversion according to
@var{type}
@item
A string is interpreted as the C code to implement the getter
@item
@code{(c @var{c-name})} specifies the C function name that implements
the getter, which is implemented elsewhere.
@end itemize
@item
@code{:setter @var{proc-spec}}
specifies how to create the slot setter. The syntax is the same as
@code{:getter}.
@end itemize

The following @var{property} are supported:

@itemize
@item
@code{(allocator @var{proc-spec})}
@item
@code{(printer @var{proc-spec})}
@item
@code{(comparer @var{proc-spec})}
@item
@code{(direct-supers @var{string} @dots{})}
@end itemize

@end deffn

@deffn {Stub Form} define-cptr @var{scheme-name} [@var{qualifier} @dots{}] @var{c-type} @var{c-name} @var{c-pred} @var{c-boxer} @var{c-unboxer} [(flags @var{flag} @dots{})] [(print @var{print-proc})] [(cleanup @var{cleanup-proc})]
Defines a new foreign pointer class based on
@code{<foreign-pointer>}. It is suitable when the C structure is
mostly passed around using pointers; most typically, when the foreign
library allocates the structure and returns the pointer to the Scheme
world.

@var{scheme-name} is a Scheme variable name. This will be bound to a
newly-created subclass of @code{<foreign-pointer>} to represent this
C-ptr type.

@var{c-type} is the type of the C pointer we wrap.

@var{c-name} is the C variable name (of type @code{ScmClass *}).  In
initialization code, an instance of a class (the same one bound to
@var{scm-name} in the Scheme world) will be stored in this C variable.

@var{c-pred} is a macro name to determine if a @code{ScmObj} is of
this type.
@var{c-boxer} is a macro name to wrap C pointer and return a
@code{ScmObj}
@var{c-unboxer} is a macro name to extract C pointer from a
@code{ScmObj}

The only supported qualifier is @code{:private}, which will generate
@var{c-pred}, @var{c-boxer} and @var{c-unboxer} definitions
automatically. Otherwise those definitions must be provided elsewhere.

The two supported flags are
@itemize
@item
@code{:keep-identity} (which is
@code{SCM_FOREIGN_POINTER_KEEP_IDENTITY} in the C world) keeps a weak
hash table that maps the wrapped C pointer to the wrapping
@code{ScmObj}, so @code{Scm_MakeForeignPointer} (i.e. @var{c-boxer}
when @code{:private} is used) returns eq? object if the same C pointer
is given.

This incurs some overhead, but cleanup procedure can safely free the
foreign object without worrying if there's other ScmObj that's
pointing to the same C pointer.

Do not use this flag if the C pointer is also allocated by
@code{GC_malloc}. The used hash table is only weak for its value, so
the C pointer wouldn't be GCed.
@item
@code{:map-null} (which is @code{SCM_FOREIGN_POINTER_MAP_NULL} in the
C world) makes @code{Scm_MakeForeignPointer} (i.e. @var{c-boxer} when
@code{:private} is used) return @code{SCM_FALSE} when the C pointer is
@code{NULL}.
@end itemize
@end deffn

@deffn {Stub Form} define-symbol @var{scheme-name} [@var{c-name}]
Defines a Scheme symbol. No Scheme binding is created.
When @var{c-name} is given, the named C variable points to the created
@code{ScmSymbol}.
@end deffn

@deffn {Stub Form} define-variable @var{scheme-name} @var{initializer}
Defines a Scheme variable.
@end deffn

@deffn {Stub Form} define-constant @var{scheme-name} @var{initializer}
Defines a Scheme constant.
@end deffn

@deffn {Stub Form} define-enum @var{name}
A @code{define-constant} specialized for enum values. This is useful for
exporting C enums to Scheme.
@end deffn

@deffn {Stub Form} define-enum-conditionally @var{name}
Abbreviation of @code{(if "defined(name)" (define-enum name))}
@end deffn

@deffn {Stub Form} define-cise-stmt @var{name} @var{clause} @dots{}
@deffnx {Stub Form} define-cise-expr @var{name} @var{clause} @dots{}
@deffnx {Stub Form} define-cfn @dots{}
@deffnx {Stub Form} declare-cfn @dots{}
@deffnx {Stub Form} define-cvar @dots{}
@deffnx {Stub Form} declare-cvar @dots{}
@deffnx {Stub Form} define-ctype @dots{}
@deffnx {Stub Form} .define @dots{}
@deffnx {Stub Form} .if @dots{}
@deffnx {Stub Form} .include @dots{}
@deffnx {Stub Form} .undef @dots{}
@deffnx {Stub Form} .unless @dots{}
@deffnx {Stub Form} .when @dots{}
Cise macro definitions (see @ref{C in S expression}).
@end deffn

@deffn {Stub Form} initcode @var{c-code}
Insert @var{c-code} literally in the initialization function
@end deffn

@deffn {Stub Form} declcode @var{stmt} @dots{}
Inserts declaration code. @var{stmt} is usually @code{.include} or
other preprocessor statements but it could also be a string which is
treated as C fragments.
@end deffn

@deffn {Stub Form} begin @var{form} @dots{}
Treat each @var{form} as if they are toplevel stub forms.
@end deffn

@deffn {Stub Form} if @var{test} @var{then-stmt} [@var{else-stmt}]
@deffnx {Stub Form} when @var{test} @var{stmt}
Deprecated. Please use @code{.if} and @code{.when} instead.
@end deffn

@deffn {Stub Form} include @var{file}
Include and evaluate another stub file.
@end deffn


@c ----------------------------------------------------------------------
@node Character code conversion, Collection framework, Generating C code, Library modules - Gauche extensions
@section @code{gauche.charconv} - Character Code Conversion
@c NODE 文字コード変換, @code{gauche.charconv} - 文字コード変換

@deftp {Module} gauche.charconv
@mdindex gauche.charconv
This module defines a set of functions that converts character encoding
schemes (CES) of the given data stream.

This module is implicitly loaded when @code{:encoding} keyword argument
is given to the file stream creating functions
(such as @code{open-input-file} and @code{call-with-output-file}).
@end deftp

@menu
* Supported character encoding schemes::
* Autodetecting the encoding scheme::
* Conversion ports::
@end menu

@node Supported character encoding schemes, Autodetecting the encoding scheme, Character code conversion, Character code conversion
@subsection Supported character encoding schemes
@c NODE サポートされる文字エンコーディング

A CES is represented by its name as a string or a symbol.
Case is ignored.  There may be several aliases defined for a single encoding.

A CES name "none" is special.  When Gauche's native encoding is @code{none},
Gauche just treats a string as a byte sequence, and it's up to the application
to interpret the sequence in an appropriate encoding.  So, conversion
to and from CES "none" does nothing.

Gauche natively supports conversions between
Unicode transfer encodings (UTF-8, UTF-16, UTF-16BE, UTF-16LE,
UTF-32, UTF-32BE, UTF-32LE), Latin-N encodings
(ISO8859-1 to 16), and
typical Japanese character encodings: ISO2022JP, ISO2022JP-3,
EUC-JP (EUC-JISX0213), Shift_JISX0213.

Conversions between other encodings are handled by @code{iconv(3)}
by default.  However, @code{iconv(3)} API lacks a feature to customize
the behavior when an input character can't be encoded in the output CES.
If you need to be sensitive about it, you can disable delegation to
@code{iconv(3)} by the following parameter.

@deffn {Parameter} external-conversion-library
The value of this parameter can be a symbol @code{iconv} or @code{#f}.
The default value is @code{iconv}.

Conversion ports opened during this parameter being @code{iconv}
will use @code{iconv(3)} library if the requested conversion isn't
supported by Gauche's native converters.
This only affect when the conversion port
is opened---once it is opened, this parameter value is irrelevant.
@end deffn

You can check whether the specific conversion is supported on
your system or not, by the following function.

@defun ces-conversion-supported? from-ces to-ces
@{@t{gauche.charconv}@}
Returns @code{#t} if conversion from the character encoding scheme
(CES) @var{from-ces} to @var{to-ces} is supported in this system.

Note that this procedure may return true even if system only supports
partial conversion between @var{from-ces} and @var{to-ces}.
In such case, actual conversion might lose information by coercing
characters in @var{from-ces} which are not supported in @var{to-ces}.
(For example, conversion from Unicode to EUC-JP is "supported",
although Unicode has characters that are not in EUC-JP).

Also note that this procedure always returns @code{#t}
if @var{from-ces} and/or @var{to-ces} is "none",
for conversion to/from CES "none" always succeeds (in fact, it does nothing).

This procedure may be affected by the value of the parameter
@code{external-conversion-library}.

@example
;; see if you can convert the internal encoding to EUC-JP
(ces-conversion-supported? (gauche-character-encoding) "euc-jp")
@end example
@end defun

Also there are two useful procedures to deal with CES names.

@defun ces-equivalent? ces-a ces-b :optional unknown-value
@{@t{gauche.charconv}@}
Returns true if two CESes @var{ces-a} and @var{ces-b} are equivalent
to the knowledge of the system.  Returns false if they are not.
If the system doesn't know about equivalency, @var{unknown-value}
is returned, whose default is @code{#f}.

CES "none" works like a wild card; it is "equivalent" to any CES.
(Thus, @code{ces-equivalent?} is not transitive.
The intended use of @code{ces-equivalent?}
is to compare two given CES names and see if conversion is required or not).

@example
(ces-equivalent? 'eucjp "EUC-JP")            @result{} #t
(ces-equivalent? 'shift_jis "EUC-JP")        @result{} #f
(ces-equivalent? "NoSuchEncoding" 'utf-8 '?) @result{} ?
@end example
@end defun

@defun ces-upper-compatible? ces-a ces-b :optional unknown-value
@{@t{gauche.charconv}@}
Returns true if a string encoded in CES @var{ces-b} can also
be regarded as a string encoded in @var{ces-a} without conversion,
to the knowledge of the system.
Returns false if not.  Returns @var{unknown-value}
if the system can't determine which is the case.

Like @code{ces-equivalent?}, CES "none" works like a wildcard.
It is upper-compatible to any CES, and any CES is upper-compatible to
"none".

@example
(ces-upper-compatible? "eucjp" "ASCII")             @result{} #t
(ces-upper-compatible? "eucjp" "utf-8")             @result{} #f
(ces-upper-compatible? "utf-8" "NoSuchEncoding" '?) @result{} ?
@end example
@end defun

When Gauche's internal conversion routine encounters a character that can't
be mapped, the behaivor depends on the @emph{illegal output handling mode} 
of the conversion port, specified by @var{illegal-output} keyword
arguments.
If the mode is @code{raise}, an @code{<io-encoding-error>}
is thrown.  If the mode is @code{replace},
the character is replaced with a replacement character.

A replacement character is U+FFFD (REPLACEMENT CHARACTER) if it is
available.  For Japanese encodings, U+FFFD isn't available, and
we use U+3013 (geta mark), for it is traditionally used as the
replacement character.  If neither one is available,
@code{?} is used.

If that happens in iconv, handling of such character depends
on iconv implementation (glibc implementation returns an error).

If the conversion routine encounters an input sequence that
is illegal in the input CES, an @code{<io-decoding-error>} is signaled.

@strong{Details of Gauche's native conversion algorithm:}
Between EUC_JP, Shift JIS and ISO2022JP, Gauche uses arithmetic
conversion whenever possible.  This even maps the undefined codepoint
properly.  Between Unicode (UTF-8) and EUC_JP, Gauche uses lookup tables.
Between Unicode and Shift JIS or ISO2022JP, Gauche converts the
input CES to EUC_JP, then convert it to the output CES.
ISO8859-N are converted to Unicode using tables, then converted to
the output CES if necessary.
If the same CES is specified for input and output, Gauche's conversion
routine just copies input characters to output characters, without
checking the validity of the encodings.

@table @code
@item EUC_JP, EUCJP, EUCJ, EUC_JISX0213
Covers ASCII, JIS X 0201 kana, JIS X 0212 and JIS X 0213 character sets.
JIS X 0212 character set is supported merely because it uses
the code region JIS X 0213 doesn't use, and JIS X 0212 characters
are not converted properly to Shift JIS and UTF-8.
Use JIS X 0213.

@item SHIFT_JIS, SHIFTJIS, SJIS
Covers Shift_JISX0213, except that 0x5c and 0x7e is mapped to ASCII
character set (REVERSE SOLIDUS and TILDE),
instead of JIS X 0201 Roman (YEN SIGN and OVERLINE).

@item UTF-8, UTF8
Unicode.  Note that some JIS X 0213 characters are mapped to Extension B
(U+20000 and up).
Some JIS X 0213 characters are mapped to two
unicode characters (one base character plus a combining character).

@item ISO2022JP, CSISO2022JP, ISO2022JP-1, ISO2022JP-2, ISO2022JP-3
These encodings differ a bit
(except ISO2022JP and CSISO2022JP, which are synonyms), but
Gauche handles them same.  If one of these CES is specified as input,
Gauche recognizes escape sequences of any of CES.
ISO2022JP-2 defines several non-Japanese escape sequences, and
they are recognized by Gauche, but mapped to substitution character
('?' or geta mark).

For output, Gauche assumes ISO2022JP first, and uses ISO2022JP-1
escape sequence to put JIS X 0212 character, or uses ISO2022JP-3
escape sequence to put JIS X 0213 plane 2 character.
Thus, if the string contains only JIS X 0208 characters,
the output is compatible to ISO2022JP.
Precisely speaking, JIS X 0213 specifies some characters in JIS X 0208
codepoint that shouldn't be mixed with JIS X 0208 characters;
Gauche output those characters as JIS X 0208 for compatibility.
(This is the same policy as Emacs-Mule's iso2022jp-3-compatible mode).
@end table

@node Autodetecting the encoding scheme, Conversion ports, Supported character encoding schemes, Character code conversion
@subsection Autodetecting the encoding scheme
@c NODE 文字エンコーディングの自動判定

There are cases that you don't know the CES of the input, but
you know it is one of several possible encodings.
The charconv module has a mechanism
to guess the input encoding.  There can be multiple algorithms,
and each algorithm has the name (wildcard CES).  Right now, there's only one
algorithm implemented:
@table @code
@item "*JP"
To guess the character encoding from japanese text, among either
ISO2022-JP(-1,2,3), EUCJP, SHIFT_JIS or UTF-8.
@end table

The wildcard CES can be used in place of CES name for some conversion functions.


@defun ces-guess-from-string string scheme
@{@t{gauche.charconv}@}
Guesses the CES of @var{string} by the character guessing scheme
@var{scheme} (e.g. "*JP").  Returns CES name that can be used
by other charconv functions.   It may return @code{#f} if the
guessing scheme finds no possible encoding in @var{string}.
Note that if there may be more than one possible encoding in
@var{string}, the guessing scheme returns one of them,
usually in favor of the native CES.
@end defun


@node Conversion ports,  , Autodetecting the encoding scheme, Character code conversion
@subsection Conversion ports
@c NODE 変換ポート

@defun open-input-conversion-port source from-code :key to-code buffer-size owner? illegal-output
@{@t{gauche.charconv}@}
Takes an input port @var{source}, which feeds characters
encoded in @var{from-code}, and returns another input port,
from which you can read characters encoded in @var{to-code}.

If @var{to-code} is omitted, the native CES is assumed.

@var{buffer-size} is used to allocate internal buffer size for
conversion.  The default size is about 1 kilobytes and it's suitable
for typical cases.

@var{hanlding} argument specifies the behavior when the output CES
doesn't have the corresponding character of input.  It can be a symbol
@code{raise} to raise an @code{<io-encoding-error>} in such cases,
or a symbol @code{replace} to replace the character with a replacement
character appropriate in the output CES.  If omitted, @code{raise}
is assumed.

Note that @code{iconv(3)} library API doesn't offer an option to
choose the illegal-output handling mode. So when the conversion is delegated to
@code{iconv(3)}, @var{illegal-output} is ignored and the behavior follows
the underlying @code{iconv(3)} implementation.  If you need to make
sure @var{illegal-output} is honored, you can bind the parameter
@code{external-conversion-library} to @code{#f} when calling
this procedure; then the conversion port won't
use @code{iconv(3)} and raises unsupported encodings error if the
conversion can't be handled entirely within Gauche.

By default, @code{open-input-conversion-port} leaves @var{source} open.
If you specify true value to @var{owner?}, the function closes
@var{source} after it reads EOF from the port.

If you don't know the @var{source}'s CES, you can specify
CES guessing scheme, such as @code{"*JP"}, in place of @var{from-code}.
The conversion port tries to guess the encoding, by prefetching
the data from @var{source} up to the buffer size.  It signals an error
if the code guessing routine finds no appropriate CES.
If the guessing routine finds ambiguous input, however, it silently
assume one of possible CES's, in favor of the native CES.
Hence it is possible that the guessing is wrong if the buffer
size is too small.  The default size is usually enough for most
text documents, but it may fail if the large text contains mostly ASCII
characters and multibyte characters appear only at the very end of
the document.
To be sure for the worst case,
you have to specify the buffer size large enough to
hold entire text.


For example, the following code copies a file @file{unknown.txt} to a file
@file{eucjp.txt}, converting unknown japanese CES to EUC-JP.
@example
(call-with-output-file "eucjp.txt"
  (lambda (out)
    (copy-port (open-input-conversion-port
                 (open-input-file "unknown.txt")
                 "*jp"             ;@r{guess code}
                 :to-code "eucjp"
                 :owner? #t)       ;@r{close unknown.txt afterwards}
               out)))
@end example
@end defun


@defun open-output-conversion-port sink to-code :key from-code buffer-size owner? illegal-output
@{@t{gauche.charconv}@}
Creates and returns an output port that converts
given characters from @var{from-code} to @var{to-code}
and feed to an output port @var{sink}.
If @var{from-code} is omitted, the native CES is assumed.
You can't specify a character guessing scheme (such as "*JP") to
neither @var{from-code} nor @var{to-code}.

@var{buffer-size} specifies the size of internal conversion buffer.
The characters put to the returned port may stay in the buffer,
until the port is explicitly flushed (by @code{flush}) or
the port is closed.

By default, the returned port doesn't closes @var{sink} when
itself is closed.  If a keyword argument @var{owner?} is provided
and true, however, it closes @var{sink} when it is closed.

The @var{illegal-output} keyword argument is the same
as @code{open-input-conversion-port}.
@end defun

@defun ces-convert-to return-type source from-code :optional to-code :key illegal-output
@defunx ces-convert source from-code :optional to-code :key illegal-output
@{@t{gauche.charconv}@}
Convert @var{source}, which is a string or an u8vector
of multibyte encoding in @var{from-code}, to a
string or u8vector encoded in @var{to-code}.  If @var{to-code} is
omitted, the native CES is assumed.

In @code{ces-convert-to}, you can specify the return type by
@var{return-type} argument; it must be either a class object @code{<string>}
or @code{<u8vector>}.  On the other hand, @code{ces-convert} always returns
a string, regardless of the type of @var{source}.

If @var{to-code} is different from the native CES and a string
is returned, it can be an incomplete string.  It's for the backward
compatibility---in general, we recommend to use u8vector to represent
multibyte sequence in CES other than the native encoding.

@var{from-code} can be a name of character guessing scheme
(e.g. "*JP").

The keyword argument @var{illegal-output} controls
the behavior when input contains a character that can't be encoded
in the output.  See @code{open-input-conversion-port} above for the
description.  By default, an @code{<io-encoding-error>} is raised,
except when the conversion is delegated to @code{iconv(3)}, in which case
the behavior depends on the external library.
@end defun

@defun call-with-input-conversion iport proc :key encoding conversion-buffer-size illegal-output
@defunx call-with-output-conversion oport proc :key encoding conversion-buffer-size illegal-output
@{@t{gauche.charconv}@}
These procedures can be used to perform character I/O with
different encoding temporary from the original port's encoding.

@code{call-with-input-conversion} takes an input port @var{iport}
which uses the character encoding @var{encoding}, and
calls @var{proc} with one argument, a conversion input port.
From the port, @var{proc} can read characters in
Gauche's internal encoding.
Note that once @var{proc} is called, it has to read all the
characters until EOF; see the note below.

@code{call-with-output-conversion} takes an output port @var{oport}
which expects the character encoding @var{encoding}, and
calls @var{proc} with one argument,
a temporary conversion output port.
To the port, @var{proc} can write characters in
Gauche's internal encoding.
When @var{proc} returns, or it exits with an error,
the temporary conversion output port is flushed and closed.
The caller of @code{call-with-output-conversion}
can continue to use @var{oport} with original encoding afterwards.

Both procedure returns the value(s) that @var{proc} returns.
The default value of @var{encoding} is Gauche's internal
encoding.  Those procedures don't create a conversion port
when it is not necessary.   If @var{conversion-buffer-size} is given,
it is used as the @var{buffer-size} argument when the conversion
port is open.

You shouldn't use @var{iport}/@var{oport} directly
while @var{proc} is active---character encoding is a
stateful process, and mixing I/O from/to the conversion port and
the underlying port will screw up the state.

@emph{Note:} for the @code{call-with-input-conversion}, you can't
use @var{iport} again unless @var{proc} reads EOF from it.
It's because a conversion port needs to buffer the input, and
there's no way to undo the buffered input to @var{iport}
when @var{proc} returns.
@end defun

@defun with-input-conversion iport thunk :key encoding conversion-buffer-size illegal-output
@defunx with-output-conversion oport thunk :key encoding conversion-buffer-size illegal-output
@{@t{gauche.charconv}@}
Similar to @code{call-with-*-conversion},
but these procedures call @var{thunk} without arguments,
while the conversion port is set as the current input or output port,
respectively.
The meaning of keyword arguments are the same as @code{call-with-*-conversion}.
@end defun

@defun wrap-with-input-conversion port from-code :key to-code owner? buffer-size illegal-output
@defunx wrap-with-output-conversion port to-code :key from-code owner? buffer-size illegal-output
@{@t{gauche.charconv}@}
Convenient procedures to avoid adding unnecessary conversion port.
Each procedure works like @code{open-input-conversion-port}
and @code{open-output-conversion-port}, respectively,
except if system knows no conversion is needed,
no conversion port is created and @var{port} is returned as is.

When a conversion port is created, @var{port} is always owned by the port.
When you want to close the port, always close the port returned
by @code{wrap-with-*-conversion}, instead the original @var{port}.
If you close the original @var{port} first, the pending conversion
won't be flushed.  (Some conversion requires trailing sequence that
is generated only when the conversion port is closing, so simply
calling @code{flush} isn't enough.)

The @var{buffer-size} and @var{illegal-output} arguments are passed to
the @code{open-*-conversion-port}.
@end defun

@c ----------------------------------------------------------------------
@node Collection framework, Configuration parameters, Character code conversion, Library modules - Gauche extensions
@section @code{gauche.collection} - Collection framework
@c NODE コレクションフレームワーク, @code{gauche.collection} - コレクションフレームワーク

@deftp {Module} gauche.collection
@mdindex gauche.collection
This module provides a set of generic functions (GFs) that iterate over
various collections.   The Scheme standard has some iterative
primitives such as @code{map} and @code{for-each},
and @code{scheme.list} (@pxref{R7RS lists} adds a rich set of such functions,
but they work only on lists.

Using the method dispatch of the object system, this module
efficiently extends those
functions for other collection classes such as vectors and hash tables.
It also provides a simple way for user-defined class to adapt
those operations.
So far, the following operations are defined.

@table @asis
@item Mapping
@code{fold}, @code{fold2}, @code{fold3},
@code{map}, @code{map-to}, @code{map-accum}, @code{for-each}
@item Selection and searching
@code{find}, @code{find-min}, @code{find-max}, @code{find-min&max},
@code{filter}, @code{filter-to},
@code{remove}, @code{remove-to}, @code{partition}, @code{partition-to}
@code{group-collection}
@item Conversion
@code{coerce-to}
@item Miscellaneous
@code{size-of}, @code{lazy-size-of}
@item Fundamental iterator creator
@code{call-with-iterator}, @code{call-with-builder},
@code{with-iterator}, @code{with-builder}, @code{call-with-iterators}.
@end table

Those operations work on @emph{collections} and its subclass,
@emph{sequences}.  A collection is a certain form of a set
of objects that you can traverse all the object in it in a certain way.
A sequence is a collection that all its elements are ordered, so that
you can retrieve its element by index.

The following Gauche built-in objects are treated as collections and/or
sequences.
@table @code
@item <list>
A sequence.
@item <vector>
A sequence.
@item <string>
A sequence (of characters)
@item <hash-table>
A collection.  Each element is a pair of a key and a value.
@item <s8vector>, <u8vector>, @dots{} <f64vector>
A sequence (methods defined in @code{gauche.uvector} module,
@pxref{Uniform vectors}).
@end table

@xref{Sequence framework}, for it adds more sequence specific
methods.

The methods that needs to return a set of objects, i.e.
@code{map}, @code{filter}, @code{remove} and @code{partition}.
returns a list (or lists).  The corresponding ``-to'' variant
(@code{map-to}, @code{filter-to}, @code{remove-to} and @code{partition-to}.
takes a collection class argument and returns the collection of the class.
@end deftp

@menu
* Mapping over collection::
* Selection and searching in collection::
* Miscellaneous operations on collection::
* Fundamental iterator creators::
* Implementing collections::
@end menu

@node Mapping over collection, Selection and searching in collection, Collection framework, Collection framework
@subsection Mapping over collection
@c NODE コレクションに対するマッピング

These generic functions extends the standard mapping procedures.
See also @ref{Mapping over sequences}, if you care the index
as well as elements.

@deffn {Generic function} fold proc knil coll coll2 @dots{}
@{@t{gauche.collection}@}
This is a natural extension of @var{fold} (@pxref{Other list procedures}).

For each element @var{Ei} in the collection @var{coll}, @var{proc} is
called as (@var{proc} @var{Ei} @var{Ri-1}), where @var{Ri-1} is the
result of (@var{i}-1)-th invocation of @var{proc} for @var{i} > 0,
and @var{R0} is @var{knil}.  Returns the last invocation of @var{proc}.
@example
(fold + 0 '#(1 2 3 4)) @result{} 10
(fold cons '() "abc")  @result{} (#\c #\b #\a)
@end example

If the @var{coll} is a sequence, it is guaranteed that
the elements are traversed in order.  Otherwise, the order
of iteration is undefined.

Note: We don't provide @code{fold-right} on collections, since the order
of elements doesn't matter, so only @code{fold} is sufficient for
meaningful traversal.
However, sequences do have @code{fold-right};
see @ref{Mapping over sequences}.

You can fold more than one collection, although it doesn't make
much sense unless all of the collections are sequences.
Suppose @code{@var{E}(@var{k}, @var{i})} for @var{i}-th element
of @var{k}-th collection.  @var{proc} is called as
@example
(@var{proc} @var{E}(0,i) @var{E}(1,i) @dots{} @var{E}(K-1,i) @var{Ri-1})
@end example

Different types of collections can be mixed together.

@example
(fold acons '() "abc" '#(1 2 3))
  @result{} ((#\c 3) (#\b 2) (#\a 1))

;; @r{calculates dot product of two vectors}
(fold (lambda (a b r) (+ (* a b) r)) 0
      '#(3 5 7) '#(2 4 6))
  @result{} 68
@end example

When more than one collection is given, @code{fold} terminates
as soon as at least one of the collections exhausted.
@end deffn

@deffn {Generic function} fold2 proc knil1 knil2 coll coll2 @dots{}
@deffnx {Generic function} fold3 proc knil1 knil2 knil3 coll coll2 @dots{}
@{@t{gauche.collection}@}
Like @code{fold}, but they can carry two and three state values
instead of one, respectively.  The state values are
initialized by @var{knilN}.  The procedure @var{proc} is called
with each element of @var{collN}, and the state values.  It must return
two (@code{fold2}) or three (@code{fold3}) values, which will be used
as the state values of next iteration.  The values returned in the
last iteration will be the return values of @code{fold2} and @code{fold3}.

@example
(fold2 (lambda (elt a b) (values (min elt a) (max elt b)))
       256 0 '#u8(33 12 142 1 74 98 12 5 99))
 @result{} 1 and 142  ;; find minimum and maximum values
@end example

See also @code{map-accum} below.
@end deffn


@deffn {Generic function} map proc coll coll2 @dots{}
@{@t{gauche.collection}@}
This extends the built-in @code{map} (@pxref{Walking over lists}).
Apply @var{proc} for each element in the collection @var{coll}, and
returns a list of the results.

If the @var{coll} is a sequence, it is guaranteed that
the elements are traversed in order.  Otherwise, the order
of iteration is undefined.

If more than one collection is passed, @var{proc} is called with
elements for each collection.  In such case, @code{map} terminates
as soon as at least one of the collection is exhausted.  Note that passing
more than one collection doesn't make much sense unless
all the collections are sequences.

@example
(map (lambda (x) (* x 2)) '#(1 2 3))
  @result{} #(2 4 6)

(map char-upcase "abc")
  @result{} (#\A #\B #\C)

(map + '#(1 2 3) '#(4 5 6))
  @result{} (5 7 9)
@end example

@code{map} @emph{always} returns a list.  If you want to get the result
in a different type of collection, use @code{map-to} described below.
If you wonder why @code{(map char-upcase "abc")} doesn't return
@code{"ABC"}, read the discussion in the bottom of this subsection.
@end deffn

@deffn {Generic function} map-to class proc coll coll2 @dots{}
@{@t{gauche.collection}@}
This works the same as @code{map}, except the result is returned
in a collection of class @var{class}.   @code{Class} must be a
collection class and have a builder interface
(@pxref{Fundamental iterator creators}).

@example
(map-to <vector> + '#(1 2 3) '#(4 5 6))
  @result{} #(5 7 9)

(map-to <string> char-upcase "def")
  @result{} "DEF"

(map-to <vector> char=? "bed" "pet")
  @result{} #(#f #t #f)
@end example
@end deffn

@deffn {Generic function} map-accum proc seed coll1 coll2 @dots{}
@{@t{gauche.collection}@}
Collects results of @var{proc} over collections, while passing
a state value.  @var{proc} is called like this:
@example
(@var{proc} @var{elt1} @var{elt2} @dots{} @var{seed})
@end example
Where @var{elt1} @var{elt2} @dots{} are the elements of
@var{coll1} @var{coll2} @dots{}.
It must return two values; the first value is collected into
a list (like @code{map}), while the second value is passed as
@var{seed} to the next call of @var{proc}.

When one of the collections is exhausted, @code{map-accum} returns
two values, the list of the first return values from @var{proc},
and the second return value of the last call of @var{proc}.

If the given collections are sequences, it is guaranteed that
@var{proc} is applied in order of the sequence.

This is similar to Haskell's @code{mapAccumL}, but note that
the order of @code{proc}'s argument and return values are
reversed.
@end deffn


@deffn {Generic function} for-each proc coll coll2 @dots{}
@{@t{gauche.collection}@}
Extension of built-in @code{for-each} (@pxref{Walking over lists}).
Applies @var{proc} for each elements in the collection(s).
The result of @var{proc} is discarded.  The return value of
@code{for-each} is undefined.

If the @var{coll} is a sequence, it is guaranteed that
the elements are traversed in order.  Otherwise, the order
of iteration is undefined.

If more than one collection is passed, @var{proc} is called with
elements for each collection.  In such case, @code{for-each} terminates
as soon as one of the collection is exhausted.  Note that passing
more than one collection doesn't make much sense unless
all the collections are sequences.
@end deffn


@deffn {Generic Function} fold$ proc
@deffnx {Generic Function} fold$ proc knil
@deffnx {Generic Function} map$ proc
@deffnx {Generic Function} for-each$ proc
@{@t{gauche.collection}@}
Partial-application version of @code{fold}, @code{map} and @code{for-each}.
@end deffn


@emph{Discussion:}  It is debatable what type of collection @code{map}
should return when it operates on the collections other than lists.
It may seem more ``natural'' if @code{(map * '#(1 2) '#(3 4))}
returns a vector, and @code{(map char-upcase "abc")} returns a string.

Although such interface seems work for simple cases, it'll become
problematic for more general cases.  What type of collection should
be returned if a string and a vector are passed?  Furthermore,
some collection may only have iterator interface but no builder
interface, so that the result can't be coerced to the argument type
(suppose you're mapping over database records, for example).
And Scheme programmers are used to think @code{map} returns a list,
and the result of @code{map} are applied to the procedures that
takes list everywhere.

So I decided to add another method, @code{map-to}, to specify
the return type explicitly
The idea of passing the return type is taken from CommonLisp's @code{map}
function, but taking a class metaobject, @code{map-to} is much flexible
to extend using method dispatch.
This protocol (``-to'' variant takes a class metaobject
for the result collection) is used throughout the collection framework.

@node Selection and searching in collection, Miscellaneous operations on collection, Mapping over collection, Collection framework
@subsection Selection and searching in collection
@c NODE コレクションからの選択と探索

@deffn {Generic function} find pred coll
@{@t{gauche.collection}@}
Applies @var{pred} for each element of a collection @var{coll} until
@var{pred} returns a true value.  Returns the element on which @var{pred}
returned a true value, or @code{#f} if no element satisfies @var{pred}.

If @var{coll} is a sequence, it is guaranteed that @var{pred} is
applied in order.  Otherwise the order of application is undefined.

@example
(find char-upper-case? "abcDe") @result{} #\D
(find even? '#(1 3 4 6)) @result{} 4
(find even? '(1 3 5 7))  @result{} #f
@end example
@end deffn

@deffn {Generic function} find-min coll :key key compare default
@deffnx {Generic function} find-max coll :key key compare default
@{@t{gauche.collection}@}
Returns a minimum or maximum element in the collection @var{coll}.

A one-argument procedure @var{key}, whose default is @code{identity},
is applied for each element to obtain a comparison value.
Then a comparison value is compared by a two-argument procedure
@var{compare}, whose default is @code{<}.
If the collection has zero or one element, the @var{compare} procedure
is never called.

When the collection is empty, a value given to @var{default} is
returned, whose default is @code{#f}.

@example
(find-min '((a . 3) (b . 9) (c . -1) (d . 7)) :key cdr) @result{} (c . -1)
@end example
@end deffn

@deffn {Generic function} find-min&max coll :key key compare default default-min default-max
@{@t{gauche.collection}@}
Does @code{find-min} and @code{find-max} simultaneously, and returns
two values, the minimum element and the maximum element.
The keyword arguments @var{key}, @var{compare}, and @var{default} are
the same as @code{find-min} and @code{find-max}.  Alternatively
you can give default values for minimum and maximum separately,
by @var{default-min} and @var{default-max}.
@end deffn

@deffn {Generic function} filter pred coll
@{@t{gauche.collection}@}
Returns a list of elements of collection @var{coll} that satisfies
the predicate @var{pred}.   If the collection is a sequence,
the order is preserved in the result.

@example
(filter char-upper-case? "Hello, World")
  @result{} (#\H #\W)
(filter even? '#(1 2 3 4)) @result{} (2 4)
@end example
@end deffn

@deffn {Generic function} filter-to class pred coll
@{@t{gauche.collection}@}
Same as @code{filter}, but the result is returned
as a collection of class @var{class}.

@example
(filter-to <vector> even? '#(1 2 3 4)) @result{} #(2 4)
(filter-to <string> char-upper-case? "Hello, World")
  @result{} "HW"
@end example
@end deffn

@deffn {Generic function} remove pred coll
@{@t{gauche.collection}@}
Returns a list of elements of collection @var{coll} that does not
satisfy the predicate @var{pred}.   If the collection is a sequence,
the order is preserved in the result.

@example
(remove char-upper-case? "Hello, World")
  @result{} (#\e #\l #\l #\o #\, #\space #\o #\r #\l #\d)
(remove even? '#(1 2 3 4)) @result{} (1 3)
@end example
@end deffn

@deffn {Generic function} remove-to class pred coll
@{@t{gauche.collection}@}
Same as @code{remove}, but the result is returned
as a collection of class @var{class}.

@example
(remove-to <vector> even? '#(1 2 3 4)) @result{} #(1 3)
(remove-to <string> char-upper-case? "Hello, World")
  @result{} "ello, orld"
@end example
@end deffn

@deffn {Generic function} partition pred coll
@{@t{gauche.collection}@}
Does @code{filter} and @code{remove} the same time.
Returns two lists, the first consists of elements of the collection
@var{coll} that satisfies the predicate @var{pred}, and the second
consists of elements that doesn't.

@example
(partition char-upper-case? "PuPu")
  @result{} (#\P #\P) @r{and} (#\u #\u)
(partition even? '#(1 2 3 4))
  @result{} (2 4) @r{and} (1 3)
@end example
@end deffn

@deffn {Generic function} partition-to class pred coll
@{@t{gauche.collection}@}
Same as @code{partition}, except the results are returned
in the collections of class @var{class}.

@example
(partition-to <string> char-upper-case? "PuPu")
  @result{} "PP" @r{and} "uu"
(partition-to <vector> even? '#(1 2 3 4))
  @result{} #(2 4) @r{and} #(1 3)
@end example
@end deffn

@deffn {Generic function} group-collection coll :key key test
@{@t{gauche.collection}@}
Generalized @code{partition}.  Groups elements in @var{coll}
into those who has the same key value, and returns the groups as
of lists.  Key values are calculated by applying the procedure @var{key}
to each element of @var{coll}.  The default value of @var{key} is
@code{identity}.   For each element of @var{coll}, @var{key} is applied
exactly once.
The equal-ness of keys are compared by
@var{test} procedure, whose default is @code{eqv?}.

If @var{coll} is a sequence, then the order of elements in each group
of the result is the same order in @var{coll}.

@example
(group-collection '(1 2 3 2 3 1 2 1 2 3 2 3))
  @result{} ((1 1 1) (2 2 2 2 2) (3 3 3 3))

(group-collection '(1 2 3 2 3 1 2 1 2 3 2 3) :key odd?)
  @result{} ((1 3 3 1 1 3 3) (2 2 2 2 2))

(group-collection '(("a" 2) ("b" 5) ("c" 1) ("b" 3) ("a" 6))
  :key car :test string=?)
  @result{} ((("a" 2) ("a" 6)) (("b" 5) ("b" 3)) (("c" 1)))
@end example

See also @code{group-sequence} in @code{gauche.sequence}
(@pxref{Other operations over sequences}),
which only groups adjacent elements.
@end deffn

@node Miscellaneous operations on collection, Fundamental iterator creators, Selection and searching in collection, Collection framework
@subsection Miscellaneous operations on collection
@c NODE コレクションに対する様々な操作

@deffn {Generic function} size-of coll
@{@t{gauche.collection}@}
Returns the number of elements in the collection.  Default method iterates over
the collection to calculate the size, which is not very efficient
and may diverge if the collection is infinite.
Some collection classes overload the method for faster calculation.
@end deffn

@deffn {Generic function} lazy-size-of coll
@{@t{gauche.collection}@}
Returns either the size of the collection, or a promise to
calculate it.  The intent of this method is to avoid
size calculation if it is expensive.  In some cases, the caller
wants to have size just for optimization, and it is not desirable
to spend time to calculate the size.  Such caller uses this method
and just discards the information if it is a promise.
@end deffn

@deffn {Generic function} coerce-to class coll
@{@t{gauche.collection}@}
Convert a collection @var{coll} to another collection
which is an instance of @var{class}.
If @var{coll} is a sequence and @var{class} is a sequence class,
the order is preserved.

@example
(coerce-to <vector> '(1 2 3 4))
  @result{} #(1 2 3 4)

(coerce-to <string> '#(#\a #\b #\c))
  @result{} "abc"
@end example
@end deffn

@node Fundamental iterator creators, Implementing collections, Miscellaneous operations on collection, Collection framework
@subsection Fundamental iterator creators
@c NODE 基礎的なイテレータ構築メソッド

These are fundamental methods on which all the rest of
iterative method are built.  The method interface is not intended
to be called from general code, but suitable for building
other iterator construct.   The reason why I chose this interface
as fundamental methods are explained at the bottom of this subsection.

@deffn {Generic function} call-with-iterator collection proc :key start
@{@t{gauche.collection}@}
A fundamental iterator creator.   This creates two procedures
from @var{collection}, both take no argument, and then call
@var{proc} with those two procedures.   The first procedure is
terminate predicate, which returns @code{#t} if the iteration
is exhausted, or @code{#f} if there are still elements to be visited.
The second procedure is an incrementer,
which returns one element from the collection and sets the
internal pointer to the next element.
The behavior is undefined if you call the incrementer after
the terminate predicate returns @code{#t}.

If the collection is actually a sequence, the incrementer is guaranteed
to return elements in order, from 0-th element to the last element.
If a keyword argument @var{start} is given, however, the iteration
begins from @var{start}-th element and ends at the last element.
If the collection is not a sequence, the iteration order is
arbitrary, and @var{start} argument has no effect.

An implementation of @var{call-with-iterator} method may
limit the extent of the iterator inside the dynamic scope of the method.
For example, it allocates some resource (e.g. connect to a database)
before calling @var{proc}, and deallocates it (e.g. disconnect from a database)
after @var{proc} returns.

This method returns the value(s) @var{proc} returns.

@example
(call-with-iterator '(1 2 3 4 5)
  (lambda (end? next)
    (do ((odd-nums 0))
        ((end?) odd-nums)
      (when (odd? (next)) (inc! odd-nums)))))
 @result{} 3
@end example

See also @code{with-iterator} macro below, for it is easier to use.
@end deffn

@defmac with-iterator (collection end? next args @dots{}) body @dots{}
@{@t{gauche.collection}@}
A convenience macro to call @code{call-with-iterator}.
@example
(with-iterator (coll end? next args @dots{}) body @dots{})
 @equiv{}
(call-with-iterator coll
  (lambda (end? next) body @dots{})
   args @dots{})
@end example
@end defmac

@defun call-with-iterators collections proc
@{@t{gauche.collection}@}
A helper function to write n-ary iterator method.
This function applies @code{call-with-iterator} for each @var{collection}s,
and makes two lists, the first consists of terminate predicates
and the second of incrementers.  Then @var{proc} is called
with those two lists.  Returns whatever @var{proc} returns.
@end defun

@deffn {Generic function} call-with-builder collection-class proc :key size
@{@t{gauche.collection}@}
A fundamental builder creator.  Builder is a way to construct
a collection incrementally.  Not all collection classes provide
this method.

@var{Collection-class} is a class of the collection to be built.
This method creates two procedures, adder and getter, then calls
@var{proc} with those procedures.
Adder procedure takes one argument and adds it to the collection
being built.  Getter takes no argument and returns a built collection object.
The effect is undefined if adder is called after getter is called.

A keyword argument @var{size} may be specified if the size of
the result collection is known.  Certain collections may be
built much more efficiently if the size is known; other collections
may just ignore it.   The behavior is undefined if more than
@var{size} elements are added, or the collection is retrieved before
@var{size} elements are accumulated.

If the collection class is actually a sequence class,
adder is guaranteed to add elements in order.  Otherwise,
the order of elements are insignificant.

Some collection class may take more keyword arguments to
initialize the collection.

This method returns the value(s) @var{proc} returned.

@example
(call-with-builder <list>
  (lambda (add! get)
    (add! 'a) (add! 'b) (add! 'c) (get)))
 @result{} (a b c)

(call-with-builder <vector>
  (lambda (add! get)
    (add! 'a) (add! 'b) (add! 'c) (get)))
 @result{} #(a b c)
@end example

See also @code{with-builder} macro below, for it is much easier to use.
@end deffn

@defmac with-builder (collection add! get args @dots{}) body @dots{}
@{@t{gauche.collection}@}
A convenience macro to call @code{call-with-builder}.
@example
(with-builder (coll add! get args @dots{}) body @dots{})
 @equiv{}
(call-with-builder coll
  (lambda (add! get) body @dots{})
  args @dots{})
@end example
@end defmac

@emph{Discussion}:
Other iterator methods are built on top of call-with-iterator and
call-with-builder.
By implementing those methods, you can easily adapt your own collection
class to all of those iterative
operations.   Optionally you can overload some of higher-level
methods for efficiency.

It is debatable that which set of operations should be primitives.
I chose call-with-iterator style for efficiency of the applications
I see most.   The following is a discussion of other possible
primitive iterators.

@table @asis
@item @code{fold}
It is possible to make @code{fold} a primitive method, and
build other iterator method on top of it.
Collection-specific iterating states can be kept in the
stack of @code{fold}, thus it runs efficiently.  The method
to optimize a procedure that uses @code{fold} as a basic
iterator construct.
However, it is rather cumbersome to derive
generator-style interface from it.   It is also tricky
to iterate irregularly over more than one collections.

@item CPS
Passes iteratee the continuation procedure that continues
the iteration.   The iteratee just returns when it want
to terminate the iteration.
It has resource management problem described in
Oleg Kiselyov's article (@uref{http://okmij.org/ftp/Scheme/enumerators-callcc.html}).

@item Iterator object
Like C++ iterator or Common Lisp generator.
Easy to write loop.   The problem is that every call of
checking termination or getting next element must be dispatched.

@item Series
Common Lisp's series can be very efficient if the compiler can statically
analyze the usage of series.  Unfortunately it is not the case in
Gauche.  Even if it could, the extension mechanism doesn't blend well
with Gauche's object system.

@item Macros
Iterator can be implemented as macros, and that will be very efficient;
e.g. Scheme48's iterator macro.  It uses macros to extend, however,
and that doesn't blend well with Gauche's object system.
@end table

The current implementation is close to the iterator object approach,
but using closures instead of iterator objects so that avoiding
dispatching in the inner loop.  Also it allows the iterator
implementor to take care of the resource problem.

@node Implementing collections,  , Fundamental iterator creators, Collection framework
@subsection Implementing collections
@c NODE コレクションの実装

The minimum requirements of the collection class implementation
is as follow:
@itemize @bullet
@item
The class inherits @code{<collection>} abstract class.
@item
A method @code{call-with-iterator} is implemented.
@end itemize

This makes iterator methods such as @code{map}, @code{for-each},
@code{find} and @code{filter} to work.

In order to make the constructive methods (e.g. @code{map-to} to
create your collection), you have to implement @code{call-with-builder}
method as well.  Note that @code{call-with-builder} method must work
a sort of class method, dispatched by class, rather than normal method
dispatched by instance.   In Gauche, you can implement it by using a
metaclass.   Then the minimal code will look like this:

@example
(define-class <your-collection-meta> (<class>) ())

(define-class <your-collection> (<collection>)
 (...) ;; @r{slots}
 :metaclass <your-collection-meta>)

(define-method call-with-iterator
    ((coll <your-collection>) proc . options)
  @dots{}
  )

(define-method call-with-builder
     ((coll <your-collection-meta>) proc . options)
  @dots{}
  )
@end example

Optionally, you can overload other generic functions to optimize
performance.

@c ----------------------------------------------------------------------
@node Configuration parameters, Generating build files, Collection framework, Library modules - Gauche extensions
@section @code{gauche.config} - Configuration parameters
@c NODE コンフィグレーション情報, @code{gauche.config} - コンフィグレーション情報

@deftp {Module} gauche.config
@mdindex gauche.config
This module allows the Scheme program to access the configuration information
the same as you can get from the @code{gauche-config} program.
@end deftp

@defun gauche-config option
@{@t{gauche.config}@}
Returns the configured value of the @var{option}.

See the manpage of @code{gauche-config}, or run @code{gauche-config}
without any argument from the shell, to find out the valid options.
@example
(gauche-config "--cc")
  @result{} "gcc"
(gauche-config "-L")
  @result{} "-L/usr/lib/gauche/0.6.5/i686-pc-linux-gnu"
(gauche-config "-l")
  @result{} "-ldl -lcrypt -lm -lpthread"
@end example
@end defun

@c ----------------------------------------------------------------------
@node Generating build files, Connection framework, Configuration parameters, Library modules - Gauche extensions
@section @code{gauche.configure} - Generating build files
@c NODE ビルド用ファイルの生成, @code{gauche.configure} - ビルド用ファイルの生成

@deftp {Module} gauche.configure
@mdindex gauche.configure
This is a utility library to write a @file{configure} script.
It is used to check the system properties and generates build files
(usually @file{Makefile}) from templates.

The primary purpose is to replace autoconf-generated 
@file{configure} shell scripts
in Gauche extension packages.

The advantage of using autoconf is that it generates
a script that runs on most vanilla unix, for it only uses minimal 
shell features and basic unix commands.   
However, when you configure Gauche extension,
you sure have Gauche already, so you don't need to limit
yourself with minimal environment.

Writing a @file{configure} script directly in Gauche means developers
don't need an extra step to generate @file{configure} before
distribution.  They can directly check in @file{configure} in
the source repo, and anybody who pulls the source tree can
run @file{configure} at once without having autoconf.

Currently, @code{gauche.configure} only covers small subset of
autoconf, though, so if you need to write complex tests
you may have to switch back to autoconf.  We'll add tests
as needed.
@end deftp

The core feature of @code{gauche.configure} is the ability to generate files
(e.g. @file{Makefile}) from templates (e.g. @file{Makefile.in}) with replacing
parameters.  We follow autoconf convention, so the substitution parameters
in a template is written like @code{@@VAR@@}.  You should be able
to reuse @file{Makefile.in} used for autoconf without changing them.

The API corresponds to autoconf's @code{AC_*} macros, while we use
@code{cf-} prefix instead.

@menu
* Structure of configure script::
* Configure API::
@end menu

@node Structure of configure script, Configure API, Generating build files, Generating build files
@subsection Structure of configure script and build files
@c NODE configureスクリプトの構成とビルドファイル

A @file{configure} script tests
running system's properties to determine values of
substitution parameters, then read one or more template build files,
and write out one output build file for each, replacing
substitution parameters for the assigned values.

By convention, a template file has a suffix @code{.in}, and
the corresponding output file is named without the suffix.
For example, @code{Makefile.in} is a template that generates
@code{Makefile}.

Templates may contain substitution parameters, noted @code{@@PARAMETER_NAME@@}.
This is a fragment of a typical Makefile template:

@example
GAUCHE_PACKAGE = "@@GAUCHE_PACKAGE@@"
SOEXT          = @@SOEXT@@
LOCAL_PATHS    = "@@LOCAL_PATHS@@"

foo.$(SOEXT): $(foo_SRCS)
        $(GAUCHE_PACKAGE) compile \
          --local=$(LOCAL_PATHS) --verbose foo $(foo_SRCS)
@end example

When processed by @code{configure}, @code{@@GAUCHE_PACKAGE@@},
@code{@@SOEXT@@} and @code{@@LOCAL_PATHS@@} are replaced
with appropriate values.   If you know autoconf, you are already
familiar with this.

The Gauche configure script is structurally similar to autoconf's
@code{configure.in}, but you can use full power of Scheme. 
The following is the minimal configure script:

@example
#!/usr/bin/env gosh
(use gauche.configure)
(cf-init-gauche-extension)
(cf-output-default)
@end example

This script does several common tasks.
The @code{cf-init-gauche-extension} does the following:

@itemize @bullet
@item
First, it handles command-line arguments given to @file{configure}.
In the default settings, it recognizes standard configure
arguments such as @code{--prefix}, and 
@code{--with-local=PATH:PATH:...}
which adds @code{PATH/include}s and @code{PATH/lib}s to
the header and library search paths.
You can handle more arguments by adding
@code{cf-arg-with} and @code{cf-arg-enable} before 
@code{cf-init-gauche-extension}.
@item
Then it reads @code{package.scm}.  Package name and version are taken
from it.  Dependencies are also checked.
@item
It sets up global environment to run other configure checks.
@item
It sets up default values for standard substitution parameters such as
@code{@@prefix@@}.
@end itemize

And @code{cf-output-default} does the following:

@itemize
@item
Generate gpd (Gauche package description) file.
@item
Writes package version to @code{VERSION} file.
@item
Scan @code{Makefile.in}'s in the source directory and its subdirectories,
and process them
to generate @code{Makefile}s.
If config header files (typically @code{config.h}) are specified by
@code{cf-config-headers}, process input files
(e.g. @code{config.h.in}) to generate the header files.
@end itemize

In general, a @code{configure} script consists of the following parts:

@enumerate
@item
Extra argument declarations (optional): Declare @code{--with-PACKAGE}
and/or @code{--enable-FEATURE} options you want to handle, by
@code{cf-with-arg} and @code{cf-enable-arg}, respectively.
@item
Initialization.  Call to @code{cf-init} or @code{cf-init-gauche-extension}
sets up global context and
parses command-line arguments passed to @code{configure}.
It also process package metainformation in @file{package.scm}, if it exists.
@item
Tests and other substitution parameter settings (optional): Check system
characteristics and sets up substitution parameters and/or
C preprocessor definitions.
@item
Output generation.  Call @code{cf-output} or @code{cf-output-default}
to process template files.
@end enumerate

Most @code{cf-*} API corresponds to autoconf's @code{AC_*} or
@code{AS_*} macros.   We need argument declarations
before @code{cf-init} so that it can generate help message
including custom arguments in one pass.

@node Configure API,  , Structure of configure script, Generating build files
@subsection Configure API

@subsubheading Initialization

@defun cf-init-gauche-extension
@{@t{gauche.configure}@}
This is a convenience API that packages several boilerplate @code{cf-*}
function calls in one call.  This must be called exactly once in a
configure script.

Specifically, it calls @code{cf-arg-with} to process @code{--with-local},
then calls @code{cf-init} with no arguments to initialize,
then sets the following substitution parameters:
@table @code
@item GOSH
Path to @code{gosh}.
@item GAUCHE_CONFIG
Path to @code{gauche-config}.
@item GAUCHE_PACKAGE
Path to @code{gauche-package}.
@item GAUCHE_INSTALL
Path to @code{gauche-install}.
@item GAUCHE_CESCONV
Path to @code{gauche-cesconv}.
@item GAUCHE_PKGINCDIR
Result of @code{gauche-config --pkgincdir}
@item GAUCHE_PKGLIBDIR
Result of @code{gauche-config --pkglibdir}
@item GAUCHE_PKGARCHDIR
Result of @code{gauche-config --pkgarchdir}
@end table

The @code{--with-local} command-line argument should take a parameter, which is
a colon-separated list of paths.  It becomes a value of substitution parameter
@code{LOCAL_PATHS}.  The default @code{Makefile.in} template passes
its value to @code{gauche-package} via the @code{--local} argument.
When the C extension is compiled and linked, the
@code{include} and @code{lib} subdirectories of the given paths are
searched for headers and libraries, respectively.
For example, if the extension requires a library foo and you install
it under @code{/opt/foo} (that is, headers in @code{/opt/foo/include}
and library objects in @code{/opt/foo/lib}), then you can pass
@code{--with-local=/opt/foo} to configure the extension.

If you don't like these default behavior, you can call individual
@code{cf-*} functions instead.  See @code{cf-init} below.
@end defun


@defun cf-init :optional package-name package-version maintainer-email homepage-url
@{@t{gauche.configure}@}
Initialize the configure system.  Corresponds to autoconf's @code{AC_INIT}.
This must be called once in the
configure script, before any feature-test procedures.
(If you call @code{cf-init-gauche-extension}, @code{cf-init} is called
from it.)

First, it checks if a file named @file{package.scm} is
in the same directory as the configure script,
and reads the Gauche package description from it.  The package description
contains package name, version, dependencies, etc.
@xref{Package metainformation}, for the details.

It then parses the command-line arguments, sets up the configure
environment, and (if @file{package.scm} defines dependencies) check
if the system has required packages.

The optional arguments are only supported for the backward compatibility
if you don't have @file{package.scm}.  You need at least 
to provide @var{package-name} and @var{package-version} to tell
what package you're configuring.  They are used as the value
of substitution parameter @code{PACKAGE_NAME} and @code{PACKAGE_VERSION}.
The other optional arguments, @var{maintainer-email} and 
@var{homepage-url}, are used to initialize @code{PACKAGE_BUGREPORT} and
@code{PACKAGE_URL}.  These arguments are compatible to autoconf's
@code{AC_INIT} macro.

We recommend to always use @file{package.scm} and omit all the optional
arguments, because it allows you to maintain the package metainformation
in one place.  When @file{package.scm} is read, @code{PACKAGE_BUGREPORT}
is initialized by the first entry of @code{maintainers} slot of
the package description, and @code{PACKAGE_URL} is initialized
by its @code{homepage} slot.
@xref{Package metainformation}, for description of slots of the package
description.

Note that if there's @file{package.scm} @emph{and} you provide
the optional arguments, they must match, or @code{cf-init} raises an
error.  It is to catch errors during transition in which you forgot
to update either one.

This procedure sets up a bunch of standard substitution parameters
such as @code{prefix}, @code{bindir} or @code{srcdir}.   To see what
substitution parameters are set, you can call @code{cf-show-substs}
after @code{cf-init}.
@end defun

@subsubheading Command-line arguments

@defun cf-arg-enable feature help-string :optional proc-if-given proc-if-not-given
@defunx cf-arg-with package help-string :optional proc-if-given proc-if-not-given
@{@t{gauche.configure}@}
Make the configure script accept feature selection argument and
package selection argument, respectively.  The corresponding
autoconf macros are @code{AC_ARG_ENABLE} and @code{AC_ARG_WITH}.

Those procedures must be called before calling @code{cf-init}
or @code{cf-init-gauche-extension}.

The @var{feature} and @var{package} arguments must be a symbol.

A feature selection argument is in a form of either
@code{--enable-@var{feature}=@var{val}}, 
@code{--enable-@var{feature}}, or @code{--disable-@var{feature}}.
The latter two are equivalent to @code{--enable-@var{feature}=yes}
and @code{--enable-@var{feature}=no}, respectively.
It is to select an optional feature provided with the package itself.

A package selection argument is in a form of either
@code{--with-@var{package}=@var{val}},
@code{--with-@var{package}} and @code{--without-@var{package}}.
The latter two are equivalent to @code{--with-@var{package}=yes}
and @code{--with-@var{package}=no}, respectively.
It is to select an external software package to be used with
this package.

When @code{cf-init} finds these arguments, it adds entry of @var{feature}
or @var{package} to the global tables, with the value @var{val}.
Those global tables can be accessed with @code{cf-feature-ref} and
@code{cf-package-ref} procedures below.

The @var{help-string} argument must be a string and
is used as is to list the help
of the option in part of usage message displayed by
@code{configure --help}.  You can use @code{cf-help-string} below
to create a help string that fits nicely in the usage message.

If optional @var{proc-if-given} argument is given, it must be a procedure
that accepts one argument, @var{val}.  It is called when @code{cf-init}
finds one of those arguments.

If optional @var{proc-if-not-given} argument is given, it must be a procedure
that accepts no arguments.  It is called when @code{cf-init}
doesn't find any of those arguments.

The following is to accept @code{--with-local=@var{PATH}:@var{PATH}:@dots{}}.
(This @code{cf-arg-with} call is included in @code{cf-init-gauche-extension}).
Note that the help string (the second argument) is generated by
@code{cf-help-string} call.  The command-line parameter followed by
@code{--with-local} is passed as the argument of the procedure
in the third argument:

@example
(cf-arg-with 'local
             (cf-help-string
              "--with-local=PATH:PATH..."
              "For each PATH, add PATH/include to the include search
  paths and PATH/lib to the library search paths.  Useful if you have some
  libraries installed in non-standard places. ")
             (^[with-local]
               (unless (member with-local '("yes" "no" ""))
                 (cf-subst 'LOCAL_PATHS with-local)))
             (^[] (cf-subst 'LOCAL_PATHS "")))
@end example
@end defun

@defun cf-help-string item description
@{@t{gauche.configure}@}
Return a string formatted suitable to show as an option's help message.
The result can be passed to @var{help-string} argument of
@code{cf-arg-enable} and @code{cf-arg-with}. 
This corresponds to autoconf's @code{AS_HELP_STRING}.

Call it as follows, and it'll indent and fill the description nicely.

@example
(cf-help-string "--option=ARG" "Give ARG as the value of option")
@end example
@end defun

@defun cf-feature-ref name
@defunx cf-package-ref name
@{@t{gauche.configure}@}
Lookup a symbol @var{name} from the global feature table and the
global package table, respectively.
These can be called after @code{cf-init}.

For example, if you've called @code{cf-arg-enable} with @code{foofeature},
and the user has invoked the @code{configure} script with
@code{--with-foofeature=full}, then @code{(cf-feature-ref 'foofeature)}
returns @code{"full"}.   If the user hasn't given the command-line
argument, @code{#f} is returned.

If you add or change the value of features or packages,
you can use generalized @code{set!} as
@code{(set! (cf-feature-ref 'NAME) VALUE)} etc.
@end defun


@subsubheading Messages

The @code{cf-init} procedure opens the default log drain
that goes to @code{config.log}, and you can use @code{log-format}
to write to it (@xref{User-level logging}, for the details of logging).

However, to have consistent message format conveniently, the following
procedures are provided.  They emits the message both to log files and 
the current output port (in slightly different formats so that the
console messages align nicely visually.)

@defun cf-msg-checking fmt arg @dots{}
@{@t{gauche.configure}@}
Writes out ``checking XXX...'' message.  The @var{fmt} and @var{arg} @dots{}
arguments are passed to @code{format} to produce the ``XXX'' part
(@pxref{Formatting output}).

For the current output port, this does not emit the trailing newline,
expecting @code{cf-msg-result} will be called subsequently.

Here's an excerpt of the source that uses @code{cf-msg-checking}
and @code{cf-msg-result}:
@example
(define (compiler-can-produce-executable?)
  (cf-msg-checking "whether the ~a compiler works" (~ (cf-lang)'name))
  (rlet1 result ($ run-compiler-with-content
                   (cf-lang-link-m (cf-lang))
                   (cf-lang-null-program-m (cf-lang)))
    (cf-msg-result (if result "yes" "no"))))
@end example

This produces a console output like this:
@example
checking whether the C compiler works... yes
@end example
while the log file records more info:
@example
checking: whether the C compiler works
... whatever logging message from run-compiler-with-content ...
result: yes
@end example

This corresponds to autoconf's @code{AC_MSG_CHECKING}.
@end defun

@defun cf-msg-result fmt arg @dots{}
@{@t{gauche.configure}@}
The @var{fmt} and @var{arg} @dots{} are passed to @code{format}, and
the formatted message and newline is written out
(@pxref{Formatting output}).
For the log file, it records ``result: XXX'' where XXX is the
formatted message.  Supposed to be used with @code{cf-msg-checking}.

This corresponds to autoconf's @code{AC_MSG_RESULT}.
@end defun

@defun cf-msg-notice fmt arg @dots{}
@{@t{gauche.configure}@}
Produces formatted message to both console and log.  Newline is added.
This corresponds to autoconf's @code{AC_MSG_NOTICE}.
@end defun

@defun cf-msg-warn fmt arg @dots{}
@defunx cf-msg-error fmt arg @dots{}
@{@t{gauche.configure}@}
Produces ``Warning: XXX'' and
``Error: XXX'' messages, respectively.
The @var{fmt} and @var{arg} @dots{} are passed to @code{format} to
generate XXX part (@pxref{Formatting output}).
These corresponds to
autoconf's @code{AC_MSG_WARN} and @code{AC_MSG_ERROR}.
@end defun

@defun cf-echo arg @dots{} [> file][>> file]
@{@t{gauche.configure}@}
Convenience routine to replace shell's @code{echo} command.

If the argument list ends with @code{> @var{file}} or
@code{>> @var{file}}, where @var{file} is a string file name,
then this works just like shell's @code{echo}; that is,
@var{arg}s except the last two are written to @var{file}, space
separated, newline terminated.  Using @code{>} supersedes
@var{file}, while @code{>>} appends to it.

If the argument list doesn't end with those redirection message,
it writes out the argument to both the current output port
and the log file, space separated, newline terminated.
For the log file, the message is prefixed with ``Message:''.
@end defun

@subsubheading Parameters and definitions

The configure script maintains two global tables, definition tables
and parameter tables.  Definition tables is used for C preprocessor
definitions, and parameter tables are used for @code{@@PARAMETER@@}
substitutions.  (Do not confuse substitution parameters with
Scheme's parameter objects (@pxref{Parameters})).

@defun cf-define symbol :optional value
@{@t{gauche.configure}@}
Registers C preprocessor definition of @var{symbol} with @var{value}.
@var{Value} can be any Scheme objects, but it is emitted to a command
line (in @code{-DSYMBOL=VALUE} form) or in @file{config.h}
(in @code{#define SYMBOL VALUE} form) using @code{display}, so
you want to avoid including funny characters.  If @var{value} is
omitted, @code{1} is assumed.

NB: To @code{#define} a string value, e.g. @code{#define FOO "foo"},
you have to call as @code{(cf-define 'FOO "\"foo\"")}.

This corresponds to autoconf's @code{AC_DEFINE}.
@end defun

@defun cf-defined? symbol
@{@t{gauche.configure}@}
Returns @code{#t} iff @var{symbol} is @code{cf-define}d.
@end defun

@defun cf-subst symbol value
@{@t{gauche.configure}@}
Registers a substitution parameter @var{symbol} with @var{value}.
@var{Value} can be any Scheme objects; its @code{display} representation
is used to substitute @var{@@SYMBOL@@} in the template.

This corresponds to autoconf's @code{AC_SUBST}, but we require
the value (while autoconf can refer to the shell variable value as default).
@end defun

@defun cf-subst-prepend symbol value :optional delim default
@defunx cf-subst-append symbol value :optional delim default
@{@t{gauche.configure}@}
Prepend or append @var{value} to the substitution parameter @var{symbol},
using delimiter @var{delim}.  If the substitution parameter isn't
defined, @var{value} becomes the sole value of the parameter,
except when @var{default} is given and not an empty string.
If @var{delim} is omitted, single whitespace is used.
@end defun

@defspec with-cf-subst ((@var{symbol} @var{value}) @dots{}) @dots{}
@{@t{gauche.configure}@}
Temporarily replace substitution parameters with new values. This
could be useful for example to run some compilation tests with
different parameters

@example
(with-cf-subst ((LIBS "-L<path> -l<lib>"))
  (cf-try-compile-and-link @dots{}))
@end example
@end defspec

@defun cf-have-subst? symbol
@{@t{gauche.configure}@}
Returns true iff @code{symbol} is registered as a substitution parameter by
@code{cf-subst}.
@end defun

@defun cf-arg-var symbol
@{@t{gauche.configure}@}
Lookup the environment variable @code{symbol} and if it is found,
use its value as the substitution value.  For example,
if you call @code{(cf-arg-var 'MYCFLAGS)}, then the user
can provide the value of @code{@@MYCFLAGS@@} as
@code{MYCFLAGS=-g ./configure}.

This corresponds to autoconf's @code{AC_ARG_VAR}, but we lack the ability
of setting the help string.  That's because @code{cf-arg-var} must
be run after @code{cf-init}, but the help message is constructed
within @code{cf-init}.
@end defun

@defun cf-ref symbol :optional default
@{@t{gauche.configure}@}
This looks up the value of the substitution parameter @var{symbol}.
If there's no such substitution parameter registered,
it returns @var{default} when it's provided, otherwise
throws an error.
@end defun

@defun cf$ symbol
@{@t{gauche.configure}@}
Looks up the value of the substitution parameter @var{cf-ref},
but it returns empty string if it's unregistered.  Useful
to use within string interpolation, e.g. @code{#"gosh ~(cf$'GOSHFLAGS)"}.
@end defun

@subsubheading Predefined tests

@defun cf-check-prog sym prog-or-progs :key value default paths filter
@defunx cf-path-prog sym prog-or-progs :key value default paths filter
@{@t{gauche.configure}@}
Check if a named executable program exists in search paths, and if it
exists, sets the substitution parameter @var{sym} to the name
of the found program.  The name to search is specified by @var{prog-or-progs},
which is either a string or a list of strings.

The difference of @code{cf-check-prog} and @code{cf-path-prog} is that
@code{cf-check-prog} uses the basename of the found program, while
@code{cf-path-prog} uses its full path.  These corresponds to
autoconf's @code{AC_CHECK_PROG}, @code{AC_CHECK_PROGS}, 
@code{AC_PATH_PROG} and @code{AC_PATH_PROGS}.

For example, the following
feature test searches either one of @code{cc}, @code{gcc}, @code{tcc}
or @code{pcc} in @code{PATH} and sets the substitution parameter @code{MY_CC}
to the name of the found one.

@example
(cf-check-prog 'MY_CC '("cc" "gcc" "tcc" "pcc"))
@end example

If multiple program names is given, the search is done in the following
order: First, we search for the first item (@code{cc}, in the above
example) for each of paths, then the second, etc.  For example,
if we have @code{/usr/local/bin:/usr/bin:/bin} in @code{PATH} and
we have @code{/usr/local/bin/tcc} and @code{/usr/bin/gcc}, the above
feature test sets @code{MY_CC} to @code{"gcc"}.  If you use @code{cf-path-prog}
instead, @code{MY_CC} gets @code{"/usr/bin/gcc"}.

If no program is found, @var{sym} is set to the keyword argument
@var{default} if it is given, otherwise @var{sym} is left unset.

If the @var{value} keyword argument is given, its value is
used instead of the found program name to be set to @var{sym}.

The list of search paths is taken from @code{PATH} environment
variable.  You can override the list by the @var{paths} keyword
argument, which must be a list of directory names.  It may contain
nonexistent directory names, which are silently skipped.

The @var{filter} keyword argument, if given, must be a predicate
that takes full pathname of the executable program.  It is called
when the procedure finds matching executable; the @var{filter} procedure
may reject it by returning @code{#f}, in which case the procedure
keeps searching.

Note: If the substitution parameter @var{sym} is already set
at the time these procedure is called, these procedures do nothing.
Combined with @code{cf-arg-var}, it allows the configure script caller
to override the feature test.  For example, suppose you have the
following in the @code{configure} script:

@example
(cf-arg-var 'GREP)
(cf-path-prog 'GREP '("egrep" "fgrep" "grep"))
@end example

A user can override the test by calling @code{configure} like this:

@example
$ ./configure GREP=mygrep
@end example

@end defun

@defun cf-prog-cxx
@{@t{gauche.configure}@}
A convenience feature test to find C++ compiler.  This searches
popular names of C++ compilers from the search paths, sets the
substitution parameter @code{CXX} to the compiler's name,
then tries to compile a small
program with it to see it can generate an executable.

This corresponds to autoconf's @code{AC_PROG_CXX}.

@code{CXX} is @code{cf-arg-var}'ed in this procedure.  If a user
provide the value when he calls @code{configure}, the searching
is skipped, but the check of generating an executable is still
performed.

If the substitution parameter @code{CXXFLAGS} is set, its value
is used to check if the compiler can generate an executable.
@code{CXXFLAGS} is @code{cf-arg-var}'ed in this procedure.

This procedure also emulates autoconf's @code{AC_PROG_CXX} behavior---
if @code{CXX} is not set, but @code{CCC} is set, then we set
@code{CXX} by the value of @code{CCC} and skip searching.
@end defun

@defun cf-header-available? header :key includes
@defunx cf-check-header header :key includes
@{@t{gauche.configure}@}
Check if a header file @var{header} exists and usable, by
compiling a source program of the current language
that includes the named header file.
Return @code{#t} if the header is usable, @code{#f} if not.

Both procedure does the same thing.  The name @code{cf-check-header}
corresponds to autoconf's @code{AC_CHECK_HEADER}.  

If @var{header} requires other headers being included or
preprocessor symbols defined before it,
you can pass a list of strings to be emitted before the check
in the @var{includes} keyword arguments.  The given strings 
are just concatenated and used as a C program fragment.
The default value is provided by @code{cf-includes-default}.

The following example sets C preprocessor symbol @code{HAVE_CRYPT_H} to
1 if @file{crypt.h} is available.  (Note: For this kind of common task,
you can use @code{cf-check-headers} below.  The advantage of using
@code{cf-check-header} is that you can write other actions in Scheme
depending on the result.)

@example
(when (cf-check-header "crypt.h")
  (cf-define "HAVE_CRYPT_H" 1))
@end example
@end defun

@defun cf-check-headers headers :key includes if-found if-not-found
@{@t{gauche.configure}@}
Codify a common pattern of checking the availability of headers and
sets C preprocessor definitions.
This corresponds to autoconf's @code{AC_CHECK_HEADERS}.
This procedure is invoked for the side effects,
and returns an undefined vlaue.

See this example:

@example
(cf-check-headers '("unistd.h" "stdint.h" "inttypes.h" "rpc/types.h"))
@end example

This checks availability of each of listed headers,
and sets C preprocessor definition @code{HAVE_UNISTD_H},
@code{HAVE_STDINT_H}, @code{HAVE_INTTYPES_H} and 
@code{HAVE_RPC_TYPES_H} to 1 if the corresponding header
file is available.

A list of strings given to @var{includes} are emitted to the
C source file before the inclusion of the testing header.  You can
give necessary headers and/or C preprocessor definitions there;
if omitted, @code{cf-includes-default} provides
the default list of such headers.

The keyword argument @var{if-found} and @var{if-not-found} are
procedures to be called when a header is found to be available or
to be unavailable, respectively.  The procedure receives the name
of the header.

The name of the C preprocessor definition is derived from the
header name by upcasing it and replacing non-alphanumeric characters
for @code{_}.  Note that this substitution is not injective:
Both @file{gdbm/ndbm.h} and @file{gdbm-ndbm.h} yield
@code{GDBM_NDBM_H}.  If you need to distinguish such files
you have to use @code{cf-check-header}.
@end defun

@defun cf-includes-default
@{@t{gauche.configure}@}
Returns a list of strings that are included in the check program by
default.  It is actually a combination of C preprocessor @code{#ifdef}s
and @code{#include}s, and would probably be better to be called
@code{cf-prologue-default} or something, but the corresponding
autoconf macro is @code{AC_INCLUDES_DEFAULT} so we stick to this name.

Usually you don't need to call this explicitly.  Not giving the
@code{includes} argument to @code{cf-check-header} and
@code{cf-check-headers} will make @code{cf-includes-default}
called implicitly.
@end defun

@defun cf-type-available? type :key includes
@defunx cf-check-type type :key includes
@{@t{gauche.configure}@}
Test if @var{type} is defined as a type name.
Return @code{#t} if @var{type} is defined, @code{#f} otherwise.

Two procedures are the same.  The name @code{cf-check-type}
corresponds to @code{AC_CHECK_TYPE}.

A list of strings given to @var{includes} are emitted to the
C source file before the inclusion of the testing header.  You can
give necessary headers and/or C preprocessor definitions there;
if omitted, @code{cf-includes-default} provides
the default list of such headers.
@end defun

@defun cf-check-types types :key includes if-found if-not-found
@{@t{gauche.configure}@}
For each type in the list @var{types}, call @code{cf-check-type} to
see it is defined as a type.  If it is,
defines @code{HAVE_@var{type}}, and calls @var{if-found} with the
type as an argument if provide.  If the type is not defined and
@var{if-not-found} is provided, calls it with the type as an argument.

The argument @var{includes} is passed to @code{cf-check-type}.

This corresponds to autoconf's @code{AC_CHECK_TYPES}.

Returns an undefiend value.  This procedure is for side effects.

@example
;; May define HAVE_PTRDIFF_T and/or HAVE_UNSIGNED_LONG_LONG_INT
;; depending on its availability:
(cf-check-types '("ptrdiff_t" "unsigned long long int"))

;; Example of using @var{includes} to add an extra header.
(cf-check-types '("float_t") 
                :includes `(,@@(cf-includes-default)
                            "#include <math.h>\n"))
@end example
@end defun

@defun cf-decl-available? symbol :key includes
@defunx cf-check-decl symbol :key includes
@{@t{gauche.configure}@}
Test if @var{symbol} is declared as a cpp macro, a variable,
a constant, or a function.
Return @code{#t} if @var{type} is defined,
@code{#f} otherwise.   

Two procedures are the same.  The name @code{cf-check-decl} corresponds
to autoconf's @code{AC_CHECK_DECL}.

A list of strings given to @var{includes} are emitted to the
C source file before the inclusion of the testing header.  You can
give necessary headers and/or C preprocessor definitions there;
if omitted, @code{cf-includes-default} provides
the default list of such headers.
@end defun

@defun cf-check-decls symbols :key includes if-found if-not-found
@{@t{gauche.configure}@}
For each symbol in @var{symbols}, call @code{cf-check-decl} to see
if it is declared.  If it is, define @code{HAVE_DECL_@var{symbol}} to
1, and calls @var{if-found} with the symbol if provided.  
If it is not declared, define @code{HAVE_DECL_@var{symbol}} to 0, 
and calls @var{if-not-found} with the symbol if provided.
This corresponds to autoconf's @code{AC_CHECK_DECLS}.

The argument @var{includes} is passed to @code{cf-check-decl}.

This procedure returns an undefined value.  This procedure is for
side effects.

Note that, unlike other @code{cf-check-*} routines which leave
@code{HAVE_*} macro undefined when the item isn't found, this one
always defines the macro and differentiate the result with its value.
This behavior is the same as @code{AC_CHECK_DECLS}.
@end defun

@defun cf-member-available? aggregate.member :key includes
@defunx cf-check-member aggregate.member :key includes
@{@t{gauche.configure}@}
The @var{aggregate.member} argument is a string of aggregate type name
and its member concatenated by a dot, e.g. @code{"struct password.pw_gecos"}.
It can also be a submember, e.g. @code{"struct foo.bar.baz"}.
The @var{aggregate} part can be any type name (typedef-ed name is ok).

This test checks if @var{member} is a member of @var{aggregate}, and
returns @code{#t} if so, or returns @code{#f} if not.

Two procedures are the same.  The name @code{cf-check-member}
corresponds to autoconf's @code{AC_CHECK_MEMBER}.

A list of strings given to @var{includes} are emitted to the
C source file before the inclusion of the testing header.  You can
give necessary headers and/or C preprocessor definitions there;
if omitted, @code{cf-includes-default} provides
the default list of such headers.
@end defun

@defun cf-check-members members :key includes if-found if-not-found
@{@t{gauche.configure}@}
For each @var{aggregate.member}
in @var{members}, call @code{cf-check-member}.
If the test passes, defines @code{HAVE_@var{aggregate}_@var{member}},
and calls @var{if-found} with @var{aggregate.member} if provided.
If the test fails, calls @var{if-not-found} with @var{aggregate.member}
if provided.

This corresponds to autoconf's @code{AC_CHECK_MEMBERS}.

The @var{include} argument is passed to @code{cf-check-member}.

@example
;; Defines HAVE_STRUCT_ST_RDEV and/or HAVE_STRUCT_ST_BLKSIZE
;; depending on their availability:
(cf-check-members '("struct stat.st_rdev"
                    "struct stat.st_blksize"))
@end example

This procedure is for side effects, and returns an undefined value.
@end defun

@defun cf-func-available? func
@defunx cf-check-func func
@{@t{gauche.configure}@}
See if a function @var{func} is available.  This emits C code
to call @var{func} (with dummy declaration) and tries to compile and link,
using current value of substitution parameter @code{LIBS}.
The value of @code{cf-includes-default} is at the top of the emitted C code.

They return @code{#t} if @var{func} is available, @code{#f} otherwise.

Two procedures are the same.  The name @code{cf-check-func}
corresponds to autoconf's @code{AC_CHECK_FUNC}.
@end defun

@defun cf-check-funcs funcs :key if-found if-not-found
@{@t{gauche.configure}@}
For each function name @var{func} in @var{funcs}, call @code{cf-check-func}
to determine availability.  If it is available, define
@code{HAVE_@var{func}}, and calls @code{if-found} with @var{func}
if provided.  If it is not available, calls @code{if-not-found}
with @var{func} if provided.

This corresponds to autoconf's @code{AC_CHECK_FUNCS}.

This procedure is for side effects, and returns an undefined value.
@end defun

@defun cf-lib-available?  lib fn :key other-libs if-found if-not-found
@defunx cf-check-lib lib fn :key other-libs if-found if-not-found
@{@t{gauche.configure}@}
See if a library @var{lib} can be linked and a function @var{fn} in it
is callable.  Return @code{#t} it is, @code{#t} if not.

Two procedures are the same.  The name @code{cf-check-lib}
corresponds to autoconf's @code{AC_CHECK_LIB}.

Give the name you pass after @code{-l} option to @var{lib};
for example, if you want to check availability of @code{libm}, you can
say as follows:

@example
(cf-check-lib "m" "sin")
@end example

This generates a C source that calls @var{fn} and try to compile and link
it to generate executable.  If linking @var{lib} requires additional
libraries, it should be listed in @var{other-libs}:

@example
(cf-check-lib "Xt" "XtDisplay" :other-libs '("-lX11" "-lSM" "-lICE"))
@end example

If compilation and linking succeeds, 
@var{if-found} is called at the
tail position with
the library name (@code{"m"} and @code{"Xt"} in the above examples,
respectively) as the argument. 
The default behavior is to add
@code{-l@var{lib}} in the left of substitution parameter @code{LIBS},
and set @code{HAVE_LIB@var{lib}} definition, then
returns @code{#t}.

If compilation or linking fails, @var{if-not-found} is called at
the tail position with the library name.  The default behavior is
to return @code{#f}.

The default behavior of @var{if-found} and @var{if-not-found} allows
@code{cf-check-lib} to be used as predicate as well.  If you merery
want to take an action depending on whether the library is found or
not, you can write like this:

@example
(unless (cf-check-lib "foo" "foo_fn)
  ... do something if libfoo isn't available ...)
@end example

Use @var{if-found} and/or @var{if-not-found} only if you want to
override the default behaviors.
@end defun

@defun cf-search-libs fn libs :key other-libs if-found if-not-found
@{@t{gauche.configure}@}
Like @code{cf-check-lib}, but can be used if you're not sure which
library contains desired function.
This corresponds to autoconf's @code{AC_SEARCH_LIBS}.  Note that
this takes function name first, while @code{cf-check-lib} takes
function name second---blame autoconf for this inconsistency.

First it tests if @var{fn} is available without any library in @var{libs}
(that is, with the ones already in @code{LIBS} and specified in
@var{other-libs}).  If not, it tests each library in @var{libs}
in turn.

If @var{fn} is found, @var{if-found} is called at the tail position,
with the name of
the library as an argument (if @var{fn} is available without any
library, the argument is @code{#f}).  If omitted, and a library
is required, then the library is
added to the substitution parameter @code{LIBS}, and @code{HAVE_LIB@var{lib}}
is defined.  The default procedure returns @code{#t}.

If @var{fn} isn't found in any of the libraries, @var{if-not-found}
is called at the tail position
with @code{#f} as the argument.  The default procedure
does nothing and just returns @code{#f}.

The default behavior of @var{if-found} and @var{if-not-found} allows
@code{cf-search-libs} to be used as predicate as well.

This procedure is for side effects, and returns an undefiend vlaue.
@end defun


@subsubheading Running compiler

The @code{gauche.configure} module provides a generic mechanism
to construct a small test program, compile it, and run it.
Currently we only support @code{C} and @code{C++}; we'll add support
for other languages as needed.

@deffn {Parameter} cf-lang
@{@t{gauche.configure}@}
@end deffn

@defun cf-lang-program prologue body
@{@t{gauche.configure}@}
Returns a string tree that consists a stand-alone program for
the current language.  @var{Prologue} and @var{body} must be a
string tree.  @var{Prologue} comes at the beginning of
the source, and @var{body} is included in the part of the program
that's executed.  If the current language is C, the code fragment:

@example
(use text.tree)
(write-tree (cf-lang-program "#include <stdio.h>\n" "printf(\"()\");\n"))
@end example

would produce something like this:

@example
#include <stdio.h>

int main()@{
printf("()");

; return 0;
@}
@end example
@end defun

@defun cf-lang-io-program
@{@t{gauche.configure}@}
This is a convenience routine.  It returns a string tree
of a program in the current language, that creates a file 
named @file{conftest.out}, then exits with zero status on
success, or nonzero status on failure.
@end defun

@defun cf-lang-call prologue func-name
@{@t{gauche.configure}@}
@end defun

@defun cf-try-compile prologue body
@{@t{gauche.configure}@}
@end defun

@defun cf-try-compile-and-link prologue body
@{@t{gauche.configure}@}
@end defun



@subsubheading Output

@defun cf-output-default file @dots{}
@{@t{gauche.configure}@}
A convenience routine to produce typical output.
It does the following:

@itemize @bullet
@item
Generate gpd (Gauche package description) file using
@code{cf-make-gpd}.
@item
Generate @code{VERSION} file that contains the value of
@code{PACKAGE_VERSION} substitution parameter.
@item
Search @code{Makefile.in}'s under the source directory
(the value of substitution parameter @code{srcdir}),
and process them to produce @code{Makefile}'s.
If @var{file} @dots{} are given, @code{@var{file}.in} are also
processed as well to produce @var{file}.

See @code{cf-output} below for the details.
@item
If config header is registered by @code{cf-config-headers},
process them as well.
@end itemize
@end defun

@defun cf-output file @dots{}
@{@t{gauche.configure}@}
Generates @var{file}'s from the input templates.
This corresponds to autoconf's @code{AC_OUTPUT}.

For each @var{file}, a file named @file{@var{file}.in} is read
as a template.  Within the file, @code{@@PARAMETER@@} is substituted
with the value of @code{(cf$ 'PARAMETER)}.  If the named parameter
isn't registered, a warning is issued and the parameter is left
unsubstituted.

If config headers are not registered via @code{cf-config-headers},
a substitution parameter @code{DEFS} is replaced with
all the definitions in the form of @code{-D...}.  For example,
if you have checked header files @file{foo/bar.h} and
@file{foo/baz.h}, @code{DEFS} gets the value
@code{-DHAVE_FOO_BAR_H -DHAVE_FOO_BAZ_H}.

If config header is registered by @code{cf-config-headers},
they are processed as well.  In such case, the substitution
parameter @code{DEFS} gets the value @code{-DHAVE_CONFIG_H}.
@end defun

@defun cf-config-headers header-or-headers
@{@t{gauche.configure}@}
Sets up config header files to be processed.  Usually a config header
file is named @file{config.h}, and contains definitions determined
by feature tests.

The @var{header-or-headers} argument may be a string header-spec
or a list of string header-specs, where each header spec is
a header file name (e.g. @code{"config.h"}) or a header name
and a input file name concatenated with a colon
(e.g. @code{"config.h:config.h.templ"}).  If it's just a header name,
input file name is assumed to be the header file name with @code{".in"}
appended.

The input template of config header file contains a bunch of
@code{#undef} directives, such as the following:

@example
/* Gauche ABI version string */
#undef GAUCHE_ABI_VERSION

/* Define if Gauche handles multi-byte character as EUC-JP */
#undef GAUCHE_CHAR_ENCODING_EUC_JP

/* Define if Gauche handles multi-byte character as Shift JIS */
#undef GAUCHE_CHAR_ENCODING_SJIS

/* Define if Gauche handles multi-byte character as UTF-8 */
#undef GAUCHE_CHAR_ENCODING_UTF_8
@end example

Once processed, the generated header file has either
@code{#undef} line is replaced with @code{#define}, or
commented out, depending on the definitions determined by feature
tests.

@example
/* Gauche ABI version string */
#define GAUCHE_ABI_VERSION "0.97"

/* Define if Gauche handles multi-byte character as EUC-JP */
/* #undef GAUCHE_CHAR_ENCODING_EUC_JP */

/* Define if Gauche handles multi-byte character as Shift JIS */
/* #undef GAUCHE_CHAR_ENCODING_SJIS */

/* Define if Gauche handles multi-byte character as UTF-8 */
#define GAUCHE_CHAR_ENCODING_UTF_8 /**/
@end example

Note that the lines other than @code{#undef} are copied as they are.

The substitution parameter @code{DEFS} behaves differently whether
config header is specified or not.  If no config header is registered,
The value of @code{DEFS} is a C command-line arguments for definitions,
e.g. @code{-DGAUCHE_ABI_VERSION=0.97 -DGAUCHE_CHAR_ENCODING_UTF8}.
If config header files are registered, the value of @code{DEFS} becomes
simply @code{-DHAVE_CONFIG_H}.
@end defun


@defun cf-show-substs :key formatter
@{@t{gauche.configure}@}
Print all substitution parameters; this is for debugging.

For each substitution parameter name and value, 
@var{formatter} is called with them; the default is
@code{(^[k v] (format #t "~16s ~s" k v))}.
@end defun

@defun cf-make-gpd
@{@t{gauche.configure}@}
Generate gpd (Gauche package description) file,
@file{PACKAGE_NAME.gpd}, where @code{PACKAGE_NAME} is the
package's name either taken form @file{package.scm} or
the argument to @code{cf-init}.
@xref{Package metainformation}, for the package description file format.
@end defun


@c ----------------------------------------------------------------------
@node Connection framework, Dictionary framework, Generating build files, Library modules - Gauche extensions
@section @code{gauche.connection} - Connection framework
@c NODE コネクションフレームワーク, @code{gauche.connection} - コネクションフレームワーク

@deftp {Module} gauche.connection
@mdindex gauche.connection
A connection is an abstract class to handle full-duplex
communication channel.  The actual data I/O is done through
Scheme ports; a channel provides an interface to retrieve those
ports.  It also has interface to know endpoint names, and the
way to shutdown the communication.

The @code{<socket>} class, for example, implements the connection
framework (@pxref{Networking}).  The @code{<tls>} class, which
wraps a socket to provide TLS communication, also implements it.
That means you can write a client code that works both plain
socket connection and secure connection.
You can also abstract communication to the external process
as a connection (@pxref{Process connection}).

Each of the connection endpoints (@emph{self} for our side,
and @emph{peer} fo the other side) has @emph{addresses},
some object that identifies the endpoint.  The framework
doesn't specify the actual type of addresses; it only requires
that addresses can be passed to @code{connection-address-name} method
to get its string representation, so that can be used for logging
and monitoring.  The concrete
class can choose suitable address representation.  For example,
@code{<socket>} uses @code{<sockaddr>} for the addresses.

A concrete class must implement the following methods.

@example
connection-self-address (c <connection>)
connection-peer-address (c <connection>)
connection-input-port (c <connection>)
connection-output-port (c <connection>)
connection-shutdown (c <connection>) how
connection-close (c <connection>)
connection-address-name obj                ; optional
@end example

At this moment this framework doesn't provide a generic way to
@emph{create} a connection, since the way to do it may greatly vary
depending on the concrete implementation.  Each concrete implementation
should provide its own procedure to create and return a new connection.
@end deftp


@deffn {Method} connection-self-address connection
@deffnx {Method} connection-peer-address connection
Returns the address of this @var{connection}'s endpoint and
its peer's.  For sockets and @code{<tls>}, it is an instance
of @code{<sockaddr>}.  For processes, it is a string
describing the process.

If @var{connection} is not connected, these methods can return @code{#f}.

The returned value (other than @code{#f}) must be able to
be passed to @code{connection-address-name} method.

Currently addresses are only used for logging purpose within
the connection framework; however, we may enhance the framework
to add ``connect'' operation, for example, so the concrete class
is encouraged to use objects that can be used to create connections.
@end deffn

@deffn {Method} connection-address-name address
This method returns a string representation of @var{address}, which is
a returned value from @code{connection-self-address} and
@code{connection-peer-address}.  The default method just uses
@var{address}'s @code{display}-representation.  If a concrete
class chooses aggregate objects to represent addresses, it should
provide this method as well.
@end deffn

@deffn {Method} connection-input-port connection
@deffnx {Method} connection-output-port connection
Returns an input port and an output port to read from and write to
the connection, respectively.

If the connection is not connected, or already shutdown or closed,
the return value of these methods are unspecified.
@end deffn

@deffn {Method} connection-shutdown connection :optional how
Shutdown the connection.  You can either shutdown the connection
entirely at once, or shutdown only read or write channel of it.

Shutdown is about telling the peer to terminate the communication.
Usually the peer will detect the termination by reading EOF from
their input channel.  The port corresponding to the shutdown channel
is closed so no further communication is possible.

Note that merely closing the connection doesn't shutdown the
connection---the process may fork after creating the connection,
and in that case, one process may close the connection without
shutting down.

The @var{how} argument must be one of those symbols:
@table @code
@item read
Shutdown read channel of the connection.
@item write
Shutdown write channel of the connection.
@item both
Shutdown both channels of the connection.
@end table

If omitted, @var{both} is assumed.

Shutting down already shut down channel has no effect.

Note: Some concrete implementation of connection may not allow
to shutdown each channels independently.  In such case,
the connection is shut down entirely regardless of @var{how} argument.

The one-argument case is handled by the default method (it calls
two-argument method with @code{both} as @var{how}).  So the
concrete class only need to define two argument method.
@end deffn

@deffn {Method} connection-close connection
Close the connection.  This destroys the connection and frees
local resources.  Note that this does not shutdown the connection
itself.  If this connection is the only endpoint of this side,
the peer will get an error when it tries to communicate.

See @code{connection-shutdown} for the details of shutting down
a connection.
@end deffn

@c ----------------------------------------------------------------------
@node Dictionary framework, Low-level file operations, Connection framework, Library modules - Gauche extensions
@section @code{gauche.dictionary} - Dictionary framework
@c NODE ディクショナリフレームワーク, @code{gauche.dictionary} - ディクショナリフレームワーク

@deftp {Module} gauche.dictionary
@mdindex gauche.dictionary
A dictionary is an abstract class for objects that can
map a key to a value.  This module provides some useful generic
functions for dictionaries, plus generic dictionary classes
built on top of other dictionary classes.
@end deftp

@menu
* Generic functions for dictionaries::
* Generic dictionaries::
@end menu

@node Generic functions for dictionaries, Generic dictionaries, Dictionary framework, Dictionary framework
@subsection Generic functions for dictionaries
@c NODE ディクショナリのためのジェネリック関数

These generic functions are useful to implement algorithms
common to any dictionary-like objects, a data structure
that maps discrete, finite set of keys to values.  
(Theoretically we can think of continuous and/or infinite set of
keys, but implementation-wise it is cleaner to limit the dictionary

Among built-in classes, @code{<hash-table>} and @code{<tree-map>}
implement the dictionary interface.  All the @code{<dbm>} classes
provided by @code{dbm} module also implement it.

To make your own class implement the dictionary interface, you have
to provide at least @code{dict-get}, @code{dict-put!},
@code{dict-delete!}, @code{dict-fold} and @code{dict-comparator}.
(You can omit @code{dict-delete!} if the datatype doesn't allow
deleting entries.)
Other generic functions
have default behavior built on top of these.  You can
implement other methods as well, potentially to gain better performance.

(Note: Dictionaries are also collections, so you can use collection
methods as well; for example, to get the number of entries, just use
@code{size-of}).

@deffn {Generic function} dict-get (dict @code{<dictionary>}) key :optional default
@{@t{gauche.dictionary}@}
Returns the value corresponding to the @var{key}.
If the dictionary doesn't have an entry with @var{key},
returns @var{default} when it is provided, or raises an error
if not.
@end deffn

@deffn {Generic function} dict-put! (dict @code{<dictionary>}) key value
@{@t{gauche.dictionary}@}
Puts the mapping from @var{key} to @var{value} into the dictionary.
@end deffn

@deffn {Generic function} {(setter dict-get)} (dict @code{<dictionary>}) key value
@{@t{gauche.dictionary}@}
This works the same as @code{dict-put!}.
@end deffn

@deffn {Generic function} dict-exists? (dict @code{<dictionary>}) key
@{@t{gauche.dictionary}@}
Returns @code{#t} if the dictionary has an entry with @var{key},
@code{#f} if not.
@end deffn

@deffn {Generic function} dict-delete! (dict @code{<dictionary>}) key
@{@t{gauche.dictionary}@}
Removes an entry with @var{key} form the dictionary.
If the dictionary doesn't have such an entry, this function is noop.
@end deffn

@deffn {Generic function} dict-clear! (dict @code{<dictionary>})
@{@t{gauche.dictionary}@}
Empties the dictionary.  Usually this is much faster than looping
over keys to delete them one by one.
@end deffn

@deffn {Generic function} dict-comparator (dict @code{<dictionary>})
@{@t{gauche.dictionary}@}
Should return a comparator used to compare keys.
@end deffn

@deffn {Generic function} dict-fold (dict @code{<dictionary>}) proc seed
@{@t{gauche.dictionary}@}
Calls a procedure @var{proc} over each entry in a dictionary @var{dict},
passing a seed value.  Three arguments are given to @var{proc};
an entry's key, an entry's value, and a seed value.  Initial
seed value is @var{seed}.  The value returned from @var{proc} is used
for the seed value of the next call of @var{proc}.  The result of the
last call of @var{proc} is returned from @var{dict-fold}.

If @var{dict} is @code{<ordered-dictionary>}, @var{proc} is called
in the way to keep the following associative order, where
the key is ordered from @var{K0} (minimum) to @var{Kn} (maximum), and
the corresponding values is from @var{V0} to @var{Vn}:
@example
(proc Kn Vn (proc Kn-1 Vn-1 ... (proc K0 V0 seed)))
@end example
@end deffn

@deffn {Generic function} dict-fold-right (dict @code{<ordered-dictionary>}) proc seed
@{@t{gauche.dictionary}@}
Like @code{dict-fold}, but the associative order of applying @var{proc}
is reversed as follows:
@example
(proc K0 V0 (proc K1 V1 ... (proc Kn Vn seed)))
@end example

This generic function is only defined on @code{<ordered-dictionary>}.
@end deffn

@deffn {Generic function} dict-for-each (dict @code{<dictionary>}) proc
@{@t{gauche.dictionary}@}
Calls @var{proc} with a key and a value of every entry in
the dictionary @var{dict}.  For ordered dictionaries, @var{proc}
is guaranteed to be called in the increasing order of keys.
@end deffn

@deffn {Generic function} dict-map (dict @code{<dictionary>}) proc
@{@t{gauche.dictionary}@}
Calls @var{proc} with a key and a value of every entry in
the dictionary @var{dict}, and gathers the result into a list
and returns it.  For ordered dictionaries, the result is in
the increasing order of keys (it doesn't necessarily mean @var{proc}
is called in that order).
@end deffn

@deffn {Generic function} dict-keys (dict @code{<dictionary>})
@deffnx {Generic function} dict-values (dict @code{<dictionary>})
@{@t{gauche.dictionary}@}
Returns a list of all keys or values of a dictionary @var{dict},
respectively.  For ordered dictionaries, the returned list is
in the increasing order of keys.
@end deffn

@deffn {Generic function} dict->alist (dict @code{<dictionary>})
@{@t{gauche.dictionary}@}
Returns a list of pairs of key and value in the dictionary.
The order of pairs is undefined.
@end deffn

@deffn {Generic function} dict-push! (dict @code{<dictionary>}) key value
@{@t{gauche.dictionary}@}
A shorthand way to say @code{(dict-put! dict key (cons value (dict-get dict key '())))}.  A concrete implementation may be more efficient
(e.g. it may not search @var{key} twice.)
@end deffn

@deffn {Generic function} dict-pop! (dict @code{<dictionary>}) key :optional fallback
@{@t{gauche.dictionary}@}
If @code{(dict-get dict key)} is a pair @var{p},
the entry value is replaced with @code{(cdr p)} and the procedure
returns @code{(car p)}.  If no entry for @var{key} is in the table,
or the entry isn't a a pair, the table isn't modified, and
@var{fallback} is returned if given, or an error is raised.
@end deffn

@deffn {Generic function} dict-update! (dict @code{<dictionary>}) key proc :optional fallback
@{@t{gauche.dictionary}@}
Works like the following code, except that the concrete implementation
may be more efficient by looking up @var{key} only once.
@example
(rlet1 x (proc (dict-get dict key fallback))
  (dict-put! dict key x))
@end example
@end deffn

@defmac define-dict-interface dict-class method proc method2 proc2 @dots{}
@{@t{gauche.dictionary}@}
Many dictionary-like datatypes already has their own procedures
that directly corresponds to the generic dictionary API, and adding
dictionary interface tends to become a simple repetition of
@code{define-method}s, like this:

@example
(define-method dict-put! ((dict <my-dict>) key value)
  (my-dict-put! key value))
@end example

The @code{define-dict-interface} macro is a convenient way to
define those methods in a batch.  Each @var{method} argument is
a keyword that corresponds to @code{dict-@var{method}}, and @var{proc}
is the name of the datatype-specific procedure.  Here's the definition
of dict interface for @code{<tree-map>} and you'll get the idea.
You don't need to provide every dictionary interface.

@example
(define-dict-interface <tree-map>
  :get        tree-map-get
  :put!       tree-map-put!
  :delete!    tree-map-delete!
  :clear!     tree-map-clear!
  :comparator tree-map-comparator
  :exists?    tree-map-exists?
  :fold       tree-map-fold
  :fold-right tree-map-fold-right
  :for-each   tree-map-for-each
  :map        tree-map-map
  :keys       tree-map-keys
  :values     tree-map-values
  :pop!       tree-map-pop!
  :push!      tree-map-push!
  :update!    tree-map-update!
  :->alist    tree-map->alist)
@end example
@end defmac


@node Generic dictionaries,  , Generic functions for dictionaries, Dictionary framework
@subsection Generic dictionaries
@c NODE 汎用ディクショナリ

@subsubheading Bimap


@deftp {Class} <bimap>
@clindex bimap
@{@t{gauche.dictionary}@}
Provides a bidirectional map (@emph{bimap}), a relation between two
set of values, of which you can lookup both ways.

Internally, a bimap consists of two dictionaries, @emph{left} map
and @emph{right} map.  Think a bimap as a relation between @var{x}s
and @var{y}s.  The left map takes an @var{x} as a key and returns
corresponding @var{y} as its value.  The right map takes an @var{y}
as a key and returns corresponding @var{x} as its value.

Currently, @code{<bimap>} only supports strict one-to-one mapping.
Mutating interface (@code{bimap-*-put!}, @code{bimap-*-delete!} etc)
modifies both left and right maps to maintain this one-to-one mapping.
(In future, we may provide an option to make many-to-one and
many-to-many mappings).

A bimap can be used as a dictionary, with the generic dictionary
functions such as @code{dict-get}.  In such cases, the left map takes
precedence; that is, the key given to @code{dict-get} etc. is
regarded as the key to the left map.
@end deftp

@defun make-bimap left-map right-map :key on-conflict
@{@t{gauche.dictionary}@}
Creates a new bimap consists of two dictionaries, @var{left-map}
and @var{right-map}.   It is the caller's responsibility to
choose appropriate type of dictionaries; for example, if you want
to create a relation between a string and a number, you man want
to create it like this:

@example
(make-bimap (make-hash-table 'string=?)  ; string -> number
            (make-hash-table 'eqv?))     ; number -> string
@end example

The keyword argument @var{on-conflict} specifies what will happen
when the added entry would conflict the existing entries.
The following values are allowed:

@table @code
@item :supersede
This is the default behavior.  Duplicate relations are silently
removed in order to maintain one-to-one mapping.  For example,
suppose a bimap between strings and numbers has had
@code{("foo", 1)} and @code{("bar", 2)}.  When you try to
put @code{("bar", 2)} with this option, the first two entries
are removed.  Returns @code{#t}.

@item :error
Raises an error when duplicate relations are found.

@item #f
When duplicate relations are found, does nothing and returns @code{#f}.
@end table

Note: At this moment, an attempt to add a relation exactly same as the
existing one is regarded as a conflict.  This limitation may be
lifted in future.
@end defun

@defun bimap-left bimap
@defunx bimap-right bimap
@{@t{gauche.dictionary}@}
Returns the left or right map of @var{bimap}, respectively.
Do not mutate the returned map, or you'll break
the consistency of the bimap.
@end defun

@defun bimap-left-get bimap key :optional default
@defunx bimap-right-get bimap key :optional default
@{@t{gauche.dictionary}@}
Lookup the value corresponding to the @var{key} in the left or right
map of @var{bimap}.   If no entry is found for @var{key},
@var{default} is returned if provided, otherwise an error is
raised.
@end defun

@defun bimap-left-exists? bimap key
@defunx bimap-right-exists? bimap key
@{@t{gauche.dictionary}@}
Returns @code{#f} if the left or right map of @var{bimap} has an entry of
the key, @code{#t} otherwise.
@end defun

@defun bimap-put! bimap x y :key on-conflict
@{@t{gauche.dictionary}@}
Put a relation (@var{x}, @var{y}) into the bimap.
After this, @code{(bimap-left-get @var{x})} will return @var{y},
and @code{(bimap-right-get @var{y})} will return @var{x}.

If the bimap already have relations with @var{x} and/or @var{y},
the conflict is handled according to the value of @var{on-conflict};
see @code{make-bimap} for the possible values and their meanings.
The @var{on-conflict} keyword argument can override the
bimap's default setting specified at its creation time.
@end defun

@defun bimap-left-delete! bimap key
@defunx bimap-right-delete! bimap key
@{@t{gauche.dictionary}@}
Deletes an relation with the given left key or right key from @var{bimap}.
Both left and right maps are modified so that the consistency is maintained.
If there's no relations with given key, these are noop.
@end defun

@subsubheading Stacked map

@deftp {Class} <stacked-map>
@{@t{gauche.dictionary}@}
Stacked map allows you to stack (layer) multiple maps (dictionaries)
and treat as if they are a single map.  
The upper map "shadows" the lower maps.  Think of nested scopes, for
example.

As a dictionary, it behaves as follows:

@itemize @bullet
@item
The @code{dict-get} operation searches the given key from the top
dictionary to the bottom dictionary, returns the first found entry.
@item
The @code{dict-put!} operation always put the entry to the topmost
dictionary.  If there's an entry with the same key exists in a
lower dictionary, it will be shadowed.
If you want to alter the existing entry of non-top dictionary,
use @code{stacked-map-entry-update!}.
@item
The @code{dict-delete!} operations deletes all the entries with the
given key from all the dictionaries.  This is for consistency as
a dictionary---you don't want an entry pop up after deleting it.
If you want to delete only from the first entry in the stack,
use @code{stacked-map-entry-delete!}.
@item
The @code{dict-fold} operation traverse all the dictionaries
from top to bottom.  When there are duplicate keys, the second and after
will be skipped.
@end itemize
@end deftp


@defun make-stacked-map dic dic2 @dots{}
@defunx make-stacked-map key-comparator dic dic2 @dots{}
Creates a new stacked map with the given dictionaries
@var{dic} @var{dic2} @dots{}, where @var{dic} is the topmost dictionary.
You can give a comparator
@var{key-comparator} to be used to compare keys during
traversal with @code{dict-fold}.  If @var{key-comparator} is
omitted, the comparator from @var{dic} is used.
The key comparator is returned from @code{dict-comparator}
on the stacked map.
@end defun

@deffn {Method} staked-map-stack (smap <stacked-map>) (dic <dictionary>)
Creates a new stacked map, adding @var{dic} on top of the existing
stacked map @var{smap}.  The key comparator is inherited from
@var{smap}.
@end deffn

@deffn {Method} staked-map-push! (smap <stacked-map>) (dic <dictionary>)
Adds @var{dic} on top of the dictionaries @var{smap} holds.
@end deffn

@deffn {Method} staked-map-pop! (smap <stacked-map>)
Remove the topmost dictionary @var{smap} holds.  An error is signaled
if you attempt to pop from an @var{smap} that has no dictionaries.
@end deffn

@deffn {Method} staked-map-depth (smap <stacked-map>)
Returns a number of dictionaries @var{smap} has.
@end deffn

@deffn {Method} staked-map-entry-update! (smap <stacked-map>) key proc :optional fallback
Run @code{(dict-update! d @var{key} @var{proc} @var{fallback})} on the
first dictionary @code{d} that has the given key.

This differs from running @code{dict-update!} on @var{smap}; if the topmost
dictionary doesn't have an entry with @var{key} but some lower dictionary has,
@code{dict-update!} takes the existing value and applies @var{proc} to it,
then insert the result to the topmost dictionary, while the original entry
remains intact.
@end deffn

@deffn {Method} staked-map-entry-delete! (smap <stacked-map>) key
Deletes the first entry with @var{key}.  If there's another entry
with @var{key} in a lower dictionary, it will become visible.

This differs from running @code{dict-delete!} on @var{smap}; it
deletes all entries with @var{key}, so that @code{dict-exists?}
after @code{dict-delete!} is guaranteed to return @code{#f}.
@end deffn


@c ----------------------------------------------------------------------
@node Low-level file operations, Generators, Dictionary framework, Library modules - Gauche extensions
@section @code{gauche.fcntl} - Low-level file operations
@c NODE 低レベルファイル操作, @code{gauche.fcntl} - 低レベルファイル操作

@deftp {Module} gauche.fcntl
@mdindex gauche.fcntl
Provides interface for low-level filesystem operations,
including @code{fcntl(2)}.
@end deftp

@defun sys-fcntl port-or-fd operation :optional arg
@{@t{gauche.fcntl}@}
Performs certain operation on the file specified by @var{port-or-fd},
which should be a port object or an integer
that specifies a system file descriptor.  If it is a port, it must
be associated to the opened file (i.e. @code{port-type}
returns @code{file}, see @ref{Common port operations}).

The operation is specified by an integer @var{operation}.
Several variables are defined for valid @var{operation}.

@table @code
@item F_GETFD
@vindex F_GETFD
@vindex FD_CLOEXEC
Returns flags associated to the file descriptor of @var{port-or-fd}.
The optional argument @var{arg} is not used.   The return value is
an integer whose definition is system specific, except one flag,
@code{FD_CLOEXEC}, which indicates the file descriptor should be
closed on @code{exec}.  See the manual entry of @code{fcntl(2)} of
your system for the details.

@item F_SETFD
@vindex F_SETFD
Sets the file descriptor flags given as @var{arg} to @var{port-or-fd}.
For example, the portable way of setting @code{FL_CLOEXEC} flag is
as follows:
@example
(sys-fcntl port F_SETFD
          (logior FD_CLOEXEC
                  (sys-fcntl port F_GETFD)))
@end example

@item F_GETFL
@vindex F_GETFL
Returns flags associated to the open files specified by @var{port-or-fd}.
The flags includes the following information:

@itemize @bullet
@item
@vindex O_ACCMODE
@vindex O_RDONLY
@vindex O_WRONLY
@vindex O_RDWR
File access mode.  When masked by @code{O_ACCMODE},
it's either one of @code{O_RDONLY}, @code{O_WRONLY} or @code{O_RDWR}.
@item
@vindex O_CREAT
@vindex O_EXCL
@vindex O_TRUNC
File creation options.  @code{O_CREAT}, @code{O_EXCL} and/or
@code{O_TRUNC}.
@item
@vindex O_APPEND
Whether appending is allowed or not, by @code{O_APPEND}
@item
@vindex O_CLOEXEC
Whether the file is closed automatically on @code{fork}.
@item
@vindex O_NONBLOCK
Whether I/O is blocking or non-blocking, by @code{O_NONBLOCK}.
@item
@vindex O_NOCTTY
Whether it grabs terminal control, by @code{O_NOCTTY}.
@item
@vindex O_NOFOLLOW
Let the system call fail with @code{ELOOP}
when the pathname is a symbolink link.
@end itemize

The system may define system-specific flags.

@item F_SETFL
@vindex F_SETFL
Sets flags to the open files specified by @var{port-or-fd}.
Among the flags listed above, only @code{O_NONBLOCK} and @code{O_APPEND}
can be changed.

Note that @code{F_GETFD}/@code{F_SETFD} concern flags associated
to the file descriptor itself, while @code{F_GETFL}/@code{F_SETFL}
concern flags associated to the opened file itself.  This makes difference
when more than one file descriptor points to the same opened file.

@item F_DUPFD
@vindex F_DUPFD
Creates new file descriptor that points to the same file referred by
@var{port-or-fd}.
An integer must be provided as @var{arg}, and that specifies
the minimum value of file descriptor to be assigned.

@item F_GETLK
@vindex F_GETLK
The third argument must be provided and be an instance of @code{<sys-flock>}
object described below.  It searches the lock information specified by
@var{arg}, and modifies @var{arg} accordingly.

@item F_SETLK
@itemx F_SETLKW
@vindex F_SETLK
@vindex F_SETLKW
The third argument must be provided and be an instance of @code{<sys-flock>}
object described below.  Sets the advisory file lock according to
@var{arg}.   If the lock is successfully obtained, @code{#t} is returned.
If the other process has the lock conflicting the request,
@code{F_SETLK} returns @code{#f}, while @code{F_SETLKW} waits until
the lock is available.

@item F_GETOWN
@vindex F_GETOWN
Returns the process id or process group that will receive
SIGIO and SIGURG signals for events on the file descriptor.
Process group is indicated by a negative value.
This flag is only available on the systems that has this
feature (BSD and Linux have this).

@item F_SETOWN
@vindex F_SETOWN
Sets the process id or process group that will receive SIGIO
and SIGURG signals for events on the file descriptor.
Process group is indicated by a negative value.
This flag is only available on the systems that has this
feature (BSD and Linux have this).
Check out fcntl(2) manpage of your system for the details.

@end table

Other value for @var{operation} causes an error.
@end defun

@deftp {Builtin Class} <sys-flock>
@clindex sys-flock
@{@t{gauche.fcntl}@}
A structure represents POSIX advisory record locking.
Advisory record locking means the system may not prevents the process
from operating on files that it doesn't have an appropriate lock.
All the processes are expected to use @code{fcntl} to check locks
before it operates on the files that may be shared.

The following slots are defined.

Note that @code{fcntl} lock is per-process, per-file.  If you try
to lock the same file more than once within the same process, it always
succeeds.  But it's not a recursive lock, so the process loses
any locks to the file as soon as any of such lock is released,
or any of such file is closed.   It makes @code{fcntl} lock difficult
to use in libraries.  See @code{with-lock-file} (@pxref{Lock files}) for
an alternative way to realize inter-process locks.

@defivar {<sys-flock>} type
An integer represents lock type.  Following variables are predefined
for the valid values:

@table @code
@item F_RDLCK
@vindex F_RDLCK
Read locking
@item F_WRLCK
@vindex F_WRLCK
Write locking
@item F_UNLCK
@vindex F_UNLCK

To remove a lock by @code{F_SETLK}, or to indicate the record is not
locked by @code{F_GETLK}.
@end table
@end defivar

@defivar {<sys-flock>} whence
Indicates from where @code{start} is measured.
@end defivar

@defivar {<sys-flock>} start
The offset of beginning of the locked region.
@end defivar

@defivar {<sys-flock>} len
The number of bytes to lock.  Zero means ``until EOF''.
@end defivar

@defivar {<sys-flock>} pid
An integer process id that holding the lock; used only by @code{F_GETLK}.
@end defivar
@end deftp


@defun sys-open path flags :optional mode
@{@t{gauche.fcntl}@}
A low-level interface corresponds to POSIX open().
Open a file named by @var{path}, and returns an integer file descriptor.
The file descriptor should be closed with @code{sys-close},
or can be turned into a port by @code{open-@{input|output@}-fd-oprt}
and to be closed when the port is closed.

This is provided for the code that needs to deal with low-level fd.
Unless absolutely necessary, user code should use
high-level @code{open-@{input|output@}-file}.

The @var{flags} argument is a logical ior of
bitmasks @code{O_RDONLY}, @code{O_WRONLY}, @code{O_RDWR},
@code{O_APPEND}, @code{O_CREAT}, @code{O_EXCL}, @code{O_TRUNC},
@code{O_CLOEXEC}, @code{O_NOCTTY}, @code{O_NOFOLLOW},
@code{O_NONBLOCK} and @code{O_ASYNC}.  Either one of
@code{O_RDONLY}, @code{O_WRONLY} or @code{O_RDWR} must present.

The @var{mode} argument specifies the permission bits
when a new file is created.  The default is @code{#o664}.
@end defun


@defun sys-statvfs path
@defunx sys-fstatvfs port-or-fd
@{@t{gauche.fcntl}@}
Interface to POSIX @code{statvfs} and @code{fstatvfs}.

Returns information about the filesystem where @var{path}, or
a file associated to @var{port-or-fd}, as @code{<sys-statvfs>} instance
described below.

These procedures are only defined if the system supports them.
You can use the feature identifier @code{gauche.sys.statvfs}
for the availability (@pxref{Feature conditional}).

@example
(cond-expand
  [gauche.sys.statvfs
    (... code using sys-statvfs ...)]
  [else
    (... alternative code ...)])
@end example
@end defun

@deftp {Builtin Class} <sys-statvfs>
@clindex sys-statvfs
@{@t{gauche.fcntl}@}
POSIX @code{struct statvfs}.
This class is only defined if a feature @code{gauche.sys.statvfs} is
provided.

@defivar {<sys-statvfs>} bsize
Filesystem block size.
@end defivar

@defivar {<sys-statvfs>} frsize
Fragment size.
@end defivar

@defivar {<sys-statvfs>} blocks
@defivarx {<sys-statvfs>} bfree
@defivarx {<sys-statvfs>} bavail
Number of blocks, number of free blocks, and number of free blocks
for unprivileged users, in @code{frsize} units.
@end defivar

@defivar {<sys-statvfs>} files
@defivarx {<sys-statvfs>} ffree
@defivarx {<sys-statvfs>} favail
Number of inodes, number of free inodes, and number of free inodes
for unprivileged users.
@end defivar

@defivar {<sys-statvfs>} fsid
An exact integer filesystem ID.  
@end defivar

@defivar {<sys-statvfs>} flag
An exact integer, logical IOR of the bitflags.
Portable bitflag values is provided with constants
@code{ST_NOSUID} a @code{ST_RDONLY}.
@end defivar

@defivar {<sys-statvfs>} namemax
Maximum filename length.
@end defivar
@end deftp

@defvr {Constant} ST_NOSUID
@defvrx {Constant} ST_RDONLY
@{@t{gauche.fcntl}@}
Bitflag values that can be used in @code{flag} slot of @code{<sys-statvfs>}.
These constants are only defined if a feature @code{gauche.sys.statvfs} is
provided.

If @code{ST_NOSUID} bit is on, suid and sgid bits of the files on this
filesystem are ignored by @code{exec(3)}.

If @code{ST_RDONLY} bit is on, the filesystem is mounted read-only. 
@end defvr


@c ----------------------------------------------------------------------
@node Generators, Hooks, Low-level file operations, Library modules - Gauche extensions
@section @code{gauche.generator} - Generators
@c NODE ジェネレータ, @code{gauche.generator} - ジェネレータ

@deftp {Module} gauche.generator
@mdindex gauche.generator
A generator is merely a procedure with no arguments and works
as a source of a series of values.  Every time it is called,
it yields a value.  The EOF value indicates the generator is exhausted.
For example, @code{read-char} can be seen as a generator that
generates characters from the current input port.

It is common practice to abstract the source of values in such a way,
so it is useful to define utility procedures that work on the
generators.  This module provides them.

Srfi-121 (Generators) is a subset of this module.
Since @code{gauche.generator} predates srfi-121, we have different
names for some procedures; for the compatibility, we provide
both names.  Srfi-151 (Generators and accumulators) adds some more
generator procedures, which is also included (but accumulator procedures
are left to srfi-158. @xref{R7RS generators}.)
@end deftp

A generator is very lightweight, and handy to implement simple
on-demand calculations.  However, keep in mind that it is
side-effecting construct; you can't safely backtrack, for example.
For more functional on-demand calculation, you can use
lazy sequences (@pxref{Lazy sequences}), which is actually
built on top of generators.

The typical pattern of using generator is as follows: First you
create a source or sources of the values, 
using one of generator constructors
(@pxref{Generator constructors}) or rolling your own one.  You
may connect generator operators that modifies the stream of
generated items as you wish (@pxref{Generator operations}).
Eventually you need to extract actual values from the generator
to consume; there are utility procedures provided
(@pxref{Generator consumers}).  Overall, you create a pipeline
(or DAG) of generators that works as lazy value-propagation network.

@menu
* Generator constructors::
* Generator operations::
* Generator consumers::
@end menu

@node Generator constructors, Generator operations, Generators, Generators
@subsection Generator constructors
@c NODE ジェネレータの生成

A generator isn't a special datatype but just an ordinary procedure,
so you can make a generator with lambdas.  This module provides
some common generator constructors for the convenience.

If you want to use your procedure as a generator, note that a
generator can be invoked many times even after it returns EOF once.
You have to code it so that once it returns EOF, it keeps returning
EOF for the subsequent calls.

The result of generator constructors is merely a procedure,
and printing it doesn't show much.  In the examples in this section
we use @code{generator->list} to convert the generator to the list.
See @ref{Generator consumers} for the description of @code{generator->list}.

@defun null-generator
@{@t{gauche.generator}@}
An empty generator.  Returns just an EOF object when called.
@end defun

@defun circular-generator arg @dots{}
[SRFI-158]
@{@t{gauche.generator}@}
Returns an infinite generator that repeats the given arguments.

@example
(generator->list (circular-generator 1 2 3) 10)
  @result{} (1 2 3 1 2 3 1 2 3 1)
@end example

Note that the above example limits the length of
the converted list by 10; otherwise
@code{generator->list} won't return.
@end defun

@defun giota :optional (count +inf.0) (start 0) (step 1)
@{@t{gauche.generator}@}
Like @code{iota} (@pxref{List constructors}), creates a generator
of a series of @var{count} numbers, starting from @var{start}
and increased by @var{step}.

@example
(generator->list (giota 10 3 2))
  @result{} (3 5 7 9 11 13 15 17 19 21)
@end example

If both @var{start} and @var{step} are exact, the generator
yields exact numbers; otherwise it yields inexact numbers.

@example
(generator->list (giota +inf.0 1/2 1/3) 6)
  @result{} (1/2 5/6 7/6 3/2 11/6 13/6)
(generator->list (giota +inf.0 1.0 2.0) 5)
  @result{} (1.0 3.0 5.0 7.0 9.0)
@end example
@end defun

@defun grange start :optional (end +inf.0) (step 1)
@{@t{gauche.generator}@}
Similar to @code{giota}, creates a generator of a series of
numbers.  The series begins with @var{start}, increased by @var{step},
and continues while the number is below @var{end}.

@example
(generator->list (grange 3 8))
  @result{} (3 4 5 6 7)
@end example
@end defun

@defun generate proc
@{@t{gauche.generator}@}
Creates a generator from coroutine.

The @var{proc} argument is a procedure that takes one argument,
@var{yield}.   When called, @code{generate} immediately returns
a generator @var{G}.  When @var{G} is called, the @var{proc} runs
until it calls @var{yield}.  Calling @var{yield} causes to suspend
the execution of @var{proc} and @var{G} returns the value passed
to @var{yield}.

Once @var{proc} returns, it is the end of the series---@var{G} returns
eof object from then on.  The return value of @var{proc} is ignored.

The following code creates a generator that produces a series
0, 1, and 2 (effectively the same as @code{(giota 3)} and binds
it to @code{g}.

@example
(define g
  (generate
   (^[yield] (let loop ([i 0])
               (when (< i 3) (yield i) (loop (+ i 1)))))))

(generator->list g) @result{} (0 1 2)
@end example
@end defun

@defun list->generator lis :optional start end
@defunx vector->generator vec :optional start end
@defunx reverse-vector->generator vec :optional start end
@defunx string->generator str :optional start end
@defunx uvector->generator uvec :optional start end
@defunx bytevector->generator u8vector :optional start end
[SRFI-158+]
@{@t{gauche.generator}@}
Returns a generator that yields each item in the given argument.
A generator returned from @code{reverse-*} procedures runs in
reverse order.
Srfi-121 defines these except @code{uvector->generator}, which can
take any type of uniform vectors.  The srfi-121 version,
@code{bytevector->generator}, limits the argument to @code{u8vector}.

@example
(generator->list (list->generator '(1 2 3 4 5)))
  @result{} (1 2 3 4 5)
(generator->list (vector->generator '#(1 2 3 4 5)))
  @result{} (1 2 3 4 5)
(generator->list (reverse-vector->generator '#(1 2 3 4 5)))
  @result{} (5 4 3 2 1)
(generator->list (string->generator "abcde"))
  @result{} (#\a #\b #\c #\d #\e)
(generator->list (uvector->generator '#u8(1 2 3 4 5)))
  @result{} (1 2 3 4 5)
@end example

The generator is exhausted once all items are retrieved;
the optional @var{start} and @var{end} arguments can limit the range
the generator walks across; @var{start} specifies the left bound
and @var{end} specifies the right bound.

For forward generators, the first value the generator yields
is @var{start}-th element, and it ends right before @var{end}-th element.
For reverse generators, the first value is the item right next
to the @var{end}-th element, and the last value is the @var{start}-th
element.
at the last element, and reverse generators ends at the first element.

@example
(generator->list (vector->generator '#(a b c d e) 2))
  @result{} (c d e)
(generator->list (vector->generator '#(a b c d e) 2 4))
  @result{} (c d)
(generator->list (reverse-vector->generator '#(a b c d e) 2))
  @result{} (e d c b)
(generator->list (reverse-vector->generator '#(a b c d e) 2 4))
  @result{} (d c)
(generator->list (reverse-vector->generator '#(a b c d e) #f 2))
  @result{} (b a)
@end example
@end defun

@defun bits->generator n :optional start end
@defunx reverse-bits->generator n :optional start end
@{@t{gauche.generator}@}
These procedures take an exact integer and treat it as a sequence of
boolean values (0 for false and 1 for true), as @code{bits->list} does
(@pxref{R7RS bitwise operations}).  @code{Bits->generator} takes bits from
LSB, while @code{reverse-bits->generator} takes them from MSB.

@example
(generator->list (bits->generator #b10110))
 @result{} (#f #t #t #f #t)
(generator->list (reverse-bits->generator #b10110))
 @result{} (#t #f #t #t #f)
@end example

The optional @var{start} and/or @var{end} arguments are used to specify
the range of bitfield, LSB being 0.  Unlike @code{list->generator} etc,
@var{start} specifies the rightmost position (inclusive) and
@var{end} specifies the leftmost position (exclusive).  It is consistent
with other procedures that accesses bit fields in integers
(@pxref{R7RS bitwise operations}).

@example
(generator->list (bits->generator #x56 0 4)
  @result{} (#f #t #t #f)  ; takes bit 0, 1, 2 and 3
(generator->list (bits->generator #x56 4 8)
  @result{} (#t #f #t #f)  ; takes bit 4, 5, 6 and 7

(generator->list (reverse-bits->generator #x56 4 8)
  @result{} (#f #t #f #t)  ; takes bit 7, 6, 5 and 4 
@end example

Note: SRFI-151's @code{make-bitwise-generator} is similar to
@code{bits->generator}, except that it produces an infinite generator.
@xref{R7RS bitwise operations}.
@end defun

@defun port->sexp-generator input-port
@defunx port->line-generator input-port
@defunx port->char-generator input-port
@defunx port->byte-generator input-port
@{@t{gauche.generator}@}
Returns a generator that reads characters or bytes from the given
port, respectively.  They're just
@code{(cut read input-port)},
@code{(cut read-line input-port)},
@code{(cut read-char input-port)}
and @code{(cut read-byte input-port)}, respectively,
but we provide them for completeness.
@end defun

@deffn {Generic function} x->generator obj
@{@t{gauche.generator}@}
A generic version to convert any collection @var{obj} to a generator
that walks across the @var{obj}.  Besides, if @var{obj} is an input port,
@code{port->char-generator} is called.
@end deffn

@defun file->generator filename reader . open-args
@{@t{gauche.generator}@}
Opens a file @var{filename}, and returns a generator
that reads items from the file
by a procedure @var{reader}, which takes one argument, an input port.
The arguments @var{open-args} are passed to @code{open-input-file}

The file is closed when the generator is exhausted.  If a generator
is abandoned before being read to the end, then the file is kept
open until the generator is garbage-collected.  If you want to
make sure the file is closed by a certain point of time, you might want
to use a reader procedure as a generator within the dynamic extent
of @code{with-input-from-file} etc.
@end defun

@defun file->sexp-generator filename . open-args
@defunx file->char-generator filename . open-args
@defunx file->line-generator filename . open-args
@defunx file->byte-generator filename . open-args
@{@t{gauche.generator}@}
Returns a generator that reads a series
of sexps, characters, lines and bytes from a file @var{filename},
respectively.  These are versions
of @code{file->generator} specialized by @code{read},
@code{read-char}, @code{read-line} and @code{read-byte} as the
@var{reader} argument.

Like @code{file->generator}, @var{open-args}
are passed to @code{open-input-file} (@pxref{File ports}).
The file is closed when the generator is exhausted.
@end defun

@defun gunfold p f g seed :optional tail-gen
@{@t{gauche.generator}@}
A generator constructor similar to @var{unfold} (@pxref{R7RS lists}).

@var{P} is a predicate that takes a seed value and determines
where to stop.  @var{F} is a procedure that calculates a value
from a seed value.  @var{G} is a procedure that calculates the
next seed value from the current seed value.  @var{Tail-gen}
is a procedure that takes the last seed value and returns a generator
that generates the tail.

For each call of the resulting generator, @var{p} is called with
the current seed value.  If it returns a true, then we see we've
done, and @code{tail-gen} is called (if it is given) to get a
generator for the tail.  Otherwise,
we apply @var{f} on the current seed value to get the value to
generate, and use @var{g} to update the seed value.

@example
(generator->list (gunfold (^s (> s 5)) (^s (* s 2)) (^s (+ s 1)) 0))
  @result{} '(0 2 4 6 8 10)
@end example
@end defun

@defun giterate f seed
@defunx giterate1 f seed
@{@t{gauche.generator}@}
Returns a generator of
an infinite sequence of values where the next value is computed
by applying @var{f} on the current value.  The first value generated
by @code{giterate} is @var{seed} itself, while the first one by 
@code{giterate1} is @code{(@var{f} @var{seed})}.

@example
(generator->list (giterate (pa$ * 2) 1) 10)
  @result{} (1 2 4 8 16 32 64 128 256 512)
(generator->list (giterate1 (pa$ * 2) 1) 10)
  @result{} (2 4 8 16 32 64 128 256 512 1024)
@end example

The reason we have @code{giterate1} is that it's pretty efficient
(up to 10% faster than @code{giterate}).

See also @code{literate} in @code{gauche.lazy}
(@pxref{Lazy sequence utilities}).
@end defun


@subsubheading SRFI-158 compatible procedures

@defun generator item @dots{}
[SRFI-158]
@{@t{gauche.generator}@}
Returns a generator that generates @var{item} @dots{}.
@end defun

@defun make-iota-generator count :optional start step
[SRFI-158]
@{@t{gauche.generator}@}
Same as @code{giota}, except that the @var{count} argument is
required.
@end defun

@defun make-range-generator start :optional end stop
[SRFI-158]
@{@t{gauche.generator}@}
Same as @code{grange}.
@end defun

@defun make-coroutine-generator proc
[SRFI-158]
@{@t{gauche.generator}@}
Same as @code{generate}.
@end defun

@defun make-for-each-generator for-each obj
[SRFI-158]
@{@t{gauche.generator}@}
Given collection @var{obj} and walker @var{for-each}, creates a
generator that retrieves one item at a time from the collection.
Trivially defined as follows:

@example
(define (make-for-each-generator for-each coll)
  (generate (^[yield] (for-each yield coll))))
@end example

If @var{obj} is mutated before the returned generator walks all the values,
the behavior depends on how the @var{for-each} procedure handles the
situation; it may or may not be safe.  In general it's better to avoid
mutation until the generator returns EOF.  Once the generator is exhausted,
though, it is safe to mutate @code{obj}.
@end defun

@defun make-unfold-generator stop? mapper successor seed
[SRFI-158]
@{@t{gauche.generator}@}
This is the same as @code{gunfold}, except it doesn't take
optional @var{tail-gen} argument.
@end defun


@node Generator operations, Generator consumers, Generator constructors, Generators
@subsection Generator operations
@c NODE ジェネレータの操作


The following procedures take generators (noted as @var{gen} and
@var{gen2}) and return a generator.  For the convenience, they
also accept any collection to @var{gen} and @var{gen2} parameters;
if a collection is passed where a generator is expected,
it is implicitly coerced into a generator.

(NB: This is Gauche's extension.  For portable srfi-121/srfi-158 programs,
you shouldn't rely on this behavior; instead, explicitly convert
collections to generators.)

@defun gcons* item @dots{} gen
[SRFI-158]
@{@t{gauche.generator}@}
Returns a generator that adds @var{item}s in front of @var{gen}.

@example
(generator->list (gcons* 'a 'b (giota 2)))
 @result{} (a b 0 1)
@end example
@end defun

@defun gappend gen @dots{}
[SRFI-158]
@{@t{gauche.generator}@}
Returns a generator that yields the items from the first given
generator, and once it is exhausted, use the second generator, and so on.

@example
(generator->list (gappend (giota 3) (giota 2)))
 @result{} (0 1 2 0 1)

(generator->list (gappend))
 @result{} ()
@end example
@end defun

@defun gconcatenate gen
@{@t{gauche.generator}@}
The @var{gen} argument should generate generators and/or sequences.
Returns a generator that yields elements from the first generator/sequence,
then the second one, then the third, etc.

It is similar to @code{(apply gappend (generator->list gen))}, except
that @code{gconcatenate} can work even @var{gen} generates infinite
number of generators.

@example
($ generator->list $ gconcatenate
   $ list->generator `(,(giota 3) ,(giota 2)))
 @result{} (0 1 2 0 1)
@end example
@end defun

@defun gflatten gen
[SRFI-158]
@{@t{gauche.generator}@}
The argument @var{gen} is a generator that yields lists.
This procedure returns a generator that's yield each element of the lists
one at a time.

Example: The game Tetris determines the next 
dropping piece (tetrimino) by the following algorithm: Take a
bag of tetriminos with one for each kind (O, I, T, S, Z, L, J),
permute it, and draw one by one; once the bag is empty, take another
bag and repeat.  The algorithm can be implemented by a pipeline
of generates as follows.  (Tetris is a registered trademark of
The Tetris Company).

@example
(use gauche.generator)
(use data.random) ; for permutations-of

(define g
  ($ gflatten $ permutations-of
     $ (circular-generator '(O I T S Z L J))))

(generator->list g 21)
  @result{}
  (L O Z T J S I J L Z T I O S T L Z S I J O)
@end example

Note the subtle difference of this example and the example
in @code{gconcatenate} above---@code{gconcatenate} takes
a generator of generators, while @code{gflatten} takes
a generator of lists.

If we use Haskell-ish type notation, you can see the subtle differences
of those similar procedures:

@example
gappend             :: (Generator a, Generator a, ...) -> Generator a
(pa$ apply gappend) :: [(Generator a)] -> Generator a
gconcatenate        :: Generator Generator a -> Generator a
gflatten            :: Generator [a] -> Generator a
@end example
@end defun

@defun gmerge less-than gen gen2 @dots{}
[SRFI-158]
@{@t{gauche.generator}@}
Creates a generator that yields elements out of input generators,
with the order determined by a procedure @code{less-than}.
The procedure is called as
@code{(less-than a b)} and
must return @code{#t} iff the element @code{a} must precede
the element @code{b}.

Each input generator must yield an ordered elements by itself;
otherwise the result won't be ordered.

If only one generator is given, it is just returned (after coercing the
input to a generator).  In that case, @code{less-than} won't be called at all.

@example
(generator->list (gmerge < '(1 3 8) '(5) '(2 4)))
  @result{} '(1 2 3 4 5 8)
@end example
@end defun

@defun gmap proc gen gen2 @dots{}
[SRFI-158]
@{@t{gauche.generator}@}
Returns a generator that yields a value returned by @var{proc}
applied on the values from given generators.  The returned generator
terminates when any of the given generator is exhausted.

NB: This differs from @code{generator-map} (@pxref{Folding generated values})
which consumes all
values at once and returns the results as a list, while @code{gmap}
returns a generator immediately without consuming input.
@end defun

@defun gmap-accum proc seed gen gen2 @dots{}
@{@t{gauche.generator}@}
A generator version of @code{map-accum} (@pxref{Mapping over collection}),
mapping with states. 

The @var{proc} argument is a procedure that takes as many arguments
as the input generators plus one.  It is called as
@code{(proc v v2 @dots{} seed)} where @code{v}, @code{v2}, @dots{} are
the values yielded from the input generators, and @var{seed} is the
current seed value.  It must return two values, the yielding value
and the next seed.

NB: This is called @code{gcombine} in srfi-121.
@end defun

@defun gcombine proc seed gen gen2 @dots{}
[SRFI-158]
@{@t{gauche.generator}@}
An alias of @code{gmap-accum}, provided for the compatibility of srfi-121.
@end defun

@defun gfilter pred gen
@defunx gremove pred gen
[SRFI-158]
@{@t{gauche.generator}@}
Returns a generator that yields the items from the source generator
@var{gen}, except those who makes @var{pred} answers false (@code{gfilter})
or those who makes @var{pred} answers a true value (@code{gremove})

@example
(generator->list (gfilter odd? (grange 0)) 6)
 @result{} (1 3 5 7 9 11)
(generator->list (gremove odd? (grange 0)) 6)
 @result{} (0 2 4 6 8 10)
@end example
@end defun

@defun gdelete item gen :optional =
[SRFI-158]
@{@t{gauche.generator}@}
Return a generator that yields the items from the source generator
@var{gen}, except those are the same as @var{item}.  The comparison
is done by the procedure passed to @var{=}, which defaults to @code{equal?}.

@example
;; Note: This example relies on auto-coercing list to generator.
;; SRFI-121 requires list->generator for the second argument.
(generator->list (gdelete 3 '(1 2 3 4 3 2 1)))
  @result{}  (1 2 4 2 1)
@end example
@end defun

@defun gdelete-neighbor-dups gen :optional =
[SRFI-158]
@{@t{gauche.generator}@}
Returns a generator that yields the items from the source generator
@var{gen}, but the consecutive items of the same value is omitted.
The comparison
is done by the procedure passed to @var{=}, which defaults to @code{equal?}.

@example
;; Note: This example relies on auto-coercing list to generator.
;; SRFI-121 requires string->generator for the second argument.
(generator->list (gdelete-neighbor-dups "mississippi"))
  @result{} (#\m #\i #\s #\i #\s #\i #\p #\i)
@end example
@end defun

@defun gfilter-map proc gen gen2 @dots{}
[SRFI-158]
@{@t{gauche.generator}@}
Works the same as @code{(gfilter values (gmap proc gen gen2 @dots{}))},
only slightly efficiently.
@end defun

@defun gstate-filter proc seed gen
[SRFI-158]
@{@t{gauche.generator}@}
This allows stateful filtering of a series.  The @var{proc} argument
must be a procedure that takes a value @var{V} from the source generator and
a seed value.  It should return two values, a boolean flag and the next
seed value.  If it returns true for the boolean flag, the generator
yields @var{V}.  Otherwise, the generator keeps calling @var{proc},
with updating the seed value, until it sees the true flag value
or the source generator is exhausted.

The following example takes a generator of oscillating values
and yields only values that are greater than their previous value.

@example
(generator->list
 (gstate-filter (^[v s] (values (< s v) v)) 0
                (list->generator '(1 2 3 2 1 0 1 2 3 2 1 0 1 2 3))))
 @result{} (1 2 3 1 2 3 1 2 3)
@end example
@end defun

@defun gbuffer-filter proc seed gen :optional tail-gen
@{@t{gauche.generator}@}
This procedure allows n-to-m mapping between elements in input and output---
that is, you can take a look at several input elements to generate
one or more output elements.

The procedure @var{proc} receives the next input element and accumulated
seed value.  It returns two values: A list of output values, and the next
seed value.  If you need to look at more input to generate
output, you can return an empty list as the first value.

If the input reaches the end, @var{tail-gen} is called with the
current seed value; it should return a list of last output values.
If omitted, the output ends when the output of the last call to @var{proc}
is exhausted (the last seed value is discarded).

Suppose you have a text file.  Each line contains a command,
but if the line ends with backslash, next line is treated as a
continuation of the current line.  The following code creates
a generator that returns @emph{logical} lines, that is,
the lines after such line continuations are taken care of.

@example
(gbuffer-filter (^[v s]
                  (if-let1 m (#/\\$/ v)
                    (values '() (cons (m 'before) s))
                    (values `(,(string-concatenate-reverse (cons v s))) '())))
                '()
                (file->line-generator "input-file.txt")
                (^[s] `(,(string-concatenate-reverse s))))
@end example
@end defun

@defun gtake gen k :optional padding
@defunx gdrop gen k
[SRFI-158]
@{@t{gauche.generator}@}
Returns a generator that takes or drops initial @var{k} elements
from the source generator @var{gen}.

Those won't complain if the source generator is exhausted before generating
@var{k} items.  By default, the generator returned by @code{gtake}
terminates as the source ends, but if you give the optional @var{padding}
argument, then the returned generator does yield @var{k} items, using the
value given to @var{padding} to fill the rest.

Note: If you pass @var{padding}, @code{gtake} always returns a generator
that generates exactly @var{k} elements even the input generator is already
exhausted---there's no general way to know whether you've reached
the end of the input.  If you need to take @var{k} items repeatedly
from the input generator, you may want to use @code{gslices} below.

Note for the compatibility: Until 0.9.4, @code{gtake} takes two optional
arguments, @var{fill?} and @var{padding}.  That is consistent with
Gauche's builtin @code{take*}, but incompatible to srfi-121's @code{gtake}.
We think srfi-121's interface is more compact and intuitive, so we
renamed the original one to @code{gtake*} (emphasizing
the similarity to @code{take*}), and made @code{gtake} compatible to
srfi-121.
To ease transition, the current @code{gtake} allows two optional arguments
(four in total),
in which case we assume the caller wants to call @code{gtake*}; so
the code that gives two optional arguments to @code{gtake} would work in
both pre-0.9.4 and 0.9.5.
@end defun

@defun gtake* gen k :optional fill? padding
@{@t{gauche.generator}@}
A variation of @code{gtake}; instead of single optional @var{padding}
argument, this takes two optional arguments just like @code{take*}
(@xref{List accessors and modifiers}.)  Up to 0.9.4 this version
is called @code{gtake}.  This is provided for the backward compatibility.
@end defun

@defun gtake-while pred gen
@defunx gdrop-while pred gen
[SRFI-158]
@{@t{gauche.generator}@}
The generator version of @code{take-while} and @code{drop-while}
(@pxref{List accessors and modifiers}).  The generator returned
from @code{gtake-while} yields items from the source generator
as far as @var{pred} returns true for each.  The generator returned
from @code{gdrop-while} first reads items from the source generator
while @var{pred} returns true for them, then start yielding items.
@end defun

@defun gslices gen k :optional (fill? #f) (padding #f)
@{@t{gauche.generator}@}
The generator version of @code{slices} (@pxref{List accessors and modifiers}).
This returns a generator, that yields a list of @var{k} items from
the input generator @var{gen} at a time.

@example
(generator->list (gslices (giota 7) 3))
  @result{} ((0 1 2) (3 4 5) (6))
@end example

The @var{fill?} and @var{padding} arguments controls how the end
of input is handled, just like @code{gtake}.  When @var{fill?} is
@code{#f} (default), the last item from output generator may not
have @var{k} items if the input is short to fill them, as shown
in the above example.  If @var{fill?} is true and the input is
short to complete @var{k} items, @var{padding} argument is used
to fill the rest.

@example
(generator->list (gslices (giota 6) 3 #t 'x))
  @result{} ((0 1 2) (3 4 5))
(generator->list (gslices (giota 7) 3 #t 'x))
  @result{} ((0 1 2) (3 4 5) (6 x x))
@end example
@end defun

@defun ggroup gen k :optional padding
[SRFI-158]
@{@t{gauche.generator}@}
Returns a generator lists of @var{k} elements taken from @var{gen}.
If @var{padding} is omitted, it works just as @code{(gslices gen k)}.
If @var{padding} is given, it works just as @code{(gslices gen k #t padding)}.

This is defined in srfi-158, and more portable than @code{gslices}.
@end defun

@defun grxmatch regexp gen
@{@t{gauche.generator}@}
The @var{gen} argument must be, after coerced, a generator that
yields characters.

A generator returned from this procedure
tries to match @var{regexp} from the character sequence
generated by @var{gen}, and once it matches, remember the position after
the match and returns @code{#<rxmatch>} object.  If no more match
is found, the generator is exhausted.

@example
($ generator->list
   $ gmap rxmatch-substring
   $ grxmatch #/\w+/ "The quick brown fox jumps over the lazy dog.")
 @result{} ("The" "quick" "brown" "fox" "jumps" "over" "the" "lazy" "dog")
@end example

Note: This procedure is efficient if @var{gen} is a string, in which
case we actually bypass coercing it to a generator.  If @var{gen} is other
than a string, the current implementation may need to apply @var{regexp}
as many times as O(n^2) where n is the entire length of the character
sequence generated by @var{gen}, although the coefficient is small.
This may be improved in future, but be careful using this function
on very large input.

Note also that, when @var{gen} is not a string, @var{rxmatch} is applied
on some buffered partial input.  So @code{rxmatch-after} of the returned
match does not represents the whole ``rest of input'' after the match,
but merely the rest of strings within the buffer.
@end defun

@defun gindex vgen igen
[SRFI-158]
@{@t{gauche.generator}@}
Both arguments are generators.  The @var{igen} generator must
yield monotonically increasing series of exact nonnegative integers.

Returns a generator that generates items from @var{vgen}
indexed by the numbers from @var{igen}, exhausted when either
source generator is exhausted.

An error is thrown when @var{igen} yields a value that doesn't
conform the condition.

@example
;; This example takes advantage of Gauche's auto-coercing
;; list to generator.  For portable srfi-121 programs,
;; you need list->generator for each argument:
(generator->list (gindex '(a b c d e) '(0 2 3)))
  @result{} (a c d)
@end example
@end defun

@defun gselect vgen bgen
[SRFI-158]
@{@t{gauche.generator}@}
Both arguments are generators.  Creates and returns a
generator that yields a value from @var{vgen} but only
the corresponding value from @var{bgen} is true.

The returned generator is exhausted when one of the
source generators is exhausted.

@example
;; This example takes advantage of Gauche's auto-coercing
;; list to generator.  For portable srfi-121 programs,
;; you need list->generator for each argument:
(generator->list (gselect '(a b c d e) '(#t #t #f #t #f)))
  @result{} (a b d)
@end example

Combined with a bitgenerator, you can use @code{gselect}
to extract items using bitmask:

@example
(generator->list (gselect '(a b c d e)
                           (reverse-bits->generator #x1a)))
  @result{} (a b d)
@end example
@end defun



@node Generator consumers,  , Generator operations, Generators
@subsection Generator consumers
@c NODE ジェネレータの消費

Some generator consumers are built-in.
@xref{Folding generated values}, for @code{generator-fold},
@code{generator-fold-right}, @code{generator-for-each},
@code{generator-map}, and @code{generator-find}.

@defun generator->list generator :optional k
@defunx generator->reverse-list generator :optional k
[SRFI-158]
@{@t{gauche.generator}@}
Reads items from @var{generator} and returns a list of them
(or a reverse list, in case of @code{generator->reverse-list}).
By default, this reads until the generator is exhausted.  If
an optional argument @var{k} is given, it must be a nonnegative
integer, and the list ends either @var{k} items are read,
or the generator is exhausted.

Be careful not to pass an infinite generator to this without
specifying @var{k}---this procedure won't return but hogs
all the memory before crash.
@end defun

@defun generator-map->list proc gen gen2 @dots{}
[SRFI-158]
@{@t{gauche.generator}@}
The @var{proc} argument must be a procedure that takes as many arguments
as the number of given generators.

Returns a list, each of whose element is created by applying @var{proc}
on each element from given generators @var{gen} @var{gen2} @dots{}.
The list ends when any of the generator is exhausted.

Note that the list is created eagerly---if all of the generators are
infinite, this procedure never returns.
@end defun

@defun generator->vector gen :optional k
@defunx generator->string gen :optional k
[SRFI-158]
@{@t{gauche.generator}@}
Extracts items from the generator @var{gen} up to @var{k} items
or until it exhausts, and create a fresh
vector or string from the extracted items.

When @var{k} is omitted, @var{gen} is called until it exhausts;
note that if @var{gen} is infinite generator this procedure won't return.

For @code{generator->string}, @var{gen} must yield a character, or
an error is reported.
@end defun

@defun generator->uvector gen :optional k class
@defunx generator->bytevector gen :optional k
[SRFI-158]
@{@t{gauche.generator}@}
Extracts items from the generator @var{gen} up to @var{k} items
or until it exhausts, and create a fresh uniform vector
of class @var{class} filled with those items.
If @var{k} is omitted, @var{gen} is read until it exhausts.

If @var{class} is specified, it must be one of the uniform vector
classes (@pxref{Uniform vectors}).  When omitted, @code{<u8vector>} is
assumed.

@code{Generator->bytevector} works like @code{generator->uvector}
except that the class is fixed to @code{<u8vector>}.

The generator must always produce numeric values acceptable to be an
element of the specified uvector; otherwise an error is signalled.
@end defun

@defun generator->vector! vector at gen
[SRFI-158]
@{@t{gauche.generator}@}
Fill @var{vector} from index @var{at} with the value yielded
from @var{gen}.  It terminates when @var{gen} is exhausted or the index
reaches at the end of the vector.  Returns the number of items
generated.

@example
(define v (vector 'a 'b 'c 'd 'e))

(generator->vector! v 2 (giota))
  @result{} 3

v @result{} #(a b 0 1 2)
@end example
@end defun

@defun generator->uvector! uvector at gen
@defunx generator->bytevector! u8vector at gen
@{@t{gauche.generator}@}
Like @var{generator->vector!}, fill a uniform vector @var{uvector}
starting from index @var{at} with elements read from a generator
@var{gen}.  It terminates when @var{gen} is exhausted or the index
reaches at the end of the vector.  Returns the number of items
generated.

Any type of uvector can be passed to @code{generator->uvector!}, while
@code{generator->bytevector!} can only accept @code{u8vector}.

The generator must always produce numeric values acceptable to be an
element of the specified uvector; otherwise an error is signalled.
@end defun

@defmac glet* (binding @dots{}) body body2 @dots{}
@{@t{gauche.generator}@}
This captures a monadic pattern frequently appears in the generator
code.  It is in a similar spirit of @code{and-let*}, but returns
as soon as the evaluating expression returns EOF, instead of @code{#f}
as @code{and-let*} does.

The @var{binding} part can be either @code{(var expr)} or @code{( expr )}.
The actual definition will explain this syntax clearly.

@example
(define-syntax glet*
  (syntax-rules ()
    [(_ () body body2 ...) (begin body body2 ...)]
    [(_ ([var gen-expr] more-bindings ...) . body)
     (let1 var gen-expr
       (if (eof-object? var)
         var
         (glet* (more-bindings ...) . body)))]
    [(_ ([ gen-expr ] more-bindings ...) . body)
     (let1 var gen-expr
       (if (eof-object? var)
         var
         (glet* (more-bindings ...) . body)))]))
@end example
@end defmac

@defmac glet1 var expr body body2 @dots{}
@{@t{gauche.generator}@}
This is to @code{glet*} as @code{let1} is to @code{let*}.  In other words,
it is @code{(glet* ([var expr]) body body2 @dots{})}.
@end defmac

@defmac do-generator (var gexpr) body @dots{}
@{@t{gauche.generator}@}
This is a generator version of @code{dolist} and @code{dotimes}
(@pxref{Binding constructs}).

@var{Gexpr} is an expression that yields a generator.  It is
evaluated once.  The resulting generator is called repeatedly
until it returns EOF.  Every time the generator is called,
@var{body} @dots{} are evaluated in the scope
where @var{var} is bound to the value yielded from the generator.

Like @code{dolist} and @code{dotimes}, this macro exists for
side-effects.  You can write the same thing with @code{for-each} families,
but sometimes this macro makes the imperative code more readable:

@example
(do-generator [line (file->line-generator "filename")]
  ;; do some side-effecting stuff with line
  )
@end example
@end defmac

@defun generator-any pred gen
@defunx generator-every pred gen
[SRFI-158]
@{@t{gauche.generator}@}
Like @code{any} and @code{every} (@pxref{Walking over lists}), but
works on a generator.
@end defun

@defun generator-count pred gen
[SRFI-158]
@{@t{gauche.generator}@}
Returns the number of items in a generator @var{gen}
that satisfies @var{pred}.
As a side effect, @var{gen} is exhausted.
@end defun

@defun generator-unfold gen unfold arg @dots{}
[SRFI-158]
@{@t{gauche.generator}@}
Apply @var{unfold} using the values generated from a generator @var{gen}
as seeds.  It is equivalent to the following expression:

@code{(@var{unfold} eof-object? identity (^_ (@var{gen})) (@var{gen}) @var{arg} @dots{})}

The @var{unfold} procedure must have the signature
@code{(unfold stop? mapper successor seed arg @dots{})}, like @code{unfold}
in @code{scheme.list} (@pxref{R7RS lists}).

It can be seen as a general method to convert a generator to a sequence,
an inverse of @code{x->generator}.

@example
(generator-unfold (x->generator "abc") string-unfold)
  @result{} "abc"
@end example
@end defun


@c ----------------------------------------------------------------------
@node Hooks, Interactive session, Generators, Library modules - Gauche extensions
@section @code{gauche.hook} - Hooks
@c NODE フック, @code{gauche.hook} - フック

@deftp {Module} gauche.hook
@mdindex gauche.hook
Provides a hook object, which manages a list of closures to be
called at certain time.

This API of hooks are upper-compatible of Guile's, with the
following extensions.
@itemize @bullet
@item
Based on Gauche's object system.  Most APIs are methods
so you can extend the hook features.
@item
Hook object itself is applicable.  You don't need to use @code{run-hook}.
@item
The method to remove a procedure from a hook is called @code{delete-hook!},
for consistency with SRFI-1 and others.  @code{remove-hook!} is
defined as an alias of @code{delete-hook!} for compatibility with Guile.
@end itemize

If you're writing portable code, srfi-173 provides the basic
hook functionality (@pxref{Hooks (srfi)}).
@end deftp

@deftp {Class} <hook>
@clindex hook
@{@t{gauche.hook}@}
A hook class, which keeps a list of procedures to be called at once.

The @code{object-apply} method is defined on @code{<hook>} class,
so you can "apply" a hook object as if it were a procedure---which
causes all the registered procedure to be invoked.
@end deftp

@defun make-hook :optional (arity 0)
@{@t{gauche.hook}@}
Creates a new hook object with given arity, which should be a
non-negative integer.
@end defun

@defun hook? obj
@{@t{gauche.hook}@}
Returns true if @var{obj} is a hook object.
@end defun

@defun hook-empty? hook
@{@t{gauche.hook}@}
Returns true if @var{hook}'s procedure list is empty.
@end defun

@deffn {Method} add-hook! (hook <hook>) proc :optional (append? #f)
@{@t{gauche.hook}@}
Adds a procedure @var{proc} to @var{hook}.  If @var{append?}
is given and true, @var{proc} is added at the end of the list.
Otherwise, @var{proc} is added at the front of the list.
The @var{proc} has to be called with the arity given
at the @code{make-hook}.
@end deffn

@deffn {Method} delete-hook! (hook <hook>) proc
@deffnx {Method} remove-hook! (hook <hook>) proc
@{@t{gauche.hook}@}
Removes @var{proc} from the procedure list of @var{hook}.
@code{Remove-hook!} is an alias of @code{delete-hook!} just for
compatibility with Guile.
@end deffn

@deffn {Method} reset-hook! (hook <hook>)
@{@t{gauche.hook}@}
Empties @var{hook}'s procedure list.
@end deffn

@deffn {Method} hook->list (hook <hook>)
@{@t{gauche.hook}@}
Returns a copy of @var{hook}'s procedure list.
@end deffn

@deffn {Method} run-hook (hook <hook>) arg @dots{}
@{@t{gauche.hook}@}
Calls @var{hook}'s procedures in order, with arguments @var{arg} @dots{}.
The number of arguments must match the arity given at @code{make-hook}.
@end deffn

@c ----------------------------------------------------------------------
@node Interactive session, Lazy sequence utilities, Hooks, Library modules - Gauche extensions
@section @code{gauche.interactive} - Utilities for interactive session
@c NODE インタラクティブセッション, @code{gauche.interactive} - インタラクティブセッション

@deftp {Module} gauche.interactive
@mdindex gauche.interactive
Provides useful utilities for the interactive session.

This module is automatically loaded when you run @code{gosh}
interactively.

This module also sets autoloads for functions defined in
@code{gauche.reload} module
(see @ref{Reloading modules}), so that
those functions can be used by default in interactive development.
@end deftp

@defmac apropos pattern :optional module
@{@t{gauche.interactive}@}
Show a list of defined variables whose name matches @var{pattern}.
If you give a module or a module name @var{module}, only the variables
defined in that module are listed.  Without @var{module},
the variables "visible" from the current module are listed.

@var{pattern} may be a symbol or a regexp object.
If it is a symbol, the variables whose name contains the
substring that matches the symbol's name are listed.
If it is a regexp object, the variables whose name matches
the regexp are listed.

Some examples:
@example
;; @r{List variables that contains "string" in their name}
(apropos 'string)

;; @r{Search in srfi-14 module}
(apropos 'char 'srfi-14)
@end example
@end defmac

@deffn {Generic Function} describe :optional obj
@deffnx {Generic Function} d :optional obj
@{@t{gauche.interactive}@}
Prints the detail information about a Scheme object @var{obj}.
The default method shows @var{obj}'s class, and if it has
any slots, the list of slot names and their values.
You can specialize this method for customized display.
Some built-in types has specialized methods
(see how an integer is described in the example below).

If @var{obj} is omitted, the last evaluation result bound to @code{*1} in REPL
is used.  (@pxref{Working in REPL})

@example
gosh> (sys-stat "Makefile")
#<<sys-stat> 0x1e7de60>
gosh> (d)
#<<sys-stat> 0x1e7de60> is an instance of class <sys-stat>
slots:
  type      : regular
  perm      : 436
  mode      : 33204
  ino       : 3242280
  dev       : 2097
  rdev      : 0
  nlink     : 1
  uid       : 500
  gid       : 500
  size      : 19894
  atime     : 1435379061
  mtime     : 1432954340
  ctime     : 1432954340
gosh> (d 1432954340)
1432954340 is an instance of class <integer>
  (#x556925e4, ~ 1.4Gi, 2015-05-30T02:52:20Z as unix-time)
@end example
@end deffn

@defun info symbol
@{@t{gauche.interactive}@}
Displays an entry of the named function, syntax, module or class
from Gauche's info document.
If an environment variable @code{INFOPATH} is defined,
this function searches for the info file from the directories in it.
Otherwise, this function guesses info file location from the
@code{gosh}'s library directory.   If the info file can't be
found, an error is signaled.
So this function doesn't work if you haven't installed info file.

If no entry exactly matching with @var{symbol} is found, the procedure tries
to look for similar named entries:

@example
gosh> (info 'stirng)
There is no entry for stirng.
Did you mean:
  string>
  string?
  string=
  string<
  string
  :string
@end example

(If you want to search entries using pattern, see @code{info-serach} below.)

If the current output port is a tty, the info page is displayed by
a paging software.  If an environment variable @code{PAGER} is defined,
it is used as a paging software.  Otherwise, this function looks for
@code{less} and @code{more} in this order from the directories in
@code{PATH}.  If none of them is found, or the output port is not
a tty, this function just displays the page.

The first invocation of this function in a session takes some time
to parse the info file.

NB: When you use @code{less} as a pager, make sure you set
it to handle utf-8 characters (e.g. setting @code{LESSCHARSET} 
environment variable to
@code{UTF-8}), or you'll see some escaped sequences on the screen.

NB: If you invoke @code{gosh} within the build tree, using @code{-ftest}
option, @code{info} reads the info files in the build tree if they exist.
@end defun

@defun info-search regexp
@{@t{gauche.interactive}@}
Lists info entries matching @var{regexp}.  See @code{info} above
about where the info files are searched.
@end defun

@defun ed filename-or-procedure :key editor load-after
@{@t{gauche.interactive}@}
Invoke an external editor to open the named file, or the file containing
the definition of the given procedure (if it can be known).  
For the latter, it uses @code{source-location} procedure to find out
the source code location (@pxref{Debugging aid}).

The name of the editor to invoke is determined as follows:

@enumerate
@item
The @var{editor} keyword argument.
@item
The value of the variable @code{*editor*} in the @code{user} module,
if defined.  This is handy that you can set this in your @code{.gaucherc}.
@item
The value of the environment variable @code{GAUCHE_EDITOR}.
@item
The value of the environment variable @code{EDITOR}.
@end enumerate

If none of the above is defined or @code{#f}, the procedure prompts the user
to type in the name of the editor.

Once the editor name is obtained, it is invoked as a subprocess,
with the following format:

@example
EDITOR +lineno filename
@end example

The @var{lineno} is an integer line number, 1 being the first line.
The editor is expected to locate the cursor on the specified line.

Once the editor process exits, the procedure checks if the named
file is updated.  If so, it may load the file, according to the
value of the @var{load-after} keyword argument.  It may take one
of the following values:

@table @code
@item #t
Load the file automatically if it's updated.
@item #f
Do not load the file.
@item ask
The symbol @code{ask} cause the procedure to prompt the user
whether it should load the file.  This is the default.
@end table
@end defun


@c ----------------------------------------------------------------------
@node Lazy sequence utilities, Listener, Interactive session, Library modules - Gauche extensions
@section @code{gauche.lazy} - Lazy sequence utilities
@c NODE 遅延シーケンスユーティリティ, @code{gauche.lazy} - 遅延シーケンスユーティリティ

@deftp {Module} gauche.lazy
@mdindex gauche.lazy
This module provides utility procedures that yields lazy sequences.
For the details of lazy sequences, @pxref{Lazy sequences}.
@end deftp

Since lazy sequences are forced implicitly and indistinguishable
from ordinary lists, we don't need a separate set of procedures
for @emph{taking} lists and lazy sequences; we can use @code{find}
to search in both ordinary lists and lazy sequences.

However, we do need a separate set of procedures
for @emph{returning} either lists or lazy sequences.  For example,
@var{lmap} can take any kind of sequences, and
returns lazy sequence (and calls the procedure on demand).

This distinction is subtle, so I reiterate it.  You can use
both @code{map} and @code{lmap} on lazy sequences.  If you want
the result list at once, use @code{map}; it doesn't have
overhead of delayed calculation.  If you don't know you'll use
the entire result, or you know the result will get very large
list and don't want to waste space for an intermediate list,
you want to use @code{lmap}.

@defun x->lseq obj
@{@t{gauche.lazy}@}
A convenience function to coerce @var{obj} to (possibly lazy) list.
If @var{obj} is a list, it is returned as it is.  If @var{obj} is
other type of collection, the return value is a lazy sequence
that iterates over the collection.  If @var{obj} is other object,
it is returned as it is (you can think of it as a special case
of dotted list).

If you try @code{x->lseq} in REPL, it looks as if it just
converts the input collection to a list.

@example
(x->lseq '#(a b c)) @result{} (a b c)
@end example

But that's because the lazy sequence is forced by the output
routine of the REPL.
@end defun

@defun lunfold p f g seed :optional tail-gen
@{@t{gauche.lazy}@}
A lazy version of @code{unfold} (@pxref{R7RS lists}).
The arguments @var{p}, @var{f} and @var{g} are procedures,
each of which take one argument, the current seed value.
The predicate @var{p} determines when to stop, @var{f} creates
each element, and @var{g} generates the next seed value.
The @var{seed} argument gives the initial seed value.
If @var{tail-gen} is given, it should also be a procedure
that takes one argument, the last seed value (that is, the
seed value @code{(p seed)} returned @code{#f}).  It must return
a (possibly lazy) list, that forms the tail of the resulting sequence.

@example
(lunfold ($ = 10 $) ($ * 2 $) ($ + 1 $) 0 (^_ '(end)))
  @result{} (0 2 4 6 8 10 12 14 16 18 end)
@end example
@end defun

@defun literate proc seed
@{@t{gauche.lazy}@}
Creates an infinite sequence of
@code{(@var{seed} (@var{proc} @var{seed}) (@var{proc} (@var{proc} @var{seed})) @dots{})}.

The same sequence can be created with
@code{(lunfold (^_ #f) identity proc seed)},
but this one is a lot more efficient.

See also @code{util.stream}, which as @code{stream-iterate}
(@pxref{Stream constructors}).

@example
(take (literate (pa$ + 1) 0) 10)
 @result{} (0 1 2 3 4 5 6 7 8 9)
@end example
@end defun


@defun lmap proc seq seq2 @dots{}
@{@t{gauche.lazy}@}
Returns a lazy sequence consists of values calculated
by applying @var{proc} to every first element of @var{seq} @var{seq2}
@dots{}, every second element of them, etc., until any of
the input is exhausted.
Application of @var{proc} will be delayed as needed.

@example
;; If you use map instead of lmap, this won't return
(use math.prime)
(take (lmap (pa$ * 2) *primes*) 10)
  @result{} (4 6 10 14 22 26 34 38 46 58)
@end example
@end defun

@defun lmap-accum proc seed seq seq2 @dots{}
@{@t{gauche.lazy}@}
The procedure @var{proc} takes one element each from
@var{seq} @var{seq2} @dots{}, plus the current seed value.
It must return two values, a result value and the next seed value.
The result of @code{lmap-accum} is a lazy sequence consists
of the first values returned by each invocation of @var{proc}.

@example
(use math.prime)
(take (lmap-accum (^[p sum] (values sum (+ p sum))) 0 *primes*) 10)
  @result{} (0 2 5 10 17 28 41 58 77 100)
@end example

This is a lazy version of @code{map-accum} (@pxref{Mapping over collection}),
but @code{lmap-accum} does not return the final seed value.  We only
know the final seed value when we have the result sequence to the
end, so it can't be calculated lazily.
@end defun

@defun lappend seq @dots{}
@{@t{gauche.lazy}@}
Returns a lazy sequence which is concatenation of @var{seq} @dots{}.
Unlike @code{append}, this procedure returns immediately, taking O(1) time.
It is useful when you want to append large sequences but may use
only a part of the result.
@end defun

@defun lconcatenate seqs
@{@t{gauche.lazy}@}
The @var{seqs} argument is a sequence of sequences.  Returns
a lazy sequence that is a concatenation of all the sequences in @var{seqs}.

This differs from @code{(apply lappend seqs)}, for @code{lconcatenate}
can handle infinite number of lazy @var{seqs}.
@end defun

@defun lappend-map proc seq1 seq @dots{}
@{@t{gauche.lazy}@}
Lazy version of @code{append-map}.   This differs from a simple
composition of @var{lappend} and @var{lmap}, since
@code{(apply lappend (lmap proc seq1 seq @dots{}))} would
evaluate the result of @code{lmap} to the end before passing it to
@code{lappend} (it's because @code{apply} need to determine
the list of arguments before calling @code{lappend}).

It also differs from
@code{(lconcatenate (lmap proc seq1 seq @dots{}))} in the subtle way.

Remember that Gauche's lazy sequence evaluates one element ahead?
@code{lconcatenate} does that to the result of @code{lmap}.
To see the effect, let's define a procedure with a debug print:

@example
(define (p x) #?=(list x x))
@end example

You can see in the following example
that @code{(apply lappend (lmap ...))} wouldn't delay
any of application of @code{p}:

@example
gosh> (car (apply lappend (lmap p '(1 2 3))))
(car (apply lappend (lmap p '(1 2 3))))
#?="(standard input)":4:(list x x)
#?-    (1 1)
#?="(standard input)":4:(list x x)
#?-    (2 2)
#?="(standard input)":4:(list x x)
#?-    (3 3)
1
@end example

How about @code{lconcatenate}?

@example
gosh> (car (lconcatenate (lmap p '(1 2 3))))
(car (lconcatenate (lmap p '(1 2 3))))
#?="(standard input)":4:(list x x)
#?-    (1 1)
#?="(standard input)":4:(list x x)
#?-    (2 2)
1
@end example

Oops, even though we need only the first element, and the first
result of @code{lmap}, @code{(1 1)}, provides the second element, too,
@code{p} is already applied to the second input.

This is because the intermediate lazy list of the result of @code{lmap} is
evaluated ``one element ahead''.   On the other hand, @code{lappend-map}
doesn't have this problem.

@example
gosh> (car (lappend-map p '(1 2 3)))
(car (lappend-map p '(1 2 3)))
#?="(standard input)":4:(list x x)
#?-    (1 1)
1
@end example
@end defun

@defun linterweave seq @dots{}
@{@t{gauche.lazy}@}
Returns a lazy seq of the first items from @var{seq} @dots{}, then
their second items, and so on.   If the length of shortest sequence
of @var{seqs} is N, the length of the resulting sequence is
@code{(* N number-of-sequences)}.  If all of @var{seq}s are infinite,
the resulting sequence is also infinite.

@example
(linterweave (lrange 0) '(a b c d e) (circular-list '*))
 @result{} (0 a * 1 b * 2 c * 3 d * 4 e *)
@end example
@end defun

@defun lfilter proc seq
@{@t{gauche.lazy}@}
Returns a lazy sequence that consists of non-false values calculated
by applying @var{proc} on every elements in @var{seq}.
@end defun

@defun lfilter-map proc seq seq2 @dots{}
@{@t{gauche.lazy}@}
Lazy version of @code{filter-map}.
@end defun

@defun lstate-filter proc seed seq
@{@t{gauche.lazy}@}
Lazy sequence version of @code{gstate-filter} (@pxref{Generator operations}).
@end defun

@defun ltake seq n :optional fill? padding
@defunx ltake-while pred seq
@{@t{gauche.lazy}@}
Lazy versions of @code{take*} and @code{take-while}
(@pxref{List accessors and modifiers}).   Note that
@code{ltake} works rather like @code{take*} than @code{take},
that is, it won't complain if the input sequence has less than @var{n}
elements.  Because of the lazy nature of @code{ltake}, it can't know
whether input is too short or not before returning the sequence.

There are no @code{ldrop} and @code{ldrop-while}; you don't need them.
if you apply
@code{drop} and @code{drop-while} on lazy sequence, they return
lazy sequence.
@end defun

@defun lrxmatch rx seq
@{@t{gauche.lazy}@}
This is a lazy sequence version of @code{grxmatch}
(@pxref{Generator operations}).

The @var{seq} argument must be a sequence of characters (including
ordinary strings).
The return value is a lazy sequence of @var{<rxmatch>} objects,
each representing strings matching to the regular expression @var{rx}.

This procedure is convenient to scan character sequences from
lazy character sequences, but it may be slow if you're looking for
rarely matching string from very large non-string input.
Unless @var{seq} is a string,
@code{lrxmatch} buffers certain length of input,
and if matching phrase isn't found, it extend the buffer and scan
again from the beginning, since the match may span from the end of
previous chunk to the newly added portion.
@end defun

@defun lslices seq k :optional fill? padding
@{@t{gauche.lazy}@}
Lazy version of @code{slices} (@pxref{List accessors and modifiers}).

@example
(lslices '(a b c d e f) 2)
  @result{} ((a b) (c d) (e f))
@end example
@end defun

@c ----------------------------------------------------------------------
@node Listener, User-level logging, Lazy sequence utilities, Library modules - Gauche extensions
@section @code{gauche.listener} - Listener
@c NODE リスナー, @code{gauche.listener} - リスナー

@deftp {Module} gauche.listener
@mdindex gauche.listener
This module provides a convenient way to enable multiple
read-eval-print loop (repl) concurrently.

An obvious way to run multiple repls is to use threads;
creating as many threads as sessions and calling
@code{read-eval-print-loop} (@pxref{Eval and repl}) from each thread.
Nevertheless, sometimes single threaded implementation is preferred.
For instance, you're using a library which is not MT-safe,
or your application already uses select/poll-based dispatching mechanism.

To implement repl in the single-threaded selection-base application,
usually you register a handler that is called when data is available
in the listening port.  The handler reads the data and add them into
a buffer.  Then it examines if the data in the buffer consists a
complete expression, and if so, it reads the expression from the
buffer, evaluates it, then prints the result to the reporting port.
The @code{<listener>} class in this module provides this handler mechanism,
so all you need to do is to register the handler to your dispatching
mechanism.

Note: it may also be desirable to buffer the output sometimes,
but the current version doesn't implement it.
@end deftp

@subheading Listener API

@deftp {Class} <listener>
@clindex listener
@{@t{gauche.listener}@}
An object that maintains the state of a repl session.
It has many external slots to customize its behavior.
Those slot values can be set at construction time
by using the keyword of the same name as the slot,
or can be set by @code{slot-set!} afterwards.  However,
most of them should be set before calling
@code{listener-read-handler}.

@defivar <listener> input-port
Specifies the input port from which the listener get the input.
The default value is the current input port when the object is
constructed.
@end defivar

@defivar <listener> output-port
Specifies the output port to which the listener output will go.
The default value is the current output port when the object is
constructed.
@end defivar

@defivar <listener> error-port
Specifies the output port to which the listener's error messages will go.
The default value is the current error port when the object is
constructed.
@end defivar

@defivar <listener> reader
A procedure with no arguments.  It should read a Scheme expression
from the current input port when called.
The default value is system's @code{read} procedure.
@end defivar

@defivar <listener> evaluator
A procedure that takes two arguments, a Scheme expression and
an environment specifier.  It should evaluate the expression in
the given environment and returns zero or more value(s).
The default value is system's @code{eval} procedure.
@end defivar

@defivar <listener> printer
A procedure that takes zero or more argument(s) and prints them
out to the current output port.  The default value is a procedure
that prints each value by @code{write}, followed by a newline.
@end defivar

@defivar <listener> prompter
A procedure with no arguments.  It should prints a prompt
to the current output port.  The output is flushed by the listener
object so this procedure doesn't need to care about it.
The default procedure prints @code{"listener> "}.
@end defivar

@defivar <listener> environment
An environment specifier where the expressions will be
evaluated.  The default value is the value returned by
@code{(interaction-environment)}.
@end defivar

@defivar <listener> finalizer
A thunk that will be called when EOF is read from @code{input-port}.
During the execution of @var{finalizer}, the current input, output
and error ports are restored to the ones when
@code{listener-read-handler} is called.

It can be @code{#f} if no such procedure is needed.
The default value is @code{#f}.
@end defivar

@defivar <listener> error-handler
A procedure that takes one argument, an error exception.  It is
called when an error occurs during read-eval-print stage,
with the same dynamic environment as the error is signaled.
The default value is a procedure that simply prints the
error exception by @code{report-error}.
@end defivar

@defivar <listener> fatal-handler
A procedure that takes one argument, an error exception.
It is called when a @emph{fatal} error occurred (see below
for the precise definition).  If this handler is
called, you should assume you can no longer continue the listener
session safely, even write messages to the client.  This handler
is to log such condition or to clean up the listener.
During the execution of @var{fatal-handler}, the current input, output
and error ports are restored to the ones when
@code{listener-read-handler} is called.

If @var{fatal-handler} returns @code{#f}, @var{finalizer} is
called afterwards.  With this, you can implement a common
cleanup work in @var{finalizer}.  If @var{fatal-handler} returns
a true value, @var{finalizer} will not be called.

@end defivar

@end deftp


@deffn {Method} listener-read-handler (listener <listener>)
@{@t{gauche.listener}@}
Returns a thunk that is to be called when a data is available
from @code{input-port} of the listener.

The returned thunk (read handler) does the following steps.
Note that the first prompt is @emph{not} printed by this
procedure.  See @code{listener-show-prompt} below.
@enumerate
@item
Reads available data from @code{input-port} and appends it to the
listener's internal buffer.
@item
Scans the buffer to see if it has a complete S-expression.
If not, returns.
@item
Reads the S-expression from the buffer.
The read data is removed from the buffer.
@item
Evaluates the S-expression, then prints the result to
@code{output-port}.
@item
Prints the prompt by prompter procedure to @code{output-port},
then flush @code{output-port}.
@item
Repeats from 2.
@end enumerate
@end deffn

@deffn {Method} listener-show-prompt (listener <listener>)
@{@t{gauche.listener}@}
Shows a prompt to the listener's output port, by using
listener's prompter procedure.  Usually you want to use
this procedure to print the first prompt, for instance,
when the client is connected to the listener socket.
@end deffn

@defun complete-sexp? str
@{@t{gauche.listener}@}
Returns @code{#t} if @var{str} contains a complete S-expression.
This utility procedure is exported as well, since it might be useful
for other purposes.

Note that this procedure only checks syntax of the expressions,
and doesn't rule out erroneous expressions (such as containing
invalid character name, unregistered SRFI-10 tag, etc.).
This procedure may raise an error if the input contains
'@code{#<}' character sequence.
@end defun

@subheading Error handling

There are a few error situations the listener handles differently.

@itemize @bullet
@item
@emph{Fatal error} - An error situation that the listener session
can no longer go on safely.  You cannot even tell so to the
listener client, since the connection to the client may be broken.
All you can do is to clean up the listener session (e.g. removes
the handler).   This case happens in (1) a low-level system error
occurs during reading from @var{input-port}. (A syntax error
of the input isn't count as fatal, and handled as REPL error described
below.), (2) a @code{SIGPIPE} signal is raised during writing to
@var{output-port}, or (3) an unhandled error occurred during executing
@var{error-handler}.

When this situation happens, the @var{fatal-handler} is called
if it is given.  If @var{fatal-handler} returns @code{#f}, or
@var{fatal-handler} isn't given, @var{finalizer} is also called.

@item
@emph{Leaked error} - If an error occurs during executing
@var{fatal-handler} or @var{finalizer}, we don't have no more
safety net.  The error is 'leaked' outside the listener handler,
and should be handled by the user of @code{gauche.listener}.

Generally this situation should be considered as a bug of
the program; you should make sure to catch foreseeable errors within
@var{fatal-handler} and @var{finalizer}.

@item
@emph{REPL error} - Other errors are handled by @var{error-handler}.
@end itemize

@subheading Listener example

The following code snippet opens a server socket, and opens
a Scheme interactive session when a client is connected.
(Note: this code is just for demonstration.  Do not run
this program on the machine accessible from outside network!)

@example
(use gauche.net)
(use gauche.selector)
(use gauche.listener)

(define (scheme-server port)
  (let ((selector (make <selector>))
        (server   (make-server-socket 'inet port :reuse-addr? #t))
        (cid      0))

    (define (accept-handler sock flag)
      (let* ((client (socket-accept server))
             (id     cid)
             (input  (socket-input-port client :buffering :none))
             (output (socket-output-port client))
             (finalize (lambda ()
                         (selector-delete! selector input #f #f)
                         (socket-close client)
                         (format #t "client #~a disconnected\n" id)))
             (listener (make <listener>
                         :input-port input
                         :output-port output
                         :error-port output
                         :prompter (lambda () (format #t "client[~a]> " id))
                         :finalizer finalize))
             (handler (listener-read-handler listener))
             )
        (format #t "client #~a from ~a\n" cid (socket-address client))
        (inc! cid)
        (listener-show-prompt listener)
        (selector-add! selector input (lambda _ (handler)) '(r))))

    (selector-add! selector
                   (socket-fd server)
                   accept-handler
                   '(r))
    (format #t "scheme server started on port ~s\n" port)
    (do () (#f) (selector-select selector))))
@end example

@c ----------------------------------------------------------------------
@node User-level logging, Propagating slot access, Listener, Library modules - Gauche extensions
@section @code{gauche.logger} - User-level logging
@c NODE ユーザレベルのロギング, @code{gauche.logger} - ユーザレベルのロギング

@deftp {Module} gauche.logger
@mdindex gauche.logger
Provides a simple interface to log the program's activity.
The information can be written to the specified file,
or to the system logger using @code{syslog(3)}.
When a file is used, syslog-like prefix string is added
to each message, which is configurable.  It can also takes care of
locking of the file (see the description of @code{lock-policy} below).
@end deftp

@deftp {Class} <log-drain>
@clindex log-drain
@{@t{gauche.logger}@}
Represents the destination of log messages.
There's one implicit global @code{<log-drain>} instance, which is
used by default.  However, you can create as many instances
by @code{make} method as you want, in case if you want to log
to more than one destination.

@defivar {<log-drain>} path
Designates destination of log output.  It can be one of the following
values.

@table @asis
@item @r{string}
Pathname of the log file.  The output is written to it.
@item @code{current-error}
@itemx @code{#t}
The output goes to the current error port.
@item @code{current-output}
The output goes to the current output port.
@item @code{syslog}
The output is sent to the system logger.
@item @code{ignore}
Make @code{log-format} does nothing.
@item @code{#f}
The output is turned to a string and returned from
@code{log-format}.
@end table

By default, this slot is @code{#f}.
@end defivar

@defivar {<log-drain>} prefix
Specifies the prefix string that is attached to the beginning of every
message.  If the message spans to several lines, the prefix is
attached to each line.   The value of this slot can also be a procedure
that takes @code{<log-drain>} object and returns a string to be used as
the prefix.  The procedure is called every time prefix is needed.

When the @code{path} slot is a symbol @code{syslog}, the value of this slot
is ignored.  System logger will attach an appropriate prefix.

When the value of the prefix slot is a string, the following character sequences
have special meanings and replaced by @code{log-format} for appropriate
information when written out.

@table @code
@item ~T
Current time, in the format of "Mmm DD hh:mm:ss" where "Mmm" is
an abbreviated month, "DD" is the day of month, "hh", "mm" and
"ss" are hours (in 24 hour basis), minutes and seconds, respectively.
This format is compatible with system logs.

@item ~Y
Current 4-digit year.

@item ~P
The program name.  The default value is the basename of
@code{(car (command-line))} (@pxref{Command-line arguments}),
but you can change it by the @code{program-name}
slot described below.

@item ~$
The process id of this program.

@item ~U
The name of the effective user of the process.

@item ~H
The hostname the process is running.
@end table

The default value of this slot is "@code{~T ~P[~$]: }".  For example,
if a string "this is a log message.\nline 2\nline 3" is given as the
message, it produces something like the following log entry.

@example
Sep  1 17:30:23 myprogram[441]: this is a log message
Sep  1 17:30:23 myprogram[441]: line 2
Sep  1 17:30:23 myprogram[441]: line 3
@end example

@end defivar

@defivar {<log-drain>} program-name
Specifies the program name written by @code{~P} directive of
the prefix slot.
@end defivar

@defivar {<log-drain>} lock-policy
Specifies the way the log file should be locked.
If the value of this slot is a symbol @code{fcntl},
the log file is locked using
fcntl() (@pxref{Low-level file operations}).
If the value is a symbol @code{file}, the log file is locked by
creating auxiliary lock file, whose name is generated by appending ".lock"
after the log file path.  The logging
process needs a write permission to the log file directory.
Note that if the process is killed forcibly during writing the
log file, a stale lock file may remain.  @code{Log-format}
silently removes the lock file if it is unusually old (currently 10 minutes).
If the value is @code{#f}, no locking is performed.

The default value is @code{fcntl}, except MacOSX which doesn't
support fcntl()-style locking and thus @code{file} is default.

The locking isn't performed if the destination is not a file.
@end defivar

@defivar {<log-drain>} syslog-option
@defivarx {<log-drain>} syslog-facility
@defivarx {<log-drain>} syslog-priority
The value of these slots are used when the destination of the drain
is the system logger.   @xref{Syslog}, for the detailed information
about these values.  The default values of these slots
are @code{LOG_PID}, @code{LOG_USER} and @code{LOG_INFO}, respectively.
@end defivar
@end deftp


@defun log-open path :key prefix program-name
@{@t{gauche.logger}@}
Sets the destination of the default log message to the path @var{path}.
It can be a string or a boolean, as described above.
You can also set prefix and program name by corresponding keyword
arguments.  See the @code{<log-drain>} above for those parameters.

Despite its name, this function doesn't open the specified file
immediately.  The file is opened and closed every time @code{log-format}
is called.
@end defun

@deffn {Parameter} log-default-drain
@{@t{gauche.logger}@}
When called with no argument, returns the current default log-drain
@code{log-format} uses when the explicit drain is omitted.
It may return @code{#f} if the default log drain hasn't been
opened by @code{log-open}.

Calling with new @code{<log-drain>} object or
@code{#f} alters the default log-drain.
You can also use @code{parameterize} (@ref{Parameters}) to change
the log drain temporary.
@end deffn


@deffn {Method} log-format (format <string>) arg @dots{}
@deffnx {Method} log-format (drain <log-drain>) (format <string>) arg @dots{}
@{@t{gauche.logger}@}
Formats a log message by @var{format} and @var{arg @dots{}}, by using
@code{format} (@pxref{Output}).    In the first form, the output goes
to the default destination.  In the second form, the output goes to
the specified drain.

The file is opened and closed every time.  You can safely move
the log file while your program that touches the log file is running.
Also @code{log-format} acquires a write lock of the log file by
@code{sys-fcntl} (@pxref{Low-level file operations}).

If the first form of @code{log-format} is called before @code{log-open}
is called, @code{log-format} does nothing.
It is useful to embed debug stubs in your code; once your code is
past the debugging stage, you just comment out @code{log-open} and
the code runs without logging.
@end deffn

@c ----------------------------------------------------------------------
@node Propagating slot access, Singleton, User-level logging, Library modules - Gauche extensions
@section @code{gauche.mop.propagate} - Propagating slot access
@c NODE スロットアクセスの伝播, @code{gauche.mop.propagate} - スロットアクセスの伝播

@deftp {Module} gauche.mop.propagate
@mdindex gauche.mop.propagate
Provides a metaclass to add @code{:propagated} slot allocation option.

When a slot allocation has @code{:propagated}, access
to the slot is redirected to other object's slot.
It is handy for composite objects to keep external
interface simple, for access to the slot of inner objects
can be disguised as if it is a slot of the parent object.
@end deftp

An example would work better than explanation.
Suppose you have a @code{<rect>} class to represent
generic rectangular area, and you want to use it when you create
a @code{<viewport>} class by composition, instead of
inheritance.  A simple way would be as follows:

@example
(define-class <rect> ()
  ((width  :init-keyword :width)
   (height :init-keyword :height)))

(define-class <viewport> ()
  ((dimension :init-form (make <rect>))
   ;;   ... other slots ...
   ))
@end example

With this definition, whenever you want to access the viewport's
width or height, you have to go through @code{<rect>} object, e.g.
@code{(~ viewport'dimension'width)}.  This is not only cumbersome,
but the users of viewport class have to know that how the
viewport is composed (it's not necessarily a bad thing,
but sometimes you may want to hide it).

Using @code{gauche.mop.propagate}, you can define slots
@code{width} and @code{height} in @code{<viewport>} class
that are proxies of @code{<rect>}'s slots.

@example
(use gauche.mop.propagate)

(define-class <rect> ()
  ((width  :init-keyword :width)
   (height :init-keyword :height)))

(define-class <viewport> (<propagate-mixin>)
  ((dimension :init-form (make <rect>))
   (width     :allocation :propagated :propagate 'dimension
              :init-keyword :width)
   (height    :allocation :propagated :propagate 'dimension
              :init-keyword :height)))
@end example

With @code{:propagated} allocation, the slots are not actually
allocated in @code{<viewport>} instance, and accesses to the
slots are redirected to the object in the slot specified by
@code{:propagate} slot option---in this case, the @code{dimension} slot.
It is somewhat similar to the virtual slots, but it's more convenient
for you don't explicitly write procedures to redirect the access.

Now you can treat @code{width} and @code{height} as if they
are slots of @code{<viewport>}.   You can even make them
initialize via @code{init-keyword} (but you can't use
@code{:init-form} or @code{:init-value}; if you want to specify
default values, give the default values to the actual object).

@example
gosh> (define vp (make <viewport> :width 640 :height 480))
vp
gosh> (d vp)
#<<viewport> 0xc5a1e0> is an instance of class <viewport>
slots:
  dimension : #<<rect> 0xc5a130>
  width     : 640
  height    : 480
gosh> (set! (~ vp'width) 800)
#<undef>
gosh> (~ vp'width)
800
@end example

Here's two classes that enables this feature.
Usually all you have to do is to inherit @code{<propagate-mixin>} class.

@deftp {Class} <propagate-meta>
@clindex propagate-meta
@{@t{gauche.mop.propagate}@}
Adds @code{:propagated} slot allocation.
The propagated slot has to have @code{:propagate} slot option
which specifies the name of the slot that points to an object
that actually holds the value of the slot.
If a slot has @code{:propagated} slot allocation but
does not have @code{:propagate} slot option, an error is signaled.

The @code{:propagate} slot option should have a value
of either a symbol, or a list of two symbols.

If it is a symbol, it names the slot that contains an
object, whose slot with the same name of the propagate slot
holds the value.

If it is a list of two symbols as @code{(X Y)}, then
the access to this propagated slot actually works as
@code{(slot-ref (slot-ref obj X) Y)}.

If you want to make a propagated slot initializable by
init-keywords, make sure the slot holding the actual object
comes before the propagated slots.  Slot initialization proceeds
in the order of appearance by default, and you want the
actual object is created before setting values.
@end deftp

@deftp {Class} <propagate-mixin>
@clindex propagate-mixin
@{@t{gauche.mop.propagate}@}
This is a convenience mixin class.   Instead of giving
@code{:metaclass <propagate-meta>}, you can just inherit
this calss to make propagated slots available.
@end deftp

@c ----------------------------------------------------------------------
@node Singleton, Slot with validator, Propagating slot access, Library modules - Gauche extensions
@section @code{gauche.mop.singleton} - Singleton
@c NODE シングルトン, @code{gauche.mop.singleton} - シングルトン

@deftp {Module} gauche.mop.singleton
@mdindex gauche.mop.singleton
Provides a metaclass to define a singleton class.
@end deftp

@deftp {Class} <singleton-meta>
@clindex singleton-meta
@{@t{gauche.mop.singleton}@}
Creates a singleton class.  A singleton class is a class that is
guaranteed to create only one instance.
The first invocation of @code{make} creates the single instance,
and further attempt of creation returns the same instance.
@example
(define-class single () () :metaclass <singleton-meta>)

(define a (make single))
(define b (make single))

(eq? a b) @result{} #t
@end example

The slots of the instance are initialized at the first invocation
of @code{make}.  Initargs of @code{make} are effective only in the
fist invocation, and ignored in the subsequent invocation.

The call of initialization in @code{make} is thread-safe.
@end deftp

@deffn {Method} instance-of (class <singleton-meta>) :rest initargs
@{@t{gauche.mop.singleton}@}
This method just calls @code{make} with the passed arguments.
It is more obvious in the program that you're dealing with singleton.
@end deffn

@deftp {Class} <singleton-mixin>
@clindex singleton-mixin
@{@t{gauche.mop.singleton}@}
An instance of @code{<singleton-meta>}.  Instead of specifying
@code{<singleton-meta>} as the @code{:metaclass} argument of
@code{define-class}, you can inherit this class to give your
class the property of singleton.
@end deftp

@c ----------------------------------------------------------------------
@node Slot with validator, Networking, Singleton, Library modules - Gauche extensions
@section @code{gauche.mop.validator} - Slot with validator
@c NODE Validator付きスロット, @code{gauche.mop.validator} - Validator付きスロット

@deftp {Module} gauche.mop.validator
@mdindex gauche.mop.validator
Provides a metaclass that adds @code{:validator} and @code{:observer}
slot options.
@end deftp

@deftp {Class} <validator-meta>
@clindex validator-meta
@{@t{gauche.mop.validator}@}
This metaclass adds a feature that you can specify callbacks that are
called before and after the slot value is set.
For example, if you want to guarantee
that a certain slot always holds a string value, you can make a procedure
be called before the slot is modified, either by @code{slot-ref} or
by a setter method.  In the procedure you can either rejects a
value except string, or coerce the value to a string.

A @emph{validator} procedure is a callback procedure that is called
before the slot value is set.   It can be specified by @code{:validator}
slot option.  The procedure takes two values, the instance and
the value to be set.  Whatever the procedure returns is set to
the actual slot value.

A @emph{observer} procedure is a callback procedure that is called
after the slot value is set.  It can be specified by @code{:observer}
slot option.  The procedure also takes two values, the instance
and the new value.  Result of the observer procedure is discarded.

See the following example:

@example
(define-class <v> ()
  ((a :accessor a-of
      :validator (lambda (obj value) (x->string value)))
   (b :accessor b-of
      :validator (lambda (obj value)
                   (if (integer? value)
                       value
                       (error "integer required for slot b")))))
  :metaclass <validator-meta>)

(define v (make <v>))
(slot-set! v 'a 'foo)
(slot-ref v 'a) @result{} "foo"

(set! (a-of v) 1234)
(a-of v) @result{} "1234"

(slot-set! v 'b 55)
(slot-ref v 'b) @result{} 55

(slot-set! v 'b 3.4) @result{} @r{error}
(set! (b-of v) 3.4)  @result{} @r{error}
@end example

You can specify default slot value (@code{:init-value} etc.) with
@code{:validator}.  In that case, the initialization method of the
instance calls the validator with the specified default value,
if :init-keyword is not given.

@example
(define-class <v> ()
  ((a :initform 'foo :init-keyword :a
      :validator (lambda (obj value) (x->string value)))))

(slot-ref (make <v>) 'a)        @result{} "foo"
(slot-ref (make <v> :a 555) 'a) @result{} "555"
@end example

It looks similar to the virtual slot, but note that a slot with
validator has an actual storage in the instance, while a virtual
slot doesn't.

It is also a good example of customizing how the slots are accessed
using the metaobject protocol.  This feature is implemented by
only a couple of dozen lines of code.
@end deftp

@c ----------------------------------------------------------------------
@node Networking, Package metainformation, Slot with validator, Library modules - Gauche extensions
@section @code{gauche.net} - Networking
@c NODE ネットワーキング, @code{gauche.net} - ネットワーキング

@deftp {Module} gauche.net
@mdindex gauche.net
Provides a set of functions necessary for network communications
based on BSD socket interface.

The API is provided in two different levels.  Lower level routines
reflect traditional BSD socket interface, such as @code{bind(2)}.
Higher level routines provides more convenient way to create
typical connection-oriented server/client sockets.

This module also provides APIs to obtain various information
about hostnames, service ports, and protocols.

Gauche can handle IPv6 if it is compiled
with the @code{--enable-ipv6} configuration option.
To check whether IPv6 is enabled or not,
you can use @code{cond-expand} with
@code{gauche.net.ipv6} feature identifier
after loading @code{gauche.net}, as shown below.

@example
(use gauche.net)
(cond-expand
  (gauche.net.ipv6
    ... code to use ipv6 ...)
  (else
    ... ipv4 only code ...))
@end example

See @ref{Feature conditional} for the details of @code{cond-expand}.

@end deftp

Note: If you want to write a portable program using network,
take a look at @code{srfi-106} (@pxref{Basic socket interface}).

@menu
* Socket address::
* High-level network functions::
* Low-level socket interface::
* Netdb interface::
@end menu

@node Socket address, High-level network functions, Networking, Networking
@subsection Socket address
@c NODE ソケットアドレス

@subsubheading Socket address objects

@deftp {Builtin Class} <sockaddr>
@clindex sockaddr
@{@t{gauche.net}@}
An abstract base class of socket addresses.  Each socket address family
is implemented as a subclass of this class.

Although socket addresses are built-in classes, you can use
@code{make} method to create an instance of a
specific socket address family.
@end deftp

@deffn {Generic Function} sockaddr-family addr
@{@t{gauche.net}@}
Returns a symbol that indicates the family of the socket address
@var{addr}.
@end deffn

@deffn {Generic Function} sockaddr-name addr
@{@t{gauche.net}@}
Returns a string which represents the content of the socket address
@var{addr}.
@end deffn

@deftp {Builtin Class} <sockaddr-in>
@clindex sockaddr-in
@{@t{gauche.net}@}
AF_INET family socket address.  To create an instance of this class,
use @code{make} method as follows:
@example
(make <sockaddr-in> :host @var{host} :port @var{port})
@end example
@var{host} can be a string, an integer IP address, a
@code{u8vector} IP address, or one of the keywords
@code{:any}, @code{:broadcast}, @code{:none} or @code{:loopback}.
If it is a string, it is either a host name or a dotted IP notation.
Gauche uses @code{gethostbyname(3)} to obtain the actual IP address from
@var{host} parameter.  If it is a keyword @code{:any},
or @code{:broadcast}, the address
uses @code{INADDR_ANY}, or @code{INADDR_BROADCAST}
respectively.  The keyword @code{:loopback} is a synonym to the
IPv4 loopback address "127.0.0.1".

@var{port} must be a positive integer indicating the port number.
See also @code{make-sockaddrs} below, to create multiple
socket addresses on the machine which may have more than one
protocol stack.
@end deftp

@deffn {Method} sockaddr-family (addr <sockaddr-in>)
@{@t{gauche.net}@}
Returns a symbol @code{inet}.
@end deffn

@deffn {Method} sockaddr-name (addr <sockaddr-in>)
@{@t{gauche.net}@}
Returns a string in the form "@var{a}.@var{b}.@var{c}.@var{d}:@var{port}",
 where "@var{a}.@var{b}.@var{c}.@var{d}" is dotted decimal notion of
the IP address and @var{port} is the port number.
@end deffn

@deffn {Method} sockaddr-addr (addr <sockaddr-in>)
@deffnx {Method} sockaddr-port (addr <sockaddr-in>)
@{@t{gauche.net}@}
Returns the IP address and the port number as an integer, respectively.
@end deffn

@deftp {Builtin Class} <sockaddr-un>
@clindex sockaddr-un
@{@t{gauche.net}@}
AF_UNIX family socket address.  To create an instance of this class,
use @code{make} method as follows:
@example
(make <sockaddr-un> :path @var{path})
@end example
@var{path} must be a string specifying pathname of the socket.
@end deftp

@deffn {Method} sockaddr-family (addr <sockaddr-un>)
@{@t{gauche.net}@}
Returns a symbol @code{unix}.
@end deffn

@deffn {Method} sockaddr-name (addr <sockaddr-un>)
@{@t{gauche.net}@}
Returns a pathname of the socket address.
@end deffn

@deftp {Builtin Class} <sockaddr-in6>
@clindex sockaddr-in6
@{@t{gauche.net}@}
AF_INET6 family socket address.  This is only available if
gauche is configured with --enable-ipv6 configure option.
The constructor and the slots are the same as @code{<sockaddr-in>}.
See also @code{make-sockaddrs} below, to create multiple
socket addresses on the machine which may have more than one
protocol stack.
@end deftp

@defun make-sockaddrs host port :optional proto
@{@t{gauche.net}@}
This is a higher-level utility procedure to create all possible
inet domain socket addresses that point to @code{@var{host}:@var{port}}
of protocol @var{proto}.  Particularly, if the specified host has
both IPv4 and IPv6 addresses, and the running system supports both,
then both IPv4 and IPv6 socket addresses are returned.   If @var{host} has
multiple IP addresses, socket addresses are created for each of these
IP address.   You can make your network application much more portable
among different network stack configurations.

Passing @code{#f} to @var{host} creates the local
(server) address.  You can also pass a service name (e.g. @code{"http"})
instead of an integer, to the @var{port} argument.
The value of @var{proto} can be either a symbol @code{tcp} or @code{udp},
and the default is @code{tcp}.

It always returns a list of socket addresses.  If the lookup of @var{host}
is failed, null list is returned.
@end defun

@subsubheading Address and string conversion

@defun inet-string->address address
@{@t{gauche.net}@}
Converts string representing of the internet address @var{address}
to an integer address.  If @var{address} is parsed successfully,
returns two values: the integer address value and the recognized
protocol (the constant value @code{2} (= @code{AF_INET})
for IPv4 addresses, and @code{10} (= @code{AF_INET6})
for IPv6 addresses).  If @var{address} can't be
parsed, @code{#f} and @code{#f} are returned.

@example
(inet-string->address "192.168.1.1")
 @result{} 3232235777 and 2
(inet-string->address "::1")
 @result{} 1 and 10
(inet-string->address "::192.168.1.1")
 @result{} 3232235777 and 10
(inet-string->address "ffe0::1")
 @result{} 340116213421465348979261631549233168385 and 10
(inet-string->address "::192.168.1.1")
 @result{} 3232235777 and 10
@end example
@end defun

@defun inet-string->address! address buf
@{@t{gauche.net}@}
Like @code{inet-string->address}, but fills the given u8vector
@var{buf} by the parsed address instead of returning it as
an integer value.  The integer representation of inet addresses
is likely to be a bignum, and you can avoid creating bignums
with this function.  The given u8vector @var{buf} must be mutable.
Returns the protocol on success, or @code{#f} on failure.

The caller must provide big enough buffer.  If @var{buf}
is larger than required, the result is filled from the top
of the u8vector and the rest of the vector remains intact.

@example
(let* ((buf (make-u8vector 16 0))
       (proto (inet-string->address! "192.168.1.1" buf)))
  (list proto buf))
 @result{} (2 #u8(192 168 1 1 0 0 0 0 0 0 0 0 0 0 0 0))
@end example
@end defun


@defun inet-address->string address protocol
@{@t{gauche.net}@}
Converts the given @var{address} to its string representation
of the protocol @var{protocol}, which can be either
@code{2} (the constant @code{AF_INET}) or @code{10}
(the constant @code{AF_INET6}).
An integer or a u8vector can be used as @var{address}.  If it is
a u8vector, only the necessary portion of the vector is read; i.e.
the vector can be longer than the required length.

@example
(inet-address->string 3232235777 AF_INET)
  @result{} "192.168.1.1"

(inet-address->string '#u8(192 168 1 1) AF_INET)
  @result{} "192.168.1.1"

(inet-address->string 3232235777 AF_INET6)
  @result{} "::c0a8:101"
@end example
@end defun


@node High-level network functions, Low-level socket interface, Socket address, Networking
@subsection High-level network functions
@c NODE 高レベルネットワーク手続き

@deftp {Builtin Class} <socket>
@clindex socket
@{@t{gauche.net}@}
Abstracts a socket, a communication endpoint.

For a connection-oriented socket, you can access the communication
channel by two ports associated to the socket, one for input and
another for output.  @code{socket-input-port} and @code{socket-output-port}
returns those ports, respectively.

The @code{<socket>} class implements @code{<connection>} interface.
@xref{Connection framework}, for the details.
The @code{connection-self-address}
and @code{connection-peer-address} methods return
a socket address object.
@end deftp

The following three functions are convenient ways to create
a connection-oriented socket.  Those functions
are to provide an easy methods for typical cases,
but have less control.  If you need more than these functions
provide, use low-level interface.

@defun make-client-socket :optional address-spec @dots{}
@{@t{gauche.net}@}
Creates and returns a client socket, connected to the address
specified by @var{address-spec} @dots{}.

@table @code
@item (make-client-socket 'unix @var{path})
The client socket is connected to the unix domain server socket
of address @var{path}.
@item (make-client-socket 'inet @var{host} @var{port})
The client socket is connected to the inet domain server socket
with hostname @var{host} and port @var{port}.   TCP protocol is
assumed.   @var{host} can be either a hostname, or
a dotted decimal notation of IPv4 address.
If gauche is compiled with --enable-ipv6, IPv6 address notation
can also be used.  @var{Port} must be an exact integer specifying
a port number, or a string service name (e.g. @code{"http"}).

If gauche is compiled with --enable-ipv6, and the hostname is given,
and the hostname has both IPv6 and IPv4 addresses, then
IPv6 connection is tried first, and IPv4 is used when IPv6 fails.
@item (make-client-socket @var{host} @var{port})
This works the same as above.  This form is for compatibility with STk.
@item (make-client-socket @var{sockaddr})
If an instance of @code{<sockaddr>} is passed,
a socket suitable for @var{sockaddr} is opened and then connected
to the given address.
@end table

This function raises an error if it cannot create a socket,
or cannot connect to the specified address.

@example
(make-client-socket 'inet "www.w3.com" 80)
  @result{} ;@r{a socket connected to www.w3.com, port 80}
(make-client-socket "127.0.0.1" 23)
  @result{} ;@r{a socket connected to localhost, port 23}
(make-client-socket 'unix "/tmp/.sock"
  @result{} ;@r{a socket connected to a unix domain socket "/tmp/.sock"}
@end example
@end defun

@defun make-server-socket :optional address-spec @dots{}
@{@t{gauche.net}@}
Creates and returns a server socket, listening the address
specified by @var{address-spec}.

@table @code
@item (make-server-socket 'unix @var{path} [:backlog @var{num}])
The socket is bound to a unix domain socket with a name @var{path}.
The keyword argument @var{backlog} is passed to @code{socket-listen}
to specify the maximum number of connection request the server can keep
before accepting them.  The default is 5.  If your server is very busy
and you see "connection refused" often, you might want to increase it.
@item (make-server-socket 'inet @var{port} [:reuse-addr? @var{flag}] [:sock-init @var{proc}] [:backlog @var{num}])
The socket is bound to an inet domain TCP socket, listening
port @var{port}, which must be a non-negative exact integer
or a string service name (e.g. @code{"http"}).
If @var{port} is zero, the system assigns one of available port numbers.
If a keyword argument @var{reuse-addr?} is given and true,
@code{SO_REUSEADDR} option is set to the socket before bound to
the port.  This allows the process to bind the server socket
immediately after other process releases the port.

Alternatively, you can pass a list of positive exact integers to @var{port}.
In that case, Gauche tries to bind each port in the list until it succeeds.

If keyword argument @code{sock-init} is given, it should be a procedure
that takes two arguments, a created socket and the socket address.
The procedure is called just after the socket is created.  It is
useful to set some special socket options.
The keyword argument @var{backlog} is the same as in unix sockets;
see the description above.
@item (make-server-socket @var{port} [:reuse-addr? @var{flag}] [:sock-init @var{proc}][:backlog @var{num}])
This is a synonym to the above form (except @var{port} must be
an integer).  This form is backward-compatible
with STk's @code{make-server-socket}.
@item (make-server-socket @var{sockaddr} [:reuse-addr? @var{flag}][:sock-init @var{proc}][:backlog @var{num}])
This form explicitly specifies the socket address to listen
by an instance of @code{<sockaddr>}.
@end table

@example
(make-server-socket 'inet 8080)
  @result{} #<socket (listen "0.0.0.0:8080")>
(make-server-socket 8080)
  @result{} #<socket (listen "0.0.0.0:8080")>
(make-server-socket 'inet 0)
  @result{} #<socket (listen "0.0.0.0:35628")>
(make-server-socket 'unix "/tmp/.sock")
  @result{} #<socket (listen "/tmp/.sock")>
@end example
@end defun

@defun make-server-sockets host port :key reuse-addr? sock-init
@{@t{gauche.net}@}
Creates one or more sockets that listen at @var{port}
on all available network interfaces of @var{host}.
You can specify a service name (such as "@code{http}") to
@var{port}, as well as an integer port number.
Returns a list of opened, bound and listened sockets.

This procedure is particularly useful when the host
has multiple protocol stacks, such as IPv4 and IPv6.
In that case, this procedure may return a list of IPv4 socket(s) and
IPv6 socket(s).
(On some OSes, single socket can listen both IPv4 and IPv6.  On
such platform, a list of single socket will be returned.)

The meaning of keyword arguments are the same as of @code{make-server-socket}.

You can pass 0 to @var{port}, just like @code{make-server-socket},
to let the system choose an available port number.  If pass 0 as
port and this procedure returns multiple sockets, it is guaranteed
that all the sockets share the same port number.
@end defun

Several accessors are available on the returned socket object.

@defun socket-address socket
@{@t{gauche.net}@}
Returns a socket address associated with @var{socket}.
If no address has been associated to the socket, @code{#f} is returned.
@end defun

@defun socket-input-port socket :key (buffering :modest)
@defunx socket-output-port socket :key (buffering :line)
@{@t{gauche.net}@}
Returns an input and output port associated with @var{socket},
respectively.

The keyword argument @var{buffering} specifies the buffering mode
of the port.  @xref{File ports}, for explanation of the
buffering mode.
@end defun

@defun socket-close socket
@{@t{gauche.net}@}
Closes @var{socket}.  All the ports associated to
@var{socket} are closed as well.
Note: as of release 0.7.2, this procedure does not shutdown
the connection.  It is because @var{socket} may be referenced
by forked process(es) and you might want to close it without
interfering the existing connection.   You can call
@code{socket-shutdown} to shutdown the connection explicitly.
@end defun

@defun call-with-client-socket socket proc :key input-buffering output-buffering
@{@t{gauche.net}@}
@var{socket} must be a connected client socket.  @var{proc} is called
with two arguments, an input port that reads from the socket
and an output port that writes to the socket.
The socket is closed after @var{proc} returns or @var{proc}
raises an error.

The keyword arguments @var{input-buffering} and @var{output-buffering}
are, if given, passed as the @var{buffering} keyword arguments
of @code{socket-input-port} and @code{socket-output-port}, respectively.
@end defun

This is an example of usage of high-level socket functions,
a very simple http client.

@example
#!/usr/bin/env gosh
(use gauche.net)

(define (usage)
  (display "Usage: swget url\n" (current-error-port))
  (exit 1))

;; Returns three values: host, port, and path.
(define (parse-url url)
  (rxmatch-let (rxmatch #/^http:\/\/([-A-Za-z\d.]+)(:(\d+))?(\/.*)?/ url)
      (#f host #f port path)
    (values host port path)))

(define (get url)
  (receive (host port path) (parse-url url)
    (call-with-client-socket
        (make-client-socket 'inet host (string->number (or port "80")))
      (lambda (in out)
        (format out "GET ~a HTTP/1.0\r\n" path)
        (format out "host: ~a\r\n\r\n" host)
        (flush out)
        (copy-port in (current-output-port))))))

(define (main args)
  (if (= (length args) 2)
      (get (cadr args))
      (usage))
  0)
@end example


@node Low-level socket interface, Netdb interface, High-level network functions, Networking
@subsection Low-level socket interface
@c NODE 低レベルソケットインタフェース

These functions provide APIs similar to the system calls.
Those who are familiar to programming with socket APIs will
find these functions useful since you can have more detailed control over
the sockets.

@defun make-socket domain type :optional protocol
@{@t{gauche.net}@}
Returns a socket with specified parameters.
@end defun

@defvr {Constant} PF_UNIX
@defvrx {Constant} PF_INET
@defvrx {Constant} PF_INET6
@{@t{gauche.net}@}
These constants are bound to the system's constants
@code{PF_UNIX}, @code{PF_INET} and @code{PF_INET6}.
You can use those values for @var{domain} argument of @code{make-socket}.

(@code{PF_INET6} is defined only if the underlying operating
system supports IPv6.)
@end defvr

@defvr {Constant} AF_UNIX
@defvrx {Constant} AF_INET
@defvrx {Constant} AF_INET6
@{@t{gauche.net}@}
These constants are bound to @code{AF_UNIX},
@code{AF_INET} and @code{AF_INET6}.

(@code{AF_INET6} is defined only if the underlying operating
system supports IPv6.)
@end defvr

@defvr {Constant} SOCK_STREAM
@defvrx {Constant} SOCK_DGRAM
@defvrx {Constant} SOCK_RAW
@{@t{gauche.net}@}
These constants are bound to @code{SOCK_STREAM}, @code{SOCK_DGRAM}
and @code{SOCK_RAW}, and suitable to pass to the @var{type} argument
of @code{make-socket}.
@end defvr

@defun socket-fd socket
@{@t{gauche.net}@}
Returns an integer system file descriptor of the underlying socket.
@end defun


@defun socket-status socket
@{@t{gauche.net}@}
Returns a internal status of @var{socket}, by one of the following
symbols.
@multitable {aaaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa}
@item none
@tab The socket is just created.
@item bound
@tab The socket is bound to an address by @code{socket-bind}
@item listening
@tab The socket is listening a connection by @code{socket-listen}
@item connected
@tab The socket is connected by @code{socket-connect} or @code{socket-accept}.
@item shutdown
@tab The socket is shutdown by @code{socket-shutdown}
@item closed
@tab The socket is closed by @code{socket-close}.
@end multitable
@end defun

@defun socket-bind socket address
@{@t{gauche.net}@}
Binds @var{socket} to the local network address @var{address}.
It is usually used to associate specific address to the server port.
If binding failed, an error is signaled (most likely the address is
already in use).

For the inet domain address, you can pass @var{address} with port=0;
the system assigns the port number and sets the actual address to
the @code{address} slot of @var{socket}.
@end defun

@defun socket-listen socket backlog
@{@t{gauche.net}@}
Listens @var{socket}.  The socket must be already bound to some
address.  @var{backlog} specifies maximum number of connection
requests to be queued.
@end defun

@defun socket-accept socket
@{@t{gauche.net}@}
Accepts a connection request coming to @var{socket}.
Returns a new socket that is connected to the remote entity.
The original @var{socket} keeps waiting for further connections.
If there's no connection requests, this call waits for one to come.

You can use @code{sys-select} to check if there's a pending connection
request.
@end defun

@defun socket-connect socket address
@{@t{gauche.net}@}
Connects @var{socket} to the remote address @var{address}.
This is the way for a client socket to connect to the remote entity.
@end defun

@defun socket-shutdown socket how
@{@t{gauche.net}@}
Shuts down connection of @var{socket}.  If @var{how} is @code{SHUT_RD} (or 0),
the receive channel of @var{socket} is disallowed.
If @var{how} is @code{SHUT_WR} (or 1), the send channel of
@var{socket} is disallowed.
If @var{how} is @code{SHUT_RDWR} (or 2), both receive and send channels are
disallowed.  It is an error to call this function on a non-connected socket.

If you shut down the send channel of the socket, the remote peer
sees EOF from its receive channel.  This is useful if the remote peer
expects EOF before sending something back to you.
@end defun

@defun socket-getsockname socket
@{@t{gauche.net}@}
Returns a @code{<sockaddr>} instance that is the local address of
@var{socket}.
@end defun

@defun socket-getpeername socket
@{@t{gauche.net}@}
Returns a @code{<sockaddr>} instance that is the peer address of
@var{socket}.
@end defun

@defun socket-send socket msg :optional flags
@defunx socket-sendto socket msg to-address :optional flags.
@{@t{gauche.net}@}
Interfaces to @code{send(2)} and @code{sendto(2)}, respectively.
Transmits the content of @var{msg} through @var{socket}.
@var{msg} can be either a string or a uniform vector; if you send
binary packets, uniform vectors are recommended.

Returns the number of octets that are actually sent.

When @code{socket-send} is used, @var{socket} must already be connected.
On the other hand, @code{socket-sendto} can be used for non-connected
socket, and the destination address is specified by
a @code{<sockaddr>} instance @var{to-address}.

The optional @var{flags} can be a bitwise OR of the integer
constants @code{MSG_*}.  See the system's manpage of @code{send(2)}
and @code{sendto(2)} for the details.
@end defun

@defun socket-sendmsg socket msghdr :optional flags
@{@t{gauche.net}@}
Sends a packet described by @var{msghdr} through @var{socket}
using @code{sendmsg(3)}.  The @var{msghdr} argument must be a
string or u8vector, and it must be prepared as a binary representation
of @code{struct msghdr}.  A reliable way to build a @var{msghdr} is
to use @code{socket-buildmsg} described below.

The @var{flags} argument is the same as @code{socket-send} and
@code{socket-sendto}.

Returns number of octets sent.

This procedure is not yet supported under the Windows native platform.
You can use the feature identifier @code{gauche.os.windows} to check
availability of this procedure (@pxref{Platform-dependent features}).
@end defun

@defun socket-buildmsg addr iov control flags :optional buf
@{@t{gauche.net}@}
Builds a binary representation of @code{struct msghdr} which is
suitable to be given to @code{socket-sendmsg}.
You have to be familiar with @code{sendmsg(3)} system call
to understand this procedure.

The @var{addr} argument must be an instance of @code{<sockaddr>}
or @code{#f}.  If it is a sockaddr, the @code{msg_name} field
of the msghdr is filled with the address.

The @var{iov} argument must be a vector or @code{#f}.  If it is
a vector, each element must be either a string or a u8vector.
They are used to fill @code{msg_iov} field of the msghdr.
Their contents will be concatenated in the kernel to make a payload.

The @var{control} argument represents ancillary data, a.k.a. cmsg.
It can be @code{#f} if you don't need ancillary data.  Otherwise,
it must be a list in the following form:
@example
((@var{level} @var{type} @var{data}) @dots{})
@end example
Where @var{level} and @var{type} are exact integers,
and @var{data} is either a string or a u8vector.
The former two are used to fill cmsg's @code{cmsg_level}
and @code{cmsg_type} fields.  The @var{data} is for
cmsg's data (@code{cmsg_len} is calculated from @var{data}).

The @var{flags} argument is used to fill @code{msg_flags}.

If the @var{buf} argument is @code{#f} or omitted, new memories
are allocated to construct the msghdr.  If a mutable
u8vector is given to @var{buf}, @code{socket-buildmsg} tries
to use it to construct the msghdr as much as possible; it allocates
memory only if @var{buf} is used up.

Returns the constructed msghdr as a u8vector.

This procedure is not yet supported under the Windows native platform.
You can use the feature identifier @code{gauche.os.windows} to check
availability of this procedure (@pxref{Platform-dependent features}).
@end defun

@defun socket-recv! socket buf :optional flags
@{@t{gauche.net}@}
Interface to @code{recv(2)}.  Receives a message from @var{socket},
and stores it into @var{buf}, which must be a mutable uniform vector.
Returns the number of bytes actually written.   @var{socket} must
be already connected.  If the size of @var{buf} isn't enough to
store the entire message, the rest may be discarded depending on
the type of @var{socket}.

The optional @var{flags} can be a bitwise OR of the integer
constants @code{MSG_*}.  See the system's manpage of @code{recv(2)}
for the details.
@end defun

@defun socket-recvfrom! socket buf addrs :optional flags
@{@t{gauche.net}@}
Interface to @code{recvfrom(2)}.  Receives a message from
@var{socket}, which may be unconnected, and stores it to
a mutable uniform vector @var{buf}.  Like @var{socket-recv},
if the size of @var{buf} isn't enough to store the entire message,
the rest may be discarded depending on the type of @var{socket}.

Returns two values; the number of bytes actually written into
@var{buf}, and an instance of a subclass of @code{<sys-sockaddr>}
which shows the sender's address.

The @var{addrs} argument must be a list of instances of socket
addresses, optionally its last cdr being @code{#t} (as a special
case, if there's zero addresses to pass, just @code{#t} may be given).
The content of each address doesn't matter; if the protocol family
of one of them matches the sender's address, the sender's address
is written into the passed sockaddr object.  By listing sockaddrs
of possible families, you can count on @code{socket-recvfrom!}
to allocate no memory on successful operation.  It is useful if
you call @code{socket-recvfrom!} in a speed-sensitive inner loop.

If the sender's address family doesn't match any of the addresses
given to @var{addrs}, the behavior depends on whether the list is
terminated by @code{()} or @code{#t}.  If it is terminated by @code{()},
(i.e. @var{addrs} is a proper list), the sender's address is simply
discarded and @code{socket-recvfrom!} returns @code{#f} as the
second value.  If the list is terminated by @code{#t},
@code{socket-recvfrom!} allocates a fresh sockaddr object and
returns it as the second value.

Two simple cases: If you pass @code{()} to @var{addrs}, the sender's
address is always discarded, which is useful if @var{socket} is
connected (that is, you already know your sender's address).
If you pass @code{#t} to @var{addrs}, a new socket address
object is always allocated for the sender's address,
which is convenient if you don't mind memory allocation.

The optional @var{flags} can be a bitwise OR of the integer
constants @code{MSG_*}.  See the system's manpage of @code{recvfrom(2)}
for the details.
@end defun


@defun socket-recv socket bytes :optional flags
@defunx socket-recvfrom socket bytes :optional flags
@{@t{gauche.net}@}
Like @code{socket-recv!} and @code{socket-recvfrom!}, but
these returns the received message as a (possibly incomplete)
string, up to @var{bytes} size.  Additionally,
@code{socket-recvfrom} always allocates a socket address
object for the sender's address.

The use of these procedures are discouraged, since they
often returns incomplete strings for binary messages.
Using strings for binary data creates many pitfalls.
Uniform vectors (especially @code{u8vector}s) are for binary data.
(The reason these procedures return strings is merely historical.)
@end defun

@defvar MSG_CTRUNC
@defvarx MSG_DONTROUTE
@defvarx MSG_EOR
@defvarx MSG_OOB
@defvarx MSG_PEEK
@defvarx MSG_TRUNC
@defvarx MSG_WAITALL
@{@t{gauche.net}@}
Pre-defined integer constants to be used as @var{flags} values
for @code{socket-send}, @code{socket-sendto}, @code{socket-recv}
and @code{socket-recvfrom}.   Some of these constants may not be
defined if the underlying operating system doesn't provide them.
@end defvar

Further control over sockets and protocol layers is possible
by getsockopt/setsockopt interface, as described below.

@defun socket-setsockopt socket level option value
@defunx socket-getsockopt socket level option rsize
@{@t{gauche.net}@}
These are the interface to setsockopt() and getsockopt() calls.
The interface is a bit clumsy, in order to allow full access to
those low-level calls.

@var{socket} must be a non-closed socket object.
@var{level} and @var{option} is an exact integer to specify
the level of protocol stack and the option you want to deal with.
There are several variables pre-bound to system constants listed below.

To set the socket option, you can pass either an exact integer or
a string to @var{value}.  If it is an integer, the value is passed
to setsockopt(2) as C @code{int} value.  If it is a string, the
byte sequence is passed as is.  The required type of value depends on
the option, and Gauche can't know if the value you passed is expected
by setsockopt(2); it is your responsibility to pass the correct values.

To get the socket option, you need to tell the maximum length of expected
result by @var{rsize} parameter, for Gauche doesn't know the amount
of data each option returns.
@code{socket-getsockopt} returns the option value as a byte string.
If you know the option value is an integer, you can pass 0 to @var{rsize};
in that case @code{socket-getsockopt} returns the value as an exact integer.

Note about the name: I tempted to name these function socket-@{set|get@}opt
or socket-@{set|get@}-option,
but I rather took the naming consistency.  Hence duplicated "sock"s.


@end defun

The following predefined variables are provided.
Note that some of them are not available on all platforms.
See manpages @code{socket(7)}, @code{tcp(7)} or @code{ip(7)} of
your system to find out exact specification of those values.

For ``level'' argument:
@defvar SOL_SOCKET
@defvarx SOL_TCP
@defvarx SOL_IP
@{@t{gauche.net}@}
These variables are bound to @code{SOL_SOCKET}, @code{SOL_TCP} and
@code{SOL_IP}, respectively.
@end defvar

For ``option'' argument:
@defvar SO_KEEPALIVE
@{@t{gauche.net}@}
Expects integer value.  If it is not zero, enables sending  of
keep-alive messages on connection-oriented sockets.
@end defvar

@defvar SO_OOBINLINE
@{@t{gauche.net}@}
Expects integer value.  If it is not zero, out-of-band data is
directly placed into the receive data stream.  Otherwise
out-of-band  data  is  only passed when the
MSG_OOB flag is set during receiving.
@end defvar

@defvar SO_REUSEADDR
@{@t{gauche.net}@}
Expects integer value.  If it is not zero, @code{socket-bind}
allows to reuse local addresses, unless an active listening
socket bound to the address.
@end defvar

@defvar SO_TYPE
@{@t{gauche.net}@}
Gets the socket type as an integer (like @code{sock_stream}).
Can be only used with @code{socket-getsockopt}.
@end defvar

@defvar SO_BROADCAST
@{@t{gauche.net}@}
Expects integer value.  If it is not zero, datagram sockets
are allowed to send/receive broadcast packets.
@end defvar

@defvar SO_PRIORITY
@{@t{gauche.net}@}
Expects integer value, specifying the protocol-defined priority
for all packets to be sent on this socket.
@end defvar

@defvar SO_ERROR
@{@t{gauche.net}@}
Gets and clears the pending socket error as an integer.
Can be only used with @code{socket-getsockopt}.
@end defvar


@defun inet-checksum packet size
@{@t{gauche.net}@}
Calculates one's complement of Internet Checksum (RFC1071) of the
@var{packet}, which must be given as a uniform vector.  First
@var{size} bytes of @var{packet} are used for calculation.
Returned value is in network byte order (big-endian).
It is an error if @var{size} is greater than the size of @var{packet}.

Note: The used algorithm assumes @var{packet} is not too big (< 64K).
@end defun


@node Netdb interface,  , Low-level socket interface, Networking
@subsection  Netdb interface
@c NODE Netdbインタフェース




@deftp {Builtin Class} <sys-hostent>
@clindex sys-hostent
@{@t{gauche.net}@}
A class of objects for network hosts.  Corresponding to
@code{struct hostent} in C.  The following slots are available read-only.

@defivar {<sys-hostent>} name
The formal name of the host (string).
@end defivar
@defivar {<sys-hostent>} aliases
A list of alias names of the host (list of strings).
@end defivar
@defivar {<sys-hostent>} addresses
A list of addresses (list of strings).  Only ipv4 address is
supported currently.  Each address is represented by dotted decimal
notation.
@end defivar
@end deftp

@defun sys-gethostbyname name
@{@t{gauche.net}@}
Looks up a host named @var{name}.
If found, returns a @code{<sys-hostent>} object.
Otherwise, returns @code{#f}.
@example
(let ((host (sys-gethostbyname "www.w3c.org")))
  (list (slot-ref host 'name)
        (slot-ref host 'aliases)
        (slot-ref host 'addresses)))
  @result{} ("www.w3.org" ("www.w3c.org") ("18.29.1.34" "18.29.1.35"))
@end example
@end defun

@defun sys-gethostbyaddr addr proto
@{@t{gauche.net}@}
Looks up a host that has an address @var{addr} of protocol @var{proto}.
@var{addr} is a natural string representation of the address;
for ipv4, it is a dotted decimal notation.  @var{proto} is a
protocol number; only @code{AF_INET} is supported currently.
If the host is found, returns a @code{<sys-hostent>} object.
Otherwise, returns @code{#f}.
@example
(let ((host (sys-gethostbyaddr "127.0.0.1" AF_INET)))
  (list (slot-ref host 'name)
        (slot-ref host 'aliases)
        (slot-ref host 'addresses))
  @result{} ("localhost" ("localhost.localdomain") ("127.0.0.1"))
@end example
@end defun

@deftp {Builtin Class} <sys-servent>
@clindex sys-servent
@{@t{gauche.net}@}
An entry of the network service database.  Corresponding to
@code{struct servent} in C.  The following slots are available read-only.

@defivar {<sys-servent>} name
The formal name of the service (string).
@end defivar
@defivar {<sys-servent>} aliases
A list of alias names of the service (list of strings).
@end defivar
@defivar {<sys-servent>} port
A port number registered for this service (exact integer).
@end defivar
@defivar {<sys-servent>} proto
A protocol name for this service (string).
@end defivar
@end deftp

@defun sys-getservbyname name proto
@{@t{gauche.net}@}
Looks up the network service database with a service name @var{name} and
a protocol @var{proto}.  Both @var{name} and @var{proto} must be a string.
If a service is found, an instance of @code{<sys-servent>} is returned.
Otherwise, @code{#f} is returned.
@example
(let ((serv (sys-getservbyname "http" "tcp")))
  (list (slot-ref serv 'name)
        (slot-ref serv 'aliases)
        (slot-ref serv 'port)
        (slot-ref serv 'proto)))
  @result{} ("http" () 80 "tcp")
@end example
@end defun

@defun sys-getservbyport port proto
@{@t{gauche.net}@}
Looks up the network service database with a service port @var{port} and
a protocol @var{proto}.  @var{port} must be an exact integer, and
@var{proto} must be a string.
If a service is found, an instance of @code{<sys-servent>} is returned.
Otherwise, @code{#f} is returned.
@example
(let ((serv (sys-getservbyport 6000 "tcp")))
  (list (slot-ref serv 'name)
        (slot-ref serv 'aliases)
        (slot-ref serv 'port)
        (slot-ref serv 'proto)))
  @result{} ("x-server" () 6000 "tcp")
@end example
@end defun

@deftp {Builtin Class} <sys-protoent>
@clindex sys-protoent
@{@t{gauche.net}@}
An entry of the protocol database.   Corresponds to @code{struct protoent}
in C.   The following slots are available read-only.

@defivar {<sys-servent>} name
The formal name of the protocol (string).
@end defivar
@defivar {<sys-servent>} aliases
A list of alias names of the protocol (list of strings).
@end defivar
@defivar {<sys-servent>} proto
A protocol number (exact integer).
@end defivar
@end deftp

@defun sys-getprotobyname name
@{@t{gauche.net}@}
Looks up the network protocol database with a name @var{name},
which must be a string.
If a protocol is found, an instance of @code{<sys-protoent>} is returned.
Otherwise, @code{#f} is returned.
@example
(let ((proto (sys-getprotobyname "icmp")))
  (list (slot-ref proto 'name)
        (slot-ref proto 'aliases)
        (slot-ref proto 'proto)))
  @result{} ("icmp" ("ICMP") 1)
@end example
@end defun

@defun sys-getprotobynumber number
@{@t{gauche.net}@}
Looks up the network protocol database with a protocol number @var{number},
which must be an exact integer.
If a protocol is found, an instance of @code{<sys-protoent>} is returned.
Otherwise, @code{#f} is returned.
@example
(let ((proto (sys-getprotobynumber 17)))
  (list (slot-ref proto 'name)
        (slot-ref proto 'aliases)
        (slot-ref proto 'proto)))
  @result{} ("udp" ("UDP") 17)
@end example
@end defun

@deftp {Builtin Class} <sys-addrinfo>
@clindex sys-addrinfo
@{@t{gauche.net}@}
The new interface to keep address information.
Corresponds to @code{struct addrinfo} in C.
This is only available if gauche is configured with --enable-ipv6 option.
The following slots are provided.

@defivar {<sys-addrinfo>} flags
@end defivar
@defivar {<sys-addrinfo>} family
@end defivar
@defivar {<sys-addrinfo>} socktype
@end defivar
@defivar {<sys-addrinfo>} protocol
@end defivar
@defivar {<sys-addrinfo>} addrlen
@end defivar
@defivar {<sys-addrinfo>} addr
@end defivar
@end deftp

@defun sys-getaddrinfo nodename servname hints
@{@t{gauche.net}@}
Returns a list of @code{<sys-addrinfo>} instances from the given @var{nodename},
@var{servname} and @var{hints}.
This is only available if gauche is compiled with --enable-ipv6 option.
@end defun

@defun sys-ntohs integer
@defunx sys-ntohl integer
@defunx sys-htons integer
@defunx sys-htonl integer
@{@t{gauche.net}@}
Utility functions to convert 16bit (@code{s}) or 32bit (@code{l}) integers
between @emph{network} byte order (@code{n}) and @emph{host} byte order
(@code{h}).

Scheme API to the netdb interface calls those byte order conversion
functions internally, so you don't usually need them so much as in C
programs.  However, it may be useful when you're constructing or
analyzing binary packets.  See also @ref{Packing binary data} to handle
binary data.
@end defun

@c ----------------------------------------------------------------------
@node Package metainformation, Parameters (extra), Networking, Library modules - Gauche extensions
@section @code{gauche.package} - Package metainformation
@c NODE パッケージメタ情報, @code{gauche.package} - パッケージメタ情報

@deftp {Module} gauche.package
@mdindex gauche.package
Gauche manages extra libraries and extension modules as @emph{packages}.

Each package source tree has @file{package.scm} on top directory, which
contains @code{define-gauche-package} form that provides metainformation
about the package---the package name, version, author, dependencies, etc.

When the package is installed, the standard installation process copies
that information, with additional information such as the version of
Gauche used to build the package, into @file{.packages} subdirectory
of the library installation path, with the name @file{PACKAGENAME.gpd},
where @code{PACKAGENAME} is the name of the package.

We collectively call @file{package.scm} and @file{*.gpd} as
@emph{package description file}.

This module provides utility procedures to read and write package 
description files, and search installed @file{*.gpd} files.
@end deftp

@subheading @code{define-gauche-package} form

@subheading @code{configure} script and @code{*.gpd} file generation

@subheading Utility procedures

@defun <gauche-package-description>
@{@t{gauche.package}@}
@end defun

@defun path->gauche-package-description filename
@{@t{gauche.package}@}
@end defun

@defun write-gauche-package-description description :optional oport
@{@t{gauche.package}@}
@end defun

@defun make-gauche-package-description
@{@t{gauche.package}@}
@end defun

@defun gauche-package-description-paths :key all-versions
@{@t{gauche.package}@}
@end defun

@defun find-gauche-package-description name :key all-versions
@{@t{gauche.package}@}
@end defun




@c ----------------------------------------------------------------------
@node Parameters (extra), Parsing command-line options, Package metainformation, Library modules - Gauche extensions
@section @code{gauche.parameter} - Parameters (extra)
@c NODE パラメータ(追加), @code{gauche.parameter} - パラメータ(追加)

@deftp {Module} gauche.parameter
@mdindex gauche.parameter
Parameters are now built-in, so you no longer need to @code{use} this
module for basic parameter functionalities.
This module is provided mainly so that the existing code with
@code{(use gauche.parameter)} won't get an error.

It also provides a less-frequenlty used parameter observer interface.
@end deftp

@defun parameter-observer-add! p proc :optional when where
@{@t{gauche.parameter}@}
Adds @var{proc} to "observer" procedures of a parameter @var{p}.
Observer procedures are called either (1) just before
a new value is set to the parameter, or (2) just after the new value
is set to the parameter.   In case of (1), a filter procedure is
already applied before a callback is called.
In either case, observer procedures are called with two arguments,
the old value and the new value.  The return value(s) of observer
procedures are discarded.

The optional @var{when} argument must be either a symbol @code{before}
or @code{after}, to specify whether @var{proc} should be called
before or after the value is changed.   If omitted, @code{after} is
assumed.

The optional @var{where} argument must be either a symbol
@code{append} or @code{prepend}, to specify whether @var{proc} should
be prepended or appended to the existing observer procedure list.
If omitted, @code{append} is assumed.

@emph{Note}: Although the parameter value itself is thread-local,
the observer list is shared by all threads.
@end defun


@defun parameter-observer-delete! p proc :optional when
@{@t{gauche.parameter}@}
Deletes @var{proc} from observer procedure list of a parameter @var{p}.
If @var{proc} is not in the list, nothing happens.
You can give either a symbol @code{before} or @code{after} to
@var{when} argument to specify from which list @var{proc} should be
deleted.  If @var{when} argument is omitted, @var{proc} is deleted
from both lists.
@end defun

@defun parameter-pre-observers p
@defunx parameter-post-observers p
@{@t{gauche.parameter}@}
Returns a hook object (@pxref{Hooks}) that keeps
"before" or "after" observers, respectively.

@emph{Note}: Although the parameter value itself is thread-local,
these hook objects are shared by all threads.
@end defun


@c ----------------------------------------------------------------------
@node Parsing command-line options, Partial continuations, Parameters (extra), Library modules - Gauche extensions
@section @code{gauche.parseopt} - Parsing command-line options
@c NODE コマンドライン引数の解析, @code{gauche.parseopt} - コマンドライン引数の解析

@deftp {Module} gauche.parseopt
@mdindex gauche.parseopt
This module defines a convenient way to parse command-line options.
The interface is hinted by Perl, and conveniently handles long-format
options with multiple option arguments.

Actually, you have a few choices to parse command-line
options in Gauche.
SRFI-37 (@pxref{A program argument processor}) provides
functional interface to parse POSIX/GNU compatible argument syntax.
SLIB has @code{getopt}-compatible utility.
Required features may differ from application to application,
so choose whichever fits your requirement.
@end deftp

@subheading High-level API

@defmac let-args args (bind-spec @dots{} [. rest]) body @dots{}
@{@t{gauche.parseopt}@}
This macro captures the most common pattern of argument processing.
It takes a list of arguments, @var{args}, and scans it to find
Unix-style command-line options and binds their values to local
variables according to @var{bind-spec}, then executes @var{body} @dots{}.

Let's look at a simple example first, which gives you a good idea of
what this form does. (See the ``Examples'' section below for more
examples).

@example
(define (main args)
  (let-args (cdr args)
      ((verbose     "v|verbose")
       (outfile     "o|outfile=s")
       (debug-level "d|debug-level=i" 0)
       (help        "h|help" => (cut show-help (car args)))
       . restargs
      )
    ....))

(define (show-help progname)
  ...)
@end example

The local variable @var{verbose} will be bound to @code{#t} if
a command-line argument @code{-v} or @code{--verbose} is given,
and to @code{#f} otherwise.
The variable @var{output} is specified to take one option argument;
if the command-line arguments are given like @code{-o out.txt},
@var{outfile} receives
@code{"out.txt"}.  The @var{debug-level} one is similar, but the
option argument is coerced to an integer, and also it has default
value 0 when the option isn't given.  The @var{help} clause
invokes an action rather than merely binding the value.

(Note: Currently @code{let-args} does not distinguish so-called
short and long options, e.g. @code{-v} and @code{--v} have the same
effect, so as @code{-verbose} and @code{--verbose}.  In future we
may add an option to make it compatible with @code{getopt_long(3)}.)

The final @var{restargs} variable after the dot receives a list of
non-optional command-line arguments.

Let's look at @var{bind-spec} in detail.
It must be one of the following forms.

@example
1. (@var{var} @var{option-spec})
2. (@var{var} @var{option-spec} @var{default})
3. (@var{var} @var{option-spec} => @var{callback})
4. (@var{var} @var{option-spec} @var{default} => @var{callback})

5. (else => @var{handler})
6. (else @var{formals} @var{body} ...)
@end example

A list of command-line arguments passed to @var{args} are parsed
according to @var{option-spec}s.  If the corresponding option
is given, a variable @var{var} is bound to a value as follows:

@example
(a) If the @var{bind-spec} is 1. or 2., then
  (a1) If @var{option-spec} doesn't require an argument, then @code{#t}:
  (a2) If @var{option-spec} requires one argument, then the value of
       the argument:
  (a3) If @var{option-spec} requires more than one argument,
       the list of the values of the arguments.
(b) If the @var{bind-spec} is 3. or 4., then @var{callback} is called with
  the value(s) of arguments, and its return value.
@end example

We'll explain the details of @var{option-spec} later.

As a special case, @var{var} can be @code{#f}, in which case
the value is ignored.  It is only useful for side effects in
@var{callback}.

If the corresponding option is not given in @var{args},
@var{var} is bound to @var{default} if it is given, or
@code{#f} otherwise.

The last @var{bind-spec} may be the form 5 or 6. in which case
the clause is selected when no other @var{option-spec} matches
a given command-line option.
In the form 5, @var{handler} will be called with three arguments;
the given option, a list of remaining command-line arguments,
and a continuation procedure.  The @var{handler}
is supposed to handle the given option, and it may call the
continuation procedure with the remaining arguments to continue
processing, or it may return a list of arguments which will
be treated as non-optional command-line arguments.
The form 6 is a shorthand notion of
@code{(else => (lambda @var{formals} @var{body} ...))}.

The @var{bind-spec} list can be an improper list, whose last cdr is
a symbol.  In which case, a list of the rest of the command-line arguments
is bound to the variable named by the symbol.

Note that the @var{default}, @var{callback}, and forms in @code{else}
clause is evaluated outside of the scope of binding of @var{var}s
(as the name @code{let-args} implies).

Unlike typical @code{getopt} or @code{getopt_long} implementation in C,
@code{let-args} does not permute the given command-line arguments.
It stops parsing when it encounters a non-option argument (argument without
starting with a minus sign).

If the parser encounters an argument with only two minus signs `@code{--}',
it stops argument parsing and returns a list of arguments after `@code{--}'.


After all the bindings is done, @var{body} @dots{} are evaluated.
@var{Body} may began with internal define forms.
@end defmac

@subheading Option spec

@var{option-spec} is a string that specifies the name of the option and
how the option takes the arguments.  An alphanumeric characters, underscore,
plus and minus sign is allowed for option's names, except that
minus sign can't be the first character, i.e. the valid option name
matches a regexp @code{#/[\w+][-\w+]*/}.

If the option takes argument(s), it can be specified by attaching
equal character and a character (or characters) that represents
the type of the argument(s) after the name.  The option
can take more than one arguments.
The following characters are recognized as a type specifier of
the option's argument.

@table @code
@item s
String.
@item n
Number.
@item f
Real number (coerced to flonum).
@item i
Exact integer.
@item e
S-expression.
@item y
Symbol (argument is converted by @code{string->symbol}).
@end table

Let's see some examples of @var{option-spec}:

@table @code
@item "@var{name}"
Specifies option @var{name}, that doesn't take any argument.

@item "@var{name}=s"
Option @var{name} takes one argument, and it is passed as a string.

@item "@var{name}=i"
Option @var{name} takes one argument, and it is passed as an exact integer.

@item "@var{name}=ss"
Option @var{name} takes two arguments, both string.

@item "@var{name}=iii"
Option @var{name} takes three integer arguments.

@item "@var{name}=sf"
Option @var{name} takes two arguments, the first is a string and the
second is a number.
@end table

If the option has alternative names, they can be concatenated by "|".
For example, an option spec @code{"h|help"} will match both
"h" and "help".

In the command line, the option may appear with preceding
single or double minus signs.  The option's argument may be combined
by the option itself with an equal sign.  For example, all the following
command line arguments match an option spec @code{"prefix=s"}.
@example
-prefix /home/shiro
-prefix=/home/shiro
--prefix /home/shiro
--prefix=/home/shiro
@end example

@subheading Error handling

@deftp {Condition Type} <parseopt-error>
@{@t{gauche.parseopt}@}
When @code{let-args} encounters an argument that cannot be
processed as specified by option specs, an error of condition type
@code{<parseopt-error>} is raised.   The cases include
when a mandatory option argument is missing, or when
an option argument has a wrong type.

@example
(let-args '("-a" "foo") ((a "a=i")) ; option a requires integer
  (list a))
 @result{} @r{parseopt-error}
@end example

Note that this condition is about parsing the given @var{args}.
If an invalid @var{option-spec} is given,
an ordinary error is thrown.
@end deftp

@subheading Examples

This example is taken from @code{gauche-install} script.
The @var{mode} option takes numbers in octal, so it
uses the callback procedure to convert it.
See also the @code{else} clause how to handle unrecognized option.

@example
  (let-args (cdr args)
      ((#f      "c")        ;; ignore for historical reason
       (mkdir   "d|directory")
       (mode    "m|mode=s" #o755 => (cut string->number <> 8))
       (owner   "o|owner=s")
       (group   "g|group=s")
       (srcdir  "S|srcdir=s")
       (target  "T|target=s")
       (utarget "U|uninstall=s")
       (shebang "shebang=s")
       (verb    "v")
       (dry     "n|dry-run")
       (#f      "h|help" => usage)
       (else (opt . _) (print "Unknown option : " opt) (usage))
       . args)
    ...)
@end example

The next example is a small test program to show the usage of
@code{else} clause.  It gathers all options into the variable @var{r},
except that when it sees @code{-c} it stops argument processing and
binds the rest of the arguments to @var{restargs}.

@example
(use gauche.parseopt)

(define (main args)
  (let1 r '()
    (let-args (cdr args)
      ((else (opt rest cont)
         (cond [(equal? opt "c") rest]
               [else (push! r opt) (cont rest)]))
       . restargs)
     (print "options: " (reverse r))
     (print "restargs: " restargs)
     0)))
@end example

Sample session of the above script (suppose it is saved as @file{example}).

@example
$ ./example -a -b -c -d -e foo
options: (a b)
restargs: (-d -e foo)
$ ./example -a -b -d -e foo
options: (a b d e)
restargs: (foo)
@end example


@subheading Low-level API

The followings are lower-level API used to build @code{let-args}
macro.


@defmac parse-options args (option-clause @dots{})
@{@t{gauche.parseopt}@}
@var{args} is an expression that contains a list of command-line arguments.
This macro scans the command-line options (an argument that begins with
`@code{-}') and processes it as specified in @var{option-clause}s, then
returns the remaining arguments.

Each @var{option-clause} is consisted by a pair of @var{option-spec}
and its action.

If a given command-line option matches one of @var{option-spec}, then
the associated action is evaluated.  An action can be one of the
following forms.

@table @code
@item @var{bind-spec} @var{body} @dots{}
@var{bind-spec} is a proper or dotted list of variables like lambda-list.
The option's arguments are bound to @var{bind-spec}, then
then @var{body} @dots{} is evaluated.

@item => @var{proc}
If a command-line option matches @var{option-spec}, calls a procedure
@var{proc} with a list of the option's arguments.
@end table

If a symbol @code{else} is at the position of @var{option-spec},
the clause is selected when no other option clause matches a given
command-line option.  Three ``arguments'' are associated to
the clause; the unmatched option, the rest of arguments, and
a procedure that represents the option parser.

@end defmac

@defmac make-option-parser (option-clause @dots{})
@{@t{gauche.parseopt}@}
This is a lower-level interface.  @var{option-clause}s are the
same as @code{parse-options}.  This macro returns a procedure
that can be used later to parse the command line options.

The returned procedure takes one required argument and one
optional argument.  The required argument is a list of strings,
for given command-line arguments.  The optional argument may
be a procedure that takes more than three arguments, and if given,
the procedure is used as if it is the body of @code{else} option clause.
@end defmac

@c ----------------------------------------------------------------------
@node Partial continuations, High-level process interface, Parsing command-line options, Library modules - Gauche extensions
@section @code{gauche.partcont} - Partial continuations
@c NODE 部分継続, @code{gauche.partcont} - 部分継続

@deftp {Module} gauche.partcont
@mdindex gauche.partcont
Gauche internally supports partial continuations
(a.k.a. delimited continuations) natively.
This module exposes the feature for general use.
@end deftp

Note:
Partial continuations use two operators, @code{reset} and @code{shift}.
Those names are introduced in the original papers, and stuck in the
programming world.  Unfortunately those names are too generic as
library function names.  We thought giving them more descriptive names,
but decided to keep them after all; when you talk about partial
continuations you can't get away from those names.  If these names
conflict to other names in your program, you can use @code{:prefix}
import specifier (@pxref{Using modules}), for example as follows:

@example
;; Add prefix pc: to the 'reset' and 'shift' operators.
(use gauche.partcont :prefix pc:)

(pc:reset ... (pc:shift k ....) )
@end example

@defmac reset expr @dots{}
@{@t{gauche.partcont}@}
Saves the current continuation, and executes @var{expr} @dots{} with
a @emph{null continuation} or @emph{empty continuation}.
The @code{shift} operator captures the continuation from the @code{shift}
expression to this null continuation.

Note on @emph{implicit delimited continuations}:
There's an occasion Gauche effectively calls @code{reset} internally:
When C routine calls back to Scheme in non-CPS manner.
(If you know C API, it is @code{Scm_EvalRec()}, @code{Scm_ApplyRec*()},
@code{Scm_Eval()} and @code{Scm_Apply()} family of functions.)  The callers
of such routines expect the result is returned at most once, which won't
work well with Scheme's continuations that have unlimited extent.
Such calls create delimited continuations implicitly.

For example, the @code{main} routine of @code{gosh} calls Scheme REPL by
@code{Scm_Eval()}, which means the entire REPL is effectively surrounded
by a @code{reset}.  So, if you call @code{shift} without corresponding
@code{reset}, the continuation of @code{shift} becomes the continuation
of the entire REPL---which is to exit from @code{gosh}.
This may be surprising if you don't know about the implicit delimited
continuation.

Other places the implicit delimited continuations are created
are the handlers virtual ports (@pxref{Virtual ports}),
@code{object-apply} methods called from @code{write} and @code{display},
and GUI callbacks such as the one registered by @code{glut-display-func}
(See the document of Gauche-gl for the details), to name a few.

In general you don't need to worry about it too much, since most
built-in and extension routines written in C calls back Scheme in CPS manner,
and works with both full and delimited continuations.
@end defmac

@defmac shift var expr @dots{}
@{@t{gauche.partcont}@}
Packages the continuation of this expression until the current null
continuation marked by the most recent @code{reset} into a procedure,
binds the procedure to @var{var}, then executes @var{expr} @dots{}
with the continuation saved by the most recent @code{reset}.

That is, after executing @var{expr} @dots{}, the value is passed
to the expression waiting for the value of the most recent @code{reset}.
When a partial continuation bound to @var{var} is executed, its
argument is passed to the continuation waiting for the value
of this @code{shift}.   When the execution of the partial continuation
reaches its end, it returns from the expression waiting
for the value of invocation of @var{var}.
@end defmac

@defun call/pc proc
@{@t{gauche.partcont}@}
This is a wrapper of @code{shift}.  @code{(shift k expr @dots{})}
is equivalent to @code{(call/pc (lambda (k) expr @dots{}))}.
Sometimes this similarity of @code{call/cc} comes handy.
@end defun

Well, @dots{} I bet you feel like your brain is twisted hard
unless you are one of those rare breed from the land of continuation.
Let me break down what's happening here informally and intuitively.

Suppose a procedure A calls an expression B.   If A expects a return
value from B and continue processing, we split the part after returning
from B into a separate chunk A', then we can think of the whole
control flow as this straight chain:

@example
A -> B -> A'
@end example

@code{A -> B} is a procedure call and @code{B -> A'} is a return,
but we all know procedure call and return is intrinsically the
same thing, right?

Procedure B may call another procedure C, and so on.  So when
you look at an execution of particular piece of code, you can
think of a chain of control flow like this:

@example
... -> A -> B -> C -> .... -> C' -> B' -> A' -> ...
@end example

The magic procedure @code{call/cc} picks the head of the chain
following its execution (marked as @code{*} in the figure below),
and passes it to the given procedure (denoted @code{k} in the figure
below).
So, whenever @code{k} is invoked, the control goes through the
chain from @code{*}.

@example
... -> A -> B -> (call/cc -> (lambda (k) ... ) ) -> B' -> A' -> ...
                                      |             ^
                                      \-----------> *
@end example

One difficulty with @code{call/cc} is that the extracted chain
is only one-ended---we don't know what is chained to the
right.  In fact, what will come after that depends
on the whole program; it's outside of local control.  This global
attribute of @code{call/cc} makes it difficult to deal with.

The @code{reset} primitive @emph{cuts} this chain of
continuation.  The original chain of continuation (the @code{x}-end
in the following figure) is saved somewhere, and the continuation
of @code{reset} itself becomes open-ended (the @code{o}-end
in the following figure).

@example
... -> A -> B -> (reset ... ) -> o

                                 x -> B ' -> A' -> ...
@end example

A rule: If control reaches to the @code{o}-end, we pick the
@code{x}-end @emph{most recently saved}.
Because of this, @code{reset} alone doesn't show any
difference in the program behavior.

Now what happens if we insert @code{shift} inside @code{reset}?
This is a superficial view of inserting @code{shift} into
somewhere down the chain of reset:

@example
... -> (reset -> X -> Y -> (shift k ... ) -> Y' -> X' ) -> o
@end example

What actually happens is as follows.

@enumerate
@item
@code{shift} packages @emph{the rest of the chain of work} until the
end of @code{reset}, and bind it to the variable @var{k}.
@item
The continuation of @code{shift} becomes a null continuation as well,
so after @code{shift} returns, the control skips the rest of
operations until the corresponding @code{reset}.
@end enumerate

@example
... -> (reset -> X -> Y -> (shift k ... ) ---------> ) -> o
                                  |
                                  \-------> Y' -> X' ) -> o
@end example

In other words, when you consider the @code{reset} form as
one chunk of task, then @code{shift} in it
@emph{stashes away} the rest of the task and immediately
returns from the task.

Let's see an example.  The @var{walker} argument in
the following example is a procedure that takes a procedure
and some kind of collection,
and applies the procedure to the each element in the collection.
We ignore the return value of @var{walker}.

@example
(define (inv walker)
  (lambda (coll)
    (define (continue)
      (reset (walker (lambda (e) (shift k (set! continue k) e)) coll)
             (eof-object)))
    (lambda () (continue))))
@end example

A typical example of @var{walker} is @code{for-each}, which takes
a list and applies the procedure to each element of the list.
If we pass @code{for-each} to @code{inv}, we get a procedure
that is inverted @emph{inside-out}.  What does that mean?
See the following session:

@example
gosh> (define inv-for-each (inv for-each))
inv-for-each
gosh> (define iter (inv-for-each '(1 2 3)))
iter
gosh> (iter)
1
gosh> (iter)
2
gosh> (iter)
3
gosh> (iter)
#<eof>
@end example

When you pass a list to @code{inv-for-each}, you get an iterator
that returns each element in the list for each call.  That's because every
time @code{iter} is called, @code{shift} in @code{inv}
stashes away the task of @emph{walking the rest of the collection}
and set it to @code{continue}, then returns the current element @var{e}.

@var{walker} doesn't need to work just on list.  The following
function @code{for-each-leaf} traverses a tree and
apply @var{f} on each non-pair element.

@example
(define (for-each-leaf f tree)
  (match tree
   [(x . y) (for-each-leaf f x) (for-each-leaf f y)]
   [x (f x)]))
@end example

And you can inverse it just like @code{for-each}.

@example
gosh> (define iter2 ((inv for-each-leaf) '((1 . 2) . (3 . 4))))
iter2
gosh> (iter2)
1
gosh> (iter2)
2
gosh> (iter2)
3
gosh> (iter2)
4
gosh> (iter2)
#<eof>
@end example

The @code{util.combinations} module (@pxref{Combination library})
provides a procedure that @emph{calls} a given procedure with
every permutation of the given collection.  If you pass
it to @code{inv}, you get a procedure that @emph{returns}
every permutation each time.

@example
gosh> (define next ((inv permutations-for-each) '(a b c)))
next
gosh> (next)
(a b c)
gosh> (next)
(a c b)
gosh> (next)
(b a c)
gosh> (next)
(b c a)
gosh> (next)
(c a b)
gosh> (next)
(c b a)
gosh> (next)
#<eof>
@end example



@c ----------------------------------------------------------------------
@node High-level process interface, Record types, Partial continuations, Library modules - Gauche extensions
@section @code{gauche.process} - High-level process interface
@c NODE 高レベルプロセスインタフェース, @code{gauche.process} - 高レベルプロセスインタフェース

@deftp {Module} gauche.process
@mdindex gauche.process
This module provides a higher-level API of process control,
implemented on top of low-level system calls.
This module also provides ``process ports'',
a convenient way to send/receive information to/from subprocesses.
@end deftp

@menu
* Running subprocess::
* Running process pipeline::
* Process object::
* Process ports::
* Process connection::
@end menu

@node Running subprocess, Running process pipeline, High-level process interface, High-level process interface
@subsection Running subprocess
@c NODE サブプロセスの実行

@defun do-process cmd/args :key redirects input output error @
                   fork directory host sigmask on-abnormal-exit
@defunx do-process! cmd/args :key redirects input output error @
                    fork directory host sigmask
@defunx run-process cmd/args :key redirects input output error @
                   fork directory host sigmask wait
@{@t{gauche.process}@}
Runs a command with arguments given to @var{cmd/args} in a subprocess.
The @var{cmd/args} argument must be a list, whose car specifies
the command name and whose cdr is the command-line arguments.

If the command name contains a slash, it is taken as the
pathname of the executable.  Otherwise the named command
is searched from the directories in the @code{PATH} environment variable.

Each element in @var{cmd/args} are converted to a string
by @code{x->string}, for the convenience.

@code{Do-process} always waits the subprocess to terminate, and
returns @code{#t} if it exits successfully (i.e. with zero exit status).
If the subprocess terminates abnormally, it returns @code{#f} by default,
or raise an error if @code{:error} is passed to the keyword argument
@code{on-abnormal-exit}.

@code{Do-process!} is like @code{do-process} except that
it raises @code{<process-abnormal-exit>} error when the process
exists with non-zero status.  It's the same behavior as
giving @code{:error} to the @code{on-abnormal-exit} keyword argument
of @code{do-process}.  It is often more convenient to let the commands
fail in shell-script type tasks.

@code{Run-process} can run the subprocess concurrently by default,
that is, it returns immediately.  The return value is a @code{<process>}
object, which can be used to track the status of the subprocess
(@pxref{Process object}). 

For example, the following expression runs @code{ls -al}.

@example
(do-process '(ls -al))
@end example

You see the output of @code{ls -al}, then it returns @code{#t},
unless the execution of @code{ls} command fails with some reason.

Since @code{do-process} returns the success or failure of the command
by a boolean value, you can use @code{and} and @code{or} to combine
commands pretty much the same way as shell's @code{&&} and @code{||}
operators.

@example
;; shell: make && make -s check
(and (do-process '(make))
     (do-process '(make -s check)))

;; shell: mv x.tmp x.c || rm -f x.tmp
(or (do-process '(mv x.tmp x.c))
    (do-process '(rm -f x.tmp)))
@end example

If you use @code{run-process} instead, you'll get @code{<process>} object
without waiting @code{ls -al} to finish.  If you run the following expression
on REPL, you'll likely to see the return value before output of @code{ls}.

@example
(run-process '(ls -al))
@end example

You can keep the returned @code{<process>} object
and call @code{process-wait} on it to wait for its termination.
@xref{Process object}, for the details of @code{process-wait}.

@example
(let1 p (run-process '(ls -al))
  ... do some other work ...
  (process-wait p))
@end example

You can tell @code{run-process} to wait for the subprocess to exit; in
that case, @code{run-process} calls @code{process-wait} internally.
It is useful if you want to examine the exit status of the subprocess,
rather than just caring its success/failure as @code{do-process} does.

Note that @code{-i} is read as an imaginary number,
so be careful to pass @code{-i} as a command-line
argument; you should use a string, or write @code{|-i|} to make it
a symbol.

@example
(run-process '(ls "-i"))
@end example

Note: An alternative way to run external process is @code{sys-system},
which takes a command line as a single string (@pxref{Process management}).
The string is passed to the shell to be interpreted,
so you can include redirections, or can pipe several commands.
It would be handy for quick throwaway scripts.

On the other hand, with @code{sys-system}, 
if you want to change command parameters
at runtime, you need to worry about properly escape them
(actually we have one to do the job in @code{gauche.process}; 
see @code{shell-escape-string}
below); you need to be aware that @code{/bin/sh}, used by 
@code{sys-system} via @code{system(3)} call, may differ among
platforms and be careful not to rely on specific features on
certain systems.  As a rule of thumb, keep @code{sys-system} for
really simple tasks with a constant command line,
and use @code{run-process} and @code{do-process}
for all other stuff.

Note: Old version of this procedure took arguments differently,
like @code{(run-process "ls" "-al" :wait #t)}, which was compatible
to STk.  This is still supported but deprecated.

Large number of keyword arguments can be passed to 
@code{do-process} and
@code{run-process}
to control execution of the child process.  We describe them by
categories.
@end defun


@subsubheading Synchronization

@deftp {Subprocess argument} wait @var{flag}
This can only be given to @code{run-process}.
If @var{flag} is true, @code{run-process} waits until the
subprocess terminates, by calling @code{process-wait} internally.
Otherwise the subprocess runs asynchronously
and @code{run-process} returns immediately, which is the default behavior.

Note that if the subprocess is running asynchronously, it is the
caller's responsibility to call @code{process-wait} at a certain
timing to collect its exit status.

@example
;; This returns after wget terminates.
(define p (run-process '(wget http://practical-scheme.net/) :wait #t))

;; Check the exit status
(let1 st (process-exit-status p)
  (cond [(sys-wait-exited? st)
         (print "wget exited with status " (sys-wait-exit-status st))]
        [(sys-wait-signaled? st)
         (print "wget interrupted by signal " (sys-wait-termsig st))]
        [else
         (print "wget terminated with unknown status " st)]))
@end example
@end deftp

@deftp {Subprocess argument} on-abnormal-exit @var{how}
This can only be given to @code{do-process}.
If @var{how} is @code{#f}, which is the default,
@code{do-process} returns @code{#f} when
the subprocess exits abnormally (i.e. with nonzero exit status).
If @var{how} is @code{:error}, it raises an error in such a case.
@end deftp

@deftp {Subprocess argument} fork @var{flag}
If @var{flag} is true, @code{do-process} and
@code{run-process} forks to run
the subprocess, which is the default behavior.  If @var{flag} is
false, @code{do-process} and
@code{run-process} directly calls @code{sys-exec}, so
it never returns.
@end deftp

@subsubheading I/O redirection

@deftp {Subprocess argument} redirects (@var{iospec} @dots{})
Specifies how to redirect child process's I/Os.
Each @var{iospec}
can be one of the followings, where @var{fd}, @var{fd0}, and @var{fd1}
are nonnegative integers referring to the file descriptor
@emph{of the child process}.

(Note: If you just want to run a command and get its output as a string
take a look at @code{process-output->string} (@pxref{Process ports}).
If you want to pipe multiple commands together,
@pxref{Running process pipeline}.)

@table @code
@item (< @var{fd} @var{source})
@var{source} can be a string, a symbol, a keyword @code{:null},
an integer, or an input port.

If it is a string, it names a file opened for read
and the child process can reads the content of the file from @var{fd}.
An error is signaled if the file does not exist or cannot open for read.

If it is a symbol, an unidirectional pipe is created, whose reader end
is connected to the child's @var{fd}, and whose writer end is
available as an output port returned from
@code{(process-input @var{process} @var{source})}.

If it is @code{:null}, the child's @var{fd} is connected to the
null device.

If it is an integer, it should specify a parent's file descriptor
opened for read.  The child sees the duped file descriptor as @var{fd}.

If it is an input port, the underlying file descriptor is duped
into child's @var{fd}.  It is an error to pass an input port without
associated file descriptor (See @code{port-file-number} in
@ref{Common port operations}).

@item (<< @var{fd} @var{value})
@itemx (<<< @var{fd} @var{obj})
Feeds @var{value} or @var{obj} to the input file
descriptor @var{fd} of the child process.

With @code{<<}, @var{value} must be either a string or a uniform
vector (@pxref{Uniform vectors}).  It is sent to the child process as is.
Using a uniform vector is good to pass binary content.

With @code{<<<}, @var{obj} can be any Scheme object, and
the result of @code{(write-to-string obj)} is sent to the child process.

@item (<& @var{fd0} @var{fd1})
Makes child process's file descriptor @var{fd0} refer to the same input
as its file descriptor @var{fd1}.  Note the difference from @code{<};
@code{(< 3 0)} makes the parent's stdin (file descriptor 0) be read
by the child's file descriptor 3, while  @code{(<& 3 0)} makes
the child's file descriptor 3 refer to the same input as child's stdin
(which may be redirected to a file or something else by another @var{iospec}).

See the note below on the order of processing @code{<&}.

@item (> @var{fd} @var{sink})
@itemx (>> @var{fd} @var{sink})
@var{sink} must be either a string, a symbol, a keyword @code{:null},
an integer or a file output port.

If it is a string, it names a file.  The output of the child to
the file descriptor @var{fd} is written to the file.
If the named file already exists, @code{>} first truncates its
content, while @code{>>} appends to the existing content.

For other arguments, @code{>} and @code{>>} works the same.

If @var{sink} is a symbol, an unidirectional pipe is created
whose writer end is connected to the child's @var{fd}, and whose
reader end is available as an input port returned by
@code{(process-output @var{process} @var{sink})}.

If @var{sink} is @code{:null}, child's @var{fd} is connected
to the system's null device.

If @var{sink} is an integer, it must specify a parent's file
descriptor opened for output.  The child sees the duped file descriptor
as @var{fd}.

If @var{sink} is an output port, the underlying file descriptor is
duped into @var{fd} in the child process.

@item (>& @var{fd0} @var{fd1})
Makes child process's file descriptor @var{fd0} refer to the same output
as its file descriptor @var{fd1}.  Note the difference from @code{>};
@code{(> 2 1)} makes the child's stderr go to parent's stdout,
while  @code{(>& 2 1)} makes the child's stderr go to the same
output as child's stdout (which may be redirected by another @var{iospec}).

@example
;; Read both child's stdout and stderr
(let1 p (run-process '(command arg)
                     :redirects '((>& 2 1) (> 1 out)))
  (begin0 (port->string (process-output p 'out))
          (process-wait p)))
@end example

@end table

Note: You can't use the same name (symbol) more than once for
the pipe of source or sink.  For example, the following code
signals an error:
@example
(run-process '(command) :redirects '((> 1 out) (> 2 out))) ; error!
@end example
You can use @code{>&} to ``merge'' the output to one sink,
or @code{<&} to ``split'' the input from one source, instead:
@example
(run-process '(command) :redirects '((> 1 out) (>& 2 1)))
@end example
It is allowed to give the same file name more than once,
just like the Unix shell.  However, note that the file is
opened individually for each file descriptor, so simply 
writing to them may not produce desired result (for regular
files, most likely that one output would overwrite another).

Note: I/O redirections are processed @emph{at once}, unlike the way
unix shell does.  For example, both of the following expression
works the same way, that is, they redirect
both stdout and stderr to a file @file{out}.

@example
(run-process '(command arg) :redirects '((>& 2 1) (> 1 "out")))
(run-process '(command arg) :redirects '((> 1 "out") (>& 2 1)))
@end example

Most unix shells process redirections @emph{in order}, so the following
two command line works differently: The first one redirects child's
stderr to the @emph{current} stdout, which is the same as the parent's
stdout, then redirects child's stdout to a file @file{out}.  So the
error messages appear in the parent's stdout.  The second one first
redirects the child's stdout to a file @file{out}, so at the time
of processing @code{2>&1}, the child's stderr also goes to the file.

@example
$ command arg 2>&1 1>out
$ command arg 1>out 2>&1
@end example

You can say @code{do-process} and
@code{run-process} always works like the latter,
regardless of the order in @var{redirects} argument.

If you want to redirect child's stderr to parent's stdout,
you can use @code{>} like the following:

@example
(run-process '(command arg) :redirects '((> 2 1) (> 1 "out")))
@end example

@end deftp


@deftp {Subprocess argument} input @var{source}
@deftpx {Subprocess argument} output @var{sink}
@deftpx {Subprocess argument} error @var{sink}
Redirects child's standard i/o.
@var{source} and @var{sink} may be either a string, one
of keywords @code{:null}, @code{:pipe}, or @code{merge},
an integer file descriptor, or a symbol.

These are really shorthand notations of the @var{redirects} argument:

@example
:input x   @equiv{} :redirects '((< 0 x))
:output x  @equiv{} :redirects '((> 1 x))
:error x   @equiv{} :redirects '((> 2 x))
@end example

The keyword @code{:pipe} as @var{source} or @var{sink} is supported
just for the backward compatibility.  They work as if a symbol
@code{stdin}, @code{stdout} or @code{stderr} is given, respectively:

@example
:input :pipe   @equiv{} :redirects '((< 0 stdin))
:output :pipe  @equiv{} :redirects '((> 1 stdout))
:error :pipe   @equiv{} :redirects '((> 2 stderr))
@end example

That is, a pipe is created and its one end is connected to the
child process's stdio, and the other end is available
by calling @code{(process-input @var{process})},
@code{(process-output @var{process})} or @code{(process-error @var{process})}.
(That is because @code{process-input} and @code{process-output}
uses @code{stdin} and @code{stdout} respectively when @var{name} argument
is omitted, and @code{(process-error p)} is equivalent
to @code{(process-output p 'stderr)}.)

The keyword @code{:merge} can only be used for @code{:error} keyword
argument, and it is a shorthand notation of
@code{:redirects '((>& 2 1))}, that is, merge the child process's
stderr into child process's stdout.

See the description of @var{redirects} above for the meanings
of the argument values.
@end deftp


@subsubheading Execution environment

@deftp {Subprocess argument} directory @var{directory}
If a string is given to @var{directory},
the process starts with @var{directory} as its working directory.
If @var{directory} is @code{#f}, this argument is ignored.
An error is signaled if @var{directory} is other type of objects,
or it is a string but is not a name of a existing directory.

When @var{host} keyword argument is also given, this argument
specifies the working directory of the @emph{remote} process.

Note: @code{do-process} and
@code{run-process} check the validity of @var{directory},
but actual @code{chdir(2)} is done just before @code{exec(2)},
and it is possible that @code{chdir} fails in spite of previous
checks.  At the moment when @code{chdir} fails, there's no
reliable way to raise an exception to the caller,
so it writes out an error message to standard error port and exits.
A robust program may take this case into account.
@end deftp


@deftp {Subprocess argument} sigmask @var{mask}
@var{Mask} must be either an instance of @code{<sys-sigset>},
a list of integers, or
@code{#f}.  If an instance of @code{<sys-sigset>} is given, the
signal mask of executed process is set to it.   A list of integers
are treated as a list of signals to mask.  It is important
to set an appropriate mask if you call @code{run-process} from
multithreaded application.
See the description of @code{sys-exec} (@ref{Process management})
for the details.

If the @var{host} keyword argument is specified, this argument
merely sets the signal mask of the local process (@code{ssh}).
@end deftp

@deftp {Subprocess argument} detached @var{flag}
When a true value is given, the new process is detached from
the parent's process group and belongs to its own group.
It is useful when you run a daemon process.
See @code{sys-fork-and-exec} (@pxref{Process management}), for
the detailed description of @var{detached} argument.
@end deftp


@deftp {Subprocess argument} host @var{hostspec}
This argument is used to execute @var{command} on the remote host.
The full syntax of @var{hostspec} is @code{protocol:user@@hostname:port},
where @var{protocol:}, @var{user@@}, or @var{:port} part can be
omitted.

The @var{protocol} part specifies the protocol to communicate
with the remote host; currently only @code{ssh} is supported, and
it is also the default when @var{protocol} is omitted.
The @var{user} part specifies the login name of the remote host.
The @var{hostname} specifies the remote host name, and the
@var{port} part specifies the alternative port number which
@var{protocol} connects to.

The command line arguments are interpreted on the remote host.
On the other hand, the I/O redirection is done on the local end.
For example, the following code reads the file @file{/foo/bar} on
the remote machine and copies its content into the local file
@file{baz} in the current working directory.

@example
(do-process '(cat "bar")
            :host "remote-host.example.com"
            :directory "/foo"
            :output "baz")
@end example
@end deftp

@node Running process pipeline, Process object, Running subprocess, High-level process interface
@subsection Running process pipeline
@c NODE プロセスパイプラインの実行

@defun do-pipeline commands :key input output error directory sigmask on-abnormal-exit
@defunx run-pipeline commands :key input output error wait directory sigmask
@{@t{gauche.process}@}
Convenience routines to run pipeline of processes at once.
Example:

@example
(do-pipeline '((ls "src/")
               (grep "\\.c$")
               (wc -l)))
@end example

This is equivalent to shell command pipeline
@code{ls src/ | grep '\.c$' | wc -l}, i.e. shows the
number of C source files in the @file{src} subdirectory.

The @var{commands} argument is a list of lists.  Each list
must be @code{cmd/args} argument @code{do-process}/@code{run-process} can accept.
At least one command must be specified.

The specified commands will run concurrently, with the stdout of
the first command is connected to the stdin of the second, and
stdout of the second to the stdin of the third, and so on.
The stdin of the first command is fed from the source specified
by the @var{input} keyword argument, and the stdout of the last
command is sent to the sink specified by the @var{output} keyword
argument.  The default values of these are the calling process's
stdin and stdout, respectively.  See @code{do-process}/@code{run-process},
for the possible values of these arguments
(@pxref{Running subprocess}).

The stderr of all the processes are sent to the sink specified
by the @var{error} keyword argument, which is defaulted by the
calling process's stderr.

Like @code{do-process}, @code{do-pipeline} waits for completion of
all the processes, and returns @code{#t} if the tail process
succeeds (i.e. exits with zero status) or @code{#f} if the last process
fails (i.e. exits with non-zero status).   If you give
@code{:error} to @code{on-abnormal-exit} keyword arguments, however,
a failure of the tail process raises an error.
Exit statuses of subprocesses other than the tail one are
collected by @code{process-wait}, but won't affect the
return value, and won't cause an error even
@code{on-abnormal-exit} is @code{:error}.

On the other hand, @code{run-pipeline} returns a @code{<process>} object of
the tail process.  You can get other process objects in
the pipeline by applying @code{process-upstreams} to the tail process.
By default, @code{run-pipeline} runs all the subprocesses in background
and returns immediately.  Calling @code{process-wait} on the returned
process object will waits for all the subprocesses.
If you give a true value to @var{wait} keyword argument,
@code{run-process} waits for all the subprocesses to finish
before returning.

The @var{directory} and @var{sigmask} keyword arguments are applied
to all the processes; 
see @code{do-process}/@code{run-process} for the description
of these arguments
(@pxref{Running subprocess}).

Note: In Gauche 0.9.5, we introduced @code{run-process-pipeline}.  It is similar
to the current @code{run-pipeline} but returns a list of subprocess objects
instead of a single one.  We realized it's not very convenient, so we
deprecated @code{run-process-pipeline} and replaced it with @code{run-pipeline}.
We still support @code{run-process-pipeline}, but strongly recommend
to move to @code{run-pipeline} as soon as possible.
@end defun


@node Process object, Process ports, Running process pipeline, High-level process interface
@subsection Process object

@deftp {Class} <process>
@clindex process
@{@t{gauche.process}@}
An object to keep the status of a child process.  You can create
the process object by @code{run-process} procedure described below.
The process ports explained in the next section also use process objects.

The @code{<process>} class keeps track of
the child processes spawned by high-level APIs such
as @code{run-process} or @code{open-input-process-port}.
The exit status of such children must be collected by
@code{process-wait} or @code{process-wait-any} calls,
which also do some bookkeeping.   Using
the low-level process calls such as @code{sys-wait} or
@code{sys-waitpid} directly will cause inconsistent state.
@end deftp

@deftp {Class} <process-abnormal-exit>
@clindex process-abnormal-exit
@{@t{gauche.process}@}
A condition type mainly used by the process port utility procedures.
Inherits @code{<error>}.  This type of condition is thrown when
the high-level process port utilities detect the child process exited
with non-zero status code.

@defivar {<process-abnormal-exit>} process
A process object.
@end defivar

Note: In Unix terms, exiting a process by calling @code{exit(2)} or
returning from @code{main()} is a normal exit, regardless of the
exit status.  Some commands do use non-zero exit status
to tell one of the normal results of execution (such as @code{grep(1)}).
However, large number of commands uses non-zero exit status to
indicate that they couldn't carry out the required operation,
so we treat them as exceptional situations.
@end deftp


@defun process? obj
@{@t{gauche.process}@}
@equiv{} @code{(is-a? @var{obj} <process>)}
@end defun

@deffn {Method} process-pid (process <process>)
@{@t{gauche.process}@}
Returns the process ID of the subprocess @var{process}.
@end deffn

@deffn {Method} process-command (process <process>)
@{@t{gauche.process}@}
Returns the command invoked in the subprocess @var{process}.
@end deffn

@deffn {Method} process-input (process <process>) :optional name
@deffnx {Method} process-output (process <process>) :optional name
@{@t{gauche.process}@}
Retrieves one end of a pipe, whose another end is connected
to the process's input or output, respectively.
@var{name} is a symbol given to the @var{redirects} argument
of @code{run-process} to distinguish the pipe.  See the following
example:

@example
(let1 p (run-process '(command arg)
                     :redirects '((< 3 aux-in)
                                  (> 4 aux-out)))
  (let ([auxin  (process-input p 'aux-in)]
        [auxout (process-output p 'aux-out)])
    ;; feed something to the child's input
    (display 'something auxin)
    ;; read data from the child's output
    (read-line auxout)
    @dots{}
    )
  (process-wait p))
@end example

The symbols @code{aux-in} and @code{aux-out} is used to
identify the pipes.  Note that @code{process-input} returns
@emph{output} port, and @code{process-output} returns
@emph{input} port.

When @var{name} is omitted, @code{stdin} is used for @code{process-input}
and @code{stdout} is used for @code{process-output}.  These are
the names used if child's stdin and stdout are redirected by
@code{:input :pipe} and @code{:output :pipe} arguments, respectively.

If there's no pipe with the given name, @code{#f} is returned.

@example
(let* ((process (run-process '("date") :output :pipe))
       (line (read-line (process-output process))))
  (process-wait process)
  line)
 @result{} "Fri Jun 22 22:22:22 HST 2001"
@end example

If @var{process} is a result of @code{run-pipeline},
@code{(process-input process)} and @code{(process-input process 'stdin)}
behave slightly differently---they return the pipe connected to the
stdin of the @emph{head} process of the pipeline, not the
process represented by @var{process} (which is the tail of the pipeline).
This allows you to treat the whole pipeline as one entity.

@example
(let1 p (run-pipeline `((cat)
                        (grep "aba"))
                       :input :pipe :output :pipe)
  (display "banana\nhabana\ntabata\ncabara\n"
           (process-input p))    ; head of the pipeline
  (close-port (process-input p))
  (process-wait p)
  (port->string (process-output p)))
  @result{} "habana\ntabata\ncabara\n"
@end example
@end deffn

@deffn {Method} process-error (process <process>)
@{@t{gauche.process}@}
This is equivalent to @code{(process-output @var{process} 'stderr)}.
@end deffn

@defun process-alive? process
@{@t{gauche.process}@}
Returns true if @var{process} is alive.  Note that Gauche can't
know the subprocess' status until it is explicitly checked by
@code{process-wait}.
@end defun

@defun process-upstreams process
@{@t{gauche.process}@}
If @var{process} is the result of @code{run-pipeline}, this returns
a list of processes that are upstream of @var{process} in the pipeline.
If @var{process} is not the result of @code{run-pipeline}, this returns
an empty list.

@example
(define p (run-pipeline `((cat) (grep "ho") (wc)) :input :pipe))

p @result{} #<process 20658 "wc" active>

(process-upstreams p)
  @result{} (#<process 20656 "cat" active> #<process 20657 "grep" active>)
@end example
@end defun

@defun process-list
@{@t{gauche.process}@}
Returns a list of active processes.  The process remains active
until its exit status is explicitly collected by @code{process-wait}.
Once the process's exit status is collected and its state changed
to inactive, it is removed from the list @code{process-list} returns.
@end defun

@defun process-wait process :optional nohang error-on-nonzero-status
@{@t{gauche.process}@}
Obtains the exit status of the subprocess @var{process}, and stores it
to @var{process}'s status slot.  The status can be obtained by
@code{process-exit-status}.

This suspends execution until @var{process} exits by default.
However, if a true value is given to the optional argument @var{nohang},
it returns immediately if @var{process} hasn't exit.

If a true value is given to the optional argument
@var{error-on-nonzero-status}, and the obtained status code is not zero,
this procedure raises @code{<process-abnormal-exit>} error.

Returns @code{#t} if this call actually obtains the exit status,
or @code{#f} otherwise.

If the process object is created by @code{run-pipeline}
(@pxref{Running process pipeline}), @code{process-wait} waits
@emph{all} of the subprocesses in the pipeline, not just the last one,
unless true value is given to the @var{nohang} argument.
However, @var{error-on-nonzero-status} only affects to the status
of @var{process}, which represents the last process in the pipeline;
if an other subprocess exits with nonzero status, it is stored in
its respective process objects, but won't cause a fuss.

If you specify a true value to @var{nohang} for the pipelined
process, @code{process-wait} still
probes other subprocesses in the pipeline and updates exit statuses
of terminated ones, but doesn't wait unterminated subprocesses.
The unterminated subprocesses should be waited individually, or
by @code{process-wait-any}, to collect their exit statuses.
@end defun

@defun process-wait-any :optional nohang
@{@t{gauche.process}@}
Obtains the exit status of any of the subprocesses created by
@code{run-process}.
Returns a process object whose exit status is collected.

If a true value is given to the optional argument @var{nohang}, this procedure
returns @code{#f }immediately even if no child process has exit.
If @var{nohang} is omitted or
@code{#f}, this procedure waits for any of children exits.

If there's no child processes, this procedure immediately returns @code{#f}.
@end defun

@defun process-wait/poll process :key interval max-wait continue-test raise-error?
@{@t{gauche.process}@}
Polls wait status of @var{process} periodically, sleeping 
@var{interval} nanoseconds (default 2e6 ns, i.e. 2ms) between each poll.
It returns as soon as it finds the process has exitted and its status is 
retrieved.

If @var{max-wait} is given and not @code{#f}, it species maximum duration
in nanoseconds to keep polling.  Once the duration expires, the procedure
gives up and return.  If it is not given or @code{#f},
the procedure keeps polling until the process exits.

The @var{continue-test}, if given and not @code{#f}, must be a procedure
that takes one argument, poll count.  It is called after each unsuccessul
polling (that is, the process hasn't been exitted), and the argument begins
with 0 and incretemented for each callback.  The procedure can return
@code{#f} to give up polling.  When it returns a true value, polling continues.

The @var{raise-error?} argument is the same as @code{process-wait}; an
error is raised if @var{process}'s exit status isn't zero.

The procedure returns @code{#t} if the process exitted, and @code{#f} if
it has given up.  The process's exit status should be retrieved
with @code{process-exit-status} from @var{process}.
@end defun


@defun process-exit-status process
@{@t{gauche.process}@}
Returns exit status of @var{process} retrieved by @code{process-wait}.
If this is called before @code{process-wait} is called on @var{process},
the result is undefined.

The meaning of exit status depends on the platform.  You need to
use @code{sys-wait-exited?} or @code{sys-wait-signaled?} to
see if it is terminated voluntarily or by a signal, and
use @code{sys-wait-exit-status} or @code{sys-wait-termsig}
to extract the exit code or the terminating signal
(@pxref{Process management}).
@end defun

@defun process-send-signal process signal
@{@t{gauche.process}@}
Sends a signal @var{signal} to the subprocess @var{process}.
@var{signal} must be an exact integer for signal number.
@xref{Signal}, for predefined variables of signals.
@end defun

@defun process-kill process
@defunx process-stop process
@defunx process-continue process
@{@t{gauche.process}@}
Sends SIGKILL, SIGSTOP and SIGCONT to @var{process}, respectively.
@end defun

@defun process-shutdown process :key ask ask-interval ask-retry signals signal-interval
Tries to terminate @var{process} in the gradually escalating means.

The @var{ask} argument is, if not @code{#f}, a procedure taking one argument,
the retry count.  The @var{ask} procedure is responsible to interact with
@var{process} in a proper protocol (e.g. send @code{exit} command via
comminucation channel).  After @var{ask} is executed (the return value
is ignored), the process's status is monitored, and 
@code{process-shutdown} returns @code{#t} as soon as the
process exits.  If the process doesn't exit, the procedure repeats
calling @var{ask} up to @var{retry} times, with @var{ask-interval} nanoseconds
delay inbetween, incrementing the retry count
argument.   If @var{ask} argument is @code{#f}, this step is skipped.
The default value of @var{ask} is @code{#f}, @var{ask-interval} is
50e6 ns (50ms), and @var{ask-retry} is 1.

If the first step fails, this procedure starts sending signals.
The process's status is checked every time after a signal is sent.
As soon as the process exists, @code{process-shutdown}
returns @code{#t}.
The sequence of signals is specified by @var{signals} argument,
and the interval of sending signals is specified by @var{signal-interval}
argument.  The default value of @var{signals} is
@code{(list SIGTERM SIGTERM SIGKILL)}, and @var{singal-interval} is
50e6 ns (50ms).

If all the measures fail, @code{#f} is returned.

(Hint: If you wants to keep sending signals until the process really
exits, you can pass a circular list to the @var{signals}.)
@end defun

@node Process ports, Process connection, Process object, High-level process interface
@subsection Process ports

@defun open-input-process-port command :key input error encoding conversion-buffer-size
@{@t{gauche.process}@}
Runs @var{command} asynchronously in a subprocess.  Returns
two values, an input port which is connected to the stdout of the
running subprocess, and a process object.

@var{Command} can be a string, a list of command name and arguments,
or a list of lists of command name and arguments.

If it is a string, it is passed to @code{/bin/sh}.
You can use shell metacharacters in this form, such as
environment variable interpolation, globbing, and redirections.
If you create the command line by concatenating strings,
it's your responsibility to ensure escaping special characters
if you don't want the shell to interpret them.
The @code{shell-escape-string} function described below might
be a help.

If @var{command} is a list (but not a list of lists),
each element is converted to a
string by @code{x->string} and then passed directly to @code{sys-exec}
(the @code{car} of the list is used as both the command path
and the first element of argv, i.e. @code{argv[0]}).
Use this form if you want to avoid the shell from interfering;
i.e. you don't need to escape special characters.

The subprocess's stdin is redirected from @code{/dev/null},
and its stderr shares the calling process's stderr by default.
You can change these by giving file pathnames to @var{input} and
@var{error} keyword arguments, respectively.

If @var{command} is a list of lists, it creates a command pipeline,
as in @code{run-pipeline} (@pxref{Running process pipeline}).
Each inner list should consists of a command path, followed by command-line
arguments.  They are applied on @code{x->string} before passed to
@code{sys-exec}.
The stdout of the last command is available from the returned input port,
and the stdin of the first command is provided by @var{input} keyword
arguments, or @code{/dev/null} by default.  The stderr of all the commands
goes to @var{error} keyword arguments if given, or shared with
the caller process's stderr.

You can also give the @var{encoding} keyword argument
to specify character encoding of the process output.  If it differs
from the Gauche's internal encoding format,
@code{open-input-process-port} inserts a character encoding
conversion port.
If @var{encoding} is given, the @var{conversion-buffer-size} keyword
argument can control the conversion buffer size.
See @ref{Character code conversion}, for
the details of character encoding conversions.
@example
(receive (port process) (open-input-process-port "ls -l Makefile")
  (begin0 (read-line port)
          (process-wait process)))
 @result{} "-rw-r--r--   1 shiro    users        1013 Jun 22 21:09 Makefile"

(receive (port process) (open-input-process-port '(ls -l "Makefile"))
  (begin0 (read-line port)
          (process-wait process)))
 @result{} "-rw-r--r--   1 shiro    users        1013 Jun 22 21:09 Makefile"

(open-input-process-port "command 2>&1")
 @result{} ;@r{the port reads both stdout and stderr}

(open-input-process-port "command 2>&1 1>/dev/null")
 @result{} ;@r{the port reads stderr}
@end example
The exit status of subprocess is not automatically collected.
It is the caller's responsibility to issue @code{process-wait},
or the subprocess remains in a zombie state.  If it bothers you,
you can use one of the following functions.
@end defun

@defun call-with-input-process command proc :key input error encoding conversion-buffer-size on-abnormal-exit
@{@t{gauche.process}@}
Runs @var{command} in a subprocess and pipes its stdout
to an input port, then call @var{proc} with the port as an argument.
When @var{proc} returns, it collects its exit status,
then returns the result @var{proc} returned.
The cleanup is done even if @var{proc} raises an error.

The keyword argument @var{on-abnormal-exit} specifies what happens
when the child process exits with non-zero status code.
It can be either @code{:error} (default), @code{:ignore}, or
a procedure that takes one argument.  If it is @code{:error},
a @code{<process-abnormal-exit>} error condition is thrown by
non-zero exit status; the @code{process} slot of the condition
holds the process object.  If it is @code{:ignore}, nothing is done
for non-zero exit status.  If it is a procedure, it is called with
a process object; when the procedure returns, @code{call-with-input-process}
returns normally.

The semantics of @var{command} and other keyword arguments are the same
as @code{open-input-process-port} above.
@example
(call-with-input-process "ls -l *"
  (lambda (p) (read-line p)))
@end example
@end defun

@defun with-input-from-process command thunk :key input error encoding conversion-buffer-size on-abnormal-exit
@{@t{gauche.process}@}
Runs @var{command} in a subprocess, and calls @var{thunk}
with its current input port connected to the command's stdout.
The command is terminated and its exit status is collected,
after @var{thunk} returns or raises an error.

The semantics of @var{command} and keyword arguments are the same
as @code{call-with-input-process} above.
@example
(with-input-from-process "ls -l *" read-line)
@end example
@end defun

@defun open-output-process-port command :key output error encoding conversion-buffer-size
@{@t{gauche.process}@}
Runs @code{command} in a subprocess asynchronously.  Returns two values,
an output port which is connected to the stdin of the subprocess.
and the process object.

The semantics of @var{command} is the same as
@code{open-input-process-port}.  The semantics of
@var{encoding} and @var{conversion-buffer-size} are also the same.

The subprocess's stdout is redirected to @code{/dev/null} by default,
and its stderr shares the calling process's stderr.
You can change these by giving file pathnames to @var{output} and
@var{error} keyword arguments, respectively.

The exit status of the subprocess is not automatically collected.
The caller should call @code{process-wait} on the subprocess
at appropriate time.
@end defun

@defun call-with-output-process command proc :key output error encoding conversion-buffer-size on-abnormal-exit
@{@t{gauche.process}@}
Runs @code{command} in a subprocess, and calls @var{proc}
with an output port which is connected to the stdin of the command.
The exit status of the command is collected after either @var{proc}
returns or raises an error.

The semantics of keyword arguments are the same as
@code{open-output-process-port}, except @var{on-abnormal-exit},
which is the same as described in @code{call-with-input-process}.
@example
(call-with-output-process "/usr/sbin/sendmail"
  (lambda (out) (display mail-body out)))
@end example
@end defun

@defun with-output-to-process command thunk :key output error encoding conversion-buffer-size on-abnormal-exit
@{@t{gauche.process}@}
Same as @code{call-with-output-process}, except that the
output port which is connected to the stdin of the command
is set to the current output port while executing @var{thunk}.
@end defun

@defun call-with-process-io command proc :key error encoding conversion-buffer-size on-abnormal-exit
@{@t{gauche.process}@}
Runs @var{command} in a subprocess, and calls @var{proc}
with two arguments; the first argument is an input port which
is connected to the command's stdout, and the second is an output
port connected to the command's stdin.  The error output from
the command is shared by the calling process's, unless
an alternative pathname is given to the @var{error} keyword argument.

The exit status of the command is collected when @var{proc}
returns or raises an error.
@end defun

@defun process-output->string command :key error encoding conversion-buffer-size on-abnormal-exit
@defunx process-output->string-list command :key error encoding conversion-buffer-size on-abnormal-exit
@{@t{gauche.process}@}
Runs @var{command} and collects its output (to stdout) and returns them.
@code{process-output->string} concatenates all the output from @var{command}
to one string, replacing any sequence of whitespace characters to
single space.   The action is similar to ``command substitution''
in shell scripts.
@code{process-output->string-list} collects the output from
@var{command} line-by-line and returns the list of them.  Newline
characters are stripped.

Internally, @var{command} is run by @code{call-with-input-process},
to which keyword arguments are passed.

(Tip: To receive stderr output of the child process in the result as well,
pass @code{:merge} to @code{:error}.  See @code{run-process} above
for the details.)
@example
(process-output->string '(uname -smp))
  @result{} "Linux i686 unknown"

(process-output->string '(ls))
  @result{} "a.out foo.c foo.c~ foo.o"

(process-output->string-list '(ls))
  @result{} ("a.out" "foo.c" "foo.c~" "foo.o")
@end example

@end defun

@defun shell-escape-string str :optional flavor
@{@t{gauche.process}@}
If @var{str} contains characters that affects shell's command-line
argument parsing, escape @var{str} to avoid shell's interpretation.
Otherwise, returns @var{str} itself.

The optional @var{flavor} argument takes a symbol to
specify the platform; currently @code{windows} and
@code{posix} can be specified.  The way shell handles
the escape and quotation differ a lot between these platforms;
the @code{windows} flavor uses MSVC runtime argument parsing behavior,
while the @code{posix} flavor assumes IEEE Std 1003.1.
When omitted, the default
value is chosen according to the running platform.
(Note: Cygwin is regarded as @code{posix}.)

Use this procedure when you need to build a command-line string by yourself.
(If you pass a command-line argument list, instead of a single
command-line string, you don't need to escape them since we
bypass the shell.)
@end defun

@defun shell-tokenize-string str :optional flavor
@{@t{gauche.process}@}
Split a string @var{str} into arguments as the shell does.

@example
(shell-tokenize-string "grep -n -e \"foo bar\" log")
 @result{} ("grep" "-n" "-e" "foo bar" "log")
@end example

The optional @var{flavor} arguments can be a symbol either 
@code{windows} or @code{posix} to specify the syntax.
If it's @code{windows}, we follow MSVC runtime command-line
argument parser behavior.  If it's @code{posix}, we follow
IEEE Std 1003.1 Shell Command Language.  When omitted,
the default value is chosen according to the running platform.
(Note: Cygwin is regarded as @code{posix}.)

This procedure does not handle fancier shell features such
as variable substitution.  If it encounters a metacharacter
that requires such interpretation, an error is signaled.
In other words, metacharacters must be properly quoted
in @var{str}.

@example
(shell-tokenize-string "echo $foo" 'posix)
  @result{} @r{signals error}

(shell-tokenize-string "echo \"$foo\"" 'posix)
  @result{} @r{still signals error}

(shell-tokenize-string "echo '$foo'" 'posix)
  @result{} ("echo" "$foo")

(shell-tokenize-string "echo \\$foo" 'posix)
  @result{} ("echo" "$foo")
@end example
@end defun

@node Process connection,  , Process ports, High-level process interface
@subsection Process connection

@deftp {Class} <process-connection>
A connection abstraction to communicate with an external processs.
Inherits @code{<connection>}.
@xref{Connection framework}, for the details of the connection interface.

This is useful to give an external process to the code that expects
connection.  For example, instead of direct network connection, you can
insert a filter process between remote server and your client code.
@end deftp

@defun make-process-connection process-or-spec
Run an external process and returns a connection that's connected
to standard I/O of the process.

You can pass a list of command and its arguments, or
a @var{<process>} object, to the @var{process-or-spec} argument.
If you it's a @code{<process>} object, it's stdin and stdout
is connected to pipes.  If it is a list, it is passed to @code{run-process}
to run a new process.

Shutting down both channels of the connection terminates the process.
Most processes that reads from stdin would exits after it reads EOF
from input, so we just poll the process exit status for a short period of time.
If the process doesn't exit, we send signals (first SIGTERM, then SIGKILL)
to ensure the termination of the process.

Merely closing the connection doesn't terminate the process, so that
the forked process can keep talking to the process.
@end defun


@c ----------------------------------------------------------------------
@node Record types, Reloading modules, High-level process interface, Library modules - Gauche extensions
@section @code{gauche.record} - Record types
@c NODE レコード型, @code{gauche.record} - レコード型

@deftp {Module} gauche.record
@mdindex gauche.record
This module provides a facility to define @emph{record types},
user-defined aggregate types.
The API is upper compatible to SRFI-9 (Defining Record Types) and
SRFI-99 (ERR5RS Records).
@end deftp

Record types are implemented as Gauche's classes,
but have different characteristics from the general classes.
@xref{Record types introduction}, for when you want to
use record types.

The record API consists of three layers, following
SRFI-99 and R6RS design.

The syntactic layer is the @code{define-record-type} macro
that conveniently defines a record type and related procedures
(a constructor, a predicate, accessors and modifiers) all at once
declaratively.   Knowing this macro alone is sufficient for
most common usage of records.

The inspection layer defines common procedures
to query information to the records and record types.

The procedural layer is a low-level machinery to implement
the syntactic layer; you don't usually need to use them
in day-to-day programming, but they might be handy to
create record types on-the-fly at runtime.

@menu
* Record types introduction::
* Record types syntactic layer::
* Record types inspection layer::
* Record types procedural layer::
* Pseudo record types::
@end menu

@node Record types introduction, Record types syntactic layer, Record types, Record types
@subsection Introduction

Gauche provides a general way for users to define new types as new
classes, using object system (@pxref{Object system}), and indeed
record types are implemented as Gauche's classes.
However, using record types instead of classes has several advantages.

@itemize
@item
It is portable.  The API conforms two major record SRFIs,
SRFI-9 and SRFI-99, so the code using record types can run on
various Scheme systems.
@item
It is efficient.  Record types are less flexibile than classes,
but that allows Gauche to optimize more.  Hence creating records and
accessing/modifying them are much faster than creating instances
of general classes and accessing/modifying them.  It makes record
types preferable choice when you only need a mechanism to bundle
several related values to carry around, and don't need fancier
mechanisms such as class redefinitions.
@item
As Gauche's extension, you can define pseudo record types,
which interprets ordinary aggregate types such as vectors and lists
as records.  (For Common Lisp users; it is like the @code{:type}
option of @code{defstruct}).
This helps flexibility of interface.  For example, you can ask
your library's users to pass a point in a vector of three numbers,
instead of asking users to pack their point data into your
custom point record type.  Yet inside your library you can
treat the passed data as if it is your point record type.
See @ref{Pseudo record types}, for more details.
@end itemize

The disadvantage of record types is that
they don't obey Gauche's class redefinition
protocol (@pxref{Class redefinition}).
That is, if you redefine a record with the same name,
it creates a new record type unrelated to the old one.
The record instances created from the old definition
won't be updated according to the new definition.

More importantly, record constructors, accessors and modifiers
are tend to be inlined where they are used, to achieve
better performance.   Since they are inlined, the code
that uses those procedures are not affected when
the record type is redefined.
This means if you redefine a record type, you have to
reload (recompile) the sources that uses any of
record constructors, accessors or modifiers.


@node Record types syntactic layer, Record types inspection layer, Record types introduction, Record types
@subsection Syntactic Layer


@defmac define-record-type type-spec ctor-spec pred-spec field-spec @dots{}
[R7RS base][SRFI-9][SRFI-99+]
@{@t{gauche.record}@}
Defines a record type, and optionally defines
a constructor, a predicate, and field accessors and modifiers.

The @var{type-spec} argument names the record type,
and optionally specifies the supertype (@var{parent}).

@example
@var{type-spec} : @var{type-name}
                | (@var{type-name} @var{parent} @var{option} @dots{})

@var{type-name} : @r{identifier}
@var{parent} : @r{expression}
@var{option} @dots{} : @r{keyword-value list}
@end example

The @var{type-name} identifier will be bound to a
@emph{record type descriptor}, or rtd,
which can be used for introspection and reflection.
See @ref{Record types inspection layer} and @ref{Record types procedural layer}
for possible operations for record types.
In Gauche, a record type descriptor is a @code{<class>} with a metaclass
@code{<record-meta>}.

The @var{parent} expression should evaluate to a record type descriptor.
If given, the defined record type inherits it; that is, all the
slots defined in the parent type are available to the @var{type-name}
as well, and the instance of @var{type-name} answers @code{#t} to the
predicate of the parent type.

Since a record type is also a class, parent type is also a superclass
of the defined record type.  However, record types are limited to
have single implementation inheritance.  The parent type must be
a subclass of @code{<record>}.  (You can have abstract classes along
the main inheritance, though.  See @var{mixins} below.)

You can give a pseudo record base type as @var{parent} to define a
pseudo record type, which allows you to access ordinary aggregates
like vectors as records.  See @ref{Pseudo record types} for more details.

the @var{option} @dots{} part is Gauche's extension.  It must be a
keyword-value list.  The following keywords are recognized:

@table @asis
@item @code{:mixins} (@var{class} @dots{})
Specifies auxiliary superclasses.  The classes must be abstract, that is,
must not have slots.  It is to implement protocols in the record type,
e.g. @code{<sequence>} (@pxref{Sequence framework}).
@item @code{:metaclass} @var{metaclass}
Specifies alternative metaclass.  By default, metaclass of record types
is @code{<record-meta>}.  If you specify an alternative metaclass,
it must be a subclass of @code{<record-meta>}.
@end table

The @var{ctor-spec} defines the constructor of the record instance.

@example
@var{ctor-spec} : #f | #t | @var{ctor-name}
          | (@var{ctor-name} @var{field-name} @dots{})

@var{ctor-name} : @r{identifier}
@var{field-name} : @r{identifier}
@end example

If it is @code{#f}, no constructor is created.
If it is @code{#t}, a default constructor is created with a name
@code{make-@var{type-name}}.  If it is a single identifier
@var{ctor-name}, a default constructor is created with the name.
The default constructor takes as many arguments as
the number of fields of the record, including inherited ones if any.
When called, it allocates an instance of the record, and initialize its
fields with the given arguments in the order (inherited fields comes
first), and returns the record.

The last variation of @var{ctor-spec} creates a custom
constructor with the name @var{ctor-name}.  The custom constructor
takes as many arguments as the given @var{field-name}s, and initializes
the named fields.  If the inherited record type has a field of the same name
as the ancestor record type, only the inherited ones are initialized.
In Gauche, uninitialized fields remains unbound until some value is
set to it.

The @var{pred-spec} defines the predicate of the record instance,
which takes one argument and returns @code{#t} iff it is an instance
of the defined record type or its descendants.

@example
@var{pred-spec} : #f | #t | @var{pred-name}

@var{pred-name} : @r{identifier}
@end example

If it is @code{#f}, no predicate is created.
If it is @code{#t}, a predicate is created with a name
@code{@var{type-name}?}.  If it is a single identifier,
a predicate is created with the given name.

The rest of the arguments specify fields (slots) of the record.

@example
@var{field-spec}
 : @var{field-name}   ; @r{immutable, with default accessor}
 | (@var{field-name}) ; @r{mutable, with default accessor/modifier}
 | (@var{field-name} @var{accessor-name}); @r{immutable}
 | (@var{field-name} @var{accessor-name} @var{modifier-name}); @r{mutable}

@var{field-name}    : @r{identifier}
@var{accessor-name} : @r{identifier}
@var{modifier-name} : @r{identifier}
@end example

The first and the third forms define immutable fields, which can only
be initialized by the constructor but cannot be modified afterwards
(thus such fields don't have modifiers).
The second and the fourth forms define mutable fields.

The third and fourth forms explicitly name the accessor and modifier.
With the first and second forms, on the other hand,
the accessor is named as
@code{@var{type-name}-@var{field-name}}, and the modifier is named
as @code{@var{type-name}-@var{field-name}-set!}.
@end defmac

Let's see some examples.  Here's a definition of a record
type @code{point}.

@example
(define-record-type point #t #t
  x y z)
@end example

The variable @code{point} is bound to a record type descriptor,
which is just a class.  But you can take its class and see it is
indeed an instance of @code{<record-meta>} metaclass.

@example
point            @result{} #<class point>
(class-of point) @result{} #<class <record-meta>>
@end example

You can create an instance of @code{point} by the default
constructor @code{make-point}.  The predicate is given the
default name @code{point?}, and you can access the fields
of the created record by @code{point-x} etc.

@example
(define p (make-point 1 2 3))

(point? p)  @result{} #t
(point-x p) @result{} 1
(point-y p) @result{} 2
(point-z p) @result{} 3
@end example

Since we defined all fields immutable, we cannot modify
the instance @code{p}.

Here's a mutable version of point, @code{mpoint}.
You can modify its fields by modifier procedures and
generalized @code{set!}.

@example
(define-record-type mpoint #t #t
  (x) (y) (z))

(define p2 (make-mpoint 1 2 3)) ; @r{create an instance}

(mpoint-x p2)  @result{} 1

(mpoint-x-set! p2 4)            ; @r{default modifier}
(mpoint-x p2)  @result{} 4

(set! (mpoint-x p2) 6)          ; @r{generalized @code{set!} also works}
(mpoint-x p2)  @result{} 6
@end example

Next one is an example of inheritance.
Note that the default constructor takes arguments for
fields of the parent record as well.

@example
(define-record-type (qpoint mpoint) #t #t
  (w))

(define p3 (make-qpoint 1 2 3 4))

(qpoint? p3)  @result{} #t      ; @r{p3 is a qpoint}
(mpoint? p3)  @result{} #t      ; @r{... and also an mpoint}

(mpoint-x p3) @result{} 1       ; @r{accessing inherited field}
(mpoint-y p3) @result{} 2
(mpoint-z p3) @result{} 3
(qpoint-w p3) @result{} 4
@end example

A small caveat: Accessors and modifiers for inherited fields
(e.g. @code{qpoint-x} etc.) are not created.

Gauche's convention is to enclose class name by @code{<>}.
You can follow the convention and still explicitly gives
simpler names (instead of @code{make-<point>} or @code{<point>-x}):

@example
(define-record-type <point> make-point point?
  (x point-x)
  (y point-y)
  (z point-z))
@end example


@node Record types inspection layer, Record types procedural layer, Record types syntactic layer, Record types
@subsection Inspection layer

This layer provides common procedures that operates on record type
descriptors and record instances.

Note that a record type descriptor is a class in Gauche, so
you can also use operators on classes (e.g. @code{class-name},
@code{class-slots} etc.) on record type descriptors as well.
However, these procedures are more portable.

@defun record? obj
[SRFI-99][R6RS]
@{@t{gauche.record}@}
Returns @code{#t} iff @var{obj} is an instance of record type,
@code{#f} otherwise.
@end defun

@defun record-rtd record
[SRFI-99][R6RS]
@{@t{gauche.record}@}
Returns the record type descriptor of the record instance.
@end defun

@defun rtd-name rtd
[SRFI-99]
@{@t{gauche.record}@}
Returns the name of the record type descriptor @var{rtd}.
@end defun

@defun rtd-parent rtd
[SRFI-99]
@{@t{gauche.record}@}
Returns the parent type of the record type descriptor @var{rtd}.
If @var{rtd} doesn't have a parent, @code{#f} is returned.
@end defun

@defun rtd-field-names rtd
[SRFI-99]
@{@t{gauche.record}@}
Returns a vector of symbols, each of which is the names of the direct
fields of the record represented by @var{rtd}.   The result doesn't
include inherited fields.
@end defun

@defun rtd-all-field-names rtd
[SRFI-99]
@{@t{gauche.record}@}
Returns a vector of symbols, each of which is the names of the
fields of the record represented by @var{rtd}.   The result includes
all inherited fields.
@end defun

@defun rtd-field-mutable? rtd field-name
[SRFI-99]
@{@t{gauche.record}@}
Returns @code{#t} iff the field with the name @var{field-name}
of a record represented by @var{rtd} is mutable.
@end defun


@node Record types procedural layer, Pseudo record types, Record types inspection layer, Record types
@subsection Procedural layer

These procedures are low-level machinery on top of which
@code{define-record-type} is implemented.  They can be used
to create a new record type at runtime.

@defun make-rtd name field-specs :optional parent
[SRFI-99]
@{@t{gauche.record}@}
Creates and returns a new record type descriptor with name @var{name} and
having fields specified by @var{field-specs}.  If @var{parent}
is given, it must be a record type descriptor or @code{#f}.
If it is a record type descriptor, the created record type
inherits from it.

The @var{field-specs} argument must be a vector, each
element of which is a @emph{field specifier}.  A field
specifier can be a symbol, a list @code{(mutable @var{symbol})},
or a list @code{(immutable @var{symbol})}.  The @var{symbol} names
the field.  A single symbol or @code{(mutable @var{symbol})} format
makes the field mutable, and @code{(immutable @var{symbol})} format
makes the field immutable.

Note: Gauche does not implement the extension suggested in
SRFI-99 yet, which is @code{sealed}, @code{opaque} and @code{uid}
arguments.
@end defun

@defun rtd? obj
[SRFI-99]
@{@t{gauche.record}@}
Returns @code{#t} if @var{obj} is a record type descriptor,
@code{#f} otherwise.
@end defun

@defun rtd-constructor rtd :optional field-specs
[SRFI-99]
@{@t{gauche.record}@}
Returns a procedure that creates an instance record of
the record type represented by @var{rtd}.
Without @var{field-specs}, it returns the default constructor,
which takes as many arguments as the number of fields of
the record to initialize them.

You can give a vector of symbols as @var{field-specs}.  The @var{n}-th
symbol specifies which field of the instance should be initialized
by the @var{n}-th argument.   The @var{field-specs} vector cannot
contain duplicate names.  If the record type defines a field with
the same name as the one in the parent record type, the custom constructor
can only initialize the field of the derived type's instance.
@end defun

@defun rtd-predicate rtd
[SRFI-99]
@{@t{gauche.record}@}
Returns a predicate to test an object is an instance of @var{rtd}.

If @var{rtd} is a pseudo record type, the predicate merely tests
the given object is in an appropriate type and has enough size
to hold the contents.   See @ref{Pseudo record types} for the details.
@end defun

@defun rtd-accessor rtd field-name
[SRFI-99]
@{@t{gauche.record}@}
Returns a procedure that takes one argument, an instance of @var{rtd},
and returns the value of the @var{field-name} of the instance.

An error is signaled if the record type doesn't have the field
of name @var{field-name}.

If @var{rtd} is inherits other record types, and it defines a field
of the same name as inherited ones, then the accessor returned by
this procedure retrieves the value of the field of the derived record.
@end defun

@defun rtd-mutator rtd field-name
[SRFI-99]
@{@t{gauche.record}@}
Returns a procedure that takes two arguments, an instance of @var{rtd}
and a value, and sets the latter as the value of the @var{field-name}
of the instance.

An error is signaled if the record type doesn't have the field
of name @var{field-name}, or the named field is immutable.

Like @code{rtd-accessor}, if the record has a field with the same
name as inherited one, the modifier returned by this procedure
only modifies the field of the derived record.
@end defun


@node Pseudo record types,  , Record types procedural layer, Record types
@subsection Pseudo record types

A pseudo record type is a record type that does not create
an instance of its own type.
Instead it treats an object of other collection
types, such as a vector, as if it had named fields.  It's easier
to understand by an example:

@example
(define-record-type (vpoint (pseudo-rtd <vector>)) #t #t
  (x) (y) (z))

(make-vpoint 1 2 3)  @result{} #(1 2 3)
(vpoint-x '#(1 2 3)) @result{} 1

(rlet1 v (make-vpoint 1 2 3)
  (set! (vpoint-y v) -1))
 @result{} #(1 -1 3)
@end example

To create a pseudo record type, specify another pseudo
record type as a parent.   The procedure @code{pseudo-rtd}
can be used to obtain a base pseudo record type of
the suitable instance class.

@defun pseudo-rtd instance-class
@{@t{gauche.record}@}
Returns a pseudo rtd suitable to use @var{instance-class} as
a pseudo record.

Currently, @code{<list>}, @code{<vector>}, and uniform vector
classes (@code{<u8vector>} etc.) are supported as @var{instance-class}.
@end defun

The predicates of a pseudo record return @code{#t} if the given
object can be interpreted as the pseudo record.  In the above
example of @code{vpoint} record, the predicate @code{vpoint?}
returns @code{#t} iff the given object is a vector with 3 or more
elements:

@example
(vpoint? '#(0 0 0))   @result{} #t
(vpoint? '#(0 0))     @result{} #f
(vpoint? '(0 0 0))    @result{} #f
(vpoint? '#(0 0 0 0)) @result{} #t
@end example

We allow more elements so that the pseudo record can be used
to interpret the header part of the longer data.

@c ----------------------------------------------------------------------
@node Reloading modules, Simple dispatcher, Record types, Library modules - Gauche extensions
@section @code{gauche.reload} - Reloading modules
@c NODE モジュールの再ロード, @code{gauche.reload} - モジュールの再ロード

@deftp {Module} gauche.reload
@mdindex gauche.reload
In the development cycle, you often have to reload modules frequently.
This module supports it.

Note that some part of semantics of the program depends on
the order of loading modules, so reloading arbitrary modules
may change the program behavior unexpectedly.  This module
is for developers who knows what they are doing.

@strong{Redefinition rules}: Reloading a module resets all
the binding in the module by default.
Sometimes it is not desirable, however.  For example,
you might want to keep an intermediate results in some variable.
You can specify rules for the reloading procedure to determine
which binding to keep.

The rule is described in the following syntax.
@example
  <module-rules> : (<module-rule> @dots{})
  <module-rule>  : (<module-pattern> <rule> @dots{})
  <module-pattern> : @r{a symbol module name, or a symbol containing glob pattern}
  <rule>         : @r{procedure} | @r{symbol} | @r{regexp}
                 | (and <rule> @dots{})
                 | (or  <rule> @dots{})
                 | (not <rule>)
@end example

@code{<module-rules>} is the global rule to determine per-module
rules.  @code{<module-pattern>} is either a symbol module name
or a symbol that contains glob pattern (e.g. @code{mylib.*}).
If @code{<rule>} is a procedure, it is used as a predicate
and the bindings whose value satisfies the predicate are kept from
redefinition.   If @code{<rule>} is a symbol, the binding of
the variable whose name is the symbol is kept.  If @code{<rule>}
is a regexp, the bindings of the variable whose name matches the
regexp are kept.

Note that the mechanism to prevent redefinition is kind of ad-hoc
hack and semantically unclean.  Especially, the right-hand expressions
of @code{define}s are still evaluated, so any side effects they have
will be in effect (e.g. @code{define-class} would still redefine a class).
It's just for your convenience.
Take a look at the code if you want to know the exact behavior.
@end deftp

@defun reload module-name :optional rule @dots{}
@{@t{gauche.reload}@}
Reloads the specified module.   You can optionally specify
redefinition rules by @var{rule} @dots{},
where each @var{rule} is the term @code{<rule>} defined above.
@end defun

@defun reload-modified-modules :optional module-rules
@{@t{gauche.reload}@}
Reloads module(s) that have been modified since they are loaded
last time.  If optional @var{module-rules} is given, it is
used to determine the redefinition rules for reloaded modules.
If @var{module-rules} is omitted, the current rules are used.
The default of current rules is empty.   You can set the current
rules by @code{module-reload-rules}.
@end defun

@defun module-reload-rules :optional module-rules
@{@t{gauche.reload}@}
This is a parameter (@pxref{Parameters}) that keeps
the default module rules for @code{reload-modified-modules}.
If called without arguments, returns the current module rules.
If called with @var{module-rules}, sets the argument to the
current module rules.
@end defun

@defun reload-verbose :optional flag
@{@t{gauche.reload}@}
This is a parameter to control verbosity of the reloading procedures.
If called without arguments, returns the current verbosity flag.
If called with @var{flag}, it is set to the current verbosity flag.
@end defun

@c ----------------------------------------------------------------------
@node Simple dispatcher, Sequence framework, Reloading modules, Library modules - Gauche extensions
@section @code{gauche.selector} - Simple dispatcher
@c NODE 簡単なディスパッチャ, @code{gauche.selector} - 簡単なディスパッチャ

@deftp {Module} gauche.selector
@mdindex gauche.selector
This module provides a simple interface to dispatch I/O events to
registered handlers, based on @code{sys-select} (@pxref{I/O multiplexing}).
@end deftp

@deftp {Class} <selector>
@clindex selector
@{@t{gauche.selector}@}
A dispatcher instance that keeps watching I/O ports with associated
handlers.  A new instance can be created by @code{make} method.
@end deftp


@deffn {Method} selector-add! (self <selector>) port-or-fd proc flags
@{@t{gauche.selector}@}
Add a handler @var{proc} to the selector.  @var{proc} is called
when @var{port-or-fd}, which should be a port object or an integer
that specifies a system file descriptor,  meets a certain condition
specified by @var{flags}.
@var{flags} must be a list of one or more of the following symbols.
@table @code
@item r
Calls @var{proc} when data is available at @var{port-or-fd} to read.
@item w
Calls @var{proc} when @var{port-or-fd} is ready to be written.
@item x
Calls @var{proc} when an exceptional condition occurs on @var{port-or-fd}.
@end table

@var{proc} is called with two arguments.  The first one is @var{port-or-fd}
itself, and the second one is a symbol @code{r}, @code{w} or @code{x},
indicating the condition.

If a handler is already associated with @var{port-or-fd} under the
same condition, the previous handler is replaced by @var{proc}.
@end deffn

@deffn {Method} selector-delete! (self <selector>) port-or-fd proc flags
@{@t{gauche.selector}@}
Deletes the handler entries that matches @var{port-or-fd}, @var{proc}
and @var{flags}.   One or more of the arguments may be @code{#f},
meaning ``don't care''.  For example,
@example
(selector-delete! selector the-port #f #f)
@end example
deletes all the handlers associated to @var{the-port}, and
@example
(selector-delete! selector #f #f '(w))
@end example
deletes all the handlers waiting for writable condition.
@end deffn


@deffn {Method} selector-select (self <selector>) :optional (timeout #f)
@{@t{gauche.selector}@}
Dispatcher body.  Waits for the conditions registered in @var{self},
and when it occurs, calls the associated handler.
If the @var{timeout} argument is omitted or false, this method waits
indefinitely.  Alternatively you can give a timeout value, that can
be a real number in microseconds, or a list of two integers that
represents seconds and microseconds.

Returns the number of handlers called.  Zero means the selector has been
timed out.

It is safe to modify @var{self} inside handler.  The change will be
effective from the next call of @code{selector-select}
@end deffn

This is a simple example of "echo" server:

@example
(use gauche.net)
(use gauche.selector)
(use gauche.uvector)

(define (echo-server port)
  (let ((selector (make <selector>))
        (server   (make-server-socket 'inet port :reuse-addr? #t)))

    (define (accept-handler sock flag)
      (let* ((client (socket-accept server))
             (output (socket-output-port client)))
        (selector-add! selector
                       (socket-input-port client :buffering #f)
                       (lambda (input flag)
                         (echo client input output))
                       '(r))))

    (define (echo client input output)
      (let ((str (read-uvector <u8vector> 4096 input)))
        (if (eof-object? str)
            (begin (selector-delete! selector input #f #f)
                   (socket-close client))
            (begin (write-uvector str output)
                   (flush output)))))

    (selector-add! selector
                   (socket-fd server)
                   accept-handler
                   '(r))
    (do () (#f) (selector-select selector))))
@end example

@c ----------------------------------------------------------------------
@node Sequence framework, Syslog, Simple dispatcher, Library modules - Gauche extensions
@section @code{gauche.sequence} - Sequence framework
@c NODE シーケンスフレームワーク, @code{gauche.sequence} - シーケンスフレームワーク

@deftp {Module} gauche.sequence
@mdindex gauche.sequence
Provides a generic operations on @emph{sequences}.
A sequence is a collection with ordered elements.
Besides all the operations applicable on collections,
you can associate integer index to each element,
and apply order-aware operations on the elements.

This module inherits @code{gauche.collection} (@pxref{Collection framework}).
All the collection generic operations can be applied to a sequence as well.

Among Gauche builtin class, lists, vectors and strings are sequences
and the specialized methods are defined for them.   Other extension
types, such as uniform vectors, have the methods as well.
@end deftp

@menu
* Fundamental sequence accessors::
* Slicing sequence::
* Mapping over sequences::
* Other operations over sequences::
* Implementing sequence::
@end menu

@node Fundamental sequence accessors, Slicing sequence, Sequence framework, Sequence framework
@subsection Fundamental sequence accessors
@c NODE 基本的なシーケンスのアクセサ

@deffn {Method} ref (seq <sequence>) index :optional fallback
@{@t{gauche.sequence}@}
Returns @var{index}-th element of the sequence @var{seq}.
This method enables uniform access for any sequence types.

When @var{index} is less than zero, or greater than or equal to the
size of the sequence, @var{fallback} is returned if provided, or
an error is signaled if not.

@example
(ref '(a b c) 1)  @result{} b
(ref '#(a b c) 1) @result{} b
(ref "abc" 1)     @result{} #\b
@end example
@end deffn

@deffn {Method} {(setter ref)} (seq <sequence>) index value
@{@t{gauche.sequence}@}
Sets @var{value} to the @var{index}-th element of the sequence @var{seq}.
This is the uniform sequence modifier.

Note: Some sequences may not support arbitrary modification by index.
For example, if you have a sequence representing a set of sorted integers,
you cannot modify @var{i}-th element with arbitrary value.  Yet such
sequence may provide other means of modification, such as inserting
or deleting elements.

@example
(let ((x (list 'a 'b 'c)))
  (set! (ref x 1) 'z)
  x) @result{} (a z c)

(let ((x (vector 'a 'b 'c)))
  (set! (ref x 1) 'z)
  x) @result{} #(a z c)

(let ((x (string #\a #\b #\c)))
  (set! (ref x 1) #\z)
  x) @result{} "azc"
@end example
@end deffn

@deffn {Method} referencer (seq <sequence>)
@{@t{gauche.sequence}@}
@end deffn

@deffn {Method} modifier (seq <sequence>)
@{@t{gauche.sequence}@}
@end deffn

@node Slicing sequence, Mapping over sequences, Fundamental sequence accessors, Sequence framework
@subsection Slicing sequence
@c NODE シーケンスのスライス

@deffn {Method} subseq (seq <sequence>) :optional start end
@{@t{gauche.sequence}@}
Retrieve a subsequence of the sequence @var{seq}, from
@var{start}-th element (inclusive) to @var{end}-th element (exclusive).
If @var{end} is omitted, up to the end of sequence is taken.
The type of the returned sequence is the same as @var{seq}.

@example
(subseq '(a b c d e) 1 4)   @result{} (b c d)
(subseq '#(a b c d e) 1 4)  @result{} #(b c d)
(subseq "abcde" 1 4)        @result{} "bcd"

(subseq '(a b c d e) 3)     @result{} (d e)
@end example
@end deffn

@deffn {Method} {(setter subseq)} (seq <sequence>) start end value-seq
@deffnx {Method} {(setter subseq)} (seq <sequence>) start value-seq
@{@t{gauche.sequence}@}
Sets the elements of @var{value-seq} from the @var{start}-th element
(inclusive) to the @var{end}-th element (exclusive) of the sequence @var{seq}.
@var{Value-seq} can be any sequence, but its size
must be larger than (@var{end} - @var{start}).

In the second form, @var{end} is figured out by the length of @var{value-seq}.

@example
(define s (vector 'a 'b 'c 'd 'e))
(set! (subseq s 1 4) '(4 5 6))
s @result{} #(a 4 5 6 e)
(set! (subseq s 0)   "ab")
s @result{} #(#\a #\b 5 6 e)
@end example
@end deffn

@node Mapping over sequences, Other operations over sequences, Slicing sequence, Sequence framework
@subsection Mapping over sequences
@c NODE シーケンス上のマップ

You can use extended @code{fold}, @code{map}, @code{for-each} and other
generic functions on sequences, since a sequence is also a collection.
However, sometimes you want to have index as well as the element itself
during iteration.   There are several generic functions for it.

@deffn {Method} fold-with-index kons knil (seq <sequence>) @dots{}
@{@t{gauche.sequence}@}
Like generic @code{fold}, except @var{kons} is given
the index within @var{seq}, as the first argument,
as well as each element from @var{seq}s and the accrued value.

@example
(fold-with-index acons '() '(a b c))
  @result{} ((2 . c) (1 . b) (0 . a))
@end example
@end deffn

@deffn {Method} map-with-index proc (seq <sequence>) @dots{}
@deffnx {Method} map-to-with-index class proc (seq <sequence>) @dots{}
@deffnx {Method} for-each-with-index proc (seq <sequence>) @dots{}
@{@t{gauche.sequence}@}
Like @code{map}, @code{map-to} and @code{for-each}, except @var{proc}
receives the index as the first argument.

@example
(map-with-index list '(a b c d) '(e f g h))
  @result{} ((0 a e) (1 b f) (2 c g) (3 d h))

(map-to-with-index <vector> cons '(a b c d))
  @result{} #((0 . a) (1 . b) (2 . c) (3 . d))
@end example
@end deffn

@deffn {Method} find-with-index pred (seq <sequence>)
@{@t{gauche.sequence}@}
Finds the first element in @var{seq} that satisfies @var{pred}
like @code{find}, but returns two values, the index of the element
and the element itself.   If no element satisfies @var{pred},
two @code{#f}'s are returned.

@example
(find-with-index char-upper-case? "abraCadabra")
  @result{} 4 and #\C

(find-with-index char-numeric? "abraCadabra")
  @result{} #f and #f
@end example
@end deffn

@deffn {Method} find-index pred (seq <sequence>)
@{@t{gauche.sequence}@}
Like @code{find}, but returns the index of the first element
that satisfies @var{pred} in @var{seq}, instead of the element itself.
If no element in @var{seq} satisfies @var{pred}, @code{#f} is returned.

@example
(find-index char-upper-case? "abraCadabra")
  @result{} 4

(find-index char-numeric? "abraCadabra")
  @result{} #f
@end example

See also @code{list-index} in @code{scheme.list}
(@pxref{R7RS lists}).
@end deffn

@deffn {Method} fold-right kons knil (seq <sequence>) @dots{}
@{@t{gauche.sequence}@}
Generalization of @code{fold-right} on lists.
Like @code{fold}, this method applies a higher-order function
@var{kons} over given sequence(s), passing the "seed" value
whose default is @var{knil}.  The difference between @code{fold}
and @code{fold-right} is the associative order of elements on
which @var{kons} is applied.

When we have one sequence, @code{[E0, E1, ..., En]}, @code{fold}
and @code{fold-right} work as follows, respectively.

@example
fold:
  (kons En (kons En-1 (kons ... (kons E1 (kons E1 knil)) ...)))

fold-right
  (kons E0 (kons E1 (kons ... (kons En-1 (kons En knil)) ...)))
@end example

This method isn't defined on @code{<collection>}, since
collections don't care the order of elements.
@end deffn


@node Other operations over sequences, Implementing sequence, Mapping over sequences, Sequence framework
@subsection Other operations over sequences
@c NODE その他のシーケンス上の操作

@subsubheading Selection and searching

@deffn {Generic function} sequence-contains haystack needle :key test
@{@t{gauche.sequence}@}
Both @var{needle} and @var{haystack} must be sequences.
Searches @var{needle} from @var{haystack} from the beginning of @var{haystack}.
If @var{needle} is found, the index in @var{haystack} where it begins is
returned.  Otherwise @code{#f} is returned.  The keyword argument
@var{test} is used to compare elements; its default is @code{eqv?}.

@example
(sequence-contains '#(a b r a c a d a b r a) '#(b r a))
  @result{} 1

(sequence-contains '#(a b r a c a d a b r a) '#(c r a))
  @result{} #f
@end example

This can be regarded as generalization of @code{string-contains} in srfi-13
(@pxref{SRFI-13 String searching}).
@end deffn

@defun break-list-by-sequence list needle :key test
@defunx break-list-by-sequence! list needle :key test
@{@t{gauche.sequence}@}
Searches a sequence @var{needle} from @var{list},
and if found, breaks @var{list}
to two parts---the prefix of @var{list} up to right before @var{needle}
begins, and the rest---and returns them.
@var{List} must be a list, but @var{needle} can be any sequence.
Elements are compared by @var{test}, defaulted to @code{eqv?}.

@example
(break-list-by-sequence '(a b r a c a d a b r a) '(c a d))
  @result{} (a b r a) @r{and} (c a d a b r a)
@end example

If @var{needle} isn't found in @var{list}, it returns @var{list} itself
and @code{()}.  This behavior is aligned to @code{span} and @code{break}
(@pxref{R7RS lists}), which split a list by predicate but
returns the whole list if split condition isn't met.

@example
(break-list-by-sequence '(a b r a c a d a b r c a) '(c a z))
  @result{} (a b r a c a d a b r c a) @r{and} ()
@end example

The linear update version @code{break-list-by-sequence!}
modifies @var{list} to create the return value if necessary,
so @var{list} must be mutable.  The caller must use the return
value instead of relying on side-effects, though,
for @var{list} may not be modified.
@end defun

@defun sequence->kmp-stepper needle :key test
@{@t{gauche.sequence}@}
This is an internal routine to search subsequence (@var{needle}) inside
larger sequence, using Knuth-Morris-Pratt (KMP) algorithm.
It is used in @code{sequence-contains},
@code{break-list-by-sequence} and @code{break-list-by-sequence!}.

Returns a procedure that performs one step of KMP search.
The procedure takes two arguments, an element @var{elt}
and an index @var{k}.  It compares @var{elt} with
@code{(~ needle k)}, and returns two values---the next index and
a flag indicating the match is completed.  When the match is
completed, the next index is equal to the length of @var{needle}.

As an edge case, if @var{needle} is an empty sequence,
@code{sequence->kmp-stepper} returns @code{#f}.

Elements are compared using @var{test}, which is defaulted to @code{eqv?}.

The following is a skeleton of searcher using
@code{sequence->kmp-stepper}.  Here we assume @var{haystack}
is a list, and we just return whether the needle is
found or not, or needle is empty; you might want to carry
around other info in the loop (e.g. @code{sequence-contains}
tracks the current index of @var{haystack} in order to
return the found index.)

@example
(if-let1 stepper (sequence->kmp-stepper needle)
  (let loop ([haystack haystack]
             [k 0])
    (if (null? haystack)
      'not-found
      (receive (k found) (stepper (car haystack) k) ; KMP step
        (if found
          'found
          (loop (cdr haystack) k)))))
  'needle-is-empty)
@end example
@end defun

Note that selection and searching methods for collections
can also be applied to sequences.
See @ref{Selection and searching in collection}.

@subsubheading Grouping

@deffn {Generic function} group-sequence seq :key key test
@{@t{gauche.sequence}@}
Groups consecutive elements in a sequence @var{seq} which
have the common key value.  A key value of an element is
obtained by applying the procedure @var{key} to the element;
the default procedure is @code{identity}.
For each element in @var{seq}, @var{key} is applied exactly once.
The equal-ness of keys are compared by @var{test} procedure,
whose default is @code{eqv?}.

@example
(group-sequence '(1 1 1 2 3 4 4 2 2 3 1 1 3))
  @result{} ((1 1 1) (2) (3) (4 4) (2 2) (3) (1 1) (3))

(group-sequence '(1 1 1 2 3 4 4 2 2 3 1 1 3)
                :key (cut modulo <> 2)))
  @result{} ((1 1 1) (2) (3) (4 4 2 2) (3 1 1 3))

(group-sequence '#("a" "a" "b" "b" "c" "d" "d")
                :test string=?)
  @result{} (("a" "a") ("b" "b") ("c") ("d" "d"))

(group-sequence "aabbcdd"
                :test char=?)
  @result{} ((#\a #\a) (#\b #\b) (#\c) (#\d #\d))
@end example

This method is similar to Haskell's @code{group}.
If you want to group elements that are not adjacent,
use @code{group-collection}
(@pxref{Selection and searching in collection}).

If you simply need to reduce each group for one instance,
that is, removing adjacent duplicated elements,
you can use @code{delete-neighbor-dups} below.
@end deffn

@deffn {Generic function} group-contiguous-sequence seq :key key next test squeeze
@{@t{gauche.sequence}@}
Group contiguous elements in @var{seq}.

@example
(group-contiguous-sequence '(1 2 3 4 7 8 9 11 13 14 16))
  @result{} ((1 2 3 4) (7 8 9) (11) (13 14) (16))
@end example

If the keyword argument @var{squeeze} is true, each subsequence is
represented with its first and last elements, except when the subsequence
has only one element.

@example
(group-contiguous-sequence '(1 2 3 4 7 8 9 11 13 14 16) :squeeze #t)
  @result{} ((1 4) (7 9) (11) (13 14) (16))
@end example

The keyword argument @var{key} must be a procedure taking one argument,
and it is applied to every element in the sequence once, to construct
the result.  Its default is @code{identity}.

The keyword argument @var{next} must be a procedure 
taking one argument, which is the key value (whatever @var{key} procedure
returns) and must return the ``next'' key value.
Its default is @code{(^n (+ n 1))}.

The @var{test} argument must be a procedure taking two argument
and used to compare two key values.  Its default is @code{eqv?}.

@example
(group-contiguous-sequence "AbCdFgH"
  :key char-upcase :next (^c (integer->char (+ 1 (char->integer c)))))
  @result{} ((#\A #\B #\C #\D) (#\F #\G #\H))
@end example
@end deffn

@deffn {Generic function} delete-neighbor-dups seq :key key test start end
@{@t{gauche.sequence}@}
Returns a sequence of the same type as @var{seq}, in which
elements in @var{seq} are included in the original order, except
duplicate adjacent elements.
The type of @var{seq} must has a builder.

@example
(delete-neighbor-dups '(1 1 1 2 3 4 4 2 2 3 1 1 3))
  @result{} (1 2 3 4 2 3 1 3)

(delete-neighbor-dups '#(1 1 1 2 3 4 4 2 2 3 1 1 3))
  @result{} #(1 2 3 4 2 3 1 3)

(delete-neighbor-dups "1112344223113")
  @result{} "12342313"
@end example

Elements are compared with @code{eqv?} by default.  You can pass
alternative procedure to @var{test} keyword argument; it is always
called as @code{(@var{test} @var{x} @var{y})},
where @var{x} and @var{y} are the contiguous elements in @var{seq}.
If elements are compared equal, the first one is kept:

@example
(delete-neighbor-dups "AaaAbBBbCCcc" :test char-ci=?)
  @result{} "AbC"
@end example

If @var{key} is provided, it must be a procedure that takes one arguments.
It is applied to each element of @var{seq} at most once, and each resulting
value is used for the comparison instead of elements themselves.

@example
(delete-neighbor-dups
  '((1 . "a") (1 . "b") (2 . "c") (2 . "d"))
  :key car)
  @result{} ((1 . "a") (2 . "c"))
@end example

The @var{start} and @var{end} arguments specify indexes in the @var{seq}
to limit the range to look at.  Where @var{start} is inclusive, @var{end}
is exclusive.

@example
(delete-neighbor-dups "1112344223113" :start 3 :end 9)
  @result{} "2342"
@end example
@end deffn

@deffn {Generic function} delete-neighbor-dups! seq :key key test start end
@{@t{gauche.sequence}@}
Scan @var{seq} from left to right, dropping consecutive duplicated
elements.  The result is stored into @var{seq}, packed to left.
Note @var{seq} must be modifiable by index, i.e. @code{modifier} method
must be defined.  The rest of @var{seq} will be untouched.
Returns the next index after the last modified entry.

@example
(let1 v (vector 1 1 2 2 3 3 2 2 4 4)
  (list (delete-neighbor-dups! v)
        v))
  @result{} (5 #(1 2 3 2 4 3 2 2 4 4))
@end example

The semantics of keyword arguments @var{key}, @var{test},
@var{start} and @var{end} are the same as
@code{delete-neighbor-dups}.

@example
(let1 v (vector 1 1 2 2 3 3 2 2 4 4)
  (list (delete-neighbor-dups! v :start 2)
        v))
  @result{} (6 #(1 1 2 3 2 4 2 2 4 4))
@end example

Note: This method works on any sequence with @code{modifier}
method, but it's not necessarily more efficient than
@code{delete-neighbor-dups}, which creates a new sequence.
If @var{seq} is a list or a string, each modification by index takes O(n)
time (for a string even it costs O(n) extra storage), so the
total cost is O(n^2), whereas @code{delete-neighbor-dups} 
needs O(n) time and storage.
This works best for vectors and alike,
with which it doesn't cost extra allocation and runs in O(n) time.
@end deffn

@deffn {Generic function} delete-neighbor-dups-squeeze! seq :key key test start end
@{@t{gauche.sequence}@}
Operates like @code{delete-neighbor-dups} but reuses storage of @var{seq},
which will be resized by dropping duplicated elements.
Returns the sequence after dupes are removed.

Not all sequences are resizable, so this method won't be defined
for such sequences.  The @code{gauche.sequence} module only
provides this method for @code{<list>}, in which dropping the
middle of the sequence is very efficient as it is just a
single @code{set-cdr!}.

@example
(delete-neighbor-dups-squeeze! (list 1 1 1 2 2 2 3 3 3))
  @result{} (1 2 3)

(delete-neighbor-dups-squeeze! (list 1 1 1 2 2 2 3 3 3 4 4)
                               :start 3 :end 9)
  @result{} (2 3)
@end example

The semantics of keyword arguments @var{key}, @var{test},
@var{start} and @var{end} are the same as
@code{delete-neighbor-dups}.
@end deffn


@subsubheading Prefix

@deffn {Generic function} common-prefix (a <sequence>) (b <sequence>) :key key test
@{@t{gauche.sequence}@}
Returns a new sequence of the same type of @var{a} which contains
the common prefix of sequences @var{a} and @var{b}.  The types of
@var{a} and @var{b} doesn't need to match.
The type of @var{a} must have a builder.

For each corresponding element in @var{a} and @var{b}, the @var{key}
procedure is applied (default @code{identity}), then compared with
@var{test} procedure (default @code{eqv?}).

@example
(common-prefix '(a b c d e) '(a b c e f))
  @result{} (a b c)

(common-prefix "abcef" '#(#\a #\b #\c #\d #\e))
  @result{} "abc"
@end example

For strings, @code{srfi-13} has a specific function with
related feature: @code{string-prefix-length}
(@pxref{SRFI-13 String prefixes & suffixes}).
@end deffn

@deffn {Generic function} common-prefix-to (class <class>) (a <sequence>) (b <sequence>) :key key test
@{@t{gauche.sequence}@}
Returns a new sequence of the type @var{class} which contains
the common prefix of sequences @var{a} and @var{b}.  The types of
@var{a} and @var{b} doesn't need to match, and neither
needs to have a builder.  The @var{class} must be a sequence class
with a builder.

The meanings of keyword arguments are the same as @code{common-prefix}.

@example
(common-prefix-to <list> "abcde" "ABCEF" :test char-ci=?)
  @result{} '(#\a #\b #\c)
@end example
@end deffn


@subsubheading Permutation and shuffling

@deffn {Generic function} permute (src <sequence>) (permuter <sequence>) :optional fallback
@{@t{gauche.sequence}@}
Returns a newly created sequence of the same type as @var{src}, in which
the elements are permuted from @var{src} according to @var{permuter}.

@var{Permuter} is a sequence of exact integers.  When the @var{k}-th element
of @var{permuter} is @var{i}, the @var{k}-th element of the result
is @code{(ref @var{src} @var{i})}.   Therefore, the size of the result
sequence is the same as the size of @var{permuter}.  @var{Permuter}
can be any kind of sequence, unrelated to the type of @var{src}.

It is allowed that the same index @var{i} can appear more than once
in @var{permuter}.

@example
(permute '(a b c d) '(3 2 0 1))     @result{} (d c a b)
(permute '(a b c d) '(0 2))         @result{} (a c)
(permute '(a b c d) '(0 0 1 1 2 2)) @result{} (a a b b c c)
@end example

If an integer in @var{permuter} is out of the valid range as the index
of @var{src}, then an error is signaled unless @var{fallback} is given.
If @var{fallback} is given, what value is used depends on the result of
@code{(ref @var{src} @var{i} @var{fallback})}---which usually returns
@var{fallback} for the out-of-range index @var{i}.

@example
(permute '#(a b c) '(3 2 1 0) 'foo) @result{} #(foo c b a)

(permute "!,HWdelor" #(2 5 6 6 7 1 -1 3 7 8 6 4 0) #\space)
  @result{} "Hello, World!"
@end example
@end deffn

@deffn {Generic function} permute-to (class <class>) (src <sequence>) (permuter <sequence>) :optional fallback
@{@t{gauche.sequence}@}
Like @code{permute}, but the result will be an instance of the given @var{class}
instead of the class of @var{src}.

@example
(permute-to <string> '(#\a #\b #\c #\d #\r)
            '(0 1 4 0 2 0 3 0 1 4 0))
  @result{} "abracadabra"
@end example
@end deffn

@deffn {Generic function} permute! (src <sequence>) (permuter <sequence>) :optional fallback
@{@t{gauche.sequence}@}
Also like @code{permute}, but the result is stored back to @var{src}.
@var{Src} must be a mutable sequence, and the length of @var{src} and
@var{permuter} must be the same.
@end deffn

@deffn {Generic function} shuffle (src <sequence>) :optional random-source
@{@t{gauche.sequence}@}
Returns a new sequence of the same type and size as @var{src},
in which elements are randomly permuted.

@example
(shuffle '(a b c d e))  @result{} (e b d c a)
(shuffle "abcde")       @result{} "bacde"
@end example

This generic function uses @code{srfi-27} (@pxref{Sources of random bits}).
By default it uses @code{default-random-source}, but you can pass
an alternative random source by the optional argument.
@end deffn

@deffn {Generic function} shuffle-to (class <class>) (src <sequence>) :optional random-source
@{@t{gauche.sequence}@}
Like @code{shuffle}, except that the result will be an instance of
@var{class} instead of the class of @var{src}.
@end deffn

@deffn {Generic function} shuffle! (src <sequence>) :optional random-source
@{@t{gauche.sequence}@}
Like @code{shuffle}, but the result is stored back to @var{src}.
@var{Src} must be a mutable sequence.
@end deffn


@node Implementing sequence,  , Other operations over sequences, Sequence framework
@subsection Implementing sequence
@c NODE シーケンスを実装する



@c ----------------------------------------------------------------------
@c @node Serializer, Terminal control, Simple dispatcher, Library modules
@c @section @code{gauche.serializer} - Serializer

@c @deftp {Module} gauche.serializer
@c @mdindex gauche.serializer
@c @end deftp

@c ----------------------------------------------------------------------
@node  Syslog, Terminal control, Sequence framework, Library modules - Gauche extensions
@section @code{gauche.syslog} - Syslog
@c NODE Syslog, @code{gauche.syslog} - Syslog

@deftp {Module} gauche.syslog
@mdindex gauche.syslog
This module provides syslog(3) system logger interface.

For the common applications, you might find @code{gauche.logger} module
easier to use (@pxref{User-level logging}).  This module is for those
who need direct access to the syslog API.

The procedures are only defined if the underlying system supports them.
@end deftp

@defun sys-openlog ident option facility
[POSIX]
@{@t{gauche.syslog}@}
Opens a connection to the system logger.  A string argument
@var{ident} is used for the prefix of the log, and usually is
the program name.  @var{Option} is an integer flag to control
the behavior of logging, and @var{facility} is an integer
that specify the type of the program.

The flag for @var{option} can be composed by @code{logior}-ing
one or more of the following integer constants:
@code{LOG_CONS}, @code{LOG_NDELAY}, @code{LOG_NOWAIT},
@code{LOG_ODELAY}, @code{LOG_PERROR} and @code{LOG_PID}.
(Some of the constants may not be defined if the underlying system
doesn't support them).

The @var{facility} argument can be one of the following integer
constants: @code{LOG_AUTH}, @code{LOG_AUTHPRIV}, @code{LOG_CRON},
@code{LOG_DAEMON}, @code{LOG_FTP}, @code{LOG_KERN}, @code{LOG_LOCAL0}
through @code{LOG_LOCAL7}, @code{LOG_LPR}, @code{LOG_MAIL}, @code{LOG_NEWS},
@code{LOG_SYSLOG}, @code{LOG_USER} and @code{LOG_UUCP}.
(Some of the constants may not be defined if the underlying system
doesn't support them).

See your system's manpage of openlog(3) for detail description about
these constants.
@end defun

@defun sys-syslog priority message
[POSIX]
@{@t{gauche.syslog}@}
Log the string @var{message}.  Unlike syslog(3), this procedure doesn't
do formatting---you can use @code{format} (@pxref{Output}) to create
a formatted message, or use higher-level routine @code{log-format}
(@pxref{User-level logging}).

An integer argument @var{priority} can be composed by @code{logior}-ing
one of the @var{facility} constants described above and
the @var{level} constants: @code{LOG_EMERG}, @code{LOG_ALERT},
@code{LOG_CRIT}, @code{LOG_ERR}, @code{LOG_WARNING}, @code{LOG_NOTICE},
@code{LOG_INFO}, @code{LOG_DEBUG}.

@end defun

@defun sys-closelog
[POSIX]
@{@t{gauche.syslog}@}
Closes the connection to the logging system.
@end defun

@defun sys-setlogmask mask
[POSIX]
@{@t{gauche.syslog}@}
Sets the process's log priority mask that determines which calls to
@code{sys-syslog} may be logged.
An priority @var{mask} can be composed by @code{logior}-ing
bitmasks corresponding to the @var{level} argument of @code{sys-syslog}.
You can use @code{sys-logmask} below to obtain a bitmask
from the level.
@end defun

@defun sys-logmask level
[POSIX]
@{@t{gauche.syslog}@}
Returns an integer bitmask for @code{sys-setlogmask} from
the log level @var{level}.
@end defun

@c ----------------------------------------------------------------------
@node Terminal control, Unit testing, Syslog, Library modules - Gauche extensions
@section @code{gauche.termios} - Terminal control
@c NODE 端末の制御, @code{gauche.termios} - 端末の制御

@deftp {Module} gauche.termios
@mdindex gauche.termios
This module provides procedures to control terminals.
On Unix platforms, the low-level API provides POSIX termios interface
as the module name suggests.  This module also provides
pseudo tty interface, if the system supports it.

On Windows native platforms, POSIX termios interface is not
available.  It is too different from Windows console API to
provide a meaningful emulation.  The low-level Windows console
API is available in the @code{os.windows} module
(@pxref{Windows support}).   You can still use high-level
terminal control procedures in this module.
@end deftp

@menu
* Posix termios interface::
* Common high-level terminal control::
@end menu

@node Posix termios interface, Common high-level terminal control, Terminal control, Terminal control
@subsection Posix termios interface
@c NODE POSIX termiosインタフェース

These procedures are available when the feature identifier
@code{gauche.os.windows} is @emph{not} defined.   See @code{cond-expand}
in @ref{Feature conditional} for how to switch code using
feature identifiers.

@deftp {Builtin Class} <sys-termios>
@clindex sys-termios
@{@t{gauche.termios}@}
POSIX termios(7) structure.

@defivar {<sys-termios>}  iflag
@end defivar
@defivar {<sys-termios>}  oflag
@end defivar
@defivar {<sys-termios>}  cflag
@end defivar
@defivar {<sys-termios>}  lflag
@end defivar
@defivar {<sys-termios>}  cc
@end defivar

The slots @code{iflag}, @code{oflag}, @code{cflag} and @code{lflag}
contains non-negative integers representing bitmasks.

The slot @code{cc} contains a @emph{copy} of @code{c_cc} array
of @code{struct termios}, as an u8vector (see @ref{Uniform vectors}
for the details about u8vector).
Since @code{cc} slot is a copy of the internal structure, you have
to @code{set!} an u8vector to the slot explicitly to make
changes to the @code{c_cc} array.

@end deftp

Throughout this section, argument @var{port-or-fd} refers to
either a port object or a small integer representing system's file
descriptor.  If @var{port} is not associated
to the system terminal, an error is signaled.  (You can check if @var{port}
has an associated terminal by @code{sys-isatty?}.
@pxref{Other file operations}).

@defun sys-tcgetattr port-or-fd
@{@t{gauche.termios}@}
Returns terminal parameters in a @code{<sys-termios>} object,
associated to @var{port-or-fd}.
@end defun

@defun sys-tcsetattr port-or-fd when termios
@{@t{gauche.termios}@}
Sets terminal parameters associated to @var{port-or-fd} by @var{termios},
which must be an instance of @code{<sys-termios>}.

An integer argument @var{when} specifies when the changes take effect.
Three variables are pre-defined for the argument:
@table @code
@item TCSANOW
@vindex TCSANOW
The change is reflected immediately.
@item TCSADRAIN
@vindex TCSADRAIN
The change is reflected after all pending output is flushed.
@item TCSAFLUSH
@vindex TCSAFLUSH
The change is reflected after all pending output is flushed,
and all pending input is discarded.
@end table
@end defun

@defun sys-tcsendbreak port-or-fd duration
@{@t{gauche.termios}@}
Transmits a zero stream for the specified duration
to the terminal associated to @var{port-or-fd}.
The unit of duration depends on the system; see man tcsendbreak(3) of
your system for details.
@end defun

@defun sys-tcdrain port-or-fd
@{@t{gauche.termios}@}
Waits until all output written to @var{port-or-fd} is transmitted.
@end defun

@defun sys-tcflush port-or-fd queue
@{@t{gauche.termios}@}
Discards data in the buffer of @var{port-or-fd}, specified by
@var{queue}, which may be one of the following values.
@table @code
@item TCIFLUSH
@vindex TCIFLUSH
Discards data received but not read.
@item TCOFLUSH
@vindex TCOFLUSH
Discards data written but not transmitted.
@item TCIOFLUSH
@vindex TCIOFLUSH
Do both @code{TCIFLUSH} and @code{TCOFLUSH} action.
@end table
@end defun

@defun sys-tcflow port-or-fd action
@{@t{gauche.termios}@}
Controls data flow of @var{port-or-fd} by @var{action}, which may be
one of the following values:
@table @code
@item TCOOFF
@vindex TCOOFF
Suspends output transmission.
@item TCOON
@vindex TCOON
Restarts output transmission.
@item TCIOFF
@vindex TCIOFF
Transmits a STOP character to make the terminal device stop transmitting
data to the system.
@item TCION
@vindex TCION
Transmits a START character to make the terminal device resume transmitting
data to the system.
@end table
@end defun

@defun sys-tcgetpgrp port-or-fd
@{@t{gauche.termios}@}
Returns process group ID of the terminal associated to @var{port-or-fd}.
@end defun

@defun sys-tcsetpgrp port-or-fd pgrp
@{@t{gauche.termios}@}
Sets process group ID of the terminal associated to @var{port-or-fd}
to @var{pgrp}.
@end defun

@defun sys-cfgetispeed termios
@defunx sys-cfsetispeed termios speed
@defunx sys-cfgetospeed termios
@defunx sys-cfsetospeed termios speed
@{@t{gauche.termios}@}
Gets/sets input/output speed (baud rate) parameter stored in @var{termios}
object.   Speed is represented by the following predefined numbers:
@code{B0}, @code{B50}, @code{B75}, @code{B110}, @code{B134},
@code{B150}, @code{B200}, @code{B300}, @code{B600}, @code{B1200},
@code{B1800}, @code{B2400}, @code{B4800}, @code{B9600},
@code{B19200}, @code{B38400}.

Some system may support higher baud rate, such as @code{B57600},
@code{B115200} or @code{B230400}.  You can use @code{symbol-bound?}
to check these options are defined.  @code{B0} is used to
terminate the connection.
@end defun

@defun sys-openpty :optional term
@{@t{gauche.termios}@}
Opens a pair of pseudo ttys, one for master and the other for slave,
then returns two integers which are their file descriptors.
An optional argument @var{term} must be, if passed, a @code{<sys-termios>}
object; it sets the slave pty's parameters.

You can use @code{open-input-fd-port} and/or @code{open-output-fd-port}
to create a port around the returned file descriptor (@pxref{File ports}).
To obtain pseudo tty's name, use @code{sys-ttyname}
(@pxref{Other file operations}).

This function is available only if the system supports @code{openpty(3)}.
@end defun

@defun sys-forkpty :optional term
@{@t{gauche.termios}@}
Opens a pair of pseudo ttys, one for master and the other for slave,
sets the slave pty suitable for login terminal, then fork(2).

Returns two integers; the first value is a child pid for the parent process,
and 0 for the child process.  The second value is a file descriptor
of the master pty.

An optional argument @var{term} must be, if passed, a @code{<sys-termios>}
object; it sets the slave pty's parameters.

This function is available only if the system supports @code{forkpty(3)}.

Note: @code{sys-forkpty} has the same MT hazard as @code{sys-fork}
(see @ref{Process management}, for details).  If you're
running multiple threads, use @code{sys-forkpty-and-exec} below.
@end defun

@defun sys-forkpty-and-exec command args :key iomap term sigmask
@{@t{gauche.termios}@}
Does @code{sys-forkpty}, and lets the child process
immediately @code{exec}s the specified @var{command}
with arguments @var{args}.   This function doesn't have
the hazard in multi-thread environment.

The meanings of arguments @var{command}, @var{args}, @var{iomap} and
@var{sigmask}
are the same as @code{sys-exec} (see @ref{Process management}).
If the keyword argument @var{term} is given, it is used to initialize
the slave pty.
@end defun

@node Common high-level terminal control,  , Posix termios interface, Terminal control
@subsection Common high-level terminal control
@c NODE 共通の高レベル端末制御

@defun without-echoing iport proc
@{@t{gauche.termios}@}
If @var{iport} is an input port connected to a terminal,
sets the terminal mode non-echoing and call @var{proc} with
@var{iport} as an argument.  Before returning from
@code{without-echoing}, or throwing an error,
the terminal mode is reset to the original state when this
procedure is called.  The procedure returns whatever value(s)
@var{proc} returns.

You can also pass @code{#f} to @var{iport}.  In that case,
this procedure tries to open a console (@code{/dev/tty} on Unix,
@code{CON} on Windows) and set the console mode, then calls
@var{proc} with the opened input port.  An error is thrown
if the procedure can not open a console.

If @var{iport} is other than above, this procedure
simply calls @var{proc} with @var{iport}.  This allows
the caller to read password from redirected input,
for example.

Note: Because of an implementation issue, on Windows native
platforms this procedure always changes console mode
of the standard input handle when @code{iport} is either
@code{#f} or a terminal input port.
@end defun

@defun has-windows-console?
@{@t{gauche.termios}@}
Returns @code{#t} iff the running Gauche is Windows-native and
the process has attached console.  On POSIX platforms this
procedure always returns @code{#f}.

The reason that @code{cond-expand} isn't enough is that on Windows
the program may start without console, but you can attach console
afterwards.  @xref{Windows console API}, for the details.
@end defun


@c ----------------------------------------------------------------------
@node Unit testing, Threads, Terminal control, Library modules - Gauche extensions
@section @code{gauche.test} - Unit Testing
@c NODE 単体テスト, @code{gauche.test} - 単体テスト

@deftp {Module} gauche.test
@mdindex gauche.test
Defines a set of functions to write test scripts.
A test script will look like this:

@lisp
(use gauche.test)
(test-start "my feature")
(load "my-feature")  ; @r{load your program}
(import my-feature)  ; @r{if your program defines a module.}

(test-module 'my-feature) ; @r{tests consistency in your module.}

(test-section "feature group 1")
(test "feature 1-1" EXPECT (lambda () TEST-BODY))
(test "feature 1-2" EXPECT (lambda () TEST-BODY))
 @dots{}

(test-section "feature group 2")
(define test-data ...)
(test "feature 2-1" EXPECT (lambda () TEST-BODY))
(test "feature 2-2" (test-error) (lambda () TEST-THAT-SIGNALS-ERROR))
 @dots{}

(test-end :exit-on-failure #t)
@end lisp

With this convention, you can run test both interactively or
in batch.   To run a test interactively, just load the file
and it reports a result of each test, as well as the summary
of failed test at the end.  To run a test in batch, it is
convenient to redirect the stdout to some file
If stdout is redirected to other than tty, all the verbose logs will go
there, and only a small amount of messages go to stderr.

It is recommended to have a "check" target always in Makefile
of your module/program, so that the user of your program can run a
test easily.  The rule may look like this:

@example
check :
        gosh my-feature-test.scm > test.log
@end example
@end deftp

@subheading Structuring a test file

@defun test-start module-name
@{@t{gauche.test}@}
Initializes internal state and prints a log header.
This should be called before any tests.
@var{Module-name} is used only for logging purpose.
@end defun

@defun test-section section-name
@{@t{gauche.test}@}
Marks beginning of the group of tests.  This is just for logging.
@end defun

@defun test-log fmtstr args @dots{}
@{@t{gauche.test}@}
This is also just for logging.  Creates a formatted string
with @var{fmrstr} and @var{args} just like @code{format},
then write it to the current output port, with prefix @code{;; } 
and newline at the end.

With the typical Makefile settings, where you redirect
stdout of test scripts to a log file, the message only goes to
the log file.

Using this, you can dump information that can't be automatically
tested but may be useful for troubleshooting.    For example, 
you get a mysterious test failure reports you can't reproduce
on your machine, and suspect
some aspects of the running systems may unpredictably
affect the test result.
You can put @code{test-log} in the test code to dump such parameters,
and ask the reporter to run the test again and analyze the log.
@end defun

@defun test-end :key exit-on-failure
@{@t{gauche.test}@}
Prints out list of failed tests.  If @var{exit-on-failure} is @code{#f} or
omitted, this procedure returns the number of failed tests.

Otherwise, this function terminates the @code{gosh}
process by @code{exit}.  If a fixnum is given to @code{exit-on-failure}
it becomes the process's exit status; if other true value is given,
the exit status will be 1.
@end defun

@defun test-record-file file
@{@t{gauche.test}@}
Suppose you have several test scripts.  Normally you run them
as a group and what you want to know is a concise summary of
the whole results, instead of each result of individual test files.

A @emph{test record file} is an auxiliary file used to
gather summary of the result.   It holds a one-line summary
of tests like this:

@example
Total:  9939 tests,  9939 passed,     0 failed,     0 aborted.
@end example

When a test record file exists,
@code{test-start} reads and parses it, and remembers the numbers.
Then @code{test-end} adds the count of the results and
writes them back to the same test record file.

If you writes the @code{check} target in your makefile as follows,
you will get the final one-line summary every time you run
@code{make check}, assuming that @file{test1.scm}, @file{test2.scm},
and @file{test3.scm} all has @code{(test-record-file "test.record")}
before a call to @code{test-start}.

@example
check:
        @@rm -f test.record test.log
        gosh test1.scm >> test.log
        gosh test2.scm >> test.log
        gosh test3.scm >> test.log
        @@cat test.record
@end example

Note that to make @code{test-record-file} work, it must be placed
before the call to @code{test-start}.

Alternatively, you can use the environment variable
@code{GAUCHE_TEST_RECORD_FILE} to specify the test record file.
@end defun

@deftp {Environment Variable} GAUCHE_TEST_RECORD_FILE
If this environment variable is set when the test script is run,
its value is used as the name of the test record file.

If the test script calls @code{test-record-file}, it takes precedence
and this environment variable is ignored.
@end deftp

@defun test-summary-check
@{@t{gauche.test}@}
If the test record file is set (either by @code{test-record-file} or
the environment variable @code{GAUCHE_TEST_RECORD_FILE}), read it,
and then exit with status 1 if the record has nonzero failure
count and/or nonzero abort count.  If the test record file isn't
set, this procedure does nothing.

This is useful when you have multiple test scripts and you want
to let @code{make} fail if any of tests fails, but not before all
test script is run.  If you make every test script use
@code{:exit-on-failure} of @code{test-end}, then @code{make}
stops immediately after the script that fails.  Instead, you
avoid using @code{:exit-on-failure}, but use the test record file
and for the last thing you can call this function:

@example
check:
   rm -f $GAUCHE_TEST_RECORD_FILE test.log
   gosh test1.scm >> test.log
   gosh test2.scm >> test.log
   cat $GAUCHE_TEST_RECORD_FILE /dev/null
   gosh -ugauche.test -Etest-summary-check -Eexit
@end example

By this, @code{make} will run all the test script no matter how
many of them fails (since @code{gosh} exits with status 0), but
detect an error since the last line of @code{gosh} call exits
with status 1 if there has been any failure.
@end defun

@subheading Individual tests

@defmac test* name expected expr :optional check hook
@{@t{gauche.test}@}
A convenience macro that wraps @var{expr} by lambda.

@example
(test* name expected expr)
  @equiv{} (test name expected (lambda () expr))
@end example
@end defmac

@defun test name expected thunk :optional check hook
@{@t{gauche.test}@}
Calls @var{thunk}, and checks its result fits @var{expected}
using a procedure @var{check}, which
is called as follows:
@example
(@var{check} @var{expected} @var{result-of-thunk})
@end example
It should return @code{#t} if the given result agrees with the
expected value, or @code{#f} otherwise.
The default check procedure is @code{test-check}, explained
below.  It compares @var{expected} and @var{result-of-thunk}
with @code{equal?}, except when @var{expected} is some
of special case test objects.  (See ``testing ambiguous results''
and ``testing abnormal cases''
paragraphs below for this special treatment.)

One typical usage of the custom check
procedure is to compare inexact numbers tolerating small error.

@example
(test "test 1" (/ 3.141592653589 4)
      (lambda () (atan 1))
      (lambda (expected result)
        (< (abs (- expected result)) 1.0e-10)))
@end example

@var{Name} is a name of the test, for the logging purpose.

When @var{thunk} signals an uncaptured error, it is caught and
yields a special error object @code{<test-error>}.
You can check it with another error object created by
@code{test-error} function to see if it is an expected type
of error.  See the entry of @code{test-error} below for the details.

The @var{hook} optional argument must be an @code{#f} or a procedure
that takes four arguments.  If it is a procedure, it is called after
the @code{test} procedure finishes the test.  The first argument
is a symbol either @code{pass} or @code{fail}, the second argument
is @var{name}, the third argument is @var{expected}, and the fourth argument
is either the result of @var{thunk}, or a @code{<test-error>} object
when @var{thunk} raises an error.  The return value of @var{hook} is
ignored.

It is mainly for libraries that wrap @code{gauche.test} and wants to
do its own bookkeeping.
@end defun

@defun test-check expected result :optional fallback
@{@t{gauche.test}@}
The default procedure @code{test} and @code{test*} use
to check the result of the test expression conforms the
expected value.  By default, @code{test-check} just compares
@var{expected} and @var{result} with a procedure @var{fallback},
which is defaulted to @code{equal?}.   @code{test-check} behaves
differently if @var{expected} is one of special test objects
described below.
@end defun

@subheading Testing ambiguous results

@defun test-one-of choice @dots{}
@{@t{gauche.test}@}
Sometimes the result of test expression depends on various
external environment, and you cannot put an exact expected value.
This procedure supports to write such tests conveniently.

Returns a special object representing @emph{either one of the choices}.
The default check procedure, @code{test-check}, recognizes the object
when it is passed in the @var{expected} argument, and returns true
if any one of @var{choice} @dots{} passes the check against the result.

For example, the following test passes if @code{proc} returns either
1 or 2.

@example
(test* "proc returns either 1 or 2" (test-one-of 1 2) (proc))
@end example
@end defun

@defun test-none-of choice @dots{}
@{@t{gauche.test}@}
Similar to @code{test-one-of}, but creates a special object
representing @emph{none of the choices}.
The test suceeds if the test expression evaluates to a value that
don't match any of @var{choice}s.
@end defun

@subheading Testing abnormal cases

@defun test-error :optional (condition-type <error>) (message #f)
@{@t{gauche.test}@}
Returns a new @code{<test-error>} object that matches with
other @code{<test-error>} object with the given @var{condition-type}.

The @code{test-check} procedure treats @code{<test-error>} objects
specially.  When @code{err-expected} and @code{err-actual}
are @code{<test-error>} objects,
@code{(test-check err-expected err-actual)} returns @code{#t}
if @code{err-expected}'s
condition type is the same as or supertype of @code{err-actual}'s.

For example, if you want to test a call to @code{foo} raises
an @code{<io-error>} (or its condition subtype), you can write
as the following example:

@example
(test "see if foo raises <io-error>" (test-error <io-error>) (foo))
@end example

Another optional argument @var{message} can be used to check if
the raised error has a message of expected pattern.  The argument
may be a string, a regexp or @code{#f} (default).
If it is a string, @code{test-check}
checks if the message of the raised error exactly match the
string.  If it is a regexp, @code{test-check} checks
the message of the raised error matches that regexp.
If it is @code{#f}, the message is not checked.
@end defun

@defvar *test-error*
@{@t{gauche.test}@}
(Deprecated) Bounded to an instance of @code{<test-error>} with
condition type @code{<error>}.  This is only provided for the
backward compatibility; new code should use @code{test-error}
procedure above.
@end defvar

@defvar *test-report-error*
@{@t{gauche.test}@}
If this variable is true, the @code{test} routine prints stack trace
to the current error port when it captures an error.  It is useful
when you got an unexpected test-error object and want to check out
where the error is occurring.

This variable is initialized by the environment variable
@code{GAUCHE_TEST_REPORT_ERROR} when the @code{gauche.test} module
is loaded.  For example, you can use the environment variable to check out
an unexpected error from your test script as follows (the value
of the environment variable doesn't matter).

@example
env GAUCHE_TEST_REPORT_ERROR=1 gosh mytest.scm
@end example
@end defvar

@subheading Quasi-static checks

Scheme is dynamically typed, which is convenient for incremental
and experimental development on REPL, but it tends to delay error detection
until the code is actually run.  It is very annoying that you run your
program for a while only to see it barfs on simple typo of variable name.

Gauche addresses this issue by checking certain types of errors
at the test phase.  It isn't purely a static check (we need to load
a module or a script, which evaluates toplevel expressions), nor
exhaustive (we can't catch inconsistencies that span over multiple
modules or about information that can be added at runtime).  Nevertheless
it can often catch some common mistakes, such as incorrect variable names
or calling procedures with wrong number of arguments.

The two procedures, @code{test-module} and @code{test-script}, 
load the named module and the script files respectively (which compiles
the Scheme code to VM instructions), then scan the compiled VM code
to perform the following tests:

@enumerate
@item
See if the global variables referenced within functions are all defined
(either in the module, or in one of imported modules).

@item
If a global variable is used as a function, see if the number of arguments
given to it is consistent to the actual function.

@item
See if the symbols set as autoload in the code can be resolved.

@item
While testing module, see if the symbols declared in the export list
are actually defined.
@end enumerate

The check is somewhat heuristic and we may miss some errors and/or
can have false positives.  For false positives, you can enumerate
symbols to be excluded from the test.

@defun test-module module :key allow-undefined bypass-arity-check
@{@t{gauche.test}@}
Loads the module and runs the quasi-static consistency check.
@var{Module} must be a symbol module name or a module.

Sometimes you have a global variable that may not be
defined depending on compiler options or platforms, and
you check its existence at runtime before using it.
The undefined variable reference check by @code{test-module}
doesn't follow such logic, and reports an error whenever
it finds your code referring to undefined variable.  In such case,
you can give a list of symbols to the @var{allow-undefined}
keyword argument; the test will excludes them from the check.

The arity check may also raise false positives, if the module
count on a behavior of global procedures that will be modified
after the module is loaded (e.g. a method with different number
of arguments can be added to a generic function after the module
is loaded, which would make the code valid.)  If you know
you're doing right thing and need to suppress the false positives,
pass a list of names of the functions to @code{bypass-arity-check}
keyword arguments.
@end defun

@defun test-script filename :key allow-undefined bypass-arity-check compile-only
@{@t{gauche.test}@}
Loads the script named by @var{filename}
into a fresh anonymous module and runs the quasi-static
consistency check.
@var{Filename} must be a string that names the script file.

The meaning of keyword arguments is the same as @code{test-module}.

Note that the toplevel forms in @var{filename} are evaluated, so scripts that
relies on the actions of toplevel forms could cause unwanted side-effects.
This check works best for the scripts written in @code{srfi-22} convention,
that is, calling actions from @code{main} procedure instead of toplevel
forms.  R7RS scripts relies on actions in toplevel forms and can't be
tested with this procedure.

Scripts that relies on being loaded into @code{user} module also
won't work well with this check, which loads the forms into anonymous
module.

If you need to test a script with toplevel side-effecting forms and
you can't change it, you may want to pass
true value to the @code{compile-only} keyword argument.  Then
@code{test-script} just compiles each toplevel form before running
static checking,
instead of @code{load}ing (which not only compiles but executes each
of toplevel forms).
@end defun

@c ----------------------------------------------------------------------
@node Threads, Measure timings, Unit testing, Library modules - Gauche extensions
@section @code{gauche.threads} - Threads
@c NODE スレッド, @code{gauche.threads} - スレッド

If enabled at compilation time, Gauche can use threads
built on top of either POSIX threads (pthreads) or Windows threads.

@deftp {Module} gauche.threads
@mdindex gauche.threads
Provides thread API.   You can 'use' this module regardless
whether the thread support is compiled in or not; if threads are not
supported, many thread-related procedures simply signals a
"not supported" error.
@end deftp

If you want to switch code depending on whether pthreads are
available or not, you can use a feature identifier @code{gauche.sys.threads}
with @code{cond-expand} form (@pxref{Feature conditional}).

@example
(cond-expand
 [gauche.sys.threads
   ;; Code that uses thread API (@code{gauche.threads} is automatically
   ;; loaded at this moment).
  ]
 [else
   ;; Code that doesn't use thread API
  ])
@end example

There are also feature identifiers @code{gauche.sys.pthreads} and
@code{gauche.sys.wthreads} defined for pthreads and Windows threads
platforms, respectively.
In Scheme level, however, you hardly need to distinguish
the underlying implementations.  It is recommended to use
@code{gauche.sys.threads} to switch the code according to
thread availability.

To check if threads are available at runtime,
instead of compile time, use the following procedure.

@defun gauche-thread-type
@{@t{gauche.threads}@}
Returns a symbol that indicates the supported thread type.
It can be one of the following symbols.

@table @code
@item none
Threads are not supported.
@item pthread
Threads are built on top of POSIX pthreads.
@item win32
Threads are built on top of Win32 threads.
@end table

(Note: On pthreads platforms, it should return @code{pthreads} instead
of @code{pthread}; then the returned symbol would correspond to the
value given to @code{--enable-threads} option at configuration time.
It's a historical overlook, stuck for the backward compatibility.)
@end defun

Scheme-level thread API conforms SRFI-18, "Multithreading support"
(@uref{https://srfi.schemers.org/srfi-18/srfi-18.html}), wrapped around Gauche's object interface.

@menu
* Thread programming tips::
* Thread procedures::
* Synchronization primitives::
* Thread exceptions::
@end menu

@node Thread programming tips, Thread procedures, Threads, Threads
@subsection Thread programming tips
@c NODE スレッドプログラミングTips

@subsubheading What's Gauche threads for

Although the surface API of threads looks simple and portable,
you need to know how the threads are implemented in order to utilize
the feature's potential.   Some languages support threads as
language's built-in construct and encourage programmers
to express the calculation in terms of threads.
However, it should be noted that in many cases there are
alternative ways than threads to implement the desired
algorithm, and you need to compare advantages and
disadvantages of using threads depending on how the threads
are realized in the underlying system.

In Gauche, the primary purpose of threads is to write programs
that @emph{require} preemptive scheduling, therefore are
difficult to express in other ways.  Preemptive threads may
be required, for example, when you have to call a module that
does blocking I/O which you can't intercept, or may spend
nondeterministic amount of calculation time that you want
to interrupt.

For each Gauche's thread, an individual VM is allocated
and it is run by the dedicated POSIX thread.  Thus the
cost of context switch is the same as the native
thread, but the creation of threads costs much higher than,
say, lightweight threads built on top of call/cc.
So Gauche's preemptive threads are @emph{not} designed for
applications that want to create thousands of threads
for fine-grained calculation.

The recommended usage is the technique so called "thread pool",
that you create a set of threads and keep them around for
long time and dispatch jobs to them as needed.  Gauche provides
a thread pool implementation in @code{control.thread-pool} module
(@pxref{Thread pools}).

Preemptive threads have other difficulties,
and sometimes the alternatives may be a better fit
than the native preemptive threads
(e.g. see @uref{https://www-sop.inria.fr/mimosa/rp/FairThreads/html/FairThreads.html}).

@itemize @bullet
@item
If what you need is just a concurrent calculation, you
might be able to use cooperative thread technique built
on top of @code{call/cc}.   Creating call/cc-based threads
is much faster than creating native threads.

@item
If what you need is to deal with blocking I/O, and you have
all your code at hand, it is sometimes easier to use good old
@code{select}-based dispatching (@xref{Simple dispatcher},
for example).

@item
If what you need is to control the resource consumption in the
subsystem, and the subsystem works fairly independently from
the main system, you may be able to use Unix processes instead of threads.
It may sound to go backward, but Unix process does provide
higher "shield" between the subsystem and the main system
(e.g. the main system can keep running even if subsystem segfaults).

@end itemize

Of course, these technique are not mutually exclusive with
native threads.  You can use dispatcher with "thread pool" technique,
for example.   Just keep it in your mind that the native threads
are not only but one of the ways to realize those features.

@subsubheading Uncaught errors in a thread body

When you run a single-thread program that raises an unexpected (unhandled)
error, Gauche prints an error message and a stack trace by default.
So sometimes it perplexes programmers when a thread doesn't print
anything when it dies because of an unhandled error.

What's happening is this: An unhandled error in a thread body would
cause the thread to terminate, and the error itself will propagate
to the thread who's expecting the result of the terminated thread.
So, you get the error (wrapped by @code{<uncaught-exception>})
when you call @code{thread-join!} on a thread which is terminated
because of an unhandled error.  The behavior is defined in SRFI-18.

If you fire a thread for one-shot calculation, expecting to receive
the result by @code{thread-join!}, then this is reasonable---you can
handle the error situation in the ``parent'' thread.  However,
if you run a thread to loop indefinitely to process something and
not expect to retrieve its result via @code{thread-join!}, this becomes
a pitfall; the thread may die unexpectedly but you wouldn't know it.
(If such a thread is garbage-collected, a warning is printed.
However you wouldn't know when that happens so you can't count on it.)

For such threads, you should always wrap the body of such thread
with @code{guard}, and handles the error explicitly.  You can call
@code{report-error} to display the default error message and a stack
trace.

@example
(thread-start!
 (make-thread (^[] (guard (e [else (report-error e) #f])
                     ... thread body ...))))
@end example

@xref{Thread exceptions}, for the details of thread exception handling.

Note: As of 0.9.5, Gauche has a known bug that the tail call of
error handling clauses of @code{guard} doesn't become a proper
tail call.   So, the following code, which should run safely
in Scheme, could eat up a stack:

@example
(thread-start!
 (make-thread (^[] (let loop ()
                     (guard (e [else (report-error e) (loop)])
                       ... thread body ...)))))
@end example

For the time being, you can lift the call to loop outside of
@code{guard} as workaround.

@example
(thread-start!
 (make-thread (^[] (let loop ()
                     (guard (e [else (report-error e)])
                       ... thread body ...)
                     (loop)))))
@end example


@node Thread procedures, Synchronization primitives, Thread programming tips, Threads
@subsection Thread procedures
@c NODE スレッド手続き

@deftp {Builtin Class} <thread>
@clindex thread
A thread.  Each thread has an associated thunk which is evaluated by
a POSIX thread.  When thunk returns normally, the result is stored
in the internal 'result' slot, and can be retrieved by @code{thread-join!}.
When thunk terminates abnormally, either by raising an exception or
terminated by @code{thread-terminate!}, the exception condition is
stored in their internal 'result exception' slot, and will be passed
to the thread calling @code{thread-join!} on the terminated thread.

Each thread has its own dynamic environment and dynamic handler stack.
When a thread is created, its dynamic environment is initialized by
the creator's dynamic environment.  The thread's dynamic handler
stack is initially empty.

A thread is in one of the following four states at a time.
You can query the thread state by the @code{thread-state} procedure.

@table @code
@item new
A thread hasn't started yet.  A thread returned from @code{make-thread}
is in this state.
Once a thread is started it will never be in this state again.
At this point, no POSIX thread has been created; @code{thread-start!}
creates a POSIX thread to run the Gauche thread.
@item runnable
When a thread is started by @code{thread-start!}, it becomes to this
state.   Note that a thread blocked by a system call is still in
@code{runnable} state.
@item stopped
A thread becomes in this state when it is stopped by @code{thread-stop!}.
A thread in this state can go back to @code{runnable} state by
@code{thread-cont!}, resuming execution from the point when
it is stopped.
@item terminated
When the thread finished executing associated code, or
is terminated by @code{thread-terminate!}, it becomes in this state.
Once a thread is in this state, the state can no longer be changed.
@end table

Access to the resources shared by multiple threads must be protected
explicitly by synchronization primitives.
@xref{Synchronization primitives}.

Access to ports are serialized by Gauche. If multiple threads attempt
to write to a port, their output may be interleaved but no output
will be lost, and the state of the port is kept consistent.
If multiple threads attempt to read from a port, a single read
primitive (e.g. @code{read}, @code{read-char} or @code{read-line})
works atomically.

Signal handlers are shared by all threads, but each thread has
its own signal mask.  @xref{Signals and threads}, for details.

A thread object has the following external slots.

@defivar <thread> name
A name can be associated to a thread.
This is just for the convenience of the application.
The primordial thread has the name "@code{root}".
@end defivar

@defivar <thread> specific
A thread-local slot for use of the application.
@end defivar
@end deftp

@defun current-thread
[SRFI-18], [SRFI-21]
@{@t{gauche.threads}@}
Returns the current thread.
@end defun

@defun thread? obj
[SRFI-18], [SRFI-21]
@{@t{gauche.threads}@}
Returns @code{#t} if @var{obj} is a thread, @code{#f} otherwise.
@end defun

@defun make-thread thunk :optional name
[SRFI-18], [SRFI-21]
@{@t{gauche.threads}@}
Creates and returns a new thread to execute @var{thunk}.
To run the thread, you need to call @code{thread-start!}.
The result of @var{thunk} may be retrieved by calling @var{thread-join!}.

You can provide the name of the thread by the optional argument @var{name}.

The created thread inherits the signal mask of the calling thread
(@pxref{Signals and threads}), and has a copy of
parameters of the calling thread at the time of creation
(@pxref{Parameters}).

Other than those initial setups, there will be no relationship between
the new thread and the calling thread; there's no parent-child
relationship like Unix process.   Any thread can call @code{thread-join!}
on any other thread to receive the result.  If nobody issues
@code{thread-join!} and nobody holds a
reference to the created thread, it will be garbage collected
after the execution of the thread terminates.

If a thread execution is terminated because of uncaught exception,
and its result is never retrieved by @code{thread-join!}, a warning
will be printed to the standard error port notifying
``thread dies a lonely death'':  It usually indicates some coding
error.  If you don't collect the result of threads, you have to
make sure that all the exceptions are captured and handled within @var{thunk}.

Internally, this procedure just allocates and initializes a Scheme
thread object; the POSIX thread is not created until @code{thread-start!}
is called.
@end defun

@defun thread-state thread
@{@t{gauche.threads}@}
Returns one of symbols @code{new}, @code{runnable}, @code{stopped}
or @code{terminated}, indicating the state of @var{thread}.
@end defun

@defun thread-name thread
[SRFI-18], [SRFI-21]
@{@t{gauche.threads}@}
Returns the value of @var{name} slot of @var{thread}.
@end defun

@defun thread-specific thread
@defunx thread-specific-set! thread value
[SRFI-18], [SRFI-21]
@{@t{gauche.threads}@}
Gets/sets the value of the @var{thread}'s specific slot.
@end defun

@defun thread-start! thread
[SRFI-18], [SRFI-21]
@{@t{gauche.threads}@}
Starts the @var{thread}.  It is an error if @var{thread} is already started.
Returns @var{thread}.
@end defun

@defun thread-yield!
[SRFI-18], [SRFI-21]
@{@t{gauche.threads}@}
Suspends the execution of the calling thread and yields CPU to other
waiting runnable threads, if any.
@end defun

@defun thread-sleep! timeout
[SRFI-18], [SRFI-21]
@{@t{gauche.threads}@}
Suspends the calling thread for the period specified by @var{timeout},
which must be either a @code{<time>} object (@pxref{Time}) that
specifies absolute point of time, or a real number that specifies
relative point of time from the time this procedure is called
in number of seconds.

After the specified time passes, @code{thread-sleep!} returns with
unspecified value.

If @var{timeout} points a past time, @code{thread-sleep!} returns
immediately.
@end defun

@defun thread-stop! thread :optional timeout timeout-val
@{@t{gauche.threads}@}
Stops execution of the target @var{thread} temporarily.
You can resume the execution of the @var{thread} by @code{thread-cont!}.

The stop request is handled synchronously; that is,
Gauche VM only checks the request at the ``safe'' point
of the VM and stops itself.  It means if the @var{thread} is
blocked by a system call, it won't become @code{stopped} state
until the system call returns.

By default, @code{thread-stop!} returns after the target
thread stops.  Since it may take indefinitely, you can give optional
@var{timeout} argument to specify timeout.   The @var{timeout}
argument can be @code{#f}, which means no timeout, or
a @code{<time>} object that specifies an absolute point of time,
or a real number specifying the number of seconds to wait.

The return value of @code{thread-stop!} is @var{thread} if
it could successfully stop the target, or @var{timeout-val}
if timeout reached.   When @var{timeout-val} is omitted, @code{#f}
is assumed.

If the target @var{thread} has already been stopped by the caller
thread, this procedure returns @var{thread} immediately.

When @var{thread-stop!} is timed out, the request remains
effective even after @code{thread-stop!} returns.
That is, the target thread may stop at some point in future.
The caller thread is expected to call @code{thread-stop!}
again to complete the stop operation.

An error is signaled if the target thread has already been
stopped by another thread (including the ``pending'' stop
request issued by other threads), or the target thread
is in neither @code{runnable} nor @code{stopped} state.
@end defun

@defun thread-cont! thread
@{@t{gauche.threads}@}
Resumes execution of @var{thread} which has been stopped by
@code{thread-stop!}.  An error is raised if @var{thread}
is not in stopped state, or it is stopped by another thread.

If the caller thread has already requested to stop the target
thread but timed out, calling @code{thread-cont!} cancels
the request.
@end defun

@defun thread-terminate! thread
[SRFI-18], [SRFI-21]
@{@t{gauche.threads}@}
Terminates the specified thread @var{thread}.
The @var{thread} is terminated and an instance of
@code{<terminated-thread-exception>} is stored in the result exception
field of @var{thread}.

If @var{thread} is the same as the calling thread, this procedure
won't return.  Otherwise, this procedure returns unspecified value.

This procedure should be used with care, since
@var{thread} won't have a chance to call cleanup
procedures (such as 'after' thunks of @code{dynamic-wind}).
If @var{thread} is in a critical section, it can leave some state
inconsistent.  However, once a thread is terminated, any mutex
that the thread has kept becomes 'abandoned' state, and an attempt
to lock such a mutex by other thread raises an 'abandoned mutex exception',
so that you will know the situation.  @xref{Synchronization primitives}.
@end defun


@defun thread-join! thread :optional timeout timeout-val
[SRFI-18], [SRFI-21]
@{@t{gauche.threads}@}
Waits termination of @var{thread}, or until the timeout is reached
if @var{timeout} is given.

@var{Timeout} must be either a @code{<time>} object (@pxref{Time})
that specifies absolute point of time, or a real number that specifies
relative point of time from the time this procedure is called
in number of seconds, or @code{#f} that indicates no timeout (default).

If @var{thread} terminates normally, @code{thread-join!} returns
a value which is stored in the result field of @var{thread}.
If @var{thread} terminates abnormally, @code{thread-join!} raises
an exception which is stored in the result exception field of @var{thread}.
It can be either a @code{<terminated-thread-exception>} or
@code{<uncaught-exception>}.

If the timeout is reached, @var{thread-join!} returns @var{timeout-val}
if given, or raises @code{<join-timeout-exception>}.

@xref{Thread exceptions}, for the details of these exceptions.
@end defun

@node Synchronization primitives, Thread exceptions, Thread procedures, Threads
@subsection Synchronization primitives
@c NODE 同期プリミティブ

Mutexes and condition variables are the low-level synchronization devices.
Defined in srfi-18 and srfi-21, they are portable across Scheme implementations
that supports one of those srfis.  However, in most cases you want to
use following higher-level synchronization utilities:

@table @asis
@item Atoms
An atom is a wrapper of arbitrary Scheme object, and allows synchronized
access to it somewhat like Java's @code{synchronized} blocks.  Atoms are
explained in this section.
@item MT-Queues
Thread-safe queues (@code{<mtqueue>}) are provided in @code{data.queue} module
(@pxref{Queue}), which works as a synchronized channel and
suitable to implement producer-consumer pattern. 
@end table


@subsubheading Mutex

@deftp {Builtin Class} <mutex>
@clindex mutex
@{@t{gauche.threads}@}
A primitive synchronization device.  It can take one of four states:
locked/owned, locked/not-owned, unlocked/abandoned and unlocked/not-abandoned.
A mutex can be locked (by @code{mutex-lock!}) only if it is in unlocked state.
An 'owned' mutex keeps a thread that owns it.
Typically an owner thread is the one that locked the mutex,
but you can make a thread other than the locking thread own a mutex.
A mutex becomes unlocked either by @code{mutex-unlock!} or the owner
thread terminates.  In the former case, a mutex becomes unlocked/not-abandoned
state.  In the latter case, a mutex becomes unlocked/abandoned state.

A mutex has the following external slots.

@defivar <mutex> name
The name of the mutex.
@end defivar

@defivar <mutex> state
The state of the mutex.  This is a read-only slot.
See the description of @code{mutex-state} below.
@end defivar

@defivar <mutex> specific
A slot an application can keep arbitrary data.  For example, an application
can implement a 'recursive' mutex using the specific field.
@end defivar
@end deftp

@defun mutex? obj
[SRFI-18], [SRFI-21]
@{@t{gauche.threads}@}
Returns @code{#t} if @var{obj} is a mutex, @code{#f} otherwise.
@end defun

@defun make-mutex :optional name
[SRFI-18], [SRFI-21]
@{@t{gauche.threads}@}
Creates and returns a new mutex object.
When created, the mutex is in unlocked/not-abandoned state.
Optionally, you can give a name to the mutex.
@end defun

@defun mutex-name mutex
[SRFI-18], [SRFI-21]
@{@t{gauche.threads}@}
Returns the name of the mutex.
@end defun

@defun mutex-specific mutex
@defunx mutex-specific-set! mutex value
[SRFI-18], [SRFI-21]
@{@t{gauche.threads}@}
Gets/sets the specific value of the mutex.
@end defun

@defun mutex-state mutex
[SRFI-18], [SRFI-21]
@{@t{gauche.threads}@}
Returns the state of @var{mutex}, which may be one of the followings:

@table @asis
@item a thread
The mutex is locked/owned, and the owner is the returned thread.
@item symbol @code{not-owned}
The mutex is locked/not-owned.
@item symbol @code{abandoned}
The mutex is unlocked/abandoned.
@item symbol @code{not-abandoned}
The mutex is unlocked/not-abandoned.
@end table
@end defun

@defun mutex-lock! mutex :optional timeout thread
[SRFI-18], [SRFI-21]
@{@t{gauche.threads}@}
Locks @var{mutex}.  If @var{mutex} is in unlocked/not-abandoned
state, this procedure changes its state to locked state exclusively.
By default, @var{mutex} becomes locked/owned state, owned by the
calling thread.  You can give other owner thread as @var{thread} argument.
If @var{thread} argument is given and @code{#f}, the mutex becomes
locked/not-owned state.

If @var{mutex} is in unlocked/abandoned state, that is, some other
thread has been terminated without unlocking it, this procedure
signals 'abandoned mutex exception' (@pxref{Thread exceptions})
after changing the state of @var{mutex}.

If @var{mutex} is in locked state and
@var{timeout} is omitted or @code{#f}, this procedure blocks until
@var{mutex} becomes unlocked.   If @var{timeout} is specified,
@code{mutex-lock!} returns when the specified time reaches in
case it couldn't obtain a lock.  You can give @var{timeout}
an absolute point of time (by @code{<time>} object, @pxref{Time}),
or a relative time (by a real number).

@code{Mutex-lock!} returns @code{#t} if @var{mutex} is successfully
locked, or @code{#f} if timeout reached.

Note that @var{mutex} itself doesn't implements a 'recursive lock'
feature; that is, if a thread that has locked @var{mutex} tries to lock
@var{mutex} again, the thread blocks.  It is not difficult, however,
to implement a recursive lock semantics on top of this mutex.
The following example is taken from SRFI-18 document:

@example
(define (mutex-lock-recursively! mutex)
  (if (eq? (mutex-state mutex) (current-thread))
      (let ((n (mutex-specific mutex)))
        (mutex-specific-set! mutex (+ n 1)))
      (begin
        (mutex-lock! mutex)
        (mutex-specific-set! mutex 0))))

(define (mutex-unlock-recursively! mutex)
  (let ((n (mutex-specific mutex)))
    (if (= n 0)
        (mutex-unlock! mutex)
        (mutex-specific-set! mutex (- n 1)))))
@end example
@end defun

@defun mutex-unlock! mutex :optional condition-variable timeout
[SRFI-18], [SRFI-21]
@{@t{gauche.threads}@}
Unlocks @var{mutex}.  The state of @var{mutex} becomes unlocked/not-abandoned.
It is allowed to unlock a mutex that is not owned by the calling thread.

If optional @var{condition-variable} is given, @code{mutex-unlock!}
serves the "condition variable wait" operation (e.g. @code{pthread_cond_wait}
in POSIX threads).   The current thread atomically wait on
@var{condition-variable} and unlocks @var{mutex}.
The thread will be unblocked when other thread signals on
@var{condition-variable} (see @code{condition-variable-signal!}
and @code{condition-variable-broadcast!} below), or @var{timeout}
reaches if it is supplied.  The @var{timeout} argument can be either
a @code{<time>} object to represent an absolute time point (@pxref{Time}),
a real number to represent a relative time in seconds, or @code{#f} which
means never.  The calling thread may be unblocked prematurely,
so it should reacquire the lock of @var{mutex} and checks the
condition, as in the following example (it is taken from SRFI-18 document):

@example
(let loop ()
  (mutex-lock! m)
  (if (condition-is-true?)
      (begin
        (do-something-when-condition-is-true)
        (mutex-unlock! m))
      (begin
        (mutex-unlock! m cv)
        (loop))))
@end example

The return value of @code{mutex-unlock!} is @code{#f} when it returns
because of timeout, and @code{#t} otherwise.
@end defun

@defun mutex-locker mutex
@defunx mutex-unlocker mutex
@{@t{gauche.threads}@}
Returns @code{(lambda () (mutex-lock! mutex))} and
@code{(lambda () (mutex-unlock! mutex))}, respectively.
Each closure is created at most once per @var{mutex},
thus it is lighter than using literal lambda forms in a tight loop.
@end defun


@defun with-locking-mutex mutex thunk
@{@t{gauche.threads}@}
Calls @var{thunk} with locking a mutex @var{mutex}.  This is defined as
follows.
@example
(define (with-locking-mutex mutex thunk)
  (dynamic-wind
   (mutex-locker mutex)
   thunk
   (mutex-unlocker mutex)))
@end example
@end defun

@subsubheading Condition variable

@deftp {Builtin Class} <condition-variable>
@clindex condition-variable
@{@t{gauche.threads}@}
A condition variable keeps a set of threads that are waiting for
a certain condition to be true.  When a thread modifies the state
of the concerned condition, it can call @code{condition-variable-signal!}
or @code{condition-variable-broadcast!}, which unblock one or more
waiting threads so that they can check if the condition is satisfied.

A condition variable object has the following slots.

@defivar <condition-variable> name
The name of the condition variable.
@end defivar

@defivar <condition-variable> specific
A slot an application can keep arbitrary data.
@end defivar

Note that SRFI-18 doesn't have a routine equivalent to pthreads'
@code{pthread_cont_wait}.  If you want to wait on condition variable,
you can pass a condition variable to @code{mutex-unlock!} as an
optional argument (see above), then acquire mutex again by
@code{mutex-lock!}.  This design is for flexibility; see
SRFI-18 document for the details.

This is the common usage of pthreads' condition variable:
@example
while (some_condition != TRUE) @{
  pthread_cond_wait(condition_variable, mutex);
@}
@end example
And it can be translated to SRFI-18 as follows:
@example
(let loop ()
  (unless some-condition
    (mutex-unlock! mutex condition-variable)
    (mutex-lock! mutex)
    (loop)))
@end example
@end deftp

@defun condition-variable? obj
[SRFI-18], [SRFI-21]
@{@t{gauche.threads}@}
Returns @code{#t} if @var{obj} is a condition variable,
@code{#f} otherwise.
@end defun

@defun make-condition-variable :optional name
[SRFI-18], [SRFI-21]
@{@t{gauche.threads}@}
Returns a new condition variable.  You can give its name by
optional @var{name} argument.
@end defun

@defun condition-variable-name cv
[SRFI-18], [SRFI-21]
@{@t{gauche.threads}@}
Returns the name of the condition variable.
@end defun

@defun condition-variable-specific cv
@defunx condition-variable-specific-set! cv value
[SRFI-18]、[SRFI-21]
@{@t{gauche.threads}@}
Gets/sets the specific value of the condition variable.
@end defun

@defun condition-variable-signal! cv
[SRFI-18]、[SRFI-21]
@{@t{gauche.threads}@}
If there are threads waiting on @var{cv}, causes the scheduler to select
one of them and to make it runnable.
@end defun

@defun condition-variable-broadcast! cv
[SRFI-18]、[SRFI-21]
@{@t{gauche.threads}@}
Unblocks all the threads waiting on @var{cv}.
@end defun

@subsubheading Atom

An atom is a convenient wrapper to make operations on a
given set of objects thread-safe.  Instead of defining
thread-safe counterparts of every structure, you can easily
wrap an existing data structures to make it thread-safe.

@defun atom val @dots{}
@{@t{gauche.threads}@}
Creates and returns an atom object with @var{val} @dots{} as the
initial values.
@end defun

@defun atom? obj
@{@t{gauche.threads}@}
Returns @code{#t} iff @var{obj} is an atom.
@end defun

The following procedures can be used to @emph{atomically}
access and update the content of an atom.   They commonly
take optional @var{timeout} and @var{timeout-val} arguments,
both are defaulted to @code{#f}.  In some cases, the procedure
takes more than one @var{timeout-val} arguments.
With the default value @code{#f} as @var{timeout} argument,
those procedures blocks until they acquire a lock.

The timeout arguments can be used to modify the behavior when
the lock cannot be acquired in timely manner.
@var{timeout} may be a @code{<time>} object (@pxref{Time})
to specify an absolute point of time, or a real number
to specify the relative time in seconds.  If timeout is
expired, those procedures give up acquiring the lock,
and the value given to @var{timeout-val} is returned.
In @code{atomic} and @code{atomic-update!}, you can make them return
multiple timeout values, by giving 
more than one @var{timeout-val} arguments.

@defun atom-ref atom :optional index timeout timeout-val
@{@t{gauche.threads}@}
Returns @var{index}-th value of @var{atom}.
See above for @var{timeout} and @var{timeout-val} arguments.

@example
(define a (atom 'a 'b))

(atom-ref a 0) @result{} a
(atom-ref a 1) @result{} b
@end example
@end defun

@defun atomic atom proc :optional timeout timeout-val timeout-val2 @dots{}
@{@t{gauche.threads}@}
Calls @var{proc} with the current values in @var{atom},
while locking @var{atom}.  @var{proc} must take
as many arguments as the number of values @var{atom} has.

The returned value(s) of @var{proc} is the result of
@code{atomic}, unless timeout occurs.
See above for @var{timeout} and @var{timeout-val} arguments.

For example, the @code{ref/count} procedure
in the following example counts the number of times
the hashtable is referenced in thread-safe way.

@example
(define a (atom (make-hash-table 'eq?) (list 0)))

(define (ref/count a key)
  (atomic a
   (lambda (ht count-cell)
     (inc! (car count-cell))
     (hash-table-get h key))))
@end example
@end defun

@defun atomic-update! atom proc :optional timeout timeout-val timeout-val2 @dots{}
@{@t{gauche.threads}@}
Calls @var{proc} with the current values in @var{atom}
while locking @var{atom}, and updates the values in @var{atom}
by the returned values from @var{proc}.
@var{proc} must take as many arguments as the number of
values @var{atom} has, and must return the at least the same number of
values.  If @var{proc} returns more than the number of values @var{atom}
holds, the extra values are not used to update the @var{atom}, but
is included in the return values of @code{atomic-update!}.

The returned value(s) of @code{atomic-update!} is what
@var{proc} returns, unless timeout occurs.
See above for @var{timeout} and @var{timeout-val} arguments.

The following example shows a thread-safe counter.

@example
(define a (atom 0))

(atomic-update! a (cut + 1 <>))
@end example
@end defun

Note: The term @emph{atom} in historical Lisps
meant an object that is not a cons cell (pair).  Back then
cons cells were the only aggregate datatype and there were
few other datatypes (numbers and symbols), so having a
complementary term to cells made sense.

Although it still appears in introductory Lisp tutorials,
modern Lisps, including Scheme, has so many datatypes and it makes
little sense to have a specific term for non-pair types.

Clojure adopted the term @emph{atom} for thread-safe (atomic)
primitive data, and we followed it.

Note: The constructor of atom is not @code{make-atom}
but @code{atom}, following the convention of @code{list}/@code{make-list},
@code{vector}/@code{make-vector}, and @code{string}/@code{make-string};
that is, the name without @code{make-} takes its elements as
variable number of arguments.

@node Thread exceptions,  , Synchronization primitives, Threads
@subsection Thread exceptions
@c NODE スレッド例外

Some types of exceptions may be thrown from thread-related procedures.
These exceptions can be handled by Gauche's exception mechanism
(@pxref{Exceptions}).

@deftp {Builtin Class} <thread-exception>
@clindex thread-exception
@{@t{gauche.threads}@}
A base class of thread-related exceptions.  Inherits @code{<exception>} class.
It has one slot.

@defivar <thread-exception> thread
A thread that threw this exception.
@end defivar
@end deftp

@deftp {Builtin Class} <join-timeout-exception>
@clindex join-timeout-exception
@{@t{gauche.threads}@}
An exception thrown by @code{thread-join!} when a timeout reaches
before the waited thread returns.  Inherits @code{<thread-exception>}.
@end deftp

@deftp {Builtin Class} <abandoned-mutex-exception>
@clindex abandoned-mutex-exception
@{@t{gauche.threads}@}
An exception thrown by @code{mutex-lock!} when a @var{mutex} to be
locked is in unlocked/abandoned state.  Inherits @code{<thread-exception>}.
It has one additional slot.

@defivar <abandoned-mutex-exception> mutex
A mutex that caused this exception.
@end defivar
@end deftp

@deftp {Builtin Class} <terminated-thread-exception>
@clindex terminated-thread-exception
@{@t{gauche.threads}@}
An exception thrown by @code{thread-join!} when the waited thread
is terminated abnormally (by @code{thread-terminate!}).
Inherits @code{<thread-exception>}.  It has one additional slot.

@defivar <terminated-thread-exception> terminator
A thread that terminated the thread that causes this exception.
@end defivar
@end deftp

@deftp {Builtin Class} <uncaught-exception>
@clindex uncaught-exception
@{@t{gauche.threads}@}
An exception thrown by @code{thread-join!} when the waited thread
is terminated by an uncaught exception.
Inherits @code{<thread-exception>}.  It has one additional slot.

@defivar <uncaught-exception> reason
An exception that caused the termination of the thread.
@end defivar
@end deftp

@defun join-timeout-exception? obj
@defunx abandoned-mutex-exception? obj
@defunx terminated-thread-exception? obj
@defunx uncaught-exception? obj
[SRFI-18], [SRFI-21]
@{@t{gauche.threads}@}
These procedures checks if @var{obj} is a certain type of exception.
Provided for the compatibility to SRFI-18.
@end defun

@defun uncaught-exception-reason exc
[SRFI-18], [SRFI-21]
@{@t{gauche.threads}@}
Returns the value of @code{reason} slot of @code{<uncaught-exception>}
object.
Provided for the compatibility to SRFI-18.
@end defun


@c ----------------------------------------------------------------------
@node Measure timings, Unicode utilities, Threads, Library modules - Gauche extensions
@section @code{gauche.time} - Measure timings
@c NODE 時間の計測, @code{gauche.time} - 時間の計測

@deftp {Module} gauche.time
@mdindex gauche.time
Provides three ways to measure execution time of Scheme code.
A macro @code{time}, which is convenient for interactive use,
a set of procedures for benchmarking,
and @code{<time-counter>} objects which are useful to be embedded
in the program.
@end deftp

@subheading Interactive measurement of execution time

Note: The @code{time} macro is pre-defined to autoload @code{gauche.time}
for the convenience; you don't need to say @code{(use gauche.time)}
to use the @code{time} macro.

@defmac time expr expr2 @dots{}
@{@t{gauche.time}@}
Evaluates @var{expr} @var{expr2} @dots{} sequentially, as @code{begin},
and returns the result(s) of the last expression.
Before returning the value(s), the macro reports the elapsed (real) time
and CPU times in the user space and the kernel space to the current
error port, much like the bourne shell's time command.

The current version uses @code{sys-gettimeofday} (@pxref{Time}) to
calculate the elapsed time, and @code{sys-times} (@pxref{System inquiry})
to calculate user and system CPU times.  So the resolution of these numbers
depends on these underlying system calls.  Usually the CPU
time has 10ms resolution, while the elapsed time might have higher
resolution.  On the systems that doesn't have gettimeofday(2) support,
however, the elapsed time resolution can be as bad as a second.

@smallexample
gosh> (time (length (sort (call-with-input-file "/usr/share/dict/words"
                                                port->string-list))))
;(time (length (sort (call-with-input-file "/usr/share/dict/words" port- ...
; real   0.357
; user   0.350
; sys    0.000
45427
@end smallexample
@end defmac

@subheading Benchmarking

It is not unusual that the routine you want to measure takes only
a fraction of second, so you have to run it many times for better
measurement.  It is also common that you want to compare results
of measurement of two or more implementation strategies.
Here are useful procedures to do so.

The name and behavior of those benchmarking routines are inspired
by Perl's Benchmark module.

@defun time-this how thunk
@{@t{gauche.time}@}
Calls @var{thunk} many times and measure its execution time.
The argument @var{how} can be one of the following forms.

@table @code
@item @var{integer}
It calls @var{thunk} as many times as the given number.
@item (cpu @var{real})
It calls @var{thunk} as many times as the total cpu time exceeds
the given number of seconds.
@end table

It also runs an empty loop as the same times and subtract the
time took for the empty loop from the measured time, to get
more accurate result.

The result is returned in a @code{<time-result>} record, described below.
Here are some examples:
@smallexample
;; Run the thunk 1,000,000 times
(time-this 1000000 (lambda () (expt 100 30)))
  @result{} #<time-result 1000000 times/  1.030 real/  1.040 user/  0.000 sys>

;; Run the thunk at least 5.0 cpu seconds
(time-this '(cpu 5.0) (lambda () (expt 100 30)))
  @result{} #<time-result 4903854 times/  5.090 real/  5.050 user/  0.010 sys>
@end smallexample
@end defun

@deftp {Record} <time-result>
@{@t{gauche.time}@}
A record to hold the benchmark result.
Following slots are defined.

@defivar {<time-result>} count
@fnindex time-result-count
The number of times the thunk was run.   This slot is also
accessed by a procedure @code{time-result-count}.
@end defivar

@defivar {<time-result>} real
@fnindex time-result-real
The total real (elapsed) time running the thunk took.
This slot is also accessed by a procedure @code{time-result-real}.
@end defivar

@defivar {<time-result>} user
@fnindex time-result-user
The total user cpu time running the thunk took.
This slot is also accessed by a procedure @code{time-result-user}.
@end defivar

@defivar {<time-result>} sys
@fnindex time-result-sys
The total system cpu time running the thunk took.
This slot is also accessed by a procedure @code{time-result-sys}.
@end defivar
@end deftp

@defun make-time-result count real user sys
@{@t{gauche.time}@}
The constructor of @code{<time-result>} records.
@end defun

@defun time-result? obj
@{@t{gauche.time}@}
The predicate of @code{<time-result>} records.
@end defun

@defun time-result+ t1 t2 :key (with-count #f)
@defunx time-result- t1 t2 :key (with-count #f)
@{@t{gauche.time}@}
Add or subtract two @code{<time-result>} records and returns a new record.

If @var{with-count} is false,
only the real, user and sys slots are added or subtracted,
and the result's count slot is set to the same as @var{t1}'s count slot.
It is supposed to be used to calculate on measurement
from different chunk of code.

If @var{with-count} is true,
then the values of count slot is also added or subtracted.
It is supposed to calculate on
multiple benchmark results of the same code.
@end defun

@defun time-these how alist
@defunx time-these/report how alist
@{@t{gauche.time}@}
These procedures benchmarks multiple chunks of code to compare.

The @var{alist} argument must be the form of
@code{((key . thunk) @dots{})}, where @code{key} is a symbol
and @var{thunk} is a procedure taking no arguments.

The @var{how} argument is the same as @code{time-this}; that is,
either an integer for number of iterations, or a list
@code{(cpu @var{x})} to indicate @var{x} seconds of cpu time.

@code{time-these} runs benchmarks for each thunk in @var{alist}
using @code{time-this}, and returns the result in a list of
the form
@code{(@var{how} (@var{key1} . @var{result1}) (@var{key2} . @var{result2}) @dots{})},
where each @var{result} is a @code{<time-result>} object.

@code{time-these/report} outputs the benchmark results and
comparison matrix in human readable way to the current output port.

@smallexample
gosh> (time-these/report '(cpu 3.0)
        `((real1 . ,(cut expt 100 20))
          (real2 . ,(cut %expt 100 20))
          (imag  . ,(cut expt +100i 20))))
Benchmark: ran real1, real2, imag, each for at least 3.0 cpu seconds.
  real1: 3.312 real, 3.320 cpu (3.320 user + 0.000 sys)@@ 1694277.11/s n=5625000
  real2: 2.996 real, 3.010 cpu (3.010 user + 0.000 sys)@@35595634.55/s n=107142860
   imag: 3.213 real, 3.190 cpu (3.190 user + 0.000 sys)@@  862068.97/s n=2750000

              Rate  real1 real2   imag
  real1  1694277/s     -- 0.048  1.965
  real2 35595635/s 21.009    -- 41.291
   imag   862069/s  0.509 0.024     --
@end smallexample

The first part of the report shows, for each thunks,
the real (elapsed) time,
the cpu time used (and its breakdown of user and system time),
the rate of iteration per second, and the total number of iterations.

The second part compares the speed between each pair of the benchmarks.
For example, its first row tells that the benchmark @code{real1} is
0.048 times faster than @code{real2} and 1.965 times faster than
@code{imag}.
@end defun

@defun report-time-results result
@{@t{gauche.time}@}
This is a utility procedure to create a report from
the result of @code{time-these}.  Actually, @code{time-these/report}
is just a combination of @code{time-these} and this procedure:

@example
(define (time-these/report how samples)
  (report-time-results (time-these how samples)))
@end example
@end defun


@subheading Finer measurement

@deftp {Class} <time-counter>
@clindex time-counter
@{@t{gauche.time}@}
An abstract class of time counters.  Time counter is a kind of timer
whose value is incremented as the time passes.  The counting
can be started and stopped any number of times.
The value of the counter can be read
when the timer is stopping.
You can have multiple time counters.  It is useful, for example,
to measure the time in two parts inside a loop independently.

The concrete subclass determines which time it is counting.
You have to instantiate one of those subclasses described below
to use the time counter.
@end deftp

@deftp {Class} <real-time-counter>
@deftpx {Class} <user-time-counter>
@deftpx {Class} <system-time-counter>
@deftpx {Class} <process-time-counter>
@clindex real-time-counter
@clindex user-time-counter
@clindex system-time-counter
@clindex process-time-counter
@{@t{gauche.time}@}
Classes for time counters that count real (elapsed) time, user-space CPU time,
kernel-space CPU time, and total CPU time (user + system), respectively.
@end deftp

@deffn {Method} time-counter-start! (counter <time-counter>)
@deffnx {Method} time-counter-stop! (counter <time-counter>)
@{@t{gauche.time}@}
Starts and stops the @var{counter}.  The time during the counter is
running is accumulated to the counter value when the counter is stopped.

Start/stop pairs can be nested,
but only the outermost pair takes the effect.  That is, if you call
@code{time-counter-start!} on the counter that is already started,
it doesn't have any effect except that to stop such a counter
you have to call @code{time-counter-stop!} one more time.  It is useful
when you want to measure the time spent in the larger block that
may already contain timer start/stop pairs.

Calling @code{time-counter-stop!} on the already stopped counter
has no effect.
@end deffn

@deffn {Method} time-counter-reset! (counter <time-counter>)
@{@t{gauche.time}@}
Resets the value of @var{counter}.  If @var{counter} is already
running, it is forced to stop before being reset.
@end deffn

@deffn {Method} time-counter-value (counter <time-counter>)
@{@t{gauche.time}@}
Returns the current value of the counter as the number of seconds,
in a real number.  The resolution depends on the source of the counter.
@end deffn

@defmac with-time-counter counter expr @dots{}
@{@t{gauche.time}@}
A convenience macro to run the @var{counter} while @var{expr} @dots{}
are evaluated.  Returns the result(s) of the last expression.
It is defined as follows.
@example
(define-syntax with-time-counter
  (syntax-rules ()
    ((_ counter . exprs)
     (dynamic-wind
      (lambda () (time-counter-start! counter))
      (lambda () . exprs)
      (lambda () (time-counter-stop! counter))))
    ))
@end example
@end defmac

The following example measures approximate times
spend in process-A and process-B inside a loop.

@example
(let ((ta (make <real-time-counter>))
      (tb (make <real-time-counter>)))
  (dotimes (i 100000)
    (with-time-counter ta
      (process-A))
    (with-time-counter tb
      (process-B)))
  (format #t "Time spent in process-A: ~s\n" (time-counter-value ta))
  (format #t "Time spent in process-B: ~s\n" (time-counter-value tb))
  )
@end example

@c ----------------------------------------------------------------------
@node Unicode utilities, Uniform vector library, Measure timings, Library modules - Gauche extensions
@section @code{gauche.unicode} - Unicode utilities
@c NODE Unicodeユーティリティ, @code{gauche.unicode} - Unicodeユーティリティ

@deftp {Module} gauche.unicode
@mdindex gauche.unicode
This module provides various operations on a sequence of Unicode codepoints.

Gauche can be compiled with a native encoding other than Unicode,
and the full Unicode-compatible behavior on characters and strings may
not be available on such systems.  So we provide most operations in two
flavors: Operations on characters and strings, or operations on
codepoints represented as a sequence of integers.

If Gauche is compiled with its native encoding being @code{none},
@code{euc-jp} or @code{sjis}, character-and-string operations
are likely to be partial functions of the operations defined
in Unicode standard.  That is, if the operation can yield a
character that are not supported in the native encoding, it
may be remapped to an alternative character.  Each manual entry
explains the detailed behavior.

The codepoint operations are independent from Gauche's native
encoding and supports full spec as defined in Unicode standard.
If Gauche is compiled with the @code{utf-8} native encoding,
the operations are essentially the same as character-and-string flavors
when you convert codepoints and characters by @code{char->integer} and
@code{integer->char}.  The codepoint operations are handy when
you need to support the algorithms described in Unicode standard
fully, no matter what the running Gauche's native encoding is.
@end deftp

@menu
* Unicode transfer encodings::
* Unicode text segmentation::
* Full string case conversion::
* East asian width property::
@end menu

@node Unicode transfer encodings, Unicode text segmentation, Unicode utilities, Unicode utilities
@subsection Unicode transfer encodings

The procedures in this group operate on codepoints represented as integers.
In the following descriptions, an octet refers to an integer
between 0 to 255, inclusive.

They take optional @var{strictness} argument.  It specifies
what to do when the procedure encounters a datum outside
of the defined domain.  Its value can be either one of the
following symbols:

@table @code
@item strict
Raises an error when the procedure encounters such input.
This is the default behavior.
@item permissive
Whenever possible, treat the date as if it is a valid value.
For example, codepoint value beyond @code{#x10ffff} is invalid
in Unicode standard, but it may be useful for some other purpose
that just want to use UTF-8 as an encoding scheme of binary data.
@item replace
If the procedure sees invalid input, replaces it with a unicode
replacement character @code{U+FFFD} and proceed.
@item ignore
Whenver possible, treat the invalid input as if they do not exist.
@end table

The procedure may still raise an error in @code{permissive}, @code{replace} or
@code{ignore} strictness mode, if there can't be a sensible
way to handle the input data.

@defun ucs4->utf8 codepoint :optional strictness
@{@t{gauche.unicode}@}
Takes an integer codepoint and returns a list of octets that
encodes the input in UTF-8.

@example
(ucs4->utf8 #x3bb)  @result{} (206 187)
(ucs4->utf8 #x3042) @result{} (227 129 130)
@end example

If @var{strictness} is @code{strict} (default), input codepoint
between @code{#xd800} to @code{#xdfff}, and beyond @code{#x110000},
are rejected. If @var{strictness} is @code{replace}, such input
yields a utf8 sequence @code{#xef, #xbf, #xbd}, which encodes
@code{U+FFFD}.
If @var{strictness} is @code{permissive}, it accepts
input between @code{0} and @code{#x7fffffff}, inclusive; it may produce
5 or 6 octets if the input is large (as the original UTF-8 definition).
If @var{strictness} is @code{ignore}, it returns an empty list
for invalid codepoints.
@end defun

@defun utf8-length octet :optional strictness
@{@t{gauche.unicode}@}
Takes @var{octet} as the first octet of UTF-8 sequence, and
returns the number of total octets required to decode
the codepoint.

If @var{octet} is not an exact integer between 0 and 255 (inclusive),
an error is thrown, regardless of @var{strictness} argument.

If @var{strictness} is @code{strict} (default), this
procedure returns either 1, 2, 3 or 4.   An error is
thrown if @var{octet} cannot be a leading octet of
a proper UTF-8 encoded Unicode codepoint.

If @var{strictness} is @code{permissive} or @code{replace}, this procedure
may return an integer between 0 and 6, inclusive.
If the input is from @code{#xf8} to @code{#xfd}, inclusive,
this returns 5 or 6, according to the original utf-8 spec
(these values corresponds to the codepoint 
range @code{#x110000} to
@code{#x7fffffff}).
If the input is in the range between @code{#x80}
and @code{#xbf}, inclusive, or @var{#xfe} or @code{#xff},
this procedure returns 1--it's up to the application how to treat these illegal
octets.

If @var{strictness} is @code{ignore}, this procedure
returns @code{0} when it would raise an error if
@var{strictness} is @code{strict}.  Other than that,
it works the same as the default case.
@end defun

@defun utf8->ucs4 octet-list :optional strictness
@{@t{gauche.unicode}@}
Takes a list of octets, and decodes it as a utf-8 sequence.
Returns two values: The decoded ucs4 codepoint, and the
rest of the input list.

If it finds a value other than exact integer
between 0 and 255 in the input list, an error is thrown
regardless of the value of @var{strictness}.

An invalid utf8 sequence causes an error if @var{strictness}
is @code{strict}, or skipped if it is @code{ignore}.
If @var{strictness} is @code{replace}, such utf8 sequence
yields @code{U+FFFD}.
If @var{strictness} is @code{permissive}, the procedure accepts
the original utf-8 sequence which can produce surrogated pair
range (between @code{#xd800} and @code{#dfff}) and the range
between @code{#x110000} to @code{#x7fffffff}.  The invalid
octet sequence is still an error with @code{permissive} mode.
@end defun

@defun utf8->string u8vector :optional start end
[R7RS base]
@{@t{gauche.unicode}@}
Converts a sequence of utf8 octets in @var{u8vector} to a string.
Optional @var{start} and/or @var{end} argument(s) will limit the
range of the input.

If Gauche's native encoding is utf8, this procedure first tries
@code{u8vector->string} (@pxref{Uvector conversion operations}).
If the input utf8 sequence is valid, this is the fastest way.
If the input contains invalid utf8 sequence, the procedure falls
back to construct a string by one character at at time, 
replacing invalid sequence with Unicode replacement character @code{U+FFFD}.
Hence it always returns a complete string.
To know if the input contains invalid utf8 sequence, you can use
@code{u8vector->string} directly.

If Gauche's native encoding is other than utf8,
there's no @code{U+FFFD} so invalid utf8 sequence throws an error.
@end defun

@defun string->utf8 string :optional start end
[R7RS base]
@{@t{gauche.unicode}@}
Converts a string to a u8vector of utf8 octets.
Optional @var{start} and/or @var{end} argument(s) will limit the
range of the input.

If Gauche's native encoding is utf8, this procedure
just calls @code{string->u8vector} (@pxref{Uvector conversion operations}).
Otherwise, it first converts the input string to utf-8, then
@code{string->u8vector} is called.
@end defun

@defun ucs4->utf16 codepoint :optional strictness
@{@t{gauche.unicode}@}
Takes an integer codepoint and returns a list of integers
that encodes the input in UTF-16.

If @var{strictness} is @code{strict} (default),
the input must be either
between @code{0} and @code{#xd7ff} or between @code{#xe000} and
@code{#x10ffff}.  An error is thrown otherwise.  The 'hole' is the
codepoint reserved for surrogates, and there's no valid
mapping from them to utf-16 is defined.

If @var{strictness} is @code{replace}, such input is replaced
with @code{#xfffd}, which encodes Unicode replacement character.

If @var{strictness} is @code{permissive}, it accepts
high surrogates and low surrogates, in which case the result is
single element list of input.  An error is still thrown for
negative input and input greater than or equal to @code{#x110000}.

If @var{strictness} is @code{ignore},
an empty list is returned for an invalid codepoint (including surrogates).

Note: We can encode values larger than @code{#x10ffff} in utf-8
in the permissive mode, but not in utf-16.
@end defun

@defun utf16-length code :optional strictness
@{@t{gauche.unicode}@}
@var{Code} must be an exact integer between 0 and 65535, inclusive.
Returns 1 if @var{code} is BMP character codepoint, or
2 if @var{code} is a high surrogate.

If @var{strictness} is @code{strict} (default), an error is
signalled if @var{code} is a low surrogate, or it is out of range.
If @var{strictness} is @code{permissive} or @code{replace}, 1 is returned
for low surrogates, but an error is signalled for out of range arguments.
If @var{strictness} is @code{ignore}, 0 is returned
for low surrogates and out of range arguments.
@end defun

@defun utf16->ucs4 code-list :optional strictness
@{@t{gauche.unicode}@}
Takes a list of exact integers and decodes it as a utf-16 sequence.
Returns two values: The decoded ucs4 codepoint, and the rest of
input list.

If @var{strictness} is @code{strict} (default), an invalid utf-16
sequence and out-of-range integer raise an error.  If @var{strictness}
is @code{permissive}, an out-of-range integer causes an error, but
a lone surrogate is allowed and returned as is.  
If @var{strictness} is @code{replace}, a lone surrogate is
replaced with @code{U+FFFD}.
If @var{strictness}
is @code{ignore}, lone surrogates and out-of-range integers are just
ignored.
@end defun


@defun utf16->string u8vector :optional endian ignore-bom? start end
@defunx utf32->string u8vector :optional endian ignore-bom? start end
@{@t{guache.unicode}@}
[R7RS scheme.bytevector]
Convert utf16 and utf32 sequence stored in @var{u8vector} to a string,
respectively.
For @code{utf16->string}, 
if the input contains invlaid utf16 sequence (unpaired surrogate),
it is replaced with Unicode replacement character @code{U+FFFD}.
If the number of input octet is not the multiple of unit (2 octets
for utf16, and 4 octets for utf32), an error is thrown.

The optional @var{endian} and @var{ignore-bom?} arguments
determines whether the input is in UTF16BE/UTF32BE or UTF16LE/UTF32LE.
If @var{ignore-bom?} is @code{#f} or omitted, the first two octets
of input is examined; if it's BOM, it deterimines the endianness
regardless of @var{endian} argument,
and the BOM won't be included in the output.
If the input does not begin with BOM, or @var{ignore-bom?} is true,
then the endianness is determined by @var{endian} argument: It can be
@code{big-endian} or @code{big} for UTF16BE/UTF32BE, and
@code{little-endian} or @code{little} or @code{arm-big-endian}
for UTF16LE/UTF32LE (@pxref{Endianness}, for the details of endianness).

Note that if @var{ignore-bom?} is given and true,
the initial BOM is interpreted as a codepoint @code{U+FEFF}.
If @var{endian} is @code{#f} or omitted, UTF16BE/UTF32BE
is assumed (it is defined so in R7RS @code{scheme.bytevector}).

In R7RS @code{scheme.bytevector}, @var{ignore-bom?} argument
is called @var{endianness-mandatory}.  The behavior is the same.

Optinoal argument @var{start} and @var{end} trims the input octet sequence
before other processing (including BOM detection).  These arguments are
Gauche's extension, and not the part of R7RS @code{scheme.bytevector}.
@end defun

@defun string->utf16 str :optional endian add-bom? start end
@defunx string->utf32 str :optional endian add-bom? start end
@{@t{gauche.unicode}@}
[R7RS scheme.bytevector]
Encode a string @var{str} to utf-16 and utf-32 sequences stored in a u8vector,
respectively.

The optional @var{endian} argument specifies whether the encoding
is UTF16BE/UTF32BE or UTF16LE/UTF32LE.  If it is a symobl @code{big-endian} or
@code{big}, the encoding is UTF16BE/UTF32BE.  If it is a symbol
@code{little-endian}, @code{little} or @code{arm-little-endian},
the encoding is UTF16LE/UTF32LE.
@xref{Endianness}, for the details of endianness.
If it is omitted or @code{#f}, UTF16BE/UTF32BE is assumed.

The second optional argument @var{add-bom?} specifies, if true value is
given, the output contains BOM.  When omitted BOM won't be added.

The @var{start} and @var{end} arguments limits the range of @var{str}
to be converted.

R7RS @code{scheme.bytevector} only defines @var{endian} optional
argument.  The rest is Gauche's extension.
@end defun



@node Unicode text segmentation, Full string case conversion, Unicode transfer encodings, Unicode utilities
@subsection Unicode text segmentation

These procedures implements grapheme-cluster and
word breaking algorithms defined in UAX #29: Unicode Text Segmentation.

@defun string->words string
@defunx codepoints->words sequence
@{@t{gauche.unicode}@}
From given string or codepoint sequence (a @code{<sequence>}
object containing codepoints), returns a list of
words.  Each word is represented as a string, or
a sequence of the same type as input, respectively.

@example
(string->words "That's it.")
 @result{} ("That's" " " "it" ".")
(codepoints->words '(84 104 97 116 39 115 32 105 116 46)
 @result{} ((84 104 97 116 39 115) (32) (105 116) (46))
(codepoints->words '#(84 104 97 116 39 115 32 105 116 46)
 @result{} (#(84 104 97 116 39 115) #(32) #(105 116) #(46))
@end example

In the second and third example, the input is a sequence of codepoints
of characters in "That's it."
@end defun


@defun string->grapheme-clusters string
@defunx codepoints->grapheme-clusters sequence
@{@t{gauche.unicode}@}
From given string or codepoint sequence (a @code{<sequence>}
object containing codepoints), returns a list of
grapheme clusters.  Each cluster is represented as a string,
or a sequence of the same type as input, respectively.
@end defun

The following procedures are low-level building blocks
to build the above @code{string->words} etc.

@defun make-word-breaker generator
@defunx make-grapheme-cluster-breaker generator
@{@t{gauche.unicode}@}
From given @var{generator}, which is a generator of characters or codepoints,
returns a generator that returns two values: The first value is the
character or codepoint generated from the original generator, and the
second value is a boolean flag, which is @code{#t} if a word
or a grapheme cluster
breaks before the character/codepoint, and @code{#f} otherwise.

Suppose a generator @var{g} returns characters in a string
@code{That's it.}, one at a time.  Then the created generator
will work as follows:

@example
(define brk (make-word-breaker g))
(brk)  @result{}  #\T     and #t
(brk)  @result{}  #\h     and #f
(brk)  @result{}  #\a     and #f
(brk)  @result{}  #\t     and #f
(brk)  @result{}  #\'     and #f
(brk)  @result{}  #\s     and #f
(brk)  @result{}  #\space and #t
(brk)  @result{}  #\i     and #t
(brk)  @result{}  #\t     and #f
(brk)  @result{}  #\.     and #t
(brk)  @result{}  #<eof>  and #t
@end example

It shows the word breaks at those character boundaries shown
by the caret @code{^} below (for clearity, I use @code{_} to indicate
the space).

@example
  T h a t ' s _ i t .
 ^           ^ ^   ^ ^
@end example
@end defun

@defun make-word-reader generator return
@defunx make-grapheme-cluster-reader generator return
@{@t{gauche.unicode}@}
The input @var{generator} is a generator of characters or codepoints,
and @var{return} is a procedure that takes a list of characters or
codepoints, and returns an object.   These procedures creates a
generator that returns an object at at time, each consists of a
word or a grapheme cluster, respectively.

Suppose a generator @var{g} returns characters in a string
@code{That's it.}, one at a time, again.
Then the created generator works as follows:

@example
(define brk (make-word-reader g list->string))
(brk)  @result{}  "That's"
(brk)  @result{}  " "
(brk)  @result{}  "it"
(brk)  @result{}  "."
(brk)  @result{}  #<eof>
@end example

@end defun


@node Full string case conversion, East asian width property, Unicode text segmentation, Unicode utilities
@subsection Full string case conversion
@c NODE フルセットの大文字小文字変換

@defun string-upcase string
@defunx string-downcase string
@defunx string-titlecase string
@defunx string-foldcase string
[R6RS][R7RS char]
@{@t{gauche.unicode}@}
Converts the case of given @var{string}
using language-independent full case folding defined by Unicode standard.
They differ from srfi-13's procedures
with the same names (@pxref{SRFI-13 String case mapping}),
which simply uses character-by-character case mapping.
Notably, the length of resulting string may differ from the source string,
and some conversions are sensitive to whether the character is at the
word boundary or not.  The word boundaries are determined according
to UAX #29 text segmentation rules.

@example
(string-upcase "straße")
 @result{} "STRASSE"
(string-downcase "ΧΑΟΣΧΑΟΣ.ΧΑΟΣ. Σ.")
 @result{} "χαοσχαοσ.χαος. σ."
(string-titlecase "You're talking about R6RS, right?")
 @result{} "You're Talking About R6rs, Right?"
(string-foldcase "straße")
 @result{} "strasse"
(string-foldcase "ΧΑΟΣΣ")
 @result{} "χαοσσ"
@end example

Note that @code{string-titlecase} isn't included in R7RS @code{scheme.char}
module.
@end defun

@defun codepoints-upcase sequence
@defunx codepoints-downcase sequence
@defunx codepoints-titlecase sequence
@defunx codepoints-foldcase sequence
@{@t{gauche.unicode}@}
Like @code{string-upcase} etc, but these work on a sequence of
codepoints instead.  Returns a sequence of the same type of the input.

@example
(codepoints-upcase '#(115 116 114 97 223 101))
 @result{} #(83 84 82 65 83 83 69)
@end example
@end defun

@defun string-ci=? string1 string2 string3 @dots{}
@defunx string-ci<? string1 string2 string3 @dots{}
@defunx string-ci<=? string1 string2 string3 @dots{}
@defunx string-ci>? string1 string2 string3 @dots{}
@defunx string-ci>=? string1 string2 string3 @dots{}
[R7RS char]
@{@t{gauche.unicode}@}
Case-insensitive string comparison, using full-string case conversion.

Note that Gauche has builtin @code{string-ci=?} etc., which use
character-wise case folding (@pxref{String comparison}).  These are
different procedures.

@example
(string-ci=? "\u00df" "SS") @result{} #t
@end example
@end defun

@node East asian width property,  , Full string case conversion, Unicode utilities
@subsection East asian width property

@defun char-east-asian-width char-or-codepoint
@{@t{gauche.unicode}@}
The argument may be a character or a nonnegative integer of Unicode
codepoint.  Returns one of the symbols @code{N} (neutral), 
@code{F} (fullwidth), @code{H} (halfwidth), @code{W} (wide),
@code{Na} (narrow), and @code{A} (ambiguous).

The meaning of this property is explained in Unicode standard annex #11,
@url{http://unicode.org/reports/tr11/}.
@end defun


@c ----------------------------------------------------------------------
@node Uniform vector library, Comparing version numbers, Unicode utilities, Library modules - Gauche extensions
@section @code{gauche.uvector} - Uniform vector library
@c NODE ユニフォームベクタライブラリ, @code{gauche.uvector} - ユニフォームベクタライブラリ

@deftp {Module} gauche.uvector
@mdindex gauche.uvector
Provides procedures that work on uniform vectors
(@pxref{Uniform vectors}).
This module is a superset of R7RS uniform vector library
(@code{scheme.vector.@@}) and srfi-4.

The @code{@@} part is actually one of @code{u8}, @code{s8}, @code{u16},
@code{s16}, @code{u32}, @code{s32}, @code{u64}, @code{s64},
@code{f16}, @code{f32}, @code{f64}, @code{c32}, @code{c64} or @code{c128}.

@end deftp

Gauche's extension to srfi-160 is as follows:
@itemize @bullet
@item
Support of @code{f16vector} and @code{c32vector}, using 16-bit floating 
point numbers as used in high-dynamic range image format.
@item
Efficient element-wise arithmetic procedures, e.g. @code{@@vector-add}.
@item
Implements the collection framework (@pxref{Collection framework})
and the sequence framework (@pxref{Sequence framework}).  So the
methods like @code{map}, @code{for-each}, @code{ref} or @code{subseq}
can be used.
@item
Some routines takes optional parameters: @code{@@vector-ref}
takes optional fallback value.
@end itemize

When you try to store a number out of the range of the vector type,
an error is signaled by default.  However, some procedures take
an optional argument @var{clamp} that specifies alternative behavior
in such a case.  @var{Clamp} argument may take one of the following values.
@table @code
@item #f
Default behavior (signals an error).
@item high
Clamps high bound; i.e. if the value to be stored is beyond the higher bound
of the range, the maximum value is stored instead.
@item low
Clamps low bound; i.e. if the value to be stored is below the lower bound
of the range, the minimum value is stored instead.
@item both
Clamps both sides; does both @code{high} and @code{low}.
@end table

@example
(list->u8vector '(-1))         @result{} @r{error}
(list->u8vector '(-1) 'low)    @result{} #u8(0)
(list->u8vector '(-1) 'high)   @result{} @r{error}
(list->u8vector '(3000) 'high) @result{} #u8(255)
(list->u8vector '(-100 20 300) 'both) @result{} #u8(0 20 255)
@end example

In the following description, @code{@@} can be replaced
for any of @code{s8}, @code{u8}, @code{s16}, @code{u16},
@code{s32}, @code{u32}, @code{s64}, @code{u64},
@code{f16}, @code{f32}, @code{f64}, @code{c32}, @code{c64} or @code{c128}.

Note: R7RS-large provides separate library for each type,
and you should import them individually, for example,
@code{(use scheme.vector.u8)} (Gauche way) or
@code{(import (scheme vector u8))} (R7RS way).

On the other hand, using @code{gauche.uvector} imports all the bindings.

@menu
* Uvector basic operations::
* Uvector conversion operations::
* Uvector numeric operations::
* Uvector block I/O::
* Bytevector compatibility::
@end menu

@node Uvector basic operations, Uvector conversion operations, Uniform vector library, Uniform vector library
@subsection Uvector basic operations
@c NODE ユニフォームベクタの基本操作

The following procedures are built-in; @pxref{Uniform vectors}:

@example
uvector?          @@vector?
uvector-ref       @@vector-ref
uvector-set!      @@vector-set!
uvector-length
@end example

@deffn {Function} @@? obj
@findex s8?
@findex u8?
@findex s16?
@findex u16?
@findex s32?
@findex u32?
@findex s64?
@findex u64?
@findex f16?
@findex f32?
@findex f64?
@findex c32?
@findex c64?
@findex c128?
[R7RS vector.@@]
@{@t{gauche.uvector}@}
Returns @code{#t} iff @var{obj} can be an element of @code{@@vector}.
@end deffn

@deffn {Function} @@vector-empty? obj
@findex u8vector-empty?
@findex s8vector-empty?
@findex u16vector-empty?
@findex s16vector-empty?
@findex u32vector-empty?
@findex s32vector-empty?
@findex u64vector-empty?
@findex s64vector-empty?
@findex f16vector-empty?
@findex f32vector-empty?
@findex f64vector-empty?
@findex c32vector-empty?
@findex c64vector-empty?
@findex c128vector-empty?
[R7RS vector.@@]
@{@t{gauche.uvector}@}
The argument must be a @@vector.
Returns @code{#t} iff it is empty.
@end deffn

@deffn {Function} @@vector x @dots{}
@findex s8vector
@findex u8vector
@findex s16vector
@findex u16vector
@findex s32vector
@findex u32vector
@findex s64vector
@findex u64vector
@findex f16vector
@findex f32vector
@findex f64vector
@findex c32vector
@findex c64vector
@findex c128vector
[R7RS vector.@@]
@{@t{gauche.uvector}@}
Constructs @@vector whose elements are numbers @var{x} @dots{}.
The numbers must be exact integer for exact integer vectors,
and in the valid range of the vector.
@example
(s8vector 1 2 3) @result{} #s8(1 2 3)
@end example
@end deffn


@deffn {Function} make-@@vector len :optional fill
@findex make-s8vector
@findex make-u8vector
@findex make-s16vector
@findex make-u16vector
@findex make-s32vector
@findex make-u32vector
@findex make-s64vector
@findex make-u64vector
@findex make-f16vector
@findex make-f32vector
@findex make-f64vector
@findex make-c32vector
@findex make-c64vector
@findex make-c128vector
[R7RS vector.@@]
@{@t{gauche.uvector}@}
Constructs a @@vector of length @var{len}.  The elements are
initialized by a number @var{fill}.   For exact integer vectors,
@var{fill} must be an exact integer and in the valid range.
If @var{fill} is omitted, the content of the vector is undefined.
@example
(make-u8vector 4 0) @result{} #u8(0 0 0 0)
@end example
@end deffn

@defun make-uvector @code{class} @code{len} :optional @code{fill}
@{@t{gauche.uvector}@}
This is a Gauche extension; instead of using separate constructor for
each uvector type, you can pass the class of desired uvector.

@example
(make-uvector <u8vector> 3)    @result{} #u8(0 0 0)
(make-uvector <s8vector> 5 -1) @result{} #s8(-1 -1 -1 -1 -1)
@end example
@end defun

@deffn {Function} @@vector-unfold f len seed
@deffnx {Function} @@vector-unfold-right f len seed
@findex u8vector-unfold
@findex s8vector-unfold
@findex u16vector-unfold
@findex s16vector-unfold
@findex u32vector-unfold
@findex s32vector-unfold
@findex u64vector-unfold
@findex s64vector-unfold
@findex f16vector-unfold
@findex f32vector-unfold
@findex f64vector-unfold
@findex c32vector-unfold
@findex c64vector-unfold
@findex c128vector-unfold
@findex u8vector-unfold-right
@findex s8vector-unfold-right
@findex u16vector-unfold-right
@findex s16vector-unfold-right
@findex u32vector-unfold-right
@findex s32vector-unfold-right
@findex u64vector-unfold-right
@findex s64vector-unfold-right
@findex f16vector-unfold-right
@findex f32vector-unfold-right
@findex f64vector-unfold-right
@findex c32vector-unfold-right
@findex c64vector-unfold-right
@findex c128vector-unfold-right
@{@t{gauche.uvector}@}
Construct a @@vector of length @var{len}, with each element
as a result of @code{(f seed)}, @code{(f (f seed))},
@code{(f (f (f seed)))}, @dots{}.
@@vector-unfold fills the element from left to right,
while @@vector-unfold-right from right to left.
@example
(u8vector-unfold (cut + 2 <>) 5 0)
 @result{} #u8(2 4 6 8 10)
(u8vector-unfold-right (pa$ + 2) 5 0)
 @result{} #u8(10 8 6 4 2)
@end example
@end deffn


@deffn {Function} @@vector-length vec
@findex u8vector-length
@findex s8vector-length
@findex u16vector-length
@findex s16vector-length
@findex u32vector-length
@findex s32vector-length
@findex u64vector-length
@findex s64vector-length
@findex f16vector-length
@findex f32vector-length
@findex f64vector-length
@findex c32vector-length
@findex c64vector-length
@findex c128vector-length
[R7RS vector.@@]
@{@t{gauche.uvector}@}
Returns the length of the @@vector @var{vec}.

Note that the generic function @code{size-of} can be used
to obtain the length of @var{vec} as well,
if you import @code{gauche.collection}
(@pxref{Collection framework}).
@example
(s16vector-length '#s16(111 222 333)) @result{} 3

(use gauche.collection)
(size-of '#s16(111 222 333)) @result{} 3
@end example
@end deffn

@defun uvector-size uvector :optional start end
@{@t{gauche.uvector}@}
This function can be applied to any type of uniform vectors, and
returns the raw size of the @var{uvector} in number of octets.

When @var{start} and/or @var{end} is/are given, the size of data
between those indices are calculated.  The special value @code{-1}
for @var{end} indicates the end of the vector.
The returned value matches the number of octets to be written out
by @code{(write-uvector @var{uvector} port @var{start} @var{end})}.

(Do not confuse this with @code{uvector-length}, which returns
the number of elements.)

@example
(uvector-size '#u8(1 2 3))        @result{} 3
(uvector-size '#u64(1 2 3))       @result{} 24

(uvector-size '#u32(0 1 2 3) 2)   @result{} 8
(uvector-size '#u32(0 1 2 3) 0 1) @result{} 4
@end example
@end defun

@defun uvector-class-element-size class
@{@t{gauche.uvector}@}
Returns the size of an element of a uvector of the given class, in bytes.
An error is raised when @var{class} is not a uvector class.

@example
(uvector-class-element-size <u8vector>)  @result{} 1
(uvector-class-element-size <s64vector>) @result{} 8
@end example
@end defun

@deffn {Function} @@vector-swap! vec i j
@findex u8vector-swap!
@findex s8vector-swap!
@findex u16vector-swap!
@findex s16vector-swap!
@findex u32vector-swap!
@findex s32vector-swap!
@findex u64vector-swap!
@findex s64vector-swap!
@findex f16vector-swap!
@findex f32vector-swap!
@findex f64vector-swap!
@findex c32vector-swap!
@findex c64vector-swap!
@findex c128vector-swap!
[R7RS vector.@@]
@{@t{gauche.uvector}@}
Interchanges @var{i}th and @var{j}th elements of the uvector @var{vec}.
Return value is not specified.
@end deffn

@deffn {Function} @@vector-fill! vec fill :optional start end
@findex u8vector-fill!
@findex s8vector-fill!
@findex u16vector-fill!
@findex s16vector-fill!
@findex u32vector-fill!
@findex s32vector-fill!
@findex u64vector-fill!
@findex s64vector-fill!
@findex f16vector-fill!
@findex f32vector-fill!
@findex f64vector-fill!
@findex c32vector-fill!
@findex c64vector-fill!
@findex c128vector-fill!
@{@t{gauche.uvector}@}
Stores @var{fill} in every element of @var{vec},
ranging from @var{start} to @var{end} of @var{vec},
if they are given.
Return value is not specified.
@end deffn

@deffn {Function} @@vector= @var{vec1} @dots{}
@findex u8vector=
@findex s8vector=
@findex u16vector=
@findex s16vector=
@findex u32vector=
@findex s32vector=
@findex u64vector=
@findex s64vector=
@findex f16vector=
@findex f32vector=
@findex f64vector=
@findex c32vector=
@findex c64vector=
@findex c128vector=
[R7RS vector.@@]
@{@t{gauche.uvector}@}
All arguments must be @@vectors.  Returns @code{#t} iff
all arguments have the same length and has the same values (in terms of @code{=})
at the corresponding position. Zero arguments
return @var{#t}.

Note that in Gauche you can compare uvectors with @code{equal?}as well.
@end deffn


@deffn {Function} @@vector=? @var{vec1} @var{vec2}
@findex u8vector=?
@findex s8vector=?
@findex u16vector=?
@findex s16vector=?
@findex u32vector=?
@findex s32vector=?
@findex u64vector=?
@findex s64vector=?
@findex f16vector=?
@findex f32vector=?
@findex f64vector=?
@findex c32vector=?
@findex c64vector=?
@findex c128vector=?
[SRFI-66]
@{@t{gauche.uvector}@}
Note: This is provided only for the srfi-66 compatibility.
Use @code{@@vector=} instead.

Both arguments must be a @@vector.  Returns @code{#t} if
@var{vec1} and @var{vec2} are equal to each other, @code{#f} otherwise.
@end deffn

@deffn {Function} @@vector-compare @var{vec1} @var{vec2}
@findex u8vector-compare
@findex s8vector-compare
@findex u16vector-compare
@findex s16vector-compare
@findex u32vector-compare
@findex s32vector-compare
@findex u64vector-compare
@findex s64vector-compare
@findex f16vector-compare
@findex f32vector-compare
@findex f64vector-compare
@findex c32vector-compare
@findex c64vector-compare
@findex c128vector-compare
[SRFI-66]
@{@t{gauche.uvector}@}
Both arguments must be a @@vector.  Returns @code{-1} if
@var{vec1} is smaller than @var{vec2},
@code{0} if both are equal to each other,
and @code{1} if @var{vec1} is greater than @var{vec2}.

Shorter vector is smaller than longer vectors.  If the lengths of
both vectors are the same, elements are compared from left to right.

Note that you can compare uvectors with @code{compare} in Gauche.
These are provided because SRFI-66 defines @code{u8vector-compare}.
You can also use them to indicate arguments are vectors of the specific type.
@end deffn

@deffn {Function} @@vector-copy vec :optional start end
@findex u8vector-copy
@findex s8vector-copy
@findex u16vector-copy
@findex s16vector-copy
@findex u32vector-copy
@findex s32vector-copy
@findex u64vector-copy
@findex s64vector-copy
@findex f16vector-copy
@findex f32vector-copy
@findex f64vector-copy
@findex c32vector-copy
@findex c64vector-copy
@findex c128vector-copy
[R7RS vector.@@]
@{@t{gauche.uvector}@}
Returns a fresh copy of uniform vector @var{vec}.
If @var{start} and/or @var{end} are given, they limit the range of
@var{vec} to be copied.

@example
(u8vector-copy '#u8(1 2 3 4))     @result{} #u8(1 2 3 4)
(u8vector-copy '#u8(1 2 3 4) 2)   @result{} #u8(3 4)
(u8vector-copy '#u8(1 2 3 4) 1 3) @result{} #u8(2 3)
@end example
@end deffn

@defun uvector-copy vec :optional start end
@{@t{gauche.uvector}@}
This is a generic version of @code{@@vector-copy}.
You can give any type of uvector to @var{vec}, and get its copy
(or copy of its part, depending on @var{start}/@var{end} argument).
@end defun

@deffn {Function} @@vector-reverse-copy vec :optional start end
@findex u8vector-reverse-copy
@findex s8vector-reverse-copy
@findex u16vector-reverse-copy
@findex s16vector-reverse-copy
@findex u32vector-reverse-copy
@findex s32vector-reverse-copy
@findex u64vector-reverse-copy
@findex s64vector-reverse-copy
@findex f16vector-reverse-copy
@findex f32vector-reverse-copy
@findex f64vector-reverse-copy
@findex c32vector-reverse-copy
@findex c64vector-reverse-copy
@findex c128vector-reverse-copy
[R7RS vector.@@]
@{@t{gauche.uvector}@}
Copies @var{vec} between @var{strat} and @var{end} index, but
reversing it.
@example
(u8vector-reverse-copy '#u8(1 2 3 4 5))
  @result{} #u8(5 4 3 2 1)

(u8vector-reverse-copy '#u8(1 2 3 4 5) 1 4)
  @result{} #u8(4 3 2)
@end example
@end deffn

@deffn {Function} @@vector-copy! target tstart source :optional sstart send
@findex u8vector-copy!
@findex s8vector-copy!
@findex u16vector-copy!
@findex s16vector-copy!
@findex u32vector-copy!
@findex s32vector-copy!
@findex u64vector-copy!
@findex s64vector-copy!
@findex f16vector-copy!
@findex f32vector-copy!
@findex f64vector-copy!
@findex c32vector-copy!
@findex c64vector-copy!
@findex c128vector-copy!
[R7RS vector.@@]
@{@t{gauche.uvector}@}
Both @var{target} and @var{source} must be @@vectors, and
@var{target} must be mutable.
This procedure copies the elements of @var{source}, beginning from index
@var{sstart} (inclusive) and up to @var{send}, into @var{target},
beginning from index @var{tstart}.  @var{sstart} and @var{send}
may be omitted, and in that case 0 and the length of @var{source}
are assumed, respectively.

@example
(let ((target (u8vector 0 1 2 3 4 5 6)))
  (u8vector-copy! target 2 '#u8(10 11 12 13 14) 1 4)
  target)
 @result{} #u8(0 1 11 12 13 6)
@end example

If the number of elements in the source vector between @var{sstart}
and @var{send} is larger than the target vector beginning from @var{tstart},
the excess elements are silently discarded.

It is ok to pass the same vector to @var{target} and @var{source};
it always works even if the regions of source and destination are
overlapping.

@emph{Note:} This procedure used to take just two uniform vectors, @var{target}
and @var{source}, and just copies contents of @var{source} to @var{target}.
Both vectors had to be the same type and same length.  The API is revised
according to srfi-160.  The old interface is still supported
for the backward compatibility, but it is deprecated and will be gone
in the future releases.

Also note that SRFI-66 provides @code{uvector-copy!} with different
argument order (@pxref{Octet vectors}).
@end deffn

@deffn {Function} @@vector-multi-copy! target tstart tstride source :optional sstart ssize sstride count
@findex u8vector-multi-copy!
@findex s8vector-multi-copy!
@findex u16vector-multi-copy!
@findex s16vector-multi-copy!
@findex u32vector-multi-copy!
@findex s32vector-multi-copy!
@findex u64vector-multi-copy!
@findex s64vector-multi-copy!
@findex f16vector-multi-copy!
@findex f32vector-multi-copy!
@findex f64vector-multi-copy!
@findex c32vector-multi-copy!
@findex c64vector-multi-copy!
@findex c128vector-multi-copy!
@{@t{gauche.uvector}@}
This procedure allows different parts of the source uvector @var{source} into
various parts of the target uvector @var{target}, all at once.

When @var{ssize} is omitted or zero, this procedure does the following:

@example
;; For each @var{i} from 0 to @var{count}:
(u8vector-copy! target (+ tstart (* i tstride))
                source sstart)
@end example

That is, it copies the content of @var{source} (offset by @var{sstart},
which defaults to 0)
into the @var{target} repeatedly, advancing index with @var{tstride}.
If either the target index reaches the end or @var{count} copies
are made, the procedure returns.  See the example:

@example
(define t (make-u8vector 10 0))
(u8vector-multi-copy! t 0 4 '#u8(1 2 3))

t @result{} #u8(1 2 3 0 1 2 3 0 1 2)
@end example

If @var{ssize} is given and positive, the source is also splitted
as follows:

@example
;; For each @var{i} from 0 to @var{count}:
(u8vector-copy! target (+ tstart (* i tstride))
                source (+ sstart (* i sstride))
                       (+ sstart (* i sstride) ssize))
@end example

That is, each @var{ssize} slice from @var{source},
 is copied into @var{target}, advancing source index
by @var{sstride} and the destination index by @var{dstride}.
In this case, @var{sstride} defaults to @var{ssize} if omitted.

@example
(define t (make-u8vector 12 0))
(u8vector-multi-copy! t 0 4 '#u8(1 2 3 4 5 6 7 8 9) 0 3)

t @result{} #u8(1 2 3 0 4 5 6 0 7 8 9 0)
@end example

The operation ends when either @var{count} slices are copied,
or destination index or source index reaches the end.

Hint: If you want to copy a part of the source vector repeatedly
(instead of to its end), you can specify 0 to @var{sstride}:

@example
(define t (make-u8vector 12 0))
(u8vector-multi-copy! t 0 4 '#u8(1 2 3 4 5 6 7 8 9) 2 4 0)

t @result{} #u8(3 4 5 6 3 4 5 6 3 4 5 6)
@end example
@end deffn


Using collection and sequence framework, you can perform
various operations on the homogeneous vectors.

@example
(use gauche.collection)
(use gauche.sequence)

(fold + 0 '#s32(1 2 3 4)) @result{} 10

(map-to <f32vector> * '#f32(3.2 1.1 4.3) '#f32(-4.3 2.2 9.4))
  @result{} #f32(-13.760001 2.420000 40.420002)

(subseq #u32(1 4 3 4 5) 2 4) @result{} #u32(3 4)
@end example


@defun uvector-copy! target tstart source :optional sstart send
@{@t{gauche.uvector}@}
This is a generic version of @code{@@vector-copy!}.
The destination @var{target} and the source @var{source} can be
any type of uniform vectors, and they don't need to match.
The copy is done bit-by-bit.  So if you copy to a different type
of uvector, the result depends on how the numbers are represented
internally.  This is mainly to manipulate binary data.

@var{Tstart} is interpreted according to the type of @var{target},
and @var{sstart} and @var{send} are interpreted according to the
type of @var{source}.

@example
(rlet1 v (make-u8vector 6 0)
  (uvector-copy! v 1 '#u32(0 #x01020304 0) 1 2))
 @result{} #u8(0 1 2 3 4 0) or #u8(0 4 3 2 1 0)
@end example
@end defun


@deffn {Function} @@vector-append vec @dots{}
@findex u8vector-append
@findex s8vector-append
@findex u16vector-append
@findex s16vector-append
@findex u32vector-append
@findex s32vector-append
@findex u64vector-append
@findex s64vector-append
@findex f16vector-append
@findex f32vector-append
@findex f64vector-append
@findex c32vector-append
@findex c64vector-append
@findex c128vector-append
[R7RS vector.@@]
@{@t{gauche.uvector}@}
All arguments must be @@vectors.  Returns a fresh vector
whose contents are concatenation of the given vectors.
(It returns a fresh vector even there's only one argument).

@example
(u8vector-append '#u8(1 2 3) '#u8(4 5) '#u8() '#u8(6 7 8))
  @result{} #u8(1 2 3 4 5 6 7 8)
@end example
@end deffn

@deffn {Function} @@vector-concatenate vecs
@findex u8vector-concatenate
@findex s8vector-concatenate
@findex u16vector-concatenate
@findex s16vector-concatenate
@findex u32vector-concatenate
@findex s32vector-concatenate
@findex u64vector-concatenate
@findex s64vector-concatenate
@findex f16vector-concatenate
@findex f32vector-concatenate
@findex f64vector-concatenate
@findex c32vector-concatenate
@findex c64vector-concatenate
@findex c128vector-concatenate
[R7RS vector.@@]
@{@t{gauche.uvector}@}
Returns a new @@vector which is concatenation of the list of
@@vectors @var{vecs}.
@example
(u8vector-concatenate '(#u8(1 2 3) #u8(4 5 6)))
  @result{} #u8(1 2 3 4 5 6)
@end example
@end deffn

@deffn {Function} @@vector-append-subvectors :optional vec start end @dots{}
@findex u8vector-append-subvectors
@findex s8vector-append-subvectors
@findex u16vector-append-subvectors
@findex s16vector-append-subvectors
@findex u32vector-append-subvectors
@findex s32vector-append-subvectors
@findex u64vector-append-subvectors
@findex s64vector-append-subvectors
@findex f16vector-append-subvectors
@findex f32vector-append-subvectors
@findex f64vector-append-subvectors
@findex c32vector-append-subvectors
@findex c64vector-append-subvectors
@findex c128vector-append-subvectors
[R7RS vector.@@]
@{@t{gauche.uvector}@}
Returns a new @@vector which is concatenation of the subvectors of
given @var{vec}s, using accompanied @var{start} and @var{end} index.
@example
(u8vector-append-subvectors '#u8(1 2 3 4) 1 3 '#u8(5 6 7 8) 0 2)
  @result{} #u8(2 3 5 6)
@end example
@end deffn

@defvar @@vector-comparator
@vindex u8vector-comparator
@vindex s8vector-comparator
@vindex u16vector-comparator
@vindex s16vector-comparator
@vindex u32vector-comparator
@vindex s32vector-comparator
@vindex u64vector-comparator
@vindex s64vector-comparator
@vindex f16vector-comparator
@vindex f32vector-comparator
@vindex f64vector-comparator
@vindex c32vector-comparator
@vindex c64vector-comparator
@vindex c128vector-comparator
[R7RS vector.@@]
@{@t{gauche.uvector}@}
Bound to comparators that can compare two @code{@@vector}s and
to hash a @code{@@vector}.  @xref{Basic comparators}, for the details
of comparators.  These comparators both provides ordering predicate
and hash function.
@end defvar


@defun uvector-binary-search uvector key :optional start end skip rounding
@{@t{gauche.uvector}@}
The @code{uvector} must contain values in increasing order.
This procedure finds the index of an element that is equal to @var{key},
using binary search.   If such element can't be found, @code{#f} is returned.

@example
(uvector-binary-search '#u8(0 5 19 32 58 96) 32)
  @result{} 3

(uvector-binary-search '#u8(0 5 19 32 58 96) 33)
  @result{} #f
@end example

The optional @var{start} and @var{end} arguments limits the portion
of @var{uvector} to search; @var{start} specifies starting index (inclusive)
and @var{end} specifies ending index (exclusive).
Passing @code{#f} indicates the default
value (0 for @var{start}, the length of the vector for @var{end}).
The returned index is the actual index of the vector, but the elements
outside of @var{start}-@var{end} range don't need to be sorted.

@example
(uvector-binary-search '#u8(99 99 19 32 58 99) 32 2 5)
  @result{} 3

(uvector-binary-search '#u8(99 99 19 32 58 99) 99 2 5)
  @result{} #f
@end example

The optional @var{skip} argument must be a nonnegative exact integer
or @code{#f}.  If it is a positive integer, the number of elements after
every key in the @var{uvector} is ignored.  For example, if @var{skip} is 2
and @var{uvector} is @code{#u8(3 100 101 5 102 103 13 104 105)},
only @code{3}, @code{5} and @code{13} are subject to search, and elements
inbetween are ignored.  This allows the caller to store @emph{payload},
or associated value to each key, in the @var{uvector} itself.
If @var{skip} is positive integer, the length of the searched portion
of @var{uvector} must be a multiple of the record size (@var{skip}+1).

@example
(uvector-binary-search '#u8(3 100 101 5 102 103 13 104 105) 13 #f #f 2)
  @result{} 6

(uvector-binary-search '#u8(3 100 101 5 102 103 13 104) 13 #f #f 2)
  @result{} ; @r{Error: uvector size (8) isn't multiple of record size (3)}
@end example

Finally, @var{rounding} argument adjusts the behavior when the exact
match isn't found.  It can be either one of the following values:

@table @asis
@item @code{#f}
This is the default.
The procedure searches the element that is equal to @var{key}, and
returns @code{#f} if such element isn't found.
@item a symbol @code{floor}
When the exact match isn't found, the procedure
returns an index of the element that's closest to but
not greater than @var{key}.  If @var{key} is smaller than all the elements,
@code{#f} is returned.
@item a symbol @code{ceiling}
When the exact match isn't found, the procedure
returns an index of the element that's closest to but
not smaller than @var{key}.  If @var{key} is greater than all the elements,
@code{#f} is returned.
@end table

@example
(uvector-binary-search '#u32(1 10 100 1000 10000) 3757)
  @result{} #f

(uvector-binary-search '#u32(1 10 100 1000 10000) 3757 #f #f #f 'floor)
  @result{} 3

(uvector-binary-search '#u32(1 10 100 1000 10000) 3757 #f #f #f 'ceiling)
  @result{} 4
@end example

Note: SRFI-133 has @code{vector-binary-search}, which is quite similar to
this procedure (@pxref{R7RS vectors}) but it requires comparison
procedure, for it needs to compare general Scheme values.  And it
does not support @var{skip} and @var{rounding} arguments.
@end defun

@node Uvector conversion operations, Uvector numeric operations, Uvector basic operations, Uniform vector library
@subsection Uvector conversion operations
@c NODE ユニフォームベクタの変換

@deffn {Function} @@vector->list vec :optional start end
@findex u8vector->list
@findex s8vector->list
@findex u16vector->list
@findex s16vector->list
@findex u32vector->list
@findex s32vector->list
@findex u64vector->list
@findex s64vector->list
@findex f16vector->list
@findex f32vector->list
@findex f64vector->list
@findex c32vector->list
@findex c64vector->list
@findex c128vector->list
[R7RS vector.@@]
@{@t{gauche.uvector}@}
Converts @@vector @var{vec} to a list.
If @var{start} and/or @var{end} are given, they limit the range of
@var{vec} to be extracted.

Note that the generic function @code{coerce-to} can be used as well,
if you import @code{gauche.collection}.
@example
(u32vector->list '#u32(9 2 5)) @result{} (9 2 5)

(use gauche.collection)
(coerce-to <list> '#u32(9 2 5)) @result{} (9 2 5)
@end example
@end deffn

@defun uvector->list uvec :optional start end
@{@t{gauche.uvector}@}
This is a generic version of @code{@@vector->list}.  
It can take any kind of uvector as @var{uvec}.  The meaning of
optional arguments are the same as @code{@@vector->list}.
@end defun


@deffn {Function} @@vector->vector vec :optional start end
@findex u8vector->vector
@findex s8vector->vector
@findex u16vector->vector
@findex s16vector->vector
@findex u32vector->vector
@findex s32vector->vector
@findex u64vector->vector
@findex s64vector->vector
@findex f16vector->vector
@findex f32vector->vector
@findex f64vector->vector
@findex c32vector->vector
@findex c64vector->vector
@findex c128vector->vector
[R7RS vector.@@]
@{@t{gauche.uvector}@}
Converts @@vector @var{vec} to a vector.
If @var{start} and/or @var{end} are given, they limit the range of
@var{vec} to be copied.

Note that the generic function @code{coerce-to} can be used as well,
if you import @code{gauche.collection}.
@example
(f32vector->vector '#f32(9.3 2.2 5.5))   @result{} #(9.3 2.2 5.5)
(f32vector->vector '#f32(9.3 2.2 5.5) 2) @result{} #(5.5)

(use gauche.collection)
(coerce-to <vector> '#f32(9.3 2.2 5.5)) @result{} #(9.3 2.2 5.5)
@end example
@end deffn

@defun uvector->vector uvec :optional start end
@{@t{gauche.uvector}@}
This is a generic version of @code{@@vector->vector}.  
It can take any kind of uvector as @var{uvec}.  The meaning of
optional arguments are the same as @code{@@vector->vector}.
@end defun

@deffn {Function} list->@@vector list :optional clamp
@findex list->s8vector
@findex list->u8vector
@findex list->s16vector
@findex list->u16vector
@findex list->s32vector
@findex list->u32vector
@findex list->s64vector
@findex list->u64vector
@findex list->f16vector
@findex list->f32vector
@findex list->f64vector
@findex list->c32vector
@findex list->c64vector
@findex list->c128vector
[R7RS vector.@@]
@{@t{gauche.uvector}@}
Converts a list @var{list} to a @@vector.
Optional argument @var{clamp} specifies the behavior when
the element of @var{list} is out of the valid range.
(The @var{clamp} argument is Gauche's extension.)

Note that the generic function @code{coerce-to} can be used as well,
if you import @code{gauche.collection}.
@example
(list->s64vector '(9 2 5)) @result{} #s64(9 2 5)

(use gauche.collection)
(coerce-to <s64vector> '(9 2 5)) @result{} #s64(9 2 5)
@end example
@end deffn

@deffn {Function} reverse-list->@@vector list :optional clamp
@findex reverse-list->s8vector
@findex reverse-list->u8vector
@findex reverse-list->s16vector
@findex reverse-list->u16vector
@findex reverse-list->s32vector
@findex reverse-list->u32vector
@findex reverse-list->s64vector
@findex reverse-list->u64vector
@findex reverse-list->f16vector
@findex reverse-list->f32vector
@findex reverse-list->f64vector
@findex reverse-list->c32vector
@findex reverse-list->c64vector
@findex reverse-list->c128vector
[R7RS vector.@@]
@{@t{gauche.uvector}@}
Create a new @code{@@vector} with the elements of @var{list} in
reverse order.  
Optional argument @var{clamp} specifies the behavior when
the element of @var{list} is out of the valid range.
(The @var{clamp} argument is Gauche's extension.)
@end deffn


@deffn {Function} vector->@@vector vec :optional start end clamp
@findex vector->s8vector
@findex vector->u8vector
@findex vector->s16vector
@findex vector->u16vector
@findex vector->s32vector
@findex vector->u32vector
@findex vector->s64vector
@findex vector->u64vector
@findex vector->f16vector
@findex vector->f32vector
@findex vector->f64vector
@findex vector->c32vector
@findex vector->c64vector
@findex vector->c128vector
[R7RS vector.@@]
@{@t{gauche.uvector}@}
Converts a vector @var{vec} to a @@vector.
If @var{start} and/or @var{end} are given, they limit the range of
@var{vec} to be copied.
Optional argument @var{clamp} specifies the behavior when
the element of @var{vec} is out of the valid range.
(The @var{clamp} argument is Gauche's extension.)

Note that the generic function @code{coerce-to} can be used as well,
if you import @code{gauche.collection}.
@example
(vector->f64vector '#(3.1 5.4 3.2)) @result{} #f64(3.1 5.4 3.2)

(use gauche.collection)
(coerce-to <f64vector> '#(3.1 5.4 3.2)) @result{} #f64(3.1 5.4 3.2)
@end example
@end deffn

@defun string->s8vector string :optional start end immutable?
@defunx string->u8vector string :optional start end immutable?
@{@t{gauche.uvector}@}
Returns an s8vector or u8vector whose byte sequence is the same
as the internal representation of the given string.
Optional range arguments @var{start} and @var{end} specifies
the @emph{character position} (not the byte position) inside @var{string} to be
converted.

By default, the content of the string is copied to a newly created
mutable uvector.  However, if a true value is given to the
optional @var{immutable?} argument, the result is an immutable
uvector, and it may avoid copying the string body (note that
in Gauche, the body of string is immutable; @code{string-set!} creates
a new body, so changing the original string won't affect the
uvector created by @code{string->u8vector} with @code{immutable?} flag.)

These procedures are useful when you want to access byte
sequence of the string randomly.

@example
(string->u8vector "abc") @result{} #u8(97 98 99)

@end example

@example
(string->u8vector "very large string .... " 0 -1 #t)
  @result{} #u8(...)  ; @r{immutable, sharing content with the original string}
@end example

@end defun

@defun string->s8vector! target tstart string :optional start end
@defunx string->u8vector! target tstart string :optional start end
@{@t{gauche.uvector}@}
@var{Target} must be an s8vector or a u8vector, respectively.
@var{Target} must be mutable.
Like copies the raw byte representation of @var{string}
into @var{target} beginning from index @var{tstart}.

Returns @var{target}.

@example
(let ((target (make-u8vector 10 0)))
  (string->u8vector! target 3 "abcde"))
 @result{} #u8(0 0 0 97 98 99 100 101 0 0)
@end example

@end defun

@defun s8vector->string vec :optional start end terminator
@defunx u8vector->string vec :optional start end terminator
@{@t{gauche.uvector}@}
Converts a byte sequence in s8vector or u8vector to a string that
has the same byte sequence.  Optional range arguments @var{start} and
@var{end} specifies the byte position in @var{vec} to be converted.

The optional @var{terminator} argument can be an exact integer or
@code{#f} (default).  If it is an exact integer, and it appears
in @var{vec}, the string terminates right before it.
For example, you can give 0 as @var{terminator}
to read a NUL-terminated string from a buffer.

@example
(u8vector->string '#u8(65 66 0 67 68) 0 5)   @result{} "AB\0CD"
(u8vector->string '#u8(65 66 0 67 68) 0 5 0) @result{} "AB"
@end example

Note that these procedure may result an incomplete string if
@var{vec} contains a byte sequence invalid as the internal encoding
of the string.
@end defun

@defun string->s32vector string :optional start end endian
@defunx string->u32vector string :optional start end endian
@{@t{gauche.uvector}@}
Returns an s32vector or u32vector whose elements are
the internal codes of the characters in the string.
Optional range arguments @var{start} and @var{end} specifies
the @emph{character position} inside @var{string} to be
converted.

The optional @var{endian} argument specifies the endianness to store
codepoint value into the uvector.  When omitted or @code{#f},
we use the platform's
native endianness.  You can give a symbol @code{big-endian}, @code{big},
@code{little-endian}, @code{little} or @code{arm-little-endian} to use a specific
endianness.  Note that when you access the resulting uvector,
the platform's native endianness is used.

These procedures are useful when you want to access
the characters in the string randomly.


@end defun

@defun string->s32vector! target tstart string :optional start end endian
@defunx string->u32vector! target tstart string :optional start end endian
@{@t{gauche.uvector}@}
@var{Target} must be a mutable s32vector or u32vector, respectively.
Fill the @var{target} from position @var{tstart} with the codepoint
of each character of @var{string}, until either @var{string} is exhausted
or @var{target} is filled to the end. 

Optional range arguments @var{start} and @var{end} specifies
the @emph{character position} inside @var{string} to be
considered.

The optional @var{endian} argument specifies the endianness to store
codepoint value into the uvector.  When omitted or @code{#f},
we use the platform's
native endianness.  You can give a symbol @code{big-endian}, @code{big},
@code{little-endian}, @code{little} or @code{arm-little-endian} to use a specific
endianness.  Note that when you access the resulting uvector,
the platform's native endianness is used.
@end defun

@defun s32vector->string vec :optional start end terminator endian
@defunx u32vector->string vec :optional start end terminator endian
@{@t{gauche.uvector}@}
Without @var{start} and @var{end}, these procedures work like this:
@example
(lambda (vec) (map-to <string> integer->char vec)))
@end example
Optional range arguments @var{start} and @var{end} limits
the range of conversion between them.

The optional @var{terminator} argument must be an exact
integer or @code{#f} (default).  If an integer is given,
and the integer is found in the input,
the output string terminates right before it.

The optional @var{endian} argument specifies the endianness to store
codepoint value into the uvector.  When omitted or @code{#f},
we use the platform's
native endianness.  You can give a symbol @code{big-endian}, @code{big},
@code{little-endian}, @code{little} or @code{arm-little-endian} to use a specific
endianness.

@example
(u32vector->string '#u32(65 66 0 67 68) 0 5 0) @result{} "AB"
@end example
@end defun

@defun uvector-alias uvector-class vec :optional start end
@{@t{gauche.uvector}@}
This procedure creates an uvector of class @var{uvector-class}
that shares the storage of the given uniform vector @var{vec}.
If optional @var{start} and @var{end} arguments are given,
only the specified range of @var{vec} is used for the new vector.
Since the storage is shared, modification of the original vector
can be seen from the new vector, or vice versa.

The class @var{uvector-class} must be either one of the uniform
vector class, but is not necessary match the class of the
source vector @var{vec}.   In such case, the new vector looks at the same
region of @var{vec}'s memory, but interprets it differently.
For example, the following code determines whether Gauche
is running on big-endian or little-endian machine:

@example
(let ((u8v (uvector-alias <u8vector> #u32(1))))
  (if (zero? (u8vector-ref u8v 0))
      'big-endian
      'little-endian))
@end example

If the @var{uvector-class} is other than s8vector or u8vector,
the region the new vector points has to meet the alignment
requirement.  You can assume the beginning of the source vector
is aligned suitable for any uniform vectors.  So, for example,
if you're creating u32vector from u8vector, the @var{start} and
@var{end} must be multiple of 4 (or, if they're omitted, the length
of the original u8vector must be multiple of 4).
An error is signaled when the given parameters doesn't satisfy
alignment constraint.
@end defun




@node Uvector numeric operations, Uvector block I/O, Uvector conversion operations, Uniform vector library
@subsection Uvector numeric operations
@c NODE ユニフォームベクタの数値演算

These are Gauche extension that allows faster arithmetic over uniform
vectors, than extracting and calculating element-wise values.

Most procedures comes with two flavors, a functional version (without @code{!}
in the name) and a linear-update version (with @code{!} in the name).

A functional version assumes the caller treats the arguments and
results immutable objects; mutating them later could have unexpected
consequences.  (Notably, the functional version may return one of its
arguments as is, or returns a pre-computed value,
so you shouldn't assume the return values are freshly
allocated objects, unless it is noted so explicitly.)

A linear update version may reuse the storage of the designated
argument to produce the return value.  Gauche tries to reuse the
argument as much as possible, but you should always use the return
value and shouldn't assume the argument itself is modified in-place.
In fact, after calling linear-updating procedure, you can't use
the argument that may be modified, since you can't assume the state
of the object after calling the procedure.

@deffn {Function} @@vector-add vec val :optional clamp
@deffnx {Function} @@vector-add! vec val :optional clamp
@deffnx {Function} @@vector-sub vec val :optional clamp
@deffnx {Function} @@vector-sub! vec val :optional clamp
@deffnx {Function} @@vector-mul vec val :optional clamp
@deffnx {Function} @@vector-mul! vec val :optional clamp
@findex s8vector-add
@findex s8vector-add!
@findex s8vector-sub
@findex s8vector-sub!
@findex s8vector-mul
@findex s8vector-mul!
@findex u8vector-add
@findex u8vector-add!
@findex u8vector-sub
@findex u8vector-sub!
@findex u8vector-mul
@findex u8vector-mul!
@findex s16vector-add
@findex s16vector-add!
@findex s16vector-sub
@findex s16vector-sub!
@findex s16vector-mul
@findex s16vector-mul!
@findex u16vector-add
@findex u16vector-add!
@findex u16vector-sub
@findex u16vector-sub!
@findex u16vector-mul
@findex u16vector-mul!
@findex s32vector-add
@findex s32vector-add!
@findex s32vector-sub
@findex s32vector-sub!
@findex s32vector-mul
@findex s32vector-mul!
@findex u32vector-add
@findex u32vector-add!
@findex u32vector-sub
@findex u32vector-sub!
@findex u32vector-mul
@findex u32vector-mul!
@findex s64vector-add
@findex s64vector-add!
@findex s64vector-sub
@findex s64vector-sub!
@findex s64vector-mul
@findex s64vector-mul!
@findex u64vector-add
@findex u64vector-add!
@findex u64vector-sub
@findex u64vector-sub!
@findex u64vector-mul
@findex u64vector-mul!
@findex f16vector-add
@findex f16vector-add!
@findex f16vector-sub
@findex f16vector-sub!
@findex f16vector-mul
@findex f16vector-mul!
@findex f32vector-add
@findex f32vector-add!
@findex f32vector-sub
@findex f32vector-sub!
@findex f32vector-mul
@findex f32vector-mul!
@findex f64vector-add
@findex f64vector-add!
@findex f64vector-sub
@findex f64vector-sub!
@findex f64vector-mul
@findex f64vector-mul!
@findex c32vector-add
@findex c32vector-add!
@findex c32vector-sub
@findex c32vector-sub!
@findex c32vector-mul
@findex c32vector-mul!
@findex c64vector-add
@findex c64vector-add!
@findex c64vector-sub
@findex c64vector-sub!
@findex c64vector-mul
@findex c64vector-mul!
@findex c128vector-add
@findex c128vector-add!
@findex c128vector-sub
@findex c128vector-sub!
@findex c128vector-mul
@findex c128vector-mul!
@{@t{gauche.uvector}@}
Element-wise arithmetic.  @var{Vec} must be a @@vector,
and @var{val} must be either a @@vector, a vector, or a list
of the same length as @var{vec}, or a number
(an exact integer for integer vectors,
and a real number for f32- and f64-vectors).

If @var{val} is a @@vector, its elements are
added to, subtracted from, or multiplied by the corresponding
elements of @var{vec}, respectively,
and the results are gathered to a @@vector
and returned.  The linear-update version (those have bang `!' in the name)
reuses @var{vec} to store the result, and also returns it.
If the result of calculation goes out of the range of @@vector's
element, the behavior is specified by @var{clamp} optional argument.
(For f32vector and f64vector, @var{clamp} argument is ignored and
the result may contain infinity).

If @var{val} is a number, it is added to, subtracted from, or
multiplied by each element of @var{vec}, respectively.

@example
(s8vector-add '#s8(1 2 3 4) '#s8(5 6 7 8)) @result{} #s8(6 8 10 12)
(u8vector-sub '#u8(1 2 3 4) '#u8(2 2 2 2)) @result{} @r{error}
(u8vector-sub '#u8(1 2 3 4) '#u8(2 2 2 2) 'both) @result{} #u8(0 0 1 2)

(f32vector-mul '#f32(3.0 2.0 1.0) 1.5) @result{} #f32(4.5 3.0 1.5)
@end example
@end deffn

@deffn {Function} @@vector-div vec val
@deffnx {Function} @@vector-div! vec val
@findex f16vector-div
@findex f16vector-div!
@findex f32vector-div
@findex f32vector-div!
@findex f64vector-div
@findex f64vector-div!
@findex c32vector-div
@findex c32vector-div!
@findex c64vector-div
@findex c64vector-div!
@findex c128vector-div
@findex c128vector-div!
@{@t{gauche.uvector}@}
Element-wise division of flonum vectors.   These are only defined
for f16, f32 and f64vector.  @var{val} must be a @@vector,
a vector or a list of the same length as @var{vec}, or a real number.

@example
(f32vector-div '#f32(1.0 2.0 3.0) 2.0) @result{} #f32(0.5 1.0 1.5)
@end example
@end deffn


@deffn {Function} @@vector-and vec val
@deffnx {Function} @@vector-and! vec val
@deffnx {Function} @@vector-ior vec val
@deffnx {Function} @@vector-ior! vec val
@deffnx {Function} @@vector-xor vec val
@deffnx {Function} @@vector-xor! vec val
@findex s8vector-and
@findex s8vector-and!
@findex s8vector-ior
@findex s8vector-ior!
@findex s8vector-xor
@findex s8vector-xor!
@findex u8vector-and
@findex u8vector-and!
@findex u8vector-ior
@findex u8vector-ior!
@findex u8vector-xor
@findex u8vector-xor!
@findex s16vector-and
@findex s16vector-and!
@findex s16vector-ior
@findex s16vector-ior!
@findex s16vector-xor
@findex s16vector-xor!
@findex u16vector-and
@findex u16vector-and!
@findex u16vector-ior
@findex u16vector-ior!
@findex u16vector-xor
@findex u16vector-xor!
@findex s32vector-and
@findex s32vector-and!
@findex s32vector-ior
@findex s32vector-ior!
@findex s32vector-xor
@findex s32vector-xor!
@findex u32vector-and
@findex u32vector-and!
@findex u32vector-ior
@findex u32vector-ior!
@findex u32vector-xor
@findex u32vector-xor!
@findex s64vector-and
@findex s64vector-and!
@findex s64vector-ior
@findex s64vector-ior!
@findex s64vector-xor
@findex s64vector-xor!
@findex u64vector-and
@findex u64vector-and!
@findex u64vector-ior
@findex u64vector-ior!
@findex u64vector-xor
@findex u64vector-xor!
@{@t{gauche.uvector}@}
Element-wise logical (bitwise) operation.
These procedures are only defined for integral vectors.
@var{val} must be a @@vector, a vector or a list
of the same length as @var{vec},
or an exact integer.  Bitwise and, inclusive or or exclusive or
is calculated between each element in @var{vec} and the corresponding
element of @var{val} (when @var{val} is a non-scalar value),
or @var{val} itself (when @var{val} is an integer).
The result is returned in a @@vector.
The linear-update version reuses @var{vec} to store the result,
and also returns it.
@end deffn

@deffn {Function} @@vector-dot vec0 vec1
@findex s8vector-dot
@findex s16vector-dot
@findex s32vector-dot
@findex s64vector-dot
@findex u8vector-dot
@findex u16vector-dot
@findex u32vector-dot
@findex u64vector-dot
@findex f16vector-dot
@findex f32vector-dot
@findex f64vector-dot
@findex c32vector-dot
@findex c64vector-dot
@findex c128vector-dot
@{@t{gauche.uvector}@}
Calculates the dot product of two @@vectors.
The length of @var{vec0} and @var{vec1} must be the same.
@end deffn

@deffn {Function} @@vector-range-check vec min max
@findex s8vector-range-check
@findex s16vector-range-check
@findex s32vector-range-check
@findex s64vector-range-check
@findex u8vector-range-check
@findex u16vector-range-check
@findex u32vector-range-check
@findex u64vector-range-check
@findex f16vector-range-check
@findex f32vector-range-check
@findex f64vector-range-check
@{@t{gauche.uvector}@}
@var{Vec} must be a @@vector, and each of @var{min} and @var{max}
must be either a @@vector, a vector or a list of the same length
as @var{vec}, or a number, or @code{#f}.

For each element in @var{vec}, this procedure checks if the value
is between @var{minval} and @var{maxval} inclusive, where
@var{minval} and @var{maxval} are the corresponding values of
@var{min} and @var{max} (when @var{min} and/or @var{max} is/are
non-scalar value) or @var{min} and @var{max} themselves (when
@var{min} and/or @var{max} is/are a number).
When @var{min} is @code{#f}, negative infinity is assumed.
When @var{max} is @code{#f}, positive infinity is assumed.

If all the elements in @var{vec} are within the range, @code{#f} is
returned.  Otherwise, the index of the leftmost element of @var{vec}
that is out of range is returned.

@example
(u8vector-range-check '#u8(3 1 0 2) 0 3)  @result{} #f
(u8vector-range-check '#u8(3 1 0 2) 1 3)  @result{} 2

(u8vector-range-check '#u8(4 32 64 98) 0 '#u8(10 40 70 90))
  @result{} 3

;; Range check in a program
(cond
 ((u8vector-range-check u8v 1 31)
  => (lambda (i)
      (errorf "~sth vector element is out of range: ~s"
              i (u8vector-ref u8v i))))
 (else (do-something u8v)))
@end example
@end deffn

@deffn {Function} @@vector-clamp vec min max
@deffnx {Function} @@vector-clamp! vec min max
@findex s8vector-clamp
@findex s16vector-clamp
@findex s32vector-clamp
@findex s64vector-clamp
@findex u8vector-clamp
@findex u16vector-clamp
@findex u32vector-clamp
@findex u64vector-clamp
@findex f32vector-clamp
@findex f64vector-clamp
@findex s8vector-clamp!
@findex s16vector-clamp!
@findex s32vector-clamp!
@findex s64vector-clamp!
@findex u8vector-clamp!
@findex u16vector-clamp!
@findex u32vector-clamp!
@findex u64vector-clamp!
@findex f16vector-clamp!
@findex f32vector-clamp!
@findex f64vector-clamp!
@{@t{gauche.uvector}@}
@var{Vec} must be a @@vector, and each of @var{min} and @var{max}
must be either a @@vector, a vector or a list of the same length
as @var{vec}, or a number, or @code{#f}.

Like @@vector-range-check, these procedures check if
each element of @var{vec} are within the range between @var{minval}
and @var{maxval} inclusive, which are derived from @var{min} and @var{max}.
If the value is less than @var{minval}, it is replaced by @var{minval}.
If the value is grater than @var{maxval}, it is replaced by @var{maxval}.

@@vector-clamp creates a copy of @var{vec} and do clamp
operation on it, while @@vector-clamp! modifies @var{vec}.
Both return the clamped vector.

@example
(s8vector-clamp '#s8(8 14 -3 -22 0) -10 10) @result{} #s8(8 10 -3 -10 0)
@end example
@end deffn


@node Uvector block I/O, Bytevector compatibility, Uvector numeric operations, Uniform vector library
@subsection Uvector block I/O
@c NODE ユニフォームベクタのブロック入出力

A uniform vector can be seen as an abstraction of a chunk of memory.
So you might want to use it for binary I/O.  Yes, you can do it.

@defun read-uvector class size :optional iport endian
@{@t{gauche.uvector}@}
Reads @var{size} elements of uvector of class @var{class} from
@var{iport}, and returns fleshly created uvector.  If @var{iport}
is omitted, the curret input port is used.

For example, you can read input as an octet stream as follows:

@example
(with-input-from-string "abcde"
  (^[] (read-uvector <u8vector> 5)))
 @result{} #u8(97 98 99 100 101)
@end example

If the input port has already reached EOF, an EOF object is
returned.  The returned uvector can be shorter than @var{size}
if the input reaches EOF before @var{size} elements are read.

If the @var{iport} is a buffered port with `modest' or `none'
buffering mode (@pxref{File ports}), @code{read-uvector} may return
before @var{size} elements are read, even if @var{iport}
hasn't reached EOF.  The ports connected to a pipe or a network socket
behave so by default.

The data is read as a byte stream, so if you give uniform vectors
other than s8vector or u8vector, your result may affected by
the endianness.  If the optional argument @var{endian} is
given, the input is interpreted in that endianness.
When omitted, the value of the parameter @code{default-endian}
is used.  @xref{Endianness}, for more about endian handling.

If the size of the input data is unknown and you need to read everything
until EOF, use @code{port->uvector} below.
@end defun

@defun read-bytevector size :optional iport
[R7RS base]
@{@t{gauche.uvector}@}
Equivalent to @code{(read-uvector <u8vector> size iport)}.
This is an R7RS base procedure.
@end defun

@defun read-uvector! vec :optional iport start end endian
@{@t{gauche.uvector}@}
Reads a chunk of data from the given input port @var{iport},
and stores it to the uniform vector @var{vec}.
You can give any uniform vector.
If optional @var{start} and @var{end}
arguments are given, they specify the index range in @var{vec}
that is to be filled, and the rest of the vector remains untouched.
Otherwise, entire vector is used.  A special value -1 for @var{end}
indicates the end of @var{vec}.
If @var{iport} is omitted, the current input port is used.

If the input reached EOF before the required region of @var{vec}
is filled, the rest of the vector is untouched.

If @var{iport} is already reached EOF when @code{read-uvector!} is
called, an EOF object is returned.  Otherwise,
the procedure returns the number of @emph{elements} read (not bytes).

If the @var{iport} is a buffered port with `modest' or `none'
buffering mode (@pxref{File ports}), @code{read-uvector!} may return
before all the elements in @var{vec} is filled, even if @var{iport}
hasn't reached EOF.  The ports connected to a pipe or a network socket
behave so by default.  If you know there will be enough data arriving and
want to make sure @var{vec} is filled, change the buffering mode of
@var{iport} to `full'.

The data is read as a byte stream, so if you give uniform vectors
other than s8vector or u8vector, your result may affected by
the endianness.  If the optional argument @var{endian} is
given, the input is interpreted in that endianness.
When omitted, the value of the parameter @code{default-endian}
is used.  @xref{Endianness}, for more about endian handling.
@end defun

@defun read-block! vec :optional iport start end endian
@{@t{gauche.uvector}@}
An old name of @code{read-uvector!}.  Supported for the backward
compatibility, but new code should use @code{read-uvector!}.
@end defun

@defun port->uvector iport :optional class
@{@t{gauche.uvector}@}
Read data from the input port @var{iport} until EOF and store them
into a uvector of @var{class}.  If @var{class} is omitted,
@code{<u8vector>} is used.

If you specify a class of uvector whose element is more than an octet,
the input data is packed with platform's native byteorder.

This procedure is parallel to @code{port->string} etc.
(@pxref{Input utility functions}).
@end defun

@defun read-bytevector! bv :optional iport start end
[R7RS base]
@{@t{gauche.uvector.}@}
Similar to @code{read-uvector!}, but @var{bv} must be a u8vector.
This is an R7RS base procedure.
@end defun


@defun write-uvector vec :optional oport start end endian
@{@t{gauche.uvector}@}
Writes out the content of the uniform vector @var{vec} 'as is'
to the output port @var{oport}.   If @var{oport} is omitted,
the current output port is used.
If optional @var{start} and @var{end} arguments are given,
they specify the index range in @var{vec} to be written out.
A special value -1 for @var{end} indicates the end of @var{vec}.
This procedure returns an unspecified value.

If you write out a uniform vector except s8vector and u8vector, the
care should be taken about the endianness, as in @code{read-uvector}.
The optional argument @var{endian} specifies the output endian.
When it is omitted, the value of the parameter @code{default-endian}
is used (@pxref{Endianness}).
@end defun

@defun write-bytevector bv :optional oport start end
[R7RS base]
@{@t{gauche.uvector}@}
Similar to @code{write-uvector}, but @var{bv} must be a u8vector.
This is an R7RS base procedure.
@end defun

@defun write-block vec :optional oport start end endian
@{@t{gauche.uvector}@}
An old name of @code{write-uvector}.  Supported for the backward
compatibility, but new code should use @code{write-uvector}.
@end defun



@node Bytevector compatibility,  , Uvector block I/O, Uniform vector library
@subsection Bytevector compatibility
@c NODE バイトベクタ互換性

R7RS-small includes bytevectors in its core (@code{scheme.base}).
In Gauche, bytevectors are the same as u8vectors.

The basic R7RS bytevector procedures are provided in this module.
Conversion between bytevectors and strings are provided in
@code{gauche.unicode} (@pxref{Unicode transfer encodings}).

@defun bytevector byte @dots{}
@{@t{gauche.uvector}@}
[R7RS base]
Alias of @code{u8vector}.  Returns a fresh bytevector (u8vector) with
@var{byte} @dots{} as its elements.
@end defun

@defun bytevector? obj
@{@t{gauche.uvector}@}
[R7RS base]
Alias of @code{u8vector?}.  Returns true iff @var{obj} is 
a bytevector (u8vector).
@end defun

@defun make-bytevector len :optional byte
@{@t{gauche.uvector}@}
[R7RS base][R7RS bytevector]
Returns a fresh bytevector (u8vector)
of length @var{len}.  All elements are initialized by @var{byte}
if given.

R7RS base accepts an exact integer between 0 and 255 inclusive as
@var{byte}.  R7RS bytevector extends the range to -128 to 255 inclusive,
while the negative value is wrapped-around by modulo 255.
This procedure supports the extended range.
@end defun

@defun bytevector-length bv
@{@t{gauche.uvector}@}
[R7RS base]
Alias of @code{u8vector-length}.  Returns the length of the
bytevector (u8vector) @var{bv}.
@end defun

@defun bytevector-u8-ref bv k
@defunx bytevector-u8-set! bv k byte
@{@t{gauche.uvector}@}
[R7RS base]
Alias of @code{u8vector-ref} and @code{u8vector-set!}.
Read and write @var{k}-th element of a bytevector (u8vector) @var{bv}.

It is an error to give out-of-bound index.

The return value of @code{bytevector-u8-set!} is unspecified.

As Gauche's extension, @code{(setter bytevector-u8-ref)} is
@code{bytevector-u8-set!}.
@end defun

@defun bytevector-s8-ref bv k
@defunx bytevector-s8-set! bv k signed-byte
@{@t{gauche.uvector}@}
[R7RS bytevector]
Like @code{bytevector-u8-ref} and @code{bytevector-u8-set!}, but
treates octets as a signed byte, ranging from -128 to 127, inclusive.

As Gauche's extension, @code{(setter bytevector-s8-ref)} is
@code{bytevector-s8-set!}.
@end defun

@defun bytevector-copy bv :optional start end
@{@t{gauche.uvector}@}
[R7RS base]
Alias of @code{u8vector-copy}.  Returns a fresh copy of a 
bytevector (u8vector) @var{bv}.  Optionally you can restrict the
range of the source vector by indices @var{start} (inclusive)
and @var{end} (exclusive).
@end defun

@defun bytevector-copy! target tstart source :optional sstart send
@{@t{gauche.uvector}@}
[R7RS base]
Alias of @code{u8vector-copy!}.  Both @var{target} and @var{source}
muse be bytevectors (u8vectors), and @var{target} must be mutable.
Copy the content of @var{source} (optionally restricting the range
between indices @var{start} (inclusive) and @var{end} (exclusive))
into @var{target} starting at the index @var{tstart}.
@end defun

@defun bytevector-copy!-r6 src sstart target tstart len
@{@t{gauche.uvector}@}
This is a compatibility procedure for R6RS @code{bytevector-copy!}
(hence the suffix @code{-r6}).  When R6RS bytevectors are
adpoted as R7RS-large @code{scheme.bytevector}, the R6RS version
of @code{bytevector-copy!} comes into R7RS as well
(hence R7RS has two different @code{bytevector-copy!}, one in
@code{scheme.base} and one in @code{scheme.bytevector}).

It's unfortunate
that R6RS tends to break tradition and invent a new API; here, the
arguments differ from other @code{*-copy!} procedures:
This procedure copies from @var{src}, starting from
@var{sstart} and length @var{len}, to @var{target} starting @var{tstart}.
@end defun

@defun bytevector-append bv @dots{}
@{@t{gauche.uvector}@}
[R7RS base]
Alias of @code{u8vector-append}.  All arguments must be bytevectors
(u8vectors).  Returns a fresh bytevector whose elements are
the concatenation of elements of @var{bv} @dots{}.
@end defun

@defun bytevector=? bv1 bv2
@{@t{gauche.uvector}@}
[R7RS bytevector]
Alias of @code{u8vector=?}.  All arguments must be bytevectors
(u8vectors).  Returns @code{#t} iff all bytevectors are of the same
size and content.
@end defun

@defun bytevector->u8-list bv
@defunx u8-list->bytevector list
[R7RS bytevector]
Convert a u8vector to a list of bytes, and vice versa.
Same as @code{u8vector->list} and @code{list->u8vector}, except to not
taking optional @var{start}/@var{end} arguments.
@end defun


@c ----------------------------------------------------------------------
@node Comparing version numbers, Virtual ports, Uniform vector library, Library modules - Gauche extensions
@section @code{gauche.version} - Comparing version numbers
@c NODE バージョン番号の比較, @code{gauche.version} - バージョン番号の比較

@deftp {Module} gauche.version
@mdindex gauche.version
This module provides a convenient procedure to compare
@emph{version numbers} or @emph{revision numbers},
such as "@code{0.5.1}", "@code{3.2-3}" or "@code{8.2pl1}".
Usually each release of software component has
a version number, and you can define order between them.
For example, version "1.2.3" is newer than "1.2" and
older than "2.1".   You can compare those version numbers like this:

@example
(version<? "2.2.3" "2.2.11")     @result{} #t
(version<? "2.3.1" "2.3")        @result{} #f
(version<? "2.3.1-1" "2.3.1-10") @result{} #t
(version<? "13a" "5b")           @result{} #f
@end example

There are no standard way to name versions, so I chose
one convention.   This won't work for all possible
variations, but I think it covers typical cases.

Strictly speaking, you can only define partial order between
version numbers, for there can be branches.   This module
uses simple measure and just assumes the version numbers
can be fully ordered.

The version number here is defined by the following syntax.
@example
 <version> : <principal-release>
           | <version> <post-subrelease>
           | <version> <pre-subrelease>
 <principal-release> : <relnum>
 <post-subrelease>   : [.-] <relnum>
 <pre-subrelease>    : _ <relnum>?
 <relnum>            : [0-9A-Za-z]+
@end example

Typically @code{<relnum>} is composed by numeric part and extension part.
For example, "23a" is composed by an integer 23 and extension "a".
If @code{<relnum>} doesn't begins with digits, we assume its
numeric part is -1.

Then, the order of @code{<relnum>} is defined as follows:
@enumerate
@item
If relnum A and relnum B have different numeric part, we ignore the
extension and order them numerically, e.g.  "@code{3b}" < "@code{4a}".
@item
If relnum A and relnum B have the same numeric part, we compare
extension by alphabetically, e.g.  "@code{4c}" < "@code{4d}"
and "@code{5}" < "@code{5a}".
@end enumerate

Given the order of @code{<relnum>}, the order of version numbers
are defined as follows:
@enumerate
@item
Decompose each version number into a list of @code{<principal-release>} and
subsequence subrelease components.   We call each element of
the list "release components".
@item
If the first release component of both lists are the same,
remove it from both.  Repeat this until the head of the lists differ.
@item
Now we have the following cases.
@enumerate
@item
Both lists are empty: versions are the same.
@item
One list (A) is empty and the other list (B) has post-subrelease
at head: A is prior to B
@item
One list (A) is empty and the other list (B) has pre-subrelease
at head: B is prior to A
@item
List A's head is post-subrelease and list B's head is
pre-subrelease: B is prior to A
@item
Both lists have post-subrelease or pre-subrelease at head:
compare their relnums.
@end enumerate
@end enumerate
Here are some examples:
@example
"1" < "1.0" < "1.1" < "1.1.1" < "1.1.2" < "1.2" < "1.11"
"1.2.3" < "1.2.3-1" < "1.2.4"
"1.2.3" < "1.2.3a" < "1.2.3b"
"1.2_" < "1.2_rc0" < "1.2_rc1" < "1.2" < "1.2-pl1" < "1.2-pl2"
"1.1-patch112" < "1.2_alpha"
@end example

The reason of having @code{<pre-subrelease>} is to allow
"release candidate" or "pre-release" version.

A trick: If you want ``version 1.2 release or later'', you
can say @code{(version<=? "1.2" v)}.  This excludes prerelease
versions such as @code{1.2_pre3}.
If you want ``version 1.2 release or later'', 
you can say @code{(version<=? "1.2_" v)}, which includes
@code{1.2_pre1} etc., but excludes anything below, such as
@code{1.1.99999}.

It is common if you want to specify acceptable versions with
combination of conditions, e.g. ``version 1.3 or later, except
version 1.4.1'' or ``greater than version 1.1 and below 1.5''.
A @emph{version spec} is an S-expression to represent that condition.
You can use @code{version-satisfy?} to check if given version
satisfies the spec.

The syntax of version spec is as follows.

@example
<version-spec> : <version>
               | (<op> <version>)
               | (and <version-spec> ...)
               | (or <version-spec> ...)
               | (not <version-spec>)

<version> : version string
<op>      : = | < | <= | > | >=
@end example

@end deftp

@defun version=? ver1 ver2
@defunx version<? ver1 ver2
@defunx version<=? ver1 ver2
@defunx version>? ver1 ver2
@defunx version>=? ver1 ver2
@{@t{gauche.version}@}
Returns a boolean value depending on the order of two version number
string @var{ver1} and @var{ver2}.  If the arguments contain invalid
strings as the defined version number, an error is signaled.
@end defun

@defun version-compare ver1 ver2
@{@t{gauche.version}@}
Compares two version number strings @var{ver1} and @var{ver2},
and returns either -1, 0, or 1, depending whether @var{ver1} is
prior to @var{ver2}, @var{ver1} is the same as @var{ver2}, or
@var{ver1} is after @var{ver2}, respectively.
@end defun

@defun relnum-compare rel1 rel2
@{@t{gauche.version}@}
This is lower-level procedure of @code{version-compare}.  Compares
two release numbers (relnums) @var{rel1} and @var{rel2},
and returns either -1, 0, or 1 depending whether  @var{rel1} is
prior to @var{rel2}, @var{rel1} is the same as @var{rel2}, or
@var{rel1} is after @var{rel2}, respectively.
@end defun

The following procedures are to check if a given version
satisfies a version specification.

@defun valid-version-spec? spec
@{@t{gauche.version}@}
This is a syntax checker.  Returns @code{#t} if @var{spec} is
a valid version specification, @code{#f} otherwise.
See @code{gauche.version} module description for the definition of
version specification.
@end defun

@defun version-satisfy? spec version
@{@t{gauche.version}@}
Returns @code{#t} if @var{version} satisfies
a version specification @var{spec}, @code{#f} otherwise.
See @code{gauche.version} module description for the definition of
version specification.
@end defun



@c ----------------------------------------------------------------------
@node Virtual ports,  , Comparing version numbers, Library modules - Gauche extensions
@section @code{gauche.vport} - Virtual ports
@c NODE 仮想ポート, @code{gauche.vport} - 仮想ポート

@deftp {Module} gauche.vport
@mdindex gauche.vport
@emph{Virtual ports}, or procedural ports, are the ports
whose behavior can be programmed in Scheme.

This module provides two kinds of virtual ports:
Fully virtual ports, in which every I/O operation invokes
user-provided procedures, and virtual buffered ports,
in which I/O operations are done on an internal buffer and
user-provided procedures are called only when the buffer
needs to be filled or flushed.

This module also provides virtual buffered ports backed up
by a uniform vector, as an example of the feature.
@end deftp

@subsubheading Fully virtual ports

This type of virtual ports are realized by classes
@code{<virtual-input-port>} and @code{<virtual-output-port>}.
You can customize the port behavior by setting
appropriate slots with procedures.

@deftp {Class} <virtual-input-port>
@clindex virtual-input-port
@{@t{gauche.vport}@}
An instance of this class can be used as an input port.
The behavior of the port depends on the settings of the
instance slot values.

To work as a meaningful input port, at least either one of
@code{getb} or @code{getc} slot must be set.  Otherwise,
the port returns EOF for all input requests.

@defivar {<virtual-input-port>} getb
If set, the value must be a procedure that takes no arguments.
Every time binary input is required, the procedure is called.

The procedure must return an exact integer between 0 and 255
inclusive, or @code{#f} or an EOF object.  If it returns an
integer, it becomes the value read from the port.  If it returns
other values, the port returns EOF.

If the port is requested a character input and it doesn't have
the @code{getc} procedure, the port calls this procedure, possibly
multiple times, to construct a whole character.
@end defivar

@defivar {<virtual-input-port>} getc
If set, the value must be a procedure that takes no arguments.
Every time character input is required, the procedure is called.

The procedure must return a character,
@code{#f} or an EOF object.  If it returns a character,
it becomes the value read from the port.  If it returns
other values, the port returns EOF.

If the port is requested a binary input and it doesn't have
the @code{getb} procedure, the port calls this procedure, then converts
a character into a byte sequence, and use it as the binary
value(s) read from the port.
@end defivar

@defivar {<virtual-input-port>} gets
If set, the value must be a procedure that takes one argument,
a positive exact integer.  It is called when the block binary
input, such as @code{read-uvector}, is requested.
It must return a (maybe incomplete) string up to the specified size,
or @code{#f} or EOF object.  If it returns a null string, @code{#f}
or EOF object,
the port thinks it reached EOF.  If it returns other string,
it is used as the result of block read.
It shouldn't return a string larger than the given size
(Note: you must count size (bytes), not the number of characters).
The reason of this procedure is efficiency; if this procedure
is not provided, the port calls @code{getb} procedure repeatedly
to prepare the block of data.  In some cases, providing block input
can be much more efficient (e.g. suppose you're reading from
a block of memory chunk).

You can leave this slot unset if you don't need to take such
advantage.
@end defivar

@defivar {<virtual-input-port>} ready
If set, the value must be a procedure that takes one boolean argument.
It is called when @code{char-ready?} or @code{byte-ready?} is
called on the port.   The value returned from your procedure will
be the result of these procedures.

The boolean argument is @code{#t} if
@code{char-ready?} is called, or @code{#f} if @code{byte-ready?} is called.

If unset, @code{char-ready?} and @code{byte-ready?}
always return @code{#t} on the port
@end defivar

@defivar {<virtual-input-port>} close
If set, the value must be a procedure that takes no arguments.
It is called when the port is closed.  Return value is discarded.
You can leave this unset
if you don't need to take an action when the port is closed.

This procedure may be called from a finalizer, so you have to be
careful to write it.   See the note on finalization below.
@end defivar

@defivar {<virtual-input-port>} seek
If set, the value must be a procedure that takes two arguments,
offset and whence.  The meaning of them is the same as the arguments
to @code{port-seek} (@pxref{Common port operations}).
The procedure must adjust the port's internal read pointer
so that the next read begins from the new pointer.
It should return the updated pointer (the byte offset from the
beginning of the port).

If unset, call of @code{port-seek} and @code{port-tell} on this
port will return @code{#f}.

Note that this procedure may be called for the purpose of merely
querying the current position, with 0 as @code{offset} and @code{SEEK_CUR}
as @code{whence}.  If your port knows the read pointer but cannot move it,
you can still provide this procedure, which returns the current pointer
position for such queries and returns @code{#f} for other arguments.
@end defivar

@end deftp


@deftp {Class} <virtual-output-port>
@clindex virtual-output-port
@{@t{gauche.vport}@}
An instance of this class can be used as an output port.
The behavior of the port depends on the settings of the
instance slot values.

To work as an output port, at least either one of @code{putb} or
@code{putc} slot has to be set.

@defivar {<virtual-output-port>} putb
If set, the value must be a procedure that takes one argument,
a byte value (exact integer between 0 and 255, inclusive).
Every time binary output is required, the procedure is called.
The return value of the procedure is ignored.

If this slot is not set and binary output is requested,
the port may signal an @code{<io-unit-error>} error.
@end defivar

@defivar {<virtual-output-port>} putc
If set, the value must be a procedure that takes one argument,
a character.
Every time character output is required, the procedure is called.
The return value of the procedure is ignored.

If this slot is not set but @code{putb} slot is set,
the virtual port decomposes the character into a sequence of bytes
then calls @code{putb} procedures.
@end defivar

@defivar {<virtual-output-port>} puts
If set, the value must be a procedure that takes a
(possibly incomplete) string.
The return value of the procedure is ignored.

This is for efficiency.  If this slot is not set, the virtual port
calls @code{putb} or @code{putc} repeatedly to output a chunk of data.
But if your code can perform chunked output efficiently,
you can provide this procedure.
@end defivar

@defivar {<virtual-output-port>} flush
If set, the value must be a procedure that takes no arguments.
It is called when flushing a port is required (e.g. @code{flush}
is called on the port, or the port is being closed).

This procedure is useful that your port does some sort of buffering,
or needs to keep some state.  If your port doesn't do stateful operation,
you can leave this unset.

This procedure may be called from a finalizer, and needs a special
care.  See notes on finalizers below.

@end defivar

@defivar {<virtual-output-port>} close
The same as @code{<virtual-input-port>}'s @code{close} slot.
@end defivar

@defivar {<virtual-output-port>} seek
The same as @code{<virtual-input-port>}'s @code{seek} slot.
@end defivar

@end deftp

@subsubheading Virtual buffered ports

This type of virtual ports are realized by classes
@code{<buffered-input-port>} and @code{<buffered-output-port>}.
You can customize the port behavior by setting
appropriate slots with procedures.

Those ports have internal buffer and only calls Scheme procedures
when the buffer needs to be filled or flushed.  Generally it is
far more efficient than calling Scheme procedures for every
I/O operation.   Actually, the internal buffering mechanism is
the same as Gauche's file I/O ports.

These ports uses @code{u8vector} as a buffer.  See @ref{Uniform vectors}
for the details.

@deftp {Class} <buffered-input-port>
@clindex buffered-input-port
@{@t{gauche.vport}@}
An instance of this class behaves as an input port.
It has the following instance slots.  For a meaningful input
port, you have to set at least @code{fill} slot.

@defivar {<buffered-input-port>} fill
If set, it must be a procedure that takes one argument,
a @code{u8vector}.  It must fill the data from the
beginning of the vector.  It doesn't need to fill the entire
vector if there's not so many data.  However, if there are remaining
data, it must fill at least one byte; if the data isn't readily
available, it has to wait until some data becomes available.

The procedure must return a number of bytes it actually filled.
It may return 0 or an EOF object to indicate the port has reached EOF.
@end defivar

@defivar {<buffered-input-port>} ready
If set, it must be a procedure that takes no arguments.
The procedure must return a true value if there are some data
readily available to read, or @code{#f} otherwise.
Unlike fully virtual ports, you don't need to distinguish
binary and character I/O.

If this slot is not set, the port is regarded as it always has data ready.
@end defivar

@defivar {<buffered-input-port>} close
If set, it must be a procedure that takes no arguments.
The procedure is called when the virtual buffered port is closed.
You don't need to set this slot unless you need some cleaning up
when the port is closed.

This procedure may be called from a finalizer, and
needs special care.  See the note on finalization below.
@end defivar

@defivar {<buffered-input-port>} filenum
If set, it must be a procedure that returns underlying
file descriptor number (exact nonnegative integer).
The procedure is called when @code{port-file-number} is called
on the port.

If there's no such underlying file descriptor, you can
return @code{#f}, or you can leave this slot unset.
@end defivar

@defivar {<buffered-input-port>} seek
If set, it must be a procedure that takes two arguments,
@var{offset} and @var{whence}.
It works the same way as @code{<virtual-input-port>}'s seek procedure;
see above.

This procedure may be called from a finalizer, and
needs special care.  See the note on finalization below.
@end defivar

Besides those slot values, you can pass an exact nonnegative integer
as the @code{:buffer-size} keyword argument to the @var{make} method
to set the size of the port's internal buffer.  If @code{:buffer-size}
is omitted, or zero is passed, the system's default buffer size
(something like 8K) is used.  @code{:buffer-size} is not an instance
slot and you cannot set it after the instance of the buffered port
is created.   The following example specifies the buffered port
to use a buffer of size 64K:

@example
(make <buffered-input-port> :buffer-size 65536 :fill my-filler)
@end example
@end deftp

@deftp {Class} <buffered-output-port>
@clindex buffered-output-port
@{@t{gauche.vport}@}
An instance of this class behaves as an output port.
It has the following instance slots.
You have to set at least @code{flush} slot.

@defivar {<buffered-output-port>} flush
If set, it must be a procedure that takes two arguments,
an @code{u8vector} buffer and a flag.
The procedure must output data in the buffer to somewhere,
and returns the number of bytes actually output.

If the flag is false, the procedure may output less
than entire buffer (but at least one byte).  If the flag
is true, the procedure must output entire buffer.
@end defivar

@defivar {<buffered-output-port>} close
Same as @code{<buffered-input-port>}'s @code{close} slot.
@end defivar

@defivar {<buffered-output-port>} filenum
Same as @code{<buffered-input-port>}'s @code{filenum} slot.
@end defivar

@defivar {<buffered-output-port>} seek
Same as @code{<buffered-input-port>}'s @code{seek} slot.
@end defivar

Besides those slot values, you can pass an exact nonnegative integer
as the @code{:buffer-size} keyword argument to the @var{make} method
to set the size of the port's internal buffer.  See the description
of @code{<buffered-input-port>} above for the details.

@end deftp

@subsubheading Uniform vector ports

The following two procedures return a buffered input/output port
backed up by a uniform vector.    The source or destination vector
can be any type of uniform vector, but they will be aliased
to @code{u8vector} (see @code{uvector-alias} in
@ref{Uvector conversion operations}).

If used together with @code{pack}/@code{unpack}
(see @ref{Packing binary data}), it is useful to parse
or construct binary data structure.  It is also an
example of using virtual ports; read @file{gauche/vport.scm}
(or @file{ext/vport/vport.scm} in the source tree) if you're
curious about the implementation.

@defun open-input-uvector uvector
@{@t{gauche.vport}@}
Returns an input port that reads the content of the given
uniform vector @var{uvector} from its beginning.  If reading
operation reaches the end of @var{uvector}, EOF is returned.
Seek operation is also implemented.
@end defun

@defun open-input-bytevector u8vector
[R7RS base]
@{@t{gauche.vport}@}
Similar to @code{open-input-uvector},
but the argument must be an u8vector.
This is an R7RS base procedure.
@end defun

@defun open-output-uvector :optional uvector :key extendable
@{@t{gauche.vport}@}
Returns an output port that uses the given uvector as the
storage for the data output to the port.

If @var{uvector} is completely filled, what happens after that
depends on @var{extendable} - if it is false (default), the rest
of data is discarded silently.  If it is true, the storage is
extended automatically to accommodate more data.

If you give true value to @var{extendable}, you have to retrieve
the result by @code{get-output-uvector} below, since the uvector
you passed in won't contain spilled data.

As a special case, you can omit @var{uvector} argument; then
@code{u8vector} is used as the storage.  In that case
you can't specify @var{extendable} keyword argument, but it is
assumed true, since it won't make sense otherwise.  Use
@code{get-output-uvector} to retrieve the stored result.

Seek operation is also implemented.  Note that the meaning
of @code{SEEK_END} whence differ between extendable and
fixed-size uvector ports.  For extendable ports,
the end whence placed next to the biggest offset of
the data ever written; if you open a port and just write
one byte, the end whence is the second byte, no matter
how big the existing buffer is.  On the other hand,
for fixed-size uvector ports, end whence is fixed to
the next to the end of the given buffer, no matter
how much data you've written to it.  In the latter case,
you can't seek on or past the end (you need to pass negative
number along @code{SEEK_END} to @code{port-seek}).
@end defun

@defun open-output-bytevector
[R7RS base]
@{@t{gauche.vport}@}
Same as @code{open-output-uvector} without arguments.
Uses extenable u8vector as the buffer.
This is an R7RS base procedure.
@end defun

@defun get-output-uvector port :key shared
@{@t{gauche.vport}@}
If @var{port} is a port created by @code{open-output-uvector}, returns
a @var{uvector} that contains accumulated data.
If @var{port} is not a port created by @code{open-output-uvector},
@code{#f} is returned.

The returned uvector is the same type as the one passed to
@code{open-output-uvector}, containing up to actually written data; it may
be smaller than the @var{uvector} passed to @code{open-output-uvector};
it can be larger if the port is extendable.

If the type of uvector is other than @code{s8vector} and @code{u8vector},
and the written data doesn't fill up the whole element won't be
in the result.
For example, if you use @code{s32vector} to create the port,
then write 7 bytes to it, @code{get-output-uvector} returns a
single element @code{s32vector}, for the last 3 bytes does not
consist a whole 32bit integer.

By default, the returned vector is a fresh copy of the contents.
Passing true value to @var{shared} may avoid copying and allow
sharing storage for the one being used by @var{port}.  If you do so,
keep in mind that if you seek back and write to @var{port} subsequently,
the content of returned vector may be changed.
@end defun

@defun get-output-bytevector port
[R7RS base]
@{@t{gauche.vport}@}
Extract the data put to an bytevector output port as an u8vector.
The port must be created by @code{open-output-bytevector} or
@code{open-output-uvector}.
This is an R7RS base procedure.
@end defun


@subsubheading List ports

The following procedures allow you to use list of characters
or octets as a source of an input port.  These are (a kind of)
opposite of @code{port->list} family
(@pxref{Input utility functions}) or @code{port->char-lseq} family
(@pxref{Lazy sequences}).

@defun open-input-char-list char-list
@defunx open-input-byte-list byte-list
@{@t{gauche.vport}@}
Creates and returns an input port that uses
the given list of characters and bytes as the source.

@example
(read (open-input-char-list '(#\a #\b)))
 @result{} ab
@end example
@end defun

@defun get-remaining-input-list port
@{@t{gauche.vport}@}
If @var{port} is the one created by @code{open-input-char-list} 
or @code{open-input-byte-list}, returns a list of remaining data
that hasn't been read yet.  If the port already read everything,
or the port is not the one created by @code{open-input-char-list} 
or @code{open-input-byte-list}, an empty list is returned.

A caveat: Gauche allows mixing binary input and textual input from
the same port.  If you read or even peek a byte from a port
created from a character list, the port buffers a character
and disassembles it to bytes; the disassembled character
may not be included in the remaining input list.
@end defun

@subsubheading Generator ports

The following procedures allow you to use character generators
or byte generators as a source of an input port.  These are (a kind of)
opposite of @code{port->char-generator} family
(@pxref{Generator constructors}).

@defun open-input-char-generator cgen
@defunx open-input-byte-generator bgen
@{@t{gauche.vport}@}
Creates and returns an input port that uses
the given generators as the source.  The @var{cgen} argument
must be a generator that yields characters.  The @var{bgen} argument
must be a generator that yields bytes (exact integers between 0 and
255, inclusive).
An error will be raised if the given generator yields
incorrect type of objects.

@example
(read (open-input-char-generator (string->generator "foo")))
 @result{} foo
@end example

Since the generators are objects relying on side effects,
you shouldn't use @var{cgen} or @var{bgen} after you pass them
to those procedures; if you use them afterwards, the result
is undefined.
@end defun

@defun get-remaining-input-generator port
@{@t{gauche.vport}@}
If @var{port} is the one created by @code{open-input-char-generator} 
or @code{open-input-byte-generator}, returns a generator that
yields the characters or bytes that haven't been read yet.
If the port already read everything, an empty generator
is returned.

Once you take the remaining input generator, you should no longer
read from the input generator ports; they share internal states and
mixing them will likely to cause unexpected behaviors.
If side-effects safe behavior is desired, use lazy sequence and
input list ports.
@end defun

@subsubheading Accumulator ports

Accumulators are dual to generators; it's a procedure that accepts a value
at a time, and the end of the value is indicated by EOF.
@xref{R7RS generators}, for the basic operations of accumulators.

The following procedures turns an accumulator that accepts characters
or octets into an output port.

@defun open-output-char-accumulator acc
@{@t{gauche.vport}@}
Returns an output port that sends the output characters to an
accumulator @code{acc}, which takes a character as the argument.
When the returned output port is closed, EOF is passed to @var{acc}.

Note: The behavior is undefined if you try to perform binary output
to the returned output port.
@end defun

@defun open-output-char-accumulator acc
@{@t{gauche.vport}@}
Returns an output port that sends the output bytes to an
accumulator @code{acc}, which takes a byte as the argument.
When the returned output port is closed, EOF is passed to @var{acc}.

A character sent to the output port is converted to octets in
the Gauche's native encoding.
@end defun

@defun open-output-accumulator acc
@{@t{gauche.vport}@}
The accumulator @var{acc} must accept a byte, a character or a string.
Returns an output port that sends the output data to the @var{acc}.
When the returned output port is closed, EOF is passed to @var{acc}.
@end defun

@subsubheading Note on finalization

If an unclosed virtual port is garbage collected, its close procedure
is called (in case of virtual buffered ports, its flush procedure
may also be called before close procedure).  It is done by
a finalizer of the port.  Since it is a part of garbage-collection
process (although the Scheme procedure itself is called outside of
the garbage collector main part), it requires special care.

@itemize @bullet
@item
It is possible that the object the virtual port has a reference
may already be finalized.  For example, if a virtual port @var{X}
holds the only reference to a @emph{sink} port @var{Y}, to which
the output goes.  @var{X}'s @code{flush} procedure sends its output to
@var{Y}.  However, if @code{flush} procedure can be called from a
finalizer, it may be possible that @var{Y}'s finalizer has already been
called and @var{Y} is closed.   So @var{X}'s @code{flush} procedure
has to check if @var{Y} has not been closed.

@item
You cannot know when and in which thread the finalizer runs.
So if the procedure like @code{close} or @code{flush} of virtual ports
need to lock or access the global resource, it needs to take
extra care of avoiding dead lock or conflict of access.

Even in single thread programs, the finalizer can run anywhere
in Scheme programs, so effectively it should be considered as
running in a different thread.
@end itemize

@c Local variables:
@c mode: texinfo
@c coding: utf-8
@c end:
@node Library modules - R7RS standard libraries, Library modules - SRFIs, Library modules - Gauche extensions, Top
@chapter Library modules - R7RS standard libraries

@c NODE ライブラリモジュール - R7RS標準ライブラリ

Gauche predates R7RS, and for the convenience, Gauche makes quite a few
procedures as built-in (@pxref{Core library}).  Although the set of
Gauche's core features are mostly superset of R7RS, some functions
and syntaxes have different names and/or interface from R7RS.

R7RS fully-compatible syntaxes and functions are available
in the set of modules described in this chapter.  Since R7RS
programs and libraries needs to follow a specific format
(@code{import} declaration or @code{define-library} form),
generally there's no ambiguity in whether you're looking at R7RS code
or Gauche-specific code.  Also, it is totally transparent to load
R7RS library into Gauche-specific code or vice versa.
However, you need to be aware of which ``world'' you're in when
you code.

If you're familiar with Gauche, take a look at
the section @ref{R7RS integration}, which describes how you can
go back and forth between Gauche and R7RS.

@menu
* R7RS integration::
* R7RS small language::
* R7RS large::
@end menu


@node R7RS integration, R7RS small language, Library modules - R7RS standard libraries, Library modules - R7RS standard libraries
@section R7RS integration
@c NODE R7RS統合

@menu
* Traveling between two worlds back and forth::
* Three forms of import::
@end menu

@node Traveling between two worlds back and forth, Three forms of import, R7RS integration, R7RS integration
@subsection Traveling between two worlds back and forth
@c NODE 二つの世界を往き来する

When you start Gauche, either in REPL or as a script, you're in
@code{user} module, which @emph{inherits} @code{gauche} module.
Likewise, when you read a library, the initial module inherits
@code{gauche} module (until you call @code{select-module}).
That's why you can access all the built-in procedures of Gauche
without saying @code{(use something)}.  (@xref{Module inheritance}, for
the details about inheriting modules).

On the other hand, R7RS requires to be explicit about which namespaces
you'll be using, by @code{import} form, e.g. @code{(import (scheme base))}.
Besides, R7RS library must be explicitly enclosed by @code{define-library} form.
Before the first @code{import} form of a program, or outside of
@code{define-library}, is beyond R7RS world---the standard defines
nothings about it.

These facts let Gauche to set up appropriate ``world'',
and you can use R7RS code and traditional Gauche code transparently.

NB: As explained in @ref{Three forms of import},
R7RS @code{import} is rather different from Gauche
@code{import}, so we note the former @code{r7rs#import} and the latter
@code{gauche#import} in this section for clarity.  When you write code
don't use prefixes @code{r7rs#} and @code{gauche#}; just write @code{import}.

@subheading Loading R7RS libraries

The @code{define-library} form is defined as a macro in @code{gauche} module;
it sets up R7RS environment before evaluating its contents.
So, when you load an R7RS library (either from Gauche code via @code{use}
form, or from R7RS code via @code{r7rs#import} form),
Gauche starts loading the file in @code{gauche} module, but immediately
see @code{define-library} form, and the rest is handled in R7RS
environment.

Suppose you have an R7RS library @code{(mylib foo)} with the following code:

@example
(define-library (mylib foo)
  (import (scheme base))
  (export snoc)
  (begin
    (define (snoc x y) (cons y x))))
@end example

It should be saved as @file{mylib/foo.scm} in one of the directories in
@code{*load-path*}.

From R7RS code, this library can be loaded by @code{r7rs#import}:

@example
(import (mylib foo))

(snoc 1 2) @result{} (2 . 1)
@end example

To use this library from Gauche code, concatenate elements of library
names by @code{.} to get a module name, and @code{use} it:

@example
(use mylib.foo)

(snoc 1 2) @result{} (2 . 1)
@end example

@subheading Loading Gauche libraries

To use Gauche library @code{foo.bar} from R7RS code,
split the module name by @code{.} to make a list for the name
of the library.  For example, @code{gauche.lazy} module can be
used from R7RS as follows:

@example
(import (gauche lazy))
@end example

For SRFI modules, R7RS implementations have a convention to
name it as @code{(srfi n)}, and Gauche follows it.
The following code loads srfi-1 and srfi-13 from R7RS code:

@example
(import (srfi 1) (srfi 13))
@end example

(It's not that Gauche treat @code{srfi} name specially; installation
of Gauche includes adapter libraries such as @file{srfi/1.scm}.)

A tip: To use Gauche's built-in features (the bindings that are
available by default in Gauche code) from R7RS code, import
@code{(gauche base)} library (@pxref{Importing gauche built-ins}):

@example
(import (gauche base))

filter @result{} #<closure filter>
@end example

@subheading Running R7RS scripts

R7RS scripts always begin with @code{import} form.  However, @code{r7rs#import}
has a different syntax and semantics
from @code{gauche#import}---so we employ a trick.

When @code{gosh} is started, it loads the given script file
in @code{user} module.  We have a separate @code{user#import} macro, which
examines its arguments and if it is R7RS import syntax, switch to the
@code{r7rs.user} module and run the @code{r7rs#import}.  Otherwise, it
runs @code{gauche#import}.  @xref{Three forms of import}, for the details.

An example of R7RS script:

@example
(import (scheme base) (scheme write))
(display "Hello, world!\n")
@end example

If you're already familiar with Gauche scripts, keep in mind that
R7RS program doesn't treat @code{main} procedure specially; it
just evaluates toplevel forms from top to bottom.  So the following
script doesn't output anything:

@example
(import (scheme base) (scheme write))
(define (main args)
  (display "Hello, world!\n")
  0)
@end example

To access the command-line arguments in R7RS scripts, use
@code{command-line} in @code{(scheme process-context)} library
(@pxref{R7RS process context}, also @pxref{Command-line arguments}).

@subheading Using R7RS REPL

When @code{gosh} is invoked with @code{-r7} option and no script file is
given, it enters an R7RS REPL mode.  For the convenience, the following
modules (``libraries'', in R7RS term) are pre-loaded.

@example
(scheme base) (scheme case-lambda) (scheme char)
(scheme complex) (scheme cxr) (scheme eval)
(scheme file) (scheme inexact) (scheme lazy)
(scheme load) (scheme process-context) (scheme read)
(scheme repl) (scheme time) (scheme write)
@end example

Besides, the history variables @code{*1}, @code{*2}, @code{*3},
@code{*1+}, @code{*2+}, @code{*3+}, @code{*e} and @code{*history}
are available (@xref{Working in REPL}, for the details of history variables).

You can know you're in R7RS REPL by looking at the prompt, where
@code{gosh} shows the current module (@code{r7rs.user}):

@example
gosh[r7rs.user]>
@end example

To switch Gauche REPL from R7RS REPL, import @code{(gauche base)} and
select @code{user} module using @code{select-module}:

@example
gosh[r7rs.user]> (import (gauche base))
#<undef>
gosh[r7rs.user]> (select-module user)
#<undef>
gosh>
@end example

(You can @code{(select-module gauche)} but that's usually not what you
want to do---changing @code{gauche} module can have unwanted side effects.)

When you're working on R7RS code in file and load it into R7RS REPL
(for example, if you're using Emacs Scheme mode, C-c C-l does the job),
make sure the file is in proper shape as R7RS; that is, the file
must start with appropriate @code{import} declarations, or
the file contains @code{define-library} form(s).  If you load
file without those forms, it is loaded into Gauche's @code{user} module
no matter what your REPL's current module is,
and the definitions won't be visible from @code{r7rs.user} module
by default.

@subheading Switching from Gauche REPL

By default, @code{gosh} enters Gauche REPL when no script file is given.
@xref{Working in REPL}, for detailed explanation of using REPL.

To switch Gauche REPL to R7RS REPL, simply use r7rs-style import;
@code{user#import} knows you want R7RS and make a switch.

@example
gosh> (import (scheme base))
#<undef>
gosh[r7rs.user]>
@end example

If you don't start @code{gosh} with @code{-r7} option, however,
only the libraries you given to @code{user#import} are loaded at
this moment.

If you want to switch the ``vanilla'' r7rs environment, that is, even
not loading @code{(scheme base)}, then you can use @code{r7rs}
module and directly select @code{r7rs.user}:

@example
gosh> (use r7rs)
gosh> (select-module r7rs.user)
gosh[r7rs.user]>
@end example

If you do this, the only
bindings visible initially are @code{import} and @code{define-library};
even @code{define} is undefined!
You have to manually do @code{(import (scheme base))} etc. to start
writing Scheme in this environment.


@node Three forms of import,  , Traveling between two worlds back and forth, R7RS integration
@subsection Three import forms
@c NODE 3つのimport形式

For historical reasons, Gauche has three @code{import} forms; the original
Gauche's @code{import}, R7RS @code{import}, and the hybrid @code{import}.

Usually it is clear that the code is written in traditional Gauche
or in R7RS, and usage of @code{import} is typically idiomatic, so there's
not much confusion in practice.  Only when you talk about @code{import}
outside of code, you might need to specify which one you're talking.

The hybrid @code{import} is what we described @code{user#import} in
the previous section (@pxref{Traveling between two worlds back and forth}).
It understands both of Gauche's @code{import} and
R7RS @code{import}.
So what you really need to know is the first two.

Gauche's module system design is inherited from STk, and we've been
used @code{import} for purely name-space level operation; that is,
it assumes the module you import from already exists in memory.
Loading a file that defines the module (if necessary) is
done by separate primitives, @code{require}.  In most cases one file
defines one module, and using that module means @code{require} it then
@code{import} it (it's so common that Gauche has a macro for it---@code{use}).
However, separating those two sometimes comes handy when you need
some nontrivial hacks.  @xref{Using modules}, for the details of
Gauche's @code{import}.

R7RS leaves out the relation between modules (libraries) and files
in order to give implementation freedom.  If necessary, its @code{import}
must load a file implicitly and transparently.  So R7RS's @code{import}
is semantically Gauche's @code{use}.

The hybrid @code{import} only appears at the beginning of the Scheme
scripts.  It finds out whether the script is in the traditional Gauche
code or in the R7RS code.  @xref{Traveling between two worlds back and forth}, for the details.

Now we'll explain R7RS @code{import}:


@defspec import import-spec @dots{}
[R7RS]
Imports libraries specified by @var{import-spec}s.  What R7RS calls
libraries are what Gauche calls modules; they're the same thing.

R7RS libraries are named by a list of symbols or integers,
e.g. @code{(scheme base)} or @code{(srfi 1)}.
It is translated to Gauche's module name by joining the symbols
by periods; so, R7RS @code{(scheme base)} is Gauche's @code{scheme.base}.
Conversely, Gauche's @code{data.queue} is available as
@code{(data queue)} in R7RS.  To use those two libraries,
R7RS program needs this form at the beginning.

@example
(import (scheme base)
        (data queue))
@end example

It works just like Gauche's @code{use} forms; that is, if the named
module doesn't exist in the current process, it loads the file; then
the module's exported bindings become visible from the current module.

@example
(use scheme.base)
(use data.queue)
@end example

(You may wonder what if R7RS library uses symbols with periods in them.
Frankly, we haven't decided yet.   It'll likely be that we use some
escaping mechanism; for the time being you'd want to stick with
alphanumeric characters and hyphens as possible.)

Just like Gauche's @code{use}, you can select which symbols to be
imported (or not imported), rename specific symbols, or add
prefix to all imported symbols.  The formal syntax
of R7RS import syntax is as follows:

@smallexample
<import declaration> : (import <import-set> <import-set> ...)

<import-set> : <library-name>
  | (only <import-set> <identifier> <identifier> ...)
  | (except <import-set> <identifier> <identifier> ...)
  | (prefix <import-set> <identifier>)
  | (rename <import-set>
            (<identifier> <identifier>)
            (<identifier> <identifier>) ...)

<library-name> : (<identifier-or-base-10-integer>
                  <identifier-or-base-10-integer> ...)
@end smallexample
@end defspec

@node R7RS small language, R7RS large, R7RS integration, Library modules - R7RS standard libraries
@section R7RS small language
@c NODE R7RS small language

@menu
* R7RS library form::
* R7RS base library::           @code{scheme.base}
* R7RS case-lambda::            @code{scheme.case-lambda}
* R7RS char library::           @code{scheme.char}
* R7RS complex numbers::        @code{scheme.complex}
* R7RS cxr accessors::          @code{scheme.cxr}
* R7RS eval::                   @code{scheme.eval}
* R7RS file library::           @code{scheme.file}
* R7RS inexact numbers::        @code{scheme.inexact}
* R7RS lazy evaluation::        @code{scheme.lazy}
* R7RS load::                   @code{scheme.load}
* R7RS process context::        @code{scheme.process-context}
* R7RS read::                   @code{scheme.read}
* R7RS repl::                   @code{scheme.repl}
* R7RS time::                   @code{scheme.time}
* R7RS write::                  @code{scheme.write}
* R5RS compatibility::          @code{scheme.r5rs}
@end menu

@node R7RS library form, R7RS base library, R7RS small language, R7RS small language
@subsection R7RS library form
@c NODE R7RSライブラリ形式

R7RS libraries are defined by @code{define-library} form.

In R7RS view, @code{define-library} form itself does not belong
to a Scheme code---it exists outside of the Scheme world.
It defines the boundary of
R7RS Scheme; inside @code{define-library} there is R7RS world,
but outside, it's not a business of R7RS.
For example, you can't generate
@code{define-library} by a macro, within R7RS specification.

In Gauche, we implement R7RS world inside Gauche world;
@code{define-library} itself is interpreted in the Gauche world.
In fact, @code{define-library} @emph{is} a Gauche macro.
However, if you're writing portable R7RS code, you should forget
how @code{define-library} is implemented, and do not put anything
outside of @code{define-library} form.

@defmac define-library library-name library-decl @dots{}
[R7RS]
Defines a library @var{library-name}, which is a list of
symbols or base-10 integer:

@smallexample
<library-name> : (<identifier-or-base-10-integer>
                  <identifier-or-base-10-integer> ...)
@end smallexample

Library declarations @var{library-decl}
can be export declarations, import declarations,
@code{begin}-list of Scheme code,
include forms, or @code{cond-expand} forms.

@smallexample
<library-decl> : (export <export-spec> @dots{})
               | <import declaration>
               | (begin <command-or-definition> @dots{})
               | (include <string> <string2> @dots{})
               | (include-ci <string> <string2> @dots{})
               | (include-library-declarations
                        <string> <string2> @dots{})
               | (cond-expand <cond-expand-clause>
                              <cond-expand-clause2> @dots{})
               | (cond-expand <cond-expand-clause>
                              <cond-expand-clause2> @dots{}
                              (else <library-decl> @dots{}))
@end smallexample

The @code{export} declaration is the same Gauche's @code{export}
form; @pxref{Using modules}.

The @code{import} declaration is R7RS's @code{import} form,
described in @ref{Three forms of import}.

The @code{include} and @code{include-ci} declarations
are the same as Gauche's; @pxref{Inclusions}.
Note that Gauche allows any code to be included---the content of
the named file is simply wrapped with @code{begin} and
substituted with these forms---but in R7RS definition,
what you include must contain only Scheme code
(not one of the library declarations or @code{define-library} form).

The @code{include-library-declarations} declaration works like @code{include},
but the content of the read file is interpreted
as library declarations instead of Scheme code.

The @code{cond-expand} declaration is also the same as Gauche's;
@pxref{Feature conditional}.  When used directly below
@code{define-library}, it must expands to one of the
library declarations.
@end defmac


@node R7RS base library, R7RS case-lambda, R7RS library form, R7RS small language
@subsection @code{scheme.base} - R7RS base library
@c NODE R7RS基本ライブラリ, @code{scheme.base} - R7RS基本ライブラリ

@deftp {Module} scheme.base
@mdindex scheme.base
Exports bindings of R7RS @code{(scheme base)} library.  From R7RS programs,
those bindings are available by @code{(import (scheme base))}.
@end deftp

@subheading Bindings common to Gauche's built-ins

The following syntaxes and procedures are the same as Gauche's
builtins:

@table @asis
@item Primitive expression types
@example
quote if include include-ci lambda
@end example
@item Derived expression types
@example
cond case and or when unless cond-expand let let* letrec letrec*
let-values let*-values begin do make-parameter parameterize
guard quasiquote unquote unquote-splicing case-lambda
@end example
@item Macros
@example
let-syntax letrec-syntax syntax-rules syntax-error define-syntax
@end example
@item Variable definitions
@example
define define-values
@end example
@item Record type definitions
@example
define-record-type
@end example
@item Equivalence predicates
@example
eqv? eq? equal?
@end example
@item Numbers
@example
number? complex? real? rational? integer? exact? exact-integer?
= < > <= >= zero? positive? negative? odd? even? max min + * - / abs
floor/ floor-quotient floor-remainder
truncate/ truncate-quotient truncate-remainder
quotient modulo remainder gcd lcm numerator denominator
floor ceiling truncate round rationalize square exact-integer-sqrt
expt inexact exact number->string string->number
@end example
@item Booleans
@example
not boolean? boolean=?
@end example
@item Pairs and lists
@example
pair? cons car cdr set-car! set-cdr! caar cadr cdar cddr null? list?
make-list list length append reverse list-tail list-ref list-set!
memq memv member assq assv assoc list-copy
@end example
@item Symbols
@example
symbol? symbol=? symbol->string string->symbol
@end example
@item Characters
@example
char? char=? char<? char>? char<=? char>=? char->integer integer->char
@end example
@item Strings
@example
string? make-string string string-length string-ref string-set!
string=? string<? string>? string<=? string>=? substring string-append
string->list list->string string-copy string-copy! string-fill!
string-map string-for-each
@end example
@item Vectors
@example
vector? make-vector vector vector-length vector-ref vector-set!
vector->list list->vector vector->string string->vector
vector-copy vector-copy! vector-append vector-fill!
@end example
@item Control features
@example
procedure? apply map call-with-current-continuation call/cc
values call-with-values dynamic-wind
@end example
@item Exception
@example
error
@end example
@item Environments and evaluation
@example
scheme-report-environment null-environment
@end example
@item Input and output
@example
input-port? output-port? port? current-input-port current-output-port
current-error-port close-port close-input-port close-output-port
open-input-string open-output-string get-output-string
read-char peek-char read-u8 peek-u8
read-line eof-object? eof-object char-ready? u8-ready?
newline write-char write-u8
@end example
@end table

@subheading Bytevector utilities

R7RS's bytevectors are the same as Gauche's u8vectors.

The following procedures are the same as @code{gauche.uvector}'s
(@pxref{Bytevector compatibility}).

@example
bytevector         bytevector?       make-bytevector
bytevector-length  bytevector-u8-ref bytevector-u8-set!
bytevector-copy    bytevector-copy!  bytevector-append
read-bytevector    read-bytevector!  write-bytevector
@end example

The following procedures are the same as @code{gauche.vport}'s
(@pxref{Virtual ports}).

@example
open-input-bytevector open-output-bytevector get-output-bytevector
@end example

And the following procedures are the same as @code{gauche.unicode}'s
(@pxref{Unicode transfer encodings}).

@example
utf8->string       string->utf8
@end example

@subheading Control features

@defun with-exception-handler handler thunk
[R7RS base]
@{@t{scheme.base}@}
@var{handler} is evaluated in the dynamic environment of the call to
@var{handler}, except that the current exception handler is that in
place for the call to @code{with-exception-handler}.

If the exception is not continuable, it is reraised after evaluating
@var{handler} and handled by the exception handler in place for the
call to @code{with-exception-handler}.

This slightly differs from Gauche's built-in @code{with-exception-handler},
which calls @var{handler} without replacing the current exception handler.
@xref{Handling exceptions}, for the details.
@end defun

@defun raise obj
@defunx raise-continuable obj
[R7RS base]
@{@t{scheme.base}@}
Gauche's @code{raise} may return if @var{obj} isn't a
@code{<serious-condition>}.
Distinguishing continuable and noncontinuable exception throw by the
procedure has an issue when your exception handler wants to reraise
the condition (you don't know if the original condition is raised
by @code{raise} or @code{raise-continuable}!).  Yet R7RS adopted
that model, so we compel.

R7RS @code{raise} is a wrapper of Gauche's @code{raise},
which throws an error if Gauche's @code{raise} returns.

R7RS @code{raise-continuable} is currently just an alias of
Gauche's @code{raise}---as long as you don't pass
@code{<serious-condition>}, it may return.  It is not exactly
R7RS conformant---it won't return if you pass @code{<serious-condition>}
or object of one of its subclasses (e.g. @code{<error>}), but
it's weired to expect returning from raising @code{<error>}, isn't it?
@end defun

@defun error-object? exc
[R7RS base]
@{@t{scheme.base}@}
Defined as @code{(condition-has-type? exc <error>))}
@end defun

@defun error-object-message exc
[R7RS base]
@{@t{scheme.base}@}
If @var{exc} is a @code{<message-condition>},
returns its @code{message-prefix} slot;
otherwise, returns an empty string.
@end defun

@defun error-object-irritants exc
[R7RS base]
@{@t{scheme.base}@}
If @var{exc} is a @code{<message-condition>},
returns its @code{message-args} slot;
otherwise, returns an empty string.
@end defun

@defun read-error? exc
[R7RS base]
@{@t{scheme.base}@}
Defined as @code{(condition-has-type? e <read-error>))}.
@end defun

@defun file-error? exc
[R7RS base]
@{@t{scheme.base}@}
At this moment, Gauche doesn't have distinct @code{<file-error>} condition,
but most file errors are thrown as one of @code{<system-error>}s.
This procedure checks error code of @code{<system-error>} and
returns @code{#t} if the error is likely to be related to the filesystem.
@end defun

@subheading Input and output

@defun textual-port? port
@defunx binary-port? port
[R7RS base]
@{@t{scheme.base}@}
Gauche's port can handle both, so these are equivalent to @code{port?}.
@end defun

@defun input-port-open? iport
@defunx output-port-open? oport
[R7RS base]
@{@t{scheme.base}@}
Checks whether @var{iport}/@var{oport} is an input/output port @emph{and}
it is not closed.
@end defun


@defun flush-output-port :optional oport
[R7RS base]
@{@t{scheme.base}@}
An alias to @code{flush}.
@end defun

@defun features
[R7RS base]
@{@t{scheme.base}@}
Returns a list of symbols of supported feature identifiers,
recognized by @code{cond-expand} (@pxref{Feature conditional}).
@end defun


@node R7RS case-lambda, R7RS char library, R7RS base library, R7RS small language
@subsection @code{scheme.case-lambda} - R7RS case-lambda
@c NODE R7RS case-lambda, @code{scheme.case-lambda} - R7RS case-lambda

@deftp {Module} scheme.case-lambda
@mdindex scheme.case-lambda
Exports bindings of R7RS @code{(scheme case-lambda)} library.
From R7RS programs,
those bindings are available by @code{(import (scheme case-lambda))}.

The only binding exported from this module is @code{case-lambda},
and it is the same as Gauche's built-in @code{case-lambda};
@pxref{Making procedures} for the details.
@end deftp


@node R7RS char library, R7RS complex numbers, R7RS case-lambda, R7RS small language
@subsection @code{scheme.char} - R7RS char library
@c NODE R7RS文字ライブラリ, @code{scheme.char} - R7RS文字ライブラリ

@deftp {Module} scheme.char
@mdindex scheme.char
Exports bindings of R7RS @code{(scheme char)} library.
From R7RS programs,
those bindings are available by @code{(import (scheme char))}.
@end deftp

The following procedures are the same as Gauche's builtin procedures;
@pxref{Characters}.

@example
char-alphabetic? char-ci<=? char-ci<?  char-ci=? char-ci>=? char-ci>?
char-downcase char-foldcase char-lower-case? char-numeric?
char-upcase char-upper-case?  char-whitespace?
@end example

The following procedures are the same as the ones provided
in @code{gauche.unicode} module (@pxref{Full string case conversion}).
They use full case folding by Unicode standard (e.g. taking into
account of German eszett).

@example
string-ci<=? string-ci<?  string-ci=? string-ci>=?  string-ci>?
string-downcase string-foldcase string-upcase
@end example

@defun digit-value c
[R7RS char]
@{@t{scheme.char}@}
If @var{c} is a character with @code{Nd} general category---that is,
if it represents a decimal digit---this procedure returns the value
the character represents.  Otherwise it returns @code{#f}.

@example
(digit-value #\3) @result{} 3

(digit-value #\z) @result{} #f
@end example

Note that Unicode defines about two dozen sets of digit characters.

@example
(digit-value #\x11068) @result{} 2
@end example

Gauche's built-in procedure @code{digit->integer} has more general
interface (@pxref{Characters}).

@example
(digit-value c) @equiv{} (digit->integer c 10 #t)
@end example
@end defun

@node R7RS complex numbers, R7RS cxr accessors, R7RS char library, R7RS small language
@subsection @code{scheme.complex} - R7RS complex numbers
@c NODE R7RS複素数, @code{scheme.complex} - R7RS複素数

@deftp {Module} scheme.complex
@mdindex scheme.complex
Exports bindings of R7RS @code{(scheme complex)} library.
From R7RS programs,
those bindings are available by @code{(import (scheme complex))}.

This module provides the following bindings, all of which are
Gauche built-in (@pxref{Numerical conversions}).

@example
angle imag-part magnitude make-polar make-rectangular real-part
@end example
@end deftp


@node R7RS cxr accessors, R7RS eval, R7RS complex numbers, R7RS small language
@subsection @code{scheme.cxr} - R7RS cxr accessors
@c NODE R7RS cxrアクセサ, @code{scheme.cxr} - R7RS cxrアクセサ

@deftp {Module} scheme.cxr
@mdindex scheme.cxr
Exports bindings of R7RS @code{(scheme cxr)} library.
From R7RS programs,
those bindings are available by @code{(import (scheme cxr))}.

This module provides the following bindings, all of which are
Gauche built-in (@pxref{List accessors and modifiers}).

@example
caaar caadr cadar caddr cdaar cdadr cddar cdddr caaaar caaadr caadar
caaddr cadaar cadadr caddar cadddr cdaaar cdaadr cdadar cdaddr cddaar
cddadr cdddar cddddr
@end example
@end deftp

@node R7RS eval, R7RS file library, R7RS cxr accessors, R7RS small language
@subsection @code{scheme.eval} - R7RS eval
@c NODE R7RS eval, @code{scheme.eval} - R7RS eval

@deftp {Module} scheme.eval
@mdindex scheme.eval
Exports bindings of R7RS @code{(scheme eval)} library.
From R7RS programs,
those bindings are available by @code{(import (scheme eval))}.
@end deftp

@defun eval expr environment
[R7RS eval]
@{@t{scheme.eval}@}
This is the same as Gauche's built-in @code{eval} (@pxref{Eval and repl}).
@end defun

@defun environment import-list @dots{}
[R7RS eval]
@{@t{scheme.eval}@}
This is R7RS way to create an environment specifier suitable to pass
to @code{eval}.  In Gauche, an environment specifier is just a
module object.

The argument is the same as what @code{r7rs#import} takes.
This procedure creates an empty environment (as a fresh anonymous module;
see @code{make-module} in @ref{Module introspection}, for the details),
then imports the bindings as specified by @var{import-list}s.

The following example creates an environment that includes
@code{scheme.base} bindings plus @code{select-module} syntax from Gauche.

@example
(environment
 '(scheme base)
 '(only (gauche base) select-module))
 @result{} #<module #f>  ; an anonymous module
@end example
@end defun


@node R7RS file library, R7RS inexact numbers, R7RS eval, R7RS small language
@subsection @code{scheme.file} - R7RS file library
@c NODE R7RSファイルライブラリ, @code{scheme.file} - R7RSファイルライブラリ

@deftp {Module} scheme.file
@mdindex scheme.file
Exports bindings of R7RS @code{(scheme file)} library.
From R7RS programs,
those bindings are available by @code{(import (scheme file))}.
@end deftp

The following bindings provided in this module are
Gauche built-in (@pxref{File ports}, and @ref{File stats}).

@example
call-with-input-file call-with-output-file
file-exists?
open-input-file open-output-file
with-input-from-file with-output-to-file
@end example

The following binding is the same as one in @code{file.util}
(@pxref{File operations}).

@example
delete-file
@end example

@defun open-binary-input-file filename
@defunx open-binary-output-file filename
[R7RS file]
@{@t{scheme.file}@}
In Gauche, ports are both textual and binary at the same time,
so these R7RS procedures
are just aliases of @code{open-input-file} and @code{open-output-file},
respectively.  @xref{File ports}.
@end defun

@node R7RS inexact numbers, R7RS lazy evaluation, R7RS file library, R7RS small language
@subsection @code{scheme.inexact} - R7RS inexact numbers
@c NODE R7RS不正確数, @code{scheme.inexact} - R7RS不正確数

@deftp {Module} scheme.inexact
@mdindex scheme.inexact
Exports bindings of R7RS @code{(scheme inexact)} library.
From R7RS programs,
those bindings are available by @code{(import (scheme inexact))}.

This module provides the following bindings, all of which are
Gauche built-in (@pxref{Arithmetics}, and @ref{Numerical predicates}).

@example
acos asin atan cos exp finite? infinite? log nan? sin sqrt tan
@end example
@end deftp

@node R7RS lazy evaluation, R7RS load, R7RS inexact numbers, R7RS small language
@subsection @code{scheme.lazy} - R7RS lazy evaluation
@c NODE R7RS遅延評価, @code{scheme.lazy} - R7RS遅延評価

@deftp {Module} scheme.lazy
@mdindex scheme.lazy
Exports bindings of R7RS @code{(scheme lazy)} library.
From R7RS programs,
those bindings are available by @code{(import (scheme lazy))}.
@end deftp

The following bindings this module provides are Gauche built-ins
(@pxref{Delay force and lazy}).

@example
delay force promise?
@end example

@defspec delay-force promise
[R7RS lazy]
@{@t{scheme.lazy}@}
This is the same as Gauche's built-in @code{lazy}.
@pxref{Delay force and lazy} for the discussion about when this
form should be used.
@end defspec

@defun make-promise obj
[R7RS lazy]
@{@t{scheme.lazy}@}
If @var{obj} is a promise, it is returned as is.  Otherwise,
A promise, which yields @var{obj} when forced, is returned.
Because this is a procedure, expression passed as @var{obj} is
eagerly evaluated, so this doesn't have effect on lazy evaluation,
but can be used to ensure you have a promise.

This procedure is important on implementations where
@code{force} only takes a promise, and portable code should
use this procedure to yield a value that can be passed to @code{force}.

If you write Gauche-specific code, however, @code{force} can take
non-promise values, so you don't need this.
@end defun


@node R7RS load, R7RS process context, R7RS lazy evaluation, R7RS small language
@subsection @code{scheme.load} - R7RS load
@c NODE R7RS load, @code{scheme.load} - R7RS load

@deftp {Module} scheme.load
@mdindex scheme.load
Exports bindings of R7RS @code{(scheme load)} library.
From R7RS programs,
those bindings are available by @code{(import (scheme load))}.
@end deftp

@defun load file :optional env
[R7RS load]
@{@t{scheme.load}@}
R7RS @code{load} takes environment as an optional argument,
while Gauche @code{load} takes it as a keyword argument
(among other keyword arguments).  @xref{Loading Scheme file}.

In Gauche, @var{env} is just a module.  In portable code,
you can create a module with desired bindings with R7RS @code{environment}
procedure; @pxref{R7RS eval}.
@end defun


@node R7RS process context, R7RS read, R7RS load, R7RS small language
@subsection @code{scheme.process-context} - R7RS process context
@c NODE R7RSプロセスコンテキスト, @code{scheme.process-context} - R7RSプロセスコンテキスト

@deftp {Module} scheme.process-context
@mdindex scheme.process-context
Exports bindings of R7RS @code{(scheme process-context)} library.
From R7RS programs,
those bindings are available by @code{(import (scheme process-context))}.
@end deftp

The following bindings are the same as Gauche built-ins
(@pxref{Command-line arguments}, and @ref{Program termination}):

@example
command-line exit
@end example

The following bindings are the same as SRFI-98
(@pxref{Accessing environment variables}):

@example
get-environment-variable get-environment-variables
@end example

@defun emergency-exit :optional (obj 0)
[R7RS process-context]
@{@t{scheme.process-context}@}
Terminate the program without running any clean-up procedures
(@var{after} thunks of @code{dynamic-wind}).    I/O buffers won't
be flushed.
Internally,
it calls the @code{_exit(2)} system call directly.
The optional argument is used for the process exit code.
When omitted, 0 is assumed.

This is almost the same
as Gauche's @code{sys-exit}, except that @code{sys-exit} requires
the exit code argument (@pxref{Program termination}).
@end defun

@node R7RS read, R7RS repl, R7RS process context, R7RS small language
@subsection @code{scheme.read} - R7RS read
@c NODE R7RS read, @code{scheme.read} - R7RS read

@deftp {Module} scheme.read
@mdindex scheme.read
Exports bindings of R7RS @code{(scheme read)} library.
From R7RS programs,
those bindings are available by @code{(import (scheme read))}.

The only binding exported from this module is @code{read},
which is the same as Gauche's built-in.  @xref{Reading data}.
@end deftp

@node R7RS repl, R7RS time, R7RS read, R7RS small language
@subsection @code{scheme.repl} - R7RS repl
@c NODE R7RS repl, @code{scheme.repl} - R7RS repl

@deftp {Module} scheme.repl
@mdindex scheme.repl
Exports bindings of R7RS @code{(scheme repl)} library.
From R7RS programs,
those bindings are available by @code{(import (scheme repl))}.

The only binding exported from this module is @code{interaction-environment},
which is the same as Gauche's built-in.  @xref{Eval and repl}.
@end deftp


@node R7RS time, R7RS write, R7RS repl, R7RS small language
@subsection @code{scheme.time} - R7RS time
@c NODE R7RS time, @code{scheme.time} - R7RS time

@deftp {Module} scheme.time
@mdindex scheme.time
Exports bindings of R7RS @code{(scheme time)} library.
From R7RS programs,
those bindings are available by @code{(import (scheme time))}.
@end deftp

@defun current-second
[R7RS time]
@{@t{scheme.time}@}
Returns a real number represents the number of seconds since
the midnight of Jan. 1, 1970 TAI (which is 23:59:52, Dec 31, 1969 UTC, that
is, -8 seconds before Unix Epoch.)  Number of leap seconds were
inserted since then, and as of 2014, UTC is 35 seconds behind TAI.  That means
the number returned is 27 seconds larger than the unix time,
which is returned from @code{sys-time} or @code{sys-gettimeofday}.

The reason that R7RS adopts TAI is that it is monotonic and suitable
to take difference of two timepoints.  The unix time returned by
@code{sys-time} and @code{sys-gettimeofday} are defined in terms of
UTC date and time, so if the interval spans across leap seconds,
it won't reflect the actual number of seconds in the interval.
(The precise definition is given in section 4.15 of
IEEE Std 1003.1, 2013 Edition, a.k.a Single Unix Specification 4.)

However, since we don't know yet when the next leap second happen,
the current implementation just uses a fixed amount of offset
from the unix time.

Just be aware the difference, or you'll be surprised if you
pass the return value of @code{current-second} to the UTC time
formatter such as @code{sys-strftime}, or compare it with
the file timestamps which uses the unix time.  You can convert
between TAI and UTC using srfi-19 (@pxref{SRFI-19 Date}).
@end defun

@defun current-jiffy
[R7RS time]
@{@t{scheme.time}@}
Returns an exact integer measuring a real (wallclock) time elapsed
since some point in the past, which does not change while a
process is running.  The time unit is a @code{jiffies-per-second}-th
second.

The absolute value of current jiffies doesn't matter, but
the difference can be used to measure the time interval.
@end defun

@defun jiffies-per-second
[R7RS time]
@{@t{scheme.time}@}
Returns a constant to tell how many time units used in @code{current-jiffy}
consists of a second.  In the current Gauche implementation,
this is 10^9 on 64bit architectures
(that is, nanosecond resolution) and 10^4 on 32bit architectures
(100 microseconds resolution).

The resolution for 32bit architectures
is unfortunately rather coarse, but if we make it finer
the current jiffy value easily becomes bignums, taking time
to allocate and operate, beating the purpose of benchmarking.
With the current choice, we have 53,867 seconds since process start
before we spill into bignum on 32bit architecture.
On 64bit architectures we have enough bits
not to worry about bignums, with nanosecond resolution.

If you want to do more finer benchmarks on 32bit machines,
you need to roll your own with @code{sys-clock-gettime-monotonic} or
@code{sys-gettimeofday}.
@end defun


@node R7RS write, R5RS compatibility, R7RS time, R7RS small language
@subsection @code{scheme.write} - R7RS write
@c NODE R7RS write, @code{scheme.write} - R7RS write

@deftp {Module} scheme.write
@mdindex scheme.write
Exports bindings of R7RS @code{(scheme write)} library.
From R7RS programs,
those bindings are available by @code{(import (scheme write))}.

This module provides the following bindings, all of which are
Gauche built-in (@pxref{Object output}).

@example
display write write-shared write-simple
@end example
@end deftp

@node R5RS compatibility,  , R7RS write, R7RS small language
@subsection @code{scheme.r5rs} - R5RS compatibility
@c NODE R5RS compatibility, @code{scheme.r5rs} - R5RS互換性

@deftp {Module} scheme.r5rs
@mdindex scheme.r5rs
This module is to provide R5RS environment in R7RS programs.
The following bindings are exported.  Note that @code{lambda}
is @code{scheme#lambda}, without the support of
extended formals (@code{:optional} etc.)
@xref{Making procedures}, for the details of extended formals.

@example
* + - / < <= = > >= abs acos and angle append apply asin assoc assq
assv atan begin boolean? caaaar caaadr caaar caadar caaddr caadr
caar cadaar cadadr cadar caddar cadddr caddr cadr
call-with-current-continuation call-with-input-file
call-with-output-file call-with-values car case cdaaar cdaadr cdaar
cdadar cdaddr cdadr cdar cddaar cddadr cddar cdddar cddddr cdddr cddr
cdr ceiling char->integer char-alphabetic? char-ci<=? char-ci<?
char-ci=? char-ci>=? char-ci>? char-downcase char-lower-case?
char-numeric? char-ready? char-upcase char-upper-case? char-whitespace?
char<=? char<? char=? char>=? char>? char? close-input-port
close-output-port complex? cond cons cos current-input-port
current-output-port define define-syntax delay denominator display
do dynamic-wind eof-object? eq? equal? eqv? eval even? exact->inexact
exact? exp expt floor for-each force gcd if imag-part inexact->exact
inexact? input-port? integer->char integer? interaction-environment
lambda lcm length let let* let-syntax letrec letrec-syntax list
list->string list->vector list-ref list-tail list? load log magnitude
make-polar make-rectangular make-string make-vector map max member
memq memv min modulo negative? newline not null-environment null?
number->string number? numerator odd? open-input-file open-output-file
or output-port? pair? peek-char positive? procedure? quasiquote quote
quotient rational? rationalize read read-char real-part real? remainder
reverse round scheme-report-environment set! set-car! set-cdr! sin
sqrt string string->list string->number string->symbol string-append
string-ci<=? string-ci<? string-ci=? string-ci>=? string-ci>?
string-copy string-fill! string-length string-ref string-set!
string<=? string<? string=? string>=? string>? string? substring
symbol->string symbol? tan truncate values vector vector->list
vector-fill! vector-length vector-ref vector-set! vector?
with-input-from-file with-output-to-file write write-char zero?
@end example
@end deftp

@node R7RS large,  , R7RS small language, Library modules - R7RS standard libraries
@section R7RS large
@c NODE R7RS large

R7RS large is still under development, and we're gradually
adding support of the libraries that has been passed.

Currently R7RS-large has two editions (Red and Tangerine),
and Gauche supports them.

@menu
* R7RS lists::                  @code{scheme.list}
* R7RS vectors::                @code{scheme.vector}
* R7RS uniform vectors::        @code{scheme.vector.@@}
* R7RS sort::                   @code{scheme.sort}
* R7RS sets::                   @code{scheme.set}
* R7RS character sets::         @code{scheme.charset}
* R7RS hash tables::            @code{scheme.hash-table}
* R7RS immutable lists::        @code{scheme.ilist}
* R7RS random-access lists::    @code{scheme.rlist}
* R7RS immutable deques::       @code{scheme.ideque}
* R7RS immutable texts::        @code{scheme.text}
* R7RS generators::             @code{scheme.generator}
* R7RS lazy sequences::         @code{scheme.lseq}
* R7RS stream::                 @code{scheme.stream}
* R7RS boxes::                  @code{scheme.box}
* R7RS list queues::            @code{scheme.list-queue}
* R7RS ephemerons::             @code{scheme.ephemeron}
* R7RS comparators::            @code{scheme.comparator}
* R7RS regular expressions::    @code{scheme.regex}
* R7RS mappings::               @code{scheme.mapping}
* R7RS integer division::       @code{scheme.division}
* R7RS bitwise operations::     @code{scheme.bitwise}
* R7RS fixnum::                 @code{scheme.fixnum}
* R7RS flonum::                 @code{scheme.flonum}
* R7RS bytevectors::            @code{scheme.bytevector}
* R7RS combinator formatting::  @code{scheme.show}
@end menu

@node R7RS lists, R7RS vectors, R7RS large, R7RS large
@subsection @code{scheme.list} - R7RS lists
@c NODE R7RSリスト, @code{scheme.list} - R7RSリスト

@deftp {Module} scheme.list
@mdindex scheme.list
This module is a rich collection of list manipulation procedures,
and same as @code{srfi-1}.

Note that Gauche supports quite a few @code{scheme.list}
procedures as built-in.
The following procedures can be used
without loading @code{scheme.list} module.  For the manual entries of
these procedures, @ref{Pairs and lists}.

@example
null-list? cons* last member
take drop take-right drop-right take! drop-right!
delete delete! delete-duplicates delete-duplicates!
assoc alist-copy alist-delete alist-delete!
any every filter filter! fold fold-right find find-tail
split-at split-at! iota
@end example
@end deftp

@subsubheading List constructors

@defun xcons cd ca
[R7RS list]
@{@t{scheme.list}@}
Equivalent to @code{(cons ca cd)}.  Useful to pass to
higher-order procedures.
@end defun

@defun list-tabulate n init-proc
[R7RS list]
@{@t{scheme.list}@}
Constructs an @var{n}-element list, in which
each element is generated by @code{(@var{init-proc} @i{i})}.
@example
(list-tabulate 4 values) @result{} (0 1 2 3)
@end example
@end defun

@defun circular-list elt1 elt2 @dots{}
[R7RS list]
@{@t{scheme.list}@}
Constructs a circular list of the elements.
@example
(circular-list 'z 'q) @result{} (z q z q z q @dots{})
@end example
@end defun

@subsubheading List predicates

@defun not-pair? x
[R7RS list]
@{@t{scheme.list}@}
Same as @code{(lambda (x) (not (pair? x)))}.

SRFI-1 says: Provided as a procedure as it can be useful as
the termination condition for list-processing procedures that wish to
handle all finite lists, both proper and dotted.
@end defun

@defun list= elt= list @dots{}
[R7RS list]
@{@t{scheme.list}@}
Determines list equality by comparing every n-th element
of given lists by the procedure @var{elt=}.

It is an error to apply @code{list=} to anything except proper lists.

The equality procedure must be consistent with @code{eq?}, i.e.

@example
(eq? x y) @result{} (elt= x y).
@end example
@end defun

@subsubheading List selectors

@defun  first pair
@defunx second pair
@defunx third pair
@defunx fourth pair
@defunx fifth pair
@defunx sixth pair
@defunx seventh pair
@defunx eighth pair
@defunx ninth pair
@defunx tenth pair
[R7RS list]
@{@t{scheme.list}@}
Returns n-th element of the (maybe improper) list.
@end defun

@defun car+cdr pair
[R7RS list]
@{@t{scheme.list}@}
Returns two values, @code{(car pair)} and @code{(cdr pair)}.
@end defun

@subsubheading List miscellaneous routines

@defun zip clist1 clist2 @dots{}
[R7RS list]
@{@t{scheme.list}@}
Equivalent to @code{(map list clist1 clist2 @dots{})}.
If @code{zip} is passed @var{n} lists, it returns a list as long as
the shortest of these lists, each element of which is an @var{n}-element list
comprised of the corresponding elements from the parameter lists.

@example
(zip '(one two three)
     '(1 2 3)
     '(odd even odd even odd even odd even))
     @result{} ((one 1 odd) (two 2 even) (three 3 odd))

(zip '(1 2 3)) @result{} ((1) (2) (3))
@end example

At least one of the argument lists must be finite:

@example
(zip '(3 1 4 1) (circular-list #f #t))
     @result{} ((3 #f) (1 #t) (4 #f) (1 #t))
@end example
@end defun

@defun unzip1 list
@defunx unzip2 list
@defunx unzip3 list
@defunx unzip4 list
@defunx unzip5 list
[R7RS list]
@{@t{scheme.list}@}
@code{unzip1} takes a list of lists, where every list must
contain at least one element, and returns a list containing the
initial element of each such list.
@code{unzip2} takes a list of lists, where every list
must contain at least two elements, and returns two values:
a list of the first elements, and a list of the second
elements. @code{unzip3} does the same for the first
three elements of the lists, and so on.

@example
(unzip2 '((1 one) (2 two) (3 three))) @result{}
   (1 2 3) @r{and}
   (one two three)
@end example
@end defun

@subsubheading List fold, unfold & map

@defun pair-fold kons knil clist1 clist2 @dots{}
@defunx pair-fold-right kons knil clist1 clist2 @dots{}
[R7RS list]
@{@t{scheme.list}@}
Like @code{fold} and @code{fold-right}, but the procedure @var{kons}
gets each @code{cdr} of the given @var{clist}s, instead of @code{car}.

@example
(pair-fold cons '() '(a b c d e))
  @result{} ((e) (d e) (c d e) (b c d e) (a b c d e))

(pair-fold-right cons '() '(a b c d e))
  @result{} ((a b c d e) (b c d e) (c d e) (d e) (e))
@end example
@end defun

@defun unfold p f g seed :optional tail-gen
[R7RS list]
@{@t{scheme.list}@}
Fundamental recursive list constructor.
Defined by the following recursion.

@example
(unfold p f g seed tail-gen) @equiv{}
   (if (p seed)
       (tail-gen seed)
       (cons (f seed)
             (unfold p f g (g seed))))
@end example

That is, @var{p} determines where to stop, @var{g} is used to generate
successive seed value from the current seed value, and @var{f} is used
to map each seed value to a list element.

@example
(unfold (pa$ = 53) integer->char (pa$ + 1) 48)
  @result{} (#\0 #\1 #\2 #\3 #\4)
@end example
@end defun

@defun unfold-right p f g seed :optional tail
[R7RS list]
@{@t{scheme.list}@}
Fundamental iterative list constructor.
Defined by the following recursion.

@example
(unfold-right p f g seed tail) @equiv{}
  (let lp ((seed seed) (lis tail))
    (if (p seed)
        lis
        (lp (g seed) (cons (f seed) lis))))
@end example

@example
(unfold-right (pa$ = 53) integer->char (pa$ + 1) 48)
 @result{} (#\4 #\3 #\2 #\1 #\0)
@end example
@end defun

@defun map! f clist1 clist2 @dots{}
[R7RS list]
@{@t{scheme.list}@}
The procedure @var{f} is applied to each element of @var{clist1} and
corresponding elements of @var{clist2}s, and the result is collected
to a list.  Cells in @var{clist1} is reused to construct the result list.
@end defun

@defun map-in-order f clist1 clist2 @dots{}
[R7RS list]
@{@t{scheme.list}@}
A variant of @code{map}, but it guarantees to apply @var{f}
on each elements of arguments in a left-to-right order.
Since Gauche's @code{map} implementation follows the same order,
this function is just a synonym of @code{map}.
@end defun

@defun pair-for-each f clist1 clist2 @dots{}
[R7RS list]
@{@t{scheme.list}@}
Like @code{for-each}, but the procedure @var{f} is applied on
@var{clist}s themselves first, then each @code{cdr}s of them, and so on.

@example
(pair-for-each write '(a b c))
 @result{} @r{prints} (a b c)(b c)(c)
@end example
@end defun

@subsubheading List partitioning

@defun partition pred list
@defunx partition! pred list
[R7RS list]
@{@t{scheme.list}@}
@code{filter} and @code{remove} simultaneously, i.e.
returns two lists, the first is the result of filtering elements of
@var{list} by @var{pred}, and the second is the result of
removing elements of @var{list} by @var{pred}.
@example
(partition odd? '(3 1 4 5 9 2 6))
  @result{} (3 1 5 9) (4 2 6)
@end example
@code{partition!} is the linear-update variant.  It may destructively
modifies @var{list} to produce the result.
@end defun

@subsubheading List searching

@defun take-while pred clist
@defunx take-while! pred list
[R7RS list]
@{@t{scheme.list}@}
Returns the longest initial prefix of @var{clist} whose elements all
satisfy @var{pred}.
@end defun

@defun drop-while pred clist
[R7RS list]
@{@t{scheme.list}@}
Drops the longest initial prefix of @var{clist} whose elements all
satisfy @var{pred}, and returns the rest.
@end defun

@defun span pred clist
@defunx span! pred list
@defunx break pred clist
@defunx break! pred list
[R7RS list]
@{@t{scheme.list}@}
@code{span} is equivalent to
@code{(values (take-while pred clist) (drop-while pred clist))}.
@code{break} inverts the sense of @var{pred}.
@end defun

@defun list-index pred clist1 clist2 @dots{}
[R7RS list]
@{@t{scheme.list}@}
Returns the index of the leftmost element that satisfies @var{pred}.
If no element satisfies @var{pred}, @code{#f} is returned.
@end defun

@subsubheading Association lists

@defun alist-cons key datum alist
[R7RS list]
@{@t{scheme.list}@}
Returns @code{(cons (cons @var{key} @var{datum}) @var{alist})}.
This is an alias of the Gauche builtin procedure @code{acons}.
@end defun

@subsubheading Lists as sets

These procedures use a list as a set, that is,
the elements in a list matter, but their order doesn't.

All procedures in this category takes a comparison procedure
@var{elt=}, as the first argument, which is used to determine
two elements in the given sets are the same.

Since lists require linear time to search, those procedures aren't
suitable to deal with large sets.  @xref{R7RS sets}, if you
know your sets will contain more than a dozen items or so.

See also @ref{Combination library}, which
concerns combinations of elements in the set.

@defun lset<= elt= list1 @dots{}
[R7RS list]
@{@t{scheme.list}@}
Returns @code{#t} iff all elements in @var{list1} are also included
in @var{list2}, and so on.
If no lists are given, or a single list is given,
@code{#t} is returned.
@end defun

@defun lset= elt= list1 list2 @dots{}
[R7RS list]
@{@t{scheme.list}@}
Returns @code{#t} if all elements in @var{list1} are in @var{list2},
and all elements in @var{list2} are in @var{list1}, and so on.

@example
(lset= eq? '(b e a) '(a e b) '(e e b a)) @result{} #t
@end example
@end defun

@defun lset-adjoin elt= list elt @dots{}
[R7RS list]
@{@t{scheme.list}@}
Adds @var{elt} @dots{} to the set @var{list}, if each one is not
already a member of @var{list}.  (The order doesn't matter).

@example
(lset-adjoin eq? '(a b c) 'a 'e) @result{} '(e a b c)
@end example
@end defun

@defun lset-union elt= list1 @dots{}
[R7RS list]
@{@t{scheme.list}@}
Returns the union of the sets @var{list1} @dots{}.
@end defun

@defun lset-intersection elt= list1 list2 @dots{}
[R7RS list]
@{@t{scheme.list}@}
Returns a set of elements that are in every @var{list}s.
@end defun

@defun lset-difference elt= list1 list2 @dots{}
[R7RS list]
@{@t{scheme.list}@}
Returns a set of elements that are in @var{list1} but not
in @var{list2}.  In n-ary case, binary difference operation is
simply folded.
@end defun

@defun lset-xor elt= list1 @dots{}
[R7RS list]
@{@t{scheme.list}@}
Returns the exclusive-or of given sets; that is, the returned
set consists of the elements that are in either @var{list1} or @var{list2},
but not in both.   In n-ary case, binary xor operation is simply folded.
@end defun

@defun lset-diff+intersection elt= list1 list2 @dots{}
[R7RS list]
@{@t{scheme.list}@}
Returns two sets, a difference and an intersection of given sets.
@end defun

@defun lset-union! elt= list @dots{}
@defunx lset-intersection! elt= list1 list2 @dots{}
@defunx lset-difference! elt= list1 list2 @dots{}
@defunx lset-xor! elt= list1 @dots{}
@defunx lset-diff+intersection! elt= list1 list2 @dots{}
[R7RS list]
@{@t{scheme.list}@}
Linear update variant of the corresponding procedures.
The cells in the first list argument may be reused to construct the result.
@end defun

@node R7RS vectors, R7RS uniform vectors, R7RS lists, R7RS large
@subsection @code{scheme.vector} - R7RS vectors
@c NODE R7RSベクタ, @code{scheme.vector} - R7RSベクタ

@deftp {Module} scheme.vector
@mdindex scheme.vector
This module adds rich set of vector operations to the built-in / R7RS
vector procedures.

The following procedures are built-in.
@xref{Vectors}, for the description.  We only explain
the procedures that are not built-in.

@example
make-vector          vector               vector?
vector-ref           vector-set!          vector-length
vector-fill!         vector-copy          vector-copy!
vector-append        vector->list         list->vector
reverse-list->vector vector->string       string->vector
vector-map           vector-map!          vector-for-each
@end example

This module is @code{srfi-133}, which supersedes @code{srfi-43}
(@pxref{Vector library (Legacy)}).
Note that the interface of following procedures in @code{srfi-43}
are changed for the consistency:

@example
vector-map           vector-map!          vector-for-each
vector-fold          vector-fold-right    vector-count
@end example

Some of the functionalities
of @code{srfi-43} version is supported by built-in procedures
(e.g. Built-in @code{vector-map-with-index} is the same as
@code{srfi-43}'s @code{vector-map}).  So there's little point
for new code to use @code{srfi-43}.
@end deftp

@subheading Vector constructors

@defun vector-unfold f length seed @dots{}
[R7RS vector]
@{@t{scheme.vector}@}
Creates a vector of length @var{length}, filling elements
left to right by calling @var{f} repeatedly.

The procedure @var{f} must take as many arguments as
one plus number of seed values, and must return the same number
of values.  The first argument is the index.  The first return
value is used for the element of the result vector, and the
rest of return values are passed to the next call of @var{f}.

@example
(vector-unfold (^[i] (* i i)) 5)
 @result{} #(0 1 4 9 16)

(vector-unfold (^[i x] (values (cons i x) (* x 2))) 8 1)
 @result{} #((0 . 1) (1 . 2) (2 . 4) (3 . 8)
    (4 . 16) (5 . 32) (6 . 64) (7 . 128))
@end example

Note: This protocol is different from the list @code{unfold}
and most of other @code{*-unfold} constructors (@pxref{R7RS lists}).  
For fixed-length strcuctures like vectors,
it makes more sense to know the final length beforehand, rather than
checking the termination condition for each iteration.
@end defun

@defun vector-unfold-right f length seed @dots{}
[R7RS vector]
@{@t{scheme.vector}@}
Creates a vector of length @var{length}, filling elements
right to left by calling @var{f} repeatedly.

The procedure @var{f} must take as many arguments as
one plus number of seed values, and must return the same number
of values.  The first argument is the index.  The first return
value is used for the element of the result vector, and the
rest of return values are passed to the next call of @var{f}.

@example
(vector-unfold-right (^[i] (* i i)) 5)
 @result{} #(0 1 4 9 16)

(vector-unfold-right (^[i x] (values (cons i x) (* x 2))) 8 1)
 @result{} #((0 . 128) (1 . 64) (2 . 32) (3 . 16)
    (4 . 8) (5 . 4) (6 . 2) (7 . 1))
@end example
@end defun

@defun vector-reverse-copy vec :optional start end
[R7RS vector]
@{@t{scheme.vector}@}
Copies the vector @var{vec} with reversing its elements.
Optional @var{start} and @var{end} arguments can limit
the range of the input.

@example
(vector-reverse-copy '#(a b c d e) 1 4)
 @result{} #(d c b)
@end example
@end defun

@defun vector-concatenate list-of-vectors
[R7RS vector]
@{@t{scheme.vector}@}
Same as @code{(apply vector-append list-of-vectors)}.
@end defun

@defun vector-append-subvectors spec @dots{}
[R7RS vector]
@{@t{scheme.vector}@}
The number of arguments must be multiple of 3.  The argument list
must be in the following format, where each @var{vecN} is
a vector, and @code{startN} and @code{endN} are nonnegative exact integers:

@example
vec1 start1 end1 vec2 start2 end2 @dots{}
@end example

This procedure creates a new vector by concatenating subvectors
specified by each triplet.  That is, it works as if it's the following
code, except it avoids copying each subvector:

@example
(vector-append (vector-copy vec1 start1 end1)
               (vector-copy vec2 start2 end2)
               @dots{})
@end example

Here's an example:

@example
(vector-append-subvectors '#(a b c d e) 0 3
                          '#(f g h i j) 2 5)
  @result{} #(a b c h i j)
@end example
@end defun


@subheading Vector predicates

@defun vector-empty? vec
[R7RS vector]
@{@t{scheme.vector}@}
Returns @code{#t} if @var{vec}'s length is zero, and
@code{#f} if @var{vec}'s length is more than zero.
Signals an error if @var{vec} is not a vector.
@end defun

@defun vector= elt= vec @dots{}
[R7RS vector]
@{@t{scheme.vector}@}
Compares @var{vec}s element-wise, using given predicate @var{elt=}.
Returns @code{#t} iff lengths of all the vectors are the same,
and every corresponding elements are equal by @var{elt=}.

@var{Elt=} is always called with two arguments and must
return @code{#t} iff two are the same.

When zero or one vector is passed, @var{elt=} won't be called
and @var{vector=} always returns @code{#t}.
@end defun

@subheading Vector iteration

@defun vector-fold kons knil vec1 vec2 @dots{}
[R7RS vector]
@{@t{scheme.vector}@}
@var{Kons} is a procedure that takes @var{n}+1 arguments, where
@var{n} is the number of given vectors.  For each element of the
given vectors, @var{kons} is called as
@code{(@var{kons} @var{seed} @var{e_1i} @var{e_2i} @dots{})},
where and @var{e_ni} is the @var{i}-th element
of the vector @var{n}.  If the lengths of the vectors differ,
iteration stops when the shortest vector is exhausted.

The initial value of @var{seed} is @var{knil}, and the return value
from @var{kons} is used as the next seed value.  The last return value
of @var{kons} is returned from @code{vector-fold}.

The iteration is strictly left to right.

Note that the seed value precedes elements, which is opposite to
@code{fold} (@pxref{Mapping over collection}).  It's an unfortunate
historical glitch; @code{vector-fold-left} would be more consistent
name.

@example
(vector-fold (^[a b] (cons b a)) '() '#(a b c d))
  @result{} (d c b a)
@end example
@end defun

@defun vector-fold-right kons knil vec1 vec2 @dots{}
[R7RS vector]
@{@t{scheme.vector}@}
Like @code{vector-fold}, but elements in the @var{vec1} @var{vec2} @dots{}
are visited from right to left.

If the lengths of the vectors differ, this procedure only looks up to
the number of elements of the shortest vector and ignores any excessive
elements.  See the second example below.

Unlike @code{fold-right} (@pxref{Mapping over sequences}),
the procedure @var{kons} takes the seed value in the
first argument.

@example
(vector-fold-right (^[a b] (cons b a)) '() '#(a b c d))
  @result{} (a b c d)

(vector-fold-right (^[s x y] (cons (list x y) s)) '()
                   '#(a b c) '#(1 2 3 4))
  @result{} ((a 1) (b 2) (c 3))                   
@end example
@end defun

@defun vector-count pred vec1 vec2 @dots{}
[R7RS vector]
@{@t{scheme.vector}@}
Applies @var{pred} on each elements in argument vectors (if N vectors
are given, @var{pred} takes N arguments, the first being
@var{i}-th element of @var{vec1}, the second being @var{i}-th element
of @var{vec2}, etc.)  Then returns the number of times
@var{pred} returned true value.   The order @var{pred} applied
to each element is unspecified.

@example
(vector-count odd? '#(0 1 2 3 4)
  @result{} 2

(vector-count < '#(7 3 9 1 5) '#(6 8 2 3 8 8))
  @result{} 3
@end example
@end defun

@defun vector-cumulate f seed vec
[R7RS vector]
@{@t{scheme.vector}@}
Returns a fresh vector with the same size of @var{vec}, with
the elements calculated as follows:

The first element of result vector is a result of procedure @var{f}
called with @var{seed} and the first element of @var{vec}.

The @var{i}-th element of result vector is a result of procedure @var{f}
called with @var{i-1}-th element of result vector and @var{i}-th element
of @var{vec}.

@example
(vector-cumulate string-append "z" '#("a" "b" "c"))
  @result{} #("za" "zab" "zabc")
@end example
@end defun


@subheading Vector searching

@defun vector-index pred vec1 vec2 @dots{}
@defunx vector-index-right pred vec1 vec2 @dots{}
[R7RS vector]
@{@t{scheme.vector}@}
Returns the index of the first or the last elements in @var{vec1}
@var{vec2} @dots{} that satisfy @var{pred}, respectively.
Returns @code{#f} if no elements satisfy @var{pred}.
In @code{vector-index}, comparison ends at the end of the shortest vector.
For @code{vector-index-right}, all the vectors must have the same length.
@end defun

@defun vector-skip pred vec1 vec2 @dots{}
@defunx vector-skip-right pred vec1 vec2 @dots{}
[R7RS vector]
@{@t{scheme.vector}@}
Like @code{vector-index} and @code{vector-index-right}, except that
the result of @var{pred} is negated.  That is, returns the index
of the first or the last elements that don't satisfy @var{pred}.
@end defun

@defun vector-binary-search vec value cmp :optional start end
[R7RS+]
@{@t{scheme.vector}@}
Look for @var{value} in a sorted vector @var{vec}, and returns its
index if it is found, or @code{#f} if it is not found.

Comparison of @var{value} and an element in @var{vec} is
done by a procedure @var{cmp}, which takes two arguments,
and should return a negative integer if the first argument is less than the
second, 0 if they are the same, and a positive integer if the first
is greater than the second.

Elements in @var{vec} must be ordered from smaller to greater
w.r.t. @var{cmp}.  Using that fact, this procedure performs
binary search instead of linear search.

The optional arguments @var{start} and @var{end} are an
extension to SRFI-133, and can be used to limit the range of the
search in @var{start}-th element (inclusive) to
@var{end}-th element (exclusive).
@end defun

@defun vector-any pred vec1 vec2 @dots{}
[R7RS vector]
@{@t{scheme.vector}@}
Applies @var{pred} on each corresponding elements
of @var{vec1} @var{vec2} @dots{} left to right, and
as soon as @var{pred} returns non-@code{#f} value,
the procedure stops iteration and returns the value.

If no elements that satisfy @var{pred} are found, it returns @code{#f}.

Vectors can have different lengths.  Iteration stops at the end
of the shortest.
@end defun

@defun vector-every pred vec1 vec2 @dots{}
[R7RS vector]
@{@t{scheme.vector}@}
Applies @var{pred} on each corresponding elements
of @var{vec1} @var{vec2} @dots{} left to right.
If all the elements (when the lengths of vectors differ, the
first N elements where N is the length of the shortest) satisfy
@var{pred}, returns the last result of @var{pred}.
If any of the elements don't satisfy @var{pred},
it returns @code{#f} immediately without looking further.

@example
(vector-every < '#(1 2 3 4 5) '#(2 3 4 4 5)
  @result{} #f

(vector-every (^[x y] (and (real? x) (real? y) (- x y)))
              '#(1 2 3)
              '#(2 4 6))
  @result{} -3
@end example
@end defun

@defun vector-partition pred vec
[R7RS vector]
@{@t{scheme.vector}@}
Allocates a fresh vector of the same size as @var{vec},
then fill it with elements in @var{vec} that satisfy @var{pred},
followed by elements that don't satisfy @var{pred}.

Returns two values, the newly created vector and
an exact integer of the index of the first element that doesn't satisfy
@var{pred} in the returned vector.

@example
(vector-partition odd? '#(1 2 3 4 5 6 7 8))
  @result{} #(1 3 5 7 2 4 6 8) @r{and} 4
@end example
@end defun

@subheading Vector mutators

@defun vector-swap! vec i j
[R7RS vector]
@{@t{scheme.vector}@}
Swaps vector @var{vec}'s @var{i}-th and @var{j}-th elements.
Returns unspecified value.

@example
(rlet1 v (vector 'a 'b 'c 'd 'e)
  (vector-swap! v 0 2))
  @result{} #(c b a d e)
@end example
@end defun

@defun vector-reverse! vec :optional start end
[R7RS vector]
@{@t{scheme.vector}@}
Reverse the elements of @var{vec}.  Returns an undefined value.
Optional @var{start} and @var{end} arguments can limit
the range of operation.

@example
(rlet1 v (vector 'a 'b 'c 'd 'e)
  (vector-reverse! v 0 4))
  @result{} #(d c b a e)
@end example
@end defun

@defun vector-reverse-copy! target tstart source :optional sstart send
[R7RS vector]
@{@t{scheme.vector}@}
Like @code{vector-copy!}, but reverses the order of elements from @var{start}.

@example
(rlet1 v (vector 'a 'b 'c 'd 'e)
  (vector-reverse-copy! v 2 '#(1 2)))
  @result{} #(a b 2 1 e)
@end example

It is ok to pass the same vector to @var{target} and @var{source};
it always works even if the regions of source and destination are
overlapping.

@example
(rlet1 v (vector 'a 'b 'c 'd 'e)
  (vector-reverse-copy! v 1 v 1))
  @result{} #(a e d c b)
@end example
@end defun

@defun vector-unfold! f rvec start end seeds @dots{}
@defunx vector-unfold-right! f rvec start end seeds @dots{}
[R7RS vector]
@{@t{scheme.vector}@}
Fill @var{rvec} starting from index @var{start} (inclusive) and
ending at index @var{end} (exclusive), with the elements
calculated by @var{f}.

The procedure @var{f} takes the number of seed values @var{seeds} @dots{}
plus one arguments.  The first argument is the current index,
followed by seed values.  The same number of values
as the arguments must be returned from @var{f}; the first return value
is used to fill the current element of @var{rvec}, and the rest of the values
are used as the next seed values.

The result vector is filled from left to right by @code{vector-unfold!},
and right to left by @code{vector-unfold-right!}.
The return value is unspecified.

@example
(let1 rvec (vector 'a 'b 'c 'd 'e 'f)
  (vector-unfold! (^[i] (+ i 1)) rvec 1 4)
  rvec)
 @result{} #(a 2 3 4 e f)

(let1 rvec (vector 'a 'b 'c 'd 'e 'f)
  (vector-unfold-right! (^[i] (+ i 1)) rvec 1 4)
  rvec)
 @result{} #(a 2 3 4 e f)

(let1 rvec (vector 'a 'b 'c 'd 'e 'f)
  (vector-unfold! (^[i x] (values x (* x 2))) rvec 1 5 10)
  rvec)
 @result{} #(a 10 20 40 80 f)

(let1 rvec (vector 'a 'b 'c 'd 'e 'f)
  (vector-unfold! (^[i x] (values x (* x 2))) rvec 1 5 10)
  rvec)
 @result{} #(a 80 40 20 10 f)
@end example
@end defun

@subheading Vector conversion

@defun reverse-vector->list vec :optional start end
[R7RS vector]
@{@t{scheme.vector}@}
Same as @code{(reverse (vector->list vec start end))}, but more efficient.
@end defun

@node R7RS uniform vectors, R7RS sort, R7RS vectors, R7RS large
@subsection @code{scheme.vector.@@} - R7RS uniform vectors
@c NODE R7RSユニフォームベクタ, @code{scheme.vector.@@} - R7RSユニフォームベクタ

@deftp {Module} scheme.vector.@@
@mdindex scheme.vector.base
@mdindex scheme.vector.u8
@mdindex scheme.vector.s8
@mdindex scheme.vector.u16
@mdindex scheme.vector.s16
@mdindex scheme.vector.u32
@mdindex scheme.vector.s32
@mdindex scheme.vector.u64
@mdindex scheme.vector.s64
@mdindex scheme.vector.f32
@mdindex scheme.vector.f64
@mdindex scheme.vector.c64
@mdindex scheme.vector.c128
@code{@@} is actually one of @code{u8}, @code{s8}, @code{u16}, @code{s16},
@code{u32}, @code{s32}, @code{u64}, @code{s64}, @code{f32},
@code{f64}, @code{c64} or @code{c128}.
(Gauche's @code{gauche.uvector} module also provides @code{f16}
and @code{c32} vectors.)

These modules provides vectors that can hold specific range of numeric
values.  In Gauche we use @emph{packed} representation, meaning
numbers are tightly stored in consecutive memory region.

Additionally, @code{scheme.vector.base} module exports basic procedures,
@code{make-@@vector}, @code{@@vector}, @code{@@vector?}, @code{@@vector-length},
@code{@@vector-ref}, @code{@@vector-set!},
@code{@@vector->list}, @code{list->@@vector}, @code{@@?},
for @code{@@} being over all element types.

The @code{gauche.uvector} module is a superset of these modules, and
all procedures are described there.  @xref{Uniform vectors} for the
details.
@end deftp

@node R7RS sort, R7RS sets, R7RS uniform vectors, R7RS large
@subsection @code{scheme.sort} - R7RS sort
@c NODE R7RSソート, @code{scheme.sort} - R7RSソート

@deftp {Module} scheme.sort
@mdindex scheme.sort
Provides utilities to sort, and to work on sorted lists/vectors.
This module is the same as @code{srfi-132}.

Gauche has built-in sort and merge procedures (@pxref{Sorting and merging}).
This module has a bit different API.  Notably, the ordering predicate
comes first than the sequence to be sorted, and the procedures
dealing with vectors uniformly support start/end arguments

This module also provide useful procedures working on sorted or
partially sorted sequences.
@end deftp

@defun list-sort elt< lis
@defunx list-sort! elt< lis
@defunx list-stable-sort elt< lis
@defunx list-stable-sort! elt< lis
[R7RS sort]
@{@t{scheme.sort}@}
Sort elements in a list @var{lis} according to the ordering
predicate @var{elt<}, which takes two elements from @var{lis}
and returns true iff the first argument is strictly less
than the second argument.

Returns a sorted list.
The procedures with bang are linear update version.  They are
allowed, but not required, to reuse
@var{lis}.  The ``stable'' variation guarantees stable sort.

These are basically the same as Gauche's built-in
@code{sort}, @code{sort!}, @code{stable-sort} and @code{stable-sort!},
except the Gauche's version works on any sequences and takes
arguments differently. (@xref{Sorting and merging}.)
@end defun


@defun list-sorted? elt< lis
[R7RS sort]
@{@t{scheme.sort}@}
Returns true iff the list @var{list} is sorted according to the
ordering predicate @var{elt<}.

See also @code{sorted?} in @ref{Sorting and merging}.
@end defun


@defun list-merge elt< lis1 lis2
@defunx list-merge! elt< lis1 lis2
[R7RS sort]
@{@t{scheme.sort}@}
Given two sorted lists @var{lis1} and @var{lis2}, returns
a new sorted list according to the ordering predicate @var{elt<}.

Note that @code{list-merge!} works in-place, that is, all the pairs
in @var{lis1} and @var{lis2} are reused.

See also @code{merge} and @var{merge!} in @ref{Sorting and merging}.
@end defun

@defun vector-sort elt< vec :optional start end
@defunx vector-stable-sort elt< vec :optional start end
[R7RS sort]
@{@t{scheme.sort}@}
Sort elements in a vector @var{vec} according to the ordering
predicate @var{elt<}, which takes two elements from @var{vec}
and returns true iff the first argument is strictly less
than the second argument.  Returns a fresh sorted vector.
The ``stable'' variation guarantees stable sort.

When the optional @var{start} and/or @var{end} arguments are given,
only the portion from @var{start} (inclusive) and
@var{end} (exclusive) of @var{vec} are looked at.
The result vector's length is @code{@var{end} - @var{start})}.
When @var{end} is omitted, the length of @var{vec} is assumed.

See also @code{sort} and @code{stable-sort} in @ref{Sorting and merging}.
@end defun

@defun vector-sort! elt< vec :optional start end
@defunx vector-stable-sort! elt< vec :optional start end
[R7RS sort]
@{@t{scheme.sort}@}
Sort elements ``in-place'' in a vector @var{vec} according to the ordering
predicate @var{elt<}, which takes two elements from @var{vec}
and returns true iff the first argument is strictly less
than the second argument.  Upon successful return,
@var{vec}'s elements are sorted.  Returns unspecified value; the
caller must rely on the side effect.

When the optional @var{start} and/or @var{end} arguments are given,
only the portion from @var{start} (inclusive) and
@var{end} (exclusive) of @var{vec} are sorted; other elements
will remain intact.
When @var{end} is omitted, the length of @var{vec} is assumed.

See also @code{sort!} and @code{stable-sort!} in @ref{Sorting and merging}.
@end defun

@defun vector-sorted? elt< vec :optional start end
[R7RS sort]
@{@t{scheme.sort}@}
Returns true iff @var{vec} between @var{start} (inclusive)
and @var{end} (exclusive) is sorted according to the ordering
predicate @var{elt<}.  If @var{start} and/or @var{end} is/are omitted,
0 and the length of @var{vec} are assumed, respectively.

See also @code{sorted?} in @ref{Sorting and merging}.
@end defun


@defun vector-merge elt< vec1 vec2 :optional start1 end1 start2 end2
@defunx vector-merge! elt< rvec vec1 vec2 :optional rstart start1 end1 start2 end2
[R7RS sort]
@{@t{scheme.sort}@}
Merge two sorted vectors @var{vec1} and @var{vec2}
into one vector, according to the
ordering predicate @var{elt<}.

The optional argument @var{start1} and @var{end1} restricts @var{vec1}'s
portion to be looked at, and @var{start2} and @var{end2}
restricts @var{vec2}'s portion to be looked at.

The functional version @var{vector-merge} allocates a fresh vector
to hold the result, and returns it.

The side-effecting version @var{vector-merge!} uses @var{rvec}.
to hold the result. The procedure doesn't return a meaningful value.
The optional @var{rstart} argument specifies
the index of @var{rvec} from which the result is filled; the default
is 0.
@end defun

@defun list-delete-neighbor-dups elt= lis
@defunx list-delete-neighbor-dups! elt= lis
@defunx vector-delete-neighbor-dups elt= vec :optional start end
@defunx vector-delete-neighbor-dups! elt= vec :optional start end
[R7RS sort]
@{@t{scheme.sort}@}
From the given list @var{lis} or vector @var{vec},
these procedures delete adjacent duplicate elements.  Equivalence
is checked by @var{elt=} procedure.

@example
(list-delete-neighbor-dups eq? '(m i s s i s s i p p i))
  @result{} (m i s i s i p i)
@end example

The non-destructive versions @code{list-delete-neighbor-dups} and
@code{vector-delete-neighbor-dups} returns a freshly allocated
list and vector, respectively.

The destructive @code{list-delete-neighbor-dups!} works in-place,
reusing pairs of @var{lis}.  No allocation will be done.

The destructive @code{vector-delete-neighbor-dups!} has a bit different
interface.  It updates @var{vec} in-place, but since we can't change
the length of the vector, it gathers the result from the beginning of
the @var{vec}, then returns the next index @var{newend}
of @var{vec}---that is,
after calling this procedure, @code{[@var{start}, @var{newend})}
holds the result.
The elements between @code{[@var{newend}, @var{end})} will remain intact.

The optional @var{start} and @var{end} arguments limits the region
of @var{vec} to be looked at.

@example
(vector-delete-neighbor-dups eq? '#(a a a b b c c d d e e f f) 3 10)
  @result{} #(b c d e)

(let1 v '#(a a a b b c c d d e e f f)
  (cons (vector-delete-neighbor-dups! eq? v 3 10) v))
  @result{} (7 . #(a a a b c d e d d e e f f))
@end example

Note: The @code{gauche.sequence} module provides neighbor duplicate
deletion on generic sequences.  Those procedures are implemented by
the generic versions as shown below.  @xref{Other operations over sequences},
for the details.
@table @code
@item list-delete-neighbor-dups
@code{delete-neighbor-dups}
@item list-delete-neighbor-dups!
@code{delete-neighbor-dups-squeeze!}
@item vector-delete-neighbor-dups
@code{delete-neighbor-dups}
@item vector-delete-neighbor-dups!
@code{delete-neighbor-dups!}
@end table
@end defun

@defun vector-select! elt< vec k :optional start end
[R7RS sort]
@{@t{scheme.sort}@}
Select @var{k}-th smallest element in @var{vec} according to the
ordering predicate @var{elt<}.  @var{K} is zero based, i.e. 0 means
the smallest.  The optional @var{start} and @var{end} arguments
limits the range of @var{vec} to be looked at, and defaulted to
0 and the length of @var{vec}, respectively.
@var{K} must satisfy @code{@var{start} <= @var{k} < @var{end}}.

This procedure runs in O(n) time, and requires no extra stroage.
This procedure may partially modify @var{vec}.
@end defun

@defun vector-separate! elt< vec k :optional start end
[R7RS sort]
@{@t{scheme.sort}@}
Find @var{k}-th smallerst element in @var{vec} (pivot) between
between @var{start} and @var{end}, according to the ordering
predicate @var{elt<}, then rearrange elements
between @var{start} and @var{end} so that
elements smaller than the pivot comes between @code{@var{start}} and
@code{@var{start} + @var{k}}, and the rest of the elements come
afterwards.  When omitted, @var{start} is 0 and @var{end} is
the length of the @var{vec}.

This can be used as a building block for in-place divide-and-conquer
algorithms.  Runs in O(n) time.
@end defun

@defun vector-find-median elt< vec knil :optional mean
@defunx vector-find-median! elt< vec knil :optional mean
[R7RS sort]
@{@t{scheme.sort}@}
Find median value of elements in @var{vec}, when ordered by
the ordering predicate @var{elt<}.  Non-destructive version
@code{vector-find-median} runs in O(n) time.  The destructive
version @code{vector-find-median!} is specified to leave
@var{vec} sorted, so it runs in O(n log n).

@enumerate
@item
If @var{vec} is empty, @var{knil} is returned.  This is the only case
@var{knil} is used.
@item
If @var{vec} has odd number of elements, the element falls in the exactly
the midpoint when ordered, is returned.
@item
If @var{vec} has even number of elements, the two elements closest to
the midpoint is chosen and passed to the procedure @var{mean}, and
its result is returned.  The default of @var{mean} is an arithmetic
mean of numbers.
@end enumerate

@example
(vector-find-median < #() 0)
  @result{} 0

(vector-find-median < #(78 61 19 38 51) 0)
  @result{} 51

(vector-find-median < #(78 61 19 38 51 52) 0)
  @result{} 103/2
@end example
@end defun

@node R7RS sets, R7RS character sets, R7RS sort, R7RS large
@subsection @code{scheme.set} - R7RS sets
@c NODE R7RSセット, @code{scheme.set} - R7RSセット

@deftp {Module} scheme.set
@mdindex scheme.set
Sets and bags are unordered collection of Scheme values.
A set doesn't count duplicates; if you add an item
which is already in a set, you still have one item of the kind.
A bag counts duplicates; if you add an item which
is already in a bag, you have two items of the kind.

To check whether the items are ``the same'', sets and bags
takes a comparator at construction time.  The comparator
doesn't need to have an ordering predicate (we don't need
to order the elements) but has to have a hash function.
@xref{Basic comparators}, for the details of comparators.

This module is originally specified as @code{srfi-113}, and then
incorporated to R7RS large.

As a Gauche's extension, sets and bags implement collection protocol
(@pxref{Collection framework}, for the details), and generic collection
operations can be applied.

@example
(coerce-to <list> (set eq-comparator 'a 'b 'a 'b))
  @result{} (a b)      ; @r{order may differ}

(coerce-to <list> (bag eq-comparator 'a 'b 'a 'b))
  @result{} (a a b b)  ; @r{order may differ}
@end example
@end deftp

@subheading Constructors

@defun set comparator elt @dots{}
@defunx bag comparator elt @dots{}
[R7RS set]
@{@t{scheme.set}@}
Creates a new set and bag from given elements @var{elt} @dots{}.
Given @var{comparator} will be used to compare equality of elements.

@example
(set->list (set eq-comparator 'a 'b 'a 'b))
  @result{} (a b)

(bag->list (bag eq-comparator 'a 'b 'a 'b))
  @result{} (a a b b)
@end example
@end defun

@defun set-unfold stop? mapper successor seed comparator
@defunx bag-unfold stop? mapper successor seed comparator
[R7RS set]
@{@t{scheme.set}@}
Procedurally creates a set or a bag.  The first three
arguments, @var{stop?},  @var{mapper} and @var{successor},
are all procedures that takes one argument, the current seed value.
It may be easier to know their types:

@example
seed      :: Seed
stop?     :: Seed -> Boolean
mapper    :: Seed -> ElementType
successor :: Seed -> Seed
@end example

The @code{stop?} procedure takes the current seed value and
returns a boolean value - if it is true, iteration stops.

The @code{mapper} procedure takes the current seed value
and returns an item, which is to be included in the resulting set or bag.

The @code{successor} procedure takes the current seed value
and returns the next seed value.

And the @code{seed} argument gives the initial seed value.

@example
(set->list (set-unfold (^s (= s 75))
                       integer->char
                       (^s (+ s 1))
                       65
                       eqv-comparator))
 @result{} (#\D #\H #\A #\E #\I #\J #\B #\F #\C #\G)
@end example
@end defun

@subheading Predicates

@defun set-contains? set obj
@defunx bag-contains? bag obj
[R7RS set]
@{@t{scheme.set}@}
Check if @var{obj} is in the set or the bag.
@end defun

@defun set-empty? set
@defunx bag-empty? bag
[R7RS set]
@{@t{scheme.set}@}
Returns @code{#t} iff the given set or bag is empty.
@end defun

@defun set-disjoint? set1 set2
@defunx bag-disjoint? bag1 bag2
[R7RS set]
@{@t{scheme.set}@}
Returns @code{#t} iff the given arguments (sets or bags) don't have
common items.  Both arguments must have the same comparator---otherwise
an error is signaled.
@end defun

@subheading Accessors

@defun set-member set obj default
@defunx bag-member bag obj default
[R7RS set]
@{@t{scheme.set}@}
Returns an element in the given set or bag which is equal to @var{obj}
in terms of the set's or the bag's comparator.  If no such element is
found, @var{default} will be returned.

Note that the returned object doesn't need to be ``the same''
as @var{obj} in a usual sense.  See the following example:

@example
(let s (set string-ci-comparator "abc" def")
  (set-member s "ABC" #f))
  @result{} "abc"
@end example
@end defun

@defun set-element-comparator set
@defunx bag-element-comparator bag
[R7RS set]
@{@t{scheme.set}@}
Returns the comparator used to compare the elements for the set or the bag.
@end defun

@subheading Updaters

@defun set-adjoin set elt @dots{}
@defunx bag-adjoin bag elt @dots{}
[R7RS set]
@{@t{scheme.set}@}
Returns a newly created set or bag that contains all the elements
in the original set/bag, plus given elements.  The new set/bag's
comparator is the same as the original set/bag's one.
@end defun

@defun set-replace set elt
@defunx bag-replace bag elt
[R7RS set]
@{@t{scheme.set}@}
Returns a newly created set/bag with the same comparator with
the original set/bag, and the same elements, except that the elements
equal to @var{elt} (in terms of set/bag's comparator) is replaced
by @var{elt}.  If the original set/bag doesn't contain an element
equal to @var{elt}, the original one is returned.

@example
(let ((s (set string-ci-comparator "ABC" "def")))
  (set->list (set-replace s "abc")))
  @result{} ("abc" "def")
@end example
@end defun

@defun set-delete set elt @dots{}
@defunx bag-delete bag elt @dots{}
[R7RS set]
@{@t{scheme.set}@}
Returns a newly created set or bag that has the same comparator
and the same elements in the original set/bag, except that the
item which is equal to @var{elt}.
@end defun

@defun set-delete-all set elt-list
@defunx bag-delete-all bag elt-list
[R7RS set]
@{@t{scheme.set}@}
Returns a newly created set or bag with the same comparator of
the original set/bag, with the elements of the original set/bag
except the ones listed in @var{elt-list}.
@end defun


@defun set-adjoin! set elt @dots{}
@defunx bag-adjoin! bag elt @dots{}
@defunx set-replace! set elt
@defunx bag-replace! bag elt
@defunx set-delete! set elt @dots{}
@defunx bag-delete! bag elt @dots{}
@defunx set-delete-all! set elt-list
@defunx bag-delete-all! bag elt-list
[R7RS set]
@{@t{scheme.set}@}
These are the linear update versions of their counterparts.
It works just like the ones without @code{!}, except that
the original set/bag @emph{may} be reused to produce the result,
instead of new one being allocated.

Note that it's not guaranteed that the original
set/bag is modified, so you should use the return value of them,
instead of relying on the side effects.
@end defun

@defun set-search! set elt failure success
@defunx bag-search! bag elt failure success
[R7RS set]
@{@t{scheme.set}@}
Lookup-and-modify procedures.  The @var{failure} and @var{success}
arguments are procedures.

First, they search @var{elt} in the given set/bag.
If an item that matches @var{elt} is found, the @var{success} procedure
is called with three arguments, as follows:
@example
(success item update remove)
@end example
The @var{update} argument is a procedure that takes two arguments,
as @code{(update new-item retval)}.  It replaces the matching @var{item} in the
set/bag with @var{new-item}, and returns @var{retval}.
The @var{remove} argument is a procedure that takes one argument,
as @code{(remove retval)}.  It removes the matching @var{item} in
the set/bag, and returns @var{retval}.

If an item that matches @var{elt} is not found, the @var{failure} procedure
is called with two arguments, as follows:
@example
(failure insert ignore)
@end example
The @var{insert} argument is a procedure that takes one argument,
as @code{(insert retval)}.  It inserts @var{elt} into the set/bag, and
returns @var{retval}.
The @var{ignore} argument is a procedure that takes one argument,
as @code{(ignore retval)}.  It just returns @var{retval}.

The return values of @code{set-search!} and @code{bag-search!} is
the modified set/bag (which may or may not be @code{eq?} to the passed one),
and the value returned by @var{success} or @var{failure} procedures.

Note that @var{retval} isn't used in this process; it is just to provide
one of the return values of @code{set-search!}/@code{bag-search!}, for
the procedures passed to @var{success} or @var{failure} are expected
to be tail-called.

If there are more than one item that matches @var{elt} in a bag,
@code{bag-search!} only invokes @var{success} for the first item
it finds.  You can recurse into @code{bag-search!} in the @var{failure}
procedure to visit all matching items.  It is guaranteed that @var{success}
and @var{failure} procedures are tail-called.
@end defun

@subheading The whole set

@defun set-size set
@defunx bag-size bag
[R7RS set]
@{@t{scheme.set}@}
Returns the number of items in the set/bag.
@end defun

@defun set-find pred set failure
@defunx bag-find pred bag failure
[R7RS set]
@{@t{scheme.set}@}
Apply @var{pred} on each item in the set/bag, and returns the
first item on which @var{pred} returns true.  Since sets and bags
are unordered, if there are more than one items that satisfy @var{pred},
you won't know which one will be returned.

If there're no items that satisfy @var{pred}, a thunk @code{failure}
is called and its result is returned.
@end defun

@defun set-count pred set
@defunx bag-count pred bag
[R7RS set]
@{@t{scheme.set}@}
Returns the number of items that satisfy @var{pred} in the set/bag.
@end defun

@defun set-any? pred set
@defunx bag-any? pred bag
[R7RS set]
@{@t{scheme.set}@}
Returns true iff any item in the set/bag satisfy @var{pred}.
@end defun

@defun set-every? pred set
@defunx bag-every? pred bag
[R7RS set]
@{@t{scheme.set}@}
Returns true iff every item in the set/bag satisfy @var{pred}.
@end defun

@subheading Mapping and folding

@defun set-map comparator proc set
@defunx bag-map comparator proc bag
[R7RS set]
@{@t{scheme.set}@}
Create and return a new set/bag with the comparator @var{comparator},
whose items are calculated by applying @var{proc} to each element
in the original set/bag.
@end defun

@defun set-for-each proc set
@defunx bag-for-each proc bag
[R7RS set]
@{@t{scheme.set}@}
Apply @var{proc} to each element in the set/bag.   The result of @var{proc}
is ignored.  Return value is undefined.
@end defun

@defun set-fold proc seed set
@defunx bag-fold proc seed bag
[R7RS set]
@{@t{scheme.set}@}
For each item in the set/bag, call @var{proc} with two arguments, an item
and a seed value.  What @var{proc} returns becomes the next seed value.
The @var{seed} argument gives the initial seed value, and the last return
value of @var{proc} will be the result of @code{set-fold}/@code{bag-fold}.

@example
(bag-fold + 0 (bag eqv-comparator 1 1 2 2 3 3 4 4))
  @result{} 20
@end example
@end defun

@defun set-filter pred set
@defunx bag-filter pred bag
[R7RS set]
@{@t{scheme.set}@}
Returns a newly created set/bag with the same comparator of the original
set/bag, and its content consists of items from the original set/bag
that satisfy @var{pred}.

@example
(set->list (set-filter odd? (set eqv-comparator 1 2 3 4 5)))
  @result{} (1 3 5)
@end example
@end defun

@defun set-remove pred set
@defunx bag-remove pred bag
[R7RS set]
@{@t{scheme.set}@}
Returns a newly created set/bag with the same comparator of the original
set/bag, and its content consists of items from the original set/bag
that does not satisfy @var{pred}.

@example
(set->list (set-remove odd? (set eqv-comparator 1 2 3 4 5)))
  @result{} (2 4)
@end example
@end defun

@defun set-partition pred set
@defunx bag-partition pred bag
[R7RS set]
@{@t{scheme.set}@}
Returns two sets or bags, both have the same comparator of the original
set or bag.  The first one consists of the items from the original set/bag
that satisfy @var{pred}, and the second one consists of the items that don't.

@example
(receive (in out) (set-remove odd? (set eqv-comparator 1 2 3 4 5))
  (values (set->list in)
          (set->list out)))
  @result{} (1 3 5) @r{and} (2 4)
@end example
@end defun

@defun set-filter! pred set
@defunx bag-filter! pred bag
@defunx set-remove! pred set
@defunx bag-remove! pred bag
@defunx set-partition! pred set
@defunx bag-partition! pred bag
[R7RS set]
@{@t{scheme.set}@}
Linear update versions of their counterparts (the procedures without @code{!}).
They work like their respective counterpart, but they are allowed (but not
required) to reuse the original set/bag to produce the result(s).

Note that it is not guaranteed that the original set/bag is modified, so
you have to use the return value(s) instead of relying on the side effects.
@end defun

@subheading Copying and conversion

@defun set-copy set
@defunx bag-copy bag
[R7RS set]
@{@t{scheme.set}@}
Returns a copy of the set/bag.
@end defun

@defun set->list set
@defunx bag->list bag
[R7RS set]
@{@t{scheme.set}@}
Returns a list of all items in the set/bag.
Since sets and bags are unordered, there's no guarantee on the
order of items.
@end defun

@defun list->set comparator elt-list
@defunx list->bag comparator elt-list
[R7RS set]
@{@t{scheme.set}@}
Creates a set or a bag with the given comparator, and
the list of element.  Functionally equivalent to the followings:

@example
(apply set comparator elt-list)
(apply bag comparator elt-list)
@end example
@end defun

@defun list->set! set elt-list
@defunx list->bag! bag elt-list
[R7RS set]
@{@t{scheme.set}@}
Add items in @var{elt-list} to the existing set/bag, and returns
the updated set/bag.  The original set/bag is also modified.
Functionally equivalent to the followings:

@example
(apply set-adjoin! set elt-list)
(apply bag-adjoin! bag elt-list)
@end example
@end defun

@defun bag->set bag
@defunx set->bag set
[R7RS set]
@{@t{scheme.set}@}
Conversions between a bag and a set.  Returns a newly created bag or set,
respectively.

If @var{bag} has duplicated items, @code{bag->set} coerces them to one
item.
@end defun

@defun set->bag! bag set
[R7RS set]
@{@t{scheme.set}@}
Adds all items in @var{set} to @var{bag}, and returns @var{bag}.
Both @var{bag} and @var{set} must have the same comparator.
@end defun


@defun bag->alist bag
[R7RS set]
@{@t{scheme.set}@}
Returns a list of @code{(item . count)}, where @var{item} is
an item in @var{bag}, and @var{count} is the number of that item
in the bag.
@end defun

@defun alist->bag comparator alist
[R7RS set]
@{@t{scheme.set}@}
Creates a new bag with @var{comparator}, and fills it according to
@var{alist}, which must be a list of @code{(item . count)}.

If there's duplicate items in @var{alist}, only fist one counts.
@end defun

@subheading Subsets

@defun set=? set1 set2 @dots{}
@defunx bag=? bag1 bag2 @dots{}
[R7RS set]
@{@t{scheme.set}@}
Returns true iff all sets/bags have exactly same items.

The comparators of the argument sets/bags are not checked, but assumed
to be the same, in terms of the equality of items.
@end defun

@defun set<? set1 set2 @dots{}
@defunx bag<? bag1 bag2 @dots{}
@defunx set>? set1 set2 @dots{}
@defunx bag>? bag1 bag2 @dots{}
@defunx set<=? set1 set2 @dots{}
@defunx bag<=? bag1 bag2 @dots{}
@defunx set>=? set1 set2 @dots{}
@defunx bag>=? bag1 bag2 @dots{}
[R7RS set]
@{@t{scheme.set}@}
Returns true iff each preceding set/bag is a proper subset of,
a proper superset of, a subset of, or a superset of the following
set/bags, respectively.

Again, the comparators of the argument sets/bags are not checked, but assumed
to be the same, in terms of the equality of items.
@end defun

@subheading Set theory operations

@defun set-union set1 set2 @dots{}
@defunx bag-union bag1 bag2 @dots{}
[R7RS set]
@{@t{scheme.set}@}
Returns a newly allocated set or bag which is a union of all
the sets/bags.
@end defun

@defun set-intersection set1 set2 @dots{}
@defunx bag-intersection bag1 bag2 @dots{}
[R7RS set]
@{@t{scheme.set}@}
Returns a newly allocated set or bag which is an intersection of
all the sets/bags.
@end defun

@defun set-difference set1 set2 @dots{}
@defunx bag-difference bag1 bag2 @dots{}
[R7RS set]
@{@t{scheme.set}@}
Returns a newly created set or bag that contains items in @var{set1}/@var{bag1}
except those are also in @var{set2}/@var{bag2} @dots{}.

@example
(sort (set->list (set-difference (set eqv-comparator 1 2 3 4 5 6 7)
                                 (set eqv-comparator 3 5 7 9 11 13)
                                 (set eqv-comparator 4 8 16 32))))
  @result{} (1 2 6)
@end example
@end defun

@defun set-xor set1 set2
@defunx bag-xor bag1 bag2
[R7RS set]
@{@t{scheme.set}@}
Returns a newly created set or bag that consists of items
that are either in @var{set1}/@var{bag1} or @var{set2}/@var{bag2},
but not in both.

@example
(sort (set->list (set-xor (set eqv-comparator 2 3 5 7 11 13 17)
                          (set eqv-comparator 3 5 7 9 11 13 15))))
  @result{} (2 9 15 17)
@end example
@end defun

@defun set-union! set1 set2 @dots{}
@defunx bag-union! bag1 bag2 @dots{}
@defunx set-intersection! set1 set2 @dots{}
@defunx bag-intersection! bag1 bag2 @dots{}
@defunx set-difference! set1 set2 @dots{}
@defunx bag-difference! bag1 bag2 @dots{}
@defunx set-xor! set1 set2
@defunx bag-xor! bag1 bag2
[R7RS set]
@{@t{scheme.set}@}
Linear update versions of their corresponding procedures.
Those procedures works like their @code{!}-less counterparts,
except that they are allowed to, but not required to, reuse
@var{set1}/@var{bag1} to produce the result.

The caller should always use the returned set/bag instead of
relying on the side effects.
@end defun

@subheading Bag-specific procedures

@defun bag-sum bag1 bag2 @dots{}
@defunx bag-sum! bag1 bag2 @dots{}
[R7RS set]
@{@t{scheme.set}@}
Returns a bag that gathers all the items in given bags, counting
duplicates.  The functional version @code{bag-sum} always
creates new bag to return.
The linear update version @code{bag-sum!} is allowed to,
but not required to, modify @var{bag1} to produce the result.

@example
(sort (bag->list (bag-sum (bag eqv-comparator 1 1 2 4 5 5 6)
                          (bag eqv-comparator 3 3 5 9))))
  @result{} (1 1 2 3 3 4 5 5 5 6 9)
@end example

Note the difference from @code{bag-union}:

@example
(sort (bag->list (bag-union (bag eqv-comparator 1 1 2 4 5 5 6)
                            (bag eqv-comparator 3 3 5 9))))
  @result{} (1 1 2 3 3 4 5 5 6 9)
@end example
@end defun

@defun bag-product n bag
@defunx bag-product! n bag
[R7RS set]
@{@t{scheme.set}@}
Returns a bag that contains every item as @var{n}-times
many as the original bag.  A fresh bag is created and returned
by @code{bag-product}, while @code{bag-product!} may reuse
@var{bag} to produce the result.

@example
(sort (bag->list (bag-product 2 (bag eq-comparator 'a 'b 'r 'a))))
  @result{} (a a a a b b r r)
@end example
@end defun

@defun bag-unique-size bag
[R7RS set]
@{@t{scheme.set}@}
Returns the number of unique elements in @var{bag}.

@example
(bag-unique-size (bag eqv-comparator 1 1 2 2 3 3 4))
 @result{} 4
@end example
@end defun

@defun bag-element-count bag elt
[R7RS set]
@{@t{scheme.set}@}
Returns the number of specified element @var{elt} in @var{bag}.

@example
(bag-element-count (bag eqv-comparator 1 1 2 2 2 3 3) 2)
 @result{} 3
@end example
@end defun

@defun bag-for-each-unique proc bag
[R7RS set]
@{@t{scheme.set}@}
For each unique item in @var{bag}, calls @code{proc} with two arguments:
The item, and the count of the item in the bag.
@end defun

@defun bag-fold-unique proc seed bag
[R7RS set]
@{@t{scheme.set}@}
For each unique item in @var{bag}, calls @var{proc} with three arguments:
The item, the count of the item, and the previous seed value.
The @var{seed} argument provides the initial seed value; the result
of @var{proc} is used for the next seed value, and the last
result of @code{proc} is returned from @code{bag-fold-unique}.

@example
(sort (bag-fold-unique acons '()
        (bag equal-comparator "a" "a" "b" "b" "b" "c" "d"))
      string<? car)
 @result{} (("a" . 2) ("b" . 3) ("c" . 1) ("d" . 1))
@end example
@end defun

@defun bag-increment! bag elt count
@defunx bag-decrement! bag elt count
[R7RS set]
@{@t{scheme.set}@}
Linear update @var{bag} to increase or decrease the count of @var{elt} in it
by @var{count}, which must be an exact integer.  Note that the
element count won't get below zero; if a bag has two @code{a}'s, and
you call @code{(bag-decrement! bag 'a 100)}, you get a bag
with zero @code{a}'s.
@end defun

@subheading Comparators

@defvr {Comparator} set-comparator
@defvrx {Comparator} bag-comparator
[R7RS comparator]
@{@t{scheme.set}@}
Comparators to be used to compare sets or bags.  They don't provide
comparison procedure, for you cannot define a total order among sets or bags.
They do provide hash functions.
@end defvr


@node R7RS character sets, R7RS hash tables, R7RS sets, R7RS large
@subsection @code{scheme.charset} - R7RS character sets
@c NODE R7RS文字集合, @code{scheme.charset} - R7RS文字集合

@deftp {Module} scheme.charset
@mdindex scheme.charset
Implements character set library, originally defined as SRFI-14.
Note that the following
character-set procedures and pre-defined charsets are Gauche's build-in.
@xref{Character sets}.

@example
char-set             char-set?            char-set-contains?
char-set-copy        char-set-complement  char-set-complement!

char-set:lower-case  char-set:upper-case  char-set:title-case
char-set:letter      char-set:digit       char-set:letter+digit
char-set:graphic     char-set:printing    char-set:whitespace
char-set:iso-control char-set:punctuation char-set:symbol
char-set:hex-digit   char-set:blank       char-set:ascii
char-set:empty       char-set:full
@end example

In Gauche,
the @code{<char-set>} class inherits @code{<collection>} and implements
the collection protocol, so that the generic operations defined in
@code{gauche.collection} can also be used (@pxref{Collection framework}).
@end deftp

@menu
* Character-set constructors::
* Character-set comparison::
* Character-set iteration::
* Character-set query::
* Character-set algebra::
@end menu

@node Character-set constructors, Character-set comparison, R7RS character sets, R7RS character sets
@subsubsection Character-set constructors
@c NODE 文字集合の構築子

@defun list->char-set char-list :optional base-cs
@defunx list->char-set! char-list base-cs
[R7RS comparator]
@{@t{scheme.charset}@}
Constructs a character set from a list of characters @var{char-list}.
If @var{base-cs} is given, it must be a character set, and the characters
in it are added to the result character set.
@code{List->char-set!} is allowed, but not required, to reuse @var{base-cs}
to store the result.
@end defun

@defun string->char-set s :optional base-cs
@defunx string->char-set! s base-cs
[R7RS charset]
@{@t{scheme.charset}@}
Like @code{list->char-set} and @code{list->char-set!},
but take a list of characters from a string @var{s}.
@end defun

@defun char-set-filter pred char-set :optional base-cs
@defunx char-set-filter! pred char-set base-cs
[R7RS charset]
@{@t{scheme.charset}@}
Returns a character set containing every character @var{c} in
@var{char-set} such that @code{(@var{pred} @var{c})} returns true.
If a character set @var{base-cs} is given, its content is added to
the result.  The linear update version @code{char-set-filter!}
is allowed, but not required, to modify @var{base-cs} to store the result.
@end defun

@defun ucs-range->char-set lower upper :optional error? base-cs
@defunx ucs-range->char-set! lower upper error? base-cs
[R7RS charset]
@{@t{scheme.charset}@}
Creates a character set containing every character whose ISO/IEC 10646
UCS-4 code lies in the half-open range [@var{lower},@var{upper}).

If the range contains unassigned codepoint, they are silently ignored.

If the range contains a valid codepoint which isn't supported in Gauche,
it is ignored when @var{error?} is false (default),
or an error is raised when @var{error?} has a true value.
If you compile Gauche with utf-8 native encoding (default), all valid
Unicode codepoints are supported.  If Gauche is compiled with other native
encoding, some codepoints are not supported.

If a character set @var{base-cs} is given, its content is added to
the result.  The linear update version @code{ucs-range->char-set!}
is allowed, but not required, to modify @var{base-cs} to store the result.
@end defun

@defun integer-range->char-set lower upper :optional error? base-cs
@defunx integer-range->char-set! lower upper error? base-cs
@{@t{scheme.charset}@}
These are Gauche-specific procedures and not in @code{scheme.charset}.
When Gauche is compiled with utf-8 native encoding (default), they are
the same as @code{ucs-range->char-set} and @code{ucs-range->char-set!},
respectively.
If Gauche is compiled with other native encoding, these interprets
the given range in its native encoding.

Meaning of @var{error?} and @var{base-cs} are the same as
@code{ucs-char->char-set}.
@end defun

@defun ->char-set x
[R7RS charset]
@{@t{scheme.charset}@}
A convenience function to coerce various kinds of objects to a char-set.
The argument @var{x} can be a collection of characters,
a char-set, or a character.  If the argument is a char-set,
it is returned as-is.  If the argument is a character,
a char-set with that single character is returned.

Note: R7RS @code{(scheme charset)}'s
@code{->char-set} only accepts a string, a char-set
or a character as an argument.  Gauche extends it so that it can
accept any collection of characters.
@end defun

@node Character-set comparison, Character-set iteration, Character-set constructors, R7RS character sets
@subsubsection Character-set comparison
@c NODE 文字集合の比較

@defun char-set= char-set1 @dots{}
[R7RS charset]
@{@t{scheme.charset}@}
Returns @code{#t} iff all the character sets have exactly the
same members.

@example
(char-set=)  @result{} #t
(char-set= (char-set)) @result{} #t
(char-set= (string->char-set "cba")
           (list->char-set #\a #\b #\c))
  @result{} #t
@end example

@end defun

@defun char-set<= char-set1 @dots{}
[R7RS charset]
@{@t{scheme.charset}@}
Returns @code{#t} iff every char-set argument is a subset of
the following char-sets.  If no arguments are given, @code{#t} is returned.
@end defun

@defun char-set-hash char-set :optional bound
[R7RS charset]
@{@t{scheme.charset}@}
Returns a non-negative exact integer as a hash value of @var{char-set}.
If optional @var{bound} argument is given, it must be a positive integer
that limits the range of the hash value, which will fall between
0 to @code{(- bound 1)}, inclusive.
@end defun

@node Character-set iteration, Character-set query, Character-set comparison, R7RS character sets
@subsubsection Character-set iteration
@c NODE 文字集合のイテレーション

@defun char-set-cursor char-set
[R7RS charset]
@{@t{scheme.charset}@}
Returns an object that can point to a first character within @var{char-set}
(here, `first' merely means the beginning of iteration; the order of
iteration is implementation-dependent and you can't assume a specific
order).
The caller must treat the return value as an opaque object; it can only
be used to pass as the @var{cursor} argument of @code{char-set-ref},
@code{char-set-cursor-next} and @code{end-of-char-set?}.
@end defun

@defun char-set-ref char-set cursor
[R7RS charset]
@{@t{scheme.charset}@}
Returns a character in @var{char-set} pointed by @var{cursor}.

The @var{cursor} argument must be an object returned from
@code{char-set-cursor} or @code{char-set-cursor-next} with @var{char-set}.
The behavior is undefined if @var{cursor} is not a cursor
created from @var{char-set}.
@end defun

@defun char-set-cursor-next char-set cursor
[R7RS charset]
@{@t{scheme.charset}@}
Returns a new cursor for the next character pointed by @var{cursor}
within @var{char-set}.

The @var{cursor} argument must be an object returned from
@code{char-set-cursor} or @code{char-set-cursor-next} with @var{char-set}.
The behavior is undefined if @var{cursor} is not a cursor
created from @var{char-set}.
@end defun

@defun end-of-char-set? cursor
[R7RS charset]
@{@t{scheme.charset}@}
Returns @code{#t} iff @var{cursor} points to the end of the charset.
@end defun

@defun char-set-fold kons knil char-set
[R7RS charset]
@{@t{scheme.charset}@}
Iterate over all characters in @var{char-set}, calling the procedure @var{kons}
with a character and the seed value.  The return value of @var{kons} becomes
the next seed value, while @var{knil} gives the first seed value.
Returns the last seed value.  The order of traversal isn't specified.
@end defun

@defun char-set-unfold pred fun gen seed :optional base-char-set
@defunx char-set-unfold! pred fun gen seed base-char-set
[R7RS charset]
@{@t{scheme.charset}@}
Build a character set by calling @var{fun} on the seed value repeatedly.
For each iteration, first @var{pred} is applied to the current seed value.
If it returns true, a character set that gathers characters generated so far
is returned.  Otherwise, @var{fun} is called on the seed value,
which must return a character.  Then @var{gen} is called on the seed value
to obtain the next seed value.

If @var{base-char-set} is given, a union of it and the generated characters
is returned.
The linear-update version @code{char-set-unfold!} may modify @var{base-char-set}
to create the result.
@end defun

@defun char-set-for-each proc char-set
[R7RS charset]
@{@t{scheme.charset}@}
Applies @var{proc} on each character in @var{char-set}.  The return value
of @var{proc} is discarded.  Returns undefined value.
@end defun

@defun char-set-map proc char-set
[R7RS charset]
@{@t{scheme.charset}@}
Applies @var{proc} on each character in @var{char-set}, which must
return a character.  Returns a new charset consists of the characters
returned from @var{proc}.
@end defun

@node Character-set query, Character-set algebra, Character-set iteration, R7RS character sets
@subsubsection Character-set query
@c NODE 文字集合への問い合わせ

@defun char-set-every pred char-set
@defunx char-set-any pred char-set
@defunx char-set-count pred char-set
[R7RS charset]
@{@t{scheme.charset}@}
These procedures apply @var{pred} to each character in @var{char-set}.

@code{char-set-every} returns @code{#f} as soon as @var{pred} returns
@code{#f}.  Otherwise, it returns the result of the last application of
@var{pred}.

@code{char-set-any} returns as soon as @var{pred} returns a true value,
and the return value is the one @var{pred} returns.
If @var{pred} returns @code{#f} for all characters, @code{#f} is returned.

@code{char-set-count} returns the number of times
@var{pred} returns a true value.

Note that @var{char-set} can be huge (e.g. a complement of small char-set),
which can make these procedures take very long.
@end defun

@defun char-set->list char-set
@defunx char-set->string char-set
[R7RS charset]
@{@t{scheme.charset}@}
Returns a list of each character, or a string consisting of
each character, in @var{char-set}, respectively.
Be careful to apply this on a large char set.
@end defun


@node Character-set algebra,  , Character-set query, R7RS character sets
@subsubsection Character-set algebra
@c NODE 文字集合に適用できる代数的関数

@defun char-set-adjoin char-set char1 @dots{}
@defunx char-set-adjoin! char-set char1 @dots{}
[R7RS charset]
@{@t{scheme.charset}@}
Returns a character set that adds @var{char1} @dots{} to
@var{char-set}.

The linear update version @code{char-set-adjoin!} may modify
@var{char-set}.
@end defun

@defun char-set-delete char-set char1 @dots{}
@defunx char-set-delete! char-set char1 @dots{}
[R7RS charset]
@{@t{scheme.charset}@}
Returns a character set that removes @var{char1} @dots{} from @var{char-set}.
It is noop if @var{char-set} doesn't have @var{char1} @dots{}.

The linear update version @code{char-set-delete!} may modify
@var{char-set}.
@end defun

@defun char-set-union char-set @dots{}
@defunx char-set-union! char-set1 char-set2 @dots{}
[R7RS charset]
@{@t{scheme.charset}@}
Returns a character set of all characters in any one of
@var{char-set} @dots{}.
Without arguments, returns an empty charset.

The linear update version @code{char-set-union!} may modify
@var{char-set1}.
@end defun

@defun char-set-intersection char-set @dots{}
@defunx char-set-intersection! char-set1 char-set2 @dots{}
[R7RS charset]
@{@t{scheme.charset}@}
Returns a character set of every character that
is in all of @var{char-set} @dots{}.
Without arguments, returns @code{char-set:full}.

The linear update version @code{char-set-intersection!} may modify
@var{char-set1}.
@end defun

@defun char-set-difference char-set1 char-set2 @dots{}
@defunx char-set-difference! char-set1 char-set2 @dots{}
[R7RS charset]
@{@t{scheme.charset}@}
Returns a character set of every character that is in @var{char-set1}
but not in any of @var{char-set2} @dots{}.

The linear update version @code{char-set-difference!} may modify
@var{char-set1}.
@end defun

@defun char-set-xor char-set @dots{}
@defunx char-set-xor! char-set1 char-set2 @dots{}
[R7RS charset]
@{@t{scheme.charset}@}
With zero arguments, returns an empty charset.
With one argument, it is returned as is.
With two arguments, returns a character set of every character that
is in either one of two sets, but not in both.
With more than two arguments, it returns
@code{(char-set-xor (char-set-xor set1 set2) set3 @dots{})}.

The linear update version @code{char-set-xor!} may modify
@var{char-set1}.
@end defun

@defun char-set-diff+intersection char-set1 char-set2 @dots{}
@defunx char-set-diff+intersection! char-set1 char-set2 char-set3 @dots{}
[R7RS charset]
@{@t{scheme.charset}@}
Returns two values, the result of
@code{(char-set-difference char-set1 char-set2 @dots{}} and the result of
@code{(char-set-intersection char-set1 char-set2 @dots{}}.
@end defun


@node R7RS hash tables, R7RS immutable lists, R7RS character sets, R7RS large
@subsection @code{scheme.hash-table} - R7RS hash tables
@c NODE R7RSハッシュテーブル, @code{scheme.hash-table} - R7RSハッシュテーブル

@deftp {Module} scheme.hash-table
@mdindex scheme.hash-table
This module provides hash table library, originally defined as @code{srfi-125}.

Hash table provided with this module is the same as Gauche's built-in
hash table.  However, srfi-125 introduces procedures that conflict
with Gauche's original procedures, so Gauche provides those procedures
built-in but under aliases.
@xref{Hashtables}, for the built-in hash table procedures.

With this module, procedures are provided as defined in R7RS.  Use this
module when you're writing portable code.

Srfi-125 also defines compatibility procedures with srfi-69, although saying
they're deprecated.  Those deprecated procedures are supported in this
module, too.

The following procedures are the same as Gauche's built-in.
@example
hash-table?         hash-table-contains? hash-table-exists?  
hash-table-empty?   hash-table=?         hash-table-mutable? 
hash-table-ref      hash-table-ref/default
hash-table-set!     hash-table-update!/default
hash-table-clear!   hash-table-size   hash-table-keys
hash-table-values   hash-table-copy   hash-table-empty-copy
hash-table->alist   hash-table-union! hash-table-intersection!
hash-table-difference!                hash-table-xor!
@end example

@xref{Hashtables}, for the description of those procedures.

The following procedures are also provided as Gauche's built-in,
but with @code{-r7} suffix.
@example
hash-table         hash-table-delete! hash-table-intern!
hash-table-update! hash-table-pop!    hash-table-find
hash-table-count   hash-table-map     hash-table-for-each
hash-table-map!    hash-table-map->list
hash-table-prune!
@end example
@end deftp

@defun make-hash-table comparator arg @dots{}
@defunx make-hash-table equal-proc hash-proc arg @dots{}
[R7RS hash-table]
@{@t{scheme.hash-table}@}
This enhances built-in @code{make-hash-table} with the second form,
that takes two procedures instead of one comparator, as srfi-69.

In the srfi-69 form, @var{equal-proc} is a procedure taking two keys
to see if they are the same, and @var{hash-proc} is a procedure taking
a key to calculate its hash value (nonnegative fixnum).
The compatibility form is deprecated and should be avoided in the new code.

The optional @var{arg} @var{dots} are implementation-dependent,
and specify various properties of the created hash table.
They are ignored in Gauche.
@end defun

@defun hash-table cmpr key value @dots{}
[R7RS hash-table]
@{@t{scheme.hash-table}@}
This is the same as built-in @code{hash-table-r7} (@pxref{Hashtables}).

Construct a new hash table with key-comparator @var{cmpr}.  It is
populated by @var{key} @var{value} @dots{}, which is a list with
keys and values appear alternatively.  It is an error if the length
of key-value list is not even.

Note that srfi-125 defines this procedure to return an immutable
hash table if the implementation supports one.  Gauche doesn't provide
immutable hash tables (we do have immutable map
instead, @pxref{Immutable map}), but when you're writing a portable
program, be careful not to modify the table returned by this procedure.
@end defun

@defun alist->hash-table alist cmpr arg @dots{}
@defunx alist->hash-table alist equal-proc hash-proc cmpr arg @dots{}
[R7RS hash-table]
@{@t{scheme.hash-table}@}
This enhances built-in @code{alist->hash-table} with the second form,
that takes two procedures instead of one comparator, as srfi-69.

In the srfi-69 form, @var{equal-proc} is a procedure taking two keys
to see if they are the same, and @var{hash-proc} is a procedure taking
a key to calculate its hash value (nonnegative fixnum).
The compatibility form is deprecated and should be avoided in the new code.

The optional @var{arg} @var{dots} are implementation-dependent,
and specify various properties of the created hash table.
They are ignored in Gauche.
@end defun

@defun hash-table-unfold p f g seed comparator :optional arg @dots{}
[R7RS hash-table]
@{@t{scheme.hash-table}@}
Same as Gauche's built-in @code{hash-table-unfold}, except that this
allows optional arguments, which are ignored.  They are
implementation-specific parameters to tune the created hash tables.
@xref{Hashtables}, for the detailed description.
@end defun


@defun hash-table-delete! ht key @dots{}
[R7RS hash-table]
@{@t{scheme.hash-table}@}
This is the same as built-in @code{hash-table-delete!-r7}.

Deletes entries associated with the given @var{key}s from the
table @var{ht}.  It is ok if @var{ht} doesn't have @var{key}.
Returns the number of entries that are actually deleted.

It differs from built-in @code{hash-table-delete!} in two points:
The built-in one can take exactly one @var{key}, and returns
a boolean indicating if the entry is actually deleted.
@end defun

@defun hash-table-intern! ht key failure
[R7RS hash-table]
@{@t{scheme.hash-table}@}
This is the same as built-in @code{hash-table-intern!-r7}.

Search @var{key} in @var{ht}.  If it is found, returns the associated
value.  If it is not found, call @var{failure} without artuments,
and insert a new entry associating @var{key} and the value
@var{failure} returns, and returns that new value.
@end defun

@defun hash-table-update! ht key updater :optional failure success
[R7RS hash-table]
@{@t{scheme.hash-table}@}
This is the same as built-in @code{hash-table-update!-r7}.
It takes different optional arguments from built-in @code{hash-table-update!}.

@var{Updater} is a procedure that takes one argument,
@var{failure} is a thunk, and @var{success} is a procedure
that takes one argument.

Works the same as follows, except maybe more efficiently.
@example
(hash-table-set! ht key (updater (hash-table-ref ht key failure success)))
@end example
@end defun

@defun hash-table-pop! ht
[R7RS hash-table]
@{@t{scheme.hash-table}@}
This is the same as built-in @code{hash-table-pop!-r7}.
It is a completely different procedure as built-in @code{hash-table-pop!}.

Removes an arbitrary entry in the hash table @var{ht}, and
returns the removed entry's key and value as two values.

If @var{ht} is empty, an error is signalled.
@end defun

@defun hash-table-find proc ht failure
[R7RS hash-table]
@{@t{scheme.hash-table}@}
This is the same as built-in @code{hash-table-find-r7}.
It takes different arguments from built-in @code{hash-table-find}.

Calls @var{proc} with a key and a value of each entry in @var{ht},
until @var{proc} returns non-false value.  If @var{proc} returns
non-false value, @code{hash-table-find} immediately returns it.
If @var{proc} returns @code{#f} for all entries, calls a thunk
@var{failure} and returns its result.
@end defun

@defun hash-table-count ht
[R7RS hash-table]
@{@t{scheme.hash-table}@}
This is the same as built-in @code{hash-table-count-r7}.

Calls @var{proc} with a key and a value of each entry in @var{ht},
and returns the number of times when @var{proc} returned true.
@end defun

@defun hash-table-map proc cmpr ht
[R7RS hash-table]
@{@t{scheme.hash-table}@}
This is the same as built-in @code{hash-table-map-r7}.
This is different from built-in @code{hash-table-map}.

Creates a fresh hashtable with a key comparator @var{cmpr}, then
populate it by inserting the key and the result of applying @var{proc}
on the value of each entry in @var{ht}.
@end defun

@defun hash-table-map! proc ht
[R7RS hash-table]
@{@t{scheme.hash-table}@}
This is the same as built-in @code{hash-table-map!-r7}.

Calls @var{proc} on the value of each entry in @var{ht}, and update
the entry with the result of @var{proc}.
@end defun

@defun hash-table-map->list proc ht
[R7RS hash-table]
@{@t{scheme.hash-table}@}
This is the same as built-in @code{hash-table-map->list-r7},
and same as built-in @code{hash-table-map} (not the @code{scheme.hash-table}'s
@code{hash-table-map}) except the order of the arguments.

Apply @var{proc} on a key and a value of each entry in @var{ht},
in arbitrary order, and returns a list of results.
@end defun

@defun hash-table-for-each proc ht
@defunx hash-table-for-each ht proc
[R7RS hash-table]
@{@t{scheme.hash-table}@}
Apply @var{proc} on a key and a value of each entry in @var{ht}.  The
result of @var{proc} is discarded.  Returns an unspecified value.

This procedure allows arguments in both order for the compatibility---
the first way is the @code{scheme.hash-table} recommended one,
which is the same as built-in @code{hash-table-for-each-r7},
and the latter way is compatible with srfi-69, which is
the same as built-in @code{hash-table-for-each}.

It is unfortunate that this compatibility thing is extremely confusing;
especially in Gauche, you can make anything applicable, so the distinction
between procedures and other objects is blurred.

We recommend that you stick to one way or another within a module; if
your module uses built-in interface, use @code{(hash-table-for-each ht proc)}.
If your module imports @code{scheme.hash-table},
use @code{(hash-table-for-each proc ht)}.
@end defun

@defun hash-table-fold proc seed ht
@defunx hash-table-fold ht proc seed
[R7RS hash-table]
@{@t{scheme.hash-table}@}
The @var{proc} argument takes three arguments, a key, a value, and
the current seed value.  The procedure applies @var{proc} for
each entry in @var{ht}, using @var{seed} as the first seed value,
and using the previous result of @var{proc} as the subsequent seed value.
Returns the result of the last call of @var{seed}.

This procedure allows arguments in both order for the compatibility---
the first way is the @code{scheme.hash-table} recommended one,
which is the same as built-in @code{hash-table-fold-r7},
and the latter way is compatible with srfi-69, which is
the same as built-in @code{hash-table-fold}.

It is unfortunate that this compatibility thing is extremely confusing.
We recommend that you stick to one way or another within a module; if
your module uses built-in interface, use the second interface.
If your module imports @code{scheme.hash-table},
use the first interface.
@end defun

@defun hash-table-prune! proc ht
[R7RS hash-table]
@{@t{scheme.hash-table}@}
This is the same as built-in @code{hash-table-prune!-r7}.

Apply @var{proc} on a key and a value of each entry in @var{ht},
and deletes the entry if @var{proc} returns a true value.
This procedure returns an unspecified value.
@end defun

@defun hash-table-merge! ht1 ht2
[R7RS hash-table]
@{@t{scheme.hash-table}@}
This is the same as @code{hash-table-union!}, and provided just
for the compatibility with srfi-69.  Deprecated.
@end defun

@defun hash obj :optional ignore
@defunx string-hash obj :optional ignore
@defunx string-ci-hash obj :optional ignore
@defunx hash-by-identity obj :optional ignore
[R7RS hash-table]
@{@t{scheme.hash-table}@}
Provided for the compatibility with srfi-69, and are deprecated.

The first three are the same as built-in @code{default-hash},
@code{string-hash}, and @code{string-ci-hash}, except that
these accept an optional second argument, which is ignored.
Note that @code{hash-by-identity} is also defined as the same
as @code{default-hash} except the ignored optional second argument,
per srfi-125, although the name suggests that it would work as if
@code{eq-hash}.

Do not use these procedures in the new code; you can use comparators
instead (@code{default-comparator}, @code{string-comparator},
@code{string-ci-comparator} and @code{eq-comparator},
@pxref{Predefined comparators}).   If you do need hash function,
you should still avoid @code{hash} and @code{hash-by-identity},
and use @code{default-hash} and @code{eq-hash} instead.
@end defun

@defun hash-table-equivalence-function ht
@defunx hash-table-hash-function ht
[R7RS hash-table]
@{@t{scheme.hash-table}@}
Provided for the compatibility with srfi-69, and are deprecated.

Returns the equivalence function and hash function of a hash table @var{ht}.

For the introspection, we recommend to use
built-in @code{hash-table-comparator}.  (Unfortunately, it is not
included in @code{scheme.hash-table}, though.)
@end defun


@node R7RS immutable lists, R7RS random-access lists, R7RS hash tables, R7RS large
@subsection @code{scheme.ilist} - R7RS immutable lists
@c NODE R7RS変更不可リスト, @code{scheme.ilist} - R7RS変更不可リスト

@deftp {Module} scheme.ilist
@mdindex scheme.ilist
@findex proper-ilist?
@findex ilist?
@findex dotted-ilist?
@findex not-ipair?
@findex null-ilist?
@findex ilist=
@findex icar
@findex icdr
@findex icaar
@findex icadr
@findex icdar
@findex icddr
@findex icaaar
@findex icaadr
@findex icadar
@findex icaddr
@findex icdaar
@findex icdadr
@findex icddar
@findex icdddr
@findex icaaaar
@findex icaaadr
@findex icaadar
@findex icaaddr
@findex icadaar
@findex icadadr
@findex icaddar
@findex icadddr
@findex icdaaar
@findex icdaadr
@findex icdadar
@findex icdaddr
@findex icddaar
@findex icddadr
@findex icdddar
@findex icddddr
@findex icar+icdr
@findex ilist-ref
@findex ifirst
@findex isecond
@findex ithird
@findex ifourth
@findex ififth
@findex isixth
@findex iseventh
@findex ieighth
@findex ininth
@findex itenth
@findex idrop
@findex ilist-tail
@findex itake-right
@findex ilast
@findex last-ipair
@findex ilength
@findex icount
@findex ifor-each
@findex ifold
@findex ipair-fold
@findex ireduce
@findex ifold-right
@findex ipair-fold-right
@findex ireduce-right
@findex ipair-for-each
@findex imember
@findex imemv
@findex imemq
@findex ifind-tail
@findex iany
@findex ievery
@findex ilist-index
@findex idrop-while
@findex iassoc
@findex iassq
@findex iassv
@findex iapply
@findex make-ilist-comparator
@findex make-improper-ilist-comparator
@findex make-icar-comparator
@findex make-icdr-comparator
This module provides a set of procedures that handles immutable pairs
and lists.

The standard allows an implementation to have mutable pairs and immutable
pairs separately, so it defines immutable version of most @code{scheme.list}
procedures.   In Gauche, mutable pairs and immutable pairs are both
abstract ``pairs'', and all procedures that accesses pairs (without modifying
them) works seamlessly on both kind.

Consequently, the following procedures are just aliases of their
non-immutable versions (just remove @code{i} prefix from them).
Note that these procedures and variables in Gauche do not reject if the input is
mutable pairs/lists, but such usage may not be portable.

@example
proper-ilist?     ilist?            dotted-ilist?     not-ipair?
null-ilist?       ilist=
icar              icdr              icaar             icadr
icdar             icddr             icaaar            icaadr
icadar            icaddr            icdaar            icdadr
icddar            icdddr            icaaaar           icaaadr
icaadar           icaaddr           icadaar           icadadr
icaddar           icadddr           icdaaar           icdaadr
icdadar           icdaddr           icddaar           icddadr
icdddar           icddddr           icar+icdr         ilist-ref
ifirst            isecond           ithird            ifourth
ififth            isixth            iseventh          ieighth
ininth            itenth
idrop             ilist-tail        itake-right
ilast             last-ipair        ilength           icount
ifor-each         ifold             ipair-fold        ireduce
ifold-right       ipair-fold-right  ireduce-right     ipair-for-each
imember           imemv             imemq             ifind-tail
iany              ievery            ilist-index       idrop-while
iassoc            iassq             iassv             iapply
make-ilist-comparator               make-improper-ilist-comparator
make-icar-comparator                make-icdr-comparator
@end example
@end deftp

@node R7RS random-access lists, R7RS immutable deques, R7RS immutable lists, R7RS large
@subsection @code{scheme.rlist} - R7RS random-access lists
@c NODE R7RSランダムアクセスリスト, @code{scheme.rlist} - R7RSランダムアクセスリスト

@deftp {Module} scheme.rlist
@mdindex scheme.rlist
This module provides an alternative datatype for pairs and lists,
which are immutable and allows O(log n) random access, while
maintaining O(1) @code{car} and @code{cdr} operations.
This is originally defined as @code{srfi-101}.  We call this datatype
@emph{rlist} in the following explanation.

The srfi allows a Scheme implementation to adopt rlist
as the built-in pairs and lists, so the procedure names are
duplicated from the Scheme primitives.  If you use this module,
you might want to import with prefix
(e.g. @code{(use scheme.rlist :prefix rlist:)}).

In Gauche, we implement rlist on top of skew-list
(@pxref{Skew binary random-access lists}).  The main difference
is that skew-list only allows proper lists, while rlist allows
improper lists (the @code{cdr} of the last pair can be an arbitrary
objects).

However, having improper lists makes things a lot complicated.  If you just
need a list with fast random access, you want to use skew-list.
Use rlist only if you need to deal with improper lists.

The following procedures behave just like the built-in counterparts,
except they take/return rlists instead of ordinary pairs and lists.
(NB: @code{list-ref} and @code{list-tail} here doesn't take the optional
fallback argument, for they are Gauche's extension).

@example
pair?     cons       car        cdr
caar      cadr       cdar       cddr
caaar     caadr      cadar      caddr
cdaar     cdadr      cddar      cdddr
caaaar    caaadr     caadar     caaddr
cadaar    cadadr     caddar     cadddr
cdaaar    cdaadr     cdadar     cdaddr
cddaar    cddadr     cdddar     cddddr
null?     list?      list       make-list
length    append     reverse    list-tail
list-ref  map        for-each
@end example

This module also exports a syntax @code{quote}, which denotes
the literal rlist.  @code{(quote (a (b c)))} becomes a literal
rlist consists of elements @code{a}, and an rlist consists
of @code{b} and @code{c}.

Note that if you import @code{scheme.rlist} without suffix,
the shorthand notation @code{'(a (b c))} refers to @code{scheme.rlist#quote},
instead of built-in @code{quote}.
@end deftp

@defun list-set rlist k obj
Returns a new rlist which is the same as @var{rlist} except
that its @var{k}-th element is replaced with @var{obj}.
This is O(log n) operation where n is the length of @var{rlist}.
@end defun

@defun list-ref/update rlist k proc
Returns two values, the result of @code{(list-ref rlist k)}
and the result of @code{(list-set rlist k (proc (list-ref rlist k)))},
but may be more efficient.
@end defun

@defun random-access-list->linear-access-list rlist
Convert a proper rlist to an ordinary list.  An error is
thrown when @var{rlist} is not proper.
The conversion is only done in the ``spine'' of @var{rlist}; that is,
if @var{rlist} is nested, only the outermost @var{rlist} is converted.
@end defun

@defun linear-access-list->linear-access-list list
Convert a proper ordinary list to an rlist.
An error is thrown when @var{list} is not proper.
The conversion is only done in the ``spine'' of @var{list}; that is,
if @var{list} is nested, only the outermost @var{list} is converted.
@end defun


@node R7RS immutable deques, R7RS immutable texts, R7RS random-access lists, R7RS large
@subsection @code{scheme.ideque} - R7RS immutable deques
@c NODE R7RS変更不可な両端キュー, @code{scheme.ideque} - R7RS変更不可な両端キュー

@deftp {Module} scheme.ideque
@mdindex scheme.ideque
This module provides a functional double-ended queue
(deque, pronounced as ``deck''),
with amortized O(1) access of queue operations on either end.

It also serves as a convenient bidirectional list structures
in a sense that operations from the end of the list is just as
efficient as the ones from the front.

Note: If you don't need immutability and wants space-efficient
deque, you can also use @code{data.ring-buffer} as a deque
(@pxref{Ring buffer}).

This module was originally defined as @code{srfi-134}, then
became a part of R7RS large.

Gauche's @code{data.ideque} is a superset of this module.
@xref{Immutable deques}.
@end deftp

@defun ideque element @dots{}
[R7RS ideque]
@{@t{scheme.ideque}@}
Returns an ideque with the given elements.
@end defun

@defun ideque-unfold p f g seed
[R7RS ideque]
@{@t{scheme.ideque}@}
@end defun

@defun ideque-unfold-right p f g seed
[R7RS ideque]
@{@t{scheme.ideque}@}
@end defun

@defun ideque-tabulate size init
[R7RS ideque]
@{@t{scheme.ideque}@}
@end defun

@defun ideque? idq
[R7RS ideque]
@{@t{scheme.ideque}@}
@end defun

@defun ideque-empty? idq
[R7RS ideque]
@{@t{scheme.ideque}@}
@end defun

@defun ideque-add-front idq x
@defunx ideque-add-back idq x
[R7RS ideque]
@{@t{scheme.ideque}@}
@end defun

@defun ideque-front idq
@defunx ideque-back idq
[R7RS ideque]
@{@t{scheme.ideque}@}
@end defun

@defun ideque-remove-front idq
@defunx ideque-remove-back idq
[R7RS ideque]
@{@t{scheme.ideque}@}
@end defun

@defun ideque-reverse idq
[R7RS ideque]
@{@t{scheme.ideque}@}
@end defun

@defun ideque= idq idq2 @dots{}
[R7RS ideque]
@{@t{scheme.ideque}@}
@end defun

@defun ideque-ref idq n
[R7RS ideque]
@{@t{scheme.ideque}@}
@end defun

@defun ideque-take idq n
@defunx ideque-take-right idq n
[R7RS ideque]
@{@t{scheme.ideque}@}
@end defun

@defun ideque-drop idq n
@defunx ideque-drop-right idq n
[R7RS ideque]
@{@t{scheme.ideque}@}
@end defun

@defun ideque-split-at idq n
[R7RS ideque]
@{@t{scheme.ideque}@}
@end defun

@defun ideque-length idq
[R7RS ideque]
@{@t{scheme.ideque}@}
@end defun

@defun ideque-append idq @dots{}
[R7RS ideque]
@{@t{scheme.ideque}@}
@end defun

@defun ideque-zip idq idq2 @dots{}
[R7RS ideque]
@{@t{scheme.ideque}@}
@end defun

@defun ideque-map proc idq @dots{}
[R7RS ideque]
@{@t{scheme.ideque}@}
@end defun

@defun ideque-filter-map proc idq @dots{}
[R7RS ideque]
@{@t{scheme.ideque}@}
@end defun

@defun ideque-for-each proc idq @dots{}
@defunx ideque-for-each-right proc idq @dots{}
[R7RS ideque]
@{@t{scheme.ideque}@}
@end defun

@defun ideque-fold proc knil idq @dots{}
@defunx ideque-fold-right proc knil idq @dots{}
[R7RS ideque]
@{@t{scheme.ideque}@}
@end defun

@defun ideque-append-map proc idq @dots{}
[R7RS ideque]
@{@t{scheme.ideque}@}
@end defun

@defun ideque-filter pred idq
@defunx ideque-remove pred idq
[R7RS ideque]
@{@t{scheme.ideque}@}
@end defun

@defun ideque-partition pred idq
[R7RS ideque]
@{@t{scheme.ideque}@}
@end defun

@defun ideque-find pred idq :optional failure
@defunx ideque-find-right pred idq :optional failure
[R7RS ideque]
@{@t{scheme.ideque}@}
@end defun

@defun ideque-take-while pred idq
@defunx ideque-take-while-right pred idq
[R7RS ideque]
@{@t{scheme.ideque}@}
@end defun

@defun ideque-drop-while pred idq
@defunx ideque-drop-while-right pred idq
[R7RS ideque]
@{@t{scheme.ideque}@}
@end defun

@defun ideque-span pred idq
@defunx ideque-break pred idq
[R7RS ideque]
@{@t{scheme.ideque}@}
@end defun

@defun ideque-any pred idq @dots{}
@defunx ideque-every pred idq @dots{}
[R7RS ideque]
@{@t{scheme.ideque}@}
@end defun

@defun ideque->list idq
@defunx list->ideque list
[R7RS ideque]
@{@t{scheme.ideque}@}
@end defun

@defun ideque->generator idq
@defunx generator->ideque gen
[R7RS ideque]
@{@t{scheme.ideque}@}
@end defun

@node R7RS immutable texts, R7RS generators, R7RS immutable deques, R7RS large
@subsection @code{scheme.text} - R7RS immutable texts
@c NODE R7RS変更不可なテキスト, @code{scheme.text} - R7RS変更不可なテキスト

@deftp {Module} scheme.text
@mdindex scheme.text
This module provides @emph{text} type, an immutable string
with O(1) random access.  This is originally defined in srfi-135.

In Gauche, a string with index access generally takes O(n); however,
if the string is ASCII-only or you precalculate string indexes,
index access becomes O(1) (@pxref{String indexing}).
So, a text in Gauche is just an immutable indexed string.  It satisfies
@code{string?}, too.

Note that, in Gauche, text is not disjoint from string, so @emph{textual}
type is just a string type, and many @code{textual-*} procedures are
just aliases to the corresponding @code{string-*} procedures.
Use this module if you need portability.
@end deftp

@defun text? obj
[R7RS text]
@{@t{scheme.text}@}
Returns @code{#t} iff @var{obj} is a text, which is an immutable
indexed string in Gauche.  Note that a text type is not disjoint
from a string in Gauche.
@end defun

@defun textual? obj
[R7RS text]
@{@t{scheme.text}@}
Returns @code{#t} iff @var{obj} is either a text or a string.
In Gauche, this is just an alias of @code{string?}.
@end defun

@defun textual-null? obj
[R7RS text]
@{@t{scheme.text}@}
Returns @code{#t} iff @var{obj} is an empty string/text.  In Gauche
this is just an alias of @code{string-null?}.
@end defun

@defun textual-every pred textual :optional start end
@defunx textual-any pred textual :optional start end
[R7RS text]
@{@t{scheme.text}@}
@end defun

@defun make-text len char
[R7RS text]
@{@t{scheme.text}@}
In Gauche it is same as @code{make-string}, except that the returned
string is immutable and indexed, and you can't omit @var{char}.
@end defun

@defun text char @dots{}
[R7RS text]
@{@t{scheme.text}@}
Like @code{string}, but returned string is immutable and indexed.
@end defun

@defun text-tabulate proc len
[R7RS text]
@{@t{scheme.text}@}
Like @code{string-tabulate}, but returned string is immutable and indexed
(@pxref{String constructors}).
@end defun

@defun text-unfold p f g seed :optional base make-final
@defunx text-unfold-right p f g seed :optional base make-final
[R7RS text]
@{@t{scheme.text}@}
Like @code{string-unfold} and @code{string-unfold-right},
but returned string is immutable and indexed
(@pxref{String constructors}).  The mapper procedure @var{f} may return
a string instead of a character.
@end defun

@defun text-length text
[R7RS text]
@{@t{scheme.text}@}
@end defun

@defun text-ref text index
[R7RS text]
@{@t{scheme.text}@}
@end defun

@defun textual-length textual
@defunx textual-ref textual index
[R7RS text]
@{@t{scheme.text}@}
@end defun

@defun textual->text textual
[R7RS text]
@{@t{scheme.text}@}
Takes a string, and returns an immutable, indexed string of the same
content.  If @var{textual} is already a such string, it is returned as is.
@end defun

@defun textual->string textual :optional start end
@defunx textual->vector textual :optional start end
@defunx textual->list textual :optional start end
[R7RS text]
@{@t{scheme.text}@}
Converts a textual to a fresh mutable string,
a vector and a list, respectively.
These are aliases of @code{string-copy}, @code{string->vector}
and @code{string->list} in Gauche.
@end defun

@defun string->text string :optional start end
@defunx vector->text char-vector :optional start end
@defunx list->text char-list :optional start end
[R7RS text]
@{@t{scheme.text}@}
Convert a string, a vector of characters, and a list of characters
to an immutable indexed string.
If an immutable indexed string is given to @code{string->text} without
start/end arguments, the input is returned as is.
@end defun

@defun reverse-list->text char-list
[R7RS text]
@{@t{scheme.text}@}
Same as @code{(list->text (reverse char-list))} but maybe more efficient.
@end defun

@defun textual->utf8 textual :optional start end
[R7RS text]
@{@t{scheme.text}@}
Returns a bytevector that contains utf8 encoding of the input
textual.  In Gauche, it is the same as @code{string->utf8}
(@pxref{Unicode transfer encodings}).
@end defun

@defun textual->utf16 textual :optional start end
[R7RS text]
@{@t{scheme.text}@}
Returns a bytevector that contains utf16 encoding of the input
textual, with BOM attached, and in the native byteorder.
In Gauche, it is the same as
@code{(string->utf16 textual (native-endian) #t [start end])}
(@pxref{Unicode transfer encodings}).
@end defun

@defun textual->utf16be textual :optional start end
@defunx textual->utf16le textual :optional start end
[R7RS text]
@{@t{scheme.text}@}
Returns a bytevector that contains utf16be and utf16le encoding of the input
textual.  No BOM is attached.
In Gauche, they are the same as
@code{(string->utf16 textual 'big-endian #f [start end])} and
@code{(string->utf16 textual 'little-endian #t [start end])}
(@pxref{Unicode transfer encodings}).
@end defun

@defun utf8->text bytevector :optional start end
[R7RS text]
@{@t{scheme.text}@}
Converts a utf8 octet sequence stored in @var{bytevector} to a text.
If the octet sequence begins with BOM sequence, it is interpreted
as a character U+FEFF.  Optional @var{start}/@var{end} arguments
limits the input range of @var{bytevector}.

If the input contains an invalid utf-8 sequence, and Gauche's native
encoding is utf-8, it is replaced by a unicode replacement character
U+FFFD.  (NB: Srfi-135 says it is an error.)
@end defun

@defun utf16->text bytevector :optional start end
@defunx utf16be->text bytevector :optional start end
@defunx utf16le->text bytevector :optional start end
[R7RS text]
Converts a utf16 octet sequence stored in @var{bytevector} to a text.
For @code{utf16->text}, the sequence may begin with BOM,
in which case it determines the endianness.
Otherwise, platform's native endianness is assumed.
Fro @code{utf16be->text} and @code{utf16le->text}, the input is
assumed to be in UTF16BE/UTF16LE respectively; if it begins with BOM
it is treated as a character U+FEFF.

Optional @var{start}/@var{end} arguments
limits the input range of @var{bytevector}.

If the length of input (@var{end} - @var{start}, if the range is limited)
isn't even, an error is thrown.

If the input contains an invalid utf-16 sequence (unpaired surrogates),
it is replaced by a unicode replacement character U+FFFD.
(NB: Srfi-135 says it is an error.)
@{@t{scheme.text}@}
@end defun

@defun subtext text start end
@defunx subtextual textual start end
[R7RS text]
@{@t{scheme.text}@}
Returns a text between @var{start}-th (inclusive) and @var{end}-th (exclusive)
characters in the input.
@end defun

@defun textual-copy textual :optional start end
[R7RS text]
@{@t{scheme.text}@}
Returns a copy of @var{textual}, optionally limited between
@var{start}/@var{end}.

Srfi-135 specifies that even the input is a text, the returned one
must be freshly allocated.  In Gauche, string body is immutable anyway,
so it isn't a big deal.
@end defun

@defun textual-take textual nchars
@defunx textual-drop textual nchars
@defunx textual-take-right textual nchars
@defunx textual-drop-right textual nchars
@defunx textual-pad textual len :optional char start end
@defunx textual-pad-right textual len :optional char start end
@defunx textual-trim textual :optional pred start end
@defunx textual-trim-right textual :optional pred start end
@defunx textual-trim-both textual :optional pred start end
[R7RS text]
@{@t{scheme.text}@}
In Gauche, these are the same as corresponding string operations
(@code{string-take}, @code{string-drop}, @code{string-take-right},
@code{string-drop-right}, @code{string-pad}, @code{string-pad-right},
@code{string-trim}, @code{string-tirm-right}, and @code{string-trim-both}),
except that the returned string is always immutable and indexed.
@xref{SRFI-13 String selection}, for these string procedures.
@end defun

@defun textual-replace textual1 textual2 start1 end1 :optional start2 end2
[R7RS text]
@{@t{scheme.text}@}
In Gauche, this is same as @code{string-replace},
except that the returned string is always immutable and indexed.
@xref{SRFI-13 Other string operations}, for the details.
@end defun

@defun textual=? textual1 textual2 textual3 @dots{}
@defunx textual<? textual1 textual2 textual3 @dots{}
@defunx textual>? textual1 textual2 textual3 @dots{}
@defunx textual<=? textual1 textual2 textual3 @dots{}
@defunx textual>=? textual1 textual2 textual3 @dots{}
[R7RS text]
@{@t{scheme.text}@}
In Gauche, these are just aliases of built-in
@code{string=?}, @code{string<?}, @code{string>?},
@code{string<=?} and @code{string>?}, respectively.
@xref{String comparison}, for the details.
@end defun

@defun textual-ci=? textual1 textual2 textual3 @dots{}
@defunx textual-ci<? textual1 textual2 textual3 @dots{}
@defunx textual-ci>? textual1 textual2 textual3 @dots{}
@defunx textual-ci<=? textual1 textual2 textual3 @dots{}
@defunx textual-ci>=? textual1 textual2 textual3 @dots{}
[R7RS text]
@{@t{scheme.text}@}
In Gauche, these are just aliases of @emph{the unicode version} of
@code{string-ci=?}, @code{string-ci<?}, @code{string-ci>?},
@code{string-ci<=?} and @code{string-ci>?}, respectively.
@xref{Full string case conversion}, for the details.
@end defun

@defun textual-prefix-length textual1 textual2 :optional start1 end1 start2 end2
@defunx textual-suffix-length textual1 textual2 :optional start1 end1 start2 end2
@defunx textual-prefix? textual1 textual2 :optional start1 end1 start2 end2
@defunx textual-suffix? textual1 textual2 :optional start1 end1 start2 end2
[R7RS text]
@{@t{scheme.text}@}
@end defun

@defun textual-index textual pred :optional start end
@defunx textual-index-right textual pred :optional start end
@defunx textual-skip textual pred :optional start end
@defunx textual-skip-right textual pred :optional start end
@defunx textual-contains textual1 textual2 :optional start1 end1 start2 end2
@defunx textual-contains-right textual1 textual2 :optional start1 end1 start2 end2
[R7RS text]
@{@t{scheme.text}@}
@end defun

@defun textual-upcase textual
@defunx textual-downcase textual
@defunx textual-foldcase textual
@defunx textual-titlecase textual
[R7RS text]
@{@t{scheme.text}@}
@end defun

@defun textual-append textual @dots{}
@defunx textual-concatenate textual-list
[R7RS text]
@{@t{scheme.text}@}
@end defun

@defun textual-concatenate-reversse args :optional final-textual end
[R7RS text]
@{@t{scheme.text}@}
@end defun

@defun textual-join textual-list :optional delimiter grammar
[R7RS text]
@{@t{scheme.text}@}
@end defun

@defun textual-fold kons knil textual :optional start end
@defunx textual-fold-right kons knil textual :optional start end
[R7RS text]
@{@t{scheme.text}@}
@end defun

@defun textual-map proc textural1 textural2 @dots{}
[R7RS text]
@{@t{scheme.text}@}
@end defun

@defun textual-for-each proc textual1 textual2 @dots{}
[R7RS text]
@{@t{scheme.text}@}
@end defun

@defun textual-map-index proc textual :optional start end
[R7RS text]
@{@t{scheme.text}@}
@end defun

@defun textual-for-each-index proc textual :optional start end
[R7RS text]
@{@t{scheme.text}@}
@end defun

@defun textual-count textual pred :optional start end
[R7RS text]
@{@t{scheme.text}@}
@end defun

@defun textual-filter pred textual :optional start end
@defunx textual-remove pred textual :optional start end
[R7RS text]
@{@t{scheme.text}@}
@end defun

@defun textual-replicate textual from to :optional start end
[R7RS text]
@{@t{scheme.text}@}
@end defun

@defun textual-split textual delimiter :optional grammar limit start end
[R7RS text]
@{@t{scheme.text}@}
Like @code{string-split}, except that the returned strings are all
immutable and indexed.  @xref{String utilities}, for the details.
@end defun


@node R7RS generators, R7RS lazy sequences, R7RS immutable texts, R7RS large
@subsection @code{scheme.generator} - R7RS generators
@c NODE R7RSジェネレータ, @code{scheme.generator} - R7RSジェネレータ

@deftp {Module} scheme.generator
@mdindex scheme.generator
This module provides generators and accumulators.
They were first defined in srfi-121,
then enhanced in srfi-158, and finally
incorporated R7RS large as @code{(scheme generator)}.

A generator is a thunk to generate a sequence of values, potentially
terminated by EOF.  Procedures to deal with generators are
provided by @code{gauche.generator}, which is a superset of srfi-121.
@xref{Generators}, for the details.

An accumulator is an opposite of generators.
They are procedures
that work as consumers.  An accumulator takes one argument.
When non-eof value is given, the value is stored, and when EOF
is given, the accumulated value is returned.
How the values are accumulated depends on the accumulator.

Once EOF is given, the accumulator is ``finalized''.  Subsequent
EOF makes it return the same accumulated value.  It is undefined
if other values are passed after EOF is passed.

The accumulator can be used to parameterize procedures that yield
aggregate objects.  Consider the following procedure, which
takes items from two generators and accumulate them alternatively.
(Note that @code{glet*} is Gauche's procedure but not in srfi-158).

@example
(define (intertwine acc gen1 gen2)
  (let loop ()
    (glet* ([a (gen1)]
            [b (gen2)])
      (acc a)
      (acc b)
      (loop)))
  (acc (eof-object)))
@end example

The procedure can return various type of collections, without
knowing the actual type---the passed accumulator determines it.

@example
(intertwine (list-accumulator) (giota 5) (giota 5 100))
  @result{} (0 100 1 101 2 102 3 103 4 104)
(intertwine (vector-accumulator) (giota 5) (giota 5 100))
  @result{} #(0 100 1 101 2 102 3 103 4 104)
(intertwine (bytevector-accumulator) (giota 5) (giota 5 100))
  @result{} #u8(0 100 1 101 2 102 3 103 4 104)
@end example

Note: In Gauche, you can also use classes to parameterize returned
container types (e.g. @code{map-to}),
for many collection classes support @emph{builder protocol}.
@xref{Collection framework}, for the details.
Accumulator has the flexibility that you can provide more than one
ways to construct return value on the same type (e.g. forward and reverse
list).
@end deftp

The following generator procedures are explained in
@code{gauche.generator} section (@pxref{Generators}):

@itemize
@item @ref{Generator constructors}:
@example
generator                circular-generator       make-iota-generator
make-range-generator     make-coroutine-generator
make-unfold-generator    make-for-each-generator
list->generator
vector->generator        reverse-vector->generator
string->generator        bytevector->generator
@end example
@item @ref{Generator operations}:
@example
gcons*                   gappend                  gflatten
ggroup                   gmerge                   gmap
gcombine                 gfilter                  gremove
gstate-filter            ggroup
gtake                    gdrop                    gtake-while
gdrop-while              gdelete                  gdelete-neighbor-dups
gindex                   gselect
@end example
@item @ref{Generator consumers}:
@example
generator->list         generator->reverse-list   generator-map->list
generator->vector       generator->vector!        generator->string
generator-count         generator-any             generator-every
generator-unfold
@end example
@item @ref{Folding generated values}:
@example
generator-fold          generator-for-each        generator-find
@end example
@end itemize

The following are accumulator procedures:

@defun make-accumulator kons knil finalizer
[R7RS generator]
@{@t{scheme.generator}@}
Creates and returns an accumulator with a state,
whose initial value is @var{knil}.
When non-EOF value @var{v} is passed to the accumulator,
@var{kons} is called as @code{(kons v state)}, and its result
becomes the new state value.  When EOF value is passed,
@code{(finalizer state)} is called and its result becomes
the result of accumulator.
@end defun

@defun list-accumulator
@defunx reverse-list-accumulator
[R7RS generator]
@{@t{scheme.generator}@}
Creates and returns accumulators that return accumulated value
as a list, in the accumulated order (@code{list-accumulator})
or the reverse order (@code{reverse-list-accumulator}).
@end defun

@defun vector-accumulator
@defunx reverse-vector-accumulator
@defunx bytevector-accumulator
[R7RS generator]
@{@t{scheme.generator}@}
Returns accumulators that return accumulated value
as a fresh vector or bytevector (u8vector),
in the accumulated order (@code{vector-accumulator},
@code{bytevector-accumulator})
or the reverse order (@code{reverse-vector-accumulator}).
There's no @code{reverse-bytevector-accumulator}.
@end defun

@defun vector-accumulator! vec at
@defunx bytevector-accumulator! bvec at
[R7RS generator]
@{@t{scheme.generator}@}
The @var{vec} or @var{bvec} argument is a mutable vector or
bytevector (u8vector), and is used as a buffer.

Returns an accumulator that stores the accumulated values in the
buffer, starting from the index @var{at}.
It is an error if the accumulator gets more values after
the buffer reaches at the end.

Once EOF is passed to the accumulator, @var{vec} or @var{bvec}
is returned, respectively.
@end defun

@defun string-accumulator
[R7RS generator]
@{@t{scheme.generator}@}
Returns an accumulator that accepts characters and accumulates
them to a string.
@end defun

@defun sum-accumulator
@defunx product-accumulator
@defunx count-accumulator
[R7RS generator]
@{@t{scheme.generator}@}
Returns accumulators that yield a scalar value.

The accumulator created by @code{sum-accumulator} and
@code{product-accumulator} accepts numbers,
and keep adding or multiplying it with the accumulated value
(the default value is 0 and 1, respectively).

The accumulator created by @code{count-accumulator} accepts any
objects and just counting it.
@end defun


@node R7RS lazy sequences, R7RS stream, R7RS generators, R7RS large
@subsection @code{scheme.lseq} - R7RS lazy sequences
@c NODE R7RS遅延シーケンス, @code{scheme.lseq} - R7RS遅延シーケンス


@deftp {Module} scheme.lseq
@mdindex scheme.lseq
This module provides lightweight lazy sequence (lseq), conceptually represented
by a pair of element and generator.  When the rest of sequence is
taken, the generator is evaluated and yields another pair of element and
generator, and so on.  The overhead is one allocation of a pair per
element.  It is much lighter than streams (@pxref{Stream library}),
which requires to create a thunk for every element.

Gauche already has built-in support for such lazy sequences;
we go further to make it behave like ordinary pairs---that is, if you
take cdr of a lazy pair, we automatically forces the generator so
it is indistinguishable from an ordinary pair, modulo side effects.
@xref{Lazy sequences}.

Srfi-127, the original srfi for this module,
is a bit ambiguous whether its lazy sequence @emph{must} be
implemented with a pair whose cdr is a generator procedure, or
it refers to the pair+generator as a conceptual model.  Considering
of the purpose of lazy sequence, the concrete implementation shouldn't
matter; that is, the user of lazy sequence should not count on the fact
that the lseq is an improper list terminated by a generator procedure.
Instead, an lseq should be treated as an opaque object that can be
passed to @code{scheme.lseq} procedures.

With that premise, we implement this module as just a thin wrapper of
Gauche's native lazy sequence.  It is upper-compatible,
except that the code that assumes the internal structure could break.
Notably, the constructor @code{generator->lseq} is the same as
Gauche's built-in, which returns Gauche's lseq, undistinguishable
to the ordinary list.

@example
(procedure? (generator->lseq (generator 1)))
  ;; => #t, in srfi-127 reference implementation,
  ;;    #f, in our implementation.
@end example
@end deftp

@defun lseq? x
[R7RS lseq]
@{@t{scheme.lseq}@}
Returns true iff @var{x} is an object that can be passed to
lseq procedures.  In Gauche, it returns @code{#t} if @var{x} is
a pair or an empty list, since a lazy pair is indistinguishable
from a pair.
@end defun

@defun lseq=? elt=? lseq1 lseq2
[R7RS lseq]
@{@t{scheme.lseq}@}
Compare two lseqs element-wise using @code{elt=?} and returns @code{#t}
iff two lseqs are equal.
@end defun

@defun lseq-car lseq
@defunx lseq-first lseq
[R7RS lseq]
@{@t{scheme.lseq}@}
Returns the first item of @var{lseq}.  If @var{lseq} is empty, an error
is raised.  In Gauche, these are just aliases of @code{car}.
@end defun

@defun lseq-cdr lseq
@defunx lseq-rest lseq
[R7RS lseq]
@{@t{scheme.lseq}@}
Returns the rest of @var{lseq}.  If @var{lseq} is empty, an error
is raised.  In Gauche, these are just aliases of @code{cdr}.
@end defun

@defun lseq-take lseq k
@defunx lseq-drop lseq k
[R7RS lseq]
@{@t{scheme.lseq}@}
Returns an lseq that has first @code{k} items,
or an lseq that skips first @code{k} items, respectively.

An error is signaled when the resulting lseq of @code{lseq-take}
reached at the end of sequence before @code{k} items are taken.
It is different from Gauche's @code{ltake}, which simply returns @code{()}
in such case.

On the other hand,  @code{lseq-drop} is the same as @code{drop}
in Gauche; it just drops @var{k} items from the head of input
sequence, regardless of whether it is an ordinary list or lseq.
@end defun

@defun lseq-realize lseq
[R7RS lseq]
@{@t{scheme.lseq}@}
Realizes all the elements in @var{lseq}, resulting an ordinary list.
@end defun

@defun lseq->generator lseq
[R7RS lseq]
@{@t{scheme.lseq}@}
Creates a generator from @var{lseq}.  In Gauche, this is same
as @code{list->generator}.
@end defun

@defun lseq-length lseq
[R7RS lseq]
@{@t{scheme.lseq}@}
Returns the length of @var{lseq}.  All the elements in @var{lseq} are
realized as the side effect.  In Gauche, this is same as @code{length}.
@end defun

@defun lseq-append lseq lseq2 @dots{}
[R7RS lseq]
@{@t{scheme.lseq}@}
Append one or more @var{lseq}s lazily.  This is the same as @code{lappend}
in Gauche.
@end defun

@defun lseq-zip lseq lseq2 @dots{}
[R7RS lseq]
@{@t{scheme.lseq}@}
Returns a lazy sequence in which the first element is a list of
first elements of @code{lseq}s, and so on.
@end defun

@defun lseq-map proc lseq lseq2 @dots{}
[R7RS lseq]
@{@t{scheme.lseq}@}
Lazy map.  The same as Gauche's @code{lmap}.  Returns a lazy sequence.
@end defun

@defun lseq-for-each proc lseq lseq2 @dots{}
[R7RS lseq]
@{@t{scheme.lseq}@}
This one consumes all the input lseqs, applying @var{proc} on
each corresponding elements of the input sequences for the side
effects.  In Gauche, it is the same as @code{for-each}, for
Gauche doesn't distinguish lseqs and ordinary lists.
@end defun

@defun lseq-filter pred lseq
@defunx lseq-remove pred lseq
[R7RS lseq]
@{@t{scheme.lseq}@}
Returns an lseq that contains elements from the input
@var{lseq} that satisfy or don't satisfy @var{pred}, respectively.
@code{Lseq-filter} is the same as Gauche's @code{lfilter}.
@end defun

@defun lseq-take-while pred lseq
@defunx lseq-drop-while pred lseq
[R7RS lseq]
@{@t{scheme.lseq}@}
These are the same as Gauche's @code{ltake-while} and @code{drop-while}
(the latter doesn't have @code{l}-prefix, since it just drops items
from the head of the input sequence, regardless of whether it is
an ordinary list or an lseq.
@end defun

@defun lseq-find pred lseq
@defunx lseq-find-tail pred lseq
@defunx lseq-any pred lseq
@defunx lseq-every pred lseq
@defunx lseq-index pred lseq
@defunx lseq-member pred lseq :optional eq
@defunx lseq-memq pred lseq
@defunx lseq-memv pred lseq
[R7RS lseq]
@{@t{scheme.lseq}@}
In Gauche, these are the same as the corresponding list functions,
@code{find}, @code{find-tail}, @code{any}, @code{every},
@code{list-index}, @code{member}, @code{memq} and @code{memv}, respectively,
for all of those functions won't look at input more than necessary
so @var{lseq}s work just as well as ordinary lists.
@end defun

@node R7RS stream, R7RS boxes, R7RS lazy sequences, R7RS large
@subsection @code{scheme.stream} - R7RS stream
@c NODE R7RSストリーム, @code{scheme.stream} - R7RSストリーム

@deftp {Module} scheme.stream
@mdindex scheme.stream
This module provides utilities for lazily evaluated streams.
It is more heavyweight than lazy sequences (@pxref{Lazy sequences}),
but it strictly implements ``as lazy as possible'' semantics---elements
are never evaluated until it is actually accessed.

The following procedures are provided in Gauche's @code{util.stream} module;
@pxref{Stream library} for their description:

@example
stream-null         stream-cons       stream?          stream-null?
stream-pair?        stream-car        stream-cdr       stream-lambda

define-stream       list->stream      port->stream
stream->list        stream-append     stream-concat    stream-constant
stream-drop-while   stream-filter     stream-fold
stream-for-each     stream-from       stream-iterate   stream-length
stream-let          stream-map        stream-match     stream-of
stream-range        stream-ref        stream-reverse   stream-scan
stream-take-while   stream-unfold     stream-unfolds   stream-zip
@end example

The following macro and procedures have different interface from
Gauche's @code{util.stream} module:

@example
stream              stream-take      stream-drop
@end example
@end deftp

@defmac stream expr @dots{}
[R7RS stream]
@{@t{scheme.stream}@}
Returns a new stream whose elements are the result of @var{expr} @dots{}.
Arguments won't be evaluated until required.

This differs from srfi-40 and @code{util.stream}'s @code{stream},
which is a procedure so arguments are evaluated
(@pxref{Stream constructors}, for the details).
@end defmac


@defun stream-take n stream
@defunx stream-drop n stream
[R7RS stream]
@{@t{scheme.stream}@}
Returns a stream that contains first @var{n} elements from @var{stream},
or elements without first @var{n} elements from it, respectively.
If @var{stream} has less than @var{n} elements, @code{stream-take}
returns a copy of the entire @var{stream}, while @code{stream-drop}
returns a null stream.

Note that the argument order doesn't follow the Scheme tradition,
which takes the main object (@var{stream} in this case) first, then
the count.  Procedures with the same name is provided in @code{util.stream}
with the different argument order.
@end defun

@node R7RS boxes, R7RS list queues, R7RS stream, R7RS large
@subsection @code{scheme.box} - R7RS boxes
@c NODE R7RSボックス, @code{scheme.box} - R7RSボックス

@deftp {Module} scheme.box
@mdindex scheme.box
Gauche supports boxes built-in (@pxref{Boxes}), so this module
is merely a facade that exports the following identifiers:

@example
box    box?    unbox    set-box!
@end example
@end deftp

@node R7RS list queues, R7RS ephemerons, R7RS boxes, R7RS large
@subsection @code{scheme.list-queue} - R7RS list queues
@c NODE R7RSリストキュー, @code{scheme.list-queue} - R7RSリストキュー

@deftp {Module} scheme.list-queue
@mdindex scheme.list-queue
A library of simple queue based on lists.
Gauche has a queue support in @code{data.queue} module, which also
includes MT-safe queue (@pxref{Queue}).  This library is implemented
on top of @code{data.queue}'s @code{<queue>} object and mainly provided
for portable code.

The list-queue is just an instance of @code{<queue>}, so you can
pass a queue created by @code{make-queue} to @code{scheme.list-queue}
API and
a list-queue created by @code{make-list-queue} to Gauche's queue API.

Note: Some API of this library requires to return internal pairs the queue
uses, for the efficiency.
The pair's car/cdr will be mutated by subsequent queue operation,
and also any mutation done on the pair would cause inconsistency
in the original queue.
@end deftp

@defun make-list-queue lis :optional last
[R7RS list-queue]
@{@t{scheme.list-queue}@}
Creates and returns a list-queue whose initial content is @var{lis}.
In Gauche, a list queue is just an instance of @code{<queue>} (@pxref{Queue}).

The cells in @var{lis} are owned by the queue; the caller shouldn't mutate
it afterwards, nor assume its structure remains the same.

The optional @var{last} argument must be the last pair of @var{lis}.
If it is passed, @code{make-list-queue} will skip scanning @var{lis}
and just hold a reference to @var{last} as the tail of the queue.
@end defun

@defun list-queue elt @dots{}
[R7RS list-queue]
@{@t{scheme.list-queue}@}
Creates and returns a list-queue whose initial content is @var{elt} @dots{}.
In Gauche, a list queue is just an instance of @code{<queue>} (@pxref{Queue}).
@end defun

@defun list-queue-copy queue
[R7RS list-queue]
@{@t{scheme.list-queue}@}
Returns a copy of a list-queue @var{queue}.
@end defun

@defun list-queue-unfold p f g seed :optional queue
[R7RS list-queue]
@{@t{scheme.list-queue}@}
Prepend @var{queue} with the items generated by
@code{(unfold p f g seed)} and returns the updated queue.
@xref{R7RS lists}, for @code{unfold}.
If @var{queue} is omitted, a fresh queue is created.

@example
(list-queue-unfold (pa$ = 5) ; p
                   (pa$ * 2) ; f
                   (pa$ + 1) ; g
                   0         ; seed
                   (list-queue 'x 'y 'z))
 @result{} @r{a queue containing (0 2 4 6 8 x y z)}
@end example
@end defun

@defun list-queue-unfold-right p f g seed :optional queue
[R7RS list-queue]
@{@t{scheme.list-queue}@}
Append @var{queue} with the items generated by
@code{(unfold-right p f g seed)} and returns the updated queue.
@xref{R7RS lists}, for @code{unfold-right}.
If @var{queue} is omitted, a fresh queue is created.

@example
(list-queue-unfold-right (pa$ = 5) ; p
                         (pa$ * 2) ; f
                         (pa$ + 1) ; g
                         0         ; seed
                         (list-queue 'x 'y 'z))
 @result{} @r{a queue containing (x y z 8 6 4 2 0)}
@end example
@end defun

@defun list-queue? obj
[R7RS list-queue]
@{@t{scheme.list-queue}@}
Returns true iff @var{queue} is a list-queue.
In Gauche, it is the same as @code{queue?} in the @code{data.queue} module.
@end defun

@defun list-queue-empty? queue
[R7RS list-queue]
@{@t{scheme.list-queue}@}
Returns true iff @var{queue} is empty.
Same as @code{queue-empty?} of @code{data.queue}.
@end defun

@defun list-queue-front queue
[R7RS list-queue]
@{@t{scheme.list-queue}@}
Returns the front element of the @var{queue}.
An error is thrown if @var{queue} is empty.
Same as @code{queue-front} of @code{data.queue}.
@end defun

@defun list-queue-back queue
[R7RS list-queue]
@{@t{scheme.list-queue}@}
Returns the rear element of the @var{queue}.
An error is thrown if @var{queue} is empty.
Same as @code{queue-rear} of @code{data.queue}.
@end defun

@defun list-queue-list queue
[R7RS list-queue]
@{@t{scheme.list-queue}@}
Returns the internal list of @var{queue}.
Note that the list would be modified by subsequent operations of @var{queue},
and any modification on the list would make @var{queue} inconsistent.
The primary purpose of this procedure is to implement other
queue-related operations with small overhead.

If you merely need a cheap access the content of the queue,
consider @code{list-queue-remove-all!}.
That returns the list of elements of the queue without copying, and
simultaneously reset the queue to empty, so it's safe.
@end defun

@defun list-queue-fist-last queue
[R7RS list-queue]
@{@t{scheme.list-queue}@}
Returns two values, the first and last pair of @var{queue}.
If the queue is empty, two empty lists are returned.

This also returns the internal pair of the queue, so
any subsequent operations of @var{queue} would change the contents
of the pairs, and any modification on the pairs would make @var{queue}
inconsistent.
The purpose of this procedure is to implement other
queue-related operations with small overhead.  This procedure should
not be used in general.
@end defun

@defun list-queue-add-front! queue elt
[R7RS list-queue]
@{@t{scheme.list-queue}@}
Add @var{elt} to the front of @var{queue}.
Same as @code{(queue-push! queue elt)} of @code{data.queue}.
@end defun

@defun list-queue-add-back! queue elt
[R7RS list-queue]
@{@t{scheme.list-queue}@}
Add @var{elt} to the back of @var{queue}.
Same as @code{(enqueue! queue elt)} of @code{data.queue}.
@end defun

@defun list-queue-remove-front! queue
[R7RS list-queue]
@{@t{scheme.list-queue}@}
Remove an element from the front of @var{queue} and returns
the removed element.  Throws an error if @var{queue} is empty.
Same as @code{dequeue!} of @code{data.queue}.
@end defun

@defun list-queue-remove-back! queue
[R7RS list-queue]
@{@t{scheme.list-queue}@}
Remove an element from the back of @var{queue} and returns the
removed element.  Throws an error if @var{queue} is empty.
This isn't guaranteed to be efficient; it is O(n)
operation where n is the number of elements.
In general, if you need this operation frequently, you should
consider double-ended queue.  (@xref{Immutable deques}, and also
@pxref{Ring buffer}.)
@end defun

@defun list-queue-remove-all! queue
[R7RS list-queue]
@{@t{scheme.list-queue}@}
Remove all the elements from @var{queue} and returns them as a list.
The list isn't copied---this is O(1) operation.  This should be preferred
over @code{list-queue-list}, for it's safer.
In Gauche, this is the same as @code{dequeue-all!} in @code{data.queue}.
@end defun

@defun list-queue-set-list! queue lis :optional last
[R7RS list-queue]
@{@t{scheme.list-queue}@}
Modify @var{queue} to have the elements in @var{lis} as its element.
The original content of @var{queue} is discarded.  If the optional
@var{last} argument is provided, it must be the last pair of @var{lis},
and the procedure uses that instead of scanning @var{lis}, to achieve
O(1) operation.

After calling this, @var{lis} is owned by @var{queue} and it may
be mutated.  The caller shouldn't change, or rely on @var{lis} afterwards.
@end defun

@defun list-queue-append queue @dots{}
[R7RS list-queue]
@{@t{scheme.list-queue}@}
Returns a fresh list-queue whose contents are concatenation of
@var{queue}s.  The contents of arguments are intact.
This is O(n) operation where n is the total number of elements.
@end defun

@defun list-queue-append! queue @dots{}
[R7RS list-queue]
@{@t{scheme.list-queue}@}
Returns a list-queue whose contents are concatenation of
@var{queue}s.  During the operation, the contents of @var{queue}s
may be mutated, and they shouldn't be used any longer.  (In Gauche,
to avoid accident, we actually empty all the @var{queue}s.)
It is also noted that the result doesn't need to be @code{eq?} to
any of the arguments.
This is O(m) operation where m is the total number of queues
(as opposed to the number of elements).
@end defun

@defun list-queue-concatenate queues
[R7RS list-queue]
@{@t{scheme.list-queue}@}
@code{(apply list-queue-append queues)}.
@end defun

@defun list-queue-map proc queue
[R7RS list-queue]
@{@t{scheme.list-queue}@}
Returns a fresh list-queue whose elements are obtained by
applying @var{proc} on every elements in @var{queue}.
@end defun

@defun list-queue-map! proc queue
[R7RS list-queue]
@{@t{scheme.list-queue}@}
Replaces every element in @var{queue} by the result of
application of @var{proc} on the element.
@end defun

@defun list-queue-for-each proc queue
[R7RS list-queue]
@{@t{scheme.list-queue}@}
Applies @var{proc} on every element of @var{queue}.
The results are discarded.
@end defun

@node R7RS ephemerons, R7RS comparators, R7RS list queues, R7RS large
@subsection @code{scheme.ephemeron} - R7RS ephemeron
@c NODE R7RS Ephemeron, @code{scheme.ephemeron} - R7RS Ephemeron

@deftp {Module} scheme.ephemeron
@mdindex scheme.ephemeron
This module defined @emph{ephemerons}, a weak reference
structure to hold key-value association.  This is originally
defined as srfi-142.

Gauche supports weak pointers in the form of weak vectors
(@pxref{Weak vectors}), but it is known that a simple weak
pointer (a single pointer that doesn't prevent the pointed
object from being collected) isn't enough to implement
weak key-value association such as mappings.

An ephemeron is a record that points to a key and an associated
datum, with the following characteristics:

@enumerate
@item
Reference to the key is weak; it doesn't prevent the key from
being collected if there's no strong reference to the key,
@emph{except from the datum associated by the ephemeron}.

@item
Reference to the datum is also a kind of weak; it doesn't prevent the datum
from being collected if there's no strong reference to the datum,
@emph{and there's no strong reference to the associated key}.
Note that the datum is retained as long as the key is retained,
even there's no strong reference to the datum itself.
@end enumerate

Implementing the proper ephemeron requires deep integration with
the GC.  At this moment, Gauche's ephemeron is implemented separately
from GC, and has the following limitations:

@itemize @bullet
@item
If the datum has a strong reference to the associated key, the
key won't be collected even if there's no other strong reference to it.

@item
After the key is collected and there's no strong reference to
the datum, @code{ephemeron-broken?} needs to be called in order
to trigger the collection of the datum.
@end itemize

Since the timing of collection isn't specified in the spec,
Gauche's implementation still conforms srfi-142, but in practice
you need to be aware of these limitations.  Eventually we want
to support full ephemeron integrated with GC.

Once the key and/or the datum is collected (we call such ephemeron
``broken''), referencing them returns a bogus value.  The proper
way to use an ephemeron @var{e} is the following pattern:

@example
(let ([k (ephemeron-key e)]
      [d (ephemeron-datum e)])
  (if (ephemeron-broken? e)
    (... k and d are invalid ...)
    (... k and d are valid ...)))
@end example

You should take values, then check if the ephemeron isn't broken yet.
If you call @code{ephemeron-broken?} first, there's a chance
that the ephemeron is broken between the check and the time
you reference it.
@end deftp

@defun make-ephemeron key datum
[R7RS ephemeron]
@{@t{scheme.ephemeron}@}
Create a new ephemeron associating the @var{key} to the @var{datum}.
@end defun

@defun ephemeron? obj
[R7RS ephemeron]
@{@t{scheme.ephemeron}@}
Returns @code{#t} iff @var{obj} is an ephemeron.
@end defun


@defun ephemeron-key ephemeron
@defunx ephemeron-datum ephemeron
[R7RS ephemeron]
@{@t{scheme.ephemeron}@}
Returns the key and the datum of @var{ephemeron}, respectively.
If the ephemeron is already broken, there's no guarantee
on what is returned. Thus you should always call @code{ephemeron-broken?}
@emph{after} calling these procedure to ensure the values are
meaningful.  See the @code{scheme.ephemeron} entry for the details.
@end defun

@defun ephemeron-broken? ephemeron
[R7RS ephemeron]
@{@t{scheme.ephemeron}@}
Returns @code{#t} iff @var{ephemeron} has been broken, that is,
its key and/or datum may be collected and cannot be reliably retrieved.
See the @code{scheme.ephemeron} entry for the details.
@end defun

@defun reference-barrier key
[R7RS ephemeron]
@{@t{scheme.ephemeron}@}
This procedure does nothing by itself,
but guarantees @var{key} is strongly reference
until returning from this procedure.
@end defun


@node R7RS comparators, R7RS regular expressions, R7RS ephemerons, R7RS large
@subsection @code{scheme.comparator} - R7RS comparators
@c NODE R7RS比較器, @code{scheme.comparator} - R7RS比較器

@deftp {Module} scheme.comparator
@mdindex scheme.comparator
This module defines comparators and related procedures.
Originally called @code{srfi-128}.

Gauche supports comparators fully compatible to
@code{scheme.comparator} built-in.
@xref{Basic comparators}, for the following procedures
defined in this module.

@example
comparator? comparator-ordered? comparator-hashable?
make-comparator make-pair-comparator
make-list-comparator make-vector-comparator
make-eq-comparator make-eqv-comparator make-equal-comparator

boolean-hash char-hash char-ci-hash string-hash
string-ci-hash symbol-hash number-hash
hash-bound hash-salt

make-default-comparator default-hash
comparator-register-default!

comparator-type-test-predicate comparator-equality-predicate
comparator-ordering-predicate comparator-hash-function
comparator-test-type comparator-check-type comparator-hash

=? <? >? <=? >=? comparator-if<=>
@end example
@end deftp

@c ----------------------------------------------------------------------
@node R7RS regular expressions, R7RS mappings, R7RS comparators, R7RS large
@subsection @code{scheme.regex} - R7RS regular expressions
@c NODE R7RS正規表現, @code{scheme.regex} - R7RS正規表現

@deftp {Module} scheme.regex
@mdindex scheme.regex
This module provides operations on Scheme Regular Expressions (SRE).
Originally defined as srfi-115.

@end deftp

@subheading Scheme regular expression syntax

@subsubheading Syntax summary

SRE is just an S-expression with the structure summarized below.

With the exception of @code{or}, any syntax that takes multiple
@code{<sre>} processes them in a sequence. In other words @code{(foo
<sre> ...)} is equivalent to @code{(foo (seq <sre> ...))}.

Note: SRE uses the symbol @code{|} for alteration, but the vertical bar
character is used for symbol escape in Gauche (and R7RS), so you have to
write such symbol as @code{|\||}.  We recommend to use @code{or} instead.

@smallexample
    <sre> ::=
     | <string>                    ; A literal string match.
     | <cset-sre>                  ; A character set match.
     | (* <sre> ...)               ; 0 or more matches.
     | (zero-or-more <sre> ...)
     | (+ <sre> ...)               ; 1 or more matches.
     | (one-or-more <sre> ...)
     | (? <sre> ...)               ; 0 or 1 matches.
     | (optional <sre> ...)
     | (= <n> <sre> ...)           ; <n> matches.
     | (exactly <n> <sre> ...)
     | (>= <n> <sre> ...)          ; <n> or more matches.
     | (at-least <n> <sre> ...)
     | (** <n> <m> <sre> ...)      ; <n> to <m> matches.
     | (repeated <n> <m> <sre> ...)

     | (|\||  <sre> ...)           ; Alternation.
     | (or <sre> ...)

     | (:   <sre> ...)             ; Sequence.
     | (seq <sre> ...)
     | ($ <sre> ...)               ; Numbered submatch.
     | (submatch <sre> ...)
     | (-> <name> <sre> ...)               ;  Named submatch.  <name> is
     | (submatch-named <name> <sre> ...)   ;  a symbol.

     | (w/case   <sre> ...)        ; Introduce a case-sensitive context.
     | (w/nocase <sre> ...)        ; Introduce a case-insensitive context.

     | (w/unicode   <sre> ...)     ; Introduce a unicode context.
     | (w/ascii <sre> ...)         ; Introduce an ascii context.

     | (w/nocapture <sre> ...)     ; Ignore all enclosed submatches.

     | bos                         ; Beginning of string.
     | eos                         ; End of string.

     | bol                         ; Beginning of line.
     | eol                         ; End of line.

     | bow                         ; Beginning of word.
     | eow                         ; End of word.
     | nwb                         ; A non-word boundary.
     | (word <sre> ...)            ; An SRE wrapped in word boundaries.
     | (word+ <cset-sre> ...)      ; A single word restricted to a cset.
     | word                        ; A single word.

     | (?? <sre> ...)              ; A non-greedy pattern, 0 or 1 match.
     | (non-greedy-optional <sre> ...)
     | (*? <sre> ...)              ; Non-greedy 0 or more matches.
     | (non-greedy-zero-or-more <sre> ...)
     | (**? <m> <n> <sre> ...)     ; Non-greedy <m> to <n> matches.
     | (non-greedy-repeated <sre> ...)
     | (atomic <sre> ...)          ; Atomic clustering.

     | (look-ahead <sre> ...)      ; Zero-width look-ahead assertion.
     | (look-behind <sre> ...)     ; Zero-width look-behind assertion.
     | (neg-look-ahead <sre> ...)  ; Zero-width negative look-ahead assertion.
     | (neg-look-behind <sre> ...) ; Zero-width negative look-behind assertion.

     | (backref <n-or-name>)       ; Match a previous submatch.
     @c These are extensions
     @c | (if-look-ahead <test-sre> <then-sre> [<else-sre>])      ; Conditional pattern
     @c | (if-neg-look-ahead <test-sre> <then-sre> [<else-sre>])  ; Conditional pattern
     @c | (if-look-behind <test-sre> <then-sre> [<else-sre>])     ; Conditional pattern
     @c | (if-neg-look-behind <test-sre> <then-sre> [<else-sre>]) ; Conditional pattern
     @c | (if-backref <backref> <then-sre> [<else-sre>])          ; Conditional pattern
@end smallexample

The grammar for @code{cset-sre} is as follows.

@smallexample
    <cset-sre> ::=
     | <char>                      ; literal char
     | "<char>"                    ; string of one char
     | <char-set>                  ; embedded SRFI 14 char set
     | (<string>)                  ; literal char set
     | (char-set <string>)
     | (/ <range-spec> ...)        ; ranges
     | (char-range <range-spec> ...)
     | (or <cset-sre> ...)         ; union
     | (|\|| <cset-sre> ...)
     | (and <cset-sre> ...)        ; intersection
     | (& <cset-sre> ...)
     | (- <cset-sre> ...)          ; difference
     | (- <difference> ...)
     | (~ <cset-sre> ...)          ; complement of union
     | (complement <cset-sre> ...)
     | (w/case <cset-sre>)         ; case and unicode toggling
     | (w/nocase <cset-sre>)
     | (w/ascii <cset-sre>)
     | (w/unicode <cset-sre>)
     | any | nonl | ascii | lower-case | lower
     | upper-case | upper | title-case | title
     | alphabetic | alpha | alphanumeric | alphanum | alnum
     | numeric | num | punctuation | punct | symbol
     | graphic | graph | whitespace | white | space
     | printing | print | control | cntrl | hex-digit | xdigit

    <range-spec> ::= <string> | <char>
@end smallexample

@subsubheading Basic patterns

@table @code
@item <string>

A literal string.

@example
(regexp-search "needle" "hayneedlehay")
 @result{} #<regexp-match>
(regexp-search "needle" "haynEEdlehay")
 @result{} #f
@end example

@item (seq <sre> ...)
@itemx (: <sre> ...)

A sequence of patterns that should be matched in the same order. This
is the same as RE syntax @code{(?:@i{re}@dots{})}

@example
(regexp-search '(: "one" space "two" space "three") "one two three")
 @result{} #<regexp-match>
@end example

@item (or <sre> ...)
@itemx (|\|| <sre> ...)

Matches one of the given patterns. This is the same as
RE syntax @code{@i{pattern1}|@i{pattern2}|@dots{}}

@example
(regexp-search '(or "eeney" "meeney" "miney") "meeney")
 @result{} #<regexp-match>
(regexp-search '(or "eeney" "meeney" "miney") "moe")
 @result{} #f
@end example

@item (w/nocase <sre> ...)

Changes to match the given patterns case-insensitively. Sub-patterns
can still be made sensitive with @code{w/case}. This is the same as
RE syntax @code{(?i:@i{re}@dots{})}

@example
(regexp-search "needle" "haynEEdlehay") @result{} #f
(regexp-search '(w/nocase "needle") "haynEEdlehay")
  @result{}  #<regexp-match>

(regexp-search '(~ ("Aab")) "B") @result{} #<regexp-match>
(regexp-search '(~ ("Aab")) "b") @result{} #f
(regexp-search '(w/nocase (~ ("Aab"))) "B") @result{} #f
(regexp-search '(w/nocase (~ ("Aab"))) "b") @result{} #f
(regexp-search '(~ (w/nocase ("Aab"))) "B") @result{} #f
(regexp-search '(~ (w/nocase ("Aab"))) "b") @result{} #f
@end example

@item (w/case <sre> ...)

Changes to match the given patterns case-sensitively. Sub-patterns can
still be made case-insensitive. This is the same as RE syntax
@code{(?-i:@i{re}@dots{})}. This is the default.

@example
(regexp-search '(w/nocase "SMALL" (w/case "BIG")) "smallBIGsmall")
 @result{} #<regexp-match>
(regexp-search '(w/nocase (~ (w/case ("Aab")))) "b") @result{} #f
@end example

@item (w/ascii <sre> ...)

Limits the character sets and other predefined patterns to ASCII. This
affects patterns or character sets like @code{any}, @code{alpha},
@code{(word)}@dots{}

@example
(regexp-search '(w/ascii bos (* alpha) eos) "English")
 @result{} #<regexp-match>
(regexp-search '(w/ascii bos (* alpha) eos) "Ελληνική") @result{} #f
@end example

@item (w/unicode <sre> ...)

Changes the character sets and other predefined patterns back to
Unicode if @code{w/ascii} has been used in the outer scope. This is
the default.

@example
(regexp-search '(w/unicode bos (* alpha) eos) "English")
 @result{} #<regexp-match>
(regexp-search '(w/unicode bos (* alpha) eos) "Ελληνική")
 @result{} #<regexp-match>
@end example

@item (w/nocapture <sre> ...)

Disables capturing for all @code{submatch} and @code{submatch-named}
inside.

@example
(let ((number '($ (+ digit))))
  (cdr
   (regexp-match->list
    (regexp-search `(: ,number "-" ,number "-" ,number)
                   "555-867-5309")))  ; @result{} '("555" "867" "5309")
  (cdr
   (regexp-match->list
    (regexp-search `(: ,number "-" (w/nocapture ,number) "-" ,number)
                   "555-867-5309"))))   @result{} '("555" "5309")
@end example
@end table

@subsubheading Repeating patterns
@table @code
@item (optional <sre> ...)
@itemx (? <sre> ...)

Matches the pattern(s) one or zero times.

@example
(regexp-search '(: "match" (? "es") "!") "matches!")
 @result{} #<regexp-match>
(regexp-search '(: "match" (? "es") "!") "match!")
 @result{} #<regexp-match>
(regexp-search '(: "match" (? "es") "!") "matche!")
 @result{} #f
@end example

@item (zero-or-more <sre> ...)
@itemx (* <sre> ...)

Matches the pattern(s) zero or more times.

@example
(regexp-search '(: "<" (* (~ #\>)) ">") "<html>")
 @result{} #<regexp-match>
(regexp-search '(: "<" (* (~ #\>)) ">") "<>")
 @result{} #<regexp-match>
(regexp-search '(: "<" (* (~ #\>)) ">") "<html")
 @result{} #f
@end example

@item (one-or-more <sre> ...)
@itemx (+ <sre> ...)

Matches the pattern(s) at least once.

@example
(regexp-search '(: "<" (+ (~ #\>)) ">") "<html>")
 @result{} #<regexp-match>
(regexp-search '(: "<" (+ (~ #\>)) ">") "<a>")
 @result{} #<regexp-match>
(regexp-search '(: "<" (+ (~ #\>)) ">") "<>")
 @result{} #f
@end example

@item (at-least n <sre> ...)
@itemx (>= n <sre> ...)

Matches the pattern(s) at least @code{n} times.

@example
(regexp-search '(: "<" (>= 3 (~ #\>)) ">") "<table>")
 @result{} #<regexp-match>
(regexp-search '(: "<" (>= 3 (~ #\>)) ">") "<pre>")
 @result{} #<regexp-match>
(regexp-search '(: "<" (>= 3 (~ #\>)) ">") "<tr>")
 @result{} #f
@end example

@item (exactly n <sre> ...)
@itemx (= n <sre> ...)

Matches the pattern(s) exactly @code{n} times.

@example
(regexp-search '(: "<" (= 4 (~ #\>)) ">") "<html>")
 @result{} #<regexp-match>
(regexp-search '(: "<" (= 4 (~ #\>)) ">") "<table>")
 @result{} #f
@end example

@item (repeated from to <sre> ...)
@itemx (** from to <sre> ...)

Matches the pattern(s) at least @code{from} times and up to @code{to}
times.

@example
(regexp-search '(: (= 3 (** 1 3 numeric) ".") (** 1 3 numeric))
               "192.168.1.10")
 @result{} #<regexp-match>
(regexp-search '(: (= 3 (** 1 3 numeric) ".") (** 1 3 numeric))
               "192.0168.1.10")
 @result{} #f
@end example
@end table

@subsubheading Submatch Patterns
@table @code
@item (submatch <sre> ...)
@itemx ($ <sre> ...)

Captures the matched string. Each capture is numbered increasing from
one (capture zero is the entire matched string). For nested captures,
the numbering scheme is depth-first walk.

@item (submatch-named <name> <sre> ...)
@itemx (-> <name> <sre> ...)

Captures the matched string and assigns a name to it in addition to a
number. This is the equivalent of @code{(?<@i{name}>@i{re}@dots{})}

@item (backref <n-or-name>)

Matches a previously matched submatch. This is the same as
RE syntax @code{\@i{n}} or @code{\k<@i{name}>}.

@c @item (if-backref <n> <then-sre> [<else-sre>])

@c Conditional matching. If the @code{<n>}-th capturing group has a
@c match, @code{<then-sre>} pattern is tried; otherwise @code{<else-sre>}
@c pattern is tried when provided.

@c This is Gauche extension and is the same as RE syntax
@c @code{(?(@i{n})@i{then})} or @code{(?(@i{n})@i{then}|@i{else})}.

@end table

@subsubheading Character Sets

@table @code
@item <char>

A character set contains a single character.

@example
(regexp-matches '(* #\-) "---") @result{} #<regexp-match>
(regexp-matches '(* #\-) "-_-") @result{} #f
@end example

@item "<char>"

A character set contains a single character. This is technically
ambiguous with SRE matching a literal string. However the end result
of both syntaxes is the same.

@item <char-set>

A SRFI-14 character set.

Note that while currently there is no portable written representation
of SRFI 14 character sets, you can use Gauche reader syntax
@code{#[char-set-spec]}, @pxref{Character sets}.

@example
(regexp-partition `(+ ,char-set:vowels) "vowels")
 @result{} ("v" "o" "w" "e" "ls")
@end example

@item (char-set <string>)
@itemx (<string>)

A character set contains the characters in the given string. This is
the same as @code{`(char-set ,(string->char-set <string>))}.

@example
(regexp-matches '(* ("aeiou")) "oui") @result{} #<regexp-match>
(regexp-matches '(* ("aeiou")) "ouais") @result{} #f
(regexp-matches '(* ("e\x0301")) "e\x0301") @result{} #<regexp-match>
(regexp-matches '("e\x0301") "e\x0301") @result{} #f
(regexp-matches '("e\x0301") "e") @result{} #<regexp-match>
(regexp-matches '("e\x0301") "\x0301") @result{} #<regexp-match>
(regexp-matches '("e\x0301") "\x00E9") @result{} #f
@end example

@item (char-range <range-spec> ...)
@itemx (/ <range-spec> ...)

A character set contains the characters within
@code{<range-set>}. This is the same as RE syntax @code{[]}.

@example
(regexp-matches '(* (/ "AZ09")) "R2D2") @result{} #<regexp-match>
(regexp-matches '(* (/ "AZ09")) "C-3PO") @result{} #f
@end example

@item (or <cset-sre> ...)
@itemx (|\|| <cset-sre> ...)

A shorthand for @code{`(char-set ,(char-set-union <cset-sre>...))}.

@item (complement <cset-sre> ...)
@itemx (~ <cset-sre> ...)

A shorthand for @code{`(char-set ,(char-set-complement <cset-sre>...))}.

@item (difference <cset-sre> ...)
@itemx (- <cset-sre> ...)

A shorthand for @code{`(char-set ,(char-set-difference <cset-sre>...))}.

@example
(regexp-matches '(* (- (/ "az") ("aeiou"))) "xyzzy")
 @result{} #<regexp-match>
(regexp-matches '(* (- (/ "az") ("aeiou"))) "vowels")
 @result{} #f
@end example

@item (and <cset-sre> ...)
@itemx (& <cset-sre> ...)

A shorthand for @code{`(char-set ,(char-set-intersection <cset-sre>...))}.

@example
(regexp-matches '(* (& (/ "az") (~ ("aeiou")))) "xyzzy")
 @result{} #<regexp-match>
(regexp-matches '(* (& (/ "az") (~ ("aeiou")))) "vowels")
 @result{} #f
@end example

@item (w/case <cset-sre>)
@itemx (w/nocase <cset-sre>)
@itemx (w/ascii <cset-sre>)
@itemx (w/unicode <cset-sre>)

This is similar to the SRE equivalent, listed to indicate that they
can also be applied on character sets.

@end table

@subsubheading Named Character Sets

Note that if @code{w/ascii} is in effect, these character sets will
return the ASCII subset. Otherwise they return full Unicode ones.

@table @code
@item any

Matches any character. This is the @code{.} in regular expression.

@item nonl

Matches any character other than @code{#\return} or @code{#\newline}.

@item ascii

A shorthand for @code{`(char-set ,char-set:ascii)}.

@item lower-case
@itemx lower

A shorthand for @code{`(char-set ,char-set:lower-case)}.

@item upper-case
@itemx upper

A shorthand for @code{`(char-set ,char-set:upper-case)}.

@item title-case
@itemx title

A shorthand for @code{`(char-set ,char-set:title-case)}.

@item alphabetic
@itemx alpha

A shorthand for @code{`(char-set ,char-set:letter)}.

@item numeric
@itemx num

A shorthand for @code{`(char-set ,char-set:digit)}.

@item alphanumeric
@itemx alphanum
@itemx alnum

A shorthand for @code{`(char-set ,char-set:letter+digit)}.

@item punctuation
@itemx punct

A shorthand for @code{`(char-set ,char-set:punctuation)}.

@item symbol

A shorthand for @code{`(char-set ,char-set:symbol)}.

@item graphic
@itemx graph

A shorthand for @code{`(char-set ,char-set:graphic)}.

@example
(or alphanumeric punctuation symbol)
@end example


@item whitespace
@itemx white
@itemx space

A shorthand for @code{`(char-set ,char-set:whitespace)}.

@item printing
@itemx print

A shorthand for @code{`(char-set ,char-set:printing)}.

@item control
@itemx cntrl

A character set contains ASCII characters with from 0 to 31.

@item hex-digit
@itemx xdigit

A shorthand for @code{`(char-set ,char-set:hex-digit)}.

@end table

@subsubheading Boundary Assertions

@table @code
@item bos
@itemx eos

Matches the beginning of the string. If start/end parameters are
specified, matches the start or end of the substring as specified.

@item bol
@itemx eol

Matches the beginning or end of a line (or the string). For single
line matching, this is the same as @code{bos} and @code{eos}. A line
is interpreted the same way with @code{read-line}.

@item bow
@itemx eow

Matches the beginning or the end of a word.

@example
  (regexp-search '(: bow "foo") "foo") @result{} #<regexp-match>
  (regexp-search '(: bow "foo") "<foo>>") @result{} #<regexp-match>
  (regexp-search '(: bow "foo") "snafoo") @result{} #f
  (regexp-search '(: "foo" eow) "foo") @result{} #<regexp-match>
  (regexp-search '(: "foo" eow) "foo!") @result{} #<regexp-match>
  (regexp-search '(: "foo" eow) "foobar") @result{} #f
@end example


@item nwb

A shorthand for @code{(neg-look-ahead (or bow eow))}.

@item (word <sre> ...)

Matches the word boundary around the given SRE:

@example
(: bow <sre> ... eow)
@end example


@item (word+ <cset-sre> ...)

Matches a single word composed of characters of the given characters
sets:

@example
(word (+ (and (or alphanumeric "_") (or cset-sre ...))))
@end example


@item word

A shorthand for @code{(word+ any)}.

@end table

@subsubheading Non-Greedy Patterns

@table @code

@item (non-greedy-optional <sre> ...)
@itemx (?? <sre> ...)

The non-greedy equivalent of @code{(optional <sre>...)}. This is the
same as RE syntax @code{@i{re}??}

@item (non-greedy-zero-or-more< <sre> ...)
@itemx (*? <sre> ...)

The non-greedy equivalent of @code{(zero-or-more <sre>...)}. This is
the same as RE syntax @code{@i{re}*?}

@item (non-greedy-repeated <m> <n> <sre> ...)
@itemx (**? <m> <n> <sre> ...)

The non-greedy equivalent of @code{(repeated <sre>...)}. This is the
same as RE syntax @code{@i{re}@{@i{n},@i{m}@}?}

@item (atomic <sre> ...)

Atomic clustering. Once @code{<sre> ...} matches, the match is fixed;
even if the following pattern fails, the engine won't backtrack to try
the alternative match in @code{<sre> ...}. This is Gauche extension
and is the same as RE syntax @code{(?>@i{pattern})}

@end table

@subsubheading Look Around Patterns

@table @code
@item (look-ahead <sre> ...)

Zero-width look-ahead assertion. Asserts the sequence matches from the
current position, without advancing the position. This is the same as
RE syntax @code{(?=@i{pattern})}

@example
(regexp-matches '(: "regular" (look-ahead " expression") " expression")
                "regular expression")
 @result{} #<regexp-match>
(regexp-matches '(: "regular" (look-ahead " ") "expression")
                "regular expression")
 @result{} #f
@end example


@item (look-behind <sre> ...)

Zero-width look-behind assertion. Asserts the sequence matches behind
the current position, without advancing the position. It is an error
if the sequence does not have a fixed length. This is the same as RE
syntax @code{(?<=@i{pattern})}

@item (neg-look-ahead <sre> ...)

Zero-width negative look-ahead assertion. This is the same as
RE syntax @code{(?!@i{pattern})}

@item (neg-look-behind <sre> ...)

Zero-width negative look-behind assertion. This is the same as RE
syntax @code{(?<!@i{pattern})}

@c @item (if-look-ahead <test-sre> <then-sre> [<else-sre>])
@c @itemx (if-neg-look-ahead <test-sre> <then-sre> [<else-sre>])
@c @itemx (if-look-behind <test-sre> <then-sre> [<else-sre>])
@c @itemx (if-neg-look-behind <test-sre> <then-sre> [<else-sre>])

@c Conditional matching. If @code{<test-sre>} counts true,
@c @code{<then-sre>} pattern is tried; otherwise @code{<else-sre>}
@c pattern is tried when provided.

@c This is Gauche extension and the same as @code{(?(?=..)...)},
@c @code{(?(?!..)...)}, @code{(?(?<=..)...)}, @code{(?(?<!..)...)}
@c respectively.

@end table

@subheading Using regular expressions

@defun regexp @var{re}
[R7RS regex]
@{@t{scheme.regex}@}
Compiles the given Scheme Regular Expression into a @code{<regexp>}
object. If @var{re} is already a regexp object, the object is
returned as-is.

@end defun

@defmac rx @var{sre} @dots{}
[R7RS regex]
@{@t{scheme.regex}@}
A macro shorthand for @code{(regexp `(: @var{sre} ...))}.
@end defmac

@defun regexp->sre @var{re}
[R7RS regex]
@{@t{scheme.regex}@}
Returns the SRE corresponding to the given given regexp object. Note
that if the regexp object is not created from an SRE, it may contain
features that cannot be expressed in SRE and cause an error.
@end defun

@defun char-set->sre @var{char-set}
[R7RS regex]
@{@t{scheme.regex}@}
Returns the SRE of the given character set. Currently this is not
optimized. If you convert @code{any} to SRE for example, you may get
an SRE listing every single character.
@end defun

@defun valid-sre? @var{obj}
[R7RS regex]
@{@t{scheme.regex}@}
Returns true iff @var{obj} can be safely passed to regexp.
@end defun

@defun regexp? @var{obj}
[R7RS regex]
@{@t{scheme.regex}@}
Returns true iff @var{obj} is a regexp.
@end defun

@defun regexp-matches @var{re} @var{str} [@var{start} [@var{end}]]
[R7RS regex]
@{@t{scheme.regex}@}
Returns an @code{<regexp-match>} object if re successfully matches the
entire string @var{str} or optionally from @var{start} (inclusive) to
@var{end} (exclusive), or @code{#f} is the match fails.

For convenience, @var{end} accepts @code{#f} and interprets it as the
end of the string.

The regexp-match object will contain information needed to extract any
submatches.
@end defun

@defun regexp-matches? @var{re} @var{str} [@var{start} [@var{end}]]
[R7RS regex]
@{@t{scheme.regex}@}
Similar to @code{regexp-matches} but returns @code{#t} instead of a
@code{<regexp-match>} object.
@end defun

@defun regexp-search @var{re} @var{str} [@var{start} [@var{end}]]
[R7RS regex]
@{@t{scheme.regex}@}
Similar to @code{regexp-matches} except that @var{re} only has to
match a substring in @var{str} instead.
@end defun


@defun regexp-fold @var{re} @var{kons} @var{knil} @var{str} [@var{finish} [@var{start} [@var{end}]]]
[R7RS regex]
@{@t{scheme.regex}@}
Calls the procedure @var{kons} for every match found in @var{str} with
following four arguments:

@itemize
@item
The position of the end of the last matched string.
@item
The @code{<regexp-match>} object.
@item
The argument @var{str}.
@item
The result of the last @var{kons} call or @var{knil} if this is the
first call.
@end itemize

If @var{finish} is given, it is called after all matches with the same
parameters as calling @var{kons} except that @code{#f} is passed
instead of @code{<regexp-match>} and the result is returned. Otherwise
the result of the last @var{kons} call is returned.

@example
   (regexp-fold 'word
                (lambda (i m str acc)
                  (let ((s (regexp-match-submatch m 0)))
                   (cond ((assoc s acc)
                          => (lambda (x) (set-cdr! x (+ 1 (cdr x))) acc))
                         (else `((,s . 1) ,@@acc)))))
                '()
                "to be or not to be")
   @result{} '(("not" . 1) ("or" . 1) ("be" . 2) ("to" . 2))
@end example
@end defun


@defun regexp-extract @var{re} @var{str} [@var{start} [@var{end}]]
[R7RS regex]
@{@t{scheme.regex}@}
Returns a list of matched string or an empty list if no matches.

@example
   (regexp-extract '(+ numeric) "192.168.0.1")
   @result{} ("192" "168" "0" "1")
@end example
@end defun

@defun regexp-split @var{re} @var{str} [@var{start} [@var{end}]]
[R7RS regex]
@{@t{scheme.regex}@}
Returns a list of not matched substrings. This can be seen as the
opposite of @code{regexp-extract} where the matched strings are
removed instead of returned.

@example
   (regexp-split '(+ space) " fee fi  fo\tfum\n")
   @result{} ("fee" "fi" "fo" "fum")
   (regexp-split '(",;") "a,,b,")
   @result{} ("a" "" "b" "")
   (regexp-split '(* numeric) "abc123def456ghi789")
   @result{} ("abc" "def" "ghi" "")
@end example
@end defun

@defun regexp-partition @var{re} @var{str} [@var{start} [@var{end}]]
[R7RS regex]
@{@t{scheme.regex}@}
Returns a list of all matched and not matched substrings. In other
words it's the combination of @code{regexp-extract} and
@code{regexp-split} where the boundary of matched strings are used to
split the original string.

@example
   (regexp-partition '(+ (or space punct)) "")
   @result{} ("")
   (regexp-partition '(+ (or space punct)) "Hello, world!\n")
   @result{} ("Hello" ", " "world" "!\n")
   (regexp-partition '(+ (or space punct)) "¿Dónde Estás?")
   @result{} ("" "¿" "Dónde" " " "Estás" "?")
   (regexp-partition '(* numeric) "abc123def456ghi789")
   @result{} ("abc" "123" "def" "456" "ghi" "789")
@end example
@end defun

@defun regexp-replace @var{re} @var{str} @var{subst} [@var{start} [@var{end} [@var{count}]]]
[R7RS regex]
@{@t{scheme.regex}@}
Returns a new string where the first matched substring is replaced
with @var{subst}. If @var{count} is specified, the @var{count}-th
match will be replaced instead of the first one.

@var{subst} can be either a string (the replacement), an integer or a
symbol to refer to the capture group that will be used as the
replacement, or a list of those.

The special symbols @code{pre} and @code{post} use the substring to
the left or right of the match as replacement, respectively.

@var{subst} could also be a procedure, which is
called with the given match object and the result will be used as the
replacement.

The optional parameters @var{start} and @var{end} essentially
transform the substitution into this

@example
   (regexp-replace re (substring str start end) subst)
@end example

except that @var{end} can take @code{#f} which is the same as
@code{(string-length str)}.

@example
   (regexp-replace '(+ space) "one two three" "_")
   @result{} "one_two three"
   (regexp-replace '(+ space) "one two three" "_" 1 10)
   @result{} "ne_two th"
   (regexp-replace '(+ space) "one two three" "_" 0 #f 0)
   @result{} "one_two three"
   (regexp-replace '(+ space) "one two three" "_" 0 #f 1)
   @result{} "one two_three"
   (regexp-replace '(+ space) "one two three" "_" 0 #f 2)
   @result{} "one two three"
@end example

Note that Gauche also has a builtin procedure of the same name, but
works slightly differently, @pxref{Using regular expressions}.
@end defun


@defun regexp-replace-all @var{re} @var{str} @var{subst} [@var{start} [@var{end}]]
[R7RS regex]
@{@t{scheme.regex}@}
Returns a new string where all matches in @var{str} are replaced with
@var{subst}. @var{subst} can also take a string, a number, a symbol or
a procedure similar to @code{regexp-replace}.

@example
(regexp-replace-all '(+ space) "one two three" "_")
   @result{} "one_two_three"
@end example

Note that Gauche also has a builtin procedure of the same name, but
works slightly differently, @pxref{Using regular expressions}.
@end defun


@defun regexp-match? @var{obj}
[R7RS regex]
@{@t{scheme.regex}@}
Returns true iff @var{obj} is a @code{<regexp-match>} object.

@example
(regexp-match? (regexp-matches "x" "x"))  @result{} #t
(regexp-match? (regexp-matches "x" "y"))  @result{} #f
@end example
@end defun


@defun regexp-match-count @var{regexp-match}
[R7RS regex]
@{@t{scheme.regex}@}
Returns the number of matches in @var{match} except the implicit zero
full match. This is just an alias of @code{rxmatch-num-matches} minus
one.

@example
(regexp-match-count (regexp-matches "x" "x"))  @result{} 0
(regexp-match-count (regexp-matches '($ "x") "x"))  @result{} 1
@end example
@end defun

@defun regexp-match-submatch @var{regexp-match} @var{field}
[R7RS regex]
@{@t{scheme.regex}@}
This is an alias of @code{rxmatch-substring}

@example
   (regexp-match-submatch (regexp-search 'word "**foo**") 0)  @result{} "foo"
   (regexp-match-submatch
    (regexp-search '(: "*" ($ word) "*") "**foo**") 0)  @result{} "*foo*"
   (regexp-match-submatch
    (regexp-search '(: "*" ($ word) "*") "**foo**") 1)  @result{} "foo"
@end example
@end defun

@defun regexp-match-submatch-start @var{regexp-match} @var{field}
[R7RS regex]
@{@t{scheme.regex}@}
This is an alias of @code{regexp-match-submatch-start}.

@example
   (regexp-match-submatch-start
    (regexp-search 'word "**foo**") 0)  @result{} 2
   (regexp-match-submatch-start
    (regexp-search '(: "*" ($ word) "*") "**foo**") 0)  @result{} 1
   (regexp-match-submatch-start
    (regexp-search '(: "*" ($ word) "*") "**foo**") 1)  @result{} 2
@end example
@end defun

@defun regexp-match-submatch-end @var{regexp-match} @var{field}
[R7RS regex]
@{@t{scheme.regex}@}
This is an alias of @code{regexp-match-submatch-end}.

@example
   (regexp-match-submatch-end
    (regexp-search 'word "**foo**") 0)  @result{} 5
   (regexp-match-submatch-end
    (regexp-search '(: "*" ($ word) "*") "**foo**") 0)  @result{} 6
   (regexp-match-submatch-end
    (regexp-search '(: "*" ($ word) "*") "**foo**") 1)  @result{} 5
@end example
@end defun

@defun regexp-match->list @var{regexp-match}
[R7RS regex]
@{@t{scheme.regex}@}
This is an alias of @code{rxmatch-substrings}

@example
   (regexp-match->list
    (regexp-search '(: ($ word) (+ (or space punct)) ($ word)) "cats & dogs"))
    @result{} '("cats & dogs" "cats" "dogs")
@end example
@end defun

@node R7RS mappings, R7RS integer division, R7RS regular expressions, R7RS large
@subsection @code{scheme.mapping} - R7RS mappings
@c NODE R7RSマップ, @code{scheme.mapping} - R7RSマップ

@deftp {Module} scheme.mapping
@deftpx {Module} scheme.mapping.hash
@mdindex scheme.mapping
@mdindex scheme.mapping.hash
This module defines immutable mappings from keys to values.
Originally called @code{srfi-146} and @code{srfi-146.hash}.

The @code{scheme.mapping} module provides @emph{mapping} objects,
where keys have total order.  The @code{scheme.mapping.hash} module
provides @code{hashmap} objects, where keys can be hashed.

Currently, Gauche uses built-in @code{<tree-map>} for the mapping object,
and built-in @code{<hash-table>} for the hashmap object.
The actual implementation
may be changed in future versions, so the user must not rely on the
underlying implementations.

The caller must treat mappings and hashmaps as immutable object.
The modules also provide ``linear update'' APIs, which is @emph{allowed}
to mutate the mappings passed to the arguments, under assumption
that the argument won't be used afterwards.  The linear update APIs
are marked with @code{!} at the end of the name.
@end deftp

@menu
* Mappings::
* Hashmaps::
@end menu


@node Mappings, Hashmaps, R7RS mappings, R7RS mappings
@subsubsection Mappings
@c NODE Mappings

@deftp {Class} <mapping>
@clindex mapping
@{@t{scheme.mapping}@}
On Gauche, this is just an alias of @code{<tree-map>}.
@end deftp

@subsubheading Constructors

@defun mapping comparator key value @dots{}
[R7RS mapping]
@{@t{scheme.mapping}@}
Creates a new mapping with the given @var{comparator},
whose initial content is
provided by @var{key} @var{value} @dots{}.

The @var{comparator} argument must be a comparator
(@pxref{Basic comparators}).

The @var{key} @var{value} @dots{} arguments must be
even length, alternating keys and values.

@example
(define m (mapping default-comparator 'a 1 'b 2))

(mapping-ref m 'a) @result{} 1
(mapping-ref m 'b) @result{} 2
@end example
@end defun

@defun mapping-unfold p f g seed comparator
[R7RS mapping]
@{@t{scheme.mapping}@}
Creates a new mapping, whose content is populated by
three procedures, @var{p}, @var{f} and @var{g}, and
a seed value @var{seed}, as follows.

In each iteration, we have a current seed value, whose initial
value is @var{seed}.

First, @var{p}, a stop predicate, is applied to the current
seed value. If it returns true, we stop iteration and returns
the new mapping.

Next, @var{f} is applied to the current seed value.  It must
return two values.  The first one is for a key and the second
one for the value.  We add this pair to the mapping.

Then, @var{g} is applied to the current seed value.  The result
becomes the seed value of the next iteration.  And we iterate.

The following example creates a mapping that maps ASCII characters
to their character codes:

@example
(mapping-unfold (cut >= <> 128)
                (^c (values (integer->char c) c))
                (cut + <> 1)
                0
                default-comparator)
@end example
@end defun

@defun mapping/ordered comparator key value @dots{}
[R7RS mapping]
@{@t{scheme.mapping}@}
Similar to @code{mapping}, but keys are given in the ascending order
w.r.t. the comparator.  An implementation may use more efficient algorithm
than @code{mapping}.  In Gauche, this is the same as @code{mapping}
at this moment.
@end defun

@defun mapping-unfold/ordered p f g seed comparator
[R7RS mapping]
@{@t{scheme.mapping}@}
Similar to @code{mapping-unfold}, but keys are generated in the
ascending order
w.r.t. the comparator.  An implementation may use more efficient algorithm
than @code{mapping-unfold}.
In Gauche, this is the same as @code{mapping-unfold} at this moment.
@end defun

@subsubheading Predicates

@defun mapping? obj
[R7RS mapping]
@{@t{scheme.mapping}@}
Returns @code{#t} iff @var{obj} is a mapping object.
@end defun

@defun mapping-empty? m
[R7RS mapping]
@{@t{scheme.mapping}@}
@var{M} must be a mapping.
Returns @code{#t} if @var{m} is empty, @code{#f} otherwise.
In Gauche, this is same as @code{tree-map-empty?}
(@pxref{Treemaps}).
@end defun

@defun mapping-contains? m key
[R7RS mapping]
@{@t{scheme.mapping}@}
@var{M} must be a mapping.
Returns @code{#t} if @var{m} has an entry with @var{key},
@code{#f} otherwise.
In Gauche, this is same as @code{tree-map-exists?}
(@pxref{Treemaps}).
@end defun

@defun mapping-disjoint? m1 m2
[R7RS mapping]
@{@t{scheme.mapping}@}
Returns @code{#t} iff two mappings @var{m1} and @var{m2} have no keys
in common.  In other words, there's no such key K that
satisfy both @code{(mapping-contains? m1 K)} and
@code{(mapping-contains? m2 K)}.
@end defun

@subsubheading Accessors

@defun mapping-ref m key :optional failure success
[R7RS mapping]
@{@t{scheme.mapping}@}
Get the value from a mapping @var{m} associated with @var{key},
and calls @var{success} on the value, and returns its result.
If @var{m} doesn't have @var{key}, @var{failure} is invoked with no
arguments and its result is returned.
Both @var{success} and @var{failure} is called in tail context.

When @var{failure} is omitted and @var{key} is not found, an error
is signaled.  When @var{success} is omitted, @code{identity} is
assumed.
@end defun

@defun mapping-ref/default m key default
[R7RS mapping]
@{@t{scheme.mapping}@}
Returns the value associated to @var{key} from a mapping @var{m}.
If @var{m} doesn't have @var{key}, @var{default} is returned.
@end defun

@defun mapping-key-comparator m
[R7RS mapping]
@{@t{scheme.mapping}@}
Returns a comparator used to compare keys in a mapping @var{m}.
@xref{Basic comparators}, for the details of comparators.
@end defun

@subsubheading Updaters

Note that the basic premise of mappings srfi is to treat mappings
as immutable.  Each updating operation comes with a purely functional
version (without bang) and a linear update version (with bang), but
the linear update version may not require to destructively modiy
the passed mapping; it's merely a hint that it may reuse the
argument for the efficiency.  You always need to use the returned
mapping as the result of update.  If you use linear update versions,
you shouldn't use the passed mapping afterwards, for there's no guarantee
how the state of the passed mapping is.

@defun mapping-adjoin m arg @dots{}
@defunx mapping-adjoin! m arg @dots{}
[R7RS mapping]
@{@t{scheme.mapping}@}
The @var{arg} @dots{} are alternating between key and value.  Returns
a mapping that contains all the entries in @var{m} plus given
keys and values, with the same comparator as @var{m}.
Linear update version @code{mapping-adjoin!} may destructively modify
@var{m} to create the return value, while @code{mapping-adjoin}
creates a new mapping.

Arguments are processed in order.
If there's already an entry in @var{m} with the same key as given to
@var{arg}, the original entry remains.

@example
(mapping-adjoin (mapping default-comparator 'a 1 'b 2) 'c 3 'a 4 'c 5)
 @result{} @r{mapping with @t{a} @arrow{} 1, @t{b} @arrow{} 2, @t{c} @arrow{} 3}
@end example
@end defun

@defun mapping-set m arg @dots{}
@defunx mapping-set! m arg @dots{}
[R7RS mapping]
@{@t{scheme.mapping}@}
The @var{arg} @dots{} are alternating between key and value.  Returns
a mapping that contains all the entries in @var{m} plus given
keys and values, with the same comparator as @var{m}.
Linear update version @code{mapping-set!} may destructively modify
@var{m} to create the return value, while @code{mapping-set}
creates a new mapping.

Arguments are processed in order.
If there's already an entry in @var{m} with the same key as given to
@var{arg}, the new key-value pair supersedes the old one.

@example
(mapping-set (mapping default-comparator 'a 1 'b 2) 'c 3 'a 4 'c 5)
 @result{} @r{mapping with @t{a} @arrow{} 4, @t{b} @arrow{} 2, @t{c} @arrow{} 5}
@end example
@end defun

@defun mapping-replace m key value
@defunx mapping-replace! m key value
[R7RS mapping]
@{@t{scheme.mapping}@}
If the mapping @var{m} has an entry of @var{key}, return a mapping
with the value of the entry replaced for @var{value}.  If @var{m} doesn't
have an entry with @var{key}, @var{m} is returned unchanged.

Linear update version @code{mapping-replace!} may destructively modify
@var{m} to produce the return value, while @code{mapping-replace}
creates a new mapping.

@example
(mapping-replace (mapping default-comparator 'a 1 'b 2) 'a 3)
 @result{} @r{mapping with @t{a} @arrow{} 3, @t{b} @arrow{} 2}

(mapping-replace (mapping default-comparator 'a 1 'b 2) 'c 3)
 @result{} @r{mapping with @t{a} @arrow{} 1, @t{b} @arrow{} 2}
@end example
@end defun


@defun mapping-delete m key @dots{}
@defunx mapping-delete! m key @dots{}
[R7RS mapping]
@{@t{scheme.mapping}@}
Returns a mapping that is the same as @var{m} except its entries with
any of the given @var{key} @dots{} being removed.  Keys that are
not in @var{m} are ignored.

Linear update version @code{mapping-delete!} may destructively modify
@var{m} to produce the return value, while @code{mapping-delete}
creates a new mapping.
@end defun

@defun mapping-delete-all m key-list
@defunx mapping-delete-all! m key-list
[R7RS mapping]
@{@t{scheme.mapping}@}
Returns a mapping that is the same as @var{m} except its entries with
any of the given keys in @var{key-list} being removed.  Keys that are
not in @var{m} are ignored.

Linear update version @code{mapping-delete-all!} may destructively modify
@var{m} to produce the return value, while @code{mapping-delete-all}
creates a new mapping.
@end defun


@defun mapping-intern m key make-value
@defunx mapping-intern! m key make-value
[R7RS mapping]
@{@t{scheme.mapping}@}
Looks up @var{key} in the mapping @var{m}, and returns two values,
@var{m} and the associated value.  If @var{m} does not contain an entry
with @var{key}, a thunk @var{make-value} is invoked, and creates a new
mapping that contains all entries in @var{m} plus a new entry with
@var{key} and the return value of @var{make-value}, then returns the
new mapping and the return value of @var{make-value}.

Linear update version @code{mapping-intern!} may destructively modify
@var{m} to produce the return value, while @code{mapping-intern}
creates a new mapping.

@example
(mapping-intern (mapping default-comparator 'a 1) 'b (^[] 2))
  @result{}
  @r{mapping with @t{a} @arrow{} 1, @t{b} @arrow{} 2}
  @r{and}
  2

(mapping-intern (mapping default-comparator 'a 1) 'a (^[] 2))
  @result{}
  @r{mapping with @t{a} @arrow{} 1}
  @r{and}
  1
@end example
@end defun

@defun mapping-update m key updater :optional failure success
@defunx mapping-update! m key updater :optional failure success
[R7RS mapping]
@{@t{scheme.mapping}@}
Semantically equivalent to this:

@example
(mapping-set @var{m} @var{var}
  (@var{updater} (mapping-ref @var{m} @var{key} @var{failure} @var{success})))
@end example

The @var{failure} and @var{success} optional arguments are procedures
with zero and one arguments, respectively.  When omitted,
@var{failure} defaults to a thunk that raises an error,
and @var{success} defaults to @code{identity}.

First, @var{key} is looked up in @var{m}.  If an entry is found,
the associated value is passed to @var{success}; otherwise,
@var{failure} is called with no arguments.  Either way, let the returned
value be @var{v0}.

Then, @var{v0} is passed to @var{updater}.  Let its result be @var{v1}.

Finally, a mapping with the same entries as @var{m} except the value of
@var{key} is altered to @var{v1} is returned.

Linear update version @code{mapping-update!} may destructively modify
@var{m} to produce the return value, while @code{mapping-update}
creates a new mapping.

@example
(mapping-update (mapping default-comparator 'a 1)
                'a (pa$ + 1))
 @result{} @r{mapping with @t{a} @arrow{} 2}

(mapping-update (mapping default-comparator)
                'a (pa$ + 1) (^[] 0))
 @result{} @r{mapping with @t{a} @arrow{} 1}
@end example
@end defun

@defun mapping-update/default m key updater default
@defunx mapping-update!/default m key updater default
[R7RS mapping]
@{@t{scheme.mapping}@}
@end defun

@defun mapping-pop m :optional failure
@defunx mapping-pop! m :optional failure
[R7RS mapping]
@{@t{scheme.mapping}@}
@end defun

@defun mapping-search m k failure success
@defunx mapping-search! m k failure success
[R7RS mapping]
@{@t{scheme.mapping}@}
@end defun

@subsubheading The whole mapping

@defun mapping-size m
[R7RS mapping]
@{@t{scheme.mapping}@}
@end defun

@defun mapping-find pred m failure
[R7RS mapping]
@{@t{scheme.mapping}@}
@end defun

@defun mapping-count pred m
[R7RS mapping]
@{@t{scheme.mapping}@}
@end defun

@defun mapping-any? pred m
@defunx mapping-every? pred m
[R7RS mapping]
@{@t{scheme.mapping}@}
@end defun

@defun mapping-keys m
@defunx mapping-values m
[R7RS mapping]
@{@t{scheme.mapping}@}
@end defun

@defun mapping-entries m
[R7RS mapping]
@{@t{scheme.mapping}@}
@end defun

@subsubheading Mapping and folding

@defun mapping-map proc comparator m
[R7RS mapping]
@{@t{scheme.mapping}@}
@end defun

@defun mapping-map/monotone proc comparator m
@defunx mapping-map/monotone! proc comparator m
[R7RS mapping]
@{@t{scheme.mapping}@}
@end defun

@defun mapping-for-each proc m
[R7RS mapping]
@{@t{scheme.mapping}@}
@end defun

@defun mapping-fold kons knil m
[R7RS mapping]
@{@t{scheme.mapping}@}
@end defun

@defun mapping-fold/reverse kons knil m
[R7RS mapping]
@{@t{scheme.mapping}@}
@end defun

@defun mapping-map->list proc m
[R7RS mapping]
@{@t{scheme.mapping}@}
@end defun

@defun mapping-filter pred m
@defunx mapping-filter! pred m
[R7RS mapping]
@{@t{scheme.mapping}@}
@end defun

@defun mapping-remove pred m
@defunx mapping-remove! pred m
[R7RS mapping]
@{@t{scheme.mapping}@}
@end defun

@defun mapping-partition pred m
@defunx mapping-partition! pred m
[R7RS mapping]
@{@t{scheme.mapping}@}
@end defun

@subsubheading Copying and conversion

@defun mapping-copy m
[R7RS mapping]
@{@t{scheme.mapping}@}
@end defun

@defun mapping->alist m
[R7RS mapping]
@{@t{scheme.mapping}@}
@end defun

@defun alist->mapping comparator alist
[R7RS mapping]
@{@t{scheme.mapping}@}
@end defun

@defun alist->mapping! m alist
[R7RS mapping]
@{@t{scheme.mapping}@}
@end defun

@defun alist->mapping/ordered comparator alist
@defunx alist->mapping/ordered! m alist
[R7RS mapping]
@{@t{scheme.mapping}@}
@end defun

@subsubheading Submappings

@defun mapping=? comparator m1 m2 @dots{}
[R7RS mapping]
@{@t{scheme.mapping}@}
@end defun

@defun mapping<? comparator m1 m2 @dots{}
@defunx mapping<=? comparator m1 m2 @dots{}
@defunx mapping>? comparator m1 m2 @dots{}
@defunx mapping>=? comparator m1 m2 @dots{}
[R7RS mapping]
@{@t{scheme.mapping}@}
@end defun

@subsubheading Set operations

@defun mapping-union m1 m2 @dots{}
@defunx mapping-union! m1 m2 @dots{}
[R7RS mapping]
@{@t{scheme.mapping}@}
@end defun

@defun mapping-intersection m1 m2 @dots{}
@defunx mapping-intersection! m1 m2 @dots{}
[R7RS mapping]
@{@t{scheme.mapping}@}
@end defun

@defun mapping-difference m1 m2 @dots{}
@defunx mapping-difference! m1 m2 @dots{}
[R7RS mapping]
@{@t{scheme.mapping}@}
@end defun

@defun mapping-xor m1 m2 @dots{}
@defunx mapping-xor! m1 m2 @dots{}
[R7RS mapping]
@{@t{scheme.mapping}@}
@end defun

@subsubheading Mappings with ordered keys

@defun mapping-min-key m
@defunx mapping-max-key m
[R7RS mapping]
@{@t{scheme.mapping}@}
@end defun

@defun mapping-min-value m
@defunx mapping-max-value m
[R7RS mapping]
@{@t{scheme.mapping}@}
@end defun

@defun mapping-min-entry m
@defunx mapping-max-entry m
[R7RS mapping]
@{@t{scheme.mapping}@}
@end defun

@defun mapping-key-predecessor m obj failure
@defunx mapping-key-successor m obj failure
[R7RS mapping]
@{@t{scheme.mapping}@}
@end defun

@defun mapping-range= m obj
@defunx mapping-range< m obj
@defunx mapping-range<= m obj
@defunx mapping-range> m obj
@defunx mapping-range>= m obj
[R7RS mapping]
@{@t{scheme.mapping}@}
@end defun

@defun mapping-range=! m obj
@defunx mapping-range<! m obj
@defunx mapping-range<=! m obj
@defunx mapping-range>! m obj
@defunx mapping-range>=! m obj
[R7RS mapping]
@{@t{scheme.mapping}@}
@end defun

@defun mapping-split m obj
@defunx mapping-split! m obj
[R7RS mapping]
@{@t{scheme.mapping}@}
@end defun

@defun mapping-catenate comparator m1 key value m2
@defunx mapping-catenate! m1 key value m2
[R7RS mapping]
@{@t{scheme.mapping}@}
@end defun

@subsubheading Comparators

@defun make-mapping-comparator comparator
[R7RS mapping]
@{@t{scheme.mapping}@}
@end defun

@defvar mapping-comparator
[R7RS mapping]
@{@t{scheme.mapping}@}
@end defvar


@node Hashmaps,  , Mappings, R7RS mappings
@subsubsection Hashmaps
@c NODE Hashmaps

@subsubheading Constructors

@defun hashmap comparator key value @dots{}
[R7RS mapping]
@{@t{scheme.mapping.hash}@}
Creates a new hashmap with the given @var{comparator},
whose initial content is
provided by @var{key} @var{value} @dots{}.

The @var{comparator} argument must be a comparator
(@pxref{Basic comparators}).

The @var{key} @var{value} @dots{} arguments must be
even length, alternating keys and values.

@example
(define m (hashmap default-comparator 'a 1 'b 2))

(hashmap-ref m 'a) @result{} 1
(hashmap-ref m 'b) @result{} 2
@end example
@end defun

@defun hashmap-unfold p f g seed comparator
[R7RS mapping]
@{@t{scheme.mapping.hash}@}
Creates a new hashmap, whose content is populated by
three procedures, @var{p}, @var{f} and @var{g}, and
a seed value @var{seed}, as follows.

In each iteration, we have a current seed value, whose initial
value is @var{seed}.

First, @var{p}, a stop predicate, is applied to the current
seed value. If it returns true, we stop iteration and returns
the new hashmap.

Next, @var{f} is applied to the current seed value.  It must
return two values.  The first one is for a key and the second
one for the value.  We add this pair to the hashmap.

Then, @var{g} is applied to the current seed value.  The result
becomes the seed value of the next iteration.  And we iterate.

The following example creates a hashmap that maps ASCII characters
to their character codes:

@example
(hashmap-unfold (cut >= <> 128)
                (^c (values (integer->char c) c))
                (cut + <> 1)
                0
                default-comparator)
@end example
@end defun

@subsubheading Predicates

@defun hashmap? obj
[R7RS mapping]
@{@t{scheme.mapping.hash}@}
Returns @code{#t} iff @var{obj} is a hashmap object.
@end defun

@defun hashmap-empty? m
[R7RS mapping]
@{@t{scheme.mapping.hash}@}
@var{M} must be a hashmap.
Returns @code{#t} if @var{m} is empty, @code{#f} otherwise.
In Gauche, this is same as @code{tree-map-empty?}
(@pxref{Treemaps}).
@end defun

@defun hashmap-contains? m key
[R7RS mapping]
@{@t{scheme.mapping.hash}@}
@var{M} must be a hashmap.
Returns @code{#t} if @var{m} has an entry with @var{key},
@code{#f} otherwise.
In Gauche, this is same as @code{tree-map-exists?}
(@pxref{Treemaps}).
@end defun

@defun hashmap-disjoint? m1 m2
[R7RS mapping]
@{@t{scheme.mapping.hash}@}
Returns @code{#t} iff two hashmaps @var{m1} and @var{m2} have no keys
in common.  In other words, there's no such key K that
satisfy both @code{(hashmap-contains? m1 K)} and
@code{(hashmap-contains? m2 K)}.
@end defun

@subsubheading Accessors

@defun hashmap-ref m key :optional failure success
[R7RS mapping]
@{@t{scheme.mapping.hash}@}
Get the value from a hashmap @var{m} associated with @var{key},
and calls @var{success} on the value, and returns its result.
If @var{m} doesn't have @var{key}, @var{failure} is invoked with no
arguments and its result is returned.
Both @var{success} and @var{failure} is called in tail context.

When @var{failure} is omitted and @var{key} is not found, an error
is signaled.  When @var{success} is omitted, @code{identity} is
assumed.
@end defun

@defun hashmap-ref/default m key default
[R7RS mapping]
@{@t{scheme.mapping.hash}@}
Returns the value associated to @var{key} from a hashmap @var{m}.
If @var{m} doesn't have @var{key}, @var{default} is returned.
@end defun

@defun hashmap-key-comparator m
[R7RS mapping]
@{@t{scheme.mapping.hash}@}
Returns a comparator used to compare keys in a hashmap @var{m}.
@xref{Basic comparators}, for the details of comparators.
@end defun

@subsubheading Updaters

Note that the basic premise of hashmaps srfi is to treat hashmaps
as immutable.  Each updating operation comes with a purely functional
version (without bang) and a linear update version (with bang), but
the linear update version may not require to destructively modiy
the passed hashmap; it's merely a hint that it may reuse the
argument for the efficiency.  You always need to use the returned
hashmap as the result of update.  If you use linear update versions,
you shouldn't use the passed hashmap afterwards, for there's no guarantee
how the state of the passed hashmap is.

@defun hashmap-adjoin m arg @dots{}
@defunx hashmap-adjoin! m arg @dots{}
[R7RS mapping]
@{@t{scheme.mapping.hash}@}
@end defun

@defun hashmap-set m arg @dots{}
@defunx hashmap-set! m arg @dots{}
[R7RS mapping]
@{@t{scheme.mapping.hash}@}
@end defun

@defun hashmap-replace m key value
@defunx hashmap-replace! m key value
[R7RS mapping]
@{@t{scheme.mapping.hash}@}
@end defun


@defun hashmap-delete m key @dots{}
@defunx hashmap-delete! m key @dots{}
[R7RS mapping]
@{@t{scheme.mapping.hash}@}
@end defun

@defun hashmap-delete-all m key-list
@defunx hashmap-delete-all! m key-list
[R7RS mapping]
@{@t{scheme.mapping.hash}@}
@end defun


@defun hashmap-intern m key failure
@defunx hashmap-intern! m key failure
[R7RS mapping]
@{@t{scheme.mapping.hash}@}
@end defun

@defun hashmap-update m key updater :optional failure success
@defunx hashmap-update! m key updater :optional failure success
[R7RS mapping]
@{@t{scheme.mapping.hash}@}
@end defun

@defun hashmap-update/default m key updater default
@defunx hashmap-update!/default m key updater default
[R7RS mapping]
@{@t{scheme.mapping.hash}@}
@end defun

@defun hashmap-pop m :optional failure
@defunx hashmap-pop! m :optional failure
[R7RS mapping]
@{@t{scheme.mapping.hash}@}
@end defun

@defun hashmap-search m k failure success
@defunx hashmap-search! m k failure success
[R7RS mapping]
@{@t{scheme.mapping.hash}@}
@end defun

@subsubheading The whole hashmap

@defun hashmap-size m
[R7RS mapping]
@{@t{scheme.mapping.hash}@}
@end defun

@defun hashmap-find pred m failure
[R7RS mapping]
@{@t{scheme.mapping.hash}@}
@end defun

@defun hashmap-count pred m
[R7RS mapping]
@{@t{scheme.mapping.hash}@}
@end defun

@defun hashmap-any? pred m
@defunx hashmap-every? pred m
[R7RS mapping]
@{@t{scheme.mapping.hash}@}
@end defun

@defun hashmap-keys m
@defunx hashmap-values m
[R7RS mapping]
@{@t{scheme.mapping.hash}@}
@end defun

@defun hashmap-entries m
[R7RS mapping]
@{@t{scheme.mapping.hash}@}
@end defun

@subsubheading Mapping and folding

@defun hashmap-map proc comparator m
[R7RS mapping]
@{@t{scheme.mapping.hash}@}
@end defun

@defun hashmap-for-each proc m
[R7RS mapping]
@{@t{scheme.mapping.hash}@}
@end defun

@defun hashmap-fold kons knil m
[R7RS mapping]
@{@t{scheme.mapping.hash}@}
@end defun

@defun hashmap-map->list proc m
[R7RS mapping]
@{@t{scheme.mapping.hash}@}
@end defun

@defun hashmap-filter pred m
@defunx hashmap-filter! pred m
[R7RS mapping]
@{@t{scheme.mapping.hash}@}
@end defun

@defun hashmap-remove pred m
@defunx hashmap-remove! pred m
[R7RS mapping]
@{@t{scheme.mapping.hash}@}
@end defun

@defun hashmap-partition pred m
@defunx hashmap-partition! pred m
[R7RS mapping]
@{@t{scheme.mapping.hash}@}
@end defun

@subsubheading Copying and conversion

@defun hashmap-copy m
[R7RS mapping]
@{@t{scheme.mapping.hash}@}
@end defun

@defun hashmap->alist m
[R7RS mapping]
@{@t{scheme.mapping.hash}@}
@end defun

@defun alist->hashmap comparator alist
[R7RS mapping]
@{@t{scheme.mapping.hash}@}
@end defun

@defun alist->hashmap! m alist
[R7RS mapping]
@{@t{scheme.mapping.hash}@}
@end defun

@subsubheading Subhashmaps

@defun hashmap=? comparator m1 m2 @dots{}
[R7RS mapping]
@{@t{scheme.mapping.hash}@}
@end defun

@defun hashmap<? comparator m1 m2 @dots{}
@defunx hashmap<=? comparator m1 m2 @dots{}
@defunx hashmap>? comparator m1 m2 @dots{}
@defunx hashmap>=? comparator m1 m2 @dots{}
[R7RS mapping]
@{@t{scheme.mapping.hash}@}
@end defun

@subsubheading Set operations

@defun hashmap-union m1 m2 @dots{}
@defunx hashmap-union! m1 m2 @dots{}
[R7RS mapping]
@{@t{scheme.mapping.hash}@}
@end defun

@defun hashmap-intersection m1 m2 @dots{}
@defunx hashmap-intersection! m1 m2 @dots{}
[R7RS mapping]
@{@t{scheme.mapping.hash}@}
@end defun

@defun hashmap-difference m1 m2 @dots{}
@defunx hashmap-difference! m1 m2 @dots{}
[R7RS mapping]
@{@t{scheme.mapping.hash}@}
@end defun

@defun hashmap-xor m1 m2 @dots{}
@defunx hashmap-xor! m1 m2 @dots{}
[R7RS mapping]
@{@t{scheme.mapping.hash}@}
@end defun

@subsubheading Comparators

@defun make-hashmap-comparator comparator
[R7RS mapping]
@{@t{scheme.mapping.hash}@}
@end defun

@defvar hashmap-comparator
[R7RS mapping]
@{@t{scheme.mapping.hash}@}
@end defvar

@c ----------------------------------------------------------------------
@node R7RS integer division, R7RS bitwise operations, R7RS mappings, R7RS large
@subsection @code{scheme.division} - R7RS integer division
@c NODE R7RS整数除算, @code{scheme.division} - R7RS整数除算

@deftp {Module} scheme.division
@mdindex scheme.division
This module provides a comprehensive set of integer division operators.

Quotient and remainder in integer divisions can be defined in multiple
ways, when you consider the choice of sign of the result with regard to
the operands.  Gauche has builtin procedures in several flavors:
R5RS @code{quotient}, @code{remainder} and @code{modulo},
R6RS @code{div}, @code{mod}, @code{div0} and @code{mod0},
and R7RS @code{floor-quotient}, @code{floor-remainder}, @code{floor/},
@code{truncate-quotient}, @code{truncate-remainder}, @code{truncate/}.

This module complements R7RS procedures, by adding @code{ceiling},
@code{round}, @code{euclidean} and @code{balanced} variants.

The following procedures are in scheme.division but built-in in Gauche
(@pxref{Arithmetics}).
@example
floor-quotient     floor-remainder    floor/
truncate-quotient  truncate-remainder truncate/
@end example
@end deftp

@defun ceiling-quotient n d
@defunx ceiling-remainder n d
@defunx ceiling/ n d
[R7RS division]
@{@t{scheme.division}@}
@example
ceiling-quotient = ceiling(n / d)
ceiling-remainder = n - d * ceiling-quotient
ceiling/ = values(ceiling-quotient, ceiling-remainder)
@end example
@end defun

@defun round-quotient n d
@defunx round-remainder n d
@defunx round/ n d
[R7RS division]
@{@t{scheme.division}@}
@example
round-quotient = round(n/d)
round-remainder = n - d * round-quotient
round/ = values(round-quotient, round-remainder)
@end example
@end defun

@defun euclidean-quotient n d
@defunx euclidean-remainder n d
@defunx euclidean/ n d
[R7RS division]
@{@t{scheme.division}@}
@example
euclidean-quotient = floor(n / d)   if d > 0
                     ceiling(n / d) if d < 0
euclidean-remainder = n - d * euclidean-quotient
euclidean/ = values(euclidean-quotient, euclidean-remainder)
@end example
The Eclidean variant satisfies a property @code{0 <= remainder < abs(d)}.
These are the same as R6RS's @code{div}, @code{mod}, and @code{div-and-mod},
except that they accept non-integers (@pxref{Arithmetics})
@end defun

@defun balanced-quotient n d
@defunx balanced-remainder n d
@defunx balanced/ n d
[R7RS division]
@{@t{scheme.division}@}
@example
balanced-quotient = roundup(n / d)
balanced-remainder = n - d * balanced-quotient
balanced/ = values(balanced-quotient, balanced-remainder)
  where roundup(x) rounds towards zero if |x| - floor(|x|) < 0.5,
                   and away from zero  if |x| - floor(|x|) >= 0.5,
@end example
The balanced variant satisfies a property
@code{-abs(d/2) <= remainder < abs(d/2)}.
These are the same as R6RS's @code{div0}, @code{mod0}, and
@code{div0-and-mod0}, except that they accept non-integers
(@pxref{Arithmetics}).
@end defun

@c ----------------------------------------------------------------------
@node R7RS bitwise operations, R7RS fixnum, R7RS integer division, R7RS large
@subsection @code{scheme.bitwise} - R7RS bitwise operations
@c NODE R7RSビット演算, @code{scheme.bitwise} - R7RSビット演算

@deftp {Module} scheme.bitwise
@mdindex scheme.bitwise
This module provides comprehensive bitwise operations.
Originally it was srfi-151.
It is mostly a superset of srfi-60, with some change of names for the consistency
and the compatibility (@pxref{Integers as bits}).  We keep srfi-60 for
legacy code, while recommend this module to be used in the new code.

The following procedures are Gauche built-in.
@xref{Basic bitwise operations}, for the description.

@example
integer-length    copy-bit          bit-field
@end example
@end deftp

@subheading Basic operations

@defun bitwise-not n
[R7RS bitwise]
@{@t{scheme.bitwise}@}
Returns the bitwise complement of @var{n}.
Same as builtin @code{lognot} (@pxref{Basic bitwise operations}).
@end defun

@defun bitwise-and n @dots{}
@defunx bitwise-ior n @dots{}
@defunx bitwise-xor n @dots{}
@defunx bitwise-eqv  n @dots{}
[R7RS bitwise]
@{@t{scheme.bitwise}@}
When no arguments are given, these procedures returns @code{-1}, @code{0},
@code{0} and @code{-1}, respectively.  With one arguments, they return the
argument as is.  With two arguments, they return bitwise and, ior, xor,
and eqv (complement of xor).  With three or more arguments, they apply
binary operations associaively, that is,

@example
(bitwise-xor a b c)
 @equiv{} (bitwise-xor a (bitwise-xor b c))
 @equiv{} (bitwise-xor (bitwise-xor a b) c)
@end example

Be careful that multi-argument @code{bitwise-eqv} does not produce
bit 1 everywhere that all the argument's bit agree.

The first three procedures are the same as built-in
@code{logand}, @code{logior} and @code{logxor}, respectively
(@pxref{Basic bitwise operations}).
@end defun

@defun bitwise-nand n0 n1
@defunx bitwise-nor n0 n1
@defunx bitwise-andc1 n0 n1
@defunx bitwise-andc2 n0 n1
@defunx bitwise-orc1 n0 n1
@defunx bitwise-orc2 n0 n1
[R7RS bitwise]
@{@t{scheme.bitwise}@}
These operations are not associative.

@example
nand n0 n1   @equiv{}  (NOT (AND n0 n1))
nor n0 n1    @equiv{}  (NOT (OR n0 n1))
andc1 n0 n1  @equiv{}  (AND (NOT n0) n1)
andc2 n0 n1  @equiv{}  (AND n0 (NOT n1))
orc1 n0 n1   @equiv{}  (OR (NOT n0) n1)
orc2 n0 n1   @equiv{}  (OR n0 (NOT n1))
@end example
@end defun

@subheading Integer operations

@defun arithmetic-shift n count
[R7RS bitwise]
@{@t{scheme.bitwise}@}
Shift @var{n} for @var{count} bits to left; if @var{count} is negative,
it shifts @var{n} to right for @var{-count} bits.

Same as builtin @code{ash} (@pxref{Basic bitwise operations}).
@end defun

@defun bit-count n
[R7RS bitwise]
@{@t{scheme.bitwise}@}
If @var{n} is positive, returns the number of @code{1}'s in @var{n}.
If @var{n} is negative, returns the number of @code{0}'s in @var{n}.

Same as builtin @code{logcount} (@pxref{Basic bitwise operations}).
@end defun

@defun bitwise-if mask n0 n1
[R7RS bitwise]
@{@t{scheme.bitwise}@}
Returns integer, whose @var{n}-th bit is taken as follows:
If the @var{n}-th bit of @var{mask} is 1, the @var{n}-th bit of @var{n0};
otherwise, the @var{n}-th bit of @var{n1}.

@example
(bitwise-if #b10101100 #b00110101 #b11001010)
 @result{} #b01100110
@end example
@end defun

@subheading Single-bit operations

@defun bit-set? index n
[R7RS bitwise]
@{@t{scheme.bitwise}@}
Returns @code{#t} or @code{#f} if @var{index}-th bit (counted from LSB)
of @var{n} is @code{1} or @code{0}, respectively.

Same as built-in @code{logbit?} (@pxref{Basic bitwise operations}).
@end defun

@defun bit-swap index1 index2 n
[R7RS bitwise]
@{@t{scheme.bitwise}@}
Returns an integer with @var{index1}-th bit and @var{index2}-th bit are
swapped.  Index is counted from LSB.
@end defun

@defun any-bit-set? mask n
@defunx every-bit-set? mask n
[R7RS bitwise]
@{@t{scheme.bitwise}@}
Returns @code{#t} iff any/all bits set in @var{mask} are also set in @var{n}.

@code{any-bit-set?} is the same as built-in @code{logtest},
except @code{logtest} accepts one or more arguments
(@pxref{Basic bitwise operations}).
@end defun

@defun first-set-bit n
[R7RS bitwise]
@{@t{scheme.bitwise}@}
Returns the number of factors of two of integer @var{n}; that is,
returns a maximum @code{k} such that @code{(expt 2 k)} divides
@var{n} without a remainder.
It is the same as the index of the least significant @code{1} in @var{n},
hence the alias @code{first-set-bit}.

@example
(first-set-bit 0) @result{} -1   ; @r{edge case}
(first-set-bit 1) @result{} 0
(first-set-bit 2) @result{} 1
(first-set-bit 15) @result{} 0
(first-set-bit 16) @result{} 4
@end example

This is equivalent to Gauche's built-in @code{twos-exponent-factor}
(@pxref{Basic bitwise operations}).
@end defun

@subheading Bit field operations

@defun bit-field-any? n start end
@defunx bit-field-every? n start end
[R7RS bitwise]
@{@t{scheme.bitwise}@}
Returns @code{#t} iff any/all bits of @var{n} from @var{start} (inclusive)
to @var{end} (exclusive) are set.
@end defun

@defun bit-field-clear n start end
@defunx bit-field-set n start end
[R7RS bitwise]
@{@t{scheme.bitwise}@}
Returns @var{n} with the bits from @var{start} (inclusive)
to @var{end} (exclusive) are set to all @code{0}'s/@code{1}'s.
@end defun

@defun bit-field-replace dst src start end
[R7RS bitwise]
@{@t{scheme.bitwise}@}
Returns @var{dst} with the bitfield from @var{start} to @var{end}
are replaced with the least-significant (@var{end}-@var{start}) bits
of @var{src.}

@example
(bit-field-replace #b101010 #b010 1 4) @result{} #b100100
@end example

Same as built-in @code{copy-bit-field} (@pxref{Basic bitwise operations}).
@end defun

@defun bit-field-replace-same dst src start end
[R7RS bitwise]
@{@t{scheme.bitwise}@}
Returns @var{dst} with the bitfield from @var{start} to @var{end}
are replaced with the @code{src}'s bitfield from @var{start} to @var{end}.

@example
(bit-field-replace-same #b111111 #b100100 1 4) @result{} #b110101
@end example
@end defun

@defun bit-field-rotate n count start end
[R7RS bitwise]
@{@t{scheme.bitwise}@}
Rotate the region of @var{n} between @var{start}-th bit (inclusive) and
@var{end}-th bit (exclusive) by @var{count} bits to the left.
If @var{count} is negative, it rotates to the right by @var{-count}
bits.

@example
(bit-field-rotate #b110100100010000 -1 5 9)
 @result{} 26768 ;#b110100010010000

(bit-field-rotate #b110100100010000 1 5 9)
 @result{} 26672 ;#b110100000110000
@end example
@end defun

@defun bit-field-reverse n start end
[R7RS bitwise]
@{@t{scheme.bitwise}@}
Reverse the order of bits of @var{n} between @var{start}-th bit
(inclusive) and @var{end}-th bit (exclusive).

@example
(bit-field-reverse #b10100111 0 8)
 @result{} 229 ; #b11100101
@end example
@end defun

@subheading Bits conversion

@defun bits->list n :optional len
@defunx bits->vector n :optional len
[R7RS bitwise]
@{@t{scheme.bitwise}@}
Returns a list/vector of booleans of length @var{len},
corresponding to each bit in non-negative integer @var{n}, LSB-first.
When @var{len} is omitted, @code{(integer-length n)} is used.

@example
(bits->vector #b101101110)
  @result{} #(#f #t #t #t #f #t #t #f #t)
@end example

Note: Srfi-60 has a similar @code{integer->list}, but the order of
bits is reversed.
@end defun

@defun list->bits bool-list
@defunx vector->bits bool-vector
[R7RS bitwise]
@{@t{scheme.bitwise}@}
Returns an exact integer formed from boolean values in given list/vector,
LSB first.  The result will never be negative.

@example
(list->bits '(#f #t #t #t #f #t #t #f #t))
 @result{} #b101101110
@end example

Note: Srfi-60 has a similar @code{list->integer}, but the order of
bits is reversed.
@end defun

@defun bits bool @dots{}
[R7RS bitwise]
@{@t{scheme.bitwise}@}
Returns the integer coded by @var{bool}s, LSB first.
The result will never be negative.

@example
(bits #f #t #t #t #f #t #t #f #t)
 @result{} #b101101110
@end example

Note: Srfi-60 has a similar @code{booleans->integer}, but the order of
bits is reversed.
@end defun

@subheading Fold, unfold and generate

@defun bitwise-fold kons knil n
[R7RS bitwise]
@{@t{scheme.bitwise}@}
Traverse bits in integer @var{n} from LSB to the @code{(integer-length n)} bit,
applying @code{kons} on the bit as boolean
and the seed value, whose initial value
is given by @var{knil}.  Returns the last result of @var{kons}.

@example
(bitwise-fold cons '() #b10110111)
 @result{} (#t #f #t #t #f #t #t #t)
@end example
@end defun

@defun bitwise-for-each proc n
[R7RS bitwise]
@{@t{scheme.bitwise}@}
Applies @var{proc} to the bit as boolean in @var{n}, from LSB to
the @code{(integer-length n)} bit.  The result is discarded.
@end defun

@defun bitwise-unfold p f g seed
[R7RS bitwise]
@{@t{scheme.bitwise}@}
Generates a non-negative integer bit by bit, from LSB to MSB.
The @var{seed} gives the initial state value.
For each iteration, @var{p} is applied to the current state value,
and if it returns a true value, the iteration ends and @code{bitwise-unfold}
returns the accumulated bits as an integer.
Otherwise, @var{f} is applied to the current state value, and
its result, coerced to a boolean value, determines the bit value.
Then @var{g} is applied to the current state value to produce
the next state value of the next iteration.

The following expression produces a bitfield of width 100, where n-th bit
indicates whether n is prime or not:

@example
(use math.prime)
(bitwise-unfold (cut = 100 <>)
                small-prime?
                (cut + 1 <>)
                0)
@end example
@end defun

@defun make-bitwise-generator n
[R7RS bitwise]
@{@t{scheme.bitwise}@}
Returns a generator that generates boolean values
corresponding to the bits in @var{n}, LSB-first.  The returned generator
is infinite.

This is similar to @code{bits->generator} in @code{gauche.generator},
except that the generator created by it stops at the integer
length of @var{n} (@pxref{Generators}).
@end defun

@c ----------------------------------------------------------------------
@node R7RS fixnum, R7RS flonum, R7RS bitwise operations, R7RS large
@subsection @code{scheme.fixnum} - R7RS fixnums
@c NODE R7RS fixnum, @code{scheme.fixnum} - R7RS fixnum

@deftp {Module} scheme.fixnum
@mdindex scheme.finxum
This module provides a set of fixnum-specific operations.
Originally defined as srfi-143.

A fixnum is a small exact integer that can be handled very efficiently.
In Gauche, fixnum is 62bit wide on 64bit platforms, and
30bit wide on 32bit platforms.

Note that these procedures are defined only to work on fixnums,
but it is not enforced.  If you pass non-fixnum arguments, or
the result falls out of range of fixnums, what happens is up to
the implementation.  Consider these procedures as the way to
tell your intentions to the compiler for potential optimizations.

In the current Gauche architecture,
generic numeric operators are just as efficient,
so most procedures provided in this module are aliases to corresponding
operators.   However, we might employ some optimizations in future
versions.

The procedure @code{fixnum?} is built-in, and
not explained here.  @xref{Numerical predicates}.
@end deftp

@defvar fx-width
[R7RS fixnum]
@{@t{scheme.fixnum}@}
A variable bound to an exact positive integer @var{w}, where @var{w}
is the greatest number such that exact integers between
@code{2^(w-1) - 1} and @code{-2^(w-1)} are all fixnums.
This value is the same as the built-in procedure @code{fixnum-width}
returns (@pxref{Arithmetics}).

In Gauche, it is usually @code{30} for 32bit platforms, and @code{62} for
64bit platforms.
@end defvar

@defvar fx-greatest
@defvarx fx-least
[R7RS fixnum]
@{@t{scheme.fixnum}@}
Variables bound to the greatest fixnum and the least fixnum.
They are the same as the built-in procedures
@code{greatest-fixnum} and @code{least-fixnum} return, respectively
(@pxref{Arithmetics}).

The following table shows the typical values on Gauche:

@multitable {Platform} {2,305,843,009,213,693,951} {-2,305,843,009,213,693,951}
@headitem Platform @tab @code{fx-greatest} @tab @code{fx-least}
@item 32bit @tab 536,870,911 @tab -536,870,912
@item 64bit @tab 2,305,843,009,213,693,951 @tab -2,305,843,009,213,693,952
@end multitable
@end defvar

@defun fx=? i @dots{}
@defunx fx<? i @dots{}
@defunx fx<=? i @dots{}
@defunx fx>? i @dots{}
@defunx fx>=? i @dots{}
[R7RS fixnum]
@{@t{scheme.fixnum}@}
These are equivalent to built-in @code{=}, @code{<}, @code{<=},
@code{>} and @code{>=}, except that you should use these only for fixnums.
@end defun

@defun fxzero? i
@defunx fxpositive? i
@defunx fxnegative? i
@defunx fxodd? i
@defunx fxeven? i
[R7RS fixnum]
@{@t{scheme.fixnum}@}
These are equivalent to built-in @code{zero?}, @code{positive?},
@code{negative?}, @code{odd?} and @code{even?},
except that you should use these only for fixnums.
@end defun

@defun fxmax i j @dots{}
@defunx fxmin i j @dots{}
[R7RS fixnum]
@{@t{scheme.fixnum}@}
These are equivalent to built-in @code{max} and  @code{min},
except that you should use these only for fixnums.
@end defun

@defun fx+ i j
@defunx fx- i j
@defunx fx* i j
[R7RS fixnum]
@{@t{scheme.fixnum}@}
These are equivalent to built-in @code{+}, @code{-}
and  @code{*},
except that these take exactly two arguments, and
you should use these only for fixnums and
when the result fits within fixnum range.
@end defun

@defun fxneg i
[R7RS fixnum]
@{@t{scheme.fixnum}@}
This is equivalent to single-argument @code{-},
except that you should use this only for fixnums and
when the result fits within fixnum range.
@end defun

@defun fxquotient i j
@defunx fxremainder i j
@defunx fxabs i
@defunx fxsquare i
[R7RS fixnum]
@{@t{scheme.fixnum}@}
These are equivalent to built-in @code{quotient}, @code{remainder},
@code{abs} and @code{square},
except that you should use these only for fixnums and
when the result fits within fixnum range.
@end defun

@defun fxsqrt i
[R7RS fixnum]
@{@t{scheme.fixnum}@}
This is equivalent to @code{exact-integer-sqrt} (not @code{sqrt}),
except that you should use it only for fixnums.
@xref{Arithmetics}.
@end defun

@defun fx+/carry i j k
@defunx fx-/carry i j k
@defunx fx*/carry i j k
[R7RS fixnum]
@{@t{scheme.fixnum}@}
These calculates @code{(+ i j k)}, @code{(- i j k)} and @code{(+ (* i j) k)},
respectively, then split the result to the remainder value @code{R}
in the fixnum range, and spilled value @code{Q}, and return those values.
That is,
@code{(+ (* Q (expt 2 fx-width)) R)} is the result of above calculations.
Both @code{Q} and @code{R} fits in the fixnum range, and
@code{- 2^(w-1) <= R < 2^(w-1)}, where @code{w} is @code{fx-width}.

@example
(fx*/carry 1845917459 19475917581 4735374)
 @result{} -942551854601421179 @r{and} 8

(+ (* 8 (expt 2 fx-width)) -942551854601421179)
 @result{} 35950936292817682053

(+ (* 1845917459 19475917581) 4735374)
 @result{} 35950936292817682053
@end example

These are primitives to implement extended-precision
integer arithmetic on top of fixnum operations.  In Gauche, however,
you can just use built-in bignums.  We provide these for the compatibility.
@end defun

@defun fxnot i
@defunx fxand i @dots{}
@defunx fxior i @dots{}
@defunx fxxor i @dots{}
@defunx fxarithmetic-shift i count
@defunx fxlength i
@defunx fxbit-count i
@defunx fxcopy-bit index i boolean
@defunx fxbit-set? index i
@defunx fxbit-field i start end
@defunx fxfirst-set-bit i
[R7RS fixnum]
@{@t{scheme.fixnum}@}
These are equivalent to @code{lognot}, @code{logand},
@code{logior}, @code{logxor}, @code{ash}, @code{integer-length},
@code{logcount},
@code{copy-bit}, @code{logbit?}, @code{bit-field},
and @code{twos-exponent-factor} respectively,
except that you should use these only for fixnums.
@xref{Basic bitwise operations}.
@end defun

@defun fxif mask i j
@defunx fxbit-field-rotate i start end
@defunx fxbit-field-rotate i start end
[R7RS fixnum]
@{@t{scheme.fixnum}@}
These are equivalent to srfi-60's
@code{bitwise-if}, @code{rotate-bit-field} and
@code{reverse-bit-field},
except that you should use these only for fixnums.
@xref{Integers as bits}.
@end defun


@c ----------------------------------------------------------------------
@node R7RS flonum, R7RS bytevectors, R7RS fixnum, R7RS large
@subsection @code{scheme.flonum} - R7RS flonum
@c NODE R7RS flonum, @code{scheme.flonum} - R7RS flonum

@deftp {Module} scheme.flonum
@mdindex scheme.flonum
This module provides a set of flonum-specific operations.
Originally defined as srfi-144.

In Gauche, a flonum is IEEE 754 double-precision floating point numbers.

Note that these procedures are defined only to work on flonums,
but it is not enforced.  If you pass non-flonum arguments,
the result is undefined.
Consider these procedures as the way to
tell your intentions to the compiler for potential optimizations.

In the current Gauche architecture,
generic numeric operators are just as efficient,
so most procedures provided in this module are aliases to corresponding
operators.   However, we might employ some optimizations in future
versions.

The procedure @code{flonum?} is built-in, and
not explained here.  @xref{Numerical predicates}.
@end deftp

@subheading Constants

We also have a few constants in @code{math.const} module
(@pxref{Mathematic constants}).

@defvr {Constant} fl-e
[R7RS flonum]
@{@t{scheme.flonum}@}
e.
@end defvr

@defvr {Constant} fl-1/e
[R7RS flonum]
@{@t{scheme.flonum}@}
@code{(/ e)}.
@end defvr


@defvr {Constant} fl-e-2
[R7RS flonum]
@{@t{scheme.flonum}@}
@code{(square e)}.
@end defvr

@defvr {Constant} fl-e-pi/4
[R7RS flonum]
@{@t{scheme.flonum}@}
@code{(expt e (/ pi 4))}.
@end defvr

@defvr {Constant} fl-log2-e
[R7RS flonum]
@{@t{scheme.flonum}@}
@code{(log2 e)}.  (Same as @code{(/ (log 2))}).
@end defvr

@defvr {Constant} fl-log10-e
[R7RS flonum]
@{@t{scheme.flonum}@}
@code{(log10 e)}.  (Same as @code{(/ (log 10))}).
@end defvr

@defvr {Constant} fl-log-2
[R7RS flonum]
@{@t{scheme.flonum}@}
@code{(log 2)}.
@end defvr

@defvr {Constant} fl-1/log-2
[R7RS flonum]
@{@t{scheme.flonum}@}
@code{(/ (log 2))}.  (Same as @code{(log2 e)}).
@end defvr

@defvr {Constant} fl-log-3
[R7RS flonum]
@{@t{scheme.flonum}@}
@code{(log 3)}.
@end defvr

@defvr {Constant} fl-log-pi
[R7RS flonum]
@{@t{scheme.flonum}@}
@code{(log pi)}.
@end defvr

@defvr {Constant} fl-log-10
[R7RS flonum]
@{@t{scheme.flonum}@}
@code{(log 10)}.
@end defvr

@defvr {Constant} fl-1/log-10
[R7RS flonum]
@{@t{scheme.flonum}@}
@code{(/ (log 10))}.  (Same as @code{(log10 e)}).
@end defvr

@defvr {Constant} fl-pi
[R7RS flonum]
@{@t{scheme.flonum}@}
@code{pi}.
@end defvr

@defvr {Constant} fl-1/pi
[R7RS flonum]
@{@t{scheme.flonum}@}
@code{(/ pi)}.
@end defvr

@defvr {Constant} fl-2pi
[R7RS flonum]
@{@t{scheme.flonum}@}
@code{(* 2 pi)}.
@end defvr

@defvr {Constant} fl-pi/2
[R7RS flonum]
@{@t{scheme.flonum}@}
@code{(/ pi 2)}.
@end defvr

@defvr {Constant} fl-pi/4
[R7RS flonum]
@{@t{scheme.flonum}@}
@code{(/ pi 4)}.
@end defvr

@defvr {Constant} fl-pi-squared
[R7RS flonum]
@{@t{scheme.flonum}@}
@code{(square pi)}.
@end defvr

@defvr {Constant} fl-degree
[R7RS flonum]
@{@t{scheme.flonum}@}
@code{(/ pi 180)}.
@end defvr

@defvr {Constant} fl-2/pi
[R7RS flonum]
@{@t{scheme.flonum}@}
@code{(/ 2 pi)}.
@end defvr

@defvr {Constant} fl-2/sqrt-pi
[R7RS flonum]
@{@t{scheme.flonum}@}
@code{(/ 2 (sqrt pi))}.
@end defvr

@defvr {Constant} fl-sqrt-2
@code{(sqrt 2)}.
@end defvr

@defvr {Constant} fl-sqrt-3
[R7RS flonum]
@{@t{scheme.flonum}@}
@code{(sqrt 3)}.
@end defvr

@defvr {Constant} fl-sqrt-5
[R7RS flonum]
@{@t{scheme.flonum}@}
@code{(sqrt 5)}.
@end defvr

@defvr {Constant} fl-sqrt-10
[R7RS flonum]
@{@t{scheme.flonum}@}
@code{(sqrt 10)}.
@end defvr

@defvr {Constant} fl-1/sqrt-2
[R7RS flonum]
@{@t{scheme.flonum}@}
@code{(/ (sqrt 2))}.
@end defvr

@defvr {Constant} fl-cbrt-2
[R7RS flonum]
@{@t{scheme.flonum}@}
@code{(expt 2 1/3)}.
@end defvr

@defvr {Constant} fl-cbrt-3
[R7RS flonum]
@{@t{scheme.flonum}@}
@code{(expt 3 1/3)}.
@end defvr

@defvr {Constant} fl-4thrt-2
[R7RS flonum]
@{@t{scheme.flonum}@}
@code{(expt 2 1/4)}.
@end defvr

@defvr {Constant} fl-phi
[R7RS flonum]
@{@t{scheme.flonum}@}
@code{(/ (+ 1 (sqrt 5)) 2)}.
@end defvr

@defvr {Constant} fl-log-phi
[R7RS flonum]
@{@t{scheme.flonum}@}
@code{(log fl-phi)}.
@end defvr

@defvr {Constant} fl-1/log-phi
[R7RS flonum]
@{@t{scheme.flonum}@}
@code{(/ (log fl-phi))}.
@end defvr

@defvr {Constant} fl-euler
[R7RS flonum]
@{@t{scheme.flonum}@}
Euler's constant.
@end defvr

@defvr {Constant} fl-e-euler
[R7RS flonum]
@{@t{scheme.flonum}@}
@code{(exp fl-euler)}
@end defvr

@defvr {Constant} fl-sin-1
[R7RS flonum]
@{@t{scheme.flonum}@}
@code{(sin 1)}
@end defvr

@defvr {Constant} fl-cos-1
[R7RS flonum]
@{@t{scheme.flonum}@}
@code{(cos 1)}
@end defvr

@defvr {Constant} fl-gamma-1/2
[R7RS flonum]
@{@t{scheme.flonum}@}
@code{(gamma 1/2)}
@end defvr

@defvr {Constant} fl-gamma-1/3
[R7RS flonum]
@{@t{scheme.flonum}@}
@code{(gamma 1/3)}
@end defvr

@defvr {Constant} fl-gamma-2/3
[R7RS flonum]
@{@t{scheme.flonum}@}
@code{(gamma 2/3)}
@end defvr

@defvr {Constant} fl-gamma-1/3
[R7RS flonum]
@{@t{scheme.flonum}@}
@code{(gamma 1/3)}
@end defvr

@defvr {Constant} fl-greatest
@defvrx {Constant} fl-least
[R7RS flonum]
@{@t{scheme.flonum}@}
Bound to the largest/smallest positive finite flonum.

The latter is the same as @code{(flonum-min-denormalized)} in Gauche
(@pxref{Numerical comparison}).
@end defvr

@defvr {Constant} fl-epsilon
[R7RS flonum]
@{@t{scheme.flonum}@}
The same as @code{(flonum-epsilon)} in Gauche
(@pxref{Numerical comparison}).
@end defvr

@defvr {Constant} fl-fast-fl+*
[R7RS flonum]
@{@t{scheme.flonum}@}
If this is @code{#t}, @code{(fl+* x y z)} executes as fast as,
or faster than, @code{(fl+ (fl* x y) z)}.  If not, @code{#f}.
@end defvr

@defvr {Constant} fl-integer-exponent-zero
@defvrx {Constant} fl-integer-exponent-nan
[R7RS flonum]
@{@t{scheme.flonum}@}
These are exact integer values returned in special occasion
from @code{flinteger-exponent}.  The values themselves don't mean
much; they're to be compared with the result of @code{flinteger-exponent}.

If its argument is 0, @code{flinteger-exponent} returns
@code{fl-integer-exponent-zero}.  If its argument is @code{+nan.0},
@code{flinteger-exponent} returns @code{fl-integer-exponent-nan}.
@end defvr

@subheading Constructors

@defun flonum number
[R7RS flonum]
@{@t{scheme.flonum}@}
Returns a flonum that's equal to or (if there's no equivalent flnoum)
the closest to @var{number}.

If @var{number} is not a real number,
@code{+nan.0} is returned.  (Note: srfi-144 recommends it, but
a conformant implementation may signal an error in such case.
Portable code shouldn't rely on this behavior.)
@end defun

@defun fladjacent x y
[R7RS flonum]
@{@t{scheme.flonum}@}
Returns a flonum adjacent to @var{x} in the direction of @var{y}.
If @var{x} = @var{y}, @var{x} is returned.

@example
(fladjacent 1.0 2.0) @result{} 1.0000000000000002
(fladjacent 1.0 0.0) @result{} 0.9999999999999999
@end example
@end defun

@defun flcopysign x y
[R7RS flonum]
@{@t{scheme.flonum}@}
Returns a flonum whose absolute value is @code{(abs x)} and whose
sign is the sign of @var{y}.
@end defun


@defun make-flonum x n
[R7RS flonum]
@{@t{scheme.flonum}@}
Returns a flonum @code{(* @var{x} (expt 2 @var{n}))}.  It is the same
as @code{ldexp} (@pxref{Numerical conversions}).
@end defun

@subheading Accessors

@defun flinteger-fraction x
[R7RS flonum]
@{@t{scheme.flonum}@}
Returns two flnoums, the integral part of @var{x} and the fractional
part of @var{x}.  Same as @code{modf} (@pxref{Numerical conversions}).

If @var{x} is @code{+inf.0}, @code{+inf.0} and @code{0.0} is returned.
If @var{x} is @code{-inf.0}, @code{-inf.0} and @code{-0.0} is returned.
If @var{x} is @code{+nan.0}, @code{+nan.0} and @code{+nan.0} is returned.
(These corner cases are not explicit in srfi-144, but follows
the POSIX specification of @code{modf}.)

@example
(flinteger-fraction fl-pi)
 @result{} 3.0 @r{and} 0.14159265358979312
@end example
@end defun

@defun flexponent x
[R7RS flonum]
@{@t{scheme.flonum}@}
Returns the exponent part of @var{x} as a flnoum.  If @var{x} is
a non-zero finite value, the result is an integer.

If @var{x} is zero, @code{-inf.0} is returned.
If @var{x} is @var{+inf.0} or @code{-inf.0}, @code{+inf.0} is returned.

@example
(flexponent 1.0)    @result{} 0.0
(flexponent 1024.0) @result{} 10.0
(flexponent 0.01)   @result{} -7.0
(flexponent fl-least) @result{} -1074.0
@end example
@end defun

@defun flinteger-exponent x
[R7RS flonum]
@{@t{scheme.flonum}@}
Returns the same as @code{flexponent} but as an exact integer.

If @var{x} is zero, the value of @code{fl-integer-exponent-zero} is
returned.
If @var{x} is @var{+inf.0} or @code{-inf.0}, a large
implementation-dependent exact integer (usually it's so large that
@code{(ldexp 1 (flinteger-exponent +inf.0))} becomes @code{+inf.0})
is returned.
If @var{x} is @code{+nan.0}, the value of
@code{fl-integer-exponent-nan} is returned.
@end defun

@defun flnormalized-fraction-exponent x
[R7RS flonum]
@{@t{scheme.flonum}@}
Returns two values, a normalized mantissa of @var{x} with the same sign
as @var{x} as a flonum, and an exact integer exponent of @var{x}.  If it returns
a value @var{y} and @var{n}, @code{x = (* y (expt 2 n))} and
@code{x = (ldexp y n)}.
This is the same as @code{frexp}
(@pxref{Numerical conversions}).

If @var{x} is non-zero finite value, the first value
falls between 0.5 (inclusive) and 1.0 (exclusive).
The corner cases are not explicit in srfi-144, but Gauche follows
@code{frexp}: If @var{x} is (minus) zero, it returns
(minus) zero and 0; if @var{x} is infinity, it returns
infinity (of the same sign) and 0; if @var{x} is @code{+nan.0},
it returns @code{+nan.0} and 0.

@example
(flnormalized-fraction-exponent 12345.6789)
  @result{} 0.7535204406738282 @r{and} 14
(make-flonum 0.7535204406738282 14)
  @result{} 12345.6789
@end example
@end defun

@defun flsign-bit x
[R7RS flonum]
@{@t{scheme.flonum}@}
Returns 0 if @var{x} is positive or @var{0.0},
and 1 if it is negative (including @code{-0.0}).
@code{(flsign-bit +nan.0)} is implementation-dependent.

There's also @code{flsgn}, if you need sign instead of a bit value.
@end defun

@subheading Predicates

(Note: @code{flonum?} is built-in; @pxref{Numerical predicates}).

@defun fl=? x y z @dots{}
@defunx fl<? x y z @dots{}
@defunx fl>? x y z @dots{}
@defunx fl<=? x y z @dots{}
@defunx fl>=? x y z @dots{}
[R7RS flonum]
@{@t{scheme.flonum}@}
Flonum specific version of numerical comparison predicates
@code{=}, @code{<}, @code{>}, @code{<=} and @code{>=}, respectively.

Currently these are just an alias of the generic numerical comparison
predicates; hence they don't reject when you pass non-flonum
arguments, but doing so is not portable.  These are to give
compilers hints that you are passing flonums so that it can optimize.

Note that @code{-0.0} and @code{0.0} are the same in terms of
these predicates, e.g. @code{(fl<? -0.0 0.0)} is @code{#f}.

If a @code{+nan.0} is passed to any of the arguments, these predicates returns
@code{#f}.
@end defun

@defun flunordered? x y
[R7RS flonum]
@{@t{scheme.flonum}@}
Returns @code{#t} iff at least one of @var{x} or @var{y} is
a @code{+nan.0}.
@end defun

@defun flinteger? x
[R7RS flonum]
@{@t{scheme.flonum}@}
Returns @code{#t} if @var{x} is an integral flonum,
@code{#f} otherwise.
@end defun

@defun flzero? x
@defunx flpositive? x
@defunx flnevative? x
[R7RS flonum]
@{@t{scheme.flonum}@}
Flonum-specific version of @code{zero?}, @code{positive?} and @code{negative?}.
Note that @code{(flnegative? -0.0)} is @code{#f}.
You need @code{flsign-bit} or @code{flsgn} to
distinguish negative zero from zero.
@end defun

@defun flodd? x
@defunx fleven? x
[R7RS flonum]
@{@t{scheme.flonum}@}
Flonum-specific version of @code{odd?} and @code{even?}.  An error is thrown
if @var{x} is not an integer.
@end defun

@defun flfinite? x
@defunx flinfinite? x
@defunx flnan? x
[R7RS flonum]
@{@t{scheme.flonum}@}
Flonum-specific version of @code{finite?}, @code{infinite?} and
@code{nan?} (@pxref{Numerical predicates}).
@end defun

@defun flnormalized? x
@defunx fldenormalized? x
[R7RS flonum]
@{@t{scheme.flonum}@}
Returns @code{#t} iff @var{x} is a normalized/denormalized flonum,
respectively.
@end defun

@subheading Arithmetic

@defun flmax x @dots{}
@defunx flmin x @dots{}
[R7RS flonum]
@{@t{scheme.flonum}@}
Flonum-specific version of @code{min} and @code{max}, except that
these can take no arguments, in which case @code{-inf.0}
and @code{+inf.0} are returned, respectively.

Note that we don't check whether the arguments are flonums or not,
but passing non-flonums are not portable.
@end defun

@defun fl+ x @dots{}
@defunx fl* x @dots{}
[R7RS flonum]
@{@t{scheme.flonum}@}
Flonum-specific version of @code{+.} and @code{*.}
(@pxref{Arithmetics}).

Note that we don't check whether the arguments are flonums or not,
but passing non-flonums is not portable.
@end defun

@defun fl+* x y z
[R7RS flonum]
@{@t{scheme.flonum}@}
Returns @code{(+ (* x y) z)}, but (potentially) faster, and more accurately.
It calls C99 @code{fma} function internally.  ``More accurately'' means
that calculation is done in a single step, with rounding once at the end.

Note: As of release of 0.9.8, MinGW implementation of @code{fma} seems
to produce slightly off value occasionally, as if it is calculated
with the two steps (rounding after multiplication).
@end defun

@defun fl- x y @dots{}
@defunx fl- x y @dots{}
[R7RS flonum]
@{@t{scheme.flonum}@}
Flonum-specific version of @code{-.} and @code{/.}
(@pxref{Arithmetics}).

Note that we don't check whether the arguments are flonums or not,
but passing non-flonums is not portable.
@end defun

@defun flabs x
[R7RS flonum]
@{@t{scheme.flonum}@}
Flonum-specific version of @code{abs}
(@pxref{Arithmetics}).

Note that we don't check whether the argument is a flonum or not,
but passing non-flonum is not portable.
@end defun

@defun flabsdiff x y
[R7RS flonum]
@{@t{scheme.flonum}@}
Returns @code{(abs (- x y))}.

Note that we don't check whether the arguments are flonums or not,
but passing non-flonum is not portable.
@end defun

@defun flposdiff
[R7RS flonum]
@{@t{scheme.flonum}@}
Returns @code{(max (- x y) 0)}.

Note that we don't check whether the arguments are flonums or not,
but passing non-flonum is not portable.
@end defun

@defun flsgn x
[R7RS flonum]
@{@t{scheme.flonum}@}
Returns @code{1.0} if @var{x}'s sign bit is 0 (zero or positive),
@code{-1.0} if it's 1 (negative).  Same as @code{(flcopysign 1.0 x)},
or @code{(if (zero? (flsign-bit x)) 1.0 -1.0)}.
Note that @code{(flsgn 0.0)} is @code{1.0}, while
@code{(flsgn -0.0)} is @code{-1.0}.  The result of
passing @code{+nan.0} is implementation-dependent, reflecting
the sign bit of underlying representation; it returns either @code{1.0} or
@code{-1.0} but you can't count on which.

To extract the sign bit, instead of obtaining a signed flonum,
you can use @code{flsign-bit}.
@end defun

@defun flnumerator x
@defunx fldenominator x
[R7RS flonum]
@{@t{scheme.flonum}@}
Flonum-specific version of @code{numerator} and @code{denominator}
(@pxref{Arithmetics}).

For infinity and zero, denominator is 1.0.

Note that we don't check whether the arguments are flonums or not,
but passing non-flonum is not portable.
@end defun

@defun flfloor x
@defunx flceiling x
@defunx flround x
@defunx fltruncate x
[R7RS flonum]
@{@t{scheme.flonum}@}
Flonum-specific version of @code{floor}, @code{ceiling},
@code{round} and @code{truncate}
(@pxref{Arithmetics}).

Note that we don't check whether the arguments are flonums or not,
but passing non-flonum is not portable.
@end defun

@subheading Exponents and logarithms

@defun flexp x
[R7RS flonum]
@{@t{scheme.flonum}@}
Flonum-specific version of @code{exp} (@pxref{Arithmetics}).
Returns @code{(expt fl-e x)}.
@end defun

@defun flexp2 x
[R7RS flonum]
@{@t{scheme.flonum}@}
Returns @code{(expt 2 x)}
@end defun

@defun flexp-1 x
[R7RS flonum]
@{@t{scheme.flonum}@}
Returns @code{(- 1 (expt fl-e x))}, but is much more accurate
when @var{x} is small.  We call C's @code{expm1} internally.
@end defun

@defun flsquare x
[R7RS flonum]
@{@t{scheme.flonum}@}
Returns @code{(*. x x)}
@end defun

@defun flsqrt x
[R7RS flonum]
@{@t{scheme.flonum}@}
Flonum-specific version of @code{sqrt}.
@end defun

@defun flcbrt x
[R7RS flonum]
@{@t{scheme.flonum}@}
Returns cubic root of a flonum @var{x}.
@end defun

@defun flhypot x y
[R7RS flonum]
@{@t{scheme.flonum}@}
Calculates @code{(sqrt (* x x) (* y y))}, with avoiding
overflow or underflow during the intermediate steps.
@end defun

@defun flexpt x y
[R7RS flonum]
@{@t{scheme.flonum}@}
Flonum-specific version of @code{expt} (@pxref{Arithmetics}).
@end defun

@defun fllog x
[R7RS flonum]
@{@t{scheme.flonum}@}
Flonum-specific version of @code{log} (@pxref{Arithmetics}).
@end defun

@defun fllog1+ x
[R7RS flonum]
@{@t{scheme.flonum}@}
Returns @code{(log (+ x 1))}, but is more accurate than @code{log}
when @var{x} is near zero.
@end defun

@defun fllog2 x
@defunx fllog10 x
[R7RS flonum]
@{@t{scheme.flonum}@}
Returns base-2 and base-10 logarithm of a flonum @var{x}, respectively.
@end defun

@defun make-fllog-base x
[R7RS flonum]
@{@t{scheme.flonum}@}
Returns a procedure that calculates base-@var{x} logarithm.
An error is signalled if @var{x} isn't a real number greater than 1.0.

@example
(define log5 (make-fllog-base 5.0))

(log5 25.0) @result{} 5.0
@end example
@end defun

@subheading Trigonometric functions

@defun flsin x
@defunx flcos x
@defunx fltan x
@defunx flasin x
@defunx flacos x
@defunx flatan x
@defunx flatan y x
@defunx flsinh x
@defunx flcosh x
@defunx fltanh x
@defunx flasinh x
@defunx flacosh x
@defunx flatanh x
[R7RS flonum]
@{@t{scheme.flonum}@}
Flonum-specific version of @code{sin}, @code{cos}, @code{tan},
@code{asin}, @code{acos}, @code{sinh}, @code{cosh}, @code{tanh},
@code{asinh}, @code{acosh}, and @code{atanh}, respectively
(@pxref{Arithmetics}).

Note that @code{flatan} can take one or two arguments; if two arguments
are passed, it calculates @code{(atan (/ y x)}.
@end defun

@subheading Integer division

@defun flquotient x y
[R7RS flonum]
@{@t{scheme.flonum}@}
Returns @code{(fltruncate (fl/ x y))}.

The result is always integer flonum, but @var{x} and @var{y} doesn't
need to be integers.

@example
(flquotient 14.0 4.0)  @result{} 3.0
(flquotient -14.0 4.0) @result{} -3.0
(flquotient 14.0 2.5)  @result{} 5.0
(flquotient -14.2 2.8) @result{} -5.0
@end example
@end defun

@defun flremainder x y
[R7RS flonum]
@{@t{scheme.flonum}@}
Returns @code{(- x (* y (flquotient x y)))}.

@example
(flquotient 14.0 4.0)  @result{} 2.0
(flquotient -14.0 4.0) @result{} -2.0
(flquotient 14.0 2.5)  @result{} 1.5
(flquotient -14.2 2.8) @result{} -0.1999999999999993 ; inexact calculation
@end example
@end defun

@defun flremquo x y
[R7RS flonum]
@{@t{scheme.flonum}@}
Returns two values:
@itemize @bullet
@item
Remainder of @var{x} divided by @var{y}.
(Same as @code{(flremainder x y)}, but we calculate it in different
routines so the result may differ in a few ulp.
@item
Integer quotient of @var{x} divided by @var{y}, modulo 2^@var{n} (@var{n} >= 3), as
an exact integer.  Its sign is the same as @var{x}/@var{y}.
@end itemize

This corresponds to C99's @code{remquo}.

This function is useful to reduce the input for the periodic functions
with symmetries.
@end defun


@subheading Special functions

@defun flgamma x
[R7RS flonum]
@{@t{scheme.flonum}@}
Computes the value of gamma function for a flonum @var{x}.
When @var{x} is integer, it is the same as the factorial of @var{x}-1.

This is same as Gauche's built-in @code{gamma} (@pxref{Arithmetics}).
@end defun

@defun flloggamma x
[R7RS flonum]
@{@t{scheme.flonum}@}
Returns two values, @code{(log (abs (flgamma x)))} and the sign of
@code{(flgamma x)} as 1.0 if it is positive and -1.0 if it is negative.

The first value is calculated by Gauche's built-in @code{lgamma}
(@pxref{Arithmetics}).  It's more accurate than using @code{gamma} then
calling @code{log}.  The second value is @code{+nan.0} when
@var{x} is @code{-inf.0} or @code{+nan.0}.
@end defun

@defun flfirst-bessel n x
[R7RS flonum]
@{@t{scheme.flonum}@}
Returns the @var{n}-th order Bessel function of the first kind.
@end defun

@defun flsecond-bessel n x
[R7RS flonum]
@{@t{scheme.flonum}@}
Returns the @var{n}-th order Bessel function of the second kind.
@end defun

@defun flerf x
[R7RS flonum]
@{@t{scheme.flonum}@}
Returns the error function erf(@var{x}).
@end defun

@defun flerfc x
[R7RS flonum]
@{@t{scheme.flonum}@}
Returns the complementary error function, 1 - erf(@var{x}).
@end defun

@c ----------------------------------------------------------------------
@node R7RS bytevectors, R7RS combinator formatting, R7RS flonum, R7RS large
@subsection @code{scheme.bytevector} - R7RS bytevectors
@c NODE R7RS bytevectors, @code{scheme.bytevector} - R7RS bytevector

@deftp {Module} scheme.bytevector
@mdindex scheme.bytevector
This module is taken from R6RS (@code{(rnrs bytevectors)} (note
that R7RS uses singular form).

The bytevector in this module is u8vector in Gauche.

The following procedures are the same as in @code{gauche.uvector}.
@xref{Bytevector compatibility}, for the explanations.

@example
bytevector?        make-bytevector     bytevector-length
bytevector=?       bytevector-fill!    bytevector-copy
bytevector-u8-ref  bytevector-u8-set!  bytevector-s8-ref
bytevector-s8-set! bytevector->u8-list u8-list->bytevector
@end example

The following procedures are the same as in @code{gauche.unicode}.
@xref{Unicode utilities}, for the explanations.

@example
string->utf8       string->utf16       string->utf32
utf8->string       utf16->string       utf32->string
@end example

This module exports @code{bytevector-copy!}, which takes arguments
in different order from
R7RS base's (and @code{gauche.uvector}'s) @code{bytevector-copy!}.
It is the same as @code{bytevector-copy!-r6} in @code{gauche.uvector}
(@pxref{Bytevector compatibility}).
@end deftp

@defmac endianness symbol
[R7RS bytevector]
If @var{symbol} is a valid endianness symbol, returns it.  Otherwise,
raise an error at macro-expansion time.   Useful to catch an error early,
and explicitly indicates you mean endianness.

Valid symbols are listed in @ref{Endianness}.  Only @code{big} and
@code{little} are portable.
@end defmac

@defun native-endianness
[R7RS bytevector]
Returns a symbol representing the native endianness.
Same as Gauche's built-in @code{native-endian} (@pxref{Endianness}).
@end defun


@defun bytevector-uint-ref bv pos endian size
@defunx bytevector-sint-ref bv pos endian size
[R7RS bytevector]
Read @var{size} octets from u8vector @var{bv}, starting from @var{pos}-th
octet, as an unsigned or signed integer, respectively.
Similar to @code{binary.io}'s @code{get-uint} and @code{get-sint},
with different argument order.

They accept all valid endianness symbols in Gauche, but
the portable code should only use @code{big} and @code{little} for
@var{endian} argument.
@end defun

@defun bytevector-uint-set! bv pos val endian size
@defunx bytevector-sint-set! bv pos val endian size
[R7RS bytevector]
Store an unsigned or signed integer @var{val} into an u8vector
@var{bv} starting from @var{pos}-th octet, for @var{size} octets,
respectively.
Similar to @code{binary.io}'s @code{put-uint!} and @code{put-sint!},
with different argument order.

They accept all valid endianness symbols in Gauche, but
the portable code should only use @code{big} and @var{little} for
@var{endian} argument.
@end defun

@defun bytevector->uint-list bv endian size
@defunx bytevector->sint-list bv endian size
[R7RS bytevector]
Convert the u8vector @var{bv} to a list of unsigned or signed integer,
each of which is represented by @var{size}-octets.
The length of @var{bv} must be a multiple of @var{size}; otherwise
an error is signaled.

They accept all valid endianness symbols in Gauche, but
the portable code should only use @code{big} and @var{little} for
@var{endian} argument.
@end defun

@defun uint-list->bytevector lis endian size
@defunx sint-list->bytevector lis endian size
[R7RS bytevector]
@var{Lis} must be a list of unsigned or signed integers, respectively.
Creates a u8vector of length @code{(* size (length lis))}, and
stores each integer into the u8vector using @var{size} octets,
and returns the u8vector.

They accept all valid endianness symbols in Gauche, but
the portable code should only use @code{big} and @var{little} for
@var{endian} argument.
@end defun

@defun bytevector-u16-ref bv k endian
@defunx bytevector-s16-ref bv k endian
@defunx bytevector-u32-ref bv k endian
@defunx bytevector-s32-ref bv k endian
@defunx bytevector-u64-ref bv k endian
@defunx bytevector-s64-ref bv k endian
@defunx bytevector-ieee-single-ref bv k endian
@defunx bytevector-ieee-double-ref bv k endian
[R7RS bytevector]
Retrieve a numerical value from a u8vector @var{bv} starting at
index @var{k}, using @var{endian}.  These are the same as
@code{get-u16}, @dots{} in @code{binary.io}, except that
all arguments are mandatory.  (Note that
@code{ieee-single} and @code{ieee-double} corresponds to @code{f32} and
@code{f64}).  @xref{Binary I/O}), for the details.

They accept all valid endianness symbols in Gauche, but
the portable code should only use @code{big} and @var{little} for
@var{endian} argument.
@end defun

@defun bytevector-u16-native-ref bv k
@defunx bytevector-s16-native-ref bv k
@defunx bytevector-u32-native-ref bv k
@defunx bytevector-s32-native-ref bv k
@defunx bytevector-u64-native-ref bv k
@defunx bytevector-s64-native-ref bv k
@defunx bytevector-ieee-single-native-ref bv k
@defunx bytevector-ieee-double-native-ref bv k
[R7RS bytevector]
Like @code{bytevector-u16-ref} etc., but uses native endianness.
@end defun

@defun bytevector-u16-set! bv k val endian
@defunx bytevector-s16-set! bv k val endian
@defunx bytevector-u32-set! bv k val endian
@defunx bytevector-s32-set! bv k val endian
@defunx bytevector-u64-set! bv k val endian
@defunx bytevector-s64-set! bv k val endian
@defunx bytevector-ieee-single-set! bv k val endian
@defunx bytevector-ieee-double-set! bv k val endian
[R7RS bytevector]
Store a numerical value into a u8vector @var{bv} starting at
index @var{k}, using @var{endian}.  These are the same as
@code{put-u16!}, @dots{} in @code{binary.io}, except that
all arguments are mandatory.  (Note that
@code{ieee-single} and @code{ieee-double} corresponds to @code{f32} and
@code{f64}).  @xref{Binary I/O}), for the details.

They accept all valid endianness symbols in Gauche, but
the portable code should only use @code{big} and @var{little} for
@var{endian} argument.
@end defun

@defun bytevector-u16-native-set! bv k val
@defunx bytevector-s16-native-set! bv k val
@defunx bytevector-u32-native-set! bv k val
@defunx bytevector-s32-native-set! bv k val
@defunx bytevector-u64-native-set! bv k val
@defunx bytevector-s64-native-set! bv k val
@defunx bytevector-ieee-single-native-set! bv k val
@defunx bytevector-ieee-double-native-set! bv k val
[R7RS bytevector]
Like @code{bytevector-u16-set!} etc., but uses native endianness.
@end defun

@node R7RS combinator formatting,  , R7RS bytevectors, R7RS large
@subsection @code{scheme.show} - R7RS combinator formatting
@c NODE R7RS combinator formatting, @code{scheme.show} - R7RS combinator formatting

@subsubheading Module structure
@deftp {Module} scheme.show
@mdindex scheme.show
Exports bindings of R7RS @code{(scheme show)} library.
From R7RS programs, those bindings are available by
@code{(import (scheme show))}.

scheme.show is a combination of submodules scheme.show.base,
scheme.show.color, scheme.show.columnar and scheme.show.unicode.
@end deftp

@deftp {Module} scheme.show.base
Exports bindings of R7RS @code{(scheme show base)} library.
From R7RS programs, those bindings are available by
@code{(import (scheme show base))}.

This contains most combinator formatting procedures.
@end deftp

@deftp {Module} scheme.show.color
Exports bindings of R7RS @code{(scheme show color)} library.
From R7RS programs, those bindings are available by
@code{(import (scheme show color))}.

This contains formatters to color text using ANSI escape codes.
@end deftp

@deftp {Module} scheme.show.columnar
Exports bindings of R7RS @code{(scheme show columnar)} library.
From R7RS programs, those bindings are available by
@code{(import (scheme show columnar))}.

This contains formatters to help format in columns.
@end deftp

@deftp {Module} scheme.show.unicode
Exports bindings of R7RS @code{(scheme show unicode)} library.
From R7RS programs, those bindings are available by
@code{(import (scheme show unicode))}.
@end deftp

@subsubheading Usage

Combinator formatting provides a functionality similar to
@code{format} from SRFI-28. But instead of writing a template string,
you can use S-expressions, which are called ``formatters''. It's also
extensible.

The two main concepts in combinator formatting are formatters and
states. Formatters are procedures that specify how or what you want to
output. Formatters can be composed to produce complex format. Normal
types are also accepted where a procedure takes a formatter, they are
formatted with @code{displayed}.

Format states let us customize control formatting, for example how
many precision digits, what character for padding @dots{}. Format
states can be changed locally with @code{with} or @code{with!}.

The entry point to combinator formatting is @code{show}, which takes a
sequence of formatters and outputs to a port or returns a string.

@defun show @var{output-dest} @var{fmt} @dots{}
[R7RS show base]
@{@t{scheme.show.base}@}
This is the main entry for combinator formatting. All formatters are
processed to produce a string to @var{output-dest} if it's a port. If
@var{output-dest} is @code{#f}, the output string is returned.
@code{show} return value is otherwise undefined. Non-formatters are
also accepted and will be wrapped in @code{displayed} formatter.

@example
(show #f "π = " (with ((precision 2)) (acos -1)) nl)
@result{} "π = 3.14\n"
@end example
@end defun

@subsubheading Formatting Objects

@defun displayed @var{obj}
[R7RS show base]
@{@t{scheme.show.base}@}
The formatter that formats the object @var{obj} the
same as @code{display}. This is the default formatter when you pass an
object to @code{show}.
@end defun

@defun written @var{obj}
[R7RS show base]
@{@t{scheme.show.base}@}
The formatter that formats the object @var{obj} the same as
@code{write}. Formatting settings @code{numeric} and @code{precision}
are respected for relevant number types as long as the result can
still be passed to @code{read}.
@end defun

@defun written-simply @var{obj}
[R7RS show base]
@{@t{scheme.show.base}@}
Similar to @code{written} but does not handle shared structures.
@end defun

@defun pretty @var{obj}
[R7RS show base]
@{@t{scheme.show.base}@}
Pretty prints an object.
@end defun

@defun pretty-simply @var{obj}
[R7RS show base]
@{@t{scheme.show.base}@}
Similar to @code{pretty} but does not handle shared structures.
@end defun

@defun escaped @var{str} [@var{quote-ch} @var{esc-ch} @var{renamer}]
[R7RS show base]
@{@t{scheme.show.base}@}
Prints a string, adding @var{esc-ch} (@code{#\\} by default) in front
of all @var{quote-ch} (@code{#\"} by default).

If @var{esc-ch} is @code{#f}, escape all @var{quote-ch} by doubling
it.

If @var{renamer} is specified, it's a procedure that takes one
character and returns another character or @code{#f}. It serves two
purposes: to allow quoting more than one character and to replace them
with something else. If the procedure returns @code{#f}, the character
in question is not escaped. Otherwise the character is escaped and
replaced with a new one.

@var{esc-ch} could also be a string, but this is Gauche specific behavior.

@example
(show #t (escaped "hello \"world\"")) @result{} hello \"world\"
(show #t (escaped "hello \"world\"" #\l)) @result{} he\l\lo "world"
(show #t (escaped "hello \"world\"" #\l #\x)) @result{} hexlxlo "worxld"
(show #t (escaped "hello \"world\""
                  #\e #f
                  (lambda (x) (if (char=? x #\o) #\O #f))))
@result{} heelleO "weOrld"
@end example
@end defun

@defun maybe-escaped @var{str} @var{pred} [@var{quote-ch} @var{esc-ch} @var{renamer}]
[R7RS show base]
@{@t{scheme.show.base}@}
Determines if @var{str} needs to be escaped or not. If true, the
string is wrapped with @var{quote-ch}. The original string is escaped
with @code{escaped}.

The string needs to be escaped if any @var{quote-ch} or @var{esc-ch}
is present, or any character that makes @var{pred} return @code{#t}.

@example
(show #t (maybe-escaped "helloworld" char-whitespace?)) @result{} helloworld
(show #t (maybe-escaped "hello world" char-whitespace?)) @result{} "hello world"
(show #t (maybe-escaped "hello \"world\"" char-whitespace? #\")) @result{} "hello \"world\""
@end example

@end defun

@subsubheading Formatting Numbers

@defun numeric @var{num} [@var{radix} @var{precision} @var{sign-rule} @var{comma-rule} @var{comma-sep} @var{decimal-sep}]
[R7RS show base]
@{@t{scheme.show.base}@}
Formats a number. The default values are from state variables below.

@example
(show #f (numeric 1000)) @result{} "1000"
(show #f (numeric 1000 8)) @result{} "1750"
(show #f (numeric 1000 8 2)) @result{} "1750.00"
(show #f (numeric 1000 8 2 #t)) @result{} "+1750.00"
(show #f (numeric -1000 8 2 (cons "(" ")"))) @result{} "(1750.00)"
(show #f (numeric 1000 8 2 #t 2)) @result{} "+17,50.00"
(show #f (numeric 1000 8 2 #t 2 #\')) @result{} "+17'50.00"
(show #f (numeric 1000 8 2 #t 2 #\' #\:)) @result{} "+17'50:00"
@end example

@end defun

@defun numeric/comma @var{num} [@var{radix} @var{precision} @var{sign-rule}]
[R7RS show base]
@{@t{scheme.show.base}@}
Formats a number with default @var{comma-rule} 3. See @code{numeric}
for details.
@example
(show #f (numeric/comma 1000)) @result{} "1,000"
(show #f (with ((comma-sep #\.)) (numeric/comma 1000))) @result{} "1.000"
@end example

@end defun

@defun numeric/si @var{num} [@var{base} @var{separator}]
[R7RS show base]
@{@t{scheme.show.base}@}
Formats a numeric with SI suffix. The default base is 1024 and uses
suffix names like Ki, Mi, Gi@dots{}. Other bases (e.g. 1000) use
suffixes k, M, G@dots{}. If @var{separator} is specified, it's
inserted between the number and suffix.

@example
(show #f (numeric/si 1024)) @result{} "1Ki"
(show #f (numeric/si 200000 1000)) @result{} "200k"
(show #f (numeric/si 1024 1024 #\/)) @result{} "1/Ki"
@end example

@end defun

@defun numeric/fitted @var{width} @var{n} [@var{arg} @dots{}]
[R7RS show base]
@{@t{scheme.show.base}@}
Like @code{numeric} but if the result does not fit in @var{width}
characters with current precision, outputs a string of hashes instead
of the truncated and incorrect number.

@example
(show #f (with ((precision 2)) (numeric/fitted 4 1.25))) @result{} "1.25"
(show #f (with ((precision 2)) (numeric/fitted 4 12.345))) @result{} "#.##"
@end example

@end defun

@subsubheading Formatting Space

@defvar nl
Outputs a newline.

@example
(show #f nl) @result{} "\n"
@end example
@end defvar

@defvar fl
Short for ``fresh line'', make sures the following output is at the
beginning of the line.

@example
(show #f fl) @result{} ""
(show #f "aaa" fl) @result{} "aaa\n"
@end example
@end defvar

@defvar nothing
Outputs nothing. This is useful in combinators as default no-op in
conditionals.
@end defvar

@defun space-to @var{column}
[R7RS show base]
@{@t{scheme.show.base}@}
Appends @var{pad-char} to reach the given @var{column}.

@example
(show #f "abcdef" (space-to 3) "a") @result{} "   a"
(show #f "abcdef" (space-to 3) "a") @result{} "abcdefa"
@end example
@end defun

@defun tab-to [@var{tab-width}]
[R7RS show base]
@{@t{scheme.show.base}@}
Outputs @var{pad-char} to reach the next tab stop.
@end defun

@subsubheading Concatenation

@defun each @var{fmt} @dots{}
[R7RS show base]
@{@t{scheme.show.base}@}
@end defun

@defun each-in-list @var{list-of-fmts}
[R7RS show base]
@{@t{scheme.show.base}@}
@end defun

@defun joined @var{mapper} @var{list} [@var{sep}]
[R7RS show base]
@{@t{scheme.show.base}@}
Formats each element in @var{list} with @var{mapper} and inserts
@var{sep} in between. @var{sep} by default is an empty string, but it
could be any string or formatter.

@example
(show #f (joined displayed (list "a" "b") " ")) @result{} "a b"
(show #f (joined displayed (list "a" "b") nl)) @result{} "a\nb"
@end example
@end defun

@defun joined/prefix @var{mapper} @var{list} [@var{sep}]
[R7RS show base]
@{@t{scheme.show.base}@}
Similar to @code{joined} except the separator is inserted before
every element.

@example
(show #f (joined/prefix displayed '(usr local bin) "/")) @result{} "/usr/local/bin"
@end example
@end defun

@defun joined/suffix @var{mapper} @var{list} [@var{sep}]
[R7RS show base]
@{@t{scheme.show.base}@}
Similar to @code{joined} except the separator is inserted after every
element.

@example
(show #f (joined/suffix displayed '(1 2 3) nl)) @result{} "1\n2\n3\n"
@end example
@end defun

@defun joined/last @var{mapper} @var{last-mapper} @var{list} [@var{sep}]
[R7RS show base]
@{@t{scheme.show.base}@}
Similar to @code{joined} but @var{last-mapper} is used on the last
element of @var{list} instead.

@example
(show #f (joined/last displayed
                      (lambda (last) (each "and " last))
                      '(lions tigers bears)
                      ", "))
@result{} "lions, tigers, and bears"
@end example
@end defun

@defun joined/dot @var{mapper} @var{dot-mapper} @var{list} [@var{sep}]
[R7RS show base]
@{@t{scheme.show.base}@}
Similar to @code{joined} but if @var{list} is a dotted list, then
formats the dotted value with @var{dot-mapper} instead.
@end defun

@defun joined/range @var{mapper} @var{start} [@var{end} @var{sep}]
[R7RS show base]
@{@t{scheme.show.base}@}
@end defun

@subsubheading Padding and Trimming

@defun padded @var{width} @var{fmt} @dots{}
[R7RS show base]
@{@t{scheme.show.base}@}
Pads the output of @var{fmt}@dots{} on the left side with
@var{pad-char} if it's shorter than @var{width} characters.

@example
(show #f (padded 10 "abc")) @result{} "       abc"
(show #f (with ((pad-char #\-)) (padded 10 "abc"))) @result{} "-------abc"
@end example
@end defun

@defun padded/right @var{width} @var{fmt} @dots{}
[R7RS show base]
@{@t{scheme.show.base}@}
Similar to @code{padded} but except padding is on the right side instead.
@end defun

@defun padded/both @var{width} @var{fmt} @dots{}
[R7RS show base]
@{@t{scheme.show.base}@}
Similar to @code{padded} but except padding is on both sides, keeping
the @var{fmt} output at the center.
@end defun

@defun trimmed @var{width} @var{fmt} @dots{}
[R7RS show base]
@{@t{scheme.show.base}@}
Trims the output of @var{fmt}@dots{} on the left so that the length is
@var{width} characters or less. If @var{ellipsis} state variable is
defined, it will be put on the left to denote trimming.

@example
(show #f (trimmed 5 "hello world")) @result{} "world"
(show #f (with ((ellipsis "..")) (trimmed 5 "hello world"))) @result{} "..rld"
@end example
@end defun

@defun trimmed/right @var{width} @var{fmt} @dots{}
[R7RS show base]
@{@t{scheme.show.base}@}
Similar to @code{trimmed} but the trimming is on the right.
@end defun

@defun trimmed/both @var{width} @var{fmt} @dots{}
[R7RS show base]
@{@t{scheme.show.base}@}
Similar to @code{trimmed} but the trimming is on both sides, keeping
the center of the output.
@end defun

@defun trimmed/lazy @var{width} @var{fmt} @dots{}
[R7RS show base]
@{@t{scheme.show.base}@}
A variant of @code{trimmed} which generates each @code{fmt} in left to
right order, and truncates and terminates immediately if more than
@code{width} characters are generated. Thus this is safe to use with
an infinite amount of output, e.g. from @code{written-simply} on an
infinite list.
@end defun

@defun fitted width @var{fmt} @dots{}
[R7RS show base]
@{@t{scheme.show.base}@}
A combination of @code{padded} and @code{trimmed}, ensures the output
width is exactly @var{width}, truncating if it goes over and padding
if it goes under.
@end defun

@defun fitted/right @var{width} @var{fmt} @dots{}
[R7RS show base]
@{@t{scheme.show.base}@}
A combination of @code{padded/right} and @code{trimmed/right}, ensures
the output width is exactly @var{width}, truncating if it goes over
and padding if it goes under.
@end defun

@defun fitted/both @var{width} @var{fmt} @dots{}
[R7RS show base]
@{@t{scheme.show.base}@}
A combination of @code{padded/both} and @code{trimmed/both}, ensures
the output width is exactly @var{width}, truncating if it goes over
and padding if it goes under.
@end defun

@subsubheading Columnar Formatting

@defun columnar @var{column} @dots{}
[R7RS show columnar]
@{@t{scheme.show.columnar}@}
@end defun

@defun tabular @var{column} @dots{}
[R7RS show columnar]
@{@t{scheme.show.columnar}@}
@end defun

@defun wrapped @var{fmt} @dots{}
[R7RS show columnar]
@{@t{scheme.show.columnar}@}
@end defun

@defun wrapped/list @var{list-of-strings}
[R7RS show columnar]
@{@t{scheme.show.columnar}@}
@end defun

@defun wrapped/char @var{fmt} @dots{}
[R7RS show columnar]
@{@t{scheme.show.columnar}@}
@end defun

@defun justified @var{format} @dots{}
[R7RS show columnar]
@{@t{scheme.show.columnar}@}
@end defun

@defun from-file @var{pathname}
[R7RS show columnar]
@{@t{scheme.show.columnar}@}
@end defun

@defun line-numbers [@var{start}]
[R7RS show columnar]
@{@t{scheme.show.columnar}@}
@end defun

@subsubheading Colors

@defun as-red @var{fmt} @dots{}
@defunx as-blue @var{fmt} @dots{}
@defunx as-green @var{fmt} @dots{}
@defunx as-cyan @var{fmt} @dots{}
@defunx as-yellow @var{fmt} @dots{}
@defunx as-magenta @var{fmt} @dots{}
@defunx as-white @var{fmt} @dots{}
@defunx as-black @var{fmt} @dots{}
@defunx as-bold @var{fmt} @dots{}
@defunx as-underline @var{fmt} @dots{}
[R7RS show color]
@{@t{scheme.show.color}@}
Outputs the ANSI escape code to make all @var{fmt}@dots{} a given
color or style.
@end defun

@subsubheading Unicode

@defun as-unicode @var{fmt} @dots{}
[R7RS show unicode]
@{@t{scheme.show.unicode}@}
@end defun

@defun unicode-terminal-width @var{str}
[R7RS show unicode]
@{@t{scheme.show.unicode}@}
@end defun

@subsubheading Higher Order Formatters and State

@defun fn ((@var{id} @var{state-var}) @dots{}) @var{expr} @dots{} @var{fmt}
[R7RS show base]
@{@t{scheme.show.base}@}
This is short for ``function'' and the analog to @code{lambda}. It
returns a formatter which on application evaluates each @var{expr} and
@var{fmt} in left-to-right order, in a lexical environment extended
with each identifier id bound to the current value of the state
variable named by the symbol @var{state-var}. The result of the
@var{fmt} is then applied as a formatter.

As a convenience, any @code{(id state-var)} list may be abbreviated as
simply @code{id}, indicating @var{id} is bound to the state variable
of the same (symbol) name.
@end defun

@defun with ((@var{state-var} @var{value}) @dots{}) @var{fmt} @dots{}
[R7RS show base]
@{@t{scheme.show.base}@}
This is the analog of @code{let}. It temporarily binds specified state
variables with new values for @var{fmt} @dots{}.
@end defun

@defun with! (@var{state-var} @var{value}) @var{fmt} @dots{}
[R7RS show base]
@{@t{scheme.show.base}@}
Similar to @code{with} but the value updates persist even after
@code{with!}.
@end defun

@defun forked @var{fmt1} @var{fmt2}
[R7RS show base]
@{@t{scheme.show.base}@}
Calls @var{fmt1} on (a conceptual copy of) the current state, then
@var{fmt2} on the same original state as though @var{fmt1} had not
been called (i.e. any potential state mutation by @var{fmt1} does not
affect @var{fmt2}).
@end defun

@defun call-with-output @var{formatter} @var{mapper}
[R7RS show base]
@{@t{scheme.show.base}@}
A utility, calls formatter on a copy of the current state (as with
@code{forked}), accumulating the results into a string. Then calls the
formatter resulting from @code{(mapper result-string)} on the original
state.
@end defun

@subsubheading Standard State Variables

@defvar port
The current port output is written into, could be overriden to capture
intermediate output.
@end defvar

@defvar row
The current row of the output.
@end defvar

@defvar col
The current column of the output.
@end defvar

@defvar width
The current line width, used for wrapping, pretty printing and
columnar formatting.
@end defvar

@defvar output
The underlying standard formatter for writing a single string.

The default value outputs the string while tracking the current row
and col. This can be overridden both to capture intermediate output
and perform transformations on strings before outputting, but should
generally wrap the existing output to preserve expected behavior.
@end defvar

@defvar writer
The mapper for automatic formatting of non-string/char values in
top-level show, each and other formatters. Default value is
implementation-defined.
@end defvar

@defvar string-width
A function of a single string. It returns the length in columns of
that string, used by the default output.
@end defvar

@defvar pad-char
The character used for by padding formatters, @code{#\space} by default
@end defvar

@defvar ellipsis
The string used when truncating as described in @code{trimmed}.
@end defvar

@defvar radix
The radix for numeric output, 10 by default. Valid values are from 2
to 36.
@end defvar

@defvar precision
The number of digits written after the decimal point for numeric
output. The value is rounded if the numeric value written out requires
more digits than requested precision. See the SRFI for exact rounding
behavior.
@end defvar

@defvar sign-rule
If @code{#t}, always output the plus sign @code{+} for positive
numbers. If @var{sign-rule} is a par of two strings, negative numbers
are printed with the strings wrapped around (and no preceding negative
sign @code{-}).
@end defvar

@defvar comma-rule
The number of digits between commans, specified by @var{comma-sep}.
@end defvar

@defvar comma-sep
The character used as comma for numeric formatting, @code{#\,} by
default.
@end defvar

@defvar decimal-sep
The character to use for decimals in numeric formatting. The default
depends on @var{comma-sep}, if it's @code{#\.}, then the decimal
separator is @code{#\,}, otherwise it's @code{#\.}
@end defvar

@defvar decimal-align
@end defvar

@defvar word-separator?
@end defvar


@c Local variables:
@c mode: texinfo
@c coding: utf-8
@c end:
@node Library modules - SRFIs, Library modules - Utilities, Library modules - R7RS standard libraries, Top
@chapter Library modules - SRFIs
@c NODE ライブラリモジュール - SRFI

This chapter lists modules that provides SRFI functionalities.
Note that some of SRFI features are built in Gauche core and
not listed here.  The SRFIs that have been adopted to R7RS-large
are described in @ref{Library modules - R7RS standard libraries}.

@xref{Standard conformance}, for entire list
of supported SRFIs.

(Even if a srfi is not listed here, you can still say
@code{(use srfi-N)} or @code{(import (srfi N))}, as far as
srfi N is supported by Gauche.)

@c ----------------------------------------------------------------------
@menu
* SRFIs that have become R7RS-large::
* Homogeneous vectors::         srfi-4
* A compatible let form with signatures and rest arguments::  srfi-5
* Feature-based program configuration language::  srfi-7
* String library::              srfi-13
* Time data types and procedures::  srfi-19
* Sources of random bits::      srfi-27
* Localization::                srfi-29
* A program argument processor::  srfi-37
* Eager comprehensions::        srfi-42
* Vector library (Legacy)::     srfi-43
* Requiring extensions::        srfi-55
* Integers as bits::            srfi-60
* A Scheme API for test suites::  srfi-64
* Octet vectors::               srfi-66
* Basic hash tables::           srfi-69
* Octet-addressed binary blocks::  srfi-74
* Lightweight testing::         srfi-78
* Accessing environment variables::  srfi-98
* Basic socket interface::      srfi-106
* Purely functional random-access pairs and lists::  srfi-101
* Portable runtime environment inquiry::  srfi-112
* Comparators::                 srfi-114
* Simple adjustable-size strings::  srfi-118
* Cursor-based string library::  srfi-130
* String library (reduced)::    srfi-152
* First-class dynamic extents::  srfi-154
* Homogeneous numeric vector libraries::  srfi-160
* Comparator sublibrary::       srfi-162
* POSIX API::                   srfi-170
* Hooks (srfi)::                srfi-173
* POSIX timespecs::             srfi-174
* ASCII character library::     srfi-175
* Bitvector library::           srfi-178
* JSON::                        srfi-180
* Custom ports::                srfi-181
* Linear adjustable-length strings::  srfi-185
* Maybe and Either optional container types::  srfi-189
* Port positioning::            srfi-192
* Command line::                srfi-193
@end menu


@node SRFIs that have become R7RS-large, Homogeneous vectors, Library modules - SRFIs, Library modules - SRFIs
@section SRFIs that have become R7RS-large
@c NODE R7RS-largeになったSRFI

Here's a list of SRFIs that have become a part of R7RS-large,
ordered by SRFI numbers.

@table @asis
@item srfi-1 List library
@code{scheme.list} (@pxref{R7RS lists}).
@item srfi-14 Character-set library
@code{scheme.char-set} (@pxref{R7RS character sets}).
@item srfi-41 Streams
@code{scheme.stream} (@pxref{R7RS stream}).
@item srfi-101 Purely functional random-access pairs and lists
@code{scheme.rlist} (@pxref{R7RS random-access lists}).
@item srfi-111 Boxes
@code{scheme.box} (@pxref{R7RS boxes}).
@item srfi-113 Sets and bags
@code{scheme.set} (@pxref{R7RS sets}).
@item srfi-115 Scheme Regular Expressions
@code{scheme.regex} (@pxref{R7RS regular expressions}).
@item srfi-116 Immutable list library
@code{scheme.ilist}
@item srfi-117 Queues based on lists
@code{scheme.list-queue} (@pxref{R7RS list queues}).
@item srfi-121 Generators
@code{scheme.generator} (@pxref{R7RS generators}).
@item srfi-124 Ephemerons
@code{scheme.ephemeron} (@pxref{R7RS ephemerons}).
@item srfi-125 Intermediate hash tables
@code{scheme.hash-table} (@pxref{R7RS hash tables}).
@item srfi-127 Lazy sequences
@code{scheme.lseq} (@pxref{R7RS lazy sequences}).
@item srfi-128 Comparators (reduced)
@code{scheme.comparator} (@pxref{R7RS comparators}).
@item srfi-132 Sort library
@code{scheme.sort} (@pxref{R7RS sort}).
@item srfi-133 Vector library
@code{scheme.vector} (@pxref{R7RS vectors}).
@item srfi-134 Immutable deques
@code{scheme.ideque} (@pxref{R7RS immutable deques}).
@item srfi-135 Immutable texts
@code{scheme.text} (@pxref{R7RS immutable texts}).
@item srfi-141 Integer division
@code{scheme.division} (@pxref{R7RS integer division}).
@item srfi-143 Fixnums
@code{scheme.fixnum} (@pxref{R7RS fixnum}).
@item srfi-144 Flonums
@code{scheme.flonum} (@pxref{R7RS flonum}).
@item srfi-146 Mappings
@code{scheme.mapping}, @code{scheme.mapping.hash} (@pxref{R7RS mappings}).
@item srfi-151 Bitwise operations
@code{scheme.bitwise} (@pxref{R7RS bitwise operations}).
@item srfi-158 Generators and accumulators
@code{scheme.generator} (@pxref{R7RS generators}).
@item srfi-159 Combinator formatting
@code{scheme.show}
@item srfi-160 Homogeneous numeric vector libraries
@code{scheme.vector.@@} (@pxref{R7RS uniform vectors}).
@end table


@c ----------------------------------------------------------------------
@node Homogeneous vectors, A compatible let form with signatures and rest arguments, SRFIs that have become R7RS-large, Library modules - SRFIs
@section @code{srfi-4} - Homogeneous vectors
@c NODE 単一型のベクタ, @code{srfi-4} - 単一型のベクタ

@deftp {Module} srfi-4
@mdindex srfi-4
SRFI-4 is now implemented in @code{gauche.uvector} module
@xref{Uniform vectors}.
This module simply inherits @code{gauche.uvector} for backward-compatibility.
@end deftp

@c ----------------------------------------------------------------------
@node A compatible let form with signatures and rest arguments, Feature-based program configuration language, Homogeneous vectors, Library modules - SRFIs
@section @code{srfi-5} - A compatible let form with signatures and rest arguments
@c NODE シグネチャとrest引数に互換性のあるlet形式, @code{srfi-5} - シグネチャとrest引数に互換性のあるlet形式

@deftp {Module} srfi-5
@mdindex srfi-5
This module provides srfi-5's extended @code{let} syntax.
@end deftp

@defmac let ((var val) @dots{} [. (rest val @dots{})]) body @dots{}
@defmacx let name ((var val) @dots{} [. (rest val @dots{})]) body @dots{}
@defmacx let (name (var val) @dots{} [. (rest val @dots{})]) body @dots{}
[SRFI-5]
@{@t{srfi-5}@}
The @code{let} syntax is extended in two ways.

@itemize @bullet
@item
The extended @code{let} syntax accepts the @var{name} identifier (for
named let syntax) within the list of bindings (as in the third
syntax above).
@item
The extended @code{let} syntax accepts the rest parameter binding
which works like the rest parameter in the @code{lambda} syntax.
@end itemize

See SRFI-5 document for rationale of this extension.
@end defmac

@c ----------------------------------------------------------------------
@node Feature-based program configuration language, String library, A compatible let form with signatures and rest arguments, Library modules - SRFIs
@section @code{srfi-7} - Feature-based program configuration language
@c NODE 機能ベースプログラム設定言語, @code{srfi-7} - 機能ベースプログラム設定言語

@deftp {Module} srfi-7
@mdindex srfi-7
This module provides a program configuration metalanguage
(@code{program} form) defined in srfi-7.
Gauche autoloads srfi-7 module, so you don't need
to say @code{(use srfi-7)} explicitly.
Note that the @code{program} form isn't necessary to be a
Scheme expression.  Srfi-7 allows an implementation to preprocess
the @code{program} form to produce a Scheme program, then
executes it with different means.
Gauche implements @code{program} form as a macro, so it can
evaluates the form directly.  Nonetheless, it doesn't make sense
to mix @code{program} form and other forms in one file,
or expecting a return value of @code{program} form.
A typical usage of @code{program} form is to prepare a single
file which just contains @code{program} form.  (It can load
other files using @code{files} clause (see below) within the
@code{program} form.)   To execute such a program file in Gauche,
you can just load it.
@end deftp

@deffn {Configuration Language} program program-clause program-clause2 @dots{}
[SRFI-7]
@{@t{srfi-7}@}
This is a configuration language to structure a Scheme program,
based on availability of the features.

A Scheme program is constructed from the @code{program} form.
Gauche evaluates the constructed Scheme program on-the-fly.

Each @var{program-clause} needs to be one of the "Program Clauses" below.
@end deffn

@deffn {Program Clause} requires feature-id feature-id2 @dots{}
[SRFI-7]
The @var{feature-id}'s are the same as @code{srfi-0}'s
(@pxref{Feature conditional}).
It tells that the following code requires these @var{feature-id}'s.

If a feature-id which is not supported in Gauche is given,
an error is signaled.
@end deffn

@deffn {Program Clause} files filename @dots{}
[SRFI-7]
Inserts the content of the @var{filename}s into a program.
In Gauche, this clause just causes @var{filename}s to be loaded
into the current module.
@end deffn

@deffn {Program Clause} code scheme-expression @dots{}
[SRFI-7]
The @var{scheme-expression}s are inserted into a program.
@end deffn

@deffn {Program Clause} feature-cond clause clause2 @dots{}
[SRFI-7]
@var{Clause} is a following form:
@example
(@var{requirement} @var{program-clause} @var{program-clause2} @dots{})
@end example

Where @var{requirement} should be one of the following:
@itemize @bullet
@item
@var{feature-id}
@item
@code{(and @var{requirement} @dots{})}
@item
@code{(or @var{requirement} @dots{})}
@item
@code{(not @var{requirement})}
@end itemize

The @var{requirement} of the last @var{clause} may be @code{else}.

Gauche checks each @var{requirement} one by one, and if it finds
a fulfilled @var{requirement}, inserts the @var{program-clause}s
in that @var{clause} into the program.
@end deffn

@c ----------------------------------------------------------------------
@node String library, Time data types and procedures, Feature-based program configuration language, Library modules - SRFIs
@section @code{srfi-13} - String library
@c NODE 文字列ライブラリ, @code{srfi-13} - 文字列ライブラリ

@deftp {Module} srfi-13
@mdindex srfi-13
Defines a large set of string-related functions.
In Gauche, those functions are splitted to number of files
and the form @code{(use srfi-13)} merely sets up autoloading of
those files.  So it is not likely to slow down the script startup.
See SRFI-13 (@uref{https://srfi.schemers.org/srfi-13/srfi-13.html})
for the detailed specification and discussion of design issues.
This manual serves as a reference of function API.
Some SRFI-13 functions are Gauche built-in and not listed here.
Note: SRFI-13 documents suggests the name of the module that
implements these functions to be ``string-lib'' and ``string-lib-internals''.
Gauche uses the name ``srfi-13'' for consistency.
@end deftp

@menu
* SRFI-13 General conventions::
* SRFI-13 String predicates::
* SRFI-13 String constructors::
* SRFI-13 String selection::
* SRFI-13 String comparison::
* SRFI-13 String prefixes & suffixes::
* SRFI-13 String searching::
* SRFI-13 String case mapping::
* SRFI-13 String reverse & append::
* SRFI-13 String mapping::
* SRFI-13 String rotation::
* SRFI-13 Other string operations::
* SRFI-13 String filtering::
* SRFI-13 Low-level string procedures::
@end menu

@node SRFI-13 General conventions, SRFI-13 String predicates, String library, String library
@subsection General conventions
@c NODE 一般規約

There are a few common factors in string library API, which I don't
repeat in each function description

@table @emph
@item argument convention
The following argument names imply their types.
@table @asis
@item @var{s}, @var{s1}, @var{s2}
Those arguments must be strings.
@item @var{char/char-set/pred}
This argument can be a character, a character-set object,
or a predicate that takes a single character and returns a boolean value.
``Applying @var{char/char-set/pred} to a character'' means,
if @var{char/char-set/pred} is a character, it is compared to the given
character; if @var{char/char-set/pred} is a character set, it is
checked if the character set contains the given character; if
@var{char/char-set/pred} is a procedure, it is applied
to the given character.  ``A character satisfies @var{char/char-set/pred}''
means such application to the character yields true value.

@item @var{start}, @var{end}
Lots of SRFI-13 functions takes these two optional arguments, which
limit the area of input string from @var{start}-th character
(inclusive) to @var{end}-th character (exclusive),
where the operation is performed.
When specified, the condition
0 <= @var{start} <= @var{end} <= @var{length of the string} must be
satisfied.  Default value of @var{start} and @var{end} is
0 and the length of the string, respectively.
@end table

@item @code{shared} variant
Some functions have variants with ``/shared'' attached to its name.
SRFI-13 defines those functions to allow to share the part of input
string, for better performance.  Gauche doesn't have a concept of
shared string, and these functions are mere synonyms of their
non-shared variants.  However, Gauche @emph{internally} shares
the storage of strings, so generally you don't need to worry
about the overhead of copying substrings.

@item @code{right} variant
Most functions works from left to right of the input string.
Some functions have variants with ``-right'' to its name,
that works from right to left.

@end table

@node SRFI-13 String predicates, SRFI-13 String constructors, SRFI-13 General conventions, String library
@subsection String predicates
@c NODE 文字列についての述語

@defun string-null? s
[SRFI-13]
@{@t{srfi-13}@}
Returns @code{#t} if @var{s} is an empty string, @code{""}.
@end defun

@defun string-every char/char-set/pred s :optional start end
[SRFI-13]
@{@t{srfi-13}@}
Sees if every character in @var{s} satisfies
@var{char/char-set/pred}.  If so, @code{string-every} returns
the value that is returned at the last application of @var{char/char-set/pred}.
If any of the application returns @code{#f}, @code{string-every}
returns @code{#f} immediately.
@end defun

@defun string-any char/char-set/pred s :optional start end
[SRFI-13]
@{@t{srfi-13}@}
Sees if any character in @var{s} satisfies
@var{char/char-set/pred}.  If so, @code{string-any} returns
the value that is returned by the application.   If no character
satisfies @var{char/char-set/pred}, @code{#f} is returned.
@end defun

@node SRFI-13 String constructors, SRFI-13 String selection, SRFI-13 String predicates, String library
@subsection String constructors
@c NODE 文字列の構築子

@defun string-tabulate proc len
[SRFI-13]
@{@t{srfi-13}@}
@var{proc} must be a procedure that takes an integer
argument and returns a character.  @code{string-tabulate}
creates a string, whose @var{i}-th character is calculated by
@code{(proc i)}.
@example
(string-tabulate
  (lambda (i) (integer->char (+ i #x30))) 10)
 @result{} "0123456789"
@end example
@end defun

@defun string-unfold p f g seed :optional base make-final
[SRFI-13]
@{@t{srfi-13}@}
A fundamental string builder.  The @var{p}, @var{f} and @var{g} are
procedures, taking the current seed value.  The stop predicate @var{p}
determines when to stop: If it returns a true value, string building
stops.  The mapping function @var{f} returns a character
from the current seed value.  The next seed function @var{g} returns
a next seed value from the current seed value.  The @var{seed} argument
gives the initial seed value.

@example
(string-unfold (^n (= n 10))
               (^n (integer->char (+ n 48)))
               (^n (+ n 1))
               0)
  @result{} "0123456789"
@end example

The optional argument @var{base} is, when given, prepended to the
result string.  Another optional argument @var{make-final}
is a procedure that takes the last return value of @var{g} and
returns a string that becomes the suffix of the result string.

@example
(string-unfold (^n (= n 10))
               (^n (integer->char (+ n 48)))
               (^n (+ n 1))
               0 "foo" x->string)
  @result{} "foo012345678910"
@end example
@end defun

@defun string-unfold-right p f g seed :optional base make-final
[SRFI-13]
@{@t{srfi-13}@}
Another fundamental string builder.  The meanings of arguments
are the same as @code{string-unfold}.  The only difference is
that the string is build right-to-left.  The optional @var{base},
if given, becomes the suffix of result, and the result of
@var{make-final} becomes the prefix.

@example
(string-unfold-right (^n (= n 10))
                     (^n (integer->char (+ n 48)))
                     (^n (+ n 1))
                     0 "foo" x->string)
  @result{} "109876543210foo"
@end example
@end defun


@defun reverse-list->string char-list
[SRFI-13]
@{@t{srfi-13}@}
@equiv{} @code{(list->string (reverse char-list))}.
@end defun

@node SRFI-13 String selection, SRFI-13 String comparison, SRFI-13 String constructors, String library
@subsection String selection
@c NODE 文字列の選択

@defun substring/shared s start :optional end
[SRFI-13]
@{@t{srfi-13}@}
In Gauche, this is the same as @code{substring}, except
that the @var{end} argument is optional.
@example
(substring/shared "abcde" 2) @result{} "cde"
@end example
@end defun

@defun string-copy! target tstart s :optional start end
[SRFI-13]
@{@t{srfi-13}@}
Copies a string @var{s} into a string
@var{target} from the position @var{tstart}.
The @var{target} string must be mutable.
Optional @var{start} and @var{end} arguments limits the range of @var{s}.
If the copied string run over the end of @var{target}, an error is
signaled.
@example
(define s (string-copy "abcde"))
(string-copy! s 2 "ZZ")
s @result{} "abZZe"
@end example

It is ok to pass the same string to @var{target} and @var{s}; this
always work even if the regions of source and destination are overlapping.

Note that Gauche encourages you to treat strings as immutable objects.
Internally, a string is an indirect pointer to a immutable entity, and 
mutating a string means copying the original entity and creating a new one.
It doesn't ``save allocations''.
Always use the functional version @code{string-copy} unless you
absolutely need to replace a string in-place.
@xref{String utilities}.
@end defun

@defun string-take s nchars
@defunx string-drop s nchars
@defunx string-take-right s nchars
@defunx string-drop-right s nchars
[SRFI-13]
@{@t{srfi-13}@}
Returns the first @var{nchars}-character string of @var{s}
(@code{string-take}) or the string without first @var{nchars}
(@code{string-drop}).  The @code{*-right} variation counts from
the end of string.  It is guaranteed that the returned string is
always a copy of @var{s}, even no character is dropped.
@example
(string-take "abcde" 2) @result{} "ab"
(string-drop "abcde" 2) @result{} "cde"

(string-take-right "abcde" 2) @result{} "de"
(string-drop-right "abcde" 2) @result{} "abc"
@end example
@end defun

@defun string-pad s len :optional char start end
@defunx string-pad-right s len :optional char start end
[SRFI-13]
@{@t{srfi-13}@}
If a string @var{s} is shorter than @var{len},
returns a string of @var{len} where @var{char} is
padded to the left or right, respectively.
If @var{s} is longer than @var{len}, the rightmost
or leftmost @var{len} chars are taken.
@var{Char} defaults to @code{#\space}.
If @var{start} and @var{end} are provided,
the substring of @var{s} is used as the source.

@example
(string-pad "abc" 10)    @result{} "       abc"
(string-pad "abcdefg" 3) @result{} "efg"

(string-pad-right "abc" 10) @result{} "abc       "

(string-pad "abcdefg" 10 #\+ 2 5)
  @result{} "+++++++cde"
@end example
@end defun

@defun string-trim s :optional char/char-set/pred start end
@defunx string-trim-right s :optional char/char-set/pred start end
@defunx string-trim-both s :optional char/char-set/pred start end
[SRFI-13]
@{@t{srfi-13}@}
Removes characters that match @var{char/char-set/pred}
from @var{s}.  @code{String-trim} removes the characters from
left of @var{s}, @code{string-trim-right} does from right,
and @code{string-trim-both} does from both sides.
@var{Char/char-set/pred} defaults to @code{#[\s]}, i.e. a char-set
of whitespaces.
If @var{start} and @var{end} are provided,
the substring of @var{s} is used as the source.

@example
(string-trim "   abc  ")       @result{} "abc  "
(string-trim-right "   abc  ") @result{} "   abc"
(string-trim-both "   abc  ")  @result{} "abc"
@end example
@end defun

@node SRFI-13 String comparison, SRFI-13 String prefixes & suffixes, SRFI-13 String selection, String library
@subsection String comparison
@c NODE 文字列の色々な比較

@defun string-compare s1 s2 proc< proc= proc> :optional start1 end1 start2 end2
@defunx string-compare-ci s1 s2 proc< proc= proc> :optional start1 end1 start2 end2
[SRFI-13]
@{@t{srfi-13}@}
Compares two strings @var{s1} and @var{s2} codepoint-wise from left.
When mismatch is found at the index @var{k} of @var{s1},
calls @var{proc<} with @var{k} if @var{s1}'s codepoint is smaller than
the corresponding @var{s2}'s, or calls @var{proc>} if @var{s1}'s one is
greater than @var{s2}'s.  If two strings are the same, calls @var{proc=}
with the index of the last compared position in @var{s1}.

@example
(string-compare "abcd" "abzd"
                (^i `(< ,i)) (^i `(= ,i)) (^i `(> ,i)))
  @result{} (< 2)

(string-compare "abcd" "abcd"
                (^i `(< ,i)) (^i `(= ,i)) (^i `(> ,i)))
  @result{} (= 3)
@end example

The optional arguments restricts
the range of the input strings; however, the index passed to one 
of the procedures is always an index from the beginning of @var{s1}.

@example
(string-compare "zzabcdyy" "abcz"
   (^i `(< ,i)) (^i `(= ,i)) (^i `(> ,i)) 2 6 0 4)
 @result{} (< 5)

(string-compare "zzabcdyy" "abcz"
   (^i `(< ,i)) (^i `(= ,i)) (^i `(> ,i)) 2 5 0 3)

 @result{} (= 4)
@end example

The case-insensitive variant, @code{string-compare-ci}, compares
each codepoint with character-wise case-folding.  It won't consider
special case folding such as German eszett.
@end defun

@defun string= s1 s2 :optional start1 end1 start2 end2
@defunx string<> s1 s2 :optional start1 end1 start2 end2
@defunx string< s1 s2 :optional start1 end1 start2 end2
@defunx string<= s1 s2 :optional start1 end1 start2 end2
@defunx string> s1 s2 :optional start1 end1 start2 end2
@defunx string>= s1 s2 :optional start1 end1 start2 end2
[SRFI-13]
@{@t{srfi-13}@}
Compare two strings @var{s1} and @var{s2}.  Optional arguments
can limit the portion of strings to be compared.
Comparison is done by character-wise.

Note: The builtin procedures @code{string=?} etc. can also be
used for character-wise string comparison, but they take
arguments differently.  @xref{String comparison}.
@end defun

@defun string-ci= s1 s2 :optional start1 end1 start2 end2
@defunx string-ci<> s1 s2 :optional start1 end1 start2 end2
@defunx string-ci< s1 s2 :optional start1 end1 start2 end2
@defunx string-ci<= s1 s2 :optional start1 end1 start2 end2
@defunx string-ci> s1 s2 :optional start1 end1 start2 end2
@defunx string-ci>= s1 s2 :optional start1 end1 start2 end2
[SRFI-13]
@{@t{srfi-13}@}
Compare two strings @var{s1} and @var{s2} in case-insensitive way.
Optional arguments can limit the portion of strings to be compared.
Case folding and comparison is done by character-wise, so they don't
consider case folding that affects multiple characters.

Note: We have two other sets of string comparison operations,
both are named as @code{string-ci=?} etc.
The builtin version (@pxref{String comparison}) does character-wise
comparison.  The one in @code{gauche.unicode} uses full-string
case conversion (@pxref{Full string case conversion}).
R7RS version is the latter.
@end defun

@defun string-hash s :optional bound start end
@defunx string-hash-ci s :optional bound start end
[SRFI-13]
@{@t{srfi-13}@}
(Note: Gauche has builtin @code{string-hash} and @code{string-ci-hash}
according to SRFI-128. @xref{Hashing}, for the details.
SRFI-13's API is upper-compatible to SRFI-128's.  The underlying
hash algorithm is the same as the builtin ones, so @code{string-hash}
returns the same value as the builtin ones for the same string
if optional arguments are omitted.
On the other hand, the builtin @code{string-ci-hash} uses string case
folding (e.g. German eszett and @code{SS} are the same), while
SRFI-13's @code{string-hash-ci} uses character-wise case folding.
Unless there's a strong reason, we recommend new code should use
builtin SRFI-128 version instead of SRFI-13.)

Calculates hash value of a string @var{s}.  For @code{string-hash-ci},
character-wise case folding is done before calculating the hash value.

If the optional @var{bound} argument is given, it must be a positive
exact integer, and the return value is limited below it.
The optional @var{start} and @var{end} arguments allows
using that portion for calculation.
@end defun

@node SRFI-13 String prefixes & suffixes, SRFI-13 String searching, SRFI-13 String comparison, String library
@subsection String prefixes & suffixes
@c NODE 文字列のプリフィックスとサフィックス

@defun string-prefix-length s1 s2 :optional start1 end1 start2 end2
@defunx string-suffix-length s1 s2 :optional start1 end1 start2 end2
@defunx string-prefix-length-ci s1 s2 :optional start1 end1 start2 end2
@defunx string-suffix-length-ci s1 s2 :optional start1 end1 start2 end2
[SRFI-13]
@{@t{srfi-13}@}
Returns the length of the longest common prefix/suffix of two strings,
@var{s1} and @var{s2}.  The optional arguments restrict the range of
search.  The @code{*-ci} variations use case folding character comparison.

@example
(string-prefix-length "abacus" "abalone")   @result{} 3
(string-prefix-length "machine" "umbrella") @result{} 0
(string-suffix-length "peeking" "poking")   @result{} 4

(string-prefix-length "obvious" "oblivious" 2 7 4 9)
  @result{} 5
@end example
@end defun

@defun string-prefix? s1 s2 :optional start1 end1 start2 end2
@defunx string-suffix? s1 s2 :optional start1 end1 start2 end2
@defunx string-prefix-ci? s1 s2 :optional start1 end1 start2 end2
@defunx string-suffix-ci? s1 s2 :optional start1 end1 start2 end2
[SRFI-13]
@{@t{srfi-13}@}
Returns true iff @var{s1} is a prefix or suffix of @var{s2}, respectively.
The optional arguments limit the range of @var{s1} and @var{s2} to look at.
The @code{*-ci} variations use case folding character comparison.

@example
(string-prefix? "sch" "scheme")   @result{} #t
(string-prefix? "lisp" "scheme")  @result{} #f

(string-suffix? "eme" "scheme")   @result{} #t
(string-suffix? "eme" "lisp")     @result{} #f

(string-prefix? "mit-scheme" "scheme-family" 4) @result{} #t
@end example
@end defun

@node SRFI-13 String searching, SRFI-13 String case mapping, SRFI-13 String prefixes & suffixes, String library
@subsection String searching
@c NODE 文字列の探索

@defun string-index s char/char-set/pred :optional start end
@defunx string-index-right s char/char-set/pred :optional start end
[SRFI-13]
@{@t{srfi-13}@}
Looks for the first element in a string @var{s}
that matches @var{char/char-set/pred}, and returns its index.
If @var{char/char-set/pred} is not found in @var{s}, returns @code{#f}.
Optional @var{start} and @var{end} limit the range of @var{s} to search.
@example
(string-index "Aloha oe" #\a) @result{} 4
(string-index "Aloha oe" #[Aa]) @result{} 0
(string-index "Aloha oe" #[\s]) @result{} 5
(string-index "Aloha oe" char-lower-case?) @result{} 1
(string-index "Aloha oe" #\o 3) @result{} 6
@end example

See also the Gauche built-in procedure @code{string-scan}
(@ref{String utilities}), if you need speed over portability.
@end defun

@defun string-skip s char/char-set/pred :optional start end
@defunx string-skip-right s char/char-set/pred :optional start end
[SRFI-13]
@{@t{srfi-13}@}
Looks for the first element that does not match
@var{char/char-set/pred} and returns its index.
If such element is not found, returns @code{#f}.
Optional @var{start} and @var{end} limit the range of @var{s} to search.
@end defun

@defun string-count s char/char-set/pred :optional start end
[SRFI-13]
@{@t{srfi-13}@}
Counts the number of elements in @var{s}
that matches @var{char/char-set/pred}.
Optional @var{start} and @var{end} limit the range of @var{s} to search.
@end defun

@defun string-contains s1 s2 :optional start1 end1 start2 end2
@defunx string-contains-ci s1 s2 :optional start1 end1 start2 end2
[SRFI-13]
@{@t{srfi-13}@}
Looks for a string @var{s2} inside another string @var{s1}.
If found, returns an index in @var{s1} from where the matching string
begins.  Returns @code{#f} otherwise.
Optional @var{start1}, @var{end1}, @var{start2} and @var{end2}
limits the range of @var{s1} and @var{s2}.

See also the Gauche built-in procedure @code{string-scan}
(@ref{String utilities}), if you need speed over portability.
@end defun

@node SRFI-13 String case mapping, SRFI-13 String reverse & append, SRFI-13 String searching, String library
@subsection String case mapping
@c NODE 文字列のケース(大文字小文字)マッピング

@defun string-titlecase s :optional start end
@defunx string-titlecase! s :optional start end
@defunx string-upcase s :optional start end
@defunx string-upcase! s :optional start end
@defunx string-downcase s :optional start end
@defunx string-downcase! s :optional start end
[SRFI-13]
@{@t{srfi-13}@}
Converts a string @var{s} to titlecase, upcase or downcase,
respectively.  These operations uses character-by-character
mapping provided by @code{char-upcase} etc.  That is, @code{string-upcase}
and @code{string-downcase} can be understood as follow:

@example
(string-upcase s)
  @equiv{} (string-map char-upcase s)
(string-downcase s)
  @equiv{} (string-map char-downcase s)
@end example

If you need full case mapping that handles the case when
a character is mapped to more than one characters, use
the procedures with the same name in @code{gauche.unicode} module
(@pxref{Full string case conversion}).

The linear-update version @code{string-titlecase!}, @code{string-upcase!}
and @code{string-downcase!} destroys @var{s} to store the result.
Note that in Gauche, using those procedures doesn't save anything,
since string mutation is expensive by design.  They are provided merely
for completeness.
@end defun


@node SRFI-13 String reverse & append, SRFI-13 String mapping, SRFI-13 String case mapping, String library
@subsection String reverse & append
@c NODE 文字列の反転と追加

@defun string-reverse s :optional start end
@defunx string-reverse! s :optional start end
[SRFI-13]
@{@t{srfi-13}@}
Returns a string in which the character positions are reversed
from @var{s}.  @code{string-reverse!} modifies @var{s}.
@example
(string-reverse "mahalo") @result{} "olaham"
(string-reverse "mahalo" 3) @result{} "ola"
(string-reverse "mahalo" 1 4) @result{} "aha"

(let ((s (string-copy "mahalo")))
  (string-reverse! s 1 5)
  s)
  @result{} "mlahao"
@end example
@end defun

@defun string-concatenate string-list
[SRFI-13]
@{@t{srfi-13}@}
Concatenates list of strings.
@example
(string-concatenate '("humuhumu" "nukunuku" "apua" "`a"))
  @result{} "humuhumunukunukuapua`a"
@end example
@end defun

@defun string-concatenate/shared string-list
@defunx string-append/shared s @dots{}
[SRFI-13]
@{@t{srfi-13}@}
``Shared'' version of @code{string-concatenate} and
@code{string-append}.  In Gauche, these are just synonyms of them.
@end defun

@defun string-concatenate-reverse string-list
@defunx string-concatenate-reverse/shared string-list
[SRFI-13]
@{@t{srfi-13}@}
Reverses @var{string-list} before concatenation.
``Shared'' version works the same in Gauche.
@end defun

@node SRFI-13 String mapping, SRFI-13 String rotation, SRFI-13 String reverse & append, String library
@subsection String mapping
@c NODE 文字列のマッピング

@defun string-map! proc s :optional start end
[SRFI-13]
@{@t{srfi-13}@}
@code{string-map!} applies @var{proc} on every character of @var{s},
and stores the results into @var{s}.  It is an error if @var{proc} returns
non-character.
@example
(let ((s (string-copy "wikiwiki")))
  (string-map! char-upcase s 4)
  s)
  @result{} "wikiWIKI"
@end example
@end defun

@defun string-fold kons knil s :optional start end
@defunx string-fold-right kons knil s :optional start end
[SRFI-13]
@{@t{srfi-13}@}
Like @var{fold} and @var{fold-right} (@pxref{Walking over lists}),
but works on a string instead of a list.

@example
(string-fold cons '() "abcde")
  @result{} (#\e #\d #\c #\b #\a)
(string-fold-right cons '() "abcde")
  @result{} (#\a #\b #\c #\d #\e)
@end example
@end defun

@defun string-for-each-index proc s :optional start end
[SRFI-13]
@{@t{srfi-13}@}
Call @var{proc} on each index of the string @var{s}, from left to right.
The result of @var{proc} is discarded.
The optional @var{start} and @var{end} arguments can be an integer
index or a string cursor, restricting the range
of the input string to be traversed.
@end defun

@node SRFI-13 String rotation, SRFI-13 Other string operations, SRFI-13 String mapping, String library
@subsection String rotation
@c NODE 文字列のローテーション

@defun xsubstring s from :optional to start end
[SRFI-13]
@{@t{srfi-13}@}
Takes a substring of infinite repetition of string @var{s}
between index @var{from} (inclusive) and index @var{to} (exclusive).
If @var{to} is omitted, the length of @var{s} is assumed.

For example, if @var{s} is @code{"abcde"}, we repeat it
infinitely to both sides.  So @var{5n}-th character for integer @var{n}
is always @code{#\a}, which extends negative @var{n} as well.

@example
(xsubstring "abcde" 2 10)
  @result{} "cdeabcde"
(xsubstring "abcde" -9 -2)
  @result{} "bcdeabc"
@end example

The optional @var{start} and @var{end} arguments can be an integer
index or a string cursor, it works as
@code{(xsubstring (substring s start end) from to)}.
@end defun

@defun string-xcopy! target tstart s sfrom :optional sto start end
[SRFI-13]
@{@t{srfi-13}@}
It works as 
@code{(string-copy! target tstart (xsubstring s sfrom sto start end))}.
@end defun

@node SRFI-13 Other string operations, SRFI-13 String filtering, SRFI-13 String rotation, String library
@subsection Other string operations
@c NODE 他の文字列操作

@defun string-replace s1 s2 start1 end1 :optional start2 end2
[SRFI-13]
@{@t{srfi-13}@}
Returns a new string whose content is a copy of a string @var{s1}, except
the part beginning from the index
@var{start1} (inclusive) and ending at the index @var{end1} (exclusive)
are replaced by a string @var{s2}.   When optional @var{start2} and @var{end2}
arguments are given, @var{s2} is trimmed first according to them.
The size of the @emph{gap}, @code{(- @var{end1} @var{start1})}, doesn't
need to be the same as the size of the inserted string.
Effectively, this is the same as the following code.

@example
(string-append (substring s1 0 start1)
               (substring s2 start2 end2)
               (substring s1 end1 (string-length s1)))
@end example
@end defun

@defun string-tokenize s :optional token-set start end
[SRFI-13]
@{@t{srfi-13}@}
Splits the string @var{s} into a list of substrings,
where each substring is a maximal non-empty contiguous
sequence of characters from the character set @var{token-set}.
The default of @var{token-set} is @code{char-set:graphic}
(@pxref{Predefined character sets}).

See also Gauche's built-in @code{string-split} (@pxref{String utilities}),
which provides similar features but different criteria.
@end defun

@node SRFI-13 String filtering, SRFI-13 Low-level string procedures, SRFI-13 Other string operations, String library
@subsection String filtering
@c NODE 文字列のフィルタリング

@defun string-filter char/char-set/pred s :optional start end
@defunx string-delete char/char-set/pred s :optional start end
[SRFI-13]
@{@t{srfi-13}@}
Returns a string consists of characters in a string @var{s} 
that passes (or don't pass) the test indicated by @var{char/char-set/pred},
respectively.  

@example
(string-filter char-upper-case? "Hello, World!")
  @result{} "HW"

(string-delete char-upper-case? "Hello, World!")
  @result{} "ello, orld!"

(string-delete #\l "Hello, World!")
  @result{} "Heo, Word!"

(string-filter #[\w] "Hello, World!")
  @result{} "HelloWorld"
@end example

Note: Srfi-13 was revised after finalization to switch
the order of arguments @var{char/char-set/pred} and @var{s} was.
At the time of finalization, the order was
@code{(string-filter s pred)} and Gauche implemented it accordingly.
However, most existing implementations follows the revised order,
since that was what the srfi-13 reference implementation had.

So, from 0.9.4, we revised the API to comply the current
srfi-13 spec, but we also accept the old order as well
not to break the old code.
We recommend the new code to use the new order.
@end defun

@node SRFI-13 Low-level string procedures,  , SRFI-13 String filtering, String library
@subsection Low-level string procedures
@c NODE 低レベルな文字列に関する手続き

@defun string-parse-start+end proc s args
@defunx string-parse-final-start+end proc s args
[SRFI-13]
@{@t{srfi-13}@}
@end defun

@defmac let-string-start+end (start end [rest]) proc-exp s-exp args-exp body @dots{}
[SRFI-13]
@{@t{srfi-13}@}
@end defmac

@defun check-substring-spec proc s start end
@defunx substring-spec-ok? s start end
[SRFI-13]
@{@t{srfi-13}@}
@end defun

@defun make-kmp-restart-vector s :optional c= start end
[SRFI-13]
@{@t{srfi-13}@}
@end defun

@defun kmp-step pat rv c i c= p-start
[SRFI-13]
@{@t{srfi-13}@}
@end defun

@defun string-kmp-partial-search pat rv s i :optional c= p-start s-start s-end
[SRFI-13]
@{@t{srfi-13}@}
@end defun

@c ----------------------------------------------------------------------
@node Time data types and procedures, Sources of random bits, String library, Library modules - SRFIs
@section @code{srfi-19} - Time data types and procedures
@c NODE 時間のデータ型と手続き, @code{srfi-19} - 時間のデータ型と手続き

@deftp {Module} srfi-19
@mdindex srfi-19
This SRFI defines various representations of time and date, and
conversion methods among them.

On Gauche, time object is supported natively by @code{<time>} class
(@pxref{Time}).  Date object is supported by @code{<date>} class
described below.
@end deftp

@menu
* SRFI-19 Time types::
* SRFI-19 Time queries::
* SRFI-19 Time procedures::
* SRFI-19 Date::
* SRFI-19 Date reader and writer::
@end menu

@node SRFI-19 Time types, SRFI-19 Time queries, Time data types and procedures, Time data types and procedures
@subsection Time types
@c NODE 時間のタイプ

Time type is represented by a symbol.  This module defines
the following constant variables that is bound to its name, for
convenience.

@defvr {Constant} time-utc
[SRFI-19]
@{@t{srfi-19}@}
UTC time.  Gauche's built-in @code{current-time} always returns
this type (@pxref{Time}).
@end defvr

@defvr {Constant} time-tai
[SRFI-19]
@{@t{srfi-19}@}
International Atomic Time.  This time is a bit larger than UTC, due to
the leap seconds.
@end defvr

@defvr {Constant} time-monotonic
[SRFI-19]
@{@t{srfi-19}@}
Implementation-dependent monotonically increasing time.
In Gauche, this is the same as @code{time-tai}.
@end defvr

@defvr {Constant} time-duration
[SRFI-19]
@{@t{srfi-19}@}
Duration between two absolute time points.
@end defvr

@defvr {Constant} time-process
[SRFI-19]
@{@t{srfi-19}@}
CPU time in current process.
Gauche calculates this from user time and system time returned by
POSIX times(3).
@end defvr

@defvr {Constant} time-thread
[SRFI-19]
@{@t{srfi-19}@}
CPU time in current thread.
In the current implementation, this is the same as @code{time-process}.
@end defvr

@node SRFI-19 Time queries, SRFI-19 Time procedures, SRFI-19 Time types, Time data types and procedures
@subsection Time queries
@c NODE 時間に関する問い合わせ

@defun current-time :optional time-type
[SRFI-19]
@{@t{srfi-19}@}
Extends Gauche built-in @code{current-time} (@pxref{Time}) to take
optional @var{time-type} argument to specify the desired time type.
@var{time-type} must be one of the types described in @ref{SRFI-19 Time types}.
@end defun

@defun current-date :optional tz-offset
[SRFI-19]
@{@t{srfi-19}@}
Returns the current date as an instance of @code{<date>} class
(@pxref{SRFI-19 Date}).  If @var{tz-offset} is given, it must be
an offset from UTC in number of seconds.  If @var{tz-offset} is
not given, returns the date in local time zone.
@end defun

@defun current-julian-day
[SRFI-19]
@{@t{srfi-19}@}
Returns the current julian day, a point in time as a real number of
days since -4714-11-24T12:00:00Z (November 24, -4714 at noon, UTC).
@end defun

@defun current-modified-julian-day
[SRFI-19]
@{@t{srfi-19}@}
Returns the current modified julian day, a point in time as a real
number of days since 1858-11-17T00:00:00Z
(November 17, 1858 at midnight, UTC).
@end defun

@defun time-resolution
[SRFI-19]
@{@t{srfi-19}@}
@end defun


@node SRFI-19 Time procedures, SRFI-19 Date, SRFI-19 Time queries, Time data types and procedures
@subsection Time procedures
@c NODE 時間に関する手続き

@defun make-time type nanoseconds seconds
[SRFI-19]
@{@t{srfi-19}@}
Returns an instance of @code{<time>} class with specified initial values.
Equivalent to @code{(make <time> :type type :second seconds :nanosecond nanoseconds)}.

(This function had been defined incorrectly before release 0.6.8;
the arguments @var{seconds} and @var{nanoseconds} were switched.
Please check your code if it uses @code{make-time}).
@end defun

@defun time-type time
@defunx time-second time
@defunx time-nanosecond time
@defunx set-time-type! time type
@defunx set-time-second! time second
@defunx set-time-nanosecond! time nanosecond
[SRFI-19]
@{@t{srfi-19}@}
Getter and setter of @code{<time>} object slots.
@end defun

@defun copy-time time
[SRFI-19]
@{@t{srfi-19}@}
Returns a new instance of @code{<time>} whose content is the same as
given @var{time}
@end defun

@defun time=? time0 time1
@defunx time<? time0 time1
@defunx time<=? time0 time1
@defunx time>? time0 time1
@defunx time>=? time0 time1
[SRFI-19]
@{@t{srfi-19}@}
Compares two times.  Types of both times must match.
@end defun

@defun time-difference time0 time1
@defunx time-difference! time0 time1
[SRFI-19]
@{@t{srfi-19}@}
Returns the difference of two times, in @code{time-duration} time.
Types of both times must match.
@code{Time-difference!} modifies @var{time0} to store the result.
@end defun

@defun add-duration time0 time-duration
@defunx add-duration! time0 time-duration
@defunx subtract-duration time0 time-duration
@defunx subtract-duration! time0 time-duration
[SRFI-19]
@{@t{srfi-19}@}
Adds or subtracts @var{time-duration} to or from @var{time0}.
Type of returned time is the same as @var{time0}.  Type of
@var{time-duration} must be @code{time-duration}.
@code{add-duration!} and @code{subtract-duration!} reuse
@var{time0} to store the result.
@end defun

@node SRFI-19 Date, SRFI-19 Date reader and writer, SRFI-19 Time procedures, Time data types and procedures
@subsection Date
@c NODE 日付

@deftp {Class} <date>
@clindex date
@{@t{srfi-19}@}
Represents a date.

@defivar <date> nanosecond
Nanosecond portion of the date by an integer between 0 and 999,999,999,
inclusive.
@end defivar

@defivar <date> second
Second portion of the date by an integer between 0 and 60, inclusive.
(60 for leap second).
@end defivar

@defivar <date> minute
Minute portion of the date by an integer between 0 and 59, inclusive.
@end defivar

@defivar <date> hour
Hour portion of the date by an integer between 0 and 23, inclusive.
@end defivar

@defivar <date> day
Day portion of the date by an integer between 0 and 31, inclusive.
The actual upper bound of the day is determined by the year and the month.
(Note: 1 is for the first day; 0 is allowed by the specification,
but I don't see why).
@end defivar

@defivar <date> month
Month portion of the date by an integer between 1 and 12, inclusive.
1 for January, 2 for February, and so on.
(Note: this is different from POSIX's @code{<sys-tm>} convention).
@end defivar

@defivar <date> year
Year portion of the date.
@end defivar

@defivar <date> zone-offset
The number of seconds east of GMT for this timezone, by an integer.
@end defivar
@end deftp

@defun make-date nanosecond second minute hour day month year zone-offset
[SRFI-19]
@{@t{srfi-19}@}
Makes a @code{<date>} object from the given values.
Note: this procedure does not check if the values are in the valid range.
@end defun

@defun date? obj
[SRFI-19]
@{@t{srfi-19}@}
Returns true iff @var{obj} is a @code{<date>} object.
@end defun

@defun date-nanosecond date
@defunx date-second date
@defunx date-minute date
@defunx date-hour date
@defunx date-day date
@defunx date-month date
@defunx date-year date
@defunx date-zone-offset date
[SRFI-19]
@{@t{srfi-19}@}
Accessors.
@end defun

@defun date-year-day date
@defunx date-week-day date
@defunx date-week-number date day-of-week-starting-week
[SRFI-19]
@{@t{srfi-19}@}
Calculates the day number in the year (1 for January 1st),
the day number in the week (0 for Sunday, 1 for Monday, ...),
and the ordinal week of the year which holds this date,
ignoring a first partial week, respectively.

@var{Day-of-week-starting-week} is the integer corresponding to
the day of the week which is to be considered the first day of
the week (Sunday=0, Monday=1, etc.).
@end defun

@defun date->julian-day date
@defunx date->modified-julian-day date
@defunx date->time-monotonic date
@defunx date->time-tai date
@defunx date->time-utc date
[SRFI-19]
@{@t{srfi-19}@}
Conversions from date to various date/time types.
@end defun

@defun julian-day->date jd :optional tz-offset
@defunx julian-day->time-monotonic jd
@defunx julian-day->time-tai jd
@defunx julian-day->time-utc jd
[SRFI-19]
@{@t{srfi-19}@}
Conversions from julian-day to various date/time types.
@end defun

@defun modified-julian-day->date jd :optional tz-offset
@defunx modified-julian-day->time-monotonic jd
@defunx modified-julian-day->time-tai jd
@defunx modified-julian-day->time-utc jd
[SRFI-19]
@{@t{srfi-19}@}
Conversions from modified julian-day to various date/time types.
@end defun

@defun time-monotonic->date time :optional tz-offset
@defunx time-monotonic->julian-day time
@defunx time-monotonic->modified-julian-day time
@defunx time-monotonic->time-tai time
@defunx time-monotonic->time-tai! time
@defunx time-monotonic->time-utc time
@defunx time-monotonic->time-utc! time
[SRFI-19]
@{@t{srfi-19}@}
Conversions from time-monotonic to various date/time types.
@end defun

@defun time-tai->date time :optional tz-offset
@defunx time-tai->julian-day time
@defunx time-tai->modified-julian-day time
@defunx time-tai->time-monotonic time
@defunx time-tai->time-monotonic! time
@defunx time-tai->time-utc time
@defunx time-tai->time-utc! time
[SRFI-19]
@{@t{srfi-19}@}
Conversions from time-tai to various date/time types.
@end defun

@defun time-utc->date time :optional tz-offset
@defunx time-utc->julian-day time
@defunx time-utc->modified-julian-day time
@defunx time-utc->time-monotonic time
@defunx time-utc->time-monotonic! time
@defunx time-utc->time-tai time
@defunx time-utc->time-tai! time
[SRFI-19]
@{@t{srfi-19}@}
Conversions from time-utc to various date/time types.
@end defun

@node SRFI-19 Date reader and writer,  , SRFI-19 Date, Time data types and procedures
@subsection Date reader and writer
@c NODE 日付の読み書き

@defun date->string date :optional format-string
[SRFI-19+]
@{@t{srfi-19}@}
Converts a @code{<date>} object to a string, according
to the format specified by @var{format-string}.
If @var{format-string} is omitted, @code{"~c"} is assumed.

A format string is copied to output, except a sequence begins with
@code{~} which is replaced with the following rules:

@table @code
@item ~~
A literal @code{~}.
@item ~a
Locale's abbreviated weekday name (Sun...Sat).
@item ~A
Locale's full weekday name (Sunday...Saturday).
@item ~b
Locale's abbreviate month name (Jan...Dec).
@item ~B
Locale's full month name (January...December).
@item ~c
Locale's date and time (e.g., "Fri Jul 14 20:28:42-0400 2000").
@item ~d
Day of month, zero padded (01...31).
@item ~D
Date (mm/dd/yy).
@item ~e
Day of month, blank padded ( 1...31).
@item ~f
Seconds+fractional seconds, using locale's decimal separator (e.g. 5.2).
@item ~h
Same as ~b.
@item ~H
Hour, zero padded, 24-hour clock (00...23).
@item ~I
Hour, zero padded, 12-hour clock (01...12).
@item ~j
Day of year, zero padded.
@item ~k
Hour, blank padded, 24-hour clock ( 0...23).
@item ~l
Hour, blank padded, 12-hour clock ( 1...12).
@item ~m
Month, zero padded (01...12).
@item ~M
Minute, zero padded (00...59).
@item ~n
New line.
@item ~N
Nanosecond, zero padded.
@item ~p
Locale's AM or PM.
@item ~r
Time, 12 hour clock, same as "~I:~M:~S ~p".
@item ~s
Number of full seconds since "the epoch" (in UTC).
@item ~S
Second, zero padded (00...60).
@item ~t
Horizontal tab.
@item ~T
Time, 24 hour clock, same as "~H:~M:~S".
@item ~U
Week number of year with Sunday as first day of week (01...53).
@item ~V
Week number of year with Monday as first day of week (00...52).
@item ~w
Day of week (0...6).
@item ~W
Week number of year with Monday as first day of week (00...52).
@item ~x
Locale's date representation, for example: "07/31/00".
@item ~X
Locale's time representation, for example: "06:51:44".
@item ~y
Last two digits of year (00...99).
@item ~Y
Year.
@item ~z
Time zone in RFC-822 style.
@c @item ~Z
@c Symbol time zone (not-implemented).
@item ~1
ISO-8601 year-month-day format.
@item ~2
ISO-8601 hour-minute-second-timezone format.
@item ~3
ISO-8601 hour-minute-second format.
@item ~4
ISO-8601 year-month-day-hour-minute-second-timezone format.
@item ~5
ISO-8601 year-month-day-hour-minute-second format.
@end table

Note: currently Gauche doesn't honor process's locale setting,
and it always formats the date as if the locale is "C".  It may
be changed in future, so you shouldn't rely on, for example,
@code{~a} always formatted as "Sun".."Sat".

There's no portable way to ensure you'll get "C" locale formats
since there's no standard way to set process's locale yet.
However, Gauche provides a way to ensure the locale to be "C",
as an extension to srfi-19.
Insert @code{@@} between @code{~} and the directive
character, such as @code{~@@a}.
@end defun

@defun string->date string template-string
[SRFI-19]
@{@t{srfi-19}@}
@c   [NB] srfi-19's string->date is broken, in both spec and reference
@c   implementation.  I'm wondering whether I should change string->date
@c   to make usable, or introduce another procedure, like string->date*,
@c   which fixes the problem.
@c
@c Both procedures parse a string representation of date in @var{string},
@c according to the format given in @var{template-string}.

@c The input string must match the @var{template-string},
@c except tilde-directives described below, which matches
@c one or more component(s) of the date.  If the input string
@c is parsed successfully, a @code{<date>} object is returned
@c with the matched components are filled.

@c If the input string does not match @var{template-string},
@c an error is signaled.  (The SRFI-19 spec doesn't explicitly
@c state what happens if @code{string->date} doesn't accept the
@c input, which actually reduces usability of @code{string->date}

@c but the reference implementation signals an error, and
@c it would be safe to assume


@c @table @code
@c @item ~~
@c Matches literal @code{~}.
@c @item ~a
@c Skip to an alphanumeric character, then matches abbreviated
@c weekday in locale.  Match result is ignored.
@c @item ~A
@c Skip to an alphanumeric character, then matches full
@c weekday in locale.  Match result is ignored.
@c @item ~b
@c Skip to an alphanumeric character, then matches abbreviated
@c month name in locale.  Sets the month component of the date.
@c @item ~B
@c Skip to an alphanumeric character, then matches full
@c month name in locale.  Sets the month component of the date.
@c @item ~d
@c Skip to a numeric character, then matches the day of month.
@c Sets the month component of the date.
@c @item ~e

@c ~e	any	day of month, blank padded	date-day
@c ~h	char-alphabetic?	same as ~b	nothing
@c ~H	char-numeric?	hour	date-hour
@c ~k	any	hour, blank padded	date-hour
@c ~m	char-numeric?	month	date-month
@c ~M	char-numeric?	minute	date-minute
@c ~S	char-numeric?	second	date-second
@c ~y	any	2-digit year	date-year within 50 years
@c ~Y	char-numeric?	year	date-year
@c ~z	any	time zone	date-zone-offset@end table

@end defun

@c ----------------------------------------------------------------------
@node Sources of random bits, Localization, Time data types and procedures, Library modules - SRFIs
@section @code{srfi-27} - Sources of Random Bits
@c NODE ランダムビットのソース, @code{srfi-27} - ランダムビットのソース

@deftp {Module} srfi-27
@mdindex srfi-27
This module provides SRFI-27 pseudo random generator interface,
using Mersenne Twister algorithm
(@pxref{Mersenne-Twister random number generator}) as the backbone.
@end deftp

@defun random-integer n
[SRFI-27]
@{@t{srfi-27}@}
Returns a random exact integer between [0, @var{n}-1], inclusive,
using the default random source.
To set a random seed for this procedure, use @code{random-source-randomize!}
or @code{random-source-pseudo-randomize!} on @code{default-random-source}.
@end defun

@defun random-real
[SRFI-27]
@{@t{srfi-27}@}
Returns a random real number between (0, 1), exclusive,
using the default random source.
To set a random seed for this procedure, use @code{random-source-randomize!}
or @code{random-source-pseudo-randomize!} on @code{default-random-source}.
@end defun

@defvar default-random-source
[SRFI-27]
@{@t{srfi-27}@}
Keeps the default random source that is used by @code{random-integer}
and @code{random-real}.
@end defvar

@defun make-random-source
[SRFI-27]
@{@t{srfi-27}@}
Creates and returns a new random source.
In the current Gauche implementation, it is just a @code{<mersenne-twister>}
object.  It may be changed in the future implementation.
@end defun

@defun random-source? obj
[SRFI-27]
@{@t{srfi-27}@}
Returns @code{#t} if @var{obj} is a random source object.
@end defun

@defun random-source-state-ref s
@defunx random-source-state-set! s state
[SRFI-27]
@{@t{srfi-27}@}
Gets and sets the "snapshot" of the state of the random source @var{s}.
@var{State} is an opaque object whose content depends on the backbone
generator.
@end defun

@defun random-source-randomize! s
[SRFI-27]
@{@t{srfi-27}@}
Makes an effort to set the state of the random source @var{s} to
a truly random state.  The current implementation uses the current
time and the process ID to set the random seed.
@end defun

@defun random-source-pseudo-randomize! s i j
[SRFI-27]
@{@t{srfi-27}@}
Changes the state of the random source @var{s} into the initial state
of the (@var{i}, @var{j})-th independent random source,
where @var{i} and @var{j} are non-negative integers.
This procedure can be used to reuse a random source @var{s} as large
number of independent random source, indexed by two non-negative integers.
Note that this procedure is entirely deterministic.
@end defun

@defun random-source-make-integers s
[SRFI-27]
@{@t{srfi-27}@}
Returns a procedure, that takes one integer argument @var{n} and
returns a random integer between 0 and @var{n}-1 inclusive for every
invocation, from the random source @var{s}.
@end defun

@defun random-source-make-reals s :optional unit
[SRFI-27]
@{@t{srfi-27}@}
Returns a procedure, that takes no argument and
returns a random real between 0 and 1 exclusive for
every invocation, from the random source @var{s}.
If @var{unit} is given, the random real the returned procedure
generates will be quantized by the given @var{unit}, where
0 < @var{unit} < 1.
@end defun

@c ----------------------------------------------------------------------
@node Localization, A program argument processor, Sources of random bits, Library modules - SRFIs
@section @code{srfi-29} - Localization
@c NODE 地域化, @code{srfi-29} - 地域化

@deftp {Module} srfi-29
@mdindex srfi-29
@mdindex srfi-29.bundle
@mdindex srfi-29.format
This module implements the message localization mechanism
defined in SRFI-29.

In fact, this module consists of two submodules,
@code{srfi-29.bundle} and @code{srfi-29.format}.
The module @code{srfi-29} extends both submodules.
It is because srfi-29's definition of the @code{format}
procedure is incompatible to Gauche's native @code{format}
(thus Common Lisp's @code{format}) in the handling of
@code{~@@*} directive.

So I splitted the module into two, @code{srfi-29.format}
which contains srfi-29's @code{format}, and @code{srfi-29.bundle}
which contains the rest ("bundle" API).
If a program wishes a complete compatibility of
srfi-29, use @code{srfi-29} module, which overrides
Gauche's native @code{format}.   If a program just wants
srfi-29's "bundle" API, but wants to keep Gauche's @code{format},
use @code{srfi-29.bundle}.

A localization feature is also provided by @code{text.gettext} module
(@pxref{Localized messages}),
which is a preferable way of message localization in Gauche.
This module is provided mainly for porting code that uses
srfi-29 features.
@end deftp

@subheading Bundle specifier

A @emph{bundle specifier} is an arbitrary list of symbols,
but typically it takes the form like:
@example
@code{(@var{package} @var{language} @var{country} @var{details} @dots{})}
@end example
Where @var{package} specifies the software package,
@var{language} and @var{country} specifies language and country code,
and @var{details} gives other informations like encoding.

The values for the default bundle specifier can be obtained
by the following parameters.

@deffn {Parameter} current-language
@deffnx {Parameter} current-country
@deffnx {Parameter} current-locale-details
[SRFI-29]
@{@t{srfi-29}@}
The @code{current-language} and @code{current-country} parameters
keep the ISO 639-1 language code and ISO 3166-1 country code
respectively, both as symbols.
The @code{current-locale-details} keeps a list of auxiliary
local informations, such as encodings.

These parameters are initialized if @code{LANG} environment
variable is set in the form of @code{lang_country.encoding} format.
For example, if the @code{LANG} setting is @code{ja_JP.eucJP},
those parameters are @code{ja}, @code{jp}, and @code{(eucjp)},
respectively.   If @code{LANG} is @code{C} or undefined,
the default values are @code{en}, @code{us}, and @code{()}, respectively.
@end deffn

@subheading Bundle preparation

@defun declare-bundle! bundle-specifier association-list
[SRFI-29]
@{@t{srfi-29}@}
Put the association list of template key (symbol) and the locale-specific
message (string) into the bundle database, with @var{bundle-specifier}
as the key.
@end defun

Gauche currently supports only in-memory bundle database.
That is, you have to call @code{declare-bundle!} within the application
in order to lookup the localized messages.

@defun save-bundle! bundle-specifier
@defunx load-bundle! bundle-specifier
[SRFI-29]
@{@t{srfi-29}@}
Since Gauche doesn't support persistent bundle database yet,
these procedures does nothing and returns @code{#f}.
(It is still conforming behavior of srfi-29).
@end defun

@subheading Retrieving localized message

@defun localized-template package-name message-template-name
[SRFI-29]
@{@t{srfi-29}@}
Retrieves localized message, associated with a symbol
@var{message-template-name} in the package @var{package-name}.
@end defun

@subheading Extended format procedure

@defun format format-string args
[SRFI-29]
@{@t{srfi-29}@}
SRFI-29 extends SRFI-28's @code{format} procedure spec
(which supports @code{~a}, @code{~s}, @code{~%} and @code{~~} directives),
in order to support argument repositioning.

A directive @code{~N@@*}, where N is an integer or can be omitted,
causes the next directive to retrieve a value from @var{N}-th
optional argument.  The referenced value isn't consumed,
and won't affect the processing of subsequent directives.

Although SRFI-28 spec is compatible to
Gauche's native @code{format} (@pxref{Output}),
this SRFI-29 extension isn't.
Specifically, the @code{~N@@*} directive of Gauche's @code{format}
changes the argument pointer to points @var{N}-th optional argument,
thus it affects all the subsequent arguments.

Because of this incompatibility, this function is defined in
a separate module, @code{srfi-29.format}.  If you use @code{srfi-29},
which extends @code{srfi-29.bundle} and @code{srfi-29.format},
the @code{format} procedure will be overridden by srfi-29's @code{format}
in your module.  If you want to keep Gauche's native @code{format},
use @code{srfi-29.bundle} only.
@end defun

@c ----------------------------------------------------------------------
@node A program argument processor, Eager comprehensions, Localization, Library modules - SRFIs
@section @code{srfi-37} - args-fold: a program argument processor
@c NODE args-fold プログラム引数処理, @code{srfi-37} - args-fold プログラム引数処理

@deftp {Module} srfi-37
@mdindex srfi-37
This module implements @code{args-fold},
yet another procedure to process command-line
arguments, defined in SRFI-37 (@uref{https://srfi.schemers.org/srfi-37/srfi-37.html}).

Unlike @code{gauche.parseopt}
(@pxref{Parsing command-line options}),
@code{args-fold} provides functional interface, i.e.
the user's states are explicitly passed via parser's argument and
return values, and also follows POSIX and GNU getopt guidelines,
including long options.
@end deftp

@defun args-fold args options unrecognized-proc operand-proc :rest seeds
@{@t{srfi-37}@}
Processes program options @var{args} from left to right,
according to given option specification @var{options},
and two procedures @var{unrecognized-proc} and @var{operand-proc}.

@var{Options} is a list of option objects, explained below.
Each option object keeps the name(s) of the option,
a flag to specify whether the option takes
an argument or not, and a procedure to process that option
(we'll call it @emph{option procedure}).

@code{Args-fold} recognizes both single-character options (short options)
and long options.  A short option must begin with single hyphen
(e.g. @code{-a}), while long option must begin with double hyphens
(e.g. @code{--help}).   Short options can be
concatenated, e.g. @code{-abc} or @code{-a -b -c}.
Both a short option and a long option can take
required or optional arguments.   Required short-option argument
can appear with or without space after the option, e.g.
@code{-afoo} or @code{-a foo}.
Long-option argument can appear after character '@code{=}' or
space, e.g. @code{--long=foo} or @code{--long foo}.

When @code{args-fold} encounters a command-line argument that cannot
be an option argument, and doesn't begin with hyphen, the argument is
treated as an @emph{operand}.   @code{Args-fold} allows operands and
options to be interleaved.  However, if @code{args-fold} encounters
'@code{--}', the rest of arguments are treated as operands,
regardless of beginning with hyphen or not.

When the given option matches one of option object in @var{options},
the option procedure is called as follows:

@example
(@var{option-proc} @var{option} @var{name} @var{arg} @var{seed} @dots{})
@end example

where @var{option} is the matched option object, @var{name} is
the string actually used to specify the option, @var{arg} is
the option argument (or @code{#f} if there's none), and
@var{seed} @dots{} is the user's state information.
@var{Option-proc} must return as many arguments as @var{seed}s.

When @code{args-fold} encounters an option that doesn't match
any of the option objects, it creates a new option object
for the option and calls @var{unrecognized-proc}
with the same arguments as @var{option-proc}.

When @code{args-fold} finds an operand, @var{operand-proc}
is called as follows:

@example
(@var{operand-proc} @var{operand} @var{seed} @dots{})
@end example

@var{Operand-proc} must return as many arguments as @var{seed}s.

The caller's state should be explicitly passed around seed arguments
and return values.  The initial seed values are @var{seed}s given
to @code{args-fold}.  The values returned from option procedure,
@var{unrecognized-proc} and @var{operand-proc} are used as the seed
arguments of next invocation of those procedures.  The values
returned from the last call to the procedures are returned
from @code{args-fold}.
@end defun

@defun option names require-arg? optional-arg? processor
@{@t{srfi-37}@}
Creates an option object with the passed properties.

@var{Names} is a list of characters and/or strings.
A character is used for a short option, and a string is used
for a long option.

Two flags, @var{require-arg?} and @var{optional-arg?}
indicates whether the option should take an option argument,
or may take an option argument.

@var{Processor} is the option processor procedure.

Note that, if an option argument is passed using '@code{=}'
character, it is passed to the option procedure even if
the option has @code{#f} in both @var{require-arg?}
and @var{optional-arg?}.  It is up to the option procedure
to deal with the argument.

It should also be noted that the optional option argument
for a short option is only recognized if it is given
without whitespace after the short option.  That is, if
a short option '@code{d}' is marked to take optional option argument,
then '@code{-dfoo}' is interpreted as '@code{-d}' with argument '@code{foo}',
but '@code{-d foo}' is interpreted as '@code{-d}' without argument
and an operand @code{foo}.  If '@code{d}' is marked to
take required option argument, however, both are interpreted
as '@code{-d}' with argument '@code{foo}'.
@end defun

@defun option? obj
@{@t{srfi-37}@}
Returns @code{#t} if @var{obj} is an option object,
@code{#f} otherwise.
@end defun

@defun option-names option
@defunx option-required-arg? option
@defunx option-optional-arg? option
@defunx option-processor
@{@t{srfi-37}@}
Returns the properties of an option object @var{option}.
@end defun

A simple example:

@example
(use srfi-37)

(define options
 (list (option '(#\d "debug") #f #t
               (lambda (option name arg debug batch paths files)
                 (values (or arg "2") batch paths files)))
       (option '(#\b "batch") #f #f
               (lambda (option name arg debug batch paths files)
                 (values debug #t paths files)))
       (option '(#\I "include") #t #f
               (lambda (option name arg debug batch paths files)
                 (values debug batch (cons arg paths) files)))))

(define (main args)
  (receive (debug-level batch-mode include-paths files)
    (args-fold (cdr args)
               options
               (lambda (option name arg . seeds)         ; unrecognized
                 (error "Unrecognized option:" name))
               (lambda (operand debug batch paths files) ; operand
                 (values debug batch paths (cons operand files)))
               0      ; default value of debug level
               #f     ; default value of batch mode
               '()    ; initial value of include paths
               '()    ; initial value of files
               )
     (print "debug level = " debug-level)
     (print "batch mode = " batch-mode)
     (print "include paths = " (reverse include-paths))
     (print "files = " (reverse files))
     0))
@end example

@c ----------------------------------------------------------------------
@node Eager comprehensions, Vector library (Legacy), A program argument processor, Library modules - SRFIs
@section @code{srfi-42} - Eager comprehensions
@c NODE 先行評価的内包表記, @code{srfi-42} - 先行評価的内包表記

@deftp {Module} srfi-42
@mdindex srfi-42
This module provides a generic comprehension mechanism, which some other
languages (e.g. Haskell and Python) offer as a built-in mechanism.
It provides a rich set of operators so it can be used not only as a list
generator but as a generic loop construct (actually, some may say
it is as powerful/evil as Common Lisp's @emph{loop} macro).

It runs eagerly as the name suggests, that is, if it generates a list, it
creates the entire list when evaluated, instead of generate the
elements @emph{on demand}.  Thus it can't represent an infinite
sequence, which Haskell's comprehension naturally does.  Gauche offers
a few alternatives to deal with lazy, possibly infinite, sequences:
See @ref{Lazy sequences}, @ref{Generators} and @ref{Stream library}.
@end deftp

@subheading Eager comprehension examples

Let's begin with some examples.

Generate a list of squares for the first five integers:
@example
(list-ec (: i 5) (* i i)) @result{} (0 1 4 9 16)
@end example

@code{list-ec} is a comprehension macro that generates a list.
The first form @code{(: i 5)} is called a @var{qualifier}, which
specifies a set of values to repeat over (here it is each integer
from 0 below 5).
The last form
@code{(* i i)} is called a @var{body}, which is an ordinary Scheme expression
evaluated for each values generated by the @var{qualifier}.

A comprehension can have more than one qualifiers.
Next example generate set of pair of numbers @code{(x y)}, where @code{x}
is between 2 (inclusive) and 5 (exclusive),
and @code{y} is between 1 (inclusive) and x (exclusive).

@example
(list-ec (: x 2 5) (: y 1 x) (list x y))
  @result{} ((2 1) (3 1) (3 2) (4 1) (4 2) (4 3))
@end example

The qualifiers works as @emph{nested}; that is, @code{(: x 2 5)}
specifies to repeat the rest of the clauses---@code{(: y 1 x)} and
@code{(list x y)}.

The above two examples can be written in Haskell as the followings:

@example
[ i*i   | i <- [0..4] ]
[ (x,y) | x <- [2..4], y <- [1..x-1] ]
@end example

Note the differences: (1) In Haskell, the body expression to yield the
elements comes first, followed by qualifiers (selectors).  In srfi-42, the body
expression comes last.  (2) In srfi-42, range operator's lower bound
is inclusive but its upper bound is exclusive.

List a set of numbers @code{(a b c d)}, where @code{a^3+b^3 = c^3+d^3}:
@example
(define (taxi-number n)
  (list-ec (: a 1 n)
           (: b (+ a 1) n)
           (: c (+ a 1) b)
           (: d (+ c 1) b)
           (if (= (+ (expt a 3) (expt b 3))
                  (+ (expt c 3) (expt d 3))))
           (list a b c d)))
@end example

If you want to change values of more than one variable
simultaneously, instead of nesting, you can bundle the qualifiers
like this:

@example
(list-ec (:parallel (: x '(a b c d)) (: y '(1 2 3 4)))
         (list x y))
  @result{} ((a 1) (b 2) (c 3) (d 4))
@end example

You can generate not only a list, but other sequences:
@example
(vector-ec (: i 5) i) @result{} #(0 1 2 3 4)
(string-ec (: i 5) (integer->char (+ i 65))) @result{} "ABCDE"
@end example

Or apply folding operations:
@example
(sum-ec (: i 1 100) i)
  @result{} 4950    ;; sum of integers from 1 below 100.
(product-ec (: i 1 10) i)
  @result{} 362880 ;; ... and product of them.
@end example

@subheading Comprehension macros

Each comprehension takes the following form.
@example
(@var{comprehension-macro} @var{qualifier} @dots{} @var{body})
@end example

It evaluates @var{body} repeatedly as specified by @var{qualifier} @dots{}.
Depending on the type of comprehension,
the results of @var{body} may be either collected to create an
aggregate (list, vector, string, ...), folded by some operator
(sum, product, min, max, ...), or simply discarded.

Each @var{qualifier} specifies how to repeat the following
@var{qualifiers} and @var{body}.  A @var{qualifier} can be a
generational qualifier that yields a set of values to loop
over, or a control qualifier that specify a condition
to exclude some values.  See the Qualifiers heading below.

A few comprehensions takes extra values before @var{qualifiers} or
after @var{body}.

@defmac do-ec qualifier @dots{} body
[SRFI-42]
@{@t{srfi-42}@}
Repeats @var{body}.  The results of @var{body} is discarded.
This is for side-effecting operations.
@end defmac

@defmac list-ec qualifier @dots{} body
[SRFI-42]
@{@t{srfi-42}@}
Repeats @var{body} and collects the results into a list.
@end defmac

@defmac append-ec qualifier @dots{} body
[SRFI-42]
@{@t{srfi-42}@}
Repeats @var{body}, which must yield a list.
Returns a list which is the concatenation of all lists returned by @var{body}.
@end defmac

@defmac string-ec qualifier @dots{} body
@defmacx string-append-ec qualifier @dots{} body
[SRFI-42]
@{@t{srfi-42}@}
Repeats @var{body}, which must yield a character (in @code{string-ec})
or a string (in @code{string-append-ec}).  Returns a string that
consists of the results of @var{body}.
@end defmac

@defmac vector-ec qualifier @dots{} body
[SRFI-42]
@{@t{srfi-42}@}
Repeats @var{body} and collects the results into a vector.
@end defmac

@defmac vector-of-length-ec k qualifier @dots{} body
[SRFI-42]
@{@t{srfi-42}@}
This is like @code{vector-ec}, except that the length of the
result vector is known to be @var{k}.  It can be more efficient
than @code{vector-ec}.  Unless the comprehension repeats exactly
@code{k} times, an error is signaled.
@end defmac

@defmac sum-ec qualifier @dots{} body
@defmacx product-ec qualifier @dots{} body
[SRFI-42]
@{@t{srfi-42}@}
@var{body} must yield a numeric value.  Returns sum of and product of
the results, respectively.
@end defmac

@defmac min-ec qualifier @dots{} body
@defmacx max-ec qualifier @dots{} body
[SRFI-42]
@{@t{srfi-42}@}
@var{body} must yield a numeric value.  Returns maximum and minimum value
of the results, respectively.  @var{body} must be evaluated at least once,
or an error is signaled.
@end defmac

@defmac any?-ec qualifier @dots{} test
@defmacx every?-ec qualifier @dots{} test
[SRFI-42]
@{@t{srfi-42}@}
Evaluates @var{test} for each iteration, and returns
@code{#t} as soon as it yields non-@code{#f} (for @code{any?-ec}),
or returns @code{#f} as soon as it yields @code{#f} (for @code{every?-ec}).
Unlink the comprehensions introduced above, these stop evaluating
@var{test} as soon as the condition meets.
If the qualifiers makes no iteration, @code{#f} and @code{#t} are
returned, respectively.
@end defmac

@defmac first-ec default qualifier @dots{} body
@defmacx last-ec default qualifier @dots{} body
[SRFI-42]
@{@t{srfi-42}@}
First initializes the result by the value of the expression @var{default},
then start iteration, and returns the value of the first and last
evaluation of @var{body}, respectively.  In fact, @code{first-ec}
only evaluates @var{body} at most once.

These procedures are most useful when used with control qualifiers.
For example, the following @code{first-ec} returns the @emph{first}
set of distinct integers (@var{x}, @var{y}, @var{z}),
where @var{x}*@var{x}+@var{y}*@var{y}+@var{z}*@var{z} becomes a square
of another integer @var{w}.

@example
(first-ec #f (:integers w) (: z 1 w) (: y 1 z) (: x 1 y)
          (if (= (* w w) (+ (* x x) (* y y) (* z z))))
          (list x y z w))
@end example

Note that the first qualifier, @code{(:integers w)}, generates
infinite number of integers; if you use @code{list-ec} instead of
@code{first-ec} it won't stop.
@end defmac

@defmac fold-ec seed qualifier @dots{} expr proc
@defmacx fold3-ec seed qualifier @dots{} expr init proc
[SRFI-42]
@{@t{srfi-42}@}
Reduces the values produced by @var{expr}.

Suppose @var{expr} produces a sequence of values
@var{x0}, @var{x1}, @dots{}, @var{xN}.  @code{Fold-ec}
calculates the following value:

@example
(@var{proc} @var{xN} (@dots{}(@var{proc} @var{x1} (@var{proc} @var{x0} @var{seed}))@dots{}))
@end example

It's similar to @code{fold}, except that @var{proc} is evaluated
within the scope of @var{qualifier} @dots{} so you can refer to the
variables introduced by them.  On the other hand,
@var{seed} is outside of the scope of @var{qualifier}s.

@code{Fold-ec3} is almost the same but the initial value calculation.
In @code{fold-ec3}, @var{seed} is only used when @var{qualifier}s
makes no iteration.  Otherwise it calculates the following value:

@example
(@var{proc} @var{xN} (@dots{}(@var{proc} @var{x1} (@var{init} @var{x0}))@dots{}))
@end example

@end defmac

@subheading Qualifiers

@subsubheading Generational qualifiers

This type of qualifiers generates (possibly infinite) values
over which the rest of clauses iterate.

In the following descriptions, @var{vars} refers to either
a single identifier, or a series of identifier and a form
@code{(index @var{identifier2})}.  The single identifier
in the former case and the first identifier in the latter case
name the variable to which each generated value is bound.
The @var{identifier2} in the latter case names a variable
to which a series of integers, increasing with each generated
element, is bound.   See the following example:

@example
(list-ec (: x '(a b c)) x)
  @result{} (a b c)
(list-ec (: x (index y) '(a b c)) (cons x y))
  @result{} ((a . 0) (b . 1) (c . 2))
@end example

@deffn {EC Qualifier} : vars arg1 args @dots{}
A generic dispatcher of generational qualifiers.
An appropriate generational qualifier is selected based on the
types of @var{arg1} @var{args} @dots{}.
@end deffn

@deffn {EC Qualifier} :list vars arg1 args @dots{}
@deffnx {EC Qualifier} :vector vars arg1 args @dots{}
@deffnx {EC Qualifier} :uvector vars arg1 args @dots{}
@deffnx {EC Qualifier} :string vars arg1 args @dots{}
@var{Arg1} @var{args} @dots{} should be all lists, vectors, uniform vectors
or strings,
respectively.  Repeats the subsequent clauses while binding
each element from those args bound to @var{vars}.
(The @code{:uvector} qualifier is Gauche's extension.)

@example
(list-ec (:string c "ab" "cd") c) @result{} (#\a #\b #\c #\d)
@end example

If the arguments given to the generic qualifier @code{:} are
all lists, vectors, uniform vectors or strings, then these qualifiers are used.
@end deffn

@deffn {EC Qualifier} :integers vars
Generates infinite series of increasing integers, starting from 0.
@end deffn

@deffn {EC Qualifier} :range vars stop
@deffnx {EC Qualifier} :range vars start stop
@deffnx {EC Qualifier} :range vars start stop step
Generates a series of exact integers, starting from
@var{start} (defaults to 0) and stops below @var{stop},
stepping by @var{step} (defaults to 1).  Giving a negative
integer to @var{step} makes a decreasing series.

@example
(list-ec (:range v 5) v)      @result{} (0 1 2 3 4)
(list-ec (:range v 3 8) v)    @result{} (3 4 5 6 7)
(list-ec (:range v 1 8 2) v)  @result{} (1 3 5 7)
(list-ec (:range v 8 1 -2) v) @result{} (8 6 4 2)
@end example

If one, two or three exact integer(s) is/are given to the generic
qualifier @code{:}, this qualifier is used.
@end deffn

@deffn {EC Qualifier} :real-range vars stop
@deffnx {EC Qualifier} :real-range vars start stop
@deffnx {EC Qualifier} :real-range vars start stop step
Generates a series of real numbers, starting from
@var{start} (defaults to 0) and stops below @var{stop},
stepping by @var{step} (defaults to 1).  If all the arguments
are exact numbers, the result consists of exact numbers; if any
of the arguments are inexact, the result consists of inexact numbers.

@example
(list-ec (:real-range v 5.0) v)
  @result{} (0.0 1.0 2.0 3.0 4.0)
(list-ec (:real-range v 1 4 1/3) v)
  @result{} (1 4/3 5/3 2 7/3 8/3 3 10/3 11/3)
(list-ec (:real-range v 1 5.0 1/2) v)
  @result{} (1.0 1.5 2.0 2.5 3.0 3.5 4.0 4.5)
@end example

If one, two or three real numbers is/are given to the generic
qualifier @code{:}, and any one of them isn't an exact integer,
then this qualifier is used.
@end deffn

@deffn {EC Qualifier} :char-range vars min max
Generates a series of characters, starting from @var{min} and
ending at @var{max} (inclusive).  The characters are enumerated
in the order defined by @code{char<=?} (@pxref{Characters}).

@example
(list-ec (:char-range v #\a #\e) v)
  @result{} (#\a #\b #\c #\d #\e)
@end example

If two characters are given to the generic
qualifier @code{:}, this qualifier is used.
@end deffn

@deffn {EC Qualifier} :port vars port
@deffnx {EC Qualifier} :port vars port read-proc
Generates a series of values read from an input port @var{port},
by the procedure @var{read-proc} (defaults to @code{read}).  The
series terminates when EOF is read.

@example
(call-with-input-string "a \"b\" :c"
  (^p (list-ec (:port v p) v)))
  @result{} (a "b" :c)
@end example

If one or two arguments are given to the generic
qualifier @code{:} and the first one is an input port,
then this qualifier is used.
@end deffn

@deffn {EC Qualifier} :generator vars gen
This is Gauche's extension and not defined in SRFI-42.
@var{gen} must be a procedure with zero arguments.
This qualifier repeats until @var{gen} returns EOF.

Gauche has a set of utilities to create and operate on
such procedures; see @ref{Generators}.

@example
(use gauche.generator)
(list-ec (:generator v (grange 1 8)) v)
  @result{} (1 2 3 4 5 6 7)
@end example

If one argument is given to the generic
qualifier @code{:} and it is applicable without arguments,
then this qualifier is used.
@end deffn

@deffn {EC Qualifier} :collection vars coll
This is Gauche's extension and not defined in SRFI-42.
@var{coll} must be an instance of @code{<collection>} or its subclass.
(@pxref{Collection framework}).
This qualifier repeats over the elements in the collection.

If srfi-42 has a specialized qualifier, it is faster to use it
(e.g. a vector is also a collection, but using @code{:vector} is
faster than @code{:collection}).

If one argument is given to the generic
qualifier @code{:} and it is a collection other than the specific
types suppored directly in srfi-42, this qualifer is used.
@end deffn

@deffn {EC Qualifier} :parallel generator @dots{}
This is used to run through multiple generators in parallel.
It terminates when any one of @var{generator} is exhausted.

@example
(list-ec (:parallel (: x '(a b c))
                    (: y "defg"))
  (cons x y))
 @result{} ((a . #\d) (b . #\e) (c . #\f))

;; Compare with this:
(list-ec (: x '(a b c))
         (: y "defg")
  (cons x y))
 @result{} ((a . #\d) (a . #\e) (a . #\f) (a . #\g)
     (b . #\d) (b . #\e) (b . #\f) (b . #\g)
     (c . #\d) (c . #\e) (c . #\f) (c . #\g))
@end example
@end deffn

@deffn {EC Qualifier} :let vars expr
Evaluate @var{expr}, and bind the result to @var{vars} and execure
the following clauses once.
If @var{vars} has an index var, it is bound to 0.
It is effectively the same as @code{(:list vars (list expr))}.
@end deffn

@deffn {EC Qualifier} :while g-qualifier expr
@deffnx {EC Qualifier} :until generator expr
Generates values from  @var{g-qualifier} while/until @var{expr} evaluates true. 
Here, @var{g-qualifier} is one of generative EC qualifiers.  The variable
bound in @var{g-qualifier} is visible from @var{expr}.


@example
(use math.prime)
(sum-ec (:while (: p (index k) *primes*) (<= k 100)) p)
@end example
@end deffn


@deffn {EC Qualifier} :dispatched vars dispatch arg1 args @dots{}
@end deffn

@deffn {EC Qualifier} :do (lb @dots{}) ne1? (ls @dots{})
@deffnx {EC Qualifier} :do (let (ob @dots{}) oc @dots{}) (lb @dots{}) ne1? (let (ib @dots{}) ic @dots{}) ne2? (ls @dots{})
@end deffn

@subsubheading Control qualifiers

@deffn {EC Qualifier} if test
@end deffn

@deffn {EC Qualifier} not test
@deffnx {EC Qualifier} and test @dots{}
@deffnx {EC Qualifier} or test @dots{}
@end deffn

@deffn {EC Qualifier} begin command @dots{} expr
@end deffn

@deffn {EC Qualifier} nested qualifier @dots{}
@end deffn


@c ----------------------------------------------------------------------
@node Vector library (Legacy), Requiring extensions, Eager comprehensions, Library modules - SRFIs
@section @code{srfi-43} - Vector library (legacy)
@c NODE ベクタライブラリ(旧式), @code{srfi-43} - ベクタライブラリ(旧式)

@deftp {Module} srfi-43
@mdindex srfi-43
This module is effectively superseded by R7RS and @code{srfi-133}.  
There are a few procedures that are not compatible with R7RS and 
@code{srfi-133}, and this module remains to support
legacy code that depends on them.  

@xref{Vectors}, and @pxref{R7RS vectors}, for the ``modern'' versions
of vector library.  New code should use them.

The following procedures in srfi-43 are built-in.
@xref{Vectors}, for the description.

@example
make-vector     vector          vector?         vector-ref
vector-set!     vector-length   vector-fill!    vector-copy
vector-copy!    vector-append   vector->list    list->vector
reverse-list->vector
@end example

The following procedures in srfi-43 are supported by srfi-133.
@xref{R7RS vectors}, for the description.

@example
vector-unfold         vector-unfold-right   vector-reverse-copy
vector-reverse-copy!  vector-concatenate    vector-empty?
vector=               vector-index          vector-index-right
vector-skip           vector-skip-right     vector-binary-search
vector-any            vector-every          vector-swap!    
reverse-vector->list
@end example

We explain the procedures that are not listed above.
@end deftp

@defun vector-fold kons knil vec1 vec2 @dots{}
@defunx vector-fold-right kons knil vec1 vec2 @dots{}
[SRFI-43]
@{@t{srfi-43}@}
Like @code{vector-fold} and @code{vector-fold-right}
in @code{srfi-133}, but @var{kons}
takes an extra argument, the current index, as its first argument.
So @var{kons} must accept @var{n}+2 arguments, where
@var{n} is the number of given vectors.
It is called as @code{(kons <index> <cumulated-value> <elt1> <elt2> ...)}.

Gauche has @code{fold-with-index} (@pxref{Mapping over sequences})
that can be used to fold vectors with index, but the argument order
of @var{kons} is slightly different: It passes the index, each
element from argument vectors, then cumulated values.  

@example
(use srfi-43)
(vector-fold list '() '#(a b c) '#(d e f))
  @result{} (2 (1 (0 () a d) b e) c f)

(use gauche.sequence)
(fold-with-index list '() '#(a b c) '#(d e f))
  @result{} (2 c f (1 b e (0 a d ())))
@end example
@end defun

@defun vector-map f vec1 vec2 @dots{}
@defunx vector-map! f vec1 vec2 @dots{}
@defunx vector-for-each f vec1 vec2 @dots{}
@defunx vector-count f vec1 vec2 @dots{}
[SRFI-43]
@{@t{srfi-43}@}
Like @code{vector-map} and @code{vector-for-each} of R7RS,
and @code{vector-map!} and @code{vector-count} in @code{srfi-133},
except @var{f} takes
an extra argument, the current index, as its first argument.

Gauche provides @code{vector-map-with-index},
@code{vector-map-with-index!} and @code{vector-for-each-with-index}
which are the same as @code{srfi-43}'s @code{vector-map}, @code{vector-map!}
and @code{vector-for-each}, respectively.  @xref{Vectors}.

@example
(vector-map list '#(a b c))
 @result{} #((0 a) (1 b) (2 c))
(vector-map list '#(a b c) '#(d e f g))
 @result{} #((0 a d) (1 b e) (2 c f))
(vector-count = '#(0 2 2 4 4))
 @result{} 3
@end example

(Note: The @code{vector-count} example calls @code{=} with
two arguments, the current index and the element, for each element
of the input vector.  So it counts the number of
occasions when the element is equal to the index.)

The generic @code{map} and @code{for-each}
in @code{gauche.collection} can be used
on vectors, but the mapped procedure is called without index, and the result
is returned as a list.
@code{(vector-map f vec1 vec2 @dots{})} is operationally equivalent to
@code{(map-to-with-index <vector> f vec1 vec2 @dots{})}.
See @ref{Collection framework} and @ref{Sequence framework}.
@end defun

@c ----------------------------------------------------------------------
@node Requiring extensions, Integers as bits, Vector library (Legacy), Library modules - SRFIs
@section @code{srfi-55} - Requiring extensions
@c NODE Requiring extensions, @code{srfi-55} - require の拡張

@deftp {Module} srfi-55
@mdindex srfi-55
This module defines @code{require-extension} macro, a yet another way
to write portable scripts.  See @ref{Feature conditional} and
@ref{Feature-based program configuration language} for other means of
ensuring specific features.

This module is autoloaded when you use @code{require-extension}, so
you don't need explicitly say @code{(use srfi-55)}; for portable scripts,
you shouldn't.
@end deftp

@defmac require-extension clause @dots{}
@{@t{srfi-55}@}
Make extension(s) specified by @var{clause}s available in the rest
of the program.

A @var{clause} takes the following form:
@example
(@var{extension-id} @var{extension-arg} @dots{})
@end example

Currently, only @code{srfi} is supported as @var{extension-id}, and
its arguments are SRFI numbers.

For example, the following form:
@example
(require-extension (srfi 1 13 14))
@end example

Roughly corresponds to Gauche's @code{use} forms:
@example
(use srfi-1)
(use srfi-13)
(use srfi-14)
@end example
@end defmac

@c ----------------------------------------------------------------------
@node Integers as bits, A Scheme API for test suites, Requiring extensions, Library modules - SRFIs
@section @code{srfi-60} - Integers as bits
@c NODE 整数に対するビット操作, @code{srfi-60} - 整数に対するビット操作

@deftp {Module} srfi-60
@mdindex srfi-60
This srfi provides bit operations on integers, regarding them
as 2's complement representation.  It is compatible to SLIB's @code{logical}
module.

The newer srfi-151 (@pxref{R7RS bitwise operations}) provides the same
functionality and more, with more consistent naming.  We recommend
new code to use srfi-151, while we keep srfi-60 for the backward
compatibility.

The following procedures are Gauche built-in.
@xref{Basic bitwise operations}, for the description.

@example
lognot           logand           logior           logxor
logtest          logcount         integer-length   logbit?
copy-bit         bit-field        copy-bit-field   ash
@end example

The following procedures are defined in srfi-151.
@xref{R7RS bitwise operations}, for the description.

@example
bitwise-not      bitwise-and      bitwise-ior      bitwise-xor
arithmetic-shift bit-count        bitwise-if       bit-set?
copy-bit         first-set-bit    
@end example
@end deftp

We describe procedures that are unique in srfi-60 below.

@defun bitwise-merge mask n0 n1
[SRFI-60]
@{@t{srfi-60}@}
Same as @code{bitwise-if} (@pxref{R7RS bitwise operations}).
@end defun

@defun any-bits-set? mask n
[SRFI-60]
@{@t{srfi-60}@}
Same as builtin @code{logtest} (@pxref{Basic bitwise operations}).
It is also called @code{any-bit-set?} in srfi-151 (@pxref{R7RS bitwise operations}).
@end defun

@defun log2-binary-factors n
[SRFI-60]
@{@t{srfi-60}@}
It is also called as @code{first-set-bit} in this srfi, which is also
in srfi-151 (@pxref{R7RS bitwise operations}).
This is equivalent to Gauche's built-in  @code{twos-exponent-factor}
(@pxref{Basic bitwise operations}).
@end defun

@defun rotate-bit-field n count start end
[SRFI-60]
@{@t{srfi-60}@}
This is equivalent to @code{bit-field-rotate} in srfi-151
(@pxref{R7RS bitwise operations}).
@end defun

@defun reverse-bit-field n start end
[SRFI-60]
@{@t{srfi-60}@}
This is equivalent to @code{bit-field-reverse} in srfi-151
(@pxref{R7RS bitwise operations}).
@end defun

@defun integer->list n :optional len
[SRFI-60]
@{@t{srfi-60}@}
Breaks @var{n} to each bits, representing @code{1} as @code{#t} and
@code{0} as @code{#f}, LSB last, and returns a list of them.
If a nonnegative integer @var{len} is given, it specifies the length
of the result.   If it is omitted, @code{(integer-length n)} is used.

@example
(integer->list 10)   @result{} (#t #f #t #f)
(integer->list 10 6) @result{} (#f #f #t #f #t #f)
@end example

Srfi-151 has similar procedure @code{bits->list}, with a reversed bit
order (LSB first) (@pxref{R7RS bitwise operations}).
@end defun

@defun list->integer lis
[SRFI-60]
@{@t{srfi-60}@}
Takes a list of boolean values, replaces the true value for @code{1}
and the false value for @code{0}, and compose an integer regarding
each value as a binary digit.  If @var{n} is nonnegative integer,
@code{(eqv? (list->integer (integer->list n)) n)} is true.

@example
(list->integer '(#f #t #f #t #f)) @result{} 10
@end example

Srfi-151 has similar procedure @code{list->bits}, with a reversed bit
order (LSB first) (@pxref{R7RS bitwise operations}).
@end defun

@defun booleans->integer bool @dots{}
[SRFI-60]
@{@t{srfi-60}@}
@equiv{} @code{(list->integer (list @var{bool} @dots{}))}

Srfi-151 has similar procedure @code{bits}, with a reversed bit
order (LSB first) (@pxref{R7RS bitwise operations}).
@end defun

@c ----------------------------------------------------------------------
@node A Scheme API for test suites, Octet vectors, Integers as bits, Library modules - SRFIs
@section @code{srfi-64} - A Scheme API for test suites
@c NODE SchemeテストスイートAPI, @code{srfi-64} - SchemeテストスイートAPI

@deftp {Module} srfi-64
@mdindex srfi-64
This module defines API to write a portable test suite.  In Gauche,
it is adapted to work with @code{gauche.test} native test framework
(@pxref{Unit testing}).

If srfi-64 tests are run with the default runner during @code{gauche.test}
is active, the tests becomes a part of the whole @code{gauche.test} suite.

The recommended way is to write a test suite in pure srfi-64, then include
it from the gauche test script:

@example
(use gauche.test)
(test-start "the tests")
;; portable test
(include "test-suite-in-srfi-64")

;; gauche-specific test, if needed
...

(test-end)
@end example

If @file{test-suite-in-srfi-64.scm} is run by itself, it uses srfi-64's
default reporting system.  If it is run within @code{gauche.test} script,
the results are reported via @code{gauche.test}, consolidated with other
Gauche test results.
@end deftp

@menu
* Srfi-64 test API::
* Srfi-64 test runner::
@end menu

@node Srfi-64 test API, Srfi-64 test runner, A Scheme API for test suites, A Scheme API for test suites
@subsection Test API

@node Srfi-64 test runner,  , Srfi-64 test API, A Scheme API for test suites
@subsection Test runner


@c ----------------------------------------------------------------------
@node Octet vectors, Basic hash tables, A Scheme API for test suites, Library modules - SRFIs
@section @code{srfi-66} - Octet vectors
@c NODE オクテットベクタ, @code{srfi-66} - オクテットベクタ

@deftp {Module} srfi-66
@mdindex srfi-66
This module defines procedures to deal with @code{u8vector}s; they are
almost a subset of @code{srfi-160} and @code{gauche.uvector}
(@pxref{Uniform vectors}, except one procedure, @code{u8vector-copy!},
which has different argument orders (unfortunate historical artifacts).

There's no reason to use this srfi except porting code that relies
on @code{srfi-66}.

The following procedures are the same as @code{gauche.uvector}:

@example
u8vector?       make-u8vector      u8vector
u8vector->list  list->u8vector
u8vector-length u8vector-ref       u8vector-set!
u8vector=?      u8vector-compare   u8vector-copy
@end example
@end deftp

@defun u8vector-copy! src sstart target tstart n
[SRFI-66]
@{@t{srfi-66}@}
Copy the content of an u8vector @var{src}, starting from @var{sstart}
for @var{n} octets, into an u8vector @var{target} beginning from
@var{tstart}.  The @var{target} u8vector must be mutable.

Note that @code{gauche.uvector} has also @code{u8vector-copy!},
but its argument order is as follows, where @var{send} 
is @code{(+ @var{sstart} @var{n})}:

@example
(u8vector-copy! target tstart src sstart send)
@end example

Gauche's argument order is consistent with @code{vector-copy!} of
R7RS, srfi-43 and srfi-133.

We recommend to use @code{srfi-66} only for porting third-party
libraries to avoid confusion.
@end defun

@c ----------------------------------------------------------------------
@node Basic hash tables, Octet-addressed binary blocks, Octet vectors, Library modules - SRFIs
@section @code{srfi-69} - Basic hash tables
@c NODE 基本的なハッシュテーブル, @code{srfi-69} - 基本的なハッシュテーブル

@deftp {Module} srfi-69
@mdindex srfi-69
This module has been superseded by R7RS @code{scheme.hash-table}
(@pxref{R7RS hash tables}).  New code should use it instead.

This is a thin adaptor on Gauche's built-in hashtables
(@pxref{Hashtables}).  This is provided for the compatibility
to the portable libraries; the hashtable object created by
this module's @code{make-hash-table} is the same as the one
created by Gauche's built-in, and you can pass the table to
both APIs.
@end deftp

Here's a summary of difference between srfi-69 and Gauche's built-in
hash table API:

@itemize
@item
The constructor @code{make-hash-table}, as well as @code{alist->hash-table},
takes equality predicate and hash function, instead of a single
comparator argument.
@item
The hash function passed to @code{srfi-69}'s @code{make-hash-table}
takes two arguments, an object to calculate a hash value,
and a positive integer that limits the range of the hash value.
@item
@code{Srfi-69}'s primary hash table accessor is @code{hash-table-ref},
which takes a thunk to be called when the table doesn't have an
entry for the given key, while Gauche's @code{hash-table-get} takes
a fallback value for that.
@code{Srfi-69} also has @code{hash-table-ref/default},
which takes a fallback value like Gauche's @code{hash-table-get},
but the default value can't be omitted.
@item
The basic iterator of @code{srfi-69} is called @code{hash-table-walk},
which is Gauche's @code{hash-table-for-each}.  The srfi name is chosen
to avoid conflict with existing Scheme implementations.
@end itemize

The following procedures are the same as Gauche's built-in ones.
@xref{Hashtables}, for the details.

@example
hash-table?       hash-table-delete!   hash-table-exists?
hash-table-keys   hash-table-values    hash-table-fold
hash-table->alist hash-table-copy 
@end example


@defun make-hash-table :optional eq-pred hash-proc :rest args
[SRFI-69]
@{@t{srfi-69}@}
Creates a new hashtable and returns it.  This is the same name
as Gauche's built-in procedure, but the arguments are different.

The @var{eq-pred} argument is an equality predicate; it takes
two arguments and returns @code{#t} if two are the same,
and @code{#f} if not.  When omitted, @code{equal?} is used.

The @var{hash-proc} argument is a hash function.
It takes two arguments: an object to hash, and a positive
integer to limit the range of the hash value.  (Note that
Gauche's native hash functions takes only one argument.)
When omitted, Gauche tries to choose appropriate hash function
if @code{eq-pred} is known one (@code{eq?}, @code{eqv?},
@code{equal?}, @code{string=?} or @code{string-ci=?}).
Otherwise we use Gauche's @code{hash} procedure, but there's
no guarantee that it works appropriately; you should give
suitable @var{hash-proc} if you pass custom @var{eq-pred}.

The returned hash table is an instance of Gauche's native
hash table.  You can pass it to Gauche's builtin procedures.

@code{Srfi-69} allows implementation-specific arguments @var{args} to be
passed to @code{make-hash-table}.  At this moment, Gauche
ignores them.
@end defun

@defun alist->hash-table alist :optional eq-pred hash-fn :rest args
[SRFI-69]
@{@t{srfi-69}@}
Like Gauche's builtin @code{alist->hash-table}, but takes
@var{eq-pred} and @var{hash-fn} separately,
instead of a single comparator.

The @var{alist} argument is a list of pairs.  The car of each
pair is used for a key, and the cdr for its value.

See @code{make-hash-table} above for the description of
@var{eq-pred}, @var{hash-fn} and @var{args}.
@end defun

@defun hash-table-equivalence-function ht
@defunx hash-table-hash-function ht
[SRFI-69]
@{@t{srfi-69}@}
Returns equivalence function and hash function of the
hashtable @var{ht}.

The hash function returned from @code{hash-table-hash-function}
takes two arguments, an object to hash and bound, a positive exact integer.
Note that the function returned by @code{hash-table-hash-function} may not
be @code{eq?} to the one you gave to @code{make-hash-table}.
@end defun

@defun hash-table-ref ht key :optional thunk
[SRFI-69]
@{@t{srfi-69}@}
Looks up the value corresponding to @var{key} in a hash table @var{ht}.
If there's no entry for @var{key}, @var{thunk} is called
without arguments.  The default of @var{thunk} is to signal an error.
@end defun

@defun hash-table-ref/default ht key default
[SRFI-69]
@{@t{srfi-69}@}
Looks up the value corresponding to @var{key} in a hash table @var{ht}.
This is like Gauche's @code{hash-table-get}, but @var{default} can't be
omitted.
@end defun

@defun hash-table-set! ht key val
[SRFI-69]
@{@t{srfi-69}@}
This is the same as Gauche's @code{hash-table-put!}.
@end defun

@defun hash-table-update! ht key proc :optional thunk
@defunx hash-table-update!/default ht key proc default
[SRFI-69]
@{@t{srfi-69}@}
@end defun

@defun hash-table-size ht
[SRFI-69]
@{@t{srfi-69}@}
Returns the number of entries in a hash table @var{ht}.  The same as Gauche's
@code{hash-table-num-entries}.
@end defun
          
@defun hash-table-walk ht proc
[SRFI-69]
@{@t{srfi-69}@}
For each entry in a hash table @var{ht}, 
calls @var{proc} with two arguments, a key and its value.
It's the same as Gauche's @code{hash-table-for-each}.
@end defun

@defun hash-table-merge! ht1 ht2
[SRFI-69]
@{@t{srfi-69}@}
Add all entries in a hash table @var{ht2} into a hash table @var{ht1},
and returns @var{ht1}.
@end defun

@defun hash obj :optional bound
[SRFI-69]
@{@t{srfi-69}@}
Like Gauche's @code{hash}, except this one can take bound argument;
if provided, it must be a positive integer, and the return value
is limited between 0 and @code{(- bound 1)}, inclusive.
@end defun

@defun string-hash obj :optional bound
@defunx string-ci-hash obj :optional bound
[SRFI-69]
@{@t{srfi-69}@}
These are like @code{srfi-13}'s (@pxref{String library}), except
these don't take @var{start} and @var{end} argument.
@end defun

@defun hash-by-identity obj :optional bound
[SRFI-69]
@{@t{srfi-69}@}
This is Gauche's @code{eq-hash}, except this one can take bound argument.
@end defun

@c ----------------------------------------------------------------------
@node Octet-addressed binary blocks, Lightweight testing, Basic hash tables, Library modules - SRFIs
@section @code{srfi-74} - Octet-addressed binary blocks

@deftp {Module} srfi-74
@mdindex srfi-74
This module provides procedures to deal with @emph{blob},
or a sequence of octets.  In Gauche, a blob is simply an u8vector.

Most functionalities of this module is available
in @code{binary.io} module (@pxref{Binary I/O}), and in fact
this module is a thin wrapper to it.
We provide this module for the compatibility.
If you're writing Gauche-specific code, we recommend to use
@code{binary.io} directly.
@end deftp

@defmac endianness e
[SRFI-74]
@{@t{srfi-74}@}
The argument @var{e} must be either @code{big}, @code{little},
or @code{native}.  It expands to the implementation-specific
endianness designator.  In Gauche, the result is one of the
symbols; @pxref{Endianness}, for the details.
@end defmac

@defun make-blob size
[SRFI-74]
@{@t{srfi-74}@}
Returns a freshly created blob that can hold @var{size} octets.
In Gauche, this is the same as @code{(make-u8vector size)}.
@end defun

@defun blob? obj
[SRFI-74]
@{@t{srfi-74}@}
Returns @code{#t} if @var{obj} is a blob, @code{#f} otherwise.
In Gauche, this is the same as @code{(u8vector? obj)}.
@end defun

@defun blob-length blob
[SRFI-74]
@{@t{srfi-74}@}
Returns the size of the blob, in octets.  In Gauche,
this is the same as @code{(u8vector-length blob)}.
@end defun

@defun blob-uint-ref size endian blob pos
@defunx blob-sint-ref size endian blob pos
[SRFI-74]
@{@t{srfi-74}@}
Read an unsigned or signed integer of @var{size} octets beginning
at the position of @var{pos} from @var{blob}, respectively.

These are wrappers of @code{(get-uint size blob pos endian)}
and @code{(get-sint size blob pos endian)} in @code{binary.io}
module (@pxref{Binary I/O}), except that
@code{blob-uint-ref}/@code{blob-sint-ref} only accept u8vector
as @var{blob}.
@end defun

@defun blob-uint-set! size endian blob pos val
@defunx blob-sint-set! size endian blob pos val
[SRFI-74]
@{@t{srfi-74}@}
Store an unsigned or signed integer @var{val} of @var{size} octets
into @var{blob} starting at the position of @var{pos}, respectively.

These are wrappers of @code{(put-uint! size blob pos val endian)}
and @code{(put-sint! size blob pos val endian)} in @code{binary.io}
module (@pxref{Binary I/O}), except that
@code{blob-uint-set!}/@code{blob-sint-set!} only accept u8vector
as @var{blob}.
@end defun

@defun blob-u8-ref blob pos
@defunx blob-u8-set! blob pos val
@defunx blob-s8-ref blob pos
@defunx blob-s8-set! blob pos val
[SRFI-74]
@{@t{srfi-74}@}
Get/set an unsigned or signed integer as a octet at @var{pos}
from/to @var{blob}.

These are wrappers of @code{get-u8}, @code{put-u8!},
@code{get-s8} and @code{put-s8!} in @code{binary.io}, respectively.
@end defun

@defun blob-u16-ref endian blob pos
@defunx blob-u16-set! endian blob pos val
@defunx blob-s16-ref endian blob pos
@defunx blob-s16-set! endian blob pos val
@defunx blob-u32-ref endian blob pos
@defunx blob-u32-set! endian blob pos val
@defunx blob-s32-ref endian blob pos
@defunx blob-s32-set! endian blob pos val
@defunx blob-u64-ref endian blob pos
@defunx blob-u64-set! endian blob pos val
@defunx blob-s64-ref endian blob pos
@defunx blob-s64-set! endian blob pos val
[SRFI-74]
@{@t{srfi-74}@}
Get/set an unsigned or signed integer of the indicated length
at @var{pos} from/to @var{blob}, using the specified @var{endian}.

These are wrappers of corresponding @code{get-XX} and @code{put-XX!}
in @code{binary.io}; note that the argument orders differ, though.
@end defun

@defun blob-u16-native-ref blob pos
@defunx blob-u16-native-set! blob pos val
@defunx blob-s16-native-ref blob pos
@defunx blob-s16-native-set! blob pos val
@defunx blob-u32-native-ref blob pos
@defunx blob-u32-native-set! blob pos val
@defunx blob-s32-native-ref blob pos
@defunx blob-s32-native-set! blob pos val
@defunx blob-u64-native-ref blob pos
@defunx blob-u64-native-set! blob pos val
@defunx blob-s64-native-ref blob pos
@defunx blob-s64-native-set! blob pos val
[SRFI-74]
@{@t{srfi-74}@}
Get/set an unsigned or signed integer of the indicated length
at @var{pos} from/to @var{blob}, using the native endianness.

These are wrappers of corresponding @code{get-XX} and @code{put-XX!}
in @code{binary.io}; note that the argument orders differ, though.
@end defun

@defun blob=? blob1 blob2
[SRFI-74]
@{@t{srfi-74}@}
This is the same as @code{u8vector=?} in @code{gauche.uvector}.
@end defun

@defun blob-copy! src sstart target tstart n
[SRFI-74]
@{@t{srfi-74}@}
Copy @var{n} octets from the source blob @var{src} starting from @var{sstart}
into the target blob @var{target} starting from @var{tstart}.

Note that the order of arguments differs from other @code{*-copy!}
procedures (e.g. R7RS's @code{string-copy!} and @code{vector-copy!},
and @code{gauche.uvector}'s @code{u8vector-copy!})), which have the
following signature: @code{(*-copy! target tstart src sstart send)}
@end defun

@defun blob-copy blob
[SRFI-74]
@{@t{srfi-74}@}
Returns a fresh copy of @var{blob}.  The same as @code{u8vector-copy}
in @code{gauche.uvector}.
@end defun

@defun blob->u8-list blob
@defunx u8-list->blob list
[SRFI-74]
@{@t{srfi-74}@}
Wrappers of @code{u8vector->list} and @code{list->u8vector}, except
those don't take optional start/end arguments.
@end defun

@defun blob->uint-list size endian blob
@defunx blob->sint-list size endian blob
[SRFI-74]
@{@t{srfi-74}@}
Read a sequence of unsigned or signed integers of @var{size} octets from
@var{blob} with @var{endian}, and returns them as a list.

@example
(blob->uint-list 3 (endianness big) '#u8(0 0 1 0 0 2 0 0 3))
  @result{} (1 2 3)
@end example
@end defun

@defun uint-list->blob size endian list
@defunx sint-list->blob size endian list
[SRFI-74]
@{@t{srfi-74}@}
Convert a @var{list} of unsigned or signed integers to a blob.
The resulting blob has @code{(* size (length list))} octets.
Each integer occupies @var{size} octets.

@example
(uint-list->blob 3 (endianness little) '(1 2 3))
  @result{} #u8(1 0 0 2 0 0 3 0 0)
@end example
@end defun

@c ----------------------------------------------------------------------
@node Lightweight testing, Accessing environment variables, Octet-addressed binary blocks, Library modules - SRFIs
@section @code{srfi-78} - Lightweight testing
@c NODE 軽量なテスト, @code{srfi-78} - 軽量なテスト

@deftp {Module} srfi-78
@mdindex srfi-78
This srfi defines @code{check} and @code{check-ec} macro, along
with a few helper procedures, to write tests.  Especially,
@code{check-ec} uses the same comprehension style as @code{srfi-42}
to run test expressions with various combinations of input easily.

We implemented this module to work with @code{gauche.test}
(@pxref{Unit testing}).
Specifically,
if the check macros are invoked while @code{gauche.test} is active
(that is, between @code{test-start} and @code{test-end}), the check
macros are simply a wrapper of Gauche's @code{test} macro; the results
are tracked and reported by @code{gauche.test}.

If this module is used without @code{gauche.test}, however, it works as
specified by the srfi, including reporting.  So, a tests using this srfi
can be run in both ways---if it is loaded by itself, it runs as vanilla srfi-78,
and if it is included in a test file that uses @code{gacuhe.test}, it runs
as a part of @code{gauche.test}.
@end deftp

@defmac check expr => expected
@defmacx check expr (=> equal) expected
[SRFI-78]
@{@t{srfi-78}@}
Evaluate @var{expected} and @var{equal}, then evaluate @var{expr} and
compare the results of @var{expected} and @var{expr} using @var{equal}.
In the first form, @code{equal?} is used as @var{equal}.
@end defmac

@defmac check-ec qualifier @dots{} expr => expected (argument @dots{})
@defmacx check-ec qualifier @dots{} expr (=> equal) expected (argument @dots{})
@defmacx check-ec qualifier @dots{} expr => expected
@defmacx check-ec qualifier @dots{} expr (=> equal) expected
[SRFI-78]
@{@t{srfi-78}@}
Evaluates @var{expr}, @var{equal} and @var{expected} repeatedly
in the environment where the @var{qualifier}s bind variables,
and each time the results of @var{expr} and @var{equal} are
compared with @var{equal}.  If the results don't agree,
the failure is recorded with the given @var{argument} @dots{}, which can
be useful to diagnose which combination of bindings the test failed on.
Single failure stops the iteration.  If the results of @var{expr} and
@var{expected} agrees on all the iterations, the entire @code{check-ec}
is regarded as success.

The way @var{qualifier}s work is the same as srfi-42.
@xref{Eager comprehensions}, for the details.

The following example tests Fermat numbers (2^2^n + 1) are primes.
It fails since F_5 is a composite.

@example
(use math.prime)
(check-ec (: n 6)
          (:let fn (+ (expt 2 (expt 2 n)) 1))
          (bpsw-prime? fn)
          => #t (n))
 @result{}
 @r{prints} Checking (bpsw-prime? fn), expecting #t => ERROR: got #f, with n: 5
@end example

The entire @code{check-ec} form is treated as one check for the sake of
reporting.
@end defmac

@defun check-report
[SRFI-78]
@{@t{srfi-78}@}
If this module is used stand-alone, prints the summary of test results
to the current output port.

If this module is running inside @code{gauche.test}, this does nothing.
Reporting is done by @code{gauche.test}.
@end defun

@defun check-set-mode! mode
[SRFI-78]
@{@t{srfi-78}@}
Sets how the test progress and result will be reported.  This only has
an effect when check is run without @code{gauche.test}.

Valid @var{mode} is one of the following symbols:
@table @code
@item off
Do not report the result at all, even from @code{(check-report)}.
@item summary
Report the summary of the results when @code{(chec-report)} is called.
@item report-failed
In addition to @code{summary}, report any failed checks as they occur.
@item report
In addition to @code{summary}, report each result of check as they occur.
@end table

The default is @code{report}.
@end defun

@defun check-reset!
[SRFI-78]
@{@t{srfi-78}@}
Clears the internal state to keep track of number of performed checks and
failed checks, etc.  This doesn't affect @code{gauche.test} bookkeeping.
@end defun

@defun check-passed? expected-total-count
[SRFI-78]
@{@t{srfi-78}@}
This can be used to programatically query whether the expected number
of tests are passed since the last @code{check-reset!} or the beginning.
The @var{expected-total-count} must be a number, and it returns @code{#t}
iff the internal count of passed test matches it and there is no failed checks.

This works even if checks are run with @code{gauche.test}.
However, only the tests using @code{check} and @code{check-ec} are counted.
@end defun

@c ----------------------------------------------------------------------
@node Accessing environment variables, Basic socket interface, Lightweight testing, Library modules - SRFIs
@section @code{srfi-98} - Accessing environment variables
@c NODE 環境変数へのアクセス, @code{srfi-98} - 環境変数へのアクセス

@deftp {Module} srfi-98
@mdindex srfi-98
This srfi defines a portable way to access the underlying system's
environment variables.  Gauche supports such procedures built-in
(@pxref{Environment inquiry}),
but portable programs may want to use srfi API instead.
@end deftp

@defun get-environment-variable name
[SRFI-98]
@{@t{srfi-98}@}
Returns a string value of an environment variable named by a string @var{name}.
If the named environment variable doesn't exist, @code{#f} is returned.

This is equivalent to @code{sys-getenv}.
@example
(get-environment-variable "PATH")
  @result{} "/bin:/usr/sbin:/usr/bin"
@end example
@end defun

@defun get-environment-variables
[SRFI-98]
@{@t{srfi-98}@}
Returns an assoc list of the name and the value of each environment
variable.

This is equivalent to @code{sys-environ->alist} without
the optional argument.
@example
(get-environment-variables)
  @result{} (("PATH" . "/bin:/usr/sbin:/usr/bin")
        @dots{})
@end example
@end defun

@c ----------------------------------------------------------------------
@node Basic socket interface, Purely functional random-access pairs and lists, Accessing environment variables, Library modules - SRFIs
@section @code{srfi-106} - Basic socket interface
@c NODE 基本的なソケットインタフェース, @code{srfi-106} - 基本的なソケットインタフェース

@deftp {Module} srfi-106
@mdindex srfi-106
A portable basic socket interface.

Although comprehensive network API is provided by @code{gauche.net}
(@pxref{Networking}), it is Gauche-specific.  This srfi provides
a small subset of socket operations, but it offers a portable way
to create applications that needs simple networking.

Note that some procedures have the same name as the ones in @code{gauche.net},
but the interface may differ.

A socket object created by this srfi's API is an instance
of Gauche's @code{<socket>}, so it can be passed to the API
in @code{gauche.net} and vice versa.

The following procedures are exactly the same as defined in @code{gauche.net}.
@xref{Networking}, for the details.

@example
socket-accept        socket-shutdown       socket-close
socket-input-port    socket-output-port
@end example
@end deftp

@subheading Socket object

@defun make-client-socket node service :optional ai-family ai-socktype ai-flags ai-protocol
[SRFI-106]
@{@t{srfi-106}@}
Creates and returns a socket to
communicate with the node @var{node} and @var{service}.
If the socket type is connection-oriented (that is, @var{ai-socktype} is
@code{*sock-stream*}, which is the default),
the returned socket is already connected.

Both @var{node} and @var{service} must be strings.
The @var{node} argument is passed to @code{getaddrinfo(3)} to resolve
to the server IP address(es).
A service name solely consists of decimal digits is interpreted as
a port number.

The default value of optional arguments are as follows:
@code{*af-inet*} for @var{ai-family},
@code{*sock-stream*} for @var{ai-socktype},
@code{(socket-merge-flags *ai-v4mapped* *ai-addrconfig*)} for
@var{ai-flags}, and @code{*ipproto-ip*} for @var{ai-protocol}.
See below for valid flag values.

This API differs from @code{make-client-socket} in @code{gauche.net}.

@example
(make-client-socket "127.0.0.1" "80")
 @result{} a <socket> connected to port 80 of localhost
@end example
@end defun

@defun make-server-socket service :optional ai-family ai-socktype ai-protocol
[SRFI-106]
@{@t{srfi-106}@}
Creates and returns a server socket that binds and listens at
the port specified by
@var{service}, which must be a string.  A service name solely consists
of decimal digits is interpreted as a port number.

The default value of optional arguments are as follows:
@code{*af-inet*} for @var{ai-family},
@code{*sock-stream*} for @var{ai-socktype},
and @code{*ipproto-ip*} for @var{ai-protocol}.
See below for valid flag values.

This API differs from @code{make-server-socket} in @code{gauche.net}.
@end defun

@defun socket? obj
[SRFI-106]
@{@t{srfi-106}@}
Equivalent to @code{(is-a? obj <socket>)}.
@end defun

@subheading Communication

@defun socket-send socket u8vector :optional flags
[SRFI-106]
@{@t{srfi-106}@}
Almost same as @code{socket-send} in @code{gauche.net}, except that
this procedure only accepts a u8vector as the message.
(The one in @code{gauche.net} can take a string as well.)

Returns the number of octets that are actually sent.
@end defun

@defun socket-recv socket size :optional flags
[SRFI-106]
@{@t{srfi-106}@}
This is like @code{socket-recv} in @code{gauche.net}, except that
this procedure returns the received data in u8vector,
instead of a string.  If the peer has shut down the connection,
this procedure returns an empty u8vector, @code{#u8()}.

The @var{size} argument specifies the maximum size of the receiving
data.  The returned vector may be shorter if that much data is received.
@end defun

@subheading Flags

The srfi provides common names for constants of typical socket flags,
as well as macros that map symbolic name(s) to the flags.

@defun socket-merge-flags flag @dots{}
[SRFI-106]
@{@t{srfi-106}@}
Merge bitwise flags.  This is simply @code{logior} in Gauche.
@end defun

@defun socket-purge-flags base-flag flag @dots{}
[SRFI-106]
@{@t{srfi-106}@}
Drop the bitwise flags in @var{base-flag} that are set
in @var{flag} @dots{}.
@end defun

@subsubheading Address family

@multitable {aaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaa}
@vindex *af-inet*
@vindex *af-inet6*
@vindex *af-unspec*
@item @code{*af-inet*} @tab @code{AF_INET}
@item @code{*af-inet6*} @tab @code{AF_INET6}
@item @code{*af-unspec*} @tab @code{AF_UNSPEC}
@end multitable

@defmac address-family name
@{@t{srfi-106}@}
@var{Name} can be either one of symbols
@code{inet}, @code{inet6}, or @code{unspec}, and
the macro expands into the value of @code{*af-inet*},
@code{*af-inet6*} or @code{*af-unspec*}, respectively.

If @var{name} is other object, an error is signaled.
@end defmac


@subsubheading Socket domain

@multitable {aaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaa}
@vindex *sock-stream*
@vindex *sock-dgram*
@item @code{*sock-stream*} @tab @code{SOCK_STREAM}
@item @code{*sock-dgram*} @tab @code{SOCK_DGRAM}
@end multitable

@defmac socket-domain name
@{@t{srfi-106}@}
@var{Name} can be either one of symbols
@code{stream} or @code{datagram}, and the macro
expands into the value of @code{*sock-stream*} and
@code{*sock-dgram*}, respectively.

If @var{name} is other object, an error is signaled.
@end defmac


@subsubheading Address info

@multitable {aaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaa}
@vindex *ai-canonname*
@vindex *ai-numerichost*
@vindex *ai-v4mapped*
@vindex *ai-all*
@vindex *ai-addrconfig*
@item @code{*ai-canonname*} @tab @code{AI_CANONNAME}
@item @code{*ai-numerichost*} @tab @code{AI_NUMERICHOST}
@item @code{*ai-v4mapped*} @tab @code{AI_V4MAPPED}
@item @code{*ai-all*} @tab @code{AI_ALL}
@item @code{*ai-addrconfig*} @tab @code{AI_ADDRCONFIG}
@end multitable

@defmac address-info name @dots{}
@{@t{srfi-106}@}
Maps combination of names @code{canoname}, @code{numerichost},
@code{v4mapped}, @code{all} and @code{addrconfig}
to the combination of corresponding flags.

An error is signaled if other symbols are passed.
(Note: @code{canoname} for @code{*ai-canonname*}).
@end defmac

@subsubheading Protocol

@multitable {aaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaa}
@vindex *ipproto-ip*
@vindex *ipproto-tcp*
@vindex *ipproto-udp*
@item @code{*ipproto-ip*} @tab @code{IPPROTO_IP}
@item @code{*ipproto-tcp*} @tab @code{IPPROTO_TCP}
@item @code{*ipproto-udp*} @tab @code{IPPROTO_UDP}
@end multitable

@defmac ip-protocol name
@{@t{srfi-106}@}
Maps one of names @code{ip}, @code{tcp}, and @code{udp}
to the corresponding flag value.  An error is signaled
if other symbol is passed.
@end defmac

@subsubheading Message type

@multitable {aaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaa}
@vindex *msg-none*
@vindex *msg-peek*
@vindex *msg-oob*
@vindex *msg-waitall*
@item @code{*msg-none*} @tab 0
@item @code{*msg-peek*} @tab  @code{MSG_PEEK}
@item @code{*msg-oob*} @tab   @code{MSG_OOB}
@item @code{*msg-waitall*} @tab @code{MSG_WAITALL}
@end multitable

@defmac message-type name @dots{}
@{@t{srfi-106}@}
Maps combination of names @code{none}, @code{peek},
@code{oob} and @code{wait-all}
to the combination of corresponding flags.

An error is signaled if other symbols are passed.
(Note: @code{wait-all} for @code{*msg-waitall*}).
@end defmac

@subsubheading Shutdown method

@multitable {aaaaaaaaaaaaaaaa} {aaaaaaaaaaaaaaaaaaaaaa}
@vindex *shut-rd*
@vindex *shut-wr*
@vindex *shut-rdwr*
@item @code{*shut-rd*} @tab @code{SHUT_RD}
@item @code{*shut-wr*} @tab @code{SHUT_WR}
@item @code{*shut-rdwr*} @tab @code{SHUT_RDWR}
@end multitable

@defmac shutdown-method name @dots{}
@{@t{srfi-106}@}
Maps combination of names @code{read} and @code{write}
to the combination of corresponding flags.

An error is signaled if other symbols are passed.
@end defmac

@c ----------------------------------------------------------------------
@node Purely functional random-access pairs and lists, Portable runtime environment inquiry, Basic socket interface, Library modules - SRFIs
@section @code{srfi-101} - Purely functional random-access pairs and lists
@c NODE 純粋に関数的でランダムアクセス可能なペアとリスト, @code{srfi-101} - 純粋に関数的でランダムアクセス可能なペアとリスト

@deftp {Module} srfi-101
@mdindex srfi-101
SRFI-101 has become a part of R7RS large.
@xref{R7RS random-access lists}.

Special treatment of @code{cond-expand}: The feature conditional
@code{cond-expand} implicitly makes the checked library loaded
if available.  That is, you can usually say
@code{(cond-expand (srfi-N <code>))} where @code{<code>} can assume
@code{srfi-N} is already available, without saying @code{(use srfi-N)}.

However, @code{srfi-101} exports the names that conflicts with
standard primitive pair and list operators, and it is generally
useless to import it without prefix or renaming.  Currently @code{cond-expand}
has no way to specify such renaming, so we don't import
@code{srfi-101} by @code{cond-expand}.
You have to say @code{(cond-expand (srfi-101 (use srfi-101 :prefix ra:)))},
for example.
@end deftp

@c ----------------------------------------------------------------------
@node Portable runtime environment inquiry, Comparators, Purely functional random-access pairs and lists, Library modules - SRFIs
@section @code{srfi-112} - Environment inquiry
@c NODE ポータブルな実行環境の問い合わせ, @code{srfi-112} - 実行環境の問い合わせ

@deftp {Module} srfi-112
@mdindex srfi-112
This srfi provides a portable way to obtain runtime information.
@end deftp

@defun implementation-name
[SRFI-112]
@{@t{srfi-112}@}
The name of the implementation.
Returns a string @code{"Gauche"}.
@end defun

@defun implementation-version
[SRFI-112]
@{@t{srfi-112}@}
Returns a string of Gauche's version.  The same as @code{gauche-version}
(@pxref{Environment inquiry}).
@end defun

@defun cpu-architecture
[SRFI-112]
@{@t{srfi-112}@}
Returns a string of CPU architecture info, such as @code{"x86_64"}.
Same as the @code{machine} field of the return value of @code{sys-uname}
(@pxref{System inquiry}).
@end defun

@defun machine-name
[SRFI-112]
@{@t{srfi-112}@}
Returns the host name.  Same as the @code{nodename} field of
the return value of @code{sys-uname}.
(@pxref{System inquiry}).
@end defun

@defun os-name
[SRFI-112]
@{@t{srfi-112}@}
Returns the OS name.  Same as the @code{sysname} field
of the return value of @code{sys-uname}.
@end defun

@defun os-version
[SRFI-112]
@{@t{srfi-112}@}
Returns the OS version.  Same as the @code{release} field
of the return value of @code{sys-uname}.
@end defun

Here's an example of output.  It is likely to differ on your environment.

@example
gosh> (implementation-name)
"Gauche"
gosh> (implementation-version)
"0.9.5"
gosh> (cpu-architecture)
"x86_64"
gosh> (machine-name)
"scherzo"
gosh> (os-name)
"Linux"
gosh> (os-version)
"3.2.0-89-generic"
@end example


@c ----------------------------------------------------------------------
@node Comparators, Simple adjustable-size strings, Portable runtime environment inquiry, Library modules - SRFIs
@section @code{srfi-114} - Comparators
@c NODE 比較器, @code{srfi-114} - 比較器

@deftp {Module} srfi-114
@mdindex srfi-114
This module is provided for the compatibility of code using srfi-114.
The new code should use srfi-128, which is fully built-in.
@end deftp

The following procedures are built-in.  @xref{Basic comparators}, for
the detailed documentation.   Those are also exported from @code{srfi-114}
for the compatibility.

@table @asis
@item Predicates
@code{comparator?},

@item Standard comparators
@code{boolean-comparator},
@code{char-comparator},
@code{char-ci-comparator},
@code{string-comparator},
@code{string-ci-comparator},
@code{symbol-comparator},
@code{exact-integer-comparator},
@code{integer-comparator},
@code{rational-comparator},
@code{real-comparator},
@code{complex-comparator},
@code{number-comparator},
@code{pair-comparator},
@code{list-comparator},
@code{vector-comparator},
@code{bytevector-comparator},
@code{uvector-comparator}

@item The default comparator
@code{default-comparator}

@item Wrapped equality predicates
@code{eq-comparator},
@code{eqv-comparator},
@code{equal-comparator}

@item Accessors
@code{comparator-equality-predicate},
@code{comparator-comparison-procedure},
@code{comparator-hash-function}

@item Primitive applicators
@code{comparator-test-type},
@code{comparator-check-type},
@code{comparator-compare},
@code{comparator-hash}

@item Comparison predicates
@code{=?},
@code{<?},
@code{<=?},
@code{>?},
@code{>=?}
@end table

@subsubheading Basic comparator interface

@defun make-comparator type-test equal compare hash :optional name
[SRFI-114+]
@{@t{srfi-114}@}
This is SRFI-114 style comparator constructor.  The optional @var{name}
argument is Gauche's extension.

This is the same as built-in @code{make-comparator/compare}.
@xref{Basic comparators}, for the details.

Do not confuse this with built-in (SRFI-128) @code{make-comparator};
if you @code{(use srfi-114)}, this one shadows the built-in one.

Note that a comparator works for both SRFI-114 and SRFI-128 procedures,
regardless of how it is constructed.
@end defun

@defun comparator-comparison-procedure? c
@defunx comparator-hash-function? c
[SRFI-114]
@{@t{srfi-114}@}
Returns true iff a comparator @var{c} can be used to order objects
or to hash them, respectively.  These are aliases of
built-in @code{comparator-ordered?} and @code{comparator-hashable?}.
@end defun

@defun comparator-type-test-procedure c
[SRFI-114]
@{@t{srfi-114}@}
Returns type test predicate of a comparator @var{c}.
This is an alias of built-in @code{comparator-type-test-predicate}.
@end defun

@defun comparator-equal? c a b
[SRFI-114]
@{@t{srfi-114}@}
Checks equality of @var{a} and @var{b} using the equality predicate
of a comparator @var{c}.  This can be also written in @code{=?}, which
is built-in (@pxref{Comparator predicates and accessors}).
@example
(=? c a b)
@end example
@end defun


@subsubheading Auxiliary comparator constructors

@defun make-inexact-real-comparator epsilon rounding nan-handling
[SRFI-114]
@{@t{srfi-114}@}
Returns a comparator for inexact real numbers, taking into
account of errors and NaNs.

The basic idea is that we compare two finite real numbers
after rounding them to @var{epsilon} interval, which must be
a nonnegative real number.
(Note that it's not to compare two numbers ``close enough'', as often
being done to compare inexact numbers.  ``Close enough'' scheme
won't be transitive.)

The rounding mode is specified by the @var{rounding} argument.
It can be either one of the symbols @code{round}, @code{ceiling},
@code{floor} or @code{truncate}, or a procedure that takes
two arguments, a real number and an epsilon, and returns
the rounded result of the first argument according to the
given epsilon.

The @var{nan-handling} argument determines how to handle the
case to compare NaN and non-NaN numbers.  (If both are NaNs,
this comparator regards them as equal).  It can be either
one of the followings:
@table @asis
@item @code{min}
If it's a symbol @code{min}, NaN is compared as smaller than
all other real numbers, even than @code{-inf.0}.
@item @code{max}
If it's a symbol @code{min}, NaN is compared as greater than
all other real numbers, even than @code{+inf.0}.
@item @code{error}
If it's a symbol @code{error}, an error is signaled.
@item a procedure taking one argument
The procedure is invoked with the real number which is not NaN.
If it ever returns, it must return either 1, 0 or -1, for
it's used as the result of the comparison procedure of
the comparator.  However, since the procedure doesn't know
@emph{which} argument is non-NaN, it's hard to have consistent
semantics; the best bet is to throw a custom error.
@end table

@example
(define c (make-inexact-real-comparator 0.1 'round 'error))

(comparator-compare c 0.112 0.098) @result{} 0
(comparator-compare c 0.131 0.172) @result{} -1
@end example

Note: Rounding to the nearest epsilon interval would involve
scaling inexact numbers, and that may reveal small difference
between the actual number and its notation.  For example,
an inexact real number denoted as @code{0.15} is actually
slightly smaller than @code{15/100}, and rounding with epsilon
@code{0.1} would result @code{0.1}, not @code{0.2}.
@end defun

@defun make-car-comparator cmpr
@defunx make-cdr-comparator cmpr
[SRFI-114]
@{@t{srfi-114}@}
Returns comparators that accept pairs, and compare them with
their car or cdr by @var{cmpr}, respectively.

Using @code{make-key-comparator}, these cam be written as follows
(@pxref{Combining comparators}, for @code{make-key-comparator}).
@example
(define (make-car-comparator cmpr)
  (make-key-comparator cmpr pair? car))

(define (make-cdr-comparator cmpr)
  (make-key-comparator cmpr pair? cdr))
@end example
@end defun

@defun make-list-comparator element-comparator
@defunx make-vector-comparator element-comparator
@defunx make-bytevector-comparator element-comparator
@{@t{srfi-114}@}
[SRFI-114]
Returns a new comparator that compares lists, vectors and
bytevectors element-wise using @var{element-comparator},
respectively.  These are more general versions of
@code{list-comparator}, @code{vector-comparator} and
@code{bytevector-comparator}, which use @code{default-comparator}
as @var{element-comparator}.

For a list comparator, it is an error to pass improper lists.

Note that comparing sequences of different lengths is slightly
different between lists and vector/bytevectors.  List comparator
uses ``dictionary'' order, so @code{(1 3)} comes after @code{(1 2 3)},
assuming elements are compared numerically.
For vectors and bytevectors, shorter one always precedes the other,
so @code{#(1 3)} comes before @code{#(1 2 3)}.
@end defun

@defun make-listwise-comparator type-test element-comparator empty? head tail
[SRFI-114]
@{@t{srfi-114}@}
More general version of @code{make-list-comparator}.
Returns a comparator that compares structures which can be
traversed using three procedures, @var{empty?}, @var{head} and @var{tail}.
Each of those procedure receives a structure to be compared, and @var{empty?}
must return @code{#t} iff the structure is empty, @var{head}
must return the first element in the structure, and @var{tail}
must return the same type of structure containing all the elements
but the head.  The @var{type-test} predicate checks if the arguments
passed to the comparator to be a suitable structure.

That is, @code{make-list-comparator} can be written in
@code{make-listwise-comparator} as follows.
@example
(make-list-compartator element-comparator)
  @equiv{}
  (make-listwise-comparator list? element-comparator null? car cdr)
@end example

This can be used to compare list-like structures.  For example,
the following call returns a comparator that compares elements
of two lazy streams (@pxref{Stream library}).

@example
(make-listwise-comparator stream?
                          element-comparator
                          stream-null?
                          stream-car
                          stream-cdr)
@end example
@end defun

@defun make-vectorwise-comparator type-test element-comparator length ref
[SRFI-114]
@{@t{srfi-114}@}
More general version of @code{make-vector-comparator}.
Returns a comparator that compares structures which can be
traversed using two procedures, @var{length} and @var{ref}.
The @var{length} procedure must return the number of elements in the
structure.  The @var{ref} procedure receives a structure and a nonnegative
exact integer index @var{k}, and must return @var{k}-th element
of the structure.

That is, the following equivalence holds:
@example
(make-vector-comparator element-comparator)
  @equiv{}
  (make-vectorwise-comparator vector? element-comparator
                              vector-length vector-ref)

(make-bytevector-comparator element-comparator)
  @equiv{}
  (make-vectorwise-comparator u8vector? element-comparator
                              u8vector-length u8vector-ref)
@end example
@end defun

@defun make-pair-comparator car-comparator cdr-comparator
[SRFI-114]
@{@t{srfi-114}@}
Creates a comparator that compares pairs, with their cars
by @var{car-comparator} and their cdrs by @var{cdr-comparator}.
@end defun

@defun make-improper-list-comparator element-comparator
[SRFI-114]
@{@t{srfi-114}@}
This may be understood as recursive pair comparator; if objects
to be compared are pairs, we recurse their cars then their cdrs.
If objects to be compared are not pairs, we use @var{element-comparator}
to compare them.
@end defun

@defun make-selecting-comparator comparator1 comparator2 @dots{}
[SRFI-114]
@{@t{srfi-114}@}
This creates a comparator that works any one of the given comparators;
the objects to be compared are type-tested with each of the comparators
in order, and the first comparator that accepts all objects will be used.
@end defun

@defun make-refining-comparator comparator1 comparator2 @dots{}
[SRFI-114]
@{@t{srfi-114}@}
This is similar to @code{make-selecting-comparator}, except that
if the first comparator that accepts given objects to compare finds
they are equal (or 0 by the comparison procedure), it tries other
comparators down the list, if any.
@end defun

@defun make-reverse-comparator comparator
[SRFI-114]
@{@t{srfi-114}@}
Returns a comparator that just reverses the comparison order of
@var{comparator}.
@end defun

@defun make-debug-comparator comparator
[SRFI-114]
@{@t{srfi-114}@}
@end defun

@subsubheading Comparison procedure constructors

@defun make-comparison< lt-pred
@defunx make-comparison> gt-pred
@defunx make-comparison<= le-pred
@defunx make-comparison>= ge-pred
@defunx make-comparison=/< eq-pred lt-pred
@defunx make-comparison=/> eq-pred gt-pred
[SRFI-114]
@{@t{srfi-114}@}
Utility procedures to create a comparison procedure (the one returns
-1, 0, or 1) from the given predicate.  For example, 
@code{make-comparison<} can be defined as follows:

@example
(define (make-comparison< pred)
  (^[a b] (cond [(pred a b) -1]
                [(pred b a) 1]
                [else 0])))
@end example
@end defun

@subsubheading Comparison syntax

@defmac if3 expr less equal greater
[SRFI-114]
@{@t{srfi-114}@}
Three-way @code{if}: Evaluates @var{expr}, and then evaluates
either one of @var{less}, @var{equal}, or @var{greater},
depending on the value of @var{expr} is either less than zero,
equal to zero, or greater than zero, respectively.
@end defmac

@defmac if=? expr consequent :optional alternate
@defmacx if<? expr consequent :optional alternate
@defmacx if>? expr consequent :optional alternate
@defmacx if<=? expr consequent :optional alternate
@defmacx if>=? expr consequent :optional alternate
@defmacx if-not=? expr consequent :optional alternate
[SRFI-114]
@{@t{srfi-114}@}
Conditional evaluation according to comparison expression @var{expr};
that is, @code{if@var{OP}?} evaluates @var{consequent} if
@code{(@var{OP} expr 0)} is true, otherwise it evaluates @var{alternate}
when provided.

@example
(if<? (compare 10 20) 'yes)      @result{} yes
(if>=? (compare 10 20) 'yes 'no) @result{} no
@end example
@end defmac

@subsubheading Comparison predicate constructors

@defun make=? comparator
@defunx make<? comparator
@defunx make>? comparator
@defunx make<=? comparator
@defunx make>=? comparator
[SRFI-114]
@{@t{srfi-114}@}
@example
((make=? comparator) obj1 obj2 obj3 @dots{})
  @equiv{} (=? comparator obj1 obj2 obj3 @dots{})
@end example
@end defun

@subsubheading Interval comparison predicates


@defun in-open-interval? [comparator] obj1 obj2 obj3
@defunx in-closed-interval? [comparator] obj1 obj2 obj3
@defunx in-open-closed-interval? [comparator] obj1 obj2 obj3
@defunx in-closed-open-interval? [comparator] obj1 obj2 obj3
[SRFI-114]
@{@t{srfi-114}@}
Check if @var{obj1}, @var{obj2} and @var{obj3} has the following
relationships:

@example
(and (op1 obj1 obj2) (op2 obj2 obj3))
@end example

Where each of @var{op1} and @var{op2} can be
@code{(make<? comparator)} (if that end is @emph{open}),
or @code{(make<=? comparator)} (if that end is @emph{closed}).

When @var{comparator} is omitted, the default comparator is used.

@example
(use srfi-42)
(list-ec (: x 0 5) (list x (in-closed-open-interval? 1 x 3)))
  @result{} ((0 #f) (1 #t) (2 #t) (3 #f) (4 #f))
@end example
@end defun

@subsubheading Min/max comparison procedures

@code{comparator-min} and @code{comparator-max} are the
same as @code{srfi-162}.  @xref{Comparator sublibrary}.


@c ----------------------------------------------------------------------
@node Simple adjustable-size strings, Cursor-based string library, Comparators, Library modules - SRFIs
@section @code{srfi-118} - Simple adjustable-size strings
@c NODE 簡単な可変長文字列, @code{srfi-118} - 簡単な可変長文字列

@deftp {Module} srfi-118
@mdindex srfi-118
This SRFI defines two string mutating operations that can change
the length of the string: @code{string-append!} and @code{string-replace!}.

Note that, in Gauche, the body of strings is immutable; when you mutate
a string, Gauche creates a fresh new string body and just switch a pointer
in the original string to point the new string body.  So it is not a
problem to implement this SRFI in Gauche, but it also means you won't
get any performance benefit by using these operations.  Using immutable
counterparts (@code{string-append} and @code{string-replace}) gives
you the same performance.  (Be aware that the interface is slightly
different from the immutable versions.)

We provide this module only for the compatibility.  Gauche-specific
programs should stay away from this module.  Particularly, avoid
code like the example in SRFI-118 document (build a string by
@code{append!}-ing small chunks at a time)---they're quadratic on Gauche.
@end deftp

@defun string-append! string values @dots{}
[SRFI-118]
@{@t{srfi-118}@}
The @var{string} argument must be a mutable string.
Modify @var{string} by appending @var{values}, each of which is
either a character or a string.

@example
(rlet1 a (string-copy "abc")
  (string-append! a #\X "YZ"))
 @result{} "abcXYZ"
@end example
@end defun

@defun string-replace! dst dst-start dst-end src :optional src-start src-end
[SRFI-118]
@{@t{srfi-118}@}
The @var{dst} argument must be a mutable string.
Replace @var{dst} between @var{dst-start} (inclusive) and
@var{dst-end} (exclusive) with a string @var{src}.  The optional
arguments @var{src-start} and @var{src-end} limits the region of
@var{src} to be used.

Be aware that the order of arguments differ from
SRFI-13's @code{string-replace} (@pxref{SRFI-13 Other string operations});
@code{string-replace!} resembles to @code{string-copy!} (also in SRFI-13),
rather than @code{string-replace}.

@example
(rlet1 a (string-copy "abc")
  (string-replace! a 1 2 "XYZ"))
 @result{} "aXYZc"
@end example
@end defun


@c ----------------------------------------------------------------------
@node Cursor-based string library, String library (reduced), Simple adjustable-size strings, Library modules - SRFIs
@section @code{srfi-130} - Cursor-based string library

@deftp {Module} srfi-130
@mdindex srfi-130
This is an reduced version of @code{srfi-13} that supports cursors in
addition to indexes. The consistency with R7RS and recent srfis are
also considered.

The following are built-in.  @xref{String cursors}, for the details.

@example
string-cursor?        string-cursor-start    string-cursor-end
string-cursor-next    strig-cursor-prev      string-cursor-forward
string-cursor-back    string-cursor=?        string-cursor<?
string-cursor<=?      string-cursor>?        string-cursor>=?
string-cursor-diff    string-cursor->index   string-index->cursor
@end example

The following procedures are simply aliases of the builtin version
without the @code{/cursor} or @code{/cursors} suffix.

@example
string->list/cursors  string->vector/cursors string-copy/cursors
string-ref/cursor     substring/cursors
@end example

The following procedures are defined in srfi-13.  @xref{String library},
for the details.  Note: Some of those procedures in srfi-13 accept
only indexes (e.g. @code{string-index}).  In srfi-130, both indexes
and cursors are accepted.  Our srfi-13 implementation shares the same
procedure with srfi-130, so they accept both indexes and cursors but
such code won't be portable as srfi-13.

@example
string-null?       string-any         string-every       string-tabulate
string-unfold      string-unfold-right                   reverse-list->string
string-take        string-drop        string-take-right  string-drop-right
string-pad         string-pad-right   string-trim        string-trim-right
string-trim-both   string-replace     string-prefix-length
string-suffix-length                  string-prefix?     string-suffix
string-concatenate string-concatenate-reverse            string-count
string-filter      string-reverse
@end example

The following procedures are also defined in srfi-13 and redefined in
srfi-130. However, for operations going from left to right, the
srfi-130 version returns a cursor instead of an index when found or
@code{(string-cursor-end)} of the input string when not found.  For
operations going from right to left, it returns a cursor representing
a @emph{successor} of the matching character when found, or
@code{(string-cursor-begin)} of the input string when not found. In
contrast, the srfi-13 version returns either an index when found or
@code{#f} otherwise.

@example
string-fold        string-fold-right   string-index
string-index-right string-skip         string-skip-right
@end example

@code{string-contains} is defined the same as srfi-13. However the
srfi-130 returns a cursor when a string is found, and @code{#f}
otherwise. In contrast, the srfi-13 version returns an index or
@code{#f}. @code{string-contains-right} is similar to
@code{string-contains} except that the searching start from the end of
the string.

@code{string-for-each-cursor} is similar to
@code{string-for-each-index} from srfi-13 but @code{proc} will take
the cursor instead of the index.

@code{xsubstring} and @code{string-delete} in srfi-13 are renamed
@code{string-replicate} and @code{string-remove} respectively in
srfi-130. Similar to srfi-152, the @var{to} argument is required in
@code{string-replicate}.

@code{string-split} is the same as one from srfi-152 or
@code{gauche.stringutil} module.

@end deftp



@c ----------------------------------------------------------------------
@node String library (reduced), First-class dynamic extents, Cursor-based string library, Library modules - SRFIs
@section @code{srfi-152} - String library (reduced)
@c NODE 文字列ライブラリ(簡略版), @code{srfi-152} - 文字列ライブラリ(簡略版)

@deftp {Module} srfi-152
@mdindex srfi-152
This is an improved version of @code{srfi-13}.  The spec is actually smaller
than srfi-13 (hence 'reduced' in the title) by removing bells and whistles.
The consistency with R7RS and recent srfis are also considered.

The following are built-in.  @xref{Strings}, for the details.

@example
string?            make-string        string             string-length
string->vector     string->list       vector->string     list->string
string-ref         string-set!        substring          string-copy
string=?           string<?           string<=?          string>?
string>=?          string-append      string-join        string-split
string-map         string-for-each    read-string        write-string
string-fill!
@end example

The following procedures are defined to use Unicode string case folding,
and @code{gauche.unicode} module provides them.
@xref{Full string case conversion}, for the details.
Note that Gauche's
built-in versions uses character-wise case folding, which differs
from string case folding on some characters (German eszett, for example).

@example
string-ci=?   string-ci<?   string-ci<=?  string-ci>?   string-ci>=?
@end example

The following procedures are defined in srfi-13.  @xref{String library},
for the details.  Note: Some of those procedures in srfi-13 that require
predicate allows a char-set or a character to be passed instead
(e.g. @code{string-filter}).  In srfi-152, only predicate is allowed.
Our srfi-152 implementation shares the same procedure with srfi-13, so
they accept the same arguments as srfi-13's, but such code won't be
portable as srfi-152.

@example
string-null?       string-any         string-every       string-tabulate
string-unfold      string-unfold-right      reverse-list->string
string-take        string-drop        string-take-right  string-drop-right
string-pad         string-pad-right   string-trim        string-trim-right
string-trim-both   string-replace     string-prefix-length string-suffix-length
string-prefix?     string-suffix?     string-index       string-index-right
string-skip        string-skip-right  string-contains    string-concatenate
string-concatenate-reverse            string-fold        string-fold-right
string-count       string-filter      string-copy!
@end example
@end deftp

We describe procedures unique to this module below.

@defun string-remove pred string :optional start end
[SRFI-152]
@{@t{srfi-152}@}
Returns a substring of @var{string} between @var{start} and @var{end},
except characters that satisfy @var{pred}.   In other words,
it is @code{(string-filter (complement pred) string start end)}.

This is called @var{string-delete} in @code{srfi-13}.  Being changed
to take only a predicate (but not a character), it is renamed for
the consistency of other srfi (e.g. @code{filter}, @code{remove} and
@code{delete} in srfi-1.)

@example
(string-remove char-whitespace?
               "Quick fox jumps over the lazy dog"
               3 22)
 @result{} "ckfoxjumpsovert"
@end example
@end defun

@defun string-replicate string from to :optional start end
[SRFI-152]
@{@t{srfi-152}@}
Extended substring.  It is called @code{xsubstring} in srfi-13, but
renamed for the consistency.

Extract a substring of @var{string} between @var{start} and @var{end},
and conceptually create a bidirectional infinite string by repeating
the substring to both direction.  For example, suppose @var{string}
is @code{"abcde"}, @var{start} is 1, and @var{end} is 4.  So we repeat
the substring @code{"bcd"}, with one @code{b} falling on the index zero:

@example
... b  c  d  b  c  d  b  c  d  b  c  d  b ... 
   -6 -5 -4 -3 -2 -1  0  1  2  3  4  5  6
@end example

Then we extract a substring between @var{from} and @var{to}
out of this infinite string.

@example
(string-replicate "abcde" 2 10 1 4)
  @result{} "dbcdbcdb"
(string-replicate "abcde" -5 -3 1 4)
  @result{} "cdbcdbcd"
@end example
@end defun

@defun string-segment string k
[SRFI-152]
@{@t{srfi-152}@}
Splits @var{string} by every @var{k} characters and returns
a list of those strings.  The last string may be shorter than @var{k}.

@example
(string-segment "abcdefghijklmn" 3)
 @result{} ("abc" "def" "ghi" "jkl" "mn")
@end example

We have a similar procedure on lists, @code{slices}
(@pxref{List accessors and modifiers}).
@end defun

@defun string-contains-right string1 string2 :optional start1 end1 start2 end2
[SRFI-152]
@{@t{srfi-152}@}
Like @code{string-contains}, looks for a needle @var{string2} from
a haystack @var{string1}, but if it is found, returns the start index
of the @emph{last} match, instead of the first match.  The returned index
is in @var{string1}.  The optional arguments limit the range of a needle
and a haystack.  If a needle isn't found, @code{#f} is returned.

An edge case: If a needle is empty (e.g. @var{string2} is empty,
or @var{start2} = @var{end2}), it always matches right after the haystack,
so @var{end1} is returned.

@example
(string-contains-right "Little Lisper" "Li")
  @result{} 7
@end example
@end defun

@defun string-take-while string pred :optional start end
@defunx string-take-while-right string pred :optional start end
[SRFI-152]
@{@t{srfi-152}@}
Returns the longest prefix or suffix of @var{string} in which all characters
satisfy @var{pred}.

Note: The order of @var{pred} and the source object is different from
other @code{take-while}-style procedures, such as @code{take-while}
(@ref{R7RS lists}), @code{ideque-take-while} (@ref{R7RS immutable deques}),
and @code{lseq-take-while} (@ref{R7RS lazy sequences}).
@end defun

@defun string-drop-while string pred :optional start end
@defunx string-drop-while-right string pred :optional start end
[SRFI-152]
@{@t{srfi-152}@}
Returns the longest prefix or suffix of @var{string} in which all characters
does not satisfy @var{pred}.

Note: The order of @var{pred} and the source object is different from
other @code{drop-while}-style procedures, such as @code{drop-while}
(@ref{R7RS lists}), @code{ideque-drop-while} (@ref{R7RS immutable deques}),
and @code{lseq-drop-while} (@ref{R7RS lazy sequences}).
@end defun

@defun string-span string pred :optional start end
@defunx string-break string pred :optional start end
[SRFI-152]
@{@t{srfi-152}@}
Find the longest prefix of @var{string} between @var{start} and @var{end}
in which all characters satisy / do not satisfy @var{pred}, and returns
the prefix and the rest of substring as two values.

@example
(string-break "foo@@example.com" (cut eqv? <> #\@@))
 @result{} "foo" @r{and} "@@example.com"

(string-break "foo@@example.com" (cut eqv? <> #\@@) 1 10)
 @result{} "oo" "@@exampl"

;; This is Gauche specific - a char-set can work as a predicate:
(string-span "VAR_1 = $VAR_2" #[\w])
 @result{} "VAR_1" @r{and} " = $VAR_2"
@end example

Note: The order of @var{pred} and the source object is different from
@code{span} and @code{break} in @code{scheme.list}
(@pxref{R7RS lists}).
@end defun

@c ----------------------------------------------------------------------
@node First-class dynamic extents, Homogeneous numeric vector libraries, String library (reduced), Library modules - SRFIs
@section @code{srfi-154} - First-class dynamic extents
@c NODE 第一級の動的エクステント, @code{srfi-154} - 第一級の動的エクステント

@deftp {Module} srfi-154
@mdindex srfi-154
This module provides a convenient way to reify the dynamic environment.
A continuation captured by @code{call/cc} includes the dynamic environment,
as well as the control flow.  Sometimes you only want the dynamic environment
part.  A dynamic extent is a reified dynamic environment.

Let's see an example.  You want a procedure that prints out
a message to the error port, so you wrote this @code{print-error}:

@example
(define print-error
  (lambda (msg) (display msg (current-error-port))))
@end example

However, if @code{print-error} is called while the current error port
is altered, it is affected.  It is supposed to be so, that's
the point of @code{current-error-port}.

@example
(call-with-output-string
  (^p (with-error-to-port p (^[] (print-error "abc\n")))))
 @result{} "abc\n"
@end example

If you do want @code{print-error} to use the error port
at the time it is defined, you have to extract the dynamic value
at the moment.

@example
(define print-error
  (let1 eport (current-error-port)
    (lambda (msg) (display msg eport))))
@end example

This would be quickly cumbersome when you need to capture multiple
dynamic values, or the original @code{print-error} is called indirectly
and you can't modify it the way shown above.

Using @code{dynamic-lambda} addresses this issue.  It not only captures
the lexical environment, but also the dynamic environment when it
is evaluated.  So the @code{current-error-port} in its body
returns the current error port at the time of @code{print-error}
being defined, not when it is called:

@example
(define print-error
  (dynamic-lambda (msg) (display msg (current-error-port))))
@end example
@end deftp

@defun current-dynamic-extent
[SRFI-154]
@{@t{srfi-154}@}
Returns a dynamic-extent object that reifies the current dynamic
environment.
@end defun

@defun dynamic-extent? obj
[SRFI-154]
@{@t{srfi-154}@}
Returns @code{#t} iff @var{obj} is a dynamic-extent object.
@end defun

@defun with-dynamic-extent dynext thunk
[SRFI-154]
@{@t{srfi-154}@}
Calls the @var{thunk} in the dynamic extent @var{dynext}, and
returns the values yielded by @var{thunk}.
@end defun

@defmac dynamic-lambda formals body @dots{}
[SRFI-154]
@{@t{srfi-154}@}
Like @code{lambda}, but this not only captures the lexical environment,
but also the dynamic environment.  Yields a procedure.

Note: Since @code{dynamic-lambda} needs to swap the dynamic environment
after executing @var{body}, the last expression of @var{body} isn't
called in the tail context even if the procedure created by
@code{dynamic-lambda} is called in tail context.
@end defmac



@c ----------------------------------------------------------------------
@node Homogeneous numeric vector libraries, Comparator sublibrary, First-class dynamic extents, Library modules - SRFIs
@section @code{srfi-160} - Homogeneous numeric vector libraries
@c NODE 均質な数値ベクタライブラリ, @code{srfi-160} - 均質な数値ベクタライブラリ

@deftp {Module} srfi-160
@mdindex srfi-160
This is an enhancement of srfi-4, Homogeneous vectors
(@pxref{Homogeneous vectors}), and then become a part
of R7RS-large (@pxref{R7RS uniform vectors}).

In Gauche, all the procedures in this module are provided
as a part of @code{gauche.uvector} module
(@pxref{Uniform vectors}, and described there.

This module only exports the procedures defined in @code{srfi-160}.
@end deftp

@c ----------------------------------------------------------------------
@node Comparator sublibrary, POSIX API, Homogeneous numeric vector libraries, Library modules - SRFIs
@section @code{srfi-162} - Comparator sublibrary
@c NODE 比較器のサブライブラリ, @code{srfi-162} - 比較器のサブライブラリ

@deftp {Module} srfi-162
@mdindex srfi-162
This is a supplement of srfi-128, comparators.  It provides
a few comparator procedures, as well as several useful
pre-defined comparators, listed below.
Theese pre-defined comparators are already built in Gauche,
so see @ref{Predefined comparators} for the details.

@example
default-comparator    boolean-comparator    real-comparator
char-comparator       char-ci-comparator    string-comparator
string-ci-comparator  pair-comparator       list-comparator
vector-comparator     eq-comparator         eqv-comparator
equal-comparator
@end example
@end deftp

@defun comparator-min comparator obj obj2 @dots{}
@defunx comparator-max comparator obj obj2 @dots{}
[SRFI-162]
@{@t{srfi-162}@}
Find the object in @var{obj1} @var{obj2} @dots{} that is
minimum or maximum compared by @var{comparator}.
Note: Srfi-114 provides the same procedures.

@example
(comparator-min list-comparator '(a c b) '(a d) '(a c))
  @result{} (a c)
@end example
@end defun

@defun comparator-min-in-list comparator list
@defunx comparator-min-in-list comparator list
[SRFI-162]
@{@t{srfi-162}@}
Find the object in @var{list} that is minimum or maximum compared
by @var{comparator}.  It is an error if @var{list} is empty.
@end defun

@c ----------------------------------------------------------------------
@node POSIX API, Hooks (srfi), Comparator sublibrary, Library modules - SRFIs
@section @code{srfi-170} - POSIX API

@deftp {Module} srfi-170
@mdindex srfi-170
This module provides a portable interface to a part of POSIX API,
mainly filesystem interface.

In Gauche, it is a thin wrapper of Gauche's native system interface
(@pxref{System interface}).  You may want to use this module for
a portable code.
@end deftp

@subheading POSIX Error

@defun posix-error? obj
[SRFI-170]
@{@t{srfi-170}@}
Returns @code{#t} iff @var{obj} is a condition thrown due to
underlying POSIX-layer error.  On Gauche, POSIX-layer condition
is the same as @code{<system-error>} (@pxref{Conditions}).
@end defun

@defun posix-error-name err
[SRFI-170]
@{@t{srfi-170}@}
The argument must be a POSIX-layer condition (@code{<system-error>} object).
Returns the POSIX error name such as @code{ENOENT}.

See also @code{sys-errno->symbol} (@pxref{System inquiry}).
@end defun

@defun posix-error-message err
[SRFI-170]
@{@t{srfi-170}@}
The argument must be a POSIX-layer condition (@code{<system-error>} object).
Returns the error message describing the error.

See also @code{sys-strerror} (@pxref{System inquiry}).
@end defun

@subheading I/O

@defun open-file fname port-type flags :optional permission buffer-mode
[SRFI-170]
@{@t{srfi-170}@}
Opens a file named by @var{fname} and returns a port to read or write
the file.  You have finer control than
@code{open-input-file}/@code{open-output-file}.

The @code{port-type} argument must be either one of the value
of the constant @code{binary-input}, @code{textual-input},
@code{binary-output}, @code{textual-output} and
@code{binary-input/output}.  The direction of the returned port
is determined by this argument.

Gauche doesn't distinguish textual ports and binary ports.

The @var{flags} argument is a bitwise ior of
zero or more of the following bitmasks:
@code{open/append}, @code{open/create}, @code{open/exclusive},
@code{open/nofollow} and @code{open/truncate}.  These corresponds
to the POSIX flags @code{O_APPEND}, @code{O_CREAT}, @code{O_EXCL},
@code{O_NOFOLLOW} and @code{O_TRUNC}.  Gauche exposes the POSIX flags
in @code{gauche.fcntl} (@pxref{Low-level file operations}).

Note: POSIX @code{open(2)} also requires one of the bitmasks
@code{O_RDONLY}, @code{O_WRONLY} and @code{O_RDWR}.  These flags
are deduced from the @var{port-type} argument.

The optional @var{permission} is an integer permission bits
to be used when a new file is created.  The actual permission bits
are also affected by the current @code{umask}.

The optional @var{buffer-mode} is a value of either one of the followings:
@code{buffer-none}, @code{buffer-block}, and @code{buffer-line}.
@end defun

@defun fd->port fd port-type :optional buffer-mode
[SRFI-170]
@{@t{srfi-170}@}
Creates a Scheme port wrapping an integer file descriptor @var{fd}.
The descriptor shouldn't be used by other Scheme ports.  After calling
this procedure, no I/O should be done via @var{fd} directly; the descriptor
is ``owned'' by the port, and will be closed once the port is closed.

The @code{port-type} argument must be either one of the value
of the constant @code{binary-input}, @code{textual-input},
@code{binary-output}, @code{textual-output} and
@code{binary-input/output}.  The direction must match how @var{fd} was
opened.

The optional @var{buffer-mode} is a value of either one of the followings:
@code{buffer-none}, @code{buffer-block}, and @code{buffer-line}.
@end defun

@defvr {Constant} binary-input
@defvrx {Constant} textual-input
@defvrx {Constant} binary-output
@defvrx {Constant} textual-output
@defvrx {Constant} binary-input/output
[SRFI-170]
@{@t{srfi-170}@}
Constants to be used as @var{port-type} argument of
@code{open-file} and @code{fd->port}.
@end defvr

@defvr {Constant} buffer-none
@defvrx {Constant} buffer-block
@defvrx {Constant} buffer-line
[SRFI-170]
@{@t{srfi-170}@}
Constants to be used as @var{buffer-mode} argument of
@code{open-file} and @code{fd->port}.
@end defvr

@defvr {Constant} open/append
@defvrx {Constant} open/create
@defvrx {Constant} open/exclusive
@defvrx {Constant} open/nofollow
@defvrx {Constant} open/truncate
[SRFI-170]
@{@t{srfi-170}@}
Bitmask constants to be used as @var{flags} argument of
@code{open-file}.
@end defvr

@subheading File System

@defun create-directory fname :optional permission
@defunx create-fifo fname :optional permission
@defunx create-hard-link old-fname new-fname
@defunx create-symlink old-fname new-fname
[SRFI-170]
@{@t{srfi-170}@}
Corresponds to Gauche's built-in @code{sys-mkdir}, @code{sys-mkfifo},
@code{sys-link} and @code{sys-symlink}.

The default value of @var{permission} is @code{#o775} for 
@code{create-directory}, and @code{#o664} for @code{create-fifo}
(It's not optoinal for Gauche's built-in).

On Windows, @code{create-fifo} and @code{create-symlink} are
not supported.  Procedures exist, but raise an error when called.
@end defun

@defun read-symlink name
[SRFI-170]
@{@t{srfi-170}@}
Gauche's @code{sys-readlink}.
@end defun

@defun rename-file old new
[SRFI-170]
@{@t{srfi-170}@}
Gauche's @code{sys-rename}.
@end defun

@defun delete-directory name
[SRFI-170]
@{@t{srfi-170}@}
Gauche's @code{sys-rmdir}.  The directory must be empty.
@end defun

@defun set-file-owner fname uid gid
[SRFI-170]
@{@t{srfi-170}@}
Gauche's @code{sys-chown}.  The @var{uid} and @var{gid} arguments
should be an integer uid/gid, or the value of the constant
@code{owner/unchanged} and @code{group/unchanged}, respectively,
to indicate to keep the original value.
@end defun

@defvr {Constant} owner/unchanged
@defvrx {Constant} group/unchanged
[SRFI-170]
@{@t{srfi-170}@}
Constants to be passed as @var{uid} and @var{gid} arguments
of @code{set-file-owner}, respectively.
@end defvr


@defun set-file-times funame :optional atime mtime
[SRFI-170]
@{@t{srfi-170}@}
Gauche's @code{sys-utime}.  The @var{atime} and @var{mtime}
arguments must be a @code{<time>} object (@pxref{Time}), or
either one of the values of constants @code{time/now} or
@code{time/unchanged}.  The constant @code{time/now}
indicates the time when the procedure is called,
and the constant @code{time/unchanged} indicates the
corresponding timestamp remains the same.
@end defun

@defvr {Constant} time/now
@defvrx {Constant} time/unchanged
[SRFI-170]
@{@t{srfi-170}@}
Constants that can be passed to @var{atime} and @var{mtime}
arguments of @code{set-file-times}.
@end defvr

@defun truncate-file fname-or-port len
[SRFI-170]
@{@t{srfi-170}@}
The first argument can be a string filename or a open port associated
to a file.  If it is a filename, @code{sys-truncate} is called,
and if it is a port, @code{sys-ftruncate} is called.
@end defun

@defun file-info fname-or-port follow?
[SRFI-170]
@{@t{srfi-170}@}
Gauche's @code{sys-stat}, @code{sys-lstat} or @code{sys-fstat}.

The first argument can be a string filename or a open port associated
to a file.  If it is a filename, @code{sys-stat} or @code{sys-lstat}
is called depending on whether @var{follow?} is @code{#t} or @code{#f}.
If it is a port, @code{sys-fstat} is called.

Returns a file-info object, which is a @code{<sys-stat>} instance
in Gauche (@pxref{File stats}).
@end defun

@defun file-info? obj
[SRFI-170]
@{@t{srfi-170}@}
Returns @code{#t} iff @var{obj} is a file-info object, which is
a @code{<sys-stat>} instance in Gauche (@pxref{File stats}).
@end defun

@defun file-info:device file-info
@defunx file-info:inode file-info
@defunx file-info:mode file-info
@defunx file-info:nlinks file-info
@defunx file-info:uid file-info
@defunx file-info:gid file-info
@defunx file-info:rdev file-info
@defunx file-info:size file-info
@defunx file-info:blksize file-info
@defunx file-info:blocks file-info
@defunx file-info:atime file-info
@defunx file-info:mtime file-info
@defunx file-info:ctime file-info
[SRFI-170]
@{@t{srfi-170}@}
Accessorso of file-info object (@code{<sys-stat>}) (@pxref{File stats}).
Access its @code{dev}, @code{ino}, @code{mode}, @code{nlink},
@code{uid}, @code{gid}, @code{rdev}, @code{size},
@code{blksize}, @code{blocks}, @code{atim}, @code{mtim}, @code{ctim}
slots, respectively.

Note: @code{<sys-stat>}'s @code{atime}, @code{mtime} and @code{ctime}
contains integer for the backward compatibility, while
@code{file-info:atime}, @code{file-info:mtime} and @code{file-info:ctime}
returns @code{<time>} object.
@end defun

@defun file-info-directory? file-info
@defunx file-info-fifo? file-info
@defunx file-info-symlink? file-info
@defunx file-info-regular? file-info
@defunx file-info-socket? file-info
@defunx file-info-device? file-info
[SRFI-170]
@{@t{srfi-170}@}
Returns true iff the file-info object (@code{<sys-stat>} is of the
respective type.  (@code{file-info-device?} returns true if
the file is either block or character device).
It corresponds to the @code{type} slot of @code{<sys-stat>}.
@end defun

@defun set-file-mode fname mode-bits
[SRFI-170]
@{@t{srfi-170}@}
Gauche's @code{sys-chmod}.
@end defun

@defun directory-files dir :optional dotfiles?
[SRFI-170]
@{@t{srfi-170}@}
Returns a list of filenames in the directory named @var{dir}.
Similar to @code{directory-list} in @code{file.util}
(@pxref{Directory utilities}), but (1) it never includes
@code{.} and @code{..} (as true value is given to @code{:children?}
argument of @code{directory-list}), and (2) it doesn't include
files beginning with @code{.} by default, unless @code{dotfiles?} is true.
@end defun

@defun make-directory-files-generator dir :optional dotfiles?
[SRFI-170]
@{@t{srfi-170}@}
Returns a generator (@pxref{Generators}) that generates file names
in the directory named @var{dir}.  The names never include
@code{.} and @code{..}, and the filenames beginning with @code{.} is
omitted unless @var{dotfiles?} is true.
@end defun

@defun open-directory dir :optional dotfiles?
@defunx read-directory dir-object
@defunx close-directory dir-object
[SRFI-170]
@{@t{srfi-170}@}
This is a directory scanner API more close to POSIX @code{opendir},
@code{readdir} and @code{closedir}.  A directory object is opened
with @code{open-directory}, and its entries (filenames) can be read
one by one using @code{read-directory}.  If the file names are exausted,
@code{read-directory} returns an EOF object.  A directory object
must be closed with @code{close-directory}.

The filenames to be retrieved are the same as @code{directory-files}; that is,
@code{.} and @code{..} are never included, and names beginning with @code{.}
is exluded unless @var{dotfiles?} is true.
@end defun

@defun real-path path
[SRFI-170]
@{@t{srfi-170}@}
Gauche's @code{sys-realpath}.
@end defun

@defun file-space path-or-port
[SRFI-170]
@{@t{srfi-170}@}
Returns the free space of a file system where a file specified by
@var{path-or-port} resides, in number of bytes.
@end defun

@deffn {Parameter} temp-file-prefix
[SRFI-170]
@{@t{srfi-170}@}
A parameter holding a path prefix to be used by @code{create-temp-file}
and @code{call-with-temporary-filename}.  In Gauche,
the default value is set to
@code{(build-path (temporary-directory) (x->string (sys-getpid)))}.
@xref{Temporary files and directories}, for the description of
@code{temporary-directory}.
@end deffn

@defun create-temp-file :optional prefix
[SRFI-170]
@{@t{srfi-170}@}
@end defun

@defun call-with-temporary-filename maker :optional prefix
[SRFI-170]
@{@t{srfi-170}@}
@end defun

@subheading Process state

Note: For srfi-170's @code{current-directory}, we reuse
@code{file.util}'s one.  @xref{Directory utilities}, for the description.

@defun umask
[SRFI-170]
@{@t{srfi-170}@}
Returns the current umask value.
Gauche's @code{sys-umask} without argument.
@end defun

@defun set-umask! mask
[SRFI-170]
@{@t{srfi-170}@}
Sets @var{mask}, which must be a nonnegative exact integer, 
as the current umask.
Gauche's @code{sys-umask}, except that it returns unspecified value.
@end defun

@defun set-current-directory! dir
[SRFI-170]
@{@t{srfi-170}@}
Sets the process's current working directory to @var{dir}.
Gauche's @code{sys-chdir}.
It can also be done with @code{current-working-directory} in @code{file.util}
(@pxref{Directory utilities}).
@end defun

@defun pid
[SRFI-170]
@{@t{srfi-170}@}
Returns the current process id.  Gauche's @code{sys-getpid}.
@end defun

@defun nice :optional delta
[SRFI-170]
@{@t{srfi-170}@}
Increments the current process's nice value by @var{delta}, which must
be an exact integer.  The lower the nice value is, the more chance
the process gets run.  If omitted, @var{delta} is assumed to be 1.
Gauche's @code{sys-nice}.
@end defun

@defun user-uid
@defunx user-gid
@defunx user-effective-uid
@defunx user-effecitve-gid
@defunx user-supplementary-gids
[SRFI-170]
@{@t{srfi-170}@}
Gauche's @code{sys-getuid}, @code{sys-getgid}, @code{sys-geteuid},
@code{sys-getegid}, and @code{sys-getgroups}, respectievly.
@end defun

@subheading User and group database access

@defun user-info uid-or-name
[SRFI-170]
@{@t{srfi-170}@}
Returns a user-info object, which is a @code{<sys-passwd>} instance
in Gauche, of a user specified by @var{uid-or-name}, which must be
an exact integer uid or a string username.
If it is an uid, @var{sys-getpwuid} is called, and if it is a username
@code{sys-getpwnam} is called.
@end defun

@defun user-info? obj
[SRFI-170]
@{@t{srfi-170}@}
Returns @code{#t} iff @var{obj} is a user-info object (@code{<sys-passwd>}).
@end defun

@defun user-info:name uinfo
@defunx user-info:uid uinfo
@defunx user-info:gid uinfo
@defunx user-info:home-dir uinfo
@defunx user-info:shell uinfo
@defunx user-info:full-name uinfo
[SRFI-170]
@{@t{srfi-170}@}
Returns the value of @var{name}, @code{uid}, @code{gid}, @code{dir},
@code{shell} and @var{gecos} slots of a user-info object (@code{<sys-passwd})
@var{uinfo}.
@end defun

@defun user-info:parsed-full-name uinfo
[SRFI-170]
@{@t{srfi-170}@}
@end defun

@defun group-info gid-or-name
[SRFI-170]
@{@t{srfi-170}@}
Returns a group-info object, which is a @code{<sys-group>} instance
in Gauche, of a group specified by @var{gid-or-name}, which must be
an exact integer gid or a string groupname.
If it is an gid, @var{sys-getgrgid} is called, and if it is a groupname
@code{sys-getgrnam} is called.
@end defun

@defun group-info? obj
[SRFI-170]
@{@t{srfi-170}@}
Returns @code{#t} iff @var{obj} is a group-info object (@code{<sys-group}).
@end defun

@defun group-info:name ginfo
@defunx group-info:gid ginfo
[SRFI-170]
@{@t{srfi-170}@}
Returns the value of @code{name} and @code{gid} slot of a group info
(@code{<sys-group>}).
@end defun

@subheading Time

@defun posix-time
[SRFI-170]
@{@t{srfi-170}@}
Same as @code{current-time} (@pxref{Time}).  Return value is a @code{<time>}
instance of @code{time-utc}.
@end defun

@defun monotonic-time
[SRFI-170]
@{@t{srfi-170}@}
Returns a @code{<time>} instance of @code{time-monotonic}, representing
a elapsed time since an unspecified epoch.  It is guaranteed to monotonically
increasing during the lifetime of the process, even if the system clock
is modified.
@end defun

@subheading Environment variables

@xref{Accessing environment variables}, for getting environment variables.
This srfi defines the means to modify them.

@defun set-enviroment-variable! name value
[SRFI-170]
@{@t{srfi-170}@}
Gauche's @code{sys-setenv} with the third argument being @code{#t}
(overwrite the existing value).
@end defun

@defun delete-environment-variable! name
[SRFI-170]
@{@t{srfi-170}@}
Gauche's @code{sys-unsetenv}.
@end defun

@subheading Terminal device control

@defun terminal? port
[SRFI-170]
@{@t{srfi-170}@}
Gauche's @code{sys-isatty}.
@end defun

@c ----------------------------------------------------------------------
@node Hooks (srfi), POSIX timespecs, POSIX API, Library modules - SRFIs
@section @code{srfi-173} - Hooks (srfi)
@c NODE フック(srfi), @code{srfi-173} - フック(srfi)

@deftp {Module} srfi-173
@mdindex srfi-173
This module provides hooks, which manages a list of
closures to be called.

It is based on Guile's hooks, which Gauche supports in
@code{gauche.hook} module (@pxref{Hooks}).  This srfi
is a thin layer on top of @code{gauche.hook}.

The following procedures are the same as @code{gauche.hook}:

@example
make-hook     hook?      hook->list
@end example
@end deftp

@defun hook-add! hook proc
[SRFI-173]
@{@t{srfi-173}@}
Add a procedure @var{proc} to a hook @var{hook}.   The procedure
must accept the number of arguments that matches the arity of the hook.
It is the same as @code{(add-hook! hook proc)} of @code{gauche.hook}.
@end defun

@defun hook-delete! hook proc
[SRFI-173]
@{@t{srfi-173}@}
Delete @var{proc} from @var{hook}.  If @var{proc} isn't in @var{hook},
do nothing.  It is the same as @code{(delete-hook! hook proc)}
of @code{gauche.hook}.
@end defun

@defun hook-reset! hook
[SRFI-173]
@{@t{srfi-173}@}
Remove all the procedures registered in @var{hook}.
It is the same as @code{(reset-hook! hook)} of @code{gauche.hook}.
@end defun

@defun hook-run hook args @dots{}
[SRFI-173]
@{@t{srfi-173}@}
Apply all the procedures from @var{hook} to the @var{args}.
The order of the procedure isn't specified in the srfi, though
Gauche preserves the order (see @code{run-hook}
(@pxref{Hooks}).
@end defun

@defun list->hook arity list
[SRFI-173]
@{@t{srfi-173}@}
Creates a new hook with specified @var{arity} (which is a non-negative
exact integer), which has the procedures in @var{list}.
All the procedures must accept @var{arity} number of arguments.
@end defun

@defun list->hook! hook list
[SRFI-173]
@{@t{srfi-173}@}
Replace the list of procedures in @var{hook} with procedures
in @var{list}.
All the procedures must accept the number of arguments
the same as @var{hook}'s arity.
@end defun

@c ----------------------------------------------------------------------
@node POSIX timespecs, ASCII character library, Hooks (srfi), Library modules - SRFIs
@section @code{srfi-174} - POSIX timespecs

@deftp {Module} srfi-174
@mdindex srfi-174
Note: This srfi is originally intended to be used with srfi-170
(@pxref{POSIX API}), but it turned out this was not enough to support
the latter--notably, we need srfi-19 type argument in the constructor.

Consequently, it is likely that this srfi will be superseded later.
We deprecate using this srfi; if you need a portable time representation,
srfi-19 is the best choice at this moment.  @xref{Time data types and procedures},
for the details.
@end deftp

@defun timespec secs nsecs
[SRFI-174]
@{@t{srfi-174}@}
Creates and returns a timespec, whose second part is @var{secs} and
nanosecond part is @var{nsecs}.  The second part must be an exact
integer; if it is positive, it's the number of seconds since
Epoch (Jan 1, 1970 UTC), and if it's negative, it's before the Epoch.
The nanosecond part is a nonnegative integer less than 1e9, and represents
the fraction of seconds in nanosecond resolution.  Note that if the second
part is negative, the nanosecond part counts toward past.

This is the same as @code{(make-time time-utc nsecs secs)} of
srfi-19.  Note the order of arguments.
@end defun

@defun timespec? obj
[SRFI-174]
@{@t{srfi-174}@}
Returns @code{#t} iff @var{obj} is a @code{<time>} object.  It doesn't
check the type of time.
@end defun

@defun timespec-seconds ts
@defunx timespec-nanosecods ts
[SRFI-174]
@{@t{srfi-174}@}
Returns second and nanosecond part of the @code{<time>} object.
Same as @code{time-second} and @code{time-nanosecond} of srfi-19
(note that we use plurals in this srfi).
@end defun

@defun inexact->timespec v
[SRFI-174]
@{@t{srfi-174}@}
Convert an inexact real number @var{v} to a timespec.  The integral part
of @var{v} is the seconds after (when @var{v} is positive)  
or before (when @var{v} is negative) the Epoch, and the fractional part
is rounded into nanosecond resolution.
@end defun

@defun timespec->inexact ts
[SRFI-174]
Convert a timespec into an inexact real number in seconds.
@{@t{srfi-174}@}
@end defun

@defun timespec=? ts1 ts2
[SRFI-174]
@{@t{srfi-174}@}
Returns @code{#t} iff two timespecs are the same.
It is the same as @code{time=?} in srfi-19.
@end defun

@defun timespec<? ts1 ts2
[SRFI-174]
@{@t{srfi-174}@}
Returns @code{#t} iff a timespec @var{ts1} is strictly before
the timespec @var{ts2}.  It is the same as @code{time<?} in srfi-19.
@end defun

@defun timespec-hash ts
[SRFI-174]
@{@t{srfi-174}@}
Compute a hash value of a timespec @var{ts}.  It is same as
passing a @code{<time>} object to @code{default-hash}, and
affected by the current hash salt value (@pxref{Hashing}).
@end defun

@c ----------------------------------------------------------------------
@node ASCII character library, Bitvector library, POSIX timespecs, Library modules - SRFIs
@section @code{srfi-175} - ASCII character library
@c NODE ASCII文字ライブラリ, @code{srfi-175} - ASCII文字ライブラリ

@deftp {Module} srfi-175
@mdindex srfi-175
This module provides a set of character/string utilities that deal with
ASCII characters and codepoints.  It is particulary useful for small
Scheme implementations that only handles, and a portable
code that only concerns, ASCII characters.

Since Gauche supports full Unicode (if it is compiled with utf-8 internal
encoding, which is the default), you may not need to use this module
to write Gauche-specific code.  This is mainly for the compatibility.

One of the characteristics of this module is that many procedures can
take an integer in place of a character; an integer between 0 and 127
is interpreted as an ASCII codepoint.  An integer outside the range
is interpreted as an non-ASCII codepoint.  Such argument is noted
as @var{char-or-code} in the description.  It is handy while you're
dealing with a binary file which may contain some ASCII text in it.
@end deftp

@defun ascii-codepoint? obj
[SRFI-175]
@{@t{srfi-175}@}
Returns @code{#t} iff @var{obj} is an exact integer between 0 and 127,
inclusive.
@end defun

@defun ascii-bytevecotr? obj
[SRFI-175]
@{@t{srfi-175}@}
Returns @code{#t} iff @var{obj} is a bytevector (@code{u8vector}) and
all of its elements are between 0 and 127, inclusive.
@end defun

@defun ascii-char? obj
[SRFI-175]
@{@t{srfi-175}@}
Returns @code{#t} iff @var{obj} is an ASCII character.
@end defun

@defun ascii-string? obj
[SRFI-175]
@{@t{srfi-175}@}
Returns @code{#t} iff @var{obj} is a string and all of its elements
are ASCII characters.
@end defun

@defun ascii-control? char-or-code
[SRFI-175]
@{@t{srfi-175}@}
Returns @code{#t} iff @var{char-or-code} is in the range of
ASCII control characters

@example
(ascii-control? #\tab) @result{} #t
(ascii-control? #\A)   @result{} #f

(ascii-control? 127)   @result{} #t
(ascii-control? 255)   @result{} #f
@end example

Note: The accepted character range corresponds to
@code{char-set:ascii-control} (@pxref{Predefined character sets}).
@end defun

@defun ascii-non-control? char-or-code
[SRFI-175]
@{@t{srfi-175}@}
Returns @code{#t} iff @var{char-or-code} is in the range of ASCII but
not a control character.
@end defun

@defun ascii-space-or-tab? char-or-code
[SRFI-175]
@{@t{srfi-175}@}
Returns @code{#t} iff @var{char-or-code} is a tab or a whitespace.
@end defun

@defun ascii-other-graphic? char-or-code
[SRFI-175]
@{@t{srfi-175}@}
Returns @code{#t} iff @var{char-or-code} is in the range of ASCII
graphic characters but not a letter nor a digit.

Note: The accepted character range corresponds to
@code{(char-set-difference char-set:ascii-graphic char-set:ascii-letter+digit)}
(@pxref{Predefined character sets}).
@end defun

@defun ascii-alphanumeric? char-or-code
[SRFI-175]
@{@t{srfi-175}@}
Returns @code{#t} iff @var{char-or-code} is in the ASCII alphabet or digit
range.

Note: The accepted character range corresponds to
@code{char-set:ascii-letter+digit}
(@pxref{Predefined character sets}).
@end defun

@defun ascii-alphabetic? char-or-code
[SRFI-175]
@{@t{srfi-175}@}
Returns @code{#t} iff @var{char-or-code} is in the ASCII alphabet range.

Note: The accepted character range corresponds to
@code{char-set:ascii-letter}
(@pxref{Predefined character sets}).
@end defun

@defun ascii-numeric? char-or-code
[SRFI-175]
@{@t{srfi-175}@}
Returns @code{#t} iff @var{char-or-code} is in the ASCII digit range.

Note: The accepted character range corresponds to
@code{char-set:ascii-digit}
(@pxref{Predefined character sets}).
@end defun

@defun ascii-whitespace? char-or-code
[SRFI-175]
@{@t{srfi-175}@}
Returns @code{#t} iff @var{char-or-code} is one of the ASCII whitespaces.

Note: The accepted character range corresponds to
@code{char-set:ascii-whitespace}
(@pxref{Predefined character sets}).
@end defun

@defun ascii-upper-case? char-or-code
@defunx ascii-lower-case? char-or-code
[SRFI-175]
@{@t{srfi-175}@}
Returns @code{#t} iff @var{char-or-code} is one of upper/lower case
ASCII alphabets.

Note: The accepted character range corresponds to
@code{char-set:ascii-upper-case}/@code{char-set:ascii-lower-case}
(@pxref{Predefined character sets}).
@end defun

@defun ascii-ci=? char-or-code1 char-or-code2
@defunx ascii-ci<? char-or-code1 char-or-code2
@defunx ascii-ci<=? char-or-code1 char-or-code2
@defunx ascii-ci>? char-or-code1 char-or-code2
@defunx ascii-ci>=? char-or-code1 char-or-code2
[SRFI-175]
@{@t{srfi-175}@}
Each argument may be a character or a codepoint.  If the argument
falls into ASCII upper case letters, it is converted to the corresponding
lower case letter codepoint, and then two are compared as codepoints.
Two arguments don't need to be of the same type.

It is allowed to pass non-ascii range; if it is a non-ASCII character,
its codepoint of the native encoding is taken (no case-folding is considered),
and compared as codepoints.  Of course the result are not portable, except
that any non-ASCII character has a codepoint greater than any ASCII characters.
@end defun

@defun ascii-string-ci=? string1 string2
@defunx ascii-string-ci<? string1 string2
@defunx ascii-string-ci<=? string1 string2
@defunx ascii-string-ci>? string1 string2
@defunx ascii-string-ci>=? string1 string2
[SRFI-175]
@{@t{srfi-175}@}
Compares two strings with ASCII case folding.   Argument strings may
contain non-ASCII characters; such characters are compared without
case folding.
@end defun

@defun ascii-upcase char-or-code
@defunx ascii-downcase char-or-code
[SRFI-175]
@{@t{srfi-175}@}
If the argument represents a ASCII upper/lower case letter,
returns the corresponding lower/upper case character or codepoint.
The type of the return value is the same as the argument.
If the argument is a character or a codepoint other than that,
it is returned as is.
@end defun

@defun ascii-control->graphic char-or-code
@defunx ascii-graphic->control char-or-code
[SRFI-175]
@{@t{srfi-175}@}
ASCII control characters (@code{#\x00}, @code{#\x01} .. @code{#\x1f}, 
and @code{#\x7f})
are sometimes noted as @code{^@@}, @code{^A} .. @code{^_}, and @code{^?}.
These procedures converts the control character and corresponding
graphical character (the one comes after @code{^}), and vice versa.
The type of the return value is the same as the argument.

If the argument isn't an ASCII control character / a graphical character
that corresponds to an ASCII control character, @code{#f} is returned.
@end defun

@defun ascii-mirror-bracket char-or-code
[SRFI-175]
@{@t{srfi-175}@}
There are four pairs of brackets in ASCII: @code{(} and @code{)},
@code{@{} and @code{@}}, @code{[} and @code{]}, and @code{<} and @code{>}.
If @var{char-or-code} is either one of these eight chars or codepoints,
returns the corresponding bracket.
The type of the return value is the same as the argument.

If the argument is a char or a codepoint other than those brackets,
@code{#f} is returned.
@end defun

@defun ascii-nth-digit n
[SRFI-175]
@{@t{srfi-175}@}
Returns a digit character representing the number @var{n}.
If @var{n} is not an exact integer between 0 and 9, inclusive,
@code{#f} is returned.

@example
(ascii-nth-digit 3) @result{} #\3
@end example

See also @code{integer->digit} (@pxref{Characters}).
@end defun

@defun ascii-nth-upper-case n
@defunx ascii-nth-lower-case n
[SRFI-175]
@{@t{srfi-175}@}
Returns @code{(modulo @var{n} 26)}-th character of upper/lower case
ASCII alphabet.

@example
(ascii-nth-upper-case 0) @result{} #\A
(ascii-nth-lower-case 1) @result{} #\b

(ascii-nth-upper-case 25) @result{} #\Z
(ascii-nth-lower-case 26) @result{} #\a
@end example

See also @code{integer->digit} (@pxref{Characters}).
@end defun

@defun ascii-digit-value char-or-code limit
[SRFI-175]
@{@t{srfi-175}@}
If @var{char-or-code} represents an ASCII decimal digits and
the corresponding number is less than @var{limit},
returns the number.  Otherwise, returns @code{#f}.

@example
(ascii-digit-value #\5 10) @result{} 5
(ascii-digit-value #\9 8)  @result{} #f

(ascii-digit-value 48 10)  @result{} 0
@end example

See also @code{digit->integer} (@pxref{Characters}).
@end defun

@defun ascii-upper-case-value char-or-code offset limit
@defunx ascii-lower-case-value char-or-code offset limit
[SRFI-175]
@{@t{srfi-175}@}
If @var{char-or-code} is n-th ASCII upper/lower case alphabet,
and @var{n} is less than @var{limit}, returns @code{(+ @var{n} @var{offset})}.
Otherwise returns @code{#f}.

@example
(ascii-upper-case-value #\E 10 6) @result{} 14
(ascii-lower-case-value #\z 0 26) @result{} 25
@end example

See also @code{digit->integer} (@pxref{Characters}).
@end defun

@c ----------------------------------------------------------------------
@node Bitvector library, JSON, ASCII character library, Library modules - SRFIs
@section @code{srfi-178} - Bitvector library
@c NODE ビットベクタライブラリ, @code{srfi-178} - ビットベクタライブラリ

@deftp {Module} srfi-178
@mdindex srfi-178
Gauche supports bitvectors as a native type, but the core library only
offers a handful of primitives.  This module complements the comprehensive
operations on bitvectors.

The following procedures are built-in.  @xref{Bitvectors}, for the description.

@example
bit->integer      bit->boolean
bitvector         make-bitvector     list->bitvector
bitvector?        bitvector-length
string->bitvector bitvector->string
bitvector-ref/int bitvector-ref/bool
bitvector-set!    bitvector-copy     bitvector-copy!
@end example
@end deftp

@subheading Constructors

@defun bitvector-unfold f length seed @dots{}
@defunx bitvector-unfold-right f length seed @dots{}
[SRFI-178]
@{@t{srfi-178}@}
Creates a bitvector of length @var{length}, and fill its contents by
repeatedly applying @var{f}.  The procedure @var{f} must take one more
than the number of seeds, and must return the same number
of values.  First, @var{f} is applied to the index and @var{seed} @dots{},
then its first return value (which must be a bit, i.e. 0, 1 or a boolean
value) is used to initialize the first element of the bitvector,
and the rest of the return value is used as the next argument to @var{f}.
It is repeated @var{length} times.

While @code{bitvector-unfold} fills the bits from left to right,
@code{bitvector-unfold-right} does from right to left.

@example
(use math.prime)
(bitvector-unfold (^[index n]
                    (values (small-prime? n) (+ n 1))) 
                  20 0)
  @result{} #*00110101000101000101
(bitvector-unfold-right (^[index n] 
                          (values (small-prime? n) (+ n 1))) 
                        20 0)
  @result{} #*10100010100010101100  
@end example

Note: This procedure follows the protocol of @code{vector-unfold}
(@pxref{R7RS vectors}), and has a different protocol from other
@code{unfold} procedures (@pxref{R7RS lists}).
@end defun

@defun bitvector-reverse-copy bv :optional start end
[SRFI-178]
@{@t{srfi-178}@}
Copies a bitvector @var{bv} in reverse order.  Optional @var{start}
and @var{end} arguments limits the range of the input.

@example
(bitvector-reverse-copy #*10110011100011110000 4 16)
  @result{} #*111100011100
@end example
@end defun

@defun bitvector-append bv @dots{}
[SRFI-178]
@{@t{srfi-178}@}
All arguments must be bytevectors.  Returns a fresh bytevector
which is concatenation of all arguments.
@end defun

@defun bitvector-concatenate bvs
[SRFI-178]
The argument must be a list of bytevectors.  Returns a fresh bytevector
which is concatenation of all arguments.
@{@t{srfi-178}@}
@end defun

@defun bitvector-append-subbitvectors bv start end @dots{}
[SRFI-178]
@{@t{srfi-178}@}
The number of arguments must be a multiple of 3.  Each triplet of
the arguments is a bytevector followed by start and end index,
specifying the input bytevector range.  Returns a fresh bytevector
which is concatenation of all the subvectors.
@end defun

@subheading Predicates

@defun bitvector-emtpy? bv
[SRFI-178]
@{@t{srfi-178}@}
Returns @code{#t} iff @var{bv} is an empty bytevector.
@end defun

@defun bitvector=? bv @dots{}
[SRFI-178]
@{@t{srfi-178}@}
Returns @code{#t} iff all the bytevectors have the same content.
If there's zero or one argument, it returns @code{#t}.
@end defun

@subheading Iteration

@defun bitvector-take bv n
@defunx bitvector-take-right bv n
[SRFI-178]
@{@t{srfi-178}@}
Returns a new bitvector with the first/last @var{n} bits of a bitvector @var{bv}.
An error is thrown if length of @var{bv} is less than @var{n}.

In Gauche, you can also use generic @code{(subseq bv 0 n)} to take the
first @var{n} bits.  @xref{Sequence framework}.
@end defun

@defun bitvector-drop bv n
@defunx bitvector-drop-right bv n
[SRFI-178]
@{@t{srfi-178}@}
Returns a new bitvector with bits except first/last @var{n} bits of 
a bitvector @var{bv}.
An error is thrown if length of @var{bv} is less than @var{n}.

In Gauche, you can also use generic @code{(subseq bv n)}
to drop the first @var{n} bits.  @xref{Sequence framework}.
@end defun

@defun bitvector-segment bv n
[SRFI-178]
@{@t{srfi-178}@}
Slices a bitvector @var{bv} with @var{n}-bits each, and returns
a list of bitvectors.  If the length of @var{bv} isn't a multiple
of @var{n}, the last bitvector may be shorter.
@end defun

@defun bitvector-fold/int kons knil bv1 bv2 @dots{}
@defunx bitvector-fold/bool kons knil bv1 bv2 @dots{}
@defunx bitvector-fold-right/int kons knil bv1 bv2 @dots{}
@defunx bitvector-fold-right/bool kons knil bv1 bv2 @dots{}
[SRFI-178]
@{@t{srfi-178}@}
Fold @var{kons} over the elements of bitvectors with @var{knil} as
the initial state value.

The @var{kons} procedure is always called as
@code{(kons state e1 e2 @dots{})}, where @var{e1} @var{e2} @dots{}
are elements from each bitvectors, as integer 0/1 (for @code{/int} procdures)
or boolean @code{#f}/@code{#t} (for @code{/bool} procedures).
This is the same order as @code{vector-fold} in
@code{scheme.vector} module (@pxref{R7RS vectors}).
(Note that list @code{fold} procedure calls the @var{knil} procedure
with different order; @pxref{Walking over lists}).

All bitvectors must have the same length; otherwise, an error is thrown.
@end defun

@defun bitvector-map/int f bv1 bv2 @dots{}
@defunx bitvector-map/bool f bv1 bv2 @dots{}
[SRFI-178]
@{@t{srfi-178}@}
Apply a procedure @var{f} over each element taken from given bitvectors.
The result of the procedure is gathered as a fresh bitvector and returned.

All bitvectors must have the same length; otherwise, an error is thrown.
@end defun

@defun bitvector-map!/int f bv1 bv2 @dots{}
@defunx bitvector-map!/bool f bv1 bv2 @dots{}
[SRFI-178]
@{@t{srfi-178}@}
Apply a procedure @var{f} over each element taken from given bitvectors.
The result of the procedure is set into @var{bv1}.

These procedure returns undefined value; you should count on the
side effect onto @var{bv1.}

All bitvectors must have the same length; otherwise, an error is thrown.
@end defun

@defun bitvector-map->list/int f bv1 bv2 @dots{}
@defunx bitvector-map->list/bool f bv1 bv2 @dots{}
[SRFI-178]
@{@t{srfi-178}@}
Apply a procedure @var{f} over each element taken from given bitvectors.
The result of the procedure is gathered as a list and returned.

All bitvectors must have the same length; otherwise, an error is thrown.
@end defun

@defun bitvector-for-reach/int f bv1 bv2 @dots{}
@defunx bitvector-for-reach/bool f bv1 bv2 @dots{}
[SRFI-178]
@{@t{srfi-178}@}
Apply a procedure @var{f} over each element taken from given bitvectors.
The result of the procedure is discarded.

All bitvectors must have the same length; otherwise, an error is thrown.
@end defun

@subheading Prefixes, suffixes, trimming and padding

@defun bitvector-prefix-length bv1 bv2
@defunx bitvector-suffix-length bv1 bv2
[SRFI-178]
@{@t{srfi-178}@}
Returns the length of common prefix/suffix of two bitvectors
@var{bv1} and @var{bv2}.

@example
(bitvector-prefix-length #*1100101001 #*110001101) @result{} 4
(bitvector-suffix-length #*1100101001 #*110001101) @result{} 2
@end example
@end defun

@defun bitvector-prefix? needle haystack
@defunx bitvector-suffix? needle haystack
[SRFI-178]
@{@t{srfi-178}@}
Both arguments must be bitvectors.  Returns @code{#t}
iff  @var{needle} is a prefix/suffix of @var{haystack}.

@example
(bitvector-prefix? #*101 #*1010100) @result{} #t
(bitvector-prefix? #*101 #*1000110) @result{} #f
(bitvector-suffix? #*110 #*1000110) @result{} #t
(bitvector-suffix? #*110 #*1010100) @result{} #f
@end example
@end defun

@defun bitvector-pad bit bv len
@defunx bitvector-pad-right bit bv len
[SRFI-178]
@{@t{srfi-178}@}
If the length of a bitvector @var{bv} is smaller than @var{len},
returns a bitvector of length @var{len} by adding @var{bit} before/after
@var{bv}.  If the length of @var{bv} is equal to or greater than @var{len},
@var{bv} is returned as is.

@example
(bitvector-pad 1 #*00010 10) @result{} #*1111100010
(bitvector-pad-right 1 #*00010 10) @result{} #*0001011111
@end example
@end defun

@defun bitvector-trim bit bv
@defunx bitvector-trim-right bit bv
@defunx bitvector-trim-both bit bv
[SRFI-178]
@{@t{srfi-178}@}
Returns a bitvector without preceding and/or trailing consecutive
@var{bit} from @var{bv}.

@example
(bitvector-trim 0 #*000101000) @result{} #*101000
(bitvector-trim-right 0 #*000101000) @result{} #*000101
(bitvector-trim-both 0 #*000101000) @result{} #*101
@end example
@end defun


@subheading Mutators

@defun bitvector-swap! bv i j
[SRFI-178]
@{@t{srfi-178}@}
Swap the @var{i}-th value and @var{j}-th value of a bitvector @var{bv}.
If the index is out of range, an error is thrown.
@end defun

@defun bitvector-reverse! bv :optional start end
[SRFI-178]
@{@t{srfi-178}@}
Reverse the order of the content of a bitvector @var{bv} destructively.
The optional @var{start}/@var{end} indexes limit the range of the operation;
elements outside of the range won't be affected.
@end defun

@defun bitvector-reverse-copy! to tstart from :optional start end
[SRFI-178]
@{@t{srfi-178}@}
Same as @code{(bitvector-copy! to start (bitvector-reverse-copy from start end))}, 
but potentially more efficient.
@end defun

@subheading Conversion

@defun bitvector->list/int bv :optional start end
@defunx bitvector->list/bool bv :optional start end
@defunx reverse-bitvector->list/int bv :optional start end
@defunx reverse-bitvector->list/bool bv :optional start end
[SRFI-178]
@{@t{srfi-178}@}
@end defun

@defun reverse-list->bitvector lis
[SRFI-178]
@{@t{srfi-178}@}
@end defun

@defun bitvector->vector/int bv :optional start end
@defunx bitvector->vector/bool bv :optional start end
@defunx revrese-bitvector->vector/int bv :optional start end
@defunx reverse-bitvector->vector/bool bv :optional start end
[SRFI-178]
@{@t{srfi-178}@}
@end defun

@defun vector->bitvetor vec :optional start end
@defunx reverse-vector->bitvector vec :optional start end
[SRFI-178]
@{@t{srfi-178}@}
@end defun

@defun bitvector->integer bv
@defunx integer->bitvector n :optional len
[SRFI-178]
@{@t{srfi-178}@}
@end defun

@subheading Generators

@defun make-bitvector/int-generator bv
@defunx make-bitvector/bool-generator bv
[SRFI-178]
@{@t{srfi-178}@}
@end defun

@defun make-bitvector-accumulator
[SRFI-178]
@{@t{srfi-178}@}
@end defun

@subheading Bitwise operations

@defun bitvector-not bv
@defunx bitvector-not! bv
[SRFI-178]
@{@t{srfi-178}@}
@end defun

@defun bitvector-and bv1 bv2 bv @dots{}
@defunx bitvector-and! bv1 bv2 bv @dots{}
@defunx bitvector-ior bv1 bv2 bv @dots{}
@defunx bitvector-ior! bv1 bv2 bv @dots{}
@defunx bitvector-xor bv1 bv2 bv @dots{}
@defunx bitvector-xor! bv1 bv2 bv @dots{}
@defunx bitvector-eqv bv1 bv2 bv @dots{}
@defunx bitvector-eqv! bv1 bv2 bv @dots{}
[SRFI-178]
@{@t{srfi-178}@}
@end defun

@defun bitvector-nand bv1 bv2
@defunx bitvector-nand! bv1 bv2
@defunx bitvector-nor bv1 bv2
@defunx bitvector-nor! bv1 bv2
@defunx bitvector-andc1 bv1 bv2
@defunx bitvector-andc1! bv1 bv2
@defunx bitvector-andc2 bv1 bv2
@defunx bitvector-andc2! bv1 bv2
@defunx bitvector-orc1 bv1 bv2
@defunx bitvector-orc1! bv1 bv2
@defunx bitvector-orc2 bv1 bv2
@defunx bitvector-orc2! bv1 bv2
[SRFI-178]
@{@t{srfi-178}@}
@end defun

@subheading Quasi-integer operations

@defun bitvector-logical-shift bv count bit
[SRFI-178]
@{@t{srfi-178}@}
@end defun

@defun bitvector-count bit bv
[SRFI-178]
@{@t{srfi-178}@}
@end defun

@defun bitvector-count-run bit bv start
[SRFI-178]
@{@t{srfi-178}@}
@end defun

@defun bitvector-if bv-if bv-then bv-else
[SRFI-178]
@{@t{srfi-178}@}
@end defun

@defun bitvector-first-bit bit bv
[SRFI-178]
@{@t{srfi-178}@}
@end defun

@subheading Bit field operations

@defun bitvector-field-any? bv start end
[SRFI-178]
@{@t{srfi-178}@}
@end defun

@defun bitvector-field-every? bv start end
[SRFI-178]
@{@t{srfi-178}@}
@end defun

@defun bitvector-field-clear bv start end
@defunx bitvector-field-clear! bv start end
@defunx bitvector-field-set bv start end
@defunx bitvector-field-set! bv start end
[SRFI-178]
@{@t{srfi-178}@}
@end defun

@defun bitvector-field-replace to from start end
@defunx bitvector-field-replace! to from start end
[SRFI-178]
@{@t{srfi-178}@}
@end defun

@defun bitvector-field-replace-same to from start end
@defunx bitvector-field-replace-same! to from start end
[SRFI-178]
@{@t{srfi-178}@}
@end defun

@defun bitvector-field-rotate bv count start end
[SRFI-178]
@{@t{srfi-178}@}
@end defun

@defun bitvector-field-flip bv start end
@defunx bitvector-field-flip! bv start end
[SRFI-178]
@{@t{srfi-178}@}
@end defun

@c ----------------------------------------------------------------------
@node JSON, Custom ports, Bitvector library, Library modules - SRFIs
@section @code{srfi-180} - JSON

@deftp {Module} srfi-180
@mdindex srfi-180
This srfi defines the means of parsing and constructin JSON.

In Gauche, this module is implemented on top of @code{rfc.json} module
(@pxref{JSON parsing and construction}).
Notably, the parameter @code{json-nesting-depth-limit} is the same
as the one in @code{rfc.json}.

Gauche's @code{rfc.json} is more flexible in terms of mapping
JSON objects to Scheme objects.  On the other hand, @code{srfi-180}
provides a streaming parser/generator, which allows the caller
to process input as it is read, instead of waiting the entire
input to be parsed.
@end deftp

@subheading Predicates and parameters

@defun json-error? obj
[SRFI-180]
@{@t{srfi-180}@}
JSON reader and writer raise a condition that satisfies
this predicate when it encounters invalid JSON syntax and/or object,
or the input exceeds the limits specified by
@code{json-nesting-depth-limit} or
@code{json-number-of-character-limit} parameters.

Since @code{srfi-180} is implemented on top of @code{rfc.json},
which raises a condition @code{<json-parse-error>} for input and
@code{<json-construct-error>} for the output, this predicate simply
returns @code{#t} iff @var{obj} is an instance of either class.
@xref{JSON parsing and construction}, for the detail of these conditions.
@end defun

@defun json-error-reason err
[SRFI-180]
@{@t{srfi-180}@}
Returns a string explaining the reasonfor the error @var{err},
if @var{err} is a JSON error object (an object that satisfies
@code{json-error?}).

In Gauche, a JSON error object is an instance of either
@code{<json-parse-error>} or @code{<json-construct-error>})
conditions, and @code{json-error-reason} simply returns the content of
its @code{message} slot.
@end defun

@defun json-null? obj
[SRFI-180]
@{@t{srfi-180}@}
Returns @code{#t} iff @var{obj} is the symbol @code{null}.
@end defun

@deffn {Parameter} json-number-of-character-limit
[SRFI-180]
@{@t{srfi-180}@}
A parameter that holds a real value.  If the number of characters
of input JSON text exceeds the value while @code{json-generator},
@code{json-fold} or @code{json-read} is processing the input,
a JSON error is thrown.
@end deffn

@subheading JSON reader

@defun json-generator :optional port-or-generator
[SRFI-180]
@{@t{srfi-180}@}
Streaming parser.  The input @var{port-or-generator} must be
an input port, or a char generator.

Each time it is called, it returns one of the following values, parsed
from the input.

@table @asis
@item string
JSON string.
@item real number
JSON number.
@item @code{#t}, @code{#f}
JSON @code{true} and @code{false}
@item @code{null}
JSON @code{null}
@item @code{array-start}
The beginning of an array.  What follows is the array's element,
up to the matching @code{array-end}.
@item @code{array-end}
The ending of an array.
@item @code{object-start}
The beginning of an object.  What follows is alternating
string keys and JSON values, up to the matching @code{object-end}.
@item @code{object-end}
The ending of an object.
@item EOF
After one top-level JSON value is read, the generator returns EOF.
@end table

The generator internally tracks the state, and raises
@code{<json-parse-error>} when the input contains invalid JSON text.
See also @code{json-error?} above.

If the input contains more than one toplevel JSON value, you have to
call @code{json-generator} after the previous generator is exhausted.

Note that if a toplevel JSON value is a number, @code{true}, @code{false}
or @code{null}, the parser need to read one character ahead to recognize
the value.  So the subsequent call of @code{json-generator} won't read
a character immediately following those values.

Generally, multiple toplevel values uses delimiters for each values
so it won't be an issue.  See @code{json-lines-read} and
@code{json-sequence-read} below.
@end defun

@defun json-fold proc array-start array-end object-start object-end seed :optional port-or-generator
[SRFI-180]
@{@t{srfi-180}@}
A procedure to translate JSON pasring result to Scheme object on the fly.

The @var{port-or-generator} argument is either an input port,
or a char generator, defaulted to the current input port.
It is first passed to @code{json-generator} to
get a generator of parser events.  Then, @code{json-fold} retrieves
value from the generator and take one of the following actions:

@itemize
@item
If it generates a string, a number, a boolean or @code{null},
calls @code{(proc obj seed)} where @var{obj} is the generated value
and @var{seed} is the current seed value, and make the result a new seed value.
@item
If it generates @code{array-start}, save the current seed, calls
@code{(array-start seed)} and make the result a new seed value.
@item
If it generates @code{array-end}, calls @code{(array-end seed)}, let
the result be @var{arr}, recover the seed value saved
at the corresponding @code{array-start}, and calls
@code{(proc arr recovered-seed)}.  Let the result a new seed value.
@item
If it generates @code{object-start}, save the current seed, calls
@code{(object-start seed)} and make the result a new seed value.
@item
If it generates @code{object-end}, calls @code{(object-end seed)}, let
the result be @var{obj}, recover the seed value saved
at the corresponding @code{object-start}, and calls
@code{(proc obj recovered-seed)}.  Let the result a new seed value.
@item
If it generates EOF, returns the seed value as the result of
@code{json-fold}.
@end itemize
@end defun

@defun json-read :optional port-or-generator
[SRFI-180]
@{@t{srfi-180}@}
Read one JSON value or object from @var{port-or-generator}, which
should be an input port or a char generator.  If it is omitted,
the current input port is used.

JSON strings and numbers are mapped to Scheme strings and numbers.
JSON @code{true} and @code{false} become @code{#t} and @code{#f}.
JSON @code{null} becomes a symbol @code{null}.
JSON arrays become Scheme vectors, and JSON objects
become Scheme alist, in which keys are converted to symbols.

If the input contains invalid JSON text, a @code{<json-parse-error>}
is thrown.

See also @code{parse-json} in @code{rfc.json}
(@pxref{JSON parsing and construction}).

@example
(call-with-input-string 
  "[@{\"a\":1@}, @{\"b\":true, \"c\":\"foo\"@}, null]"
  json-read)
  @result{} #(((a . 1))
      ((b . #t) (c . "foo"))
      null)
@end example
@end defun

@defun json-lines-read :optional port-or-generator
[SRFI-180]
@{@t{srfi-180}@}
Read JSON Lines format
(@url{http://jsonlines.org/}), which contains multiple
toplevel JSON values separated with @code{#\newline}.
The input @var{port-or-generator} should be an input port
or a char generator, defaulted to the current input port.

See @code{json-read} above about the mapping from JSON values to Scheme
values.

Returns a list of read JSON values.  A @code{<json-parse-error>}
is thrown if it encounters invalid JSON text.
@end defun

@defun json-sequence-read :optional port-or-generator
[SRFI-180]
@{@t{srfi-180}@}
Read JSON Text Sequence format (RFC7464, @url{https://tools.ietf.org/html/rfc7464}) from @var{port-or-generator}, which should be an input port
or a char generator, defaulted to the current input port.

JSON Text Sequence can contain multiple JSON values,
each one leaded by one or more consecutive U+001E.
If it encounters text unparsable as JSON, that segment (until next U+001E)
is silently ignored.  Returns a list of read JSON values.

See @code{json-read} above about the mapping from JSON values to Scheme
values.

See also @code{construct-json} in @code{rfc.json}
(@pxref{JSON parsing and construction}).
@end defun

@subheading JSON writer

@defun json-accumulator port-or-accumlator
[SRFI-180]
@{@t{srfi-180}@}
This is dual to @code{json-generator}.  The @code{port-or-accumulator}
should be an output port or an accumulator that accepts a character or
a string.  This procedure
returns an accumulator that accepts the events such as
@code{json-generator} generates.  
@end defun

@defun json-write obj :optional port-or-accumulator
[SRFI-180]
@{@t{srfi-180}@}
Write @var{obj} as a JSON to @var{port-or-accumulator}, which
must be an output port or an accumulator that accepts a character or
a string.
@end defun

@c ----------------------------------------------------------------------
@node Custom ports, Linear adjustable-length strings, JSON, Library modules - SRFIs
@section @code{srfi-181} - Custom ports
@c NODE カスタムポート, @code{srfi-181} - カスタムポート

@deftp {Module} srfi-181
@mdindex srfi-181
This srfi defins a way to implement a port in Scheme.
Gauche has native support of such ports (@pxref{Virtual ports}),
but this srfi is useful for portable code.

The interface is upper compatible to R6RS.

Note that R7RS Scheme distinguishes binary and textual ports,
while Gauche ports can handle both.
@end deftp

@subheading Creating custom ports

@defun make-custom-binary-input-port id read! get-pos set-pos! close
@defunx make-custom-textual-input-port id read! get-pos set-pos! close
[SRFI-181]
@{@t{srfi-181}@}
Creates a new binary and textual input port and returns it, respectively.

The @var{id} argument is an arbitrary Scheme procedure.  SRFI doesn't
specify how it is used.  In Gauche, @var{id} will be returned
with @code{port-name} procedure (@pxref{Common port operations}).

The @var{read!} argument is a procedure to be called
as @code{(read! @var{buffer} @var{start} @var{count})}.
For @code{make-custom-binary-input-port}, @var{buffer} is a bytevector.
For @code{make-custom-textual-input-port}, @var{buffer} is either
a string or a vector of characters (Gauche's implementation always
use a vector, but portable code should handle both).

It should generate up to @var{count} bytes/characters of data and fill 
@var{buffer} beginning from @var{start}, then return the number of 
bytes/characters generated.
It should generate at least 1 byte/character if there's still data. 
To indicate the end of the data, it writs no data and returns 0.

The @var{get-pos} argument is a procedure to be called without arguments,
and returns an implementation-dependent object that indicates
the current position of the input stream.  The `current position' is
where next @var{read!} will generate the data.  This can be @code{#f}
if the port doesn't provide positions.

For @code{make-custom-binary-input-port}, there's a special rule that
if @var{get-pos} returns an exact integer, it should be a byte position
in the stream.

The @var{set-pos!} argument is a procedure to be called with one argument, 
a new position.
It should set the source's position so that next @var{read!} starts
generating data from there.  The passed position is something that has
been returned by @var{get-pos}, or, for @code{make-custom-binary-input-port},
an exact integer that indicates the byte offset from the beginning of
the input.   This argument can be @code{#f} if the port doesn't
support setting positions.  The returned value of @var{set-pos!} is
ignored.

If the position passed to @var{set-pos!} is invalid,
an error that satisfy @code{i/o-invalid-position-error?} should be
thrown.  Portably, it can be done by throwing a condition created
by @code{make-i/o-invalid-position-error} (@pxref{Port positioning}).
For Gauche-specific code, you can throw a condition
@code{<io-invalid-position-error>}.

The @var{close} argument is a procedure to be called without
argument, when the port is closed.  It can be @code{#f} if you
don't need a special cleanup.
@end defun

@defun make-custom-binary-output-port id write! get-pos set-pos! close :optional flush
@defunx make-custom-textual-output-port id write! get-pos set-pos! close :optional flush
[SRFI-181]
@{@t{srfi-181}@}
Creates a new binary and textual out port and returns it, respectively.

The @var{id} argument is an arbitrary Scheme procedure.  SRFI doesn't
specify how it is used.  In Gauche, @var{id} will be returned
with @code{port-name} procedure (@pxref{Common port operations}).

The @var{write!} argument is a procedure to be called as
@code{(write! @var{buffer} @var{start} @var{count})}.
For @code{make-custom-binary-output-port}, @var{buffer} is a bytevector.
For @code{make-custom-textual-output-port}, @var{buffer} is either
a string or a vector of characters (Gauche's implementation always
use a vector, but portable code should handle both).

The @var{write!} procedure needs to consume data in @var{buffer}
starting from @var{start}, upto @var{count} items.  It must return
the actual number of items consumed.

The @var{get-pos} argument should be a procedure without taking argument,
or @code{#f}.  If it is a procedure, it should return the position
of the sink where the next @var{write!} writes to.  The position
can be an arbitrary Scheme object, but for
@code{make-custom-binary-output-port}, a position represented as
an exact integer should correspond to the byte offset in the port.

The @var{set-pos!} argument is a procedure to be called with one argument, 
a new position.
It should set the sink's position so that next @var{write!} starts
to write data from there.  The passed position is something that has
been returned by @var{get-pos}, or, for @code{make-custom-binary-output-port},
an exact integer that indicates the byte offset from the beginning of
the output.   This argument can be @code{#f} if the port doesn't
support setting positions.  The returned value of @var{set-pos!} is
ignored.

If the position passed to @var{set-pos!} is invalid,
an error that satisfy @code{i/o-invalid-position-error?} should be
thrown.  Portably, it can be done by throwing a condition created
by @code{make-i/o-invalid-position-error} (@pxref{Port positioning}).
For Gauche-specific code, you can throw a condition
@code{<io-invalid-position-error>}.

The @var{close} argument is a procedure to be called without
argument, when the port is closed.  It can be @code{#f} if you
don't need a special cleanup.

The @var{flush} argument, if provided and not @code{#f}, 
should be a procedure taking no arguments.  It is called when
the port is requested to flush the data buffered in the sink, if any.
@end defun

@defun make-custom-binary-input/output-port id read! write! get-pos set-pos! close :optional flush
[SRFI-181]
@{@t{srfi-181}@}
Creates a bidirectional binary i/o port.  Since Gauche doesn't distinguish
binary and textual ports, you can use the returned port for textual i/o as well,
but portable code must avoid it.

(The reason textual input/output port is not defined in the SRFI is that
it is difficult to define a consistent semantics agnostic to the internal
representation of character stream.  In Gauche, we immediately convert
characters to the octet stream of internal character encoding.)

The arguments, @var{id}, @var{read!}, @var{write!},
@var{get-pos}, @var{set-pos!}, @var{close} and @var{flush} are
the same as @code{make-custom-binary-input-port} and
@code{make-custom-binary-output-port}.
@end defun

@subheading Transcoded ports

A transcoded port is a portable way to read/write characters in
an encodings other than the system's default one.  This API is
defined first in R6RS, and adopted in srfi-181.

In srfi-181 (and R6RS) world, strings and characters are all
an abstract entity without the concept of encodings (internally,
you can think them being encoded in the system's native encoding),
and the explicit encodings only matter when you refer to the outside
resource, e.g. files or a binary data represented in a bytevector.
Therefore, conversions are only defined between binary ports (external world)
and textual ports (internal), or a bytevector (external world) and
a string (internal).

Here's some terms:

@table @emph
@item Codec
A codec names a character encoding scheme.
@item EOL-style
Specifies (non)converson of EOL character(s).
@item Transcoder
A transcoder bundles a codec, an eol-style, and error handling mode.
@end table

@subsubheading Transcoders

@defun make-transcoder codec eol-style handling-mode
[SRFI-181]
@{@t{srfi-181}@}
Creates and returns a transcoder with the given parameters.
A transcoder is an immutable object.
@end defun

@defun native-transcoder
[SRFI-181]
@{@t{srfi-181}@}
Returns a singleton of the transcoder representing systems native
(internal) codec and eol-style.  In Gauche, the native codec
is the same as Gauche's native encoding 
(returned by @code{gauche-character-encoding}, @pxref{Characters}),
and eol-style is @code{none}.
@end defun

@defun transcoded-port binary-port transcoder
[SRFI-181]
@{@t{srfi-181}@}
Creates a transcoded port wrapping @var{binary-port}, performing the
conversion specified by @var{transcoder}.

If @var{binary-port} is an input port, it returns an input port,
converting the CES specified in @var{transcoder} to the system's
native encoding.

If @var{binary-port} is an output port, it returns an output port,
converting the system's native encoding to the CES specified in
@var{transcoder}.

In Gauche, conversion is done by conversion ports.
@xref{Conversion ports}, for the details.
@end defun

@defun bytevector->string bytevector transcoder
[SRFI-181]
@{@t{srfi-181}@}
Decode the binary data in @var{bytevector} as the CES specified
by @var{transcoder}, and returns a string in the native encoding.

It is a wrapper of Gauche's @code{ces-convert}; @pxref{Conversion ports}.
@end defun

@defun string->bytevector string transcoder
[SRFI-181]
@{@t{srfi-181}@}
Encode the string in the CES specified by @var{transcoder},
and returns a bytevector.

It is a wrapper of Gauche's @code{ces-convert-to}; @pxref{Conversion ports}.
@end defun

@subsubheading Codecs

@defun make-codec name
[SRFI-181]
@{@t{srfi-181}@}
Returns a coded representing a character encoding scheme named by
@var{name}.  A portable code should only use string for @var{name},
while Gauche accepts a symbol as well.

If @var{name} isn't recognized as a supported codec name,
a condition that satisfies @code{unknown-encoding-error?} is thrown.
@end defun

@defun unknown-encoding-error? obj
[SRFI-181]
@{@t{srfi-181}@}
If the system sees unknown or unsupported codec, a condition
that satisfies this predicate is thrown.
@end defun

@defun unknown-encoding-error-name obj
[SRFI-181]
@{@t{srfi-181}@}
The argument must be an unknown encoding error condition
that satisfies @code{unknown-encoding-error?}.  It returns
the name that caused the condition to be thrown.
@end defun

@defun latin-1-codec
@defunx utf-8-codec
@defunx utf-16-codec
[SRFI-181]
@{@t{srfi-181}@}
A pre-defined codecs for @code{latin-1} (ISO8859-1),
@code{utf-8}, and @code{utf-16}.

The @code{utf-16} codec recognizes
BOM when used for input; if no BOM is found, UTF-16BE is assumed.
When used for output, @code{utf-16} always attaches BOM.
@end defun

@subsubheading EOL style

@defun native-eol-style
[SRFI-181]
@{@t{srfi-181}@}
Returns the default eol style.  In Gauche, it is @code{none}.
@end defun

@subsubheading Transcoding errors

@defun i/o-decoding-error? obj
[SRFI-181]
@{@t{srfi-181}@}
When an input transcoded port encounters a sequence that's not valid
for the input codec, a condition that satisfies this predicate
is thrown.

In Gauche, such condition is @code{<io-decoding-error>}.
@end defun

@defun i/o-encoding-error? obj
[SRFI-181]
@{@t{srfi-181}@}
When an output transcoded port encounters a character that can't be
encoded in the output codec, and the handling mode is @code{raise},
a condition that satisfies this predicate is thrown.

In Gauche, such condition is @code{<io-encoding-error>}.
@end defun

@defun i/o-encoding-error-char i/o-encoding-condition
[SRFI-181]
@{@t{srfi-181}@}
Retries the character that caused the @code{<io-encoding-error>} is thrown.
@end defun


@c ----------------------------------------------------------------------
@node Linear adjustable-length strings, Maybe and Either optional container types, Custom ports, Library modules - SRFIs
@section @code{srfi-185} - Linear adjustable-length strings
@c NODE 線形更新な可変長文字列, @code{srfi-185} - 線形更新な可変長文字列

@deftp {Module} srfi-185
@mdindex srfi-185
This module provides a linear-update version of @code{string-append}
and @code{string-replace}.  ``Linear update'' means the caller
won't access the first string argument, hence the implementation
@emph{can} reuse it to store the result, for the efficiency.

Note that, in Gauche, a string is just a pointer to an immutable
string body.  Mutation of a string is actually constructing a new
string body and swapping the pointer, so it has no performance
advantage to immutable versions.  And in fact, we implement
these without mutating their arguments.

This module also provides macros with the same name as @code{srfi-118}
procedures (@pxref{Simple adjustable-size strings}), which @code{set!}
the result to its first argument, so they can work as a drop-in
replacement to @code{srfi-118}.
@end deftp

@defun string-append-linear! dst str-or-char @dots{}
[SRFI-185]
@{@t{srfi-185}@}
Returns a string which is a concatenation of a string @var{dst}
and the arguments.  The second argument an after can be
a string or a character.  The caller shouldn't access @var{dst}
after calling this procedure, for the implementation may destructively
reuse the string passed to @var{dst}.   Although Gauche won't
mutate @var{dst}, other implementations may, so portable code
should adhere this restriction.

You can't count on @var{dst} being mutated; you always have to use the returned
string.

@example
(string-append-linear! "abc" "def" #\g "hij")
  @result{} "abcdefghij"
@end example
@end defun

@defun stirng-replace-linear! dst dst-start dst-end src :optional src-start src-end
[SRFI-185]
@{@t{srfi-185}@}
Returns copy of a string @var{dst} except
the portion of from @var{dst-start} (inclusive)
to @var{dst-end} (exclusive), by a string @var{src} (from @var{src-start}
to @var{src-end}).
The caller shouldn't access @var{dst}
after calling this procedure, for the implementation may destructively
reuse the string passed to @var{dst}.   Although Gauche won't
mutate @var{dst}, other implementations may, so portable code
should adhere this restriction.

Gauche allows string cursors, as well as integer character index,
in @var{dst-start}, @var{dst-end}, @code{src-start} and @var{src-end} arguments.
(@xref{String cursors}).
@end defun

@defmac string-append! dst string-or-char @dots{}
@defmacx string-replace! dst dst-start dst-end src :optional src-start src-end
[SRFI-185]
@{@t{srfi-185}@}
These macros expand into the following forms:

@example
(set! dst (string-append-linear! dst string-or-char @dots{}))

(set! dst (string-replace-linear! dst dst-start dst-end src src-start src-end))
@end example

Hence they can be used for the code that expects @var{dst} to contain
the result after calling these macros.
Gauche supports generalized @code{set!}, so @var{dst} can be
a procedure call with a setter defined.

@example
(define x (list (string-copy "abc")))

(string-append! (car x) #\d #\e #\f)

x @result{} ("abcdef")
@end example

The code that uses srfi-118 (@pxref{Simple adjustable-size strings}) is
likely to be replaced using these macros.
@end defmac

@c ----------------------------------------------------------------------
@node Maybe and Either optional container types, Port positioning, Linear adjustable-length strings, Library modules - SRFIs
@section @code{srfi-189} - Maybe and Either: optional container types
@c NODE MaybeとEither、オプショナルなコンテナ型, @code{srfi-189} - MaybeとEither、オプショナルなコンテナ型

@deftp {Module} srfi-189
@mdindex srfi-189
Maybe and Either types are immutable container types
that can ``wrap'' zero or more values.  Maybe can be used
in the context where the value(s) may be missing (as opposed to
``zero values'').  Either can be used in the context where
the value(s) can be correct ones or erroneous ones.

If you're familiar with functional languages like Haskell, you may
already know them.  They are useful when used in the monadic pattern; that is,
you can code as if the chain of calculations never fails, 
yet whenever the calculation fail at one place,
the rest of chain is canceled and just the failure is returned.

Maybe is a union of two types, Just and Nothing.  Just wraps
valid value(s), while Nothing indicates there's no meaningful values.
Either is a union of two types, Right and Left.  Right wraps
valid value(s), while Left indicates an error, carrying some information
as its payload.
@end deftp

@menu
* Maybe and Either types and predicates::
* Maybe and Either constructors::
* Maybe and Either accessors::
* Maybe and Either sequence operations::
* Maybe and Either protocol converters::
* Maybe and Either syntactic utilities::
* Trivalent logic::
@end menu

@node Maybe and Either types and predicates, Maybe and Either constructors, Maybe and Either optional container types, Maybe and Either optional container types
@subsection Types and predicates

@deftp {Class} <maybe>
@deftpx {Class} <just>
@deftpx {Class} <nothing>
@{@t{srfi-189}@}
Maybe classes.  @code{<just>} and @code{<nothing>} are subclasses of
@code{<maybe>}.  An instance of @code{<just>} carries zero or more
values (payload), while an instance of @code{<nothing>} doesn't carry
information.

The @code{<maybe>} class is an abstract class and can't
create an instance of its own.
Instances of @code{<just>} and @code{<nothing>} should be created with
constructor procedures @code{just} and @code{nothing}.
@end deftp

@deftp {Class} <either>
@deftpx {Class} <right>
@deftpx {Class} <left>
@{@t{srfi-189}@}
Either classes.  @code{<right>} and @code{<left>} are subclasses of
@code{<either>}.  An instance of either class carry zero or more
values (payload); it is customary to use @code{<right>} to propagate
the legitimate results of compuation, while use @code{<left>} to
propagate erroneous conditions whose payload describes what's wrong.

The @code{<either>} class is an abstract class and can't
create an instance of its own.
Instances of @code{<right>} and @code{<left>} should be created with
constructor procedures @code{right} and @code{left}.
@end deftp

@defun maybe? obj
@defunx just? obj
@defunx nothing? obj
@{@t{srfi-189}@}
[SRFI-189]
Type predicates.
Returns @code{#t} iff @var{obj} is a Maybe, a Just, or a Nothing,
respectively.
@end defun

@defun either? obj
@defunx right? obj
@defunx left? obj
@{@t{srfi-189}@}
[SRFI-189]
Type predicates.
Returns @code{#t} iff @var{obj} is a Either, a Right, or a Left,
respectively.
@end defun

@defun maybe= elt= maybe1 maybe @dots{}
@{@t{srfi-189}@}
[SRFI-189]
Equality predicate of Maybes.  It returns @code{#t} iff
all of @var{maybe1} @var{maybe} @dots{} are Nothings,
or Justs with their respective payload objects are the same
using @var{elt=}.
@end defun

@defun either= elt= either1 either @dots{}
@{@t{srfi-189}@}
[SRFI-189]
Equality predicate of Eithers.  It returns @code{#t} iff
all of @var{either11} @var{either} @dots{} are the same
types (all Rights, or all Lefts), with
respective payload objects are the same
using @var{elt=}.
@end defun

@node Maybe and Either constructors, Maybe and Either accessors, Maybe and Either types and predicates, Maybe and Either optional container types
@subsection Constructors

@defun just obj @dots{}
@{@t{srfi-189}@}
[SRFI-189]
Returns a Just with @var{obj} @dots{} as its payload.
@end defun

@defun nothing
@{@t{srfi-189}@}
[SRFI-189]
Returns a Nothing.
@end defun

@defun right obj @dots{}
@defunx left obj @dots{}
@{@t{srfi-189}@}
[SRFI-189]
Returns a Right or a Left respectively, with @var{obj} @dots{}
as its payload.
@end defun

@defun list->just objs
@defunx list->right objs
@defunx list->left objs
@{@t{srfi-189}@}
[SRFI-189]
Returns a Just, Right or Left respectively, with
@var{objs} as its payload.
@end defun

@defun maybe->either maybe obj @dots{}
@{@t{srfi-189}@}
[SRFI-189]
The @var{maybe} argument must be a Maybe.
If it is a Just, then a Right with the same payload is returned.
If it is a Nothing, a Left with @var{obj} @dots{} as its payload.
@end defun

@defun either->maybe either
@{@t{srfi-189}@}
[SRFI-189]
The @var{either} argument must be an Either.
If it is a Right, then a Just with the same payload is returned.
If it is a Left, a Nothing is returned.
@end defun

@defun either-swap either
@{@t{srfi-189}@}
[SRFI-189]
The @var{either} argument must be an Either.
If it is a Right, a Left with the same payload argument is returned.
If it is a Left, a Right with the same payload argument is returned.
@end defun

@node Maybe and Either accessors, Maybe and Either sequence operations, Maybe and Either constructors, Maybe and Either optional container types
@subsection Accessors

@defun maybe-ref maybe failure :optional success
@{@t{srfi-189}@}
[SRFI-189]
The @var{maybe} arugment must be a Maybe.  If it's a Nothing,
a procedure @var{failure} is tail-called with no arguments.
If it's Just, a procedure @var{success} is tail-called with its
payload object(s).  If @var{success} is omitted, @code{values} is used.

@example
(maybe-ref (just 1 2) (^[] (error 'huh?)) +)
  @result{} 3
@end example
@end defun

@defun either-ref either failure :optional success
@{@t{srfi-189}@}
[SRFI-189]
The @var{either} argument must be an Either.
If it's a Left, a procedure @var{failure} is called with
its payload object(s).  If it's a Right, a procedure
@var{success} is called with its payload object(s).
If @var{success} is omitted, @code{values} is used.
@end defun

@defun maybe-ref/default maybe default @dots{}
@{@t{srfi-189}@}
[SRFI-189]
The @var{maybe} argument must be a Maybe.  If it's a Nothing,
@var{default} @dots{} are returned as multiple values.
If it's a Just, its payload object(s) is/are returned as multiple values.
@end defun

@defun either-ref/default maybe default @dots{}
@{@t{srfi-189}@}
[SRFI-189]
The @var{either} argument must be an Either.  If it's a Left,
@var{default} @dots{} are returned as multiple values (the Left's payload
is discarded).
If it's a Right, its payload object(s) is/are returned as multiple values.
@end defun

@defun maybe-join maybe
@{@t{srfi-189}@}
[SRFI-189]
If @var{maybe} is a Nothing,
it is returned.  If it's a Maybe and its only payload is a Maybe,
the inner Maybe is returned.  Other cases raise an error.
@end defun

@defun either-join either
@{@t{srfi-189}@}
[SRFI-189]
If @var{either} is a Left, it is returned.
If it is a Right and its only payload is an Either,
the inner Either is returned.  Other cases raise an error.
@end defun

@defun maybe-bind maybe mproc mproc2 @dots{}
@{@t{srfi-189}@}
[SRFI-189]
Monadic @var{bind} operation.  The @var{maybe} argument must be a Maybe.
If it is a Nothing, it is returned.
If it is a Just, its payload object(s) is/are applied to a procedure
@var{mproc}, which must return a Maybe.  If @var{mproc2} @dots{} are
given, the same operation is repeated on them.

@example
(maybe-bind m p p2)
  @equiv{} (maybe-bind (maybe-bind m p) p2)
@end example
@end defun

@defun either-bind either mproc mproc2 @dots{}
@{@t{srfi-189}@}
[SRFI-189]
Monadic @var{bind} operation.  The @var{either} argument must be an Either.
If it is a Left, it is returned as is.
If it is a Right, its payload object(s) is/are applied to a procedure
@var{mproc}, which must return an Either.  If @var{mproc2} @dots{} are
given, the same operation is repeated on them.

@example
(either-bind e p p2)
  @equiv{} (either-bind (either-bind e p) p2)
@end example
@end defun

@defun maybe-compose mproc mproc2 @dots{}
@defunx either-compose mproc mproc2 @dots{}
@{@t{srfi-189}@}
[SRFI-189]
Each argument must be a procedure taking zero or more arguments
and return a Maybe/an Either.   Returns a procedure that accepts zero or more
arguments and returns a Maybe/an Either.

When the returned procedure is called, it first calls @var{mproc};
if it returns a Nothing/Left, or there's no more mprocs, the result is
returned.  If the result is a Just, its payload is applied
to the next mproc, and so on.

@example
(maybe-bind m p p2 ...)
  @result{} (maybe-ref m (^[] (nothing))
              (maybe-compose p p2 ...))
@end example
@end defun


@node Maybe and Either sequence operations, Maybe and Either protocol converters, Maybe and Either accessors, Maybe and Either optional container types
@subsection Sequence operations

A Maybe and an Either can be a container of zero or one element, and
we have several procedures that employ this view.
(Note: For this purpose, we treat multiple payload values as a whole,
since they are processed in one step---as if we don't regard
multiple procedure arguments and multiple return values as a sequence
of individual values.)

@defun maybe-length maybe
@defunx either-length either
@{@t{srfi-189}@}
[SRFI-189]
Returns 0 if @var{maybe}/@var{either} is a Nothing/Left, and
1 if it is a Just/Right.  An error is thrown if the argument
isn't a Maybe/an Either.
@end defun

@defun maybe-filter pred maybe
@defunx either-filter pred either obj @dots{}
@{@t{srfi-189}@}
[SRFI-189]
If @var{maybe}/@var{either} is a Nothing/Left,
returns a Nothing/a Left of @var{obj} @dots{}.
If @var{maybe}/@var{either} is a Just/a Right, apply @var{pred} on
its payload value(s).  If @var{pred} returns a true value,
@var{maybe}/@var{either} is returned; otherwise,
a Nothing/a Left of @var{obj} @dots{} is returned.

An error is thrown if @var{maybe}/@var{either} isn't a Maybe/an Either.
@end defun

@defun maybe-remove pred maybe
@defunx either-remove pred either obj @dots{}
@{@t{srfi-189}@}
[SRFI-189]
Like @code{maybe-filter}/@code{either-filter}, but the meaning of
@var{pred} is reversed.
@end defun

@defun maybe-sequence mappable cmap :optional aggregator
@defunx either-sequence mappable cmap :optional aggregator
@{@t{srfi-189}@}
[SRFI-189]
This converts a collection of Maybes/Eithers to a Mayber/an Either of
a collection.  The input collection and the collection in the output can
be of different type.

It's easier to explain using Haskell-ish type signatures, although
it's not precisely specified.  Suppose @code{Container x} is
some kind of a collection of
type @var{x}, and @code{a*} is multiple values of arbitrary types.

@example
Mappable   = Container Maybe a*
CMap       = ((Maybe a* -> b) -> Container Maybe a* -> Container' b
Aggregator = a* -> b

maybe-sequence :: Mappable -> CMap -> Aggregator -> Container' b
@end example

The @var{cmap} maps @var{proc} over the input container (@var{mappable}),
and gathers the result into another container.  It can be any containers,
as long as it matches the @var{mappable} argument.  For example, @var{mappable}
may be a vector of Maybes, and @var{cmap} can be @code{vector-map}--in that case,
both @code{Container} and @code{Container'} are @code{Vector}.
Or, @var{mappable} may be a list of Maybes, and @var{cmap} can be
@code{(cut map-to <string> <> <>)}, then @code{Container} is a list and
@code{Container'} is a string.

The types @code{a*} and @code{b} is determined by the @var{aggregator}
procedure, whose default value is @code{list}.
@end defun

@defun maybe-map proc maybe
@defunx either-map proc either
@{@t{srfi-189}@}
[SRFI-189]
If @var{maybe}/@var{either} is a Nothing/Left, it is returned as is.
If it is a Just/Right, its payload value(s) is/are passed to @var{proc},
and the result is returned.
@end defun

@defun maybe-for-each proc maybe
@defunx either-for-each proc either
@{@t{srfi-189}@}
[SRFI-189]
If @var{maybe}/@var{either} is a Nothing/Left, these procedures do nothing.
Otherwise, @var{proc} is applied to the argument's payload values.
The result of @var{proc} is discarded.  Returns an unspecified vlaue.
@end defun

@defun maybe-fold kons knil maybe
@defunx either-fold kons knil either
@{@t{srfi-189}@}
[SRFI-189]
If @var{maybe}/@var{either} is a Nothing/Left, @var{knil} is returned.
Otherwise, @var{kons} is called with the argument's payload values, plus
@var{knil}.  What @var{kons} returns becomes the result.
@end defun

@defun maybe-unfold p f g seed @dots{}
@defunx either-unfold p f g seed @dots{}
@{@t{srfi-189}@}
[SRFI-189]
First, the stop predicate @var{p} is applied to @var{seed} @dots{}.
If it returns a true value, a Nothing / a Left of @var{seed} @dots{} is
returned.  Otherwise, @var{g} is applied to @var{seed} @dots{},
which should return the same number of values as seeds, and passed
to @var{p}.  If @var{p} returns false, it is an error.
If @var{p} returns true, @var{mapper} is applied to @var{seed} @dots{},
then the results are wrapped in a Just/Right to be returned.
@end defun


@node Maybe and Either protocol converters, Maybe and Either syntactic utilities, Maybe and Either sequence operations, Maybe and Either optional container types
@subsection Protocol converters

@defun maybe->list maybe
@{@t{srfi-189}@}
[SRFI-189]
If @var{maybe} is a Just, returns a list of its payload values.
If it is a Nothing, an empty list is retured.
@end defun

@defun list->maybe lis
@{@t{srfi-189}@}
[SRFI-189]
If @var{lis} is an empty list, a Nothing is returned.
Otherwise, a Just that has elements in @var{lis} as payload values
is returned.

Note that @code{(list->maybe (maybe->list x))} isn't an identity
mapping---if @var{x} is a Just with zero payload values, you'll get
a Nothing.
@end defun

@defun either->list either
@{@t{srfi-189}@}
[SRFI-189]
If @var{either} is a Right, returns a list of its payload values.
If it is a Left, returns an empty string.
@end defun

@defun list->either lis obj @dots{}
@{@t{srfi-189}@}
[SRFI-189]
If @var{lis} is an empty list, a Left of @var{obj} @dots{} is returned.
Otherwise, a Right that has elements in @var{lis} as payload values
is returned.
@end defun

@defun maybe->truth maybe
@{@t{srfi-189}@}
[SRFI-189]
If @var{maybe} is a Nothing, @code{#f} is returned.
Otherwise, it must be a Just with one value, and its value is returned.

If @var{maybe} is a Just and it doesn't have exactly one value, an error
is thrown.  If you want to deal with arbitrary number of payload values,
use @code{maybe->list-truth}.
@end defun

@defun truth->maybe obj
@{@t{srfi-189}@}
[SRFI-189]
If @var{obj} is @code{#f}, returns a Nothing.
Otherwise, returns a Just with @var{obj} as its payload.

Note that @code{(truth->maybe (maybe->truth x))} isn't an identity mapping---
if @var{x} is a Just wrapping @code{#f}, you'll get a Nothing.
@end defun

@defun either->truth either
@{@t{srfi-189}@}
[SRFI-189]
If @var{either} is a Left, @code{#f} is returned.
Otherwise, it must be a Right with one value, and its value is returned.

If @var{either} is a Right and it doesn't have exactly one value, an error
is thrown.  If you want to deal with arbitrary number of payload values,
use @code{either->list-truth}.
@end defun

@defun truth->either obj fail-obj @dots{}
@{@t{srfi-189}@}
[SRFI-189]
If @var{obj} is @code{#f}, returns a Left with @var{fail-obj} @dots{} is
returned.
Otherwise, returns a Right with @var{obj} as its payload.
@end defun

@defun maybe->list-truth maybe
@{@t{srfi-189}@}
[SRFI-189]
Like @code{maybe->list}, it returns @code{#f} if @var{maybe} is a Nothing.
If @var{maybe} is a Just, however, it returns a list of its payload values.
@end defun

@defun list-truth->maybe lis-or-false
@{@t{srfi-189}@}
[SRFI-189]
The argument must be @code{#f} of a list.  If it is @code{#f}, a Nothing
is returned.  If it is a list, a Just with elements of the list is
returned.

@code{(list-truth->maybe (maybe->list-truth x))} is an identity mapping.
@end defun

@defun either->list-truth either
@{@t{srfi-189}@}
[SRFI-189]
Like @code{either->list}, it returns @code{#f} if @var{either} is a Left.
If @var{either} is a Right, however, it returns a list of its payload values.
@end defun

@defun list-truth->either lis-or-false fail-objs @dots{}
@{@t{srfi-189}@}
[SRFI-189]
The @var{list-or-false} argument must be @code{#f} of a list.  
If it is @code{#f}, a Left with @var{fail-objs} @dots{}
is returned.  If it is a list, a Right with elements of the list is
returned.
@end defun

@defun maybe->generation maybe
@{@t{srfi-189}@}
[SRFI-189]
If @var{maybe} is a Nothing, an EOF object is returned.
Otherwise, it must be a Just with one value, and its value is returned.
If @var{maybe} is a Just and it doesn't have exactly one value, an error
is thrown.
@end defun

@defun generation->maybe obj
@{@t{srfi-189}@}
[SRFI-189]
If @var{obj} is an EOF value, a Nothing is returned.
Otherwise, a Just wrapping @var{obj} is returned.
@end defun

@defun either->generation either
@{@t{srfi-189}@}
[SRFI-189]
If @var{either} is a Left, an EOF object is returned.
Otherwise, it must be a Right with one value, and its value is returned.
If @var{either} is a Right and it doesn't have exactly one value, an error
is thrown.
@end defun

@defun generation->either obj fail-objs @dots{}
@{@t{srfi-189}@}
[SRFI-189]
If @var{obj} is an EOF value, a Left with @var{fail-objs} @dots{} is returned.
Otherwise, a Right wrapping @var{obj} is returned.
@end defun

@defun maybe->values maybe
@{@t{srfi-189}@}
[SRFI-189]
If @var{maybe} is a Just, returns its payload as multiple values.
If it is a Nothing, returns no values.
(Note that a Just with zero values also returns no values.)
@end defun

@defun values->maybe producer
@{@t{srfi-189}@}
[SRFI-189]
It first invokes a procedure @var{producer} with no values.
If it returns zero values, a Nothing is returned; otherwise,
a Just with those values are returned.
@end defun

@defun either->values either
@{@t{srfi-189}@}
[SRFI-189]
If @var{either} is a Right, returns its payload as multiple values.
If it is a Left, returns no values.
(Note that a Right with zero values also returns no values.)
@end defun

@defun values->either producer fail-obj @dots{}
@{@t{srfi-189}@}
[SRFI-189]
It first invokes a procedure @var{producer} with no values.
If it returns zero values, a Left with @var{fail-obj} @dots{} as
its payload is returned.
If it returns one or more values,
a Right with those values are returned.
@end defun

@defun maybe->two-values maybe
@{@t{srfi-189}@}
[SRFI-189]
If @var{maybe} is a Just with exactly one value, the value and @code{#t}
is returned.  If @var{maybe} is a Nothing, two @code{#f} is returned.
An error is thrown if @var{maybe} has a Just with zero or more than two
values.
@end defun

@defun two-values->maybe producer
@{@t{srfi-189}@}
[SRFI-189]
The inverse of @code{maybe->two-values}.  A procedure @var{producer}
is called with no arguments.  It must return two values, a possible
payload value, and a boolean.  If the second value is true,
a Just with the first value is returned.  If the second value is @code{#f},
a Nothing is returned (the first return value is ignored).
@end defun

@defun exception->either pred thunk
@{@t{srfi-189}@}
[SRFI-189]
A procedure @var{thunk} is called without argument, wrapped by an
exception handler.  If @var{thunk} raises a condition, it is
examined by @var{pred}.  If @var{pred} returns true on the condition, 
the exception is wrapped by a Left and returned.  
If @var{pred} returns @code{#f}, the exception is reraised.
If no exception is raised, the result(s) of @var{thunk} is wrapped
by a Right and returned.
@end defun

@node Maybe and Either syntactic utilities, Trivalent logic, Maybe and Either protocol converters, Maybe and Either optional container types
@subsection Syntactic utilities

@defmac maybe-if mtest then else
@{@t{srfi-189}@}
[SRFI-189]
If the @var{mtest} expression yields a Just, evaluates @var{then}.
If the @var{mtest} expression yeilds a Nothing, evaluates @var{else}.
If the @var{mtest} expression doesn't produce a Maybe, an error
is thrown.
@end defmac

@defmac maybe-and maybe @dots{}
@defmacx either-and either @dots{}
@{@t{srfi-189}@}
[SRFI-189]
Evaluates @var{maybe}/@var{either} from left to right, as far as
each yields a Just/Right.  If every expression yields a Just/Right,
the last one is returned.  If it encounters an expression that
yields a Nothing/Left, it stops evaluating the rest of expressions and
returns the Nothing/Left.

If expressions yield something other than Maybe/Either, an error is thrown.
@end defmac

@defmac maybe-or maybe @dots{}
@defmacx either-or either @dots{}
@{@t{srfi-189}@}
[SRFI-189]
Evaluates @var{maybe}/@var{either} from left to right, as far as
each yields a Nothing/Left.   If it encounters an expression that
yields a Just/Right, it stops evaluating the rest of expressions and
returns it.  

If expressions yield something other than Maybe/Either, an error is thrown.
@end defmac

@defmac maybe-let* ( claw @dots{} ) body @dots{}
@defmacx either-let* ( claw @dots{} ) body @dots{}
@{@t{srfi-189}@}
[SRFI-189]
This is a Maybe/Either version of @code{and-let*}.
@end defmac

@defmac maybe-let*-values ( mv-claw @dots{} ) body @dots{}
@defmacx either-let*-values ( mv-claw @dots{} ) body @dots{}
@{@t{srfi-189}@}
[SRFI-189]
@end defmac

@defmac either-guard (pred) body @dots{}
@{@t{srfi-189}@}
[SRFI-189]
@end defmac

@node Trivalent logic,  , Maybe and Either syntactic utilities, Maybe and Either optional container types
@subsection Trivalent logic

@defun tri-not maybe
@{@t{srfi-189}@}
[SRFI-189]
@end defun

@defun try=? maybe @dots{}
@{@t{srfi-189}@}
[SRFI-189]
@end defun

@defun try-and maybe @dots{}
@{@t{srfi-189}@}
[SRFI-189]
@end defun

@defun try-or maybe @dots{}
@{@t{srfi-189}@}
[SRFI-189]
@end defun

@defun try-merge maybe @dots{}
@{@t{srfi-189}@}
[SRFI-189]
@end defun

@c ----------------------------------------------------------------------
@node Port positioning, Command line, Maybe and Either optional container types, Library modules - SRFIs
@section @code{srfi-192} - Port positioning
@c NODE ポート位置,  @code{srfi-192} - ポート位置

@deftp {Module} srfi-192
@mdindex srfi-192
This srfi defines procedures to get and set the current position of
the port.

This feature is already supported in the Gauche core, so the following
procedure is described in @ref{Common port operations}.
@example
port-position
port-has-port-position?
set-port-position!
port-has-set-port-position?
@end example
@end deftp

@defun make-i/o-invalid-position-error pos
[SRFI-192]
@{@t{srfi-192}@}
This portably creates a condition suitable to be raised from
@code{set-port-position!} when the given position object can't
be accepted.  The @var{pos} argument is the offending position object.

In Gauche, such condition is represented by 
@code{<io-invalid-position-error>} class, which is a subclass
of @code{<port-error>}.

If you raise a condition created with this procedure from
the @code{set-position!} callback of the custom ports
(@pxref{Custom ports}), Gauche intercepts it and adds
the port information to the condition.
@end defun

@defun i/o-invalid-position-error? obj
[SRFI-192]
@{@t{srfi-192}@}
Returns @code{#t} iff @var{obj} is an i/o-invalid-position-error
condition (or a compound condition that includes it).

In Gauche, it is the same as
@code{(condition-has-type? @var{obj} <io-invalid-position-error>)}.
@end defun

@c ----------------------------------------------------------------------
@node Command line,  , Port positioning, Library modules - SRFIs
@section @code{srfi-193} - Command line
@c NODE コマンドライン,  @code{srfi-193} - コマンドライン

@deftp {Module} srfi-193
@mdindex srfi-193
This srfi clarifying how the command line arguments can be accessed
via R7RS @code{command-line}, plus a few supporting APIs.

The following procedures are built-in.  @xref{Command-line arguments},
for the details.

@example
command-line          script-file
@end example
@end deftp

@defun command-name
[SRFI-193]
@{@t{srfi-193}@}
If the first element of @code{command-line} is an empty string,
returns @code{#f}.  Otherwise, returns the first element without directory
name and obvious extension (@code{.scm}, @code{.exe}) stripped.

This is useful for diagnostic messages, for example.
@end defun

@defun command-args
[SRFI-193]
@{@t{srfi-193}@}
Returns the cdr of @code{command-line}.
@end defun

@defun script-directory
[SRFI-193]
@{@t{srfi-193}@}
Returns the directory part of @code{script-file}.  It always ends with
the directory separator.
@end defun

@c Local variables:
@c mode: texinfo
@c coding: utf-8
@c end:

@node Library modules - Utilities, C to Scheme mapping, Library modules - SRFIs, Top
@chapter Library modules - Utilities
@c NODE ライブラリモジュール - ユーティリティ


@c ----------------------------------------------------------------------
@menu
* Binary I/O::                  binary.io
* Packing binary data::         binary.pack
* Running Chibi-scheme test suite::  compat.chibi-test
* Rational-less arithmetic::    compat.norational
* A common job descriptor for control modules::  control.job
* Thread pools::                control.thread-pool
* Password hashing::            crypt.bcrypt
* Cache::                       data.cache
* Heap::                        data.heap
* Immutable deques::            data.ideque
* Immutable map::               data.imap
* Priority map::                data.priority-map
* Queue::                       data.queue
* Random data generators::      data.random
* Ring buffer::                 data.ring-buffer
* Skew binary random-access lists::  data.skew-list
* Sparse data containers::      data.sparse
* Trie::                        data.trie
* Database independent access layer::  dbi
* Generic DBM interface::       dbm
* File-system dbm::             dbm.fsdbm
* GDBM interface::              dbm.gdbm
* NDBM interface::              dbm.ndbm
* Original DBM interface::      dbm.odbm
* Filtering file content::      file.filter
* Filesystem utilities::        file.util
* Mathematic constants::        math.const
* Mersenne-Twister random number generator::  math.mt-random
* Prime numbers::               math.prime
* Windows support::             os.windows
* PEG parser combinators::      parser.peg
* RFC822 message parsing::      rfc.822
* Base64 encoding/decoding::    rfc.base64
* HTTP cookie handling::        rfc.cookie
* FTP::                         rfc.ftp
* HMAC keyed-hashing::          rfc.hmac
* HTTP::                        rfc.http
* ICMP packets::                rfc.icmp
* IP packets::                  rfc.ip
* JSON parsing and construction::  rfc.json
* MD5 message digest::          rfc.md5
* MIME message handling::       rfc.mime
* Quoted-printable encoding/decoding::  rfc.quoted-printable
* SHA message digest::          rfc.sha
* Transport layer security::    rfc.tls
* URI parsing and construction::  rfc.uri
* UUID::                        rfc.uuid
* Zlib compression library::    rfc.zlib
* SLIB::                        slib
* Functional XML parser::       sxml.ssax
* SXML query language::         sxml.sxpath
* Manipulating SXML structure::  sxml.tools
* Serializing XML and HTML from SXML::  sxml.serializer
* Text terminal control::       text.console
* CSV tables::                  text.csv
* Calculate difference of text streams::  text.diff
* EDN parsing and construction::  text.edn
* Running external editor::     text.external-editor
* Gap buffer::                  text.gap-buffer
* Localized messages::          text.gettext
* Simple HTML document construction::  text.html-lite
* Display with pager::          text.pager
* Parsing input stream::        text.parse
* Showing progress on text terminals::  text.progress
* SQL parsing and construction::  text.sql
* Simple template expander::    text.template
* Transliterate characters::    text.tr
* Lazy text construction::      text.tree
* Combination library::         util.combinations
* Message digester framework::  util.digest
* Calculate dominator tree::    util.dominator
* Determine isomorphism::       util.isomorph
* The longest common subsequence::  util.lcs
* Levenshtein edit distance::   util.levenshtein
* Pattern matching::            util.match
* SLIB-compatible record type::  util.record
* Relation framework::          util.relation
* Stream library::              util.stream
* Topological sort::            util.toposort
* Unification::                 util.unification
* CGI utility::                 www.cgi
* CGI testing::                 www.cgi.test
* CSS parsing and construction::  www.css
@end menu

@c ----------------------------------------------------------------------
@node Binary I/O, Packing binary data, Library modules - Utilities, Library modules - Utilities
@section @code{binary.io} - Binary I/O
@c NODE バイナリI/O, @code{binary.io} - バイナリI/O

@deftp {Module} binary.io
@mdindex binary.io
This module provides basic procedures to perform binary I/O
of numeric data.  Each datum can be read from or written to a port,
and got from or put to a uniform vector (see @ref{Uniform vectors}).
For structured binary data I/O,
more convenient @code{pack} utility is implemented
on top of this module (see @ref{Packing binary data}).
You might want to use this module directly if you need
speed or want a flexible control of endianness.

See also @ref{Uniform vectors}, which provides binary block I/O.
@end deftp

@subheading Endianness
Most procedures of this module take an optional @var{endian} argument,
specifying the byte order of the binary input.
It must be either one of symbols @code{big-endian}, @code{little-endian},
or @code{arm-little-endian}.
If the endian argument is omitted, the current value of the builtin
parameter @code{default-endian} is used (@pxref{Endianness}).
(For 8-bit I/O procedures like @code{read-u8} the endian
argument has no effect, but is accepted for consistency).

@subheading I/O using port

@defun read-u8 :optional port endian
@defunx read-u16 :optional port endian
@defunx read-u32 :optional port endian
@defunx read-u64 :optional port endian
@{@t{binary.io}@}
Reads 8, 16, 32 or 64 bit unsigned integer from @var{port}
with specified endian, respectively.  If @var{port} is omitted,
current input port is used.  If @var{port} reaches EOF before
a complete integer is read, EOF is returned.
@end defun

@defun read-s8 :optional port endian
@defunx read-s16 :optional port endian
@defunx read-s32 :optional port endian
@defunx read-s64 :optional port endian
@{@t{binary.io}@}
Reads 8, 16, 32 or 64 bit 2's complement signed integer from @var{port}
with specified endian, respectively.  If @var{port} is omitted,
current input port is used.  If @var{port} reaches EOF before
a complete integer is read, EOF is returned.
@end defun

@defun read-uint size :optional port endian
@defunx read-sint size :optional port endian
@{@t{binary.io}@}
More flexible version.  Reads @var{size}-octet unsigned
or signed integer from @var{port} with specified endian.
If @var{port} reaches EOF before a complete integer is read,
EOF is returned.
@end defun

@defun read-ber-integer :optional port
@{@t{binary.io}@}
Reads BER compressed integer a la X.209.
A BER compressed integer is an unsigned integer in base 128,
most  significant digit first, where the high bit is set on all but the
final (least significant) byte.
@end defun

@defun write-u8 val :optional port endian
@defunx write-u16 val :optional port endian
@defunx write-u32 val :optional port endian
@defunx write-u64 val :optional port endian
@{@t{binary.io}@}
Writes a nonnegative integer @var{val} as 8, 16, 32 or 64 bit
unsigned integer
to @var{port} with specified endian, respectively.  @var{Val} must be within
the range of integers representable by the specified bits.
When @var{port} is omitted, current output port is used.
@end defun

@defun write-s8 val :optional port endian
@defunx write-s16 val :optional port endian
@defunx write-s32 val :optional port endian
@defunx write-s64 val :optional port endian
@{@t{binary.io}@}
Writes an integer @var{val} as 8, 16, 32 or 64 bit
as 2's complement signed integer to @var{port} with specified endian,
respectively.  @var{Val} must be within
the range of integers representable by the specified bits.
When @var{port} is omitted, current output port is used.
@end defun

@defun write-uint size val :optional port endian
@defunx write-sint size val :optional port endian
@{@t{binary.io}@}
More flexible version.  Writes an integer @var{val} as unsigned
or signed integer of @var{size} bytes to @var{port} with
specified endian.
When @var{port} is omitted, current output port is used.
@end defun

@defun write-ber-integer val :optional port
@{@t{binary.io}@}
Writes a nonnegative integer @var{val} in BER compressed integer
to @var{port}.  See @code{read-ber-integer} above for BER format.
@end defun

@defun read-f16 :optional port endian
@defunx read-f32 :optional port endian
@defunx read-f64 :optional port endian
@{@t{binary.io}@}
Reads 16, 32, or 64-bit floating point numbers, respectively.
32bit is IEEE754 single-precision, and 64bit is
IEEE754 double-precision numbers.  16-bit floating
point number consists of 1-bit sign, 5-bit exponent and
10-bit mantissa, as used in some HDR image format.

If @var{port} is omitted,
current input port is used.  If @var{port} reaches EOF before
a complete number is read, EOF is returned.
@end defun

@defun write-f16 val :optional port endian
@defunx write-f32 val :optional port endian
@defunx write-f64 val :optional port endian
@{@t{binary.io}@}
Writes a real number @var{val} to @var{port} in 16,
32, or 64-bit floating point number, respectively.
If @var{port} is omitted, current output port is used.
@end defun


@subheading I/O using uniform vectors

In the following routines, the argument @var{uv} can be any
type of uniform vector; if it is not a @code{u8vector}, it is
treated as if @code{(uvector-alias <u8vector> @var{uv})} is
called---that is, it reads directly from the memory image
that holds the uvector's content.  The @var{pos} argument
specifies the byte position from the beginning of the memory
area (it is always byte position, regardless of the uniform
vector's element size).

@defun get-u8 uv pos :optional endian
@defunx get-u16 uv pos :optional endian
@defunx get-u32 uv pos :optional endian
@defunx get-u64 uv pos :optional endian
@defunx get-s8 uv pos :optional endian
@defunx get-s16 uv pos :optional endian
@defunx get-s32 uv pos :optional endian
@defunx get-s64 uv pos :optional endian
@defunx get-f16 uv pos :optional endian
@defunx get-f32 uv pos :optional endian
@defunx get-f64 uv pos :optional endian
@{@t{binary.io}@}
Reads a number of a specific format from a uniform vector @var{uv},
starting at a byte position @var{pos}.  An error is signaled
if the specified position makes reference outside of the uniform
vector's content.  Returns the read number.
@end defun

@defun get-u16be uv pos
@defunx get-u16le uv pos
@defunx get-u32be uv pos
@defunx get-u32le uv pos
@defunx get-u64be uv pos
@defunx get-u64le uv pos
@defunx get-s16be uv pos
@defunx get-s16le uv pos
@defunx get-s32be uv pos
@defunx get-s32le uv pos
@defunx get-s64be uv pos
@defunx get-s64le uv pos
@defunx get-f16be uv pos
@defunx get-f16le uv pos
@defunx get-f32be uv pos
@defunx get-f32le uv pos
@defunx get-f64be uv pos
@defunx get-f64le uv pos
@{@t{binary.io}@}
These are big-endian (@code{be}) or little-endian (@code{le}) specific
versions of @code{get-*} procedures.  In speed-sensitive code,
you might want to use these to avoid the overhead of optional-argument
handling.
@end defun

@defun get-uint size uv pos :optional endian
@defunx get-sint size uv pos :optional endian
@{@t{binary.io}@}
Read @var{size} octets from uvector @var{uv},
starting from @var{pos}-th octet, as an unsigned or signed integer,
respectively.

@example
(get-uint 3 '#u8(1 2 3 4) 1 'big-endian)
  @result{} 131884 ; @r{#x020304}

(get-sint 3 '#u9(1 2 3 #xff) 1 'little-endian)
  @result{} -64766 ; @r{sign extended #xff0302}
@end example
@end defun

@defun put-u8! uv pos val :optional endian
@defunx put-u16! uv pos val :optional endian
@defunx put-u32! uv pos val :optional endian
@defunx put-u64! uv pos val :optional endian
@defunx put-s8! uv pos val :optional endian
@defunx put-s16! uv pos val :optional endian
@defunx put-s32! uv pos val :optional endian
@defunx put-s64! uv pos val :optional endian
@defunx put-f16! uv pos val :optional endian
@defunx put-f32! uv pos val :optional endian
@defunx put-f64! uv pos val :optional endian
@{@t{binary.io}@}
Writes a number @var{val} into a uniform vector @var{uv} in
a specific format, starting at a byte position @var{pos}.
An error is signaled
if the specified position makes reference outside of the uniform
vector's content.
@end defun

@defun put-u16be! uv pos val
@defunx put-u16le! uv pos val
@defunx put-u32be! uv pos val
@defunx put-u32le! uv pos val
@defunx put-u64be! uv pos val
@defunx put-u64le! uv pos val
@defunx put-s16be! uv pos val
@defunx put-s16le! uv pos val
@defunx put-s32be! uv pos val
@defunx put-s32le! uv pos val
@defunx put-s64be! uv pos val
@defunx put-s64le! uv pos val
@defunx put-f16be! uv pos val
@defunx put-f16le! uv pos val
@defunx put-f32be! uv pos val
@defunx put-f32le! uv pos val
@defunx put-f64be! uv pos val
@defunx put-f64le! uv pos val
@{@t{binary.io}@}
These are big-endian (@code{be}) or little-endian (@code{le}) specific
versions of @code{put-*} procedures.  In speed-sensitive code,
you might want to use these to avoid the overhead of optional-argument
handling.
@end defun

@defun put-uint! size uv pos val :optional endian
@defunx put-sint! size uv pos val :optional endian
@{@t{binary.io}@}
Write an unsigned or signed integer @var{val} into
an uvector @var{uv} starting from @var{pos}-th octet,
for @var{size} octets, respectively.
@end defun


@subheading Compatibility notes

@code{read-u8} etc. were called @code{read-binary-uint8} etc., and
@code{read-f32} and @code{read-f64} were called @code{read-binary-float}
and @code{read-binary-double}, respectively.
These old names are still supported for the backward compatibility
but their use is deprecated.  The reason of the changes is
for brevity and for consistency with the uniform vectors.

@c ----------------------------------------------------------------------
@node Packing binary data, Running Chibi-scheme test suite, Binary I/O, Library modules - Utilities
@section @code{binary.pack} - Packing binary data
@c NODE バイナリデータのパック, @code{binary.pack} - バイナリデータのパック

@deftp {Module} binary.pack
@mdindex binary.pack
This module provides an interface for packing and unpacking (writing
and reading) binary data with templates.  The functionality was
inspired largely by the Perl pack/unpack functions, with comparison of
similar features from other languages, however an effort was made to
make it more general and more efficient, to be usable for
database-like processing.  To that end, the most notable differences
are that any packable value is unpackable (and vice versa), and the
default behavior is to pack and unpack using port I/O, so you can seek
in a large file and unpack from it.  Also, templates may be stored as
dispatch closures to pack, unpack or even skip over values without
re-parsing the template.

@c See also binary.io - Binary I/O for utilities to read and write
@c individual binary values.
@end deftp

@defun pack template list :key output to-string?
@{@t{binary.pack}@}
Writes the values in @var{list} to the current output port, according
to the format specified by the string @var{template}.  The template
string is a series of single character codes, optionally followed by a
numeric count (which defaults to 1).
The format characters can generally be divided into string types,
which interpret the count as a string byte size, and object types,
which treat the count as a repetition indicator.  The count may be
specified as the character @code{*}, which means to use the full
size of the string for string types, and use all remaining values for
object types.
Counts may also be specified as a template enclosed in brackets, which
means the count is the byte size of the enclosed template.  For
example, @code{x[L]} skips a long.
The special format character @code{/} may be used to indicate a
structure where the packed data contains a dynamic count followed by
the value itself.  The template is written as
@code{<count-item>/<value-item>}, where @code{<count-item>} is any
template character to be interpreted as a numeric count, and
@code{<value-item>} is any other template character to use this count.
If a normal count is given after @code{<value-item>} it is ignored.
The format character @code{@@} may be used with a count to pad to an
absolute position since the start of the template.
Sub-templates may be grouped inside parentheses.  If angle-brackets
are used, then they also behave as group operators but recursively
operate on nested lists.
The string types:
@table @code
@item a
An arbitrary incomplete string, null padded.

@item A
A text string, space padded.

@item Z
A null terminated (ASCIZ) string, null padded.

@item b
A bit string (ascending bit order inside each byte).

@item B
A bit string (descending bit order inside each byte).

@item h
A hex string (low nybble first).

@item H
A hex string (high nybble first).
@end table

The object types:

@table @code
@item c
A signed 8bit integer.

@item C
An unsigned 8bit integer.

@item s
A signed short (16 bit) value.

@item S
An unsigned short (16 bit) value.

@item i
A signed integer (>= 32 bit) value.

@item I
An unsigned integer (>= 32 bit) value.

@item l
A signed long (32 bit) value.

@item L
An unsigned long (32 bit) value.

@item n, n!
An unsigned and signed short (16 bit) in "network" (big-endian) order.

@item N, N!
An unsigned and signed long (32 bit) in "network" (big-endian) order.

@item v, v!
An unsigned and signed short (16 bit) in "VAX" (little-endian) order.

@item V, V!
An unsigned and signed long (32 bit) in "VAX" (little-endian) order.

@item q
A signed quad (64 bit) value.

@item Q
An unsigned quad (64 bit) value.

@item f
A single-precision float in the native format.

@item d
A double-precision float in the native format.

@item w
A BER compressed integer.  An unsigned integer in base 128, most
significant digit first, where the high bit is set on all but the
final (least significant) byte.  Thus any size integer can be encoded,
but the encoding is efficient and small integers don't take up any
more space than they would in normal char/short/int encodings.

@item x
A null byte.

@item o
An sexp, handled with @code{read} and @code{write}.

@end table

If the optional keyword @var{:output} is given that port is used
instead of the current output port.  If @var{:to-string?} is given and
true, then pack accumulates and returns the output as a string.

Note that the returned string may be an incomplete string
if the packed string contains a byte sequence invalid as
a character sequence.

@example
(pack "CCCC" '(65 66 67 68) :to-string? #t)
 @result{} "ABCD"

(pack "C/a*" '("hello") :to-string? #t)
 @result{} "\x05hello"
@end example
@end defun

@defun unpack template :key :input :from-string
@{@t{binary.pack}@}
The complement of pack, unpack reads values from the current input
port assuming they've been packed according to the string template and
returns the values as a list.  unpack accepts the same format strings
as pack.  Further, the following tautology holds:

@example
(equal? x (unpack fmt :from-string (pack fmt x :to-string? #t)))
@end example

for any list @var{x} and format string @var{fmt}.  The only exceptions
to this are when the template includes a @code{*} and when the
@code{o} template is used, since Scheme numeric literals cannot be
reliably delimited (though future versions of @code{pack} may
circumvent this by registering a new read syntax).

If the optional keyword @var{:input} is given that port is used
instead of the current input port.  If @var{:from-string} is given,
then pack reads input from that string.

@example
(unpack "CCCC" :from-string "ABCD")
 @result{} '(65 66 67 68)

(unpack "C/a*" :from-string "\x05hello")
 @result{} '("hello")
@end example

@emph{Note:} in the current version, @code{@@} in @code{unpack}
template has a bug and does not work as supposed.  It will
be fixed in the future version.
@end defun

@defun unpack-skip template :key :input
@{@t{binary.pack}@}
unpack-skip is the same as unpack except it does not return the
values.  In some cases, particularly with fixed-size templates, this
can be much more efficient when you just want to skip over a value.
@end defun

@defun make-packer template
@{@t{binary.pack}@}
The low-level interface.  This function returns a dispatch closure
that can be used to pack, unpack and skip over the same cached
template.  The dispatch closure accepts symbol methods as follows:

@table @code
@item 'pack list
pack the items in list to the current output port.

@item 'unpack
unpack items from the current input port.

@item 'skip
skip items from the current input port.

@item 'packer
return the cached 'pack closure

@item 'unpacker
return the cached 'unpack closure.

@item 'skipper
return the cached 'skip closure.

@item 'length
return the known fixed length of the template.

@item 'variable-length?
return #t if the template has variable length elements.
@end table
@end defun

@c ----------------------------------------------------------------------

@node Running Chibi-scheme test suite, Rational-less arithmetic, Packing binary data, Library modules - Utilities
@section @code{compat.chibi-test} - Running Chibi-scheme test suite
@c NODE Chibi schemeテストの実行, @code{compat.chibi-test} - Chibi schemeテストの実行

@deftp {Module} compat.chibi-test
@mdindex compat.chibi-test
Quite a few srfis come with test suites that's to be run with
Chibi Scheme test framework.  This module enables Gauche to run
the test code as is.
@end deftp

@defmac chibi-test code @dots{}
Run @var{code} @dots{}, while translating Chibi test framework
to Gauche's.

A typical usage is to write a wrapper that includes the original
test code (suppose it's called @file{test-suite.scm}):

@example
(use gauche.test)
(test-start "running test-suite.scm")
(chibi-test
  (include "test-suite.scm"))
(test-end)
@end example

Chibi's test directives are translated to Gauche's test directives
(@pxref{Unit testing}, for Gauche's test framework).

The main thing is that Chibi allows expressions and definitions to
be intermingled within a body, while Gauche only allows all definitions
before expressions within a body.
We expand such body into nested @code{let} by @code{chibi-test} macro.
Chibi test macros (e.g. @code{test-assert}) are defined as local macros
in @code{chibi-test} expansion, which expand into @code{gauche.test}
macros.

Note that we ignore @code{use} forms inside @code{chibi-test}; we might
want to use different modules that work better in Gauche.  Necessary
modules need to be @code{use}'d before you call @code{chibi-test}.

You may want to check out @file{test/srfi.scm} in Gauche source tree
for the use case.
@end defmac


@c ----------------------------------------------------------------------

@node Rational-less arithmetic, A common job descriptor for control modules, Running Chibi-scheme test suite, Library modules - Utilities
@section @code{compat.norational} - Rational-less arithmetic
@c NODE 有理数のない算術演算, @code{compat.norational} - 有理数のない算術演算

@deftp {Module} compat.norational
@mdindex compat.norational

Until release 0.8.7, Gauche didn't have exact rational numbers.
It was able to read the rational number literals such as
@code{2/3}, but they are immediately coerced to inexact real
numbers (except when it represents a whole integer).
And if you divided an exact integer by another exact integer,
the result could be coerced to an inexact real if the result
wasn't a whole integer.

As of 0.8.8, this is not the case anymore.  Exact division
always yields exact result, except when the divisor is zero.
@example
(/ 2 3)  @result{} 2/3
(/ 5)    @result{} 1/5
(/ 4 2)  @result{} 2
@end example

This is more precise, but has one drawback: exact rational
arithmetic is much slower than the integer and inexact real
arithmetic.  If you inadvertently produce
a rational number in the early stage of calculation, and
continue to apply exact arithmetic, performance would be
degraded miserably.

The proper way to solve this is to insert @code{exact->inexact}
to appropriate places.  However, to ease the transition, you can
just import this module and the division @code{/} behaves
in the way it used to.

@example
(use compat.norational)

(/ 2 3)  @result{} 0.6666666666666666
(/ 5)    @result{} 0.2
(/ 4 2)  @result{} 2
@end example

The effect is not global, but only to the modules you explicitly
import @code{compat.norational}.

This module only redefines @code{/}.  So if your code has
exact rational literals, they are treated as exact rationals
rather than coerced to inexact reals.  You should prefix
rational literals with @code{#i} to force Gauche to coerce
them to inexact reals:
@example
gosh> 1/3
1/3
gosh> #i1/3
0.3333333333333333
@end example
@end deftp

@c ----------------------------------------------------------------------
@node A common job descriptor for control modules, Thread pools, Rational-less arithmetic, Library modules - Utilities
@section @code{control.job} - A common job descriptor for control modules
@c NODE 制御モジュールのための汎用ジョブ記述子, @code{control.job} - 制御モジュールのための汎用ジョブ記述子

@deftp {Module} control.job
@mdindex control.job
This module provides a @code{job} record type, a lightweight
structure to be used in the control flow subsystems
(@code{control.*} modules).
Currently the only user is @code{control.thread-pool}, but
some other modules are planned to use @code{job} records.

A @code{job} record may be returned to an application
by other @code{control.*} modules so that the application
can keep track of the job.  It's not meant for
general use, however.   An application isn't supposed to
create a new job, or to modify its content; it can just query
the job's properties.

In this section we only describe procedures an application
needs to know.  The interface for control subsystems is still
fluid and may be changed as more subsystems are developed.

Different control flow subsystems may use job structure differently.
This section only describes the common properties.  Check the
individual control flow module to know how to handle returned job
objects.
@end deftp

@deftp {Record type} job
@{@t{control.job}@}
A record type denotes the job.  Applications should treat it
as an opaque structure.
@end deftp

@defun job? obj
@{@t{control.job}@}
Returns @code{#t} iff @var{obj} is a job record, @code{#f} otherwise.
@end defun

@defun job-status job
@{@t{control.job}@}
Returns the status of the job.  It may be either one of the followings.
@table @code
@item #f
Newborn or orphaned job.  Usually an application won't see a job
in this status.
@item acknowledged
A job is recognized by a control flow library, but haven't yet
been run.
@item running
A job is being processed.
@item done
A job is finished.  An application can retrieve its result
by @code{job-result}.
@item error
A job is terminated by an error.  An application can retrieve the
error causing condition by @code{job-result}.
@item killed
A job is killed by external force.  An application can retrieve the
reason of kill (which is specific to a particular control flow
subsystem) by @code{job-result}.
@end table
@end defun

@defun job-result job
@{@t{control.job}@}
If the job is in @code{done} status, it returns the result of the job.
If the job is in @code{error} status, it returns the condition object
that describes the error.
If the job is in @code{killed} status, it returns an object describing
the reason of kill.  The details of the object depends on a particular
control flow library.
Calling @code{job-result} on a job in any other status may return
anything; you can't rely on the result.
@end defun

@defun job-wait job :optional timeout timeout-val
@{@t{control.job}@}
Suspends the calling thread until the job becomes either
@code{done}, @code{error} or @code{killed} status.  If the job
is already in one of those status, it returns immediately.
Returns job's status.

If @var{timeout} is given and not @code{#f}, it must be
a valid timeout spec (a @code{<time>} object that represents
an absolute time point, or a real number that represents a
relative time in seconds.)  The meaning of @var{timeout} is
the same as in @code{mutex-unlock!} (@pxref{Synchronization primitives}).
Once the timeout reaches, @code{job-wait} returns no matter
how the job's status is, and returns the value specified
to @var{timeout-val}, which defaults to @code{#f}.

Depending on the control flow subsystem, jobs created by it
may not be waitable; check out each subsystem's documentation for the details.
@end defun

@defun job-acknowledge-time job
@defunx job-start-time job
@defunx job-finish-time job
@{@t{control.job}@}
If the control flow subsystem keeps track of timestamps,
these procedure returns the time (in @code{<time>} objects)
when the job is acknowledged, started and finished (either normally,
or abnormally by an error or by being killed).  If the job hasn't
reached to certain status, @code{#f} is returned instead.

If the subsystem does not track timestamps, these procedures
always returns @code{#f}.
@end defun

@c ----------------------------------------------------------------------
@node Thread pools, Password hashing, A common job descriptor for control modules, Library modules - Utilities
@section @code{control.thread-pool} - Thread pools
@c NODE スレッドプール, @code{control.thread-pool} - スレッドプール

@deftp {Module} control.thread-pool
@mdindex control.thread-pool
Provides thread pools.  Only available when Gauche is compiled
with pthreads support.
@end deftp

@deftp {Class} <thread-pool>
@clindex thread-pool
@{@t{control.thread-pool}@}
A class for thread pool objects.   It maintains a set of worker threads, and
let them work on the jobs you ask to do asynchronously.

Currently the size of pool (number of threads) is fixed
and you have to specify it when creating a pool.
In future we might add a feature to grow or shrink the pool.

You can also set maximum backlog of the job queue.  You cannot
put a job when the queue already reaches the max length (see
@code{add-job!} below).
@end deftp


@deftp {Condition type} <thread-pool-shut-down>
@{@t{control.thread-pool}@}
A condition indicating that a thread pool is already shut down
by @code{terminate-all!} and no longer accepting new jobs.
Inherits @code{<error>}.  The following slot is provided.

@defivar <thread-pool-shut-down> pool
The thread pool object that caused the condition.
@end defivar
@end deftp

@defun make-thread-pool size :key (max-backlog 0)
@{@t{control.thread-pool}@}
Creates a new thread pool of size @var{size} (the number of
worker threads).  Optionally you can give a nonnegative integer
to the maximum backlog; 0 means unlimited.
@end defun

@defun thread-pool-results pool
@{@t{control.thread-pool}@}
When you put a job to a thread pool, you can specify
whether you need to check its result or not.  If you say you need
a result, the terminated job is queued to a @emph{result queue},
an @code{<mt-queue>} object, in the pool.
This procedure returns the pool's result queue.
@xref{Queue}, for the details of @code{<mt-queue>}.
@end defun

@defun thread-pool-shut-down? pool
@{@t{control.thread-pool}@}
Returns @code{#t} if the thread pool is shut down and no longer
accepting new jobs, or @code{#f} otherwise.
@end defun

@defun add-job! pool thunk :optional (need-result #f) (timeout #f)
@{@t{control.thread-pool}@}
Add a @var{thunk} to be executed in the thread pool @var{pool}.
Returns a @code{job} record (@pxref{A common job descriptor for control modules}).

The returned job record is not waitable; if you need to track
its result, you have to give a true value to @var{need-result}
argument.  Then when the job is terminated (either normally or
abnormally) the job is queued to the @code{result-queue} of
the pool, and you can check the queue.   If you don't pass
a true value to @var{need-result}, the job won't be queued
to @code{result-queue} even it is terminated.

The returned job is timestamped.  You can examine acknowledged
time, start time and finish time of the job (if the job hasn't
been started and/or finished, the corresponding timestamp fields
are @code{#f}.)  It's sometimes
handy to find out how long the job was waiting in the
queue and how long it took to run.

If the pool has positive @code{max-backlog} value, and it
already has that many jobs to be waiting, then @code{add-job!}
blocks until some jobs are start being executed.
You can give a real number in seconds, or a @code{<time>} object
as an absolute point of time, to the @var{timeout} argument
to set the time limit of blocking.  If timeout is reached,
@code{add-job!} returns @code{#f} without creating any job.
Omitting @var{timeout}
or giving @code{#f} to it sets no timeout.

(Note: This behavior is different from 0.9.1, in which @code{add-job!}
didn't take the timeout argument and always behaved as if zero
timeout value was given.  To achieve the same behavior, you have
to give 0 to the @var{timeout} argument explicitly.)

If the thread pool is shut down, this procedure
raises @code{<thread-pool-shut-down>} condition.
@end defun

@defun wait-all pool :optional (timeout #f) (check-interval #e5e8)
@{@t{control.thread-pool}@}
Wait for the job queue to be empty and
all worker threads to finish.  It is done by polling the
pool's status in every @var{check-interval} nanoseconds.
Returns @code{#t} if all jobs are finished.

You can give a real number in seconds, or a @code{<time>} object
as an absolute point of time, in @var{timeout} optional argument.
When timeout is reached, @code{wait-all} returns @code{#f}.
@end defun

@defun terminate-all! pool :key (force-timeout #f) (cancel-queued-jobs #f)
@{@t{control.thread-pool}@}
Wait for all the queued jobs to be finished, then ask all threads
to terminate.  After calling this procedure, the pool no longer
accepts new jobs.  Calling @code{add-job!} on this module would
raise a @code{<thread-pool-shut-down>} condition.
This is intended to be called when shutting down the application.

By default, this procedure first waits for all queued jobs
to be handled, then tries to terminate threads gracefully.

Giving a true value to the @var{cancel-queued-jobs} argument
immediately cancels queued but not started jobs; the status
of such jobs is set @code{killed}.
It does not cancels already started jobs, though.

If you want to cancel already started jobs,
you can give a timeout value (either @code{<time>} object to
specify absolute point of time, or a real number indicating
relative time in seconds) to the @var{force-timeout} argument.
Once timeout is reached, it forcefully terminates the threads
and the jobs handled at that time are also killed.

Forcing termination of threads is an extreme measure; the terminated
thread may not have a chance to clean up properly.  So it is usually
better to give some time for the thread to finish the executing jobs.
@end defun

@c ----------------------------------------------------------------------
@node Password hashing, Cache, Thread pools, Library modules - Utilities
@section @code{crypt.bcrypt} - Password hashing
@c NODE パスワードハッシュ, @code{crypt.bcrypt} - パスワードハッシュ

@deftp {Module} crypt.bcrypt
@mdindex crypt.bcrypt
This module implements a password hashing algorithm using blowfish,
and compatible to OpenBSD's bcrypt algorithm (version 2a, 2b).

Don't use version ``2a'' for new code. It's vulnerable.
Use version ``2b''.

The typical usage of this module is simple enough.
To get a new password hash value (e.g. for a new user), pass the
password string to @code{bcrypt-hashpw} as the only argument:

@example
(bcrypt-hashpw @var{password})
  @result{} @r{hashed-string}
@end example

The routine automatically adds a salt value.  The returned hash
string can be stored in the user database.  To check if the given
password matches the stored one, pass the
hashed string as the second argument of @code{bcrypt-hashpw} to
check the password.

@example
(bcrypt-hashpw @var{password} @var{hashed-string})
  @result{} @r{hashed-string}
@end example

If the given password is correct, the returned value should
exactly matches @var{hash-string}.
@end deftp

@defun bcrypt-hashpw password :optional setting
@{@t{crypt.bcrypt}@}
Calculates a hash value of @var{password}, using the salt value
and parameters included in @var{setting}.  If @var{setting} is
omitted, a suitable default settings and random salt value is
chosen automatically.

The returned hash value contains the salt value and parameters,
and can be used as @var{setting}.  So, to check the password
against existing hash value, just pass the hash value to
@var{setting}; if the password is correct, the returned hash value
should match the one you passed in.

The bcrypt algorithm supports up to 72 octets for the password.

To tweak parameters when you calculate a new hash value,
use @code{bcrypt-gensalt} below to get the initial @var{setting}
value.
@end defun

@defun bcrypt-gensalt :key prefix count entropy-source
@{@t{crypt.bcrypt}@}
Returns a string that contains given parameters and suitable to
pass to the @var{setting} argument of @code{bcrypt-hashpw}.

The @var{prefix} argument specifies the version/scheme of
password hashing.  Currently @code{$2a$} and @code{$2b$} are supported,
which means the blowfish algorithm compatible to bcrypt.
But @code{$2a$} is vulnerable. Use @code{$2b$} for new code.
If you omit @var{prefix}, use @code{$2b$} for default value.

The @var{count} argument specifies the amount of iterations;
the larger the value is, the more time is required to calculate
the hash value.  Note that for the password hashing, taking more
time is actually a good thing, for it works against the dictionary attack.
For normal password checking you need to run the hash routine only
once per login, so it doesn't matter if the calculation takes a fraction
of second.
The bcrypt algorithm iterates @code{(expt 2 @var{count})} times.

The @var{entropy-source} argument is a @code{u8vector} to feed
a random bytes.  For bcrypt algorithm it must be at least 16 octet long.
@end defun

@c ----------------------------------------------------------------------
@node Cache, Heap, Password hashing, Library modules - Utilities
@section @code{data.cache} - Cache
@c NODE キャッシュ, @code{data.cache} - キャッシュ

@deftp {Module} data.cache
@mdindex data.cache
A cache works similarly as a dictionary, associating keys to values,
but its entries may disappear according to the policy of the cache
algorithm.  This module defines
a common protocol for cache datatypes, and also provides several
typical cache implementations.
@end deftp

@subheading Examples

Let's start from simple examples to get the idea.

Suppose you want to read given files and you want to
cache the frequently read ones.  The following code defines
a cached version of @code{file->string}:

@example
(use data.cache)
(use file.util)

(define file->string/cached
  (let1 file-cache (make-lru-cache 10 :comparator string-comparator)
    (^[path] (cache-through! file-cache path file->string))))
@end example

The procedure closes a variable @code{file-cache},
which is an LRU (least recently used) cache that associates
string pathnames to the file contents.
The actual logic is in @code{cache-through!}, which first consults the
cache if it has an entry for the @code{path}.  If the cache has
the entry, its value (the file content) is returned.  If not,
it calls @code{file->string} with the @var{path} to fetch the file content,
register it to the cache, and return it.  The capacity of cache is
set to 10 (the first argument of @code{make-lru-cache}), so when the
11th file is read, the least recently used file will be purged from the
cache.

The effect of cache isn't very visible in the above example.  You
can insert some print stubs to see the cache is actually in action,
as the following example.
Try read various files using @code{file->string/cached}.

@example
(define file->string/cached
  (let1 file-cache (make-lru-cache 10 :comparator string-comparator)
    (^[path]
      (print #"file->string/cached called on ~path")
      (cache-through! file-cache path
                      (^[path]
                        (print #"cache miss.  fetching ~path")
                        (file->string path))))))
@end example

Caveat: A cache itself isn't MT-safe.  If you are using it in
multithreaded programs, you have to wrap it with an atom
(@pxref{Synchronization primitives}):

@example
(use data.cache)
(use file.util)
(use gauche.threads)

(define file->string/cached
  (let1 file-cache (atom (make-lru-cache 10 :comparator string-comparator))
    (^[path]
      (atomic file-cache (cut cache-through! <> path file->string)))))
@end example

@subheading Common properties of caches

A cache of any kind has a comparator and a storage.
The comparator is used to compare keys; in the example above,
we use @code{string-comparator} to compare string pathnames
(@pxref{Basic comparators}, for more about comparators).

The storage is a dictionary that maps keys to internal
structures of the cache.  By default, a hashtable is
created automatically using the given comparator (or,
if a comparator is omitted, using @code{default-comparator}).
The comparator must have hash function.

Alternatively, you can give a pre-filled dictionary
(copied from another instance of the same kind of cache) 
to start cache with some data already in it.  Note that
what the cache keeps in the dictionary totally depends on the
cache algorithm, so you can't just pass a random dictionary;
it has to be created by the same kind of cache.
If you pass in the storage, the comparator is taken from it.

Thus, the cache constructors uniformly take keyword arguments
@var{comparator} and @var{storage}; you can specify either one,
or omit both to use the defaults.

@subheading Predefined caches

For the @var{storage} and @var{comparator} keyword arguments, see above.

@defun make-fifo-cache capacity :key storage comparator
@{@t{data.cache}@}
Creates and returns a FIFO (first-in, first-out) cache that can
hold up to @var{capacity} entries.
If the number of entries exceeds @var{capacity}, the oldest entry
is removed.
@end defun

@defun make-lru-cache capacity :key storage comparator
@{@t{data.cache}@}
Creates and returns an LRU (least recently used) cache that can
hold up to @var{capacity} entries.
If the number of entries exceeds @var{capacity}, the least recently used
entry is removed.
@end defun

@defun make-ttl-cache timeout :key storage comparator timestamper
@{@t{data.cache}@}
Creates and returns a TTL (time to live) cache with the timeout value
@var{timeout}.
Each entry is timestamped when it's inserted, and it is removed
when the current time passes @var{timeout} unit from the timestamp.
The actual entry removal is done when the cache is accessed.

By default, the Unix system time (seconds from Epoch) is used
as a timestamp, and @var{timeout} is in seconds.  It may not be
fine-grained enough if you add multiple entries in shorter intervals
than seconds.   You can customize
it by giving a thunk to @var{timestamper}; the thunk is called to
obtain a timestamp, which can be any monotonically increasing real number
(it doesn't need to be associated with physical time).
If you give @var{timestamper}, the unit of @var{timeout} value should
be the same as whatever @var{timestamper} returns.
@end defun

@defun make-ttlr-cache timeout :key storage comparator timestamper
@{@t{data.cache}@}
A variation of TTL cache, but the entry's timestamp is updated
(refreshed) whenever the entry is read.  Hence we call it TTL with refresh
(TTLR).  But you can also think it as a variation of LRU cache with
timeout.

The unit of timeout, and the role of @var{timestamper} argument, are
the same as @code{make-ttl-cache}.
@end defun

@subheading Common operations of caches

The following APIs are for the users of a cache.

@defun cache-lookup! cache key :optional default
@{@t{data.cache}@}
Look for an entry with @var{key} in @var{cache}, and returns its
value if it exists.  If there's no entry, the procedure returns @var{default}
if it is provided, or throws an error otherwise.

Some types of cache algorithms update @var{cache} by this operation, hence
the bang is in the name.
@end defun

@defun cache-through! cache key value-fn
@{@t{data.cache}@}
Look for an entry with @var{key} in @var{cache}, and returns its
value if it exists.  If there's no entry, a procedure @var{value-fn}
is called with @var{key} as the argument, and its return value
is inserted into @var{cache} and also returned.
@end defun

@deffn {Generic function} cache-write! cache key value
@{@t{data.cache}@}
This inserts association of @var{key} and @var{value} into @var{cache}.
If there's already an entry with @var{key}, it is overwritten.
Otherwise a new entry is created.

The same effect can be achieved by calling @code{cache-evict!} then
@code{cache-through!}, but cache algorithms may provide efficient
way through this method.
@end deffn

@deffn {Generic function} cache-evict! cache key
@{@t{data.cache}@}
Removes an entry with @var{key} from @var{cache}, if it exists.
@end deffn

@deffn {Generic function} cache-clear! cache
@{@t{data.cache}@}
Removes all entries from @var{cache}.
@end deffn

@subheading Implementing a cache algorithm

Each cache algorithm must define a class inheriting @code{<cache>},
and implement the following two essential methods.
The higher-level API calls them.

@deffn {Generic function} cache-check! cache key
@{@t{data.cache}@}
Looks for an entry with @var{key} in @var{cache}.
If it exists, returns a pair of @var{key} and the associated value.
Otherwise, returns @code{#f}.  It may update the cache,
for example, the timestamp of the entry for being read.
@end deffn

@deffn {Generic function} cache-register! cache key value
@{@t{data.cache}@}
Add an entry with @var{key} and associated @var{value} into @var{cache}.
This is called after @var{key} is confirmed not being in @var{cache}.
@end deffn

Additionally, the implementation should consider the following points.

@itemize @bullet
@item
The initialize method must call @code{next-method} first, which sets up
the @code{comparator} and @code{storage} slots.  You should check
if @code{storage} has pre-filled entries, and if so, set up other
internal structures appropriately.
@item
The default methods of @code{cache-evict!} and @code{cache-clear!} only
takes care of the storage of the cache.  You should implement them
if your auxiliary structure needs to be taken care of.
@item
The default method of @code{cache-write!} is just @code{cache-evict!}
followed by @code{cache-register!}.  You may provide alternative method
if you can do it more efficiently, which is often the case.
@end itemize

There are several procedures that help implementing cache subclasses:

@defun cache-comparator cache
@defunx cache-storage cache
@{@t{data.cache}@}
Returns the comparator and the storage of the cache, respectively.
@end defun

Typical caches may be constructed with a storage (dictionary) and
a queue, where the storage maps keys to @code{(<n> . <value>)},
and queues holds @code{(<key> . <n>)}, @code{<n>} being a number
(timestamp, counter, etc.)  Here are some common operations work
on this queue-and-dictionary scheme:

@defun cache-populate-queue! queue storage
@{@t{data.cache}@}
You can call this in the @code{initialize} method to set up the
queue.  This procedure walks storage to construct @code{(<key> . <n>)}
pairs, sorts it in increasing order of @code{<n>}, and pushes them
into the queue.
@end defun

@defun cache-compact-queue! queue storage
@{@t{data.cache}@}
The queue may contain multiple pairs with the same key.  Sometimes the
queue gets to have too many duplicated entries (e.g. the same entry
is read repeatedly).  This scans the queue and removes duplicated entries
but the up-to-date one.  After this operation, the length of the queue
and the number of entries in the storage should match.
@end defun

@defun cache-renumber-entries! queue storage
@{@t{data.cache}@}
This procedure renumbers @code{<n>}s in the queue and the storage
starting from 0, without changing their order, and returns the
maximum @code{<n>}.  The duplicated entries in the queue is removed
as in @code{cache-compact-queue!}.

When you're using monotonically increasing counter for @code{<n>} and
you don't want @code{<n>} to get too big (i.e. bignums), you can
call this procedure occasionally to keep @code{<n>}'s in reasonable
range.
@end defun


@c ----------------------------------------------------------------------
@node Heap, Immutable deques, Cache, Library modules - Utilities
@section @code{data.heap} - Heap
@c NODE ヒープ, @code{data.heap} - ヒープ

@deftp {Module} data.heap
@mdindex data.heap
A heap is a data container that allows efficient retrieval of
the minimum or maximum entry.  Unlike a @code{<tree-map>}
(@pxref{Treemaps}), which always keeps all entries in order,
a heap only cares the minimum or the maximum of the current set;
the other entries are only partially ordered, and reordered
when the minimu/maximum entry is removed.  Hence it is more
efficient than a treemap if all you need is minimum/maximum value.
Besides binary heaps can store entries in packed, memory-efficient way.
@end deftp

@deftp {Class} <binary-heap>
@clindex binary-heap
@{@t{data.heap}@}
An implementation of a binary heap.  Internally it uses min-max heap,
so that you can find both minimum and maximum value in O(1).
Pushing a new value and popping the minimum/maximum value are both O(log n).

It also stores its values in a flat vector, a lot more compact
than a general tree structure that needs a few pointers per node.
By default it uses a sparse vector for the backing storage, allowing
virtually unlimited capacity (@pxref{Sparse vectors}).
But you can use an ordinal vector
or a uniform vector as a backing storage instead.

A binary heap isn't MT-safe structure; you must put it in atom
or use mutexes if multiple threads can access to it
(@pxref{Synchronization primitives}).
@end deftp

@defun make-binary-heap :key comparator storage key
@{@t{data.heap}@}
Creates and returns a new binary heap.

The @var{comparator} keyword argument specifies how to compare the
entries.  It must have comparison procedure or ordering predicate.
The default is @code{default-comparator}.
@xref{Basic comparators}, for the details of comparators.

The @var{storage} keyword argument gives alternative
backing storage.  It must be either a vector, a uniform vector,
or an instance of a sparse vector (@pxref{Sparse vectors}).
The default is an instance of @code{<sparse-vector>}.
If you pass a vector or a uniform vector, it determines
the maximum number of elements the heap can hold.
The heap won't be extend the storage once it gets full.

The @var{key} keyword argument must be a procedure; it is applied
on each entry before comparison.  Using key procedure allows you to
store auxiliary data other than the actual value to be compared.
The following example shows the entries are compared by their @code{car}'s:

@example
(define *heap* (make-binary-heap :key car))
(binary-heap-push! *heap* (cons 1 'a))
(binary-heap-push! *heap* (cons 3 'b))
(binary-heap-push! *heap* (cons 1 'c))

(binary-heap-find-min *heap*) @result{} (1 . c)
(binary-heap-find-max *heap*) @result{} (3 . b)
@end example
@end defun

@defun build-binary-heap storage :key comparator key num-entries
@{@t{data.heap}@}
Create a heap from the data in @var{storage}, and returns it.
(Sometimes this operation is called @emph{heapify}.)
This allows you to create a heap without allocating a new storage.
The @var{comparator} and @var{key} arguments are the same as
@code{make-binary-heap}.

@var{Storage} must be either a vector, a uniform vector,
or an instance of a sparse vector.  The storage is modified
to satisfy the heap property, and will be used as the backing
storage of the created heap.  Since the storage will be owned
by the heap, you shouldn't modify the storage later.

The storage supposed to have keys from index 0 below
@var{num-entries}.
If @var{num-entries} is omitted or @code{#f}, entire vector or
uniform vector, or up to @code{sparse-vector-num-entries} on
the sparse vector, is heapified.
@end defun

@defun binary-heap-copy heap
@{@t{data.heap}@}
Copy the heap.  The backing storage is also copied.
@end defun

@defun binary-heap-clear! heap
@{@t{data.heap}@}
Empty the heap.
@end defun

@defun binary-heap-num-entries heap
@{@t{data.heap}@}
Returns the current number of entries in the heap.
@end defun

@defun binary-heap-empty? heap
@{@t{data.heap}@}
Returns @code{#t} if the heap is empty, @code{#f} otherwise.
@end defun

@defun binary-heap-push! heap item
@{@t{data.heap}@}
Insert @var{item} into the @var{heap}.  This is O(log n) operation.
If the heap is already full, an error is raised.
@end defun

@defun binary-heap-find-min heap :optional fallback
@defunx binary-heap-find-max heap :optional fallback
@{@t{data.heap}@}
Returns the minimum and maximum entry of the heap, respectively.
The heap will be unmodified.  This is O(1) operation.

If the heap is empty, @var{fallback} is returned when it is provided,
or an error is signaled.
@end defun

@defun binary-heap-pop-min! heap
@defunx binary-heap-pop-max! heap
@{@t{data.heap}@}
Removes the minimum and maximum entry of the heap and returns it,
respectively.  O(log n) operation.
If the heap is empty, an error is signaled.
@end defun

The following procedures are not heap operations, but provided
for the convenience.

@defun binary-heap-swap-min! heap item
@defunx binary-heap-swap-max! heap item
@{@t{data.heap}@}
These are operationally equivalent to the followings, respectively:

@example
(begin0 (binary-heap-pop-min! heap)
  (binary-heap-push! heap item))

(begin0 (binary-heap-pop-max! heap)
  (binary-heap-push! heap item))
@end example

However, those procedures are slightly efficient, 
using heap property maintaining procedure only once per function call.
@end defun



@defun binary-heap-find heap pred
@{@t{data.heap}@}
Returns an item in the heap that satisfies @var{pred}.
If there are more than one item that satisfy @var{pred},
any one of them can be returned.  If no item satisfy @var{pred},
@code{#f} is returned.  This is O(n) operation.
@end defun

@defun binary-heap-remove! heap pred
@{@t{data.heap}@}
Remove all items in the heap that satisfy @var{pred}.  This is O(n) operation.
@end defun

@defun binary-heap-delete! heap item
@{@t{data.heap}@}
Delete all items in the heap that are equal to @var{item},
in terms of the heap's comparator and key procedure.  This is O(n) operation.

Note that the key procedure is applied to @var{item} as well
before comparison.
@end defun

@c ----------------------------------------------------------------------
@node Immutable deques, Immutable map, Heap, Library modules - Utilities
@section @code{data.ideque} - Immutable deques
@c NODE 変更不可な両端キュー, @code{data.ideque} - 変更不可な両端キュー

@deftp {Module} data.ideque
@mdindex data.ideque
This module provides a functional double-ended queue (deque, 
pronounced as ``deck'').

Almost all procedures in this module are now a part of R7RS large.
@xref{R7RS immutable deques}, for description of the following
procedures:

@example
ideque               ideque-unfold        ideque-unfold-right
ideque-tabulate      ideque?              ideque-empty?
ideque-add-front     ideque-add-back
ideque-remove-front  ideque-remove-back
ideque-front         ideque-back
ideque-reverse       ideque=              ideque-ref
ideque-take          ideque-drop
ideque-take-right    ideque-drop-right
ideque-split-at      ideque-append        ideque-zip
ideque-map           ideque-for-each      ideque-for-each-right
ideque-fold          ideque-fold-right    ideque-append-map
ideque-filter        ideque-remove
ideque-find          ideque-find-right
ideque-take-while    ideque-take-while-right
ideque-drop-while    ideque-drop-while-right
ideque-span          ideque-break
ideque-any           ideque-every
ideque->list         list->ideque
ideque->generator    generator->ideque
@end example
@end deftp

@defun make-ideque n :optional init
@{@t{data.ideque}@}
Creates an ideque of length @var{n} with all the elements being
@var{init}.  If @var{init} is omitted, @code{#f} is used.

This is provided just for the symmetry with other container data
structures; it's not in srfi-134, and the portable code can use
@code{ideque-tabulate}.
@end defun


@c ----------------------------------------------------------------------
@node Immutable map, Priority map, Immutable deques, Library modules - Utilities
@section @code{data.imap} - Immutable map
@c NODE 変更不可なマップ, @code{data.imap} - 変更不可なマップ

@deftp {Module} data.imap
@mdindex data.imap
This module provides a immutable data structure with O(log n)
access and update operations (here, update means to return a
new structure with requested changes).
The current implementation is
based on the functional red-black tree.
@end deftp

Although lists and alists are useful for stack-like immutable
operations, where you can add and remove items to the head of
existing data without modifying them, they require O(n) access time
and sometimes you need better one.  The @code{<imap>} object
provides O(log n) access, in exchange of O(log n) insertion and
deletion.

@deftp {Class} <imap-meta>
@{@t{data.imap}@}
Metaclass of @code{<imap>}.
@end deftp

@deftp {Class} <imap>
@{@t{data.imap}@}
Immutable map class.  An instance of @code{<imap-meta>}.

Inherits @code{<ordered-dictionary>}, conforms dictionary protocol
except mutating operators (@pxref{Dictionary framework}).
As a sequence, you can access key-value
pairs in increasing order of keys.
@end deftp

@defun make-imap
@defunx make-imap comparator
@defunx make-imap key=? key<?
@{@t{data.imap}@}
Creates a new empty immutable map.  Without arguments,
@code{default-comparator} is used to compare keys.  To give a
specific comparator, use the second form; the @var{comparator}
argument should have comparison procedure.
For the details of comparators, @pxref{Basic comparators}.
The third form creates a key comparator from a equality
predicate @var{key=?} and less-than predicate @code{key<?},
both must accept two keys.  This interface is consistent with
@code{tree-map} (@pxref{Treemaps}).
@end defun

@defun alist->imap alist
@defunx alist->imap alist comparator
@defunx alist->imap alist key=? key<?
@{@t{data.imap}@}
Creates a new empty immutable map, populates it with
key-value association list @var{alist}, and returns it.
This may be a bit more efficient than creating an empty map with
@code{make-imap} and populates it with @code{imap-put}
one by one.

The @var{comparator} argument specifies how to compare the keys.
It must have comparison procedure.  If omitted, @code{default-comparator}
is used.  @xref{Basic comparators}, for the details.

The third form creates a key comparator from a equality
predicate @var{key=?} and less-than predicate @code{key<=?},
both must accept two keys.

@example
(define m (alist->imap '((a . 1) (b . 2))))

(imap-get m 'a) @result{} 1
(imap-get m 'b) @result{} 2
@end example
@end defun

@defun tree-map->imap tree-map
@{@t{data.imap}@}
Returns a new immutable map with the same content (and the same comparator)
as @var{tree-map}.
@end defun

@defun imap? obj
@{@t{data.imap}@}
Returns @code{#t} if @var{obj} is an immutable map,
@code{#f} otherwise.
@end defun

@defun imap-empty? immap
@{@t{data.imap}@}
Returns @code{#t} if an immutable map @var{immap} is empty,
@code{#f} otherwise.
@end defun

@defun imap-exists? immap key
@{@t{data.imap}@}
Returns @code{#t} if @var{key} exists in an immutable map @var{immap}.
@end defun

@defun imap-get immap key :optional default
@{@t{data.imap}@}
Returns the value associated with @var{key} in an immutable map @var{immap}.
If @var{immap} doesn't have @var{key}, @var{default} is returned
when provided, otherwise an error is signalled.
@end defun

@defun imap-put immap key val
@{@t{data.imap}@}
Returns a new immutable map where association of @var{key} to @var{val}
is added to (or replaced in) an immutable map @var{immap}.
This operation is O(log n).

@example
(define m1 (alist->imap '((a . 1) (b . 2))))

(define m2 (imap-put m1 'a 3))

(imap-get m2 'a)  @result{} 3
(imap-get m1 'a)  @result{} 1  ; not affected
@end example
@end defun

@defun imap-delete immap key
@{@t{data.imap}@}
Returns a new immutable map where @var{key} is removed from
@var{immap}.   If @var{immap} doesn't have @var{key}, returned
map has the same content as @var{immap}.

@example
(define m1 (alist->imap '((a . 1) (b . 2))))

(define m2 (imap-delete m1 'a))

(imap-get m2 'a #f)  @result{} #f
(imap-get m1 'a)     @result{} 1  ; not affected
@end example
@end defun

@defun imap-min immap
@defunx imap-max immap
@{@t{data.imap}@}
Returns a pair of key and value with the minimum or maximum
key in @var{immap}, respectively.  If @var{immap} is empty,
@code{#f} is returned.
@end defun

@c ----------------------------------------------------------------------
@node Priority map, Queue, Immutable map, Library modules - Utilities
@section @code{data.priority-map} - Priority map
@c NODE プライオリティマップ, @code{data.priority-map} - プライオリティマップ

@deftp {Module} data.priority-map
@mdindex data.priority-map
Priority map is a dictionary that can map keys to values, while
the entires are sorted by their @emph{values}.
(If the entires are sorted by keys, it's a treemap--@pxref{Treemaps}).

It is useful when you wanted a sorted sequence, with quick access by
keys that are associated to each value.

Note: If what you need is just a priority queue, you can use
@code{data.heap} (@pxref{Heap}).
@end deftp

@deftp {Class} <priority-map>
@cindex priority-map
@{@t{data.priority-map}@}
Priority map class.  It has no public slots.
Instances of priority maps must be created by
@code{make-priority-map} procedure instead of @code{make} method on
the class.

Inherits @code{<ordered-dictionary>}, and implements dictionary protocol.
Operations concerning
associations of keys and values are done through dictionary generic
functions (@pxref{Generic functions for dictionaries}).

When iterated, it iterates increasing order of values.
@end deftp

@defun make-priority-map :key key-comparator value-comparator
@{@t{data.priority-map}@}
Creates and returns an empty priority map.
It can take @var{key-comparator}, which must have a hash procedure
and is used to hash keys, and
@var{value-comparator}, which must have ordering predicate
and is used to order values.
When omitted, @code{default-comparator} is assumed.
@end defun

@defun priority-map-min pmap
@defunx priority-map-max pmap
@{@t{data.priority-map}@}
Return a pair of a key and a value, where the value is smallest or
largest in the priority map @var{pmap}, respectively.

If @var{pmap} is empty, @code{#f} is returned.

If @var{pmap} has more than one value that are equal to each other
(w.r.t. @var{value-comparator} given to the constructor),
either one of them is picked.
@end defun

@defun priority-map-pop-min! pmap
@defunx priority-map-pop-max! pmap
@{@t{data.priority-map}@}
Remove one entry with the smallest or largest value, respectively,
and returns a pair of the key and the value of removed entry.

If @var{pmap} is empty, @var{#f} is returned.

If @var{pmap} has more than one value that are equal to each other
(w.r.t. @var{value-comparator} given to the constructor),
either one of them is picked.
@end defun

@c ----------------------------------------------------------------------
@node Queue, Random data generators, Priority map, Library modules - Utilities
@section @code{data.queue} - Queue
@c NODE キュー, @code{data.queue} - キュー

@deftp {Module} data.queue
@mdindex data.queue
Provides a queue (FIFO).  You can create a simple queue,
which is lightweight but not thread-safe, or an MTqueue,
a thread-safe queue.  Basic queue operations work on
both type of queues.  When an mtqueue is passed to the
procedures listed in this section, each operation is
done in atomic way, unless otherwise noted.

There are also a set of procedures for mtqueues that
can be used for thread synchronization; for example,
you can let the consumer thread block if an
mtqueue is empty, and/or the producer thread block if the number
of items in the mtqueue reaches a specified limit.
Using these procedures allows the program to use an mtqueue
as a @emph{channel}.

The simple queue API is a superset of SLIB's queue implementation,
which supports not only @code{enqueue!} (add item to the end of the sequence)
and @code{dequeue!} (take item from the front of the sequence), but also
@code{queue-push!} (add item to the front of the sequence), so that
it can be used as a stack as well.

If you also want to take item from the end of the sequence in O(1),
you need a deque (double-ended queue).
@xref{Ring buffer}, which works as an efficient (both speed and space)
dequeue on top of vectors.  Or you can use immutable deques
provided by @code{data.ideque} (@pxref{Immutable deques}).

See also @code{scheme.list-queue} (@ref{R7RS list queues}), which defines a
portable API for list-based queue.
@end deftp

@deftp {Class} <queue>
@clindex queue
@{@t{data.queue}@}
A class of simple queue.

@defivar {<queue>} length
A read-only slot that returns the number of items in the queue.
@end defivar
@end deftp

@deftp {Class} <mtqueue>
@{@t{data.queue}@}
@clindex mtqueue
A class of mtqueue.  Inherits @code{<queue>}.

@defivar {<mtqueue>} max-length
The upper bound of the number of items in the queue.

If this slot is zero, the queue cannot hold any items, but
works as a synchronization device.
A writer will block until a reader appears to take the item;
a reader will block until a writer appears to give the item.
@end defivar
@end deftp

@defun make-queue
@{@t{data.queue}@}
Creates and returns an empty simple queue.
@end defun

@defun make-mtqueue :key max-length
@{@t{data.queue}@}
Creates and returns an empty mtqueue.  When an integer is given
to the keyword argument @var{max-length}, it is used to
initialize the @code{max-length} slot.
@end defun

@defun queue? obj
@{@t{data.queue}@}
Returns @code{#t} if @var{obj} is a queue (either a simple queue
or an mtqueue).
@end defun

@defun mtqueue? obj
@{@t{data.queue}@}
Returns @code{#t} if @var{obj} is an mtqueue.
@end defun

@defun queue-empty? queue
@{@t{data.queue}@}
Returns @code{#t} if @var{obj} is an empty queue.
@end defun

@defun queue-length queue
@{@t{data.queue}@}
Returns the number of the items in the queue.
@end defun

@defun mtqueue-max-length mtqueue
@{@t{data.queue}@}
Returns the maximum number of items the mtqueue can hold.
If the queue doesn't have a limit, @code{#f} is returned.
@end defun

@defun mtqueue-room mtqueue
@{@t{data.queue}@}
Returns the number of elements the mtqueue can accept at this moment
before it hits its maximum length.   For example, if the queue
already has the maximum number of elements, 0 is returned.
If the queue doesn't have the limit, @code{+inf.0} is returned.

Note that even if this returns a non-zero finite value, subsequent 
@code{enqueue!} may throw an error because of the queue being full.
It's because another thread may put an item to the queue
between this procedure call and @code{enqueue!}.  To avoid
this situation, use @code{enqueue/wait!} to insert item
to mtqueue with finite max-length.
@end defun

@defun mtqueue-num-waiting-readers mtqueue
@{@t{data.queue}@}
Returns the number of threads waiting on the mtqueue to read
at this moment. 
The return value is always a nonnegative exact integer.

Note that the value might change between this procedure's returning
the value and your checking it, if some other thread inserts
an element into the queue.  To use the value reliably, you need
another mutex to restrict putting items in the queue.

@example
(define q (make-mtqueue))

(thread-start! (make-thread (^[] (dequeue/wait! q))))

(mtqueue-num-waiting-readers q) @result{} 1

(enqueue! q 'a)

(mtqueue-num-waiting-readers q) @result{} 0
@end example
@end defun

@defun copy-queue queue
@{@t{data.queue}@}
Returns a copy of the queue.
@end defun

@defun enqueue! queue obj :optional more-objs @dots{}
@{@t{data.queue}@}
Add @var{obj} to the end of @var{queue}.  You may give more than
one object, and each of them are enqueued in order.

If @var{queue} is an mtqueue, all the objects are enqueued
atomically; no other objects from other threads can be inserted
between the objects given to a single @code{enqueue!} call.
Besides, if the value of its @code{max-length} slot
has a positive finite value, and adding @var{obj}s makes the number of
elements in @var{queue} exceeds @code{max-length},
an error is signaled and @var{queue} won't be modified.
(If @code{max-length} is zero, this procedure always fail.
Use @code{enqueue/wait!} below.)
@end defun

@defun queue-push! queue obj :optional more-objs @dots{}
@{@t{data.queue}@}
Add @var{obj} in front of @var{queue}.  You may give more than
one object, and each of them are pushed in order.

Like @code{enqueue!}, when @var{queue} is an mtqueue,
all objects are added atomically, and the value of
@code{max-length} slot is checked.  See @code{enqueue!} above
for the details.
@end defun

@defun enqueue-unique! queue eq-proc obj :optional more-objs @dots{}
@defunx queue-push-unique! queue eq-proc obj :optional more-objs @dots{}
@{@t{data.queue}@}
Like @code{enqueue!} and @code{queue-push!}, respectively, except that these
don't modify @var{queue} if it already contains @var{obj}
(elements are compared by two-argument procedure @var{eq-proc}).

When @var{queue} is an mtqueue, all objects are added atomically,
and the value of
@code{max-length} slot is checked.  See @code{enqueue!} above
for the details.
@end defun

@defun dequeue! queue :optional fallback
@defunx queue-pop! queue :optional fallback
@{@t{data.queue}@}
Take one object from the front of the queue @var{queue} and returns it.
Both function works the same, but @code{queue-pop!} may be used to
emphasize it works with @code{queue-push!}.

If @var{queue} is empty, @var{fallback} is returned if given,
otherwise an error is signaled.

If @var{queue} is an mtqueue and its @code{max-length} is zero,
the queue is always empty.  Use @code{dequeue/wait!} to use
such a queue as an synchronization device.
@end defun

@defun dequeue-all! queue
@{@t{data.queue}@}
Returns the whole content of the queue by a list, with emptying
@var{queue}.   If @var{queue} is already empty, returns an empty list.
See also @code{queue->list} below.
@end defun

@defun queue-front queue :optional fallback
@defunx queue-rear queue :optional fallback
@{@t{data.queue}@}
Peek the head or the tail of the queue and returns the object, respectively.
The queue itself is not modified.
If @var{queue} is empty, @var{fallback} is returned if it is given,
otherwise an error is signaled.
@end defun

@defun list->queue list :optional class :rest initargs
@{@t{data.queue}@}
Returns a new queue whose content is the elements in @var{list},
in the given order.

By default the created queue is a simple queue, but you
can create mtqueue or instances of other subclasses of @code{<queue>}
by giving the class to the optional @var{class} arguments.
The optional @var{initargs} arguments are passed to the constructor
of @var{class}.
@end defun

@defun queue->list queue
@{@t{data.queue}@}
Returns a list whose content is the items in the queue in order.
Unlike @code{dequeue-all!}, the content of @var{queue} remains intact.

In Gauche, @code{queue->list} copies the content of the queue to a
freshly allocated list, while @code{dequeue-all!} doesn't copy but
directly returns the queue's internal list.   There are some Scheme
systems that has @code{queue->list} but doesn't guarantee the content
is copied, so if you're planning to share the code among these
implementations, it's better not to rely on the fact that
@code{queue->list} copies the content.
@end defun

@defun queue-internal-list queue
@{@t{data.queue}@}
Like @code{queue->list}, returns a list whose content is the items
in the queue in order, but the returned list @emph{may} share the
internal storage of @var{queue}.  The returned list can be modified
by subsequent operations of @var{queue}, and any modification on the
list can make @var{queue} inconsistent.

Because of this danger, we don't allow @code{<mtqueue>} to be
passed to this procedure; it would signal an error if you do so.

If you just want to extract the accumulated result in @var{queue} without
copying, consider @code{dequeue-all!}, which is safe because it atomically
resets the queue.  Use this procedure only when you absolutely need
to access the contents of the queue without taking them out.
@end defun

@defun find-in-queue pred queue
@{@t{data.queue}@}
Returns the first item in @var{queue} that satisfies a
predicate @var{pred}.  The order of arguments follows
@code{find} (@pxref{Other list procedures}).
@end defun

@defun any-in-queue pred queue
@{@t{data.queue}@}
Like @code{any} in SRFI-1, apply @var{pred} on each item
in @var{queue} until it evaluates true, and returns that
true value (doesn't necessarily be @code{#t}).  If no
items in the queue satisfies @var{pred}, @code{#f} is returned.
@end defun

@defun every-in-queue pred queue
@{@t{data.queue}@}
Like @code{every} in SRFI-1, apply @var{pred} on each item
in @var{queue}.  If @var{pred} returns @code{#f}, stops
iteration and returns @code{#f} immediately.
Otherwise, returns the result of the application of
@var{pred} on the last item of the queue.  If the queue
is empty, @code{#t} is returned.
@end defun

@defun remove-from-queue! pred queue
@{@t{data.queue}@}
Removes all items in the queue that satisfies @var{pred}.
Returns @code{#t} if any item is removed.  Otherwise returns @code{#f}.
The order of arguments follows
@code{remove} in @code{scheme.list}
(@pxref{R7RS lists}).
@end defun

Note on portability:
Scheme48 has @code{delete-from-queue!}, which takes object to remove
rather than predicate, and also takes arguments in reversed order
(i.e. queue comes first).   Avoid conflicting with that I intentionally
left out @code{delete-from-queue!}; it's easy to write one in either
Scheme48 compatible way or consistent to SRFI-1 argument order.

@defun enqueue/wait! mtqueue obj :optional timeout timeout-val
@defunx queue-push/wait! mtqueue obj :optional timeout timeout-val
@defunx dequeue/wait! mtqueue :optional timeout timeout-val
@defunx queue-pop/wait! mtqueue :optional timeout timeout-val
@{@t{data.queue}@}
These synchronizing variants work on an mtqueue and
make the caller thread block when the mtqueue has reached
its maximum length (for @code{enqueue/wait!} and @code{queue-push/wait!}),
or the mtqueue is empty (for @code{dequeue/wait!} and
@code{queue-pop/wait!}).   The blocked caller thread is unblocked
either when the blocking condition is resolved, or the timeout
condition is met.

The optional @var{timeout} argument specifies the timeout condition.
If it is @code{#f}, those procedures wait indefinitely.
If it is a real number, they wait at least the given number of
seconds.  If it is a @code{<time>} object (@pxref{Time}),
they wait until the absolute point of time the argument specifies.

In case the call is blocked then timed out, the value of
@var{timeout-val} is returned, which defaults to @code{#f}.

When @code{enqueue/wait!} and @code{queue-push/wait!} succeeds
without hitting timeout, they return @code{#t}.
@end defun



@c ----------------------------------------------------------------------
@node Random data generators, Ring buffer, Queue, Library modules - Utilities
@section @code{data.random} - Random data generators
@c NODE ランダムデータの生成, @code{data.random} - ランダムデータの生成

@deftp {Module} data.random
@mdindex data.random
This module defines a set of generators and generator makers
that yield random data of specific type and distribution.
@end deftp

A naming convention: Procedures that takes parameters and returns
a generator is suffixed by @code{$} (e.g. @code{integer$}).
Procedures that are generators themselves are not (e.g. @code{fixnums}).
Procedures that are combinators, that is, the ones that take
one or more generators and returns a generator, generally ends
with a preposition (e.g. @code{list-of}).

@subheading Global state

All the generators in this module shares a global random state.
The random seed is initialized by a fixed value when the module
is loaded.
You can get and set the random seed by
the following procedure.

@defun random-data-seed
@defunx {(setter random-data-seed)} seed-value
@{@t{data.random}@}
Calling @code{random-data-seed} (without arguments)
returns the random seed value used to initialize the current random state.

It can be used with generic setter, to reinitialize the random state
with @var{seed-value}.

Random seed value must be an exact integer.  Its lower 32bits are used.

@example
; @r{reinitialize the random state with a new random seed.}
(set! (random-data-seed) 1)

(random-data-seed) @result{} 1
@end example

Note: This procedure doesn't have parameter interface (alter the global
value by giving the new value as an argument), since it doesn't work
like a parameter (@pxref{Parameters}).
You can get the random seed value, but you can't
get the current random state itself---if you restore the
random seed value again, the internal state is reset, instead
of restoring the state at the time you called @code{random-data-seed}.

If you want to use different random state temporarily, and ensure to
restore original state afterwards, use @code{with-random-data-seed} below.
@end defun

@defun with-random-data-seed seed thunk
@{@t{data.random}@}
Saves the current global random state, initializes the random state with
@var{seed}, then executes @var{thunk}.  If @var{thunk} returns or
the control exits out of @var{thunk}, the state at the time
@code{with-random-data-seed} was called is restored.
@end defun

Since the default random seed value is fixed, you can get deterministic
output when you call the random data generators below without altering
the random seed explicitly.

@subheading Generators of primitive data types

Those generators generate uniformly distributed data.

In the following examples, we use @code{generator->list} to show
some concrete data from the generators.  It is provided
in @code{gauche.generator} module.  @xref{Generators}, for more
utilities work on generators.

@defun integers$ size :optional (start 0)
@defunx integers-between$ lower-bound upper-bound
@{@t{data.random}@}
Create exact integer generators.  The first one, @code{integers$}, creates
a generator that generates integers from start (inclusive) below
start+size (exclusive) uniformly.  The second one, @code{integers-between$},
creates a generator that generates integers between
@var{lower-bound} and @var{upper-bound} (both inclusive) uniformly.

@example
;; A dice roller
(define dice (integers$ 6 1))

;; Roll the dice 10 times
(generator->list dice 10)
 @result{} (6 6 2 4 2 5 5 1 2 2)
@end example
@end defun

@defun fixnums
@defunx int8s
@defunx uint8s
@defunx int16s
@defunx uint16s
@defunx int32s
@defunx uint32s
@defunx int64s
@defunx uint64s
@{@t{data.random}@}
Uniform integer generators.  Generate integers in fixnum range, and
8/16/32/64bit signed and unsigned integers, respectively.

@example
(generator->list int8s 10)
 @result{} (20 -101 50 -99 -111 -28 -19 -61 39 110)
@end example
@end defun

@defun booleans
@{@t{data.random}@}
Generates boolean values (@code{#f} and @code{#t}) in equal probability.

@example
(generator->list booleans 10)
 @result{} (#f #f #t #f #f #t #f #f #f #f)
@end example
@end defun

@defun chars$ :optional char-set
@{@t{data.random}@}
Creates a generator that generates characters in @var{char-set} uniformly.
The default @var{char-set} is @code{#[A-Za-z0-9]}.

@example
(define alphanumeric-chars (chars$))

(generator->list alphanumeric-chars 10)
 @result{} (#\f #\m #\3 #\S #\z #\m #\x #\S #\l #\y)
@end example
@end defun

@defun reals$ :optional size start
@defunx reals-between$ lower-bound upper-bound
@{@t{data.random}@}
Create a generator that generates real numbers uniformly with given range.
The first procedure, @code{reals$}, returns reals between start
and start+size, inclusively.  The default of size is 1.0 and start is 0.0.
The second procedure, @code{reals-between$}, returns reals between
lower-bound and upper-bound, inclusively.

@example
(define uniform-100 (reals$ 100))

(generator->list uniform-100 10)
 @result{} (81.67965004942268 81.84927577572596 53.02443813660833)
@end example

Note that a generator from @code{reals$} can generate the upper-bound
value start+size, as opposed to @code{integers$}.  If you need to exclude
the bound value, just discard the bound value; @code{gfilter} may come
handy.

@example
(define generate-from-0-below-1
  (gfilter (^r (not (= r 1.0))) (reals$ 1.0 0.0)))
@end example
@end defun

@defun samples$ collection
@{@t{data.random}@}
Creates a generator that returns randomly chosen item in @var{collection}
at a time.

Do not confuse this with @code{samples-from} below, which is to combine
multiple generators for sampling.

@example
(define coin-toss (samples$ '(head tail)))

(generator->list coin-toss 5)
 @result{} (head tail tail head tail)
@end example
@end defun

@defun regular-string$ regexp
@{@t{data.random}@}
Creates an infinite
generator that generates random strings each of which matches the given
@var{regexp}.  The @var{regexp} shouldn't include conditional patterns
and lookahead/behind assertions.

Note: It is hard to define how the distribution of the generated strings
should look like.  For now, we build an NFA from regexp and put the
same probability when there are multiple choices, but that may not be
really useful for typical use cases (e.g. generate test data).
Please assume the current implementation strategy a provisional one.
@end defun

@subheading Nonuniform distributions

@defun reals-normal$ :optional mean deviation
@{@t{data.random}@}
Creates a generator that yields real numbers from normal distribution
with @var{mean} and @var{deviation}.  The default of @var{mean} is 0.0
and @var{deviation} is 1.0.
@end defun

@defun reals-exponential$ mean
@{@t{data.random}@}
Creates a generator that yields real numbers from exponential distribution
with @var{mean}.
@end defun

@defun integers-geometric$ p
@{@t{data.random}@}
Creates a generator that yields integers from geometric distribution
with success probability @var{p} (0 <= p <= 1).  The mean is @code{1/p} and
variance is @code{(1-p)/p^2}.
@end defun

@defun integers-poisson$ L
@{@t{data.random}@}
Creates a generator that yields integers from poisson distribution with
mean @var{L}, variance @var{L}.
@end defun

@subheading Aggregate data generators

@defun samples-from generators
@{@t{data.random}@}
Takes a finite sequence of generators
(sequence in the sense of @code{gauche.sequence}),
and returns a generator.  Every time the resulting generator is called,
it picks one of the input generators in equal probability, then
calls it to get a value.

@example
(define g (samples-from (list uint8s (chars$ #[a-z]))))

(generator->list g 10)
 @result{} (207 107 #\m #\f 199 #\o #\b 57 #\j #\e)
@end example

NB: To create a generator that samples from a fixed collection of items,
use @code{samples$} described above.
@end defun

@defun weighted-samples-from weight&gens
@{@t{data.random}@}
The argument is a list of pairs of a nonnegative real number and a generator.
The real number determines the weight, or the relative probability
that the generator is chosen.  The sum of weight doesn't need to
be 1.0.

The following example chooses the uint8 generator four times frequently
than the character generator.

@example
(define g (weighted-samples-from
           `((4.0 . ,uint8s)
             (1.0 . ,(chars$)))))

(generator->list g 10)
 @result{} (195 97 #\j #\W #\5 72 49 143 19 164)
@end example
@end defun

@defun pairs-of car-gen cdr-gen
@{@t{data.random}@}
Returns a generator that yields pairs,
whose car is generated from @var{car-gen}
and whose cdr is generated from @var{cdr-gen}.

@example
(define g (pairs-of int8s booleans))

(generator->list g 10)
 @result{} ((113 . #t) (101 . #f) (12 . #t) (68 . #f) (-55 . #f))
@end example
@end defun

@defun tuples-of gen @dots{}
@{@t{data.random}@}
Returns a generator that yields lists, 
whose i-th element is generated from the i-th argument.

@example
(define g (tuples-of int8s booleans (char$)))

(generator->list g 3)
 @result{} ((-43 #f #\8) (53 #f #\1) (-114 #f #\i))
@end example
@end defun

@defun permutations-of seq
@{@t{data.random}@}
Returns a generator that yields a random permutations of @var{seq}.

The type of @var{seq} should be a sequence with a builder
(@pxref{Sequence framework}).  The type of generated objects
will be the same as @var{seq}.

@example
(generator->list (permutations-of '(1 2 3)) 3)
 @result{} ((1 2 3) (2 3 1) (3 2 1))

(generator->list (permutations-of "abc") 3)
 @result{} ("cba" "cba" "cab")
@end example
@end defun

@defun combinations-of size seq
@{@t{data.random}@}
Returns a generator that yields a sequence of @var{size} elements
randomly picked from @var{seq}.

The type of @var{seq} should be a sequence with a builder
(@pxref{Sequence framework}).  The type of generated objects
will be the same as @var{seq}.

@example
(generator->list (combinations-of 2 '(a b c)) 5)
 @result{} ((a c) (a b) (a c) (b a) (a c))

(generator->list (combinations-of 2 '#(a b c)) 5)
 @result{} (#(a c) #(b c) #(c b) #(b a) #(b c))
@end example
@end defun

The following procedures takes optional @var{sizer} argument, which can
be either a nonnegative integer or a generator of nonnegative integers.
The value of the sizer determines the length of the result data.

Unlike most of Gauche procedures, @var{sizer} argument comes before
the last argument when it is not omitted.
We couldn't resist the temptation to
write something like @code{(lists-of 3 booleans)}.

If @var{sizer} is omitted, the default value is taken from
the parameter @code{default-sizer}.  The default of @code{default-sizer}
is @code{(integers-poisson$ 4)}.

@defun lists-of item-gen
@defunx lists-of sizer item-gen
@defunx vectors-of item-gen
@defunx vectors-of sizer item-gen
@defunx strings-of
@defunx strings-of item-gen
@defunx strings-of sizer item-gen
@{@t{data.random}@}
Creates a generator that generates lists, vectors or strings of values from @var{item-gen}, respectively.  The size of each datum is determined by
@var{sizer}.

You can also omit @var{item-gen} for @code{strings-of}.  In that case,
a generator created by @code{(chars$)} is used.

@example
(generator->list (lists-of 3 uint8s) 4)
 @result{} ((254 46 0) (77 158 46) (1 134 156) (74 5 110))

;; using the default sizer
(generator->list (lists-of uint8s) 4)
 @result{} ((93 249) (131 97) (98 206 144 247 241) (126 156 31))

;; using a generator for the sizer
(generator->list (strings-of (integers$ 8) (chars$)) 5)
 @result{} ("dTJYVhu" "F" "PXkC" "w" "")
@end example
@end defun

@defun sequences-of class item-gen
@defunx sequences-of class sizer item-gen
@{@t{data.random}@}
Creates a generator that yields sequences of class @var{class},
whose items are generated by @var{item-gen}.  The size of each
sequence is determined by @var{sizer}, or the value of @code{default-sizer}
if omitted; the sizer can be a nonnegative integer, or a generator
that yields nonnegative integers.

The class @var{class} must be a subclass of @code{<sequence>} and
implement the builder interface.

@example
(generator->list (sequences-of <u8vector> 4 uint8s) 3)
 @result{} (#u8(95 203 243 46) #u8(187 199 153 152) #u8(39 114 39 25))
@end example
@end defun


@deffn {Parameter} default-sizer
@{@t{data.random}@}
The sizer used by @code{lists-of}, @code{vectors-of} and @code{strings-of}
when @var{sizer} argument is omitted.

The value must be either an nonnegative integer, or a generator
of nonnegative integers.
@end deffn

@c ----------------------------------------------------------------------
@node Ring buffer, Skew binary random-access lists, Random data generators, Library modules - Utilities
@section @code{data.ring-buffer} - Ring buffer
@c NODE リングバッファ, @code{data.ring-buffer} - リングバッファ

@deftp {Module} data.ring-buffer
@mdindex data.ring-buffer
A ring buffer is an array with two fill pointers; in a typical usage,
a producer adds new data to one end while a consumer removes data
from the other end; if fill pointer reaches at the end of the array,
it wraps around to the beginning, hence the name.

The ring buffer of this module allows adding and removing elements
from both ends, hence functionally it is a double-ended queue,
or deque.  It also allows O(1) indexed access to the contents,
and customized handling for the case when the buffer gets full.

You can use an ordinary vector or a uniform vector as the backing
storage of a ring buffer.
@end deftp

@defun make-ring-buffer :optional initial-storage :key overflow-handler
@{@t{data.ring-buffer}@}
Creates a ring buffer.  By default, a fresh vector is allocated
for the backing storage.  You can pass a vector or a uvector to
@var{initial-storage} to be used instead.  The passed storage must
be mutable, and will
be modified by the ring buffer; the caller shouldn't modify it,
nor make assumption about its content.

The @var{overflow-handler} keyword argument specifies what to do when
a new element is about to be added to the full buffer.
It must be a procedure, or a symbol @code{error}
or @code{overwrite}.

If it is a procedure, it will be called with a ring buffer and
a backing storage (vector or uvector) when it is filled.  The procedure
must either (1) allocate and return a larger vector/uvector of the same
type of the passed backing storage, (2) return a symbol @code{error},
or (3) return a symbol @code{overwrite}.  If it returns a vector/uvector,
it will be used as the new backing storage.  The returned vector doesn't need
to be initialized; the ring buffer routine takes care of copying the
necessary data.
If it returns @code{error},
an error (``buffer is full'') is thrown.  If it returns @code{overwrite},
the new element overwrites the existing element (as if one element
from the other end is popped and discarded.)

Passing a symbol @code{error} or @code{overwrite} to @var{overflow-handler}
is a shorthand of passing a procedure that unconditionally returns
@code{error} or @code{overwrite}, respectively.

The default behavior on overflow is to double the size of backing
storage.  You can use @code{make-overflow-doubler} below to create
the customized overflow handler easily.
@end defun

@defun make-overflow-doubler :key max-increase max-capacity
@{@t{data.ring-buffer}@}
Returns a procedure suitable to be passed to the @var{overflow-handler}
keyword argument of @code{make-ring-buffer}.

The returned procedure takes a ring buffer and its backing storage,
and behaves as follows.

@itemize
@item
If the size of current backing storage is equal to or greater than
@var{max-capacity}, returns @code{error}.
@item
Otherwise, if the size of current backing storage is equal to or
greater than @var{max-increase}, allocates a vector/uvector of
the same type of the current backing storage, with the size
@code{(+ max-increase size-of-current-storage)}.
@item
Otherwise, allocates a vector/uvector of
the same type of the current backing storage with the size
@code{(* 2 size-of-current-storage)}.
@end itemize

The default value of @var{max-increase} and @var{max-capacity} is
@code{+inf.0}.
@end defun

@defun ring-buffer-empty? rb
@{@t{data.ring-buffer}@}
Returns @code{#t} if the ring buffer @var{rb} is empty,
@code{#f} if not.
@end defun

@defun ring-buffer-full? rb
@{@t{data.ring-buffer}@}
Returns @code{#t} if the ring buffer @var{rb} is full,
@code{#f} if not.
@end defun

@defun ring-buffer-num-entries rb
@{@t{data.ring-buffer}@}
Returns the number of current elements in the ring buffer @var{rb}.
@end defun

@defun ring-buffer-capacity rb
@{@t{data.ring-buffer}@}
Returns the size of the current backing storage of the ring buffer @var{rb}.
@end defun

@defun ring-buffer-front rb
@defunx ring-buffer-back rb
@{@t{data.ring-buffer}@}
Returns the element in the front or back of the ring buffer @var{rb},
respectively.
If the buffer is empty, an error is signaled.
@end defun

@defun ring-buffer-add-front! rb elt
@defunx ring-buffer-add-back! rb elt
@{@t{data.ring-buffer}@}
Add an element to the front or back of the ring buffer @var{rb},
respectively.  If @var{rb} is full, the behavior is determined by
the buffer's overflow handler, as described in @code{make-ring-buffer}.
@end defun

@defun ring-buffer-remove-front! rb
@defunx ring-buffer-remove-back! rb
@{@t{data.ring-buffer}@}
Remove an element from the front or back of the ring buffer @var{rb},
and returns the removed element, respectively.
If the buffer is empty, an error is signaled.
@end defun

@defun ring-buffer-ref rb index :optional fallback
@{@t{data.ring-buffer}@}
Returns @var{index}-th element in the ring buffer @var{rb}.
The elements are counted from the front; thus, if a new element
is added to the front, the indexes of existing elements will shift.

If the index out of bounds of the existing content,
@var{fallback} will be returned; if @var{fallback} is not
provided, an error is signaled.
@end defun

@defun ring-buffer-set! rb index value
@{@t{data.ring-buffer}@}
Sets @var{index}-th element of the ring buffer @var{rb} to @var{value}.
The elements are counted from the front; thus, if a new element
is added to the front, the indexes of existing elements will shift.

An error is signaled if the index is out of bounds.
@end defun


@c ----------------------------------------------------------------------
@node Skew binary random-access lists, Sparse data containers, Ring buffer, Library modules - Utilities
@section @code{data.skew-list} - Skew binary random-access lists
@c NODE Skew binary random-access lists, @code{data.sparse} - Skew binary random-access lists

@deftp {Module} data.skew-list
@mdindex data.skew-list
This module implements skew binary random-access list (we call it skew-list
for short).  It's an immutable
data structure that has properties of both list and vector; constant
time to take the first element (car) and append an element in front
of existing one (cons), O(log n) to take the rest of
the elements (cdr), and O(log n) for indexed access, wher n is
the number of elements.

A skew-list is always 'proper'; that is, it is either an empty
skew-list (@code{skew-list-null}), or an object appended in front
of a skew-list.
@end deftp

@deftp {Class} <skew-list>
@clindex skew-list
@{@t{data.skew-list}@}
The class for skew-lists.

It inherits @code{<sequence>} and follws the sequence protocol.
@end deftp

@defun skew-list? obj
@{@t{data.skew-list}@}
Returns @code{#t} iff @var{obj} is a skew-list.
@end defun

@defun skew-list-empty? sl
@{@t{data.skew-list}@}
The argument must be a skew list.  Returns @code{#t} iff @var{sl}
is an empty skew list.
@end defun

@defvar skew-list-null
@{@t{data.skew-list}@}
An empty skew list.
@end defvar

@defun skew-list-cons obj sl
@{@t{data.skew-list}@}
Returns a new skew-list which has @var{obj} prepended to
a skew-list @var{sl}.
@end defun

@defun skew-list-car sl
@{@t{data.skew-list}@}
Returns the first element of a skew-list @var{sl}.  An error is
raised when @var{sl} is empty.
@end defun

@defun skew-list-cdr sl
@{@t{data.skew-list}@}
Returns a new skew-list that containts elements in @var{sl} but
the firest one.  An error is
raised when @var{sl} is empty.
@end defun

@defun skew-list-ref sl k :optional fallback
@{@t{data.skew-list}@}
Returns the @var{k}-th element of a skew-list @var{sl}.  If @var{k}
points past the range of @var{sl}, @var{fallback} is returned if it
is given, or an error is signaled.

Sicne a skew-list is also a sequence, you can use generic @code{ref} as well
(@pxref{Sequence framework}.
@end defun

@defun skew-list-set sl k obj
@{@t{data.skew-list}@}
Returns a new skew-list which is the same as @var{sl} except the @var{k}-th
element is replaced with @var{obj}.  The argument @var{sl} remains intact.

It is an error if @var{k} points beyond the last element of @var{sl}.
@end defun

@defun skew-list-length sl
@{@t{data.skew-list}@}
Returns an integer length of a skew-list @var{sl}.

Sicne a skew-list is also a sequence, you can use generic @code{size-of} as well
(@pxref{Sequence framework}.
@end defun

@defun skew-list-length<=? sl n
@{@t{data.skew-list}@}
Returns @code{#t} iff the length of a skew-list @var{sl} is less than
or equal to @var{n}.  It is more efficient than calculating
the total length and compares with @var{n}.
@end defun

@defun list->skew-list lis
@{@t{data.skew-list}@}
Returns a new skew-list which contains elements in @var{lis}, with the
same order.  It is an error if @var{lis} is not a proper list.

Sicne a skew-list is also a sequence, you can use generic @code{coerce-to}
as well (@pxref{Sequence framework}.
@end defun

@defun list*->skew-list lis
@{@t{data.skew-list}@}
The argument @var{lis} may be an improper list (but can't be circular).
Returns two values: a new skew-list which contains elements 
in @var{lis} except the last cdr of it, and the last cdr of @var{lis}.
@end defun

@defun skew-list->list sl
@{@t{data.skew-list}@}
Returns a new list that contains all the elements in a skew-list @var{sl},
with the same order.

Sicne a skew-list is also a sequence, you can use generic @code{coerce-to}
as well (@pxref{Sequence framework}.
@end defun

@defun skew-list->generator sl
@{@t{data.skew-list}@}
Returns a new generator that traverses a skew-list @var{sl}.
@end defun

@defun skew-list->lseq sl
@{@t{data.skew-list}@}
Converts a skew-list @var{sl} to a lazy sequence.
@end defun

@defun skew-list-take sl k
@defunx skew-list-drop sl k
@{@t{data.skew-list}@}
Returns a new skew-list of the first @var{k} elements and the elements
except the first @var{k} elements, respectively.
@end defun

@defun skew-list-split-at sl k
@{@t{data.skew-list}@}
Returns two values, the result of @code{(skew-list-take sl k)}
and @code{(skew-list-drop sl k)}, but more efficiently.
@end defun

@defun skew-list-append sl sl2 @dots{}
@{@t{data.skew-list}@}
Returns a skew-list which is a concatenation of all the given skew-lists.
@end defun

@defun skew-list-fold sl kons knil
@{@t{data.skew-list}@}
Like @var{fold} on a list.

Sicne a skew-list is also a sequence, you can use generic @code{fold}
as well (@pxref{Sequence framework}.
@end defun

@defun skew-list-map sl proc
@{@t{data.skew-list}@}
Returns a skew list, each element of which is the result of
applying @var{proc} on the element of @var{sl}.

NB: If you want ot map over multiple skew-lists, you can use generic
@code{map} (@pxref{Sequence framework}).  The @code{skew-list-map} employs
optimization that's specific to one-argument case.
@end defun


@c ----------------------------------------------------------------------
@node Sparse data containers, Trie, Skew binary random-access lists, Library modules - Utilities
@section @code{data.sparse} - Sparse data containers
@c NODE 疎なデータコンテナ, @code{data.sparse} - 疎なデータコンテナ

@deftp {Module} data.sparse
@mdindex data.sparse
This module provides a @emph{sparse vector} and @emph{sparse matrix}, 
a space efficient data container indexed by nonnegative integer(s), and
a @emph{sparse table}, a hash table using a sparse vector
as a backing storage.
@end deftp

A sparse vector associates a nonnegative integer index
to a value.  It has @emph{vector} in its name since it is indexed
by an integer, but it isn't like a flat array on contiguous memory;
it's more like an associative array.  (Internally, the current
implementation uses compact trie structure.)
It is guaranteed that you can store a value with index at least
up to @code{2^32-1}; the actual maximum bits of indexes can
be queried by @code{sparse-vector-max-index-bits}.
(We have a plan to remove the maximum bits limitation in future).

Unlike ordinary vectors, you don't need to specify the size
of a sparse vector when you create one.  You can just set
a value to any index in the supported range.

@example
(define v (make-sparse-vector))

(sparse-vector-set! v 0 'a)
(sparse-vector-ref v 0) @result{} a

(sparse-vector-set! v 100000000 'b)
(sparse-vector-ref v 100000000) @result{} b

;; set! also work
(set! (sparse-vector-ref v 100) 'c)
(sparse-vector-ref v 100) @result{} c
@end example

If you try to access an element that hasn't been set,
an error is signaled by default.  You can set
a default value for each vector, or give a
fallback value to @code{sparse-vector-ref}, to suppress the error.

@example
(sparse-vector-ref v 1)        @result{} @r{error}
(sparse-vector-ref v 1 'noval) @result{} noval

(let1 w (make-sparse-vector #f :default 'x)
  (sparse-vector-ref w 1))     @result{} x
@end example

A sparse matrix is like a sparse vector, except it can be indexed
by a pair of integers.

A sparse table works just like a hash table, but it uses
a sparse vector to store the values using hashed number of the keys.

The main reason of these sparse data containers are for
memory efficiency.   If you want to store values in a vector
but knows you'll use only some entries sparsely, obviously it
is waste to allocate a large vector and to leave many entries unused.
But it is worse than that; Gauche's GC doesn't like a large
contiguous region of memory.  Using lots of large vectors adds
GC overhead quickly.  It becomes especially visible when you
store large number of entries (like >100,000) into hash tables,
since Gauche's builtin hash tables use a flat vector as a backing
storage.   You'll see the heap size grows quickly and
GC runs more frequently and longer.
On the other hand, sparse table works pretty stable with
large number of entries.

Sparse data containers does have overhead on access speed.
They are a bit slower than the ordinary hash tables,
and much slower than ordinary vectors.  We should note, however,
as the number of entries grow, access time on ordinary hash
tables grows quicker than sparse tables and eventually two become
comparable.

It depends on your application which you should use, and
if you're not sure, you need to benchmark.
As a rule of thumb, if you use more than several hashtables
each of which contains more than a few tens of thousands of
entries, sparse tables may work better.
If you see GC Warnings telling ``repeated allocation of large
blocks'', you should definitely consider sparse tables.

@menu
* Sparse vectors::
* Sparse matrixes::
* Sparse tables::
@end menu

@node Sparse vectors, Sparse matrixes, Sparse data containers, Sparse data containers
@subsection Sparse vectors
@c NODE 疎なベクタ

@deftp {Class} <sparse-vector-base>
@clindex sparse-vector-base
@{@t{data.sparse}@}
An abstract base class of sparse vectors.
Inherits @code{<dictionary>} and @code{<collection>}.
Note that sparse vectors are @emph{not} @code{<sequence>}; even
they can be indexable by integers, they don't have
means of @emph{ordered} access.

Sparse vector may be a general vector
that can contain any Scheme objects (like @code{<vector>}),
or a specialized vector that can contain only certain
types of numbers (like @code{<s8vector>} etc.).

All of these sparse vectors can be accessed by the same API.

Sparse vectors also implements the Collection API
(@pxref{Collection framework}) and the Dictionary API
(@pxref{Dictionary framework}).
@end deftp

@deftp {Class} <sparse-vector>
@deftpx {Class} <sparse-@@vector>
@clindex sparse-vector
@clindex sparse-s8vector
@clindex sparse-u8vector
@clindex sparse-s16vector
@clindex sparse-u16vector
@clindex sparse-s32vector
@clindex sparse-u32vector
@clindex sparse-s64vector
@clindex sparse-u64vector
@clindex sparse-f16vector
@clindex sparse-f32vector
@clindex sparse-f64vector
@{@t{data.sparse}@}
The actual sparse vector classes.  Inherits @code{<sparse-vector-base>}.
An instance of @code{<sparse-vector>} can contain any Scheme objects.

@code{@@} is either one of @code{s8}, @code{u8},
@code{s16}, @code{u16}, @code{s32}, @code{u32},
@code{s64}, @code{u64}, @code{f16}, @code{f32}, or @code{f64}.
The range of values an instance of those classes can hold
is the same as the corresponding @code{<@@vector>} class
in @code{gauche.uvector} (@pxref{Uniform vectors}).  That is,
@code{<sparse-u8vector>} can have exact integer values
between 0 and 255.
@end deftp

@defun make-sparse-vector :optional type :key default
@{@t{data.sparse}@}
Creates an empty sparse vector.  The @var{type} argument can be
@code{#f} (default), one of subclasses of @code{<sparse-vector-base>},
or a symbol of either one of @code{s8}, @code{u8},
@code{s16}, @code{u16}, @code{s32}, @code{u32},
@code{s64}, @code{u64}, @code{f16}, @code{f32}, or @code{f64}.

If @var{type} is omitted or @code{#f}, a @code{<sparse-vector>} is
created.  If it is a class, an instance of the class is created
(It is an error to pass a class that is not a subclass of
@code{<sparse-vector-base>}.)
If it is a symbol, an instance of corresponding @code{<sparse-@@vector>}
is created.

You can specify the default value of the vector by @var{default}
keyword argument.   If given, the vector behaves as if it is filled
with the default value (but the vector iterator only picks
the values explicitly set).

Note that you have to give the optional argument as well
to specify the keyword argument.

@example
(define v (make-sparse-vector 'u8 :default 128))

(sparse-vector-ref v 0) @result{} 128
@end example
@end defun

@defun sparse-vector-max-index-bits
@{@t{data.sparse}@}
Returns maximum number of bits of allowed integer.  If this
returns 32, the index up to @code{(expt 2 32)} is supported.
It is guaranteed that this is at least 32.
@end defun

In the following entries, the argument @var{sv} denotes
an instance of sparse vector; an error is signaled if other
object is passed.

@defun sparse-vector-copy sv
@{@t{data.sparse}@}
Returns a copy of a sparse vector @var{sv}.
@end defun

@defun sparse-vector-ref sv k :optional fallback
@{@t{data.sparse}@}
Returns @var{k}-th element of a sparse vector @var{sv}, where
@var{k} must an exact integer.

If the sparse vector doesn't have a value for @var{k}, it
behaves as follows:

@itemize @bullet
@item
If @var{fallback} is given, it is returned.
@item
Otherwise, if the vector has the default value, it is returned.
@item
Otherwise, an error is signaled.
@end itemize
@end defun

@defun sparse-vector-set! sv k value
@{@t{data.sparse}@}
Sets @var{value} for @var{k}-th element of a sparse vector @var{sv}.
@var{K} must be a nonnegative exact integer, and below the maximum
allowed index.

If @var{sv} is a numeric sparse vector, @var{value} must also be
within the allowed range, or an error is signaled.
@end defun

@defun sparse-vector-num-entries sv
@{@t{data.sparse}@}
Returns the number of entries in @var{sv}.
@end defun

@defun sparse-vector-exists? sv k
@{@t{data.sparse}@}
Returns @code{#t} if @var{sv} has an entry for index @var{k},
@code{#f} otherwise.
@end defun

@defun sparse-vector-delete! sv k
@{@t{data.sparse}@}
Deletes the @var{k}-th entry of @var{sv}.  If @var{sv} had the entry ,
returns @code{#t}.  If @var{sv} didn't have the entry, returns @code{#f}.
@end defun

@defun sparse-vector-clear! sv
@{@t{data.sparse}@}
Empties a sparse vector.
@end defun

@defun sparse-vector-inc! sv k delta :optional (fallback 0)
@{@t{data.sparse}@}
This is a shortcut of the following.  It is especially efficient
for numeric sparse vectors.

@example
(sparse-vector-set! sv k (+ (sparse-vector-ref sv k fallback) delta))
@end example

If the result of addition exceeds the allowed value range of @var{sv},
an error is signaled.  In future we'll allow an option to clamp
the result value within the range.
@end defun

@defun sparse-vector-update! sv k proc :optional fallback
@defunx sparse-vector-push! sv k val
@defunx sparse-vector-pop! sv k :optional fallback
@{@t{data.sparse}@}
Convenience routines to fetch-and-update an entry of
a sparse vector.  Works just like @code{hash-table-update!},
@code{hash-table-push!} and @code{hash-table-pop!};
(@pxref{Hashtables}).
@end defun

The following procedures traverses a sparse vector.
Note that elements are not visited in the order of index;
it's just like hash table traversers.

At this moment, if you want to walk a sparse vector with
increasing/decreasing index order, you have to get a list
of keys by @code{sparse-vector-keys}, sort it, then use
it to retrieve values.
We may add an option in future to @code{make-sparse-vector} so that
those walk operation will be more convenient.

@defun sparse-vector-fold sv proc seed
@{@t{data.sparse}@}
For each entry in @var{sv}, calls @var{proc} as
@code{(proc @var{k_n} @var{v_n} @var{seed_n})}, where
@var{k_n} is an index and @var{v_n} is a value for it,
and @var{seed_n} is the returned value of the previous
call to @var{proc} if @var{n} @code{>=} 1, and @var{seed} if @var{n} = 0.
Returns the value of the last call of @var{proc}.
@end defun

@defun sparse-vector-for-each sv proc
@defunx sparse-vector-map sv proc
@{@t{data.sparse}@}
Calls @code{proc} with index and value, e.g. @code{(proc k value)},
for each element of @var{sv}.

The results of @var{proc} are discarded by @code{sparse-vector-for-each},
and gathered to a list and returned by @code{sparse-vector-map}.
@end defun

@defun sparse-vector-keys sv
@defunx sparse-vector-values sv
@{@t{data.sparse}@}
Returns a list of all keys and all values in @var{sv}, respectively.
@end defun

@node Sparse matrixes, Sparse tables, Sparse vectors, Sparse data containers
@subsection Sparse matrixes
@c NODE 疎行列

A sparse matrix is like a sparse vector, except it can be indexed
by two nonnegative integers.

Note: This implementation of sparse matrixes aims at a reasonable
space efficiency for sparse matrixes without knowing its structure
beforehand (imagine, for example, a 2D map with some scattered landmarks).
If what you want is a sparse matrix implementation for efficient numeric
calculations, with certain particular structures,
probably the access speed of this module isn't suitable.

Currently, each index can have half of bits of
@code{sparse-vector-max-index-bits}.  We'll remove
this limitation in future.


@deftp {Class} <sparse-matrix-base>
@clindex sparse-matrix-base
@{@t{data.sparse}@}
An abstract base class of sparse matrixes.  Inherits @code{<collection>}.

Like sparse vectors, a sparse matrix can be of type that
can store any Scheme objects, or that can store only
certain types of numbers.

All of these sparse matrix subtypes can be accessed by the same API.
@end deftp

@deftp {Class} <sparse-matrix>
@deftpx {Class} <sparse-@@matrix>
@clindex sparse-matrix
@clindex sparse-s8matrix
@clindex sparse-u8matrix
@clindex sparse-s16matrix
@clindex sparse-u16matrix
@clindex sparse-s32matrix
@clindex sparse-u32matrix
@clindex sparse-s64matrix
@clindex sparse-u64matrix
@clindex sparse-f16matrix
@clindex sparse-f32matrix
@clindex sparse-f64matrix
@{@t{data.sparse}@}
The actual sparse matrix classes.  Inherits @code{<sparse-matrix-base>}.
An instance of @code{<sparse-matrix>} can contain any Scheme objects.

@code{@@} is either one of @code{s8}, @code{u8},
@code{s16}, @code{u16}, @code{s32}, @code{u32},
@code{s64}, @code{u64}, @code{f16}, @code{f32}, or @code{f64}.
The range of values an instance of those classes can hold
is the same as the corresponding @code{<@@vector>} class
in @code{gauche.uvector} (@pxref{Uniform vectors}).  That is,
@code{<sparse-u8matrix>} can have exact integer values
between 0 and 255.
@end deftp

@defun make-sparse-matrix :optional type :key default
@{@t{data.sparse}@}
Creates an empty sparse matrix.  The @var{type} argument can be
@code{#f} (default), one of subclasses of @code{<sparse-matrix-base>},
or a symbol of either one of @code{s8}, @code{u8},
@code{s16}, @code{u16}, @code{s32}, @code{u32},
@code{s64}, @code{u64}, @code{f16}, @code{f32}, or @code{f64}.

If @var{type} is omitted or @code{#f}, a @code{<sparse-matrix>} is
created.  If it is a class, an instance of the class is created
(It is an error to pass a class that is not a subclass of
@code{<sparse-matrix-base>}.)
If it is a symbol, an instance of corresponding @code{<sparse-@@matrix>}
is created.

You can specify the default value of the matrix by @var{default}
keyword argument.   If given, the vector behaves as if it is filled
with the default value (but the matrix iterator only picks
the values explicitly set).

Note that you have to give the optional argument as well
to specify the keyword argument.
@end defun

@defun sparse-matrix-num-entries mat
@{@t{data.sparse}@}
Returns the number of entries explicitly set in a sparse matrix @var{mat}.
@end defun

@defun sparse-matrix-ref mat x y :optional fallback
@{@t{data.sparse}@}
Returns an element indexed by (@var{x}, @var{y}) in a sparse matrix @var{mat}.
If the indexed element isn't set, @var{fallback} is returned if provided;
otherwise, if the matrix has the default value, it is returned; otherwise,
an error is raised.
@end defun

@defun sparse-matrix-set! mat x y value
@{@t{data.sparse}@}
Set @var{value} to the sparse matrix @var{mat} at the location
(@var{x}, @var{y}).
@end defun

@defun sparse-matrix-exists? mat x y
@{@t{data.sparse}@}
Returns @code{#t} iff the sparse matrix @var{mat} has a value at
(@var{x}, @var{y}).
@end defun

@defun sparse-matrix-clear! mat
@{@t{data.sparse}@}
Empties the sparse matrix @var{mat}.
@end defun

@defun sparse-matrix-delete! mat x y
@{@t{data.sparse}@}
Remove the value at (@var{x}, @var{y}) from the sparse matrix @var{mat}.
@end defun

@defun sparse-matrix-copy mat
@{@t{data.sparse}@}
Returns a fresh copy of @var{mat}.
@end defun

@defun sparse-matrix-update! mat x y proc :optional fallback
@{@t{data.sparse}@}
Call @var{proc} with the value at (@var{x}, @var{y}) of the sparse matrix,
and sets the result of @var{proc} as the new value of the location.

The optional @var{fallback} argument works just like @code{sparse-matrix-ref};
if provided, it is passed to @var{proc} in case the
matrix doesn't have a value at (@var{x}, @var{y}).
If @var{fallback} isn't provided and the matrix doesn't have a value
at the location, the default value of the matrix is used if it has one.
Otherwise, an error is signalled.
@end defun

@defun sparse-matrix-inc! mat x y delta :optional fallback
@{@t{data.sparse}@}
@example
(sparse-matrix-update! mat x y (cut + <> delta) fallback)
@end example
@end defun

@defun sparse-matrix-push! mat x y val
@{@t{data.sparse}@}
@example
(sparse-matrix-update! mat x y (cut cons val <>) '())
@end example
@end defun

@defun sparse-matrix-pop! mat x y
@{@t{data.sparse}@}
@example
(rlet1 r #f
  (sparse-matrix-update! mat x y (^p (set! r (car p)) (cdr p))))
@end example
@end defun

@defun sparse-matrix-fold mat proc seed
@{@t{data.sparse}@}
Loop over values in the sparse matrix @var{mat}.  The procedure
@var{proc} is called with four arguments, @var{x}, @var{y}, @var{val}
and @var{seed}, for each index (@var{x}, @var{y}) which has the value
@var{val}.  The initial value of @var{seed} is the one given to
@code{sparse-matrix-fold}, and the result of @var{proc} is passed
as the next seed value.  The last result of @var{proc} is returned
from @code{sparse-matrix-fold}.

The procedure @var{proc} is only called on the entries that's actually
has a value, and the order of which the procedure is called is undefined.
@end defun

@defun sparse-matrix-map mat proc
@{@t{data.sparse}@}
@example
(sparse-matrix-fold sv (^[x y v s] (cons (proc x y v) s)) '()))
@end example
@end defun

@defun sparse-matrix-for-each mat proc
@{@t{data.sparse}@}
@example
(sparse-matrix-fold sv (^[x y v _] (proc x y v)) #f))
@end example
@end defun

@defun sparse-matrix-keys mat
@{@t{data.sparse}@}
@example
(sparse-matrix-fold sv (^[x y _ s] (cons (list x y) s)) '())
@end example
@end defun

@defun sparse-matrix-values mat
@{@t{data.sparse}@}
@example
(sparse-matrix-fold sv (^[x y v s] (cons v s)) '())
@end example
@end defun

@node Sparse tables,  , Sparse matrixes, Sparse data containers
@subsection Sparse tables
@c NODE 疎なテーブル

@deftp {Class} <sparse-table>
@clindex sparse-table
@{@t{data.sparse}@}
A class for sparse table.  Inherits @code{<dictionary>} and
@code{<collection>}.

Operationally sparse tables are the same as hash tables, but
the former consumes less memory in trade of slight slower access.
(Roughly x1.5 to x2 access time when the table is small.
As the table gets larger the difference becomes smaller.)
@end deftp

@defun make-sparse-table comparator
@{@t{data.sparse}@}
Creates and returns an empty sparse table.
The @var{comparator} argument specifies how to compare and hash keys;
it must be either a comparator (@pxref{Basic comparators}),
or one of the symbols @code{eq?}, @code{eqv?}, @code{equal?} and
@code{string=?}, like hash tables (@pxref{Hashtables}).   If it is a symbol,
@code{eq-comparator}, @code{eqv-comparator}, @code{equal-comparator} or
@code{string-comparator} are used, respectively.
@end defun

@defun sparse-table-comparator st
@{@t{data.sparse}@}
Returns the comparator used in the sparse table @var{st}.
@end defun

@defun sparse-table-copy st
@{@t{data.sparse}@}
Returns a copy of a sparse table @var{st}.
@end defun

@defun sparse-table-num-entries st
@{@t{data.sparse}@}
Returns the number of entries in a sparse table @var{st}.
@end defun

@defun sparse-table-ref st key :optional fallback
@{@t{data.sparse}@}
Retrieves a value associated to the @var{key} in @var{st}.
If no entry with @var{key} exists, @var{fallback} is returned
when it is provided, or an error is signaled otherwise.
@end defun

@defun sparse-table-set! st key value
@{@t{data.sparse}@}
Sets @var{value} with @var{key} in @var{st}.
@end defun

@defun sparse-table-exists? st key
@{@t{data.sparse}@}
Returns @code{#t} if an entry with @var{key} exists in @var{st},
@code{#f} otherwise.
@end defun

@defun sparse-table-delete! st key
@{@t{data.sparse}@}
Deletes an entry with @var{key} in @var{st} if it exists.
Returns @code{#t} if an entry is actually deleted, or @code{#f}
if there hasn't been an entry with @var{key}.
@end defun

@defun sparse-table-clear! st
@{@t{data.sparse}@}
Empties @var{st}.
@end defun

@defun sparse-table-update! st key proc :optional fallback
@defunx sparse-table-push! st key val
@defunx sparse-table-pop! st key :optional fallback
@{@t{data.sparse}@}
@end defun

@defun sparse-table-fold st proc seed
@defunx sparse-table-for-each st proc
@defunx sparse-table-map st proc
@{@t{data.sparse}@}
@end defun

@defun sparse-table-keys st
@defunx sparse-table-values st
@{@t{data.sparse}@}
@end defun

@c ----------------------------------------------------------------------
@node Trie, Database independent access layer, Sparse data containers, Library modules - Utilities
@section @code{data.trie} - Trie
@c NODE Trie, @code{data.trie} - Trie

@deftp {Module} data.trie
@mdindex data.trie
This module provides @emph{Trie}, a dictionary-like data
structure that maps keys to values, where a key is an arbitrary sequence.
Internally it stores the data as a tree where each node corresponds
to each element in the key sequence.
Key lookup is O(n) where n is the length of the key, and not affected
much by the number of total entries.
Also it is easy to find a set of values whose keys share a common prefix.

The following example may give you the idea.

@example
(define t (make-trie))   ;; create a trie

(trie-put! t "pho" 3)    ;; populate the trie
(trie-put! t "phone" 5)
(trie-put! t "phrase" 6)

(trie-get t "phone")  @result{} 5  ;; lookup

(trie-common-prefix t "pho")       ;; common prefix search
  @result{} (("phone" . 5) ("pho" . 3))
(trie-common-prefix-keys t "ph")
  @result{} ("phone" "pho" "phrase")
@end example

Tries are frequently used with string keys, but you are not
limited to do so; any sequence (@pxref{Sequence framework}) can be
a key.  If the types of keys differ, they are treated as different
keys:

@example
(trie-put! t '(#\p #\h #\o) 8)  ;; different key from "pho"
@end example

Trie inherits @code{<collection>} and implements collection framework
including the builder. So you can apply generic collection
operations on a trie (@pxref{Collection framework}).
When iterated, each element of a trie appears as a pair of a key
and a value.
@end deftp

@deftp {Class} <trie>
@clindex trie
@{@t{data.trie}@}
A class for Trie.  No slots are intended for public.
Use the following procedures to operate on tries.

This class also implements the dictionary interface
(@pxref{Generic functions for dictionaries}).
@end deftp

@defun make-trie :optional tab-make tab-get tab-put! tab-fold tab-empty?
@{@t{data.trie}@}
Creates and returns an empty trie.  The optional arguments
are procedures to customize how the nodes of the internal
tree are managed.

Each node can have a table to store its child nodes, indexed
by an element of the key sequence (e.g. if the trie uses strings
as keys, a node's table is indexed by characters).

@table @code
@item tab-make
A procedure with no arguments.  When called, creates and
returns an empty table for a node.
@item tab-get @var{tab} @var{elt}
Returns a child node indexed by @var{elt}, or returns @code{#f}
if the table doesn't have a child for @var{elt}.
@item tab-put! @var{tab} @var{elt} @var{child-node}
If @var{child-node} isn't @code{#f},
stores a @var{child-node} with index @var{elt}.
If @var{child-node} is @code{#f},
removes the entry with index @var{elt}.
In both cases, this procedure should return the updated table.
@item tab-fold @var{tab} @var{proc} @var{seed}
Calls @var{proc} for every index and node in @var{tab}, while
passing a seed value, whose initial value is @var{seed}.
That is, @var{proc} has a type of @code{(index, node, seed) -> seed}.
Should return the last result of @var{proc}.
@item tab-empty? @var{tab}
Returns @code{#t} if @var{tab} is empty, @code{#f} otherwise.
You can omit or pass @code{#f} to this procedure; then we use
@code{tab-fold} to check if @var{tab} is empty, which can be expensive.
@end table

The default assumes @code{eqv?}-hashtables, i.e. the
following procedures are used.

@example
tab-make: (lambda () (make-hash-table 'eqv?))

tab-get:  (lambda (tab k) (hash-table-get tab k #f))

tab-put!: (lambda (tab k v)
            (if v
              (hash-table-put! tab k v)
              (hash-table-delete! tab k))
            tab)

tab-fold: hash-table-fold

tab-empty?: (lambda (tab) (zero? (hash-table-num-entries tab)))
@end example

The following example creates a trie using
assoc list to manage children, while comparing
string keys with case-insensitive way:

@example
(make-trie list
           (cut assoc-ref <> <> #f char-ci=?)
           (lambda (t k v)
             (if v
               (assoc-set! t k v char-ci=?)
               (alist-delete! k t char-ci=?)))
           (lambda (t f s) (fold f s t))
           null?)
@end example

It is important that @code{tab-put!} must return an updated
table---by that, you can replace the table structure on the fly.
For example, you may design a table which uses assoc list when
the number of children are small, and then switches to a vector
(indexed by character code) once the number of children grows over
a certain threshold.
@end defun

@defun trie params kv @dots{}
@{@t{data.trie}@}
Construct a trie with the initial contents
@var{kv} @dots{}, where each @var{kv} is a pair of a key and a value.
@var{Params} are a list of arguments
which will be given to @code{make-trie} to create the trie.
The following example creates a trie with two entries
and the default table procedures.

@example
(trie '() '("foo" . a) '("bar" . b))
@end example
@end defun

@defun trie-with-keys params key @dots{}
@{@t{data.trie}@}
A convenient version of @code{trie} when you only concern
the keys.  Each value is the same as its key.
The following example creates a trie with two entries
and the default table procedures.

@example
(trie-with-keys '() "foo" "bar")
@end example
@end defun

@defun trie? obj
@{@t{data.trie}@}
Returns @code{#t} if @var{obj} is a trie, or @code{#f} otherwise.
@end defun

@defun trie-num-entries trie
@{@t{data.trie}@}
Returns the number of entries in @var{trie}.
@end defun

@defun trie-exists? trie key
@{@t{data.trie}@}
Returns @code{#t} if @var{trie} contains an entry with @var{key},
or returns @code{#f} otherwise.

@example
(let1 t (trie '() '("foo" . ok))
  (list (trie-exists? t "foo")
        (trie-exists? t "fo")
        (trie-exists? t "bar")))
  @result{} '(#t #f #f)
@end example
@end defun

@defun trie-partial-key? trie seq
@{@t{data.trie}@}
Returns @code{#t} if there's at least one key in @var{trie} that is
not equal to @var{seq} but @var{seq} matches its prefix.   Note that
@var{seq} may or may not a key of @var{trie}; see the example below.

@example
(define t (trie '() '("foo" . ok) '("fo" . ok)))

(trie-partial-key? t "f")    @result{} #t
(trie-partial-key? t "fo")   @result{} #t
(trie-partial-key? t "foo")  @result{} #f
(trie-partial-key? t "bar")  @result{} #f
@end example
@end defun


@defun trie-get trie key :optional fallback
@{@t{data.trie}@}
Returns the value associated with @var{key} in @var{trie}, if
such an entry exists.  When there's no entry for @var{key},
if @var{fallback} is given, it is returned; otherwise,
an error is signaled.
@end defun

@defun trie-put! trie key value
@{@t{data.trie}@}
Puts @var{value} associated to @var{key} into @var{trie}.
@end defun

@defun trie-update! trie key proc :optional fallback
@{@t{data.trie}@}
Works like the following code, except that the
lookup of entry in @var{trie} is done only once.

@example
(let ((val (trie-get trie key fallback)))
  (trie-put! trie key (proc val)))
@end example
@end defun

@defun trie-delete! trie key
@{@t{data.trie}@}
Removes an entry associated with @var{key} from @var{trie}.
If there's no such entry, this procedure does nothing.
@end defun

@defun trie->list trie
@{@t{data.trie}@}
Makes each entry in @var{trie} to a pair @code{(@var{key} . @var{value})}
and returns a list of pairs of all entries.  The order of entries
are undefined.
@end defun

@defun trie-keys trie
@defunx trie-values trie
@{@t{data.trie}@}
Returns a list of all keys and values in @var{trie}, respectively.
The order of keys/values are undefined.
@end defun

@defun trie->hash-table trie ht-type
@{@t{data.trie}@}
Creates a hash table with type @var{ht-type} (see @ref{Hashtables},
about hash table types), and populates it with every key and value
pair in @var{trie}.
@end defun

@defun trie-longest-match trie seq :optional fallback
@{@t{data.trie}@}
Returns a pair of the key and its value, where the key is the
longest prefix of @var{seq}.   If no such key is found, @var{fallback}
is returned if it is provided, or an error is thrown.

Do not confuse this with @code{trie-common-prefix-*} procedures below;
In this procedure, the key is the prefix of the given argument.
In @code{trie-common-prefix-*} procedures, the given argument is
the prefix of the keys.

@example
(let1 t (make-trie)
  (trie-put! t "a"  'a)
  (trie-put! t "ab" 'ab)

  (trie-longest-match t "abc")  @result{} ("ab" . ab)
  (trie-longest-match t "acd")  @result{} ("a"  . a)
  (trie-longest-match t "ab")   @result{} ("ab" . ab)
  (trie-longest-match t "zy")   @result{} error
  )
@end example
@end defun


@defun trie-common-prefix trie prefix
@defunx trie-common-prefix-keys trie prefix
@defunx trie-common-prefix-values trie prefix
@{@t{data.trie}@}
Gathers all entries whose keys begin with @var{prefix};
@code{trie-common-prefix} returns those entries in a list of
pairs @code{(key . value)}; @code{trie-common-prefix-keys} returns
a list of keys; and @code{trie-common-prefix-values} returns a list
of values.   The order of entries in a returned list is undefined.
If @var{trie} contains no entry whose key has @var{prefix}, an
empty list is returned.

Note that prefix matching doesn't consider the type of sequence;
if @var{trie} has entries for @code{"foo"} and @code{(#\f #\o #\o)},
@code{(trie-common-prefix trie "foo")} will return both entries.
@end defun

@defun trie-common-prefix-fold trie prefix proc seed
@{@t{data.trie}@}
For each entry whose key begins with @var{prefix},
calls @var{proc} with three arguments, the entry's key,
its value, and the current seed value.  @var{Seed} is
used for the first seed value, and the value @var{proc}
returns is used for the seed value of the next call of @var{proc}.
The last returned value from @var{proc} is returned from
@code{trie-common-prefix-fold}.
The order of entries on which @var{proc} is called is undefined.
If @var{trie} contains no entry whose key has @var{prefix},
@var{proc} is never called and @var{seed} is returned.
@end defun

@defun trie-common-prefix-map trie prefix proc
@defunx trie-common-prefix-for-each trie prefix proc
@{@t{data.trie}@}
These are to @var{trie-common-prefix-fold} as @code{map} and @code{for-each}
are to @code{fold}; @code{trie-common-prefix-map} calls
@var{proc} with key and value for matching entries and
gathers its result to a list; @code{trie-common-prefix-for-each}
also applies @var{proc}, but discards its results.
@end defun

@defun trie-fold trie proc seed
@defunx trie-map trie proc
@defunx trie-for-each trie proc
@{@t{data.trie}@}
These procedures are like their common-prefix versions, but
traverse entire @var{trie} instead.
@end defun




@c ----------------------------------------------------------------------

@node Database independent access layer, Generic DBM interface, Trie, Library modules - Utilities
@section @code{dbi} - Database independent access layer
@c NODE データベース非依存アクセス層, @code{dbi} - データベース非依存アクセス層

@deftp {Module} dbi
@mdindex dbi
This module provides the unified interface to access various
relational database systems (RDBMS).  The operations specific
to individual database systems are packaged
in database driver (DBD) modules, which is usually loaded
implicitly by DBI layer.

The module is strongly influenced by Perl's DBI/DBD architecture.
If you have used Perl DBI, it would be easy to use this module.
@end deftp

It's better to look at the example.  This is a simple outline
of accessing a database by @code{dbi} module:

@example
(use dbi)
(use gauche.collection) ; to make 'map' work on the query result

(guard (e ((<dbi-error> e)
           ;; handle error
           ))
  (let* ((conn   (dbi-connect "dbi:mysql:test;host=dbhost"))
         (query  (dbi-prepare conn
                   "SELECT id, name FROM users WHERE department = ?"))
         (result (dbi-execute query "R&D"))
         (getter (relation-accessor result)))
    (map (lambda (row)
           (list (getter row "id")
                 (getter row "name")))
         result)))
@end example

There's nothing specific to the underlying database system
except the argument @code{"dbi:mysql:test;host=dbhost"}
passed to @code{dbi-connect}, from which @code{dbi} module
figures out that it is an access to @code{mysql} database,
loads @code{dbd.mysql} module, and let it handle the mysql-specific
stuff.  If you want to use whatever database system, you can just
pass @code{"dbi:@var{whatever}:@var{parameter}"} to @code{dbi-connect}
instead, and everything stays the same as far as you have
@code{dbd.whatever} installed in your system.

A query to the database can be created by @code{dbi-prepare}.
You can issue the query by @code{dbi-execute}.  This two-phase
approach allows you to create a prepared query, which is a kind of
parameterized SQL statement.  In the above example the query
takes one parameter, denoted as @code{'?'} in the SQL.
The actual value is given in @code{dbi-execute}.  When you
issue similar queries a lot, creating a prepared query and
execute it with different parameters may give you performance gain.
Also the parameter is automatically quoted.

When the query is a @code{SELECT} statement,
its result is returned as a collection that implements
the relation protocol.  See @ref{Collection framework}
and @ref{Relation framework} for the details.

The outermost @code{guard} is to catch errors.  The @code{dbi} related
errors are supposed to inherit @code{<dbi-error>} condition.
There are a few specific errors defined in @code{dbi} module.
A specific @code{dbd} layer may define more specific errors.

In the next section we describe user-level API, that is,
the procedures you need to concern when you're using @code{dbi}.
The following section is for the driver API, which you need to use
to write a specific @code{dbd} driver to make it work with @code{dbi}
framework.

@menu
* DBI user API::
* Writing drivers for DBI::
@end menu

@node DBI user API, Writing drivers for DBI, Database independent access layer, Database independent access layer
@subsection DBI user API
@c NODE DBIのユーザAPI

@subsubheading DBI Conditions

There are several predefined conditions @code{dbi} API may throw.
See @ref{Exceptions} for the details of conditions.

@deftp {Condition Type} <dbi-error>
@{@t{dbi}@}
The base class of @code{dbi}-related conditions.  Inherits @code{<error>}.
@end deftp

@deftp {Condition Type} <dbi-nonexistent-driver-error>
@{@t{dbi}@}
This condition is thrown by @code{dbi-connect} when it cannot
find the specified driver.  Inherits @code{<dbi-error>}.

@defivar <dbi-nonexistent-driver-error> driver-name
Holds the requested driver name as a string.
@end defivar
@end deftp

@deftp {Condition Type} <dbi-unsupported-error>
@{@t{dbi}@}
This condition is thrown when the called method isn't supported
by the underlying driver.  Inherits @code{<dbi-error>}.
@end deftp

@deftp {Condition Type} <dbi-parameter-error>
@{@t{dbi}@}
This condition is thrown when the number of parameters given to
the prepared query doesn't match the ones in the prepared statement.
@end deftp

Besides these errors, if a driver relies on @code{dbi} to
parse the prepared SQL statement, @code{<sql-parse-error>} may
be thrown if an invalid SQL statement is passed to @code{dbi-prepare}.
(@pxref{SQL parsing and construction}).

@subsubheading Connecting to the database

@defun dbi-connect dsn :key username password
@{@t{dbi}@}
Connect to a database using a data source specified by @var{dsn}
(data source name).  @var{Dsn} is a string with the following syntax:
@example
dbi:@var{driver}:@var{options}
@end example

@var{Driver} part names a specific driver.  You need to have the
corresponding driver module, @code{dbd.@var{driver}}, installed in
your system.  For example, if @var{dsn} begins with @code{"dbi:mysql:"},
@code{dbi-connect} tries to load @code{dbd.mysql}.

Interpretation of the @var{options} part is up to the driver.
Usually it is in the form of @code{key1=value1;key2=value2;...},
but some driver may interpret it differently.  For example,
@code{mysql} driver allows you to specify a database name
at the beginning of @var{options}.   You have to check out
the document of each driver for the exact specification of
@var{options}.

The keyword arguments gives extra information required for
connection.  The @var{username} and @var{password} are commonly
supported arguments.  The driver may recognize more keyword arguments.

If a connection to the database is successfully established,
a connection object (an instance of a subclass of @code{<dbi-connection>})
is returned.  Otherwise, an error is signaled.
@end defun

@deftp {Class} <dbi-connection>
@clindex dbi-connection
@{@t{dbi}@}
The base class of a connection to a database system.
Each driver defines a subclass of this to keep information about
database-specific connections.
@end deftp

@deffn {Method} dbi-open? (c <dbi-connection>)
@{@t{dbi}@}
Queries whether a connection to the database is still open (active).
@end deffn

@deffn {Method} dbi-close (c <dbi-connection>)
@{@t{dbi}@}
Closes a connection to the database.  This causes releasing resources
related to this connection.   Once closed, @var{c} cannot
be used for any dbi operations (except passing to @code{dbi-open?}).
Calling @code{dbi-close} on an already closed connection has no effect.

Although a driver usually closes a connection when @code{<dbi-connection>}
object is garbage-collected, it is not a good idea to rely on that,
since the timing of GC is unpredictable.  The user program must make
sure that it calls @code{dbi-close} at a proper moment.
@end deffn

@defun dbi-list-drivers
@{@t{dbi}@}
Returns a list of module names of known drivers.
@end defun

@deftp {Class} <dbi-driver>
@clindex dbi-driver
@{@t{dbi}@}
The base class of a driver.  You usually don't need to see this
as far as you're using the high-level @code{dbi} API.
@end deftp

@defun dbi-make-driver driver-name
@{@t{dbi}@}
This is a low-level function called from @code{dbi-connect} method,
and usually a user doesn't need to call it.

Loads a driver module specified by @var{driver-name}, and
instantiate the driver class and returns it.
@end defun

@subsubheading Preparing and issuing queries

@deffn {Method} dbi-prepare conn sql :key pass-through @dots{}
@{@t{dbi}@}
From a string representation of SQL statement @var{sql},
creates and returns a query object (an instance of @code{<dbi-query>}
or its subclass) for the database connection @code{conn}

@var{Sql} may contain parameter slots, denoted by @code{?}.
@example
(dbi-prepare conn "insert into tab (col1, col2) values (?, ?)")

(dbi-prepare conn "select * from tab where col1 = ?")
@end example

They will be filled when you actually issue the query by
@code{dbi-execute}.
There are some advantages of using parameter
slots: (1) The necessary quoting is done automatically.
You don't need to concern about security holes caused by
improper quoting, for example.
(2) Some drivers support a feature to send the template SQL
statement to the server at the preparation stage, and send
only the parameter values at the execution stage.  It would be
more efficient if you issue similar queries lots of time.

If the backend doesn't support prepared statements (SQL templates
having @code{?} parameters), the driver may use @code{text.sql}
module to parse @var{sql}.  It may raise @code{<sql-parse-error>}
condition if the given SQL is not well formed.

You may pass a true value to the keyword argument @var{pass-through}
to suppress interpretation of SQL and pass @var{sql} as-is to the
back end database system.  It is useful if the back-end supports
extension of SQL which @code{text.sql} doesn't understand.

If the driver lets prepared statement handled in back-end,
without using @code{text.sql}, the @code{pass-through} argument
may be ignored.
The driver may also take other keyword arguments.  Check out
the documentation of individual drivers.

@emph{Note:} Case folding of SQL statement
is implementation dependent.  Some DBMS may treat table
names and column names in case insensitive way, while
others do in case sensitive way.  To write a portable
SQL statement, make them quoted identifiers, that is,
always surround names by double quotes.
@end deffn

@deftp {Class} <dbi-query>
@clindex dbi-query
@{@t{dbi}@}
Holds information about prepared query, created by @code{dbi-prepare}.
The following slots are defined.

@defivar <dbi-query> connection
Contains the @code{<dbi-connection>} object.
@end defivar

@defivar <dbi-query> prepared
If the driver prepares query by itself, this slot may contain
a prepared statement.  It is up to each driver how to use
this slot, so the client shouldn't rely on its value.
@end defivar

@end deftp

@deffn {Method} dbi-open? (q <dbi-query>)
@{@t{dbi}@}
Returns @code{#t} iff the query can still be passed to
@code{dbi-execute}.
@end deffn

@deffn {Method} dbi-close (q <dbi-query>)
@{@t{dbi}@}
Destroy the query and free resources associated to the query.
After this operation, @code{dbi-open?} returns @code{#f} for @var{q},
and the query can't be used in any other way.  Although the resource
may be freed when @var{q} is garbage-collected, it is strongly recommended
that the application closes queries explicitly.
@end deffn

@deffn {Method} dbi-execute (q <dbi-query>) parameter @dots{}
@{@t{dbi}@}
Executes a query created by @code{dbi-prepare}.  You should pass
the same number of @var{parameter}s as the query expects.

If the issued query is @code{select} statement, @code{dbi-execute}
returns an object represents a @emph{relation}.
A relation encapsulates the values in
rows and columns, as well as meta information like column names.
See "Retrieving query results" below for how to access the result.

If the query is other types, such as @code{create}, @code{insert}
or @code{delete}, the return value of the query closure is unspecified.
@end deffn

@deffn {Method} dbi-do conn sql :optional options parameter-value @dots{}
@{@t{dbi}@}
This is a convenience procedure when you create a query
and immediately execute it.   It is equivalent to the following
expression, although the driver may overload this method to avoid
creating intermediate query object to avoid the overhead.
@example
(dbi-execute (apply dbi-prepare conn sql options)
             parameter-value @dots{})
@end example
@end deffn

@deffn {Method}  dbi-escape-sql conn str
@{@t{dbi}@}
Returns a string where special characters in @var{str} are escaped.

The official SQL standard only specify a single quote (@code{'}) as
such character.  However, it doesn't specify non-printable characters,
and the database system may use other escaping characters.  So
it is necessary to use this method rather than doing escaping
by your own.

@example
;; assumes c is a valid DBI connection
(dbi-escape-sql c "don't know")
  @result{} "don''t know"
@end example
@end deffn

@subsubheading Retrieving query results

If the query is a @code{select} statement, it returns an object
of both @code{<collection>} and @code{<relation>}.
It is a collection of rows (that is, it implements @code{<collection>} API),
so you can use @code{map}, @code{for-each} or other generic functions
to access rows.  You can also use the relation API to retrieve column
names and accessors from it.  See @ref{Relation framework}, for the relation
API, and @ref{Collection framework}, for the collection API.

The actual class of the object returned from a query depends on
the driver, but you may use the following method on it.

@deffn {Method} dbi-open? result
@{@t{dbi}@}
Check whether the result of a query is still active.
The result may become inactive when it is explicitly closed
by @code{dbi-close} and/or the connection to the database is
closed.
@end deffn

@deffn {Method} dbi-close result
@{@t{dbi}@}
Close the result of the query.  This may cause releasing resources
related to the result.   You can no longer use @var{result} once it is
closed, except passing it to @code{dbi-open?}.

Although a driver usually releases resources when the result is
garbage-collected, the application shouldn't rely on that and
is recommended call @code{dbi-close} explicitly when it is done
with the result.
@end deffn

@node Writing drivers for DBI,  , DBI user API, Database independent access layer
@subsection Writing drivers for DBI
@c NODE DBI用のドライバを書く

Writing a driver for a specific database system means implementing
a module @code{dbd.@var{foo}}, where @var{foo} is the name of the driver.

The module have to implement several classes and methods, as explained below.

@subsubheading DBI classes to implement

You have to define the following classes.

@itemize @bullet
@item
Subclass @code{<dbi-driver>}.
The class name @emph{must} be @code{<@var{foo}-driver>}, where
@var{foo} is the name of the driver.
Usually this class produces a singleton instance,
and is only used to dispatch @code{dbi-make-connection}
method below.
@item
Subclass @code{<dbi-connection>}.  An instance of this class is created
by @code{dbi-make-connection}.  It needs to keep the information about
the actual connections.
@item
Subclass @code{<relation>} and @code{<collection>} to represent
query results suitable for the driver.  (In most cases, the order of
the result of SELECT statement is significant, since it may be
sorted by ORDER BY clause.  Thus it is more appropriate to
inherit @code{<sequence>}, rather than @code{<collection>}).
@item
Optionally, subclass @code{<dbi-query>} to keep driver-specific
information of prepared queries.
@end itemize

@subsubheading DBI methods to implement

The driver need to implement the following methods.

@deffn {Method} dbi-make-connection (d <foo-driver>) (options <string>) (options-alist <list>) :key username password @dots{}
@{@t{dbi}@}
This method is called from @code{dbi-connect}, and responsible to
connect to the database and to create a connection object.
It must return a connection object, or raise an @code{<dbi-error>} if
it cannot establish a connection.

@var{Options} is the option part of the data source name (DSN) given to
@code{dbi-connect}.  @var{options-alist} is an assoc list of
the result of parsing @var{options}.  Both are provided so that
the driver may interpret @var{options} string in nontrivial way.

For example, given @code{"dbi:foo:myaddressbook;host=dbhost;port=8998"}
as DSN, foo's @code{dbi-make-connection} will receive
@code{"myaddressbook;host=dbhost;port=8998"} as @var{options},
and @code{(("myaddressbook" . #t) ("host" . "dbhost") ("port" . "8998"))}
as @var{options-alist}.

After @var{options-alist}, whatever keyword arguments given to
@code{dbi-connect} are passed.  DBI protocol currently
specifies only @var{username} and @var{password}.
The driver may define other keyword arguments.
It is recommended to name the driver-specific keyword arguments
prefixed by the driver name, e.g. for @code{dbd.foo}, it may take
a @code{:foo-whatever} keyword argument.

It is up to the driver writer to define what options are available and
the syntax of the options.  The basic idea is that the DSN
identifies the source of the data; it's role is like URL in WWW.
So, it may include the hostname and port number of the database,
and/or the name of the database, etc.  However, it shouldn't include
information related to authentication, such as username and password.
That's why those are passed via keyword arguments.
@end deffn

@deffn {Method} dbi-prepare (c <foo-connection>) (sql <string>) :key pass-through @dots{}
@{@t{dbi}@}
This method should create and return a prepared query object,
which is an instance of @code{<dbi-query>} or its subclass.
The query specified by @var{sql} is issued to the database system
when the prepared query object is passed to @code{dbi-execute}.

The method must set @var{c} to the @code{connection} slot of
the returned query object.

@var{Sql} is an SQL statement.  It may contain placeholders represented
by @code{'?'}.  The query closure should take the same number of arguments
as of the placeholders.   It is up to the driver whether it parses
@var{sql} internally and construct a complete SQL statement when
the query closure is called, or it passes @var{sql} to the back-end
server to prepare the statement and let the query closure just send
parameters.

If the driver parses SQL statement internally, it should recognize
a keyword argument @code{pass-through}.  If a true value is given,
the driver must treat @code{sql} opaque and pass it as is when
the query closure is called.

The driver may define other keyword arguments.
It is recommended to name the driver-specific keyword arguments
prefixed by the driver name, e.g. for @code{dbd.foo}, it may take
a @code{:foo-whatever} keyword argument.
@end deffn

@deffn {Method} dbi-execute-using-connection (c <foo-connection>) (q <dbi-query>) (params <list>)
@{@t{dbi}@}
This method is called from @code{dbi-execute}.
It must issue the query kept in @var{q}.  If the query is parameterized,
the actual parameters given to @var{dbi-execute} are passed to
@var{params} argument.

If @var{q} is a @code{select}-type query, this method must return
an appropriate relation object.
@end deffn

@deffn {Method} dbi-escape-sql (c <foo-connection>) str
@{@t{dbi}@}
If the default escape method isn't enough, the driver may
overload this method to implement a specific escaping.
For example, MySQL treats backslash characters specially
as well as single quotes, so it has its @code{dbi-escape-sql}
method.
@end deffn

@deffn {Method} dbi-open? (c <foo-connection>)
@deffnx {Method} dbi-open? (q <foo-query>)
@deffnx {Method} dbi-open? (r <foo-result>)
@deffnx {Method} dbi-close (c <foo-connection>)
@deffnx {Method} dbi-close (q <foo-query>)
@deffnx {Method} dbi-close (r <foo-result>)
@{@t{dbi}@}
Queries open/close status of a connection and a result, and
closes a connection and a result.  The close methods should cause
releasing resources used by connection/result.  The driver
has to allow @code{dbi-close} to be called on a connection or a
result which has already been closed.
@end deffn

@deffn {Method} dbi-do (c <foo-connection>) (sql <string>) :optional options parameter-value @dots{}
@{@t{dbi}@}
The default method uses @code{dbi-prepare} and @code{dbi-execute}
to implement the function.  It just works,
but the driver may overload this method in order to skip
creating intermediate query object for efficiency.
@end deffn

@subsubheading DBI utility functions

The following functions are low-level utilities which you may
use to implement the above methods.

@defun dbi-parse-dsn data-source-name
@{@t{dbi}@}
Parse the data source name (DSN) string given to @code{dbi-connect},
and returns tree values: (1) The driver name in a string. (2)
'options' part of DSN as a string.  (3) parsed options in an assoc
list.  This may raise @code{<dbi-error>} if the given string doesn't
conform DSN syntax.

You don't need to use this to write a typical driver, for the
parsing is done before @code{dbi-make-connection} is called.
This method may be useful if you're writing a kind of meta-driver,
such as a proxy.
@end defun

@defun dbi-prepare-sql connection sql
@{@t{dbi}@}
Parses an SQL statement @var{sql} which may contain placeholders,
and returns a closure, which generates a complete SQL statement when
called with actual values for the parameters.  If the back-end
doesn't support prepared statements, you may use this function
to prepare queries in the driver.

@var{Connection} is a DBI connection to the database.  It is required
to escape values within SQL properly (see @code{dbi-escape-sql} above).

@example
;; assume c contains a valid dbi connection
((dbi-prepare-sql c "select * from table where id=?") "foo'bar")
 => "select * from table where id='foo''bar'"
@end example
@end defun

@c ----------------------------------------------------------------------

@node Generic DBM interface, File-system dbm, Database independent access layer, Library modules - Utilities
@section @code{dbm} - Generic DBM interface
@c NODE 汎用DBMインタフェース, @code{dbm} - 汎用DBMインタフェース

@deftp {Module} dbm
@mdindex dbm
DBM-like libraries provides an easy way to store values to a file,
indexed by keys.  You can think it as a persistent associative memory.

This modules defines @code{<dbm>} abstract class, which has
a common interface to use various DBM-type database packages.
As far as you operate on the already opened database,
importing @code{dbm} module is enough.

To create or open a database, you need a concrete implementation
of the database.  With the default build-time configuration,
the following implementations are included in Gauche.
Bindings to various other dbm-like libraries are
available as extension packages.
Each module defines its own low-level accessing functions
as well as the common interface.
Note that your system may not have one or more of those DBM libraries;
Gauche defines only what the system provides.

@table @code
@item dbm.fsdbm
file-system dbm (@pxref{File-system dbm}).

@item dbm.gdbm
GDBM library (@pxref{GDBM interface}).

@item dbm.ndbm
NDBM library (@pxref{NDBM interface}).

@item dbm.odbm
DBM library  (@pxref{Original DBM interface}).
@end table
@end deftp

The following code shows a typical usage of the database.

@example
(use dbm)         ; @r{dbm abstract interface}
(use dbm.gdbm)    ; @r{dbm concrete interface}

; @r{open the database}
(define *db* (dbm-open <gdbm> :path "mydb" :rw-mode :write))

; @r{put the value to the database}
(dbm-put! *db* "key1" "value1")

; @r{get the value from the database}
(define val (dbm-get *db* "key1"))

; @r{iterate over the database}
(dbm-for-each *db* (lambda (key val) (foo key val)))

; @r{close the database}
(dbm-close *db*)
@end example

The @code{<dbm>} abstract class implements collection 
and dictionary framework.  (See @ref{Collection framework}
and @ref{Dictionary framework}, respectively).

@menu
* Opening and closing a dbm database::
* Accessing a dbm database::
* Iterating on a database::
* Managing dbm database instance::
* Dumping and restoring dbm database::
* Writing a dbm implementation::
@end menu

@node Opening and closing a dbm database, Accessing a dbm database, Generic DBM interface, Generic DBM interface
@subsection Opening and closing a dbm database
@c NODE DBMデータベースのオープンとクローズ

@deftp {Class} <dbm>
@clindex dbm
@{@t{dbm}@}
An abstract class for dbm-style database.    Inherits
@code{<dictionary>} (@pxref{Dictionary framework}).
Defines the common
database operations.   This class has the following instance slots.
They must be set before the database is actually opened by
@code{dbm-open}.

The concrete class may add more slots for finer control on the database,
such as locking.

@defivar <dbm> path
Pathname of the dbm database.  Some dbm implementation may append
suffixes to this.
@end defivar

@defivar <dbm> rw-mode
Specifies read/write mode.  Can be either one of the following keywords:
@table @code
@item :read
The database will be opened in read-only mode.  The database file must
exist when @code{dbm-open} is called.
@item :write
The database will be opened in Read-write mode.
If the database file does not exist, @code{dbm-open} creates one.
@item :create
The database will be created and opened in Read-write mode.
If the database file exists, @code{dbm-open} truncates it.
@end table
@end defivar

@defivar <dbm> file-mode
Specifies the file permissions (as @code{sys-chmod}) to create the
database.  The default value is @code{#o664}.
@end defivar

@defivar <dbm> key-convert
@defivarx <dbm> value-convert
By default, you can use only strings for both key and values.  With this
option, however, you can specify how to convert other Scheme values to/from
string to be stored in the database.   The possible values are the
followings:
@table @asis
@item @code{#f}
The default value.  Keys (values) are not converted.  They must be
a string.
@item @code{#t}
Keys (values) are converted to its string representation, using
@code{write}, to store in the database, and converted
back to Scheme values, using @code{read}, to retrieve from the database.
The data must have an external representation that can be read back.
(But it is not checked when the data is written; you'll get an error
when you read the data).  The key comparison is done in the string
level, so the external representation of the same key must match.
@item a list of two procedures
Both procedure must take a single argument.  The first procedure must
receive a Scheme object and returns a string.  It is used to convert
the keys (values) to store in the database.  The second procedure
must receive a string and returns a Scheme object.  It is used to
convert the stored data in the database to a Scheme object.
The key comparison is done in the string
level, so the external representation of the same key must match.
@end table
@end defivar
@end deftp

@deftp {Metaclass} <dbm-meta>
@clindex dbm-meta
@{@t{dbm}@}
A metaclass of @code{<dbm>} and its subclasses.
@end deftp

@deffn {Method} dbm-open (dbm <dbm>)
@{@t{dbm}@}
Opens a dbm database.  @var{dbm} must be an instance of
one of the concrete classes that derived from the @code{<dbm>} class,
and its slots must be set appropriately.   On success, it returns
the @var{dbm} itself.  On failure, it signals an error.
@end deffn

@deffn {Method} dbm-open (dbm-class <dbm-meta>) options @dots{}
@{@t{dbm}@}
A convenient method that creates dbm instance and opens it.
It is defined as follows.
@example
(define-method dbm-open ((class <class>) . initargs)
  (dbm-open (apply make class initargs)))
@end example
@end deffn

Database file is closed when it is garbage collected.
However, to ensure the modification is properly synchronized,
you should close the database explicitly.

@deffn {Method} dbm-close (dbm @code{<dbm>})
@{@t{dbm}@}
Closes a database @var{dbm}.  Once the database is closed, any
operation to access the database content raises an error.
@end deffn

@deffn {Method} dbm-closed? (dbm @code{<dbm>})
@{@t{dbm}@}
Returns true if a database @var{dbm} is already closed, false otherwise.
@end deffn

@defun dbm-type->class dbmtype
@{@t{dbm}@}
Sometimes you don't know which type of dbm implementation you
need to use in your application beforehand, but rather you need to
determine the type according to the information given at run-time.
This procedure fulfills the need.

The @var{dbmtype} argument is a symbol that names the type
of dbm implementation; for example, @code{gdbm} for @code{dbm.gdbm},
and @code{fsdbm} for @code{dbm.fsdbm}.   We assume that the
dbm implementation of type @code{@var{foo}} is provided as
a module @code{dbm.@var{foo}}, and its class is named
as @code{<@var{foo}>}.

This procedure first checks if the required module has been
loaded, and if not, it tries to load it.   If the module
loads successfully, it returns the class object of the
named dbm implementation.   If it can't load the module,
or can't find the dbm class, this procedure returns #f.

@example
(use dbm)

(dbm-type->class 'gdbm)
  @result{} @code{#<class <gdbm>>}

(dbm-type->class 'nosuchdbm)
  @result{} @code{#f}
@end example
@end defun

@node Accessing a dbm database, Iterating on a database, Opening and closing a dbm database, Generic DBM interface
@subsection Accessing a dbm database
@c NODE DBMデータベースのアクセス

Once a database is opened, you can use the following methods
to access individual key/value pairs.

@deffn {Method} dbm-put! (dbm @code{<dbm>}) key value
@{@t{dbm}@}
Put a @var{value} with @var{key}.
@end deffn

@deffn {Method} dbm-get (dbm @code{<dbm>}) key :optional default
@{@t{dbm}@}
Get a value associated with @var{key}.  If no value exists for @var{key}
and @var{default} is specified, it is returned.  If no value exists for
@var{key} and @var{default} is not specified, an error is signaled.
@end deffn

@deffn {Method} dbm-exists? (dbm @code{<dbm>}) key
@{@t{dbm}@}
Return true if a value exists for @var{key}, false otherwise.
@end deffn

@deffn {Method} dbm-delete! (dbm @code{<dbm>}) key
@{@t{dbm}@}
Delete a value associated with @var{key}.
@end deffn

@node Iterating on a database, Managing dbm database instance, Accessing a dbm database, Generic DBM interface
@subsection Iterating on a dbm database
@c NODE DBMデータベース上の繰り返し処理

To walk over the entire database, following methods are provided.

@deffn {Method} dbm-fold (dbm @code{<dbm>}) procedure knil
@{@t{dbm}@}
The basic iterator.
For each key/value pair, @var{procedure} is called as
@code{(@var{procedure} @var{key} @var{value} @var{r})},
where @var{r} is @var{knil} for the fist call of @var{procedure},
and the return value of the previous call for subsequent calls.
Returns the result of the last call of @var{procedure}.
If no data is in the database, @var{knil} is returned.

The following method returns the sum of all the integer values.
@example
(dbm-fold dbm (lambda (k v r) (if (integer? v) (+ v r) r)) 0)
@end example
@end deffn

@deffn {Method} dbm-for-each (dbm @code{<dbm>}) procedure
@{@t{dbm}@}
For each key/value pair in the database @var{dbm}, @var{procedure}
is called.  Two arguments are passed to @var{procedure}---a key and
a value.   The result of @var{procedure} is discarded.
@end deffn

@deffn {Method} dbm-map (dbm @code{<dbm>}) procedure
@{@t{dbm}@}
For each key/value pair in the database @var{dbm}, @var{procedure}
is called.  Two arguments are passed to @var{procedure}---a key and
a value.   The result of @var{procedure} is accumulated to a list
which is returned as a result of @code{dbm-map}.
@end deffn

@node Managing dbm database instance, Dumping and restoring dbm database, Iterating on a database, Generic DBM interface
@subsection Managing dbm database instance
@c NODE DBMデータベースインスタンスの管理

Each dbm implementation has its own way to store the
database.  Legacy dbm uses two files, whose names are
generated by adding @file{.dir} and @file{.pag} to the
value of @var{path} slot.  @code{Fsdbm} creates a directory
under @var{path}.  If dbm database is backed up by
some database server, @var{path} may be used only as
a key to the database in the server.
The following methods hide such variations and provides
a convenient way to manage a database itself.   You have to
pass a class that implements a concrete dbm database to their
first argument.

@deffn {Generic Function} dbm-db-exists? class name
@{@t{dbm}@}
Returns @code{#t} if a database of class @var{class}
specified by @var{name} exists.

@example
;; Returns #t if testdb.dir and testdb.pag exist
(dbm-db-exists? <odbm> "testdb")
@end example
@end deffn

@deffn {Generic Function} dbm-db-remove class name
@{@t{dbm}@}
Removes an entire database of class @var{class} specified by
@var{name}.
@end deffn

@deffn {Generic Function} dbm-db-copy class from to
@{@t{dbm}@}
Copy a database of class @var{class} specified by
@var{from} to @var{to}.  The integrity of @var{from}
is guaranteed if the @var{class}'s dbm implementation supports
locking (i.e. you won't get a corrupted database even if
some other process is trying to write to @var{from}
during copy).   If the destination database @var{to} exists,
its content is destroyed.  If this function is interrupted,
whether @var{to} is left in incomplete state or not depends
on the dbm implementation.   The implementation usually tries
its best to provide transactional behavior, that is,
to recover original @var{to} when the copy fails.  However,
for the robust operations the caller have to check the state
of @var{to} if @code{dbm-db-copy} fails.

@example
(dbm-db-copy <gdbm> "testdb.dbm" "backup.dbm")
@end example
@end deffn

@deffn {Generic Function} dbm-db-move class from to
@{@t{dbm}@}
Moves or renames a database of class @var{class} specified by
@var{from} to @var{to}.  Like @code{dbm-db-copy}, the database
integrity is guaranteed as far as @var{class}'s dbm implementation
supports locking.  If the destination database @var{to} exists,
its content is destroyed.
@end deffn

@node Dumping and restoring dbm database, Writing a dbm implementation, Managing dbm database instance, Generic DBM interface
@subsection Dumping and restoring dbm database
@c NODE DBMデータベースのダンプとリストア

Most dbm implementations use some kind of binary format, and
some of them are architecture dependent.
That makes it difficult to pass around dbm databases
between different machines.
A safe way is to write out the content of a dbm database
into some portable format on the source machine,
and rebuild another dbm database from it on the destination
machine.

The operation is so common that Gauche provides convenience
scripts that does the job.  They are installed into the
standard Gauche library directory, so it can be invoked
by @code{gosh <scriptname>}.

To write out the content of a dbm database named by @var{dbm-name},
you can use @code{dbm/dump} script:

@example
$ gosh dbm/dump [-o @var{outfile}][-t @var{type}] @var{dbm-name}
@end example

The @var{outfile} argument names the output file.  If omitted,
the output is written out to stdout.  The @var{type} argument
specifies the implementation type of the dbm database; e.g.
@code{gdbm} or @code{fsdbm}.  The program calls
@code{dbm-type->class} (@pxref{Opening and closing a dbm database})
on the @var{type} argument to load the necessary dbm implementation.

The dumped format is simply a series of S-expressions,
each of which is a dotted pair of string key and string value.
Character encodings are assumed to be the same as
@code{gosh}'s native character encoding.

The dumped output may contain S-expressions other than dotted pair
of strings to include meta information.  For now, programs
that deals with dumped output should just ignore S-expressions
other than dotted pairs.

To read back the dumped dbm format, you can use @code{dbm/restore}
script:

@example
$ gosh dbm/restore [-i @var{infile}][-t @var{type}] @var{dbm-name}
@end example

The @var{infile} argument names the dumped file to be read.
If omitted, it reads from stdin.  The @var{type} argument
specifies the dbm type, as in @code{dbm/dump} script.
The @var{dbm-name} argument names the dbm database; if the
database already exists, its content is cleared, so be careful.


@node Writing a dbm implementation,  , Dumping and restoring dbm database, Generic DBM interface
@subsection Writing a dbm implementation
@c NODE DBM実装を書く

When you write an extension module that behaves like
a persistent hashtable, it is a good idea to adapt it
to the dbm interface, so that the application can use
the module in a generic way.

The minimum procedures to conform the dbm interface
are as follow:

@itemize @bullet
@item
Define a metaclass @code{<@var{foo}-meta>}.   It doesn't
need to inherit anything except @code{<class>}.
@item
Define a dbm class @code{<@var{foo}>} that inherits @code{<dbm>}
and whose metaclass is @code{<@var{foo}-meta>}.
@item
Define methods for @code{dbm-open}, @code{dbm-close},
@code{dbm-put!}, @code{dbm-get}, @code{dbm-exists},
@code{dbm-delete!}, @code{dbm-fold}, @code{dbm-closed?},
specialized for @code{<@var{foo}>}.
(The case of @code{dbm-open} for @code{<@var{foo}-meta>} is
handled automatically, so you don't need to define it unless
you want something special).
Also note that the specialized @code{dbm-open} must call
@code{next-method} in it to set up dbm base class internals.
@item
Define methods for @code{dbm-db-exists?} and
@code{dbm-db-remove} on @code{<@var{foo}-meta>}.
@end itemize

Besides above, you may define the following methods.

@itemize @bullet
@item
Methods for @code{dbm-for-each} and @code{dbm-map}.
If you don't define them, a generic implementation
by @code{dbm-fold} is used.  There may be an implementation
specific way which is more efficient.
@item
Methods for @code{dbm-db-copy} and @code{dbm-db-move}.
If you don't define them, a fallback method
opens the specified databases and copies elements one by
one, and removes the original if the method is  @code{dbm-db-move}.
Note that the fallback method is not only inefficient,
but also it may not copy any implementation-specific
meta information.  It is highly recommended for the
dbm implementation to provide these methods as well.
@end itemize

It is generally recommended to name the implementation module
as @code{dbm.@var{foo}}, and the class of the implementation
as @code{<@var{foo}>}.  With this convention it is easier to
write an application that dynamically loads and uses
dbm implementation specified at runtime.

@c ----------------------------------------------------------------------
@node File-system dbm, GDBM interface, Generic DBM interface, Library modules - Utilities
@section @code{dbm.fsdbm} - File-system dbm
@c NODE ファイルシステムdbm, @code{dbm.fsdbm} - ファイルシステムdbm

@deftp {Module} dbm.fsdbm
@mdindex dbm.fsdbm
Implements fsdbm.  Extends @code{dbm}.
@end deftp

@deftp {Class} <fsdbm>
@clindex fsdbm
@{@t{dbm.fsdbm}@}
@code{Fsdbm} is a dbm implementation that directly uses
the filesystem.  Basically, it uses file names for keys,
and file content for values.   Unlike other dbm implementations,
this doesn't depend on external libraries---it is pure Scheme
implementation---so it is always available, while other dbm
implementations may not.
Obviously, it is not suitable for the database that has
lots of entries, or has entries deleted and added very frequently.
The advantage is when the number of entries
are relatively small, and the values are relatively large while
keys are small.
The database name given to @code{<fsdbm>} instance
is used as a directory name that stores the data.
The data files are stored in subdirectories under @var{path} of
@code{fsdbm} instance, hashed by the key.  Non-alphanumeric characters
in the key is encoded like @code{_3a} for '@code{:}', for example.
If a key is too long to be a file name, it is chopped to chunks,
and each chunk but the last one is used as a directory name.
Note that a long key name may still cause a problem, for example,
some of old 'tar' command can't deal with pathnames (not each
pathname components, but the entire pathname) longer than 256
characters.
@end deftp

Fsdbm implements all of the dbm protocol
(see @ref{Generic DBM interface}).
It doesn't have any fsdbm-specific procedures.

@c ----------------------------------------------------------------------
@node GDBM interface, NDBM interface, File-system dbm, Library modules - Utilities
@section @code{dbm.gdbm} - GDBM interface
@c NODE GDBMインタフェース, @code{dbm.gdbm} - GDBMインタフェース

@deftp {Module} dbm.gdbm
@mdindex dbm.gdbm
Provides interface to the gdbm library.  Extends @code{dbm}.
@end deftp

@deftp {Class} <gdbm>
@clindex gdbm
@{@t{dbm.gdbm}@}
Inherits @code{<dbm>}.  Provides an implementation for GDBM library.
This module is only installed when your system already has GDBM
(1.8.0 is preferred, but works with older 1.7.x with some limitations).

@defivar <gdbm> sync
@end defivar
@defivar <gdbm> nolock
@end defivar
@defivar <gdbm> bsize
@end defivar
@end deftp

Besides the unified DBM interface (@pxref{Generic DBM interface}),
this module provides the following low-level functions that provides
direct access to the gdbm API.  See gdbm manual for details of these
APIs.

@defun gdbm-open path :optional size rwmode fmode error-callback
@{@t{dbm.gdbm}@}
@end defun

@defvar GDBM_READER
@{@t{dbm.gdbm}@}
@end defvar

@defvar GDBM_WRITER
@{@t{dbm.gdbm}@}
@end defvar

@defvar GDBM_WRCREAT
@{@t{dbm.gdbm}@}
@end defvar

@defvar GDBM_NEWDB
@{@t{dbm.gdbm}@}
@end defvar

@defvar GDBM_FAST
@{@t{dbm.gdbm}@}
@end defvar

@defvar GDBM_SYNC
@{@t{dbm.gdbm}@}
@end defvar

@defvar GDBM_NOLOCK
@{@t{dbm.gdbm}@}
@end defvar

@defun gdbm-close gdbm-object
@{@t{dbm.gdbm}@}
@end defun

@defun gdbm-closed? gdbm-object
@{@t{dbm.gdbm}@}
@end defun

@defun gdbm-store key value :optional flag
@{@t{dbm.gdbm}@}
@end defun

@defvar GDBM_INSERT
@{@t{dbm.gdbm}@}
@end defvar

@defvar GDBM_REPLACE
@{@t{dbm.gdbm}@}
@end defvar


@defun gdbm-fetch gdbm-object key
@{@t{dbm.gdbm}@}
@end defun


@defun gdbm-delete gdbm-object key
@{@t{dbm.gdbm}@}
@end defun


@defun gdbm-firstkey gdbm-object
@{@t{dbm.gdbm}@}
@end defun


@defun gdbm-nextkey gdbm-object key
@{@t{dbm.gdbm}@}
@end defun


@defun gdbm-reorganize gdbm-object
@{@t{dbm.gdbm}@}
@end defun


@defun gdbm-sync gdbm-object
@{@t{dbm.gdbm}@}
@end defun


@defun gdbm-exists? gdbm-object key
@{@t{dbm.gdbm}@}
@end defun


@defun gdbm-strerror errno
@{@t{dbm.gdbm}@}
@end defun


@defun gdbm-setopt gdbm-object option value
@{@t{dbm.gdbm}@}
@end defun

@defvar GDBM_CACHESIZE
@{@t{dbm.gdbm}@}
@end defvar

@defvar GDBM_FASTMODE
@{@t{dbm.gdbm}@}
@end defvar

@defvar GDBM_SYNCMODE
@{@t{dbm.gdbm}@}
@end defvar

@defvar GDBM_CENTFREE
@{@t{dbm.gdbm}@}
@end defvar

@defvar GDBM_COALESCEBLKS
@{@t{dbm.gdbm}@}
@end defvar

@defun gdbm-version
@{@t{dbm.gdbm}@}
@end defun

@defun gdbm-errno
@{@t{dbm.gdbm}@}
@end defun

@c ----------------------------------------------------------------------
@node NDBM interface, Original DBM interface, GDBM interface, Library modules - Utilities
@section @code{dbm.ndbm} - NDBM interface
@c NODE NDBMインタフェース, @code{dbm.ndbm} - NDBMインタフェース

@deftp {Module} dbm.ndbm
@mdindex dbm.ndbm
Provides interface to the 'new' dbm library, a.k.a. ndbm.
Extends @code{dbm}.
@end deftp

@deftp {Class} <ndbm>
@clindex ndbm
@{@t{dbm.ndbm}@}
Inherits @code{<dbm>}.  Provides an implementation for NDBM library.
This module is only installed when your system already has NDBM.
@end deftp

Besides the unified DBM interface (@pxref{Generic DBM interface}),
this module provides the following low-level functions that provides
direct access to the ndbm API.  See ndbm manual for details of these
APIs.

@defun ndbm-open path flags mode
@{@t{dbm.ndbm}@}
@end defun

@defun ndbm-close ndbm-object
@{@t{dbm.ndbm}@}
@end defun

@defun ndbm-closed? ndbm-object
@{@t{dbm.ndbm}@}
@end defun

@defun ndbm-store ndbm-object key content :optional flag
@{@t{dbm.ndbm}@}
@end defun

@defun ndbm-fetch ndbm-object key
@{@t{dbm.ndbm}@}
@end defun

@defun ndbm-delete ndbm-object key
@{@t{dbm.ndbm}@}
@end defun

@defun ndbm-firstkey ndbm-object
@{@t{dbm.ndbm}@}
@end defun

@defun ndbm-nextkey ndbm-object
@{@t{dbm.ndbm}@}
@end defun

@defun ndbm-error ndbm-object
@{@t{dbm.ndbm}@}
@end defun

@defun ndbm-clear-error ndbm-object
@{@t{dbm.ndbm}@}
@end defun

@c ----------------------------------------------------------------------
@node Original DBM interface, Filtering file content, NDBM interface, Library modules - Utilities
@section @code{dbm.odbm} - Original DBM interface
@c NODE オリジナルのDBMインタフェース, @code{dbm.odbm} - オリジナルのDBMインタフェース

@deftp {Module} dbm.odbm
@mdindex dbm.odbm
Provides interface to the legacy dbm library.
Extends @code{dbm}.
@end deftp

@deftp {Class} <odbm>
@clindex odbm
@{@t{dbm.odbm}@}
Inherits @code{<dbm>}.  Provides an implementation for legacy DBM
library.
This module is only installed when your system already has DBM.

The biggest limitation of the legacy DBM is that you can only open
one database at a time.  You can create a multiple @code{<odbm>}
instances, but you can open at most one of it at a time, or
you'll get an error.
@end deftp

Besides the unified DBM interface (@pxref{Generic DBM interface}),
this module provides the following low-level functions that provides
direct access to the dbm API.  See dbm manual for details of these
APIs.

@defun odbm-init path
@{@t{dbm.odbm}@}
@end defun

@defun odbm-close
@{@t{dbm.odbm}@}
@end defun

@defun odbm-store key value
@{@t{dbm.odbm}@}
@end defun

@defun odbm-fetch key
@{@t{dbm.odbm}@}
@end defun

@defun odbm-delete key
@{@t{dbm.odbm}@}
@end defun

@defun odbm-firstkey
@{@t{dbm.odbm}@}
@end defun

@defun odbm-nextkey key
@{@t{dbm.odbm}@}
@end defun


@c ----------------------------------------------------------------------
@c @node Pseudo DBM interface, gauche.charconv - Character code conversion, Original DBM interface, Library modules
@c @section @code{dbm.pdbm} - Pseudo DBM interface

@c ----------------------------------------------------------------------
@node Filtering file content, Filesystem utilities, Original DBM interface, Library modules - Utilities
@section @code{file.filter} - Filtering file content
@c NODE ファイルのフィルタ, @code{file.filter} - ファイルのフィルタ

@deftp {Module} file.filter
@mdindex file.filter
This module provides utilities for a common pattern in
filter-type commands, that is, to take an input, to process
the content, and to write the result.   The common occurring
pattern is:

@itemize @bullet
@item
Input may be a specified file, or an input port
(the current input port by default).
@item
Output may be a specified file, or an output port
(the current output port by default).
@item
Output may be a temporary file, which will be renamed
upon completion of the processing.
@item
Output file may be removed when an error occurs
in the processing.
@end itemize
@end deftp

@defun file-filter proc :key input output temporary-file keep-output? rename-hook
@{@t{file.filter}@}
Calls @var{proc} with two arguments, an input port and
an output port.   Returns the result(s) of @var{proc}.
The input port and output port are chosen depending on the keyword arguments.

@table @code
@item input
The argument must be either an input port or a string
that specifies a file name.
If it's an input port, it is passed to @var{proc} as is.
If it's a string, the named file is opened for input and the resulting
port is passed to @var{proc}, and the port is closed when @var{proc}
returns.
If this argument is omitted, the current input port is passed.
@item output
The argument must be either an output port or a string
that specifies a file name.
If it's an output port, it is passed to @var{proc} as is.
If it's a string, the named file is opened for output
(unless @var{temporary-file} is given, in that case
a temporary file is opened instead), and the resulting port
is passed to @var{proc}.  This port is closed when @var{proc} returns.
If this argument is omitted, the current output port is passed.
@item temporary-file
The value must be a boolean or a string.  If a non-false value
is given, and output is a file, then a fresh temporary file is
created and opened for output and passed to @var{proc}.
When @var{proc} returns normally, the file is renamed
to the name given to @var{output} keyword argument.

If @code{#t} is given, a temporary file name is generated
based on the name of the output file.
If a string file name is given to this argument, the name
is used for @code{sys-mkstemp}.

If the given file name begins with characters except @code{"/"}, @code{"./"}
or @code{"../"}, the directory of the file name given to @var{output} argument
is attached before it.

The default value is @code{#f} (do not use a temporary file).
@item keep-output?
If a true value is given, the output is not deleted even
when @var{proc} signals an error.
By default, the output (or the temporary file when
@var{temporary-file} is given) will be deleted on error.
@item leave-unchanged
When a temporary file is used, and a true value is given to this argument,
the existing output file is left intact when the generated output in
the temporary file exactly matches the original content of the output
file.  It is useful if touching output file may trigger some actions
(e.g. by @code{make}) and you want to avoid invoking unnecessary
actions.  The default value is @code{#f} (always replace the output).
@end table
@end defun

@defun file-filter-fold proc seed :key reader input output temporary-file keep-output? rename-hook
@{@t{file.filter}@}
A convenience wrapper of @code{file-filter}.
Call @var{proc} for each item read from input
by @var{reader} (@code{read-line} by default).  The argument
@var{proc} receives is the item, the seed value and the output port;
@var{proc} can emit the output, as well as returning some value
that is passed along as the seed value.  Other keyword arguments
are passed to @code{file-filter}.

For example, the following code reads each line from @file{file.txt} and
displays lines matching @code{#/regexp/} with line numbers.

@example
(file-filer-fold
  (^[line nc out]
    (when (#/regexp/ line) (format out "~3d: ~a\n" nc line))
    (+ nc 1))
  1 :input "file.txt")
@end example
@end defun

@defun file-filter-map proc :key reader input output temporary-file keep-output? rename-hook
@defunx file-filter-for-each proc :key reader input output temporary-file keep-output? rename-hook
@{@t{file.filter}@}
Utilities similar to @code{file-filter-fold},
like @code{map} and @code{for-each} to @code{fold}.

The procedure @var{proc} is called with two arguments,
an item read from the input and an output port.
The results of @var{proc} are collected as a list and returned
by @code{file-filter-map}, and discarded by @code{file-filter-for-each}.

The meaning of keyword arguments are the same as @code{file-filter-fold}.
@end defun


@c ----------------------------------------------------------------------
@node Filesystem utilities, Mathematic constants, Filtering file content, Library modules - Utilities
@section @code{file.util} - Filesystem utilities
@c NODE ファイルシステムユーティリティ, @code{file.util} - ファイルシステムユーティリティ

@deftp {Module} file.util
@mdindex file.util
Provides convenient utility functions handling files and directories.
Those functions are built on top of the primitive system
procedures described in @ref{Filesystems}.

Many procedures in this module takes a keyword argument @var{follow-link?},
which specifies the behavior when the procedure sees a symbolic link.
If true value is given to @var{follow-link?} (which is the default),
the procedure operates on the file referenced by the link; if false is
given, it operates on the link itself.
@end deftp

Note on the naming convention: Some Scheme implementations "create"
new directories and files, while the others "make" them.
Some implementations "delete" them, while the others "remove" them.
It seems that both conventions are equally popular.
So Gauche provides @emph{both}.

@menu
* Directory utilities::
* Pathname utilities::
* File attribute utilities::
* File operations::
* Temporary files and directories::
* Lock files::
@end menu

@node Directory utilities, Pathname utilities, Filesystem utilities, Filesystem utilities
@subsection Directory utilities
@c NODE ディレクトリユーティリティ

@defun current-directory :optional new-directory
@{@t{file.util}@}
When called with no argument, this returns the pathname of the current
working directory.  When called with a string argument @var{new-directory},
this sets the current working directory of the process to it.
If the process can't change directory to @var{new-directory}, an error is
signaled.

This function is in ChezScheme, MzScheme and some other Scheme
implementations.

SRFI-170 defines @code{current-directory} without arguments, to return
the current working directory.
@end defun

@defun home-directory :optional user
@{@t{file.util}@}
Returns the home directory of the given @var{user},
which may be a string user name or an integer user id.
If @var{user} is omitted, the current user is assumed.
If the given user cannot be found, or the home directory
of the user cannot be determined, @code{#f} is returned.

On Windows native platforms, this function is only supported
to query the current user's directory.
@end defun

@defun directory-list path :key children? add-path? filter filter-add-path?
@{@t{file.util}@}
Returns a list of entries in the directory @var{path}.
The result is sorted by dictionary order.

By default, only the basename (the last component) of the entries
returned.   If @var{add-path?} is given and true, @var{path} is appended
to each entry.  If @var{children?} is given and true, @code{"."} and
@code{".."} are excluded from the result.

If @var{filter} is given, it must be a predicate that takes one argument.
It is called on every element of the directory entry,
and only the entries on which
@var{filter} returns true are included in the result.
The argument passed to @var{filter} is a basename of the directory entry
by default, but when @var{filter-add-path?} is true, @var{path} is
appended to the entry.

If @var{path} is not a directory, an error is signaled.

@example
(directory-list "test")
 @result{} ("." ".." "test.scm" "test.scm~")

(directory-list "test" :add-path? #t)
 @result{} ("test/." "test/.." "test/test.scm" "test/test.scm~")

(directory-list "test" :children? #t)
 @result{} ("test.scm" "test.scm~")

(directory-list "test" :children? #t :add-path? #t
   :filter (lambda (e) (not (string-suffix? "~" e))))
 @result{} ("test/test.scm")
@end example
@end defun

@defun directory-list2 path :key children? add-path? filter follow-link?
@{@t{file.util}@}
Like @code{directory-list}, but returns two values; the first one is a list
of subdirectories, and the second one is a list of the rest.
The keyword arguments @var{children?}, @code{add-path?} and @var{filter}
are the same as @code{directory-list}.

Giving false value to @var{follow-link?} makes @code{directory-list2}
not follow the symbolic links; if the @var{path} contains a
symlink to a directory,
it will be included in the first list if @var{follow-link?}
is omitted or true,
while it will be in the second list if @var{follow-link?} is false.
@end defun

@defun directory-fold path proc seed :key lister follow-link?
@{@t{file.util}@}
A fundamental directory traverser.
Conceptually it works as follows, in recursive way.

@itemize @bullet
@item
If @var{path} is not a directory, calls
@code{(@var{proc} @var{path} @var{seed})} and returns the result.
@item
If @var{path} is a directory, calls
@code{(@var{lister} @var{path} @var{seed})}.  The procedure @var{lister}
is expected to return two values: a list of pathnames, and the
next seed value.   Then
@code{directory-fold} is called on each returned pathname,
passing the returned seed value to the @var{seed} argument of the
next call of @code{directory-fold}.
Returns the result of the last seed value.
@end itemize

The default procedure of @var{lister} is just a call to @code{directory-list},
as follows.
@example
(lambda (path seed)
  (values (directory-list path :add-path? #t :children? #t)
          seed))
@end example

Note that @var{lister} shouldn't return the given path itself (@code{"."})
nor the parent directory (@code{".."}), or the recursion wouldn't
terminate.  Also note @var{lister} is expected to return a path accessible
from the current directory, i.e. if @var{path} is @code{"/usr/lib/foo"} and
it contains @code{"libfoo.a"} and @code{"libfoo.so"}, @var{lister} should
return @code{'("/usr/lib/foo/libfoo.a" "/usr/lib/foo/libfoo.so")}.

The keyword argument @var{follow-link?} is used to determine whether
@var{lister} should be called on a symbolic link pointing to a directory.
When @var{follow-link?} is true (default), @var{lister} is called
with the symbolic link if it points to a directory.
When @var{follow-link?} is false, @var{proc} is not called.

The following example returns a list of pathnames of the emacs backup files
(whose name ends with "~") under the given path.
@example
(use srfi-13) ;; for string-suffix?
(directory-fold path
                (lambda (entry result)
                  (if (string-suffix? "~" entry)
                      (cons entry result)
                      result))
                '())
@end example

The following example lists all the files and directories under the
given pathname.   Note the use of @var{lister} argument to include
the directory path itself in the result.
@example
(directory-fold path cons '()
  :lister (lambda (path seed)
            (values (directory-list path :add-path? #t :children? #t)
                    (cons path seed))))
@end example

@end defun

@defun make-directory* name :optional perm
@defunx create-directory* name :optional perm
@{@t{file.util}@}
Creates a directory @var{name}.  If the intermediate path to the
directory doesn't exist, they are also created
(like @code{mkdir -p} command on Unix).   If the directory
@var{name} already exist, these procedure does nothing.
@var{Perm} specifies the integer flag for permission bits of the
directory.
@end defun


@defun remove-directory* name
@defunx delete-directory* name
@{@t{file.util}@}
Deletes directory @var{name} and its content recursively
(like @code{rm -r} command on Unix).   Symbolic links are not
followed.
@end defun

@defun copy-directory* src dst :key if-exists backup-suffix safe keep-timestamp keep-mode follow-link?
@{@t{file.util}@}
If @var{src} is a regular file, copies its content to @var{dst}, just like
@code{copy-file} does.  If @var{src} is a directory, recursively
descends it and copy the file tree to @var{dst}.  Basically
it mimics the behavior of @code{cp -r} command.

If there's any symbolic links under @var{src}, the link itself
is copied instead of the file pointed to by it, unless a true value
is given to the @var{follow-link?} keyword argument,
i.e. the default value of @var{follow-link?} is @code{#f}.
(Note that this is opposite to the @code{copy-file}, in which
@var{follow-link?} is true by default.)

The meanings of the other keyword arguments are the same as
@code{copy-file}.  See the entry of @code{copy-file} for the details.
@end defun

@defun create-directory-tree dir spec
@{@t{file.util}@}
Creates a directory tree under @var{dir} according to @var{spec}.
This procedure is useful to set up certain directory hierarchy at once.

The @var{spec} argument is an S-expression with the following structure:

@example
<spec> : <name>                             ; empty file
       | (<name> <option> ...)              ; empty file
       | (<name> <option> ... <string>)     ; file with content
       | (<name> <option> ... <procedure>)  ; file with generated content
       | (<name> <option> ... (<spec> ...)) ; directory

<name> : string or symbol

<option> ... : keyword-value alternating list
@end example

With the first and second form of @var{spec}, an empty file is created
with the given name.
With the third form of @var{spec}, the string becomes the
content of the file.

With the fourth form of @var{spec}, the procedure is called with the
pathname as an argument, and output to the current output
port within the procedure is written to the created file.
The pathname is relative to the @var{dir} argument.
At the time the procedure is called, its parent directory
is already created.

The last form of @var{spec} creates a named directory,
then creates its children recursively according to the specs.

With @var{option}s you can control attributes of created files/directories.
Currently the following options are recognized.

@table @code
@item :mode @var{mode}
Takes integer as permission mode bits.
@item :owner @var{uid}
@itemx :group @var{gid}
Takes integer uid/gid of the owner/group of the file/directory.
Calling process may need special privilege to change the owner
and/or group.
@item :symlink @var{path}
This is only valid for file spec, and it causes
@code{create-directory-tree} to create a named symbolic link
whose content is @var{path}.
@end table
@end defun

@defun check-directory-tree dir spec
@{@t{file.util}@}
Checks if a directory hierarchy according to @var{spec} exists
under @var{dir}.  Returns @code{#t} if it exists, or @code{#f} otherwise.

The format of @var{spec} is the same
as @code{create-directory-tree} described above.

If @var{spec} contains options, the attributes of existing
files/directories are also checked if they match the given options.
@end defun


@node Pathname utilities, File attribute utilities, Directory utilities, Filesystem utilities
@subsection Pathname utilities
@c NODE パスネームユーティリティ

@defun build-path base-path component @dots{}
@{@t{file.util}@}
Appends pathname components @var{component} to the @var{base-path}.
@var{Component} can be a symbol @code{up} or @code{same};
in Unix, they are synonym to @code{".."} and @code{"."}.
This API is taken from MzScheme.
@end defun

@defun absolute-path? path
@defunx relative-path? path
@{@t{file.util}@}
Returns @code{#t} if @var{path} is absolute or relative, respectively.
@end defun

@defun expand-path path
@{@t{file.util}@}
Expands tilda-notation of @var{path} if it contains one.
Otherwise, @var{path} is returned.  This function does not
check if @var{path} exists and/or readable.
@end defun

@defun resolve-path path
@{@t{file.util}@}
Expands @var{path} like @code{expand-path},
then resolve symbolic links for every components
of the path.  If @var{path} does not exist, or contains dangling link,
or contains unreadable directory, an error is signaled.
@end defun

@defun simplify-path path
@{@t{file.util}@}
Remove 'up' (@code{".."}) components and 'same' (@code{"."}) components
from @var{path} as much as possible.
This function does not access the filesystem.
@end defun

@defun decompose-path path
@{@t{file.util}@}
Returns three values; the directory part of @var{path},
the basename without extension of @var{path}, and
the extension of @var{path}.    If the pathname doesn't have an extension,
the third value is @code{#f}.  If the pathname ends with a directory
separator, the second and third values are @code{#f}. (Note: This treatment
of the trailing directory separator differs from
@code{sys-dirname}/@code{sys-basename}; those follow popular shell's
convention, which ignores trailing slashes.)
@example
(decompose-path "/foo/bar/baz.scm")
  @result{} "/foo/bar", "baz", "scm"
(decompose-path "/foo/bar/baz")
  @result{} "/foo/bar", "baz", #f

(decompose-path "baz.scm")
  @result{} ".", "baz", "scm"
(decompose-path "/baz.scm")
  @result{} "/", "baz", "scm"

;; Boundary cases
(decompose-path "/foo/bar/baz.")
  @result{} "/foo/bar", "baz", ""
(decompose-path "/foo/bar/.baz")
  @result{} "/foo/bar", ".baz", #f
(decompose-path "/foo/bar.baz/")
  @result{} "/foo/bar.baz", #f, #f
@end example
@end defun

@defun path-extension path
@defunx path-sans-extension path
@{@t{file.util}@}
Returns an extension of @var{path},
and  a pathname of @var{path} without extension, respectively.
If @var{path} doesn't have an extension, @code{#f} and @var{path}
is returned respectively.

@example
(path-extension "/foo/bar.c")       @result{} "c"
(path-sans-extension "/foo/bar.c")  @result{} "/foo/bar"

(path-extension "/foo/bar")         @result{} #f
(path-sans-extension "/foo/bar")    @result{} "/foo/bar"
@end example
@end defun

@defun path-swap-extension path newext
@{@t{file.util}@}
Returns a pathname in which the extension of @var{path} is replaced
by @var{newext}.  If @var{path} doesn't have an extension,
"." and @var{newext} is appended to @var{path}.

If @var{newext} is @code{#f}, it returns @var{path} without extension.

@example
(path-swap-extension "/foo/bar.c" "o")  @result{} "/foo/bar.o"
(path-swap-extension "/foo/bar.c" "")   @result{} "/foo/bar."
(path-swap-extension "/foo/bar.c" #f)   @result{} "/foo/bar"

(path-swap-extension "/foo/bar" "o")  @result{} "/foo/bar.o"
(path-swap-extension "/foo/bar" "")   @result{} "/foo/bar."
(path-swap-extension "/foo/bar" #f)   @result{} "/foo/bar"
@end example
@end defun

@defun find-file-in-paths name :key paths pred extensions
@{@t{file.util}@}
Looks for a file that has name @var{name} in the given list of pathnames
@var{paths} and that satisfies a predicate @var{pred}.  If found,
the absolute pathname of the file is returned.  Otherwise, @code{#f}
is returned.

If @var{name} is an absolute path, only the existence of @var{name}
and whether it satisfies @var{pred} are checked.

The default value of @var{paths} is taken from the environment variable
@code{PATH}, and the default value of @var{pred} is @code{file-is-executable?}
(@pxref{File attribute utilities}).  That is, @code{find-file-in-paths}
searches the named executable file in the command search paths
by default.

@example
(find-file-in-paths "ls")
  @result{} "/bin/ls"

;; @r{example of searching user preference file of my application}
(find-file-in-paths "userpref"
  :paths `(,(expand-path "~/.myapp")
           "/usr/local/share/myapp"
           "/usr/share/myapp")
  :pred  file-is-readable?)
@end example

The @var{extensions} keyword argument may list alternative extensions
added to @var{name}.  For example, the following example searches
not only @file{notepad}, but also @file{notepad.exe} and @file{notepad.com},
in the PATH.  If an alternate name is found,
the returned pathname contains the extension.

@example
(find-file-in-paths "notepad" :extensions '("exe" "com"))
@end example

For each path, the name and the alternative names are checked in order.
That is,
if there are @file{/bin/b.com} and @file{/usr/bin/b.exe} and @var{paths}
is @code{("/bin" "/usr/bin")}, you'll get @file{/bin/b.com} when you
search @file{b} with extensions @code{("exe" "com")}.
@end defun

@defun null-device
@{@t{file.util}@}
Returns a name of the @emph{null} device.
On unix platforms (including cygwin) it returns @code{"/dev/null"},
and on Windows native platforms (including mingw) it returns @code{"NUL"}.
@end defun

@defun console-device
@{@t{file.util}@}
Returns a name of the console device.
On unix platforms (including cygwin) it returns @code{"/dev/tty"},
and on Windows native platforms (including mingw) it returns @code{"CON"}.

This function does not guarantee the device is actually available
to the calling process.
@end defun


@node File attribute utilities, File operations, Pathname utilities, Filesystem utilities
@subsection File attribute utilities
@c NODE ファイル属性ユーティリティ

@defun file-type path :key follow-link?
@defunx file-perm path :key follow-link?
@defunx file-mode path :key follow-link?
@defunx file-ino path :key follow-link?
@defunx file-dev path :key follow-link?
@defunx file-rdev path :key follow-link?
@defunx file-nlink path :key follow-link?
@defunx file-uid path :key follow-link?
@defunx file-gid path :key follow-link?
@defunx file-size path :key follow-link?
@defunx file-atime path :key follow-link?
@defunx file-mtime path :key follow-link?
@defunx file-ctime path :key follow-link?
@{@t{file.util}@}
These functions return the attribute of file/directory specified by
@var{path}.  The attribute name corresponds to the slot name of
@code{<sys-stat>} class (@pxref{File stats}).
If the named path doesn't exist, @code{#f} is returned.

If @var{path} is a symbolic link, these functions queries the
attributes of the file pointed by the link, unless
an optional argument @var{follow-link?} is given and false.

MzScheme and Chicken have @code{file-size}.  Chicken also has
@code{file-modification-time}, which is @code{file-mtime}.
@end defun

@defun file-is-readable? path
@defunx file-is-writable? path
@defunx file-is-executable? path
@{@t{file.util}@}
Returns @code{#t} if @var{path} exists and readable/writable/executable
by the current effective user, respectively.
This API is taken from STk.
@end defun

@defun file-is-symlink? path
@{@t{file.util}@}
Returns @code{#t} if @var{path} exists and a symbolic link.
See also @code{file-is-regular?} and @code{file-is-directory?} in
@ref{File stats}.
@end defun

@defun file-eq? path1 path2
@defunx file-eqv? path1 path2
@defunx file-equal? path1 path2
@{@t{file.util}@}
Compares two files specified by @var{path1} and @var{path2}.
@code{file-eq?} and @code{file-eqv?} checks if @var{path1} and @var{path2}
refers to the identical file, that is, whether they are on the same
device and have the identical inode number.  The only difference is
when the last component of @var{path1} and/or @var{path2} is a symbolic
link, @code{file-eq?} doesn't resolve the link (so compares the links
themselves) while @var{file-eqv?} resolves the link and compares the
files referred by the link(s).

@code{file-equal?} compares @var{path1} and @var{path2} considering their
content, that is, when two are not the identical file in the sense of
@code{file-eqv?}, @code{file-equal?} compares their content and returns
@code{#t} if all the bytes match.

The behavior of @code{file-equal?} is undefined
when @var{path1} and @var{path2} are both directories.
Later, it may be extended to scan the directory contents.
@end defun

@deffn {Generic Function} file-mtime=? f1 f2
@deffnx {Generic Function} file-mtime<? f1 f2
@deffnx {Generic Function} file-mtime<=? f1 f2
@deffnx {Generic Function} file-mtime>? f1 f2
@deffnx {Generic Function} file-mtime>=? f1 f2
@{@t{file.util}@}
Compares file modification time stamps.  There are a bunch of methods defined,
so each argument can be either one of the followings.

@itemize @bullet
@item
String pathname.   The mtime of the specified path is used.
@item
@code{<sys-stat>} object (@pxref{File stats}).
The mtime is taken from the stat structure.
@item
@code{<time>} object.  The time is used as the mtime.
@item
Number.  It is considered as the number of seconds since Unix Epoch, and
used as mtime.
@end itemize

@example
;; @r{compare "foo.c" is newer than "foo.o"}
(file-mtime>? "foo.c" "foo.o")

;; @r{see if "foo.log" is updated within last 24 hours}
(file-mtime>? "foo.c" (- (sys-time) 86400))
@end example
@end deffn

@deffn {Generic Function} file-ctime=? f1 f2
@deffnx {Generic Function} file-atime=? f1 f2
@findex file-ctime<?
@findex file-ctime<=?
@findex file-ctime>?
@findex file-ctime>=?
@findex file-atime<?
@findex file-atime<=?
@findex file-atime>?
@findex file-atime>=?
@{@t{file.util}@}
Same as @code{file-mtime=?}, except these checks file's change time
and access time, respectively.
All the variants of @code{<}, @code{<=}, @code{>}, @code{>=} are also
defined.
@end deffn

@node File operations, Temporary files and directories, File attribute utilities, Filesystem utilities
@subsection File operations
@c NODE ファイル操作

@defun touch-file path :key (time #f) (type #f) (create #t)
@defunx touch-files paths :key (time #f) (type #f) (create #t)
@{@t{file.util}@}
Updates timestamp of @var{path}, or each path in the list @var{paths},
to the current time.  If the specified path
doesn't exist, a new file with size zero is created, unless
the keyword argument @var{create} is @code{#f}.

If the keyword argument @var{time} is given and not @code{#f}, it
must be a nonnegative real number.  It is used as the timestamp value
instead of the current time.

The keyword argument @var{type} can be @code{#f} (default), a symbol
@code{atime} or @code{mtime}.  If it is a symbol, only the access time
or modification time is updated.

Note: @code{touch-files} processes one file at a time, so the timestamp
of each file may not be exactly the same.

These procedures are built on top of the system call
@code{sys-utime} (@pxref{File stats}).
@end defun

@defun copy-file src dst :key if-exists backup-suffix safe keep-timestamp keep-mode follow-link?
@{@t{file.util}@}
Copies file from @var{src} to @var{dst}.  The source file @var{src} must exist.
The behavior when the destination @var{dst} exists varies by the keyword
argument @var{if-exists};

@table @code
@item :error
(Default) Signals an error when @var{dst} exists.
@item :supersede
Replaces @var{dst} to the copy of @var{src}.
@item :backup
Keeps @var{dst} by renaming it.
@item :append
Append the @var{src}'s content to the end of @var{dst}.
@item #f
Doesn't copy and returns @code{#f} when @var{dst} exists.
@end table

@code{Copy-file} returns @code{#t} after completion.

If @var{src} is a symbolic link, @code{copy-file} follows the
symlink and copies the actual content by default.  An error
is raised if @var{src} is a dangling symlink.

Giving @code{#f} to the keyword argument @var{follow-link?}
makes @code{copy-file} to copy the link itself.
It is possible that @var{src} is a dangling
symlink in this case.

If @var{if-exists} is @code{:backup}, the keyword argument @var{backup-suffix}
specifies the suffix attached to the @var{dst} to be renamed.
The default value is @code{".orig"}.

By default, @code{copy-file} starts copying to @var{dst} directly.
However, if the keyword argument @var{safe} is a true value,
it copies the file to a temporary file in the same directory of @var{dst},
then renames it to @var{dst} when copy is completed.
(When @var{safe} is true and @var{if-exists} is @code{:append},
we first copy the content of @var{dst} to a temporary file if @var{dst}
exists, appends the content of @var{src}, then renames the result to @var{dst}).
If copy is interrupted for some reason, the filesystem is "rolled back"
properly.


If the keyword argument @var{keep-timestamp} is true, @code{copy-file}
sets the destination's timestamp to the same as the source's timestamp
after copying.

If the keyword argument @var{keep-mode} is true, the destination file's
permission bits are set to the same as the source file's.  If it is false
(default), the destination file's permission remains the same if
the destination already exists and the @var{safe} argument is false,
otherwise it becomes @code{#o666} masked by umask settings.
@end defun

@c @defun copy-files files dstdir :key if-exists backup-suffix safe keep-timestamp keep-mode follow-link?
@c @c EN
@c Copies each file in a list @var{files} to the destination @var{dstdir}, which
@c must be an existing directory.  The keyword arguments are passed
@c to @code{copy-file}.
@c @c JP
@c リスト@var{files}中の各ファイルをディレクトリに@var{dstdir}にコピーします。
@c @var{dstdir}は既に存在しなければなりません。
@c キーワード引数はそのまま@code{copy-file}に渡されます。
@c @c COMMON
@c @end defun

@defun move-file src dst :key if-exists backup-suffix
@{@t{file.util}@}
Moves file @var{src} to @var{dst}.   The source @var{src} must exist.
The behavior when @var{dst} exists varies by the keyword argument
@var{if-exists}, as follows.
@table @code
@item :error
(Default) Signals an error when @var{dst} exists.
@item :supersede
Replaces @var{dst} by @code{src}.
@item :backup
Keeps @var{dst} by renaming it.
@item #f
Doesn't move and returns @code{#f} when @var{dst} exists.
@end table

@code{Move-file} returns @code{#t} after completion.

If @var{if-exists} is @code{:backup}, the keyword argument @var{backup-suffix}
specifies the suffix attached to the @var{dst} to be renamed.
The default value is @code{".orig"}.

The file @var{src} and @var{dst} can be on the different filesystem.
In such a case, @code{move-file} first copies @var{src} to the
temporary file on the same directory as @var{dst}, then renames
it to @var{dst}, then removes @var{src}.
@end defun

@c @defun move-files files dstdir :key if-exists backup-suffix
@c @c EN
@c Moves each file in a list @var{files} to @var{dstdir},
@c which must be an existing directory.  Keyword arguments
@c are passed to @code{move-file}.
@c @c JP
@c リスト@var{files}中の各ファイルをディレクトリ@var{dstdir}に移動します。
@c @var{dstdir}は既に存在しなければなりません。
@c キーワード引数はそのまま@code{move-file}に渡されます。
@c @c COMMON
@c @end defun

@defun remove-file filename
@defunx delete-file filename
[R7RS file]
@{@t{file.util}@}
Removes the named file.  An error is signalled if @var{filename}
does not exist, is a directory, or cannot be deleted with other
reasons such as permissions.
R7RS defines @code{delete-file}.

Compare with @code{sys-unlink} (@pxref{Directory manipulation}),
which doesn't raise an error when the named file doesn't exist.
@end defun

@defun remove-files paths
@defunx delete-files paths
@{@t{file.util}@}
Removes each path in a list @var{paths}.  If the path is
a file, it is @code{unlink}ed.  If it is a directory,
its contents are recursively removed by @code{remove-directory*}.
If the path doesn't exist, it is simply ignored.

@code{delete-files} is just an alias of @code{remove-files}.
@end defun


@defun file->string filename options @dots{}
@defunx file->list reader filename options @dots{}
@defunx file->string-list filename options @dots{}
@defunx file->sexp-list filename options @dots{}
@{@t{file.util}@}
Convenience procedures to read from a file @var{filename}.
They first open the named file, then call @code{port->string},
@code{port->list}, @code{port->string-list} and @code{port->sexp-list}
on the opened file, respectively.  (@pxref{Input utility functions}).
The file is closed if all the content is read or an error is
signaled during reading.

Those procedures take the same keyword arguments as
@code{call-with-input-file}.
When the named file doesn't exist, the behavior depends on
@var{:if-does-not-exist} keyword argument---an error is signaled
if it is @code{:error}, and @code{#f} is returned if the argument is
@code{#f}.
@end defun

@defun string->file filename string options @dots{}
@defunx list->file writer filename lis options @dots{}
@defunx string-list->file filename lis options @dots{}
@defunx sexp-list->file filenme lis options @dots{}
@{@t{file.util}@}
Opposite of @code{file->string} etc.  They are convenient
to quickly write out things into a file.

NB: The name @code{string->file} etc. might suggest they would take the
object to be written as the first argument.  We decided to put @var{filename}
first, since in the situations where these procedures are used,
it is more likely that one want to write literal data, which would be
bigger than the filename itself.

The options part is passed to @code{call-with-output-file} as is.
For example, the following code appends the text when @file{foo.txt}
already exists:

@example
(string->file "foo.txt" "New text to append\n"
              :if-exists :append)
@end example

The @code{list->file} takes @var{writer} argument, which is a procedure
that receives two arguments, an element from the list @var{lis}, and an
output port.  It should write out the element to the port in a suitable
way.  The @code{string-list->file} and @code{sexp-list->file} are
specialized versions of @code{list->file}, where @code{string-list->file}
uses @code{(^[s p] (display s p) (newline p))} as @var{writer},
and @code{sexp-list->file} uses 
@code{(^[s p] (write s p) (newline p))} as @var{writer}.
@end defun


@node Temporary files and directories, Lock files, File operations, Filesystem utilities
@subsection Temporary files and directories
@c NODE 一時ファイルとディレクトリ

@deffn {Parameter} temporary-directory
@{@t{file.util}@}
A parameter that keeps the name of the directory that can be used
to create a temporary files.   The default value is
the one returned from @code{sys-tmpdir} (@pxref{Pathnames}).
The difference of @code{sys-tmpdir} is that, since this is a parameter,
it can be overridden by application during execution.
Libraries are recommended to use this instead of @code{sys-tmpdir}
for greater flexibility.
@end deffn

@defun call-with-temporary-file proc :key directory prefix
@{@t{file.util}@}
Creates a temporary file with a unique name and opens it for output,
then calls @var{proc} with the output port and the temporary file's name.
The temporary file is removed after either @var{proc} returns
or raises an uncaught error.
Returns the value(s) @var{proc} returns.

The temporary file is created in the directory @var{directory},
with the name @var{prefix} followed by several random alphanumeric characters.
When omitted, the value of @code{(temporary-directory)} is used
for @var{directory}, and @code{"gtemp"} for @var{prefix}.

The name passed to @var{proc} consists of @var{directory} and
the file's name.  So whether the name is absolute or relative pathname
depends on the value of @var{directory}.

@example
(call-with-temporary-file (^[_ name] name)
 @result{} @r{Something like "/tmp/gtemp4dSpMh"}
@end example

You can keep the output file by renaming it in @var{proc}.  But if doing so,
make sure to specify @var{directory} so that the temporary file
is created in the same directory as the final output; rename
may not work across filesystems.

Internally, it calls @code{sys-mkstemp} to create a unique file.
@xref{Directory manipulation}, for the details.
@end defun

@defun call-with-temporary-directory proc :key directory prefix
@{@t{file.util}@}
Creates a temporary directory with unique name,
then calls @var{proc} with the name.
The temporary directory and its contents are removed
after either @var{proc} returns
or raises an uncaught error.
Returns the value(s) @var{proc} returns.

The temporary directory is created in the directory @var{directory},
with the name @var{prefix} followed by several random alphanumeric characters.
When omitted, the value of @code{(temporary-directory)} is used
for @var{directory}, and @code{"gtemp"} for @var{prefix}.

The name passed to @var{proc} consists of @var{directory} and
the directory name.  So whether the name is absolute or relative pathname
depends on the value of @var{directory}.

Internally, it calls @code{sys-mkdtemp} to create a unique file.
@xref{Directory manipulation}, for the details.
@end defun

@node Lock files,  , Temporary files and directories, Filesystem utilities
@subsection Lock files
@c NODE ロックファイル

Exclusivity of creating files or directories is often used
for inter-process locking.   The following procedure provides
a packaged interface for it.

@defun with-lock-file lock-name thunk :key type retry-interval @
                      retry-limit secondary-lock-name retry2-interval @
                      retry2-limit perms abandon-timeout
@{@t{file.util}@}
Exclusively creates a file or a directory (@emph{lock file})
with @var{lock-name}, then executes @var{thunk}.
After @var{thunk} returns, or an error is thrown in it,
the lock file is removed.  When @var{thunk} returns normally,
its return values become the return values of @code{with-lock-file}.

If the lock file already exists, @code{with-lock-file} waits and retries
getting the lock until timeout reaches.  It can be configured by
the keyword arguments.

There's a chance that @code{with-lock-file} leaves the lock file
when it gets a serious error situation and doesn't have the opportunity
to clean up.  You can allow @code{with-lock-file} to @emph{steal}
the lock if its timestamp is too old; say, if you know that the
applications usually locks just for seconds, and you find the lock
file is 10 minutes old, then it's likely that the previous
process was terminated abruptly and couldn't clean it up.
You can also configure this behavior by the keyword arguments.

Internally, @emph{two} lock files are used to implement this
stealing behavior safely.  The creation and removal of the primary
lock file (named by @var{lock-name} argument) are guarded by
the secondary lock file (named by @var{secondary-lock-file} argument,
defaulted by @code{.2} suffix attached to @var{lock-name}).
The secondary lock prevents more than one process steals
the same primary lock file simultaneously.

The secondary lock is acquired for a very short period so there's
much less chance to be left behind by abnormal terminations.
If it happens, however, we just give up; we don't steal the
secondary lock.

If @code{with-lock-file} couldn't get a lock before timeout,
a @code{<lock-file-failure>} condition is thrown.

Here's a list of keyword arguments.

@table @var
@item type

It can be either one of the symbols @code{file} or @code{directory}.

If it is @code{file}, we use a lock file, relying on the @code{O_EXCL}
exclusive creation flag of @code{open(2)}.
This is the default value.
It works for most platforms;
however, some NFS implementation may not implement the exclusive
semantics properly.   

If it is @code{directory}, we use a lock directory, relying on the
atomicity of @code{mkdir(2)}.  It should work for any platforms,
but it may be slower than @code{file}.

@item retry-interval
@itemx retry-limit

Accepts a nonnegative real number that specifies either
the interval to attempt to acquire the primary lock, or the maximum
time we should keep retrying, respectively, in seconds.
The default value is 1 second interval and 10 second limit.
To prevent retrying, give 0 to @var{retry-limit}.

@item secondary-lock-name

The name of the secondary lock file (or directory).  If omitted,
@var{lock-name} with a suffix @code{.2} attached is used.
Note: The secondary lock name must be agreed on all programs that
locks the same (primary) lock file.  I recommend to leave this
to the default unless there's a good reason to do otherwise.

@item retry2-interval
@itemx retry2-limit

Like @var{retry-interval} and @var{retry-limit}, but these specify
interval and timeout for the secondary lock file.  The possibility
of secondary lock file collision is usually pretty low, so
you would hardly need to tweak these.  The default values are
1 second interval and 10 second limit.

@item perms

Specify the permission bitmask of the lock file or directory,
in a nonnegative exact integer.  The default is @code{#o644} for
a lock file and @code{#o755} for a lock directory.

Note that to control who can acquire/release/steal the lock,
what matters is
the permission of the directory in which the lock file/directory,
not the permission of the lock file/directory itself.

@item abandon-timeout

Specifies the period in seconds in a nonnegative real number.
If the primary lock file is
older than that, @code{with-lock-file} steals the lock.
To prevent stealing, give @code{#f} to this argument.
The default value is 600 seconds.

@end table

@end defun

@deftp {Condition type} <lock-file-failure>
@{@t{file.util}@}
A condition indicating that @code{with-lock-file} couldn't
obtain the lock.  Inherits @code{<error>}.

@defivar <lock-file-failure> lock-file-name
The primary lock file name.
@end defivar
@end deftp

Gauche also provides OS-supported file locking feature,
@code{fcntl} lock, via @code{gauche.fcntl} module.
Whether you want to use @code{fcntl} lock or @code{with-lock-file}
will depend on your application.

These are the advantages of the @code{fcntl} lock:

@itemize
@item
The lock is removed when the process dies without explicitly unlocking it.
@item
You can directly lock the file you're touching.
@item
You can lock a part of a file.
@item
You can have shared (read) and exclusive (write) locks.
@end itemize

In common situations, probably the most handy property is the
first one; you don't need to worry about leaving lock behind
unexpected process termination.

However, there are a couple of shortcomings in @code{fcntl} locks.

@itemize
@item
It is not guaranteed to work across different platforms,
and/or NFS-mounted filesystems.
@item
The lock is per-process, per-file, and non-recursive.
If you have a lock in a file,
then calls a library that also locks the file, the lock always
succeeds.  Worse, if the library unlocks the file,
the lock is completely removed, while the caller doesn't know
about it.  It also means that, in order to prevent multiple threads
in a process from accessing the same file, you have to use
mutex along the fcntl lock.
@end itemize

Especially because of the second point, it is very difficult
to use @code{fcntl} lock unless you have total control over and knowledge
of the entire application.
It is ok to use the @code{fcntl} lock by the application code to lock
the application-specific file.
Library developers have difficulty, however, to make sure any potential
user of the library won't try to lock the same file as the library tries
to lock (usually it's impossible).

@c ----------------------------------------------------------------------
@node Mathematic constants, Mersenne-Twister random number generator, Filesystem utilities, Library modules - Utilities
@section @code{math.const} - Mathematic constants
@c NODE 定数, @code{math.const} - 定数

@deftp {Module} math.const
@mdindex math.const
This module defines several commonly-used mathematic constants.
@end deftp

@defvr {Constant} pi
@defvrx {Constant} pi/2
@defvrx {Constant} pi/4
@defvrx {Constant} pi/180
@defvrx {Constant} 1/pi
@defvrx {Constant} 180/pi
@{@t{math.const}@}
Bound to pi, pi/2, pi/4, pi/180, 1/pi and 180/pi, respectively.
@end defvr

@defvr {Constant} e
@{@t{math.const}@}
Napier's constant.
@end defvr

@c ----------------------------------------------------------------------
@node Mersenne-Twister random number generator, Prime numbers, Mathematic constants, Library modules - Utilities
@section @code{math.mt-random} - Mersenne Twister Random number generator
@c NODE Mersenne Twister乱数発生器, @code{math.mt-random} - Mersenne Twister乱数発生器

@deftp {Module} math.mt-random
@mdindex math.mt-random
Provides a pseudo random number generator (RNG) based on
"Mersenne Twister" algorithm developed by Makoto Matsumoto and
Takuji Nishimura.   It is fast, and has huge period of 2^19937-1.
See @url{https://dl.acm.org/citation.cfm?id=272995}, for details about the algorithm.

For typical use cases of random number generators,
we recommend to use @code{srfi-27} which is implemented
on top of this module and provides portable API.
You should use this module directly only when you need
functions that aren't available through @code{srfi-27}.
@end deftp

@deftp {Class} <mersenne-twister>
@clindex mersenne-twister
@{@t{math.mt-random}@}
A class to encapsulate the state of Mersenne Twister RNG.
Each instance of this class has its own state, and can be used
as an independent source of random bits if initialized
by individual seed.

The random seed value can be given at the instantiation time
by @code{:seed} initialization argument, or by using
@code{mt-random-set-seed!} described below.

@example
(define m (make <mersenne-twister> :seed (sys-time)))

(mt-random-real m) @result{} 0.10284287848537865
(mt-random-real m) @result{} 0.463227748348805
(mt-random-real m) @result{} 0.8628500643709712
@dots{}
@end example
@end deftp

@defun mt-random-set-seed! mt seed
@{@t{math.mt-random}@}
Sets random seed value @var{seed} to the Mersenne Twister RNG (MTRNG) @var{mt}.
@var{Seed} can be an arbitrary positive exact integer,
or arbitrary length of u32vector (@pxref{Homogeneous vectors}).
If it is a u32vector, up to 624 elements are used for initialization.

Internally, MTRNG keeps its state in array of 32-bit integers.  When a fixnum
is given, its lower 32bit is used to generate a linear congruential series
to fill the state space.  If you do so, there is an algorithm
that only samples a couple of result from MTRNG to calculate the original
seed value, hence can predict entire sequence.  If you want the random
sequence harder to predict, prepare your own u32vector seed filled with
high-entroby bits. 

Note that Mersenne Twister is never intended for cryptograhpy, you shouldn't
use it for security-sensitive purposes.

NB: Up to 0.9.9, when @var{seed} is a bignum, we roll our own way to
fold it in 32bit integer and then called Mersenne-Twister's initialization
function.  It loses the entropy, so we changed it and now all the bits
in the bignum is used for the seed.
@end defun

@defun mt-random-get-state mt
@defunx mt-random-set-state! mt state
@{@t{math.mt-random}@}
Retrieves and reinstalls the state of Mersenne Twister RNG @var{mt}.
The state is represented by a u32vector of 625 elements.  The state
can be stored elsewhere, and then restored to an instance of
@code{<mersenne-twister>} to continue to generate the pseudo random
sequence.
@end defun

@defun mt-random-real mt
@defunx mt-random-real0 mt
@{@t{math.mt-random}@}
Returns a random real number between 0.0 and 1.0.
1.0 is not included in the range.  @code{Mt-random-real} doesn't
include 0.0 either, while @code{mt-random-real0} does.
Excluding 0.0 is from the draft SRFI-27.
@end defun

@defun mt-random-integer mt range
@{@t{math.mt-random}@}
Returns a random exact positive integer between 0 and @var{range}-1.
@var{Range} can be any positive exact integer.
@end defun

@defun mt-random-fill-u32vector! mt u32vector
@defunx mt-random-fill-f32vector! mt f32vector
@defunx mt-random-fill-f64vector! mt f64vector
@{@t{math.mt-random}@}
Fills the given uniform vector by the random numbers.
For @code{mt-random-fill-u32vector!}, the elements are filled
by exact positive integers between 0 and 2^32-1.
For @code{mt-random-fill-f32vector!} and
@code{mt-random-fill-f64vector!}, it is filled by an inexact
real number between 0.0 and 1.0, exclusive.

If you need a bunch of random numbers at once, these are much
faster than getting one by one.
@end defun

@c ----------------------------------------------------------------------
@node Prime numbers, Windows support, Mersenne-Twister random number generator, Library modules - Utilities
@section @code{math.prime} - Prime numbers
@c NODE 素数, @code{math.prime} - 素数

@deftp {Module} math.prime
@mdindex math.prime
This module provides utilities related to prime numbers.
@end deftp

@subheading Sequence of prime numbers

@defvar *primes*
@{@t{math.prime}@}
An infinite lazy sequence of primes.

@example
;; show 10 prime numbers from 100-th one.
(take (drop *primes* 100) 10)
 @result{} (547 557 563 569 571 577 587 593 599 601)
@end example
@end defvar

@defun reset-primes
@{@t{math.prime}@}
Once you take a very large prime out of @code{*primes*}, all primes
before that has been calculated remains in memory, since the
head of sequence is held in @code{*primes*}.  Sometimes you know
you need no more prime numbers and you wish those calculated ones
to be garbage-collected.  Calling @code{reset-primes} rebinds
@code{*primes*} to unrealized lazy sequence, allowing the previously
realized primes to be GCed.
@end defun

@defun primes
@{@t{math.prime}@}
Returns a fresh lazy sequence of primes.  It is useful when
you need certain primes in a short period of time---if you don't keep
a reference to the head of the returned sequence, it will be garbage
collected after you've done with the primes.
(Note that calculation of a prime number needs the
sequence of primes from the beginning, 
so even if your code only keep a reference
in the middle of the sequence, the entire sequence will be kept
in the thunk within the lazy sequence---you have to release all
references in order to make the sequence GCed.)

On the other hand,
each sequence returned by @code{primes} are realized individually,
duplicating calculation.  

The rule of thumb is---if you use primes repeatedly throughout
the program, just use @code{*primes*} and you'll save calculation.
If you need primes one-shot, call @code{primes} and abandon it
and you'll save space.
@end defun

@subheading Testing primality

@defun small-prime? n
@{@t{math.prime}@}
For relatively small positive integers 
(below @code{*small-prime-bound*}, to be specific), this procedure
determines if the input is prime or not, quickly and deterministically.
If @var{n} is on or above the bound, this procedure returns @code{#f}.

This can be used to quickly filter out known primes; it never returns
@code{#t} on composite numbers (while it may return @code{#f} on
large prime numbers).
Miller-Rabin test below can tell if the input is composite for sure,
but it may return @code{#t} on some composite numbers.
@end defun

@defvar *small-prime-bound*
@{@t{math.prime}@}
For all positive integers below this value
(slightly above 3.4e14 in the current implementation),
@code{small-prime?} can determines whether it is a prime or not.
@end defvar


@defun miller-rabin-prime? n :key num-tests random-integer
@{@t{math.prime}@}
Check if an exact integer @var{n} is a prime number, using
probabilistic Miller-Rabin algorithm (@var{n} must be greater than 1).
If this procedure returns @code{#f},
@var{n} is a composite number.  If this procedure returns @code{#t},
@var{n} is @emph{likely} a prime, but there's a small probability
that it is a false positive.

Note that if @var{n} is smaller than a certain number
(@code{*small-prime-bound*}), the algorithm is
deterministic; if it returns @code{#t}, @var{n} is certainly a prime.

If @var{n} is greater than or equal to 
@code{*small-prime-bound*},
we use a probabilistic test.  We choosing random base integer
to perform Miller-Rabin test up to 7 times by default.
You can change the number of tests by the keyword argument
@var{num-tests}.  The error probability
(to return @code{#t} for a composite number)
is at most @code{(expt 4 (- num-tests))}.

For a probabilistic test, @code{miller-rabin-prime?} uses
its own fixed random seed by default.  We chose fixed seed
so that the behavior can be reproducible.  To change the random
sequence, you can provide your own random integer generator
to the @var{random-integer} keyword argument.   It must be
a procedure that takes a positive integer @var{k} and returns
a random integer from 0 to @var{k-1}, including.
@end defun

@defun bpsw-prime? n
@{@t{math.prime}@}
Check if an exact integer @var{n} is a prime number, using
Baillie-PSW primality test
(@url{http://www.trnicely.net/misc/bpsw.html}).   It is deterministic,
and returns the definitive answer below 2^64 (around 1.8e19).
For larger integers this can return @code{#t} on a composite number,
although such number hasn't been found yet.  This never returns @code{#f}
on a prime number.

This is slower than Miller-Rabin but fast enough for casual use,
so it is handy when you want a definitive answer below the above range.
@end defun

@subheading Factorization

@defun naive-factorize n :optional divisor-limit
@{@t{math.prime}@}
Factorize a positive exact integer @var{n} by trying to divide it with
all primes up to @code{(sqrt n)}.  Returns a list of prime factors
(each of which is equal to or greater than 2),
smaller ones first.

@example
(naive-factorize 142857)
  @result{} (3 3 3 11 13 37)
@end example

Note that @code{(naive-factorize 1)} is @code{()}.

Although this is pretty naive method, this works well as far as
any of @var{n}'s factors are up to the order of around @code{1e7}.
For example, the following example runs in about 0.4sec on 2.4GHz Core2
machine.
(The first time will take about 1.3sec to realize lazy prime sequences.)

@example
(naive-factorize 3644357367494986671013))
  @result{} (10670053 10670053 32010157)
@end example

Of course, if @var{n} includes any factors above that order,
the performance becomes abysmal.   So it is better to use this
procedure below 1e14 or so.

Alternatively, you can give @var{divisor-limit} argument that specifies
the upper bound of the prime number to be tried.  If it is given,
@code{naive-factorize} leaves a factor @var{f} as is if it can't be
divided by any primes less than or equal to @var{divisor-limit}.
So, the last element of the returned list may be composite number.
This is handy to exclude trivial factors before applying more sophisticated
factorizing algorithms.

@example
(naive-factorize 825877877739 1000)
  @result{} (3 43 6402154091)

;; whereas
(naive-factorize 825877877739)
  @result{} (3 43 4591 1394501)
@end example

The procedure also memoizes the results on smaller @var{n} to make
things faster.
@end defun

@defun mc-factorize n
@{@t{math.prime}@}
Factorize a positive exact integer @var{n} using the algorithm
described in 
R. P. Brent, An improved Monte Carlo factorization algorithm, BIT 20 (1980), 176-184. @url{http://maths-people.anu.edu.au/~brent/pub/pub051.html}.

This one is capable to handle much larger range than
@code{naive-factorize}, somewhere around 1e20 or so.

Since this method is probabilistic, the execution time may vary
on the same @var{n}.  But it will always return the definitive
results as far as every prime factor of @var{n} is smaller than 2^64.

At this moment, if @var{n} contains a prime factor greater than
2^64, this routine would keep trying factorizing it forever.
Practical applications should have some means to interrupt the
function and give it up after some time bounds.
This will be addressed once we have deterministic primality test.
@end defun


@subheading Miscellaneous

@defun jacobi a n
@{@t{math.prime}@}
Calculates Jacobi symbol @code{(@var{a}/@var{n})}
(@url{http://en.wikipedia.org/wiki/Jacobi_symbol}).
@end defun

@defun totient n
@{@t{math.prime}@}
Euler's totient function of nonnegative integer @var{n}.

The current implementation relies on @code{mc-factorize} above,
so it may take very long if @var{n} contains large prime factors.
@end defun


@c ----------------------------------------------------------------------
@node Windows support, PEG parser combinators, Prime numbers, Library modules - Utilities
@section @code{os.windows} - Windows support
@c NODE Windowsのサポート, @code{os.windows} - Windowsのサポート

@deftp {Module} os.windows
@mdindex os.windows
This module is only available on Windows-native Gauche, and
provides Windows-specific procedures.
You can check @code{gauche.os.windows} feature with
 @code{cond-expand} macro (@pxref{Feature conditional})
to conditionalize windows-specific code.

@example
(cond-expand
  [gauche.os.windows
   (use os.windows)
   ... Windows-specific code ...]
  [else
   ... Unix code ...])
@end example

Currently there aren't enough procedures provided here, but
eventually we want to support simple scripting on Windows.

Unless otherwise noted,
when Windows API returns an error value, a @code{<system-error>} condition
is thrown.
@end deftp

@menu
* Windows dialogs::
* Windows console API::
@end menu

@node Windows dialogs, Windows console API, Windows support, Windows support
@subsection Windows dialogs

Currenly we only have MessageBox API.

@defun sys-message-box window message :optional caption flags
@{@t{os.windows}@}
Calls Windows MessageBox API.   The @var{window} argument should
be a handle for a window, or @code{#f}; at the moment we don't
provide any API that retrieves window handles, so you should always
pass @code{#f} here.  The @var{message} argument takes a string
for the content of the message box.  Optional @var{caption}
argument takes a string to be used in the window title.

The @var{flags} argument is an integer; it should be @code{logior}
of values from one or more of the following groups.  See the
Windows reference manual for the details.

@table @emph
@item Buttons
@code{MB_ABORTRETRYIGNORE},
@code{MB_CANCELTRYCONTINUE},
@code{MB_HELP},
@code{MB_OK} (default),
@code{MB_OKCANCEL},
@code{MB_RETRYCANCEL},
@code{MB_YESNO},
@code{MB_YESNOCANCEL}
@item Icon
Default is no icon.  Possible values:
@code{MB_ICONEXCLAMATION},
@code{MB_ICONWARNING},
@code{MB_ICONINFORMATION},
@code{MB_ICONASTERISK},
@code{MB_ICONQUESTION},
@code{MB_ICONSTOP},
@code{MB_ICONERROR},
@code{MB_ICONHAND}
@item Default button
@code{MB_DEFBUTTON1} (default),
@code{MB_DEFBUTTON2},
@code{MB_DEFBUTTON3},
@code{MB_DEFBUTTON4}
@item Modality
@code{MB_APPLMODAL} (default),
@code{MB_SYSTEMMODAL},
@code{MB_TASKMODAL}
@item Other options
@code{MB_DEFAULT_DESKTOP_ONLY},
@code{MB_RIGHT},
@code{MB_RTLREADING},
@code{MB_SETFOREGROUND},
@code{MB_TOPMOST},
@code{MB_SERVICE_NOTIFICATION}
@end table

Return value is one of the following integer constants,
indicating which button is pressed:
@code{IDABORT},
@code{IDCANCEL},
@code{IDCONTINUE},
@code{IDIGNORE},
@code{IDNO},
@code{IDOK},
@code{IDRETRY},
@code{IDTRYAGAIN}, or
@code{IDYES}
@end defun

@node Windows console API,  , Windows dialogs, Windows support
@subsection Windows console API

Most of these procedures corresponds to Windows Console API one-to-one.
See the Windows reference for the detail description of what each API does.

@subsubheading Attaching and detaching

@defun sys-alloc-console
@defunx sys-free-console
[Windows]
@{@t{os.windows}@}
Calls @code{AllocConsole} and @code{FreeConsole}, respectively.
@end defun

@defun sys-generate-console-ctrl-event event pgid
[Windows]
@{@t{os.windows}@}
@end defun

@defvr {Constant} CTRL_C_EVENT
@defvrx {Constant} CTRL_BREAK_EVENT
[Windows]
@{@t{os.windows}@}
@end defvr

@subsubheading Console codepage

@defun sys-get-console-cp
@defunx sys-get-console-output-cp
@defunx sys-set-console-cp codepage
@defunx sys-set-console-output-cp codepage
[Windows]
@{@t{os.windows}@}
@end defun

@defun sys-get-console-cursor-info handle
@defunx sys-set-console-cursor-info handle size visible
[Windows]
@{@t{os.windows}@}
@end defun

@defun sys-set-console-cursor-position handle x y
[Windows]
@{@t{os.windows}@}
@end defun

@subsubheading Console mode

@defun sys-get-console-mode handle
@defunx sys-set-console-mode handle mode
[Windows]
@{@t{os.windows}@}
@end defun

@defvr {Constant} ENABLE_LINE_INPUT
@defvrx {Constant} ENABLE_ECHO_INPUT
@defvrx {Constant} ENABLE_PROCESSED_INPUT
@defvrx {Constant} ENABLE_WINDOW_INPUT
@defvrx {Constant} ENABLE_MOUSE_INPUT
@defvrx {Constant} ENABLE_PROCESSED_OUTPUT
@defvrx {Constant} ENABLE_WRAP_AT_EOL_OUTPUT
[Windows]
@{@t{os.windows}@}
@end defvr

@subsubheading Screen buffer

@defun sys-create-console-screen-buffer desired-access share-mode inheritable
[Windows]
@{@t{os.windows}@}
@end defun

@defvr {Constant} GENERIC_READ
@defvrx {Constant} GENERIC_WRITE
[Windows]
@{@t{os.windows}@}
@end defvr

@defvr {Constant} FILE_SHARE_READ
@defvrx {Constant} FILE_SHARE_WRITE
[Windows]
@{@t{os.windows}@}
@end defvr

@defun sys-set-console-active-screen-buffer handle
[Windows]
@{@t{os.windows}@}
@end defun

@defun sys-scroll-console-screen-buffer handle scroll-rectangle clip-rectangle x y fill
[Windows]
@{@t{os.windows}@}
@end defun

@deftp {Class} <win:console-screen-buffer-info>
@clindex win:console-screen-buffer-info
[Windows]
@{@t{os.windows}@}

@defivar {<win:console-screen-buffer-info>} size.x
@defivarx {<win:console-screen-buffer-info>} size.y
@end defivar

@defivar {<win:console-screen-buffer-info>} cursor-position.x
@defivarx {<win:console-screen-buffer-info>} cursor-position.y
@end defivar

@defivar {<win:console-screen-buffer-info>} attributes
@end defivar

@defivar {<win:console-screen-buffer-info>} window.left
@defivarx {<win:console-screen-buffer-info>} window.top
@defivarx {<win:console-screen-buffer-info>} window.right
@defivarx {<win:console-screen-buffer-info>} window.bottom
@end defivar

@defivar {<win:console-screen-buffer-info>} maximum-window-size.x
@defivarx {<win:console-screen-buffer-info>} maximum-window-size.y
@end defivar

@end deftp

@defvr {Constant} FOREGROUND_BLUE
@defvrx {Constant} FOREGROUND_GREEN
@defvrx {Constant} FOREGROUND_RED
@defvrx {Constant} FOREGROUND_INTENSITY
@defvrx {Constant} BACKGROUND_BLUE
@defvrx {Constant} BACKGROUND_GREEN
@defvrx {Constant} BACKGROUND_RED
@defvrx {Constant} BACKGROUND_INTENSITY
[Windows]
@{@t{os.windows}@}
@end defvr

@defun sys-get-console-screen-buffer-info handle
[Windows]
@{@t{os.windows}@}
@end defun

@defun sys-get-largest-console-window-size handle
[Windows]
@{@t{os.windows}@}
@end defun

@defun sys-set-screen-buffer-size handle x y
[Windows]
@{@t{os.windows}@}
@end defun

@subsubheading Console input/output

@deftp {Class} <win:input-record>
@clindex win:input-record
[Windows]
@{@t{os.windows}@}

@defivar {<win:input-record>} event-type
@end defivar

@defivar {<win:input-record>} key.down
@defivarx {<win:input-record>} key.repeat-count
@defivarx {<win:input-record>} key.virtual-key-code
@defivarx {<win:input-record>} key.virtual-scan-code
@defivarx {<win:input-record>} key.unicode-char
@defivarx {<win:input-record>} key.ascii-char
@defivarx {<win:input-record>} key.control-key-state
@end defivar

@defivar {<win:input-record>} mouse.x
@defivarx {<win:input-record>} mouse.y
@defivarx {<win:input-record>} mouse.button-state
@defivarx {<win:input-record>} mouse.control-key-state
@defivarx {<win:input-record>} mouse.event-flags
@end defivar

@defivar {<win:input-record>} window-buffer-size.x
@defivarx {<win:input-record>} window-buffer-size.y
@end defivar

@defivar {<win:input-record>} menu.command-id
@end defivar

@defivar {<win:input-record>} focus.set-focus
@end defivar

@end deftp

@defun sys-get-number-of-console-input-events handle
[Windows]
@{@t{os.windows}@}
@end defun

@defun sys-get-number-of-console-mouse-buttons
[Windows]
@{@t{os.windows}@}
@end defun

@defun sys-peek-console-input handle
@defunx sys-read-console-input handle
[Windows]
@{@t{os.windows}@}
@end defun

@defun sys-read-console handle buf
[Windows]
@{@t{os.windows}@}
@end defun

@defun sys-read-console-output handle buf w h x y region
[Windows]
@{@t{os.windows}@}
@end defun

@defun sys-read-console-output-attribute handle buf x y
[Windows]
@{@t{os.windows}@}
@end defun

@defun sys-read-console-output-character handle len x y
[Windows]
@{@t{os.windows}@}
@end defun

@defun sys-set-console-text-attribute handle attr
[Windows]
@{@t{os.windows}@}
@end defun

@defun sys-set-console-window-info handle absolute window
[Windows]
@{@t{os.windows}@}
@end defun

@defun sys-write-console handle string
[Windows]
@{@t{os.windows}@}
@end defun

@defun sys-write-console-output-character handle string x y
[Windows]
@{@t{os.windows}@}
@end defun

@defun sys-fill-console-output-character handle char len x y
[Windows]
@{@t{os.windows}@}
@end defun

@defun sys-fill-console-output-attribute handle attr len x y
[Windows]
@{@t{os.windows}@}
@end defun

@defun sys-flush-console-input-buffer handle
[Windows]
@{@t{os.windows}@}
@end defun

@defun sys-get-console-title
[Windows]
@{@t{os.windows}@}
@end defun

@defun sys-set-console-title string
[Windows]
@{@t{os.windows}@}
@end defun

@subsubheading Standard handles

@defun sys-get-std-handle which
@defunx sys-set-std-handle which handle
[Windows]
@{@t{os.windows}@}
@end defun

@defvr {Constant} STD_INPUT_HANDLE
@defvrx {Constant} STD_OUTPUT_HANDLE
@defvrx {Constant} STD_ERROR_HANDLE
[Windows]
@{@t{os.windows}@}
@end defvr


@c ----------------------------------------------------------------------
@node PEG parser combinators, RFC822 message parsing, Windows support, Library modules - Utilities
@section @code{parser.peg} - PEG parser combinators
@c NODE PEGパーザコンビネータ, @code{parser.peg} - PEGパーザコンビネータ

@deftp {Module} parser.peg
@mdindex parser.peg
This module implements a parser combinator library
to build parsers based on Parsing Expression Grammar, or PEG.

PEG is a @emph{formal grammar} to define a language, like regular
expressions or context-free grammars.
An interesting characteristic of PEG is that it can
be directly mapped to a recursive decent parser, which is exactly
what this library does---each production rule is a Scheme expression
that takes parsers and returns a combined parser.  One advantage of
this approach is that you can freely mix ordinary Scheme code
within the parser, that is, there's no special ``parser description
language'' distinct from the base Scheme language, nor you need to
run separate tools like parser generators to obtain a runnable parser code.

Although PEG can directly parse the character string, the parser
combinators are not tied to it.  In fact, most of the combinators
work transparently for any
sequence of tokens, where the exact meanings of tokens depend on
the application; you can have separate lexer that generates
token sequence that PEG parser can parse, for example.

This library is specifically written to get a good performance
on Gauche.  The parser created by @code{parser.peg} is
no slower than the parser written manually from scratch.
However, you have to watch out some traps; see
@ref{PEG performance tips}, for the details.
@end deftp

@menu
* PEG Walkthrough::
* PEG parser drivers::
* What is a PEG parser::
* PEG primitive parser builders::
* PEG ropes::
* PEG choice::
* PEG sequencing combinators::
* PEG repetition combinators::
* PEG miscellaneous combinators::
* PEG performance tips::
@end menu

@node PEG Walkthrough, PEG parser drivers, PEG parser combinators, PEG parser combinators
@subsection Walkthrough
@c NODE PEGひとめぐり

In this section we cover the basic concepts and tools of @code{parser.peg}.
The code of examples is in @file{examples/pegintro.scm} if you have the
source tree of Gauche.

In @code{parser.peg}, a parser is merely a Scheme procedure
that takes a list of tokens as an argument and returns
a result (well, in fact, it returns three values, but we'll go
into the details later.)

Typically you don't need to write parser procedures directly.
Instead, you can use procedures that
generates parsers.   A parser can be as simple as the
following, which accepts a character @code{#\a}.

@example
($. #\a)   ; @result{} a parser
@end example

Here, @emph{accept} means the parser checks if the head of input has
a character @code{#\a}, and if it is, it succeeds, and if not, it fails.

A parser can be invoked by a @emph{parser driver}.  For example,
you can use @code{peg-parse-string} to invoke the above parser
on a string:

@example
gosh> (peg-parse-string ($. #\a) "abc")
#\a
@end example

The parsing succeeds, and returns the matched value---@code{#\a} in this case.
If the parser can't accept the input, the driver throws an error
@code{<parse-error>}.

@example
gosh> (peg-parse-string ($char #\a) "xyz")
*** PARSE-ERROR: expecting #\a at 0, but got #\x
@end example

A parser can also be constructed by combining simpler parsers,
using @emph{parser combinators}.   For example, @code{$seq} takes
zero or more parsers and apply them sequentially, returning
the last result.

@example
gosh> (peg-parse-string ($seq ($. #\a) ($. #\b) ($. #\c)) "abc")
#\c
@end example

The combinator @code{$many} takes a parser and returns a new parser
that accepts zero or more occurrence of the string the original parser
accepts.

@example
gosh> (peg-parse-string ($many ($. #\a)) "aaaaabc")
(#\a #\a #\a #\a #\a)
gosh> (peg-parse-string ($many ($. #\a)) "xxxxxyz")
()
@end example

A parser is just an ordinary Scheme procedure, so it can be bound
to a variable, then can be used to construct more complex parsers.

@example
(define digits    ($many1 ($. #[\d])))
(define ws        ($many_ ($. #[\s])))
(define separator ($seq ws ($. #\,) ws))
@end example

I leave explanation of @code{$many1} and
@code{$many_} for the later section,
but you may be able to guess what those parsers do;
@code{digits} accepts a sequence of one or more digits, and
@code{ws} accepts sequence of zero or more whitespaces.   The @code{separator}
parser accepts a comma, optionally surrounded by whitespaces.

The @code{digits} parser returns a list of accepted
characters:

@example
gosh> (peg-parse-string digits "12345")
(#\1 #\2 #\3 #\4 #\5)
@end example

Can we create a parser that returns an integer as
a parsed result?    Yes, we can use the @code{$let} macro.

@example
(define integer
  ($let ([ds digits])
    ($return (x->integer (list->string ds)))))
@end example

The @code{$let} works somewhat like @code{and-let*}; it takes
a form of @code{($let ([@var{var} @var{parser}] @dots{}) @var{expr} @dots{})},
applying the @var{parser}s in order, binding the result of each
parser to @var{var}.  If any of the @var{parser} fails, the entire
parser created by @code{$let} macro fails.  When all the @var{parser} succeeds,
each result is  bound to @var{var} and @var{expr} @dots{} are
evaluated.  The last @var{expr} must yield a parser.

The @code{$return} procedure creates a parser
that doesn't consume input, always succeeds
and returns the given value.  The name is taken from
Haskell's monads.  Note that is is just an ordinary procedure
and not like a control-transfer syntax like traditional language's
@code{return}.  You may think it just as type conversion
procedure from a Scheme object to a parser.

@example
gosh> (peg-parse-string integer "12345")
12345
@end example

Now you can combine those parsers to build more complex one, such
as a comma-separated list of integers:

@example
(define integers1 ($seq integer
                        ($many ($seq separator integer))))

gosh> (peg-parse-string integers1 "123, 456, 789")
(456 789)
@end example

Oops, where's 123?  Well, remember that
@code{$seq} discards the results but the last one.
We can use @code{$let} again to keep all the results.

@example
(define integers2 ($let ([n  integer]
                         [ns ($many ($seq separator integer))])
                     ($return (cons n ns))))

gosh> (peg-parse-string integers2 "123, 456, 789")
(123 456 789)
@end example

(Unlike @code{let} where the order of its init expressions are
not defined, @code{$let} guarantees the parsers are applied sequentially.
The reason it is not called @code{$let*} is the scope;
we also have @code{$let*}, which we'll explain shortly.)

Another way to gather the results of parsers is a combinator @code{$lift}.
It is used as @code{($lift proc parser @dots{})}, where @var{proc}
is an ordinary procedure which receives the result of @var{parser} @dots{}
as arguments.  The return value of @var{proc} becomes the result of
the entire parser.  Unlike @code{$let}, @var{proc} doesn't need to
return a parser.

@example
(define integers3 ($lift cons
                         integer
                         ($many ($seq separator integer))))
@end example

The parsers so far doen't handle the case when the list contains no
integers.   Using @code{$or} combinator, which represents a choice,
we can modify it to handle zero-element case.

@example
(define integers4 ($or ($let ([n  integer]
                              [ns ($many ($seq separator integer))])
                         ($return (cons n ns)))
                       ($return '())))
@end example

By the way, ``list of stuff separated by something'' is a very common
pattern, so we can extract the pattern to name it:

@example
(define (sep-by stuff separator)
  ($or ($let ([n  stuff]
              [ns ($many ($seq separator stuff))])
         ($return (cons n ns)))
       ($return '())))
@end example

Then the list of integers can be written this simple:

@example
(define integers5 (sep-by integer separator))
@end example

In fact, @code{parser.peg} provides @code{$sep-by} to do the above,
but we've just shown the definition to demonstrate
the power of the combinatorial approach;
you can use ordinary procedural abstraction to factor out common patterns.

There's one catch in the @code{$or} form.
It tries the next alternative only when the
parser fails @emph{without consuming the input}.  Once the input is
consumed, @code{$or} commits to that choice.   For example,
the following fails even if the input seems to match the
second alternative:

@example
(define paren  ($. #\())
(define thesis ($. #\)))

(peg-parse-string ($or ($seq paren ($."ab") thesis)
                       ($seq paren ($."cd") thesis))
                  "(cd)")
 @result{} *** PARSE-ERROR: expecting ab at 1, but got #\c
@end example

It's because when @code{$or} tries the first branch, it reads the initial
open paren from the input, so @code{$or} commits to the first branch.
When the branch fails, @code{$or} doesn't bother to try the second branch.
(In other words, @code{$or} does not backtrack.)

You may factor out the common prefix:

@example
($seq paren
      ($or ($."ab") ($."cd"))
      thesis)
@end example


But it may complicates the syntax, and it is not always trivial to
factor out like above.  The better way is to use the @code{$try}
combinator: @code{($try @var{p})} runs a parser @var{p}, and if
it fails, @code{$try} rolls back the input as if it didn't
consume input at all.  Using with @code{$or}, you can do arbitrary
lookahead and backtrack.

@example
($or ($try ($seq paren ($."ab") thesis))
     ($seq paren ($."cd") thesis))
@end example

Now, let's get back to the integer list example and make
it more interesting.
Suppose the list of integers are surrounded by parentheses,
brackets or curly-braces.  Opening one and closing one must correspond.

@example
(define begin-list 
  ($seq0 ($. #[\(\[\@{]) ws))

(define (end-list opener) 
  ($seq ws (case opener
            [(#\() ($. #\))]
            [(#\[) ($. #\])]
            [(#\@{) ($. #\@})])))

(define int-list
  ($let* ([opener begin-list]                ;*1
          [ints ($sep-by integer separator)] ;*2
          [ (end-list opener) ])             ;*3
    ($return ints)))
@end example

The opening bracket is parsed by the parser @code{begin-list}.
The @code{$seq0} combinator is similar to @code{seq}, but returns
the result of the first parser instead of the last one
(it's @code{begin0} to @code{begin}).

The closing bracket must match the opening one, so @code{end-list}
is a procedure that takes the opening bracket and returns a suitable
parser to accept the corresponding closing bracket.

The @code{int-list} first parses the opening bracket by @code{begin-list}
and bind the result to @var{opener} (*1).
Then goes to parse comma-separated integers (*2) and bind the
result list to @var{ints}.
Finally, it parses the matching closing bracket (*3).  Note that
the it omits the variable, since we don't need the result of
closing bracket parser.

Since we need to use the value of @var{opener} in the following bindings,
we use @code{$let*} here, instead of @code{$let}.  The difference is
the scope of the parser expressions in the binding.  Note that, however,
@code{$let} is a lot more easier to optimize, so you want to use
@code{$let} whenever possible.

Let's see it works.

@example
gosh> (peg-parse-string int-list "[123, 456, 789]")
(123 456 789)
gosh> (peg-parse-string int-list "@{123, 456, 789@}")
(123 456 789)
gosh> (peg-parse-string int-list "(123, 456, 789@}")
*** PARSE-ERROR: expecting #\) at 14, but got #\@}
@end example

The last example shows it rejects unmatched brackets.

What if we want a nested list?  In BNF, we could write
something like this:

@example
list : begin-list (elem (separator elem)* )? end-list
elem : integer | list
@end example

The straight translation would be he following.

@example
;; First try
(define nested-list
  ($let* ([opener begin-list]
          [ints ($sep-by elem separator)]
          [ (end-list opener) ])
    ($return ints)))
(define elem  ($or integer nested-list))
@end example

Let's load it... Oops.

@example
*** ERROR: unbound variable: elem
Stack Trace:
_______________________________________
  0  elem
        [unknown location]
  1  (eval expr env)
        at "../lib/gauche/interactive.scm":267
@end example

We need the parser @code{elem} to construct @code{nested-list}, but
we need the parser @code{nested-list} to construct @code{elem}.
In lazy languages like Haskell this doesn't matter, but we Schemers
are @emph{eager}!

The solution is to delay the parser construction until it is
actually used.  The @code{$lazy} form does the job:

@example
(define nested-list
  ($lazy
    ($let* ([opener begin-list]
            [ints ($sep-by elem separator)]
            [ (end-list opener) ])
      ($return ints))))
(define elem  ($or integer nested-list))

gosh> (peg-parse-string nested-list "(123, [456, @{@}, 789], 987)")
(123 (456 () 789) 987)
@end example

Ok, we're almost done.  Our code can parse nested list of integers,
checking bracket matches.  But if you give an erroneous input, the message
is cryptic and not helpful:

@example
gosh> (peg-parse-string nested-list "(123, [456, @{@}, 789), 987)")
*** PARSE-ERROR: expecting one of (#[0-9] #\]) at 19
Stack Trace:
_______________________________________
  0  (eval expr env)
        at "../lib/gauche/interactive.scm":267
@end example

We could check the reason of failure in the parser, and call
@code{$fail} with more reasonable error message.  Let's replace
@code{end-list} above with @code{end-list2} below:

@example
(define (end-list2 opener) 
  (define expected
    (assv-ref '((#\( . #\)) (#\[ . #\]) (#\@{ . #\@})) opener))
  ($seq ws 
        ($let ([closer ($. #[\)\]\@}])])
          (if (eqv? closer expected)
            ($return closer)
            ($fail (format "Mismatched closing bracket. '~c' expected, \
                            but got '~c'"
                           expected closer))))))
@end example

You also have to change @code{nested-list} and @code{elem} to 
use @code{end-list2}:
                           
@example
(define nested-list2
  ($lazy
    ($let* ([opener begin-list]
            [ints ($sep-by elem2 separator)]
            [ (end-list2 opener) ])
      ($return ints))))

(define elem2  ($or integer nested-list2))
@end example

(You could redefine @code{end-list}, but if you do so, don't forget to
re-evaluate the definitions of @code{nested-list} and @code{elem}.  
It's because the combinators
are caculated taking the value of other combinators when it's defined,
unlike typical procedural approach where you redefine one procedure and
other procedures will refer to the updated version after that.)

And now you see this error:

@example
gosh> (peg-parse-string nested-list2 "(123, [456, @{@}, 789), 987)")
*** PARSE-ERROR: Mismatched closing bracket. ']' expected, but got ')' at 20
Stack Trace:
_______________________________________
  0  (eval expr env)
        at "../lib/gauche/interactive.scm":267
@end example

For further examples, you can take a look at some libraries in the
Gauche source tree that use @code{parser.peg}:

@itemize @bullet
@item
@file{lib/rfc/json.scm}
@item
@file{lib/text/edn.scm}
@item
@file{lib/www/css.scm}
@end itemize


@node PEG parser drivers, What is a PEG parser, PEG Walkthrough, PEG parser combinators
@subsection Parser drivers
@c NODE PEGパーザドライバ, パーザドライバ

@defun peg-run-parser parser list
@{@t{parser.peg}@}
Apply @var{parser} on the input @var{list}.   If @var{parser} accepts it,
returns two values--the result of @var{parser}, and the rest of
the input.  If @var{parser} fails, raise @code{<parse-error>}.

The result of @var{parse} is a value yielded by @var{parser}
passed to @code{rope-finalize}, so any unfinalized rope is
finalized before being returned.  @xref{PEG ropes}, for the details.

Typically, you don't want to have entire input as a list beforehand,
so you pass a lazy sequence as @var{list} (@pxref{Lazy sequences}).
If the input is a string
or a port, convenience procedures are defined.

Input doesn't need to be a character list.  You may, for example,
have a separate lexer that generates a (lazy) list of tokens, and let @var{parser}
parse them.
@end defun

@defun peg-parse-string parser string :optional cont
@defunx peg-parse-port parser iport :optional cont
@{@t{parser.peg}@}
Convenience wrappers of @code{peg-run-parser} that takes input from
@var{string} or @var{iport}.

Without @var{cont} argument or it is @code{#f}, 
it returns the parsed result and discards
the rest of the input.  (Hint: To make sure there's no garbage
following, use @code{$eos} parser.)

If you want to keep parsing after @var{parser} accepts its input,
pass @var{cont} a procedure; it must take two arguments, the result of
@var{parser} and a lazy sequence of the rest of the input.  What @var{cont}
returns will be the result of these procedures.

It is an error to pass other values ot @var{cont}.
@end defun

@defun peg-parser->generator parser list
@{@t{parser.peg}@}
This is useful when you need to apply @var{parser} repeatedly over
the input @var{list}.    Returns a generator that generates
the parsed result one match at a time.

The same input can be accepted by
by @code{(peg-run-parser ($many parser) list)}, but this one
won't return until all input is consumed.
@end defun

@deftp {Condition type} <parse-error>
@{@t{parser.peg}@}
An condition type raised by the parser driver when the given parser
failed ultimately.  Inherits @code{<error>}.
(Note that each parser won't throw this; one
parser's failure doesn't necessarily mean the entire parser fails.
It's the driver that recognizes the ultimate failure and raise this
condition.)

The following slots are available:

@defivar <parse-error> message
This slot is inherited from @code{<error>}.  Contains string error message.
@end defivar

@defivar <parse-error> position
The position the failure occurs, counted by the number of tokens
from the beginning of the input.
@end defivar

@defivar <parse-error> type
The type of failure.  It's either one of the follownig symbols:
@table @code
@item fail-expect
The parser expects one of the objects in @var{objects} slot, but
got a different one (stored in @var{token}).
@item fail-unexpect
The parser isn't expecting any of the objects in @var{objects} slot,
but got the one in @var{token}.
@item fail-compound
The parser failed multiple options.  The @var{objects} slot contains
a list of of @code{(type . msg)} where @var{type} is one of the
@code{<parse-error>} types, and
@var{msg} is the message associated with it.
@item fail-message
Other miscellaneous failure.  The @var{objects} slot contains
a mmessage.
@end table
@end defivar

@defivar <parse-error> objects
Value of this slot depends on the value of @var{type} slot.
@end defivar

@defivar <parse-error> token
The token at the head of input when failure occur.  If input already
reached at the end, this slot is set to @code{#<eof>}.
@end defivar
@end deftp

@node What is a PEG parser, PEG primitive parser builders, PEG parser drivers, PEG parser combinators
@subsection What is a PEG parser, really?

A PEG parser is a Scheme procedure that takes a list of items as an input,
and returns three values:

@itemize
@item
Failure type.  If the parser successfully accepts the input, this value
is @code{#f}.  If the parser fails to accept the input,
this value is either one of the symbols
@code{fail-expect}, @code{fail-unexpect}, @code{fail-compound}
and @code{fail-message}.  It corresponds to the @code{type} slot
of @code{<parse-error>}, and determines the meaning of the second
return value.
@item
Value.  If the parser successfully accepts the input, this
value is the parser's ``result'', sometimes called a semantic
value.  If the parser fails to accept the input,
this value contains the hint of the failure.  It corresponds
to the @code{objects} slot of @code{<parse-error>}; see the documentation
of @code{<parse-error>} for the details (@pxref{PEG parser drivers}).
@item
The rest of the input list.
@end itemize

Typically you don't need to write a parser as a procedure; instead,
you can use one of the parser builders and combinators described in
the following sections.

We do provide a few utilities to write a parser from scratch, in case
you need to do so.

@defun return-result value rest
@{@t{parser.peg}@}
Call this at the tail position of the parser when it succeeds, with
@var{value} for the semantic value and @var{rest} for the rest of
input.  This is the same as @code{(values #f value rest)}, but
clearer to show the intention.
@end defun

@defun return-failure/expect objs rest
@defunx return-failure/unexpect objs rest
@defunx return-failure/message msg rest
@defunx return-failure/compound fails rest
@{@t{parser.peg}@}
Call one of these at the tail position of the parser when it fails.
The first argument will be in @code{objects} slot of @code{<parse-error>}.

@itemize
@item
If you're expecting some types of objects (@var{objs}) but got anything
else, call @code{return-failure/expect}.  It generates @code{fail-expect}
type failure.
@item
If you're not expecting some types of objects (@var{objs}) but got one,
call @code{return-failure/unexpect}.  It generates @code{fail-unexpect}
type failure
@item
If you're failing because of all of multiple choices fail, you can
gather those failures into an assoc list
@code{((fail-type . objs) @dots{})}, and 
call @code{return-failure/compound}.  It generates @code{fail-compound}
type failure.
@item
Finally, your failure can't be categorized to one of the above,
you can call @code{return-failure/message}, with the message
describing the reason of the failure.
@end itemize
@end defun

@defun return-failure type objs rest
@{@t{parser.peg}@}
This should only be used to pass down the failure form other parser.
See the example in @code{parse-success?} entry below.
@end defun


@defun parse-success? r
@{@t{parser.peg}@}
Check the first return value of a parser to see if it is a success.
A typical usage is to check another parser's result and take
actions accordingly:

@example
(receive (r v s) (parser input)
  (if (parse-success? r)
     (... do things after PARSER succeeds ...
       (return-result ...))
     (return-failure r v s)))
@end example
@end defun


@node PEG primitive parser builders, PEG ropes, What is a PEG parser, PEG parser combinators
@subsection Primitive parser builders

Procedures and macros that create parsers.

@defun $return val
@{@t{parser.peg}@}
Returns a parser that always succeeds, without consuming
input, and yields @var{val} as the result of parser.

Frequently used in @code{$let} and @code{$let*}'s body, but can be
used anywhere a parser is expected.
@end defun

@defun $fail msg-string
@{@t{parser.peg}@}
Returns a parser that always fails, without consuming input,
and uses @var{msg-string} as the failure message.

Frequently used to produce user-friendly error messages.
@end defun

@defun $satisfy pred expect :optional result
@{@t{parser.peg}@}
This corresponds to ``semantic predicate'' in PEG; a parser
that can apply an arbitrary predicate on input.

Returns a parser that works as follows:
@itemize @bullet
@item
If the head of input stream satisfies @var{pred},
call @code{(@var{result} head (@var{pred} head))} and
yield its return value as the result of successful parsing.
If @var{result} is omitted, it yields the head of input.
@item
Otherwise, the parsing fails with @var{expect} as the expected input.
@end itemize
@end defun

@defun $. obj
@{@t{parser.peg}@}
Creates a parser that matches a Scheme object @var{obj},
which may be a character, a string, or a char-set.
If @var{obj} is a char-set, the parser matches any character in the set.

The resulting parser is atomic, that is, it doesn't consume
input when it fails.
@end defun

@defun $char c
@defunx $char-ci c
@{@t{parser.peg}@}
Returns a parser that accepts a single character, @var{c}.
@code{$char-ci} ignores case.
On success, the parser yields the input character.
The resulting parser is atomic, that is, it doesn't consume
input when it fails.
@end defun

@defun $string str
@defunx $string-ci str
@{@t{parser.peg}@}
Returns a parser that accepts an input that matches
a string @var{str}.  @code{$string-ci} ignores case.
On success, the parser yields the matched string.

The parsing of string is atomic: When the parser fails,
it doesn't consume the input.  That is,
@code{($string "ab")} is not the same as
@code{($let ([a ($char #\a)] [b ($char #\b)]) ($return (string a b)))}.
@end defun

@defun $one-of cset
@{@t{parser.peg}@}
Returns a parser that accepts any character in the character set @var{cset}.
On success, the parser yields the accepted character.
@end defun

@defun $none-of cset
@{@t{parser.peg}@}
Returns a parser that accepts any character not in the character set @var{cset}.
On success, the parser yields the accepted character.
@end defun

@defun $any
@{@t{parser.peg}@}
Returns a parser that matches any one item, and yields the matched
input item on success.
It fails only when the input already reached at the end.
@end defun

@defun $eos
@{@t{parser.peg}@}
Stands for ``end of stream''.  Returns a parser that matches
the end of input.  It never consumes input.
@end defun


@defmac $match1 pattern result
@defmacx $match1 pattern
@defmacx $match1 pattern (@code{=>} fail) result
@defmacx $match1* pattern result
@defmacx $match1* pattern
@defmacx $match1* pattern (@code{=>} fail) result
@{@t{parser.peg}@}
The pattern matcher macro @code{match-let1} lifted to the parser.
@xref{Pattern matching}, for the details of supported @var{pattern}.

The macro @code{$match1} returns a parser that takes one item
from the input stream, and see if it matches @var{pattern}.
If it matches, evaluate @var{result} within an environment
where pattern variables are bound to matched content, and the
parser yields the value of @var{result}.  If the input doesn't
match @var{pattern}, or the input is empty, the parser fails without
consuming input.

In the third form @code{=>} must be a literal identifier and @var{fail}
must be an identifier.  The identifier @var{fail} is bound to a procedure
that takes one string argument in @var{result}.  You can call @var{fail}
at the tail position of @var{result} to make the match fail, with
the passed argument as the message.  If @var{fail} is called,
no input will be consumed.

(NB: The @code{match} macro in @code{util.match} has a similar feature,
but it binds @var{fail} to a continuation that abandons the current match
clause and go to try the next pattern.  In @code{$match1}, @var{fail}
is simply a procedure, so you have to call it at the tail position
to make it work.)

The macro @code{$match1*} is similar to @code{$match1}, except
the entire input is matched @var{pattern}.   It is useful to
look into several items in input, instead of just one.
Note that if you give a pattern that consumes arbitrary length
of input (e.g. @code{($match1* (a ...))}, it will consume entire
input.

These macros especially come handy when you have a token stream
generated by a separate lexer---each token can have some structure
(instead of just a character) and you can take advantage of @code{match}.
@end defmac



@node PEG ropes, PEG choice, PEG primitive parser builders, PEG parser combinators
@subsection Ropes

Often you want to construct a string out of the results of other parsers.
It can be costly to construct strings eagerly, for a string may be
just an intermediate one to be a part of a larger string.  We provide
a lightweight lazily string construction mechanism, called ropes.

A rope is either a character, a string or a pair of ropes.  It allows
O(1) concatenation.  A rope becomes a string when @emph{finalized}.
The parser drivers such as @code{peg-run-parser} automatically finalizes
ropes in the parser result.

@defun $->rope parser @dots{}
@{@t{parser.peg}@}
The parsers must yield either a character, a string, a rope,
or @code{#f} or @code{()}.  This procedure
returns a parser that matches @var{parser} @dots{}, then gather the
result into a rope.  @code{#f} and @code{()} in the results are ignored.
@end defun

@defun $->string parser @dots{}
@{@t{parser.peg}@}
This is a common idiom of @code{($lift rope->string ($->rope parser @dots{}))}.
@end defun

@defun $->symbol parser @dots{}
@{@t{parser.peg}@}
Like @code{$->string}, but yields a symbol rather than a string.
@end defun

@defun rope->string rope
@{@t{parser.peg}@}
Converts a rope to a string.
@end defun

@defun rope-finalize obj
@{@t{parser.peg}@}
Converts any ropes in in @var{obj} into strings.
@end defun


@node PEG choice, PEG sequencing combinators, PEG ropes, PEG parser combinators
@subsection Choice, backtrack and assertion combinators

@defun $or p1 p2 @dots{}
@{@t{parser.peg}@}
Returns a choice parser.  Tries the given parser in order on input.
If one succeeds, immediately yields its result.
If one fails, and does not consume input, then tries the next one.
If one fails with consuming input, immediately fails.

If @var{p1} @var{p2} @dots{} don't share the same prefix
to match, you can let it fail as soon as one parser fails with consuming
input.   If more than one parsers do match the same prefix,
you want to wrap them with @code{$try} except the last one.
@end defun

@defun $try p
@{@t{parser.peg}@}
Returns a parser that accepts the same input
the parser @var{p} accepts, but when @var{p} fails
the returned parser doesn't consume input.  Used with @code{$or},
you can explicitly implement a backtrack behavior.
@end defun

@defun $optional p :optional fallback
@{@t{parser.peg}@}
Returns a parser that tries @var{p} on the input.
If it succeeds, yielding its result.  If it fails,
it still succeeds, yielding @var{fallback} as the result.

This is atomic; if @var{p} fails, it doesn't consume input.
@end defun

@defun $assert p
@{@t{parser.peg}@}
Returns a parser that accepts the same input as @var{p}
and returns its result on success, but never consumes the input.
It can be used as a lookahead assertion.
@end defun

@defun $not p
@{@t{parser.peg}@}
Returns a parser that succeeds when @var{p} fails, and that fails
when @var{p} succeeds.  When @var{p} succeeds, it yields an
``unexpected'' error.  It never consumes input in either way.
It can be used as a negative lookahead assertion.
@end defun

@defun $expect p msg-string
@{@t{parser.peg}@}
Returns a parser that calls a parser @var{p}, and if it succeeds
yields its result.  If @var{p} fails, fails with an error message
that says expecting @var{msg-string}.
Useful to produce user-friendly error messages.
@end defun


@node PEG sequencing combinators, PEG repetition combinators, PEG choice, PEG parser combinators
@subsection Sequencing combinators

@defun $seq p1 p2 @dots{}
@defunx $seq0 p1 p2 @dots{}
@{@t{parser.peg}@}
Matches @var{p1}, @var{p2}, @dots{} sequentially.  When all the parser
succeeds, @code{$seq} returns
the last result, while @var{$seq0} returns the first result.
Fails immediately when one of the parsers fails.
@end defun

@defun $between p1 p2 p3
@{@t{parser.peg}@}
Matches @var{p1}, @var{p2} and @var{p3} sequentially, and returns
the result of @var{p2}.
@end defun

@defun $bind p f
@{@t{parser.peg}@}
The basic block of parser combinators;
@var{p} argument is a parser, and @var{f} is a procedure
that takes a Scheme value and returns a parser.

Returns a parser that first applies @var{p} on the input, and if
it succeeds, calls @var{f} with the result of @var{p}, and applies
the returned parser on the subsequent input.

This combinator, along with @code{$return} and @code{$fail},
composes a MonadFail interface as in Haskell.  Theoretically any
combinators can be built on top of these three.  In practice, 
however, it is not always easy to build things directly on top
of @code{$bind}, and more high-level forms such as @code{$let},
@code{$let*} and @code{$lift} are frequently used.
@end defun


@defmac $let (binding @dots{}) body @dots{}
@defmacx $let* (binding @dots{}) body @dots{}
@{@t{parser.peg}@}
Monadic binding form.  Each @var{binding} can be one of the
following forms:

@table @code
@item (var parser)
Run the @var{parser}, and if it succeeds, bind its result to a variable
@var{var}.  If it fails, the entire @code{$let} or @code{$let*} immdiately
fails.

@item (parser)
The variable is omitted.  The @var{parser} is run, and if it succeeds,
its result is discarded and the next binding or body is evaluated.
If it fails, the entire @code{$let} or @code{$let*} immdiately fails.

@item parser
Same as above.  This form can only be used if @var{parser} is just
a vairable reference.
@end table

Once all the parsers in @var{binding} @dots{} succeeds, @var{body} @dots{}
are evaluated in the environment where @var{var} in bindings are bound
to the parser results.  The last expression of @var{body} must return
a parser.

Unlike @code{let}, the parsers in @var{binding} @dots{} are always applied
to the input sequentially.  The difference of @code{$let} and
@code{$let*} is the scope.  With @code{$let*}, the variables bound
in earlier @var{binding} can be used to consturct the @var{parser} later.

This means @code{$let} can evaluate all the parsers beforehand, while
@code{$let*} may need to construct parsers at the time of processing
input.  Creating a parser involves closure allocations, so you want
to use @code{$let} whenever possible.

Note: @code{$let*} is similar to Haskell's @code{do} construct.  We chose
the name @code{$let} and @code{$let*}, for it is easier to see it's
a binding form, and also Scheme already uses @code{do} for
loop construct.
@end defmac

@defun $lift f p @dots{}
@defunx $lift* f p @dots{}
@{@t{parser.peg}@}
Lifts a procedure @var{f} onto the parsers' world.

In a pseudo type declaration, @code{lift}'s type can be understood
as follows:
@example
lift :: (a b ... -> z) (Parser a) (Parser b) ... -> (Parser z)
@end example

That is, @code{lift} creates a parser such that
it first applies parsers on the input, and if all of them succeeds,
it calls @var{f} with the parsers' results as arguments,
and the return value of @var{f} becomes the whole parser's result.

In other words, the following equivalence holds:
@example
($lift f p0 p1 @dots{})
 @equiv{} ($let ([r0a p0] [r1 p1] @dots{}) ($return (f r0 r1 @dots{})))
@end example

It is sometimes simpler to use @code{$lift} instead of @code{$let}.  
For example, the following code creates a parser that matches
input with @var{p0} @var{p1} @dots{} sequentially, then yields
the list of the parser results:

@example
($lift list p0 p1 @dots{})
@end example

Note that after all the parsers succeeds, the whole parser is
destined to succeed---the procedure @var{f} can't make the parser
fail.  If you need to fail after all the parsers succeeds, use @code{$let}
or @code{$let}.
@end defun

@defun $fold-parsers proc seed ps
@{@t{parser.peg}@}
@var{Ps} is a list of parsers.  Apply those parsers sequentially
on the input, passing around the seed value.  That is, if we let
@code{v0}, @var{v1} @dots{} @var{vn} be the result of each parsers in @var{ps},
it returns @code{(proc vn (... (proc v2 (proc v1 seed))...))}.

If any of the parser in @var{ps} fails, @code{$fold-parsers} fails at
that point.

Conceptually, it can be written as follows:

@example
(define ($fold-parsers proc seed ps)
  (if (null? ps)
    ($return seed)
    ($let ([v (car ps)])
      ($fold-parsers proc (proc v seed) (cdr ps)))))
@end example

But we use more efficient implementation.
@end defun

@defun $fold-parsers-right proc seed ps
@{@t{parser.peg}@}
Similar to @code{$fold-parsers}, but the folding by @var{proc}
right to left.  That is, if we let
@code{v0}, @var{v1} @dots{} @var{vn} be the result of each parsers in @var{ps},
it returns @code{(proc v1 (proc v2 (... (proc vn seed)...)))}.

If any of the parser in @var{ps} fails, @code{$fold-parsers-right} fails at
that point.
@end defun


@node PEG repetition combinators, PEG miscellaneous combinators, PEG sequencing combinators, PEG parser combinators
@subsection Repetition combinators


@defun $many p :optional min max
@defunx $many_ p :optional min max
@{@t{parser.peg}@}
Without optional arguments, returns
a parser that accepts zero or more repetition of @var{p}.
On success, @code{$many} yields a list of mached results,
while @var{$many_} doesn't keep the results (and faster).

Optinoal @var{min} and @var{max} must be nonnegative integers
and limit the number of occurrences of @var{p}. The numbers are inclusive.
For example,
@code{($many ($. #\a) 3)} accepts three or more @code{#\a}'s,
and @code{($many ($. #\a) 2 4)} accepts @code{aa}, @code{aaa} and
@code{aaaa}.

Note that @code{$many} may fail if the input partially matches
@code{p}.

@example
(peg-parse-string ($many ($seq ($. #\a) ($. #\b))) "ababcd")
  @result{} (#\b #\b)
  
(peg-parse-string ($many ($seq ($. #\a) ($. #\b))) "ababac")
  @result{} *** PARSE-ERROR: expecting #\b at 5, but got #\c
@end example

If you want to stop @code{$many} at the first two occurrences
in the latter case, use @code{$try}:

@example
(peg-parse-string ($many ($try ($seq ($. #\a) ($. #\b)))) "ababac")
  @result{} (#\b #\b)
@end example
@end defun

@defun $many1 p :optional max
@defunx $many1_ p :optional max
@{@t{parser.peg}@}
Returns a parser that accepts one or more occurences of @var{p}.
On success, @code{$many1} yields a list of results of @var{p},
while @var{$many_} discards the results of @var{p} and faster.
If @var{max} is given, it specifies the maximum number of matches.

Same as @code{($many p 1 max)} and @code{($many_ p 1 max)}.
Provided as a common pattern.
@end defun

@defun $repeat p n
@defunx $repeat_ p n
@{@t{parser.peg}@}
Returns a parser that accepts exaclty @var{n} occurences of @var{p}.
On success, @code{$repeat} yields a list of results of @var{p},
while @var{$repeat_} discards the results of @var{p} and faster.

Same as @code{($many p n n)} and @code{($many_ p n n)}.
Provided as a common pattern.
@end defun

@defun $many-till p pe :optional min max
@defunx $many-till_ p pe :optional min max
@{@t{parser.peg}@}
Returns a parser that accepts repetition of @var{p}, until it
sees input that accepts @var{pe}.
On success, @code{$many-till} yields a list of results of @var{p},
while @var{$many-till_} discards the results of @var{p} and faster.

@example
(define comment ($seq ($.";") ($many-till ($any) ($."\n"))))
@end example
@end defun

@defun $sep-by p psep :optional min max
@defunx $end-by p psep :optional min max
@defunx $sep-end-by p psep :optional min max
@{@t{parser.peg}@}
These combinators match repetition of @var{p} separated by @var{psep},
such as comma-separated values.
Returns the list of results of @var{p}.
Optional @var{min} and @var{max} are integers that limits the
number of repetitions.

These three differ only on treatment of the last separator; @code{$sep-by}
accepts strictly infix syntax, that is, the input must not end
with the separator; while @code{$end-by} accepts strictly suffix syntax,
that is, the input must end with the separator; @code{$sep-end-by}
makes the last separator optional.
@end defun

@defun $chain-left p op
@defunx $chain-right p op
@{@t{parser.peg}@}
Returns a parser that parsers left-assosiative and right-associative operators,
respectively.

The term of expression is parsed by a parser @var{p}, and the
operator is parsed by @var{op}.
@end defun

@node PEG miscellaneous combinators, PEG performance tips, PEG repetition combinators, PEG parser combinators
@subsection Miscellaneous combinators

@defmac $parameterize ((param expr) @dots{}) parser @dots{}
@{@t{parser.peg}@}
Returns a parser that runs @var{parser} @dots{}, while altering
the parameter values of @var{param} @dots{} with the reuslt of
@var{expr} @dots{}, like @code{parameterize}.
The @var{parser} @dots{} are run as if in @code{$seq}, so only the value
of them is returned on success.

You can't use ordinary @code{parameterize}, since such parameterization
takes effect on parser construction time, and not when the parser
parsing the input.
@end defmac

@defun $debug name p
@{@t{parser.peg}@}
Parses the same input as @var{p}, but reports when it is parsing
the input, and the result, just like @code{debug-print}.

You can't use @code{debug-print} directly, for it will take effect
on the parser construction time, not when the input is parsed.
@end defun

@defmac $lazy p
@{@t{parser.peg}@}
Returns a parser that works the same as @var{p}, but delays evaluation
of @var{p} until needed.  It is useful when you define mutually
recursive parsers.
@end defmac



@node PEG performance tips,  , PEG miscellaneous combinators, PEG parser combinators
@subsection Performance



@c ----------------------------------------------------------------------
@node RFC822 message parsing, Base64 encoding/decoding, PEG parser combinators, Library modules - Utilities
@section @code{rfc.822} - RFC822 message parsing
@c NODE RFC822メッセージ形式, @code{rfc.822} - RFC822メッセージ形式

@deftp {Module} rfc.822
@mdindex rfc.822
Defines a set of functions that parses and constructs the ``Internet
Message Format'', a text format used to exchange e-mails.
The most recent specification can be found in
RFC5322.
The format was originally defined in RFC 822, and people still
call it ``RFC822 format'', hence I named this module.
In the following document, I also refer to the format as ``RFC822 format''.
@end deftp

@subheading Parsing message headers

@defun rfc822-read-headers iport :key strict? reader
@{@t{rfc.822}@}
Reads RFC822 format message from an input port @var{iport},
until it reaches the end of the message header.
The header fields are broken into a list of the following
format:
@example
((name body) @dots{})
@end example
@var{Name} @dots{} are the field names, and @var{body} @dots{} are
the corresponding field body, both as strings.
Field names are converted to lower-case characters.
Field bodies are not modified, except the folded line is unfolded.
The order of fields are preserved.

By default, the parser works permissively.  If EOF is encountered
during parsing header, it is taken as the end of the message.
And if a line that doesn't consist neither continuing (folded) line
nor start a new header field, it is simply ignored.
You can change this behavior by giving true value to
the keyword argument @var{strict?}; then the parser raises an error
for such a malformed header.

The keyword argument @var{reader} takes a procedure that reads
a line from @var{iport}.  Its default is @code{read-line}, which
should be enough for most cases.
@end defun

@defun rfc822-header->list iport :key strict? reader
@{@t{rfc.822}@}
This is an old name of @code{rfc822-read-headers}.  This is kept
for the backward compatibility.  The new code should use
@code{rfc822-read-headers} instead.
@end defun


@defun rfc822-header-ref header-list field-name :optional default
@{@t{rfc.822}@}
An utility procedure to get a specific field from the parsed
header list, which is returned by @code{rfc822-read-headers}.

@var{Field-name} specifies the field name in a lowercase string.
If the field with given name is in @var{header-list}, the procedure
returns its value in a string.  Otherwise, if @var{default} is given,
it is returned, and if not, @code{#f} is returned.

This procedure can actually be used not only for the result of
@code{rfc822-read-headers}, but for retrieving a value keyed
by strings in a list-of-list structure: @code{((name value option ...) ...)}.
For example, the return value of @code{parse-cookie-string}
can be passed to @code{rfc-822-header-ref} 
(@pxref{HTTP cookie handling}, for @code{parse-cookie-string}).

@example
(rfc822-header-ref 
  '(("from" "foo@@example.com") ("to" "bar@@example.com"))
  "from")
 @result{} "foo@@example.com"

;; If no entry matches, #f is returned by default
(rfc822-header-ref 
  '(("from" "foo@@example.com") ("to" "bar@@example.com"))
  "reply-to")
 @result{} #f

;; You can give the default value for no-match case
(rfc822-header-ref 
  '(("from" "foo@@example.com") ("to" "bar@@example.com"))
  "reply-to" 'none)
 @result{} none

;; By giving the default value, you can distinguish
;; the no-match case and there's actually an entry with value #f.
(rfc822-header-ref 
  '(("from" "foo@@example.com") ("reply-to" #f))
  "reply-to" 'none)
 @result{} #f
@end example
@end defun

@subheading Basic field parsers

Several procedures are provided to parse "structured" header fields
of RFC2822 messages.  These procedures deal with the body of
a header field, i.e. if the header field is
"@code{To: Wandering Schemer <schemer@@example.com>}",
they parse "@code{Wandering Schemer <schemer@@example.com>}".

Most of procedures take an input port.  Usually you first parse
the entire header fields by @code{rfc822-read-headers},
obtain the body of the header by @code{rfc822-header-ref},
then open an input string port for the body and use those
procedures to parse them.

The reason for this complexity is because you need
different tokenization schemes depending on the type of the field.
Rfc2822 also allows comments to appear between tokens for most cases,
so a simple-minded regexp won't do the job,
since rfc2822 comment can be nested
and can't be represented by regular grammar.
So, this layer of procedures are designed flexible enough
to handle various syntaxes.  For the standard header types,
high-level parsers are also provided; see "specific field parsers" below.

@defun rfc822-next-token iport :optional tokenizer-specs
@{@t{rfc.822}@}
A basic tokenizer.  First it skips whitespaces and/or
comments (@code{CFWS}) from @var{iport}, if any.  Then
reads one token according to @var{tokenizer-specs}.  If @var{iport}
reaches EOF before any token is read, EOF is returned.

@var{Tokenizer-specs} is a list of tokenizer spec, which is
either a char-set or a cons of a char-set and a procedure.

After skipping @code{CFWS}, the procedure peeks a character
at the head of @var{iport}, and checks it
against the char-sets in @var{tokenizer-specs} one by one.
If a char-set that contains the character belongs to is found,
then a token is retrieved as follows:
If the tokenizer spec is just a char-set, a sequence of characters
that belong to the char-set consists a token.
If it is a cons, the procedure is called with @var{iport} to
read a token.

If the head character doesn't match any char-sets,
the character is taken from @var{iport} and returned.

The default @var{tokenizer-specs} is as follows:
@example
(list (cons #["] rfc822-quoted-string)
      (cons *rfc822-atext-chars* rfc822-dot-atom))
@end example
Where @code{rfc822-quoted-string} and @code{rfc822-dot-atom}
are tokenizer procedures described below, and @code{*rfc822-atext-chars*}
is bound to a char-set of @code{atext} specified in rfc2822.
This means @code{rfc822-next-token} retrieves a token
either @code{quoted-string} or @code{dot-atom} specified in rfc2822
by default.

Using @var{tokenizer-specs}, you can customize how the header
field is parsed.  For example, if you want to retrieve a token
that is either (1) a word constructed by alphabetic characters, or
(2) a quoted string, then you can call @code{rfc822-next-token}
by this:

@example
(rfc822-next-token iport
   `(#[[:alpha:]] (#["] . ,rfc822-quoted-string)))
@end example
@end defun

@defun rfc822-field->tokens field :optional tokenizer-specs
@{@t{rfc.822}@}
A convenience procedure.  Creates an input string port for
a field body @var{field}, and calls @code{rfc822-next-token}
repeatedly on it until it consumes all input, then returns
a list of tokens.   @var{Tokenizer-specs} is passed to
@code{rfc822-next-token}.
@end defun

@defun rfc822-skip-cfws iport
@{@t{rfc.822}@}
A utility procedure that consumes any comments and/or whitespace
characters from @var{iport}, and returns the head character
that is neither a whitespace nor a comment.  The returned character
remains in @var{iport}.
@end defun

@defvr {Constant} *rfc822-atext-chars*
@{@t{rfc.822}@}
Bound to a char-set that is a valid constituent of @code{atom}.
@end defvr

@defvr {Constant} *rfc822-standard-tokenizers*
@{@t{rfc.822}@}
Bound to the default @var{tokenizer-specs}.
@end defvr

@defun rfc822-atom iport
@defunx rfc822-dot-atom iport
@defunx rfc822-quoted-string iport
@{@t{rfc.822}@}
Tokenizers for @code{atom}, @code{dot-atom} and @code{quoted-string},
respectively.  The double-quotes and escaping backslashes within
@code{quoted-string} are removed by @code{rfc822-quoted-string}.
@end defun

@subheading Specific field parsers

@defun rfc822-parse-date string
@{@t{rfc.822}@}
Takes RFC-822 type date string, and returns eight values:
@example
year, month, day-of-month, hour, minutes, seconds, timezone,
day-of-week.
@end example

@emph{Timezone} is an offset from UT in minutes.
@emph{Day-of-week} is a day from sunday,
and may be #f if that information is not available.
@emph{Month} is an integer between 1 and 12, inclusive.
If the string is not parsable, all the elements are #f.
@end defun

@defun rfc822-date->date string
@{@t{rfc.822}@}
Parses RFC822 type date format and returns SRFI-19 @code{<date>} object
(see @ref{SRFI-19 Date}).  If @var{string} can't be parsed,
returns @code{#f} instead.

To construct rfc822 date string from SRFI-19 date, you can use
@code{date->rfc822-date} below.
@end defun

@subheading Message constructors

@defun rfc822-write-headers headers :key output continue check
@{@t{rfc.822}@}
This is a sort of inverse function of @code{rfc822-read-headers}.
It receives a list of header data, in which each header data
consists of @code{(<name> <body>)}, and writes them out in RFC822 header
field format to the output port specified by the @var{output} keyword
argument.  The default output is the current output port.

By default, the procedure assumes @var{headers} contains all the
header fields, and adds an empty line in the end of output
to indicate the end of the header.  You can pass a true value to
the @var{continue} keyword argument to prevent this, enabling
more headers can be added later.

I said ``a sort of'' above.  That's because this function doesn't
(and can't) do the exact inverse.
Specifically, the caller is responsible for line folding and
make sure each header line doesn't exceed the ``hard limit'' defined
by RFC2822 (998 octets).  This procedure cannot do the line
folding on behalf of the caller, because the places where
line folding is possible depend on the semantics of each
header field.

It is also the caller's responsibility to make sure header
field bodies don't have any characters except non-NUL US-ASCII
characters.  If you want to include characters outside of that
range, you should convert them in the way allowed by the
protocol, e.g. MIME.  The @code{rfc.mime} module
(@pxref{MIME message handling}) provides a convenience procedure
@code{mime-encode-text} for such purpose.
Again, this procedure cannot do the encoding automatically,
since the way the field
should be encoded depends on header fields.

What this procedure can do is to check and report such violations.
By default, it runs several checks and signals an error if it finds any
violations of RFC2822.  You can control this checking behavior
by the @var{check} keyword argument.  It can take one of the
following values:

@table @code
@item :error
Default.  Signals an error if a violation is found.
@item #f, :ignore
Doesn't perform any check.  Trust the caller.
@item @var{procedure}
When @code{rfc822-write-headers} finds a violation, the procedure
is called with three arguments; the header field name,
the header field body, and the type of violation explained below.
The procedure may correct the problem and return two values,
the corrected header field name and body.  The returned values
are checked again.  If the procedure returns the
header field name and body unchanged, an error is signaled
in the same way as @code{:error} is specified.
@end table

The third argument passed to the procedure given to the @var{check}
argument is one of the following symbols.  New symbols may be
added in future versions for more checks.

@table @code
@item incomplete-string
Incomplete string is passed.
@item bad-character
Header field contains characters outside of US-ASCII or NUL.
@item line-too-long
Line length exceeds 998 octet limit.
@item stray-crlf
The string contains CR and/or LF character that doesn't consist of
proper line folding.
@end table

@end defun

@defun date->rfc822-date date
@{@t{rfc.822}@}
Takes SRFI-19 @code{<date>} object (see @ref{SRFI-19 Date})
and returns a string of its rfc822 date representation.
This is a reverse operation of @code{rfc822-date->date}.
@end defun


@c ----------------------------------------------------------------------
@node Base64 encoding/decoding, HTTP cookie handling, RFC822 message parsing, Library modules - Utilities
@section @code{rfc.base64} - Base64 encoding/decoding
@c NODE Base64エンコーディング, @code{rfc.base64} - Base64エンコーディング

@deftp {Module} rfc.base64
@mdindex rfc.base64
This module defines a few functions to encode/decode Base64 format,
defined in RFC 2045 (@uref{https://www.ietf.org/rfc/rfc2045.txt}), section 6.3
and RFC 4648 (@uref{https://www.ietf.org/rfc/rfc4648.txt}).
@end deftp

@defun base64-encode :key line-width url-safe
@{@t{rfc.base64}@}
Reads byte stream from the current input port, encodes it in Base64
format and writes the result character stream to the current output port.
The conversion ends when it reads EOF from the current input port.

Newline characters can be inserted to keep the maximum line width to
the value given to the @var{line-width} keyword argument.  The default
value of @var{line-width} is 76, as specified in RFC2045.  You can give
@code{#f} or zero to @var{line-width} to suppress line splitting.

If a true value is given to @var{url-safe},
the input bytes will be encoded with an
alternative encoding table, which substitutes @code{+} instead of
@code{-} and @code{/} instead of @code{_}. The result will contain
filename and url safe characters only.  Default value of @var{url-safe}
is false.
@end defun

@defun base64-encode-string string :key line-width url-safe
@{@t{rfc.base64}@}
Converts contents of @var{string} to Base64 encoded format.
Input string can be either complete or incomplete string;
it is always interpreted as a byte sequence.
@end defun

@defun base64-decode :key url-safe
@{@t{rfc.base64}@}
Reads character stream from the current input port, decodes it from Base64
format and writes the result byte stream to the current output port.
The conversion ends when it reads EOF or the termination character
(@code{=}).  The characters which does not in legal Base64 encoded character
set are silently ignored.
@end defun

@defun base64-decode-string string :key url-safe
@{@t{rfc.base64}@}
Decodes a Base64 encoded string @var{string} and returns
the result as a string.
The conversion terminates at the end of @var{string} or
the termination character (@code{=}).
The characters which does not in legal Base64 encoded character
set are silently ignored.
@end defun

@c ----------------------------------------------------------------------
@node HTTP cookie handling, FTP, Base64 encoding/decoding, Library modules - Utilities
@section @code{rfc.cookie} - HTTP cookie handling
@c NODE HTTPクッキー, @code{rfc.cookie} - HTTPクッキー

@deftp {Module} rfc.cookie
@mdindex rfc.cookie
Defines a set of functions to parse and construct a ``cookie'' information
defined in RFC 6265.
@end deftp

@defun parse-cookie-string string :optional version
@{@t{rfc.cookie}@}
Parse a cookie string @var{string}, which is the value of ``Cookie''
request header.  Usually, the same information is available to CGI
program via the environment variable @code{HTTP_COOKIE}.

If the cookie version is known, via ``Cookie2'' request header,
the integer version must be passed to @var{version}.  Otherwise,
@code{parse-cookie-string} figures out the version from @var{string}.

The result has the following format.
@example
((<name> <value> [:path <path>] [:domain <domain>] [:port <port>])
 @dots{})
@end example
where @var{<name>} is the attribute name, and @var{<value>} is
the corresponding value.  If the attribute doesn't have value,
@var{<value>} is @code{#f}.  (Note that it differs from the attribute
having null value, @code{""}.)
If the attribute has path, domain or port options, it is given
as a form of keyword-value pair.

Note: To retrieve the value of a specific cookie conveniently, you can use
@code{rfc822-header-ref} (@pxref{RFC822 message parsing}).
@end defun

@defun construct-cookie-string specs :optional version
@{@t{rfc.cookie}@}
Given list of cookie specs, creates a cookie string suitable for
@code{Set-cookie2} or @code{Set-cookie} header.

Optional @var{version} argument specifies cookie protocol version.
0 for the old Netscape style format, and 1 for RFC2965 style format.
When omitted, version 1 is assumed.

Each cookie spec has the following format.
@example
(<name> <value> [:comment <comment>] [:comment-url <url>]
                [:discard <bool>] [:domain <domain>]
                [:max-age <age>] [:path <path>]
                [:port <port-list>] [:secure <bool>] [:http-only <bool>]
                [:version <version>] [:expires <date>])
@end example
Where,
@table @code
@item <name>
A string.  Name of the cookie.
@item <value>
Value of the cookie.  May be a string, or @code{#f} if no value is needed.
@item <comment> <url> <domain> <path> <port-list>
Strings.
@item <bool>
Boolean value
@item <age> <version>
Integers
@item <date>
Either an integer (seconds since Epoch) or a formatted date string
following the netscape cookie specification.
@end table

The attribute values are quoted appropriately.  If the specified attribute
is irrelevant for the @var{version}, it is ignored.  So you can pass
the same specs to generate both old-style and new-style cookie strings.

Return value is a list of cookie strings, each of which stands for
each cookie.  For old-style protocol (using @code{Set-cookie} header)
you must send each of them by individual header.  For new-style
protocol (using @code{Set-cookie2} header), you can join them
with comma and send it at once.  See RFC6265 for further details.

Some examples:
@example
(construct-cookie-string
   `(("name" "foo" :domain "foo.com" :path "/"
                   :expires ,(+ (sys-time) 86400) :max-age 86400)))
 @result{} ("name=foo;Domain=foo.com;Path=/;Max-age=86400")

(construct-cookie-string
   `(("name" "foo" :domain "foo.com" :path "/"
                   :expires ,(+ (sys-time) 86400) :max-age 86400))
   0)
 @result{}
 ("name=foo;Domain=foo.com;Path=/;Expires=Sun, 09-Sep-2001 01:46:40 GMT")
@end example
@end defun

@c ----------------------------------------------------------------------
@node FTP, HMAC keyed-hashing, HTTP cookie handling, Library modules - Utilities
@section @code{rfc.ftp} - FTP client
@c NODE FTPクライアント, @code{rfc.ftp} - FTPクライアント

@deftp {Module} rfc.ftp
@mdindex rfc.ftp
This module provides a set of convenient functions to access ftp
servers.
@end deftp

@deftp {Class} <ftp-connection>
@clindex ftp-connection
@{@t{rfc.ftp}@}
An object to keep FTP connection to a server.  It has the following
public slots.

@defivar {<ftp-connection>} transfer-type
FTP transfer type.  Must be one of the following symbols:
@code{ascii}, @code{binary} (default), and @code{image}.
@end defivar

@defivar {<ftp-connection>} passive
True if the client uses passive connection.c
@end defivar

@defivar {<ftp-connection>} log-drain
This slot must hold a @code{<log-drain>} instance (@pxref{User-level logging})
or @code{#f}.  If it has a @code{<log-drain>} instance, ftp communication
logs are put to it.

@end defivar
@end deftp

@deftp {Condition Type} <ftp-error>
@clindex ftp-error
@{@t{rfc.ftp}@}
This type of exception is thrown when the ftp server returns an error code.
Inherits @code{<error>}.  The message field contains the server reply,
including the status code.
@end deftp

@defun call-with-ftp-connection host proc :key passive port username password account log-drain
@{@t{rfc.ftp}@}
A high-level convenience routine to open an ftp connection to
an ftp server and calls the given procedure.

The server is specified by @var{host}.  Optionally, you can add user
name and/or port number by the form
@code{@var{user}@@@var{servername}:@var{port}}.
If present, user and port portion in @var{host} supersedes the
keyword arguments.

If ftp connection to @var{host} is established successfully,
@var{proc} is called with one argument, which is an instance
of @code{<ftp-connection>}.  When @var{proc} returns,
the connection is closed and the return value(s) of @var{proc}
is/are returned from @code{call-with-ftp-connection}.
When an exception is thrown, the ftp connection is closed
before the exception escapes from @code{call-with-ftp-connection}.

When a true value is given to the keyword argument @var{passive},
created ftp connection will use passive mode to send/receive
data.  The default is the active mode.

The keyword argument @var{port}, @var{username}, and @var{password}
specify the port number, username, and password, respectively.
When omitted, the port number defaults to 21, @var{username} to
@code{"anonymous"}, and @var{password} to @code{"anonymous@@"}.
Note that the port number and/or username are ignored when
those information is given in the @var{host} argument.

If the keyword argument @var{account} is given, its value
is passed to ftp @code{ACCT} command when requested by
the server at login time.  The default value is a null string @code{""}.

The keyword argument @var{log-drain} is set to the created
ftp connection's @code{log-drain} slot.
@end defun

@defun ftp-transfer-type conn
@{@t{rfc.ftp}@}
Returns the transfer type of the ftp connection @code{conn}.
Can be used with setter, e.g. @code{(set! (ftp-transfer-type conn) 'ascii)}.
@end defun

@defun ftp-passive? conn
@{@t{rfc.ftp}@}
Returns true iff ftp connection uses passive data retrieval.
@end defun

@defun ftp-login host :key passive port username password account log-drain
@{@t{rfc.ftp}@}
Connects to the ftp server specified by @var{host}, authenticate the user,
and returns a newly created @code{<ftp-connection>} instance.
This procedure is called implicitly when you use
@code{call-with-ftp-connection}.  The semantics of
the @var{host} argument and the keyword arguments are
the same as @code{call-with-ftp-connection}.
@end defun

@defun ftp-quit conn
@{@t{rfc.ftp}@}
Sends ftp @code{QUIT} command to the connection @var{conn} and
shutdown the connection.
This procedure is called implicitly when you use
@code{call-with-ftp-connection}.

Once a connection is shut down, you cannot communicate through
this connection.
@end defun

@defun ftp-chdir conn dirname
@{@t{rfc.ftp}@}
Changes the remote directory to @var{dirname}.
@end defun

@defun ftp-remove conn path
@{@t{rfc.ftp}@}
Removes the remote file named by @var{path}.
@end defun

@defun ftp-help conn :optional option @dots{}
@{@t{rfc.ftp}@}
Sends ftp @code{HELP} commands.  @var{Option}s must be strings,
and will be passed to the @code{HELP} command arguments.
@end defun

@defun ftp-mkdir conn dirname
@{@t{rfc.ftp}@}
Creates a directory @var{dirname}.  Returns the created directory
name.
@end defun

@defun ftp-current-directory conn
@{@t{rfc.ftp}@}
Returns the current remote directory.
@end defun

@defun ftp-site conn arg
@{@t{rfc.ftp}@}
Sends ftp @code{SITE} command with the argument @var{arg}.
The @code{SITE} command's semantics depends on the server.
Returns the server reply.
@end defun

@defun ftp-rmdir conn dirname
@{@t{rfc.ftp}@}
Removes remote directory specified by @var{dirname}.
Returns the server reply.
@end defun

@defun ftp-stat conn :optional pathname
@{@t{rfc.ftp}@}
Sends ftp @code{STAT} command to the server.
RFC959 defines several different semantics of this command.
See RFC959 for the details.
Returns the server reply.
@end defun

@defun ftp-system conn
@{@t{rfc.ftp}@}
Queries the server's operating system by ftp @code{SYST} command.
Returns the server reply without status code.

@example
(call-with-ftp-connection "localhost" ftp-system)
  @result{} "UNIX Type: L8"
@end example
@end defun

@defun ftp-size conn path
@{@t{rfc.ftp}@}
Queries the size of the remote file specified by @var{path}.
Returns the integer value.

Note: The size may differ whether the connection is in ascii mode
or binary mode; furthermore, some ftp server may returns the value
only if the connection is in binary mode.  Make sure you have
desired transfer type in the connection.
@end defun

@defun ftp-mdtm conn path
@{@t{rfc.ftp}@}
Queries the modification time of the remote file specified by @var{path}.
This function returns the server's reply as is, including the status
code.  Use @code{ftp-mtime} below to obtain a parsed result.
@end defun

@defun ftp-mtime conn path :optional local-time?
@{@t{rfc.ftp}@}
Queries the modification time of the remote file specified by @var{path},
and returns the result in a @code{<date>} object
(@pxref{Time data types and procedures}).
If a true value is given to @code{local-time?}, the returned date is
in local time.  Otherwise, the returned date is in UTC.
@end defun

@defun ftp-noop conn
@{@t{rfc.ftp}@}
Sends ftp @code{NOOP} command and returns the server's reply.
@end defun

@defun ftp-list conn :optional path
@{@t{rfc.ftp}@}
Returns the information about the files within the remote file
or directory specified by @var{path}, or the current remote directory,
much like @code{ls(1)} format.  Returns a list of strings, where
each string is for each line of the server's reply.  The exact
format depends on the server.
@end defun

@defun ftp-name-list conn :optional path
@defunx ftp-ls conn :optional path
@{@t{rfc.ftp}@}
Return the list of names in the specified @var{path}, or the current
remote directory, without any other information.  @code{ftp-ls}
is just an alias of @code{ftp-name-list} for the convenience.

Note that the server may return an error if there's no files
in the remote directory.
@end defun

@defun ftp-get conn path :key sink flusher
@{@t{rfc.ftp}@}
Retrieves a remote file @var{path}.  The retrieved data is
sent to an output port given to @var{sink}.  Once all the data
is retrieved, a procedure given to @var{flusher} is called
with the port @var{sink} as an argument, and its return value(s)
is/are returned from @code{ftp-get}.

The default values of @var{sink} and @var{flusher} are
a newly created string port and @code{get-output-string}, respectively.
That is, @code{ftp-get} returns the retrieved data as a string
by default.
You don't want this behavior if the retrieved file is huge.
@end defun

@defun ftp-put conn from-file :optional to-file
@{@t{rfc.ftp}@}
Sends the local file specified by @var{from-file} to the remote
server as the name specified by @var{to-file}.  If @var{to-file}
is omitted, the basename of @var{from-file} is used.
Returns the server response.
@end defun

@defun ftp-put-unique conn from-file
@{@t{rfc.ftp}@}
Sends the local file specified by @var{from-file} to the
remote server.  The remote side filename is guaranteed to
be unique.  Returns two values---the final server response,
and the remote file name.  The second value can be @code{#f}
if the remote host doesn't support RFC1123 (which must be rare).
@end defun

@defun ftp-rename conn from-name to-name
@{@t{rfc.ftp}@}
Renames the remote file specified by @var{from-name} to the
name @var{to-name}.  Returns the final response of the server.
@end defun

@c ----------------------------------------------------------------------
@node HMAC keyed-hashing, HTTP, FTP, Library modules - Utilities
@section @code{rfc.hmac} - HMAC keyed-hashing
@c NODE HMAC鍵付きハッシング, @code{rfc.hmac} - HMAC鍵付きハッシング

@deftp {Module} rfc.hmac
@mdindex rfc.hmac
This module implements HMAC algorithm,
Keyed-hashing for message authentication, defined in RFC 2104.

For simple batched keyed hashing, you can use high-level API
@code{hmac-digest} and @code{hmac-digest-string}.
Or you can create @code{<hmac>} object and update its state
as the data coming in.
@end deftp

@deftp {Class} <hmac>
@clindex hmac
@{@t{rfc.hmac}@}
Keeps state information of HMAC algorithm.
Key and the hashing algorithm should be given at the construction
time, using @code{:key} and @code{:hasher} keyword-arguments respectively.
You can pass any class object that implements message digest
interface (@pxref{Message digester framework}),
such as @code{<md5>} (@pxref{MD5 message digest})
or @code{<sha256>} (@pxref{SHA message digest}).

Example:
@example
(make <hmac> :key (make-byte-string 16 #x0b) :hasher <md5>)
@end example
@end deftp

@deffn {Method} hmac-update! (hmac <hmac>) data
@{@t{rfc.hmac}@}
Updates the internal state of @var{hmac} by @var{data},
which must be represented by a (possibly incomplete) string.
@end deffn

@deffn {Method} hmac-final! (hmac <hmac>)
@{@t{rfc.hmac}@}
Finalizes the internal state of @var{hmac} and returns the
hashed string in incomplete string.
You can use @code{digest-hexify}
(@pxref{Message digester framework}) to obtain "hexified"
result.
Once finalized, you can't call @code{hmac-update!} or @code{hmac-final!}
on @var{hmac}.
@end deffn

@deffn {Method} hmac-digest :key key hasher
@{@t{rfc.hmac}@}
Creates an @code{<hmac>} object and hash the data stream
from the current input port, then returns the hashed result
in an incomplete string.
@end deffn

@deffn {Method} hmac-digest-string string :key key hasher
@{@t{rfc.hmac}@}
Creates an @code{<hmac>} object and hash the data in @var{string},
then returns the hashed result in an incomplete string.
@end deffn

@c ----------------------------------------------------------------------
@node HTTP, ICMP packets, HMAC keyed-hashing, Library modules - Utilities
@section @code{rfc.http} - HTTP

@deftp {Module} rfc.http
@mdindex rfc.http
This module provides a simple client API for
HTTP/1.1, defined in RFC2616, "Hypertext Transfer Protocol -- HTTP/1.1"
(@uref{https://www.ietf.org/rfc/rfc2616.txt}).

Current API implements only a part of the protocol.
It doesn't talk with HTTP/1.0 server yet,
and it doesn't support HTTP/1.1 advanced features
such as persistent connection.
Support for those features may be added in the future versions.
@end deftp

@deftp {Condition Type} <http-error>
@clindex http-error
@{@t{rfc.http}@}
This type of condition is raised when the server terminates
connection prematurely or server's response has invalid
header fields.  Inherits @code{<error>}.
@end deftp

@defun http-get server request-uri :key sink flusher redirect-handler secure @dots{}
@defunx http-head server request-uri :key redirect-handler secure @dots{}
@defunx http-post server request-uri body :key sink flusher redirect-handler secure @dots{}
@defunx http-put server request-uri body :key sink flusher redirect-handler secure @dots{}
@defunx http-delete server request-uri :key sink flusher redirect-handler secure @dots{}
@{@t{rfc.http}@}
Send http GET, HEAD, POST, PUT and DELETE requests to the http @var{server},
respectively, and returns the server's reply.

By default, if the server returns 300, 301, 302, 303, 305 and 307 status,
these procedures attempts to fetch the redirected URL by the
"location" reply message header if it is allowed by RFC2616.
This behavior can be turned off or customized by the @var{redirect-handler}
keyword argument;
see the "keyword arguments" heading below for the details.

@strong{Required arguments:}
The @var{server} argument specifies http server name in a string.
A server name can be optionally followed by colon and a port number.
You can use IP address, too; for IPv6, you have to surround the
address in brackets.

Additionally, you can specify @code{"unix:/path"} where @code{/path}
is the absolute path to the unix domain socket; this allows to connect
to httpd listening on unix domain sockets.
Examples: @code{"w3c.org"}, @code{"mycompany.com:8080"}, 
@code{"192.168.0.1:8000"}, @code{"[::1]:8000"}

The @var{request-uri} argument can be a string or a list.
If it is a string, it's @emph{request-uri} specified in
RFC2616; usually, this is the path part of http url.
The string is passed to the server as is, so the caller must
properly convert character encodings and perform necessary
url encodings.

If @var{request-uri} is a list, it must be in the following form:

@example
(@var{path} (@var{name} @var{value}) ...)
@end example

Here, @var{path} is a string specifying up to the path component
of the request-uri.
From provided alist of @var{name}s and @var{value}s,
http procedures compose a query string in
@code{application/x-www-form-urlencoded} format
as defined in HTML4, and append it to @var{path}.
For example, the following two requests have the same effect.
Note that url escaping is automatically handled in the second call.

@example
(http-get "example.com" "/search?q=foo%20bar&n=20")

(http-get "example.com" '("/search" (q "foo bar") (n 20)))
@end example

If @var{request-encoding} keyword argument is also given,
@var{name}s and @var{value}s
are converted into the specified character encoding before url escaping.
If it is omitted, gauche's internal character encoding is used.

Some procedures take the third argument, @var{body},
to specify the body of the request message.
It can be a string, which will be copied verbatim to the request body,
or a list, which will be encoded in @code{multipart/form-data} message.

If @var{body} is a list, it is a list of parameter specs.  Each parameter
spec is either a list of name and value, e.g.
@code{("submit" "OK")} or a name followed by keyword-value list,
e.g. @code{("upload" :file "logo.png" :content-type "image/png")}.

The first form is for the convenience.  It is also compatible to the
query parameter list in @var{request-uri}, so that you can use the
same format for GET and POST request.  Each value is put
in a MIME part with @code{text/plain} media type, with the
character encoding specified by @code{request-encoding} keyword argument
described below.

The second form allows further control over each MIME part's attributes.
The following keywords are treated specially.

@table @code
@item :value
Specifies the value of the parameter.  The convenience form,
@code{(@var{name} @var{val})}, is just an abbreviation of
@code{(@var{name} :value @var{val})}.
@item :file
Specifies the pathname of the file, whose content is inserted
as the value of the parameter.  Useful to upload a file.
This option has precedence over @code{:value}.
MIME type of the part is set to @code{application/octet-stream}
unless specified otherwise.
@item :content-type
Overrides the MIME type of the part.  A charset parameter is
added to the content-type if not given in this argument.
@item :content-transfer-encoding
Specifies the value of content-transfer-encoding; currently the
following values are supported: @code{7bit},
@code{binary}, @code{quoted-printable} and @code{base64}.
If omitted, @code{binary} is used.
@end table

Other keywords are used as the header of the MIME part.

@strong{Return values:}
All procedures return three values.

The first value is the status code defined in RFC2616
in a string (such as "200" for success, "404" for "not found").

The second value is a list of parsed headers---each element of list
is a list of @code{(@var{header-name} @var{value} @dots{})},
where @var{header-name} is a string name of the header
(such as "content-type" or "location"), and @var{value} is
the corresponding value in a string.  The header name is converted
to lowercase letters.  The value is untouched except that "soft line breaks"
are removed, as defined in RFC2822.   If the server returns
more than one headers with the same name, their values are
consolidated to one list.  Except that, the order of the header list
in the second return value is the same as the order in the server's reply.

The third value is for the message body of the server's reply.
By default, it is a message body itself in a string.   If the server's
reply doesn't have a body, the third value is @code{#f}.  You can
change how the message body is handled by keyword arguments; for example,
you can directly store the returned message body to a file without
creating intermediate string.  The details are explained below.

@strong{Keyword arguments:}
By default, these procedures only attaches @code{"Host"} header
field to the request message.  You can give keyword arguments
to add more header fields.
@example
(http-get "foo.bar.com" "/index.html"
  :accept-language "ja"
  :user-agent "My Scheme Program/1.0")
@end example

The following keyword arguments are recognized by the procedure
and do not appear in the request headers.

@table @code
@item request-encoding
When a list is given to the @var{request-uri} or @var{body} arguments,
the characters in names and values of the parameters are first
converted to the character encoding specified by this keyword
argument, then encoded into @code{application/x-www-form-urlencoded}
or @code{multipart/form-data} MIME formats.
If this argument is omitted, Gauche's internal character encoding is used.

For @code{multipart/form-data}, you can override character encodings
for individual parameters by giving @code{content-type} header.
See the description of @var{body} arguments above.

If you give a string to @var{request-uri} or @var{body},
it is used without encoding conversion.  It is caller's responsibility
to ensure desired character encodings are used.
@item proxy
Specify http proxy server in a string of a form @code{hostname} or
@code{hostname:port}.  If omitted, the value of the parameter
@code{http-proxy} is used.
@item redirect-handler
Specifies how the redirection is handled when the server responds with
3xx status code.
You can pass @code{#f}, @code{#t} or a procedure.  The default is @code{#t}.

If @code{#f} is given, no redirect attempt will be made; the 3xx status
code and response is just returned from @code{http-*} procedures as they are.

If a procedure is given, it is called when the response status code
is 3xx.  The procedure takes four arguments, the request method (in symbol,
e.g. @code{GET}), the response status code (in string, e.g. @code{"302"}),
the parsed response headers and the response body (a string
if there's a body, or @code{#f} if the response doesn't have a body).

The procedure can return a pair or @code{#f}.
If it is a pair, it should be @code{(method . url)}, where @var{method}
is a symbol (e.g. @code{GET}) and @var{url} is a string representing url.
If a pair is returned, the @code{http-*} procedures tries to send
the request with the given method (it allows a redirection of POST request
to be GET, for example).  If it is @code{#f}, no further attempt of
redirection is made.

If @var{redirect-handler} is @code{#t}, which is the default,
then it works as if the value of the parameter
@code{http-default-redirect-handler} is passed to @var{redirect-handler}.
The parameter contains a procedure with reasonable default behavior.
See the @code{http-default-redirect-handler} entry below for the details.

A loop in redirection is detected automatically and @code{<http-error>}
is thrown.
@item no-redirect
This is an obsoleted keyword argument kept only for the backward
compatibility.  If a true value is given, it has the same effect
as specifying @code{#f} to @var{redirect-handler}.
@item secure
If a true value is given, the secure connection is used.  The value
specifies the secure transport agent to establish https connection.
It can be @code{#t} or a symbol @code{tls} or @code{stunnel}.
If @code{#f} is given (default), non-secure plain http is used.
See the ``Secure connection'' section below.
@item auth-user, auth-password
If given, the authorization header using Basic Authentication
(RFC2617) is added to the request.
In future, we might add support for other authentication scheme.
@item sink, flusher
You can customize how the reply message body is handled by these
keyword arguments.  You have to pass an output port to @var{sink},
and a procedure that takes two arguments to @var{flusher}.

When the procedure starts receiving the message body, it
feeds the received chunk to @var{sink}.  When the procedure
receives entire message body, @var{flusher} method is called
with @var{sink} and a list of message header fields (in the
same format to be returned in the second value from the procedure).
The return value of @var{flusher} becomes the third return value
from the procedure.

So, the default value of @var{sink} is a newly opened string
port and the default value of @var{flusher} is
@code{(lambda (sink headers) (get-output-string sink))}.

The following example saves the message body directly to a file,
without allocating (potentially very big) string buffer.
@example
(call-with-output-file "page.html"
  (lambda (out)
    (http-get "www.schemers.org" "/"
       :sink out :flusher (lambda _ #t))))
@end example

@end table

@end defun

The module also provides some utility procedures.

@deffn {Parameter} http-user-agent :optional value
@{@t{rfc.http}@}
The value of this parameter is used as a default value
to pass to the user-agent header.
The default value is something like @code{gauche.http/*},
where @code{*} is Gauche's version.
An application is encouraged to set this parameter appropriately.
@end deffn

@deffn {Parameter} http-proxy :optional value
@{@t{rfc.http}@}
This value is used as the default http proxy name by @code{http-get} etc.
The default value is @code{#f} (no proxy).
@end deffn

@deffn {Parameter} http-default-redirect-handler :optional value
@{@t{rfc.http}@}
Specifies the behavior of redirection if no @code{redirect-handler} keyword
argument is given to the @code{http-*} procedures.
If you change this value, it must be a procedure that follows the
protocol of @code{redirect-handler}; see the description of @code{http-*}
procedures above.

The default behavior is as follows:

@table @asis
@item @code{300}, @code{301}, @code{305}, @code{307}
Redirect to the url given to the @code{location} header only if
the original request method is @code{GET} or @code{HEAD}.
@item @code{302}
Redirect to the url given to the @code{location} header.  If
the original request method is @code{HEAD}, it is used again.
Otherwise, @code{GET} method is used.

Strictly speaking, this is a violation of RFC2616.  However, as the note
in RFC2616 says, many user agent do this, so we follow the flock.
(We may change this in future.)
@item @code{303}
Redirect to the url given to the @code{location} header.  If
the original request method is @code{HEAD}, it is used again.
Otherwise, @code{GET} method is used.
@item other than above
No redirection is made.
@end table

The following code is an example of intercepting the default
behavior in a specific request:

@example
(http-get server uri
  :redirect-handler
  (^[method status headers body]
    (if (and (equal? status "302")
             (not (member method '(GET HEAD))))
        #f
        ((http-default-request-handler) method status headers body))))
@end example
@end deffn


@defun http-compose-query path params :optional encoding
@{@t{rfc.http}@}
A helper procedure to create a request-uri from
a list of query parameters.  @var{Encoding} specifies
the character encodings to be used.

@example
(http-compose-query "/search" '((q "$foo") (n 20)))
 @result{} "/search?q=%24foo&n=20"

(http-compose-query "" '((x "a b") (x 2)))
 @result{} "?x=a%20b&x=2"
@end example

If @var{path} is @code{#f}, only the query parameter part
is returned (compare the following example and the last
example):

@example
(http-compose-query #f '((x "a b") (x 2)))
 @result{} "x=a%20b&x=2"
@end example
@end defun

@defun http-compose-form-data params port :optional encoding
@{@t{rfc.http}@}
A helper procedure to create @code{multipart/form-data}
from a list of parameters.  The format of @var{params} argument
is the same as the list format of @var{body} argument of
http request procedures.  The result is written to an output
port @var{port}, and the boundary string used to compose
MIME message is returned.  Alternatively you can pass @code{#f}
to the @var{port} to get the result in a string.
In that case, two values are returned, the MIME message string
and the boundary string.

@var{Encoding} specifies the character encodings to be used.
When omitted, Gauche's native encoding is used.

@example
(define p (open-output-string))

(http-compose-form-data '((name "Preludes and Fugues")
                          (composer "Shostakovich, Dmitri")
                          (opus "87"))
                         p)
  @result{} "boundary-fh87o52rp6zkubp2uhdmo"

(get-output-string p)
  @result{}
  "\r\n--boundary-fh87o52rp6zkubp2uhdmo\r\nContent-type: te
   xt/plain; charset=utf-8\r\nContent-transfer-encoding: bi
   nary\r\ncontent-disposition: form-data; name=title\r\n\r\n
   Preludes and Fugues\r\n--boundary-fh87o52rp6zkubp2uhdmo...
;; (result is truncated)
@end example
@end defun

@defun http-status-code->description code
@{@t{rfc.http}@}
Returns a brief description of http status code @code{code},
which may be an integer or a string (e.g. @code{"404"}).
If @code{code} isn't one of known code, @code{#f} is returned.

@example
(http-status-code->description 404)
  @result{} "Not Found"
@end example
@end defun


@subheading Secure connection

When you pass a true value to @code{secure} keyword argument,
the request-making APIs such as @code{http-get} use a secure
connection.  That is, it connects with @code{https} instead of
@code{http}.  The actual value for the keyword argument can be one of the
followings:

@table @code
@item #t
@itemx tls
The @code{rfc.tls} module is used for the secure connection.
@xref{Transport layer security}, for the details---you might need to
set CA certificate bundle path.
@item stunnel
The external process @code{stunnel} is spawned and used for the
secure connection.
@item #f
Secure connection is not used.
@end table

If specified secure connection subsystem isn't available in the running Gauche,
an error is signaled.
Use the following procedure to check if you can use secure
connections:

@defun http-secure-connection-available? :optional type
@{@t{rfc.http}@}
The @var{type} argument may be @code{tls} or @code{stunnel}.
If omitted, @code{tls} is assumed.
Returns @code{#t} if running Gauche can use secure connection of the given type,
@code{#f} otherwise.
@end defun

@c ----------------------------------------------------------------------
@node ICMP packets, IP packets, HTTP, Library modules - Utilities
@section @code{rfc.icmp} - ICMP packets
@c NODE ICMPパケット, @code{rfc.icmp} - ICMPパケット

@deftp {Module} rfc.icmp
@mdindex rfc.icmp
@{@t{rfc.icmp}@}
This module provides some basic utilities to construct and parse ICMP
packets.
@end deftp

For the functions below, @var{buffer} should be a writable
u8vector of the enough size.

Parsing functions takes @var{offset} as well as @var{buffer},
which specifies the beginning of the ICMP packet.  Using the offset
you can carry the whole IP packet in @var{buffer}, without
creating a new buffer to extract ICMP portion.

@defun icmp4-fill-echo! buffer ident sequence data
@{@t{rfc.icmp}@}
Fills @var{buffer} with the ICMPv4 Echo Request packet.
@var{Data} must be a u8vector.  The checksum field is
left to be zero, which can be filled by @code{icmp4-fill-checksum!}.
@end defun

@defun icmp4-fill-checksum! buffer size
@{@t{rfc.icmp}@}
Calculates the ICMPv4 checksum of the packet in the @var{buffer},
of @var{size} length (the size of the packet, not the buffer),
and fills the checksum field of the packet.
@end defun

@defun icmp6-fill-echo! buffer ident sequence data
@{@t{rfc.icmp}@}
Fills @var{buffer} with the ICMPv6 Echo Request packet.
@var{Data} must be a u8vector.  The checksum field is
left to be zero, which is to be filled by the kernel
(so you don't need to fill by yourself).
@end defun

@defun icmp-packet-type buffer offset
@defunx icmp-packet-code buffer offset
@defunx icmp-packet-ident buffer offset
@defunx icmp-packet-sequence buffer offset
@{@t{rfc.icmp}@}
Extracts type, code, ident and sequence fields of ICMP packet.
These functions are common to both ICMPv4/v6.
@end defun

@defun icmp4-describe-packet buffer offset
@defunx icmp6-describe-packet buffer offset
@{@t{rfc.icmp}@}
Prints out a simple text description of the given ICMPv4 and v6 packet,
respectively.
@end defun

@defun icmp4-message-type->string type
@defunx icmp4-unreach-code->string code
@defunx icmp4-redirect-code->string code
@defunx icmp4-router-code->string code
@defunx icmp4-exceeded-code->string code
@defunx icmp4-parameter-code->string code
@defunx icmp4-security-code->string code
@defunx icmp6-message-type->string type
@defunx icmp6-unreach-code->string code
@defunx icmp6-exceeded-code->string code
@defunx icmp6-parameter-code->string code
@{@t{rfc.icmp}@}
Returns a text description of ICMPv4 and ICMPv6 types and codes.
@end defun

@c ----------------------------------------------------------------------
@node IP packets, JSON parsing and construction, ICMP packets, Library modules - Utilities
@section @code{rfc.ip} - IP packets
@c NODE IPパケット, @code{rfc.ip} - IPパケット

@deftp {Module} rfc.ip
@mdindex rfc.ip
This module provides some basic utilities to parse raw IP packets.
@end deftp

The @var{packet} argument in the following functions must be
any type of uniform vector (@pxref{Uniform vectors}), containing
a raw IP packet including its IP header.
Those functions work for both IPv4 and IPv6 packets; however,
reading from a raw IPv6 socket returns a packet without IPv6 header,
so you usually don't need to use these functions.

The @var{offset} argument specifies the beginning of the IP packet
in @var{packet}.  If @var{packet} contains only one IP packet
you can pass 0.  It is not an optional argument, since these routines
may be used in speed-sensitive inner loop.

@defun ip-version packet offset
@{@t{rfc.ip}@}
Returns the IP version number (either 4 or 6) of the given IP packet.
@end defun

@defun ip-header-length packet offset
@{@t{rfc.ip}@}
Returns the size of IP header of the given packet in octets,
including any IP header options.
@end defun

@defun ip-protocol packet offset
@{@t{rfc.ip}@}
Returns the IP protocol number of the given packet.
@end defun

@defun ip-source-address packet offset
@defunx ip-destination-address packet offset
@{@t{rfc.ip}@}
Returns the source and destination address in the given packet
in an integer, respectively.
@end defun


@c ----------------------------------------------------------------------
@node JSON parsing and construction, MD5 message digest, IP packets, Library modules - Utilities
@section @code{rfc.json} - JSON parsing and construction
@c NODE JSONのパーズと構築, @code{rfc.json} - JSONのパーズと構築

@deftp {Module} rfc.json
@mdindex rfc.json
Procedures to parse JSON (RFC7159) data to S-expressions,
and convert S-expressions to JSON representation, are provided.
@end deftp

@deftp {Condition type} <json-parse-error>
@{@t{rfc.json}@}
The parser @code{parse-json} and @code{parse-json-string} raise
this condition when they encounter
invalid JSON syntax.  It inherits @code{<error>}, and adds the following
slot.

@defivar {<json-parse-error>} position
The input position, counted in characters, where the error occurred.
@end defivar
@end deftp

@deffn {Parameter} json-nesting-depth-limit
[SRFI-180]
@{@t{rfc.json}@}
Its value must be a real number, specifying the maximum nesting depth
of JSON text that can be parsed by @code{parse-json}.  If the input
exceeds the value, an @code{<json-parse-error>} is thrown.
The default value is @code{+inf.0}.
@end deffn


@defun parse-json :optional input-port
@{@t{rfc.json}@}
Reads and parses the JSON representation from @var{input-port} (default is
the current input port), and returns the result in an S-expression.
May raise a @code{<json-parse-error>} condition when parse error occurs,
or the nesting level exceeds the value of @code{json-nesting-depth-limit}.

The following table shows how JSON datatypes are
mapped to Scheme objects.

@table @asis
@item @code{true}, @code{false}, @code{null}
Symbols @code{true}, @code{false} and @code{null}.
(Customizable by @code{json-special-handler})
@item Arrays
Scheme vectors.  (Customizable by @code{json-array-handler})
@item Objects
Scheme assoc-lists, in which keys are strings, and values
are Scheme objects.  (Customizable by @code{json-object-handler})
@item Numbers
Scheme inexact real numbers.
@item Strings
Scheme strings.
@end table

Since the parser used internally in @code{parse-json} prefetches
characters, some characters after the parsed JSON expression
may already been read from @var{port} when @code{parse-json} returns.
That is, you cannot call @code{parse-json} repeatedly on @var{port}
to read subsequent JSON expressions.  Use @code{parse-json*} if you
need to read multiple JSON expressions.
@end defun

@defun parse-json* :optional input-port
@{@t{rfc.json}@}
Read JSON repeatedly from @var{input-port} until it reaches EOF,
and returns parsed results as a list.
@end defun

@defun parse-json-string str
@{@t{rfc.json}@}
Parses the JSON string and returns the result in an S-expression.
May raise a @code{<json-parse-error>} condition when parse error occurs.

See @code{parse-json} above for the mappings from JSON datatypes
to Scheme types.
@end defun

@deffn {Parameter} json-array-handler
@deffnx {Parameter} json-object-handler
@deffnx {Parameter} json-special-handler
@{@t{rfc.json}@}
The value of these parameters must be a procedure that takes
one argument: for @code{json-array-handler}, it is a list of
elements of a JSON array, for @code{json-object-handler},
it is a list of conses of key and value of a JSON object,
and for @code{json-special-handler}, it is one of the
symbols @code{false}, @code{true} or @code{null}.

Whenever @code{parse-json} reads a JSON array, a JSON object,
or one of those special values,
it calls corresponding parameter to get a Scheme object.

The default value of these parameters are @code{list->vector},
@code{identity}, and @code{identity}, respectively.

The following example maps JSON objects to hash tables.

@example
(parameterize ([json-object-handler (cut alist->hash-table <> 'string=?)])
  (parse-json-string "@{\"a\":1, \"b\":2@}"))
 @result{} #<hash-table ...>
@end example
@end deffn


@deftp {Condition type} <json-construct-error>
@{@t{rfc.json}@}
The converters @code{construct-json} and
@code{construct-json-string} raise this condition
when they cannot convert given Scheme object to JSON.
It inherits @code{<error>}, and adds the following slot.

@defivar {<json-construct-error>} object
The Scheme object that cannot convert to JSON representation.
@end defivar
@end deftp

@defun construct-json obj :optional output-port
@defunx construct-json-string obj
@{@t{rfc.json}@}
Creates JSON representation of Scheme object @var{obj}.
@code{construct-json} writes out the result to @var{output-port},
whose default is the current output port.  @code{construct-json-string}
returns the result in a string.

If @var{obj} contains a Scheme object that cannot be mapped
to JSON representation, a @code{<json-construct-error>} condition
is raised.

Scheme objects are mapped to JSON as follows:

@table @asis
@item symbol @code{false}, @code{#f}
@code{false}
@item symbol @code{true}, @code{#t}
@code{true}
@item symbol @code{null}
@code{null}
@item list, instance of @code{<dictionary>}
JSON object (list must be an assoc list of key and value).
@item string
string
@item real number
number
@item instance of @code{<sequence>} (except strings and lists)
JSON array
@end table

@end defun

@c ----------------------------------------------------------------------
@node MD5 message digest, MIME message handling, JSON parsing and construction, Library modules - Utilities
@section @code{rfc.md5} - MD5 message digest
@c NODE MD5メッセージダイジェスト, @code{rfc.md5} - MD5メッセージダイジェスト

@deftp {Module} rfc.md5
@mdindex rfc.md5
This module implements MD5 message digest algorithm, defined in
RFC 1321 (@uref{https://www.ietf.org/rfc/rfc1321.txt}).
The module extends util.digest
(@pxref{Message digester framework}).
@end deftp

@deftp {Class} <md5>
@clindex md5
@{@t{rfc.md5}@}
The instance of this class keeps internal state of MD5 digest algorithm.

This class implements @code{util.digest} framework interface,
@code{digest-update!}, @code{digest-final!},
@code{digest}, and @code{digest-string}.
@xref{Message digester framework}, for detailed explanation
of these methods.
@end deftp

Besides the digester framework, this module provides to
short-cut procedures.

@defun md5-digest
@{@t{rfc.md5}@}
Reads data from the current input port until EOF, and returns
its digest in an incomplete string.
@end defun

@defun md5-digest-string string
@{@t{rfc.md5}@}
Digest the data in @var{string}, and returns the result
in an incomplete string.
@end defun

@c ----------------------------------------------------------------------
@node MIME message handling, Quoted-printable encoding/decoding, MD5 message digest, Library modules - Utilities
@section @code{rfc.mime} - MIME message handling
@c NODE MIMEメッセージ処理, @code{rfc.mime} - MIMEメッセージ処理

@deftp {Module} rfc.mime
@mdindex rfc.mime
This module provides utility procedures to handle
Multipurpose Internet Mail Extensions (MIME) messages,
defined in RFC2045 thorough RFC2049.
Provided APIs include procedures to parse or compose MIME-specific
header fields, and parse or compose MIME-encoded message bodies.

This module mainly focuses on providing low-level building-block procedures,
on top of which application-specific modules are to be built.
For example, @code{rfc.http} uses this module to compose
@code{multipart/form-data} message for the body of POST requests
(@pxref{HTTP}).

This module is supposed to be used with @code{rfc.822} module
(@pxref{RFC822 message parsing}).
@end deftp

@subheading Utilities for header fields

A few utility procedures to parse and generate MIME-specific header fields.

@defun mime-parse-version field
@{@t{rfc.mime}@}
If @var{field} is a valid header field for MIME-Version, returns
its major and minor versions in a list.  Otherwise, returns @code{#f}.
It is allowed to pass @code{#f} to @var{field}, so that
you can directly pass the result of @code{rfc822-header-ref} to it.
Given parsed header list by @code{rfc822-read-headers}, you can
get mime version (currently, it should be @code{(1 0)}) by the
following code.
@example
(mime-parse-version (rfc822-header-ref headers "mime-version"))
@end example

Note: simple regexp such as @code{#/\d+\.\d+/} doesn't do this job,
for @var{field} may contain comments between tokens.
@end defun

@defun mime-parse-content-type field
@{@t{rfc.mime}@}
Parses the "content-type" header field, and returns a list such as:
@example
(@i{type} @i{subtype} (@i{attribute} . @i{value}) @dots{})
@end example
where @i{type} and @i{subtype} are MIME media type and
subtype in a string, respectively

@example
(mime-parse-content-type "text/html; charset=iso-2022-jp")
 @result{} ("text" "html" ("charset" . "iso-2022-jp"))
@end example

If @var{field} is not a valid content-type field, @code{#f} is
returned.
@end defun

@defun mime-parse-content-disposition field
@{@t{rfc.mime}@}
Parses Content-disposition header field as specified in RFC2183.
(mime-parse-content-disposition "attachment; filename=genome.jpeg;\
  modification-date=\"Wed, 12 Feb 1997 16:29:51 -0500\";")
 @result{} ("attachment"
      ("filename" . "genome.jpeg")
      ("modification-date" . "Wed, 12 Feb 1997 16:29:51 -0500"))
@end defun


@defun mime-parse-parameters :optional iport
@defunx mime-compose-parameters params :optional oport :key start-column
@{@t{rfc.mime}@}
These are low-level utility procedures to parse and compose @emph{parameter}
part of header fields (as appeared in RFC2045 Section 5.1 etc).

@code{Mime-parse-parameters} reads the parameter
part of the header body from an input port @var{iport}, and
returns an assoc list of the parameter names and values.
Conversely, @code{mime-compose-parameters} takes an assoc
list of names and values, compose parameter part and
emit it to @var{oport}.   When omitted, the current input
port and the current output port are used for @var{iport}
and @var{oport}, respectively.  You can pass @code{#f} to
@var{oport} and @code{mime-compose-parameters} returns the
result in a string instead of emitting it to a port.

@example
(call-with-input-string
   "; name=foo; filename=\"foo/bar/baz\""
   mime-parse-parameters)
 @result{} (("name" . "foo") ("filename" . "foo/bar/baz"))

(mime-compose-parameters
 '(("name" . "foo") ("filename" . "foo/bar/baz"))
 #f)
 @result{} "; name=foo; filename=\"foo/bar/baz\""
@end example

@code{Mime-compose-parameters} tries to insert folding line breaks
between parameters to avoid the header line becomes too long.
You can pass the beginning column position of the parameter
part via @var{start-column} argument.

We plan to make these procedures handle RFC2231's parameter value
extension transparently in future.
@end defun


@defun mime-decode-word word
@{@t{rfc.mime}@}
Decodes RFC2047-encoded word.  If @var{word} isn't an encoded word,
it is returned as is.

Note that this procedure decodes only if the entire @var{word} is
an ``encoded word'' defined in RFC2047.  If you are dealing with
a field that may contain multiple encoded word and/or unencoded parts,
use @code{mime-decode-text} below.

@example
(mime-decode-word "=?iso-8859-1?q?this=20is=20some=20text?=")
 @result{} "this is some text"
@end example

@end defun
@defun mime-decode-text text
@{@t{rfc.mime}@}
Returns a string in which
all encoded words contained within @var{text} are decoded.
This procedure can deal with a header field body that may contain
mixture of non-encoded and encoded parts, and/or multiple encoded
parts.  One of such header field is the Subject field of email.

@example
(mime-decode-text "This is =?US-ASCII?q?some=20text?=")
 @result{} "This is some text"
@end example

Care should be taken if you apply this procedure to a ``structured''
header field body (see RFC2822 section 2.2.2).
The proper way of parsing a structured header field body is
to tokenize it first, then to decode each word using @code{mime-decode-word}.
since the decoded text may contain characters that affects the tokenization.
(However, if you can just show the header field in human readable way
for informational purposes, you may just use @code{mime-decode-text}
on entire header field for the convenience).
@end defun

@defun mime-encode-word word :key charset transfer-encoding
@{@t{rfc.mime}@}
Encodes @var{word} in the RFC2047 format.  The keyword
argument @var{charset} specifies the character encoding scheme
in string or symbol.
whose default is @code{utf-8}.  If @var{charset} differs from
Gauche's internal encoding and @var{word} is a complete string,
the procedure converts the character encoding to @var{charset},
then performs transfer encoding.

@example
(mime-encode-word "this is some text")
 @result{} "=?utf-8?B?dGhpcyBpcyBzb21lIHRleHQ=?="
@end example

The keyword argument @var{transfer-encoding} specifies how
the octets are encoded to transfer-safe characters.  You can
give a symbol @code{b}, @code{B} or @code{base64} for Base64,
and @code{Q}, @code{q}, @code{quoted-printable} for Quoted-printable
transfer encodings.  An error is raised if you pass values other
than those.  The default is Base64 encoding.

This procedure does not consider the length of the resulting
encoded word, which RFC2047 recommends to be less than 75 octets.
Use @code{mime-encode-text} below to conform the line length limit.

(Note: In most Gauche procedures, a keyword argument @code{encoding}
is used to specify character encodings.  In this context we have
two encodings, however, and to avoid the confusion we chose to use
the terms ``charset'' and ``transfer-encoding'' that appear in
RFC documents.)
@end defun

@defun mime-encode-text text :key charset transfer-encoding line-width start-column force
@{@t{rfc.mime}@}
Encode @var{text} in RFC2047 format if necessary, and considering
line folding if the result gets too long.

The keyword arguments @var{charset} and @var{transfer-encoding} are the same
as @code{mime-encode-word}.

If the @var{text} only consists of printable ASCII characters,
no encoding is done, and only line folding is considered.
However, if a true value is given to the @var{force} argument,
even ASCII-only @var{text} is encoded.

The @var{line-width} specifies the maximum line width of the result.
Its default is 76.
If the encoded word gets too long, it is splitted to multiple encoded
words and CR LF SPC sequence (``folding white space'' defined in RFC2822)
are inserted inbetween.
You can suppress this behavior by passing @code{#f} or @code{0} to
@var{line-width}.
Since encoded word needs some overhead characters, it doesn't make much sense
to specify small value to @code{line-width}.  Current implementation
rejects @code{line-width} smaller than 30.

The @var{start-column} keyword argument can be used to
shorten the first of folded
lines to make room for header field name.  For example, if
you want to encode the body of a Subject header field,
you can pass the value of @code{(string-length "Subject: ")} so that
the encoded result can directly concatenated after the header
field name.  The default value is 0.

This procedure is not designed to encode parts of structured
header fields, which have further restrictions such as which parts
can be encoded and where the folding white spaces can be inserted.
The robust way is to encode some parts first, then construct
a structured header fields, considering line folding.
@end defun

@subheading Streaming parser

The streaming parser is designed so that you can decide how
to do with the message body before the entire message is read.

@defun mime-parse-message port headers handler
@{@t{rfc.mime}@}
The fundamental streaming parser.  @var{Port} is an input port
from where the message is read.  @var{Headers} is a list of headers
parsed by @code{rfc822-read-headers}; that is, this procedure
is supposed to be called after the header part of the message
is parsed from @var{port}:
@example
(let* ((headers (rfc822-read-headers port)))
  (if (mime-parse-version (rfc822-header-ref headers "mime-version"))
     ;; parse MIME message
     (mime-parse-message port headers handler)
     ;; retrieve a non-MIME body
     ...))
@end example

@code{Mime-parse-message} analyzes @var{headers}, and calls
@var{handler} on each message body with two arguments:

@example
(handler @var{part-info} @var{xport})
@end example

@var{Part-Info} is a @code{<mime-part>} structure described below
that encapsulates the information of this part of the message.
@var{Xport} is an input port, initially points to the beginning
of the body of message.  The handler can read from the port
as if it is reading from the original @var{port}.  However,
@var{xport} recognizes MIME boundary internally, and returns EOF
when it reaches the end of the part.
(Do not read from the original @var{port} directly, or it will mess up
the internal state of @var{vport}).

@var{Handler} can read the part into the memory, or
save it to the disk, or even discard the part.
Whatever it does, it has to read from @var{vport} until it
returns EOF.

The return value of @var{handler} will be set in
the @code{content} slot of @var{part-info}.
If the message has nested multipart messages, @var{handler} is
called for each "leaf" part, in depth-first order.  @var{Handler}
can know its nesting level by examining @var{part-info} structure.
The message doesn't need to be a multipart type; if it is a
MIME @code{message} type, @var{handler} is called on the body
of enclosed message.  If it is other media types such as @code{text}
or @code{application}, @var{handler} is called on the (only) message body.
@end defun

@deftp {Class} <mime-part>
@clindex mime-message
@{@t{rfc.mime}@}
A structure that encloses metainformation about a MIME part.
It is constructed when the header of the part is read, and
passed to the handler that reads the body of the part.

It has the following slots:

@defivar {<mime-part>} type
MIME media type string.  If @code{content-type} header is omitted
to the part, an appropriate default value is set.
@end defivar

@defivar {<mime-part>} subtype
MIME media subtype string.  If @code{content-type} header is omitted
to the part, an appropriate default value is set.
@end defivar

@defivar {<mime-part>} parameters
Associative list of parameters given to @code{content-type} header field.
@end defivar

@defivar {<mime-part>} transfer-encoding
The value of @code{content-transfer-encoding} header field.
If the header field is omitted, an appropriate default value is set.
@end defivar

@defivar {<mime-part>} headers
The list of header fields, as parsed by @code{rfc822-read-headers}.
@end defivar

@defivar {<mime-part>} parent
If this is a part of multipart message or encapsulated message,
points to the enclosing part's @code{<mime-part>} structure.
Otherwise @code{#f}.
@end defivar

@defivar {<mime-part>} index
Sequence number of this part within the same parent.
@end defivar

@defivar {<mime-part>} content
If this part is multipart/* or message/* media type,
this slot contains a list of parts within it.
Otherwise, the return value of @var{handler} is stored.
@end defivar

@defivar {<mime-part>} source
This slot is only used when composing a MIME message.
The caller can set this slot a name of the file to be inserted
into this part, instead of setting the entire content of the
file to the @code{content} slot.   See
@code{mime-compose-message} below for the more details.
@end defivar
@end deftp

@defun mime-retrieve-body part-info xport outp
@{@t{rfc.mime}@}
A procedure to retrieve message body.  It is intended to
to be a building block of @var{handler} to be passed to
@code{mime-parse-message}.

@var{Part-info} is a @code{<mime-part>} object.
@var{Xport} is an input port passed to the handler,
from which the MIME part can be read.
This procedure read from @var{xport}
until it returns EOF.  It also looks at the
@code{transfer-encoding} of @var{part-info}, and decodes
the body accordingly; that is, base64 encoding and
quoted-printable encoding is handled.  The result is
written out to an output port @var{outp}.

This procedure does not handle charset conversion.
The caller must use CES conversion port as @var{outp}
(@pxref{Character code conversion}) if desired.
@end defun

A couple of convenience procedures are defined for typical
cases on top of @code{mime-retrieve-body}.

@defun mime-body->string part-info xport
@defunx mime-body->file part-info xport filename
@{@t{rfc.mime}@}
Reads in the body of mime message, decoding transfer encoding,
and returns it as a string or writes it to a file, respectively.
@end defun

The simplest form of MIME message parser would be like this:

@example
(let ((headers (rfc822-read-headers port)))
  (mime-parse-message port headers
                      (cut mime-body->string <> <>)))
@end example

This reads all the message on memory (i.e. the "leaf" @code{<mime-part>}
objects' @code{content} field would hold the part's body as a string),
and returns the top @code{<mime-part>} object.  Content transfer encoding
is recognized and handled, but character set conversion isn't done.

You may want to feed the message body to a file directly,
or even want to skip some body according to mime media types and/or
other header information.  Then you can put the logic in the handler
closure.  That's the reason that this module provides building
blocks, instead of all-in-one procedure.

@subheading Message composer

@defun mime-compose-message parts :optional port :key boundary
@defunx mime-compose-message-string parts :key boundary
@{@t{rfc.mime}@}
Composes a MIME multipart message.  @code{Mime-compose-message}
emits the result to an output port @var{port}, whose default
is the current output port.  @code{Mime-compose-message-string}
makes the result into a string.   You can give a boundary string
via @var{boundary} argument; when omitted, a fresh boundary string
is automatically generated by @code{mime-make-boundary} below.

@code{Mime-compose-message} returns the boundary string.
@code{Mime-compose-message-string} returns two values, the result
string and the boundary string.

The content of the message is provided by the @var{parts} argument,
which can be a list of instances of @code{<mime-part>} (see above)
or lists that describe parts.  The list form is supported for
the caller's convenience, and internally it is converted to
a list of @code{<mime-part>}s.

The syntax of each part element in @var{parts} are defined as follow.

@example
<part>           : <mime-part> | <mime-part-desc>

<mime-part>      : @r{an instance of the class} <mime-part>

<mime-part-desc> : (<content-type> (<header> ...) <body>)
<content-type>   : (<type> <subtype> <header-param> ...)
<header-param>   : (<key> . <value>) ...
<header>         : (<header-name> <encoded-header-value>)
                 | (<header-name> (<header-value> <header-param> ...))
<body>           : @r{a string}
                 | (file <filename>)
                 | (subparts <part> ...)
@end example

Note: In the first form of @code{<header>},
@code{<encoded-header-value>} must already be encoded using RFC2047
or RFC2231 if the original value contains non-ascii characters.
In the second form, we plan to do RFC2231 encoding on behalf of
the caller; but the current version does not implement it.  The
caller should not pass encoded words in this form, since it may
result double-encoding when we implement the auto encoding feature;
for the time being, the second form restricts ASCII-only values.

If @code{<body>} is a string, it is used as the part's content.
If @code{<body>} is @code{(file @var{filename})}, the content is
read from the named file.   If @code{<body>} is
@code{(subparts @var{part} @dots{})}, the part becomes nested
MIME part.

It is the caller's responsibility to give the proper content.
For example, if @code{<body>} is in the third form, the
part must have @code{multipart} content type.

The caller needs to provide proper @code{content-transfer-encoding}
header, depending on the application.  If none is given, the content
is inserted into the message as is, which may be appropriate for
some applications, but if you want to use the result in email
message you certainly want to encode binary part with base64,
for example.
@end defun

@defun mime-make-boundary
@{@t{rfc.mime}@}
Returns a unique string that can be used as a boundary of a MIME multipart
message.
@end defun


@c ----------------------------------------------------------------------
@node Quoted-printable encoding/decoding, SHA message digest, MIME message handling, Library modules - Utilities
@section @code{rfc.quoted-printable} - Quoted-printable encoding/decoding
@c NODE Quoted-printableエンコーディング, @code{rfc.quoted-printable} - Quoted-printableエンコーディング

@deftp {Module} rfc.quoted-printable
@mdindex rfc.quoted-printable
This module defines a few functions to encode/decode Quoted-printable format,
defined in RFC 2045 (@uref{https://www.ietf.org/rfc/rfc2045.txt}), section 6.7.
@end deftp

@defun quoted-printable-encode :key line-width binary
@{@t{rfc.quoted-printable}@}
Reads byte stream from the current input port, encodes it in Quoted-printable
format and writes the result character stream to the current output port.
The conversion ends when it reads EOF from the current input port.
The keyword argument @var{line-width} specifies the maximum
line width of the generated output in characters.  If the encoded
output creates a long line, the procedure inserts a ``soft line break''
so that the each line is equal to or shorter than this number.
Soft line breaks are removed when quoted-printable text is
decoded.
The default line width is 76.  (The minimum meaningful number of
line-width is 4).  You can suppress soft line breaks by
giving @code{#f} or @code{0} to @var{line-width}.
By default, @code{quoted-printable-encode} generates @code{CR-LF} sequence
for each line break in the input (``hard line break'').
When a true value is given to the keyword argument @var{binary},
however, octets @code{#x0a} and @code{#x0d} in the input are encoded
as @code{=0A} and @code{=0D}, respectively.  See RFC2045 section 6.7
for the details.
@end defun

@defun quoted-printable-encode-string string :key line-width binary
@{@t{rfc.quoted-printable}@}
Converts contents of @var{string} to Quoted-printable encoded format.
Input string can be either complete or incomplete string;
it is always interpreted as a byte sequence.

The keyword arguments are the same as @code{quoted-printable-encode}.
@end defun

@defun quoted-printable-decode
@{@t{rfc.quoted-printable}@}
Reads character stream from the current input port,
decodes it from Quoted-printable
format and writes the result byte stream to the current output port.
The conversion ends when it reads EOF.
If it encounters illegal character sequence (such as '=' followed
by non-hexadecimal characters), it copies them literally to the output.
@end defun

@defun quoted-printable-decode-string string
@{@t{rfc.quoted-printable}@}
Decodes a Quoted-printable encoded string @var{string} and returns
the result as a string.
@end defun

@c ----------------------------------------------------------------------
@node SHA message digest, Transport layer security, Quoted-printable encoding/decoding, Library modules - Utilities
@section @code{rfc.sha} - SHA message digest
@c NODE SHAメッセージダイジェスト, @code{rfc.sha} - SHAメッセージダイジェスト

@deftp {Module} rfc.sha
@mdindex rfc.sha
This module implements US Secure Hash Algorithm
defined in RFC 4634.  It provides SHA-1, SHA-224, SHA-256,
SHA-384 and SHA-512 (the latter four are sometimes referred
as SHA-2 collectively).

The module extends util.digest
(@pxref{Message digester framework}).
@end deftp

@deftp {Module} rfc.sha1
@mdindex rfc.sha1
This is the old module that provided only SHA-1.  It is kept as
an alias of @code{rfc.sha} for the backward compatibility.  New code
should use @code{rfc.sha}.
@end deftp


@deftp {Class} <sha1>
@deftpx {Class} <sha224>
@deftpx {Class} <sha256>
@deftpx {Class} <sha384>
@deftpx {Class} <sha512>
@clindex sha1
@clindex sha224
@clindex sha256
@clindex sha384
@clindex sha512
@{@t{rfc.sha}@}
An instance of these class keeps internal state of SHA digest algorithm.

This class implements @code{util.digest} framework interface,
@code{digest-update!}, @code{digest-final!},
@code{digest}, and @code{digest-string}.
@xref{Message digester framework}, for detailed explanation
of these methods.
@end deftp

Besides the digester framework, this module provides to
short-cut procedures.

@defun sha1-digest
@defunx sha224-digest
@defunx sha256-digest
@defunx sha384-digest
@defunx sha512-digest
@{@t{rfc.sha}@}
Reads data from the current input port until EOF, and returns
its digest in an incomplete string.
@end defun

@defun sha1-digest-string string
@defunx sha224-digest-string string
@defunx sha256-digest-string string
@defunx sha384-digest-string string
@defunx sha512-digest-string string
@{@t{rfc.sha}@}
Digest the data in @var{string}, and returns the result
in an incomplete string.
@end defun

@c ----------------------------------------------------------------------
@node Transport layer security, URI parsing and construction, SHA message digest, Library modules - Utilities
@section @code{rfc.tls} - Transport layer security
@c NODE トランスポート・レイヤ・セキュリティ, @code{rfc.tls} - トランスポート・レイヤ・セキュリティ

@deftp {Module} rfc.tls
@mdindex rfc.tls
This module handles secure connection over TCP socket.
This module is used by @code{rfc.http} to realize https connection
(@pxref{HTTP}).
@end deftp

@subheading CA certificates

You need CA certificates to verify server certificates properly.
Gauche doesn't have its own CA certificates, and relies on the
system's certificate store by default.  On Unix-based systems,
we search several known locations: On popular Linux distributions
we recommend you to install @code{ca-certificates} package (or similar one).
On OSX, we recommend to install openssl via Homebrew.  On Windows,
we use system's certificate store via Wincrypt API.

With the default configuration, Gauche checks the availability of the system's
certificate store at initilization and use one if available.  You can explicitly
give the path of CA certificate bundle, or disable it and provide
individual certificate per connection.

If, for some reasons, you cannot install system-wide CA certificate bundle,
you can also download Curl's CA certificate bundle 
@url{https://curl.haxx.se/ca/cacert.pem}, and install it in
Gauche installation directory.  We have a convenience script.
After installing Gauche, run the following command:

@example
gosh rfc/tls/get-cacert.scm
@end example

You need curl installed on your system.  If you've installed
Gauche with root priviledge, you'll be asked sudo password to install
the CA bundle file.

If you decided to do this, make sure you run the above command occasionally
to get updated CA certificate bundles, for certificates may expire or
be revoked.

@deffn {Parameter} tls-ca-bundle-path :optional path
@{@t{rfc.tls}@}
Holds CA certificate bundle to be used.  The value
can be either a string path to a CA bundle file, a symbol @code{system},
or @code{#f}.

If it is @code{system}, Gauche uses system's default bundle.  
An error is signaled on connection
if Gauche can't find one.

If it is @code{#f}, CA certificate won't be loaded automatically,
and you have to manually load one using @code{tls-load-object}.
(Note: This option is only valid with @code{<ax-tls>}.  If you're using
@code{<mbed-tls>}, you need valid CA certificate bundle.)

With the default configuration, Gauche scans the system CA bundle
when @code{rfc.tls} module is initialized, and if it finds one,
@code{tls-ca-bundle-path} is set to @code{system}; otherwise,
@code{tls-ca-bundle-path} is set to @code{#f}.  So if you're using
with default configuration and you see its value is @code{system},
you can count on the system CA certificate bundle.

This default behavior may be altered if Gauche is configured
with @code{--with-ca-bundle} option.  You can execute
@code{gauche-config --reconfigure} command to see if
special @code{--with-ca-bundle} option is given.
@end deffn


@subheading Supported TLS subsystems

Gauche supports two TLS subsystems - one based on AxTLS
(@url{http://axtls.sourceforge.net/}), and the other based on
MbedTLS (@url{https://tls.mbed.org/}).  Whether they're included
depends on the configuration options.  By default, AxTLS support
is compiled in, and MbedTLS support is included if the build
platform has MbedTLS library installed. 

AxTLS library has advanage of being included in Gauche, so that
it won't depend on external library, however, its supported ciphers
are limited, and it can't connect to some https sites.  MbedTLS has
wider cipher support, but it requires MbedTLS dynamic libraries
(e.g. @file{libmbedtls.so}) at runtime.

Gauche chooses available TLS subsystem at runtime, so the user usually
does not need to worry about the difference.  If you're building Gauche
by yourself, we recommend to use the default configuration, on a system
that has MbedTLS installed.   That will give you the most flexible choice.

Whether the running Gauche has any of TLS support can be checked with
a feature identifier @code{gauche.net.tls}.  Availability of each
individual subsystems can be checked with feature identifiers
@code{gauche.net.tls.axtls} and @code{gauche.net.tls.mbedtls}, respectively.
@xref{Feature conditional}, for more about feature identifiers.

@deftp {Class} <tls>
@clindex tls
@{@t{rfc.tls}@}
An abstract base class of TLS implementations.
@end deftp

@deftp {Class} <ax-tls>
@clindex ax-tls
@{@t{rfc.tls}@}
A class that implements axTLS subsystem interface.
@end deftp

@deftp {Class} <mbed-tls>
@clindex mbed-tls
@{@t{rfc.tls}@}
A class that implements mbedTLS subsystem interface.
@end deftp

@deffn {Parameter} default-tls-class :optional class
@{@t{rfc.tls}@}
Set/get the default TLS subsystem to be used.  Without arguments, it
return a class (either @code{<ax-tls>} or @code{<mbed-tls>} to be used.
With one argument, which must be either @code{<ax-tls>} or @code{<mbed-tls>},
changes the default and returns the previous value.
@end deffn

@subheading TLS interface

@defun make-tls initargs @dots{}
@{@t{rfc.tls}@}
Creates and returns a new TLS instance of the class @code{default-tls-class}.
The returned TLS instance can be used for the tls procedures below.

The arguments must be a keyword-value list, and passed to the constructor
of the TLS class.

@table @code
@item :server-name
Server name to be used for TLS Server Name Indication extension.
@item :num-sessions
[AxTLS only]
The number of sessions ot be used for session caching.
0 indicates no sessino caching. 
@item :options
[AxTLS only]
Bitflags of options.  Logical OR of the following numeric constants.
@end table

@table @code
@item SSL_SERVER_VERIFY_LATER
(client only) Let handshake success even the server authentication fails.
@item SSL_CLIENT_AUTHENTICATION
(server only) Request client sertificate to be authenticated.
@end table
@end defun

@defun tls-connect tls socket
@{@t{rfc.tls}@}
Establishes TLS connection as a client.  The @var{tls} argument must
be an unconnected TLS object, and the @var{socket} argument must
be a @emph{connected} socket.  On success, it returns @var{tls},
which is in connected state.  It can be used to read/write data
from/to the connected peer.

The @var{socket} is owned by @var{tls} object and should not be directly
accessed after calling this procedure.
@end defun

@defun tls-accept tls socket
@{@t{rfc.tls}@}
Establishes TLS connection as a server.  The @var{tls} argument must
be an unconnected TLS object, and the @var{socket} argument must
be a @emph{listening} socket.  On success, it returns @var{tls},
which is in connected state.  It can be used to read/write data
from/to the connected peer.
@end defun

@defun tls-close tls
@{@t{rfc.tls}@}
Shuts down the underling connection.  The peer will notified
the connection is closed.
Once @var{tls} is closed, it can no longer be used, but the reosurces
won't be collected until @var{tls} is GC-ed or @code{tls-destroy} is
called.  We recommend the user call @code{tls-destroy} explicitly.
@end defun

@defun tls-destroy tls
@{@t{rfc.tls}@}
Releases resources associated to @var{tls}.
@end defun

@defun tls-input-port tls
@defunx tls-output-port tls
@{@t{rfc.tls}@}
If @var{tls} is connected, it returns input and output port to communicate
with the peer, respectively.

If @var{tls} is not connected, @code{#f} is returned.
@end defun

@defun tls-load-object tls type filename :optional password
@{@t{rfc.tls}@}
This procedure is only meaningful for @code{<axl-tls>}.  For @code{<mbed-tls>},
this procedure does nothing.

Load private keys or certificates stored in a file specified by
@var{filenames}.  The type of object is specified by @var{type}
argument with one of the following numberic constants.  If the file
requires a password, it should be given to @var{password}.

@table @code
@item SSL_OBJ_X509_CERT
@item SSL_OBJ_X509_CACERT
@item SSL_OBJ_RSA_KEY
@item SSL_OBJ_PKCS8
@item SSL_OBJ_PKC12
@end table
@end defun

@defvr {Constant} SSL_OBJ_X509_CERT
@defvrx {Constant} SSL_OBJ_X509_CACERT
@defvrx {Constant} SSL_OBJ_RSA_KEY
@defvrx {Constant} SSL_OBJ_PKCS8
@defvrx {Constant} SSL_OBJ_PKCS12
@{@t{rfc.tls}@}
@end defvr

@c ----------------------------------------------------------------------
@node URI parsing and construction, UUID, Transport layer security, Library modules - Utilities
@section @code{rfc.uri} - URI parsing and construction
@c NODE URIの解析と作成, @code{rfc.uri} - URIの解析と作成

@deftp {Module} rfc.uri
@mdindex rfc.uri
Provides a set of procedures to parse and construct Uniform Resource Identifiers
defined in RFC 2396 (@uref{https://www.ietf.org/rfc/rfc2396.txt}),
as well as Data URI scheme defined in RFC2397.
@end deftp

First, lets review the structure of URI briefly.
The following graph shows how the URI is constructed:

@example
URI-+-scheme
    |
    +-specific--+--authority-+--userinfo
                |            +--host
                |            +--port
                +--path
                +--query
                +--fragment
@end example

Not all URIs have this full hierarchy.  For example,
@code{mailto:admin@@example.com} has only @emph{scheme} (@code{mailto})
and @emph{specific} (@code{admin@@example.com}) parts.

Most popular URI schemes, however, organize resources
in a tree, so they adopt @emph{authority} (which usually identifies
the server) and the hierarchical @emph{path}.  In the URI
@code{http://example.com:8080/search?q=key#results}, the authority
part is @code{example.com:8080}, the path is @code{/search},
the query is @code{key} and the fragment is @code{results}.
The userinfo can be provided before hostname, such as @code{anonymous}
in @code{ftp://anonymous@@example.com/pub/}.

We have procedures that decompose a URI into those parts,
and that compose a URI from those parts.

@subheading Parsing URI

@defun uri-ref uri parts
@{@t{rfc.uri}@}
Extract specific part(s) from the given URI.  You can fully
decompose URI by the procedures described below, but in actual
applications, you often need only some of the parts.  This procedure
comes handy for it.

The @var{parts} argument may be a symbol, or a list of symbols,
to name the desired parts.  The recognized symbos are as follows.

@table @code
@item scheme
The scheme part, as string.
@item authority
The authority part, as string.
If URI doesn't have the part, @code{#f}.
@item userinfo
The userinfo part, as string.  If URI doesn't have the part, @code{#f}.
@item host
The host part, as string.  If URI doesn't have the part, @code{#f}.
@item port
The port part, as integer.  If URI doesn't have the part, @code{#f}.
@item path
The path part, as string.  If URI isn't hierarchical, this returns
the specific part.
@item query
The query part, as string. If URI doesn't have the part, @code{#f}.
@item fragment
The fragment part, as string.  If URI doesn't have the part, @code{#f}.
@item scheme+authority
The scheme and authority part.
@item host+port
The host and port part.
@item userinfo+host+port
The userinfo, host and port part.
@item path+query
The path and query part.
@item path+query+fragment
The path, query and fragment part.
@end table

@example
(define uri "http://foo:bar@@example.com:8080/search?q=word#results")

(uri-ref uri 'scheme)             @result{} "http"
(uri-ref uri 'authority)          @result{} "//foo:bar@@example.com:8080/"
(uri-ref uri 'userinfo)           @result{} "foo:bar"
(uri-ref uri 'host)               @result{} "example.com"
(uri-ref uri 'port)               @result{} 8080
(uri-ref uri 'path)               @result{} "/search"
(uri-ref uri 'query)              @result{} "q=word"
(uri-ref uri 'fragment)           @result{} "results"
(uri-ref uri 'scheme+authority)   @result{} "http://foo:bar@@example.com:8080/"
(uri-ref uri 'host+port)          @result{} "example.com:8080"
(uri-ref uri 'userinfo+host+port) @result{} "foo:bar@@example.com:8080"
(uri-ref uri 'path+query)         @result{} "/search?q=word"
(uri-ref uri 'path+query+fragment)@result{} "/search?q=word#results"
@end example

You can extract multiple parts at once by specifying a list of parts.
A list of parts is returned.

@example
(uri-ref uri '(host+port path+query))
  @result{} ("example.com:8080" "/search?q=word")
@end example
@end defun


@defun uri-parse uri
@defunx uri-scheme&specific uri
@defunx uri-decompose-hierarchical specific
@defunx uri-decompose-authority authority
@{@t{rfc.uri}@}
General parser of URI.  These functions does not decode
URI encoding, since the parts to be decoded differ among
the uri schemes.   After parsing uri, use @code{uri-decode} below
to decode them.

@code{uri-parse} is the most handy procedure.  It breaks the uri
into the following parts and returns them as multiple values.
If the uri doesn't have the corresponding
parts, @code{#f} are returned for the parts.

@itemize @bullet
@item
URI scheme as a string
(e.g. @code{"mailto"} in @code{"mailto:foo@@example.com"}).
@item
User-info in the authority part (e.g. @code{"anonymous"}
in @code{ftp://anonymous@@ftp.example.com/pub/foo}).
@item
Hostname in the authority part (e.g. @code{"ftp.example.com"}
in @code{ftp://anonymous@@ftp.example.com/pub/foo}).
@item
Port number in the authority part, as an integer (e.g. @code{8080}
in @code{http://www.example.com:8080/}).
@item
Path part (e.g. @code{"/index.html"} in
@code{http://www.example.com/index.html}).
@item
Query part (e.g. @code{"key=xyz&lang=en"} in
@code{http://www.example.com/search?key=xyz&lang=en}).
@item
Fragment part (e.g. @code{"section4"} in
@code{http://www.example.com/document.html#section4}).
@end itemize

The following procedures are finer grained and break up
uris with different stages.

@code{uri-scheme&specific} takes a URI @var{uri}, and
returns two values, its scheme part and its scheme-specific part.
If @var{uri} doesn't have a scheme part, @code{#f} is returned for it.
@example
(uri-scheme&specific "mailto:sclaus@@north.pole")
  @result{} "mailto" @r{and} "sclaus@@north.pole"
(uri-scheme&specific "/icons/new.gif")
  @result{} #f @r{and} "/icons/new.gif"
@end example

If the URI scheme uses hierarchical notation, i.e.
``@code{//@var{authority}/@var{path}?@var{query}#@var{fragment}}'',
you can pass
the scheme-specific part to @code{uri-decompose-hierarchical}
and it returns four values, @var{authority}, @var{path}, @var{query}
and @var{fragment}.
@example
(uri-decompose-hierarchical "//www.foo.com/about/company.html")
  @result{} "www.foo.com"@r{,} "/about/company.html"@r{,} #f @r{and} #f
(uri-decompose-hierarchical "//zzz.org/search?key=%3fhelp")
  @result{} "zzz.org"@r{,} "/search"@r{,} "key=%3fhelp" @r{and} #f
(uri-decompose-hierarchical "//jjj.jp/index.html#whatsnew")
  @result{} "jjj.jp"@r{,} "/index.html"@r{,} #f @r{and} "whatsnew"
(uri-decompose-hierarchical "my@@address")
  @result{} #f@r{,} #f@r{,} #f @r{and} #f
@end example

Furthermore, you can parse @var{authority} part of the
hierarchical URI by @code{uri-decompose-authority}.
It returns @var{userinfo}, @var{host} and @var{port}.
@example
(uri-decompose-authority "yyy.jp:8080")
  @result{} #f@r{,} "yyy.jp" @r{and} "8080"
(uri-decompose-authority "[::1]:8080")  ;@r{(IPv6 host address)}
  @result{} #f@r{,} "::1" @r{and} "8080"
(uri-decompose-authority "mylogin@@yyy.jp")
  @result{} "mylogin"@r{,} "yyy.jp" @r{and} #f
@end example
@end defun


@defun uri-decompose-data uri
@{@t{rfc.uri}@}
Parse a Data URI string @var{uri}.  You can either pass the entire
uri including @code{data:} scheme part, or just the specific part.
If the passed uri is invalid as a data uri, an error is signalled.

Returns two values: parsed content type and the decoded data.
The data is a string if the content type is @code{text/*}, and
a u8vector otherwise.

The content-type is parsed by @code{mime-parse-content-type}
(@pxref{MIME message handling}).  The result format is a list as follows:

@example
@code{(@i{type} @i{subtype} (@i{attribute} . @i{value}) @dots{})}.
@end example

Here are a couple of examples:

@example
(uri-decompose-data
 "data:text/plain;charset=utf-8;base64,KGhlbGxvIHdvcmxkKQ==")
  @result{} ("text" "plain" ("charset" . "utf-8")) @r{and} "(hello world)"

(uri-decompose-data
 "data:application/octet-stream;base64,AAECAw==")
  @result{} ("application" "octet-stream") @r{and} #u8(0 1 2 3)
@end example

@end defun


@subheading Constructing URI

@defun uri-compose :key scheme userinfo host port authority path path* query fragment specific
@{@t{rfc.uri}@}
Compose a URI from given components.
There can be various combinations of components to create a valid
URI---the following diagram shows the possible 'paths' of
combinations:

@example
        /-----------------specific-------------------\
        |                                            |
 scheme-+------authority-----+-+-------path*---------+-
        |                    | |                     |
        \-userinfo-host-port-/ \-path-query-fragment-/
@end example

If @code{#f} is given to a keyword argument, it is
equivalent to the absence of that keyword argument.
It is particularly useful to pass the results of
parsed uri.

If a component contains a character that is not appropriate
for that component, it must be properly escaped before
being passed to @code{url-compose}.

Some examples:
@example
(uri-compose :scheme "http" :host "foo.com" :port 80
             :path "/index.html" :fragment "top")
  @result{} "http://foo.com:80/index.html#top"

(uri-compose :scheme "http" :host "foo.net"
             :path* "/cgi-bin/query.cgi?keyword=foo")
  @result{} "http://foo.net/cgi-bin/query.cgi?keyword=foo"

(uri-compose :scheme "mailto" :specific "a@@foo.org")
  @result{} "mailto:a@@foo.org"

(receive (authority path query fragment)
   (uri-decompose-hierarchical "//foo.jp/index.html#whatsnew")
 (uri-compose :authority authority :path path
              :query query :fragment fragment))
  @result{} "//foo.jp/index.html#whatsnew"
@end example
@end defun


@defun uri-merge base-uri relative-uri relative-uri2 @dots{}
@{@t{rfc.uri}@}
Arguments are strings representing
full or part of URIs.  This procedure resolves @var{relative-uri}
in relative to @var{base-uri}, as defined in RFC3986 Section 5.2.
``Relative Resolution''.

If more @var{relative-uri2}s are given, first @var{relative-uri}
is merged to @var{base-uri}, then the next argument is merged
to the resulting uri, and so on.

@example
(uri-merge "http://example.com/foo/index.html" "a/b/c")
 @result{} "http://example.com/foo/a/b/c"

(uri-merge "http://example.com/foo/search?q=abc" "../about#me")
 @result{} "http://example.com/about#me"

(uri-merge "http://example.com/foo" "http://example.net/bar")
 @result{} "http://example.net/bar"

(uri-merge "http://example.com/foo/" "q" "?xyz")
 @result{} "http://example.com/foo/q?xyz"
@end example
@end defun

@defun uri-compose-data data :key content-type encoding
@{@t{rfc.uri}@}
Creates a Data URI of the given @var{data}, with specified content-type
and transfer encoding.  Returns a string.

The @var{data} argument must be a string or a u8vector.

The @var{content-type} argument can be @code{#f} (default),
a string that represents a content type (e.g. @code{"text/plain;charset=utf-8"}),
or a list form of parsed content type
(e.g. @code{("application" "octet-stream")}.  If it is @code{#f},
@code{text/plain} with the gauche's native character encoding is
used when @var{data} is a complete string, and @code{application/octet-stream}
is used otherwise.

The @var{encoding} argument can be either @code{#f} (default),
or a symbol @code{uri} or @code{base64}.  This is for transfer encoding,
not character encoding.  If it is @code{#f}, URI encoding is used
for text data and base64 encoding is used for binary data.

@example
(uri-compose-data "(hello world)")
 @result{} "data:text/plain;charset=utf-8,%28hello%20world%29"

(uri-compose-data "(hello world)" :encoding 'base64)
 @result{} "data:text/plain;charset=utf-8;base64,KGhlbGxvIHdvcmxkKQ=="

(uri-compose-data '#u8(0 1 2 3))
 @result{} "data:application/octet-stream;base64,AAECAw=="
@end example
@end defun


@subheading URI Encoding and decoding

@defun uri-decode :key :cgi-decode
@defunx uri-decode-string string :key :cgi-decode :encoding
@{@t{rfc.uri}@}
Decodes ``URI encoding'', i.e. @code{%}-escapes.
@code{uri-decode} takes input from the current input port,
and writes decoded result to the current output port.
@code{uri-decode-string} takes input from @var{string} and
returns decoded string.

If @var{cgi-decode} is true, also replaces @code{+} to a space character.

To @code{uri-decode-string} you can provide the external character
encoding by the @var{encoding} keyword argument.  When it is given,
the decoded octet sequence is assumed to be in the specified encoding
and converted to the Gauche's internal character encoding.
@end defun

@defun uri-encode :key :noescape
@defunx uri-encode-string string :key :noescape :encoding
@{@t{rfc.uri}@}
Encodes unsafe characters by @code{%}-escape.  @code{uri-encode}
takes input from the current input port and writes the result to
the current output port.  @code{uri-encode-string} takes input
from @var{string} and returns the encoded string.

By default, characters that are not specified ``unreserved'' in
RFC3986 are escaped.  You can pass different character
set to @var{noescape} argument to keep from being encoded.
For example, the older RFC2396 has several more ``unreserved''
characters, and passing @code{*rfc2396-unreserved-char-set*} (see below)
prevents those characters from being escaped.

The multibyte characters are encoded as the octet stream of Gauche's
native multibyte representation by default.  However, you can pass
the @code{encoding} keyword argument to @code{uri-encode-string},
to convert @var{string} to the specified character encoding.
@end defun

@defvr {Constant} *rfc2396-unreserved-char-set*
@defvrx {Constant} *rfc3986-unreserved-char-set*
@{@t{rfc.uri}@}
These constants are bound to character sets that represents
``unreserved'' characters defined in RFC2396 and RFC3986, respectively.
(See @ref{Character sets}, and @ref{R7RS character sets}, for
operations on character sets).
@end defvr

@c ----------------------------------------------------------------------
@node UUID, Zlib compression library, URI parsing and construction, Library modules - Utilities
@section @code{rfc.uuid} - UUID
@c NODE UUID, @code{rfc.uuid} - UUID

@deftp {Module} rfc.uuid
@mdindex rfc.uuid
This module implements UUID defined in RFC4122.

It provides generators of UUID version 1 and 4, and writer/parser
of the string represenation of UUIDs.
@end deftp

@deftp {Class} <uuid>
@{@t{rfc.uuid}@}
Class of UUID instances.
@end deftp

@defun uuid-value uuid
@{@t{rfc.uuid}@}
Returns the raw value of @var{uuid} as 16-element @code{u8vector}.
You shouldn't mutate the returned u8vector.
@end defun

@defun uuid-version uuid
@{@t{rfc.uuid}@}
Returns the version number of @var{uuid}.
@end defun

@defvar uuid-comparator
@{@t{rfc.uuid}@}
A comparator to compare and hash uuids.  @xref{Basic comparators}.
@end defvar

@defun uuid-random-source-set! random-source
@{@t{rfc.uuid}@}
We use PRNG to generate UUIDs.  By default, we internally creates
a random source and randomize it.  You can pass in your own
random source instead (@pxref{Sources of random bits}, for the details).
@end defun

@defun uuid1 :optional node-id
@{@t{rfc.uuid}@}
Generates a uuid with version 1 algorithm (timestamp and node id based).
The optional @var{node-id} argument must be 48bit exact integer
specifing the node ID (IEEE802 MAC address of the machine).
If it is omitted, we generate a process-global
random node ID (with the multicast bit set to 1, so that it won't
conflict with existing MAC address).
@end defun

@defun uuid4
@{@t{rfc.uuid}@}
Generates a uuid with version 4 algorithm (random numbers).
@end defun

@defun nil-uuid
@{@t{rfc.uuid}@}
Returns a nil-UUID (all bits zero).
@end defun

@defun parse-uuid string
@{@t{rfc.uuid}@}
Takes a string representation of UUID, parses it and returns
an uuid instance.  If the string isn't a valid UUID representation,
an error is thrown.

Other than @code{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX} format,
it recognizes the one with @code{urn:uuid:} prefix,
the one enclosed by curly braces, and the one without hyphens.
@end defun

@defun write-uuid uuid :optional port
@{@t{rfc.uuid}@}
Writes out a string representation of @var{uuid},
in @code{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX} format, to the given
port.  If the port is omitted, current output port is used.
@end defun

@defun uuid->string uuid
@{@t{rfc.uuid}@}
Returns a string representation of @var{uuid},
in @code{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX} format.
@end defun

@c ----------------------------------------------------------------------
@node Zlib compression library, SLIB, UUID, Library modules - Utilities
@section @code{rfc.zlib} - zlib compression library
@c NODE zlib圧縮ライブラリ, @code{rfc.zlib} - zlib圧縮ライブラリ

@deftp {Module} rfc.zlib
@mdindex rfc.zlib
This module provides bindings to zlib compression library.
Most features of zlib can be used through this module.

Zlib supports reading and writing of
Zlib compressed data format (RFC1950),
DEFLATE compressed data format (RFC1951),
and GZIP file format (RFC1052).  It also provides
procedures to calculate CRC32 and Adler32 checksums.

Compression and decompression are done through specialized ports.
There are number of parameters to fine-tune compression; refer
to zlib documentation for the details.
@end deftp

@subheading Condition types

The following condition types are defined to represent errors
during processing by zlib.

@deftp {Condition Type} <zlib-error>
@{@t{rfc.zlib}@}
Subclass of @code{<error>} and superclass of the following
condition types.  This class is an abstract class to catch any of the
zlib-specific errors.  Zlib-specific errors raised by
procedures in @code{rfc.zlib} are always an instance (or a compound
condition including) one of the following specific classes.
@end deftp

@deftp {Condition Type} <zlib-need-dict-error>
@deftpx {Condition Type} <zlib-stream-error>
@deftpx {Condition Type} <zlib-data-error>
@deftpx {Condition Type} <zlib-memory-error>
@deftpx {Condition Type} <zlib-version-error>
@{@t{rfc.zlib}@}
Subclasses of @code{<zlib-error>}.  Those condition type correspond
to zlib's
@code{Z_NEED_DICT_ERROR},
@code{Z_STREAM_ERROR},
@code{Z_DATA_ERROR},
@code{Z_MEMORY_ERROR}, and
@code{Z_VERSION_ERROR} errors.

When an error occurs during reading data, a compound
condition of a subclass of @code{<zlib-error>} and
@code{<io-read-error>} is raised.
When an error occurs without I/O, a simple condition
of a subclass of @code{<zlib-error>} is raised.
Errors unrelated to zlib, such as invalid argument error,
would be a simple @code{<error>} condition.
@end deftp

@subheading Compression/decompression ports

@deftp {Class} <deflating-port>
@deftpx {Class} <inflating-port>
@clindex deflating-port
@clindex inflating-port
@{@t{rfc.zlib}@}
Compression and decompression functions are provided
via ports.  A @emph{deflating port} is an output port
that compresses the output data.  An @emph{inflating port}
is an input that reads compressed data and decompress it.

When an inflating port encounters a corrupted compressed
data, a compound condition of @code{<io-read-error>}
and @code{<zlib-data-error>} is raised during read operation.
@end deftp


@defun open-deflating-port drain :key compression-level buffer-size window-bits memory-level strategy dictionary owner?
@{@t{rfc.zlib}@}
Creates and returns an instance of @code{<deflating-port>},
an output port that compresses the output data and sends
the compressed data to another output port @var{drain}.
This combines the functionality of zlib's @code{deflateInit2()}
and @code{deflateSetDictionary()}.

You can specify an exact integer between 1 and 9 (inclusive) to
@var{compression-level}.  Larger integer means larger compression ratio.
When omitted, a default compression level is used, which is usually 6.

The following constants are defined to specify @var{compression-level}
conveniently:

@defvr {Constant} Z_NO_COMPRESSION
@defvrx {Constant} Z_BEST_SPEED
@defvrx {Constant} Z_BEST_COMPRESSION
@defvrx {Constant} Z_DEFAULT_COMPRESSION
@{@t{rfc.zlib}@}
@end defvr

The @var{buffer-size} argument specifies the buffer size of the port in bytes.
The default is 4096.

The @var{window-bits} argument specifies the size of the window in
exact integer.   Typically the value should be
between 8 and 15, inclusive, and it specifies the base two logarithm
of the window size used in compression.
Larger number yields better compression ratio, but more memory usage.
The default value is 15.

There are a couple of special modes specifiable by @var{window-bits}.
When an integer between -8 and -15 is given to
@var{window-bits}, the port produces a raw deflated data,
that lacks zlib header and trailer.  In this case, Adler32 checksum isn't
calculated.  The actual window size is determined by the absolute value of
@var{window-bits}.

When @var{window-bits} is between 24 and 31, the port uses GZIP encoding;
that is, instead of zlib wrapper,
the compressed data is enveloped by simple gzip header and trailer.
The gzip header added by this case doesn't have filenames, comments,
header CRC and other data, and have zero modified time, and 255 (unknown)
in the OS field.  The @code{zstream-adler32} procedure will return
CRC32 checksum instead of Adler32.
The actual window size is determined by @var{window-bits}-16.

The @var{memory-level} argument specifies how much memory
should be allocated to keep the internal state during compression.
1 means smallest memory, which causes slow and less compression.
9 means fastest and best compression with largest amount of memory.
The default value is 8.

To fine tune compression algorithm, you can use the @var{strategy}
argument.  The following constants are defined as the valid
value as @var{strategy}:

@defvr {Constant} Z_DEFAULT_STRATEGY
@{@t{rfc.zlib}@}
The default strategy, suitable for most ordinary data.
@end defvr

@defvr {Constant} Z_FILTERED
@{@t{rfc.zlib}@}
Suitable for data generated by filters.
Filtered data consists mostly of small values with a
random distribution, and this makes the compression algorithm
to use more huffman encoding and less string match.
@end defvr

@defvr {Constant} Z_HUFFMAN_ONLY
@{@t{rfc.zlib}@}
Force huffman encoding only (no string match).
@end defvr

@defvr {Constant} Z_RLE
@{@t{rfc.zlib}@}
Limit match distance to 1 (that is, to force run-length encoding).
It is as fast as @code{Z_HUFFMAN_ONLY} and gives better compression
for png image data.
@end defvr

@defvr {Constant} Z_FIXED
@{@t{rfc.zlib}@}
Prohibits dynamic huffman encoding.  It allows a simple decoder
for special applications.
@end defvr

The choice of @var{strategy} only affects compression ratio and
speed.  Any choice produces correct and decompressable data.

You can give an initial dictionary to the @var{dictionary}
argument to be used in compression.
The compressor and decompressor must use exactly the same dictionary.
See the zlib documentation for the details.

By default, a deflating port leaves @var{drain} open
after all conversion is done, i.e. the deflating port itself is
closed.  If you don't want to bother closing @var{drain},
give a true value to the @var{owner?} argument; then @var{drain}
is closed after the deflating port is closed and all data
is written out.

Note: You @emph{must} close a deflating port explicitly,
or the compressed data can be chopped prematurely.
When you leave a deflating port open to be GCed, the
finalizer will close it; however, the order in which
finalizers are called is undeterministic, and it is
possible that the @var{drain} port is closed before
the deflating port is closed.  In such cases,
the deflating port's attempt to flush the buffered data
and trailer will fail.
@end defun

@defun open-inflating-port source :key buffer-size window-bits dictionary owner?
@{@t{rfc.zlib}@}
Takes an input port @var{source} from which a compressed data
can be read, and creates and returns a new instance of
@code{<inflating-port>}, that is, a port that allows
decompressed data from it.
This procedure covers zlib's functionality of
@code{inflateInit2()} and @code{inflateSetDictionary()}.

The meaning of @var{buffer-size} and @var{owner} are
the same as @code{open-deflating-port}.

The meaning of @var{window-bits} is almost the same,
except that if a value increased by 32 is given, the inflating port
automatically detects whether the source stream is
zlib or gzip by its header.

If the input data is compressed with specified dictionary,
the same dictionary must be given to the @var{dictionary} argument.
Otherwise, a compound condition of
@code{<io-read-error>} and @code{<zlib-need-dict-error>} will be raised.
@end defun

@subheading Operations on inflating/deflating ports

@defun zstream-total-in xflating-port
@defunx zstream-total-out xflating-port
@defunx zstream-adler32 xflating-port
@defunx zstream-data-type xflating-port
@{@t{rfc.zlib}@}
The @var{xflating-port} argument must be either
inflating and deflating port, or an error is raised.

Returns the value of @code{total_in}, @code{total_out},
@var{adler32}, and @code{data_type} fields of the @code{z_stream}
structure associated to the given inflating or deflating port,
respectively.

The value of @code{data_type} can be one of the following
constants:

@defvr {Constant} Z_BINARY
@defvrx {Constant} Z_TEXT
@defvrx {Constant} Z_ASCII
@defvrx {Constant} Z_UNKNOWN
@{@t{rfc.zlib}@}
@end defvr

@end defun

@defun zstream-params-set! deflating-port :key compression-level strategy
@{@t{rfc.zlib}@}
Changes compression level and/or strategy during compressing.
@end defun

@defun zstream-dictionary-adler32 deflating-port
@{@t{rfc.zlib}@}
When a dictionary is given to @code{open-deflating-port}, the
dictionary's adler32 checksum is calculated.  This
procedure returns the checksum.  If no dictionary has been given,
this procedure returns @code{#f}.
@end defun

@defun deflating-port-full-flush deflating-port
@{@t{rfc.zlib}@}
Flush the data buffered in the @var{deflating-port}, and
resets compression state.  The decompression routine can
skip the data to the full-flush point by @code{inflate-sync}.
@end defun

@defun inflate-sync inflating-port
@{@t{rfc.zlib}@}
Skip the (possibly corrupted) compressed data up to the
next full-flush point marked by @code{deflating-port-full-flush}.
You may want to use this procedure when you get
@code{<zlib-data-error>}.  Returns the number of bytes
skipped when the next full-flush point is found, or
@code{#f} when the input reaches EOF before finding the next point.
@end defun

@subheading Miscellaneous API

@defun zlib-version
@{@t{rfc.zlib}@}
Returns Zlib's version in string.
@end defun

@defun deflate-string string options @dots{}
@{@t{rfc.zlib}@}
Compresses the given string and returns zlib-compressed data
in a string.  All optional arguments are passed to
@code{open-deflating-port} as they are.
@end defun

@defun inflate-string string options @dots{}
@{@t{rfc.zlib}@}
Takes zlib-compressed data in string, and returns decompressed data
in a string.  All optional arguments are passed to
@code{open-inflating-port} as they are.
@end defun

@defun gzip-encode-string string options @dots{}
@defunx gzip-decode-string string options @dots{}
@{@t{rfc.zlib}@}
Like @code{deflate-string} and @code{inflate-string}, but
uses the gzip format instead.  It is same as giving
more than 15 to the @var{window-bits} argument of @code{deflate-string}
and @code{inflate-string}.
@end defun

@defun crc32 string :optional checksum
@{@t{rfc.zlib}@}
Returns CRC32 checksum of @var{string}.  If optional @var{checksum}
is given, the returned checksum is an update of @var{checksum} by
@var{string}.
@end defun

@defun adler32 string :optional checksum
@{@t{rfc.zlib}@}
Returns Adler32 checksum of @var{string}.  If optional @var{checksum}
is given, the returned checksum is an update of @var{checksum} by
@var{string}.

Calculating Adler32 is faster than CRC32, but it is known to produce
uneven distribution of hash values for small input.
See RFC3309 for the detailed description.  If it matters,
use CRC32 instead.
@end defun






@c ----------------------------------------------------------------------
@node SLIB, Functional XML parser, Zlib compression library, Library modules - Utilities
@section @code{slib} - SLIB interface
@c NODE SLIBインタフェース, @code{slib} - SLIBインタフェース

@deftp {Module} slib
@mdindex slib
This module is the interface to the Aubrey Jaffer's SLIB.
To use SLIB, say @code{(use slib)}.   SLIB itself is not included
in Gauche distribution.   If you don't have it on your system,
get it from @uref{http://www-swiss.ai.mit.edu/~jaffer/SLIB.html}.

By default, the SLIB installation is searched from the directory
specified at the Gauche configuration.  If SLIB isn't there, an error
is signaled.  In that case, you can set the environment
variable @code{SCHEME_LIBRARY_PATH} to point to the SLIB installation path.

This module redefines @code{require}, shadowing the Gauche's original
@code{require}.  If it gets a symbol as an argument, it works as
SLIB's @code{require}, while if it gets a string, it works as
Gauche's @code{require}.   The same applies to @code{provide} and
@code{provided?}.

All SLIB symbol bindings, loaded by @code{require}, stay in the
module @code{slib}.
@end deftp

@example
(use slib)         ; @r{load and set up slib}
(require 'getopt)  ; @r{load SLIB's getopt module}
(require "foo")    ; @r{load Gauche's foo module}
@end example

@c ----------------------------------------------------------------------
@node Functional XML parser, SXML query language, SLIB, Library modules - Utilities
@section @code{sxml.ssax} - Functional XML parser
@c NODE 関数的なXMLパーザ, @code{sxml.ssax} - 関数的なXMLパーザ

@deftp {Module} sxml.ssax
@mdindex sxml.ssax
@code{sxml.*} modules are the adaptation of
Oleg Kiselyov's SXML framework (@uref{http://okmij.org/ftp/Scheme/xml.html}),
which is based on S-expression representation of XML structure.

SSAX is a parser part of SXML framework.
This is a quote from SSAX webpage:

@quotation
A SSAX functional XML parsing framework consists of a DOM/SXML parser,
a SAX parser, and a supporting library of lexing and parsing procedures.
The procedures in the package can be used separately to tokenize or parse
various pieces of XML documents.
The framework supports XML Namespaces, character, internal
and external parsed entities, attribute value normalization,
processing instructions and CDATA sections. The package includes
a semi-validating SXML parser : a DOM-mode parser that is an
instantiation of a SAX parser (called SSAX).
@end quotation

The current version is based on the SSAX CVS version newer than
the last 'official' release of SXML toolset (4.9), and
SXML-gauche-0.9 package which was based on SXML-4.9.
There is an important change from that release.
Now the API uses lowercase letter suffix @code{ssax:}
instead of uppercase @code{SSAX:}---the difference matters since
Gauche is case sensitive by default.
Alias names are defined for backward compatibility,
but the use of uppercase suffixed names are deprecated.
@end deftp

I derived the content of this part of the manual from SSAX
source code, just by converting its comments into texinfo format.
The original text is by Oleg Kiselyov.  Shiro Kawai
should be responsible for any typographical error or formatting error
introduced by conversion.

The manual entries are ordered in "bottom-up" way, beginning from
the lower-level constructs towards the high-level utilities.
If you just want to parse XML document and obtain SXML,
check out @code{ssax:xml->sxml} in @ref{SSAX Highest-level parsers - XML to SXML}.

@c ----------------------------------------------------------------------
@menu
* SSAX data types::
* SSAX low-level parsing code::
* SSAX higher-level parsers and scanners::
* SSAX Highest-level parsers - XML to SXML::
@end menu

@node SSAX data types, SSAX low-level parsing code, Functional XML parser, Functional XML parser
@subsection SSAX data types
@c NODE SSAXデータタイプ

@table @emph
@item TAG-KIND
a symbol '@code{START}, '@code{END}, '@code{PI}, '@code{DECL}, '@code{COMMENT}, '@code{CDSECT}
or '@code{ENTITY-REF} that identifies a markup token.
@item UNRES-NAME
a name (called @code{GI} in the XML Recommendation) as given in an xml
document for a markup token: start-tag, @code{PI} target, attribute name.
If a @code{GI} is an @code{NCName}, @var{UNRES-NAME} is this @code{NCName} converted into
a Scheme symbol. If a @code{GI} is a @code{QName}, @var{UNRES-NAME} is a pair of
symbols: (@var{PREFIX} . @var{LOCALPART})
@item RES-NAME
An expanded name, a resolved version of an @var{UNRES-NAME}.
For an element or an attribute name with a non-empty namespace URI,
@var{RES-NAME} is a pair of symbols, (@var{URI-SYMB} . @var{LOCALPART}).
Otherwise, it's a single symbol.
@item ELEM-CONTENT-MODEL
A symbol:
@multitable @columnfractions .3 .7
@item @code{ANY}
@tab anything goes, expect an END tag.
@item @code{EMPTY-TAG}
@tab no content, and no END-tag is coming.
@item @code{EMPTY}
@tab no content, expect the END-tag as the next token.
@item @code{PCDATA}
@tab expect character data only, and no children elements.
@item @code{MIXED}
@tab
@item @code{ELEM-CONTENT}
@tab
@end multitable
@item URI-SYMB
A symbol representing a namespace URI -- or other symbol chosen
by the user to represent URI. In the former case,
@var{URI-SYMB} is created by @code{%}-quoting of bad URI characters and
converting the resulting string into a symbol.
@item NAMESPACES
A list representing namespaces in effect. An element of the list
has one of the following forms:

@table @code
@item (@var{prefix} @var{uri-symb} . @var{uri-symb})
or,
@item (@var{prefix} @var{user-prefix} . @var{uri-symb})
@var{user-prefix} is a symbol chosen by the user
to represent the URI.
@item (#f @var{user-prefix} . @var{uri-symb})
Specification of the user-chosen prefix and a @var{uri-symbol}.
@item (*DEFAULT* @var{user-prefix} . @var{uri-symb})
Declaration of the default namespace
@item (*DEFAULT* #f . #f)
Un-declaration of the default namespace. This notation
represents overriding of the previous declaration
@end table

A @var{NAMESPACES} list may contain several elements for the same @var{PREFIX}.
The one closest to the beginning of the list takes effect.

@item ATTLIST
An ordered collection of (@var{NAME} . @var{VALUE}) pairs, where @var{NAME} is
a @var{RES-NAME} or an @var{UNRES-NAME}. The collection is an ADT.
@item STR-HANDLER
A procedure of three arguments:
@code{(@var{string1} @var{string2} @var{seed})}
returning a new @var{seed}.
The procedure is supposed to handle a chunk of character data
@var{string1} followed by a chunk of character data @var{string2}.
@var{string2} is a short string, often "\n" and even ""
@item ENTITIES
An assoc list of pairs:
@example
  (@var{named-entity-name} . @var{named-entity-body})
@end example
where @var{named-entity-name} is a symbol under which the entity was
declared, @var{named-entity-body} is either a string, or
(for an external entity) a thunk that will return an
input port (from which the entity can be read).
@var{named-entity-body} may also be @code{#f}. This is an indication that a
@var{named-entity-name} is currently being expanded. A reference to
this @var{named-entity-name} will be an error: violation of the
WFC nonrecursion.
@item XML-TOKEN
A record with two slots, @var{kind} and @var{token}.
This record represents a markup, which is, according to the XML
Recommendation, "takes the form of start-tags, end-tags, empty-element tags,
entity references, character references, comments, CDATA section delimiters,
document type declarations, and processing instructions."
@table @var
@item kind
a @var{TAG-KIND}
@item head
an @var{UNRES-NAME}. For xml-tokens of kinds '@code{COMMENT} and
'@code{CDSECT}, the head is @code{#f}
@end table

For example,
@example
<P>  => kind='START, head='P
</P> => kind='END, head='P
<BR/> => kind='EMPTY-EL, head='BR
<!DOCTYPE OMF ...> => kind='DECL, head='DOCTYPE
<?xml version="1.0"?> => kind='PI, head='xml
&my-ent; => kind = 'ENTITY-REF, head='my-ent
@end example
Character references are not represented by xml-tokens as these references
are transparently resolved into the corresponding characters.
@item XML-DECL
A record with three slots, @var{elems}, @var{entities}, and @var{notations}.

The record represents a datatype of an XML document: the list of
declared elements and their attributes, declared notations, list of
replacement strings or loading procedures for parsed general
entities, etc. Normally an xml-decl record is created from a DTD or
an XML Schema, although it can be created and filled in in many other
ways (e.g., loaded from a file).

@var{elems}: an (assoc) list of decl-elem or @code{#f}. The latter instructs
the parser to do no validation of elements and attributes.

@var{decl-elem}: declaration of one element:
@code{(@var{elem-name} @var{elem-content} @var{decl-attrs})};
@var{elem-name} is an @var{UNRES-NAME} for the element.
@var{elem-content} is an @var{ELEM-CONTENT-MODEL}.
@var{decl-attrs} is an @var{ATTLIST},
of @code{(@var{attr-name} . @var{value})} associations.
This element can declare a user procedure to handle parsing of an
element (e.g., to do a custom validation, or to build a hash of
IDs as they're encountered).

@var{decl-attr}: an element of an @var{ATTLIST}, declaration of one attribute
@code{(@var{attr-name} @var{content-type} @var{use-type} @var{default-value})}:
@var{attr-name} is an @var{UNRES-NAME} for the declared attribute;
@var{content-type} is a symbol: @code{CDATA}, @var{NMTOKEN}, @var{NMTOKENS}, ...;
or a list of strings for the enumerated type.
@var{use-type} is a symbol: @code{REQUIRED}, @code{IMPLIED}, @code{FIXED}
default-value is a string for the default value, or @code{#f} if not given.
@end table

@defun make-empty-attlist
@defunx attlist-add attlist name-value
@defunx attlist-null?
@defunx attlist-remove-top attlist
@defunx attlist->alist attlist
@defunx attlist-fold
@{@t{sxml.ssax}@}
Utility procedures to deal with attribute list, which
keeps name-value association.
@end defun

@defun make-xml-token kind head
@defunx xml-token? token
@{@t{sxml.ssax}@}
A constructor and a predicate for a @var{XML-TOKEN} record.
@end defun

@defmac xml-token-kind token
@defmacx xml-token-head token
@{@t{sxml.ssax}@}
Accessor macros of a @var{XML-TOKEN} record.
@end defmac

@c ----------------------------------------------------------------------
@node SSAX low-level parsing code, SSAX higher-level parsers and scanners, SSAX data types, Functional XML parser
@subsection SSAX low-level parsing code
@c NODE SSAXの低レベルパージングコード

They deal with primitive lexical units (Names, whitespaces, tags)
and with pieces of more generic productions. Most of these parsers
must be called in appropriate context. For example, @code{ssax:complete-start-tag}
must be called only when the start-tag has been detected and its @code{GI}
has been read.

@defun ssax:skip-S port
@{@t{sxml.ssax}@}
Skip the S (whitespace) production as defined by
@example
 [3] S ::= (#x20 | #x9 | #xD | #xA)
@end example
The procedure returns the first not-whitespace character it
encounters while scanning the @var{port}. This character is left
on the input stream.
@end defun

@defun ssax:ncname-starting-char? a-char
@{@t{sxml.ssax}@}
Check to see if a-char may start a @code{NCName}.
@end defun

@defun ssax:read-NCName port
@{@t{sxml.ssax}@}
Read a @code{NCName} starting from the current position in the @var{port} and
return it as a symbol.
@end defun

@defun ssax:read-QName port
@{@t{sxml.ssax}@}
Read a (namespace-) Qualified Name, @code{QName}, from the current
position in the @var{port}.

From REC-xml-names:
@example
 [6] QName ::= (Prefix ':')? LocalPart
 [7] Prefix ::= NCName
 [8] LocalPart ::= NCName
@end example

Return: an @var{UNRES-NAME}.
@end defun

@defvar ssax:Prefix-XML
@{@t{sxml.ssax}@}
The prefix of the pre-defined XML namespace, i.e. '@code{xml}.
@end defvar

@defun ssax:read-markup-token port
@{@t{sxml.ssax}@}
This procedure starts parsing of a markup token. The current position
in the stream must be @code{#\<}. This procedure scans enough of the input stream
to figure out what kind of a markup token it is seeing. The procedure returns
an xml-token structure describing the token. Note, generally reading
of the current markup is not finished! In particular, no attributes of
the start-tag token are scanned.

Here's a detailed break out of the return values and the position in the @var{port}
when that particular value is returned:
@table @code
@item PI-token
only @code{PI}-target is read.
To finish the Processing Instruction and disregard it,
call @code{ssax:skip-pi}. @code{ssax:read-attributes} may be useful
as well (for @code{PI}s whose content is attribute-value
pairs)
@item END-token
The end tag is read completely; the current position
is right after the terminating @code{#\>} character.
@item COMMENT
is read and skipped completely. The current position
is right after "@code{-->}" that terminates the comment.
@item CDSECT
The current position is right after "@code{<!CDATA[}".
Use @code{ssax:read-cdata-body} to read the rest.
@item DECL
We have read the keyword (the one that follows "@code{<!}")
identifying this declaration markup. The current
position is after the keyword (usually a
whitespace character)
@item START-token
We have read the keyword (@code{GI}) of this start tag.
No attributes are scanned yet. We don't know if this
tag has an empty content either.
Use @code{ssax:complete-start-tag} to finish parsing of
the token.
@end table
@end defun

@defun ssax:skip-pi port
@{@t{sxml.ssax}@}
The current position is inside a @code{PI}. Skip till the rest of the @code{PI}.
@end defun

@defun ssax:read-pi-body-as-string port
@{@t{sxml.ssax}@}
The current position is right after reading the @code{PITarget}. We read the
body of @code{PI} and return it as a string. The port will point to the
character right after '@code{?>}' combination that terminates @code{PI}.
@example
 [16] PI ::= '<?' PITarget (S (Char* - (Char* '?>' Char*)))? '?>'
@end example
@end defun

@defun ssax:skip-internal-dtd port
@{@t{sxml.ssax}@}
The current pos in the port is inside an internal DTD subset
(e.g., after reading @code{#\[ }that begins an internal DTD subset)
Skip until the "@code{]>}" combination that terminates this DTD
@end defun

@defun ssax:read-cdata-body port str-handler seed
@{@t{sxml.ssax}@}
This procedure must be called after we have read a string "@code{<![CDATA[}"
that begins a @code{CDATA} section. The current position must be the first
position of the @code{CDATA} body. This function reads @emph{lines} of the @code{CDATA}
body and passes them to a @var{STR-HANDLER}, a character data consumer.

The str-handler is a @var{STR-HANDLER}, a procedure @code{string1} @var{string2} @var{seed}.
The first @var{string1} argument to @var{STR-HANDLER} never contains a newline.
The second @var{string2} argument often will. On the first invocation of
the @var{STR-HANDLER}, the seed is the one passed to @code{ssax:read-cdata-body}
as the third argument. The result of this first invocation will be
passed as the seed argument to the second invocation of the line
consumer, and so on. The result of the last invocation of the
@var{STR-HANDLER} is returned by the @code{ssax:read-cdata-body}.  Note a
similarity to the fundamental '@code{fold}' iterator.

Within a @code{CDATA} section all characters are taken at their face value,
with only three exceptions:
@itemize @bullet
@item
@code{CR}, @code{LF}, and @code{CRLF} are treated as line delimiters, and passed
as a single @code{#\newline} to the @var{STR-HANDLER}.
@item
"@code{]]>}" combination is the end of the @code{CDATA} section.
@item
@code{&gt;} is treated as an embedded @code{#\>} character.
Note, @code{&lt;} and @code{&amp;} are not specially recognized (and are not expanded)!
@end itemize
@end defun

@defun ssax:read-char-ref port
@{@t{sxml.ssax}@}
@example
 [66]  CharRef ::=  '&#' [0-9]+ ';'
                  | '&#x' [0-9a-fA-F]+ ';'
@end example
This procedure must be called after we we have read "@code{&#}"
that introduces a char reference.
The procedure reads this reference and returns the corresponding char.
The current position in @var{port} will be after "@code{;}" that terminates
the char reference.
Faults detected: @code{WFC: XML-Spec.html#wf-Legalchar}.

According to Section "4.1 Character and Entity References"
of the XML Recommendation:
@quotation
"[Definition: A character reference refers to a specific character
 in the ISO/IEC 10646 character set, for example one not directly
 accessible from available input devices.]"
@end quotation
Therefore, we use a @code{ucscode->char} function to convert a character
code into the character -- @emph{regardless} of the current character
encoding of the input stream.
@end defun

@defun ssax:handle-parsed-entity port name entities content-handler str-handler seed
@{@t{sxml.ssax}@}
Expand and handle a parsed-entity reference
@itemize @bullet
@item
@var{port} - a PORT
@item
@var{name} - the name of the parsed entity to expand, a symbol.
@item
@var{entities} - see @var{ENTITIES}
@item
@var{content-handler} - procedure @var{port} @var{entities} @var{seed}
that is supposed to return a @var{seed}.
@item
@var{str-handler} - a @var{STR-HANDLER}. It is called if the entity in question
turns out to be a pre-declared entity
@end itemize
The result is the one returned by @var{content-handler} or @var{str-handler}.

Faults detected:
@example
  WFC: XML-Spec.html#wf-entdeclared
  WFC: XML-Spec.html#norecursion
@end example
@end defun

@defun ssax:read-attributes port entities
@{@t{sxml.ssax}@}
This procedure reads and parses a production @code{Attribute*}
@example
 [41] Attribute ::= Name Eq AttValue
 [10] AttValue ::=  '"' ([^<&"] | Reference)* '"'
                 | "'" ([^<&'] | Reference)* "'"
 [25] Eq ::= S? '=' S?
@end example
The procedure returns an @var{ATTLIST}, of @var{Name} (as @var{UNRES-NAME}),
@var{Value} (as string) pairs.
The current character on the @var{port} is a non-whitespace character
that is not an ncname-starting character.

Note the following rules to keep in mind when reading an 'AttValue'
"Before the value of an attribute is passed to the application
or checked for validity, the XML processor must normalize it as follows:
@itemize @bullet
@item
a character reference is processed by appending the referenced
character to the attribute value
@item
an entity reference is processed by recursively processing the
replacement text of the entity [see @var{ENTITIES}]
[named entities amp lt gt quot apos are assumed pre-declared]
@item
a whitespace character (@code{#x20}, @code{#xD}, @code{#xA}, @code{#x9}) is processed by appending @code{#x20}
to the normalized value, except that only a single @code{#x20} is appended for a
"@code{#xD#xA}" sequence that is part of an external parsed entity or the
literal entity value of an internal parsed entity
@item
other characters are processed by appending them to the normalized value "
@end itemize

Faults detected:
@example
 WFC: XML-Spec.html#CleanAttrVals
 WFC: XML-Spec.html#uniqattspec
@end example
@end defun

@defun ssax:resolve-name port unres-name namespaces apply-default-ns?
@{@t{sxml.ssax}@}
Convert an @var{unres-name} to a @var{res-name} given the appropriate @var{namespaces}
declarations.
The last parameter @var{apply-default-ns?} determines if the default
namespace applies (for instance, it does not for attribute names)

Per @code{REC-xml-names/#nsc-NSDeclared}, "xml" prefix is considered pre-declared
and bound to the namespace name "@url{http://www.w3.org/XML/1998/namespace}".

This procedure tests for the namespace constraints:
@url{http://www.w3.org/TR/REC-xml-names/#nsc-NSDeclared}.
@end defun

@defun ssax:uri-string->symbol uri-str
@{@t{sxml.ssax}@}
Convert a @var{uri-str} to an appropriate symbol.
@end defun

@defun ssax:complete-start-tag tag port elems entities namespaces
@{@t{sxml.ssax}@}
This procedure is to complete parsing of a start-tag markup. The
procedure must be called after the start tag token has been
read. @var{Tag} is an @var{UNRES-NAME}.
@var{Elem
s} is an instance of @code{xml-decl::elems};
it can be @code{#f} to tell the function to do @emph{no} validation of elements
and their attributes.

This procedure returns several values:
@table @var
@item elem-gi
a @var{RES-NAME}.
@item attributes
element's attributes, an @var{ATTLIST} of @code{(@var{res-name} . @var{string})}
pairs. The list does @emph{not} include @code{xmlns} attributes.
@item namespaces
the input list of namespaces amended with namespace
(re-)declarations contained within the start-tag under parsing
@var{ELEM-CONTENT-MODEL}.
@end table

On exit, the current position in @var{port} will be the first character after
@code{#\>} that terminates the start-tag markup.

Faults detected:
@example
 VC: XML-Spec.html#enum
 VC: XML-Spec.html#RequiredAttr
 VC: XML-Spec.html#FixedAttr
 VC: XML-Spec.html#ValueType
 WFC: XML-Spec.html#uniqattspec (after namespaces prefixes are resolved)
 VC: XML-Spec.html#elementvalid
 WFC: REC-xml-names/#dt-NSName
@end example

Note, although XML Recommendation does not explicitly say it,
@var{xmlns} and @var{xmlns:} attributes don't have to be declared (although they
can be declared, to specify their default value).
@end defun

@defun ssax:read-external-id port
@{@t{sxml.ssax}@}
This procedure parses an @code{ExternalID} production.
@example
 [75] ExternalID ::= 'SYSTEM' S SystemLiteral
                 | 'PUBLIC' S PubidLiteral S SystemLiteral
 [11] SystemLiteral ::= ('"' [^"]* '"') | ("'" [^']* "'")
 [12] PubidLiteral ::=  '"' PubidChar* '"' | "'" (PubidChar - "'")* "'"
 [13] PubidChar ::=  #x20 | #xD | #xA | [a-zA-Z0-9]
                | [-'()+,./:=?;!*#@@$_%]
@end example
This procedure is supposed to be called when an @code{ExternalID} is expected;
that is, the current character must be either @code{#\S} or @code{#\P} that start
correspondingly a @code{SYSTEM} or @code{PUBLIC} token. This procedure returns the
@code{SystemLiteral} as a string. A @code{PubidLiteral} is disregarded if present.
@end defun

@c ----------------------------------------------------------------------
@node SSAX higher-level parsers and scanners, SSAX Highest-level parsers - XML to SXML, SSAX low-level parsing code, Functional XML parser
@subsection SSAX higher-level parsers and scanners
@c NODE SSAXの高レベルのパーザとスキャナ

They parse productions corresponding to the whole (document) entity
or its higher-level pieces (prolog, root element, etc).

@defun ssax:scan-Misc port
@{@t{sxml.ssax}@}
Scan the @code{Misc} production in the context:
@example
[1]  document ::=  prolog element Misc*
[22] prolog ::= XMLDecl? Misc* (doctypedec l Misc*)?
[27] Misc ::= Comment | PI |  S
@end example
The following function should be called in the prolog or epilog contexts.
In these contexts, whitespaces are completely ignored.
The return value from @code{ssax:scan-Misc} is either a @code{PI}-token,
a @code{DECL}-token, a @code{START} token, or EOF.
Comments are ignored and not reported.
@end defun

@defun ssax:read-char-data port expect-eof? str-handler seed
@{@t{sxml.ssax}@}
This procedure is to read the character content of an XML document
or an XML element.
@example
 [43] content ::=
        (element | CharData | Reference | CDSect | PI
         | Comment)*
@end example
To be more precise, the procedure reads @code{CharData}, expands @code{CDSect}
and character entities, and skips comments. The procedure stops
at a named reference, EOF, at the beginning of a @code{PI} or a start/end tag.

@table @var
@item port
a port to read
@item expect-eof?
a boolean indicating if EOF is normal, i.e., the character
data may be terminated by the EOF. EOF is normal
while processing a parsed entity.
@item str-handler
a @var{STR-HANDLER}.
@item seed
an argument passed to the first invocation of @var{STR-HANDLER}.
@end table

The procedure returns two results: @var{seed} and @var{token}.

The @var{seed} is the result of the last invocation of @var{str-handler}, or the
original seed if @var{str-handler} was never called.

@var{Token} can be either an eof-object (this can happen only if
@var{expect-eof?} was @code{#t}), or:
@itemize @bullet
@item
an xml-token describing a @var{START} tag or an @var{END}-tag;
For a start token, the caller has to finish reading it.
@item
an xml-token describing the beginning of a @code{PI}. It's up to an
application to read or skip through the rest of this @code{PI};
@item
an xml-token describing a named entity reference.
@end itemize

@code{CDATA} sections and character references are expanded inline and
never returned. Comments are silently disregarded.

As the XML Recommendation requires, all whitespace in character data
must be preserved. However, a @code{CR} character (@code{#xD}) must be disregarded
if it appears before a @code{LF} character (@code{#xA}), or replaced by a @code{#xA} character
otherwise. See Secs. 2.10 and 2.11 of the XML Recommendation. See also
the canonical XML Recommendation.
@end defun

@defun ssax:assert-token token kind gi error-cont
@{@t{sxml.ssax}@}
Make sure that @var{token} is of anticipated @var{kind} and has anticipated @var{gi}.
Note @var{gi} argument may actually be a pair of two symbols, Namespace
URI or the prefix, and of the localname.
If the assertion fails, @var{error-cont} is evaluated by passing it
three arguments: @var{token} @var{kind} @var{gi}.
The result of @var{error-cont} is returned.
@end defun

@c ----------------------------------------------------------------------
@node SSAX Highest-level parsers - XML to SXML,  , SSAX higher-level parsers and scanners, Functional XML parser
@subsection SSAX Highest-level parsers - XML to SXML
@c NODE SSAXの高レベルのパーザ - XMLからSXMLへ

These parsers are a set of syntactic forms to instantiate a SSAX parser.
A user can instantiate the parser to do the full validation, or
no validation, or any particular validation. The user specifies
which @code{PI} he wants to be notified about. The user tells what to do
with the parsed character and element data. The latter handlers
determine if the parsing follows a SAX or a DOM model.

@defmac ssax:make-pi-parser my-pi-handlers
@{@t{sxml.ssax}@}
Create a parser to parse and process one Processing Element (@code{PI}).

@var{My-pi-handlers}:
An assoc list of pairs (@var{PI-TAG} . @var{PI-HANDLER})
where @var{PI-TAG} is an @var{NCName} symbol, the @code{PI} target, and
@var{PI-HANDLER} is a procedure @var{port} @var{pi-tag} @var{seed}
where @var{port} points to the first symbol after the @code{PI} target.
The handler should read the rest of the @code{PI} up to and including
the combination '@code{?>}' that terminates the @code{PI}. The handler should
return a new seed.
One of the @var{PI-TAG}s may be a symbol @code{*DEFAULT*}. The corresponding
handler will handle @code{PI}s that no other handler will. If the
@code{*DEFAULT*} @var{PI-TAG} is not specified,
@code{ssax:make-pi-parser} will make
one, which skips the body of the @code{PI}.

The output of the @code{ssax:make-pi-parser} is a procedure
@var{port} @var{pi-tag} @var{seed},
that will parse the current @code{PI} accoding to user-specified handlers.
@end defmac

@defmac ssax:make-elem-parser my-new-level-seed my-finish-element my-char-data-handler my-pi-handlers
@{@t{sxml.ssax}@}
Create a parser to parse and process one element, including its
character content or children elements. The parser is typically
applied to the root element of a document.

@table @var
@item my-new-level-seed
procedure @var{elem-gi} @var{attributes} @var{namespaces} @var{expected-content} @var{seed} @*
where @var{elem-gi} is a @var{RES-NAME} of the element
about to be processed.
This procedure is to generate the seed to be passed
to handlers that process the content of the element.
@c This is the function identified as 'fdown' in the denotational
@c semantics of the XML parser given in the title comments to this

@item my-finish-element
procedure @var{elem-gi} @var{attributes} @var{namespaces} @var{parent-seed} @var{seed} @*
This procedure is called when parsing of @var{elem-gi} is finished.
The @var{seed} is the result from the last content parser (or
from @var{my-new-level-seed} if the element has the empty content).
@var{Parent-seed} is the same seed as was passed to @var{my-new-level-seed}.
The procedure is to generate a seed that will be the result
of the element parser.
@c This is the function identified as 'fup' in the denotational
@c semantics of the XML parser given in the title comments to this

@item my-char-data-handler
A @var{STR-HANDLER}.

@item my-pi-handlers
See @code{ssax:make-pi-handler} above.
@end table

The generated parser is a:
procedure @var{start-tag-head} @var{port} @var{elems} @var{entities}
@var{namespaces} @var{preserve-ws?} @var{seed}. @*
The procedure must be called after the start tag token has been
read. @var{Start-tag-head} is an @var{UNRES-NAME} from the start-element tag.
@var{Elems} is an instance of @code{xml-decl::elems}.
See @code{ssax:complete-start-tag::preserve-ws?}

Faults detected:
@example
 VC: XML-Spec.html#elementvalid
 WFC: XML-Spec.html#GIMatch
@end example
@end defmac

@defmac ssax:make-parser user-handler-tag user-handler-proc @dots{}
@{@t{sxml.ssax}@}
Create an XML parser, an instance of the XML parsing framework.
This will be a SAX, a DOM, or a specialized parser depending
on the supplied user-handlers.

@var{user-handler-tag} is a symbol that identifies a procedural expression
that follows the tag. Given below are tags and signatures of the
corresponding procedures. Not all tags have to be specified. If some
are omitted, reasonable defaults will apply.

@table @code
@item tag: @var{DOCTYPE}
handler-procedure: @var{port} @var{docname} @var{systemid} @var{internal-subset?} @var{seed}

If @var{internal-subset?} is @code{#t}, the current position in the port
is right after we have read @code{#\[} that begins the internal DTD subset.
We must finish reading of this subset before we return
(or must call skip-internal-subset if we aren't interested in reading it).
The port at exit must be at the first symbol after the whole
DOCTYPE declaration.

The handler-procedure must generate four values: @*
@var{elems} @var{entities} @var{namespaces} @var{seed}@*
See @code{xml-decl::elems} for @var{elems}.
It may be @code{#f} to switch off the validation.
@var{namespaces} will typically contain @var{USER-PREFIX}es for selected @var{URI-SYMB}s.
The default handler-procedure skips the internal subset,
if any, and returns @code{(values #f '() '() seed)}.

@item tag: @var{UNDECL-ROOT}
handler-procedure: @var{elem-gi} @var{seed} @*
where @var{elem-gi} is an @var{UNRES-NAME} of the root element. This procedure
is called when an XML document under parsing contains @emph{no} @code{DOCTYPE}
declaration.
The handler-procedure, as a DOCTYPE handler procedure above,
must generate four values: @*
@var{elems} @var{entities} @var{namespaces} @var{seed}@*
The default handler-procedure returns @code{(values #f '() '() seed)}.

@item tag: @var{DECL-ROOT}
handler-procedure: @var{elem-gi} @var{seed} @*
where @var{elem-gi} is an @var{UNRES-NAME} of the root element. This procedure
is called when an XML document under parsing does contains the @code{DOCTYPE}
declaration.
The handler-procedure must generate a new @code{seed} (and verify
that the name of the root element matches the doctype, if the handler
so wishes).
The default handler-procedure is the identity function.

@item tag: @var{NEW-LEVEL-SEED}
handler-procedure: see @code{ssax:make-elem-parser}, @var{my-new-level-seed}

@item tag: @var{FINISH-ELEMENT}
handler-procedure: see @code{ssax:make-elem-parser}, @var{my-finish-element}

@item tag: @var{CHAR-DATA-HANDLER}
handler-procedure: see @code{ssax:make-elem-parser}, @var{my-char-data-handler}

@item tag: @var{PI}
handler-procedure: see @code{ssax:make-pi-parser}. @*
The default value is @code{'()}.
@end table

The generated parser is a @*
procedure @var{PORT} @var{SEED}

This procedure parses the document prolog and then exits to
an element parser (created by ssax:make-elem-parser) to handle
the rest.

@example
 [1]  document ::=  prolog element Misc*
 [22] prolog ::= XMLDecl? Misc* (doctypedec | Misc*)?
 [27] Misc ::= Comment | PI |  S

 [28] doctypedecl ::=  '<!DOCTYPE' S Name (S ExternalID)? S?
                        ('[' (markupdecl | PEReference | S)* ']' S?)? '>'
 [29] markupdecl ::= elementdecl | AttlistDecl
                      | EntityDecl
                      | NotationDecl | PI
                      | Comment
@end example
@end defmac

A few utility procedures that turned out useful.

@defun ssax:reverse-collect-str fragments
@{@t{sxml.ssax}@}
given the list of @var{fragments} (some of which are text strings)
reverse the list and concatenate adjacent text strings.
@end defun

@defun ssax:reverse-collect-str-drop-ws fragments
@{@t{sxml.ssax}@}
given the list of fragments (some of which are text strings)
reverse the list and concatenate adjacent text strings.
We also drop "unsignificant" whitespace, that is, whitespace
in front, behind and between elements. The whitespace that
is included in character data is not affected.
We use this procedure to "intelligently" drop "insignificant"
whitespace in the parsed SXML. If the strict compliance with
the XML Recommendation regarding the whitespace is desired, please
use the @code{ssax:reverse-collect-str} procedure instead.
@end defun

@defun ssax:xml->sxml port namespace-prefix-assig
@{@t{sxml.ssax}@}
This is an instance of a SSAX parser above that returns an SXML
representation of the XML document to be read from @var{port}.
@var{Namespace-prefix-assig} is a list of
@code{(@var{USER-PREFIX} . @var{URI-STRING})}
that assigns @var{USER-PREFIX}es to certain namespaces identified by
particular @var{URI-STRING}s. It may be an empty list.
The procedure returns an SXML tree. The port points out to the
first character after the root element.
@end defun

@c ----------------------------------------------------------------------
@node SXML query language, Manipulating SXML structure, Functional XML parser, Library modules - Utilities
@section @code{sxml.sxpath} - SXML query language
@c NODE SXMLクエリ言語, @code{sxml.sxpath} - SXMLクエリ言語

@deftp {Module} sxml.sxpath
@mdindex sxml.sxpath
SXPath is a query language for SXML, an instance of XML Information
set (Infoset) in the form of s-expressions.

It is originally written by Oleg Kiselyov, and
improved by Dmitry Lizorkin and Kirill Lisovsky.
This module also incorporates
various procedures written for SXPath by Dmitry Lizorkin and Kirill Lisovsky.

Current version is based on sxpathlib.scm,v 3.915,
sxpath.scm,v 1.1, and sxpath-ext.scm,v 1.911.
@end deftp

This manual is mostly derived from the comments in the
original source files.

The module consists of three layers.
@enumerate
@item
Basic converters and applicators, which provides the means to
access and translate SXML tree.
@item
High-level query language compiler,
which takes abbreviated SXPath and
returns a Scheme function that selects a nodeset
that satisfies the specified path from the given nodeset.
@item
Extension libraries, which implements
SXML counterparts to W3C XPath Core Functions Library.
@end enumerate

@c ----------------------------------------------------------------------
@menu
* SXPath basic converters and applicators::
* SXPath query language::
* SXPath extension::
@end menu

@node SXPath basic converters and applicators, SXPath query language, SXML query language, SXML query language
@subsection SXPath basic converters and applicators
@c NODE SXPathの基本的なコンバータとアプリケータ

A converter is a function
@example
  type Converter = Node|Nodeset -> Nodeset
@end example
A converter can also play a role of a predicate: in that case, if a
converter, applied to a node or a nodeset, yields a non-empty
nodeset, the converter-predicate is deemed satisfied. Throughout
this file a nil nodeset is equivalent to @code{#f} in denoting a failure.

@defun nodeset? x
@{@t{sxml.sxpath}@}
Returns @code{#t} if given object is a nodeset.
@end defun

@defun as-nodeset x
@{@t{sxml.sxpath}@}
If @var{x} is a nodeset - returns it as is, otherwise wrap it in a list.
@end defun

@defun sxml:element? obj
@{@t{sxml.sxpath}@}
Predicate which returns @code{#t}
if @var{obj} is SXML element, otherwise returns @code{#f}.
@end defun

@defun ntype-names?? crit
@{@t{sxml.sxpath}@}
The function @code{ntype-names??} takes a list of acceptable node names as a
criterion and returns a function, which, when applied to a node,
will return @code{#t} if the node name is present in criterion list
and @code{#f} otherwise.
@example
 ntype-names?? :: ListOfNames -> Node -> Boolean
@end example
@end defun

@defun ntype?? crit
@{@t{sxml.sxpath}@}
The function @code{ntype??} takes a type criterion and returns
a function, which, when applied to a node, will tell if the node satisfies
the test.
@example
  ntype?? :: Crit -> Node -> Boolean
@end example

The criterion @var{crit} is
one of the following symbols:
@table @code
@item id
tests if the Node has the right name (id)
@item @@
tests if the Node is an @var{attributes-list}.
@item *
tests if the Node is an @var{Element}.
@item *text*
tests if the Node is a text node.
@item *data*
tests if the Node is a data node
(text, number, boolean, etc., but not pair).
@item *PI*
tests if the Node is a @code{PI} node.
@item *COMMENT*
tests if the Node is a @code{COMMENT} node.
@item *ENTITY*
tests if the Node is a @code{ENTITY} node.
@item *any*
@code{#t} for any type of Node.
@end table
@end defun

@defun ntype-namespace-id?? ns-id
@{@t{sxml.sxpath}@}
This function takes a namespace-id, and returns a predicate
@code{Node -> Boolean}, which is @code{#t}
for nodes with this very namespace-id.
@var{ns-id} is a string.
@code{(ntype-namespace-id?? #f)} will be @code{#t}
for nodes with non-qualified names.
@end defun

@defun sxml:invert pred
@{@t{sxml.sxpath}@}
This function takes a predicate and returns it inverted .
That is if the given predicate yields @code{#f} or '@code{()} the inverted one
yields the given node (@code{#t}) and vice versa.
@end defun

@defun node-eq? other
@defunx node-equal? other
@{@t{sxml.sxpath}@}
Curried equivalence converter-predicates, i.e.
@example
  ((node-eq? a) b)    @equiv{} (eq? a b)
  ((node-equal? a) b) @equiv{} (equal? a b)
@end example
@end defun

@defun node-pos n
@{@t{sxml.sxpath}@}

@example
 node-pos:: N -> Nodeset -> Nodeset, or
 node-pos:: N -> Converter
@end example

Select the @var{N}'th element of a Nodeset and return as a singular Nodeset;
Return an empty nodeset if the Nth element does not exist.
@code{((node-pos 1) Nodeset)} selects the node at the head of the Nodeset,
if exists;
@code{((node-pos 2) Nodeset)} selects the Node after that, if
exists.
@var{N} can also be a negative number: in that case the node is picked from
the tail of the list.
@code{((node-pos -1) Nodeset)} selects the last node of a non-empty nodeset;
@code{((node-pos -2) Nodeset)} selects the last but one node, if exists.
@end defun

@defun sxml:filter pred?
@{@t{sxml.sxpath}@}

@example
 filter:: Converter -> Converter
@end example

A filter applicator, which introduces a filtering context. The argument
converter is considered a predicate, with either @code{#f}
or nil result meaning failure.
@end defun

@defun take-until pred?
@{@t{sxml.sxpath}@}

@example
 take-until:: Converter -> Converter, or
 take-until:: Pred -> Node|Nodeset -> Nodeset
@end example

Given a converter-predicate and a nodeset, apply the predicate to
each element of the nodeset, until the predicate yields anything but
@code{#f} or nil. Return the elements of the input nodeset that have
been processed
till that moment (that is, which fail the predicate).
@code{take-until} is a variation of the filter above:
@code{take-until} passes
elements of an ordered input set till (but not including) the first
element that satisfies the predicate.
The nodeset returned by @code{((take-until (not pred)) nset)} is a subset --
to be more precise, a prefix -- of the nodeset returned by
@code{((filter pred) nset)}.
@end defun

@defun take-after pred?
@{@t{sxml.sxpath}@}

@example
take-after:: Converter -> Converter, or
take-after:: Pred -> Node|Nodeset -> Nodeset
@end example

Given a converter-predicate and a nodeset, apply the predicate to
each element of the nodeset, until the predicate yields anything but
@code{#f} or
nil. Return the elements of the input nodeset that have not been processed:
that is, return the elements of the input nodeset that follow the first
element that satisfied the predicate.
@code{take-after} along with @code{take-until}
partition an input nodeset into three
parts: the first element that satisfies a predicate, all preceding
elements and all following elements.
@end defun

@defun map-union proc lst
@{@t{sxml.sxpath}@}
Apply proc to each element of lst and return the list of results.
If proc returns a nodeset, splice it into the result.

From another point of view,
@code{map-union} is a function Converter->Converter,
which places an argument-converter in a joining context.
@end defun

@defun node-reverse node-or-nodeset
@{@t{sxml.sxpath}@}

@example
node-reverse :: Converter, or
node-reverse:: Node|Nodeset -> Nodeset
@end example

Reverses the order of nodes in the nodeset.
This basic converter is needed to implement a reverse document order
(see the XPath Recommendation).
@end defun

@defun node-trace title
@{@t{sxml.sxpath}@}

@example
 node-trace:: String -> Converter
@end example

@code{(node-trace title)} is an identity converter. In addition it prints out
a node or nodeset it is applied to, prefixed with the 'title'.
This converter is very useful for debugging.
@end defun

What follow are Converter combinators,
higher-order functions that transmogrify a converter
or glue a sequence of converters into a single, non-trivial
converter. The goal is to arrive at converters that correspond to
XPath location paths.

From a different point of view, a combinator is a fixed, named
@emph{pattern} of applying converters. Given below is a complete set of
such patterns that together implement XPath location path
specification. As it turns out, all these combinators can be built
from a small number of basic blocks: regular functional composition,
map-union and filter applicators, and the nodeset union.

@defun select-kids test-pred?
@{@t{sxml.sxpath}@}

@example
select-kids:: Pred -> Node -> Nodeset
@end example
Given a Node, return an (ordered) subset its children that satisfy
the Pred (a converter, actually).

@example
select-kids:: Pred -> Nodeset -> Nodeset
@end example
The same as above, but select among children of all the nodes in
the Nodeset.
@end defun

@defun node-self pred
@{@t{sxml.sxpath}@}

@example
 node-self:: Pred -> Node -> Nodeset, or
 node-self:: Converter -> Converter
@end example

Similar to select-kids but apply to the Node itself rather
than to its children. The resulting Nodeset will contain either one
component, or will be empty (if the Node failed the Pred).
@end defun

@defun node-join . selectors
@{@t{sxml.sxpath}@}

@example
 node-join:: [LocPath] -> Node|Nodeset -> Nodeset, or
 node-join:: [Converter] -> Converter
@end example

join the sequence of location steps or paths as described
in the title comments above.
@end defun

@defun node-reduce . converters
@{@t{sxml.sxpath}@}

@example
 node-reduce:: [LocPath] -> Node|Nodeset -> Nodeset, or
 node-reduce:: [Converter] -> Converter
@end example

A regular functional composition of converters.
From a different point of view,
@code{((apply node-reduce converters) nodeset)}
is equivalent to
@code{(foldl apply nodeset converters)}
i.e., folding, or reducing, a list of converters with the nodeset
as a seed.
@end defun

@defun node-or . converters
@{@t{sxml.sxpath}@}

@example
 node-or:: [Converter] -> Converter
@end example

This combinator applies all converters to a given node and
produces the union of their results.
This combinator corresponds to a union, '@code{|}' operation for XPath
location paths.
@end defun

@defun node-closure test-pred?
@{@t{sxml.sxpath}@}

@example
 node-closure:: Converter -> Converter
@end example

Select all @emph{descendants} of a node that satisfy a converter-predicate.
This combinator is similar to @code{select-kids} but applies to
grand... children as well.
This combinator implements the "@code{descendant::}" XPath axis.
Conceptually, this combinator can be expressed as
@example
 (define (node-closure f)
      (node-or
        (select-kids f)
	 (node-reduce (select-kids (ntype?? '*)) (node-closure f))))
@end example

This definition, as written, looks somewhat like a fixpoint, and it
will run forever.  It is obvious however that sooner or later
@code{(select-kids (ntype?? '*))} will return an empty nodeset. At
this point further iterations will no longer affect the result and
can be stopped.
@end defun

@c ----------------------------------------------------------------------
@node SXPath query language, SXPath extension, SXPath basic converters and applicators, SXML query language
@subsection SXPath query language
@c NODE SXPathクエリ言語

@defun sxpath abbrpath . ns-binding
@{@t{sxml.sxpath}@}
Evaluates an abbreviated SXPath. Returns a procedure that when applied
on a node or nodeset will return a nodeset matching the given path.

@example
 sxpath:: AbbrPath -> Converter, or
 sxpath:: AbbrPath -> Node|Nodeset -> Nodeset
@end example

@var{AbbrPath} is a list or a string. If it is a list, it is
translated to the full SXPath according to the following rewriting
rules. More informal explanation follows shortly. If it is a string,
it is an XPath query.

Note that these are abstract rules to show how it works, and not the
running code examples. The nonterminals @i{sxpath1} and @i{sxpathr}
don't exist as APIs. The term @i{txpath} is an internal function that
interprets XPath query given as a string.

@example
 (sxpath '()) -> (node-join)
 (sxpath '(path-component ...)) ->
                (node-join (@i{sxpath1} path-component) (sxpath '(...)))
 (@i{sxpath1} '//) -> (node-or
                     (node-self (ntype?? '*any*))
                     (node-closure (ntype?? '*any*)))
 (@i{sxpath1} '(equal? x)) -> (select-kids (node-equal? x))
 (@i{sxpath1} '(eq? x))    -> (select-kids (node-eq? x))
 (@i{sxpath1} '(or@@ ...))  -> (select-kids (ntype-names??
                                          (cdr '(or@@ ...))))
 (@i{sxpath1} '(not@@ ...)) -> (select-kids (sxml:invert
                                         (ntype-names??
                                          (cdr '(not@@ ...)))))
 (@i{sxpath1} '(ns-id:* x)) -> (select-kids
                                      (ntype-namespace-id?? x))
 (@i{sxpath1} ?symbol)     -> (select-kids (ntype?? ?symbol))
 (@i{sxpath1} ?string)     -> (@i{txpath} ?string)
 (@i{sxpath1} procedure)   -> procedure
 (@i{sxpath1} '(?symbol ...)) -> (@i{sxpath1} '((?symbol) ...))
 (@i{sxpath1} '(path reducer ...)) ->
                (node-reduce (sxpath path) (@i{sxpathr} reducer) ...)
 (@i{sxpathr} number)      -> (node-pos number)
 (@i{sxpathr} path-filter) -> (filter (sxpath path-filter))
@end example


SXPath in its simplest form is a list of path components. The result
procedure will follow the same path and return the matching node
list. For example @code{(one two three)} will find element @code{one}
then @code{two} inside it and @code{three} inside element
@code{two}. The equivalent XPath would be @code{one/two/three}.

There are a few special path components (see @code{ntype??} for the
complete list):

@table @code
@item *
matches an element node.
@item //
matches any one or many consecutive path components.
@item *text*
matches a text node (@code{text()} in XPath).
@item *data*
matches any data node (e.g. text, number, boolean, etc.,
but not pair).
@item @@
selects the attribute list node.
@end table

A path component could be a list in one of these forms:

@table @code
@item (equal? x)
matches if the node under examination matches @var{x} using
@code{node-equal?}
@item (eq? x)
matches if the node under examination matches @var{x} using
@code{node-eq?}
@item (or@@ ...)
matches if the element name is one of the specified symbols.
@item (not@@ ...)
matches if the element name is not one of the specified symbols.
@item (ns-id:* x)
matches the node if it's with namespace @var{x}
@item (<path> n)
matches the @var{n}-th node matching same path component. @var{n}
starts from 1. Negative numbers start from the end of the node list
backward. This is @code{path[n]} syntax in XPath.
@item (<path> (<predicate>...))
matches a path component @var{path} and @code{(sxpath (<predicate>...))}
on those nodes are not empty. This is @code{path[predicate...]} syntax
in XPath.
@end table

If the path component is a string, it is interpreted as an XPath query
string.

If the path component is a procedure, the procedure takes three
arguments: the nodeset being examined, the root node and the variable
bindings.

The root node is usually the entire sxml being applied. However if you
apply the result sxpath procedure with two arguments, root-node will
be the second argument.

When applied with three arguments, the variable bindings are the third
one. This lets you pass arguments to the procedure.


@smalllisp
;; select all <book> elements whose style attribute value is equal to
;; the <bookstore> element's specialty attribute value.
(sxpath "//book[/bookstore/@@specialty=@@style]")
;; a similar query but this time make sure specialty of _all_
;; bookstores is matched
(let ([match-specialty
       (lambda (node root var-binding)
         (let ([style (car ((sxpath '(@@ style *text*)) node))]
               [all-specialty ((sxpath '(bookstore @@ specialty *text*)) node)])
           (fold (lambda (specialty last-result)
                   (and last-result (string=? style specialty)))
                        #t
                        all-specialty)))])
  (sxpath `(// (book (,match-specialty)))))

;; select all <bookstore> elements that are inside top-level <book>
;; element
(sxpath '(book bookstore))
;; select all <bookstore> elements from anywhere
(sxpath '(// bookstore))
;; select attribute "name" in the top-level <book> element
(sxpath '(book @@ name))
;; select all <bookstore> and <bookshop> elements that are inside
;; top-level <book> element
(sxpath '(book (or@@ bookstore bookshop)))
;; select all elements except <movie> that are inside top-level <book>
;; element
(sxpath '(book (not@@ movie @@)))
;; select the attribute "name" of the second <bookstore> element
(sxpath '(book (bookstore 2) @@ name))
;; select the attribute "name" of all <bookstore> elements that has
;; attribute "recommended"
(sxpath '(book (bookstore (@@ recommended)) @@ name))
;; select the attribute "name" of all <bookstore> elements whose
;; "rating" attribute is 3
(sxpath '(book (bookstore (@@ rating (eq? 3))) @@ name))
;; select the attribute "rating" whose value is greater than 3 from
;; all <bookstore> elements
(let ([greater (lambda (nodeset root-node var-binding)
                 (filter (lambda (node)
                           (> (string->number (sxml:string-value node))
                              3))
                         nodeset))])
  (sxpath `(book bookstore @@ rating ,greater)))
@end smalllisp
@end defun

Some wrapper functions around @code{sxpath}:

@defun if-sxpath path
@{@t{sxml.sxpath}@}
@code{sxpath} always returns a list, which is @code{#t} in Scheme.
@code{if-sxpath} returns @code{#f} instead of empty list.
@end defun

@defun if-car-sxpath path
@{@t{sxml.sxpath}@}
Returns first node found, if any.
Otherwise returns @code{#f}.
@end defun

@defun car-sxpath path
@{@t{sxml.sxpath}@}
Returns first node found, if any.
Otherwise returns empty list.
@end defun

@defun sxml:id-alist node . lpaths
@{@t{sxml.sxpath}@}
Built an index as a list of
@code{(@var{ID_value} . @var{element})} pairs for given
node.  @var{lpaths} are location paths for attributes of type ID.
@end defun

@c ----------------------------------------------------------------------
@node SXPath extension,  , SXPath query language, SXML query language
@subsection SXPath extension
@c NODE SXPathの拡張

SXML counterparts to W3C XPath Core Functions Library.

@defun sxml:string object
@{@t{sxml.sxpath}@}
The counterpart to XPath @code{string} function (section 4.2 XPath Rec.)
Converts a given object to a string.
NOTE:
@enumerate
@item
When converting a nodeset - a document order is not preserved
@item
@var{number->string} function returns the result in a form which is slightly
different from XPath Rec. specification
@end enumerate
@end defun

@defun sxml:boolean object
@{@t{sxml.sxpath}@}
The counterpart to XPath @code{boolean} function (section 4.3 XPath Rec.)
Converts its argument to a boolean.
@end defun

@defun sxml:number obj
@{@t{sxml.sxpath}@}
The counterpart to XPath @code{number} function (section 4.4 XPath Rec.)
Converts its argument to a number
NOTE:
@enumerate
@item
The argument is not optional (yet?).
@item
@code{string->number} conversion is not IEEE 754 round-to-nearest.
@item
NaN is represented as 0.
@end enumerate
@end defun

@defun sxml:string-value node
@{@t{sxml.sxpath}@}
Returns a string value for a given node in accordance to
XPath Rec. 5.1 - 5.7
@end defun


@defun sxml:node? node
@{@t{sxml.sxpath}@}
According to XPath specification 2.3, this test is true for any
XPath node.
For SXML auxiliary lists and lists of attributes has to be excluded.
@end defun

@defun sxml:attr-list obj
@{@t{sxml.sxpath}@}
Returns the list of attributes for a given SXML node.
Empty list is returned if the given node is not an element,
or if it has no list of attributes
@end defun

@defun sxml:id id-index
@{@t{sxml.sxpath}@}
Select SXML element by its unique IDs.  (XPath Rec. 4.1)
Returns a converter that takes @var{object},
which is a nodeset or a datatype which can be converted to a string by means
of a '@code{string}' function.

@var{id-index} is @code{( (id-value . element) (id-value . element) ... )}.

This index is used for selection of an element by its unique ID.
@end defun

Comparators for XPath objects:

@defun sxml:equality-cmp bool-op number-op string-op
@{@t{sxml.sxpath}@}
A helper for XPath equality operations: @code{=} , @code{!=}
@var{bool-op}, @var{number-op} and
@var{'string-op} are comparison operations for
a pair of booleans,  numbers and strings respectively.
@end defun

@defun sxml:equal? a b
@defunx sxml:not-equal? a b
@{@t{sxml.sxpath}@}
Counterparts of XPath equality operations: @code{=} , @code{!=},
using default equality tests.
@end defun

@defun sxml:relational-cmp op
@{@t{sxml.sxpath}@}
Creates a relational operation ( @code{<} , @code{>} , @code{<=} , @code{>=} )
for two XPath objects.
@code{op} is comparison procedure: @code{<} , @code{>} , @code{<=} or @code{>=}.
@end defun

XPath axises.
An order in resulting nodeset is preserved.

@defun sxml:attribute test-pred?
@{@t{sxml.sxpath}@}
Attribute axis.
@end defun

@defun sxml:child test-pred?
@{@t{sxml.sxpath}@}
Child axis.
This function is similar to '@code{select-kids}', but it returns an empty
child-list for PI, Comment and Entity nodes.
@end defun

@defun sxml:parent test-pred?
@{@t{sxml.sxpath}@}
Parent axis.

Given a predicate, it returns a function
@code{RootNode -> Converter}
which yields a
@code{ node -> parent }
converter then applied to a rootnode.

Thus, such a converter may be constructed using
@code{ ((sxml:parent test-pred) rootnode) }
and returns a parent of a node it is applied to.
If applied to a nodeset, it returns the
list of parents of nodes in the nodeset. The rootnode does not have
to be the root node of the whole SXML tree -- it may be a root node
of a branch of interest.
The @code{parent::} axis can be used with any SXML node.
@end defun

@defun sxml:ancestor test-pred?
@{@t{sxml.sxpath}@}
Ancestor axis
@end defun

@defun sxml:ancestor-or-self test-pred?
@{@t{sxml.sxpath}@}
Ancestor-or-self axis
@end defun

@defun sxml:descendant test-pred?
@{@t{sxml.sxpath}@}
Descendant axis
@end defun

@defun sxml:descendant-or-self test-pred?
@{@t{sxml.sxpath}@}
Descendant-or-self axis
@end defun

@defun sxml:following test-pred?
@{@t{sxml.sxpath}@}
Following axis
@end defun

@defun sxml:following-sibling test-pred?
@{@t{sxml.sxpath}@}
Following-sibling axis
@end defun

@defun sxml:namespace test-pred?
@{@t{sxml.sxpath}@}
Namespace axis
@end defun

@defun sxml:preceding test-pred?
@{@t{sxml.sxpath}@}
Preceding axis
@end defun

@defun sxml:preceding-sibling test-pred?
@{@t{sxml.sxpath}@}
Preceding-sibling axis
@end defun

Popular shortcuts:

@defun sxml:child-nodes nodeset
@{@t{sxml.sxpath}@}
@example
((sxml:child sxml:node?) nodeset)
@end example
@end defun

@defun sxml:child-elements nodeset
@{@t{sxml.sxpath}@}
@example
((select-kids sxml:element?) nodeset)
@end example
@end defun


@c ----------------------------------------------------------------------
@node Manipulating SXML structure, Serializing XML and HTML from SXML, SXML query language, Library modules - Utilities
@section @code{sxml.tools} - Manipulating SXML structure
@c NODE SXML構造を操作する, @code{sxml.tools} - SXML構造を操作する

@deftp {Module} sxml.tools
@mdindex sxml.tools

This module is a port of Kirill Lisofsky's sxml-tools,
a collection of convenient procedures that work on
SXML structure.
The current version is derived from sxml-tools CVS revision 3.13.

The manual entry is mainly derived from the comments in the original
source code.
@end deftp

@c ----------------------------------------------------------------------
@menu
* SXML predicates::
* SXML accessors::
* SXML modifiers::
* SXPath auxiliary utilities::
* SXML to markup conversion::
@end menu

@c ----------------------------------------------------------------------
@node SXML predicates, SXML accessors, Manipulating SXML structure, Manipulating SXML structure
@subsection SXML predicates
@c NODE SXMLの述語

@defun sxml:empty-element? obj
@{@t{sxml.tools}@}
A predicate which returns @code{#t} if given element @var{obj} is empty.
Empty element has no nested elements, text nodes, @code{PI}s,
Comments or entities
but it may contain attributes or namespace-id.
It is a SXML counterpart of XML @code{empty-element}.
@end defun

@defun sxml:shallow-normalized? obj
@{@t{sxml.tools}@}
Returns @code{#t} if the given @var{obj} is shallow-normalized SXML element.
The element itself has to be normalized but its nested elements are not tested.
@end defun

@defun sxml:normalized? obj
@{@t{sxml.tools}@}
Returns @code{#t} if the given @var{obj} is normalized SXML element.
The element itself and all its nested elements have to be normalised.
@end defun

@defun sxml:shallow-minimized? obj
@{@t{sxml.tools}@}
Returns @code{#t} if the given @var{obj} is shallow-minimized SXML element.
The element itself has to be minimised but its nested elements are not tested.
@end defun

@defun sxml:minimized? obj
@{@t{sxml.tools}@}
Returns @code{#t} if the given @var{obj} is minimized SXML element.
The element itself and all its nested elements have to be minimised.
@end defun

@c ----------------------------------------------------------------------
@node SXML accessors, SXML modifiers, SXML predicates, Manipulating SXML structure
@subsection SXML accessors
@c NODE SXMLへのアクセッサ

@defun sxml:name obj
@{@t{sxml.tools}@}
Returns a name of a given SXML node.
It's just an alias of @code{car}, but introduced for the sake of encapsulation.
@end defun

@defun sxml:element-name obj
@{@t{sxml.tools}@}
A version of @code{sxml:name}, which returns @code{#f}
if the given @var{obj} is not a SXML element.
Otherwise returns its name.
@end defun

@defun sxml:node-name obj
@{@t{sxml.tools}@}
Safe version of @code{sxml:name}, which returns @code{#f}
if the given @var{obj} is not a SXML node.
Otherwise returns its name.
@end defun

@defun sxml:ncname obj
@{@t{sxml.tools}@}
Returns Local Part of Qualified Name (Namespaces in XML production [6])
for given obj, which is "@code{:}"-separated suffix of its Qualified Name.
If a name of a node given is @code{NCName} (Namespaces in XML production [4]),
then it is returned as is.
Please note that while SXML name is a symbol this function returns a string.
@end defun

@defun sxml:name->ns-id sxml-name
@{@t{sxml.tools}@}
Returns namespace-id part of given name, or @code{#f} if it's LocalName
@end defun

@defun sxml:content obj
@{@t{sxml.tools}@}
Returns the content of given SXML element or nodeset (just text and element
nodes) representing it as a list of strings and nested elements in document
order.  This list is empty if @var{obj} is empty element or empty list.
@end defun

@defun sxml:content-raw obj
@{@t{sxml.tools}@}
Returns all the content of normalized SXML element except
@var{attr-list} and @var{aux-list}.
Thus it includes @code{PI}, @code{COMMENT} and @code{ENTITY}
nodes as well as @code{TEXT} and @code{ELEMENT} nodes
returned by @code{sxml:content}.
Returns  a list of nodes in document order or empty list if @var{obj} is empty
element or empty list.
This function is faster than @code{sxml:content}.
@end defun

In SXML normal form, an element is represented by a list as this:
@example
  (@var{name} @var{attr-list} @var{aux-list} @var{content} @dots{})
@end example
where @var{attr-list} is a list beginning with @code{@@},
and @var{aux-list} is a list beginning with @code{@@@@}.

In the minimized form,
@var{Aux-list} can be omitted when it is empty.
@var{Attr-list} can be omitted when it is empty @emph{and}
@var{aux-list} is absent.

The following procedures extract @var{attr-list} and @var{aux-list}.

@defun sxml:attr-list-node obj
@{@t{sxml.tools}@}
Returns @var{attr-list} for a given @var{obj},
or @code{#f} if it is absent
@end defun

@defun sxml:attr-as-list obj
@{@t{sxml.tools}@}
Returns @var{attr-list} wrapped in list,
or '@code{((@@))} if it is absent and @var{aux-list} is present,
or '@code{()} if both lists are absent.
@end defun

@defun sxml:aux-list-node obj
@{@t{sxml.tools}@}
Returns @var{aux-list} for a given @var{obj},
or @code{#f} if it is absent.
@end defun

@defun sxml:aux-as-list obj
@{@t{sxml.tools}@}
Returns @var{aux-list} wrapped in list,
or '@code{()} if it is absent.
@end defun

@defun sxml:attr-list-u obj
@{@t{sxml.tools}@}
Returns the list of attributes for given element or nodeset.
Analog of @code{((sxpath '(@@ *)) @var{obj})}.
Empty list is returned if there is no list of attributes.

The @code{-u} suffix indicates it can be used for non-normalized
SXML node.  ('u' stands for 'universal').
@end defun

@defun sxml:aux-list obj
@{@t{sxml.tools}@}
Returns the list of auxiliary nodes for given element or nodeset.
Analog of @code{((sxpath '(@@@@ *)) @var{obj})}.
Empty list is returned if a list of auxiliary nodes is absent.
@end defun

@defun sxml:aux-list-u obj
@{@t{sxml.tools}@}
Returns the list of auxiliary nodes for given element or nodeset.
Analog of @code{((sxpath '(@@@@ *)) @var{obj})}.
Empty list is returned if a list of auxiliary nodes is absent.

The @code{-u} suffix indicates it can be used for non-normalized
SXML node.  ('u' stands for 'universal').
@end defun

@defun sxml:aux-node obj aux-name
@{@t{sxml.tools}@}
Return the first aux-node with @var{aux-name}
given in SXML element @var{obj}
or @code{#f} is such a node is absent.
Note: it returns just the @emph{first} node found even if multiple nodes are
present, so it's mostly intended for nodes with unique names .
@end defun

@defun sxml:aux-nodes obj aux-name
@{@t{sxml.tools}@}
Return a list of aux-node with @var{aux-name}
given in SXML element @var{obj}
or '@code{()} if such a node is absent.
@end defun

@defun sxml:attr obj attr-name
@{@t{sxml.tools}@}
Accessor for an attribute @var{attr-name} of
given SXML element @var{obj}.
It returns:
the value of the attribute if the attribute is present, or
@code{#f} if there is no such an attribute in the given element.
@end defun

@defun sxml:num-attr obj attr-name
@{@t{sxml.tools}@}
Accessor for a numerical attribute @var{attr-name}
of given SXML element @var{obj}.
It returns:
a value of the attribute as the attribute as a number if the attribute
is present and its value may be converted to number using @code{string->number},
or @code{#f} if there is no such an attribute in the given element or
its value can't be converted to a number.
@end defun

@defun sxml:attr-u obj attr-name
@{@t{sxml.tools}@}
Accessor for an attribute @var{attr-name}
of given SXML element @var{obj} which
may also be an attributes-list or nodeset (usually content of SXML element).

It returns:
the value of the attribute if the attribute is present,
or @code{#f} if there is no such an attribute in the given element.

The @code{-u} suffix indicates it can be used for non-normalized
SXML node.  ('u' stands for 'universal').
@end defun

@defun sxml:ns-list obj
@{@t{sxml.tools}@}
Returns the list of namespaces for given element.
Analog of @code{((sxpath '(@@@@ *NAMESPACES* *)) @var{obj})}
Empty list is returned if there is no list of namespaces.
@end defun

@defun sxml:ns-id->nodes obj namespace-id
@{@t{sxml.tools}@}
Returns the list of namespace-assoc's for given @var{namespace-id} in
SXML element @var{obj}.
Analog of @code{((sxpath '(@@@@ *NAMESPACES* namespace-id)) @var{obj})}.
Empty list is returned if there is no namespace-assoc with
@var{namespace-id} given.
@end defun

@defun sxml:ns-id->uri obj namespace-id
@{@t{sxml.tools}@}
Returns a URI for @var{namespace-id} given, or
@code{#f} if there is no namespace-assoc with @var{namespace-id} given.
@end defun

@defun sxml:ns-uri->id obj uri
@{@t{sxml.tools}@}
Returns a namespace-id for namespace URI given.
@end defun

@defun sxml:ns-id ns-assoc
@{@t{sxml.tools}@}
Returns namespace-id for given namespace-assoc list.
@end defun

@defun sxml:ns-uri ns-assoc
@{@t{sxml.tools}@}
Returns URI for given namespace-assoc list.
@end defun

@defun sxml:ns-prefix ns-assoc
@{@t{sxml.tools}@}
It returns namespace prefix for given namespace-assoc list.
Original (as in XML document) prefix for namespace-id given
has to be strored as the third element in namespace-assoc list
if it is different from namespace-id.
If original prefix is omitted in namespace-assoc then
namespace-id is used instead.
@end defun

@c ----------------------------------------------------------------------
@node SXML modifiers, SXPath auxiliary utilities, SXML accessors, Manipulating SXML structure
@subsection SXML modifiers
@c NODE SXMLのモディファイヤ

Constructors and mutators for normalized SXML data.
These functions are optimized for normalized SXML data.
They are not applicable to arbitrary non-normalized SXML data.

Most of the functions are provided in two variants:
@enumerate
@item
side-effect intended functions for linear update of given elements.
Their names are ended with exclamation mark.
Note that the returned value of this variant is unspecified,
unless explicitly noted.
An example: @code{sxml:change-content!}.
@item
pure functions without side-effects which return modified elements.
An example: @code{sxml:change-content}.
@end enumerate

@defun sxml:change-content obj new-content
@defunx sxml:change-content! obj new-content
@{@t{sxml.tools}@}
Change the content of given SXML element to @var{new-content}.
If @var{new-content} is an empty list then the @var{obj} is transformed
to an empty element.
The resulting SXML element is normalized.
@end defun

@defun sxml:change-attrlist obj new-attrlist
@defunx sxml:change-attrlist! obj new-attrlist
@{@t{sxml.tools}@}
The resulting SXML element is normalized.
If @var{new-attrlist} is empty,
the cadr of @var{obj} is @code{(@@)}.
@end defun

@defun sxml:change-name obj new-name
@defunx sxml:change-name! obj new-name
@{@t{sxml.tools}@}
Change a name of SXML element destructively.
@end defun

@defun sxml:add-attr obj attr
@{@t{sxml.tools}@}
Returns SXML element @var{obj} with attribute @var{attr} added,
or @code{#f} if the attribute with given name already exists.
@var{attr} is @code{(@var{attr-name} @var{attr-value})}.
Pure functional counterpart to @code{sxml:add-attr!}.
@end defun

@defun sxml:add-attr! obj attr
@{@t{sxml.tools}@}
Add an attribute @var{attr} for an element @var{obj}.
Returns @code{#f} if the attribute with given name already exists.
The resulting SXML node is normalized.
Linear update counterpart to @code{sxml:add-attr}.
@end defun

@defun sxml:change-attr obj attr
@{@t{sxml.tools}@}
Returns SXML element @var{obj} with changed value of
attribute @var{attr}, or @code{#f}
if where is no attribute with given name.
@var{attr} is @code{(@var{attr-name} @var{attr-value})}.
@end defun

@defun sxml:change-attr! obj attr
@{@t{sxml.tools}@}
Change value of the attribute for element @var{obj}.
@var{attr} is @code{(@var{attr-name} @var{attr-value})}.
Returns @code{#f} if where is no such attribute.
@end defun

@defun sxml:set-attr obj attr
@defunx sxml:set-attr! obj attr
@{@t{sxml.tools}@}
Set attribute @var{attr} of element @var{obj}.
If there is no such attribute the new one is added.
@end defun

@defun sxml:add-aux obj aux-node
@{@t{sxml.tools}@}
Returns SXML element @var{obj}
with an auxiliary node @var{aux-node} added.
@end defun

@defun sxml:add-aux! obj aux-node
@{@t{sxml.tools}@}
Add an auxiliary node @var{aux-node} for an element @var{obj}.
@end defun

@defun sxml:squeeze obj
@defunx sxml:squeeze! obj
@{@t{sxml.tools}@}
Eliminates empty lists of attributes and aux-lists for given SXML element
@var{obj} and its descendants ("minimize" it).
Returns a minimized and normalized SXML element.
@end defun

@defun sxml:clean obj
@{@t{sxml.tools}@}
Eliminates empty lists of attributes and all aux-lists for given SXML element
@var{obj} and its descendants.
Returns a minimized and normalized SXML element.
@end defun

@c ----------------------------------------------------------------------
@node SXPath auxiliary utilities, SXML to markup conversion, SXML modifiers, Manipulating SXML structure
@subsection SXPath auxiliary utilities
@c NODE SXPathの補助的ユーティリティ

These are convenience utilities to extend SXPath functionalities.

@defun sxml:add-parents obj . top-ptr
@{@t{sxml.tools}@}
Returns an SXML nodeset with a 'parent pointer' added.
A parent pointer is an aux node of the form @code{(*PARENT* @var{thunk})},
where @var{thunk} returns the parent element.
@end defun

@defun sxml:node-parent rootnode
@{@t{sxml.tools}@}
Returns a fast 'node-parent' function, i.e.
a function of one argument - SXML element - which returns its parent
node using @code{*PARENT*} pointer in aux-list.
'@code{*TOP-PTR*} may be used as a pointer to root node.
It return an empty list when applied to root node.
@end defun

@defun sxml:lookup id index
@{@t{sxml.tools}@}
Lookup an element using its ID.
@end defun

@c ----------------------------------------------------------------------
@node SXML to markup conversion,  , SXPath auxiliary utilities, Manipulating SXML structure
@subsection SXML to markup conversion
@c NODE SXMLからマークアップへの変換

Procedures to generate XML or HTML marked up text from SXML.
For more advanced conversion, see the SXML serializer
(@ref{Serializing XML and HTML from SXML}).


@defun sxml:clean-feed . fragments
@{@t{sxml.tools}@}
Filter the 'fragments'.
The fragments are a list of strings, characters,
numbers, thunks, @code{#f} -- and other fragments.
The function traverses the tree depth-first, and returns a list
of strings, characters and executed thunks,
and ignores @code{#f} and '@code{()}.

If all the meaningful fragments are strings, then
@code{(apply string-append ... )}
to a result of this function will return its string-value.

It may be considered as a variant of Oleg Kiselyov's
@code{SRV:send-reply}:
While @code{SRV:send-reply} displays fragments, this function returns the list
of meaningful fragments and filter out the garbage.
@end defun

@defun sxml:attr->xml attr
@{@t{sxml.tools}@}
Creates the XML markup for attributes.
@end defun

@defun sxml:string->xml string
@{@t{sxml.tools}@}
Return a string or a list of strings where all the occurrences of
characters @code{<}, @code{>},
@code{&}, @code{"}, or @code{'} in a given string are
replaced by corresponding
character entity references. See also @code{sxml:string->html}.
@end defun

@defun sxml:sxml->xml tree
@{@t{sxml.tools}@}
A version of dispatch-node specialized and optimized for SXML->XML
transformation.
@end defun

@defun sxml:attr->html attr
@{@t{sxml.tools}@}
Creates the HTML markup for attributes.
@end defun

@defun sxml:string->html string
@{@t{sxml.tools}@}
Given a string, check to make sure it does not contain characters
@var{<}, @var{>}, @var{&},
@var{"} that require encoding.
See also @code{html-escape-string}
in @ref{Simple HTML document construction}.
@end defun

@defun sxml:non-terminated-html-tag? tag
@{@t{sxml.tools}@}
This predicate yields @code{#t} for "non-terminated" HTML 4.0 tags.
@end defun

@defun sxml:sxml->html tree
@{@t{sxml.tools}@}
A version of dispatch-node specialized and optimized for SXML->HTML
transformation.
@end defun

@c ----------------------------------------------------------------------
@node Serializing XML and HTML from SXML, Text terminal control, Manipulating SXML structure, Library modules - Utilities
@section @code{sxml.serializer} -  Serializing XML and HTML from SXML
@c NODE SXMLからXMLとXHTMLのシリアライゼーション, @code{sxml.serializer} - SXMLからXMLとXHTMLのシリアライゼーション

@deftp {Module} sxml.serializer
@mdindex sxml.serializer
This module contains a full-featured serializer from SXML into XML and
HTML, partially conforming to XSLT 2.0 and XQuery 1.0 Serialization
(@uref{http://www.w3.org/TR/2005/CR-xslt-xquery-serialization-20051103/}).
It's more powerful than sxml:sxml->xml and sxml:sxml->html from
sxml.tools.

The manual entry is mainly derived from the comments in the original
source code.
@end deftp

@c ----------------------------------------------------------------------
@menu
* Simple SXML serializing::
* Custom SXML serializing::
@end menu

@c ----------------------------------------------------------------------
@node Simple SXML serializing, Custom SXML serializing, Serializing XML and HTML from SXML, Serializing XML and HTML from SXML
@subsection Simple SXML serializing
@c NODE 簡単なSXML変換

The SXML serializer provides some convenient high-level converters which
should be enough for most tasks.

@defun srl:sxml->xml sxml-obj :optional port-or-filename
@{@t{sxml.serializer}@}
Serializes the @var{sxml-obj} into XML, with indentation to facilitate
readability by a human.

If @var{port-or-filename} is not supplied, the functions return a
string that contains the serialized representation of the
@var{sxml-obj}.

If @var{port-or-filename} is supplied and is a port, the functions
write the serialized representation of @var{sxml-obj} to this port and
return an unspecified result.

If @var{port-or-filename} is supplied and is a string, this string is
treated as an output filename, the serialized representation of
@var{sxml-obj} is written to that filename and an unspecified result
is returned. If a file with the given name already exists, the effect
is unspecified.
@end defun

@defun srl:sxml->xml-noindent sxml-obj :optional port-or-filename
@{@t{sxml.serializer}@}
Serializes the @var{sxml-obj} into XML, without indentation.

Argument @var{port-or-filename} works like described in
@code{srl:sxml->xml}.
@end defun

@defun srl:sxml->html sxml-obj :optional port-or-filename
@{@t{sxml.serializer}@}
Serializes the @var{sxml-obj} into HTML, with indentation to
facilitate readability by a human.

Argument @var{port-or-filename} works like described in @code{srl:sxml->xml}.
@end defun

@defun srl:sxml->html-noindent sxml-obj :optional port-or-filename
@{@t{sxml.serializer}@}
Serializes the @var{sxml-obj} into HTML, without indentation.

Argument @var{port-or-filename} works like described in @code{srl:sxml->xml}.
@end defun

@c ----------------------------------------------------------------------
@node Custom SXML serializing,  , Simple SXML serializing, Serializing XML and HTML from SXML
@subsection Custom SXML serializing
@c NODE カスタムSXML変換

These functions provide full access to all configuration parameters of
the XML serializer.

@defun srl:parameterizable sxml-obj :optional port-or-filename params*
@{@t{sxml.serializer}@}
Generalized serialization procedure, parameterizable with all the
serialization parameters supported by this implementation.

@var{sxml-obj} - an SXML object to serialize

@var{port-or-filename} - either @code{#f}, a port or a string; works
like in srl:sxml->xml (@ref{Simple SXML serializing}).

@var{params} - each parameter is a cons of param-name (a symbol) and
param-value.  The available parameter names and their values are
described below:

@code{method} - Either the symbol @code{xml} or @code{html}.  For a
detailed explanation of the difference between XML and HTML methods,
see XSLT 2.0 and XQuery 1.0 Serialization (@uref{http://www.w3.org/TR/2005/CR-xslt-xquery-serialization-20051103/}).

@code{indent} - Whether the output XML should include whitespace for
human readability (@code{#t} or @code{#f}).  You can also supply a
string, which will be used as the indentation unit.

@code{omit-xml-declaration?} - Whether the XML declaration should be
omitted.  Default: @code{#t}.

@code{standalone} - Whether to define the XML document as standalone in
the XML declaration.  Should be one of the symbols @code{yes},
@code{no} or @code{omit}, the later causing standalone declaration to
be suppressed.  Default: @code{omit}.

@code{version} - The XML version used in the declaration.  A string or
a number.  Default: @code{"1.0"}.

@code{cdata-section-elements} - A list of SXML element names (as
symbols).  The contents of those elements will be escaped as CDATA
sections.

@code{ns-prefix-assig} - A list of @code{(cons prefix namespace-uri)},
where each @code{prefix} is a symbol and each @code{namespace-uri} a
string.  Will serialize the given namespaces with the corresponding
prefixes.

ATTENTION: If a parameter name is unexpected or a parameter value is
ill-formed, the parameter is silently ignored!

Example usage:

@lisp
(srl:parameterizable
  '(tag (@@ (attr "value")) (nested "text node") (empty))
  (current-output-port)
  '(method . xml)  ; XML output method is used by default
  '(indent . "\t")  ; use a single tabulation to indent
  '(omit-xml-declaration . #f)  ; add XML declaration
  '(standalone . yes)  ; denote a standalone XML document
  '(version . "1.0"))  ; XML version
@end lisp

@lisp
param ::= (cons param-name param-value)
param-name ::= symbol

cdata-section-elements
value ::= (listof sxml-elem-name)
sxml-elem-name ::= symbol

indent
value ::= 'yes | #t | 'no | #f | whitespace-string

method
value ::= 'xml | 'html

ns-prefix-assig
value ::= (listof (cons prefix namespace-uri))
prefix ::= symbol
namespace-uri ::= string

omit-xml-declaration?
value ::= 'yes | #t | 'no | #f

standalone
value ::= 'yes | #t | 'no | #f | 'omit

version
value ::= string | number
@end lisp
@end defun

@defun srl:sxml->string sxml-obj cdata-section-elements indent method ns-prefix-assig omit-xml-declaration? standalone version
@{@t{sxml.serializer}@}
Same as @code{srl:parameterizable} returning a string and without the
overhead of parsing parameters.  This function interface may change in
future versions of the library.
@end defun

@defun srl:display-sxml sxml->obj port-or-filename cdata-section-elements indent method ns-prefix-assig omit-xml-declaration? standalone version
@{@t{sxml.serializer}@}
Same as @code{srl:parameterizable} writing output to
@var{port-or-filename} and without the overhead of parsing parameters.
This function interface may change in
future versions of the library.
@end defun

@c ----------------------------------------------------------------------
@node Text terminal control, CSV tables, Serializing XML and HTML from SXML, Library modules - Utilities
@section @code{text.console} - Text terminal control
@c NODE テキスト端末制御, @code{text.console} - テキスト端末制御

@deftp {Module} text.console
@mdindex text.console
This module provides a simple interface for character terminal control.
Currently we support vt100 compatible terminals and Windows
console.

This module doesn't depend on external library such as @code{curses}
and works with Gauche alone, but
what it can do is limited; for example, you can't get an event
when shift key alone is pressed.  For finer controls, you need
some extension libraries.

For an example of the features in this module, see 
@file{snake.scm} in the examples directory of Gauche source distribution.
@end deftp

@subheading Console objects

@deftp {Class} <vt100>
@clindex vt100
@{@t{text.console}@}
Represents a vt100-compatible terminal.   An instance of this class
can be passed to the ``console'' argument of the following generic
functions.

@defivar {<vt100>} iport
Input port connected to the terminal.  The default value is
the standard input port.
@end defivar

@defivar {<vt100>} oport
Output port connected to the terminal.  The default value is
the standard output port.
@end defivar

@defivar {<vt100>} input-delay
The terminal send back special keys encoded in an input escape sequence.
In order to distinguish such keys from the actual ESC key, we time the
input---if the subsequent input doesn't come within @code{input-delay}
microseconds, we interpret the input as individual keystroke, rather
than a part of an escape sequence.  The default value is @code{1000} (1ms).
@end defivar
@end deftp

@deftp {Class} <windows-console>
@clindex windows-console
Represents Windows console.  This class is defined on all platforms,
but its useful methods are only available on Windows-native runtime.

It doesn't have public slots.
@end deftp

The application has to check the runtime to see what kind of console
is available.  A suggested flow is as follows.
@itemize
@item 
If @code{has-windows-console?} returns true, create @code{<windows-console>}
instance.
You don't need @code{cond-expand}; @code{has-windows-console?} returns
@code{#f} on non-Windows platforms.
@item 
Check the environment variable @code{TERM}.  If it is set and
satisfies @code{vt100-compatible?}, you can create
@code{<vt100>} instance.
(Note: It is possible that you end up using @code{<vt100>} console
on Windows; e.g. @code{gosh} running on MSYS shell.)
@item
Otherwise, console isn't available.
@end itemize

The following procedure packages this flow.

@defun make-default-console :key if-not-available
@{@t{text.console}@}
Determines a suitable console class of the running process and
returns its instance.

If no suitable console is available, the behavior depends on the
@var{if-not-available} keyword argument.  If it is @code{:error},
which is default, an error is signalled.  If it is @code{#f},
the procedure returns @code{#f}. 
@end defun

@defun vt100-compatible? string
@{@t{text.console}@}
Given the string value of the environment variable @code{TERM},
returns @code{#t} if the terminal can be handled by @code{<vt100>} console,
@code{#f} otherwise.
@end defun


@subheading Console control

@deffn {Generic function} call-with-console console proc :key mode
@{@t{text.console}@}
Takes over the control of the console, and calls @var{proc} with
@var{console} as the only argument.   The console is set to
the @var{mode}, which must be a symbol @code{with-terminal-mode}
accepts: @code{raw}, @code{rare} or @code{cooked}.  By default
the console is set to @code{rare} mode, which turn off the echoing
and passes most of keystrokes to the program, but it intercepts
terminal controls (like @code{Ctrl-C} for interrupt and
@code{Ctrl-Z} for suspend; the actual key depends on terminal
settings, though.)

If @var{proc} raises an unhandled error, this generic function
resets the terminal mode before returning.  It does not clear
the screen.
@end deffn

@deffn {Generic function} putch console char
@{@t{text.console}@}
Display a character at the current cursor position, and
move the current cursor position.
@end deffn

@deffn {Generic function} putstr console string
@{@t{text.console}@}
Display a string from the current cursor position, and
move the current cursor position.
@end deffn

@deffn {Generic function} beep console
@{@t{text.console}@}
Ring the beep, or flash the screen (visible bell) if possible.
@end deffn

@deffn {Generic function} getch console
@{@t{text.console}@}
Fetch a keypress from the console.  This blocks until
any key is pressed.

The return value may be one of the following values:

@table @asis
@item A character
A key for the character is pressed.  It may be a control code
if the control key is pressed with the key; that is, if the user
presses Ctrl-A, @code{#\x01} will be returned.
@item A symbol
Indicates a special key; the following keys are supported:
@code{KEY_UP}, @code{KEY_DOWN}, @code{KEY_LEFT}, @code{KEY_RIGHT},
@code{KEY_HOME}, @code{KEY_END}, @code{KEY_INS}, @code{KEY_DEL},
@code{KEY_PGDN}, @code{KEY_PGUP}, @code{KEY_F1}, @code{KEY_F2},
@code{KEY_F3}, @code{KEY_F4}, @code{KEY_F5}, @code{KEY_F6},
@code{KEY_F7}, @code{KEY_F8}, @code{KEY_F9}, @code{KEY_F10},
@code{KEY_F11}, @code{KEY_F12}.
(Note: DELETE key is usually mapped to @code{#\x7f}, but it depends on
the terminal).
@item A list of symbol @code{ALT} and a character.
Indicates the character key is pressed with Alt key.  For example,
if the user presses Alt-a, @code{(ALT #\a)} is returned (assuming
CAPSLOCK is off).
@item EOF
Indicates the input is closed somehow.
@end table

Modifier keys except @code{ALT} are not treated separately but
included in the returned keycode.  Assuming CAPSLOCK is off,
if the user press @code{a}, @code{Shift}+@code{a}, and @code{Ctrl}+@code{a},
the returned value is @code{#\a}, @code{#\A} and @code{#\x01}, respectively.
@code{Ctrl}+@code{Shift}+@code{a} can't be distinguished from 
@code{Ctrl}+@code{a}.  @code{ALT}+@code{a}, @code{ALT}+@code{Shift}+@code{a},
and @code{ALT}+@code{Ctrl}+@code{a} will be @code{(ALT #\a)},
@code{(ALT #\A)} and @code{(ALT #\x01)}, respectively.
@end deffn

@deffn {Generic function} chready? console
@{@t{text.console}@}
Returns true if there's a key sequence to be read in the console's
input.
@end deffn

@deffn {Generic function} query-cursor-position console
@{@t{text.console}@}
Returns two values, the current cursor's x and y position.
The top-left corner is (0,0).
@end deffn

@deffn {Generic function} move-cursor-to console row column
@{@t{text.console}@}
Move cursor to the specified position.  The top-left corner is (0,0).
@end deffn

@deffn {Generic function} reset-terminal console
@{@t{text.console}@}
Reset terminal.  Usually this sets the
character attributes to the default,
clears the screen, and moves the cursor to (0, 0).
@end deffn

@deffn {Generic function} clear-screen console
@{@t{text.console}@}
Clear entire screen.
@end deffn

@deffn {Generic function} clear-to-eol console
@{@t{text.console}@}
Clear characters from the current cursor position to the
end of the line.
@end deffn

@deffn {Generic function} clear-to-eos console
@{@t{text.console}@}
Clear characters from the current cursor position to the
end of the screen.
@end deffn

@deffn {Generic function} hide-cursor console
@deffnx {Generic function} show-cursor console
@{@t{text.console}@}
Hide/show the cursor.
@end deffn

@deffn {Generic function} cursor-down/scroll-up console
@{@t{text.console}@}
If the cursor is at the bottom line of the screen,
scroll up the contents and clear the bottom line; the cursor stays
the same position.  If the cursor is not at the bottom line of
the screen, move the cursor down.
@end deffn

@deffn {Generic function} cursor-up/scroll-down console
@{@t{text.console}@}
If the cursor is at the top line of the screen,
scroll down the contents and clear the top line; the cursor stays
the same position.  If the cursor is not at the top line of
the screen, move the cursor up.
@end deffn

@deffn {Generic function} query-screen-size console
@{@t{text.console}@}
Returns two values, the width and height of the screen.

Note: This may affect what's shown in the console.
It is recommended that you only call this before redrawing
the entire screen and save the result.
@end deffn

@deffn {Generic function} set-character-attribute console spec
@{@t{text.console}@}
Set the console so that the subsequent characters will be written
with attributes specified by @var{spec}.

The character attributes spec is a list in the following format:

@example
(<fgcolor> [<bgcolor> . <option> ...])
@end example

where:

@example
<fgcolor> : <color> | #f     ; #f means default
<bgcolor> : <color> | #f
<color>  : black | red | green | yellow | blue | magenta | cyan | white
<option> : bright | reverse | underscore
@end example

For example, you can set characters to be written in red with 
black background and underscore, you can call:

@example
(set-character-attribute con '(red black underscore))
@end example

That the options may seem rather limited in the age of
full-color bitmap displays.  That's what it used to be, young lads.
@end deffn

@deffn {Generic function} reset-character-attribute console
@{@t{text.console}@}
Reset character attributes to the default.
@end deffn

@deffn {Generic function} with-character-attribute console attrs thunk
@{@t{text.console}@}
Sets the console's attributes to @var{attrs} and calls @var{thunk},
then restores the attributes.  Even if @var{thunk} throws an error,
attributes are restored.

Note: You should be able to nest this, but currently nesting
isn't working.
@end deffn


@c ----------------------------------------------------------------------
@node CSV tables, Calculate difference of text streams, Text terminal control, Library modules - Utilities
@section @code{text.csv} - CSV tables
@c NODE CSVテーブル, @code{text.csv} - CSVテーブル

@deftp {Module} text.csv
@mdindex text.csv
Provides a function to parse/generate CSV (comma separated value) tables,
including the format defined in RFC4180.  You can customize the
separator and quoter character to deal with variations of CSV formats.

CSV table is consisted by a series of @var{records}, separated by
a newline.  Each record contains number of @var{fields}, separated
by a separator character (by default, a comma).  A field can contain
comma or newline if quoted, i.e. surrounded by double-quote characters.
To include double-quote character in a quoted field, use two
consecutive double-quote character.   Usually, the whitespaces around
the field are ignored.

Since use cases of CSV-like files vary, we provide layered API
to be combined flexibly.
@end deftp

@subheading Low-level API

The bottom layer of API is to convert text into list of lists and vice versa.

@defun make-csv-reader separator :optional (quote-char #\")
@{@t{text.csv}@}
Returns a procedure with one optional argument, an input port.
When the procedure is called, it reads one record from the port
(or, if omitted, from the current input port)
and returns a list of fields.
If input reaches EOF, it returns EOF.
@end defun

@defun make-csv-writer separator :optional newline (quote-char #\") special-char-set
@{@t{text.csv}@}
Returns a procedure with two arguments, output port and
a list of fields.  When the procedure is called, it
outputs a @var{separator}-separated fields with proper escapes,
to the output port.   Each field value must be a string.
The separator argument can be a character or a string.

You can also specify the record delimiter
string by @var{newline}; for example, you can pass @code{"\r\n"}
to prepare a file to be read by Windows programs.

The output of field is quoted when it contains special characters---
which automatically includes characters
in @var{separator}, @var{quote-char} and @var{newline} argument,
plus the characters in the char-set given to @var{special-char-set};
its default is @code{#[;\s]}.
@end defun

@subheading Middle-level API

Occasionally, CSV files generated from spreadsheet contains
superfluous rows/columns and we need to make sense of them.
Here are some utilities to help them.

A typical format of such spreadsheet-generated CSV file has
the following properties:

@enumerate
@item
There's a ``header row'' near the top; not necessarily the very
first row, but certainly it comes before any real data.  It signifies
the meaning of each column of the data.  
There may be superfluous columns inserted just for cosmetics,
and sometimes the order of columns are changed when the original spreadsheet
is edited.  So we need some
flexibility to interpret the input data.

@item
``Record rows'' follow the header row.  It contains actual data.
There may be superfluous rows inserted just for cosmetics.
Also, it's often the case that the end of data isn't marked clearly
(you find large number of rows of empty strings, for example).
@end enumerate

The main purpose of middle-level CSV parser is to take the output
of low-level parser, which is a list of lists of strings, and
find the header row, and then convert the subsequent record rows
into tuples according to the header row.  A tuple is just a list of
strings, but ordered in the same way as the specified header spec.

@defun csv-rows->tuples rows header-specs :key required-slots allow-gap?
@{@t{text.csv}@}
Convert input rows (a list of lists of strings)
to a list of tuples.
A tuple is a list of slot values.

First, it looks for a header row that
matches the given @var{header-spec}.  Once the header row is found,
parse the subsequent rows as record row according to the header
and convert them to tuples.
If no header is found, @code{#f} is returned.

@var{Header-specs} is a list of header spec, each of which can be either
a string, a regexp, or a predicate on a string.  If it's a string,
a column that exactly matches the string is picked.  If it's a regexp,
a column that matches the regexp is picked.  And if it's a predicate,
as you might have already guessed, a column that satisfies the predicate
is picked.

The order fo @var{header-specs} determines the order of columns of
output tuples.

@var{Required-slots} determines if the input row is a valid record row
or not.  The structure of @var{required-slots} is as follows:

@example
   <required-slots> : (<spec> ...)
   <spec> : <header-spec> | (<header-spec> <predicate>)
@end example

The @code{<header-spec>} compared to the elements of @var{header-slot}
(by @code{equal?}) to figure out which columns to check.  A single
@code{<header-spec>} in @code{<spec>} means that the column shouldn't be
empty for a valid record row.  If @var{<spec>} is a list of
@code{<header-spec>} and @code{<predicate>}, then the value of the
column corresponds to the @var{<header-spec>} is passed to @var{<predicate>}
to determine if it's a valid record row.

If @var{required-slots} is omitted or an empty list, any row with
at least one non-empty column to be included in the tuple.

If @var{allow-gap?} is @code{#t}, it keeps reading rows until the end,
skipping invalid rows.  If @var{allow-gap?} is @code{#f} (default), 
it stops reading once it sees an invalid row after headers.

Let's see an example.  Suppose we have the following CSV file as
@file{data.csv}.  It has extra rows and columns, as is often seen
in spreadsheet-exported files.

@smallexample
,,,,,,,,
"Exported data",,,,,,,,
,,,,,,,,
,,Year,Country,,Population,GDP,,Note
,,1958,"Land of Lisp",,39994,"551,435,453",,
,,1957,"United States of Formula Translators",,115333,"4,343,225,434",,Estimated
,,1959,"People's Republic of COBOL",,82524,"3,357,551,143",,
,,1970,"Kingdom of Pascal",,3785,,,"GDP missing"
,,,,,,,,
,,1962,"APL Republic",,1545,"342,335,151",,
@end smallexample

You can extract tuples of Country, Year, GDP and Population,
as follows:

@smallexample
(use text.csv)
(use gauche.generator)

(call-with-input-file "data.csv" 
  (^p (csv-rows->tuples 
       (generator->list (cute (make-csv-reader #\,) p))
       '("Country" "Year" "GDP" "Population"))))
 @result{}
  (("Land of Lisp" "1958" "551,435,453" "39994")
   ("United States of Formula Translators" "1957" "4,343,225,434" "115333")
   ("People's Republic of COBOL" "1959" "3,357,551,143" "82524")
   ("Kingdom of Pascal" "1970" "" "3785"))
@end smallexample

Note that irrelevant rows are skipped, and columns in the results
are ordered as specified in the @var{header-specs}.

Since there's a gap (empty row) after the ``Kingdom of Pascal'' entry,
@code{csv-rows->tuples} stops processing there by default.  If you want
to include ``APL Republic'', you have to pass @code{:allow-gap? #t}
to @code{csv-rows->tuples}.

The next example gives @code{:required-slots} option to eliminate
rows with missing some of Year, Country or GDP---thus ``Kingdom of Pascal''
is omitted from the result, while ``APL Republic'' is included
because of @code{:allow-gap?} argument.
(It also checks Year has exactly 4 digits.)

@smallexample
(call-with-input-file "data.csv" 
  (^p (csv-rows->tuples 
       (generator->list (cute (make-csv-reader #\,) p))
       '("Country" "Year" "GDP" "Population")
        :required-slots '(("Year" #/^\d@{4@}$/) "Country" "GDP")
        :allow-gap? #t)))
 @result{}
 (("Land of Lisp" "1958" "551,435,453" "39994")
  ("United States of Formula Translators" "1957" "4,343,225,434" "115333")
  ("People's Republic of COBOL" "1959" "3,357,551,143" "82524")
  ("APL Republic" "1962" "342,335,151" "1545"))
@end smallexample
@end defun

The following two procedures are ingredients of 
@code{csv-rows->tuples}:


@defun make-csv-header-parser header-specs
@{@t{text.csv}@}
Create a procedure that takes a row (a list of strings) and checks if
if it matches the criteria specified by @var{header-specs}.
(See @code{csv-rows->tuples} above about @var{header-specs}.)
If the input satisfies the spec, it returns a permuter vector that maps
the tuple positions to the input column numbers.
Otherwise, it returns @code{#f}.

The permuter vector is a vector of integers,
where K-th element being I means the K-th item of the tuple should be
taken from I-th column.

Let's see the example.  Suppose we know that the input contains
the following row as the header row:

@example
(define *input-row*
  '("" "" "Year" "Country" "" "Population" "GDP" "Notes"))
@end example

We want to detect that row, but we only needs
Country, Year, GDP and Population columns, in that order.  So we create
a header parser as follows:

@example
(define header-parser
  (make-csv-header-parser '("Country" "Year" "GDP" "Population")))
@end example

Applying this header parser to the input data returns the permuter vector:

@example
(header-parser *input-row*)
 @result{} #(3 2 6 5)
@end example

It means, the first item of tuple (Country) is in the 3rd column of the input,
the second item of tuple (Year) is in the 2nd column of the input,
and so on.  This permuter vector can be used to parse record rows to
get tuples.
@end defun

@defun make-csv-record-parser header-slots permuter :optional required-slots
@{@t{text.csv}@}
Create a procedure that converts one input row into a tuple.

@var{Permuter} is the vector returned by @code{make-csv-header-parser}.

See @code{cvs-rows->tuples} above for @var{header-slots} and
@var{required-slots} arguments.
@end defun


@c ----------------------------------------------------------------------
@node Calculate difference of text streams, EDN parsing and construction, CSV tables, Library modules - Utilities
@section @code{text.diff} - Calculate difference of text streams
@c NODE テキストストリームの相違点を計算する, @code{text.diff} - テキストストリームの相違点を計算する

@deftp {Module} text.diff
@mdindex text.diff
This module calculates the difference of two text streams or strings,
using @code{util.lcs} (@pxref{The longest common subsequence}).
@end deftp

@defun diff src-a src-b :key reader eq-fn
@{@t{text.diff}@}
Generates an "edit list" from text sources @var{src-a} and @var{src-b}.

Each of text sources, @var{src-a} and @var{src-b}, can be either an input
port or a string.  If it is a string, it is converted to a string input
port internally.  Then, the text streams from both sources are converted
to sequences by calling @var{reader} repeatedly on them; the default
of @var{reader} is @code{read-line}, and those sequences are
passed to @code{lcs-edit-list} to calculate the edit list.
The equality function @var{eq-fn} is also passed to @code{lcs-edit-list}.

An edit list is a set of commands that turn the text sequence
from @code{src-a} to the one from @code{src-b}.
See the description of @code{lcs-edit-list} for
the detailed explanation of the edit list.

@example
(diff "a\nb\nc\nd\n" "b\ne\nd\nf\n")
@result{}
  (((- 0 "a"))
   ((- 2 "c") (+ 1 "e"))
   ((+ 3 "f")))
@end example
@end defun

@defun diff-report src-a src-b :key reader eq-fn writer
@{@t{text.diff}@}
A convenience procedure to take the diff of two text sources
and display the result nicely.  This procedure calls @code{lcs-fold}
to calculate the difference of two text sources.  The meanings of
@var{src-a}, @var{src-b}, @var{reader} and @var{eq-fn} are the
same as @code{diff}'s.

@var{Writer} is a procedure that takes two arguments, the text element
and a type, which is either a symbol @code{+},
a symbol @code{-}, or @code{#f}.   If the text element is only
in @var{src-a}, @var{writer} is called with the element and
@code{-}.  If the text element is only in @var{src-b},
it is called with the element and @code{+}.  If the text element
is in both sources, it is called with the element and
@code{#f}.   The default procedure of @var{writer} prints
the passed text element to the current output port
in unified-diff-like format:
@example
(diff-report "a\nb\nc\nd\n" "b\ne\nd\nf\n")
@end example
displays:
@example
- a
  b
- c
+ e
  d
+ f
@end example
@end defun

@c ----------------------------------------------------------------------
@node EDN parsing and construction, Running external editor, Calculate difference of text streams, Library modules - Utilities
@section @code{text.edn} - EDN parsing and construction
@c NODE EDNのパーズと構築, @code{text.edn} - EDNのパーズと構築

@deftp {Module} text.edn
@mdindex text.edn
EDN (Extensible Data Notation) is a subset of Clojure literals
for data exchange.  This module provides utilities to read and write EDN
format.  See @url{https://github.com/edn-format/edn} for the details of EDN.

@multitable @columnfractions .2 .2 .6
@item EDN @tab Gauche @tab Note
@item @code{true} @tab @code{#t} @tab
@item @code{false} @tab @code{#f} @tab
@item @code{nil} @tab @code{nil}
@tab Clojure's nil is not a symbol but a special value; since Clojure
can't have a symbol named nil, we can map it to Gauche's symbol @code{nil}.
@item number @tab @code{<real>}
@tab Integers and floating point numbers.
The @code{N} and @code{M} suffixes in Clojure are ignored.
@item symbol @tab @code{<symbol>}
@tab Clojure's symbol name has some restrictions, so not all Gauche symbols
map to EDN symbols.
Clojure's namespace-prefixed symbol, e.g. @code{foo/bar} simply maps to
Gauche's symbol @code{foo/bar}; we provide utility procedure to extract
namespace and basename parts.
@item keyword @tab @code{<keyword>}
@tab Clojure has keywords distinct from symbols.  They are mapped to Gauche's
keywords (which is a subtype of symbols).
Gauche's keywords can also be symbols, but
no Clojure symbols begin with @code{:} so there won't be a conflict.
@item list @tab @code{<list>}
@tab Clojure lists are Gauche lists.  Note that Clojure doesn't allow
improper lists.
@item vector @tab @code{<vector>}
@tab Clojure vectors are Gauche vectors.
@item map @tab @code{<hash-table>}
@tab Clojure's map becomes Gauche's hashtable with @code{edn-comparator}
for hashing and comparison.
@item set @tab @code{<set>}
@tab Clojure's set becomes Gauche's set with @code{edn-comparator}
for comparison.  @xref{R7RS sets} for interface of sets.
@item tagged object @tab @code{<edn-object>}
@tab Tagged objects are mapped to @code{<edn-object>} by default. 
You can customize the parser/writer to map tagged objects with a
specific tag to a specific Gauche objects.
@end multitable
@end deftp

@subheading Parsing

@deftp {Condition Type} <edn-parse-error>
When the parser encounters an error, this condition is thrown.
Inherits @code{<error>}.
@end deftp

@defun parse-edn :optional iport
@{@t{text.edn}@}
Read one EDN representation from the given input port, and returns
Gauche object created from it.  If @var{iport} is omitted,
current input port is assumed.

When the parser encounters unparsable sequence, 
it raises @code{<edn-parse-error>}.

Note that @var{iport} may be read ahead for characters. Suppose
the input consists of @code{abc@{:a b@}}, i.e. a symbol immediately
followed by a map.  The parser need to read @code{@{} to know the
end of the symbol. The read-ahead brace isn't pushed back
to the @var{iport}.  So it would be a problem if you keep reading
more EDN subsequently.   Use @code{parse-edn*} if you want to read
multiple objects.
@end defun

@defun parse-edn* :optional iport
@{@t{text.edn}@}
Read EDN representations repeatedly from the given input port
and returns a list of them.  If @var{iport} is omitted,
current input port is assumed.

When the parser encounters unparsable sequence, 
it raises @code{<edn-parse-error>}.
@end defun

@defun parse-edn-string str
@{@t{text.edn}@}
A convenience procedure to parse EDN representation in a string @var{str},
and returns the read object.

When the parser encounters unparsable sequence, 
it raises @code{<edn-parse-error>}.

@example
(parse-edn-string "[1 2 (3 4) @{:a 5@}]")
 @result{} #(1 2 (3 4) #<hash-table general 0x1f05780>)
@end example
@end defun

@subheading Constructing

@defun construct-edn obj :optional oport
@{@t{text.edn}@}
Write out an EDN representation of object @var{obj}
to the output port @var{oport}.  If @var{oport} is omitted,
current output port is assumed.

If @var{obj} contains an object that doesn't have a defined
EDN representation, a generic function @var{edn-write} is called
on it.  See Customization heading below.  If no method is defined for
the object, an error is signaled.
@end defun

@defun construct-edn-string obj
@{@t{text.edn}@}
Returns an EDN representation of @var{obj} in a string.

If @var{obj} contains an object that doesn't have a defined
EDN representation, a generic function @var{edn-write} is called
on it.  See Customization heading below.  If no method is defined for
the object, an error is signaled.

@example
@end example
(construct-edn-string '#(1 2 "abc"))
 @result{} "[1 2 \"abc\"]"
@end defun

@subheading Utilities

@defun edn-equal? a b
@{@t{text.edn}@}
Test equality of two objects that are read from EDN representation.
@end defun

@defvar edn-comparator
@{@t{text.edn}@}
A comparator that uses @code{edn-equal?} for the equality predicate.
Corresponding has function is also included.
EDN maps and sets become Gauche hash-tables and sets with this comparator.
@end defvar

@defun edn-map key value @dots{}
@defunx edn-set item @dots{}
@{@t{text.edn}@}
Convenience procedures to create hash-tables and sets compatible
for EDN.
@end defun

@deftp {Class} <edn-object>
@clindex edn-object
@{@t{text.edn}@}
EDN tagged object becomes an instance of this class by default.
The instance has the following slots, both are immutable:

@defivar <edn-object> tag
Object's tag.  A symbol.
@end defivar

@defivar <edn-object> payload
Object's payload.  Can be any object that can be representable in EDN.
@end defivar

For example, when you read @code{#myobject @{:a 1 :b 2@}},
the tag is @code{myobject} and the payload is a hashtable
containing mapping @code{@{:a 1 :b 2@}}.
@end deftp

@defun make-edn-object tag payload
@{@t{text.edn}@}
Returns a new @code{<edn-object>} instance.
Note: Arguments are not checked.  It's caller's responsibility to
pass valid arguments to guarantee it's serializable as EDN.
@end defun

@defun edn-object? obj
@{@t{text.edn}@}
Returns @code{#t} iff @var{obj} is an instance of @code{<edn-object>}.
@end defun

@defun edn-object-tag edn-object
@defunx edn-object-payload edn-object
@{@t{text.edn}@}
Returns the tag and the payload of @var{edn-object}, respectively.
@end defun

@defun edn-symbol-prefix symbol
@defunx edn-symbol-basename symbol
@{@t{text.edn}@}
Return prefix and basename part of the symbol, respectively.

@example
(edn-symbol-prefix 'foo/bar) @result{} foo
(edn-symbol-basename 'foo/bar) @result{} bar

(edn-symbol-prefix 'bar) @result{} #f
(edn-symbol-basename 'bar) @result{} bar
@end example
@end defun

@defun edn-valid-symbol-name? str
@{@t{text.edn}@}
Returns @code{#t} iff a string @var{str} can be a valid Clojure symbol name.
It may have namespace prefix.
@end defun

@subheading Customization

You can map EDN tagged objects to other Gauche objects.

@defun register-edn-object-handler! tag handler
@{@t{text.edn}@}
@var{Tag} is a symbol, and @var{handler} is @code{#f} or a procedure
that takes a tag symbol and a payload object.

@var{Tag} must have a name valid as Clojure symbol, or an error
is signaled.

After the parser reads a tagged object with a symbol @var{tag}
and payload, it calls @var{handler}, and the returned object
becomes the result of the parser, instead of @code{<edn-object>}.
Registering @code{#f} removes the previously registered handler.

This procedure is thread-safe.

The following example makes EDN @code{#u8vector[1 2 3 4]} to be read
as @code{#u8(1 2 3 4)}:

@example
(register-edn-object-handler! 'u8vector 
                              (^[tag vec] (vector->u8vector vec)))
@end example
@end defun

@defun edn-object-handler tag
@{@t{text.edn}@}
Returns a handler registered with a symbol @var{tag}.  If a handler
is not registered for @var{tag}, @code{#f} is returned.
This procedure is thread-safe.
@end defun

@deffn {Generic Function} edn-write obj
@{@t{text.edn}@}
Write EDN representation of @var{obj} to the current output port.
The @code{construct-edn} procedure calls this internally.

To write out a Gauche object as EDN tagged object, define a method to
this generic function.   In the method you can call @code{edn-write}
recursively to write out components of the object.

The following example writes @code{#u8(1 2 3 4)} as
EDN @code{#u8vector[1 2 3 4]}:

@example
(define-method edn-write ((x <u8vector>))
  (display "#u8vector")
  (edn-write (u8vector->vector x)))
@end example
@end deffn

@c ----------------------------------------------------------------------
@node Running external editor, Gap buffer, EDN parsing and construction, Library modules - Utilities
@section @code{text.external-editor} - Running external editor
@c NODE 外部エディタの起動, @code{text.external-editor} - 外部エディタの起動

@deftp {Module} text.external-editor
@mdindex text.external-editor
A convenience module to invoke external editor program.
This is mainly to be used from REPL, but can be useful for
other purposes.
@end deftp

@defun ed path-or-proc :key editor load-after
@{@t{text.external-editor}@}
Starts an external editor.  The editor program path is determined
in the following order:

@itemize @bullet
@item
The @var{editor} keyword argument, if it's a string.
@item
The value of @code{*editor*} in the user module, if defined.
@item
The value of the environment variable @code{GAUCHE_EDITOR}.
@item
The value of the environment variable @code{EDITOR}.
@item
If none works, the behavior depends on the value of :editor keyword
argument:
@table @code
@item #f
Just returns @code{#f}.
@item error
Throws an error.
@item ask
Asks the user.
@item message
Prints message and returns @code{#f}.
@end table
@end itemize

Returns @code{#t} for normal termination.

The editor program may be called in one of the following way:

@example
EDITOR filename
EDITOR +lineno filename
@end example

The latter expects to locate the cursor on the specified line number
in the filename.

The file to open is determined by a generic function @code{ed-pick-file}.
It should return @code{(@var{filename} @var{lineno})},
or @code{#f} to indicate that it couldn't determine the file to edit.

The @var{load-after} argument controls whether the file is loaded
into the process after the file is modified.  It must be one of
the following values:
@table @code
@item #t
Load the file once editor exits and the file is modified.
@item #f
Do not load the file.
@item ask
Ask the user if the file should be loaded or not.
@end table

NB: Common Lisp's @code{ed} can be invoked without argument.  For our usage,
though, that feature doesn't seem too useful---it's more likely that
repl IS inside an editor so we only need to open a specific file in
a buffer.  Emacsclient requires filename, so it further complicates things.
For now we just require one argument.
@end defun

@defun ed-string string :key editor
@{@t{text.external-editor}@}
Invoke an external editor (as described in @code{ed}) with @var{string}
being the initial content.  Once editor exits,
returns the edited content as a string.
@end defun

@deffn {Generic Function} ed-pick-file obj
@{@t{text.external-editor}@}
Determine what to edit.  It must return a list of
filename and line number, or @code{#f} if it can't find appropriate file to
edit.

Methos for strings, procedures and @code{<top>} are already defined.
If @var{obj} is a string, it is taken as a filename.
If @var{obj} is a procedure and its source location is available,
the source file and the location is returned.
Otherwise, @code{#f} is returned.
@end deffn

@c ----------------------------------------------------------------------
@node Gap buffer, Localized messages, Running external editor, Library modules - Utilities
@section @code{text.gap-buffer} - Gap buffer
@c NODE ギャップバッファ, @code{text.gap-buffer} - ギャップバッファ

@deftp {Module} text.gap-buffer
@mdindex text.gap-buffer
This module provides a gap buffer, a data structure useful for
editable text.

A gap buffer is a vector of characters with a ``cursor'', where
you can insert or delete a character in O(1) time.  Most of
the editing API operate on the current cursor position.
@end deftp

@defun make-gap-buffer :key initial-capacity
@{@t{text.gap-buffer}@}
Creates a fresh gap buffer and returns it.  The initial content
is emtpy.

The keyword argument
@var{initial-capacity} must be a positive exact integer if given,
and specifies the initial capacity of the buffer.  The buffer is
automatically extended if necessary, so the argument is only a 
hint; if you know you'll insert a long string, for example,
you can create a buffer that's large enough to hold it to avoid
reallocation overhead.
@end defun

@defun string->gap-buffer string :optional pos whence start end
@{@t{text.gap-buffer}@}
Creates a gap buffer large enough to contain the given @var{string},
and returns it.

The initial cursor position is set at the end of the string by default.
The @var{pos} and @var{whence} argument can set the initial
cursor position.  The @var{whence} argument must be either a symbol
@code{beginning} or a symbol @code{end}, and @var{pos} must be an exact
integer offset from the whence.  For example, @var{pos} = 10 and 
@var{whence} = @code{beginning} sets the cursor at the 10th character
of the string from the beginning, and @var{pos} = -1 and @var{whence} = 
@code{end} sets the cursor position at one character before the end
of the string.  If the combination of @var{pos} and @var{whence}
points the outside of the string, an error is signaled.

The optional @var{start} and @var{end} trims the input string before 
creating the gap buffer.
@end defun

@defun gap-buffer? obj
@{@t{text.gap-buffer}@}
Returns @code{#t} iff @var{obj} is a gap buffer.
@end defun

@defun gap-buffer-copy gbuf
@{@t{text.gap-buffer}@}
Returns a fresh copy of a gap buffer @var{gbuf}, with the same content
and cursor position.
@end defun

@defun gap-buffer->string gbuf :optional start end
@defunx gap-buffer->generator gbuf :optional start end
@{@t{text.gap-buffer}@}
Retrieve the content of a gap buffer @var{gbuf} as a string or
a generator of characters, respectively.  The optional @var{start} and
@var{end} arguments are nonnegative exact integers of character index
in the content of the buffer, and limits the output within the specified
range.

If you modify the content of gap buffer before the returned generator
is exhausted, consistent behavior isn't guaranteed.
@end defun

@defun gap-buffer-pos gbuf
@{@t{text.gap-buffer}@}
Returns the current cursor position of @var{gbuf}, in a nonnegative
exact integer.
@end defun

@defun gap-buffer-capacity gbuf
@{@t{text.gap-buffer}@}
Returns the currently allocated storage size of @var{gbuf}.
If you insert more characters into @var{gbuf}, the storage is automatically
expanded.
@end defun

@defun gap-buffer-content-length gbuf
@{@t{text.gap-buffer}@}
Returns the length of current content of @var{gbuf},
in the number of characters.
@end defun

@defun gap-buffer-gap-at? gbuf whence
@{@t{text.gap-buffer}@}
The @var{whence} argument must be either a symbol @code{beginning}
or a symbol @code{end}.  Returns @code{#t} iff the current cursor position
of @var{gbuf} is at the beginning or at the end, respectively.
@end defun

@defun gap-buffer-ref gbuf index :optional fallback
@{@t{text.gap-buffer}@}
Returns @var{index}-th character of @var{gbuf}.  If @var{index} is
out of range, @var{fallback} is returned if given, or an error
is raised.
@end defun

@defun gap-buffer-set! gbuf index char
@{@t{text.gap-buffer}@}
Replaces @var{index}-th character of @var{gbuf} with @var{char}.
If @var{index} is out of range, an error is signaled.
@end defun

@defun gap-buffer-move! gbuf pos :optional whence
@{@t{text.gap-buffer}@}
Moves the cursor position of @var{gbuf} to a position @var{pos}, which
must be an exact integer.  The position @var{pos} is relative to
@var{whence}, which must be either one of the symbols @code{beginning},
@var{current} or @code{end}.
@end defun

@defun gap-buffer-insert! gbuf content
@{@t{text.gap-buffer}@}
Inserts @var{content}, which must be a character or a string,
at the current cursor position of @var{gbuf}.
The current cursor position is moved to the end of the inserted content.
@end defun

@defun gap-buffer-delete! gbuf size
@{@t{text.gap-buffer}@}
Delets @var{size} characters from the current cursor position
of @var{gbuf}.  It is an error if @var{size} overruns.
@end defun

@defun gap-buffer-clear! gbuf
@{@t{text.gap-buffer}@}
Makes @var{gbuf} empty.
@end defun

@defun gap-buffer-replace! gbuf size content
@{@t{text.gap-buffer}@}
This is a combination of @code{(gap-buffer-delete! gbuf size)} and
@code{(gap-buffer-insert! gbuf content)}. 
The @var{size} argument must be a nonnegative exact integer,
and the @var{content} argument must be either a string or a character.
@end defun

@defun gap-buffer-edit! gbuf edit-command
@{@t{text.gap-buffer}@}
This is a convenience procedure to ``replay'' editing of the gap buffer
@var{gbuf}.  The @var{edit-command} argument must be either one of the
following:

@table @code
@item (i @var{pos} @var{string})
Insert @var{string} at a position @var{pos}.
@item (d @var{pos} @var{length})
Delete @var{length} characters from a position @var{pos}.
@item (c @var{pos} @var{length} @var{string})
Change: Delets @var{length} characters from a position @var{pos},
then insert @var{string}.
@end table

Here, @var{pos} must be a nonnegative exact integer specifying the
position in the gap buffer.

One of the appliations of this procedure is to handle undo/redo list.
@end defun


@c ----------------------------------------------------------------------
@node Localized messages, Simple HTML document construction, Gap buffer, Library modules - Utilities
@section @code{text.gettext} - Localized messages
@c NODE 地域化メッセージ, @code{text.gettext} - 地域化メッセージ

@deftp {Module} text.gettext
@mdindex text.gettext
This module provides utilities to deal with localized messages.
The API is compatible to GNU's gettext, and the messages
are read from @file{*.po} and @file{*.mo} files,
so that you can use the GNU gettext
toolchain to prepare localized messages.
However, the code is written from scratch by Alex Shinn and
doesn't depend on GNU's gettext library.

This implementation extends GNU's gettext API in the following ways:
@itemize @bullet
@item
It can read from multiple message files in cascaded way,
allowing applications to share a part of message files.
@item
It supports multiple locale/domain simultaneously.
@end itemize

SRFI-29 (@pxref{Localization}) provides another means of message
localization.  A portable program may wish to use srfi-29, but
generally @code{text.gettext} is recommended in Gauche scripts
because of its flexibility and compatibility to existing message files.
@end deftp

@subheading Gettext-compatible API

@defun textdomain domain-name :optional locale dirs cdir cached? lookup-cached?
@{@t{text.gettext}@}
Sets up the default domain and other parameters for
the application.  The setting affects to the following @code{gettext}
call.

@var{Domain} is a string or list of strings specifying the domain
(name of @file{.mo} or @file{.po} files) as in C gettext.
You can pass @code{#f} as @var{domain-name} just to get the default
domain accessor procedure.
You can alo pass multiple domains to @var{domain-name}.
@example
(textdomain '("myapp" "gimp"))  ; search 1st myapp, then gimp
(gettext "/File/Close")         ; "Close" from gimp unless overridden
@end example

@var{Locale} is a string or list of strings in the standard Unix format of
@code{LANG[_REGION][.ENCODING]}.  You can also pass a list of locales
to specify fallbacks.

@example
(textdomain "myapp" '("ru" "uk"))  ; search 1st Russian then Ukranian,
(gettext "Hello, World!")          ; which are somewhat similar
@end example

@var{Dirs} is the search path of directories which should hold the
@file{LOCALE/CDIR/} directories which contain the actual message catalogs.
This is always appended with the system default, e.g.
@file{"/usr/share/locale"}, and may also inherit from the
@code{GETTEXT_PATH} colon-delimited environment variable.

@var{Cdir} is the category directory, defaulting to either the
@code{LC_CATEGORY}
environment variable or the appropriate system default
(e.g. @code{LC_MESSAGES}).  You generally won't need this.

@var{Cached?}
means to cache individual messages, and defaults to @code{#t}.

@var{Lookup-cached?}
means to cache the lookup dispatch generated by these
parameters, and defaults to @code{#t}.

@code{Textdomain} just passes these parameters to the internal
@code{make-gettext},
and binds the result to the global dispatch used by @code{gettext}.
You may build these closures manually for convenience in using multiple
separate domains or locales at once (useful for server environments).
See the description of @code{make-gettext} below.

@code{Textdomain} returns an @emph{accessor procedure} which
packages information of the domain.  See @code{make-gettext} below
for the details.
@end defun

@defun gettext msg-id
@{@t{text.gettext}@}
Returns a translated message of @var{msg-id}.  If there's no
translated message, @var{msg-id} itself is returned.
@end defun

@defun ngettext msg-id :optional msg-id2 num
@{@t{text.gettext}@}
Similar to @var{gettext}, but it can be used to handle
plural forms.
Pass a singular form to @var{msg-id}, and plural form to
@code{msg-id2}.  The @var{num} argument is used to determine
the plural form.  If no message catalog is found, @var{msg-id}
is returned when @var{num} is 1, and @var{msg-id2} otherwise.
@end defun

@defun bindtextdomain domain dirs
@{@t{text.gettext}@}
Sets the search path of domain @var{domain} to @var{dirs}, which
may be just a single directory name or a list of directory names.
@end defun

@defun dgettext domain msg-id
@defunx dcgettext domain msg-id locale
@{@t{text.gettext}@}
Returns a translated message of @var{msg-id} in @var{domain}.
@code{Dcgettext} takes @var{locale} as well.
@end defun

@subheading Low-level flexible API

The following procedure is more flexible interface, on top of which
the gettext-compatible APIs are written.

@defun make-gettext :optional domain locale dirs gettext-cached? lookup-cached?
@{@t{text.gettext}@}
Creates and returns an @emph{accessor procedure}, which encapsulates
methods to retrieve localized messages.

The meaning of arguments are the same as @code{textdomain} above.
Indeed, @code{textdomain} just calls @code{make-gettext}, and later
it binds the result to the global parameter.   If you wish to have
multiple independent domains within a single program, you can
call @code{make-gettext} directly and manage the created
accessor procedure by yourself.

@example
(define my-gettext (make-gettext "myapp"))
(define _ (my-gettext 'getter))
(_ "Hello, World!")
@end example
@end defun

@c ----------------------------------------------------------------------
@node Simple HTML document construction, Display with pager, Localized messages, Library modules - Utilities
@section @code{text.html-lite} - Simple HTML document construction
@c NODE シンプルなHTMLドキュメントの構築, @code{text.html-lite} - シンプルなHTMLドキュメントの構築

@deftp {Module} text.html-lite
@mdindex text.html-lite
Provides procedures to construct an HTML document easily.
For example, you can construct an HTML table by the following code:
@example
(html:table
  (html:tr (html:th "Item No") (html:th "Quantity"))
  (html:tr (html:td 1) (html:td 120))
  (html:tr (html:td 2) (html:td 30))
  (html:tr (html:td 3) (html:td 215)))
@end example
See the description of @code{html:@var{element}} below for details.

This module does little check for the constructed html documents,
such as whether the attributes are valid, and whether the content
of the element matches DTD.  It does not provide a feature to parse
the html document neither.  Hence the name `lite'.
@end deftp

@defun html-escape
@defunx html-escape-string string
@{@t{text.html-lite}@}
Escapes the ``unsafe'' characters in HTML.  @code{html-escape}
reads input string from the current input port and writes the result
to the current output port.   @code{html-escape-string} takes the
input from @var{string} and returns the result in a string.
@end defun

@defun html-doctype :key type
@{@t{text.html-lite}@}
Returns a doctype declaration for an HTML document.
@var{type} can be either one of the followings (default is
@code{:html-4.01-strict}).
@table @code
@item :html-4.01-strict, :html-4.01, :strict
HTML 4.01 Strict DTD
@item :html-4.01-transitional, :transitional
HTML 4.01 Transitional DTD
@item :html-4.01-frameset, :frameset
HTML 4.01 Frameset DTD
@item :xhtml-1.0-strict, :xhtml-1.0
XHTML 1.0 Strict DTD
@item :xhtml-1.0-transitional
XHTML 1.0 Transitional DTD
@item :xhtml-1.0-frameset
XHTML 1.0 Frameset DTD
@item :xhtml-1.1
XHTML 1.1 DTD
@end table
@end defun

@deftp {Function} html:@var{element} @var{args} @dots{}
@findex html:a
@findex html:abbr
@findex html:acronym
@findex html:address
@findex html:area
@findex html:b
@findex html:base
@findex html:bdo
@findex html:big
@findex html:blockquote
@findex html:body
@findex html:br
@findex html:button
@findex html:caption
@findex html:cite
@findex html:code
@findex html:col
@findex html:colgroup
@findex html:dd
@findex html:del
@findex html:dfn
@findex html:div
@findex html:dl
@findex html:dt
@findex html:em
@findex html:fieldset
@findex html:form
@findex html:frame
@findex html:frameset
@findex html:h1
@findex html:h2
@findex html:h3
@findex html:h4
@findex html:h5
@findex html:h6
@findex html:head
@findex html:hr
@findex html:html
@findex html:i
@findex html:iframe
@findex html:img
@findex html:input
@findex html:ins
@findex html:kbd
@findex html:label
@findex html:legend
@findex html:li
@findex html:link
@findex html:map
@findex html:meta
@findex html:noframes
@findex html:noscript
@findex html:object
@findex html:ol
@findex html:optgroup
@findex html:option
@findex html:p
@findex html:param
@findex html:pre
@findex html:q
@findex html:samp
@findex html:script
@findex html:select
@findex html:small
@findex html:span
@findex html:strong
@findex html:style
@findex html:sub
@findex html:sup
@findex html:table
@findex html:tbody
@findex html:td
@findex html:textarea
@findex html:tfoot
@findex html:th
@findex html:thead
@findex html:title
@findex html:tr
@findex html:tt
@findex html:ul
@findex html:var
@{@t{text.html-lite}@}
Construct an HTML element @var{element}.  Right now,
the following elements are provided.
(The elements defined in HTML 4.01 DTD,
@uref{http://www.w3.org/TR/html4/sgml/dtd.html}).
@example
a        abbr       acronym    address     area      b
base     bdo        big        blockquote  body      br
button   caption    cite       code        col       colgroup
dd       del        dfn        div         dl        dt
em       fieldset   form       frame       frameset
h1       h2         h3         h4          h5        h6
head     hr         html       i           iframe    img
input    ins        kbd        label       legend    li
link     map        meta       noframes    noscript  object
ol       optgroup   option     p           param     pre
q        samp       script     select      small     span
strong   style      sub        sup         table     tbody
td       textarea   tfoot      th          thead     title
tr       tt         ul         var
@end example

The result of these functions is a tree of text segments,
which can be written out to a port by @code{write-tree} or
can be converted to a string by @code{tree->string}
(@pxref{Lazy text construction}).

You can specify attributes of the element by using a keyword-value
notation before the actual content.
@example
(tree->string (html:a :href "http://foo/bar" "foobar"))
  @result{}
  "<a href=\"http://foo/bar\">foobar</a\n>"

(tree->string
  (html:table :width "100%" :cellpadding 0 "content here"))
  @result{}
  "<table width=\"100%\" cellpadding=\"0\">content here</table\n>"
@end example

The boolean value given to the attribute has a special meaning.
If @code{#t} is given, the attribute is rendered without a value.
If @code{#f} is given, the attribute is not rendered.
@example
(tree->string (html:table :border #t))
  @result{} "<table border></table\n>"

(tree->string (html:table :border #f))
  @result{} "<table></table\n>"
@end example

Special characters in attribute values are escaped by the function,
but the ones in the content are not.  It is caller's responsibility
to escape them.

The functions signal an error if a content is given to the
HTML element that doesn't take a content.   They do not
check if the given attribute is valid, neither
if the given content is valid for the element.

@emph{Note:}
You might have noticed that these procedures insert a newline
before @code{>} of the closing tag.  That is, the rendered
HTML would look like this:

@example
<table><tr><td>foo</td
><td>bar</td
></tr
></table
>
@end example

We intentionally avoid inserting newlines after the closing
tag, since @emph{it depends on the surrounding context whether
the newline is significant or not}.  We may be able to insert newlines
after the elements directly below a @code{<head>} element,
for example, but we cannot in a @code{<p>} element, without
affecting the content.

There are three possible solutions: (1) not to insert newlines
at all, (2) to insert newlines within tags, and (3) to insert
newlines only at the safe position.  The first one creates one
long line of HTML, and although it is still valid HTML, it is
inconvenient to handle it with line-oriented tools.
The third one requires the
rendering routine to be aware of DTD.  So we took the second
approach.
@end deftp

@c ----------------------------------------------------------------------
@node Display with pager, Parsing input stream, Simple HTML document construction, Library modules - Utilities
@section @code{text.pager} - Display with pager
@c NODE ページャーを用いた出力, @code{text.pager} - ページャーを用いた出力

@deftp {Module} text.pager
@mdindex text.pager
A convenience module to present long text nicely to the user.
@end deftp

@deffn {Parameter} pager-program
@{@t{text.pager}@}
A parameter containing a list of pager program and its arguments
(e.g. @code{("/usr/bin/less" "-M")}).

The program must take input from the standard input.

The default value is taken from the environment variable @code{PAGER}
if set, or either @code{less} or @code{more} if those programs are
available on the system.
@end deffn

@defun display/pager string
@{@t{text.pager}@}
Display @var{string} by a pager subprocess specified by the parameter
@code{pager-program}.  The procedure returns when the subprocess exits.

If the terminal is not suitable for control
(e.g. @code{TERM} is @code{dumb} or @code{emacs}), @var{string} is
simply @code{display}ed without a pager.

If you're running MinGW version of @code{gosh} on mintty,
calling subprocess pager doesn't work well, so the procedure
emulate the pager behavior (@code{pager-program} is ignored).
@end defun

@defun with-output-to-pager thunk
@{@t{text.pager}@}
Call @var{thunk} with its current output port to a string buffer,
then show the buffered output using @code{display/pager}.

Note that the output begins after @var{thunk} returns.
@end defun


@c ----------------------------------------------------------------------
@node Parsing input stream, Showing progress on text terminals, Display with pager, Library modules - Utilities
@section @code{text.parse} - Parsing input stream
@c NODE 入力ストリームのパージング, @code{text.parse} - 入力ストリームのパージング

@deftp {Module} text.parse
@mdindex text.parse
A collection of utilities that does simple parsing from
the input port.   The API is inspired, and compatible with
Oleg Kiselyov's input parsing library (@uref{http://okmij.org/ftp/Scheme/parsing.html}).
His library is used in lots of other libraries, notably,
a full-Scheme XML parser/generator SSAX (@uref{http://okmij.org/ftp/Scheme/xml.html}).

You can use this module in place of his
@code{input-parse.scm} and @code{look-for-str.scm}.

I reimplemented the functions to be efficient on Gauche.
Especially, usage of @code{string-set!} is totally avoided.
I extended the interface a bit so that they can deal with character sets
and predicates, as well as a list of characters.

These functions work sequentially on the given input port,
that is, they read from the port as much as they need, without
buffering extra characters.
@end deftp

@defun find-string-from-port? str in-port :optional max-no-chars
@{@t{text.parse}@}
Looks for a string @var{str} from the input port @var{in-port}.
The optional argument @var{max-no-chars} limits the maximum number of
characters to be read from the port; if omitted, the search span is
until EOF.

If @var{str} is found, this function returns the number of characters
it has read.   The next read from @var{in-port} returns the next char
of @var{str}.  If @var{str} is not found, it returns @code{#f}.

Note: Although this procedure has `@code{?}' in its name,
it may return non-boolean value, contrary to the Scheme convention.
@end defun

@defun peek-next-char :optional port
@{@t{text.parse}@}
Discards the current character and peeks the next character from @var{port}.
Useful to look ahead one character.
If @var{port} is omitted, the current input port is used.
@end defun

In the following functions, @var{char-list} refers to one of the
followings:
@itemize @bullet
@item
A character set.
@item
A list of characters, character sets and/or symbol @code{*eof*}.
@end itemize
That denotes a set of characters.  If a symbol @code{*eof*} is
included, the EOF condition is also included.  Without @code{*eof*},
the EOF condition is regarded as an error.

@defun assert-curr-char char-list string :optional port
@{@t{text.parse}@}
Reads a character from @var{port}.  If it is included in @var{char-list},
returns the character.  Otherwise, signals an error with a message
containing @var{string}.
If @var{port} is omitted, the current input port is used.
@end defun

@defun skip-until char-list/number :optional port
@{@t{text.parse}@}
@var{char-list/number} is either a char-list or a number.
If it is a number; it reads that many characters and returns @code{#f}.
If the input is not long enough, an error is signaled.
If @var{char-list/number} is a char-list, it reads from @var{port}
until it sees a character that belongs to the char-list.
Then the character is returned.
If @var{port} is omitted, the current input port is used.
@end defun

@defun skip-while char-list :optional port
@{@t{text.parse}@}
Reads from @var{port} until it sees a character that does not
belong to @var{char-list}.  The character remains in the stream.
If it reaches EOF, an EOF is returned.
If @var{port} is omitted, the current input port is used.

This example skips whitespaces from input.  Next read from
port returns the first non-whitespace character.
@example
(skip-while #[\s] port)
@end example
@end defun

@defun next-token prefix-char-list break-char-list :optional comment port
@{@t{text.parse}@}
Skips any number of characters in @var{prefix-char-list},
then collects the characters until it sees @var{break-char-list}.
The collected characters are returned as a string.
The break character remains in the @var{port}.

If the function encounters EOF and @code{*eof*} is not included in
@var{break-char-list}, an error is signaled with @var{comment} is
included in the message.
@end defun

@defun next-token-of char-list/pred :optional port
@{@t{text.parse}@}
Reads and collects the characters as far as
it belongs to @var{char-list/pred}, then returns them as a string.
The first character that doesn't belong to @var{char-list/pred} remains
on the port.

@var{char-list/pred} may be a char-list or a predicate that takes
a character.   If it is a predicate, each character is passed to it,
and the character is regarded to ``belong to'' @var{char-list/pred}
when it returns a true value.
@end defun

@defun read-string n :optional port
@{@t{text.parse}@}
This is like built-in @code{read-string} (@pxref{Reading data}),
except that this returns @code{""} when the input already reached EOF.

Provided for the compatibility for the code that depends Oleg's library.
@end defun

@c ----------------------------------------------------------------------
@node Showing progress on text terminals, SQL parsing and construction, Parsing input stream, Library modules - Utilities
@section @code{text.progress} - Showing progress on text terminals
@c NODE テキスト端末上で進捗を表示する, @code{text.progress} - テキスト端末上で進捗を表示する

@deftp {Module} text.progress
@mdindex text.progress
This module provides a utility to report a progress of processing
on a text terminal, using characters to display bar chart.

The generic format of a progress bar consists of a single line
of text, which is splitted into several parts; a header, which
displays the title; followed by a bar, a numeric part, and a time part,
as shown in the following example (only the line beginning with ``foo''
is actually displayed).
@example
<-header-> <-------bar---------> <-num-><-time->      <---info---->
foo       |#############        |123/211   01:21 ETA  compiling...
          ^
          separator
@end example

Various things like the character used in the bar chart or
the format of the numeric progress can be configured.

Internally a progress bar maintains two numbers, the maximum (goal)
value and the current value.  The bar shows the proportion of
the current value relative to the maximum value.  The numeric progress
shows the current value over the maximum value by default, but you
can configure it to show only the current value or percentage, for example.

A progress bar also has two states, ``in progress'' and ``finished''.
When it is in progress, every time the text is displayed it is
followed by @code{#\return}, so that the next display overwrites
the bar, and the time part shows ETA (estimated time of arrival).
Once it becomes finished, the last line of text is displayed
with @code{#\newline}, and the time part shows the actual time
it took to finish.
@end deftp

This module provides only one procedure, @code{make-text-progress-bar},
which packages the progress bar feature in a closure and returns it.

@defun make-text-progress-bar :key header header-width bar-char bar-width num-width num-format time-width info info-width separator-char max-value port
@{@t{text.progress}@}
Returns a procedure that packages operations on the progress bar.
The procedure can be called with a symbol indicating an operation,
and an optional numeric argument.

@table @code
@item @var{proc} 'show
Redisplays the progress bar.  All other operations implies redisplay,
so you don't need to use this unless you have a specific reason to
redisplay the current state.

@item @var{proc} 'set @var{value}
Sets the current value to @var{value}, then redisplays the progress bar.
If @var{value} exceeds the max value, it is clipped by the max value.

@item @var{proc} 'inc @var{value}
Increments the current value by @var{value}, then redisplays the progress bar.
If the current value exceeds the max value, it is clipped by the max value.

@item @var{proc} 'finish
Puts the progress bar to the ``finished'' state, then redisplays it.
The time part shows the total elapsed time, and the line is terminated
by @code{#\newline} so that it won't be clobbered.   Once a progress
bar becomes ``finished'', there's no way to put it back ``in progress''.

@item @var{proc} 'set-info @var{text}
Changes the text displayed in the ``info'' part.  To use the info part,
you have to give a positive value to @var{info-width} keyword argument
of @code{make-text-progress-bar}.


@item @var{proc} 'set-header @var{text}
Changes the text displayed in the ``header' area.
@end table

The keyword arguments are used to customize the display:
@table @var
@item header
The text to be displayed in the header part.
This can be changed later, by sending @code{set-header} message
to the created progress bar.

@item header-width
The width of the header part, in number of characters.
The header text is displayed left-aligned in the part.
If the header text is longer than the width, the excess characters
are omitted.  The default is 14.

@item bar-char
A character used to draw a bar chart.  The default is @code{#\#}.

@item bar-width
The width of the bar chart part, in number of characters.
The default is 40.

@item num-width
The width of the numeric part, in number of characters.
The default is 9.  Setting this to 0 hides the numeric part.

@item num-format
A procedure to format the numeric part.  Two arguments are
passed; the current value and the maximum value.  It must return
a string.  The default is the following procedure.
@example
(lambda (cur max)
  (format "~d/~d" cur max))
@end example

@item time-width
The width of the time part, in number of characters.
The default is 7.  Settings this to 0 hides the time part.

@item info
The text to be displayed in the info part.  This text can be
changed later by sending @code{set-info} message to the created
progress bar.  Note that you have to give a positive number
to @var{info-width} keyword argument to enable the info part.

@item info-width
The width of the info part.  The default value is zero,
which means the info part is not displayed.

@item separator-char
A character put around the bar part.  Default is @code{#\|}.
You can pass @code{#f} not to display the separators.

@item max-value
The maximum value of the progress bar.  Must be a positive real number.
Default is 100.

@item port
An output port to which the progress bar is displayed.  The default value
is the current output port when @code{make-text-progress-bar} is called.
@end table
@end defun

Here's a simple example, using customized numeric part:

@example
(use text.progress)

(define (main args)
  (define (num-format cur max)
    (format "~d/~d(~3d%)" cur max
            (round->exact (/. (* cur 100) max))))

  (let ((p (make-text-progress-bar :header "Example"
                                   :header-width 10
                                   :bar-char #\o
                                   :num-format num-format
                                   :num-width 13
                                   :max-value 256)))
    (do ((i 0 (+ i 1)))
        ((= i 256) (p 'finish))
      (p 'inc 1)
      (sys-select #f #f #f 50000))))
@end example

@c ----------------------------------------------------------------------
@node SQL parsing and construction, Simple template expander, Showing progress on text terminals, Library modules - Utilities
@section @code{text.sql} - SQL parsing and construction
@c NODE SQLのパーズと構築, @code{text.sql} - SQLのパーズと構築

@deftp {Module} text.sql
@mdindex text.sql
This module provides a utility to parse and construct SQL statement.

It is currently under development, and we only have a tokenization routine.
The plan is to define S-expression syntax of SQL and provides a routine
to translate one form to the other.

Note: If you're looking for a routine to escape strings to be
safe in SQL, see @code{dbi-escape-sql} in @ref{DBI user API}.
@end deftp

@defun sql-tokenize sql-string
@{@t{text.sql}@}
Tokenize a SQL statement @var{sql-string}.  The return value is
a list of tokens, where each token is
represented by one of the following forms.

@example
<symbol>              Special delimiter.  One of the followings:
                      + - * / < = > <> <= >= ||
<character>           Special delimiter.  One of the followings:
                      #\, #\. #\( #\) #\;
<string>              Regular identifier
(delimited <string>)  Delimited identifier
(parameter <num>)     Positional parameter (?)
(parameter <string>)  Named parameter (:foo)
(string    <string>)  Character string literal
(number    <string>)  Numeric literal
(bitstring <string>)  Binary string.  <string> is like "01101"
(hexstring <string>)  Binary string.  <string> is like "3AD20"
@end example

If it encounters an untokenizable string, it raises an
@code{<sql-parse-error>} condition.
@end defun

@deftp {Condition Type} <sql-parse-error>
@{@t{text.sql}@}
A condition to indicate an SQL parse error.  Inherits @code{<error>}.
@defivar <sql-parse-error> sql-string
Holds the source SQL string.
@end defivar
@end deftp

@c ----------------------------------------------------------------------
@node Simple template expander, Transliterate characters, SQL parsing and construction, Library modules - Utilities
@section @code{text.template} - Simple template expander
@c NODE 簡単なテンプレート拡張, @code{text.template} - 簡単なテンプレート拡張

@deftp {Module} text.template
@mdindex text.template
This module lifts Gauche's built-in string interpolation feature
to be more general template engine.

Gauche's string interpolation syntax is expanded at read time and then
handled by macro expanders, and 
becomes a simple Scheme code fragment.  
For example, if you have this:
@example
(let ([x 10])
  #"The square of x is ~(* x x).")
@end example

It is eventually converted to this after macro expansion:
@example
(let ([x 10])
  (string-append '"The square of x is " (x->string (* x.0 x.0)) '"."))
@end example

It is a kind of template expansion, but you have to have the template string
as a literal, so it's restricted.  With this module, you can feed template
string and the bindings of the value at the runtime:

@example
(define *template* "The square of x is ~(* x x).")

(expand-template-string *template*
  (make-template-environment :bindings '(x 10)))
  @result{} "The square of x is 100."
@end example

The syntax of template strings is the same as string interpolation
(@pxref{String interpolation}); that is, tokens following @code{~}
is read as a Scheme expression.  In case if the token is a symbol
and you need to delimit it from subsequent characters, you can use
symbol escape by @code{|}.

You also need to provide a @emph{template environment}, where the
expressions in the template is evaluated.  Note that, 
unlike string interpolation,
those expressions can't refer to the local bindings.
@end deftp

@defun expand-template-string template env
Expands a template string @var{template} with a template environment
@var{env}, and returns the result string.
@end defun

@defun expand-template-file filename env :optional paths
Reads a template string from a file named by @var{filename}, expands
it with a template environment @var{env}, and returns the result string.

If @var{filename} is not an absolute path, it is looked in the directories
listed in @var{paths}.
@end defun

@defun make-template-environment :key extends imports bindings
Creates and returns a template environment.   A template environment
is like a module (@pxref{Modules}): It maps symbols to values, and
it can import bindings from other modules, or extend other modules.

The keyword arguments @var{extends} and @var{imports} must be a list
of symbols; they specify names of modules to inherit from or to import from.

The keyword arguments @var{bindings} must either be a dictionary
(anything that inherits @code{<dictionary>}), or a key-value list.
The mappings represented by it are incorporated to the environment.
@end defun

@c ----------------------------------------------------------------------
@node Transliterate characters, Lazy text construction, Simple template expander, Library modules - Utilities
@section @code{text.tr} - Transliterate characters
@c NODE 文字変換, @code{text.tr} - 文字変換

@deftp {Module} text.tr
@mdindex text.tr
This module implements a transliterate function,
that substitutes characters of the input string.
This functionality is realized in Unix @code{tr(1)} command,
and incorporated in various programs such as @code{sed(1)}
and @code{perl}.

Gauche's @code{tr} is aware of multibyte characters.
@end deftp

@defun tr from-list to-list :key :complement :delete :squeeze :table-size :input :output
@{@t{text.tr}@}
Reads from @var{input} and writes to @var{output},
with transliterating characters in @var{from-list} to the
corresponding ones in @var{to-list}.  Characters that doesn't
appear in @var{from-list} are passed through.

The default values of @var{input} and @var{output} are
current input port and current output port, respectively.

Both @var{from-list} and @var{to-list} must be strings.
They may contain the following special syntax.
Other characters that doesn't fits in the syntax are taken as they are.

@table @code
@item @b{x-y}
Expanded to the increasing sequence of characters from @code{x} to @code{y},
inclusive.  The order is determined by the internal character
encoding system; generally it is safer to limit use of this within
the range of the same character class.   The character @code{x}
must be before @code{y}.

@item @b{x*n}
Repeat @code{x} for @code{n} times.  @code{n} is a decimal number notation.
Meaningful only in
@var{to-list}; it is an error to use this form in @var{from-list}.
If @code{n} is omitted or zero, @code{x} is repeated until @var{to-list}
matches the length of @var{from-list} (any character after it is ignored).

@item @b{@code{\}x}
Represents @code{x} itself.  Use this escape to avoid a special
character to be interpreted as itself.   Note that if you place
a backslash in a string, you must write @code{\\}, for the Scheme
reader also interprets backslash as a special character.

There's no special sequence to represent non-graphical characters,
for you can put such characters by the string syntax.
@end table

Here's some basic examples.
@example
;; @r{swaps case of input}
(tr "A-Za-z" "a-zA-Z")

;; @r{replaces 7-bit non-graphical characters to `?'}
(tr "\x00-\x19\x7f" "?*")
@end example

If @var{to-list} is shorter than @var{from-list}, the behavior
depends on the keyword argument @var{delete}.  If a true value is
given,  characters that appear in @var{from-list} but not
in @var{to-list} are deleted.   Otherwise,
the extra characters in @var{from-list} are just passed through.

When a true value is specified to @var{complement},
the character set in @var{from-list} is complemented.
Note that it implies @emph{huge} set of characters,
so it is not very useful unless either output character
set is a single character (using `*') or used with
@code{delete} keyword.

When a true value is specified to @var{squeeze},
the sequence of the same replaced characters is squeezed to one.
If @var{to-list} is empty, the sequence of the same characters
in @var{from-list} is squeezed.

Internally, @code{tr} builds a table to map the characters for
efficiency.  Since Gauche can deal with potentially huge set
of characters, it limits the use of the table for only smaller
characters (<256 by default).  If you want to transliterate
multibyte characters on the large text, however, you might want
to use larger table, trading off the memory usage.  You can specify
the internal table size by @var{table-size} keyword argument.
For example, if you transliterate lots of EUC-JP hiragana text
to katakana, you may want to set table size greater than 42483
(the character code of the last katakana).

Note that the pre-calculation to build the transliterate table
needs some overhead.  If you want to call @code{tr} many times
inside loop, consider to use @code{build-transliterator} described below.
@end defun

@defun string-tr string from-list to-list :key :complement :delete :squeeze :table-size
@{@t{text.tr}@}
Works like @code{tr}, except that input is taken from a string @var{string}.
@end defun

@defun build-transliterator from-list to-list :key :complement :delete :squeeze :table-size :input :output
@{@t{text.tr}@}
Returns a procedure that does the actual transliteration.  This effectively
``pre-compiles'' the internal data structure.   If you want to run
@code{tr} with the same sets repeatedly, you may build the procedure
once and apply it repeatedly, saving the overhead of initialization.

A note for an edge case:
When @var{input} and/or @var{output} keyword arguments are omitted,
the created transliterator is set up to use current-input-port and/or
current-output-port at the time transliterator is called.

@example
(with-input-from-file "huge-file.txt"
  (lambda ()
    (let loop ((line (read-line)))
      (unless (eof-object? line) (tr "A-Za-z" "a-zA-Z")))))

;; @r{runs more efficiently...}

(with-input-from-file "huge-file.txt"
  (lambda ()
    (let ((ptr (build-transliterator "A-Za-z" "a-zA-Z")))
      (let loop ((line (read-line)))
        (unless (eof-object? line) (ptr))))))
@end example

@end defun

@c ----------------------------------------------------------------------
@node Lazy text construction, Combination library, Transliterate characters, Library modules - Utilities
@section @code{text.tree} - Lazy text construction
@c NODE 怠惰なテキスト構築, @code{text.tree} - 怠惰なテキスト構築

@deftp {Module} text.tree
@mdindex text.tree
Defines simple but commonly used functions for a text construction.

When you generate a text by a program,
It is a very common operation to concatenate text segments.
However, using string-append repeatedly causes unnecessary
copying of intermediate strings, and sometimes such intermediate
strings are discarded due to the error situation (for example,
think about constructing an HTML document in the CGI script).

The efficient technique is to delay concatenation of those
text segments until it is needed.  In Scheme it is done very
easily by just consing the text segments together, thus forming
a tree of text, and then traverse the tree to construct a text.
You can even directly writes out the text during traversal,
avoiding intermediate string buffer.
(Hans Boehm's ``cord'' library, which comes with his garbage
collector library, uses this technique and proves it is very
efficient for editor-type application).

Although the traversal of the tree can be written in a
few lines of Scheme, I provide this module in the spirits
of OnceAndOnlyOnce.   Also it's easier if we have a common interface.
@end deftp

@deffn {Generic Function} write-tree tree :optional out
@{@t{text.tree}@}
Writes out an @var{tree} as a tree of text, to the output port @var{out}.
If @var{out} is omitted, the current output port is used.

Two methods are defined for this generic function, as shown below.
If you have more complex behavior, you can define more methods
to customize the behavior.
@end deffn

@deffn {Method} write-tree ((tree <list>) out)
@deffnx {Method} write-tree ((tree <top>) out)
@{@t{text.tree}@}
Default methods.  For a list, @code{write-tree} is recursively
called for each element.  Any objects other than list is written out
using @code{display}.
@end deffn

@defun tree->string tree
@{@t{text.tree}@}
Just calls the @code{write-tree} method for @var{tree} using
an output string port, and returns the result string.
@end defun


@c ----------------------------------------------------------------------
@node Combination library, Message digester framework, Lazy text construction, Library modules - Utilities
@section @code{util.combinations} - Combination library
@c NODE 組み合わせ, @code{util.combinations} - 組み合わせ

@deftp {Module} util.combinations
@mdindex util.combinations
This module implements several useful procedures of
combinations, permutations and related operations.

Most procedures in the module have two variants: a procedure without
star (e.g. @code{permutations}) treats all elements in the given
set distinct, while a procedure with star (e.g. @code{permutations*})
considers duplication.  The procedures with star take optional @var{eq}
argument that is used to test equality, which defaults to @code{eqv?}.
@end deftp

@defun permutations set
@defunx permutations* set :optional eq
@{@t{util.combinations}@}
Returns a list of all permutations of a list @var{set}.

@example
(permutations '(a b c))
  @result{} ((a b c) (a c b) (b a c) (b c a) (c a b) (c b a))

(permutations '(a a b))
  @result{} ((a a b) (a b a) (a a b) (a b a) (b a a) (b a a))

(permutations* '(a a b))
  @result{} ((a a b) (a b a) (b a a))
@end example

The number of possible permutations explodes if @var{set} has
more than several elements.  Use with care.  If you want to process
each permutation at a time, consider @code{permutations-for-each} below.
@end defun

@defun permutations-for-each proc set
@defunx permutations*-for-each proc set :optional eq
@{@t{util.combinations}@}
For each permutation of a list @var{set}, calls @var{proc}.
Returns an undefined value.
@end defun

@defun combinations set n
@defunx combinations* set n :optional eq
@{@t{util.combinations}@}
Returns a list of all possible combinations of @var{n} elements out
of a list @var{set}.

@example
(combinations '(a b c) 2)
  @result{} ((a b) (a c) (b c))

(combinations '(a a b) 2)
  @result{} ((a a) (a b) (a b))

(combinations* '(a a b) 2)
  @result{} ((a a) (a b))
@end example

Watch out the explosion of combinations when @var{set} is large.
@end defun

@defun combinations-for-each proc set n
@defunx combinations*-for-each proc set n :optional eq
@{@t{util.combinations}@}
Calls @var{proc} for each combination of @var{n} elements out of @var{set}.
Returns an undefined value.
@end defun

@defun power-set set
@defunx power-set* set :optional eq
@{@t{util.combinations}@}
Returns power set (all subsets) of a list @var{set}.

@example
(power-set '(a b c))
  @result{} (() (a) (b) (c) (a b) (a c) (b c) (a b c))

(power-set* '(a a b)
  @result{} (() (a) (b) (a a) (a b) (a a b))
@end example
@end defun

@defun power-set-for-each proc set
@defunx power-set*-for-each proc set :optional eq
@{@t{util.combinations}@}
Calls @var{proc} for each subset of @var{set}.
@end defun

@defun power-set-binary set
@{@t{util.combinations}@}
Returns power set of @var{set}, like @code{power-set}, but in different order.
@code{Power-set-binary} traverses subset space in depth-first order,
while @code{power-set} in breadth-first order.

@example
(power-set-binary '(a b c))
  @result{} (() (c) (b) (b c) (a) (a c) (a b) (a b c))
@end example
@end defun

@defun cartesian-product list-of-sets
@defunx cartesian-product-right list-of-sets
@{@t{util.combinations}@}
Returns a cartesian product of sets in @var{list-of-sets}.
@code{Cartesian-product} construct the result in left fixed order
(the rightmost element varies first), while
@code{cartesian-product-right} in right fixed order
(the leftmost element varies first).

@example
(cartesian-product '((a b c) (0 1)))
  @result{} ((a 0) (a 1) (b 0) (b 1) (c 0) (c 1))

(cartesian-product-right '((a b c) (0 1)))
  @result{} ((a 0) (b 0) (c 0) (a 1) (b 1) (c 1))
@end example
@end defun

@c ----------------------------------------------------------------------
@node Message digester framework, Calculate dominator tree, Combination library, Library modules - Utilities
@section @code{util.digest} - Message digester framework
@c NODE メッセージダイジェストフレームワーク, @code{util.digest} - メッセージダイジェストフレームワーク

@deftp {Module} util.digest
@mdindex util.digest
This module provides a base class and common interface for
message digest algorithms, such as MD5 (@pxref{MD5 message digest})
and SHA (@pxref{SHA message digest}).
@end deftp

@deftp {Class} <message-digest-algorithm-meta>
@clindex message-digest-algorithm-meta
@{@t{util.digest}@}
A metaclass of message digest algorithm implementation.

@defivar {<message-digest-algorithm-meta>} hmac-block-size
Specifies the block size (in bytes), which is specific to each algorithm.
(This is a slot for each @emph{class} object that implements the algorithm,
not for instance of such classes.  Only the author of such digest classes
needs to care.  See @file{ext/digest/sha.scm} in the source tree
for more details.)
@end defivar
@end deftp

@deftp {Class} <message-digest-algorithm>
@clindex message-digest-algorithm
@{@t{util.digest}@}
A base class of message digest algorithm implementation.
@end deftp

The concrete subclass of message digest algorithm has to
implement the following methods.

@deffn {Generic function} digest-update! algorithm data
@{@t{util.digest}@}
Takes the instance of massage-digest algorithm, and updates it
with the data @var{data}, which can be either a u8vector
or a (possibly incomplete) string.
@end deffn

@deffn {Generic function} digest-final! algorithm
@{@t{util.digest}@}
Finalizes the instance of message-digest algorithm, and
returns the digest result in an incomplete string.
@end deffn

@deffn {Generic function} digest class
@{@t{util.digest}@}
A wrapper of digest routines.  Given message-digest algorithm @var{class},
this function reads the input data from current input port until EOF,
and returns the digest result in an incomplete string.
@end deffn

@deffn {Generic function} digest-string class string
@{@t{util.digest}@}
A wrapper of digest routines.  Given message-digest algorithm @var{class},
this function reads the input data from @var{string},
and returns the digest result in an incomplete string.
@end deffn

@defun digest-hexify digest-result
@{@t{util.digest}@}
An utility procedure.  Given the result of digest, @var{digest-result},
which can be an u8vector or a (possibly incomplete) string,
converts it to a hexified string.
@end defun

@c ----------------------------------------------------------------------
@node Calculate dominator tree, Determine isomorphism, Message digester framework, Library modules - Utilities
@section @code{util.dominator} - Calculate dominator tree
@c NODE 支配木, @code{util.dominator} - 支配木

@deftp {Module} util.dominator
@mdindex util.dominator
Dominator tree is an auxiliary structure for control flow graphs.
It is frequently used in the flow analysis of compilers, but
also useful for handling general directed graphs.
@end deftp

@defun calculate-dominators start upstreams downstreams node-comparator
@{@t{util.dominator}@}
The four arguments represent a directed, possibly cyclic, graph.
Here, we use @code{Node} to denote an abstract type of a node 
of the graph.  It can be anything---the algorithm is oblivious on
the actual type of nodes.

@table @asis
@item @var{start} @code{:: Node}
The start node, or the enter node, of the graph.
@item @var{upstreams} @code{:: Node -> (Node @dots{})}
A procedure that takes a node, and returns its upstream
(immediate ancestor) nodes.
@item @var{downstreams} @code{:: Node -> (Node @dots{})}
A procedure that takes a node, and returns its downstream
(immediate descendant) nodes.
@item @var{node-comparator}
A comparator that is used to determine if two nodes are equal to each other.
It doesn't need to have comparison procedure (we don't need to see
which is smaller than the other), but it has to have hash function,
for we use hashtables internally.  (@xref{Basic comparators}, for the details
of comparators.)
@end table

The procedure returns a list of @code{(node1 node2)}, where
@code{node2} is the immediate dominator of @code{node1}.

If there are node in the given graph that are unreachable
from @var{start}, such nodes are ignored and not included
in the result.

(A bit of explanation: Suppose you want to go to node X from @var{start}.
There may be multiple routes, but if you have to pass node Y no matter
which route you take, then Y is a dominator of X.  There may be
many dominators of X.  Among them, there's
always one dominator such that all other X's dominators are also
its dominators---in other words, the closest dominator of X---which
is called the immediate dominator of X.)

Let's see an example.  You have this directed graph:

@example
          A (start)
          |
          v
          B <-------+
          |         |
    ------+-----    |
    |          |    |
    v          v    |
    C -------> D ---+
    |          |
    v          v
    E <------- F
@end example

Let's represent the graph by a list of @code{(x y z ...)} where @code{x}
can directly go to either @code{y z ...}.

@example
(define *graph* '((A B)
                  (B C D)
                  (C D E)
                  (D F B)
                  (F E)))
@end example

Then you can calculate the immediate dominator of each node as follows:

@example
(calculate-dominators 'A
  (^n (filter-map (^g (and (memq n (cdr g)) (car g))) *graph*))
  (^n (assoc-ref *graph* n '()))
  eq-comparator)
  @result{} ((E B) (F D) (D B) (C B) (B A))
@end example

That is, @code{E}'s immediate dominator is @code{B},
@code{F}'s is @code{D}, and so on.

The result itself can be viewed as a tree.  It is called a dominator tree.

@example
              F
              |
              v
        E     D     C
        |     |     |
        |     v     |
        +---> B <---+
              |
              v
              A
@end example
@end defun


@c ----------------------------------------------------------------------
@node Determine isomorphism, The longest common subsequence, Calculate dominator tree, Library modules - Utilities
@section @code{util.isomorph} - Determine isomorphism
@c NODE 同型判定, @code{util.isomorph} - 同型判定

@deftp {Module} util.isomorph
@mdindex util.isomorph
Provides a procedure that determines whether two structures are
isomorphic.
@end deftp

@defun isomorphic? obj1 obj2 :optional context
@{@t{util.isomorph}@}
Returns @code{#t} if @var{obj1} and @var{obj2} are isomorphic.

@var{context} is used if you want to call @code{isomorphic?}
recursively inside @code{object-isomorphic?} described below.

@example
(isomorphic? '(a b) '(a b)) @result{} #t

(define x (cons 0 0))
(define y (cons 0 0))
(isomorphic? (cons x x)
             (cons x y))
 @result{} #f
(isomorphic? (cons x x)
             (cons y y))
 @result{} #t
@end example
@end defun

@deffn {Generic Function} object-isomorphic? obj1 obj2 context
@{@t{util.isomorph}@}
With this method, you can customize how to determine isomorphism of
two objects.  Basically, you will call @code{isomorphic?} recursively
for each slots of object you want to traverse; the method should return
@code{#t} if all of the test succeeds, or return @code{#f} otherwise.
@var{context} is an opaque structure
that keeps the traversal context, and you should pass it to
@code{isomorphic?} as is.

The default method returns @code{#t} if @var{obj1} and @var{obj2} are
equal (in the sense of @code{equal?}).
@end deffn

@c ----------------------------------------------------------------------
@node The longest common subsequence, Levenshtein edit distance, Determine isomorphism, Library modules - Utilities
@section @code{util.lcs} - The longest common subsequence
@c NODE 最長共通サブシーケンス, @code{util.lcs} - 最長共通サブシーケンス

@deftp {Module} util.lcs
@mdindex util.lcs
This module implements the algorithm to find the longest common subsequence
of two given sequences.  The implemented algorithm is based on
Eugene Myers' O(ND) algorithm 
(Eugene Myers, An O(ND) Difference Algorithm and Its Variations,
@i{Algorithmica} Vol. 1 No. 2, pp. 251-266, 1986.).

One of the applications of this algorithm is to calculate
the difference of two text streams;
see @ref{Calculate difference of text streams}.
@end deftp

@defun lcs seq-a seq-b :optional eq-fn
@{@t{util.lcs}@}
Calculates and returns the longest common sequence of
two lists, @var{seq-a} and @var{seq-b}.
Optional @var{eq-fn} specifies
the comparison predicate; if omitted, @code{equal?} is used.

@example
(lcs '(x a b y) '(p a q b))
 @result{} (a b)
@end example
@end defun

@defun lcs-with-positions seq-a seq-b :optional eq-fn
@{@t{util.lcs}@}
This is the detailed version of @code{lcs}.
The arguments are the same.

Returns a list of the following structure:

@example
(@var{length} ((@var{elt} @var{a-pos} @var{b-pos}) @dots{}))
@end example

@var{Length} is an integer showing the length of the found LCS.
What follows is a list of elements of LCS; each sublist
consists of the element, the integer position of the element
in @var{seq-a}, then the integer position of the element in @var{seq-b}.

@example
(lcs-with-positions '(a) '(a))
 @result{} (1 ((a 0 0)))

(lcs-with-positions '(x a b y) '(p q a b))
 @result{} (2 ((a 1 2) (b 2 3)))

(lcs-with-positions '(x a b y) '(p a q b))
 @result{} (2 ((a 1 1) (b 2 3)))

(lcs-with-positions '(x y) '(p q))
 @result{} (0 ())
@end example
@end defun

@defun lcs-fold a-proc b-proc both-proc seed a b :optional eq-fn
@{@t{util.lcs}@}
A fundamental iterator over the "edit list" derived from
two lists @var{a} and @var{b}.

@var{A-proc}, @var{b-proc}, @var{both-proc} are all procedures
that take two arguments.   The second argument is a intermediate
state value of the calculation.  The first value is an element
only in @var{a} for @var{a-proc}, or an element only in @var{b}
for @var{b-proc}, or an element in both @var{a} and @var{b}
for @var{both-proc}.  The return value of each procedure is used
as the state value of the next call of either one of the procedures.
@var{Seed} is used as the initial value of the state value.
The last state value is returned from @code{lcs-fold}.

The three procedures are called in the following order: Suppose the sequence
@var{a} consists of @var{a'}@var{c}@var{a''}, and @var{b} consists of
@var{b'}@var{c}@var{b''}, where @var{a'}, @var{b'}, @var{a''}, and @var{b''}
are subsequences, and @var{c} is the head of the
LCS of @var{a} and @var{b}.   Then @var{a-proc} is called first on
each element in @var{a'}, @var{b-proc} is called second on
each element in @var{b'}, then @var{both-proc} is called on @var{c}.
Afterwards, the process is repeated using @var{a''} and @var{b''}.
@end defun

@defun lcs-edit-list a b :optional eq-fn
@{@t{util.lcs}@}
Calculates 'edit-list' from two lists @var{a} and @var{b}, which is
the smallest set of commands (additions and deletions) that changes
@var{a} into @var{b}.
This procedure is built on top of @code{lcs-fold} above.

Returns a list of @emph{hunk}s, which is a contiguous section of
additions and deletions.  Each hunk consists of a list of
directives, which is a form of:
@example
(@var{+}|@var{-} @var{position} @var{element})
@end example

Here's an example.  Suppose @var{a} and @var{b} are the following
lists, respectively.

@example
@var{a} @equiv{} ("A" "B" "C" "E" "H" "J" "L" "M" "N" "P")
@var{b} @equiv{} ("B" "C" "D" "E" "F" "J" "K" "L" "M" "R" "S" "T")
@end example

Then, @code{(lcs-edit-list a b equal?)} returns the following list.
@example
(((- 0 "A"))
 ((+ 2 "D"))
 ((- 4 "H") (+ 4 "F"))
 ((+ 6 "K"))
 ((- 8 "N") (- 9 "P") (+ 9 "R") (+ 10 "S") (+ 11 "T"))
)
@end example
The result consists of five hunks.  The first hunk consists of
one directive, @code{(- 0 "A")}, which means the element @code{"A"}
at the position 0 of list @var{a} has to be deleted.
The second hunk also consists of one directive, @code{(+ 2 "D")},
meaning the element @code{"D"} at the position 2 of list @var{b}
has to be added.  The third hunk means @code{"H"} at the position
4 of list @var{a} should be removed and @code{"F"} at the position
4 of list @var{b} should be added, and so on.

If you are familiar with Perl's Algorithm::Diff module, you may
notice that this is the same structure that its @code{diff} procedure
returns.
@end defun

@c ----------------------------------------------------------------------
@node Levenshtein edit distance, Pattern matching, The longest common subsequence, Library modules - Utilities
@section @code{util.levenshtein} - Levenshtein edit distance
@c NODE Levenshtein編集距離, @code{util.levenshtein} - Levenshtein編集距離

@deftp {Module} util.levenshtein
@mdindex util.levenshtein
This module provides procedures to calculate edit distance between
two sequences.  Edit distance is the minimum number of edit operations
required to match one sequence to another.
Three algorithms are implemented:

@table @asis
@item Levenshtein distance
Count deletion of one element, insertion of one element,
and substitution of one element.
@item Damerau-Levenshtein distance
Besides deletion, insertion and substitution, we allow transposition
of adjacent elements.
@item Restricted edit distance
Also called optimal string alignment distance.  Like Damerau-Levenshtein,
but once transposition is applied, no further editing on those elements
are allowed.
@end table

These algorithms are often used to compare strings, but the procedures
in this module can handle any type of sequence (@pxref{Sequence framework}).
@end deftp

@defun l-distance seq-A seq-B :key elt= cutoff
@defunx l-distances seq-A seq-Bs :key elt= cutoff
@defunx re-distance seq-A seq-B :key elt= cutoff
@defunx re-distances seq-A seq-Bs :key elt= cutoff
@defunx dl-distance seq-A seq-B :key elt= cutoff
@defunx dl-distances seq-A seq-Bs :key elt= cutoff
@{@t{util.levenshtein}@}
Calculates Levenshtein distance (@code{l-*}), restricted edit
distance (@code{re-*}) and Damerau-Levenshtein distance (@code{dl-*})
between sequences, respectively.  Each algorithm comes in two 
flavors: The singular form @code{*-distance} takes two sequences,
@var{seq-A} and @var{seq-B}, and calculates distance between them.
The plural form @code{*-distances} takes a sequence @var{seq-A}
and a list of sequences @var{seq-Bs}, and calculates distances
between @var{seq-A} and each in @var{seq-Bs}.

If you need to calculate distances from a single sequence to many
sequences, using the plural version is much faster than repeatedly
calling the singular version, for the plural version can reuse internal
data structures and save allocation and setup time.

Sequences can be any object that satisfy the @code{<sequence>} protocol
(@pxref{Sequence framework}).

The keyword argument @var{elt=} is used to compare elements in
the sequences.  Its default is @code{eqv?}.

The keyword argument @var{cutoff} must be, if given, a nonnegative
exact integer.  Once the possible minimum distance between two sequences
becomes greater than this number, the algorithm stops and gives @code{#f}
as the result, and moves on to the next calculation.
This is useful when you run the algorithm on large set of sequences
and you only need to look for the pairs closer than the certain limit.

In our implementation, Levenshtein is the fastest, Damerau-Levenshtein
is the slowest and Restricted edit is somewhere inbetween.  If you don't
need to take into account of transpositions, use Levenshtein; it counts
2 for @code{cat} -> @code{act}, while other algorithms yield 1 for it.
If you need to consider transpositions, choose either
@code{re-} or @code{dl-}.  The catch in @code{re-} is that it does not
satisfy triangular inequality, i.e. for given three sequences X, Y and Z,
(Damerau-)Levenshtein distance L always satisfy
L(X;Z) <= L(X;Y) + L(Y;Z), but restricted edit distance doesn't
guarantee that.

@example
(l-distance "cat" "act")  @result{} 2
(l-distances "cat" '("Cathy" "scathe" "stack")
  :elt= char-ci=?)
  @result{} (2 3 4)

(re-distance "cat" "act") @result{} 1

(re-distances "pepper"
  '("peter" "piper" "picked" "peck" "pickled" "peppers")
  :cutoff 4)
  @result{} (2 2 4 4 #f 1)

(dl-distance '(a b c d e) '(c d a b e)) @result{} 4
@end example

Note: If you pass a list of sequences to the second argument
of the singular version by accident, you might not get an error immediately
because a list is also a sequence.
@end defun

@c ----------------------------------------------------------------------
@node Pattern matching, SLIB-compatible record type, Levenshtein edit distance, Library modules - Utilities
@section @code{util.match} - Pattern matching
@c NODE パターンマッチング, @code{util.match} - パターンマッチング

@deftp {Module} util.match
@mdindex util.match
This module is a port of Andrew Wright's pattern matching macro library.
It is widely used in the Scheme world, and ported to various Scheme
implementations, including Chez Scheme, PLT Scheme, Scheme48, Chicken,
and SLIB.
It is similar to, but more powerful than
Common Lisp's @code{destructuring-bind}.

This version retains compatibility of the original Wright's macro,
except (1) @var{box} is not supported since Gauche doesn't have one,
and (2) structure matching is integrated to Gauche's object system.
@end deftp

We show a list of APIs first, then the table of complete syntax of
patterns, followed by examples.

@subheading Pattern matching API

@defmac match expr clause @dots{}
@{@t{util.match}@}
Each @var{clause} is either one of the followings:
@example
(@var{pat} @var{body} @dots{})
(@var{pat} (=> @var{identifier}) @var{body} @dots{})
@end example

First, the @var{expr} is matched against @var{pat} of each clauses.
The detailed syntax of the pattern is explained below.

If a matching @var{pat} is found, the @emph{pattern variables} in
@var{pat} are bound to the corresponding elements in @var{expr}, then
@var{body} @dots{} are evaluated.  Then @code{match} returns the value(s)
of the last expression of @var{body} @dots{}.

If the clause is the second form, @var{identifier} is also bound
to the failure continuation of the @var{clause}.  It is a
procedure with no arguments, and when called, it jumps back to
the matcher as if the matching of @var{pat} is failed, and
@code{match} continues to try the rest of clauses.
So you can perform extra tests
within @var{body} @dots{} and if you're not satisfied you can reject
the match by calling @code{(@var{identifier})}.  See the examples
below for more details.

If no @var{pat} matches, @code{match} reports an error.
@end defmac

@defmac match-lambda clause @dots{}
@{@t{util.match}@}
Creates a function that takes one argument and performs @code{match} on it,
using @var{clause} @dots{}.  It's functionally equivalent to the following
expression:
@example
(lambda (expr) (match expr @var{clause} @dots{}))
@end example

Example:

@example
(map (match-lambda
       ((item price-per-lb (quantity 'lbs))
        (cons item (* price-per-lb quantity)))
       ((item price-per-lb (quantity 'kg))
        (cons item (* price-per-lb quantity 2.204))))
     '((apple      1.23 (1.1 lbs))
       (orange     0.68 (1.4 lbs))
       (cantaloupe 0.53 (2.1 kg))))
 @result{} ((apple . 1.353) (orange . 0.952)
            (cantaloupe . 2.4530520000000005))
@end example
@end defmac

@defmac match-lambda* clause @dots{}
@{@t{util.match}@}
Like @code{match-lambda}, but performs @code{match} on the list of
whole arguments.
It's functionally equivalent to the following expression:
@example
(lambda expr (match expr @var{clause} @dots{}))
@end example
@end defmac

@defmac match-let ((pat expr) @dots{}) body-expr @dots{}
@defmacx match-let name ((pat expr) @dots{}) body-expr @dots{}
@defmacx match-let* ((pat expr) @dots{}) body-expr @dots{}
@defmacx match-letrec ((pat expr) @dots{}) body-expr @dots{}
@{@t{util.match}@}
Generalize @code{let}, @code{let*}, and @code{letrec} to allow
patterns in the binding position rather than just variables.
Each @var{expr} is evaluated, and then matched to @var{pat},
and the bound pattern variables are visible in
@var{body-expr} @dots{}.

@example
(match-let (
             (((ca . cd) ...)   '((a . 0) (b . 1) (c . 2)))
           )
  (list ca cd))
 @result{} ((a b c) (0 1 2))
@end example

If you're sick of parenthesis, try @code{match-let1} below.
@end defmac

@defmac match-let1 pat expr body-expr @dots{}
@{@t{util.match}@}
This is a Gauche extension and isn't found in the original Wright's code.
This one is equivalent to the following code:
@example
(match-let ((@var{pat} @var{expr})) @var{body-expr} @dots{})
@end example

Syntactically, @code{match-let1} is very close to the Common Lisp's
@code{destructuring-bind}.

@example
(match-let1 ('let ((var val) ...) body ...)
            '(let ((a b) (c d)) foo bar baz)
  (list var val body))
 @result{} ((a c) (b d) (foo bar baz))
@end example
@end defmac

@defmac match-define pat expr
@{@t{util.match}@}
Like toplevel @code{define}, but allows a pattern instead of variables.

@example
(match-define (x . xs) (list 1 2 3))

x  @result{} 1
xs @result{} (2 3)
@end example

@end defmac

@subheading Pattern syntax

Here's a summary of pattern syntax. The asterisk @code{(*)}
after explanation means Gauche's extension which does not present
in the original Wright's code.

@example
pat : @var{patvar}                       ;; anything, and binds pattern var
    | @b{_}                            ;; anything
    | ()                           ;; the empty list
    | #t                           ;; #t
    | #f                           ;; #f
    | @var{string}                       ;; a string
    | @var{number}                       ;; a number
    | @var{character}                    ;; a character
    | '@var{sexp}                        ;; an s-expression
    | '@var{symbol}                      ;; a symbol (special case of s-expr)
    | (@var{pat1} ... @var{patN})              ;; list of n elements
    | (@var{pat1} ... @var{patN} . @var{patN+1})     ;; list of n or more
    | (@var{pat1} ... @var{patN} @var{patN+1} ooo)   ;; list of n or more, each element
                                   ;;   of remainder must match @var{patN+1}
    | #(@var{pat1} ... @var{patN})             ;; vector of n elements
    | #(@var{pat1} ... @var{patN} @var{patN+1} ooo)  ;; vector of n or more, each element
                                   ;;   of remainder must match @var{patN+1}
    | (@b{$} @var{class} @var{pat1} ... @var{patN})      ;; an object (@var{patK} matches in slot order)
    | (@b{struct} @var{class} @var{pat1} ... @var{patN}) ;; ditto (*)
    | (@b{@@} @var{class} (@var{slot1} @var{pat1}) ...)   ;; an object (using slot names) (*)
    | (@b{object} @var{class} (@var{slot1} @var{pat1}) ...) ;; ditto (*)
    | (@b{=} @var{proc} @var{pat})                 ;; apply proc, match the result to pat
    | (@b{and} @var{pat} ...)                ;; if all of pats match
    | (@b{or} @var{pat} ...)                 ;; if any of pats match
    | (@b{not} @var{pat} ...)                ;; if all pats don't match at all
    | (@b{?} @var{predicate} @var{pat} ...)        ;; if predicate true and all pats match
    | (@b{set!} @var{patvar})                ;; anything, and binds setter
    | (@b{get!} @var{patvar})                ;; anything, and binds getter
    | `qp                          ;; a quasi-pattern

patvar : a symbol except @b{_}, @b{quote}, @b{$}, @b{struct}, @b{@@}, @b{object}, @b{=}, @b{and}, @b{or},
         @b{not}, @b{?}, @b{set!}, @b{get!}, @b{quasiquote}, @b{...}, @b{___}, @b{..@i{k}}, @b{__@i{k}}.

@c @b doesn't work well in pdf version, so we conditionalize...
@ifnottex
ooo : @b{...}                          ;; zero or more
    | @b{___}                          ;; zero or more
    | @b{..@i{k}}                          ;; @i{k} or more, where @i{k} is an integer.
                                   ;;   Example: @b{..1}, @b{..2} ...
    | @b{__@i{k}}                          ;; @i{k} or more, where @i{k} is an integer.
                                   ;;   Example: @b{__1}, @b{__2} ...
@end ifnottex
@iftex
ooo : ...                          ;; zero or more
    | ___                          ;; zero or more
    | ..@slanted{k}                          ;; @i{k} or more, where @i{k} is an integer.
                                   ;;   Example: ..1, ..2 ...
    | __@slanted{k}                          ;; @i{k} or more, where @i{k} is an integer.
                                   ;;   Example: __1, __2 ...
@end iftex

@end example

@itemize @bullet
@item
A bare symbol is a "pattern variable"; it matches anything, and
the matched part of the expression is bound to the symbol.
The following symbols have special meanings and cannot be used
as a pattern variable: @code{_}, @code{quote}, @code{$}, @code{struct},
@code{@@}, @code{object}, @code{=}, @code{and}, @code{or},
@code{not}, @code{?}, @code{set!}, @code{get!}, @code{quasiquote},
@code{...}, @code{___}, and @code{..k} and @code{__k} where @emph{k} is
an integer.

@item
A symbol @code{_} matches anything, without binding a pattern variable.
It can be used to show "don't care" placeholder.

@item
Literals such as emptylist, booleans, strings, numbers, characters and
keywords match the same object (in the sense of @code{equal?}).

@item
Quoted expression matches the same expression (in the sense of @code{equal?}).
You can use a quoted symbol to match the symbol itself.

@item
A keyword, without a quote, used to match the same keyword object.
Since we're in the process of unifying keywords and symbols, the user is 
recommended to write keywords with a quote in a pattern in order to match
the keyword in the input.  @xref{Keyword and symbol integration}, for
the details.

@item
A list and a vector in general match a list or a vector whose elements
matches the elements in the pattern recursively, unless the first element
of the list is one of the special symbols listed above, it has a special
meaning.

As a special case, the last element of a vector or a list can be
followed by a symbol @code{...}.  In that case, the pattern just before
the symbol @code{...} can be applied repeatedly until it consumes all the
elements in the given expression.  A symbol @code{___} can be used
in place of @code{...}; it is useful when you want to produce a pattern
by syntax-rules macro.

For a list pattern, you can also use a symbol @code{..1}, @code{..2},
@dots{}, which specifies the minimum number of repetition.

@item
@code{($ class pat1 @dots{})} matches an instance of a class @code{class}.
Each pattern @code{pat1} @dots{} matches each value of slots,
in order of @code{(class-slots class)} by default.
(Records are exception; they match the same order as their
default constructor since 0.9.6.)

@code{(struct class pat1 @dots{})} has the same meaning.  Although
the original Wright's code doesn't have @code{struct}, PLT Scheme has
it in its extended match feature, and it is more descriptive.

This is an adaptation of the original feature that can match structures.
It is useful to match a simple instance that you know the order of
slots; for example, a simple record created by @code{define-record-type}
(@pxref{Record types}) would be easy to match by positioned values.

If the instance's class uses inheritances, it is a bit difficult to
match by positions.  You can use @code{@@} or @code{object} pattern
below to match using slot names.

@item
@code{(object class (slot1 pat1) @dots{})} matches an instance
of a class @code{class} whose value of @var{slot1} @dots{} matches
@var{pat1} @dots{}.  This is Gauche's extension.  @code{@@} can be
used in place of @code{object}, but @code{object} is recommended
because of descriptiveness.

@item
@code{(= proc pat)} first applies @var{proc} to the corresponding
expression, then match the result with @var{pat}.

@item
@code{(and pat @dots{})}, @code{(or pat @dots{})}, and
@code{(not pat @dots{})} are boolean operations of patterns.

@item
@code{(? predicate pat @dots{})} first applies a predicate to the
corresponding expression, and if it returns true, applies each
@code{pat} @dots{} to the expression.

@item
@code{(set! patvar)} matches anything, and binds an one-argument
procedure to a pattern variable @var{patvar}.  If the procedure is
called, it replaces the value of matched pattern for the given argument.

@item
@code{(get! patvar)} matches anything, and binds a zero-argument
procedure to a pattern variable @var{patvar}.  If the procedure is
called, it returns the matched value.

@item
@code{`qp} is a quasipattern.  @var{qp} is quoted, in the sense
that it matches itself, @emph{except} the pattern that is unquoted.
(Don't confuse quasipattern to quasiquote, though the functions are
similar.  Quasiquote turns off evaluation except unquoted subtree.
Quasiquote turns off the special pattern syntax except unquoted subtree.
See the examples below).
@end itemize

@subheading Pattern examples

A simple structure decomposition:
@example
(match '(0 (1 2) (3 4 5))
  [(a (b c) (d e f))
   (list a b c d e f)])
 @result{} (0 1 2 3 4 5)
@end example

Using predicate patterns:
@example
(match 123
  [(? string? x) (list 'string x)]
  [(? number? x) (list 'number x)])
 @result{} (number 123)
@end example

Extracting variables and expressions from @code{let}.
Uses repetition and predicate patterns:
@example
(define let-analyzer
  (match-lambda
    [('let (? symbol?)
           ((var expr) ...)
       body ...)
     (format "named let, vars=~s exprs=~s" var expr)]
    [('let ((var expr) ...)
       body ...)
     (format "normal let, vars=~s exprs=~s" var expr)]
    [_
     (format "malformed let")]))

(let-analyzer '(let ((a b) (c d)) e f g))
 @result{} "normal let, vars=(a c) exprs=(b d)"

(let-analyzer '(let foo ((x (f a b)) (y (f c d))) e f g))
 @result{} "named let, vars=(x y) exprs=((f a b) (f c d))"

(let-analyzer '(let (a) b c d))
 @result{} "malformed let"
@end example

Using @code{=} function application.  The pattern variable @var{m}
is matched to the result of application of the regular expression.
@example
(match "gauche-ref.texi"
  ((? string? (= #/(.*)\.([^.]+)$/ m))
   (format "base=~a suffix=~a" (m 1) (m 2))))
 @result{} "base=gauche-ref suffix=texi"
@end example

An example of quasipattern.   In the first expression, the
pattern except @code{value} is quoted, so the symbols @code{the},
@code{answer}, and @code{is} are not pattern variables but literal
symbols.   The second expression shows that; input symbol @code{was}
does not match the literal symbol @code{is} in the pattern.
If we don't use quasiquote, all symbols in the pattern are pattern
variables, so any four-element list matches as the third expression shows.
@example
(match '(the answer is 42)
  [`(the answer is ,value) value]
  [else #f])
 @result{} 42

(match '(the answer was 42)
  [`(the answer is ,value) value]
  [else #f])
 @result{} #f

(match '(a b c d)
  [(the answer is value) value]
  [else #f])
 @result{} d
@end example

An example of matching records.
The following code implements ``rotation''
operation to balance a red-black tree.

@example
(define-record-type T #t #t
  color left value right)

(define (rbtree-rotate t)
  (match t
    [(or ($ T 'B ($ T 'R ($ T 'R a x b) y c) z d)
         ($ T 'B ($ T 'R a x ($ T 'R b y c)) z d)
         ($ T 'B a x ($ T 'R ($ T 'R b y c) z d))
         ($ T 'B a x ($ T 'R b y ($ T 'R c z d))))
     (make-T 'R (make-T 'B a x b) y (make-T 'B c z d))]
    [else t]))
@end example

@c ----------------------------------------------------------------------
@node SLIB-compatible record type, Relation framework, Pattern matching, Library modules - Utilities
@section @code{util.record} - SLIB-compatible record type
@c NODE SLIB-互換のレコード型, @code{util.record} - SLIB-互換のレコード型

@deftp {Module} util.record
@mdindex util.record
This module provides a Guile and SLIB compatible record type API.
It is built on top of Gauche's object system.

See also @ref{Record types}, which provides a convenience macro
@code{define-record-type}.
@end deftp

@defun make-record-type type-name field-names
@{@t{util.record}@}
Returns a new class which represents a new record type.
(It is what is called @emph{record-type descriptor} in SLIB).
In Gauche, the new class is a subclass of @code{<record>}
(see @ref{Record types}).

@var{type-name} is a string that is used for debugging purposes.
It is converted to a symbol and set as the name of the new class.
@var{field-names} is a list of symbols of the names of fields.
Each field is implemented as a slot of the new class.
@end defun

In the following procedures, @var{rtd} is the record class
created by @code{make-record-type}.

@defun record-constructor rtd :optional field-names
@{@t{util.record}@}
Returns a procedure that constructs an instance
of the record type of given @var{rtd}.  The returned
procedure takes exactly as many arguments as @var{field-names},
which defaults to @code{'()}.  Each argument sets the initial
value of the corresponding field in @var{field-names}.
@end defun

@defun record-predicate rtd
@{@t{util.record}@}
Returns a procedure that takes one argument, which returns @code{#t}
iff the given argument is of type of @var{rtd}.
@end defun

@defun record-accessor rtd field-name
@{@t{util.record}@}
Returns an accessor procedure for the field named by @var{field-name}
of type @var{rtd}.  The accessor procedure takes an instance of
@var{rtd}, and returns the value of the field.
@end defun

@defun record-modifier rtd field-name
@{@t{util.record}@}
Returns a modifier procedure for the field named by @var{field-name}
of type @var{rtd}.  The modifier procedure takes two arguments,
an instance of @var{rtd} and a value, and sets the value to
the specified field.
@end defun

@example
(define rtd (make-record-type "my-record" '(a b c)))

rtd @result{} #<class my-record>

(define make-my-record (record-constructor rtd '(a b c)))

(define obj (make-my-record 1 2 3))

obj @result{} #<my-record 0x819d9b0>

((record-predicate? rtd) obj)  @result{} #t

((record-accessor rtd 'a) obj) @result{} 1
((record-accessor rtd 'b) obj) @result{} 2
((record-accessor rtd 'c) obj) @result{} 3

((record-modifier rtd 'a) obj -1)

((record-accessor rtd 'a) obj) @result{} -1
@end example

@c ----------------------------------------------------------------------
@node Relation framework, Stream library, SLIB-compatible record type, Library modules - Utilities
@section @code{util.relation} - Relation framework
@c NODE リレーションフレームワーク, @code{util.relation} - リレーションフレームワーク

@deftp {Module} util.relation
@mdindex util.relation
Provides a set of common operations for relations.

Given set of values S1, S2, ..., Sn, a relation R is a set of tuples
such that the first element of a tuple is from S1, the second from
S2, ..., and the n-th from Sn.  In another word, R is a subset of
Cartesian product of S1, ..., Sn.
(The definition, as well as the term @emph{relation}, is taken
from the Codd's 1970 paper,
"A Relational Model of Data for Large Shared Data Banks", in
CACM 13(6) pp.377--387.)

This definition can be applied to various datasets: A set of Gauche
object system instances is a relation, if you view each instance as
a tuple and each slot value as the actual values.  A list of lists can be a
relation.  A stream that reads from CSV table produces a relation.
Thus it would be useful to provide a module that implements generic
operations on relations, no matter how the actual representation is.

From the operational point of view, we can treat any datastructure
that provides the following four methods; @code{relation-rows},
which retrieves a collection of tuples (rows);
@code{relation-column-names}, @code{relation-accessor}, and
@code{relation-modifier}, which provide the means to access
meta-information.
All the rest of relational operations are built on top of
those primitive methods.

A concrete implementation of relation can use duck typing,
i.e. it doesn't need to inherit a particular base class to
use the relation methods.  However, for the convenience,
a base class @code{<relation>} is provided in this module.
It works as a mixin class---a concrete class typically wants
to inherit @code{<relation>} and @code{<collection>} or
@code{<sequence>}.  Check out the sample implementations
in the @file{lib/util/relation.scm} in the source tree, if
you're curious.

This module is still under development.
The plan is to build useful relational operations on top of the
common methods.
@end deftp

@subheading Basic class and methods

@deftp {Class} <relation>
@clindex relation
@{@t{util.relation}@}
An abstract base class of relations.
@end deftp

@deffn {Method} relation-column-names (r <relation>)
@{@t{util.relation}@}
A subclass must implement this method.
It should return a sequence of names of the columns.
The type of column names is up to the relation; we don't
place any restriction on it, as far as they are different
each other in terms of @code{equal?}.
@end deffn

@deffn {Method} relation-accessor (r <relation>)
@{@t{util.relation}@}
A subclass must implement this method.
It should return a procedure that takes two arguments, a row from
the relation @var{r} and a column name, and returns the value
of the specified column.
@end deffn

@deffn {Method} relation-modifier (r <relation>)
@{@t{util.relation}@}
A subclass must implement this method. It should returns a procedure
that takes three arguments, a row from the relation @var{r}, a column
name, and a value to set.

If the relation is read-only, this method returns @code{#f}.
@end deffn

@deffn {Method} relation-rows (r <relation>)
@{@t{util.relation}@}
A subclass must implement this method.
It should return the underlying instance of @code{<collection>} or
its subclass (e.g.  @code{<sequence>})
@end deffn

The rest of method are built on top of the above four methods.
A subclass of @code{<relation>} may overload some of the
methods below for better performance, though.

@deffn {Method} relation-column-name? (r <relation>) column
@{@t{util.relation}@}
Returns true iff @var{column} is a valid column name for the relation
@var{r}.
@end deffn

@deffn {Method} relation-column-getter (r <relation>) column
@deffnx {Method} relation-column-setter (r <relation>) column
@{@t{util.relation}@}
Returns a procedure to access the specified column of a row
from the relation @var{r}.  @code{Relation-column-getter}
should return a procedure that takes one argument, a row.
@code{Relation-column-setter} should return a procedure that
takes two arguments, a row and a new value to set.

If the relation is read-only, @code{relation-column-setter}
returns @code{#f}.
@end deffn

@deffn {Method} relation-ref (r <relation>) row column :optional default
@{@t{util.relation}@}
@var{Row} is a row from the relation @var{r}.  Returns value of
the @var{column} in @var{row}.  If @var{column} is not a valid
column name, @var{default} is returned if it is given, otherwise
an error is signaled.
@end deffn

@deffn {Method} relation-set! (r <relation>) row column value
@{@t{util.relation}@}
@var{Row} is a row from the relation @var{r}.  Sets @var{value}
as the value of @var{column} in @var{row}.  This may signal
an error if the relation is read-only.
@end deffn

@deffn {Method} relation-column-getters (r <relation>)
@deffnx {Method} relation-column-setters (r <relation>)
@{@t{util.relation}@}
Returns full list of getters and setters.  Usually the default
method is sufficient, but the implementation may want to cache
the list of getters, for example.
@end deffn

@deffn {Method} relation-coercer (r <relation>)
@{@t{util.relation}@}
Returns a procedure that coerces a row into a sequence.
If the relation already uses a sequence to represent a row,
it can return row as is.
@end deffn

@deffn {Method} relation-insertable? (r <relation>)
@{@t{util.relation}@}
Returns true iff new rows can be inserted to the relation @var{r}.
@end deffn

@deffn {Method} relation-insert! (r <relation>) row
@{@t{util.relation}@}
Insert a row @var{row} to the relation @var{r}.
@end deffn

@deffn {Method} relation-deletable? (r <relation>)
@{@t{util.relation}@}
Returns true iff rows can be deleted from the relation @var{r}.
@end deffn

@deffn {Method} relation-delete! (r <relation>) row
@{@t{util.relation}@}
Deletes a row @var{row} from the relation @var{r}.
@end deffn

@deffn {Method} relation-fold (r <relation>) proc seed column @dots{}
@{@t{util.relation}@}
Applies @var{proc} to the values of @var{column} @dots{} of each row,
passing @var{seed} as the state value.  That is, for each row in
@var{r}, @var{proc} is called as follows:
@example

(@var{proc} @var{v_0} @var{v_1} @dots{} @var{v_i} @var{seed})

 where @var{v_k} = (relation-ref @var{r} @var{row} @var{column_k})

@end example

The result of the call becomes a new seed value, and the final result
is returned from @var{relation-fold}.

For example, if a relation has a column named @code{amount},
and you want to sum up all of them in a relation @var{r},
you can write like this:
@example
(relation-fold r + 0 'amount)
@end example
@end deffn

@subheading Concrete classes

@deftp {Class} <simple-relation>
@clindex simple-relation
@{@t{util.relation}@}
@end deftp

@deftp {Class} <object-set-relation>
@clindex object-set-relation
@{@t{util.relation}@}
@end deftp

@c ----------------------------------------------------------------------
@node Stream library, Topological sort, Relation framework, Library modules - Utilities
@section @code{util.stream} - Stream library
@c NODE ストリームライブラリ, @code{util.stream} - ストリームライブラリ

@deftp {Module} util.stream
@mdindex util.stream
This module provides a library of lazy streams, including the
functions and syntaxes defined in srfi-40 and srfi-41,
the latter of which became a part of R7RS large (as @code{(scheme stream)},

Gauche has a built-in lazy sequences (@pxref{Lazy sequences}), which is
a lazy stream integrated to a list so that you can use all list procedures
on it.  Lazy streams provided in this module are somewhat heavier than
lazy sequences and you need to use special procedures,
but it is strictly lazy (while a lazy sequence evaluates one element ahead)
and portable.
@end deftp

@menu
* Stream primitives::
* Stream constructors::
* Stream binding::
* Stream consumers::
* Stream operations::
@end menu

@node Stream primitives, Stream constructors, Stream library, Stream library
@subsection Stream primitives

@defun stream? obj
[R7RS stream]
@{@t{util.stream}@}
Returns @code{#t} iff @var{obj} is a stream created by a procedure
of @code{util.stream}.
@end defun

@defvar stream-null
[R7RS stream]
@{@t{util.stream}@}
The singleton instance of NULL stream.
@end defvar

@defmac stream-cons object stream
[R7RS stream]
@{@t{util.stream}@}
A fundamental constructor of a stream.  Adds @var{object} to the
head of a @var{stream}, and returns a new stream.
@end defmac

@defun stream-null? obj
[R7RS stream]
@{@t{util.stream}@}
Returns @code{#t} iff @var{obj} is the null stream.
@end defun

@defun stream-pair? obj
[R7RS stream]
@{@t{util.stream}@}
Returns @code{#t} iff @var{obj} is a non-null stream.
@end defun

@defun stream-car s
[R7RS stream]
@{@t{util.stream}@}
Returns the first element of the stream @var{s}.
@end defun

@defun stream-cdr s
[R7RS stream]
@{@t{util.stream}@}
Returns the remaining elements of the stream @var{s}, as a stream.
@end defun

@defmac stream-delay expr
[SRFI-40]
@{@t{util.stream}@}
Returns a stream which is a delayed form of @var{expr}.

As a rule of thumb, any stream-producing functions should
wrap the resulting expression by @code{stream-delay}.
(Or you can use @code{stream-lambda}, @code{stream-let} or @code{stream-define},
described below.)
@end defmac

@defmac stream-lambda formals body body2 @dots{}
[R7RS stream]
@{@t{util.stream}@}
A convenience macro to create a function that returns a stream.
Effectively, @code{(stream-lambda formals body body2 @dots{})} is the same
as @code{(lambda formals (stream-delay body body2 @dots{}))}.
@end defmac

@node Stream constructors, Stream binding, Stream primitives, Stream library
@subsection Stream constructors

@defun stream obj @dots{}
[SRFI-40]
@{@t{util.stream}@}
Returns a new stream whose elements are @var{obj} @dots{}.

Note: This differs from srfi-41's (@code{scheme.stream}'s) @code{stream},
which is a macro so that arguments are lazily evaluated.  Srfi-41's
@code{stream} is provided as @code{stream+} in this module.

@example
(stream 1 2 3))     @result{} @r{a stream that contains} (1 2 3)
(stream 1 (/ 1 0))) @result{} @r{error}
@end example
@end defun

@defmac stream+ expr @dots{}
@{@t{util.stream}@}
Returns a new stream whose elements are the result of @var{expr} @dots{}.

This is the same as srfi-41(@code{scheme.stream})'s @code{stream}.
Each @var{expr} isn't evaluated until it is accessed.

@example
(define s (stream+ 1 (/ 1 0)))  ;; doesn't yield an error

(stream-car s)  @result{} 1

(stream-cadr s) @result{} @r{error}
@end example
@end defmac

@defun stream-unfold f p g seed
[R7RS stream]
@{@t{util.stream}@}
Creates a new stream whose element is determined as follows:

@itemize
@item
A ``go'' predicate @var{p} is called on the current seed value.
If it yields @code{#f}, the stream terminates.
@item
Otherwise, @code{(f s)} is the element of the stream,
and @code{(g s)} becomes the next seed value, where
@code{s} is the current seed value.  The initial seed value
is given by @var{seed}.
@end itemize

Note: Unfortunately, the order of arguments differs from
other @code{*-unfold} procedures, which takes @code{p f g}
(predicate, value-generator and seed-generator).  Furthermore,
the predicate is stop-predicate (returning true stops iteration).

@example
(stream->list
 (stream-unfold integer->char (cut < <> 58) (cut + 1 <>) 48))
 @result{} (#\0 #\1 #\2 #\3 #\4 #\5 #\6 #\7 #\8 #\9)
@end example
@end defun

@defun stream-unfoldn f seed n
[SRFI-40]
@{@t{util.stream}@}
Creates @var{n} streams related each other, whose contents are
generated by @var{f} and @var{seed}.

The @var{f} is called with the current seed value,
and returns @code{@var{n}+1} values:
@example
(@var{f} @var{seed})
  => seed result_0 result_1 @dots{} result_n-1
@end example

The first value is to be the next seed value.
@var{Result_k} must be one of the following forms:
@table @code
@item (val)
@var{val} will be the next car of @var{k}-th stream.
@item #f
No new information for @var{k}-th stream.
@item ()
The end of @var{k}-th stream has been reached.
@end table

The following example creates two streams, the first one produces
an infinite series of odd numbers and the second produces evens.

@example
gosh> (define-values (s0 s1)
        (stream-unfoldn (lambda (i)
                          (values (+ i 2)          ;; next seed
                                  (list i)         ;; for the first stream
                                  (list (+ i 1)))) ;; for the second stream
                        0 2))
#<undef>
gosh> (stream->list (stream-take s0 10))
(0 2 4 6 8 10 12 14 16 18)
gosh> (stream->list (stream-take s1 10))
(1 3 5 7 9 11 13 15 17 19)
@end example
@end defun

@defun stream-unfolds f seed
[R7RS stream]
@{@t{util.stream}@}
Like @code{stream-unfoldn}, but the number of created streams is
determined by the number fo return values from @var{f}.  See
@code{stream-unfoldn} above for the details.
@end defun

@defun stream-constant obj @dots{}
[R7RS stream]
@{@t{util.stream}@}
Returns an infinite stream that repeats @var{obj} @dots{}.

@example
(stream->list 10 (stream-constant 1 2))
  @result{} (1 2 1 2 1 2 1 2 1 2)
@end example
@end defun

@defun make-stream n :optional init
@{@t{util.stream}@}
Creates a new stream of @var{n} elements of @var{init}.
If @var{init} is omitted, @code{#f} is used.
Specifying a negative number to @var{n} creates an infinite stream.
@end defun

@defun stream-tabulate n init-proc
@{@t{util.stream}@}
Creates a new stream of @var{n} elements.
The @var{k}-th element is obtained by applying @var{init-proc}
to @var{k}.  Specifying a negative number to @var{n} creates
an infinite stream.
@end defun

@defun stream-iota :optional count start step
@{@t{util.stream}@}
Creates a new stream of numbers, starting from @var{start}
and incrementing @var{step}.  The length of stream is maximum
integer not greater than nonnegative real number @var{count}.
The default values of @code{count}, @var{start} and @var{step} are
@code{+inf.0}, 0 and 1, respectively.

If @var{start} and @var{step} are exact, and @var{count} is exact or
infinite, a sequence of exact numbers are created.  Otherwise,
a sequence of inexact numbers are created.
@end defun

@defun stream-range start :optional end step
[R7RS stream]
@{@t{util.stream}@}
Creates a new stream of real numbers, starting from @var{start}
and stops before @var{end}, stepping by @var{step}.
If @var{end} is omitted, positive infinity is assumed.
If @var{step} is omitted, @code{1} is assumed if @var{end} is greater
than @var{start}, and @code{-1} if @var{end} is less than @var{start}.

The generated numbers are exact if @var{start} and @var{step} are exact
and @var{end} is either exact or infinite.  Otherwise, inexact numbers
are generated.

In R7RS @code{scheme.stream}, @var{end} argument is required.

@example
(stream->list (stream-range 0 10))
 @result{} (0 1 2 3 4 5 6 7 8 9)
@end example
@end defun

@defun stream-from start :optional step
[R7RS stream]
@{@t{util.stream}@}
This is yet another number sequence generator.  Generates an infinite
sequence whose @var{i}-th element is @code{(+ @var{start} (* i @var{step}))}.
If @var{step} is omitted, 1 is assumed.  If both @var{start} and @var{step}
are exact, exact numbers are generated.  Otherwise, inexact numbers are
generated.
@end defun

@defun stream-iterate f seed
[R7RS stream]
@{@t{util.stream}@}
Returns a stream starting from @var{seed}, and each successive element
is calculated by @code{(@var{f} @var{s})} where @var{s} is the previous
element.

@example
(stream->list 5 (stream-iterate (cut cons 'x <>) '()))
  @result{} (() (x) (x x) (x x x) (x x x x))
@end example

See also @code{literate} in @code{gauche.lazy} (@pxref{Lazy sequence utilities}).
@end defun

@defun stream-xcons a b
@{@t{util.stream}@}
@code{(stream-cons b a)}.  Just for convenience.
@end defun

@defun stream-cons* elt @dots{} stream
@{@t{util.stream}@}
Creates a new stream which appends @var{elt} @dots{} before @var{stream}.
@end defun

@defun list->stream list
[R7RS stream]
@{@t{util.stream}@}
Returns a new stream whose elements are the elements in @var{list}.
@end defun

@defun string->stream string :optional tail-stream
@{@t{util.stream}@}
Converts a string to a stream of characters.  If an optional
@var{tail-stream} is given, it becomes the tail of the resulting
stream.

@example
@end example
(stream->list (string->stream "abc" (list->stream '(1 2 3))))
 @result{} (#\a #\b #\c 1 2 3)
@end defun

@defun stream-format fmt arg @dots{}
@{@t{util.stream}@}
Returns a stream which is a result of applying @code{string->stream}
to @code{(format fmt arg @dots{})}.
@end defun

@defun port->stream :optional iport reader closer
[R7RS stream]
@{@t{util.stream}@}
Creates a stream, whose elements consist of the items
read from the input port @var{iport}.
The default @var{iport} is the current input port.
The default @var{reader} is @code{read-char}.

The result stream terminates at the point where @var{reader}
returns EOF (EOF itself is not included in the stream).
The port won't be closed by default when it reaches EOF.

If @var{closer} is given, it is called with @var{iport} as
an argument just after @var{reader} reads EOF.  You can close the port
with it.

The @var{reader} and @var{closer} arguments are Gauche's extension.
R7RS @code{scheme.stream} only takes one optional argument, @var{iport}.
@end defun

@defun generator->stream gen
@{@t{util.stream}@}
Creates a lazy stream of values generated by a generator @var{gen}.
A generator is a thunk that returns a value every time it is called,
with returning EOF to indicate the end of the input.
@xref{Generators}, for the details of generators.

See also @code{generator->lseq}, which is another way to get
a lazy sequence from a generator (@pxref{Lazy sequences}, for the details).
@end defun


@defun iterator->stream iter
@{@t{util.stream}@}
A generic procedure to turn an internal iterator @var{iter}
into a stream of iterated results.

The @var{iter} argument is a procedure that takes two arguments,
@var{next} and @var{end}, where @var{next} is a procedure that takes
one argument and @var{end} is a thunk.
@var{Iter} is supposed to iterate over some set and call @var{next}
for each argument, then call @var{end} to indicate the end of
the iteration.  Here's a contrived example:

@example
(stream->list
 (iterator->stream
  (lambda (next end) (for-each next '(1 2 3 4 5)) (end))))
 @result{} (1 2 3 4 5)
@end example

Internally @code{iterator->stream} uses the ``inversion of iterator''
technique, so that @var{iter} only iterates to the element that
are needed by the stream.  Thus @var{iter} can iterate over
an infinite set.  In the following example, @var{iter} is
an infinite loop calling @var{next} with increasing integers,
but only the first 10 elements are calculated because of
@code{stream-take}:

@example
(stream->list
 (stream-take
  (iterator->stream
   (lambda (next end)
     (let loop ((n 0)) (next n) (loop (+ n 1)))))
  10))
 @result{} (0 1 2 3 4 5 6 7 8 9)
@end example
@end defun

@defmac stream-of elt-expr clause @dots{}
[R7RS stream]
@{@t{util.stream}@}
Stream comprehension.  Returns a stream in which each element
is computed by @var{elt-expr}.   
The @var{clause} creates scope of @var{elt-expr}
and controls iterations.  Each @var{clause} can be one of the following
forms:
@table @code
@item (@var{x} in @var{stream-expr})
Iterate over @var{stream-expr}, binding @var{x} to each element in
each iteration.  The variable @var{x} is visible in successive @var{clause}s
and @var{elt-expr}
@item (@var{x} is @var{expr})
Bind a variable @var{x} with the value of @var{expr}.  The variable @var{x}
is visible in successive @var{clause}s
and @var{elt-expr}.
@item expr
If @var{expr} evaluates to @code{#f}, this iteration is skipped without
generating a new element.
@end table

The following comprehension generates infinite sequence of pythagorean
triples:

@example
(define pythagorean-triples
  (stream-of (list a b c)
    (c in (stream-from 3))
    (b in (stream-range 2 c))
    (a in (stream-range 1 b))
    (= (square c) (+ (square b) (square a)))))

(stream->list 5 pythagorean-triples)
  @result{} ((3 4 5) (6 8 10) (5 12 13) (9 12 15) (8 15 17))
@end example
@end defmac

@node Stream binding, Stream consumers, Stream constructors, Stream library
@subsection Stream binding

@defmac define-stream (name . formals)  body body2 @dots{}
[R7RS stream]
@{@t{util.stream}@}
A convenient macro to define a procedure that yields a stream.
Same as the following form:

@example
(define (name . formals)
  (stream-delay
    (let () body body2 @dots{})))
@end example
@end defmac

@defmac stream-let loop-var ((var init) @dots{}) body body2 @dots{}
[R7RS stream]
@{@t{util.stream}@}
A handy macro to write a lazy named-let loop.  It is the same as the
following:
@example
(let loop-var ((var init) @dots{})
  (stream-delay
    (let () body body2 @dots{})))
@end example
@end defmac

@defmac stream-match stream-expr clause @dots{}
[R7RS stream]
@{@t{util.stream}@}
This allows accessing streams via simple pattern matching.
The @var{stream-expr} argument is evaluated and must yield a stream.
Each @var{clause}
must be either a form of @code{(@var{pattern} @var{expr})} or
@code{(@var{pattern} @var{fender} @var{expr})}.

The content of the stream is matched to each @var{pattern},
which must have one of the following forms:

@table @code
@item ()
Matches a null stream.
@item (@var{p0} @var{p1} @dots{})
Matches a stream that has exactly the same number of elements as
the number of pattern elements.
@item (@var{p0} @var{p1} @dots{} . @var{pRest})
Matches a stream that has at least the same number of elements as
the number of pattern elements except @var{pRest}.  The rest of stream
matches with @var{pRest}.
@item @var{pRest}
Matches an entire stream.
@end table

Each pattern element can be an identifier or a literal underscore.  If it is
an identifier, it is bound to the matched element while evaluating
the corresponding @var{fender} and @var{expr}.

If @var{fender} is present in the @var{clause}, it is evaluated; if
it yields @code{#f}, the match of the clause fails and next clauses will be
tried.

Otherwise, @var{expr} is evaluated and the result(s) becomes the result(s)
of @code{stream-match}.

Only the elements from the stream that is required to match are accessed.

The following example defines a procedure to count the number of true
values in the stream:

@example
(define (num-trues strm)
  (stream-match strm
    (() 0)
    ((head . tail) head (+ 1 (num-trues tail)))
    ((_ . tail) (num-trues tail))))

(num-trues (stream #f #f #t #f #t #f #t #t))
  @result{} 4
@end example
@end defmac

@node Stream consumers, Stream operations, Stream binding, Stream library
@subsection Stream consumers

These procedures takes stream(s) and consumes its/their elements
until one of the streams is exhausted.

@defun stream-for-each func . streams
[R7RS stream]
@{@t{util.stream}@}
Applies @var{func} for each element of @var{streams}.
Terminates if one of @var{streams} reaches the end.
@end defun

@defun stream-fold f seed stream
[R7RS stream]
@{@t{util.stream}@}
Apply @var{f} on the current seed value and an element from
@var{stream} to obtain the next seed value, and repeat it until
@var{stream} is exhausted, then returns the last seed value.
The initial seed value is given by @var{seed}.

Note: The argument order of @var{f} differs from other @code{*-fold}
procedures, e.g. @code{fold} (@pxref{Walking over lists}) takes
the element first, then the seed value.

@example
(stream-fold - 0 (stream 1 2 3 4 5))
  @result{} -15
@end example
@end defun

@node Stream operations,  , Stream consumers, Stream library
@subsection Stream operations

@defun stream-append stream @dots{}
[R7RS stream]
@{@t{util.stream}@}
Returns a new stream which is concatenation of given @var{stream}s.
@end defun

@defun stream-concat streams
@defunx stream-concatenate streams
[R7RS stream]
@{@t{util.stream}@}
R7RS @code{scheme.stream} defines @code{stream-concat}.  Gauche had
@code{stream-concatenate}, and keeps it for the backward compatibility.
Both are the same.

The @var{streams} argument is a stream of streams.  Returns a new stream
that is concatenation of them.  Unlike @code{stream-append}, @var{streams}
can generate infinite streams.
@end defun


@defun stream-map func stream stream2 @dots{}
[R7RS stream]
@{@t{util.stream}@}
Returns a new stream, whose elements are calculated by
applying @var{func} to each element of @var{stream} @dots{}.
@end defun

@defun stream-scan func seed stream
[R7RS stream]
@{@t{util.stream}@}
Returns a stream of @code{@var{seed}}, @code{(@var{func} @var{seed} @var{e0})},
@code{(@var{func} (@var{func} @var{seed} @var{e0}) @var{e1})}, @dots{}, where
@var{e0}, @var{e1} @dots{} are the elements from the input @var{stream}.
If @var{stream} is finite, the result stream has one more elements than
the number of elements in the original stream.

@example
(stream->list
  (stream-scan xcons '() (stream 1 2 3 4 5)))
 @result{} (() (1) (2 1) (3 2 1) (4 3 2 1) (5 4 3 2 1))
@end example
@end defun

@defun stream-zip stream @dots{}
[R7RS stream]
@{@t{util.stream}@}
Returns a new stream whose elements are lists of corresponding
elements from input @var{stream}s.  The output stream ends
when one of input streams is exhausted.

@example
(stream->list
 (stream-zip (stream 1 2 3) (stream 'a 'b 'c 'd)))
 @result{} ((1 a) (2 b) (3 c))
@end example

@end defun

@defun stream-filter pred stream
[R7RS stream]
@{@t{util.stream}@}
Returns a new stream including only elements passing @var{pred}.
@end defun

@defun stream-remove pred stream
@{@t{util.stream}@}
Returns a new stream including only elements that doesn't satisfy @var{pred}.
@end defun

@defun stream-partition pred stream
@{@t{util.stream}@}
Returns two streams, one consists of the elements in @var{stream}
that satisfy @var{pred}, the other consists of the ones that doesn't
satisfy @var{pred}.
@end defun

@defun stream->list stream
@defunx stream->list n stream
[R7RS stream]
@{@t{util.stream}@}
Converts a stream to a list.  In the first form, all elements from
@var{stream} are taken (thus it never returns if @var{stream} is infinite).
In the second form, at most @var{n} elements are taken, where
@var{n} must be a nonnegative exact integer.

Note: In usual Scheme conventions, the optional @var{n} comes after
the main argument (@var{stream}).
@end defun

@defun stream->string stream
@{@t{util.stream}@}
Converts a stream to a string.
All elements of @var{stream} must be characters, or an error is signaled.
@end defun


@defun stream-lines stream
@{@t{util.stream}@}
Splits @var{stream} where its element equals to @code{#\n}, and
returns a stream of splitted streams.  The character @code{#\n} won't
be included in the results.

@example
(stream->list
 (stream-map stream->string
             (stream-lines (string->stream "abc\ndef\nghi"))))
 @result{} ("abc" "def" "ghi")
@end example
@end defun

@defun stream= elt= stream @dots{}
@{@t{util.stream}@}
Returns true iff each corresponding element of @var{stream} @dots{}
are the same in terms of @var{elt=}, which takes two arguments.
This procedure won't terminate
if all of @var{stream}s is infinite.
@end defun

@defun stream-prefix= stream prefix :optional elt=
@{@t{util.stream}@}
Compares initial elements of @var{stream} against
a list @var{prefix} by @var{elt=}.  Returns true iff they match.
Only as many elements of @var{stream}
as @var{prefix} has are checked.
@end defun

@defun stream-caar s
@defunx stream-cadr s
@findex stream-cdar
@findex stream-cddr
@findex stream-caaar
@findex stream-caadr
@findex stream-cadar
@findex stream-caddr
@findex stream-cdaar
@findex stream-cdadr
@findex stream-cddar
@findex stream-cdddr
@findex stream-caaaar
@findex stream-caaadr
@findex stream-caadar
@findex stream-caaddr
@findex stream-cadaar
@findex stream-cadadr
@findex stream-caddar
@findex stream-cadddr
@findex stream-cdaaar
@findex stream-cdaadr
@findex stream-cdadar
@findex stream-cdaddr
@findex stream-cddaar
@findex stream-cddadr
@dots{}
@end defun
@defun stream-cdddar s
@defunx stream-cddddr s
@{@t{util.stream}@}
@code{(stream-caar s)} = @code{(stream-car (stream-car s))} etc.
@end defun

@defun stream-ref stream pos
[R7RS stream]
@{@t{util.stream}@}
Returns the @var{pos}-th element in the stream.  @var{Pos}
must be a nonnegative exact integer.
@end defun

@defun stream-first s
@defunx stream-second s
@defunx stream-third s
@defunx stream-fourth s
@defunx stream-fifth s
@defunx stream-sixth s
@defunx stream-seventh s
@defunx stream-eighth s
@defunx stream-ninth s
@defunx stream-tenth s
@{@t{util.stream}@}
@code{(stream-first s)} = @code{(stream-ref s 0)} etc.
@end defun

@defun stream-take stream count
@defunx stream-take-safe stream count
@{@t{util.stream}@}
Returns a new stream that consists of the first @var{count} elements
of the given stream.   If the given stream has less than
@var{count} elements, the stream returned by @code{stream-take}
would raise an error when the elements beyond the original stream
is accessed.  On the other hand, the stream returned by
@code{stream-take-safe} will return a shortened stream when
the given stream has less than @var{count} elements.

@example
(stream->list (stream-take (stream-iota -1) 10))
 @result{} (0 1 2 3 4 5 6 7 8 9)

(stream-take (stream 1 2) 5)
 @result{} @r{stream}

(stream->list (stream-take (stream 1 2) 5))
 @result{} @r{error}

(stream->list (stream-take-safe (stream 1 2) 5))
 @result{} (1 2)
@end example

Note: srfi-41 (@code{scheme.stream}) also defines @code{stream-take}, but
the argument order is reversed, and also it allows @var{stream} to have
less than @code{count} elements.
@end defun

@defun stream-drop stream count
@defunx stream-drop-safe stream count
@{@t{util.stream}@}
Returns a new stream that consists of the elements in the given
stream except the first @var{count} elements.
If the given stream has less than @var{count} elements,
@code{stream-drop} returns a stream that raises an error
if its element is accessed, and @code{stream-drop-safe}
returns an empty stream.

Note: srfi-41 (@code{scheme.stream}) also defines @code{stream-drop}, but
the argument order is reversed, and also it allows @var{stream} to have
less than @code{count} elements.
@end defun

@defun stream-intersperse stream element
@{@t{util.stream}@}
Returns a new stream in which @var{element} is
inserted between elements of @var{stream}.
@end defun

@defun stream-split stream pred
@{@t{util.stream}@}
Split @var{stream} on elements that satisfy @var{pred},
and returns a stream of splitted streams.  The delimiting element
won't be included in the result.
@end defun

@defun stream-last stream
@{@t{util.stream}@}
Returns the last element of @var{stream}.  If @var{stream} is infinite,
this procedure won't return.
@end defun

@defun stream-last-n stream count
@{@t{util.stream}@}
Returns a stream that contains the last @var{count} elements
in @var{stream}.  The @var{count} argument must be a nonnegative exact
integer.  If the length of @var{stream} is smaller than @var{count},
the resulting stream is the same as @var{stream}.
If @var{stream} is infinite,
this procedure won't return.
@end defun

@defun stream-butlast stream
@{@t{util.stream}@}
Returns a stream which is the same as @var{stream} but without the
last element.  If @var{stream} is empty, an empty stream is returned.
@end defun

@defun stream-butlast-n stream count
@{@t{util.stream}@}
Returns a stream which is the same as @var{stream} but without the
last @var{count} elements.  The @var{count} argument must be a nonnegative exact
integer.  If @var{stream} is shorter than @var{count}, a null stream
is returned.
@end defun

@defun stream-length stream
[R7RS stream]
@{@t{util.stream}@}
Returns the number of elements in @var{stream}.  It diverges if @var{stream}
is infinite.
@end defun

@defun stream-length>= stream n
@defunx stream-length= stream n
@{@t{util.stream}@}
Returns true iff the length of @var{stream} is greater than or equal to,
and exactly equal to, @var{n}, respectively.
These procedures only realizes @var{stream} up to @var{n} elements.
@end defun

@defun stream-reverse stream :optional tail-stream
[R7RS stream]
@{@t{util.stream}@}
Returns a stream that returns the elements of @var{stream} in reverse order.
If @var{tail-stream} is given, it is added after the reversed stream.

The optional argument is Gauche's extension.  The description of @code{reverse}
(@pxref{Other list procedures}) for more details.
@end defun

@defun stream-count pred stream @dots{}
@{@t{util.stream}@}
@end defun

@defun stream-find pred stream
@{@t{util.stream}@}
@end defun

@defun stream-find-tail pred stream
@{@t{util.stream}@}
@end defun

@defun stream-take-while pred stream
[R7RS stream]
@{@t{util.stream}@}
@end defun

@defun stream-drop-while pred stream
[R7RS stream]
@{@t{util.stream}@}
@end defun

@defun stream-span pred stream
@{@t{util.stream}@}
@end defun

@defun stream-break pred stream
@{@t{util.stream}@}
@end defun

@defun stream-any pred stream @dots{}
@{@t{util.stream}@}
@end defun

@defun stream-every pred stream @dots{}
@{@t{util.stream}@}
@end defun

@defun stream-index pred stream @dots{}
@{@t{util.stream}@}
@end defun

@defun stream-member obj stream :optional elt=
@defunx stream-memq obj stream
@defunx stream-memv obj stream
@{@t{util.stream}@}
@end defun

@defun stream-delete obj stream :optional elt=
@{@t{util.stream}@}
@end defun

@defun stream-delete-duplicates stream :optional elt=
@{@t{util.stream}@}
@end defun

@defun stream-grep re stream
@{@t{util.stream}@}
@end defun

@defun write-stream stream :optional oport writer
@{@t{util.stream}@}
@end defun

@c ----------------------------------------------------------------------
@node Topological sort, Unification, Stream library, Library modules - Utilities
@section @code{util.toposort} - Topological sort
@c NODE トポロジカルソート, @code{util.toposort} - トポロジカルソート

@deftp {Module} util.toposort
@mdindex util.toposort
Implements topological sort algorithm.
@end deftp

@defun topological-sort graph :optional eqproc
@{@t{util.toposort}@}
@var{Graph} represents a directed acyclic graph (DAG) by a list
of connections, where each connection is the form
@example
(<node> <downstream> <downstream2> ...)
@end example
that means a node @code{<node>} is connected to other nodes
@code{<downstream>} etc.   @code{<node>} can be arbitrary
object, as far as it can be compared by the procedure @var{eqproc},
which is @var{eqv?} by default (@pxref{Equality}).
Returns a list of @code{<node>}s sorted topologically.

If the graph contains circular reference, an error is signaled.
@end defun

@c ----------------------------------------------------------------------
@node Unification, CGI utility, Topological sort, Library modules - Utilities
@section @code{util.unification} - Unification
@c NODE ユニフィケーション, @code{util.unification} - ユニフィケーション

@deftp {Module} util.unification
@mdindex util.unification
Implements unification algorithm.

The base API operates on abstract trees, while it is
agnostic to the actual representation of the tree.
The caller passes comparators and operators along the trees
to unify.

We assume the abstract tree has the following structure:

@example
Tree : Variable | Value | Tuple
Tuple : @{ Tree ... @}
@end example

Here, @code{@{...@}} just represents a sequence of trees.

A variable can be bound to a tree.  A value can only match itself.

To operate on this tree, we need the following comparators and procedures,
which the API takes as arguments:

@table @asis
@item Variable comparator: @code{var-cmpr}
A comparator to see if an item is a variable, and also
check equality of two variables.  It must be hashable.
@xref{Basic comparators}, for the details of comparators.
@item Value comparator: @code{val-cmpr}
A comparator to see if an item is a value, and also
check equality of two values.
Note that if a tree satisfies neither @var{var-cmpr} nor @var{val-compr},
it is regarded as a tuple.
@item Tuple folder: @code{tuple-fold}
A procedure @code{(tuple-folde proc seed tuple1 [tuple2])}. 
This procedure should work like @code{fold} (@pxref{Walking over lists})
over the elements in the tuple(s).  It is only called with
either one or two tuples.
@item Tuple constructor: @code{make-tuple}
A procedure @code{(make-tuple proto elements)}, where
@var{proto} is a tuple and @var{elements} are a list of trees.  
It must return a new tuple with the given elements,
while all other properties are the same as @var{proto}.
This procedure isn't needed by @code{unify}.
@end table
@end deftp

@defun unify a b var-cmpr val-cmpr tuple-fold
@{@t{util.unification}@}
Unify two trees @var{a} and @var{b} and returns a substitution
dictionary, which is a dictionary that maps variables
to its bounded trees.

See the entry of @code{util.unification} above for the description
of @var{var-cmpr}, @var{val-cmpr} and @var{tuple-fold}.

@example
(dict->alist (unify '(a 3 (c b)) '(c b (2 e))
                    symbol-comparator
                    number-comparator
                    fold))
 @result{} ((e . 3) (a . c) (b . 3) (c . 2))
@end example

As you can see in the example above, 
a variable may be mapped to another variable, or even to 
a tree that contains variables.  If you apply the substitution
to the original tree, you must do it recursively until all the
variables in the dictionary is eliminated.

If two trees cannot be unified, @code{#f} is returned.

@example
(unify '(a (a)) '(x x) symbol-comparator number-comparator fold)
 @result{} #f
@end example

@end defun

@defun unify-merge a b var-cmpr val-cmpr tuple-fold make-tuple
@{@t{util.unification}@}
Unify two trees @var{a} and @var{b}, and apply the result substitutions
to create a new tree eliminating variables.

See the entry of @code{util.unification} above for the description
of @var{var-cmpr}, @var{val-cmpr}, @var{tuple-fold} and
@var{make-tuple}.

@example
(unify-merge '(a 3 (c b)) '(c b (2 e))
             symbol-comparator
             number-comparator
             fold
             (^[_ elts] elts))
 @result{} (2 3 (2 3))
@end example

If two trees can't be unified, @code{#f} is returned.
@end defun


@c ----------------------------------------------------------------------
@node CGI utility, CGI testing, Unification, Library modules - Utilities
@section @code{www.cgi} - CGI utility
@c NODE CGIユーティリティ, @code{www.cgi} - CGIユーティリティ

@deftp {Module} www.cgi
@mdindex www.cgi
Provides a few basic functions useful to write a CGI script.

In order to write CGI script easily, you may want to use
other modules, such as @code{rfc.uri} (@pxref{URI parsing and construction}),
@code{text.html-lite} (@pxref{Simple HTML document construction}) and
@code{text.tree} (@pxref{Lazy text construction}).

Note: it seems that there is no active formal specification for CGI.
See @uref{http://w3c.org/CGI/} for more information.
@end deftp

@subheading Metavariables

@deffn {Parameter} cgi-metavariables :optional metavariables
@{@t{www.cgi}@}
Normally, httpd passes a cgi program various information
via environment variables.
Most procedures in @code{www.cgi} refer to them (meta-variables).
However, it is sometimes inconvenient to require environment variable access
while you're developing cgi-related programs.
With this parameter, you can overrides the information of meta-variables.

@var{Metavariables} should be a list of two-element lists.
Car of each inner list names the variable, and its cadr gives the
value of the variable by string.

For example, the following code overrides @code{REQUEST_METHOD}
and @code{QUERY_STRING} meta-variables during execution of
@code{my-cgi-procedure}.  (@xref{Parameters},
for the details of @code{parameterize}).

@example
(parameterize ((cgi-metavariables '(("REQUEST_METHOD" "GET")
                                    ("QUERY_STRING" "x=foo"))))
  (my-cgi-procedure))
@end example
@end deffn

@defun cgi-get-metavariable name
@{@t{www.cgi}@}
Returns a value of cgi metavariable @var{name}.
This function first searches the parameter @code{cgi-metavariables},
and if the named variable is not found, calls @code{sys-getenv}.

CGI scripts may want to use @code{cgi-get-metavariable} instead
of directly calling @code{sys-getenv}; doing so makes reuse of
the script easier.
@end defun

@subheading Parameter extraction

@defun cgi-parse-parameters :key :query-string :merge-cookies :part-handlers
@{@t{www.cgi}@}
Parses query string and returns associative list of parameters.
When a keyword argument @var{query-string} is given, it is used
as a source query string.  Otherwise, the function checks the
metavariable @code{REQUEST_METHOD} and obtain the query string
depending on the value (either from stdin or from the
metavariable @code{QUERY_STRING}).
If such a metavariable is not defined and
the current input port is a terminal, the function prompts the user
to type parameters; it is useful for interactive debugging.

If @code{REQUEST_METHOD} is @code{POST}, this procedure can handle
both @code{application/x-www-form-urlencoded} and
@code{multipart/form-data} as the enctype.  The latter is usually
used if the form has file-uploading capability.

When the post data is sent by @code{multipart/form-data},
each content of the part is treated as a value of the parameter.
That is, the content of uploaded file will be seen as one big
chunk of a string.  The other information, such as the original file
name, is discarded.   If it is not desirable to read entire file
into a string, you can customize the behavior by the @var{part-handler}
argument.  The details are explained in the "Handling file uploads"
section below.

When a true value is given to @var{merge-cookies}, the cookie
values obtained from the metavariable @code{HTTP_COOKIE}
are appended to the result.

Note that the query parameter may have multiple values,
so @code{cdr} of each element in the result is a list, not an atom.
If no value is given to the parameter, @code{#t} is placed as its value.
See the following example:
@example
(cgi-parse-parameters
  :query-string "foo=123&bar=%22%3f%3f%22&bar=zz&buzz")
 @result{} (("foo" "123") ("bar "\"??\"" "zz") ("buzz" #t))
@end example
@end defun


@defun cgi-get-parameter name params :key :default :list :convert
@{@t{www.cgi}@}
A convenient function to obtain a value of the parameter @var{name} from
parsed query string @var{params}, which is the value
@code{cgi-parse-parameters} returns.  @var{Name} should be a string.

Unless true value is given to @var{list}, the returned value is
a scalar value.  If more than one value is associated to @var{name},
only the first value is returned.  If @var{list} is true, the
returned value is always a list, even @var{name} has only one value.

After the value is retrieved, you can apply a procedure to
convert the string value to the appropriate type by giving
a procedure to the @var{convert} argument.  The procedure must
take one string argument.  If @var{list} is true, the convert
procedure is applied to each values.

If the parameter @var{name} doesn't appear in the query,
a value given to the keyword argument @var{default} is returned;
the default value of @var{default}
is @code{#f} if @var{list} is false, or @code{()} otherwise.
@end defun

@subheading Output generation


@defun cgi-header :key status content-type location cookies
@{@t{www.cgi}@}
Creates a text tree (@pxref{Lazy text construction}) for the
HTTP header of the reply message.  The most simple form is
like this:
@example
(tree->string (cgi-header))
  @result{} "Content-type: text/html\r\n\r\n"
@end example

You can specify alternative content-type by the keyword argument
@var{content-type}.   If you want to set cookies to the client,
specify a list of cookie strings to the keyword argument @var{cookies}.
You can use @code{construct-cookie-string} (@pxref{HTTP cookie handling})
to build such a list of cookie strings.

The keyword argument @var{location} may be used to generate
a @code{Location:} header to redirect the client to the specified URI.
You can also specify the @code{Status:} header by the keyword argument
@var{status}.   A typical way to redirect the client is as follows:

@example
(cgi-header :status "302 Moved Temporarily"
            :location target-uri)
@end example

@end defun

@deffn {Parameter} cgi-output-character-encoding :optional encoding
@{@t{www.cgi}@}
The value of this parameter specifies the character encoding scheme (CES)
used for CGI output by @code{cgi-main} defined below.
The default value is Gauche's native encoding.
If the parameter is set other than the native encoding, @code{cgi-main}
converts the output
encoding by @code{gauche.charconv} module
(@pxref{Character code conversion}).
@end deffn


@subheading Convenience procedures

@defun cgi-main proc :key on-error merge-cookies output-proc part-handlers
@{@t{www.cgi}@}
A convenient wrapper function for CGI script.
This function calls @code{cgi-parse-parameters}, then calls
@var{proc} with the result of @code{cgi-parse-parameters}.
The keyword argument @var{merge-cookies} is passed to
@code{cgi-parse-parameters}.

@var{proc} has to return a tree of strings
(@pxref{Lazy text construction}), including the HTTP header.
@code{cgi-main} outputs the returned tree to the current output port
by @code{write-tree}, then returns zero.

If an error is signaled in @var{proc}, it is caught and an HTML
page reporting the error is generated.  You can customize the
error page by providing a procedure to the @var{on-error} keyword argument.
The procedure takes an @code{<condition>} object (@pxref{Conditions}),
and has to return a tree of string for the error reporting HTML
page, including an HTTP header.

When output the result, @code{cgi-main} refers to
the value of the parameter @code{cgi-output-character-encoding},
and converts the character encoding if necessary.

The output behavior of @code{cgi-main} can be customized
by a keyword argument @var{output-proc}; if it is given,
the text tree (either the normal return value of @var{proc},
or an error page constructed by the error handler) is passed
to the procedure given to @var{output-proc}.  The procedure
is responsible to format and output a text to the current
output port, including character conversions, if necessary.

The keyword argument @var{part-handlers} are simply passed to
@code{cgi-parse-parameters}, by which you can customize
how the file uploads should be handled.  See the "Handling file
uploads" section below for the details.

If you specify to use temporary file(s) by it, @code{cgi-main}
makes sure to clean up them whenever @var{proc} exits,
even by error.   See @code{cgi-add-temporary-file} below
to utilize this feature for other purpose.

Before calling @var{proc}, @code{cgi-main} changes the buffering mode
of the current error port to @code{:line} (See @code{port-buffering}
in @ref{Common port operations} for the details about the buffering mode).
This makes the error output easier for web servers to capture.

The following example shows the parameters given to the CGI program.

@example
#!/usr/local/bin/gosh

(use text.html-lite)
(use www.cgi)

(define (main args)
  (cgi-main
    (lambda (params)
      `(,(cgi-header)
        ,(html-doctype)
        ,(html:html
          (html:head (html:title "Example"))
          (html:body
           (html:table
            :border 1
            (html:tr (html:th "Name") (html:th "Value"))
            (map (lambda (p)
                   (html:tr
                    (html:td (html-escape-string (car p)))
                    (html:td (html-escape-string (x->string (cdr p))))))
                 params))))
       ))))
@end example
@end defun


@defun cgi-add-temporary-file filename
@{@t{www.cgi}@}
This is supposed to be called inside @var{proc} of @code{cgi-main}.
It registers @var{filename} as a temporary file, which should be
unlinked when @var{proc} exits.  It is a convenient way to ensure
that your cgi script won't leave garbages even if it throws an error.
It is OK in @var{proc} to unlink or rename @var{filename} after
calling this procedure.
@end defun

@deffn {Parameter} cgi-temporary-files
@{@t{www.cgi}@}
Keeps a list of filenames registered by @code{cgi-add-temporary-file}.
@end deffn

@subheading Handling file uploads

As explained in @code{cgi-parse-parameters} above, file uploads
are handled transparently by default, taking the file content
as the value of the parameter.   Sometimes you might want to change this
behavior, for the file might be quite big and you don't want
to keep around a huge chunk of a string in memory.  It is possible to
customize handling of file uploads of @code{cgi-parse-parameters}
and @code{cgi-main} by @var{part-handlers} argument.
(The argument is only effective for the form data submitted by
@code{multipart/form-data} enctype)

The @var{part-handlers} argument is, if given, a list of lists;
each inner list is a form of
@code{(@var{name-pattern} @var{action} @var{kv-list} @dots{})}.
Each uploaded file with a matching parameter name with @var{name-pattern} is
handled according to @var{action}.  (Here, a parameter name
is the 'name' attribute given to the @code{input} element in the
submitted form, not the name of the uploaded file).

@var{Name-pattern} must be either a list of string (matches one of them),
a regexp, or @code{#t} (matches anything).

@var{Action} must be either one of the followings:
@table @code
@item #f
Default action, i.e. the content of the uploaded file is turned into
a string and becomes the value of the parameter.
@item ignore
The uploaded content is discarded.
@item file
The uploaded content is saved in a temporary file.  The value of
the parameter is the pathname of the temporary file.

For this action, you can write an entry like
@code{(@var{name-pattern} file @var{prefix})}, to specify the
prefix of the pathname of the temporary file.  For example, if you
specify @code{("image" file "/var/mycgi/incoming/img")},
the file uploaded as @code{"image"} parameter will be stored as
something like @file{/var/mycgi/incoming/img49g2Ua}.

The application should move the temporary file to appropriate
location; if you're using @code{cgi-main}, the temporary files
created by this action will be unlinked when @code{cgi-main} exits.

@item file+name
Like @code{file}, but the value of the parameter is a list of
temporary filename and the filename passed by the client.
It is useful if you want to use client's filename (but do not
blindly assume the client sends a valid pathname; for example,
you shouldn't use it to rename the uploaded file without
validating it).

@item @var{procedure}
In this case, @var{procedure} is called to handle the uploaded
contents.  It is called with four arguments:
@code{(procedure @var{name} @var{filename} @var{part-info} @var{iport})}.

@var{Name} is the name of the parameter.  @var{Filename} is
the name of the original file (pathname in the client).
@var{Part-info} is a @code{<mime-part>} object that keeps information
about this mime part,  and @var{iport} is where the body can be
read from.
For the details about these arguments,
see @ref{MIME message handling}; you might be able to
use procedures provided by @code{rfc.mime}, such as @code{mime-retrieve-body},
to construct your own procedure.

If you create a temporary file in @var{procedure}, you can call
@code{cgi-add-temporary-file} to make sure it is removed even if
an error occurs during cgi processing.
@end table

If @var{kv-list} is given after @var{action}, it must be a
keyword-value list and further modifies action.  The following
keywords are supported.

@table @code
@item :prefix
Valid only if @var{action} is either @code{file} or @code{file+name}.
Specifies the prefix of the temporary file.  If you give
@code{:prefix "/tmp/foo"}, for example, the file is saved
as something like @file{/tmp/fooxAgjeQ}.
@item :mode
Valid only if @var{action} is either @code{file} or @code{file+name}.
Specifies the mode of the temporary file in unix-style integer.  By default
it is @code{#o600}.
@end table


Note that the parameters that are not file uploads are not the subject
of @var{part-handlers}; such parameter values are always turned into a string.


Here's a short example.  Suppose you have a form like this:

@example
<form enctype="multipart/form-data" method="POST" action="mycgi.cgi">
<input type="file" name="imagefile" />
<input type="text" name="description" />
<input type="hidden" name="mode" value="normal" />
</form>
@end example

If you use @code{cgi-parse-parameters} in @file{mycgi.cgi}
without @var{part-handlers} argument,
you'll get something like the following as the result.
(The actual values depend on how the web client filled the form).

@example
(("imagefile" #*".....(image file content as a string)....")
 ("description" "my image")
 ("mode" "normal"))
@end example

If you pass @code{'(("imagefile" file :prefix "/tmp/mycgi"))}
to @var{part-handlers}
instead,
you might get something like the following, with the
content of uploaded file saved in @file{/tmp/mycgi7gq0B}

@example
(("imagefile" "/tmp/mycgi7gq0B")
 ("description" "my image")
 ("mode" "normal"))
@end example

If you use a symbol @code{file+name} instead of @code{file} above,
you'll get something like @code{("/tmp/mycgi7gq0B" "logo.jpg")} as
the value of @code{"imagefile"}, where @code{"logo.jpg"} is the
client-side filename.   (Note: the client can send any string
as the name of the file, so @emph{never} assume it is a valid
pathname).

@c @c EN
@c Now, you pass the following structure to @var{part-handlers}:
@c @c JP
@c 次のような構造を@var{part-handlers}に渡した場合：
@c @c COMMON

@c @example
@c `(("imagefile"
@c   ,(lambda (name fname info iport)
@c      (receive (outp tmpfile) (sys-mkstemp "/var/log/mycgi/tmp")
@c        (mime-retrieve-body info iport outp)
@c        (close-output-port outp)
@c        (cgi-add-temporary-file tmpfile)
@c        (string-append fname ":" tmpfile))))
@c  )
@c @end example

@c @c EN
@c You'll get something like the following; i.e. the cgi application
@c can see the client-side file name as well as the temporary file name.
@c @c JP
@c 例えば次のようなパーズ結果が得られるでしょう。つまり、
@c クライアント側でのファイル名も参照することができます。
@c @c COMMON

@c @example
@c (("imagefile" "logo.jpg:/var/log/mycgi/tmp820iQj")
@c  ("description" "my image")
@c  ("mode" "normal"))
@c @end example


@c ----------------------------------------------------------------------
@node CGI testing, CSS parsing and construction, CGI utility, Library modules - Utilities
@section @code{www.cgi.test} - CGI testing
@c NODE CGIのテスト, @code{www.cgi.test} - CGIのテスト

@deftp {Module} www.cgi.test
@mdindex www.cgi.test
This module defines a useful procedures to test CGI script.
The test actually runs the named script, with specified environment
variable settings, and retrieve the output.  Your test procedure
then examine whether the output is as expected or not.
@end deftp

@defun cgi-test-environment-ref envvar-name
@defunx {(setter cgi-test-environment-ref)} envvar-name value
@{@t{www.cgi.test}@}
The module keeps a table of default values of environment variables
with which the cgi script will be run.  These procedures allow
the programmer to get/set those default values.

Note that you can override these default values and/or pass additional
environment variables for each call of cgi script.
The following environment variables are set by default.
@multitable @columnfractions .5 .5
@item Name @tab Value
@item @code{SERVER_SOFTWARE}
@tab @code{cgitest/1.0}
@item @code{SERVER_NAME}
@tab @code{localhost}
@item @code{GATEWAY_INTERFACE}
@tab @code{CGI/1.1}
@item @code{SERVER_PROTOCOL}
@tab @code{HTTP/1.1}
@item @code{SERVER_PORT}
@tab @code{80}
@item @code{REQUEST_METHOD}
@tab @code{GET}
@item @code{REMOTE_HOST}
@tab @code{remote}
@item @code{REMOTE_ADDR}
@tab @code{127.0.0.1}
@end multitable
@end defun

@defun call-with-cgi-script script proc :key (environment ()) (parameters #f)
@{@t{www.cgi.test}@}
Runs a script with given environment, and calls @var{proc} with
one argument, an input port which is connected to the pipe of script's
standard output.
The argument @var{script} should be a list of
program name and its arguments.  Each element are
passed to @code{x->string} first to stringify.
The script is run under the environment given by @var{environment}
variable and the default test environment described above.
The @var{environment} argument must be an associative list, in which each
key (@code{car}) is the name of the environment variable and
its @code{cdr} is the value.  Both are passed to @code{x->string} first.
If the same environment variable appears in @var{environment} and
the default test environment, the one in @var{environment} is used.
Additionally, if an associative list is given to the @var{parameters}
argument, a query string is built from it and passed the script.
The actual method to pass the query string depends on the value
of @code{REQUEST_METHOD} environment variable in the setting.
If @code{REQUEST_METHOD} is either @code{GET} or @code{HEAD},
the query string is put in an environment variable @code{QUERY_STRING}.
If it is @code{POST}, the query string is fed to the standard
input of the script.  In the latter case, @code{CONTENT_TYPE}
is set to @code{application/x-www-form-urlencoded} and
@code{CONTENT_LENGTH} are set to the length of @code{QUERY_STRING}
automatically.  If @code{REQUEST_METHOD} is other values,
@var{parameters} is ignored.
You can bypass this mechanism and set up environment variable
@code{QUERY_STRING} directly, if you wish.
@end defun

@defun run-cgi-script->header&body script reader :key environment parameters
@{@t{www.cgi.test}@}
A convenient wrapper of @code{call-with-cgi-script}.
The @var{script}, @var{environment} and @var{parameters} are passed
to @code{call-with-cgi-script} as they are.
The output of the script is parsed by
@code{run-cgi-script->header&body}.
First, the RFC2822 header fields are parsed by
@code{rfc822-read-headers} (@pxref{RFC822 message parsing}).
Then, the @var{reader} is called with an input port which
is piped to the script's output.
@code{Run-cgi-script->header&body} returns two values,
the list of headers (as parsed by @code{rfc822-read-headers}),
and the return value of @var{reader}.
@end defun

@defun run-cgi-script->sxml script :key environment parameters
@{@t{www.cgi.test}@}
This is a procedure that uses @code{ssax:xml->sxml}
(@pxref{Functional XML parser}) as the @var{reader}
in @code{run-cgi-script->header&body}.
Useful when you're testing a cgi script that produces
well-formed HTML and/or XML document.
@end defun

@defun run-cgi-script->string script :key environment parameters
@defunx run-cgi-script->string-list script :key environment parameters
@{@t{www.cgi.test}@}
These procedures use @code{port->string}
and @code{port->string-list}
(@pxref{Input utility functions}) as the @var{reader}
in @code{run-cgi-script->header&body}, respectively.
@end defun

An example:
@example
(run-cgi-script->string-list "bbs.cgi"
                             :environment '((REMOTE_ADDR . "12.34.56.78"))
                             :parameters '((command . "view")
                                           (page . 1234)))
@end example


@c ----------------------------------------------------------------------
@node CSS parsing and construction,  , CGI testing, Library modules - Utilities
@section @code{www.css} - CSS parsing and construction
@c NODE CSSのパーズと構築, @code{www.css} - CSSのパーズと構築

@deftp {Module} www.css
This module provides tools to convert between S-expression and CSS.

The S-expression CSS (SxCSS) is a convenient way to manipulate
CSS in Scheme.
@end deftp

For example, the following CSS and SxCSS are equivalent, and
can be converted back and forth:

CSS:
@example
body @{ padding-left: 11em;
       font-family: Georgia, "Times New Roman", Times, serif;
       color: purple;
       background-color: #d8da3d @}
ul.navbar li @{ background: white;
               margin: 0.5em 0;
               padding: 0.3em;
               border-right: 1em solid black @}
ul#spec > a @{ text-decoration: none @}
a:visited @{ color: purple !important @}
@end example

SxCSS:
@example
((style-rule body
   (padding-left (11 em))
   (font-family (:or Georgia "Times New Roman" Times serif))
   (color purple)
   (background-color (color "d8da3d")))
 (style-rule ((ul (class navbar)) li)
   (background white)
   (margin #((0.5 em) 0))
   (padding (0.3 em))
   (border-right #((1 em) solid black)))
 (style-rule ((ul (id spec)) > a) (text-decoration none))
 (style-rule (a (: visited)) (color purple !important)))
@end example

See the ``CSS in S-expression'' section below for the complete
specification.

@subheading Constructing CSS

@defun construct-css sxcss :optional oport
@{@t{www.css}@}
Take SxCSS and writes out CSS to the given port, defaulted to
the current output port.
@end defun

@subheading Parsing CSS

@defun parse-css :optional iport
@{@t{www.css}@}
@end defun

@defun parse-css-file file :key encoding
@{@t{www.css}@}
Read the CSS text from the given file and parse it using
@code{parse-css}.  Again, we don't handle @code{@@charset} directive
yet, and you have to pass @code{encoding} argument if
the CSS text isn't in the Gauche's native character encoding.
@end defun

@defun parse-css-selector-string str
@{@t{www.css}@}
This parses the selector part of the CSS.

@example
(parse-css-selector-string "ul li.item span#foo")
  @result{} (ul (li (class item)) (span (id foo)))

(parse-css-selector-string "h1,h2")
  @result{} (:or h1 h2)
@end example
@end defun

@subheading CSS in S-expression

The following is the complete rules of SxCSS syntax.

@smallexample
<sxcss>      : (@{<style-rule> | <at-rule>@} ...)

<style-rule> : (style-rule <pattern> <declaration> ...)
             | (style-decls <declaration> ...)

<pattern>   : <selector> | (:or <selector> ...)
<selector>  : <simple-selector>
            | <chained-selector>
<chained-selector> : (<simple-selector> . (<op>? . <chained-selector>))
<op>        : > | + | ~
<simple-selector> : <element-name>
            | (<element-name> <option> ...)
<option>    : (id <name>)                           ; E#id
            | (class <ident>)                       ; E.class
            | (has <ident>)                         ; E[attrib]
            | (= <ident> <attrib-value>)            ; E[attrib=val]
            | (~= <ident> <attrib-value>)           ; E[attrib~=val]
            | (:= <ident> <attrib-value>)           ; E[attrib|=val]
            | (*= <ident> <attrib-value>)           ; E[attrib*=val]
            | (^= <ident> <attrib-value>)           ; E[attrib^=val]
            | ($= <ident> <attrib-value>)           ; E[attrib$=val]
            | (:not <negation-arg>)                 ; E:not(s)
            | (: <ident>)                           ; E:pseudo-class
            | (: (<fn> <ident> ...))                ; E:pseudo-class(arg)
            | (:: <ident>)                          ; E::pseudo-element
<element-name> : <ident> | *
<attrib-value> : <ident> | <string>
<negation-arg> | <element-name> | * | <option>  ; except <negation-arg>

<declaration>  : (<ident> <expr> <expr2> ... <important>?)
<important> : !important
<expr>      : <term>
            | (/ <term> <term> ...)
            | (:or <term> <term> ...)
            | #(<term> <term> ...)             ; juxtaposition
<term>      : <quantity> | (- <quantity>) | (+ <quantity>)
            | <string> | <ident> | <url> | <hexcolor> | <function>
<quantity>  : <number>
            | (<number> %)
            | (<number> <ident>)
<url>       | (url <string>)
<hexcolor>  | (color <string>)  ; <string> must be hexdigits
<function>  | (<fn> <arg> ...)
<arg>       | <term> | #(<term> ...) | (/ <term> <term> ...)

<at-rule>    : <at-media-rule> | <at-import-rule>
                   ; NB: Other at-rules are not supported yet
<at-media-rule>  : (@@media (<symbol> ...) <style-rule> ...)
<at-import-rule> : (@@import <string> (<symbol> ...))
@end smallexample

NB: Negation op is @code{:not} instead of @code{not}, 
since @code{(not <negation-arg>)}
would be ambiguous from the simple node named "not" with one option.

NB: @code{style-decls} selector rule is currently won't appear in
the @code{parse-css} output; it can be used in SxCSS to make
@code{construct-css} render declarations only, which can be
used in the @code{style} attribute of the document, for example.
@example
(with-output-to-string 
 (cut construct-css
      '((style-decls (width (50 %))
                     (padding #(0 (10 pt) 0 (10 pt)))))))
  @result{} "width:50%;padding:0 10pt 0 10pt"
@end example

@c Local variables:
@c mode: texinfo
@c coding: utf-8
@c end:
@node C to Scheme mapping, Function and Syntax Index, Library modules - Utilities, Top
@appendix C to Scheme mapping
@c NODE CとSchemeの関数の対応

For the convenience of the programmers familiar to C,
I composed a simple table of C operators and library functions with
the corresponding Scheme functions.

@table @code
@item +
R7RS arithmetic procedure @code{+}.   @xref{Arithmetics}.
@item +=
Gauche @code{inc!} macro.  @xref{Assignments}.
@item -
R7RS arithmetic procedure @code{-}.   @xref{Arithmetics}.
@item -=
Gauche @code{dec!} macro.  @xref{Assignments}.
@item ->
Gauche @code{slot-ref} is something close to this.  @xref{Accessing instance}.
@item * (binary)
R7RS arithmetic procedure @code{*}.   @xref{Arithmetics}.
@item * (unary)
No equivalent procedure.  Scheme doesn't have explicit notation of
pointers.
@item *=
No equivalent procedure.
@item /
In C, it has two different meanings depending on the types
of operands.  For real division, use @code{/}.
For integer quotient, use @code{quotient}.
@xref{Arithmetics}.
@item /=
No equivalent procedure.
@item & (binary)
Gauche @code{logand}.  @xref{R7RS bitwise operations}.
@item & (unary)
No equivalent procedure.  Scheme doesn't have explicit notation of
pointers.
@item &&
R7RS syntax @code{and}.  @xref{Conditionals}.
@item &=
No equivalent procedure.
@item |
Gauche @code{logior}.  @xref{R7RS bitwise operations}.
@item ||
R7RS syntax @code{or}.  @xref{Conditionals}.
@item |=
No equivalent procedure.
@item ^
Gauche @code{logxor}.  @xref{R7RS bitwise operations}.
@item =
R7RS syntax @code{set!}.  @xref{Assignments}.
@item ==
R7RS equivalence procedure, @code{eq?}, @code{eqv?} and @code{equal?}.
@xref{Equality}.
@item <
@itemx <=
R7RS arithmetic procedure @code{<} and @code{<=}.
@xref{Numerical comparison}.  Unlike C operator, Scheme version
is transitive.
@item <<
Gauche @code{ash}.  @xref{R7RS bitwise operations}.
@item <<=
No equivalent procedure.
@item >
@itemx >=
R7RS arithmetic procedure @code{>} and @code{>=}.
@xref{Numerical comparison}.  Unlike C operator, Scheme version
is transitive.
@item >>
Gauche @code{ash}.  @xref{R7RS bitwise operations}.
@item >>=
No equivalent procedure.
@item %
R7RS operator @code{modulo} and @code{remainder}.  @xref{Arithmetics}.
@item %=
No equivalent procedure.
@item []
R7RS @code{vector-ref} (@pxref{Vectors}) is something close.
Or you can use Gauche's generic function @code{ref} (@pxref{Sequence framework})
for arbitrary sequences.
@item .
Gauche @code{slot-ref} is something close to this.  @xref{Accessing instance}.
@item ~
Gauche @code{lognot}.  @xref{R7RS bitwise operations}.
@item ~=
No equivalent procedure.
@item !
R7RS procedure @code{not}.  @xref{Booleans}.
@item !=
No equivalent procedure.
@item abort
Gauche @code{sys-abort}.   @xref{Program termination}.
@item abs
R7RS @code{abs}.  @xref{Arithmetics}.
@item access
Gauche @code{sys-access}.  @xref{File stats}.
@item acos
R7RS @code{acos}.  @xref{Arithmetics}.
@item alarm
Gauche @code{sys-alarm}.   @xref{Miscellaneous system calls}.
@item asctime
Gauche @code{sys-asctime}.  @xref{Time}.
@item asin
R7RS @code{asin}.  @xref{Arithmetics}.
@item assert
No equivalent function in Gauche.
@item atan
@itemx atan2
R7RS @code{atan}.  @xref{Arithmetics}.
@item atexit
No equivalent function in Gauche, but the "after" thunk of active
dynamic handlers are called when @code{exit} is called.
@xref{Program termination}, and @xref{Continuations}.
@item atof
@itemx atoi
@itemx atol
You can use @code{string->number}.  @xref{Numerical conversions}.
@item bsearch
You can use SRFI-133's @code{vector-binary-search}.
@xref{R7RS vectors}.
@item calloc
Allocation is handled automatically in Scheme.
@item ceil
R7RS @code{ceiling}.  @xref{Arithmetics}.
@item cfgetispeed
@itemx cfgetospeed
@itemx cfsetispeed
@itemx cfsetospeed
Gauche's @code{sys-cfgetispeed}, @code{sys-cfgetospeed},
@code{sys-cfsetispeed}, @code{sys-cfsetospeed}.  @xref{Terminal control}.
@item chdir
Gauche's @code{sys-chdir}.   @xref{Other file operations}.
@item chmod
Gauche's @code{sys-chmod}.   @xref{File stats}.
@item chown
Gauche's @code{sys-chown}.   @xref{File stats}.
@item clearerr
Not supported yet.
@item clock
No equivalent function in Gauche.  You can use @code{sys-times}
to get information about CPU time.
@item close
You can't directly close the file descriptor, but when you use
@code{close-input-port} or @code{close-output-port}, underlying
file is closed.  Some port-related functions, such as
@code{call-with-output-file}, automatically closes the file
when operation is finished.  The file is also closed when
its governing port is garbage collected.
@xref{Common port operations}.
@item closedir
No equivalent function in Gauche.  You can use
@code{sys-readdir} to read the directory entries at once.
@xref{Directories}.
@item cos
@itemx cosh
@code{cos} and @code{cosh}.  @xref{Arithmetics}.
@item creat
A file is implicitly created by default when you open it for writing.
See @ref{File ports} for more control over the creation of files.
@item ctermid
Gauche @code{sys-ctermid}.  @xref{System inquiry}.
@item ctime
Gauche @code{sys-ctime}.  @xref{Time}.
@item cuserid
No equivalent function.  This is removed from the newer POSIX.
You can use alternative functions, such as @code{sys-getlogin} or
@code{sys-getpwuid} with @code{sys-getuid}.
@item difftime
Gauche @code{sys-difftime}.  @xref{Time}.
@item div
You can use R7RS @code{quotient} and @code{remainder}.
@xref{Arithmetics}.
@item dup
@itemx dup2
Not directly supported, but you can use @code{port-fd-dup!}.
@item execl
@itemx execle
@itemx execlp
@itemx execv
@itemx execve
@itemx execvp
Gauche @code{sys-exec}.  @xref{Process management}.
For higher level interface, @ref{High-level process interface}.
@item exit
@item _exit
Use @code{exit} or @code{sys-exit}, depends on what you need.
@xref{Program termination}.
@item exp
R7RS @code{exp}.  @xref{Arithmetics}.
@item fabs
R7RS @code{abs}.  @xref{Arithmetics}.
@item fclose
You can't directly close the file stream, but when you use
@code{close-input-port} or @code{close-output-port}, underlying
file is closed.  Some port-related functions, such as
@code{call-with-output-file}, automatically closes the file
when operation is finished.  The file is also closed when
its governing port is garbage collected.
@item fcntl
Implemented as @code{sys-fcntl} in @code{gauche.fcntl} module.
@xref{Low-level file operations}.
@item fdopen
Gauche's @code{open-input-fd-port} or @code{open-output-fd-port}.
@xref{File ports}.
@item feof
No equivalent operation, but you can check if an input port
have reached to the end by @code{peek-char} or @code{peek-byte}.
@xref{Reading data}.
@item ferror
Not supported yet.
@item fflush
Gauche's @code{flush}.   @xref{Output}.
@item fgetc
Use @code{read-char} or @code{read-byte}.  @xref{Input}.
@item fgetpos
Use Gauche's @code{port-tell} (@pxref{Common port operations})
@item fgets
Use @code{read-line} or @code{read-string}.    @xref{Input}.
@item fileno
@code{port-file-number}.   @xref{Common port operations}.
@item floor
R7RS @code{floor}.   @xref{Arithmetics}.
@item fmod
Gauche's @code{fmod}.
@item fopen
R7RS @code{open-input-file} or @code{open-output-file}
corresponds to this operation.  @xref{File ports}.
@item fork
Gauche's @code{sys-fork}.   @xref{Process management}.
@item forkpty
Use @code{sys-forkpty}.  @xref{Terminal control}.
@item fpathconf
Not supported.
@item fprintf
Not directly supported, but Gauche's @code{format}
provides similar functionality.  @xref{Output}.
SLIB has @code{printf} implementation.
@item fputc
Use @code{write-char} or @code{write-byte}.  @xref{Output}.
@item fputs
Use @code{display}.  @xref{Output}.
@item fread
Not directly supported.
To read binary numbers, see @ref{Binary I/O}.
If you want to read a chunk of bytes, you may be
able to use @code{read-uvector!}.
@xref{Uvector block I/O}.
@item free
You don't need this in Scheme.
@item freopen
Not supported.
@item frexp
Gauche's @code{frexp}
@item fscanf
Not supported.  For general case, you have to write a parser.
If you can keep the data in S-exp, you can use @code{read}.
If the syntax is very simple, you may be able to utilize
@code{string-tokenize} in @code{srfi-14} (@ref{String library}),
and/or regular expression stuff (@ref{Regular expressions}).
@item fseek
Use Gauche's @code{port-seek} (@pxref{Common port operations})
@item fsetpos
Use Gauche's @code{port-seek} (@pxref{Common port operations})
@item fstat
Gauche's @code{sys-stat}.  @xref{File stats}.
@item ftell
Use Gauche's @code{port-tell} (@pxref{Common port operations})
@item fwrite
Not directly supported.
To write binary numbers, see @ref{Binary I/O}.
If you want to write a chunk of bytes,
you can simply use @code{display} or @code{write-uvector}
(@pxref{Uvector block I/O}).
@item getc
@itemx getchar
Use @code{read-char} or @code{read-byte}.  @xref{Input}.
@item getcwd
Gauche's @code{sys-getcwd}.   @xref{System inquiry}.
@item getdomainname
Gauche's @code{sys-getdomainname}.  @xref{System inquiry}.
@item getegid
Gauche's @code{sys-getegid}.   @xref{System inquiry}.
@item getenv
Gauche's @code{sys-getenv}.   @xref{Environment inquiry}.
@item geteuid
Gauche's @code{sys-geteuid}.   @xref{System inquiry}.
@item gethostname
Gauche's @code{sys-gethostname}.  @xref{System inquiry}.
@item getgid
Gauche's @code{sys-getgid}.   @xref{System inquiry}.
@item getgrgid
@itemx getgrnam
Gauche's @code{sys-getgrgid} and @code{sys-getgrnam}.  @xref{Unix groups and users}.
@item getgroups
Gauche's @code{sys-getgroups}.   @xref{System inquiry}.
@item getlogin
Gauche's @code{sys-getlogin}.  @xref{System inquiry}.
@item getpgrp
Gauche's @code{sys-getpgrp}.   @xref{System inquiry}.
@item getpid
@itemx getppid
Gauche's @code{sys-getpid}.   @xref{System inquiry}.
@item getpwnam
@itemx getpwuid
Gauche's @code{sys-getpwnam} and @code{sys-getpwuid}.  @xref{Unix groups and users}.
@item gets
Use @code{read-line} or @code{read-string}.  @xref{Input}.
@item gettimeofday
Gauche's @code{sys-gettimeofday}.   @xref{Time}.
@item getuid
Gauche's @code{sys-getuid}.  @xref{System inquiry}.
@item gmtime
Gauche's @code{sys-gmtime}.   @xref{Time}.
@item isalnum
Not directly supported, but you can use R7RS @code{char-alphabetic?} and
@code{char-numeric?}.  @xref{Characters}.   You can also use
character set.  @xref{Character sets}, also @ref{R7RS character sets}.
@item isalpha
R7RS @code{char-alphabetic?}.  @xref{Characters}.  See also
@ref{Character sets} and @ref{R7RS character sets}.
@item isatty
Gauche's @code{sys-isatty}.   @xref{Other file operations}.
@item iscntrl
Not directly supported, but you can use
@code{(char-set-contains? char-set:iso-control c)} with @code{srfi-14}.
@xref{R7RS character sets}.
@item isdigit
R7RS @code{char-numeric?}.  @xref{Characters}.
You can also use @code{(char-set-contains? char-set:digit c)}
with @code{srfi-14}.   @xref{R7RS character sets}.
@item isgraph
Not directly supported, but you can use
@code{(char-set-contains? char-set:graphic c)} with @code{srfi-14}.
@xref{R7RS character sets}.
@item islower
R7RS @code{char-lower-case?}.  @xref{Characters}.
You can also use @code{(char-set-contains? char-set:lower-case c)}
with @code{srfi-14}.   @xref{R7RS character sets}.
@item isprint
Not directly supported, but you can use
@code{(char-set-contains? char-set:printing c)} with @code{srfi-14}.
@xref{R7RS character sets}.
@item ispunct
Not directly supported, but you can use
@code{(char-set-contains? char-set:punctuation c)} with @code{srfi-14}.
@xref{R7RS character sets}.
@item isspace
R7RS @code{char-whitespace?}.  @xref{Characters}.
You can also use @code{(char-set-contains? char-set:whitespace c)}
with @code{srfi-14}.   @xref{R7RS character sets}.
@item isupper
R7RS @code{char-upper-case?}.  @xref{Characters}.
You can also use @code{(char-set-contains? char-set:upper-case c)}
with @code{srfi-14}.   @xref{R7RS character sets}.
@item isxdigit
Not directly supported, but you can use
@code{(char-set-contains? char-set:hex-digit c)} with @code{srfi-14}.
@xref{R7RS character sets}.
@item kill
Gauche's @code{sys-kill}.  @xref{Signal}.
@item labs
R7RS @code{abs}.  @xref{Arithmetics}.
@item ldexp
Gauche's @code{ldexp}.
@item ldiv
Use R7RS @code{quotient} and @code{remainder}.
@xref{Arithmetics}.
@item link
Gauche's @code{sys-link}.  @xref{Directory manipulation}.
@item localeconv
Gauche's @code{sys-localeconv}. @xref{Locale}.
@item localtime
Gauche's @code{sys-localtime}.  @xref{Time}.
@item log
R7RS @code{log}.  @xref{Arithmetics}.
@item log10
Not directly supported.  @code{log10(z)} @equiv{} @code{(/ (log z) (log 10))}.
@item longjmp
R7RS @code{call/cc} provides similar (superior) mechanism.
@xref{Continuations}.
@item lseek
Use Gauche's @code{port-seek} (@pxref{Common port operations})
@item malloc
Not necessary in Scheme.
@item mblen
@itemx mbstowcs
@itemx mbtowc
Gauche handles multibyte strings internally, so generally you don't
need to care about multibyte-ness of the string.   @code{string-length}
always returns a number of characters for a string in supported
encoding.   If you want to convert the character encoding,
see @ref{Character code conversion}.
@item memcmp
@itemx memcpy
@itemx memmove
@itemx memset
No equivalent functions.
@item mkdir
Gauche's @code{sys-mkdir}.  @xref{Directory manipulation}.
@item mkfifo
Gauche's @code{sys-mkfifo}.
@item mkstemp
Gauche's @code{sys-mkstemp}.   @xref{Directory manipulation}.
Use this instead of tmpnam.
@item mktime
Gauche's @code{sys-mktime}.  @xref{Time}.
@item modf
Gauche's @code{modf}.
@item open
Not directly supported.
R7RS @code{open-input-file} or @code{open-output-file}
corresponds to this operation.  @xref{File ports}.
@item opendir
Not directly supported.
You can use @code{sys-readdir} to read the directory entries at once.
@xref{Directories}.
@item openpty
Use @code{sys-openpty}.  @xref{Terminal control}.
@item pathconf
Not supported.
@item pause
Gauche's @code{sys-pause}.  @xref{Miscellaneous system calls}.
@item perror
No equivalent function in Gauche.  System calls generally throws an
error (@code{<system-error>}), including the description of the reason
of failure.
@item pipe
Gauche's @code{sys-pipe}.  @xref{Other file operations}.
@item pow
R7RS @code{expt}.  @xref{Arithmetics}.
@item printf
Not directly supported, but Gauche's @code{format}
provides similar functionality.  @xref{Output}.
SLIB has @code{printf} implementation.
@item putc
@itemx putchar
Use @code{write-char} or @code{write-byte}.  @xref{Output}.
@item puts
Use @code{display}.   @xref{Output}.
@item qsort
Gauche's @code{sort} and @code{sort!} provides a convenient way to sort
list of items.  @xref{Sorting and merging}.
@item raise
No equivalent function in Gauche.  Scheme function @code{raise} (SRFI-18)
is to raise an exception.   You can use @code{(sys-kill (sys-getpid) SIG)}
to send a signal @code{SIG} to the current process.
@item rand
Not supported directly, but on most platforms a better RNG is available
as @code{sys-random}.  @xref{Miscellaneous system calls}.
@item read
Not supported directly, but you may be able to use
@code{read-uvector} or
@code{read-uvector!} (@pxref{Uvector block I/O}).
@item readdir
Not supported directly.   Gauche's @code{sys-readdir} reads
the directory at once.  @xref{Directories}.
@item readlink
Gauche's @code{sys-readlink}.  @xref{Directory manipulation}.
This function is available on systems that support symbolic links.
@item realloc
Not necessary in Scheme.
@item realpath
Gauche's @code{sys-normalize-pathname} or @code{sys-realpath}.
@xref{Pathnames}.
@item remove
Gauche's @code{sys-remove}.  @xref{Directory manipulation}.
@item rename
Gauche's @code{sys-rename}.  @xref{Directory manipulation}.
@item rewind
Not directly supported, but you can use @code{port-seek} instead.
@xref{Common port operations}.
@item rewinddir
Not supported directly.
You can use @code{sys-readdir} to read the directory entries at once.
@xref{Directories}.
@item rmdir
Gauche's @code{sys-rmdir}.  @xref{Directory manipulation}.
@item scanf
Not supported.  For general case, you have to write a parser.
If you can keep the data in S-exp, you can use @code{read}.
If the syntax is very simple, you may be able to utilize
@code{string-tokenize} in @code{srfi-14} (@ref{String library}),
and/or regular expression stuff (@ref{Regular expressions}).
@item select
Gauche's @code{sys-select}.  @xref{I/O multiplexing}.
@item setbuf
Not necessary.
@item setgid
Gauche's @code{sys-setgid}.
@item setjmp
R7RS @code{call/cc} provides similar (superior) mechanism.
@xref{Continuations}.
@item setlocale
Gauche's @code{sys-setlocale}.  @xref{Locale}.
@item setpgid
Gauche's @code{sys-setpgid}.  @xref{System inquiry}.
@item setsid
Gauche's @code{sys-setsid}.  @xref{System inquiry}.
@item setuid
Gauche's @code{sys-setuid}.  @xref{System inquiry}.
@item setvbuf
Not necessary.
@item sigaction
You can use @code{set-signal-handler!} to install signal handlers.
@xref{Handling signals}.
@item sigaddset
@itemx sigdelset
@itemx sigemptyset
@itemx sigfillset
Gauche's @code{sys-sigset-add!} and @code{sys-sigset-delete!}.
@xref{Signals and signal sets}.
@item sigismember
Not supported yet.
@item siglongjmp
R7RS @code{call/cc} provides similar (superior) mechanism.
@xref{Continuations}.
@item signal
You can use @code{with-signal-handlers} to install signal handlers.
@xref{Handling signals}.
@item sigpending
Not supported yet.
@item sigprocmask
Signal mask is handled internally.  @xref{Handling signals}.
@item sigsetjmp
R7RS @code{call/cc} provides similar (superior) mechanism.
@xref{Continuations}.
@item sigsuspend
Gauche's @code{sys-sigsuspend}.  @xref{Masking and waiting signals}.
@item sigwait
Gauche's @code{sys-sigwait}.  @xref{Masking and waiting signals}.
@item sin
@itemx sinh
Use @code{sin} and @code{sinh}.   @xref{Arithmetics}.
@item sleep
Gauche's @code{sys-sleep}.  @xref{Miscellaneous system calls}.
@item sprintf
Not directly supported, but Gauche's @code{format}
provides similar functionality.  @xref{Output}.
SLIB has @code{printf} implementation.
@item sqrt
R7RS @code{sqrt}.  @xref{Arithmetics}.
@item srand
Not supported directly, but on most platforms a better RNG is available
as @code{sys-srandom} (@pxref{Miscellaneous system calls}).
The @code{math.mt-random} module provides much superior RNG
(@pxref{Mersenne-Twister random number generator}).
@item sscanf
Not supported.  For general case, you have to write a parser.
If you can keep the data in S-exp, you can use @code{read}.
If the syntax is very simple, you may be able to utilize
@code{string-tokenize} in @code{srfi-14} (@ref{String library}),
and/or regular expression stuff (@ref{Regular expressions}).
@item stat
Gauche's @code{sys-stat}.  @xref{File stats}.
@item strcasecmp
R7RS @code{string-ci=?} and other comparison functions.
@xref{String comparison}.
@item strcat
R7RS @code{string-append}.  @xref{String utilities}.
@item strchr
SRFI-13 @code{string-index}.  @xref{SRFI-13 String searching}.
@item strcmp
R7RS @code{string=?} and other comparison functions.
@xref{String comparison}.
@item strcoll
Not supported yet.
@item strcpy
R7RS @code{string-copy}.    @xref{String utilities}.
@item strcspn
Not directly supported, but you can use SRFI-13 @code{string-skip}
with a character set.  @xref{SRFI-13 String searching}.
@item strerror
Gauche's @code{sys-strerror}.  @xref{System inquiry}.
@item strftime
Gauche's @code{sys-strftime}.  @xref{Time}.
@item strlen
R7RS @code{string-length}.  @xref{String accessors & modifiers}.
@item strncat
Not directly supported, but you can use @code{string-append} and
@code{substring}.
@item strncasecmp
SRFI-13 @code{string-compare-ci} provides the most flexible
(but a bit difficult to use) functionality.
@xref{SRFI-13 String comparison}.
If what you want is just to check the fixed-length prefixes of two
string matches, you can use SRFI-13 @code{string-prefix-ci?}.
@item strncmp
SRFI-13 @code{string-compare} provides the most flexible
(but a bit difficult to use) functionality.
@xref{SRFI-13 String comparison}.
If what you want is just to check the fixed-length prefixes of two
string matches, you can use SRFI-13 @code{string-prefix?}.
@xref{SRFI-13 String prefixes & suffixes}.
@item strncpy
SRFI-13 @code{substring}.  @xref{String utilities}.
@item strpbrk
Not directly supported, but you can use SRFI-13 @code{string-skip}
with a character set.  @xref{SRFI-13 String searching}.
@item strrchr
SRFI-13 @code{string-index-right}.  @xref{SRFI-13 String searching}.
@item strspn
Not directly supported, but you can use SRFI-13 @code{string-index}
with a character set.  @xref{SRFI-13 String searching}.
@item strstr
SRFI-13 @code{string-contains}.  @xref{SRFI-13 String searching}.
@item strtod
You can use R7RS @code{string->number}.   @xref{Numerical conversions}.
@item strtok
SRFI-13 @code{string-tokenize}.  @xref{SRFI-13 Other string operations}.
@item strtol
@itemx strtoul
You can use R7RS @code{string->number}.   @xref{Numerical conversions}.
@item strxfrm
Not supported yet.
@item symlink
Gauche's @code{sys-symlink}.  @xref{Directory manipulation}.
This function is available on systems that support symbolic links.
@item sysconf
Not supported yet.
@item system
Gauche's @code{sys-system}.   @xref{Process management}.
It is generally recommended to use the process library
(@ref{High-level process interface}).
@item tan
@itemx tanh
R7RS @code{tan} and Gauche @code{tanh}.  @xref{Arithmetics}.
@item tcdrain
@item tcflow
@item tcflush
@item tcgetattr
@item tcgetpgrp
@item tcsendbreak
@item tcsetattr
@item tcsetpgrp
Corresponding functions are: @code{sys-tcdrain}, @code{sys-tcflow},
@code{sys-tcflush}, @code{sys-tcgetattr}, @code{sys-tcgetpgrp},
@code{sys-tcsendbreak}, @code{sys-tcsetattr}, @code{sys-tcsetpgrp}.
@xref{Terminal control}.
@item time
Gauche's @code{sys-time}.  @xref{Time}.
@item times
Gauche's @code{sys-times}.  @xref{System inquiry}.
@item tmpfile
Not exactly supported.  See @code{sys-mkstemp} instead.
@xref{Directory manipulation}.
@item tmpnam
Gauche's @code{sys-tmpnam}.
This function is provided since it is in POSIX, but its use is
discouraged for the potential security risk.  Use @code{sys-mkstemp}
instead.   @xref{Directory manipulation}.
@item tolower
@itemx toupper
R7RS @code{char-upcase} and @code{char-downcase}.   @xref{Characters}.
@item ttyname
Gauche's @code{sys-ttyname}.  @xref{Other file operations}.
@item tzset
Not supported yet.
@item umask
Gauche's @code{sys-umask}.  @xref{Directory manipulation}.
@item uname
Gauche's @code{sys-uname}.  @xref{System inquiry}.
@item ungetc
Not directly supported.  You can use @code{peek-char} to look
one character ahead, instead of pushing back.
@item unlink
Gauche's @code{sys-unlink}.  @xref{Directory manipulation}.
@item utime
Gauche's @code{sys-utime}. @xref{File stats}.
@item va_arg
@itemx va_end
@itemx va_start
Not necessary, for Scheme handles variable number of arguments naturally.
@item vfprintf
@itemx vprintf
@itemx vsprintf
Not directly supported, but Gauche's @code{format}
provides similar functionality.  @xref{Output}.
SLIB has @code{printf} implementation.
@item wait
Gauche's @code{sys-wait}.  @xref{Process management}.
@item waitpid
Gauche's @code{sys-waitpid}.  @xref{Process management}.
@item wcstombs
@itemx wctomb
Gauche handles multibyte strings internally, so generally you don't
need to care about multibyte-ness of the string.   @code{string-length}
always returns a number of characters for a string in supported
encoding.   If you want to convert the character encoding,
see @ref{Character code conversion}.
@item write
R7RS @code{display} (@pxref{Output}).
Or @code{write-uvector} (@pxref{Uvector block I/O}).
@end table

@c Appendix : Common Lisp to Scheme mapping
@c Appendix : Perl to Scheme mapping
@c Appendix : Python to Scheme mapping?

@c Local variables:
@c mode: texinfo
@c coding: utf-8
@c end:
@node Function and Syntax Index, Module Index, C to Scheme mapping, Top
@appendix Function and Syntax Index
@c NODE Index - 手続きと構文索引
@printindex fn

@c Local variables:
@c mode: texinfo
@c coding: utf-8
@c end:
@node Module Index, Lexical syntax index, Function and Syntax Index, Top
@appendix Module Index
@c NODE Index - モジュール索引
@printindex md

@c Local variables:
@c mode: texinfo
@c coding: utf-8
@c end:
@node Lexical syntax index, Class Index, Module Index, Top
@appendix Lexical syntax index
@c NODE Index - 字句構文索引
@printindex lx

@c Local variables:
@c mode: texinfo
@c coding: utf-8
@c end:
@node Class Index, Variable Index, Lexical syntax index, Top
@appendix Class Index
@c NODE Index - クラス索引

For readability, the surrounding @code{<} and @code{>} are stripped off.

@printindex cl

@c Local variables:
@c mode: texinfo
@c coding: utf-8
@c end:
@node Variable Index, , Class Index, Top
@appendix Variable Index
@c NODE Index - 変数索引
@printindex vr

@c Local variables:
@c mode: texinfo
@c coding: utf-8
@c end:

@bye

