Core LibraryunreleasedAPI Reference

Choose documentation 2

latest

Current version

latest
English

Unreleased libtmux has not been released. Its API may change during development. This site's structure and URLs may change too.

function libtmux-ocaml latest

Client.capture

Acquire a complete graph over a recorded interval, with a fixed number of listing commands. Races fail validation. Access to returned values performs no I/O, including after closing the client.

Source and package
Qualified name
Libtmux_unix.Client.capture
Module
Libtmux_unix
Declared in
Client
Package
libtmux-unix
Source
unix/libtmux_unix.mli
Other languages
Perlmethod Erlangfunction PowerShellcmdlet Juliafunction Elixirfunction Haskell Common Lispfunction Python RubyLuaTypeScriptRustmethod GoJavaC# C++ SwiftKotlinScalaF#function Clojurefunction

Public owner: Libtmux_unix

Examples#

Navigate the typed object graph. This complete program creates a private daemon, checks its result and closes its clients. Use OCaml 5.5.2 on Linux with tmux 3.3a through 3.8. Run it from the source checkout after following the installation guide. View source

open Libtmux
module Client = Libtmux_unix.Client
module Workspace = Libtmux_unix.Workspace
module Config = Libtmux_workspace.Config
module Plan = Libtmux_workspace.Plan
module Execution = Libtmux_workspace.Execution
let get = function
| Ok value -> value
| Error error -> failwith (Format.asprintf "%a" Error.pp error)
let capture_graph client (initial : Created.t) spawn =
let linked =
get
(Client.create_session client ~name:"linked" ~window_name:"linked-home"
~spawn ())
in
let pane =
Snapshot.find_pane
(get (Client.capture client))
(Pane.Target.id linked.pane)
|> Option.get
in
let text = "showcase ready" in
ignore (get (Client.wait_for_text ~timeout:0.5 client pane ~text));
get
(Client.link_window client initial.window ~session:linked.session ~index:7);
get (Client.capture client)
let print_graph snapshot =
Snapshot.sessions snapshot
|> Iarray.iter (fun session ->
Session.window_links session
|> Iarray.iter (fun link ->
let window = Window_link.window link in
Printf.printf "%s/%d %s: %d pane(s)\n" (Session.name session)
(Window_link.index link) (Window.name window)
(Iarray.length (Window.panes window))));
assert (Iarray.length (Snapshot.sessions snapshot) = 2);
assert (Iarray.length (Snapshot.windows snapshot) = 2);
assert (Iarray.length (Snapshot.window_links snapshot) = 3);
assert (Iarray.length (Snapshot.panes snapshot) = 2);
print_endline "graph: 2 sessions, 2 windows, 3 links, 2 panes"
let with_demo binary use =
let directory = Filename.temp_dir "libtmux-ocaml-showcase-" "" in
Fun.protect
~finally:(fun () ->
Sys.readdir directory
|> Array.iter (fun name -> Sys.remove (Filename.concat directory name));
Unix.rmdir directory)
(fun () ->
let socket = Filename.concat directory "server" in
(* Give this private daemon a lifetime even if startup fails. *)
let config_file = Filename.concat directory "tmux.conf" in
Out_channel.with_open_text config_file (fun output ->
output_string output "set-option -s exit-unattached on\n");
let wrapper = Filename.concat directory "tmux" in
Out_channel.with_open_text wrapper (fun output ->
Printf.fprintf output "#!/bin/sh\nexec %s -f %s \"$@\"\n"
(Filename.quote binary)
(Filename.quote config_file));
Unix.chmod wrapper 0o700;
let channel = Unix.open_process_args_in binary [| binary; "-V" |] in
let version =
Fun.protect
~finally:(fun () ->
if Unix.close_process_in channel <> Unix.WEXITED 0 then
failwith "tmux version discovery failed")
(fun () -> String.trim (input_line channel))
in
if not (String.starts_with ~prefix:"tmux " version) then
failwith "invalid tmux version";
let version = String.sub version 5 (String.length version - 5) in
let ready = Filename.concat directory "ready.txt" in
Out_channel.with_open_text ready (fun output ->
output_string output "showcase ready\n");
let spawn =
Spawn.make (Exec { program = "/bin/cat"; args = [ "-u"; ready; "-" ] })
in
let config =
match
Config.make ~directory ~session:"showcase"
[ Config.window ~name:"editor" [ Config.pane ~spawn () ] ]
with
| Ok value -> value
| Error error -> failwith (Format.asprintf "%a" Config.pp_error error)
in
let plan =
match
Plan.make
~endpoint:(Endpoint.socket_path socket)
~version ~observed:None config
with
| Ok value -> value
| Error error -> failwith (Format.asprintf "%a" Plan.pp_error error)
in
let operation = get (Workspace.submit_bootstrap ~binary:wrapper plan) in
Fun.protect
~finally:(fun () -> get (Workspace.close operation))
(fun () ->
let receipt = get (Workspace.await operation) in
if receipt.status <> Execution.Succeeded then
failwith "workspace setup failed";
let client = Option.get (Workspace.client operation) in
let initial = List.hd (Iarray.get receipt.steps 0).created in
Printf.printf "socket=%s\n%!" socket;
let pane =
Snapshot.find_pane
(get (Client.capture client))
(Pane.Target.id initial.pane)
|> Option.get
in
ignore
(get
(Client.wait_for_text ~timeout:0.5 client pane
~text:"showcase ready"));
use client initial spawn))
let () =
let binary = if Array.length Sys.argv = 2 then Sys.argv.(1) else "tmux" in
let snapshot = with_demo binary capture_graph in
print_graph snapshot

Run the recorded entry point:

Terminal window
$ opam exec -- dune exec examples/showcase_graph.exe -- tmux

Expected outcome line, after the temporary socket path:

graph: 2 sessions, 2 windows, 3 links, 2 panes
Parameters

tmux command#

The tmux commands behind capture.

tmux C API#

The C declarations in tmux that implement these commands.

In other ports#

Capture the tmux hierarchy

Equivalents of Capture the tmux hierarchy in other languages
Language Equivalent
Python no equivalent on Server
Ruby LibTmux::Server#snapshot
Lua libtmux.Server:snapshot
PowerShell LibTmux\Get-TmuxSnapshot Acquires a replacement LibTmux.Server to -Depth (panes by default). Acquisition is not atomic; retained handles do not refresh.
Julia LibTmux.snapshot Acquires a new Snapshot over an observation interval. Topology checks do not make it a transaction; earlier snapshots do not refresh.
Erlang tmux_server:snapshot/1 Captures a new graph over an observation interval. Retained snapshots never refresh.
Elixir LibTmux.Server.snapshot/2 Captures a new graph over an observation interval. A retained Snapshot never refreshes.
Haskell No public Haskell equivalent is implemented; the current modules expose scalar values and version parsing.
Common Lisp libtmux:fetch-snapshot fetch-snapshot acquires a new interval observation. Retained snapshots never refresh in place.
TypeScript server.Server.snapshot
Rust server.Server.hierarchy Fetches the whole hierarchy with list-sessions, list-windows -a and list-panes -a, and stitches the rows by winlink. The three listings are separate commands, so the capture is not an atomic transaction.
Go tmux.Server.Snapshot
Java io.github.libtmux.Server.snapshot
Clojure libtmux.core/snapshot! Acquires a captured graph of persistent values. Retained values do not refresh after mutation or close.
Kotlin io.github.libtmux.kotlin.Server.snapshot
Scala io.github.libtmux.scaladsl.Server.snapshot
C# LibTmux.Server.CaptureSnapshotAsync
F# LibTmux.FSharp.Server.capture Acquires a replacement shared .NET LibTmux.Server to the requested depth. Acquisition is not atomic; retained handles do not refresh.
C++ no equivalent on Server: sessions, windows, panes and clients each take a snapshot of one listing, and Snapshot::take needs the internal detail::Backend, so no public call reads the whole hierarchy at once
Swift Server.snapshot()
Perl LibTmux::Server::snapshot Strict acquisition observes an interval, not an atomic transaction; retained handles do not refresh.
Esc

Type to search.

Reference previewOpen reference