Copy previous variables / eval result across file reloads.

[whenjobs.git] / lib / whenstate.mli

diff --git a/lib/whenstate.mli b/lib/whenstate.mli
index 084cd49..15df0c1 100644 (file)
--- a/lib/whenstate.mli
+++ b/lib/whenstate.mli
@@ -47,6 +47,17 @@ val copy_variables : t -> t -> t
     the variables from [old_state], adding them to [current_state],
     returning a new state.  Note the order of arguments. *)
 
+val copy_prev_state : t -> t -> t
+(** [copy_prev_state old_state current_state -> new_state] is an
+    obscure function used to make the [prev] function work predictably
+    across file reloads.  Since a file reload creates a new state
+    object, it would normally "forget" that jobs had run previously,
+    so any job that used [prev], [changes] etc would run again
+    unnecessarily.  This function copies the prev state, allowing us
+    to remember which jobs ran previously and the state of the
+    variables at that time, making these functions work predictably.
+    State is only copied for jobs that have explicit names. *)
+
 val get_variable : t -> string -> Whenexpr.variable
 (** Return the value of a variable, when unknown variables defaulting
     to empty string. *)