Merge branch 'enhance/user-facing-exception'

docs-generation/Website/article_arguments.cs

@@ -5,6 +5,7 @@
 
 using EntryPoint;
 using System.Collections.Generic;
+using EntryPoint.Exceptions;
 
 namespace Website {
     class article_arguments {
@@ -52,6 +53,10 @@ public SimpleCliArguments() : base("SimpleApp") { }
             // un-mapped operands are stored
             [Operand(Position: 1)]
             public decimal FirstOperand { get; set; }
+
+            public override void OnUserFacingException(UserFacingException e, string message) {
+                throw new NotImplementedException();
+            }
         }
 #endif
 
@@ -139,6 +144,10 @@ public MessagingCliArguments() : base("Message Sender") { }
             [Required]
             [Operand(1)]
             public string Message { get; set; }
+
+            public override void OnUserFacingException(UserFacingException e, string message) {
+                throw new NotImplementedException();
+            }
         }
 
         enum MessageImportanceEnum {

docs-generation/Website/article_commands.cs

@@ -5,6 +5,7 @@
 
 using EntryPoint;
 using System.Collections.Generic;
+using EntryPoint.Exceptions;
 
 namespace Website {
     class article_commands {
@@ -45,6 +46,10 @@ public void Command2(string[] args) {
                 // var arguments = Cli.Parse<Command2CliArguments>(args);
                 // ...Application logic
             }
+
+            public override void OnUserFacingException(UserFacingException e, string message) {
+                throw new NotImplementedException();
+            }
         }
 #endif
 

docs-generation/Website/article_help_generator.cs

@@ -5,6 +5,7 @@
 
 using EntryPoint;
 using System.Collections.Generic;
+using EntryPoint.Exceptions;
 
 namespace Website {
     class article_help_generator {
@@ -39,6 +40,10 @@ class ExampleHelpCliCommands : BaseCliCommands {
             public void Command1(string[] args) {
                 // ...etc
             }
+
+            public override void OnUserFacingException(UserFacingException e, string message) {
+                throw new NotImplementedException();
+            }
         }
 
         class CommandsHelpProgram {
@@ -68,6 +73,10 @@ public ExampleHelpCliArguments()
             [OptionParameter(LongName: "value1")]
             [Help("Some value to set")]
             public bool Value1 { get; set; }
+
+            public override void OnUserFacingException(UserFacingException e, string message) {
+                throw new NotImplementedException();
+            }
         }
 
         class ArgumentsHelpProgram {
@@ -109,6 +118,10 @@ public override void OnHelpInvoked(string helpText) {
                 Console.WriteLine(helpText);
                 throw new HelpInvokedException("Using an exception to control application flow");
             }
+
+            public override void OnUserFacingException(UserFacingException e, string message) {
+                throw new NotImplementedException();
+            }
         }
 #endif
         class HelpInvokedException : Exception {

docs-generation/Website/article_user_facing_exceptions.cs

@@ -0,0 +1,117 @@
+#define CODE
+
+using System;
+using System.Linq;
+
+using EntryPoint;
+using System.Collections.Generic;
+using EntryPoint.Exceptions;
+
+namespace Website {
+    class article_user_facing_exceptions {
+        /// ## User Facing Exceptions
+        /// 
+        /// When a user makes a mistake, EntryPoint will throw an exception which derives from UserFacingException.
+        /// 
+        /// This exception is caught and the following takes place on the relevant CliCommands or CliArguments instance
+        /// * `.UserFacingExceptionThrown` is set to `true`
+        /// * the virtual method `.OnUserFacingException(UserFacingException e, string message)` is called
+        /// 
+        /// The virtual method contains a sane default implementation which prints to screen and exits the application.
+        /// 
+        /// 
+        /// #### Custom OnUserFacingException Handler
+        /// 
+        /// If you want your own implementation you can override this, like so
+        /// 
+#if CODE
+        class CliArguments : BaseCliArguments {
+            public CliArguments() : base("Test") { }
+
+            [Option(LongName: "Option",
+                    ShortName: 'o')]
+            public bool Option { get; set; }
+
+            public override void OnUserFacingException(UserFacingException e, string message) {
+                // your own handling of the message for the user
+                Console.WriteLine("User error: " + message);
+            }
+        }
+
+        class UserFacingExceptionProgram {
+            public void main(string[] args) {
+                var arguments = Cli.Parse<CliArguments>(args);
+                // Execution would not reach this point if the user provides invalid arguments, 
+                // since OnUserFacingException would run and exit the program
+
+                // However, if you override OnUserFacingException and don't exit, 
+                // you could also do this:
+                if (arguments.UserFacingExceptionThrown) {
+                    // Return here, or run something else
+                }
+
+                // Normal Post-Arguments Application code...
+            }
+        }
+#endif
+
+        /// #### UserFacingException Bubbling
+        /// 
+        /// If your application utilises both CliCommands and CliArguments, 
+        /// you may want to handle UserFacingExceptions only on the CliCommands level.
+        /// 
+        /// This can be achieved using bubbling. 
+        /// 
+        /// Simply override OnUserFacingException in your CliArguments implementations and re-throw the exception.
+        /// The exception will then be caught at the CliCommands level.
+        /// 
+#if CODE
+        class BubblingCliArguments : BaseCliArguments {
+            public BubblingCliArguments() : base("Test") { }
+
+            [Option(LongName: "Option",
+                    ShortName: 'o')]
+            public bool Option { get; set; }
+
+            public override void OnUserFacingException(UserFacingException e, string message) {
+                // Re-throw the exception, causing it to bubble up to the root command
+                throw e;
+            }
+        }
+
+        class BubblingCliCommands : BaseCliCommands{
+
+            [Command("command1")]
+            public void Command1(string[] args) {
+                var arguments = Cli.Parse<BubblingCliArguments>(args);
+
+                // Normal Post-Arguments application logic
+            }
+
+            public override void OnUserFacingException(UserFacingException e, string message) {
+                // All UserFacingException throws will now come to here
+                Console.WriteLine("User error: " + message);
+                Console.ReadLine();
+                Environment.Exit(1);
+            }
+        }
+
+        class BubblingProgram {
+            public void main(string[] args) {
+                var commands = Cli.Execute<BubblingCliCommands>(args);
+                // Execution would not reach this point when the user provides invalid 
+                // commands or arguments, since our custom OnUserFacingException handler 
+                // would run and exit the program
+
+                // However, if you override OnUserFacingException and don't exit, 
+                // you could also do this:
+                if (commands.UserFacingExceptionThrown) {
+                    // Return here, or run something else
+                }
+
+                // Normal Post-Command Application code...
+            }
+        }
+#endif
+    }
+}

docs-generation/Website/www/arguments.md

@@ -42,6 +42,10 @@ This has one Option `-s`, one OptionParameter `--name Bob` and a positional Oper
         // un-mapped operands are stored
         [Operand(Position: 1)]
         public decimal FirstOperand { get; set; }
+
+        public override void OnUserFacingException(UserFacingException e, string message) {
+            throw new NotImplementedException();
+        }
     }
 
 #### Attributes
@@ -126,6 +130,10 @@ The following is used like:
         [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/commands.md

@@ -35,6 +35,10 @@ This is the purpose of `BaseCliCommands`.
             // var arguments = Cli.Parse<Command2CliArguments>(args);
             // ...Application logic
         }
+
+        public override void OnUserFacingException(UserFacingException e, string message) {
+            throw new NotImplementedException();
+        }
     }
 
 #### Attributes

docs-generation/Website/www/help_generator.md

@@ -29,6 +29,10 @@ The Help Generator consumes the following information for each class type.
         public void Command1(string[] args) {
             // ...etc
         }
+
+        public override void OnUserFacingException(UserFacingException e, string message) {
+            throw new NotImplementedException();
+        }
     }
 
     class CommandsHelpProgram {
@@ -58,6 +62,10 @@ The Help Generator consumes the following information for each class type.
         [OptionParameter(LongName: "value1")]
         [Help("Some value to set")]
         public bool Value1 { get; set; }
+
+        public override void OnUserFacingException(UserFacingException e, string message) {
+            throw new NotImplementedException();
+        }
     }
 
     class ArgumentsHelpProgram {
@@ -98,4 +106,8 @@ Below is a brief example of overriding the help method.
             Console.WriteLine(helpText);
             throw new HelpInvokedException("Using an exception to control application flow");
         }
+
+        public override void OnUserFacingException(UserFacingException e, string message) {
+            throw new NotImplementedException();
+        }
     }

docs-generation/Website/www/user_facing_exceptions.md

@@ -0,0 +1,102 @@
+## User Facing Exceptions
+
+When a user makes a mistake, EntryPoint will throw an exception which derives from UserFacingException.
+
+This exception is caught and the following takes place on the relevant CliCommands or CliArguments instance
+* `.UserFacingExceptionThrown` is set to `true`
+* the virtual method `.OnUserFacingException(UserFacingException e, string message)` is called
+
+The virtual method contains a sane default implementation which prints to screen and exits the application.
+
+
+#### Custom OnUserFacingException Handler
+
+If you want your own implementation you can override this, like so
+
+
+    class CliArguments : BaseCliArguments {
+        public CliArguments() : base("Test") { }
+
+        [Option(LongName: "Option",
+                ShortName: 'o')]
+        public bool Option { get; set; }
+
+        public override void OnUserFacingException(UserFacingException e, string message) {
+            // your own handling of the message for the user
+            Console.WriteLine("User error: " + message);
+        }
+    }
+
+    class UserFacingExceptionProgram {
+        public void main(string[] args) {
+            var arguments = Cli.Parse<CliArguments>(args);
+            // Execution would not reach this point if the user provides invalid arguments, 
+            // since OnUserFacingException would run and exit the program
+
+            // However, if you override OnUserFacingException and don't exit, 
+            // you could also do this:
+            if (arguments.UserFacingExceptionThrown) {
+                // Return here, or run something else
+            }
+
+            // Normal Post-Arguments Application code...
+        }
+    }
+
+#### UserFacingException Bubbling
+
+If your application utilises both CliCommands and CliArguments,
+you may want to handle UserFacingExceptions only on the CliCommands level.
+
+This can be achieved using bubbling.
+
+Simply override OnUserFacingException in your CliArguments implementations and re-throw the exception.
+The exception will then be caught at the CliCommands level.
+
+
+    class BubblingCliArguments : BaseCliArguments {
+        public BubblingCliArguments() : base("Test") { }
+
+        [Option(LongName: "Option",
+                ShortName: 'o')]
+        public bool Option { get; set; }
+
+        public override void OnUserFacingException(UserFacingException e, string message) {
+            // Re-throw the exception, causing it to bubble up to the root command
+            throw e;
+        }
+    }
+
+    class BubblingCliCommands : BaseCliCommands{
+
+        [Command("command1")]
+        public void Command1(string[] args) {
+            var arguments = Cli.Parse<BubblingCliArguments>(args);
+
+            // Normal Post-Arguments application logic
+        }
+
+        public override void OnUserFacingException(UserFacingException e, string message) {
+            // All UserFacingException throws will now come to here
+            Console.WriteLine("User error: " + message);
+            Console.ReadLine();
+            Environment.Exit(1);
+        }
+    }
+
+    class BubblingProgram {
+        public void main(string[] args) {
+            var commands = Cli.Execute<BubblingCliCommands>(args);
+            // Execution would not reach this point when the user provides invalid 
+            // commands or arguments, since our custom OnUserFacingException handler 
+            // would run and exit the program
+
+            // However, if you override OnUserFacingException and don't exit, 
+            // you could also do this:
+            if (commands.UserFacingExceptionThrown) {
+                // Return here, or run something else
+            }
+
+            // Normal Post-Command Application code...
+        }
+    }