Design/env_notes

   1
   2                          Stem Environment Notes
   3
   4 The global hash %Stem::Vars::Env is used to store environment values for
   5 the local Hub. These values can be set in a variety of ways:
   6
   7         Shell environment variables of the form STEM_* are located and
   8         the STEM_ prefix is removed and the rest of the name is lower
   9         cased. This name is set to the value of the shell variable.
  10
  11         The command line of run_stem is parsed for name=value tokens. The
  12         name/value pair is set in the Stem environment.
  13
  14         The Stem::TtyMsg module parses its input lines for name=value
  15         lines (only if the line doesn't contain a leading Cell address).
  16         White space is allowed around each part and surrounding white
  17         space is stripped from the value. The name/value pair is set in
  18         the local Stem environment.
  19
  20         The Stem::Vars Class Cell (aliased to 'var') can take a
  21         'set_env' command message. The data field is parse for
  22         name=value just like Stem::TtyMsg does. This can be used from
  23         the terminal of any Hub running Stem::TtyMsg to set environment
  24         variables in any Hub.
  25
  26 The environment values are accessable in several ways:
  27
  28         A Stem module can import %Stem::Vars::Env via a use Stem::Vars
  29         statement. The %Env hash can be directly used.
  30
  31         The Stem::Vars Class Cell supports a 'get_env' command message
  32         which uses the data field and the environment variable name. It
  33         returns its value via the normal command/response message
  34         mechanism.
  35
  36         The Stem::Vars Class Cell supports a 'status' command message
  37         which returns a printout of the entire Stem environment for this
  38         Hub. It returns that via the normal command/response message
  39         mechanism.
  40
  41 Here are some of the places and ways Stem Environment variables are
  42 used:
  43
  44         An attribute description can specify an environment variable
  45         name (via the 'env' option). If this environment variable is
  46         found it will be used as a default value for this attribute
  47         overriding the default option value if it was supplied
  48         too. A passed in value will set the attribute regardless of the
  49         environment.
  50
  51         Logical Logs use environment variables to test whether a Log
  52         Entry is filtered. The value of the variable is compared to the
  53         Entry severity level with any one of the normal numerical
  54         boolean tests and it sets the filter flag accordingly.
  55
  56         The Debug/Trace subsystem uses environment variables in a way
  57         similar to the Log subsystem. When a Debug routine is created,
  58         an enviroment name can be set and its value is used as a boolean
  59         to determine if this call to the Debug sub will happen.
  60
  61 Stem environment values are (and will be) used in many places. If you
  62 use them in configurations or in code, be sure that the names used are
  63 unique.