In Ruby, how do <<~, <<- and plain << heredocs differ, and what does quoting the identifier change?

## What a heredoc is A **here document** (heredoc) is a string literal for multi-line text. It opens with `<<` and an identifier, the body starts on the **next line**, and it ends at the first line that contains only the identifier. The resulting string includes the newline of the last body line. ```ruby banner = <<EOS BEAN THERE COFFEE EOS banner # => "BEAN THERE COFFEE\n" ``` Uppercase identifiers such as `EOS`, `SQL` or `RECEIPT` are conventional, and naming them after the content helps editors highlight the body. ## Three openers | Opener | Terminator may be indented | Body indentation kept | |---|---|---| | `<<EOS` | no, must start at column 0 | yes, exactly as written | | `<<-EOS` | yes | yes, exactly as written | | `<<~EOS` | yes | no, common indentation removed | - **`<<EOS`** is the original form. Inside an indented method, the terminator at column 0 breaks the visual structure of the code. - **`<<-EOS`** fixes only the terminator. If you indent the body to match the code, those spaces become part of the string. - **`<<~EOS`** (the squiggly heredoc) measures the indentation of the least-indented line and removes that much from every line. Blank lines and lines made only of spaces or tabs are ignored when measuring; escaped spaces and tabs count as content. ## The squiggly heredoc in a receipt ```ruby def receipt_footer(total) <<~FOOTER ------------------------------ TOTAL #{format("%24.2f", total)} Thank you, come again! FOOTER end ``` Four spaces are the smallest indentation, so they are removed from each line; the thank-you line keeps its extra two spaces. The terminator sits at the method's own indentation. Tabs are measured as advancing to the next multiple of eight columns; mixing tabs and spaces in a squiggly body is legal but hard to reason about, so most style guides forbid it. ## Quoting the identifier The quotes around the identifier choose the literal type of the body: 1. **Unquoted** or **double-quoted** (`<<~EOS`, `<<~"EOS"`): like a double-quoted string, with `#{}` interpolation and escapes such as `\n` and `\t`. 2. **Single-quoted** (`<<~'EOS'`): like a single-quoted string. `#{...}` and backslashes stay as typed, which suits embedded code samples, shell scripts or templates rendered later. 3. **Backticks** (`` <<~`CMD` ``): the body is run as a shell command, like `Kernel#` `` ` ``, and the heredoc evaluates to its output. ## Calling methods and passing heredocs Anything after the opener on the same line is ordinary code, so methods apply to the whole heredoc: - `<<~SQL.chomp` drops the final newline. - `<<~TEXT.lines.map(&:strip)` post-processes each line. - `puts(<<~ONE, <<~TWO)` opens two heredocs on one line; their bodies follow in order. Legal, but hard to read. ## When a heredoc is the right tool Ruby offers several ways to write multi-line text, and each has a sweet spot: - A **double-quoted string** can simply span lines, but its continuation lines must start at column 0 or their indentation becomes content. - **Adjacent literals** joined with a trailing backslash suit two or three long lines without newlines between them. - **`Array#join`** on a list of lines suits text assembled conditionally, such as a receipt that prints a discount line only when a discount applies. - A **squiggly heredoc** suits fixed text with a few interpolated values: SQL, email bodies, help output and receipt templates. - A **separate template file** suits long or translated text that non-developers edit. ## Common mistakes - Using `<<-` and expecting the body to be de-indented; only `<<~` does that. - Forgetting that the result ends with `"\n"`, then comparing it with a string that does not. - Interpolating a multi-line value into `<<~` and expecting it to be re-indented; the de-indentation is computed from the literal source lines, and inserted text is used as it is. - Writing the terminator with trailing text; the terminator line must hold only the identifier (plus leading whitespace for `<<-` and `<<~`).