- Class Tag

- getName

- Class Procedure

- addTag
- decompile
- getBasicBlock
- getBasicBlockAtAddress
- getBasicBlockCount
- getEntryPoint
- getHeapSize
- getTagAtIndex
- getTagCount
- getTagList
- hasTag
- removeTag
- tagIterator

- Class BasicBlock

- addTag
- getEndingAddress
- getProcedure
- getStartingAddress
- getSuccessorAddressAtIndex
- getSuccessorCount
- getSuccessorIndexAtIndex
- getTagAtIndex
- getTagCount
- getTagList
- hasTag
- removeTag
- tagIterator

- Class Instruction

- getArchitecture
- getArgumentCount
- getFormattedArgument
- getInstructionLength
- getInstructionString
- getRawArgument
- isAConditionalJump
- isAnInconditionalJump
- stringForArchitecture

- Class Section

- getLength
- getName
- getStartingAddress

- Class Segment

- addReference
- disassembleWholeSegment
- getCommentAtAddress
- getFileOffset
- getFileOffsetForAddress
- getInlineCommentAtAddress
- getInstructionAtAddress
- getLabelCount
- getLabelName
- getLabelsList
- getLength
- getName
- getNameAtAddress
- getNextAddressWithType
- getProcedureAtAddress
- getProcedureAtIndex
- getProcedureCount
- getProcedureIndexAtAddress
- getReferencesFromAddress
- getReferencesOfAddress
- getSection
- getSectionCount
- getSectionsList
- getStartingAddress
- getTypeAtAddress
- instructionStart
- isThumbAtAddress
- labelIterator
- markAsCode
- markAsDataByteArray
- markAsDataIntArray
- markAsDataShortArray
- markAsProcedure
- markAsUndefined
- markRangeAsUndefined
- readByte
- readBytes
- readUInt16BE
- readUInt16LE
- readUInt32BE
- readUInt32LE
- readUInt64BE
- readUInt64LE
- removeReference
- setARMModeAtAddress
- setCommentAtAddress
- setInlineCommentAtAddress
- setNameAtAddress
- setThumbModeAtAddress
- setTypeAtAddress
- stringForType
- writeByte
- writeBytes
- writeUInt16BE
- writeUInt16LE
- writeUInt32BE
- writeUInt32LE
- writeUInt64BE
- writeUInt64LE

- Class Document

- addTagAtAddress
- ask
- askDirectory
- askFile
- assemble
- buildTag
- destroyTag
- getAddressForName
- getAddressFromFileOffset
- getColorAtAddress
- getCurrentAddress
- getCurrentDocument
- getCurrentSegment
- getCurrentSegmentIndex
- getDatabaseFilePath
- getEntryPoint
- getExecutableFilePath
- getFileOffsetFromAddress
- getHighlightedWord
- getNameAtAddress
- getOperandFormat
- getRawSelectedLines
- getSectionByName
- getSegment
- getSegmentAtAddress
- getSegmentByName
- getSegmentCount
- getSegmentIndexAtAddress
- getSegmentsList
- getSelectionAddressRange
- getTagAtAddressByIndex
- getTagAtIndex
- getTagCount
- getTagCountAtAddress
- getTagList
- getTagListAtAddress
- getTagWithName
- hasColorAtAddress
- hasTagAtAddress
- is64Bits
- log
- message
- moveCursorAtAddress
- moveCursorAtEntryPoint
- moveCursorOneLineDown
- moveCursorOneLineUp
- readByte
- readBytes
- readUInt16BE
- readUInt16LE
- readUInt32BE
- readUInt32LE
- readUInt64BE
- readUInt64LE
- refreshView
- removeColorAtAddress
- removeTagAtAddress
- selectAddressRange
- setColorAtAddress
- setExecutableFilePath
- setNameAtAddress
- setOperandFormat
- tagIterator
- tagIteratorAtAddress
- writeByte
- writeBytes
- writeUInt16BE
- writeUInt16LE
- writeUInt32BE
- writeUInt32LE
- writeUInt64BE
- writeUInt64LE

- Class GlobalInformation

- getHopperMajorVersion
- getHopperMinorVersion
- getHopperRevisionNumber
- getHopperVersion

Here are all the public classes, and methods that you can use to script Hopper using Python.

Before using the scripting capabilities of Hopper, you need to understand the nature of a Hopper document. The basic concept is that it is a document constructed from Segments, each containing Sections of typed bytes. Let's consider a standard Mach-O file. It contains at least one segment of code (usually named TEXT) containing many bytes. Hopper attaches information to each bytes of each segments. At load time, all bytes are set to the type TYPE_UNDEFINED. Then, starting from the entry point, as Hopper follows the program flow it will set instructions to the type TYPE_CODE; if an instruction needs more than one byte, the following are set to TYPE_NEXT.

Using Python, you'll can manipulate the segments of disassembled files, retrieve information on bytes types, read or write data, create or modify label names, etc... You'll usually start by retrieving the current document, using the static method Document.getCurrentDocument().

Class Tag
A Tag that could be applied to a specific address, a BasicBlock or a Procedure. Tags are built using the document.
getName()
Returns a string with the tag name.
Class Procedure
This class represents a procedure, which is a collection of BasicBlocks. Please note that modifying the document (creating new procedure, or deleting an existing one), will result in a possible inconsistancy of the Python's Procedure object representation.
getEntryPoint()
Returns the address of the entry point.
getBasicBlockCount()
Returns the total number of basic blocks.
getBasicBlock(index)
Get a BasicBlock object by index.
getBasicBlockAtAddress(addr)
Returns the basic block which contains an instruction starting at the given address, or None.
getHeapSize()
Returns the heap size of the procedure in bytes.
addTag(tag)
Add a tag to the procedure.
removeTag(tag)
Remove the tag from the procedure.
hasTag(tag)
Returns True if the procedure has this tag.
getTagCount()
Returns the number of tags for this procedure.
getTagAtIndex(index)
Returns the Nth tag of the procedure.
tagIterator()
Iterate over all tags of the procedure
getTagList()
Returns a list a all tags for this procedure.
decompile()
Returns a string containing the pseudo-code of the procedure, or None if the decompilation is not possible.
Class BasicBlock
A BasicBlock is a set of instructions that is guaranteed to be executed in a whole, if the control flow reach the first instruction.
getProcedure()
Returns the Procedure object this BasicBlock belongs to.
getStartingAddress()
Returns the address of the first instruction of the BasicBlock.
getEndingAddress()
Returns the address following the last instruction of the BasicBlock.
getSuccessorCount()
Returns the number of successors for this BasicBlock.
getSuccessorIndexAtIndex(index)
Returns the BasicBlock index of the Nth successors.
getSuccessorAddressAtIndex(index)
Returns the BasicBlock address of the Nth successors.
addTag(tag)
Add a tag to the basic block.
removeTag(tag)
Remove the tag from the basic block.
hasTag(tag)
Returns True if the basic block has this tag.
getTagCount()
Return the number of tags for this basic block.
getTagAtIndex(index)
Return the Nth tag of the basic block.
tagIterator()
Iterate over all tags of the basic block
getTagList()
Return a list a all tags for this basic block.
Class Instruction
This class represents a disassembled instruction. The class defines some constants, like ARCHITECTURE_i386, and ARCHITECTURE_X86_64
stringForArchitecture(t)
[static]
Helper method which converts one of the architecture value (ARCHITECTURE_UNKNOWN, ARCHITECTURE_i386, ARCHITECTURE_X86_64, ARCHITECTURE_ARM, ARCHITECTURE_ARM_THUMB, or ARCHITECTURE_AARCH64) to a string value.
getArchitecture()
Returns the architecture.
getInstructionString()
Return a strings representing the instruction.
getArgumentCount()
Returns the number of argument.
getRawArgument(index)
Returns the instruction argument, identified by an index. The argument is not modified by Hopper, and represents the raw ASM argument.
getFormattedArgument(index)
Returns the instruction argument, identified by an index. The argument may have been modified according to the user, or by Hopper if a specific pattern has been detected.
isAnInconditionalJump()
Returns True if the instruction represents an inconditional jump.
isAConditionalJump()
Returns True if the instruction represents a conditional jump.
getInstructionLength()
Returns the instruction length in byte.
Class Section
This class represents a section of a segment.
getName()
Returns the name of the section.
getStartingAddress()
Returns the starting address of the section.
getLength()
Returns the length, in bytes, of the section.
Class Segment
This class represents a segment of a disassembled file. The class defines some values that are used as the type of bytes of the disassembled file.
TYPE_UNDEFINED : an undefined byte
TYPE_OUTSIDE : the byte is not in a mapped section
TYPE_NEXT : a byte that is part of a larger data type (ex, the second byte of a 4 bytes integer...)
TYPE_BYTE : an integer of a single byte
TYPE_SHORT : an integer of 2 bytes
TYPE_INT : an integer of 4 bytes
TYPE_LONG : an integer of 8 bytes
TYPE_ASCII : an ASCII string
TYPE_UNICODE : an UNICODE string
TYPE_CODE : an instruction
TYPE_PROCEDURE : a procedure
The class defines the constant BAD_ADDRESS which is returned by some methods when the requested information is incorrect.
stringForType(t)
[static]
Helper method that converts one of the type value (TYPE_UNDEFINED, TYPE_NEXT, ...) to a string value.
getName()
Returns the name of the segment.
getStartingAddress()
Returns the starting address of the segment.
getLength()
Returns the length, in bytes, of the segment.
getFileOffset()
Returns the file offset of the beginning of the segment.
getFileOffsetForAddress(addr)
Returns the file offset of a particular address.
getSectionCount()
Returns the number of section this segment contains.
getSection(index)
Returns a section by index. The returned object is an instance of the Section class. If the index of not in the range [0;count[, the function returns None.
getSectionsList()
Returns a list containing all the sections.
readBytes(addr,length)
Read bytes at a given address range. Returns False if the byte is read outside of the segment.
readByte(addr)
Read a byte (between 0..255), read at a given address. Returns False if the byte is read outside of the segment.
readUInt16LE(addr)
Read a 16 bits little endian integer.
readUInt32LE(addr)
Read a 32 bits little endian integer.
readUInt64LE(addr)
Read a 64 bits little endian integer.
readUInt16BE(addr)
Read a 16 bits big endian integer.
readUInt32BE(addr)
Read a 32 bits big endian integer.
readUInt64BE(addr)
Read a 64 bits big endian integer.
writeBytes(addr,bytesStr)
Write bytes at a given address. Bytes are given as a string. Returns True if the writting has succeed.
writeByte(addr,value)
Write a byte at a given address. Returns True if the writting has succeed.
writeUInt16LE(addr,value)
Write a 16 bits little endian integer. Returns True if succeeded.
writeUInt32LE(addr,value)
Write a 32 bits little endian integer. Returns True if succeeded.
writeUInt64LE(addr,value)
Write a 32 bits little endian integer. Returns True if succeeded.
writeUInt16BE(addr,value)
Write a 16 bits big endian integer. Returns True if succeeded.
writeUInt32BE(addr,value)
Write a 32 bits big endian integer. Returns True if succeeded.
writeUInt64BE(addr,value)
Write a 32 bits big endian integer. Returns True if succeeded.
markAsUndefined(addr)
Mark the address as being undefined.
markRangeAsUndefined(addr,length)
Mark the address range as being undefined.
markAsCode(addr)
Mark the address as being code.
markAsProcedure(addr)
Mark the address as being a procedure.
markAsDataByteArray(addr,count)
Mark the address as being byte array.
markAsDataShortArray(addr,count)
Mark the address as being a short array.
markAsDataIntArray(addr,count)
Mark the address as being an int array.
isThumbAtAddress(addr)
Returns True is instruction at address addr is ARM Thumb mode.
setThumbModeAtAddress(addr)
Set the Thumb mode at the given address.
setARMModeAtAddress(addr)
Set the ARM mode at the given address.
getTypeAtAddress(addr)
Returns the type of the byte at a given address. The type can be TYPE_UNDEFINED, TYPE_NEXT, TYPE_BYTE, TYPE_SHORT, TYPE_INT, TYPE_LONG, TYPE_ASCII, TYPE_CODE or TYPE_PROCEDURE. The method will returns None if the address is outside the segment.
setTypeAtAddress(addr,length,typeValue)
Set the type of a byte range. The type must be TYPE_UNDEFINED, TYPE_BYTE, TYPE_SHORT, TYPE_INT, TYPE_LONG or TYPE_ASCII.
getNextAddressWithType(addr,typeValue)
Returns the next address of a given type. The search begins at the given address, so the returned value can be the given address itself. If no address are found, the returned value is BAD_ADDRESS.
disassembleWholeSegment()
Disassemble the whole segment.
setNameAtAddress(addr,name)
Set the label name at a given address.
getNameAtAddress(addr)
Get the label name at a given address.
getCommentAtAddress(addr)
Get the prefix comment at a given address.
setCommentAtAddress(addr,comment)
Set the prefix comment at a given address.
getInlineCommentAtAddress(addr)
Get the inline comment at a given address.
setInlineCommentAtAddress(addr,comment)
Set the inline comment at a given address.
getInstructionAtAddress(addr)
Get the disassembled instruction at a given address.
getReferencesOfAddress(addr)
Get the list of addresses that reference a given address.
getReferencesFromAddress(addr)
Get the list of addresses referenced by a given address.
addReference(addr,referenced)
Add a cross reference to the 'referenced' address from 'addr' address.
removeReference(addr,referenced)
Remove the cross reference to the 'referenced' address from 'addr' address.
getLabelCount()
Get the number of named addresses.
getLabelName(index)
Get a label name by index.
labelIterator()
Iterate over all the labels of a segment.
getLabelsList()
Returns a list with all the label of a segment.
getProcedureCount()
Returns the number of procedures that has been defined in this segment.
getProcedureAtIndex(index)
Returns the Nth Procedure object of the segment.
getProcedureIndexAtAddress(address)
Returns the index of the procedure at a given address of the segment, or -1 if there is no procedure defined there.
getProcedureAtAddress(address)
Returns the Procedure object at a given address of the segment, or None if there is no procedure defined at there.
instructionStart(address)
Return the lowest address value of the instruction found at a particular address. If the given address is in the middle of an instruction, Hopper will look back to find the first byte of this instruction.
Class Document
This class represents the disassembled document. A document is a set of segments.
getCurrentDocument()
[static]
Returns the current document.
ask(msg)
[static]
Open a window containing a text field, and wait for the user to give a string value. Returns the string, or returns None if the Cancel button is hit.
askFile(msg,path,save)
[static]
Open a file dialog with a specified title, in order to select a file. The 'save' parameter allows you to choose between on 'open' or a 'save' dialog.
askDirectory(msg,path)
[static]
Open a file dialog with a specified title, in order to select a directory.
message(msg,buttons)
[static]
Open a window containing a text field and a set of buttons. The 'Buttons' parameter is a list of strings. The function returns the index of the clicked button.
assemble(instr,address,syntax)
Assemble an instruction, and returns the bytes as an array. The instruction is NOT injected in the document: the address given to the function is used to encode the instruction. You wan use the writeByte method to inject an assembled instruction. The first argument is the instruction to be assembled. The second is the address of the instruction. The last parameter is the syntax variant index. For the Intel processor, syntax = 0 for Intel syntax, and 1 for AT&T syntax.
getDatabaseFilePath()
Returns the path of the current Hopper database for this document (the HOP file).
getExecutableFilePath()
Returns the path of the executable being analyzed.
setExecutableFilePath(path)
Set the path of the executable being analyzed.
log(msg)
Display a string message into the log window of the document.
getSegmentCount()
Returns the number of segment the document contains.
getSegment(index)
Returns a segment by index. The returned object is an instance of the Segment class. If the index of not in the range [0;count[, the function returns None.
getSegmentByName(name)
Returns a segment by name. Return None if no segment with this name was found. If multiple segments have this name, the first one is returned.
getSectionByName(name)
Returns a section by name. Return None if no segment with this name was found. If multiple sections have this name, the first one is returned.
getSegmentsList()
Returns a list containing all the segments.
getSegmentIndexAtAddress(addr)
Returns the segment index for a particular address.
getSegmentAtAddress(addr)
Returns the segment for a particular address.
getCurrentSegmentIndex()
Returns the segment index where the cursor is. Returns -1 if the current segment cannot be located.
getCurrentSegment()
Returns the segment where the cursor is. Returns None if the current segment cannot be located.
getCurrentAddress()
Returns the address where the cursor currently is.
getSelectionAddressRange()
Returns a list, containing two addresses. Those address represents the range of bytes covered by the selection.
moveCursorAtAddress(addr)
Move the cursor at a given address.
selectAddressRange(addrRange)
Select a range of byte. The awaited argument is a list containing exactly two address.
getFileOffsetFromAddress(addr)
Returns the file offset corresponding to the given address.
getAddressFromFileOffset(offset)
Returns the address corresponding to the given file offset.
is64Bits()
Returns True if the disassembled document is interpreted as a 64 bits binary.
getEntryPoint()
Returns the entry point of the document.
moveCursorAtEntryPoint()
Move the cursor at the entry point.
getHighlightedWord()
Returns the word that is currently highlighted in the assembly view.
setNameAtAddress(addr,name)
Set the label name at a given address.
getNameAtAddress(addr)
Get the label name at a given address.
getAddressForName(name)
Get the address associated to a given name.
refreshView()
Force the assembly view to be refresh.
moveCursorOneLineDown()
Move the current line down, and remove the multiselection if needed. Returns True if cursor moved.
moveCursorOneLineUp()
Move the current line up, and remove the multiselection if needed. Returns True if cursor moved.
getRawSelectedLines()
Returns a list of strings corresponding to the current selection.
addTagAtAddress(tag,addr)
Add a tag at a particular address.
removeTagAtAddress(tag,addr)
Remove the tag at a particular address.
hasTagAtAddress(tag,addr)
Returns True if the tag is present at this address.
getTagCountAtAddress(addr)
Returns the number of tags at a given address.
getTagAtAddressByIndex(addr,index)
Returns the Nth tag present at a given address.
tagIteratorAtAddress(addr)
Iterates over all tags present at a given address.
getTagListAtAddress(addr)
Returns the list of all tags present at a given address
getTagCount()
Returns the total number of tags available.
getTagAtIndex(index)
Returns a Tag object, or None if the index does not exists.
tagIterator()
Iterate over all the tags.
getTagList()
Returns a list of all tags.
buildTag(name)
Build a tag with a given name. If a tag with the same name already exists, it return the existing tag.
getTagWithName(name)
Returns a Tag object if a tag with this name already exists, or None.
destroyTag(tag)
Remove the tag from every location, and delete it.
hasColorAtAddress(addr)
Returns True if a color has been defined at the given address.
setColorAtAddress(color,addr)
Sets the color at a given address. The color is a 32bits integer representing the hexadecimal color in the form #AARRGGBB.
getColorAtAddress(addr)
Returns the color at a given address. The color is a 32bits integer representing the hexadecimal color in the form #AARRGGBB.
removeColorAtAddress(addr)
Remove the color at a given address.
readBytes(addr,length)
Read bytes from a mapped segment, and return a string. Returns False if no segments was found for this range.
readByte(addr)
Read a byte from a mapped segment. Returns False if no segments was found for this address.
readUInt16LE(addr)
Read a 16 bits little endian integer from a mapped segment. Returns False if no segments was found for this address.
readUInt32LE(addr)
Read a 32 bits little endian integer from a mapped segment. Returns False if no segments was found for this address.
readUInt64LE(addr)
Read a 64 bits little endian integer from a mapped segment. Returns False if no segments was found for this address.
readUInt16BE(addr)
Read a 16 bits big endian integer from a mapped segment. Returns False if no segments was found for this address.
readUInt32BE(addr)
Read a 32 bits big endian integer from a mapped segment. Returns False if no segments was found for this address.
readUInt64BE(addr)
Read a 64 bits bif endian integer from a mapped segment. Returns False if no segments was found for this address.
writeBytes(addr,byteStr)
Write bytes to a mapped segment. Bytes are given as a string. Returns False if no segments was found for this range.
writeByte(addr,value)
Write a byte to a mapped segment. Returns True if succeeded.
writeUInt16LE(addr,value)
Write a 16 bits little endian integer to a mapped segment. Returns True if succeeded.
writeUInt32LE(addr,value)
Write a 32 bits little endian integer to a mapped segment. Returns True if succeeded.
writeUInt64LE(addr,value)
Write a 64 bits little endian integer to a mapped segment. Returns True if succeeded.
writeUInt16BE(addr,value)
Write a 16 bits big endian integer to a mapped segment. Returns True if succeeded.
writeUInt32BE(addr,value)
Write a 32 bits big endian integer to a mapped segment. Returns True if succeeded.
writeUInt64BE(addr,value)
Write a 64 bits big endian integer to a mapped segment. Returns True if succeeded.
getOperandFormat(addr,index)
Returns the format requested by the user for a given intruction operand.
setOperandFormat(addr,index,fmt)
Set the format of a given intruction operand.
Class GlobalInformation
An object containing various information about the current version of Hopper.
getHopperMajorVersion()
[static]
Returns the major version number. If Hopper is at version 4.1.2, it'll return "4".
getHopperMinorVersion()
[static]
Returns the minor version number. If Hopper is at version 4.1.2, it'll return "1".
getHopperRevisionNumber()
[static]
Returns the revision version number. If Hopper is at version 4.1.2, it'll return "2".
getHopperVersion()
[static]
Returns a string with the complete Hopper's version number (ie, something like "4.1.2")