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

Added section on using no prefix or delim. Updated formatting.

Browse source
This commit is contained in:
Darren 'Tadgy' Austin 2019-07-25 21:24:47 +01:00
commit f7786946c0
1 changed files with 46 additions and 16 deletions
Download patch file Download diff file Expand all files Collapse all files

62
README.md
View file

@ -22,33 +22,32 @@ Features of the parser include:
Using the Parser Using the Parser
================ ================
The basic usage of the parser is: `/path/to/parse_ini [options] <INI file>`. The basic usage of the parser is: `/path/to/parse-ini [options] <INI file>`.
The `[options]` can be seen using `/path/to/parse_ini --help` and have detailed The `[options]` can be seen using `/path/to/parse-ini --help` and have detailed
descriptions. 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 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 set of arrays whose values can be accessed in the Bash standard method, using the
keys 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.
In this usage, all that is required is a call to the `parse_ini` function within In this usage, all that is required is a call to the `parse-ini` function within
an `eval` with the desired `[options]` and an INI file name to parse. 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 arrays defined by the parse-ini script will become available to usage within
your 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
command line is a simple ini file, with contents: command line is a simple ini file, with contents:
``` ```
Global Key = Global Value Global Key = Global Value
@ -60,13 +59,13 @@ 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 associated with it. Note the case of the key names as this is important when
the arrays are 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
INI_global["Global Key"]='Global Value' INI_global["Global Key"]='Global Value'
declare -g -A INI_Section_1 declare -g -A INI_Section_1
@ -117,7 +116,7 @@ If, for example, you don't like the `<prefix>` used by the parser ("INI" by
default), you can change it with `--prefix` (or `-p` if you prefer short default), you can change it with `--prefix` (or `-p` if you prefer short
options): options):
``` ```
$ /path/to/parse_ini --prefix "Foo" example.ini $ /path/to/parse-ini --prefix "Foo" example.ini
declare -g -A Foo_global declare -g -A Foo_global
Foo_global["Global Key"]='Global Value' Foo_global["Global Key"]='Global Value'
declare -g -A Foo_Section_1 declare -g -A Foo_Section_1
@ -128,27 +127,38 @@ case - this is important since the array names are case sensitive and will need
to be accessed using their case sensitive names (see below for options to change to be accessed using their case sensitive names (see below for options to change
the case of declared arrays). the case of declared arrays).
To access this array (once `eval`ed into your script, you would use:
```
printf "%s\\n" "${Foo_global["Global Key"]}"
printf "%s\\n" "${Foo_Section_1["Section 1 Key"]}"
```
Equally, the `<delimiter>` can be changed either with or independently of the Equally, the `<delimiter>` can be changed either with or independently of the
prefix: prefix:
``` ```
$ /path/to/parse_ini --delim "X" example.ini $ /path/to/parse-ini --delim "X" example.ini
declare -g -A INIXglobal declare -g -A INIXglobal
INIXglobal["Global Key"]='Global Value' INIXglobal["Global Key"]='Global Value'
declare -g -A INIXSection_1 declare -g -A INIXSection_1
INIXSection_1["Section 1 Key"]='Section 1 Value' INIXSection_1["Section 1 Key"]='Section 1 Value'
``` ```
``` ```
$ /path/to/parse_ini --prefix "Foo" --delim "X" example.ini $ /path/to/parse-ini --prefix "Foo" --delim "X" example.ini
declare -g -A FooXglobal declare -g -A FooXglobal
FooXglobal["Global Key"]='Global Value' FooXglobal["Global Key"]='Global Value'
declare -g -A FooXSection_1 declare -g -A FooXSection_1
FooXSection_1["Section 1 Key"]='Section 1 Value' FooXSection_1["Section 1 Key"]='Section 1 Value'
``` ```
Accessed with:
```
printf "%s\\n" "${FooX_global["Global Key"]}"
printf "%s\\n" "${FooX_Section_1["Section 1 Key"]}"
```
We also have the option of changing the name of the 'global' section name used We also have the option of changing the name of the 'global' section name used
when declaring the arrays: when declaring the arrays:
``` ```
$ /path/to/parse_ini --global-name "Head" example.ini $ /path/to/parse-ini --global-name "Head" example.ini
declare -g -A INI_Head declare -g -A INI_Head
INI_Head["Global Key"]='Global Value' INI_Head["Global Key"]='Global Value'
... ...
@ -156,10 +166,11 @@ INI_Head["Global Key"]='Global Value'
Again, note that the name is mixed case, and this will need to be taken into Again, note that the name is mixed case, and this will need to be taken into
account when accessing the array. account when accessing the array.
Say you want to access the arrays using all capitals or all lowercase names. Say you want to access the arrays using all capitals or all lowercase names.
There's an option for that too! Note the combination of options from above: There's an option for that too! Note the combination of options from above:
``` ```
$ /path/to/parse_ini --prefix "Foo" --global-name "Head" --lowercase example.ini $ /path/to/parse-ini --prefix "Foo" --global-name "Head" --lowercase example.ini
declare -g -A foo_head declare -g -A foo_head
foo_head["Global Key"]='Global Value' foo_head["Global Key"]='Global Value'
declare -g -A foo_section_1 declare -g -A foo_section_1
@ -167,7 +178,7 @@ foo_section_1["Section 1 Key"]='Section 1 Value'
``` ```
Or: Or:
``` ```
$ /path/to/parse_ini --prefix "Foo" --global-name "Head" --uppercase example.ini $ /path/to/parse-ini --prefix "Foo" --global-name "Head" --uppercase example.ini
declare -g -A FOO_HEAD declare -g -A FOO_HEAD
FOO_HEAD["Global Key"]='Global Value' FOO_HEAD["Global Key"]='Global Value'
declare -g -A FOO_SECTION_1 declare -g -A FOO_SECTION_1
@ -178,6 +189,25 @@ and upper case accordingly. When using the `--lowercase` or `--uppercase`
options, each of the `<prefix>`, `<delimiter>` and `<section name>` are options, each of the `<prefix>`, `<delimiter>` and `<section name>` are
affected. But the `<key name>` remains in the case from the INI file. affected. But the `<key name>` remains in the case from the INI file.
You can even tell `parse-ini` to not use any `<prefix>` or `<delimiter>`:
```
$ /path/to/parse-ini --prefix "" --delim "" example.ini
declare -g -A global
global["Global Key"]='Global Value'
declare -g -A Section_1
Section_1["Section 1 Key"]='Section 1 Value'
```
Which you would access using:
```
printf "%s\\n" "${global["Global Key"]}"
printf "%s\\n" "${Section_1["Section 1 Key"]}"
```
Note that there are some extra rules that come into play when leaving out the
`<prefix>` and `<delimiter>` - section names cannot begin with numbers, for
example.
Using these options allows you to access the arrays in your preferred style - Using these options allows you to access the arrays in your preferred style -
mixed case, all lowercase or all uppercase, and with any prefix or delimiter mixed case, all lowercase or all uppercase, and with any prefix or delimiter
you prefer. you prefer.
@ -192,7 +222,7 @@ 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
which can be supported. I've tried to implement the widest set of features I which can be supported. I've tried to implement the widest set of features I
can, but there may be functionality missing. Some features are only available can, but there may be functionality missing. Some features are only available
by enabling them as a `--option`. See the output of `parse_ini --help` for the by enabling them as a `--option`. See the output of `parse-ini --help` for the
options. options.
The main features of the supported INI file format are as follows: The main features of the supported INI file format are as follows: