lib/whenstate.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 (** The state of jobs and variables. *)
  20
  21 type t
  22 (** This opaque, immutable type represents the state of jobs and
  23     variables from a loaded and running jobs file.
  24
  25     You can create an empty state by calling {!empty}.  This state
  26     has no jobs and no variables.
  27
  28     You can then add jobs and set variables by calling
  29     {!add_job} and {!set_variable}.  You can also copy variables
  30     from an old state to a new state (used when reloading the
  31     jobs file).
  32
  33     The rest of the functions deal with querying the state
  34     and are mainly used by the daemon (see [Daemon] module). *)
  35
  36 val empty : t
  37 (** Return an empty state.  This state has no jobs or variables. *)
  38
  39 val add_job : t -> Whenexpr.job -> t
  40 (** Add a job to the state, returning a new state. *)
  41
  42 val set_variable : t -> string -> Whenexpr.variable -> t
  43 (** Set/update the value of a variable, returning a new state. *)
  44
  45 val copy_variables : t -> t -> t
  46 (** [copy_variables old_state current_state -> new_state] copies
  47     the variables from [old_state], adding them to [current_state],
  48     returning a new state.  Note the order of arguments. *)
  49
  50 val get_variable : t -> string -> Whenexpr.variable
  51 (** Return the value of a variable, when unknown variables defaulting
  52     to empty string. *)
  53
  54 val get_variables : t -> (string * Whenexpr.variable) list
  55 (** Return the value of all variables.  Variables that are empty
  56     strings are not returned. *)
  57
  58 val get_variable_names : t -> string list
  59 (** Return all variable names.  Variables that are empty strings are
  60     ignored. *)
  61
  62 val nr_jobs : t -> int
  63 (** Returns the number of jobs in the state. *)
  64
  65 val get_dependencies : t -> string -> Whenexpr.job list
  66 (** Return the jobs which depend on the named variable. *)
  67
  68 val get_whenjobs : t -> Whenexpr.job list
  69 val get_everyjobs : t -> Whenexpr.job list
  70 (** Return all of the when-jobs / every-jobs. *)
  71
  72 val get_job : t -> string -> Whenexpr.job
  73 (** Return the named job. *)
  74
  75 val evaluate_whenjob : ?onload:bool -> t -> Whenexpr.job -> bool * t
  76 (** This evaluates the whenjob and returns [true] iff the whenjob
  77     should be run now.
  78
  79     Note that this returns a possibly-updated state structure. *)