Implement 'whenjobs --test' to test the effect of variable setting.

[whenjobs.git] / tools / whenjobs.pod

diff --git a/tools/whenjobs.pod b/tools/whenjobs.pod
index 25dff40..120608b 100644 (file)
--- a/tools/whenjobs.pod
+++ b/tools/whenjobs.pod
@@ -14,7 +14,7 @@ Editing the jobs script:
 Get and set variables:
 
  whenjobs --get variable
 Get and set variables:
 
  whenjobs --get variable

- whenjobs --set variable value [--type bool|int|float|string]
+ whenjobs --set variable=value [variable=value ...]

  whenjobs --variables
 
 Start and stop the per-user daemon:
  whenjobs --variables
 
 Start and stop the per-user daemon:


@@ -29,6 +29,7 @@ Examine running jobs:
  whenjobs --jobs
  whenjobs --cancel serial
  whenjobs --start "name"
  whenjobs --jobs
  whenjobs --cancel serial
  whenjobs --start "name"

+ whenjobs --tail serial

 
 =head1 DESCRIPTION
 
 
 =head1 DESCRIPTION
 


@@ -42,7 +43,7 @@ Periodic jobs are written like this:
  <<
    # Get the current load average.
    load=`awk '{print $1}' /proc/loadavg`
  <<
    # Get the current load average.
    load=`awk '{print $1}' /proc/loadavg`

-   whenjobs --set load $load --type float
+   whenjobs --set --type float load=$load

  >>
 
 When-statements let you create jobs that run based on variables set
  >>
 
 When-statements let you create jobs that run based on variables set


@@ -79,7 +80,7 @@ command line tool to examine and set variables:
 
  $ whenjobs --variables
  load=0.9
 
  $ whenjobs --variables
  load=0.9

- $ whenjobs --set cat sushi
+ $ whenjobs --set cat=sushi

  $ whenjobs --get cat
  sushi
 
  $ whenjobs --get cat
  sushi
 


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

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

 =item B<--jobs>
 
 List all running jobs.
 =item B<--jobs>
 
 List all running jobs.


@@ -149,7 +155,7 @@ source, eg:
 
  whenjobs --lib $builddir/lib -e
 
 
  whenjobs --lib $builddir/lib -e
 

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

 
 =item B<--type> bool|int|float|string|unit
 
 
 =item B<--type> bool|int|float|string|unit
 


@@ -157,18 +163,33 @@ I<--set> sets the variable named C<variable> to the new C<value>.  The
 variable is created if it does not already exist.  Note that setting a
 variable can cause jobs to run immediately.
 
 variable is created if it does not already exist.  Note that setting a
 variable can cause jobs to run immediately.
 

-To unset a variable, set it to the empty string:
+To unset a variable, set it to the empty string like this:

 
 

- whenjobs --set var ""
+ whenjobs --set var=

 
 By default variables are strings.  You can also set the type of a
 
 By default variables are strings.  You can also set the type of a

-variable when setting it by adding the optional I<--type> parameter:
+variable when setting it by adding the optional I<--type> parameter.
+The I<--type> parameter should come I<before> the variable
+declaration, like this:

 
 

- whenjobs --set free_space 10000 --type int
+ whenjobs --set --type int free_space=10000

 
 See the discussion of variable types in the L</REFERENCE> section
 below.
 
 
 See the discussion of variable types in the L</REFERENCE> section
 below.
 

+You can set multiple variables.  When setting multiple variables in a
+single command, the values are all changed in a single atomic
+operation.
+
+ whenjobs --set cat=sushi food=fish
+
+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
+
+(C<cat> and C<food> are strings, and C<weight> is a float).
+

 =item B<--start> "job name"
 
 Start the job immediately and unconditionally.
 =item B<--start> "job name"
 
 Start the job immediately and unconditionally.


@@ -176,6 +197,22 @@ Start the job immediately and unconditionally.
 This runs the job even if its normal preconditions are not met.  This
 may cause unexpected results, so use with caution.
 
 This runs the job even if its normal preconditions are not met.  This
 may cause unexpected results, so use with caution.
 

+=item B<--tail> serial
+
+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 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>
 
 Compile the jobs script and upload it to the daemon, without editing.
 =item B<--upload>
 
 Compile the jobs script and upload it to the daemon, without editing.