Persist variables to file (~/.whenjobs/variables).

[whenjobs.git] / tools / whenjobs.pod

diff --git a/tools/whenjobs.pod b/tools/whenjobs.pod
index 7c9e8ee..8455bcf 100644 (file)
--- a/tools/whenjobs.pod
+++ b/tools/whenjobs.pod
@@ -79,12 +79,41 @@ Variables are stored (per-user) in the daemon.  You can use the
 command line tool to examine and set variables:
 
  $ whenjobs --variables
 command line tool to examine and set variables:
 
  $ whenjobs --variables

- load=0.9
+ JOBSERIAL=297
+ libguestfs_build_local=1.17.16
+ libguestfs_commit=7e32d892d76a31f55e2a4151902623b9949e3efa
+ libguestfs_dist=1.17.16
+ libguestfs_release=1.17.16
+ libguestfs_stable_build_local=1.16.10
+ libguestfs_stable_commit=27433a0a335301441b1eb6244ba425c2c44b2d99
+ libguestfs_stable_dist=1.16.10
+ libguestfs_stable_release=1.16.10
+ libguestfs_stable_version=1.16.10
+ libguestfs_version=1.17.16

  $ whenjobs --set cat=sushi
  $ whenjobs --get cat
  sushi
 
  $ whenjobs --set cat=sushi
  $ whenjobs --get cat
  sushi
 

-The act of setting a variable (using I<--set>) can trigger jobs to run.
+Note: The act of setting a variable (using I<--set>) can trigger jobs
+to run.
+
+You can also list out what jobs are running:
+
+ $ whenjobs --jobs
+ 287 libguestfs-stable: fedora 16
+    running in: /tmp/whenjobsa2afc44fd757465f95438309f1a51609
+    started at: 2012-03-13 10:59:37
+
+and you can 'tail' the output of running jobs which is useful for
+debugging:
+
+ $ whenjobs --tail 287
+ Uploading: 147496271972717053d46b82a07435ca  libguestfs-1.16.10.tar.gz
+
+You can start and cancel jobs manually:
+
+ $ whenjobs --start 'libguestfs: poll'
+ $ whenjobs --cancel 287

 
 =head1 OPTIONS
 
 
 =head1 OPTIONS
 


@@ -127,6 +156,12 @@ C<vi> is used.
 
 Print the value of a variable.
 
 
 Print the value of a variable.
 

+=item B<-help>
+
+=item B<--help>
+
+Display brief usage and exit.
+

 =item B<--job-names>
 
 List the names of all loaded jobs (whether they are running or not).
 =item B<--job-names>
 
 List the names of all loaded jobs (whether they are running or not).


@@ -186,7 +221,9 @@ operation.
 When using I<--type> and multiple variables, the type changes the
 remaining command line parameters until the next I<--type>, eg:
 
 When using I<--type> and multiple variables, the type changes the
 remaining command line parameters until the next I<--type>, eg:
 

- whenjobs --set cat=sushi --type float weight=3.5 --type string food=fish
+ whenjobs --set cat=sushi \
+     --type float weight=3.5 \
+     --type string food=fish

 
 (C<cat> and C<food> are strings, and C<weight> is a float).
 
 
 (C<cat> and C<food> are strings, and C<weight> is a float).
 


@@ -202,13 +239,26 @@ may cause unexpected results, so use with caution.
 Tail the output of the running job identified by its serial number.
 Use the I<--jobs> flag to get a list of running jobs.
 
 Tail the output of the running job identified by its serial number.
 Use the I<--jobs> flag to get a list of running jobs.
 

+=item B<--test> variable=value [variable=value ...]
+
+This works the same way as the I<--set> option, but the difference is
+that the variables are not set.  Instead, it lists out the jobs that
+I<would> run, I<if> the variables were updated to these new values.
+
+The variables are not actually updated, and the jobs are not actually
+run.
+
+The output is a list of job names that would run.
+

 =item B<--upload>
 
 =item B<--upload>
 

-Compile the jobs script and upload it to the daemon, without editing.
+Compile the jobs file(s) and upload it to the daemon, without editing.

 Note that the I<--edit> option does this automatically.  Furthermore,
 when the daemon is started it checks for a jobs script and loads it if
 found.
 
 Note that the I<--edit> option does this automatically.  Furthermore,
 when the daemon is started it checks for a jobs script and loads it if
 found.
 

+See also L</MULTIPLE JOBS FILES> below.
+

 =item B<--variables>
 
 Display all the variables and their values, in the format C<name=value>.
 =item B<--variables>
 
 Display all the variables and their values, in the format C<name=value>.


@@ -219,11 +269,24 @@ Display all the variables and their values, in the format C<name=value>.
 
 Display the name and version of the program and exit.
 
 
 Display the name and version of the program and exit.
 

-=item B<-help>
+=item B<--whisper> variable=value [variable=value ...]

 
 

-=item B<--help>
+This works the same way as the I<--set> option, but with the
+difference that jobs' when clauses are not reevaluated.  In other
+words, the variables are set, but "quietly" so as not to trigger any
+jobs to run.

 
 

-Display brief usage and exit.
+Note that this can lead to some unexpected results: one case is a
+job such as:
+
+ when changed a || changed b : << ... >>
+
+If C<a> is changed using I<--whisper>, then the job will not run.
+
+But later on, if C<b> is set but to the same value that it already has
+(ie. not changed), the job will run because the whole when-clause is
+reevaluated and C<a> is found to have changed since the last run of
+the job.

 
 =back
 
 
 =back
 


@@ -343,7 +406,7 @@ A when statement has the form:
  >>
 
 where C<E<lt>exprE<gt>> is a I<when expression>, described below.
  >>
 
 where C<E<lt>exprE<gt>> is a I<when expression>, described below.

-Don't forget the colon character between the period expression and the
+Don't forget the colon character between the expression and the

 shell script.
 
 A when statement is a job which runs when the conditions described in
 shell script.
 
 A when statement is a job which runs when the conditions described in


@@ -384,6 +447,12 @@ If the sub-expressions are numeric, then numeric comparison is done.
 If either sub-expression is non-numeric, then both expressions are
 converted (if necessary) to strings and string comparison is done.
 
 If either sub-expression is non-numeric, then both expressions are
 converted (if necessary) to strings and string comparison is done.
 

+=item I<expr> B<E<lt>E<gt>> I<expr>
+
+=item I<expr> B<!=> I<expr>
+
+Either form can be used to test the two expressions for inequality.
+

 =item B<!> I<expr>
 
 Boolean negative of I<expr>.
 =item B<!> I<expr>
 
 Boolean negative of I<expr>.


@@ -439,7 +508,7 @@ uploaded, try giving the jobs an explicit name.
 If the named variable has changed since this job last ran, then this
 evaluates to true, else false.
 
 If the named variable has changed since this job last ran, then this
 evaluates to true, else false.
 

-This is the same as writing C<prev variable == variable>.
+This is the same as writing C<prev variable != variable>.

 
 =item B<increases> I<variable>
 
 
 =item B<increases> I<variable>
 


@@ -799,6 +868,53 @@ fields:
 
 =back
 
 
 =back
 

+=head1 MULTIPLE JOBS FILES
+
+The whenjobs I<-e> and I<-l> options edit and list a file called
+C<$HOME/.whenjobs/jobs.ml>.
+
+You can also edit C<$HOME/.whenjobs/jobs.ml> by other means (eg.  your
+own editor).  After editing, to recompile and upload it, use:
+
+ whenjobs --upload
+
+When you have lots of jobs, it is convenient to split the jobs across
+multiple files.  Any C<*.ml> files located in C<$HOME/.whenjobs> can
+be used (with some restrictions on filenames -- see below).  These are
+compiled and loaded into the daemon using the I<--upload> command.
+
+To create multiple jobs files, you cannot use the I<-e> or I<-l>
+options.  Instead you have to create them yourself in
+C<$HOME/.whenjobs>, and when you have finished creating or editing
+them, upload them.
+
+=head2 FILENAME RESTRICTIONS ON JOBS FILES
+
+In OCaml, a file called C<jobs.ml> corresponds to an OCaml module
+called C<Jobs> (note the capitalization).  OCaml module names can only
+contain ASCII alphanumeric characters, underscore, and C<'> (single
+quote), and they must begin with an alphabetic character.  The same
+rules apply to jobs files.
+
+Furthermore, various OCaml module names are reserved (eg. C<Map>,
+C<List>).  It is therefore better to prefix any names with something
+specific to your application.
+
+Examples of legal filenames are:
+
+ foo.ml
+ app_foo.ml
+ app_123.ml
+ jobs.ml
+
+Examples of illegal filenames are:
+
+ ann.txt    # must end with .ml
+ 123.ml     # must begin with alphabetic
+ app!.ml    # must contain alphanumeric or underscore
+ app-foo.ml # must contain alphanumeric or underscore
+ map.ml     # reserved module name
+

 =head1 FILES
 
 
 =head1 FILES