From 4222e716440463528243881486b24c56692559bf Mon Sep 17 00:00:00 2001
From: Mike Barrett <mike182uk@gmail.com>
Date: Sat, 15 Dec 2012 22:37:13 +0000
Subject: [PATCH] add readme

---
 README.md | 155 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 155 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..62e0ca0
--- /dev/null
+++ b/README.md
@@ -0,0 +1,155 @@
+#timestring.js
+
+timestring.js attempts to parse a human readable time string into a time based value.
+
+##Overview
+
+```js
+var str = '1h 15m';
+var time = str.parseTime(); 
+
+console.log(time); // will log 4500
+```
+
+In the example above `str` is just a plain old `String` object. timestring.js adds a new method to the `String` objects prototype named `parseTime`. This method parses the string and returns a time based value. 
+
+**By default the returned time value will be in seconds.**
+
+The time string can contain as many time groups as needed:
+
+```js
+var str = '1d 3h 25m 18s';
+var time = str.parseTime(); 
+
+console.log(time); // will log 98718
+```
+
+and can be as messy as you like:
+
+```js
+var str = '1 d    3h 25              m         1   8s';
+var time = str.parseTime(); 
+
+console.log(time); // will log 98718
+```
+
+As well as using the `String` objects `parseTime` method you can create a `Timestring` object and parse the string manually:
+
+```js
+var str = '1h 15m';
+var time = (new Timestring()).parse(str);
+
+console.log(time); // will log 4500
+```
+
+##Keywords
+
+timestring.js will parse the following keywords into time values:
+
+1. `s, sec, secs, second, seconds` - will parse to seconds
+2. `m, min, mins, minute, minutes` - will parse to minutes
+3. `h, hr, hrs, hour, hours` - will parse to hours
+4. `d, day, days` - will parse to days
+5. `w, week, weeks` - will parse to weeks
+6. `mth, mths, month`, months - will parse to months
+7. `y, yr, yrs, year`, years - will parse to years
+
+Keywords can be used interchangeably:
+
+```js
+var str = '1day 15h 20minutes 15s';
+var time = str.parseTime();
+
+console.log(time); // will log 141615
+```
+
+##Return Time Value
+
+By default the return time value will be in seconds. This can be changed by passing one of the following strings as an argument to `String.parseTime` or `Timestring.parse`:
+
+1. `s` - Seconds
+2. `m` - Minutes
+3. `h` - Hours
+4. `d` - Days
+5. `w` - Weeks
+6. `mth` - Months
+7. `y` - Years
+
+```js
+var str = '22h 16m';
+
+var hours = str.parseTime('h'); // 22.266666666666666 
+var days = str.parseTime('d'); // 0.9277777777777778 
+var weeks = str.parseTime('w'); // 0.13253968253968254
+
+// or
+
+var hours = (new Timestring()).parse(str, 'h');
+var days = (new Timestring()).parse(str, 'd');
+var weeks = (new Timestring()).parse(str, 'w');
+```
+
+##Optional Configuration
+
+timestring.js makes a few assumptions:
+
+1. There are 24 hours per day
+2. There are 7 days per week
+3. There are 4 weeks per month
+4. There are 12 months per year
+
+These settings can be changed by passing a settings object as an argument to `String.parseTime` or to the `Timestring` objects constructor.
+
+The following settings are configurable:
+
+1. `hoursPerDay`
+2. `daysPerWeek`
+3. `weeksPerMonth`
+4. `monthsPerYear`
+
+```js
+var str = '1d';
+
+var settings = {
+	hoursPerDay: 1
+}
+
+var time = str.parseTime('h', settings);
+
+// or 
+
+var time = (new Timestring(settings)).parse(str, 'h');
+
+
+console.log(time) // will log 1
+```
+
+In the example of above `hoursPerDay` is being set to `1`. When the time string is being parsed, the return value is being specified as hours. Normally `1d` would parse to `24` hours (as by deafult there are 24 hours in a day) but because `hoursPerDay` has been set to `1`, `1d` is now only equal to `1` hour.
+
+This would be useful for specific application needs. 
+
+***Example**  - Employees of my company work 7.5 hours a day, and only work 5 days a week. In my time tracking app, when they type `1d` i want 7.5 hours to be tracked. When they type `1w` i want 5 days to be tracked etc.*
+
+```js
+var settings = {
+	hoursPerDay: 7.5,
+	daysPerWeek: 5
+}
+
+// get time values from form input
+var today = document.querySelector('time-input').value,  //'1d'
+	thisWeek = document.querySelector('time-input').value //'1w';
+
+// parse times
+var hoursToday = today.parseTime('h', settings),
+	daysThisWeek = thisWeek.parseTime('d', settings);
+
+// or 
+
+var hoursToday = (new Timestring(settings)).parse(today, 'h'),
+	daysThisWeek = (new Timestring(settings)).parse(thisWeek, 'd')
+
+
+console.log(hoursToday) // will log 7.5
+console.log(daysThisWeek) // will log 5
+```
\ No newline at end of file