The south Reference Manual

This is the south Reference Manual, version 0.3.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Sep 15 06:45:46 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 south

Simple OaUTH library for oAuth1.0

Maintainer

Yukari Hafner <>

Author

Yukari Hafner <>

Home Page

https://Shinmera.github.io/south/

Source Control

(GIT https://github.com/Shinmera/south.git)

Bug Tracker

https://github.com/Shinmera/south/issues

License

zlib

Version

0.3.0

Dependencies
  • drakma (system).
  • uuid (system).
  • ironclad (system).
  • cl-ppcre (system).
Source

south.asd.

Child Components

3 Files

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


3.1 Lisp


3.1.1 south/south.asd

Source

south.asd.

Parent Component

south (system).

ASDF Systems

south.


3.1.2 south/package.lisp

Source

south.asd.

Parent Component

south (system).

Packages

south.


3.1.3 south/toolkit.lisp

Dependency

package.lisp (file).

Source

south.asd.

Parent Component

south (system).

Public Interface
Internals

3.1.4 south/oauth.lisp

Dependency

toolkit.lisp (file).

Source

south.asd.

Parent Component

south (system).

Public Interface
Internals

4 Packages

Packages are listed by definition order.


4.1 south

Source

package.lisp.

Nickname

org.tymoonnext.south

Use List

common-lisp.

Public Interface
Internals

5 Definitions

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


5.1 Public Interface


5.1.1 Special variables

Special Variable: *authentication-callback*

Function called when COMPLETE-AUTHENTICATION is called.
Two arguments are passed, the ACCESS-TOKEN and the ACCESS-SECRET.

Package

south.

Source

oauth.lisp.

Special Variable: *external-format*

The external format used for encoding/decoding.

Package

south.

Source

toolkit.lisp.

Special Variable: *oauth-access-secret*
Package

south.

Source

oauth.lisp.

Special Variable: *oauth-access-token*
Package

south.

Source

oauth.lisp.

Special Variable: *oauth-api-key*
Package

south.

Source

oauth.lisp.

Special Variable: *oauth-api-secret*
Package

south.

Source

oauth.lisp.

Special Variable: *oauth-signature-method*
Package

south.

Source

oauth.lisp.

Special Variable: *oauth-verifier-location*
Package

south.

Source

oauth.lisp.

Special Variable: *oauth-version*
Package

south.

Source

oauth.lisp.

Special Variable: *oauth/access-token*
Package

south.

Source

oauth.lisp.

Special Variable: *oauth/authenticate*
Package

south.

Source

oauth.lisp.

Special Variable: *oauth/authorize*
Package

south.

Source

oauth.lisp.

Special Variable: *oauth/request-token*
Package

south.

Source

oauth.lisp.

Special Variable: *server-port*
Package

south.

Source

oauth.lisp.


5.1.2 Macros

Macro: with-oauth-environment ((&key oauth/request-token oauth/authorize oauth/authenticate oauth/access-token signature-method version api-key api-secret access-token access-secret) &body body)

Establishes an environment for all oauth related special variables.
Unless a non-NIL value is provided for a parameter it is bound to the current value of the according special variable.

Package

south.

Source

oauth.lisp.


5.1.3 Ordinary functions

Function: complete-authentication (verifier &optional token)

Finishes the authentication procedure by retrieving the access token. Sets the *OAUTH-TOKEN* and *OAUTH-TOKEN-SECRET* to their respective values.

Package

south.

Source

oauth.lisp.

Function: generate-nonce ()

Generate a NONCE to use for requests. Currently this simply uses a v4-UUID.

Package

south.

Source

toolkit.lisp.

Function: initiate-authentication (&key method api-key api-secret)

Starts the authentication process and returns an URL that the user has to visit.
METHOD can be one of :PIN :SERVER or a string designating a callback URL.
Note that the :PIN method is NOT STANDARD and thus might not be available for your service. See OAUTH/AUTHORIZE, INITIATE-SERVER-AUTHENTICATION and OAUTH/AUTHENTICATE respectively.

Package

south.

Source

oauth.lisp.

Function: initiate-server-authentication ()

Initiate the authentication through the server mechanism. This is the same as the redirect mechanism, except it starts up a Hunchentoot server automatically and handles the callback for you. The server will be started on *SERVER-PORT* and will be shut down automatically after a single request.

Package

south.

Source

oauth.lisp.

Function: oauth/access-token (verifier)

Turn the tokens received through the authentication into an access token.

According to spec https://dev.twitter.com/docs/auth/implementing-sign-twitter

Package

south.

Source

oauth.lisp.

Function: oauth/authenticate (callback-url)

Initiate the authentication through the redirect mechanism.
Returns an URL that the user has to open in the browser.
Upon successful authentication, the page should redirect back
to the specified callback url. This callback endpoint should then
pass the proper parameters to COMPLETE-AUTHENTICATION.

According to spec https://dev.twitter.com/docs/auth/implementing-sign-twitter

Package

south.

Source

oauth.lisp.

Function: oauth/authorize ()

Initiate the authentication through the PIN mechanism.
Returns an URL that the user has to open in the browser.
This page should, upon successful authentication, return a PIN
that has to be initialized by passing it to COMPLETE-AUTHENTICATION.

According to spec https://dev.twitter.com/docs/auth/pin-based-authorization

Package

south.

Source

oauth.lisp.

Function: oauth/request-token (callback)

Query for a request token using the specified callback.
Returns an ALIST containing :OAUTH-TOKEN, :OAUTH-TOKEN-SECRET and :OAUTH-CALLBACK-CONFIRMED, the first two being strings and the last a boolean.

According to spec https://dev.twitter.com/docs/auth/implementing-sign-twitter

Package

south.

Source

oauth.lisp.

Function: pin-request-token ()

Query for a PIN based request token.
Seee CALLBACK-REQUEST-TOKEN.

According to spec https://dev.twitter.com/docs/auth/pin-based-authorization

Package

south.

Source

oauth.lisp.

Function: prepare (&key oauth/request-token oauth/authorize oauth/authenticate oauth/access-token api-key api-secret)

Cosmetic function to set the oauth request URLs and api-key and -secret. This only sets the internal value of the parameter if it is non-NIL.

Package

south.

Source

oauth.lisp.

Function: reset ()

Resets the internal API-KEY, API-SECRET, ACCESS-TOKEN and ACCESS-SECRET to NIL. This does not change the oauth request URLs.

Package

south.

Source

oauth.lisp.

Function: signed-data-parameters-request (request-url &key data-parameters parameters oauth-parameters additional-headers method drakma-params)

Issue a signed data request against the API.
See SIGNED-REQUEST. The difference to SIGNED-DATA-REQUEST is that the default PARAMETERS are used to calculate the authorization header, whereas the DATA-PARAMETERS are not. In SINGED-DATA-REQUEST, neither of the parameters are used for the header.

Package

south.

Source

oauth.lisp.

Function: signed-data-request (request-url &key data-parameters parameters oauth-parameters additional-headers method drakma-params)

Issue a signed data request against the API.
See SIGNED-REQUEST.

According to spec https://dev.twitter.com/docs/uploading-media

Package

south.

Source

oauth.lisp.

Function: signed-request (request-url &key parameters oauth-parameters additional-headers method drakma-params)

Issue a signed request against the API.
This requires the *oauth-api-key*, *oauth-signature-method*, *oauth-version* and at least *oauth-api-secret* to be set.
See CREATE-SIGNATURE.
For return values see DRAKMA:HTTP-REQUEST

According to spec https://dev.twitter.com/docs/auth/authorizing-request

Package

south.

Source

oauth.lisp.

Function: signed-stream-request (request-url &key parameters oauth-parameters additional-headers method drakma-params)

Issue a signed data request against the API.
See SIGNED-REQUEST. Returns values according to DRAKMA:HTTP-REQUEST with :WANT-STREAM T

Package

south.

Source

oauth.lisp.

Function: url-decode (string &optional external-format)

Returns a URL-decoded version of the string STRING external format EXTERNAL-FORMAT.

According to spec https://dev.twitter.com/docs/auth/percent-encoding-parameters

Package

south.

Source

toolkit.lisp.

Function: url-encode (thing &optional external-format)

Returns a URL-encoded version of the string STRING or OCTET-SEQUENCE using the external format EXTERNAL-FORMAT.

According to spec https://dev.twitter.com/docs/auth/percent-encoding-parameters

Package

south.

Source

toolkit.lisp.


5.1.4 Generic functions

Generic Reader: http-body (condition)
Generic Writer: (setf http-body) (condition)
Package

south.

Methods
Reader Method: http-body ((condition oauth-request-error))
Writer Method: (setf http-body) ((condition oauth-request-error))
Source

oauth.lisp.

Target Slot

%http-body.

Generic Reader: http-headers (condition)
Generic Writer: (setf http-headers) (condition)
Package

south.

Methods
Reader Method: http-headers ((condition oauth-request-error))
Writer Method: (setf http-headers) ((condition oauth-request-error))
Source

oauth.lisp.

Target Slot

%http-headers.

Generic Reader: http-status (condition)
Generic Writer: (setf http-status) (condition)
Package

south.

Methods
Reader Method: http-status ((condition oauth-request-error))
Writer Method: (setf http-status) ((condition oauth-request-error))
Source

oauth.lisp.

Target Slot

%http-status.

Generic Reader: parameter (condition)
Generic Writer: (setf parameter) (condition)
Package

south.

Methods
Reader Method: parameter ((condition oauth-parameter-missing))
Writer Method: (setf parameter) ((condition oauth-parameter-missing))
Source

oauth.lisp.

Target Slot

%parameter.

Generic Reader: target-headers (condition)
Generic Writer: (setf target-headers) (condition)
Package

south.

Methods
Reader Method: target-headers ((condition oauth-request-error))
Writer Method: (setf target-headers) ((condition oauth-request-error))
Source

oauth.lisp.

Target Slot

%target-headers.

Generic Reader: target-method (condition)
Generic Writer: (setf target-method) (condition)
Package

south.

Methods
Reader Method: target-method ((condition oauth-request-error))
Writer Method: (setf target-method) ((condition oauth-request-error))
Source

oauth.lisp.

Target Slot

%target-method.

Generic Reader: target-parameters (condition)
Generic Writer: (setf target-parameters) (condition)
Package

south.

Methods
Reader Method: target-parameters ((condition oauth-request-error))
Writer Method: (setf target-parameters) ((condition oauth-request-error))
Source

oauth.lisp.

Target Slot

%target-parameters.

Generic Reader: target-url (condition)
Generic Writer: (setf target-url) (condition)
Package

south.

Methods
Reader Method: target-url ((condition oauth-request-error))
Writer Method: (setf target-url) ((condition oauth-request-error))
Source

oauth.lisp.

Target Slot

%target-url.


5.1.5 Conditions

Condition: oauth-error
Package

south.

Source

oauth.lisp.

Direct superclasses

error.

Direct subclasses
Condition: oauth-parameter-missing
Package

south.

Source

oauth.lisp.

Direct superclasses

oauth-error.

Direct methods
Direct slots
Slot: %parameter
Initargs

:parameter

Readers

parameter.

Writers

(setf parameter).

Condition: oauth-request-error
Package

south.

Source

oauth.lisp.

Direct superclasses

oauth-error.

Direct methods
Direct slots
Slot: %http-status
Initargs

:status

Readers

http-status.

Writers

(setf http-status).

Slot: %http-body
Initargs

:body

Readers

http-body.

Writers

(setf http-body).

Slot: %http-headers
Initargs

:headers

Readers

http-headers.

Writers

(setf http-headers).

Slot: %target-url
Initargs

:url

Readers

target-url.

Writers

(setf target-url).

Slot: %target-method
Initargs

:method

Readers

target-method.

Writers

(setf target-method).

Slot: %target-parameters
Initargs

:parameters

Readers

target-parameters.

Writers

(setf target-parameters).

Slot: %target-headers
Initargs

:sent-headers

Readers

target-headers.

Writers

(setf target-headers).


5.2 Internals


5.2.1 Constants

Constant: +unix-epoch-difference+

The universal to unix time difference in seconds.

Package

south.

Source

toolkit.lisp.


5.2.2 Ordinary functions

Function: authorization-format-parameter (s param &rest rest)
Package

south.

Source

oauth.lisp.

Function: create-authorization-header (method request-url oauth-parameters parameters)
Package

south.

Source

oauth.lisp.

Function: create-authorization-header-value (parameters)

Turns the OAuth parameters into the correct header value.

Package

south.

Source

oauth.lisp.

Function: create-signature (method url parameters)

Create an OAuth signature for a request.
This requires at least the *oauth-api-secret* to be bound properly, and usually the *oauth-access-secret* as well.

According to spec https://dev.twitter.com/docs/auth/creating-signature

Package

south.

Source

oauth.lisp.

Function: get-unix-time ()

Return the unix timestamp for GMT, as required by OAuth.

Package

south.

Source

toolkit.lisp.

Function: hmac (string keystring)

Returns a base-64 encoded string of the HMAC digest of the given STRING using the KEYSTRING as HMAC key. The encoding of *external-format* is used throughout.

Package

south.

Source

toolkit.lisp.

Function: make-signed (method url oauth-parameters &optional other-parameters)

Returns the signed version of the oauth-parameters.
Simply generates a signature and appends the proper parameter.

Package

south.

Source

oauth.lisp.

Function: oauth-response->alist (body &optional spec)

Turn an oauth-response into an ALIST.

Package

south.

Source

oauth.lisp.

Function: parse-boolean (value)

Parses a string boolean. If the string is one of (T, true, 1), then T is returned, otherwise NIL. The check is case-insensitive.

Package

south.

Source

toolkit.lisp.

Function: prepare-data-parameters (parameters)
Package

south.

Source

oauth.lisp.

Function: request-wrapper (uri &rest drakma-params)
Package

south.

Source

oauth.lisp.

Function: signature-format-parameter (s param &rest rest)
Package

south.

Source

oauth.lisp.

Function: to-keyword (string)

Turns a key into a keyword.
Replaces _ with - and uppercases the string, then interns it into the keyword package. This is useful to parse the request responses into an alist.

Package

south.

Source

toolkit.lisp.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   (  
A   C   F   G   H   I   M   O   P   R   S   T   U   W  
Index Entry  Section

(
(setf http-body): Public generic functions
(setf http-body): Public generic functions
(setf http-headers): Public generic functions
(setf http-headers): Public generic functions
(setf http-status): Public generic functions
(setf http-status): Public generic functions
(setf parameter): Public generic functions
(setf parameter): Public generic functions
(setf target-headers): Public generic functions
(setf target-headers): Public generic functions
(setf target-method): Public generic functions
(setf target-method): Public generic functions
(setf target-parameters): Public generic functions
(setf target-parameters): Public generic functions
(setf target-url): Public generic functions
(setf target-url): Public generic functions

A
authorization-format-parameter: Private ordinary functions

C
complete-authentication: Public ordinary functions
create-authorization-header: Private ordinary functions
create-authorization-header-value: Private ordinary functions
create-signature: Private ordinary functions

F
Function, authorization-format-parameter: Private ordinary functions
Function, complete-authentication: Public ordinary functions
Function, create-authorization-header: Private ordinary functions
Function, create-authorization-header-value: Private ordinary functions
Function, create-signature: Private ordinary functions
Function, generate-nonce: Public ordinary functions
Function, get-unix-time: Private ordinary functions
Function, hmac: Private ordinary functions
Function, initiate-authentication: Public ordinary functions
Function, initiate-server-authentication: Public ordinary functions
Function, make-signed: Private ordinary functions
Function, oauth-response->alist: Private ordinary functions
Function, oauth/access-token: Public ordinary functions
Function, oauth/authenticate: Public ordinary functions
Function, oauth/authorize: Public ordinary functions
Function, oauth/request-token: Public ordinary functions
Function, parse-boolean: Private ordinary functions
Function, pin-request-token: Public ordinary functions
Function, prepare: Public ordinary functions
Function, prepare-data-parameters: Private ordinary functions
Function, request-wrapper: Private ordinary functions
Function, reset: Public ordinary functions
Function, signature-format-parameter: Private ordinary functions
Function, signed-data-parameters-request: Public ordinary functions
Function, signed-data-request: Public ordinary functions
Function, signed-request: Public ordinary functions
Function, signed-stream-request: Public ordinary functions
Function, to-keyword: Private ordinary functions
Function, url-decode: Public ordinary functions
Function, url-encode: Public ordinary functions

G
generate-nonce: Public ordinary functions
Generic Function, (setf http-body): Public generic functions
Generic Function, (setf http-headers): Public generic functions
Generic Function, (setf http-status): Public generic functions
Generic Function, (setf parameter): Public generic functions
Generic Function, (setf target-headers): Public generic functions
Generic Function, (setf target-method): Public generic functions
Generic Function, (setf target-parameters): Public generic functions
Generic Function, (setf target-url): Public generic functions
Generic Function, http-body: Public generic functions
Generic Function, http-headers: Public generic functions
Generic Function, http-status: Public generic functions
Generic Function, parameter: Public generic functions
Generic Function, target-headers: Public generic functions
Generic Function, target-method: Public generic functions
Generic Function, target-parameters: Public generic functions
Generic Function, target-url: Public generic functions
get-unix-time: Private ordinary functions

H
hmac: Private ordinary functions
http-body: Public generic functions
http-body: Public generic functions
http-headers: Public generic functions
http-headers: Public generic functions
http-status: Public generic functions
http-status: Public generic functions

I
initiate-authentication: Public ordinary functions
initiate-server-authentication: Public ordinary functions

M
Macro, with-oauth-environment: Public macros
make-signed: Private ordinary functions
Method, (setf http-body): Public generic functions
Method, (setf http-headers): Public generic functions
Method, (setf http-status): Public generic functions
Method, (setf parameter): Public generic functions
Method, (setf target-headers): Public generic functions
Method, (setf target-method): Public generic functions
Method, (setf target-parameters): Public generic functions
Method, (setf target-url): Public generic functions
Method, http-body: Public generic functions
Method, http-headers: Public generic functions
Method, http-status: Public generic functions
Method, parameter: Public generic functions
Method, target-headers: Public generic functions
Method, target-method: Public generic functions
Method, target-parameters: Public generic functions
Method, target-url: Public generic functions

O
oauth-response->alist: Private ordinary functions
oauth/access-token: Public ordinary functions
oauth/authenticate: Public ordinary functions
oauth/authorize: Public ordinary functions
oauth/request-token: Public ordinary functions

P
parameter: Public generic functions
parameter: Public generic functions
parse-boolean: Private ordinary functions
pin-request-token: Public ordinary functions
prepare: Public ordinary functions
prepare-data-parameters: Private ordinary functions

R
request-wrapper: Private ordinary functions
reset: Public ordinary functions

S
signature-format-parameter: Private ordinary functions
signed-data-parameters-request: Public ordinary functions
signed-data-request: Public ordinary functions
signed-request: Public ordinary functions
signed-stream-request: Public ordinary functions

T
target-headers: Public generic functions
target-headers: Public generic functions
target-method: Public generic functions
target-method: Public generic functions
target-parameters: Public generic functions
target-parameters: Public generic functions
target-url: Public generic functions
target-url: Public generic functions
to-keyword: Private ordinary functions

U
url-decode: Public ordinary functions
url-encode: Public ordinary functions

W
with-oauth-environment: Public macros


A.3 Variables

Jump to:   %   *   +  
C   S  
Index Entry  Section

%
%http-body: Public conditions
%http-headers: Public conditions
%http-status: Public conditions
%parameter: Public conditions
%target-headers: Public conditions
%target-method: Public conditions
%target-parameters: Public conditions
%target-url: Public conditions

*
*authentication-callback*: Public special variables
*external-format*: Public special variables
*oauth-access-secret*: Public special variables
*oauth-access-token*: Public special variables
*oauth-api-key*: Public special variables
*oauth-api-secret*: Public special variables
*oauth-signature-method*: Public special variables
*oauth-verifier-location*: Public special variables
*oauth-version*: Public special variables
*oauth/access-token*: Public special variables
*oauth/authenticate*: Public special variables
*oauth/authorize*: Public special variables
*oauth/request-token*: Public special variables
*server-port*: Public special variables

+
+unix-epoch-difference+: Private constants

C
Constant, +unix-epoch-difference+: Private constants

S
Slot, %http-body: Public conditions
Slot, %http-headers: Public conditions
Slot, %http-status: Public conditions
Slot, %parameter: Public conditions
Slot, %target-headers: Public conditions
Slot, %target-method: Public conditions
Slot, %target-parameters: Public conditions
Slot, %target-url: Public conditions
Special Variable, *authentication-callback*: Public special variables
Special Variable, *external-format*: Public special variables
Special Variable, *oauth-access-secret*: Public special variables
Special Variable, *oauth-access-token*: Public special variables
Special Variable, *oauth-api-key*: Public special variables
Special Variable, *oauth-api-secret*: Public special variables
Special Variable, *oauth-signature-method*: Public special variables
Special Variable, *oauth-verifier-location*: Public special variables
Special Variable, *oauth-version*: Public special variables
Special Variable, *oauth/access-token*: Public special variables
Special Variable, *oauth/authenticate*: Public special variables
Special Variable, *oauth/authorize*: Public special variables
Special Variable, *oauth/request-token*: Public special variables
Special Variable, *server-port*: Public special variables