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

[Jacques Pienaar]

================
@@ -0,0 +1,355 @@
+`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 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>" ... -c "<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`. A command example is shown below:
+
+```shell
+./mlir-opt input.mlir -canonicalize | ./mlir-query - -c "<your_query_1>" -c "<your_query_2>" ... -c "<your_query_N>"
+```
+
+## Register custom matchers
+
+To register a custom matcher with `mlir-query`, define a structure that implements one of the following signatures: `bool match(Operation* op)` or `bool match(Operation* op, SetVector<Operation*> &matchedOps)` and then implement the desired matching logic. Next, link `MLIRQueryLib` and register the matcher.
+
+```cpp
+#include "mlir/Tools/mlir-query/MlirQueryMain.h"
+using namespace mlir;
----------------
jpienaar wrote:

Lets perhaps expand this and show an example custom matcher. Maybe something as simple as `isa<func::FuncOp>(op);` one.

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