Notoriously Problematic Merge
    Have ideas to improve npm?Join in the discussion! »


    2.3.0 • Public • Published


    Build Status Join Gitter Chat js-standard-style npm

    Elliptical is a Javascript library for building interactive natural language text interfaces.

    It is framework-independent and runs on both the client and the server. It works with any written language that can be represented with Unicode. It is functional, compositional, easily extensible, and it's got great docs.

    There are addons to allow for internationalization, linguistic extension, sideways data loading, and more.

    There are pre-built phrases for parsing English dates and times, numbers, urls, phone numbers, email addresses, arbitrary strings, and more. Of course, you can develop your own phrases.

    To see an example of Elliptical in action, check out the Lacona App.

    Full Documentation


    npm install elliptical

    What is an Interactive Natural Language Interface?

    Interactive Natural Language Interfaces allow users to enter data in a natural, unstructured way, but still have interactive nicities like intelligent suggestions, sorting, autocomplete, and syntax highlighting.

    Well-designed interfaces can give users an unprecedented level of expressiveness and efficiency, while still being easy to learn and use.

    Elliptical helps you build interfaces like this. You create natural language grammars by combining linguistic building blocks (called Phrases). Elliptical uses that grammar to process strings, and returns objects that describe the input, offer suggestions, and allow for intelligent sorting.

    Elliptical also uses the user input to build plain Javascript objects, so you can easily do things based upon the user's input.

    Lacona is extensible, allowing phrases to have smart internationalization functionality, make use of external data sources, and more. This allows for powerful, dynamic grammars that are still easy to understand.

    Elliptical is not:

    • a library to extract meaningful information from unstructured text, like nltk. Elliptical does not know anything about English (or any other language's) grammar. Rather, it parses possible strings according to a predefined schema.
    • a voice command system, like Siri. Elliptical only operates on text (though it could conceivably be used as a layer in such an application).
    • a machine learning system. Elliptical parses strings according to a preset algorithm
    • a static string parser, like regular expressions. Elliptical schemata are dynamic - can execute arbitrary code, pull data from external sources, and interact with one another. Abstractions are provided to make these complex tasks as reasonable as possible.
    • designed for automated parsing. Elliptical is designed to build interactive textural interfaces for relatively short inputs.


    You can play with this example yourself at elliptical-example.

    /** @jsx createElement */
    import {createElement, compile} from 'elliptical'
    // Some data to work with
    const countryData = [
      {text: "China (People's Republic of)", value: 'CN'},
      {text: 'Ireland', value: 'IE'},
      {text: 'Macedonia (the former Yugoslav Republic of)', value: 'MK'},
      {text: 'United Kingdom of Great Britain and Northern Ireland', value: 'IE'},
      {text: 'United States', value: 'US'}
    // Define a Phrase
    const Country = {
      describe () {
        return (
          <label text='Country'>
            <list items={countryData} strategy='fuzzy' />
    // Build our grammar out of Elements
    const grammar = (
        <literal text='flights ' />
        <choice id='direction'>
          <literal text='from ' value='from' />
          <literal text='to ' value='to' />
        <Country id='country' />
    // Obtain a parse function from our grammar
    const parse = compile(grammar)
    // Parse based upon a given query
    const outputs = parse('flights to irela')
      [{ // direct match
        words: [
          {text: 'flights', input: true},
          {text: ' to ', input: true},
          {text: 'Irela', input: true, argument: 'Country'},
          {text: 'nd', input: false, argument: 'Country'}
        results: {
          direction: 'to',
          country: 'IE'
        score: 1
      }, { // mid-string match
        words: [
          {text: 'flights', input: true},
          {text: ' to ', input: true},
          {text: 'United Kingdom of Great Britain and Northern ', input: false, argument: 'Country'},
          {text: 'Ireland', input: true, argument: 'Country'}
        results: {
          direction: 'to',
          country: 'GB'
        score: 0.5673076923076923
      }, { // fuzzy match
        words: [
          {text: 'flights', input: true},
          {text: ' to ', input: true},
          {text: 'Macedon', input: false, argument: 'Country'},
          {text: 'i', input: true, argument: 'Country'},
          {text: 'a (the fo', input: false, argument: 'Country'},
          {text: 'r', input: true, argument: 'Country'},
          {text: 'm', input: false, argument: 'Country'},
          {text: 'e', input: true, argument: 'Country'},
          {text: 'r Yugos', input: false, argument: 'Country'},
          {text: 'la', input: true, argument: 'Country'},
          {text: 'v Republic of)', input: false, argument: 'Country'}
        results: {
          direction: 'to',
          country: 'MK'
        score: 0.024999999999999998


    npm i elliptical

    DownloadsWeekly Downloads






    Last publish


    • avatar