Core Library0.xAPI Reference

Choose documentation 3

latest

Current version

latest
English

Early release libtmux is released, and its APIs may still change between releases. This site's structure and URLs may change too.

method libtmux-swift latest

Server.split(_:direction:size:startDirectory:environment:shell:)

Splits one pane, returning the pane that appeared.

Source and package
Qualified name
Server.split(_:direction:size:startDirectory:environment:shell:)
Declared in
Server
Package
libtmux-swift
Source
Sources/LibTmux/Creation.swift
Other languages
Perlmethod Erlang PowerShell Julia Elixir Haskell Common Lisp PythonRubyLuaTypeScriptRustGoJavaC# C++ KotlinScalaOCaml F# Clojure

Description#

The same call as splitWindow(_:direction:size:startDirectory:) with the ambiguity removed: a window has an active pane and tmux splits that one, which is what you want interactively and rarely what you want when building a layout. environment and shell reach only this one split, the same as tmux's own -e and trailing shell-command on split-window.

Examples#

Split a specific pane. Split the fixture's pane to the right and give the new pane 40 percent of its width. Address the pane itself so a different active pane cannot change the target. Use Swift 6.2 or newer and tmux 3.3a or newer on Linux or macOS. In an empty directory, save this consumer package as Package.swift; SwiftPM fetches the library from release 0.1.1:

// swift-tools-version: 6.2
import PackageDescription
let package = Package(
name: "ApiExample",
platforms: [.macOS(.v13)],
dependencies: [
.package(url: "https://github.com/libtmux/libtmux-swift.git", from: "0.1.1")
],
targets: [
.executableTarget(
name: "ApiExample",
dependencies: [
.product(name: "LibTmux", package: "libtmux-swift"),
.product(name: "TmuxFixture", package: "libtmux-swift"),
],
path: "Sources"
)
]
)

Create a Sources directory and save this complete program as Sources/Example.swift. The withTmuxServer fixture owns a private tmux server and stops it after success or failure. Ordinary application code uses Server for its own socket; these examples use the fixture until their setup moves to ordinary server objects. View source

import Foundation
import LibTmux
import TmuxFixture
@main
struct ApiSplitPane {
static func main() async {
do {
try await withTmuxServer { @Sendable server in
guard let original = try await server.panes().first else {
throw ExampleError.paneMissing
}
let created = try await server.split(
original,
direction: .right,
size: .percentage(40)
)
let panes = try await server.panes().filter { $0.windowID == original.windowID }
print("Panes in window: \(panes.count)")
print("Same window: \(created.windowID == original.windowID)")
}
} catch {
FileHandle.standardError.write(Data("Example failed: \(error)\n".utf8))
exit(EXIT_FAILURE)
}
}
enum ExampleError: Error {
case paneMissing
}
}

Build and run the saved program. An operation or cleanup error produces a failing exit status. Set LIBTMUX_TMUX_BIN to an absolute executable path to select a tmux version:

Terminal window
$ swift run ApiExample

Expected output:

Panes in window: 2
Same window: true

tmux command#

The tmux commands behind split(_:direction:size:startDirectory:environment:shell:).

tmux C API#

The C declarations in tmux that implement these commands.

Each path starts at a function a command runs, which is degree 1. The degree counts steps from there along the path, and each step is a call or a reference: degree 2 is reached from that function, degree 3 from the next, and so on.

Split a window

  1. 1 cmd_split_window_exec
  2. references → 2 spawn_pane
  3. calls → 3 window_add_pane
  4. calls → 4 window_pane_create

In other ports#

Split a pane in two

Equivalents of Split a pane in two in other languages
Language Equivalent
Python libtmux.Pane.split
Ruby LibTmux::Pane#split
Lua libtmux.Pane:split
Erlang tmux_pane:split/2
Haskell No public Haskell equivalent is implemented; the current modules expose scalar values and version parsing.
TypeScript pane.Pane.split
Rust pane.Pane.split
Go tmux.Pane.Split
Java io.github.libtmux.Pane.split
Clojure libtmux.core/split-pane!
Kotlin io.github.libtmux.kotlin.Pane.split
Scala io.github.libtmux.scaladsl.Pane.split
C# LibTmux.Pane.SplitAsync
C++ no direct pane target; Window.split splits the active pane
OCaml Libtmux_unix.Client.split_pane
Perl LibTmux::Server::split_pane Explicit Server operation. Captured entities remain local observations; use a new snapshot to observe changes.

No equivalent is recorded in PowerShell, Julia, Elixir, Common Lisp or F#.

Esc

Type to search.

Reference previewOpen reference