@gooddata/maql-antlr4ts 0.2.1-001666cb.0

package/README.md

@@ -0,0 +1,97 @@
+# MAQL ANTLR4TS npm package
+
+The module bundles TypeScript MAQL lexer and parser generated from MAQL grammar,
+a visitor to create MAQL AST, and an abstract AST visitor to work with MAQL AST.
+
+The package antlr4ts is required on use, but is not bundled along with this package
+and must be provided externally.
+
+Example usage:
+
+```typescript
+import { CommonTokenStream } from "antlr4ts";
+
+import {
+    CaseInsensitiveCharStream,
+    MaqlLexer,
+    MaqlParser,
+    MaqlAstVisitor,
+    AstNormalizer,
+} from "@gooddata/maql-antlr4ts";
+
+const maql = "parse metric SELECT SUM(0.81 * {fact/price} * {fact/quantity}) BY {attribute/country} WITHOUT PF";
+const charStream = new CaseInsensitiveCharStream(maql);
+const lexer = new MaqlLexer(charStream);
+const tokenStream = new CommonTokenStream(lexer);
+const parser = new MaqlParser(tokenStream);
+const parseTree = parser.maql();
+const astVisitor = new MaqlAstVisitor(workspace);
+const ast = astVisitor.visit(parseTree);
+const normalizer = new AstNormalizer();
+const normalizedAst = normalizer.visit(ast);
+```
+
+## Local development
+
+> Requirements: [`yarn`](https://yarnpkg.com)
+
+| command          | effect                                                            |
+|------------------|-------------------------------------------------------------------|
+| `yarn install`   | install all dependencies                                          |
+| `yarn build`     | generate source files, compile files, bundle files into a package |
+| `yarn antlr4ts`  | generate source files from MAQL grammar                           |
+| `yarn funcdef`   | generate source files from MAQL function definitions              |
+| `yarn compile`   | compile TypeScript                                                |
+| `yarn rollup -c` | bundle files into a package                                       |
+| `yarn test`      | run ESLint, Prettier, and all tests                               |
+| `yarn test-ci`   | run `yarn test` with CI options and junit.xml output file         |
+| `yarn fix`       | automatically fix ESLint and Prettier errors                      |
+
+## Linking the package to other modules
+
+First build and bundle the module.
+
+`yarn build`
+
+> Warning: Do not use `yarn link` or `npm link`.
+>
+> Currently, there exists an issue which causes a runtime error when symbolically linking
+> this package using `yarn` or `npm`. The error seems to involve the `antlr4ts` library,
+> because it results in every single token having index of -1.
+
+Use [yalc](https://github.com/wclr/yalc) to link the package to other repositories.
+
+1. Run `yalc publish` in the current directory.
+2. Run `yalc add @gooddata/maql-antlr4ts` in the target directory
+3. Once you are done with testing run `yalc remove @gooddata/maql-antlr4ts` or `yalc remove --all`
+
+## Publishing
+
+The package is published automatically after merging to master branch.
+
+### Manual publishing
+
+> Unless you have a good reason to do so (i.e. you cannot test a feature otherwise)
+**do not** publish the package manually.
+
+Create a GitLab access token with `api` permissions and store it
+in the `NPM_TOKEN` environment variable.
+
+`export NPM_TOKEN=<your acces token>`
+
+Build and publish the package. You must first set a new version of the package. You must choose one that is not yet
+taken
+(or delete the existing package). You can use
+`yarn bump`  or `yarn version <new version>`.
+
+Then you should build the package
+
+`yarn build`
+
+and publish.
+
+`npm publish`
+
+You should now be able to see the package in the GitLab project registry.
+
+The id of the project is set to `16539767`