RFC: Long String (Multi-line String)

This RFC adds a new lexed token, the "long string" aka multi-line string, similar to that found in Python and Scala.

A long string starts and ends with a triple-quote:

```
"""This is a long string
and it can contain multiple lines"""
```

Long strings are useful for typing literal bodies of text where new lines should be interpretted literally. In fact, the only escape sequence used is `\"""` and `\` is otherwise allowed unescaped. This is beneficial when writing documentation within strings which may reference the back-slash often:

```
"""
In a long-string \n and C:\\ are unescaped.
"""
```

The primary value of long-strings are to write long-form input directly in query text, in tools like GraphiQL, and as a prerequisite to another pending RFC to allow docstring style documentation in the Schema Definition Language.

Author: leebyron

src/language/__tests__/kitchen-sink.graphql

@@ -48,7 +48,7 @@ subscription StoryLikeSubscription($input: StoryLikeSubscribeInput) {
 }
 
 fragment frag on Friend {
-  foo(size: $size, bar: $b, obj: {key: "value"})
+  foo(size: $size, bar: $b, obj: {key: "value", long: """longstring"""})
 }
 
 {

src/language/__tests__/lexer-test.js

@@ -258,6 +258,106 @@ describe('Lexer', () => {
     );
   });
 
+  it('lexes long-strings', () => {
+
+    expect(
+      lexOne('"""simple"""')
+    ).to.containSubset({
+      kind: TokenKind.LONG_STRING,
+      start: 0,
+      end: 12,
+      value: 'simple'
+    });
+
+    expect(
+      lexOne('""" white space """')
+    ).to.containSubset({
+      kind: TokenKind.LONG_STRING,
+      start: 0,
+      end: 19,
+      value: ' white space '
+    });
+
+    expect(
+      lexOne('"""contains " quote"""')
+    ).to.containSubset({
+      kind: TokenKind.LONG_STRING,
+      start: 0,
+      end: 22,
+      value: 'contains " quote'
+    });
+
+    expect(
+      lexOne('"""contains \\""" triplequote"""')
+    ).to.containSubset({
+      kind: TokenKind.LONG_STRING,
+      start: 0,
+      end: 31,
+      value: 'contains """ triplequote'
+    });
+
+    expect(
+      lexOne('"""multi\nline"""')
+    ).to.containSubset({
+      kind: TokenKind.LONG_STRING,
+      start: 0,
+      end: 16,
+      value: 'multi\nline'
+    });
+
+    expect(
+      lexOne('"""multi\rline"""')
+    ).to.containSubset({
+      kind: TokenKind.LONG_STRING,
+      start: 0,
+      end: 16,
+      value: 'multi\rline'
+    });
+
+    expect(
+      lexOne('"""unescaped \\n\\r\\b\\t\\f\\u1234"""')
+    ).to.containSubset({
+      kind: TokenKind.LONG_STRING,
+      start: 0,
+      end: 32,
+      value: 'unescaped \\n\\r\\b\\t\\f\\u1234'
+    });
+
+    expect(
+      lexOne('"""slashes \\\\ \\/"""')
+    ).to.containSubset({
+      kind: TokenKind.LONG_STRING,
+      start: 0,
+      end: 19,
+      value: 'slashes \\\\ \\/'
+    });
+
+  });
+
+  it('lex reports useful long string errors', () => {
+
+    expect(
+      () => lexOne('"""')
+    ).to.throw('Syntax Error GraphQL request (1:4) Unterminated string.');
+
+    expect(
+      () => lexOne('"""no end quote')
+    ).to.throw('Syntax Error GraphQL request (1:16) Unterminated string.');
+
+    expect(
+      () => lexOne('"""contains unescaped \u0007 control char"""')
+    ).to.throw(
+      'Syntax Error GraphQL request (1:23) Invalid character within String: "\\u0007".'
+    );
+
+    expect(
+      () => lexOne('"""null-byte is not \u0000 end of file"""')
+    ).to.throw(
+      'Syntax Error GraphQL request (1:21) Invalid character within String: "\\u0000".'
+    );
+
+  });
+
   it('lexes numbers', () => {
 
     expect(

src/language/__tests__/parser-test.js

@@ -328,6 +328,22 @@ describe('Parser', () => {
       });
     });
 
+    it('parses long strings', () => {
+      expect(parseValue('["""long""" "short"]')).to.containSubset({
+        kind: Kind.LIST,
+        loc: { start: 0, end: 20 },
+        values: [
+          { kind: Kind.STRING,
+            loc: { start: 1, end: 11},
+            value: 'long',
+            long: true },
+          { kind: Kind.STRING,
+            loc: { start: 12, end: 19},
+            value: 'short',
+            long: false } ]
+      });
+    });
+
   });
 
   describe('parseType', () => {

src/language/__tests__/printer-test.js

@@ -129,7 +129,7 @@ describe('Printer', () => {
       }
 
       fragment frag on Friend {
-        foo(size: $size, bar: $b, obj: {key: "value"})
+        foo(size: $size, bar: $b, obj: {key: "value", long: """longstring"""})
       }
 
       {

src/language/__tests__/visitor-test.js

@@ -592,6 +592,12 @@ describe('Visitor', () => {
       [ 'enter', 'StringValue', 'value', 'ObjectField' ],
       [ 'leave', 'StringValue', 'value', 'ObjectField' ],
       [ 'leave', 'ObjectField', 0, undefined ],
+      [ 'enter', 'ObjectField', 1, undefined ],
+      [ 'enter', 'Name', 'name', 'ObjectField' ],
+      [ 'leave', 'Name', 'name', 'ObjectField' ],
+      [ 'enter', 'StringValue', 'value', 'ObjectField' ],
+      [ 'leave', 'StringValue', 'value', 'ObjectField' ],
+      [ 'leave', 'ObjectField', 1, undefined ],
       [ 'leave', 'ObjectValue', 'value', 'Argument' ],
       [ 'leave', 'Argument', 2, undefined ],
       [ 'leave', 'Field', 0, undefined ],

src/language/ast.js

@@ -67,6 +67,7 @@ type TokenKind = '<SOF>'
                | 'Int'
                | 'Float'
                | 'String'
+               | 'LongString'
                | 'Comment';
 
 /**
@@ -289,6 +290,7 @@ export type StringValueNode = {
   kind: 'StringValue';
   loc?: Location;
   value: string;
+  long?: boolean;
 };
 
 export type BooleanValueNode = {

src/language/lexer.js

@@ -101,6 +101,7 @@ const NAME = 'Name';
 const INT = 'Int';
 const FLOAT = 'Float';
 const STRING = 'String';
+const LONG_STRING = 'LongString';
 const COMMENT = 'Comment';
 
 /**
@@ -127,6 +128,7 @@ export const TokenKind = {
   INT,
   FLOAT,
   STRING,
+  LONG_STRING,
   COMMENT
 };
 
@@ -270,7 +272,12 @@ function readToken(lexer: Lexer<*>, prev: Token): Token {
     case 53: case 54: case 55: case 56: case 57:
       return readNumber(source, position, code, line, col, prev);
     // "
-    case 34: return readString(source, position, line, col, prev);
+    case 34:
+      if (charCodeAt.call(body, position + 1) === 34 &&
+          charCodeAt.call(body, position + 2) === 34) {
+        return readLongString(source, position, line, col, prev);
+      }
+      return readString(source, position, line, col, prev);
   }
 
   throw syntaxError(
@@ -453,10 +460,14 @@ function readString(source, start, line, col, prev): Token {
     position < body.length &&
     (code = charCodeAt.call(body, position)) !== null &&
     // not LineTerminator
-    code !== 0x000A && code !== 0x000D &&
-    // not Quote (")
-    code !== 34
+    code !== 0x000A && code !== 0x000D
   ) {
+    // Closing Quote (")
+    if (code === 34) {
+      value += slice.call(body, chunkStart, position);
+      return new Tok(STRING, start, position + 1, line, col, prev, value);
+    }
+
     // SourceCharacter
     if (code < 0x0020 && code !== 0x0009) {
       throw syntaxError(
@@ -509,12 +520,65 @@ function readString(source, start, line, col, prev): Token {
     }
   }
 
-  if (code !== 34) { // quote (")
-    throw syntaxError(source, position, 'Unterminated string.');
+  throw syntaxError(source, position, 'Unterminated string.');
+}
+
+/**
+ * Reads a long string token from the source file.
+ *
+ * """("?"?(\\"""|\\(?!=""")|[^"\\]))*"""
+ */
+function readLongString(source, start, line, col, prev): Token {
+  const body = source.body;
+  let position = start + 3;
+  let chunkStart = position;
+  let code = 0;
+  let value = '';
+
+  while (
+    position < body.length &&
+    (code = charCodeAt.call(body, position)) !== null
+  ) {
+    // Closing Triple-Quote (""")
+    if (
+      code === 34 &&
+      charCodeAt.call(body, position + 1) === 34 &&
+      charCodeAt.call(body, position + 2) === 34
+    ) {
+      value += slice.call(body, chunkStart, position);
+      return new Tok(LONG_STRING, start, position + 3, line, col, prev, value);
+    }
+
+    // SourceCharacter
+    if (
+      code < 0x0020 &&
+      code !== 0x0009 &&
+      code !== 0x000A &&
+      code !== 0x000D
+    ) {
+      throw syntaxError(
+        source,
+        position,
+        `Invalid character within String: ${printCharCode(code)}.`
+      );
+    }
+
+    // Escape Triple-Quote (\""")
+    if (
+      code === 92 &&
+      charCodeAt.call(body, position + 1) === 34 &&
+      charCodeAt.call(body, position + 2) === 34 &&
+      charCodeAt.call(body, position + 3) === 34
+    ) {
+      value += slice.call(body, chunkStart, position) + '"""';
+      position += 4;
+      chunkStart = position;
+    } else {
+      ++position;
+    }
   }
 
-  value += slice.call(body, chunkStart, position);
-  return new Tok(STRING, start, position + 1, line, col, prev, value);
+  throw syntaxError(source, position, 'Unterminated string.');
 }
 
 /**

src/language/parser.js

@@ -544,10 +544,12 @@ function parseValueLiteral(lexer: Lexer<*>, isConst: boolean): ValueNode {
         loc: loc(lexer, token)
       };
     case TokenKind.STRING:
+    case TokenKind.LONG_STRING:
       lexer.advance();
       return {
         kind: (STRING: 'StringValue'),
         value: ((token.value: any): string),
+        long: token.kind === TokenKind.LONG_STRING,
         loc: loc(lexer, token)
       };
     case TokenKind.NAME:

src/language/printer.js

@@ -74,7 +74,8 @@ const printDocASTReducer = {
 
   IntValue: ({ value }) => value,
   FloatValue: ({ value }) => value,
-  StringValue: ({ value }) => JSON.stringify(value),
+  StringValue: ({ value, long }) =>
+    long ? `"""${value.replace(/"""/g, '\\"""')}"""` : JSON.stringify(value),
   BooleanValue: ({ value }) => JSON.stringify(value),
   NullValue: () => 'null',
   EnumValue: ({ value }) => value,