Documentation. Clean up directory.
This commit is contained in:
parent
9f284ef302
commit
30771b4471
51 changed files with 101 additions and 2468 deletions
137
README.md
Normal file
137
README.md
Normal file
|
|
@ -0,0 +1,137 @@
|
|||
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] <INI file>`.
|
||||
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_<option> sets it to 0/false, else 1/true.
|
||||
* Later settings of the same key override previous ones - last one wins.
|
||||
|
||||
Quotes
|
||||
------
|
||||
* Quotes are not required for section names, keys or values. However, in some cases, quotes around the value may be required; for example, when the value begins or ends with whitespace which should be retained in the value - a set of quotes (either "..." or '...') should be used around the value.
|
||||
* Quotes are not required and should not be used around section names or keys.
|
||||
* If the value is within quotes ("" or ''), any use of the same quote character (either " or ') must be backslash escaped.
|
||||
|
||||
|
||||
# http://en.wikipedia.org/wiki/INI_file:
|
||||
# * Provides a good explanation of the ini format - use this for docs *
|
||||
# * INI's have 'sections' and 'properties'. Properties have key = value format *
|
||||
#
|
||||
# Case insensitivity: Case is not changed, unless option used to covert to lower/upper case.
|
||||
# Comments: Allow ; and # for comments. Must be on their own line.
|
||||
# Blank lines: Blank lines are ignored.
|
||||
# Escape chars: \ at the end of a line will continue it onto next (leading whitespace is removed per normal)
|
||||
# Ordering: GLOBAL section must be at the top, sections continue until next section or EOF.
|
||||
|
||||
# Duplicate names: Duplicate property values overwrite previous values.
|
||||
# Provide an option to abort/error is duplicate is found?
|
||||
# Add option to merge duplicates separated by octal byte (\036 ??)
|
||||
# Duplicate sections are merged. Option to error if dup.
|
||||
# Global properties: Support. Add to a GLOBAL section?
|
||||
# Hierarchy: No hierarchy support. Each section is own section.
|
||||
# Name/value delim: Use = by default. Allow : via option?
|
||||
# Quoted values: Allow values to be within " and ' to keep literal formatting.
|
||||
# Whitespace: Whitespace around section labels and []s is removed.
|
||||
# Whitespace within section labels is kept / translated.
|
||||
# Whitespace around property names is removed.
|
||||
# Whitespace within property names is kept as is (spaces squashed - option to override).
|
||||
# Property values have whitespace between = and data removed.
|
||||
# Property values are kept as is (no squashing)
|
||||
# http://www.regular-expressions.info/posixbrackets.html
|
||||
# http://ajdiaz.wordpress.com/2008/02/09/bash-ini-parser/
|
||||
# https://github.com/rudimeier/bash_ini_parser/blob/ff9d46a5503bf41b3344af85447e28cbaf95350e/read_ini.sh
|
||||
# http://tldp.org/LDP/abs/html/
|
||||
# Specs:
|
||||
# [section] Can be upper/lower/mixed case (set by options)
|
||||
# Can only include: '-+_. [:alnum:]'
|
||||
# # Any single or consecutive occurance of '-+_. ' are converted to a *single* _
|
||||
# # eg: [foo -+_. bar] becomes [foo_bar] ??
|
||||
# Any leading/trailing spaces/tabs between the []s and name will be removed.
|
||||
|
||||
|
||||
TODO
|
||||
====
|
||||
* Specific section parsing: only parse specified section(s) given on the command
|
||||
line (separate by commas?). For the global section, use `.`. For every
|
||||
section but global, use `*`.
|
||||
* Allow changing the characters accepted as comments in the INI file.
|
||||
* Allow the key/value deliminator to be more than one character.
|
||||
Loading…
Add table
Add a link
Reference in a new issue