ScalaWorksheet

ScalaWorksheet is a Sublime Text 3 plugin that provides worksheet functionality for Scala. You can enter Scala code into a view and run a command to send the content of the view to the Scala REPL. If the code is legal, the output from the REPL will be displayed in a way that makes it easy to see the correspondence between the code and the output that it produced. If there are errors, the full REPL output will be displayed with easy navigation to the errors.

This plugin is inspired by the Scala IDE for Eclipse worksheet plugin.

Installation

The plugin is available from Package Control. It has most recently been tested on Mac OS X 10.9 with Sublime Text build 3054.

Setup

Once the plugin is installed the command palette will contain the command Show Scala Worksheet which should be invoked while in a Scala view.

You will probably want to bind a key to use this plugin, so add a binding to the show_scala_worksheet command to your keymaps. I use the “alt+w” key combination bound as follows to ensure it is only available in views that are displaying Scala code.

{ "keys": ["alt+w"], "command": "show_scala_worksheet",
  "context": [
    { "key": "selector", "operator": "equal", "operand": "source.scala" }
  ]
}

The plugin assumes that you have Scala installed and that it can run the REPL using the scala shell command.

If you want to add some JAR files to the REPL's classpath, you can set the scala_worksheet_classpath setting to a list of file paths.

"scala_worksheet_classpath": [
    "/my/great/library.jar",
    "/the/other/monad/lib.jar"
]

Also, if your code file is located inside an SBT project, the plugin will add the SBT project's target/scala-version/classes directory to the classpath, where version is 2.10, 2.9.3 etc.

Usage

Enter some Scala code into a file and save it. For example, enter

1 + 2

into temp.scala.

Run the show_scala_worksheet command via your key binding. You will see a new file open called temp.scala (worksheet). It will show the Scala REPL session as it is evaluated. Since there are no errors, once the evaluation is completed the worksheet view will change to show just the relevant output.

res0: Int = 3

You will probably want to set your session up with at least two columns and move the worksheet view to a different column from the code, so you can see them both at once.

You can update temp.scala, save it and re-run the command to evaluate the new version.

As a more complicated example, enter the following into a file.

val i = 99 * 666

var amount = {
    val x = 66
    42.5 * x
}

val x = for (a <- 1 to 20) { println (a) }

val len =
    23 + 66

println ("hello there, Tony!")

Now run the command. As before, you will see the REPL session as it progresses. This time, however, it is more obvious that the view is adjusted so that the code aligns with the output that produces it.

You should see something like the following output, where the view on the left is the original file view and the view on the right is the worksheet. The plugin has inserted blank lines as needed to line the segments up.

Errors

If your code contains errors, the plugin behaves slightly differently. Bookmarks will be set at the position of each error and the selection will be placed at the first error. You can navigate to subsequent errors using the F2 key (next_bookmark command).

As for a correct run, the error output will be sanitised by removal of the REPL welcome message, blank lines etc. If you want to see the full error output, use the following setting

"scala_worksheet_sanitise_errors": false

View syncing

By default, a code view and its corresponding worksheet view are synchronised so that if you move the selection in one of them, the other view is adjusted if necessary to keep the two views aligned.

If you do not want this behaviour, use the following setting

"scala_worksheet_sync_views": false

IMPORTANT NOTE: the current implementation only syncs the views if the selection changes. Other changes to the view that alter what is visible will currently not sync. E.g., if you scroll the view with the mouse you will need to click somewhere to get the other view to catch up. I am investigating ways to fix this deficiency.

Worksheet placement

The default behaviour of the plugin is to ensure that the worksheet view is displayed in a different file group (column) to the input code view. This arrangement ensures that you can easily see both of them at the same time.

If you request a worksheet in a window with only one column, a second column will be created and the worksheet will be placed in that column. If the worksheet view is already displayed in the window in the same column as the input view it will be moved to the column immediately to the right of the input. If the worksheet view is already displayed in the window in a different column to the input view, it will be left where it is.

If you don't want the plugin to try to position the worksheet view for you, use the following setting:

"scala_worksheet_show_in_other_group": false