redis_client/lib.rs
1//! A redis client implemented in Rust. It's create is called "redis-client".
2//!
3//! # Connection
4//!
5//! All the clients are created with a host and a port:
6//!
7//! ```plain
8//! try!(client::new("127.0.0.1", "6379"));
9//! ```
10//! They are trying to connect when they are created and the new method return a Result with either the client or a RedisError.
11//!
12//! # The clients
13//!
14//! There is more than one client in the library.
15//!
16//! ## RedisClient
17//!
18//! It is used to execute redis commands synchronously.
19//!
20//! For example:
21//!
22//! ```no_run
23//! # use redis_client::commands::CommandSender;
24//! # fn function() -> Result<(), redis_client::errors::RedisError> {
25//! # let mut client = try!(redis_client::RedisClient::new("127.0.0.1", "6379"));
26//! let result: String = try!(client.set("key", "value"));
27//! # Ok(())}
28//! ```
29//!
30//! ## RedisClientAsync
31//!
32//! It is used to execute redis commands synchronously.
33//!
34//! For example:
35//!
36//! ```no_run
37//! # use redis_client::commands::CommandSenderAsync;
38//! # fn function() -> Result<(), redis_client::errors::RedisError> {
39//! # let mut async_client = try!(redis_client::RedisClientAsync::new("127.0.0.1", "6379"));
40//! try!(async_client.get("key", |result| {
41//! let result_value: String = match result {
42//! Ok(value) => value.into(),
43//! Err(err) => err.to_string(),
44//! };
45//! println!("{:?}", result_value);
46//! }));
47//! # Ok(())}
48//! ```
49//! To get the callback to be called once the command execution is over, the pump method needs to be called.
50//!
51//! ## PubSubClientAsync
52//!
53//! It is used for redis Pub/Sub functionnality.
54//!
55//! For example:
56//!
57//! ```no_run
58//! # use redis_client::commands::PubSubCommandAsync;
59//! # fn function() -> Result<(), redis_client::errors::RedisError> {
60//! # let mut pubsub_client = try!(redis_client::PubSubClientAsync::new("127.0.0.1", "6379"));
61//! try!(pubsub_client.subscribe("foo", |cmd_result| {
62//! let cmd_result_value: String = match cmd_result {
63//! Ok(value) => value.into(),
64//! Err(err) => err.to_string(),
65//! };
66//! println!("{:?}", cmd_result_value);
67//! }, |received_value| {
68//! println!("{:?}", received_value);
69//! }
70//! ));
71//!
72//! try!(pubsub_client.publish("foo", "message", |cmd_result| {
73//! let cmd_result_value: String = match cmd_result {
74//! Ok(value) => value.into(),
75//! Err(err) => err.to_string(),
76//! };
77//! println!("{:?}", cmd_result_value);
78//! }
79//! ));
80//! # Ok(())}
81//! ```
82//! The first closure in every method is the one that will be called once the command execution ends. For the subscription methods, the second closure which is the
83//! subscription callback, will be called once a value is received on the required channels. To trigger these calls, the pump method needs to be called.
84//! (NOTE: as multiple value may be received between two calls of the pump method, a subscription callback may be triggered more than once when te pump method is called.)
85//!
86//! # Commands
87//!
88//! ## Built-in Commands
89//!
90//! They are the redis commands implemented in the traits CommandBuilder to build a RedisCommand, or in CommandSender and CommandSenderAsync to send them.
91//!
92//! For example:
93//!
94//! ```no_run
95//! # use redis_client::commands::CommandBuilder;
96//! # fn function() -> Result<(), redis_client::errors::RedisError> {
97//! # let mut client = try!(redis_client::RedisClient::new("127.0.0.1", "6379"));
98//! # let mut async_client = try!(redis_client::RedisClientAsync::new("127.0.0.1", "6379"));
99//! let cmd = &mut redis_client::RedisCommand::new();
100//! cmd.get("key");
101//!
102//! let result: String = try!(client.exec_redis_command(cmd)).into();
103//!
104//! try!(async_client.exec_redis_command_async(cmd, |result| {
105//! let result_value: String = match result {
106//! Ok(value) => value.into(),
107//! Err(err) => err.to_string(),
108//! };
109//! println!("{:?}", result_value);
110//! }));
111//! # Ok(())}
112//! ```
113//!
114//! Is the same as:
115//!
116//! ```no_run
117//! # use redis_client::commands::{CommandSender, CommandSenderAsync};
118//! # fn function() -> Result<(), redis_client::errors::RedisError> {
119//! # let mut client = try!(redis_client::RedisClient::new("127.0.0.1", "6379"));
120//! # let mut async_client = try!(redis_client::RedisClientAsync::new("127.0.0.1", "6379"));
121//! let result: String = try!(client.get("key"));
122//!
123//! try!(async_client.get("key", |result| {
124//! let result_value: String = match result {
125//! Ok(value) => value.into(),
126//! Err(err) => err.to_string(),
127//! };
128//! println!("{:?}", result_value);
129//! }));
130//! # Ok(())}
131//! ```
132//! Some redis commands can have an argument with one or more values. For these ones the rules is to implement two built-in commands,
133//! one for the single value case that have the name of the redis commands and another for the multiple values case with the same name but
134//! prefixed by a m.
135//!
136//! For example:
137//!
138//! ```no_run
139//! # use redis_client::commands::CommandSender;
140//! # fn function() -> Result<(), redis_client::errors::RedisError> {
141//! # let mut client = try!(redis_client::RedisClient::new("127.0.0.1", "6379"));
142//! let result: String = try!(client.del("key"));
143//!
144//! let mresult: String = try!(client.mdel(vec!["key1", "key2"]));
145//! # Ok(())}
146//! ```
147//! Another rule is when a redis commands has behavioral arguments, extra built-in commands are created.
148//! For example:
149//!
150//! ```no_run
151//! # use redis_client::commands::CommandSender;
152//! # fn function() -> Result<(), redis_client::errors::RedisError> {
153//! # let mut client = try!(redis_client::RedisClient::new("127.0.0.1", "6379"));
154//! let result: String = try!(client.setxx("key", "value")); // SET command with the XX argument
155//! # Ok(())}
156//! ```
157//! In the case a behavioral argument is mandatory, only the built-in commands with the arguments are created.
158//! For example lindex has an argument that is either AFTER or BEFORE:
159//!
160//! ```no_run
161//! # use redis_client::commands::CommandSender;
162//! # fn function() -> Result<(), redis_client::errors::RedisError> {
163//! # let mut client = try!(redis_client::RedisClient::new("127.0.0.1", "6379"));
164//! let aresult: String = try!(client.linsert_after("key", "pivot", "value")); // LINSERT with AFTER has an argument
165//! let bresult: String = try!(client.linsert_before("key", "pivot", "value")); // LINSERT with BEFORE has an argument
166//! // let eresult: String = try!(client.linsert("key", "pivot", "value")); DOES NOT EXIST
167//! # Ok(())}
168//! ```
169//! ## Custom Commands
170//!
171//! It is also possible to build custom command and execute them.
172//!
173//! For example:
174//!
175//! ```no_run
176//! # use redis_client::commands::CommandBuilder;
177//! # fn function() -> Result<(), redis_client::errors::RedisError> {
178//! # let mut client = try!(redis_client::RedisClient::new("127.0.0.1", "6379"));
179//! # let mut async_client = try!(redis_client::RedisClientAsync::new("127.0.0.1", "6379"));
180//! let cmd = &mut redis_client::RedisCommand::new();
181//! cmd.add_cmd("GET").add_arg("key").end();
182//!
183//! let result: String = try!(client.exec_redis_command(cmd)).into();
184//!
185//! try!(async_client.exec_redis_command_async(cmd, |result| {
186//! let result_value: String = match result {
187//! Ok(value) => value.into(),
188//! Err(err) => err.to_string(),
189//! };
190//! println!("{:?}", result_value);
191//! }));
192//! # Ok(())}
193//! ```
194//! # Pipeline
195//!
196//! To execute a command pipeline you simply need to create a RedisCommand with one or more redis commands and execute it with a client's pipeline method.
197//! The only difference with the execution of a single command is that the Result contains a vector of RedisResult instead of just a RedisResult.
198//!
199//! Example:
200//!
201//! ```no_run
202//! # use redis_client::commands::CommandBuilder;
203//! # fn function() -> Result<(), redis_client::errors::RedisError> {
204//! # let mut client = try!(redis_client::RedisClient::new("127.0.0.1", "6379"));
205//! # let mut async_client = try!(redis_client::RedisClientAsync::new("127.0.0.1", "6379"));
206//! let cmd = &mut redis_client::RedisCommand::new();
207//! cmd.set("key", "value2").get("key");
208//!
209//! let results = try!(client.exec_redis_pipeline_command(cmd)); // results is a Vec<RedisResult>
210//!
211//! try!(async_client.exec_redis_pipeline_command_async(cmd, |results| {
212//! match results {
213//! Ok(values) => {
214//! for value in values {
215//! println!("{:?}", value.convert::<String>())
216//! }
217//! },
218//! Err(err) => println!("{:?}", err.to_string()),
219//! };
220//! }));
221//! # Ok(())}
222//! ```
223//!
224//! # Redis Transaction
225//! The transaction commands are part of the built-in commands and therefore can be used like any other commmands.
226
227pub use errors::{ParsingError, RedisError};
228pub use redis::{PubSubClientAsync, RedisClient, RedisClientAsync};
229pub use results::RedisResult;
230pub use commands::{CommandBuilder, CommandSender, CommandSenderAsync, PubSubCommandAsync, RedisCommand};
231
232pub mod commands;
233pub mod errors;
234pub mod reader;
235pub mod redis;
236pub mod results;
237pub mod types;