Merge pull request #3 from mathworks/improve-documentation

Updated documentation. Refactored file read operation to use readlines() if available.

.env

@@ -1,3 +1,3 @@
-DB_HOST=localhost
-DB_USER=db_user
+DB_HOST=localhost
+DB_USER=db_user
 DB_PASS=s1mpl3

.gitignore

@@ -1,29 +1,29 @@
-# Created by https://www.gitignore.io/api/matlab
-# Edit at https://www.gitignore.io/?templates=matlab
-
-### MATLAB ###
-# Windows default autosave extension
-*.asv
-
-# OSX / *nix default autosave extension
-*.m~
-
-# Compiled MEX binaries (all platforms)
-*.mex*
-
-# Packaged app and toolbox files
-*.mlappinstall
-*.mltbx
-
-# Generated helpsearch folders
-helpsearch*/
-
-# Simulink code generation folders
-slprj/
-sccprj/
-
-# Matlab code generation folders
-codegen/
-
-# Simulink autosave extension
-*.autosave
+# Created by https://www.gitignore.io/api/matlab
+# Edit at https://www.gitignore.io/?templates=matlab
+
+### MATLAB ###
+# Windows default autosave extension
+*.asv
+
+# OSX / *nix default autosave extension
+*.m~
+
+# Compiled MEX binaries (all platforms)
+*.mex*
+
+# Packaged app and toolbox files
+*.mlappinstall
+*.mltbx
+
+# Generated helpsearch folders
+helpsearch*/
+
+# Simulink code generation folders
+slprj/
+sccprj/
+
+# Matlab code generation folders
+codegen/
+
+# Simulink autosave extension
+*.autosave

README.md

@@ -1,47 +1,63 @@
-# dotenv for MATLAB
-> A MATLAB implementation of the dotenv pattern. 
-
-Storing configuration in the environment separate from code is based on [The Twelve-Factor App](https://12factor.net/config) methodology. dotenv for MATLAB® lets you store configuration data (passwords, API keys, server names, etc.) outside of your code. This lets you share your code without sharing your configuration data. 
-
-![screenshot](config/dotenv-screenshot.png "MATLAB Screenshot")
-
-[![mathworks](https://circleci.com/gh/mathworks/dotenv-for-MATLAB.svg?style=shield)](https://circleci.com/gh/mathworks/dotenv-for-MATLAB)
-
-[![View dotenv-for-MATLAB on File Exchange](https://www.mathworks.com/matlabcentral/images/matlab-file-exchange.svg)](https://www.mathworks.com/matlabcentral/fileexchange/73988-dotenv-for-matlab)
-## Installation
-Put `dotenv.m` somewhere on your [search path](https://www.mathworks.com/help/matlab/ref/path.html).
-
-## Usage Example
-`dotenv()` will try and load a file named `.env` from the current working folder. Alternatively, you can specify the path with `dotenv('path/to/file.env')`.
-
-`.env`
-```text
-API_KEY=ybvxtzwaxa:r42DtRhuUT7TywYpzBABOFZ0IIomwuIEXnfFVq2VSXjRC
-```
-
-`file.m`
-```matlab
-d = dotenv();
-opts = weboptions('HeaderField', ["accept", "any"; "authorization", d.env.API_KEY])
-url = "https://myurl.com"
-response = webread(url, opts);
-```
-Common places you may need to do this are [`weboptions()`](https://www.mathworks.com/help/matlab/ref/weboptions.html), the [Database Toolbox](https://www.mathworks.com/help/database/ug/database.odbc.connection.html), or [`ftp()`](https://www.mathworks.com/help/matlab/ref/ftp.html).
-
-## Rules
-The parsing engine currently supports the following rules:
-* empty lines are skipped
-* lines beginning with `#` are treated as comments
-* empty values become empty strings (`DB_HOST=` becomes `DBHOST: ''`)
-* whitespace is removed from both ends of unquoted values (`DB_HOST=some server` becomes `DB_HOST:'some server'`)
-* quoted values are escaped (`DB_PASS=" some password "` becomes `DB_PASS:' some password '`)
-
-## FAQ
-### Should I commit my `.env` file?
-No. You should put `*.env` in your `.gitignore` file.
-
-## Development Setup
-Clone the repository. You can run `runtests('tests')` from the project root to run the unit test suite.
-
-## Bugs?
-I would love to hear if this breaks on any weird strings or doesn't work the way you expected.
+# dotenv for MATLAB
+
+> A MATLAB implementation of dotenv
+
+Storing [configuration in the environment](https://12factor.net/config) is one of the tenets of a [12-factor app](https://12factor.net/). dotenv for MATLAB® lets you store configuration data (passwords, API keys, server names, etc.) outside of your code. This lets you share your code without sharing your configuration data.
+
+![screenshot](config/dotenv-compare.png "MATLAB Screenshot")
+
+[![mathworks](https://circleci.com/gh/mathworks/dotenv-for-MATLAB.svg?style=shield)](https://circleci.com/gh/mathworks/dotenv-for-MATLAB)
+
+[![View dotenv-for-MATLAB on File Exchange](https://www.mathworks.com/matlabcentral/images/matlab-file-exchange.svg)](https://www.mathworks.com/matlabcentral/fileexchange/73988-dotenv-for-matlab)
+
+## Installation
+
+Put `dotenv.m` somewhere on your [search path](https://www.mathworks.com/help/matlab/ref/path.html).
+
+## Usage Example
+
+`dotenv()` will try and load a file named `.env` from the current working folder. Alternatively, you can specify the path with `dotenv('path/to/file.env')`.
+
+`.env`
+
+```perl
+# Obligatory XKCD https://xkcd.com/936/
+password=correct-horse-battery-staple 
+```
+
+`file.m`
+
+```matlab
+d = dotenv();
+opts = weboptions('HeaderField', ["accept", "any"; "authorization", d.env.password])
+url = "https://myurl.com"
+response = webread(url, opts);
+```
+
+Common places you may need to do this are [`weboptions()`](https://www.mathworks.com/help/matlab/ref/weboptions.html), [working with remote data like S3 buckets](https://www.mathworks.com/help/matlab/import_export/work-with-remote-data.html), the [Database Toolbox](https://www.mathworks.com/help/database/ug/database.odbc.connection.html), or [`ftp()`](https://www.mathworks.com/help/matlab/ref/ftp.html).
+
+## Rules
+
+The parsing engine currently supports the following rules:
+
+* empty lines are skipped
+* lines beginning with `#` are treated as comments
+* empty values become empty strings (`DB_HOST=` becomes `DBHOST: ''`)
+* whitespace is removed from both ends of unquoted values (`DB_HOST=some server` becomes `DB_HOST:'some server'`)
+* quoted values are escaped (`DB_PASS=" some password "` becomes `DB_PASS:' some password '`)
+
+Examples are in the [config](config/) directory.
+
+## FAQ
+
+### Should I commit my `.env` file?
+
+No. You should put `*.env` in your `.gitignore` file. [MATLAB.gitignore](https://github.com/github/gitignore/blob/master/Global/MATLAB.gitignore) plus `*.env` is a good start.
+
+## Development Setup
+
+Clone the repository. You can run `runtests('tests')` from the project root to run the [unit test suite](tests/).
+
+## Bugs?
+
+I would love to hear if this breaks on any weird strings or doesn't work the way you expected.

config/.env

@@ -1,4 +1,4 @@
-DB_HOST=localhost
-DB_USER=root
-DB_PASS=s1mpl3
+DB_HOST=localhost
+DB_USER=root
+DB_PASS=s1mpl3
 #DB_COMMENT=comment

config/README.md

@@ -0,0 +1,43 @@
+# Config files
+
+## [.env](.env)
+
+Shows basic functionality including the ability to comment out entries.
+
+## [blanklines.env](blanklines.env)
+
+Blank lines should be skipped.
+
+## [bottomcomment.env](bottomcomment.env)
+
+Comments should be ignored even if they're they last entry.
+
+## [empty.env](empty.env)
+
+A key doesn't have to have a value. `MYHOST=` should resolve to a kv pair of `'MYHOST': ''`
+
+## [equalPassword.env](equalPassword.env)
+
+If there is more than one `=` in an entry the kv pair splits on the first `=`.
+
+`DB_PASS=s1mpl3=123` resolves to a kv pair of `DB_PASS:s1mpl3=123`. **Not**  `DB_PASS=s1mpl3: 123`
+
+## [middleComment.env](middleComment.env)
+
+Comments in the middle of a set of entries have no effect. Tests to ensure that succeeding entries still get processed.
+
+## [single.env](single.env)
+
+To test functonality for a single entry.
+
+## [specialchars.env](specialchars.env)
+
+Values with a space preserve the space. `DB_HOST=some server` becomes `DB_HOST:'some server'`.
+
+## [topcomment.env](topcomment.env)
+
+Comments should have no effect. Tests functionality if the first entry is commented out.
+
+## [whitespace.env](whitespace.env)
+
+Whitespace is ignored.

config/blanklines.env

@@ -1,6 +1,6 @@
-DB_HOST=localhost
-
-
-DB_USER=root
-DB_PASS=s1mpl3
+DB_HOST=localhost
+
+
+DB_USER=root
+DB_PASS=s1mpl3
 DB_COMMENT=comment

config/bottomcomment.env

@@ -1,4 +1,4 @@
-DB_HOST=localhost
-DB_USER=root
-DB_PASS=s1mpl3
+DB_HOST=localhost
+DB_USER=root
+DB_PASS=s1mpl3
 #DB_COMMENT=comment

config/empty.env

@@ -1,2 +1,2 @@
-DB_HOST=
+DB_HOST=
 DB_USER=gehrhorn

config/equalPassword.env

@@ -1,4 +1,4 @@
-DB_HOST=localhost
-DB_USER=root
-DB_PASS=s1mpl3=123
+DB_HOST=localhost
+DB_USER=root
+DB_PASS=s1mpl3=123
 DB_COMMENT=comment

config/middlecomment.env

@@ -1,4 +1,4 @@
-DB_HOST=localhost
-#DB_USER=root
-DB_PASS=s1mpl3
+DB_HOST=localhost
+#DB_USER=root
+DB_PASS=s1mpl3
 DB_COMMENT=comment

config/specialchars.env

@@ -1,2 +1,2 @@
-DB_HOST=localhost server
+DB_HOST=localhost server
 DB_PASS=passhas=quote

config/topcomment.env

@@ -1,4 +1,4 @@
-#DB_HOST=localhost
-DB_USER=root
-DB_PASS=s1mpl3
+#DB_HOST=localhost
+DB_USER=root
+DB_PASS=s1mpl3
 DB_COMMENT=comment

config/whitespace.env

@@ -1,3 +1,3 @@
-DB_HOST=localhost server
-DB_USER=     george     
+DB_HOST=localhost server
+DB_USER=     george     
 DB_PASS=" mypass "

dotenv for MATLAB.prj

@@ -1,2 +1,2 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<MATLABProject xmlns="http://www.mathworks.com/MATLABProjectFile" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.0"/>
+<?xml version="1.0" encoding="UTF-8"?>
+<MATLABProject xmlns="http://www.mathworks.com/MATLABProjectFile" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="1.0"/>