diff --git a/README.md b/README.md index 12769d1..cd41d0a 100644 --- a/README.md +++ b/README.md @@ -338,6 +338,55 @@ let main argv = } ``` +## Customizing the Default Pipeline + +System.CommandLine has a `CommandLineBuilder` that allows the user to customize various behaviors. + +FSharp.SystemCommandLine is configured to use the built-in defaults (via `CommandLineBuilder().UseDefaults()`), but you can easily override them via the `usePipeline` custom operation which gives you access to the `CommandLineBuilder`. + +For example, the default behavior intercepts input strings that start with a "@" character via the "TryReplaceToken" feature. This will cause an issue if you need to accept input that starts with "@". Fortunately, you can disable this via `usePipeline`: + +```F# +module TokenReplacerExample + +open FSharp.SystemCommandLine +open System.CommandLine.Builder // Necessary when overriding the builder via usePipeline + +let app (package: string) = + if package.StartsWith("@") then + printfn $"{package}" + 0 + else + eprintfn "The package name does not start with a leading @" + 1 + +[] +let main argv = + + // The package option needs to accept strings that start with "@" symbol. + // For example, "--package @shoelace-style/shoelace". + // To accomplish this, we will need to modify the default pipeline settings below. + let package = Input.Option([ "--package"; "-p" ], "A package name that may have a leading '@' character.") + + rootCommand argv { + description "Can be called with a leading '@' package" + + usePipeline (fun builder -> + // Override default token replacer to ignore `@` processing + builder.UseTokenReplacer(fun _ _ _ -> false) + ) + + inputs package + setHandler app + } + +``` + +As you can see, there are a lot of options that can be configured here (note that you need to `open System.CommandLine.Builder`): + +![image](https://user-images.githubusercontent.com/1030435/199282781-1800b79c-7638-4242-8ca0-777d7237e20a.png) + + ## Defining Inputs Manually While the `Input.Argument` and `Input.Option` helper methods are useful for most common scenarios, sometimes it may be necessary to manually define inputs using the underlying `System.CommandLine` base library. This will make it easier to investigate the various overloads and take advantage of other features like custom validation.