--- /dev/null
+(* whenjobs
+ * Copyright (C) 2012 Red Hat Inc.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License along
+ * with this program; if not, write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+ *)
+
+(** When- and every-expression definition and evaluation, variables
+ and jobs. *)
+
+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. *)
+ | Expr_float of float (** A float constant. *)
+ | 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_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 =
+ | Every_seconds of int
+ | Every_days of int
+ | Every_months of int
+ | Every_years of int
+(** Internal type used to represent 'every' expressions. *)
+
+type shell_script = {
+ sh_loc : Camlp4.PreCast.Loc.t;
+ sh_script : string;
+}
+(** 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
+
+type variables = variable Whenutils.StringMap.t
+(** A set of variables. *)
+
+type job_private
+(** Private state associated with a job, used for evaluation. *)
+
+type job_cond =
+ | When_job of whenexpr (** when ... : << >> *)
+ | Every_job of periodexpr (** every ... : << >> *)
+
+type job = {
+ job_loc : Camlp4.PreCast.Loc.t;
+ job_name : string;
+ job_cond : job_cond;
+ job_script : shell_script;
+ job_private : job_private;
+}
+(** 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
+ more general than the expressions we can use, this can raise
+ [Invalid_argument] in many different situations. *)
+
+val string_of_whenexpr : whenexpr -> string
+(** Pretty-print an expression to a string. *)
+
+val string_of_periodexpr : periodexpr -> string
+(** Pretty-print a period expression to a string. *)
+
+val dependencies_of_whenexpr : whenexpr -> string list
+(** Return list of variables that an expression depends on. This is
+ used to work out when an expression needs to be reevaluated. *)
+
+val dependencies_of_job : job -> string list
+(** Which variables does this job depend on? *)
+
+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. *)
git.annexia.org / whenjobs.git / blobdiff