jadedctrl/ cl-ipfs-api2
1
0
Disbranĉigi 0
Fontkodo Issues 6 Tirpetoj 1 Activity

Updated documentation

This commit is contained in:
Jaidyn Levesque 2019-06-18 12:45:31 -05:00
parent 47be6a3f8c
commit 1b83ff3ddf
2 changed files with 72 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

80
README.txt
View File

@ -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 :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: Then you can do things like:
> (ipfs:add #p"~/.bashrc") > (ipfs:add #p"~/.bashrc")
"QmZweanA1JRNio6DKnPN6yECWCrxmWqqG7WWUNtyuji9hZ" "QmZweanA1JRNio6DKnPN6yECWCrxmWqqG7WWUNtyuji9hZ"
145
".bashrc"
> (ipfs:cat "/ipns/ipfs.io/index.html") > (ipfs:cat "/ipns/ipfs.io/index.html")
"<!DOCTYPE html> "<!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, Most commands available are one-to-one with their API/cli counter-parts,
with a few notable exceptions: 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: The calls implemented so far:
* root calls (cat, add, id, ls, resolve, etc) * root (cat, add, id, ls, resolve, etc)
* cid calls * bitswap, block, bootstrap
* config calls (config, config/show) * cid, config (config, config/show)
* version calls (version, version/deps) * 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)-- Some calls were skipped over, but wouldn't be hard to add:
depending on context, of course. Read docstrings ♥ * 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
————————————————————————————————————————
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;"
———————————————————————————————————————— ————————————————————————————————————————

3
main.lisp
View File

@ -905,6 +905,9 @@
functions. functions.
A system-dependent replacement for A system-dependent replacement for
/ipns/docs.ipfs.io/reference/api/http/#api-v0-pubsub-sub" /ipns/docs.ipfs.io/reference/api/http/#api-v0-pubsub-sub"
(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)) (uiop:launch-program (string+ env "ipfs pubsub sub " topic) :output :stream))
;; PROCESS-INFO-STREAM → FD-STREAM ;; PROCESS-INFO-STREAM → FD-STREAM