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_ne of whenexpr * whenexpr      (** != *)
  37   | Expr_not of whenexpr                (** boolean not *)
  38   | Expr_add of whenexpr * whenexpr     (** arithmetic addition or string cat *)
  39   | Expr_sub of whenexpr * whenexpr     (** arithmetic subtraction *)
  40   | Expr_mul of whenexpr * whenexpr     (** arithmetic multiplication *)
  41   | Expr_div of whenexpr * whenexpr     (** arithmetic division *)
  42   | Expr_mod of whenexpr * whenexpr     (** arithmetic modulo *)
  43   | Expr_len of whenexpr                (** length *)
  44   | Expr_changes of string              (** changes var *)
  45   | Expr_increases of string            (** increases var *)
  46   | Expr_decreases of string            (** decreases var *)
  47   | Expr_prev of string                 (** prev var *)
  48   | Expr_reloaded                       (** reloaded () *)
  49 (** Internal type used to represent 'when' expressions. *)
  50
  51 type periodexpr =
  52   | Every_seconds of int
  53   | Every_days of int
  54   | Every_months of int
  55   | Every_years of int
  56 (** Internal type used to represent 'every' expressions. *)
  57
  58 type shell_script = {
  59   sh_loc : Camlp4.PreCast.Loc.t;
  60   sh_script : string;
  61 }
  62 (** A shell script. *)
  63
  64 type variable =
  65   | T_unit
  66   | T_bool of bool
  67   | T_string of string
  68   | T_int of Big_int.big_int
  69   | T_float of float
  70 (** Typed variable (see also [whenproto.x]) *)
  71
  72 val string_of_variable : variable -> string
  73
  74 val variable_of_rpc : Whenproto_aux.variable -> variable
  75 val rpc_of_variable : variable -> Whenproto_aux.variable
  76
  77 type variables = variable Whenutils.StringMap.t
  78 (** A set of variables. *)
  79
  80 type preinfo = {
  81   pi_job_name : string;                 (** Job name. *)
  82   pi_serial : Big_int.big_int;          (** Job serial number. *)
  83   pi_variables : (string * variable) list; (** Variables set in job. *)
  84   pi_running : preinfo_running_job list; (** List of running jobs. *)
  85 }
  86 and preinfo_running_job = {
  87   pirun_job_name : string;              (** Running job name. *)
  88   pirun_serial : Big_int.big_int;       (** Running job serial number. *)
  89   pirun_start_time : float;             (** Running job start time. *)
  90   pirun_pid : int;                      (** Running job process ID. *)
  91 }
  92 (** Information available to pre function before the job runs. *)
  93
  94 type result = {
  95   res_job_name : string;                (** Job name. *)
  96   res_serial : Big_int.big_int;         (** Job serial number. *)
  97   res_code : int;                       (** Return code from the script. *)
  98   res_tmpdir : string;                  (** Temporary directory. *)
  99   res_output : string;                  (** Filename of output from job. *)
 100   res_start_time : float;               (** When the job started. *)
 101 }
 102 (** Result of the run of a job. *)
 103
 104 type pre = preinfo -> bool
 105 type post = result -> unit
 106 (** Pre and post functions. *)
 107
 108 type job_cond =
 109   | When_job of whenexpr                (** when ... : << >> *)
 110   | Every_job of periodexpr             (** every ... : << >> *)
 111
 112 type job = {
 113   job_loc : Camlp4.PreCast.Loc.t;
 114   job_name : string;
 115   job_pre : pre option;
 116   job_post : post option;
 117   job_cond : job_cond;
 118   job_script : shell_script;
 119 }
 120 (** A job. *)
 121
 122 val expr_of_ast : Camlp4.PreCast.Ast.Loc.t -> Camlp4.PreCast.Ast.expr -> whenexpr
 123 (** Convert OCaml AST to an expression.  Since OCaml ASTs are much
 124     more general than the expressions we can use, this can raise
 125     [Invalid_argument] in many different situations. *)
 126
 127 val string_of_whenexpr : whenexpr -> string
 128 (** Pretty-print an expression to a string. *)
 129
 130 val string_of_periodexpr : periodexpr -> string
 131 (** Pretty-print a period expression to a string. *)
 132
 133 val dependencies_of_whenexpr : whenexpr -> string list
 134 (** Return list of variables that an expression depends on.  This is
 135     used to work out when an expression needs to be reevaluated. *)
 136
 137 val dependencies_of_job : job -> string list
 138 (** Which variables does this job depend on? *)
 139
 140 val eval_whenexpr : variables -> variables option -> bool -> whenexpr -> variable
 141 val eval_whenexpr_as_bool : variables -> variables option -> bool -> whenexpr -> bool
 142 (** [eval_whenexpr variables prev_variables onload expr] is the
 143     evaluation function for when expressions.  It full evaluates
 144     [expr], returning its typed value.  It can also throw exceptions
 145     (at least [Invalid_argument] and [Failure]).
 146
 147     [eval_whenexpr_as_bool] is the same but it forces the returned
 148     value to be a boolean.
 149
 150     The other parameters represent the current and past state:
 151
 152     [variables] is the current set of variables and their values.
 153
 154     [prev_variables] is the set of variables from the previous
 155     run.  It is used to implement {i prev}, {i changes} etc operators.
 156     This can be [None], meaning there is no previous state.
 157
 158     [onload] is used to implement the {i reloaded} operator.  It is
 159     true if the file is being reloaded, and false otherwise. *)
 160
 161 val next_periodexpr : float -> periodexpr -> float
 162 (** [next_periodexpr t period] returns the earliest event of [period]
 163     strictly after time [t].
 164
 165     Visualising periods as repeated events on a timeline, this
 166     returns [t']:
 167
 168     {v
 169     events:  ---+---------+---------+---------+---------+---------+-----
 170     times:          t     t'
 171     }
 172
 173     Note that [periodexpr] events are not necessarily regular.
 174     eg. The start of a month is not a fixed number of seconds
 175     after the start of the previous month.  'Epoch' refers
 176     to the Unix Epoch (ie. 1970-01-01 00:00:00 UTC).
 177
 178     If [period = Every_seconds i] then events are when
 179     [t' mod i == 0] when t' is the number of seconds since
 180     the Epoch.  This returns the next t' > t.
 181
 182     If [period = Every_days i] then events happen at
 183     midnight UTC every [i] days since the Epoch.
 184     This returns the next midnight > t.
 185
 186     If [period = Every_months i] then events happen at
 187     midnight UTC on the 1st day of the month every [i] months
 188     since the Epoch.  This returns midnight on the
 189     1st day of the next month > t.
 190
 191     If [period = Every_years i] then events happen at
 192     midnight UTC on the 1st day of the year when
 193     [(y - 1970) mod i == 0].  This returns midnight on the
 194     1st day of the next year > t. *)
 195
 196 val check_valid_variable_name : string -> unit
 197 (** Check that [name] is a valid variable name that users are permitted
 198     to set, and raise [Failure] if it is not.  *)