Scripts - Axial

Repository F# setup

open System
open System.IO
open System.Threading
open System.Threading.Tasks
open Axial
open Axial.Console
open Axial.FileSystem
open Axial.PlatformService
open Axial.Process

Open Axial.Process.DSL for command-line-shaped authoring:

Show page setup

// Setup for the checked examples on this page.
open System
open Axial
open Axial.Console
open Axial.FileSystem
open Axial.PlatformService
open Axial.Process
open Axial.Process.DSL
/// Fails the docs test when an example's result differs from the value shown.
let shouldEqual expected actual =
    if actual <> expected then failwithf "Expected %A but got %A" expected actual

Verified

open Axial.Process.DSL

let connect (deviceId: string) (workspace: string) =
    cmd $"printf %%s {deviceId}"
    |> cwd workspace
    |> env "DEVICE_MODE" "service"
    |> timeout (TimeSpan.FromSeconds 30.0)

Axial

Process

Axial.Process.DSL

connect: string -> string -> ProcessCommand

deviceId: string

string

An abbreviation for the CLI type . Basic Types

workspace: string

cmd: FormattableString -> ProcessCommand

(|>): 'T1 -> ('T1 -> 'U) -> 'U

Apply a function to a value, the value being on the left, the function on the right The argument. The function. The function result. let doubleIt x = x * 2 3 |> doubleIt // Evaluates to 6

cwd: string -> ProcessCommand -> ProcessCommand

env: string -> string -> ProcessCommand -> ProcessCommand

timeout: TimeSpan -> ProcessCommand -> ProcessCommand

System.TimeSpan

Represents a time interval.

FromSeconds: float -> TimeSpan

Returns a that represents a specified number of seconds, where the specification is accurate to the nearest millisecond. A number of seconds, accurate to the nearest millisecond. An object that represents . is less than or greater than . -or- is . -or- is . is equal to .

Requires & types

Requires: open Axial.Process.DSL; open System (packages: Axial.Process)

val connect: string -> string -> ProcessCommand

Verified

connect "sensor 7; date" (IO.Path.GetTempPath())
|> Process.run
|> _.StdOut
|> shouldEqual "sensor 7; date"

connect: string -> string -> ProcessCommand

IO

GetTempPath: unit -> string

Returns the path of the current user's temporary folder. The path to the temporary folder, ending with a backslash. The caller does not have the required permissions.

System.IO.Path

Performs operations on instances that contain file or directory path information. These operations are performed in a cross-platform manner.

(|>): 'T1 -> ('T1 -> 'U) -> 'U

Apply a function to a value, the value being on the left, the function on the right The argument. The function. The function result. let doubleIt x = x * 2 3 |> doubleIt // Evaluates to 6

Axial.Process.Process

run: ^source -> ^result

Runs with live services and returns the value; raises ProcessRunException on failure.

_arg1: ProcessResult

StdOut: string

shouldEqual: 'a -> 'a -> unit

Requires & types

Requires: open Axial.Process (packages: Axial.Process)

Interpolation holes remain individual native arguments. Here ; date is returned as text; it does not start another command. No shell parses the value. Mark sensitive values explicitly:

Verified

let authenticate (token: string) =
    cmd $"printf %%s {secret token}"

authenticate: string -> ProcessCommand

token: string

string

An abbreviation for the CLI type . Basic Types

cmd: FormattableString -> ProcessCommand

Requires & types

Requires: open Axial.Process.DSL (packages: Axial.Process)

val authenticate: string -> ProcessCommand

Verified

authenticate "s3cret" |> Process.render |> shouldEqual "printf \"%s\" ***"
authenticate "s3cret" |> Process.run |> _.StdOut |> shouldEqual "s3cret"

authenticate: string -> ProcessCommand

(|>): 'T1 -> ('T1 -> 'U) -> 'U

Apply a function to a value, the value being on the left, the function on the right The argument. The function. The function result. let doubleIt x = x * 2 3 |> doubleIt // Evaluates to 6

Axial.Process.Process

render: ^a -> string

shouldEqual: 'a -> 'a -> unit

run: ^source -> ^result

Runs with live services and returns the value; raises ProcessRunException on failure.

_arg1: ProcessResult

StdOut: string

Requires & types

Requires: open Axial.Process (packages: Axial.Process)

The real value reaches the process; renders, plans, and errors show ***.

Use bash, sh, or pwsh when shell syntax is required. Interpolated values are passed out of band as positional arguments:

Verified

let shout (value: string) =
    bash $"printf '%%s' {value} | tr '[:lower:]' '[:upper:]'"

shout: string -> ProcessCommand

value: string

string

An abbreviation for the CLI type . Basic Types

bash: FormattableString -> ProcessCommand

Builds a Bash program with interpolation values passed as positional arguments.

Requires & types

Requires: open Axial.Process.DSL (packages: Axial.Process)

val shout: string -> ProcessCommand

Verified

shout "it's $HOME" |> Process.run |> _.StdOut |> shouldEqual "IT'S $HOME"

shout: string -> ProcessCommand

(|>): 'T1 -> ('T1 -> 'U) -> 'U

Apply a function to a value, the value being on the left, the function on the right The argument. The function. The function result. let doubleIt x = x * 2 3 |> doubleIt // Evaluates to 6

Axial.Process.Process

run: ^source -> ^result

Runs with live services and returns the value; raises ProcessRunException on failure.

_arg1: ProcessResult

StdOut: string

shouldEqual: 'a -> 'a -> unit

Requires & types

Requires: open Axial.Process (packages: Axial.Process)

toFlow and the stream constructors are lazy. Capture helpers configure retention without executing; routing helpers choose destinations independently. Process.run starts a command, spec, or Flow and returns its value. A direct command captures stdout for the caller:

Verified

cmd $"printf hello" |> Process.run |> _.StdOut |> shouldEqual "hello"

cmd: FormattableString -> ProcessCommand

(|>): 'T1 -> ('T1 -> 'U) -> 'U

Apply a function to a value, the value being on the left, the function on the right The argument. The function. The function result. let doubleIt x = x * 2 3 |> doubleIt // Evaluates to 6

Axial.Process.Process

run: ^source -> ^result

Runs with live services and returns the value; raises ProcessRunException on failure.

_arg1: ProcessResult

StdOut: string

shouldEqual: 'a -> 'a -> unit

Requires & types

Requires: open Axial.Process; open Axial.Process.DSL (packages: Axial.Process)

Process.run raises ProcessRunException on failure. A successful command exposes its exit code:

Verified

cmd $"true" |> Process.run |> _.ExitCode |> shouldEqual 0

cmd: FormattableString -> ProcessCommand

(|>): 'T1 -> ('T1 -> 'U) -> 'U

Apply a function to a value, the value being on the left, the function on the right The argument. The function. The function result. let doubleIt x = x * 2 3 |> doubleIt // Evaluates to 6

Axial.Process.Process

run: ^source -> ^result

Runs with live services and returns the value; raises ProcessRunException on failure.

_arg1: ProcessResult

ExitCode: int

shouldEqual: 'a -> 'a -> unit

Requires & types

Requires: open Axial.Process; open Axial.Process.DSL (packages: Axial.Process)

Compose longer scripts inside flow { } and run them once. toFlow makes each command a lazy step:

Verified

let script : Flow<ProcessHostEnvironment, ProcessError, string> =
    flow {
        let! first = cmd $"printf first" |> toFlow
        let! second = cmd $"printf second" |> toFlow
        return first.StdOut + second.StdOut
    }

script: Flow<ProcessHostEnvironment,ProcessError,string>

Axial.Flow`3

Axial.Process.ProcessHostEnvironment

Axial.Process.ProcessError

Expected process errors. Runtime cancellation remains Cause.Interrupt.

string

An abbreviation for the CLI type . Basic Types

flow: FlowBuilder

The universal flow { } computation expression.

first: ProcessResult

cmd: FormattableString -> ProcessCommand

(|>): 'T1 -> ('T1 -> 'U) -> 'U

Apply a function to a value, the value being on the left, the function on the right The argument. The function. The function result. let doubleIt x = x * 2 3 |> doubleIt // Evaluates to 6

toFlow: ^a -> Flow<'b,ProcessError,ProcessResult>

second: ProcessResult

StdOut: string

(+): ^T1 -> ^T2 -> ^T3

Overloaded addition operator The first parameter. The second parameter. The result of the operation. 2 + 2 // Evaluates to 4 "Hello " + "World" // Evaluates to "Hello World"

Requires & types

Requires: open Axial; open Axial.Process; open Axial.Process.DSL (packages: Axial, Axial.Process)

val script: Flow<ProcessHostEnvironment,ProcessError,string>

Verified

script |> Process.run |> shouldEqual "firstsecond"

script: Flow<ProcessHostEnvironment,ProcessError,string>

(|>): 'T1 -> ('T1 -> 'U) -> 'U

Apply a function to a value, the value being on the left, the function on the right The argument. The function. The function result. let doubleIt x = x * 2 3 |> doubleIt // Evaluates to 6

Axial.Process.Process

run: ^source -> ^result

Runs with live services and returns the value; raises ProcessRunException on failure.

shouldEqual: 'a -> 'a -> unit

Requires & types

Requires: open Axial.Process (packages: Axial.Process)

If a script needs to inspect a process failure rather than raise, Process.tryRun returns Exit. An entry point can distinguish a failed stage from a startup error:

Verified

match shText "exit 3" |> Process.tryRun with
| Exit.Failure(Cause.Fail(ProcessError.StageFailed failure)) ->
    shouldEqual 3 failure.Stage.ExitCode
| other -> failwithf "Expected stage failure, got %A" other

shText: string -> ProcessCommand

Builds an explicitly assembled POSIX shell program. Values in the text are not escaped by Axial.

(|>): 'T1 -> ('T1 -> 'U) -> 'U

Apply a function to a value, the value being on the left, the function on the right The argument. The function. The function result. let doubleIt x = x * 2 3 |> doubleIt // Evaluates to 6

Axial.Process.Process

tryRun: ^source -> ^result

Runs with live services and returns Exit, including typed failures and interruptions.

Axial.Exit`2

Represents the final outcome of a workflow execution. The type of the success value. The type of the domain-specific failure value.

Failure

The workflow failed due to a specific cause.

Axial.Cause`1

Represents the cause of a failed workflow. The type of the domain-specific failure value.

Fail

An expected domain-specific failure.

Axial.Process.ProcessError

Expected process errors. Runtime cancellation remains Cause.Interrupt.

StageFailed

failure: StageFailure

shouldEqual: 'a -> 'a -> unit

ExitCode: int

Stage: StageResult

other: Exit<ProcessResult,ProcessError>

failwithf: Printf.StringFormat<'T,'Result> -> 'T

Print to a string buffer and raise an exception with the given result. Helper printers must return strings. The formatter. The formatted result. See Printf.failwithf (link: ) for examples.

Requires & types

Requires: open Axial; open Axial.Process; open Axial.Process.DSL (packages: Axial, Axial.Process)

The With variants accept an existing environment instead of supplying live services.

Verified

type AppEnvironment =
    { Process: IProcess
      Console: IConsole
      Region: string }
    interface IHasProcess with member this.Process = this.Process
    interface IHasConsole with member this.Console = this.Console

let reportingConsole = Console.test()
let appEnvironment =
    { Process = Process.live Clock.live FileSystem.live reportingConsole
      Console = reportingConsole
      Region = "eu" }

FsLiveDocsGeneratedPage4_99FDB6C21194.AppEnvironment

Process: IProcess

Axial.Process.IProcess

Executes lazily, awaiting each observation with backpressure.

Console: IConsole

Axial.Console.IConsole

Provides explicit access to standard console and terminal I/O.

Region: string

string

An abbreviation for the CLI type . Basic Types

Axial.Process.IHasProcess

this: AppEnvironment

Process: AppEnvironment -> unit -> IProcess

Axial.Console.IHasConsole

Declares that an environment supplies the console service. Implement this on the environment supplied at the host edge. A workflow that reads or writes the console constrains its environment with 'env :> IHasConsole.

Console: AppEnvironment -> unit -> IConsole

reportingConsole: TestConsole

Axial.Console.ConsoleModule

test: unit -> TestConsole

Creates an in-memory console test double that captures output and reads scripted input.

appEnvironment: AppEnvironment

Axial.Process.Process

live: IClock -> IFileSystem -> IConsole -> IProcess

Axial.PlatformService.Clock

Helpers for the clock service.

live: IClock

Creates a live clock backed by and a monotonic timer.

Axial.FileSystem.FileSystemModule

live: IFileSystem

Creates a live file-system service backed by , , and .

Requires & types

Requires: open Axial.Console; open Axial.FileSystem; open Axial.PlatformService; open Axial.Process (packages: Axial.Console, Axial.FileSystem, Axial.PlatformService, Axial.Process)

val reportingConsole: TestConsole

val appEnvironment: AppEnvironment

Verified

cmd $"dotnet --version"
|> Process.runWith appEnvironment
|> _.ExitCode
|> shouldEqual 0

cmd: FormattableString -> ProcessCommand

(|>): 'T1 -> ('T1 -> 'U) -> 'U

Apply a function to a value, the value being on the left, the function on the right The argument. The function. The function result. let doubleIt x = x * 2 3 |> doubleIt // Evaluates to 6

Axial.Process.Process

runWith: 'env -> ^source -> ^result

Runs with supplied services and returns the value; raises ProcessRunException on failure.

appEnvironment: AppEnvironment

_arg1: ProcessResult

ExitCode: int

shouldEqual: 'a -> 'a -> unit

Requires & types

Requires: open Axial.Process; open Axial.Process.DSL (packages: Axial.Process)

For application composition, use Process.toFlow and run the enclosing workflow with Flow.run. ProcessStream.runCollect returns values plus completion; a stream must have a terminal before a host runner can execute it. Effectful terminals may have ProcessStreamError errors, which Process.tryRun supports; use the ordinary Flow runner when the application wants its own exit-code policy.

Overview

Docs

API Reference