From 30771b4471a01b09bf2a0e5f15f22dd1f067cb27 Mon Sep 17 00:00:00 2001 From: Darren 'Tadgy' Austin Date: Sun, 21 Jul 2019 01:28:46 +0100 Subject: [PATCH] Documentation. Clean up directory. --- SPEC => README.md | 156 ++++++--- TODO | 14 - bits/comments.ini | 42 --- bits/duplicate-sections.ini | 10 - bits/key-blanks.ini | 314 ------------------ bits/other-peoples/inifile.bash | 234 ------------- bits/other-peoples/sites | 3 - .../someone_elses_bash_ini_parser/README | 118 ------- .../someone_elses_bash_ini_parser/TODO | 7 - .../someone_elses_bash_ini_parser/read_ini.sh | 272 --------------- .../test/test.sh | 28 -- .../test/test1.ini | 40 --- .../test/test1.out.correct | 10 - .../test/test1.sh | 21 -- .../test/test2.ini | 8 - .../test/test2.out.correct | 2 - .../test/test2.sh | 8 - .../test/test3.ini | 23 -- .../test/test3.out.correct | 12 - .../test/test3.sh | 25 -- .../test/test4.ini | 14 - .../test/test4.out.correct | 5 - .../test/test4.sh | 15 - .../test/test5.ini | 13 - .../test/test5.out.correct | 6 - .../test/test5.sh | 16 - .../test/test6.ini | 27 -- .../test/test6.out.correct | 30 -- .../test/test6.sh | 56 ---- .../test/test7.ini | 8 - .../test/test7.out.correct | 7 - .../test/test7.sh | 30 -- .../test/test8.ini | 4 - .../test/test8.out.correct | 2 - .../test/test8.sh | 9 - .../test/test9.ini | 12 - .../test/test9.out.correct | 6 - .../test/test9.sh | 16 - .../someone_elses_bash_ini_parser/url | 1 - bits/quotes-sed.sh | 34 -- bits/readline/readline | 76 ----- bits/readline/readline.ini | 18 - bits/sanatise_section/sanatise_section | 23 -- bits/sanatise_section/sanatise_section.ini | 8 - bits/sections.ini | 7 - bits/sed-parser/sed-parser-simplified.sh | 185 ----------- bits/sed-parser/sed-parser.broken-merge | 123 ------- bits/sed-parser/sed-parser.duplicates | 128 ------- bits/sed-parser/sed-parser.nofunc | 117 ------- bits/sed-parser/sed-parser.sh | 185 ----------- bits/value-tests.ini | 41 --- 51 files changed, 101 insertions(+), 2468 deletions(-) rename SPEC => README.md (50%) delete mode 100644 TODO delete mode 100644 bits/comments.ini delete mode 100644 bits/duplicate-sections.ini delete mode 100644 bits/key-blanks.ini delete mode 100644 bits/other-peoples/inifile.bash delete mode 100644 bits/other-peoples/sites delete mode 100644 bits/other-peoples/someone_elses_bash_ini_parser/README delete mode 100644 bits/other-peoples/someone_elses_bash_ini_parser/TODO delete mode 100755 bits/other-peoples/someone_elses_bash_ini_parser/read_ini.sh delete mode 100755 bits/other-peoples/someone_elses_bash_ini_parser/test/test.sh delete mode 100644 bits/other-peoples/someone_elses_bash_ini_parser/test/test1.ini delete mode 100644 bits/other-peoples/someone_elses_bash_ini_parser/test/test1.out.correct delete mode 100755 bits/other-peoples/someone_elses_bash_ini_parser/test/test1.sh delete mode 100644 bits/other-peoples/someone_elses_bash_ini_parser/test/test2.ini delete mode 100644 bits/other-peoples/someone_elses_bash_ini_parser/test/test2.out.correct delete mode 100755 bits/other-peoples/someone_elses_bash_ini_parser/test/test2.sh delete mode 100644 bits/other-peoples/someone_elses_bash_ini_parser/test/test3.ini delete mode 100644 bits/other-peoples/someone_elses_bash_ini_parser/test/test3.out.correct delete mode 100755 bits/other-peoples/someone_elses_bash_ini_parser/test/test3.sh delete mode 100644 bits/other-peoples/someone_elses_bash_ini_parser/test/test4.ini delete mode 100644 bits/other-peoples/someone_elses_bash_ini_parser/test/test4.out.correct delete mode 100755 bits/other-peoples/someone_elses_bash_ini_parser/test/test4.sh delete mode 100644 bits/other-peoples/someone_elses_bash_ini_parser/test/test5.ini delete mode 100644 bits/other-peoples/someone_elses_bash_ini_parser/test/test5.out.correct delete mode 100755 bits/other-peoples/someone_elses_bash_ini_parser/test/test5.sh delete mode 100644 bits/other-peoples/someone_elses_bash_ini_parser/test/test6.ini delete mode 100644 bits/other-peoples/someone_elses_bash_ini_parser/test/test6.out.correct delete mode 100755 bits/other-peoples/someone_elses_bash_ini_parser/test/test6.sh delete mode 100644 bits/other-peoples/someone_elses_bash_ini_parser/test/test7.ini delete mode 100644 bits/other-peoples/someone_elses_bash_ini_parser/test/test7.out.correct delete mode 100755 bits/other-peoples/someone_elses_bash_ini_parser/test/test7.sh delete mode 100644 bits/other-peoples/someone_elses_bash_ini_parser/test/test8.ini delete mode 100644 bits/other-peoples/someone_elses_bash_ini_parser/test/test8.out.correct delete mode 100755 bits/other-peoples/someone_elses_bash_ini_parser/test/test8.sh delete mode 100644 bits/other-peoples/someone_elses_bash_ini_parser/test/test9.ini delete mode 100644 bits/other-peoples/someone_elses_bash_ini_parser/test/test9.out.correct delete mode 100755 bits/other-peoples/someone_elses_bash_ini_parser/test/test9.sh delete mode 100644 bits/other-peoples/someone_elses_bash_ini_parser/url delete mode 100644 bits/quotes-sed.sh delete mode 100755 bits/readline/readline delete mode 100644 bits/readline/readline.ini delete mode 100755 bits/sanatise_section/sanatise_section delete mode 100644 bits/sanatise_section/sanatise_section.ini delete mode 100644 bits/sections.ini delete mode 100644 bits/sed-parser/sed-parser-simplified.sh delete mode 100644 bits/sed-parser/sed-parser.broken-merge delete mode 100644 bits/sed-parser/sed-parser.duplicates delete mode 100644 bits/sed-parser/sed-parser.nofunc delete mode 100644 bits/sed-parser/sed-parser.sh delete mode 100644 bits/value-tests.ini 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_