3c05826aa277d995012632656308dcb61b67481f
[whenjobs.git] / lib / whenexpr.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 (** When- and every-expression definition and evaluation, variables
20     and jobs. *)
21
22 type whenexpr =
23   | Expr_unit                           (** Unit constant. *)
24   | Expr_bool of bool                   (** A boolean constant. *)
25   | Expr_str of string                  (** A string constant. *)
26   | Expr_int of Big_int.big_int         (** An integer constant. *)
27   | Expr_float of float                 (** A float constant. *)
28   | Expr_var of string                  (** A variable name. *)
29   | Expr_and of whenexpr * whenexpr     (** && *)
30   | Expr_or of whenexpr * whenexpr      (** || *)
31   | Expr_lt of whenexpr * whenexpr      (** < *)
32   | Expr_le of whenexpr * whenexpr      (** <= *)
33   | Expr_eq of whenexpr * whenexpr      (** == *)
34   | Expr_ge of whenexpr * whenexpr      (** >= *)
35   | Expr_gt of whenexpr * whenexpr      (** > *)
36   | Expr_not of whenexpr                (** boolean not *)
37   | Expr_add of whenexpr * whenexpr     (** arithmetic addition or string cat *)
38   | Expr_sub of whenexpr * whenexpr     (** arithmetic subtraction *)
39   | Expr_mul of whenexpr * whenexpr     (** arithmetic multiplication *)
40   | Expr_div of whenexpr * whenexpr     (** arithmetic division *)
41   | Expr_mod of whenexpr * whenexpr     (** arithmetic modulo *)
42   | Expr_changes of string              (** changes var *)
43   | Expr_increases of string            (** increases var *)
44   | Expr_decreases of string            (** decreases var *)
45   | Expr_prev of string                 (** prev var *)
46   | Expr_reloaded                       (** reloaded () *)
47 (** Internal type used to represent 'when' expressions. *)
48
49 type periodexpr =
50   | Every_seconds of int
51   | Every_days of int
52   | Every_months of int
53   | Every_years of int
54 (** Internal type used to represent 'every' expressions. *)
55
56 type shell_script = {
57   sh_loc : Camlp4.PreCast.Loc.t;
58   sh_script : string;
59 }
60 (** A shell script. *)
61
62 type variable =
63   | T_unit
64   | T_bool of bool
65   | T_string of string
66   | T_int of Big_int.big_int
67   | T_float of float
68 (** Typed variable (see also [whenproto.x]) *)
69
70 val string_of_variable : variable -> string
71
72 val variable_of_rpc : Whenproto_aux.variable -> variable
73 val rpc_of_variable : variable -> Whenproto_aux.variable
74
75 type variables = variable Whenutils.StringMap.t
76 (** A set of variables. *)
77
78 type job_private
79 (** Private state associated with a job, used for evaluation. *)
80
81 type job_cond =
82   | When_job of whenexpr                (** when ... : << >> *)
83   | Every_job of periodexpr             (** every ... : << >> *)
84
85 type job = {
86   job_loc : Camlp4.PreCast.Loc.t;
87   job_name : string;
88   job_cond : job_cond;
89   job_script : shell_script;
90   job_private : job_private;
91 }
92 (** A job.  Note that because of the [job_private] field, these cannot
93     be constructed directly.  Use {!make_when_job} or {!make_every_job}
94     to construct one. *)
95
96 val make_when_job : Camlp4.PreCast.Loc.t -> string -> whenexpr -> shell_script -> job
97 (** Make a when-statement job. *)
98
99 val make_every_job : Camlp4.PreCast.Loc.t -> string -> periodexpr -> shell_script -> job
100 (** Make an every-statement job. *)
101
102 val expr_of_ast : Camlp4.PreCast.Ast.Loc.t -> Camlp4.PreCast.Ast.expr -> whenexpr
103 (** Convert OCaml AST to an expression.  Since OCaml ASTs are much
104     more general than the expressions we can use, this can raise
105     [Invalid_argument] in many different situations. *)
106
107 val string_of_whenexpr : whenexpr -> string
108 (** Pretty-print an expression to a string. *)
109
110 val string_of_periodexpr : periodexpr -> string
111 (** Pretty-print a period expression to a string. *)
112
113 val dependencies_of_whenexpr : whenexpr -> string list
114 (** Return list of variables that an expression depends on.  This is
115     used to work out when an expression needs to be reevaluated. *)
116
117 val dependencies_of_job : job -> string list
118 (** Which variables does this job depend on? *)
119
120 val job_evaluate : job -> variables -> bool -> bool * job
121 (** [job_evaluate job variables onload] evaluates [job]'s condition in
122     the context of the [variables], and return [true] iff it should be
123     run now.
124
125     Note that this returns a possibly-updated [job] structure.
126
127     This is a no-op for 'every' jobs. *)
128
129 val next_periodexpr : float -> periodexpr -> float
130 (** [next_periodexpr t period] returns the earliest event of [period]
131     strictly after time [t].
132
133     Visualising periods as repeated events on a timeline, this
134     returns [t']:
135
136     {v
137     events:  ---+---------+---------+---------+---------+---------+-----
138     times:          t     t'
139     }
140
141     Note that [periodexpr] events are not necessarily regular.
142     eg. The start of a month is not a fixed number of seconds
143     after the start of the previous month.  'Epoch' refers
144     to the Unix Epoch (ie. 1970-01-01 00:00:00 UTC).
145
146     If [period = Every_seconds i] then events are when
147     [t' mod i == 0] when t' is the number of seconds since
148     the Epoch.  This returns the next t' > t.
149
150     If [period = Every_days i] then events happen at
151     midnight UTC every [i] days since the Epoch.
152     This returns the next midnight > t.
153
154     If [period = Every_months i] then events happen at
155     midnight UTC on the 1st day of the month every [i] months
156     since the Epoch.  This returns midnight on the
157     1st day of the next month > t.
158
159     If [period = Every_years i] then events happen at
160     midnight UTC on the 1st day of the year when
161     [(y - 1970) mod i == 0].  This returns midnight on the
162     1st day of the next year > t. *)