インポートコンバータの開発
Mathematica は,ユーザが自分のファイル形式コンバータを書き,それを Mathematica のImportとExportフレームワークと統合させることのできる関数を提供している.形式コンバータを実装し,Importを使って任意の形式からデータをインポートすることができる.
Mathematica には形式コンバータの実装および登録方法を説明するソースコードも含まれている.これらはフォルダ$InstallationDirectory/SystemFiles/Formats/format にある.ここで format はBDF,DIF,MTP,SMILES,SurferGrid,TGF,TLEのいずれかである.登録コードはファイルImport.mまたはExport.mにあり,コンバータの実装はConverter.mというファイルにある.
Importと低レベルのコンバータ関数との間のインターフェースは,
(ImportExport`コンテキスト)で指定される.基本的に
はImportとExportフレームワークに,あるファイル形式の特定の要素をインポートするときに特定の関数を呼び出す方法を指示する.
このチュートリアルでは,次のような用語が使われている.
低レベル関数はファイルあるいはストリームを入力として取り,インポートされたデータを含む規則のリストを返す.低レベル関数には次の2つの種類がある.(1) デフォルトインポータは明示的に登録されていない要素をインポートするときに,フレームワークにより呼び出される.(2) 条件付インポータは
の第2引数に登録された特定の要素をインポートする.
の第3引数に登録されているポストインポータつまりポストインポート関数は,低レベル関数の出力を入力として取る.
次にまとめたように,
にはいくつかの形式がある.このチュートリアルは徐々に高度な例題になり,
の使い方すべてを詳細に説明する.
| ImportExport`RegisterImport["format",defaultFunction] |
| タイプ のファイルをインポートするときに,Importフレームワークによりデフォルトで使われる単独の defaultFunction を登録する |
| ImportExport`RegisterImport["format",{"elem1"⧴conditionalFunction1,"elem2"⧴conditionalFunction2,...,defaultFunction}] | Importフレームワークによりデフォルトで使われる複数要素( , , ...)およびそれに対応するコンバータ関数( , , ...)を登録する.また,要求された要素が登録されたどの要素ともマッチしない場合に使われる defaultFunction を登録する. |
| ImportExport`RegisterImport["format",{conditionalFuncs,defaultFunction},{"elem3"⧴postFunction3,"elem4"⧴postFunction4,...}] | その入力が低レベル関数のうちの一つの出力となるような追加のコンバータ関数を登録する. |
デフォルトインポータ
3行のヘッダの後に4列の数字を含むファイル形式があるとする.
新規形式の登録と実装
一つの方法として,ヘッダ情報と数字をそれぞれ
要素,
要素にインポートするというものがある.これは
を使って実装することもできる,
この場合,ImportとExportフレームワークに対して,形式
のどの要素をインポートするときでも,関数
を呼び出すよう指示している.
フレームワークはデフォルトではファイル名を低レベル関数に渡すので,
は入力としてファイル名とオプションの集合を取る.この関数は
という形式の規則のリストを返さなければならない.
新しい形式のファイルのインポート
これでImportの有効なファイル形式として
が使えるようになった.
| Out[4]= |  |
| Out[5]= |  |
| Out[6]= |  |
条件付未加工インポータ
形式に多数の要素が含まれる場合,特定の低レベル関数を使って特定の要素をインポートすると便利で効率的なことがある.これは
の第2引数として "elem"->func という形式の規則のリストを与えることで実行できる.しかし,リストはリスト中で明示的に定義されているどれともマッチしない要素をインポートするときに呼ばれる,デフォルトインポータの名前で終了しなければならない.
条件付インポータによる新規形式の登録と実装
この登録はImportとExportフレームワークに,形式
のファイルのエキスポート方法を指示する.
(1)
要素をインポートするときは
を使う
(2) その他すべてには
を使う
低レベル関数は同じ構造を持つ.ファイル名とオプショナルのオプションのリストを取り,
という形式の規則の集合を返す.
MyFormat2を使ったインポート
のインポート要素の出力は
のものと同じであるが,2つの異なる要素に対して2つの異なる関数が呼び出される.
| Out[10]= |  |
| Out[11]= |  |
部分要素の指定
フレームワークはデフォルトではPartを使って部分要素をインポートする.
| Out[12]= |  |
いくつかの大きいデータ集合を含むファイルの場合,特定のデータ集合を直接インポートした方が効率がよいであろう.例えば"EDF"ファイル形式のファイルから直接データ集合をインポートすることができる.
| Out[13]= |  |
| Out[38]= |  |
低レベル関数を
の形式で登録することにより,部分要素のインポートを指定することができる.
低レベル関数の出力は
の形式にマッチしていなければならない.
これまでと同様に,他の低レベル関数の出力は
という形式の規則のリストでなければならない.
文字列の部分要素のインポートは,適切な低レベル関数を呼び出す.
| Out[20]= |  |
| Out[21]= |  |
ポストインポータ
他の要素に基づいた要素を構築しなければならない場合がある.例えば,インポートするデータがグレイスケール画像を表す数値のリストである場合,
要素のインポートにはまず
要素のインポートが必要になる.このセクションでは
要素と
要素を使った2つの例を紹介する.
ポストインポータはマッチする要素名が存在する場合は条件付きインポータの出力を入力として取る.それ以外の場合はポストインポータはデフォルトインポータの出力を入力として取る.
条件付きインポータおよびデフォルトインポータと異なり,ポストインポータは要素の値を返すだけである.
ポストインポータを使った新規形式の登録と実装
条件付きインポータとポストインポータとの違いを説明するために,
を2つの追加要素
と
で拡張する.
要素は条件付きインポータを介してインポートされるが,
要素はポストインポータを介してインポートされる.
次の登録はImportとExportフレームワークに形式
のファイルのインポート方法を指示するものである.
(1)
要素か
要素の場合は,対応する条件付きインポータを呼び出す.
(2)
要素の場合は,デフォルトインポータをまず呼び出してからその出力を
の入力として使う.
(3) その他すべての要素の場合は,デフォルトインポータを呼び出す.
条件付きインポータおよびデフォルトインポータは,前と同じ構造を持つ.
インポータは明示的にデフォルトインポータを呼び出し,手動でデータを抽出しなければならない.
条件付きインポータとして登録される
要素はないので,
要素のインポータはデフォルトインポータの出力を入力として取る.
MyFormat3を使ったインポート
ユーザの立場からすると,要素の実装にポストインポート関数が使われていても低レベル関数が使われていても差はない.

要素は条件付きインポータとして登録される.
| Out[27]= |  |

要素のインポートではポストインポータの

が呼ばれる.
| Out[28]= |  |
RegisterImportのオプション
には大きな柔軟性を可能にするオプションがいくつかある.
"FunctionChannels"と"BinaryFormat"
上の例では低レベル関数は引数としてファイル名を取り,そのファイルへのストリームを開く.
のオプションとして
を指定することにより,フレームワークはInputStreamを低レベル関数に直接渡すことができる.
オプション"BinaryFormat"->Trueを指定すると,フレームワークはバイナリストリームを低レベルインポータに渡す.
のデフォルト値は
である.
のデフォルト値はFalseである.
例
として登録された形式では,eFunc のシグネチャは
であり,フレームワークは eFunc に(非バイナリ)ストリームを渡す.
"AvailableElements"
条件付きインポータとしてもポストインポータとしても明示的に登録されていない要素をインポートする場合,デフォルトではフレームワークはデフォルトインポータを評価する.デフォルトインポータにマッチする要素が見付からない場合は,フレームワークはエラーメッセージを出力し,$Failedを返す.
指定されたリストに存在しない要素のインポートを試みる場合,オプション
を指定すると,フレームワークは直接$Failedを返し,低レベルインポータを呼ばずにエラーメッセージを出力する.
例
として登録された形式では,
Import[filename, {"format", "foo"}]を呼ぶと,フレームワークはデフォルトインポータの eDefaultFunc を評価せずに$Failedを返す.
と指定するのは誤りである.この場合,
が
により指定されたリストではないため,Import[filename, {"format", "elem2"}]は$Failedを返す.
"DefaultElement"
"DefaultElement"->elem(elem は要素の名前)を指定すると,Import要素が指定されていない場合にフレームワーク elem をインポートする.
"Sources"
オプション
は.mファイル,.mxファイル,低レベル関数の定義を含む MathLink .exeファイルへのファイルパスを指定するために使うことができる.フレームワークはソースファイルに応じてGetあるいはInstallを自動的に使い分ける.