Move initialization to static constructor

Update docs

Author: mikepal2

README.md

@@ -6,21 +6,25 @@ The library is available in a NuGet package:
 - [SnapCLI](https://www.nuget.org/packages/SnapCLI/)
 
 # Motivation
- The goal of this project is to provide a simple and effective way to handle command-line commands and parameters, allowing developers to create POSIX-like CLI applications with minimal hassle in parsing the command line and enabling them to focus on application logic. Additionally, it facilitates providing all necessary information for the application's help system, making it easily accessible to end users. The [DragonFruit](https://github.com/dotnet/command-line-api/blob/main/docs/DragonFruit-overview.md) project was a step in this direction, but is very limited in abilities it provides.
+The goal of this project is to enable developers to create POSIX-like Command Line Interface (CLI) applications without the need to parse the command line themselves, allowing them to focus on application logic. The library automatically handles command-line commands and parameters using the provided metadata, simplifying the development process. It also streamlines the creation of the application's help system, ensuring that all necessary information is easily accessible to end users.
+ 
+ The [DragonFruit](https://github.com/dotnet/command-line-api/blob/main/docs/DragonFruit-overview.md) project was a step in this direction, but is very limited in abilities it provides.
 
 # API Paradigm
 The API paradigm of this project is to use [attributes](https://learn.microsoft.com/en-us/dotnet/csharp/advanced-topics/reflection-and-attributes/) to declare and describe CLI commands, options, and arguments.
 
 Any public static method can be declared as a CLI command handler using the `[Command]` attribute, and effectively represent an entry point to the CLI application for that command. Any parameter of command handler method automatically becomes a command option. See the [usage](#usage) section and examples below for more details.
 
 ## What about classes?
-There are multiple CLI frameworks that require separate class implementation for each command. In my opinion, creating a per-command classes adds unnecessary bloat to the code with little to no benefit. To provide additional information such as descriptions and aliases, attributes are anyway required on top of the class declaration. Since the goal is to simplify things as much as possible, I decided not to use classes at all in my approach. While this approach may not be as flexible as some other solutions, it meets the basic needs of most CLI applications. 
+Many CLI frameworks require separate class implementations for each command. In my opinion, creating individual classes for each command adds unnecessary bloat to the code with minimal benefit. Using attributes is easier to maintain and understand, as they are declared close to the entities they describe, keeping all related information in one place. Additionally, attributes allow for extra details, such as descriptions and aliases. Since the goal is to simplify the implementation as much as possible, I decided not to use classes at all in my approach. While this method may not be as flexible as some other solutions, it effectively meets the needs of most CLI applications.
 
 ## Command line syntax
 Since this project is based on the [System.CommandLine](https://learn.microsoft.com/en-us/dotnet/standard/commandline/) library, the parsing rules are exactly the same as those for that package. The Microsoft documentation provides detailed explanations of the [command-line syntax](https://learn.microsoft.com/en-us/dotnet/standard/commandline/syntax) recognized by `System.CommandLine`. I will include more links to this documentation throughout the text below.
 
 ## Main method  
-Normally, the `Main` method is the entry point of a C# application. However, to simplify startup code and usage, this library overrides the program's entry point and uses command handler methods as the entry points instead. This means that if you include your own `Main` function in the program, it will **not** be invoked. If you need some initialization code to run before command, it can be placed in [Startup](#startup) method. 
+Typically, the `Main` method serves as the entry point of a C# application. However, to simplify startup code and usage, this library overrides the program's entry point and uses command handler methods as the entry points instead. This means you don't need to write any startup boilerplate code for your CLI application and can dive straight into implementing the application logic, i.e. commands.
+
+It’s important to note that since the library overrides the entry point, if you include your own `Main` function in the program, it will **not** be invoked. If you need some initialization code to run before command, it can be placed in [Startup](#startup) method. 
 
 If you really need to use your own `Main`, you can still do so:
 1. Add `<AutoGenerateEntryPoint>false</AutoGenerateEntryPoint>` property into your program .csproj file
@@ -206,7 +210,7 @@ Options:
 
 **Argument name convention**
 - Argument name is used only for help, it cannot be specified on command line.
-- If argument name is not explicitly specified in the attribute, the  name of the parameter will be implicitly used.
+- If argument name is not explicitly specified in the attribute, the name of the parameter will be implicitly used.
 
 You can provide options before arguments or arguments before options on the command line. See [documentation](https://learn.microsoft.com/en-us/dotnet/standard/commandline/syntax#order-of-options-and-arguments) for details.
 
@@ -216,7 +220,7 @@ The [arity](https://learn.microsoft.com/en-us/dotnet/standard/commandline/syntax
 ```csharp
 [Command(name: "print", description: "Arity example")]
 public static void Print(
-    [Argument(arityMin:1, arityMax:2, name:"numbers", description:"Takes 1 or 2 numbers")]
+    [Argument(name:"numbers", arityMin:1, arityMax:2, description:"Takes 1 or 2 numbers")]
     int[] nums
 )
 {
@@ -404,21 +408,33 @@ public static void Startup(CommandLineBuilder commandLineBuilder)
 }
 ```
 
+The `CLI.RootCommand` property is available in startup method and commands could be additionaly customized by startup code. 
+
+**Important**: When the startup method is invoked, the command line has not been parsed yet; therefore, global parameters still have their default values and not the values from the command line.
+
 ## Exception handling
-To catch unhandled exceptions during command execution you may set exception handler in [Startup](#startup) method. The handler is intended to provide diagnostics according to the need of your application. The return value from handler will be used as program's exit code. For example:
+To catch unhandled exceptions during command execution you may set exception handler in [Startup](#startup) method. The handler is intended to provide exception diagnostics according to the need of your application before exiting. The return value from handler will be used as program's exit code. For example:
 
-```
+```csharp
 [Startup]
 public static void Startup()
 {
     CLI.ExceptionHandler = (exception) => {
-        if (exception is not OperationCanceledException)
-        {
-            var color = Console.ForegroundColor;
-            Console.ForegroundColor = ConsoleColor.Red;
+        var color = Console.ForegroundColor;
+        Console.ForegroundColor = ConsoleColor.Red;
+        if (exception is OperationCanceledException)
+        {   // special case
+            Console.Error.WriteLine("Operation cancelled!");
+        }
+        else if (g_debugMode)
+        {   // show detailed exception info in debug mode
             Console.Error.WriteLine(exception.ToString());
-            Console.ForegroundColor = color;
         }
+        else 
+        {   // show short error message during normal run
+            Console.Error.WriteLine($"Error: {exception.Message}");
+        }
+        Console.ForegroundColor = color;
         return 1; // exit code
     };
 }

src/SnapCLI.cs

@@ -346,71 +346,17 @@ private ConsoleHelper(TextWriter? output, TextWriter? error)
         /// </summary>
         public static event AfterCommandCallback? AfterCommand;
 
-        private static Parser? _parser;
-        private static Parser Parser => _parser ??= BuildCommands();
+        private static Parser Parser { get; }
 
         /// <summary>
-        /// Helper method to run CLI application. Should be called from program Main() entry point.
-        /// </summary>
-        /// <param name="args">Command line arguments passed from Main()</param>
-        /// <param name="output">Redirect output stream</param>
-        /// <param name="error">Redirect error stream</param>
-        /// <returns></returns>
-        public static int Run(string[]? args = null, TextWriter? output = null, TextWriter? error = null) 
-        {
-            try
-            {
-                _error = error;
-                var parseResult = Parser.Parse(args ?? Environment.GetCommandLineArgs().Skip(1).ToArray());
-                return parseResult.Invoke(ConsoleHelper.CreateOrDefault(output, error));
-            }
-            catch (Exception ex)
-            {
-                if (ExceptionHandler != null)
-                    return ExceptionHandler(ex);
-                ExceptionDispatchInfo.Capture(ex).Throw();
-                return 1;
-            }
-        }
-
-        /// <summary>
-        /// Helper asynchronous method to run CLI application. Should be called from program async Main() entry point.
+        /// Provides access to commands hierarchy and their options and arguments.
         /// </summary>
-        /// <param name="args">Command line arguments passed from Main()</param>
-        /// <param name="output">Redirect output stream</param>
-        /// <param name="error">Redirect error stream</param>
-        /// <returns></returns>
-        public static async Task<int> RunAsync(string[]? args = null, TextWriter? output = null, TextWriter? error = null)
-        {
-            try
-            {
-                _error = error;
-                var parseResult = Parser.Parse(args ?? Environment.GetCommandLineArgs().Skip(1).ToArray());
-                return await parseResult.InvokeAsync(ConsoleHelper.CreateOrDefault(output, error));
-            }
-            catch (Exception ex)
-            {
-                if (ExceptionHandler != null)
-                    return ExceptionHandler(ex);
-                ExceptionDispatchInfo.Capture(ex).Throw();
-                return 1;
-            }
-        }
-
-/// <summary>
-/// Provides access to commands hierarchy and their options and arguments.
-/// </summary>
-public static Command RootCommand => Parser.Configuration.RootCommand;
+        public static RootCommand RootCommand { get; }
 
         /// <summary>
         /// Provides access to currently executing command definition.
         /// </summary>
-        public static Command CurrentCommand { 
-            get => _currentCommand ?? throw new InvalidOperationException($"Cannot access {nameof(CurrentCommand)} from outside of CLI command handler method"); 
-            private set => _currentCommand = value; 
-        }
-        private static Command? _currentCommand = null;
-
+        public static Command? CurrentCommand;
         /// <summary>
         /// Handler to use when exception is occured during command execution. Set <code>null</code> to suppress exception handling.
         /// </summary>
@@ -451,8 +397,7 @@ private static int DefaultExceptionHandler(Exception exception)
         /// <summary>
         /// Current command invocation context provides access to parsed command line, CancellationToken, ExitCode and other properties.
         /// </summary>
-        public static InvocationContext CurrentContext => _currentContext ?? throw new InvalidOperationException($"Cannot access {nameof(CurrentContext)} from outside of command handler method");
-        private static InvocationContext? _currentContext;
+        public static InvocationContext? CurrentContext;
 
 #if BEFORE_AFTER_COMMAND_ATTRIBUTE
         private static MethodInfo[]? _beforeCommandsCallbacks;
@@ -474,11 +419,58 @@ public CommandMethodDesc(MethodInfo method, DescriptorAttribute desc)
         }
 
         /// <summary>
-        /// Builds commands hierarchy based on attributes.
+        /// Helper method to run CLI application. Should be called from program Main() entry point.
+        /// </summary>
+        /// <param name="args">Command line arguments passed from Main()</param>
+        /// <param name="output">Redirect output stream</param>
+        /// <param name="error">Redirect error stream</param>
+        /// <returns></returns>
+        public static int Run(string[]? args = null, TextWriter? output = null, TextWriter? error = null) 
+        {
+            try
+            {
+                _error = error;
+                var parseResult = Parser.Parse(args ?? Environment.GetCommandLineArgs().Skip(1).ToArray());
+                return parseResult.Invoke(ConsoleHelper.CreateOrDefault(output, error));
+            }
+            catch (Exception ex)
+            {
+                if (ExceptionHandler != null)
+                    return ExceptionHandler(ex);
+                ExceptionDispatchInfo.Capture(ex).Throw();
+                return 1;
+            }
+        }
+
+        /// <summary>
+        /// Helper asynchronous method to run CLI application. Should be called from program async Main() entry point.
+        /// </summary>
+        /// <param name="args">Command line arguments passed from Main()</param>
+        /// <param name="output">Redirect output stream</param>
+        /// <param name="error">Redirect error stream</param>
+        /// <returns></returns>
+        public static async Task<int> RunAsync(string[]? args = null, TextWriter? output = null, TextWriter? error = null)
+        {
+            try
+            {
+                _error = error;
+                var parseResult = Parser.Parse(args ?? Environment.GetCommandLineArgs().Skip(1).ToArray());
+                return await parseResult.InvokeAsync(ConsoleHelper.CreateOrDefault(output, error));
+            }
+            catch (Exception ex)
+            {
+                if (ExceptionHandler != null)
+                    return ExceptionHandler(ex);
+                ExceptionDispatchInfo.Capture(ex).Throw();
+                return 1;
+            }
+        }        
+
+        /// <summary>
+        /// Static constructor, initializes commands hierarchy from attributes.
         /// </summary>
-        /// <returns>Returns <see cref="Parser"></see></returns>
-        /// <exception cref="InvalidOperationException">Commands hierarchy already built or there are attributes usage errors detected.</exception>
-        private static Parser BuildCommands()
+        /// <exception cref="InvalidOperationException">Attribute usage error detected.</exception>
+        static CLI()
         {
             Assembly executingAssembly = Assembly.GetExecutingAssembly();
             Assembly assembly = Assembly.GetEntryAssembly() ?? executingAssembly;
@@ -509,12 +501,12 @@ private static Parser BuildCommands()
 
             // create root command
 
-            RootCommand rootCommand = CreateRootCommand(assembly, globalDescriptors, commandMethods, out var rootMethod);
+            RootCommand = CreateRootCommand(assembly, globalDescriptors, commandMethods, out var rootMethod);
 
             // add commands without handler methods, i.e. those declared with [Command] on class level
 
             var parentCommands = globalDescriptors.Where(d => d.Kind == DescriptorAttribute.DescKind.Command)
-                .Select(desc => CreateAndAddCommand(rootCommand, desc.Name!, desc))
+                .Select(desc => CreateAndAddCommand(RootCommand, desc.Name!, desc))
                 .ToArray();
 
             // add properties and fields described with [Option]
@@ -532,7 +524,7 @@ private static Parser BuildCommands()
                 if (!prop.SetMethod?.IsStatic == null)
                     throw new InvalidOperationException($"Property {prop.Name} declared as [Option] must be static");
                 var opt = CreateOption(desc, prop.Name, prop.PropertyType, () => prop.GetValue(null));
-                rootCommand.AddGlobalOption(opt);
+                RootCommand.AddGlobalOption(opt);
                 globalOptionsInitializersList.Add((ctx) => prop.SetValue(null, ctx.ParseResult.GetValueForOption(opt)));
             }
 
@@ -547,7 +539,7 @@ private static Parser BuildCommands()
                 if (!field.IsStatic)
                     throw new InvalidOperationException($"Field {field.Name} declared as [Option] must be static");
                 var opt = CreateOption(desc, field.Name, field.FieldType, () => field.GetValue(null));
-                rootCommand.AddGlobalOption(opt);
+                RootCommand.AddGlobalOption(opt);
                 globalOptionsInitializersList.Add((ctx) => field.SetValue(null, ctx.ParseResult.GetValueForOption(opt)));
             }
 
@@ -572,13 +564,13 @@ private static Parser BuildCommands()
 #endif
 
             if (rootMethod != null)
-                AddCommandHandler(rootCommand, rootMethod.Method, globalOptionsInitializers);
+                AddCommandHandler(RootCommand, rootMethod.Method, globalOptionsInitializers);
 
             foreach (var m in commandMethods
                 .Where(m => m.Desc.Kind == DescriptorAttribute.DescKind.Command && m != rootMethod)
                 .OrderBy(m => m.CommandName.Length)) // sort by name length to ensure parent commands created before subcommands
             {
-                var command = CreateAndAddCommand(rootCommand, m.CommandName, m.Desc);
+                var command = CreateAndAddCommand(RootCommand, m.CommandName, m.Desc);
                 AddCommandHandler(command, m.Method, globalOptionsInitializers);
             }
 
@@ -588,7 +580,7 @@ private static Parser BuildCommands()
                 if (command.Subcommands.Count == 0 && command.Handler == null && command.IsHidden == false)
                     throw new InvalidOperationException($"Command '{command.Name}' has no subcommands nor handler methods");
 
-            var builder = new CommandLineBuilder(rootCommand);
+            var builder = new CommandLineBuilder(RootCommand);
 
             // call [Startup] methods
 
@@ -647,9 +639,7 @@ private static Parser BuildCommands()
                     ExceptionHandler?.Invoke(ex);
             };
 
-            var parser = builder.Build();
-
-            return parser;
+            Parser = builder.Build();
         }
 
         // find [RootCommand] and [Command] attributes declared on class
@@ -816,8 +806,8 @@ private static void AddCommandHandler(Command command, MethodInfo method, Action
 
             command.SetHandler(async (ctx) =>
             {
-                _currentCommand = command;
-                _currentContext = ctx;
+                CurrentCommand = command;
+                CurrentContext = ctx;
 
                 foreach (var initializer in globalOptionsInitializers)
                     initializer.Invoke(ctx);

tests/UnitTest1.cs

@@ -127,7 +127,7 @@ public void TestCLI(string commandLine, string pattern, UseExceptionHandler useE
 
         private static void TraceCommand(params object?[] args)
         {
-            Out.WriteLine($"[{CLI.CurrentCommand.Name}({string.Join(",", args)})]");
+            Out.WriteLine($"[{CLI.CurrentCommand?.Name}({string.Join(",", args)})]");
         }
 
         private static int CustomExceptionHandler(Exception exception)