imap: documentation

extra/imap/imap-docs.factor

@@ -0,0 +1,137 @@
+USING: calendar help.markup help.syntax sequences strings ;
+IN: imap
+
+ARTICLE: "imap" "IMAP library"
+"The " { $vocab-link "imap" } " vocab implements a large part of the IMAP4rev1 client protocol."
+$nl
+"Constructing an IMAP session:"
+{ $subsections <imap4ssl> }
+"IMAP folder management:"
+{ $subsections
+    list-folders
+    select-folder
+    create-folder
+    delete-folder
+    rename-folder
+    status-folder
+    close-folder
+}
+"Retrieving mails:"
+{ $subsections search-mails fetch-mails }
+"Updating and storing mails:"
+{ $subsections copy-mails append-mail store-mail }
+{ $examples
+  { $code
+    "USING: imap ; "
+    "\"imap-server\" <imap4ssl> [ \"mail@example.com\" \"password\" login drop ] with-stream"
+  }
+  { $code
+    "USING: imap ; "
+    "\"imap-server\" <imap4ssl> ["
+    "    \"mail@example.com\" \"password\" login drop"
+    "    \"factor\" select-folder drop "
+    "    \"ALL\" \"\" search-mails"
+    "    \"(BODY[HEADER.FIELDS (SUBJECT)])\" fetch-mails"
+    "] with-stream 3 head ."
+    "{"
+    "    \"Subject: [Factor-talk] Wiki Tutorial\\r\\n\\r\\n\""
+    "    \"Subject: Re: [Factor-talk] font-size in listener\\r\\n\\r\\n\""
+    "    \"Subject: Re: [Factor-talk] Indentation width and other style guidelines\\r\\n\\r\\n\""
+    "}"
+  }
+} ;
+
+HELP: <imap4ssl>
+{ $values { "host" string } { "imap4" "a duplex stream" } }
+{ $description "Connects to an IMAP server using SSL on port 993." } ;
+
+HELP: login
+{ $values { "username" string } { "password" string } { "caps" string } }
+{ $description "Authenticates with the IMAP server." } ;
+
+HELP: capabilities
+{ $values { "caps" string } }
+{ $description "Fetches the advertised extensions of the IMAP server." } ;
+
+HELP: list-folders
+{ $values { "directory" string } { "folders" "a sequence" } }
+{ $description "Lists all folders in " { $snippet "directory" } ". Folders is a sequence of 3-tuples with the attributes, root and name of each folder matched." } ;
+
+HELP: select-folder
+{ $values { "mailbox" string } { "count" "number of mails in the folder" } }
+{ $description "Selects which folder to operate on." } ;
+
+HELP: create-folder
+{ $values { "mailbox" string } }
+{ $description "Creates a new folder." } ;
+
+HELP: delete-folder
+{ $values { "mailbox" string } }
+{ $description "Deletes a folder." } ;
+
+HELP: rename-folder
+{ $values { "mailbox" string } }
+{ $description "Renames a folder." } ;
+
+HELP: status-folder
+{ $values
+  { "mailbox" string }
+  { "keys" "a sequence of attributes" }
+  { "assoc" "attribute values" }
+}
+{ $description "Requests a collection of attributes for the specified folder." }
+{ $examples
+  { $code
+    "USE: imap"
+    "\"imap-host\" <imap4ssl> [ "
+    "    \"email\" \"pwd\" login drop "
+    "    \"INBOX\" { \"MESSAGES\" \"UNSEEN\" } status-folder "
+    "] with-stream ."
+    "{ { \"MESSAGES\" 67 } { \"UNSEEN\" 18 } }"
+  }
+} ;
+
+HELP: close-folder
+{ $description "Closes the currently selected folder." } ;
+
+HELP: search-mails
+{ $values
+  { "data-spec" "An IMAP search query" }
+  { "str" "Text to search for" }
+  { "uids" "UID:s of the matching mails" }
+}
+{ $description "Searches the currently selected folder for matching mails. See rfc3501 for the syntax to use for " { $snippet "data-spec" } "." } ;
+
+HELP: fetch-mails
+{ $values
+  { "uids" "A sequence of UID:s" }
+  { "data-spec" "IMAP Message part specifier" }
+  { "texts" "A sequence of FETCH responses" }
+}
+{ $description "Fetches message parts for the specified mails. See rfc3501 for the format of " { $snippet "data-spec" } "." } ;
+
+HELP: copy-mails
+{ $values
+  { "uids" "A sequence of UID:s" }
+  { "mailbox" string }
+}
+{ $description "Copies a set of mails to the specified folder." } ;
+
+HELP: append-mail
+{ $values
+  { "mailbox" string }
+  { "flags" string }
+  { "date-time" timestamp }
+  { "mail" string }
+  { "uid/f" "UID of the mail if the server supports UIDPLUS, f otherwise" }
+}
+{ $description "Appends a mail to the specified folder." } ;
+
+HELP: store-mail
+{ $values
+  { "uids" "A sequence of UID:s" }
+  { "command" "An IMAP store command" }
+  { "flags" "Flags to set or remove" }
+  { "mail-flags" "Flags of mails after update" }
+}
+{ $description "Updates the attributes of a set of mails." } ;

extra/imap/imap.factor

@@ -110,7 +110,7 @@ CONSTANT: IMAP4_SSL_PORT 993
 : capabilities ( -- caps )
     "CAPABILITY" "" command-response parse-items ;
 
-: login ( user pass -- caps )
+: login ( username password -- caps )
     "LOGIN %s \"%s\"" sprintf "" command-response parse-items ;
 
 ! Folder management
@@ -146,10 +146,10 @@ CONSTANT: IMAP4_SSL_PORT 993
     [ "UID SEARCH CHARSET UTF-8 %s" sprintf ] dip utf8 encode
     command-response parse-items [ string>number ] map ;
 
-: fetch-mails ( message-set data-spec -- texts )
+: fetch-mails ( uids data-spec -- texts )
     [ comma-list ] dip "UID FETCH %s %s" sprintf "" command-response but-last ;
 
-: copy-mails ( message-set mailbox -- )
+: copy-mails ( uids mailbox -- )
     [ comma-list ] dip >utf7imap4 "UID COPY %s \"%s\"" sprintf ""
     command-response drop ;
 
@@ -161,6 +161,6 @@ CONSTANT: IMAP4_SSL_PORT 993
         "APPEND \"%s\" %s\"%s\"" sprintf
     ] dip utf8 encode command-response parse-append-mail ;
 
-: store-mail ( message-set command flags -- mail-flags )
+: store-mail ( uids command flags -- mail-flags )
     [ comma-list ] 2dip "UID STORE %s %s %s" sprintf "" command-response
     parse-store-mail ;