For Gauche 0.9.12Search (procedure/syntax/module):

Next: , Previous: , Up: ライブラリモジュール - SRFI   [Contents][Index]

11.38 srfi-181 - カスタムポート

Module: srfi-181

このsrfiは、ポートをSchemeで実装する方法を定義します。 Gaucheは仮想ポートとしてそういう機能を提供しています(仮想ポート)が、 ポータブルなコードを書く場合はこのsrfiが便利でしょう。

インタフェースはR6RSの上位互換になっています。

R7RSではバイナリポートとテキストポートは区別されますが、 Gaucheのポートはバイナリもテキストもどちらも読み書きできます。

カスタムポートの作成

Function: make-custom-binary-input-port id read! get-pos set-pos! close
Function: make-custom-textual-input-port id read! get-pos set-pos! close

[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個のバイトもしくは文字を生成し、 それをbufferstart番目から書き込んで、 生成されたバイト/文字数を返します。 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を渡すこともできます。

Function: make-custom-binary-output-port id write! get-pos set-pos! close :optional flush
Function: make-custom-textual-output-port id write! get-pos set-pos! close :optional flush

[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.

Function: make-custom-binary-input/output-port id read! write! get-pos set-pos! close :optional flush

[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.

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:

Codec

A codec names a character encoding scheme.

EOL-style

Specifies (non)converson of EOL character(s).

Transcoder

A transcoder bundles a codec, an eol-style, and error handling mode.

Transcoders

Function: make-transcoder codec eol-style handling-mode

[SRFI-181] {srfi-181} Creates and returns a transcoder with the given parameters. A transcoder is an immutable object.

Function: native-transcoder

[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.

Function: transcoded-port binary-port transcoder

[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.

Function: bytevector->string bytevector transcoder

[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 変換ポート.

Function: string->bytevector string transcoder

[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 変換ポート.

Codecs

Function: make-codec name

[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.

Function: unknown-encoding-error? obj

[SRFI-181] {srfi-181} If the system sees unknown or unsupported codec, a condition that satisfies this predicate is thrown.

Function: unknown-encoding-error-name obj

[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.

Function: latin-1-codec
Function: utf-8-codec
Function: utf-16-codec

[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.

EOL style

Function: native-eol-style

[SRFI-181] {srfi-181} Returns the default eol style. In Gauche, it is none.

Transcoding errors

Function: i/o-decoding-error? obj

[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>.

Function: i/o-encoding-error? obj

[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>.

Function: i/o-encoding-error-char i/o-encoding-condition

[SRFI-181] {srfi-181} Retries the character that caused the <io-encoding-error> is thrown.


Next: , Previous: , Up: ライブラリモジュール - SRFI   [Contents][Index]


For Gauche 0.9.12Search (procedure/syntax/module):