An object-hash mapping for Redis in Common Lisp

cl-ohm

#+title: CL-OHM
#+date: [2016-01-30 Sat]
#+language: en
#+startup: showall

[[http://quickdocs.org/cl-ohm/][file:http://quickdocs.org/badge/cl-ohm.svg]]
[[https://opensource.org/licenses/MIT][file:https://img.shields.io/badge/License-MIT-yellow.svg]]
[[https://travis-ci.org/rudolfochrist/cl-ohm][file:https://travis-ci.org/rudolfochrist/cl-ohm.svg?branch=master]]
[[https://coveralls.io/github/rudolfochrist/cl-ohm?branch=master][file:https://coveralls.io/repos/github/rudolfochrist/cl-ohm/badge.svg?branch=master]]

This is an implementation of [[http://ohm.keyvalue.org/][Ohm]] in Common Lisp with some inspiration from [[http://eudoxia.me/crane/][Crane]] and [[https://github.com/fukamachi/datafly][datafly]].

Ohm is an object-hash mapping for [[http://redis.io/][Redis]].

* Usage

** Starting and connecting Redis

First of all, Redis must be up and running. You can start Redis with the command line

: $ redis-server

Then load =CL-OHM=:

: (ql:quickload :cl-ohm)

Without configuration Redis runs on =localhost:6379=. If you're using a different host or port you have to
configure =CL-OHM=. For example, if Redis is running on =198.162.55.12= on port =12455= than you must setup
CL-OHM like this:

#+BEGIN_SRC lisp
(ohm:setup-redis-connection :host #(198 162 55 12) :port 12455)
#+END_SRC

** Mapping objects to Redis

Use =ohm:define-ohm-model= to specify your models.

#+BEGIN_SRC lisp :export code
(ohm:define-ohm-model person ()
  :attributes ((first-name :indexp t)
               (last-name :indexp t)
               (email :uniquep t)))
#+END_SRC

You can create new persisted objects with =CREATE=:

#+BEGIN_SRC lisp
(ohm:create 'person :first-name "John" :last-name "McCarthy")
#+END_SRC

Attributes are setfable like ordinary objects slots (Note: if you don't provide readers or writers
for an attribute, an accessor will be created) but has to be *explicitly saved to be persisted*.

#+BEGIN_SRC lisp
(ohm:create 'person :first-name "Bill")
(setf (first-name *) "William")
(ohm:save **)
#+END_SRC

** Loading objects from the data store

When you know an object's ID then you can load it with =filter-id=

#+BEGIN_SRC lisp
(ohm:filter-id 'person "5")
;;; or
(ohm:filter-id 'person 5)
#+END_SRC

*** Indexes

For each attribute marked with =:INDEXP= and index gets created. With this index it is possible to load
objects by their values.

#+BEGIN_SRC lisp
(ohm:filter 'person :first-name "Bill")
#+END_SRC

This load all objects with =first-name=Bill=. Indexed attributes can be combined in =FILTER=.

#+BEGIN_SRC lisp
(ohm:filter 'person :first-name "Bill" :last-name "Miller")
#+END_SRC

If you omit any attribute specifiers from =FILTER= than all objects for the given type are retrieved.

#+BEGIN_SRC lisp
(ohm:filter 'person)
#+END_SRC

** Unique values

Each attribute marked as =:UNIQUEP= must be unique for all instances of a given model. Considering the
=person= model from above this means two instances cannot have the same =email=. =:UNIQUEP= also creates an
index, query-able with =FILTER-WITH=.

#+BEGIN_SRC lisp
(ohm:filter-with 'person :email "e@example.org")
#+END_SRC

This load the =person= object with =email=e@example.org=

** Counters

Counters let you count atomically.

#+BEGIN_SRC lisp
(ohm:define-ohm-model candidate (person)
  :counters (votes))

(let ((candidate (create 'candidate :first-name "Bill")))
  (ohm:incr (votes candidate))
  (ohm:incr (votes candidate))

  (ohm:counter (votes candidate))       ;=> 2

  (ohm:decr (votes candidate) 2)

  (ohm:counter (votes candidate)))      ;=> 0
#+END_SRC

** Sets and Lists

Each model can define sets or lists as attributes. Sets and lists can hold other persisted objects defined by
=DEFINE-OHM-MODEL=. Therefore you most provide the set's or list's element-type.

#+BEGIN_SRC lisp
(ohm:define-ohm-model tag ()
  :attributes ((name :indexp t)))

(ohm:define-ohm-model post ()
  :lists ((authors :element-type person))
  :sets ((tags :element-type tag)))
#+END_SRC

=CL-OHM= persisted objects are internally stored in sets.
#+BEGIN_SRC lisp
(ohm:create 'person :first-name "Donald" :last-name "Duck")
(ohm:filter 'person) ;=> #<CL-OHM::OHM-SET {1009FAB643}>
#+END_SRC

This lets you combine the =FITLER= function with set operations.

*** Set operations

Creating some test data:

#+BEGIN_SRC lisp :results silent
(ohm:create 'person :first-name "Donald" :last-name "Duck")
(ohm:create 'person :first-name "Daisy" :last-name "Duck")
(ohm:create 'person :first-name "Gladstone" :last-name "Gander")
#+END_SRC

Creating the union of persons named *Duck* and persons named *Gander*:

#+BEGIN_SRC lisp
(ohm:elements (ohm:union (ohm:filter 'person :last-name "Duck")
                         (ohm:filter 'person :last-name "Gander")))
#+END_SRC

#+RESULTS:
: (#<PERSON CL-OHM::ID="1" FIRST-NAME="Donald" LAST-NAME="Duck" {1008745153}>
:  #<PERSON CL-OHM::ID="2" FIRST-NAME="Daisy" LAST-NAME="Duck" {1008745333}>
:  #<PERSON CL-OHM::ID="3" FIRST-NAME="Gladstone" LAST-NAME="Gander"
:    {1008745513}>)

Use =EXCEPT= to exclude objects with specific properties. Say, exclude persons named *Gander* from all persons:

#+BEGIN_SRC lisp
(ohm:elements (ohm:except (ohm:filter 'person) ; all persons
                          (ohm:filter 'person :last-name "Gander")))
#+END_SRC

#+RESULTS:
: (#<PERSON CL-OHM::ID="1" FIRST-NAME="Donald" LAST-NAME="Duck" {1008AA3963}>
:  #<PERSON CL-OHM::ID="2" FIRST-NAME="Daisy" LAST-NAME="Duck" {1008AA3B43}>)

Use =COMBINE= to limit the resulting set. Say, all persons with last name *Duck* and first name *Donald*:

#+BEGIN_SRC lisp
(ohm:elements (ohm:combine (ohm:filter 'person :last-name "Duck")
                           (ohm:filter 'person :first-name "Donald")))
#+END_SRC

#+RESULTS:
: (#<PERSON CL-OHM::ID="1" FIRST-NAME="Donald" LAST-NAME="Duck" {1008C6B8F3}>)

** Persistence Strategy

Sets, lists and counters are stored implicitly after their mutation. If you change normal attributes (with
=SETF=) then those objects have to be persisted with =SAVE=.

* API Documentation

See [[https://htmlpreview.github.io/?https://github.com/rudolfochrist/cl-ohm/blob/master/docs/cl-ohm-0.2.1.html#CL-OHM][CL-OHM HTML Documentation]].

* Running the tests

CL-OHM uses [[https://common-lisp.net/project/fiveam/docs/index.html][FiveAM]] for testing. Please installed it with

: (ql:quickload :fiveam)

Then you can run the test through ASDF:

: (asdf:test-system :cl-ohm)

* License

[[file:LICENSE][MIT Copyright (c) 2016 Sebastian Christ]]


cl-ohm

Upstream URL

Author

License

cl-ohm

Version:

License:

Authors:

Dependencies:

cl-ohm/test

Dependencies:

Dependencies (4)

Dependents (0)