claripy.ast.base.Base

class documentation

class Base: (source)

Known subclasses: claripy.ast.bits.Bits, claripy.ast.bool.Bool, claripy.ast.int.Int

This is the base class of all claripy ASTs. An AST tracks a tree of operations on arguments. This class should not be instanciated directly - instead, use one of the constructor functions (BVS, BVV, FPS, FPV...) to construct a leaf node and then build more complicated expressions using operations. AST objects have *hash identity*. This means that an AST that has the same hash as another AST will be the *same* object. This is critical for efficient memory usage. As an example, the following is true:: a, b = two different ASTs c = b + a d = b + a assert c is d :ivar op: The operation that is being done on the arguments :ivar args: The arguments that are being used

Class Method	`__init_with_annotations__`	Undocumented
Method	`__a_init__`	Initializes an AST. Takes the same arguments as ``Base.__new__()``
Method	`__bool__`	This prevents people from accidentally using an AST as a condition. For example, the following was previously common::
Method	`__getattr__`	Undocumented
Method	`__hash__`	Undocumented
Method	`__init__`	Undocumented
Method	`__iter__`	This prevents people from iterating over ASTs.
Method	`__new__`	This is called when you create a new Base object, whether directly or through an operation. It finalizes the arguments (see the _finalize function, above) and then computes a hash. If an AST of this hash already exists, it returns that AST...
Method	`__reduce__`	Undocumented
Method	`__repr__`	Undocumented
Method	`annotate`	Appends annotations to this AST.
Method	`append_annotation`	Appends an annotation to this AST.
Method	`append_annotations`	Appends several annotations to this AST.
Method	`canonicalize`	Undocumented
Method	`children_asts`	Return an iterator over the nested children ASTs.
Method	`dbg_is_looped`	Undocumented
Method	`dbg_repr`	Returns a debug representation of this AST.
Method	`insert_annotation`	Inserts an annotation to this AST.
Method	`insert_annotations`	Inserts several annotations to this AST.
Method	`leaf_asts`	Return an iterator over the leaf ASTs.
Method	`make_like`	Undocumented
Method	`remove_annotation`	Removes an annotation from this AST.
Method	`remove_annotations`	Removes several annotations from this AST.
Method	`replace`	Returns this AST but with the AST 'old' replaced with AST 'new' in its subexpressions.
Method	`replace_annotations`	Replaces annotations on this AST.
Method	`replace_dict`	Returns this AST with subexpressions replaced by those that can be found in `replacements` dict.
Method	`shallow_repr`	Returns a string representation of this AST, but with a maximum depth to prevent floods of text being printed.
Method	`split`	Splits the AST if its operation is `split_on` (i.e., return all the arguments). Otherwise, return a list with just the AST.
Method	`structurally_match`	Structurally compares two A objects, and check if their corresponding leaves are definitely the same A object (name-wise or hash-identity wise).
Method	`swap_args`	This returns the same AST, with the arguments swapped out for new_args.
Method	`to_claripy`	Returns itself. Provides compatibility with other classes (such as SimActionObject) which provide a similar method to unwrap to an AST.
Constant	`FULL_REPR`	Undocumented
Constant	`FULL_SIMPLIFY`	Undocumented
Constant	`LITE_REPR`	Undocumented
Constant	`LITE_SIMPLIFY`	Undocumented
Constant	`MID_REPR`	Undocumented
Constant	`UNSIMPLIFIED`	Undocumented
Class Variable	`__slots__`	Undocumented
Instance Variable	`annotations`	Undocumented
Instance Variable	`args`	Undocumented
Instance Variable	`depth`	Undocumented
Instance Variable	`length`	Undocumented
Instance Variable	`op`	Undocumented
Instance Variable	`symbolic`	Undocumented
Instance Variable	`variables`	Undocumented
Property	`cache_key`	A key that refers to this AST - this value is appropriate for usage as a key in dictionaries.
Property	`cardinality`	Undocumented
Property	`concrete`	Undocumented
Property	`ite_burrowed`	Returns an equivalent AST that "burrows" the ITE expressions as deep as possible into the ast, for simpler printing.
Property	`ite_excavated`	Returns an equivalent AST that "excavates" the ITE expressions out as far as possible toward the root of the AST, for processing in static analyses.
Property	`multivalued`	Undocumented
Property	`recursive_children_asts`	DEPRECATED: Use children_asts() instead.
Property	`recursive_leaf_asts`	DEPRECATED: Use leaf_asts() instead.
Property	`singlevalued`	Undocumented
Property	`uc_alloc_depth`	The depth of allocation by lazy-initialization. It's only used in under-constrained symbolic execution mode.
Property	`uninitialized`	Whether this AST comes from an uninitialized dereference or not. It's only used in under-constrained symbolic execution mode.
Static Method	`_arg_serialize`	Undocumented
Static Method	`_ast_serialize`	Serialize the AST and get a bytestring for hashing.
Static Method	`_calc_hash`	Calculates the hash of an AST, given the operation, args, and kwargs.
Static Method	`_check_replaceability`	Undocumented
Static Method	`_op_repr`	Undocumented
Method	`_apply_to_annotations`	Undocumented
Method	`_burrow_ite`	Undocumented
Method	`_excavate_ite`	Undocumented
Method	`_first_backend`	Undocumented
Method	`_identify_vars`	Undocumented
Method	`_rename`	Undocumented
Method	`_type_name`	Undocumented
Class Variable	`_hash_cache`	Undocumented
Class Variable	`_leaf_cache`	Undocumented
Instance Variable	`_burrowed`	Undocumented
Instance Variable	`_cache_key`	Undocumented
Instance Variable	`_cached_encoded_name`	Undocumented
Instance Variable	`_eager_backends`	Undocumented
Instance Variable	`_errored`	Undocumented
Instance Variable	`_excavated`	Undocumented
Instance Variable	`_hash`	Undocumented
Instance Variable	`_relocatable_annotations`	Undocumented
Instance Variable	`_simplified`	Undocumented
Instance Variable	`_uc_alloc_depth`	Undocumented
Instance Variable	`_uneliminatable_annotations`	Undocumented
Instance Variable	`_uninitialized`	Undocumented
Property	`_encoded_name`	Undocumented

@classmethod
def __init_with_annotations__(cls, op, a_args, depth=None, uneliminatable_annotations=None, relocatable_annotations=None, **kwargs): (source) ¶

Undocumented

def __a_init__(self, op, args, variables=None, symbolic=None, length=None, simplified=0, errored=None, eager_backends=None, uninitialized=None, uc_alloc_depth=None, annotations=None, encoded_name=None, depth=None, uneliminatable_annotations=None, relocatable_annotations=None): (source) ¶

Initializes an AST. Takes the same arguments as ``Base.__new__()`` We use this instead of ``__init__`` due to python's undesirable behavior w.r.t. automatically calling it on return from ``__new__``.

def __bool__(self): (source) ¶

This prevents people from accidentally using an AST as a condition. For example, the following was previously common:: a,b = two ASTs if a == b: do something The problem is that `a == b` would return an AST, because an AST can be symbolic and there could be no way to actually know the value of that without a constraint solve. This caused tons of issues.

def __getattr__(self, a): (source) ¶

Undocumented

def __hash__(self): (source) ¶

Undocumented

def __init__(self, *args, **kwargs): (source) ¶

overridden in claripy.ast.strings.String

Undocumented

def __iter__(self): (source) ¶

This prevents people from iterating over ASTs.

def __new__(cls, op, args, add_variables=None, hash=None, **kwargs): (source) ¶

This is called when you create a new Base object, whether directly or through an operation. It finalizes the arguments (see the _finalize function, above) and then computes a hash. If an AST of this hash already exists, it returns that AST. Otherwise, it creates, initializes, and returns the AST. :param op: The AST operation ('__add__', 'Or', etc) :param args: The arguments to the AST operation (i.e., the objects to add) :param variables: The symbolic variables present in the AST (default: empty set) :param symbolic: A flag saying whether or not the AST is symbolic (default: False) :param length: An integer specifying the bit length of this AST (default: None) :param simplified: A measure of how simplified this AST is. 0 means unsimplified, 1 means fast-simplified (basically, just undoing the Reverse op), and 2 means simplified through z3. :param errored: A set of backends that are known to be unable to handle this AST. :param eager_backends: A list of backends with which to attempt eager evaluation :param annotations: A frozenset of annotations applied onto this AST.

def __reduce__(self): (source) ¶

Undocumented

def __repr__(self, inner=False, max_depth=None, explicit_length=False): (source) ¶

Undocumented

def annotate(self, *args, remove_annotations=None): (source) ¶

Appends annotations to this AST. :param args: the tuple of annotations to append (variadic positional args) :param remove_annotations: annotations to remove :returns: a new AST, with the annotations added

def append_annotation(self, a): (source) ¶

Appends an annotation to this AST. :param a: the annotation to append :returns: a new AST, with the annotation added

def append_annotations(self, new_tuple): (source) ¶

Appends several annotations to this AST. :param new_tuple: the tuple of annotations to append :returns: a new AST, with the annotations added

def canonicalize(self, var_map=None, counter=None): (source) ¶

Undocumented

def children_asts(self): (source) ¶

Return an iterator over the nested children ASTs.

def dbg_is_looped(self): (source) ¶

Undocumented

def dbg_repr(self, prefix=None): (source) ¶

Returns a debug representation of this AST.

def insert_annotation(self, a): (source) ¶

Inserts an annotation to this AST. :param a: the annotation to insert :returns: a new AST, with the annotation added

def insert_annotations(self, new_tuple): (source) ¶

Inserts several annotations to this AST. :param new_tuple: the tuple of annotations to insert :returns: a new AST, with the annotations added

def leaf_asts(self): (source) ¶

Return an iterator over the leaf ASTs.

def make_like(self, op, args, **kwargs): (source) ¶

overridden in claripy.ast.bits.Bits

Undocumented

def remove_annotation(self, a): (source) ¶

Removes an annotation from this AST. :param a: the annotation to remove :returns: a new AST, with the annotation removed

def remove_annotations(self, remove_sequence): (source) ¶

Removes several annotations from this AST. :param remove_sequence: a sequence/set of the annotations to remove :returns: a new AST, with the annotations removed

def replace(self, old, new, variable_set=None, leaf_operation=None): (source) ¶

Returns this AST but with the AST 'old' replaced with AST 'new' in its subexpressions.

def replace_annotations(self, new_tuple): (source) ¶

Replaces annotations on this AST. :param new_tuple: the tuple of annotations to replace the old annotations with :returns: a new AST, with the annotations added

def replace_dict(self, replacements, variable_set=None, leaf_operation=None): (source) ¶

Returns this AST with subexpressions replaced by those that can be found in `replacements` dict. :param variable_set: For optimization, ast's without these variables are not checked for replacing. :param replacements: A dictionary of hashes to their replacements. :param leaf_operation: An operation that should be applied to the leaf nodes. :returns: An AST with all instances of ast's in replacements.

def shallow_repr(self, max_depth=8, explicit_length=False, details=LITE_REPR, inner=False, parent_prec=15, left=True): (source) ¶

Returns a string representation of this AST, but with a maximum depth to prevent floods of text being printed. :param max_depth: The maximum depth to print. :param explicit_length: Print lengths of BVV arguments. :param details: An integer value specifying how detailed the output should be: LITE_REPR - print short repr for both operations and BVs, MID_REPR - print full repr for operations and short for BVs, FULL_REPR - print full repr of both operations and BVs. :param inner: whether or not it is an inner AST :param parent_prec: parent operation precedence level :param left: whether or not it is a left AST :returns: A string representing the AST

def split(self, split_on): (source) ¶

Splits the AST if its operation is `split_on` (i.e., return all the arguments). Otherwise, return a list with just the AST.

def structurally_match(self, o): (source) ¶

Structurally compares two A objects, and check if their corresponding leaves are definitely the same A object (name-wise or hash-identity wise). :param o: the other claripy A object :returns: True/False

def swap_args(self, new_args, new_length=None, **kwargs): (source) ¶

This returns the same AST, with the arguments swapped out for new_args.

def to_claripy(self): (source) ¶

Returns itself. Provides compatibility with other classes (such as SimActionObject) which provide a similar method to unwrap to an AST.

FULL_REPR: int = (source) ¶

Undocumented

Value

FULL_SIMPLIFY: int = (source) ¶

Undocumented

Value

LITE_REPR: int = (source) ¶

Undocumented

Value

LITE_SIMPLIFY: int = (source) ¶

Undocumented

Value

MID_REPR: int = (source) ¶

Undocumented

Value

UNSIMPLIFIED: int = (source) ¶

Undocumented

Value

__slots__: list[str] = (source) ¶

overridden in claripy.ast.bool.Bool, claripy.ast.bv.BV, claripy.ast.fp.FP, claripy.ast.int.Int, claripy.ast.strings.String, claripy.ast.vs.VS

Undocumented

annotations = (source) ¶

Undocumented

args = (source) ¶

Undocumented

depth = (source) ¶

Undocumented

length = (source) ¶

Undocumented

op = (source) ¶

Undocumented

symbolic = (source) ¶

Undocumented

variables = (source) ¶

Undocumented

@property
cache_key = (source) ¶

A key that refers to this AST - this value is appropriate for usage as a key in dictionaries.

@property
cardinality = (source) ¶

Undocumented

@property
concrete = (source) ¶

Undocumented

@property
ite_burrowed = (source) ¶

Returns an equivalent AST that "burrows" the ITE expressions as deep as possible into the ast, for simpler printing.

@property
ite_excavated = (source) ¶

Returns an equivalent AST that "excavates" the ITE expressions out as far as possible toward the root of the AST, for processing in static analyses.

@property
multivalued = (source) ¶

Undocumented

@property
recursive_children_asts = (source) ¶

DEPRECATED: Use children_asts() instead.

@property
recursive_leaf_asts = (source) ¶

DEPRECATED: Use leaf_asts() instead.

@property
singlevalued = (source) ¶

Undocumented

@property
uc_alloc_depth = (source) ¶

The depth of allocation by lazy-initialization. It's only used in under-constrained symbolic execution mode. :returns: An integer indicating the allocation depth, or None if it's not from lazy-initialization.

@property
uninitialized = (source) ¶

Whether this AST comes from an uninitialized dereference or not. It's only used in under-constrained symbolic execution mode. :returns: True/False/None (unspecified).

@staticmethod
def _arg_serialize(arg) -> Optional[bytes]: (source) ¶

Undocumented

@staticmethod
def _ast_serialize(op: str, args_tup, keywords) -> Optional[bytes]: (source) ¶

Serialize the AST and get a bytestring for hashing. :param op: The operator. :param args_tup: A tuple of arguments. :param keywords: A dict of keywords. :return: The serialized bytestring.

@staticmethod
def _calc_hash(op, args, keywords): (source) ¶

Calculates the hash of an AST, given the operation, args, and kwargs. :param op: The operation. :param args: The arguments to the operation. :param keywords: A dict including the 'symbolic', 'variables', and 'length' items. :returns: a hash. We do it using md5 to avoid hash collisions. (hash(-1) == hash(-2), for example)

@staticmethod
def _check_replaceability(old, new): (source) ¶

overridden in claripy.ast.bits.Bits

Undocumented

@staticmethod
def _op_repr(op, args, inner, length, details, inner_infix_use_par): (source) ¶

Undocumented

def _apply_to_annotations(self, f): (source) ¶

Undocumented

def _burrow_ite(self): (source) ¶

Undocumented

def _excavate_ite(self): (source) ¶

Undocumented

def _first_backend(self, what): (source) ¶