E-MailRelay

genvironment.h
Go to the documentation of this file.
1//
2// Copyright (C) 2001-2024 Graeme Walker <graeme_walker@users.sourceforge.net>
3//
4// This program is free software: you can redistribute it and/or modify
5// it under the terms of the GNU General Public License as published by
6// the Free Software Foundation, either version 3 of the License, or
7// (at your option) any later version.
8//
9// This program is distributed in the hope that it will be useful,
10// but WITHOUT ANY WARRANTY; without even the implied warranty of
11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12// GNU General Public License for more details.
13//
14// You should have received a copy of the GNU General Public License
15// along with this program. If not, see <http://www.gnu.org/licenses/>.
16// ===
17///
18/// \file genvironment.h
19///
20
21#ifndef G_ENVIRONMENT_H
22#define G_ENVIRONMENT_H
23
24#include "gdef.h"
25#include "gexception.h"
26#include "gstringview.h"
27#include "gpath.h"
28#include <string>
29#include <vector>
30#include <map>
31
32 namespace G
33{
34 class Environment ;
35}
36
37//| \class G::Environment
38/// Holds a set of environment variables and also provides static methods
39/// to wrap getenv() and putenv().
40///
41 class G::Environment
42{
43 public:
44 G_EXCEPTION( Error , tx("invalid environment variable") )
45
46 static std::string get( const std::string & name , const std::string & default_ ) ;
47 ///< Returns the environment variable value or the given default.
48
49 static G::Path getPath( const std::string & name , const G::Path & = {} ) ;
50 ///< Returns the environment variable value as a G::Path object.
51
52 static void put( const std::string & name , const std::string & value ) ;
53 ///< Sets the environment variable value.
54
55 static Environment minimal( bool sbin = false ) ;
56 ///< Returns a minimal, safe set of environment variables.
57
58 static Environment inherit() ;
59 ///< Returns an empty() environment, as if default constructed.
60 ///< This is syntactic sugar for the G::NewProcess interface.
61
62 explicit Environment( const std::map<std::string,std::string> & ) ;
63 ///< Constructor from a map.
64
65 bool contains( const std::string & name ) const ;
66 ///< Returns true if the given variable is in this set.
67
68 std::string value( const std::string & name , const std::string & default_ = {} ) const ;
69 ///< Returns the value of the given variable in this set.
70
71 bool add( std::string_view key , std::string_view value ) ;
72 ///< Adds an environment variable. Returns false if invalid.
73
74 std::string block() const ;
75 ///< Returns a contiguous block of memory containing the
76 ///< null-terminated strings with an extra zero byte
77 ///< at the end.
78
79 std::wstring block( std::wstring (*)(std::string_view) ) const ;
80 ///< Returns a contiguous block of memory containing the
81 ///< null-terminated strings with an extra zero character
82 ///< at the end.
83
84 bool empty() const noexcept ;
85 ///< Returns true if empty.
86
87 static std::vector<char*> array( const std::string & block ) ;
88 ///< Returns a pointer array pointing into the given
89 ///< block(), with const-casts.
90
91 static std::vector<char*> array( std::string && envblock ) = delete ;
92 ///< Deleted overload.
93
94 std::map<std::string,std::string> map() const ;
95 ///< Returns the environment as a map.
96
97 private:
98 using Map = std::map<std::string,std::string> ;
99 using List = std::vector<std::string> ;
100
101 private:
102 static void sanitise( Map & ) ;
103
104 private:
105 Map m_map ;
106} ;
107
108 inline
109std::map<std::string,std::string> G::Environment::map() const
110{
111 return m_map ;
112}
113
114 inline
115 bool G::Environment::empty() const noexcept
116{
117 return m_map.empty() ;
118}
119
120 inline
121 G::Environment G::Environment::inherit()
122{
123 return Environment( {} ) ;
124}
125
126#endif
G::Environment
Holds a set of environment variables and also provides static methods to wrap getenv() and putenv().
Definition: genvironment.h:42
G::Environment::map
std::map< std::string, std::string > map() const
Returns the environment as a map.
Definition: genvironment.h:109
G::Environment::value
std::string value(const std::string &name, const std::string &default_={}) const
Returns the value of the given variable in this set.
Definition: genvironment.cpp:68
G::Environment::array
static std::vector< char * > array(std::string &&envblock)=delete
Deleted overload.
G::Environment::put
static void put(const std::string &name, const std::string &value)
Sets the environment variable value.
Definition: genvironment_unix.cpp:55
G::Environment::Environment
Environment(const std::map< std::string, std::string > &)
Constructor from a map.
Definition: genvironment.cpp:30
G::Environment::get
static std::string get(const std::string &name, const std::string &default_)
Returns the environment variable value or the given default.
Definition: genvironment_unix.cpp:35
G::Environment::empty
bool empty() const noexcept
Returns true if empty.
Definition: genvironment.h:115
G::Environment::block
std::string block() const
Returns a contiguous block of memory containing the null-terminated strings with an extra zero byte a...
Definition: genvironment.cpp:74
G::Environment::inherit
static Environment inherit()
Returns an empty() environment, as if default constructed.
Definition: genvironment.h:121
G::Environment::getPath
static G::Path getPath(const std::string &name, const G::Path &={})
Returns the environment variable value as a G::Path object.
Definition: genvironment_unix.cpp:42
G::Environment::minimal
static Environment minimal(bool sbin=false)
Returns a minimal, safe set of environment variables.
Definition: genvironment_unix.cpp:63
G::Environment::contains
bool contains(const std::string &name) const
Returns true if the given variable is in this set.
Definition: genvironment.cpp:62
G::Environment::array
static std::vector< char * > array(const std::string &block)
Returns a pointer array pointing into the given block(), with const-casts.
Definition: genvironment.cpp:100
G::Environment::add
bool add(std::string_view key, std::string_view value)
Adds an environment variable. Returns false if invalid.
Definition: genvironment.cpp:48
G::Path
A Path object represents a file system path.
Definition: gpath.h:82
gexception.h
gpath.h
gstringview.h
G
Low-level classes.
Definition: garg.h:36
G::tx
constexpr const char * tx(const char *p) noexcept
A briefer alternative to G::gettext_noop().
Definition: ggettext.h:84