apex-parser

Parser for Salesforce Apex (including Triggers & inline SOQL/SOQL). This is based on an ANTLR4 grammar, see antlr/BaseApexParser.g4. Currently packaged for Java and JavaScript/TypeScript targets.

The packages include ANTLR4 generated types plus optional extras for convenience. The TypeScript package exports type aliases for ANTLR types, while both packages have abstractions like ApexParserFactory and ApexErrorListener. There are minimal examples below and in the test classes.

Installation

$3

``xml

io.github.apex-dev-tools
apex-parser


`

$3

`sh


Optionally install antlr4 to use runtime types


npm i @apexdevtools/apex-parser
`

Usage

ApexParser entry points to access tree:

- compilationUnit(), a class file.
- triggerUnit(), a trigger file.
- anonymousUnit(), an apex script file.
- query(), a raw SOQL query.

$3

`typescript
import { ApexParserFactory, ApexParserBaseVisitor } from "@apexdevtools/apex-parser";

const parser = ApexParserFactory.createParser("public class Hello {}");

/*
* Use a visitor. Return value and manual control.
*/
class Visitor extends ApexParserBaseVisitor {}

const visitor = new Visitor();
visitor.visit(parser.compilationUnit());


/*
* Or walk with listener. Enter/exit operations - for whole tree.
*/
class Listener extends ApexParserBaseListener {}

const listener = new Listener();
ApexParseTreeWalker.DEFAULT.walk(listener, parser.compilationUnit());
`

$3

SOSL FIND uses ' as a quoting character when embedded in Apex, in the API braces are used:

`sosl
Find {something} RETURNING Account
`

To parse the API format there is an alternative parser rule, soslLiteralAlt, that you can use instead of soslLiteral. See SOSLParserTest for some examples of how these differ.

Development

$3

- JDK 11+ (for ANTLR tool)
- Maven
- NodeJS LTS

$3

The outer package contains scripts to build both distributions:

`shell


Run once - prepare for dev (installs deps, runs antlr gen)

npm run init

Run antlr gen, compile and test

npm run build
`

Or you can setup and later build each distribution separately:

`shell
npm run init:npm
npm run build:npm

npm run init:jvm
npm run build:jvm
`

$3

#### Unit Tests

More options for testing:

`shell


From ./npm

npm run build
npm test

File and test name regex filtering

npm test -- ApexParserTest -t Expression

From ./jvm

mvn test
`

#### System Tests

The system tests use a collection of sample projects located in the apex-samples repository. Follow the README instructions in apex-samples to checkout the submodules at the version tag used by the build workflow. Both packages must be built beforehand, as the js system test spawns the jar as well.

To run the tests:

`shell


Set SAMPLES env var to samples repo location

export SAMPLES=

From root dir

npm run build
npm run systest
`

System test failures relating to the snapshots may highlight regressions. Though if an error is expected or the samples have changed, instead use npm run systest:update` to update the snapshots, then commit the changes.

Source & Licenses

All the source code included uses a 3-clause BSD license. The only third-party component included is the Apex Antlr4 grammar originally from Tooling-force.com, although this version used is now markedly different from the original.