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
  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 IntMap : sig
  55   type key = int
  56   type 'a t
  57   val empty : 'a t
  58   val is_empty : 'a t -> bool
  59   val mem : key -> 'a t -> bool
  60   val add : key -> 'a -> 'a t -> 'a t
  61   (*val singleton : key -> 'a -> 'a t*)
  62   val remove : key -> 'a t -> 'a t
  63   (*val merge :
  64     (key -> 'a option -> 'b option -> 'c option) -> 'a t -> 'b t -> 'c t*)
  65   val compare : ('a -> 'a -> int) -> 'a t -> 'a t -> int
  66   val equal : ('a -> 'a -> bool) -> 'a t -> 'a t -> bool
  67   val iter : (key -> 'a -> unit) -> 'a t -> unit
  68   val fold : (key -> 'a -> 'b -> 'b) -> 'a t -> 'b -> 'b
  69   (*val for_all : (key -> 'a -> bool) -> 'a t -> bool
  70   val exists : (key -> 'a -> bool) -> 'a t -> bool
  71   val filter : (key -> 'a -> bool) -> 'a t -> 'a t
  72   val partition : (key -> 'a -> bool) -> 'a t -> 'a t * 'a t
  73   val cardinal : 'a t -> int
  74   val bindings : 'a t -> (key * 'a) list
  75   val min_binding : 'a t -> key * 'a
  76   val max_binding : 'a t -> key * 'a
  77   val choose : 'a t -> key * 'a
  78   val split : key -> 'a t -> 'a t * 'a option * 'a t*)
  79   val find : key -> 'a t -> 'a
  80   val map : ('a -> 'b) -> 'a t -> 'b t
  81   val mapi : (key -> 'a -> 'b) -> 'a t -> 'b t
  82   val keys : 'a t -> key list
  83   val values : 'a t -> 'a list
  84 end
  85 (** A map from int to any type. *)
  86
  87 module StringSet : sig
  88   type elt = String.t
  89   type t = Set.Make(String).t
  90   val empty : t
  91   val is_empty : t -> bool
  92   val mem : elt -> t -> bool
  93   val add : elt -> t -> t
  94   val singleton : elt -> t
  95   val remove : elt -> t -> t
  96   val union : t -> t -> t
  97   val inter : t -> t -> t
  98   val diff : t -> t -> t
  99   val compare : t -> t -> int
 100   val equal : t -> t -> bool
 101   val subset : t -> t -> bool
 102   val iter : (elt -> unit) -> t -> unit
 103   val fold : (elt -> 'a -> 'a) -> t -> 'a -> 'a
 104   val for_all : (elt -> bool) -> t -> bool
 105   val exists : (elt -> bool) -> t -> bool
 106   val filter : (elt -> bool) -> t -> t
 107   val partition : (elt -> bool) -> t -> t * t
 108   val cardinal : t -> int
 109   val elements : t -> elt list
 110   val min_elt : t -> elt
 111   val max_elt : t -> elt
 112   val choose : t -> elt
 113   val split : elt -> t -> t * bool * t
 114 end
 115 (** A set of strings. *)
 116
 117 val (//) : string -> string -> string
 118 (** [dir // file] concatenates directory and file. *)
 119
 120 val isalpha : char -> bool
 121 val isalnum : char -> bool
 122 (** Character tests. *)
 123
 124 val filter_map : ('a -> 'b option) -> 'a list -> 'b list
 125 (** Filter + map. *)
 126
 127 type whenexpr =
 128   | Expr_unit                           (** Unit constant. *)
 129   | Expr_bool of bool                   (** A boolean constant. *)
 130   | Expr_str of string                  (** A string constant. *)
 131   | Expr_int of Big_int.big_int         (** An integer constant. *)
 132   | Expr_float of float                 (** A float constant. *)
 133   | Expr_var of string                  (** A variable name. *)
 134   | Expr_and of whenexpr * whenexpr     (** && *)
 135   | Expr_or of whenexpr * whenexpr      (** || *)
 136   | Expr_lt of whenexpr * whenexpr      (** < *)
 137   | Expr_le of whenexpr * whenexpr      (** <= *)
 138   | Expr_eq of whenexpr * whenexpr      (** == *)
 139   | Expr_ge of whenexpr * whenexpr      (** >= *)
 140   | Expr_gt of whenexpr * whenexpr      (** > *)
 141   | Expr_not of whenexpr                (** boolean not *)
 142   | Expr_add of whenexpr * whenexpr     (** arithmetic addition or string cat *)
 143   | Expr_sub of whenexpr * whenexpr     (** arithmetic subtraction *)
 144   | Expr_mul of whenexpr * whenexpr     (** arithmetic multiplication *)
 145   | Expr_div of whenexpr * whenexpr     (** arithmetic division *)
 146   | Expr_mod of whenexpr * whenexpr     (** arithmetic modulo *)
 147   | Expr_changes of string              (** changes var *)
 148   | Expr_increases of string            (** increases var *)
 149   | Expr_decreases of string            (** decreases var *)
 150   | Expr_prev of string                 (** prev var *)
 151   | Expr_reloaded                       (** reloaded () *)
 152 (** Internal type used to represent 'when' expressions. *)
 153
 154 type periodexpr =
 155   | Every_seconds of int
 156   | Every_days of int
 157   | Every_months of int
 158   | Every_years of int
 159 (** Internal type used to represent 'every' expressions. *)
 160
 161 type shell_script = {
 162   sh_loc : Camlp4.PreCast.Loc.t;
 163   sh_script : string;
 164 }
 165 (** A shell script. *)
 166
 167 type variable =
 168   | T_unit
 169   | T_bool of bool
 170   | T_string of string
 171   | T_int of Big_int.big_int
 172   | T_float of float
 173 (** Typed variable (see also [whenproto.x]) *)
 174
 175 val string_of_variable : variable -> string
 176
 177 val variable_of_rpc : Whenproto_aux.variable -> variable
 178 val rpc_of_variable : variable -> Whenproto_aux.variable
 179
 180 type variables = variable StringMap.t
 181 (** A set of variables. *)
 182
 183 type job_private
 184 (** Private state associated with a job, used for evaluation. *)
 185
 186 type job_cond =
 187   | When_job of whenexpr                (** when ... : << >> *)
 188   | Every_job of periodexpr             (** every ... : << >> *)
 189
 190 type job = {
 191   job_loc : Camlp4.PreCast.Loc.t;
 192   job_name : string;
 193   job_cond : job_cond;
 194   job_script : shell_script;
 195   job_private : job_private;
 196 }
 197 (** A job.  Note that because of the [job_private] field, these cannot
 198     be constructed directly.  Use {!make_when_job} or {!make_every_job}
 199     to construct one. *)
 200
 201 val make_when_job : Camlp4.PreCast.Loc.t -> string -> whenexpr -> shell_script -> job
 202 (** Make a when-statement job. *)
 203
 204 val make_every_job : Camlp4.PreCast.Loc.t -> string -> periodexpr -> shell_script -> job
 205 (** Make an every-statement job. *)
 206
 207 val expr_of_ast : Camlp4.PreCast.Ast.Loc.t -> Camlp4.PreCast.Ast.expr -> whenexpr
 208 (** Convert OCaml AST to an expression.  Since OCaml ASTs are much
 209     more general than the expressions we can use, this can raise
 210     [Invalid_argument] in many different situations. *)
 211
 212 val string_of_whenexpr : whenexpr -> string
 213 (** Pretty-print an expression to a string. *)
 214
 215 val string_of_periodexpr : periodexpr -> string
 216 (** Pretty-print a period expression to a string. *)
 217
 218 val dependencies_of_whenexpr : whenexpr -> string list
 219 (** Return list of variables that an expression depends on.  This is
 220     used to work out when an expression needs to be reevaluated. *)
 221
 222 val dependencies_of_job : job -> string list
 223 (** Which variables does this job depend on? *)
 224
 225 val job_evaluate : job -> variables -> bool -> bool * job
 226 (** [job_evaluate job variables onload] evaluates [job]'s condition in
 227     the context of the [variables], and return [true] iff it should be
 228     run now.
 229
 230     Note that this returns a possibly-updated [job] structure.
 231
 232     This is a no-op for 'every' jobs. *)
 233
 234 val next_periodexpr : float -> periodexpr -> float
 235 (** [next_periodexpr t period] returns the earliest event of [period]
 236     strictly after time [t].
 237
 238     Visualising periods as repeated events on a timeline, this
 239     returns [t']:
 240
 241     {v
 242     events:  ---+---------+---------+---------+---------+---------+-----
 243     times:          t     t'
 244     }
 245
 246     Note that [periodexpr] events are not necessarily regular.
 247     eg. The start of a month is not a fixed number of seconds
 248     after the start of the previous month.  'Epoch' refers
 249     to the Unix Epoch (ie. 1970-01-01 00:00:00 UTC).
 250
 251     If [period = Every_seconds i] then events are when
 252     [t' mod i == 0] when t' is the number of seconds since
 253     the Epoch.  This returns the next t' > t.
 254
 255     If [period = Every_days i] then events happen at
 256     midnight UTC every [i] days since the Epoch.
 257     This returns the next midnight > t.
 258
 259     If [period = Every_months i] then events happen at
 260     midnight UTC on the 1st day of the month every [i] months
 261     since the Epoch.  This returns midnight on the
 262     1st day of the next month > t.
 263
 264     If [period = Every_years i] then events happen at
 265     midnight UTC on the 1st day of the year when
 266     [(y - 1970) mod i == 0].  This returns midnight on the
 267     1st day of the next year > t. *)