rockorager.dev
an experimental irc client
docs: add lua api manpages
Signed-off-by: Tim Culverhouse <tim@timculverhouse.com>
+2
-2
build.zig.zon
+2
-2
build.zig.zon
···
19
19
.hash = "1220319a215975c0ac3d251b334bfb915765adf21f7e64904028b1ec5ebcf00ea3cd",
20
20
},
21
21
.zzdoc = .{
22
-
.url = "git+https://github.com/rockorager/zzdoc?ref=v0.2.0#4952c59aa4eaacb8e58c651022ca200d0def2e8c",
23
-
.hash = "12202a808ac9b32753cf4e093ef95a1c56aa595f7e3d331092ebd8883350c48da930",
22
+
.url = "git+https://github.com/rockorager/zzdoc?ref=main#c36a0e7557197e97d16bb2d52a4ea132c830add6",
23
+
.hash = "1220b7f4bf11d7cbf1077a84fbb1a2d342c63769590898f1ae17a4305f24a1246f63",
24
24
},
25
25
},
26
26
.paths = .{""},
+14
-2
docs/comlink.1.scd
+14
-2
docs/comlink.1.scd
···
8
8
9
9
*comlink* [options...]
10
10
11
+
# DESCRIPTION
12
+
13
+
Comlink is an IRC client for your terminal. It employs many modern terminal
14
+
features, such as the Kitty Keyboard Protocol, mouse shapes, and OSC 8
15
+
hyperlinks. It also uses many IRCv3 extensions to provide a modern chat
16
+
experience.
17
+
11
18
# OPTIONS
12
19
13
20
*-v*, *--version*
···
116
123
117
124
# AUTHORS
118
125
119
-
Maintained by Tim Culverhouse <tim@timculverhouse.com>. Source code available at
120
-
https://git.sr.ht/~rockorager/comlink.
126
+
Written and maintained by Tim Culverhouse <tim@timculverhouse.com>, assisted by
127
+
open source contributors.
128
+
129
+
# REPORTING BUGS
130
+
131
+
Bugs may be reported to the mailing list <~rockorager/comlink@lists.sr.ht> or at
132
+
https://github.com/rockorager/comlink.
+84
docs/comlink.3.scd
+84
docs/comlink.3.scd
···
1
+
comlink(3)
2
+
3
+
# NAME
4
+
5
+
comlink - primary lua module for use in comlink configuration
6
+
7
+
# SYNOPSIS
8
+
9
+
*local comlink = require*(_"comlink"_)
10
+
11
+
*local conn = comlink.connect*(_config_)
12
+
13
+
*local channel = comlink.selected_channel*()
14
+
15
+
*comlink.log*(_msg_)
16
+
17
+
*comlink.bind*(_key_, _action_)
18
+
19
+
*comlink.notify*(_title_, _body_)
20
+
21
+
*comlink.add_command*(_cmd_, _callback_)
22
+
23
+
# DESCRIPTION
24
+
25
+
The comlink module is the entrypoint into configuring and scripting comlink.
26
+
This module provides application level API calls.
27
+
28
+
*comlink.connect*
29
+
Accepts a configuration table. This table defines the server
30
+
configuration. The table has the following required fields:
31
+
32
+
- *server*: string, the server URL
33
+
- *user*: string, username used in SASL
34
+
- *nick*: string, nickname to identify as
35
+
- *password*: string, password to use in SASL
36
+
- *real_name*: string, user's real name
37
+
38
+
The following optional fields are available:
39
+
40
+
- *tls*: boolean (default=true), when true, use an encrypted connection
41
+
42
+
*comlink.log*
43
+
Accepts a string and inserts a log statement into the comlink
44
+
logs. This can be helpful for debugging.
45
+
46
+
*comlink.bind*
47
+
Accepts a string description of the _key_, as well an _action_. Keys may
48
+
include modifiers which must be of the form *shift*, *alt*, *ctrl*,
49
+
*super*, *hyper*, or *meta*. Named keys may be used as well, for example
50
+
*f1* or *tab*. To add a modifier to a key use a *+*, for example
51
+
"*ctrl+a*". An _action_ can be either a string or a lua function.
52
+
Available string actions are:
53
+
54
+
- *next_channel*
55
+
- *prev_channel*
56
+
- *quit*
57
+
- *redraw*
58
+
59
+
*comlink.notify*
60
+
Accepts two strings: the first is the title of the notification and the
61
+
second is the body of the notification. This function produces a system
62
+
notification on terminals which support OSC 777.
63
+
64
+
*comlink.add_command*
65
+
Adds the string _cmd_ as an available command in comlink. This command
66
+
will show up in the completion list as well. When invoked, the
67
+
_callback_ function will be called and receives the arguments from the
68
+
command line, with the command removed and whitespace stripped.
69
+
70
+
# RETURN VALUES
71
+
72
+
*comlink.connect*
73
+
Returns a *connection*. The connection represents a connection to a
74
+
single server. In the presence of the _soju.im/bouncer-networks_
75
+
extension, discovered networks will inherit callbacks set on
76
+
*connection*. See *comlink_connection*(3).
77
+
78
+
*comlink.selected_channel*
79
+
Returns a *channel*, or *nil* if no channel is selected. See
80
+
*comlink_channel*(3).
81
+
82
+
# SEE ALSO
83
+
84
+
*comlink*(1), *comlink_connection*(3), *comlink_channel*(3)
+32
docs/comlink_channel.3.scd
+32
docs/comlink_channel.3.scd
···
1
+
comlink_channel(3)
2
+
3
+
# NAME
4
+
5
+
comlink_channel - a lua type representing an IRC channel
6
+
7
+
# SYNOPSIS
8
+
9
+
*local channel = comlink.selected_channel*()
10
+
11
+
*local name = channel:name*()
12
+
13
+
*channel:send_msg*(_msg_)
14
+
15
+
# DESCRIPTION
16
+
17
+
A *channel* represents an IRC channel.
18
+
19
+
*channel:send_msg*
20
+
A method on *channel* which accepts a string (_msg_). _Msg_ is sent to
21
+
the *channel* using a *PRIVMSG* IRC command. Note that this is a method
22
+
call, using lua colon syntax.
23
+
24
+
# RETURN VALUES
25
+
26
+
*channel:name*
27
+
Returns a string which is the name of the channel. Note that this is a
28
+
method call, using lua colon syntax.
29
+
30
+
# SEE ALSO
31
+
32
+
*comlink*(1), *comlink*(3)
+60
docs/comlink_connection.3.scd
+60
docs/comlink_connection.3.scd
···
1
+
comlink_connection(3)
2
+
3
+
# NAME
4
+
5
+
comlink_connection - a lua type representing a connection to an IRC server
6
+
7
+
# SYNOPSIS
8
+
9
+
*local conn = comlink.connect*(_config_)
10
+
11
+
*conn.on_connect = function*(_conn_)
12
+
13
+
*conn.on_message = function*(_channel_, _sender_, _msg_)
14
+
15
+
*local name = conn.name*()
16
+
17
+
*conn.join*(_channel_)
18
+
19
+
20
+
21
+
# DESCRIPTION
22
+
23
+
A *connection* represents the connection to the IRC server. A *connection* is
24
+
received after calling *comlink.connect*, which posts an event to connect to the
25
+
server. The entire lua file is executed prior to the connection occuring. This
26
+
behavior allows setting of callbacks on the connection after calling connect.
27
+
All callbacks are called from the main thread, and will block the event loop
28
+
until they return.
29
+
30
+
*conn.on_connect*
31
+
A callback which receives the *connection* object. This callback is
32
+
called when comlink receives a *RPL_WELCOME* command from the server. An
33
+
example usage is to join channels after a connection has been
34
+
established. The callback receives a *connection* object because in the
35
+
presence of _soju.im/bouncer-networks_, networks may be discovered that
36
+
the user never configured. These discovered networks will inherit the
37
+
callbacks from the bouncer connection. Users of this callback may want
38
+
to perform different actions based on the *connection*, which is best
39
+
verified using the *name* function.
40
+
41
+
*conn.on_message*
42
+
A callback which is called after any *PRIVMSG* or *NOTICE* is received
43
+
on the *connection*. The callback receives the channel, the sender, and
44
+
the content of the message - all as strings. The channel may be a
45
+
nickname in the case of a direct message.
46
+
47
+
*conn.join*
48
+
Accepts a string as the channel name to join. This performs the IRC
49
+
command *JOIN*.
50
+
51
+
# RETURN VALUES
52
+
53
+
*conn.name*
54
+
Returns a string which is the name of the connection. This is usually
55
+
the URL, but may be something else if it is a discovered network from a
56
+
bouncer.
57
+
58
+
# SEE ALSO
59
+
60
+
*comlink*(1), *comlink*(3)