From 2b29aa5c86021eb79c461975a0281b6d7635bb67 Mon Sep 17 00:00:00 2001
From: Clifford Wolf <clifford@clifford.at>
Date: Fri, 3 May 2019 08:35:45 +0200
Subject: [PATCH] Update pmgen documentation

Signed-off-by: Clifford Wolf <clifford@clifford.at>
---
 passes/pmgen/README.md | 24 ++++++++++++++++++------
 1 file changed, 18 insertions(+), 6 deletions(-)

diff --git a/passes/pmgen/README.md b/passes/pmgen/README.md
index 320e95a77..2f0b1fd5a 100644
--- a/passes/pmgen/README.md
+++ b/passes/pmgen/README.md
@@ -29,19 +29,25 @@ up in any future matches:
 
     pm.blacklist(some_cell);
 
-The `.run(callback_function)` method searches for all matches and calls the
-callback function for each found match:
+The `.run_<pattern_name>(callback_function)` method searches for all matches
+for the pattern`<pattern_name>` and calls the callback function for each found
+match:
 
-    pm.run([&](){
+    pm.run_foobar([&](){
         log("found matching 'foo' cell: %s\n", log_id(pm.st.foo));
         log("          with 'bar' cell: %s\n", log_id(pm.st.bar));
     });
 
 The `.pmg` file declares matcher state variables that are accessible via the
-`.st.<state_name>` members. (The `.st` member is of type `foobar_pm::state_t`.)
+`.st_<pattern_name>.<state_name>` members. (The `.st_<pattern_name>` member is
+of type `foobar_pm::state_<pattern_name>_t`.)
 
 Similarly the `.pmg` file declares user data variables that become members of
-`.ud`, a struct of type `foobar_pm::udata_t`.
+`.ud_<pattern_name>`, a struct of type `foobar_pm::udata_<pattern_name>_t`.
+
+There are four versions of the `run_<pattern_name>()` method: Without callback,
+callback without arguments, callback with reference to `pm`, and callback with
+reference to `pm.st_<pattern_name>`.
 
 
 The .pmg File Format
@@ -52,6 +58,12 @@ lines consist of whitespace-separated tokens.
 
 Lines in `.pmg` files starting with `//` are comments.
 
+Declaring a pattern
+-------------------
+
+A `.pmg` file contains one or more patterns. Each pattern starts with a line
+with the `pattern` keyword followed by the name of the pattern.
+
 Declaring state variables
 -------------------------
 
@@ -66,7 +78,7 @@ State variables are automatically managed by the generated backtracking algorith
 and saved and restored as needed.
 
 They are automatically initialized to the default constructed value of their type
-when `.run(callback_function)` is called.
+when `.run_<pattern_name>(callback_function)` is called.
 
 Declaring udata variables
 -------------------------
-- 
2.30.2