Module Visitor Pattern for manipulating BinaryModules

.vscode/settings.json

@@ -1,21 +1,21 @@
 {
-  "[javascript]": {
-    "editor.defaultFormatter": "biomejs.biome"
-  },
-  "[typescript]": {
-    "editor.defaultFormatter": "biomejs.biome"
-  },
-  "[javascriptreact]": {
-    "editor.defaultFormatter": "biomejs.biome"
-  },
-  "[typescriptreact]": {
-    "editor.defaultFormatter": "biomejs.biome"
-  },
-  "[gleam]": {
-    "editor.defaultFormatter": "gleam.gleam"
-  },
-  "typescript.tsdk": "./node_modules/typescript/lib",
-  "editor.tabSize": 2,
-  "editor.defaultFormatter": "biomejs.biome",
-  "editor.formatOnSave": true
+	"[javascript]": {
+		"editor.defaultFormatter": "biomejs.biome"
+	},
+	"[typescript]": {
+		"editor.defaultFormatter": "biomejs.biome"
+	},
+	"[javascriptreact]": {
+		"editor.defaultFormatter": "biomejs.biome"
+	},
+	"[typescriptreact]": {
+		"editor.defaultFormatter": "biomejs.biome"
+	},
+	"[gleam]": {
+		"editor.defaultFormatter": "gleam.gleam"
+	},
+	"typescript.tsdk": "./node_modules/typescript/lib",
+	"editor.tabSize": 2,
+	"editor.defaultFormatter": "biomejs.biome",
+	"editor.formatOnSave": false
 }

README.md

@@ -27,7 +27,7 @@ let assert Ok(add_module) =
     rec_type.func_type([val_type.i32, val_type.i32], [val_type.i32]),
   )
   // 4. Tell the wasm module that "function 0" has the type of "type 0"
-  |> module.add_function_type(type_idx_0)
+  |> module.append_function_type_index(type_idx_0)
   // 5. Add the body of the function to the module at function index 0
   |> module.add_code(
     // 5.a Function parameters and locals must be defined here: [..parameters, ..locals]
@@ -71,4 +71,11 @@ Some of these goals are personal,
 2. Be compatible with JavaScript and Gleam Targets
 3. Validate and Host WASM modules in a Spec Compliant way (not necessarily with performance in mind)
 4. (Personal) - Conquer the WebAssembly GC specification, validation, execution, and building
-5. Make a developer friendly interface for generating abstract WASM modules, manipulating code, and compile them to WASM binaries
+5. Make a developer friendly interface for generating abstract WASM modules, manipulating code, and compile them to WASM binaries
+
+## Maintainers
+
+Special Thanks to
+
+Rishit Chaudhary <rishitc@users.noreply.github.com>
+

gleam.toml

@@ -1,4 +1,4 @@
-name = "shinecoder"
+name = "shine_coder"
 version = "0.0.1"
 
 # Fill out these fields if you intend to generate HTML documentation or publish
@@ -17,6 +17,8 @@ gleam_stdlib = ">= 0.34.0 and < 2.0.0"
 ieee_float = ">= 1.0.0 and < 2.0.0"
 pprint = ">= 1.0.3 and < 2.0.0"
 simplifile = ">= 2.1.0 and < 3.0.0"
+shine_tree = ">= 0.0.3 and < 1.0.0"
+gleamy_structures = ">= 1.0.0 and < 2.0.0"
 
 [dev-dependencies]
 gleeunit = ">= 1.0.0 and < 2.0.0"

manifest.toml

@@ -4,17 +4,21 @@
 packages = [
   { name = "filepath", version = "1.0.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "filepath", source = "hex", outer_checksum = "EFB6FF65C98B2A16378ABC3EE2B14124168C0CE5201553DE652E2644DCFDB594" },
   { name = "glam", version = "2.0.1", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "glam", source = "hex", outer_checksum = "66EC3BCD632E51EED029678F8DF419659C1E57B1A93D874C5131FE220DFAD2B2" },
-  { name = "gleam_erlang", version = "0.25.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleam_erlang", source = "hex", outer_checksum = "054D571A7092D2A9727B3E5D183B7507DAB0DA41556EC9133606F09C15497373" },
-  { name = "gleam_stdlib", version = "0.39.0", build_tools = ["gleam"], requirements = [], otp_app = "gleam_stdlib", source = "hex", outer_checksum = "2D7DE885A6EA7F1D5015D1698920C9BAF7241102836CE0C3837A4F160128A9C4" },
+  { name = "gleam_erlang", version = "0.26.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleam_erlang", source = "hex", outer_checksum = "3DF72F95F4716883FA51396FB0C550ED3D55195B541568CAF09745984FD37AD1" },
+  { name = "gleam_stdlib", version = "0.40.0", build_tools = ["gleam"], requirements = [], otp_app = "gleam_stdlib", source = "hex", outer_checksum = "86606B75A600BBD05E539EB59FABC6E307EEEA7B1E5865AFB6D980A93BCB2181" },
+  { name = "gleamy_structures", version = "1.0.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleamy_structures", source = "hex", outer_checksum = "FF1B7600123B2B7C15E91BEBE6F417B4003928BF4282EF01A74A792B4ED6985A" },
   { name = "gleeunit", version = "1.2.0", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "gleeunit", source = "hex", outer_checksum = "F7A7228925D3EE7D0813C922E062BFD6D7E9310F0BEE585D3A42F3307E3CFD13" },
-  { name = "ieee_float", version = "1.0.0", build_tools = ["gleam"], requirements = ["gleam_erlang", "gleam_stdlib"], otp_app = "ieee_float", source = "hex", outer_checksum = "A9C8728DE26A8AA563FF2F49F8802C8875A41BAE86024B34A458C6EB821F1F00" },
+  { name = "ieee_float", version = "1.0.1", build_tools = ["gleam"], requirements = ["gleam_erlang", "gleam_stdlib"], otp_app = "ieee_float", source = "hex", outer_checksum = "F0585C3CF3F93634F40C8EAFBA7AEC98584E8B7B94D1F88C4C8EB4B51732F912" },
   { name = "pprint", version = "1.0.3", build_tools = ["gleam"], requirements = ["glam", "gleam_stdlib"], otp_app = "pprint", source = "hex", outer_checksum = "76BBB92E23D12D954BD452686543F29EDE8EBEBB7FC0ACCBCA66EEF276EC3A06" },
+  { name = "shine_tree", version = "0.0.6", build_tools = ["gleam"], requirements = ["gleam_stdlib"], otp_app = "shine_tree", source = "hex", outer_checksum = "AA365F6E10934F15B086CE9EB2ACF63B9992FA1F29ECBADA7A4B1E95241891E7" },
   { name = "simplifile", version = "2.1.0", build_tools = ["gleam"], requirements = ["filepath", "gleam_stdlib"], otp_app = "simplifile", source = "hex", outer_checksum = "BDD04F5D31D6D34E2EDFAEF0B68A6297AEC939888C3BFCE61133DE13857F6DA2" },
 ]
 
 [requirements]
 gleam_stdlib = { version = ">= 0.34.0 and < 2.0.0" }
+gleamy_structures = { version = ">= 1.0.0 and < 2.0.0" }
 gleeunit = { version = ">= 1.0.0 and < 2.0.0" }
 ieee_float = { version = ">= 1.0.0 and < 2.0.0" }
 pprint = { version = ">= 1.0.3 and < 2.0.0" }
+shine_tree = { version = ">= 0.0.3 and < 1.0.0" }
 simplifile = { version = ">= 2.1.0 and < 3.0.0" }

src/builder/expression.gleam

@@ -1,51 +1,43 @@
+import gleam/list
 import gleam/option.{type Option, None, Some}
-import internal/finger_tree.{type FingerTree}
 import internal/structure/types.{
   type BlockType, type Expr, type Instruction, Block, Expr, If, Loop,
 }
 
 type BlockDefinition {
   EmptyTop
-  OuterMostBlock(instructions: FingerTree(Instruction))
-  IfBlock(bt: BlockType, instructions: FingerTree(Instruction))
+  OuterMostBlock(instructions: List(Instruction))
+  IfBlock(bt: BlockType, instructions: List(Instruction))
   ElseBlock(
     bt: BlockType,
-    if_instructions: FingerTree(Instruction),
-    else_instructions: FingerTree(Instruction),
+    if_instructions: List(Instruction),
+    else_instructions: List(Instruction),
   )
-  LoopBlock(bt: BlockType, instructions: FingerTree(Instruction))
-  InlineBlock(bt: BlockType, instructions: FingerTree(Instruction))
+  LoopBlock(bt: BlockType, instructions: List(Instruction))
+  InlineBlock(bt: BlockType, instructions: List(Instruction))
 }
 
 pub opaque type ExpressionBuilder {
   ExpressionBuilder(
     result: Option(Expr),
     top: BlockDefinition,
-    block_stack: FingerTree(BlockDefinition),
+    block_stack: List(BlockDefinition),
   )
 }
 
 pub fn new() -> ExpressionBuilder {
-  ExpressionBuilder(None, OuterMostBlock(finger_tree.empty), finger_tree.empty)
+  ExpressionBuilder(None, OuterMostBlock([]), [])
 }
 
 pub fn begin_if(builder: ExpressionBuilder, bt: BlockType) -> ExpressionBuilder {
   let ExpressionBuilder(result, top, block_stack) = builder
-  ExpressionBuilder(
-    result,
-    IfBlock(bt, finger_tree.empty),
-    block_stack
-      |> finger_tree.push(top),
-  )
+  ExpressionBuilder(result, IfBlock(bt, []), [top, ..block_stack])
 }
 
 pub fn begin_else(builder: ExpressionBuilder) {
   case builder.top {
     IfBlock(bt, instructions) ->
-      ExpressionBuilder(
-        ..builder,
-        top: ElseBlock(bt, instructions, finger_tree.empty),
-      )
+      ExpressionBuilder(..builder, top: ElseBlock(bt, instructions, []))
     EmptyTop -> panic as "Stack state underflow"
     _ -> panic as "Invalid stack state, cannot start else block"
   }
@@ -55,103 +47,98 @@ pub fn begin_loop(
   builder: ExpressionBuilder,
   bt: BlockType,
 ) -> ExpressionBuilder {
-  ExpressionBuilder(
-    builder.result,
-    LoopBlock(bt, finger_tree.empty),
-    builder.block_stack
-      |> finger_tree.push(builder.top),
-  )
+  ExpressionBuilder(builder.result, LoopBlock(bt, []), [
+    builder.top,
+    ..builder.block_stack
+  ])
 }
 
 pub fn begin_block(
   builder: ExpressionBuilder,
   bt: BlockType,
 ) -> ExpressionBuilder {
-  ExpressionBuilder(
-    builder.result,
-    InlineBlock(bt, finger_tree.empty),
-    builder.block_stack
-      |> finger_tree.push(builder.top),
-  )
+  ExpressionBuilder(builder.result, InlineBlock(bt, []), [
+    builder.top,
+    ..builder.block_stack
+  ])
 }
 
 pub fn end(builder: ExpressionBuilder) {
   case builder {
     ExpressionBuilder(None, OuterMostBlock(instructions), block_stack)
-      if block_stack == finger_tree.empty
-    -> Ok(ExpressionBuilder(Some(Expr(instructions)), EmptyTop, block_stack))
+      if block_stack == []
+    ->
+      Ok(ExpressionBuilder(
+        Some(Expr(instructions |> list.reverse)),
+        EmptyTop,
+        block_stack,
+      ))
     ExpressionBuilder(None, IfBlock(bt, if_instructions), block_stack) ->
-      do_append(block_stack, If(bt, if_instructions, None))
+      do_append(block_stack, If(bt, if_instructions |> list.reverse, None))
     ExpressionBuilder(
       None,
       ElseBlock(bt, if_instructions, else_instructions),
       block_stack,
     ) ->
-      do_append(block_stack, If(bt, if_instructions, Some(else_instructions)))
+      do_append(
+        block_stack,
+        If(
+          bt,
+          if_instructions |> list.reverse,
+          Some(else_instructions |> list.reverse),
+        ),
+      )
     ExpressionBuilder(None, LoopBlock(bt, loop_instructions), block_stack) ->
-      do_append(block_stack, Loop(bt, Expr(loop_instructions)))
+      do_append(block_stack, Loop(bt, Expr(loop_instructions |> list.reverse)))
     ExpressionBuilder(None, InlineBlock(bt, block_instructions), block_stack) ->
-      do_append(block_stack, Block(bt, Expr(block_instructions)))
+      do_append(
+        block_stack,
+        Block(bt, Expr(block_instructions |> list.reverse)),
+      )
     ExpressionBuilder(_, EmptyTop, _) -> Error("Stack state underflow")
     _ -> Error("Invalid stack state")
   }
 }
 
-fn do_append(
-  next_stack: FingerTree(BlockDefinition),
-  next_instruction: Instruction,
-) {
-  case next_stack |> finger_tree.pop() {
-    Ok(#(OuterMostBlock(outer_instructions), next_stack)) ->
+fn do_append(next_stack: List(BlockDefinition), next_instruction: Instruction) {
+  case next_stack {
+    [OuterMostBlock(outer_instructions), ..next_stack] ->
       Ok(ExpressionBuilder(
         None,
-        OuterMostBlock(
-          outer_instructions
-          |> finger_tree.push(next_instruction),
-        ),
+        OuterMostBlock([next_instruction, ..outer_instructions]),
         next_stack,
       ))
 
-    Ok(#(IfBlock(outer_bt, outer_if_instructions), next_stack)) ->
+    [IfBlock(outer_bt, outer_if_instructions), ..next_stack] ->
       Ok(ExpressionBuilder(
         None,
-        IfBlock(
-          outer_bt,
-          outer_if_instructions |> finger_tree.push(next_instruction),
-        ),
+        IfBlock(outer_bt, [next_instruction, ..outer_if_instructions]),
         next_stack,
       ))
-    Ok(#(
+    [
       ElseBlock(outer_bt, outer_if_instructions, outer_else_instructions),
-      next_stack,
-    )) ->
+      ..next_stack
+    ] ->
       Ok(ExpressionBuilder(
         None,
-        ElseBlock(
-          outer_bt,
-          outer_if_instructions,
-          outer_else_instructions |> finger_tree.push(next_instruction),
-        ),
+        ElseBlock(outer_bt, outer_if_instructions, [
+          next_instruction,
+          ..outer_else_instructions
+        ]),
         next_stack,
       ))
 
-    Ok(#(LoopBlock(outer_bt, outer_instructions), next_stack)) ->
+    [LoopBlock(outer_bt, outer_instructions), ..next_stack] ->
       Ok(ExpressionBuilder(
         None,
-        LoopBlock(
-          outer_bt,
-          outer_instructions |> finger_tree.push(next_instruction),
-        ),
+        LoopBlock(outer_bt, [next_instruction, ..outer_instructions]),
         next_stack,
       ))
 
-    Ok(#(InlineBlock(outer_bt, outer_instructions), next_stack)) ->
+    [InlineBlock(outer_bt, outer_instructions), ..next_stack] ->
       Ok(ExpressionBuilder(
         None,
-        InlineBlock(
-          outer_bt,
-          outer_instructions |> finger_tree.push(next_instruction),
-        ),
+        InlineBlock(outer_bt, [next_instruction, ..outer_instructions]),
         next_stack,
       ))
     _ -> Error("Stack state underflow")
@@ -163,35 +150,31 @@ pub fn push(builder: ExpressionBuilder, inst: Instruction) {
     OuterMostBlock(instructions) ->
       ExpressionBuilder(
         None,
-        OuterMostBlock(instructions |> finger_tree.push(inst)),
+        OuterMostBlock([inst, ..instructions]),
         builder.block_stack,
       )
     IfBlock(bt, instructions) ->
       ExpressionBuilder(
         None,
-        IfBlock(bt, instructions |> finger_tree.push(inst)),
+        IfBlock(bt, [inst, ..instructions]),
         builder.block_stack,
       )
     ElseBlock(bt, if_instructions, else_instructions) ->
       ExpressionBuilder(
         None,
-        ElseBlock(
-          bt,
-          if_instructions,
-          else_instructions |> finger_tree.push(inst),
-        ),
+        ElseBlock(bt, if_instructions, else_instructions |> list.append([inst])),
         builder.block_stack,
       )
     LoopBlock(bt, instructions) ->
       ExpressionBuilder(
         None,
-        LoopBlock(bt, instructions |> finger_tree.push(inst)),
+        LoopBlock(bt, [inst, ..instructions]),
         builder.block_stack,
       )
     InlineBlock(bt, instructions) ->
       ExpressionBuilder(
         None,
-        InlineBlock(bt, instructions |> finger_tree.push(inst)),
+        InlineBlock(bt, [inst, ..instructions]),
         builder.block_stack,
       )
     _ -> panic as "Expression completed, cannot push instruction"
@@ -200,9 +183,8 @@ pub fn push(builder: ExpressionBuilder, inst: Instruction) {
 
 pub fn end_unwrap(builder) {
   case builder {
-    ExpressionBuilder(None, OuterMostBlock(instructions), stack)
-      if stack == finger_tree.empty
-    -> Expr(instructions)
+    ExpressionBuilder(None, OuterMostBlock(instructions), stack) if stack == [] ->
+      Expr(instructions |> list.reverse)
     _ -> panic as "Unable to unwrap, invalid expression state"
   }
 }

src/builder/instructions/README.md

@@ -0,0 +1,17 @@
+# WASM Instructions
+
+Regarding the WebAssembly specification, it might be difficult to understand the purpose of each opcode. The following sections can help you find the information you are looking for.
+
+## Instructions Structure
+
+- [Numeric Instructions](https://webassembly.github.io/gc/core/syntax/instructions.html#numeric-instructions)
+- [Vector (v128) Instructions](https://webassembly.github.io/gc/core/syntax/instructions.html#vector-instructions)
+- [Reference Instructions](https://webassembly.github.io/gc/core/syntax/instructions.html)
+- [Aggregate Instructions](https://webassembly.github.io/gc/core/syntax/instructions.html#aggregate-instructions)
+- [Parametric Instructions](https://webassembly.github.io/gc/core/syntax/instructions.html#parametric-instructions)
+- [Variable Instructions](https://webassembly.github.io/gc/core/syntax/instructions.html#variable-instructions)
+- [Table Instructions](https://webassembly.github.io/gc/core/syntax/instructions.html#table-instructions)
+- [Memory Instructions](https://webassembly.github.io/gc/core/syntax/instructions.html#memory-instructions)
+- [Control Instructions](https://webassembly.github.io/gc/core/syntax/instructions.html#control-instructions)
+
+These instructions are constructed while using the `ExpressionBuilder` api, which only help build the binary representation.

src/builder/instructions/any.gleam

@@ -1,6 +1,7 @@
 import builder/expression.{type ExpressionBuilder}
 import internal/structure/types.{AnyConvertExtern}
 
+/// Convert an external value to an anyref
 pub fn convert_extern(builder: ExpressionBuilder) {
   builder
   |> expression.push(AnyConvertExtern)