docs/todo-vars

   1 Specification of fvwm variables
   2 -------------------------------
   3
   4 Anything that looks like $[VAR] in fvwm command is a variable and a subject
   5 for expanding. There are 2 kinds of variables, user defined and built-in.
   6
   7 If the requested variable MY_VAR is not defined, it is not expanded in
   8 the command, i.e. the literal text "$[MY_VAR]" is left as is.
   9
  10 User defined variables
  11 ----------------------
  12
  13 A user may manage his variables using SetEnv and UnsetEnv commands,
  14 and query them using Test command options EnvIsSet and EnvMatch.
  15
  16 All shell variables that were defined on the fvwm startup are available,
  17 like $[HOME]. New invoked processes will inherit all these variables
  18 plus all new ones added by SetEnv. User variables containing non English
  19 alphanumeric characters, like "-" or "+", are not inherited by invoked
  20 processes, this may be used to create variables private to fvwm. Examples:
  21
  22   SetEnv USER nobody         # change existing variable
  23   SetEnv my_name "Some One"  # create a new variable
  24   SetEnv MY-NAME "Some One"  # only accessible in fvwm process, $[MY-NAME]
  25
  26 Any variable name starting with a digit or containing a period is
  27 reserved by fvwm.
  28
  29 Built-in variables
  30 ------------------
  31
  32 These are read-only variables set by fvwm, like $[cs.fg2] or $[w.class]
  33 or $[desk.n] or $[screen] or $[gt.some text] or $[.] or $[version.line].
  34
  35 Positional variables
  36 --------------------
  37
  38 These are variables available in functions only, they contain function
  39 parameter, like $[1] or $[12] (starting from 1). Additionally, $[*]
  40 contains the parameters text on the function invocation line (as is).
  41
  42 It makes sense to support syntax $[2-4] (three parameters starting from
  43 the second) or $[2-] (all parameters starting from the second).
  44
  45 Variable filters
  46 ----------------
  47
  48 By default, any variable $[VAR] is enclosed into single quotes and any
  49 single quote in it is escaped with a backslash. The exception is
  50 positional variables $[<number>]. Traditionally, variables like $[2] are
  51 replaced with their content without any quoting, by default at least.
  52 Another exception is $[*], also for backward compatibility. Examples:
  53
  54   Next Exec xmessage $[w.name]
  55   Next Exec xmessage "Window name is $[w.name]"
  56
  57 The last string is expanded to "Window name is 'FVWM Home Page - Firefox'".
  58
  59 It's possible to change the default quoting by specifying explicit filters:
  60
  61   $[VAR]             - expanded to: 'My %^&* window'
  62   $[VAR:quote]       - expanded to: 'My %^&* window'
  63   $[VAR:dquote]      - expanded to: "My %^&* window"
  64   $[VAR:noquote]     - expanded to: My %^&* window
  65   $[VAR:glob]        - expanded to: 'My %^&** window'
  66   $[VAR:menu]        - expanded to: 'My %%^&* window'
  67
  68 More than one filter may be applied if needed, for example:
  69
  70   AddToMenu WindowOps 'Go to first desk, $[desk.name0:menu:dquote]'
  71
  72 It makes sence to allow a raw-filter for positional parameters, which is the
  73 one used by default for $[*].
  74
  75 Escaping
  76 --------
  77
  78 A backslash may be used to quote special chars. These are not variables:
  79
  80   Echo \$[VAR]
  81   Echo $\[VAR]
  82
  83 Here a colon is literal and does not denote filters:
  84
  85   Echo $[gt.Phone\:]