
* 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

Download the latest tarball and untar it:

- [[http://download.savannah.gnu.org/releases/guile-redis/guile-redis-1.1.0.tar.gz][guile-redis-1.1.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.

  *Returns* : A reply or a list of replies if a list of commands was
  sent.

  *Throws*

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

  - /redis-invalid/ : 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)


* License

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

Copying and distribution of this file, with or without modification,
are permitted in any medium without royalty provided the copyright
notice and this notice are preserved.  This file is offered as-is,
without any warranty.

Copyright (C) 2013-2018 Aleix Conchillo Flaque <aconchillo@gmail.com>
