extra/irc/client/client-docs.factor

   1 USING: help.markup help.syntax quotations kernel ;
   2 IN: irc.client
   3
   4 HELP: irc-client "IRC Client object"
   5 "blah" ;
   6
   7 HELP: irc-server-listener "Listener for server messages unmanaged by other listeners"
   8 "blah" ;
   9
  10 HELP: irc-channel-listener "Listener for irc channels"
  11 "blah" ;
  12
  13 HELP: irc-nick-listener "Listener for irc users"
  14 "blah" ;
  15
  16 HELP: irc-profile "IRC Client profile object"
  17 "blah" ;
  18
  19 HELP: connect-irc "Connecting to an irc server"
  20 { $values { "irc-client" "an irc client object" } }
  21 { $description "Connects and logins " { $link irc-client } " using the settings specified on its " { $link irc-profile } "." } ;
  22
  23 HELP: add-listener "Listening to irc channels/users/etc"
  24 { $values { "irc-client" "an irc client object" } { "irc-listener" "an irc listener object" } }
  25 { $description "Registers " { $snippet "irc-listener" } " with " { $snippet "irc-client" } " and starts listening." } ;
  26
  27 HELP: terminate-irc "Terminates an irc client"
  28 { $values { "irc-client" "an irc client object" } }
  29 { $description "Terminates all activity by " { $link irc-client } " cleaning up resources and notifying listeners." } ;
  30
  31 ARTICLE: "irc.client" "IRC Client"
  32 "An IRC Client library"
  33 { $heading "IRC objects:" }
  34 { $subsection irc-client }
  35 { $heading "Listener objects:" }
  36 { $subsection irc-server-listener }
  37 { $subsection irc-channel-listener }
  38 { $subsection irc-nick-listener }
  39 { $heading "Setup objects:" }
  40 { $subsection irc-profile }
  41 { $heading "Words:" }
  42 { $subsection connect-irc }
  43 { $subsection terminate-irc }
  44 { $subsection add-listener }
  45 { $heading "IRC messages" }
  46 "Some of the RFC defined irc messages as objects:"
  47 { $table
  48   { { $link irc-message } "base of all irc messages" }
  49   { { $link logged-in } "logged in to server" }
  50   { { $link ping } "ping message" }
  51   { { $link join } "channel join" }
  52   { { $link part } "channel part" }
  53   { { $link quit } "quit from irc" }
  54   { { $link privmsg } "private message (to client or channel)" }
  55   { { $link kick } "kick from channel" }
  56   { { $link roomlist } "list of participants in channel" }
  57   { { $link nick-in-use } "chosen nick is in use by another client" }
  58   { { $link notice } "notice message" }
  59   { { $link mode } "mode change" }
  60   { { $link unhandled } "uninmplemented/unhandled message" }
  61   }
  62 { $heading "Special messages" }
  63 "Some special messages that are created by the library and not by the irc server."
  64 { $table
  65   { { $link irc-end } " sent when the client isn't running anymore, listeners should stop after this." }
  66   { { $link irc-disconnected } " sent to notify listeners that connection was lost." }
  67   { { $link irc-connected } " sent to notify listeners that a connection with the irc server was established." } }
  68
  69 { $heading "Example:" }
  70 { $code
  71   "USING: irc.client concurrency.mailboxes ;"
  72   "SYMBOL: bot"
  73   "SYMBOL: mychannel"
  74   "! Create the profile and client objects"
  75   "\"irc.freenode.org\" irc-port \"mybot123\" f <irc-profile> <irc-client> bot set"
  76   "! Connect to the server"
  77   "bot get connect-irc"
  78   "! Create a channel listener"
  79   "\"#mychannel123\" <irc-channel-listener> mychannel set"
  80   "! Register and start listener (this joins the channel)"
  81   "bot get mychannel get add-listener"
  82   "! Send a message to the channel"
  83   "\"what's up?\" mychannel get out-messages>> mailbox-put"
  84   "! Read a message from the channel"
  85   "mychannel get in-messages>> mailbox-get"
  86 }
  87   ;
  88
  89 ABOUT: "irc.client"