@intend-it/parser 1.0.1 → 1.1.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 +121 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
<h1>@intend-it/parser</h1>
|
|
3
|
+
<p><strong>Parser for the Intend Programming Language</strong></p>
|
|
4
|
+
<p>
|
|
5
|
+
<a href="https://www.npmjs.com/package/@intend-it/parser"><img src="https://img.shields.io/npm/v/@intend-it/parser.svg" alt="npm version"></a>
|
|
6
|
+
<a href="https://www.npmjs.com/package/@intend-it/parser"><img src="https://img.shields.io/npm/dm/@intend-it/parser.svg" alt="npm downloads"></a>
|
|
7
|
+
<a href="https://github.com/DRFR0ST/intend/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@intend-it/parser.svg" alt="license"></a>
|
|
8
|
+
</p>
|
|
9
|
+
</div>
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## Overview
|
|
14
|
+
|
|
15
|
+
`@intend-it/parser` is the lexer and parser for the **Intend** programming language. It transforms `.intent` source files into a structured Abstract Syntax Tree (AST) that can be used for code generation, analysis, or tooling.
|
|
16
|
+
|
|
17
|
+
Built with [Chevrotain](https://chevrotain.io/) for robust, fast parsing.
|
|
18
|
+
|
|
19
|
+
## Installation
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
npm install @intend-it/parser
|
|
23
|
+
# or
|
|
24
|
+
bun add @intend-it/parser
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
## Usage
|
|
28
|
+
|
|
29
|
+
### Parse to AST
|
|
30
|
+
|
|
31
|
+
```typescript
|
|
32
|
+
import { parseToAST } from "@intend-it/parser";
|
|
33
|
+
|
|
34
|
+
const source = `
|
|
35
|
+
export intent Greet(name: string) -> string {
|
|
36
|
+
step "Create a greeting message" => const message
|
|
37
|
+
ensure message is defined
|
|
38
|
+
}
|
|
39
|
+
`;
|
|
40
|
+
|
|
41
|
+
const result = parseToAST(source);
|
|
42
|
+
|
|
43
|
+
console.log(result.ast);
|
|
44
|
+
// {
|
|
45
|
+
// type: "IntendFile",
|
|
46
|
+
// imports: [],
|
|
47
|
+
// intents: [{
|
|
48
|
+
// name: "Greet",
|
|
49
|
+
// parameters: [{ name: "name", type: "string" }],
|
|
50
|
+
// returnType: { base: "string" },
|
|
51
|
+
// body: { ... }
|
|
52
|
+
// }]
|
|
53
|
+
// }
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
### Parse to CST (Concrete Syntax Tree)
|
|
57
|
+
|
|
58
|
+
```typescript
|
|
59
|
+
import { parse } from "@intend-it/parser";
|
|
60
|
+
|
|
61
|
+
const result = parse(source);
|
|
62
|
+
|
|
63
|
+
if (result.lexingErrors.length > 0) {
|
|
64
|
+
console.error("Lexing errors:", result.lexingErrors);
|
|
65
|
+
}
|
|
66
|
+
if (result.parsingErrors.length > 0) {
|
|
67
|
+
console.error("Parsing errors:", result.parsingErrors);
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
console.log(result.cst); // Raw CST from Chevrotain
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
## AST Structure
|
|
74
|
+
|
|
75
|
+
### IntendFile
|
|
76
|
+
|
|
77
|
+
```typescript
|
|
78
|
+
interface IntendFile {
|
|
79
|
+
type: "IntendFile";
|
|
80
|
+
imports: ImportNode[];
|
|
81
|
+
intents: IntentDeclaration[];
|
|
82
|
+
}
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
### IntentDeclaration
|
|
86
|
+
|
|
87
|
+
```typescript
|
|
88
|
+
interface IntentDeclaration {
|
|
89
|
+
name: string;
|
|
90
|
+
isExported: boolean;
|
|
91
|
+
isEntry: boolean;
|
|
92
|
+
parameters: Parameter[];
|
|
93
|
+
returnType: ReturnType;
|
|
94
|
+
body: {
|
|
95
|
+
invariants: InvariantNode[];
|
|
96
|
+
steps: StepNode[];
|
|
97
|
+
ensures: EnsureNode[];
|
|
98
|
+
};
|
|
99
|
+
}
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
## Language Features Supported
|
|
103
|
+
|
|
104
|
+
| Feature | Syntax | Example |
|
|
105
|
+
|---------|--------|---------|
|
|
106
|
+
| **Intents** | `intent Name(params) -> Type { ... }` | `intent Add(a: number, b: number) -> number` |
|
|
107
|
+
| **Steps** | `step "instruction"` | `step "Validate the input"` |
|
|
108
|
+
| **Result Variables** | `=> const x` or `=> let x` | `step "Calculate" => const result` |
|
|
109
|
+
| **Invariants** | `invariant "rule"` | `invariant "Input must be positive"` |
|
|
110
|
+
| **Ensures** | `ensure expression` | `ensure result is defined` |
|
|
111
|
+
| **Imports** | `import { X } from "path"` | `import { User } from "./types"` |
|
|
112
|
+
| **Entry Points** | `entry intent Main()` | `export entry intent Main() -> void` |
|
|
113
|
+
|
|
114
|
+
## Related Packages
|
|
115
|
+
|
|
116
|
+
- [`@intend-it/core`](https://www.npmjs.com/package/@intend-it/core) - AI-powered code generator
|
|
117
|
+
- [`@intend-it/cli`](https://www.npmjs.com/package/@intend-it/cli) - Command-line interface
|
|
118
|
+
|
|
119
|
+
## License
|
|
120
|
+
|
|
121
|
+
MIT © [Intend Team](https://github.com/DRFR0ST/intend)
|