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
```