(* 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.
 *)

(** Types and utility functions. *)

module StringMap : sig
  type key = String.t
  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 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
  val empty : t
  val is_empty : t -> bool
  val mem : elt -> t -> bool
  val add : elt -> t -> t
  val singleton : elt -> t
  val remove : elt -> t -> t
  val union : t -> t -> t
  val inter : t -> t -> t
  val diff : t -> t -> t
  val compare : t -> t -> int
  val equal : t -> t -> bool
  val subset : t -> t -> bool
  val iter : (elt -> unit) -> t -> unit
  val fold : (elt -> 'a -> 'a) -> t -> 'a -> 'a
  val for_all : (elt -> bool) -> t -> bool
  val exists : (elt -> bool) -> t -> bool
  val filter : (elt -> bool) -> t -> t
  val partition : (elt -> bool) -> t -> t * t
  val cardinal : t -> int
  val elements : t -> elt list
  val min_elt : t -> elt
  val max_elt : t -> elt
  val choose : t -> elt
  val split : elt -> t -> t * bool * t
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. *)
  | 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 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. *)