User Guide

One way to think of Xerblin is as a text editor that uses Joy as a macro language.

When you start the xerblin script it will present you with a StackViewer window and a TextViewer (text editor) that contains the system log. Instead of printing to stdout Xerblin prints text to the log window. This text is also written to the log.txt file in the ~/.xerblin git repo and versioned.

To quit Xerblin close the log window.

Other than editing text files everything else is done by putting things onto the stack and executing Joy commands.

You execute commands (sometimes called “words” after Forth nomenclature) by right-clicking on them in any TextViewer window. If the word you want isn’t in any window you can always just type it and click on it. (There are no menus.)

The cursor or caret is set by the left mouse button, however, the selection is set by the right mouse button. They are independent of each other, and you can even have the cursor in one TextViewer and the selection in another. (This is following the old Oberon OS user interface.) It takes a little getting used to, but then it’s quite nice.

You can copy text from one place to another with just the mouse buttons. You can also copy (or cut with the shift button held down) text to and from the system stack.

You can middle-click on numbers to put them onto the stack.

Mouse Chords

These are the mouse button chords that Xerblin understands.

Actions take place when you release the buttons. To cancel a chord click the third mouse button.

First Second Action
Left   Set the insertion caret.
Left Middle Paste from top of stack to caret. Hold down shift to also pop the stack.
Left Right Copy selection to caret. Hold down shift to also cut selection.
Middle   Execute command. Paste selection (bypassing stack). Click and drag to scroll.
Middle Left Unassigned.
Middle Right Print the documentation for a command word to the log.
Right   Start/sweep selection.
Right Middle Copy selection to stack. Hold down shift to also cut selection.
Right Left Copy selection to caret. Hold down shift to also cut selection.

Keyboard Shortcuts

There are a few built-in keyboard shortcuts.

  • Control-Enter - Run the selection as Joy code, or if there’s no selection the line containing the cursor.
  • F3 - Copy selection to stack.
  • Shift-F3 - Cut selection to stack.
  • F4 - Paste item on top of stack to insertion cursor.
  • Shift-F4 - Pop and paste top of stack to insertion cursor.

There are some commands bound to keys in the config file:

  • F5 - swap
  • F6 - dup
  • Shift-F5 - roll<
  • Shift-F6 - roll>
  • F7 - over
  • Shift-F7 - tuck
  • F8 - parse
  • F12 - words
  • F1 - reset_log show_log
  • Escape - clear reset_log show_log
  • Control-Delete - pop
  • Control-i - i

You can edit the thun.config file to change these.

Extending Xerblin

You can add definitions to the current dictionary with the inscribe command. These definitions will be forgotten when you quit Xerblin.

TODO: link to reference docs for inscribe command.

You can add definitions to the definitions.txt file to make them available every time you run Xerblin.

TODO: double check that the definitions.txt file is actually loaded!

Last but not least, you can extend the underlying Thun system with new primitives to provide additional functionality.

Creating New Documents

> TBD

Opening Documents

> TBD