Implement cleanup functions, including 'mailto'.

[whenjobs.git] / tools / whenjobs.pod

diff --git a/tools/whenjobs.pod b/tools/whenjobs.pod
index 368f413..fd0a6e7 100644 (file)
--- a/tools/whenjobs.pod
+++ b/tools/whenjobs.pod
@@ -564,10 +564,73 @@ this example:
    Whentools.set_variable "name" "Richard";
    Whentools.set_variable_int "counter" 0
 
+=head3 CLEANUP FUNCTIONS
+
+After a job runs, you can control what happens to its output by
+writing a cleanup function.  To write a cleanup function you have to
+name the job (ie. have an explicit C<job> statement).  Put C<cleanup ...>
+after the job name like this:
+
+ job "poll source"
+ cleanup (Whentools.mailto "you@example.com")
+ every 10 seconds :
+ <<
+   # ...
+ >>
+
+A number of cleanup functions are available in the library; see below.
+
+You can also write your own cleanup functions (in OCaml).  The
+function is passed one argument which is a C<Whentools.result> struct,
+defined below.
+
 =head3 WHENTOOLS LIBRARY
 
+=head4 Functions
+
 =over 4
 
+=item B<Whentools.mailto> [I<~only_on_failure:true>]
+[I<~from:from_address>] I<email_address> I<result>
+
+Send the result of the script by email to the given email address.
+
+If the optional C<~only_on_failure:true> flag is set, then it is only
+sent out if the script failed.
+
+If the optional C<~from> flag is set, then the from address is set
+accordingly.  This is sometimes needed when sending mail.
+
+Note the C<result> parameter is passed implicitly by the daemon.  You
+do not need to add it.
+
+Here are some examples of using the mailto function:
+
+ job "ex.1"
+ cleanup (Whentools.mailto "you@example.com")
+ every 10 seconds :
+ <<
+   # do something
+ >>
+
+ job "ex.2"
+ cleanup (Whentools.mailto ~only_on_failure:true
+                           "you@example.com")
+ every 10 seconds :
+ <<
+   # do something
+ >>
+
+ let from = "me@example.com"
+ let to_addr = "you@example.com"
+ 
+ job "ex.3"
+ cleanup (Whentools.mailto ~from to_addr)
+ every 10 seconds :
+ <<
+   # do something
+ >>
+
 =item B<Whentools.set_variable> I<name> I<string>
 
 Set variable I<name> to the string.
@@ -591,6 +654,24 @@ Set variable I<name> to the floating point value I<f>.
 
 =back
 
+=head4 Structures
+
+=over 4
+
+=item B<Whentools.result>
+
+This structure is passed to cleanup functions.  It has the following
+fields:
+
+ type result = {
+   res_job_name : string; # job name
+   res_code : int;        # return code from the shell script
+   res_tmpdir : string;   # temporary directory script ran in
+   res_output : string;   # filename of stdout/stderr output
+ }
+
+=back
+
 =head1 FILES