package bap-std

  1. Overview
  2. Docs
package bap-std
Legend:
Library
Module
Module type
Parameter
Class
Class type

Regular interface for BIL expressions

type t = Bil.exp

the Exp.t property.

This property of a value denotes it in terms of Bil expressions.

class state : object ... end

All visitors provide some information about the current position of the visitor

class 'a visitor : object ... end

expression visitor.

class 'a finder : object ... end

A visitor with a shortcut. Finder is a specialization of a visitor, that uses return as its folding argument. At any time you can stop the traversing by calling return function of the provided argument (which is by itself is a record with one field - a function accepting argument of type 'a option).

class mapper : object ... end

Exp mapper. By default performs deep identity mapping. Non-leaf methods deconstructs terms, calls corresponding methods on its parts and the constructs it back. So if you're overriding a non-leaf method, then make sure that you called the parent method if you want a normal traversal.

val fold : 'a visitor -> init:'a -> t -> 'a

fold visitor ~init exp traverse the exp tree with provided visitor. For example, the following will collect all address that are accessed with a load operation: { let collect_load_addresses = Exp.fold ~init:[] (object inherit [word list] Bil.visitor method! enter_load ~mem ~addr _ _ addrs = match addr with | Bil.Int addr -> addr :: addrs | _ -> addrs end) } See also Bil.fold and Stmt.fold

val iter : unit visitor -> t -> unit

iter visitor exp iterates over all terms of the exp using provided visitor. See also Bil.iter and Stmt.iter

val find : 'a finder -> t -> 'a option

find finder exp returns Some thing if finder finds some thing. See also Bil.find and Stmt.find

val map : mapper -> t -> t

map mapper exp maps exp tree using provided mapper. See also Bil.map

val exists : unit finder -> t -> bool

exists finder exp is true if finder finds something. See also Bil.exists and Stmt.exists

val substitute : exp -> exp -> exp -> exp

substitute pat rep x subsitutes each occurrence of an expression pat in x with an expression rep

val normalize : exp -> exp

normalize x ensures no-lets and normalized-memory (BNF2).

Inlines all let expressions, expands multibyte loads to a concatenation of one byte loads, and expands multibyte stores into chains of one byte stores.

The function may duplicate expressions even those that are not generative, thus breaking the semantics of the expression.

Precondition: x is well-typed and in BNF1.

See Stmt.normalize for the definition of the BNF1 and BNF2.

  • since 1.3
val simpl : ?ignore:Eff.t list -> exp -> exp

simpl ~ignore:effects x iff expression x is well-typed, then returns an expression with the same semantics as x, that might smaller according to some metrics. A subexression is removed from x if it doesn't manifest any effects other than those that are specified with the ~ignore:effects parameter (defaults to an empty list).

The following code simplification are applied:

  • constant folding: if an expression can be computed statically then it is substituted with the result of computation, e.g., 1 + 2 -> 3
  • neutral element elimination: binary operations with one of the operands being known to be neutral, are substituted with the other operand, e.g., x * 1 -> x
  • zero element propagation: binary operations applied to a zero element are substituted with the zero element, e.g., x * 0 -> 0
  • symbolic equality reduction: if both branches of a comparison are syntactically equal then the comparison is reduced to a boolean constant, e.g., a = a -> true, a < a -> false. Note, by default a read from a register is considered as a (co)effect, hence the above transformations wouldn't be applied, consider passing ~ignore:[Eff.reads] if you want such expressions to be reduced.
  • double complement reduction: an odd amount of complement operations (one and two) are reduced to one complement of the same sort, e.g., ~~~1 -> ~1
  • binary to unary reduction: reduce a subtraction from zero to the unary negation, e.g., 0 - x -> -x
  • exclusive disjunction reduction: reduces an exclusive disjunction of syntactically equal expressions to zero, e.g, 42 ^ 42 -> 0. Note, by default a read from a register is considered as a (co)effect, thus xor eax eax is not reduced, consider passing ~ignore:[Eff.reads] if you want such expressions to be reduced.
  • since 1.3
val is_referenced : var -> t -> bool

is_referenced x exp true if exp contains Var x on one of its leafs. See also Bil.is_referenced and Stmt.is_referenced

val normalize_negatives : t -> t

normalize_negatives exp returns an exp where all negative additions are substituted by subtractions. See Bil.normalize_negatives for more details

val fold_consts : t -> t

fold_consts x performs constant folding of the expression x.

Reduces all computable expressions to integers.

See also Bil.fold_consts

val fixpoint : (t -> t) -> t -> t

fixpoint f applies transformation f to t until it reaches a fixpoint, i.e., such point x that f x = f (f x). See also Bil.fixpoint and Stmt.fixpoint

val free_vars : t -> Var.Set.t

free_vars exp returns a set of all unbound variables, that occurs in the expression exp.

val eval : t -> Bil.value

eval x evaluate expression x to a value.

include Regular.Std.Regular.S with type t := t
include Core_kernel.Bin_prot.Binable.S with type t := t
include Bin_prot.Binable.S_only_functions with type t := t
val bin_size_t : t Bin_prot.Size.sizer
val bin_write_t : t Bin_prot.Write.writer
val bin_read_t : t Bin_prot.Read.reader
val __bin_read_t__ : (int -> t) Bin_prot.Read.reader

This function only needs implementation if t exposed to be a polymorphic variant. Despite what the type reads, this does *not* produce a function after reading; instead it takes the constructor tag (int) before reading and reads the rest of the variant t afterwards.

val bin_shape_t : Bin_prot.Shape.t
val bin_writer_t : t Bin_prot.Type_class.writer
val bin_reader_t : t Bin_prot.Type_class.reader
include Ppx_sexp_conv_lib.Sexpable.S with type t := t
val t_of_sexp : Sexplib0.Sexp.t -> t
val sexp_of_t : t -> Sexplib0.Sexp.t
include Regular.Std.Printable.S with type t := t
val to_string : t -> string

to_string x returns a human-readable representation of x

val str : unit -> t -> string

str () t is formatted output function that matches "%a" conversion format specifier in functions, that prints to string, e.g., sprintf, failwithf, errorf and, surprisingly all Lwt printing function, including Lwt_io.printf and logging (or any other function with type ('a,unit,string,...) formatN`. Example:

Or_error.errorf "type %a is not valid for %a"
  Type.str ty Exp.str exp
val pps : unit -> t -> string

synonym for str

val ppo : Core_kernel.Out_channel.t -> t -> unit

will print to a standard output_channel, useful for using in printf, fprintf, etc.

val pp_seq : Format.formatter -> t Core_kernel.Sequence.t -> unit

prints a sequence of values of type t

this will include pp function from Core that has type t printer, and can be used in Format.printf family of functions

include Core_kernel.Pretty_printer.S with type t := t
val pp : Base.Formatter.t -> t -> unit
include Core_kernel.Comparable.S_binable with type t := t
include Base.Comparable.S with type t := t
include Base.Comparisons.S with type t := t
include Base.Comparisons.Infix with type t := t
val (>=) : t -> t -> bool
val (<=) : t -> t -> bool
val (=) : t -> t -> bool
val (>) : t -> t -> bool
val (<) : t -> t -> bool
val (<>) : t -> t -> bool
val equal : t -> t -> bool
val compare : t -> t -> int

compare t1 t2 returns 0 if t1 is equal to t2, a negative integer if t1 is less than t2, and a positive integer if t1 is greater than t2.

val min : t -> t -> t
val max : t -> t -> t
val ascending : t -> t -> int

ascending is identical to compare. descending x y = ascending y x. These are intended to be mnemonic when used like List.sort ~compare:ascending and List.sort ~cmp:descending, since they cause the list to be sorted in ascending or descending order, respectively.

val descending : t -> t -> int
val between : t -> low:t -> high:t -> bool

between t ~low ~high means low <= t <= high

val clamp_exn : t -> min:t -> max:t -> t

clamp_exn t ~min ~max returns t', the closest value to t such that between t' ~low:min ~high:max is true.

Raises if not (min <= max).

val clamp : t -> min:t -> max:t -> t Base.Or_error.t
include Base.Comparator.S with type t := t
type comparator_witness
val validate_lbound : min:t Base.Maybe_bound.t -> t Base.Validate.check
val validate_ubound : max:t Base.Maybe_bound.t -> t Base.Validate.check
val validate_bound : min:t Base.Maybe_bound.t -> max:t Base.Maybe_bound.t -> t Base.Validate.check
include Core_kernel.Comparator.S with type t := t with type comparator_witness := comparator_witness
include Core_kernel.Hashable.S_binable with type t := t
val hash_fold_t : Base.Hash.state -> t -> Base.Hash.state
val hash : t -> Base.Hash.hash_value
val hashable : t Base.Hashable.t
include Regular.Std.Data.S with type t := t
type info = string * [ `Ver of string ] * string option

name,Ver v,desc information attached to a particular reader or writer.

val version : string

Data representation version. After any change in data representation the version should be increased.

Serializers that are derived from a data representation must have the same version as a version of the data structure, from which it is derived. This kind of serializers can only read and write data of the same version.

Other serializers can actually read and write data independent on its representation version. A serializer, that can't store data of current version simply shouldn't be added to a set of serializers.

It is assumed, that if a reader and a writer has the same name and version, then whatever was written by the writer should be readable by the reader. The round-trip equality is not required, thus it is acceptable if some information is lost.

It is also possible, that a reader and a writer that has the same name are compatible. In that case it is recommended to use semantic versioning.

val size_in_bytes : ?ver:string -> ?fmt:string -> t -> int

size_in_bytes ?ver ?fmt datum returns the amount of bytes that is needed to represent datum in the given format and version

val of_bytes : ?ver:string -> ?fmt:string -> Regular.Std.bytes -> t

of_bytes ?ver ?fmt bytes deserializes a value from bytes.

val to_bytes : ?ver:string -> ?fmt:string -> t -> Regular.Std.bytes

to_bytes ?ver ?fmt datum serializes a datum to a sequence of bytes.

val blit_to_bytes : ?ver:string -> ?fmt:string -> Regular.Std.bytes -> t -> int -> unit

blit_to_bytes ?ver ?fmt buffer datum offset copies a serialized representation of datum into a buffer, starting from the offset.

val of_bigstring : ?ver:string -> ?fmt:string -> Core_kernel.bigstring -> t

of_bigstring ?ver ?fmt buf deserializes a datum from bigstring

val to_bigstring : ?ver:string -> ?fmt:string -> t -> Core_kernel.bigstring

of_bigstring ?ver ?fmt datum serializes a datum to a sequence of bytes represented as bigstring

val blit_to_bigstring : ?ver:string -> ?fmt:string -> Core_kernel.bigstring -> t -> int -> unit

blit_to_bigstring ?ver ?fmt buffer datum offset copies a serialized representation of datum into a buffer, starting from offset.

module Io : sig ... end

Input/Output functions for the given datum.

module Cache : sig ... end

Data cache.

val add_reader : ?desc:string -> ver:string -> string -> t Regular.Std.reader -> unit

add_reader ?desc ~ver name reader registers a new reader with a provided name, version ver and optional description desc

val add_writer : ?desc:string -> ver:string -> string -> t Regular.Std.writer -> unit

add_writer ?desc ~ver name writer registers a new writer with a provided name, version ver and optional description desc

val available_readers : unit -> info list

available_reader () lists available readers for the data type

val default_reader : unit -> info

default_reader returns information about default reader

val set_default_reader : ?ver:string -> string -> unit

set_default_reader ?ver name sets new default reader. If version is not specified then the latest available version is used. Raises an exception if a reader with a given name doesn't exist.

val with_reader : ?ver:string -> string -> (unit -> 'a) -> 'a

with_reader ?ver name operation temporary sets a default reader to a reader with a specified name and version. The default reader is restored after operation is finished.

val available_writers : unit -> info list

available_writer () lists available writers for the data type

val default_writer : unit -> info

default_writer returns information about the default writer

val set_default_writer : ?ver:string -> string -> unit

set_default_writer ?ver name sets new default writer. If version is not specified then the latest available version is used. Raises an exception if a writer with a given name doesn't exist.

val with_writer : ?ver:string -> string -> (unit -> 'a) -> 'a

with_writer ?ver name operation temporary sets a default writer to a writer with a specified name and version. The default writer is restored after operation is finished.

val default_printer : unit -> info option

default_writer optionally returns an information about default printer

val set_default_printer : ?ver:string -> string -> unit

set_default_printer ?ver name sets new default printer. If version is not specified then the latest available version is used. Raises an exception if a printer with a given name doesn't exist.

val with_printer : ?ver:string -> string -> (unit -> 'a) -> 'a

with_printer ?ver name operation temporary sets a default printer to a printer with a specified name and version. The default printer is restored after operation is finished.

Low level access to serializers

val find_reader : ?ver:string -> string -> t Regular.Std.reader option

find_reader ?ver name lookups a reader with a given name. If version is not specified, then a reader with maximum version is returned.

val find_writer : ?ver:string -> string -> t Regular.Std.writer option

find_writer ?ver name lookups a writer with a given name. If version is not specified, then a writer with maximum version is returned.

val pp_adt : Format.formatter -> t -> unit
OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct