(rontolisp) docs

Gray ストリーム (ユーザー定義ストリーム)

rontolisp は実装ネイティブの Gray サポートを公開する実際の処理系にならい、独自の小さな Gray ストリーム拡張を同梱しています: ユーザークラスが rontolisp:fundamental-*-stream 基底クラスのいずれかを継承し rontolisp:stream-* 総称関数にメソッドを定義すると、 ストリームを取る組み込みはストリームハンドルの代わりにそのインスタンスを渡されたときに これらのメソッドへディスパッチします。すべてのバックエンド (インタープリタ、JVM、両 WASM) で動作します。

基底クラスは CL と同じ形の階層を成します: ルートに fundamental-stream、その下に 方向のクラス fundamental-input-stream / fundamental-output-stream と要素のクラス fundamental-character-stream / fundamental-binary-stream、リーフとして fundamental-character-input-stream / fundamental-character-output-stream / fundamental-binary-input-stream / fundamental-binary-output-stream があり、各リーフは方向のクラスと要素のクラスを 1 つずつ継承します (すべて rontolisp パッケージ)。方向のクラスと要素のクラスをクラス自身で組み合わせることもできます。

組み込みディスパッチ先
write-charrontolisp:stream-write-char
write-string, format (ストリーム宛先)rontolisp:stream-write-string
princ, prin1, print描画したテキストの rontolisp:stream-write-string (print はその後 stream-terpri)
terprirontolisp:stream-terpri (デフォルトメソッドは stream-write-char で改行を書く)
fresh-linerontolisp:stream-fresh-line (デフォルトメソッド: stream-start-line-p でなければ stream-terpri)
write-linerontolisp:stream-write-string のあと rontolisp:stream-terpri
force-output / finish-output / clear-outputrontolisp:stream-force-output / -finish-output / -clear-output (デフォルトメソッドは nil を返す)
closet を返す — 後述
write-byterontolisp:stream-write-byte
read-byterontolisp:stream-read-byte
read-charrontolisp:stream-read-char
read-char-no-hangrontolisp:stream-read-char-no-hang (デフォルトメソッドは stream-read-char そのもの)
peek-charrontolisp:stream-peek-char (デフォルトメソッドは 1 文字読んで stream-unread-char で押し戻す)。peek-type の読み飛ばし形式はこれをループします
unread-charrontolisp:stream-unread-char (デフォルトメソッドは文字をインスタンス自身に保管)
read-linerontolisp:stream-read-line (デフォルトメソッドは stream-read-char をループ)
listenrontolisp:stream-listen (デフォルトメソッドは nil を返す)
clear-inputrontolisp:stream-clear-input。メソッドの返す値によらず nil を返します (デフォルトメソッドは fundamental-character-input-stream にあり nil を返す)
open-stream-pt を返します -- close と同じく、プログラムが所有できる名前です
streamp, (typep x 'stream)t を返します -- Gray ストリームはストリームそのものなので、型で分岐するライブラリは Lisp ストリーム側の枝を選びます
stream-element-typecharacter、fundamental-binary-stream の下なら (unsigned-byte 8)。両方を継承したクラス (バイバレントなストリーム) は character を返します。この答えはどちらのバッファを確保すべきかを示すものだからです。プログラムが所有できる名前です
read-sequence / write-sequencerontolisp:stream-read-sequence / -write-sequence (デフォルトメソッドは要素総称関数をループ。文字列は 1 回の stream-write-string に渡す)
file-positionrontolisp:stream-file-position。2 引数形式は (setf rontolisp:stream-file-position) ライタ総称関数を呼ぶ

*standard-output* や *standard-input* に束縛したインスタンスは、SBCL と同じく ストリームを指定しない呼び出しの対象になります: (princ x)、(read-char)、ストリーム引数 nil、format t は、ストリームを明示したときと同様にそのメソッドへ届きます。

文字出力ストリームは stream-write-char か stream-write-string のどちらか一方を 定義すれば十分です。それぞれ他方を使ったデフォルトメソッドを持つため、書いたほうから 残りの出力プロトコルが組み上がります (どちらも定義しないのが唯一の壊れた形で、2 つの デフォルトが互いを呼び合います)。SBCL と同じく stream-write-string は常に整数の start と end 付きで呼ばれるので、メソッドは (stream string &optional start end) を受け取り、 その範囲を書き込みます。

さらに 2 つ、対応する組み込みは持たないものの行単位の演算子が参照する総称関数があります: rontolisp:stream-line-column はストリームの現在の桁位置を返し、桁位置を追跡しない ストリームでは nil (デフォルト) を返します。rontolisp:stream-start-line-p はそこから 答えます。桁位置のないストリームは行頭かどうかを判断できないため、fresh-line は常に 改行を書き込みます。fresh-line の返り値は rontolisp:stream-fresh-line の返り値で、 デフォルトでは書いたときに t、書かなかったときに nil です。 rontolisp:stream-advance-to-column は直接呼ぶプログラムのためにプロトコルを補完します。

Gray ストリームを閉じると t を返し、他には何もしません — 解放するものがないからです。 解放するものがあるストリームは CL 本来の綴り、すなわち close 自身へのメソッドを 書きます:

このメソッドはすべてのバックエンドでディスパッチします。これを定義したプログラムが close を完全に所有し、Gray のデフォルトは rontolisp:fundamental-stream 上のメソッドに 退きます (SBCL と同じ)。そのため別のクラスの Gray ストリームは引き続き t を返して閉じます。 open-stream-p、input-stream-p、output-stream-p、stream-element-type も同様です。

文字入力ストリームが定義すべきなのは stream-read-char ただ 1 つです (バイナリなら stream-read-byte)。読み取り側の残りはすべてその上に書かれています: stream-read-line と stream-read-sequence はそれをループし、 stream-read-char-no-hang はそれ自体で、stream-peek-char は 1 文字読んでから stream-unread-char で押し戻します。stream-unread-char の既定メソッドは、その文字を インスタンス自身に保管します。自前でソースを巻き戻せるクラスは stream-unread-char を 定義して押し戻しを自分で所有します — そのとき保管用のセルは一度も書かれません。

読み取り側のメソッドはストリーム終端でキーワード :eof を返します。組み込みはそれを通常の eof-error-p / eof-value 契約に翻訳します。stream-read-line は (values line missing-newline-p) を返し、末尾の部分行は 2 番目の値を真にしてその行として、 文字がまったく残っていなければ :eof を返します。自分で定義したメソッドは標準 Gray の ("" t) でストリームの終端を示すこともできます。read-line はメソッドの 2 番目の値を そのまま自身の 2 番目の値として返します。

stream-write-char だけを定義し、桁位置を追跡することで fresh-line が改行の要否を 判断できるストリーム:

file-position プロトコル付きのバイナリ入力ストリーム:

stream-read-char だけを定義した文字入力ストリームを、読み取りプロトコルの残りで 駆動する例です:

trivial-gray-streams シム

ポータブルなライブラリは処理系独自のプロトコルではなく trivial-gray-streams に対して書かれています。rontolisp はポータブル API を上のプロトコルへ適合させる組み込みの trivial-gray-streams ASDF システムを同梱しています (システムを参照): trivial-gray-streams パッケージはすべての基底クラス (trivial-gray-stream-mixin も含む) と本物のパッケージのすべての総称関数をミラーします。 stream-read-char-no-hang / stream-peek-char / stream-clear-input、 stream-read-sequence / stream-write-sequence (stream sequence start end &key)、stream-file-position とその (setf ...) ライタ、そして出力系の stream-line-column / stream-start-line-p / stream-terpri / stream-fresh-line / stream-advance-to-column / stream-force-output / stream-finish-output / stream-clear-output も含まれます — jzon の :stream ライタ API はこの仕組みで動いており、fast-io や circular-streams の定義するクラス形状もそのままロードできます。デフォルトは rontolisp プロトコルと同じ ものなので、trivial-gray-streams:stream-write-char だけを定義したポータブルなクラスでも 上のすべての演算子に応答します。

制限

  • rontolisp:stream-advance-to-column はプロトコル総称関数として存在しますが、 どの組み込みもディスパッチしません (format の ~T は桁位置を参照しません)。
  • プロトコルの押し戻しは 1 ストリームにつき 1 文字を、インスタンス自身に保持します。 これは CL が unread-char に約束している範囲そのものです。2 つのインスタンスはそれぞれ 1 文字ずつ保持でき、文字を保管したまま捨てたインスタンスは他に影響しません。保管用の セルはスロットではないので、クラスのスロット一覧、プリンタ、equal からは見えません。 プロトコル自身のデフォルトを通る読み取りは すべてこれを消費しますが、stream-read-line や stream-read-sequence を丸ごと オーバーライドしたクラスは押し戻しを読み飛ばすので、そうしたクラスは stream-unread-char も定義してください。
  • input-stream-p / output-stream-p は、クラスごとの述語メソッドではなく、 インスタンスが継承している方向の基底クラスを答えます。fundamental-input-stream の子孫は前者に t、後者に nil を返し、fundamental-stream を直接継承した クラスはどちらにも nil を返します。どちらの名前にもメソッドを定義して 答えを自分のものにできます。
  • ストリームハンドル — ファイル、文字列入力ストリーム、ソケット — への unread-char は、文字をそのストリームに保管し、同じストリームへの read-char / peek-char / read-line がそれを消費します。文字はストリームごとに保持されるので、 文字を保管したまま閉じたり捨てたりしたストリームは他のストリームに影響しません。 保管した文字が残っているストリームへの 2 回目の unread-char は通知します。 read-byte / read-sequence / read はこれを参照しません。
  • Gray インスタンスへの listen はインタープリタと JVM で動作します。Preview 1 WASM バックエンドはあらゆる listen 呼び出しをコンパイル時に拒否します (Gray とは無関係の既存プラットフォーム制限)。
  • :start / :end 付きの write-string と write-line は、SBCL と同じくメソッドを呼ぶ前に境界を検査します。 nil・負数・整数でない :start、文字列の長さを超える境界、:end より後の :start は type-error になり、何も書き込まれません。メソッドには整数の start と end が渡されます (:end が nil または省略なら文字列の長さ)。
  • 上の演算子は関数値として呼んでもディスパッチします ((funcall #'read-byte instance)、 (apply #'write-line args)、(funcall #'write-char #\x instance))。