Introduction

Argu (pronounced "Argue") is a declarative CLI argument parser for F# console applications. It allows modelling the command-line syntax using discriminated unions, which the library converts into a working parser using reflection.

Argu is a mature library that comes with many features

Declarative: easily model your syntax definitions using F# unions.
Convenient: automatic derivation of CLI syntax and documentation.
Customizable: control most aspects of your parser behaviour.
Subcommands: use contextual syntax with nested argument schemata.

It can be installed using NuGet.

Basic Concepts

The library is based on the simple observation that configuration parameters can be naturally described using discriminated unions. For instance:

type Arguments =
    | Working_Directory of path: string
    | Listener of host: string * port: int
    | Log_Level of level: int
    | Detach

Argu takes such discriminated unions and generates a corresponding argument parsing scheme. For example, a parser generated from the above template would take the following command line input

--working-directory /var/run --listener localhost 8080 --detach

and parse it into the list

[ Working_Directory "/var/run"; Listener("localhost", 8080); Detach ]

Argu is also capable of reading the AppSettings section of an application's configuration file:

<appSettings>
    <add key="working directory" value="C:\temp" />
    <add key="listener" value="192.168.0.3, 2675" />
    <add key="log level" value="3" />
    <add key="detach" value="true" />
</appSettings>

Furthermore, you can parse environment variables, by supplying the an EnvironmentVariableReader to the Parse call:

let argv = [| "--log-level"; "3" |]
let reader = EnvironmentVariableConfigurationReader() :> IConfigurationReader
let parser = ArgumentParser.Create<Args>(programName = "rutta")
// pass the reader to the Parse call
let results = parser.Parse(argv, configurationReader = reader)

Who uses Argu?

Documentation

Tutorial A short walkthrough of Argu features.
API Reference contains automatically generated documentation for all types, modules and functions in the library.

Contributing and copyright

The project is hosted on GitHub where you can report issues, fork the project and submit pull requests.

The library is available under the MIT License. For more information see the License file in the GitHub repository.

namespace Argu

Multiple items
val string: value: 'T -> string

--------------------
type string = System.String

Multiple items
val int: value: 'T -> int (requires member op_Explicit)

--------------------
type int = int32

--------------------
type int<'Measure> = int

type IArgParserTemplate = abstract Usage: string
<summary> Interface that must be implemented by all Argu template types </summary>

type Arguments = | Working_Directory of path: string | Listener of host: string * port: int | Log_Level of level: int | Detach

union case Args.Working_Directory: path: string -> Args

union case Args.Listener: host: string * port: int -> Args

union case Args.Log_Level: level: int -> Args

union case Args.Detach: Args

val argv: string array

val reader: IConfigurationReader

Multiple items
type EnvironmentVariableConfigurationReader = interface IConfigurationReader new: unit -> EnvironmentVariableConfigurationReader
<summary> Environment variable-based configuration reader </summary>

--------------------
new: unit -> EnvironmentVariableConfigurationReader

type IConfigurationReader = abstract GetValue: key: string -> string abstract Name: string
<summary> Abstract key/value configuration reader </summary>

val parser: ArgumentParser<Args>

Multiple items
type ArgumentParser = abstract Accept: visitor: IArgumentParserVisitor<'R> -> 'R member GetArgumentCases: unit -> ArgumentCaseInfo list member GetSubCommandParsers: unit -> ArgumentParser list member PrintCommandLineSyntax: ?programName: string * ?usageStringCharacterWidth: int -> string member PrintUsage: ?message: string * ?programName: string * ?hideSyntax: bool * ?usageStringCharacterWidth: int -> string static member Create: ?programName: string * ?helpTextMessage: string * ?usageStringCharacterWidth: int * ?errorHandler: IExiter * ?checkStructure: bool -> ArgumentParser<#IArgParserTemplate> member ErrorHandler: IExiter member HelpDescription: string member HelpFlags: string list member HelpTextMessage: string option ...
<summary> 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. </summary>

--------------------
type ArgumentParser<'Template (requires 'Template :> IArgParserTemplate)> = inherit ArgumentParser new: ?programName: string * ?helpTextMessage: string * ?usageStringCharacterWidth: int * ?errorHandler: IExiter * ?checkStructure: bool -> ArgumentParser<'Template> override Accept: visitor: IArgumentParserVisitor<'a1> -> 'a1 member GetArgumentCaseInfo: value: 'Template -> ArgumentCaseInfo + 1 overload member GetSubCommandParser: [<ReflectedDefinition>] expr: Expr<(ParseResults<'SubTemplate> -> 'Template)> -> ArgumentParser<'SubTemplate> (requires 'SubTemplate :> IArgParserTemplate) member GetTag: value: 'Template -> int member Parse: ?inputs: string array * ?configurationReader: IConfigurationReader * ?ignoreMissing: bool * ?ignoreUnrecognized: bool * ?raiseOnUsage: bool -> ParseResults<'Template> member ParseCommandLine: ?inputs: string array * ?ignoreMissing: bool * ?ignoreUnrecognized: bool * ?raiseOnUsage: bool -> ParseResults<'Template> member ParseConfiguration: configurationReader: IConfigurationReader * ?ignoreMissing: bool -> ParseResults<'Template> member PrintAppSettingsArguments: args: 'Template list * ?printComments: bool -> string ...
<summary> 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. </summary>

--------------------
new: ?programName: string * ?helpTextMessage: string * ?usageStringCharacterWidth: int * ?errorHandler: IExiter * ?checkStructure: bool -> ArgumentParser<'Template>

static member ArgumentParser.Create: ?programName: string * ?helpTextMessage: string * ?usageStringCharacterWidth: int * ?errorHandler: IExiter * ?checkStructure: bool -> ArgumentParser<#IArgParserTemplate>

type Args = | Working_Directory of path: string | Listener of host: string * port: int | Log_Level of level: int | Detach interface IArgParserTemplate

val results: ParseResults<Args>

member ArgumentParser.Parse: ?inputs: string array * ?configurationReader: IConfigurationReader * ?ignoreMissing: bool * ?ignoreUnrecognized: bool * ?raiseOnUsage: bool -> ParseResults<'Template>