Outline view: Support nested sections in R scripts for if / else nested braces

[lionel-]

Discussed in #8874

^{Originally posted by seanthimons August 6, 2025}
Not sure if this issue thread (#3822) has also fixed this or missed it, but when using if else statements with braces, section headers do not appear in the outline. Is there a way to force this behavior/ work around it, or is this expected behavior?

[lionel-]

#9084 also reports the case of a function within a function (which is also fixed by the linked PR)

# Define the server logic for a module

# 1 Counter server -------------------------------------------------------

counterServer <- function(id) {
  moduleServer(
    id,
    function(input, output, session) {

      # 1.1 Reactive value ----------------------------------------------------      
      count <- reactiveVal(0)

      # 1.2 Observe event -----------------------------------------------------
      observeEvent(input$button, {
        count(count() + 1)
      })

      # 1.3 Render output -----------------------------------------------------
      output$out <- renderText({
        count()
      })

      # 1.4 Return the reactive value ----------------------------------------
      count
    }
  )
}

[rodrigosf672]

NTS

QA Notes

Comment sections and other kinds of document symbols in if-else branches and loops are now part of the outline:

# top ----

if (TRUE) {
  # if ----
  foo <- function() {}
} else {
  # else ----
  foo <- function() {}
}

for (i in xs) {
  # loop ----
  bar <- function() {}
}

Comment sections in parameter lists of function definitions are now included as well. We don't recurse through default arguments though.

x <- function(
  # section ----
  arg = function() {
    # not a section ----
  }
) {
  ...
}

[rodrigosf672]

Verified Fixed

Positron Version(s) : 2025.10.0 build 8
OS Version          : macOS Sequoia 15.6

Test scenario(s)

• Outline view correctly displays nested sectins in R scripts for if/else nested braces

Example described

Additional examples
@lionel- I didn't find comprehensive tests for outlining and for making sure certain characters don't break anything, so I added some more comprehensive super-nested and character-rich R script example with different test cases to check that the outline view was correct and nothing broke for this release. All seems good. This is a good candidate for future automation as well, @testlabauto

# 0. TOP BY ITSELF =============
# Expected: "0. TOP LEVEL" appears by itself in the outline.

# top ----
xs <- 1:3

# 1. IF / ELSE CHAINS =====
# Expected: show "if", "else if", "else" sections under this block. Nested sub-sections visible.

if (TRUE) {
  # if ----
  msg_if <- "in if"
  
  if (FALSE) {
    # nested if ----
    msg_nested_if <- "nested if"
  } else if (TRUE) {
    # nested else if ----
    msg_nested_elif <- "nested else if"
  } else {
    # nested else ----
    msg_nested_else <- "nested else"
  }
  
} else if (FALSE) {
  # else if ----
  msg_elif <- "in else if"
} else {
  # else ----
  msg_else <- "in else"
}

# 2. LOOPS (for / while / repeat) + NESTED SECTIONS
# Expected: loop sections appear; nested sections inside loops appear.

for (i in xs) {
  # for loop ----
  val_i <- i * 2
  
  if (i %% 2 == 0) {
    # even branch ----
    even_val <- TRUE
  } else {
    # odd branch ----
    even_val <- FALSE
  }
}

i <- 1
while (i <= 3) {
  # while loop ----
  i <- i + 1
}

j <- 0
repeat {
  # repeat loop ----
  j <- j + 1
  if (j > 2) break
}

# 3. FUNCTIONS & NESTED DEFINITIONS =
# Expected: top-level function "f" visible; nested sections within body visible; 
#           nested function g() inside f() also visible (functions within functions).
#           Sections in parameter list at top-level are included (but no recursion through default args).

# f() ----
f <- function(
  # params: top-level section in param list ----
  x = 1,
  y = function() {
    # not a section (default arg inner) ----
    42
  }
) {
  # body section ----
  z <- x + 1
  
  # nested function g() ----
  g <- function(a) {
    # g body ----
    a * 2
  }
  
  if (z > 1) {
    # f-if branch ----
    g(z)
  } else {
    # f-else branch ----
    z
  }
}

# Another function with inline section on same line (edge pattern)
h <- function() { # h body ----
  # inner h ----
  1
}


# ===================================
# 4. SHINY MODULES & APP STRUCTURES ==
# ===================================
# Expected: module server/client sections and nested sub-sections visible.

# shiny: ui ----
app_ui <- function(request) {
  # ui.body ----
  "ui"
}

# shiny: server ----
app_server <- function(input, output, session) {
  # server.body ----
  NULL
}

# module: counter server ----
counterServer <- function(id) {
  moduleServer(
    id,
    function(input, output, session) {
      # 1 Reactive value ----
      rv <- reactiveVal(0)
      
      # 2 Observe event ----
      observeEvent(input$inc, {
        rv(rv() + 1)
      })
      
      # 3 Render ----
      output$out <- renderText({ rv() })
      
      # 4 Return ----
      rv
    }
  )
}

# module: counter ui ----
counterUI <- function(id) {
  # module.ui ----
  paste0("module-", id)
}



# 5. ERROR HANDLING (tryCatch / withCallingHandlers)

# Expected: outer sections and nested handler sections visible.

# tryCatch block ----
result <- tryCatch(
  {
    # try expr ----
    log(10)
  },
  warning = function(w) {
    # warning handler ----
    invokeRestart("muffleWarning")
  },
  error = function(e) {
    # error handler ----
    NA
  }
)

# withCallingHandlers block ----
out <- withCallingHandlers(
  {
    # wch expr ----
    sqrt(4)
  },
  warning = function(w) {
    # wch warning ----
    NULL
  }
)



# 6. SWITCH / LOCAL / WITH / SUBSET-LIKE ===

# Expected: sections inside special constructs appear.

# switch ----
k <- 2
ans <- switch(
  k,
  { # case 1 ----
    "one"
  },
  { # case 2 ----
    "two"
  },
  { # case 3 ----
    "three"
  }
)

# local ----
val <- local({
  # local block ----
  123
})

# with (environment) ----
env <- list(a = 1, b = 2)
with(env, {
  # with block ----
  a + b
})



# 7. PIPELINES / ANONYMOUS FUNCTIONS =======

# Expected: sections inside braces used for pipeline steps recognized;
#           anonymous function bodies with braces show sections.

# pipeline demo ----
numbers <- 1:5
numbers |>
  (\(x) { 
    # pipeline fn step ----
    x * 2 
  })() |>
  (\(y) {
    # pipeline second step ----
    y + 1
  })() -> piped_res



# 8. S3 / S4 / R6 STYLE DEFINITIONS ========
# Expected: class-related sections show where they’re just regular code blocks.

# S3: generic + method ----
print.myclass <- function(x, ...) {
  # print method body ----
  cat("<myclass>", "\n")
}

# S4-ish demo (without methods package to keep it simple in a .R file)
# s4 region ----
MyS4Class <- setClass("MyS4Class", slots = list(x = "numeric"))
MyS4 <- function(x) { # constructor ----
  new("MyS4Class", x = x)
}

# R6-like (no package): placeholder pattern ----
# r6 region ----
MyR6 <- list( # pretend R6 class ----
  new = function(...) { # r6 new ----
    list(...)
  }
)

# 9. DUPLICATE TITLES / UNICODE / EMOJI ====
# Expected: duplicates appear as separate sections; Unicode/emoji appear correctly.

# duplicates ----
dup_a <- 1
# duplicates ----
dup_b <- 2

# seção com acentuação ----
unic_val <- 10

# emoji 🚀 ----
rocket_val <- 42

# 10. EDGE CASES THAT SHOULD *NOT* MATCH ===
# Expected: The following SHOULD NOT create sections in the outline.

# A. Comment-like marker inside a *string*, not a comment:
txt <- "# pretend section ----"

# B. Roxygen comments should not count as section markers:
#' Title
#' @description not-a-section ----
#' @return nothing

# C. Comment not at column 1 (indented + code before marker) — depends on parser rules; include to verify:
val_c <- 1   # trailing inline ---- (many outline parsers only accept markers at line start)

# D. Marker-like token without trailing dashes (should not count as a section):
# almost a section -

# E. Too few dashes (also should not count, depending on rule):
# not enough --

# F. Marker inside default argument *string* (not comment):
fun_edge <- function(arg = "# nope ----") {
  1
}

# G. Long line with hashes but no exact pattern:
# ########## noise ######

# 11. NESTED CALLS & BRACES IN DATA STRUCTS
# Expected: sections within nested list/brace expressions appear.

# list construction ----
cfg <- list(
  a = 1,
  b = {
    # list-b ----
    2
  },
  c = (function() {
    # list-c ----
    3
  })()
)

# 12. SOURCE-ORDER & NEAR-BY MARKERS =======
# Expected: Ensure outline follows file order even with back-to-back markers (no blank lines).

# alpha ----
a_val <- 1
# beta ----
b_val <- 2
# gamma ----
g_val <- 3


# 13. LARGE NESTING DEPTH ==================
# Expected: All nested sections show in correct hierarchy.

# deep tree ----
if (TRUE) {
  # level 1 ----
  for (i in 1:2) {
    # level 2 ----
    repeat {
      # level 3 ----
      f_deep <- function() {
        # level 4 ----
        if (FALSE) {
          # level 5 ----
          0
        } else {
          # level 5b ----
          1
        }
      }
      break
    }
  }
}

# 14. INLINE BRACES & ONE-LINERS ===========
# Expected: Sections right before one-line blocks remain visible.

# one-liner if ----
if (TRUE) { 1 }

# one-liner function ----
one <- function() { # one body ----
  1
}



# 15. PARAMETER-LIST SECTIONS (VARIANTS) ===
# Expected: Only top-level parameter-list comment sections included; 
#           nested comments inside default expressions are *not* recursed.

# pfun ----
pfun <- function(
  # params A ----
  a = 1,
  # params B ----
  b = I(list(
    # not included: default nested ----
    2
  )),
  c = function() {
    # not included: default function body ----
    3
  }
) {
  # pfun body ----
  a + 1
}