Merge branch 'feature/1.2-polish'

appveyor.yml

@@ -4,7 +4,7 @@ clone_depth: 50
 
 cache:
   - '%LOCALAPPDATA%\Microsoft\dotnet -> appveyor.yml'
-  - '%USERPROFILE%\.nuget\packages -> appveyor.yml, **\project.json, Nuget.Config'
+  - '%USERPROFILE%\.nuget\packages -> appveyor.yml, **\*.csproj, Nuget.Config'
 
 before_build:
   # Install dotnet cli

docs-generation/Website/article_arguments.cs

@@ -54,9 +54,17 @@ public SimpleCliArguments() : base("SimpleApp") { }
             [Operand(Position: 1)]
             public decimal FirstOperand { get; set; }
 
+            // When the user makes a mistake, a default handler takes over
+            // You can override this behaviour on this Virtual method
             public override void OnUserFacingException(UserFacingException e, string message) {
                 throw new NotImplementedException();
             }
+
+            // When the user invokes --help/-h a default handler will take over
+            // You can define your own behaviour by overriding this Virtual method
+            public override void OnHelpInvoked(string helpText) {
+                throw new NotImplementedException();
+            }
         }
 #endif
 
@@ -70,28 +78,36 @@ public override void OnUserFacingException(UserFacingException e, string message
         /// * **Detail:** Defines an On/Off option for use on the CLI
         /// * **Argument, LongName:** the case in-sensitive name to be used like `--name`
         /// * **Argument, ShortName:** the case sensitive character to be used like `-n`
-        /// * At least one name needs to be provided
+        /// * **Usable with:** `Required` and `Help` attributes
         /// 
         /// ##### `[OptionParameter(LongName = string, ShortName = char)]`
         /// * **Apply to:** Class Properties
-        /// * **Output Types:** Primitive Types, Enums
+        /// * **Output Types:** Primitive Types, Enums, Lists of Primitives or Enums
         /// * **Detail:** Defines a parameter which can be invoked to provide a value
         /// * **Argument, LongName:** the case in-sensitive name to be used like `--name`
         /// * **Argument, ShortName:** the case sensitive character to be used like `-n`
-        /// * At least one name needs to be provided
+        /// * **Usable with:** `Required` and `Help` attributes
         /// 
-        /// ##### `[Operand(position = int)]`
+        /// ##### `[Operand(Position = int)]`
         /// * **Apply to:** Class Properties
-        /// * **Output Types:** Primitive Types, Enums
+        /// * **Output Types:** Primitive Types, Enums, Lists of Primitives or Enums
         /// * **Detail:** Maps a positional operand from the end of a CLI command
         /// * **Argument, Position:** the 1 based position of the Operand
+        /// * **Usable with:** `Required` and `Help` attributes
+        /// 
+        /// ##### `[EnvironmentVariable(VariableName = string)]`
+        /// * **Apply to:** Class Properties
+        /// * **Output Types:** Primitive Types, Enums, Lists of Primitives or Enums
+        /// * **Detail:** Maps a variable from the environment
+        /// * **Argument, VariableName:** the case in-sensitive name of the environment variable
+        /// * **Usable with:** `Required` and `Help` attributes
         /// 
         /// ##### `[Required]`
-        /// * **Apply to:** Option, OptionParameter or Operand properties
+        /// * **Apply to:** Option, OptionParameter, Operand or EnvironmentVariable properties
         /// * **Detail:** Makes an Option or Operand mandatory for the user to provide
         /// 
-        /// ##### `[Help(detail = string)]`
-        /// * **Apply to:** Class Properties with any Option or Operand Attribute applied, or an CliArguments Class
+        /// ##### `[Help(Detail = string)]`
+        /// * **Apply to:** Class Properties with any Option, Operand or EnvironmentVariable Attribute applied, or an CliArguments Class
         /// * **Detail:** Provides custom documentation on an Option, Operand or CliArguments Class, which will be consumed by the help generator
         ///
 
@@ -140,14 +156,15 @@ public MessagingCliArguments() : base("Message Sender") { }
             [OptionParameter(LongName: "recipients")]
             public List<string> Recipients { get; set; }
 
+            // Variables can be mapped from the environment
+            [Required]
+            [EnvironmentVariable("MSGSDR_PASSWORD")]
+            public string Password { get; set; }
+
             // A message *must* be provided as the first operand
             [Required]
             [Operand(1)]
             public string Message { get; set; }
-
-            public override void OnUserFacingException(UserFacingException e, string message) {
-                throw new NotImplementedException();
-            }
         }
 
         enum MessageImportanceEnum {

docs-generation/Website/www/arguments.md

@@ -43,9 +43,17 @@ This has one Option `-s`, one OptionParameter `--name Bob` and a positional Oper
         [Operand(Position: 1)]
         public decimal FirstOperand { get; set; }
 
+        // When the user makes a mistake, a default handler takes over
+        // You can override this behaviour on this Virtual method
         public override void OnUserFacingException(UserFacingException e, string message) {
             throw new NotImplementedException();
         }
+
+        // When the user invokes --help/-h a default handler will take over
+        // You can define your own behaviour by overriding this Virtual method
+        public override void OnHelpInvoked(string helpText) {
+            throw new NotImplementedException();
+        }
     }
 
 #### Attributes
@@ -58,28 +66,36 @@ We use Attributes to define CLI functionality
 * **Detail:** Defines an On/Off option for use on the CLI
 * **Argument, LongName:** the case in-sensitive name to be used like `--name`
 * **Argument, ShortName:** the case sensitive character to be used like `-n`
-* At least one name needs to be provided
+* **Usable with:** `Required` and `Help` attributes
 
 ##### `[OptionParameter(LongName = string, ShortName = char)]`
 * **Apply to:** Class Properties
-* **Output Types:** Primitive Types, Enums
+* **Output Types:** Primitive Types, Enums, Lists of Primitives or Enums
 * **Detail:** Defines a parameter which can be invoked to provide a value
 * **Argument, LongName:** the case in-sensitive name to be used like `--name`
 * **Argument, ShortName:** the case sensitive character to be used like `-n`
-* At least one name needs to be provided
+* **Usable with:** `Required` and `Help` attributes
 
-##### `[Operand(position = int)]`
+##### `[Operand(Position = int)]`
 * **Apply to:** Class Properties
-* **Output Types:** Primitive Types, Enums
+* **Output Types:** Primitive Types, Enums, Lists of Primitives or Enums
 * **Detail:** Maps a positional operand from the end of a CLI command
 * **Argument, Position:** the 1 based position of the Operand
+* **Usable with:** `Required` and `Help` attributes
+
+##### `[EnvironmentVariable(VariableName = string)]`
+* **Apply to:** Class Properties
+* **Output Types:** Primitive Types, Enums, Lists of Primitives or Enums
+* **Detail:** Maps a variable from the environment
+* **Argument, VariableName:** the case in-sensitive name of the environment variable
+* **Usable with:** `Required` and `Help` attributes
 
 ##### `[Required]`
-* **Apply to:** Option, OptionParameter or Operand properties
+* **Apply to:** Option, OptionParameter, Operand or EnvironmentVariable properties
 * **Detail:** Makes an Option or Operand mandatory for the user to provide
 
-##### `[Help(detail = string)]`
-* **Apply to:** Class Properties with any Option or Operand Attribute applied, or an CliArguments Class
+##### `[Help(Detail = string)]`
+* **Apply to:** Class Properties with any Option, Operand or EnvironmentVariable Attribute applied, or an CliArguments Class
 * **Detail:** Provides custom documentation on an Option, Operand or CliArguments Class, which will be consumed by the help generator
 
 #### Use case
@@ -126,14 +142,15 @@ The following is used like:
         [OptionParameter(LongName: "recipients")]
         public List<string> Recipients { get; set; }
 
+        // Variables can be mapped from the environment
+        [Required]
+        [EnvironmentVariable("MSGSDR_PASSWORD")]
+        public string Password { get; set; }
+
         // A message *must* be provided as the first operand
         [Required]
         [Operand(1)]
         public string Message { get; set; }
-
-        public override void OnUserFacingException(UserFacingException e, string message) {
-            throw new NotImplementedException();
-        }
     }
 
     enum MessageImportanceEnum {

docs-generation/docfx/api/.manifest

@@ -1 +1 @@
-{"EntryPoint":"EntryPoint.yml","EntryPoint.BaseCliArguments":"EntryPoint.BaseCliArguments.yml","EntryPoint.BaseCliArguments.#ctor(System.String)":"EntryPoint.BaseCliArguments.yml","EntryPoint.BaseCliArguments.Operands":"EntryPoint.BaseCliArguments.yml","EntryPoint.BaseCliArguments.HelpInvoked":"EntryPoint.BaseCliArguments.yml","EntryPoint.BaseCliArguments.OnHelpInvoked(System.String)":"EntryPoint.BaseCliArguments.yml","EntryPoint.BaseCliArguments.UserFacingExceptionThrown":"EntryPoint.BaseCliArguments.yml","EntryPoint.BaseCliArguments.OnUserFacingException(EntryPoint.Exceptions.UserFacingException,System.String)":"EntryPoint.BaseCliArguments.yml","EntryPoint.BaseCliCommands":"EntryPoint.BaseCliCommands.yml","EntryPoint.BaseCliCommands.HelpInvoked":"EntryPoint.BaseCliCommands.yml","EntryPoint.BaseCliCommands.OnHelpInvoked(System.String)":"EntryPoint.BaseCliCommands.yml","EntryPoint.BaseCliCommands.UserFacingExceptionThrown":"EntryPoint.BaseCliCommands.yml","EntryPoint.BaseCliCommands.OnUserFacingException(EntryPoint.Exceptions.UserFacingException,System.String)":"EntryPoint.BaseCliCommands.yml","EntryPoint.Cli":"EntryPoint.Cli.yml","EntryPoint.Cli.Parse``1":"EntryPoint.Cli.yml","EntryPoint.Cli.Parse``1(System.String[])":"EntryPoint.Cli.yml","EntryPoint.Cli.Parse``1(``0,System.String[])":"EntryPoint.Cli.yml","EntryPoint.Cli.Execute``1":"EntryPoint.Cli.yml","EntryPoint.Cli.Execute``1(System.String[])":"EntryPoint.Cli.yml","EntryPoint.Cli.Execute``1(``0,System.String[])":"EntryPoint.Cli.yml","EntryPoint.Cli.GetHelp``1":"EntryPoint.Cli.yml","EntryPoint.Cli.GetHelp``1(``0)":"EntryPoint.Cli.yml","EntryPoint.CommandAttribute":"EntryPoint.CommandAttribute.yml","EntryPoint.CommandAttribute.#ctor(System.String)":"EntryPoint.CommandAttribute.yml","EntryPoint.DefaultCommandAttribute":"EntryPoint.DefaultCommandAttribute.yml","EntryPoint.DefaultCommandAttribute.#ctor":"EntryPoint.DefaultCommandAttribute.yml","EntryPoint.HelpAttribute":"EntryPoint.HelpAttribute.yml","EntryPoint.HelpAttribute.#ctor(System.String)":"EntryPoint.HelpAttribute.yml","EntryPoint.HelpAttribute.Detail":"EntryPoint.HelpAttribute.yml","EntryPoint.OperandAttribute":"EntryPoint.OperandAttribute.yml","EntryPoint.OperandAttribute.#ctor(System.Int32)":"EntryPoint.OperandAttribute.yml","EntryPoint.OperandAttribute.Position":"EntryPoint.OperandAttribute.yml","EntryPoint.OptionAttribute":"EntryPoint.OptionAttribute.yml","EntryPoint.OptionAttribute.#ctor(System.String,System.Char)":"EntryPoint.OptionAttribute.yml","EntryPoint.OptionAttribute.#ctor(System.String)":"EntryPoint.OptionAttribute.yml","EntryPoint.OptionAttribute.#ctor(System.Char)":"EntryPoint.OptionAttribute.yml","EntryPoint.OptionParameterAttribute":"EntryPoint.OptionParameterAttribute.yml","EntryPoint.OptionParameterAttribute.#ctor(System.String,System.Char)":"EntryPoint.OptionParameterAttribute.yml","EntryPoint.OptionParameterAttribute.#ctor(System.String)":"EntryPoint.OptionParameterAttribute.yml","EntryPoint.OptionParameterAttribute.#ctor(System.Char)":"EntryPoint.OptionParameterAttribute.yml","EntryPoint.RequiredAttribute":"EntryPoint.RequiredAttribute.yml","EntryPoint.Exceptions":"EntryPoint.Exceptions.yml","EntryPoint.Exceptions.DuplicateOptionException":"EntryPoint.Exceptions.DuplicateOptionException.yml","EntryPoint.Exceptions.InvalidModelException":"EntryPoint.Exceptions.InvalidModelException.yml","EntryPoint.Exceptions.IUserFacingExceptionHandler":"EntryPoint.Exceptions.IUserFacingExceptionHandler.yml","EntryPoint.Exceptions.IUserFacingExceptionHandler.UserFacingExceptionThrown":"EntryPoint.Exceptions.IUserFacingExceptionHandler.yml","EntryPoint.Exceptions.IUserFacingExceptionHandler.OnUserFacingException(EntryPoint.Exceptions.UserFacingException,System.String)":"EntryPoint.Exceptions.IUserFacingExceptionHandler.yml","EntryPoint.Exceptions.NoParameterException":"EntryPoint.Exceptions.NoParameterException.yml","EntryPoint.Exceptions.RequiredException":"EntryPoint.Exceptions.RequiredException.yml","EntryPoint.Exceptions.UnknownOptionException":"EntryPoint.Exceptions.UnknownOptionException.yml","EntryPoint.Exceptions.UserFacingException":"EntryPoint.Exceptions.UserFacingException.yml","EntryPoint.Help":"EntryPoint.Help.yml","EntryPoint.Help.IHelpable":"EntryPoint.Help.IHelpable.yml","EntryPoint.Help.IHelpable.HelpInvoked":"EntryPoint.Help.IHelpable.yml","EntryPoint.Help.IHelpable.OnHelpInvoked(System.String)":"EntryPoint.Help.IHelpable.yml"}
+{"EntryPoint":"EntryPoint.yml","EntryPoint.BaseCliArguments":"EntryPoint.BaseCliArguments.yml","EntryPoint.BaseCliArguments.#ctor(System.String)":"EntryPoint.BaseCliArguments.yml","EntryPoint.BaseCliArguments.Operands":"EntryPoint.BaseCliArguments.yml","EntryPoint.BaseCliArguments.HelpInvoked":"EntryPoint.BaseCliArguments.yml","EntryPoint.BaseCliArguments.OnHelpInvoked(System.String)":"EntryPoint.BaseCliArguments.yml","EntryPoint.BaseCliArguments.UserFacingExceptionThrown":"EntryPoint.BaseCliArguments.yml","EntryPoint.BaseCliArguments.OnUserFacingException(EntryPoint.Exceptions.UserFacingException,System.String)":"EntryPoint.BaseCliArguments.yml","EntryPoint.BaseCliCommands":"EntryPoint.BaseCliCommands.yml","EntryPoint.BaseCliCommands.HelpInvoked":"EntryPoint.BaseCliCommands.yml","EntryPoint.BaseCliCommands.OnHelpInvoked(System.String)":"EntryPoint.BaseCliCommands.yml","EntryPoint.BaseCliCommands.UserFacingExceptionThrown":"EntryPoint.BaseCliCommands.yml","EntryPoint.BaseCliCommands.OnUserFacingException(EntryPoint.Exceptions.UserFacingException,System.String)":"EntryPoint.BaseCliCommands.yml","EntryPoint.Cli":"EntryPoint.Cli.yml","EntryPoint.Cli.Parse``1":"EntryPoint.Cli.yml","EntryPoint.Cli.Parse``1(System.String[])":"EntryPoint.Cli.yml","EntryPoint.Cli.Parse``1(``0,System.String[])":"EntryPoint.Cli.yml","EntryPoint.Cli.Execute``1":"EntryPoint.Cli.yml","EntryPoint.Cli.Execute``1(System.String[])":"EntryPoint.Cli.yml","EntryPoint.Cli.Execute``1(``0,System.String[])":"EntryPoint.Cli.yml","EntryPoint.Cli.GetHelp``1":"EntryPoint.Cli.yml","EntryPoint.Cli.GetHelp``1(``0)":"EntryPoint.Cli.yml","EntryPoint.CommandAttribute":"EntryPoint.CommandAttribute.yml","EntryPoint.CommandAttribute.#ctor(System.String)":"EntryPoint.CommandAttribute.yml","EntryPoint.DefaultCommandAttribute":"EntryPoint.DefaultCommandAttribute.yml","EntryPoint.DefaultCommandAttribute.#ctor":"EntryPoint.DefaultCommandAttribute.yml","EntryPoint.EnvironmentVariableAttribute":"EntryPoint.EnvironmentVariableAttribute.yml","EntryPoint.EnvironmentVariableAttribute.#ctor(System.String)":"EntryPoint.EnvironmentVariableAttribute.yml","EntryPoint.EnvironmentVariableAttribute.VariableName":"EntryPoint.EnvironmentVariableAttribute.yml","EntryPoint.HelpAttribute":"EntryPoint.HelpAttribute.yml","EntryPoint.HelpAttribute.#ctor(System.String)":"EntryPoint.HelpAttribute.yml","EntryPoint.HelpAttribute.Detail":"EntryPoint.HelpAttribute.yml","EntryPoint.OperandAttribute":"EntryPoint.OperandAttribute.yml","EntryPoint.OperandAttribute.#ctor(System.Int32)":"EntryPoint.OperandAttribute.yml","EntryPoint.OperandAttribute.Position":"EntryPoint.OperandAttribute.yml","EntryPoint.OptionAttribute":"EntryPoint.OptionAttribute.yml","EntryPoint.OptionAttribute.#ctor(System.String,System.Char)":"EntryPoint.OptionAttribute.yml","EntryPoint.OptionAttribute.#ctor(System.String)":"EntryPoint.OptionAttribute.yml","EntryPoint.OptionAttribute.#ctor(System.Char)":"EntryPoint.OptionAttribute.yml","EntryPoint.OptionParameterAttribute":"EntryPoint.OptionParameterAttribute.yml","EntryPoint.OptionParameterAttribute.#ctor(System.String,System.Char)":"EntryPoint.OptionParameterAttribute.yml","EntryPoint.OptionParameterAttribute.#ctor(System.String)":"EntryPoint.OptionParameterAttribute.yml","EntryPoint.OptionParameterAttribute.#ctor(System.Char)":"EntryPoint.OptionParameterAttribute.yml","EntryPoint.RequiredAttribute":"EntryPoint.RequiredAttribute.yml","EntryPoint.Exceptions":"EntryPoint.Exceptions.yml","EntryPoint.Exceptions.DuplicateOptionException":"EntryPoint.Exceptions.DuplicateOptionException.yml","EntryPoint.Exceptions.InvalidModelException":"EntryPoint.Exceptions.InvalidModelException.yml","EntryPoint.Exceptions.IUserFacingExceptionHandler":"EntryPoint.Exceptions.IUserFacingExceptionHandler.yml","EntryPoint.Exceptions.IUserFacingExceptionHandler.UserFacingExceptionThrown":"EntryPoint.Exceptions.IUserFacingExceptionHandler.yml","EntryPoint.Exceptions.IUserFacingExceptionHandler.OnUserFacingException(EntryPoint.Exceptions.UserFacingException,System.String)":"EntryPoint.Exceptions.IUserFacingExceptionHandler.yml","EntryPoint.Exceptions.NoParameterException":"EntryPoint.Exceptions.NoParameterException.yml","EntryPoint.Exceptions.RequiredException":"EntryPoint.Exceptions.RequiredException.yml","EntryPoint.Exceptions.UnknownOptionException":"EntryPoint.Exceptions.UnknownOptionException.yml","EntryPoint.Exceptions.UserFacingException":"EntryPoint.Exceptions.UserFacingException.yml","EntryPoint.Exceptions.VariableTypeException":"EntryPoint.Exceptions.VariableTypeException.yml","EntryPoint.Help":"EntryPoint.Help.yml","EntryPoint.Help.IHelpable":"EntryPoint.Help.IHelpable.yml","EntryPoint.Help.IHelpable.HelpInvoked":"EntryPoint.Help.IHelpable.yml","EntryPoint.Help.IHelpable.OnHelpInvoked(System.String)":"EntryPoint.Help.IHelpable.yml"}