converts natural language date ranges into queries suitable for a search engine
APACHE-2.0 License
h1. date-range-parser.js
The date-range-parser is a standalone javascript library that provides a natural language like construct for generating date range queries that would be fed into a database or search service
This is a preferred option for power user tools as standard date widgets require the use of a mouse.
the date-range-parser also contains a number parser that follows the same constructs
h2. How To Use
@dateRangeParser.parse()@ either return @null@, if the string can not be converted, or an object with @start@ and @end@ attributes @start@ and @end@ are either null (meaning no constraint) or the number of seconds since epoch. Often these values can be passed directly to the db/search service. Alternately they can be passed directly into the @Date@ constructor to produce javascript Date objects @var myDate = new Date(range.start)@
pre. $("#date-range").blur(function() { var range = window.dateRangeParser.parse($(this).val()); if(range) { $("#start-date").val(range.start || ""); $("#end-date").val(range.end || ""); } else { alert("Invalid date range entered"); } });
h4. Note on Time Zones
date-range-parser.js work entirely in @UTC / GMT / Z (+0)@ timezone. Usually databases will store dates like this. If local time is preferred, the date can be extracted with the timezone applied using methods from the javascript "Date":https://developer.mozilla.org/en/JavaScript/Reference/global_objects/date object.
h4. Note on @now@
the date range parser can generate several types of queries relative to @now@ which is defined as the current time on the users computer (to the millisecond) This can be overridden by setting @window.dateRangeParser.now@ to a new value
h2. Quick Syntax Guide
@now@
@today@
@tomorrow@
@yesterday@
@last/this/next week@
@last/this/next month@
@last/this/next year@
@1000secs@
@5mins@
@1day@
@2days@
@8d@
@9months@
@2yrs@
@5@
@5:35@
@5:35:12@
@2011@
@2011-03@
@2011-03-04@
@2011-03-04 04@
@2011-03-04 04:15@
@2011-03-04 04:15:29@
@2010 -> 2011@
@2005-11-05 16:13:49 -> 2005-11-06 05:12:11@
@last week -> next week@
@2011-05 ->@
@< now@
@2000-01-01 -> last week@
@2000 -> 10y@
@3mins < now@
@last year -> 6months@
@2010-05-13 05:13 <> 10m@
@now <> 1yr@
@lastweek <> 1month@
h2. Syntax in more detail
h3. Keywords / Key Phrases
Creates a range covering all value dates relative to @now@
Note: spaces are optional
h3. Ranges
Entering a range alone creates a date search centered on @now@ and spreading in to the past and future by the specified amount Examples: given now is @2001-09-09 01:46:40@
The following aliases can be used with ranges;
Note: Months are always calculates as 31 days, and years are always calculated as 365 days
h3. Dates
A date format alone will search the range of dates covered by the date.
Dates must be specified in the YYYY-MM-DD format
h3. Times
entering a time creates a range in today examples:
Times must be entered in the H-MM-SS format, and am/pm can not be used
h3. DateTime
entering a date and time part creates a range on the specified interval examples:
h3. Date Ranges
A Date Range is created by specifying two dates in any format (Keyword / Date / Time / DateTime) separated by @<@ or @->@ (both do the same thing) If either end of the date range is missing, it is the same as having no constraint in that direction Examples:
h3. Date Range using offset
Searches the specified date including the range in the direction specified Example:
h3. Anchor Ranges
entering a date followed by the @<>@ range operator followed by a range creates search centered on the date extended in both directions by the range Example:
h3. Number Ranges
The @parseNumber@ function can be used to parse a numnber range following the same conventions as the date range. The numberParser returns javascript numbers (which are either 32bit integers or 64bit floats)