X-Git-Url: http://git.annexia.org/?p=whenjobs.git;a=blobdiff_plain;f=lib%2Fwhenutils.mli;h=4d5ccc7bed7c4c166394004ea9bef09e38dc071f;hp=b2a88781a2ef159313c16d15192a1358b4f7c26e;hb=df2cdcfdc29af0080b9b3eace17325d2a1d83e72;hpb=61cad7bbaf63389b520b695eefdd735bc11a8aa6

diff --git a/lib/whenutils.mli b/lib/whenutils.mli
index b2a8878..4d5ccc7 100644
--- a/lib/whenutils.mli
+++ b/lib/whenutils.mli
@@ -20,7 +20,7 @@
 
 module StringMap : sig
   type key = String.t
-  type 'a t = 'a Map.Make(String).t
+  type 'a t
   val empty : 'a t
   val is_empty : 'a t -> bool
   val mem : key -> 'a t -> bool
@@ -51,6 +51,39 @@ module StringMap : sig
 end
 (** A map from string to any type. *)
 
+module IntMap : sig
+  type key = int
+  type 'a t
+  val empty : 'a t
+  val is_empty : 'a t -> bool
+  val mem : key -> 'a t -> bool
+  val add : key -> 'a -> 'a t -> 'a t
+  (*val singleton : key -> 'a -> 'a t*)
+  val remove : key -> 'a t -> 'a t
+  (*val merge :
+    (key -> 'a option -> 'b option -> 'c option) -> 'a t -> 'b t -> 'c t*)
+  val compare : ('a -> 'a -> int) -> 'a t -> 'a t -> int
+  val equal : ('a -> 'a -> bool) -> 'a t -> 'a t -> bool
+  val iter : (key -> 'a -> unit) -> 'a t -> unit
+  val fold : (key -> 'a -> 'b -> 'b) -> 'a t -> 'b -> 'b
+  (*val for_all : (key -> 'a -> bool) -> 'a t -> bool
+  val exists : (key -> 'a -> bool) -> 'a t -> bool
+  val filter : (key -> 'a -> bool) -> 'a t -> 'a t
+  val partition : (key -> 'a -> bool) -> 'a t -> 'a t * 'a t
+  val cardinal : 'a t -> int
+  val bindings : 'a t -> (key * 'a) list
+  val min_binding : 'a t -> key * 'a
+  val max_binding : 'a t -> key * 'a
+  val choose : 'a t -> key * 'a
+  val split : key -> 'a t -> 'a t * 'a option * 'a t*)
+  val find : key -> 'a t -> 'a
+  val map : ('a -> 'b) -> 'a t -> 'b t
+  val mapi : (key -> 'a -> 'b) -> 'a t -> 'b t
+  val keys : 'a t -> key list
+  val values : 'a t -> 'a list
+end
+(** A map from int to any type. *)
+
 module StringSet : sig
   type elt = String.t
   type t = Set.Make(String).t
@@ -81,7 +114,18 @@ module StringSet : sig
 end
 (** A set of strings. *)
 
+val (//) : string -> string -> string
+(** [dir // file] concatenates directory and file. *)
+
+val isalpha : char -> bool
+val isalnum : char -> bool
+(** Character tests. *)
+
+val filter_map : ('a -> 'b option) -> 'a list -> 'b list
+(** Filter + map. *)
+
 type whenexpr =
+  | Expr_unit                           (** Unit constant. *)
   | Expr_bool of bool                   (** A boolean constant. *)
   | Expr_str of string                  (** A string constant. *)
   | Expr_int of Big_int.big_int         (** An integer constant. *)
@@ -89,9 +133,22 @@ type whenexpr =
   | Expr_var of string                  (** A variable name. *)
   | Expr_and of whenexpr * whenexpr     (** && *)
   | Expr_or of whenexpr * whenexpr      (** || *)
+  | Expr_lt of whenexpr * whenexpr      (** < *)
+  | Expr_le of whenexpr * whenexpr      (** <= *)
   | Expr_eq of whenexpr * whenexpr      (** == *)
-  | Expr_not of whenexpr                (** ! *)
+  | Expr_ge of whenexpr * whenexpr      (** >= *)
+  | Expr_gt of whenexpr * whenexpr      (** > *)
+  | Expr_not of whenexpr                (** boolean not *)
+  | Expr_add of whenexpr * whenexpr     (** arithmetic addition or string cat *)
+  | Expr_sub of whenexpr * whenexpr     (** arithmetic subtraction *)
+  | Expr_mul of whenexpr * whenexpr     (** arithmetic multiplication *)
+  | Expr_div of whenexpr * whenexpr     (** arithmetic division *)
+  | Expr_mod of whenexpr * whenexpr     (** arithmetic modulo *)
   | Expr_changes of string              (** changes var *)
+  | Expr_increases of string            (** increases var *)
+  | Expr_decreases of string            (** decreases var *)
+  | Expr_prev of string                 (** prev var *)
+  | Expr_reloaded                       (** reloaded () *)
 (** Internal type used to represent 'when' expressions. *)
 
 type periodexpr =
@@ -108,12 +165,15 @@ type shell_script = {
 (** A shell script. *)
 
 type variable =
+  | T_unit
   | T_bool of bool
   | T_string of string
   | T_int of Big_int.big_int
   | T_float of float
 (** Typed variable (see also [whenproto.x]) *)
 
+val string_of_variable : variable -> string
+
 val variable_of_rpc : Whenproto_aux.variable -> variable
 val rpc_of_variable : variable -> Whenproto_aux.variable
 
@@ -123,9 +183,6 @@ type variables = variable StringMap.t
 type job_private
 (** Private state associated with a job, used for evaluation. *)
 
-val no_job_private : job_private
-(* XXX any use of no_job_private is wrong XXX *)
-
 type job_cond =
   | When_job of whenexpr                (** when ... : << >> *)
   | Every_job of periodexpr             (** every ... : << >> *)
@@ -137,7 +194,15 @@ type job = {
   job_script : shell_script;
   job_private : job_private;
 }
-(** A job. *)
+(** A job.  Note that because of the [job_private] field, these cannot
+    be constructed directly.  Use {!make_when_job} or {!make_every_job}
+    to construct one. *)
+
+val make_when_job : Camlp4.PreCast.Loc.t -> string -> whenexpr -> shell_script -> job
+(** Make a when-statement job. *)
+
+val make_every_job : Camlp4.PreCast.Loc.t -> string -> periodexpr -> shell_script -> job
+(** Make an every-statement job. *)
 
 val expr_of_ast : Camlp4.PreCast.Ast.Loc.t -> Camlp4.PreCast.Ast.expr -> whenexpr
 (** Convert OCaml AST to an expression.  Since OCaml ASTs are much
@@ -157,9 +222,46 @@ val dependencies_of_whenexpr : whenexpr -> string list
 val dependencies_of_job : job -> string list
 (** Which variables does this job depend on? *)
 
-val job_evaluate : job -> variables -> bool * job
-(** Evaluate [job]'s condition in the context of the [variables], and
-    return [true] iff it should be run now.  Note that this returns a
-    possibly-updated [job] structure.
+val job_evaluate : job -> variables -> bool -> bool * job
+(** [job_evaluate job variables onload] evaluates [job]'s condition in
+    the context of the [variables], and return [true] iff it should be
+    run now.
+
+    Note that this returns a possibly-updated [job] structure.
 
     This is a no-op for 'every' jobs. *)
+
+val next_periodexpr : float -> periodexpr -> float
+(** [next_periodexpr t period] returns the earliest event of [period]
+    strictly after time [t].
+
+    Visualising periods as repeated events on a timeline, this
+    returns [t']:
+
+    {v
+    events:  ---+---------+---------+---------+---------+---------+-----
+    times:          t     t'
+    }
+
+    Note that [periodexpr] events are not necessarily regular.
+    eg. The start of a month is not a fixed number of seconds
+    after the start of the previous month.  'Epoch' refers
+    to the Unix Epoch (ie. 1970-01-01 00:00:00 UTC).
+
+    If [period = Every_seconds i] then events are when
+    [t' mod i == 0] when t' is the number of seconds since
+    the Epoch.  This returns the next t' > t.
+
+    If [period = Every_days i] then events happen at
+    midnight UTC every [i] days since the Epoch.
+    This returns the next midnight > t.
+
+    If [period = Every_months i] then events happen at
+    midnight UTC on the 1st day of the month every [i] months
+    since the Epoch.  This returns midnight on the
+    1st day of the next month > t.
+
+    If [period = Every_years i] then events happen at
+    midnight UTC on the 1st day of the year when
+    [(y - 1970) mod i == 0].  This returns midnight on the
+    1st day of the next year > t. *)