Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix image link, add link to license & linting (fix-cla) #675

Closed
wants to merge 1 commit into from
Closed
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 34 additions & 13 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,40 +1,50 @@
![Duckling Logo](https://github.com/facebook/duckling/raw/master/logo.png)
![Duckling Logo](https://github.com/facebook/duckling/raw/main/logo.png)

# Duckling [![Build Status](https://travis-ci.org/facebook/duckling.svg?branch=master)](https://travis-ci.org/facebook/duckling)

Duckling is a Haskell library that parses text into structured data.

```
```bash
"the first Tuesday of October"
=> {"value":"2017-10-03T00:00:00.000-07:00","grain":"day"}
```

## Requirements

A Haskell environment is required. We recommend using
[stack](https://haskell-lang.org/get-started).

On Linux and MacOS you'll need to install PCRE development headers.
On Linux, use your package manager to install them.
On MacOS, the easiest way to install them is with [Homebrew](https://brew.sh/):
```

```bash
brew install pcre
```

If that doesn't help, try running `brew doctor` and fix
the issues it finds.

## Quickstart

To compile and run the binary:

```bash
stack build
stack exec duckling-example-exe
```
$ stack build
$ stack exec duckling-example-exe
```

The first time you run it, it will download all required packages.

This runs a basic HTTP server. Example request:

```bash
curl -XPOST http://0.0.0.0:8000/parse --data 'locale=en_GB&text=tomorrow at eight'
```
$ curl -XPOST http://0.0.0.0:8000/parse --data 'locale=en_GB&text=tomorrow at eight'
```

In the example application, all dimensions are enabled by default. Provide the parameter `dims` to specify which ones you want. Examples:
```

```bash
Identify credit card numbers only:
$ curl -XPOST http://0.0.0.0:8000/parse --data 'locale=en_US&text="4111-1111-1111-1111"&dims="["credit-card-number"]"'
If you want multiple dimensions, comma-separate them in the array:
Expand All @@ -46,6 +56,7 @@ project.
If your backend doesn't run Haskell or if you don't want to spin your own Duckling server, you can directly use [wit.ai](https://wit.ai)'s built-in entities.

## Supported dimensions

Duckling supports many languages, but most don't support all dimensions yet
(**we need your help!**).
Please look into [this directory](https://github.com/facebook/duckling/blob/master/Duckling/Dimensions) for language-specific support.
Expand All @@ -69,27 +80,35 @@ Please look into [this directory](https://github.com/facebook/duckling/blob/mast
[Custom dimensions](https://github.com/facebook/duckling/blob/master/exe/CustomDimensionExample.hs) are also supported.

## Extending Duckling

To regenerate the classifiers and run the test suite:
```
$ stack build :duckling-regen-exe && stack exec duckling-regen-exe && stack test

```bash
stack build :duckling-regen-exe && stack exec duckling-regen-exe && stack test
```

It's important to regenerate the classifiers after updating the code and before
running the test suite.

To extend Duckling's support for a dimension in a given language, typically 4
files need to be updated:

* `Duckling/<Dimension>/<Lang>/Rules.hs`

* `Duckling/<Dimension>/<Lang>/Corpus.hs`

* `Duckling/Dimensions/<Lang>.hs` (if not already present in `Duckling/Dimensions/Common.hs`)

* `Duckling/Rules/<Lang>.hs`

To add a new language:

* Make sure that the language code used follows the [ISO-639-1 standard](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes).
* The first dimension to implement is `Numeral`.
* Follow [this example](https://github.com/facebook/duckling/commit/24d3f199768be970149412c95b1c1bf5d76f8240).

To add a new locale:

* There should be a need for diverging rules between the locale and the language.
* Make sure that the locale code is a valid [ISO3166 alpha2 country code](https://www.iso.org/obp/ui/#search/code/).
* Follow [this example](https://github.com/facebook/duckling/commit/1ab5f447d2635fe6d48887a501d333a52adff5b9).
Expand All @@ -105,7 +124,8 @@ shouldn't) parse. The reference time for the corpus is Tuesday Feb 12, 2013 at
4:30am.

`Duckling.Debug` provides a few debugging tools:
```

```bash
$ stack repl --no-load
> :l Duckling.Debug
> debug (makeLocale EN $ Just US) "in two minutes" [Seal Time]
Expand All @@ -120,4 +140,5 @@ in|within|after <duration> (in two minutes)
```

## License
Duckling is BSD-licensed.

Duckling is [BSD-licensed](LICENSE).