Next: 線形更新な可変長文字列, Previous: JSON, Up: ライブラリモジュール - SRFI [Contents][Index]
srfi-181 - カスタムポートこのsrfiは、ポートをSchemeで実装する方法を定義します。 Gaucheは仮想ポートとしてそういう機能を提供しています(仮想ポート)が、 ポータブルなコードを書く場合はこのsrfiが便利でしょう。
インタフェースはR6RSの上位互換になっています。
R7RSではバイナリポートとテキストポートは区別されますが、 Gaucheのポートはバイナリもテキストもどちらも読み書きできます。
[SRFI-181] {srfi-181} それぞれ、新たなバイナリポートとテキストポートを作って返します。
id引数は任意のSchemeオブジェクトです。このsrfiではそれがどう使われるかは
規定されません。Gaucheでは、idに渡した値は
port-name手続きで得ることができます(ポート共通の操作参照)。
read!引数は手続きで、
(read! buffer start count)のように呼び出されます。
make-custom-binary-input-portでは、bufferは
バイトベクタ(u8vector)です。
make-custom-textual-input-portでは、bufferは文字列か
文字のベクタです(Gaucheでは常に文字のベクタが渡されますが、
ポータブルなコードはどちらにも対応できるように書かれなければなりません)。
read!手続きは、最大でcount個のバイトもしくは文字を生成し、 それをbufferのstart番目から書き込んで、 生成されたバイト/文字数を返します。 read!手続きは入力データがあるなら、 少なくとも1バイト/文字をバッファに書き込まなければなりません。 入力データがもう無いことを示すには、バッファを変更せず、0を返します。
get-pos引数は、引数を取らない手続きで、呼ばれたら入力ストリーム中の現在の位置を
示す処理系依存のオブジェクトを返します。「現在の位置」とは、次にread!が呼ばれた
時に読み出される位置です。カスタムポートが位置情報を扱う必要がなければ、
この引数は#fで構いません。
ただし、make-custom-binary-input-portについては、
get-posが正確な整数を返す場合、
それは入力ストリーム中のバイト位置でなければなりません。
set-pos!引数はひとつの引数を取る手続きです。
渡された引数は以前のget-posが返した値か、
make-custom-binary-input-portの場合は、
入力先頭からのバイトオフセットです。
この手続きは、次のread!が指定位置からデータを読み出すように内部状態を更新します。
カスタムポートが位置情報のセットをサポートしなくて良いなら、この引数は#fで
構いません。
set-pos!に渡された位置情報が不正なものであった場合、それは
i/o-invalid-position-error?を満たすエラーを投げなければなりません。
ポータブルに書くには、make-i/o-invalid-position-errorで作った
エラーオブジェクトを投げます(ポート位置参照)。
Gauche特有のコードで良ければ、
<io-invalid-position-error>コンディションを投げても良いです。
close引数は、カスタムポートがクローズされた時に呼び出される、
引数を取らない手続きです。特にクローズ時のクリーンアップが不要であれば
#fを渡すこともできます。
[SRFI-181] {srfi-181} Creates a new binary and textual out port and returns it, respectively.
The id argument is an arbitrary Scheme procedure. SRFI doesn’t
specify how it is used. In Gauche, id will be returned
with port-name procedure (see ポート共通の操作).
The write! argument is a procedure to be called as
(write! buffer start count).
For make-custom-binary-output-port, buffer is a bytevector.
For make-custom-textual-output-port, buffer is either
a string or a vector of characters (Gauche’s implementation always
use a vector, but portable code should handle both).
The write! procedure needs to consume data in buffer starting from start, upto count items. It must return the actual number of items consumed.
The get-pos argument should be a procedure without taking argument,
or #f. If it is a procedure, it should return the position
of the sink where the next write! writes to. The position
can be an arbitrary Scheme object, but for
make-custom-binary-output-port, a position represented as
an exact integer should correspond to the byte offset in the port.
The 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 write! starts
to write data from there. The passed position is something that has
been returned by get-pos, or, for make-custom-binary-output-port,
an exact integer that indicates the byte offset from the beginning of
the output. This argument can be #f if the port doesn’t
support setting positions. The returned value of set-pos! is
ignored.
If the position passed to set-pos! is invalid,
an error that satisfy i/o-invalid-position-error? should be
thrown. Portably, it can be done by throwing a condition created
by make-i/o-invalid-position-error (see ポート位置).
For Gauche-specific code, you can throw a condition
<io-invalid-position-error>.
The close argument is a procedure to be called without
argument, when the port is closed. It can be #f if you
don’t need a special cleanup.
The flush argument, if provided and not #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.
[SRFI-181] {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, id, read!, write!,
get-pos, set-pos!, close and flush are
the same as make-custom-binary-input-port and
make-custom-binary-output-port.
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:
A codec names a character encoding scheme.
Specifies (non)converson of EOL character(s).
A transcoder bundles a codec, an eol-style, and error handling mode.
[SRFI-181] {srfi-181} Creates and returns a transcoder with the given parameters. A transcoder is an immutable object.
[SRFI-181]
{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 gauche-character-encoding, see 文字),
and eol-style is none.
[SRFI-181] {srfi-181} Creates a transcoded port wrapping binary-port, performing the conversion specified by transcoder.
If binary-port is an input port, it returns an input port, converting the CES specified in transcoder to the system’s native encoding.
If binary-port is an output port, it returns an output port, converting the system’s native encoding to the CES specified in transcoder.
In Gauche, conversion is done by conversion ports. See 変換ポート, for the details.
[SRFI-181] {srfi-181} Decode the binary data in bytevector as the CES specified by transcoder, and returns a string in the native encoding.
It is a wrapper of Gauche’s ces-convert; see 変換ポート.
[SRFI-181] {srfi-181} Encode the string in the CES specified by transcoder, and returns a bytevector.
It is a wrapper of Gauche’s ces-convert-to; see 変換ポート.
[SRFI-181] {srfi-181} Returns a coded representing a character encoding scheme named by name. A portable code should only use string for name, while Gauche accepts a symbol as well.
If name isn’t recognized as a supported codec name,
a condition that satisfies unknown-encoding-error? is thrown.
[SRFI-181] {srfi-181} If the system sees unknown or unsupported codec, a condition that satisfies this predicate is thrown.
[SRFI-181]
{srfi-181}
The argument must be an unknown encoding error condition
that satisfies unknown-encoding-error?. It returns
the name that caused the condition to be thrown.
[SRFI-181]
{srfi-181}
A pre-defined codecs for latin-1 (ISO8859-1),
utf-8, and utf-16.
The utf-16 codec recognizes
BOM when used for input; if no BOM is found, UTF-16BE is assumed.
When used for output, utf-16 always attaches BOM.
[SRFI-181]
{srfi-181}
Returns the default eol style. In Gauche, it is none.
[SRFI-181] {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 <io-decoding-error>.
[SRFI-181]
{srfi-181}
When an output transcoded port encounters a character that can’t be
encoded in the output codec, and the handling mode is raise,
a condition that satisfies this predicate is thrown.
In Gauche, such condition is <io-encoding-error>.
[SRFI-181]
{srfi-181}
Retries the character that caused the <io-encoding-error> is thrown.
Next: 線形更新な可変長文字列, Previous: JSON, Up: ライブラリモジュール - SRFI [Contents][Index]