mojombo/toml — pull request #164 by ianstormtaylor (2013-03-03 00:44:50+00:00)
Title: adds multi-line and block strings

Collection of ideas from #17, #92 and #163.

The basic idea is that there are two cases for multi-line strings:

## Writing a long sentence.

You don't want random line breaks inserted just because you're wrapping lines. And the use cases that really need line breaks are few and far between, so adding an `\n` when you need it is perfectly reasonable (and actually already required).

@pygy's argument against having line-breaks ignored by default is that it forces you to un-indent the text.

One of the questions you have to ask is are we supporting wrapping strings just so that long strings are _possible_, or do we want to make it easy on the author to write strings across lines. I think authoring experience is **very** important. It's one of the biggest reasons that JSON sucks to use.

Both of @pygy's solutions in #163 aren't good in my book because they make the author's experience much more difficult. Adding `+`'s or closing `"`'s to each line isn't minimal. And it makes it much harder to use nice editor built-ins like `cmd-ctrl-Q` in Sublime (wrap paragraph at ruler).

That leads to three solutions:

1. Un-indent your strings. Which is really unfortunate, because at this point the benefit of indentation is lost.

2. Strings should respect their indentation. This makes the author's job simpler, but the parser's job harder. Tom said this [fills him with rage](https://github.com/mojombo/toml/issues/17#issuecomment-14017011). (Maybe we can solve that? :smiley:)

3. Don't indent. This could either be just a style that authors adopt, or TOML could disallow indentation altogether. (Disallowing seems too extreme.)

I think 2 or 3 are the best solutions here. If Tom really does hate indenting strings too much to have it, then authors can just choose to never indent their documents.

Regardless, the syntax looks the same in isolation:

```toml
sentence = "I will probably begin with a very classy first
line... something like: say, sweet thing, can I buy you a
fish sandwich?"
```

----

## Writing blocks of text (like markdown, lists).
The other use case if for writing blocks of text for all your line breaks are intentional, necessary. You don't want your bulleted list to be wrapped onto one line.

One of the big use cases for block strings is copy-pasting chunks of text. For that reason, we want the text to be disconnected from the TOML syntax around it, so that we don't have to have our source text and our `"""`'s intermingle, like @pygy [said in #92](https://github.com/mojombo/toml/pull/92#issuecomment-14331696)

We want to directly copy-and-paste in a block:

```toml
block = """
Here's a numbered list:
1. One
2. Two
3. Three
- ay
- bee
- see
"""
```

To get the nicest authoring experience here we should require the `"""` triple quotes to be on their own lines. That also means that when you actually _do_ want a line break before or after your text, it's obvious:

```toml
block = """

This will be surrounded by line breaks.

"""
```

The same indentation question comes up with block strings. Actually I suspect this is the case that @mojombo hates more. It's not as simple as the other one because there are multiple ways to treat indentation:

```toml
name = "Tom Preston-Werner"
organization = "GitHub"
bio = "GitHub Cofounder & CEO\nLikes tater tots and beer."

[things]
[things.one]
enabled = true

block = """
I will probably begin with a very classy first line... something
like: say, sweet thing, can I buy you a fish sandwich?
"""

block = """
I will probably begin with a very classy first line... something
like: say, sweet thing, can I buy you a fish sandwich?
"""

block = """
I will probably begin with a very classy first line... something
like: say, sweet thing, can I buy you a fish sandwich?
"""
```

I think the third one can be instantly discounted, because it's just going to be annoying to indent to a different level based on the length of your key.

I think number two gets a little too confusing to write, because it's less clear what is an intentional indent meant for output, and what is just indenting the block itself.

So that leaves solution one. Which is actually nice, because it mimics the way normal (non-block) strings behave.

---

## They go together nicely.

You end up with a nice, similar syntax for both types of strings:

```toml
sentence = "I will probably begin with a very classy first
line... something like: say, sweet thing, can I buy you a
fish sandwich?"

block = """
I will probably begin with a very classy first line... something
like: say, sweet thing, can I buy you a fish sandwich?
"""
```

That's the syntax in this pull request. And it looks like that regardless of what gets decided about indentation, which I think just needs to be decided by @mojombo.