basis/smtp/smtp-docs.factor

   1 ! Copyright (C) 2008 Doug Coleman.
   2 ! See http://factorcode.org/license.txt for BSD license.
   3 USING: accessors kernel quotations help.syntax help.markup
   4 io.sockets strings calendar ;
   5 IN: smtp
   6
   7 HELP: smtp-domain
   8 { $var-description "The name of the machine that is sending the email.  This variable will be filled in by the " { $link host-name } " word if not set by the user." } ;
   9
  10 HELP: smtp-server
  11 { $var-description "Holds an " { $link inet } " object with the address of an SMTP server." } ;
  12
  13 HELP: smtp-tls?
  14 { $var-description "If set to true, secure socket communication will be established after connecting to the SMTP server. The server must support the " { $snippet "STARTTLS" } " command. Off by default." } ;
  15
  16 HELP: smtp-read-timeout
  17 { $var-description "Holds a " { $link duration } " object that specifies how long to wait for a response from the SMTP server." } ;
  18
  19 HELP: smtp-auth
  20 { $var-description "Holds either " { $link no-auth } " or an instance of " { $link plain-auth } ", specifying how to authenticate with the SMTP server. Set to " { $link no-auth } " by default." } ;
  21
  22 HELP: no-auth
  23 { $class-description "If the " { $link smtp-auth } " variable is set to this value, no authentication will be performed." } ;
  24
  25 HELP: plain-auth
  26 { $class-description "If the " { $link smtp-auth } " variable is set to this value, plain authentication will be performed, with the username and password stored in the " { $slot "username" } " and " { $slot "password" } " slots of the tuple sent to the server as plain-text." } ;
  27
  28 HELP: <plain-auth>
  29 { $values { "username" string } { "password" string } { "plain-auth" plain-auth } }
  30 { $description "Creates a new " { $link plain-auth } " instance." } ;
  31
  32 HELP: with-smtp-connection
  33 { $values { "quot" quotation } }
  34 { $description "Connects to an SMTP server stored in " { $link smtp-server } " and calls the quotation." }
  35 { $notes "This word is used to implement " { $link send-email } " and there is probably no reason to call it directly." } ;
  36
  37 HELP: email
  38 { $class-description "An e-mail. E-mails have the following slots:"
  39     { $table
  40         { { $slot "from" } "The sender of the e-mail. An e-mail address." }
  41         { { $slot "to" } "The recipients of the e-mail. A sequence of e-mail addresses." }
  42         { { $slot "cc" } "Carbon-copy. A sequence of e-mail addresses." }
  43         { { $slot "bcc" } "Blind carbon-copy. A sequence of e-mail addresses." }
  44         { { $slot "subject" } " The subject of the e-mail. A string." }
  45         { { $slot "body" } " The body of the e-mail. A string." }
  46     }
  47 "The " { $slot "from" } " and " { $slot "to" } " slots are required; the rest are optional."
  48 $nl
  49 "An e-mail address is a string in one of the following two formats:"
  50 { $list
  51     { $snippet "joe@groff.com" }
  52     { $snippet "Joe Groff <joe@groff.com>" }
  53 } } ;
  54
  55 HELP: <email>
  56 { $values { "email" email } }
  57 { $description "Creates an empty " { $link email } " object." } ;
  58
  59 HELP: send-email
  60 { $values { "email" email } }
  61 { $description "Sends an e-mail." }
  62 { $examples
  63     { $code "USING: accessors smtp ;"
  64     "<email>"
  65     "    \"groucho@marx.bros\" >>from"
  66     "    { \"chico@marx.bros\" \"harpo@marx.bros\" } >>to"
  67     "    { \"gummo@marx.bros\" } >>cc"
  68     "    { \"zeppo@marx.bros\" } >>bcc"
  69     "    \"Pickup line\" >>subject"
  70     "    \"If I said you had a beautiful body, would you hold it against me?\" >>body"
  71     "send-email"
  72     ""
  73     }
  74 } ;
  75
  76 ARTICLE: "smtp" "SMTP client library"
  77 "The " { $vocab-link "smtp" } " vocabulary sends e-mail via an SMTP server."
  78 $nl
  79 "This library is configured by a set of dynamically-scoped variables:"
  80 { $subsection smtp-server }
  81 { $subsection smtp-tls? }
  82 { $subsection smtp-read-timeout }
  83 { $subsection smtp-domain }
  84 { $subsection smtp-auth }
  85 "The latter is set to an instance of one of the following:"
  86 { $subsection no-auth }
  87 { $subsection plain-auth }
  88 "Constructing an e-mail:"
  89 { $subsection email }
  90 { $subsection <email> }
  91 "Sending an email:"
  92 { $subsection send-email } ;
  93
  94 ABOUT: "smtp"