Merge pull request #628 from warquys/Documentation

Add Code Matcher exemple to the documentation
pardeike · Oct 27, 2024 · 7876a22 · 7876a22
2 parents efb41b4 + 5ab4c61
commit 7876a22
Show file tree

Hide file tree

Showing 3 changed files with 211 additions and 0 deletions.
diff --git a/Harmony/Documentation/articles/patching-transpiler-matcher.md b/Harmony/Documentation/articles/patching-transpiler-matcher.md
@@ -0,0 +1,29 @@
+# Patching
+
+## CodeMatcher
+
+One of the most useful tool for transpiler is the [CodeMatcher](../api/HarmonyLib.CodeMatcher.yml).
+
+`CodeMatcher` is like a cursor that can move through the IL code. Using matching methods, you can find specific set of instructions and then insert, remove or replace instructions. To find matching IL you need to use [CodeMatch](../api/HarmonyLib.CodeMatch.yml) and [Code](../api/HarmonyLib.Code.yml)
+
+### Use case
+
+Here is an example of use, we are in the context of an API providing events to mods. In the game, there is a base class `DamageHandler` which manages damage and death animation. A virtual method `DamageHandler.Apply()` provides basic damage handling. This method calls another method `DamageHandler.Kill()` which is called when the character dies. We want to replace the `Kill()` call with an API method which will invoke an `OnDeath` event. It is not possible to directly patch `Kill()` because this method is used in other API methods and we do not want to trigger the event.
+
+In our case, let's find the call to `Kill()` and replace it with our method `MyDeathHandler()`. `CodeMatcher.ThrowIfInvalid()` will throw an exception if the code does not match. There is also `ReportFailure` which returns a boolink. Using these methods can help maintain code between updates. Indicating where and which patches should have revisions.
+
+[!code-csharp[example](../examples/patching-transpiler-codematcher.cs?name=replacement)]
+
+Using `ThrowIfInvalid` is for an example purposes. There is `ThrowIfNotMatchForward` which summarizes the successive calls of `MatchStartForward` and `ThrowIfInvalid`.
+
+[!code-csharp[example](../examples/patching-transpiler-codematcher.cs?name=replacement_alt)]
+
+Furthermore, in this context, it is very likely that not all patcher methods call `Kill()`. It is possible to check the match validation in the following way. When a Match is a failure, the `CodeMatcher` pointer finds it at the end of the list of instructions. With the `Start()` method this will return the cursor to the start.
+
+[!code-csharp[example](../examples/patching-transpiler-codematcher.cs?name=check_matcher)]
+
+The `Kill()` method might be called more than once. For this it is possible to use `CodeMatcher.Repeat()`, the method will pass the current matcher code to the action. If no Match is successful, it is possible to define an optional action which takes an error message as a parameter, it is called if no match takes place.
+
+[!code-csharp[example](../examples/patching-transpiler-codematcher.cs?name=repeat)]
+
+![note] `Repeat` will not use a `CodeMatcher.Search...()`, only `Match...()` methods can be repeated. If you consider using another method `Match...()` in the "matchAction", clone your `CodeMatcher` into the match action via `CodeMatcher.Clone()`. This is to not replace the old match used by `Repeat`.
diff --git a/Harmony/Documentation/articles/toc.md b/Harmony/Documentation/articles/toc.md
@@ -14,6 +14,8 @@
 
 ## [Transpiler - CodeInstruction](patching-transpiler-codes.md)
 
+## [Transpiler - CodeMatcher](patching-transpiler-matcher.md)
+
 ## [Finalizer](patching-finalizer.md)
 
 ## [Injections](patching-injections.md)

diff --git a/Harmony/Documentation/examples/patching-transpiler-codematcher.cs b/Harmony/Documentation/examples/patching-transpiler-codematcher.cs
@@ -0,0 +1,180 @@
+namespace patching_transpiler_codematcher
+{
+	using HarmonyLib;
+	using System.Collections.Generic;
+	using System.Reflection;
+
+	public class SimpleMatching
+	{
+		// <replacement>
+		[HarmonyPatch]
+		public static class DamageHandler_Apply_Patch
+		{
+			// See "Auxiliary methods"
+			static IEnumerable<MethodBase> TargetMethods()
+			{
+				var result = new List<MethodBase>();
+				// ... (targeting all DamageHandler.Apply derived)
+				return result;
+			}
+
+			static void MyDeathHandler(DamageHandler handler, Player player)
+			{
+				// ...
+			}
+
+			static IEnumerable<CodeInstruction> Transpiler(IEnumerable<CodeInstruction> instructions /*, ILGenerator generator*/)
+			{
+				// Without ILGenerator, the CodeMatcher will not be able to create labels
+				var codeMatcher = new CodeMatcher(instructions /*, ILGenerator generator*/);
+
+				codeMatcher.MatchStartForward(
+						CodeMatch.Calls(() => default(DamageHandler).Kill(default(Player)))
+					)
+					.ThrowIfInvalid("Could not find call to DamageHandler.Kill")
+					.RemoveInstruction()
+					.InsertAndAdvance(
+						CodeInstruction.Call(() => MyDeathHandler(default, default))
+					);
+
+				return codeMatcher.Instructions();
+			}
+		}
+		// </replacement>
+
+		[HarmonyPatch]
+		public static class DamageHandler_Apply_Patch_Alternative
+		{
+			static IEnumerable<MethodBase> TargetMethods() => new List<MethodBase>();
+
+			static void MyDeathHandler(DamageHandler handler, Player player) { }
+
+			static IEnumerable<CodeInstruction> Transpiler(IEnumerable<CodeInstruction> instructions /*, ILGenerator generator*/)
+			{
+				var codeMatcher = new CodeMatcher(instructions /*, ILGenerator generator*/);
+
+				//  <replacement_alt>
+				codeMatcher.ThrowIfNotMatchForward("Could not find call to DamageHandler.Kill",
+						CodeMatch.Calls(() => default(DamageHandler).Kill(default(Player)))
+					)
+					.RemoveInstruction()
+					.InsertAndAdvance(
+						CodeInstruction.Call(() => MyDeathHandler(default, default))
+					);
+				// </replacement_alt>
+				return codeMatcher.Instructions();
+			}
+		}
+
+		class Player { }
+
+		class DamageHandler
+		{
+			public void Apply(Player player) { }
+
+			public void Kill(Player player) { }
+		}
+
+	}
+
+	public class CheckMatcherMatching
+	{
+		// <check_matcher>
+		[HarmonyPatch]
+		public static class DamageHandler_Apply_Patch
+		{
+			static IEnumerable<MethodBase> TargetMethods()
+			{
+				var result = new List<MethodBase>();
+				// ... (targeting all DamageHandler.Apply derived)
+				return result;
+			}
+
+			static void MyDeathHandler(DamageHandler handler, Player player)
+			{
+				// ...
+			}
+
+			static IEnumerable<CodeInstruction> Transpiler(IEnumerable<CodeInstruction> instructions /*, ILGenerator generator*/)
+			{
+				var codeMatcher = new CodeMatcher(instructions /*, ILGenerator generator*/);
+				codeMatcher.MatchStartForward(
+						CodeMatch.Calls(() => default(DamageHandler).Kill(default))
+					);
+
+				if (codeMatcher.IsValid)
+				{
+					codeMatcher.RemoveInstruction()
+						.InsertAndAdvance(
+							CodeInstruction.Call(() => MyDeathHandler(default, default))
+						);
+				}
+
+				codeMatcher.Start();
+				// Other match...
+
+				return codeMatcher.Instructions();
+			}
+		}
+		// </check_matcher>
+
+		class Player { }
+
+		class DamageHandler
+		{
+			public void Apply(Player player) { }
+
+			public void Kill(Player player) { }
+		}
+
+	}
+
+	public class RepeatMatching
+	{
+		// <repeat>
+		[HarmonyPatch]
+		public static class DamageHandler_Apply_Patch
+		{
+			static IEnumerable<MethodBase> TargetMethods()
+			{
+				var result = new List<MethodBase>();
+				// ... (targeting all DamageHandler.Apply derived)
+				return result;
+			}
+
+			static void MyDeathHandler(DamageHandler handler, Player player)
+			{
+				// ...
+			}
+
+			static IEnumerable<CodeInstruction> Transpiler(IEnumerable<CodeInstruction> instructions /*, ILGenerator generator*/)
+			{
+				var codeMatcher = new CodeMatcher(instructions /*, ILGenerator generator*/);
+				codeMatcher.MatchStartForward(
+						CodeMatch.Calls(() => default(DamageHandler).Kill(default))
+					)
+					// Only take the last Matching condition.
+					.Repeat(matchAction: cm =>
+					{
+						cm.RemoveInstruction();
+						cm.InsertAndAdvance(
+							CodeInstruction.Call(() => MyDeathHandler(default, default))
+						);
+					});
+
+				return codeMatcher.Instructions();
+			}
+		}
+		// </repeat>
+
+		class Player { }
+
+		class DamageHandler
+		{
+			public void Apply(Player player) { }
+
+			public void Kill(Player player) { }
+		}
+
+	}
+}