コードの候補と補完のカスタマイズ
関数とクラスのコードの候補と補完をカスタマイズするには、関数シグネチャに関する情報を MATLAB® に提供します。関数シグネチャは、関数で受け入れ可能な構文および許可されるデータ型を説明します。MATLAB は、エディター、ライブ エディターおよびコマンド ウィンドウにコードの候補と補完を表示するためにこの情報を使用します。この関数情報は functionSignatures.json という JSON 形式のファイルで定義します。MATLAB では、arguments ブロックを含む関数のコードの補完と候補を、arguments ブロックに含まれている情報に基づいて提供できます。この情報は、functionSignatures.json ファイルがなくても使用できます。カスタムのコードの候補と補完は MATLAB Online ではサポートされていません。
MATLAB で関数シグネチャ情報を検出するには、関数コードがあるフォルダー内の resources フォルダーに functionSignatures.json を配置します。クラス メソッドまたは名前空間関数の情報を定義する場合は、最も外側のクラスまたは名前空間フォルダーの親フォルダーにある resources フォルダーに functionSignatures.json を配置します。たとえば、myClass のメソッドの情報を定義するには、以下のクラスおよび名前空間構造の myFolder にある resources フォルダーに functionSignatures.json を配置します。
myFolder/+myNamespace/@myClass myFolder/+myNamespace/+mySubnamespace/@myClass
クラスまたは名前空間フォルダーの外部に配置されているクラスの場合は、クラス コードがあるフォルダー内の resources フォルダーに functionSignatures.json を配置します。同じファイルに複数の関数のシグネチャを定義できます。
functionSignatures.json ファイルには単一の JSON オブジェクトが含まれます。JSON では中かっこを使ってオブジェクトを定義し、名前と値のペアの集合としてオブジェクトを参照します。これらの用語は関数シグネチャのコンテキストにおいてオーバーロードされるので、"名前" の代わりに "プロパティ" が使用されます。functionSignatures.json 内の JSON オブジェクトには、オプションのスキーマ バージョンと "関数オブジェクト" のリストが含まれています。各関数オブジェクトには "シグネチャ オブジェクト" のリストが含まれ、各シグネチャ オブジェクトには "引数オブジェクト" の配列が含まれています。JSON では大かっこを使って配列を定義します。
オプションのスキーマ バージョンを指定するには最初のプロパティとして _schemaVersion を使用し、その値としてバージョン番号を使用します。バージョン番号を major#.minor#.patch#1.0.0 です。ファイルにスキーマ バージョンを指定しない場合、MATLAB はバージョン 1.0.0 を仮定します。
functionSignatures.json に構文エラーが含まれる場合、MATLAB がファイルを読み取るときに、コマンド ウィンドウにエラー メッセージが表示されます。関数 validateFunctionSignaturesJSON を使用して functionSignatures.json ファイルを JSON スキーマと MATLAB 関数シグネチャ スキーマに対して検証します。
関数オブジェクト
関数の情報を定義するには、関数名と同じプロパティを作成します。その値がシグネチャ オブジェクトです。
{
"functionName1": { signatureObj1 },
"functionName2": { signatureObj2 }
}クラス コンストラクター、クラス メソッド、または名前空間関数の情報を定義するには、関数またはメソッドの完全名を使用します。たとえば、クラス コンストラクター、クラス メソッド myMethod、および名前空間関数 myFunction を定義します。
{
"myClass.myClass": { signatureObj },
"myClass.myMethod": { signatureObj },
"myNamespace.myFunction": { signatureObj }
}同じプロパティ (関数名またはメソッド名) をもつ複数の関数オブジェクトを定義することによって、同じ関数またはメソッドに複数の関数シグネチャを定義できます。詳細については、複数のシグネチャを参照してください。
シグネチャ オブジェクト
シグネチャ オブジェクトは、関数の入力引数と出力引数およびサポートされているプラットフォームを定義します。platforms プロパティを除き、各プロパティの値は引数オブジェクトの配列です。
{
"functionName1":
{
"inputs": [ argumentObj1, argumentObj2 ]
}
}myClass.myMethod などのインスタンス メソッドを JSON ファイル内で指定する場合は、inputs の要素の 1 つが myClass のオブジェクトでなければなりません。通常、このオブジェクトは最初の要素です。指定したメソッドをドット表記 (b = myObj.myMethod(a)) または関数表記 (b = myMethod(myObj,a)) 構文を使用して呼び出すときに、MATLAB は、そのメソッドのコードの候補と補完をサポートします。
JSON ファイル内の各シグネチャには、以下のプロパティを含めることができます。
| プロパティ | 説明 | 値の JSON データ型 |
|---|---|---|
inputs | 関数の入力引数のリスト。MATLAB はコードの候補と補完のためにこのプロパティを使用します。 | 引数オブジェクトの配列 |
outputs | 関数の出力引数のリスト。MATLAB は、コードの候補と補完を調整するためにこのプロパティを使用します。 | 引数オブジェクトの配列 |
platforms | 関数をサポートするプラットフォームのリスト。プラットフォームで関数がサポートされていない場合、MATLAB はカスタムのコードの候補と補完を提供しません。 既定の設定はすべてのプラットフォームです。リストの要素は関数 | コンマ区切り値の文字列 |
引数オブジェクト
引数オブジェクトは、入力引数と出力引数のそれぞれについての情報を定義します。
{
"functionName1":
{
"inputs":
[
{"name":"in1", "kind":"required", "type":["numeric"]},
{"name":"in2", "kind":"required", "type":["numeric","integer","scalar"]}
]
}
}JSON ファイルにおける入力の出現順序は重要です。たとえば、関数 functionName1 への呼び出しでは in1 が in2 の前になければなりません。
各引数オブジェクトに次のプロパティを含めることができます。
さらに複雑な関数シグネチャについては、各引数オブジェクトに以下のプロパティを使用できます。
関数シグネチャ ファイルの作成
この例では、関数についてカスタムのコードの候補と補完を作成する方法を説明します。
後の手順で JSON ファイルにシグネチャを記述する関数を作成します。次の関数は以下を受け入れます。
2 つの必須の引数
vararginからの 1 つのオプションの位置引数vararginからの 2 つのオプションの名前と値の引数
myFunc はコードの候補を示すためのものであり、引数のチェックは含まれていません。
% myFunc Example function % This function is called with any of these syntaxes: % % myFunc(in1, in2) accepts 2 required arguments. % myFunc(in1, in2, in3) also accepts an optional 3rd argument. % myFunc(___, NAME, VALUE) accepts one or more of the following name-value % arguments. This syntax can be used in any of the previous syntaxes. % * 'NAME1' with logical value % * 'NAME2' with 'Default', 'Choice1', or 'Choice2' function myFunc(reqA,reqB,varargin) % Initialize default values NV1 = true; NV2 = 'Default'; posA = []; if nargin > 3 if rem(nargin,2) posA = varargin{1}; V = varargin(2:end); else V = varargin; end for n = 1:2:size(V,2) switch V{n} case 'Name1' NV1 = V{n+1}; case 'Name2' NV2 = V{n+1} otherwise error('Error.') end end end end
myFunc と同じフォルダーにある resources フォルダーで、次の関数シグネチャの記述を functionSignatures.json というファイルに作成します。入力名は myFunc の本体にある名前に一致しませんが、ヘルプ テキストと一致しています。
{
"_schemaVersion": "1.0.0",
"myFunc":
{
"inputs":
[
{"name":"in1", "kind":"required", "type":["numeric"], "purpose":"ID of item"},
{"name":"in2", "kind":"required", "type":["numeric"], "purpose":"# Items"},
{"name":"in3", "kind":"ordered", "type":["numeric"], "purpose":"Input Value"},
{"name":"Name1", "kind":"namevalue", "type":["logical","scalar"],"purpose":"Option"},
{"name":"Name2", "kind":"namevalue", "type":["char", "choices={'Default','Choice1','Choice2'}"]}
]
}
}
MATLAB はコードの候補と補完のためにこの関数シグネチャの記述を使用します。
関数シグネチャ情報の使用方法
MATLAB は、JSON ファイル内の関数シグネチャ情報を使用して、入力の途中で一致する構文を表示します。また、Tab キーを押すことにより、部分的に入力したテキストを完成させることもできます。コマンド ウィンドウでは、MATLAB は JSON ファイルを使用して、入力の途中で一致する構文を表示しません。
コードの候補を試行するには、スクリプトまたはライブ スクリプトから myFunc の呼び出しを開始します。JSON ファイルからの名前や目的が表示されます。MATLAB は、引数がオプションである場合や、複数の候補を利用できるかどうか (3 番目の位置引数、名前と値の引数など) を示します。名前と値の引数のオプションがリストされます。
名前と値の引数を関数呼び出しに追加すると、MATLAB に JSON ファイルからの選択肢が表示されます。'Name1' が logical スカラーとして定義されているので、MATLAB は選択肢を自動的に設定します (true または false)。MATLAB は、JSON ファイルから 'Name2' 引数の 3 つの値を取得します。
複数のシグネチャ
関数に多くの構文がある場合、コードの候補で構文を複数の関数シグネチャとして (関数の実装とは関係なく) グループ化すると便利なことがあります。複数のシグネチャのコードの候補と補完を提供するには、同じプロパティをもつ関数オブジェクトを JSON ファイルに複数作成します。
2 番目の入力のクラスに応じて異なるコード パスをたどる、次の関数について考えます。この関数は、コードの候補の例として提供されているので、計算やエラー チェックは一切行いません。
function anotherFunc(arg1,arg2,arg3) switch class(arg2) case 'double' % Follow code path 1 case {'char','string'} % Follow code path 2 otherwise error('Invalid syntax.') end end
コードの候補という観点から、関数が 2 つの関数シグネチャをもつと仮定します。最初のシグネチャは 2 つの必須の数値を受け入れます。2 番目のシグネチャは、必須の数値を 1 つ、その後に文字または文字列を 1 つ、最後に必須の数値を 1 つ受け入れます。複数の関数シグネチャを定義するには、JSON ファイルに同じプロパティ (関数名) をもつ複数の関数オブジェクトを定義します。
{
"_schemaVersion": "1.0.0",
"anotherFunc":
{
"inputs":
[
{"name":"input1", "kind":"required", "type":["numeric"]},
{"name":"input2", "kind":"required", "type":["numeric"]}
]
},
"anotherFunc":
{
"inputs":
[
{"name":"input1", "kind":"required", "type":["numeric"]},
{"name":"input2", "kind":"required", "type":[["char"],["string"]]},
{"name":"input3", "kind":"required", "type":["numeric"]}
]
}
}あるいは、引数オブジェクトの mutuallyExclusiveGroup プロパティを使って複数の関数シグネチャを定義することもできます。通常は、複数の関数オブジェクトを実装する方が簡単で読みやすくなりますが、相互に排他的なグループを使用することで、input1 などの共通する引数グループを再利用することが可能になります。
{
"_schemaVersion": "1.0.0",
"anotherFunc":
{
"inputs":
[
{"name":"input1", "kind":"required", "type":["numeric"]},
{"mutuallyExclusiveGroup":
[
[
{"name":"input2", "kind":"required", "type":["numeric"]}
],
[
{"name":"input2", "kind":"required", "type":[["char"],["string"]]},
{"name":"input3", "kind":"required", "type":["numeric"]}
]
]
}
]
}
}参考
validateFunctionSignaturesJSON
