Clarify stack references in stack IR instructions

28 files changed, 65 insertions, 53 deletions

diff --git a/src/main/java/org/shedlang/compiler/stackir/instructions/CallInstruction.java b/src/main/java/org/shedlang/compiler/stackir/instructions/CallInstruction.java
index 02264a62..a84c4af1 100644
--- a/src/main/java/org/shedlang/compiler/stackir/instructions/CallInstruction.java
+++ b/src/main/java/org/shedlang/compiler/stackir/instructions/CallInstruction.java
@@ -5,9 +5,11 @@ import org.shedlang.compiler.sources.Source;
 import java.util.List;
 
 /**
- * Pop a receiver and arguments from the stack and call the receiver with those arguments.
+ * Pop a receiver and arguments from the temporary value stack and call the
+ * receiver with those arguments.
  *
- * <p>Specifically, the values should have been pushed onto the stack in the following order:</p>
+ * <p>Specifically, the values should have been pushed onto the temporary value
+ * stack in the following order:</p>
  *
  * <ul>
  *     <li>The receiver i.e. the function to be called.</li>
diff --git a/src/main/java/org/shedlang/compiler/stackir/instructions/DefineEffectInstruction.java b/src/main/java/org/shedlang/compiler/stackir/instructions/DefineEffectInstruction.java
index e6bedda6..d87a6412 100644
--- a/src/main/java/org/shedlang/compiler/stackir/instructions/DefineEffectInstruction.java
+++ b/src/main/java/org/shedlang/compiler/stackir/instructions/DefineEffectInstruction.java
@@ -4,7 +4,8 @@ import org.shedlang.compiler.sources.Source;
 import org.shedlang.compiler.types.UserDefinedEffect;
 
 /**
- * Push an effect value onto the stack with the given definition.
+ * Push an effect value onto the temporary value stack with the given
+ * definition.
  */
 public record DefineEffectInstruction(
     UserDefinedEffect effect,
diff --git a/src/main/java/org/shedlang/compiler/stackir/instructions/DefineFunctionInstruction.java b/src/main/java/org/shedlang/compiler/stackir/instructions/DefineFunctionInstruction.java
index e7019357..6ca40775 100644
--- a/src/main/java/org/shedlang/compiler/stackir/instructions/DefineFunctionInstruction.java
+++ b/src/main/java/org/shedlang/compiler/stackir/instructions/DefineFunctionInstruction.java
@@ -9,7 +9,8 @@ import org.shedlang.compiler.util.P;
 import java.util.List;
 
 /**
- * Push a function value onto the stack with the given definition.
+ * Push a function value onto the temporary value stack with the given
+ * definition.
  */
 public record DefineFunctionInstruction(
     String name,
diff --git a/src/main/java/org/shedlang/compiler/stackir/instructions/DefineStructInstruction.java b/src/main/java/org/shedlang/compiler/stackir/instructions/DefineStructInstruction.java
index 1d91a1a5..098c9245 100644
--- a/src/main/java/org/shedlang/compiler/stackir/instructions/DefineStructInstruction.java
+++ b/src/main/java/org/shedlang/compiler/stackir/instructions/DefineStructInstruction.java
@@ -6,7 +6,8 @@ import org.shedlang.compiler.types.StructType;
 import java.util.List;
 
 /**
- * Push a struct type value onto the stack with the given definition.
+ * Push a struct type value onto the temporary value stack with the given
+ * definition.
  */
 public record DefineStructInstruction(
     StructType type,
diff --git a/src/main/java/org/shedlang/compiler/stackir/instructions/DiscardInstruction.java b/src/main/java/org/shedlang/compiler/stackir/instructions/DiscardInstruction.java
index 91b74c45..503ecc53 100644
--- a/src/main/java/org/shedlang/compiler/stackir/instructions/DiscardInstruction.java
+++ b/src/main/java/org/shedlang/compiler/stackir/instructions/DiscardInstruction.java
@@ -3,7 +3,7 @@ package org.shedlang.compiler.stackir.instructions;
 import org.shedlang.compiler.sources.Source;
 
 /**
- * Pop a value from the stack and discard it.
+ * Pop a value from the temporary value stack and discard it.
  */
 public record DiscardInstruction(Source source) implements Instruction {
 }
diff --git a/src/main/java/org/shedlang/compiler/stackir/instructions/DuplicateInstruction.java b/src/main/java/org/shedlang/compiler/stackir/instructions/DuplicateInstruction.java
index 0d4aee1d..03685e54 100644
--- a/src/main/java/org/shedlang/compiler/stackir/instructions/DuplicateInstruction.java
+++ b/src/main/java/org/shedlang/compiler/stackir/instructions/DuplicateInstruction.java
@@ -3,7 +3,7 @@ package org.shedlang.compiler.stackir.instructions;
 import org.shedlang.compiler.sources.Source;
 
 /**
- * Duplicates the value on top of the stack.
+ * Duplicates the value on top of the temporary value stack.
  */
 public record DuplicateInstruction(Source source) implements Instruction {
 }
diff --git a/src/main/java/org/shedlang/compiler/stackir/instructions/FieldLoadInstruction.java b/src/main/java/org/shedlang/compiler/stackir/instructions/FieldLoadInstruction.java
index 7729d1d7..53dc1ee8 100644
--- a/src/main/java/org/shedlang/compiler/stackir/instructions/FieldLoadInstruction.java
+++ b/src/main/java/org/shedlang/compiler/stackir/instructions/FieldLoadInstruction.java
@@ -6,8 +6,8 @@ import org.shedlang.compiler.types.StructType;
 import org.shedlang.compiler.types.UserDefinedEffect;
 
 /**
- * Pop a value from the stack, get the given field from the popped value, and
- * push the field's value onto the stack.
+ * Pop a value from the temporary value stack, get the given field from the
+ * popped value, and push the field's value onto the temporary value stack.
  */
 public record FieldLoadInstruction(
     Receiver receiver,
diff --git a/src/main/java/org/shedlang/compiler/stackir/instructions/IfInstruction.java b/src/main/java/org/shedlang/compiler/stackir/instructions/IfInstruction.java
index 72dbb679..a6636b91 100644
--- a/src/main/java/org/shedlang/compiler/stackir/instructions/IfInstruction.java
+++ b/src/main/java/org/shedlang/compiler/stackir/instructions/IfInstruction.java
@@ -6,11 +6,12 @@ import org.shedlang.compiler.sources.Source;
 import java.util.List;
 
 /**
- * Pop a value from the stack, and assume it is a Bool. If it is true, execute the
- * instructions in the "true" body, otherwise execute the instructions in the
- * "false" body.
+ * Pop a value from the temporary value stack, and assume it is a Bool. If it is
+ * true, execute the instructions in the "true" body, otherwise execute the
+ * instructions in the "false" body.
  * <p>
- * Each branch body should push <code>resultCount</code> values onto the stack.
+ * Each branch body should push <code>resultCount</code> values onto the
+ * temporary value stack.
  */
 public record IfInstruction(
     int resultCount,
diff --git a/src/main/java/org/shedlang/compiler/stackir/instructions/IntAddInstruction.java b/src/main/java/org/shedlang/compiler/stackir/instructions/IntAddInstruction.java
index 9f131255..55a4fb1c 100644
--- a/src/main/java/org/shedlang/compiler/stackir/instructions/IntAddInstruction.java
+++ b/src/main/java/org/shedlang/compiler/stackir/instructions/IntAddInstruction.java
@@ -3,8 +3,8 @@ package org.shedlang.compiler.stackir.instructions;
 import org.shedlang.compiler.sources.Source;
 
 /**
- * Pop two values from the stack, assumed to be Ints, add them together, and
- * push the result onto the stack.
+ * Pop two values from the temporary value stack, assumed to be Ints, add them
+ * together, and push the result onto the temporary value stack.
  */
 public record IntAddInstruction(Source source) implements Instruction {
 }
diff --git a/src/main/java/org/shedlang/compiler/stackir/instructions/IntEqualsInstruction.java b/src/main/java/org/shedlang/compiler/stackir/instructions/IntEqualsInstruction.java
index 623db1c4..7f0c97cf 100644
--- a/src/main/java/org/shedlang/compiler/stackir/instructions/IntEqualsInstruction.java
+++ b/src/main/java/org/shedlang/compiler/stackir/instructions/IntEqualsInstruction.java
@@ -3,8 +3,8 @@ package org.shedlang.compiler.stackir.instructions;
 import org.shedlang.compiler.sources.Source;
 
 /**
- * Pop two values from the stack, compare them as Ints, and push a Bool onto
- * the stack: true if equal, false if not equal.
+ * Pop two values from the temporary value stack, compare them as Ints, and push
+ * a Bool onto the temporary value stack: true if equal, false if not equal.
  */
 public record IntEqualsInstruction(Source source) implements Instruction {
 }
diff --git a/src/main/java/org/shedlang/compiler/stackir/instructions/IntNotEqualInstruction.java b/src/main/java/org/shedlang/compiler/stackir/instructions/IntNotEqualInstruction.java
index 722723d2..6b155f67 100644
--- a/src/main/java/org/shedlang/compiler/stackir/instructions/IntNotEqualInstruction.java
+++ b/src/main/java/org/shedlang/compiler/stackir/instructions/IntNotEqualInstruction.java
@@ -3,8 +3,8 @@ package org.shedlang.compiler.stackir.instructions;
 import org.shedlang.compiler.sources.Source;
 
 /**
- * Pop two values from the stack, compare them as Ints, and push a Bool onto
- * the stack: true if not equal, false if equal.
+ * Pop two values from the temporary value stack, compare them as Ints, and push
+ * a Bool onto the temporary value stack: true if not equal, false if equal.
  */
 public record IntNotEqualInstruction(Source source) implements Instruction {
 }
diff --git a/src/main/java/org/shedlang/compiler/stackir/instructions/IntSubInstruction.java b/src/main/java/org/shedlang/compiler/stackir/instructions/IntSubInstruction.java
index 4d105695..e2fa09b6 100644
--- a/src/main/java/org/shedlang/compiler/stackir/instructions/IntSubInstruction.java
+++ b/src/main/java/org/shedlang/compiler/stackir/instructions/IntSubInstruction.java
@@ -3,9 +3,9 @@ package org.shedlang.compiler.stackir.instructions;
 import org.shedlang.compiler.sources.Source;
 
 /**
- * Pop the right operand from the stack, then the left operand from the stack,
- * calculate the left operand minus the right operand, then push the result onto
- * the stack.
+ * Pop the right operand from the temporary value stack, then the left operand
+ * from the temporary value stack, calculate the left operand minus the right
+ * operand, then push the result onto the temporary value stack.
  */
 public record IntSubInstruction(Source source) implements Instruction {
 }
diff --git a/src/main/java/org/shedlang/compiler/stackir/instructions/LocalLoadInstruction.java b/src/main/java/org/shedlang/compiler/stackir/instructions/LocalLoadInstruction.java
index ef4a923f..d0753609 100644
--- a/src/main/java/org/shedlang/compiler/stackir/instructions/LocalLoadInstruction.java
+++ b/src/main/java/org/shedlang/compiler/stackir/instructions/LocalLoadInstruction.java
@@ -3,7 +3,8 @@ package org.shedlang.compiler.stackir.instructions;
 import org.shedlang.compiler.sources.Source;
 
 /**
- * Load the local with the given name and push it onto the stack.
+ * Load the local with the given name and push it onto the temporary value
+ * stack.
  */
 public record LocalLoadInstruction(String name, Source source) implements Instruction {
 }
diff --git a/src/main/java/org/shedlang/compiler/stackir/instructions/LocalStoreInstruction.java b/src/main/java/org/shedlang/compiler/stackir/instructions/LocalStoreInstruction.java
index eb0331e1..880c91f8 100644
--- a/src/main/java/org/shedlang/compiler/stackir/instructions/LocalStoreInstruction.java
+++ b/src/main/java/org/shedlang/compiler/stackir/instructions/LocalStoreInstruction.java
@@ -3,7 +3,8 @@ package org.shedlang.compiler.stackir.instructions;
 import org.shedlang.compiler.sources.Source;
 
 /**
- * Pop a value from the stack and store it as the local with the given name.
+ * Pop a value from the temporary value stack and store it as the local with the
+ * given name.
  */
 public record LocalStoreInstruction(String name, Source source) implements Instruction {
 }
diff --git a/src/main/java/org/shedlang/compiler/stackir/instructions/NamespaceFieldStoreInstruction.java b/src/main/java/org/shedlang/compiler/stackir/instructions/NamespaceFieldStoreInstruction.java
index 197def00..b83964a1 100644
--- a/src/main/java/org/shedlang/compiler/stackir/instructions/NamespaceFieldStoreInstruction.java
+++ b/src/main/java/org/shedlang/compiler/stackir/instructions/NamespaceFieldStoreInstruction.java
@@ -4,8 +4,8 @@ import org.shedlang.compiler.sources.Source;
 import org.shedlang.compiler.types.NamespaceName;
 
 /**
- * Pop a value from the stack and store it as the field with the given name on
- * the given namespace.
+ * Pop a value from the temporary value stack and store it as the field with the
+ * given name on the given namespace.
  */
 public record NamespaceFieldStoreInstruction(
     NamespaceName namespaceName,
diff --git a/src/main/java/org/shedlang/compiler/stackir/instructions/NamespaceImportInstruction.java b/src/main/java/org/shedlang/compiler/stackir/instructions/NamespaceImportInstruction.java
index f1a88f6c..cc600d5b 100644
--- a/src/main/java/org/shedlang/compiler/stackir/instructions/NamespaceImportInstruction.java
+++ b/src/main/java/org/shedlang/compiler/stackir/instructions/NamespaceImportInstruction.java
@@ -4,7 +4,7 @@ import org.shedlang.compiler.sources.Source;
 import org.shedlang.compiler.types.NamespaceName;
 
 /**
- * Import the given namespace and push it onto the stack.
+ * Import the given namespace and push it onto the temporary value stack.
  */
 public record NamespaceImportInstruction(
     NamespaceName namespaceName,
diff --git a/src/main/java/org/shedlang/compiler/stackir/instructions/PushBoolInstruction.java b/src/main/java/org/shedlang/compiler/stackir/instructions/PushBoolInstruction.java
index 59a34413..c732a390 100644
--- a/src/main/java/org/shedlang/compiler/stackir/instructions/PushBoolInstruction.java
+++ b/src/main/java/org/shedlang/compiler/stackir/instructions/PushBoolInstruction.java
@@ -3,7 +3,7 @@ package org.shedlang.compiler.stackir.instructions;
 import org.shedlang.compiler.sources.Source;
 
 /**
- * Push a boolean onto the stack.
+ * Push a boolean onto the temporary value stack.
  */
 public record PushBoolInstruction(
     boolean value,
diff --git a/src/main/java/org/shedlang/compiler/stackir/instructions/PushIntInstruction.java b/src/main/java/org/shedlang/compiler/stackir/instructions/PushIntInstruction.java
index 7a417bb6..cba3f217 100644
--- a/src/main/java/org/shedlang/compiler/stackir/instructions/PushIntInstruction.java
+++ b/src/main/java/org/shedlang/compiler/stackir/instructions/PushIntInstruction.java
@@ -5,7 +5,7 @@ import org.shedlang.compiler.sources.Source;
 import java.math.BigInteger;
 
 /**
- * Push an integer onto the stack.
+ * Push an integer onto the temporary value stack.
  */
 public record PushIntInstruction(BigInteger value, Source source) implements Instruction {
 }
diff --git a/src/main/java/org/shedlang/compiler/stackir/instructions/PushStringInstruction.java b/src/main/java/org/shedlang/compiler/stackir/instructions/PushStringInstruction.java
index 9322b72f..e33051e5 100644
--- a/src/main/java/org/shedlang/compiler/stackir/instructions/PushStringInstruction.java
+++ b/src/main/java/org/shedlang/compiler/stackir/instructions/PushStringInstruction.java
@@ -3,7 +3,7 @@ package org.shedlang.compiler.stackir.instructions;
 import org.shedlang.compiler.sources.Source;
 
 /**
- * Push a string onto the stack.
+ * Push a string onto the temporary value stack.
  */
 public record PushStringInstruction(String value, Source source) implements Instruction {
 }
diff --git a/src/main/java/org/shedlang/compiler/stackir/instructions/PushUnitInstruction.java b/src/main/java/org/shedlang/compiler/stackir/instructions/PushUnitInstruction.java
index 15a3560f..998624e1 100644
--- a/src/main/java/org/shedlang/compiler/stackir/instructions/PushUnitInstruction.java
+++ b/src/main/java/org/shedlang/compiler/stackir/instructions/PushUnitInstruction.java
@@ -3,7 +3,7 @@ package org.shedlang.compiler.stackir.instructions;
 import org.shedlang.compiler.sources.Source;
 
 /**
- * Push the unit value onto the stack.
+ * Push the unit value onto the temporary value stack.
  */
 public record PushUnitInstruction(Source source) implements Instruction {
 }
diff --git a/src/main/java/org/shedlang/compiler/stackir/instructions/ReturnInstruction.java b/src/main/java/org/shedlang/compiler/stackir/instructions/ReturnInstruction.java
index 3b711c7d..1b9e4213 100644
--- a/src/main/java/org/shedlang/compiler/stackir/instructions/ReturnInstruction.java
+++ b/src/main/java/org/shedlang/compiler/stackir/instructions/ReturnInstruction.java
@@ -3,7 +3,8 @@ package org.shedlang.compiler.stackir.instructions;
 import org.shedlang.compiler.sources.Source;
 
 /**
- * Pop a value from the stack and return with that value from the current function.
+ * Pop a value from the temporary value stack and return with that value from
+ * the current function.
  */
 public record ReturnInstruction(Source source) implements Instruction {
 }
diff --git a/src/main/java/org/shedlang/compiler/stackir/instructions/StringAddInstruction.java b/src/main/java/org/shedlang/compiler/stackir/instructions/StringAddInstruction.java
index 041ae30e..5114beff 100644
--- a/src/main/java/org/shedlang/compiler/stackir/instructions/StringAddInstruction.java
+++ b/src/main/java/org/shedlang/compiler/stackir/instructions/StringAddInstruction.java
@@ -3,9 +3,10 @@ package org.shedlang.compiler.stackir.instructions;
 import org.shedlang.compiler.sources.Source;
 
 /**
- * Pop the right operand from the stack, then the left operand from the stack,
- * assume both operands are Strings, concatenate the left and right operands,
- * then push the result onto the stack.
+ * Pop the right operand from the temporary value stack, then the left operand
+ * from the temporary value stack, assume both operands are Strings, concatenate
+ * the left and right operands, then push the result onto the temporary value
+ * stack.
  */
 public record StringAddInstruction(Source source) implements Instruction {
 }
diff --git a/src/main/java/org/shedlang/compiler/stackir/instructions/SwitchInstruction.java b/src/main/java/org/shedlang/compiler/stackir/instructions/SwitchInstruction.java
index d978df98..880349de 100644
--- a/src/main/java/org/shedlang/compiler/stackir/instructions/SwitchInstruction.java
+++ b/src/main/java/org/shedlang/compiler/stackir/instructions/SwitchInstruction.java
@@ -6,11 +6,11 @@ import org.shedlang.compiler.types.StructType;
 import java.util.List;
 
 /**
- * Pop a value from the stack, find the case corresponding to that value's type,
- * and execute the instructions in the case's body. If there is no such case,
- * the behaviour of this instruction is not defined.
+ * Pop a value from the temporary value stack, find the case corresponding to
+ * that value's type, and execute the instructions in the case's body. If there
+ * is no such case, the behaviour of this instruction is not defined.
  * <p>
- * Each case body should push exactly one value onto the stack.
+ * Each case body should push exactly one value onto the temporary value stack.
  */
 public record SwitchInstruction(
     List<Case> cases,
diff --git a/src/main/java/org/shedlang/compiler/stackir/instructions/TryInstruction.java b/src/main/java/org/shedlang/compiler/stackir/instructions/TryInstruction.java
index aa994645..0b5051df 100644
--- a/src/main/java/org/shedlang/compiler/stackir/instructions/TryInstruction.java
+++ b/src/main/java/org/shedlang/compiler/stackir/instructions/TryInstruction.java
@@ -7,14 +7,15 @@ import org.shedlang.compiler.types.UserDefinedEffect;
 import java.util.List;
 
 /**
- * For each handler method name, pop a value off the stack. The first value
- * (that is, the first pushed / last popped) corresponds to the first handler
- * method name, and so on. Push an effect handler for the given effect with the
- * popped handler methods onto the effect handler stack, and execute the body.
- * Once the body has exited, pop the effect handler from the effect handler
- * stack.
+ * For each handler method name, pop a value off the temporary value stack. The
+ * first value (that is, the first pushed / last popped) corresponds to the
+ * first handler method name, and so on. Push an effect handler for the given
+ * effect with the popped handler methods onto the effect handler stack, and
+ * execute the body. Once the body has exited, pop the effect handler from the
+ * effect handler stack.
  * <p>
- * If the body runs to completion, it should leave a single value on the stack.
+ * If the body runs to completion, it should leave a single value on the
+ * temporary value stack.
  */
 public record TryInstruction(
     UserDefinedEffect handledEffect,
diff --git a/src/main/java/org/shedlang/compiler/stackir/instructions/TupleCreateInstruction.java b/src/main/java/org/shedlang/compiler/stackir/instructions/TupleCreateInstruction.java
index d1dec767..fa331d1c 100644
--- a/src/main/java/org/shedlang/compiler/stackir/instructions/TupleCreateInstruction.java
+++ b/src/main/java/org/shedlang/compiler/stackir/instructions/TupleCreateInstruction.java
@@ -3,9 +3,9 @@ package org.shedlang.compiler.stackir.instructions;
 import org.shedlang.compiler.sources.Source;
 
 /**
- * Pop {@code elementCount} values from the stack, create a tuple from those
- * elements, and push the tuple onto the stack. Elements should have been pushed
- * onto the stack in index order.
+ * Pop {@code elementCount} values from the temporary value stack, create a
+ * tuple from those elements, and push the tuple onto the temporary value stack.
+ * Elements should have been pushed onto the stack in index order.
  */
 public record TupleCreateInstruction(
     int elementCount,
diff --git a/src/main/java/org/shedlang/compiler/stackir/instructions/TupleGetInstruction.java b/src/main/java/org/shedlang/compiler/stackir/instructions/TupleGetInstruction.java
index bf2e0456..ed52cc29 100644
--- a/src/main/java/org/shedlang/compiler/stackir/instructions/TupleGetInstruction.java
+++ b/src/main/java/org/shedlang/compiler/stackir/instructions/TupleGetInstruction.java
@@ -3,8 +3,8 @@ package org.shedlang.compiler.stackir.instructions;
 import org.shedlang.compiler.sources.Source;
 
 /**
- * Pop a tuple from the stack, get the element at the given index, and push it
- * onto the stack.
+ * Pop a tuple from the temporary value stack, get the element at the given
+ * index, and push it onto the temporary value stack.
  */
 public record TupleGetInstruction(
     int elementIndex,
diff --git a/src/main/java/org/shedlang/compiler/stackir/instructions/VarLoadInstruction.java b/src/main/java/org/shedlang/compiler/stackir/instructions/VarLoadInstruction.java
index 2ca49d90..fe35db14 100644
--- a/src/main/java/org/shedlang/compiler/stackir/instructions/VarLoadInstruction.java
+++ b/src/main/java/org/shedlang/compiler/stackir/instructions/VarLoadInstruction.java
@@ -4,7 +4,7 @@ import org.shedlang.compiler.sources.Source;
 
 /**
  * Load the value stored in the var with the given name and push it onto the
- * stack.
+ * temporary value stack.
  */
 public record VarLoadInstruction(String name, Source source) implements Instruction {
 }
diff --git a/src/main/java/org/shedlang/compiler/stackir/instructions/VarStoreInstruction.java b/src/main/java/org/shedlang/compiler/stackir/instructions/VarStoreInstruction.java
index b355d39c..33a3ab45 100644
--- a/src/main/java/org/shedlang/compiler/stackir/instructions/VarStoreInstruction.java
+++ b/src/main/java/org/shedlang/compiler/stackir/instructions/VarStoreInstruction.java
@@ -3,7 +3,8 @@ package org.shedlang.compiler.stackir.instructions;
 import org.shedlang.compiler.sources.Source;
 
 /**
- * Pop a value from the stack and store it in the var with the given name.
+ * Pop a value from the temporary value stack and store it in the var with the
+ * given name.
  */
 public record VarStoreInstruction(String name, Source source) implements Instruction {
 }