Formatting of multiline strings

[0x6675636b796f75676974687562]

Abstract

In light of the recent fixes (#1364)) for the way we format multiline strings, it makes sense to agree on how exactly we format string literals which are not effective call arguments.

There're two aspects to consider:

1. The indentation of the closing """.
2. The indentation of single LITERAL_STRING_TEMPLATE_ENTRY nodes (at least, in the .trimMargin() case).

Ideas

Variants:

1. The closing """ as well as each line are aligned using a fractional indent size (not a multiple of 4, we can introduce a separate flag similar to alignedParameters):

   fun f() {
       val xyz = """
                 | First
                 | Second
                 | Third
                 """.trimMargin()
   }

   This approach may be considered similar to the way block/Javadoc/KDoc/Doxygen comments are formatted, and there're variations, too:

   /*
    * Either this...
    */
   
   /*
   * ... or this...
   */
   
   /**
     * ... or even this (Javadoc/KDoc/Doxygen only).
     */

2. The closing """ is indented, using a single or a continuation indent, w. r. t. the current indentation level, and string fragments which start with |, use the same indentation level (we'd need a new extendedIndentInMultilineStrings flag):

   companion object Foo : Bar {
       private val xyz = """
           | First
           | Second
           | Third
           """.trimMargin()
   }

   Same as above, using a continuation indent (extendedIndentInMultilineStrings is on):

   companion object Foo : Bar {
       private val xyz = """
               | First
               | Second
               | Third
               """.trimMargin()
   }

3. Neither the closing """ nor any fragments starting with | are indented at all:

   companion object {
       private val xyz = """
       | First
       | Second
       | Third
       """.trimMargin()
   }

All the above examples may feature |-fragments being additionally indented w. r. t. the closing """, optionally controlled by a separate flag, e. g.:

    """
        | First
        | Second
        | Third
    """.trimMargin()

Whenever a string literal is followed by a .trimIndent() call or a .trimXyz() call or no call at all (we must handle this case, too), LITERAL_STRING_TEMPLATE_ENTRY nodes should retain their original indentation, only the closing """ should be indented.

Existing style guides

Kotlin style guide says nothing about indentation (nor does IDEA) but provides these examples:

println("""
    Not
    trimmed
    text
    """
       )

println("""
    Trimmed
    text
    """.trimIndent()
       )

println()

// A.S.: LITERAL_STRING_TEMPLATE_ENTRY nodes indented using 10 spaces despite 4 spaces are used for indentation:
val a = """Trimmed to margin text:
          |if(a > 1) {
          |    return a
          |}""".trimMargin()

println(a)

Additionally, the Java-to-Kotlin migration guide provides two extra examples:

// Kotlin   
val result = """
        Kotlin
        Java 
    """.trimIndent()
println(result)

(the closing """ indented once) and

// Kotlin
fun main() {
    val result = """
       #  Kotlin
       #  Java
   """.trimMargin("#")
    println(result)
}

(the closing """ indented using 3 spaces which is probably a mistake).

@akuleshov7, @Arrgentum, WDYT?

[orchestr7]

I love this one:

val a = // <-- new line?
    """
        | First
        | Second
        | Third
    """.trimMargin()

May be we will force to move it to a new line ALWAYS?

This one is also fine:

val result = """
        Kotlin
        Java 
    """.trimIndent()

But I prefer the first one

[0x6675636b796f75676974687562]

Good point, but how about single-line raw strings?

val a = """|Mary had a little lamb""".trimMargin()

[orchestr7]

Change it to a single line text instead of multiline with diktat :D
Can be a separate inspection

val a = "|Mary had a little lamb".trimMargin()

[petertrr]

Single-quoted and triple-quoted strings have different escaping rules, so it may be quite complicated to implement (and in some cases users would use triple-quoted strings just because of this):

val a = """|Mary had a "little" lamb""".trimMargin()  // <-- we'll have to find quotes inside the triple-quoted string and escape them for correct conversion

[orchestr7]

yeah, then we can simply leave it as is