"""
Adapter for bit-integers (converts bitstrings to integers, and vice versa).
See BitField.
-
+
Parameters:
* subcon - the subcon to adapt
* width - the size of the subcon, in bits
- * swapped - whether to swap byte order (little endian/big endian).
+ * swapped - whether to swap byte order (little endian/big endian).
default is False (big endian)
* signed - whether the value is signed (two's complement). the default
is False (unsigned)
default is 8.
"""
__slots__ = ["width", "swapped", "signed", "bytesize"]
- def __init__(self, subcon, width, swapped = False, signed = False,
+ def __init__(self, subcon, width, swapped = False, signed = False,
bytesize = 8):
Adapter.__init__(self, subcon)
self.width = width
"""
Adapter that maps objects to other objects.
See SymmetricMapping and Enum.
-
+
Parameters:
* subcon - the subcon to map
* decoding - the decoding (parsing) mapping (a dict)
if `Pass` is used, the unmapped object will be passed as-is
"""
__slots__ = ["encoding", "decoding", "encdefault", "decdefault"]
- def __init__(self, subcon, decoding, encoding,
+ def __init__(self, subcon, decoding, encoding,
decdefault = NotImplemented, encdefault = NotImplemented):
Adapter.__init__(self, subcon)
self.decoding = decoding
Adapter for flag fields. Each flag is extracted from the number, resulting
in a FlagsContainer object. Not intended for direct usage.
See FlagsEnum.
-
+
Parameters
* subcon - the subcon to extract
* flags - a dictionary mapping flag-names to their value
class StringAdapter(Adapter):
"""
- Adapter for strings. Converts a sequence of characters into a python
+ Adapter for strings. Converts a sequence of characters into a python
string, and optionally handles character encoding.
See String.
-
+
Parameters:
* subcon - the subcon to convert
- * encoding - the character encoding name (e.g., "utf8"), or None to
+ * encoding - the character encoding name (e.g., "utf8"), or None to
return raw bytes (usually 8-bit ASCII).
"""
__slots__ = ["encoding"]
r"""
Adapter for padded strings.
See String.
-
+
Parameters:
* subcon - the subcon to adapt
- * padchar - the padding character. default is "\x00".
- * paddir - the direction where padding is placed ("right", "left", or
- "center"). the default is "right".
- * trimdir - the direction where trimming will take place ("right" or
+ * padchar - the padding character. default is b"\x00".
+ * paddir - the direction where padding is placed ("right", "left", or
+ "center"). the default is "right".
+ * trimdir - the direction where trimming will take place ("right" or
"left"). the default is "right". trimming is only meaningful for
- building, when the given string is too long.
+ building, when the given string is too long.
"""
__slots__ = ["padchar", "paddir", "trimdir"]
- def __init__(self, subcon, padchar = "\x00", paddir = "right",
+ def __init__(self, subcon, padchar = b"\x00", paddir = "right",
trimdir = "right"):
if paddir not in ("right", "left", "center"):
- raise ValueError("paddir must be 'right', 'left' or 'center'",
+ raise ValueError("paddir must be 'right', 'left' or 'center'",
paddir)
if trimdir not in ("right", "left"):
raise ValueError("trimdir must be 'right' or 'left'", trimdir)
class LengthValueAdapter(Adapter):
"""
- Adapter for length-value pairs. It extracts only the value from the
+ Adapter for length-value pairs. It extracts only the value from the
pair, and calculates the length based on the value.
See PrefixedArray and PascalString.
-
+
Parameters:
* subcon - the subcon returning a length-value pair
"""
class CStringAdapter(StringAdapter):
r"""
Adapter for C-style strings (strings terminated by a terminator char).
-
+
Parameters:
* subcon - the subcon to convert
- * terminators - a sequence of terminator chars. default is "\x00".
+ * terminators - a sequence of terminator chars. default is b"\x00".
* encoding - the character encoding to use (e.g., "utf8"), or None to
- return raw-bytes. the terminator characters are not affected by the
+ return raw-bytes. the terminator characters are not affected by the
encoding.
"""
__slots__ = ["terminators"]
to parse that data (bottom-up). For building it works in a top-down manner;
first the upper layer builds the data, then the lower layer takes it and
writes it to the stream.
-
+
Parameters:
* subcon - the lower layer subcon
* inner_subcon - the upper layer (tunneled/nested) subcon
-
+
Example:
# a pascal string containing compressed data (zlib encoding), so first
# the string is read, decompressed, and finally re-parsed as an array
class ExprAdapter(Adapter):
"""
A generic adapter that accepts 'encoder' and 'decoder' as parameters. You
- can use ExprAdapter instead of writing a full-blown class when only a
+ can use ExprAdapter instead of writing a full-blown class when only a
simple expression is needed.
-
+
Parameters:
* subcon - the subcon to adapt
- * encoder - a function that takes (obj, context) and returns an encoded
+ * encoder - a function that takes (obj, context) and returns an encoded
version of obj
- * decoder - a function that takes (obj, context) and returns an decoded
+ * decoder - a function that takes (obj, context) and returns an decoded
version of obj
-
+
Example:
- ExprAdapter(UBInt8("foo"),
+ ExprAdapter(UBInt8("foo"),
encoder = lambda obj, ctx: obj / 4,
decoder = lambda obj, ctx: obj * 4,
)
"""
Adapter for enforcing a constant value ("magic numbers"). When decoding,
the return value is checked; when building, the value is substituted in.
-
+
Parameters:
* subcon - the subcon to validate
* value - the expected value
-
+
Example:
Const(Field("signature", 2), "MZ")
"""
class SlicingAdapter(Adapter):
"""
Adapter for slicing a list (getting a slice from that list)
-
+
Parameters:
* subcon - the subcon to slice
* start - start index
class IndexingAdapter(Adapter):
"""
Adapter for indexing a list (getting a single item from that list)
-
+
Parameters:
* subcon - the subcon to index
* index - the index of the list to get
class PaddingAdapter(Adapter):
r"""
Adapter for padding.
-
+
Parameters:
* subcon - the subcon to pad
* pattern - the padding pattern (character as byte). default is b"\x00"
- * strict - whether or not to verify, during parsing, that the given
+ * strict - whether or not to verify, during parsing, that the given
padding matches the padding pattern. default is False (unstrict)
"""
__slots__ = ["pattern", "strict"]
#===============================================================================
class Validator(Adapter):
"""
- Abstract class: validates a condition on the encoded/decoded object.
+ Abstract class: validates a condition on the encoded/decoded object.
Override _validate(obj, context) in deriving classes.
-
+
Parameters:
* subcon - the subcon to validate
"""
projects / pyelftools.git / commitdiff