extra/pop3/pop3-docs.factor

   1 ! Copyright (C) 2009 Elie Chaftari.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: arrays assocs help.markup help.syntax math sequences
   4 strings ;
   5 IN: pop3
   6
   7 HELP: <pop3-account>
   8 { $values
   9
  10     { "pop3-account" pop3-account }
  11 }
  12 { $description "creates a " { $link pop3-account } " object with defaults for the port and timeout slots." } ;
  13
  14 HELP: account
  15 { $values
  16
  17     { "pop3-account" pop3-account }
  18 }
  19 { $description "You only need to call " { $link connect } " after calling this word to reconnect to the latest accessed POP3 account." }
  20 { $examples
  21     { $code
  22     "account connect"
  23     ""
  24     }
  25 } ;
  26
  27 HELP: >user
  28 { $values
  29     { "name" "userID of the account" }
  30 }
  31 { $description "Sends the userID of the account on the POP3 server (this could be the full e-mail address)" $nl
  32 "This must be the first command after " { $link connect } " if username and password have not been set with " { $link <pop3-account> } "."
  33 } ;
  34
  35 HELP: >pwd
  36 { $values
  37     { "password" "password for the userID" }
  38 }
  39 { $description "Sends the clear-text password for the userID. The password may be case sensitive. This must be the next command after " { $link >user } "." } ;
  40
  41 HELP: capa
  42 { $values
  43
  44     { "array" array }
  45 }
  46 { $description "Queries the mail server capabilities, as described in RFC 2449. It is advised to check for command support before calling the appropriate words (e.g. TOP UIDL)." } ;
  47
  48 HELP: connect
  49 { $values
  50     { "pop3-account" pop3-account }
  51 }
  52 { $description "Opens a network connection to the pop3 mail server with the settings given in the pop3-account slots." }
  53 { $examples
  54     { $code "USING: accessors pop3 ;"
  55     "<pop3-account>"
  56     "    \"pop.yourisp.com\" >>host"
  57     "    \"username@yourisp.com\" >>user"
  58     "    \"pass123\" >>pwd"
  59     "connect"
  60     ""
  61     }
  62 } ;
  63
  64 HELP: consolidate
  65 { $values
  66
  67     { "seq" sequence }
  68 }
  69 { $description "Builds a sequence of email tuples, iterating over each email top and consolidating its headers with its number, uidl, and size." } ;
  70
  71 HELP: delete
  72 { $values
  73     { "message#" fixnum }
  74 }
  75 { $description "This marks message number message# for deletion from the server. This is the way to get rid of a problem causing message. It is not actually deleted until the " { $link close } " word is issued. If you lose the connection to the mail server before calling the " { $link close } " word, the server should not delete any messages. Example: 3 delete" } ;
  76
  77 HELP: headers
  78 { $values
  79
  80     { "assoc" assoc }
  81 }
  82 { $description "Gathers and associates the From:, Subject:, and To: headers of each message." } ;
  83
  84 HELP: list
  85 { $values
  86
  87     { "assoc" assoc }
  88 }
  89 { $description "Lists each message with its number and size in bytes" } ;
  90
  91 HELP: pop3-account
  92 { $class-description "A POP3 account on a POP3 server. It has the following slots:"
  93     { $slots
  94         { "#" "The ephemeral ordinal number of the message." }
  95         { "host" "The name or IP address of the remote host to which a POP3 connection is required." }
  96         { "port" "The POP3 server port (defaults to 110)." }
  97         { "timeout" "Maximum time in minutes to wait for a response from the POP3 server (defaults to 1 minutes)." }
  98         { "user" "The userID of the account on the POP3 server." }
  99         { "pwd" { "The clear-text password for the userID." } }
 100         { "stream" { "The duplex input/output stream wrapping the POP3 session." } }
 101         { "capa" { "A list of the mail server capabilities." } }
 102         { "count" { "Number of messages in the mailbox." } }
 103         { "list" { "A list of every message with its number and size in bytes" } }
 104         { "uidls" { "The UIDL (Unique IDentification Listing) of every message in the mailbox together with its ordinal number." } }
 105         { "messages" { "A sequence of email tuples in the mailbox containing each email's headers, number, uidl, and size." } }
 106     }
 107 "The " { $slot "host" } " is required; the rest are either set by default or optional." $nl
 108 "The " { $slot "user" } " and " { $slot "pwd" } " must either be set before using " { $link connect } " or immediately after it with the " { $link >user } " and " { $link >pwd } " words."
 109 } ;
 110
 111 HELP: message
 112 { $class-description "An e-mail message having the following slots:"
 113     { $slots
 114         { "#" "The ephemeral ordinal number of the message." }
 115         { "uidl" "The POP3 UIDL (Unique IDentification Listing) of the message." }
 116         { "headers" "The From:, Subject:, and To: headers of the message." }
 117         { "from" "The sender of the message. An e-mail address." }
 118         { "to" "The recipients of the message." }
 119         { "subject" { "The subject of the message." } }
 120         { "size" { "The size of the message in octets." } }
 121     }
 122 } ;
 123
 124 HELP: close
 125 { $description "Deletes any messages marked for deletion, and then logs you off of the mail server. This is the last command to use." } ;
 126
 127 HELP: retrieve
 128 { $values
 129     { "message#" fixnum }
 130     { "seq" sequence }
 131 }
 132 { $description "Sends message number message# to you. You should prepare for some base64 decoding. You probably want to do this with a mailer." } ;
 133
 134 HELP: reset
 135 { $description "Resets the status of the remote POP3 server. This includes resetting the status of all messages to not be deleted." } ;
 136
 137 HELP: count
 138 { $values
 139
 140     { "n" fixnum }
 141 }
 142 { $description "Gets the number of messages in the mailbox." } ;
 143
 144 HELP: top
 145 { $values
 146     { "message#" fixnum } { "#lines" fixnum }
 147     { "seq" sequence }
 148 }
 149 { $description "Lists the header for message# and the first #lines of the message text. For example, 1 0 top would list just the headers for message 1, where as 1 5 top would list the headers and first 5 lines of the message text." } ;
 150
 151 HELP: uidl
 152 { $values
 153     { "message#" fixnum }
 154     { "uidl" string }
 155 }
 156 { $description "Gets the POP3 UIDL (Unique IDentification Listing) of the given message#." } ;
 157
 158 HELP: uidls
 159 { $values
 160
 161     { "assoc" assoc }
 162 }
 163 { $description "Gets the POP3 UIDL (Unique IDentification Listing) of every specific message in the mailbox together with its ordinal number. UIDL provides a mechanism that avoids numbering issues between POP3 sessions by assigning a permanent and unique ID for each message." } ;
 164
 165 ARTICLE: "pop3" "POP3 client library"
 166 "The " { $vocab-link "pop3" } " vocab implements a client interface to the POP3 protocol, enabling a Factor application to talk to POP3 servers. It allows interactive sessions similar to telnet ones to do maintenance on your mailbox on a POP3 mail server; to look at, and possibly delete, any problem causing message (e.g. too large, improperly formatted, etc.)." $nl
 167 "Word names do not necessarily map directly to POP3 commands defined in RFC1081 or RFC1939, although most commands are supported." $nl
 168 "This article assumes that you are familiar with the POP3 protocol."
 169 $nl
 170 "Connecting to the mail server:"
 171 { $subsections connect }
 172 "You need to construct a pop3-account tuple first, setting at least the host slot."
 173 { $subsections <pop3-account> }
 174 { $examples
 175     { $code "USING: accessors pop3 ;"
 176     "<pop3-account>"
 177     "    \"pop.yourisp.com\" >>host"
 178     "    \"username@yourisp.com\" >>user"
 179     "    \"pass123\" >>pwd"
 180     "connect"
 181     ""
 182     }
 183 }
 184 $nl
 185 "If you do not supply the username or password, you will need to call the " { $link >user } " and " { $link >pwd } " vocabs in this order after the " { $link connect } " vocab."
 186 { $examples
 187     { $code "USING: accessors pop3 ;"
 188     "<pop3-account>"
 189     "    \"pop.yourisp.com\" >>host"
 190     "connect"
 191     ""
 192     "\"username@yourisp.com\" >user"
 193     "\"pass123\" >pwd"
 194     ""
 195     }
 196 }
 197 $nl
 198 { $notes "Subsequent calls to the " { $link pop3-account } " thus created can be done by calling the " { $link account } " word. If you needed to reconnect to the same POP3 account after having called " { $link close } ", you only need to call " { $link account } " followed by " { $link connect } "." }
 199 $nl
 200 "Querying the mail server:"
 201 $nl
 202 "For its capabilities:"
 203 { $subsections capa }
 204 { $examples
 205     { $code
 206     "capa ."
 207     "{ \"CAPA\" \"TOP\" \"UIDL\" }"
 208     ""
 209     }
 210 }
 211 $nl
 212 "For the message count:"
 213 { $subsections count }
 214 { $examples
 215     { $code
 216     "count ."
 217     "2"
 218     ""
 219     }
 220 }
 221 $nl
 222 "For each message's size:"
 223 { $subsections list }
 224 { $examples
 225     { $code
 226     "list ."
 227     "H{ { 1 \"1006\" } { 2 \"747\" } }"
 228     ""
 229     }
 230 }
 231 $nl
 232 "For a specific message raw header, appropriate headers, or number of lines:"
 233 { $subsections top }
 234 { $examples
 235     { $code
 236     "1 0 top ."
 237     "<the raw-source of the message header is retrieved>"
 238     ""
 239     }
 240     { $code
 241     "1 5 top ."
 242     "<the raw-source of the message header and its first 5 lines are retrieved>"
 243     ""
 244     }
 245     { $code
 246     "1 0 top headers ."
 247     "H{"
 248     "    { \"From:\" \"from@mail.com\" }"
 249     "    { \"Subject:\" \"Re:\" }"
 250     "    { \"To:\" \"username@host.com\" }"
 251     "}"
 252     ""
 253     }
 254 }
 255 $nl
 256 "To consolidate all the messages of this account into a single association:"
 257 { $subsections consolidate }
 258 { $examples
 259     { $code
 260     "consolidate ."
 261 "{
 262         T{ message
 263             { # 1 }
 264             { uidl \"000000d547ac2fc2\" }
 265             { from \"from.first@mail.com\" }
 266             { to \"username@host.com\" }
 267             { subject \"First subject\" }
 268             { size \"1006\" }
 269         }
 270         T{ message
 271             { # 2 }
 272             { uidl \"000000d647ac2fc2\" }
 273             { from \"from.second@mail.com\" }
 274             { to \"username@host.com\" }
 275             { subject \"Second subject\" }
 276             { size \"747\" }
 277         }
 278 }"
 279     ""
 280     }
 281 }
 282 $nl
 283 "You may want to delete message #2 but want to make sure you are deleting the right one. You can check that message #2 has the uidl from the example above."
 284 { $subsections uidl }
 285 { $examples
 286     { $code
 287     "2 uidl ."
 288     "\"000000d647ac2fc2\""
 289     ""
 290     }
 291 }
 292 $nl
 293 "Now with your mind at rest, you can delete message #2. The message is marked for deletion."
 294 { $subsections delete }
 295 { $examples
 296     { $code
 297     "2 delete"
 298     ""
 299     }
 300 }
 301 $nl
 302 "The messages marked for deletion are actually deleted only when " { $link close } " is called. This should be the last command you issue."
 303 { $subsections close }
 304 { $examples
 305     { $code
 306     "close"
 307     ""
 308     }
 309 }
 310 { $notes "If you change your mind at any point, you can call " { $link reset } " to reset the status of all messages to not be deleted." } ;
 311
 312 ABOUT: "pop3"