UNPKG

4.97 kBMarkdownView Raw
1# TypeScript Thrift Parser
2
3A parser for Thrift written in TypeScript. The resulting AST can be used to codegen JavaScript from a Thrift file, or just to inspect the Thrift structure.
4
5## Usage
6
7A successful parse returns a ThriftDocument object. An unsuccessful parse returns a ThriftErrors object.
8
9```js
10import { parse, ThriftDocument } from '@creditkarma/thrift-parser'
11
12
13const rawThrift: string =`
14 struct MyStruct {
15 1: required i32 id
16 }
17`;
18
19const thriftAST: ThriftDocument | ThriftErrors = parse(rawThrift);
20
21switch(thriftAST.type) {
22 case 'ThriftDocument':
23 // Do something with valid AST
24 case 'ThriftErrors':
25 // Report or recover from errors
26}
27```
28
29You can also use Thrift Parser from the command line or npm scripts. When using from the command line the generated AST is saved to file as JSON.
30
31```sh
32$ thrift-parser --rootDir thrift --outDir thrift-json --fastFail false some_file.thrift
33```
34
35In this usage there are three options:
36
37* --rootDir: where to initiate file search and save
38* --outDir: relative to rootDir where to save output files
39* --fastFail: If true fail on first error encountered
40
41### Build
42
43```sh
44$ npm install
45$ npm run build
46```
47
48### Test
49
50```sh
51$ npm test
52```
53
54## AST Structure
55
56The root of the returned AST is either a ThriftDocument (successful parse) or a ThriftErrors (unsuccessful parse).
57
58### ThriftDocument
59
60```typescript
61{
62 type: "ThriftDocument",
63 body: Array<ThriftStatement>
64}
65```
66
67### ThriftErrors
68
69```typescript
70{
71 type: "ThriftErrors",
72 errors: Array<ThriftError>
73}
74```
75
76#### ThriftError
77
78A descriptor of what went wrong while parsing the specified Thrift source.
79
80```typescript
81{
82 type: "ParseError" | "ScanError",
83 message: string,
84 loc: TextLocation
85}
86```
87
88### Thrift Statements
89
90Thrift Statements represent each of the main constructs that can be defined in Thrift source.
91
92#### NamespaceDefinition
93
94```
95namespace <identifier> <identifier>
96```
97
98```typescript
99{
100 type: "NamespaceDefinition",
101 scope: Identifier,
102 name: Identifier
103}
104```
105
106#### IncludeDefinition
107
108```
109include '<path>'"
110```
111
112```typescript
113{
114 type: "IncludeDefinition",
115 path: StringLiteral
116}
117```
118
119#### TypedefDefinition
120
121```
122typedef <field-type> <identifier>
123```
124
125```typescript
126{
127 type: "TypedefDefinition",
128 name: Identifier,
129 definitionType: FieldType
130}
131```
132
133#### ConstDefinition
134
135```
136const <field-type> <identifier> = <initializer>
137```
138
139```typescript
140{
141 type: "ConstDefinition",
142 name: Identifier,
143 fieldType: FieldType,
144 initializer: ConstValue,
145}
146```
147
148#### EnumDefinition
149
150```
151enum <identifier> { <members> }
152```
153
154```typescript
155{
156 type: "EnumDefinition",
157 name: Identifier,
158 members: Array<EnumMember>
159}
160```
161
162#### StructDefinition
163
164```
165struct <identifier> { <fields> }
166```
167
168```typescript
169{
170 type: "StructDefinition",
171 name: Identifier,
172 fields: Array<FieldDefinition>
173}
174```
175
176#### UnionDefinition
177
178```
179union <identifier> { <fields> }
180```
181
182```typescript
183{
184 type: "UnionDefinition",
185 name: Identifier,
186 fields: Array<FieldDefinition>
187}
188```
189
190#### ExceptionDefinition
191
192```
193exception <identifier> { <fields> }
194```
195
196```typescript
197{
198 type: "ExceptionDefinition",
199 name: Identifier,
200 fields: Array<FieldDefinition>
201}
202```
203
204#### ServiceDefinition
205
206```
207service <identifier> (extends <identifier>)? { <functions> }
208```
209
210```typescript
211{
212 type: "ServiceDefinition",
213 name: Identifier,
214 extends: Identifier | null,
215 functions: Array<FunctionDefinition>
216}
217```
218
219## Viewing with ASTExplorer
220
221ASTExplorer is a web app for visualizing ASTs. You type source. It shows you the resulting syntax tree based on the parser you've selected. I've included the integrations for this parser. To get that up and running you'll need to clone ASTExplorer.
222
223```sh
224$ git clone https://github.com/fkling/astexplorer.git
225$ cd astexplorer/website
226$ npm install
227```
228
229You will now need to install thrift-parser for ASTExplorer
230
231```sh
232$ npm install @creditkarma/thrift-parser
233```
234
235Cool, now we need to copy some stuff into the ASTExplorer project.
236
237If the ASTExplorer project and the @creditkarma/thrift-parser project are siblings you can type this into the temrinal (from astexplorer/website)...
238
239```sh
240$ cp -r ../../thrift-parser/astexplorer/thrift ./src/parsers/thrift
241```
242
243You'll now need to build ASTExplorer and start the server
244
245```sh
246$ npm run build
247$ npm start
248```
249
250By default this will start ASTExplorer on localhost:8080
251
252There is a dropdown to select the language you want to use, choose 'Thrift IDL'
253
254Note: I have had some trouble getting `npm run build` to work. However, the watch build is much more reliable.
255
256```sh
257$ npm run watch
258```
259
260Then in another terminal window run `start`.
261
262```sh
263$ npm start
264```
265
266## Contributing
267
268For more information about contributing new features and bug fixes, see our [Contribution Guidelines](https://github.com/creditkarma/CONTRIBUTING.md).
269External contributors must sign Contributor License Agreement (CLA)
270
271## License
272
273This project is licensed under [Apache License Version 2.0](./LICENSE)
\No newline at end of file