Breaking changes: node 14+ and reserved words

3.0.0

Released: 2023-02-21

Major Changes

• #280 Add inline examples to the documentation, from @hildjj
• #240 Generate SourceNodes for bytecode, from @hildjj
• #338 BREAKING CHANGE. Update dependencies, causing minimum supported version of node.js to move to 14. Generated grammar source should still work on older node versions and some older browsers, but testing is currently manual for those. from @hildjj
• #291: Add support for repetition operator expression|min .. max, delimiter|, from @Mingun
• #339: BREAKING CHANGE. Updated the list of JavaScript reserved words. This will break existing grammars that use any of the new words in their rule or label names. from @hildjj

Important information for plug-in authors: PR [#291] added 4 new opcodes to the bytecode:

• IF_LT
• IF_GE
• IF_LT_DYNAMIC
• IF_GE_DYNAMIC

and added a new AST node and a visitor method repeated. Do not forget to update your plug-ins.

Important information for grammar authors: the following words, which used to be valid identifiers for rules and labels, are now treated as JavaScript reserved words, and will cause errors at compile time if you are using them:

• abstract
• arguments
• as
• async
• boolean
• byte
• char
• double
• eval
• final
• float
• from
• get
• goto
• int
• long
• native
• of
• set
• short
• synchronized
• throws
• transient
• volatile

Minor Changes

• #274 "*" is now a valid allowedStartRule, which means all rules are allowed, from @hildjj
• #229 new CLI option -S <rule> or --start-rule <rule> to specify the start rule when testing, from @hildjj
• #236 Website: show line numbers in parser input textarea, from @Mingun
• #280 new output type source-with-inline-map, which generates source text with an inline map, from @hildjj
• #285 Require that a non-empty string be given as a grammarSource if you are generating a source map, from @hildjj
• #206: New output type ast and an --ast flag for the CLI to get an internal grammar AST for investigation (can be useful for plugin writers), from @Mingun
• #294 Website: show errors in the editors, from @Mingun
• #297 Website: add Discord widget, from @hildjj
• #299 Add example grammar for a SemVer.org semantic version string, from @dselman
• [#307] Allow grammars to have relative offsets into their source files (e.g. if embedded in another doc), from @hildjj.
• #308 Add support for reading test data from stdin using -T -, from @hildjj.
• #313 Create the website using eleventy, from @camcherry

Bug Fixes

• #283 Fix incorrect type information for DiagnosticCallback, from @hildjj
• #287 Allow large outputs to be received without blocking on the CLI tests, from @hildjj

Restore CDN functionality

Released: 2022-01-01

Major Changes

• None

Minor Changes

• #261: Remove documentation from
  README.md, instead linking to the HTML documentation. HTML documentation on
  https://peggyjs.org is now served from the docs branch, so that it won't
  update as we change the main branch. main must be merged onto docs as
  a part of the release process going forward.
• #266: Expose the private
  field problems in the Session class, from @hildjj.

Bug Fixes

• #263: Broken link to unpkg.
  This bug was a symptom of a relatively bad issue in the 2.0.0 release, where
  the web version of peggy was put in the wrong place, and therefore not
  tested in the release process. From @hildjj.

Source map support

Major Changes

• #163: Add support for
  generating source maps, from @Mingun
• #160: Introduce an API for
  reporting errors, warnings and information messages from passes. New API
  allows reporting several diagnostics at once with intermediate results
  checking after each compilation stage, from @Mingun
• #218: Add a sourceMappingURL
  to the generated code, from @hildjj
• #248: Remove support for
  Node.js version 10. When updating dependencies, too many of the tools we
  use no longer work on the Node 10, which went out of security maintenance
  more than a year ago. Added support for Node.js version 18, from @hildjj
• #251: Make commander and
  source-map-generator full dependencies. These are not needed for the
  pre-packaged web build, but will be used by Node or people that are doing
  their own packaging for the web, from @hildjj

Minor Changes

• #167: New CLI, from @hildjj
  • Backward compatible with the previous
  • New -t/--test and -T/--testfile flags to directly test the generated grammar
• #169: Expose string escape
  functions, stringEscape() and regexpClassEscape(), from @hildjj
• #175: Check allowedStartRules
  for validity, from @hildjj
• #185: Updated eslint rules,
  from @hildjj
• #196: Add example grammars for
  XML and source-mapping, from @hildjj
• #204: Increase coverage for the
  tests, from @Mingun
• #210: Refactor CLI testing,
  from @hildjj

Bug fixes

• #164: Fix some errors in the
  typescript definitions, from @Mingun
• #170: Add
  missing argument in function call, from @darlanalves
• #182: Fix typo in
  documentation, from @zargold
• #197: Fix a regression of
  redundant commas in the character classes in the error messages, introduced
  in fad4ab7, from @Mingun
• #198: Make all build scripts
  run on Windows, from @hildjj
• #199: Test web version locally,
  using puppeteer, from @hildjj
• #211:Command-line -t requires
  from wrong directory, from @hildjj
• #212: Parse errors with zero
  length give badly-formatted errors, from @hildjj
• #214: Failing tests don't
  format errors
• #216: Fix typescript
  definition of SyntaxError, from @cmfcmf
• #220: Fix rollup warnings,
  from @hildjj

Minor features and optimizations

Minor Changes

• Infrastructural rebake @StoneCypher

  • Builds with typescript, removes babel
  • Bundles with rollup, removes browserify
  • Tests with jest, removes mocha
  • Minifies with terser, removes uglify
  • Adds rimraf for portable pre-build cleanup
  • Extends CI testing to windows, macintosh
  • Increases node testing range to include node 16

• Option to select optimization mode removed as it had no significant effect on the
  majority of generated parsers and as such represented only academic interest. You should
  use minifiers to get smaller parsers. Option optimize is deleted from the generate()
  options, flag --optimize is deleted from the CLI (you still can supply it, but the CLI
  will issue a warning that the option is removed).
  @Mingun

• location()s now will have additional source property which value is taken
  from the options.grammarSource property. That property can contain arbitrary
  data, for example, path to the currently parsed file.
  @Mingun

• Made usage of GrammarError and peg$SyntaxError more consistent. Use the
  format method to get pretty string outputs. Updated the peggy binary to
  make pretty errors. Slight breaking change: the format of a few error
  messages have changed; use the toString() method on GrammarError to get
  something close to the old text.
  @hildjj

• The code generator was slightly reworked to simplify reusing the bytecode generator
  (generate.generateBytecode pass). Property consts on the grammar AST node,
  has been creating by the pass in the past, was decoupled into 4 other properties
  with the structured information:

  • literals
  • classes
  • expectations
  • functions

• Added missing type definitions to the peg.d.ts file. Added definitions for the
  compiler and visitor modules, AST, and plugins option in the generate() function.
  @Mingun

  Now bytecode generation pass is independent from the JavaScript backend.
  @Mingun

• Some opcodes from compiler/opcode.js were deprecated. Although you shouldn't use
  them directly because they are not considered as a public API, some plugins use them.
  For that reason backward compatibility is preserved:

  • Opcode MATCH_REGEXP is deprecated and replaced by MATCH_CHAR_CLASS with the same value.
  • Added new opcode PUSH_EMPTY_STRING that puts a new empty string on the stack.
  • Opcode PUSH is deprecated because it was used only for pushing empty string constants
    and they now pushed with PUSH_EMPTY_STRING.

  Instead of relying on the library opcodes it is better to have a copy of
  them, especially if your plugin replaces both the generateBytecode and
  the generateJs passes. @Mingun

• Default visitor functions, returned by the visitor.build(), that just forward
  call to node.expression, now return the result of underlying visit call.
  @Mingun

  Affected functions:

  • rule
  • named
  • action
  • labeled
  • text
  • simple_and
  • simple_not
  • optional
  • zero_or_more
  • one_or_more
  • group

• Parsers now can use two new functions to get location information:
  offset() and range(). Use them if you don't need the whole
  location information, because it is expensive to compute.
  These two new functions are always very efficient (back-ported pegjs/pegjs#528).
  @felix9 and @Mingun

• Add a new option config.reservedWords: string[], avalible for plugins in their
  use() method. Using this option, a plugin can change the list of words that
  cannot be used.

  By default this new option contains an array with reserved JavaScript words
  @Mingun

• Several optimizations in the generator. Generated parsers should now be faster and smaller
  @Mingun

Bug fixes

• #112: "group" node in the AST now have location information (back-ported)
• #143: peg.d.ts had some errors in the type descriptions, which were fixed

Global Initializers, @plucking

Major Changes

• Added global initializer blocks, which contain code that is only run once
  when the grammar is loaded, rather than once every time the parser runs.
  Global initializers are surrounded by {{ and }}, and must come before
  the per-parser initializer, which is surrounded by { and }.
  @jaubourg
• Back-ported value plucking with @ from pegjs head. If your rule has a simple action that returns one or more of the values matched by the rule, you can instead mark those expressions with @ and not need an action. This works inside of parens as well. @hildjj

Bug fixes

• #10: Better docs for parser options
• #40: Turn on eslint prefer-const
• #58: Release script didn't push tag correctly
• #61: Replace download link with new one in doc (partial fix)
• #71: Readme doesn't include "es" format
• #72: Generated code has wrong version number

First release

Ported over PEG.js from the last-known-good point. Without changing anything substantive, got everything to work in a mostly-current environment.