J in Racket

8.12

J in Racket🔗ℹ

Note

This is a work in progress. J support is incomplete at this time. The interfaces here are liable to change substantially.

1 Main🔗ℹ

(require j)

package: j

procedure
(j str) → any/c
str : string?

Evaluates str as a J program. The result is an appropriate Racket value. In particular, verbs may be applied to arguments and should behave as expected.

Examples:

> (j "4 * 1 + 4")
20
> (define mean (j "+/ % #"))
> (mean '(2 3 4 5 6))
4

2 J library🔗ℹ

(require j/lib/adverbs)

package: j

This module exposes J primitive adverbs with Racket-like names.

(require j/lib/conjunctions)

package: j

This module exposes J primitive conjunctions with Racket-like names.

(require j/lib/nouns)

package: j

This module exposes J primitive nouns with Racket-like names.

(require j/lib/verbs)

package: j

This module exposes J primitive verbs with Racket-like names.

3 Numbers🔗ℹ

(require j/number)

package: j

Support for parsing J-style numeric constants.

procedure
(string->number/j str) → (or/c number? #f)
str : string?

Parses str according to the J grammar. Returns the number or #f if the str does not contain a recognizable numeric constant.

4 Ranked Apply🔗ℹ

(require j/rank)

package: j

Support for J-style ranked apply.

4.1 Ranked Values🔗ℹ

procedure
(atom? v) → boolean?
v : any/c

Equivalent to (zero? (rank v)).

procedure
(normalized-value? v) → boolean?
v : any/c

A normalized value has one of the following forms:

an array? with nonzero dimension;
an array? with zero dimension whose element is not a normalized-value?;
an exact nonnegative integer; or
anything which is not an array? or a sequence?.

procedure
(normalize-value v) → normalized-value?
v : any/c

Produces a normalized form of v.

procedure
(->array v) → array?
v : any/c

Coerces v to an array. In particular, lists, vectors and sequences (but not exact nonnegative integers) are converted to a one-dimensional array containing their elements. Note that strings are interpreted as sequences.

Examples:

> (->array '(1 2 3))
(array #[1 2 3])
> (->array (vector 5))
(mutable-array #[5])
> (->array "hello")
(array #[#\h #\e #\l #\l #\o])
> (->array 'sym)
(array 'sym)
> (->array (array #[#[0 1] #[2 3]]))
(array #[#[0 1] #[2 3]])
> (->array (array "atomic string"))
(array "atomic string")

procedure
(sequence->array s) → array?
s : sequence?

Returns a one-dimensional array containing the elements of s.

procedure
(rank v) → exact-nonnegative-integer?
v : any/c

Returns the rank of v.

Examples:

> (rank 3)
0
> (rank '(3))
1
> (rank (index-array #[2 3 4]))
3
> (rank (vector))
1

procedure
(shape v) → (vectorof exact-nonnegative-integer?)
v : any/c

Returns the shape of v.

Examples:

> (shape 3)
'#()
> (shape '(3))
'#(1)
> (shape (index-array #[2 3 4]))
'#(2 3 4)
> (shape (vector))
'#(0)

procedure
(ranked-value atom/c) → flat-contract?
atom/c : flat-contract?

Returns a contract that requires the input to be a value with atoms matching atom/c.

4.2 Items🔗ℹ

procedure
(item-count v) → exact-nonnegative-integer?
v : any/c

Returns the number of items in v.

Examples:

> (item-count 3)
1
> (item-count '(3))
1
> (item-count (index-array #[2 3 4]))
2
> (item-count (vector))
0

procedure
(item-ref v pos) → any/c
v : any/c
pos : (ranked-value exact-integer?)

Returns the item of v at position pos, where the first item is position 0, and negative positions count backwards from the end.

procedure
(item-shape v) → (vectorof exact-nonnegative-integer?)
v : any/c

Returns the shape of an item of v. Equivalent to (if (atom? v) #[] (vector-drop (shape v) 1)).

procedure
(head-item v) → any/c
v : any/c

Returns the first item of v. Equivalent to (item-ref (take-items v 1) 0).

procedure
(last-item v) → any/c
v : any/c

Returns the last item of v. Equivalent to (item-ref (take-items v -1) 0).

procedure
(take-items v pos) → any/c
v : any/c
pos : (ranked-value (or/c exact-integer? infinite?))

Returns the first pos items of v if pos is atomic (counting from the end if pos is negative). If pos is a vector, this process is applied recursively to the items returned according to the succesive elements of pos.

If more items are requested than are contained in v, the extra items will be filled with (current-fill).

procedure
(tail-items v) → any/c
v : any/c

Returns all the items of v except the first. Equivalent to (drop-items v 1).

procedure
(drop-items v pos) → any/c
v : any/c
pos : (ranked-value (or/c exact-integer? infinite?))

Drops the first pos items of v if pos is atomic (counting from the end if pos is negative). If pos is a vector, this process is applied recursively to the items returned according to the succesive elements of pos.

procedure
(reshape-items v new-shape) → any/c
v : any/c
new-shape : (ranked-value exact-nonnegative-integer?)

Reshape the items of v. The returned value will have the shape (vector-append new-shape (item-shape v)), with the same items as v, repeating or truncating if necessary.

procedure
(in-items v) → sequence?
v : any/c

Returns a sequence consisting of the items of v.

Examples:

> (sequence->list (in-items 3))
'(3)
> (sequence->list (in-items '(3)))
'(3)
> (sequence->list (in-items (index-array #[2 3 4])))
(list
(array #[#[0 1 2 3] #[4 5 6 7] #[8 9 10 11]])
(array #[#[12 13 14 15] #[16 17 18 19] #[20 21 22 23]]))
> (sequence->list (in-items (vector)))
'()

4.3 Ranked Procedures🔗ℹ

A ranked procedure implicitly iterates over its arguments according to its rank.

Examples:

> (apply/rank + (list '(100 200) (index-array '#[2 3])))
(array #[#[100 101 102] #[203 204 205]])
> (define isnum? (atomic-procedure->ranked-procedure char-numeric?))
> (procedure-rank isnum? 1)
'(0)
> (isnum? #\4)
#t
> (isnum? "abc123")
(array #[#f #f #f #t #t #t])
> (define/rank (sum-rows [y 1]) (if (atom? y) y (apply + (array->list y))))
> (sum-rows (array #[#[1 3 5] #[2 4 6]]))
(array #[9 12])
> (sum-rows '(5 10 15))
30
> (sum-rows 11)
11
> (define/rank (replace-items [x #f] [y -1]) x)
> (replace-items '(one two) (array #[1 2 3]))
(array #[#['one 'two] #['one 'two] #['one 'two]])
> (define/rank (integers [y 1]) (index-array (array->vector (->array y))))
> (apply/rank integers (list (array #[#[2 2] #[3 3]])) #:fill 9)
(array #[#[#[0 1 9] #[2 3 9] #[9 9 9]] #[#[0 1 2] #[3 4 5] #[6 7 8]]])

value
procedure-rank/c : contract?

Equivalent to (listof (or/c exact-integer? #f)).

value
rankable-procedure/c : contract?

A contract which accepts procedures that have no required keyword arguments and return a single value.

procedure
(ranked-procedure? v) → boolean?
v : any/c

Returns #t if v is a ranked procedure, #f otherwise.

parameter
(current-fill) → any/c
(current-fill fill) → void?
fill : any/c
= #f

A parameter that defines the value to be used for padding cells.

procedure
(apply/rank proc v ... lst [#:fill fill]) → normalized-value?
  proc : (or/c procedure? ranked-procedure?)
  v : any/c
  lst : list?
  fill : any/c = (current-fill)

Similar to the ordinary Racket apply, except that non-ranked procedures are assumed to have rank 0 for each argument.

If the results of proc have different shapes, then they will be padded with fill.

procedure
(make-ranked-procedure proc rank-spec) → ranked-procedure?
  proc : rankable-procedure/c
   rank-spec :
(or/c (listof procedure-rank/c)
      (-> exact-positive-integer?
          procedure-rank/c))

Create a ranked procedure from proc, with ranks determined by rank-spec.

If rank-spec is a list, it must contain as many items as proc has arities, with each item being the same length as the number of arguments accepted. Otherwise, rank-spec must be a procedure accepting one argument arity, and must return a list of that length.

procedure
(atomic-procedure->ranked-procedure proc) → ranked-procedure?
proc : rankable-procedure/c

Converts proc to a ranked procedure with rank 0 for each argument.

procedure
(procedure-rank proc arity) → procedure-rank/c
proc : (or/c procedure? ranked-procedure?)
arity : exact-positive-integer?

Returns the rank of proc when applied with arity arguments.

syntax
(lambda/rank (arg ...) body ...+)

arg = id
| [id rank]

Creates a ranked procedure. If rank is not specified, it defaults to #f (infinite).

syntax
(case-lambda/rank [(arg ...) body ...+] ...)

arg = id
| [id rank]

Creates a ranked procedure with multiple arities, similar to case-lambda. If rank is not specified, it defaults to #f (infinite).

syntax
(define/rank (id arg ...) body ...+)

Shorthand for defining ranked procedures.

value
prop:rank : struct-type-property?

A structure type property to provide the rank of structure types whose instances can be applied as procedures.

The prop:rank property value must be a procedure which accepts two arguments. The instance is passed as the first argument, and the second is the arity for which a rank is required. The procedure must return a value accepted by procedure-rank/c and of length equal to the arity.