{"id":22693502,"url":"https://github.com/modernronin/fluentargumentparser","last_synced_at":"2025-04-13T00:15:40.853Z","repository":{"id":43012731,"uuid":"304681316","full_name":"ModernRonin/FluentArgumentParser","owner":"ModernRonin","description":"Parse command-line arguments directly into your POCOs with a simple, yet complete and elegant fluent API. Supports nested verbs, specifying arguments by index, long or short name and is quite configurable and extensible.","archived":false,"fork":false,"pushed_at":"2022-03-23T10:00:37.000Z","size":260,"stargazers_count":2,"open_issues_count":15,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-13T00:15:35.545Z","etag":null,"topics":["command-line","csharp","dotnet","fluent-api","parsing"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ModernRonin.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}},"created_at":"2020-10-16T16:27:11.000Z","updated_at":"2022-06-14T05:14:40.000Z","dependencies_parsed_at":"2022-09-18T01:11:37.939Z","dependency_job_id":null,"html_url":"https://github.com/ModernRonin/FluentArgumentParser","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ModernRonin%2FFluentArgumentParser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ModernRonin%2FFluentArgumentParser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ModernRonin%2FFluentArgumentParser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ModernRonin%2FFluentArgumentParser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ModernRonin","download_url":"https://codeload.github.com/ModernRonin/FluentArgumentParser/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248647274,"owners_count":21139086,"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":["command-line","csharp","dotnet","fluent-api","parsing"],"created_at":"2024-12-10T02:11:29.384Z","updated_at":"2025-04-13T00:15:40.833Z","avatar_url":"https://github.com/ModernRonin.png","language":"C#","readme":"# FluentArgumentParser\n\n[![CI Status](https://github.com/ModernRonin/FluentArgumentParser/actions/workflows/dotnet.yml/badge.svg)](https://github.com/ModernRonin/FluentArgumentParser/actions/workflows/dotnet.yml)\n[![NuGet](https://img.shields.io/nuget/v/ModernRonin.FluentArgumentParser.svg)](https://www.nuget.org/packages/ModernRonin.FluentArgumentParser/)\n[![NuGet](https://img.shields.io/nuget/dt/ModernRonin.FluentArgumentParser.svg)](https://www.nuget.org/packages/ModernRonin.FluentArgumentParser)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com) \n\n- [Summary](#summary)\n- [Quickstart](#quick-start---zero-configuration)\n- [More Info](#more-info)\n- [License](#license)\n- [Contributing](#contributing)\n- [Release History](docs/ReleaseHistory.md)\n\n## Summary\nThere are several packages out there for parsing of command-line arguments, but not one of them fulfills everything I think such a library should cover. \n\nWhat are these requirements?\n\n* populates POCOs\n* is not dependent on attributes (personally I find attributes, especially those with parameters, create a lot of noise when reading code)\n* deals with verbs, like git, and nested verbs, too\n* allows passing arguments by index, by long name and by short name\n* produces good-looking and useful help\n* possible to work with just the POCOs without any further configuration - for small in-house tools one often doesn't want to spend a lot of time with setting up these options\n* good defaults, but at the same time configurable and extensible\n\n## Quick Start - zero configuration\nLet's look at the simplest scenario. For more advanced examples, take a look [here](docs/Examples.md).\n\n\n\u003eYou want to model a single action and don't care too much about the names of the options or help-text, you just want to get over this argument parsing as quickly as possible.\n\n\n```csharp\n// this is the info you want to get from the commandline arguments - you just define it as a regular POCO\npublic class Rectangle\n{\n    public int X { get; set; }\n    public int Y { get; set; }\n    public int Width { get; set; }\n    public int Height { get; set; }\n    public Filling Filling { get; set; } = Filling.Solid;\n}\n\n// and in your Main you do:\nstatic int Main(string[] args)\n{\n    var parser = ParserFactory.Create(\"sometool\", \"somedescription\");\n    parser.DefaultVerb\u003cRectangle\u003e();\n    switch (parser.Parse(args))\n    {\n        case HelpResult help:\n            Console.WriteLine(help.Text);\n            return help.IsResultOfInvalidInput ? -1 : 0;\n        case Rectangle rectangle:\n            // do whatever you need to do\n    }\n}\n```\nNow what are valid inputs for this setup? Here are a few examples, together with how they will fill the properties of the `Rectangle` instance:\n| Argument string  | Rectangle properties |\n| --- | --- |\n| 10 11 12 13  | `X:10, Y:11, Width:12, Height:13, Filling:Filling.Solid `  |\n| 10 11 -h=13 -w=12 --filling=Hatched  | `X:10, Y:11, Width:12, Height:13, Filling:Filling.Hatched `  |\n| -x=10 -y=11 -h=13 -w=12 Hatched  | `X:10, Y:11, Width:12, Height:13, Filling:Filling.Hatched `  |\n\nAnd what would be the content of the `help.Text` property in the code-sample above?\n\n```plaintext\nsometool\nsomedescription\n\nUsage:\nsometool --x=\u003cvalue\u003e --y=\u003cvalue\u003e --width=\u003cvalue\u003e --height=\u003cvalue\u003e [--filling=\u003cvalue\u003e]\n\n\nRequired arguments:\n--x, -x       int\n--y, -y       int\n--width, -w   int\n--height, -h  int\n\nOptional arguments:\n--filling, -f  None, Hatched, Solid\n               default: Solid\n\nExamples:\nsometool 10 20 30 40\nsometool 10 20 30 40 Solid\nsometool --x=10 --y=20 --width=30 --height=40 --filling=Solid\nsometool -x=10 -y=20 -w=30 -h=40 -f=Solid\nsometool -h=40 -f=Solid -x=10 -y=20 -w=30\n\nlong parameter names are case-sensitive\nshort parameter names are not case-sensitive\ncommand names are not case-sensitive\n```\n\nThings to note:\n- if you are fine with the default naming, you can just pop in your configuration objects and be done with it.\n- if you set defaults for properties (different from the standard defaults), they are automatically assumed to be optional with the default value you set. In the example above `Rectangle.Filling` is such a case: it's automatically understood to be an optional parameter with the default value `Filling.Solid`.\n- the `Parse` method returns an object on which you can switch, using a language facility we've had now for a while. The types you need to handle are all your own POCOs that you have defined as verbs and the special type `HelpResult`\n- `HelpResult` is automatically returned when the arguments contain an explicit call for help, like `sometool help` or `sometool ?` or, if you have multiple verbs, `sometool help myverb`\n\n## More Info\n- [multiple verbs](docs/Examples.md#multiple-verbs-no-configuration)\n- [nested verbs](docs/Examples.md#multiple-and-nested-verbs-no-configuration)\n- [boolean properties](docs/Reference.md#parameters)\n- [verb specfic help](docs/Examples.md#help-startfeature)\n- overriding the automatically detected settings (like the name of a parameter)\nsee [More Examples](docs/Examples.md#multiple-and-nested-verbs-with-additional-configuration).\n- change [global configuration](docs/Configuration.md), for example the prefixes uses for parameter names\n- change how [names are generated](docs/Extensibility.md#name-generation) for verbs and parameters\n- change how [types are formatted](docs/Extensibility.md#help-generation) for the help texts\n- change how [example values](docs/Extensibility.md#help-generation) are generated for the help texts\n- [pre-process](docs/Reference.md#iargumentpreprocessor) arguments\n- if you want to interact with the low-level parser, without any reflection, check out [these tests](ModernRonin.FluentArgumentParser.Tests/Demo/LowLevelTests.cs)\n- last not least, you can always take a look at the [demo tests](ModernRonin.FluentArgumentParser.Tests/Demo)\n\n## Contributing\nIf you want to contribute, you are more than welcome. Fork the repository, make your desired changes, and create a pull request into the source repository default branch (you can read more about the fork and pull model [here](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/getting-started/about-collaborative-development-models))\n\n### .NET version\nThe solution requires .NET 6.x SDK installed on your machine.\n\n### Paket\nThis solution uses _[Paket](http://fsprojects.github.io/Paket/)_, a dependency manager for .NET projects. To get started with the solution, run:\n\n```\ndotnet tool restore\ndotnet paket restore\n```\n\nThis will restore all necessary packages in order to run the solution.\n\n### Labels\n\nCheck out the issues page. There are a few issues marked as `good-first-issue` and a few others as `help-wanted`. \n\nFurthermore, issues marked as `needs-design` would benefit from discussion about how they should ideally work, both for end-users and for library-users.\n\nLast not least, there are a few ideas marked as `do-people-need-this`- for these, it would be very interesting to get as many opinions as possible. \n\n## License\nThe [license](./LICENSE) is [Creative Commons BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/). In essence this means you are free to use and distribute and change this tool however you see fit, as long as you provide a link to the license\nand share any customizations/changes you might perform under the same license. \n\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmodernronin%2Ffluentargumentparser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmodernronin%2Ffluentargumentparser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmodernronin%2Ffluentargumentparser/lists"}