languagerepresentation module

binaryninja.languagerepresentation.CoreLanguageRepresentationFunctionType(handle)
binaryninja.languagerepresentation.HighLevelILTokenEmitter(handle)	class HighLevelILTokenEmitter contains methods for emitting text tokens for High Level IL instructions.
binaryninja.languagerepresentation.LanguageRepresentationFunction([...])	class LanguageRepresentationFunction represents a single function in a registered high level language.
binaryninja.languagerepresentation.LanguageRepresentationFunctionType([...])	class LanguageRepresentationFunctionType represents a custom language representation function type.

class CoreLanguageRepresentationFunctionType(handle: LP_BNLanguageRepresentationFunctionType)

Bases: LanguageRepresentationFunctionType

Parameters:

handle (LP_BNLanguageRepresentationFunctionType) –

create(arch: Architecture, owner: Function, hlil: HighLevelILFunction) → LanguageRepresentationFunction

This method must be overridden. This creates the class LanguageRepresentationFunction object for the given architecture, owner function, and High Level IL function.

Parameters:

• arch (Architecture) –

• owner (Function) –

• hlil (HighLevelILFunction) –

Return type:

LanguageRepresentationFunction

function_type_tokens(func: Function, settings: DisassemblySettings | None) → List[DisassemblyTextLine]

Returns a list of lines representing a function prototype in this language. If no lines are returned, the default C-style prototype will be used.

Parameters:

• func (Function) –

• settings (DisassemblySettings | None) –

Return type:

List[DisassemblyTextLine]

is_valid(view: BinaryView) → bool

Returns whether the language is valid for the given binary view.

Parameters:

view (BinaryView) –

Return type:

bool

property type_parser: TypeParser | None

Returns the type parser for parsing types in this language. If None is returned, the default type parser will be used.

property type_printer: TypePrinter | None

Returns the type printer for displaying types in this language. If None is returned, the default type printer will be used.

class HighLevelILTokenEmitter(handle: LP_BNHighLevelILTokenEmitter)

Bases: object

class HighLevelILTokenEmitter contains methods for emitting text tokens for High Level IL instructions. Methods are provided for typical patterns found in various high level languages.

This class cannot be instantiated directly. An instance of the class will be provided when the methods in class LanguageRepresentationFunction are called.

Parameters:

handle (LP_BNHighLevelILTokenEmitter) –

class ExprContext(emitter: HighLevelILTokenEmitter, hlil_expr: HighLevelILInstruction)

Bases: object

class ExprContext is a context manager that associates the tokens inside the context with the given High Level IL expression.

Parameters:

• emitter (HighLevelILTokenEmitter) –

• hlil_expr (HighLevelILInstruction) –

class ZeroConfidenceContext(emitter: HighLevelILTokenEmitter, enabled: bool)

Bases: object

class ZeroConfidenceContext is a context manager that optionally forces tokens to be of zero confidence inside the context.

Parameters:

• emitter (HighLevelILTokenEmitter) –

• enabled (bool) –

append(tokens: InstructionTextToken | List[InstructionTextToken])

Appends a token or list of tokens to the output.

Parameters:

tokens (InstructionTextToken | List[InstructionTextToken]) –

append_array_index_token(instr: HighLevelILInstruction, value: int, size: int, address: int = 0)

Appends tokens for accessing an array by index.

Parameters:

• instr (HighLevelILInstruction) –

• value (int) –

• size (int) –

• address (int) –

append_close_brace()

Appends a close brace (}) to the output.

append_close_bracket()

Appends a close bracket (]) to the output.

append_close_paren()

Appends a close parenthesis (``)``) to the output.

append_constant_text_token(instr: HighLevelILInstruction, value: int, size: int, settings: DisassemblySettings | None, precedence: OperatorPrecedence)

Appends tokens for a constant value.

Parameters:

• instr (HighLevelILInstruction) –

• value (int) –

• size (int) –

• settings (DisassemblySettings | None) –

• precedence (OperatorPrecedence) –

append_float_size_token(size: int, token_type: InstructionTextTokenType)

Appends a floating point size token for the given size in the High Level IL syntax.

Parameters:

• size (int) –

• token_type (InstructionTextTokenType) –

append_integer_text_token(instr: HighLevelILInstruction, value: int, size: int)

Appends tokens for a constant intenger value.

Parameters:

• instr (HighLevelILInstruction) –

• value (int) –

• size (int) –

append_open_brace()

Appends an open brace ({) to the output.

append_open_bracket()

Appends an open bracket ([) to the output.

append_open_paren()

Appends an open parenthesis (() to the output.

append_pointer_text_token(instr: HighLevelILInstruction, value: int, settings: DisassemblySettings | None, symbol_display: SymbolDisplayType, precedence: OperatorPrecedence, allow_short_string: bool = False) → SymbolDisplayResult

Appends tokens for displaying a constant pointer value.

Parameters:

• instr (HighLevelILInstruction) –

• value (int) –

• settings (DisassemblySettings | None) –

• symbol_display (SymbolDisplayType) –

• precedence (OperatorPrecedence) –

• allow_short_string (bool) –

Return type:

SymbolDisplayResult

append_semicolon()

Appends a semicolon (;) to the output.

append_size_token(size: int, token_type: InstructionTextTokenType)

Appends a size token for the given size in the High Level IL syntax.

Parameters:

• size (int) –

• token_type (InstructionTextTokenType) –

append_var_text_token(var: CoreVariable, instr: HighLevelILInstruction, size: int)

Appends tokens for access to a variable.

Parameters:

• var (CoreVariable) –

• instr (HighLevelILInstruction) –

• size (int) –

begin_scope(scope_type: ScopeType)

Begins a new scope. Insertion of newlines and braces will be handled using the current settings.

Parameters:

scope_type (ScopeType) –

decrease_indent()

Decreases the indentation level by one.

end_scope(scope_type: ScopeType)

Ends the current scope.

Parameters:

scope_type (ScopeType) –

expr(hlil_expr: HighLevelILInstruction) → ExprContext

Returns a context manager that associates the tokens inside the context with the given High Level IL expression.

Parameters:

hlil_expr (HighLevelILInstruction) –

Return type:

ExprContext

finalize()

Finalizes all tokens in the output.

finalize_scope()

Finalizes the previous scope, indicating that there are no more associated scopes.

force_zero_confidence(enabled: bool = True) → ZeroConfidenceContext

Returns a context manager that forces tokens inside of it to be of zero confidence. If False is passed to this method, the context has no effect, allowing the caller to conditionally apply this behavior.

Parameters:

enabled (bool) –

Return type:

ZeroConfidenceContext

increase_indent()

Increases the indentation level by one.

static names_for_outer_structure_members(view: BinaryView, struct_type: Type, var: HighLevelILInstruction) → List[str]

Gets the list of names for the outer structure members when accessing a structure member. This list can be passed for the typeNames parameter of the class InstructionTextToken constructor.

Parameters:

• view (BinaryView) –

• struct_type (Type) –

• var (HighLevelILInstruction) –

Return type:

List[str]

new_line()

Starts a new line in the output.

no_indent_for_this_line()

Forces there to be no indentation for the next line.

scope_continuation(force_same_line: bool)

Continues the previous scope with a new associated scope. This is most commonly used for else statements.

Parameters:

force_same_line (bool) –

scope_separator()

Indicates that visual separation of scopes is desirable at the current position. By default, this will insert a blank line, but this can be configured by the user.

property brace_requirement: BraceRequirement

The requirement for insertion of braces around scopes in the output.

property braces_around_switch_cases

Whether cases within switch statements should always have braces around them.

property current_tokens: List[InstructionTextToken]

The list of tokens on the current line (read-only).

property default_braces_on_same_line

Whether braces should default to being on the same line as the statement that begins the scope. If the user has explicitly set a preference, this setting will be ignored and the user’s preference will be used instead.

property lines: List[DisassemblyTextLine]

The list of lines in the output (read-only).

property simple_scope_allowed

Whether omitting braces around single-line scopes is allowed.

class LanguageRepresentationFunction(arch: Architecture | None = None, owner: Function | None = None, hlil: HighLevelILFunction | None = None, handle=None)

Bases: object

class LanguageRepresentationFunction represents a single function in a registered high level language.

Parameters:

• arch (Architecture | None) –

• owner (Function | None) –

• hlil (HighLevelILFunction | None) –

get_block_lines(block: HighLevelILBasicBlock, settings: DisassemblySettings | None = None) → List[DisassemblyTextLine]

Generates lines for a single High Level IL basic block.

Parameters:

• block (HighLevelILBasicBlock) –

• settings (DisassemblySettings | None) –

Return type:

List[DisassemblyTextLine]

get_expr_text(instr: HighLevelILInstruction, settings: DisassemblySettings | None, as_full_ast: bool = True, precedence: OperatorPrecedence = OperatorPrecedence.TopLevelOperatorPrecedence, statement: bool = False) → List[DisassemblyTextLine]

Gets the lines of tokens for a given High Level IL instruction.

Parameters:

• instr (HighLevelILInstruction) –

• settings (DisassemblySettings | None) –

• as_full_ast (bool) –

• precedence (OperatorPrecedence) –

• statement (bool) –

Return type:

List[DisassemblyTextLine]

get_linear_lines(instr: HighLevelILInstruction, settings: DisassemblySettings | None = None, as_full_ast: bool = True) → List[DisassemblyTextLine]

Generates lines for the given High Level IL instruction in the style of the linear view. To get the lines for the entire function, pass the root property of a class HighLevelILFunction.

Parameters:

• instr (HighLevelILInstruction) –

• settings (DisassemblySettings | None) –

• as_full_ast (bool) –

Return type:

List[DisassemblyTextLine]

perform_begin_lines(instr: HighLevelILInstruction, tokens: HighLevelILTokenEmitter)

This method can be overridden to emit tokens at the start of a function.

Parameters:

• instr (HighLevelILInstruction) –

• tokens (HighLevelILTokenEmitter) –

perform_end_lines(instr: HighLevelILInstruction, tokens: HighLevelILTokenEmitter)

This method can be overridden to emit tokens at the end of a function.

Parameters:

• instr (HighLevelILInstruction) –

• tokens (HighLevelILTokenEmitter) –

perform_get_expr_text(instr: HighLevelILInstruction, tokens: HighLevelILTokenEmitter, settings: DisassemblySettings | None, as_full_ast: bool = True, precedence: OperatorPrecedence = OperatorPrecedence.TopLevelOperatorPrecedence, statement: bool = False)

This method must be overridden by all language representation plugins.

This method is called to emit the tokens for a given High Level IL instruction.

Parameters:

• instr (HighLevelILInstruction) –

• tokens (HighLevelILTokenEmitter) –

• settings (DisassemblySettings | None) –

• as_full_ast (bool) –

• precedence (OperatorPrecedence) –

• statement (bool) –

perform_init_token_emitter(emitter: HighLevelILTokenEmitter)

Override this method to initialize the options for the token emitter before it is used.

Parameters:

emitter (HighLevelILTokenEmitter) –

annotation_end_string = '}'

annotation_start_string = '{'

property arch: Architecture

comment_end_string = ''

comment_start_string = '// '

property function: Function

property high_level_il: HighLevelILFunction

property hlil: HighLevelILFunction

class LanguageRepresentationFunctionType(handle=None)

Bases: object

class LanguageRepresentationFunctionType represents a custom language representation function type. This class provides methods to create class LanguageRepresentationFunction instances for functions, as well as manage the printing and parsing of types.

create(arch: Architecture, owner: Function, hlil: HighLevelILFunction) → LanguageRepresentationFunction

This method must be overridden. This creates the class LanguageRepresentationFunction object for the given architecture, owner function, and High Level IL function.

Parameters:

• arch (Architecture) –

• owner (Function) –

• hlil (HighLevelILFunction) –

Return type:

LanguageRepresentationFunction

function_type_tokens(func: Function, settings: DisassemblySettings | None) → List[DisassemblyTextLine]

Returns a list of lines representing a function prototype in this language. If no lines are returned, the default C-style prototype will be used.

Parameters:

• func (Function) –

• settings (DisassemblySettings | None) –

Return type:

List[DisassemblyTextLine]

is_valid(view: BinaryView) → bool

Returns whether the language is valid for the given binary view.

Parameters:

view (BinaryView) –

Return type:

bool

register()

Registers the language representation function type.

language_name = None

property name: str

property type_parser: TypeParser | None

Returns the type parser for parsing types in this language. If None is returned, the default type parser will be used.

property type_printer: TypePrinter | None

Returns the type printer for displaying types in this language. If None is returned, the default type printer will be used.