Try PureScript is an online PureScript code editor for quickly experimenting with PureScript code snippets and ideas. It consists of a client and a server component, both of which live within this repository.
- Writing code using the Ace Editor
- Automatic compilation
- PureScript syntax highlighting
- Run and print output or show resulting JavaScript
- Multiple view modes: code, output or both
- Shareable code and editor state via URL
- Load PureScript code from GitHub Gists or repository files
Most of these features can be controlled not only from the toolbar, but also using the query parameters:
-
Load From GitHub Repo: Load a PureScript file from a GitHub repository using the
github
parameter- Format:
github=/<owner>/<repo>/<branch or tag>/<file>.purs
- Example:
github=/purescript/trypurescript/master/client/examples/Main.purs
. - Notes: the file should be a single PureScript module with the module name
Main
.
- Format:
-
Load From Gist: Load PureScript code from a gist using the
gist
parameter- Format:
gist=<gist id>
- Example:
gist=37c3c97f47a43f20c548
- Notes: the file should be named
Main.purs
with the module nameMain
.
- Format:
-
Load From URL: Load compressed PureScript code using the
code
parameter- Managed by Try PureScript and updated on editor state change to create shareable URLs
- Format:
code=<compressed string>
- Example:
code=LYewJgrgNgpgBAWQIYEsB2cDuALGAnGIA
will set the editor state to the single linemodule Main where
-
View Mode: Control the view mode using the
view
parameter- Options are:
code
,output
,both
(default) - Example:
view=output
will only display the output
- Options are:
-
Auto Compile: Automatic compilation can be turned off using the
compile
parameter- Options are:
true
(default),false
- Example:
compile=false
will turn auto compilation off
- Options are:
-
JavaScript Code Generation: Print the resulting JavaScript code in the output window instead of the output of the program using the
js
parameter- Options are:
true
,false
(default) - Example:
js=true
will print JavaScript code instead of the program's output
- Options are:
Try PureScript aims to provide a complete, recent package set from https://github.com/purescript/package-sets. The available libraries are those listed in staging/spago.dhall
, at the versions in the package set mentioned in staging/packages.dhall
.
These steps should be performed whether you are working on the server, the client, or both.
# Clone into the repository
git clone [email protected]:purescript/trypurescript.git
cd trypurescript
This step sets up a local server for Try PureScript. You can skip this step if you just want to use the client with the production server.
# Build the trypurescript executable
stack build
# Set up the PureScript environment for the server
cd staging
spago build
# Ensure the compiled JavaScript is available to the client via symbolic link.
ln -s "$PWD/output" "$PWD/../client/public/js/output"
# Then, start the server.
#
# Below, we disable glob expansion via `set -o noglob` to ensure that globs are
# passed to `purs` unchanged.
#
# We run this in a subshell so that setting noglob only lasts for the duration
# of the command and no longer.
(set -o noglob && stack exec trypurescript 8081 $(spago sources))
# Should output that it is compiling the sources (first time)
# Then: Setting phasers to stun... (port 8081) (ctrl-c to quit)
# Install development dependencies
cd client
npm install
# Use `serve:dev` if you are using a local Try PureScript server,
# e.g. you followed the instructions in step 1.
#
# Use `serve:production` if you would like
# to test the client against the production Try PureScript server.
# Note: the production server may not match the package set you have locally.
npm run serve:(dev|production)
# Try PureScript is now available on localhost:8080
The built-in examples for Try PureScript are loaded from this GitHub repository. To change the tag that the examples are loaded from, you'll need to touch three files:
client/config/dev/Try.Config.purs
client/config/prod/Try.Config.purs
client/examples/Main.purs
, in thefromExample
function.
If you are preparing a release or if you need to adjust examples in development, you should change the tag in these three places (and ensure you're using the same tag in each place!).
The server is a very basic web service which wraps the PureScript compiler, allowing clients to send PureScript code to be compiled and receiving either compiled JS or error messages in response. It is hosted at https://compile.purescript.org/.
- Request body: PureScript code defining a module whose name must be Main
- Status code: 200 (success)
Response body on compilation success:
{
"js": "...", // a string containing JavaScript code
"warnings": [ ... ] // an array of warnings, using the same format as the
// compiler's --json-errors flag
}
Response body on compilation failure:
{
"error": {
"tag": "CompilerErrors",
"contents": [ ... ] // an array of errors, using the same format as the
// compiler's --json-errors flag
}
}
Response body on other errors (eg, the name of the module in request body was not Main, or the request body was too large)
{
"error": {
"tag": "OtherError",
"contents": "..." // a string containing an error message
}
}
Note that the API returns a 200 response in all of the above cases; in particular, if the code in the request body fails to compile and the API returns errors, this is still considered a success. Among other things, this makes it easier to use the API from another domain using CORS.
The output code will contain references to any imported modules using require
calls.
To run these files in the browser, it is necessary to either use a require
shim (such as require1k), or replace these calls and deploy a bundle of precompiled modules.
The Try PureScript client uses the first approach.
The server exposes the compiled JS for all of the modules it has access to.
If the compiled JavaScript code in the response includes a require
call such as require(../Web.HTML/index.js)
, then the client is expected to arrange things so that this require
call provides access to the JavaScript code available at the URL path /output/Web.HTML/index.js
, via a shim or otherwise.
The server application takes the following arguments on the command line:
- port number
- a list of input source files
trypurescript 8081 'bower_components/purescript-*/src/**/*.purs'