watr 1.1.1 → 1.3.0

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 (4) hide show
  1. package/package.json +1 -1
  2. package/readme.md +183 -145
  3. package/watr.js +568 -487
  4. package/watr.min.js +1 -1
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "watr",
3
- "version": "1.1.1",
3
+ "version": "1.3.0",
4
4
  "description": "Ligth & fast WAT compiler",
5
5
  "main": "watr.js",
6
6
  "type": "module",
package/readme.md CHANGED
@@ -1,145 +1,183 @@
1
- # watr
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.3 kb | 45,000
21
- wat-compiler | 6 kb | 2,500
22
- wabt | 300 kb | 3,100
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 intentionally prohibited in favor of explicit lispy structure.<br>
66
- Each instruction has prefix signature with parenthesized immediates and arguments.
67
-
68
- ```wast
69
- (func (result i32)
70
- i32.const 1 ;; ✘ stacked arguments
71
- drop
72
- i32.const 0
73
- i32.load offset=0 align=4 ;; ✘ ungrouped immediates
74
- )
75
-
76
- (func (result i32)
77
- (drop (i32.const 1)) ;; ✔ nested arguments
78
- (i32.load offset=0 align=4 (i32.const 0)) ;; ✔ grouped immediates
79
- )
80
- ```
81
-
82
- ```wast
83
- (local.get 0)
84
- if (result i32) ;; ✘ inline instruction
85
- (i32.const 1)
86
- end
87
-
88
- (local.get 0) ;; ✘ stacked argument
89
- (if (result i32)
90
- (i32.const 1)
91
- )
92
-
93
- (if (result i32) (local.get 0) ;; ✔ explicit signature
94
- (i32.const 1)
95
- )
96
- ```
97
-
98
- Numbers format limitation:
99
-
100
- * Int64 input format `0x7fffffffffffffff` is not supported (at the moment), only Int32.
101
- * Floating HEX like `0x1.fffffep+127` format is not supported.
102
- * Numeric placeholders `122_000.11_3_54E0_2_3` are not supported.
103
-
104
- <!--
105
- Main goal is to get very fluent with wasm text.
106
-
107
- Experiments:
108
-
109
- * [x] global read/write use in function
110
- * [x] scopes: refer, goto
111
- * [x] stack: understanding named and full references
112
- * [x] memory: reading/writing global memory
113
- * [x] memory: creating arrays on the go
114
- * [x] memory: passing pointer to a function
115
- * [x] benchmark array setting agains js loop
116
- → it's faster almost twice
117
-
118
- ## Useful links
119
-
120
- * [MDN: control flow](https://developer.mozilla.org/en-US/docs/WebAssembly/Reference/Control_flow)
121
- * [WASM reference manual](https://github.com/sunfishcode/wasm-reference-manual/blob/master/WebAssembly.md#loop)
122
-
123
- ## Refs
124
-
125
- * [mdn wasm text format](https://developer.mozilla.org/en-US/docs/WebAssembly/Understanding_the_text_format)
126
- * [wasm reference manual](https://github.com/sunfishcode/wasm-reference-manual/blob/master/WebAssembly.md)
127
- * [wabt source search](https://github.com/WebAssembly/wabt/search?p=5&q=then)
128
- * [wat control flow](https://developer.mozilla.org/en-US/docs/WebAssembly/Reference/Control_flow)
129
- * [wasm binary encoding](https://github.com/WebAssembly/design/blob/main/BinaryEncoding.md)
130
- * [ontouchstart wasm book](https://ontouchstart.pages.dev/chapter_wasm_binary)
131
- * [wat-compiler](https://github.com/stagas/wat-compiler/)
132
- * [hackernoon](https://web.archive.org/web/20210215171830/https://hackernoon.com/webassembly-binary-format-explained-part-2-hj1t33yp?source=rss)
133
- * [webassemblyjs](https://github.com/xtuc/webassemblyjs)
134
- * [chasm](https://github.com/ColinEberhardt/chasm/blob/master/src/encoding.ts)
135
- * [WebBS](https://github.com/j-s-n/WebBS)
136
- * [leb128a](https://github.com/minhducsun2002/leb128/blob/master/src/index.ts)
137
- * [leb128b](https://github.com/shmishtopher/wasm-LEB128/tree/master/esm)
138
-
139
- ## Alternatives
140
-
141
- * [wabt](https://www.npmjs.com/package/wabt) − port of WABT for the web, industry standard.
142
- * [wat-compiler](https://www.npmjs.com/package/wat-compiler) − compact alternative for WABT, limited support.
143
- -->
144
-
145
- <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>