Functions
Generated from LuaLS function annotations.
Command and timer types
EasyBarAsyncToken
Opaque token identifying one asynchronous command in the current Lua runtime session. Do not persist tokens across config reloads or application restarts.
EasyBarCommandExitCode
Exit status returned by EasyBar command APIs. Normal process exit codes are preserved. EasyBar uses 124 for timeout, 65 for output-limit termination, 127 when an executable cannot be found, and 130 after cancellation.
EasyBarCommandCallback
Completion callback for asynchronous command APIs. It runs exactly once with combined stdout and stderr after the process exits or is terminated.
| Value |
fun(output:string, code:EasyBarCommandExitCode, metadata:EasyBarCommandMetadata) |
EasyBarTimerCallback
One-shot callback scheduled by easybar.after(...).
EasyBarCommandOptions
Modifiers: exact.
Per-call execution and diagnostic options for easybar.exec(...), easybar.exec_async(...), and easybar.spawn_async(...). Omitted execution-limit fields use the current [app.lua_commands] defaults.
| Property |
Type |
Description |
timeout_seconds (optional) |
number |
Hard timeout in seconds. Must be greater than zero. |
max_output_bytes (optional) |
integer |
Maximum combined stdout and stderr bytes. Must be a positive integer. |
raw_output (optional) |
boolean |
Preserve output exactly, including trailing line endings. Defaults to false. |
log_operation (optional) |
string |
Optional human-readable operation name attached to command diagnostics. |
Modifiers: exact.
Metadata supplied with one completed EasyBar command.
| Property |
Type |
Description |
duration_ms |
integer |
Host-measured command duration in milliseconds. |
EasyBarTimerHandle
Modifiers: exact.
Cancellable one-shot timer returned by easybar.after(...). The handle belongs to the current Lua runtime session and becomes inactive after firing or cancellation.
| Property |
Type |
Description |
token |
string |
Opaque host timer token. Do not persist or modify it. |
API functions
EasyBar.add
Creates one EasyBar node and returns its handle. Use easybar.kind.item for simple widgets, easybar.kind.group for shared containers, and easybar.kind.row / easybar.kind.column for layout wrappers around child nodes. When interval and on_interval are provided, EasyBar runs on_interval on this widget's own repeating schedule without requiring an event subscription.
Parameters
| Name |
Type |
Description |
kind |
EasyBarKind |
Node kind, normally selected from easybar.kind. |
id |
string |
Widget-unique node id used for updates, events, and parent references. |
props (optional) |
EasyBarNodeProps |
Initial node properties merged with widget-local defaults. |
Returns
| Type |
Name |
Description |
EasyBarNodeHandle |
node |
Handle for local updates, subscriptions, and removal. |
EasyBar.clear_defaults
Clears previously configured widget defaults.
EasyBar.default
Sets per-widget default properties for future easybar.add(...) calls. Defaults apply only within the current widget file.
Parameters
| Name |
Type |
Description |
props |
EasyBarNodeProps |
Defaults merged into future nodes created by this widget file. |
EasyBar.exec
Runs one shell command synchronously through /bin/sh -lc. This blocks the Lua runtime until completion, so prefer it only for short, local commands. Output combines stdout and stderr. Trailing line endings are removed unless raw_output = true.
Parameters
| Name |
Type |
Description |
command |
string |
Shell source passed to /bin/sh -lc. |
options (optional) |
EasyBarCommandOptions |
Optional per-call limits; omitted fields use host defaults. |
Returns
| Type |
Name |
Description |
string |
output |
Combined stdout and stderr, optionally preserved exactly with raw_output. |
EasyBarCommandExitCode |
code |
Process exit status or an EasyBar termination status. |
EasyBar.exec_async
Runs one shell command asynchronously through /bin/sh -lc. Use this only when shell syntax such as pipes, redirection, expansion, or compound commands is required. The callback runs exactly once after normal exit, timeout, output-limit termination, launch failure, or cancellation.
Parameters
| Name |
Type |
Description |
command |
string |
Shell source passed to /bin/sh -lc. |
options |
EasyBarCommandOptions\|nil |
Optional per-call execution and diagnostic options, or nil to use host defaults. |
callback |
EasyBarCommandCallback |
Receives combined output, final exit status, and duration metadata. |
Returns
| Type |
Name |
Description |
EasyBarAsyncToken |
token |
Token accepted by easybar.cancel_async(...) while the command is pending. |
EasyBar.spawn_async
Runs one executable asynchronously without shell parsing or interpolation. The first array element is the executable; remaining elements are passed exactly as process arguments. Prefer this over easybar.exec_async(...) whenever shell behavior is not required.
Parameters
| Name |
Type |
Description |
arguments |
string[] |
Dense argument array whose first element is an executable name or path. |
options |
EasyBarCommandOptions\|nil |
Optional per-call execution and diagnostic options, or nil to use host defaults. |
callback |
EasyBarCommandCallback |
Receives combined output, final exit status, and duration metadata. |
Returns
| Type |
Name |
Description |
EasyBarAsyncToken |
token |
Token accepted by easybar.cancel_async(...) while the command is pending. |
EasyBar.after
Schedules one non-blocking, one-shot callback using a host-owned timer. The delay must be finite and non-negative. A zero delay schedules the callback asynchronously; it does not run inline before easybar.after(...) returns.
Parameters
| Name |
Type |
Description |
delay_seconds |
number |
Minimum delay in seconds before the callback becomes eligible to run. |
callback |
EasyBarTimerCallback |
Callback invoked at most once unless cancelled first. |
Returns
| Type |
Name |
Description |
EasyBarTimerHandle |
timer |
Handle used to cancel the pending callback. |
EasyBarTimerHandle:cancel
Cancels this timer if its callback has not fired yet.
Returns
| Type |
Name |
Description |
boolean |
cancelled |
true when a pending callback was cancelled; otherwise false. |
EasyBar.cancel_async
Requests cancellation of one pending asynchronous command and its process group. This function returns immediately. When cancellation succeeds, the original command callback runs after termination with exit status 130 and any output captured before the process stopped.
Parameters
| Name |
Type |
Description |
token |
EasyBarAsyncToken |
Token returned by easybar.exec_async(...) or easybar.spawn_async(...). |
Returns
| Type |
Name |
Description |
boolean |
pending |
true when the token was still pending and cancellation was requested; otherwise false. |
EasyBar.get
Returns a copy of one existing node's current property table.
Parameters
| Name |
Type |
Description |
id |
string |
Existing node id in the current widget runtime. |
Returns
| Type |
Name |
Description |
EasyBarNodeProps |
props |
Snapshot safe to inspect or modify locally. |
EasyBar.log
Writes one widget-scoped log line to the EasyBar host logger. Supported levels are trace, debug, info, warn, and error. Which messages are actually emitted depends on the host logging level.
Parameters
| Name |
Type |
Description |
level |
EasyBarLevel\|string |
Minimum severity for this message. |
... |
any |
Values converted to text and joined into one log message. |
EasyBar.remove
Removes one existing node and all of its descendants by id.
Parameters
| Name |
Type |
Description |
id |
string |
Existing node id in the current widget runtime. |
EasyBar.set
Merges properties into one existing node by id.
Parameters
| Name |
Type |
Description |
id |
string |
Existing node id in the current widget runtime. |
props |
EasyBarNodeProps |
Properties to merge; unspecified properties remain unchanged. |
EasyBar.subscribe
Subscribes one existing node to one or more event tokens by id.
Parameters
| Name |
Type |
Description |
id |
string |
Existing node id in the current widget runtime. |
events |
EasyBarEventToken\|EasyBarEventToken[] |
One event token or an array of tokens. |
handler |
EasyBarEventHandler |
Callback invoked when one subscribed event is delivered. |
Returns
| Type |
Name |
Description |
EasyBarSubscriptionHandle |
subscription |
Disposable registration handle. |
EasyBar.unset
Removes one or more nested properties from one existing node by id.
Parameters
| Name |
Type |
Description |
id |
string |
Existing node id in the current widget runtime. |
paths |
string\|string[] |
Dot-separated property path or array of paths to remove. |
EasyBarNodeHandle:get
Returns a copy of this node's current property table.
Returns
| Type |
Name |
Description |
EasyBarNodeProps |
props |
Snapshot safe to inspect or modify locally. |
EasyBarNodeHandle:remove
Removes this node and all of its descendants.
EasyBarNodeHandle:set
Merges properties into this node.
Parameters
| Name |
Type |
Description |
props |
EasyBarNodeProps |
Properties to merge; unspecified properties remain unchanged. |
EasyBarNodeHandle:subscribe
Subscribes this node to one or more event tokens. Interaction belongs to this node frame.
Parameters
| Name |
Type |
Description |
events |
EasyBarEventToken\|EasyBarEventToken[] |
One event token or an array of tokens. |
handler |
EasyBarEventHandler |
Callback invoked when one subscribed event is delivered. |
Returns
| Type |
Name |
Description |
EasyBarSubscriptionHandle |
subscription |
Disposable registration handle. |
EasyBarNodeHandle:unset
Removes one or more nested properties from this node.
Parameters
| Name |
Type |
Description |
paths |
string\|string[] |
Dot-separated property path or array of paths to remove. |
EasyBar.asset
Resolves a path relative to the current widget file.
Parameters
| Name |
Type |
Description |
path |
string |
Relative asset path, or an absolute path to preserve unchanged. |
Returns
| Type |
Name |
Description |
string |
resolved_path |
Filesystem path resolved for the current widget source. |
EasyBar.log.with_file
Creates a widget logger that writes normal EasyBar logs and appends to a file in easybar.log_dir. The file name must be a plain file name, not a path.
Parameters
| Name |
Type |
Description |
file_name |
string |
Plain file name created inside easybar.log_dir; paths are rejected. |
options (optional) |
EasyBarLogFileOptions |
Optional line prefix configuration. |
Returns
| Type |
Name |
Description |
EasyBarFileLogger |
logger |
Callable host-and-file logger with file utility methods. |
EasyBar.log.with_prefix
Creates a widget logger that prepends a stable prefix to normal EasyBar host logs.
Parameters
| Name |
Type |
Description |
prefix |
string |
Prefix added to every message from the returned logger. |
Returns
| Type |
Name |
Description |
EasyBarPrefixedLogger |
logger |
Callable prefixed host logger. |
EasyBarFileLogger.append
Appends raw text to the widget log file and adds a trailing newline when missing.
Parameters
| Name |
Type |
Description |
text |
any |
Value appended as text; one trailing newline is added when missing. |
Returns
| Type |
Name |
Description |
boolean |
ok |
Whether the write succeeded. |
string? |
error_message |
Failure detail when ok is false. |
EasyBarFileLogger.line
Appends one line to the widget log file.
Parameters
| Name |
Type |
Description |
text |
any |
Value appended as exactly one logical line. |
Returns
| Type |
Name |
Description |
boolean |
ok |
Whether the write succeeded. |
string? |
error_message |
Failure detail when ok is false. |
EasyBarFileLogger.tail
Returns the newest log lines as one newline-delimited string.
Parameters
| Name |
Type |
Description |
limit |
integer |
Maximum number of newest lines to return. |
Returns
| Type |
Name |
Description |
string |
text |
Newline-delimited tail content, or an empty string when unavailable. |
EasyBarFileLogger.trim
Keeps only the newest log lines in the widget log file.
Parameters
| Name |
Type |
Description |
limit |
integer |
Number of newest lines to retain. |
Returns
| Type |
Name |
Description |
boolean |
ok |
Whether the trim succeeded. |
string? |
error_message |
Failure detail when ok is false. |
EasyBarInbox.clear
Clears every current inbox item for one source.
Parameters
| Name |
Type |
Description |
source |
string |
Publisher name previously used with replace(...). |
Configures source-owned actions shown in the inbox popup header.
Parameters
| Name |
Type |
Description |
source |
string |
Stable publisher name used for context-action routing. |
configuration |
EasyBarInboxConfiguration |
Source-level action configuration. |
EasyBarInbox.on_action
Registers an action handler for one source.
Parameters
| Name |
Type |
Description |
source |
string |
Publisher name whose item actions should be delivered. |
handler |
fun(event:EasyBarInboxActionEvent) |
Callback invoked for matching item actions. |
Returns
| Type |
Name |
Description |
EasyBarSubscriptionHandle |
subscription |
Disposable registration handle. |
EasyBarInbox.on_context_action
Registers a source context-menu action handler.
Parameters
| Name |
Type |
Description |
source |
string |
Publisher name whose source actions should be delivered. |
handler |
fun(event:EasyBarInboxContextActionEvent) |
Callback invoked for matching source actions. |
Returns
| Type |
Name |
Description |
EasyBarSubscriptionHandle |
subscription |
Disposable registration handle. |
EasyBarInbox.replace
Atomically replaces every current inbox item for one source.
Parameters
| Name |
Type |
Description |
source |
string |
Stable publisher name used for grouping and action routing. |
items |
EasyBarInboxItem[] |
Complete current snapshot for this source. |
EasyBarSubscriptionHandle:dispose
Removes this subscription. Repeated calls return false.
Returns
| Type |
Name |
Description |
boolean |
removed |
Whether an active registration was removed. |
EasyBarSubscriptionHandle:unsubscribe
Alias for dispose().
Returns
| Type |
Name |
Description |
boolean |
removed |
Whether an active registration was removed. |