Main Content

自定义代码建议和自动填充

要为您的函数和类自定义代码建议和自动填充,请向 MATLAB® 提供有关您的函数签名的信息。函数签名说明函数可接受的语法和允许的数据类型。MATLAB 使用此信息在编辑器、实时编辑器和命令行窗口中显示代码建议和自动填充。在名为 functionSignatures.json 的 JSON 格式文件中定义该函数信息。

要使 MATLAB 检测函数签名信息,您必须将 functionSignatures.json 放入包含函数代码的文件夹中。如果为类方法或包函数定义信息,必须将 functionSignatures.json 放在最外层类或包文件夹的父文件夹中。例如,要为 myClass 的方法定义信息,请将 functionSignatures.json 放在这些类和包结构体的 myFolder 文件夹中:

  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 函数根据 JSON 架构和 MATLAB 函数签名架构验证 functionSignatures.json 文件。

函数对象

要为函数定义信息,请创建一个与函数名称相同的属性。它的值是签名对象

{
  "functionName1": { signatureObj1 },
  "functionName2": { signatureObj2 }
}

要为类构造函数、类方法或包函数定义信息,请使用函数或方法的全名。例如,定义类构造函数、类方法 myMethod 和包函数 myFunction

{
  "myClass.myClass": { signatureObj },
  "myClass.myMethod": { signatureObj },
  "myPackage.myFunction": { signatureObj }
}

通过定义具有相同属性(函数或方法名称)的多个函数对象,可以为同一个函数或方法定义多个函数签名。有关详细信息,请参阅多个签名

签名对象

签名对象定义函数的输入和输出参数以及支持的平台。每个属性的值(platforms 属性除外)都是一个参数对象数组。

{
  "functionName1":
  {
     "inputs": [ argumentObj1, argumentObj2 ]
  }
}

如果在 JSON 文件中指定实例方法,如 myClass.myMethod,则 inputs 中的元素之一必须为 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 文件加以描述。以下函数接受:

  • 两个必需参数

  • 一个可选的位置参数(通过 varargin

  • 两个可选的名称-值对组参数(通过 varargin

此处使用 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 会指示参数是否为可选以及是否有多个建议(如第三个位置参数或一个名称-值对组)。列出名称-值对组选项。

向函数调用添加名称-值对组参数时,MATLAB 基于 JSON 文件提供选项。由于 'Name1' 定义为逻辑标量,因此 MATLAB 会自动填充选项(truefalse)。MATLAB 基于 JSON 文件显示 'Name2' 参数的三个值。

多个签名

如果一个函数有许多语法,则可以在代码建议中将语法分组为多个函数签名(不考虑函数实现)。要为多个签名提供代码建议和自动填充,请在 JSON 文件中创建具有相同属性的多个函数对象。

以如下函数为例,它根据第二个输入的类采用不同代码路径。此函数仅用作代码建议的示例,因此不执行任何计算或错误检查。

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

从代码建议的角度来看,将函数视为具有两个函数签名。第一个签名接受两个必需的数值。第二个签名接受一个必需的数值,然后是一个字符或字符串,最后是一个必需的数值。要定义多个函数签名,请使用相同的属性(函数名称)在 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"]}
            ]
           ]
        }
     ]
  }
}

另请参阅

相关主题

外部网站