Module Core.BlangSource
Boolean expressions.
A blang is a boolean expression built up by applying the usual boolean operations to properties that evaluate to true or false in some context.
Usage
For example, imagine writing a config file for an application that filters a stream of integers. Your goal is to keep only those integers that are multiples of either -3 or 5. Using Blang for this task, the code might look like:
module Property = struct
type t =
| Multiple_of of int
| Positive
| Negative
[@@deriving sexp]
let eval t num =
match t with
| Multiple_of n -> num % n = 0
| Positive -> num > 0
| Negative -> num < 0
end
type config = {
keep : Property.t Blang.t;
} [@@deriving sexp]
let config = {
keep =
Blang.t_of_sexp
Property.t_of_sexp
(Sexp.of_string
"(or (and negative (multiple_of 3)) (and positive (multiple_of 5)))";
}
let keep config num : bool =
Blang.eval config.keep (fun p -> Property.eval p num)Note how positive and negative and multiple_of become operators in a small, newly-defined boolean expression language that allows you to write statements like (and negative (multiple_of 3)).
Blang sexp syntax
The blang sexp syntax is almost exactly the derived one, except that:
1. Base properties are not marked explicitly. Thus, if your base property type has elements FOO, BAR, etc., then you could write the following Blang s-expressions:
FOO
(and FOO BAR)
(if FOO BAR BAZ)and so on. Note that this gets in the way of using the blang "keywords" in your value language.
2. And and Or take a variable number of arguments, so that one can (and probably should) write
(and FOO BAR BAZ QUX)
instead of
(and FOO (and BAR (and BAZ QUX)))
If you want to see the derived sexp, use Raw.sexp_of_t.
type +'a t = private | True| False| And of 'a Core.Blang.t * 'a Core.Blang.t| Or of 'a Core.Blang.t * 'a Core.Blang.t| Not of 'a Core.Blang.t| If of 'a Core.Blang.t * 'a Core.Blang.t * 'a Core.Blang.t| Base of 'a
Note that the sexps are not directly inferred from the type below -- there are lots of fancy shortcuts. Also, the sexps for 'a must not look anything like blang sexps. Otherwise t_of_sexp will fail. The directly inferred sexps are available via Raw.sexp_of_t.
include Ppx_compare_lib.Comparable.S1 with type +'a t := 'a Core.Blang.t
include Ppx_compare_lib.Equal.S1 with type +'a t := 'a Core.Blang.t
include Ppx_hash_lib.Hashable.S1_any with type +'a t := 'a Core.Blang.t
val t_sexp_grammar :
'a. 'a Sexplib0.Sexp_grammar.t ->
'a Core.Blang.t Sexplib0.Sexp_grammar.t @@ portableinclude Typerep_lib.Typerepable.S1 with type +'a t := 'a Core.Blang.t
val typerep_of_t :
'a Typerep_lib.Std_internal.Typerep.t ->
'a Core.Blang.t Typerep_lib.Std_internal.Typerep.t @@ portableval typename_of_t :
'a Typerep_lib.Typename.t ->
'a Core.Blang.t Typerep_lib.Typename.t @@ portableRaw provides the automatically derived sexp_of_t, useful in debugging the actual structure of the blang.
Smart constructors that simplify away constants whenever possible
include Core.Blang.Constructors
function true -> true_ | false -> false_
n-ary And
n-ary Or
if_ if then else
constant_value t = Some b iff t = constant b
The following two functions are useful when one wants to pretend that 'a t has constructors And and Or of type 'a t list -> 'a t. The pattern of use is
match t with
| And (_, _) as t -> let ts = gather_conjuncts t in ...
| Or (_, _) as t -> let ts = gather_disjuncts t in ...
| ...or, in case you also want to handle True (resp. False) as a special case of conjunction (disjunction)
match t with
| True | And (_, _) as t -> let ts = gather_conjuncts t in ...
| False | Or (_, _) as t -> let ts = gather_disjuncts t in ...
| ...gather_conjuncts t gathers up all toplevel conjuncts in t. For example,
gather_conjuncts (and_ ts) = tsgather_conjuncts (And (t1, t2)) = gather_conjuncts t1 @ gather_conjuncts t2gather_conjuncts True = []gather_conjuncts t = [t]whentmatches neitherAnd (_, _)norTrue
gather_disjuncts t gathers up all toplevel disjuncts in t. For example,
gather_disjuncts (or_ ts) = tsgather_disjuncts (Or (t1, t2)) = gather_disjuncts t1 @ gather_disjuncts t2gather_disjuncts False = []gather_disjuncts t = [t]whentmatches neitherOr (_, _)norFalse
include Core.Container.S1 with type 'a t := 'a Core.Blang.t
include sig ... end
include sig ... end
iter must allow exceptions raised in f to escape, terminating the iteration cleanly. The same holds for all functions below taking an f.
Returns true if and only if there exists an element for which the provided function evaluates to true. This is a short-circuiting operation.
Returns true if and only if the provided function evaluates to true for all elements. This is a short-circuiting operation.
Returns the number of elements for which the provided function evaluates to true.
Returns as an option the first element for which f evaluates to true.
Returns a min (resp. max) element from the collection using the provided compare function. In case of a tie, the first element encountered while traversing the collection is returned. The implementation uses fold so it has the same complexity as fold. Returns None iff the collection is empty.
include sig ... end
val sum :
'a 'sum 'p1 'p2. (module Base__.Container_intf.Definitions.Summable__value_or_null
with type t = 'sum) ->
'a Core.Blang.t ->
f:('a -> 'sum) @ local ->
'sumReturns the sum of f i for all i in the container. The order in which the elements will be summed is unspecified.
val iter_until :
'a 'p1 'p2 'final. 'a Core.Blang.t ->
f:('a -> (unit, 'final) Base.Container.Continue_or_stop.t) @ local ->
finish:(unit -> 'final) @ local ->
'finaliter_until t ~f ~finish is a short-circuiting version of iter. If f returns Stop x the computation ceases and returns x. If f always returns Continue () the final result is computed by finish.
val fold :
'a 'p1 'p2 'acc. 'a Core.Blang.t ->
init:'acc ->
f:('acc -> 'a -> 'acc) @ local ->
'accfold t ~init ~f returns f (... f (f (f init e1) e2) e3 ...) en, where e1..en are the elements of t.
val fold_result :
'a 'p1 'p2 'acc 'e. 'a Core.Blang.t ->
init:'acc ->
f:('acc -> 'a -> ('acc, 'e) Stdlib.result) @ local ->
('acc, 'e) Stdlib.resultfold_result t ~init ~f is a short-circuiting version of fold that runs in the Result monad. If f returns an Error _, that value is returned without any additional invocations of f.
Returns the first evaluation of f that returns Some, and returns None if there is no such element.
include sig ... end
val fold_until :
'a 'p1 'p2 'acc 'final. 'a Core.Blang.t ->
init:'acc ->
f:('acc -> 'a -> ('acc, 'final) Base.Container.Continue_or_stop.t) @ local ->
finish:('acc -> 'final) @ local ->
'finalfold_until t ~init ~f ~finish is a short-circuiting version of fold. If f returns Stop _ the computation ceases and results in that value. If f returns Continue _, the fold will proceed. If f never returns Stop _, the final result is computed by finish.
Example:
type maybe_negative =
| Found_negative of int
| All_nonnegative of { sum : int }
(** [first_neg_or_sum list] returns the first negative number in [list], if any,
otherwise returns the sum of the list. *)
let first_neg_or_sum =
List.fold_until ~init:0
~f:(fun sum x ->
if x < 0
then Stop (Found_negative x)
else Continue (sum + x))
~finish:(fun sum -> All_nonnegative { sum })
;;
let x = first_neg_or_sum [1; 2; 3; 4; 5]
val x : maybe_negative = All_nonnegative {sum = 15}
let y = first_neg_or_sum [1; 2; -3; 4; 5]
val y : maybe_negative = Found_negative -3include sig ... end
Checks whether the provided element is there, using equal.
include sig ... end
include Core.Quickcheckable.S1 with type 'a t := 'a Core.Blang.t
val quickcheck_generator :
'a Base_quickcheck.Generator.t ->
'a Core.Blang.t Base_quickcheck.Generator.tval quickcheck_observer :
'a Base_quickcheck.Observer.t ->
'a Core.Blang.t Base_quickcheck.Observer.tval quickcheck_shrinker :
'a Base_quickcheck.Shrinker.t ->
'a Core.Blang.t Base_quickcheck.Shrinker.tBlang.t sports a substitution monad:
return visBase v(think ofvas a variable)bind t freplaces everyBase vintwithf v(think ofvas a variable andfas specifying the term to substitute for each variable)
Note: bind t f does short-circuiting, so f may not be called on every variable in t.
include Base.Monad.S__local with type 'a t := 'a Core.Blang.t
val return : 'a -> 'a Core.Blang.tConvert a value to a t.
val map : 'a Core.Blang.t -> f:('a -> 'b) @ local -> 'b Core.Blang.tTransforms the contents of a t.
val bind :
'a Core.Blang.t ->
f:('a -> 'b Core.Blang.t) @ local ->
'b Core.Blang.tSequences computations. bind t ~f computes f v for value(s) v in t. Well-behaved monads satisfy these "laws" (where ( >>= ) is the infix bind operator):
map t ~fis equivalent tobind t ~f:(fun x -> return (f x))return x >>= fis equivalent tof xt >>= returnis equivalent tot(t >>= f) >>= gis equivalent tot >>= fun x -> f x >>= g
val join : 'a Core.Blang.t Core.Blang.t -> 'a Core.Blang.tCombines nested t into just one layer. Equivalent to bind t ~f:Fn.id.
val ignore_m : 'a Core.Blang.t -> unit Core.Blang.tIgnores contained values of t. Equivalent to map t ~f:ignore.
val all : 'a Core.Blang.t list -> 'a list Core.Blang.tCombines a list of t.
val all_unit : unit Core.Blang.t list -> unit Core.Blang.tCombines a list of t whose contents are unimportant.
val (>>=) :
'a Core.Blang.t ->
('a -> 'b Core.Blang.t) @ local ->
'b Core.Blang.tInfix bind.
val (>>|) : 'a Core.Blang.t -> ('a -> 'b) @ local -> 'b Core.Blang.tInfix map.
values t forms the list containing every v for which Base v is a subexpression of t
eval t f evaluates the proposition t relative to an environment f that assigns truth values to base propositions.
val eval_set :
universe:('elt, 'comparator) Core.Set.t Core.Lazy.t ->
('a -> ('elt, 'comparator) Core.Set.t) @ local ->
'a Core.Blang.t ->
('elt, 'comparator) Core.Set.t @@ portableeval_set ~universe set_of_base expression returns the subset of elements e in universe that satisfy eval expression (fun base -> Set.mem (set_of_base base) e).
eval_set assumes, but does not verify, that set_of_base always returns a subset of universe. If this doesn't hold, then eval_set's result may contain elements not in universe.
And set1 set2 represents the elements that are both in set1 and set2, thus in the intersection of the two sets. Symmetrically, Or set1 set2 represents the union of set1 and set2.
val specialize :
'a Core.Blang.t ->
('a -> [ `Known of Base.Bool.t | `Unknown ]) @ local ->
'a Core.Blang.t @@ portablespecialize t f partially evaluates t according to a perhaps-incomplete assignment f of the values of base propositions. The following laws (at least partially) characterize its behavior.
specialize t (fun _ -> `Unknown) = t
specialize t (fun x -> `Known (f x)) = constant (eval t f)
List.for_all (values (specialize t g)) ~f:(fun x -> g x = `Unknown)
if List.for_all (values t) ~f:(fun x -> match g x with | `Known b -> b = f x | `Unknown -> true) then eval t f = eval (specialize t g) f
Generalizes some of the blang operations above to work in a monad.