
* guile-redis

guile-redis is a Guile module for the [[http://redis.io][redis]] key-value data
store. It provides all commands up to redis 5.0 and supports multiple commands
and pipelining.


* Installation

guile-redis is freely available for download under the terms of the GNU General
Public License version 3 (GPLv3) as well as the GNU Lesser General Public
License version 3 (LGPLv3).

Download the latest tarball and untar it:

- [[http://download.savannah.gnu.org/releases/guile-redis/guile-redis-1.0.0.tar.gz][guile-redis-1.0.0.tar.gz]]

If you are cloning the repository make sure you run this first:

    : $ autoreconf -vif

Then, run the typical sequence:

    : $ ./configure --prefix=<guile-prefix>
    : $ make
    : $ sudo make install

Where <guile-prefix> should preferably be the same as your system Guile
installation directory (e.g. /usr).

If everything installed successfully you should be up and running:

    : $ guile
    : scheme@(guile-user)> (use-modules (redis))
    : scheme@(guile-user)>

It might be that you installed guile-redis somewhere differently than your
system's Guile. If so, you need to indicate Guile where to find guile-redis, for
example:

    : $ GUILE_LOAD_PATH=/usr/local/share/guile/site guile


* Usage

** Procedures

The main interface to the redis server is really simply. It consists on three
procedures, the most important one being /redis-send/ which basically sends
commands to the server.

- (*redis-connect* #:key host port) : Establish a connection to the redis server
  at the given /host/ and /port/ and return a redis connection.

  - /host/ : it defaults to 127.0.0.1.
  - /port/ : it defaults to 6379.

- (*redis-close* connection) : Close the /connection/ to the redis server.

- (*redis-send* connection commands) : Send the given list of /commands/ to the
  redis /connection/. /commands/ can be a single command or a list of
  commands. For a list of commands, a list of all the replies is returned.

  - throws a /redis-error/ exception if the redis server returns an error. The
    exception has the error string as an argument.

  - throws a /redis-invalid/ exception with no argument if server's answer
    cannot be parsed (hopefully, this is unlikely to happen).


** Redis commands

All commands in guile-redis are defined with lower-case and hyphenated in the
case of commands that have two or more words. For example, the command "/CLIENT
LIST/" is defined as /client-list/.

The commands take exaclty the same arguments as defined in the redis manual and
all the arguments are given as strings. For example:

    : (bitfield "mykey" "INCRBY" "i5" "100" "1" "GET" "u4" "0")


** Examples

- Load the module:

    : > (use-modules (redis))

- Create a connection:

    : > (define conn (redis-connect))

- Send a single /PING/ command:

    : > (redis-send conn (ping))
    : "PONG"

- Send a couple of /PING/ commands:

    : > (redis-send conn (list (ping) (ping "hello from guile-redis")))
    : ("PONG" "hello from guile-redis")

- Set a couple of keys:

    : > (redis-send conn (mset "hello" "world" "foo" "bar"))
    : "OK"

- Retrieve the keys just set below:

    : > (redis-send conn (mget "hello" "foo"))
    : ("world" "bar")

- Finally, close the connection:

    : > (redis-close conn)
