~pkal/dirconf

da2c745dc3f49bed2738073ad47e53c2b746f714 — Philip K 2 years ago 686cfad
updated readme
1 files changed, 22 insertions(+), 26 deletions(-)

M README.md
M README.md => README.md +22 -26
@@ 5,37 5,33 @@ dirconf
that instead of storing everything in a file, uses the file system as
a hierarchical key-value storage.

Usage
-----

Initialise a configuration object as follows:

	conf, err := dirconf.Open("path/to/dir")

if `err` is nil, then `conf` shall be a valid configuration object.
This can now be used to retrieve values, as the following examples
demonstrate.
Example
-------

* Query a Boolean value with the key `active`:
	import dc "git.sr.ht/~zge/dirconf"

		active, err := conf.Bool("active")
	var (
		conf dc.Conf
		name string
		age int
	)

	The variable `active` will then and only then be true, if the file
	`path/to/dir/active` exists, regardless of it's content.
	conf.Add(&dc.String{Ptr: &name, Must: true}, "name")
	conf.Add(&dc.Int{Ptr: &age}, "person", "age")
	err := conf.Parse()
	if err != nil {
		// handle error
	}

* Get the integer value `size` from the group `buffer`:

		i, err := conf.Int64("buffer", "size")

	in the file system, this would parse the contents of the file
	`/path/to/dir/buffer/size`, as an Integer. If it is not an
	Integer, `err` shall equal `dirconf.ErrWrongType`.
* Receive a file object as `*os.File` from the key `profile.jpg` in
  the group `user`, subgroup "hans":

		f, err := conf.File("user", "hans", "profile.jpg")
Usage
-----

	If no such file exists, `err` shall equal `dirconf.ErrNoSuchKey`.
After specifying a `dirconf.Conf` variable, one has to call `Conf.Add`
for every option one wants to have parsed. Nothing is done, until
`Conf.Parse()` is called, where all the options are attempted to be set,
either to the value in their file, with additional interpretation if
needed, or to some other value, depending on the `dirconf.Option`
object.

Legal
-----