Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Additional note about formatting of block strings for legibility #394

Merged
merged 1 commit into from
Dec 21, 2017
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 19 additions & 2 deletions spec/Section 2 -- Language.md
Original file line number Diff line number Diff line change
Expand Up @@ -731,7 +731,7 @@ indentation and blank initial and trailing lines via {BlockStringValue()}.

For example, the following operation containing a block string:

```graphql
```graphql example
mutation {
sendEmail(message: """
Hello,
Expand All @@ -745,12 +745,29 @@ mutation {

Is identical to the standard quoted string:

```graphql
```graphql example
mutation {
sendEmail(message: "Hello,\n World!\n\nYours,\n GraphQL.")
}
```

Since block string values strip leading and trailing empty lines, there is no
single canonical printed block string for a given value. Because block strings
typically represent freeform text, it is considered easier to read if they begin
and end with an empty line.

```graphql example
"""
This starts with and ends with an empty line,
which makes it easier to read.
"""
```

```graphql counter-example
"""This does not start with or end with any empty lines,
which makes it a little harder to read."""
```

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
block string.
Expand Down