[spec/template-mixin.dd] Tweak examples & make them runnable (#3211)

* [spec/template-mixin.dd] Tweak and make examples runnable

Use writeln instead of writefln.
Tweak Duff's device example.

* Remove CODE_HIGHLIGHT breaking example tests

* More CODE_HIGHLIGHT

Author: ntrel

spec/template-mixin.dd

@@ -5,7 +5,7 @@ $(SPEC_S Template Mixins,
 $(HEADERNAV_TOC)
 
         $(P A $(I TemplateMixin) takes an arbitrary set of declarations from
-        the body of a $(I TemplateDeclaration) and inserts them
+        the body of a $(GLINK2 template, TemplateDeclaration) and inserts them
         into the current context.)
 
 $(GRAMMAR
@@ -40,74 +40,81 @@ $(GNAME MixinQualifiedIdentifier):
         is defined. It is analogous to cutting and pasting the body of
         the template into the location of the mixin into a $(LINK2 #mixin_scope, nested scope). It is useful for injecting
         parameterized $(SINGLEQUOTE boilerplate) code, as well as for creating
-        templated nested functions, which is not possible with
+        templated nested functions, which is not always possible with
         template instantiations.
         )
 
+$(SPEC_RUNNABLE_EXAMPLE_RUN
 ------
+import std.stdio : writeln;
+
 mixin template Foo()
 {
     int x = 5;
 }
 
-$(CODE_HIGHLIGHT mixin Foo;)
+mixin Foo;
 
 struct Bar
 {
-    $(CODE_HIGHLIGHT mixin Foo;)
+    mixin Foo;
 }
 
-void test()
+void main()
 {
-    writefln("x = %d", x);         // prints 5
+    writeln("x = ", x);         // prints 5
     {
         Bar b;
         int x = 3;
 
-        writefln("b.x = %d", b.x); // prints 5
-        writefln("x = %d", x);     // prints 3
+        writeln("b.x = ", b.x); // prints 5
+        writeln("x = ", x);     // prints 3
         {
-            $(CODE_HIGHLIGHT mixin Foo;)
-            writefln("x = %d", x); // prints 5
+            mixin Foo;
+            writeln("x = ", x); // prints 5
             x = 4;
-            writefln("x = %d", x); // prints 4
+            writeln("x = ", x); // prints 4
         }
-        writefln("x = %d", x);     // prints 3
+        writeln("x = ", x);     // prints 3
     }
-    writefln("x = %d", x);         // prints 5
+    writeln("x = ", x);         // prints 5
 }
 ------
-
-        $(P Mixins can be parameterized:)
+)
+        $(P Mixins can be
+        $(DDSUBLINK spec/template, template_type_parameters, parameterized):)
 
 ------
 mixin template Foo(T)
 {
     T x = 5;
 }
 
-$(CODE_HIGHLIGHT mixin Foo!(int);)           // create x of type int
+mixin Foo!(int);           // create x of type int
 ------
 
         $(P Mixins can add virtual functions to a class:)
 
+$(SPEC_RUNNABLE_EXAMPLE_RUN
 ------
+import std.stdio : writeln;
+
 mixin template Foo()
 {
     void func() { writeln("Foo.func()"); }
 }
 
 class Bar
 {
-    $(CODE_HIGHLIGHT mixin Foo;)
+    mixin Foo;
 }
 
 class Code : Bar
 {
     override void func() { writeln("Code.func()"); }
 }
 
-void test()
+void main()
 {
     Bar b = new Bar();
     b.func();      // calls Foo.func()
@@ -116,6 +123,7 @@ void test()
     b.func();      // calls Code.func()
 }
 ------
+)
 
         $(P Mixins are evaluated in the scope of where they appear, not the scope
         of the template declaration:)
@@ -131,12 +139,13 @@ mixin template Foo()
 void test()
 {
     int y = 8;
-    $(CODE_HIGHLIGHT mixin Foo;) // local y is picked up, not global y
+    mixin Foo; // local y is picked up, not global y
     assert(abc() == 8);
 }
 ------
 
-        $(P Mixins can parameterize symbols using alias parameters:)
+        $(P Mixins can parameterize symbols using
+        $(DDSUBLINK spec/template, aliasparameters, alias parameters):)
 
 ------
 mixin template Foo(alias b)
@@ -147,7 +156,7 @@ mixin template Foo(alias b)
 void test()
 {
     int y = 8;
-    $(CODE_HIGHLIGHT mixin Foo!(y);)
+    mixin Foo!(y);
     assert(abc() == 8);
 }
 ------
@@ -157,42 +166,44 @@ void test()
         is in bold). A nested function is generated as well as a
         delegate literal, these can be inlined by the compiler:)
 
+$(SPEC_RUNNABLE_EXAMPLE_RUN
 ------
-mixin template duffs_device(alias id1, alias id2, alias s)
+import std.stdio : writeln;
+
+mixin template duffs_device(alias low, alias high, alias fun)
 {
     void duff_loop()
     {
-        if (id1 < id2)
+        if (low < high)
         {
-            typeof(id1) n = (id2 - id1 + 7) / 8;
-            switch ((id2 - id1) % 8)
+            auto n = (high - low + 7) / 8;
+            switch ((high - low) % 8)
             {
-                case 0: do { s(); goto case;
-                case 7:      s(); goto case;
-                case 6:      s(); goto case;
-                case 5:      s(); goto case;
-                case 4:      s(); goto case;
-                case 3:      s(); goto case;
-                case 2:      s(); goto case;
-                case 1:      s(); continue;
+                case 0: do { fun(); goto case;
+                case 7:      fun(); goto case;
+                case 6:      fun(); goto case;
+                case 5:      fun(); goto case;
+                case 4:      fun(); goto case;
+                case 3:      fun(); goto case;
+                case 2:      fun(); goto case;
+                case 1:      fun(); continue;
                 default:     assert(0, "Impossible");
                         } while (--n > 0);
             }
         }
     }
 }
 
-void foo() { writeln("foo"); }
-
-void test()
+void main()
 {
     int i = 1;
     int j = 11;
 
-    mixin duffs_device!(i, j, $(CODE_HIGHLIGHT delegate { foo(); }));
+    mixin duffs_device!(i, j, delegate { writeln("foo"); });
     duff_loop();  // executes foo() 10 times
 }
 ------
+)
 
 $(H2 $(LNAME2 mixin_scope, Mixin Scope))
 
@@ -202,7 +213,10 @@ $(H2 $(LNAME2 mixin_scope, Mixin Scope))
         as a declaration in the surrounding scope, the surrounding declaration
         overrides the mixin one:)
 
+$(SPEC_RUNNABLE_EXAMPLE_RUN
 ------
+import std.stdio : writeln;
+
 int x = 3;
 
 mixin template Foo()
@@ -211,21 +225,25 @@ mixin template Foo()
     int y = 5;
 }
 
-$(CODE_HIGHLIGHT mixin Foo;)
+mixin Foo;
 int y = 3;
 
-void test()
+void main()
 {
-    writefln("x = %d", x);  // prints 3
-    writefln("y = %d", y);  // prints 3
+    writeln("x = ", x);  // prints 3
+    writeln("y = ", y);  // prints 3
 }
 ------
+)
 
         $(P If two different mixins are put in the same scope, and each
         define a declaration with the same name, there is an ambiguity
         error when the declaration is referenced:)
 
+$(SPEC_RUNNABLE_EXAMPLE_FAIL
 ------
+import std.stdio : writeln;
+
 mixin template Foo()
 {
     int x = 5;
@@ -238,24 +256,28 @@ mixin template Bar()
     void func(long x) { }
 }
 
-$(CODE_HIGHLIGHT mixin Foo;)
-$(CODE_HIGHLIGHT mixin Bar;)
+mixin Foo;
+mixin Bar;
 
-void test()
+void main()
 {
-    import std.stdio : writefln;
-    writefln("x = %d", x); // error, x is ambiguous
+    writeln("x = ", x);    // error, x is ambiguous
     func(1);               // error, func is ambiguous
 }
 ------
+)
         $(P The call to $(D func()) is ambiguous because
         Foo.func and Bar.func are in different scopes.
         )
 
         $(P If a mixin has an $(I Identifier), it can be used to
         disambiguate between conflicting symbols:
         )
+
+$(SPEC_RUNNABLE_EXAMPLE_RUN
 ------
+import std.stdio : writeln;
+
 int x = 6;
 
 mixin template Foo()
@@ -271,19 +293,20 @@ mixin template Bar()
     void func() { }
 }
 
-$(CODE_HIGHLIGHT mixin Foo F;)
-$(CODE_HIGHLIGHT mixin Bar B;)
+mixin Foo F;
+mixin Bar B;
 
-void test()
+void main()
 {
-    writefln("y = %d", y);     // prints 7
-    writefln("x = %d", x);     // prints 6
-    writefln("F.x = %d", F.x); // prints 5
-    writefln("B.x = %d", B.x); // prints 4
+    writeln("y = ", y);     // prints 7
+    writeln("x = ", x);     // prints 6
+    writeln("F.x = ", F.x); // prints 5
+    writeln("B.x = ", B.x); // prints 4
     F.func();                  // calls Foo.func
     B.func();                  // calls Bar.func
 }
 ------
+)
         $(P Alias declarations can be used to overload together
         functions declared in different mixins:)
 
@@ -301,8 +324,8 @@ mixin template Bar()
 mixin Foo!() F;
 mixin Bar!() B;
 
-$(CODE_HIGHLIGHT alias func = F.func;)
-$(CODE_HIGHLIGHT alias func = B.func;)
+alias func = F.func;
+alias func = B.func;
 
 void main()
 {
@@ -315,7 +338,10 @@ void main()
         $(P A mixin has its own scope, even if a declaration is overridden
         by the enclosing one:)
 
+$(SPEC_RUNNABLE_EXAMPLE_RUN
 ------
+import std.stdio : writeln;
+
 int x = 4;
 
 mixin template Foo()
@@ -324,14 +350,15 @@ mixin template Foo()
     int bar() { return x; }
 }
 
-$(CODE_HIGHLIGHT mixin Foo;)
+mixin Foo;
 
-void test()
+void main()
 {
-    writefln("x = %d", x);         // prints 4
-    writefln("bar() = %d", bar()); // prints 5
+    writeln("x = ", x);         // prints 4
+    writeln("bar() = ", bar()); // prints 5
 }
 ------
+)
 
 $(SPEC_SUBNAV_PREV_NEXT template, Templates, contracts, Contract Programming)
 )