Add new `str_dedent` function by chrimaho · Pull Request #514 · tidyverse/stringr

chrimaho · 2023-06-10T07:29:33Z

One incredibly helpful function in Python is the textwrap.dedent function. Under the hood, this function uses regex to strip any leading spaces, while maintaining any internal indentation within a chunk of code.

This addition here re-implements the same functionality using native R code.

I've ensured to include 4 different unit tests for the same.

arnaudgallou · 2024-09-05T09:54:26Z

I'd also like to have a dedent() function in R. Two comments:

Wouldn't it make sense to trim leading and trailing whitespaces in the output or add an argument to do so? That would be very useful when making character strings from multi-line text in R:
```
str_dedent("
  This is a long sentence that starts on the first line,
  continues on the second,
  and ends on the third one.
")
```
For readability purposes, it's better to start the text on its own line here. We wouldn't want to keep that blank line at the beginning though. Passing the output to str_trim() every time in that situation would be cumbersome.
The function currently doesn't support the following situation (when python's textwrap.dedent() does):
```
str_dedent("
    foo
  bar
")
```
It's probably uncommon enough not to support it but that could be detailed in the function documentation.

lionel-

It'd be nice if this function was consistent with glue::glue(), at least in important cases, so users don't have to remember differences or look up documentation every time.

I think this means in particular trimming the trailing whitespace by default:

glue::glue("\nfoo\n") |> unclass()
#> [1] "foo"

There are other subtle differences where it's probably not helpful to follow glue. For instance, the indentation is computed from all empty lines, including those that are trimmed, in a way I don't fully understand:

glue::glue("\n \n\n ") |> unclass()
#> [1] "\n"
glue::glue("\n  \n\n ") |> unclass()
#> [1] " \n"
glue::glue("\n  \n\n  ") |> unclass()
#> [1] "\n"
glue::glue("\n  \n\n   ") |> unclass()
#> [1] "  \n"

I also don't understand the behaviour with 2 empty lines, I would have expected "" here:

glue::glue("\n") |> unclass()
#> [1] ""
glue::glue("\n\n") |> unclass()
#> [1] "\n"
glue::glue("\n\n\n") |> unclass()
#> [1] "\n"
glue::glue("\n\n\n\n") |> unclass()
#> [1] "\n\n"
glue::glue("\n\n\n\n\n") |> unclass()
#> [1] "\n\n\n"

For comparison (one more empty line than glue due to trailing one being preserved as of now):

str_dedent("\n") |> unclass()
#> [1] ""
str_dedent("\n\n") |> unclass()
#> [1] "\n"
str_dedent("\n\n\n") |> unclass()
#> [1] "\n\n"
str_dedent("\n\n\n\n") |> unclass()
#> [1] "\n\n\n"
str_dedent("\n\n\n\n\n") |> unclass()
#> [1] "\n\n\n\n"

So while I think compatibility with glue in terms of deleting empty trailing lines would be nice for this function, full compat is probably not worth pursuing.

DavisVaughan · 2025-09-23T13:27:31Z

Like @lionel-, I think I am also surprised by the trailing \n here

library(stringr)
library(glue)

glue_chr <- function(...) { 
  unclass(glue(...))
}

str_dedent("
  Line 1
  Line 2
  Line 3
")
#> [1] "Line 1\nLine 2\nLine 3\n"
glue_chr("
  Line 1
  Line 2
  Line 3
")
#> [1] "Line 1\nLine 2\nLine 3"

I would have expected the above to give this output

str_dedent("
  Line 1
  Line 2
  Line 3")
#> [1] "Line 1\nLine 2\nLine 3"
glue_chr("
  Line 1
  Line 2
  Line 3")
#> [1] "Line 1\nLine 2\nLine 3"

I think an invariant of this function could be:

Strips all leading and trailing whitespace from the output

which provides a nice symmetry and nice user experience

DavisVaughan · 2025-09-23T13:39:21Z

+#' It does this by removing the common leading indentation from each line
+#' (ignoring lines only containing whitespace), and removing the first line,
+#' if it only contains whitespace.


Suggested change

#' It does this by removing the common leading indentation from each line

#' (ignoring lines only containing whitespace), and removing the first line,

#' if it only contains whitespace.

#' It does this by:

#' - Trimming all leading and trailing whitespace

#' - Removing the first line if it only contains whitespace

#' - Removing the common leading indentation from each line (excluding lines containing only whitespace)

Here is my suggestion for the invariants of how this function should work (if we trim leading and trailing whitespace). (Needs a document() call)

hadley · 2025-09-24T17:02:06Z

@DavisVaughan you mean "Strips all leading and trailing whitespace lines from the output" right?

And you both really think we don't want a trailing new line? If you were going to cat() this you would want a trailing \n?

jennybc · 2025-09-24T18:28:54Z

First, I'll just add some bits from glue's documentation for reference:

Empty first and last lines are automatically trimmed, as is leading whitespace that is common across all lines.
...
If you want an explicit newline at the start or end, include an extra empty line.
...
Leading and trailing whitespace from the first and last lines is removed.

A uniform amount of indentation is stripped from the second line on, equal to the minimum indentation of all non-blank lines after the first.

As for this:

And you both really think we don't want a trailing new line? If you were going to cat() this you would want a trailing \n?

If you're just cat()ing the result of 1 str_dedent() call, I think it doesn't matter because the R console basically adds the trailing newline. And in more complicated situations, this is when I'd probably use cli::cat_line() anyway.

jennybc · 2025-09-24T18:34:12Z

+    return(lines)
+  }
+
+  ws <- str_length(str_extract(lines, "^ *"))


Suggested change

ws <- str_length(str_extract(lines, "^ *"))

ws <- str_length(str_extract(lines, "^[ \t]*"))

Seems like we should also be thinking about tabs?

I think it's better to just ignore them since we don't use them. If we did, I think we'd need to multiply by the tab stop size.

...

Hmmm, I guess we need to think about this because people might be using tabs for indenting.

hadley · 2025-09-24T19:02:46Z

@jennybc that's only true if it's at the top-level (i.e. if you cat multiple times before returning, you need newlines in between them).

I'm not sure why I'm so far apart on trailing newlines than the rest of you. I thought this was a situation where preserving them was "obviously correct".

jennybc · 2025-09-24T19:42:59Z

if you cat multiple times before returning, you need newlines in between them)

I guess that's when I would use cli::cat_line().

We're talking a lot about glue, which stringr imports. Which makes me wonder ... why isn't str_dedent() just glue::trim()? 🤔

hadley · 2025-09-24T22:44:22Z

That is a good question. If I replace the existing implementation with a direct call to glue::trim() then I get the following failures:

── Failure ([test-remove.R:12:3](vscode-file://vscode-app/Applications/Positron.app/Contents/Resources/app/out/vs/code/electron-browser/workbench/workbench.html#)): strips common ws ──────────────────────────────────────────────────────────────────────────────
str_dedent("  Hello\n    World") (`actual`) not equal to "Hello\n  World" (`expected`).

`lines(actual)`:   "Hello" "World"  
`lines(expected)`: "Hello" "  World"

── Failure ([test-remove.R:13:3](vscode-file://vscode-app/Applications/Positron.app/Contents/Resources/app/out/vs/code/electron-browser/workbench/workbench.html#)): strips common ws ──────────────────────────────────────────────────────────────────────────────
str_dedent("    Hello\n  World") (`actual`) not equal to "  Hello\nWorld" (`expected`).

`lines(actual)`:   "Hello"   "World"
`lines(expected)`: "  Hello" "World"

── Failure ([test-remove.R:25:3](vscode-file://vscode-app/Applications/Positron.app/Contents/Resources/app/out/vs/code/electron-browser/workbench/workbench.html#)): preserves final newline ───────────────────────────────────────────────────────────────────────
str_dedent("  Hello\n  World\n") (`actual`) not equal to "Hello\nWorld\n" (`expected`).

`lines(actual)`:   "Hello" "World"   
`lines(expected)`: "Hello" "World" ""

── Failure ([test-remove.R:35:3](vscode-file://vscode-app/Applications/Positron.app/Contents/Resources/app/out/vs/code/electron-browser/workbench/workbench.html#)): preserves final newline ───────────────────────────────────────────────────────────────────────
str_dedent("\n      Hello\n      World\n    ") (`actual`) not equal to "Hello\nWorld\n" (`expected`).

`lines(actual)`:   "  Hello" "  World"   
`lines(expected)`: "Hello"   "World"   ""

I can make most of them go away by adding a leading \n to the strings (which better reflects real use), but the remaining weirdness is this:

cat(
  glue::trim("
    Hello
      World
  ")
)
#>   Hello
#>     World

^{Created on 2025-09-24 with reprex v2.1.1}

I find the extra indent here surprising. But maybe we could fix that?

lionel- · 2025-09-25T07:59:37Z

If you're just cat()ing the result of 1 str_dedent() call, I think it doesn't matter because the R console basically adds the trailing newline

The Positron and RStudio consoles do (at top-level as Hadley mentions), but not the R console:

If you were going to cat() this you would want a trailing \n?

I would expect the caller of cat() to add the trailing \n. But I think that's a case where I'd pipe the output to writeLines() (or use cat_line() as Jenny suggests).

Copilot

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Copilot review overview

4 open issues

@inheritParams str_detect likely pulls in a pattern parameter doc that str_dedent() doesn’t… · New
The last expectation doesn’t actually test str_dedent() on NA (it compares NA_character_ to… · New
The example applies str_dedent() twice (f() already dedents). This is redundant and may confuse… · New
trim_empty_ends is unused within str_dedent_1(), which adds confusion and suggests… · New

1 file not reviewed

man/str_dedent.Rd: Generated file

What changed in this PR

Adds a new str_dedent() utility (similar to Python’s textwrap.dedent) to remove common leading indentation from multi-line strings, with documentation, exports, and unit tests.

Changes:

Implement str_dedent() and helper str_dedent_1() in R.
Add testthat coverage for indentation stripping, empty-line handling, and newline preservation.
Export and document str_dedent() via NAMESPACE and pkgdown reference index.

File	Description
`R/remove.R`	Adds `str_dedent()` implementation and roxygen documentation/examples.
`tests/testthat/test-remove.R`	Adds unit tests covering core `str_dedent()` behaviors.
`NAMESPACE`	Exports the new `str_dedent()` function.
`_pkgdown.yml`	Lists `str_dedent` in the reference index for documentation site generation.

_{Review effort: Lite}

+#' It is inspired by Python's
+#' [`textwrap.dedent()`](https://docs.python.org/3/library/textwrap.html#textwrap.dedent).
+#'
+#' @inheritParams str_detect


+  expect_equal(str_dedent(character()), character())
+  expect_equal(str_dedent(""), "")
+  expect_equal(str_dedent("one line"), "one line")
+  expect_equal(NA_character_, NA_character_)


+#'     Line 3
+#'   ")
+#' }
+#' cat(str_dedent(f()))


+  map_chr(lines, str_dedent_1)
+}
+
+str_dedent_1 <- function(lines, trim_empty_ends = TRUE) {


chrimaho and others added 4 commits June 10, 2023 17:11

Add new str_dedent function

de85c68

Merged origin/main into chrimaho-main

b78752e

Re-document

60e6fe1

Polish implementation

a8607e9

hadley added 2 commits September 22, 2025 15:48

Merge commit '32aaf82e2101e3759f13574be752764983548dd6'

f11b135

Revise implementation + docs

64424de

lionel- reviewed Sep 23, 2025

View reviewed changes

DavisVaughan reviewed Sep 23, 2025

View reviewed changes

jennybc reviewed Sep 24, 2025

View reviewed changes

Merge remote-tracking branch 'origin/main' into pr-514

33a49d5

Copilot AI balanced review requested due to automatic review settings October 26, 2026 20:01

Copilot AI reviewed Oct 26, 2026

View reviewed changes

Copilot stopped reviewing on behalf of chrimaho due to an error October 26, 2026 20:24
The job was not acquired by a runner even after multiple attempts.

-#' It does this by removing the common leading indentation from each line
-#' (ignoring lines only containing whitespace), and removing the first line,
-#' if it only contains whitespace.
+#' It does this by:
+#' - Trimming all leading and trailing whitespace
+#' - Removing the first line if it only contains whitespace
+#' - Removing the common leading indentation from each line (excluding lines containing only whitespace)

	ws <- str_length(str_extract(lines, "^ *"))
	ws <- str_length(str_extract(lines, "^[ \t]*"))

Conversation

chrimaho commented Jun 10, 2023

Uh oh!

arnaudgallou commented Sep 5, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lionel- left a comment

Choose a reason for hiding this comment

Uh oh!

DavisVaughan commented Sep 23, 2025

Uh oh!

DavisVaughan Sep 23, 2025

Choose a reason for hiding this comment

Uh oh!

hadley commented Sep 24, 2025

Uh oh!

jennybc commented Sep 24, 2025

Uh oh!

jennybc Sep 24, 2025

Choose a reason for hiding this comment

Uh oh!

hadley Sep 24, 2025

Choose a reason for hiding this comment

Uh oh!

hadley commented Sep 24, 2025

Uh oh!

jennybc commented Sep 24, 2025

Uh oh!

hadley commented Sep 24, 2025

Uh oh!

lionel- commented Sep 25, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

arnaudgallou commented Sep 5, 2024 •

edited

Loading