1 09/12/86  value_list, vls
  2 
  3 Syntax as a command:  vls {name} {-control_args}
  4 
  5 
  6 Syntax as an active function:  [vls {name} {-control_args}]
  7 
  8 
  9 Function: lists one or more name-value pairs as set by value_set and
 10 value_get -call.
 11 
 12 
 13 Arguments:
 14 name
 15    is a character string.  It can be -name STR to specify a name
 16    beginning with a minus sign, to distinguish it from a control
 17    argument.  (See "Notes.")
 18 
 19 
 20 Control arguments:
 21 -all, -a
 22    lists variables set by value_$set_data in addition to the variables
 23    set by value_$set and the value commands.  These are listed in the
 24    form
 25       foo              (N words)
 26    Word counts alone are listed for data variables since their values
 27    have meaning only to the caller of value_.  If you give no -all, the
 28    default is to omit the data variables.
 29 -brief, -bf
 30    suppresses the error messages allowed by -long.
 31 -data
 32    lists only the values set by value_$set_data.
 33 
 34 
 35 -depth N, -dh N
 36    lists the latest N-1 pushed values for any variable in addition to
 37    the current value.  Any further pushed values result in the message
 38    "(M more pushed values)".  The default is to print the latest value
 39    followed by the message "(M pushed values)".  In the active
 40    function, -depth returns only the latest N values.
 41 -exclude STR, -ex STR
 42    lists all values except those for names that match STR.  The
 43    character string STR is searched for in names: if it is surrounded
 44    by slashes (/), it is interpreted as a qedx regular expression to
 45    match names; otherwise it is interpreted as a starname.  Only
 46    per-process values are listed if you supply -perprocess, and only
 47    permanent ones if you give -permanent.  (See "Notes.")
 48 
 49 
 50 -long, -lg
 51    allows the error messages "Name not found" and "No match for..."
 52    for individual name and -match arguments.  (Default)
 53 -match STR
 54    lists all values for names that match STR.  The character string STR
 55    is searched for in names: if it is surrounded by slashes (/), it is
 56    interpreted as a qedx regular expression to match names; otherwise
 57    it is interpreted as a starname.  Only per-process values are listed
 58    if you supply -perprocess, and only permanent ones if you give
 59    -permanent.  (See "Notes.")
 60 -pathname path, -pn path
 61    specifies a value segment other than the current default one,
 62    without changing the default (see "Notes on value segment").  You
 63    are allowed multiple -pathname control arguments to list values in
 64    more than one value segment.
 65 
 66 
 67 -permanent, -perm
 68    lists only values stored in the value segment.
 69 -perprocess, -pp
 70    lists only per-process values.
 71 -value, -val
 72    lists values only.
 73 -variable, -var
 74    lists variable names only.
 75 
 76 
 77 Access required: You require read access on the value segment, except
 78 for per-process values.
 79 
 80 
 81 Notes: The list is sorted alphabetically by name, the per-process
 82 value first where both exist.
 83 
 84 By default, this command lists both variable names and values, and both
 85 per-process and permanent values interspersed, the per-process names
 86 preceded by "(P)".
 87 
 88 Either -value or -variable is required by the active function.  The
 89 active function returns the selected names or values separated by
 90 spaces.
 91 
 92 
 93 The -match and -exclude control arguments are applied in the order
 94 specified.  Successive -match control arguments add to the set of names
 95 processed (union), and successive -exclude control arguments narrow
 96 down the set (intersection).  They are incompatible with the name
 97 argument and can appear multiple times together.
 98 
 99 See value_defined, value_delete, value_get, value_path, value_set, and
100 value_set_path.
101 
102 
103 Notes on value segment: The value segment searched is either the one
104 supplied by -pathname or the current default value segment.  The
105 default segment is initially
106    [home_dir]>[user name].value
107 but you can change it by value_set_path.  Use of -pathname does not
108 change the default segment.