watr 1.2.0 → 1.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/package.json +1 -1
  2. package/readme.md +183 -151
  3. package/watr.js +564 -564
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "watr",
3
- "version": "1.2.0",
3
+ "version": "1.3.1",
4
4
  "description": "Ligth & fast WAT compiler",
5
5
  "main": "watr.js",
6
6
  "type": "module",
package/readme.md CHANGED
@@ -1,151 +1,183 @@
1
- # watr [![Test](https://github.com/audio-lab/watr/actions/workflows/test.js.yml/badge.svg)](https://github.com/audio-lab/watr/actions/workflows/test.js.yml)
2
-
3
- > Light & fast WAT compiler.
4
-
5
- Provides bare minimum WAT to WASM compilation without unnecessary syntax complexities (see [limitations](#limitations)).<br/>
6
- Useful as WASM API layer for hi-level languages, also for dynamic (in-browser?) WASM compilation.
7
- <!--, eg. [sonl](https://github.com/audio-lab/sonl). -->
8
-
9
- <!-- See [REPL](https://audio-lab.github.io/watr/repl.html).-->
10
-
11
- <!--
12
- &nbsp; | watr | wat-compiler | wabt
13
- ---|---|---|---
14
- Size (gzipped) | 2.8kb | 6kb | 300kb
15
- Performance (op/s) | 45000 | 2500 | 3100
16
- -->
17
-
18
- &nbsp; | Size (gzipped) | Performance (op/s)
19
- ---|---|---
20
- watr | 3.8 kb | 1900
21
- wat-compiler | 6 kb | 135
22
- wabt | 300 kb | 250
23
-
24
- ## Usage
25
-
26
- ```js
27
- import wat from 'watr'
28
-
29
- // compile text to binary
30
- const buffer = wat(`(func
31
- (export "double") (param f64) (result f64)
32
- (f64.mul (local.get 0) (f64.const 2))
33
- )`)
34
-
35
- // create instance
36
- const module = new WebAssembly.Module(buffer)
37
- const instance = new WebAssembly.Instance(module)
38
-
39
- // use API
40
- const {double} = instance.exports
41
- double(108) // 216
42
- ```
43
-
44
- ## Compiler
45
-
46
- WAT tree can be compiled directly, bypassing text parsing:
47
-
48
- ```js
49
- import { compile } from 'watr'
50
-
51
- const buffer = compile([
52
- 'func', ['export', '"double"'], ['param', 'f64'], ['result', 'f64'],
53
- ['f64.mul', ['local.get', 0], ['f64.const', 2]]
54
- ])
55
- const module = new WebAssembly.Module(buffer)
56
- const instance = new WebAssembly.Instance(module)
57
- const {double} = instance.exports
58
-
59
- double(108) // 216
60
- ```
61
-
62
-
63
- ## Limitations
64
-
65
- Ambiguous syntax is prohibited in favor of explicit lispy structure.<br>
66
- Each instruction must have prefix signature with parenthesized immediates and arguments.<br>
67
- It may be supported, but discouraged.
68
-
69
- ```wast
70
- (func (result i32)
71
- i32.const 1 ;; ✘ stacked arguments
72
- drop
73
- i32.const 0
74
- i32.load offset=0 align=4 ;; ✘ ungrouped immediates
75
- )
76
-
77
- (func (result i32)
78
- (drop (i32.const 1)) ;; ✔ nested arguments
79
- (i32.load offset=0 align=4 (i32.const 0)) ;; ✔ grouped immediates
80
- )
81
- ```
82
-
83
- ```wast
84
- (local.get 0)
85
- if (result i32) ;; ✘ inline instruction
86
- (i32.const 1)
87
- end
88
-
89
- (local.get 0) ;; ✘ stacked argument
90
- (if (result i32)
91
- (i32.const 1)
92
- )
93
-
94
- (if (result i32) (local.get 0) ;; ✔ explicit signature
95
- (i32.const 1)
96
- )
97
- ```
98
-
99
- ```wast
100
- (f32.const 0x1.fffffep+127) ;; ✘ floating HEX (not supported)
101
- ```
102
-
103
- ```wast
104
- (global.set $pc (;(i32.const <new-pc>);)) ✘ default arguments must be explicit
105
- ```
106
-
107
- It may also miss some edge cases and nice error messages.
108
- For good REPL experience better use wabt.
109
-
110
- <!--
111
- Main goal is to get very fluent with wasm text.
112
-
113
- Experiments:
114
-
115
- * [x] global read/write use in function
116
- * [x] scopes: refer, goto
117
- * [x] stack: understanding named and full references
118
- * [x] memory: reading/writing global memory
119
- * [x] memory: creating arrays on the go
120
- * [x] memory: passing pointer to a function
121
- * [x] benchmark array setting agains js loop
122
- → it's faster almost twice
123
-
124
- ## Useful links
125
-
126
- * [MDN: control flow](https://developer.mozilla.org/en-US/docs/WebAssembly/Reference/Control_flow)
127
- * [WASM reference manual](https://github.com/sunfishcode/wasm-reference-manual/blob/master/WebAssembly.md#loop)
128
-
129
- ## Refs
130
-
131
- * [mdn wasm text format](https://developer.mozilla.org/en-US/docs/WebAssembly/Understanding_the_text_format)
132
- * [wasm reference manual](https://github.com/sunfishcode/wasm-reference-manual/blob/master/WebAssembly.md)
133
- * [wabt source search](https://github.com/WebAssembly/wabt/search?p=5&q=then)
134
- * [wat control flow](https://developer.mozilla.org/en-US/docs/WebAssembly/Reference/Control_flow)
135
- * [wasm binary encoding](https://github.com/WebAssembly/design/blob/main/BinaryEncoding.md)
136
- * [ontouchstart wasm book](https://ontouchstart.pages.dev/chapter_wasm_binary)
137
- * [wat-compiler](https://github.com/stagas/wat-compiler/)
138
- * [hackernoon](https://web.archive.org/web/20210215171830/https://hackernoon.com/webassembly-binary-format-explained-part-2-hj1t33yp?source=rss)
139
- * [webassemblyjs](https://github.com/xtuc/webassemblyjs)
140
- * [chasm](https://github.com/ColinEberhardt/chasm/blob/master/src/encoding.ts)
141
- * [WebBS](https://github.com/j-s-n/WebBS)
142
- * [leb128a](https://github.com/minhducsun2002/leb128/blob/master/src/index.ts)
143
- * [leb128b](https://github.com/shmishtopher/wasm-LEB128/tree/master/esm)
144
-
145
- ## Alternatives
146
-
147
- * [wabt](https://www.npmjs.com/package/wabt) − port of WABT for the web, industry standard.
148
- * [wat-compiler](https://www.npmjs.com/package/wat-compiler) − compact alternative for WABT, limited support.
149
- -->
150
-
151
- <p align=center><a href="https://github.com/krsnzd/license/">🕉</a></p>
1
+ # watr [![Test](https://github.com/audio-lab/watr/actions/workflows/test.js.yml/badge.svg)](https://github.com/audio-lab/watr/actions/workflows/test.js.yml)
2
+
3
+ > Light & fast WAT compiler.
4
+
5
+ Provides bare minimum WAT to WASM compilation.<br/>
6
+ Useful as WASM API layer, eg. for hi-level languages or for dynamic (in-browser?) compilation.
7
+ <!--, eg. [sonl](https://github.com/audio-lab/sonl). -->
8
+
9
+ <!-- See [REPL](https://audio-lab.github.io/watr/repl.html).-->
10
+
11
+ <!--
12
+ &nbsp; | watr | wat-compiler | wabt
13
+ ---|---|---|---
14
+ Size (gzipped) | 2.8kb | 6kb | 300kb
15
+ Performance (op/s) | 45000 | 2500 | 3100
16
+ -->
17
+
18
+ &nbsp; | Size (gzipped) | Performance (op/s)
19
+ ---|---|---
20
+ watr | 3.8 kb | 1900
21
+ [wat-compiler](https://github.com/stagas/wat-compiler) | 6 kb | 135
22
+ [wabt](https://github.com/AssemblyScript/wabt.js) | 300 kb | 250
23
+
24
+ ## Usage
25
+
26
+ ```js
27
+ import wat from 'watr'
28
+
29
+ // compile text to binary
30
+ const buffer = wat(`(func
31
+ (export "double") (param f64) (result f64)
32
+ (f64.mul (local.get 0) (f64.const 2))
33
+ )`)
34
+
35
+ // create instance
36
+ const module = new WebAssembly.Module(buffer)
37
+ const instance = new WebAssembly.Instance(module)
38
+
39
+ // use API
40
+ const {double} = instance.exports
41
+ double(108) // 216
42
+ ```
43
+
44
+ ## API
45
+
46
+ ### Parse
47
+
48
+ Parser converts input Wasm text string to syntax tree.
49
+
50
+ ```js
51
+ import { parse } from 'watr
52
+
53
+ parse(`(func (export "double") (param f64) (result f64) (f64.mul (local.get 0) (f64.const 2)))`)
54
+
55
+ // [
56
+ // 'func', ['export', '"double"'], ['param', 'f64'], ['result', 'f64'],
57
+ // ['f64.mul', ['local.get', 0], ['f64.const', 2]]
58
+ // ]
59
+ ```
60
+
61
+ ### Compile
62
+
63
+ Compiles Wasm tree or text into wasm binary. Lightweight alternative to [wabt/wat2wasm](https://github.com/WebAssembly/wabt).
64
+
65
+ ```js
66
+ import { compile } from 'watr'
67
+
68
+ const buffer = compile([
69
+ 'func', ['export', '"double"'], ['param', 'f64'], ['result', 'f64'],
70
+ ['f64.mul', ['local.get', 0], ['f64.const', 2]]
71
+ ])
72
+ const module = new WebAssembly.Module(buffer)
73
+ const instance = new WebAssembly.Instance(module)
74
+ const {double} = instance.exports
75
+
76
+ double(108) // 216
77
+ ```
78
+
79
+ ### Print
80
+
81
+ Format input Wasm text string or tree into minified or pretty form.
82
+
83
+ ```js
84
+ import { print } from 'watr'
85
+
86
+ const tree = [
87
+ 'func', ['export', '"double"'], ['param', 'f64'], ['result', 'f64'],
88
+ ['f64.mul', ['local.get', 0], ['f64.const', 2]]
89
+ ]
90
+
91
+ // minify (default)
92
+ const str = print(tree, {
93
+ indent: false,
94
+ newline: false,
95
+ pad: false
96
+ })
97
+ // (func (export "double")(param f64)(result f64)(f64.mul (local.get 0)(f64.const 2)))
98
+
99
+ // pretty-print
100
+ const str = print(tree, {
101
+ indent: ' ', // indentation step
102
+ newline: '\n', // new line
103
+ pad: '', // pad each newline with chars
104
+ })
105
+ // (func (export "double")
106
+ // (param f64) (result f64)
107
+ // (f64.mul
108
+ // (local.get 0)
109
+ // (f64.const 2)))
110
+ ```
111
+
112
+ <!--
113
+ ## Limitations
114
+
115
+ It may miss some edge cases and nice error messages.
116
+ For better REPL/dev experience use [wabt](https://github.com/AssemblyScript/wabt.js).
117
+
118
+
119
+ Ambiguous syntax is prohibited in favor of explicit lispy notation. Each instruction must have prefix signature with parenthesized immediates and arguments.
120
+
121
+ ```wast
122
+ (func (result i32)
123
+ i32.const 1 ;; ✘ stacked arguments
124
+ drop
125
+ i32.const 0
126
+ i32.load offset=0 align=4 ;; ✘ ungrouped immediates
127
+ )
128
+
129
+ (func (result i32)
130
+ (drop (i32.const 1)) ;; ✔ nested arguments
131
+ (i32.load offset=0 align=4 (i32.const 0)) ;; ✔ grouped immediates
132
+ )
133
+ ```
134
+
135
+ ```wast
136
+ (local.get 0) ;; ✘ stacked argument
137
+ if (result i32) ;; ✘ inline instruction
138
+ (i32.const 1)
139
+ end
140
+
141
+ (if (result i32) (local.get 0) ;; ✔ explicit signature
142
+ (i32.const 1)
143
+ )
144
+ ```
145
+
146
+ ```wast
147
+ (f32.const 0x1.fffffep+127) ;; ✘ floating HEX - not supported
148
+ ```
149
+ -->
150
+
151
+
152
+
153
+ ## Useful links
154
+
155
+ * [MDN: control flow](https://developer.mozilla.org/en-US/docs/WebAssembly/Reference/Control_flow)
156
+ * [WASM reference manual](https://github.com/sunfishcode/wasm-reference-manual/blob/master/WebAssembly.md#loop)
157
+ * [WASM binary encoding](https://github.com/WebAssembly/design/blob/main/BinaryEncoding.md)
158
+
159
+ <!--
160
+ ## Refs
161
+
162
+ * [mdn wasm text format](https://developer.mozilla.org/en-US/docs/WebAssembly/Understanding_the_text_format)
163
+ * [wasm reference manual](https://github.com/sunfishcode/wasm-reference-manual/blob/master/WebAssembly.md)
164
+ * [wabt source search](https://github.com/WebAssembly/wabt/search?p=5&q=then)
165
+ * [wat control flow](https://developer.mozilla.org/en-US/docs/WebAssembly/Reference/Control_flow)
166
+ * [ontouchstart wasm book](https://ontouchstart.pages.dev/chapter_wasm_binary)
167
+ * [wat-compiler](https://github.com/stagas/wat-compiler/)
168
+ * [hackernoon](https://web.archive.org/web/20210215171830/https://hackernoon.com/webassembly-binary-format-explained-part-2-hj1t33yp?source=rss)
169
+ * [webassemblyjs](https://github.com/xtuc/webassemblyjs)
170
+ * [chasm](https://github.com/ColinEberhardt/chasm/blob/master/src/encoding.ts)
171
+ * [WebBS](https://github.com/j-s-n/WebBS)
172
+ * [leb128a](https://github.com/minhducsun2002/leb128/blob/master/src/index.ts)
173
+ * [leb128b](https://github.com/shmishtopher/wasm-LEB128/tree/master/esm)
174
+
175
+ -->
176
+
177
+ ## Alternatives
178
+
179
+ * [wabt](https://www.npmjs.com/package/wabt) − port of WABT for the web, de-facto standard.
180
+ * [wat-compiler](https://www.npmjs.com/package/wat-compiler) − compact alternative for WABT, older brother of _watr_.
181
+ * [web49](https://github.com/FastVM/Web49)
182
+
183
+ <p align=center><a href="https://github.com/krsnzd/license/">🕉</a></p>