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 copy_prev_state : t -> t -> t
  51 (** [copy_prev_state old_state current_state -> new_state] is an
  52     obscure function used to make the [prev] function work predictably
  53     across file reloads.  Since a file reload creates a new state
  54     object, it would normally "forget" that jobs had run previously,
  55     so any job that used [prev], [changes] etc would run again
  56     unnecessarily.  This function copies the prev state, allowing us
  57     to remember which jobs ran previously and the state of the
  58     variables at that time, making these functions work predictably.
  59     State is only copied for jobs that have explicit names. *)
  60
  61 val get_variable : t -> string -> Whenexpr.variable
  62 (** Return the value of a variable, when unknown variables defaulting
  63     to empty string. *)
  64
  65 val get_variables : t -> (string * Whenexpr.variable) list
  66 (** Return the value of all variables.  Variables that are empty
  67     strings are not returned. *)
  68
  69 val get_variable_names : t -> string list
  70 (** Return all variable names.  Variables that are empty strings are
  71     ignored. *)
  72
  73 val nr_jobs : t -> int
  74 (** Returns the number of jobs in the state. *)
  75
  76 val get_dependencies : t -> string list -> Whenexpr.job list
  77 (** Return the jobs which depend on the named variables. *)
  78
  79 val get_whenjobs : t -> Whenexpr.job list
  80 val get_everyjobs : t -> Whenexpr.job list
  81 (** Return all of the when-jobs / every-jobs. *)
  82
  83 val get_job : t -> string -> Whenexpr.job
  84 (** Return the named job, or raise [Not_found]. *)
  85
  86 val evaluate_whenjob : ?onload:bool -> t -> Whenexpr.job -> bool * t
  87 (** This evaluates the whenjob and returns [true] iff the whenjob
  88     should be run now.
  89
  90     Note that this returns a possibly-updated state structure. *)