Module pychrysalide.glibext
Interface ComparableItem
Interface LineGenerator
Interface SingletonCandidate
Class BinPortion
Class BinaryCursor
Class BufferCache
Class BufferLine
Class ConfigParam
Class ConfigParamIterator
Class GenConfig
Class LineCursor
Class SingletonFactory
Module pychrysalide.glibext
Documentation
This module contains the definition of some objects derived from the GObject structure.
These common objects are used in several places inside Chrysalide and could be seen as extensions to the GLib API.
Interfaces
Classes
- BinPortion
- BinaryCursor
- BufferCache
- BufferLine
- ConfigParam
- ConfigParamIterator
- GenConfig
- LineCursor
- SingletonFactory
Interface ComparableItem
ComparableItem provides an interface to compare objects.
A typical class declaration for a new implementation looks like:
class NewImplem(GObject.Object, ComparableItem):
...
The object can be compared using rich methods (like <=
or !=
).
Hierarchy
gobject.GInterface ╰── pychrysalide.glibext.ComparableItem
Direct implementation: pychrysalide.analysis.scan.ScanExpression
Constants
RichCmpOperation
Modes for objects comparison.
1 | = 1 |
2 | = 2 |
4 | = 4 |
Interface LineGenerator
LineGenerator gives an interface to all objects which aim to produce content for rendering lines. Such lines can be exported to graphical interfaces or text files.
A typical class declaration for a new implementation looks like:
class NewImplem(GObject.Object, LineGenerator):
...
The following methods have to be defined for new implementations:
Hierarchy
gobject.GInterface ╰── pychrysalide.glibext.LineGenerator
Direct implementations:
- pychrysalide.analysis.db.items.DbComment
- pychrysalide.arch.ArchInstruction
- pychrysalide.format.BinSymbol
- pychrysalide.glibext.BinPortion
Methods
_compute_cursor(self, x, index, repeat)
Abstract method used to create a new cursor for a given location inside displayed lines.
The position on the horizontal axis, the line index and the number of repetitions (only relevant if the generator produces several lines) give indications about the active position.
The result has to be a LineCursor
instance.
_contain_cursor(self, index, repeat, cursor)
Abstract method used to check the position of a cursor in relation to rendering lines.
The line index and the number of repetitions (only relevant if the generator produces several lines) give indications about the active position. The cursor is a LineCursor
instance.
The result has to be an integer less than, equal to, or greater than zero if the cursor is, respectively, before, inside or after the area covered by the generator.
_count_lines(self)
Abstract method used to count the number of lines produced by the current generator.
_get_flags(self, index, repeat)
Abstract method used to provide flags for a given rendering line.
The line index and the number of repetitions (only relevant if the generator produces several lines) give indications about the active position.
The result has to be a BufferLineFlags
value.
_print(self, line, index, repeat, content)
Abstract method used to generate content into a rendering line, which is a provided BufferLine
instance.
The line index and the number of repetitions (only relevant if the generator produces several lines) give indications about the current rendering position.
If set, the content is a BinContent
instance providing access to the processed binary data.
compute_cursor(self, x, index, repeat)
Create a a new cursor for a given location inside displayed lines.
The position on the horizontal axis, the line index and the number of repetitions (only relevant if the generator produces several lines) give indications about the active position.
The result has to be a LineCursor
instance.
contain_cursor(self, index, repeat, cursor)
Check the position of a cursor in relation to rendering lines.
The line index and the number of repetitions (only relevant if the generator produces several lines) give indications about the active position. The cursor is a LineCursor
instance.
The result has to be an integer less than, equal to, or greater than zero if the cursor is, respectively, before, inside or after the area covered by the generator.
get_flags(self, index, repeat)
Get the flags of a given position from the generator.
The line index and the number of repetitions (only relevant if the generator produces several lines) give indications about the active position.
The result is a BufferLineFlags
value.
print(self, line, index, repeat, content)
Produce output into a rendering line with optional content.
The provided line is a BufferLine
instance. The index and the number of repetitions (only relevant if the generator produces several lines) give indications about the current rendering position.
If set, the content is a BinContent
instance providing access to the processed binary data.
Attributes
lines_count
Quantity of lines produced by the generator.
This number may vary between calls, if a width has changed for instance.
Interface SingletonCandidate
The SingletonCandidate class is a required interface for objects aiming at becoming singleton instances. All shared singletons are registered within a SingletonFactory
object.
The main implemantations come with types derived from DataType
.
A typical class declaration for a new implementation looks like:
class NewImplem(GObject.Object, SingletonCandidate):
...
The following methods have to be defined for new implementations:
_list_inner_instances()
;_update_inner_instances()
;__hash__()
;__eq__()
;_set_read_only()
;_is_read_only()
.
The object can be compared using rich methods (like <=
or !=
).
Hierarchy
gobject.GInterface ╰── pychrysalide.glibext.SingletonCandidate
Direct implementation: pychrysalide.arch.ArchOperand
Methods
__hash__(self)
Abstract method used to produce a hash of the object.
The result must be an integer value up to 64 bits.
Inner instances which are listed through the _list_inner_instances()
method do not need to get processed here as they are handled automatically by the interface core.
_is_read_only(self)
Abstract method used to retrieve the status of the data contained by a singleton candidate.
The retured value is True
if the candidate is registered inside a SingletonFactory
instance as official singleton, False
otherwise.
_list_inner_instances(self)
Provide an internal access to the list of optional internal singleton candidate instances.
The result has to be a tuple containing zero or more SingletonCandidate
instances.
_set_read_only(self)
Abstract method used to mark the content of a singleton candidate as read-only.
The read-only state is mandatory once the candidate is registered inside a SingletonFactory
instance as official singleton.
_update_inner_instances(self, instances)
Update the list of internal singleton candidate instances.
The provided instances
are a tuple of SingletonCandidate
objets promoted as singletons.
hash(self)
Compute the hash value of the singleton candidate.
The method relies on the interface core to include in the process the optional embedded instances which may become singletons.
The result is an integer value.
Even if the Python hash()
method, relying on the __hash__()
implementation, provides values up to 64 bits, the final hashes processed by the native GLib hash methods are limited to 32 bits values.
Attributes
inner_instances
List of optional internal singleton candidate instances.
The result has to be a tuple containing zero or more SingletonCandidate
instances.
read_only
State of the singleton candidate content.
The result is a boolean: True
if the object is registered as singleton, False
otherwise.
Once a singleton, the object must not change its content as it is a shared instance.
Class BinPortion
The BinPortion object handles parts of binaries usually formally identified in binary formats, like program segments or sections for ELF files for example.
Instances can be created using the following constructor:
BinPortion(code, addr, size)
Where code is the CSS class style for the rendering color to use, addr is the starting point of the portion in memory, as a vmpa
value, and size is the size of the portion.
The object can be compared using rich methods (like <=
or !=
).
Hierarchy
builtins.object ╰── gi._gi.GObject ╰── pychrysalide.glibext.BinPortion
Implements: pychrysalide.glibext.LineGenerator
Methods
include(self, sub)
Include another binary portion as a child item.
The sub portion has to be a BinPortion
instance.
limit_range(self, max)
Ensure the portion range does not cross a boundary size.
An integer value is expected as the maximum size of the portion.
A boolean value indicating the success of the operation is returned.
Attributes
continuation
Tell if the current portion is a continuation of another one.
If a section belongs to several parents, it is cut into several parts when included in the portion tree.
desc
Human description for the binary portion, as a simple string.
range
Area covered by the binary portion.
This property is a mrange
instance.
rights
Access rights declared for the binary portion, as a PortionAccessRights
value.
Constants
BinaryPortionCode
Selector names for the CSS rendering.
RAW | = "binportion-raw" |
CODE | = "binportion-code" |
DATA | = "binportion-data" |
DATA_RO | = "binportion-data-ro" |
DISASS_ERROR | = "binportion-disassembly-error" |
PortionAccessRights
Access rights for binary portions.
0 | = 0 |
1 | = 1 |
2 | = 2 |
4 | = 4 |
7 | = 7 |
Class BinaryCursor
BinaryCursor handles a position into a disassembly view.
Instances can be created using the following constructor:
BinaryCursor()
Hierarchy
builtins.object ╰── gi._gi.GObject ╰── pychrysalide.glibext.LineCursor ╰── pychrysalide.glibext.BinaryCursor
Methods
retrieve(self)
Retrieve the location of the cursor.
The result is provided as a vmpa
instance.
update(self, addr)
Update the location of the cursor.
The addr
argument must be able to get converted into a vmpa
instance.
Attributes
raw
Type of rendering in the status bar for the binary location.
Class BufferCache
The BufferCache object manages a group of lines intended to get printed onto the screen or into a file.
These lines are cached and rebuilt when needed.
Instances can be created using the following constructor:
BufferCache(content=None)
Where content is a BinContent
instance, if defined. This content is provided to lines as argument when the lines get printed, so it may not be always useful and thus can be discarded when creating a new buffer cache.
Hierarchy
builtins.object ╰── gi._gi.GObject ╰── pychrysalide.glibext.BufferCache
Methods
add_line_flag(self, index, flag)
Add one optional flag to those assigned to a given buffer line. The line is located using the index
argument.
The index
has to be a simple integer, and the flag
a BufferLineFlags
value.
An write access lock has to be held for the cache; see the lock()
function.
append(self, generator, flags=0)
Append a new line at the end of a buffer cache.
The content generator for this new line is a LineGenerator
instance. Nominal properties can be set for the line as extra BufferLineFlags
values.
An write access lock has to be held for the cache; see the lock()
function.
delete_at(self, index)
Delete the line at the index
position from a buffer cache.
An write access lock has to be held for the cache; see the lock()
function.
delete_type_at(self, index, gtype, before=False, after=False)
Delete the first generator of a given type found inside a line of a buffer cache.
The target type has to be a gobject.GType, usually provided by the __gtype__
attribute of a generator interface. The generator is deleted from the line at, before or after the provided index.
The function returns the deleted generator as a LineGenerator
instance, or None if none found.
An write access lock has to be held for the cache; see the lock()
function.
extend_with(self, count, generator)
Extend the buffer cache so it will contain count
lines.
The count
number should be greater than the current line quantity, otherwise the call makes no sense. The generator is a LineGenerator
instance used to produce the extra new lines on demand.
An write access lock has to be held for the cache; see the lock()
function.
get_line_flags(self, index)
Provide the optional flags assigned to a given buffer line. The line is located using the index
argument.
The result is a BufferLineFlags
value.
An read access lock has to be held for the cache; see the lock()
function.
insert_at(self, index, generator, flags=0, before=False, after=False)
Add an extra content generator to a given line.
The new content generator for the line at, before or after the provided index is a LineGenerator
instance. Nominal properties can be set for this line as extra BufferLineFlags
values.
An write access lock has to be held for the cache; see the lock()
function.
lock(self, write=False)
Lock for access the content of a buffer cache instance.
The write
parameter is a boolean value which has to be set if the access to perform will modify the buffer cache.
Each call of this method has to followed by a call to unlock()
, with the same write
parameter.
look_for_flag(self, index, flag)
Iterate the buffer cache lines from a starting index until a line with flags matching the provided flag is met.
The flag
argument has to be a BufferLineFlags
value.
The result is an index equal or greater than the starting index or, if no match is found, the number of lines in the buffer cache.
An read access lock has to be held for the cache; see the lock()
function.
remove_line_flag(self, index, flag)
Remove one optional flag from those assigned to a given buffer line. The line is located using the index
argument.
The index
has to be a simple integer, and the flag
a BufferLineFlags
value.
An write access lock has to be held for the cache; see the lock()
function.
truncate(self, max)
Shrink the buffer cache so it will contain at most max
lines.
The max
number should be lesser than the current line quantity, otherwise no effect will happen.
An write access lock has to be held for the cache; see the lock()
function.
unlock(self, write=False)
Unlock the content of a buffer cache instance.
The write
parameter is a boolean value which has to be set if the performed access has modified the buffer cache.
Attributes
content
Binary content linked to the buffer cache, as a BinContent
instance, or None.
left_margin
Width of the left margin inside of a buffer cache output.
line_height
Height of a line printed from the buffer cache.
lines_count
Count the number of lines contained in a buffer cache.
An read access lock has to be held for the cache; see the lock()
function.
text_position
Starting position of the text on the left of a buffer cache output.
Class BufferLine
The BufferLine object is used to display processed data: disassembled instruction, binary content in hexadecimal form, aso.
Instances can be created using the following constructor:
BufferLine()
Such objets aim to be created from the Chrysalide core only, and then get populated on demand. Thus, these lines can be viewed as cached lines and their properties have to be set through the BufferCache
instance which contains them.
Hierarchy
builtins.object ╰── gi._gi.GObject ╰── pychrysalide.glibext.BufferLine
Methods
append_text(self, column, text, tag, creator=None)
Append some text to a line at a given column index. The expected rendering for this text is defined by the tag, which must be a RenderingTagType
value.
An optional GObject instance may be provided as origin of the creation.
get_text(self, first_col, last_col, markup)
Provide the text of a buffer line.
Attributes
flags
ent flags of the buffer line.
Constants
BufferLineFlags
Optional flags linked to a rendering line.
1 | = 0x1 |
2 | = 0x2 |
4 | = 0x4 |
8 | = 0x8 |
16 | = 0x10 |
RenderingTagType
Kinds of text rendering.
0 | = 0 |
1 | = 1 |
2 | = 2 |
3 | = 3 |
4 | = 4 |
5 | = 5 |
6 | = 6 |
7 | = 7 |
8 | = 8 |
9 | = 9 |
10 | = 10 |
11 | = 11 |
12 | = 12 |
13 | = 13 |
14 | = 14 |
15 | = 15 |
16 | = 16 |
17 | = 17 |
18 | = 18 |
19 | = 19 |
20 | = 20 |
21 | = 21 |
22 | = 22 |
23 | = 23 |
24 | = 24 |
25 | = 25 |
26 | = 26 |
27 | = 27 |
28 | = 28 |
Class ConfigParam
ConfigParam holds a configuration parameter with its default and current values.
Parameters are aimed to join a GenConfig
instance.
Instances can be created using the following constructor:
ConfigParam(path, type, value=None)
Where path
is dot separated string items serving as a parameter key, type
is a ConfigParamType
value and value
is an optional default value if the parameter initial value has not to be empty.
Hierarchy
builtins.object ╰── gi._gi.GObject ╰── pychrysalide.glibext.ConfigParam
Methods
make_empty(self)
Unset the value of the current parameter.
reset(self)
Reset the content of the current parameter.
Attributes
path
Dot separated string items used as key for a configuration parameter.
state
State of a configuration parameter.
The attribute carries a ConfigParamState
value.
type
Type of value provided by a configuration parameter.
The attribute carries a ConfigParamType
value.
value
Value of a configuration parameter.
The type of the value carried by the attribute depends on type
value.
Constants
ConfigParamState
States of a value carried by a configuration parameter.
1 | = 1 |
2 | = 2 |
4 | = 4 |
ConfigParamType
Kind of value available for configuration parameter types.
0 | = 0 |
1 | = 1 |
2 | = 2 |
3 | = 3 |
4 | = 4 |
5 | = 5 |
Class ConfigParamIterator
ConfigParamIterator is an iterator for configuration parameters.
This kind of iterator is provided by the params
attribute.
Hierarchy
builtins.object ╰── pychrysalide.glibext.ConfigParamIterator
Methods
__iter__(self)
Implement iter(self).
__next__(self)
Implement next(self).
Class GenConfig
The GenConfig class defines a generic way to load, provide and store configuration items. Each of these items is handled with a ConfigParam
object.
Instances can be created using the following constructor:
GenConfig(name=None)
Where name
is a suitable storage filename for the configuration. If no name
is defined, the configuration is expected to be memory-only resident.
Hierarchy
builtins.object ╰── gi._gi.GObject ╰── pychrysalide.glibext.GenConfig
Methods
add(self, param, lock=True)
Add an existing parameter to a configuration.
The param
argument has to be a ConfigParam
instance. The lock
boolean value is an optional order handling the way configuration parameters are accessed.
The configuration has to be locked while accessing its content. This lock can be managed with the lock
argument of this function or thanks to the lock_unlock
method().
The returned value is a ConfigParam
instance in case of success or None if the parameter already exists in the configuration.
delete(self, path)
Delete an existing parameter from a configuration.
The path
argument is a string used as key pointing to the parameter to process.
lock_unlock(self, write, lock)
Lock or unlock access to the configuration internals.
The write
argument states if the operation targets read or write accesses, and the lock
value defines the state to achieve.
Both arguments are boolean values.
read(self)
Read the configuration from its relative XML file.
The returned value is True if the operation terminated with success, or False in case of failure.
search(self, path, lock=True)
Look for a given configuration parameter.
The path
argument is a string used as key pointing to a parameter. The lock
boolean value is an optional order handling the way configuration parameters are accessed.
The configuration has to be locked while accessing its content. This lock can be managed with the lock
argument of this function or thanks to the lock_unlock
method().
The returned value is a ConfigParam
instance in case of success or None if the parameter is not found.
write(self)
Write the configuration to its relative XML file.
The returned value is True if the operation terminated with success, or False in case of failure.
Attributes
filename
Path to the file used as storage backend for the configuration.
The result is a string pointing to a file which may not (yet) exist or None if not defined.
params
List of all registered configuration parameters.
The result is a ConfigParamIterator
over ConfigParam
instances.
Class LineCursor
PyChrysalide line cursor
Hierarchy
builtins.object ╰── gi._gi.GObject ╰── pychrysalide.glibext.LineCursor
Known subclass: pychrysalide.glibext.BinaryCursor
Attributes
label
l for the current state of a line cursor.
valid
dity status of the line cursor.
Class SingletonFactory
The SingletonFactory class reduces the memory footprint by compacting the quantity of running instances of a given GLib type.
Instances can be created using the following constructor:
SingletonFactory()
The first processed instance defines the type handled by the factory.
Hierarchy
builtins.object ╰── gi._gi.GObject ╰── pychrysalide.glibext.SingletonFactory
Methods
get_instance(self, candidate)
Provide the unique instance for a given singleton candidate
.
The candidate
object and the result of the function belong to the same type: SingletonCandidate
.