Merge changes made in Gnus trunk.

auth-source.el (auth-source-read-char-choice): New function to read a character choice using `dropdown-list', `read-char-choice', or `read-char'.  It appends "[a/b/c] " to the prompt if the choices were '(?a ?b ?c).  The `dropdown-list' support is disabled for now.  Use `eval-when-compile' to load `dropdown-list'.
 (auth-source-netrc-saver): Use it.
nnimap.el (nnimap-credentials): Keep the :save-function as the third parameter in the credentials.
 (nnimap-open-connection-1): Use it after a successful login.
 (nnimap-credentials): Add IMAP-specific user and password prompt.
auth-source.el (auth-source-search): Add :require parameter, taking a list.  Document it and the :save-function return token.  Pass :require down.  Change the CREATED message from a warning to a debug statement.
 (auth-source-search-backends): Pass :require down.
 (auth-source-netrc-search): Pass :require down.
 (auth-source-netrc-parse): Use :require, if it's given, as a filter.  Change save prompt to indicate all modifications saved here are deletions.
 (auth-source-netrc-create): Take user login name as default in user prompt.  Move all the save functionality to a lexically bound function under the :save-function token in the returned list.  Set up clearer default prompts for user, host, port, and secret.
 (auth-source-netrc-saver): New function, intended to be wrapped for :save-function.

2 files changed, 64 insertions, 5 deletions

diff --git a/doc/misc/ChangeLog b/doc/misc/ChangeLog
index 75674c7fd17..96a2576355a 100644
--- a/doc/misc/ChangeLog
+++ b/doc/misc/ChangeLog
@@ -1,3 +1,8 @@
+2011-03-08  Teodor Zlatanov  <tzz@lifelogs.com>
+
+        * auth.texi (Help for developers): Show example of using
+        `auth-source-search' with prompts and :save-function.
+
 2011-03-07  Antoine Levitt  <antoine.levitt@gmail.com>
 
         * message.texi (Message Buffers): Update default value of
diff --git a/doc/misc/auth.texi b/doc/misc/auth.texi
index 23ac23dce5b..e16d7b49b63 100644
--- a/doc/misc/auth.texi
+++ b/doc/misc/auth.texi
@@ -131,11 +131,11 @@ library encourages this confusion by accepting both, as you'll see
 later.
 
 If you have problems with the search, set @code{auth-source-debug} to
-@code{t} and see what host, port, and user the library is checking in
-the @code{*Messages*} buffer.  Ditto for any other problems, your
-first step is always to see what's being checked.  The second step, of
-course, is to write a blog entry about it and wait for the answer in
-the comments.
+@code{'trivia} and see what host, port, and user the library is
+checking in the @code{*Messages*} buffer.  Ditto for any other
+problems, your first step is always to see what's being checked.  The
+second step, of course, is to write a blog entry about it and wait for
+the answer in the comments.
 
 You can customize the variable @code{auth-sources}.  The following may
 be needed if you are using an older version of Emacs or if the
@@ -232,6 +232,14 @@ TODO: how does it work generally, how does secrets.el work, some examples.
 @node Help for developers
 @chapter Help for developers
 
+The auth-source library lets you control logging output easily.
+
+@defvar auth-source-debug
+Set this variable to 'trivia to see lots of output in *Messages*, or
+set it to a function that behaves like @code{message} to do your own
+logging.
+@end defvar
+
 The auth-source library only has a few functions for external use.
 
 @defun auth-source-search SPEC
@@ -240,6 +248,52 @@ TODO: how to include docstring?
 
 @end defun
 
+Let's take a look at an example of using @code{auth-source-search}
+from Gnus' @code{nnimap.el}.
+
+@example
+(defun nnimap-credentials (address ports)
+  (let* ((auth-source-creation-prompts
+          '((user  . "IMAP user at %h: ")
+            (secret . "IMAP password for %u@@%h: ")))
+         (found (nth 0 (auth-source-search :max 1
+                                           :host address
+                                           :port ports
+                                           :require '(:user :secret)
+                                           :create t))))
+    (if found
+        (list (plist-get found :user)
+              (let ((secret (plist-get found :secret)))
+                (if (functionp secret)
+                    (funcall secret)
+                  secret))
+              (plist-get found :save-function))
+      nil)))
+@end example
+
+This call requires the user and password (secret) to be in the
+results.  It also requests that an entry be created if it doesn't
+exist already.  While the created entry is being assembled, the shown
+prompts will be used to interact with the user.  The caller can also
+pass data in @code{auth-source-creation-defaults} to supply defaults
+for any of the prompts.
+
+Note that the password needs to be evaluated if it's a function.  It's
+wrapped in a function to provide some security.
+
+Later, after a successful login, @code{nnimal.el} calls the
+@code{:save-function} like so:
+
+@example
+(when (functionp (nth 2 credentials))
+   (funcall (nth 2 credentials)))
+@end example  
+
+Which will work whether the @code{:save-function} was provided or not.
+@code{:save-function} will be provided only when a new entry was
+created, so this effectively says ``after a successful login, save the
+authentication information we just used, if it was newly created.''
+
 @defun auth-source-delete SPEC
 
 TODO: how to include docstring?