# alan-compile

> Compile of alan to amm and javascript

Latest version **0.0.10** (published 2020-09-09) · AGPL-3.0 license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install alan-compile
pnpm add alan-compile
yarn add alan-compile
bun add alan-compile
```

Provides the command `alan-compile`.

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 0.0.10 |
| Published | 2020-09-09 |
| First published | 2020-08-21 |
| Weekly downloads | 0 |
| License | AGPL-3.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 6 |
| Unpacked size | 3.3 MB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| Author | David Ellis |
| Maintainers | dfellis |
| Keywords | alan, compiler, transpiler |

## Links

- npm: https://www.npmjs.com/package/alan-compile
- npm.io page: https://npm.io/package/alan-compile

## Dependencies (6)

- [uuid](https://npm.io/package/uuid.md) ^8.0.0
- [antlr4](https://npm.io/package/antlr4.md) ^4.8.0
- [commander](https://npm.io/package/commander.md) ^5.1.0
- [@types/node](https://npm.io/package/@types/node.md) ^14.0.5
- [@types/uuid](https://npm.io/package/@types/uuid.md) ^8.0.0
- [alan-js-runtime](https://npm.io/package/alan-js-runtime.md) 0.0.4

## Alternatives

- [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads
- [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads
- [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads
- [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads
- [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads

## Recent versions

- 0.0.10 (latest) — 2020-09-09
- 0.0.9 — 2020-09-04
- 0.0.8 — 2020-09-04
- 0.0.7 — 2020-09-02
- 0.0.6 — 2020-09-02
- 0.0.5 — 2020-09-01
- 0.0.4 — 2020-08-27
- 0.0.3 — 2020-08-25
- 0.0.2 — 2020-08-21
- 0.0.1 — 2020-08-21

## README

# alan-compile

A compiler for alan to Javascript and Alan Graphcode, the [runtime](https://github.com/alantech/alan/tree/master/runtime)'s bytecode format.

Caveats: There should be a strict mode that make sure int64s are using [BigInt](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt) despite the performance loss, but the vast majority of the time falling back to regular numbers should work.

This compiler is licensed AGPL 3.0 but the [alan standard library](https://github.com/alantech/alan/tree/master/std) and the [Javascript runtime shim](https://github.com/alantech/alan/tree/master/js-runtime) are licensed Apache 2.0 so you can freely distribute your compiled code.

## Install

```sh
npm install -g alan-compile
```

## Usage

```sh
alan-compile <sourcefile> <outputfile>
```

The compiler uses the file extension to determine what compilation steps to perform.

The supported source formats are:

* `.ln` - The a*l*a*n* source file extension, with automatic traversal and loading of specified imports relative to this file.
* `.amm` - The *a*lan *m*inus *m*inus (`alan--`) intermediate representation. A strict subset of `alan` in a single file used for final conversion to the output formats.
* `.aga` - The *a*lan *g*raph *a*ssembler format. An intermediate representation very close to the `.agc` format (below) that the runtime operates on. It also indicates the dependency graph of operations in the format that can be used by the runtime. Useful for debugging runtime behavior issues or if you are targeting the runtime with a different language.

The supported output formats are:

* `.amm` - The *a*lan *m*inus *m*inus (`alan--`) intermediate representation, useful only for debugging compiler issues or if you are writing your own second stage compiler for another runtime environment.
* `.aga` - The *a*lan *g*raph *a*ssembler format. An intermediate representation very close to the `.agc` format (below) that the runtime operates on. It also indicates the dependency graph of operations in the format that can be used by the runtime. Useful for debugging runtime behavior issues or if you are targeting the runtime with a different language.
* `.agc` - The *a*lan *g*raph*c*ode bytecode format. The bytecode format of the alan [runtime](https://github.com/alantech/runtime) that also maintains a dependency graph of operations to allow quick, dynamic restructuring of the code safely depending on the data being processed and the state and capabilities of the machine it is running on.
* `.js` - The most common [ECMAScript](https://ecma-international.org/ecma-262/10.0/index.html) file extension, representing a [CommonJS](http://www.commonjs.org/) module (aka a [Node](https://nodejs.org/en/) module).

Note: `.amm` to `.amm` is absurd and not supported. :)

## Browser Support

This project also uses [Browserify](http://browserify.org/) to create a version of the compiler that works directly in the browser. The browser version of the compiler does not support output to `.agc`, but does support `.js` which can be simply `eval()`ed to execute.

To get this bundled browser version, simply run:

```sh
yarn bundle
```

and copy the resulting `bundle.js` to your own project, include it in a `<script>` tag:

```html
<script src="bundle.js"></script>
```

then in your own Javascript source included later, you can acquire and use the compiler in this way:

```js
const alanCompile = require('alan-compile') // Browserify creates a toplevel `require` function that you can use to get the modules
const helloWorld = alanCompile('ln', 'js', `
  import @std/app

  on app.start {
    app.print("Hello, World!")
    emit app.exit 0
  }
`) // argument order is: sourceExtension, outputExtension, sourceCode
eval(helloWorld) // Execute the generated javascript code
```

### Licensing Warning

While the Alan Standard Library and Alan JS Runtime are Apache 2.0 license and therefore freely distributable with your own code, the Alan Compiler is AGPL 3.0 licensed, so embedding the compiler in this way requires the project using it to also be AGPL 3.0 licensed.

Pregenerating the Javascript to run in your own build system from the CLI tool does not cause this licensing escalation. However, this is only a problem in a minority of use-cases as the Javascript source is already transmitted to the users.

## Development

`alan-compile` uses [ANTLR](https://www.antlr.org/) to define the `alan` grammar and create the lexer and parser. The grammar is defined in `ln/Ln.g4` along with the autogenerated source code.

To edit the language grammar itself, you need to have `antlr4` installed:

```sh
sudo apt install antlr4
```

and then regenerate the Javascript lexer and parser by running, for example:

```sh
cd src/ln
antlr4 -Dlanguage=JavaScript Ln.g4
```

The rest of the development is relatively standard Node.js+Typescript work with the source code in `src` and running `yarn build` to recompile (or just `tsc` if you have that installed globally).

### Contribution Agreement

To contribute to `alan-compile` you need to sign a Contributor License Agreement, Alan Technologies will retain the right to relicense this code in licenses other than AGPL 3.0 concurrently or in the future to convert to a newer license.

## License

AGPL 3.0

---
_Source: https://npm.io/package/alan-compile · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._