{"id":13629482,"url":"https://github.com/SzymonHalucha/Minerals.AutoCommands","last_synced_at":"2025-04-17T09:34:05.230Z","repository":{"id":229017684,"uuid":"772388357","full_name":"SzymonHalucha/Minerals.AutoCommands","owner":"SzymonHalucha","description":"Package that uses incremental generators to provide useful attributes for creating CLI tools for dotnet platform","archived":false,"fork":false,"pushed_at":"2024-04-13T20:58:00.000Z","size":51,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-04-14T11:00:13.765Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SzymonHalucha.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2024-03-15T05:02:43.000Z","updated_at":"2024-04-15T15:58:32.458Z","dependencies_parsed_at":"2024-04-08T08:26:09.129Z","dependency_job_id":"2d6c6004-1413-4a0c-a244-9ca16572fbab","html_url":"https://github.com/SzymonHalucha/Minerals.AutoCommands","commit_stats":null,"previous_names":["szymonhalucha/minerals.autocommands"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SzymonHalucha%2FMinerals.AutoCommands","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SzymonHalucha%2FMinerals.AutoCommands/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SzymonHalucha%2FMinerals.AutoCommands/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SzymonHalucha%2FMinerals.AutoCommands/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SzymonHalucha","download_url":"https://codeload.github.com/SzymonHalucha/Minerals.AutoCommands/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223751146,"owners_count":17196579,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T22:01:11.750Z","updated_at":"2024-11-08T20:31:00.307Z","avatar_url":"https://github.com/SzymonHalucha.png","language":"C#","funding_links":[],"categories":["Contributors Welcome for those"],"sub_categories":["1. [ThisAssembly](https://ignatandrei.github.io/RSCG_Examples/v2/docs/ThisAssembly) , in the [EnhancementProject](https://ignatandrei.github.io/RSCG_Examples/v2/docs/rscg-examples#enhancementproject) category"],"readme":"# Minerals.AutoCommands\n\n![GitHub License](https://img.shields.io/github/license/SzymonHalucha/Minerals.AutoCommands?style=for-the-badge)\n![NuGet Version](https://img.shields.io/nuget/v/Minerals.AutoCommands?style=for-the-badge)\n![NuGet Downloads](https://img.shields.io/nuget/dt/Minerals.AutoCommands?style=for-the-badge)\n\n[Package on nuget.org](https://www.nuget.org/packages/Minerals.AutoCommands)\n\nThis NuGet package simplifies development of console tools in C# by automating command parsing. It eliminates need to manually write code to handle arguments, commands and commands helps, allowing you to focus on the logic of the tool.\n\n## Features\n\n- Automatic recognition of arguments, commands and help commands\n- Validation of arguments and display of error messages\n- Easy definition of shortcuts and aliases\n- Ability to define sub commands and arguments\n- Automatic generation of usage description for each command\n- Standardized output messages\n- Compatibility with ```netstandard2.0``` and C# 7.3+\n\n## Installation\n\nAdd the Minerals.AutoCommands nuget package to your C# project using the following methods:\n\n### 1. Project file definition\n\n```xml\n\u003cPackageReference Include=\"Minerals.AutoCommands\" Version=\"0.2.1\" /\u003e\n```\n\n### 2. dotnet command\n\n```bat\ndotnet add package Minerals.AutoCommands\n```\n\n## Usage\n\nTo define a new command, you must create a class that inherits from the ```CommandStatement``` base class provided by the package. This class must implement several core methods and properties to enable the parsing of commands and the execution of their logic.\n\n```csharp\nnamespace Examples\n{\n    // The command class must inherit from the CommandStatement base class.\n    public class TestCommand1 : Minerals.AutoCommands.CommandStatement\n    {\n        // The array must be initialized!\n        // Array of names for this command.\n        // Default value: null\n        public override string[] Aliases { get; } = [\"test1\"];\n\n        // The property must be initialized!\n        // Short description of the command.\n        // Default value: null\n        public override string Description { get; } = \"Lorem ipsum dolor sit amet 1.\";\n\n        // The array must be initialized!\n        // Array of command types that can be used as arguments for this command.\n        // Default value: null\n        public override Type[] PossibleArguments { get; } = [typeof(TestCommand2)];\n\n        public override bool Execute(Dictionary\u003cobject, object\u003e data = null)\n        {\n            // Example code...\n            if (success)\n            {\n                Writer.WriteLineInfo(\"Command executed successfully!\");\n\n                // THE DEVELOPER MUST MANUALLY TRIGGER THE EXECUTION OF THE NEXT COMMAND!\n                Next?.Execute(new() { { \"ExampleKey\", \"ExampleValue\" } });\n                return true;\n            }\n            else\n            {\n                Writer.WriteLineWarning(\"Command not executed!\");\n                return false;\n            }\n        }\n    }\n}\n```\n\n### Command requiring an argument\n\n```csharp\nnamespace Examples\n{\n    public class TestCommand1 : Minerals.AutoCommands.CommandStatement\n    {\n        // ...\n\n        // Requires from the user to provide an argument.\n        // Default value: false\n        public override bool ValueRequired { get; } = true;\n\n        // Regular expression can be used to specify which values are allowed.\n        // Default value: \".\" (Anything allowed)\n        public override Regex PossibleValues { get; } = new Regex(\"[a-zA-Z]\");\n\n        // ...\n    }\n}\n```\n\n### Optional command class values\n\nThe ```CommandStatement``` base class provides a set of optional values that can be used to customize functionality of the command. These properties allows you to define additional information about the command, such as its group, usage and required arguments.\n\n```csharp\nnamespace Examples\n{\n    public class TestCommand1 : Minerals.AutoCommands.CommandStatement\n    {\n        // ...\n\n        // An array of argument types required by this command.\n        // Default value: Array.Empty\u003cType\u003e()\n        public override Type[] ArgumentsRequired { get; } = [typeof(TestCommand2)];\n\n        // The name of the group to which the command belongs.\n        // Default value: \"Options\"\n        public override string Group { get; } = \"Test Commands\";\n\n        // The usage of the command, which is a description of how to invoke it correctly.\n        // If the value is empty, CommandWriter will automatically generate the usage.\n        // Default value: string.Empty\n        public override string Usage { get; } = \"[Command] [Options]\";\n\n        // ...\n    }\n}\n```\n\n### Obtaining values during command execution\n\nThe ``CommandStatement`` base class provides a set of values that can be used during command execution. They allow access to information about the context of the command execution, the values of the user-provided arguments and other data important for the logic of the command execution.\n\n```csharp\n// Stores the value of the argument provided by the user, if the command requires an argument.\npublic string? Value { get; protected set; }\n\n// Stores the previously executed command, if any.\npublic ICommandStatement? Previous { get; protected set; }\n\n// Stores the next command to be executed, if any. To execute it, you need to manually call its Execute() method.\npublic ICommandStatement? Next { get; protected set; }\n\n// Provides access to the CommandWriter object, which is used to display command output messages.\n// Use it instead of Console.WriteLine() to maintain a consistent and readable format for messages.\nprotected ICommandWriter Writer { get; set; }\n\n// Returns a collection of all commands executed before the current command.\npublic virtual IEnumerable\u003cICommandStatement\u003e AncestorCommands();\n\n// Returns a collection of all commands to be executed after the current command.\npublic virtual IEnumerable\u003cICommandStatement\u003e DescendantCommands();\n```\n\n### Running a command pipeline\n\nTo run the command pipeline created with this package, you need to perform the following steps:\n\n```csharp\nnamespace Examples\n{\n    public static class Program\n    {\n        public static void Main(string[] args)\n        {\n            // Creates a command pipeline.\n            // Arguments: title, version of the tool, main tool command (ToolCommandName in csproj file).\n            var pipeline = new CommandPipeline(\"Test Command Line\", \"1.2.3\", \"cmd\");\n\n            // REQUIRED instruction to parse the commands written by the developer.\n            pipeline.UseCommandParser\u003cCommandParser\u003e();\n\n            // What commands can be executed directly after the main tool command (ToolCommandName in csproj file).\n            pipeline.UsePossibleArguments(typeof(TestCommand1), typeof(TestCommand2), typeof(TestCommand3));\n\n            // Creates a doubly linked list (Previous, Next) of commands and returns the first command in the pipeline.\n            var command = pipeline.Evaluate(args);\n\n            // Starts execution of the first command.\n            command?.Execute();\n        }\n    }\n}\n```\n\n### CommandWriter\n\nA class provided by the package which is used to display command output messages. It enables a consistent and readable message format, and makes debugging and testing of your application easier. Instead of using ```Console.WriteLine()`` to display command output messages, use the methods available in the```CommandWriter``` class.\n\n```csharp\nWriter.WriteLineDebug(\"Example\");\n// or\nWriter.WriteLineInfo(\"Example\");\n// or\nWriter.WriteLineWarning(\"Example\");\n// or\nWriter.WriteLineError(\"Example\");\n\n// Instead of\n\nConsole.WriteLine(\"Example\");\n// or\nConsole.Error.WriteLine(\"Example\");\n```\n\n### Exceptions\n\nThis package has custom exceptions, by default the package automatically handles these exceptions, displaying the appropriate error messages. You can customize the default exceptions handlers or implement your own exception handling using the ```UseExceptionHandler()``` method on the ```CommandPipeline``` object. List of custom exceptions of the package:\n\n- CommandArgumentNotFoundException\n- CommandArgumentNotSupportedException\n- CommandArgumentRequiredException\n- CommandNotFoundException\n- CommandNotSupported\n- CommandValueNotFoundException\n- CommandValueNotSupportedException\n- CommandValueRequiredException\n\n### Customizing the CommandPipeline\n\nThis package provides a set of methods to customize the functions of the command pipeline depending on your needs.\n\n```csharp\n// Enables you to connect custom exception handling mechanisms.\npublic ICommandPipeline UseExceptionHandler\u003cT\u003e(Action\u003cT\u003e handler) where T : Exception, new();\n\n// REQUIRED instruction to parse the commands written by the developer, which defines how commands and their arguments are parsed.\n// Default value: null\npublic ICommandPipeline UseCommandParser\u003cT\u003e() where T : ICommandParser, new();\n// or\npublic ICommandPipeline UseCommandParser(ICommandParser parser);\n\n// Allows you to attach a custom CommandWriter object which defines how command output messages are displayed.\n// Default value: new CommandWriter();\npublic ICommandPipeline UseCommandWriter\u003cT\u003e(int textIndentation = 2) where T : ICommandWriter, new();\n// or\npublic ICommandPipeline UseCommandWriter(ICommandWriter writer);\n\n// Allows you to set custom aliases for help commands.\n// Default value: [\"--help\", \"-h\"]\npublic ICommandPipeline UseCommandHelpAliases(string[] aliases);\n\n// Allows you to set how the strings of command line are compared.\n// Default value: StringComparison.Ordinal\npublic ICommandPipeline UseStringComparison(StringComparison comparison);\n\n// Allows you to define a list of command types that can be executed directly after the main tool command (ToolCommandName in the csproj file).\n// Default value: null\npublic ICommandPipeline UsePossibleArguments(params Type[] possibleArguments);\n```\n\n## Versioning\n\nWe use [SemVer](http://semver.org/) for versioning. For the versions available, see the [branches on this repository](https://github.com/SzymonHalucha/Minerals.AutoCommands/branches).\n\n## Authors\n\n- **Szymon Hałucha** - Maintainer\n\nSee also the list of [contributors](https://github.com/SzymonHalucha/Minerals.AutoCommands/contributors) who participated in this project.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSzymonHalucha%2FMinerals.AutoCommands","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FSzymonHalucha%2FMinerals.AutoCommands","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSzymonHalucha%2FMinerals.AutoCommands/lists"}