lib/whenutils.mli

   1 (* whenjobs
   2  * Copyright (C) 2012 Red Hat Inc.
   3  *
   4  * This program is free software; you can redistribute it and/or modify
   5  * it under the terms of the GNU General Public License as published by
   6  * the Free Software Foundation; either version 2 of the License, or
   7  * (at your option) any later version.
   8  *
   9  * This program is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12  * GNU General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU General Public License along
  15  * with this program; if not, write to the Free Software Foundation, Inc.,
  16  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  17  *)
  18
  19 (** Types and utility functions. *)
  20
  21 module StringMap : sig
  22   type key = String.t
  23   type 'a t = 'a Map.Make(String).t
  24   val empty : 'a t
  25   val is_empty : 'a t -> bool
  26   val mem : key -> 'a t -> bool
  27   val add : key -> 'a -> 'a t -> 'a t
  28   (*val singleton : key -> 'a -> 'a t*)
  29   val remove : key -> 'a t -> 'a t
  30   (*val merge :
  31     (key -> 'a option -> 'b option -> 'c option) -> 'a t -> 'b t -> 'c t*)
  32   val compare : ('a -> 'a -> int) -> 'a t -> 'a t -> int
  33   val equal : ('a -> 'a -> bool) -> 'a t -> 'a t -> bool
  34   val iter : (key -> 'a -> unit) -> 'a t -> unit
  35   val fold : (key -> 'a -> 'b -> 'b) -> 'a t -> 'b -> 'b
  36   (*val for_all : (key -> 'a -> bool) -> 'a t -> bool
  37   val exists : (key -> 'a -> bool) -> 'a t -> bool
  38   val filter : (key -> 'a -> bool) -> 'a t -> 'a t
  39   val partition : (key -> 'a -> bool) -> 'a t -> 'a t * 'a t
  40   val cardinal : 'a t -> int
  41   val bindings : 'a t -> (key * 'a) list
  42   val min_binding : 'a t -> key * 'a
  43   val max_binding : 'a t -> key * 'a
  44   val choose : 'a t -> key * 'a
  45   val split : key -> 'a t -> 'a t * 'a option * 'a t*)
  46   val find : key -> 'a t -> 'a
  47   val map : ('a -> 'b) -> 'a t -> 'b t
  48   val mapi : (key -> 'a -> 'b) -> 'a t -> 'b t
  49   val keys : 'a t -> key list
  50   val values : 'a t -> 'a list
  51 end
  52 (** A map from string to any type. *)
  53
  54 module StringSet : sig
  55   type elt = String.t
  56   type t = Set.Make(String).t
  57   val empty : t
  58   val is_empty : t -> bool
  59   val mem : elt -> t -> bool
  60   val add : elt -> t -> t
  61   val singleton : elt -> t
  62   val remove : elt -> t -> t
  63   val union : t -> t -> t
  64   val inter : t -> t -> t
  65   val diff : t -> t -> t
  66   val compare : t -> t -> int
  67   val equal : t -> t -> bool
  68   val subset : t -> t -> bool
  69   val iter : (elt -> unit) -> t -> unit
  70   val fold : (elt -> 'a -> 'a) -> t -> 'a -> 'a
  71   val for_all : (elt -> bool) -> t -> bool
  72   val exists : (elt -> bool) -> t -> bool
  73   val filter : (elt -> bool) -> t -> t
  74   val partition : (elt -> bool) -> t -> t * t
  75   val cardinal : t -> int
  76   val elements : t -> elt list
  77   val min_elt : t -> elt
  78   val max_elt : t -> elt
  79   val choose : t -> elt
  80   val split : elt -> t -> t * bool * t
  81 end
  82 (** A set of strings. *)
  83
  84 type whenexpr =
  85   | Expr_bool of bool                   (** A boolean constant. *)
  86   | Expr_str of string                  (** A string constant. *)
  87   | Expr_int of Big_int.big_int         (** An integer constant. *)
  88   | Expr_float of float                 (** A float constant. *)
  89   | Expr_var of string                  (** A variable name. *)
  90   | Expr_and of whenexpr * whenexpr     (** && *)
  91   | Expr_or of whenexpr * whenexpr      (** || *)
  92   | Expr_eq of whenexpr * whenexpr      (** == *)
  93   | Expr_not of whenexpr                (** ! *)
  94   | Expr_changes of string              (** changes var *)
  95 (** Internal type used to represent 'when' expressions. *)
  96
  97 type periodexpr =
  98   | Every_seconds of int
  99   | Every_days of int
 100   | Every_months of int
 101   | Every_years of int
 102 (** Internal type used to represent 'every' expressions. *)
 103
 104 type shell_script = {
 105   sh_loc : Camlp4.PreCast.Loc.t;
 106   sh_script : string;
 107 }
 108 (** A shell script. *)
 109
 110 type variable =
 111   | T_bool of bool
 112   | T_string of string
 113   | T_int of Big_int.big_int
 114   | T_float of float
 115 (** Typed variable (see also [whenproto.x]) *)
 116
 117 val variable_of_rpc : Whenproto_aux.variable -> variable
 118 val rpc_of_variable : variable -> Whenproto_aux.variable
 119
 120 type variables = variable StringMap.t
 121 (** A set of variables. *)
 122
 123 type job_private
 124 (** Private state associated with a job, used for evaluation. *)
 125
 126 val no_job_private : job_private
 127 (* XXX any use of no_job_private is wrong XXX *)
 128
 129 type job_cond =
 130   | When_job of whenexpr                (** when ... : << >> *)
 131   | Every_job of periodexpr             (** every ... : << >> *)
 132
 133 type job = {
 134   job_loc : Camlp4.PreCast.Loc.t;
 135   job_name : string;
 136   job_cond : job_cond;
 137   job_script : shell_script;
 138   job_private : job_private;
 139 }
 140 (** A job. *)
 141
 142 val expr_of_ast : Camlp4.PreCast.Ast.Loc.t -> Camlp4.PreCast.Ast.expr -> whenexpr
 143 (** Convert OCaml AST to an expression.  Since OCaml ASTs are much
 144     more general than the expressions we can use, this can raise
 145     [Invalid_argument] in many different situations. *)
 146
 147 val string_of_whenexpr : whenexpr -> string
 148 (** Pretty-print an expression to a string. *)
 149
 150 val string_of_periodexpr : periodexpr -> string
 151 (** Pretty-print a period expression to a string. *)
 152
 153 val dependencies_of_whenexpr : whenexpr -> string list
 154 (** Return list of variables that an expression depends on.  This is
 155     used to work out when an expression needs to be reevaluated. *)
 156
 157 val dependencies_of_job : job -> string list
 158 (** Which variables does this job depend on? *)
 159
 160 val job_evaluate : job -> variables -> bool * job
 161 (** Evaluate [job]'s condition in the context of the [variables], and
 162     return [true] iff it should be run now.  Note that this returns a
 163     possibly-updated [job] structure.
 164
 165     This is a no-op for 'every' jobs. *)