Skip to content

Commit 58bc383

Browse files
gehrhorngehrhorn
authored
Merge pull request #3 from mathworks/improve-documentation
Updated documentation. Refactored file read operation to use readlines() if available.
2 parents dbce6c2 + 9813656 commit 58bc383

File tree

61 files changed

+469
-397
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

61 files changed

+469
-397
lines changed

‎.env‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
1-
DB_HOST=localhost
2-
DB_USER=db_user
1+
DB_HOST=localhost
2+
DB_USER=db_user
33
DB_PASS=s1mpl3

‎.gitignore‎

Lines changed: 29 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,29 +1,29 @@
1-
# Created by https://www.gitignore.io/api/matlab
2-
# Edit at https://www.gitignore.io/?templates=matlab
3-
4-
### MATLAB ###
5-
# Windows default autosave extension
6-
*.asv
7-
8-
# OSX / *nix default autosave extension
9-
*.m~
10-
11-
# Compiled MEX binaries (all platforms)
12-
*.mex*
13-
14-
# Packaged app and toolbox files
15-
*.mlappinstall
16-
*.mltbx
17-
18-
# Generated helpsearch folders
19-
helpsearch*/
20-
21-
# Simulink code generation folders
22-
slprj/
23-
sccprj/
24-
25-
# Matlab code generation folders
26-
codegen/
27-
28-
# Simulink autosave extension
29-
*.autosave
1+
# Created by https://www.gitignore.io/api/matlab
2+
# Edit at https://www.gitignore.io/?templates=matlab
3+
4+
### MATLAB ###
5+
# Windows default autosave extension
6+
*.asv
7+
8+
# OSX / *nix default autosave extension
9+
*.m~
10+
11+
# Compiled MEX binaries (all platforms)
12+
*.mex*
13+
14+
# Packaged app and toolbox files
15+
*.mlappinstall
16+
*.mltbx
17+
18+
# Generated helpsearch folders
19+
helpsearch*/
20+
21+
# Simulink code generation folders
22+
slprj/
23+
sccprj/
24+
25+
# Matlab code generation folders
26+
codegen/
27+
28+
# Simulink autosave extension
29+
*.autosave

‎README.md‎

Lines changed: 63 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -1,47 +1,63 @@
1-
# dotenv for MATLAB
2-
> A MATLAB implementation of the dotenv pattern.
3-
4-
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.
5-
6-
![screenshot](config/dotenv-screenshot.png "MATLAB Screenshot")
7-
8-
[![mathworks](https://circleci.com/gh/mathworks/dotenv-for-MATLAB.svg?style=shield)](https://circleci.com/gh/mathworks/dotenv-for-MATLAB)
9-
10-
[![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)
11-
## Installation
12-
Put `dotenv.m` somewhere on your [search path](https://www.mathworks.com/help/matlab/ref/path.html).
13-
14-
## Usage Example
15-
`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')`.
16-
17-
`.env`
18-
```text
19-
API_KEY=ybvxtzwaxa:r42DtRhuUT7TywYpzBABOFZ0IIomwuIEXnfFVq2VSXjRC
20-
```
21-
22-
`file.m`
23-
```matlab
24-
d = dotenv();
25-
opts = weboptions('HeaderField', ["accept", "any"; "authorization", d.env.API_KEY])
26-
url = "https://myurl.com"
27-
response = webread(url, opts);
28-
```
29-
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).
30-
31-
## Rules
32-
The parsing engine currently supports the following rules:
33-
* empty lines are skipped
34-
* lines beginning with `#` are treated as comments
35-
* empty values become empty strings (`DB_HOST=` becomes `DBHOST: ''`)
36-
* whitespace is removed from both ends of unquoted values (`DB_HOST=some server` becomes `DB_HOST:'some server'`)
37-
* quoted values are escaped (`DB_PASS=" some password "` becomes `DB_PASS:' some password '`)
38-
39-
## FAQ
40-
### Should I commit my `.env` file?
41-
No. You should put `*.env` in your `.gitignore` file.
42-
43-
## Development Setup
44-
Clone the repository. You can run `runtests('tests')` from the project root to run the unit test suite.
45-
46-
## Bugs?
47-
I would love to hear if this breaks on any weird strings or doesn't work the way you expected.
1+
# dotenv for MATLAB
2+
3+
> A MATLAB implementation of dotenv
4+
5+
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.
6+
7+
![screenshot](config/dotenv-compare.png "MATLAB Screenshot")
8+
9+
[![mathworks](https://circleci.com/gh/mathworks/dotenv-for-MATLAB.svg?style=shield)](https://circleci.com/gh/mathworks/dotenv-for-MATLAB)
10+
11+
[![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)
12+
13+
## Installation
14+
15+
Put `dotenv.m` somewhere on your [search path](https://www.mathworks.com/help/matlab/ref/path.html).
16+
17+
## Usage Example
18+
19+
`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')`.
20+
21+
`.env`
22+
23+
```perl
24+
# Obligatory XKCD https://xkcd.com/936/
25+
password=correct-horse-battery-staple
26+
```
27+
28+
`file.m`
29+
30+
```matlab
31+
d = dotenv();
32+
opts = weboptions('HeaderField', ["accept", "any"; "authorization", d.env.password])
33+
url = "https://myurl.com"
34+
response = webread(url, opts);
35+
```
36+
37+
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).
38+
39+
## Rules
40+
41+
The parsing engine currently supports the following rules:
42+
43+
* empty lines are skipped
44+
* lines beginning with `#` are treated as comments
45+
* empty values become empty strings (`DB_HOST=` becomes `DBHOST: ''`)
46+
* whitespace is removed from both ends of unquoted values (`DB_HOST=some server` becomes `DB_HOST:'some server'`)
47+
* quoted values are escaped (`DB_PASS=" some password "` becomes `DB_PASS:' some password '`)
48+
49+
Examples are in the [config](config/) directory.
50+
51+
## FAQ
52+
53+
### Should I commit my `.env` file?
54+
55+
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.
56+
57+
## Development Setup
58+
59+
Clone the repository. You can run `runtests('tests')` from the project root to run the [unit test suite](tests/).
60+
61+
## Bugs?
62+
63+
I would love to hear if this breaks on any weird strings or doesn't work the way you expected.

‎config/.env‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
DB_HOST=localhost
2-
DB_USER=root
3-
DB_PASS=s1mpl3
1+
DB_HOST=localhost
2+
DB_USER=root
3+
DB_PASS=s1mpl3
44
#DB_COMMENT=comment

‎config/README.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# Config files
2+
3+
## [.env](.env)
4+
5+
Shows basic functionality including the ability to comment out entries.
6+
7+
## [blanklines.env](blanklines.env)
8+
9+
Blank lines should be skipped.
10+
11+
## [bottomcomment.env](bottomcomment.env)
12+
13+
Comments should be ignored even if they're they last entry.
14+
15+
## [empty.env](empty.env)
16+
17+
A key doesn't have to have a value. `MYHOST=` should resolve to a kv pair of `'MYHOST': ''`
18+
19+
## [equalPassword.env](equalPassword.env)
20+
21+
If there is more than one `=` in an entry the kv pair splits on the first `=`.
22+
23+
`DB_PASS=s1mpl3=123` resolves to a kv pair of `DB_PASS:s1mpl3=123`. **Not** `DB_PASS=s1mpl3: 123`
24+
25+
## [middleComment.env](middleComment.env)
26+
27+
Comments in the middle of a set of entries have no effect. Tests to ensure that succeeding entries still get processed.
28+
29+
## [single.env](single.env)
30+
31+
To test functonality for a single entry.
32+
33+
## [specialchars.env](specialchars.env)
34+
35+
Values with a space preserve the space. `DB_HOST=some server` becomes `DB_HOST:'some server'`.
36+
37+
## [topcomment.env](topcomment.env)
38+
39+
Comments should have no effect. Tests functionality if the first entry is commented out.
40+
41+
## [whitespace.env](whitespace.env)
42+
43+
Whitespace is ignored.

‎config/blanklines.env‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
DB_HOST=localhost
2-
3-
4-
DB_USER=root
5-
DB_PASS=s1mpl3
1+
DB_HOST=localhost
2+
3+
4+
DB_USER=root
5+
DB_PASS=s1mpl3
66
DB_COMMENT=comment

‎config/bottomcomment.env‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
DB_HOST=localhost
2-
DB_USER=root
3-
DB_PASS=s1mpl3
1+
DB_HOST=localhost
2+
DB_USER=root
3+
DB_PASS=s1mpl3
44
#DB_COMMENT=comment

‎config/dotenv-compare.png‎

97.5 KB
Loading

‎config/empty.env‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,2 @@
1-
DB_HOST=
1+
DB_HOST=
22
DB_USER=gehrhorn

‎config/equalPassword.env‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
DB_HOST=localhost
2-
DB_USER=root
3-
DB_PASS=s1mpl3=123
1+
DB_HOST=localhost
2+
DB_USER=root
3+
DB_PASS=s1mpl3=123
44
DB_COMMENT=comment

0 commit comments

Comments
 (0)