diff --git a/docs/README.md b/docs/README.md index f4190a3..eced614 100644 --- a/docs/README.md +++ b/docs/README.md @@ -11,5 +11,5 @@ ## Итоговая документация -* [Модуль ArgParser](../lib/argparser/docs/README.md) +* [Модуль ArgParser, v1.1.0](https://github.com/bialger/ArgParser/blob/v1.1.0/lib/argparser/docs/README.md) * [Мануал weather-forecast](WeatherForecast.md) diff --git a/docs/dev/architecture.md b/docs/dev/architecture.md index 5953ce7..9a2c5a8 100644 --- a/docs/dev/architecture.md +++ b/docs/dev/architecture.md @@ -10,7 +10,7 @@ * Используется модуль UI для взаимодействия с пользовательским вводом любого рода и вывода информации. -* Используется модуль [ArgParser](../../lib/argparser/docs/README.md) - подсистема +* Используется модуль [ArgParser](https://github.com/bialger/ArgParser/tree/v1.1.0) - подсистема для обработки аргументов командной строки. * Используется модуль Forecast для выполнения и обработки запросов прогноза. * Используется библиотека [C++ Requests](https://github.com/libcpr/cpr) для выполнения HTTP-запросов. @@ -26,13 +26,11 @@ title: Project system diagram --- flowchart LR - subgraph Independent systems + subgraph Third-party libraries nodeArgParser([ArgParser]) - subgraph Third-party libraries - nodeCPR([C++ Requests]) - nodeJSON([JSON]) - nodeFTXUI([FTXUI]) - end + nodeCPR([C++ Requests]) + nodeJSON([JSON]) + nodeFTXUI([FTXUI]) end nodeForecast([Forecast]) nodeUI([UI]) @@ -325,165 +323,3 @@ Internet-запроса. Этот класс является абстракцией для представления погоды за наименьший временной промежуток: время суток. Должен иметь публичные поля для всех характеристик и метод, универсально возвращающий их всех. - -### Архитектура подсистемы "ArgParser" - -Эта подсистема представляет собой набор классов и связей между ними, которые выполняют -непосредственно парсинг аргументов командной строки, передаваемых в подсистему. Все -классы находятся в пространстве имён ArgumentParser. - -#### UML-диаграмма - -```mermaid ---- -title: Diagram of the module ArgParser ---- -%%{ - init: { - 'theme': 'base', - 'classDiagram': { 'curve': 'linear' }, - } -}%% -classDiagram - direction TB - note for ArgParser "Has pseudonym functions for AddArgument and GetValue for each argument type" - class ArgParser { - -const char[] name_; - -vector~ArgumentBuilder*~ argument_builders_; - -vector~Argument*~ arguments_; - -vector~string~ allowed_typenames_; - -vector~string~ allowed_typenames_for_help_; - -map~string, map~ string, size_t~~ arguments_by_type_; - -map~char, string~ short_to_long_names_; - -size_t help_index_; - +Parse(vector~string~ args, ConditionalOutput error_output=()) bool - +Parse(int argc, char[][] argv, ConditionalOutput error_output=()) bool - +Help() bool - +HelpDescription() string - +AddHelp(char short_name, const char[] long_name, const char[] description="") ConcreteArgumentBuilder~bool~ & - +AddHelp(const char[] long_name, const char[] description="") ConcreteArgumentBuilder~bool~ & - +AddArgument~T~(char short_name, const char[] long_name, const char[] description="") ConcreteArgumentBuilder~T~ & - +AddArgument~T~(const char[] long_name, const char[] description="") ConcreteArgumentBuilder~T~ & - +GetValue~T~(const char[] long_name, size_t index=0) T - -Parse_(vector~string~ args, ConditionalOutput error_output) bool - -GetLongKeys(string current_argument) vector~string~ - -ParsePositionalArguments(vector~string~ argv, const vector~size_t~ & used_positions) void - -HandleErrors(ConditionalOutput error_output) bool - -RefreshArguments() void - -AddArgument_~T~(char short_name, const char[] long_name, const char[] description) ConcreteArgumentBuilder~T~ & - -GetValue_~T~(const char* long_name, size_t index) T - } - class Argument { - <> - +ValidateArgument(vector~string~ argv, size_t position)* vector~size_t~ - +CheckLimit()* bool - +GetValueStatus()* ArgumentParsingStatus - +GetType()* string - +GetInfo()* ArgumentInformation - +GetUsedValues()* size_t - +ClearStored()* void - #ObtainValue(vector~string~ argv, string& value_string, vector~size_t~ & used_values, size_t position)* size_t - } - class ArgumentBuilder { - <> - +GetInfo()* ArgumentInformation - +GetDefaultValue()* string - +build()* Argument* - } - class ConcreteArgument~T~ { - -ArgumentInformation info_ - -ArgumentParsingStatus value_status_ - -size_t value_counter_ - -T value_ - -T default_value_ - -T* stored_value_ - -vector~T~* stored_values_ - +GetValue(size_t index) T - +ValidateArgument(vector~string~ argv, size_t position) vector~size_t~ - +CheckLimit() bool - +GetValueStatus() ArgumentParsingStatus - +GetType() string - +GetInfo() ArgumentInformation - +GetUsedValues() size_t - +ClearStored() void - #ObtainValue(vector~string~ argv, string& value_string, vector~size_t~ & used_values, size_t position) size_t - } - class ConcreteArgumentBuilder~T~ { - -ArgumentInformation info_; - -T default_value_; - -T* stored_value_; - -vector~T~* stored_values_; - -bool was_created_temp_vector_; - +MultiValue(size_t min=0) ConcreteArgumentBuilder & - +Positional() ConcreteArgumentBuilder& - +StoreValue(T& value) ConcreteArgumentBuilder& - +StoreValues(vector~T~ & values) ConcreteArgumentBuilder& - +Default(T value) ConcreteArgumentBuilder& - +AddValidate(function~bool(string&)~ validate) ConcreteArgumentBuilder& - +AddIsGood(function~bool(string&)~ is_good) ConcreteArgumentBuilder& - +GetInfo() ArgumentInformation - +GetDefaultValue() string - +build() Argument*` - } - class ArgumentInformation { - +char short_key = kBadChar - +const char[] long_key = "" - +const char[] description = "" - +string type - +size_t minimum_values = 0 - +bool is_multi_value = false - +bool is_positional = false - +bool has_store_values = false - +bool has_store_value = false - +bool has_default = false - +function~bool(string&)~ validate = &AlwaysTrue - ++function~bool(string&)~ is_good = &AlwaysTrue - } - class ArgumentParsingStatus { - <> - NoArgument - InvalidArgument - InsufficientArguments - Success - } - - ArgParser *-- Argument - ArgParser *-- ArgumentBuilder - ArgParser <.. ConcreteArgument - ArgParser <.. ConcreteArgumentBuilder - Argument <|.. ConcreteArgument - ArgumentBuilder <.. Argument - ArgumentBuilder <|.. ConcreteArgumentBuilder - ConcreteArgument *-- ArgumentInformation - ConcreteArgument *-- ArgumentParsingStatus - ConcreteArgumentBuilder <.. ConcreteArgument - ConcreteArgumentBuilder *-- ArgumentInformation -``` - -#### Класс ArgParser - -Этот класс является основным классом модуля, именно с ним обычно взаимодействует -пользователь. Он должен предоставлять следующие возможности: добавление обрабатываемого -аргумента (любого из указанных) с указанным ключом, парсинг набора аргументов командной -строки, а также функция добавления аргумента. Кроме того, должен иметь функцию -составления справки и обрабатывать ошибки в синтаксисе аргументов командной строки, -и, в некоторых случаях, выводить их. - -#### Класс ArgumentBuilder - -Этот класс реализует паттерн проектирования "Builder": ссылки на объекты наследников -этого класса должна возвращать функция добавления аргумента из ArgParser, к нему -должен обращаться пользователь, добавляя информацию об аргументе. Должен -реализовывать функции добавления любой информации про аргумент, представленные в -[тестах](../../tests/argparser_unit_tests.cpp) и функцию построения. Ему должен -наследовать шаблонизированный класс конкретного Builder, который будет реализовывать -вышеуказанный функционал для каждого из типов аргумента. - -#### Класс Argument - -Этот класс является родительским классом для всех классов аргументов. Должен иметь -функции возврата статуса парсинга и возврата информации об аргументе, а также функцию -получения значения аргумента из аргументов командной строки. Необходимая информация, -не изменяемая в процессе парсинга, должна храниться в виде экземпляра структуры. -На данный момент планируется аргументы всех базовых значащих типов (кроме 8-битных -чисел), StringArgument и ComplexArgument (строка с валидацией и чтением пробелов). diff --git a/lib/argparser/docs/ArgParser.md b/lib/argparser/docs/ArgParser.md deleted file mode 100644 index e274de5..0000000 --- a/lib/argparser/docs/ArgParser.md +++ /dev/null @@ -1,136 +0,0 @@ -# Документация класса ArgParser - -Этот класс является основным классом модуля, именно с ним обычно взаимодействует -пользователь. Он предоставляет следующие возможности: добавление обрабатываемого -аргумента (любого из указанных) с указанным ключом, парсинг набора аргументов командной -строки, а также добавление аргумента указанного типа. Кроме того, он имеет функцию -составления справки и обработки ошибки в синтаксисе аргументов командной строки, а -также их вывода. Находится в пространстве имён `ArgumentParser`. - -## Объявление и определение - -Объявлен в [ArgParser.hpp](../ArgParser.hpp).
-Определен там же (шаблонные функции) и в [ArgParser.cpp](../ArgParser.cpp) - -## Зависимости - -Зависит от [BasicFunctions.hpp](../basic/BasicFunctions.hpp), -[ConcreteArgument.hpp](../ConcreteArgument.hpp), -[ConcreteArgumentBuilder.hpp](../ConcreteArgumentBuilder.hpp). - -## Связанные документы - -* Документация класса [ConcreteArgumentBuilder](ConcreteArgumentBuilder.md) - -информация о задании параметров аргументов. - -## Публичные поля - -Класс не имеет публичных полей. - -## Публичные методы - -### ArgParser - -Принимает имя программы, явный. Ожидается, вызов пользователем именно его. -```cpp -explicit ArgParser(const char* name = ""); -``` -Удален конструктор копирования (как и оператор присваивания) -```cpp -ArgParser(const ArgParser& other) = delete; -ArgParser& operator=(const ArgParser& other) = delete; -``` - -### Parse -Функция парсинга. Вызывает приватный метод Parse_, который выполняет парсинг -аргументов командной строки, переданных в виде `std::vector` из `std::string` -(параметр *args*). Принимает `ConditionalOutput` параметр error_output, по умолчанию -не выводящий ошибки. Возвращает `true` при успешном завершении парсинга, -и `false` в случае его провала. - -Синтаксис аргументов частично POSIX-совместимый (поддерживается передача значений -через "=" или пробел после ключа, коротки и длинные ключи, комбинация коротких -ключей, остановка парсинга по аргументу "--", получение множества значений в аргумент). -```cpp -bool Parse(const std::vector& args, ConditionalOutput error_output = {std::cout, false}); -``` -Перегрузка Parse с тем же функционалом, но принимающая *C-style array* из -*C-style string* длиной *argc* вместо `std::vector` из `std::string`. -```cpp -bool Parse(int argc, char** argv, ConditionalOutput error_output = {std::cout, false}); -``` - -### Help -Функция, проверяющая необходимость вывода помощи. Возвращает `true` при получении -положительного значения HelpArgument, и `false` в случае его отсутствия или -негативного значения после парсинга. -```cpp -bool Help(); -``` - -### HelpDescription -Функция, возвращающая `std::string`, содержащую помощь для пользователя. -```cpp -std::string HelpDescription(); -``` -Пример вывода возвращаемого значения: - -```text -My Parser -Some Description about program - -OPTIONS: --i, --input=: File path for input file [repeated, min args = 1] - --number=: Some Number --s, --flag1: Use some logic [default = true] --p, --flag2: Use some logic - --h, --help: Display this help and exit -``` - -### GetValue -Шаблонная функция, возвращающая значение типа `T` аргумента с длинным ключом -*long_name*, полученное на *index* позиции (с нуля, по умолчанию - `0`). В случае -вызова функции с типом, не принадлежащему к поддерживаемым, при не добавленном -значении *long_name* или индекса, большего, чем количество полученных значений, -выбрасывается исключение `std::out_of_range`. В случае вызова до применения функции -парсинга, выбрасывается исключение `std::runtime_error`. -```cpp -template -T GetValue(const char* long_name, size_t index = 0); -``` - -### AddArgument -Шаблонная функция, возвращающая ссылку на экземпляр класса -[ConcreteArgumentBuilder](ConcreteArgumentBuilder.md), который будет строить -аргумент с переданными параметрами. Принимает `char` значение короткого ключа, -*constant C-style string* значение длинного ключа и, опционально, *constant C-style -string* описание ключа (по умолчанию - пустая строка). -```cpp -template -ConcreteArgumentBuilder& AddArgument(char short_name, const char* long_name, const char* description = ""); -``` -Эта перегрузка не принимает никакого значения короткого ключа. -```cpp -template -ConcreteArgumentBuilder& AddArgument(const char* long_name, const char* description = ""); -``` - -### AddFlag, AddShortArgument, ... AddStringArgument, AddCompositeArgument -Функции-псевдонимы для соответственно `AddArgument`, `AddArgument`, ... -`AddArgument` и `AddArgument` - -### AddHelp -Функция, вызывающая соответственную перегрузку `AddArgument`, возвращающая -результат и запоминающая аргумент помощи. -```cpp -ConcreteArgumentBuilder& AddHelp(char short_name, const char* long_name, const char* description = ""); -``` -Эта перегрузка не принимает никакого значения короткого ключа. -```cpp -ConcreteArgumentBuilder& AddHelp(const char* long_name, const char* description); -``` - -### GetFlag, GetShortValue, ... GetStringValue, GetCompositeValue -Функции-псевдонимы для соответственно `GetValue`, `GetValue`, -`GetValue` и `GetValue` diff --git a/lib/argparser/docs/ConcreteArgumentBuilder.md b/lib/argparser/docs/ConcreteArgumentBuilder.md deleted file mode 100644 index 6197927..0000000 --- a/lib/argparser/docs/ConcreteArgumentBuilder.md +++ /dev/null @@ -1,193 +0,0 @@ -# Документация класса ConcreteArgumentBuilder - -Этот шаблонный класс реализует паттерн проектирования "Builder": ссылки на объекты этого -класса должна возвращать функция добавления аргумента из `ArgParser`, к нему должен -обращаться пользователь, добавляя информацию об аргументе. Реализует функции добавления -любой информации про аргумент и функцию построения. Наследует абстрактному классу -`ArgumentBuilder`. Параметр шаблона - имя типа `T`. Находится в пространстве имён -`ArgumentParser`. - -## Объявление и определение - -Объявлен в [ConcreteArgumentBuilder.hpp](../ConcreteArgumentBuilder.hpp).
-Определен там же. - -## Зависимости - -Зависит от [ConcreteArgument.hpp](../ConcreteArgument.hpp) и -[ArgumentBuilder.hpp](../ArgumentBuilder.hpp). - -## Связанные документы - -* Документация класса [ConcreteArgumentBuilder](ConcreteArgumentBuilder.md) - - информация о задании параметров аргументов. - -## Публичные поля - -Класс не имеет публичных полей. - -## Публичные методы - -### ConcreteArgumentBuilder - -Принимает короткий ключ в виде `char`, длинный ключ в виде *constant C-style string*, -описание аргумента в виде *constant C-style string*. Не предназначен для прямого вызова -пользователем, поскольку имеет смысл только во внутренней логике класса `ArgParser`. -```cpp -ConcreteArgumentBuilder(char short_name, const char* long_name, const char* description); -``` -Конструктор без параметров и конструктор копирования, а также оператор присваивания с -копированием удалены. -```cpp -ConcreteArgumentBuilder() = delete; -ConcreteArgumentBuilder(const ConcreteArgumentBuilder& other) = delete; -ConcreteArgumentBuilder& operator=(const ConcreteArgumentBuilder& other) = delete; -``` - -### MultiValue - -Метод, отвечающий за придание аргументу свойства принятия множества значений. Принимает -минимальное обязательно число значений (по умолчанию ноль). Возвращает ссылку на этот -аргумент. -```cpp -ConcreteArgumentBuilder& MultiValue(size_t min = 0); -``` - -### Positional - -Метод, отвечающий за придание аргументу свойства позиционности - считывания значения -аргумента без ключа. Возвращает ссылку на этот аргумент. -```cpp -ConcreteArgumentBuilder& Positional(); -``` - -### StoreValue - -Метод, отвечающий за придание аргументу свойства хранения значения во внешней -переменной. Принимает ссылку на переменную, где должно храниться значение. -Возвращает ссылку на этот аргумент. -```cpp -ConcreteArgumentBuilder& StoreValue(T& value); -``` - -### StoreValues - -Метод, отвечающий за придание аргументу свойства хранения значений во внешнем -`std::vector`. Принимает ссылку на `std::vector`, где должны храниться значения. -Возвращает ссылку на этот аргумент. -```cpp -ConcreteArgumentBuilder& StoreValues(std::vector& values); -``` - -### Default - -Метод, отвечающий за придание аргументу значения по умолчанию. Принимает значение по -умолчанию. Возвращает ссылку на этот аргумент. -```cpp -ConcreteArgumentBuilder& Default(T value); -``` - -### AddValidate - -Метод, отвечающий за определение функции валидации для аргумента. Принимает -`std::function` валидации, которая должна принимать единственный аргумент: ссылку на -`std::string`, и возвращать `bool`. Под валидацией подразумевается проверка на общую -корректность потенциального значения. Функция валидации по умолчанию всегда принимает -истинное значение. Возвращает ссылку на этот аргумент. -```cpp -ConcreteArgumentBuilder& AddValidate(const std::function& validate); -``` - -### AddIsGood - -Метод, отвечающий за определение функции валидации для аргумента. Принимает -`std::function` проверки, которая должна принимать единственный аргумент: ссылку на -`std::string`, и возвращать `bool`. Под проверкой подразумевается проверка на полную -корректность потенциального значения. Функция проверки по умолчанию всегда принимает -истинное значение. Возвращает ссылку на этот аргумент. -```cpp -ConcreteArgumentBuilder& AddIsGood(const std::function& is_good); -``` - -### build - -Метод, отвечающий за создание аргумента по переданным параметрам. Не принимает никаких -аргументов. Возвращает указатель на интерфейс аргумента. Если значения по умолчанию -нет, а также аргумент не является MultiValue, то считается, что он обязательный. Если -аргумент логического типа (`Flag`), то считается, что его значение по умолчанию - -`false`, если пользователь не указал иного. Не предназначен для прямого вызова -пользователем, поскольку имеет смысл только во внутренней логике класса`ArgParser`. -```cpp -Argument* build() override; -``` - -### GetInfo - -Метод, предоставляющий информацию об аргументе в виде структуры `ArgumentInformation`, -хранящая типонезависимую информацию об аргументе. Ничего не принимает. Возвращает -неизменяемую ссылку на объект `ArgumentInformation`. Не модифицирует объект. Не должен -вызываться без использования значения. -```cpp -[[nodiscard]] const ArgumentInformation& GetInfo() const override; -``` - -### GetDefaultValue() - -Метод, предоставляющий информацию о значении аргумента по умолчанию в виде строки. -Ничего не принимает. Возвращает `std::string` со строковым представлением значения -по умолчанию. Не модифицирует объект. Не должен вызываться без использования значения. -```cpp -[[nodiscard]] std::string GetDefaultValue() const override; -``` - -## Приложение 1. Поддерживаемые типы аргументов, логика их парсинга - -### Целочисленные типы -* `Short` - `int16_t`: 16-битное знаковое число. Получается из целочисленного - литерала, подходящего под ограничения 16-битного знакового числа и являющегося - _подходящим_ (таким, что функция проверки принимает истинное значение). -* `Int` - `int32_t`: 32-битное знаковое число. Получается из целочисленного - литерала, подходящего под ограничения 32-битного знакового числа и являющегося - _подходящим_. -* `LongLong` - `int64_t`: 64-битное знаковое число. Получается из целочисленного - литерала, подходящего под ограничения 64-битного знакового числа и являющегося - _подходящим_. -* `UnsignedShort` - `uint16_t`: 16-битное беззнаковое число. Получается из - целочисленного литерала, подходящего под ограничения 16-битного беззнакового числа и - являющегося _подходящим_. -* `UnsignedInt` - `uint32_t`: 32-битное беззнаковое число. Получается из - целочисленного литерала, подходящего под ограничения 32-битного беззнакового числа и - являющегося _подходящим_. -* `UnsignedLongLong` - `uint64_t`: 64-битное беззнаковое число. Получается из - целочисленного литерала, подходящего под ограничения 64-битного беззнакового числа и - являющегося _подходящим_. - -### Дробные типы -* `Float` - `float`: 32-битное число с плавающей точкой. Получается из - дробного литерала, подходящего под ограничения 32-битного числа с плавающей точкой и - являющегося _подходящим_. -* `Double` - `double`: 64-битное число с плавающей точкой. Получается из - дробного литерала, подходящего под ограничения 64-битного числа с плавающей точкой и - являющегося _подходящим_. -* `LongDouble` - `long double`: 80-битное число с плавающей точкой. Получается из - дробного литерала, подходящего под ограничения 80-битного числа с плавающей точкой и - являющегося _подходящим_. - -### Элементарные типы -* `Flag` - `bool`: логическая переменная. Значение по умолчанию всегда `false`, при - наличии среди аргументов командной строки флага считается `true`. Также возможно - явное указание значения по аналогии с прочими аргументами: *false* и *0* считываются - как `false`, *true* и *1* считываются как `true`. -* `Char` - `char`: символ. Получается из _подходящего_ символьного литерала - escape - sequence или одного символа, также возможно задание в виде `\xXX`, при этом `0xXX` - - код символа в шестнадцатеричной системе счисления, а также в виде `\XXX`, при этом - `0XXX` - код символа в восьмеричной системе счисления. - -### Строковые типы -* `String` - `std::string`: строка. Получается из строкового литерала без пробелов, - являющегося _подходящим_. -* `CompositeString` - `CompositeString`: удовлетворяющая требованию строка, - возможно, содержащая пробелы. Получается из одного или нескольких идущих подряд - (разделённых пробелами) строковых литералов, прошедших _валидацию_ и обладающих - следующим свойством: вся строка является _подходящей_, но если убрать из нее любое - ненулевое количество литералов, то она перестанет быть таковой. diff --git a/lib/argparser/docs/README.md b/lib/argparser/docs/README.md deleted file mode 100644 index 91b3b9b..0000000 --- a/lib/argparser/docs/README.md +++ /dev/null @@ -1,15 +0,0 @@ -# Документация проекта - -Данный документ - сборник документации по проекту ArgParser. Здесь будут -все ссылки на документацию. - -## Документация разработки - -* [Проблема](dev/problem.md) -* [Требования](dev/requirements.md) -* [Архитектура](dev/architecture.md) - -## Итоговая документация - -* [Парсер](ArgParser.md) -* [Настройка параметров аргумента](ConcreteArgumentBuilder.md) diff --git a/lib/argparser/docs/dev/architecture.md b/lib/argparser/docs/dev/architecture.md deleted file mode 100644 index c7e0f69..0000000 --- a/lib/argparser/docs/dev/architecture.md +++ /dev/null @@ -1,185 +0,0 @@ -# Архитектура продукта - -В этом документе описывается архитектура продукта - парсера аргументов командной -строки, разработанная на основании [требований](requirements.md). - -## Системная архитектура - -* Продукт не имеет системной архитектуры, поскольку его предполагается использовать - в качестве подсистемы, встраиваемой в иные продукты. - -#### UML-диаграмма -```mermaid ---- -title: Diagram of the system of the project ---- -flowchart TB - nodeArgParser([ArgParser]) -``` - -## Архитектура подсистем - -* Исходя из вышеуказанного предполагаемого использования продукта, весь продукт - представляет собой одну подсистему - библиотеку argparer, которая должна обрабатывать - данные аргументы командной строки. - -### Архитектура подсистемы "ArgParser" - -#### UML-диаграмма -```mermaid ---- -title: Diagram of the module ArgParser ---- -%%{ - init: { - 'theme': 'base', - 'classDiagram': { 'curve': 'linear' }, - } -}%% -classDiagram - direction TB - note for ArgParser "Has pseudonym functions for AddArgument and GetValue for each argument type" - class ArgParser { - -const char[] name_; - -vector~ArgumentBuilder*~ argument_builders_; - -vector~Argument*~ arguments_; - -vector~string~ allowed_typenames_; - -vector~string~ allowed_typenames_for_help_; - -map~string, map~ string, size_t~~ arguments_by_type_; - -map~char, string~ short_to_long_names_; - -size_t help_index_; - +Parse(vector~string~ args, ConditionalOutput error_output=()) bool - +Parse(int argc, char[][] argv, ConditionalOutput error_output=()) bool - +Help() bool - +HelpDescription() string - +AddHelp(char short_name, const char[] long_name, const char[] description="") ConcreteArgumentBuilder~bool~ & - +AddHelp(const char[] long_name, const char[] description="") ConcreteArgumentBuilder~bool~ & - +AddArgument~T~(char short_name, const char[] long_name, const char[] description="") ConcreteArgumentBuilder~T~ & - +AddArgument~T~(const char[] long_name, const char[] description="") ConcreteArgumentBuilder~T~ & - +GetValue~T~(const char[] long_name, size_t index=0) T - -Parse_(vector~string~ args, ConditionalOutput error_output) bool - -GetLongKeys(string current_argument) vector~string~ - -ParsePositionalArguments(vector~string~ argv, const vector~size_t~ & used_positions) void - -HandleErrors(ConditionalOutput error_output) bool - -RefreshArguments() void - -AddArgument_~T~(char short_name, const char[] long_name, const char[] description) ConcreteArgumentBuilder~T~ & - -GetValue_~T~(const char* long_name, size_t index) T - } - class Argument { - <> - +ValidateArgument(vector~string~ argv, size_t position)* vector~size_t~ - +CheckLimit()* bool - +GetValueStatus()* ArgumentParsingStatus - +GetType()* string - +GetInfo()* ArgumentInformation - +GetUsedValues()* size_t - +ClearStored()* void - #ObtainValue(vector~string~ argv, string& value_string, vector~size_t~ & used_values, size_t position)* size_t - } - class ArgumentBuilder { - <> - +GetInfo()* ArgumentInformation - +GetDefaultValue()* string - +build()* Argument* - } - class ConcreteArgument~T~ { - -ArgumentInformation info_ - -ArgumentParsingStatus value_status_ - -size_t value_counter_ - -T value_ - -T default_value_ - -T* stored_value_ - -vector~T~* stored_values_ - +GetValue(size_t index) T - +ValidateArgument(vector~string~ argv, size_t position) vector~size_t~ - +CheckLimit() bool - +GetValueStatus() ArgumentParsingStatus - +GetType() string - +GetInfo() ArgumentInformation - +GetUsedValues() size_t - +ClearStored() void - #ObtainValue(vector~string~ argv, string& value_string, vector~size_t~ & used_values, size_t position) size_t - } - class ConcreteArgumentBuilder~T~ { - -ArgumentInformation info_; - -T default_value_; - -T* stored_value_; - -vector~T~* stored_values_; - -bool was_created_temp_vector_; - +MultiValue(size_t min=0) ConcreteArgumentBuilder & - +Positional() ConcreteArgumentBuilder& - +StoreValue(T& value) ConcreteArgumentBuilder& - +StoreValues(vector~T~ & values) ConcreteArgumentBuilder& - +Default(T value) ConcreteArgumentBuilder& - +AddValidate(function~bool(string&)~ validate) ConcreteArgumentBuilder& - +AddIsGood(function~bool(string&)~ is_good) ConcreteArgumentBuilder& - +GetInfo() ArgumentInformation - +GetDefaultValue() string - +build() Argument*` - } - class ArgumentInformation { - +char short_key = kBadChar - +const char[] long_key = "" - +const char[] description = "" - +string type - +size_t minimum_values = 0 - +bool is_multi_value = false - +bool is_positional = false - +bool has_store_values = false - +bool has_store_value = false - +bool has_default = false - +function~bool(string&)~ validate = &AlwaysTrue - ++function~bool(string&)~ is_good = &AlwaysTrue - } - class ArgumentParsingStatus { - <> - NoArgument - InvalidArgument - InsufficientArguments - Success - } - - ArgParser *-- Argument - ArgParser *-- ArgumentBuilder - ArgParser <.. ConcreteArgument - ArgParser <.. ConcreteArgumentBuilder - Argument <|.. ConcreteArgument - ArgumentBuilder <.. Argument - ArgumentBuilder <|.. ConcreteArgumentBuilder - ConcreteArgument *-- ArgumentInformation - ConcreteArgument *-- ArgumentParsingStatus - ConcreteArgumentBuilder <.. ConcreteArgument - ConcreteArgumentBuilder *-- ArgumentInformation -``` - -Эта подсистема представляет собой набор классов и связей между ними, которые выполняют -непосредственно парсинг аргументов командной строки, передаваемых в подсистему. Все -классы находятся в пространстве имён ArgumentParser. - -#### Класс ArgParser - -Этот класс является основным классом модуля, именно с ним обычно взаимодействует -пользователь. Он должен предоставлять следующие возможности: добавление обрабатываемого -аргумента (любого из указанных) с указанным ключом, парсинг набора аргументов командной -строки, а также функция добавления аргумента. Кроме того, должен иметь функцию -составления справки и обрабатывать ошибки в синтаксисе аргументов командной строки, -и, в некоторых случаях, выводить их. - -#### Класс ArgumentBuilder - -Этот класс реализует паттерн проектирования "Builder": ссылки на объекты наследников -этого класса должна возвращать функция добавления аргумента из ArgParser, к нему -должен обращаться пользователь, добавляя информацию об аргументе. Должен -реализовывать функции добавления любой информации про аргумент, представленные в -[тестах](../../../../tests/argparser_unit_tests.cpp) и функцию построения. Ему должен -наследовать шаблонизированный класс конкретного Builder, который будет реализовывать -вышеуказанный функционал для каждого из типов аргумента. - -#### Класс Argument - -Этот класс является родительским классом для всех классов аргументов. Должен иметь -функции возврата статуса парсинга и возврата информации об аргументе, а также функцию -получения значения аргумента из аргументов командной строки. Необходимая информация, -не изменяемая в процессе парсинга, должна храниться в виде экземпляра структуры. -На данный момент планируется аргументы всех базовых значащих типов (кроме 8-битных -чисел), StringArgument и ComplexArgument (строка с валидацией и чтением пробелов). diff --git a/lib/argparser/docs/dev/problem.md b/lib/argparser/docs/dev/problem.md deleted file mode 100644 index 7a4bee5..0000000 --- a/lib/argparser/docs/dev/problem.md +++ /dev/null @@ -1,5 +0,0 @@ -# Проблема - -Необходимо разработать библиотеку для парсинга аргументов командной строке на языке -C++, стандарт C++20. Библиотека должна быть POSIX-совместимой и проходить все -[тесты](../../../../tests/argparser_unit_tests.cpp) из указанного файла. diff --git a/lib/argparser/docs/dev/requirements.md b/lib/argparser/docs/dev/requirements.md deleted file mode 100644 index 4866b46..0000000 --- a/lib/argparser/docs/dev/requirements.md +++ /dev/null @@ -1,65 +0,0 @@ -# Требования к продукту - -В этом документе описаны требования к продукту - парсеру аргументов командной строки. - -## Функциональные требования - -Поскольку необходимо разработать библиотеку, подразумевающую дальнейшее использование -в качестве компонента других программ, требования не подразумевают прямо некий формат -UI, а описывают взаимодействие программистов, использующих библиотеку с ней. - -### Требования к формату входных данных - -* Входные данные должны представлять собой строки, несущие всю необходимую информацию - об аргументах, которые надо распарсить, а также непосредственно строку вызова - программы. -* Входные данные могут быть представлены в разных форматах: как вектор строк, так и динамический - массив C-style строк. -* Формат входных данных должен соответствовать [тестам](../../../../tests/argparser_unit_tests.cpp) - из соответствующего файла. То есть, должны быть реализованы все функции из тестов - со всеми возможными комбинациями аргументов функций из представленных. - -### Требования к формату выходных данных - -* Выходные данные - исключительно возвращаемые значения функций библиотеки. -* Формат выходных данных должен соответствовать [тестам](../../../../tests/argparser_unit_tests.cpp) - из соответствующего файла. То есть, должны быть реализованы все функции из тестов - с необходимыми типами возвращаемых значений. - -### Требования к функциональности продукта - -* Итоговый продукт должен проходить все [тесты](../../../../tests/argparser_unit_tests.cpp) - - главный приоритет. Первые 15 - строго обязательно. -* Кроме того, должна корректно работать программа, описанная в - [main.cpp](../../../../bin/main.cpp). -* Продукт должен настолько, насколько это возможно, соответствовать стандарту POSIX. -* К предоставленным тестам должны быть добавлены дополнительные, проверяющие - соответствие стандарту POSIX. -* Полученные значения аргументов должен валидироваться (на корректность). -* Должна быть реализована поддержка "сложного аргумента" - например, имени файла - с пробелами (последнее опционально). - -## Прочие требования - -### Требования к быстродействию - -* Требования к быстродействию отсутствуют исходя из специфики проблемы. Парсер - аргументов командной строки - модуль, который запускается всего один раз за всё - время работы программы, и всегда получает небольшое количество данных. Значит, - его быстродействие слабо влияет на быстродействие системы. - -### Требования к безопасности - -* Требования безопасности ограничены валидацией значений аргументов на корректность, - поскольку выявление угроз безопасности не относится к зоне ответственности парсера - аргументов командной строки. - -### Требования к масштабируемости - -* Масштабируемость не требуется исходя из специфики парсера аргументов командной - строки. - -### Требования к возможности доработки - -* Продукт должен обладать гибкой архитектурой с возможностью доработки и внесения - нового функционала.