Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/unstoppablemango/cliwrap.fsharp
Idiomatic F# support for CliWrap
https://github.com/unstoppablemango/cliwrap.fsharp
Last synced: 1 day ago
JSON representation
Idiomatic F# support for CliWrap
- Host: GitHub
- URL: https://github.com/unstoppablemango/cliwrap.fsharp
- Owner: UnstoppableMango
- License: mit
- Created: 2024-01-12T23:24:50.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2024-10-29T13:11:41.000Z (about 2 months ago)
- Last Synced: 2024-10-29T15:57:34.636Z (about 2 months ago)
- Language: F#
- Size: 132 KB
- Stars: 7
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# CliWrap.FSharp
[](https://github.com/UnstoppableMango/CliWrap.FSharp/actions)
[](https://app.codecov.io/gh/UnstoppableMango/CliWrap.FSharp)
[](https://github.com/UnstoppableMango/CliWrap.FSharp/releases)
[](https://nuget.org/packages/UnMango.CliWrap.FSharp)
[](https://nuget.org/packages/UnMango.CliWrap.FSharp)
Idiomatic F# support for [CliWrap](https://github.com/Tyrrrz/CliWrap).
## Install
- [NuGet](https://nuget.org/packages/UnMango.CliWrap.FSharp): `dotnet add package UnMango.CliWrap.FSharp`
- [GitHub Packages](): `dotnet add package UnMango.CliWrap.FSharp -s github`
- [Authenticating to GitHub Packages](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-nuget-registry#authenticating-to-github-packages)
- [Installing from GitHub Packages](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-nuget-registry#installing-a-package)
## Usage
Bindings for normal CliWrap commands are available in the `Cli` module.
```fsharp
let main args = async {
let! result =
Cli.wrap "dotnet"
|> Cli.args [ "build" ]
|> Cli.workDir "~/src/CliWrap.FSharp"
|> Cli.exec
result.ExitCode
}
```
Cancellation token overloads are available in `Cli.Tasks`.
```fsharp
let main args = task {
use cts = new CancellationTokenSource()
let! result =
Cli.wrap "dotnet"
|> Cli.args [ "build" ]
|> Cli.workDir "~/src/CliWrap.FSharp"
|> Cli.Task.exec cts.Token
result.ExitCode
}
```
```fsharp
let main args = task {
use graceful = new CancellationTokenSource()
use forceful = new CancellationTokenSource()
let! result =
Cli.wrap "dotnet"
|> Cli.args [ "build" ]
|> Cli.workDir "~/src/CliWrap.FSharp"
|> Cli.Task.execf forceful.Token graceful.Token
result.ExitCode
}
```
The core of the package is a simple computation expression that wraps `CliWrap.Command`.
It attempts to mimic the builder pattern and `.With*` style methods.
```fsharp
let main args =
let cmd = command "dotnet" {
args = [ "build" ]
workingDirectory = "~/src/CliWrap.FSharp"
}
cmd.ExecuteAsync()
```
The computation expression also supports executing the command with `exec`.
```fsharp
let main args = task {
let! result = command "dotnet" {
args = [ "build" ]
workingDirectory = "~/src/CliWrap.FSharp"
exec
}
result.ExitCode
}
```
Cancellation is also supported.
```fsharp
let main args = task {
use cts = new CancellationTokenSource()
let! result = command "dotnet" {
args = [ "build" ]
workingDirectory = "~/src/CliWrap.FSharp"
exec cts.Token
}
result.ExitCode
}
```
CliWrap's buffered execution is supported with `buffered`.
```fsharp
let main args = task {
use cts = new CancellationTokenSource()
let! result = command "dotnet" {
args = [ "build" ]
workingDirectory = "~/src/CliWrap.FSharp"
buffered Encoding.UTF8 cts.Token
}
result.ExitCode
}
```
Asynchrony with F#'s `Async<'T>` is supported with `async`.
```fsharp
let main args = async {
use cts = new CancellationTokenSource()
let! result = command "dotnet" {
args = [ "build" ]
workingDirectory = "~/src/CliWrap.FSharp"
async cts.Token
}
result.ExitCode
}
```
CliWrap's piping functionality is supported via the `pipeline` computation expression.
```fsharp
let main args =
let cmd = pipeline {
"an inline string source"
Cli.wrap "echo"
}
cmd.ExecuteAsync()
```
Limited support for piping is available with `|>>`.
```fsharp
let main args =
let cmd = Cli.wrap "yes" |>> Cli.wrap "echo"
cmd.ExecuteAsync()
```
## Inspirations
The idea to abuse F# computation expressions was inspired by [Akkling.Hocon](https://github.com/Horusiath/Akkling/tree/master/src/Akkling.Hocon) and [FsHttp](https://github.com/fsprojects/FsHttp).
Obviously CliWrap was a big inspiration for this package.
## Q/A
### Idiomatic? This looks nothing like the F# I write!
If something looks off please open an issue! I've only recently been diving further into the F# ecosystem.
### Why not paket?
If renovate ever [supports it](https://github.com/renovatebot/renovate/issues/11211)!