Ecolect
Ecolect helps with parsing natural language to intents and values. This can be used as a part in building a natural language interface for things such as bots, voice or search interfaces.
Installation
$ npm install --save ecolect
Matching intents
The main function of Ecolect is to match natural language expressions to
intents. Every expression is parsed into tokens that are matched and scored
using a language specific comparison function. This allows the library to
match for example cookies
even if the user skipped the last s
and entered
cookie
instead.
Matching can also be run in two modes:
- Normal mode - Match a full expression to an intent, which is best used when building a bot or a voice interface.
- Partial mode - Match most of the expression, for example when building an action launcher or a auto-complete for a search engine
Example
const ecolect = ;const en = ;const any = ; const intents = ecolect value'room' value'room' ; // Normal mode - match the bestintents ; intents ;
Options
Option | Default | Description |
---|---|---|
partial |
false |
If partial matching should be performed |
now |
new Date() |
Date to use as a base for times and dates parsed |
weekStartsOn |
0 (Sunday) |
The day the week starts on |
firstWeekContainsDate |
1 |
The day of January which is always in the first week of the year. |
A note about weeks
It's important to set weekStartsOn
and firstWeekContainsDate
to something
expected by the user. The default value for weekStartsOn
is 0
which
indicates that weeks start on Sunday.
firstWeekContainsDate
defaults to 1
which is commonly used in North America
and Islamic date systems. Countries that use this week numbering include
Canada, United States, India, Japan, Taiwan, Hong Kong, Macau, Israel,
Egypt, South Africa, the Phillippines and most of Latin America.
For EU countries most of them use Mondays as the start of the week and the ISO
week system. Settings weekStartsOn
to 1
and firstWeekContainsDate
to 4
will set weeks to a style used in EU and most other European countries, most
of Acia and Oceania.
Middle Eastern countries commonly use Saturday as their first day of week and
a week numbering system where the first week of the year contains January 1st.
Set weekStartsOn
to 6
and firstWeekContainsDate
to 1
to use this
style of week.
For more information about week numbering see the Week article on Wikipedia.
Values
Intents in Ecolect can also contain values, there are several built in types and it's easy to provide custom value validation. Values are used to capture information, such as dates, numbers, names and freeform text.
Values can either be used within intents or standalone as matchers:
const en = ;const date = ; // Create a matcher for the date valueconst dateMatcher = ; // Call the matcher ; // Optionally specify options for parsing, such as what day the week starts on ;
Value types
Integer
Capture any positive integer number.
Language | Examples |
---|---|
English | 20 , zero , one million , 4 000 , 1 dozen , 100k |
Returned value
The returned value is a simple object with one key named value
.
value: 2
Example
const integer = ; builder value'count' ;
Number
Capture any number, including numbers with a fractional element.
Language | Examples |
---|---|
English | 20 , 2.4 million , 8.0 , -12 |
Returned value
The returned value is a simple object with one key named value
.
value: 24
Example
const number = ; builder value'amount' ;
Ordinal
Capture an ordinal, such as 1st
, indicating a position.
Language | Examples |
---|---|
English | 1st , third , 3 , the fifth |
Returned value
The returned value is a simple object with one key named value
.
value: 5
Example
const ordinal = ; builder value'position' ;
Date
Capture a date representing a single day.
Language | Examples |
---|---|
English | today , in 2 days , january 12th , 2010-02-22 , 02/22/2010 , first friday in 2020 |
Returned value
The returned value is an object with the keys year
, month
, day
and can
be turned into a Date
via the function toDate
.
const date = value;
Example
const date = ; builder value'date' ;
Time
Capture a time of day.
Language | Examples |
---|---|
English | 09:00 , 3 pm , at 3:30 am , noon , quarter to twelve , in 2 hours , in 45 minutes |
Returned value
The returned value is an object with the keys hour
, minute
, second
and can
be turned into a Date
via the function toDate
.
const date = value;
Example
const time = ; builder value'time' ;
Date & Time
Capture both a date and a time.
Language | Examples |
---|---|
English | 3pm on Jan 12th , in 2 days and 2 hours , 14:00 |
const dateTime = ; builder value'when' ;
Date Interval
Capture an interval between two dates.
Language | Examples |
---|---|
English | today , this month , February to March , 2018-01-01 to 2018-04-05 , January 15th - 18th |
Returned value
The returned value is an object with two dates in the start
and end
keys.
Objects can be turned into dates with toStartDate()
and toEndDate()
:
const start = value;const end = value;
Example
const dateInterval = ; builder value'interval' ;
Date Duration
Capture a duration.
Language | Examples |
---|---|
English | 2 days , 2m, 1d , 1 year and 2 days , 4y 2m , 1 week |
Returned value
The returned value is an object containg fields with the change, such as
years
, weeks
, months
and days
. The function toDate(currentTime)
can
be used to add the duration to a date.
// Add the duration to the current timeconst fromNow = value; // Add the duration to the specific date and timeconst fromSpecific = value;
Example
const dateDuration = ; builder value'dateDuration' ;
Time Duration
Capture a duration of hours, minutes, seconds and miliseconds.
Language | Examples |
---|---|
English | 2 hours , 1s , 2h, 45m , 4 minutes and 10 seconds |
Returned value
The returned value is an object containg fields with the change, such as
hours
, minutes
, seconds
and milliseconds
. The function
toDate(currentTime)
can be used to add the duration to a date.
// Add the duration to the current timeconst fromNow = value; // Add the duration to the specific date and timeconst fromSpecific = value;
Example
const timeDuration = ; builder value'timeDuration' ;
Date & Time Duration
Capture a duration of both days, hours, minutes, seconds and miliseconds.
Language | Examples |
---|---|
English | 2 hours , 2 d 20 m , 4 weeks and 10 minutes |
Returned value
The returned value is an object containg fields with the change, such as
years
, weeks
, months
and days
, hours
, minutes
, seconds
and
milliseconds
. The function toDate(currentTime)
can be used to add the
duration to a date.
// Add the duration to the current timeconst fromNow = value; // Add the duration to the specific date and timeconst fromSpecific = value;
Example
const dateTimeDuration = ; builder value'dateTimeDuration' ;
Enumeration
Capture one of the specified values. Used to specify one or more values that should match.
const enumeration = ; builder value'type' ;
Text
Text can be captured with the type any
. You can use any
for things such as
search queries, todo items and calendar events. Values of type any
will
always try to capture as much as they can and will not validate the result.
const any = ; builder value'text' ;