branch: externals/ess
commit e39ca8fa7fce703aa2851e83987a412737d575f0
Author: Martin Maechler <[email protected]>
Commit: Martin Maechler <[email protected]>
Support for outline-minor-mode by Christophe Gouel
---
ChangeLog | 7 ++++++-
doc/ess.texi | 40 ++++++++++++++++++++++++++++++++++++++++
lisp/ess-custom.el | 6 ++++++
lisp/ess-r-mode.el | 11 +++++++++++
4 files changed, 63 insertions(+), 1 deletion(-)
diff --git a/ChangeLog b/ChangeLog
index 74a4d61a1f..6d11a1fa46 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+2025-10-27 Christophe Gouel <[email protected]>
+
+ * lisp/ess-custom.el: Support for outline-minor-mode
+ * lisp/ess-r-mode.el: Support for outline-minor-mode
+ * doc/ess.texi: Support for outline-minor-mode
+
2025-01-10 ESS Maintainers <[email protected]>
* Version 25.01.0 released.
@@ -6565,4 +6571,3 @@ The following is from the original Changelog section of
S.el
Wed May 12 dmith
* Change definition of S-dumped-missing-re to cope with 3.1
-
diff --git a/doc/ess.texi b/doc/ess.texi
index b7188fa0dc..774a685421 100644
--- a/doc/ess.texi
+++ b/doc/ess.texi
@@ -2833,6 +2833,7 @@ ESS has a few extra features, which didn't fit anywhere
else.
* Parens:: Parenthesis matching
* Graphics:: Using graphics with ESS
* Imenu:: Support for Imenu in ESS
+* Outline:: Use outline-minor-mode in R scripts
* Toolbar:: Support for toolbar in ESS
* Xref:: Xref
* Rdired:: Directory editor for R objects
@@ -3082,6 +3083,45 @@ function definition. To examine the regular expression
that ESS uses,
check the value of @code{imenu-generic-expression}. This value is set
by various ESS variables such as @code{ess-imenu-S-generic-expression}.
+@node Outline
+@section Outline navigation
+@cindex outline-minor-mode
+@cindex code folding
+@findex outline-minor-mode
+@findex ess-r-outline-level
+@vindex ess-r-outline-regexp
+R editing buffers integrate with @code{outline-minor-mode}. When you
+toggle the minor mode (for example via @kbd{M-x outline-minor-mode} or
+by adding it to @code{ess-r-mode-hook}), ESS assigns
+@code{ess-r-outline-level} to @code{outline-level} and installs
+@code{ess-r-outline-regexp} so that comment headings drive folding.
+Lines that begin with one or more @samp{#}, followed by text and a
+trailing marker of @samp{----}, @samp{====}, or @samp{####}, are treated
+as outline headings. This matches the section markers convention adopted by
+RStudio.
+
+@example
+# Setup ----
+## Data ----
+### Models ====
+#### Helpers ####
+@end example
+
+The number of leading @samp{#} characters sets the outline depth. Use
+standard Outline commands (such as @kbd{C-c @ C-t}) to cycle visibility once
+the minor mode is active. To enable Outlining automatically, add it to the R
+mode hook:
+
+@example
+(add-hook 'ess-r-mode-hook #'outline-minor-mode)
+@end example
+
+@defvr {User Option} ess-r-outline-regexp
+Regular expression used by ESS to recognise outline headings in R
+buffers. The default matches the RStudio-style sections shown above,
+but you can customise it if you prefer a different comment convention.
+@end defvr
+
@node Toolbar
@section Toolbar
diff --git a/lisp/ess-custom.el b/lisp/ess-custom.el
index 08a8409171..6610822242 100644
--- a/lisp/ess-custom.el
+++ b/lisp/ess-custom.el
@@ -1571,6 +1571,12 @@ by `ess-function-template'."
:group 'ess
:type 'regexp)
+(defcustom ess-r-outline-regexp
+ "^[ \t]*#+ +.*\\(?:----\\|====\\|####\\)\\s-*$"
+ "Regexp used to detect the beginning of R headings."
+ :group 'ess-R
+ :type 'regexp)
+
; ess-inf: variables for inferior-ess.
diff --git a/lisp/ess-r-mode.el b/lisp/ess-r-mode.el
index 2a6c329329..8cb0d9e0a2 100644
--- a/lisp/ess-r-mode.el
+++ b/lisp/ess-r-mode.el
@@ -299,6 +299,14 @@ When t, loading a file into a namespaced will output
information
about which objects are exported and which stay hidden in the
namespace.")
+(defun ess-r-outline-level ()
+ "R mode `outline-level` function."
+ (save-excursion
+ (beginning-of-line)
+ (if (looking-at "^[ \t]*\\(#+\\)\\s-")
+ (length (match-string 1))
+ 1000)))
+
;; The syntax class for '\' is punctuation character to handle R 4.1
;; lambdas. Inside strings it should be treated as an escape
;; character which we ensure here.
@@ -855,6 +863,9 @@ top level functions only."
(setq imenu-generic-expression ess-imenu-S-generic-expression)
(when ess-imenu-use-S
(imenu-add-to-menubar "Imenu-R"))
+ ;; outline
+ (setq-local outline-level #'ess-r-outline-level)
+ (setq-local outline-regexp ess-r-outline-regexp)
(setq-local beginning-of-defun-function #'ess-r-beginning-of-defun)
(setq-local end-of-defun-function #'ess-r-end-of-defun)
(ess-roxy-mode))
