The cl-s3 Reference Manual

Table of Contents

The cl-s3 Reference Manual

This is the cl-s3 Reference Manual, version 1, generated automatically by Declt version 3.0 "Montgomery Scott" on Fri Jun 26 10:32:27 2020 GMT+0.

1 Introduction

CL-S3

CL-S3 is a Common Lisp library that implements a client interface to the Amazon S3 Web Service.

More specifically, CL-S3

• uses the Amazon S3 REST interface
• does proper authorization
• implements all S3 API calls with all options
• parses the XML returned by some of the API
• converts S3 error responses to proper Common Lisp condition objects
• allows custom meta header (including canned access policies) and query parameters
• does proper keep-alive processing (courtesy S-HTTP-CLIENT)
• is portable over Common Lisp implementations (courtesy of S-SYSDEPS)
• can optionally validate get and put object calls using MD5 hashing
• contains 2 example higher level functions converting XML to simpler data
• contains 2 example higher level functions for uploading and downloading files to and from S3
• is properly packaged and has a documented public API
• should be installed using ASDF

CL-S3 was written by Sven Van Caekenberghe and is available under an LLGPL license.

Please read the full Amazon S3 documentation and study the Common Lisp source code before contacting me with ;-)

There is an interesting post on Nicky Peeters' Blog showing how to get started using CL-S3.

2 Systems

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

2.1 cl-s3

Maintainer

Sven Van Caekenberghe <svc@mac.com>

Author

Sven Van Caekenberghe <svc@mac.com>

License

Lesser Lisp General Public License (LLGPL)

Description

A Common Lisp Amazon S3 client interface package

Version

1

Dependencies

• s-http-client
• s-xml
• s-utils
• s-base64
• ironclad

Source

cl-s3.asd (file)

Components

• cl-s3-package.lisp (file)
• cl-s3.lisp (file)

3 Files

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

3.1 Lisp

3.1.1 cl-s3.asd

Location

cl-s3.asd

Systems

cl-s3 (system)

3.1.2 cl-s3/cl-s3-package.lisp

Parent

cl-s3 (system)

Location

cl-s3-package.lisp

Packages

cl-s3

3.1.3 cl-s3/cl-s3.lisp

Dependency

cl-s3-package.lisp (file)

Parent

cl-s3 (system)

Location

cl-s3.lisp

Exported Definitions

• *access-key-id* (special variable)
• *secret-access-key* (special variable)
• amazon-s3-api-error (condition)
• delete-bucket (function)
• delete-object (function)
• download-file (function)
• get-bucket (function)
• get-object (function)
• get-service (function)
• head-object (function)
• lisp-time->unix-time (function)
• list-buckets (function)
• list-objects (function)
• make-authorization (function)
• put-bucket (function)
• put-object (function)
• request-date (function)
• unix-time->lisp-time (function)
• upload-file (function)

Internal Definitions

• *amazon-host* (special variable)
• *s3-ns* (special variable)
• +zero-unix-time+ (constant)
• amazon-s3-api-error-xml (method)
• do-s3-request (function)
• hmac-sha1 (function)
• md5sum-sequence (function)

4 Packages

Packages are listed by definition order.

4.1 cl-s3

A Common Lisp Amazon S3 client interface package

Source

cl-s3-package.lisp (file)

Use List

common-lisp

Exported Definitions

• *access-key-id* (special variable)
• *secret-access-key* (special variable)
• amazon-s3-api-error (condition)
• delete-bucket (function)
• delete-object (function)
• download-file (function)
• get-bucket (function)
• get-object (function)
• get-service (function)
• head-object (function)
• lisp-time->unix-time (function)
• list-buckets (function)
• list-objects (function)
• make-authorization (function)
• put-bucket (function)
• put-object (function)
• request-date (function)
• unix-time->lisp-time (function)
• upload-file (function)

Internal Definitions

• *amazon-host* (special variable)
• *s3-ns* (special variable)
• +zero-unix-time+ (constant)
• amazon-s3-api-error-xml (generic function)
• amazon-s3-api-error-xml (method)
• do-s3-request (function)
• hmac-sha1 (function)
• md5sum-sequence (function)

5 Definitions

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

5.1 Exported definitions

5.1.1 Special variables

Special Variable: *access-key-id*

The value of your Amazon Web Services public access key ID

Package

cl-s3

Source

cl-s3.lisp (file)

Special Variable: *secret-access-key*

The value of your Amazon Web Services secret access key

Package

cl-s3

Source

cl-s3.lisp (file)

5.1.2 Functions

Function: delete-bucket BUCKET-NAME

Delete a bucket

Package

cl-s3

Source

cl-s3.lisp (file)

Function: delete-object BUCKET-NAME OBJECT-KEY

Delete the object identified by key in bucket

Package

cl-s3

Source

cl-s3.lisp (file)

Function: download-file BUCKET KEY &key DIR IF-EXISTS ELEMENT-TYPE

Assuming key in bucket denotes a file, download it, optionally in dir

Package

cl-s3

Source

cl-s3.lisp (file)

Function: get-bucket BUCKET-NAME &key PREFIX MARKER MAX-KEYS DELIMITER

List all keys in a bucket that satisfy a query

Package

cl-s3

Source

cl-s3.lisp (file)

Function: get-object BUCKET-NAME OBJECT-KEY &key CHECK-INTEGRITY BODY

Retrieve the object identified by key in bucket

Package

cl-s3

Source

cl-s3.lisp (file)

Function: get-service ()

List all available buckets

Package

cl-s3

Source

cl-s3.lisp (file)

Function: head-object BUCKET-NAME OBJECT-KEY

Retrieve all meta-data for the the object identified by key in bucket

Package

cl-s3

Source

cl-s3.lisp (file)

Function: lisp-time->unix-time S

Convert from Common Lisp time to Unix time

Package

cl-s3

Source

cl-s3.lisp (file)

Function: list-buckets ()

Returns a list of all accessible buckets’ string names

Package

cl-s3

Source

cl-s3.lisp (file)

Function: list-objects BUCKET-NAME &key PREFIX MARKER MAX-KEYS DELIMITER

Return a list of all keys’ strings in bucket, satifying the query

Package

cl-s3

Source

cl-s3.lisp (file)

Function: make-authorization VERB RESOURCE DATE &key SECRET-ACCESS-KEY CONTENT-MD5 CONTENT-TYPE AMZ-HEADERS

Compute an Amazon S3 authorization signature

Package

cl-s3

Source

cl-s3.lisp (file)

Function: put-bucket BUCKET-NAME

Create a new bucket

Package

cl-s3

Source

cl-s3.lisp (file)

Function: put-object BUCKET-NAME OBJECT-KEY CONTENT CONTENT-TYPE &key AMZ-HEADERS CHECK-INTEGRITY CONTENT-LENGTH

Set the object identified by key in bucket to the specified content

Package

cl-s3

Source

cl-s3.lisp (file)

Function: request-date &optional UNIVERSAL-TIME

Generate a GMT HTTP Request Date

Package

cl-s3

Source

cl-s3.lisp (file)

Function: unix-time->lisp-time MS

Convert from Unix time to Common Lisp time

Package

cl-s3

Source

cl-s3.lisp (file)

Function: upload-file PATHNAME BUCKET &key NAME ELEMENT-TYPE MIME-TYPE ACL

Upload the file at pathname under bucket, optionally storing it under name

Package

cl-s3

Source

cl-s3.lisp (file)

5.1.3 Conditions

Condition: amazon-s3-api-error ()

Thrown when an Amazon S3 API Error is received

Package

cl-s3

Source

cl-s3.lisp (file)

Direct superclasses

error (condition)

Direct methods

amazon-s3-api-error-xml (method)

Direct slots

Slot: xml

Initargs

:xml

Readers

amazon-s3-api-error-xml (generic function)

Slot: more-values

Initargs

:more-values

5.2 Internal definitions

5.2.1 Constants

Constant: +zero-unix-time+

Package

cl-s3

Source

cl-s3.lisp (file)

5.2.2 Special variables

Special Variable: *amazon-host*

Package

cl-s3

Source

cl-s3.lisp (file)

Special Variable: *s3-ns*

Package

cl-s3

Source

cl-s3.lisp (file)

5.2.3 Functions

Function: do-s3-request VERB URI &key CONTENT CONTENT-TYPE CONTENT-LENGTH CONTENT-MD5 AMZ-HEADERS QUERY BODY

Package

cl-s3

Source

cl-s3.lisp (file)

Function: hmac-sha1 DATA-STRING KEY-STRING

Compute an RFC 2104 HMAC-SHA1 digest on data-string using key-string

Package

cl-s3

Source

cl-s3.lisp (file)

Function: md5sum-sequence DATA-STRING

Compute a MD5 digest on data-string

Package

cl-s3

Source

cl-s3.lisp (file)

5.2.4 Generic functions

Generic Function: amazon-s3-api-error-xml CONDITION

Package

cl-s3

Methods

Method: amazon-s3-api-error-xml (CONDITION amazon-s3-api-error)

Source

cl-s3.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types