Getting Started

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

“Hello World”

  1. Download and build hoonc, a NockApp compiler which forms part of Nockchain.

    1. zorp-corp/nockchain

  2. In a separate location, download the Jock language repo.

    1. zorp-corp/jock-lang

  3. Copy hoonc from nockapp/target/build/release to the root of jock-lang.

  4. Build jockc: 

    make jockc
cp ./target/release/jockc .

  5. Run the “Hello World” JockApp:

./jockc ./common/hoon/try/hello-world --import-dir ./common/hoon/jib

This should output the simple message, “Hello World” along with some logging details. (At the current time, hoonc 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 /common/hoon/try/hello-world.jock.

let a: = 'Hello World';
a

In each case, you will see several serial outputs from the demo program: a tokenization of the program, the Jock abstract syntax tree (AST), the resulting Nock formula, the output type information (jype), and finally the result of the evaluated Nock formula. (An output of [0 0] indicates that the program has crashed.)

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 with /crates/jockc:

  • /hoon/main.hoon, the main entry point for a hoonc 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.) (The use of a txt file is here a hack for the alpha release and will be improved later.)

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

  • ../../common/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:

./jockc ./common/hoon/try/fibonacci --import-dir ./common/hoon/jib

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

  1. Examine the source code /common/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:

./jockc ./common/hoon/try/calculator --import-dir ./common/hoon/jib

This will

  1. Examine the source code /common/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 demonstration.

  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 /common/hoon/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 /common/hoon/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 jockc 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 during and after the alpha release of Jock, 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.

PreviousIntroduction to JockNextLanguage Basics

Last updated