Documentation and Inspection

/**
 * Object introspection utility class
 */
class ObjectInspector {
    /**
     * Object constructor
     * @param object Object to examine
     */
    ObjectInspector(Object object)
    
    /**
     * Get object methods information with detailed metadata
     * @return List of method information maps
     */
    List<Map<String, String>> methods()
    
    /**
     * Get meta-methods for object with optional operator inclusion
     * @param includeOperatorMethods Whether to include operator methods
     * @return List of meta-method information maps
     */
    List<Map<String, String>> metaMethods(boolean includeOperatorMethods)
    
    /**
     * Get meta-methods for object (includes operator methods by default)
     * @return List of meta-method information maps
     */
    List<Map<String, String>> metaMethods()
    
    /**
     * Get object properties information
     * @return Map containing propertyInfo, publicFields, and classProps
     */
    Map<String, Object> properties()
}

// Constants for inspection field names
class ObjectInspector {
    static final String FIELD_NAME = "name"
    static final String FIELD_PARAMETERS = "parameters"
    static final String FIELD_MODIFIERS = "modifiers"
    static final String FIELD_RETURN = "return"
    static final List<String> METHOD_COLUMNS = ["language", "modifiers", "this", "return", "name", "parameters", "exception", "8"]
    static final List<String> GLOBAL_META_METHODS = ["print", "println", "printf", "sprintf", "sleep"]
}

/**
 * Utility functions for data conversion and persistence
 */
class Utils {
    /**
     * Convert object to string representation
     * @param object Object to convert
     * @return String representation
     */
    static String toString(Object object)
    
    /**
     * Convert JSON string to object
     * @param json JSON string to parse
     * @return Parsed object
     */
    static Object toObject(String json)
    
    /**
     * Convert object to map representation
     * @param object Object to convert
     * @return Map representation
     */
    static Map<String, Object> toMap(Object object)
    
    /**
     * Convert object to JSON string
     * @param object Object to serialize
     * @return JSON string representation
     */
    static String toJson(Object object)
    
    /**
     * Persist object to file with specified format
     * @param file Target file path
     * @param object Object to persist
     * @param format Serialization format (JSON, GROOVY, NONE)
     */
    static void persist(Path file, Object object, Format format)
}

import org.apache.groovy.groovysh.jline.ObjectInspector
import org.apache.groovy.groovysh.jline.Utils

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

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

// Get properties
Map<String, Object> properties = inspector.properties()
properties.each { category, propList ->
    println "Category: $category"
    if (propList instanceof List) {
        propList.each { prop ->
            println "  Property: ${prop}"
        }
    }
}

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

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

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

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

/**
 * Documentation utility extending HashMap for URL resolution
 */
class DocFinder extends HashMap<String, Object> {
    /**
     * Find documentation URL for class or object
     * @param target Class name or object to find documentation for
     * @return Documentation URL or null if not found
     */
    String findDocumentation(Object target)
    
    /**
     * Open documentation in default browser
     * @param target Class name or object to open documentation for
     * @return true if documentation was opened, false otherwise
     */
    boolean openDocumentation(Object target)
    
    /**
     * Get available documentation sources
     * @return Map of documentation source names to base URLs
     */
    Map<String, String> getDocumentationSources()
    
    /**
     * Add custom documentation source
     * @param name Source name
     * @param baseUrl Base URL for the documentation
     * @param urlPattern Pattern for constructing URLs
     */
    void addDocumentationSource(String name, String baseUrl, String urlPattern)
}

import org.apache.groovy.groovysh.util.DocFinder

DocFinder docFinder = new DocFinder()

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

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

// Open documentation in browser
boolean opened = docFinder.openDocumentation(String.class)
if (opened) {
    println "Documentation opened in browser"
}

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

// Add custom documentation source
docFinder.addDocumentationSource(
    "MyLibrary",
    "https://docs.mylibrary.com/",
    "{baseUrl}api/{packagePath}/{className}.html"
)

/**
 * Class lookup and validation utilities
 */
class ClassUtils {
    /**
     * Check if class exists on classpath
     * @param className Fully qualified class name
     * @return true if class exists, false otherwise
     */
    static boolean lookFor(String className)
    
    /**
     * Check if class exists via specific engine
     * @param engine GroovyEngine instance
     * @param className Fully qualified class name
     * @return true if class exists, false otherwise
     */
    static boolean lookFor(GroovyEngine engine, String className)
    
    /**
     * Load class safely with error handling
     * @param className Fully qualified class name
     * @return Class instance or null if not found
     */
    static Class<?> safeLoadClass(String className)
    
    /**
     * Get class loader information
     * @param clazz Class to examine
     * @return Map containing class loader details
     */
    static Map<String, Object> getClassLoaderInfo(Class<?> clazz)
}

import org.apache.groovy.groovysh.util.ClassUtils

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

println "String class exists: $stringExists"
println "Custom class exists: $customExists"

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

// Get class loader information
Map<String, Object> loaderInfo = ClassUtils.getClassLoaderInfo(String.class)
loaderInfo.each { key, value ->
    println "$key: $value"
}

# Inspect object with various options
/inspect [options] object
# Options:
#   -i, --info         Show basic object information
#   -m, --methods      Show object methods
#   -p, --properties   Show object properties  
#   -n, --metaMethods  Show meta-methods
#   -h, --hierarchy    Show class hierarchy
#   -g, --gui          Open in GUI object browser

# Open documentation in browser
/doc object

# Browse object in GUI (if groovy-console available)
/console

groovy> def person = [name: "Alice", age: 25]
groovy> /inspect person
Object: [name:Alice, age:25]
Class: java.util.LinkedHashMap
Size: 2

groovy> /inspect -m person
Methods for java.util.LinkedHashMap:
  clear() -> void
  containsKey(Object) -> boolean
  containsValue(Object) -> boolean
  get(Object) -> Object
  put(Object, Object) -> Object
  remove(Object) -> Object
  size() -> int
  ...

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

groovy> /inspect -h person
Class Hierarchy for java.util.LinkedHashMap:
  java.util.LinkedHashMap
  java.util.HashMap
  java.util.AbstractMap
  java.lang.Object

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

groovy> /inspect -g person
Opening object browser for: [name:Alice, age:25]

// Java standard library
"java.lang.String" -> "https://docs.oracle.com/javase/8/docs/api/java/lang/String.html"

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

// Apache Commons
"org.apache.commons.lang3.StringUtils" -> "https://commons.apache.org/proper/commons-lang/apidocs/org/apache/commons/lang3/StringUtils.html"

/**
 * Browser integration utilities
 */
class BrowserIntegration {
    /**
     * Open URL in default browser
     * @param url URL to open
     * @return true if browser was launched successfully
     */
    static boolean openInBrowser(String url)
    
    /**
     * Check if desktop browsing is supported
     * @return true if desktop integration is available
     */
    static boolean isBrowsingSupported()
    
    /**
     * Get default browser command for current platform
     * @return Browser command string
     */
    static String getDefaultBrowserCommand()
}

/**
 * GUI object browser integration
 */
class ObjectBrowserIntegration {
    /**
     * Open object in GUI browser
     * @param object Object to browse
     * @return true if browser was opened successfully
     */
    static boolean browseObject(Object object)
    
    /**
     * Check if GUI browser is available
     * @return true if groovy-console is on classpath
     */
    static boolean isGuiBrowserAvailable()
    
    /**
     * Launch Groovy Console application
     * @return true if console was launched successfully
     */
    static boolean launchConsole()
}