Projects/bash-ini-parser
1
0
Fork 0
Code Releases Wiki Activity

Docs updates.

Browse source
This commit is contained in:
Darren 'Tadgy' Austin 2019-07-21 20:16:32 +01:00
commit bf008dae23
1 changed files with 34 additions and 33 deletions
Download patch file Download diff file Expand all files Collapse all files

67
README.md
View file

@ -28,9 +28,9 @@ descriptions.
The parser outputs Bash syntax associative array declarations, and array The parser outputs Bash syntax associative array declarations, and array
element definitions to `stdout`. These Bash commands can be `eval`ed into 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, 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 using `eval "$(/path/to/parse_ini example.ini)"` in your script would define a
of arrays whose values can be accessed in the Bash standard method, using the keys set of arrays whose values can be accessed in the Bash standard method, using the
from the INI file. keys from the INI file.
The functions from the `parse_ini` script can be included in your own scripts to 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. 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 Using The Arrays
================ ================
Once the parser has finished its job (assuming you ran it within an `eval`), the 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 arrays defined by the parse_ini script will become available to usage within
own script. your own script.
To access the arrays depends upon the options used to call the 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 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 ]
Section 1 Key = Ssection 1 Value Section 1 Key = Ssection 1 Value
``` ```
In this example, there is 1 key/value property in the 'global' section of the INI, In this example, there is one key/value property in the 'global' section of the
and a section named "section 1", which itself has 1 key/value property associated INI, and a section named "section 1", which itself has 1 key/value property
with it. Note the case of the key names as this is important when the arrays are associated with it. Note the case of the key names as this is important when
defined. the arrays are defined.
For these examples, the `parse_ini` script will be called directly so the output 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 of the parser can be examined - the same commands demonstrated here can be used
within an `eval` in a script. within an `eval` in a script.
* Basic usage - no options: Basic usage - no options:
``` ```
$ /path/to/parse_ini example.ini $ /path/to/parse_ini example.ini
declare -g -A INI_global 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 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). `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 It then declares a new section called `INI_Section_1` (line 3) which has it's
element, `Section 1 Key` (line 4). own element, `Section 1 Key` (line 4).
To use the arrays (once `eval`ed into your script) would be as simple as accessing To use the arrays (once `eval`ed into your script) would be as simple as
any associative array element: accessing any associative array element:
``` ```
printf "%s\\n" "${INI_global["Global Key"]}" printf "%s\\n" "${INI_global["Global Key"]}"
printf "%s\\n" "${INI_Section_1["Section 1 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 The way to understand what array names and element names are created by the
it is necessary to understand the format the parser uses to construct the array parser it is necessary to understand the format the parser uses to construct the
definitions (assuming no options are used at this point). The format is: array definitions (assuming no options are used at this point). The format is:
``` ```
<prefix><delimiter><section name>['<key name>']='<value>' <prefix><delimiter><section name>['<key name>']='<value>'
``` ```
Where `<prefix>` is the prefix given to every array/element created by the parser Where `<prefix>` is the prefix given to every array/element created by the
(the default is `INI`, but can be changed with `--prefix` - demonstrated below). parser (the default is `INI`, but can be changed with `--prefix` - demonstrated
`<delimiter>` is the delimiter character(s) used in every array/element declared below). `<delimiter>` is the delimiter character(s) used in every array/element
by the parser (the default is `_`, but can be changed with `--delim` - example declared by the parser (the default is `_`, but can be changed with `--delim` -
below). `<section name>` is the name of the section taken from the section header example below). `<section name>` is the name of the section taken from the
definition in the INI file. `<key name>` is the name of the key as defined in the section header definition in the INI file. `<key name>` is the name of the key
section of the INI file. And finally, `<value>` is the value taken from the as defined in the section of the INI file. And finally, `<value>` is the value
key/value property in the INI file. taken from the key/value property in the INI file.
Using options, the format of the array declarations can be changed. Using options, the format of the array declarations can be changed.
Options exist to: Options exist to:
* Change the `<prefix>` of the arrays declared (the value may be empty), * Change the `<prefix>` of the arrays declared (the value may be empty),
* Change the delimiter between the `<prefix>` and `<section name>` (the value may * Change the delimiter between the `<prefix>` and `<section name>` (the value
be empty), may be empty),
* Change the name of the implied section at the beginning of the file, known as the * Change the name of the implied section at the beginning of the file, known as
'global' section, the 'global' section,
* Covert the `<prefix>`, `<delimiter>` and `<section name>` to upper or lowercase * Covert the `<prefix>`, `<delimiter>` and `<section name>` to upper or
before declaring the arrays, lowercase before declaring the arrays,
* No squash multiple consecutive blanks into a single "_", as normally happens during * No squash multiple consecutive blanks into a single "_", as normally happens
processing. during processing.
Finally, the arrays may be declared as local (using the `--local` option, or as Finally, the arrays may be declared as local (using the `--local` option, or as
exported to the environment (using the `--export` option). exported to the environment (using the `--export` option).
INI File Format INI File Format
=============== ===============
The INI file format is a very loose format - there are many options and features The INI file format is a very loose format - there are many options and features