You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
**Please take into account this is still a developing project.**
8
+
Loads environment variables from `.env` files for C++ projects.
8
9
9
-
**cpp-dotenv** is implemented as a single C++ header file, so there is no need to compile nor to add complex file dependencies to your project. Simply include the header file wherever you want to use it and ta-da!, you're done.
10
+
C++ implementation of NodeJS [dotenv](https://github.com/motdotla/dotenv) project. `load_dotenv()` method API inspired by Python's [python-dotenv](https://pypi.org/project/python-dotenv/) port of the dotenv project.
11
+
12
+
> _**NOTE: please take into account this is still a developing project.**_
**NONE**, for sure! :sunglasses: If it had, it wouldn't follow the basic dotenv principles.
36
+
**NONE**, for sure! :sunglasses: If it had any, it wouldn't follow the basic dotenv principles. All the needed libraries are shipped with this repository right out of the box.
37
+
38
+
## Build
39
+
40
+
Supported build methods are:
41
+
42
+
-[CMake](#cmake) (>=3.10)
43
+
44
+
### CMake
45
+
46
+
**cpp-dotenv** comes with support for `CMake` right out of the box. In order to use it, simply include this repository's directory and link the `cpp_dotenv` target to your own targets where needed:
47
+
48
+
```cmake
49
+
add_subdirectory(cpp-dotenv)
50
+
```
51
+
52
+
```cmake
53
+
target_link_libraries(YOUR_TARGET cpp_dotenv)
54
+
```
55
+
56
+
After this, you might use the library as described in [usage](#usage); no extra scoping, no need to worry about the project's directory structure.
25
57
26
58
## Usage
27
59
28
-
To be able to use the dotenv classes, simply include the header file:
60
+
To be able to use the dotenv classes, simply include the main header file:
29
61
30
62
```cpp
31
63
#include"dotenv.h"
32
64
```
33
65
34
-
For the sake of simplycity (and if your project namespace density allows to), you can also use the `dotenv` namespace under which all definitions are:
66
+
For the sake of simplycity (and if your project namespace density allows to), you can also use the `dotenv` namespace under which all definitions are placed:
35
67
36
68
```cpp
37
69
usingnamespacedotenv;
38
70
```
39
71
40
-
For convenience, **cpp-dotenv** auto-configures a class object (which is instance of the singleton class `dotenv`) by calling the `load_dotenv()` method at the very beginning of your file (just right before the end of `dotenv.h`) and trying to load a `.env` file, although if you need to add-in your own files (like `.myenv`), simply re-run the loading step passing the file name as parameter; everything new will show up on the `dotenv` instances.
72
+
In order to bring your environment variables from your configuration files, simply make as many calls to the `load_dotenv()` method as needed with the appropriate paths (either relative to your executable's path or absolute) and arguments.
41
73
42
-
By default, already-defined environment variables are not overwritten even if redefined in some of the loaded files. This behavior can be changed, however, by calling the `load_config()` function with the `overwrite` parameter set to `true`. For an example, take a look at [this one](#several-dotenv-files).
74
+
```cpp
75
+
env.load_dotenv();
76
+
```
43
77
44
-
Also for convenience, there is a namespace-global pre-loaded reference variable to the `dotenv` singleton class instance named `env`. Simply use it as you would use a dotenv object on NodeJS, or you can define your own references:
78
+
Not passing any argument to the function is equivalent to tell **cpp-dotenv** to search for a file named `.env` at the same level as the executable that is making the call to the function.
79
+
80
+
For your convenience, there is a namespace-global reference variable to the `dotenv` singleton class instance named `env`. Simply use it as you would use a dotenv object on NodeJS, or you can define your own references:
45
81
46
82
```cpp
47
83
auto& dotenv = env; // 'auto' here is 'dotenv::dotenv'
48
84
```
49
85
50
-
### CMake
86
+
### `load_dotenv()` method
51
87
52
-
`cpp-dotenv` also comes with support for `CMake` right out of the box. In order to use it, simply include this repository's directory and link the `CPP_DOTENV_LIB` library to your own targets where needed:
88
+
The `load_dotenv()` method, part of `class dotenv`, is declared in the [`include/dotenv.h`](/include/dotenv.h) file. Since all of its parameters have default values, it can be called with any number of arguments.
After this, you might use the library as described in [usage](#usage); no extra scoping, no need to worry about the project's directory structure.
98
+
#### Parameters
99
+
100
+
- `dotenv_path`: path string, absolute or relative to the executable calling the function, of the dotenv file to be loaded. Default is `".env"`.
101
+
- `overwrite`: boolean representing whether or not to overwrite already-defined environment variables at loading time. Default is `false`.
102
+
- `interpolate`: boolean representing whether or not to resolve in-value variable references. Default is `true`.
103
+
104
+
#### Return
105
+
106
+
A reference to the `class dotenv` `this` object being used is returned, which allows for concatenating several `load_dotenv()` calls and serially load files.
107
+
108
+
## Features
109
+
110
+
The **cpp-dotenv** library has the following built-in features:
**cpp-dotenv** reports and handles four different types of errors:
120
+
121
+
- **Lexer errors**: errors produced by an incorrect format of the input language, i.e. usage of language features that do not belong to the dotenv syntax. This kind of errors throw irrecoverable exceptions.
122
+
- **Parsing errors**: errors produced by an incorrect use of the input language, i.e. the language syntax itself is correct, but it is used in an unexpected way. This kind of errors invalidate the variable they occurr in, making it to become as if it was not defined, but allowing the loading process to recover and continue.
123
+
- **Circular reference errors**: errors produced by variables that define a cycle of references, which are ultimately not resolved and their references are deleted from all the corresponding values. The variables they occurr in are ultimately defined as without the cycling references.
124
+
- **Undefined external reference warnings**: warnings produced by references to externally-loaded variables that are not present in the host environment. This variables are ultimately assigned their value as the empty string.
125
+
126
+
### Escape sequence expansion
127
+
128
+
Escape sequence expansion happens in all of the loaded values (both string and raw form) right at the end of the loading process, after the variable resolution has already been performed.
> _NOTE: escape sequences on externally-loaded variables **ARE NOT EXPANDED**._
139
+
140
+
### Variable overwritting
141
+
142
+
By default, already-defined environment variables are not overwritten even if redefined in some of the loaded files.
143
+
144
+
This behavior can be changed, however, by calling the [`load_dotenv()` method](#load_dotenv-method) with the [`overwrite` parameter](#parameters) set to `true`. For an example on how to use it, take a look at [this one](#several-dotenv-files).
145
+
146
+
### Variable resolution
147
+
148
+
**cpp-dotenv** by default resolves variables nested inside variable definitions in the parsed files, both with those defined in the file being loaded or already present in the hosting environment itself.
149
+
150
+
- Variable reference with variables declared in the **same file** is order-independent: there's no need to worry about the declaration order of the variables inside a same file, **cpp-dotenv** will resolve all of the symbols regardless of their order of declaration.
151
+
- Variable reference with variables declared on **different files** is order-depdendent on the loading order of the files via the `load_dotenv()` method: variables defined in later calls to `load_dotenv()` are not yet visible to files being processed at a previous load and will be treated as external variables.
152
+
153
+
Variable resolution can be explicitly turned off by setting the [`interpolate` parameter](#parameters) of the [`load_dotenv()` method](#load_dotenv-method) to `false`.
154
+
155
+
> _NOTE: variable references inside externally-loaded variables **ARE NOT RESOLVED**._
156
+
157
+
There are two different types of supported variable references:
158
+
159
+
- **Raw-style unbounded references** of the style `$VAR_NAME`, which only support references composed by letters, numbers and underscores. Their name must start by a letter or by an underscore, and have at least one character.
160
+
- **Bounded references**, of the style `${VAR_NAME}`, which support a wider set of character possibilities.
Assuming the same `.env` file as in the [previous case](#basic-usage), the predefined `env` reference can be easily renamed and used just exactly as the original one.
206
+
Assuming the same `.env` file as in the [previous case](#basic-usage), the predefined `env` reference can be easily renamed and used just exactly as the original one. The `load_dotenv()` method also returns a reference to the object it is being applied to, so it can be easily nested in a case like this.
The situation of having several different dotenv files is no stranger one (`.env` for private configuration variables, `.pubenv` for public variables, etc.). Loading several files in addition to the default one and overwritting any variables that are redefined on the files can be done as follows:
234
+
The situation of having several different dotenv files is no stranger one (`.env` for private configuration variables, `.pubenv` for public variables, etc.). Loading several files and overwritting any variables that are redefined on the files can be done as follows:
Assume an environment variable `${HOST}` already defined on the host environment as `myweb.com` and the following `.env` file:
281
+
282
+
```env
283
+
# FULL URL
284
+
URL=${URL_PROT}://${HOST}/${URL_SUBD}
285
+
286
+
# PARTIAL DEFINITIONS
287
+
URL_PROT=https
288
+
URL_SUBD=some/sub/page.html
289
+
```
290
+
291
+
The following `.cpp` file:
181
292
182
-
For the geeks, you can check the grammar I've implemented on the `grammar/env.g4` file. Despite being written in an ANTLR4 fashion, I've implemented a simple recursive parser myself given the basic nature of the language. The parser and its methods are publicly available under the `dotenv::parser` class.
293
+
```cpp
294
+
#include"dotenv.h"
295
+
#include<iostream>
296
+
297
+
usingnamespacedotenv;
298
+
usingnamespacestd;
183
299
184
-
## Known issues
300
+
intmain()
301
+
{
302
+
env.load_dotenv();
303
+
cout << "URL: " << env["URL"] << endl;
304
+
}
305
+
```
185
306
186
-
The complete list of issues can be consulted at the [issues page](https://github.com/adeharo9/cpp-dotenv/issues).
307
+
would produce the following output:
308
+
309
+
```shell
310
+
$ ./main
311
+
URL: https://myweb.com/some/sub/page.html
312
+
```
313
+
314
+
## Known limitations
315
+
316
+
-_Arbitrary octal value escape sequences are not expanded._
317
+
-_Arbitrary hexadecimal value escape sequences are not expanded._
318
+
-_Arbitrary unicode value escape sequences are not expanded._
319
+
320
+
## Grammar
187
321
188
-
1.[Variable resolution on values not yet vailable](https://github.com/adeharo9/cpp-dotenv/issues/3)
322
+
For the geeks, you can check the implemented grammars and all of the ANTLR-related files on the [`common/antlr/` directory](/common/antlr).
0 commit comments