138 lines
2.4 KiB
Markdown
138 lines
2.4 KiB
Markdown
# code-red
|
|
|
|
Experimental toolkit for writing x-to-JavaScript compilers. It is used in [Svelte](https://svelte.dev).
|
|
|
|
|
|
## API
|
|
|
|
The `code-red` package exposes three core functions — `b`, `x` and `print`.
|
|
|
|
`b` and `x` take a template literal and return an [ESTree](https://github.com/estree/estree) program body, or a single node:
|
|
|
|
```js
|
|
import { b, x } from 'code-red';
|
|
|
|
const expression = x`i + j`;
|
|
|
|
assert.equal(expression.type, 'AssignmentExpression');
|
|
assert.equal(expression.operator, '+');
|
|
assert.equal(expression.left.name, 'i');
|
|
assert.equal(expression.right.name, 'j');
|
|
|
|
const body = b`
|
|
const i = 1;
|
|
const j = 2;
|
|
const k = i + j;
|
|
`;
|
|
|
|
assert.equal(body.length, 3);
|
|
assert.equal(body[0].type, 'VariableDeclaration');
|
|
```
|
|
|
|
Expressions in template literals correspond to replacement nodes — so you could express the above like so:
|
|
|
|
```js
|
|
const i = x`i`;
|
|
const j = x`j`;
|
|
const expression = x`${i} + ${j}`;
|
|
|
|
const body = b`
|
|
const ${i} = 1;
|
|
const ${j} = 2;
|
|
const k = ${expression};
|
|
`;
|
|
```
|
|
|
|
The `print` function takes a node and turns it into a `{code, map}` object:
|
|
|
|
```js
|
|
const add = x`
|
|
function add(${i}, ${j}) {
|
|
return ${expression};
|
|
}
|
|
`;
|
|
|
|
print(add).code;
|
|
/*
|
|
function add(i, j) {
|
|
return i + j;
|
|
}
|
|
*/
|
|
|
|
i.name = 'foo';
|
|
j.name = 'bar';
|
|
|
|
print(add).code;
|
|
/*
|
|
function add(foo, bar) {
|
|
return foo + bar;
|
|
}
|
|
*/
|
|
```
|
|
|
|
## Prefixes
|
|
|
|
### `@`-prefixed names (replaceable globals)
|
|
|
|
So that you can use globals in your code. In Svelte, we use this to insert utility functions.
|
|
|
|
```js
|
|
// input
|
|
import { x } from 'code-red';
|
|
x`@foo(bar)`
|
|
|
|
// output
|
|
FOO(bar)
|
|
```
|
|
|
|
### `#`-prefixed names (automatically deconflicted names)
|
|
|
|
So that you can insert variables in your code without worrying if they clash with existing variable names.
|
|
|
|
|
|
`bar` used in user code and in inserted code gets a `$1` suffix:
|
|
|
|
```js
|
|
// input
|
|
import { x } from 'code-red';
|
|
x`
|
|
function foo(#bar) {
|
|
return #bar * bar;
|
|
}`;
|
|
|
|
// output
|
|
function foo(bar$1) {
|
|
return bar$1 * bar;
|
|
}
|
|
```
|
|
|
|
Without conflicts, no `$1` suffix:
|
|
|
|
```js
|
|
// input
|
|
import { b } from 'code-red';
|
|
b`const foo = #bar => #bar * 2`;
|
|
|
|
// output
|
|
const foo = bar => bar * 2;
|
|
```
|
|
|
|
## Optimiser
|
|
|
|
TODO add an optimiser that e.g. collapses consecutive identical if blocks
|
|
|
|
|
|
## Compiler
|
|
|
|
TODO add a `code-red/compiler` module that replaces template literals with the nodes they evaluate to, so that there's nothing to parse at runtime.
|
|
|
|
|
|
## Sourcemaps
|
|
|
|
TODO support source mappings for inserted nodes with location information.
|
|
|
|
|
|
## License
|
|
|
|
[MIT](LICENSE)
|