NAME

LibTmux::X - Typed failures with readable diagnostics

DESCRIPTION

Errors stringify with class, path, and message. "Creation" retains its original acquisition exception separately through cause. details returns diagnostic fields. Acquisition failures never represent an empty selection.

METHODS

new

new(%details) constructs an exception object without throwing or I/O.

throw

throw(%details) throws one exception object of the receiving class.

message

Return the human-readable failure description.

path

Return the criterion or argument path, or undef when inapplicable.

entity

Return the entity kind, or undef when inapplicable.

expected

Return the expected operand description, or undef.

received

Return the received operand description, or undef.

matched_ids

Return a fresh arrayref of observed matching IDs, including duplicate occurrences.

count

Return the observed cardinality lower bound where applicable.

result

Return a completed or bounded partial LibTmux::CommandResult, or undef before process dispatch.

dispatched

Return whether the request was submitted where known; undef means no dispatch evidence was recorded. This never proves rollback.

details

Return a fresh shallow hashref of diagnostic fields. Causes and entity handles retain their identity.

created

Creation failures expose a minimal generation-scoped entity receipt, or undef. Only "Creation" in LibTmux::X provides this method.

cause

Return the original acquisition exception for "Creation" in LibTmux::X.

CARDINALITY AND DATA FAILURES

NoMatch

No occurrence matched one().

MultipleMatches

At least two occurrences matched. matched_ids preserves occurrence diagnostics.

InvalidFilter

Invalid criteria data; path, expected, and received describe the boundary.

InvalidSelection

Undefined, hole, wrong-kind, or incompatible-generation membership.

InvalidArgument

Invalid operation or transport argument before dispatch.

Unloaded

A required field or relation is not available in captured data.

UnsupportedValue

A local value has no supported portable wire representation.

Unsupported

A daemon or execution capability is unavailable.

AcquisitionRace

Observed generations or topology changed during capture.

QueryMismatch

Native candidates disagree with captured local matches, or an expert native query returned an uncaptured ID. details->{verification} contains the detached "VERIFICATION REPORT" in LibTmux::Server. The cause may be concurrent change, a translation defect or backend semantics; the comparison does not identify it. "query_panes" in LibTmux::Server throws this for require or expert queries, while auto reports fallback through its optional observer.

StaleReference

A captured generation or contextual target no longer identifies the same resource.

Spawn

The executable could not start; dispatch is distinguished from command failure.

NoServer

The selected server cannot be reached.

Command

tmux reported nonzero status; result retains stdout/stderr/status.

Timeout

Execution exceeded its deadline; effects may already have occurred.

Cancelled

Execution was cancelled; cancellation does not roll back effects.

OutputLimit

Retained process output exceeded the configured bound.

Transport

Process supervision or result framing failed.

Codec

A tmux record or field could not be decoded.

NoSuchTarget

The selected stable target no longer exists. Native result diagnostics are retained. This differs from a stale generation and from an arbitrary command failure; acquire a new snapshot before choosing recovery.

Creation

A creation command succeeded but subsequent receipt decoding or capture failed. created returns a minimal generation-scoped entity handle when the command's receipt was decoded; other fields remain unloaded. cause preserves the original acquisition failure. dispatched is true. The returned handle permits explicit, generation-checked cleanup; absent receipts leave effects uncertain. See "new_session" in LibTmux::Server.

DIAGNOSTICS

message, path, entity, expected, received, matched_ids, count, result, dispatched, and details expose applicable fields. See "one" in LibTmux::Selection, "new" in LibTmux::Filter, and LibTmux::Server for failure boundaries.