From ee4979ee3c6cc1937f2d35433a063ce8aab85244 Mon Sep 17 00:00:00 2001 From: Ted Zlatanov Date: Tue, 8 Mar 2011 14:45:12 -0600 Subject: [PATCH] Add full usage example. * auth.texi (Help for developers): Show example of using `auth-source-search' with prompts and :save-function. --- texi/ChangeLog | 5 ++++ texi/auth.texi | 64 ++++++++++++++++++++++++++++++++++++++++++++++---- 2 files changed, 64 insertions(+), 5 deletions(-) diff --git a/texi/ChangeLog b/texi/ChangeLog index 08baca310..76bc116dd 100644 --- a/texi/ChangeLog +++ b/texi/ChangeLog @@ -1,3 +1,8 @@ +2011-03-08 Teodor Zlatanov + + * auth.texi (Help for developers): Show example of using + `auth-source-search' with prompts and :save-function. + 2011-03-07 Antoine Levitt * message.texi (Message Buffers): Update default value of diff --git a/texi/auth.texi b/texi/auth.texi index bfc3c9635..d592d029a 100644 --- a/texi/auth.texi +++ b/texi/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? -- 2.25.1