Modified readme

README.md

@@ -4,8 +4,59 @@
 [![Coverage Status](https://coveralls.io/repos/github/aneshas/flags/badge.svg?branch=trunk)](https://coveralls.io/github/aneshas/flags?branch=trunk)
 [![Go Report Card](https://goreportcard.com/badge/github.com/aneshas/flags)](https://goreportcard.com/report/github.com/aneshas/flags)
 
-Configuration package inspired by this talk/[article](https://peter.bourgon.org/go-for-industrial-programming/) by Peter Bourgon.
+Configuration package inspired by this [talk](https://www.youtube.com/watch?v=PTE4VJIdHPg) / [article](https://peter.bourgon.org/go-for-industrial-programming/) by Peter Bourgon.
 
 The guiding idea behind this package is that `flags are the best way to configure your program` and thus it provides a thin wrapper
-around go standard flag package while providig an extra degree of configurability via different extendable/composable mechanisms such as
-`env variables`, `config files` etc... on an opt-in basis.
+around go standard flag package while providig an extra degree of configurability via different extendable / composable mechanisms such as
+`environment variables`, `config files` etc... on an opt-in basis.
+
+Two of these mechanisms are provided by default `env` for environment variables and `json` for flat json config giles. Others resolvers can be implemented additionaly.
+
+# Example Usage
+
+As (almost) drop-in replacement for `flag` package:
+
+```go
+var fs flags.FlagSet
+
+var (
+	host     = fs.String("host", "DB host", "localhost")
+	username = fs.String("username", "DB username", "root")
+	port     = fs.Int("port", "DB port", 3306)
+)
+
+fs.Parse(os.Args)
+```
+
+Though where it really shines is when you use it in combination with different config mechanisms such as env flags or json config files:
+
+```go
+var fs flags.FlagSet
+
+var (
+	host     = fs.String("host", "DB host", "localhost")
+	username = fs.String("username", "DB username", "root", json.ByName(), env.Named("UNAME"))
+	port     = fs.Int("port", "DB port", 3306, json.ByName(), env.ByName())
+	cfg      = fs.String("config", "JSON Config file", "config.json", env.ByName())
+)
+
+fs.Parse(
+	os.Args,
+  // Optional prefix
+	env.WithPrefix("MYAPP_"),
+  // Path to config file
+	json.WithConfigFile(cfg),
+)
+```
+
+As you can see, flag definitions accept additional arguments where you can set different mechanisms that will be evaluated in a sequence and the first one that yields a valid value will be used.
+
+For example here:
+
+```go
+username = fs.String("username", "DB username", "root", json.ByName(), env.Named("UNAME"))
+```
+
+If no `-username` flag is provided, the package would next try to find the value as a json key in the provided config file (see below), if the value is not found it will try to read the environment variable `UNAME`. You can put as many resolvers as you want (even of the same kind).
+
+**NOTE** If flag is provided explicitly on the command line it wil **always** take a precedence regardless if value exists in environment or config file for example.

example/main.go

@@ -14,7 +14,7 @@ func main() {
 
 	var (
 		host     = fs.String("host", "DB host", "localhost")
-		username = fs.String("username", "DB username", "root", env.ByName(), env.Named("FOO"))
+		username = fs.String("username", "DB username", "root", json.ByName(), env.Named("UNAME"))
 		port     = fs.Int("port", "DB port", 3306, json.ByName(), env.ByName())
 		cfg      = fs.String("config", "JSON Config file", "config.json", env.ByName())
 	)