Class CodeMatcher

A CodeInstruction matcher

Inheritance

System.Object

CodeMatcher

Namespace : HarmonyLib

Assembly : 0Harmony.dll

Syntax

public class CodeMatcher

Constructors

CodeMatcher()

Creates an empty code matcher

Declaration

public CodeMatcher()

CodeMatcher(IEnumerable<CodeInstruction>, ILGenerator)

Creates a code matcher from an enumeration of instructions

Declaration

public CodeMatcher(IEnumerable<CodeInstruction> instructions, ILGenerator generator = null)

Parameters

The instructions (transpiler argument)

| | System.Reflection.Emit.ILGenerator | generator |

An optional IL generator

|

Properties

Blocks

Gets the exception blocks at the current position

Declaration

public List<ExceptionBlock> Blocks { get; }

Property Value

The blocks

|

Instruction

Gets instructions at the current position

Declaration

public CodeInstruction Instruction { get; }

Property Value

The instruction

|

IsInvalid

Checks whether the position of this CodeMatcher is outside its bounds

Declaration

public bool IsInvalid { get; }

Property Value

True if this CodeMatcher is invalid

|

IsValid

Checks whether the position of this CodeMatcher is within bounds

Declaration

public bool IsValid { get; }

Property Value

True if this CodeMatcher is valid

|

Labels

Gets the labels at the current position

Declaration

public List<Label> Labels { get; }

Property Value

The labels

|

Length

Gets the number of code instructions in this matcher

Declaration

public int Length { get; }

Property Value

The count

|

Opcode

Gets the opcode at the current position

Declaration

public OpCode Opcode { get; }

Property Value

The opcode

|

Operand

Gets the operand at the current position

Declaration

public object Operand { get; }

Property Value

The operand

|

Pos

The current position

Declaration

public int Pos { get; }

Property Value

The index or -1 if out of bounds

|

Remaining

Gets the remaining code instructions

Declaration

public int Remaining { get; }

Property Value

The remaining count

|

Methods

AddLabels(IEnumerable<Label>)

Adds an enumeration of labels to current position

Declaration

public CodeMatcher AddLabels(IEnumerable<Label> labels)

Parameters

The labels

|

Returns

The same code matcher

|

AddLabelsAt(Int32, IEnumerable<Label>)

Adds an enumeration of labels at a position

Declaration

public CodeMatcher AddLabelsAt(int position, IEnumerable<Label> labels)

Parameters

The position

| | System.Collections.Generic.IEnumerable\ | labels |

The labels

|

Returns

The same code matcher

|

Advance(Int32)

Advances the current position

Declaration

public CodeMatcher Advance(int offset = 1)

Parameters

The offset

|

Returns

The same code matcher

|

Clone()

Makes a clone of this instruction matcher

Declaration

public CodeMatcher Clone()

Returns

A copy of this matcher

|

CreateLabel(out Label)

Creates a label at current position

Declaration

public CodeMatcher CreateLabel(out Label label)

Parameters

[out] The label

|

Returns

The same code matcher

|

CreateLabelAt(Int32, out Label)

Creates a label at a position

Declaration

public CodeMatcher CreateLabelAt(int position, out Label label)

Parameters

The position

| | System.Reflection.Emit.Label | label |

[out] The new label

|

Returns

The same code matcher

|

CreateLabelWithOffsets(Int32, out Label)

Creates a label at the given offset from the current position

Declaration

public CodeMatcher CreateLabelWithOffsets(int offset, out Label label)

Parameters

The offset

| | System.Reflection.Emit.Label | label |

[out] The new label

|

Returns

The same code matcher

|

DeclareLocal(Type, out LocalBuilder)

Declares a local variable but does not add it

Declaration

public CodeMatcher DeclareLocal(Type variableType, out LocalBuilder localVariable)

Parameters

The variable type

| | System.Reflection.Emit.LocalBuilder | localVariable |

[out] The new local variable

|

Returns

The same code matcher

|

DefineLabel(out Label)

Declares a new label but does not add it

Declaration

public CodeMatcher DefineLabel(out Label label)

Parameters

[out] The new label

|

Returns

The same code matcher

|

DistinctLabels(IEnumerable<CodeInstruction>)

Gets a list of all distinct labels

Declaration

public List<Label> DistinctLabels(IEnumerable<CodeInstruction> instructions)

Parameters

The instructions (transpiler argument)

|

Returns

A list of Labels

|

Do(Action<CodeMatcher>)

Runs some code when chaining CodeMatcher at the current position

Declaration

public CodeMatcher Do(Action<CodeMatcher> action)

Parameters

The System.Action<T> to run

|

Returns

The same code matcher

|

End()

Moves the current position to the end

Declaration

public CodeMatcher End()

Returns

The same code matcher

|

Insert(CodeInstruction[])

Inserts some instructions at the current position

Declaration

public CodeMatcher Insert(params CodeInstruction[] instructions)

Parameters

The instructions

|

Returns

The same code matcher

|

Insert(IEnumerable<CodeInstruction>)

Inserts an enumeration of instructions at the current position

Declaration

public CodeMatcher Insert(IEnumerable<CodeInstruction> instructions)

Parameters

The instructions

|

Returns

The same code matcher

|

InsertAfter(CodeInstruction[])

Inserts instructions immediately after the current position

Declaration

public CodeMatcher InsertAfter(params CodeInstruction[] instructions)

Parameters

The instructions

|

Returns

The same code matcher

|

InsertAfter(IEnumerable<CodeInstruction>)

Inserts an enumeration of instructions immediately after the current position

Declaration

public CodeMatcher InsertAfter(IEnumerable<CodeInstruction> instructions)

Parameters

The instructions

|

Returns

The same code matcher

|

InsertAfterAndAdvance(CodeInstruction[])

Inserts instructions immediately after the current position and advances to the last inserted instruction

Declaration

public CodeMatcher InsertAfterAndAdvance(params CodeInstruction[] instructions)

Parameters

The instructions

|

Returns

The same code matcher

|

InsertAfterAndAdvance(IEnumerable<CodeInstruction>)

Inserts an enumeration of instructions immediately after the current position and advances to the last inserted instruction

Declaration

public CodeMatcher InsertAfterAndAdvance(IEnumerable<CodeInstruction> instructions)

Parameters

The instructions

|

Returns

The same code matcher

|

InsertAndAdvance(CodeInstruction[])

Inserts some instructions at the current position and advances it

Declaration

public CodeMatcher InsertAndAdvance(params CodeInstruction[] instructions)

Parameters

The instructions

|

Returns

The same code matcher

|

InsertAndAdvance(IEnumerable<CodeInstruction>)

Inserts an enumeration of instructions at the current position and advances it

Declaration

public CodeMatcher InsertAndAdvance(IEnumerable<CodeInstruction> instructions)

Parameters

The instructions

|

Returns

The same code matcher

|

InsertBranch(OpCode, Int32)

Inserts a branch at the current position

Declaration

public CodeMatcher InsertBranch(OpCode opcode, int destination)

Parameters

The branch opcode

| | System.Int32 | destination |

Branch destination

|

Returns

The same code matcher

|

InsertBranchAfter(OpCode, Int32)

Inserts a branch instruction immediately after the current position

Declaration

public CodeMatcher InsertBranchAfter(OpCode opcode, int destination)

Parameters

The branch opcode

| | System.Int32 | destination |

Branch destination index

|

Returns

The same code matcher

|

InsertBranchAfterAndAdvance(OpCode, Int32)

Inserts a branch instruction immediately after the current position and advances the position

Declaration

public CodeMatcher InsertBranchAfterAndAdvance(OpCode opcode, int destination)

Parameters

The branch opcode

| | System.Int32 | destination |

Branch destination index

|

Returns

The same code matcher

|

InsertBranchAndAdvance(OpCode, Int32)

Inserts a branch at the current position and advances it

Declaration

public CodeMatcher InsertBranchAndAdvance(OpCode opcode, int destination)

Parameters

The branch opcode

| | System.Int32 | destination |

Branch destination

|

Returns

The same code matcher

|

InstructionAt(Int32)

Gets instructions at the current position with offset

Declaration

public CodeInstruction InstructionAt(int offset)

Parameters

The offset

|

Returns

The instruction

|

InstructionEnumeration()

Gets all instructions as an enumeration

Declaration

public IEnumerable<CodeInstruction> InstructionEnumeration()

Returns

A list of instructions

|

Instructions()

Gets all instructions

Declaration

public List<CodeInstruction> Instructions()

Returns

A list of instructions

|

Instructions(Int32)

Gets some instructions counting from current position

Declaration

public List<CodeInstruction> Instructions(int count)

Parameters

Number of instructions

|

Returns

A list of instructions

|

InstructionsInRange(Int32, Int32)

Gets all instructions within a range

Declaration

public List<CodeInstruction> InstructionsInRange(int start, int end)

Parameters

The start index

| | System.Int32 | end |

The end index

|

Returns

A list of instructions

|

InstructionsWithOffsets(Int32, Int32)

Gets all instructions within a range (relative to current position)

Declaration

public List<CodeInstruction> InstructionsWithOffsets(int startOffset, int endOffset)

Parameters

The start offset

| | System.Int32 | endOffset |

The end offset

|

Returns

A list of instructions

|

MatchEndBackwards(CodeMatch[])

Matches backwards and moves the position to ending of matching sequence

Declaration

public CodeMatcher MatchEndBackwards(params CodeMatch[] matches)

Parameters

Some code matches

|

Returns

The same code matcher

|

MatchEndForward(CodeMatch[])

Matches forward and advances position to ending of matching sequence

Declaration

public CodeMatcher MatchEndForward(params CodeMatch[] matches)

Parameters

Some code matches

|

Returns

The same code matcher

|

MatchStartBackwards(CodeMatch[])

Matches backwards and moves the position to beginning of matching sequence

Declaration

public CodeMatcher MatchStartBackwards(params CodeMatch[] matches)

Parameters

Some code matches

|

Returns

The same code matcher

|

MatchStartForward(CodeMatch[])

Matches forward and advances position to beginning of matching sequence

Declaration

public CodeMatcher MatchStartForward(params CodeMatch[] matches)

Parameters

Some code matches

|

Returns

The same code matcher

|

NamedMatch(String)

Gets a match by its name

Declaration

public CodeInstruction NamedMatch(string name)

Parameters

The match name

|

Returns

An instruction

|

OnError(CodeMatcher.ErrorHandler)

Registers an error handler that is invoked instead of throwing an exception

Declaration

public CodeMatcher OnError(CodeMatcher.ErrorHandler errorHandler)

Parameters

The CodeMatcher.ErrorHandler to register or null to remove the current handler

|

Returns

The same code matcher

|

PrepareMatchEndBackwards(CodeMatch[])

Prepares matching backwards and reversing position to ending of matching sequence

Declaration

public CodeMatcher PrepareMatchEndBackwards(params CodeMatch[] matches)

Parameters

Some code matches

|

Returns

The same code matcher

|

PrepareMatchEndForward(CodeMatch[])

Prepares matching forward and advancing position to ending of matching sequence

Declaration

public CodeMatcher PrepareMatchEndForward(params CodeMatch[] matches)

Parameters

Some code matches

|

Returns

The same code matcher

|

PrepareMatchStartBackwards(CodeMatch[])

Prepares matching backwards and reversing position to beginning of matching sequence

Declaration

public CodeMatcher PrepareMatchStartBackwards(params CodeMatch[] matches)

Parameters

Some code matches

|

Returns

The same code matcher

|

PrepareMatchStartForward(CodeMatch[])

Prepares matching forward and advancing position to beginning of matching sequence

Declaration

public CodeMatcher PrepareMatchStartForward(params CodeMatch[] matches)

Parameters

Some code matches

|

Returns

The same code matcher

|

RemoveInstruction()

Removes current instruction

Declaration

public CodeMatcher RemoveInstruction()

Returns

The same code matcher

|

RemoveInstructions(Int32)

Removes some instruction from current position by count

Declaration

public CodeMatcher RemoveInstructions(int count)

Parameters

Number of instructions

|

Returns

The same code matcher

|

RemoveInstructionsInRange(Int32, Int32)

Removes the instructions in a range

Declaration

public CodeMatcher RemoveInstructionsInRange(int start, int end)

Parameters

The start

| | System.Int32 | end |

The end

|

Returns

The same code matcher

|

RemoveInstructionsWithOffsets(Int32, Int32)

Removes the instructions in an offset range

Declaration

public CodeMatcher RemoveInstructionsWithOffsets(int startOffset, int endOffset)

Parameters

The start offset

| | System.Int32 | endOffset |

The end offset

|

Returns

The same code matcher

|

RemoveSearchBackward(Func<CodeInstruction, Boolean>)

Removes instructions from the current position backward until a predicate is matched. The matched instruction is not removed

Declaration

public CodeMatcher RemoveSearchBackward(Func<CodeInstruction, bool> predicate)

Parameters

A function to test each instruction for a match

|

Returns

The same code matcher

|

RemoveSearchForward(Func<CodeInstruction, Boolean>)

Removes instructions from the current position forward until a predicate is matched. The matched instruction is not removed

Declaration

public CodeMatcher RemoveSearchForward(Func<CodeInstruction, bool> predicate)

Parameters

A function to test each instruction for a match

|

Returns

The same code matcher

|

RemoveUntilBackward(CodeMatch[])

Removes instructions backwards from the current position to the previous match (exclusive)

Declaration

public CodeMatcher RemoveUntilBackward(params CodeMatch[] matches)

Parameters

Some code matches

|

Returns

The same code matcher

|

RemoveUntilForward(CodeMatch[])

Removes instructions from the current position up to the next match (exclusive)

Declaration

public CodeMatcher RemoveUntilForward(params CodeMatch[] matches)

Parameters

Some code matches

|

Returns

The same code matcher

|

Repeat(Action<CodeMatcher>, Action<String>)

Repeats a match action until boundaries are met

Declaration

public CodeMatcher Repeat(Action<CodeMatcher> matchAction, Action<string> notFoundAction = null)

Parameters

The match action

| | System.Action\ | notFoundAction |

An optional action that is executed when no match is found

|

Returns

The same code matcher

|

ReportFailure(MethodBase, Action<String>)

Reports a failure

Declaration

public bool ReportFailure(MethodBase method, Action<string> logger)

Parameters

The method involved

| | System.Action\ | logger |

The logger

|

Returns

True if current position is invalid and error was logged

|

Reset(Boolean)

Resets the current position to -1 and clears last matches and errors

Declaration

public CodeMatcher Reset(bool atFirstInstruction = true)

Parameters

If true, sets position to 0, otherwise sets it to -1

|

Returns

The same code matcher

|

SearchBackwards(Func<CodeInstruction, Boolean>)

Searches backwards with a predicate and moves the position

Declaration

public CodeMatcher SearchBackwards(Func<CodeInstruction, bool> predicate)

Parameters

A function to test each instruction for a match

|

Returns

The same code matcher

|

SearchForward(Func<CodeInstruction, Boolean>)

Searches forward with a predicate and advances position

Declaration

public CodeMatcher SearchForward(Func<CodeInstruction, bool> predicate)

Parameters

A function to test each instruction for a match

|

Returns

The same code matcher

|

Set(OpCode, Object)

Sets opcode and operand at current position

Declaration

public CodeMatcher Set(OpCode opcode, object operand)

Parameters

The opcode

| | System.Object | operand |

The operand

|

Returns

The same code matcher

|

SetAndAdvance(OpCode, Object)

Sets opcode and operand at current position and advances

Declaration

public CodeMatcher SetAndAdvance(OpCode opcode, object operand)

Parameters

The opcode

| | System.Object | operand |

The operand

|

Returns

The same code matcher

|

SetInstruction(CodeInstruction)

Sets an instruction at current position

Declaration

public CodeMatcher SetInstruction(CodeInstruction instruction)

Parameters

The instruction to set

|

Returns

The same code matcher

|

SetInstructionAndAdvance(CodeInstruction)

Sets instruction at current position and advances

Declaration

public CodeMatcher SetInstructionAndAdvance(CodeInstruction instruction)

Parameters

The instruction

|

Returns

The same code matcher

|

SetJumpTo(OpCode, Int32, out Label)

Sets jump to

Declaration

public CodeMatcher SetJumpTo(OpCode opcode, int destination, out Label label)

Parameters

Branch instruction

| | System.Int32 | destination |

Destination for the jump

| | System.Reflection.Emit.Label | label |

[out] The created label

|

Returns

The same code matcher

|

SetOpcodeAndAdvance(OpCode)

Sets opcode at current position and advances

Declaration

public CodeMatcher SetOpcodeAndAdvance(OpCode opcode)

Parameters

The opcode

|

Returns

The same code matcher

|

SetOperandAndAdvance(Object)

Sets operand at current position and advances

Declaration

public CodeMatcher SetOperandAndAdvance(object operand)

Parameters

The operand

|

Returns

The same code matcher

|

Start()

Moves the current position to the start

Declaration

public CodeMatcher Start()

Returns

The same code matcher

|

ThrowIfFalse(String, Func<CodeMatcher, Boolean>)

Throw an InvalidOperationException if current state is invalid (position out of bounds / last match failed), or if the check function returns false

Declaration

public CodeMatcher ThrowIfFalse(string explanation, Func<CodeMatcher, bool> stateCheckFunc)

Parameters

Explanation of where/why the exception was thrown that will be added to the exception message

| | System.Func<CodeMatcher, System.Boolean> | stateCheckFunc |

Function that checks validity of current state. If it returns false, an exception is thrown

|

Returns

The same code matcher

|

ThrowIfInvalid(String)

Throw an InvalidOperationException if current state is invalid (position out of bounds / last match failed)

Declaration

public CodeMatcher ThrowIfInvalid(string explanation)

Parameters

Explanation of where/why the exception was thrown that will be added to the exception message

|

Returns

The same code matcher

|

ThrowIfNotMatch(String, CodeMatch[])

Throw an InvalidOperationException if current state is invalid (position out of bounds / last match failed), or if the matches do not match at current position

Declaration

public CodeMatcher ThrowIfNotMatch(string explanation, params CodeMatch[] matches)

Parameters

Explanation of where/why the exception was thrown that will be added to the exception message

| | CodeMatch[] | matches |

Some code matches

|

Returns

The same code matcher

|

ThrowIfNotMatchBack(String, CodeMatch[])

Throw an InvalidOperationException if current state is invalid (position out of bounds / last match failed), or if the matches do not match at any point between current position and the start

Declaration

public CodeMatcher ThrowIfNotMatchBack(string explanation, params CodeMatch[] matches)

Parameters

Explanation of where/why the exception was thrown that will be added to the exception message

| | CodeMatch[] | matches |

Some code matches

|

Returns

The same code matcher

|

ThrowIfNotMatchForward(String, CodeMatch[])

Throw an InvalidOperationException if current state is invalid (position out of bounds / last match failed), or if the matches do not match at any point between current position and the end

Declaration

public CodeMatcher ThrowIfNotMatchForward(string explanation, params CodeMatch[] matches)

Parameters

Explanation of where/why the exception was thrown that will be added to the exception message

| | CodeMatch[] | matches |

Some code matches

|

Returns

The same code matcher

|