exec

Overview ¶

Package exec provides utilities for executing system commands with IOResult-based error handling.

This package wraps system command execution in the IOResult monad, which represents IO operations that can fail with errors using Go's idiomatic (value, error) tuple pattern. Unlike the result/exec package, these operations explicitly acknowledge their side-effectful nature by returning IOResult instead of plain Result.

Overview ¶

The exec package is designed for executing system commands as IO operations that may fail. Since command execution is inherently side-effectful (it interacts with the operating system, may produce different results over time, and has observable effects), IOResult is the appropriate abstraction.

Basic Usage ¶

The primary function is Command, which executes a system command:

import (
    "github.com/IBM/fp-go/v2/bytes"
    "github.com/IBM/fp-go/v2/exec"
    "github.com/IBM/fp-go/v2/function"
    "github.com/IBM/fp-go/v2/idiomatic/ioresult"
    ioexec "github.com/IBM/fp-go/v2/idiomatic/ioresult/exec"
)

// Execute a command and get the output
version := F.Pipe1(
    ioexec.Command("openssl")([]string{"version"})([]byte{}),
    ioresult.Map(F.Flow2(
        exec.StdOut,
        bytes.ToString,
    )),
)

// Run the IO operation
result, err := version()
if err != nil {
    log.Fatal(err)
}
fmt.Println(result)

Command Output ¶

Commands return exec.CommandOutput, which contains both stdout and stderr as byte slices. Use exec.StdOut and exec.StdErr to extract the respective streams:

output := ioexec.Command("ls")([]string{"-la"})([]byte{})
result := ioresult.Map(func(out exec.CommandOutput) string {
    stdout := exec.StdOut(out)
    stderr := exec.StdErr(out)
    return bytes.ToString(stdout)
})(output)

Composing Commands ¶

Commands can be composed using IOResult combinators:

// Chain multiple commands together
pipeline := F.Pipe2(
    ioexec.Command("echo")([]string{"hello world"})([]byte{}),
    ioresult.Chain(func(out exec.CommandOutput) ioexec.IOResult[exec.CommandOutput] {
        input := exec.StdOut(out)
        return ioexec.Command("tr")([]string{"a-z", "A-Z"})(input)
    }),
    ioresult.Map(F.Flow2(exec.StdOut, bytes.ToString)),
)

Error Handling ¶

Commands return errors for various failure conditions:

• Command not found
• Non-zero exit status
• Permission errors
• System resource errors

Handle errors using IOResult's error handling combinators:

safeCommand := F.Pipe1(
    ioexec.Command("risky-command")([]string{})([]byte{}),
    ioresult.Alt(func() (exec.CommandOutput, error) {
        // Fallback on error
        return exec.CommandOutput{}, nil
    }),
)