Module hilbish.messages

simplistic message passing

Added in v2.2.0

Introduction#

The messages interface defines a way for Hilbish-integrated commands, user config and other tasks to send notifications to alert the user.

A message starts out unread when it is sent with send. It stays unread until it is explicitly marked with read (by index) or readAll (every message at once). unreadCount and all reflect this state, so a prompt or statusline can show how many messages are waiting to be seen.

hilbish.messages.send{
	title = 'Build finished',
	text = 'go build exited with code 0',
	channel = 'build',
	icon = '✅'
}


print(hilbish.messages.unreadCount()) -- -> 1


for idx, msg in pairs(hilbish.messages.all()) do
	hilbish.messages.read(idx)
end
print(hilbish.messages.unreadCount()) -- -> 0

Functions#

hilbish.messages.all() -> table: Returns all messages as a table keyed by their index.
hilbish.messages.clear(): Deletes all messages.
hilbish.messages.delete(idx): Deletes the message at idx. Errors if the index is invalid.
hilbish.messages.read(idx): Marks a message at idx as read.
hilbish.messages.readAll(): Marks all messages as read.
hilbish.messages.send(message): Sends a notification message and emits the hilbish.notification signal.
hilbish.messages.unreadCount() -> integer: Returns the count of unread messages.

all#

hilbish.messages.all() -> table

Returns all messages as a table keyed by their index.

Returns#

table All stored messages, keyed by message index.

clear#

hilbish.messages.clear()

Deletes all messages.

delete#

hilbish.messages.delete(idx)

Deletes the message at idx. Errors if the index is invalid.

Parameters#

number idx Index of the message to delete.

read#

hilbish.messages.read(idx)

Marks a message at idx as read.

Parameters#

number idx Index of the message to mark as read.

readAll#

hilbish.messages.readAll()

Marks all messages as read.

send#

hilbish.messages.send(message)

Sends a notification message and emits the hilbish.notification signal. Do not emit the hilbish.notification signal directly.

Parameters#

hilbish.message message The message to send.

unreadCount#

hilbish.messages.unreadCount() -> integer

Returns the count of unread messages.

Returns#

integer Number of messages that have not been marked as read.

Types#

hilbish.message#

Represents a Hilbish message.

Object Properties#

string? icon: Unicode (preferably standard emoji) icon for the message notification.
string title: Title of the message (like an email subject).
string text: Contents of the message.
string channel: Short identifier of the message. hilbish and hilbish.* is preserved for internal Hilbish messages.
string summary: A short summary of the message.
integer? index: Index assigned to the message once sent with send, used to reference it in read and delete.
boolean? read: Whether the full message has been read or not.

Methods#

hilbish.messageIcons#

Predefined icons for the icon field of a message. Any code sending notifications can use these, whether from user config or Hilbish itself.

Object Properties#

string INFO: Icon for informational messages.
string SUCCESS: Icon for success messages.
string WARN: Icon for warning messages.
string ERROR: Icon for error messages.