0
# RapydScript-NG
1
2
RapydScript-NG is a Python-to-JavaScript transpiler that allows developers to write JavaScript applications using Python syntax and semantics. It provides a comprehensive solution for those who prefer Python's clean, readable syntax over JavaScript's constructs, while maintaining full interoperability with existing JavaScript libraries and frameworks. The compiler supports advanced Python features including classes with inheritance, generators, iterators, comprehensions, exception handling, and a module system that works like Python's import mechanism.
3
4
## Package Information
5
6
- **Package Name**: rapydscript-ng
7
- **Package Type**: npm
8
- **Language**: JavaScript (transpiler for Python-like syntax)
9
- **Installation**: `npm install rapydscript-ng` (global: `npm install -g rapydscript-ng`)
10
11
## Core Imports
12
13
```javascript
14
// Main programmatic usage (package.json main entry)
15
const { create_compiler } = require("rapydscript-ng");
16
const RapydScript = create_compiler();
17
```
18
19
```javascript
20
// Explicit path to compiler module
21
const { create_compiler } = require("rapydscript-ng/tools/compiler");
22
const RapydScript = create_compiler();
23
```
24
25
## Basic Usage
26
27
### Command Line Usage
28
29
```bash
30
# Compile a RapydScript file to JavaScript
31
rapydscript input.pyj --output output.js
32
33
# Interactive REPL
34
rapydscript repl
35
36
# Lint RapydScript code
37
rapydscript lint input.pyj
38
39
# Execute RapydScript directly
40
rapydscript --execute input.pyj
41
```
42
43
### Programmatic Usage
44
45
```javascript
46
const { create_compiler } = require("rapydscript-ng");
47
const RapydScript = create_compiler();
48
49
// Parse RapydScript source code
50
const ast = RapydScript.parse(sourceCode, {
51
filename: 'example.pyj',
52
basedir: '/path/to/project',
53
libdir: '/path/to/stdlib'
54
});
55
56
// Generate JavaScript output
57
const output = new RapydScript.OutputStream({ beautify: true });
58
ast.print(output);
59
const javascript = output.get();
60
```
61
62
## Architecture
63
64
RapydScript-NG is built around several key components:
65
66
- **Compiler Core**: Main parsing and code generation engine with AST manipulation
67
- **Command Line Interface**: Multi-mode CLI supporting compilation, REPL, linting, and testing
68
- **Built-in Libraries**: Python standard library implementations (math, re, random, etc.)
69
- **AST System**: Complete Abstract Syntax Tree with 50+ node types covering all Python constructs
70
- **Output Generation**: Specialized code generators for different JavaScript constructs
71
- **Runtime Library**: JavaScript implementations of Python built-ins and semantics
72
73
## Capabilities
74
75
### Compilation and Parsing
76
77
Core compilation functionality for transforming RapydScript source code into optimized JavaScript. Supports all Python language features with advanced optimization options.
78
79
```javascript { .api }
80
function create_compiler(): CompilerInstance;
81
82
interface CompilerInstance {
83
parse(code: string, options: ParseOptions): AST_Toplevel;
84
OutputStream: new (options: OutputOptions) => OutputStream;
85
DefaultsError: typeof Error;
86
SyntaxError: typeof Error;
87
ImportError: typeof Error;
88
string_template: (template: string, vars: object) => string;
89
tokenizer: (code: string, options: object) => TokenStream;
90
compile_time_decorators: object;
91
ALL_KEYWORDS: string[];
92
IDENTIFIER_PAT: RegExp;
93
NATIVE_CLASSES: string[];
94
}
95
96
interface ParseOptions {
97
filename?: string;
98
toplevel?: AST_Toplevel;
99
basedir?: string;
100
libdir?: string;
101
import_dirs?: string[];
102
discard_asserts?: boolean;
103
module_cache_dir?: string;
104
}
105
```
106
107
[Compilation and Parsing](./compilation.md)
108
109
### Command Line Interface
110
111
Comprehensive CLI with multiple operational modes for different development workflows. Includes compilation, REPL, linting, testing, and internationalization tools.
112
113
```bash { .api }
114
# Main modes
115
rapydscript compile [options] <files...>
116
rapydscript repl [options]
117
rapydscript lint [options] <files...>
118
rapydscript test [tests...]
119
rapydscript self [options]
120
rapydscript gettext <files...>
121
rapydscript msgfmt
122
```
123
124
[Command Line Interface](./cli.md)
125
126
### Built-in Libraries
127
128
Python standard library implementations providing familiar APIs for JavaScript environments. Includes math operations, regular expressions, random numbers, encodings, cryptography, and more.
129
130
```javascript { .api }
131
// Import from RapydScript source
132
import { sin, cos, pi } from "math";
133
import { randint, choice } from "random";
134
import { match, search } from "re";
135
import { base64encode, utf8_decode } from "encodings";
136
```
137
138
[Built-in Libraries](./libraries.md)
139
140
### Abstract Syntax Tree
141
142
Complete AST system with 50+ node classes representing all Python language constructs. Supports programmatic manipulation and analysis of RapydScript code.
143
144
```javascript { .api }
145
// Core AST classes
146
class AST_Node {
147
transform(transformer: TreeTransformer): AST_Node;
148
walk(visitor: TreeWalker): void;
149
}
150
151
class AST_Statement extends AST_Node {}
152
class AST_Expression extends AST_Node {}
153
class AST_Function extends AST_Statement {}
154
class AST_Class extends AST_Statement {}
155
```
156
157
[Abstract Syntax Tree](./ast.md)
158
159
### Code Generation
160
161
Specialized output generation system that converts AST nodes into optimized JavaScript code. Supports multiple JavaScript versions and output formats.
162
163
```javascript { .api }
164
interface OutputOptions {
165
beautify?: boolean;
166
private_scope?: boolean;
167
omit_baselib?: boolean;
168
js_version?: number;
169
keep_docstrings?: boolean;
170
discard_asserts?: boolean;
171
}
172
173
class OutputStream {
174
constructor(options: OutputOptions);
175
print(text: string): void;
176
get(): string;
177
}
178
```
179
180
[Code Generation](./output.md)
181
182
### Embedded Compiler
183
184
Streaming compilation interface optimized for web browsers and embedded environments. Supports incremental compilation with state preservation across multiple compile operations.
185
186
```javascript { .api }
187
function create_embedded_compiler(
188
compiler: CompilerInstance,
189
baselib: string,
190
runjs?: Function,
191
name?: string
192
): EmbeddedCompiler;
193
194
interface EmbeddedCompiler {
195
compile(code: string, options: EmbeddedCompileOptions): string;
196
toplevel: AST_Toplevel | null;
197
}
198
199
interface EmbeddedCompileOptions {
200
filename?: string;
201
keep_baselib?: boolean;
202
keep_docstrings?: boolean;
203
js_version?: number;
204
private_scope?: boolean;
205
write_name?: boolean;
206
discard_asserts?: boolean;
207
}
208
```
209
210
[Embedded Compiler](./embedded.md)
211
212
## Types
213
214
```javascript { .api }
215
interface CompilerInstance {
216
parse: (code: string, options: ParseOptions) => AST_Toplevel;
217
OutputStream: new (options: OutputOptions) => OutputStream;
218
DefaultsError: typeof Error;
219
SyntaxError: typeof Error;
220
ImportError: typeof Error;
221
string_template: (template: string, vars: object) => string;
222
tokenizer: (code: string, options: object) => TokenStream;
223
ALL_KEYWORDS: string[];
224
IDENTIFIER_PAT: RegExp;
225
NATIVE_CLASSES: string[];
226
}
227
228
interface ParseOptions {
229
filename?: string;
230
toplevel?: AST_Toplevel;
231
basedir?: string;
232
libdir?: string;
233
import_dirs?: string[];
234
discard_asserts?: boolean;
235
module_cache_dir?: string;
236
}
237
238
interface OutputOptions {
239
beautify?: boolean;
240
private_scope?: boolean;
241
omit_baselib?: boolean;
242
js_version?: number;
243
keep_docstrings?: boolean;
244
discard_asserts?: boolean;
245
module_cache_dir?: string;
246
baselib_plain?: string;
247
comments?: boolean | Function;
248
}
249
250
class AST_Toplevel extends AST_Block {
251
print(output: OutputStream): void;
252
}
253
254
class OutputStream {
255
constructor(options: OutputOptions);
256
print(text: string): void;
257
with_indent(body: () => void): void;
258
get(): string;
259
toString(): string;
260
}
261
```