glirc Lua extension

• Index

Contents

• Functions

Libraries

• extension
• glirc

Manual

• Installing the Lua extension

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:

• network string Network name
• command string IRC Command
• ... string Command parameters (max 15)

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:

• network string Network name
• channel string Channel name

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:

• network string Network name
• nick string

  User nickname
  

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:

• network string Network name
• channel string Channel name
• nick string User nickname

Returns:

optional string Sigils if on channel, nil otherwise

Usage:

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:

• network string Network name
• channel string Window name

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:

• network string Network name
• channel string Window name

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 two nil 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:

1. optional string Network name
2. optional string Target name

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:

• network string Network name
• nickname string Nickname

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:

• network string Network name
• target string Target name

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:

• identifier1 string First identifier
• identifier2 string Second identifier

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