Skip to content

Commit c034fac

Browse files
paulk-asertpaulk-asert
committed
GROOVY-8162: Update Groovysh to JLine3 (document interpreter mode)
1 parent f089245 commit c034fac

File tree

1 file changed

+93
-3
lines changed

1 file changed

+93
-3
lines changed

‎subprojects/groovy-groovysh/src/spec/doc/groovysh.adoc

Lines changed: 93 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,96 @@ experiments.
7171
-V, --version Display the version
7272
-----------------------------------------------------------------
7373
74+
[[GroovyShell-Model]]
75+
=== Repl model
76+
77+
The Groovy Shell is a Read-Eval-Print Loop (REPL) which allows you to
78+
interactively evaluate Groovy expressions and statements,
79+
define classes and other types, invoke commands, and run simple experiments.
80+
81+
When you input a line, the shell will try to determine if the input you
82+
have given is a complete valid expression, statement, or definition.
83+
If not complete, it will prompt you for more input.
84+
If it is complete, it will execute the input, and print the result,
85+
if any, to the console. Each input you enter is executed in isolation.
86+
87+
There are some exceptions to this conceptual model. Any import statements
88+
entered will be remembered and used for all subsequent evaluations.
89+
Similarly, with some caveats we'll discuss next, any previously defined classes, methods, and potentially variables will be available.
90+
91+
The shell has the concept of shared variables. Given that subsequent statements
92+
are run in isolation, you should store any results needed for later use in shared variables.
93+
94+
Many Groovy tutorials and examples use the `def` keyword or a type to define variables.
95+
Script examples might distinguish between local variables with a type and script
96+
binding variables where no type, nor the `def` or `var` type placeholders,
97+
are given. The script binding is the exact equivalent to the shell's shared variables.
98+
99+
Because such statements are so common, the shell has a special mode
100+
called _interpreter mode_ which allows you to use typed variables.
101+
The following table summarizes the differences between the two modes:
102+
103+
[options="header"]
104+
|===
105+
| interpreterMode | off | on
106+
| imports 2+| remembered
107+
| types 2+| available
108+
| methods | converted to closure shared variables | remembered
109+
| shared variables 2+| available
110+
| local variables | forgotten | remembered
111+
|===
112+
113+
Conceptually, for things that are _remembered_ in the above table,
114+
it is as if you included the related code at the start of each of your inputs.
115+
116+
[NOTE]
117+
--
118+
You should treat local variables as if you were using immutable data structures.
119+
An input which mutates a local variable will likely be undone by subsequent statements.
120+
So, you should pick one of the first two styles below.
121+
122+
In either mode you can use shared variables:
123+
[source,jshell]
124+
----
125+
groovy> fruit = []
126+
groovy> fruit << 'peach'
127+
[peach]
128+
groovy> fruit << 'pear'
129+
[peach, pear]
130+
groovy> assert fruit == ['peach', 'pear']
131+
----
132+
133+
Use the `/show` command to see the shared variables.
134+
135+
Only in interpreter mode:
136+
[source,jshell]
137+
----
138+
groovy> def noFruit = []
139+
[]
140+
groovy> def oneFruit = noFruit << 'peach'
141+
[peach]
142+
groovy> def twoFruit = oneFruit << 'pear'
143+
[peach, pear]
144+
groovy> assert twoFruit == ['peach', 'pear']
145+
----
146+
147+
By the time you get to the last statement, the previous three local variable
148+
definitions are remembered, so the assertion will pass.
149+
150+
Avoid this (relevant to interpreter mode):
151+
[source,jshell]
152+
----
153+
groovy> def fruit = []
154+
[]
155+
groovy> fruit << 'peach'
156+
[peach]
157+
groovy> fruit << 'pear'
158+
[pear]
159+
groovy> assert fruit == []
160+
----
161+
The `def fruit = []` will be _remembered_ before executing each of the next three statements.
162+
--
163+
74164
[[GroovyShell-EvaluatingExpressions]]
75165
=== Evaluating Expressions
76166
@@ -178,9 +268,9 @@ the same namespace.
178268
The shell has a number of different commands, which provide rich access
179269
to the shell’s environment.
180270
181-
Commands all have a _name_ and a _shortcut_ (which is something like
182-
`/h`). Commands may also have some predefined system _aliases_. Users
183-
may also create their own aliases. This section will list commands in
271+
Commands all have a _name_, e.g. `/help` and `/prnt`.
272+
Commands may also have some predefined system _aliases_, e.g. `/h`.
273+
Users may also create their own aliases. This section will list commands in
184274
alphabetical order, but you can also use the `/help` command to list
185275
the available commands:
186276

0 commit comments

Comments
 (0)