Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/eazar001/irc_client

IRC client library for SWI Prolog
https://github.com/eazar001/irc_client

irc irc-client irc-protocol prolog swi-prolog

Last synced: 3 months ago
JSON representation

IRC client library for SWI Prolog

Awesome Lists containing this project

README 

        

# What this is



This is a low level IRC client library for making anything related to

IRC usage. For example, one can make a traditional bot, conversation

analyzer, simple logging system, statistics tracker, or even a full

blown IRC Chat application.



# What this does



This is a layer of abstraction over the IRC protocol. It helps you

establish connections to multiple servers and channels, using different

nicknames. Each connection will run in separate threads that contain

aliases that you give to them. The job of irc_client is to handle the

bookkeeping of all the specs for each server connection, and handle the

streaming of IRC server relayed messages to event handlers that you

declare. This does NOT maintain persistent connections, or even display

the text for you. However, this is simple enough to do by asserting 

event handlers. See the `examples.pl` file in the examples folder for a

clue on how to get this done. Also, an example of an IRC bot that uses

this library can be found at: https://github.com/eazar001/yesbot



# How do I use this?



```prolog

% sends a message in the ##prolog channel saying "hello world", using

% the connection with the alias, "freenode".

?- priv_msg(freenode, "hello world", "##prolog").



% sends a message to the user "nick02" with "hello" and "world", each

% on separate lines, on the connection with the alias, "efnet".

?- priv_msg(efnet, "hello\nworld", "nick02").



% sends an invitation to ##math, for freenode user, "user001"

?- send_msg(freenode, invite, "user001", "##math").



% disconnects from server on the efnet connection alias.

?- send_msg(efnet, quit).

```



One of the most important predicates is `priv_msg/N`. This is needed

for sending private messages to channels, or to individual users.



* priv_msg(+Id, +Text, +Recipient)

  This will send Text to the Recipient, on the connection Id. Id is

  an atom; Text and Recipient are strings. If the character limit is

  exceeded, the text will automatically be segmented into several

  messages, until the full message is delivered.



* priv_msg(+Id, +Text, +Recipient, :Options).

  Here one has special options. `auto_nl(Boolean)` where Boolean can be

  specified as true or false. If true, messages that are too large

  will be automatically segmented into multiple messages. `at_most(N)`,

  where N represents the number of lines that will be sent (at most).

  This is useful for rate limiting.



Another important group of predicates is `send_msg/N`. This group of

predicates is responsible for sending certain types of messages that

are responsible for carrying out various IRC actions. A basic

understanding of IRC protocols is required to use these. The arity (N)

of send_msg/N, at this point, ranges from 2 to 4. ALL OF THESE commands

must have the first argument as the connection ID to send the message

on. The format for these commands are listed below:



* send_msg(ID, admin, "target").

* send_msg(ID, away, "away message")

* send_msg(ID, help)

* send_msg(ID, info).

* send_msg(ID, links).

* send_msg(ID, lusers, "##channel").

* send_msg(ID, names, "##channel").

* send_msg(ID, oper, "username", "pass").

* send_msg(ID, rules).

* send_msg(ID, userip, "nick").

* send_msg(ID, users).

* send_msg(ID, who_op, "##channel").

* send_msg(ID, who_ops).

* send_msg(ID, whois, "nick").

* send_msg(ID, whowas, "nick").

* send_msg(ID, notice, "message", "chan or nick").

* send_msg(ID, time, "server").

* send_msg(ID, kick, "##channel", "user").

* send_msg(ID, invite, "user", "##channel").

* send_msg(ID, topic, "##channel", "topic message").

* send_msg(ID, quit).

* send_msg(ID, nick, "nickname").

* send_msg(ID, join, "channel").



There is an examples folder containing examples (with comments) that

demonstrate how this is meant to be used.



# What else?



I will add more commands and features as I find time to work on this,

but for now ... pull requests are very much welcome.



At the time of writing this, this library is being used for one of the

bots in ##prolog (Yesbot). There's another bot that's used for

interactive prolog commands in-channel (PrologMUD). The second bot can

be found at https://github.com/TeamSPoon/MUD_ircbot