Re: auth-source tokens

[Michael Albinus <michael.albinus@gmx.de>]

Ted Zlatanov <tzz@lifelogs.com> writes:

> (defun auth-source-search (&rest spec)
>   "Parse `auth-sources' for matches of the SPEC plist.

The major functionality of this defun is returning hits, matching the
spec. That the function needs also to parse `auth-sources' in order to
decide where to search, is second class information. I would start with
the major information.

> Common keys are :type, :max, :host, :protocol, and :user.

You haven't mentioned :create.

> A string value is matched as a regex for the
> file (netrc) backend and literally by the Secrets API.  A symbol
> is matched as its string value.  All the SPEC values can be
> single values or lists.

Hmm, maybe we shall extend secrets.el to support also regexp search?

> :create t means to create a token if possible.  When it is
> 'rewrite-existing, any matching existing token will be copied
> into the new token and deleted.  This defaults to nil and will
> generate an error if used with :max greater than 1..

I have a vague idea what you mean with rewrite-existing, but it is not
clear from the explanation. The word `token' is not explained. It shall
be clear, that `create' means actions in the chosen backend.

> :max N means to return at most N items (defaults to 1)

Stupid remark: it shall be greater than 0 :-)

An alternative would be to allow 0, and the function just returns t or
nil, depending whether there exist a matching token.

> :types (A B C) means to match only tokens of types A, B, or C.
> Common types include `password and `login.  Defaults to t.

:type or :types? :type is used above.

I believe, this needs more explanation what :type is. Can it have other
values but `password' or `login'?

> :host (X Y Z) means to match only hosts X, Y, or Z as a regular
> expression.  Defaults to t.
>
> :protocol (P Q R) means to match only protocols P, Q, or R.
> Defaults to t.

Shall explain what you mean with this. Could be also numbers I guess
(which is different from above, which allows on symbols or strings).

You have not explained :user.

> :K (V1 V2 V3) for any other key K will match values V1, V2, or
> V3.  If any of the values are strings, they are matched as
> regular expressions in the file (netrc) backend and literally in
> the Secrets API.  If any are symbols, they are matched literally
> as the symbol name.

This duplicates the saying at the beginning.

> Return value is a list with at most :max tokens.  Each token is a
> plist with keys :backend, :value, :type, :max, :host, :protocol,
> and :user, plus any other keys provided by the backend.
>
> The token's :value key can hold a function.  In that case you must call
> it to obtain the actual value."
> )

I would say, that :value relates to :type.

Best regards, Michael.