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

Worked examples

These examples go from a command-line script to an application Flow. Each command is a value until a Flow runner reaches the host boundary.

A command-line tool that shows progress

Use console when the command's output is for the person running the program. run supplies live services and turns the Flow outcome into the program's exit code.

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 }

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

Verified

open Axial.Process.DSL

// In a program, mark this [<EntryPoint>].
let main _ =
    cmd $"dotnet --info"
    |> console
    |> run

Axial

Process

Axial.Process.DSL

main: 'a -> int

cmd: FormattableString -> ProcessSpec

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

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

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

Forwards stdout and stderr to the host console while retaining structured completion data.

run: Flow<ProcessHostEnvironment,ProcessError,'a> -> int

Starts a process Flow with live services and returns a command-line exit code.

There is no separate process runtime to construct. Console forwarding is lazy; the final runner starts the command.

Use a command as one step in an application

Use toFlow when the command is one step among other application work. The application supplies its own IProcess service and decides how to use the result.

Verified

let gitRevision : Flow<#IHasProcess, ProcessError, string> =
    flow {
        let! result =
            Process.command $"git rev-parse --short HEAD"
            |> Process.capture

        return result.StdOut.Trim()
    }

let buildLabel =
    flow {
        let! revision = gitRevision
        return $"build-{revision}"
    }

let appEnvironment = host

gitRevision: Flow<ProcessHostEnvironment,ProcessError,string>

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.IHasProcess

Declares that an environment supplies the process service. Implement this on the environment record supplied at the host edge. A workflow that runs processes constrains its environment with 'env :> IHasProcess.

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>.

string

An abbreviation for the CLI type . Basic Types

flow: FlowBuilder

The universal flow { } computation expression.

result: ProcessResult

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

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

Runs a process specification with complete stdout and stderr capture. Example: Process.command $"dotnet --info" |> Process.capture

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.

StdOut: string

buildLabel: Flow<ProcessHostEnvironment,ProcessError,string>

revision: string

appEnvironment: ProcessHostEnvironment

host: ProcessHostEnvironment

Verified

match Flow.run appEnvironment buildLabel with
| Exit.Success label -> label.StartsWith "build-" |> shouldEqual true
| other -> failwithf "unexpected %A" other

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

appEnvironment: ProcessHostEnvironment

buildLabel: Flow<ProcessHostEnvironment,ProcessError,string>

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.

label: string

StartsWith: string -> bool

Determines whether the beginning of this string instance matches the specified string. The string to compare. if matches the beginning of this string; otherwise, . is .

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

other: Exit<string,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.

capture gives this command explicit complete-output policy. Flow.run runs the enclosing application Flow; it does not create or replace the application's environment.

Stream lines into workflow decisions

Use stream when each line should affect the workflow before the command exits. Here a producer reports JSON-like events; the workflow selects only stdout lines and collects them under Flow's cancellation and cleanup scope.

Verified

let collectEvents =
    Process.command $"printf '{{\"event\":\"ready\"}}\n{{\"event\":\"done\"}}\n'"
    |> Process.framing OutputFraming.Lines
    |> Process.stream
    |> FlowStream.choose (function
        | ProcessEvent.Output output when output.Channel = OutputChannel.StdOut ->
            Some output.Text
        | _ -> None)
    |> FlowStream.runCollect

collectEvents: Flow<ProcessHostEnvironment,ProcessError,string list>

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

framing: OutputFraming -> ProcessSpec -> ProcessSpec

Selects chunk or line event framing. Example: specification |> Process.framing OutputFraming.Lines

Axial.Process.OutputFraming

Selects arbitrary decoded chunks or complete decoded lines for streamed events.

Lines

stream: ProcessSpec -> FlowStream<'env,ProcessError,ProcessEvent>

Streams process events in the current Flow runtime. The last event is <c>Completed</c>.

Axial.FlowStreamModule

choose: ('a -> 'b option) -> FlowStream<'c,'d,'a> -> FlowStream<'c,'d,'b>

Maps and filters values in one operation. stream |> FlowStream.choose id

Axial.Process.ProcessEvent

Values emitted by a native process FlowStream.

Output

output: ProcessOutput

Channel: OutputChannel

(=): 'T -> 'T -> bool

Structural equality The first parameter. The second parameter. The result of the comparison. 5 = 5 // Evaluates to true 5 = 6 // Evaluates to false [1; 2] = [1; 2] // Evaluates to true (1, 5) = (1, 6) // Evaluates to false

Axial.Process.OutputChannel

Identifies one standard output channel.

StdOut

Some

The representation of "Value of type 'T" The input value. An option representing the value.

Text: string

None

The representation of "No value"

runCollect: FlowStream<'a,'b,'c> -> Flow<'a,'b,'c list>

Collects all emitted values into a list. stream |> FlowStream.runCollect

Verified

Flow.run appEnvironment collectEvents |> shouldEqual (Exit.Success [ """{"event":"ready"}"""; """{"event":"done"}""" ])

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

appEnvironment: ProcessHostEnvironment

collectEvents: Flow<ProcessHostEnvironment,ProcessError,string list>

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

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.

The consumer pulls the stream. If the enclosing Flow is interrupted or the consumer stops early, Axial interrupts the native process topology and waits for its cleanup.

For command construction and pipelines, continue with commands, input, and pipelines. For output destinations and bounded capture, see output capture and destinations.

Worked examples

A command-line tool that shows progress

Use a command as one step in an application

Stream lines into workflow decisions

Overview

Docs

API Reference