ptycapture

Documentation

Overview

Package ptycapture runs subprocesses with optional pseudo-terminal sizing, timeouts, output limits, and stderr handling for documentation tools.

Plain capture bounds output draining after the direct child exits so that a descendant retaining an inherited pipe cannot block forever. Output written through such descendant-held pipes may therefore be truncated; the drain interval is an implementation detail, not a timing guarantee.

Index

• func ApplyStderrMode(stdout, stderr []byte, mode StderrMode) ([]byte, []byte)
• func CapturePTY(ctx context.Context, opts Options, argv []string) (stdout, stderr []byte, err error)
• func CapturePlain(ctx context.Context, opts Options, argv []string) (stdout, stderr []byte, err error)
• func ExitCode(err error) (int, bool)
• type Options
• type StderrMode
  • func ParseStderrMode(s string) (StderrMode, error)

Examples

• CapturePlain

Functions

func ApplyStderrMode

func ApplyStderrMode(stdout, stderr []byte, mode StderrMode) ([]byte, []byte)

ApplyStderrMode merges or discards stderr per mode. Merge appends the complete stderr stream after stdout; it does not preserve the streams' temporal ordering.

func CapturePTY

func CapturePTY(ctx context.Context, opts Options, argv []string) (stdout, stderr []byte, err error)

CapturePTY runs argv with stdin and stdout on a PTY (fixed cols×rows). stderr is captured with a separate pipe. A nil context is treated as context.Background.

func CapturePlain

func CapturePlain(ctx context.Context, opts Options, argv []string) (stdout, stderr []byte, err error)

CapturePlain runs argv with ordinary pipe I/O (no pseudo-terminal). A nil context is treated as context.Background.

Example

package main

import (
	"bytes"
	"context"
	"fmt"
	"time"

	"github.com/apstndb/ptyhelp/ptycapture"
)

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
	defer cancel()

	stdout, stderr, err := ptycapture.CapturePlain(ctx, ptycapture.Options{
		KillAfter: time.Second,
	}, []string{"go", "version"})
	fmt.Println(err == nil)
	fmt.Println(bytes.HasPrefix(stdout, []byte("go version ")))
	fmt.Println(len(stderr) == 0)
}

Output:
true
true
true

func ExitCode

func ExitCode(err error) (int, bool)

ExitCode returns the subprocess exit code when err represents a normal exit failure.

Types

type Options

type Options struct {
	Cols uint
	Rows uint
	// KillAfter allows graceful termination before forcefully stopping the process.
	KillAfter time.Duration
	// MaxOutputBytes limits each captured output stream when greater than zero.
	MaxOutputBytes int64
}

Options configures subprocess capture.

type StderrMode

type StderrMode int

StderrMode controls how stderr is exposed to callers.

const (
	// StderrSeparate keeps stdout and stderr in separate slices.
	StderrSeparate StderrMode = iota
	// StderrMerge appends stderr bytes after stdout without preserving temporal ordering.
	StderrMerge
	// StderrDiscard drops captured stderr.
	StderrDiscard
)

func ParseStderrMode

func ParseStderrMode(s string) (StderrMode, error)

ParseStderrMode parses -stderr flag values.