The cl-sophia Reference Manual

Table of Contents

The cl-sophia Reference Manual

This is the cl-sophia Reference Manual, version 1.1.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Tue Dec 22 12:49:21 2020 GMT+0.

1 Introduction

CL-SOPHIA

Common Lisp high-level API for Sophia key-value storage

Installation

libsophia

$ cd install
$ make
$ sudo make install

cl-sophia

(ql:quickload "cl-sophia")

Examples

Set and get

(with-database ("test")
  (setf ($ "x") "a"
        ($ "y") "b")
  (values ($ "x")
          ($ "y")
          ($ "z")))
;; => "a"
;; => "b"
;; => NIL

Delete

(with-database ("test")
  (setf ($ "x") "a")
  (let ((x ($ "x")))
    (setf ($ "x") nil)
    (values x ($ "x"))))
;; => "a"
;; => NIL

Transaction

(with-database ("test" :comparator :u32)
  (with-transaction ()
    (setf ($ 0) "a"
          ($ 1) "b"
          ($ 2) "c"))
  (ignore-errors
    (with-transaction ()
      (setf ($ 1) nil)
      (error "Bam!")))
  (values ($ 0)
          ($ 1)
          ($ 2)))
;; => "a"
;; => "b"
;; => "c"

Nested transactions

(with-database ("test")
  (with-transaction ()
    (setf ($ "x") "foo"
          ($ "y") "bar")
    (with-transaction ()
      (setf ($ "z") "baz")))
  (values ($ "x")
          ($ "y")
          ($ "z")))
;; => "foo"
;; => "bar"
;; => "baz"

Iterators

(with-database ("test" :comparator :u32)
  (dotimes (i 3)
    (setf ($ i) (format nil "~r" i)))
  (let (result)
    (let ((*order* :>=))                ; by default
      (map-object (lambda (key value)
                    (push (cons key value) result))))
    (values result)))
;; => ((2 . "two") (1 . "one") (0 . "zero"))

2 Systems

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

2.1 cl-sophia

Author

Andrey V. Tikhonov <multimethod@yandex.ru>

License

WTFPL

Description

High-level API for Sophia key-value storage

Version

1.1.0

Dependencies

• cffi
• alexandria
• cl-fad

Source

cl-sophia.asd (file)

Components

• package.lisp (file)
• foreign.lisp (file)
• sophia.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-sophia.asd

Location

cl-sophia.asd

Systems

cl-sophia (system)

Packages

cl-sophia-asd

3.1.2 cl-sophia/package.lisp

Parent

cl-sophia (system)

Location

package.lisp

Packages

cl-sophia

3.1.3 cl-sophia/foreign.lisp

Dependency

package.lisp (file)

Parent

cl-sophia (system)

Location

foreign.lisp

Internal Definitions

• sp-begin (function)
• sp-commit (function)
• sp-ctl (function)
• sp-cursor (macro)
• sp-delete (function)
• sp-destroy (function)
• sp-env (function)
• sp-get (macro)
• sp-object (function)
• sp-open (function)
• sp-set (macro)

3.1.4 cl-sophia/sophia.lisp

Dependency

foreign.lisp (file)

Parent

cl-sophia (system)

Location

sophia.lisp

Exported Definitions

• $ (function)
• (setf $) (function)
• *order* (special variable)
• *path* (special variable)
• map-object (function)
• recommit (function)
• rollback (function)
• transaction-locked (condition)
• with-database (macro)
• with-database-iterator (macro)
• with-named-databases (macro)
• with-transaction (macro)

Internal Definitions

• *ctl* (special variable)
• *ctx* (special variable)
• *db* (special variable)
• *dbnames* (special variable)
• *env* (special variable)
• add-dbname (function)
• call-with-environment (function)
• call-with-field (function)
• call-with-key-field-by-comparator (function)
• capture-field (generic function)
• capture-field (method)
• capture-field (method)
• capture-key-field-by-comparator (generic function)
• capture-key-field-by-comparator (method)
• capture-key-field-by-comparator (method)
• capture-key-field-by-comparator (method)
• cfg (function)
• (setf cfg) (function)
• check-pointer (function)
• check-retcode (function)
• commit-transction (function)
• comparator (type)
• database (class)
• free-db-iterator (function)
• free-transaction (function)
• get-control (function)
• get-dbnames (function)
• get-environment (function)
• get-field (generic function)
• get-field (method)
• get-field (method)
• get-key-field (generic function)
• get-key-field (method)
• get-key-field (method)
• get-key-field (method)
• hack-init-dbs (function)
• init-db (function)
• init-db-iterator (function)
• init-transaction (function)
• internal-error (condition)
• open-environment (function)
• order (type)
• release-environment (function)
• release-field (generic function)
• release-field (method)
• release-field (method)
• set-order (function)
• store-schema (function)
• validate-schema (function)
• with-db (macro)
• with-dbs (macro)
• with-environment (macro)
• with-field (macro)
• with-key-field-by-comparator (macro)
• with-schema-path (macro)

4 Packages

Packages are listed by definition order.

4.1 cl-sophia-asd

Source

cl-sophia.asd

Use List

• asdf/interface
• common-lisp

4.2 cl-sophia

Source

package.lisp (file)

Nickname

sophia

Use List

• cffi
• common-lisp

Exported Definitions

• $ (function)
• (setf $) (function)
• *order* (special variable)
• *path* (special variable)
• map-object (function)
• recommit (function)
• rollback (function)
• transaction-locked (condition)
• with-database (macro)
• with-database-iterator (macro)
• with-named-databases (macro)
• with-transaction (macro)

Internal Definitions

• *ctl* (special variable)
• *ctx* (special variable)
• *db* (special variable)
• *dbnames* (special variable)
• *env* (special variable)
• add-dbname (function)
• call-with-environment (function)
• call-with-field (function)
• call-with-key-field-by-comparator (function)
• capture-field (generic function)
• capture-field (method)
• capture-field (method)
• capture-key-field-by-comparator (generic function)
• capture-key-field-by-comparator (method)
• capture-key-field-by-comparator (method)
• capture-key-field-by-comparator (method)
• cfg (function)
• (setf cfg) (function)
• check-pointer (function)
• check-retcode (function)
• commit-transction (function)
• comparator (type)
• database (class)
• free-db-iterator (function)
• free-transaction (function)
• get-control (function)
• get-dbnames (function)
• get-environment (function)
• get-field (generic function)
• get-field (method)
• get-field (method)
• get-key-field (generic function)
• get-key-field (method)
• get-key-field (method)
• get-key-field (method)
• hack-init-dbs (function)
• init-db (function)
• init-db-iterator (function)
• init-transaction (function)
• internal-error (condition)
• open-environment (function)
• order (type)
• release-environment (function)
• release-field (generic function)
• release-field (method)
• release-field (method)
• set-order (function)
• sp-begin (function)
• sp-commit (function)
• sp-ctl (function)
• sp-cursor (macro)
• sp-delete (function)
• sp-destroy (function)
• sp-env (function)
• sp-get (macro)
• sp-object (function)
• sp-open (function)
• sp-set (macro)
• store-schema (function)
• validate-schema (function)
• with-db (macro)
• with-dbs (macro)
• with-environment (macro)
• with-field (macro)
• with-key-field-by-comparator (macro)
• with-schema-path (macro)

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: *order*

Package

cl-sophia

Source

sophia.lisp (file)

Special Variable: *path*

Package

cl-sophia

Source

sophia.lisp (file)

5.1.2 Macros

Macro: with-database (DBNAME &rest SETTINGS) &body BODY

Package

cl-sophia

Source

sophia.lisp (file)

Macro: with-database-iterator (NAME &optional DB) &body BODY

Package

cl-sophia

Source

sophia.lisp (file)

Macro: with-named-databases ((NAME DBNAME &rest SETTINGS) &rest CLAUSES) &body BODY

Package

cl-sophia

Source

sophia.lisp (file)

Macro: with-transaction () &body BODY

Package

cl-sophia

Source

sophia.lisp (file)

5.1.3 Functions

Function: $ KEY &optional DB

Function: (setf $) VALUE KEY &optional DB

Package

cl-sophia

Source

sophia.lisp (file)

Function: map-object FUNCTION &optional DB

Package

cl-sophia

Source

sophia.lisp (file)

Function: recommit C

Package

cl-sophia

Source

sophia.lisp (file)

Function: rollback C

Package

cl-sophia

Source

sophia.lisp (file)

5.1.4 Conditions

Condition: transaction-locked ()

Package

cl-sophia

Source

sophia.lisp (file)

Direct superclasses

error (condition)

5.2 Internal definitions

5.2.1 Special variables

Special Variable: *ctl*

Package

cl-sophia

Source

sophia.lisp (file)

Special Variable: *ctx*

Package

cl-sophia

Source

sophia.lisp (file)

Special Variable: *db*

Package

cl-sophia

Source

sophia.lisp (file)

Special Variable: *dbnames*

Package

cl-sophia

Source

sophia.lisp (file)

Special Variable: *env*

Package

cl-sophia

Source

sophia.lisp (file)

5.2.2 Macros

Macro: sp-cursor HANDLE &rest VARARGS0

Package

cl-sophia

Source

foreign.lisp (file)

Macro: sp-get HANDLE &rest VARARGS0

Package

cl-sophia

Source

foreign.lisp (file)

Macro: sp-set HANDLE &rest VARARGS0

Package

cl-sophia

Source

foreign.lisp (file)

Macro: with-db (NAME DBNAME &rest SETTINGS) &body BODY

Package

cl-sophia

Source

sophia.lisp (file)

Macro: with-dbs (CLAUSE &rest CLAUSES) &body BODY

Package

cl-sophia

Source

sophia.lisp (file)

Macro: with-environment () &body BODY

Package

cl-sophia

Source

sophia.lisp (file)

Macro: with-field (FOREIGN-TYPE OBJECT KEY VALUE) &body BODY

Package

cl-sophia

Source

sophia.lisp (file)

Macro: with-key-field-by-comparator (COMPARATOR OBJECT VALUE) &body BODY

Package

cl-sophia

Source

sophia.lisp (file)

Macro: with-schema-path (PATH DATABASE-NAME) &body BODY

Package

cl-sophia

Source

sophia.lisp (file)

5.2.3 Functions

Function: add-dbname DBNAME

Package

cl-sophia

Source

sophia.lisp (file)

Function: call-with-environment FUNCTION

Package

cl-sophia

Source

sophia.lisp (file)

Function: call-with-field FUNCTION FOREIGN-TYPE OBJECT KEY VALUE

Package

cl-sophia

Source

sophia.lisp (file)

Function: call-with-key-field-by-comparator FUNCTION COMPARATOR OBJECT VALUE

Package

cl-sophia

Source

sophia.lisp (file)

Function: cfg KEY

Function: (setf cfg) VALUE KEY

Package

cl-sophia

Source

sophia.lisp (file)

Function: check-pointer POINTER &rest ARGUMENTS

Package

cl-sophia

Source

sophia.lisp (file)

Function: check-retcode RETCODE &rest ARGUMENTS

Package

cl-sophia

Source

sophia.lisp (file)

Function: commit-transction TRANSACTION

Package

cl-sophia

Source

sophia.lisp (file)

Function: free-db-iterator ITERATOR

Package

cl-sophia

Source

sophia.lisp (file)

Function: free-transaction TRANSACTION

Package

cl-sophia

Source

sophia.lisp (file)

Function: get-control ENVIRONMENT

Package

cl-sophia

Source

sophia.lisp (file)

Function: get-dbnames ()

Package

cl-sophia

Source

sophia.lisp (file)

Function: get-environment ()

Package

cl-sophia

Source

sophia.lisp (file)

Function: hack-init-dbs ()

Package

cl-sophia

Source

sophia.lisp (file)

Function: init-db NAME &rest SCHEMA

Package

cl-sophia

Source

sophia.lisp (file)

Function: init-db-iterator DB

Package

cl-sophia

Source

sophia.lisp (file)

Function: init-transaction ()

Package

cl-sophia

Source

sophia.lisp (file)

Function: open-environment ENVIRONMENT

Package

cl-sophia

Source

sophia.lisp (file)

Function: release-environment ENVIRONMENT

Package

cl-sophia

Source

sophia.lisp (file)

Function: set-order OBJ ORDER

Package

cl-sophia

Source

sophia.lisp (file)

Function: sp-begin HANDLE

Package

cl-sophia

Source

foreign.lisp (file)

Function: sp-commit HANDLE

Package

cl-sophia

Source

foreign.lisp (file)

Function: sp-ctl ENV

Package

cl-sophia

Source

foreign.lisp (file)

Function: sp-delete HANDLE OBJECT

Package

cl-sophia

Source

foreign.lisp (file)

Function: sp-destroy HANDLE

Package

cl-sophia

Source

foreign.lisp (file)

Function: sp-env ()

Package

cl-sophia

Source

foreign.lisp (file)

Function: sp-object HANDLE

Package

cl-sophia

Source

foreign.lisp (file)

Function: sp-open HANDLE

Package

cl-sophia

Source

foreign.lisp (file)

Function: store-schema NAME &key COMPARATOR

Package

cl-sophia

Source

sophia.lisp (file)

Function: validate-schema NAME &key COMPARATOR

Package

cl-sophia

Source

sophia.lisp (file)

5.2.4 Generic functions

Generic Function: capture-field FOREIGN-TYPE OBJECT KEY VALUE

Package

cl-sophia

Source

sophia.lisp (file)

Methods

Method: capture-field (FOREIGN-TYPE (eql string)) OBJECT KEY VALUE

Method: capture-field FOREIGN-TYPE OBJECT KEY VALUE

Generic Function: capture-key-field-by-comparator COMPARATOR OBJECT VALUE

Package

cl-sophia

Source

sophia.lisp (file)

Methods

Method: capture-key-field-by-comparator (COMPARATOR (eql u64)) OBJECT VALUE

Method: capture-key-field-by-comparator (COMPARATOR (eql u32)) OBJECT VALUE

Method: capture-key-field-by-comparator (COMPARATOR (eql string)) OBJECT VALUE

Generic Function: get-field FOREIGN-TYPE OBJECT KEY

Package

cl-sophia

Source

sophia.lisp (file)

Methods

Method: get-field (FOREIGN-TYPE (eql string)) OBJECT KEY

Method: get-field FOREIGN-TYPE OBJECT KEY

Generic Function: get-key-field COMPARATOR OBJECT

Package

cl-sophia

Source

sophia.lisp (file)

Methods

Method: get-key-field (COMPARATOR (eql u64)) OBJECT

Method: get-key-field (COMPARATOR (eql u32)) OBJECT

Method: get-key-field (COMPARATOR (eql string)) OBJECT

Generic Function: release-field FOREIGN-TYPE FIELD

Package

cl-sophia

Source

sophia.lisp (file)

Methods

Method: release-field (FOREIGN-TYPE (eql string)) FIELD

Method: release-field FOREIGN-TYPE FIELD

5.2.5 Conditions

Condition: internal-error ()

Package

cl-sophia

Source

sophia.lisp (file)

Direct superclasses

simple-error (condition)

Direct slots

Slot: retcode

Initargs

:retcode

Initform

(quote nil)

5.2.6 Classes

Class: database ()

Package

cl-sophia

Source

sophia.lisp (file)

Direct superclasses

standard-object (class)

Direct slots

Slot: handle

Initargs

:handle

Slot: comparator

Initargs

:comparator

Initform

:string

5.2.7 Types

Type: comparator ()

Package

cl-sophia

Source

sophia.lisp (file)

Type: order ()

Package

cl-sophia

Source

sophia.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types