Updated documentation
This commit is contained in:
Jaidyn Levesque
parent
47be6a3f8c
commit
1b83ff3ddf
80
README.txt
80
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")
|
||||
"QmZweanA1JRNio6DKnPN6yECWCrxmWqqG7WWUNtyuji9hZ"
|
||||
145
|
||||
".bashrc"
|
||||
|
||||
> (ipfs:cat "/ipns/ipfs.io/index.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,
|
||||
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
|
||||
————————————————————————————————————————
|
||||
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;"
|
||||
|
||||
|
||||
————————————————————————————————————————
|
||||
|
|
|
|||
|
|
@ -905,6 +905,9 @@
|
|||
functions.
|
||||
A system-dependent replacement for
|
||||
/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))
|
||||
|
||||
;; PROCESS-INFO-STREAM → FD-STREAM
|
||||
|
|
|
|||
Ŝarĝante…
Reference in New Issue