Merge branch 'main' of https://github.com/JordanMarr/FSharp.SystemCommandLine

Author: JordanMarr

README.md

@@ -64,23 +64,32 @@ _Notice that mismatches between the `setAction` and the `inputs` are caught as a
 
 ## Input API
 The new `Input` module contains functions for the underlying System.CommandLine `Option` and `Argument` properties. 
+### Inputs
 * `context` passes an `ActionContext` containing a `ParseResult` and `CancellationToken` to the action
 * `argument` creates a named `Argument<'T>`
 * `argumentMaybe` creates a named `Argument<'T option>` that defaults to `None`.
 * `option` creates a named `Option<'T>`
 * `optionMaybe` creates a named `Option<'T option>` that defaults to `None`.
+
+### Input Properties
+* `acceptLegalFilePathsOnly` sets the option or argument to accept only values representing legal file paths.
 * `alias` adds an `Alias` to an `Option`
 * `aliases` adds one or more aliases to an `Option`
 * `desc` adds a description to an `Option` or `Argument`
 * `defaultValue` or `def` provides a default value to an `Option` or `Argument`
 * `defFactory` assigns a default value factor to an `Option` or `Argument`
+* `helpName` adds the name used in help output to describe the option or argument.
 * `required` marks an `Option` as required
 * `validate` allows you to return a `Result<unit, string>` for the parsed value
 * `validateFileExists` ensures that the `FileInfo` exists
 * `validateDirectoryExists` ensures that the `DirectoryInfo` exists
 * `addValidator` allows you to add a validator to the underlying `Option` or `Argument`
+* `acceptOnlyFromAmong` validates the allowed values for an `Option` or `Argument`
 * `customParser` allows you to parse the input tokens using a custom parser function.
 * `tryParse` allows you to parse the input tokens using a custom parser `Result<'T, string>` function.
+* `arity` sets the arity of an `Option` or `Argument`
+* `allowMultipleArgumentsPerToken`  allows multiple values for an `Option` or `Argument`. (Defaults to 'false' if not set.)
+* `hidden` hides an option or argument from the help output
 * `editOption` allows you to pass a function to edit the underlying `Option`
 * `editArgument` allows you to pass a function to edit the underlying `Argument`
 * `ofOption` allows you to pass a manually created `Option`
@@ -402,14 +411,14 @@ module Global =
 
     type Options = { EnableLogging: bool; LogFile: FileInfo }
 
-    let options: HandlerInput seq = [ enableLogging; logFile ] 
+    let options: ActionInput seq = [ enableLogging; logFile ]
 
     let bind (ctx: ActionContext) = 
         { EnableLogging = enableLogging.GetValue ctx.ParseResult
           LogFile = logFile.GetValue ctx.ParseResult }
 
 let listCmd =
-    let action (ctx: InvocationContext, dir: DirectoryInfo) =
+    let action (ctx: ActionContext, dir: DirectoryInfo) =
         let options = Global.bind ctx
         if options.EnableLogging then 
             printfn $"Logging enabled to {options.LogFile.FullName}"
@@ -431,7 +440,7 @@ let listCmd =
     }
 
 let deleteCmd =
-    let action (ctx: InvocationContext, dir: DirectoryInfo, recursive: bool) =
+    let action (ctx: ActionContext, dir: DirectoryInfo, recursive: bool) =
         let options = Global.bind ctx
         if options.EnableLogging then 
             printfn $"Logging enabled to {options.LogFile.FullName}"
@@ -462,7 +471,7 @@ let ioCmd =
     }
 
 [<EntryPoint>]
-let main argv =
+let main (argv: string array) =
     let cfg = 
         commandLineConfiguration {
             description "Sample app for System.CommandLine"

src/FSharp.SystemCommandLine/CommandBuilders.fs

@@ -37,6 +37,7 @@ type CommandSpec<'Inputs, 'Output> =
         SubCommands: System.CommandLine.Command list
         /// Registers extra inputs that can be parsed via the InvocationContext if more than 8 are required.
         ExtraInputs: ActionInput list
+        Hidden: bool
     }
     static member Default = 
         { 
@@ -47,6 +48,7 @@ type CommandSpec<'Inputs, 'Output> =
             ExtraInputs = []
             Handler = def<unit -> 'Output> // Support unit -> 'Output handler by default
             SubCommands = []
+            Hidden = false
         }
 
 /// Contains shared operations for building a `rootCommand`, `command` or `commandLineConfiguration` CE.
@@ -61,6 +63,7 @@ type BaseCommandBuilder<'A, 'B, 'C, 'D, 'E, 'F, 'G, 'H, 'Output>() =
             ExtraInputs = spec.ExtraInputs
             Handler = handler
             SubCommands = spec.SubCommands
+            Hidden = spec.Hidden
         }
 
     /// Converts up to 8 handler inputs into a tuple of the specified action input type.
@@ -275,6 +278,7 @@ type BaseCommandBuilder<'A, 'B, 'C, 'D, 'E, 'F, 'G, 'H, 'Output>() =
         )
         spec.SubCommands |> List.iter cmd.Add
         spec.Aliases |> List.iter cmd.Aliases.Add
+        cmd.Hidden <- spec.Hidden
         cmd
 
     /// Sets a command handler that returns `unit`.
@@ -433,6 +437,11 @@ type RootCommandBuilder<'A, 'B, 'C, 'D, 'E, 'F, 'G, 'H, 'Output>(args: string ar
 type CommandBuilder<'A, 'B, 'C, 'D, 'E, 'F, 'G, 'H, 'Output>(name: string) = 
     inherit BaseCommandBuilder<'A, 'B, 'C, 'D, 'E, 'F, 'G, 'H, 'Output>()
 
+    /// Hides the command from the help output.
+    [<CustomOperation("hidden")>]
+    member this.Hidden (spec: CommandSpec<'Inputs, 'Output>) =
+        { spec with Hidden = true }
+
     /// Returns a Command with a handler that returns unit.
     member this.Run (spec: CommandSpec<'Inputs, unit>) = 
         Command(name)

src/FSharp.SystemCommandLine/Inputs.fs

@@ -68,6 +68,12 @@ module Input =
         | _ -> ()
         input
 
+    /// Configures the option or argument to accept only values representing legal file paths.
+    let acceptLegalFilePathsOnly (input: ActionInput<'T>) =
+        input
+        |> editOption (fun o -> o.AcceptLegalFilePathsOnly() |> ignore)
+        |> editArgument (fun a -> a.AcceptLegalFilePathsOnly() |> ignore)
+
     /// Adds one or more aliases to an option.
     let aliases (aliases: string seq) (input: ActionInput<'T>) = 
         input |> editOption (fun o -> aliases |> Seq.iter o.Aliases.Add)
@@ -100,6 +106,12 @@ module Input =
         |> editOption (fun o -> o.DefaultValueFactory <- defaultValueFactory)
         |> editArgument (fun a -> a.DefaultValueFactory <- defaultValueFactory)
 
+    /// The name used in help output to describe the option or argument.
+    let helpName (helpName: string) (input: ActionInput<'T>) =
+        input
+        |> editOption (fun o -> o.HelpName <- helpName)
+        |> editArgument (fun a -> a.HelpName <- helpName)
+
     /// Marks an option as required.
     let required (input: ActionInput<'T>) = 
         input 
@@ -229,7 +241,13 @@ module Input =
     /// Sets a value that indicates whether multiple arguments are allowed for each option identifier token. (Defaults to 'false'.)
     let allowMultipleArgumentsPerToken (input: ActionInput<'T>) = 
         input 
-        |> editOption (fun a -> a.AllowMultipleArgumentsPerToken <- true)
+        |> editOption (fun o -> o.AllowMultipleArgumentsPerToken <- true)
+
+    /// Hides an option or argument from the help output.
+    let hidden (input: ActionInput<'T>) = 
+        input 
+        |> editOption (fun o -> o.Hidden <- true)
+        |> editArgument (fun a -> a.Hidden <- true)
 
     /// Converts an `Option<'T>` to an `ActionInput<'T>` for usage with the command builders.
     let ofOption (o: Option<'T>) =