From bf008dae23c6e2c0b8de33842b9335a361f91f4a Mon Sep 17 00:00:00 2001 From: Darren 'Tadgy' Austin Date: Sun, 21 Jul 2019 20:16:32 +0100 Subject: [PATCH] Docs updates. --- README.md | 67 ++++++++++++++++++++++++++++--------------------------- 1 file changed, 34 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index 068392a..98239b0 100644 --- a/README.md +++ b/README.md @@ -28,9 +28,9 @@ descriptions. The parser outputs Bash syntax associative array declarations, and array element definitions to `stdout`. These Bash commands can be `eval`ed into a script to provide access to every element in the INI file. For example, -using `eval "$(/path/to/parse_ini example.ini)"` in your script would define a set -of arrays whose values can be accessed in the Bash standard method, using the keys -from the INI file. +using `eval "$(/path/to/parse_ini example.ini)"` in your script would define a +set of arrays whose values can be accessed in the Bash standard method, using the +keys from the INI file. The functions from the `parse_ini` script can be included in your own scripts to provide INI file parsing abilities without the need to call an external command. @@ -41,8 +41,8 @@ an `eval` with the desired `[options]` and an INI file name to parse. Using The Arrays ================ Once the parser has finished its job (assuming you ran it within an `eval`), the -arrays defined by the parse_ini script will become available to usage within your -own script. +arrays defined by the parse_ini script will become available to usage within +your own script. To access the arrays depends upon the options used to call the script. For all the examples below, assume that the `example.ini` referenced in the @@ -54,16 +54,16 @@ Global Key = Global Value [ Section 1 ] Section 1 Key = Ssection 1 Value ``` -In this example, there is 1 key/value property in the 'global' section of the INI, -and a section named "section 1", which itself has 1 key/value property associated -with it. Note the case of the key names as this is important when the arrays are -defined. +In this example, there is one key/value property in the 'global' section of the +INI, and a section named "section 1", which itself has 1 key/value property +associated with it. Note the case of the key names as this is important when +the arrays are defined. For these examples, the `parse_ini` script will be called directly so the output of the parser can be examined - the same commands demonstrated here can be used within an `eval` in a script. -* Basic usage - no options: +Basic usage - no options: ``` $ /path/to/parse_ini example.ini declare -g -A INI_global @@ -73,48 +73,49 @@ INI_Section_1["Section 1 Key"]='Ssection 1 Value' ``` Here we can see that the parser has declared an associative array named `INI_global` (line 1), followed by an array element named `Global Key` (line 2). -It then declares a new section called `INI_Section_1` (line 3) which has it's own -element, `Section 1 Key` (line 4). +It then declares a new section called `INI_Section_1` (line 3) which has it's +own element, `Section 1 Key` (line 4). -To use the arrays (once `eval`ed into your script) would be as simple as accessing -any associative array element: +To use the arrays (once `eval`ed into your script) would be as simple as +accessing any associative array element: ``` printf "%s\\n" "${INI_global["Global Key"]}" printf "%s\\n" "${INI_Section_1["Section 1 Key"]}" ``` -The way to understand what array names and element names are created by the parser -it is necessary to understand the format the parser uses to construct the array -definitions (assuming no options are used at this point). The format is: +The way to understand what array names and element names are created by the +parser it is necessary to understand the format the parser uses to construct the +array definitions (assuming no options are used at this point). The format is: ```
['']='' ``` -Where `` is the prefix given to every array/element created by the parser -(the default is `INI`, but can be changed with `--prefix` - demonstrated below). -`` is the delimiter character(s) used in every array/element declared -by the parser (the default is `_`, but can be changed with `--delim` - example -below). `
` is the name of the section taken from the section header -definition in the INI file. `` is the name of the key as defined in the -section of the INI file. And finally, `` is the value taken from the -key/value property in the INI file. +Where `` is the prefix given to every array/element created by the +parser (the default is `INI`, but can be changed with `--prefix` - demonstrated +below). `` is the delimiter character(s) used in every array/element +declared by the parser (the default is `_`, but can be changed with `--delim` - +example below). `
` is the name of the section taken from the +section header definition in the INI file. `` is the name of the key +as defined in the section of the INI file. And finally, `` is the value +taken from the key/value property in the INI file. Using options, the format of the array declarations can be changed. Options exist to: * Change the `` of the arrays declared (the value may be empty), -* Change the delimiter between the `` and `
` (the value may - be empty), -* Change the name of the implied section at the beginning of the file, known as the - 'global' section, -* Covert the ``, `` and `
` to upper or lowercase - before declaring the arrays, -* No squash multiple consecutive blanks into a single "_", as normally happens during - processing. +* Change the delimiter between the `` and `
` (the value + may be empty), +* Change the name of the implied section at the beginning of the file, known as + the 'global' section, +* Covert the ``, `` and `
` to upper or + lowercase before declaring the arrays, +* No squash multiple consecutive blanks into a single "_", as normally happens + during processing. Finally, the arrays may be declared as local (using the `--local` option, or as exported to the environment (using the `--export` option). + INI File Format =============== The INI file format is a very loose format - there are many options and features