parse-english
Version:
English natural language parser
226 lines (160 loc) • 6.84 kB
Markdown
# parse-english
[![Build][build-badge]][build]
[![Coverage][coverage-badge]][coverage]
[![Downloads][downloads-badge]][downloads]
[![Size][size-badge]][size]
Natural language parser, for the English language, that produces [nlcst][].
## Contents
* [What is this?](#what-is-this)
* [When should I use this?](#when-should-i-use-this)
* [Install](#install)
* [Use](#use)
* [API](#api)
* [`ParseEnglish()`](#parseenglish)
* [Algorithm](#algorithm)
* [Types](#types)
* [Compatibility](#compatibility)
* [Security](#security)
* [Related](#related)
* [Contribute](#contribute)
* [License](#license)
## What is this?
This package exposes a parser that takes English natural language and produces
a syntax tree.
## When should I use this?
If you want to handle English natural language as syntax trees manually, use
this.
Alternatively, you can use the retext plugin [`retext-english`][retext-english],
which wraps this project to also parse natural language at a higher-level
(easier) abstraction.
For Dutch or most Latin-script languages, you can instead use
[`parse-dutch`][parse-dutch] or [`parse-latin`][parse-latin].
## Install
This package is [ESM only][esm].
In Node.js (version 16+), install with [npm][]:
```sh
npm install parse-english
```
In Deno with [`esm.sh`][esmsh]:
```js
import {ParseEnglish} from 'https://esm.sh/parse-english@7'
```
In browsers with [`esm.sh`][esmsh]:
```html
<script type="module">
import {ParseEnglish} from 'https://esm.sh/parse-english@7?bundle'
</script>
```
## Use
```js
import {ParseEnglish} from 'parse-english'
import {inspect} from 'unist-util-inspect'
const tree = new ParseEnglish().parse(
'Mr. Henry Brown: A hapless but friendly City of London worker.'
)
console.log(inspect(tree))
```
Yields:
```txt
RootNode[1] (1:1-1:63, 0-62)
└─0 ParagraphNode[1] (1:1-1:63, 0-62)
└─0 SentenceNode[23] (1:1-1:63, 0-62)
├─0 WordNode[2] (1:1-1:4, 0-3)
│ ├─0 TextNode "Mr" (1:1-1:3, 0-2)
│ └─1 PunctuationNode "." (1:3-1:4, 2-3)
├─1 WhiteSpaceNode " " (1:4-1:5, 3-4)
├─2 WordNode[1] (1:5-1:10, 4-9)
│ └─0 TextNode "Henry" (1:5-1:10, 4-9)
├─3 WhiteSpaceNode " " (1:10-1:11, 9-10)
├─4 WordNode[1] (1:11-1:16, 10-15)
│ └─0 TextNode "Brown" (1:11-1:16, 10-15)
├─5 PunctuationNode ":" (1:16-1:17, 15-16)
├─6 WhiteSpaceNode " " (1:17-1:18, 16-17)
├─7 WordNode[1] (1:18-1:19, 17-18)
│ └─0 TextNode "A" (1:18-1:19, 17-18)
├─8 WhiteSpaceNode " " (1:19-1:20, 18-19)
├─9 WordNode[1] (1:20-1:27, 19-26)
│ └─0 TextNode "hapless" (1:20-1:27, 19-26)
├─10 WhiteSpaceNode " " (1:27-1:28, 26-27)
├─11 WordNode[1] (1:28-1:31, 27-30)
│ └─0 TextNode "but" (1:28-1:31, 27-30)
├─12 WhiteSpaceNode " " (1:31-1:32, 30-31)
├─13 WordNode[1] (1:32-1:40, 31-39)
│ └─0 TextNode "friendly" (1:32-1:40, 31-39)
├─14 WhiteSpaceNode " " (1:40-1:41, 39-40)
├─15 WordNode[1] (1:41-1:45, 40-44)
│ └─0 TextNode "City" (1:41-1:45, 40-44)
├─16 WhiteSpaceNode " " (1:45-1:46, 44-45)
├─17 WordNode[1] (1:46-1:48, 45-47)
│ └─0 TextNode "of" (1:46-1:48, 45-47)
├─18 WhiteSpaceNode " " (1:48-1:49, 47-48)
├─19 WordNode[1] (1:49-1:55, 48-54)
│ └─0 TextNode "London" (1:49-1:55, 48-54)
├─20 WhiteSpaceNode " " (1:55-1:56, 54-55)
├─21 WordNode[1] (1:56-1:62, 55-61)
│ └─0 TextNode "worker" (1:56-1:62, 55-61)
└─22 PunctuationNode "." (1:62-1:63, 61-62)
```
## API
This package exports the identifier [`ParseEnglish`][api-parse-english].
There is no default export.
### `ParseEnglish()`
Create a new parser.
`ParseEnglish` extends `ParseLatin`.
See [`parse-latin`][parse-latin] for API docs.
## Algorithm
All of [`parse-latin`][parse-latin] is included, and the following support for
the English natural language:
* unit abbreviations (`tsp.`, `tbsp.`, `oz.`, `ft.`, and more)
* time references (`sec.`, `min.`, `tues.`, `thu.`, `feb.`, and more)
* business Abbreviations (`Inc.` and `Ltd.`)
* social titles (`Mr.`, `Mmes.`, `Sr.`, and more)
* rank and academic titles (`Dr.`, `Rep.`, `Gen.`, `Prof.`, `Pres.`, and more)
* geographical abbreviations (`Ave.`, `Blvd.`, `Ft.`, `Hwy.`, and more)
* American state abbreviations (`Ala.`, `Minn.`, `La.`, `Tex.`, and more)
* Canadian province abbreviations (`Alta.`, `Qué.`, `Yuk.`, and more)
* English county abbreviations (`Beds.`, `Leics.`, `Shrops.`, and more)
* common elision (omission of letters) (`’n’`, `’o`, `’em`, `’twas`, `’80s`,
and more)
## Types
This package is fully typed with [TypeScript][].
It exports no additional types.
## Compatibility
Projects maintained by me are compatible with maintained versions of Node.js.
When I cut a new major release, I drop support for unmaintained versions of
Node.
This means I try to keep the current release line, `parse-english@^7`,
compatible with Node.js 16.
## Security
This package is safe.
## Related
* [`parse-latin`](https://github.com/wooorm/parse-latin)
— Latin-script natural language parser
* [`parse-dutch`](https://github.com/wooorm/parse-dutch)
— Dutch natural language parser
## Contribute
Yes please!
See [How to Contribute to Open Source][contribute].
## License
[MIT][license] © [Titus Wormer][author]
<!-- Definitions -->
[build-badge]: https://github.com/wooorm/parse-english/workflows/main/badge.svg
[build]: https://github.com/wooorm/parse-english/actions
[coverage-badge]: https://img.shields.io/codecov/c/github/wooorm/parse-english.svg
[coverage]: https://codecov.io/github/wooorm/parse-english
[downloads-badge]: https://img.shields.io/npm/dm/parse-english.svg
[downloads]: https://www.npmjs.com/package/parse-english
[size-badge]: https://img.shields.io/badge/dynamic/json?label=minzipped%20size&query=$.size.compressedSize&url=https://deno.bundlejs.com/?q=parse-english
[size]: https://bundlejs.com/?q=parse-english
[npm]: https://docs.npmjs.com/cli/install
[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c
[esmsh]: https://esm.sh
[typescript]: https://www.typescriptlang.org
[contribute]: https://opensource.guide/how-to-contribute/
[license]: license
[author]: https://wooorm.com
[retext-english]: https://github.com/retextjs/retext/tree/main/packages/retext-english
[nlcst]: https://github.com/syntax-tree/nlcst
[parse-latin]: https://github.com/wooorm/parse-latin
[parse-dutch]: https://github.com/wooorm/parse-dutch
[api-parse-english]: #parseenglish