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