Add some type safety to the hyperlink framework

Author: curiousdannii

inform7/Internal/Extensions/Graham Nelson/Basic Inform.i7xd/Materials/Inter/Architecture32Kit/Sections/Glk.i6t

@@ -745,6 +745,10 @@ A simple framework for handling hyperlinks in an interoperable manner.
 We combine a hyperlink tag with a payload in one 32-bit value. The tag is stored
 in the lowest bits, and the payload above it.
 
+|CALCULATE_HYPERLINK_TAG_WIDTH_R| is a |before starting the virtual machine| rule,
+which gets the number of options in the hyperlink tag enum and sets the tag/payload
+masks and widths accordingly.
+
 =
 Global hyperlink_payload_mask;
 Global hyperlink_tag_mask;
@@ -769,8 +773,30 @@ Global hyperlink_value;
 	rfalse;
 ];
 
-[ MakeTaggedHyperlink tag val;
+@ |MakeTaggedHyperlink| combines the tag and value into one 32 bit hyperlink ID,
+checking that the value is not a pointer to ephemeral data (on the stack).
+
+|HANDLE_HYPERLINK_R| then extracts tag and value from an ID, expanding the value
+back to 32 bits.
+
+=
+
+[ MakeTaggedHyperlink tag val kind;
 	if (Cached_Glk_Gestalts-->gestalt_Hyperlinks) {
+		#Ifdef DEBUG;
+			if (val >= blockv_stack && val < (blockv_stack + BLOCKV_STACK_SIZE * WORDSIZE)) {
+				if (kind) {
+					if (KindConformsTo_POINTER_VALUE_TY(kind)) {
+						! Break up the message so that Inform doesn't think it's an Inter invocation
+						print "Error: cannot make hyperlink from ephemeral value; try creating with {", "-by-reference:V}^";
+						return;
+					}
+				}
+				else {
+					print "Warning: hyperlink value might be ephemeral; try creating with explicit kind^";
+				}
+			}
+		#Endif; ! DEBUG
 		if (val > 0) {
 			@shiftl val hyperlink_tag_width val;
 		}

inform7/Internal/Extensions/Graham Nelson/Basic Inform.i7xd/Source/Sections/Glulx and Glk.w

@@ -203,18 +203,24 @@ Chapter - Hyperlinks
 
 A hyperlink tag is a kind of value.
 
-The hyperlink value is a number variable.
-The hyperlink value variable is defined by Inter as "hyperlink_value".
-
 The hyperlink handling rules is a hyperlink tag based rulebook.
 The hyperlink handling rules is accessible to Inter as "HYPERLINK_HANDLING_RB".
 
 The handle hyperlinks rule is listed in the glk event handling rules.
 The handle hyperlinks rule is defined by Inter as "HANDLE_HYPERLINK_R".
 
+To say link (T - hyperlink tag):
+	(- MakeTaggedHyperlink({T}); -).
+
+To say link (T - hyperlink tag) of (V - value of kind K):
+	(- MakeTaggedHyperlink({T}, {-by-reference:V}, {-strong-kind:K}); -).
+
 To say end link:
 	(- if (Cached_Glk_Gestalts-->gestalt_Hyperlinks) { glk_set_hyperlink(0); } -).
 
+To decide what K is hyperlink value as a/an (name of kind of value K):
+	(- (hyperlink_value) -).
+
 @ And some built-in hyperlink tags:
 
 - A rule hyperlink runs a rule when clicked; that in turn allows you to run any other code you like.
@@ -225,26 +231,18 @@ To say end link:
 Rule hyperlink is a hyperlink tag.
 
 To say link (R - rule):
-	(- MakeTaggedHyperlink((+ rule hyperlink +), {R}); -).
+	(- MakeTaggedHyperlink((+ rule hyperlink +), {-by-reference:R}, RULE_TY); -).
 
 Hyperlink handling rule for a rule hyperlink (this is the rule hyperlink rule):
-	run rule at address hyperlink value;
+	follow hyperlink value as a rule;
 
 Keypress hyperlink is a hyperlink tag.
 
 To say link (C - unicode character):
-	(- MakeTaggedHyperlink((+ keypress hyperlink +), {C}); -).
+	(- MakeTaggedHyperlink((+ keypress hyperlink +), {-by-reference:C}, UNICODE_CHARACTER_TY); -).
 
 Hyperlink handling rule for a keypress hyperlink (this is the keypress hyperlink rule):
-	process a character event for (hyperlink value of the current glk event as a unicode character) in (window of the current glk event);
-
-Section - unindexed
-
-To run rule at address (R - number):
-	(- ({R})(); -).
-
-To decide what unicode character is (N - number) as a unicode character:
-	(- ({N}) -).
+	process a character event for (hyperlink value as a unicode character) in (window of the current glk event);
 
 @h Suspending input.
 These properties and phrases allow the author to suspend and resume input requests.