Commands and composition

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

Process.command safely tokenizes an interpolated command template and returns a runnable ProcessSpec. Each interpolation hole becomes one native argument:

Show page setup

// Setup for the checked examples on this page.
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
/// 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

// The examples on this page start real processes with the live service.
let host : ProcessHostEnvironment =
    { Process = Process.live Clock.live FileSystem.live Console.live
      Console = Console.live }

let stdoutOf (workflow: Flow<ProcessHostEnvironment, ProcessError, ProcessResult>) : string =
    match Flow.run host workflow with
    | Exit.Success result -> result.StdOut
    | Exit.Failure cause -> failwithf "%A" cause

host: ProcessHostEnvironment

Axial.Process.ProcessHostEnvironment

The live environment used by <c>Process.run</c> at a command-line host boundary. Application workflows normally use their own environment record and <c>Process.runWith</c>.

Process: IProcess

Axial.Process.ProcessModule

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

Creates a live process service using an explicit clock for transcript timestamps and durations.

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 .

Axial.Console.ConsoleModule

live: IConsole

Creates a live console service backed by .

Console: IConsole

stdoutOf: Flow<ProcessHostEnvironment,ProcessError,ProcessResult> -> string

workflow: Flow<ProcessHostEnvironment,ProcessError,ProcessResult>

Axial.Flow`3

Represents a cold workflow that reads an environment, returns a typed result, and is executed explicitly through one of its execution members such as ToTask, ToAsync, or RunSynchronously. The type of the environment dependency. The type of the failure value. The type of the success value.

Axial.Process.ProcessError

A recoverable process startup, timeout, stage, or I/O failure. Interrupting the workflow is not an error: it terminates the processes and surfaces as <c>Cause.Interrupt</c>.

Axial.Process.ProcessResult

The complete structured transcript returned by a process execution.

string

An abbreviation for the CLI type . Basic Types

Axial.Flow

run: 'env -> Flow<'env,'error,'value> -> Exit<'value,'error>

Runs the workflow and blocks until the final exit is available. The environment used by the workflow. The workflow to run. The final workflow exit. let exit = workflow |> Flow.run environment

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.

Success

The workflow completed successfully.

result: ProcessResult

StdOut: string

Failure

The workflow failed due to a specific cause.

cause: Cause<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.

Verified

let status (repository: string) =
    Process.command $"git status --short"
    |> Process.workingDirectory repository
    |> Process.environment "CI" "true"
    |> Process.timeout (TimeSpan.FromSeconds 15.0)

status: string -> ProcessSpec

repository: string

string

An abbreviation for the CLI type . Basic Types

Axial.Process.ProcessModule

command: FormattableString -> ProcessSpec

Creates a safely tokenized one-command process specification from an interpolated command template. Each interpolation hole is one native argument. Example: Process.command $"git show {revision}" |> Process.toFlow

(|>): '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

workingDirectory: string -> ProcessSpec -> ProcessSpec

Sets the working directory. Example: command |> Process.workingDirectory repo

environment: string -> string -> ProcessSpec -> ProcessSpec

Sets an environment override. Example: command |> Process.environment "CI" "true"

timeout: TimeSpan -> ProcessSpec -> ProcessSpec

Sets the maximum execution time for the complete process topology. Example: specification |> Process.timeout (TimeSpan.FromSeconds 30.0)

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 .

Apply command-specific configuration before connecting stages. Process.arg, Process.secretArg, Process.workingDirectory, Process.environment, Process.removeEnvironment, Process.encoding, and Process.successCodes require a one-command specification.

Connect stdout to the next stage with Process.pipe:

Verified

let countLines : Flow<ProcessHostEnvironment, ProcessError, ProcessResult> =
    Process.command $"printf 'error one\nerror two\n'"
    |> Process.pipe (Process.command $"wc -l")
    |> Process.toFlow

countLines: Flow<ProcessHostEnvironment,ProcessError,ProcessResult>

Axial.Flow`3

Axial.Process.ProcessHostEnvironment

The live environment used by <c>Process.run</c> at a command-line host boundary. Application workflows normally use their own environment record and <c>Process.runWith</c>.

Axial.Process.ProcessError

A recoverable process startup, timeout, stage, or I/O failure. Interrupting the workflow is not an error: it terminates the processes and surfaces as <c>Cause.Interrupt</c>.

Axial.Process.ProcessResult

The complete structured transcript returned by a process execution.

Axial.Process.ProcessModule

command: FormattableString -> ProcessSpec

(|>): '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

pipe: ProcessSpec -> ProcessSpec -> ProcessSpec

Connects the current stdout to the next one-command specification's stdin.

toFlow: ProcessSpec -> Flow<'env,ProcessError,ProcessResult>

Converts a process specification into a lazy Flow in the current environment. Example: specification |> Process.toFlow

Verified

stdoutOf countLines |> _.Trim() |> shouldEqual "2"

stdoutOf: Flow<ProcessHostEnvironment,ProcessError,ProcessResult> -> string

countLines: Flow<ProcessHostEnvironment,ProcessError,ProcessResult>

(|>): '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

_arg1: string

Trim: unit -> string

Removes all leading and trailing white-space characters from the current object. The string that remains after all white-space characters are removed from the start and end of the current string. If no characters can be trimmed from the current instance, the method returns the current instance unchanged.

shouldEqual: 'a -> 'a -> unit

The DSL offers the same model with shorter names:

Verified

open Axial.Process.DSL

let shout (value: string) =
    cmd $"printf %%s {value}"
    => cmd $"tr '[:lower:]' '[:upper:]'"
    |> timeout (TimeSpan.FromSeconds 5.0)
    |> capture

Axial

Process

Axial.Process.DSL

shout: string -> Flow<'a,ProcessError,ProcessResult>

value: string

string

An abbreviation for the CLI type . Basic Types

cmd: FormattableString -> ProcessSpec

Builds a command-line-shaped command while preserving every interpolation hole as one argument.

(=>): ^source -> ^destination -> ^result

Connects a typed input, command, specification, or terminal output endpoint.

(|>): '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

timeout: TimeSpan -> ProcessSpec -> ProcessSpec

Sets the maximum execution time for a command or specification. Example: cmd $"service-device" |> timeout (TimeSpan.FromSeconds 30.0) |> capture

System.TimeSpan

Represents a time interval.

FromSeconds: float -> TimeSpan

capture: ProcessSpec -> Flow<'a,ProcessError,ProcessResult>

Runs a command or specification and captures stdout and stderr.

The interpolated value is one argument, even with spaces or shell characters in it:

Verified

stdoutOf (shout "hello; world") |> shouldEqual "HELLO; WORLD"

stdoutOf: Flow<ProcessHostEnvironment,ProcessError,ProcessResult> -> string

shout: string -> Flow<'a,ProcessError,ProcessResult>

(|>): '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

shouldEqual: 'a -> 'a -> unit

Each interpolation hole becomes one argument. Use secret when plans, failures, and transcripts must show *** instead of the real value. Use cmdText only for fixed command text.

Use Process.commandArgs when arguments already exist as a list. It has the same immutable specification result, without command-line parsing.

Process.plan returns a redacted, serializable description without executing anything. Process.render returns a redacted shell-like diagnostic string; it is not a shell command generator.

Overview

Docs

API Reference