extra/imap/imap-docs.factor

   1 USING: calendar help.markup help.syntax sequences strings
   2 quotations ;
   3 IN: imap
   4
   5 ARTICLE: "imap" "IMAP library"
   6 "The " { $vocab-link "imap" } " vocab implements a large part of the IMAP4rev1 client protocol."
   7 $nl
   8 "IMAP is primarily used for retrieving and managing email and folders on an IMAP server. Note that some IMAP servers, such as " { $snippet "imap.gmail.com" } ", require application-specific passwords."
   9 $nl
  10 "Configuration:"
  11 { $subsections
  12     imap-settings
  13 }
  14 "Combinators:"
  15 { $subsections
  16     with-imap
  17     with-imap-settings
  18 }
  19 "Constructing an IMAP session:"
  20 { $subsections <imap4ssl> }
  21 "IMAP folder management:"
  22 { $subsections
  23     list-folders
  24     select-folder
  25     create-folder
  26     delete-folder
  27     rename-folder
  28     status-folder
  29     close-folder
  30 }
  31 "Retrieving mails:"
  32 { $subsections search-mails fetch-mails }
  33 "Updating and storing mails:"
  34 { $subsections copy-mails append-mail store-mail }
  35 { $examples
  36   { $code
  37     "USING: imap ; "
  38     "\"imap.gmail.com\" \"email_address@gmail.com\" \"password\" [ list-folders ] with-imap"
  39   }
  40   { $unchecked-example
  41     "USING: imap namespaces ;
  42     \\ imap-settings get-global [
  43         \"factor\" select-folder drop
  44         \"ALL\" \"\" search-mails
  45         \"(BODY[HEADER.FIELDS (SUBJECT)])\" fetch-mails
  46     ] with-imap-settings 3 head ."
  47     "{
  48     \"Subject: [Factor-talk] Wiki Tutorial\"
  49     \"Subject: Re: [Factor-talk] font-size in listener\"
  50     \"Subject: Re: [Factor-talk] Indentation width and other style guidelines\"
  51 }"
  52   }
  53 } ;
  54
  55 HELP: <imap4ssl>
  56 { $values { "host" string } { "imap4" "a duplex stream" } }
  57 { $description "Connects to an IMAP server using SSL on port 993." } ;
  58
  59 HELP: login
  60 { $values { "username" string } { "password" string } { "caps" string } }
  61 { $description "Authenticates with the IMAP server." } ;
  62
  63 HELP: capabilities
  64 { $values { "caps" string } }
  65 { $description "Fetches the advertised extensions of the IMAP server." } ;
  66
  67 HELP: list-folders
  68 { $values { "directory" string } { "folders" sequence } }
  69 { $description "Lists all folders in " { $snippet "directory" } ". Folders is a sequence of 3-tuples with the attributes, root and name of each folder matched." } ;
  70
  71 HELP: select-folder
  72 { $values { "mailbox" string } { "count" "number of mails in the folder" } }
  73 { $description "Selects which folder to operate on." } ;
  74
  75 HELP: create-folder
  76 { $values { "mailbox" string } }
  77 { $description "Creates a new folder." } ;
  78
  79 HELP: delete-folder
  80 { $values { "mailbox" string } }
  81 { $description "Deletes a folder." } ;
  82
  83 HELP: rename-folder
  84 { $values { "old-name" string } { "new-name" string } }
  85 { $description "Renames a folder." } ;
  86
  87 HELP: status-folder
  88 { $values
  89   { "mailbox" string }
  90   { "keys" "a sequence of attributes" }
  91   { "assoc" "attribute values" }
  92 }
  93 { $description "Requests a collection of attributes for the specified folder." }
  94 { $examples
  95   { $unchecked-example
  96     "USING: imap ;
  97     \\ imap-settings get-global [
  98         \"INBOX\" { \"MESSAGES\" \"UNSEEN\" } status-folder
  99     ] with-imap-settings"
 100     "{ { \"MESSAGES\" 67 } { \"UNSEEN\" 18 } }"
 101   }
 102 } ;
 103
 104 HELP: close-folder
 105 { $description "Closes the currently selected folder." } ;
 106
 107 HELP: search-mails
 108 { $values
 109   { "data-spec" "An IMAP search query" }
 110   { "str" "Text to search for" }
 111   { "uids" "UID:s of the matching mails" }
 112 }
 113 { $description "Searches the currently selected folder for matching mails. See rfc3501 for the syntax to use for " { $snippet "data-spec" } "." } ;
 114
 115 HELP: fetch-mails
 116 { $values
 117   { "uids" "A sequence of UID:s" }
 118   { "data-spec" "IMAP Message part specifier" }
 119   { "texts" "A sequence of FETCH responses" }
 120 }
 121 { $description "Fetches message parts for the specified mails. See rfc3501 for the format of " { $snippet "data-spec" } "." } ;
 122
 123 HELP: copy-mails
 124 { $values
 125   { "uids" "A sequence of UID:s" }
 126   { "mailbox" string }
 127 }
 128 { $description "Copies a set of mails to the specified folder." } ;
 129
 130 HELP: append-mail
 131 { $values
 132   { "mailbox" string }
 133   { "flags" string }
 134   { "date-time" timestamp }
 135   { "mail" string }
 136   { "uid/f" "UID of the mail if the server supports UIDPLUS, f otherwise" }
 137 }
 138 { $description "Appends a mail to the specified folder." } ;
 139
 140 HELP: store-mail
 141 { $values
 142   { "uids" "A sequence of UID:s" }
 143   { "command" "An IMAP store command" }
 144   { "flags" "Flags to set or remove" }
 145   { "mail-flags" "Flags of mails after update" }
 146 }
 147 { $description "Updates the attributes of a set of mails." } ;
 148
 149 HELP: imap-settings
 150 { $var-description "A tuple for holding the host, email, and password for an IMAP account. Setting this information as a global variable in your .factor-rc or .factor-boot-rc is recommended." }
 151 { $examples
 152     "Run the next example and click the link to edit your boot rc:"
 153     { $unchecked-example
 154
 155         "USING: imap tools.scaffold ; "
 156         "scaffold-factor-boot-rc"
 157         ""
 158      }
 159     "Add the following settings to your bootstrap rc file:"
 160     { $unchecked-example
 161         "USING: imap namespaces ;"
 162         "\"imap.gmail.com\" \"foo@gmail.com\" \"password\" <imap-settings> \\ imap-settings set-global"
 163         ""
 164     }
 165     "Run your boot rc again:"
 166     { $unchecked-example
 167         "USING: command-line ;"
 168         "run-bootstrap-init"
 169         ""
 170     }
 171 }
 172 { $see-also with-imap-settings } ;
 173
 174 HELP: with-imap
 175 { $values
 176     { "host" string } { "email" string } { "password" string } { "quot" quotation }
 177 }
 178 { $description "Logs into the IMAP server with the provided settings. The quotation should contain code to execute once authentication has aloready occurred." } ;
 179
 180 HELP: with-imap-settings
 181 { $values
 182     { "imap-settings" imap-settings } { "quot" quotation }
 183 }
 184 { $description "Logs into the IMAP server with the provided settings. The quotation should contain code to execute once authentication has aloready occurred." } ;
 185
 186 { with-imap with-imap-settings } related-words