extra/irc/client/client-docs.factor

   1 ! Copyright (C) 2009 Bruno Deferrari
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: help.markup help.syntax irc.client.chats irc.messages
   4 irc.messages.base ;
   5 IN: irc.client
   6
   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 } "." } ;
  10
  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." } ;
  14
  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." } ;
  18
  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." } ;
  22
  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." } ;
  26
  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" } "." } ;
  30
  31 ARTICLE: "irc.client" "IRC Client"
  32 "An IRC Client library"
  33 { $heading "IRC objects:" }
  34 { $subsections irc-client }
  35 { $heading "Chat objects:" }
  36 { $subsections
  37     irc-server-chat
  38     irc-channel-chat
  39     irc-nick-chat
  40 }
  41 { $heading "Setup objects:" }
  42 { $subsections irc-profile }
  43 { $heading "Words:" }
  44 { $subsections
  45     connect-irc
  46     terminate-irc
  47     attach-chat
  48     detach-chat
  49     hear
  50     speak
  51 }
  52 { $heading "IRC messages" }
  53 "Some of the RFC defined irc messages as objects:"
  54 { $table
  55   { { $link irc-message } "base of all irc messages" }
  56   { { $link rpl-welcome } "logged in to server" }
  57   { { $link ping } "ping message" }
  58   { { $link join } "channel join" }
  59   { { $link part } "channel part" }
  60   { { $link quit } "quit from irc" }
  61   { { $link privmsg } "private message (to client or channel)" }
  62   { { $link kick } "kick from channel" }
  63   { { $link rpl-names } "list of participants in channel" }
  64   { { $link rpl-nickname-in-use } "chosen nick is in use by another client" }
  65   { { $link notice } "notice message" }
  66   { { $link mode } "mode change" }
  67   { { $link unhandled } "uninmplemented/unhandled message" }
  68   }
  69
  70 { $heading "Special messages" }
  71 "Some special messages that are created by the library and not by the irc server."
  72 { $table
  73   { { $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." }
  74   { { $link irc-end } " sent when the client isn't running anymore, the chat should stop after it receives this message." }
  75   { { $link irc-disconnected } " sent to notify chats that connection was lost." }
  76   { { $link irc-connected } " sent to notify chats that a connection with the irc server was established." } }
  77
  78 { $heading "Example:" }
  79 { $code
  80   "USING: irc.client irc.client.chats ;"
  81   "SYMBOL: bot"
  82   "SYMBOL: mychannel"
  83   "! Create the profile and client objects"
  84   "\"irc.libera.chat\" irc-port \"mybot123\" f <irc-profile> <irc-client> bot set"
  85   "! Connect to the server"
  86   "bot get connect-irc"
  87   "! Create a channel chat"
  88   "\"#mychannel123\" <irc-channel-chat> mychannel set"
  89   "! Register and start chat (this joins the channel)"
  90   "mychannel get bot get attach-chat"
  91   "! Send a message to the channel"
  92   "\"Hello World!\" mychannel get speak"
  93   "! Read a message from the channel"
  94   "mychannel get hear"
  95 }
  96   ;
  97
  98 ABOUT: "irc.client"