diff options
authorJaidyn Levesque <>2019-06-18 17:45:31 +0000
committerJaidyn Levesque <>2019-06-18 17:45:31 +0000
commit1b83ff3ddfe28eb53b05a22ffee3ab9da2b4d232 (patch)
parent47be6a3f8c3788aef7d18d4904e74f291c6d9492 (diff)
Updated documentation
2 files changed, 72 insertions, 11 deletions
diff --git a/README.txt b/README.txt
index a4bdfe6..c541915 100644
--- a/README.txt
+++ b/README.txt
@@ -1,9 +1,11 @@
-CL-IPFS-API² Binder for galactic transguys
+CL-IPFS-API² For space-orientied lisp weenies
:cl-ipfs-api² is a pretty simple set of IPFS bindings for Common Lisp, using
-the HTTP API. It uses Dexador for HTTP(S) requests and YASON for JSON.
+the HTTP API for (almost) everything, except for pubsub (which uses the locally
+installed go-ipfs program).
+It uses Dexador, YASON, and UIOP.
@@ -15,8 +17,6 @@ and you're good).
Then you can do things like:
> (ipfs:add #p"~/.bashrc")
- 145
- ".bashrc"
> (ipfs:cat "/ipns/")
"<!DOCTYPE html>
@@ -24,16 +24,74 @@ Then you can do things like:
Most commands available are one-to-one with their API/cli counter-parts,
with a few notable exceptions:
- * #'dl (counter-part to the /get call)
+ * #'dl (counter-part to the /get call. the name is different, so
+ as to not conflict with #'common-lisp:get)
The calls implemented so far:
- * root calls (cat, add, id, ls, resolve, etc)
- * cid calls
- * config calls (config, config/show)
- * version calls (version, version/deps)
+ * root (cat, add, id, ls, resolve, etc)
+ * bitswap, block, bootstrap
+ * cid, config (config, config/show)
+ * dag, dht, diag
+ * file, files, filestore
+ * key, name, object
+ * p2p, pin, pubsub
+ * version (version, version/deps)
-Functions return either strings, lists, or hash-tables (parsed JSON)--
-depending on context, of course. Read docstrings ♥
+Some calls were skipped over, but wouldn't be hard to add:
+ * object/put, object/set-data object/patch/append-data
+Functions return either strings, lists, or associative lists, depending on
+context. All errors return two values— nil and an error message (string).
+Make sure to read docstrings ☆
+Pubsub usage here is such an abberation that it warrants its own section.
+Since there isn't a (functional) HTTP API for pubsub yet, we're using the
+actual go-ipfs program from your computer.
+If you don't have go-ipfs locally installed, it won't work.
+If you are using Windows, or anything but *nix, it probably won't work.
+If you haven't enabled pubsub (--enable-pubsub-experiment argument to daemon),
+it won't work.
+Well… here we go.
+You can sub to a topic with, ofc, #'pubsub-sub, which will return a
+UIOP-originated process-info stream— while the `ipfs pubsub sub` command runs
+in the background.
+This stream can't be directly #'read-char or #'listen with, which is exactly
+what you wanna do— instead, running #'uiop/launch-program:process-info-output
+on it is necessary to expose a usable stream.
+To make all that easier, there's a little abstraction I added which obfuscates
+UIOP use and is adequate shorthand:
+ * #'pubsub-sub-read-char
+ * #'pubsub-sub-listen
+ * #'pubsub-sub-process
+ * #'pubsub-sub-close
+All of those operate on the original UIOP-originated process-info stream, and
+work exactly like you'd expect.
+The only weird, non-obvious one is probably #'pubsub-sub-process, which applies
+#'uiop/launch-program:process-info-output— just in case you need the raw,
+usable stream.
+Anyway, with this, you can get a continuous read on what's going on with the
+topic you're subbed to. To publish to a topic, run #'pubsub-pub with the topic
+and data as arguments. Pretty simple.
+Both #'pubsub-sub and #'pubsub-pub, being the only functions that run a shell
+command, include an :env argument. If you supply a string as the :env argument,
+that string will prefix the "ipfs" command— basically only useful for changing
+something with the "env" command (like $IPFS_PATH).
+Also, if you change the ipfs:*ipfs-root* variable (to the correct value of
+$IPFS_PATH), the :env arguments (unless otherwise specified) will default to
+"env IPFS_PATH=" + ipfs:*ipfs-root* + " > /dev/null;"
diff --git a/main.lisp b/main.lisp
index 1535464..dcca1cd 100644
--- a/main.lisp
+++ b/main.lisp
@@ -905,6 +905,9 @@
A system-dependent replacement for
+ (when (and *ipfs-root* (empty-string-p env))
+ (setq env (string+ "env IPFS_PATH=" *ipfs-root* " > /dev/null;")))
(uiop:launch-program (string+ env "ipfs pubsub sub " topic) :output :stream))