0
# Documentation and Inspection
1

2
Tools for exploring objects, browsing documentation, and understanding code structure during interactive development sessions. These utilities provide comprehensive introspection capabilities and automatic documentation access.
3

4
## Capabilities
5

6
### Object Inspection
7

8
Comprehensive object introspection utilities for examining properties, methods, and metadata of any Java or Groovy object.
9

10
```groovy { .api }
11
/**
12
 * Object introspection utility class
13
 */
14
class ObjectInspector {
15
    /**
16
     * Object constructor
17
     * @param object Object to examine
18
     */
19
    ObjectInspector(Object object)
20
    
21
    /**
22
     * Get object methods information with detailed metadata
23
     * @return List of method information maps
24
     */
25
    List<Map<String, String>> methods()
26
    
27
    /**
28
     * Get meta-methods for object with optional operator inclusion
29
     * @param includeOperatorMethods Whether to include operator methods
30
     * @return List of meta-method information maps
31
     */
32
    List<Map<String, String>> metaMethods(boolean includeOperatorMethods)
33
    
34
    /**
35
     * Get meta-methods for object (includes operator methods by default)
36
     * @return List of meta-method information maps
37
     */
38
    List<Map<String, String>> metaMethods()
39
    
40
    /**
41
     * Get object properties information
42
     * @return Map containing propertyInfo, publicFields, and classProps
43
     */
44
    Map<String, Object> properties()
45
}
46

47
// Constants for inspection field names
48
class ObjectInspector {
49
    static final String FIELD_NAME = "name"
50
    static final String FIELD_PARAMETERS = "parameters"
51
    static final String FIELD_MODIFIERS = "modifiers"
52
    static final String FIELD_RETURN = "return"
53
    static final List<String> METHOD_COLUMNS = ["language", "modifiers", "this", "return", "name", "parameters", "exception", "8"]
54
    static final List<String> GLOBAL_META_METHODS = ["print", "println", "printf", "sprintf", "sleep"]
55
}
56
```
57

58
### Utility Functions
59

60
Data conversion and persistence utilities for the shell environment.
61

62
```groovy { .api }
63
/**
64
 * Utility functions for data conversion and persistence
65
 */
66
class Utils {
67
    /**
68
     * Convert object to string representation
69
     * @param object Object to convert
70
     * @return String representation
71
     */
72
    static String toString(Object object)
73
    
74
    /**
75
     * Convert JSON string to object
76
     * @param json JSON string to parse
77
     * @return Parsed object
78
     */
79
    static Object toObject(String json)
80
    
81
    /**
82
     * Convert object to map representation
83
     * @param object Object to convert
84
     * @return Map representation
85
     */
86
    static Map<String, Object> toMap(Object object)
87
    
88
    /**
89
     * Convert object to JSON string
90
     * @param object Object to serialize
91
     * @return JSON string representation
92
     */
93
    static String toJson(Object object)
94
    
95
    /**
96
     * Persist object to file with specified format
97
     * @param file Target file path
98
     * @param object Object to persist
99
     * @param format Serialization format (JSON, GROOVY, NONE)
100
     */
101
    static void persist(Path file, Object object, Format format)
102
}
103
```
104

105
**Usage Examples:**
106

107
```groovy
108
import org.apache.groovy.groovysh.jline.ObjectInspector
109
import org.apache.groovy.groovysh.jline.Utils
110

111
// Inspect a list object
112
def myList = [1, 2, 3, "hello"]
113
ObjectInspector inspector = new ObjectInspector(myList)
114

115
// Get methods
116
List<Map<String, String>> methods = inspector.methods()
117
methods.each { method ->
118
    println "Method: ${method[ObjectInspector.FIELD_NAME]}(${method[ObjectInspector.FIELD_PARAMETERS]})"
119
    println "Return Type: ${method[ObjectInspector.FIELD_RETURN]}"
120
    println "Modifiers: ${method[ObjectInspector.FIELD_MODIFIERS]}"
121
}
122

123
// Get properties
124
Map<String, Object> properties = inspector.properties()
125
properties.each { category, propList ->
126
    println "Category: $category"
127
    if (propList instanceof List) {
128
        propList.each { prop ->
129
            println "  Property: ${prop}"
130
        }
131
    }
132
}
133

134
// Get meta-methods (exclude operator methods)
135
List<Map<String, String>> metaMethods = inspector.metaMethods(false)
136
metaMethods.each { method ->
137
    println "Meta-method: ${method[ObjectInspector.FIELD_NAME]}"
138
}
139

140
// Use utility functions
141
String jsonData = Utils.toJson(myList)
142
println "JSON: $jsonData"
143

144
Map<String, Object> mapData = Utils.toMap(myList)
145
println "Map: $mapData"
146

147
Object parsedData = Utils.toObject('{"name":"test","value":42}')
148
println "Parsed: $parsedData"
149
```
150

151
### Documentation Finder
152

153
Automatic documentation URL resolution for Groovy and Java classes with integration to online documentation systems.
154

155
```groovy { .api }
156
/**
157
 * Documentation utility extending HashMap for URL resolution
158
 */
159
class DocFinder extends HashMap<String, Object> {
160
    /**
161
     * Find documentation URL for class or object
162
     * @param target Class name or object to find documentation for
163
     * @return Documentation URL or null if not found
164
     */
165
    String findDocumentation(Object target)
166
    
167
    /**
168
     * Open documentation in default browser
169
     * @param target Class name or object to open documentation for
170
     * @return true if documentation was opened, false otherwise
171
     */
172
    boolean openDocumentation(Object target)
173
    
174
    /**
175
     * Get available documentation sources
176
     * @return Map of documentation source names to base URLs
177
     */
178
    Map<String, String> getDocumentationSources()
179
    
180
    /**
181
     * Add custom documentation source
182
     * @param name Source name
183
     * @param baseUrl Base URL for the documentation
184
     * @param urlPattern Pattern for constructing URLs
185
     */
186
    void addDocumentationSource(String name, String baseUrl, String urlPattern)
187
}
188
```
189

190
**Usage Examples:**
191

192
```groovy
193
import org.apache.groovy.groovysh.util.DocFinder
194

195
DocFinder docFinder = new DocFinder()
196

197
// Find documentation for standard Java classes
198
String stringDocs = docFinder.findDocumentation("java.lang.String")
199
println "String docs: $stringDocs"
200
// Output: https://docs.oracle.com/javase/8/docs/api/java/lang/String.html
201

202
// Find documentation for Groovy classes
203
String listDocs = docFinder.findDocumentation("java.util.ArrayList")
204
println "ArrayList docs: $listDocs"
205

206
// Open documentation in browser
207
boolean opened = docFinder.openDocumentation(String.class)
208
if (opened) {
209
    println "Documentation opened in browser"
210
}
211

212
// Check available sources
213
Map<String, String> sources = docFinder.getDocumentationSources()
214
sources.each { name, url ->
215
    println "Source: $name -> $url"
216
}
217

218
// Add custom documentation source
219
docFinder.addDocumentationSource(
220
    "MyLibrary",
221
    "https://docs.mylibrary.com/",
222
    "{baseUrl}api/{packagePath}/{className}.html"
223
)
224
```
225

226
### Class Utilities
227

228
Utilities for class lookup, validation, and management within the shell environment.
229

230
```groovy { .api }
231
/**
232
 * Class lookup and validation utilities
233
 */
234
class ClassUtils {
235
    /**
236
     * Check if class exists on classpath
237
     * @param className Fully qualified class name
238
     * @return true if class exists, false otherwise
239
     */
240
    static boolean lookFor(String className)
241
    
242
    /**
243
     * Check if class exists via specific engine
244
     * @param engine GroovyEngine instance
245
     * @param className Fully qualified class name
246
     * @return true if class exists, false otherwise
247
     */
248
    static boolean lookFor(GroovyEngine engine, String className)
249
    
250
    /**
251
     * Load class safely with error handling
252
     * @param className Fully qualified class name
253
     * @return Class instance or null if not found
254
     */
255
    static Class<?> safeLoadClass(String className)
256
    
257
    /**
258
     * Get class loader information
259
     * @param clazz Class to examine
260
     * @return Map containing class loader details
261
     */
262
    static Map<String, Object> getClassLoaderInfo(Class<?> clazz)
263
}
264
```
265

266
**Usage Examples:**
267

268
```groovy
269
import org.apache.groovy.groovysh.util.ClassUtils
270

271
// Check if classes exist
272
boolean stringExists = ClassUtils.lookFor("java.lang.String")
273
boolean customExists = ClassUtils.lookFor("com.example.MyClass")
274

275
println "String class exists: $stringExists"
276
println "Custom class exists: $customExists"
277

278
// Safe class loading
279
Class<?> dateClass = ClassUtils.safeLoadClass("java.util.Date")
280
if (dateClass) {
281
    println "Loaded class: ${dateClass.name}"
282
}
283

284
// Get class loader information
285
Map<String, Object> loaderInfo = ClassUtils.getClassLoaderInfo(String.class)
286
loaderInfo.each { key, value ->
287
    println "$key: $value"
288
}
289
```
290

291
### Interactive Inspection Commands
292

293
Command-line interface for object inspection and documentation access.
294

295
```bash { .api }
296
# Inspect object with various options
297
/inspect [options] object
298
# Options:
299
#   -i, --info         Show basic object information
300
#   -m, --methods      Show object methods
301
#   -p, --properties   Show object properties  
302
#   -n, --metaMethods  Show meta-methods
303
#   -h, --hierarchy    Show class hierarchy
304
#   -g, --gui          Open in GUI object browser
305

306
# Open documentation in browser
307
/doc object
308

309
# Browse object in GUI (if groovy-console available)
310
/console
311
```
312

313
**Usage Examples:**
314

315
```bash
316
groovy> def person = [name: "Alice", age: 25]
317
groovy> /inspect person
318
Object: [name:Alice, age:25]
319
Class: java.util.LinkedHashMap
320
Size: 2
321

322
groovy> /inspect -m person
323
Methods for java.util.LinkedHashMap:
324
  clear() -> void
325
  containsKey(Object) -> boolean
326
  containsValue(Object) -> boolean
327
  get(Object) -> Object
328
  put(Object, Object) -> Object
329
  remove(Object) -> Object
330
  size() -> int
331
  ...
332

333
groovy> /inspect -p person
334
Properties for java.util.LinkedHashMap:
335
  name = Alice (java.lang.String)
336
  age = 25 (java.lang.Integer)
337

338
groovy> /inspect -h person
339
Class Hierarchy for java.util.LinkedHashMap:
340
  java.util.LinkedHashMap
341
  java.util.HashMap
342
  java.util.AbstractMap
343
  java.lang.Object
344

345
groovy> /doc String
346
Opening documentation for java.lang.String...
347
URL: https://docs.oracle.com/javase/8/docs/api/java/lang/String.html
348

349
groovy> /inspect -g person
350
Opening object browser for: [name:Alice, age:25]
351
```
352

353
### Documentation Integration
354

355
Automatic integration with online documentation systems and local documentation sources.
356

357
**Supported Documentation Sources:**
358

359
- **Oracle Java Documentation**: docs.oracle.com
360
- **Groovy Documentation**: docs.groovy-lang.org  
361
- **Apache Documentation**: Various Apache project docs
362
- **Custom Sources**: Configurable documentation sources
363

364
**URL Pattern Examples:**
365

366
```groovy
367
// Java standard library
368
"java.lang.String" -> "https://docs.oracle.com/javase/8/docs/api/java/lang/String.html"
369

370
// Groovy classes
371
"groovy.lang.Closure" -> "https://docs.groovy-lang.org/latest/html/gapi/groovy/lang/Closure.html"
372

373
// Apache Commons
374
"org.apache.commons.lang3.StringUtils" -> "https://commons.apache.org/proper/commons-lang/apidocs/org/apache/commons/lang3/StringUtils.html"
375
```
376

377
### Browser Integration
378

379
Automatic browser launching for documentation viewing with fallback mechanisms.
380

381
```groovy { .api }
382
/**
383
 * Browser integration utilities
384
 */
385
class BrowserIntegration {
386
    /**
387
     * Open URL in default browser
388
     * @param url URL to open
389
     * @return true if browser was launched successfully
390
     */
391
    static boolean openInBrowser(String url)
392
    
393
    /**
394
     * Check if desktop browsing is supported
395
     * @return true if desktop integration is available
396
     */
397
    static boolean isBrowsingSupported()
398
    
399
    /**
400
     * Get default browser command for current platform
401
     * @return Browser command string
402
     */
403
    static String getDefaultBrowserCommand()
404
}
405
```
406

407
**Platform Support:**
408

409
- **Windows**: Uses `cmd /c start`
410
- **macOS**: Uses `open` command
411
- **Linux**: Uses `xdg-open` or `sensible-browser`
412
- **Fallback**: Prints URL to console if GUI not available
413

414
### GUI Object Browser
415

416
Integration with Groovy Console's object browser for visual inspection (when groovy-console is available).
417

418
```groovy { .api }
419
/**
420
 * GUI object browser integration
421
 */
422
class ObjectBrowserIntegration {
423
    /**
424
     * Open object in GUI browser
425
     * @param object Object to browse
426
     * @return true if browser was opened successfully
427
     */
428
    static boolean browseObject(Object object)
429
    
430
    /**
431
     * Check if GUI browser is available
432
     * @return true if groovy-console is on classpath
433
     */
434
    static boolean isGuiBrowserAvailable()
435
    
436
    /**
437
     * Launch Groovy Console application
438
     * @return true if console was launched successfully
439
     */
440
    static boolean launchConsole()
441
}
442
```
443

444
**Features:**
445

446
- **Visual Tree**: Hierarchical object structure display
447
- **Property Editing**: Modify object properties interactively
448
- **Method Invocation**: Call methods directly from browser
449
- **Export Options**: Save object state to various formats
450
- **Search and Filter**: Find specific properties or methods