Getting Started

Jock programs are written in plain text and built using choo, the NockApp compiler.

“Hello World”

1. Download and build choo.

   1. GitHub: zorp-corp/nockapp

2. In a separate location, download the JockApp basic repo.

   1. GitHub: zorp-corp/jockapp-tutorial

3. Copy choo from nockapp/target/build/release to the root of jockapp-tutorial.

4. Run the “Hello World” JockApp:

$ make demo hello-world

This should output the simple message, “Hello World” along with some logging details. (At the current time, choo does not always exit after a successful poke, so you may have to press Ctrl+C to close the JockApp instance.)

1. Examine the source code /hoon/try/hello-world.jock.

let a: = 'Hello World';
a

Context

(You can skip this section and come back to it later if you are completing this tutorial for the first time.)

The following files are included in this tutorial repository:

• /hoon/main.hoon, the main entry point for a choo application. (If you know Hoon, you can change this file to load or manipulate other Jock programs.)

• /hoon/lib/jock.hoon, the main Jock language definition. (You would only change this if you want to play with changing Jock.)

• /hoon/lib/mini.txt, the reference Hoon implementation which Jock utilizes. (You can change this to add functionality to the Hoon standard library if you like.)

• /hoon/lib/wrapper.hoon, the NockApp dispatcher. (You would not typically change this.)

• /hoon/try/*, the Jock tutorial files.

• Other files in /hoon/lib such as math.hoon and sequent.hoon are libraries for use in examples.

• main.rs is the Rust input/output wrapper which handles the command-line interface.

Fibonacci Sequence

1. Follow steps 1–3 of the “Hello World” tutorial to make sure that your environment is set up correctly.

2. Run the “Fibonacci” JockApp:

$ make demo fibonacci

This will calculate and display the first ten Fibonacci sequence numbers twice; once calculated recursively, once non-recursively.

1. Examine the source code /hoon/try/fibonacci.jock.

// fibonacci
// The classic Fibonacci sequence

func fib(n:@) -> @{
  if n == 0 {
    1
  } else if n == 1 {
    1
  } else {
    $(n - 1) + $(n - 2)
  }
};

(
  fib(0)
  fib(1)
  fib(2)
  fib(3)
  fib(4)
  fib(5)
  fib(6)
  fib(7)
  fib(8)
  fib(9)
  fib(10)
)

You will notice that, in Jock, the recursion point for the function is indicated not by reusing the function's name but by the universal symbol $ buc.

Calculator

1. Follow steps 1–3 of the “Hello World” tutorial to make sure that your environment is set up correctly.

2. Run the “Calculator” JockApp:

$ make demo calculator

This will

1. Examine the source code /hoon/try/calculator.jock.

// calculator
// Various arithmetic operations, as a list

[
    1 + 2
    4 - 3
    6 * 5
    8 / 7
    9 ** 4
    11 % 12
]

1. You can modify the program using conventional arithmetic operators, with the caveat that () “pal”/“par” parentheses should be used to order expressions intuitively. (Jock currently evaluates operators from right to left, APL-style.) Furthermore, underflows (sub(3 4)) will cause a crash.

NockApp

A NockApp can build and run a program written in Jock. A NockApp is a kernel with a defined interface for interacting with its Rust I/O wrapper. At this point in the developer preview, we will have to modify the Jock program to accept a command-line argument before we build it.

We will use the fibonacci program from above as the basis for this exercise.

1. We have already prepared main.hoon and main.rs to permit a demo with an optional argument. Examine the demo-arg material in main.hoon and the Command and let poke components in main.rs if you are interested in implementation details.

   1. If you modify main.rs, you need to run cargo build again.

2. Make a fresh copy of it as /try/fibapp.jock.

3. Replace the tuple at the end with fib(#0), which we will use as a placeholder for command line arguments at the current time.

4. In /lib/demos.hoon, we make the following changes (already made, but noted here):

   1. Add /* fibapp %jock /try/fibapp/jock after the other library imports at the top.

   2. Add [%fibapp q.fibapp] to ++demos. By itself, this imports the text of the file, which would be parsed naturally by the other arms in this Hoon file. However, we need to modify the file with the received command-line argument that we will supply.

   3. Because we need to interpolate the command-line argument into the text, we need to add a preprocessor gate in main.hoon. Since the arms of the NockApp interface are fixed, we should add it to a |^ “barket” inside of %demo-arg.

      ++  preprocess
        |=  [body=@t arg=(list @t)]
        =|  idx=@
        =/  body  (trip body)
        |-  ^-  @t
        ?:  ?|  =(~ arg)
                =((lent arg) idx)
            ==
          (crip body)  :: TMI
        =/  off  (find "#{(scow %ud idx)}" body)
        ?~  off  $(idx +(idx))
        =/  top  (scag u.off body)
        =/  bot  (slag (dec (add u.off (lent (scow %ud u.off)))) body)
        =/  new  :(weld top (trip (snag idx arg)) bot)
        $(body new, idx +(idx))

   4. Add the preprocessor over the source text as (preprocess u.code ~[(scot %ud v.c)]).

   5. With those pieces in place, the NockApp framework can replace arbitrary command-line arguments in numerical order into the Jock code.

   6. Rebuild the NockApp with the updated files using make release, then run it using make demo fibapp 5.

This NockApp still relies on a Hoon wrapper to dispatch data from the Rust I/O interface to the Jock code, rather like a script file or Urbit generator.

In this release, Jock preprocesses a file to supply command-line arguments; at a later date we intend to change this to an exposed Map namespace once language support becomes available.

Comments

• Syntax is liable to change, although the target Nock instruction set architecture is fixed.

• The Hoon standard library is available through the hoonnamespace. This is an extended version of /lib/tinyand provides basic mathematics, container operations, and other simpler affordances. It does not include the Hoon parser, the compiler, etc.