Skip to content

Commit

Permalink
Additional note about formatting of block strings for legibility (#394)
Browse files Browse the repository at this point in the history
  • Loading branch information
leebyron authored Dec 21, 2017
1 parent 8041a9e commit 902f24c
Showing 1 changed file with 19 additions and 2 deletions.
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

2 comments on commit 902f24c

@samuelu253
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

0

@samuelu253
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

0

Please # to comment.