From 14f0c7a66307107df1fef350b9bf6325dc7a315e Mon Sep 17 00:00:00 2001 From: Eric Vergnaud Date: Sat, 17 Dec 2016 00:03:03 +0800 Subject: [PATCH] also published to npm --- doc/ace-javascript-target.md | 18 +++++++++++++----- runtime/JavaScript/src/antlr4/package.json | 2 +- runtime/JavaScript/src/npm.txt | 12 ++++++++++++ 3 files changed, 26 insertions(+), 6 deletions(-) create mode 100644 runtime/JavaScript/src/npm.txt diff --git a/doc/ace-javascript-target.md b/doc/ace-javascript-target.md index fbba9e9b9..63b8826e2 100644 --- a/doc/ace-javascript-target.md +++ b/doc/ace-javascript-target.md @@ -174,13 +174,20 @@ At this point, you should have an editor which displays an error icon next to th What remains to be done is have our validate function actually validate the input. Finally ANTLR comes in the picture! -To start with, let's load ANTLR and your parser, listener etc.. Easy, since you could write: +To start with, let's load ANTLR and your parser, listener etc.. + +The preferred approach for loading parser code is to bundle your parser, [as described here](javascript-target.md). +You can then load it as part of the importScripts instruction at the start of your worker code. + +Another approach is to load it using 'require'. Easy, since you could write: ```js var antlr4 = require('antlr4/index'); ``` -This may work, but it's actually unreliable. The reason is that the require function used by ANTLR, which exactly mimics the NodeJS require function, uses a different syntax than the require function that comes with ACE. So we need to bring in a require function that conforms to the NodeJS syntax. I personally use one that comes from Torben Haase's Honey project, which you can find here. But hey, now we're going to have 2 'require' functions not compatible with each other! Indeed, this is why you need to take special care, as follows: +This may work, but it's actually unreliable. The reason is that the 'require' function that comes with ACE uses a different syntax than the 'require' function used by ANTLR, which follows the NodeJS 'require' convention. +So we need to bring in a NodeJS compatible 'require' function that conforms to the NodeJS syntax. I personally use one that comes from Torben Haase's Honey project, which you can find in li/require.js. +But hey, now we're going to have 2 'require' functions not compatible with each other! Indeed, this is why you need to take special care, as follows: ```js // load nodejs compatible require @@ -191,7 +198,8 @@ importScripts("../lib/require.js"); var antlr4_require = require; require = ace_require; ``` -Now it's safe to load antlr, and the parsers generated for your language. Assuming that your language files (generated or hand-built) are in a folder with an index.js file that calls require for each file, your parser loading code can be as simple as follows: +Now it's safe to load antlr and the parsers generated for your language. +Assuming that your language files (generated or hand-built) are in a folder with an index.js file that calls require for each file, your parser loading code can be as simple as follows: ```js // load antlr4 and myLanguage var antlr4, mylanguage; @@ -204,6 +212,7 @@ try { } ``` Please note the try-finally construct. ANTLR uses 'require' synchronously so it's perfectly safe to ignore the ACE 'require' while running ANTLR code. ACE itself does not guarantee synchronous execution, so you are much safer always switching 'require' back to 'ace_require'. + Now detecting deep syntax errors in your code is a task for your ANTLR listener or visitor or whatever piece of code you've delegated this to. We're not going to describe this here, since it would require some knowledge of your language. However, detecting grammar syntax errors is something ANTLR does beautifully (isn't that why you went for ANTLR in the first place?). So what we will illustrate here is how to report grammar syntax errors. I have no doubt that from there, you will be able to extend the validator to suit your specific needs. Whenever ANTLR encounters an unexpected token, it fires an error. By default, the error is routed to an error listener which simply writes to the console. What we need to do is replace this listener by our own listener, se we can route errors to the ACE editor. First, let's create such a listener: @@ -243,5 +252,4 @@ var validate = function(input) { }; ``` You know what? That's it! You now have an ACE editor that does syntax validation using ANTLR! I hope you find this useful, and simple enough to get started. -What I did not address here is packaging, not something I'm an expert at. The good news is that it makes development simple, since I don't have to run any compilation process. I just edit my code, reload my editor page, and check how it goes. -Now wait, hey! How do you debug this? Well, as usual, using Chrome, since neither Firefox or Safari are able to debug worker code. What a shame... +WNow wait, hey! How do you debug this? Well, as usual, using Chrome, since no other browser is able to debug worker code. What a shame... diff --git a/runtime/JavaScript/src/antlr4/package.json b/runtime/JavaScript/src/antlr4/package.json index 5e6f8d299..34a7e1eca 100644 --- a/runtime/JavaScript/src/antlr4/package.json +++ b/runtime/JavaScript/src/antlr4/package.json @@ -1,6 +1,6 @@ { "name": "antlr4", - "version": "4.6", + "version": "4.6.0", "description": "JavaScript runtime for ANTLR4", "main": "src/antlr4/index.js", "repository": "antlr/antlr4.git", diff --git a/runtime/JavaScript/src/npm.txt b/runtime/JavaScript/src/npm.txt new file mode 100644 index 000000000..66dacd9df --- /dev/null +++ b/runtime/JavaScript/src/npm.txt @@ -0,0 +1,12 @@ +publishing to npm +================= +The JavaScript runtime is published on npm. +There is nothing to build since JavaScript is based on source code only. +The JavaScript itself is tested using npm, so assumption is npm is already installed. +The current npm version used is 3.10.9. +The publishing itself relies on the information in src/antlr4/package.json. +To publish, from Terminal, you need to navigate to the src/ directory. +Once there, login: npm login +Then npm publish antlr4 +That's it! +