(groovy) branch master updated: GROOVY-8162: Update Groovysh to JLine3 (documentation for widgets)

[pa...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

paulk pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/groovy.git


The following commit(s) were added to refs/heads/master by this push:
     new 83e2afe753 GROOVY-8162: Update Groovysh to JLine3 (documentation for widgets)
83e2afe753 is described below

commit 83e2afe753d03091ff727edc8503d92fda6d2dc2
Author: Paul King <pa...@asert.com.au>
AuthorDate: Thu Jul 31 17:12:09 2025 +1000

    GROOVY-8162: Update Groovysh to JLine3 (documentation for widgets)
---
 .../src/spec/doc/assets/img/widget1.png            | Bin 0 -> 30250 bytes
 .../src/spec/doc/assets/img/widget2.png            | Bin 0 -> 14842 bytes
 .../src/spec/doc/assets/img/widget3.png            | Bin 0 -> 34339 bytes
 .../groovy-groovysh/src/spec/doc/groovysh.adoc     |  65 ++++++++++++++++++---
 4 files changed, 58 insertions(+), 7 deletions(-)

diff --git a/subprojects/groovy-groovysh/src/spec/doc/assets/img/widget1.png b/subprojects/groovy-groovysh/src/spec/doc/assets/img/widget1.png
new file mode 100644
index 0000000000..d5690fd9d1
Binary files /dev/null and b/subprojects/groovy-groovysh/src/spec/doc/assets/img/widget1.png differ
diff --git a/subprojects/groovy-groovysh/src/spec/doc/assets/img/widget2.png b/subprojects/groovy-groovysh/src/spec/doc/assets/img/widget2.png
new file mode 100644
index 0000000000..cc768984d7
Binary files /dev/null and b/subprojects/groovy-groovysh/src/spec/doc/assets/img/widget2.png differ
diff --git a/subprojects/groovy-groovysh/src/spec/doc/assets/img/widget3.png b/subprojects/groovy-groovysh/src/spec/doc/assets/img/widget3.png
new file mode 100644
index 0000000000..8e5906a470
Binary files /dev/null and b/subprojects/groovy-groovysh/src/spec/doc/assets/img/widget3.png differ
diff --git a/subprojects/groovy-groovysh/src/spec/doc/groovysh.adoc b/subprojects/groovy-groovysh/src/spec/doc/groovysh.adoc
index 4aebb5a6a0..e43c7a28f4 100644
--- a/subprojects/groovy-groovysh/src/spec/doc/groovysh.adoc
+++ b/subprojects/groovy-groovysh/src/spec/doc/groovysh.adoc
@@ -646,6 +646,64 @@ mode.
 
 Edit-line history is stored in this file.
 
+[[GroovyShell-widgets]]
+=== Widgets
+
+JLine provides a powerful widget system that lets you extend the functionality of its line reader.
+A number of builtin widgets are available including `end-of-line`, `beginning-of-line`, `forward-word`, `backward-word`, `kill-word`, `backward-kill-word`, `capitalize-word`, `transpose-words`, and `yank-pop`, just to name a few. You can use the `/keymap` command to see the key bindings for these widgets.
+
+Groovy also includes JLine's _tailtip_ and _autosuggest_ widget functionality.
+You can see the related widgets by using the `/widget -l` command, which lists custom widgets.
+
+[source,shell]
+----
+groovy> /widget -l
+_autosuggest-end-of-line (_autosuggest-end-of-line)
+_autosuggest-forward-char (_autosuggest-forward-char)
+_autosuggest-forward-word (_autosuggest-forward-word)
+_tailtip-accept-line (_tailtip-accept-line)
+_tailtip-backward-delete-char (_tailtip-backward-delete-char)
+_tailtip-delete-char (_tailtip-delete-char)
+_tailtip-expand-or-complete (_tailtip-expand-or-complete)
+_tailtip-kill-line (_tailtip-kill-line)
+_tailtip-kill-whole-line (_tailtip-kill-whole-line)
+_tailtip-redisplay (_tailtip-redisplay)
+_tailtip-self-insert (_tailtip-self-insert)
+autosuggest-toggle (autosuggest-toggle)
+tailtip-toggle (tailtip-toggle)
+tailtip-window (tailtip-window)
+----
+
+These are available but not enabled by default. You can enable them using the related
+_toggle_ widgets. You can see what key bindings are associated with these widgets by
+using the `/keymap` command.
+
+[source,shell]
+----
+groovy> /keymap
+...
+"^[s" tailtip-toggle
+"^[v" autosuggest-toggle
+...
+----
+
+Normally, completions are shown when you hit the 'TAB' key, but with the tailtip widget enabled,
+you can see completions as you type., as well as additional usage information given in the
+tailtip window as seen here for a command:
+
+image:assets/img/widget1.png[Tailtip]
+
+And here for some code:
+
+image:assets/img/widget3.png[Tailtip]
+
+With the autosuggest widget enabled, you can see suggestions for what to type next
+as you type, as seen here:
+
+image:assets/img/widget2.png[Tailtip]
+
+You can accept the entire suggestion or a word at a time. Both widgets can be enabled.
+
 [[GroovyShell-register]]
 === Custom commands
 
@@ -684,13 +742,6 @@ groovy:000>
 
 Note that the command class must be found on classpath: you cannot define a new command from within the shell.
 
-[[GroovyShell-Troubleshooting]]
-=== Troubleshooting
-
-Please https://issues.apache.org/jira/browse/GROOVY[report] any problems you
-run into. Please be sure to mark the JIRA issue with the `Groovysh`
-component.
-
 [[GroovyShell-PlatformProblems]]
 ==== Platform Problems