Querying iris watch

iris watch keeps the whole project compiled in memory, dependencies included. iris watch query asks it questions by qualified name, so you do not need to open files or start a second compiler.

Find the watcher

Run queries from anywhere inside the project. If the watcher was started with --output DIR, pass the same option: append query … to the watcher's command line (iris watch --output DIR query wait), or run iris watch query --output DIR wait. A relative DIR is resolved from the current directory, so run the query from the directory the watcher was started in.

iris watch query wait

• Exit status 4 means no watcher is running for the project's output directory. Before starting one, check whether the project already starts it: look at package.json scripts (a dev script may run iris watch next to a dev server), .amp/services.yaml, and the project's agent guide. If a service runs it, start or restart that service instead. Otherwise run iris watch in the background and keep it running; queries right after it starts exit 4 until Spago has fetched dependencies, so retry for a few seconds.
• Never stop or restart a watcher you did not start. Only one watcher can run per output directory.
• A warning that the watcher runs a different Iris version means the project uses another iris build, which the warning names; use that executable for queries if answers look wrong.

After editing files

iris watch query wait
iris watch query diagnostics

wait rescans the sources, rebuilds if anything changed, and reports whether the build succeeded. Always run it after writing files and before other queries, so answers reflect your edits. It exits 0 even when the build has errors; read its output, then ask for diagnostics.

Queries

Command	Answer
iris watch query wait	Build outcome after picking up every change on disk
iris watch query signature Data.Maybe.fromMaybe	Signature of a value, or kind of a type or class, with its documentation
iris watch query module Data.Maybe	Every export of a module with signatures and documentation
iris watch query definition Data.Maybe.Maybe	path:line:column of the declaration
iris watch query references Data.Maybe.fromMaybe	path:line:column of every use
iris watch query dependents Data.Maybe	Every module that imports a module; an indirect one names the module it imports on the way
iris watch query instances class Data.Show.Show	path:line:column and head of every instance of a class
iris watch query instances type Data.Maybe.Maybe	path:line:column and head of every instance whose head mentions a type, whatever its class
iris watch query search foldl	Qualified names and signatures of declarations whose names match, best first
iris watch query diagnostics [Main]	Errors and warnings of every module, or of one module
iris watch query javascript Main	The JavaScript written to output/ for a module

• Use search when you do not know which module declares something; it matches whole names, then prefixes, then substrings, then letters in order (fromMay finds fromMaybe), ignoring case, and lists the best 50.
• Names are fully qualified: the module, a dot, then the item. Operators may be written with or without parentheses: Data.Function.(<<<).
• A name that is both a type and a value, such as a constructor named after its type, answers both. To ask about one, put value or type before the name: iris watch query definition type Data.Maybe.Maybe, iris watch query signature value Data.Tuple.Tuple. This works for signature, definition, and references; classes are in the type namespace, and data constructors and class members in the value namespace.
• Any module in the project or its dependencies can be queried, including ones that are not imported anywhere.
• Declarations of the built-in Prim modules point at copies the watcher writes to a temporary directory, which you can read like any other source.
• Paths inside the project, dependencies included, are relative to its root; lines and columns count from 1, and columns count characters.
• javascript fails while any module has errors, because nothing is written to output/ then.
• Each query invocation connects, receives its answer, and exits; there is no client session.
• --json prints the watcher's response as JSON: successful answers have kind and value; errors have kind and message.
• Exit status: 0 answered, 1 the query failed (the message says why, for example an unknown name), 2 invalid arguments, 4 no watcher.