1 ! Copyright (C) 2009 Bruno Deferrari
2 ! See http://factorcode.org/license.txt for BSD license.
3 USING: help.markup help.syntax quotations kernel
4 irc.messages irc.messages.base irc.messages.parser irc.client.chats ;
7 HELP: connect-irc "Connecting to an irc server"
8 { $values { "irc-client" "an irc client object" } }
9 { $description "Connects and logins " { $link irc-client } " using the settings specified on its " { $link irc-profile } "." } ;
11 HELP: attach-chat "Chatting with irc channels/users/etc"
12 { $values { "irc-chat" "an irc chat object" } { "irc-client" "an irc client object" } }
13 { $description "Registers " { $snippet "irc-chat" } " with " { $snippet "irc-client" } " and starts listening." } ;
15 HELP: detach-chat "Stop an unregister chat"
16 { $values { "irc-chat" "an irc chat object" } }
17 { $description "Unregisters " { $snippet "irc-chat" } " from " { $snippet "irc-client" } " and stops listening. This is how you part from a channel." } ;
19 HELP: terminate-irc "Terminates an irc client"
20 { $values { "irc-client" "an irc client object" } }
21 { $description "Terminates all activity by " { $link irc-client } " cleaning up resources and notifying chats." } ;
23 HELP: speak "Sends a message through a chat"
24 { $values { "message" "a string or irc message object" } { "irc-chat" "an irc chat object" } }
25 { $description "Sends " { $snippet "message" } " through " { $snippet "irc-chat" } ". Strings are automatically promoted to privmsg objects." } ;
27 HELP: hear "Reads a message from a chat"
28 { $values { "irc-chat" "an irc chat object" } { "message" "an irc message object" } }
29 { $description "Reads " { $snippet "message" } " from " { $snippet "irc-chat" } "." } ;
31 ARTICLE: "irc.client" "IRC Client"
32 "An IRC Client library"
33 { $heading "IRC objects:" }
34 { $subsection irc-client }
35 { $heading "Chat objects:" }
36 { $subsection irc-server-chat }
37 { $subsection irc-channel-chat }
38 { $subsection irc-nick-chat }
39 { $heading "Setup objects:" }
40 { $subsection irc-profile }
42 { $subsection connect-irc }
43 { $subsection terminate-irc }
44 { $subsection attach-chat }
45 { $subsection detach-chat }
48 { $heading "IRC messages" }
49 "Some of the RFC defined irc messages as objects:"
51 { { $link irc-message } "base of all irc messages" }
52 { { $link rpl-welcome } "logged in to server" }
53 { { $link ping } "ping message" }
54 { { $link join } "channel join" }
55 { { $link part } "channel part" }
56 { { $link quit } "quit from irc" }
57 { { $link privmsg } "private message (to client or channel)" }
58 { { $link kick } "kick from channel" }
59 { { $link rpl-names } "list of participants in channel" }
60 { { $link rpl-nickname-in-use } "chosen nick is in use by another client" }
61 { { $link notice } "notice message" }
62 { { $link mode } "mode change" }
63 { { $link unhandled } "uninmplemented/unhandled message" }
66 { $heading "Special messages" }
67 "Some special messages that are created by the library and not by the irc server."
69 { { $link irc-chat-end } "sent to a chat when it has been detached from the client, the chat should stop after it receives this message. " }
70 { { $link irc-end } " sent when the client isn't running anymore, chats should stop after it receives this message." }
71 { { $link irc-disconnected } " sent to notify chats that connection was lost." }
72 { { $link irc-connected } " sent to notify chats that a connection with the irc server was established." } }
74 { $heading "Example:" }
76 "USING: irc.client irc.client.chats ;"
79 "! Create the profile and client objects"
80 "\"irc.freenode.org\" irc-port \"mybot123\" f <irc-profile> <irc-client> bot set"
81 "! Connect to the server"
83 "! Create a channel chat"
84 "\"#mychannel123\" <irc-channel-chat> mychannel set"
85 "! Register and start chat (this joins the channel)"
86 "mychannel get bot get attach-chat"
87 "! Send a message to the channel"
88 "\"Hello World!\" mychannel get speak"
89 "! Read a message from the channel"