[Mlir-commits] [mlir] [MLIR] Add documentation page for `mlir-query` tool (PR #146535)

[Jacques Pienaar]

================
@@ -0,0 +1,354 @@
+`mlir-query` is an interactive tool designed to simplify IR exploration. It provides a REPL interface and supports an interactive query language for MLIR, enabling developers to query the MLIR IR dynamically.  
+The tool uses matchers as its core mechanism for performing queries over the MLIR IR, relying on simple matchers from `Matchers.h` and slicing-related matchers from `SliceMatchers.h`.  
+
+Through its IR exploration capabilities and the interactive query language, `mlir-query` serves both as a prototyping environment for pattern matchers and as a good debugging tool.
+
+## Usage
+
+### Query modes
+In order to prototype pattern matchers, explore, test, or debug the MLIR IR, the tool provides two main usage modes:
+
+* **Run queries directly from the CLI:**
+    ```shell
+    ./mlir-query input.mlir -c "<your_query_1>" -c "<your_query_2>" ... "<your_query_N>"
+    ```
+    The commands are executed and the program exits immediately.
+
+* **Launch an interactive session:**
+    ```shell
+    ./mlir-query input.mlir
+    ```
+    Opens a REPL-like interface where you can type queries interactively.
+
+### Use with `mlir-opt`
+
+The tool can easily be used with the MLIR pass pipeline infrastructure by running a pass pipeline and passing the result as input to `mlir-query`.
+
+```shell
+./mlir-opt input.mlir -canonicalize | ./mlir-query -c "<your_query_1>" -c "<your_query_2>" ... "<your_query_N>"
+```
+*Command example*
+
+## Register a new matcher
+
+To register a new matcher with `mlir-query`, you need to define a new structure that implements one of the following signatures: `bool match(Operation* op)` or `bool match(Operation* op, SetVector<Operation*> &matchedOps)`. Next, link `MLIRQueryLib` and register the matcher.
+
+```cpp
+#include "mlir/Tools/mlir-query/MlirQueryMain.h"
+using namespace mlir;
+
+int main(int argc, char **argv) {
+
+  DialectRegistry dialectRegistry;
+  registerAllDialects(dialectRegistry);
+
+  query::matcher::Registry matcherRegistry;
+
+  // Replace <matcher_name> with your desired matcher identifier string.
+  matcherRegistry.registerMatcher("<matcher_name>", matcherInstance);
+
+  MLIRContext context(dialectRegistry);
+  return failed(mlirQueryMain(argc, argv, context, matcherRegistry));
+}
+```
+
+## Features
+### Autocompletion
+
+To simplify usage, `mlir-query` provides autocompletion in the REPL interface, enabling users to ease query input by pressing the Tab key.
+<div style="overflow-x:auto; margin:1em 0;">
+  <img
+    src="https://i.imgur.com/3QiJgrU.gif"
----------------
jpienaar wrote:

They do, if you could make the font bigger even better. And by bigger I mean, record on narrower/smaller terminal, so that the longer commands maybe span over multiple lines, but roughly same size (or bigger) than the text to make it easier to read.

https://github.com/llvm/llvm-project/pull/146535