[Boost-users] Re: Environment variable library?

From: Vladimir Prus (ghost_at_[hidden])
Date: 2005-01-17 02:22:07

Jeff Garland wrote:

> On Sun, 16 Jan 2005 21:05:55 -0600, Aaron W. LaFramboise wrote
>> Is there a Boost library that supports manipulating process environment
>> variables?
> 
> I think there was some discussion of integrating this capability into the
> program options library, but it may be a 'planned extension' as it isn't
> in the current docs that I could find.

It's present in the 1.32 version as the function
'parse_environment_variables'. I'm not sure if that's what Aaron wanted so
here's the docs (they were added after 1.32 and I don't know where's CVS
Boost.Book-generated docs now).

   <title>Environment variables</title>

      <para><firstterm>Environment variables</firstterm> are string
variables
      which are available to all programs via the <code>getenv</code>
function
      of C runtime library. The operating system allows to set initial
values
      for a given user, and the values can be further changed on the command
      line.  For example, on Windows one can use the
      <filename>autoexec.bat</filename> file or (on recent versions) the
      <filename>Control Panel/System/Advanced/Environment
Variables</filename>
      dialog, and on Unix &#x2014;, the <filename>/etc/profile</filename>,
      <filename>~/profile</filename> and <filename>~/bash_profile</filename>
      files. Because environment variables can be set for the entire system,
      they are particularly suitable for options which apply to all
programs.
      </para>

      <para>The environment variables can be parsed with the
      &parse_environment; function. The function have several overloaded
      versions. The first parameter is always an &options_description;
      instance, and the second specifies what variables must be processed,
and
      what option names must correspond to it. To describe the second
      parameter we need to consider naming conventions for environment
      variables.</para>
      
      <para>If you have an option that should be specified via environment
      variable, you need make up the variable's name. To avoid name clashes,
      we suggest that you use a sufficiently unique prefix for environment
      variables. Also, while option names are most likely in lower case,
      environment variables conventionally use upper case. So, for an option
      name <literal>proxy</literal> the environment variable might be called
      <envar>BOOST_PROXY</envar>. During parsing, we need to perform reverse
      conversion of the names. This is accomplished by passing the choosen
      prefix as the second parameter of the &parse_environment; function.
      Say, if you pass <literal>BOOST_</literal> as the prefix, and there
are
      two variables, <envar>CVSROOT</envar> and <envar>BOOST_PROXY</envar>,
the
      first variable will be ignored, and the second one will be converted
to
      option <literal>proxy</literal>. 
      </para>
      
      <para>The above logic is sufficient in many cases, but it is also
      possible to pass, as the second parameter of the &parse_environment;
      function, any function taking a <code>std::string</code> and returning
      <code>std::string</code>. That function will be called for each
      environment variable and should return either the name of the option,
or
      empty string if the variable should be ignored.
      </para>

 
- Volodya