README
¶
Subflow
Subflow is a Go library designed for managing and executing subprocesses. It provides an interface to define commands, manage input/output streams, and handle subprocess lifecycle events synchronously and asynchronously.
Installation
Install Subflow using go get:
go get github.com/bobcatalyst/subflow
Import it in your Go code:
import "github.com/bobcatalyst/subflow"
Quick Start
Define a Command
Create a basic command:
cmd := subflow.NewCommand("ls")
Add arguments and environment variables:
cmdArgsEnv := subflow.NewCommandArgsEnv("ls", []string{"-l", "-a"}, []string{"PATH=/usr/bin"})
Run a Command
Execute a command and get output:
ctx := context.Background()
output := subflow.Run(ctx, cmdArgsEnv, nil)
fmt.Printf("Stdout: %s\n", string(output.Stdout()))
fmt.Printf("Stderr: %s\n", string(output.Stderr()))
Manage Subprocesses
Asynchronous subprocess management:
ctx, cancel := context.WithCancel(context.Background())
defer cancel()
subCmd, err := subflow.New(ctx, cmdArgsEnv)
if err != nil {
log.Fatalf("failed to create command: %v", err)
}
defer subCmd.Close()
go func() {
for msg := range subCmd.Listen(ctx) {
fmt.Printf("Message: %v\n", msg)
}
}()
subCmd.Start()
<-subCmd.Wait()
Streaming Input
Push input data to a running command:
subCmd.Push(subflow.NewInputln("example input"))
Documentation
¶
Index ¶
- type BaseMessage
- type Cmd
- type Command
- type CommandArgs
- type CommandArgsEnv
- type CommandEnv
- type Data
- type DataLike
- type ErrExitCode
- type ExitMessage
- type Input
- type JSONString
- type Message
- type Output
- type StartMessage
- type StderrMessage
- type StdinMessage
- type StdioLike
- type StdoutMessage
- type TextInput
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BaseMessage ¶
type BaseMessage[K fmt.Stringer] struct { Time time.Time `json:"time"` Kind JSONString[K] `json:"kind"` }
func NewBaseMessage ¶
func NewBaseMessage[K fmt.Stringer]() BaseMessage[K]
NewBaseMessage initializes a new BaseMessage with the current time.
type Cmd ¶
type Cmd struct {
// contains filtered or unexported fields
}
func (*Cmd) CloseTimeout ¶
CloseTimeout stops the command and cleans up resources. If the command does not terminate, it will be killed after a timeout.
func (*Cmd) Done ¶
func (cmd *Cmd) Done() <-chan struct{}
Done returns a channel that closes when the process completes.
func (*Cmd) Listen ¶
Listen emits the process start, stdout/err/in, and the exit code. It is non buffered, so any messages emitted before Listen is called will be lost. Call Listen before Start to get all messages.
c1 := cmd.Listen(context.Background) cmd.Start() c2 := cmd.Listen(context.Background)
c1 will contain the start message while c2 will not.
type CommandArgs ¶
func NewCommandArgs ¶
func NewCommandArgs(command string, args []string) CommandArgs
type CommandArgsEnv ¶
type CommandArgsEnv interface {
CommandArgs
Environment() []string
}
func NewCommandArgsEnv ¶
func NewCommandArgsEnv(command string, args, env []string) CommandArgsEnv
type CommandEnv ¶
func NewCommandEnv ¶
func NewCommandEnv(command string, env []string) CommandEnv
func WithEnv ¶
func WithEnv(cmd Command, env []string) CommandEnv
WithEnv appends new environment variables to the command.
type Data ¶
type Data []byte
Data represents a slice of bytes that can be serialized to/from JSON.
func (Data) MarshalJSON ¶
func (*Data) UnmarshalJSON ¶
type ErrExitCode ¶
type ErrExitCode int
ErrExitCode represents a non zero process exit code.
func (ErrExitCode) Error ¶
func (err ErrExitCode) Error() string
type ExitMessage ¶
type ExitMessage struct {
BaseMessage[kind[exit]]
Code int `json:"code"`
}
ExitMessage represents a message indicating the end of a process, including the exit code.
type Input ¶
Input extends Message and provides a method to get the input data as bytes.
func NewInputln ¶
NewInputln creates a new TextInput with a newline appended.
type JSONString ¶
JSONString wraps a type that implements fmt.Stringer for JSON serialization.
func (JSONString[S]) MarshalJSON ¶
func (js JSONString[S]) MarshalJSON() ([]byte, error)
func (JSONString[S]) String ¶
func (JSONString[S]) String() string
func (*JSONString[S]) UnmarshalJSON ¶
func (js *JSONString[S]) UnmarshalJSON(b []byte) error
type Message ¶
type Message interface {
// contains filtered or unexported methods
}
Message represents a generic interface for message types.
func NewExitMessage ¶
func NewStartMessage ¶
func NewStartMessage() Message
func NewStdioMessage ¶
NewStdioMessage creates a specific type of StdioMessage based on the provided data.
type Output ¶
type Output struct {
// contains filtered or unexported fields
}
Output struct captures the result of asynchronously running a command. It includes the standard output, standard error, exit code, and any execution error.
type StartMessage ¶
type StartMessage struct {
BaseMessage[kind[start]]
}
StartMessage represents a message indicating the start of a process.
type StderrMessage ¶
type StderrMessage = stdioMessage[kind[stderr]]
type StdinMessage ¶
type StdinMessage = stdioMessage[kind[stdin]]
type StdioLike ¶
type StdioLike interface {
StderrMessage | StdoutMessage | StdinMessage
}
StdioLike groups StdioMessage types for stdin, stdout, and stderr.
type StdoutMessage ¶
type StdoutMessage = stdioMessage[kind[stdout]]
Source Files