Настройте предложения кода и завершения

Чтобы настроить предложения кода и завершения для ваших функций и классов, обеспечьте MATLAB® с информацией о ваших функциональных подписях. Функциональные подписи описывают приемлемые синтаксисы и допустимые типы данных для функции. MATLAB использует эту информацию, чтобы отобразить предложения кода и завершения в Редакторе, Live Editor и Командном окне. Задайте эту функциональную информацию в JSON-отформатированном файле под названием functionSignatures.json.

Для MATLAB, чтобы обнаружить функциональную информацию о подписи, необходимо поместить functionSignatures.json в папке, которая содержит функциональный код. Если вы задаете информацию для метода класса или функции пакета, необходимо поместить functionSignatures.json в родительской папке наиболее удаленного класса или папке пакета. Например, чтобы задать информацию для метода myClass, поместите functionSignatures.json в папке myFolder поскольку они классифицируют и структуры пакета:

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

Для классов, расположенных за пределами класса или папок пакета, поместите functionSignatures.json в папке, которая содержит код класса. Можно задать подписи для нескольких функций в том же файле.

functionSignatures.json файл содержит один объект JSON. JSON использует фигурные скобки, чтобы задать объекты и называет объекты наборами пар значения и имени. Поскольку эти термины перегружаются в контексте функциональных подписей, "свойство" используется вместо "имени". Объект JSON в functionSignatures.json содержит дополнительную версию схемы и список function objects. Каждый функциональный объект содержит список signature objects, и каждый объект подписи содержит массив argument objects. JSON использует скобки, чтобы задать массивы.

Чтобы задать дополнительную версию схемы используют _schemaVersion как первое свойство и номер версии как его значение. Задайте номер версии как строку JSON в формате major#.minor#закрашенная фигура, с каждым номером, заданным как неотрицательное целое число. Текущей версией схемы является 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 должен быть объект myClass. Как правило, этот объект является первым элементом. MATLAB поддерживает предложения кода и завершения для заданного метода, когда вы вызываете его с помощью любой записи через точку (b = myObj.myMethod(a)) или функциональное обозначение (b = myMethod(myObj,a)Синтаксис.

Каждая подпись в файле JSON может включать следующие свойства.

СвойствоОписаниеТип данных JSON значения
inputs

Список входных аргументов функции. MATLAB использует это свойство для предложений кода и завершений.

Массив объектов аргумента

outputs

Список выходных аргументов функции. MATLAB использует это свойство совершенствовать предложения кода и завершения.

Массив объектов аргумента

platforms

Список платформ, которые поддерживают функцию. MATLAB не представляет предложения пользовательского кода и завершения, если платформа не поддерживает функцию.

Значением по умолчанию являются все платформы. Элементы списка должны совпадать с archstr возвращенный из computer функция. Список может быть включен или исключен, но не оба. Значениями в качестве примера является "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 из скрипта или live скрипта. Имена и цели из файла JSON появляются. MATLAB указывает, когда аргументы являются дополнительными и если существует несколько доступных предложений (таких как третий позиционный параметр или пара "имя-значение"). Опции пар "имя-значение" перечислены.

При добавлении аргумента пары "имя-значение" вызову функции MATLAB представляет выбор из файла JSON. Начиная с 'Name1' задан как логический скаляр, MATLAB заполняет выбор автоматически (true или false). MATLAB принимает эти три значения для 'Name2' аргумент из файла JSON.

Несколько подписей

Если функция имеет много синтаксисов, может быть полезно для предложений кода сгруппировать синтаксисы как несколько функциональных подписей (независимо от реализации функции). Чтобы обеспечить предложения кода и завершения для нескольких подписей, создайте несколько функциональных объектов с тем же свойством в файле 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"]}
            ]
           ]
        }
     ]
  }
}

Смотрите также

Похожие темы

Внешние веб-сайты

Для просмотра документации необходимо авторизоваться на сайте