JNJ: J iN Janet

JNJ (J iN Janet)

JNJ provides bindings to the J language to be used in Janet code.

J is a powerful array programming language in the APL lineage. It has a few features that might make it useful to expose from within a more general-purpose language:


JNJ requires the presence of libj.{so,dylib,dll}, provided by the J Language. You might need to install an -devel package for J depending on your package manager.

It will attempt to load at runtime. If is not present in your search path for dlopen(), you can specify the path when you install jnj:

LIBJ_DIR=/directory/containing/sofile jpm install


See eval/eval* and j/j* for details.

jnj is designed to allow you to use J from within Janet. Thus, it has two main functions:

To do so, jnj introduces two main abstract types:

All J computations take place within an instance of the J Engine. For convenience, a default instance is created at import time and available at jnj/j-engine. The eval and j commands both use this default instance, while eval* and j* allow you to specify your own.

All of the above functions have the same basic signature (modulo the presence or absence of an engine argument): they take a verb and 0, 1, or 2 arguments.

The difference is that j and j* will evaluate their J command and return native Janet datatypes. eval and eval*, on the other hand, will return the other abstract type, a J Array.

J Arrays can be inspected for rank, shape, etc., but they can also be passed as arguments to further eval/j calls. Thus, they’re an efficient way to perform more complex procedures, involving multiple calls to the J interpreter, without having to convert data in and out of the J representation. They are also the most efficient and convenient way to create multi-dimensional arrays, as opposed to nesting multiple Janet array/tuples.


The verb can be any J sentence, verb or verb sequence. It can be a symbol or a string.

If there are no arguments, the sentence will be evaluated and returned.

repl:3:> (jnj/j "3 4 $ i. 10")
((0 1 2 3) (4 5 6 7) (8 9 0 1))

Arguments should be native Janet terms or a J Array. If they’re present, the verb will be applied to them. If there’s a single argument Y, it will be evaluated in the form <VERB> <Y>. If there are two arguments, X and Y, they will be evaluated in the form <X> VERB <Y>.

repl:4:> (jnj/j "$" [3 4] (range 10))
((0 1 2 3) (4 5 6 7) (8 9 0 1))
repl:5:> (def mat (jnj/eval "$" [3 4] (range 10)))
<jnj/jarray float [2/12]>
repl:6:> (jnj/j '$ mat)
(3 4)

In the first example, we evaluate a J sentence using native datatypes and return the result as native datatypes. In the second, we evaluate the same command and return the result as a J Array, which we can then use as an argument in subsequent commands.

Advanced Usage


The let-j/let-j* convenience macros provide a simple wrapper around eval and j which is more expressive and efficient.

The above example could also be written as:

repl:1> (let-j [mat ("$" [3 4] (range 10))]
          ('$ mat))
(3 4)


As noted above, JNJ provides the J Array abstract type as a way to efficiently store J values. J provides an efficient and terse way to construct multi-dimensional arrays; however, if you have some existing Janet data which you want to use as an argument to J, you can convert it:

repl:2:> (to-j-array [[1 1 1][2 2 2][3 3 3]])
<jnj/jvalue float [2/9]>
repl:3:> (j "+/" _)
(6 6 6)


eval, eval*, from-j-array, j, j*, j-engine, jnj-primitives/init, let-j, let-j*, to-j-array


function | source

(eval verb & args)

Evaluate verb and args with the default J engine instance (see eval* for details).


function | source

(eval* je verb & args)

Evaluate verb with arguments args in the context of je. Returns a j-array abstract type which can be used for further evaluations, or converted into a tuple matrix.


function | source

(from-j-array res)

Turn a j-array abstract type result into a Janet term of the appropriate shape:


function | source

(j verb & args)

Evaluate verb with args in the default J engine instance (see j* for details).


function | source

(j* je verb & args)

Evaluate verb with args in the context of je, returning a native Janet datatype:


nil | source

The default J instance, used by jnj/j.


function | source

(jnj-primitives/init &)


macro | source

(let-j bindings expr)

Evaluate let-j bindings and expr in the default J engine instance (see let-j* for details).


macro | source

(let-j* je bindings body)

Use a series of intermediate bindings to compute a complex J value and convert it back to Janet.

bindings should be, like with let, alternating binding keywords and J expressions.

A binding keyword is any keyword, which can then be referred to in subsequent expressions.

A J expression is a tuple of the form that can be passed to eval* or j* - an arbitrary symbol-or-string sentence followed by 0, 1 or 2 args. In addition to the arg types understood by eval* and j*, an arg can also be a keyword, in which case it will refer to the result bound to that keyword earlier in the bindings form.

Finally, body is the J expression to be evaluated - again, a sentence followed by 0, 1 or 2 arguments, where the arguments can include any keywords specified in the bindings.

Here’s an example that creates a 4x3 matrix, gets its shape, and then sums the shape:

> (let-j* je
>  [x ("$" [3 4] [0 1])
>   y ("$" x)]
>   ('+/ y))

Because the intermediate expressions in let-j only consist in the J engine, it can also be used to handle datatypes not yet understood by JNJ, like boxes:

> (let-j* je
>  [box ("<" "foo")
>   arglist (";" box "bar")]
>   ("#" arglist))

This same fact makes let-j operations somewhat more efficient than multiple eval calls, as the intermediate values don’t need to be copied back into the J runtime.


function | source

(to-j-array matrix)

Turn an arbitrarily nested array/tuple of numbers into a J Array.

NB: This function performs some validation on its input to assert that it can be transformed into a J Array. So if the data is not already in Janet form, it might be more efficient to generate it using jnj/eval.

Z. D. Smith, 2021.
Built with Bagatto.