Merge pull request #30 from ShaderFrog/rename-beta

5.0.0: Rename utility functions breaking API change

README.md

@@ -61,15 +61,18 @@ type ParserOptions = {
  // 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;
+
  // If true, sets location information on each AST node, in the form of
  // { column: number, line: number, offset: number }. Defaults to false.
  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.
@@ -427,19 +430,86 @@ visitors.
 
 ### Utility Functions
 
-Rename all the variables in a program:
+#### Rename variables / identifiers in a program
+
+You can rename bindings (aka variables), functions, and types (aka structs) with `renameBindings`, `renameFunctions`, and `renameTypes` respectively.
+
+The signature for these methods:
+
+```ts
+const renameBindings = (
+ // The scope to rename the bindings in. ast.scopes[0] is the global scope.
+ // Passing this ast.scopes[0] renames all global variables
+ bindings: ScopeIndex,
+
+ // The rename function. This is called once per scope entry with the original
+ // name in the scope, to generate the renamed variable. 
+ mangle: (name: string) => string
+): ScopeIndex
+```
+
+These scope renaming functions, `renameBindings`, `renameFunctions`, and `renameTypes`, do two things:
+1. Each function *mutates* the AST to rename identifiers in place.
+2. They *return* an *immutable* new ScopeIndex where the scope references
+ themselves are renamed.
+
+If you want your ast.scopes array to stay in sync with your AST, you need to
+re-assign it to the output of the functions! Examples:
 
 ```typescript
 import { renameBindings, renameFunctions, renameTypes } from '@shaderfrog/glsl-parser/utils';
 
-// ... parse an ast...
+// Suffix top level variables with _x, and update the scope
+ast.scopes[0].bindings = renameBindings(ast.scopes[0].bindings, (name) => `${name}_x`);
 
-// Suffix top level variables with _x
-renameBindings(ast.scopes[0], (name, node) => `${name}_x`);
 // Suffix function names with _x
-renameFunctions(ast.scopes[0], (name, node) => `${name}_x`);
+ast.scopes[0].functions = renameFunctions(ast.scopes[0].functions, (name) => `${name}_x`);
+
 // Suffix struct names and usages (including constructors) with _x
-renameTypes(ast.scopes[0], (name, node) => `${name}_x`);
+ast.scopes[0].types = renameTypes(ast.scopes[0].types, (name) => `${name}_x`);
+```
+
+There are also functions to rename only one variable/identifier in a given
+scope. Use these if you know specifically which variable you want to rename.
+
+```typescript
+import { renameBinding, renameFunction, renameType } from '@shaderfrog/glsl-parser/utils';
+
+// Replace all instances of "oldVar" with "newVar" in the global scope, and
+// creates a new global scope entry named "newVar"
+ast.scopes[0].bindings.newVar = renameBinding(
+ ast.scopes[0].bindings.oldVar,
+ 'newVar',
+);
+// You need to manually delete the old scope entry if you want the scope to stay
+// in sync with your program AST
+delete ast.scopes[0].bindings.oldVar;
+
+// Rename a specific function
+ast.scopes[0].functions.newFn = renameFunction(
+ ast.scopes[0].functions.oldFn,
+ 'newFn',
+);
+delete ast.scopes[0].functions.oldFn;
+
+// Rename a specific type/struct
+ast.scopes[0].functions.newType = renametype(
+ ast.scopes[0].functions.oldType,
+ 'newType',
+);
+delete ast.scopes[0].functions.oldType;
+```
+
+#### Debugging utility functions
+
+The parser also exports a debugging function, useful for logging information
+about the AST.
+
+```ts
+import { debugScopes } from '@shaderfrog/glsl-parser/parser/utils';
+
+// Print a condensed representation of the AST scopes to the console
+debugScopes(ast);
 ```
 
 ## What are "parsing" and "preprocessing"?

package.json

@@ -3,7 +3,7 @@
  "engines": {
  "node": ">=16"
  },
- "version": "4.1.1",
+ "version": "5.0.0",
  "type": "module",
  "description": "A GLSL ES 1.0 and 3.0 parser and preprocessor that can preserve whitespace and comments",
  "scripts": {
@@ -49,6 +49,6 @@
  "prettier": "^2.1.2",
  "ts-jest": "^29.1.2",
  "ts-jest-resolver": "^2.0.1",
- "typescript": "^5.3.3"
+ "typescript": "^5.5.3"
  }
 }

src/parser/scope.test.ts

@@ -176,7 +176,10 @@ float fn() {
 `);
 
  expect(ast.scopes[0].functions.noise);
- renameFunctions(ast.scopes[0], (name) => `${name}_FUNCTION`);
+ ast.scopes[0].functions = renameFunctions(
+ ast.scopes[0].functions,
+ (name) => `${name}_FUNCTION`
+ );
  expect(generate(ast)).toBe(`
 float noise_FUNCTION() {}
 float fn_FUNCTION() {
@@ -233,8 +236,14 @@ vec4 linearToOutputTexel( vec4 value ) { return LinearToLinear( value ); }
  { quiet: true }
  );
 
- renameBindings(ast.scopes[0], (name) => `${name}_VARIABLE`);
- renameFunctions(ast.scopes[0], (name) => `${name}_FUNCTION`);
+ ast.scopes[0].bindings = renameBindings(
+ ast.scopes[0].bindings,
+ (name) => `${name}_VARIABLE`
+ );
+ ast.scopes[0].functions = renameFunctions(
+ ast.scopes[0].functions,
+ (name) => `${name}_FUNCTION`
+ );
 
  expect(generate(ast)).toBe(`
 float selfref_VARIABLE, b_VARIABLE = 1.0, c_VARIABLE = selfref_VARIABLE;
@@ -306,7 +315,8 @@ StructName main(in StructName x, StructName[3] y) {
  float a2 = 1.0 + StructName(1.0).color.x;
 }
 `);
- renameTypes(ast.scopes[0], (name) => `${name}_x`);
+ ast.scopes[0].types = renameTypes(ast.scopes[0].types, (name) => `${name}_x`);
+
  expect(generate(ast)).toBe(`
 struct StructName_x {
  vec3 color;
@@ -342,10 +352,10 @@ StructName_x main(in StructName_x x, StructName_x[3] y) {
  ]);
  expect(Object.keys(ast.scopes[0].bindings)).toEqual(['reflectedLight']);
  expect(Object.keys(ast.scopes[0].types)).toEqual([
- 'StructName',
- 'OtherStruct',
+ 'StructName_x',
+ 'OtherStruct_x',
  ]);
- expect(ast.scopes[0].types.StructName.references).toHaveLength(16);
+ expect(ast.scopes[0].types.StructName_x.references).toHaveLength(16);
 
  // Inner struct definition should be found in inner fn scope
  expect(Object.keys(ast.scopes[2].types)).toEqual(['StructName']);
@@ -357,7 +367,7 @@ attribute vec3 position;
 vec3 func(vec3 position) {
  return position;
 }`);
- renameBindings(ast.scopes[0], (name) =>
+ ast.scopes[0].bindings = renameBindings(ast.scopes[0].bindings, (name) =>
  name === 'position' ? 'renamed' : name
  );
  // The func arg "position" shadows the global binding, it should be untouched
@@ -378,7 +388,10 @@ uniform vec2 vProp;
 };`);
 
  // This shouldn't crash - see the comment block in renameBindings()
- renameBindings(ast.scopes[0], (name) => `${name}_x`);
+ ast.scopes[0].bindings = renameBindings(
+ ast.scopes[0].bindings,
+ (name) => `${name}_x`
+ );
  expect(generate(ast)).toBe(`
 layout(std140,column_major) uniform;
 float a_x;

src/parser/scope.ts

@@ -118,7 +118,6 @@ export const functionDeclarationSignature = (
  const quantifiers = specifier.quantifier || [];
 
  const parameterTypes = proto?.parameters?.map(({ specifier, quantifier }) => {
- // todo: saving place on putting quantifiers here
  const quantifiers =
  // vec4[1][2] param
  specifier.quantifier ||

src/parser/test-helpers.ts

@@ -67,37 +67,6 @@ export const buildParser = () => {
 // }
 // };
 
-export const debugEntry = (bindings: ScopeIndex) => {
- return Object.entries(bindings).map(
- ([k, v]) =>
- `${k}: (${v.references.length} references, ${
- v.declaration ? '' : 'un'
- }declared): ${v.references.map((r) => r.type).join(', ')}`
- );
-};
-export const debugFunctionEntry = (bindings: FunctionScopeIndex) =>
- Object.entries(bindings).flatMap(([name, overloads]) =>
- Object.entries(overloads).map(
- ([signature, overload]) =>
- `${name} (${signature}): (${overload.references.length} references, ${
- overload.declaration ? '' : 'un'
- }declared): ${overload.references.map((r) => r.type).join(', ')}`
- )
- );
-
-export const debugScopes = (astOrScopes: Program | Scope[]) =>
- console.log(
- 'Scopes:',
- 'scopes' in astOrScopes
- ? astOrScopes.scopes
- : astOrScopes.map((s) => ({
- name: s.name,
- types: debugEntry(s.types),
- bindings: debugEntry(s.bindings),
- functions: debugFunctionEntry(s.functions),
- }))
- );
-
 const middle = /\/\* start \*\/((.|[\r\n])+)(\/\* end \*\/)?/m;
 
 type ParseSrc = (src: string, options?: ParserOptions) => Program;