Antlr-odata NPM

antlr-odata

This project provides an antlr generated lexer and parser for OData Queries.

Note this project depends on antlr4ts ^0.5.0-alpha.3 - use in production code at your own risk.

Dependencies

antlr4ts (Alpha).

Usage (ts)

The main useful classes exported by this library are ODataLiteLexer and ODataLiteParser. Here's how you can use these...

import { CharStreams, CodePointCharStream, CommonTokenStream } from 'antlr4ts';
import { ParseTree, ParseTreeWalker } from 'antlr4ts/tree';

const odataQuery = 'MyEntity?$select=Property1&$expand=NavProperty1($select=Property2;$expand=NavProperty2)$filter=Property1 eq @MyAlias&@MyAlias=1';

const codePointCharStream: CodePointCharStream = CharStreams.fromString(odataQuery);
const lexer = new OData4LiteLexer(codePointCharStream);
const tokens: CommonTokenStream = new CommonTokenStream(lexer);

// Alternative 1: Context unaware parser - fine if you a) don't have metadata, or do not support unbound functions.
const parser: OData4LiteParser = new OData4LiteParser(tokens);

// Alternative 2 (from version 0.0.12): Context aware parser
// A metadata sybmbol table has been provided with an api for querying EntitySet, EntityType and UnboundFunction symbols.
// The user can select a desired Schema and provide it to the parser, which can then distinguish between urls /EntitySet(1) and /UnBoundFunction(1) by querying the symbol table.

const metaDataSymbol: MetadataSymbols = new MetadataSymbols(xml);
const schema: Schema = metaDataSymbol.defaultSchema;
const parser: OData4LiteParser = OData4LiteParser.buildOData4LiteParser(tokens, schema);

const tree: ParseTree = parser.odataRelativeURI();
// Now we have a parse tree we can use like this...

// Whats a list of all the aliases in the query string?
const walker: ParseTreeWalker = new ParseTreeWalker();
const aliasResolver: ODataAliasResolver = new ODataAliasResolver();

aliasResolver.forEach(alias => console.log(`${alias} `)); 
// output: MyAlias

export class ODataAliasResolver implements OData4LiteListener {
    aliases: string[] = [];

    constructor() {}

    enterParameterAlias: (ctx: ParameterAliasContext) => void = ctx => {
        if (ctx.parent instanceof AliasAndValueContext) {
            return;
        }
        this.aliases.push(ctx.IDENTIFIER().text);
    }
}

Lite Grammar

The Lite grammar can match the following OData Query features:

EntitySet Queries - $expand, $select, $top, $filter, $count, $apply + groupby + aggregate
Unbound Functions
Aliases

Full Grammar

This library currently doesn't support the full odata 4.0 grammar. An full Antlr OData grammar has been defined here:

https://tools.oasis-open.org/version-control/browse/wsvn/odata/trunk/4.01%20spec/grammar/ANTLR/ODataLexer.g4

...has been copied to this project purely for my reference. In its current state it will not build with antlr4ts.

Releases

Version 0.0.18

Changes

Bumped devdep Typescript to 4
added // @ts-nocheck to generated ts code to workaround https://github.com/tunnelvisionlabs/antlr4ts/issues/485

Version 0.0.17

Fixes

added expression support to $orderby
added reference material - abnf v4.01.

Version 0.0.16

Fixes

Version 0.0.15 used a stale distribution in error

Version 0.0.15

Fixes

Definition of literal collections fixed to use [] not () and to support empty collections

Version 0.0.14

Breaking Changes

Definition of First Member Expressions updated to include single navigation properties. IDENTIFIER removed from firstMemberExpr

Version 0.0.13

Type now throws an error if no rawType is provided.
added github repo details

Version 0.0.12

fixed precendence of firstMemberExpression Context so IDENTIFIER is matched if its only a simple property

Version 0.0.11

Features:

support for any/all lambda functions
initial support for $it, $ref

Breaking Changes

- null token incorrectly defined as 'ull' - fixed definition of Alias's and collection literals - renamed collectionNavigationExpr to collectionNavigation to enable inclusion of actual collectionNavigationExpr rule (see abnf grammar for differences). - replaced simple ID Expression rule with more complete FirstMemberExpr rule which includes collection navigation.

Version 0.0.10

do not use

Version 0.0.9

New features

support collection navigations: Entity(x)

Breaking change

functionImportCall no longer included IDENTIFIER - instead its available in the parent context 'resourcePath'

Version 0.0.8

New features

$apply=compute()

Breaking change

renamed aggregateAs rule to dynamicPropertyAssignment

Version 0.0.7

New features

Add support for $orderby desc and asc
Added support for $apply filter transformation

Version 0.0.6

New features

Add support for $orderby
Fixed IDENTIFIER definition to allow digits

Version 0.0.5

New features

Add support for $skip

Version 0.0.4

New features

Fixed FunctionExpression should start with an Identifier

Version 0.0.3

New features

Added partial support for $apply. Supported operations include: groupby & aggregate
Added support for 'in' expressions. E.g. PropertyName in (1,2,3)

Breaking Changes:

replaced expression rule for IDENTIFIER with propertyPath (which effectively includes IDENTIFIER).
renamed rule navigationProperty to property (non-normative). property replaced several rules including the abnf rule called navigationProperty.
renamed collectionNavigation to collectionNavigationExpr in line with abnf grammar

Breaking changes

Version 0.0.2

Added support for Unbound Function Import with primitiveLiterals and alias's as parameters
Removed support (temporary) for collectionNavigation in a resource path due to ambiguity.