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!

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 used Watson's preprocessor for app-specific logic, such as determining which course the user wants to add their assignment to. We used 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.

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

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.