インポートコンバータの開発

Wolfram言語は,ユーザが自分のファイル形式コンバータを書き,それをWolfram言語のImportExportフレームワークと統合させることのできる関数を提供している.形式コンバータを実装し,Importを使って任意の形式からデータをインポートすることができる.

Wolframシステムには形式コンバータの実装および登録方法を説明するソースコードも含まれている.これらはフォルダ$InstallationDirectory/SystemFiles/Formats/format にある.ここで formatBDFDIFMTPSMILESSurferGridTGFTLEのいずれかである.登録コードはファイルImport.mまたはExport.mにあり,コンバータの実装はConverter.mというファイルにある.

Importと低レベルのコンバータ関数との間のインターフェースは,ImportExport`コンテキスト)で指定される.基本的にImportExportフレームワークに,あるファイル形式の特定の要素をインポートするときに特定の関数を呼び出す方法を指示する.

このチュートリアルでは,次のような用語が使われている.

低レベル関数はファイルあるいはストリームを入力として取り,インポートされたデータを含む規則のリストを返す.低レベル関数には次の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列の数字を含むファイル形式があるとする.

新規形式の登録と実装

一つの方法として,ヘッダ情報と数字をそれぞれ要素,要素にインポートするというものがある.これはを使って実装することもできる,

In[2]:=
Click for copyable input

この場合,ImportExportフレームワークに対して,形式のどの要素をインポートするときでも,関数を呼び出すよう指示している.

フレームワークはデフォルトではファイル名を低レベル関数に渡すので,は入力としてファイル名とオプションの集合を取る.この関数はという形式の規則のリストを返さなければならない.

In[3]:=
Click for copyable input

新しい形式のファイルのインポート

これでImportの有効なファイル形式としてが使えるようになった.

In[4]:=
Click for copyable input
Out[4]=
In[5]:=
Click for copyable input
Out[5]=
In[6]:=
Click for copyable input
Out[6]=

条件付未加工インポータ

形式に多数の要素が含まれる場合,特定の低レベル関数を使って特定の要素をインポートすると便利で効率的なことがある.これはの第2引数として "elem"->func という形式の規則のリストを与えることで実行できる.しかし,リストはリスト中で明示的に定義されているどれともマッチしない要素をインポートするときに呼ばれる,デフォルトインポータの名前で終了しなければならない.

条件付インポータによる新規形式の登録と実装

この登録はImportExportフレームワークに,形式のファイルのエキスポート方法を指示する.

(1) 要素をインポートするときはを使う
(2) その他すべてにはを使う

In[7]:=
Click for copyable input

低レベル関数は同じ構造を持つ.ファイル名とオプショナルのオプションのリストを取り,という形式の規則の集合を返す.

In[8]:=
Click for copyable input
In[9]:=
Click for copyable input

MyFormat2を使ったインポート

のインポート要素の出力はのものと同じであるが,2つの異なる要素に対して2つの異なる関数が呼び出される.

In[10]:=
Click for copyable input
Out[10]=
In[11]:=
Click for copyable input
Out[11]=

部分要素の指定

フレームワークはデフォルトではPartを使って部分要素をインポートする.

In[12]:=
Click for copyable input
Out[12]=

いくつかの大きいデータ集合を含むファイルの場合,特定のデータ集合を直接インポートした方が効率がよいであろう.例えば"EDF"ファイル形式のファイルから直接データ集合をインポートすることができる.

In[13]:=
Click for copyable input
Out[13]=
In[35]:=
Click for copyable input
In[38]:=
Click for copyable input
Out[38]=

低レベル関数を の形式で登録することにより,部分要素のインポートを指定することができる.

In[16]:=
Click for copyable input

低レベル関数の出力はの形式にマッチしていなければならない.

In[17]:=
Click for copyable input

これまでと同様に,他の低レベル関数の出力は という形式の規則のリストでなければならない.

In[18]:=
Click for copyable input
In[19]:=
Click for copyable input

文字列の部分要素のインポートは,適切な低レベル関数を呼び出す.

In[20]:=
Click for copyable input
Out[20]=
In[21]:=
Click for copyable input
Out[21]=

ポストインポータ

他の要素に基づいた要素を構築しなければならない場合がある.例えば,インポートするデータがグレイスケール画像を表す数値のリストである場合,要素のインポートにはまず要素のインポートが必要になる.このセクションでは要素と要素を使った2つの例を紹介する.

ポストインポータはマッチする要素名が存在する場合は条件付きインポータの出力を入力として取る.それ以外の場合はポストインポータはデフォルトインポータの出力を入力として取る.

条件付きインポータおよびデフォルトインポータと異なり,ポストインポータは要素の値を返すだけである.

ポストインポータを使った新規形式の登録と実装

条件付きインポータとポストインポータとの違いを説明するために,を2つの追加要素で拡張する.要素は条件付きインポータを介してインポートされるが,要素はポストインポータを介してインポートされる.

次の登録はImportExportフレームワークに形式のファイルのインポート方法を指示するものである.
(1) 要素か要素の場合は,対応する条件付きインポータを呼び出す.
(2) 要素の場合は,デフォルトインポータをまず呼び出してからその出力をの入力として使う.
(3) その他すべての要素の場合は,デフォルトインポータを呼び出す.

In[22]:=
Click for copyable input

条件付きインポータおよびデフォルトインポータは,前と同じ構造を持つ.

In[23]:=
Click for copyable input
In[24]:=
Click for copyable input

インポータは明示的にデフォルトインポータを呼び出し,手動でデータを抽出しなければならない.

In[25]:=
Click for copyable input

条件付きインポータとして登録される要素はないので,要素のインポータはデフォルトインポータの出力を入力として取る.

In[26]:=
Click for copyable input

MyFormat3を使ったインポート

ユーザの立場からすると,要素の実装にポストインポート関数が使われていても低レベル関数が使われていても差はない.

要素は条件付きインポータとして登録される.
In[27]:=
Click for copyable input
Out[27]=
要素のインポートではポストインポータのが呼ばれる.
In[28]:=
Click for copyable input
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"->elemelem は要素の名前)を指定すると,Import要素が指定されていない場合にフレームワーク elem をインポートする.

"Sources"

オプションは.mファイル,.mxファイル,低レベル関数の定義を含むWolfram Symbolic Transfer Protocol (WSTP) .exeファイルへのファイルパスを指定するために使うことができる.フレームワークはソースファイルに応じてGetあるいはInstallを自動的に使い分ける.