Added intro (animated gif) to README.md

dotmake-build · Feb 15, 2024 · 26dc0e7 · 26dc0e7
1 parent 85b395d
commit 26dc0e7
Show file tree

Hide file tree

Showing 77 changed files with 147 additions and 122 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -44,15 +44,22 @@ PM> Install-Package DotMake.CommandLine
 ### Delegate-based model
 
 Create a CLI App with DotMake.Commandline in seconds!
-In Program.cs, add this simple code:
+
+In `Program.cs`, add this simple code:
 ```c#
+using System;
+using DotMake.CommandLine;
+
 Cli.Run(([CliArgument]string argument1, bool option1) =>
 {
     Console.WriteLine($@"Value for {nameof(argument1)} parameter is '{argument1}'");
     Console.WriteLine($@"Value for {nameof(option1)} parameter is '{option1}'");
 });
 ```
-And that's it! You now have a fully working command-line app.
+And that's it! You now have a fully working command-line app:
+
+![DotMake Command-Line Intro](https://raw.githubusercontent.com/dotmake-build/command-line/master/images/intro.gif "DotMake Command-Line Intro")
+
 
 #### Summary
 - Pass a delegate (a parenthesized lambda expression or a method reference) which has parameters that represent your options and arguments, to `Cli.Run`.
@@ -68,13 +75,18 @@ And that's it! You now have a fully working command-line app.
 
 ### Class-based model
 
-While delegate-based model above is useful for simple apps, for more complex apps, you can use the class-based model.
-Create a simple class like this:
+While delegate-based model above is useful for simple apps, for more complex apps, you should use the class-based model 
+because you can have sub-commands and command inheritance.
 
+In `Program.cs`, add this simple code:
 ```c#
 using System;
 using DotMake.CommandLine;
 
+// Add this single line to run you app!
+Cli.Run<RootCliCommand>(args);
+
+// Create a simple class like this to define your root command:
 [CliCommand(Description = "A root cli command")]
 public class RootCliCommand
 {
@@ -93,10 +105,6 @@ public class RootCliCommand
     }
 }
 ```
-In Program.cs, add this single line:
-```c#
-Cli.Run<RootCliCommand>(args);
-```
 And that's it! You now have a fully working command-line app. You just specify the name of your class which represents your root command to `Cli.Run<>` method and everything is wired.
 
 > `args` is the string array typically passed to a program. This is usually
@@ -178,6 +186,8 @@ if (parseResult.Errors.Count > 0)
   This can be also controlled manually by extension method `ShowHelp` in `CliContext`.
   Other extension methods `IsEmptyCommand` and `ShowValues` are also useful.
 - Call `Cli.Run<>` or`Cli.RunAsync<>` method with your class name to run your CLI app (see [Cli](https://dotmake.build/api/html/T_DotMake_CommandLine_Cli.htm) docs for more info).
+- For best practice, create a subfolder named `Commands` in your project and put your command classes there 
+  so that they are easy to locate and maintain in the future.
 
 ## Commands
 
@@ -570,7 +580,6 @@ The following types for properties are supported:
 * Enums - The values are bound by name, and the binding is case insensitive
 * Common CLR types:
 
-  * `string`, `bool`
   * `FileSystemInfo`, `FileInfo`, `DirectoryInfo`
   * `int`, `long`, `short`, `uint`, `ulong`, `ushort`
   * `double`, `float`, `decimal`
@@ -655,54 +664,71 @@ The following types for properties are supported:
     }
     ```
 
-* Arrays, lists, collections - any type that implements `IEnumerable<T>` and has a public constructor with a `IEnumerable<T>` or `IList<T>` parameter (other parameters, if any, should be optional).
-  If type is generic `IEnumerable<T>`, `IList<T>`, `ICollection<T>` interfaces itself, array `T[]` will be used.
-  If type is non-generic `IEnumerable`, `IList`, `ICollection` interfaces itself, array `string[]` will be used.
-    ```c#
-    [CliCommand]
-    public class EnumerableCliCommand
-    {
-        [CliOption]
-        public IEnumerable<int> OptEnumerable { get; set; }
+* Arrays, lists, collections:
+
+  * Any type that implements `IEnumerable<T>` and has a public constructor with a `IEnumerable<T>` or `IList<T>` parameter 
+    (other parameters, if any, should be optional). CLR collection types already satisfy this condition.
+
+  * If type is generic `IEnumerable<T>`, `IList<T>`, `ICollection<T>` interfaces itself, array `T[]` will be used to create an instance.
+
+  * If type is non-generic `IEnumerable`, `IList`, `ICollection` interfaces itself, array `string[]` will be used to create an instance.
+
+  ```c#
+  [CliCommand]
+  public class EnumerableCliCommand
+  {
+      [CliOption]
+      public IEnumerable<int> OptEnumerable { get; set; }
 
-        [CliOption]
-        public List<string> OptList { get; set; }
+      [CliOption]
+      public List<string> OptList { get; set; }
 
-        [CliOption(AllowMultipleArgumentsPerToken = true)]
-        public FileAccess[] OptEnumArray { get; set; }
+      [CliOption(AllowMultipleArgumentsPerToken = true)]
+      public FileAccess[] OptEnumArray { get; set; }
 
-        [CliOption]
-        public Collection<string> OptCollection { get; set; }
+      [CliOption]
+      public Collection<string> OptCollection { get; set; }
 
-        [CliOption]
-        public HashSet<string> OptHashSet { get; set; }
+      [CliOption]
+      public HashSet<string> OptHashSet { get; set; }
 
-        [CliOption]
-        public Queue<FileInfo> OptQueue { get; set; }
+      [CliOption]
+      public Queue<FileInfo> OptQueue { get; set; }
 
-        [CliOption]
-        public CustomList<string> OptCustomList { get; set; }
-
-        [CliArgument]
-        public IList ArgIList { get; set; }
-    }
-
-    public class CustomList<T> : List<T>
-    {
-        public CustomList(IEnumerable<T> items)
-            : base(items)
-        {
+      [CliOption]
+      public CustomList<string> OptCustomList { get; set; }
 
-        }
-    }
-    ```
+      [CliArgument]
+      public IList ArgIList { get; set; }
+  }
+
+  public class CustomList<T> : List<T>
+  {
+      public CustomList(IEnumerable<T> items)
+          : base(items)
+      {
+
+      }
+  }
+  ```
 
 ### Validation
 
 In `[CliOption]` and `[CliArgument]` attributes;
-`ValidationRules` property allows setting predefined validation rules such as `ExistingFile`, `NonExistingFile`, `ExistingDirectory`,
-`NonExistingDirectory`, `ExistingFileOrDirectory`, `NonExistingFileOrDirectory`, `LegalPath`, `LegalFileName`, `LegalUri`, `LegalUrl`.
-Validation rules can be combined.
+`ValidationRules` property allows setting predefined validation rules such as
+- `CliValidationRules.ExistingFile`
+- `CliValidationRules.NonExistingFile`
+- `CliValidationRules.ExistingDirectory`
+- `CliValidationRules.NonExistingDirectory`
+- `CliValidationRules.ExistingFileOrDirectory`
+- `CliValidationRules.NonExistingFileOrDirectory`
+- `CliValidationRules.LegalPath`
+- `CliValidationRules.LegalFileName`
+- `CliValidationRules.LegalUri` 
+- `CliValidationRules.LegalUrl`
+
+Validation rules can be combined via using bitwise 'or' operator(`|` in C#).
+
 `ValidationPattern` property allows setting a regular expression pattern for custom validation,
 and `ValidationMessage` property allows setting a custom error message to show when `ValidationPattern` does not match.
 
@@ -829,7 +855,7 @@ public sealed class SingletonClass : IDisposable
 ## Help output
 
 When you run the app via 
-- `TestApp.exe -?` in project output path (e.g. in `TestApp\bin\Debug\net6.0`)
+- `TestApp.exe -?` in project output path (e.g. in `TestApp\bin\Debug\net7.0`)
 - or `dotnet run -- -?` in project directory (e.g. in `TestApp`) (note the double hyphen/dash which allows `dotnet run` to pass arguments to our actual application)
 
 - You see this usage help:

diff --git a/docs/intro.gif b/docs/intro.gif
diff --git a/...otMake.CommandLine.SourceGeneration.CliCommandGenerator/(ModuleInitializerAttribute).g.cs b/...otMake.CommandLine.SourceGeneration.CliCommandGenerator/(ModuleInitializerAttribute).g.cs
@@ -1,6 +1,6 @@
 // <auto-generated />
 // Generated by DotMake.CommandLine.SourceGeneration v1.8.0.0
-// Roslyn (Microsoft.CodeAnalysis) v4.800.23.57201
+// Roslyn (Microsoft.CodeAnalysis) v4.900.24.8111
 // Generation: 1
 
 #if !NET5_0_OR_GREATER

diff --git a/...n/DotMake.CommandLine.SourceGeneration.CliCommandGenerator/(RequiredMemberAttribute).g.cs b/...n/DotMake.CommandLine.SourceGeneration.CliCommandGenerator/(RequiredMemberAttribute).g.cs
@@ -1,6 +1,6 @@
 // <auto-generated />
 // Generated by DotMake.CommandLine.SourceGeneration v1.8.0.0
-// Roslyn (Microsoft.CodeAnalysis) v4.800.23.57201
+// Roslyn (Microsoft.CodeAnalysis) v4.900.24.8111
 // Generation: 1
 
 // Licensed to the .NET Foundation under one or more agreements.

diff --git a/...Line.SourceGeneration.CliCommandGenerator/ArgumentConverterCliCommandBuilder-f61jepm.g.cs b/...Line.SourceGeneration.CliCommandGenerator/ArgumentConverterCliCommandBuilder-f61jepm.g.cs
@@ -1,6 +1,6 @@
 // <auto-generated />
 // Generated by DotMake.CommandLine.SourceGeneration v1.8.0.0
-// Roslyn (Microsoft.CodeAnalysis) v4.800.23.57201
+// Roslyn (Microsoft.CodeAnalysis) v4.900.24.8111
 // Generation: 1
 
 namespace TestApp.Commands

diff --git a/...andLine.SourceGeneration.CliCommandGenerator/AsyncIntReturnCliCommandBuilder-7vdns44.g.cs b/...andLine.SourceGeneration.CliCommandGenerator/AsyncIntReturnCliCommandBuilder-7vdns44.g.cs
@@ -1,6 +1,6 @@
 // <auto-generated />
 // Generated by DotMake.CommandLine.SourceGeneration v1.8.0.0
-// Roslyn (Microsoft.CodeAnalysis) v4.800.23.57201
+// Roslyn (Microsoft.CodeAnalysis) v4.900.24.8111
 // Generation: 1
 
 namespace TestApp.Commands

diff --git a/...ndLine.SourceGeneration.CliCommandGenerator/AsyncVoidReturnCliCommandBuilder-7ha5x0r.g.cs b/...ndLine.SourceGeneration.CliCommandGenerator/AsyncVoidReturnCliCommandBuilder-7ha5x0r.g.cs
@@ -1,6 +1,6 @@
 // <auto-generated />
 // Generated by DotMake.CommandLine.SourceGeneration v1.8.0.0
-// Roslyn (Microsoft.CodeAnalysis) v4.800.23.57201
+// Roslyn (Microsoft.CodeAnalysis) v4.900.24.8111
 // Generation: 1
 
 namespace TestApp.Commands

diff --git a/....CommandLine.SourceGeneration.CliCommandGenerator/CamelCaseCliCommandBuilder-293mz7r.g.cs b/....CommandLine.SourceGeneration.CliCommandGenerator/CamelCaseCliCommandBuilder-293mz7r.g.cs
@@ -1,6 +1,6 @@
 // <auto-generated />
 // Generated by DotMake.CommandLine.SourceGeneration v1.8.0.0
-// Roslyn (Microsoft.CodeAnalysis) v4.800.23.57201
+// Roslyn (Microsoft.CodeAnalysis) v4.900.24.8111
 // Generation: 1
 
 namespace TestApp.Commands.CasingConvention

diff --git a/...otMake.CommandLine.SourceGeneration.CliCommandGenerator/CliCommandAsDelegate_4yk4pbm.g.cs b/...otMake.CommandLine.SourceGeneration.CliCommandGenerator/CliCommandAsDelegate_4yk4pbm.g.cs
@@ -1,6 +1,6 @@
 // <auto-generated />
 // Generated by DotMake.CommandLine.SourceGeneration v1.8.0.0
-// Roslyn (Microsoft.CodeAnalysis) v4.800.23.57201
+// Roslyn (Microsoft.CodeAnalysis) v4.900.24.8111
 // Generation: 1
 
 namespace GeneratedCode

diff --git a/...ine.SourceGeneration.CliCommandGenerator/CliCommandAsDelegate_4yk4pbmBuilder-fgjtvar.g.cs b/...ine.SourceGeneration.CliCommandGenerator/CliCommandAsDelegate_4yk4pbmBuilder-fgjtvar.g.cs
@@ -1,6 +1,6 @@
 // <auto-generated />
 // Generated by DotMake.CommandLine.SourceGeneration v1.8.0.0
-// Roslyn (Microsoft.CodeAnalysis) v4.800.23.57201
+// Roslyn (Microsoft.CodeAnalysis) v4.900.24.8111
 // Generation: 1
 
 namespace GeneratedCode

diff --git a/...otMake.CommandLine.SourceGeneration.CliCommandGenerator/CliCommandAsDelegate_5v59h64.g.cs b/...otMake.CommandLine.SourceGeneration.CliCommandGenerator/CliCommandAsDelegate_5v59h64.g.cs
@@ -1,6 +1,6 @@
 // <auto-generated />
 // Generated by DotMake.CommandLine.SourceGeneration v1.8.0.0
-// Roslyn (Microsoft.CodeAnalysis) v4.800.23.57201
+// Roslyn (Microsoft.CodeAnalysis) v4.900.24.8111
 // Generation: 1
 
 namespace GeneratedCode

diff --git a/...ine.SourceGeneration.CliCommandGenerator/CliCommandAsDelegate_5v59h64Builder-7065v10.g.cs b/...ine.SourceGeneration.CliCommandGenerator/CliCommandAsDelegate_5v59h64Builder-7065v10.g.cs
@@ -1,6 +1,6 @@
 // <auto-generated />
 // Generated by DotMake.CommandLine.SourceGeneration v1.8.0.0
-// Roslyn (Microsoft.CodeAnalysis) v4.800.23.57201
+// Roslyn (Microsoft.CodeAnalysis) v4.900.24.8111
 // Generation: 1
 
 namespace GeneratedCode

diff --git a/...otMake.CommandLine.SourceGeneration.CliCommandGenerator/CliCommandAsDelegate_a5kez68.g.cs b/...otMake.CommandLine.SourceGeneration.CliCommandGenerator/CliCommandAsDelegate_a5kez68.g.cs
@@ -1,6 +1,6 @@
 // <auto-generated />
 // Generated by DotMake.CommandLine.SourceGeneration v1.8.0.0
-// Roslyn (Microsoft.CodeAnalysis) v4.800.23.57201
+// Roslyn (Microsoft.CodeAnalysis) v4.900.24.8111
 // Generation: 1
 
 namespace GeneratedCode

diff --git a/...ine.SourceGeneration.CliCommandGenerator/CliCommandAsDelegate_a5kez68Builder-8v0rf78.g.cs b/...ine.SourceGeneration.CliCommandGenerator/CliCommandAsDelegate_a5kez68Builder-8v0rf78.g.cs
@@ -1,6 +1,6 @@
 // <auto-generated />
 // Generated by DotMake.CommandLine.SourceGeneration v1.8.0.0
-// Roslyn (Microsoft.CodeAnalysis) v4.800.23.57201
+// Roslyn (Microsoft.CodeAnalysis) v4.900.24.8111
 // Generation: 1
 
 namespace GeneratedCode

diff --git a/...otMake.CommandLine.SourceGeneration.CliCommandGenerator/CliCommandAsDelegate_a79pkj0.g.cs b/...otMake.CommandLine.SourceGeneration.CliCommandGenerator/CliCommandAsDelegate_a79pkj0.g.cs
@@ -1,6 +1,6 @@
 // <auto-generated />
 // Generated by DotMake.CommandLine.SourceGeneration v1.8.0.0
-// Roslyn (Microsoft.CodeAnalysis) v4.800.23.57201
+// Roslyn (Microsoft.CodeAnalysis) v4.900.24.8111
 // Generation: 1
 
 namespace GeneratedCode

diff --git a/...ine.SourceGeneration.CliCommandGenerator/CliCommandAsDelegate_a79pkj0Builder-7q3whb8.g.cs b/...ine.SourceGeneration.CliCommandGenerator/CliCommandAsDelegate_a79pkj0Builder-7q3whb8.g.cs
@@ -1,6 +1,6 @@
 // <auto-generated />
 // Generated by DotMake.CommandLine.SourceGeneration v1.8.0.0
-// Roslyn (Microsoft.CodeAnalysis) v4.800.23.57201
+// Roslyn (Microsoft.CodeAnalysis) v4.900.24.8111
 // Generation: 1
 
 namespace GeneratedCode

diff --git a/...otMake.CommandLine.SourceGeneration.CliCommandGenerator/CliCommandAsDelegate_dtqhqvw.g.cs b/...otMake.CommandLine.SourceGeneration.CliCommandGenerator/CliCommandAsDelegate_dtqhqvw.g.cs
@@ -1,6 +1,6 @@
 // <auto-generated />
 // Generated by DotMake.CommandLine.SourceGeneration v1.8.0.0
-// Roslyn (Microsoft.CodeAnalysis) v4.800.23.57201
+// Roslyn (Microsoft.CodeAnalysis) v4.900.24.8111
 // Generation: 1
 
 namespace GeneratedCode

diff --git a/...ine.SourceGeneration.CliCommandGenerator/CliCommandAsDelegate_dtqhqvwBuilder-24t9d3r.g.cs b/...ine.SourceGeneration.CliCommandGenerator/CliCommandAsDelegate_dtqhqvwBuilder-24t9d3r.g.cs
@@ -1,6 +1,6 @@
 // <auto-generated />
 // Generated by DotMake.CommandLine.SourceGeneration v1.8.0.0
-// Roslyn (Microsoft.CodeAnalysis) v4.800.23.57201
+// Roslyn (Microsoft.CodeAnalysis) v4.900.24.8111
 // Generation: 1
 
 namespace GeneratedCode

diff --git a/...otMake.CommandLine.SourceGeneration.CliCommandGenerator/CliCommandAsDelegate_fsqgtf8.g.cs b/...otMake.CommandLine.SourceGeneration.CliCommandGenerator/CliCommandAsDelegate_fsqgtf8.g.cs
@@ -1,6 +1,6 @@
 // <auto-generated />
 // Generated by DotMake.CommandLine.SourceGeneration v1.8.0.0
-// Roslyn (Microsoft.CodeAnalysis) v4.800.23.57201
+// Roslyn (Microsoft.CodeAnalysis) v4.900.24.8111
 // Generation: 1
 
 namespace GeneratedCode

diff --git a/...ine.SourceGeneration.CliCommandGenerator/CliCommandAsDelegate_fsqgtf8Builder-adpk9bw.g.cs b/...ine.SourceGeneration.CliCommandGenerator/CliCommandAsDelegate_fsqgtf8Builder-adpk9bw.g.cs
@@ -1,6 +1,6 @@
 // <auto-generated />
 // Generated by DotMake.CommandLine.SourceGeneration v1.8.0.0
-// Roslyn (Microsoft.CodeAnalysis) v4.800.23.57201
+// Roslyn (Microsoft.CodeAnalysis) v4.900.24.8111
 // Generation: 1
 
 namespace GeneratedCode

diff --git a/...CommandLine.SourceGeneration.CliCommandGenerator/EnumerableCliCommandBuilder-7xpketw.g.cs b/...CommandLine.SourceGeneration.CliCommandGenerator/EnumerableCliCommandBuilder-7xpketw.g.cs
@@ -1,6 +1,6 @@
 // <auto-generated />
 // Generated by DotMake.CommandLine.SourceGeneration v1.8.0.0
-// Roslyn (Microsoft.CodeAnalysis) v4.800.23.57201
+// Roslyn (Microsoft.CodeAnalysis) v4.900.24.8111
 // Generation: 1
 
 namespace TestApp.Commands

diff --git a/...Line.SourceGeneration.CliCommandGenerator/ExternalLevel1SubCliCommandBuilder-1qdg7dr.g.cs b/...Line.SourceGeneration.CliCommandGenerator/ExternalLevel1SubCliCommandBuilder-1qdg7dr.g.cs
@@ -1,6 +1,6 @@
 // <auto-generated />
 // Generated by DotMake.CommandLine.SourceGeneration v1.8.0.0
-// Roslyn (Microsoft.CodeAnalysis) v4.800.23.57201
+// Roslyn (Microsoft.CodeAnalysis) v4.900.24.8111
 // Generation: 1
 
 namespace TestApp.Commands.External

diff --git a/...Line.SourceGeneration.CliCommandGenerator/ExternalLevel2SubCliCommandBuilder-cmx9hw0.g.cs b/...Line.SourceGeneration.CliCommandGenerator/ExternalLevel2SubCliCommandBuilder-cmx9hw0.g.cs
@@ -1,6 +1,6 @@
 // <auto-generated />
 // Generated by DotMake.CommandLine.SourceGeneration v1.8.0.0
-// Roslyn (Microsoft.CodeAnalysis) v4.800.23.57201
+// Roslyn (Microsoft.CodeAnalysis) v4.900.24.8111
 // Generation: 1
 
 namespace TestApp.Commands.External

diff --git a/...mmandLine.SourceGeneration.CliCommandGenerator/ForwardSlashCliCommandBuilder-1pt4qm0.g.cs b/...mmandLine.SourceGeneration.CliCommandGenerator/ForwardSlashCliCommandBuilder-1pt4qm0.g.cs
@@ -1,6 +1,6 @@
 // <auto-generated />
 // Generated by DotMake.CommandLine.SourceGeneration v1.8.0.0
-// Roslyn (Microsoft.CodeAnalysis) v4.800.23.57201
+// Roslyn (Microsoft.CodeAnalysis) v4.900.24.8111
 // Generation: 1
 
 namespace TestApp.Commands.PrefixConvention

diff --git a/...ndLine.SourceGeneration.CliCommandGenerator/GlobalNamespaceCliCommandBuilder-1355he0.g.cs b/...ndLine.SourceGeneration.CliCommandGenerator/GlobalNamespaceCliCommandBuilder-1355he0.g.cs
@@ -1,6 +1,6 @@
 // <auto-generated />
 // Generated by DotMake.CommandLine.SourceGeneration v1.8.0.0
-// Roslyn (Microsoft.CodeAnalysis) v4.800.23.57201
+// Roslyn (Microsoft.CodeAnalysis) v4.900.24.8111
 // Generation: 1
 
 /// <inheritdoc />

diff --git a/...tMake.CommandLine.SourceGeneration.CliCommandGenerator/HelpCliCommandBuilder-5a0txz0.g.cs b/...tMake.CommandLine.SourceGeneration.CliCommandGenerator/HelpCliCommandBuilder-5a0txz0.g.cs
@@ -1,6 +1,6 @@
 // <auto-generated />
 // Generated by DotMake.CommandLine.SourceGeneration v1.8.0.0
-// Roslyn (Microsoft.CodeAnalysis) v4.800.23.57201
+// Roslyn (Microsoft.CodeAnalysis) v4.900.24.8111
 // Generation: 1
 
 namespace TestApp.Commands

diff --git a/...ommandLine.SourceGeneration.CliCommandGenerator/InheritanceCliCommandBuilder-ers9v78.g.cs b/...ommandLine.SourceGeneration.CliCommandGenerator/InheritanceCliCommandBuilder-ers9v78.g.cs
@@ -1,6 +1,6 @@
 // <auto-generated />
 // Generated by DotMake.CommandLine.SourceGeneration v1.8.0.0
-// Roslyn (Microsoft.CodeAnalysis) v4.800.23.57201
+// Roslyn (Microsoft.CodeAnalysis) v4.900.24.8111
 // Generation: 1
 
 namespace TestApp.Commands

diff --git a/....CommandLine.SourceGeneration.CliCommandGenerator/LocalizedCliCommandBuilder-c6vc5m0.g.cs b/....CommandLine.SourceGeneration.CliCommandGenerator/LocalizedCliCommandBuilder-c6vc5m0.g.cs
@@ -1,6 +1,6 @@
 // <auto-generated />
 // Generated by DotMake.CommandLine.SourceGeneration v1.8.0.0
-// Roslyn (Microsoft.CodeAnalysis) v4.800.23.57201
+// Roslyn (Microsoft.CodeAnalysis) v4.900.24.8111
 // Generation: 1
 
 namespace TestApp.Commands