updated README.md [ci skip]

README.md

@@ -1,19 +1,45 @@
-argparse
+# argparse
-=========
 
 [![Build Status](https://travis-ci.org/mpeterv/argparse.png?branch=master)](https://travis-ci.org/mpeterv/argparse)
 
-Feature-rich command line parser for Lua inspired by argparse for Python. 
+__argparse__ is a feature-rich command line parser for Lua inspired by argparse for Python. 
 
-WIP. 
+Not everything stated here is implemented. 
 
-TODO
+Features: 
-====
 
-* Add choices, converters. 
+* Parses: 
-* Write tests related to declarative interface. 
+    * Short options(e.g. `-q`); 
-* Write more tests related to parsing. 
+    * Combined short options(e.g. `-zx`); 
-* Write tests related to commands. 
+    * Short options combined with arguments(e.g. `-I/usr/local/include`); 
-* Implement automated help and usage message generation. 
+    * Long options(e.g. `--quiet`); 
-* Improve error messages. 
+    * Long options with arguments(e.g. `--from there); 
-* Suggestions for command typos. E.g. `$ luarocks isntall` -> `Did you mean 'install'?`. 
+    * GNU-style long options with arguments(e.g. `--from=there`). 
+* Supports named arguments consuming several arguments. 
+* Supports options and flags which can be invoked several times, consuming several arguments. 
+
+    Example: 
+
+    ```lua
+    parser:option "-p" "--pair" {
+       count = "*",
+       args = 2
+    }
+
+    parser:flag "-v" "--verbose" {
+       count = "*"
+    }
+
+    local args = parser:parse{"--pair", "Alice", "Bob", "-p", "Emma", "John", "-vvv"}
+    -- args = {
+    --    pair = {
+    --       {"Alice", "Bob"},
+    --       {"Emma", "John"}
+    --    },
+    --    verbose = 3
+    -- }
+    ```
+
+* Supports default values and automatic conversions for arguments. 
+* [___NYI___] Automatically generates error, help and usage messages. 
+* Supports commands(e.g. in [git](http://git-scm.com/) CLI `add`, `commit`, `push`, etc. are commands). Each command has its own set of options and arguments.