Skip to content

Commit 902f24c

Browse files
authored
Additional note about formatting of block strings for legibility (#394)
1 parent 8041a9e commit 902f24c

File tree

1 file changed

+19
-2
lines changed

1 file changed

+19
-2
lines changed

spec/Section 2 -- Language.md

Lines changed: 19 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -731,7 +731,7 @@ indentation and blank initial and trailing lines via {BlockStringValue()}.
731731

732732
For example, the following operation containing a block string:
733733

734-
```graphql
734+
```graphql example
735735
mutation {
736736
sendEmail(message: """
737737
Hello,
@@ -745,12 +745,29 @@ mutation {
745745

746746
Is identical to the standard quoted string:
747747

748-
```graphql
748+
```graphql example
749749
mutation {
750750
sendEmail(message: "Hello,\n World!\n\nYours,\n GraphQL.")
751751
}
752752
```
753753

754+
Since block string values strip leading and trailing empty lines, there is no
755+
single canonical printed block string for a given value. Because block strings
756+
typically represent freeform text, it is considered easier to read if they begin
757+
and end with an empty line.
758+
759+
```graphql example
760+
"""
761+
This starts with and ends with an empty line,
762+
which makes it easier to read.
763+
"""
764+
```
765+
766+
```graphql counter-example
767+
"""This does not start with or end with any empty lines,
768+
which makes it a little harder to read."""
769+
```
770+
754771
Note: If non-printable ASCII characters are needed in a string value, a standard
755772
quoted string with appropriate escape sequences must be used instead of a
756773
block string.

0 commit comments

Comments
 (0)