Working with Crystal Playground

This tool is very useful if you want to quickly run and test some Crystal code, get instant feedback, understand its execution, try ideas, and teach Crystal. It’s kind of a 21st-century version of a REPL-like irb, but it’s built in JavaScript to run in the browser.

You must have Crystal installed on your machine for this. See the instructions earlier in this chapter to find out how.

Open up a terminal, and enter the command $ crystal play.

You’ll see this message: Listening on http://localhost:8080. Open up a browser with this URL, and you’ll see the Playground with our familiar code:

The left pane is for code writing, editing, pasting, or dragging and dropping your code file. After you stop typing, the Playground will compile the code and execute it. You can speed things up by changing Time to wait in the Settings menu to 0.

Start with a specific code file by typing $ crystal play ./path/to/file.cr.

You’ll be able to see every expression with its value in the right pane, so we’ll often omit puts, print, or p statements in the book’s code. For example, you’ll see that the greet method, while running, will write the string “Hello, world!” to standard output. Helloworld.new creates an object (indicated by #<HelloWorld:memory_address>), and greet returns nil. Click on a line in the right pane to see a popup-window with values and their types.

If the program has output, you’ll see it in the bottom pane. Click the >_ icon below the right pane. The editor stores your code in browser storage so that you can continue working on it in a later session.

When you want to execute code, press CTRL+ENTER or simply ENTER in the left pane, or push the large blue-green button in the bottom-right. When compiling, the center arrow changes into a stop button and a colored circle spins. Subsequently, any change in the editor pane also triggers the compilation.

When hovering over the blue button, two more icons appear: the upper to share the code as a gist, and a download button so you can save your code to a file.

Handling Errors

If the code contains an error, you’ll see that message on a red background. Again, you can click on it to see more details:

Using a Workbook

Crystal provides you with the notebook functionality as in the Jupyter and Mathematica environments, where you can mix executable code and text documentation and presentation.

On the logo line, you’ll see the menu items Playground, Workbook, and About, which contains a tutorial. Using a workbook is easy: create a folder called playground in the directory where you start up the $ crystal play server (probably your home folder). Inside the folder, create workbook files, which are .md Markdown files containing markdown and code. A code fragment is indicated like this:

Now you can access these files from the Workbook menu, which is handy for creating presentations and tutorials as shown in the figure.

See GitHub^[142] for a recipe for building awesome presentations with the Playground.

How Does It Work?

When you execute the $crystal play command, a Crystal http server is started. In the Playground, your browser connects via a websocket to that http server, and the code you type in is sent through it. The server processes the code and sends back the results (the –verbose flag shows the inner details).