LibTmux.New-TmuxServer

Description#

Choose a socket name or absolute socket path. Construction performs no tmux I/O and does not start or own a daemon. A later command explicitly acquires data or changes tmux.

Omitting both socket parameters passes tmux no socket, so tmux picks the server: the one the TMUX variable names inside a tmux pane, otherwise its default socket. Two variables choose a socket for such a handle. LIBTMUX_SOCKET_PATH becomes -S and LIBTMUX_SOCKET becomes -L; when both are set the path wins, and a blank value counts as unset. A parameter beats both variables. The handle reads the variables when it is made. LIBTMUX_SOCKET_NAME, which earlier versions read, selects nothing.

What is on here. Most cmdlets in the module start from the handle this one returns. They take it directly, or take a session, window, pane or client that was read through it. The cmdlets fall into a few groups:

Connecting. New-TmuxServer builds the handle. Connect-TmuxServer discovers the live server behind it and returns a connected replacement, and Get-TmuxServer reads the daemon's identity and version without starting one. Connect-TmuxControl opens a control client and Disconnect-TmuxControl closes it.

Finding one thing. Get-TmuxSession and Get-TmuxWindow select by id or name, Get-TmuxPane by id, and Get-TmuxClient by name. A selector that matches nothing emits nothing. Get-TmuxClientAttachment resolves the session, window and pane a client is viewing.

Listing everything. Get-TmuxSession, Get-TmuxWindow, Get-TmuxPane and Get-TmuxClient list everything on the server when given no selector. A missing daemon writes an error instead of returning an empty list. Get-TmuxSnapshot captures the hierarchy to a depth you choose and returns a replacement server. Update-TmuxPane and Update-TmuxClient read one object again into a new capture.

Querying things and getting around. New-TmuxQuery builds reusable criteria. Select-TmuxSession, Select-TmuxWindow and Select-TmuxPane filter objects you already captured without contacting tmux, and can require exactly one match. Invoke-TmuxQuery acquires fresh objects instead. Get-TmuxQueryField lists the fields and operators, Get-TmuxQueryPlan shows how a query will run, and ConvertTo-TmuxQueryJson serializes one. To move down the hierarchy, pass a session to Get-TmuxWindow or Get-TmuxPane, or a window to Get-TmuxPane.

Changing things. New-TmuxSession, New-TmuxWindow, Split-TmuxPane and New-TmuxWindowLink create, and New-TmuxSession can start a daemon that is not running yet. Move-TmuxWindow, Set-TmuxLayout, Set-TmuxPaneSize and Set-TmuxWindowSize rearrange. Remove-TmuxSession, Remove-TmuxWindow, Remove-TmuxWindowLink and Remove-TmuxPane delete.

Options and hooks. Get-TmuxOption, Set-TmuxOption and Remove-TmuxOption read, write and unset options on a server, session, window or pane. Get-TmuxHook, Set-TmuxHook and Remove-TmuxHook do the same for hooks, and Invoke-TmuxHook runs one now. Get-TmuxEnvironment, Set-TmuxEnvironment and Remove-TmuxEnvironment manage the environment table of a server or session.

Everything else tmux keeps. Send-TmuxText and Send-TmuxKey type into a pane, Get-TmuxPaneContent reads what it shows, and Wait-TmuxPaneText waits for text to appear. Invoke-TmuxPaneCommand runs a shell command in a pane and reports its exit status. Wait-TmuxChannel waits for a channel signal, and Watch-TmuxEvent streams events from a control client.

Things that need a terminal. Enter-TmuxSession attaches your foreground terminal to a session and returns when you detach. Run it outside tmux; it rejects redirected input.

Anything tmux can do that is not here is reachable through Invoke-TmuxCommand, which runs literal tmux arguments and returns the result. Invoke-TmuxChain runs several commands in order, New-TmuxCommand builds one without running it, and Invoke-TmuxControlCommand sends one over a control client.

Notes

The returned LibTmux.Server is unmaterialized. TmuxBinaryPath and ConfigurationFile affect subsequent operations; construction does not execute them.