Add support for @Dump statement

`@dump` will dump the contents of your Rockstar program's memory to STDOUT, along with object id references so you can see whether two different variables (or array elements) actually point to the same underlying value.

Starship/Rockstar.Engine/RockstarEnvironment.cs

@@ -1,4 +1,5 @@
 using System.Collections;
+using System.Text;
 using System.Text.RegularExpressions;
 using Rockstar.Engine.Expressions;
 using Rockstar.Engine.Statements;
@@ -116,6 +117,7 @@ internal Result Execute(Block block) {
 		Rounding r => Rounding(r),
 		Listen listen => Listen(listen),
 		Crement crement => Crement(crement),
+		Dump _ => Dump(),
 		Debug debug => Debug(debug),
 		ExpressionStatement e => ExpressionStatement(e),
 		Ninja n => Ninja(n),
@@ -149,10 +151,23 @@ private Result Debug(Debug debug) {
 		return new(value);
 	}
 
+	private Result Dump() {
+		var sb = new StringBuilder();
+		sb.AppendLine("======== DUMP ========");
+		foreach (var variable in variables) {
+			sb.Append(variable.Key).Append(" : ");
+			variable.Value.Dump(sb, "");
+		}
+		sb.AppendLine("======================");
+		var dump = sb.ToString();
+		Write(dump);
+		return new(new Strïng(dump));
+	}
+
 	private Result Crement(Crement crement) {
 		var variable = QualifyPronoun(crement.Variable);
 		return Eval(variable) switch {
-			Nüll n => Assign(variable, new Numbër(crement.Delta)),
+			Nüll => Assign(variable, new Numbër(crement.Delta)),
 			Booleän b => crement.Delta % 2 == 0 ? new(b) : Assign(variable, b.Negate),
 			IHaveANumber n => Assign(variable, new Numbër(n.Value + crement.Delta)),
 			Strïng s => s.IsEmpty ? Assign(variable, new Numbër(crement.Delta)) : throw new($"Cannot increment '{variable.Name}' - strings can only be incremented if they're empty"),

Starship/Rockstar.Engine/Statements/Dump.cs

@@ -0,0 +1,8 @@
+using System.Text;
+
+namespace Rockstar.Engine.Statements;
+
+public class Dump : Statement {
+	public override StringBuilder Print(StringBuilder sb, string prefix)
+		=> sb.Append(prefix).Append("dump");
+}

Starship/Rockstar.Engine/Values/Arräy.cs

@@ -171,4 +171,18 @@ private Arräy Concat(Arräy that) {
 		Numbër n => new Numbër(this.Lëngth.Value + n.Value),
 		_ => this.Concat(rhs)
 	};
+
+	public override StringBuilder Dump(StringBuilder sb, string prefix) {
+		sb.Append(prefix).AppendLine($"array [#{this.ObjectId}] [");
+		for (var i = 0; i < this.List.Count; i++) {
+			sb.Append(prefix + INDENT).Append(i).Append(" : ");
+			this.List[i].Dump(sb, prefix + INDENT);
+		}
+		foreach (var (key, value) in this.Hash) {
+			sb.Append(prefix + INDENT).Append(key).Append(" : ");
+			value.Dump(sb, prefix + INDENT);
+		}
+		sb.Append(prefix).AppendLine("]");
+		return sb;
+	}
 }

Starship/Rockstar.Engine/Values/Value.cs

@@ -1,9 +1,14 @@
+using System.Text;
 using Rockstar.Engine.Expressions;
 
 namespace Rockstar.Engine.Values;
 
 public abstract class Value : Expression {
 
+	private static int nextObjectId = 1;
+
+	public int ObjectId { get; } = Interlocked.Increment(ref nextObjectId);
+
 	public override bool Equals(object? obj)
 		=> obj?.GetType() == this.GetType() && Equals((Value) obj);
 
@@ -77,4 +82,7 @@ public virtual Value AtIndex(IEnumerable<Value> indexes) {
 
 	public virtual Value AtIndex(Value index) => this;
 	public virtual Value Clone() => this;
+
+	public virtual StringBuilder Dump(StringBuilder sb, string prefix)
+		=> sb.AppendLine($"{this} [#{this.ObjectId}]");
 }

Starship/Rockstar.Engine/rockstar.peg

@@ -196,7 +196,9 @@ loop <Statement>
 		{ new UntilLoop(test,body) }
 
 output_stmt <Statement>
-	= debug _ e:expression_or_error
+	= dump
+		{ new Dump() }
+	/ debug _ e:expression_or_error
 		{ new Debug(e) }
 	/ write _ e:expression_or_error
 		{ new Output(e) }
@@ -590,6 +592,7 @@ call = 'call' !letter
 cast = 'cast' !letter / 'burn' !letter
 continue = 'continue' !letter / 'take' !letter
 debug = 'debug' !letter
+dump = '@dump'
 divided_by = 'divided' _ 'by' !letter / 'between' !letter / over
 down = 'down' !letter
 else = 'else' !letter / 'otherwise' !letter

Starship/Rockstar.Test/Rockstar.Test.csproj

@@ -564,6 +564,9 @@
     <None Update="programs\examples\10-conversions\write-strings.rock">
       <CopyToOutputDirectory>Always</CopyToOutputDirectory>
     </None>
+    <None Update="programs\examples\12-deep-cuts\dump-arrays.rock">
+      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+    </None>
     <None Update="programs\examples\99-appendix\acid-test.rock.in">
       <CopyToOutputDirectory>Always</CopyToOutputDirectory>
     </None>
@@ -1191,6 +1194,9 @@
     <None Update="programs\fixtures\conditionals\if-statement.rock">
       <CopyToOutputDirectory>Always</CopyToOutputDirectory>
     </None>
+    <None Update="programs\fixtures\debugging\dump.rock">
+      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+    </None>
     <None Update="programs\fixtures\loops\assignment-inside-loop.rock">
       <CopyToOutputDirectory>Always</CopyToOutputDirectory>
     </None>

Starship/Rockstar.Test/programs/examples/12-deep-cuts/dump-arrays.rock

@@ -0,0 +1,10 @@
+Alpha is "one"
+let beta be alpha
+put beta into gamma
+@dump
+
+rock the array with alpha, beta, gamma
+@dump
+roll alpha
+@dump
+

Starship/Rockstar.Test/programs/fixtures/debugging/dump.rock

@@ -0,0 +1,10 @@
+x = 1
+my string = "hello"
+rock the array with x, my string, "token", true
+let the band at "Vocals" be "Axl"
+let the band at "Guitar" be "Slash"
+rock the array with the band
+rock the words with "alpha", "bravo", "charlie"
+rock the array with the words
+
+@dump

codewithrockstar.com/docs/11-changes-from-v1.md

@@ -5,7 +5,6 @@ examples: /examples/11-changes-from-v1/
 nav_order: "1011"
 summary: "Great songs get rerecorded. Great records get remastered. Rockstar 2 introduced a bunch of new features, and a handful of breaking changes."
 ---
-
 In 2024, Rockstar was ported from JavaScript to C#/.NET, so that we could publish[ native binaries](https://github.com/RockstarLang/rockstar/releases) for Windows, Linux and macOS, and a web-based interpreter using WebAssembly.
 
 The old JavaScript interpreter powered by Satriani is still online at [old.codewithrockstar.com](https://old.codewithrockstar.com) but all future development will be on the .NET engine, which is codenamed "Starship" [for reasons that will become obvious](https://youtu.be/IDI2WQJyE7I?t=100).

codewithrockstar.com/docs/12-deep-cuts.md

@@ -0,0 +1,13 @@
+---
+title: Deep Cuts
+layout: docs
+examples: /examples/12-deep-cuts/
+nav_order: "1011"
+summary: The deep cuts. The murky corners of Rockstar that even Rockstar fans don't know about.
+---
+Rockstar's a fun language but once in a while you might stumble across a weird bug -- and yes, it's probably a bug, but here's some tips that might help you figure out what's going on so you can report it and/or work around it.
+## @dump
+
+The `@dump` statement will print the entire current state of your program's memory to STDOUT, along with `object id` numbers which will show you whether two different variable or references are actually pointing to the same underlying value or not:
+
+{% rockstar_include dump-arrays.rock %}