wikipeg 6.1.2 → 6.1.3

package/HISTORY.md

@@ -1,5 +1,14 @@
 # Release History
 
+## 6.1.3 (2026-06-03)
+* Add array-transformation rules to --common-lang transformation,
+  which allows you to generate PHP and JavaScript parser from the same
+  grammar specification.
+* Add --esm option to wikipeg binary to allow creation of a JavaScript
+  ESM module.
+* Bug fix to parameter value assertions involving reference
+  parameters, which would previously incorrectly fail a type check.
+
 ## 6.1.2 (2026-05-07)
 * Update jasmine to 7.0.0-pre.1.  This removes the reported security
   vulnerability in the glob package even though this is only used

package/README.md

@@ -589,12 +589,17 @@ All parameters referenced in the grammar have an initial value and can
 be used before their first assignment.
 
 Parameters have a type detected at compile time: boolean, integer,
-string, reference, or labeled expression. Initial values for each type are:
+or string.  Initial values for each type are:
   - boolean: false
   - integer: 0
   - string: ""
-  - reference: null
-  - labeled expression: null (or the integer or string default value)
+
+Parameters can also be a *reference* to a value of one of these types,
+in which case they are initialized to `null`.  Parameters can also be
+set to the value of a labeled expression; these assignments are
+ignored for the purpose of assigning a type and initial value.  However,
+if *every* assignment to the parameter is a labeled expression it is
+given the initial value `null`.
 
 The parameter namespace is global, but the value of a parameter reverts
 to its previous value after termination of the assigning rule reference.
@@ -747,10 +752,39 @@ done to manage the memory cost of excessive caching of simple matches.
 For more predictable caching, you may wish to use the `noInlining`
 option.
 
-Requirements
--------------
-
-* Node.js 6 or later
+Making a release
+----------------
+Each wikipeg release is made to the PHP ecosystem
+(composer/packagist.org) and Node/JS ecosystem (npm/npmjs.org)
+together.
+
+1. Begin by running `composer update-history` which will
+update the [`HISTORY.md`](./HISTORY.md) with the next patch version.
+Update the release number in `HISTORY.md` if this is to be a minor or
+major release.
+
+2. Update the version number in [`package.json`](./package.json) and
+at the top of [`lib/peg.js`](./lib/peg.js).
+
+3. Run `npm install --package-lock-only` to update the version number
+in [`package-lock.json`](./package-lock.json).
+
+4. Commit these changes with the commit message "Release <version number>",
+and push to gerrit. When merged, sign and tag the resulting commit
+with the unprefixed version number; eg `git tag -s 6.1.3`.  Push the
+tag to the origin (`git push origin 6.1.3`) to complete the
+PHP/composer/`packagist.org` release.
+
+5. With the tagged release as your local HEAD, `npm publish` to push
+the release to node/npm/`npmjs.org`.
+
+6. Run `composer update-history` again, which should add an entry to
+`HISTORY.md` for the next "not yet released" version.  Add a `-git`
+suffix to the version number in [`package.json`](./package.json) and
+at the top of [`lib/peg.js`](./lib/peg.js).
+Run `npm install --package-lock-only` to update `package-lock.json`.
+Commit these changes with the commit message "Bump version after
+release" and push to gerrit.
 
 Development
 -----------

package/bin/wikipeg

@@ -33,6 +33,7 @@ Options:
                                      "module.exports")
       --php                          force PHP mode regardless of extension
       --class-name <name>            specify generated PHP class name
+      --esm                          generate ESM module instead of CommonJS
       --cache                        make generated parser cache results
       --allowed-start-rules <rules>  comma-separated list of rules the generated
                                      parser will be allowed to start parsing
@@ -122,6 +123,7 @@ function readStream(inputStream, callback) {
 
 /* This makes the generated parser a CommonJS module by default. */
 var exportVar = "module.exports";
+var sourceSuffix = "";
 var options = {
   cache:    false,
   output:   "source",
@@ -142,6 +144,11 @@ while (args.length > 0 && isOption(args[0])) {
       options.language = "php";
       break;
 
+    case "--esm":
+      exportVar = "const api";
+      sourceSuffix = "\nexport default api;";
+      break;
+
     case '--common-lang':
       options.commonLang = true;
       break;
@@ -318,6 +325,7 @@ readStream(inputStream, function(input) {
 
   if (options.language === 'javascript') {
     outputStream.write(exportVar !== "" ? `${exportVar} = ${source}\n` : `${source}\n`);
+    outputStream.write(sourceSuffix);
   } else {
     outputStream.write(source + "\n");
   }

package/lib/compiler/passes/analyze-params.js

@@ -10,7 +10,7 @@ function analyzeParams(ast, options) {
   var boolIndex = 0;
   var refScopeIndex = 0;
 
-  function registerParamType(name, type, location) {
+  function registerParamType(name, isref, type, location) {
     var paramInfo = getParamInfo(name);
     if (
       (paramInfo.type === 'labeled' && type === 'boolean') ||
@@ -18,12 +18,27 @@ function analyzeParams(ast, options) {
     ){
       throw new GrammarError("Labeled expression parameters can't also be boolean: " + name, location);
     }
+    if (paramInfo.isref === undefined ) {
+      paramInfo.isref = isref;
+      paramInfo.isrefLocation = location;
+    } else if (isref !== undefined ) {
+      if ( paramInfo.isref !== isref) {
+        throw new GrammarError(
+          "Reference type conflict in parameter " + name +
+            " (previous def at " + paramInfo.isrefLocation + ")",
+          location);
+      }
+    }
     if (paramInfo.type !== undefined && paramInfo.type !== 'labeled') {
       if (paramInfo.type !== type && type !== 'labeled') {
-        throw new GrammarError("Type conflict in parameter " + name, location);
+        throw new GrammarError(
+          "Type conflict in parameter " + name +
+            " (previous def at " + paramInfo.typeLocation + ")",
+          location);
       }
     } else {
       paramInfo.type = type;
+      paramInfo.typeLocation = location;
       if (type === 'boolean') {
         if (boolIndex > 31) {
           throw new GrammarError("A maximum of 32 boolean parameters may be defined", location);
@@ -118,14 +133,12 @@ function analyzeParams(ast, options) {
         let assignment = node.assignments[i];
         let type;
 
-        if (assignment.isref) {
-          type = 'reference';
-        } else if (assignment.type === 'increment') {
+        if (assignment.type === 'increment') {
           type = 'integer';
         } else {
           type = assignment.type;
         }
-        registerParamType(assignment.name, type, node.location);
+        registerParamType(assignment.name, assignment.isref || false, type, node.location);
         assignment.paramInfo = getParamInfo(assignment.name);
 
         let refScope = null;
@@ -142,12 +155,12 @@ function analyzeParams(ast, options) {
     },
     parameter_and: function(node) {
       if (node.assert) {
-        registerParamType(node.parameter, node.assert.type, node.location);
+        registerParamType(node.parameter, undefined, node.assert.type, node.location);
       }
     },
     parameter_not: function(node) {
       if (node.assert) {
-        registerParamType(node.parameter, node.assert.type, node.location);
+        registerParamType(node.parameter, undefined, node.assert.type, node.location);
       }
     },
   })(ast);

package/lib/compiler/passes/ast-to-code.js

@@ -337,7 +337,7 @@ function generateJavascript(ast, options) {
       let rule = currentRule;
       // Add reference variables
       for (let name in rule.passedParams) {
-        if (rule.passedParams[name].type === 'reference') {
+        if (rule.passedParams[name].isref) {
           saved.refs.push({reg: allocReg([]), name: name});
         }
       }
@@ -595,7 +595,7 @@ function generateJavascript(ast, options) {
   function makeActionFunc(code, context) {
     var argNames = [];
     Object.keys(context.env).forEach(function(argName) {
-      if (context.envTypes[argName] === 'reference') {
+      if (context.envTypes[argName].isref) {
         argNames.push(language.refArgActionDeclarator(argName));
       } else {
         argNames.push(language.valueArgActionDeclarator(argName));
@@ -641,7 +641,7 @@ function generateJavascript(ast, options) {
    */
   function makeParamExpression(info) {
     if (!currentRule || !currentRule.passedParams[info.name]) {
-      return makeInitialParamValue(info, false);
+      return makeInitialParamValue(info);
     }
     if (info.type === undefined) {
       throw new Error("Undefined parameter type");
@@ -649,7 +649,7 @@ function generateJavascript(ast, options) {
       return [
         '/*', info.name, '*/',
         '(', language.boolParams, ' & 0x', (1 << info.index).toString(16), ') !== 0'].join('');
-    } else if (info.type === 'reference') {
+    } else if (info.isref) {
       return language.refParamValue(info.name);
     } else {
       return language.paramArgName(info.name);
@@ -660,7 +660,7 @@ function generateJavascript(ast, options) {
    * Return an expression which gives the parameter reference object
    */
   function makeParamRefExpression(info) {
-    if (info.type !== 'reference') {
+    if (!info.isref) {
       throw new Error('Cannot make reference object for non-reference parameter ' + info.name);
     }
     return language.paramArgName(info.name);
@@ -669,20 +669,19 @@ function generateJavascript(ast, options) {
   /**
    * Get an expression giving the initial value of a parameter
    */
-  function makeInitialParamValue(info, isref) {
+  function makeInitialParamValue(info, refIsNull) {
     let type = info.type;
+    let isref = info.isref;
+    if (isref) {
+      let val = refIsNull ? 'null' : makeInitialParamValue({type:type});
+      return language.newRef(val);
+    }
     if (type === 'boolean') {
       return 'false';
     } else if (type === 'integer') {
       return '0';
     } else if (type === 'string') {
       return '""';
-    } else if (type === 'reference') {
-      if (isref) {
-        return language.newRef('null');
-      } else {
-        return 'null';
-      }
     } else if (type === 'labeled') {
       return 'null';
     } else {
@@ -861,10 +860,11 @@ function generateJavascript(ast, options) {
 
     for (let name in rule.passedParams) {
       let type = rule.passedParams[name].type;
-      if (type === undefined || type === 'boolean') {
-        continue;
-      } else if (type === 'reference') {
+      let isref = rule.passedParams[name].isref;
+      if (isref) {
         args.push(language.refParamArgDeclarator(name));
+      } else if (type === undefined || type === 'boolean') {
+        continue;
       } else {
         args.push(language.paramArgName(name));
       }
@@ -889,18 +889,7 @@ function generateJavascript(ast, options) {
         args.push('0');
       } else {
         let paramName = language.paramNameFromArg(argName);
-        let type = rule.passedParams[paramName].type;
-        if (type === 'integer') {
-          args.push('0');
-        } else if (type === 'boolean') {
-          args.push('false');
-        } else if (type === 'string') {
-          args.push('""');
-        } else if (type === 'reference') {
-          args.push(language.newRef('null'));
-        } else {
-          throw new Error('Unknown param type: ' + type);
-        }
+        args.push(makeInitialParamValue(rule.passedParams[paramName], true));
       }
     }
     return args;
@@ -926,10 +915,11 @@ function generateJavascript(ast, options) {
 
     for (let name in rule.passedParams) {
       let type = rule.passedParams[name].type;
-      if (type === undefined || type === 'boolean') {
-        continue;
-      } else if (type === 'reference') {
+      let isref = rule.passedParams[name].isref;
+      if (isref) {
         args.push(language.refParamValue(name));
+      } else if (type === undefined || type === 'boolean') {
+        continue;
       } else {
         args.push(language.paramArgName(name));
       }
@@ -945,7 +935,7 @@ function generateJavascript(ast, options) {
   function getCacheLoadRefs(rule) {
     var block = [];
     for (let name in rule.passedParams) {
-      if (rule.passedParams[name].type === 'reference') {
+      if (rule.passedParams[name].isref) {
         block.push(language.cacheLoadRef(name));
       }
     }
@@ -1323,7 +1313,7 @@ function generateJavascript(ast, options) {
       var subresult = recurse(node.expression, newContext);
       subresult.block.push(`// ${node.label} <- ${reg}`);
       context.env[node.label] = reg;
-      context.envTypes[node.label] = 'value';
+      context.envTypes[node.label] = { type: 'value' };
       return subresult;
     },
 
@@ -1334,7 +1324,7 @@ function generateJavascript(ast, options) {
       } else {
         context.env[node.label] = makeParamExpression(node.paramInfo);
       }
-      context.envTypes[node.label] = node.paramInfo.type;
+      context.envTypes[node.label] = node.paramInfo;
       result.condition = 'true';
       result.expression = language.assertionSuccess;
       return result;

package/lib/compiler/passes/transform-common-lang.js

@@ -1,6 +1,8 @@
 "use strict";
 
-var visitor        = require("../visitor");
+var visitor = require("../visitor");
+var transformArray = require("../../utils/transform-array");
+
 
 /**
  * Perform a few simple transformations to convert a special subset of PHP to
@@ -14,6 +16,7 @@ function transformCommonLang(ast, options) {
 
   function transform(code) {
     if (options.language === 'javascript') {
+      code = transformArray.parse(code);
       code = code.replace(/\$this->/g, '');
       code = code.replace(/\$(?=\w+)/g, '');
     }

package/lib/peg.js

@@ -4,7 +4,7 @@ var objects = require("./utils/objects");
 
 var PEG = {
   /* WikiPEG version (uses semantic versioning). */
-  VERSION: "6.1.2",
+  VERSION: "6.1.3",
 
   GrammarError: require("./grammar-error"),
   parser:       require("./parser"),