Clojure API for Erlang/OTP Communications (built on jiface)
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
dev-resources Updated targets used for CI/CD. Jul 19, 2018
docs Updated docs for 0.6.0 release. Jul 19, 2018
examples Updated example deps. May 22, 2016
resources Updated docs for 0.6.0 release. Jul 19, 2018
src
test/clojang/test Refactored type conversions. Jan 17, 2017
.gitignore Added ignore. May 22, 2016
.travis.yml Updated targets used for CI/CD. Jul 19, 2018
LICENSE Updated copyright years. Jul 18, 2018
Makefile Updated docs generation and related targets. Mar 5, 2017
README.md Updated deps to 0.5.0. Jul 19, 2018
project.clj Bumped version for 0.6.0 release. Jul 19, 2018
rebar.config Updated rebar config. May 22, 2016

README.md

clojang

Build Status Dependencies Status Clojars Project

Erlang/OTP Communications in Clojure (wraps jiface + JInterface)

Clojang logo

Contents

Introduction

This project provides a final solution to the Clojure JInterface Problem. The jiface low-level API solves this to a certain extent, but jiface requires that programmers perform all their own type conversions, manual creation of nodes and mboxes, etc.

The Clojang library, however, provides an interface that is not only syntactically idiomatic Clojure (not unlike the jiface library), but even more so, provides developers with the same level of convenience they have come to expect when using Clojure libraries in general, without the need to perform many manual operations in order to handle Erlang data.

For a comparison of JInterface, the low-level jiface API, and the high-level clojang API, see the APIs summary page.

Dependencies

  • Java
  • Erlang
  • lein
  • rebar3

The default (and tested) version combinations are as follows:

Clojang jiface JInterface Erlang Release Erlang Version (erts)
0.5.0 0.5.0 1.8.1 20.3 9.3
0.4.0 0.4.0 1.7.1 19.2, 19.3 8.2, 8.3
0.3.0 0.3.0 1.7.1 19.2 8.2
0.2.0 0.2.0 1.7.1 19.1, 19.2 8.1, 8.2
0.1.0 0.1.0 1.6.1 18.2, 18.3 7.2, 7.3

While other version combination may work (and existing versions may be updated to work with different onces), those are the only ones which are supported.

Building

rebar3 is used for the top-level builds of the project. It runs lein under the covers in order to build the Clojure code and create the Clojang.jar file. As such, to build everything -- LFE, Erlang, and Clojure -- you need only do the following:

  • rebar3 compile

If you wish to build your own JInterface .jar file and not use the one we've uploaded to Clojars, you'll need to follow the instrucations given in the jinterface-builder Clojang project.

Shells & REPLs

There are three interactive programming environments you may start, each of which will have full access to the project's libraries/dependencies.

LFE:

$ make lfe-repl

Erlang:

$ rebar3 shell

Clojure:

$ lein clj-repl

Documentation

Project documentation, including Clojang API reference docs, Javadocs for JInterface, and the Erlang JInterface User's Guide, is availble here:

Quick links for the other docs:

  • Clojang User Guides:
    • jiface User's Guide - A translation of the JInterface User's Guide (Erlang documantaion) from Java into Clojure; this is refered to as the Clojang low-level API.
    • Clojang User's Guide - An adaptation of the jiface User's Guide which demonstrates the improved API that Clojang offers
  • JInterface User's Guide - The JInterface (Java support for Erlang Ports) documentation provided in Erlang distributions
  • Jinterface Javadocs - Javadoc-generated API documentation built from the JInterface source code

Usage

Using Clojang in a project is just like any other Clojure library. Just add the following to the :dependencies in your project.clj file:

Clojars Project

For the Erlang/LFE side of things, you just need to add the Github URL to your rebar.config file, as with any other rebar-based Erlang VM project.

As for actual code usage, the documentation section provides links to developer guides and API references, but below are also provided some quick examples.

Here, we'll send a message to our own (default) node's message box, and then receive it:

(require '[clojang.core :refer [! receive self]])

(! [(self) :hello-word])
(let [[pid msg] (receive)]
  (println msg))

To show remote usage, from an LFE (Lisp Flavoured Erlang) REPL:

(clojang-lfe@mndltl01)> (! #(default clojang@host) `#(,(self) hej!))
#(<0.35.0> hej!)

Then back in Clojure, the same that we used before, but we'll capture the process id that we sent from LFE and then send another message back to it:

(let [[pid msg] (receive)]
  (println msg)
  (! pid "hello, world!"))

Then, returning to the LFE REPL, we check that we received the message from Clojang:

(clojang-lfe@mndltl01)> (c:flush)
Shell got "hello, world!"
ok

Running Tests

All the tests may be run with just one command:

$ rebar3 eunit

This will not only run Erlang and LFE unit tests, it also runs the Clojure unit tests for Clojang.

Clojure Test Selectors

If you would like to be more selective in the types of Clojang tests which get run, you may be interested in reading this section.

The Clojang tests use metadata annotations to indicate whether they are unit, system, or integration tests. to run just the unit tests, you can do any one of the following, depending upon what you're used to:

$ lein test
$ lein test :unit
$ lein test :default

To run just the system tests:

$ lein test :system

And, similarly, just the integration tests:

$ lein test :integtration

To run everything:

$ lein test :all

This is what is used by the rebar3 configuration to run the Clojang tests.

Donating

A donation account for supporting development on this project has been set up on Liberapay here:

You can learn more about Liberapay on its Wikipedia entry or on the service's "About" page.

License

Copyright © 2018 The Clojang Project

Copyright © 2016-2017 Duncan McGreggor

Distributed under the Apache License Version 2.0.