Merge remote-tracking branch 'origin/main' into aeschli/3.3.0

CHANGELOG.md

@@ -1,3 +1,7 @@
+3.3.0 2022-06-24
+=================
+- `JSONVisitor.onObjectBegin` and `JSONVisitor.onArrayBegin` can now return `false` to instruct the visitor that no children should be visited.
+
 
 3.2.0 2022-08-30
 =================

README.md

@@ -12,7 +12,7 @@ JSONC is JSON with JavaScript style comments. This node module provides a scanne
  - the *scanner* tokenizes the input string into tokens and token offsets
  - the *visit* function implements a 'SAX' style parser with callbacks for the encountered properties and values.
  - the *parseTree* function computes a hierarchical DOM with offsets representing the encountered properties and values.
- - the *parse* function evaluates the JavaScript object represented by JSON string in a fault tolerant fashion. 
+ - the *parse* function evaluates the JavaScript object represented by JSON string in a fault tolerant fashion.
  - the *getLocation* API returns a location object that describes the property or value located at a given offset in a JSON document.
  - the *findNodeAtLocation* API finds the node at a given location path in a JSON DOM.
  - the *format* API computes edits to format a JSON document.
@@ -37,7 +37,7 @@ API
  * If ignoreTrivia is set, whitespaces or comments are ignored.
  */
 export function createScanner(text: string, ignoreTrivia: boolean = false): JSONScanner;
-    
+
 /**
  * The scanner object, representing a JSON scanner at a position in the input string.
  */
@@ -106,20 +106,21 @@ export declare function visit(text: string, visitor: JSONVisitor, options?: Pars
 
 /**
  * Visitor called by {@linkcode visit} when parsing JSON.
- * 
+ *
  * The visitor functions have the following common parameters:
  * - `offset`: Global offset within the JSON document, starting at 0
  * - `startLine`: Line number, starting at 0
  * - `startCharacter`: Start character (column) within the current line, starting at 0
- * 
+ *
  * Additionally some functions have a `pathSupplier` parameter which can be used to obtain the
  * current `JSONPath` within the document.
  */
 export interface JSONVisitor {
     /**
      * Invoked when an open brace is encountered and an object is started. The offset and length represent the location of the open brace.
+     * When `false` is returned, the array items will not be visited.
      */
-    onObjectBegin?: (offset: number, length: number, startLine: number, startCharacter: number, pathSupplier: () => JSONPath) => void;
+    onObjectBegin?: (offset: number, length: number, startLine: number, startCharacter: number, pathSupplier: () => JSONPath) => void | boolean;
 
     /**
      * Invoked when a property is encountered. The offset and length represent the location of the property name.
@@ -133,8 +134,9 @@ export interface JSONVisitor {
     onObjectEnd?: (offset: number, length: number, startLine: number, startCharacter: number) => void;
     /**
      * Invoked when an open bracket is encountered. The offset and length represent the location of the open bracket.
+     * When `false` is returned, the array items will not be visited.*
      */
-    onArrayBegin?: (offset: number, length: number, startLine: number, startCharacter: number, pathSupplier: () => JSONPath) => void;
+    onArrayBegin?: (offset: number, length: number, startLine: number, startCharacter: number, pathSupplier: () => JSONPath) => void | boolean;
     /**
      * Invoked when a closing bracket is encountered. The offset and length represent the location of the closing bracket.
      */
@@ -233,14 +235,14 @@ export function findNodeAtOffset(root: Node, offset: number, includeRightBound?:
 export function getNodePath(node: Node): JSONPath;
 
 /**
- * Evaluates the JavaScript object of the given JSON DOM node 
+ * Evaluates the JavaScript object of the given JSON DOM node
  */
 export function getNodeValue(node: Node): any;
 
 /**
  * Computes the edit operations needed to format a JSON document.
- * 
- * @param documentText The input text 
+ *
+ * @param documentText The input text
  * @param range The range to format or `undefined` to format the full content
  * @param options The formatting options
  * @returns The edit operations describing the formatting changes to the original document following the format described in {@linkcode EditResult}.
@@ -250,10 +252,10 @@ export function format(documentText: string, range: Range, options: FormattingOp
 
 /**
  * Computes the edit operations needed to modify a value in the JSON document.
- * 
- * @param documentText The input text 
+ *
+ * @param documentText The input text
  * @param path The path of the value to change. The path represents either to the document root, a property or an array item.
- * If the path points to an non-existing property or item, it will be created. 
+ * If the path points to an non-existing property or item, it will be created.
  * @param value The new value for the specified property or item. If the value is undefined,
  * the property or item will be removed.
  * @param options Options
@@ -264,7 +266,7 @@ export function modify(text: string, path: JSONPath, value: any, options: Modifi
 
 /**
  * Applies edits to an input string.
- * @param text The input text 
+ * @param text The input text
  * @param edits Edit operations following the format described in {@linkcode EditResult}.
  * @returns The text with the applied edits.
  * @throws An error if the edit operations are not well-formed as described in {@linkcode EditResult}.
@@ -306,7 +308,7 @@ export interface Edit {
 */
 export interface Range {
     /**
-     * The start offset of the range. 
+     * The start offset of the range.
      */
     offset: number;
     /**
@@ -315,7 +317,7 @@ export interface Range {
     length: number;
 }
 
-/** 
+/**
  * Options used by {@linkcode format} when computing the formatting edit operations
  */
 export interface FormattingOptions {
@@ -333,7 +335,7 @@ export interface FormattingOptions {
     eol: string;
 }
 
-/** 
+/**
  * Options used by {@linkcode modify} when computing the modification edit operations
  */
 export interface ModificationOptions {