"Janet Playground" proof of concept -- request for input

[MikeBeller]

I am working on a WebAssembly based Janet Playground. The idea is for trying, documenting, and sharing Janet code and posting "live docs" examples that can run in the browser. It is inspired by the go playground, play.golang.org, and I shamelessly stole their CSS styles. Here is a proof of concept version of it. Please try it out! You can edit the code there and run whatever you want (It's running in your own browser).

https://externalweb.s3.amazonaws.com/play/play.html

There is a web repl already on the Janet home page but I do not find it sufficient for my use cases:

Use case A: Just trying out some code without having to fire up an editor or even install Janet.

Use case B: Creating online documentation where the examples are executable.

Use case C: For sharing live code with others for discussion purposes.

The code I wrote works for A and B (it demonstrates case A but to do case B all you have to do is modify the html page to have multiple "code" and "output" locations, and intersperse with your docs.)

For case C we will need some kind of back end. For that we will need a non-static web server. I do not have one now and wondering if the community does?

Anyway -- looking for feedback on all of this. Code is also available at https://github.com/MikeBeller/janet-playground but it is very primitive still. No useful build organization. That will evolve.

[pepe]

Case A: Nice work!

Case B: I guess combination with source documenting capabilities of Mendoza will be a good match.

Case C: I can easily see Osprey as a good solution. I am adding a web interface to the Neil project, so I have experience using it (and it is not that much to learn), so I can definitely help with this. It is not only that. You will need some persistent storage and other usual suspects. But I think I am aware of a good solution for any of those problems in the community codes.

[MikeBeller]

Thanks @pepe . Osprey looks really nice. I'm sure I could easily develop a back end with that. But one question I have is does the Janet community have a maintained webserver (i.e. not a static site like github pages) so that I could use that to host the backend? Otherwise I will have to put up my own server just for this extremely limited usage. (for example do you know: Is janet-lang.org an active or static website?)

I'm thinking of just having people use public gists for the persistent storage -- so we don't have to maintain any database.

Also what is the Neil project?

[pepe]

Sorry for misread. It makes better sense now and I feel dumb 🤦‍♂️. I can provide space on a shared server for a while I guess, I am using to run my Janet code now.

About the community webserver, I do not know anything tho. But janet-lang.org seems to be all static Mendoza generated site.

[sogaiu]

@MikeBeller FWIW, I think pepe was referring to this: https://git.sr.ht/~pepe/neil

[pepe]

Indeed I did. I have written to @MikeBeller DM on matrix, not to hijack the debate here. But now I see Mike is still on gitter, so I am not sure he got the message.

[MikeBeller]

Ah yes @sogaiu / @pepe thanks that explains "Neil". Looks interesting. I don't think I have that much discipline. :-)

[uvtc]

Hi, Mike.

What is the difference between the repl at janet-lang.org and the Janet Playground?

In my own experience, I've found that

1. some people may want to learn a little Janet, but they don't have access to install Janet on their machine, and
2. being able to write programs that draw moving shapes (like with jaylib) is a big motivator for learners.

Is there any way to have the Janet Playground run jaylib, with a split window so users can see their graphical output in an additional pane, all in one browser tab? My understanding is that raylib can provide output for the browser, but I'm not sure that's been set up in jaylib yet.

I think this would be huge. I know some people who would immediately find that useful. I would also find it immediately useful for demo purposes.

[MikeBeller]

Hi @uvtc -- the main difference: Whereas the "playground" allows you to edit a bunch of code and then run it all at once, the thing on on janet-lang.org is an actual repl, where you can execute sequential forms. The page keeps an open fiber, and sends the forms to the fiber for sequential execution. It sounds cool, but in my experience the UI is very difficult to use for use cases A, B and C in my original email. The repl doesn't really allow repeated editing of anything longer than a short line. So try writing a 6-line function in it and continually editing. Yuck. Goals A, B, C are about learning and sharing code and I think the large editable window with 1-shot execution is better.

As to jaylib -- very interesting! I looked up and found out that raylib does compile to webassembly, so it may be possible - though not trivial to accomplish given all that has to be integrated. I will put it on my list of "potential janet playground improvements", but to be honest I may not attack it first as there are much simpler enhancements I need first so I can cover case C above. Will definitely keep it in mind though! (Of course if you wanted to take a stab please feel free!)

[uvtc]

So, the Janet Playground and also the repl at janet-lang.org both compile to wasm?

This sounds excellent, btw. Thanks so much. It's even more convenient than sending someone a gist; just send them the specific link to the janet-playground and the code is right there for them to modify/execute.

[MikeBeller]

Yes -- emcc will compile the Janet amalgamation just fine. One trick (as shown by my janet/MAKE script) is you can not at this time produce what is known as a "standalone" wasm module because Janet requires many items from the emcc standard library. You use the .js output type on emcc, and emcc produces a .wasm file and a .js file which have to be used together. (The .js file loads the .wasm file, but also exports to the .wasm module all kinds of "stub" functions for the C stdlib to provide a fake OS for Janet to run in.)

[sogaiu]

@MikeBeller Haven't tested running yet, but was able to build janet.wasm by doing the following:

• clone respository and cd to resulting dir
• create build subdir
• copy static/js/janet.js into build
• cd janet
• adjust MAKE for use of local emsdk_env.sh
• run the MAKE script

Now I see a new janet.wasm file in the build dir.

Does that sound about right?

Just writing this up in case there are other folks who want to try.

[MikeBeller]

Yes -- I apologize as there are incomplete build scripts as yet. Actually @sogiau once you have emcc set up you really just need to cd to janet/ directory and run ./MAKE (a shell script). Then copy the janet.js and janet.wasm from build/ to static/js

To deploy it you just deploy the contents of static (including the js/ subdirectory) to any static site and access play.html -- it should just work

Mike

[sogaiu]

Thanks for the tips!

Building and execution appear to be fine now :)

One minor obstacle was this:

$ sh MAKE
Setting environment variables:
EMSDK = /home/user/src/emsdk

shared:ERROR: specified output file (../build/janet.js) is in a directory that does not exist

After doing mkdir ../build, sh MAKE completed without errors and copying the two files in build to static/js and starting up a web server led to a functioning interactive janet exeperience in the brower :)

Thank you!

[MikeBeller]

Thanks @sogaiu I am cleaning up the github repo to include installation instructions and more complete scripts. mkdir -p ../build will be added. :-)

[sogaiu]

The "bundled" janet.wasm seems to work fine:

When I tried my locally built one for the evaluation result I see "running..."

Wonder what I'm doing wrong...I guess my emsdk may be old.

[MikeBeller]

Yes it may require a recent emsdk. I am using emcc 2.0.11

But you are welcome to use it on the current link for now while I work on making it easier to deploy --

https://externalweb.s3.amazonaws.com/play/play.html

[sogaiu]

@MikeBeller So after walking around in subzero (celcius) weather for a bit, a couple thoughts came up...

I have a work-in-progress PEG tutorial: https://gitlab.com/-/snippets/2053876

As you can see, it's quite long (too long perhaps).

I've found successive evaluation with some narrative / annotative text to be quite helpful in becoming more familiar with various libraries, programming language constructs, etc. Modifying existing forms but also coming up with one's own seems to also help with memory (at least in my case).

I got to thinking about how one might try to provide this kind of thing using the wasm janet-playground.

One way might be to try to have multiple instances on a page. I'm not sure how all of this works, but depending on the details, it seems like it could be a problem in terms of brower resources. Another issue might have to do with continuity of state between one instance and another (e.g. the result of a def in one instance might not "carry over" to another instance.).

An alternative approach is to have one (or a few) large "windows" on a page that have multiple "sets of forms" that work together:

(def a 1)

(+ a 2)

(let [x a] (+ x 3))

...but have some way to not evaluate everything at once. In Emacs terms that might be something like evaluate the last s-expression, based on where one's cursor is.

Presumably to make that ergonomic one would want some sort of shortcut / hot key to invoke evaluation. Possibly also some nice way to display an evaluation result so that it is clear which form that's associated with.

A possibly related thought is that tree-sitter can generate .wasm output. @GrayJack has made a tree-sitter grammar for Janet, so I wonder whether there's some way to get that hooked up to enhance the editing experience...

[MikeBeller]

Ah. Yes I agree with you. Actually I don't mean paredit. I just kind of mean something that highlights the matching left paren every time you type a right paren. That plus autoformat.

[sogaiu]

@uvtc Thanks for pointing out the Chicken Scheme site and specifically the code-related bits.

I see that if one scrolls up from: http://wiki.call-cc.org/man/5/Using%20the%20interpreter#toplevel-commands there is an example that has the "rainbow parens"-ish feature.

On a side note, I too am not a "paredit" user, but I do use some things that are typically included (e.g. navigation based on s-expressions and cutting an s-expression). Though I wonder if those are really desirable in this current context.

For the current playground case, I think it would be great to have "evaluate last s-expression". If there is a good way to do this without tree-sitter (may be using something from Janet's parsing capabilities?) possibly that's a better approach.

I think there may be non-tree-sitter highlighting solutions that could work here, e.g. Rouge. I suspect @pyrmont knows better :)

For formatting, may be it's possible to use spork/fmt (or pieces of it) toward that end.

[MikeBeller]

I'm working on spork/fmt for formatting. (Not sure how best to get spork into my wasm build so that's the holdup.) I'd like to keep things simple at the start and have the playground always run the whole code cell. It's supposed to be for learners so complexity is to be avoided. I definitely misspoke when I said paredit -- I really just mean "show me the left paren when I type a right paren". KISS principle. Anyway, right now I think integrating with janetdocs is my main focus. Would be great if you could easily run (and tweak and rerun) every example right in janetdocs. But I think it would help if I got @swlkr views on how best to integrate. I will try to track him down in gitter some time (unless he happens to still be watching this thread. You there @swlkr? )

[sogaiu]

Thanks for the current-focus-clarification, it makes sense to me too.

/me tries some summoning spells but realizes he doesn't know any...

[MikeBeller]

LOL. BTW: Just learned you can "preload" files into the mock filesystem that emscripten creates. That means I could make available a set of (popular) modules in the playground. :-)

[saikyun]

I like this. If I could make two requests, they would be:

1. A hotkey (e.g. ctrl+enter) to run the code without using the mouse
2. Seeing the final result, even when not using print (often code I want to share doesn't naturally contain prints)

[MikeBeller]

Thanks @saikyun -- I will add ctrl-enter in my next version. Final result ...that's a bit trickier. Let me think about that one I can probably make it happen without making it too complicated. (Currently using janet_dostring call which doesn't have an obvious way of returning a non-error result.) I will look in to it.

[MikeBeller]

Actually @saikyun I figured it out. The proof of concept version at https://externalweb.s3.amazonaws.com/play/play.html now contains both your feature requests. It prints the "result" of your code, and also supports ctrl-enter.

[uvtc]

Oh, nice! Looks like it prints the value of the last expression. Might be useful to have that displayed in a different color than the rest, so as not to be confused with print statement output.

[MikeBeller]

@uvtc -- I couldn't make up my mind re differentiating the result from the print statements. I tried it both ways, and ended switching back to having them both look the same. I will keep this in mind and wait to see if your view is echoed by others.

[sogaiu]

I agree that being able to have some way to differentiate would be good.

I think it is easy to get confused in some situations otherwise.

Specifically how it is achieved, I don't yet have an opinion on.

[pyrmont]

This looks like a cool project! In answer to your question about whether 'the community' has a webserver, janet-lang.org is a server that is administered by @bakpakin. He mentions on his GitHub Sponsors page using donations to cover this cost. Perhaps something like this could live there.

Alternatively, while it would probably not be adequate for large-scale usage, Heroku's free tier is another option. I used to maintain the syntax highlighter Rouge and its preview dingus is a Sinatra app that runs entirely on the free tier there. I made a buildpack that can be used for deploying web apps written in Janet that could be of use if you wanted to pursue that route (discussed more in #574).

[pepe]

Well, I guess the whole spork would not be possible as there is net/ code, which is not working in .wasm.

[MikeBeller]

True but whatever works works, and whatever doesn't, doesn't. True also of other OS calls which are mocked by emscripten. Some have limited functionality, and some have none. Have to live with that for now.

[MikeBeller]

@uvtc I missed your earlier question -- it stores the code in the page. you just load up janet.js and playground.js into your webpage and you get a new function run_janet_code(code_string, output_element), and that is all you need to do! so I think it will be pretty easy to integrate with janet-docs for example (except that janet-docs UI intersperses a bunch of formatting tags so if I do a PR I will need to stash a "clean" version of the code on the page for use by run_janet_code).

[uvtc]

So, the code is in the link, correct? That is, you click the link at JanetDocs, and the link contains the code to display in JanetPlayground?

[MikeBeller]

The most straighforward is that the code is on the page in some text element. E.g. a textarea. You put a button next to it "run" that when clicked calls janet_run_code, giving it some other element on the page to use for its output (e.g. a div below the code). So the code is in the page in that case, not in the link. Similarly in the Janet Playground right now, the demo code that is in the page is in the textarea in the HTML of that page. To make it work like you suggest -- that you click on a link and that launches the playground with some specific (not static) code, determined by the link (e.g. an HTTP post request with the code in the post), requires an active back end which would send back the page with the code from the POST already loaded. Could definitely be done very easily -- would just need somewhere to host it. ( For the case of JanetDocs there is no need because there already IS a backend. For JanetDocs I would just need to modify the JanetDocs system to add a bit more code on each page, plus a run button, (plus including the two javascript files in the page load) in order to make each JanetDocs example executable, with the output coming back on the very page of the JanetDocs examples.

[yumaikas]

So, I'd like this to follow more in the style of the Janet website than the go playground CSS, for my two cents. Usually language playgrounds tend towards unique styles, rather than aping other ones, and I like the visual style of Janet's janet-lang.org

[MikeBeller]

Thanks @yumikas -- I think that's a good idea but not sure which styles from janet-lang.org to apply to which parts of my code. I'm really terrible at visual styling in general and css in particular. I pulled the google playground one because it was already tied into an HTML that did approximately what I wanted. If you have a more specific suggestion (or even a PR on janet-playground) as to how to fix, I'd be happy to adopt!

[yumaikas]

True, janet-lang.org is a pretty bland website outside of the front page. I also like janet-docs for it's look: https://janetdocs.com/

The one thing, I think I dislike about the Go playground the most (and I know you weren't a party to it), is that it doesn't do syntax highlighting. I don't yet know how to make it happen in a JS code editor, but I really like rainbow parens for editing Janet. I do know that https://ace.c9.io/ provides a decently fully featured editor that I plan on using next time I put Janet editing (for a personal project) online myself.

Another thing I noticed is that this playground doesn't print out certain type names? Like, I tried to use the playground for this https://gist.github.com/yumaikas/a131ab310e3735b4e4e42f5516c08cae/2a0a760a401369abf2b3c0d5eaadc24939e0faf4 to help someone out in the gitter, and it didn't print out the <tuple 0xDEADBEEF> in the peg/match error that code spits out, so I had to test on my laptop.

Thanks for taking a step with this though, I appreciate it!

[MikeBeller]

Thanks Yumikas. (1) I will look in to ace and other ways of getting syntax support. It looks like ace allows you to write a syntax file module for your particular language (in this case Janet), but that is perhaps more work I wanted to do for basic editing capabilities. Tree-sitter was suggested as another approach. Or maybe just whenever someone types ) I should check back through the text and find the matching ( and highlight it? Perhaps that would be enough. As to (2) I think it is a bug. I will work on tracking it down. I filed an issue (the first for the janet-playground project).

[MikeBeller]

Hey @yumaikas I just fixed the <tuple 0xDEADBEEF> problem. You can try again in the demo playground. I had failed to htmlEscape the output, so the text was there but it was getting eaten in HTML rendering. Minor add'l tweak: now distinguishes the result of the final form with RESULT> so you can distinguish it from print output.

[MikeBeller]

Hey y'all -- thanks for the input. I incorporated a number of ideas from you all. Better usability, better emcc build, some JPM, built-in local server for testing. I created an "explanation page" and a "live docs" example. All my examples have truly horrible or nonexistent CSS because it's just not my thing. sigh. Will eventually have to improve that.

Online demo: https://externalweb.s3.amazonaws.com/play/index.html
Source (with built in local server) https://github.com/MikeBeller/janet-playground

Next major step will be integrating with a back end. @swlkr suggests integrating with janetdocs -- sounds good to me. I am looking in to it.

[sogaiu]

Thanks for the case B example! So far it has been working well.

On a side note, I am encountering a difficulty with case A. After I click on the "Run" button I only see "running..." below the text area.

In case it wasn't clear, above I meant on your online demo.

Hmmm, weird...it seems to work sometimes but not others...

[MikeBeller]

Thanks for the input @sogaiu -- can you give me an example of code that does not work and code that does? I did notice something about memory limitations that I am looking into and perhaps that has something to do with it. But if it's code specific, then example code would be very helpful.

[sogaiu]

@MikeBeller It would happen with the default code sporadically -- I didn't change anything. Perhaps there was something odd with my browser.

When I try it now it seems fine.

Hoping it was just something on my end!

[MikeBeller]

If it happens again can you bring up your browser's "inspector" and let me know what you see in the console? (Clear the console, reproduce the behavior, send the console contents.)

[MikeBeller]

Hey gang thanks for the input. I put up a new version with the ace editor, syntax highlighting (using clojure mode). The bug involving not printing types is also fixed. Give it a spin if you wish! https://externalweb.s3.amazonaws.com/play/play.html

[sogaiu]

Re: #570 (comment)

Nice!

The syntax highlighting and evaluation have been working well 👍

How is the indentation determined currently?

Some minor notes:

• I don't see any visual change when I click on the "About" button.
• Indentation seems to be 4 spaces -- is that something that's easy to configure?

[MikeBeller]

Hi yes -- I just took the defaults for ace editor in clojure mode. I know I need some work to align with janet formatting standard. On my list...

About button -- I thought I marked it "disabled" in the HTML .... ah the CSS makes no distinction. Thanks for the heads up.

[MikeBeller]

New version of Janet Playground. Now integrated with JanetDocs. Now includes spork/format based formatting, and integrates with the examples on janetdocs. Try it here: https://janetdocs.com/playground -- old playground will go away soonish.

[uvtc]

Wow! This looks awesome. I like how it not only shows output printed but also the "RESULT>" value. The autoindentation when typing feels like too much, but the "format" button fixes it up. Thanks for this!

[MikeBeller]

Thanks John! Yeah having the autoindentation exactly track what spork/format would do is actually pretty tricky so I decided to leave it at "good enough" for now.

[MikeBeller]

Actually @uvtc I just realized what you meant by "too much". I had a typo in my code and it defaulted the tabs to 4. I will clean it up to 2 on the next major update. (I don't want to bother @swlkr with a small commit like that.)

[uvtc]

Ah! Whoops, I see I was unclear about that.

[MikeBeller]

Oh not at all. I just misread. I already have a fix in my fork of janetdocs, but as I said I'm working on a larger update before sending a PR.

…

On Thu, Jan 28, 2021 at 3:00 PM John Gabriele ***@***.***> wrote: Ah! Whoops, I see I was unclear about that. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#570 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAM7HKTHTQRXAXOAPEUHBCDS4G67DANCNFSM4V4T3RAA> .