Browse code

Updated documentation

Jaidyn Levesque authored on 2019-06-18 17:45:31
Showing 2 changed files
... ...
@@ -1,9 +1,11 @@
1 1
 ===============================================================================
2
-CL-IPFS-API²                                      Binder for galactic transguys
2
+CL-IPFS-API²                                   For space-orientied lisp weenies
3 3
 ===============================================================================
4 4
 
5 5
 :cl-ipfs-api² is a pretty simple set of IPFS bindings for Common Lisp, using
6
-the HTTP API. It uses Dexador for HTTP(S) requests and YASON for JSON.
6
+the HTTP API for (almost) everything, except for pubsub (which uses the locally
7
+installed go-ipfs program).
8
+It uses Dexador, YASON, and UIOP.
7 9
 
8 10
 
9 11
 ————————————————————————————————————————
... ...
@@ -15,8 +17,6 @@ and you're good).
15 17
 Then you can do things like:
16 18
 	> (ipfs:add #p"~/.bashrc")
17 19
 	"QmZweanA1JRNio6DKnPN6yECWCrxmWqqG7WWUNtyuji9hZ"
18
-	145
19
-	".bashrc"
20 20
 
21 21
 	> (ipfs:cat "/ipns/ipfs.io/index.html")
22 22
 	"<!DOCTYPE html>
... ...
@@ -24,16 +24,74 @@ Then you can do things like:
24 24
 
25 25
 Most commands available are one-to-one with their API/cli counter-parts,
26 26
 with a few notable exceptions:
27
-	* #'dl	(counter-part to the /get call)
27
+	* #'dl	(counter-part to the /get call. the name is different, so
28
+	         as to not conflict with #'common-lisp:get)
28 29
 
29 30
 The calls implemented so far:
30
-	* root calls (cat, add, id, ls, resolve, etc)
31
-	* cid calls
32
-	* config calls (config, config/show)
33
-	* version calls (version, version/deps)
31
+	* root (cat, add, id, ls, resolve, etc)
32
+	* bitswap, block, bootstrap
33
+	* cid, config (config, config/show)
34
+	* dag, dht, diag
35
+	* file, files, filestore
36
+	* key, name, object
37
+	* p2p, pin, pubsub
38
+	* version (version, version/deps)
34 39
 
35
-Functions return either strings, lists, or hash-tables (parsed JSON)--
36
-depending on context, of course. Read docstrings ♥
40
+Some calls were skipped over, but wouldn't be hard to add:
41
+	* object/put, object/set-data object/patch/append-data
42
+
43
+Functions return either strings, lists, or associative lists, depending on
44
+context. All errors return two values— nil and an error message (string).
45
+Make sure to read docstrings ☆
46
+
47
+
48
+————————————————————————————————————————
49
+PUBSUB USAGE
50
+————————————————————————————————————————
51
+Pubsub usage here is such an abberation that it warrants its own section.
52
+Since there isn't a (functional) HTTP API for pubsub yet, we're using the
53
+actual go-ipfs program from your computer.
54
+
55
+If you don't have go-ipfs locally installed, it won't work.
56
+If you are using Windows, or anything but *nix, it probably won't work.
57
+If you haven't enabled pubsub (--enable-pubsub-experiment argument to daemon),
58
+it won't work.
59
+
60
+Well… here we go.
61
+
62
+You can sub to a topic with, ofc, #'pubsub-sub, which will return a
63
+UIOP-originated process-info stream— while the `ipfs pubsub sub` command runs
64
+in the background.
65
+
66
+This stream can't be directly #'read-char or #'listen with, which is exactly
67
+what you wanna do— instead, running #'uiop/launch-program:process-info-output
68
+on it is necessary to expose a usable stream.
69
+
70
+To make all that easier, there's a little abstraction I added which obfuscates
71
+UIOP use and is adequate shorthand:
72
+	* #'pubsub-sub-read-char
73
+	* #'pubsub-sub-listen
74
+	* #'pubsub-sub-process
75
+	* #'pubsub-sub-close
76
+
77
+All of those operate on the original UIOP-originated process-info stream, and
78
+work exactly like you'd expect.
79
+The only weird, non-obvious one is probably #'pubsub-sub-process, which applies
80
+#'uiop/launch-program:process-info-output— just in case you need the raw,
81
+usable stream.
82
+
83
+Anyway, with this, you can get a continuous read on what's going on with the
84
+topic you're subbed to. To publish to a topic, run #'pubsub-pub with the topic
85
+and data as arguments. Pretty simple.
86
+
87
+Both #'pubsub-sub and #'pubsub-pub, being the only functions that run a shell
88
+command, include an :env argument. If you supply a string as the :env argument,
89
+that string will prefix the "ipfs" command— basically only useful for changing
90
+something with the "env" command (like $IPFS_PATH).
91
+
92
+Also, if you change the ipfs:*ipfs-root* variable (to the correct value of
93
+$IPFS_PATH), the :env arguments (unless otherwise specified) will default to
94
+"env IPFS_PATH=" + ipfs:*ipfs-root* + " > /dev/null;"
37 95
 
38 96
 
39 97
 ————————————————————————————————————————
... ...
@@ -905,6 +905,9 @@
905 905
   functions.
906 906
   A system-dependent replacement for
907 907
   /ipns/docs.ipfs.io/reference/api/http/#api-v0-pubsub-sub"
908
+  (when (and *ipfs-root* (empty-string-p env))
909
+    (setq env (string+ "env IPFS_PATH=" *ipfs-root* " > /dev/null;")))
910
+
908 911
   (uiop:launch-program (string+ env "ipfs pubsub sub " topic) :output :stream))
909 912
 
910 913
 ;; PROCESS-INFO-STREAM → FD-STREAM