@malloydata/motly-ts-parser 0.3.0 → 0.3.1
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 +149 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
# @malloydata/motly-ts-parser
|
|
2
|
+
|
|
3
|
+
A pure TypeScript implementation of a parser for [MOTLY](https://github.com/malloydata/motly), a configuration language from [Malloy](https://github.com/malloydata/malloy). Zero native dependencies.
|
|
4
|
+
|
|
5
|
+
This package parses MOTLY source text into a node tree and validates it against schemas. Higher-level language bindings for working with MOTLY data are planned separately.
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
npm install @malloydata/motly-ts-parser
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Quick usage
|
|
14
|
+
|
|
15
|
+
```typescript
|
|
16
|
+
import { MOTLYSession } from "@malloydata/motly-ts-parser";
|
|
17
|
+
|
|
18
|
+
const session = new MOTLYSession();
|
|
19
|
+
|
|
20
|
+
const errors = session.parse(`
|
|
21
|
+
server = webhost {
|
|
22
|
+
host = localhost
|
|
23
|
+
port = 8080
|
|
24
|
+
ssl = @true
|
|
25
|
+
}
|
|
26
|
+
`);
|
|
27
|
+
|
|
28
|
+
if (errors.length > 0) {
|
|
29
|
+
console.error(errors);
|
|
30
|
+
} else {
|
|
31
|
+
const value = session.getValue();
|
|
32
|
+
console.log(value);
|
|
33
|
+
// {
|
|
34
|
+
// properties: {
|
|
35
|
+
// server: {
|
|
36
|
+
// eq: "webhost",
|
|
37
|
+
// properties: {
|
|
38
|
+
// host: { eq: "localhost" },
|
|
39
|
+
// port: { eq: 8080 },
|
|
40
|
+
// ssl: { eq: true }
|
|
41
|
+
// }
|
|
42
|
+
// }
|
|
43
|
+
// }
|
|
44
|
+
// }
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
session.dispose();
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
## MOTLY syntax at a glance
|
|
51
|
+
|
|
52
|
+
```motly
|
|
53
|
+
# Bare strings, numbers, booleans, dates
|
|
54
|
+
name = hello
|
|
55
|
+
port = 8080
|
|
56
|
+
enabled = @true
|
|
57
|
+
created = @2024-01-15
|
|
58
|
+
|
|
59
|
+
# Nested properties
|
|
60
|
+
database: {
|
|
61
|
+
host = localhost
|
|
62
|
+
pool: { max = 20 min = 5 }
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
# Deep path shorthand
|
|
66
|
+
database.pool.timeout = 5000
|
|
67
|
+
|
|
68
|
+
# Arrays (including objects)
|
|
69
|
+
colors = [red, green, blue]
|
|
70
|
+
users = [
|
|
71
|
+
{ name = alice role = admin },
|
|
72
|
+
{ name = bob role = user }
|
|
73
|
+
]
|
|
74
|
+
|
|
75
|
+
# References and cloning
|
|
76
|
+
defaults: { timeout = 30 retries = 3 }
|
|
77
|
+
api := $defaults { timeout = 10 }
|
|
78
|
+
|
|
79
|
+
# Environment references
|
|
80
|
+
secrets: { password = @env.DB_PASSWORD }
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
See the [full language reference](https://github.com/malloydata/motly/blob/main/docs/language.md) for all string types, operators, deletion, schemas, and more.
|
|
84
|
+
|
|
85
|
+
## API reference
|
|
86
|
+
|
|
87
|
+
### `MOTLYSession`
|
|
88
|
+
|
|
89
|
+
```typescript
|
|
90
|
+
class MOTLYSession {
|
|
91
|
+
parse(source: string): MOTLYError[];
|
|
92
|
+
parseSchema(source: string): MOTLYError[];
|
|
93
|
+
getValue(): MOTLYNode;
|
|
94
|
+
reset(): void;
|
|
95
|
+
validateSchema(): MOTLYSchemaError[];
|
|
96
|
+
validateReferences(): MOTLYValidationError[];
|
|
97
|
+
dispose(): void;
|
|
98
|
+
}
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
| Method | Description |
|
|
102
|
+
|--------|-------------|
|
|
103
|
+
| `parse(source)` | Parse MOTLY source and apply it to the session value. Returns parse errors. Successive calls accumulate into the same value tree. |
|
|
104
|
+
| `parseSchema(source)` | Parse MOTLY source as a schema (replaces any previous schema). |
|
|
105
|
+
| `getValue()` | Return a deep clone of the current value tree. |
|
|
106
|
+
| `reset()` | Clear the value tree (schema is kept). |
|
|
107
|
+
| `validateSchema()` | Validate the current value against the stored schema. Returns `[]` if no schema is set. |
|
|
108
|
+
| `validateReferences()` | Check that all `$`-references in the value tree resolve. |
|
|
109
|
+
| `dispose()` | Mark the session as dead. All subsequent method calls will throw. |
|
|
110
|
+
|
|
111
|
+
### Exported types
|
|
112
|
+
|
|
113
|
+
```typescript
|
|
114
|
+
// The value tree
|
|
115
|
+
interface MOTLYNode {
|
|
116
|
+
eq?: MOTLYValue;
|
|
117
|
+
properties?: Record<string, MOTLYPropertyValue>;
|
|
118
|
+
deleted?: boolean;
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
type MOTLYScalar = string | number | boolean | Date;
|
|
122
|
+
type MOTLYValue = MOTLYScalar | MOTLYEnvRef | MOTLYPropertyValue[];
|
|
123
|
+
type MOTLYPropertyValue = MOTLYNode | MOTLYRef;
|
|
124
|
+
|
|
125
|
+
interface MOTLYRef { linkTo: string } // $-reference (structural link)
|
|
126
|
+
interface MOTLYEnvRef { env: string } // @env.NAME (value from environment)
|
|
127
|
+
|
|
128
|
+
// Errors
|
|
129
|
+
interface MOTLYError { code: string; message: string; begin: Position; end: Position }
|
|
130
|
+
interface MOTLYSchemaError { code: string; message: string; path: string[] }
|
|
131
|
+
interface MOTLYValidationError { code: string; message: string; path: string[] }
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
### Type guards
|
|
135
|
+
|
|
136
|
+
```typescript
|
|
137
|
+
import { isRef, isEnvRef } from "@malloydata/motly-ts-parser";
|
|
138
|
+
|
|
139
|
+
isRef(propertyValue); // true if MOTLYRef ({ linkTo })
|
|
140
|
+
isEnvRef(node.eq); // true if MOTLYEnvRef ({ env })
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
## Full language documentation
|
|
144
|
+
|
|
145
|
+
[docs/language.md](https://github.com/malloydata/motly/blob/main/docs/language.md) — complete reference with EBNF grammar.
|
|
146
|
+
|
|
147
|
+
## License
|
|
148
|
+
|
|
149
|
+
MIT
|