Changeset 39489 in project


Ignore:
Timestamp:
01/10/21 04:30:25 (3 months ago)
Author:
svnwiki
Message:

Anonymous wiki edit for IP [2.83.241.62]: Update transmission docs (0.2.1)

File:
1 edited

Legend:

Unmodified
Added
Removed
  • wiki/eggref/5/transmission

    r39427 r39489  
    77=== Description
    88
    9 An egg to work with [[https://github.com/transmission/transmission|Transmission]]'s
    10 RPC. It assumes familiarity with the [[https://github.com/transmission/transmission/blob/master/extras/rpc-spec.txt|spec]].
     9An egg to work with the
     10[[https://github.com/transmission/transmission|Transmission]] (v3.01)
     11[[https://github.com/transmission/transmission/wiki/RPC-Protocol-Specification|RPC
     12protocol]] (v17). It assumes familiarity with the
     13[[https://github.com/transmission/transmission/blob/f59118d1fe6a320d797b151a6f235f739ef3b487/extras/rpc-spec.txt|spec]].
     14
     15This egg may still work with a more recent version of the spec, but it's not
     16guaranteed. An example of a change in the spec that doesn't require any change
     17in the API is this:
     18
     19<enscript>
     2017    | 3.01    | yes       | torrent-get          | new arg "file-count"
     2117    | 3.01    | yes       | torrent-get          | new arg "primary-mime-type"
     22</enscript>
     23
     24This is because the library doesn't check if the fields are valid (this is
     25intentional).
     26
     27These changes, however:
     28
     29<enscript>
     3016    | 3.00    | yes       | session-get          | new request arg "fields"
     3116    | 3.00    | yes       | torrent-get          | new request arg "format"
     3216    | 3.00    | yes       | torrent-set          | new arg "labels"
     33</enscript>
     34
     35Require API changes, because otherwise the {{fields}} and {{format}}
     36arguments can't be used.
    1137
    1238=== Author
     
    113139or {{result/ok}}.
    114140
    115 <procedure>(default-error-proc result tag req resp)</procedure>
     141<procedure>(default-error-proc result/con #!optional tag req resp)</procedure>
    116142<procedure>(with-transmission-result result success-proc #!optional (error-proc default-error-proc))</procedure>
    117143
     
    119145
    120146{{with-transmission-result}} is similar to {{result-ref}} ({{either-ref}} from
    121 SRFI-189)), except that the order of the success and failure procedures is
     147SRFI-189), except that the order of the success and failure procedures is
    122148swapped. The failure procedure defaults to {{default-error-proc}}, which calls
    123149{{error}} with a generic error message.
     
    127153{{intarweb}} response object.
    128154
    129 {{failure-proc}} should be a procedure that accepts 1 or 4 parameters: if only
    130 one argument is given, it is a condition; if 4 arguments are given, they are
    131 the {{result}} and {{tag}} fields of a reply message, the {{uri-common}}
    132 request object, and the {{intarweb}} response object.
     155{{failure-proc}} should be a procedure of 4 parameters, 3 of them optional:
     156{{result/con}}, {{tag}}, {{req}}, and {{resp}}. {{result}} and {{tag}} are the
     157fields of a reply message, {{req}} is the {{uri-common}} request object, and
     158{{resp}} is the {{intarweb}} response object. {{tag}}, {{req}}, and {{resp}}
     159are either all false or none false. If they're false, {{result/con}} is a
     160{{condition}} object thrown during the API call; if they're not false, then
     161{{result/con}} is a {{result}} string.
    133162
    134163===== Low-level API
     
    184213==== {{transmission.utils}} module
    185214
    186 <syntax>(alist-let alist (key ...) body ...)</syntax>
    187 <syntax>(alist-let/and alist (key ...) body ...)</syntax>
    188 <syntax>(alist-let/nor alist (key ...) body ...)</syntax>
     215<syntax>(alist-let alist (formal ...) body ...)</syntax>
     216<syntax>(alist-let/and alist (formal ...) body ...)</syntax>
     217<syntax>(alist-let/nor alist (formal ...) body ...)</syntax>
     218
     219Where {{formal}} is either {{key}}, which will be used both as the key name and
     220the variable, or {{(var key)}}, which will be the variable name and key
     221respectively.
    189222
    190223Equivalent to:
    191224
    192225<enscript highlight="scheme">
    193 (let ((key (alist-ref 'key alist))
     226(let ((var (alist-ref 'key alist))
    194227      ...)
    195228  body
     
    197230</enscript>
    198231
    199 Except that, with {{alist-let/and}}, if {{alist}} is false, the value of the
    200 whole expression is false; and with {{alist-let/nor}}, if {{alist}} is false,
    201 the value of the whole expression is true.
     232Except that, with {{alist-let/and}}, if {{alist}} is false, the whole
     233expression evaluates to false; and with {{alist-let/nor}}, if {{alist}} is
     234false, the whole expression evaluates to true.
     235
     236Example:
     237
     238<enscript highlight="scheme">
     239(alist-let/and '((ant . 3) (bunny . 5) (Cat . 3))
     240               (ant bunny (cat Cat))
     241  (list ant bunny  cat))
     242</enscript>
     243
     244Expands to something like this:
     245
     246<enscript highlight="scheme">
     247(let ((%alist '((ant . 3) (bunny . 5) (Cat . 3))))
     248  (let ((ant (alist-ref 'ant %alist))
     249        (bunny (alist-ref 'bunny %alist))
     250        (cat (alist-ref 'Cat %alist)))
     251  (list ant bunny cat)))
     252</enscript>
    202253
    203254<procedure>(unique-tag! #!optional (new-n #f))</procedure>
     
    231282               (*username* "username")
    232283               (*password* "password"))
    233   (with-transmission-result
    234     (torrent-get '("downloadDir" "id" "name" "status" "uploadRatio") #:ids #f)
    235     (lambda (arguments . _)
    236       (define (want-torrent? tor)
    237         (alist-let/and tor (downloadDir status uploadRatio)
    238                        (and (= status status/seed)
    239                             (> uploadRatio 1)
    240                             (string=? downloadDir "/some/path/"))))
    241       (alist-let/and arguments (torrents)
    242                      (let ((wanted-tors (filter want-torrent? (vector->list torrents))))
    243                        (for-each print wanted-tors))))
    244     (lambda (result . _)
    245       (error 'here "torrent-get call failed with the following error" result))))
     284  (let ((tag (unique-tag!)))
     285    (with-transmission-result
     286      (torrent-get '("downloadDir" "id" "name" "status" "uploadRatio") #:ids #f #:tag tag)
     287      (lambda (arguments tag req resp)
     288        (define (want-torrent? tor)
     289          (alist-let/and tor (downloadDir status uploadRatio)
     290                         (and (= status status/seed)
     291                              (> uploadRatio 1)
     292                              (string=? downloadDir "/some/path/"))))
     293        (alist-let/and arguments (torrents)
     294                       (let ((wanted-tors (filter want-torrent? (vector->list torrents))))
     295                         (for-each print wanted-tors))))
     296      ; NOTE: The error case handling procedure doesn't have to accept
     297      ;       #!optional arguments -- the "missing" arguments will be #f.
     298      (lambda (result tag req resp)
     299        (error 'here "torrent-get call failed with the following error" result)))))
    246300</enscript>
    247301
     
    275329=== Version History
    276330
     331==== 0.2.1 (2021/01/10)
     332
     333* {{default-error-proc}} now supports the case where the result was just a
     334  condition;
     335
     336* Add (hopefully) useful example programs to the {{examples}} directory -- you
     337  can get these from the repo or the {{chicken-install}} cache directory;
     338
     339* Export {{alist-let}} from {{transmission.utils}}.
     340
    277341==== 0.2.0 (2020/12/09)
    278342
     
    282346
    283347* Improve {{alist-let/and}} and {{alist-let/nor}} to support optional variable
    284   names;
     348  names, and save the value resulting of evaluating the alist expression;
    285349
    286350* Add {{priority}} constants;
Note: See TracChangeset for help on using the changeset viewer.