DefineInputStreamMethod

DefineInputStreamMethod["name",{"fname₁"function₁,"fname₂"function₂,… }]

Wolfram言語が入力ストリームを開き，そこから読み込むために，ストリーム関数 function_i を呼ぶことを許可する，指定された名前のカスタム入力ストリームメソッドを定義する．

詳細とオプション

入力ストリーム法は，InputStreamオブジェクトを作成するための異なる方法である．DefineInputStreamMethodを使って事前定義されたリストに新しい入力ストリーム法が追加できる．
入力ストリーム法は，新たな入力ソースからのストリームを提供し，入力をフィルタ処理し（復号化または展開の適用等），読取り中に副作用を実行し，それらを組み合せることができる．
次のストリーム関数を使うことができる．

	"NameTestFunction"	指定された名前のストリームを開くことができるかどうか
	"ConstructorFunction"	このメソッドを使って新たな入力ストリームを開く
	"CloseFunction"	ストリームを閉じ，そのリソースを解放する
	"ReadFunction"	ストリームからバイトを読む
	"EndOfFileQFunction"	ストリームにこれ以上読み込む入力がないかどうか
	"WaitForInputFunction"	読み込む入力が現れるまで待つ
	"SeekFunction"	入力が読み込まれるストリーム中の点の位置を変える
	"StreamPositionFunction"	入力が読み込まれているストリーム中の現行点
	"StreamSizeFunction"	ストリームから読み込むことができるバイト数
	"SeekableQFunction"	入力が読み込まれる点の位置を，ストリームメソッドが変えられるかどうか
	"ErrorTextFunction"	エラーがあったかどうかを示す
	"ClearErrorFunction"	エラーの表示をクリアする
	"OptionChangesFunction"	Options[stream]によって返されたオプションを変更する

DefineInputStreamMethodに渡さなければならないのは"ConstructorFunction"だけである．関数が与えられない場合，他のすべての関数にはデフォルトの定義がある．
各InputStreamには，それに関連付けられた現在の状態式がある．初期状態式は"ConstructorFunction"によって返される．その他の関数は現在の状態をパラメータとして受け取り，新しい状態値を返す．この状態式は，ストリームメソッドが，もとになるストリーム資源へのハンドル，現在のストリーム位置，最新のエラーメッセージ，およびストリームメソッド関数に必要なその他の情報等の情報を格納できる場所である．
新しい状態値を返す関数が与えられない場合，デフォルトの定義は与えられた状態を変更せずに返す．
OpenReadは，Methodオプションが登録済み入力ストリームメソッド名を使用する場合，または MethodAutomaticでかつ入力ストリームメソッドの"NameTestFunction"がそのストリーム名に対して Trueを返す場合は，入力ストリームメソッドを使用する．
MethodAutomaticのとき，OpenRead["name"]は"NameTestFunction"f を f["name"]として呼び出し，f が Trueを返す場合には，ストリームを構築するために入力ストリームメソッドを用いる．
"NameTestFunction"が与えられない場合，デフォルトの実装は常にFalseを返す．
OpenReadまたは他の関数が入力ストリームを開く際には，"ConstructorFunction"f を f[name,caller,opts]として呼び出す．ここで，name はストリーム名（例えば，ファイルパスまたはURL）である．caller はストリームを開いたOpenReadまたは他の関数であり，メッセージを発行するために使用できる．opts 引数はオプション規則である．関数 f は，{success,state}というリストを返すことが期待される．ここで，コンストラクタがストリームを開くことに成功した場合には success は Trueであり，state はストリーム状態の初期値である．
Method{"method","name"値,...}を用いてストリームを開く場合，"method"の後にある規則は，"ConstructorFunction"に渡されるopts規則に含まれる．これによって，メソッド固有の設定を入力ストリームメソッドに渡すことが可能になる．
Close[stream]は，"CloseFunction"f を f[state]として呼び出す．これは入力ストリームに対して最後に呼び出される関数で，必要なリソースのクリーンアップを実行する．
"CloseFunction"が指定されない場合，デフォルトの実装は何も行わない．
ReadやBinaryReadのようなストリーム読取り関数は，読取りの前に"WaitForInputFunction"f を f[state]として呼び出し，新しい状態を返す．ストリームメソッドが，外部プロセスからの出力を読み取る場合のように，入力が断続的に読み取られる可能性のある状況で使用される場合には，"ReadFunction"が入力待ちを決して行わないようにこのメソッドにおいて待機を行うべきである．
"WaitForInputFunction"が指定されていない場合，デフォルトの関数は待機することなく，可能な限り速くその入力を返す．これは，待機が不要なストリームメソッドに適している．
ストリーム読取り関数，例えばReadやBinaryReadは，"ReadFunction"f を f[state,n]として呼び出す．ここで state は現在のストリーム状態であり，n は返すバイト数の最大値である．関数 f は，{{byte1,...},state}というリストを返すことが期待されている．ここで第1要素は n 個以下のバイト値のリストであり，state は新しい状態式である．
"ReadFunction"が指定されない場合，デフォルト実装は常に空のバイト列リストと変更されていない状態式を返す．
もし "ReadFunction"が要求された数より少ないバイト数を返す場合には，"EndOfFileQFunction"f が f[state]として呼び出される．これは{eof,state}というリストを返すことが期待されている．ここで eof は，入力ストリームがその入力元の終端に到達している場合にはTrueであり，それ以外の場合にはFalseである．
デフォルトで，"EndOfFileQFunction"関数は{True,state}を返す．
もし "ReadFunction"が要求されたバイト数より少ないバイト数を返し，かつ"EndOfFileQFunction"が入力の終端に到達したことを示さない場合，"ErrorTextFunction"f は f[state]として呼び出される．関数 f は，{error,state}というリストを返すことが想定されている．ここで error はエラー文字列であり，state は新しい状態である．エラーが存在しない場合，f はエラー文字列の代りにNullを返す．
"ErrorTextFunction"が指定されない場合，デフォルトの実装は{Null,state}を返す．
"ReadFunction"がエラー文字列を返す場合は，"ClearErrorFunction"f が f[state]として呼び出される．関数 f は，リスト{Null,state}を返す必要がある．通常，ストリームメソッドは読取り時に状態式の中へエラーテキストを格納することがあるため，"ClearErrorFunction"はエラーメッセージが消去された新しい状態を返す．
"ClearErrorFunction"が指定されない場合，デフォルトの実装は{Null,state}を返す．
StreamPositionは "StreamPositionFunction"f を f[state]として呼び出す．関数 f はリスト{n,state}を返す必要がある．ここで n は，ストリームの先頭からのバイト数として測定された，開いているストリーム内の現在位置の点の位置である．位置-1は，ストリーム位置が不明であることを示す．
"StreamPositionFunction"が指定されない場合，デフォルトの実装は-1の位置を返す．
ストリームを開く際には，"StreamSizeFunction"f が f[state]として呼び出される．関数 f は，{size, state}というリストを返すことが想定されている．ここで size は，既知である場合には入力ストリームの総サイズ（バイト単位）であり，未知である場合には-1である．また，state は次の状態式（変更されていなくてもよい）である．ストリームのサイズが既知である場合は，より高速な読取りが可能になることがある．
"StreamSizeFunction"が指定されない場合，デフォルトの実装 -1の大きさを返す．
ストリームを開く際には，"SeekableQFunction"  f が f[state]として呼び出される．関数 f は，{flag,state}というリストを返すことが期待され，その際，flag は，ストリームメソッドが SetStreamPositionによってストリーム位置を変更できる場合にはTrueで，そうではない場合はFalseである．また，state は新しい状態式（変更されていなくてもよい）である．
"SeekableQFunction"が指定されない場合，デフォルトの実装はFalseのフラグを返す．
SetStreamPositionは，"SeekFunction"f を f[state,pos]として呼び出す．ここで pos は新しいストリーム位置である．位置は，ストリームの先頭からのバイト数を示す非負整数，またはストリームの終端を示す Infinityのいずれかである．関数 f は，{success,state}というリストを返すことが期待されている．ここで success はストリーム位置が正常に変更されたかどうかを示し，state は新しいストリーム状態を示す．"SeekFunction"は，ストリームメソッドの"SeekableQFunction"が以前にストリーム位置の変更をサポートすることを示していた場合にのみ呼び出される．
"SeekFunction"が指定されない場合，デフォルト実装は success フラグとしてFalseを返す．
"OptionChangesFunction"は，パスワードのような秘密情報をオプションが含む場合に，Options[stream,Method]が返す値を変更するための手段をストリームメソッドに与えるために用いられる．
Options[stream]は，"OptionChangesFunction"f を f[state,opts]として呼び出す．関数 f は{newopts,state}というリストを返す必要がある．ここで newopts は，Optionsによって返されるMethodオプション設定として用いられる．
同じ名前を持つ入力ストリームメソッドが存在する場合，DefineInputStreamMethodは失敗する．
入力ストリームメソッドは，RemoveInputStreamMethodによって削除できる．

例題

すべて開くすべて閉じる

例 (1)

ストリーム名そのものから読み出す入力ストリームメソッドを定義する：

Wolfram Language code:

DefineInputStreamMethod["StringName", {
	"ConstructorFunction" -> ({True, <|"Pos" -> 1, "Text" -> ToCharacterCode[#]|>}&), 
	"ReadFunction" -> (With[{pos = #["Pos"]}, 
	Replace[Take[#["Text"], {pos, UpTo[pos + #2 - 1]}], 
	bytes_List :> {bytes, Append[#, "Pos" -> pos + Length[bytes]]}]
	]&)
	}]

名前として読むテキストがあるストリームを開く：

Wolfram Language code:

strm = OpenRead["Hello, world.
Here is text.", Method -> "StringName"]

ストリームの行を読む：

Wolfram Language code: ReadList[strm, String]

ストリームを閉じる：

Wolfram Language code: Close[strm]

スコープ (5)

接頭辞"text:"で始まる名前を持つ任意のストリームを開くために"NameTestFunction"を用いる入力ストリームメソッドを定義する：

Wolfram Language code:

DefineInputStreamMethod["TextName", {
	"NameTestFunction" -> StringStartsQ["text:"], 
	"ConstructorFunction" -> ({True, <|"Pos" -> 1, "Text" -> ToCharacterCode[StringDrop[#, 5]]|>}&), 
	"ReadFunction" -> (With[{pos = #["Pos"]}, 
	Replace[Take[#["Text"], {pos, UpTo[pos + #2 - 1]}], 
	bytes_List :> {bytes, Append[#, "Pos" -> pos + Length[bytes]]}]
	]&)
	}]

ストリーム名に接頭辞"text:" 含めることで，"TextName"ストリームメソッドでストリームを開く：

Wolfram Language code:

strm = OpenRead["text:Hello, world.
Here is text."]

ストリームから行を読み取る：

Wolfram Language code: ReadList[strm, String]

ストリームを閉じる：

Wolfram Language code: Close[strm]

ストリームから読み取るたびにメッセージを出力する入力ストリームメソッドをファイルに対して定義する：

Wolfram Language code:

DefineInputStreamMethod["FileProgress", {
	"ConstructorFunction" -> Function[{name, caller, opts}, 
	Replace[OpenRead[name, BinaryFormat -> True], {
	s_InputStream :> {True, <|"Stream" -> s, "End" -> False|>}, 
	_ :> {False, Null}
	}]
	], 
	"CloseFunction" -> Function[state, Close[state["Stream"]]], 
	"ReadFunction" -> Function[{state, n}, 
	Replace[BinaryReadList[state["Stream"], "Byte", n], {
	{} :> {{}, Append[state, "End" -> True]}, 
	bytes_List :> (
	Print["Read ", Length[bytes], " bytes"];
	{bytes, state}
	)
	}]
	], 
	"EndOfFileQFunction" -> Function[state, {state["End"], state}]
	}]

この入力メソッドでストリームを開く．内部バッファを満たすために直ちに読み取られることに注意のこと：

Wolfram Language code:

file = FileNameJoin[{$InstallationDirectory, "Documentation/English/System/ExampleData/USConstitution.txt"}];
strm = OpenRead[file, Method -> "FileProgress"]

ストリームから読み込み，読み込みと同時に進行状況メッセージを表示する：

Wolfram Language code: Short[ReadList[strm, String]]

ストリームを閉じる：

Wolfram Language code: Close[strm];

シークメソッドを定義しないストリームメソッドであっても使うことはできるが，ある種の操作をサポートするためにカーネルの使用メモリが多くなる．読込みごとに出力するストリームメソッドを定義する：

Wolfram Language code:

DefineInputStreamMethod["FileProgress", {
	"ConstructorFunction" -> Function[{name, caller, opts}, 
	Replace[OpenRead[name, BinaryFormat -> True], {
	s_InputStream :> {True, <|"Stream" -> s, "End" -> False|>}, 
	_ :> {False, Null}
	}]
	], 
	"CloseFunction" -> Function[state, Close[state["Stream"]]], 
	"ReadFunction" -> Function[{state, n}, 
	Replace[BinaryReadList[state["Stream"], "Byte", n], {
	{} :> {{}, Append[state, "End" -> True]}, 
	bytes_List :> (
	Print["Read ", Length[bytes], " bytes"];
	{bytes, state}
	)
	}]
	], 
	"EndOfFileQFunction" -> Function[state, {state["End"], state}]
	}]

次は，連続する読取り呼出しにおいて，読み取られるバイト数が次第に増加していくことを示している：

Wolfram Language code:

st = OpenRead[FindLibrary["demo"], BinaryFormat -> True, Method -> "FileProgress"];
data = BinaryReadList[st];
Close[st];

"SeekableQFunction"，"StreamSize"，"SeekFunction"にサポートを加えることで，ストリームメソッドを再定義する：

Wolfram Language code:

RemoveInputStreamMethod["FileProgress"];
DefineInputStreamMethod["FileProgress", {
	"ConstructorFunction" -> Function[{name, caller, opts}, 
	Replace[OpenRead[name, BinaryFormat -> True], {
	s_InputStream :> {True, <|"Stream" -> s, "Size" -> FileByteCount[name], "End" -> False|>}, 
	_ :> {False, Null}
	}]
	], 
	"CloseFunction" -> Function[state, Close[state["Stream"]]], 
	"ReadFunction" -> Function[{state, n}, 
	Replace[BinaryReadList[state["Stream"], "Byte", n], {
	{} :> {{}, Append[state, "End" -> True]}, 
	bytes_List :> (
	Print["Read ", Length[bytes], " bytes"];
	{bytes, state}
	)
	}]
	], 
	"EndOfFileQFunction" -> Function[state, {state["End"], state}], 
	"SeekableQFunction" -> Function[state, {True, state}], 
	"StreamSizeFunction" -> Function[state, {state["Size"], state}], 
	"SeekFunction" -> Function[{state, newpos}, 
	SetStreamPosition[state["Stream"], newpos];
	{True, state}
	]
	}]

これで毎回ストリームから固定量が読み取られるため，ストリームの使用に伴うメモリ要求が制限される：

Wolfram Language code:

st = OpenRead[FindLibrary["demo"], BinaryFormat -> True, Method -> "FileProgress"];
data = BinaryReadList[st];
Close[st];

一定数のバイトを読み取った後に人為的にエラーを導入する入力ストリームメソッドを定義する：

Wolfram Language code:

exampleStreamContents = BinaryReadList[FileNameJoin[{$InstallationDirectory, "Documentation/English/System/ExampleData/USConstitution.txt"}]];
DefineInputStreamMethod["ErrorDemo", {
	"ConstructorFunction" -> ({True, <|"Pos" -> 1, "Text" -> exampleStreamContents, "Error" -> Null|>}&), 
	"ReadFunction" -> 
	(If[#["Pos"] > 18000, 
	(* artificially introduce an error *)
	{{}, Append[#, "Error" -> "Internal error detected."]}, 
	(* normal reading *)
	 With[{pos = #["Pos"]}, 
	Replace[Take[#["Text"], {pos, UpTo[pos + #2 - 1]}], 
	bytes_List :> {bytes, Append[#, "Pos" -> pos + Length[bytes]]}]
	]
	]&), 
	"EndOfFileQFunction" -> ({#["Pos"] >= Length[#["Text"]], #}&), 
	"ErrorTextFunction" -> ({#["Error"], #}&), 
	"ClearErrorFunction" -> ({Null, Append[#, "Error" -> Null]}&)
	}]

このメソッドからストリームを開く：

Wolfram Language code: strm = OpenRead["errordemo", Method -> "ErrorDemo"]

ストリームから行を読み取る．これはストリームメソッドからのエラーメッセージが返される時点までは機能する：

Wolfram Language code: Short[ReadList[strm, String]]

この時点で，ストリームはファイル終端にあると見なされる：

Wolfram Language code: Read[strm, String]

ストリームは再配置できる：

Wolfram Language code: SetStreamPosition[strm, 0]

状態式からエラーマーカーを取り除く"ClearErrorFunction"のおかげで，ストリームは再読み取り可能である：

Wolfram Language code: Read[strm, String]

各バイトをある数だけ回転させることで読み込まれるファイルを見えにくくする入力ストリームメソッドを定義するが，その際，"OptionChangesFunction"を用いて，使用される正確な数をストリームオプションから隠す；

Wolfram Language code:

DefineInputStreamMethod["ObscureFile", {
	"ConstructorFunction" -> Function[{name, caller, opts}, 
	Replace[OpenRead[name, BinaryFormat -> True], {
	s_InputStream :> {True, <|"Stream" -> s, "End" -> False, "Rotate" -> With[{n = Lookup[opts, "Rotate", 0]}, If[FromCharacterCode[#] === "
", #, Mod[# + n, 256]]&]|>}, 
	_ :> {False, Null}
	}]
	], 
	"CloseFunction" -> Function[state, Close[state["Stream"]]], 
	"OptionChangesFunction" -> Function[{state, options}, {FilterRules[options, Except["Rotate"]], state}], 
	"ReadFunction" -> Function[{state, n}, 
	Replace[BinaryReadList[state["Stream"], "Byte", n], {
	bytes_List :> {Map[state["Rotate"], bytes], Append[state, "End" -> bytes === {}]}
	}]
	], 
	"EndOfFileQFunction" -> Function[state, {state["End"], state}]
	}]

回転パラメータが7のストリームを開く；

Wolfram Language code:

file = FileNameJoin[{$InstallationDirectory, "Documentation/English/System/ExampleData/USConstitution.txt"}];
strm = OpenRead[file, Method -> {"ObscureFile", "Rotate" -> 7}]

ストリームから読み取る；

Wolfram Language code: Read[strm, String]

ストリームオプションがチェックされると，"Rotate"パラメータは"OptionChangesFunction"によって隠される：

Wolfram Language code: Options[strm]

ストリームを閉じる：

Wolfram Language code: Close[strm];

Top

その他のラーニングリソース

テクニカルサポート

データサイエンス，金融，ビジネス

工学

科学とテクノロジー

教育のためのテクノロジー

教育イニシアチブ

使い始める

Grow Your Skills

Wolframと繋がる

大人用の教育プログラム

若者のための教育プログラム

読む

DefineInputStreamMethod

詳細とオプション

例題

例 (1)

スコープ (5)

テキスト

CMS

APA

BibTeX

BibLaTeX

DefineInputStreamMethod

詳細とオプション

例題

例 (1)

スコープ (5)

関連項目

テクニカルノート

関連するガイド

履歴

テキスト

CMS

APA

BibTeX

BibLaTeX