From 03163a760f465045137984b5eb8103d490be9989 Mon Sep 17 00:00:00 2001
From: Bob Nystrom <robert@stuffwithstuff.com>
Date: Sat, 21 Nov 2015 09:20:50 -0800
Subject: [PATCH] Document interpolation.

---
 README.md                         |  2 +-
 doc/site/getting-started.markdown |  2 +-
 doc/site/index.markdown           |  2 +-
 doc/site/style.scss               | 11 +++++++----
 doc/site/values.markdown          | 19 +++++++++++++++++++
 5 files changed, 29 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 6c5ef58a..5300722f 100644
--- a/README.md
+++ b/README.md
@@ -8,7 +8,7 @@ System.print("Hello, world!")
 
 class Wren {
   flyTo(city) {
-    System.print("Flying to ", city)
+    System.print("Flying to %(city)")
   }
 }
 
diff --git a/doc/site/getting-started.markdown b/doc/site/getting-started.markdown
index c8535fa0..a275ae49 100644
--- a/doc/site/getting-started.markdown
+++ b/doc/site/getting-started.markdown
@@ -56,7 +56,7 @@ it. Here's something to try:
 Or a little more exciting:
 
     :::wren
-    for (i in 1..10) System.print("Counting up " + i.toString)
+    for (i in 1..10) System.print("Counting up %(i)")
 
 You can exit the interpreter using good old Ctrl-C or Ctrl-D, or just throw
 your computer to the ground and storm off.
diff --git a/doc/site/index.markdown b/doc/site/index.markdown
index 47285817..c0f9853e 100644
--- a/doc/site/index.markdown
+++ b/doc/site/index.markdown
@@ -10,7 +10,7 @@ a familiar, modern [syntax][].
 
     class Wren {
       flyTo(city) {
-        System.print("Flying to " + city)
+        System.print("Flying to %(city)")
       }
     }
 
diff --git a/doc/site/style.scss b/doc/site/style.scss
index b7acf3d0..9dc5e314 100644
--- a/doc/site/style.scss
+++ b/doc/site/style.scss
@@ -270,7 +270,7 @@ footer {
   span.c1, span.cm { color: mix($code-color, $code-bg, 60%); }
 
   // Keywords.
-  span.k, span.kd, span.kc, span.nb  { color: hsl(200, 60%, 50%); }
+  span.k, span.kd, span.kc, span.nb  { color: hsl(200, 70%, 50%); }
 
   // Names.
   span.vg { color: hsl(180, 70%, 35%); }
@@ -278,11 +278,14 @@ footer {
   span.vc { color: hsl(130, 60%, 40%); }
 
   // Numbers.
-  span.m, span.mi, span.mf { color: hsl(30, 80%, 45%); }
+  span.m, span.mi, span.mf { color: hsl(90, 40%, 50%); }
 
   // Strings.
-  span.s, span.s2  { color: hsl(40, 80%, 45%); }
-  span.se          { color: hsl(45, 80%, 50%); }
+  span.s, span.s2  { color: hsl(40, 90%, 40%); }
+  // Escape.
+  span.se          { color: hsl(50, 90%, 45%); }
+  // Interpolation.
+  span.si          { color: hsl(50, 90%, 40%); background: hsl(40, 90%, 95%); }
 
   // Operators and punctuation.
   span.o           { color: hsl(200, 40%, 50%); }
diff --git a/doc/site/values.markdown b/doc/site/values.markdown
index 6fdb8993..b26241e1 100644
--- a/doc/site/values.markdown
+++ b/doc/site/values.markdown
@@ -49,6 +49,7 @@ A handful of escape characters are supported:
     "\0" // The NUL byte: 0.
     "\"" // A double quote character.
     "\\" // A backslash.
+    "\%" // A percent sign.
     "\a" // Alarm beep. (Who uses this?)
     "\b" // Backspace.
     "\f" // Formfeed.
@@ -77,6 +78,24 @@ Strings are instances of class [String][].
 
 [string]: modules/core/string.html
 
+### Interpolation
+
+String literals also allow *interpolation*. If you have a percent sign (`%`)
+followed by a parenthesized expression, the expression is evaluated. The
+resulting object's `toString` method is called and the result is inserted in the
+string:
+
+    :::wren
+    System.print("Math %(3 + 4 * 5) is fun!") //> Math 23 is fun!
+
+Arbitrarily complex expressions are allowed inside the parentheses:
+
+    :::wren
+    System.print("wow %((1..3).map {|n| n * n}.join())") //> wow 149
+
+An interpolated expression can even contain a string literal which in turn has
+its own nested intpolations, but doing that gets unreadable pretty quickly.
+
 ## Ranges
 
 A range is a little object that represents a consecutive range of numbers. They