Skip to content

Commit 3ce158f

Browse files
authored
Added Inputs API and extensibility examples to README
1 parent 2357fa5 commit 3ce158f

File tree

1 file changed

+57
-3
lines changed

1 file changed

+57
-3
lines changed

README.md

Lines changed: 57 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,9 +13,7 @@ _[Click here to view the old beta 4 README](README-beta4.md)_
1313
* `Input.context` helper allows you to pass the `ActionContext` to your action function which is necessary for some operations.
1414
* `Input.validate` helper allows you to validate against parsed value using the F# `Result` type.
1515

16-
## Examples
17-
18-
### Simple App
16+
## Example
1917

2018
```F#
2119
open System.IO
@@ -62,6 +60,62 @@ let main argv =
6260
_Notice that mismatches between the `setAction` and the `inputs` are caught as a compile time error:_
6361
![fs scl demo](https://user-images.githubusercontent.com/1030435/164288239-e0ff595d-cdb2-47f8-9381-50c89aedd481.gif)
6462

63+
## Input API
64+
The new `Input` module contains functions for the underlying System.CommandLine `Option` and `Argument` properties.
65+
* `context` passes an `ActionContext` containing a `ParseResult` and `CancellationToken` to the action
66+
* `argument` creates a named `Argument<'T>`
67+
* `argumentMaybe` creates a named `Argument<'T option>` that defaults to `None`.
68+
* `option` creates a named `Option<'T>`
69+
* `optionMaybe` creates a named `Option<'T option>` that defaults to `None`.
70+
* `alias` adds an `Alias` to an `Option`
71+
* `aliases` adds one or more aliases to an `Option`
72+
* `desc` adds a description to an `Option` or `Argument`
73+
* `defaultValue` or `def` provides a default value to an `Option` or `Argument`
74+
* `defFactor` assigns a default value factor to an `Option` or `Argument`
75+
* `required` marks an `Option` as required
76+
* `validate` allows you to return a `Result<unit, string>` for the parsed value
77+
* `addValidator` allows you to add a validator to the underlying `Option` or `Argument`
78+
* `editOption` allows you to pass a function to edit the underlying `Option`
79+
* `editArgument` allows you to pass a function to edit the underlying `Argument`
80+
* `ofOption` allows you to pass a manually created `Option`
81+
* `ofArgument` allows you to pass a manually created `Argument`
82+
83+
### Extensibility
84+
You can easily compose your own custom `Input` functions with `editOption` and `editArgument`.
85+
For example, this is how the existing `alias` and `desc` functions were created:
86+
87+
```fsharp
88+
let alias (alias: string) (input: ActionInput<'T>) =
89+
input
90+
|> editOption (fun o -> o.Aliases.Add alias)
91+
92+
let desc (description: string) (input: ActionInput<'T>) =
93+
input
94+
|> editOption (fun o -> o.Description <- description)
95+
|> editArgument (fun a -> a.Description <- description)
96+
```
97+
* _Since `alias` can only apply to `Option`, it only calls `editOption`_
98+
* _Since `desc` can apply to both `Option` and `Argument`, you need to use both_
99+
100+
You could just as easily create a custom `Input.validateFileExists` function:
101+
```fsharp
102+
let validateFileExists (input: ActionInput<'T>) =
103+
input
104+
|> validate (fun file ->
105+
if file.Exists then Ok ()
106+
else Error $"File '{file.FullName}' does not exist."
107+
)
108+
```
109+
110+
And then use it like this:
111+
```fsharp
112+
let zipFile =
113+
argument "zipfile"
114+
|> desc "The file to unzip"
115+
|> validateFileExists
116+
```
117+
118+
## More Examples
65119

66120
### Simple App that Returns a Status Code
67121

0 commit comments

Comments
 (0)