Compromise

https://github.com/spencermountain/compromise
Admin
compromise is a modest natural language processing library that turns text into data by making...
Tokens:34,220
Snippets:452
Trust Score:10
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install compromise-dates

Source: https://github.com/spencermountain/compromise/blob/master/plugins/dates/README.md

Command to install the plugin via npm.

```bash
npm install compromise-dates
```

--------------------------------

### Install project dependencies

Source: https://github.com/spencermountain/compromise/wiki/Contributing

Run this command to download the necessary packages for the project. Ensure you have npm installed.

```bash
npm install
```

--------------------------------

### Name Matching Example

Source: https://github.com/spencermountain/compromise/blob/master/tests/bugs.md

An example of matching first names within a text.

```javascript
nlp('you are John, Lisa, Fred').match('#FirstName{1,2}').debug()
```

--------------------------------

### Install Wikipedia Plugin

Source: https://github.com/spencermountain/compromise/blob/master/README.md

Command to install the compromise-wikipedia plugin.

```bash
npm install compromise-wikipedia
```

--------------------------------

### Install Stats Plugin

Source: https://github.com/spencermountain/compromise/blob/master/README.md

Command to install the compromise-stats plugin.

```bash
npm install compromise-stats
```

--------------------------------

### Run the project

Source: https://github.com/spencermountain/compromise/wiki/Contributing

Use these commands to start the project or run it in watch mode. These commands are typically defined in the package.json file.

```bash
npm run start
```

```bash
npm run watch
```

--------------------------------

### Paragraphs Plugin Initialization and Basic Usage

Source: https://github.com/spencermountain/compromise/blob/master/plugins/paragraphs/README.md

Demonstrates how to install the plugin, initialize it with text, and access basic properties like length and JSON output.

```APIDOC
## Initialization and Basic Usage

### Description
Install the plugin and use it to process text into paragraphs.

### Installation
```bash
npm install compromise-paragraphs
```

### Usage
```js
let str = `What's with these homies dissin' my girl? Why do they gotta front? 

What did we ever do to these guys that made them so violent?

Woo-hoo, but you know I'm yours.
Woo-hoo, and I know you're mine.
Woo-hoo, and that's for all time
`;

let doc = nlp(str).paragraphs();

// Get the number of paragraphs
doc.length;
// 3

// Get JSON representation of paragraphs
doc.json(options);
/*
[ 
  {text:'What's with these ...', sentences:[{},{}]}
  {text:'What did we ever ...', sentences:[{}]}
]
*/
```
```

--------------------------------

### Install Syllables Plugin

Source: https://github.com/spencermountain/compromise/blob/master/README.md

Command to install the compromise-syllables plugin.

```bash
npm install compromise-syllables
```

--------------------------------

### Specification worked examples

Source: https://github.com/spencermountain/compromise/blob/master/docs/spec-format.md

Examples showing the mapping of sentences to their corresponding tag-sets.

```text
The dog is nice. {Det,Noun,Vb,Adj}
The dog don't bark. {Det,Noun,Vb,Negative,Vb}
The dog's tail wagged. {Det,Noun,Noun,Vb}
We'll see well-known cases. {Noun,Vb,Vb,Adv,Adj,Noun}
It's a 3.5 inch disk. {Noun,Vb,Det,Val,Noun,Noun}
He cannot go. {Noun,Vb,Negative,Vb}
Visit https://nlp.com or email me@x.com today! {Noun,Url,Conj,Noun,Email,Date}
there are five hundred quick reasons. {There,Vb,Val,Val,Adj,Noun}
```

--------------------------------

### Date Parsing Example

Source: https://github.com/spencermountain/compromise/blob/master/tests/bugs.md

Shows how to parse date-related phrases using the compromise library.

```javascript
console.log(nlp('next week').dates().json())
```

--------------------------------

### Verb Tense Transformation Examples

Source: https://github.com/spencermountain/compromise/wiki/v7-Upgrade,-welcome

Illustrates how to use the `verbs().toPastTense()` method on different inputs, including single words, phrases, and sentences, and how to collect results as an array.

```javascript
r= nlp('singing').verbs().toPastTense()
// sang

r= nlp('would have been singing').verbs().toPastTense()
// would have sang

r= nlp('john is singing. Sara was singing.').verbs().toPastTense().out('array')
//[was, was]
```

--------------------------------

### Install Compromise via npm

Source: https://github.com/spencermountain/compromise/wiki/v7-Upgrade,-welcome

The command to install the compromise library using npm.

```bash
npm install compromise
```

--------------------------------

### Tagger Examples

Source: https://github.com/spencermountain/compromise/blob/master/tests/bugs.md

A collection of examples demonstrating the compromise tagger's ability to process various phrases and sentences.

```javascript
let doc = nlp(`the latter a dire security threat`)
```

```javascript
let doc = nlp(`My first thought was to push it away, he said.`)
```

```javascript
let doc = nlp(`and too many of the rich made their money`)
```

```javascript
let doc = nlp(`Puerto Rico only (I need historical inflation data)`)
```

```javascript
let doc = nlp(`blows it up`)
```

```javascript
let doc = nlp(`20 people, including many children`)
```

```javascript
let doc = nlp(` with heads and arms rolling around`)
```

--------------------------------

### Outputting Processed Text in Various Formats

Source: https://github.com/spencermountain/compromise/wiki/v7-Upgrade,-welcome

Provides examples of different output formats available in compromise, including 'normal', 'text', 'html', and 'terms'.

```javascript
nlp('John is cool').out('normal');
nlp('John is cool').out('text');
nlp('John is cool').out('html');
//show part-of-speech tags, etc
nlp('John is cool').out('terms');
//and soon, adhoc-scripting
nlp('John is cool').out(myFunction);
```

--------------------------------

### Extend Compromise with TypeScript

Source: https://github.com/spencermountain/compromise/blob/master/README.md

Example of importing and extending the compromise library with plugins in a TypeScript environment.

```ts
import nlp from 'compromise'
import stats from 'compromise-stats'

const nlpEx = nlp.extend(stats)

nlpEx('This is type safe!').ngrams({ min: 1 })
```

--------------------------------

### Get Compromise Version

Source: https://github.com/spencermountain/compromise/wiki/Home

Use this snippet to check the installed version of the compromise library. Ensure you are running the latest version before reporting issues.

```javascript
var nlp=require('compromise')
console.log(nlp.version)
```

--------------------------------

### Match with anchors

Source: https://github.com/spencermountain/compromise/blob/master/docs/match-syntax.md

Uses caret and dollar sign to anchor matches to the start or end of a sentence.

```javascript
nlp('the cat sat').match('^the').text()   // 'the'
nlp('the cat sat').match('sat$').text()   // 'sat'
```

--------------------------------

### Tokenize Words by Syllables with Compromise Speech

Source: https://github.com/spencermountain/compromise/blob/master/plugins/speech/README.md

Use the `.syllables()` method after extending compromise with the speech plugin to get an array of syllable arrays for each token. This method provides an approximate tokenization based on pronunciation rules.

```javascript
import plg from 'compromise-speech'
nlp.extend(plg)

let doc = nlp('seventh millenium. white collar')
doc.syllables()
[ [ 'se', 'venth', 'mil', 'le', 'nium' ], [ 'white', 'col', 'lar' ] ]
```

--------------------------------

### Initialize and Use KeyPress Plugin

Source: https://github.com/spencermountain/compromise/blob/master/plugins/speed/demo/index.html

Load the keyPress plugin and set up an event listener to parse input on each keystroke. This avoids re-parsing the entire text, improving performance.

```javascript
nlp.plugin(compromiseSpeed.keyPress)
const opts = { verbose: true }
const parse = function (text) {
  let doc = nlp.keyPress(text, null, opts)
  document.querySelector('#res').innerHTML = `${doc.length} sentences - only 1 parsed`
}
let el = document.querySelector('#input')
parse(el.value)
el.onkeypress = (e) => parse(e.target.value)
```

--------------------------------

### Basic document transformation

Source: https://github.com/spencermountain/compromise/blob/master/docs/SKILL.md

Demonstrates initializing a document, applying a transformation, and retrieving the full text.

```javascript
import nlp from 'compromise'

let doc = nlp('she sells seashells by the seashore.')
doc.verbs().toPastTense()        // transform
doc.text()                       // 'she sold seashells by the seashore.'
```

--------------------------------

### Library Build Tiers

Source: https://github.com/spencermountain/compromise/blob/master/docs/concepts.md

Shows the different import options available based on required functionality and bundle size.

```javascript
import nlp from 'compromise'          // full (recommended)
import nlp from 'compromise/two'      // tags, no selections
import nlp from 'compromise/tokenize' // tokens only
```

--------------------------------

### Basic Text Manipulation with Compromise v7

Source: https://github.com/spencermountain/compromise/wiki/v7-Upgrade,-welcome

Demonstrates the core workflow of initializing compromise, transforming a subset of text (nouns to uppercase), applying subset-specific methods (sentences to exclamation), and outputting the result.

```javascript
var r = nlp(`Finally, the api is stable.`)

r.nouns().toUpperCase()

r.sentences().toExclamation()

r.out('text')
//"Finally, the API is stable!"
```

--------------------------------

### Extending Compromise with Plugins

Source: https://github.com/spencermountain/compromise/blob/master/AGENTS.md

Shows how to add lexicon entries, extend the tagset, and add custom methods to the View prototype.

```javascript
nlp.plugin({
  words: { kermit: 'FirstName' },         // add lexicon entries
  tags:  { Muppet: { isA: 'Person' } },   // extend the tagset graph
  api:   (View) => { View.prototype.myMethod = function () { return this } },
})
```

--------------------------------

### Gerund Usage Examples

Source: https://github.com/spencermountain/compromise/blob/master/tests/bugs.md

Illustrates the different grammatical roles a gerund (verb ending in -ing used as a noun) can take in a sentence.

```text
Snowboarding is a winter sport.   [snowboarding = subject]
```

```text
I love snowboarding.    [snowboarding = object ]
```

```text
I am excited by snowboarding.   [snowboarding = object of a preposition]
```

```text
One popular sport is snowboarding.   [snowboarding = subject complement]
```

```text
Right now, the athlete is snowboarding.   [is snowboarding = present continuous]
```

```text
He was snowboarding yesterday afternoon.   [was snowboarding = past continuous]
```

```text
Tomorrow, my friends and I are going to be snowboarding.   [are going to be snowboarding = future
```

--------------------------------

### Match terms using compromise syntax

Source: https://github.com/spencermountain/compromise/blob/master/docs/match-syntax.md

Demonstrates basic usage of the .match() method with part-of-speech tags.

```javascript
nlp('the cat sat down').match('#Determiner #Noun').text()
// 'the cat'
```

--------------------------------

### View code differences

Source: https://github.com/spencermountain/compromise/wiki/Contributing

See a detailed comparison of your changes against the current version of the code. This helps in understanding the modifications made.

```bash
git diff
```

--------------------------------

### Tagger Performance on Specific Phrases

Source: https://github.com/spencermountain/compromise/blob/master/tests/bugs.md

These examples test the compromise tagger's accuracy on various challenging phrases, including compound words and idiomatic expressions.

```javascript
nlp('lowered according').debug()
```

```javascript
nlp('it bristles outwards, brushlike.').debug()
```

```javascript
nlp('red-shouldered').debug()
```

```javascript
nlp('age of it').debug()
```

```javascript
nlp('so well that').debug()
```

```javascript
nlp('is off-white').debug()
```

```javascript
nlp('polyunsaturated').debug()
```

```javascript
nlp('favoured treat').debug()
```

--------------------------------

### Basic Document Parsing and Transformation

Source: https://github.com/spencermountain/compromise/blob/master/AGENTS.md

Demonstrates the fundamental workflow of parsing text into a View, performing transformations, and retrieving the output.

```javascript
import nlp from 'compromise'

let doc = nlp('she sells seashells by the seashore.')  // parse → a View of the whole document
doc.verbs().toPastTense()                               // select verbs, transform them (mutates doc)
doc.text()                                              // 'she sold seashells by the seashore.'
```

--------------------------------

### Initialize and Use compromise-stats Plugin

Source: https://github.com/spencermountain/compromise/blob/master/plugins/stats/demo/index.html

Load the compromise-stats plugin and use it to generate n-grams from text. Ensure the plugin is loaded before processing documents.

```javascript
nlp.plugin(compromiseStats)
```

```javascript
let txt = document.querySelector('kbd').innerText
let doc = nlp(txt)
let json = doc.ngrams()
document.querySelector('#res').innerHTML = JSON.stringify(json, null, 2)
```

--------------------------------

### Date Context Configuration

Source: https://github.com/spencermountain/compromise/blob/master/plugins/dates/README.md

Configuring the context for date parsing using an optional configuration object.

```APIDOC
## .dates(context)

### Description
Accepts an optional context object to refine date parsing logic.

### Parameters
- **context** (Object) - Optional - Configuration object containing:
  - **timezone** (string): The timezone (default: local).
  - **today** (string): The reference date (ISO format).
  - **punt** (Object): Implied duration for relative dates.
  - **dayStart** (string): Start time of the day.
  - **dayEnd** (string): End time of the day.
  - **dmy** (boolean): Whether to assume British-format dates.
```

--------------------------------

### Match Syntax Reference

Source: https://github.com/spencermountain/compromise/blob/master/docs/match-syntax.md

A comprehensive reference table for the compromise match-syntax mini-language, detailing tokens, operators, and their matching behavior.

```APIDOC
## Match Syntax Reference

| Token | Means | Example pattern | Matches |
|---|---|---|---|
| `word` | exact word (case-insensitive, lemma-aware) | `sat` | "sat" |
| `#Tag` | a part-of-speech tag | `#Person` | "John" |
| `.` | exactly one of any term | `the . sat` | "the cat sat" |
| `*` | zero or more of any term (greedy) | `the * sat` | "the cat quickly sat" |
| `(a|b)` | one of these options (OR) | `(cat|dog)` | "cat" or "dog" |
| `(a && #Tag)` | term matches both conditions (AND) | `(cool && #Adjective)` | "cool" (only if tagged Adjective) |
| `word?` | optional term (zero or one) | `the big? cat` | "the cat" and "the big cat" |
| `+` | one or more of the previous (greedy) | `#Adjective+` | "big red" |
| `term{m,n}` | between m and n of the previous | `.{2,3}` | 2–3 of any term |
| `term{n}` | exactly n | `.{2}` | exactly 2 terms |
| `!` | negate — term is anything except this | `the !#Verb` | "the cat" (not "the runs") |
| `[ ]` | capture group | `[#Person+]` | captures the people |
| `[<name> ]` | named capture group | `[<who>#Person+]` | group named "who" |
| `^` | must be first term in the sentence | `^the` | leading "the" |
| `$` | must be last term in the sentence | `sat$` | trailing "sat" |
| `~word~` | fuzzy match (typos / near-spellings) | `~organization~` | "organisation" |
| `{root}` | match by root/lemma form | `{walk}` | "walk", "walks", "walked", "walking" |
| `{root/pos}` | root form, restricted to a part-of-speech | `{walk/verb}` | "walks" as a verb (not the noun) |
| `<Chunk>` | a noun-phrase/verb-phrase chunk | `<Noun>` | "the cat" |
| `@method` | a term-method predicate | `@isTitleCase` | title-cased terms |
```

--------------------------------

### Suggesting tags for words during initialization

Source: https://github.com/spencermountain/compromise/blob/master/README.md

Pass a lexicon object as the second argument to nlp() to suggest tags for specific words.

```javascript
let myWords = {
  kermit: 'FirstName',
  fozzie: 'FirstName',
}
let doc = nlp(muppetText, myWords)
```

--------------------------------

### nlp.buildNet(matches)

Source: https://github.com/spencermountain/compromise/blob/master/docs/api.md

Compiles a set of match objects to a more optimized form.

```APIDOC
## nlp.buildNet(matches)

### Description
Compile a set of match objects to a more optimized form.

### Parameters
- **matches** (array) - Required - List of match objects.
```

--------------------------------

### Part-of-speech tagging with compromise/two

Source: https://github.com/spencermountain/compromise/blob/master/README.md

Demonstrates basic part-of-speech tagging and matching using the compromise/two package.

```js
import nlp from 'compromise/two'

let doc = nlp("Wayne's World, party time")
let str = doc.match('#Possessive #Noun').text()
// "Wayne's World"
```

--------------------------------

### Document mutation and cloning

Source: https://github.com/spencermountain/compromise/blob/master/docs/SKILL.md

Shows that transformations mutate the document in place and how to use .clone() to preserve the original state.

```javascript
let doc = nlp('I walk to work')
doc.verbs().toPastTense()
doc.text()                                            // ✅ 'I walked to work'  (read from doc)

nlp('I walk to work').verbs().toPastTense().text()    // ❌ 'walked work'  (just the selection)
```

```javascript
let past = doc.clone().verbs().toPastTense().text()
```

--------------------------------

### Initialize and Use Wikipedia Plugin

Source: https://github.com/spencermountain/compromise/blob/master/plugins/wikipedia/README.md

Extend compromise with the wikipedia plugin and then use the .wikipedia() method to find mentions of Wikipedia articles in a document. The .json() method can be used to view the results.

```javascript
import plg from 'compromise-wikipedia'
nlp.extend(plg)

let doc = nlp('You could always go to McGill, the Harvard of Canada!')
let m = doc.wikipedia()
m.json()
```

--------------------------------

### Load and Use Compromise Plugin

Source: https://github.com/spencermountain/compromise/blob/master/demos/plugin.html

Load the compromise library and a plugin, then use the plugin's functionality to compute syllables for a given text.

```javascript
// compromise is loaded as 'window.nlp'
// plugin is loaded as 'window.compromiseSpeech'
nlp.plugin(compromiseSpeech)
var doc = nlp('edmonton oilers')
doc.compute('syllables')
window.onload = function () {
  let arr = doc.syllables()
  let el = document.getElementById('result')
  el.innerHTML = JSON.stringify(arr, null, 2)
}
```

--------------------------------

### Basic Text Transformation

Source: https://github.com/spencermountain/compromise/blob/master/docs/concepts.md

Demonstrates tokenizing text and applying a verb tense transformation.

```javascript
import nlp from 'compromise'

let doc = nlp('she sells seashells by the seashore.')
doc.verbs().toPastTense()
doc.text()
// 'she sold seashells by the seashore.'
```

--------------------------------

### Create and Listen to Web Worker

Source: https://github.com/spencermountain/compromise/blob/master/demos/web-worker/index.html

Initializes a new Web Worker and sets up an event listener to receive messages back from it. Use this to handle background tasks without blocking the main thread.

```javascript
var worker = new Worker('./\_worker.js')
worker.addEventListener('message', function (msg) {
  console.log('worker response:', msg)
  let rows = msg.data.map(o => `<div>${o.text}</div>`).join('')
  document.getElementById('result').innerHTML = rows
}, false)
```

--------------------------------

### Concise Compromise v7 Workflow

Source: https://github.com/spencermountain/compromise/wiki/v7-Upgrade,-welcome

A simplified representation of the typical compromise v7 usage pattern: initializing with text, selecting a subset, applying a method, and outputting.

```javascript
nlp(myText).mySubset().subsetFn().out(myOutput)
```

--------------------------------

### Handling Mutability

Source: https://github.com/spencermountain/compromise/blob/master/docs/concepts.md

Illustrates how transform methods mutate the underlying document and how to use .clone() to preserve the original.

```javascript
let doc = nlp('I walk to work')
doc.verbs().toPastTense()       // mutates doc, even though we didn't reassign
doc.text()                      // 'I walked to work'  ← doc changed
```

```javascript
let past = doc.clone().verbs().toPastTense().text()   // doc is untouched
```

--------------------------------

### Chaining Methods

Source: https://github.com/spencermountain/compromise/blob/master/docs/concepts.md

Shows how to chain methods on a View to extract specific text.

```javascript
nlp(text).match('#Person+').first().text()
```

--------------------------------

### Match chunks

Source: https://github.com/spencermountain/compromise/blob/master/docs/match-syntax.md

Matches entire noun or verb phrases.

```javascript
nlp('the cat sat down').match('<Noun>').text()   // 'the cat'
```

--------------------------------

### Load and Use Compromise-Speech Plugin

Source: https://github.com/spencermountain/compromise/blob/master/plugins/speech/demo/index.html

Load the compromise-speech plugin and use it to count syllables in text. Ensure compromise-speech is loaded before use.

```javascript
nlp.plugin(compromiseSpeech) // window.compromiseSpeech
```

```javascript
let txt = document.querySelector('kbd').innerText
```

```javascript
let doc = nlp(txt)
```

```javascript
let json = doc.syllables()
```

```javascript
document.querySelector('#res').innerHTML = JSON.stringify(json, null, 2)
```

--------------------------------

### nlp.buildTrie(words)

Source: https://github.com/spencermountain/compromise/blob/master/docs/api.md

Turns a list of words into a searchable graph.

```APIDOC
## nlp.buildTrie(words)

### Description
Turn a list of words into a searchable graph.

### Parameters
- **words** (array) - Required - List of words.
```

--------------------------------

### Verb Conjugation and Tense Conversion

Source: https://github.com/spencermountain/compromise/blob/master/tests/bugs.md

Demonstrates handling of verb phrases, including different tenses (past participle, past tense, future tense) and conjugation.

```javascript
let doc = nlp('i am being driven')
let doc = nlp('i should be driven')
let doc = nlp('i should have been driven')
doc.verbs().toParticiple()
doc.verbs().toPastTense()
doc.debug()
console.log(doc.verbs(0).conjugate())
doc.sentences().toFutureTense().debug()
```

```javascript
let doc = nlp('i could study').debug()
doc.verbs().toParticiple()
doc.sentences().toPastTense()
console.log(doc.text())
```

```javascript
let doc = nlp('i did really walk')
doc.sentences().toPresentTense()
console.log(doc.text())
```

--------------------------------

### Lexicon and Plugin Management

Source: https://github.com/spencermountain/compromise/blob/master/docs/llms-full.txt

Methods for extending the library's vocabulary and functionality.

```APIDOC
## nlp.addWords(lexicon)

### Description
Globally adds new words and their associated tags to the library's lexicon.

## nlp.plugin(pluginObject)

### Description
Extends the library by adding custom words, tags, or chainable methods to the View prototype.
```

--------------------------------

### Match using logical options

Source: https://github.com/spencermountain/compromise/blob/master/docs/match-syntax.md

Uses pipe for OR logic and double ampersand for AND logic to combine conditions.

```javascript
nlp('i like red and blue').match('(red|blue)').out('array')   // ['red','blue']
nlp('a cool cat').match('(cool && #Adjective)').text()        // 'cool'
nlp('a nice gift today').match('(#Noun && gift)').text()      // 'gift'
```

--------------------------------

### Match using wildcards

Source: https://github.com/spencermountain/compromise/blob/master/docs/match-syntax.md

Uses '.' for a single term and '*' for any number of terms.

```javascript
nlp('the cat sat').match('the . sat').text()            // 'the cat sat'
nlp('the cat quickly sat').match('the * sat').text()    // 'the cat quickly sat'
```

--------------------------------

### Parse dates from text

Source: https://github.com/spencermountain/compromise/blob/master/plugins/dates/README.md

Initialize the plugin with compromise and extract date objects from a string.

```javascript
import nlp from 'compromise'
import datePlugin from 'compromise-dates'
nlp.plugin(datePlugin)

let doc = nlp('the second monday of february')
doc.dates().get()[0]
/*
  { start: '2021-02-08T00:00:00.000Z', end: '2021-02-08T23:59:59.999Z'}
*/
```

--------------------------------

### View project status

Source: https://github.com/spencermountain/compromise/wiki/Contributing

Check the status of your changes in the repository. This command shows which files have been modified.

```bash
git status
```

--------------------------------

### Keystroke Caching with keyPress

Source: https://github.com/spencermountain/compromise/blob/master/plugins/speed/README.md

Optimize performance for real-time text analysis by caching parsed sentences with `keyPress`. This plugin avoids re-parsing unchanged sentences and cleans up temporary ones.

```javascript
import {keyPress} from 'compromise-speed'
nlp.extend(keyPress)

let doc = nlp.keyPress('parsed once. it was the blurst of')
doc = nlp.keyPress('parsed once. it was the blurst of times')
```

```html
<textarea>Chocolate microscopes? Double guitars?</textarea>
<script src="https://unpkg.com/compromise"></script>
<script src="https://unpkg.com/compromise-speed"></script>
<script defer>
  nlp.plugin(compromiseSpeed.keyPress)
  document.querySelector('textarea').onkeypress = (e) => {
    let doc = nlp.keyPress(e.target.value)
  }
</script>
```

--------------------------------

### SoundsLike

Source: https://github.com/spencermountain/compromise/blob/master/plugins/speech/README.md

Generates an expected pronunciation for a word as a normalized string using the Metaphone algorithm.

```APIDOC
## SoundsLike

Generate an expected pronounciation for the word, as a normalized string. We use the [metaphone implementation](https://en.wikipedia.org/wiki/Metaphone), which is a simple rule-based pronounciation system.

### Method
```js
import plg from 'compromise-speech'
nlp.extend(plg)

let doc = nlp('seventh millenium. white collar')
doc.soundsLike()
```

### Response
```json
// [ [ 'sefenth', 'milenium' ], [ 'wite', 'kolar' ] ]
```

### Alternative Usage with `.compute()`

Alternatively, if you'd like to combine syllable information with other properties, you can use `.compute('syllables')`

### Method
```js
let doc = nlp('edmonton oilers')
doc.compute('soundsLike')
```

### Response
```json
/*[{"terms":[{"normal":"edmonton","soundsLike":"etmonton"},{"normal":"oilers","soundsLike":"oilers"}]}]*/
```
```

--------------------------------

### Teach new words

Source: https://github.com/spencermountain/compromise/blob/master/docs/recipes.md

Extend the library's vocabulary using a lexicon object at parse time or globally via addWords.

```js
nlp('kermit waved', { kermit: 'FirstName' }).people().out('array')   // ['kermit']
```

```js
nlp.addWords({ frodo: 'FirstName', gandalf: 'FirstName' })
nlp('frodo met gandalf').people().out('array')   // ['frodo', 'gandalf']
```

--------------------------------

### Cache and State Management

Source: https://github.com/spencermountain/compromise/blob/master/docs/api.md

Methods for managing document state, performance caching, and linguistic transformations.

```APIDOC
## Cache and State Management

### Methods
- `.cache(options?)` - Freeze document state for speed.
- `.uncache(options?)` - Un-freeze document state.
- `.freeze()` - Prevent tags from being removed.
- `.unfreeze()` - Allow tags to be changed.
- `.lookup(trie, opts?)` - Quick find for string matches.
- `.autoFill()` - Assume type-ahead prefixes.
- `.contractions(n?)` - Return multi-word terms.
- `.contract()` - Contract words that can combine.
- `.confidence()` - Measure tag confidence.
- `.swap(fromLemma, toLemma, guardTag?)` - Smart-replace root forms.
- `.expand()` - Expand contractions.
```

--------------------------------

### Core Methods

Source: https://github.com/spencermountain/compromise/blob/master/docs/api.md

Methods available on every View to preserve original text properties.

```APIDOC
## Core Methods

- **.case** [getter] — preserve the case of the original, ignoring the case of the replacement
- **.possessives** [getter] — preserve whether the original was a possessive
- **.tags** [getter] — preserve all of the tags of the original, regardless of the tags of the replacement
```

--------------------------------

### Output Methods

Source: https://github.com/spencermountain/compromise/blob/master/docs/api.md

Methods for retrieving document content in various formats.

```APIDOC
## Output Methods

### Methods
- `.text(options?)` - Return the document as text.
- `.json(options?)` - Pull out metadata from the document.
- `.debug()` - Pretty-print the current document and tags.
- `.out(format?)` - Return named output formats.
- `.html(toHighlight)` - Produce an HTML string.
- `.wrap(matches)` - Produce an HTML string.
```

--------------------------------

### Extend Compromise with Plugins

Source: https://github.com/spencermountain/compromise/wiki/v12-Release-Notes

Use `nlp.extend()` to integrate external plugins like 'compromise-plugin-foo' to add new functionality. This is the recommended way to customize compromise behavior.

```javascript
const nlp = require('compromise')
lp.extend(require('compromise-plugin-foo'))
```

--------------------------------

### Document Mutation and Selection

Source: https://github.com/spencermountain/compromise/blob/master/AGENTS.md

Illustrates that transformations mutate the document in place and that methods return a selection, not the full document.

```javascript
let doc = nlp('I walk to work')
doc.verbs().toPastTense()
doc.text()                       // ✅ 'I walked to work'
// ❌ nlp('I walk to work').verbs().toPastTense().text()  →  'walked work' (selection only)
```

--------------------------------

### Extend compromise with a custom plugin

Source: https://github.com/spencermountain/compromise/blob/master/docs/recipes.md

Use nlp.plugin to define custom lexicon entries, tags, and chainable API methods. Ensure the plugin is registered before executing match operations.

```javascript
nlp.plugin({
  // add words to the lexicon
  words: { kermit: 'FirstName' },
  // add new tags to the tagset graph
  tags: { Muppet: { isA: 'Person' } },
  // add new chainable methods
  api: (View) => {
    View.prototype.exclaim = function () {
      return this.post('!')   // add '!' after each match
    }
  },
})

let doc = nlp('hello there')
doc.match('there').exclaim()
doc.text()                       // 'hello there!'
```

--------------------------------

### Configure date parsing context

Source: https://github.com/spencermountain/compromise/blob/master/plugins/dates/README.md

Use a context object to define timezone, reference date, and parsing defaults for date extraction.

```javascript
const context = {
  timezone: 'Canada/Eastern', //the default is your local timezone
  today: '2020-02-20', //the implicit, or reference day/year
  punt: { weeks: 2 }, // the implied duration to use for 'after june 2nd'
  dayStart: '8:00am',
  dayEnd: '5:30pm',
  dmy : false //assume british-format dates, when unclear
}

nlp('in two days').dates(context).get()
/*
  [{ start: '2020-02-22T08:00:00.000+5:00', end: '2020-02-22T17:30:00.000+5:00' }]
*/
```

--------------------------------

### Match by root or lemma

Source: https://github.com/spencermountain/compromise/blob/master/docs/match-syntax.md

Matches all inflected forms of a word using its dictionary root.

```javascript
nlp('he walked away').match('{walk}').text()    // 'walked'
nlp('she is running').match('{run}').text()     // 'running'
nlp('he walks home').match('{walk/verb}').text()      // 'walks'
nlp('the object is heavy').match('{object/noun}').text()  // 'object'
```

--------------------------------

### Load and Use compromise-dates Plugin

Source: https://github.com/spencermountain/compromise/blob/master/plugins/dates/demo/index.html

Load the compromise-dates plugin and process text to extract date information. Ensure the plugin is loaded before use.

```javascript
nlp.plugin(compromiseDates) // window.compromiseDates
```

```javascript
let txt = document.querySelector('kbd').innerText
```

```javascript
let doc = nlp(txt)
```

```javascript
let json = doc.dates().json()
```

```javascript
let iso = json[0].dates.start
```

```javascript
document.querySelector('#res').innerHTML = new Date(iso).toDateString()
```

--------------------------------

### Paragraph Methods

Source: https://github.com/spencermountain/compromise/blob/master/plugins/paragraphs/README.md

Lists the available methods for interacting with paragraph objects, categorized by their function.

```APIDOC
## Paragraph Methods

### Description
This plugin exposes several methods to work with paragraphs, including text output, JSON conversion, matching, selection, and iteration.

### Outputs
- `.text()`: Returns the plain text of the paragraph.
- `.json(options)`: Returns a JSON representation of the paragraph.

### Matches
- `.match(reg)`: Finds paragraphs matching a given regular expression.
- `.not(reg)`: Finds paragraphs not matching a given regular expression.
- `.if(reg)`: Filters paragraphs that match a given regular expression.
- `.ifNo(reg)`: Filters paragraphs that do not match a given regular expression.
- `.has(tag)`: Checks if a paragraph contains a specific tag.

### Selectors
- `.sentences()`: Returns all sentences within the paragraph.
- `.terms()`: Returns all terms within the paragraph.

### Accessors
- `.eq(index)`: Returns the paragraph at the specified index.
- `.first()`: Returns the first paragraph.
- `.last()`: Returns the last paragraph.

### Loops
- `.forEach(fn)`: Iterates over each paragraph.
- `.map(fn)`: Transforms each paragraph and returns a new collection.
- `.filter(fn)`: Filters paragraphs based on a condition.
```

--------------------------------

### Iteration and Loop Methods

Source: https://github.com/spencermountain/compromise/blob/master/README.md

Methods for iterating over phrases or documents using callback functions.

```APIDOC
## .map(fn)
### Description
Runs each phrase through a function and creates a new document.

## .forEach(fn)
### Description
Runs a function on each phrase as an individual document.

## .filter(fn)
### Description
Returns only the phrases that return true for the provided function.

## .find(fn)
### Description
Returns a document containing only the first phrase that matches the function.

## .some(fn)
### Description
Returns true or false if there is at least one matching phrase.

## .random(fn)
### Description
Returns a random subset of the results.
```

--------------------------------

### Money API

Source: https://github.com/spencermountain/compromise/blob/master/README.md

Methods for handling currency values like '$2.50'.

```APIDOC
## .money()

### Description
Identify and manipulate currency-related phrases.

### Methods
- **.money().get()** - Retrieve the parsed amount(s) of money
- **.money().json()** - Get currency and number metadata
- **.money().currency()** - Identify the currency type
```

--------------------------------

### Generate Phonetic Pronunciation with Compromise Speech

Source: https://github.com/spencermountain/compromise/blob/master/plugins/speech/README.md

Use the `.soundsLike()` method after extending compromise with the speech plugin to generate a normalized phonetic string for each token using the Metaphone algorithm. This is useful for fuzzy matching or phonetic searching.

```javascript
import plg from 'compromise-speech'
nlp.extend(plg)

let doc = nlp('seventh millenium. white collar')
doc.soundsLike()
// [ [ 'sefenth', 'milenium' ], [ 'wite', 'kolar' ] ]
```

--------------------------------

### Mutate document in place

Source: https://github.com/spencermountain/compromise/blob/master/docs/recipes.md

Demonstrates how transformation methods modify the original document and how to correctly read the result.

```javascript
let doc = nlp('I walk to work')
doc.verbs().toPastTense()        // mutates doc; the returned view is just "walked"
doc.text()                       // 'I walked to work'   ✅ read from doc

// ⚠️ common mistake — .text() here is only the matched selection:
nlp('I walk to work').verbs().toPastTense().text()   // 'walked work'  (not the whole sentence)
```

--------------------------------

### Matching Grammatical Patterns

Source: https://github.com/spencermountain/compromise/wiki/v7-Upgrade,-welcome

Illustrates using the `.match()` method with a pattern to find specific grammatical structures like '#Person is'. Also shows `.not()` to exclude patterns and `.matchOne()` for single occurrences.

```javascript
nlp('john is cool and jane is nice').match('#Person is').out('array')
//[ 'john is', 'jane is']
nlp('john is cool and jane is nice').not('#Person is').out('array')
//[ 'cool', 'nice']
nlp('john is cool and jane is nice').matchOne('#Person is').out('array')
//[ 'john is']
```

--------------------------------

### nlp.plugin(plugin) / nlp.extend(plugin)

Source: https://github.com/spencermountain/compromise/blob/master/docs/api.md

Mixes in a compromise-plugin to extend library functionality.

```APIDOC
## nlp.plugin(plugin)
## nlp.extend(plugin)

### Description
Mix in a compromise-plugin.

### Parameters
- **plugin** (object) - Required - The plugin to extend the library with.
```

--------------------------------

### Tokenizing with compromise/one

Source: https://github.com/spencermountain/compromise/blob/master/README.md

Use the lightweight tokenizer to extract JSON data from text.

```js
import nlp from 'compromise/one'

let doc = nlp("Wayne's World, party time")
let data = doc.json()
/* [{
  normal:"wayne's world party time",
    terms:[{ text: "Wayne's", normal: "wayne" },
      ...
      ]
  }]
*/
```

--------------------------------

### nlp.addWords(words, isFrozen?)

Source: https://github.com/spencermountain/compromise/blob/master/docs/api.md

Adds new words to the internal lexicon.

```APIDOC
## nlp.addWords(words, isFrozen?)

### Description
Add new words to internal lexicon.

### Parameters
- **words** (object) - Required - The words to add.
- **isFrozen** (boolean) - Optional - Whether the words should be frozen.
```

--------------------------------

### Extracting metadata from phrases

Source: https://github.com/spencermountain/compromise/blob/master/README.md

Retrieves structured metadata for fractions and currency using the compromise/three package.

```js
let doc = nlp('four out of five dentists')
console.log(doc.fractions().json())
/*[{
    text: 'four out of five',
    terms: [ [Object], [Object], [Object], [Object] ],
    fraction: { numerator: 4, denominator: 5, decimal: 0.8 }
  }
]*/
```

```js
let doc = nlp('$4.09CAD')
doc.money().json()
/*[{
    text: '$4.09CAD',
    terms: [ [Object] ],
    number: { prefix: '$', num: 4.09, suffix: 'cad'}
  }
]*/
```

--------------------------------

### Match with term methods

Source: https://github.com/spencermountain/compromise/blob/master/docs/match-syntax.md

Applies built-in predicates to filter tokens.

```javascript
nlp('Hello World now').match('@isTitleCase').out('array')   // ['Hello','World']
```

--------------------------------

### Stage changes for commit

Source: https://github.com/spencermountain/compromise/wiki/Contributing

Add modified files to the staging area before committing them. This prepares your changes to be included in the next commit.

```bash
git add .
```

--------------------------------

### Match a tag in compromise

Source: https://github.com/spencermountain/compromise/blob/master/docs/llms-full.txt

Use the '#' prefix to match specific part-of-speech tags within a document.

```javascript
doc.match('#Person')
```

--------------------------------

### Extending compromise with custom tags and methods

Source: https://github.com/spencermountain/compromise/blob/master/README.md

Use nlp.extend() to define new tags, update the lexicon, modify irregular inflections, and add custom prototype methods to the View object.

```javascript
import nlp from 'compromise'
nlp.extend({
  // add new tags
  tags: {
    Character: {
      isA: 'Person',
      notA: 'Adjective',
    },
  },
  // add or change words in the lexicon
  words: {
    kermit: 'Character',
    gonzo: 'Character',
  },
  // change inflections
  irregulars: {
    get: {
      pastTense: 'gotten',
      gerund: 'gettin',
    },
  },
  // add new methods to compromise
  api: View => {
    View.prototype.kermitVoice = function () {
      this.sentences().prepend('well,')
      this.match('i [(am|was)]').prepend('um,')
      return this
    }
  },
})
```

--------------------------------

### Loops

Source: https://github.com/spencermountain/compromise/blob/master/docs/api.md

Methods for iterating over phrases within the document.

```APIDOC
## Loops

- **.forEach(fn)** — run a function on each phrase, as an individual document
- **.map(fn, emptyResult?)** — run each phrase through a function, and create a new document
- **.filter(fn)** — return only the phrases that return true
- **.find(fn)** — return a document with only the first phrase that matches
- **.some(fn)** — return true or false if there is one matching phrase
- **.random(n?)** — sample a subset of the results
```

--------------------------------

### Add and Retrieve Payloads

Source: https://github.com/spencermountain/compromise/blob/master/plugins/payload/README.md

Extend compromise with the payload plugin and use .addPayload() to attach data to matches. Retrieve specific payloads with .getPayloads() or all payloads with .getPayloads().

```javascript
import plg from 'compromise-payload'
nlp.extend(plg)

let doc = nlp('i saw John Lennon in Manchester, and Bob Dylan in Southhampton')

// markup metadata
doc.match('(john lennon|bob dylan)').addPayload({ instrument: 'guitar' })

// add more
doc.people().forEach(m => {
  if (m.has('lennon')) {
    m.addPayload({ height: `5'11` })
  }
  if (m.has('ringo')) {
    m.addPayload({ height: `5'8` })
  }
})

// retrieve specific payloads
doc.match('john lennon').getPayloads()
doc.match('bob dylabn').getPayloads()

// retrieve them all
doc.getPayloads()

// inspect given payloads:
doc.debug('payload')
```

--------------------------------

### Perform fast lookups with an array

Source: https://github.com/spencermountain/compromise/blob/master/docs/match-syntax.md

Use .lookup() for efficient matching against a list of literal words instead of multiple .match() calls.

```javascript
nlp('i saw mary and john').lookup(['mary', 'john']).out('array')   // ['mary','john']
```

--------------------------------

### Pointer and Set Operations

Source: https://github.com/spencermountain/compromise/blob/master/docs/api.md

Methods for performing set-based operations on document matches.

```APIDOC
## Pointer and Set Operations

### Methods
- `.union(match)` - Return all matches without duplicates.
- `.and(match)` - Alias for .union().
- `.intersection(match)` - Return only duplicate matches.
- `.not(match, options?)` - Return all results except for the match.
- `.difference(match, options?)` - Alias for .not().
- `.complement(match)` - Get everything that is not a match.
- `.settle(match)` - Remove overlaps in matches.
```

--------------------------------

### Load and Use compromise-wikipedia Plugin

Source: https://github.com/spencermountain/compromise/blob/master/plugins/wikipedia/demo/index.html

This snippet shows how to load the compromise-wikipedia plugin, process text, and output Wikipedia entities as a JSON array. Ensure the compromise library and the wikipedia plugin are loaded before executing this code.

```javascript
nlp.plugin(compromiseWikipedia)
let txt = document.querySelector('kbd').innerText
let doc = nlp(txt)
let json = doc.wikipedia().out('array')
document.querySelector('#res').innerHTML = JSON.stringify(json, null, 2)
```

--------------------------------

### nlp.tokenize(text, lexicon?)

Source: https://github.com/spencermountain/compromise/blob/master/docs/api.md

Interprets text without performing full tagging.

```APIDOC
## nlp.tokenize(text, lexicon?)

### Description
Interpret text without tagging.

### Parameters
- **text** (string) - Required - The input text to tokenize.
- **lexicon** (object) - Optional - Custom lexicon for tokenization.
```

--------------------------------

### Whitespace and Formatting

Source: https://github.com/spencermountain/compromise/blob/master/docs/api.md

Methods for managing whitespace, hyphens, and quotation marks around document selections.

```APIDOC
## Whitespace and Formatting

### Methods
- `.pre(str?, concat?)` - Add punctuation or whitespace before each match.
- `.post(str?, concat?)` - Add punctuation or whitespace after each match.
- `.trim()` - Remove start and end whitespace.
- `.hyphenate()` - Connect words with hyphens.
- `.dehyphenate()` - Remove hyphens between words.
- `.deHyphenate()` - Alias for .dehyphenate().
- `.toQuotations(start?, end?)` - Add quotation marks around selections.
- `.toQuotation(start?, end?)` - Alias for .toQuotations().
- `.toParentheses(start?, end?)` - Add parentheses around selections.
```

--------------------------------

### Demonstrate nested match syntax limitation

Source: https://github.com/spencermountain/compromise/blob/master/README.md

Shows that complex nested regex-like patterns are not supported in the current match syntax.

```javascript
doc.match('(modern (major|minor))? general')
```

--------------------------------

### nlp.parseMatch(match, opts?)

Source: https://github.com/spencermountain/compromise/blob/master/docs/api.md

Turns a match-string into JSON format.

```APIDOC
## nlp.parseMatch(match, opts?)

### Description
Turn a match-string into json.

### Parameters
- **match** (string) - Required - The match string to parse.
- **opts** (object) - Optional - Parsing options.
```

--------------------------------

### Demonstrate inter-sentence match limitation

Source: https://github.com/spencermountain/compromise/blob/master/README.md

Shows that matches cannot span across sentence boundaries by default.

```javascript
nlp("that's it. Back to Winnipeg!").has('it back')//false
```

--------------------------------

### nlp.typeahead(words)

Source: https://github.com/spencermountain/compromise/blob/master/docs/api.md

Adds words to the autoFill dictionary.

```APIDOC
## nlp.typeahead(words)

### Description
Add words to the autoFill dictionary.

### Parameters
- **words** (array) - Required - List of words.
```

--------------------------------

### Fractions API

Source: https://github.com/spencermountain/compromise/blob/master/README.md

Methods for handling fractional values like '2/3rds'.

```APIDOC
## .fractions()

### Description
Identify and manipulate fractional phrases.

### Methods
- **.fractions().parse()** - Get tokenized fraction
- **.fractions().get()** - Get numerator and denominator data
- **.fractions().json()** - Get fraction metadata
- **.fractions().toDecimal()** - Convert '2/3' to '0.66'
- **.fractions().normalize()** - Convert 'four out of 10' to '4/10'
- **.fractions().toText()** - Convert '4/10' to 'four tenths'
- **.fractions().toPercentage()** - Convert '4/10' to '40%'
```

--------------------------------

### Match exact words

Source: https://github.com/spencermountain/compromise/blob/master/docs/match-syntax.md

Matches specific words literally without lemmatization.

```javascript
nlp('we walked to work').has('walked')          // true
nlp('we walked to work').match('walk').text()   // '' — exact word, not lemma
```

--------------------------------

### Utils

Source: https://github.com/spencermountain/compromise/blob/master/docs/api.md

Utility methods for inspecting and manipulating the document structure.

```APIDOC
## Utils

- **.found** [getter] — is this document empty?
- **.docs** [getter] — get a list of term objects for this view
- **.document** [getter] — get the full parsed text
- **.pointer** [getter] — the indexes for the current view
- **.fullPointer** [getter] — explicit indexes for the current view
- **.methods** [getter] — access internal library methods
- **.model** [getter] — access internal library data
- **.hooks** [getter] — which compute methods run by default
- **.isView** [getter] — helper for detecting a compromise object
- **.length** [getter] — count the # of characters of each match
- **.update(pointer)** — create a new view, from this document
- **.toView(pointer)** — turn a Verb or Noun view into a normal one
- **.fromText(text)** — create a new document
- **.termList()** — .docs [alias]
- **.compute(method)** — run a named operation on the document
- **.clone(shallow?)** — deep-copy the document, so that no references remain
```

--------------------------------

### Percentages API

Source: https://github.com/spencermountain/compromise/blob/master/README.md

Methods for handling percentage values like '2.5%'.

```APIDOC
## .percentages()

### Description
Identify and manipulate percentage phrases.

### Methods
- **.percentages().get()** - Return the percentage number divided by 100
- **.percentages().json()** - Get percentage information
- **.percentages().toFraction()** - Convert '80%' to '8/10'
```
Tokens:
Raw