The datafly Reference Manual

This is the datafly Reference Manual, version 0.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Sep 15 04:57:48 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 datafly

Lightweight database library.

Author

Eitaro Fukamachi

License

BSD 3-Clause

Long Description

# datafly

[![Build Status](https://travis-ci.org/fukamachi/datafly.svg?branch=master)](https://travis-ci.org/fukamachi/datafly)

Datafly is a lightweight database library for Common Lisp.

## Quickstart

Datafly provides 3 functions which wrap [CL-DBI](https://github.com/fukamachi/cl-dbi) — ‘retrieve-one‘, ‘retrieve-all‘ and ‘execute‘.

They take a [SxQL](https://github.com/fukamachi/sxql) statement.

“‘common-lisp
(use-package :sxql)

(connect-toplevel :sqlite3 :database-name #P"myapp.db")

(retrieve-one
(select :*
(from :user)
(where (:= :name "nitro_idiot"))))
;=> (:ID 1 :NAME "nitro_idiot" :EMAIL "nitro_idiot@example.com" :REGISTERED-AT "2014-04-14T19:20:13")

(retrieve-all
(select :*
(from :user)))
;=> ((:ID 1 :NAME "nitro_idiot" :EMAIL "nitro_idiot@example.com" :REGISTERED-AT "2014-04-14T19:20:13")
; (:ID 2 :NAME "m2ym" :EMAIL "m2ym@example.com" :REGISTERED-AT "2014-04-15T01:03:42"))

(execute
(insert-into :tweet
(set= :id 1
:user_id 1
:body "Hi."
:created_at (princ-to-string *now*))))
“‘

If you specify ‘:as‘ option with a class name to retrieval functions, they create instances of the class for each rows.

“‘common-lisp
(defstruct user
id
name
email
registered-at)

(retrieve-one
(select :*
(from :user)
(where (:= :name "nitro_idiot")))
:as ’user)
;=> #S(USER :ID 1 :NAME "nitro_idiot" :EMAIL "nitro_idiot@example.com" :REGISTERED-AT "2014-04-14T19:20:13")

(retrieve-all
(select :*
(from :user))
:as ’user)
;=> (#S(USER :ID 1 :NAME "nitro_idiot" :EMAIL "nitro_idiot@example.com" :REGISTERED-AT "2014-04-14T19:20:13")
; #S(USER :ID 2 :NAME "m2ym" :EMAIL "m2ym@example.com" :REGISTERED-AT "2014-04-15T01:03:42"))
“‘

The structure doesn’t require having slots same as an existing table’s in a database. It is acceptable even if the names are different. This might be convenient when you’d like to treat a JOINed table result as a structure object.

## Model Definitions

Datafly provides a macro ‘defmodel‘ which defines a flavored structure class.

“‘common-lisp
(defmodel (user (:inflate registered-at #’datetime-to-timestamp))
id
name
email
registered-at)

;; Same as the above.
(syntax:use-syntax :annot)

@model
(defstruct (user (:inflate registered-at #’datetime-to-timestamp))
id
name
email
registered-at)
“‘

‘(:inflate <columns> <inflation-function>)‘ options mean ‘inflation-function‘ will be applied to each ‘<columns>‘ when creating an instance.

“‘common-lisp
(defvar *user*
(retrieve-one
(select :*
(from :user)
(where (:= :name "nitro_idiot")))
:as ’user))

;; Returns a local-time:timestamp.
(user-registered-at *user*)
;=> @2014-04-15T04:20:13.000000+09:00
“‘

‘defmodel‘ also allows ‘:has-a‘ and ‘:has-many‘ options.

“‘common-lisp
(use-package :sxql)

(defmodel (user (:inflate registered-at #’datetime-to-timestamp)
(:has-a config (where (:= :user_id id)))
(:has-many (tweets tweet)
(select :*
(from :tweet)
(where (:= :user_id id))
(order-by (:desc :created_at)))))
id
name
email
registered-at)

(defvar *user*
(retrieve-one
(select :*
(from :user)
(where (:= :name "nitro_idiot")))
:as ’user))

(user-config *user*)
;=> #S(CONFIG :ID 4 :USER-ID 1 :TIMEZONE "JST" :COUNTRY "jp" :LANGUAGE "ja")

(user-tweets *user*)
;=> (#S(TWEET :ID 2 :USER-ID 1 :BODY "Is it working?" :CREATED-AT @2014-04-16T11:02:31.000000+09:00)
; #S(TWEET :ID 1 :USER-ID 1 :BODY "Hi." :CREATED-AT @2014-04-15T18:58:20.000000+09:00))
“‘

## Provided inflation functions

* ‘tinyint-to-boolean‘
* ‘datetime-to-timestamp‘
* ‘unixtime-to-timestamp‘
* ‘string-to-keyword‘
* ‘octet-vector-to-string‘

## Tips: Getting Association List or Hash Table for each rows

‘retrieve-one‘ and ‘retrieve-all‘ return row(s) as a property list or a list of property lists by default.

If you’d like they were other types, for example "Association List" or "Hash Table", you can do it by passing ‘:as‘ parameter.

“‘common-lisp
(retrieve-one
(select :*
(from :user)
(where (:= :name "nitro_idiot")))
:as ’trivial-types:association-list)
;=> ((:ID . 1) (:NAME . "nitro_idiot") (:EMAIL . "nitro_idiot@example.com") (:REGISTERED-AT . "2014-04-14T19:20:13"))

(retrieve-one
(select :*
(from :user)
(where (:= :name "nitro_idiot")))
:as ’hash-table)
;=> #<HASH-TABLE :TEST EQL :COUNT 4 {1007AE3CD3}>
“‘

If no ‘:as‘ parameter is specified, ‘*default-row-type*‘ will be used.

“‘common-lisp
(let ((*default-row-type* ’hash-table))
(retrieve-all
(select :*
(from :user))))
;=> (#<HASH-TABLE :TEST EQL :COUNT 4 {100815FA03}> #<HASH-TABLE :TEST EQL :COUNT 4 {100815FE43}>)
“‘

## See Also

* [SxQL](https://github.com/fukamachi/sxql)
* [CL-DBI](https://github.com/fukamachi/cl-dbi)
* [cl-annot](https://github.com/arielnetworks/cl-annot), [CL-SYNTAX](https://github.com/m2ym/cl-syntax)
* [function-cache](https://github.com/AccelerationNet/function-cache)

## Author

* Eitaro Fukamachi (e.arrows@gmail.com)

## Copyright

Copyright (c) 2014 Eitaro Fukamachi (e.arrows@gmail.com)

# License

Licensed under the BSD 3-Clause License.

Version

0.1

Dependencies
  • iterate (system).
  • optima (system).
  • trivial-types (system).
  • closer-mop (system).
  • named-readtables (system).
  • sxql (system).
  • dbi (system).
  • alexandria (system).
  • babel (system).
  • local-time (system).
  • function-cache (system).
  • jonathan (system).
  • kebab (system).
  • log4cl (system).
Source

datafly.asd.

Child Component

src (module).


3 Modules

Modules are listed depth-first from the system components tree.


3.1 datafly/src

Source

datafly.asd.

Parent Component

datafly (system).

Child Components

4 Files

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


4.1 Lisp


4.1.1 datafly/datafly.asd

Source

datafly.asd.

Parent Component

datafly (system).

ASDF Systems

datafly.


4.1.2 datafly/src/datafly.lisp

Dependencies
Source

datafly.asd.

Parent Component

src (module).

Packages

datafly.


4.1.3 datafly/src/model.lisp

Dependencies
Source

datafly.asd.

Parent Component

src (module).

Packages

datafly.model.

Public Interface

4.1.4 datafly/src/db.lisp

Dependencies
Source

datafly.asd.

Parent Component

src (module).

Packages

datafly.db.

Public Interface
Internals

4.1.5 datafly/src/cache.lisp

Dependency

syntax.lisp (file).

Source

datafly.asd.

Parent Component

src (module).

Packages

datafly.cache.

Public Interface
Internals

4.1.6 datafly/src/logger.lisp

Dependency

syntax.lisp (file).

Source

datafly.asd.

Parent Component

src (module).

Packages

datafly.logger.

Public Interface
Internals

*sql-logger-pattern* (special variable).


4.1.7 datafly/src/inflate.lisp

Dependencies
Source

datafly.asd.

Parent Component

src (module).

Packages

datafly.inflate.

Public Interface

4.1.8 datafly/src/json.lisp

Dependency

syntax.lisp (file).

Source

datafly.asd.

Parent Component

src (module).

Packages

datafly.json.

Public Interface
Internals

4.1.9 datafly/src/syntax.lisp

Source

datafly.asd.

Parent Component

src (module).

Packages

datafly.syntax.

Public Interface

enable-syntax (macro).


4.1.10 datafly/src/util.lisp

Source

datafly.asd.

Parent Component

src (module).

Packages

datafly.util.

Public Interface

5 Packages

Packages are listed by definition order.


5.1 datafly.logger

Source

logger.lisp.

Use List
Public Interface
Internals

*sql-logger-pattern* (special variable).


5.2 datafly.db

Source

db.lisp.

Use List
Public Interface
Internals

5.3 datafly.cache

Source

cache.lisp.

Use List
Public Interface
Internals

5.4 datafly

Source

datafly.lisp.

Use List

common-lisp.


5.5 datafly.util

Source

util.lisp.

Use List
Public Interface

5.6 datafly.model

Source

model.lisp.

Use List
Public Interface

5.7 datafly.syntax

Source

syntax.lisp.

Use List

common-lisp.

Used By List
Public Interface

enable-syntax (macro).


5.8 datafly.json

Source

json.lisp.

Use List
Public Interface
Internals

5.9 datafly.inflate

Source

inflate.lisp.

Use List
Public Interface

6 Definitions

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


6.1 Public Interface


6.1.1 Special variables

Special Variable: *connection*
Package

datafly.db.

Source

db.lisp.

Special Variable: *default-row-type*
Package

datafly.db.

Source

db.lisp.

Special Variable: *sql-logger*
Package

datafly.logger.

Source

logger.lisp.

Special Variable: *trace-sql*
Package

datafly.logger.

Source

logger.lisp.


6.1.2 Macros

Macro: defcached-accessor (name args cache-args &body body)
Package

datafly.cache.

Source

cache.lisp.

Macro: defmodel (name-and-options &body slot-descriptions)
Package

datafly.model.

Source

model.lisp.

Macro: enable-syntax ()
Package

datafly.syntax.

Source

syntax.lisp.

Macro: model (defstruct-form)
Package

datafly.model.

Source

model.lisp.


6.1.3 Ordinary functions

Function: clear-model-caches (model &optional accessor)
Package

datafly.cache.

Source

cache.lisp.

Function: clear-object-caches (object &optional accessor)
Package

datafly.cache.

Source

cache.lisp.

Function: connect-cached (&rest connect-args)
Package

datafly.db.

Source

db.lisp.

Function: connect-toplevel (&rest connect-args)
Package

datafly.db.

Source

db.lisp.

Function: copy-model (object)
Package

datafly.model.

Source

model.lisp.

Function: database-type ()
Package

datafly.db.

Source

db.lisp.

Function: datetime-to-timestamp (val)
Package

datafly.inflate.

Source

inflate.lisp.

Function: disconnect-toplevel ()
Package

datafly.db.

Source

db.lisp.

Function: execute (statement)
Package

datafly.db.

Source

db.lisp.

Function: object-to-plist (object)
Package

datafly.model.

Source

model.lisp.

Function: octet-vector-to-string (val)
Package

datafly.inflate.

Source

inflate.lisp.

Function: partition (item sequence &key from-end start end key test)
Package

datafly.util.

Source

util.lisp.

Function: partition-if (pred sequence &key from-end start end key)
Package

datafly.util.

Source

util.lisp.

Function: retrieve-all (statement &key as prettify)
Package

datafly.db.

Source

db.lisp.

Function: retrieve-all-values (statement &optional key prettify)
Package

datafly.db.

Source

db.lisp.

Function: retrieve-one (statement &key by = as prettify)
Package

datafly.db.

Source

db.lisp.

Function: retrieve-one-value (statement &optional key prettify)
Package

datafly.db.

Source

db.lisp.

Function: string-to-keyword (val)
Package

datafly.inflate.

Source

inflate.lisp.

Function: tinyint-to-boolean (val)
Package

datafly.inflate.

Source

inflate.lisp.

Function: unixtime-to-timestamp (val)
Package

datafly.inflate.

Source

inflate.lisp.


6.1.4 Generic functions

Generic Function: convert-object (object)
Package

datafly.json.

Source

json.lisp.

Methods
Method: convert-object ((object structure-object))
Method: convert-object ((object standard-object))
Generic Function: encode-json (object &optional stream)
Package

datafly.json.

Source

json.lisp.

Methods
Method: encode-json (object &optional stream)

6.2 Internals


6.2.1 Special variables

Special Variable: *connections*
Package

datafly.db.

Source

db.lisp.

Special Variable: *model-accessors*
Package

datafly.cache.

Source

cache.lisp.

Special Variable: *sql-logger-pattern*
Package

datafly.logger.

Source

logger.lisp.


6.2.2 Ordinary functions

Function: accessor-cache (accessor)
Package

datafly.cache.

Source

cache.lisp.

Function: association-list-p (object)
Package

datafly.json.

Source

json.lisp.

Function: connection-quote-character (conn)
Package

datafly.db.

Source

db.lisp.

Function: convert-column-name (name)
Package

datafly.db.

Source

db.lisp.

Function: convert-column-value (value)
Package

datafly.db.

Source

db.lisp.

Function: convert-for-json (object)
Package

datafly.json.

Source

json.lisp.

Function: convert-row (row &key as prettify)
Package

datafly.db.

Source

db.lisp.

Function: execute-with-connection (conn statement)
Package

datafly.db.

Source

db.lisp.

Function: get-prev-stack ()
Package

datafly.db.

Source

db.lisp.

Function: object-to-plist (object)
Package

datafly.json.

Source

json.lisp.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   A   C   D   E   F   G   M   O   P   R   S   T   U  
Index Entry  Section

A
accessor-cache: Private ordinary functions
association-list-p: Private ordinary functions

C
clear-model-caches: Public ordinary functions
clear-object-caches: Public ordinary functions
connect-cached: Public ordinary functions
connect-toplevel: Public ordinary functions
connection-quote-character: Private ordinary functions
convert-column-name: Private ordinary functions
convert-column-value: Private ordinary functions
convert-for-json: Private ordinary functions
convert-object: Public generic functions
convert-object: Public generic functions
convert-object: Public generic functions
convert-row: Private ordinary functions
copy-model: Public ordinary functions

D
database-type: Public ordinary functions
datetime-to-timestamp: Public ordinary functions
defcached-accessor: Public macros
defmodel: Public macros
disconnect-toplevel: Public ordinary functions

E
enable-syntax: Public macros
encode-json: Public generic functions
encode-json: Public generic functions
execute: Public ordinary functions
execute-with-connection: Private ordinary functions

F
Function, accessor-cache: Private ordinary functions
Function, association-list-p: Private ordinary functions
Function, clear-model-caches: Public ordinary functions
Function, clear-object-caches: Public ordinary functions
Function, connect-cached: Public ordinary functions
Function, connect-toplevel: Public ordinary functions
Function, connection-quote-character: Private ordinary functions
Function, convert-column-name: Private ordinary functions
Function, convert-column-value: Private ordinary functions
Function, convert-for-json: Private ordinary functions
Function, convert-row: Private ordinary functions
Function, copy-model: Public ordinary functions
Function, database-type: Public ordinary functions
Function, datetime-to-timestamp: Public ordinary functions
Function, disconnect-toplevel: Public ordinary functions
Function, execute: Public ordinary functions
Function, execute-with-connection: Private ordinary functions
Function, get-prev-stack: Private ordinary functions
Function, object-to-plist: Public ordinary functions
Function, object-to-plist: Private ordinary functions
Function, octet-vector-to-string: Public ordinary functions
Function, partition: Public ordinary functions
Function, partition-if: Public ordinary functions
Function, retrieve-all: Public ordinary functions
Function, retrieve-all-values: Public ordinary functions
Function, retrieve-one: Public ordinary functions
Function, retrieve-one-value: Public ordinary functions
Function, string-to-keyword: Public ordinary functions
Function, tinyint-to-boolean: Public ordinary functions
Function, unixtime-to-timestamp: Public ordinary functions

G
Generic Function, convert-object: Public generic functions
Generic Function, encode-json: Public generic functions
get-prev-stack: Private ordinary functions

M
Macro, defcached-accessor: Public macros
Macro, defmodel: Public macros
Macro, enable-syntax: Public macros
Macro, model: Public macros
Method, convert-object: Public generic functions
Method, convert-object: Public generic functions
Method, encode-json: Public generic functions
model: Public macros

O
object-to-plist: Public ordinary functions
object-to-plist: Private ordinary functions
octet-vector-to-string: Public ordinary functions

P
partition: Public ordinary functions
partition-if: Public ordinary functions

R
retrieve-all: Public ordinary functions
retrieve-all-values: Public ordinary functions
retrieve-one: Public ordinary functions
retrieve-one-value: Public ordinary functions

S
string-to-keyword: Public ordinary functions

T
tinyint-to-boolean: Public ordinary functions

U
unixtime-to-timestamp: Public ordinary functions


A.4 Data types

Jump to:   C   D   F   I   J   L   M   P   S   U  
Index Entry  Section

C
cache.lisp: The datafly/src/cache․lisp file

D
datafly: The datafly system
datafly: The datafly package
datafly.asd: The datafly/datafly․asd file
datafly.cache: The datafly․cache package
datafly.db: The datafly․db package
datafly.inflate: The datafly․inflate package
datafly.json: The datafly․json package
datafly.lisp: The datafly/src/datafly․lisp file
datafly.logger: The datafly․logger package
datafly.model: The datafly․model package
datafly.syntax: The datafly․syntax package
datafly.util: The datafly․util package
db.lisp: The datafly/src/db․lisp file

F
File, cache.lisp: The datafly/src/cache․lisp file
File, datafly.asd: The datafly/datafly․asd file
File, datafly.lisp: The datafly/src/datafly․lisp file
File, db.lisp: The datafly/src/db․lisp file
File, inflate.lisp: The datafly/src/inflate․lisp file
File, json.lisp: The datafly/src/json․lisp file
File, logger.lisp: The datafly/src/logger․lisp file
File, model.lisp: The datafly/src/model․lisp file
File, syntax.lisp: The datafly/src/syntax․lisp file
File, util.lisp: The datafly/src/util․lisp file

I
inflate.lisp: The datafly/src/inflate․lisp file

J
json.lisp: The datafly/src/json․lisp file

L
logger.lisp: The datafly/src/logger․lisp file

M
model.lisp: The datafly/src/model․lisp file
Module, src: The datafly/src module

P
Package, datafly: The datafly package
Package, datafly.cache: The datafly․cache package
Package, datafly.db: The datafly․db package
Package, datafly.inflate: The datafly․inflate package
Package, datafly.json: The datafly․json package
Package, datafly.logger: The datafly․logger package
Package, datafly.model: The datafly․model package
Package, datafly.syntax: The datafly․syntax package
Package, datafly.util: The datafly․util package

S
src: The datafly/src module
syntax.lisp: The datafly/src/syntax․lisp file
System, datafly: The datafly system

U
util.lisp: The datafly/src/util․lisp file