Main Content

コードの候補と補完のカスタマイズ

関数とクラスのコードの候補と補完をカスタマイズするには、関数シグネチャに関する情報を MATLAB® に提供します。関数シグネチャは、関数で受け入れ可能な構文および許可されるデータ型を説明します。MATLAB は、エディター、ライブ エディターおよびコマンド ウィンドウにコードの候補と補完を表示するためにこの情報を使用します。この関数情報は functionSignatures.json という JSON 形式のファイルに定義します。

MATLAB によって関数シグネチャ情報を検出するには、関数コードがあるフォルダー内に functionSignatures.json を配置しなければなりません。クラス メソッドまたはパッケージ関数の情報を定義する場合は、最も外側のクラスまたはパッケージ フォルダーの親フォルダーに functionSignatures.json を配置しなければなりません。たとえば、myClass のメソッドの情報を定義するには、以下のクラスおよびパッケージ構造のフォルダー myFolder に functionSignatures.json を配置します。

  myFolder/+myPackage/@myClass
  myFolder/+myPackage/+mySubpackage/@myClass

クラスまたはパッケージ フォルダーの外部に配置されているクラスの場合は、クラス コードがあるフォルダー内に functionSignatures.json を配置します。同じファイルに複数の関数のシグネチャを定義できます。

functionSignatures.json ファイルには単一の JSON オブジェクトが含まれます。JSON では中かっこを使ってオブジェクトを定義し、名前と値のペアの集合としてオブジェクトを参照します。これらの用語は関数シグネチャのコンテキストにおいてオーバーロードされるので、"名前" の代わりに "プロパティ" が使用されます。functionSignatures.json 内の JSON オブジェクトには、オプションのスキーマ バージョンと "関数オブジェクト" のリストが含まれています。各関数オブジェクトには "シグネチャ オブジェクト" のリストが含まれ、各シグネチャ オブジェクトには "引数オブジェクト" の配列が含まれています。JSON では大かっこを使って配列を定義します。

オプションのスキーマ バージョンを指定するには最初のプロパティとして _schemaVersion を使用し、その値としてバージョン番号を使用します。バージョン番号を major#.minor#.patch# という形式の JSON 文字列として指定します。各番号には非負の整数を指定します。現在のスキーマ バージョンは 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 },
  "myPackage.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 はカスタムのコードの候補と補完を提供しません。

既定の設定はすべてのプラットフォームです。リストの要素は関数 computer から返される archstr に一致しなければなりません。リストは包含または排他にできますが、この両方にすることはできません。値の例としては "win64,maci64" や "-win64,-maci64" があります。

コンマ区切り値の文字列

引数オブジェクト

引数オブジェクトは、入力引数と出力引数のそれぞれについての情報を定義します。

{
  "functionName1":
  {
     "inputs":
     [
        {"name":"in1",  "kind":"required", "type":["numeric"]},
        {"name":"in2",  "kind":"required", "type":["numeric","integer","scalar"]}
     ]
  }
}

JSON ファイルにおける入力の出現順序は重要です。たとえば、関数 functionName1 への呼び出しでは in1 が in2 の前になければなりません。

各引数オブジェクトに次のプロパティを含めることができます。

 name – 引数の名前

 kind – 引数の種類

 type – 引数のクラスと属性

 repeating – 引数を複数回指定

 purpose – 引数の説明

さらに複雑な関数シグネチャについては、各引数オブジェクトに以下のプロパティを使用できます。

 platforms – サポートされるプラットフォームのリスト

 tuple – 引数のセットの定義

 mutuallyExclusiveGroup – 排他的な引数のセットの定義

関数シグネチャ ファイルの作成

この例では、関数についてカスタムのコードの候補と補完を作成する方法を説明します。

後の手順で 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 pair 
%       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 と同じフォルダー内で、次の関数シグネチャの記述を 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"]}
            ]
           ]
        }
     ]
  }
}

参考

関連するトピック

外部の Web サイト