Adds more examples and sections

Author: adeharo9

README.md

@@ -1,6 +1,8 @@
 # cpp-dotenv
 
-C++ implementation of nodejs [dotenv](https://github.com/motdotla/dotenv) project. Loads environment variables from .env for C++ projects.
+![version 0.1.0](https://img.shields.io/badge/version-0.1.0-blue)
+
+C++ implementation of NodeJS [dotenv](https://github.com/motdotla/dotenv) project. Loads environment variables from `.env` for C++ projects.
 
 **Please take into account this is still a developing project.**
 
@@ -12,6 +14,9 @@ C++ implementation of nodejs [dotenv](https://github.com/motdotla/dotenv) projec
 2. [Usage](#usage)
    1. [CMake](#cmake)
 3. [Examples](#examples)
+   1. [Basic usage](#basic-usage)
+   2. [Reference renaming](#reference-renaming)
+   3. [Several dotenv files](#several-dotenv-files)
 4. [Grammar](#grammar)
 
 ## Dependencies
@@ -34,6 +39,8 @@ using namespace dotenv;
 
 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.
 
+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).
+
 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:
 
 ```cpp
@@ -56,6 +63,8 @@ After this, you might use the library as described in [usage](#usage); no extra
 
 ## Examples
 
+### Basic usage
+
 Assume the following `.env` file:
 
 ```env
@@ -80,8 +89,34 @@ using namespace std;
 
 int main()
 {
-    auto& dotenv = env;  // Reference re-naming
+    cout << "DB_NAME: " << env["DB_NAME"] << endl;
+    cout << "eval \"" << env["COMMAND"] << " " << env["HOST"] << "\"" << endl;
+}
+```
 
+would produce the following output:
+
+```shell
+$ ./main
+  DB_NAME: DontDoThisAtHome
+  eval "ping 8.8.8.8"
+```
+
+### Reference renaming
+
+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 following code:
+
+```cpp
+#include "dotenv.h"
+#include <iostream>
+
+using namespace std;
+
+int main()
+{
+    auto& dotenv = dotenv::env;
     cout << "DB_NAME: " << dotenv["DB_NAME"] << endl;
     cout << "eval \"" << dotenv["COMMAND"] << " " << dotenv["HOST"] << "\"" << endl;
 }
@@ -95,6 +130,60 @@ $ ./main
   eval "ping 8.8.8.8"
 ```
 
+### Several dotenv files
+
+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:
+
+Assume the following `.env` file:
+
+```env
+# DB THINGS
+DB_NAME=DontDoThisAtHome
+DB_PASS=such_security
+```
+
+And the following `.pubenv` file:
+
+```env
+# CONNECTIONS THINGS
+COMMAND=ping
+HOST=8.8.8.8
+MESSAGE="Hey buddy!"
+```
+
+The following source file:
+
+```cpp
+#include "dotenv.h"
+#include <iostream>
+
+using namespace dotenv;
+using namespace std;
+
+int main()
+{
+    env.load_dotenv(".env", true);
+    env.load_dotenv(".pubenv", true);
+    cout << "DB_NAME: " << env["DB_NAME"] << endl;
+    cout << "eval \"" << env["COMMAND"] << " " << env["HOST"] << "\"" << endl;
+}
+```
+
+would produce the following output:
+
+```shell
+$ ./main
+  DB_NAME: DontDoThisAtHome
+  eval "ping 8.8.8.8"
+```
+
 ## Grammar
 
 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.
+
+## Known issues
+
+The complete list of issues con be consulted at the [issues page](https://github.com/adeharo9/cpp-dotenv/issues).
+
+1. [Variable resolution on values not yet vailable](https://github.com/adeharo9/cpp-dotenv/issues/3)
+2. Scaped sequences not being scaped inside strings