From 6ab71ce923872feded41f736685f19e9f69d95d7 Mon Sep 17 00:00:00 2001 From: Darren 'Tadgy' Austin Date: Sun, 21 Jul 2019 02:33:35 +0100 Subject: [PATCH] Documentation updates. --- README.md | 95 ++++++++++++++++++++++--------------------------------- 1 file changed, 37 insertions(+), 58 deletions(-) diff --git a/README.md b/README.md index 88b8dd6..66a2409 100644 --- a/README.md +++ b/README.md @@ -45,7 +45,6 @@ by enabling them as a `--option`. See the output of `parse_ini --help` for the options. The main features of the supported INI file format are as follows: -#........1.........2.........3.........4.........5.........6.........7.........8 General File Format ------------------- @@ -55,77 +54,57 @@ General File Format as comments and ignored during parsing. Comments must appear on a line on their own. * Escaping of shell special characters is not required. +* Using `\`as the last character on a line allows continuation of that line + onto a subsequent line. Leading whitespace is removed from the continuation + lines. Comments are not recognised between continuation lines. +* Whitespace is ignored wherever possible. +* The first section (before the first explicit section definition) of the INI + file is known as the "global" section, and it continues until the first + explicit definition of a section (or until EOF). The "global" section is + optional. - -[section] format +[Section] Format ---------------- -* Section names must only be comprised of alphanumeric characters, plus _.-+ -* The .-+ characters in section names will be converted to _ -* Section names are case sensitive (unless --ignore-case? is used), so 'Foo' and 'foo' are different sections. +* Sections run from one section definition until the next (or EOF). +* Sections are optional. The "global" section can be the only section used. +* Section names can only be comprised of alphanumeric characters, plus `_`, `.`, + `-`, and `+`. +* Section names are case sensitive, unless one of the options `--lowercase` or + `--uppercase` is used. +* The characters `.`, `-`, and `+` will be converted to `_` when defining the + bash arrays. * Whitespace is ignored before and after the section name. * Section names should not be quoted in any way. +* Sections can be duplicated in different parts of the INI file - their keys + and values will be merged as long as the keys are unique. If the keys are + not unique they may overwrite or append values (depending upon CLI options). Keys ---- -* Keys must only be comprised of alphanumeric characters, plus _.-+ +* Key names are case sensitive, unless one of the `--lowercase` or `--uppercase` + options is used. +* Keys can be comprised of any character. * Keys should not be quoted in any way. +* Keys are delimited from the values by an `=`, unless the `--bound` option is + used. +* If duplicate keys are defined in the same section, the latter definition takes + presedence, unless the `--duplicates-merge`option is used. +#........1.........2.........3.........4.........5.........6.........7.........8 Values ------ -Values can optionally be bookmarked with single or double quotes. - - If quotes are to be used, they must be the first and last characters of the value - - Whitespace within the quotes is retained verbatim. - - Backslash line continuation is supported within quotes (but leading whitespace on subsequent lines is removed). -Values can be continued by use of \ in the last column. - - Subsequent lines are subject to leading whitespace removal as normal. - - Comments are not recognised on subsequent lines - they are treated as part of the value. +* Values are used verbatim - there is no conversion to upper or lower case. +* Values can be surrounded by quotes in order to maintain whitespace. Quotes + must be the first and last characters on the line (after whitespace removal). Booleans -------- -* no_