diff --git a/README.md b/README.md index 588b851d..f5dabb88 100644 --- a/README.md +++ b/README.md @@ -4,118 +4,93 @@ [![Nuget](https://img.shields.io/nuget/vpre/commandlineparser.svg)](http://nuget.org/packages/commandlineparser) [![Join the gitter chat!](https://badges.gitter.im/gsscoder/commandline.svg)](https://gitter.im/gsscoder/commandline?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) -Command Line Parser Library for CLR and NetStandard -=== +# Command Line Parser Library for CLR and NetStandard -**Note:** the API surface has changed since 1.9.x and earlier. If you are looking for documentation on 1.9.x, please see [this branch](https://github.com/gsscoder/commandline/tree/stable-1.9.71.2) +**Note:** the API surface has changed since v1.9.x and earlier. If you are looking for documentation on v1.9.x, please see [stable-1.9.71.2](https://github.com/gsscoder/commandline/tree/stable-1.9.71.2) The Command Line Parser Library offers CLR applications a clean and concise API for manipulating command line arguments and related tasks, such as defining switches, options and verb commands. It allows you to display a help screen with a high degree of customization and a simple way to report syntax errors to the end user. ``` C:\Project> Nuget Install CommandLineParser +``` or +``` C:\Project> paket install CommandLineParser ``` -Everything that is boring and repetitive about parsing command line arguments is delegated to the library, letting developers concentrate on core logic. It's written in **C#** and doesn't depend on other packages. - __This library provides _hassle free_ command line parsing with a constantly updated API since 2005.__ Compatibility: ---- - .NET Framework 4.0+ - Mono 2.1+ Profile - .Net Core -Current Release: ---- - - For documentation please read appropriate [wiki section](https://github.com/gsscoder/commandline/wiki/Latest-Version). - - From version **2.0.x-pre+** parsing kernel was rewritten and public API simplified. +# At a glance: -At glance: ---- - - One line parsing using default singleton: `CommandLine.Parser.Default.ParseArguments(...)`. - - Automatic or one line help screen generator: `HelpText.AutoBuild(...)`. - - Supports `--help`, `--version`, `version` and `help [verb]` by default. - - Map to sequences (`IEnumerable`) or scalar types, including enum and `Nullable`. - - You can also map to every type with a constructor that accepts a string (like `System.Uri`). - - __Plug-In friendly__ architecture as explained [here](https://github.com/gsscoder/commandline/wiki/Plug-in-Friendly-Architecture). - - Define [verb commands](https://github.com/gsscoder/commandline/wiki/Latest-Version#verbs) as `git commit -a`. - - Unparsing support: `CommandLine.Parser.Default.FormatCommandLine(T options)`. - - F#-friendly with support for `option<'a>`, see [demo](https://github.com/gsscoder/commandline/blob/master/demo/fsharp-demo.fsx). - - Most of features applies with a [CoC](http://en.wikipedia.org/wiki/Convention_over_configuration) philosophy. - - C# demo: source [here](https://github.com/gsscoder/commandline/tree/master/demo/ReadText.Demo). - -Integrate directly into your project ---- -It is possible to integrate the CommandLineParser library directly into your project in two ways: +- Doesn't depend on other packages (No dependencies beyond standard base libraries) +- One line parsing using default singleton: `CommandLine.Parser.Default.ParseArguments(...)`. +- Automatic or one line help screen generator: `HelpText.AutoBuild(...)`. +- Supports `--help`, `--version`, `version` and `help [verb]` by default. +- Map to sequences (`IEnumerable`) or scalar types, including enum and `Nullable`. +- You can also map to every type with a constructor that accepts a string (like `System.Uri`). +- __Plug-In friendly__ architecture as explained [here](https://github.com/gsscoder/commandline/wiki/Plug-in-Friendly-Architecture). +- Define [verb commands](https://github.com/gsscoder/commandline/wiki/Latest-Version#verbs) as `git commit -a`. +- Unparsing support: `CommandLine.Parser.Default.FormatCommandLine(T options)`. +- F#-friendly with support for `option<'a>`, see [demo](https://github.com/gsscoder/commandline/blob/master/demo/fsharp-demo.fsx). +- Most of features applies with a [CoC](http://en.wikipedia.org/wiki/Convention_over_configuration) philosophy. +- C# demo: source [here](https://github.com/gsscoder/commandline/tree/master/demo/ReadText.Demo). -First way is simply copy the .cs files into your project: -``` -C:\Projects\MyProject> cp -r ClonedRepo/src/CommandLine To/Your/Project/Dir -``` +Used by several open source projects and by various commercial products: See the [wiki for listing](https://github.com/gsscoder/commandline/Used_By) -You can also use ILMerge during your library build process: +# Getting Started with the Command Line Parser Library -``` -C:\Projects\MyProject> msbuild MyProject.sln /p:Configuration=Release -C:\Projects\MyProject> ilmerge bin\Release\MyProject.exe bin\Release\CommandLineParser.dll bin\Release\MyProject.merged.exe -``` +You can utilize the parser library in several ways: -To build: ---- -- [FAKE](http://fsharp.github.io/FAKE/) Script -- MS Visual Studio -- Xamarin Studio +- Install via Nuget/Paket +- Integrate directly into your project by copying the .cs files into your project. +- ILMerge during your build process. -Public API: ---- -Latest changes are recorded from Version 1.9.4.91, please refer to [this document](https://github.com/commandlineparser/commandline/blob/master/docs/PublicAPI.md). +See more details in the [wiki for direct integrations](https://github.com/gsscoder/commandline/wiki/Direct_Integrations) -Used by: ---- -- [FSharp.Formatting](https://github.com/tpetricek/FSharp.Formatting) by @tpetricek. -- [MiniDumper](https://github.com/goldshtn/minidumper) by @goldshtn. -- [Google APIs Client Library for .NET](https://github.com/google/google-api-dotnet-client) by Google. -- [FSpec](https://github.com/PeteProgrammer/fspec) by @PeteProgrammer. -- Various commercial products. +## Quick Start Examples -Notes: ---- -The project is well suited to be included in your application. If you don't merge it to your project tree, you must reference `CommandLine.dll` and import `CommandLine` and `CommandLine.Text` namespaces (or install via NuGet). The help text builder and support types are in the `CommandLine.Text` namespace that is loosely coupled with the parser. It is good to know that the `HelpText` class will avoid a lot of repetitive coding. +1. Create a class to define valid options, and to receive the parsed options. +2. Call ParseArguments with the args string array. -**C#:** +C# Examples: -Define a class to receive parsed values: ```csharp -class Options { - [Option('r', "read", Required = true, - HelpText = "Input files to be processed.")] +internal class Options { + [Option('r',"read", + Required = true, + HelpText = "Input files to be processed.")] public IEnumerable InputFiles { get; set; } - // Omitting long name, default --verbose + // Omitting long name, defaults to name of property, ie "--verbose" [Option( - HelpText = "Prints all messages to standard output.")] + DefaultValue = false, + HelpText = "Prints all messages to standard output.")] public bool Verbose { get; set; } - - [Option(DefaultValue = "中文", - HelpText = "Content language.")] - public string Language { get; set; } + + [Option("stdin", + DefaultValue = false + HelpText = "Read from stdin")] + public bool stdin { get; set; } [Value(0, MetaName = "offset", - HelpText = "File offset.")] + HelpText = "File offset.")] public long? Offset { get; set; } } -``` -Consume them: -```csharp + static int Main(string[] args) { var options = new Options(); var isValid = CommandLine.Parser.Default.ParseArgumentsStrict(args, options); ``` -**F#:** + +F# Examples: + ```fsharp type options = { [] files : seq; @@ -123,24 +98,24 @@ type options = { [] language : string; [] offset : int64 option; } -``` -Consume them: -```fsharp + let main argv = let result = CommandLine.Parser.Default.ParseArguments(argv) match result with | :? Parsed as parsed -> run parsed.Value | :? NotParsed as notParsed -> fail notParsed.Errors ``` -**VB.NET:** + +VB.Net: + ```VB.NET Class Options Public Property InputFiles As IEnumerable(Of String) - ' Omitting long name, default --verbose - Public Property Verbose As Boolean @@ -152,16 +127,17 @@ Class Options HelpText:="File offset.")> Public Property Offset As Long? End Class -``` -Consume them: -```VB.NET -TODO + +'TODO ``` +### For verbs: -For verbs: +1. Create separate option classes for each verb. An options base class is supported. +2. Use MapResult to direct program flow to the verb that was parsed. + +C# example: -**C#:** ```csharp [Verb("add", HelpText = "Add file contents to the index.")] class AddOptions { @@ -178,15 +154,37 @@ class CloneOptions { int Main(string[] args) { return CommandLine.Parser.Default.ParseArguments(args) - .MapResult( - (AddOptions opts) => RunAddAndReturnExitCode(opts), - (CommitOptions opts) => RunCommitAndReturnExitCode(opts), - (CloneOptions opts) => RunCloneAndReturnExitCode(opts), - errs => 1); + .MapResult( + (AddOptions opts) => RunAddAndReturnExitCode(opts), + (CommitOptions opts) => RunCommitAndReturnExitCode(opts), + (CloneOptions opts) => RunCloneAndReturnExitCode(opts), + errs => 1); } ``` -**F#:** +VB.Net example: + +```VB.NET + +Public Class AddOptions + 'Normal options here +End Class + +Public Class AddOptions + 'Normal options here +End Class + +Public Class AddOptions + 'Normal options here +End Class + +Public Shared Sub Main() + 'TODO +End Sub +``` + +F# Example: + ```fsharp open CommandLine @@ -208,31 +206,14 @@ let main args = let result = Parser.Default.ParseArguments args match result with | :? CommandLine.Parsed as command -> - match command.Value with - | :? AddOptions as opts -> RunAddAndReturnExitCode opts - | :? CommitOptions as opts -> RunCommitAndReturnExitCode opts - | :? CloneOptions as opts -> RunCloneAndReturnExitCode opts + match command.Value with + | :? AddOptions as opts -> RunAddAndReturnExitCode opts + | :? CommitOptions as opts -> RunCommitAndReturnExitCode opts + | :? CloneOptions as opts -> RunCloneAndReturnExitCode opts | :? CommandLine.NotParsed -> 1 ``` -**VB.NET:** -```VB.NET - -Public Class AddOptions - 'Normal options here -End Class - -Public Class AddOptions - 'Normal options here -End Class - -Public Class AddOptions - 'Normal options here -End Class -Public Shared Sub Main() - 'TODO -End Sub -``` +For additional examples, check the [wiki for additional examples](https://gsscoder/commandline/wiki/Examples) Acknowledgements: --- @@ -240,22 +221,30 @@ Acknowledgements: Thanks to JetBrains for providing an open source license for [ReSharper](http://www.jetbrains.com/resharper/). -Main Contributors (alphabetical order): +# Contibutors +First off, _Thank you!_ All contributions are welcome. + +Please consider sticking with the GNU getopt standard for command line parsing. + +Additionally, for easiest diff compares, please follow the project's tabs settings. Utilizing the EditorConfig extension for Visual Studio/your favorite IDE is recommended. + +For more info, see the [wiki for details about contributing](https://github.com/gsscoder/commandline/wiki/Building_the_library) and for building the project. + +## Main Contributors (alphabetical order): - Alexander Fast (@mizipzor) - Dan Nemec (@nemec) - Kevin Moore (@gimmemoore) - Steven Evans - Thomas Démoulins (@Thilas) -Resources for newcomers: ---- - - [CodePlex](http://commandline.codeplex.com) - - [Quickstart](https://github.com/gsscoder/commandline/wiki/Quickstart) - - [Wiki](https://github.com/gsscoder/commandline/wiki) - - [GNU getopt](http://www.gnu.org/software/libc/manual/html_node/Getopt.html) +## Resources for newcomers: + +- [Quickstart](https://github.com/gsscoder/commandline/wiki/Quickstart) +- [Wiki](https://github.com/gsscoder/commandline/wiki) +- [GNU getopt](http://www.gnu.org/software/libc/manual/html_node/Getopt.html) + +# Contacts: -Contact: ---- - Giacomo Stelluti Scala - gsscoder AT gmail DOT com (_use this for everything that is not available via GitHub features_) - GitHub: [gsscoder](https://github.com/gsscoder)