Add readmeHEADmaster

1 files changed, 27 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..feb75ec
--- /dev/null
+++ b/README.md
@@ -0,0 +1,27 @@
+# icaltool - simple tool for getting info from ical/ics files.
+
+`icaltool` started out as a tool for myself to count the number of vacation days I had used from an ownCloud calendar. Since ownCloud didn't have the functionality, I downloaded the ics file, and wrote this tool to extract it myself. Hopefully it can be useful to others as well.
+
+## Usage
+
+Currently `icaltool`is extremely primitive, it takes exactly two arguments, the file to parse and the pattern to look for. The pattern consist of a key in an event, followed by a colon, and followed by a regex to match against the value of the key. like this:
+
+    # find any event with 'vacation' somewhere in it's summary fiel
+    icaltool calendar.ics summary:vacation
+
+The pattern is case insensitive, and supports most perl-like regexes.
+
+    # find all events in 2018 starting on the 14th of the month
+    icaltool calendar.ics dtstart:2018\\d{2}14
+
+## Limitations
+
+Queries against more than one key is not supported at this time. Neither does the tool take timezones or other parameters into consideration. The output format is not configurable, except by changing the code and recompiling it. And there's no helpful error messages or usage info. The code calls `unwrap` everywhere, so most likely you'll just get some cryptic internal error from Rust.
+
+The heavy lifting of parsing the ics files is done by the [ical crate](https://docs.rs/crate/ical).
+
+## Contributing
+
+If you do find this tool useful, and have suggestions or even patches that will improve it, please [let me know](mailto:haraldei@anduin.net).
+
+`icaltool` is licensed as [GPLv3](https://www.gnu.org/licenses/gpl.txt), see the file LICENSE for the details.
\ No newline at end of file