d9df5a92d5a58019b1e9b0fa2d8ccdb061fd4930
[whenjobs.git] / 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. *)