Merge pull request #208 from commandlineparser/readme-updates

ericnewton76 · web-flow · commit 74afbfa5af62 · 2018-01-07T22:51:04.000-05:00
Update README.md
diff --git a/README.md b/README.md
@@ -4,143 +4,118 @@
 [![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<T>`) or scalar types, including enum and `Nullable<T>`.
-  - 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>(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<T>`) or scalar types, including enum and `Nullable<T>`.
+- 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>(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<string> 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 = {
   [<Option('r', "read", Required = true, HelpText = "Input files.")>] files : seq<string>;
   [<Option(HelpText = "Prints all messages to standard output.")>] verbose : bool;
   [<Option(DefaultValue = "русский", HelpText = "Content language.")>] language : string;
   [<Value(0, MetaName="offset", HelpText = "File offset.")>] offset : int64 option;
 }
-```
-Consume them:
-```fsharp
+
 let main argv =
   let result = CommandLine.Parser.Default.ParseArguments<options>(argv)
   match result with
   | :? Parsed<options> as parsed -> run parsed.Value
   | :? NotParsed<options> as notParsed -> fail notParsed.Errors
 ```
-**VB.NET:**
+
+VB.Net:
+
 ```VB.NET
 Class Options
 	<CommandLine.Option('r', "read", Required := true,
 	HelpText:="Input files to be processed.")>
 	Public Property InputFiles As IEnumerable(Of String)
 
-    ' Omitting long name, default --verbose
-    <CommandLine.Option(
+	' Omitting long name, defaults to name of property, ie "--verbose"
+	<CommandLine.Option(
 	HelpText:="Prints all messages to standard output.")>
 	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<AddOptions, CommitOptions, CloneOptions>(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
+<CommandLine.Verb("add", HelpText:="Add file contents to the index.")>
+Public Class AddOptions
+	'Normal options here
+End Class
+<CommandLine.Verb("commit", HelpText:="Record changes to the repository.")>
+Public Class AddOptions
+	'Normal options here
+End Class
+<CommandLine.Verb("clone", HelpText:="Clone a repository into a new directory.")>
+Public Class AddOptions
+	'Normal options here
+End Class
+
+Public Shared Sub Main()
+	'TODO
+End Sub
+```
+
+F# Example:
+
 ```fsharp
 open CommandLine
 
@@ -208,54 +206,45 @@ let main args =
   let result = Parser.Default.ParseArguments<AddOptions, CommitOptions, CloneOptions> args
   match result with
   | :? CommandLine.Parsed<obj> 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<obj> -> 1
 ```
-**VB.NET:**
-```VB.NET
-<CommandLine.Verb("add", HelpText:="Add file contents to the index.")>
-Public Class AddOptions
-	'Normal options here
-End Class
-<CommandLine.Verb("commit", HelpText:="Record changes to the repository.")>
-Public Class AddOptions
-	'Normal options here
-End Class
-<CommandLine.Verb("clone", HelpText:="Clone a repository into a new directory.")>
-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:
 ---
 [![Jet Brains ReSharper](/art/resharper-logo.png)](http://www.jetbrains.com/resharper/)
 
 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)
