2 REPL

6.1.1.7

← prev up next →

2 REPL

2.1 Summary

2.3 Sample Interaction

The REPL is a simple, interactive way to explore bytecode files. It is implemented in the file zo-shell.rkt, which exports a single function:

procedure
(init args) → void?
args : (vectorof string?)

Accepts a vector of command-line arguments, parses the first argument as a bytecode file, then starts a REPL session using the output of calling zo-parse on this file.

This document is a users’ guide for the REPL. See the API page for implementation details.

2.1 Summary

The REPL works by storing an internal context and reacting to commands. This context is normally a zo struct, but may also be:

A list of zo structs
Search results, obtained by calling find.

The commands show information about this context or change it.

Also, the REPL remembers previous states. We call this recorded past the history of the REPL. It’s basically a list of contexts.

2.2 Commands

The REPL supports commands to display and explore structs parsed from a .zo file.

2.2.1 alst

List all command aliases.

For fun and uniformity, the canonical name of each command has 4 letters. But each has plenty of shorter and more mnemonic aliases to choose from. For example, you can type ls instead of info and cd instead of dive.

2.2.2 back

Move up to the previous context.

Each successful dive or find command changes the current context to new struct or list. Before making these transitions, we save the previous context to a stack. The back command pops and switches to the most recent element from this stack.

Note that back will fail (and do nothing) at the top of the zo struct hierarchy or the top of a saved subtree.

2.2.3 dive

Enter a struct’s field.

This is where exploring happens. Each struct has a few fields; you can see these by printing with info. Any field containing zo structs is a candidate for dive. For example, the struct assign has a field rhs, which can be accessed by:

dive rhs

Notes:

Fields that do not exist or do not contain structs may not be explored.
Fields that are zo change the context to a zo; fields that are lists change the context to a list.
Elements in a list may be accessed by their index, as in dive 3.
dive takes exactly one argument. Any more or less is not permitted.

2.2.4 find

Search the current struct’s children for a certain zo struct.

Find uses string matching to automate a simple search process. Give it a string, for instance find lam, and it searches for lam structs nested within the current context. The string must be the name of a zo struct—anything else will return null results.

A successful find changes context to a list of zo structs. Exploring any element of the list changes the current history to be that element’s history. You are free to explore the children and parents of any struct returned by a find query. Use jump to immediately return to the search results.

2.2.5 help

Print command information.

Shows a one-line summary of each command. The tabernacle is all-knowing.

2.2.6 info

Print the current context.

This info command does the real work of exploring. It shows the current context, whether struct or list. Lists give their length and the names of their elements. Zo structs show their name, their fields’ names, and their fields’ values. Non-struct field values are printed as best we know how; struct field values are not printed in detail, but may be dive-ed into.

There is currently no tool for printing the current history.

2.2.7 jump

Warp back to a previously-saved context.

The commands jump and save work together. After saving or making a successful query with find, the current history is saved. At this point, a step backwards will recover this history. The interesting thing is that steps forward create a new history, and you can immediately forget that new history by calling jump.

For example, if you call find and explore one of the results, you can immediately jump back to your search results.

2.2.8 save

Mark the current context and history as a future target for jump.

Manually calling save is not very useful, but helpful if you know of a zo struct you will want to revisit.

2.2.9 quit

Exit the REPL.

2.3 Sample Interaction

Let’s explore the REPL’s own bytecode. First, compile the project and build an executable:

$ raco make zordoz.rkt
$ raco exe zordoz.rkt

Now we have both an executable and some bytecode to explore. Open the bytecode for zo-string.rkt. You should see the interpreter prompt.

$ ./zordoz private/compiled/zo-string_rkt.zo
INFO: Loading bytecode file 'private/compiled/zo-string_rkt.zo'...
INFO: Parsing bytecode...
INFO: Parsing complete!
--- Welcome to the .zo shell,version 1.0 'vortex'---
zo>

Now we can start typing commands, like info.

zo> info
<struct:compilation-top>
  max-let-depth : 31
  prefix        : <struct:prefix>
  code          : <struct:mod>

Next, let’s try a dive.

zo> dive max-let-depth
'dive max-let-depth'not permitted.

Didn’t work! That’s because max-let-depth is an integer. Let’s try one of the structs.

zo> dive prefix
zo> info
<struct:prefix>
  num-lifts : 0
  toplevels : [#f]
  stxs      : []

Great! We can’t dive any further from here, so let’s go back up.

zo> back
zo> info
<struct:compilation-top>
  max-let-depth : 31
  prefix        : <struct:prefix>
  code          : <struct:mod>

And we’re back to where we began. From here we could dive to the code field and print it, but the printout is a little overwhelming. The module we’re exploring, zo-string, creates over 40 different functions. There’s just a lot of data to look at, and because it’s heterogenous data we do not have a nice way of truncating it.

Instead, we let’s use find. Be warned, the search might take a minute.

zo> find compilation-top
FIND returned 0 results

Zero results is good: there should not be any other compilation-top structs besides the one we’re currently in. Now try searching for something else, like branch.

zo> find branch
FIND returned 422 results
FIND automatically saving context
<struct:branch>[422]

Wow! Over 400 results.

← prev up next →