Class CodeMatcher

Namespace

HarmonyLib

Assembly

0Harmony.dll

A CodeInstruction matcher

public class CodeMatcher

Inheritance

object

CodeMatcher

Constructors

CodeMatcher()

Creates an empty code matcher

public CodeMatcher()

CodeMatcher(IEnumerable<CodeInstruction>, ILGenerator)

Creates a code matcher from an enumeration of instructions

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

Parameters

instructions IEnumerable<CodeInstruction>

The instructions (transpiler argument)

generator ILGenerator

An optional IL generator

Properties

Blocks

Gets the exception blocks at the current position

public ref List<ExceptionBlock> Blocks { get; }

Property Value

List<ExceptionBlock>

The blocks

Instruction

Gets instructions at the current position

public CodeInstruction Instruction { get; }

Property Value

CodeInstruction

The instruction

IsInvalid

Checks whether the position of this CodeMatcher is outside its bounds

public bool IsInvalid { get; }

Property Value

bool

True if this CodeMatcher is invalid

IsValid

Checks whether the position of this CodeMatcher is within bounds

public bool IsValid { get; }

Property Value

bool

True if this CodeMatcher is valid

Labels

Gets the labels at the current position

public ref List<Label> Labels { get; }

Property Value

List<Label>

The labels

Length

Gets the number of code instructions in this matcher

public int Length { get; }

Property Value

int

The count

Opcode

Gets the opcode at the current position

public ref OpCode Opcode { get; }

Property Value

OpCode

The opcode

Operand

Gets the operand at the current position

public ref object Operand { get; }

Property Value

object

The operand

Pos

The current position

public int Pos { get; }

Property Value

int

The index or -1 if out of bounds

Remaining

Gets the remaining code instructions

public int Remaining { get; }

Property Value

int

The remaining count

Methods

AddLabels(IEnumerable<Label>)

Adds an enumeration of labels to current position

public CodeMatcher AddLabels(IEnumerable<Label> labels)

Parameters

labels IEnumerable<Label>

The labels

Returns

CodeMatcher

The same code matcher

AddLabelsAt(int, IEnumerable<Label>)

Adds an enumeration of labels at a position

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

Parameters

position int

The position

labels IEnumerable<Label>

The labels

Returns

CodeMatcher

The same code matcher

Advance(int)

Advances the current position

public CodeMatcher Advance(int offset = 1)

Parameters

offset int

The offset

Returns

CodeMatcher

The same code matcher

Clone()

Makes a clone of this instruction matcher

public CodeMatcher Clone()

Returns

CodeMatcher

A copy of this matcher

CreateLabel(out Label)

Creates a label at current position

public CodeMatcher CreateLabel(out Label label)

Parameters

label Label

[out] The label

Returns

CodeMatcher

The same code matcher

CreateLabelAt(int, out Label)

Creates a label at a position

public CodeMatcher CreateLabelAt(int position, out Label label)

Parameters

position int

The position

label Label

[out] The new label

Returns

CodeMatcher

The same code matcher

CreateLabelWithOffsets(int, out Label)

Creates a label at the given offset from the current position

public CodeMatcher CreateLabelWithOffsets(int offset, out Label label)

Parameters

offset int

The offset

label Label

[out] The new label

Returns

CodeMatcher

The same code matcher

DeclareLocal(Type, out LocalBuilder)

Declares a local variable but does not add it

public CodeMatcher DeclareLocal(Type variableType, out LocalBuilder localVariable)

Parameters

variableType Type

The variable type

localVariable LocalBuilder

[out] The new local variable

Returns

CodeMatcher

The same code matcher

DefineLabel(out Label)

Declares a new label but does not add it

public CodeMatcher DefineLabel(out Label label)

Parameters

label Label

[out] The new label

Returns

CodeMatcher

The same code matcher

DistinctLabels(IEnumerable<CodeInstruction>)

Gets a list of all distinct labels

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

Parameters

instructions IEnumerable<CodeInstruction>

The instructions (transpiler argument)

Returns

List<Label>

A list of Labels

Do(Action<CodeMatcher>)

Runs some code when chaining CodeMatcher at the current position

public CodeMatcher Do(Action<CodeMatcher> action)

Parameters

action Action<CodeMatcher>

The System.Action<T> to run

Returns

CodeMatcher

The same code matcher

End()

Moves the current position to the end

public CodeMatcher End()

Returns

CodeMatcher

The same code matcher

Insert(params CodeInstruction[])

Inserts some instructions at the current position

public CodeMatcher Insert(params CodeInstruction[] instructions)

Parameters

instructions CodeInstruction[]

The instructions

Returns

CodeMatcher

The same code matcher

Insert(IEnumerable<CodeInstruction>)

Inserts an enumeration of instructions at the current position

public CodeMatcher Insert(IEnumerable<CodeInstruction> instructions)

Parameters

instructions IEnumerable<CodeInstruction>

The instructions

Returns

CodeMatcher

The same code matcher

InsertAfter(params CodeInstruction[])

Inserts instructions immediately after the current position

public CodeMatcher InsertAfter(params CodeInstruction[] instructions)

Parameters

instructions CodeInstruction[]

The instructions

Returns

CodeMatcher

The same code matcher

InsertAfter(IEnumerable<CodeInstruction>)

Inserts an enumeration of instructions immediately after the current position

public CodeMatcher InsertAfter(IEnumerable<CodeInstruction> instructions)

Parameters

instructions IEnumerable<CodeInstruction>

The instructions

Returns

CodeMatcher

The same code matcher

InsertAfterAndAdvance(params CodeInstruction[])

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

public CodeMatcher InsertAfterAndAdvance(params CodeInstruction[] instructions)

Parameters

instructions CodeInstruction[]

The instructions

Returns

CodeMatcher

The same code matcher

InsertAfterAndAdvance(IEnumerable<CodeInstruction>)

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

public CodeMatcher InsertAfterAndAdvance(IEnumerable<CodeInstruction> instructions)

Parameters

instructions IEnumerable<CodeInstruction>

The instructions

Returns

CodeMatcher

The same code matcher

InsertAndAdvance(params CodeInstruction[])

Inserts some instructions at the current position and advances it

public CodeMatcher InsertAndAdvance(params CodeInstruction[] instructions)

Parameters

instructions CodeInstruction[]

The instructions

Returns

CodeMatcher

The same code matcher

InsertAndAdvance(IEnumerable<CodeInstruction>)

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

public CodeMatcher InsertAndAdvance(IEnumerable<CodeInstruction> instructions)

Parameters

instructions IEnumerable<CodeInstruction>

The instructions

Returns

CodeMatcher

The same code matcher

InsertBranch(OpCode, int)

Inserts a branch at the current position

public CodeMatcher InsertBranch(OpCode opcode, int destination)

Parameters

opcode OpCode

The branch opcode

destination int

Branch destination

Returns

CodeMatcher

The same code matcher

InsertBranchAfter(OpCode, int)

Inserts a branch instruction immediately after the current position

public CodeMatcher InsertBranchAfter(OpCode opcode, int destination)

Parameters

opcode OpCode

The branch opcode

destination int

Branch destination index

Returns

CodeMatcher

The same code matcher

InsertBranchAfterAndAdvance(OpCode, int)

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

public CodeMatcher InsertBranchAfterAndAdvance(OpCode opcode, int destination)

Parameters

opcode OpCode

The branch opcode

destination int

Branch destination index

Returns

CodeMatcher

The same code matcher

InsertBranchAndAdvance(OpCode, int)

Inserts a branch at the current position and advances it

public CodeMatcher InsertBranchAndAdvance(OpCode opcode, int destination)

Parameters

opcode OpCode

The branch opcode

destination int

Branch destination

Returns

CodeMatcher

The same code matcher

InstructionAt(int)

Gets instructions at the current position with offset

public CodeInstruction InstructionAt(int offset)

Parameters

offset int

The offset

Returns

CodeInstruction

The instruction

InstructionEnumeration()

Gets all instructions as an enumeration

public IEnumerable<CodeInstruction> InstructionEnumeration()

Returns

IEnumerable<CodeInstruction>

A list of instructions

Instructions()

Gets all instructions

public List<CodeInstruction> Instructions()

Returns

List<CodeInstruction>

A list of instructions

Instructions(int)

Gets some instructions counting from current position

public List<CodeInstruction> Instructions(int count)

Parameters

count int

Number of instructions

Returns

List<CodeInstruction>

A list of instructions

InstructionsInRange(int, int)

Gets all instructions within a range

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

Parameters

start int

The start index

end int

The end index

Returns

List<CodeInstruction>

A list of instructions

InstructionsWithOffsets(int, int)

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

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

Parameters

startOffset int

The start offset

endOffset int

The end offset

Returns

List<CodeInstruction>

A list of instructions

MatchEndBackwards(params CodeMatch[])

Matches backwards and moves the position to ending of matching sequence

public CodeMatcher MatchEndBackwards(params CodeMatch[] matches)

Parameters

matches CodeMatch[]

Some code matches

Returns

CodeMatcher

The same code matcher

MatchEndForward(params CodeMatch[])

Matches forward and advances position to ending of matching sequence

public CodeMatcher MatchEndForward(params CodeMatch[] matches)

Parameters

matches CodeMatch[]

Some code matches

Returns

CodeMatcher

The same code matcher

MatchStartBackwards(params CodeMatch[])

Matches backwards and moves the position to beginning of matching sequence

public CodeMatcher MatchStartBackwards(params CodeMatch[] matches)

Parameters

matches CodeMatch[]

Some code matches

Returns

CodeMatcher

The same code matcher

MatchStartForward(params CodeMatch[])

Matches forward and advances position to beginning of matching sequence

public CodeMatcher MatchStartForward(params CodeMatch[] matches)

Parameters

matches CodeMatch[]

Some code matches

Returns

CodeMatcher

The same code matcher

NamedMatch(string)

Gets a match by its name

public CodeInstruction NamedMatch(string name)

Parameters

name string

The match name

Returns

CodeInstruction

An instruction

OnError(ErrorHandler)

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

public CodeMatcher OnError(CodeMatcher.ErrorHandler errorHandler)

Parameters

errorHandler CodeMatcher.ErrorHandler

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

Returns

CodeMatcher

The same code matcher

PrepareMatchEndBackwards(params CodeMatch[])

Prepares matching backwards and reversing position to ending of matching sequence

public CodeMatcher PrepareMatchEndBackwards(params CodeMatch[] matches)

Parameters

matches CodeMatch[]

Some code matches

Returns

CodeMatcher

The same code matcher

PrepareMatchEndForward(params CodeMatch[])

Prepares matching forward and advancing position to ending of matching sequence

public CodeMatcher PrepareMatchEndForward(params CodeMatch[] matches)

Parameters

matches CodeMatch[]

Some code matches

Returns

CodeMatcher

The same code matcher

PrepareMatchStartBackwards(params CodeMatch[])

Prepares matching backwards and reversing position to beginning of matching sequence

public CodeMatcher PrepareMatchStartBackwards(params CodeMatch[] matches)

Parameters

matches CodeMatch[]

Some code matches

Returns

CodeMatcher

The same code matcher

PrepareMatchStartForward(params CodeMatch[])

Prepares matching forward and advancing position to beginning of matching sequence

public CodeMatcher PrepareMatchStartForward(params CodeMatch[] matches)

Parameters

matches CodeMatch[]

Some code matches

Returns

CodeMatcher

The same code matcher

RemoveInstruction()

Removes current instruction

public CodeMatcher RemoveInstruction()

Returns

CodeMatcher

The same code matcher

RemoveInstructions(int)

Removes some instruction from current position by count

public CodeMatcher RemoveInstructions(int count)

Parameters

count int

Number of instructions

Returns

CodeMatcher

The same code matcher

RemoveInstructionsInRange(int, int)

Removes the instructions in a range

public CodeMatcher RemoveInstructionsInRange(int start, int end)

Parameters

start int

The start

end int

The end

Returns

CodeMatcher

The same code matcher

RemoveInstructionsWithOffsets(int, int)

Removes the instructions in an offset range

public CodeMatcher RemoveInstructionsWithOffsets(int startOffset, int endOffset)

Parameters

startOffset int

The start offset

endOffset int

The end offset

Returns

CodeMatcher

The same code matcher

RemoveSearchBackward(Func<CodeInstruction, bool>)

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

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

Parameters

predicate Func<CodeInstruction, bool>

A function to test each instruction for a match

Returns

CodeMatcher

The same code matcher

RemoveSearchForward(Func<CodeInstruction, bool>)

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

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

Parameters

predicate Func<CodeInstruction, bool>

A function to test each instruction for a match

Returns

CodeMatcher

The same code matcher

RemoveUntilBackward(params CodeMatch[])

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

public CodeMatcher RemoveUntilBackward(params CodeMatch[] matches)

Parameters

matches CodeMatch[]

Some code matches

Returns

CodeMatcher

The same code matcher

RemoveUntilForward(params CodeMatch[])

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

public CodeMatcher RemoveUntilForward(params CodeMatch[] matches)

Parameters

matches CodeMatch[]

Some code matches

Returns

CodeMatcher

The same code matcher

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

Repeats a match action until boundaries are met

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

Parameters

matchAction Action<CodeMatcher>

The match action

notFoundAction Action<string>

An optional action that is executed when no match is found

Returns

CodeMatcher

The same code matcher

ReportFailure(MethodBase, Action<string>)

Reports a failure

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

Parameters

method MethodBase

The method involved

logger Action<string>

The logger

Returns

bool

True if current position is invalid and error was logged

Reset(bool)

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

public CodeMatcher Reset(bool atFirstInstruction = true)

Parameters

atFirstInstruction bool

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

Returns

CodeMatcher

The same code matcher

SearchBackwards(Func<CodeInstruction, bool>)

Searches backwards with a predicate and moves the position

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

Parameters

predicate Func<CodeInstruction, bool>

A function to test each instruction for a match

Returns

CodeMatcher

The same code matcher

SearchForward(Func<CodeInstruction, bool>)

Searches forward with a predicate and advances position

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

Parameters

predicate Func<CodeInstruction, bool>

A function to test each instruction for a match

Returns

CodeMatcher

The same code matcher

Set(OpCode, object)

Sets opcode and operand at current position

public CodeMatcher Set(OpCode opcode, object operand)

Parameters

opcode OpCode

The opcode

operand object

The operand

Returns

CodeMatcher

The same code matcher

SetAndAdvance(OpCode, object)

Sets opcode and operand at current position and advances

public CodeMatcher SetAndAdvance(OpCode opcode, object operand)

Parameters

opcode OpCode

The opcode

operand object

The operand

Returns

CodeMatcher

The same code matcher

SetInstruction(CodeInstruction)

Sets an instruction at current position

public CodeMatcher SetInstruction(CodeInstruction instruction)

Parameters

instruction CodeInstruction

The instruction to set

Returns

CodeMatcher

The same code matcher

SetInstructionAndAdvance(CodeInstruction)

Sets instruction at current position and advances

public CodeMatcher SetInstructionAndAdvance(CodeInstruction instruction)

Parameters

instruction CodeInstruction

The instruction

Returns

CodeMatcher

The same code matcher

SetJumpTo(OpCode, int, out Label)

Sets jump to

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

Parameters

opcode OpCode

Branch instruction

destination int

Destination for the jump

label Label

[out] The created label

Returns

CodeMatcher

The same code matcher

SetOpcodeAndAdvance(OpCode)

Sets opcode at current position and advances

public CodeMatcher SetOpcodeAndAdvance(OpCode opcode)

Parameters

opcode OpCode

The opcode

Returns

CodeMatcher

The same code matcher

SetOperandAndAdvance(object)

Sets operand at current position and advances

public CodeMatcher SetOperandAndAdvance(object operand)

Parameters

operand object

The operand

Returns

CodeMatcher

The same code matcher

Start()

Moves the current position to the start

public CodeMatcher Start()

Returns

CodeMatcher

The same code matcher

ThrowIfFalse(string, Func<CodeMatcher, bool>)

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

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

Parameters

explanation string

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

stateCheckFunc Func<CodeMatcher, bool>

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

Returns

CodeMatcher

The same code matcher

ThrowIfInvalid(string)

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

public CodeMatcher ThrowIfInvalid(string explanation)

Parameters

explanation string

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

Returns

CodeMatcher

The same code matcher

ThrowIfNotMatch(string, params 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

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

Parameters

explanation string

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

matches CodeMatch[]

Some code matches

Returns

CodeMatcher

The same code matcher

ThrowIfNotMatchBack(string, params 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

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

Parameters

explanation string

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

matches CodeMatch[]

Some code matches

Returns

CodeMatcher

The same code matcher

ThrowIfNotMatchForward(string, params 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

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

Parameters

explanation string

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

matches CodeMatch[]

Some code matches

Returns

CodeMatcher

The same code matcher