docs: Reworked README (#235)

Reworked README content / documentation to use current code
standards ( read / modify / write example ), work better in npms
page bounds ( 730 pixel width limit ) and be generally more easily
comprehensible.

Author: PhoneDroid

README.md

@@ -1,125 +1,180 @@
-An ini format parser and serializer for node.
 
-Sections are treated as nested objects.  Items before the first
-heading are saved on the object directly.
+An INI format parser & serializer.
+
+## Note
+
+-   Sections are treated as nested objects.
+
+-   Section-less items are treated as globals.
 
 ## Usage
 
-Consider an ini-file `config.ini` that looks like this:
+Consider an INI file such as the following:
+
 ```ini
-    ; this comment is being ignored
-    scope = global
-
-    [database]
-    user = dbuser
-    password = dbpassword
-    database = use_this_database
-
-    [paths.default]
-    datadir = /var/lib/data
-    array[] = first value
-    array[] = second value
-    array[] = third value
+; This comment is being ignored
+scope = global
+
+[database]
+user = dbuser
+password = dbpassword
+database = use_this_database
+
+[paths.default]
+datadir = /var/lib/data
+array[] = first value
+array[] = second value
+array[] = third value
 ```
 
-You can read, manipulate and write the ini-file like so:
+You can **read**, **modify** and **write** it like so:
 
 ```js
-    var fs = require('fs')
-      , ini = require('ini')
+import { writeFile , readFile } from 'node:fs/promises'
+import { stringify , parse } from 'ini'
+
+//  Read INI file as text
+
+let text = await readFile(`./Original.ini`,{
+    encoding : 'utf-8'
+})
+
+//  Parse text data to object
+
+const config = parse(text)
 
-    var config = ini.parse(fs.readFileSync('./config.ini', 'utf-8'))
+//  Modify data object
 
-    config.scope = 'local'
-    config.database.database = 'use_another_database'
-    config.paths.default.tmpdir = '/tmp'
-    delete config.paths.default.datadir
-    config.paths.default.array.push('fourth value')
+config.scope = 'local'
+config.database.database = 'use_another_database'
+config.paths.default.tmpdir = '/tmp'
+delete config.paths.default.datadir
+config.paths.default.array.push('fourth value')
 
-    fs.writeFileSync('./config_modified.ini', ini.stringify(config, { section: 'section' }))
+//  Stringify data object
+
+text = stringify(config,{ 
+    section : 'section' 
+})
+
+//  Write INI file as text
+
+await writeFile(`./Modified.ini`,text)
 ```
 
-This will result in a file called `config_modified.ini` being written
-to the filesystem with the following content:
+The written file will contain the following:
 
 ```ini
-    [section]
-    scope=local
-    [section.database]
-    user=dbuser
-    password=dbpassword
-    database=use_another_database
-    [section.paths.default]
-    tmpdir=/tmp
-    array[]=first value
-    array[]=second value
-    array[]=third value
-    array[]=fourth value
+[section]
+scope=local
+[section.database]
+user=dbuser
+password=dbpassword
+database=use_another_database
+[section.paths.default]
+tmpdir=/tmp
+array[]=first value
+array[]=second value
+array[]=third value
+array[]=fourth value
 ```
 
 ## API
 
-### decode(inistring)
+### Parse
 
-Decode the ini-style formatted `inistring` into a nested object.
+Attempts to turn the given INI string into a nested data object.
 
-### parse(inistring)
+```js
+// You can also use `decode`
+const object = parse(`<INI Text>`) 
+```
+
+### Stringify
 
-Alias for `decode(inistring)`
+Encodes the given data object as an INI formatted string.
 
-### encode(object, [options])
+```js
+// You can also use `encode`
+stringify(object,{
 
-Encode the object `object` into an ini-style formatted string. If the
-optional parameter `section` is given, then all top-level properties
-of the object are put into this section and the `section`-string is
-prepended to all sub-sections, see the usage example above.
+    /**
+     *  Whether to insert spaces before & after `=`
+     * 
+     *  Disabled by default to have better 
+     *  compatibility with old picky parsers.
+     */
 
-The `options` object may contain the following:
+    whitespace : false ,
 
-* `align` Boolean to specify whether to align the `=` characters for
-  each section. This option will automatically enable `whitespace`.
-  Defaults to `false`.
-* `section` String which will be the first `section` in the encoded
-  ini data.  Defaults to none.
-* `sort` Boolean to specify if all keys in each section, as well as
-  all sections, will be alphabetically sorted.  Defaults to `false`.
-* `whitespace` Boolean to specify whether to put whitespace around the
-  `=` character.  By default, whitespace is omitted, to be friendly to
-  some persnickety old parsers that don't tolerate it well.  But some
-  find that it's more human-readable and pretty with the whitespace.
-  Defaults to `false`.
-* `newline` Boolean to specify whether to put an additional newline
-  after a section header. Some INI file parsers (for example the TOSHIBA
-  FlashAir one) need this to parse the file successfully.  By default,
-  the additional newline is omitted.
-* `platform` String to define which platform this INI file is expected
-  to be used with: when `platform` is `win32`, line terminations are
-  CR+LF, for other platforms line termination is LF.  By default, the
-  current platform name is used.
-* `bracketedArray` Boolean to specify whether array values are appended
-  with `[]`.  By default this is true but there are some ini parsers
-  that instead treat duplicate names as arrays.
+    /**
+     *  Whether to align the `=` character for each section.
+     *  -> Also enables the `whitespace` option
+     */
 
-For backwards compatibility reasons, if a `string` options is passed
-in, then it is assumed to be the `section` value.
+    align : false ,
 
-### stringify(object, [options])
+    /**
+     *  Identifier to use for global items 
+     *  and to prepend to all other sections.
+     */
 
-Alias for `encode(object, [options])`
+    section ,
 
-### safe(val)
+    /**
+     *  Whether to sort all sections & their keys alphabetically.
+     */
 
-Escapes the string `val` such that it is safe to be used as a key or
-value in an ini-file. Basically escapes quotes. For example
+    sort : false ,
+
+    /**
+     *  Whether to insert a newline after each section header.
+     * 
+     *  The TOSHIBA & FlashAir parser require this format. 
+     */
+
+    newline : false ,
+
+    /**
+     *  Which platforms line-endings should be used.
+     * 
+     *  win32 -> CR+LF
+     *  other -> LF
+     * 
+     *  Default is the current platform
+     */
+
+    platform ,
+
+    /**
+     *  Whether to append `[]` to array keys.
+     * 
+     *  Some parsers treat duplicate names by themselves as arrays
+     */
+
+    backetedArray : true
+
+})
+```
+
+*For backwards compatibility any string passed as the*  
+*options parameter is treated as the `section` option.*
 
 ```js
-    ini.safe('"unsafe string"')
+stringify(object,'section')
 ```
 
-would result in
+### Un / Escape
 
-    "\"unsafe string\""
+Turn the given string into a safe to  
+use key or value in your INI file.
 
-### unsafe(val)
+```js
+safe(`"unsafe string"`) // -> \"unsafe string\"
+```
 
-Unescapes the string `val`
+Or reverse the process with:
+
+```js
+unsafe(`\\"safe string\\"`) // -> "safe string"
+```