Merge pull request #11 from MarcelBolten/develop

dev into next

Author: MarcelBolten

.eslintrc.js

@@ -12,35 +12,49 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [14.x, 16.x, 18.x, 19.x]
+        node-version: [20.x, 22.x, 24.x]
         os: [ubuntu-latest, windows-latest, macos-latest]
 
     runs-on: ${{ matrix.os }}
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
+
+      - name: "Install PHP"
+        uses: "shivammathur/setup-php@v2"
+        with:
+          coverage: "none"
+          php-version: "8.1"
+          tools: composer:v2
+          ini-values: error_reporting=-1
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+
       - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
-          cache: npm
+          cache: pnpm
+
       - name: Install dependencies
-        run: npm ci
+        run: pnpm install
+
       - name: Test
         run: npm run test
 
   PHP:
 
     strategy:
       matrix:
-        php-version: [8.0, 8.1, 8.2]
+        php-version: [8.1, 8.2, 8.3, 8.4]
         os: [ubuntu-latest]
 
     runs-on: ${{ matrix.os }}
 
     steps:
       - name: "Checkout"
-        uses: "actions/checkout@v3"
+        uses: "actions/checkout@v4"
 
       - name: "Install PHP"
         uses: "shivammathur/setup-php@v2"

.github/workflows/CI-tests.yml

@@ -1,7 +1,9 @@
-/.phpdoc
-/phpdoc
-/docker/xdebug_out
-/manual-test/output
-/node_modules
-/vendor
+.phpdoc/
+.pnpm-store/
+.vscode/
+phpdoc/
+docker/xdebug_out/
+manual-test/output/
+node_modules/
+vendor/
 composer.lock

.gitignore

@@ -1,15 +1,16 @@
 .git/
 .github/
-.phpdoc
+.phpdoc/
+.pnpm-store/
+.vscode/
 docker/
 manual-test/
 node_modules/
-phpdoc
+phpdoc/
 src/.eslintrc.json
 test/
 vendor/
 .dockerignore
-.eslintrc.js
 .gitattributes
 .gitignore
 .nvmrc
@@ -18,5 +19,7 @@ vendor/
 composer.json
 composer.lock
 docker-compose.yml
+eslint.config.js
 phpstan.neon
+pnpm-lock.yaml
 psalm.xml

.npmignore

@@ -1 +1 @@
-v16.13.0
+v24.0.0

.nvmrc

@@ -7,8 +7,7 @@
 
 return $config->setRules(array(
     '@PSR12' => true,
-    '@PHP80Migration' => true,
-    'braces' => false,
+    '@PHP81Migration' => true,
     'method_argument_space' => false,
     ))
     ->setFinder($finder)

.php-cs-fixer.dist.manual.php

@@ -7,7 +7,7 @@
 
 return $config->setRules(array(
     '@PSR12' => true,
-    '@PHP80Migration' => true,
+    '@PHP81Migration' => true,
     ))
     ->setFinder($finder)
 ;

.php-cs-fixer.dist.php

@@ -3,6 +3,27 @@ Change Log
 
 This file documents all notable changes to PHPeggy.
 
+3.0.0
+-----
+
+Released: TBD
+
+### Breaking Changes
+
+- Node.js v20+ is now required
+- `mbstring` extension is required now. The `mbstringAllowed` option is removed.
+- Drop support for Internet Explorer
+
+### Major Changes
+
+- Add wider support for unicode in grammar files:
+
+
+### Minor Changes
+
+- Fix a bug with named NEVER_MATCH expressions.
+  compare to https://github.com/peggyjs/peggy/pull/454
+
 2.0.1
 -----
 

CHANGELOG.md

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2014-2023 The PHPeggy AUTHORS
+Copyright (c) 2014-2025 The PHPeggy AUTHORS
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

LICENSE

@@ -2,6 +2,17 @@
 [![npm version](https://img.shields.io/npm/v/phpeggy)](https://www.npmjs.com/package/phpeggy)
 [![License](https://img.shields.io/badge/license-mit-blue)](https://opensource.org/licenses/MIT)
 
+- [Migrating from phpegjs](#migrating-from-phpegjs)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Generating a Parser](#generating-a-parser)
+    - [JS API](#js-api)
+    - [Command Line](#command-line)
+  - [Using the Parser](#using-the-parser)
+- [Grammar Syntax and Semantics](#grammar-syntax-and-semantics)
+- [Conversion Guide - Peggy action blocks to PHPeggy](#guide-for-converting-peggy-action-blocks-to-phpeggy)
+
 # PHPeggy
 
 A PHP code generation plugin for
@@ -34,36 +45,38 @@ Follow these steps to upgrade:
 
 ## Requirements
 
-* [Peggy](https://peggyjs.org/) (known compatible with v3.0.0)
+* [Peggy](https://peggyjs.org/) (known compatible with version 5)
+* PHP version >=8 for the created parser
+* `mbstring` extension enabled
 
-Installation
-------------
+## Installation
 
 ### Node.js
 
-Install Peggy with `phpeggy` plugin
+Install Peggy with PHPeggy plugin
 
 ```sh
-$ npm install peggy@3.0.0 phpeggy
+$ npm install peggy@^5.0.0 phpeggy
 ```
 
-Usage
------
+## Usage
 
 ### Generating a Parser
 
-In Node.js, require both the Peggy parser generator and the `phpeggy` plugin:
+#### JS API
+
+In Node.js, require both the Peggy parser generator and the PHPeggy plugin:
 
 ```js
-var peggy = require("peggy");
-var phpeggy = require("phpeggy");
+const peggy = require("peggy");
+const phpeggy = require("phpeggy");
 ```
 
-To generate a PHP parser, pass both the `phpeggy` plugin and your grammar to
+To generate a PHP parser, pass both the PHPeggy plugin and your grammar to
 `peggy.generate`:
 
 ```js
-var parser = peggy.generate("start = ('a' / 'b')+", {
+const parser = peggy.generate("start = ('a' / 'b')+", {
     plugins: [phpeggy]
 });
 ```
@@ -88,7 +101,7 @@ Supported options of `peggy.generate`:
 You can also pass options specific to the PHPeggy plugin as follows:
 
 ```js
-var parser = peggy.generate("start = ('a' / 'b')+", {
+const parser = peggy.generate("start = ('a' / 'b')+", {
     plugins: [phpeggy],
     phpeggy: { /* phpeggy-specific options */ }
 });
@@ -99,17 +112,36 @@ Here are the options available to pass this way:
   * `parserNamespace` - namespace of generated parser (default: `PHPeggy`). If
     value is `''` or `null`, no namespace will be used.
   * `parserClassName` - name of generated class for parser (default: `Parser`).
-  * `mbstringAllowed` - whether to allow usage of PHP's `mb_*` functions which
-    depend on the `mbstring` extension being installed (default: `true`). This
-    can be disabled for compatibility with a wider range of PHP configurations,
-    but this will also disable several features of Peggy (case-insensitive
-    string matching, case-insensitive character classes, and empty character
-    classes). Attempting to use these features with `mbstringAllowed: false`
-    will cause `passes.check` to throw an error.
   * `header` - you can provide a custom header that will be added at the top of the parser, e.g. `/* My custom header */`.
 
-Using the Parser
-----------------
+#### Command Line
+
+To generate a parser from your grammar, use the peggy command:
+
+```bash
+npx peggy --plugin /path/to/phpeggy/src/phpeggy.js arithmetics.pegjs
+```
+
+The following options might be of interest in the context of PHPeggy:
+
+- `--allowed-start-rules <rules>`
+- `--cache`
+- `--extra-options <options>`
+- `-c, --extra-options-file <file>`
+- `-o, --output <file>`
+- `-S, --start-rule <rule>`
+
+`--format` is irrelevant as PHPeggy will only provide PHP source code.
+
+Here is a more complex example:
+
+```bash
+npx peggy -o arithmeticsParser.php --plugin /path/to/phpeggy/src/phpeggy.js arithmetics.pegjs --cache --extra-option '{ "phpeggy" : { "parserNamespace" : "MyNameSpace", "parserClassName" : "ArithmeticsParser", "header" : "/* My custom header */" } }'
+```
+
+A more detailed description of the different options can be found in the [peggy documentation](https://peggyjs.org/documentation.html#generating-a-parser-command-line).
+
+## Using the Parser
 
 1) Save parser generated by `peggy.generate` to a file
 
@@ -160,21 +192,21 @@ maintain compatibility with PCRE versions that are missing Unicode support
 array (one array element per UTF-8 character) and pass this array into
 `$parser->parse()` instead of the string input.
 
-Grammar Syntax and Semantics
-----------------------------
+## Grammar Syntax and Semantics
 
 See [documentation of Peggy](https://peggyjs.org/documentation.html) with following differences:
 
 * action and predicate blocks should be written in PHP.
 * the _per-parse initializer_ code block is used to provide additional methods, properties and constants to the Parser class. A special method `function initialize()` can be provided and resembles the Peggy per-parse initializer i.e. this method is called before the generated parser starts parsing (see [examples/fizzbuzz.pegjs](examples/fizzbuzz.pegjs)). All methods have access to the input (`$this->input`) and the options (`$this->options`).
 * the _global initializer_ code block can be used to add use statements, classes, functions, constants, ...
+* [Importing External Rules](https://peggyjs.org/documentation.html#importing-external-rules) works only from the Command Line.
 
 Original Peggy rule:
 
 ```js
 media_list = head:medium tail:("," S* medium)* {
-  var result = [head];
-  for (var i = 0; i < tail.length; i++) {
+  let result = [head];
+  for (let i = 0; i < tail.length; i++) {
     result.push(tail[i][2]);
   }
   return result;
@@ -206,8 +238,8 @@ media_list = head:medium tail:("," S* medium)* {
   return $result;
   ?> **/
 
-  var result = [head];
-  for (var i = 0; i < tail.length; i++) {
+  let result = [head];
+  for (let i = 0; i < tail.length; i++) {
     result.push(tail[i][2]);
   }
   return result;
@@ -221,8 +253,7 @@ You can also use the following utility functions in PHP action blocks:
 - `ord_unicode($code)` - return the UTF-8 code for a character (analogue of
   JavaScript's `String.prototype.charCodeAt(0)` function).
 
-Guide for converting Peggy action blocks to PHPeggy
----------------------------------------------------
+## Guide for converting Peggy action blocks to PHPeggy
 
 | Javascript code                   | PHP analogue                              |
 | --------------------------------- | ----------------------------------------- |