# Compromise API Reference Every method returns a new **View** (a sub-selection of the document) unless noted, so calls chain: `nlp(text).match('#Verb').toPastTense().text()`. Methods are grouped by what they do. Method availability depends on the [build tier](concepts.md): `compromise/one` (tokenize), `compromise/two` (+tags & contractions), and the default `compromise` / `compromise/three` (+ all selections below). ## Core methods _(available on every View)_ - **`.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 ### 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 ### 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 ### Accessors - **`.terms(n?)`** — split-up results by each individual term - **`.groups(name?)`** — grab a specific named capture group - **`.eq(n)`** — use only the nth result - **`.first(n?)`** — use only the first result(s) - **`.last(n?)`** — use only the last result(s) - **`.firstTerms()`** — get the first word in each match - **`.lastTerms()`** — get the end word in each match - **`.slice(start, end?)`** — grab a subset of the results - **`.all()`** — return the whole original document ('zoom out') - **`.fullSentences()`** — return the full original sentence for each match - **`.none()`** — return an empty view - **`.isDoc(view?)`** — are these two views of the same document? - **`.wordCount()`** — count the # of terms in each match ### Match - **`.match(match, group?, options?)`** — return matching patterns in this doc - **`.matchOne(match, group?, options?)`** — return only the first match - **`.has(match, group?, options?)`** — Return a boolean if this match exists - **`.if(match, group?, options?)`** — return each current phrase, only if it contains this match - **`.ifNo(match, group?, options?)`** — Filter-out any current phrases that have this match - **`.before(match, group?, options?)`** — return the terms before each match - **`.after(match, group?, options?)`** — return the terms after each match - **`.lookBehind(match, group?, options?)`** — alias of .before() - **`.lookBefore(match, group?, options?)`** — alias of .before() - **`.lookAhead(match, group?, options?)`** — alias of .after() - **`.lookAfter(match, group?, options?)`** — alias of .after() - **`.growLeft(match, group?, options?)`** — add any immediately-preceding matches to the view - **`.growRight(match, group?, options?)`** — add any immediately-following matches to the view - **`.grow(match, group?, options?)`** — expand the view with any left-or-right matches - **`.sweep(match, opts?)`** — apply a sequence of match objects to the document - **`.splitOn(match?, group?)`** — .split() [alias] - **`.splitBefore(match?, group?)`** — separate everything after the match as a new phrase - **`.splitAfter(match?, group?)`** — separate everything before the word, as a new phrase - **`.split(match?, group?)`** — splitAfter() alias ### Case - **`.toLowerCase()`** — turn every letter of every term to lower-cse - **`.toUpperCase()`** — turn every letter of every term to upper case - **`.toTitleCase()`** — upper-case the first letter of each term - **`.toCamelCase()`** — remove whitespace and title-case each term ### Insert - **`.concat(input)`** — add these new things to the end - **`.insertBefore(input)`** — add these words before each match - **`.prepend(input)`** — insertBefore() alias - **`.insertAfter(text)`** — add these words after each match - **`.append(text)`** — insertAfter() alias - **`.insert(text)`** — insertAfter() alias - **`.remove(match)`** — fully remove these terms from the document - **`.delete(match)`** — alias for .remove() - **`.replace(from, to?, keep?)`** — search and replace match with new content - **`.replaceWith(to, keep?)`** — substitute-in new content - **`.unique()`** — remove any duplicate matches - **`.reverse()`** — reverse the order of the matches, but not the words - **`.sort(method?)`** — re-arrange the order of the matches (in place) - **`.normalize(options?)`** — cleanup various aspects of the words ### Whitespace - **`.pre(str?, concat?)`** — add this punctuation or whitespace before each match - **`.post(str?, concat?)`** — add this punctuation or whitespace after each match - **`.trim()`** — remove start and end whitespace - **`.hyphenate()`** — connect words with hyphen, and remove whitespace - **`.dehyphenate()`** — remove hyphens between words, and set whitespace - **`.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 ### Output - **`.text(options?)`** — return the document as text - **`.json(options?)`** — pull out desired metadata from the document - **`.debug()`** — pretty-print the current document and its tags - **`.out(format?)`** — some named output formats - **`.html(toHighlight)`** — produce an html string - **`.wrap(matches)`** — produce an html string ### Pointers - **`.union(match)`** — return all matches without duplicates - **`.and(match)`** — .union() alias - **`.intersection(match)`** — return only duplicate matches - **`.not(match, options?)`** — return all results except for this - **`.difference(match, options?)`** — .not() alias - **`.complement(match)`** — get everything that is not a match - **`.settle(match)`** — remove overlaps in matches ### Tag - **`.tag(tag, reason?)`** — Give all terms the given tag - **`.tagSafe(tag, reason?)`** — Only apply tag to terms if it is consistent with current tags - **`.unTag(tag, reason?)`** — Remove this term from the given terms - **`.canBe(tag)`** — return only the terms that can be this tag ### Cache - **`.cache(options?)`** — freeze the current state of the document, for speed-purposes - **`.uncache(options?)`** — un-freezes the current state of the document, so it may be transformed - **`.freeze()`** — prevent current tags from being removed - **`.unfreeze()`** — allow current tags to be changed [default] - **`.lookup(trie, opts?)`** — quick find for an array of string matches - **`.autoFill()`** — assume any type-ahead prefixes - **`.contractions(n?)`** — return any multi-word terms, like "didn't" - **`.contract()`** — contract words that can combine, like "did not" - **`.confidence()`** — Average measure of tag confidence - **`.swap(fromLemma, toLemma, guardTag?)`** — smart-replace root forms - **`.expand()`** — turn "i've" into "i have" ## Selections (compromise/three) These return specialised sub-views with extra methods. e.g. `doc.verbs().toPastTense()`. ### Selection methods on any View - **`.clauses(n?)`** — split-up results into multi-term phrases - **`.chunks()`** — split-up noun-phrase and verb-phrases - **`.normalize(options?)`** — clean-up the document, in various ways - **`.redact(opts?, blockStr?, keepTags?)`** — remove any people, places, and organizations - **`.hyphenated(n?)`** — return all terms connected with a hyphen or dash like `'wash-out'` - **`.hashTags(n?)`** — return terms like `'#nlp'` - **`.emails(n?)`** — return terms like `'hi@compromise.cool'` - **`.emoji(n?)`** — return terms like `💋` - **`.emoticons(n?)`** — return terms like `:)` - **`.atMentions(n?)`** — return terms like `'@nlp_compromise'` - **`.urls(n?)`** — return terms like `'compromise.cool'` - **`.pronouns(n?)`** — return terms like `'he'` - **`.conjunctions(n?)`** — return terms like `'but'` - **`.prepositions(n?)`** — return terms like `'of'` - **`.honorifics(n?)`** — return terms like `'Dr.'` - **`.abbreviations(n?)`** — return terms like `'st.'` - **`.phoneNumbers(n?)`** — return terms like `'(939) 555-0113'` - **`.addresses(n?)`** — return terms like `'23 Park Avenue'` - **`.acronyms(n?)`** — return terms like `'FBI'` - **`.parentheses(n?)`** — return anything inside (parentheses) - **`.possessives(n?)`** — return terms like "Spencer's" - **`.quotations(n?)`** — return any terms inside 'quotation marks' - **`.slashes(n?)`** — return any slashed terms like 'love/hate' - **`.adjectives(n?)`** — return words like "clean" - **`.adverbs(n?)`** — return words like "quickly" - **`.nouns(n?, opts?)`** — return noun phrases in the view - **`.numbers(n?, opts?)`** — return any numbers in the view - **`.percentages(n?, opts?)`** — return any percentages in the view - **`.money(n?, opts?)`** — return any money in the view - **`.fractions(n?, opts?)`** — return any fractions in the view - **`.sentences(n?, opts?)`** — return full sentences in the view - **`.questions(n?, opts?)`** — find full sentences of any questions in the view - **`.verbs(n?)`** — return any subsequent terms tagged as a Verb - **`.people(n?)`** — return person names like `'John A. Smith'` - **`.places(n?)`** — return location names like `'Paris, France'` - **`.organizations(n?)`** — return companies and org names like `'Google Inc.'` - **`.topics(n?)`** — return people, places, and organizations ### `.nouns()` → - **`.parse(n?)`** — grab the parsed noun-phrase - **`.isPlural()`** — return only plural nouns - **`.adjectives()`** — get any adjectives describing this noun - **`.toPlural(setArticle?)`** — 'football captain' → 'football captains' - **`.toSingular(setArticle?)`** — 'turnovers' → 'turnover' ### `.numbers()` → - **`.parse(n?)`** — grab the parsed number - **`.get(n?)`** — grab the parsed number - **`.isOrdinal()`** — return only ordinal numbers - **`.isCardinal()`** — return only cardinal numbers - **`.isUnit(units)`** — return only numbers with the given unit(s), like 'km' - **`.toNumber()`** — convert number to `5` or `5th` - **`.toLocaleString()`** — add commas, or nicer formatting for numbers - **`.toText()`** — convert number to `five` or `fifth` - **`.toCardinal()`** — convert number to `five` or `5` - **`.toOrdinal()`** — convert number to `fifth` or `5th` - **`.isEqual()`** — return numbers with this value - **`.greaterThan(min)`** — return numbers bigger than n - **`.lessThan(max)`** — return numbers smaller than n - **`.between(min, max)`** — return numbers between min and max - **`.set(n)`** — set number to n - **`.add(n)`** — increase number by n - **`.subtract(n)`** — decrease number by n - **`.increment()`** — increase number by 1 - **`.decrement()`** — decrease number by 1 ### `.fractions()` → - **`.parse(n?)`** — grab the parsed number - **`.get(n?)`** — grab the parsed number - **`.toDecimal()`** — convert '1/4' to `0.25` - **`.toFraction()`** — convert 'one fourth' to `1/4` - **`.toOrdinal()`** — convert '1/4' to '1/4th' - **`.toCardinal()`** — convert '1/4th' to '1/4' - **`.toPercentage()`** — convert '1/4' to `25%` ### `.sentences()` → - **`.parse(n?)`** — grab the parsed sentence - **`.toPastTense()`** — 'will go' → 'went' - **`.toPresentTense()`** — 'walked' → 'walks' - **`.toFutureTense()`** — 'walked' → 'will walk' - **`.toInfinitive()`** — 'walks' → 'walk' - **`.toNegative()`** — 'he is cool' → 'he is not cool' - **`.toPositive()`** — 'he isn't cool' -> 'he is cool' - **`.isQuestion()`** — keep only questions - **`.isExclamation()`** — keep only sentences with an exclamation-mark - **`.isStatement()`** — remove questions, and exclamations ### `.people()` → - **`.parse()`** — get first/last/middle names ### `.verbs()` → - **`.parse(n?)`** — grab the parsed verb-phrase - **`.subjects()`** — grab what [doing] the verb - **`.adverbs()`** — return the adverbs describing this verb - **`.isSingular()`** — return only singular nouns - **`.isPlural()`** — return only plural nouns - **`.isImperative()`** — only verbs that are instructions - **`.toInfinitive()`** — 'walks' → 'walk' - **`.toPresentTense()`** — 'walked' → 'walks' - **`.toPastTense()`** — 'will go' → 'went' - **`.toFutureTense()`** — 'walked' → 'will walk' - **`.toGerund()`** — 'walks' → 'walking' - **`.toPastParticiple()`** — 'walks' → 'has walked' - **`.conjugate()`** — return all forms of these verbs - **`.isNegative()`** — return verbs with 'not' - **`.isPositive()`** — only verbs without 'not' - **`.toPositive()`** — "didn't study" → 'studied' - **`.toNegative()`** — 'went' → 'did not go' ### `.acronyms()` → - **`.strip()`** — 'F.B.I.' -> 'FBI' - **`.addPeriods()`** — 'FBI' -> 'F.B.I.' ### `.parentheses()` → - **`.strip()`** — remove ( and ) punctuation ### `.possessives()` → - **`.strip()`** — "spencer's" -> "spencer" ### `.quotations()` → - **`.strip()`** — remove leading and trailing quotation marks ### `.slashes()` → - **`.split()`** — turn 'love/hate' into 'love hate' ### `.adjectives()` → - **`.adverbs()`** — get the words describing this adjective - **`.conjugate()`** — return all forms of these - **`.toComparative(n?)`** — 'quick' -> 'quicker' - **`.toSuperlative(n?)`** — 'quick' -> 'quickest' - **`.toAdverb(n?)`** — 'quick' -> 'quickly' - **`.toNoun(n?)`** — 'quick' -> 'quickness' ## Constructor methods (`nlp.*`) _(called on the imported `nlp` object, not a View)_ - **`nlp.tokenize(text, lexicon?)`** — interpret text without tagging - **`nlp.lazy(text, match?)`** — scan through text with minimal analysis - **`nlp.plugin(plugin)`** — mix in a compromise-plugin - **`nlp.extend(plugin)`** — mix-in a compromise plugin - **`nlp.parseMatch(match, opts?)`** — turn a match-string into json - **`nlp.world()`** — grab library internals - **`nlp.model()`** — grab library metadata - **`nlp.methods()`** — grab exposed library methods - **`nlp.hooks()`** — which compute functions run automatically - **`nlp.verbose(toLog?)`** — log our decision-making for debugging - **`nlp.version`** — current semver version of the library - **`nlp.addTags(tags)`** — connect new tags to tagset graph - **`nlp.addWords(words, isFrozen?)`** — add new words to internal lexicon - **`nlp.buildTrie(words)`** — turn a list of words into a searchable graph - **`nlp.buildNet(matches)`** — compile a set of match objects to a more optimized form - **`nlp.typeahead(words)`** — add words to the autoFill dictionary