/ 
Redis-Client-0.009
River stage zero No dependents
/ Redis::Client

NAME

Redis::Client - Perl client for Redis 2.4 and up

VERSION

version 0.009

SYNOPSIS

use Redis::Client;

my $client = Redis::Client->new( host => 'localhost', port => 6379 );

# work with strings
$client->set( some_key => 'myval' );
my $str_val = $client->get( 'some_key' );
print $str_val;        # myval

# work with lists
$client->lpush( some_list => 1, 2, 3 );
my $list_elem = $client->lindex( some_list => 2 );
print $list_elem;      # 3

# work with hashes
$client->hset( 'some_hash', foobar => 42 );
my $hash_val = $client->hget( 'some_hash', 'foobar' );
print $hash_val;      # 42

DESCRIPTION

Redis::Client is a Perl-native client for the Redis (http://redis.io) key/value store. Redis supports storage and retrieval of strings, ordered lists, hashes, sets, and ordered sets.

Redis::Client uses the new binary-safe Unified Request Protocol to implement all of its commands. This requires that Redis::Client be able to get accurate byte-length counts of all strings passed to it. Therefore, if you are working with character data, it MUST be encoded to a binary form (e.g. UTF-8) before you send it to Redis; otherwise the string lengths may be counted incorrectly and the requests will fail. Redis guarantees round-trip safety for binary data.

This distribution includes classes for working with Redis data via tie based objects that map Redis items to native Perl data types. See the documentation for those modules for usage:

INSTALLATION

Redis::Client can be installed the usual way via CPAN. In order to run the test suite, Redis::Client needs to know about a Redis server that it can talk to. Make sure to set the following environment variables prior to installing this distribution or running the test suite.

  • PERL_REDIS_TEST_SERVER - the hostname of the Redis server (default localhost).

  • PERL_REDIS_TEST_PORT - the port number of the Redis server (default 6379).

  • PERL_REDIS_TEST_PASSWORD - (optional) the Redis server password (default undef).

All keys generated by the test suite will have the prefix perl_redis_test. Unless something goes wrong, they'll all be deleted when each test is completed.

CLASS METHODS

new

Constructor. Returns a new Redis::Client object for talking to a Redis server. Throws a fatal error if a connection cannot be obtained.

host

The hostname of the Redis server. Defaults to localhost.

port

The port number of the Redis server. Defaults to 6379.

Redis connection passwords are not currently supported.

my $client = Redis::Client->new( host => 'foo.example.com', port => 1234 );

KEY METHODS

del

Redis DEL command.

Deletes keys. Takes a list of key names. Returns the number of keys deleted.

$client->del( 'foo', 'bar', 'baz' );

type

Redis TYPE command.

Retrieves the type of a key. Takes the key name and returns one of string, list, hash, set, or zset.

my $type = $client->type( 'some_key' );

STRING METHODS

get

Redis GET command.

Retrieves a string value associated with a key. Takes one key name. Returns undef if the key does not exist. If the key is associated with something other than a string, a fatal error is thrown.

print $client->get( 'mykey' );

append

Redis APPEND command.

Appends a value to the end of a string. Takes the key name and a value to append. Returns the new length of the string. If the key is not a string, a fatal error is thrown.

my $new_length = $client->append( mykey => 'foobar' );

decr

Redis DECR command.

Decrements a number stored in a string. Takes the key name and returns the decremented value. If the key does not exist, zero is assumed and decremented to -1. If the key is not a string, a fatal error is thrown.

my $new_val = $client->decr( 'my_num' );

decrby

Redis DECRBY command.

Decrements a number stored in a string by a certain amount. Takes the key name and the amount by which to decrement. Returns the new value. If the key is not a string, a fatal error is thrown.

my $new_val = $client->decrby( 'my_num', 3 );

get

Redis GET command.

Returns the value of a string. Takes the key name. If the key is not a string, a fatal error is thrown.

my $val = $client->get( 'my_key' );

getrange

Redis GETRANGE command.

Returns a substring of a string, specified by a range. Takes the key name and the start and end offset of the range. Negative numbers count from the end. If the key is not a string, a fatal error is thrown.

my $substr = $client->getrange( 'my_key', 3, 5 );
my $substr = $client->getrange( 'my_key', -5, -1 );  # last five

getset

Redis GETSET command.

Sets the value of a string and returns the old value atomically. Takes the key name and the new value. If the key is not a string, a fatal error is thrown. If the key does not exist, it is created and undef is returned.

my $old_val = $client->getset( my_key => 'new value' );

incr

Redis INCR command.

Increments a number stored in a string. Takes the key name and returns the incremented value. If the key does not exist, zero is assumed and incremented to 1. If the key is not a string, a fatal error is thrown.

my $new_val = $client->incr( 'my_num' );

incrby

Redis INCRBY command.

Increments a number stored in a string by a certain amount. Takes the key name and the amount by which to increment. Returns the new value. If the key is not a string, a fatal error is thrown.

my $new_val = $client->incrby( 'my_num', 3 );

mget

Redis MGET command.

Gets the values of multiple strings. Takes the list of key names to get. If a key does not exist or if it is not a string, undef will be returned in its place.

my @vals = $client->mget( 'foo', 'bar', baz' );
print $vals[2];    # value of baz

mset

Redis MSET command.

Sets the values of multiple strings. Takes a list of key/value pairs to set. If a key does not exist, it will be created. If a key is not a string, it will be silently converted to one. Therefore, use with caution.

$client->mset( foo => 1, bar => 2, baz => 3 );

msetnx

Redis MSETNX command.

Atomically sets the values of multiple strings, only if none of the keys yet exist. Returns 1 on success, 0 otherwise.

my $it_worked = $client->msetnx( foo => 1, bar => 2, baz => 3 );

set

Redis SET command.

Sets the value of a string. Takes the key name and a value.

$client->set( my_key => 'foobar' );

setbit

Redis SETBIT command.

Sets the value of one bit in a string. Takes the key name, offset of the bit, and new value. Returns the original value of the bit. If the key is not a string or if the bit value is not 0 or 1, a fatal error is thrown.

my $old_bit = $client->setbit( 'my_key', 3, 1 );

setex

Redis SETEX command.

Sets the value of a string and its expiration time in seconds. Takes the key name, the expiration time, and the value.

$client->setex( 'my_key', 5, 'foo' );   # goes bye-bye in 5 secs.

setnx

Redis SETNX command.

Sets the value of a string, only if it does not yet exist. Takes the key name and value. Returns 1 on success, 0 otherwise.

my $key_was_set = $client->setnx( my_key => 'foobar' );

setrange

Redis SETRANGE command.

Sets the value of a substring of a string. Takes the key name, the offset, and a replacement string. Returns the length of the modified string. If the key is not a string, a fatal error is thrown.

$client->set( my_key => "I'm a teapot." );
my $new_length = $client->setrange( 'my_key', 6, 'foobar' ); # I'm a foobar.

strlen

Redis STRLEN command.

Returns the length of a string. Takes the key name. If the key is not a string, a fatal error is thrown.

my $length = $client->strlength( 'my_key' );

LIST METHODS

blpop

Redis BLPOP command.

Blocking left list pop. Takes a list of keys to poll and a timeout in seconds. Returns a two-element list containing the name of the list and the popped value on success, undef otherwise. Returns immediately if a value is waiting on any of the specified lists, otherwise waits for a value to appear or the timeout to expire. A timeout of zero waits forever.

my ( $list, $value ) = $client->blpop( 'list1', 'list2', 5 ); # wait 5 secs

See lpop for the non-blocking version.

brpop

Redis BRPOP command.

Blocking right list pop. Takes a list of keys to poll and a timeout in seconds. Returns a two-element list containing the name of the list and the popped value on success, undef otherwise. Returns immediately if a value is waiting on any of the specified lists, otherwise waits for a value to appear or the timeout to expire. A timeout of zero waits forever.

my ( $list, $value ) = $client->brpop( 'list1', 'list2', 5 ); # wait 5 secs

See rpop for the non-blocking version.

lindex

Redis LINDEX command.

Retrieves the value stored at a particular index in a list. Takes the list name and the numeric index.

my $val = $client->lindex( 'my_list', 42 );

lset

Redis LSET command.

Sets the value at a particular index in a list. Takes the list name, the numeric index, and the new value.

$client->lset( 'my_list', 42, 'yippee!' );

llen

Redis LLEN command.

Retrieves the number of items in a list. Takes the list name.

my $length = $client->llen( 'my_list' );

ltrim

Redis LTRIM command.

Removes all elements of a list outside of the specified range. Takes the list name, start index, and stop index. All keys between the start and stop indices (inclusive) will be preserved. The rest will be deleted. The list is shifted down if the start index is not zero. The stop index -1 can be used to select everything until the end of the list.

# get rid of first two elements.
$client->ltrim( 'my_list', 2, -1 );

rpush

Redis RPUSH command.

Adds items to the end of a list, analogous to the Perl push operator. Takes the list name and a list of items to add. Returns the length of the list when done.

my $new_length = $client->rpush( my_list => 42, 43, 'narf', 'poit' );

rpop

Redis RPOP command.

Removes and returns the last element of a list, analogous to the Perl pop operator.

my $last = $client->rpop( 'my_list' );

lpush

Redis LPUSH command.

Adds items to the beginning of a list, analogous to the Perl unshift operator. Takes the list name and a list of items to add. Returns the length of the list when done.

my $new_length = $client->lpush( my_list => 1, 2, 3 );

lpop

Redis LPOP command.

Removes and returns the first element of a list, analogous to the Perl shift operator.

my $first = $client->lpop( 'my_list' );

HASH METHODS

hdel

Redis HDEL command.

Deletes keys from a hash. Takes the name of a hash and a list of key names to delete. Returns the number of keys deleted. Returns zero if the hash does not exist, or if none of the keys specified exist in the hash.

$client->hdel( 'myhash', 'foo', 'bar', 'baz' );

hexists

Redis HEXISTS command.

Returns a true value if a key exists in a hash. Takes a hash name and the key name.

blah() if $client->hexists( 'myhash', 'foo' );

hget

Redis HGET command.

Retrieves a value associated with a key in a hash. Takes the name of the hash and the key within the hash. Returns undef if the hash or the key within the hash does not exist. (Use "hexists" to determine if a key exists at all.)

# sets the value for 'key' in the hash 'foo'
$client->hset( 'foo', key => 42 );

print $client->hget( 'foo', 'key' );   # 42

hgetall

Redis HGETALL command.

Retrieves all of the keys and values in a hash. Takes the name of the hash and returns a list of key/value pairs.

my %hash = $client->hgetall( 'myhash' );

hkeys

Redis HKEYS command.

Retrieves a list of all the keys in a hash. Takes the name of the hash and returns a list of keys.

my @keys = $client->hkeys( 'myhash' );

hlen

Redis HLEN command.

Retrieves the number of keys in a hash. Takes the name of the hash.

my $size = $client->hlen( 'myhash' );

hmget

Redis HMGET command.

Retrieves a list of values associated with the given keys in a hash. Takes the name of the hash and a list of keys. If a given key does not exist, undef will be returned in the corresponding location in the result list.

my @values = $client->hmget( 'myhash', 'key1', 'key2', 'key3' );

hmset

Redis HMSET command.

Sets a list of key/value pairs in a hash. Takes the hash name and a list of keys and values to set.

$client->hmset( 'myhash', foo => 1, bar => 2, baz => 3 );

hvals

Redis HVALS command.

Retrieves a list of all the values in a given hash. Takes the hash name.

my @values = $client->hvals( 'myhash' );

SET METHODS

sadd

Redis SADD command.

Adds members to a set. Takes the names of the set and the members to add.

$client->sadd( 'myset', 'foo', 'bar', 'baz' );

srem

Redis SREM command.

Removes members from a set. Takes the names of the set and the members to remove.

$client->srem( 'myset', 'foo', 'baz' );

smembers

Redis SMEMBERS command.

Returns a list of all members in a set, in no particular order. Takes the name of the set.

my @members = $client->smembers( 'myset' );

sismember

Redis SISMEMBER command.

Returns a true value if the given member is in a set. Takes the names of the set and the member.

if ( $client->sismember( 'myset', foo' ) ) { ... }

SORTED SET METHODS

zadd

Redis ZADD command.

Adds members to a sorted set (zset). Takes the sorted set name and a list of score/member pairs.

$client->zadd( 'myzset', 1 => 'foo', 2 => 'bar', 3 => 'baz' );

(The ordering of the scores and member names may seem backwards if you think of zsets as rough analogs of hashes. That's just how Redis does it.)

zcard

Redis ZCARD command.

Returns the cardinality (size) of a sorted set. Takes the name of the sorted set.

my $size = $client->zcard( 'myzset' );

zcount

Redis ZCOUNT command.

Returns the number of members in a sorted set with scores between two values. Takes the name of the sorted set and the minimum and maximum

my $count = $client->zcount( 'myzset', $min, $max );

zrange

Redis ZRANGE command.

Returns all the members of a sorted set with scores between two values. Takes the name of the sorted set, a minimum and maximum, and an optional boolean to control whether or not the scores are returned along with the members.

my @members = $client->zrange( 'myzset', $min, $max );
my %members_scores = $client->zrange( 'myzset', $min, $max, 1 );

zrank

Redis ZRANK command.

Returns the index of a member within a sorted. set. Takes the names of the sorted set and the member.

my $rank = $client->zrank( 'myzset', 'foo' );

zscore

Redis ZSCORE command.

Returns the score associated with a member in a sorted set. Takes the names of the sorted set and the member.

my $score = $client->zscore( 'myzset', 'foo' );

CONNECTION METHODS

echo

Redis ECHO command.

Returns whatever you send it. Useful for testing only. Takes one argument.

print $client->echo( "Hello, World!" );

=str_methdod getbit

Returns the value of one bit in a string. Takes the key name and the offset of the bit. If the offset is beyond the length of the string, 0 is returned. If the key is not a string, a fatal error is thrown.

my $bit = $client->getbit( 'my_key', 4 );    # fifth bit from left

CAVEATS

This early release is not feature-complete. I've implemented all the Redis commands that I use, but there are several that are not yet implemented. There is also no support for Redis publish/subscribe, but I intend to add that soon. Patches welcome. :)

The MONITOR command will probably not be supported any time soon since it would require some kind of asynchronous solution and does not use the URP.

EXTENDS

CONSUMES

AUTHOR

Mike Friedman <friedo@friedo.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by Mike Friedman.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.