The clavatar Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The clavatar Reference Manual

This is the clavatar Reference Manual, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 11:29:19 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

#+TITLE: Clavatar: Common Lisp Avatar URL Determiner

* What it Is
Clavatar is a Common Lisp library to find an avatar URL using some sort of
identifier.

* Synopsis

#+begin_src lisp
  (clavatar:get-avatar-url "avatars@example.com" :size 120)
  ; => #
  (clavatar:get-avatar-url "http://example.com/user/avatars")
  ; => #
#+end_src

* API
** get-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.

* Supported Services
 * Gravatar
 * Libravatar (both hosted and federated)
 * Unicornify

* Supported Identifier Types
 * E-mail addresses (as strings)
 * URLs (as strings, and as PURI:URI objects)

* Adding a New Identifier Type
In some cases, it may be desirable to extend Clavatar's identifier support to an
object type it does not know about; for instance, the e-mail address type of an
SMTP library.  This can be accomplished by adding methods on
CANONICAL-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.

* Adding a New Service Type
At minimum, adding a service requires adding a class for the service, and two
methods on AVATAR-URL.

The first method should be of the form:
#+begin_src lisp
  (defmethod avatar-url ((service (eql 'service-name)) identifier &rest rest)
    (apply #'avatar-url (make-instance 'service-object) identifier rest))
#+end_src
SERVICE-NAME and SERVICE-OBJECT should probably be the same symbol, but this is
not required.  This method is what enables GET-AVATAR-URL's list of services to
work with bare symbols.

The second method should be of the form:
#+begin_src lisp
  (defmethod avatar-url ((service service-type) identifier &key size default &allow-other-keys)
    (determine-identifiers-avatar-uri))
#+end_src
This is the workhorse method whose job is to produce the URL of an avatar.

see =clavatar.lisp= for examples.

* See Also
 * cl-gravatar :: Essentially the same thing, but Gravatar-specific


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 clavatar

Author

Pixie <pix@kepibu.org>

License

MIT

Description

Determines appropriate URLs for avatars using assorted avatar services.

Dependencies
Source

clavatar.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 clavatar.asd

Location

clavatar.asd

Systems

clavatar (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 clavatar/package.lisp

Parent

clavatar (system)

Location

package.lisp

Packages

clavatar


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.3 clavatar/util.lisp

Dependency

package.lisp (file)

Parent

clavatar (system)

Location

util.lisp

Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.4 clavatar/identifiers.lisp

Dependency

util.lisp (file)

Parent

clavatar (system)

Location

identifiers.lisp

Exported Definitions
Internal Definitions

Previous: , Up: Lisp files   [Contents][Index]

3.1.5 clavatar/clavatar.lisp

Dependency

identifiers.lisp (file)

Parent

clavatar (system)

Location

clavatar.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 clavatar

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Functions

Function: get-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.

Package

clavatar

Source

clavatar.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Generic functions

Generic Function: canonical-identifier IDENTIFIER
Package

clavatar

Source

identifiers.lisp (file)

Methods
Method: canonical-identifier (E-MAIL %e-mail)
Method: canonical-identifier (URI uri)
Method: canonical-identifier (IDENTIFIER string)
Generic Function: identifier-domain IDENTIFIER
Package

clavatar

Source

identifiers.lisp (file)

Methods
Method: identifier-domain (IDENTIFIER %e-mail)
Method: identifier-domain (IDENTIFIER uri)
Method: identifier-domain (IDENTIFIER string)

Previous: , Up: Exported definitions   [Contents][Index]

5.1.3 Classes

Class: gravatar ()
Package

clavatar

Source

clavatar.lisp (file)

Direct superclasses

hosted-service (class)

Direct methods

avatar-url (method)

Direct slots
Slot: base-uri
Initform

(puri:uri "https://secure.gravatar.com/")

Class: libravatar ()
Package

clavatar

Source

clavatar.lisp (file)

Direct superclasses
Direct slots
Slot: base-uri
Initform

(puri:uri "https://seccdn.libravatar.org/")

Class: unicornify ()
Package

clavatar

Source

clavatar.lisp (file)

Direct superclasses

hosted-service (class)

Direct methods

avatar-url (method)

Direct slots
Slot: base-uri
Initform

(puri:uri "https://unicornify.appspot.com/")


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Functions

Function: %e-mail-domain INSTANCE
Function: (setf %e-mail-domain) VALUE INSTANCE
Package

clavatar

Source

identifiers.lisp (file)

Function: %e-mail-local-part INSTANCE
Function: (setf %e-mail-local-part) VALUE INSTANCE
Package

clavatar

Source

identifiers.lisp (file)

Function: %e-mail-p OBJECT
Package

clavatar

Source

identifiers.lisp (file)

Function: build-url-query ARGS
Package

clavatar

Source

util.lisp (file)

Function: copy-%e-mail INSTANCE
Package

clavatar

Source

identifiers.lisp (file)

Function: default-port-p SCHEME PORT
Package

clavatar

Source

util.lisp (file)

Function: ensure-identifier IDENTIFIER
Package

clavatar

Source

identifiers.lisp (file)

Function: identifier-hash IDENTIFIER HASH
Package

clavatar

Source

identifiers.lisp (file)

Function: make-%e-mail LOCAL-PART DOMAIN
Package

clavatar

Source

identifiers.lisp (file)

Function: make-e-mail STRING
Package

clavatar

Source

identifiers.lisp (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Generic functions

Generic Function: avatar-url SERVICE IDENTIFIER &key SIZE DEFAULT &allow-other-keys
Package

clavatar

Source

clavatar.lisp (file)

Methods
Method: avatar-url (SERVICE federated-service) IDENTIFIER &key SIZE DEFAULT &allow-other-keys
Method: avatar-url (SERVICE unicornify) IDENTIFIER &rest REST
Method: avatar-url (SERVICE libravatar-protocol) IDENTIFIER &rest REST
Method: avatar-url (SERVICE gravatar) IDENTIFIER &rest REST
Method: avatar-url (SERVICE hosted-service) IDENTIFIER &key SIZE DEFAULT &allow-other-keys around
Method: avatar-url (SERVICE (eql federated)) IDENTIFIER &rest REST
Method: avatar-url (SERVICE (eql unicornify)) IDENTIFIER &rest REST
Method: avatar-url (SERVICE (eql libravatar)) IDENTIFIER &rest REST
Method: avatar-url (SERVICE (eql gravatar)) IDENTIFIER &rest REST

Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.3 Structures

Structure: %e-mail ()
Package

clavatar

Source

identifiers.lisp (file)

Direct superclasses

structure-object (structure)

Direct methods
Direct slots
Slot: local-part
Readers

%e-mail-local-part (function)

Writers

(setf %e-mail-local-part) (function)

Slot: domain
Readers

%e-mail-domain (function)

Writers

(setf %e-mail-domain) (function)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.4 Classes

Class: federated-service ()
Package

clavatar

Source

clavatar.lisp (file)

Direct superclasses

libravatar-protocol (class)

Direct methods

avatar-url (method)

Class: hosted-service ()
Package

clavatar

Source

clavatar.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses
Direct methods

avatar-url (method)

Direct slots
Slot: base-uri
Class: libravatar-protocol ()
Package

clavatar

Source

clavatar.lisp (file)

Direct superclasses

standard-object (class)

Direct subclasses
Direct methods

avatar-url (method)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   C   F   L  
Index Entry  Section

C
clavatar.asd: The clavatar<dot>asd file
clavatar/clavatar.lisp: The clavatar/clavatar<dot>lisp file
clavatar/identifiers.lisp: The clavatar/identifiers<dot>lisp file
clavatar/package.lisp: The clavatar/package<dot>lisp file
clavatar/util.lisp: The clavatar/util<dot>lisp file

F
File, Lisp, clavatar.asd: The clavatar<dot>asd file
File, Lisp, clavatar/clavatar.lisp: The clavatar/clavatar<dot>lisp file
File, Lisp, clavatar/identifiers.lisp: The clavatar/identifiers<dot>lisp file
File, Lisp, clavatar/package.lisp: The clavatar/package<dot>lisp file
File, Lisp, clavatar/util.lisp: The clavatar/util<dot>lisp file

L
Lisp File, clavatar.asd: The clavatar<dot>asd file
Lisp File, clavatar/clavatar.lisp: The clavatar/clavatar<dot>lisp file
Lisp File, clavatar/identifiers.lisp: The clavatar/identifiers<dot>lisp file
Lisp File, clavatar/package.lisp: The clavatar/package<dot>lisp file
Lisp File, clavatar/util.lisp: The clavatar/util<dot>lisp file

Jump to:   C   F   L  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   %   (  
A   B   C   D   E   F   G   I   M  
Index Entry  Section

%
%e-mail-domain: Internal functions
%e-mail-local-part: Internal functions
%e-mail-p: Internal functions

(
(setf %e-mail-domain): Internal functions
(setf %e-mail-local-part): Internal functions

A
avatar-url: Internal generic functions
avatar-url: Internal generic functions
avatar-url: Internal generic functions
avatar-url: Internal generic functions
avatar-url: Internal generic functions
avatar-url: Internal generic functions
avatar-url: Internal generic functions
avatar-url: Internal generic functions
avatar-url: Internal generic functions
avatar-url: Internal generic functions

B
build-url-query: Internal functions

C
canonical-identifier: Exported generic functions
canonical-identifier: Exported generic functions
canonical-identifier: Exported generic functions
canonical-identifier: Exported generic functions
copy-%e-mail: Internal functions

D
default-port-p: Internal functions

E
ensure-identifier: Internal functions

F
Function, %e-mail-domain: Internal functions
Function, %e-mail-local-part: Internal functions
Function, %e-mail-p: Internal functions
Function, (setf %e-mail-domain): Internal functions
Function, (setf %e-mail-local-part): Internal functions
Function, build-url-query: Internal functions
Function, copy-%e-mail: Internal functions
Function, default-port-p: Internal functions
Function, ensure-identifier: Internal functions
Function, get-avatar-url: Exported functions
Function, identifier-hash: Internal functions
Function, make-%e-mail: Internal functions
Function, make-e-mail: Internal functions

G
Generic Function, avatar-url: Internal generic functions
Generic Function, canonical-identifier: Exported generic functions
Generic Function, identifier-domain: Exported generic functions
get-avatar-url: Exported functions

I
identifier-domain: Exported generic functions
identifier-domain: Exported generic functions
identifier-domain: Exported generic functions
identifier-domain: Exported generic functions
identifier-hash: Internal functions

M
make-%e-mail: Internal functions
make-e-mail: Internal functions
Method, avatar-url: Internal generic functions
Method, avatar-url: Internal generic functions
Method, avatar-url: Internal generic functions
Method, avatar-url: Internal generic functions
Method, avatar-url: Internal generic functions
Method, avatar-url: Internal generic functions
Method, avatar-url: Internal generic functions
Method, avatar-url: Internal generic functions
Method, avatar-url: Internal generic functions
Method, canonical-identifier: Exported generic functions
Method, canonical-identifier: Exported generic functions
Method, canonical-identifier: Exported generic functions
Method, identifier-domain: Exported generic functions
Method, identifier-domain: Exported generic functions
Method, identifier-domain: Exported generic functions

Jump to:   %   (  
A   B   C   D   E   F   G   I   M  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   B   D   L   S  
Index Entry  Section

B
base-uri: Exported classes
base-uri: Exported classes
base-uri: Exported classes
base-uri: Internal classes

D
domain: Internal structures

L
local-part: Internal structures

S
Slot, base-uri: Exported classes
Slot, base-uri: Exported classes
Slot, base-uri: Exported classes
Slot, base-uri: Internal classes
Slot, domain: Internal structures
Slot, local-part: Internal structures

Jump to:   B   D   L   S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   %  
C   F   G   H   L   P   S   U  
Index Entry  Section

%
%e-mail: Internal structures

C
Class, federated-service: Internal classes
Class, gravatar: Exported classes
Class, hosted-service: Internal classes
Class, libravatar: Exported classes
Class, libravatar-protocol: Internal classes
Class, unicornify: Exported classes
clavatar: The clavatar system
clavatar: The clavatar package

F
federated-service: Internal classes

G
gravatar: Exported classes

H
hosted-service: Internal classes

L
libravatar: Exported classes
libravatar-protocol: Internal classes

P
Package, clavatar: The clavatar package

S
Structure, %e-mail: Internal structures
System, clavatar: The clavatar system

U
unicornify: Exported classes

Jump to:   %  
C   F   G   H   L   P   S   U