complex tuple expressions supported

Reviewed-on: #11

Changelog.md

@@ -1,5 +1,29 @@
 # Changelog
 
+[0.4.7]
+
+- Added support for Windows CRLF endings
+
+[0.4.6]
+
+- Fixed bug in compiler where you were unable to assign a `const` value to
+  a `let` variable
+
+[0.4.5]
+
+- Fixed issue where after clicking "Cancel" on the IC10 Editor, the side-by-side
+  IC10 output would no longer update with highlighting or code updates.
+- Added ability to live-reload the mod while developing using the `ScriptEngine`
+  mod from BepInEx
+  - This required adding in cleanup code to cleanup references to the Rust DLL
+    before destroying the mod instance.
+- Added BepInEx debug logging. This will ONLY show if you have debug logs
+  enabled in the BepInEx configuration file.
+
+[0.4.4]
+
+- Added Stationpedia docs back after removing all harmony patches from the mod
+
 [0.4.3]
 
 - Removed references to the `Mod` class from SLP. This was the root of the multiplayer

ModData/About/About.xml

@@ -2,11 +2,11 @@
 <ModMetadata xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
   <Name>Slang</Name>
   <Author>JoeDiertay</Author>
-  <Version>0.4.3</Version>
+  <Version>0.4.7</Version>
   <Description>
 [h1]Slang: High-Level Programming for Stationeers[/h1]
 
-Stop writing assembly. Start writing code.
+Iterate faster. Stop writing assembly. Start writing code.
 
 Slang (Stationeers Language) brings modern programming to Stationeers. It allows you to write scripts using a familiar C-style syntax (variables, functions, if/else, loops) directly in the in-game editor. When you hit confirm, Slang compiles your code into IC10 instantly.
 
@@ -15,7 +15,7 @@ Slang (Stationeers Language) brings modern programming to Stationeers. It allows
 [h2]Features[/h2]
 [list]
 [*] [b]In-Game Compilation:[/b] No external tools needed. Write Slang directly in the IC editor.
-[*] [b]No More Register Juggling:[/b] Define variables with let (e.g., let temp = 300). The compiler manages r0-r15 for you.
+[*] [b]No More Register Juggling:[/b] Define variables with let (e.g., let temp = 200c). The compiler manages r0-r15 for you.
 [*] [b]Control Flow:[/b] Write readable logic with if, else, while, loop, break, and continue.
 [*] [b]Functions:[/b] Create reusable code blocks with arguments.
 [*] [b]Smart Editor:[/b] Get real-time syntax highlighting and error checking (red text) as you type.
@@ -53,14 +53,13 @@ loop {
 [h2]Known Issues (Beta)[/h2]
 [list]
 [*] [b]Stack Access:[/b] Direct stack memory access is disabled to prevent conflicts with the compiler's internal memory management. A workaround is being planned.
-[*] [b]Documentation:[/b] In-game tooltips for syscalls (like load, set) are WIP. Check the "Slang" entry in the Stationpedia (F1) for help.
+[*] [b]Documentation:[/b] In-game tooltips for syscalls (like load, set) are WIP. Check the "Slang" entry in the Stationpedia (F1) for help, or checkout [url=https://github.com/dbidwell94/stationeers_lang/blob/master/docs/getting-started.md]The Docs[/url] for guides on how to get started.
 [/list]
 
 [h2]Planned Features[/h2]
 [list]
 [*] Enhanced LSP features (Autocomplete, Go to Definition).
 [*] Full feature parity with all IC10 instructions.
-[*] Tutorials and beginner script examples.
 [/list]
 
 [h2]FAQ[/h2]
@@ -70,10 +69,18 @@ A: The Slang compiler is built in Rust for performance and reliability. It is co
 [b]Q: Is this compatible with my current save?[/b]
 A: Yes! Slang does not modify any existing IC10 code, it is only a compiler. As a matter of fact: if you wish to stop using Slang at any time, your compiled IC10 will still exist on the chip. However: Slang adds a comment at the bottom of your compiled IC10 which is a GZIP and base64 encoded version of your Slang source code. This might break line limits with Slang not installed. If you wish to no longer use Slang, I recommend you remove this comment from the source code after uninstalling Slang.
 
+[b]Q: Does this modify the in-game scripting language[/b]
+A: No! Slang compiles directly to IC10. Any valid Slang file will produce valid IC10. The goal of this mod is twofold:
+[list]
+[*] Allow experienced users to quickly iterate on their scripts to get back into base upgrades faster
+[*] Allow newcomers who already know C-style languages (JS/C#/Java/Rust/C/etc) to see how it maps to IC10 so they can get to understand IC10 better
+[/list]
+
 [h2]Useful Links[/h2]
 [url=https://github.com/dbidwell94/stationeers_lang]Source Code on GitHub[/url]
 [url=https://discord.gg/stationeers]Stationeers Official Discord[/url]
 [url=https://discord.gg/M4sCfYMacs]Stationeers Modding Discord[/url]
+[url=https://github.com/dbidwell94/stationeers_lang/blob/master/docs/getting-started.md]Getting Started Guide[/url]
   </Description>
   <ChangeLog xsi:nil="true" />
   <WorkshopHandle>3619985558</WorkshopHandle>
@@ -116,5 +123,7 @@ A: Yes! Slang does not modify any existing IC10 code, it is only a compiler. As
         See: https://github.com/StationeersLaunchPad/StationeersLaunchPad
 
         Source Code: https://github.com/dbidwell94/stationeers_lang
+
+        Documentation: https://github.com/dbidwell94/stationeers_lang/blob/master/docs/getting-started.md
         ]]></InGameDescription>
 </ModMetadata>

README.md

@@ -1,30 +1,45 @@
-# Stationeers Language (slang)
+# Slang Language Documentation
 
-This is an ambitious attempt at creating:
+Slang is a high-level programming language that compiles to IC10 assembly for [Stationeers](https://store.steampowered.com/app/544550/Stationeers/).
+It provides a familiar C-like syntax while targeting the limited instruction set
+of in-game IC10.
 
-- A new programming language (slang)
-- A compiler to translate slang -> IC10
-- A mod to allow direct input of slang in the in-game script editor to
-  automatically compile to IC10 before running
+## Quick Links
 
-This project currently outputs 3 files:
+- [Getting Started](docs/getting-started.md) - Installation and first program
+- [Language Reference](docs/language-reference.md) - Complete syntax guide
+- [Built-in Functions](docs/builtins.md) - System calls and math functions
+- [Examples](docs/examples.md) - Real-world code samples
 
-- A Linux CLI
-- A Windows CLI
-- A Windows FFI dll
-  - Contains a single function: `compile_from_string`
+## Overview
 
-The aim of this project is to lower the amount of time it takes to code simple
-scripts in Stationeers so you can get back to engineering atmospherics or
-whatever you are working on. This project is NOT meant to fully replace IC10.
-Obviously hand-coded assembly written by an experienced programmer is more
-optimized and smaller than something that a C compiler will spit out. This is
-the same way. It WILL produce valid IC10, but for large complicated projects it
-might produce over the allowed limit of lines the in-game editor supports.
+Slang aims to reduce the time spent writing IC10 assembly by providing:
 
-Current Unknowns
+- **Familiar syntax** - C-like declarations, control flow, and expressions
+- **Device abstraction** - Named device bindings with property access
+- **Automatic register allocation** - No manual register management
+- **Built-in functions** - Math operations and device I/O as function calls
+- **Temperature literals** - Native support for Celsius, Fahrenheit, and Kelvin
 
-- Should I support a configurable script line length in-game to allow larger
-  scripts to be saved?
-- Should compilation be "behind the scenes" (in game editor will ALWAYS be what
-  you put in. IC10 will be IC10, slang will be slang)
+## Example
+
+```rust
+device gasSensor = "d0";
+device airCon = "d1";
+
+const TARGET_TEMP = 20c;
+
+loop {
+    yield();
+    airCon.On = gasSensor.Temperature > TARGET_TEMP;
+}
+```
+
+This compiles to IC10 that monitors temperature and controls an air
+conditioner.
+
+## Project Status
+
+Slang is under active development. It may produce suboptimal code for complex programs.
+It is not a replacement for IC10, for performance-critical or large scripts,
+hand-written IC10 may still be preferred.

csharp_mod/Formatter.cs

@@ -6,7 +6,6 @@ using System.Linq;
 using System.Threading;
 using System.Threading.Tasks;
 using StationeersIC10Editor;
-using StationeersIC10Editor.IC10;
 
 public class SlangFormatter : ICodeFormatter
 {
@@ -14,8 +13,25 @@ public class SlangFormatter : ICodeFormatter
     private CancellationTokenSource? _lspCancellationToken;
     private object _tokenLock = new();
 
-    protected Editor? Ic10Editor = null;
-    private IC10CodeFormatter iC10CodeFormatter = new IC10CodeFormatter();
+    protected Editor? __Ic10Editor = null;
+
+    protected Editor Ic10Editor
+    {
+        get
+        {
+            if (__Ic10Editor == null)
+            {
+                var tab = Editor.ParentTab;
+                tab.ClearExtraEditors();
+                __Ic10Editor = new Editor(Editor.KeyHandler);
+                Ic10Editor.IsReadOnly = true;
+                tab.AddEditor(__Ic10Editor);
+            }
+
+            return __Ic10Editor;
+        }
+    }
+
     private string ic10CompilationResult = "";
     private List<SourceMapEntry> ic10SourceMap = new();
 
@@ -80,7 +96,7 @@ public class SlangFormatter : ICodeFormatter
     {
         if (!Marshal.CompileFromString(RawText, out var compilationResult, out var sourceMap))
         {
-            return "Compilation Error";
+            return "# Compilation Error";
         }
 
         return compilationResult + $"\n{EncodeSource(RawText, SLANG_SRC)}";
@@ -118,6 +134,10 @@ public class SlangFormatter : ICodeFormatter
         return styledLine;
     }
 
+    /// <summary>
+    /// This handles calling the `HandleLsp` function by creating a new `CancellationToken` and
+    /// cancelling the current call if applicable.
+    /// </summary>
     private void HandleCodeChanged()
     {
         CancellationToken token;
@@ -133,6 +153,11 @@ public class SlangFormatter : ICodeFormatter
         _ = HandleLsp(inputSrc, token);
     }
 
+    /// <summary>
+    /// Takes a copy of the current source code and sends it to the Rust compiler in a background thread
+    /// to get diagnostic data. This also handles getting a compilation response of optimized IC10 for the
+    /// side-by-side IC10Editor to show with sourcemap highlighting.
+    /// </summary>
     private async Task HandleLsp(string inputSrc, CancellationToken cancellationToken)
     {
         try
@@ -165,24 +190,21 @@ public class SlangFormatter : ICodeFormatter
                 return;
             }
 
-            var (compilationSuccess, compiled, sourceMap) = await Task.Run(
-                () =>
-                {
-                    var successful = Marshal.CompileFromString(
-                        inputSrc,
-                        out var compiled,
-                        out var sourceMap
-                    );
-                    return (successful, compiled, sourceMap);
-                },
-                cancellationToken
-            );
+            var (compilationSuccess, compiled, sourceMap) = await Task.Run(() =>
+            {
+                var successful = Marshal.CompileFromString(
+                    inputSrc,
+                    out var compiled,
+                    out var sourceMap
+                );
+                return (successful, compiled, sourceMap);
+            });
 
             if (compilationSuccess)
             {
                 ic10CompilationResult = compiled;
                 ic10SourceMap = sourceMap;
-                UpdateIc10Formatter();
+                UpdateIc10Content(Ic10Editor);
             }
         }
         catch (OperationCanceledException) { }
@@ -192,22 +214,24 @@ public class SlangFormatter : ICodeFormatter
         }
     }
 
+    /// <summary>
+    /// Updates the underlying code in the IC10 Editor, after which will call `UpdateIc10Formatter` to
+    /// update highlighting of relavent fields.
+    /// </summary>
+    private void UpdateIc10Content(Editor editor)
+    {
+        editor.ResetCode(ic10CompilationResult);
+        UpdateIc10Formatter();
+    }
+
+    // This runs on the main thread. This function ONLY updates the highlighting of the IC10 code.
+    // If you need to update the code in the editor itself, you should use `UpdateIc10Content`.
     private void UpdateIc10Formatter()
     {
-        var tab = Editor.ParentTab;
-        if (Ic10Editor == null)
-        {
-            iC10CodeFormatter = new IC10CodeFormatter();
-            Ic10Editor = new Editor(Editor.KeyHandler);
-            Ic10Editor.IsReadOnly = true;
-            iC10CodeFormatter.Editor = Ic10Editor;
-        }
-
-        if (tab.Editors.Count < 2)
-        {
-            tab.AddEditor(Ic10Editor);
-        }
-
+        // Bail if our backing field is null. We don't want to set the field in this function. It
+        // runs way too much and we might not even have source code to use.
+        if (__Ic10Editor == null)
+            return;
         var caretPos = Editor.CaretPos.Line;
 
         // get the slang sourceMap at the current editor line
@@ -215,10 +239,6 @@ public class SlangFormatter : ICodeFormatter
             entry.SlangSource.StartLine == caretPos || entry.SlangSource.EndLine == caretPos
         );
 
-        // extract the current "context" of the ic10 compilation. The current Slang source line
-        // should be directly next to the compiled IC10 source line, and we should highlight the
-        // IC10 code that directly represents the Slang source
-
         Ic10Editor.ResetCode(ic10CompilationResult);
 
         if (lines.Count() < 1)
@@ -245,7 +265,11 @@ public class SlangFormatter : ICodeFormatter
         };
     }
 
-    // This runs on the Main Thread
+    /// <summary>
+    /// Takes diagnostics from the Rust FFI compiler and applies it as semantic tokens to the
+    /// source in this editor.
+    /// This runs on the Main Thread
+    /// </summary>
     private void ApplyDiagnostics(Dictionary<uint, IGrouping<uint, Diagnostic>> dict)
     {
         HashSet<uint> linesToRefresh;

csharp_mod/Marshal.cs

@@ -67,7 +67,9 @@ public static class Marshal
         try
         {
             _libraryHandle = LoadLibrary(ExtractNativeLibrary(Ffi.RustLib));
+            L.Debug("Rust DLL loaded successfully. Enjoy native speed compilations!");
             CodeFormatters.RegisterFormatter("Slang", typeof(SlangFormatter), true);
+
             return true;
         }
         catch (Exception ex)
@@ -91,8 +93,13 @@ public static class Marshal
 
         try
         {
-            FreeLibrary(_libraryHandle);
+            CodeFormatters.RegisterFormatter("Slang", typeof(PlainTextFormatter), true);
+            if (!FreeLibrary(_libraryHandle))
+            {
+                L.Warning("Unable to free Rust library");
+            }
             _libraryHandle = IntPtr.Zero;
+            L.Debug("Rust DLL library freed");
             return true;
         }
         catch (Exception ex)
@@ -191,9 +198,9 @@ public static class Marshal
 
         Assembly assembly = Assembly.GetExecutingAssembly();
 
-        using (Stream stream = assembly.GetManifestResourceStream(libName))
+        using (Stream resourceStream = assembly.GetManifestResourceStream(libName))
         {
-            if (stream == null)
+            if (resourceStream == null)
             {
                 L.Error(
                     $"{libName} not found. This means it was not embedded in the mod. Please contact the mod author!"
@@ -201,18 +208,85 @@ public static class Marshal
                 return "";
             }
 
+            // Check if file exists and contents are identical to avoid overwriting locked files
+            if (File.Exists(destinationPath))
+            {
+                try
+                {
+                    using (
+                        FileStream fileStream = new FileStream(
+                            destinationPath,
+                            FileMode.Open,
+                            FileAccess.Read,
+                            FileShare.ReadWrite
+                        )
+                    )
+                    {
+                        if (resourceStream.Length == fileStream.Length)
+                        {
+                            if (StreamsContentsAreEqual(resourceStream, fileStream))
+                            {
+                                L.Debug(
+                                    $"DLL {libName} already exists and matches. Skipping extraction."
+                                );
+                                return destinationPath;
+                            }
+                        }
+                    }
+                }
+                catch (IOException ex)
+                {
+                    L.Warning(
+                        $"Could not verify existing {libName}, attempting overwrite. {ex.Message}"
+                    );
+                }
+            }
+
+            resourceStream.Position = 0;
+
+            // Attempt to overwrite if missing or different
             try
             {
                 using (FileStream fileStream = new FileStream(destinationPath, FileMode.Create))
                 {
-                    stream.CopyTo(fileStream);
+                    resourceStream.CopyTo(fileStream);
                 }
                 return destinationPath;
             }
             catch (IOException e)
             {
-                L.Warning($"Could not overwrite {libName} (it might be in use): {e.Message}");
-                return "";
+                // If we fail here, the file is likely locked.
+                // However, if we are here, it means the file is DIFFERENT or we couldn't read it.
+                // As a fallback for live-reload, we can try returning the path anyway
+                // assuming the existing locked file might still work.
+                L.Warning(
+                    $"Could not overwrite {libName} (it might be in use): {e.Message}. Attempting to use existing file."
+                );
+                return destinationPath;
+            }
+        }
+    }
+
+    private static bool StreamsContentsAreEqual(Stream stream1, Stream stream2)
+    {
+        const int bufferSize = 4096;
+        byte[] buffer1 = new byte[bufferSize];
+        byte[] buffer2 = new byte[bufferSize];
+
+        while (true)
+        {
+            int count1 = stream1.Read(buffer1, 0, bufferSize);
+            int count2 = stream2.Read(buffer2, 0, bufferSize);
+
+            if (count1 != count2)
+                return false;
+            if (count1 == 0)
+                return true;
+
+            for (int i = 0; i < count1; i++)
+            {
+                if (buffer1[i] != buffer2[i])
+                    return false;
             }
         }
     }

csharp_mod/Patches.cs

@@ -0,0 +1,18 @@
+namespace Slang;
+
+using Assets.Scripts.UI;
+using HarmonyLib;
+
+[HarmonyPatch]
+public static class SlangPatches
+{
+    [HarmonyPatch(typeof(Stationpedia), nameof(Stationpedia.Regenerate))]
+    [HarmonyPostfix]
+    public static void Stationpedia_Regenerate()
+    {
+        foreach (var page in Marshal.GetSlangDocs())
+        {
+            Stationpedia.Register(page);
+        }
+    }
+}

csharp_mod/Plugin.cs

@@ -1,4 +1,3 @@
-using System.Text.RegularExpressions;
 using BepInEx;
 using HarmonyLib;
 
@@ -40,43 +39,32 @@ namespace Slang
     {
         public const string PluginGuid = "com.biddydev.slang";
         public const string PluginName = "Slang";
-        public const string PluginVersion = "0.4.3";
+        public const string PluginVersion = "0.4.7";
 
-        private Harmony? _harmony;
+        private static Harmony? _harmony;
 
-        private static Regex? _slangSourceCheck = null;
-
-        private static Regex SlangSourceCheck
-        {
-            get
-            {
-                if (_slangSourceCheck is null)
-                {
-                    _slangSourceCheck = new Regex(@"[;{}()]|\b(let|fn|device)\b|\/\/");
-                }
-
-                return _slangSourceCheck;
-            }
-        }
-
-        public static bool IsSlangSource(ref string input)
-        {
-            return SlangSourceCheck.IsMatch(input);
-        }
-
-        private void Awake()
+        public void Awake()
         {
             L.SetLogger(Logger);
-            this._harmony = new Harmony(PluginGuid);
+            _harmony = new Harmony(PluginGuid);
 
             // If we failed to load the compiler, bail from the rest of the patches. It won't matter,
             // as the compiler itself has failed to load.
             if (!Marshal.Init())
             {
+                L.Error("Marshal failed to init");
                 return;
             }
 
-            this._harmony.PatchAll();
+            _harmony.PatchAll();
+            L.Debug("Ran Harmony patches");
+        }
+
+        public void OnDestroy()
+        {
+            Marshal.Destroy();
+            _harmony?.UnpatchSelf();
+            L.Debug("Cleaned up Harmony patches");
         }
     }
 }

docs/builtins.md

@@ -0,0 +1,302 @@
+# Built-in Functions
+
+<!--toc:start-->
+
+- [Built-in Functions](#built-in-functions)
+  - [System Functions](#system-functions)
+    - [`yield()`](#yield)
+    - [`sleep(ticks)`](#sleepticks)
+    - [`hash(prefabName)`](#hashprefabname)
+  - [Device I/O Functions](#device-io-functions)
+    - [Reading from Devices](#reading-from-devices)
+      - [Load from device](#load-from-device)
+      - [Load From Device Batched](#load-from-device-batched)
+      - [Load From Device Batched Named](#load-from-device-batched-named)
+      - [Load Slot](#load-slot)
+      - [Load Reagent](#load-reagent)
+    - [Writing to Devices](#writing-to-devices)
+      - [Set On Device](#set-on-device)
+      - [Set On Device Batched](#set-on-device-batched)
+      - [Set On Device Batched Named](#set-on-device-batched-named)
+      - [Set Slot](#set-slot)
+  - [Math Functions](#math-functions)
+    - [Trigonometric Functions](#trigonometric-functions)
+      - [Trig Example](#trig-example)
+    - [Rounding Functions](#rounding-functions)
+      - [Rounding Example](#rounding-example)
+    - [Other Math Functions](#other-math-functions)
+      - [Math Example](#math-example)
+  - [See Also](#see-also)
+  <!--toc:end-->
+
+Slang provides built-in functions for device I/O and mathematical operations.
+These map directly to IC10 instructions.
+
+## System Functions
+
+### `yield()`
+
+Pauses execution for exactly one game tick.
+
+```rust
+yield();
+```
+
+**IC10:** `yield`
+
+---
+
+### `sleep(ticks)`
+
+Pauses execution for the specified number of ticks.
+
+```rust
+sleep(10);  // Sleep for 10 ticks
+```
+
+**IC10:** `sleep ticks`
+
+---
+
+### `hash(prefabName)`
+
+Computes the in-game hash for a prefab name. The hash is computed at compile
+time and no runtime code is generated.
+
+```rust
+const AC_HASH = hash("StructureAirConditioner");
+```
+
+**Note:** This is different from IC10's `hash` instruction, which computes the
+hash at runtime.
+
+```rust
+setBatched(AC_HASH, "On", 0);
+```
+
+**IC10:** `sb -2087593337 On 0` (no hash computation at runtime)
+
+---
+
+## Device I/O Functions
+
+### Reading from Devices
+
+#### Load from device
+
+`load(device, property)` / `l(device, property)`
+
+Loads a property value from a device:
+
+```rust
+let temp = load(sensor, "Temperature");
+let temp = l(sensor, "Temperature");
+
+// Preferred: use dot notation
+let temp = sensor.Temperature;
+```
+
+**IC10:** `l r? d? var`
+
+---
+
+#### Load From Device Batched
+
+`loadBatched(deviceHash, property, batchMode)` / `lb(...)`
+
+Loads a property from all devices matching a hash, aggregated by batch mode:
+
+```rust
+const SENSOR = hash("StructureGasSensor");
+let avgTemp = loadBatched(SENSOR, "Temperature", "Average");
+let maxTemp = lb(SENSOR, "Temperature", "Maximum");
+```
+
+**Batch Modes:** `"Average"`, `"Sum"`, `"Minimum"`, `"Maximum"`
+
+**IC10:** `lb r? deviceHash logicType batchMode`
+
+---
+
+#### Load From Device Batched Named
+
+`loadBatchedNamed(deviceHash, nameHash, property, batchMode)` / `lbn(...)`
+
+Loads a property from devices matching both device hash and name hash:
+
+```rust
+const SENSOR_HASH = hash("StructureGasSensor");
+const SENSOR_NAME_HASH = hash("Outdoor Gas Sensor");
+let avgTemp = loadBatchedNamed(SENSOR_HASH, SENSOR_NAME_HASH, "Temperature", "Average");
+let maxTemp = lbn(SENSOR_HASH, SENSOR_NAME_HASH, "Temperature", "Maximum");
+```
+
+**IC10:** `lbn r? deviceHash nameHash logicType batchMode`
+
+**Note:** This function is useful when a script interfaces with a lot of
+devices, as it allows for arbitrary device access without limited to the 6 `dx` pins.
+
+---
+
+#### Load Slot
+
+`loadSlot(device, slotIndex, property)` / `ls(...)`
+
+Loads a slot property from a device:
+
+```rust
+let occupied = loadSlot(sorter, 0, "Occupied");
+let occupied = ls(sorter, 0, "Occupied");
+```
+
+**IC10:** `ls r? d? slotIndex logicSlotType`
+
+---
+
+#### Load Reagent
+
+`loadReagent(device, reagentMode, reagentHash)` / `lr(...)`
+
+Loads reagent information from a device:
+
+```rust
+let amount = loadReagent(furnace, "Contents", reagentHash);
+let amount = lr(furnace, "Contents", reagentHash);
+```
+
+**IC10:** `lr r? d? reagentMode reagentHash`
+
+---
+
+### Writing to Devices
+
+#### Set On Device
+
+`set(device, property, value)` / `s(...)`
+
+Sets a property on a device:
+
+```rust
+set(valve, "On", true);
+s(valve, "On", true);
+
+// Preferred: use dot notation
+valve.On = true;
+```
+
+**IC10:** `s d? logicType r?`
+
+---
+
+#### Set On Device Batched
+
+`setBatched(deviceHash, property, value)` / `sb(...)`
+
+Sets a property on all devices matching a hash:
+
+```rust
+const LIGHT_HASH = hash("StructureWallLight");
+setBatched(LIGHT_HASH, "On", true);
+sb(LIGHT_HASH, "On", true);
+```
+
+**IC10:** `sb deviceHash logicType r?`
+
+**Note:** This function is useful when a script interfaces with a lot of devices,
+as it allows for arbitrary device access without limited to the 6 `dx` pins.
+
+---
+
+#### Set On Device Batched Named
+
+`setBatchedNamed(deviceHash, nameHash, property, value)` / `sbn(...)`
+
+Sets a property on devices matching both device hash and name hash:
+
+```rust
+const SENSOR_HASH = hash("StructureGasSensor");
+const SENSOR_NAME_HASH = hash("Outdoor Gas Sensor");
+setBatchedNamed(SENSOR_HASH, SENSOR_NAME_HASH, "On", true);
+sbn(SENSOR_HASH, SENSOR_NAME_HASH, "On", true);
+```
+
+**IC10:** `sbn deviceHash nameHash logicType r?`
+
+---
+
+#### Set Slot
+
+`setSlot(device, slotIndex, property, value)` / `ss(...)`
+
+Sets a slot property on a device:
+
+```rust
+setSlot(sorter, 0, "Open", true);
+ss(sorter, 0, "Open", true);
+```
+
+**IC10:** `ss d? slotIndex logicSlotType r?`
+
+---
+
+## Math Functions
+
+All math functions accept numbers, variables, or expressions as arguments.
+
+### Trigonometric Functions
+
+| Function      | Description                  | IC10    |
+| ------------- | ---------------------------- | ------- |
+| `sin(x)`      | Sine of angle in radians     | `sin`   |
+| `cos(x)`      | Cosine of angle in radians   | `cos`   |
+| `tan(x)`      | Tangent of angle in radians  | `tan`   |
+| `asin(x)`     | Arc sine, returns radians    | `asin`  |
+| `acos(x)`     | Arc cosine, returns radians  | `acos`  |
+| `atan(x)`     | Arc tangent, returns radians | `atan`  |
+| `atan2(y, x)` | Two-argument arc tangent     | `atan2` |
+
+#### Trig Example
+
+```rust
+let angle = atan2(y, x);
+let sineValue = sin(angle);
+```
+
+### Rounding Functions
+
+| Function   | Description                   | IC10    |
+| ---------- | ----------------------------- | ------- |
+| `ceil(x)`  | Round up to nearest integer   | `ceil`  |
+| `floor(x)` | Round down to nearest integer | `floor` |
+| `trunc(x)` | Remove decimal portion        | `trunc` |
+| `abs(x)`   | Absolute value                | `abs`   |
+
+#### Rounding Example
+
+```rust
+let rounded = floor(3.7);  // 3
+let positive = abs(-5);    // 5
+```
+
+### Other Math Functions
+
+| Function    | Description                   | IC10   |
+| ----------- | ----------------------------- | ------ |
+| `sqrt(x)`   | Square root                   | `sqrt` |
+| `log(x)`    | Natural logarithm             | `log`  |
+| `max(a, b)` | Maximum of two values         | `max`  |
+| `min(a, b)` | Minimum of two values         | `min`  |
+| `rand()`    | Random number between 0 and 1 | `rand` |
+
+#### Math Example
+
+```rust
+let root = sqrt(16);        // 4
+let bigger = max(a, b);
+let randomVal = rand();
+```
+
+## See Also
+
+- [Language Reference](language-reference.md) — Complete syntax guide
+- [Examples](examples.md) — Real-world code samples

docs/examples.md

@@ -0,0 +1,254 @@
+# Examples
+
+Real-world Slang programs demonstrating common patterns.
+
+## Temperature Control
+
+Basic thermostat that controls an air conditioner based on room temperature:
+
+```rust
+device ac = "db";
+device roomGasSensor = "d0";
+
+const TARGET_TEMP = 22c;
+const HYSTERESIS = 1;
+
+loop {
+    yield();
+    let temp = roomGasSensor.Temperature;
+
+    if (temp > TARGET_TEMP + HYSTERESIS) {
+        ac.On = true;
+    } else if (temp < TARGET_TEMP - HYSTERESIS) {
+        ac.On = false;
+    }
+}
+```
+
+**Note:** The IC10 chip is assumed to be inserted in the air conditioner's IC slot.
+
+---
+
+## Two-Axis Solar Panel Tracking
+
+Handles two-axis solar panel tracking based on the sun's position:
+
+```rust
+device sensor = "d0";
+
+const H_PANELS = hash("StructureSolarPanelDual");
+
+loop {
+    setBatched(H_PANELS, "Horizontal", sensor.Horizontal);
+    setBatched(H_PANELS, "Vertical", sensor.Vertical + 90);
+    yield();
+}
+```
+
+**Note:** Assumes the daylight sensor is mounted with its port looking 90
+degrees east of the solar panel's data port, an offset can be added on the
+horizontal angle if needed.
+
+---
+
+## Day/Night Lighting
+
+Controls grow lights during the day and ambient lights at night:
+
+```rust
+device greenhouseSensor = "d0";
+
+const daylightSensor = hash("StructureDaylightSensor");
+const growLight = hash("StructureGrowLight");
+const wallLight = hash("StructureLightLong");
+
+loop {
+    yield();
+    let solarAngle = lb(daylightSensor, "SolarAngle", "Average");
+    let isDaylight = solarAngle < 90;
+
+    sb(growLight, "On", isDaylight);
+    sb(wallLight, "On", !isDaylight);
+}
+```
+
+---
+
+## Pressure Relief Valve
+
+Controls a volume pump based on pressure readings for emergency pressure relief:
+
+```rust
+device volumePump = "d0";
+device pipeSensor = "d1";
+
+const MAX_PRESSURE = 10_000;
+const R = 8.314;
+
+loop {
+    yield();
+
+    let pressure = pipeSensor.Pressure;
+
+    if (pressure > MAX_PRESSURE) {
+        // Use PV=nRT to calculate the amount of mols we need to move
+        // n = PV / RT
+        let molsToMove = (pressure - MAX_PRESSURE) *
+          pipeSensor.Volume / (R * pipeSensor.Temperature);
+
+        // V = nRT / P
+        let setting = molsToMove * R * pipeSensor.Temperature / pressure;
+        volumePump.Setting = setting;
+        volumePump.On = true;
+    } else {
+        volumePump.On = false;
+    }
+}
+```
+
+---
+
+## Greenhouse Environment Controller
+
+Complete greenhouse control with pressure, temperature, and lighting:
+
+```rust
+device self = "db";
+device emergencyRelief = "d0";
+device greenhouseSensor = "d1";
+device recycleValve = "d2";
+
+const MAX_INTERIOR_PRESSURE = 80;
+const MAX_INTERIOR_TEMP = 28c;
+const MIN_INTERIOR_PRESSURE = 75;
+const MIN_INTERIOR_TEMP = 25c;
+const daylightSensor = 1076425094;
+const growLight = hash("StructureGrowLight");
+const wallLight = hash("StructureLightLong");
+const lightRound = hash("StructureLightRound");
+
+let shouldPurge = false;
+
+loop {
+    yield();
+    let interiorPress = greenhouseSensor.Pressure;
+    let interiorTemp = greenhouseSensor.Temperature;
+
+    shouldPurge = (
+        interiorPress > MAX_INTERIOR_PRESSURE ||
+        interiorTemp > MAX_INTERIOR_TEMP
+    ) || shouldPurge;
+
+    emergencyRelief.On = shouldPurge;
+    recycleValve.On = !shouldPurge;
+
+    if (
+        shouldPurge && (
+          interiorPress < MIN_INTERIOR_PRESSURE &&
+          interiorTemp < MIN_INTERIOR_TEMP
+          )
+        ) {
+        shouldPurge = false;
+    }
+
+    let solarAngle = lb(daylightSensor, "SolarAngle", "Average");
+    let isDaylight = solarAngle < 90;
+
+    sb(growLight, "On", isDaylight);
+    sb(wallLight, "On", !isDaylight);
+    sb(lightRound, "On", !isDaylight);
+}
+```
+
+---
+
+## Advanced Furnace Pressure Control
+
+Automates multi-furnace pump control based on dial setting for pressure target:
+
+```rust
+const FURNACE1 = 1234;
+const DIAL1 = 1123;
+const ANALYZER1 = 1223;
+
+const FURNACE2 = 1235;
+const DIAL2 = 1124;
+const ANALYZER2 = 1224;
+
+const FURNACE3 = 1236;
+const DIAL3 = 1124;
+const ANALYZER3 = 1225;
+
+const R = 8.314;
+
+fn handleFurnace(furnace, dial, analyzer) {
+    let pressure = furnace.Pressure;
+    let targetPressure = max(dial.Setting, 0.1) * 1000;
+
+    if (abs(targetPressure - pressure) <= 0.1) {
+        furnace.On = false;
+        return;
+    }
+
+    let molsToMove = max(furnace.TotalMoles, 1) * (
+      (targetPressure / pressure) - 1
+    );
+
+    // V = nRT / P
+    if (molsToMove > 0) {
+        // Calculate volume required
+        if (analyzer.Pressure == 0) {
+            // No more gas to add
+            furnace.On = false;
+            return;
+        }
+        let volume = molsToMove * R * analyzer.Temperature / analyzer.Pressure;
+
+        furnace.On = true;
+        furnace.SettingOutput = 0;
+        furnace.SettingInput = volume;
+
+        return;
+    }
+
+    // Calculate volume required
+    let volume = (-molsToMove) * R * furnace.Temperature / pressure;
+
+    furnace.On = true;
+    furnace.SettingInput = 0;
+    furnace.SettingOutput = volume;
+
+    return;
+}
+
+loop {
+    yield();
+
+    handleFurnace(FURNACE1, DIAL1, ANALYZER1);
+    handleFurnace(FURNACE2, DIAL2, ANALYZER2);
+    handleFurnace(FURNACE3, DIAL3, ANALYZER3);
+}
+```
+
+**Note:** This example does not handle edge cases such as insufficient gas in
+the input network or overfilling the furnace/pipe network.
+
+---
+
+## Common Patterns
+
+### Waiting for a Condition
+
+```rust
+fn waitForDeviceToTurnOff(device) {
+    while (device.On) {
+        yield();
+    }
+}
+```
+
+## See Also
+
+- [Getting Started](getting-started.md) — First steps with Slang
+- [Language Reference](language-reference.md) — Complete syntax guide
+- [Built-in Functions](builtins.md) — System calls and math functions

docs/getting-started.md

@@ -0,0 +1,99 @@
+# Getting Started
+
+<!--toc:start-->
+
+- [Getting Started](#getting-started)
+  - [Program Structure](#program-structure)
+  - [The `yield()` Function](#the-yield-function)
+  - [Your First Program](#your-first-program)
+    - [Explanation](#explanation)
+  - [Comments](#comments)
+  - [See Also](#see-also)
+  <!--toc:end-->
+
+This guide covers the basics of writing your first Slang program.
+
+## Program Structure
+
+A Slang program consists of top-level declarations and a main loop:
+
+```rust
+// Device declarations
+device self = "db";
+device sensor = "d0";
+
+// Constants
+const THRESHOLD = 100;
+
+// Variables
+let counter = 0;
+
+// Main program loop
+loop {
+    yield();
+    // Your logic here
+}
+```
+
+## The `yield()` Function
+
+IC10 programs run continuously. The `yield()` function pauses execution for one
+game tick, preventing the script from consuming excessive resources.
+
+**Important:** You should always include `yield()` in your main loop unless you
+know what you're doing.
+
+```rust
+loop {
+    yield(); // Recommended!
+    // ...
+}
+```
+
+## Your First Program
+
+Here's a simple program that turns on a light when a gas sensor detects low
+pressure:
+
+```rust
+device gasSensor = "d0";
+device light = "d1";
+
+const LOW_PRESSURE = 50;
+
+loop {
+    yield();
+    light.On = gasSensor.Pressure < LOW_PRESSURE;
+}
+```
+
+### Explanation
+
+1. `device gasSensor = "d0"` — Binds the device at port `d0` to the name
+   `gasSensor`
+2. `device light = "d1"` — Binds the device at port `d1` to the name `light`
+3. `const LOW_PRESSURE = 50` — Defines a compile-time constant
+4. `loop { ... }` — Creates an infinite loop
+5. `yield()` — Pauses for one tick
+6. `light.On = gasSensor.Pressure < LOW_PRESSURE` — Reads the pressure and sets
+   the light state
+
+## Comments
+
+Slang supports single-line comments and documentation comments:
+
+```rust
+// This is a regular comment
+
+/// This is a documentation comment
+/// It can span multiple lines
+fn myFunction() {
+    // ...
+}
+```
+
+## See Also
+
+- [Language Reference](language-reference.md) — Complete syntax guide
+- [Built-in Functions](builtins.md) — Available system calls
+- [Examples](examples.md) — Real-world programs and patterns

docs/language-reference.md

@@ -0,0 +1,339 @@
+# Language Reference
+
+<!--toc:start-->
+
+- [Language Reference](#language-reference)
+  - [Literals](#literals)
+    - [Numbers](#numbers)
+    - [Temperature Literals](#temperature-literals)
+    - [Booleans](#booleans)
+    - [Strings](#strings)
+  - [Variables](#variables)
+    - [`let` - Mutable Variables](#let-mutable-variables)
+    - [`const` - Constants](#const-constants)
+  - [Device Declarations](#device-declarations)
+    - [Device Property Access](#device-property-access)
+    - [Device Property Assignment](#device-property-assignment)
+  - [Operators](#operators)
+    - [Arithmetic Operators](#arithmetic-operators)
+    - [Comparison Operators](#comparison-operators)
+    - [Logical Operators](#logical-operators)
+    - [Ternary Operator](#ternary-operator)
+    - [Operator Precedence](#operator-precedence)
+  - [Control Flow](#control-flow)
+    - [`if` / `else`](#if-and-else)
+    - [`loop`](#loop)
+    - [`while`](#while)
+    - [`break`](#break)
+    - [`continue`](#continue)
+  - [Functions](#functions)
+    - [Declaration](#declaration)
+    - [Invocation](#invocation)
+    - [Return Values](#return-values)
+  - [Parentheses for Grouping](#parentheses-for-grouping)
+  - [See Also](#see-also)
+  <!--toc:end-->
+
+Complete syntax reference for the Slang programming language.
+
+## Literals
+
+### Numbers
+
+Numbers can be integers or decimals. Underscores are allowed as visual
+separators:
+
+```rust
+const integer = 42;                 // Integer
+const decimal = 3.14;               // Decimal
+const million = 1_000_000;          // Integer with separators
+const decimalSeparators = 5_000.50; // Decimal with separators
+```
+
+### Temperature Literals
+
+Append a unit suffix to specify temperature. Values are automatically converted
+to Kelvin at compile time:
+
+| Suffix | Unit       | Example |
+| ------ | ---------- | ------- |
+| `c`    | Celsius    | `20c`   |
+| `f`    | Fahrenheit | `68f`   |
+| `k`    | Kelvin     | `293k`  |
+
+```rust
+const ROOM_TEMP = 20c;       // Converts to 293.15 Kelvin
+const FREEZING  = 32f;       // Converts to 273.15 Kelvin
+const ABSOLUTE1 = 0k;        // Already in Kelvin
+const ABSOLUTE2 = 0;         // Assumed to be in Kelvin
+```
+
+### Booleans
+
+Booleans compile to integer values `1` and `0` in IC10.
+
+```rust
+device ac = "d0";
+
+ac.Mode = false;
+ac.On = true;
+```
+
+### Strings
+
+Strings use double or single quotes. They are primarily used for prefab and
+name hashes.
+
+```rust
+const AC_HASH = hash("StructureAirConditioner");
+const AC_NAME_HASH = hash("Greenhouse Air Conditioner");
+```
+
+## Variables
+
+### `let` Mutable Variables
+
+Declares a variable that can be reassigned:
+
+```rust
+let counter = 0;
+// ...
+counter = counter + 1;
+```
+
+### `const` Constants
+
+Declares a compile-time constant. Constants are inlined and do not consume
+registers:
+
+```rust
+const MAX_PRESSURE = 10_000;
+const DOOR_HASH = hash("StructureCompositeDoor");
+```
+
+Constants support the `hash()` function for compile-time hash computation.
+
+## Device Declarations
+
+The `device` keyword binds a device port or reference ID to a named variable:
+
+```rust
+device self = "db";   // IC housing, or device the IC is plugged into (eg. an AC)
+device sensor = "d0"; // Device at port d0
+device valve = "d1";  // Device at port d1
+device ac1 = "$3FC";  // Device with reference ID $3FC (hexadecimal 1020)
+device ac2 = "1020";  // Device with reference ID 1020 (decimal)
+```
+
+**Note:** Reference IDs can be found in-game using the Configuration cartridge.
+
+### Device Property Access
+
+Read device properties using dot notation:
+
+```rust
+let temp = sensor.Temperature;
+let pressure = sensor.Pressure;
+let isOn = valve.On;
+```
+
+### Device Property Assignment
+
+Write to device properties using dot notation:
+
+```rust
+valve.On = true;
+valve.Setting = 100;
+```
+
+## Operators
+
+### Arithmetic Operators
+
+| Operator | Description    | Example  |
+| -------- | -------------- | -------- |
+| `+`      | Addition       | `a + b`  |
+| `-`      | Subtraction    | `a - b`  |
+| `*`      | Multiplication | `a * b`  |
+| `/`      | Division       | `a / b`  |
+| `%`      | Modulo         | `a % b`  |
+| `**`     | Exponentiation | `a ** b` |
+| `-`      | Negation       | `-a`     |
+
+### Comparison Operators
+
+| Operator | Description           | Example  |
+| -------- | --------------------- | -------- |
+| `==`     | Equal                 | `a == b` |
+| `!=`     | Not equal             | `a != b` |
+| `<`      | Less than             | `a < b`  |
+| `>`      | Greater than          | `a > b`  |
+| `<=`     | Less than or equal    | `a <= b` |
+| `>=`     | Greater than or equal | `a >= b` |
+
+### Logical Operators
+
+| Operator | Description | Example    |
+| -------- | ----------- | ---------- |
+| `&&`     | Logical AND | `a && b`   |
+| `\|\|`   | Logical OR  | `a \|\| b` |
+| `!`      | Logical NOT | `!a`       |
+
+### Ternary Operator
+
+Conditional expressions using `?` and `:`:
+
+```rust
+let result = condition ? valueIfTrue : valueIfFalse;
+```
+
+### Operator Precedence
+
+Operators are evaluated in the following order, from highest to lowest
+precedence:
+
+| Precedence | Operator(s)       | Description                      |
+| ---------- | ----------------- | -------------------------------- |
+| 1          | `()` `.`          | Grouping, Property access        |
+| 2          | `!` `-`           | Logical NOT, Negation            |
+| 3          | `**`              | Exponentiation                   |
+| 4          | `*` `/` `%`       | Multiplication, Division, Modulo |
+| 5          | `+` `-`           | Addition, Subtraction            |
+| 6          | `<` `<=` `>` `>=` | Comparison                       |
+| 7          | `==` `!=`         | Equality                         |
+| 8          | `&&`              | Logical AND                      |
+| 9          | `\|\|`            | Logical OR                       |
+| 10         | `?:`              | Ternary conditional              |
+| 11         | `=`               | Assignment                       |
+
+Use parentheses to override precedence:
+
+```rust
+let result = (20 + 10) * 5;
+```
+
+## Control Flow
+
+### if and else
+
+Conditional branching:
+
+```rust
+if (tank.Temperature > 30c) {
+    ac.On = true;
+} else {
+    ac.On = false;
+}
+```
+
+### `loop`
+
+Infinite loop that runs until `break`:
+
+```rust
+loop {
+    yield();
+    // Loop body
+    if (condition) {
+        break;  // Exit the loop
+    }
+}
+```
+
+### `while`
+
+Conditional loop that runs while the condition is true:
+
+```rust
+while (counter < 100) {
+    counter = counter + 1;
+    yield();
+}
+```
+
+### `break`
+
+Exits the current loop:
+
+```rust
+loop {
+    yield();
+    // ...
+    if (done) {
+        break;
+    }
+}
+```
+
+### `continue`
+
+Skips to the next iteration of the current loop:
+
+```rust
+loop {
+    yield();
+    if (shouldSkip) {
+        continue;
+    }
+    // This code is skipped when shouldSkip is true
+    // ...
+}
+```
+
+## Functions
+
+**Warning:** Functions are currently experimental and may produce suboptimal code.
+
+### Declaration
+
+```rust
+fn functionName(arg1, arg2) {
+    // Function body
+    return arg1 + arg2;
+}
+```
+
+### Invocation
+
+```rust
+let result = functionName(10, 20);
+```
+
+### Return Values
+
+Use `return` to exit a function and optionally return a value:
+
+```rust
+fn calculate(x) {
+    if (x < 0) {
+        return 0;  // Early return
+    }
+
+    return x * 2;
+}
+
+fn doWork() {
+    // No return value
+    return;
+}
+```
+
+## Parentheses for Grouping
+
+Use parentheses to control operator precedence:
+
+```rust
+let result = (a + b) * c;
+
+let complex = (
+    temp > 0c &&
+    stress < 50 &&
+    (pressure < 10_000 || temp > 20c)
+);
+```
+
+## See Also
+
+- [Getting Started](getting-started.md) — First steps with Slang
+- [Built-in Functions](builtins.md) — System calls and math functions
+- [Examples](examples.md) — Real-world code samples

rust_compiler/Cargo.lock

@@ -930,7 +930,7 @@ checksum = "e3a9fe34e3e7a50316060351f37187a3f546bce95496156754b601a5fa71b76e"
 
 [[package]]
 name = "slang"
-version = "0.4.3"
+version = "0.4.7"
 dependencies = [
  "anyhow",
  "clap",

rust_compiler/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "slang"
-version = "0.4.3"
+version = "0.4.7"
 edition = "2021"
 
 [workspace]

rust_compiler/libs/compiler/src/test/declaration_literal.rs

@@ -168,3 +168,28 @@ fn test_const_hash_expr() -> anyhow::Result<()> {
     );
     Ok(())
 }
+
+#[test]
+fn test_declaration_is_const() -> anyhow::Result<()> {
+    let compiled = compile! {
+        debug
+        r#"
+            const MAX = 100;
+
+            let max = MAX;
+        "#
+    };
+
+    assert_eq!(
+        compiled,
+        indoc! {
+            "
+            j main
+            main:
+            move r8 100
+            "
+        }
+    );
+
+    Ok(())
+}

rust_compiler/libs/compiler/src/test/mod.rs

@@ -47,3 +47,4 @@ mod logic_expression;
 mod loops;
 mod math_syscall;
 mod syscall;
+mod tuple_literals;

rust_compiler/libs/compiler/src/test/tuple_literals.rs

@@ -0,0 +1,950 @@
+#[cfg(test)]
+mod test {
+    use indoc::indoc;
+    use pretty_assertions::assert_eq;
+
+    #[test]
+    fn test_tuple_literal_declaration() -> anyhow::Result<()> {
+        let compiled = compile!(
+            debug
+            r#"
+            let (x, y) = (1, 2);
+            "#
+        );
+
+        assert_eq!(
+            compiled,
+            indoc! {
+                "
+                j main
+                main:
+                move r8 1
+                move r9 2
+                "
+            }
+        );
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_tuple_literal_declaration_with_underscore() -> anyhow::Result<()> {
+        let compiled = compile!(
+            debug
+            r#"
+            let (x, _) = (1, 2);
+            "#
+        );
+
+        assert_eq!(
+            compiled,
+            indoc! {
+                "
+                j main
+                main:
+                move r8 1
+                "
+            }
+        );
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_tuple_literal_assignment() -> anyhow::Result<()> {
+        let compiled = compile!(
+            debug
+            r#"
+            let x = 0;
+            let y = 0;
+            (x, y) = (5, 10);
+            "#
+        );
+
+        assert_eq!(
+            compiled,
+            indoc! {
+                "
+                j main
+                main:
+                move r8 0
+                move r9 0
+                move r8 5
+                move r9 10
+                "
+            }
+        );
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_tuple_literal_with_variables() -> anyhow::Result<()> {
+        let compiled = compile!(
+            debug
+            r#"
+            let a = 42;
+            let b = 99;
+            let (x, y) = (a, b);
+            "#
+        );
+
+        assert_eq!(
+            compiled,
+            indoc! {
+                "
+                j main
+                main:
+                move r8 42
+                move r9 99
+                move r10 r8
+                move r11 r9
+                "
+            }
+        );
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_tuple_literal_three_elements() -> anyhow::Result<()> {
+        let compiled = compile!(
+            debug
+            r#"
+            let (x, y, z) = (1, 2, 3);
+            "#
+        );
+
+        assert_eq!(
+            compiled,
+            indoc! {
+                "
+                j main
+                main:
+                move r8 1
+                move r9 2
+                move r10 3
+                "
+            }
+        );
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_tuple_literal_assignment_with_underscore() -> anyhow::Result<()> {
+        let compiled = compile!(
+            debug
+            r#"
+            let i = 0;
+            let x = 123;
+            (i, _) = (456, 789);
+            "#
+        );
+
+        assert_eq!(
+            compiled,
+            indoc! {
+                "
+                j main
+                main:
+                move r8 0
+                move r9 123
+                move r8 456
+                "
+            }
+        );
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_tuple_return_simple() -> anyhow::Result<()> {
+        let compiled = compile!(
+            debug
+            r#"
+            fn getPair() {
+                return (10, 20);
+            };
+            let (x, y) = getPair();
+            "#
+        );
+
+        assert_eq!(
+            compiled,
+            indoc! {
+                "
+                j main
+                getPair:
+                move r15 sp
+                push ra
+                push 10
+                push 20
+                move r15 1
+                sub r0 sp 3
+                get ra db r0
+                j ra
+                main:
+                jal getPair
+                pop r9
+                pop r8
+                move sp r15
+                "
+            }
+        );
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_tuple_return_with_underscore() -> anyhow::Result<()> {
+        let compiled = compile!(
+            debug
+            r#"
+            fn getPair() {
+                return (5, 15);
+            };
+            let (x, _) = getPair();
+            "#
+        );
+
+        assert_eq!(
+            compiled,
+            indoc! {
+                "
+                j main
+                getPair:
+                move r15 sp
+                push ra
+                push 5
+                push 15
+                move r15 1
+                sub r0 sp 3
+                get ra db r0
+                j ra
+                main:
+                jal getPair
+                pop r0
+                pop r8
+                move sp r15
+                "
+            }
+        );
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_tuple_return_three_elements() -> anyhow::Result<()> {
+        let compiled = compile!(
+            debug
+            r#"
+            fn getTriple() {
+                return (1, 2, 3);
+            };
+            let (a, b, c) = getTriple();
+            "#
+        );
+
+        assert_eq!(
+            compiled,
+            indoc! {
+                "
+                j main
+                getTriple:
+                move r15 sp
+                push ra
+                push 1
+                push 2
+                push 3
+                move r15 1
+                sub r0 sp 4
+                get ra db r0
+                j ra
+                main:
+                jal getTriple
+                pop r10
+                pop r9
+                pop r8
+                move sp r15
+                "
+            }
+        );
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_tuple_return_assignment() -> anyhow::Result<()> {
+        let compiled = compile!(
+            debug
+            r#"
+            fn getPair() {
+                return (42, 84);
+            };
+            let i = 1;
+            let j = 2;
+            (i, j) = getPair();
+            "#
+        );
+
+        assert_eq!(
+            compiled,
+            indoc! {
+                "
+                j main
+                getPair:
+                move r15 sp
+                push ra
+                push 42
+                push 84
+                move r15 1
+                sub r0 sp 3
+                get ra db r0
+                j ra
+                main:
+                move r8 1
+                move r9 2
+                jal getPair
+                pop r9
+                pop r8
+                move sp r15
+                "
+            }
+        );
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_tuple_return_mismatch() -> anyhow::Result<()> {
+        let errors = compile!(
+            result
+            r#"
+            fn doSomething() {
+                return (1, 2, 3);
+            };
+            let (x, y) = doSomething();
+            "#
+        );
+
+        // Should have exactly one error about tuple size mismatch
+        assert_eq!(errors.len(), 1);
+
+        // Check for the specific TupleSizeMismatch error
+        match &errors[0] {
+            crate::Error::TupleSizeMismatch(expected_size, actual_count, _) => {
+                assert_eq!(*expected_size, 3);
+                assert_eq!(*actual_count, 2);
+            }
+            e => panic!("Expected TupleSizeMismatch error, got: {:?}", e),
+        }
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_tuple_return_called_by_non_tuple_return() -> anyhow::Result<()> {
+        let compiled = compile!(
+            debug
+            r#"
+            fn doSomething() {
+                return (1, 2);
+            };
+            
+            fn doSomethingElse() {
+                let (x, y) = doSomething();
+                return y;
+            };
+            
+            let returnedValue = doSomethingElse();
+            "#
+        );
+
+        assert_eq!(
+            compiled,
+            indoc! {
+                "
+                j main
+                doSomething:
+                move r15 sp
+                push ra
+                push 1
+                push 2
+                move r15 1
+                sub r0 sp 3
+                get ra db r0
+                j ra
+                doSomethingElse:
+                push ra
+                jal doSomething
+                pop r9
+                pop r8
+                move sp r15
+                move r15 r9
+                j __internal_L2
+                __internal_L2:
+                pop ra
+                j ra
+                main:
+                jal doSomethingElse
+                move r8 r15
+                "
+            }
+        );
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_non_tuple_return_called_by_tuple_return() -> anyhow::Result<()> {
+        let compiled = compile!(
+            debug
+            r#"
+            fn getValue() {
+                return 42;
+            };
+            
+            fn getTuple() {
+                let x = getValue();
+                return (x, x);
+            };
+            
+            let (a, b) = getTuple();
+            "#
+        );
+
+        assert_eq!(
+            compiled,
+            indoc! {
+                "
+                j main
+                getValue:
+                push ra
+                move r15 42
+                j __internal_L1
+                __internal_L1:
+                pop ra
+                j ra
+                getTuple:
+                move r15 sp
+                push ra
+                jal getValue
+                move r8 r15
+                push r8
+                push r8
+                move r15 1
+                sub r0 sp 3
+                get ra db r0
+                j ra
+                main:
+                jal getTuple
+                pop r9
+                pop r8
+                move sp r15
+                "
+            }
+        );
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_tuple_literal_size_mismatch() -> anyhow::Result<()> {
+        let errors = compile!(
+            result
+            r#"
+            let (x, y) = (1, 2, 3);
+            "#
+        );
+
+        // Should have exactly one error about tuple size mismatch
+        assert_eq!(errors.len(), 1);
+        assert!(matches!(
+            errors[0],
+            crate::Error::TupleSizeMismatch(_, _, _)
+        ));
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_multiple_tuple_returns_in_function() -> anyhow::Result<()> {
+        let compiled = compile!(
+            debug
+            r#"
+            fn getValue(x) {
+                if (x) {
+                    return (1, 2);
+                } else {
+                    return (3, 4);
+                }
+            };
+            
+            let (a, b) = getValue(1);
+            "#
+        );
+
+        assert_eq!(
+            compiled,
+            indoc! {
+                "
+                j main
+                getValue:
+                pop r8
+                move r15 sp
+                push ra
+                beqz r8 __internal_L3
+                push 1
+                push 2
+                move r15 0
+                sub r0 sp 3
+                get ra db r0
+                j ra
+                sub sp sp 2
+                j __internal_L2
+                __internal_L3:
+                push 3
+                push 4
+                move r15 0
+                sub r0 sp 3
+                get ra db r0
+                j ra
+                sub sp sp 2
+                __internal_L2:
+                main:
+                push 1
+                jal getValue
+                pop r9
+                pop r8
+                move sp r15
+                "
+            },
+        );
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_tuple_return_with_expression() -> anyhow::Result<()> {
+        let compiled = compile!(
+            debug
+            r#"
+            fn add(x, y) {
+                return (x, y);
+            };
+            
+            let (a, b) = add(5, 10);
+            "#
+        );
+
+        assert_eq!(
+            compiled,
+            indoc! {
+                "
+                j main
+                add:
+                pop r8
+                pop r9
+                move r15 sp
+                push ra
+                push r9
+                push r8
+                move r15 1
+                sub r0 sp 3
+                get ra db r0
+                j ra
+                main:
+                push 5
+                push 10
+                jal add
+                pop r9
+                pop r8
+                move sp r15
+                "
+            }
+        );
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_nested_function_tuple_calls() -> anyhow::Result<()> {
+        let compiled = compile!(
+            debug
+            r#"
+            fn inner() {
+                return (1, 2);
+            };
+            
+            fn outer() {
+                let (x, y) = inner();
+                return (y, x);
+            };
+            
+            let (a, b) = outer();
+            "#
+        );
+
+        assert_eq!(
+            compiled,
+            indoc! {
+                "
+                j main
+                inner:
+                move r15 sp
+                push ra
+                push 1
+                push 2
+                move r15 1
+                sub r0 sp 3
+                get ra db r0
+                j ra
+                outer:
+                move r15 sp
+                push ra
+                jal inner
+                pop r9
+                pop r8
+                move sp r15
+                push r9
+                push r8
+                move r15 1
+                sub r0 sp 3
+                get ra db r0
+                j ra
+                main:
+                jal outer
+                pop r9
+                pop r8
+                move sp r15
+                "
+            }
+        );
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_tuple_literal_with_constant_expressions() -> anyhow::Result<()> {
+        let compiled = compile!(
+            debug
+            r#"
+            let (a, b) = (1 + 2, 3 * 4);
+            "#
+        );
+
+        assert_eq!(
+            compiled,
+            indoc! {
+                "
+                j main
+                main:
+                move r8 3
+                move r9 12
+                "
+            }
+        );
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_tuple_literal_with_variable_expressions() -> anyhow::Result<()> {
+        let compiled = compile!(
+            debug
+            r#"
+            let x = 5;
+            let y = 10;
+            let (a, b) = (x + 1, y * 2);
+            "#
+        );
+
+        assert_eq!(
+            compiled,
+            indoc! {
+                "
+                j main
+                main:
+                move r8 5
+                move r9 10
+                add r1 r8 1
+                move r10 r1
+                mul r2 r9 2
+                move r11 r2
+                "
+            }
+        );
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_tuple_assignment_with_expressions() -> anyhow::Result<()> {
+        let compiled = compile!(
+            debug
+            r#"
+            let a = 0;
+            let b = 0;
+            let x = 5;
+            (a, b) = (x + 1, x * 2);
+            "#
+        );
+
+        assert_eq!(
+            compiled,
+            indoc! {
+                "
+                j main
+                main:
+                move r8 0
+                move r9 0
+                move r10 5
+                add r1 r10 1
+                move r8 r1
+                mul r2 r10 2
+                move r9 r2
+                "
+            }
+        );
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_tuple_literal_with_function_calls() -> anyhow::Result<()> {
+        let compiled = compile!(
+            debug
+            r#"
+            fn getValue() { return 42; };
+            fn getOther() { return 99; };
+            
+            let (a, b) = (getValue(), getOther());
+            "#
+        );
+
+        assert_eq!(
+            compiled,
+            indoc! {
+                "
+                j main
+                getValue:
+                push ra
+                move r15 42
+                j __internal_L1
+                __internal_L1:
+                pop ra
+                j ra
+                getOther:
+                push ra
+                move r15 99
+                j __internal_L2
+                __internal_L2:
+                pop ra
+                j ra
+                main:
+                push r8
+                jal getValue
+                pop r8
+                move r1 r15
+                move r8 r1
+                push r8
+                push r9
+                jal getOther
+                pop r9
+                pop r8
+                move r2 r15
+                move r9 r2
+                "
+            }
+        );
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_tuple_with_logical_expressions() -> anyhow::Result<()> {
+        let compiled = compile!(
+            debug
+            r#"
+            let x = 1;
+            let y = 0;
+            let (a, b) = (x && y, x || y);
+            "#
+        );
+
+        assert_eq!(
+            compiled,
+            indoc! {
+                "
+                j main
+                main:
+                move r8 1
+                move r9 0
+                and r1 r8 r9
+                move r10 r1
+                or r2 r8 r9
+                move r11 r2
+                "
+            }
+        );
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_tuple_with_comparison_expressions() -> anyhow::Result<()> {
+        let compiled = compile!(
+            debug
+            r#"
+            let x = 5;
+            let y = 10;
+            let (a, b) = (x > y, x < y);
+            "#
+        );
+
+        assert_eq!(
+            compiled,
+            indoc! {
+                "
+                j main
+                main:
+                move r8 5
+                move r9 10
+                sgt r1 r8 r9
+                move r10 r1
+                slt r2 r8 r9
+                move r11 r2
+                "
+            }
+        );
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_tuple_with_device_property_access() -> anyhow::Result<()> {
+        let compiled = compile!(
+            debug
+            r#"
+            device sensor = "d0";
+            device display = "d1";
+            
+            let (temp, pressure) = (sensor.Temperature, sensor.Pressure);
+            "#
+        );
+
+        assert_eq!(
+            compiled,
+            indoc! {
+                "
+                j main
+                main:
+                l r1 d0 Temperature
+                move r8 r1
+                l r2 d0 Pressure
+                move r9 r2
+                "
+            }
+        );
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_tuple_with_device_property_and_function_call() -> anyhow::Result<()> {
+        let compiled = compile!(
+            debug
+            r#"
+            device self = "db";
+            
+            fn getY() {
+                return 42;
+            }
+            
+            let (x, y) = (self.Setting, getY());
+            "#
+        );
+
+        assert_eq!(
+            compiled,
+            indoc! {
+                "
+                j main
+                getY:
+                push ra
+                move r15 42
+                j __internal_L1
+                __internal_L1:
+                pop ra
+                j ra
+                main:
+                l r1 db Setting
+                move r8 r1
+                push r8
+                push r9
+                jal getY
+                pop r9
+                pop r8
+                move r2 r15
+                move r9 r2
+                "
+            }
+        );
+
+        Ok(())
+    }
+
+    #[test]
+    fn test_tuple_with_function_call_expressions() -> anyhow::Result<()> {
+        let compiled = compile!(
+            debug
+            r#"
+            fn getValue() { return 10; }
+            fn getOther() { return 20; }
+            
+            let (a, b) = (getValue() + 5, getOther() * 2);
+            "#
+        );
+
+        assert_eq!(
+            compiled,
+            indoc! {
+                "
+                j main
+                getValue:
+                push ra
+                move r15 10
+                j __internal_L1
+                __internal_L1:
+                pop ra
+                j ra
+                getOther:
+                push ra
+                move r15 20
+                j __internal_L2
+                __internal_L2:
+                pop ra
+                j ra
+                main:
+                push r8
+                jal getValue
+                pop r8
+                move r1 r15
+                add r2 r1 5
+                move r8 r2
+                push r8
+                push r9
+                jal getOther
+                pop r9
+                pop r8
+                move r3 r15
+                mul r4 r3 2
+                move r9 r4
+                "
+            }
+        );
+
+        Ok(())
+    }
+}

rust_compiler/libs/compiler/src/v1.rs

@@ -9,7 +9,8 @@ use parser::{
         AssignmentExpression, BinaryExpression, BlockExpression, ConstDeclarationExpression,
         DeviceDeclarationExpression, Expression, FunctionExpression, IfExpression,
         InvocationExpression, Literal, LiteralOr, LiteralOrVariable, LogicalExpression,
-        LoopExpression, MemberAccessExpression, Spanned, TernaryExpression, WhileExpression,
+        LoopExpression, MemberAccessExpression, Spanned, TernaryExpression,
+        TupleAssignmentExpression, TupleDeclarationExpression, WhileExpression,
     },
 };
 use rust_decimal::Decimal;
@@ -63,6 +64,9 @@ pub enum Error<'a> {
     #[error("Attempted to re-assign a value to a device const `{0}`")]
     DeviceAssignment(Cow<'a, str>, Span),
 
+    #[error("Expected a {0}-tuple, but you're trying to destructure into {1} variables")]
+    TupleSizeMismatch(usize, usize, Span),
+
     #[error("{0}")]
     Unknown(String, Option<Span>),
 }
@@ -84,7 +88,8 @@ impl<'a> From<Error<'a>> for lsp_types::Diagnostic {
             | InvalidDevice(_, span)
             | ConstAssignment(_, span)
             | DeviceAssignment(_, span)
-            | AgrumentMismatch(_, span) => Diagnostic {
+            | AgrumentMismatch(_, span)
+            | TupleSizeMismatch(_, _, span) => Diagnostic {
                 range: span.into(),
                 message: value.to_string(),
                 severity: Some(DiagnosticSeverity::ERROR),
@@ -142,6 +147,8 @@ pub struct Compiler<'a> {
     pub parser: ASTParser<'a>,
     function_locations: HashMap<Cow<'a, str>, usize>,
     function_metadata: HashMap<Cow<'a, str>, Vec<Cow<'a, str>>>,
+    function_tuple_return_sizes: HashMap<Cow<'a, str>, usize>, // Track tuple return sizes
+    current_function_name: Option<Cow<'a, str>>, // Track the function currently being compiled
     devices: HashMap<Cow<'a, str>, Cow<'a, str>>,
 
     // This holds the IL code which will be used in the
@@ -155,6 +162,8 @@ pub struct Compiler<'a> {
     label_counter: usize,
     loop_stack: Vec<(Cow<'a, str>, Cow<'a, str>)>, // Stores (start_label, end_label)
     current_return_label: Option<Cow<'a, str>>,
+    current_return_is_tuple: bool, // Track if the current function returns a tuple
+    current_function_sp_saved: bool, // Track if we've emitted the SP save for the current function
     /// stores (IC10 `line_num`, `Vec<Span>`)
     pub source_map: HashMap<usize, Vec<Span>>,
     /// Accumulative errors from the compilation process
@@ -176,6 +185,10 @@ impl<'a> Compiler<'a> {
             label_counter: 0,
             loop_stack: Vec::new(),
             current_return_label: None,
+            current_return_is_tuple: false,
+            current_function_sp_saved: false,
+            current_function_name: None,
+            function_tuple_return_sizes: HashMap::new(),
             source_map: HashMap::new(),
             errors: Vec::new(),
         }
@@ -465,6 +478,14 @@ impl<'a> Compiler<'a> {
                     temp_name: Some(result_name),
                 }))
             }
+            Expression::TupleDeclaration(tuple_decl) => {
+                self.expression_tuple_declaration(tuple_decl.node, scope)?;
+                Ok(None)
+            }
+            Expression::TupleAssignment(tuple_assign) => {
+                self.expression_tuple_assignment(tuple_assign.node, scope)?;
+                Ok(None)
+            }
             _ => Err(Error::Unknown(
                 format!(
                     "Expression type not yet supported in general expression context: {:?}",
@@ -714,7 +735,12 @@ impl<'a> Compiler<'a> {
 
                         Operand::Register(VariableScope::TEMP_STACK_REGISTER)
                     }
-                    VariableLocation::Constant(_) | VariableLocation::Device(_) => unreachable!(),
+                    VariableLocation::Constant(Literal::Number(num)) => Operand::Number(num.into()),
+                    VariableLocation::Constant(Literal::Boolean(b)) => {
+                        Operand::Number(Number::from(b).into())
+                    }
+                    VariableLocation::Device(_)
+                    | VariableLocation::Constant(Literal::String(_)) => unreachable!(),
                 };
                 self.emit_variable_assignment(&var_loc, src)?;
                 (var_loc, None)
@@ -927,6 +953,504 @@ impl<'a> Compiler<'a> {
         Ok(())
     }
 
+    fn expression_function_invocation_with_invocation(
+        &mut self,
+        invoke_expr: &InvocationExpression<'a>,
+        parent_scope: &mut VariableScope<'a, '_>,
+        backup_registers: bool,
+    ) -> Result<(), Error<'a>> {
+        let InvocationExpression { name, arguments } = invoke_expr;
+
+        if !self.function_locations.contains_key(name.node.as_ref()) {
+            self.errors
+                .push(Error::UnknownIdentifier(name.node.clone(), name.span));
+            return Ok(());
+        }
+
+        let Some(args) = self.function_metadata.get(name.node.as_ref()) else {
+            return Err(Error::UnknownIdentifier(name.node.clone(), name.span));
+        };
+
+        if args.len() != arguments.len() {
+            self.errors
+                .push(Error::AgrumentMismatch(name.node.clone(), name.span));
+            return Ok(());
+        }
+        let mut stack = VariableScope::scoped(parent_scope);
+
+        // Get the list of active registers (may or may not backup)
+        let active_registers = stack.registers();
+
+        // backup all used registers to the stack (unless this is for tuple return handling)
+        if backup_registers {
+            for register in &active_registers {
+                stack.add_variable(
+                    Cow::from(format!("temp_{register}")),
+                    LocationRequest::Stack,
+                    None,
+                )?;
+                self.write_instruction(
+                    Instruction::Push(Operand::Register(*register)),
+                    Some(name.span),
+                )?;
+            }
+        }
+        for arg in arguments {
+            match &arg.node {
+                Expression::Literal(spanned_lit) => match &spanned_lit.node {
+                    Literal::Number(num) => {
+                        self.write_instruction(
+                            Instruction::Push(Operand::Number((*num).into())),
+                            Some(spanned_lit.span),
+                        )?;
+                    }
+                    Literal::Boolean(b) => {
+                        self.write_instruction(
+                            Instruction::Push(Operand::Number(Number::from(*b).into())),
+                            Some(spanned_lit.span),
+                        )?;
+                    }
+                    _ => {}
+                },
+                Expression::Variable(var_name) => {
+                    let loc = match stack.get_location_of(&var_name.node, Some(var_name.span)) {
+                        Ok(l) => l,
+                        Err(_) => {
+                            self.errors.push(Error::UnknownIdentifier(
+                                var_name.node.clone(),
+                                var_name.span,
+                            ));
+                            VariableLocation::Temporary(0)
+                        }
+                    };
+
+                    match loc {
+                        VariableLocation::Persistant(reg) | VariableLocation::Temporary(reg) => {
+                            self.write_instruction(
+                                Instruction::Push(Operand::Register(reg)),
+                                Some(var_name.span),
+                            )?;
+                        }
+                        VariableLocation::Constant(lit) => {
+                            self.write_instruction(
+                                Instruction::Push(extract_literal(lit, false)?),
+                                Some(var_name.span),
+                            )?;
+                        }
+                        VariableLocation::Stack(stack_offset) => {
+                            self.write_instruction(
+                                Instruction::Sub(
+                                    Operand::Register(VariableScope::TEMP_STACK_REGISTER),
+                                    Operand::StackPointer,
+                                    Operand::Number(stack_offset.into()),
+                                ),
+                                Some(var_name.span),
+                            )?;
+
+                            self.write_instruction(
+                                Instruction::Get(
+                                    Operand::Register(VariableScope::TEMP_STACK_REGISTER),
+                                    Operand::Device(Cow::from("db")),
+                                    Operand::Register(VariableScope::TEMP_STACK_REGISTER),
+                                ),
+                                Some(var_name.span),
+                            )?;
+
+                            self.write_instruction(
+                                Instruction::Push(Operand::Register(
+                                    VariableScope::TEMP_STACK_REGISTER,
+                                )),
+                                Some(var_name.span),
+                            )?;
+                        }
+                        VariableLocation::Device(_) => {
+                            self.errors.push(Error::Unknown(
+                                "Device references not supported in function arguments".into(),
+                                Some(var_name.span),
+                            ));
+                        }
+                    }
+                }
+                _ => {
+                    self.errors.push(Error::Unknown(
+                        "Only literals and variables supported in function arguments".into(),
+                        Some(arg.span),
+                    ));
+                }
+            }
+        }
+
+        let Some(_location) = self.function_locations.get(&name.node) else {
+            self.errors
+                .push(Error::UnknownIdentifier(name.node.clone(), name.span));
+            return Ok(());
+        };
+
+        self.write_instruction(
+            Instruction::JumpAndLink(Operand::Label(name.node.clone())),
+            Some(name.span),
+        )?;
+
+        // pop all registers back (if they were backed up)
+        if backup_registers {
+            for register in active_registers.iter().rev() {
+                self.write_instruction(
+                    Instruction::Pop(Operand::Register(*register)),
+                    Some(name.span),
+                )?;
+            }
+        }
+
+        Ok(())
+    }
+
+    fn expression_tuple_declaration(
+        &mut self,
+        tuple_decl: TupleDeclarationExpression<'a>,
+        scope: &mut VariableScope<'a, '_>,
+    ) -> Result<(), Error<'a>> {
+        let TupleDeclarationExpression { names, value } = tuple_decl;
+
+        // Compile the right-hand side expression
+        // For function calls returning tuples:
+        // r15 = pointer to beginning of tuple on stack
+        // r14, r13, ... contain the tuple elements, or they're on the stack
+        match value.node {
+            Expression::Invocation(invoke_expr) => {
+                // Execute the function call
+                // Tuple values are on the stack, sp points after the last pushed value
+                // Pop them in reverse order (from end to beginning)
+                // We don't need to backup registers for tuple returns
+                self.expression_function_invocation_with_invocation(&invoke_expr, scope, false)?;
+
+                // Validate tuple return size matches the declaration
+                let func_name = &invoke_expr.node.name.node;
+                if let Some(&expected_size) = self.function_tuple_return_sizes.get(func_name) {
+                    if names.len() != expected_size {
+                        self.errors.push(Error::TupleSizeMismatch(
+                            expected_size,
+                            names.len(),
+                            value.span,
+                        ));
+                    }
+                }
+
+                // First pass: allocate variables in order
+                let mut var_locations = Vec::new();
+                for name_spanned in names.iter() {
+                    // Skip underscores
+                    if name_spanned.node.as_ref() == "_" {
+                        var_locations.push(None);
+                        continue;
+                    }
+
+                    // Add variable to scope
+                    let var_location = scope.add_variable(
+                        name_spanned.node.clone(),
+                        LocationRequest::Persist,
+                        Some(name_spanned.span),
+                    )?;
+                    var_locations.push(Some(var_location));
+                }
+
+                // Second pass: pop in reverse order through the list (since stack is LIFO)
+                // var_locations[0] is the first element (bottom of stack)
+                // var_locations[n-1] is the last element (top of stack)
+                // We pop from the top, so we iterate in reverse through var_locations
+                for (idx, var_loc_opt) in var_locations.iter().enumerate().rev() {
+                    match var_loc_opt {
+                        Some(var_location) => {
+                            let var_reg = self.resolve_register(&var_location)?;
+
+                            // Pop from stack into the variable's register
+                            self.write_instruction(
+                                Instruction::Pop(Operand::Register(var_reg)),
+                                Some(names[idx].span),
+                            )?;
+                        }
+                        None => {
+                            // Underscore: pop into temp register to discard
+                            self.write_instruction(
+                                Instruction::Pop(Operand::Register(
+                                    VariableScope::TEMP_STACK_REGISTER,
+                                )),
+                                Some(names[idx].span),
+                            )?;
+                        }
+                    }
+                }
+
+                // Restore stack pointer to value saved at function entry
+                self.write_instruction(
+                    Instruction::Move(
+                        Operand::StackPointer,
+                        Operand::Register(VariableScope::RETURN_REGISTER),
+                    ),
+                    Some(value.span),
+                )?;
+            }
+            Expression::Tuple(tuple_expr) => {
+                // Direct tuple literal: (value1, value2, ...)
+                let tuple_elements = tuple_expr.node;
+
+                // Validate tuple size matches names
+                if tuple_elements.len() != names.len() {
+                    return Err(Error::TupleSizeMismatch(
+                        names.len(),
+                        tuple_elements.len(),
+                        value.span,
+                    ));
+                }
+
+                // Compile each element and assign to corresponding variable
+                for (name_spanned, element) in names.into_iter().zip(tuple_elements.into_iter()) {
+                    // Skip underscores
+                    if name_spanned.node.as_ref() == "_" {
+                        continue;
+                    }
+
+                    // Add variable to scope
+                    let var_location = scope.add_variable(
+                        name_spanned.node.clone(),
+                        LocationRequest::Persist,
+                        Some(name_spanned.span),
+                    )?;
+
+                    // Compile the element expression - use compile_operand to handle all expression types
+                    let (value_operand, cleanup) = self.compile_operand(element, scope)?;
+                    self.emit_variable_assignment(&var_location, value_operand)?;
+
+                    // Clean up any temporary registers used for complex expressions
+                    if let Some(temp_name) = cleanup {
+                        scope.free_temp(temp_name, None)?;
+                    }
+                }
+            }
+            _ => {
+                return Err(Error::Unknown(
+                    "Tuple declaration only supports function invocations or tuple literals as RHS"
+                        .into(),
+                    Some(value.span),
+                ));
+            }
+        }
+
+        Ok(())
+    }
+
+    fn expression_tuple_assignment(
+        &mut self,
+        tuple_assign: TupleAssignmentExpression<'a>,
+        scope: &mut VariableScope<'a, '_>,
+    ) -> Result<(), Error<'a>> {
+        let TupleAssignmentExpression { names, value } = tuple_assign;
+
+        // Similar to tuple declaration, but variables must already exist
+        match value.node {
+            Expression::Invocation(invoke_expr) => {
+                // Execute the function call
+                // Tuple values are on the stack, sp points after the last pushed value
+                // Pop them in reverse order (from end to beginning)
+                // We don't need to backup registers for tuple returns
+                self.expression_function_invocation_with_invocation(&invoke_expr, scope, false)?;
+
+                // Validate tuple return size matches the assignment
+                let func_name = &invoke_expr.node.name.node;
+                if let Some(&expected_size) = self.function_tuple_return_sizes.get(func_name) {
+                    if names.len() != expected_size {
+                        self.errors.push(Error::TupleSizeMismatch(
+                            expected_size,
+                            names.len(),
+                            value.span,
+                        ));
+                    }
+                }
+
+                // First pass: look up variable locations
+                let mut var_locs = Vec::new();
+                for name_spanned in names.iter() {
+                    // Skip underscores
+                    if name_spanned.node.as_ref() == "_" {
+                        var_locs.push(None);
+                        continue;
+                    }
+
+                    // Get the existing variable location
+                    let var_location =
+                        match scope.get_location_of(&name_spanned.node, Some(name_spanned.span)) {
+                            Ok(l) => l,
+                            Err(_) => {
+                                self.errors.push(Error::UnknownIdentifier(
+                                    name_spanned.node.clone(),
+                                    name_spanned.span,
+                                ));
+                                VariableLocation::Temporary(0)
+                            }
+                        };
+                    var_locs.push(Some(var_location));
+                }
+
+                // Second pass: pop in reverse order and assign
+                for (idx, var_loc_opt) in var_locs.iter().enumerate().rev() {
+                    if let Some(var_location) = var_loc_opt {
+                        // Pop from stack and assign to variable
+                        match var_location {
+                            VariableLocation::Temporary(reg)
+                            | VariableLocation::Persistant(reg) => {
+                                // Pop directly into the variable's register
+                                self.write_instruction(
+                                    Instruction::Pop(Operand::Register(*reg)),
+                                    Some(names[idx].span),
+                                )?;
+                            }
+                            VariableLocation::Stack(offset) => {
+                                // Pop into temp register, then write to variable stack
+                                self.write_instruction(
+                                    Instruction::Pop(Operand::Register(
+                                        VariableScope::TEMP_STACK_REGISTER,
+                                    )),
+                                    Some(names[idx].span),
+                                )?;
+
+                                // Write to variable stack location
+                                self.write_instruction(
+                                    Instruction::Sub(
+                                        Operand::Register(0),
+                                        Operand::StackPointer,
+                                        Operand::Number((*offset).into()),
+                                    ),
+                                    Some(names[idx].span),
+                                )?;
+
+                                self.write_instruction(
+                                    Instruction::Put(
+                                        Operand::Device(Cow::from("db")),
+                                        Operand::Register(0),
+                                        Operand::Register(VariableScope::TEMP_STACK_REGISTER),
+                                    ),
+                                    Some(names[idx].span),
+                                )?;
+                            }
+                            VariableLocation::Constant(_) => {
+                                return Err(Error::ConstAssignment(
+                                    names[idx].node.clone(),
+                                    names[idx].span,
+                                ));
+                            }
+                            VariableLocation::Device(_) => {
+                                return Err(Error::DeviceAssignment(
+                                    names[idx].node.clone(),
+                                    names[idx].span,
+                                ));
+                            }
+                        }
+                    }
+                }
+
+                // Restore stack pointer to value saved at function entry
+                self.write_instruction(
+                    Instruction::Move(
+                        Operand::StackPointer,
+                        Operand::Register(VariableScope::RETURN_REGISTER),
+                    ),
+                    Some(value.span),
+                )?;
+            }
+            Expression::Tuple(tuple_expr) => {
+                // Direct tuple literal: (value1, value2, ...)
+                let tuple_elements = tuple_expr.node;
+
+                // Validate tuple size matches names
+                if tuple_elements.len() != names.len() {
+                    return Err(Error::TupleSizeMismatch(
+                        tuple_elements.len(),
+                        names.len(),
+                        value.span,
+                    ));
+                }
+
+                // Compile each element and assign to corresponding variable
+                for (name_spanned, element) in names.into_iter().zip(tuple_elements.into_iter()) {
+                    // Skip underscores
+                    if name_spanned.node.as_ref() == "_" {
+                        continue;
+                    }
+
+                    // Get the existing variable location
+                    let var_location =
+                        match scope.get_location_of(&name_spanned.node, Some(name_spanned.span)) {
+                            Ok(l) => l,
+                            Err(_) => {
+                                self.errors.push(Error::UnknownIdentifier(
+                                    name_spanned.node.clone(),
+                                    name_spanned.span,
+                                ));
+                                VariableLocation::Temporary(0)
+                            }
+                        };
+
+                    // Compile the element expression - use compile_operand to handle all expression types
+                    let (value_operand, cleanup) = self.compile_operand(element, scope)?;
+
+                    // Assign the compiled value to the target variable location
+                    match &var_location {
+                        VariableLocation::Temporary(reg) | VariableLocation::Persistant(reg) => {
+                            self.write_instruction(
+                                Instruction::Move(Operand::Register(*reg), value_operand),
+                                Some(name_spanned.span),
+                            )?;
+                        }
+                        VariableLocation::Stack(offset) => {
+                            self.write_instruction(
+                                Instruction::Sub(
+                                    Operand::Register(VariableScope::TEMP_STACK_REGISTER),
+                                    Operand::StackPointer,
+                                    Operand::Number((*offset).into()),
+                                ),
+                                Some(name_spanned.span),
+                            )?;
+
+                            self.write_instruction(
+                                Instruction::Put(
+                                    Operand::Device(Cow::from("db")),
+                                    Operand::Register(VariableScope::TEMP_STACK_REGISTER),
+                                    value_operand,
+                                ),
+                                Some(name_spanned.span),
+                            )?;
+                        }
+                        VariableLocation::Constant(_) => {
+                            return Err(Error::ConstAssignment(
+                                name_spanned.node.clone(),
+                                name_spanned.span,
+                            ));
+                        }
+                        VariableLocation::Device(_) => {
+                            return Err(Error::DeviceAssignment(
+                                name_spanned.node.clone(),
+                                name_spanned.span,
+                            ));
+                        }
+                    }
+
+                    // Clean up any temporary registers used for complex expressions
+                    if let Some(temp_name) = cleanup {
+                        scope.free_temp(temp_name, None)?;
+                    }
+                }
+            }
+            _ => {
+                return Err(Error::Unknown(
+                    "Tuple assignment only supports function invocations or tuple literals as RHS"
+                        .into(),
+                    Some(value.span),
+                ));
+            }
+        }
+
+        Ok(())
+    }
+
     fn expression_function_invocation(
         &mut self,
         invoke_expr: Spanned<InvocationExpression<'a>>,
@@ -1941,6 +2465,169 @@ impl<'a> Compiler<'a> {
                         }
                     }
                 }
+                Expression::Tuple(tuple_expr) => {
+                    let span = expr.span;
+                    let tuple_elements = &tuple_expr.node;
+
+                    // Record the stack offset where the tuple will start
+                    let tuple_start_offset = scope.stack_offset();
+
+                    // First pass: Add temporary variables to scope for each tuple element
+                    // This updates the scope's stack_offset so we can calculate ra position later
+                    let mut temp_names = Vec::new();
+                    for (i, _element) in tuple_elements.iter().enumerate() {
+                        let temp_name = format!("__tuple_ret_{}", i);
+                        scope.add_variable(
+                            temp_name.clone().into(),
+                            LocationRequest::Stack,
+                            Some(span),
+                        )?;
+                        temp_names.push(temp_name);
+                    }
+
+                    // Second pass: Push the actual values onto the stack
+                    for element in tuple_elements.iter() {
+                        match &element.node {
+                            Expression::Literal(lit) => {
+                                let value_operand = extract_literal(lit.node.clone(), false)?;
+                                self.write_instruction(
+                                    Instruction::Push(value_operand),
+                                    Some(span),
+                                )?;
+                            }
+                            Expression::Variable(var) => {
+                                let var_loc = match scope.get_location_of(&var.node, Some(var.span))
+                                {
+                                    Ok(l) => l,
+                                    Err(_) => {
+                                        self.errors.push(Error::UnknownIdentifier(
+                                            var.node.clone(),
+                                            var.span,
+                                        ));
+                                        VariableLocation::Temporary(0)
+                                    }
+                                };
+
+                                match &var_loc {
+                                    VariableLocation::Temporary(reg)
+                                    | VariableLocation::Persistant(reg) => {
+                                        self.write_instruction(
+                                            Instruction::Push(Operand::Register(*reg)),
+                                            Some(span),
+                                        )?;
+                                    }
+                                    VariableLocation::Constant(lit) => {
+                                        let value_operand = extract_literal(lit.clone(), false)?;
+                                        self.write_instruction(
+                                            Instruction::Push(value_operand),
+                                            Some(span),
+                                        )?;
+                                    }
+                                    VariableLocation::Stack(offset) => {
+                                        self.write_instruction(
+                                            Instruction::Sub(
+                                                Operand::Register(
+                                                    VariableScope::TEMP_STACK_REGISTER,
+                                                ),
+                                                Operand::StackPointer,
+                                                Operand::Number((*offset).into()),
+                                            ),
+                                            Some(span),
+                                        )?;
+                                        self.write_instruction(
+                                            Instruction::Get(
+                                                Operand::Register(
+                                                    VariableScope::TEMP_STACK_REGISTER,
+                                                ),
+                                                Operand::Device(Cow::from("db")),
+                                                Operand::Register(
+                                                    VariableScope::TEMP_STACK_REGISTER,
+                                                ),
+                                            ),
+                                            Some(span),
+                                        )?;
+                                        self.write_instruction(
+                                            Instruction::Push(Operand::Register(
+                                                VariableScope::TEMP_STACK_REGISTER,
+                                            )),
+                                            Some(span),
+                                        )?;
+                                    }
+                                    VariableLocation::Device(_) => {
+                                        return Err(Error::Unknown(
+                                            "You can not return a device from a function.".into(),
+                                            Some(var.span),
+                                        ));
+                                    }
+                                }
+                            }
+                            _ => {
+                                // For complex expressions, just push 0 for now
+                                self.write_instruction(
+                                    Instruction::Push(Operand::Number(
+                                        Number::Integer(0, Unit::None).into(),
+                                    )),
+                                    Some(span),
+                                )?;
+                            }
+                        }
+                    }
+
+                    // Store the pointer to the tuple (stack offset) in r15
+                    self.write_instruction(
+                        Instruction::Move(
+                            Operand::Register(VariableScope::RETURN_REGISTER),
+                            Operand::Number(tuple_start_offset.into()),
+                        ),
+                        Some(span),
+                    )?;
+
+                    // For tuple returns, ra is buried under the tuple values on the stack.
+                    // Stack layout: [ra, val0, val1, val2, ...]
+                    // Instead of popping and pushing, use Get to read ra from its stack position
+                    // while leaving the tuple values in place.
+
+                    // Calculate offset to ra from current stack position
+                    // ra is at tuple_start_offset - 1, so offset = (current - tuple_start) + 1
+                    let current_offset = scope.stack_offset();
+                    let ra_offset_from_current = (current_offset - tuple_start_offset + 1) as i32;
+
+                    // Use a temp register to read ra from the stack
+                    if ra_offset_from_current > 0 {
+                        self.write_instruction(
+                            Instruction::Sub(
+                                Operand::Register(VariableScope::TEMP_STACK_REGISTER),
+                                Operand::StackPointer,
+                                Operand::Number(ra_offset_from_current.into()),
+                            ),
+                            Some(span),
+                        )?;
+
+                        self.write_instruction(
+                            Instruction::Get(
+                                Operand::ReturnAddress,
+                                Operand::Device(Cow::from("db")),
+                                Operand::Register(VariableScope::TEMP_STACK_REGISTER),
+                            ),
+                            Some(span),
+                        )?;
+                    }
+
+                    // Jump back to caller
+                    self.write_instruction(Instruction::Jump(Operand::ReturnAddress), Some(span))?;
+
+                    // Mark that we had a tuple return so the function declaration can skip return label cleanup
+                    self.current_return_is_tuple = true;
+
+                    // Record the tuple return size for validation at call sites
+                    if let Some(func_name) = &self.current_function_name {
+                        self.function_tuple_return_sizes
+                            .insert(func_name.clone(), tuple_elements.len());
+                    }
+
+                    // Early return to skip the normal return label processing
+                    return Ok(VariableLocation::Persistant(VariableScope::RETURN_REGISTER));
+                }
                 _ => {
                     return Err(Error::Unknown(
                         format!("Unsupported `return` statement: {:?}", expr),
@@ -2569,6 +3256,78 @@ impl<'a> Compiler<'a> {
         }
     }
 
+    /// Check if a function body contains any tuple returns
+    fn has_tuple_return(body: &BlockExpression) -> bool {
+        for expr in &body.0 {
+            match &expr.node {
+                Expression::Return(Some(ret_expr)) => {
+                    if let Expression::Tuple(_) = &ret_expr.node {
+                        return true;
+                    }
+                }
+                Expression::If(if_expr) => {
+                    // Check the then block
+                    if Self::has_tuple_return(&if_expr.node.body.node) {
+                        return true;
+                    }
+                    // Check the else branch if it exists
+                    if let Some(else_branch) = &if_expr.node.else_branch {
+                        match &else_branch.node {
+                            Expression::Block(block) => {
+                                if Self::has_tuple_return(block) {
+                                    return true;
+                                }
+                            }
+                            Expression::If(_) => {
+                                // Handle else-if chains
+                                if Self::has_tuple_return_in_expr(else_branch) {
+                                    return true;
+                                }
+                            }
+                            _ => {}
+                        }
+                    }
+                }
+                Expression::While(while_expr) => {
+                    if Self::has_tuple_return(&while_expr.node.body) {
+                        return true;
+                    }
+                }
+                Expression::Loop(loop_expr) => {
+                    if Self::has_tuple_return(&loop_expr.node.body.node) {
+                        return true;
+                    }
+                }
+                Expression::Block(block) => {
+                    if Self::has_tuple_return(block) {
+                        return true;
+                    }
+                }
+                _ => {}
+            }
+        }
+        false
+    }
+
+    /// Helper to check for tuple returns in any expression
+    fn has_tuple_return_in_expr(expr: &Spanned<Expression>) -> bool {
+        match &expr.node {
+            Expression::Block(block) => Self::has_tuple_return(block),
+            Expression::If(if_expr) => {
+                if Self::has_tuple_return(&if_expr.node.body.node) {
+                    return true;
+                }
+                if let Some(else_branch) = &if_expr.node.else_branch {
+                    return Self::has_tuple_return_in_expr(else_branch);
+                }
+                false
+            }
+            Expression::While(while_expr) => Self::has_tuple_return(&while_expr.node.body),
+            Expression::Loop(loop_expr) => Self::has_tuple_return(&loop_expr.node.body.node),
+            _ => false,
+        }
+    }
+
     /// Compile a function declaration.
     /// Calees are responsible for backing up any registers they wish to use.
     fn expression_function(
@@ -2596,6 +3355,9 @@ impl<'a> Compiler<'a> {
             arguments.iter().map(|a| a.node.clone()).collect(),
         );
 
+        // Set the current function being compiled
+        self.current_function_name = Some(name.node.clone());
+
         // Declare the function as a line identifier
         self.write_instruction(Instruction::LabelDef(name.node.clone()), Some(span))?;
 
@@ -2657,6 +3419,18 @@ impl<'a> Compiler<'a> {
             )?;
         }
 
+        // If this function has tuple returns, save the SP to r15 before pushing ra
+        if Self::has_tuple_return(&body) {
+            self.write_instruction(
+                Instruction::Move(
+                    Operand::Register(VariableScope::RETURN_REGISTER),
+                    Operand::StackPointer,
+                ),
+                Some(span),
+            )?;
+            self.current_function_sp_saved = true;
+        }
+
         self.write_instruction(Instruction::Push(Operand::ReturnAddress), Some(span))?;
 
         let return_label = self.next_label_name();
@@ -2710,54 +3484,63 @@ impl<'a> Compiler<'a> {
 
         self.current_return_label = prev_return_label;
 
-        self.write_instruction(Instruction::LabelDef(return_label.clone()), Some(span))?;
+        // Only write the return label if this function doesn't have a tuple return
+        // (tuple returns handle their own pop ra and return)
+        if !self.current_return_is_tuple {
+            self.write_instruction(Instruction::LabelDef(return_label.clone()), Some(span))?;
 
-        if ra_stack_offset == 1 {
-            self.write_instruction(Instruction::Pop(Operand::ReturnAddress), Some(span))?;
+            if ra_stack_offset == 1 {
+                self.write_instruction(Instruction::Pop(Operand::ReturnAddress), Some(span))?;
 
-            let remaining_cleanup = block_scope.stack_offset() - 1;
-            if remaining_cleanup > 0 {
+                let remaining_cleanup = block_scope.stack_offset() - 1;
+                if remaining_cleanup > 0 {
+                    self.write_instruction(
+                        Instruction::Sub(
+                            Operand::StackPointer,
+                            Operand::StackPointer,
+                            Operand::Number(remaining_cleanup.into()),
+                        ),
+                        Some(span),
+                    )?;
+                }
+            } else {
                 self.write_instruction(
                     Instruction::Sub(
+                        Operand::Register(VariableScope::TEMP_STACK_REGISTER),
                         Operand::StackPointer,
-                        Operand::StackPointer,
-                        Operand::Number(remaining_cleanup.into()),
+                        Operand::Number(ra_stack_offset.into()),
                     ),
                     Some(span),
                 )?;
-            }
-        } else {
-            self.write_instruction(
-                Instruction::Sub(
-                    Operand::Register(VariableScope::TEMP_STACK_REGISTER),
-                    Operand::StackPointer,
-                    Operand::Number(ra_stack_offset.into()),
-                ),
-                Some(span),
-            )?;
 
-            self.write_instruction(
-                Instruction::Get(
-                    Operand::ReturnAddress,
-                    Operand::Device(Cow::from("db")),
-                    Operand::Register(VariableScope::TEMP_STACK_REGISTER),
-                ),
-                Some(span),
-            )?;
-
-            if block_scope.stack_offset() > 0 {
                 self.write_instruction(
-                    Instruction::Sub(
-                        Operand::StackPointer,
-                        Operand::StackPointer,
-                        Operand::Number(block_scope.stack_offset().into()),
+                    Instruction::Get(
+                        Operand::ReturnAddress,
+                        Operand::Device(Cow::from("db")),
+                        Operand::Register(VariableScope::TEMP_STACK_REGISTER),
                     ),
                     Some(span),
                 )?;
+
+                if block_scope.stack_offset() > 0 {
+                    self.write_instruction(
+                        Instruction::Sub(
+                            Operand::StackPointer,
+                            Operand::StackPointer,
+                            Operand::Number(block_scope.stack_offset().into()),
+                        ),
+                        Some(span),
+                    )?;
+                }
             }
+
+            self.write_instruction(Instruction::Jump(Operand::ReturnAddress), Some(span))?;
         }
 
-        self.write_instruction(Instruction::Jump(Operand::ReturnAddress), Some(span))?;
+        // Reset the flag for the next function
+        self.current_return_is_tuple = false;
+        self.current_function_sp_saved = false;
+        self.current_function_name = None;
         Ok(())
     }
 }

rust_compiler/libs/parser/src/lib.rs

@@ -441,7 +441,13 @@ impl<'a> Parser<'a> {
                 ));
             }
 
-            TokenType::Keyword(Keyword::Let) => Some(self.spanned(|p| p.declaration())?),
+            TokenType::Keyword(Keyword::Let) => {
+                if self_matches_peek!(self, TokenType::Symbol(Symbol::LParen)) {
+                    Some(self.spanned(|p| p.tuple_declaration())?)
+                } else {
+                    Some(self.spanned(|p| p.declaration())?)
+                }
+            }
 
             TokenType::Keyword(Keyword::Device) => {
                 let spanned_dev = self.spanned(|p| p.device())?;
@@ -561,9 +567,7 @@ impl<'a> Parser<'a> {
                 })
             }
 
-            TokenType::Symbol(Symbol::LParen) => {
-                self.spanned(|p| p.priority())?.node.map(|node| *node)
-            }
+            TokenType::Symbol(Symbol::LParen) => self.parenthesized_or_tuple()?,
 
             TokenType::Symbol(Symbol::Minus) => {
                 let start_span = self.current_span();
@@ -642,8 +646,8 @@ impl<'a> Parser<'a> {
                 }
             }
             TokenType::Symbol(Symbol::LParen) => *self
-                .spanned(|p| p.priority())?
-                .node
+                .parenthesized_or_tuple()?
+                .map(Box::new)
                 .ok_or(Error::UnexpectedEOF)?,
 
             TokenType::Identifier(ref id) if SysCall::is_syscall(id) => {
@@ -774,7 +778,8 @@ impl<'a> Parser<'a> {
             | Expression::Ternary(_)
             | Expression::Negation(_)
             | Expression::MemberAccess(_)
-            | Expression::MethodCall(_) => {}
+            | Expression::MethodCall(_)
+            | Expression::Tuple(_) => {}
             _ => {
                 return Err(Error::InvalidSyntax(
                     self.current_span(),
@@ -1081,19 +1086,39 @@ impl<'a> Parser<'a> {
                     end_col: right.span.end_col,
                 };
 
-                expressions.insert(
-                    i,
-                    Spanned {
+                // Check if the left side is a tuple, and if so, create a TupleAssignment
+                let node = if let Expression::Tuple(tuple_expr) = &left.node {
+                    // Extract variable names from the tuple, handling underscores
+                    let mut names = Vec::new();
+                    for item in &tuple_expr.node {
+                        if let Expression::Variable(var) = &item.node {
+                            names.push(var.clone());
+                        } else {
+                            return Err(Error::InvalidSyntax(
+                                item.span,
+                                String::from("Tuple assignment can only contain variable names"),
+                            ));
+                        }
+                    }
+
+                    Expression::TupleAssignment(Spanned {
                         span,
-                        node: Expression::Assignment(Spanned {
-                            span,
-                            node: AssignmentExpression {
-                                assignee: boxed!(left),
-                                expression: boxed!(right),
-                            },
-                        }),
-                    },
-                );
+                        node: TupleAssignmentExpression {
+                            names,
+                            value: boxed!(right),
+                        },
+                    })
+                } else {
+                    Expression::Assignment(Spanned {
+                        span,
+                        node: AssignmentExpression {
+                            assignee: boxed!(left),
+                            expression: boxed!(right),
+                        },
+                    })
+                };
+
+                expressions.insert(i, Spanned { span, node });
             }
         }
         operators.retain(|symbol| !matches!(symbol, Symbol::Assign));
@@ -1117,8 +1142,12 @@ impl<'a> Parser<'a> {
         expressions.pop().ok_or(Error::UnexpectedEOF)
     }
 
-    fn priority(&mut self) -> Result<Option<Box<Spanned<Expression<'a>>>>, Error<'a>> {
+    fn parenthesized_or_tuple(
+        &mut self,
+    ) -> Result<Option<Spanned<tree_node::Expression<'a>>>, Error<'a>> {
+        let start_span = self.current_span();
         let current_token = self.current_token.as_ref().ok_or(Error::UnexpectedEOF)?;
+
         if !token_matches!(current_token, TokenType::Symbol(Symbol::LParen)) {
             return Err(Error::UnexpectedToken(
                 self.current_span(),
@@ -1127,17 +1156,112 @@ impl<'a> Parser<'a> {
         }
 
         self.assign_next()?;
-        let expression = self.expression()?.ok_or(Error::UnexpectedEOF)?;
 
-        let current_token = self.get_next()?.ok_or(Error::UnexpectedEOF)?;
-        if !token_matches!(current_token, TokenType::Symbol(Symbol::RParen)) {
-            return Err(Error::UnexpectedToken(
-                Self::token_to_span(&current_token),
-                current_token,
-            ));
+        // Handle empty tuple '()'
+        if self_matches_peek!(self, TokenType::Symbol(Symbol::RParen)) {
+            self.assign_next()?;
+            let end_span = self.current_span();
+            let span = Span {
+                start_line: start_span.start_line,
+                start_col: start_span.start_col,
+                end_line: end_span.end_line,
+                end_col: end_span.end_col,
+            };
+            return Ok(Some(Spanned {
+                span,
+                node: Expression::Tuple(Spanned { span, node: vec![] }),
+            }));
         }
 
-        Ok(Some(boxed!(expression)))
+        let first_expression = self.expression()?.ok_or(Error::UnexpectedEOF)?;
+
+        if self_matches_peek!(self, TokenType::Symbol(Symbol::Comma)) {
+            // It is a tuple
+            let mut items = vec![first_expression];
+            while self_matches_peek!(self, TokenType::Symbol(Symbol::Comma)) {
+                // Next toekn is a comma, we need to consume it and advance 1 more time.
+                self.assign_next()?;
+                self.assign_next()?;
+                items.push(self.expression()?.ok_or(Error::UnexpectedEOF)?);
+            }
+
+            let next = self.get_next()?.ok_or(Error::UnexpectedEOF)?;
+            if !token_matches!(next, TokenType::Symbol(Symbol::RParen)) {
+                return Err(Error::UnexpectedToken(Self::token_to_span(&next), next));
+            }
+
+            let end_span = Self::token_to_span(&next);
+            let span = Span {
+                start_line: start_span.start_line,
+                start_col: start_span.start_col,
+                end_line: end_span.end_line,
+                end_col: end_span.end_col,
+            };
+
+            Ok(Some(Spanned {
+                span,
+                node: Expression::Tuple(Spanned { span, node: items }),
+            }))
+        } else {
+            // It is just priority
+            let next = self.get_next()?.ok_or(Error::UnexpectedEOF)?;
+            if !token_matches!(next, TokenType::Symbol(Symbol::RParen)) {
+                return Err(Error::UnexpectedToken(Self::token_to_span(&next), next));
+            }
+
+            Ok(Some(Spanned {
+                span: first_expression.span,
+                node: Expression::Priority(boxed!(first_expression)),
+            }))
+        }
+    }
+
+    fn tuple_declaration(&mut self) -> Result<Expression<'a>, Error<'a>> {
+        // 'let' is consumed before this call
+        // expect '('
+        let next = self.get_next()?.ok_or(Error::UnexpectedEOF)?;
+        if !token_matches!(next, TokenType::Symbol(Symbol::LParen)) {
+            return Err(Error::UnexpectedToken(Self::token_to_span(&next), next));
+        }
+
+        let mut names = Vec::new();
+        while !self_matches_peek!(self, TokenType::Symbol(Symbol::RParen)) {
+            let token = self.get_next()?.ok_or(Error::UnexpectedEOF)?;
+            let span = Self::token_to_span(&token);
+            if let TokenType::Identifier(id) = token.token_type {
+                names.push(Spanned { span, node: id });
+            } else {
+                return Err(Error::UnexpectedToken(span, token));
+            }
+
+            if self_matches_peek!(self, TokenType::Symbol(Symbol::Comma)) {
+                self.assign_next()?;
+            }
+        }
+        self.assign_next()?; // consume ')'
+
+        let assign = self.get_next()?.ok_or(Error::UnexpectedEOF)?;
+
+        if !token_matches!(assign, TokenType::Symbol(Symbol::Assign)) {
+            return Err(Error::UnexpectedToken(Self::token_to_span(&assign), assign));
+        }
+
+        self.assign_next()?; // Consume the `=`
+
+        let value = self.expression()?.ok_or(Error::UnexpectedEOF)?;
+
+        let semi = self.get_next()?.ok_or(Error::UnexpectedEOF)?;
+        if !token_matches!(semi, TokenType::Symbol(Symbol::Semicolon)) {
+            return Err(Error::UnexpectedToken(Self::token_to_span(&semi), semi));
+        }
+
+        Ok(Expression::TupleDeclaration(Spanned {
+            span: names.first().map(|n| n.span).unwrap_or(value.span),
+            node: TupleDeclarationExpression {
+                names,
+                value: boxed!(value),
+            },
+        }))
     }
 
     fn invocation(&mut self) -> Result<InvocationExpression<'a>, Error<'a>> {

rust_compiler/libs/parser/src/test/mod.rs

@@ -112,7 +112,7 @@ fn test_function_invocation() -> Result<()> {
 #[test]
 fn test_priority_expression() -> Result<()> {
     let input = r#"
-            let x = (4);
+            let x = (4 + 3);
         "#;
 
     let tokenizer = Tokenizer::from(input);
@@ -120,7 +120,7 @@ fn test_priority_expression() -> Result<()> {
 
     let expression = parser.parse()?.unwrap();
 
-    assert_eq!("(let x = 4)", expression.to_string());
+    assert_eq!("(let x = ((4 + 3)))", expression.to_string());
 
     Ok(())
 }
@@ -137,7 +137,7 @@ fn test_binary_expression() -> Result<()> {
     assert_eq!("(((45 * 2) - (15 / 5)) + (5 ** 2))", expr.to_string());
 
     let expr = parser!("(5 - 2) * 10;").parse()?.unwrap();
-    assert_eq!("((5 - 2) * 10)", expr.to_string());
+    assert_eq!("(((5 - 2)) * 10)", expr.to_string());
 
     Ok(())
 }
@@ -170,7 +170,7 @@ fn test_ternary_expression() -> Result<()> {
 fn test_complex_binary_with_ternary() -> Result<()> {
     let expr = parser!("let i = (x ? 1 : 3) * 2;").parse()?.unwrap();
 
-    assert_eq!("(let i = ((x ? 1 : 3) * 2))", expr.to_string());
+    assert_eq!("(let i = (((x ? 1 : 3)) * 2))", expr.to_string());
 
     Ok(())
 }
@@ -191,3 +191,99 @@ fn test_nested_ternary_right_associativity() -> Result<()> {
     assert_eq!("(let i = (a ? b : (c ? d : e)))", expr.to_string());
     Ok(())
 }
+
+#[test]
+fn test_tuple_declaration() -> Result<()> {
+    let expr = parser!("let (x, _) = (1, 2);").parse()?.unwrap();
+
+    assert_eq!("(let (x, _) = (1, 2))", expr.to_string());
+
+    Ok(())
+}
+#[test]
+fn test_tuple_assignment() -> Result<()> {
+    let expr = parser!("(x, y) = (1, 2);").parse()?.unwrap();
+
+    assert_eq!("((x, y) = (1, 2))", expr.to_string());
+
+    Ok(())
+}
+
+#[test]
+fn test_tuple_assignment_with_underscore() -> Result<()> {
+    let expr = parser!("(x, _) = (1, 2);").parse()?.unwrap();
+
+    assert_eq!("((x, _) = (1, 2))", expr.to_string());
+
+    Ok(())
+}
+
+#[test]
+fn test_tuple_declaration_with_function_call() -> Result<()> {
+    let expr = parser!("let (x, y) = doSomething();").parse()?.unwrap();
+
+    assert_eq!("(let (x, y) = doSomething())", expr.to_string());
+
+    Ok(())
+}
+
+#[test]
+fn test_tuple_declaration_with_function_call_with_underscore() -> Result<()> {
+    let expr = parser!("let (x, _) = doSomething();").parse()?.unwrap();
+
+    assert_eq!("(let (x, _) = doSomething())", expr.to_string());
+
+    Ok(())
+}
+
+#[test]
+fn test_tuple_assignment_with_function_call() -> Result<()> {
+    let expr = parser!("(x, y) = doSomething();").parse()?.unwrap();
+
+    assert_eq!("((x, y) = doSomething())", expr.to_string());
+
+    Ok(())
+}
+
+#[test]
+fn test_tuple_assignment_with_function_call_with_underscore() -> Result<()> {
+    let expr = parser!("(x, _) = doSomething();").parse()?.unwrap();
+
+    assert_eq!("((x, _) = doSomething())", expr.to_string());
+
+    Ok(())
+}
+
+#[test]
+fn test_tuple_declaration_with_complex_expressions() -> Result<()> {
+    let expr = parser!("let (x, y) = (1 + 1, doSomething());")
+        .parse()?
+        .unwrap();
+
+    assert_eq!("(let (x, y) = ((1 + 1), doSomething()))", expr.to_string());
+
+    Ok(())
+}
+
+#[test]
+fn test_tuple_assignment_with_complex_expressions() -> Result<()> {
+    let expr = parser!("(x, y) = (doSomething(), 123 / someValue.Setting);")
+        .parse()?
+        .unwrap();
+
+    assert_eq!(
+        "((x, y) = (doSomething(), (123 / someValue.Setting)))",
+        expr.to_string()
+    );
+
+    Ok(())
+}
+
+#[test]
+fn test_tuple_declaration_all_complex_expressions() -> Result<()> {
+    let expr = parser!("let (x, y) = (a + b, c * d);").parse()?.unwrap();
+
+    assert_eq!("(let (x, y) = ((a + b), (c * d)))", expr.to_string());
+
+    Ok(())
+}

rust_compiler/libs/parser/src/tree_node.rs

@@ -245,6 +245,42 @@ impl<'a> std::fmt::Display for DeviceDeclarationExpression<'a> {
     }
 }
 
+#[derive(Debug, PartialEq, Eq)]
+pub struct TupleDeclarationExpression<'a> {
+    pub names: Vec<Spanned<Cow<'a, str>>>,
+    pub value: Box<Spanned<Expression<'a>>>,
+}
+
+impl<'a> std::fmt::Display for TupleDeclarationExpression<'a> {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        let names = self
+            .names
+            .iter()
+            .map(|n| n.node.to_string())
+            .collect::<Vec<_>>()
+            .join(", ");
+        write!(f, "(let ({}) = {})", names, self.value)
+    }
+}
+
+#[derive(Debug, PartialEq, Eq)]
+pub struct TupleAssignmentExpression<'a> {
+    pub names: Vec<Spanned<Cow<'a, str>>>,
+    pub value: Box<Spanned<Expression<'a>>>,
+}
+
+impl<'a> std::fmt::Display for TupleAssignmentExpression<'a> {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        let names = self
+            .names
+            .iter()
+            .map(|n| n.node.to_string())
+            .collect::<Vec<_>>()
+            .join(", ");
+        write!(f, "(({}) = {})", names, self.value)
+    }
+}
+
 #[derive(Debug, PartialEq, Eq)]
 pub struct IfExpression<'a> {
     pub condition: Box<Spanned<Expression<'a>>>,
@@ -348,6 +384,9 @@ pub enum Expression<'a> {
     Return(Option<Box<Spanned<Expression<'a>>>>),
     Syscall(Spanned<SysCall<'a>>),
     Ternary(Spanned<TernaryExpression<'a>>),
+    Tuple(Spanned<Vec<Spanned<Expression<'a>>>>),
+    TupleAssignment(Spanned<TupleAssignmentExpression<'a>>),
+    TupleDeclaration(Spanned<TupleDeclarationExpression<'a>>),
     Variable(Spanned<Cow<'a, str>>),
     While(Spanned<WhileExpression<'a>>),
 }
@@ -384,8 +423,20 @@ impl<'a> std::fmt::Display for Expression<'a> {
             ),
             Expression::Syscall(e) => write!(f, "{}", e),
             Expression::Ternary(e) => write!(f, "{}", e),
+            Expression::Tuple(e) => {
+                let items = e
+                    .node
+                    .iter()
+                    .map(|x| x.to_string())
+                    .collect::<Vec<_>>()
+                    .join(", ");
+                write!(f, "({})", items)
+            }
+            Expression::TupleAssignment(e) => write!(f, "{}", e),
+            Expression::TupleDeclaration(e) => write!(f, "{}", e),
             Expression::Variable(id) => write!(f, "{}", id),
             Expression::While(e) => write!(f, "{}", e),
         }
     }
 }
+

rust_compiler/libs/tokenizer/src/token.rs

@@ -115,7 +115,7 @@ macro_rules! keyword {
 }
 
 #[derive(Debug, PartialEq, Hash, Eq, Clone, Logos)]
-#[logos(skip r"[ \t\f]+")]
+#[logos(skip r"[ \r\t\f]+")]
 #[logos(extras = Extras)]
 #[logos(error(LexError, LexError::from_lexer))]
 pub enum TokenType<'a> {
@@ -843,3 +843,20 @@ documented! {
     }
 }
 
+#[cfg(test)]
+mod tests {
+    use super::TokenType;
+    use logos::Logos;
+
+    #[test]
+    fn test_windows_crlf_endings() -> anyhow::Result<()> {
+        let src = "let i = 0;\r\n";
+
+        let lexer = TokenType::lexer(src);
+
+        let tokens = lexer.collect::<Vec<_>>();
+
+        assert!(!tokens.iter().any(|res| res.is_err()));
+        Ok(())
+    }
+}

spilling.slang

@@ -1,43 +0,0 @@
-device self = "db";
-device gasSensor  = "d0";
-device atmosAnal  = "d1";
-device atmosValve = "d2";
-device atmosTank  = "d3";
-device atmosInlet = "d4";
-
-atmosInlet.Lock = true;
-atmosInlet.Mode = 1;
-atmosValve.On = false;
-atmosValve.Lock = true;
-
-let isPumping = false;
-let tempPressure = 0;
-
-loop {
-  yield();
-  let temp = gasSensor.Temperature;
-  let pres = atmosAnal.Pressure;
-  let liqV = atmosAnal.VolumeOfLiquid;
-  let tempVol = atmosAnal.Volume;
-
-  let stress = 5_000 * liqV / tempVol;
-
-  tempPressure = isPumping ? 1_000 : 10_000;
-
-  let shouldTurnOnInlet = (
-    temp > 0c &&
-    pres < tempPressure &&
-    stress < 50
-  );
-
-  isPumping = (
-    !shouldTurnOnInlet &&
-    atmosTank.Pressure < 35_000 &&
-    atmosAnal.RatioPollutant == 0 &&
-    atmosAnal.RatioLiquidPollutant == 0 &&
-    atmosAnal.Pressure > 1_000
-  );
-
-  atmosValve.On = isPumping;
-  atmosInlet.On = shouldTurnOnInlet;
-}

test.slang

@@ -1,72 +0,0 @@
-/// Laree script V1
-
-device self = "db";
-device larre = "d0";
-device exportChute = "d1";
-
-const TOTAL_SLOTS = 19;
-const EXPORT_CHUTE = 1;
-const START_STATION = 2;
-
-let currentIndex = 0;
-
-/// Waits for the larre to be idle before continuing
-fn waitForIdle() {
-  yield();
-  while (!larre.Idle) {
-    yield();
-  }
-}
-
-/// Instructs the Larre to go to the chute and deposit
-/// what is currently in its arm
-fn deposit() {
-  larre.Setting = EXPORT_CHUTE;
-  waitForIdle();
-  larre.Activate = true;
-  waitForIdle();
-  exportChute.Open = false;
-}
-
-/// This function is responsible for checking the plant under
-/// the larre at this index, and harvesting if applicable
-fn checkAndHarvest(currentIndex) {
-  if (currentIndex <= EXPORT_CHUTE || ls(larre, 255, "Seeding") < 1) {
-    return;
-  }
-
-  // harvest from this device
-  while (ls(larre, 255, "Mature")) {
-    yield();
-    larre.Activate = true;
-  }
-  let hasRemainingPlant = ls(larre, 255, "Occupied");
-
-  // move to the export chute
-  larre.Setting = EXPORT_CHUTE;
-  waitForIdle();
-  deposit();
-  if (hasRemainingPlant) {
-    deposit();
-  }
-
-  larre.Setting = currentIndex;
-  waitForIdle();
-
-  if (ls(larre, 0, "Occupied")) {
-    larre.Activate = true;
-  }
-  waitForIdle();
-}
-
-loop {
-  yield();
-  if (!larre.Idle) {
-    continue;
-  }
-  let newIndex = currentIndex + 1 > TOTAL_SLOTS ? START_STATION : currentIndex + 1;
-
-  checkAndHarvest(currentIndex);
-  larre.Setting = newIndex;
-  currentIndex = newIndex;
-}