Determines appropriate URLs for avatars using assorted avatar services.

Upstream URL


Pixie <>


Clavatar: Common Lisp Avatar URL Determiner

1What it Is

Clavatar is a Common Lisp library to find an avatar URL using some sort ofidentifier.


  (clavatar:get-avatar-url "" :size 120)
  ; => #<URI ...>
  (clavatar:get-avatar-url "")
  ; => #<URI ...>


3.1get-avatar-url (identifier &key size default services)

Returns an avatar URL for a given identifier.

First, checks if the domain of identifier provides some clue as to how to get avatars. If so, uses the federated behavior of the domain. Otherwise, tries SERVICES in order and uses the first service which does not return a 404. Will use DEFAULT on the last service if no service knows about the identifier.

Note that because this involves DNS and HTTP queries, it is slow and you should cache the results.

SERVICES is a list which may contain any of 'LIBRAVATAR, 'GRAVATAR, or 'UNICORNIFY by default. Additional services may also be used, if support is added for them. See "Adding a New Service Type", below.

4Supported Services

  • Gravatar
  • Libravatar (both hosted and federated)
  • Unicornify

5Supported Identifier Types

  • E-mail addresses (as strings)
  • URLs (as strings, and as PURI:URI objects)

6Adding a New Identifier Type

In some cases, it may be desirable to extend Clavatar's identifier support to anobject type it does not know about; for instance, the e-mail address type of anSMTP library. This can be accomplished by adding methods onCANONICAL-IDENTIFIER and IDENTIFIER-DOMAIN.

The return value from CANONICAL-IDENTIFIER should be a string, representing the canonical form of the identifier (hostnames in lowercase, etc.).

The return value of IDENTIFIER-DOMAIN should be a string, representing the domain name which has authority for the given identifier. E.g., the host portion of an URL, or the domain of an e-mail address.

see identifiers.lisp for examples.

7Adding a New Service Type

At minimum, adding a service requires adding a class for the service, and twomethods on AVATAR-URL.

The first method should be of the form:

  (defmethod avatar-url ((service (eql 'service-name)) identifier &rest rest)
    (apply #'avatar-url (make-instance 'service-object) identifier rest))
SERVICE-NAME and SERVICE-OBJECT should probably be the same symbol, but this isnot required. This method is what enables GET-AVATAR-URL's list of services towork with bare symbols.

The second method should be of the form:

  (defmethod avatar-url ((service service-type) identifier &key size default &allow-other-keys)
This is the workhorse method whose job is to produce the URL of an avatar.

see clavatar.lisp for examples.

8See Also

Essentially the same thing, but Gravatar-specific

Dependencies (4)

  • babel
  • drakma
  • iolib
  • ironclad

Dependents (0)

    • GitHub
    • Quicklisp