arclanguage / rainbow-js Goto Github PK

In the browser-based REPL, running the (rat) unit tests gives one test failure with a very clear error message: "No filesystem."

We could do the same thing for other operations the unit tests use, such as java-new. Having some binding for java-new will then cause a few more files of unit tests to run, as per the conditional logic in src/arc/lib/unit-test.arc. (Like the other unit tests, these extra ones pass except for some expected failures, like when they attempt to use the java-... FFI operations.)

We should document the library people get when they require("rainbow-js-arc") from a Node.js program. This is the API surface area that should be documented:

const rainbowLibrary = require("rainbow-js-arc");

const rainbowInstance =
    rainbowLibrary.makeRainbow(
       System_in, System_out, System_err, System_getenvAsync0,
       System_getenvAsync1, System_exitAsync, System_fs);

const rainbowInstance2 =
    rainbowLibrary.makeNodeRainbow(stdin, getStdout, getStderr);

const rainbowInstance3 = rainbowLibrary.getSharedRainbow();

The documentation for makeRainbow() is bound to be the most complex part. If possible, we should document it thoroughly enough that people can write their own I/O systems for Rainbow.js like index-first.js, index-last.js, and rainbow-node-src.js do.

I've put together a few of these recently:

• Lathe Modules for JS, probably the most polished take on it so far.
• Cene for JS
• Anarki

Currently, timing begins from the moment Console_st.mainAsync() is called. In Java, the start of main is one of the earliest, if not the earliest, possible times to do something. But in our Node.js and web REPLs, we spend some time loading Rainbow.js itself, and we can potentially start the clock much earlier on. Let's do that.

We should create a rainbow-js-args run [args...] subcommand that has functionality similar to rainbow-js-args run-compat [args...] for executing Arc programs in batch mode and starting REPLs.

By allowing ourselves to change the CLI syntax, we can probably achieve a bit more flexibility than what Java Rainbow supports, such as the way Racket's CLI supports interleaving files to load and expressions to evaluate. Java Rainbow's CLI can already execute multiple files and multiple expressions, but it executes every file before executing any of the expressions.

The readme and the demo page could be updated in a few ways:

• Give more up-to-date instructions for how to install and run the project. Let's formulate some specific advice for how to set up Node.js applications and front-end web libraries that run Arc code using Rainbow.js.
• Reevaluate how the performance compares with Java Rainbow. We should at least tone down the old excitement we had that was based on a version of Rainbow.js that didn't pass the unit tests, but we might have a more interesting perspective to show if the benchmarks can run (#5).
• Most features that don't yet exist are possible to "implement" in the same way we do already for System_out, System_getenvAsync0, and so on, where different wrappers like src/node/rainbow-node.js and src/web/index-first.js implement these variables in ways that make the most sense for their platforms. Threads are absolutely possible to implement in terms of continuation-passing style, too, which was something I learned in part thanks to doing this port. While I didn't start porting this project with that extent of parity in mind, it is possible, and let's make sure the readme reflects that potential.

The npm install rainbow-js-arc npm package is currently better than nothing, and it has two parts, neither of which is in the best shape:

• A Node.js library that can be imported with require("rainbow-js-arc"). This library has no documentation.
• A rainbow-js-arc command that can execute Arc code. This command has to be run from the node_modules/rainbow-js-arc/src/arc/ directory, or else it can't load essential libraries like arc.arc.

Let's facilitate a workflow like this:

• Application developers set up a directory in which they assemble arc.arc and all the libraries they're using.
• Library developers offer a command that operates on a given directory by performing one of the following tasks:
  • Copying the library's Arc code into the directory.
  • Getting a map from library versions to a list of file paths that represent code belonging to this library, application state belonging exclusively to this library, and application state which may be a collaboration between libraries. This list can be used to back up and restore application state on a whole-application or per-library basis, and it can be used to facilitate certain simple cases of library uninstallation or upgrade.
• Rainbow.js offers a command that operates on a given directory by performing one of the following tasks:
  • Performing any of the above tasks for the core libraries (such as arc.arc).
  • Performing compound package management actions, such as library upgrades.
  • Executing batch-mode Arc programs based on some given filenames or expressions.
  • Starting a REPL.
  • Perhaps other, more adventurous things, like attaching a REPL to another running Arc program, running an Arc program in such a way that files reload automatically when modified, or starting a language server for IDE interaction.
  • Interpreting command line arguments in a way that conforms better with what the original Rainbow would do. This way, if we change up the command line argument parsing logic somewhat, we can still retain some parity with Java Rainbow.