// Environment.h

#ifndef Environment_H
#define Environment_H

// David Adams
// August 2002
//
// Holds the description of a POSIX environment, i.e. a collection
// of named strings.
// 
// The std::map<string,string> interface can be used inspect or
// update the table.
// 
// XML format:
//
// Environment
//   variable
//     name="MYHOME"
//     value="/home/me"
//   variable
//     name="MYPATH"
//     value="/home/a:/home/b"

#include <string>
#include <vector>
#include <map>
#include <iosfwd>

class XmlElement;
class Text;

class Environment : public std::map<std::string, std::string> {

private:  // data

  // Containers to manage returned process tables.
  mutable std::vector<std::vector<std::string> > m_lines;
  mutable std::vector<std::vector<const char*> > m_clines;

public:  // static functions

  // XML name.
  static const char* xml_name() { return "Environment"; }

  // Return the system environment capatured during C++ startup.
  // This does not change.
  static const Environment& initial();

  // Return the current environment.
  static Environment current();

  // Return the posix environment.
  // For use in execve and execle.
  static const Environment& posix();

  // DTD
  static const Text& dtd();

public:  // functions

  // Default constructor.
  // Creates an empty environment.
  Environment();

  // XML constructor.
  explicit Environment(const XmlElement& ele);

  // Fill from a null-terminated array of lines with the format
  // name=value.
  void fill(const char *const * lines);

  // Fill from the current process environment.
  // This is a copy--modifications do not affect the process
  // environment.
  void sysfill();

  // Return is name is assigned.
  bool has(std::string name) const;

  // Return the value associated with a name.
  // Blank if there is no such value.
  std::string value(std::string name) const;

  // Return the environment as a null-terminated array of lines
  // with the format name=value.
  // This is the format of the unix system process table.
  // The return is a snapshot--it is not updated to reflect changes
  // in this object.
  // Return is valid until this object is deleted.
  const char *const * env() const;

  // Same as above but with char instead of cknst char. This allows
  // a devious user to corrupt the c-string array but is the type
  // required by the POSIX exec commands.
  char *const * unsafe_env() const;

  // Write to XML.
  // Caller is responsible for managing the returned object.
  const XmlElement* xml() const;

};

// Output stream.
std::ostream& operator<<(std::ostream& lhs, const Environment& rhs);

#endif