# @atlassianlabs/jql-parser

> JQL lexer, parser, listener and visitor

Latest version **1.0.1** (published 2023-07-12) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @atlassianlabs/jql-parser
pnpm add @atlassianlabs/jql-parser
yarn add @atlassianlabs/jql-parser
bun add @atlassianlabs/jql-parser
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.1 |
| Published | 2023-07-12 |
| First published | 2021-12-10 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=6.0.0 |
| Dependencies | 2 |
| Unpacked size | 908.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Atlassian |
| Maintainers | doklovic, prkb, crumley, nrundquist, dkolbly-atlassian, kpainter-atl, soneymathew |
| Keywords | jql, antlr4, grammar, jira |

## Links

- npm: https://www.npmjs.com/package/@atlassianlabs/jql-parser
- Repository: https://bitbucket.org/atlassian/jql-grammar
- Homepage: https://bitbucket.org/atlassian/jql-grammar#readme
- Issues: https://bitbucket.org/atlassian/jql-grammar/issues
- npm.io page: https://npm.io/package/@atlassianlabs/jql-parser

## Dependencies (2)

- [antlr4ts](https://npm.io/package/antlr4ts.md) 0.5.0-alpha.4
- [@babel/runtime](https://npm.io/package/@babel/runtime.md) ^7.15.4

## Recent versions

- 1.0.1 (latest) — 2023-07-12
- 1.0.0 — 2022-02-21
- 0.0.1 — 2021-12-10

## README

# JQL Parser

[![Atlassian license](https://img.shields.io/badge/license-Apache%202.0-blue.svg?style=flat-square)](LICENSE)

This library contains auto-generated sources from the [antlr4ts](https://github.com/tunnelvisionlabs/antlr4ts) 
library using the JQL ANTLR4 grammar. It enables consumers to parse a JQL query into a parse tree.

## Usage

```typescript
import { CharStreams, CommonTokenStream } from 'antlr4ts';
import { JQLLexer, JQLParser } from '@atlassianlabs/jql-parser';

// Create the lexer and parser
const jqlText = "project = JQL";
const charStream = CharStreams.fromString(jqlText);
const lexer = new JQLLexer(charStream);
const tokenStream = new CommonTokenStream(lexer);
const parser = new JQLParser(tokenStream);

// Parse the input, where `jqlQuery` is the entry point
const parsedJQLTree = parser.jqlQuery();
```

## Installation

```sh
yarn add @atlassianlabs/jql-parser
```

## Documentation

### Inspecting the parse tree

A JQL parse tree can be inspected using the `JQLParserListener` or `JQLParserVisitor`, you can read 
about the differences between the visitor/listener approaches [here](https://github.com/antlr/antlr4/blob/master/doc/listeners.md).

#### Listener Approach

```typescript
import { JQLParserListener, JqlQueryContext } from '@atlassianlabs/jql-parser';
import { ParseTreeWalker } from 'antlr4ts/tree/ParseTreeWalker';


class EnterQueryListener implements JQLParserListener {
    enterJqlQuery: (context: JqlQueryContext) {
        console.log(`Query start line number ${context._start.line}`);
        // ...
    }

    // other enterX functions...
}

// Create the listener
const listener: JQLParserListener = new EnterQueryListener();
// Use the entry point for listeners on the parsed JQL tree
ParseTreeWalker.DEFAULT.walk(listener, parsedJQLTree);
```

#### Visitor Approach

```typescript
import { JQLParserVisitor, JqlOperandContext } from '@atlassianlabs/jql-parser';
import { AbstractParseTreeVisitor } from 'antlr4ts/tree/AbstractParseTreeVisitor';

// Extend the AbstractParseTreeVisitor to get default visitor behaviour
class CountOperandsVisitor extends AbstractParseTreeVisitor<number>
  implements JQLParserVisitor<number> {
  defaultResult() {
    return 0;
  }

  aggregateResult(aggregate: number, nextResult: number) {
    return aggregate + nextResult;
  }

  visitJqlOperand(context: JqlOperandContext): number {
    return 1 + super.visitChildren(context);
  }
}

// Create the visitor
const countOperandsVisitor = new CountOperandsVisitor()
// Use the visitor entry point with the parsed JQL tree
const numberOfOperands = countOperandsVisitor.visit(parsedJQLTree);
```

## Support

For developers outside of Atlassian looking for help, or to report issues, [please make a post on the community forum](https://community.developer.atlassian.com/c/atlassian-ecosystem-design).
We will monitor the forums and redirect topics to the appropriate maintainers.

## License
Copyright (c) 2021 - 2022 Atlassian and others. Apache 2.0 licensed, see [LICENSE](LICENSE) file.

---
_Source: https://npm.io/package/@atlassianlabs/jql-parser · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
