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

Type	Name	Description
System.Collections.Generic.IEnumerable<CodeInstruction>	instructions	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 ref List<ExceptionBlock> Blocks { get; }

Property Value

Type	Description
System.Collections.Generic.List<ExceptionBlock>	The blocks

Instruction

Gets instructions at the current position

Declaration

public CodeInstruction Instruction { get; }

Property Value

Type	Description
CodeInstruction	The instruction

IsInvalid

Checks whether the position of this CodeMatcher is outside its bounds

Declaration

public bool IsInvalid { get; }

Property Value

Type	Description
System.Boolean	True if this CodeMatcher is invalid

IsValid

Checks whether the position of this CodeMatcher is within bounds

Declaration

public bool IsValid { get; }

Property Value

Type	Description
System.Boolean	True if this CodeMatcher is valid

Labels

Gets the labels at the current position

Declaration

public ref List<Label> Labels { get; }

Property Value

Type	Description
System.Collections.Generic.List<System.Reflection.Emit.Label>	The labels

Length

Gets the number of code instructions in this matcher

Declaration

public int Length { get; }

Property Value

Type	Description
System.Int32	The count

Opcode

Gets the opcode at the current position

Declaration

public ref OpCode Opcode { get; }

Property Value

Type	Description
System.Reflection.Emit.OpCode	The opcode

Operand

Gets the operand at the current position

Declaration

public ref object Operand { get; }

Property Value

Type	Description
System.Object	The operand

Pos

The current position

Declaration

public int Pos { get; }

Property Value

Type	Description
System.Int32	The index or -1 if out of bounds

Remaining

Gets the remaining code instructions

Declaration

public int Remaining { get; }

Property Value

Type	Description
System.Int32	The remaining count

Methods

AddLabels(IEnumerable<Label>)

Adds an enumeration of labels to current position

Declaration

public CodeMatcher AddLabels(IEnumerable<Label> labels)

Parameters

Type	Name	Description
System.Collections.Generic.IEnumerable<System.Reflection.Emit.Label>	labels	The labels

Returns

Type	Description
CodeMatcher	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

Type	Name	Description
System.Int32	position	The position
System.Collections.Generic.IEnumerable<System.Reflection.Emit.Label>	labels	The labels

Returns

Type	Description
CodeMatcher	The same code matcher

Advance(Int32)

Advances the current position

Declaration

public CodeMatcher Advance(int offset)

Parameters

Type	Name	Description
System.Int32	offset	The offset

Returns

Type	Description
CodeMatcher	The same code matcher

Clone()

Makes a clone of this instruction matcher

Declaration

public CodeMatcher Clone()

Returns

Type	Description
CodeMatcher	A copy of this matcher

CreateLabel(out Label)

Creates a label at current position

Declaration

public CodeMatcher CreateLabel(out Label label)

Parameters

Type	Name	Description
System.Reflection.Emit.Label	label	[out] The label

Returns

Type	Description
CodeMatcher	The same code matcher

CreateLabelAt(Int32, out Label)

Creates a label at a position

Declaration

public CodeMatcher CreateLabelAt(int position, out Label label)

Parameters

Type	Name	Description
System.Int32	position	The position
System.Reflection.Emit.Label	label	[out] The new label

Returns

Type	Description
CodeMatcher	The same code matcher

CreateLabelWithOffsets(Int32, out Label)

Creates a label at a position

Declaration

public CodeMatcher CreateLabelWithOffsets(int offset, out Label label)

Parameters

Type	Name	Description
System.Int32	offset	The offset
System.Reflection.Emit.Label	label	[out] The new label

Returns

Type	Description
CodeMatcher	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

Type	Name	Description
System.Type	variableType	The variable type
System.Reflection.Emit.LocalBuilder	localVariable	[out] The new local variable

Returns

Type	Description
CodeMatcher	The same code matcher

DefineLabel(out Label)

Declares a new label but does not add it

Declaration

public CodeMatcher DefineLabel(out Label label)

Parameters

Type	Name	Description
System.Reflection.Emit.Label	label	[out] The new label

Returns

Type	Description
CodeMatcher	The same code matcher

DistinctLabels(IEnumerable<CodeInstruction>)

Gets a list of all distinct labels

Declaration

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

Parameters

Type	Name	Description
System.Collections.Generic.IEnumerable<CodeInstruction>	instructions	The instructions (transpiler argument)

Returns

Type	Description
System.Collections.Generic.List<System.Reflection.Emit.Label>	A list of Labels

End()

Moves the current position to the end

Declaration

public CodeMatcher End()

Returns

Type	Description
CodeMatcher	The same code matcher

Insert(CodeInstruction[])

Inserts some instructions

Declaration

public CodeMatcher Insert(params CodeInstruction[] instructions)

Parameters

Type	Name	Description
CodeInstruction[]	instructions	The instructions

Returns

Type	Description
CodeMatcher	The same code matcher

Insert(IEnumerable<CodeInstruction>)

Inserts an enumeration of instructions

Declaration

public CodeMatcher Insert(IEnumerable<CodeInstruction> instructions)

Parameters

Type	Name	Description
System.Collections.Generic.IEnumerable<CodeInstruction>	instructions	The instructions

Returns

Type	Description
CodeMatcher	The same code matcher

InsertAndAdvance(CodeInstruction[])

Inserts some instructions and advances the position

Declaration

public CodeMatcher InsertAndAdvance(params CodeInstruction[] instructions)

Parameters

Type	Name	Description
CodeInstruction[]	instructions	The instructions

Returns

Type	Description
CodeMatcher	The same code matcher

InsertAndAdvance(IEnumerable<CodeInstruction>)

Inserts an enumeration of instructions and advances the position

Declaration

public CodeMatcher InsertAndAdvance(IEnumerable<CodeInstruction> instructions)

Parameters

Type	Name	Description
System.Collections.Generic.IEnumerable<CodeInstruction>	instructions	The instructions

Returns

Type	Description
CodeMatcher	The same code matcher

InsertBranch(OpCode, Int32)

Inserts a branch

Declaration

public CodeMatcher InsertBranch(OpCode opcode, int destination)

Parameters

Type	Name	Description
System.Reflection.Emit.OpCode	opcode	The branch opcode
System.Int32	destination	Branch destination

Returns

Type	Description
CodeMatcher	The same code matcher

InsertBranchAndAdvance(OpCode, Int32)

Inserts a branch and advances the position

Declaration

public CodeMatcher InsertBranchAndAdvance(OpCode opcode, int destination)

Parameters

Type	Name	Description
System.Reflection.Emit.OpCode	opcode	The branch opcode
System.Int32	destination	Branch destination

Returns

Type	Description
CodeMatcher	The same code matcher

InstructionAt(Int32)

Gets instructions at the current position with offset

Declaration

public CodeInstruction InstructionAt(int offset)

Parameters

Type	Name	Description
System.Int32	offset	The offset

Returns

Type	Description
CodeInstruction	The instruction

InstructionEnumeration()

Gets all instructions as an enumeration

Declaration

public IEnumerable<CodeInstruction> InstructionEnumeration()

Returns

Type	Description
System.Collections.Generic.IEnumerable<CodeInstruction>	A list of instructions

Instructions()

Gets all instructions

Declaration

public List<CodeInstruction> Instructions()

Returns

Type	Description
System.Collections.Generic.List<CodeInstruction>	A list of instructions

Instructions(Int32)

Gets some instructions counting from current position

Declaration

public List<CodeInstruction> Instructions(int count)

Parameters

Type	Name	Description
System.Int32	count	Number of instructions

Returns

Type	Description
System.Collections.Generic.List<CodeInstruction>	A list of instructions

InstructionsInRange(Int32, Int32)

Gets all instructions within a range

Declaration

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

Parameters

Type	Name	Description
System.Int32	start	The start index
System.Int32	end	The end index

Returns

Type	Description
System.Collections.Generic.List<CodeInstruction>	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

Type	Name	Description
System.Int32	startOffset	The start offset
System.Int32	endOffset	The end offset

Returns

Type	Description
System.Collections.Generic.List<CodeInstruction>	A list of instructions

MatchEndBackwards(CodeMatch[])

Matches backwards and reverses position to ending of matching sequence

Declaration

public CodeMatcher MatchEndBackwards(params CodeMatch[] matches)

Parameters

Type	Name	Description
CodeMatch[]	matches	Some code matches

Returns

Type	Description
CodeMatcher	The same code matcher

MatchEndForward(CodeMatch[])

Matches forward and advances position to ending of matching sequence

Declaration

public CodeMatcher MatchEndForward(params CodeMatch[] matches)

Parameters

Type	Name	Description
CodeMatch[]	matches	Some code matches

Returns

Type	Description
CodeMatcher	The same code matcher

MatchStartBackwards(CodeMatch[])

Matches backwards and reverses position to beginning of matching sequence

Declaration

public CodeMatcher MatchStartBackwards(params CodeMatch[] matches)

Parameters

Type	Name	Description
CodeMatch[]	matches	Some code matches

Returns

Type	Description
CodeMatcher	The same code matcher

MatchStartForward(CodeMatch[])

Matches forward and advances position to beginning of matching sequence

Declaration

public CodeMatcher MatchStartForward(params CodeMatch[] matches)

Parameters

Type	Name	Description
CodeMatch[]	matches	Some code matches

Returns

Type	Description
CodeMatcher	The same code matcher

NamedMatch(String)

Gets a match by its name

Declaration

public CodeInstruction NamedMatch(string name)

Parameters

Type	Name	Description
System.String	name	The match name

Returns

Type	Description
CodeInstruction	An instruction

RemoveInstruction()

Removes current instruction

Declaration

public CodeMatcher RemoveInstruction()

Returns

Type	Description
CodeMatcher	The same code matcher

RemoveInstructions(Int32)

Removes some instruction from current position by count

Declaration

public CodeMatcher RemoveInstructions(int count)

Parameters

Type	Name	Description
System.Int32	count	Number of instructions

Returns

Type	Description
CodeMatcher	The same code matcher

RemoveInstructionsInRange(Int32, Int32)

Removes the instructions in a range

Declaration

public CodeMatcher RemoveInstructionsInRange(int start, int end)

Parameters

Type	Name	Description
System.Int32	start	The start
System.Int32	end	The end

Returns

Type	Description
CodeMatcher	The same code matcher

RemoveInstructionsWithOffsets(Int32, Int32)

Removes the instructions in a offset range

Declaration

public CodeMatcher RemoveInstructionsWithOffsets(int startOffset, int endOffset)

Parameters

Type	Name	Description
System.Int32	startOffset	The start offset
System.Int32	endOffset	The end offset

Returns

Type	Description
CodeMatcher	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

Type	Name	Description
System.Action<CodeMatcher>	matchAction	The match action
System.Action<System.String>	notFoundAction	An optional action that is executed when no match is found

Returns

Type	Description
CodeMatcher	The same code matcher

ReportFailure(MethodBase, Action<String>)

Reports a failure

Declaration

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

Parameters

Type	Name	Description
System.Reflection.MethodBase	method	The method involved
System.Action<System.String>	logger	The logger

Returns

Type	Description
System.Boolean	True if current position is invalid and error was logged

SearchBackwards(Func<CodeInstruction, Boolean>)

Searches backwards with a predicate and reverses position

Declaration

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

Parameters

Type	Name	Description
System.Func<CodeInstruction, System.Boolean>	predicate	The predicate

Returns

Type	Description
CodeMatcher	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

Type	Name	Description
System.Func<CodeInstruction, System.Boolean>	predicate	The predicate

Returns

Type	Description
CodeMatcher	The same code matcher

Set(OpCode, Object)

Sets opcode and operand at current position

Declaration

public CodeMatcher Set(OpCode opcode, object operand)

Parameters

Type	Name	Description
System.Reflection.Emit.OpCode	opcode	The opcode
System.Object	operand	The operand

Returns

Type	Description
CodeMatcher	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

Type	Name	Description
System.Reflection.Emit.OpCode	opcode	The opcode
System.Object	operand	The operand

Returns

Type	Description
CodeMatcher	The same code matcher

SetInstruction(CodeInstruction)

Sets an instruction at current position

Declaration

public CodeMatcher SetInstruction(CodeInstruction instruction)

Parameters

Type	Name	Description
CodeInstruction	instruction	The instruction to set

Returns

Type	Description
CodeMatcher	The same code matcher

SetInstructionAndAdvance(CodeInstruction)

Sets instruction at current position and advances

Declaration

public CodeMatcher SetInstructionAndAdvance(CodeInstruction instruction)

Parameters

Type	Name	Description
CodeInstruction	instruction	The instruction

Returns

Type	Description
CodeMatcher	The same code matcher

SetJumpTo(OpCode, Int32, out Label)

Sets jump to

Declaration

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

Parameters

Type	Name	Description
System.Reflection.Emit.OpCode	opcode	Branch instruction
System.Int32	destination	Destination for the jump
System.Reflection.Emit.Label	label	[out] The created label

Returns

Type	Description
CodeMatcher	The same code matcher

SetOpcodeAndAdvance(OpCode)

Sets opcode at current position and advances

Declaration

public CodeMatcher SetOpcodeAndAdvance(OpCode opcode)

Parameters

Type	Name	Description
System.Reflection.Emit.OpCode	opcode	The opcode

Returns

Type	Description
CodeMatcher	The same code matcher

SetOperandAndAdvance(Object)

Sets operand at current position and advances

Declaration

public CodeMatcher SetOperandAndAdvance(object operand)

Parameters

Type	Name	Description
System.Object	operand	The operand

Returns

Type	Description
CodeMatcher	The same code matcher

Start()

Moves the current position to the start

Declaration

public CodeMatcher Start()

Returns

Type	Description
CodeMatcher	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

Type	Name	Description
System.String	explanation	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

Type	Description
CodeMatcher	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

Type	Name	Description
System.String	explanation	Explanation of where/why the exception was thrown that will be added to the exception message

Returns

Type	Description
CodeMatcher	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

Type	Name	Description
System.String	explanation	Explanation of where/why the exception was thrown that will be added to the exception message
CodeMatch[]	matches	Some code matches

Returns

Type	Description
CodeMatcher	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

Type	Name	Description
System.String	explanation	Explanation of where/why the exception was thrown that will be added to the exception message
CodeMatch[]	matches	Some code matches

Returns

Type	Description
CodeMatcher	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

Type	Name	Description
System.String	explanation	Explanation of where/why the exception was thrown that will be added to the exception message
CodeMatch[]	matches	Some code matches

Returns

Type	Description
CodeMatcher	The same code matcher