danabra.mov
An experimental TypeSpec syntax for Lexicon
tweaks
+23
-11
+23
-11
DOCS.md
+23
-11
DOCS.md
···
48
48
49
49
The JSON is what you'll publish—typelex just makes authoring easier. Think of it as "CoffeeScript for Lexicon" (however terrible that may be).
50
50
51
-
Typelex tries to stay faithful to both TypeSpec idioms and Lexicon concepts, which is a tricky balance. Since we can't add keywords to TypeSpec, decorators fill the gaps—you'll write `@procedure op` instead of `procedure`, or `model` for what Lexicon calls a "def". One downside of this approach is you'll need to learn both Lexicon *and* TypeSpec to know what you're doing. Scan the [TypeSpec language overview](https://typespec.io/docs/language-basics/overview/) to get a feel for it, it isn't much.
51
+
Typelex tries to stay faithful to both TypeSpec idioms and Lexicon concepts, which is a tricky balance. Since we can't add keywords to TypeSpec, decorators fill the gaps—you'll write `@procedure op` instead of `procedure`, or `model` for what Lexicon calls a "def". One downside of this approach is you'll need to learn both Lexicon *and* TypeSpec to know what you're doing. Scan the [TypeSpec language overview](https://typespec.io/docs/language-basics/overview/) to get a feel for it.
52
52
53
53
Personally, I find JSON Lexicons hard to read and author, so the tradeoff works for me.
54
54
55
55
### Playground
56
56
57
-
[Open Playground](https://playground.typelex.org/) to play with a bunch of lexicons and to see how typelex code translates to Lexicon JSON. If you already know Lexicon, you can learn the syntax by just opening the Lexicons you're familiar with.
57
+
[Open Playground](https://playground.typelex.org/) to play with a bunch of lexicons and to see how typelex code translates to Lexicon JSON.
58
+
59
+
If you already know Lexicon, you can learn the syntax by just opening the Lexicons you're familiar with.
58
60
59
61
## Quick Start
60
62
···
84
86
85
87
[Try it in the playground](https://playground.typelex.org/?c=aW1wb3J0ICJAdHlwZWxleC9lbWl0dGVyIjsKCm5hbWVzcGFjZSBhcHAuYnNreS5mZWVkLmRlZnMgewogIG1vZGVsIFBvc3RWaWV3xRMgIHJlcGx5Q291bnQ%2FOiBpbnRlZ2VyO8gab3N01RtsaWtl0xl9Cn0K&e=%40typelex%2Femitter&options=%7B%7D&vs=%7B%7D).
86
88
87
-
Use backticks for reserved words:
89
+
If TypeSpec complains about reserved words in namespaces, use backticks:
88
90
89
91
```typescript
90
92
import "@typelex/emitter";
···
124
126
}
125
127
```
126
128
127
-
Model names convert PascalCase → camelCase:
129
+
Model names convert PascalCase → camelCase. For example, `PostView` becomes `postView`:
128
130
129
131
```json
130
132
{
···
141
143
142
144
### Namespace Conventions: `.defs` vs `Main`
143
145
144
-
By convention, a namespace must either have a `Main` model or end with `.defs`.
146
+
By convention, a namespace must either end with `.defs` or have a `Main` model.
145
147
146
148
Use `.defs` for a grabbag of reusable definitions:
147
149
···
182
184
}
183
185
```
184
186
185
-
This becomes a local `ref`:
187
+
This becomes a `ref` to the `caption` definition in the same file:
186
188
187
189
```json
188
190
// ...
189
-
"captions": {
190
-
"type": "array",
191
-
"items": { "type": "ref", "ref": "#caption" }
192
-
}
191
+
"defs": {
192
+
"main": {
193
+
// ...
194
+
"properties": {
195
+
"captions": {
196
+
// ...
197
+
"items": { "type": "ref", "ref": "#caption" }
198
+
}
199
+
}
200
+
},
201
+
"caption": {
202
+
"type": "object",
203
+
"properties": {}
204
+
}
193
205
// ...
194
206
```
195
207
···
209
221
}
210
222
```
211
223
212
-
This becomes a fully qualified reference:
224
+
This becomes a fully qualified reference to another Lexicon:
213
225
214
226
```json
215
227
// ...