Include language to remove common indentation from multi-line strings

Author: leebyron

spec/Appendix B -- Grammar Summary.md

@@ -85,6 +85,9 @@ EscapedUnicode :: /[0-9A-Fa-f]{4}/
 
 EscapedCharacter :: one of `"` \ `/` b f n r t
 
+Note: Multi-line string values are interpretted to exclude empty lines and
+uniform indentation with {MultilineStringValue()}.
+
 
 ## Query Document
 

spec/Section 2 -- Language.md

@@ -715,37 +715,51 @@ Strings are sequences of characters wrapped in double-quotes (`"`). (ex.
 significant within a string value.
 
 Note: Unicode characters are allowed within String value literals, however
-GraphQL source must not contain some ASCII control characters so escape
+{SourceCharacter} must not contain some ASCII control characters so escape
 sequences must be used to represent these characters.
 
 **Multi-line Strings**
 
 Multi-line strings are sequences of characters wrapped in triple-quotes (`"""`).
-White space, line terminators, and quote and backslash characters may all be
-used unescaped, enabling freeform text. Characters must all be valid
-{SourceCharacter} to ensure printable source text. If non-printable ASCII
-characters need to be used, escape sequences must be used within standard
-double-quote strings.
+White space, line terminators, quote, and backslash characters may all be
+used unescaped to enable freeform text. Characters must all be valid
+{SourceCharacter}.
 
-**Semantics**
+Since multi-line strings represent freeform text often used in indented
+positions, the string value semantics of a multi-line string excludes uniform indentation and empty initial and trailing lines via {MultilineStringValue()}.
 
-StringValue :: `"` StringCharacter* `"`
+For example, the following operation containing a multi-line string:
 
-  * Return the Unicode character sequence of all {StringCharacter}
-    Unicode character values (which may be empty).
+```graphql
+mutation {
+  sendEmail(message: """
+    Hello,
+      World!
 
-StringValue :: `"""` MultiLineStringCharacter* `"""`
+    Yours,
+      GraphQL.
+  """)
+}
+```
 
-  * Return the Unicode character sequence of all {MultiLineStringCharacter}
-    Unicode character values (which may be empty).
+Is identical to the standard quoted string:
 
-MultiLineStringCharacter :: SourceCharacter but not `"""` or `\"""`
+```graphql
+mutation {
+  sendEmail(message: "Hello,\n  World!\n\nYours,\n  GraphQL.")
+}
+```
 
-  * Return the character value of {SourceCharacter}.
+Note: If non-printable ASCII characters are needed in a string value, a standard
+quoted string with appropriate escape sequences must be used instead of a
+multi-line string.
 
-MultiLineStringCharacter :: `\"""`
+**Semantics**
 
-  * Return the character sequence `"""`.
+StringValue :: `"` StringCharacter* `"`
+
+  * Return the Unicode character sequence of all {StringCharacter}
+    Unicode character values (which may be empty).
 
 StringCharacter :: SourceCharacter but not `"` or \ or LineTerminator
 
@@ -771,6 +785,49 @@ StringCharacter :: \ EscapedCharacter
 | `r`               | U+000D          | carriage return              |
 | `t`               | U+0009          | horizontal tab               |
 
+StringValue :: `"""` MultiLineStringCharacter* `"""`
+
+  * Let {rawValue} be the Unicode character sequence of all
+    {MultiLineStringCharacter} Unicode character values (which may be empty).
+  * Return the result of {MultilineStringValue(rawValue)}.
+
+MultiLineStringCharacter :: SourceCharacter but not `"""` or `\"""`
+
+  * Return the character value of {SourceCharacter}.
+
+MultiLineStringCharacter :: `\"""`
+
+  * Return the character sequence `"""`.
+
+MultilineStringValue(rawValue):
+
+  * Let {lines} be the result of splitting {rawValue} by {LineTerminator}.
+  * Let {minIndent} be {null}.
+  * For each {line} in {lines}:
+    * If {line} is the first item in {lines}, continue to the next line.
+    * Let {length} be the number of characters in {line}.
+    * Let {indent} be the number of leading consecutive {WhiteSpace} characters
+      in {line}.
+    * If {indent} is less than {length}:
+      * If {indent} is less than {minIndent} or {minIndent} is {null}:
+        * Let {minIndent} be {indent}.
+  * If {minIndent} is not {null}:
+    * For each {line} in {lines}:
+      * If {line} is the first item in {lines}, continue to the next line.
+      * Remove {minIndent} characters from the beginning of {line}.
+  * While the first {line} in {lines} contains no characters:
+    * Remove the first {line} from {lines}.
+  * While the last {line} in {lines} contains no characters:
+    * Remove the last {line} from {lines}.
+  * Let {formatted} be the empty character sequence.
+  * For each {line} in {lines}:
+    * If {line} is the first item in {lines}:
+      * Append {formatted} with {line}.
+    * Otherwise:
+      * Append {formatted} with a line feed character (U+000A).
+      * Append {formatted} with {line}.
+  * Return {formatted}.
+
 
 ### Null Value