tmux

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 16, 2023 License: MIT Imports: 12 Imported by: 0

Documentation

Index

Constants

View Source 
const DefaultTmux = "tmux"

DefaultTmux is the default name of the tmux executable.

Variables

View Source 
var (
	// ErrNilRunner is returned when a nil [Runner] argument is passed.
	ErrNilRunner = errors.New("runner is nil")
	// ErrNilSession is returned when a nil [Session] argument is passed.
	ErrNilSession = errors.New("session is nil")
	// ErrNilWindow is returned when a nil [Window] argument is passed.
	ErrNilWindow = errors.New("window is nil")
	// ErrNilPane is returned when a nil [Pane] argument is passed.
	ErrSessionClosed = errors.New("session is closed")
	// ErrSessionNotApplied is returned when an unapplied [Session] is used.
	ErrSessionNotApplied = errors.New("session is not applied")
	// ErrWindowNotApplied is returned when an unapplied [Window] is used.
	ErrWindowNotApplied = errors.New("window is not applied")
	// ErrPaneNotApplied is returned when an unapplied [Pane] is used.
	ErrPaneNotApplied = errors.New("pane is not applied")
)

Functions

This section is empty.

Types

type DefaultRunner 

type DefaultRunner struct {
	// contains filtered or unexported fields
}

DefaultRunner is the default Runner implementation.

func NewRunner 

func NewRunner(opts ...RunnerOption) (*DefaultRunner, error)

NewRunner creates a new Runner with the provided options.

func (*DefaultRunner) Debug 

func (c *DefaultRunner) Debug(msg string, args ...any)

Debug logs a debug message using a slog.Logger.

func (*DefaultRunner) Execve 

func (c *DefaultRunner) Execve(args ...string) error

Execve runs the tmux command with the provided arguments using the execve syscall (syscall.Exec) to replace the current process with the tmux process.

func (*DefaultRunner) IsDryRun 

func (c *DefaultRunner) IsDryRun() bool

IsDryRun returns true if the runner is in dry-run mode.

Dry-run mode means that the runner will not actually run any tmux commands but only log the commands that would have been run and return empty output.

func (*DefaultRunner) Log 

func (c *DefaultRunner) Log(msg string, args ...any)

Log logs an info message using a slog.Logger.

func (*DefaultRunner) Run 

func (c *DefaultRunner) Run(ctx context.Context, args ...string) ([]byte, error)

Run runs the tmux command in a context-aware manner with the provided arguments and returns the output.

func (*DefaultRunner) SetLogger 

func (c *DefaultRunner) SetLogger(logger *slog.Logger)

SetLogger sets the logger used by the runner.

type OSCommandRunner 

type OSCommandRunner func(ctx context.Context, name string, args ...string) (output []byte, err error)

OSCommandRunner runs a command with the provided name and arguments and returns the output.

type Pane 

type Pane struct {
	// contains filtered or unexported fields
}

Pane represents a tmux window pane.

func NewPane 

func NewPane(runner Runner, window *Window, parentPane *Pane, opts ...PaneOption) (*Pane, error)

NewPane creates a new Pane instance configured with the provided options and belonging to the provided window and optional parent pane.

The window must be applied before being passed to this function. If a parent pane is provided, it must be applied before being passed to this function.

NOTE: The pane is not created until Pane.Apply is called.

func (*Pane) Apply 

func (p *Pane) Apply(ctx context.Context) error

Apply creates the tmux pane by invoking the split-window command using its internal Runner instance.

If the pane is already applied, this method is a no-op.

https://man.archlinux.org/man/tmux.1#split-window

func (*Pane) IsActive 

func (p *Pane) IsActive() bool

IsActive returns true if the pane is configured as the active pane of its window.

func (*Pane) IsApplied 

func (p *Pane) IsApplied() bool

IsApplied returns true if the pane has been applied with Pane.Apply.

func (*Pane) IsClosed 

func (p *Pane) IsClosed() bool

IsClosed return true if the session has been closed.

func (*Pane) Name 

func (p *Pane) Name() string

Name returns the pane's fully qualified name.

The name is composed of the session name, the window name separated by a colon, followed by a dot and the pane index.

func (*Pane) NumPanes 

func (p *Pane) NumPanes() int

NumPanes returns the number of panes in the pane.

func (*Pane) RunCommands 

func (p *Pane) RunCommands(ctx context.Context, cmds ...string) error

RunCommands runs the provided commands inside the pane by invoking the send-keys tmux command using its internal Runner instance.

The commands are automatically followed by a carriage return.

If the pane is not applied, the method returns ErrPaneNotApplied.

If no commands are provided, the method is a no-op.

https://man.archlinux.org/man/tmux.1#send-keys

func (*Pane) Select 

func (p *Pane) Select(ctx context.Context) error

Select selects the pane by invoking the select-pane command using its internal Runner instance.

If the pane is not applied, the method returns ErrPaneNotApplied.

https://man.archlinux.org/man/tmux.1#select-pane

func (*Pane) String 

func (p *Pane) String() string

String returns a string representation of the pane.

type PaneOption 

type PaneOption func(*Pane) error

PaneOption configures a Pane.

func PaneAsActive 

func PaneAsActive() PaneOption

PaneAsActive configures the Pane to be the active pane of its window.

func PaneWithCommands 

func PaneWithCommands(cmds ...string) PaneOption

PaneWithCommands configures the Pane with an initial shell commands.

The commands will run in the pane after it has been created.

NOTE: Commands are appended to the list of commands, so applying this option multiple times will add to the list of commands.

func PaneWithEnv 

func PaneWithEnv(env map[string]string) PaneOption

PaneWithEnv configures the Pane with environment variables.

Environment variables are inherited from session to window to pane. If a an environment variable is is named the same as an inherited variable, it will take precedence.

func PaneWithHorizontalDirection 

func PaneWithHorizontalDirection() PaneOption

PaneWithHorizontalDirection configures the Pane to be horizontal instead of vertical.

func PaneWithPath 

func PaneWithPath(s string) PaneOption

PaneWithPath configures the Pane working directory.

If a pane is not configured with a working directory, the window's working directory is used instead.

func PaneWithSize 

func PaneWithSize(size string) PaneOption

PaneWithSize configures the Pane size.

The size can be specified as a percentage of the available space or as a number of lines or columns.

type Runner 

type Runner interface {
	// Run runs the tmux command in a context-aware manner with the provided
	// arguments and return the output.
	Run(ctx context.Context, args ...string) ([]byte, error)
	// Execve runs the tmux command with the provided arguments using the execve
	// syscall ([syscall.Exec]) to replace the current process with the tmux
	// process.
	Execve(args ...string) error
	// IsDryRun returns true if the runner is in dry-run mode.
	//
	// Dry-run mode means that the runner will not actually run any tmux commands
	// but only log the commands that would have been run and return empty output.
	IsDryRun() bool
	// Debug writes a debug message using a [slog.Logger].
	Debug(msg string, args ...any)
	// Log writes an info message using a [slog.Logger].
	Log(msg string, args ...any)
	// SetLogger sets the logger used by the runner.
	SetLogger(logger *slog.Logger)
}

Runner runs tmux commands and provide logging functionality.

type RunnerOption 

type RunnerOption func(*DefaultRunner) error

RunnerOption configures a DefaultRunner.

func WithDryRunMode 

func WithDryRunMode(enable bool) RunnerOption

WithDryRunMode configures the runner to run in dry-run mode.

Dry-run mode means that the runner will not actually run any tmux commands but only log the commands that would have been run and return empty output.

The default is false.

func WithLogger 

func WithLogger(logger *slog.Logger) RunnerOption

WithLogger configures the runner to use the provided slog.Logger for logging.

The default is a no-op logger writing to os.Discard.

func WithOSCommandRunner 

func WithOSCommandRunner(runner OSCommandRunner) RunnerOption

WithOSCommandRunner configures the runner to use the provided OSCommandRunner for running tmux commands.

This option is intended for testing purposes only.

func WithSyscallExecRunner 

func WithSyscallExecRunner(runner SyscallExecRunner) RunnerOption

WithSyscallExecRunner configures the runner to use the provided SyscallExecRunner for running tmux commands.

This option is intended for testing purposes only.

func WithTmux 

func WithTmux(name string) RunnerOption

WithTmux configures the runner to use provided name as the tmux executable.

The default is "tmux".

func WithTmuxOptions 

func WithTmuxOptions(opts ...string) RunnerOption

WithTmuxOptions configures the runner with additional tmux options to be added to all tmux command invocations.

type Session 

type Session struct {
	// contains filtered or unexported fields
}

Session represents a tmux session.

func GetSessions 

func GetSessions(ctx context.Context, runner Runner) ([]*Session, error)

GetSessions returns a list of current tmux sessions by invoking the list-sessions command using the provided Runner instance.

https://man.archlinux.org/man/tmux.1#list-sessions

func NewSession 

func NewSession(runner Runner, opts ...SessionOption) (*Session, error)

NewSession creates a new Session instance configured with the provided options.

NOTE: The session is not created until Session.Apply is called.

func (*Session) Apply 

func (s *Session) Apply(ctx context.Context) error

Apply creates the tmux session by invoking the new-session command using its internal Runner instance.

If the session is already applied, this method is a no-op.

https://man.archlinux.org/man/tmux.1#new-session

func (*Session) Attach 

func (s *Session) Attach(ctx context.Context) error

Attach attaches the current client to the session by invoking a tmux command using its internal Runner instance.

NOTE: syscall.Exec is used to replace the current process with the tmux client process. This means that this method will never return if it succeeds.

If the TMUX environment variable is set, it is assumed that the current process is already attached to a tmux session. In this case, the switch-client command is used instead of the attach-session command.

https://man.archlinux.org/man/tmux.1#attach-session https://man.archlinux.org/man/tmux.1#switch-client

func (*Session) Close 

func (s *Session) Close() error

Close closes the session by invoking the kill-session command using its internal Runner instance.

If the session is already closed or not applied, this method is a no-op.

Any subsequent calls to command-invoking methods on the session or any of its windows or panes will return an ErrSessionClosed error.

https://man.archlinux.org/man/tmux.1#kill-session

func (*Session) IsApplied 

func (s *Session) IsApplied() bool

IsApplied returns true if the session has been applied with Session.Apply.

func (*Session) IsClosed 

func (s *Session) IsClosed() bool

IsClosed returns true if the session has been closed with Session.Close.

func (*Session) Name 

func (s *Session) Name() string

Name returns the session name.

func (*Session) NumPanes 

func (s *Session) NumPanes() int

NumPanes returns the number of panes across all windows in the session.

func (*Session) NumWindows 

func (s *Session) NumWindows() int

NumWindows returns the number of windows in the session.

func (*Session) SelectActive 

func (s *Session) SelectActive(ctx context.Context) error

SelectActive selects the window configured as the active window by invoking the select-window command using its internal Runner instance.

If no window is configured as active, the first window is selected.

https://man.archlinux.org/man/tmux.1#select-window

func (*Session) String 

func (s *Session) String() string

String returns a string representation of the session.

type SessionOption 

type SessionOption func(*Session) error

SessionOption configures a Session.

func SessionWithEnv 

func SessionWithEnv(env map[string]string) SessionOption

SessionWithEnv configures the Session environment variables.

Environment variables are inherited from session to window to pane. If a window or pane is confiured with a similarly named environment variable, it will take precedence over the session environment variable.

func SessionWithName 

func SessionWithName(name string) SessionOption

SessionWithName configures the Session name.

func SessionWithOnAnyCommand 

func SessionWithOnAnyCommand(cmd string) SessionOption

SessionWithOnAnyCommand configures a Session with a shell command that will be run in all created windows and panes.

If a command is also configured with SessionWithOnWindowCommand or SessionWithOnPaneCommand, the any command will be run first.

func SessionWithOnPaneCommand 

func SessionWithOnPaneCommand(cmd string) SessionOption

SessionWithOnPaneCommand configures a Session with a shell command that will be run in all created panes.

If a command is also configured with SessionWithOnAnyCommand, the pane command will be run after the any command.

func SessionWithOnWindowCommand 

func SessionWithOnWindowCommand(cmd string) SessionOption

SessionWithOnWindowCommand configures a Session with a shell command that will be run in all created windows.

If a command is also configured with SessionWithOnAnyCommand, the window command will be run after the any command.

func SessionWithPath 

func SessionWithPath(path string) SessionOption

SessionWithPath configures the Session working directory.

type SyscallExecRunner 

type SyscallExecRunner func(string, []string, []string) error

SyscallExecRunner runs a command with the provided arguments using the execve syscall (syscall.Exec) to replace the current process with the new process.

type Window 

type Window struct {
	// contains filtered or unexported fields
}

Window represents a tmux window.

func NewWindow 

func NewWindow(runner Runner, session *Session, opts ...WindowOption) (*Window, error)

NewWindow creates a new Window instance configured with the provided options and belonging to the provided session.

The session must be applied before being passed to this function.

NOTE: The window is not created until Window.Apply is called.

func (*Window) Apply 

func (w *Window) Apply(ctx context.Context) error

Apply creates the tmux window by invoking the new-window command using its internal Runner instance.

If the window is already applied, this method is a no-op.

If the window is the first window in the session, it is created with the -k flag to override the default initial window created by the new-session command.

https://man.archlinux.org/man/tmux.1#new-window

func (*Window) IsActive 

func (w *Window) IsActive() bool

IsActive returns true if the window is configured as the active window of its session.

func (*Window) IsApplied 

func (w *Window) IsApplied() bool

IsApplied returns true if the window has been applied with Window.Apply.

func (*Window) IsClosed 

func (w *Window) IsClosed() bool

IsClosed returns true if the session has been closed.

func (*Window) Name 

func (w *Window) Name() string

Name returns the window's fully qualified name.

The name is composed of the session name and the window name separated by a colon.

func (*Window) NumPanes 

func (w *Window) NumPanes() int

NumPanes returns the number of panes in the window.

func (*Window) RunCommands 

func (w *Window) RunCommands(ctx context.Context, cmds ...string) error

RunCommands runs the provided commands inside the window by invoking the send-keys tmux command using its internal Runner instance.

The commands are automatically followed by a carriage return.

If the window is not applied, the method returns ErrWindowNotApplied.

If no commands are provided, the method is a no-op.

https://man.archlinux.org/man/tmux.1#send-keys

func (*Window) Select 

func (w *Window) Select(ctx context.Context) error

Select selects the window by invoking the select-window command using its internal Runner instance.

If the window is not applied, the method returns ErrWindowNotApplied.

If the window has a pane configured to be the active pane, the pane is also selected.

https://man.archlinux.org/man/tmux.1#select-window

func (*Window) String 

func (w *Window) String() string

String returns a string representation of the window.

type WindowOption 

type WindowOption func(*Window) error

WindowOption configures a Window.

func WindowAsActive 

func WindowAsActive() WindowOption

WindowAsActive configures the Window to be the active window of its session.

func WindowWithCommands 

func WindowWithCommands(cmds ...string) WindowOption

WindowWithCommands configures the Window with an initial shell commands.

The commands will run in the window after it has been created.

NOTE: Commands are appended to the list of commands, so applying this option multiple times will add to the list of commands.

func WindowWithEnv 

func WindowWithEnv(env map[string]string) WindowOption

WindowWithEnv configures the Window with environment variables.

Environment variables are inherited from session to window to pane. If a an environment variable is is named the same as an inherited variable, it will take precedence.

func WindowWithName 

func WindowWithName(name string) WindowOption

WindowWithName configures the Window with a name.

func WindowWithPath 

func WindowWithPath(p string) WindowOption

WindowWithPath configures the Window with a working directory.

If a window is not configured with a working directory, the session's working directory is used instead.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.