- +
-
-

To write support code for the Standard Library's "group together" phrases.

+ +

The "group together" phrase in the Standard Rules needs support functions, which are compiled within the user's enclosure.

-
- -

§1. This section exists to support phrases such as: -

- -
-

To group (OS - description of objects) together giving articles: ...

-
- -

For obscure reasons to do with the Inform 6 property list_together -(see DM4 for details), each such usage needs to define a small I6 -routine. The code here manages that. -

- -

The only data stored is a single bit, saying whether to give articles or not: +

§1. This section exists to support usages such as: 

-typedef struct list_together_routine {
-    struct inter_name *ltr_array_iname;
-    struct inter_name *ltr_routine_iname;
-    int articles_bit;  if false, add NOARTICLE_BIT to the I6 listing style
-    CLASS_DEFINITION
-} list_together_routine;
+    group containers together;
+    group keys together, giving articles;
+    group coins together as "filthy lucre";
-
  • The structure list_together_routine is private to this section.
-

§2. Creation. When the inline compiler wants a new LTR, it calls the following, which -prints the name of a routine to be compiled later. +

At the Inter level, the different groupings of an object are stored in a text +property called list_together.1 That's fine for the "filthy lucre" case, +but for the other two usages we will have to make a text substitution, in order +to have a valid value here. It's those substitutions which concern us here: 

-inter_name *ListTogether::new(int include_articles) {
-    list_together_routine *ltr = CREATE(list_together_routine);
-    package_request *PR = Hierarchy::local_package(LISTS_TOGETHER_HAP);
-    ltr->ltr_routine_iname = Hierarchy::make_iname_in(LIST_TOGETHER_FN_HL, PR);
-    ltr->ltr_array_iname = Hierarchy::make_iname_in(LIST_TOGETHER_ARRAY_HL, PR);
+                      small block:
+    ----------------> CONSTANT_PACKED_TEXT_STORAGE
+                      GTF function
+
+

A critical point is that even if the GTF functions do the same thing as each +other (and they likely do — there are only two possibilities), we need to +compile a different function each time, so that BasicInformKit can +distinguish them as values. Thus: +

- ltr->articles_bit = include_articles; - return ltr->ltr_array_iname; +
+    group woodwind instruments together;
+    group brass instruments together;
+
+

must compile to +

+ +
+                      small block:
+    ----------------> CONSTANT_PACKED_TEXT_STORAGE
+                      GTF function 1
+    ----------------> CONSTANT_PACKED_TEXT_STORAGE
+                      GTF function 2
+
+

even though GTF functions 1 and 2 are identical; we need them to be at different +addresses in memory. +

+ +

  • 1 For backwards compatibility with Inform 6, where this same feature was called +"list together" and not "group together". + ↩

+
+typedef struct group_together_function {
+    struct inter_name *text_value_iname;
+    struct inter_name *printing_fn_iname;
+    int articles_bit;  list with indefinite articles, or not
+    CLASS_DEFINITION
+} group_together_function;
+
+
  • The structure group_together_function is private to this section.
+

§2. When Compile Invocations Inline (in imperative) wants a new GTF, it calls the +following, which returns a text literal to print a listing grouped as asked. +

+ +
+inter_name *GroupTogether::new(int include_articles) {
+    group_together_function *gtf = CREATE(group_together_function);
+    gtf->printing_fn_iname =
+        Enclosures::new_iname(GROUPS_TOGETHER_HAP, GROUP_TOGETHER_FN_HL);
+    gtf->text_value_iname = TextLiterals::small_block(gtf->printing_fn_iname);
+    gtf->articles_bit = include_articles;
+    return gtf->text_value_iname;
 }
-

§3. Compilation. And here's later. Note that there are only two possible routines made -here, and we keep compiling them over and over, with different names. That -looks wasteful, but we do it so that the routine addresses can be used as -distinct values of the list_together property at run-time, because this -is significant to the run-time list-printing code. +

§3. And here we work through the queue of GTFs waiting to be compiled: 

-list_together_routine *latest_ltr_compiled = NULL;
+group_together_function *latest_gtf_compiled = NULL;
 
-int ListTogether::compilation_coroutine(void) {
+int GroupTogether::compilation_coroutine(void) {
     int N = 0;
     while (TRUE) {
-        list_together_routine *ltr = FIRST_OBJECT(list_together_routine);
-        if (latest_ltr_compiled)
-            ltr = NEXT_OBJECT(latest_ltr_compiled, list_together_routine);
-        if (ltr == NULL) break;
-        Compile the actual LTR3.1;
-        latest_ltr_compiled = ltr;
+        group_together_function *gtf = FIRST_OBJECT(group_together_function);
+        if (latest_gtf_compiled)
+            gtf = NEXT_OBJECT(latest_gtf_compiled, group_together_function);
+        if (gtf == NULL) break;
+        Compile the actual GTF3.1;
+        latest_gtf_compiled = gtf;
         N++;
     }
     return N;
 }
-

§3.1. Again, see the DM4. +

§3.1. Again, see the DM4; this all continues to follow Inform 6 conventions.

-

Compile the actual LTR3.1 = +

Compile the actual GTF3.1 = 

-    packaging_state save = Functions::begin(ltr->ltr_routine_iname);
+    packaging_state save = Functions::begin(gtf->printing_fn_iname);
     EmitCode::inv(IF_BIP);
     EmitCode::down();
         EmitCode::inv(EQ_BIP);
@@ -151,7 +180,7 @@ is significant to the run-time list-printing code.
                 EmitCode::ref_iname(K_value, Hierarchy::find(C_STYLE_HL));
                 EmitCode::val_iname(K_value, Hierarchy::find(ENGLISH_BIT_HL));
             EmitCode::up();
-            if (!(ltr->articles_bit)) {
+            if (!(gtf->articles_bit)) {
             EmitCode::inv(SETBIT_BIP);
             EmitCode::down();
                 EmitCode::ref_iname(K_value, Hierarchy::find(C_STYLE_HL));
@@ -174,15 +203,10 @@ is significant to the run-time list-printing code.
 
     EmitCode::rfalse();
     Functions::end(save);
-
-    save = EmitArrays::begin(ltr->ltr_array_iname, K_value);
-    EmitArrays::iname_entry(Hierarchy::find(CONSTANT_PACKED_TEXT_STORAGE_HL));
-    EmitArrays::iname_entry(ltr->ltr_routine_iname);
-    EmitArrays::end(save);
-
  • This code is used in §3.
+
  • This code is used in §3.