Command line

Ghostwriter arguments can be passed directly through either supported entry point:

mgw --help
python -m mgw --help

General Ghostwriter invocation

Use gw when the caller already has the argument sequence expected by Ghostwriter:

from mgw import gw

result = gw(["--help"])
print(result)

If args is omitted, gw forwards the current process arguments after the executable name. It returns the result from the Java Ghostwriter command as a string.

Guidance processing

Use gdp to scan a project for guidance tags. The path may be a relative path, glob, or regular-expression matcher understood by the Java processor:

from mgw import gdp

report = gdp(path="src", project_dir=".", threads=2)
for item in report:
    print(item)

Act execution

Use adw to execute a named Act or Act expression against a project:

from mgw import adw

results = adw("my-act", path="src", project_dir=".")
for result in results:
    print(result)

Additional libraries may be local paths or Maven coordinates and are resolved before the JVM starts:

report = gdp(
    path="src",
    libs=["com.example:example-library:1.0.0", "lib/custom-tools.jar"],
)

gw

def gw(args: list[str] | None = None) -> str:

Runs Ghostwriter through the Java command-line processor. args is an optional list of command-line arguments; when it is None, the function uses the current process arguments. The function starts the JVM lazily, invokes Ghostwriter, and returns its result as a string. JAVA_HOME must be set before the first invocation.

gdp

def gdp(
    model: str | None = None,
    project_dir: str | None = None,
    path: str = ".",
    config_file: str = "gw.properties",
    instructions: str | None = None,
    threads: int | None = None,
    excludes: list[str] | None = None,
    non_recursive: bool = False,
    module_thread_timeout_minutes: int | None = None,
    libs: list[str] | None = None,
) -> list[str]:

Processes guidance tags in the selected project and returns the Java processor report as a Python list. model selects the provider or model, project_dir identifies the project (defaulting to the current directory), path selects what to scan, and config_file supplies the configurator properties file. instructions overrides processor instructions. threads controls processing concurrency, excludes supplies path patterns, non_recursive limits traversal to the selected level, and module_thread_timeout_minutes sets the module timeout. libs accepts a list of local library paths or Maven coordinates. Thread and timeout values must be positive integers; libs and excludes must not be strings.

adw

def adw(
    act: str,
    model: str | None = None,
    project_dir: str | None = None,
    path: str = ".",
    config_file: str = "gw.properties",
    acts_location: str | None = None,
    interactive: bool = False,
    disable_normal_order: bool = False,
    libs: list[str] | None = None,
) -> list[str]:

Executes the non-empty act name or expression and returns the processor results as a Python list. model, project_dir, path, config_file, and libs have the same roles as in gdp. acts_location selects where Acts are loaded from, interactive enables interactive processing, and disable_normal_order disables the normal Act order. The function validates the Act name and the JVM prerequisites before scanning the project.