redis-client

A Redis client library for CHICKEN Scheme.

This is a fork of the original redis egg by Daniel Ziltener.

Installation

chicken-install redis-client

Dependencies

SRFI	Description
34	Exception Handling
35	Exception Types
69	Hash Tables
113	Sets and Bags
128	Comparators
152	Strings
158	Generators and Accumulators

API

Exceptions

This library defines an SRFI-35 exception type &redis-error that gets raised when Redis returns an error. The exception type has a single field called redis-error-message containing the error message returned by Redis.

Connection Management

This egg currently uses a simple TCP connection without any "bells and whistles". The two ports are kept in a record of type redis-connection in the fields input and output.

(redis-connect host port #!optional (protocol-version 1))

Connects to a (hopefully) Redis server at host:port, using the given protocol version. Defaults, like Redis itself, to version 1.

Returns two values: the connection object and the HELLO response from the server.

(redis-disconnect rconn)

Disconnects from rconn which must be a redis-connection.

Running Commands

(redis-run rconn command . args)

Uses connection rconn to run command with args. The args will be appended to the command, space-separated. Returns the parsed reply.

(redis-run-proc rconn proc . args)

Calls proc with the output port of the rconn as current output port, optionally with args. Returns the parsed reply.

(redis-read-reply #!optional port)

Reads and parses a single RESP reply from the port. Useful for pub/sub where you need to read multiple replies.

Connection Record Accessors

• (make-redis-connection input output) - Create a connection record
• (redis-connection? obj) - Test if object is a connection
• (redis-connection-input rconn) - Get the input port
• (redis-connection-output rconn) - Get the output port

Parameters

redis-set-comparator

A parameter that specifies the default comparator to be used for sets returned by Redis. It defaults to (make-default-comparator).

Supported Data Types

This Redis client supports all data types up to and including as specified in RESP3.

Simple Strings

Simple strings start with + and are single-line. Returned as Scheme strings.

+this is a simple string.

Simple Errors

Simple errors are like simple strings, but they start with a - instead. They raise an &redis-error condition.

-ERR unknown command 'helloworld'

Blob Strings

Blob strings are longer, potentially multi-line strings. Their sigil is $, followed by an integer designating the string length. Returned as Scheme strings.

$7
chicken

Blob Errors

Analogous to simple errors, blob errors are just blob strings. Receiving one with this Redis library will raise an &redis-error condition.

Verbatim Strings

This is exactly like the Blob string type, but the initial byte is = instead of $. Moreover the first three bytes provide information about the format of the following string, which can be txt for plain text, or mkd for markdown. This library treats verbatim strings exactly like blob strings and won't split off the format info.

Integers

Integers are sent to the client prefixed with :. Returned as Scheme numbers.

:180

Doubles

Doubles are prefixed with ,. The data type also allows inf for positive and -inf for negative infinity. Returned as Scheme numbers.

,1.23

Bignums

Bignums are prefixed with (. Returned as Scheme bignums.

(3492890328409238509324850943850943825024385

Booleans

True and false values are represented as #t and #f, returned as Scheme booleans.

Null

The null type is encoded simply as _, and results in '().

Arrays

Arrays are marked with * followed by the number of entries, and get returned as vectors.

*3
:1
:2
:3

Push Arrays (RESP3)

Push arrays are marked with > and are handled the same as regular arrays. These are used for pub/sub messages.

Maps

Maps are represented exactly as arrays, but instead of using the * byte, the encoded value starts with a % byte. Moreover the number of following elements must be even. Maps represent a sequence of field-value items. They get returned as SRFI-69 hash tables.

%2
+first
:1
+second
:2

Sets

Sets are exactly like the Array type, but the first byte is ~ instead of *. They get returned as SRFI-113 sets using the comparator from redis-set-comparator.

~4
+orange
+apple
#t
#f

Attributes

The attribute type is exactly like the Map type, but instead of the % first byte, the | byte is used. Attributes describe a dictionary exactly like the Map type, however the client should not consider such a dictionary part of the reply, but just auxiliary data that is used in order to augment the reply.

This library returns two values in this case, the first value being the actual data reply from redis, the second one being the attributes.

Example Usage

(import redis-client)

;; Connect to Redis
(define-values (conn hello-response) (redis-connect "localhost" 6379))

;; Run commands
(redis-run conn "SET" "mykey" "myvalue")
(redis-run conn "GET" "mykey")  ;; => "myvalue"

;; Disconnect
(redis-disconnect conn)

Author

Rolando Abarca

This is a fork of the original redis egg by Daniel Ziltener.

License

BSD 3-Clause License. See LICENSE file for details.