On this page

libtmux.neo._token_scope

Module: libtmux.neo
Package: libtmux
Source: src/libtmux/neo.py

_token_scope ( field_name : str ) → str function [source] ¶ function [source] ¶ _token_scope

Resolve a format token's scope from its name.

Returns "universal" for cross-scope tokens (e.g. version, socket_path, host). Returns "event" for runtime-only tokens that never appear in a list-* output (mouse, cursor, selection, popup). Returns "context" for tokens registered outside format.c's static table (only resolve in a specific command or mode context). Returns "pane" / "window" / "session" / "client" / "buffer" for scope-prefixed tokens.

Fields that don't match any prefix, override, or known-token table fall back to "unknown". "unknown" is intentionally absent from every SCOPES_BY_LIST_CMD entry, so an unclassified field is excluded from every list-* -F template — preventing a future untracked field from being silently emitted under a list command where it might crash older tmux. Add such a field to _SCOPE_OVERRIDES (or the appropriate prefix / known-token table) to admit it.

Examples

>>> from libtmux.neo import _token_scope
>>> _token_scope("pane_id")
'pane'
>>> _token_scope("window_zoomed_flag")
'window'
>>> _token_scope("client_name")
'client'
>>> _token_scope("version")
'universal'
>>> _token_scope("mouse_x")
'event'

Tokens whose name doesn't carry a scope prefix can still be scope-gated via _SCOPE_OVERRIDES (verified against tmux's format_cb_*). The override also corrects prefix-misclassified tokens — e.g. mouse_all_flag is a per-pane mode bit, not a runtime mouse event:

>>> _token_scope("mouse_all_flag")
'pane'
>>> _token_scope("active_window_index")
'session'

Context-only tokens (registered outside format.c's static table) route to the "context" scope and are excluded from every list-* -F template:

>>> _token_scope("command_list_alias")
'context'
>>> _token_scope("search_match")
'context'

Unclassified tokens fall back to "unknown", also excluded from every list command:

>>> _token_scope("libtmux_test_nonexistent_token")
'unknown'

0 declared, 0 inherited