README.adoc
1ifdef::generate_manpage[]
2= retcl(n)
3:author: Pietro Cerutti
4:email: gahr@gahr.ch
5:revdate: October 24, 2021
6:revnumber: 0.4.0
7:package: retcl
8:doctype: manpage
9:manmanual: RETCL
10:mansource: RETCL
11:man-linkstyle: pass:[blue R<>]
12
13== Name
14
15Retcl - Redis client library for Tcl
16
17== Synopsis
18
19`package require *retcl*`
20
21`*retcl* create _?objectName?_ _?-noconnect?_ _?host?_ _?port?_`
22
23`set r [*retcl* new _?-noconnect?_ _?host?_ _?port?_]`
24
25`*$r* connect _?host?_ _?port?_`
26
27`*$r* disconnect`
28
29`*$r* connected`
30
31`*$r* _?-sync?_ _?-cb?_ _redisCmd_ _?redisArg ...?_`
32
33`*$r* result _?async?_ _commandId_`
34
35`*$r* resultReady _commandId_`
36
37`*$r* resultType _commandId_`
38
39`*$r* allResults`
40
41`*$r* clearResult _?commandId?_`
42
43`*$r* +async`
44
45`*$r* -async`
46
47`*$r* ?async`
48
49`*$r* +keepCache`
50
51`*$r* -keepCache`
52
53`*$r* ?keepCache`
54
55`*$r* errorHandler _?cmdPrefix?_`
56
57`*$r* pipeline _script_`
58
59`*$r* callback _item_ _?callback?_`
60
61== Description
62endif::generate_manpage[]
63
64ifndef::generate_manpage[]
65= retcl: Tcl client library for Redis
66endif::generate_manpage[]
67
68The retcl module is an event-driven, object-oriented, https://redis.io[Redis]
69client library for the https://www.tcl-lang.org/[Tcl] programming language. The
70library exposes a single `retcl` class, conveniently packaged as a sourceable
71https://www.tcl-lang.org/man/tcl8.6/TclCmd/tm.htm#M9[Tcl module]. Instances of
72this class represent connections to a https://redis.io[Redis] server and are
73used to send requests in the form of native https://redis.io[Redis] commands
74and retrieve responses.
75
76Other than a few book-keeping methods, `retcl` instances transparently
77handle https://redis.io[Redis] commands as first-class methods.
78As an example, `r SET K Hello` can be used to set the value of the key _K_
79to the string _Hello_. This is achieved by proxying all unknown methods to the
80https://redis.io[Redis] server by concatenating all arguments, effectively
81making `retcl` instances completely decoupled from any version of Redis. This
82has several advantages:
83
84* A `retcl` instance does not need to know about the semantics of a
85 particular https://redis.io[Redis] command. This includes syntax checks,
86 context verification and arguments validation, which are offloaded to the
87 https://redis.io[Redis] server. As a consequence, the code base remains clean
88 and small.
89
90* New commands introduced by a server upgrade are immediately available to
91 a live application.
92
93ifndef::generate_manpage[]
94
95[source,tcl]
96----
97package require retcl
98retcl create r
99r SET key val
100r -sync GET key ;# val
101----
102
103endif::generate_manpage[]
104
105ifdef::generate_manpage[]
106== Methods
107endif::generate_manpage[]
108
109=== Construction
110
111[source,tcl]
112----
113set r [retcl new ?-noconnect? ?host? ?port?]
114retcl create r ?-noconnect? ?host? ?port?
115----
116
117Create an instance *r* of `retcl`. By default, the client automatically
118connects to localhost on port 6379. If `-noconnect` is specified, the client is
119created in disconnected mode.
120
121=== Connection / disconnection
122
123[source,tcl]
124----
125$r connect ?host? ?port?
126$r disconnect
127$r connected
128----
129
130The `connect` method can be used to connect to a different host and port. It is
131an error to call this method on an already connected client. The `disconnect`
132method can be called no matter the connection status; it disconnects the client
133from the current host, if any. The `connected` method can be used to query the
134current connection status. It returns a true result if the client is connected
135and a false result otherwise.
136
137=== Interaction with Redis
138
139[source,tcl]
140----
141set rid1 [$r SET key val] ;# rid stands for result id
142$r result $rid1 ;# OK
143
144set rid2 [$r GET key]
145$r result $rid2] ;# val
146
147$r resultType $rid1 ;# SimpleString
148$r resultType $rid2 ;# BulkString
149
150$r -sync GET key ;# val
151
152proc mycb {id type body} {
153 puts " id: $id"
154 puts "type: $type"
155 puts "body: $body"
156}
157
158$r -cb mycb GET key ;# returns immediately and arrange for mycb to be invoked
159 ;# with {rds:1 BulkString val} when the result arrives
160----
161
162As shown in the examples above, the interaction with https://redis.io[Redis] is
163very straightforwards. Any methods not directly understood by the `retcl` class
164are forwarded to the https://redis.io[Redis] server, along with any additional
165arguments provided. The result is a small string representing a result id. Each
166call to https://redis.io[Redis] produces a new result id, which can then
167be queried to inspect its status, type, and value.
168
169By using the `-sync` switch, it is possible to have https://redis.io[Redis]
170commands block and only return as soon as the result is available. In this
171case, the return value is the value returned by https://redis.io[Redis].
172
173By using the `-cb` switch, it is possible to arrange for a callback procedure
174to be called whenever the result is ready. In this case, the command returns
175immediately.
176
177=== Configuration
178
179By default, `retcl` objects operate in asynchronous mode: they return
180immediately and produce a result id (rid) that can be inspected later on. The
181methods `-async`, `+async` and `?async` can be used to disable, enbale, and
182query this setting. The asynchronous behaviour is off, methods wait and
183return the values returned by https://redis.io[Redis] instead of a result id.
184
185A cache of all results is kept by default. This allows to query previously
186returned results. The `-keepcache`, `+keepcache`, and `?keepcache` methods can
187be used to disable, enable, and query this setting. When the results cache is
188disabled, results are removed from the cache as soon as they are retrieved by
189the client.
190
191=== Error handling
192
193A custom error handler can be setup with the `errorHandler` method. The
194argument is a command prefix that gets expanded and additioned with an error
195message string. Passing an empty command prefix resets the error handler to the
196default `error` proc.
197
198=== Pipelining
199
200A pipeline can be built with the `pipeline` method. The argument is a script
201which gets evaluated in the context of the caller. Commands to the
202https://redis.io[Redis] server are held for the duration of the script and
203released as a bulk when the script ends.
204
205=== Publish / subscribe
206
207Publish / subscribe callbacks for specific items can be specified with the
208`callback` method. The `item` argument is a pattern or channel as in PSUBSCRIBE
209and SUBSCRIBE. The `callback` argument is a command prefix. Whenever a message
210arrives on the specific channel, the command prefix is called by appending the
211type of the message, the pattern that was subscribed to, the actual channel,
212and the payload.
213
214ifdef::generate_manpage[]
215== Resources
216
217[%hardbreaks]
218Project page: https://gahr.github.io/retcl
219Project code repository: https://github.com/gahr/retcl
220
221== Copying
222
223Copyright (C) 2014-2018 {author}.
224Free use of this software is granted under the terms of the BSD-2-Clause
225License.
226endif::generate_manpage[]
227