Module glirc
Library for interacting with the client state
This module provides client-specific hooks back into the glirc client.
Through this library scripts can send messages, check modes, and more.
Info:
- Copyright: Eric Mertens 2018
- License: ISC
- Author: Eric Mertens
Functions
send_message (network, command, ...) | Send an IRC command on a connected network. |
inject_chat (network, source, target, message) | Add a message to a chat window as though it was said by the given user. |
print (message) | Print a message to the client console |
error (message) | Print an error message to the client console |
list_networks () | Generate a list of names of connected networks. |
list_channels (network) | List the connected channels for a given network |
list_channel_users (network, channel) | List the users in a channel |
user_account (network, nick) | Determine the services account for a given nickname |
user_channel_modes (network, channel, nick) | Return the mode sigils for a user on a channel (e.g. |
my_nick (network) | Return the client's nickname on a particular network |
mark_seen (network, channel) | Mark a client window seen cleaning the unread message counter. |
clear_window (network, channel) | Clear all message from a client window. |
current_focus () | Get currently focused window. |
is_logged_on (network, nickname) | Determine if we are sure that the given user on the given network is currently connected. |
is_channel (network, target) | Test if target identifies a channel. |
resolve_path (path) | Resolve file path. |
set_timer (millis, callback) | Register a timer callback. |
identifier_cmp (identifier1, identifier2) | Case-insensitive comparison of two identifiers using IRC case map. |
Functions
- send_message (network, command, ...)
-
Send an IRC command on a connected network. Message tags are ignored
when sending a message.
Parameters:
Raises:
'too many parameters'
and'client failure'
Usage:
glirc.send_message('mynet', 'PRIVMSG', 'someone', 'Hello, Someone!')
- inject_chat (network, source, target, message)
-
Add a message to a chat window as though it was said by the given user.
Parameters:
- network string Network name
- source string Message source
- target string Target message window name
- message string Chat message body
Raises:
'client failure'
Usage:
glirc.inject_chat('mynet', 'nick!user@host', '#mychannel', 'An injected message') glirc.inject_chat('mynet', 'script output', 'somenick', 'Script output text')
- print (message)
-
Print a message to the client console
Parameters:
- message string Message to print to console
Usage:
glirc.print('This shows up on the * window')
- error (message)
-
Print an error message to the client console
Parameters:
- message string Message to print to console
Usage:
glirc.error('This shows up on the * window')
- list_networks ()
-
Generate a list of names of connected networks.
Returns:
-
{string,...}
A table of network names
Raises:
'client failure'
Usage:
glirc.list_networks() --> { 'mynet' }
- list_channels (network)
-
List the connected channels for a given network
Parameters:
- network string Network name
Returns:
-
{string,...}
A table of channel names
Raises:
'no such network'
Usage:
glirc.list_channels('mynet') --> { '#somechan', '#friends' }
- list_channel_users (network, channel)
-
List the users in a channel
Parameters:
Returns:
-
{string,...}
A table of nicknames
Raises:
'no such channel'
Usage:
glirc.list_channel_users('mynet', '#somechan') --> { 'chatter', 'quietguy' }
- user_account (network, nick)
-
Determine the services account for a given nickname
Parameters:
Returns:
-
optional string
Account name if known, otherwise
nil
Usage:
glirc.user_account('mynet', 'somenick') --> 'anaccount'
- user_channel_modes (network, channel, nick)
-
Return the mode sigils for a user on a channel (e.g. + or @)
Parameters:
Returns:
-
optional string
Sigils if on channel,
nil
otherwiseUsage:
glirc.user_channel_modes('mynet', '#somechan', 'an_op') --> '@'
- my_nick (network)
-
Return the client's nickname on a particular network
Parameters:
- network string Network name
Returns:
-
optional string
Client user's nickname if connected, otherwise
nil
Usage:
glirc.my_nick('mynet') --> 'mynick'
- mark_seen (network, channel)
-
Mark a client window seen cleaning the unread message counter. The
window name should be either a channel name or a user nickname.
Parameters:
Usage:
glirc.mark_seen('mynet', '#somechan') -- channel glirc.mark_seen('mynet', 'chatter') -- direct message
- clear_window (network, channel)
-
Clear all message from a client window. The window name should be
either a channel name or a user nickname.
Parameters:
Usage:
glirc.clear_window('mynet', '#somechan') -- channel glirc.clear_window('mynet', 'chatter') -- direct message
- current_focus ()
-
Get currently focused window.
The client window
*
is identified by twonil
values.The network windows are identified by a network name and
nil
target.The chat windows are identified by both a network name and a target name.
Returns:
Usage:
glirc.current_focus() --> nil, nil glirc.current_focus() --> 'mynet', nil glirc.current_focus() --> 'mynet', '#somechan'
- is_logged_on (network, nickname)
-
Determine if we are sure that the given user on the given network is
currently connected.
Parameters:
Returns:
-
boolean
User known to be connected
Usage:
glirc.is_logged_on('mynet', 'chatter')
- is_channel (network, target)
-
Test if target identifies a channel.
This provides a network-specific test to determine if a target name identifies a channel. While most networks use
#
to prefix channel names, there are other possibilities.Parameters:
Returns:
-
boolean
Target is a channel name
Usage:
glirc.is_channel('mynet', 'chatter') --> false glirc.is_channel('mynet', '#somechan') --> true glirc.is_channel('mynet', '&somechan') --> true
- resolve_path (path)
-
Resolve file path.
This provides access to the same path resolution logic used by the client configuration file. Relative paths are resolved from the directory containing the loaded configuration file.
~
is expanded to the home directory.Parameters:
- path string Path
Returns:
-
string
Absolute file path
Usage:
-- assuming configuration is at '/home/user/.config/glirc/config' glirc.resolve_path('relative/path') --> 'home/user/.config/glirc/relative/path' glirc.resolve_path('/absolute/path') --> '/abbsolute/path' glirc.resolve_path('~/path') --> '/home/user/path'
- set_timer (millis, callback)
-
Register a timer callback.
The given callback will be called after waiting at least the given number of milliseconds.
Parameters:
- millis integer Milliseconds delay
- callback func Callback function
Usage:
glirc.set_timer(10000, function() glirc.print('10 seconds has passed') end)
- identifier_cmp (identifier1, identifier2)
-
Case-insensitive comparison of two identifiers using IRC case map.
Return -1 when first identifier is "less than" the second.
Return 0 when first identifier is "equal to" the second.
Return 1 when first identifier is "greater than" the second.
Parameters:
Returns:
-
integer
Comparison result
Usage:
glirc.identifier_cmp('somenick', 'SOMENICK') --> 0 glirc.identifier_cmp('surprise{|}~', 'surprise[\\]^') --> 0 glirc.identifier_cmp('apple', 'zebra') --> -1 glirc.identifier_cmp('zebra', 'apple') --> 1