Observable is not JavaScript! Documentation?

Community Help
1

This is not a complaint, but merely a comment from a coworker. There are important semantic and syntactic differences. This came up as I recommended using Observable as a core tool for documenting AgentScript, a “kit” for making agent based models.

It was followed by “Oh boy, another thing to learn!”.

I looked at the docs and they’re great but it would be nice to have a “differences between Observable & JavaScript” notebook. The very first line my pal wrote was an es6 import which naturally not only is JS but also must be the first entry in the “file” … notebook.

OK fine, so the dynamic form of import should work. Hmm but that’s a promise so somehow I have to set the .then(module => ....) part to make the module available.

I said this works:

esm1 = import(“https://backspaces.github.io/agentscript/dist/agentscript.esm.js”)

… and naturally I heard “But that’s not JavaScript!”

It goes on but I do think this deserves a concrete “diff” notebook. I think we may be loosing folks who “Just want a JS notebook”.

1 Like
2

The parser for the notebook documents all the added syntax, although that may be too low level for your use cases.

1 Like
3

This is a great idea for documentation. I started one in April (it’s called “Observable’s not JavaScript!” even). I put a bit more work into today and it should be available soon, time permitting. Thanks for the feedback!

3 Likes
4

Possibly "prettier" code formatting would be useful? It hit all the syntactic differences.

5

To briefly dive into the absurdity of modern parsing toolchains :stuck_out_tongue_winking_eye:: for us and probably most projects that implement new languages or language features, you have a few different parsers with really different priorities. Our Acorn-based parser that we use to translate to JavaScript produces an AST, our Prettier-based parser creates a CST (it captures comments, whitespace, and other non-abstract features), and finally the CodeMirror mode doesn’t produce a syntax tree at all - CodeMirror’s editor modes are able to run on arbitrary bits of a document and without storing their output in memory.

The main effort to span two of these worlds is tree-sitter, and there’s an effort to replicate its strategy in CodeMirror 6 - that would allow editor modes to be written more like AST parsers, without having to deal with so much ‘state’ in the parsing. That’s one of the reasons why I’m so excited about CodeMirror 6!

5 Likes
6

@tom Whoa, fascinating! You’re having too much fun!

Is there any chance we could use your experience, either with prettifing ObservableScript or with translating cells to JS, to tease out the “diff” between JS & Observable for documentation purposes?

It would at least nail all the syntax issues.

1 Like
7

Here it is! Please send feedback or suggestions.

3 Likes