Docs updates.
This commit is contained in:
parent
e15cc878e5
commit
bf008dae23
1 changed files with 34 additions and 33 deletions
67
README.md
67
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:
|
||||
```
|
||||
<prefix><delimiter><section name>['<key name>']='<value>'
|
||||
```
|
||||
Where `<prefix>` is the prefix given to every array/element created by the parser
|
||||
(the default is `INI`, but can be changed with `--prefix` - demonstrated below).
|
||||
`<delimiter>` 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). `<section name>` is the name of the section taken from the section header
|
||||
definition in the INI file. `<key name>` is the name of the key as defined in the
|
||||
section of the INI file. And finally, `<value>` is the value taken from the
|
||||
key/value property in the INI file.
|
||||
Where `<prefix>` is the prefix given to every array/element created by the
|
||||
parser (the default is `INI`, but can be changed with `--prefix` - demonstrated
|
||||
below). `<delimiter>` 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). `<section name>` is the name of the section taken from the
|
||||
section header definition in the INI file. `<key name>` is the name of the key
|
||||
as defined in the section of the INI file. And finally, `<value>` 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 `<prefix>` of the arrays declared (the value may be empty),
|
||||
* Change the delimiter between the `<prefix>` and `<section name>` (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 `<prefix>`, `<delimiter>` and `<section name>` 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 `<prefix>` and `<section name>` (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 `<prefix>`, `<delimiter>` and `<section name>` 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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue