porffor 0.2.0-3272f21 → 0.2.0-3aaa9b4

package/CONTRIBUTING.md

@@ -0,0 +1,183 @@
+# Contributing to Porffor
+
+Hello! Thanks for your potential interest in contributing to Porffor :)
+
+This document hopes to help you understand Porffor-specific TS, specifically for writing built-ins (inside `compiler/builtins/` eg `btoa`, `String.prototype.trim`, ...). This guide isn't really meant for modifying the compiler itself yet (eg `compiler/codegen.js`), as built-ins are ~easier to implement and more useful at the moment.
+
+I mostly presume decent JS knowledge, with some basic TS too but nothing complicated. Knowing low-level stuff generally (pointers, etc) and/or Wasm (bytecode) is also a plus but hopefully not required.
+
+<br>
+
+## Types
+
+Porffor has usual JS types (or at least the ones it supports), but also internal types for various reasons.
+
+### ByteString
+
+The most important and widely used internal type is ByteString (also called `bytestring` or `_bytestring` in code). Regular strings in Porffor are UTF-16 encoded, so each character uses 2 bytes. ByteStrings are special strings which are used when the characters in a string only use ASCII/LATIN-1 characters, so the lower byte of the UTF-16 characters are unused. Instead of wasting memory with all the unused memory, ByteStrings instead use 1 byte per character. This halves memory usage of such strings and also makes operating on them faster. The downside is that many Porffor built-ins have to be written twice, slightly different, for both `String` and `ByteString` types.
+
+### i32
+
+This is complicated internally but essentially, only use it for pointers. (This is not signed or unsigned, instead it is the Wasm valtype `i32` so the signage is ~instruction dependant).
+
+<br>
+
+## Pointers
+
+Pointers are the main (and most difficult) unique feature you ~need to understand when dealing with objects (arrays, strings, ...).
+
+We'll explain things per common usage you will likely need to know:
+
+## Commonly used Wasm code
+
+### Get a pointer
+
+```js
+Porffor.wasm`local.get ${foobar}`
+```
+
+Gets the pointer to the variable `foobar`. You don't really need to worry about how it works in detail, but essentially it gets the pointer as a number (type) instead of as the object it is.
+
+### Store a character in a ByteString
+
+```js
+Porffor.wasm.i32.store8(pointer, characterCode, 0, 4)
+```
+
+Stores the character code `characterCode` at the pointer `pointer` **for a ByteString**.[^1]
+
+### Store a character in a String
+
+```js
+Porffor.wasm.i32.store16(pointer, characterCode, 0, 4)
+```
+
+Stores the character code `characterCode` at the pointer `pointer` **for a String**.[^1]
+
+### Load a character from a ByteString
+
+```js
+Porffor.wasm.i32.load8_u(pointer, 0, 4)
+```
+
+Loads the character code at the pointer `pointer` **for a ByteString**.[^1]
+
+### Load a character from a String
+
+```js
+Porffor.wasm.i32.load16_u(pointer, 0, 4)
+```
+
+Loads the character code at the pointer `pointer` **for a String**.[^1]
+
+### Manually store the length of an object
+
+```js
+Porffor.wasm.i32.store(pointer, length, 0, 0)
+```
+
+Stores the length `length` at pointer `pointer`, setting the length of an object. This is mostly unneeded today as you can just do `obj.length = length`. [^2]
+
+<br>
+
+## Example
+
+Here is the code for `ByteString.prototype.toUpperCase()`:
+
+```ts
+export const ___bytestring_prototype_toUpperCase = (_this: bytestring) => {
+  const len: i32 = _this.length;
+
+  let out: bytestring = '';
+  Porffor.wasm.i32.store(out, len, 0, 0);
+
+  let i: i32 = Porffor.wasm`local.get ${_this}`,
+      j: i32 = Porffor.wasm`local.get ${out}`;
+
+  const endPtr: i32 = i + len;
+  while (i < endPtr) {
+    let chr: i32 = Porffor.wasm.i32.load8_u(i++, 0, 4);
+
+    if (chr >= 97) if (chr <= 122) chr -= 32;
+
+    Porffor.wasm.i32.store8(j++, chr, 0, 4);
+  }
+
+  return out;
+};
+```
+
+Now let's go through it section by section:
+
+```ts
+export const ___bytestring_prototype_toUpperCase = (_this: bytestring) => {
+```
+
+Here we define a built-in for Porffor. Notably:
+- We do not use `a.b.c`, instead we use `__a_b_c`
+- The ByteString type is actually `_bytestring`, as internal types have an extra `_` at the beginning (this is due to be fixed/simplified soon(tm))
+- We use a `_this` argument, as `this` does not exist in Porffor yet
+- We use an arrow function
+
+---
+
+```ts
+  const len: i32 = _this.length;
+
+  let out: bytestring = '';
+  Porffor.wasm.i32.store(out, len, 0, 0);
+```
+
+This sets up the `out` variable we are going to write to for the output of this function. We set the length in advance to be the same as `_this`, as `foo.length == foo.toLowerCase().length`, because we will later be manually writing to it using Wasm instrinsics, which will not update the length themselves.
+
+---
+
+```ts
+  let i: i32 = Porffor.wasm`local.get ${_this}`,
+      j: i32 = Porffor.wasm`local.get ${out}`;
+```
+
+Get the pointers for `_this` and `out` as `i32`s (~`number`s).
+
+---
+
+```ts
+  const endPtr: i32 = i + len;
+  while (i < endPtr) {
+```
+
+Set up an end target pointer as the pointer variable for `_this` plus the length of it. Loop below until that pointer reaches the end target, so we iterate through the entire string.
+
+---
+
+```ts
+    let chr: i32 = Porffor.wasm.i32.load8_u(i++, 0, 4);
+```
+
+Read the character (code) from the current `_this` pointer variable, and increment it so next iteration it reads the next character, etc.
+
+---
+
+```ts
+    if (chr >= 97) if (chr <= 122) chr -= 32;
+```
+
+If the character code is >= 97 (`a`) and <= 122 (`z`), decrease it by 32, making it an upper case character. eg: 97 (`a`) - 32 = 65 (`A`).
+
+---
+
+```ts
+    Porffor.wasm.i32.store8(j++, chr, 0, 4);
+```
+
+Store the character code into the `out` pointer variable, and increment it.
+
+<br>
+
+## Formatting/linting
+
+There is 0 setup for this (right now). You can try looking through the other built-ins files but do not worry about it a lot, I honestly do not mind going through and cleaning up after a PR as long as the code itself is good :^)
+
+[^1]: The `0, 4` args are necessary for the Wasm instruction, but you don't need to worry about them (`0` alignment, `4` byte offset for length).
+
+[^2]: The `0, 4` args are necessary for the Wasm instruction, but you don't need to worry about them (`0` alignment, `0` byte offset).

package/README.md

@@ -14,60 +14,75 @@ Porffor is primarily built from scratch, the only thing that is not is the parse
 Expect nothing to work! Only very limited JS is currently supported. See files in `bench` for examples.
 
 ### Setup
-1. Clone this repo (`git clone https://github.com/CanadaHonk/porffor.git`)
-2. `npm install` - for parser(s)
+**`npm install -g porffor`**. It's that easy (hopefully) :)
 
-### Running a file
-The repos comes with easy alias files for Unix and Windows, which you can use like so:
-- Unix: `./porf path/to/script.js`
-- Windows: `.\porf path/to/script.js`
+### Trying a REPL
+**`porf`**. Just run it with no script file argument.
 
-Please note that further examples below will just use `./porf`, you need to use `.\porf` on Windows. You can also swap out `node` in the alias to use another runtime like Deno (`deno run -A`) or Bun (`bun ...`), or just use it yourself (eg `node runner/index.js ...`, `bun runner/index.js ...`). Node and Bun should work great, Deno support is WIP.
+### Running a JS file
+**`porf path/to/script.js`**
 
-### Trying a REPL
-**`./porf`**. Just run it with no script file argument.
+### Compiling to Wasm
+**`porf wasm path/to/script.js out.wasm`**. Currently it does not use an import standard like WASI, so it is mostly unusable on its own.
 
 ### Compiling to native binaries
 > [!WARNING]
 > Compiling to native binaries uses [2c](#2c), Porffor's own Wasm -> C compiler, which is experimental.
 
-**`./porf native path/to/script.js out(.exe)`**. You can specify the compiler with `-compiler=clang/zig/gcc`, and which opt level to use with `-cO=O3` (`Ofast` by default). Output binaries are also stripped by default.
+**`porf native path/to/script.js out(.exe)`**. You can specify the compiler with `--compiler=clang/zig/gcc`, and which opt level to use with `--cO=O3` (`Ofast` by default). Output binaries are also stripped by default.
 
 ### Compiling to C
 > [!WARNING]
 > Compiling to C uses [2c](#2c), Porffor's own Wasm -> C compiler, which is experimental.
 
-**`./porf c path/to/script.js (out.c)`**. When not including an output file, it will be printed to stdout instead.
+**`porf c path/to/script.js (out.c)`**. When not including an output file, it will be printed to stdout instead.
+
+### Profiling a JS file
+> [!WARNING]
+> Very experimental WIP feature!
+
+**`porf profile path/to/script.js`**
+
+### Debugging a JS file
+> [!WARNING]
+> Very experimental WIP feature!
+
+**`porf debug path/to/script.js`**
+
+### Profiling the generated Wasm of a JS file
+> [!WARNING]
+> Very experimental WIP feature!
+
+**`porf debug-wasm path/to/script.js`**
 
-### Compiling to a Wasm binary
-**`./porf compile path/to/script.js out.wasm`**. Currently it does not use an import standard like WASI, so it is mostly unusable.
 
 ### Options
-- `-target=wasm|c|native` (default: `wasm`) to set target output (native compiles c output to binary, see args below)
-- `-target=c|native` only:
-  - `-o=out.c|out.exe|out` to set file to output c or binary
-- `-target=native` only:
-  - `-compiler=clang` to set compiler binary (path/name) to use to compile
-  - `-cO=O3` to set compiler opt argument
-- `-parser=acorn|@babel/parser|meriyah|hermes-parser` (default: `acorn`) to set which parser to use
-- `-parse-types` to enable parsing type annotations/typescript. if `-parser` is unset, changes default to `@babel/parser`. does not type check
-- `-opt-types` to perform optimizations using type annotations as compiler hints. does not type check
-- `-valtype=i32|i64|f64` (default: `f64`) to set valtype
+- `--parser=acorn|@babel/parser|meriyah|hermes-parser` (default: `acorn`) to set which parser to use
+- `--parse-types` to enable parsing type annotations/typescript. if `-parser` is unset, changes default to `@babel/parser`. does not type check
+- `--opt-types` to perform optimizations using type annotations as compiler hints. does not type check
+- `--valtype=i32|i64|f64` (default: `f64`) to set valtype
 - `-O0` to disable opt
 - `-O1` (default) to enable basic opt (simplify insts, treeshake wasm imports)
 - `-O2` to enable advanced opt (inlining). unstable
 - `-O3` to enable advanceder opt (precompute const math). unstable
-- `-no-run` to not run wasm output, just compile
-- `-opt-log` to log some opts
-- `-code-log` to log some codegen (you probably want `-funcs`)
-- `-regex-log` to log some regex
-- `-funcs` to log funcs
-- `-ast-log` to log AST
-- `-opt-funcs` to log funcs after opt
-- `-sections` to log sections as hex
-- `-opt-no-inline` to not inline any funcs
-- `-tail-call` to enable tail calls (experimental + not widely implemented)
-- `-compile-hints` to enable V8 compilation hints (experimental + doesn't seem to do much?)
+- `--no-run` to not run wasm output, just compile
+- `--opt-log` to log some opts
+- `--code-log` to log some codegen (you probably want `-funcs`)
+- `--regex-log` to log some regex
+- `--funcs` to log funcs
+- `--ast-log` to log AST
+- `--opt-funcs` to log funcs after opt
+- `--sections` to log sections as hex
+- `--opt-no-inline` to not inline any funcs
+- `--tail-call` to enable tail calls (experimental + not widely implemented)
+- `--compile-hints` to enable V8 compilation hints (experimental + doesn't seem to do much?)
+
+### Running in the repo
+The repo comes with easy alias files for Unix and Windows, which you can use like so:
+- Unix: `./porf path/to/script.js`
+- Windows: `.\porf path/to/script.js`
+
+Please note that further examples below will just use `./porf`, you need to use `.\porf` on Windows. You can also swap out `node` in the alias to use another runtime like Deno (`deno run -A`) or Bun (`bun ...`), or just use it yourself (eg `node runner/index.js ...`, `bun runner/index.js ...`). Node and Bun should work great, Deno support is WIP.
 
 ## Limitations
 - No full object support yet
@@ -190,7 +205,7 @@ Mostly for reducing size. I do not really care about compiler perf/time as long
 ### Traditional opts
 - Inlining functions (WIP, limited)
 - Inline const math ops
-- Tail calls (behind flag `-tail-call`)
+- Tail calls (behind flag `--tail-call`)
 
 ### Wasm transforms
 - `local.set`, `local.get` -> `local.tee`

package/asur/index.js

@@ -1244,7 +1244,7 @@ paused = _paused;`);
 });
 
 export const instantiate = async (binary, importImpls) => {
-  const _vm = process?.argv?.includes('-wasm-debug') ? await wasmDebugVm() : vm;
+  const _vm = process?.argv?.includes('--wasm-debug') ? await wasmDebugVm() : vm;
 
   const parsed = parse(binary);
   const exports = {};

package/compiler/assemble.js

@@ -154,7 +154,7 @@ export default (funcs, globals, tags, pages, data, flags) => {
 
   const exports = funcs.filter(x => x.export).map((x, i) => [ ...encodeString(x.name === 'main' ? 'm' : x.name), ExportDesc.func, x.index ]);
 
-  if (Prefs.alwaysMemory && pages.size === 0) pages.set('-always-memory', 0);
+  if (Prefs.alwaysMemory && pages.size === 0) pages.set('--always-memory', 0);
   if (optLevel === 0) pages.set('O0 precaution', 0);
 
   const usesMemory = pages.size > 0;

package/compiler/builtins/annexb_string.js

@@ -1,5 +1,5 @@
 export default () => {
-  let out = `// @porf -funsafe-no-unlikely-proto-checks -valtype=i32
+  let out = `// @porf --funsafe-no-unlikely-proto-checks --valtype=i32
 `;
 
   const annexB_noArgs = (a0, a1) => out += `

package/compiler/builtins/annexb_string.ts

@@ -1,4 +1,4 @@
-// @porf -funsafe-no-unlikely-proto-checks -valtype=i32
+// @porf --funsafe-no-unlikely-proto-checks --valtype=i32
 
 // todo: trimLeft, trimRight
 export const __String_prototype_trimLeft = (_this: string) => {

package/compiler/builtins/array.ts

@@ -1,4 +1,4 @@
-// @porf -funsafe-no-unlikely-proto-checks
+// @porf --funsafe-no-unlikely-proto-checks
 
 export const __Array_isArray = (x: unknown): boolean =>
   // Porffor.wasm`local.get ${x+1}` == Porffor.TYPES._array;

package/compiler/builtins/base64.ts

@@ -1,4 +1,4 @@
-// @porf -funsafe-no-unlikely-proto-checks -valtype=i32
+// @porf --funsafe-no-unlikely-proto-checks --valtype=i32
 
 // while (len >= 8) {
 //   Porffor.wasm`

package/compiler/builtins/crypto.ts

@@ -1,4 +1,4 @@
-// @porf -funsafe-no-unlikely-proto-checks -valtype=i32
+// @porf --funsafe-no-unlikely-proto-checks --valtype=i32
 
 export const __crypto_randomUUID = (): bytestring => {
   let bytes: bytestring = '................';