Анализ аргументов расширения

Статья
06/15/2023

Платформа расширения EngExtCpp предоставляет методы для анализа аргументов командной строки, передаваемых в расширение. Чтобы воспользоваться этими методами, расширение должно сначала объявить формат аргументов командной строки в макросе EXT_COMMAND.

Чтобы обойти синтаксический анализ аргумента командной строки, выполненный платформой, и позволить самому расширению анализировать аргументы, задайте для описания командной строки описание "{{custom}}" и используйте метод GetRawArgStr , чтобы получить аргументы командной строки для синтаксического анализа.

Строки описания командной строки автоматически будут упакованы при печати, чтобы соответствовать ширине столбца дисплея. Однако новые символы могут быть внедрены в строки описания с помощью '\n' для запуска новых строк.

Описание командной строки может иметь значение NULL или пустую строку. В любом случае это означает, что команда расширения не принимает никаких аргументов.

Описание командной строки

Описание аргументов командной строки — это последовательность, содержащая два типа компонентов: директивы и аргументы. Описание может содержать одну из каждой директивы и может содержать до 64 аргументов.

Директивы

Директивы указывают способ синтаксического анализа аргументов. Они заключены в двойные скобки ('{{' и '}}'). Каждая директива может при необходимости отображаться ноль или один раз в строке, описывающей аргументы.

Доступны следующие директивы:

custom
Отключает синтаксический анализ, выполненный платформой расширений, и позволяет расширению выполнять собственный анализ.

l:str
Переопределяет длинное описание аргументов командной строки по умолчанию. Платформа расширений будет использовать str для полного описания всех аргументов.

opt:str
Переопределяет символы префикса по умолчанию для именованных команд. Значением по умолчанию является "/-"разрешение "" или "-/" в качестве префикса, определяющего именованные аргументы.

s:str
Переопределяет краткое описание аргументов командной строки по умолчанию. Платформа расширений будет использовать str для краткого описания всех аргументов.

Ниже приведены некоторые примеры директив. Следующая строка используется командой расширения, которая анализирует свои собственные аргументы. Он также предоставляет краткие и длинные описания для использования с автоматической командой расширения !help :

{{custom}}{{s:<arg1> <arg2>}}{{l:arg1 - Argument 1\narg2 - Argument 2}}

Следующая строка изменяет префикс параметра аргумента на "/" или "-". В этой директиве аргументы будут указаны с помощью "+arg" и "" вместо "" и:arg "/arg" и "-arg:

{{opt:+:}}

Аргументы

Аргументы могут иметь два типа: именованные и неименованные. Неименованные аргументы считываются позиционально. Оба типа аргумента также имеют отображаемое имя, используемое командой справки.

Описания аргументов заключены одними фигурными скобками ('{' и '}').

Каждое описание аргумента имеет следующий синтаксис:

{[optname];[type[,flags]];[argname];[argdesc]}

где:

optname
Имя аргумента. Это имя, используемое в командах и методах, которые извлекает аргументы по имени. Это имя является необязательным. Если он присутствует, аргумент становится "именованным аргументом"; он может отображаться в любой точке командной строки и ссылается по имени. Если он отсутствует, аргумент становится "неименованным аргументом"; его позиция в командной строке важна, и она ссылается на ее позицию относительно других неименованных аргументов.

type
Тип аргумента. Это влияет на то, как аргумент анализируется и как он извлекается. Параметр типа может иметь одно из следующих значений:

b
Логический тип. Аргумент присутствует или отсутствует. Именованные логические аргументы можно получить с помощью HasArg.

e[d][s][bits]
Тип выражения. Аргумент имеет числовое значение. Аргументы именованных выражений можно получить с помощью GetArgU64 и неназванных аргументов выражений можно получить с помощью GetUnnamedArgU64.

d
Выражение ограничено следующим символом пробела в строке аргумента. Если это не так, средство оценки выражений будет использовать символы из командной строки, пока не определит, что оно достигло конца выражения.

s
Значение выражения подписывается. В противном случае значение выражения не назначено.

Биты
Число битов в значении аргумента. Максимальное значение для битов равно 64.

s
Тип строки. Строка ограничена следующим символом пробела. Именованные строковые аргументы можно получить с помощью GetArgStr и неименованных строковых аргументов можно получить с помощью GetUnnamedArgStr.

x
Тип строки. Аргумент является остальной частью командной строки. Аргумент извлекается с помощью GetArgStr или GetUnnamedArgStr, как и в строковом типе.

flags
Флаги аргументов. Они определяют способ обработки аргумента синтаксического анализа. Параметр флагов может иметь одно из следующих значений:

d=expr
Значение по умолчанию аргумента. Если аргумент отсутствует в командной строке, аргумент имеет значение expr. Значение по умолчанию — это строка, которая анализируется в соответствии с типом аргумента.

ds
Значение по умолчанию не будет отображаться в описании аргумента, предоставленном справкой.

o
Аргумент не обязателен. Это значение по умолчанию для именованных аргументов.

r
Аргумент является обязательным. Это значение по умолчанию для неименованных аргументов.

argname
Отображаемое имя аргумента. Это имя, используемое командой автоматического расширения !help и автоматическими аргументами /? или -? командной строки. Используется при печати сводки параметров командной строки.

argdesc
Описание аргумента. Это описание, напечатанное автоматическим расширением !help и автоматическими аргументами командной строки "/?"" или "-?".

Ниже приведены некоторые примеры описания аргументов. Следующее выражение определяет команду, которая принимает один необязательный аргумент выражения. Аргумент должен соответствовать 32 битам. Если аргумент отсутствует в командной строке, будет использоваться значение по умолчанию 0x100.

{;e32,o,d=0x100;flags;Flags to control command}

Следующее выражение определяет команду с необязательным логическим аргументом "/v" и обязательным неименованным строковым аргументом.

{v;b;;Verbose mode}{;s;name;Name of object}

Следующее выражение определяет команду, которая имеет необязательный именованный аргумент выражения /oname expr и необязательный именованный строковый аргумент /eol str. Если параметр /eol присутствует, его значение будет задано в оставшейся части командной строки, а дальнейшие аргументы не будут проанализированы.

{oname;e;expr;Address of object}{eol;x;str;Commands to use}

Командная строка

Ниже приведен список способов анализа аргументов в командной строке:

Значения именованных выражений и строковых аргументов следуют имени в командной строке. Например, /name expr или /name str.
Для именованных логических аргументов значение равно true, если имя отображается в командной строке; False в противном случае.
В командной строке можно сгруппировать несколько логического параметров с одним символом. Например, "/a/b /c" можно написать с помощью краткой нотации "/abc" (если аргумент с именем abc еще не существует).
Если в командной строке содержится именованный аргумент "?", например "/?" и "-?" — концы синтаксического анализа аргументов, а текст справки для расширения отображается.

Анализ внутренних компонентов

Для задания аргументов используются несколько методов синтаксического анализа аргументов.

Метод SetUnnamedArg изменит значение неназванного аргумента. Для удобства методы SetUnnamedArgStr и SetUnnamedArgU64 будут задавать аргументы без именованных строк и выражений соответственно.

Аналогичные методы существуют для именованных аргументов. SetArg используется для изменения значения любого именованного аргумента и SetArgStr и SetArgU64 для аргументов именованных строк и выражений соответственно.

Поделиться через