Adds documentation

README.md

@@ -1,5 +1,17 @@
 The command line tool to read, manipulate and update .env files.
 
+## Features
+
+* by default, preserves white spaces, line breaks and comments
+* supports reading and updating .end files
+* can read and write to stdin/stdout to be used in shell as a part of commands pipeline
+* support multiple input files for updates as well as list of arguments at end of command
+* supports single and double quoted values
+* support comment lines and comments at end of variables
+* can do smart append to preserve logical groups of variables
+* can beautify (normalize) file layout
+* command line can work in resilient mode, ignoring parsing errors
+
 ## Setup
 
 ```bash
@@ -16,6 +28,14 @@ $ cat result.txt
 value1
 ```
 
+By default, new keys are added at end of resulting file.
+This can be changed by options:
+
+* `--onlyUpdate` - prevents new keys to be appended, only existing keys are updated 
+* `--smartAppend` - finds most similar group of variables and appends new variables between them, preserving alphabetical order.
+
+To operate on files, specify input file(s) with `-i` and output file with `-o`. To modify first input file use `-m`.
+
 ### Modify files
 
 ```bash
@@ -23,7 +43,7 @@ $ dotenv-tool -h
 ```
 
 ```
-Usage: dotenv-tool [options] [command] [paramsToSet]
+Usage: dotenv-tool [options] [command] [paramsToSet...]
 
 Tool to read and update .env files
 
@@ -35,6 +55,10 @@ Options:
   -i, --files <filePaths...>   Input file(s)
   -o, --outputFile <filePath>  Output file
   -m, --modify                 Modify first input file
+  -b, --beautify               Beautifies resulting env file
+  -u, --onlyUpdate             Only updates existing values, without appending new values
+  -p, --smartAppend            Smart appends variables depending on their names
+  -r, --resilient              Ignore files that cannot be read during update
   -s, --silent                 Mute all messages and errors
   -h, --help                   display help for command
 
@@ -59,4 +83,67 @@ Arguments:
 Options:
   -f, --file <filePath>  Input file to parse (if not given, stdio is used)
   -h, --help             display help for command
+```
+
+## API
+
+Internally, library parses into and manipulates on array of tokens `Token[]`: 
+
+* `VariableToken` holding contents of line with variable
+* `SimpleToken` - for new lines, white space lines or comment lines.
+
+To parse .env string, use `parseMultiLine`, to update list of tokens use `update`, to convert token list back into .env string use `stringifyTokens`.
+
+```ts
+import { parseMultiLine } from 'dotenv-tool'
+
+const tokens = parseMultiLine("VAR1=value1\nVAR2=value2");
+const updatedTokens = update(tokens, { name: 'VAR1', value: 'new value', comment: ' # optional comment' });
+console.log(stringifyTokens(updatedTokens))
+```
+
+### update
+
+```ts
+function update(tokens: Token[], updateWith: VariableToUpdate[], config?: Config): Token[];
+```
+
+For convenience, `update` can get list of updates (`updateWith` argument) in three different formats:
+
+* **Tuple** 
+  `[string, string | null]` - with key on position `0` and value on position `1`
+* **Simple object** 
+  `Variable` type - contains key, value and optional comment
+* **Token** 
+  `VariableToken` type - useful when updating with result of parsing other .env strings
+
+```ts
+update(tokens, [['VAR1', 'new value'], ['VAR2', null]])
+update(tokens, [ { name: 'VAR1', value: 'new value' }])
+update(tokens, [ 
+  { 
+    token: TokenType.VARIABLE,
+    name: 'VAR1', 
+    value: 'new value',
+    beginning: '',
+    equals: ' = ', // extra space around =
+    quote: '"',    // value will be inside double quotes
+    ending: '   '  // extra white space at end of line
+    comment: ''
+  }
+])
+```
+
+If new value is `null` - **variable will be deleted**, if it is empty string or `undefined` - it will be left empty (`VAR=`)
+
+### Configuration
+
+Both `update` as well as `stringifyTokens` take `config` parameter:
+
+```ts
+type Config = {
+    beautify?: boolean;            // if true, output will be beautified/normalized. Default: false
+    enforceNewLineEnd?: boolean;   // if true, output will have ensured \n character at end. Default: true
+    modifyMode?: ModifyMode;       // decide if new keys should or should not be added, and where. Default: ModifyMode.APPEND
+};
 ```