Change whenjobs --set syntax (NOTE: breaks compatibility).

[whenjobs.git] / tools / whenjobs.pod

diff --git a/tools/whenjobs.pod b/tools/whenjobs.pod
index 466bdb1..5750646 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
- whenjobs --set variable value [--type bool|int|float|string]
+ whenjobs --set variable=value [variable=value ...]
  whenjobs --variables
 
 Start and stop the per-user daemon:
@@ -43,7 +43,7 @@ Periodic jobs are written like this:
  <<
    # 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
@@ -80,7 +80,7 @@ command line tool to examine and set variables:
 
  $ whenjobs --variables
  load=0.9
- $ whenjobs --set cat sushi
+ $ whenjobs --set cat=sushi
  $ whenjobs --get cat
  sushi
 
@@ -150,7 +150,7 @@ source, eg:
 
  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
 
@@ -158,18 +158,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.
 
-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
-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.
 
+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.