expose Argu metadata to public API

Author: eiriktsarpalis

src/Argu/ArgumentParser.fs

@@ -10,7 +10,7 @@ open FSharp.Reflection
 /// The Argu type generates an argument parser given a type argument
 /// that is an F# discriminated union. It can then be used to parse command line arguments
 /// or XML configuration.
-[<NoEquality; NoComparison; Sealed; AutoSerializable(false)>]
+[<NoEquality; NoComparison; AutoSerializable(false)>]
 type ArgumentParser<'Template when 'Template :> IArgParserTemplate> private (argInfo : UnionArgInfo, ?programName : string, ?description : string, ?errorHandler : IExiter) =
     // memoize parser generation for given template type
     static let argInfoLazy = lazy(preComputeUnionArgInfo<'Template> ())
@@ -39,11 +39,16 @@ type ArgumentParser<'Template when 'Template :> IArgParserTemplate> private (arg
         new ArgumentParser<'Template>(argInfoLazy.Value, ?programName = programName, 
                                         ?description = description, ?errorHandler = errorHandler)
 
-
-    /// Returns true if top-level parser
-    /// and false if parser defined for a subcommand
-    member __.IsTopLevelParser = argInfo.TryGetParent() |> Option.isNone
-
+    /// Gets the help flags specified for the CLI parser
+    member __.HelpFlags = argInfo.HelpParam.Flags
+    /// Gets the help description specified for the CLI parser
+    member __.HelpDescription = argInfo.HelpParam.Description
+    /// Gets metadata for all union cases used by parser
+    member __.GetArgumentCases() = argInfo.Cases |> Array.map (fun p -> p.ToArgumentCaseInfo())
+    /// Returns true if parser corresponds to a subcommand
+    member __.IsSubCommandParser = argInfo.TryGetParent() |> Option.isSome
+    /// If subcommand parsers, gets parent argument metadata
+    member __.ParentInfo = argInfo.TryGetParent() |> Option.map (fun p -> p.ToArgumentCaseInfo())
     /// Gets the default error handler used by the instance
     member __.ErrorHandler = errorHandler
 
@@ -150,16 +155,24 @@ type ArgumentParser<'Template when 'Template :> IArgParserTemplate> private (arg
     ///     Gets the F# union tag representation for given argument
     /// </summary>
     /// <param name="value">Argument instance.</param>
-    member __.GetTag(value : 'Template) : UnionCaseInfo =
+    member __.GetTag(value : 'Template) : int = 
+        argInfo.TagReader.Value (value :> obj)
+
+    /// <summary>
+    ///     Gets argument metadata for given argument instance.
+    /// </summary>
+    /// <param name="value">Argument instance.</param>
+    member __.GetArgumentCaseInfo(value : 'Template) : ArgumentCaseInfo =
         let tag = argInfo.TagReader.Value (value :> obj)
-        argInfo.Cases.[tag].UnionCaseInfo
+        argInfo.Cases.[tag].ToArgumentCaseInfo()
 
     /// <summary>
-    ///     Gets the F# union tag representation for given union case constructor
+    ///     Gets argument metadata for given union case constructor
     /// </summary>
     /// <param name="ctorExpr">Quoted union case constructor.</param>
-    member __.GetTag(ctorExpr : Expr<'Fields -> 'Template>) : UnionCaseInfo =
-        expr2Uci ctorExpr
+    member __.GetArgumentCaseInfo(ctorExpr : Expr<'Fields -> 'Template>) : ArgumentCaseInfo =
+        let uci = expr2Uci ctorExpr
+        argInfo.Cases.[uci.Tag].ToArgumentCaseInfo()
 
     /// <summary>
     ///     Prints command line syntax. Useful for generating documentation.
@@ -212,5 +225,5 @@ module ArgumentParserUtils =
         ArgumentParser.Create<'Template>().ToParseResult(inputs)
 
     /// gets the F# union tag representation of given argument instance
-    let tagOf (input : 'Template) : UnionCaseInfo =
+    let tagOf (input : 'Template) : int =
         ArgumentParser.Create<'Template>().GetTag input

src/Argu/PreCompute.fs

@@ -273,7 +273,7 @@ let rec private preComputeUnionCaseArgInfo (stack : Type list) (helpParam : Help
         AppSettingsName = appSettingsName
         AppSettingsSeparators = appSettingsSeparators
         AppSettingsSplitOptions = appSettingsSplitOptions
-        Usage = usageString
+        Description = usageString
         FieldParsers = parsers
         AppSettingsCSV = isAppSettingsCSV
         IsMandatory = isMandatory

src/Argu/Types.fs

@@ -1,6 +1,7 @@
 namespace Argu
 
 open System
+open FSharp.Reflection
 
 // Attribute declarations
 
@@ -82,13 +83,13 @@ module ArguAttributes =
         inherit Attribute ()
         member __.Names = names
 
-    /// Sets a custom AppSettings key name.
+    /// Sets a custom Configuration parsing key name.
     [<AttributeUsage(AttributeTargets.Property, AllowMultiple = false)>]
     type CustomAppSettingsAttribute (name : string) =
         inherit Attribute ()
         member __.Name = name
 
-    /// Specify a custom value separator in AppSettings parameters
+    /// Specify a custom value separator in Configuration parsing parameters
     [<AttributeUsage(AttributeTargets.Class ||| AttributeTargets.Property, AllowMultiple = false)>]
     type AppSettingsSeparatorAttribute ([<ParamArray>] separators : string [], splitOptions : StringSplitOptions) =
         inherit Attribute()
@@ -113,6 +114,7 @@ module CliPrefix =
     let [<Literal>] DoubleDash = "--"
 
 /// Source from which to parse arguments
+[<Flags>]
 type ParseSource = 
     | None          = 0
     | AppSettings   = 1
@@ -167,4 +169,59 @@ type IConfigurationReader =
     /// Configuration reader identifier
     abstract Name : string
     /// Gets value corresponding to supplied key
-    abstract GetValue : key:string -> string
+    abstract GetValue : key:string -> string
+
+/// Argument parameter type identifier
+type ArgumentType =
+    /// Argument specifies primitive parameters like strings or integers
+    | Primitive  = 1
+    /// Argument specifies an optional parameter which is primitive
+    | Optional   = 2
+    /// Argument specifies a list of parameters of specific primitive type
+    | List       = 3
+    /// Argument specifies a subcommand
+    | SubCommand = 4
+
+/// Union argument metadata
+[<NoEquality; NoComparison>]
+type ArgumentCaseInfo =
+    {
+        /// Human readable name identifier
+        Name : string
+        /// Union case reflection identifier
+        UnionCaseInfo : UnionCaseInfo
+        /// Type of argument parser
+        ArgumentType : ArgumentType
+
+        /// head element denotes primary command line arg
+        CommandLineNames : string list
+        /// name used in AppSettings
+        AppSettingsName : string option
+
+        /// Description of the parameter
+        Description : string
+
+        /// AppSettings parameter separator
+        AppSettingsSeparators : string []
+        /// AppSettings parameter split options
+        AppSettingsSplitOptions : StringSplitOptions
+
+        /// If specified, should consume remaining tokens from the CLI
+        IsRest : bool
+        /// If specified, parameter can only be at start of CLI parameters
+        IsFirst : bool
+        /// If specified, use '--param=arg' CLI parsing syntax
+        IsEquals1Assignment : bool
+        /// If specified, use '--param key=value' CLI parsing syntax
+        IsEquals2Assignment : bool
+        /// If specified, multiple parameters can be added in AppSettings in CSV form.
+        AppSettingsCSV : bool
+        /// Fails if no argument of this type is specified
+        IsMandatory : bool
+        /// Specifies that argument should be specified at most once in CLI
+        IsUnique : bool
+        /// Hide from Usage
+        IsHidden : bool
+        /// Combine AppSettings with CLI inputs
+        GatherAllSources : bool
+    }

src/Argu/UnParsers.fs

@@ -21,7 +21,7 @@ let printCommandLineSyntax (argInfo : UnionArgInfo) (programName : string) = str
     let sorted = 
         argInfo.Cases
         |> Seq.filter (fun aI -> not aI.IsHidden)
-        |> Seq.sortBy (fun aI -> not aI.IsFirst, aI.IsRest || aI.IsNested, aI.Tag)
+        |> Seq.sortBy (fun aI -> not aI.IsFirst, aI.IsRest || aI.Type = ArgumentType.SubCommand, aI.Tag)
         |> Seq.toArray
 
     for aI in sorted do
@@ -110,7 +110,7 @@ let printArgUsage (aI : UnionCaseArgInfo) = stringExpr {
             yield " <options>"
 
         yield ": "
-        yield aI.Usage
+        yield aI.Description
         yield Environment.NewLine
 }
 
@@ -155,7 +155,7 @@ let printUsage (argInfo : UnionArgInfo) programName (description : string option
     let options, subcommands =
         argInfo.Cases
         |> Seq.filter (fun aI -> not aI.IsHidden)
-        |> Seq.partition (fun aI -> not aI.IsNested)
+        |> Seq.partition (fun aI -> aI.Type <> ArgumentType.SubCommand)
 
     if options.Length > 0 || argInfo.UsesHelpParam then
         yield Environment.NewLine; yield Environment.NewLine
@@ -273,7 +273,7 @@ let printAppSettings (argInfo : UnionArgInfo) printComments (args : 'Template li
                 let mkComment () =
                     stringExpr {
                         yield ' '
-                        yield aI.Usage
+                        yield aI.Description
 
                         match parsers |> Array.toList with
                         | [] -> ()
@@ -298,7 +298,7 @@ let printAppSettings (argInfo : UnionArgInfo) printComments (args : 'Template li
                             |> Seq.map (fun t -> fp.UnParser (t :> _))
                             |> String.concat aI.AppSettingsSeparators.[0]
 
-                        let mkComment () = sprintf " %s : %s ..." aI.Usage fp.Description
+                        let mkComment () = sprintf " %s : %s ..." aI.Description fp.Description
 
                         mkElem mkComment key values }
 
@@ -310,7 +310,7 @@ let printAppSettings (argInfo : UnionArgInfo) printComments (args : 'Template li
                             | None -> ""
                             | Some t -> fp.UnParser (t :> _)
 
-                        let mkComment () = sprintf " %s : ?%s" aI.Usage fp.Description
+                        let mkComment () = sprintf " %s : ?%s" aI.Description fp.Description
 
                         mkElem mkComment key value }
 

src/Argu/UnionArgInfo.fs

@@ -75,11 +75,11 @@ type UnionCaseArgInfo =
         AppSettingsName : string option
 
         /// Description of the parameter
-        Usage : string
+        Description : string
 
-        /// AppSettings parameter separator
+        /// Configuration parsing parameter separator
         AppSettingsSeparators : string []
-        /// AppSettings parameter split options
+        /// Configuration parsing split options
         AppSettingsSplitOptions : StringSplitOptions
 
         /// If specified, should consume remaining tokens from the CLI
@@ -90,7 +90,7 @@ type UnionCaseArgInfo =
         IsEquals1Assignment : bool
         /// If specified, use '--param key=value' CLI parsing syntax
         IsEquals2Assignment : bool
-        /// If specified, multiple parameters can be added in AppSettings in CSV form.
+        /// If specified, multiple parameters can be added in Configuration in CSV form.
         AppSettingsCSV : bool
         /// Fails if no argument of this type is specified
         IsMandatory : bool
@@ -104,8 +104,12 @@ type UnionCaseArgInfo =
 with
     member inline __.Tag = __.UnionCaseInfo.Tag
     member inline __.NoCommandLine = __.CommandLineNames.Length = 0
-    member inline __.IsNested = match __.FieldParsers with NestedUnion _ -> true | _ -> false
-    member inline __.IsOptional = match __.FieldParsers with OptionalParam _ -> true | _ -> false
+    member inline __.Type =
+        match __.FieldParsers with
+        | Primitives _ -> ArgumentType.Primitive
+        | OptionalParam _ -> ArgumentType.Optional
+        | ListParam _ -> ArgumentType.List
+        | NestedUnion _ -> ArgumentType.SubCommand
 
 and ParameterType =
     | Primitives of FieldParserInfo []
@@ -167,4 +171,27 @@ type UnionParseResults =
         UnrecognizedCliParams : string list
         /// Usage string requested by the caller
         IsUsageRequested : bool
-    }
+    }
+
+
+type UnionCaseArgInfo with
+    member ucai.ToArgumentCaseInfo() : ArgumentCaseInfo =
+        {
+            Name = ucai.Name
+            ArgumentType = ucai.Type
+            UnionCaseInfo = ucai.UnionCaseInfo
+            CommandLineNames = ucai.CommandLineNames
+            AppSettingsName = ucai.AppSettingsName
+            Description = ucai.Description
+            AppSettingsSeparators = ucai.AppSettingsSeparators
+            AppSettingsSplitOptions = ucai.AppSettingsSplitOptions
+            IsRest = ucai.IsRest
+            IsFirst = ucai.IsFirst
+            IsEquals1Assignment = ucai.IsEquals1Assignment
+            IsEquals2Assignment = ucai.IsEquals2Assignment
+            AppSettingsCSV = ucai.AppSettingsCSV
+            IsMandatory = ucai.IsMandatory
+            IsUnique = ucai.IsUnique
+            IsHidden = ucai.IsHidden
+            GatherAllSources = ucai.GatherAllSources
+        }

tests/Argu.Tests/Tests.fs

@@ -93,7 +93,7 @@ module ``Argu Tests`` =
 
     [<Fact>]
     let ``Simple AppSettings parsing`` () =
-        let args = [ Mandatory_Arg true ; Detach ; Listener ("localhost", 8080) ; Log_Level 2 ] |> List.sortBy (fun u -> tagOf(u).Tag)
+        let args = [ Mandatory_Arg true ; Detach ; Listener ("localhost", 8080) ; Log_Level 2 ] |> List.sortBy tagOf
         let xmlSource = parser.PrintAppSettings args
         let xmlFile = Path.GetTempFileName()
         do File.WriteAllText(xmlFile, xmlSource)