Browse Source

Add initial README

Damien Cassou 4 years ago
Signed by untrusted user: DamienCassou GPG Key ID: B68746238E59B548
1 changed files with 57 additions and 0 deletions
  1. +57

+ 57
- 0 View File

@ -0,0 +1,57 @@
* json-process-client
<a href="">
<img alt="pipeline status" src="" />
** Summary
The package json-process-client is an Emacs library to facilitate
communicating with servers that read and write JSON. The library is
responsible for starting the server and connecting with TCP. It is
also responsible for converting to and from JSON.
The library was written by [[][Nicolas Petton]] in the context of [[][Indium]] and
later generalized by [[][Damien Cassou]] who needed something similar to
integrate [[][basecamp within Emacs]].
** Installation
Get json-process-client from [[][melpa]] or [[][melpa stable]]. You can also clone
the git repository.
** Usage
There are two entry points to the API: ~json-process-client-start~ and
~json-process-client-start-with-id~. They both launch an executable
passed as parameter wait for it to be ready, and connect to it using
TCP. They both return an "application" that must be passed as
parameter to all other functions of the API.
Because everything is asynchronous, the server can send responses in a
different order than the messages the client sent. The server can also
send messages which are not responses to a former message. There must
be a way to map responses to the initial message when there was
one. The two functions ~json-process-client-start~ and
~json-process-client-start-with-id~ differs in the way they map
responses to their corresponding message. The later function is the
simplest but requires that the server reads ids from the messages and
writes the ids back in its responses. The former function let the API
user implement the mapping.
There are three other public methods in the API:
- ~json-process-client-stop~ terminates the TCP connection and the
- ~json-process-client-process-live-p~ returns non-nil if the server
is still listening.
- ~json-process-client-send~ sends a message to the server and
executes a given callback upon reception.
** License
See [[file:COPYING][COPYING]]. Copyright (c) 2019 Nicolas Petton and Damien Cassou.