@creditkarma/thrift-parser
v2.0.0
Published
A parser for Thrift written in TypeScript
Downloads
40,468
Readme
TypeScript Thrift Parser
A 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.
Usage
A successful parse returns a ThriftDocument object. An unsuccessful parse returns a ThriftErrors object.
import { parse, ThriftDocument } from '@creditkarma/thrift-parser'
const rawThrift: string =`
struct MyStruct {
1: required i32 id
}
`;
const thriftAST: ThriftDocument | ThriftErrors = parse(rawThrift);
switch(thriftAST.type) {
case 'ThriftDocument':
// Do something with valid AST
case 'ThriftErrors':
// Report or recover from errors
}
You 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.
$ thrift-parser --rootDir thrift --outDir thrift-json --fastFail false some_file.thrift
In this usage there are three options:
- --rootDir: where to initiate file search and save
- --outDir: relative to rootDir where to save output files
- --fastFail: If true fail on first error encountered
Build
$ npm install
$ npm run build
Test
$ npm test
AST Structure
The root of the returned AST is either a ThriftDocument (successful parse) or a ThriftErrors (unsuccessful parse).
ThriftDocument
{
type: "ThriftDocument",
body: Array<ThriftStatement>
}
ThriftErrors
{
type: "ThriftErrors",
errors: Array<ThriftError>
}
ThriftError
A descriptor of what went wrong while parsing the specified Thrift source.
{
type: "ParseError" | "ScanError",
message: string,
loc: TextLocation
}
Thrift Statements
Thrift Statements represent each of the main constructs that can be defined in Thrift source.
NamespaceDefinition
namespace <identifier> <identifier>
{
type: "NamespaceDefinition",
scope: Identifier,
name: Identifier
}
IncludeDefinition
include '<path>'"
{
type: "IncludeDefinition",
path: StringLiteral
}
TypedefDefinition
typedef <field-type> <identifier>
{
type: "TypedefDefinition",
name: Identifier,
definitionType: FieldType
}
ConstDefinition
const <field-type> <identifier> = <initializer>
{
type: "ConstDefinition",
name: Identifier,
fieldType: FieldType,
initializer: ConstValue,
}
EnumDefinition
enum <identifier> { <members> }
{
type: "EnumDefinition",
name: Identifier,
members: Array<EnumMember>
}
StructDefinition
struct <identifier> { <fields> }
{
type: "StructDefinition",
name: Identifier,
fields: Array<FieldDefinition>
}
UnionDefinition
union <identifier> { <fields> }
{
type: "UnionDefinition",
name: Identifier,
fields: Array<FieldDefinition>
}
ExceptionDefinition
exception <identifier> { <fields> }
{
type: "ExceptionDefinition",
name: Identifier,
fields: Array<FieldDefinition>
}
ServiceDefinition
service <identifier> (extends <identifier>)? { <functions> }
{
type: "ServiceDefinition",
name: Identifier,
extends: Identifier | null,
functions: Array<FunctionDefinition>
}
Viewing with ASTExplorer
ASTExplorer 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.
$ git clone https://github.com/fkling/astexplorer.git
$ cd astexplorer/website
$ npm install
You will now need to install thrift-parser for ASTExplorer
$ npm install @creditkarma/thrift-parser
Cool, now we need to copy some stuff into the ASTExplorer project.
If the ASTExplorer project and the @creditkarma/thrift-parser project are siblings you can type this into the temrinal (from astexplorer/website)...
$ cp -r ../../thrift-parser/astexplorer/thrift ./src/parsers/thrift
You'll now need to build ASTExplorer and start the server
$ npm run build
$ npm start
By default this will start ASTExplorer on localhost:8080
There is a dropdown to select the language you want to use, choose 'Thrift IDL'
Note: I have had some trouble getting npm run build
to work. However, the watch build is much more reliable.
$ npm run watch
Then in another terminal window run start
.
$ npm start
Contributing
For more information about contributing new features and bug fixes, see our Contribution Guidelines. External contributors must sign Contributor License Agreement (CLA)
License
This project is licensed under Apache License Version 2.0