Implement 'whenjobs --job-names' which lists all loaded jobs.

[whenjobs.git] / tools / whenjobs.pod

diff --git a/tools/whenjobs.pod b/tools/whenjobs.pod
index 466bdb1..7c9e8ee 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
 
@@ -127,6 +127,11 @@ C<vi> is used.
 
 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.
@@ -150,7 +155,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 +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.
 
-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.