@op-ted/efx-syntax-highlighter 0.2.1 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,41 +1,82 @@
1
1
  # efx-syntax-highlighter
2
2
 
3
- A minimal JavaScript package providing Lezer-based parsing and CodeMirror 6 language support for the efx language.
3
+ EFX support for [CodeMirror 6](https://codemirror.net/) editors: syntax highlighting and completions for EFX-2, the EFX language of the eForms SDK 2, and syntax highlighting for EFX-1, the language of the SDK 1. It reads template files (view templates), rules files (validation rules, EFX-2 only), single expressions with their context, and bare expressions, whose context the application keeps apart.
4
4
 
5
- ## Features
6
- - Lezer parser for efx
7
- - CodeMirror 6 language extension
8
- - Custom highlight theme
5
+ Both parsers read the tokens of the SDK's own ANTLR lexer (`efx-grammar/EfxLexer.g4`): `npm run sync` takes the lexer's compiled table from the lexer ANTLR generates, and a small engine (`src/lexer/`) runs it in the editor as ANTLR runs it, over the whole text, mode by mode. The EFX-2 parser is a [Lezer](https://lezer.codemirror.net/) grammar that follows the SDK's ANTLR grammar (`efx-grammar/Efx.g4`) rule for rule; its completion list comes from the EFX Toolkit. The EFX-1 parser gives expressions no type (`grammar/efx1.grammar`). All of it is taken at the commits pinned in `package.json` (`config`). Tests compare the editor's tokens with ANTLR's lexer's, over the SDK's view templates and rules files and over texts made at random, the EFX-2 trees with ANTLR's parser's, and the EFX-1 grouping of operators with ANTLR's parser's. What each release changes is in [CHANGELOG.md](CHANGELOG.md).
6
+
7
+ ## Install
9
8
 
10
- ## Usage
11
- Install via npm:
12
9
  ```bash
13
10
  npm install @op-ted/efx-syntax-highlighter
14
11
  ```
15
12
 
16
- Import and use in CodeMirror 6:
13
+ The package is an ES module. It needs the CodeMirror packages it lists as dependencies; a bundler resolves them, or an import map in the page, which must then name their own dependencies too (`demo/index.html` has one).
14
+
15
+ ## Use
16
+
17
17
  ```js
18
- import { efx, efxHighlightStyle } from '@op-ted/efx-syntax-highlighter';
18
+ import { autocompletion } from '@codemirror/autocomplete';
19
+ import { EditorState } from '@codemirror/state';
20
+ import { EditorView } from '@codemirror/view';
21
+ import { efx, efxSymbols, efxTheme } from '@op-ted/efx-syntax-highlighter';
19
22
 
20
- const editor = new EditorView({
21
- extensions: [efx(), efxHighlightStyle]
23
+ const view = new EditorView({
24
+ parent: document.getElementById('editor'),
25
+ state: EditorState.create({
26
+ doc: text, // the EFX text to edit
27
+ extensions: [
28
+ efx('template'),
29
+ efxSymbols.of({ fields: ['BT-01-notice', 'BT-26(m)-Procedure'], nodes: ['ND-Root', 'ND-Lot'] }),
30
+ autocompletion(),
31
+ efxTheme,
32
+ ],
33
+ }),
22
34
  });
23
35
  ```
24
36
 
25
- ## Build & Test
26
- To build the parser:
27
- ```bash
28
- npm run build
29
- ```
30
- To run tests:
37
+ The package offers four things:
38
+
39
+ - **`efx(kind)`** gives an editor what it needs to read one kind of EFX-2 text: its parser, the EFX colours and the completions. The kind is `'template'` for a template file, `'rules'` for a rules file, `'expression'` for a single expression with its context, such as `WITH ND-Root COMPUTE BT-01-notice is present`, or `'bare-expression'` for an expression with no context in the text, such as `BT-01-notice is present`, read as the expression of `WITH … COMPUTE`. Any other kind is refused with a `RangeError`. `efx(kind).language` is the CodeMirror language, for an application that needs it on its own.
40
+ - **`efx(kind, { version: 1 })`** does the same for EFX-1 text, without completions. The kinds are `'template'`, `'expression'`, such as `{ND-Root} ${BT-01-notice is present}`, and `'bare-expression'`; EFX-1 has no rules files. Any other kind or version is refused with a `RangeError`.
41
+ - **`efxSymbols`** gives the editor the field and node ids it offers: `efxSymbols.of({ fields, nodes })`, each a list of ids, for example those of the SDK's `fields.json`. The ids of several such extensions add up.
42
+ - **`efxHighlightStyle`** is the EFX colours. `efx(kind)` already uses them as the editor's default colours; an application that gives its editor its own colours with `syntaxHighlighting(...)` replaces them.
43
+ - **`efxTheme`** is a light look for the editor itself (white background, black cursor). Add it if you want it.
44
+
45
+ ### Completions
46
+
47
+ The application turns completion on, with `autocompletion()` from `@codemirror/autocomplete` (or the `basicSetup` of the `codemirror` package, which includes it). While you type, the editor offers the words the grammar can take at the cursor:
48
+
49
+ - at the start of an expression, the functions as calls with their required parameters (`contains(haystack, needle)`), with their signatures beside them, and the keywords;
50
+ - after a field and a colon, the field's properties (`:rawValue`, `:publicationDate`, ...);
51
+ - after `is`, `not`, `empty`, `present` and `unique`;
52
+ - in a label block, the asset types and label types; after the pipe of an expression block, the format options;
53
+ - at the start of a line, the words of a template line or of a rule;
54
+ - the variables the cursor can use, and the field and node ids given through `efxSymbols`, where the grammar takes one.
55
+
56
+ In template text any word can go, so there the list opens only when asked for (Ctrl-Space). Nothing is offered inside a comment or a string.
57
+
58
+ Known limits: after a `/` the `@` of an attribute is not offered; after a syntax error nothing is offered until the error is fixed.
59
+
60
+ ## Develop
61
+
31
62
  ```bash
32
- npm test
63
+ npm run sync # writes the lexer tables, the words and the completion list (committed), and the SDK's EFX files and ANTLR grammars that the tests and the demo read (not committed)
64
+ npm run build # generates the parsers from grammar/efx2.grammar and grammar/efx1.grammar and writes the package to dist/
65
+ npm test # the package, lexer, conformance, style, EFX-2 tree and completion, EFX-1 entry and incremental tests, on the build
66
+ npm run demo # serves a demo page at http://localhost:8080/demo/ (after npm run sync and npm run build)
67
+ npm run site # gathers the demo page and what it loads into site/ (after npm run sync and npm run build)
33
68
  ```
34
69
 
70
+ Each version of EFX has its own places: its grammar in `grammar/efx2.grammar` or `grammar/efx1.grammar`, the modules its parser loads in `src/efx2/` or `src/efx1/` (its lexer table and the lexer's options in `lexer.js`, its highlight tags, and for EFX-2 its completions), and its tests, its copy of the SDK's ANTLR grammar (`oracle/`) and of the SDK's EFX files (`corpus/`) in `test/efx2/` or `test/efx1/`. What both share is at the top of `src/` and `test/`: the entry point and the language (`src/efxLanguage.js`), the lexer engine (`src/lexer/`), the ids (`src/efxSymbols.js`), the colours (`src/efxTheme.js`), and the package, lexer, conformance, style and incremental tests. The build writes each parser beside its modules, in `dist/efx2/` and `dist/efx1/`.
71
+
72
+ The lexer reads the text on its own, as ANTLR's does, whatever the parser makes of the tokens, so the editor shows the tokens ANTLR's lexer reads, errors included. As a token depends on all the text before it, through the lexer's modes, the editor reuses its earlier tree only before the first change to the text, and the lexer reads the parts of the document a parse reads as one text, as ANTLR would (`src/lexer/EditorParser.js`). A comment that a token holds (the `;` that ends a template line, the path of an include) is shown as a comment.
73
+
74
+ `npm run sync` reads the SDK, the toolkit and the SDK of EFX-1 from GitHub at the commits pinned in `package.json`, or pins new ones first: `npm run sync -- <owner>/<repository>@<commit> <owner>/<repository>@<commit> [<owner>/<repository>@<commit>]` (the SDK, then the toolkit, then, if it changes, the SDK of EFX-1). It needs Node 22.13 or later and network access; behind a proxy, set `NODE_USE_ENV_PROXY=1`. A `GITHUB_TOKEN`, when set, is sent to the GitHub API only. Building needs neither network nor Java: the lexer tables, the words and the completion list it builds from are committed. The SDK's EFX files and ANTLR grammars are not: the sync writes them into `corpus/` and `oracle/` of `test/efx2/` and `test/efx1/`, which git ignores, so run `npm run sync` once after cloning and again after moving a pin; the tests say so when they are missing. The Check workflow syncs, builds and tests every push, and fails if a generated file differs from the committed one. The Pages workflow publishes `site/` to the repository's GitHub Pages site on every push to `develop`.
75
+
35
76
  ## Publishing
36
- - Only the `dist/` output is published
37
- - Do not include grammar or test files in the package
38
- - Use `npm publish` to release
77
+
78
+ Only `dist/` is published, with the README and the licence. Pushing a tag of the form `x.y.z` runs the Publish workflow, which builds, tests and publishes to npm, with provenance, the version written in `package.json`: the tag does not set the version, so tag the commit that sets it, with the same number (for example `0.3.0`).
39
79
 
40
80
  ## License
41
- EUPL 2.0
81
+
82
+ [EUPL 2.0](LICENSE)
@@ -0,0 +1,45 @@
1
+ // The highlight tags of the EFX-1 grammar (grammar/efx1.grammar, @external propSource), by the same
2
+ // rules as those of EFX-2 (src/efx2/efx2Highlighting.js), so that both read alike with the same colours.
3
+ import { styleTags, tags as t } from "@lezer/highlight";
4
+
5
+ export const EFX1_STYLES = {
6
+ // The words of expressions.
7
+ "And Or Not Is In Like Present Empty Unique Every Some Satisfies If Then Else For Return Notice Axis": t.className,
8
+ // The words chosen from a fixed list: asset and label types.
9
+ "AssetType LabelType": t.className,
10
+
11
+ // Types, which EFX-1 writes with their colon.
12
+ "BooleanTypeCast NumericTypeCast TextTypeCast CodeTypeCast DateTypeCast TimeTypeCast DurationTypeCast": t.typeName,
13
+ ContextTypeCast: t.typeName,
14
+
15
+ // The built-in functions.
16
+ "FunctionCall/Not CountFunction SubstringFunction StringFunction NumberFunction ContainsFunction": t.function(t.keyword),
17
+ "StartsWithFunction EndsWithFunction StringLengthFunction SumFunction FormatNumberFunction ConcatFunction": t.function(t.keyword),
18
+ "DateFunction TimeFunction DayTimeDurationFunction YearMonthDurationFunction AddMeasure SubtractMeasure": t.function(t.keyword),
19
+ "DistinctValuesFunction UnionFunction IntersectFunction ExceptFunction SequenceEqualFunction": t.function(t.keyword),
20
+
21
+ // Literals.
22
+ "STRING UUIDV4 INTEGER DECIMAL DATE TIME DayTimeDurationLiteral YearMonthDurationLiteral": t.literal,
23
+ "True False Always Never": t.literal,
24
+
25
+ // The data of a notice: fields, nodes and attributes.
26
+ "FieldId NodeId BtId AttributeReference/Identifier": t.propertyName,
27
+
28
+ // Variables, and the field value and label of the context in a template.
29
+ "Variable ShorthandFieldValueReferenceFromContextField ShorthandIndirectLabelReferenceFromContextField": t.variableName,
30
+
31
+ // Names of assets in a label.
32
+ "OtherAssetId AssetId/AssetType AssetId/LabelType": t.special(t.name),
33
+
34
+ // Template text.
35
+ FreeText: t.special(t.string),
36
+
37
+ "Comparison Plus Minus Star Slash Percent ColonColon": t.operator,
38
+ "OpenParenthesis CloseParenthesis OpenBracket CloseBracket Pipe": t.punctuation,
39
+ SlashAt: t.punctuation,
40
+ "StartExpression StartLabel StartSelector EndExpression EndLabel": t.bracket,
41
+ Comment: t.lineComment,
42
+ Identifier: t.name,
43
+ };
44
+
45
+ export const efx1Highlighting = styleTags(EFX1_STYLES);