@ccmaymay/concrete 4.15.0 → 4.15.1

package/README.md

@@ -0,0 +1,125 @@
+concrete-js for Node.js
+=======================
+
+*This README describes the Node.js version of **concrete-js**.
+For the standard jQuery version, see `README-js.md`.*
+
+**concrete-js** is a Node.js library for working with
+[Concrete](https://github.com/hltcoe/concrete), a set of NLP data
+types defined by a [Thrift](https://thrift.apache.org) schema.  Thrift
+makes it easy to use a shared set of data structures across multiple
+programming languages.
+
+**concrete-js** is designed for visualization and annotation.
+While it is *technically* possible to implement NLP algorithms in
+JavaScript, you should instead use
+[concrete-python](https://github.com/hltcoe/concrete-python) or
+[concrete-java](https://github.com/hltcoe/concrete-java).
+
+In general, you should use **concrete-js** when you have a Concrete
+*Communication* object that was created by another tool, and need a UI
+that visually represents data in the *Communication*.  You may also
+need the user/annotator to interactively modify Concrete data
+structures, and then save their modifications.
+
+The **concrete-js** library contains:
+
+- Serialization and deserialization code for Concrete data structures.
+  The serialization code is generated by the Thrift compiler from the
+  [Thrift schema for Concrete](http://hltcoe.github.io/concrete/schema/).
+- Utility code for working with Concrete objects
+
+API documentation for **concrete-js** is available at:
+http://hltcoe.github.io/concrete-js/
+
+
+Including concrete-js in your project
+-------------------------------------
+
+```
+npm install @ccmaymay/concrete
+```
+
+```javascript
+import thrift from "thrift";
+import concrete from "concrete";
+```
+
+
+Fetching Communications with JavaScript
+---------------------------------------
+
+Replace `/FETCH/URL/PATH/`, `FETCH_HOST_ADDRESS`, `9090`, and
+`["FETCH-COMM-ID-1", "FETCH-COMM-ID-2"]` with the appropriate values
+for your application:
+
+```javascript
+import thrift from "thrift";
+import concrete from "concrete";
+
+var options = {
+  transport: thrift.TBufferedTransport,
+  protocol: thrift.TJSONProtocol,
+  path: "/FETCH/URL/PATH/",
+  https: false,
+};
+
+const connection = thrift.createXHRConnection(
+  "FETCH-HOST-ADDRESS",
+  9090,
+  options
+);
+connection.on("error", function (err) {
+  console.error(err);
+});
+
+const client = thrift.createXHRClient(
+  concrete.access.FetchCommunicationService,
+  connection
+);
+
+const request = new concrete.access.FetchRequest({
+  communicationIds: ["FETCH-COMM-ID-1", "FETCH-COMM-ID-2"],
+});
+client.fetch(request).then((result) =>
+  console.log(result.communications)
+).catch((error) =>
+  console.error("fetch error: " + error.message);
+);
+```
+
+Building concrete-js
+--------------------
+
+You do not need to build **concrete-js** in order to use
+**concrete-js** - a working copy of the library is included in the
+`dist/` directory.  The **concrete-js** library only needs to
+(re)built when the Thrift schema files for Concrete have been updated,
+or when the code in `src/` is modified.
+
+Requirements for building **concrete-js**:
+
+* A copy of the [Concrete](https://github.com/hltcoe/concrete)
+  repo in your home directory - ```${HOME}/concrete```
+* [Thrift](https://thrift.apache.org)
+* [Node](http://nodejs.org)
+* [Grunt](http://gruntjs.com) - a JavaScript build tool
+
+Install the Node packages required for building **concrete-js** using:
+
+```
+npm install
+```
+
+Build **concrete-js** using the command:
+
+```
+grunt
+```
+
+(or perhaps `npx grunt`) which will:
+
+* call the Thrift compiler to generate JavaScript code for the Thrift schema under ```${HOME}/concrete```
+* combine the Thrift-generated JavaScript code with the hand-written utility function JavaScript code in a single directory
+* run [JSHint](http://www.jshint.com) on the combined JavaScript code to check for problems
+* minify the combined code