diff --git a/SPEC b/README.md similarity index 50% rename from SPEC rename to README.md index a842f2f..88b8dd6 100644 --- a/SPEC +++ b/README.md @@ -1,3 +1,97 @@ +Bash INI File Parser +==================== +This is my attempt at a Bash INI File Parser. It's probably not elegant, +certainly not fast, but it does implement a large set of options and features. + +I started work on this parser simply because I couldn't find an existing example +that wasn't just a hack, incomplete or didn't have the features I expected from +a decent parser. I hope I've come up with something helpful for other people, +but it's scratched a personal itch and I'll be using it in my future projects. + +Features of the parser include: + * Global properties section. + * Unlimited custom section names to contain any number of properties. + * Section and keys can be case sensitive, or converted to upper/lower case. + * Line comments. + * Duplicate key handling - duplicate keys can be handled in 2 different ways. + * Custom bound delimiter. + * Booleans. + * ... and more! + + +Usage +===== +The basic usage of the parser is: `parse_ini [options] `. +The `[options]` can be seen using `parse_ini --help` and have detailed +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 "$(parse_ini test.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. + + +INI File Format +=============== +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 +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 +options. + +The main features of the supported INI file format are as follows: +#........1.........2.........3.........4.........5.........6.........7.........8 + +General File Format +------------------- +* Blank lines are ignored and can be used to separate sections/properties for + easy reading. +* After leading whitespace removal, lines beginning with `#` or `;` are treated + as comments and ignored during parsing. Comments must appear on a line on + their own. +* Escaping of shell special characters is not required. + + +[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. +* Whitespace is ignored before and after the section name. +* Section names should not be quoted in any way. + +Keys +---- +* Keys must only be comprised of alphanumeric characters, plus _.-+ +* Keys should not be quoted in any way. + +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. + +Booleans +-------- +* no_