NAME
Redis::Client - Perl client for Redis 2.4 and up
VERSION
version 0.002
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; # 42DESCRIPTION
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:
- Redis::Client::String
- Redis::Client::List
- Redis::Client::Hash
- Redis::Client::Set
- Redis::Client::Zset
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 );del
Deletes keys. Takes a list of key names. Returns the number of keys deleted.
$client->del( 'foo', 'bar', 'baz' );echo
Returns whatever you send it. Useful for testing only. Takes one argument.
print $client->echo( "Hello, World!" );get
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' );hdel
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
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
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 exists 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' ); # 42hgetall
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
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' );hmget
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
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
Retrieves a list of all the values in a given hash. Takes the hash name.
my @values = $client->hvals( 'myhash' );sadd
Adds members to a set. Takes the names of the set and the members to add.
$client->sadd( 'myset', 'foo', 'bar', 'baz' );srem
Removes members from a set. Takes the names of the set and the members to remove.
$client->srem( 'myset', 'foo', 'baz' );smembers
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
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' ) ) { ... }zadd
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
Returns the cardinality (size) of a sorted set. Takes the name of the sorted set.
my $size = $client->zcard( 'myzset' );zcount
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
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
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
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' );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. :)
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.