smithy-lisp

# Smithy Common Lisp

A Common Lisp code generator for [Smithy](https://smithy.io/) protocol specifications that generates client libraries from Smithy JSON AST files. Primarily designed for generating AWS SDK clients.

> **Looking for an AWS SDK for Common Lisp?** Check out [pira](https://github.com/fukamachi/pira) - a ready-to-use AWS SDK generated by this library.

## Overview

This library provides two main components:

1. **Code Generator**: Converts Smithy JSON AST files into Common Lisp code
2. **Runtime SDK**: Provides macros and infrastructure for defining SDK operations manually

The codegen system reads Smithy JSON specifications and generates complete Common Lisp client libraries with type definitions, operations, and protocol implementations.

## Code Generation

### Basic Usage

Generate Common Lisp code from Smithy JSON files:

```lisp
(ql:quickload :smithy)

;; Generate from a single JSON file
(smithy:codegen-from-json #P"path/to/service.json"
                          :package-name "my-service"
                          :output #P"output/my-service.lisp")

;; Generate multiple AWS services
(smithy:codegen #P"path/to/aws-models/" #P"output/services/"
                :services '("s3" "ec2" "lambda")
                :prefix "aws/"
                :base-error-name 'aws-error)
```

### Generated Code Structure

The generator creates:

- **Type definitions** using `define-type`, `define-list`, `define-map`, `define-enum`
- **Structure definitions** using `define-structure`, `define-input`, `define-output`, `define-error`
- **Service definitions** using `define-service`
- **Operation definitions** using `define-operation`

Example generated code for S3:
```lisp
;; Type definitions
(smithy/sdk:define-type streaming-blob smithy/sdk:blob)
(smithy/sdk:define-list buckets :member (bucket :xml-name "Bucket"))

;; Input structure (minimal for list-buckets)
(smithy/sdk:define-input list-buckets-request ()
  ((max-buckets :target-type integer
                :member-name "MaxBuckets"
                :http-query "max-buckets"))
  (:shape-name "ListBucketsRequest"))

;; Output structure
(smithy/sdk:define-output list-buckets-output ()
  ((buckets :target-type buckets :member-name "Buckets")
   (owner :target-type owner :member-name "Owner"))
  (:shape-name "ListBucketsOutput"))

;; Operation definition
(smithy/sdk:define-operation list-buckets
  :shape-name "ListBuckets"
  :input list-buckets-request
  :output list-buckets-output
  :method "GET"
  :uri "/?x-id=ListBuckets")

;; More complex input with HTTP bindings
(smithy/sdk:define-input get-object-request ()
  ((bucket :target-type bucket-name
           :required t
           :member-name "Bucket"
           :http-label t)
   (key :target-type object-key
        :required t
        :member-name "Key"
        :http-label t)
   (if-match :target-type string
             :member-name "IfMatch"
             :http-header "If-Match"))
  (:shape-name "GetObjectRequest"))

;; Output with payload
(smithy/sdk:define-output get-object-output ()
  ((body :target-type streaming-blob
         :member-name "Body"
         :http-payload t)
   (content-type :target-type string
                 :member-name "ContentType"
                 :http-header "Content-Type"))
  (:shape-name "GetObjectOutput"))

;; Complete operation definition
(smithy/sdk:define-operation get-object
  :shape-name "GetObject"
  :input get-object-request
  :output get-object-output
  :method "GET"
  :uri "/{Bucket}/{Key+}?x-id=GetObject"
  :errors '(no-such-key))
```

### Defining Services

```lisp
(smithy/sdk:define-service s3
  :version "2006-03-01"
  :operations '(get-object put-object delete-object list-buckets)
  :traits
  '(("aws.api#service"
     ("arnNamespace" . "s3")
     ("endpointPrefix" . "s3"))
    ("aws.protocols#restXml"
     ("noErrorWrapping" . t))))
```

## See Also

- [Smithy Specification](https://smithy.io/)
- [pira](https://github.com/fukamachi/pira) - Unofficial AWS SDK generated by smithy-lisp

## License

MIT License - see [LICENSE](LICENSE) for details.


alexandria

assoc-utils

babel

closer-mop

kebab

smithy/sdk

smithy/utils

split-sequence

yason

smithy

cl-base64

cl-ppcre

ironclad/digests

local-time

plump

quri

rove

smithy/tests

smithy-lisp

Upstream URL

Author

License

smithy

Version:

License:

Authors:

Dependencies:

smithy/sdk

Dependencies:

smithy/tests

Dependencies:

smithy/utils

Dependencies:

Dependencies (14)

Dependents (1)