A Tool for Literate Programming, Executable Documentation, and
Interactive Exploration in Scala
A Tool for Literate Programming, Executable Documentation, and
Interactive Exploration in Scala
While Escalator is not all things to all people, it does attempt to be several things to at least a few people. In particular:
Escalator is an unconventional approach to Literate Programming. Where most LP systems require the code to be embedded in the document source files, to be extracted for compilation through the "tangling" process, Escalator documents are located alongside the files in an ordinary source tree. The program source files need little or no modification to be included in the presentation form of the documents. While LP purists might complain that this loses the power of macros to provide arbitrary structure to the source within the documentation, we believe that the advantage gained in better interaction with other tools (editors, compilers, version-control systems, build tools, ...) outweighs this loss, particularly when using a modern language with adequate support for abstraction.
Escalator documents use an extension of Markdown syntax, which is a way of describing a formatted document in a plain text form that is as readable as a common email message. Output is a set of webpages displaying the files in the source tree, including the processed Escalator documentation. One extension selects fragments out of a source code file. Fragments may be identified by pattern matching on the context and first line (the fragment will spread across all successive lines that are more indented than the first), or by naming a tag which selects lines surrounded by comments containing the tag (this is the only way in which a source file might need to be modified, in case the pattern-matching heuristic doesn't work to select the desired fragment).
Escalator's other Markdown extensions support a form of Executable Documentation. Blocks of code may be marked as examples or tests. When the document is processed, these blocks are run against the compiled project. Example output is presented as it would be seen in an interactive console (REPL) session, while test output is presented as a report (with passing tests in green). Currently, executable code must be in Scala, and tests use a subset of specs with ScalaCheck.
A variant of the executable blocks produces an interactive console in the generated webpage. Currently this is only supported for local viewing (with Escalator acting as the server on localhost); the contents of the block are in an editable textarea, and may be submitted to the server for evaluation, producing example or test output just as for the non-interactive case.
Escalator may be run from a command line (on any system with Java 1.5 or greater), or there is a simple Swing GUI which provides an alternative interaction mode, including the ability to edit and save example scripts for inclusion in an Escalator document.
Even without writing any document files, Escalator may be used to browse and interact with a Scala source tree. It may also be used to document and browse sources in other languages, although more complete support for this (possibly including interaction) is future work.
Escalator was designed for use in educational settings: for in-class demonstrations and experimentation, for student use as an alternative to console interaction, for the display of interactive tutorials, and for the documentation of student projects and homework. However, we would be delighted if it proved useful in non-educational settings as well; one of our design goals was to allow Escalator to work well with existing source tools, and a near-term project is to integrate Escalator with sbt, the simple build tool.
Here is an example of including some source code; the command is
// source 'demo/BST.scala' object Tree / def search:
def search[T <% Ordered[T]](x: T, tree: Tree[T]): Boolean = tree match {
case Tip => false
case Node(left, value, right) if x < value => search(x, left)
case Node(left, value, right) if x > value => search(x, right)
case _ => true
}This is what the result of running an example looks like:
> println("Hello World!")
Hello World!
> 2+2
res1: Int = 4
> import demo._
import demo._
> import Tree._
import Tree._
> search(4, insert(2, insert(6, insert(4, Tip))))
res2: Boolean = true
And here is a sample of test output:
Specification "Spec1"
+ 2+2 is 4
x 2+2 is 5
'4' is not equal to '5' (<console>:16)
Total for specification "Spec1":
Finished in 0 second, 297 ms
2 examples, 2 expectations, 1 failure, 0 error
(Be sure to look at the source in each case).
Here is what Escalator does with a (very small) source tree: demo
Here is the start of a set of tutorials on using Scala: tut
The Escalator team is led by Dr. Brian Howard (bhoward@depauw.edu) at DePauw University as a part of the Scales Project. This research was supported by NSF REU grant number CCF-0851812.
Of course, this site was generated by Escalator; look at the Escalator source for this page.
Here is Escalator 1.0, a different approach to writing literate Scala programs which is no longer maintained.