~subsetpark/jnj

063dc8a5de4089ce57caef7f79e45741119995b6 — Zach Smith 2 years ago 88df580
Update docs
2 files changed, 199 insertions(+), 18 deletions(-)

M .gitignore
M README.md
M .gitignore => .gitignore +1 -1
@@ 1,3 1,3 @@
/tags
/build
/janet_modules
/jpm_tree

M README.md => README.md +198 -17
@@ 1,3 1,5 @@
# jnj API

# JNJ (J iN Janet)

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


@@ 63,7 65,7 @@ repl:6:> (jnj/j '$ mat)

## jnj

[eval](#eval), [eval*](#eval-1), [j](#j), [j*](#j-1), [j-engine](#j-engine), [to-matrix](#to-matrix)
[eval](#eval), [eval*](#eval-1), [from-j-value](#from-j-value), [j](#j), [j*](#j-1), [j-engine](#j-engine), [jnj-primitives/do](#jnj-primitivesdo), [jnj-primitives/getm](#jnj-primitivesgetm), [jnj-primitives/init](#jnj-primitivesinit), [jnj-primitives/rank](#jnj-primitivesrank), [jnj-primitives/setm](#jnj-primitivessetm), [jnj-primitives/shape](#jnj-primitivesshape), [jnj-primitives/to-j-value](#jnj-primitivesto-j-value), [jnj-primitives/values](#jnj-primitivesvalues), [let-j](#let-j), [let-j*](#let-j-1), [to-j-value](#to-j-value)

## eval



@@ 76,7 78,7 @@ repl:6:> (jnj/j '$ mat)
Evaluate `verb` and `args` with the default J engine instance (see `eval*`
for details).

[1]: jnj.janet#L68
[1]: jnj.janet#L256

## eval*



@@ 90,24 92,39 @@ 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.

[2]: jnj.janet#L32
[2]: jnj.janet#L107

## j
## from-j-value

**function**  | [source][3]

```janet
(from-j-value res)
```

Turn a j-value abstract type result into a Janet term of the appropriate shape:
- a string
- a scalar value
- a matrix of nested tuples

[3]: jnj.janet#L119

## j

**function**  | [source][4]

```janet
(j verb & args)
```

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

[3]: jnj.janet#L92
[4]: jnj.janet#L264

## j*

**function**  | [source][4]
**function**  | [source][5]

```janet
(j* je verb & args)


@@ 118,30 135,194 @@ datatype:
- a matrix of nested tuples for anything with rank > 0
- a Janet atom (string, number) otherwise

[4]: jnj.janet#L76
[5]: jnj.janet#L214

## j-engine

**keyword**  | [source][5]
**nil**  | [source][6]


The default J instance, used by `jnj/j`.

[6]: jnj.janet#L11

## jnj-primitives/do

**function**  | [source][7]

```janet
<jnj/je J Engine 0x56257e4fe000>
<function comment>
```

The default J instance, used by `jnj/j`.

[5]: jnj.janet#L3

## to-matrix
[7]: jnj.janet#L5

## jnj-primitives/getm

**function**  | [source][8]

```janet
<function comment>
```



[8]: jnj.janet#L7

## jnj-primitives/init

**function**  | [source][9]

```janet
<function comment>
```



[9]: jnj.janet#L2

## jnj-primitives/rank

**function**  | [source][10]

```janet
<function comment>
```



[10]: jnj.janet#L8

## jnj-primitives/setm

**function**  | [source][11]

```janet
<function comment>
```



[11]: jnj.janet#L6

## jnj-primitives/shape

**function**  | [source][6]
**function**  | [source][12]

```janet
(to-matrix j-array)
<function comment>
```

Turn a j-array result abstract type into nested tuples of the appropriate
shape.

[6]: jnj.janet#L21

[12]: jnj.janet#L3

## jnj-primitives/to-j-value

**function**  | [source][13]

```janet
<function comment>
```



[13]: jnj.janet#L9

## jnj-primitives/values

**function**  | [source][14]

```janet
<function comment>
```



[14]: jnj.janet#L4

## let-j

**macro**  | [source][15]

```janet
(let-j bindings expr)
```

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

[15]: jnj.janet#L272

## let-j*

**macro**  | [source][16]

```janet
(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 j-e
>  [x ("$" [3 4] [0 1])
>   y ("$" x)]
>   ('+/ y))
7
```

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))
2
```

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.

[16]: jnj.janet#L149

## to-j-value

**function**  | [source][17]

```janet
(to-j-value 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`.

[17]: jnj.janet#L226