From 0747ba504824cc6b35d7817f78a7572b370e292a Mon Sep 17 00:00:00 2001 From: Tim Culverhouse Date: Wed, 14 Aug 2024 10:24:36 -0500 Subject: [PATCH] docs: add lua api manpages Signed-off-by: Tim Culverhouse --- build.zig.zon | 4 +- docs/comlink.1.scd | 16 ++++++- docs/comlink.3.scd | 84 +++++++++++++++++++++++++++++++++++ docs/comlink_channel.3.scd | 32 +++++++++++++ docs/comlink_connection.3.scd | 60 +++++++++++++++++++++++++ 5 files changed, 192 insertions(+), 4 deletions(-) create mode 100644 docs/comlink.3.scd create mode 100644 docs/comlink_channel.3.scd create mode 100644 docs/comlink_connection.3.scd diff --git a/build.zig.zon b/build.zig.zon index f2fec35..901b373 100644 --- a/build.zig.zon +++ b/build.zig.zon @@ -19,8 +19,8 @@ .hash = "1220319a215975c0ac3d251b334bfb915765adf21f7e64904028b1ec5ebcf00ea3cd", }, .zzdoc = .{ - .url = "git+https://github.com/rockorager/zzdoc?ref=v0.2.0#4952c59aa4eaacb8e58c651022ca200d0def2e8c", - .hash = "12202a808ac9b32753cf4e093ef95a1c56aa595f7e3d331092ebd8883350c48da930", + .url = "git+https://github.com/rockorager/zzdoc?ref=main#c36a0e7557197e97d16bb2d52a4ea132c830add6", + .hash = "1220b7f4bf11d7cbf1077a84fbb1a2d342c63769590898f1ae17a4305f24a1246f63", }, }, .paths = .{""}, diff --git a/docs/comlink.1.scd b/docs/comlink.1.scd index 8516d23..57558b8 100644 --- a/docs/comlink.1.scd +++ b/docs/comlink.1.scd @@ -8,6 +8,13 @@ comlink - an IRC client *comlink* [options...] +# DESCRIPTION + +Comlink is an IRC client for your terminal. It employs many modern terminal +features, such as the Kitty Keyboard Protocol, mouse shapes, and OSC 8 +hyperlinks. It also uses many IRCv3 extensions to provide a modern chat +experience. + # OPTIONS *-v*, *--version* @@ -116,5 +123,10 @@ shortcuts shown here are the defaults. # AUTHORS -Maintained by Tim Culverhouse . Source code available at -https://git.sr.ht/~rockorager/comlink. +Written and maintained by Tim Culverhouse , assisted by +open source contributors. + +# REPORTING BUGS + +Bugs may be reported to the mailing list <~rockorager/comlink@lists.sr.ht> or at +https://github.com/rockorager/comlink. diff --git a/docs/comlink.3.scd b/docs/comlink.3.scd new file mode 100644 index 0000000..543ec06 --- /dev/null +++ b/docs/comlink.3.scd @@ -0,0 +1,84 @@ +comlink(3) + +# NAME + +comlink - primary lua module for use in comlink configuration + +# SYNOPSIS + +*local comlink = require*(_"comlink"_) + +*local conn = comlink.connect*(_config_) + +*local channel = comlink.selected_channel*() + +*comlink.log*(_msg_) + +*comlink.bind*(_key_, _action_) + +*comlink.notify*(_title_, _body_) + +*comlink.add_command*(_cmd_, _callback_) + +# DESCRIPTION + +The comlink module is the entrypoint into configuring and scripting comlink. +This module provides application level API calls. + +*comlink.connect* + Accepts a configuration table. This table defines the server + configuration. The table has the following required fields: + + - *server*: string, the server URL + - *user*: string, username used in SASL + - *nick*: string, nickname to identify as + - *password*: string, password to use in SASL + - *real_name*: string, user's real name + + The following optional fields are available: + + - *tls*: boolean (default=true), when true, use an encrypted connection + +*comlink.log* + Accepts a string and inserts a log statement into the comlink + logs. This can be helpful for debugging. + +*comlink.bind* + Accepts a string description of the _key_, as well an _action_. Keys may + include modifiers which must be of the form *shift*, *alt*, *ctrl*, + *super*, *hyper*, or *meta*. Named keys may be used as well, for example + *f1* or *tab*. To add a modifier to a key use a *+*, for example + "*ctrl+a*". An _action_ can be either a string or a lua function. + Available string actions are: + + - *next_channel* + - *prev_channel* + - *quit* + - *redraw* + +*comlink.notify* + Accepts two strings: the first is the title of the notification and the + second is the body of the notification. This function produces a system + notification on terminals which support OSC 777. + +*comlink.add_command* + Adds the string _cmd_ as an available command in comlink. This command + will show up in the completion list as well. When invoked, the + _callback_ function will be called and receives the arguments from the + command line, with the command removed and whitespace stripped. + +# RETURN VALUES + +*comlink.connect* + Returns a *connection*. The connection represents a connection to a + single server. In the presence of the _soju.im/bouncer-networks_ + extension, discovered networks will inherit callbacks set on + *connection*. See *comlink_connection*(3). + +*comlink.selected_channel* + Returns a *channel*, or *nil* if no channel is selected. See + *comlink_channel*(3). + +# SEE ALSO + +*comlink*(1), *comlink_connection*(3), *comlink_channel*(3) diff --git a/docs/comlink_channel.3.scd b/docs/comlink_channel.3.scd new file mode 100644 index 0000000..f66c05e --- /dev/null +++ b/docs/comlink_channel.3.scd @@ -0,0 +1,32 @@ +comlink_channel(3) + +# NAME + +comlink_channel - a lua type representing an IRC channel + +# SYNOPSIS + +*local channel = comlink.selected_channel*() + +*local name = channel:name*() + +*channel:send_msg*(_msg_) + +# DESCRIPTION + +A *channel* represents an IRC channel. + +*channel:send_msg* + A method on *channel* which accepts a string (_msg_). _Msg_ is sent to + the *channel* using a *PRIVMSG* IRC command. Note that this is a method + call, using lua colon syntax. + +# RETURN VALUES + +*channel:name* + Returns a string which is the name of the channel. Note that this is a + method call, using lua colon syntax. + +# SEE ALSO + +*comlink*(1), *comlink*(3) diff --git a/docs/comlink_connection.3.scd b/docs/comlink_connection.3.scd new file mode 100644 index 0000000..d90006b --- /dev/null +++ b/docs/comlink_connection.3.scd @@ -0,0 +1,60 @@ +comlink_connection(3) + +# NAME + +comlink_connection - a lua type representing a connection to an IRC server + +# SYNOPSIS + +*local conn = comlink.connect*(_config_) + +*conn.on_connect = function*(_conn_) + +*conn.on_message = function*(_channel_, _sender_, _msg_) + +*local name = conn.name*() + +*conn.join*(_channel_) + + + +# DESCRIPTION + +A *connection* represents the connection to the IRC server. A *connection* is +received after calling *comlink.connect*, which posts an event to connect to the +server. The entire lua file is executed prior to the connection occuring. This +behavior allows setting of callbacks on the connection after calling connect. +All callbacks are called from the main thread, and will block the event loop +until they return. + +*conn.on_connect* + A callback which receives the *connection* object. This callback is + called when comlink receives a *RPL_WELCOME* command from the server. An + example usage is to join channels after a connection has been + established. The callback receives a *connection* object because in the + presence of _soju.im/bouncer-networks_, networks may be discovered that + the user never configured. These discovered networks will inherit the + callbacks from the bouncer connection. Users of this callback may want + to perform different actions based on the *connection*, which is best + verified using the *name* function. + +*conn.on_message* + A callback which is called after any *PRIVMSG* or *NOTICE* is received + on the *connection*. The callback receives the channel, the sender, and + the content of the message - all as strings. The channel may be a + nickname in the case of a direct message. + +*conn.join* + Accepts a string as the channel name to join. This performs the IRC + command *JOIN*. + +# RETURN VALUES + +*conn.name* + Returns a string which is the name of the connection. This is usually + the URL, but may be something else if it is a discovered network from a + bouncer. + +# SEE ALSO + +*comlink*(1), *comlink*(3) -- 2.51.2