dusual/sherlock

Natural-language event parser for Javascript

Sherlock

https://github.com/Tabule/Sherlock/

Sherlock parses events written in plain English, and returns an object defining a basic event. Try demo.

It was designed to allow event creation using natural language. For example, "The party is tomorrow from 3pm to 5pm." will return:

{
	eventTitle: 'The party',
	startDate: Sat Dec 01 2012 15:00:00 GMT-0600 (CST),
	endDate: Sat Dec 01 2012 17:00:00 GMT-0600 (CST),
	isAllDay: false
}

Sherlock can handle times, days, date ranges, event titles, and more. It supports a wide variety of input formats that are common in US English. Try the demo, and let us know if you find an input that does not work.

Just like Sherlock the detective finds the clues needed to solve a mystery by looking at a crime scene, Sherlock.js finds the components needed to define an event by looking at a sentence. But Sherlock doesn't work alone...

Watson

Sherlock is great for parsing sentences into basic events, but what if you need to manipulate the data for your specific use case or add some extra properties to the returned object? Just tell Watson to help Sherlock out!

Watson provides a preprocessor and postprocessor layer on Sherlock that allows you to customize Sherlock's input and output. With the preprocessor, you can manipulate the input string before it is parsed by Sherlock. The postprocessor allows you to modify the data returned by Sherlock, or add any additional properties.

For example, Tabule uses Watson's preprocessor for app-specific logic, such as determining which course the user wants to add their assignment to. We use the postprocessor to validate the data, such as making sure the user provided a due date. View an example watson.js processor.

Basically, Watson helps Sherlock fit in and interact with the world.

Usage

Include sherlock.js and watson.js in your code.

<script type="text/javascript" src="sherlock.js"></script>
<!-- optional - include if you want Watson to help Sherlock -->
<script type="text/javascript" src="watson.js"></script>

To parse a string, simply use

var sherlocked = Sherlock.parse('Homework 5 due next monday at 3pm');

// Basic properties
var	title = sherlocked.eventTitle;		// 'Homework 5 due'
var	startDate = sherlocked.startDate; 	// Date object pointing to next monday at 3pm
var	endDate = sherlocked.endDate; 		// null in this case, since no duration was given
var	isAllDay = sherlocked.isAllDay;		// false, since a time is included with the event

// Example of an additional custom property added by Watson
var validated = sherlocked.validated; 	// true

That's it!

Methods

There are 2 methods in Sherlock.js.

Sherlock.parse(String)

Sherlock.parse() takes a string representing some English phrase, and returns an object with the following properties:

• eventTitle - string representing Sherlock's best guess at what the event title should be, or null if no title found.
• startDate - Date object representing start of the event, or null if not found.
• endDate - Date object representing end of the event, or null if not found.
• isAllDay - true if the input string describes an all-day event, otherwise false.

Sherlock._setNow(Date)

Sherlock._setNow() allows you to change what time Sherlock thinks it is right now, regardless of the system clock.

Pass in a Date object, and Sherlock will parse strings as if they there were entered on that day and time. Pass in null to clear your custom date and use the system time instead.

This method is primarily meant for debugging purposes.

Limitations

Sherlock was built to handle due date scheduling for Tabule. With that in mind, Sherlock has the following limitations:

• Specifying years is not supported.
• Dates must be in the future.

These two limitations together mean that Sherlock always finds the nearest future date that meets the input. For example, if today is December 25th, 2012 and the user enters 'Oct 27th,' then Sherlock will return October 27, 2013. If the user just enters 'the 15th', then January 15th, 2013 will be returned.

A more aggressive example would be if you enter '12/25 at 8pm' and it is past 8pm, Sherlock will return 12/26 at 8pm. The reason for this is that if you are scheduling an event and accidently enter today's date for a time that's already passed, in most cases, you probably meant to enter tomorrow's date. However, this can be confusing to the user if they enter 'today at 8pm' and get back tomorrow's date. Eventually, I plan to modify Sherlock to return these more aggressive assumptions as suggested dates in addition to the actual entered date.

How does this compare to alternatives like Datejs?

Datejs is a date manipulation library, and is not built for handling user input. That means it can only parse very specific dates or times. If you are progrematically passing values or have a dedicated input field for times and a separate one for dates, then you can use Datejs. If you want to let users enter dates, you need Sherlock.

Oh, and Mr. Holmes could take on a ninja any day.

License

The MIT License (MIT) Copyright (c) 2014 Tabule, Inc.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.