Merge pull request #53 from ShaderFrog/error-format

6.0.0 Breaking change: parser.parse() -> parse() with better error message

Author: AndrewRayCode

.gitignore

@@ -5,4 +5,4 @@ dist
 tmp
 src/parser/parser.js
 src/preprocessor/preprocessor-parser.js
-tsconfig.tsbuildinfo
+tsconfig.tsbuildinfo

README.md

@@ -39,18 +39,18 @@ npm install --save @shaderfrog/glsl-parser
 ## Parsing
 
 ```typescript
-import { parser, generate } from '@shaderfrog/glsl-parser';
+import { parse, generate } from '@shaderfrog/glsl-parser';
 
 // To parse a GLSL program's source code into an AST:
-const program = parser.parse('float a = 1.0;');
+const program = parse('float a = 1.0;');
 
 // To turn a parsed AST back into a source program
 const transpiled = generate(program);
 ```
 
 The parser accepts an optional second `options` argument:
 ```js
-parser.parse('float a = 1.0;', options);
+parse('float a = 1.0;', options);
 ```
 
 Where `options` is:
@@ -72,28 +72,26 @@ type ParserOptions = {
   // Hide warnings. If set to false or not set, then the parser logs warnings
   // like undefined functions and variables. If `failOnWarn` is set to true,
   // warnings will still cause the parser to raise an error. Defaults to false.
-  quiet: boolean;
-
-  // An optional string representing the origin of the GLSL, for debugging and
-  // error messages. For example, "main.js". If the parser raises an error, the
-  // grammarSource shows up in the error.source field. If you format the error
-  // (see the errors section), the grammarSource shows up in the formatted error
-  // string. Defaults to undefined.
-  grammarSource: string;
+  quiet?: boolean;
 
   // If true, sets location information on each AST node, in the form of
   // { column: number, line: number, offset: number }. Defaults to false.
-  includeLocation: boolean;
+  includeLocation?: boolean;
 
   // If true, causes the parser to raise an error instead of log a warning.
   // The parser does limited type checking, and things like undeclared variables
   // are treated as warnings. Defaults to false.
-  failOnWarn: boolean;
+  failOnWarn?: boolean;
+
+  // An optional string representing the file name of your GLSL For example,
+  // you can pass "main.glsl" here. If an error is raised, the error message
+  // will show "main.glsl:row:column". This is only used in the error message.
+  grammarSource?: string;
 }
 ```
 
 ## The program type
-`parser.parse()` returns a `Program`, which is a special AST Node:
+`parse()` returns a `Program`, which is a special AST Node:
 
 ```typescript
 interface Program {
@@ -194,27 +192,23 @@ See also [Utility-Functions](#Utility-Functions) for renaming scope references.
 
 ## Errors
 
-If you have invalid GLSL, the parser throws a `GlslSyntaxError`. The parser uses
-Peggy under the hood, so `GlslSyntaxError` is a convenience type alias for a
-`peggy.SyntaxError`.
+If you have invalid GLSL, the parser throws a `GlslSyntaxError`.
 
 ```ts
-import { parser, GlslSyntaxError } from '@shaderfrog/glsl-parser';
+import { parse, GlslSyntaxError } from '@shaderfrog/glsl-parser';
 
 let error: GlslSyntaxError | undefined;
 try {
   // Line without a semicolon
-  c.parse(`float a`);
+  parse(`float a`);
 } catch (e) {
   error = e as GlslSyntaxError;
 }
 ```
 
-If you want to check if a caught error is an `instanceof` a `GlslSyntaxError`,
-then you need to use the Peggy `SyntaxError` error object, which lives on the
-parser:
+If you want to check if a caught error is an `instanceof` a `GlslSyntaxError`:
 ```ts
-console.log(error instanceof parser.SyntaxError)
+console.log(error instanceof GlslSyntaxError)
 // true
 ```
 
@@ -224,7 +218,13 @@ should be safe to cast it to a `GlslSyntaxError` with `as` in Typescript.
 The error message string is automatically generated by Peggy:
 ```ts
 console.log(error.message)
-// 'Expected ",", ";", "=", or array specifier but end of input found'
+/*
+Error: Expected ",", ";", "=", or array specifier but "f" found.
+  --> undefined:2:1
+  |
+2 | float b
+  | ^
+*/
 ```
 
 The error object includes the location of the error. It is not printed in the
@@ -241,26 +241,10 @@ console.log(error.location)
 ```
 Note the `source` field on the error object is the `grammarSource` string
 provided to the parser options, which is `undefined` by default. If you pass in
-a `grammarSource` to `parser.parse()`, it shows up in the error object. This is
+a `grammarSource` to `parse()`, it shows up in the error object. This is
 meant to help you track which source file you're parsing, for example you could
-enter `"myfile.glsl"` as an argument to `parser.parse()` so that the error
+enter `"myfile.glsl"` as an argument to `parse()` so that the error
 includes that your source GLSL came from your application's `myfile.glsl` file.
-
-The error object  also has a fairly confusing `format()` method, which comes
-from the underlying Peggy error object. It produces an ASCII formatted string
-with arrows and underlines. The `source` option passed to `.format()` **must**
-match your `grammarSource` in parser options (which is `undefined` by default).
-This API is awkward and I might override it in future versions of the parser.
-
-```ts
-console.log(error.format([{ text, source: undefined }])
-/*
-Error: Expected ",", ";", "=", or array specifier but "f" found.
-  --> undefined:2:1
-  |
-2 | float b
-  | ^
-*/
 ```
 
 ## Preprocessing
@@ -311,14 +295,14 @@ import {
   preprocessAst,
   preprocessComments,
   generate,
-  parser,
+  parse,
 } from '@shaderfrog/glsl-parser/preprocessor';
 
 // Remove comments before preprocessing
 const commentsRemoved = preprocessComments(`float a = 1.0;`);
 
 // Parse the source text into an AST
-const ast = parser.parse(commentsRemoved);
+const ast = parse(commentsRemoved);
 
 // Then preprocess it, expanding #defines, evaluating #ifs, etc
 preprocessAst(ast);
@@ -328,6 +312,23 @@ preprocessAst(ast);
 const preprocessed = generate(ast);
 ```
 
+## Accessing the raw Peggy parser
+If you need to access the Peggy compiled parser directly, import the `parser`.
+You can manually call `parser.parse()` if you prefer. Note if there are errors,
+rather than returning a `GlslSyntaxError`, it will return the underlying
+`peg$syntaxError`.
+
+```typescript
+import { parser } from '@shaderfrog/glsl-parser';
+import { parser as preprocessorParser } from '@shaderfrog/glsl-parser/preprocessor';
+
+try {
+  const ast = parser.parse('float f = 1.0;');
+} catch (e) {
+  console.log(e instanceof parser.SyntaxError); // true
+}
+```
+
 ## Manipulating and Searching ASTs
 
 ### Visitors
@@ -409,12 +410,12 @@ follow the same convention outlined above.
 
 ```typescript
 import {
-  parser,
+  parse,
   visitPreprocessedAst,
 } from '@shaderfrog/glsl-parser/preprocessor';
 
 // Parse the source text into an AST
-const ast = parser.parse(`float a = 1.0;`);
+const ast = parse(`float a = 1.0;`);
 visitPreprocessedAst(ast, visitors);
 ```
 

build.sh

@@ -11,7 +11,6 @@ npx tsc
 npx peggy --cache --format es -o dist/parser/parser.js src/parser/glsl-grammar.pegjs
 # Manualy copy in the type definitions
 cp src/parser/parser.d.ts dist/parser/
-cp src/error.d.ts dist/
 
 npx peggy --cache --format es -o dist/preprocessor/preprocessor-parser.js src/preprocessor/preprocessor-grammar.pegjs
 cp src/preprocessor/preprocessor-parser.d.ts dist/preprocessor/preprocessor-parser.d.ts

jest.config.js

@@ -8,4 +8,6 @@ export default {
   transform: {
     '^.+\\.(t|j)sx?$': '@swc/jest',
   },
+  // In CI, it builds the test files into JS files, which we don't want to run
+  testMatch: ['**/*.test.ts'],
 };

package.json

@@ -3,7 +3,7 @@
   "engines": {
     "node": ">=16"
   },
-  "version": "5.5.1",
+  "version": "6.0.1",
   "type": "module",
   "description": "A GLSL ES 1.0 and 3.0 parser and preprocessor that can preserve whitespace and comments",
   "scripts": {
@@ -16,8 +16,8 @@
   "files": [
     "ast",
     "index.d.ts",
-    "error.d.ts",
     "index.js",
+    "error.js",
     "parser",
     "preprocessor"
   ],

postbuild.sh

@@ -1,4 +1,4 @@
 #!/bin/bash
 set -e
 
-rm -rf ast index.d.ts index.js parser preprocessor
+rm -rf ast index.d.ts error.js index.js parser preprocessor