diff --git a/_misc/import_regex_tester.pl b/_misc/import_regex_tester.pl index 6b304e9..3b330a6 100755 --- a/_misc/import_regex_tester.pl +++ b/_misc/import_regex_tester.pl @@ -20,11 +20,11 @@ with the following differences: (see import_regex_tester.pl) ENDMSG -( $html =~ s{ <(?script\s+src="webperl\.js"\s*> }{}xms )==1 or die; -( $html =~ s{ }{<$+{x}>}xms )==1 or die; -( $html =~ s{ ^ \s* our \s+ \$RUN_CODE_IN_IFRAME\s*=\s*\K0(?=\s*;\s*) }{1}xms )==1 or die; -( $html =~ s{ https?://github.com/haukex/webperl/blob/\Kmaster/web/regex_tester.html }{gh-pages/regex.html}xms )==1 or die; -( $html =~ s{ \#\#\#\#\#\s*-->\n\K }{\n\n}xms )==1 or die; +( $html =~ s{ <(?script\s+src="(?:webperl\.js|__WEBPERLURL__)"\s*> }{}xmsg )==2 or die; +( $html =~ s{ }{<$+{x}>}xmsg )==2 or die; +( $html =~ s{ ^ \s* our \s+ \$RUN_CODE_IN_IFRAME\s*=\s*\K[01](?=\s*;\s*) }{1}xmsg )==1 or die; +( $html =~ s{ https?://github.com/haukex/webperl/blob/\Kmaster/web/regex_tester.html }{gh-pages/regex.html}xmsg )==1 or die; +( $html =~ s{ \#\#\#\#\#\s*-->\n\K }{\n\n}xmsg )==1 or die; open my $ofh, '>:encoding(UTF-8)', $outfn or die "$outfn: $!"; print $ofh $html; diff --git a/building.md b/building.md index dc7c8e5..62aaf92 100644 --- a/building.md +++ b/building.md @@ -5,8 +5,8 @@ Building - [Legal](legal.html) - [GitHub Wiki](https://github.com/haukex/webperl/wiki/Building-WebPerl) \] -🕸️🐪 Building WebPerl -=================== +Building WebPerl +================ **Notice: WebPerl is very much in beta.** @@ -48,6 +48,15 @@ The source code is in two repositories: You only need to check out the first of the two, the `emperl5` repository is checked out by the build script. +Some of the central source files of WebPerl are: + +- [`webperl/build/build.pl`](https://github.com/haukex/webperl/blob/master/build/build.pl) +- [`emperl5/hints/emscripten.sh`](https://github.com/haukex/emperl5/blob/emperl_v5.28.0/hints/emscripten.sh) +- [`emperl5/perlmain_noexit_patch`](https://github.com/haukex/emperl5/blob/emperl_v5.28.0/perlmain_noexit_patch) +- [`emperl5/ext/WebPerl/WebPerl.xs`](https://github.com/haukex/emperl5/blob/emperl_v5.28.0/ext/WebPerl/WebPerl.xs) +- [`emperl5/ext/WebPerl/WebPerl.pm`](https://github.com/haukex/emperl5/blob/emperl_v5.28.0/ext/WebPerl/WebPerl.pm) +- [`webperl/web/webperl.js`](https://github.com/haukex/webperl/blob/master/web/webperl.js) + Running the Build ----------------- @@ -157,6 +166,9 @@ so for example `Cpanel/JSON/XS` instead of `Cpanel::JSON::XS` Note that the build script does **not** automatically fetch modules' dependencies, for now you will need to resolve them and add them to `EMPERL_EXTENSIONS` yourself. (This may be improved upon in the future.) +You can try out the script +[`experiments/depend.pl`](https://github.com/haukex/webperl/blob/master/experiments/depend.pl), +which uses the MetaCPAN API to resolve dependencies. *** diff --git a/democode/index.html b/democode/index.html new file mode 100644 index 0000000..45f5127 --- /dev/null +++ b/democode/index.html @@ -0,0 +1,208 @@ + + + + +WebPerl Code Demo + + + + + + + + + + +

+This page demonstrates the embeddable +WebPerl +Code Demo Editor (beta), which can be embedded using <iframe> elements, including +sandboxing. +The documentation is contained in the source of this page, please use +the "View Source" function of your browser to view it, or have a look at +the project sources on GitHub. +

+ + + + + + + +

This is a simple example of running a oneliner:

+ + + + + + +

This example includes several files:

+ + + + + + + + diff --git a/democode/perleditor.css b/democode/perleditor.css new file mode 100644 index 0000000..62f566c --- /dev/null +++ b/democode/perleditor.css @@ -0,0 +1,83 @@ + +body { + margin: 0.4em; +} +.text { + font-family: Calibri, Ubuntu, "Droid Sans", Tahoma, Arial, Helvetica, sans-serif; + font-size: 0.9em; +} +pre,textarea,code,.code,.filename,.CodeMirror { + font-family: Consolas, "Ubuntu Mono", "Droid Sans Mono", "Lucida Console", "Courier New", Courier, monospace; +} +pre { + margin: 0; +} +a { + text-decoration: none; +} + +.CodeMirror { + border: 1px solid lightgrey; + height: auto; +} +.CodeMirror-scroll { + max-height: 12em; +} + +.codewithfn { + margin-top: 0.4em; +} +.fnfuncs { + cursor: default; +} +.filename { + display: inline-block; + border: 0; + padding: 1px; + min-width: 1em; + cursor: auto; +} +.filefuncs { + display: inline-block; + padding-top: 2px; + position: absolute; + right: 0.2em; +} +.fakelink { + color: darkblue; + cursor: pointer; +} +.badfilename { + background-color: rgba(255,200,200,255); + /* also has a placeholder text */ + min-width: 10em; +} + +#perlctrl { + margin-top: 0.3em; +} + +#misctools { + display: inline-block; + border: 1px solid grey; + padding: 1px 0.8em 1px 0.5em; + margin-top: 0.5em; +} +#runnerstate { + margin-top: 0.2em; + margin-bottom: 0.3em; +} +#runnererrors { + background-color: rgba(255,200,200,255); + margin-top: 0.3em; + margin-bottom: 0.3em; + padding: 0.1em 0.2em; +} + +#inputhere, #outputhere { + text-align: right; +} + +#footer { + margin-top: 0.5em; +} diff --git a/democode/perleditor.html b/democode/perleditor.html new file mode 100644 index 0000000..6bfd47c --- /dev/null +++ b/democode/perleditor.html @@ -0,0 +1,552 @@ + + + + +WebPerl Perl Editor + + + + + + + + + + + + + + + + + + + + + +
+ + +
+ +
+ Loading... +
+ + + + + + + + + +
+ +
+ Show Tools + +
+
+ + + + + + diff --git a/democode/perlrunner.html b/democode/perlrunner.html new file mode 100644 index 0000000..00532be --- /dev/null +++ b/democode/perlrunner.html @@ -0,0 +1,179 @@ + + + + +WebPerl Perl Runner + + + + + + + + + + + + + + + diff --git a/index.md b/index.md index b659db5..dc9c7b2 100644 --- a/index.md +++ b/index.md @@ -5,8 +5,8 @@ [Legal](legal.html) - [GitHub Wiki](https://github.com/haukex/webperl/wiki) \] -🕸️🐪 Welcome to WebPerl! -====================== +Welcome to WebPerl! +=================== WebPerl uses the power of [WebAssembly](https://webassembly.org/) and @@ -36,8 +36,10 @@ js('document')->getElementById('my_button') - [**Download `webperl_prebuilt_v0.07-beta.zip`**](https://github.com/haukex/webperl/releases/download/v0.07-beta/webperl_prebuilt_v0.07-beta.zip) - [**Get the sources on GitHub**](https://github.com/haukex/webperl) -For a web application written with WebPerl, see the -[**WebPerl Regex Tester** (beta)](regex.html)! +For web applications written with WebPerl, see: + +- [**WebPerl Code Demo Editor** (beta)](democode/index.html) +- [**WebPerl Regex Tester** (beta)](regex.html) Quick Start @@ -56,17 +58,17 @@ Quick Start $ plackup webperl.psgi HTTP::Server::PSGI: Accepting connections at http://0:5000/ -- Then point your browser at - or - , - and have a look at the HTML source of `webperl_demo.html`. +- Then point your browser at + and have a look at its source. The ZIP archive also contains several + other examples, which you can access at . -You may also host the contents of the above ZIP archive on a webserver of your choice, -as described in [Using WebPerl](using.html). (Note: In `webperl_demo.html`, you'll -likely see "AJAX Failed!", which is to be expected since your webserver won't -know how to handle the example AJAX request.) +You may also host the contents of the above ZIP archive on a webserver of your +choice, or some browsers will support opening the files locally; both are +described in [Serving WebPerl](using.html#serving-webperl). +(Note: In `webperl_demo.html`, you'll likely see "AJAX Failed!", which is to be +expected since your webserver won't know how to handle the example AJAX request.) -Have fun! ️🐪 +Have fun! *** diff --git a/legal.md b/legal.md index 2492fa7..54eb3ea 100644 --- a/legal.md +++ b/legal.md @@ -5,8 +5,8 @@ Legal - [GitHub Wiki](https://github.com/haukex/webperl/wiki) \] -🕸️🐪 WebPerl Author, Copyright, and License -========================================= +WebPerl Author, Copyright, and License +====================================== **WebPerl - ** diff --git a/notes.md b/notes.md index d878a97..b9c89ef 100644 --- a/notes.md +++ b/notes.md @@ -5,8 +5,31 @@ Notes - [Legal](legal.html) - [GitHub Wiki](https://github.com/haukex/webperl/wiki) \] -🕸️🐪 Misc. Notes on WebPerl -========================= +Misc. Notes on WebPerl +====================== + + +Links +----- + +Other places I've written about WebPerl: + +- [Run Perl 5 in the Browser!](https://www.perlmonks.org/?node_id=1220426) +- [WebPerl Regex Tester (beta)](https://www.perlmonks.org/?node_id=1221705) +- [Embedding WebPerl Code Demos into Other Pages](https://www.perlmonks.org/?node_id=1223812) + +I also gave a [lightning talk](http://act.perlconference.org/tpc-2018-glasgow/talk/7475) +at YAPC::EU 2018 in Glasgow: [Video Link](https://youtu.be/KrGSg7uVZj0?t=29520) + +[![DOI 10.5281/zenodo.1400490](https://zenodo.org/badge/DOI/10.5281/zenodo.1400490.svg)](https://doi.org/10.5281/zenodo.1400490) + +### In the Press + +- [Reddit: Your scientists were so preoccupied with whether or not they could, they didn't stop to think if they should (2018-10-22)](https://www.reddit.com/r/programmingcirclejerk/comments/9qerw5/your_scientists_were_so_preoccupied_with_whether/) 😉 +- [Hacker News (2018-10-21)](https://news.ycombinator.com/item?id=18269071) +- [Reddit /r/programming (2018-10-21)](https://www.reddit.com/r/programming/comments/9q65tf/run_perl_in_the_browser_with_webperl/) +- [Facebook Group "Perl Programmers" (2018-10-20)](https://www.facebook.com/groups/perlprogrammers/permalink/2141844605848316/) +- [Reddit /r/perl: WebPerl Regex Tester (2018-09-05)](https://www.reddit.com/r/perl/comments/9d5n77/webperl_regex_tester/) TODOs @@ -36,6 +59,13 @@ TODOs - Add Perl.Util functions for making file uploads and downloads easier - Plus an example showing how to use it to run a "legacy" Perl script with inputs and output - Perhaps create a CPAN Bundle:: module or similar for `build.pl` deps? + - There is some potential for restructuring: + - `Perl.glue()` and `Perl.dispatch()` could go into `WebPerl.xs` (?) + - Parts of `webperl.js` could go into `common_preamble.js` or `WebPerl.xs`, + so that `emperl.js` is runnable on its own in a Web Worker (?) + (see notes in `perlrunner.html` / `e12f1aa25a000`) + - `nodeperl_dev_prerun.js` could probably be merged into that as well + - Regarding the funky syntax highlighting on GitHub: 3. See Also @@ -45,6 +75,16 @@ TODOs or using the included `findtodo.sh`. +SSL +--- + + $ openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout selfsigned.key -out selfsigned.crt + ... + Common Name (e.g. server FQDN or YOUR name) []: localhost + ... + $ plackup --enable-ssl --ssl-key-file=selfsigned.key --ssl-cert-file=selfsigned.crt web/webperl.psgi + # then go to https://localhost:5000 and accept the certificate warning + Possible Improvements --------------------- @@ -94,12 +134,11 @@ Release Checklist At a minimum there is: - `web/webperl.js` - `Perl.WebPerlVersion` - `emperl5/ext/WebPerl/WebPerl.pm` - `$VERSION` - - `pages/index.md` - download links + - `pages/index.md` and `pages/using.md` - download links - Update [Subresource Integrity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) values as needed, e.g.: - $ perl -wMstrict -MDigest -le 'open my $fh, "<:raw", "web/webperl.js" or die $!; - print Digest->new("SHA-256")->addfile($fh)->b64digest' + $ perl -wMstrict -MDigest::SRI=sri -le 'print sri "SHA-256","web/webperl.js"' - Build and create dist, e.g. `build/build.pl --reconfig --dist=webperl_prebuilt_v0.07-beta` diff --git a/using.md b/using.md index 351da07..f623ae4 100644 --- a/using.md +++ b/using.md @@ -5,8 +5,8 @@ [Legal](legal.html) - [GitHub Wiki](https://github.com/haukex/webperl/wiki/Using-WebPerl) \] -🕸️🐪 Using WebPerl -================ +Using WebPerl +============= **Notice: WebPerl is very much in beta.** @@ -30,6 +30,19 @@ Your feedback is always appreciated! Basic Usage ----------- +### Getting WebPerl + +If you plan on building WebPerl, for example if you'd like to add more CPAN +modules, then head on over to [Building WebPerl](building.html). Otherwise, if +you'd just like to get started quickly and work with the prebuilt WebPerl +(includes many of the Perl core modules plus a couple extras), then download +[`webperl_prebuilt_v0.07-beta.zip`](https://github.com/haukex/webperl/releases/download/v0.07-beta/webperl_prebuilt_v0.07-beta.zip) +and unpack it. This ZIP file includes the contents of the +[`web`](https://github.com/haukex/webperl/tree/master/web) directory of the +source code, as well as the build products `emperl.*` (currently three files). +If you'd like to work with the source code as checked out from GitHub, then you +can copy these `emperl.*` files into the `web` directory of the source tree. + ### Serving WebPerl You should serve WebPerl via a webserver of your choice, or you can @@ -219,6 +232,8 @@ after having passed them to JavaScript, as that will probably cause mysterious b Emscripten provides a virtual file system that also provides a few "fake" files such as `/home/web_user`, `/dev`, and others, so that it resembles a normal *NIX file system. +This filesystem resides entirely in memory in the browser. + Perl's libraries (`*.pm`) are installed into this virtual file system at `/opt/perl`. Note that because the `perl` binary is compiled to WebAssembly and XS libraries are statically linked into it, you won't find any `perl` binary or shared library files in the @@ -368,7 +383,7 @@ This option was added in `v0.05-beta`. Enable this option at any time to get additional trace-level output to `console.debug()`. Defaults to `false`. -#### `Perl.addStateChangeListener` +#### `Perl.addStateChangeListener(function)` Pass this function a `function (from,to) {...}` to register a new handler for state changes of the Perl interpreter. @@ -377,7 +392,7 @@ The states currently are: - `"Uninitialized"` - `Perl.init` has not been called yet. - `"Initializing"` - `Perl.init` is currently operating. -- `"Ready" - `Perl.init` is finished and `Perl.start` can be called. +- `"Ready"` - `Perl.init` is finished and `Perl.start` can be called. - `"Running"` - The Perl interpreter is running, `Perl.eval` and `Perl.end` may be called - `"Ended"` - The Perl interpreter has ended. ~~You might receive several state change notifications for this state.~~ @@ -479,9 +494,11 @@ stored in a Perl scalar `$foo` pointing to a JavaScript object `foo`: regular Perl data structure (deep copy). Note that JavaScript functions are kept wrapped inside anonymous Perl `sub`s. - `jscode` returns a string of JavaScript code that represents a reference - to the JavaScript object. You should treat the string as an opaque value, - no guarantees are made about its format and whether it may change in future - releases. *Do not* call JavaScript's `delete` on this value. + to the JavaScript object. **Warning:** Treat this value as read-only in + JavaScript! *Do not* assign to this value, call JavaScript's `delete` on + this value, etc. (calling methods that may mutate the object is ok, though). + You should treat the string as an opaque value, no guarantees are made about + its format and whether it may change in future releases. This is an advanced function that should not normally be needed, unless you are building strings of JavaScript to run. In that case, you may need to wrap the value in parentheses for it to evaluate correctly in @@ -504,19 +521,20 @@ Unlike the JavaScript to Perl mappings, values are (currently¹) generally *copi Perl to JavaScript, instead of being *referenced*. The exceptions are Perl `sub`s and `WebPerl::JSObject`s. -- Perl arrayrefs become JavaScript arrays -- Perl hashrefs become JavaScript objects +- Perl arrayrefs become JavaScript arrays (deep copy) +- Perl hashrefs become JavaScript objects (deep copy) - Perl coderefs become JavaScript functions - **Warning:** please see the discussion in ["Memory Management and Anonymous `sub`s"](#memory-management-and-anonymous-subs)! - Perl `WebPerl::JSObject`s become references to the wrapped JavaScript objects + (i.e. the underlying JS object is passed back to JS transparently) - Perl numbers/strings are copied to JavaScript via `Cpanel::JSON::XS::encode_json` (with its `allow_nonref` option enabled). This means that the choice for whether to encode a Perl scalar as a JavaScript number or string is left up to the module, and is subject to the usual ambiguities when serializing Perl scalars. See [the `Cpanel::JSON::XS` documentation](https://metacpan.org/pod/Cpanel::JSON::XS). -- Other references, including objects, are currently not supported. +- Other references, including Perl objects, are currently not supported. ¹ So far, the focus of WebPerl has been to replace JavaScript with Perl, and therefore on accessing JavaScript from Perl, and not as much the other diff --git a/webperl.png b/webperl.png index a4359e2..4b7eb80 100644 Binary files a/webperl.png and b/webperl.png differ