Linguistic Analysis

/**
 * Return all verb phrases in the view
 * @param n - Optional limit on number of results
 * @returns Verbs view with specialized verb methods
 */
verbs(n?: number): Verbs;

interface Verbs extends View {
  /** Get parsed verb phrase information */
  parse(n?: number): object[];
  /** Get subjects performing the verb action */
  subjects(): View;
  /** Get adverbs describing the verb */
  adverbs(): View;
  /** Return only singular verbs */
  isSingular(): View;
  /** Return only plural verbs */
  isPlural(): View;
  /** Return only imperative verbs (commands) */
  isImperative(): View;
  /** Return only negative verbs */
  isNegative(): View;
  /** Return only positive verbs (without 'not') */
  isPositive(): View;
  /** Get all conjugated forms of these verbs */
  conjugate(): object[];
}

const doc = nlp("I walked to the store and quickly bought groceries");

// Extract verbs
const verbs = doc.verbs();
console.log(verbs.out('array')); // ['walked', 'bought']

// Get verb subjects
const subjects = doc.verbs().subjects();
console.log(subjects.out('array')); // ['I']

// Get adverbs modifying verbs
const adverbs = doc.verbs().adverbs();
console.log(adverbs.out('array')); // ['quickly']

// Parse verb information
const verbData = doc.verbs().parse();
console.log(verbData); // [{ text: 'walked', tense: 'PastTense', ... }]

// Check verb properties
const negativeVerbs = doc.verbs().isNegative();
const imperativeVerbs = doc.verbs().isImperative();

/**
 * Return noun phrases in the view
 * @param n - Optional limit on number of results
 * @param opts - Additional options for noun extraction
 * @returns Nouns view with specialized noun methods
 */
nouns(n?: number, opts?: object): Nouns;

interface Nouns extends View {
  /** Get parsed noun phrase information */
  parse(n?: number): object[];
  /** Return only plural nouns */
  isPlural(): View;
  /** Get adjectives describing these nouns */
  adjectives(): View;
}

const doc = nlp("The red car and blue trucks were parked outside");

// Extract nouns
const nouns = doc.nouns();
console.log(nouns.out('array')); // ['car', 'trucks']

// Check if plural
const pluralNouns = doc.nouns().isPlural();
console.log(pluralNouns.out('array')); // ['trucks']

// Get adjectives describing nouns
const adjectives = doc.nouns().adjectives();
console.log(adjectives.out('array')); // ['red', 'blue']

// Parse noun information
const nounData = doc.nouns().parse();
console.log(nounData); // [{ text: 'car', isPlural: false, ... }]

/**
 * Return adjectives in the view
 * @param n - Optional limit on number of results
 * @returns Adjectives view with specialized methods
 */
adjectives(n?: number): Adjectives;

interface Adjectives extends View {
  /** Get adverbs describing these adjectives */
  adverbs(): View;
  /** Get all conjugated forms */
  conjugate(): object[];
}

const doc = nlp("The very tall man was extremely happy");

// Extract adjectives
const adjectives = doc.adjectives();
console.log(adjectives.out('array')); // ['tall', 'happy']

// Get adverbs modifying adjectives
const adverbs = doc.adjectives().adverbs();
console.log(adverbs.out('array')); // ['very', 'extremely']

// Get conjugated forms
const conjugated = doc.adjectives().conjugate();
console.log(conjugated); // [{ comparative: 'taller', superlative: 'tallest', ... }]

/**
 * Return adverbs in the view
 * @param n - Optional limit on number of results
 * @returns Adverbs view
 */
adverbs(n?: number): Adverbs;

interface Adverbs extends View {
  // Inherits all standard View methods
}

const doc = nlp("He quickly and carefully walked slowly");

// Extract adverbs
const adverbs = doc.adverbs();
console.log(adverbs.out('array')); // ['quickly', 'carefully', 'slowly']

/**
 * Return person names
 * @param n - Optional limit on number of results
 * @returns People view with name parsing methods
 */
people(n?: number): People;

/**
 * Return location names
 * @param n - Optional limit on number of results
 */
places(n?: number): View;

/**
 * Return organization names
 * @param n - Optional limit on number of results
 */
organizations(n?: number): View;

/**
 * Return all named entities (people, places, organizations)
 * @param n - Optional limit on number of results
 */
topics(n?: number): View;

interface People extends View {
  /** Parse person names into first/last/middle components */
  parse(): object[];
}

const doc = nlp("John Smith works at Google in San Francisco");

// Extract people
const people = doc.people();
console.log(people.out('array')); // ['John Smith']

// Parse person names
const nameData = doc.people().parse();
console.log(nameData); // [{ first: 'John', last: 'Smith', ... }]

// Extract places
const places = doc.places();
console.log(places.out('array')); // ['San Francisco']

// Extract organizations
const orgs = doc.organizations();
console.log(orgs.out('array')); // ['Google']

// Get all named entities
const entities = doc.topics();
console.log(entities.out('array')); // ['John Smith', 'Google', 'San Francisco']

/**
 * Return terms with hyphens or dashes
 */
hyphenated(n?: number): View;

/**
 * Return hashtag terms
 */
hashTags(n?: number): View;

/**
 * Return email addresses
 */
emails(n?: number): View;

/**
 * Return emoji characters
 */
emoji(n?: number): View;

/**
 * Return emoticon patterns
 */
emoticons(n?: number): View;

/**
 * Return @ mentions
 */
atMentions(n?: number): View;

/**
 * Return URL patterns
 */
urls(n?: number): View;

/**
 * Return phone number patterns
 */
phoneNumbers(n?: number): View;

const doc = nlp("Contact me at john@example.com or call (555) 123-4567! #awesome 😊");

// Extract different text types
console.log(doc.emails().out('array')); // ['john@example.com']
console.log(doc.phoneNumbers().out('array')); // ['(555) 123-4567']
console.log(doc.hashTags().out('array')); // ['#awesome']
console.log(doc.emoji().out('array')); // ['😊']

const socialDoc = nlp("Check out @username and their well-documented code");
console.log(socialDoc.atMentions().out('array')); // ['@username']
console.log(socialDoc.hyphenated().out('array')); // ['well-documented']

/**
 * Return pronoun terms
 */
pronouns(n?: number): View;

/**
 * Return conjunction terms
 */
conjunctions(n?: number): View;

/**
 * Return preposition terms
 */
prepositions(n?: number): View;

/**
 * Return honorific terms
 */
honorifics(n?: number): View;

/**
 * Return abbreviation terms
 */
abbreviations(n?: number): View;

const doc = nlp("Dr. Smith said he and she went to the store, but they came back early");

// Extract grammatical categories
console.log(doc.pronouns().out('array')); // ['he', 'she', 'they']
console.log(doc.conjunctions().out('array')); // ['and', 'but']
console.log(doc.prepositions().out('array')); // ['to']
console.log(doc.honorifics().out('array')); // ['Dr.']

/**
 * Return full sentences
 * @param n - Optional limit on number of results
 * @param opts - Additional options
 * @returns Sentences view with sentence methods
 */
sentences(n?: number, opts?: object): Sentences;

/**
 * Return only question sentences
 */
questions(n?: number, opts?: object): View;

interface Sentences extends View {
  /** Parse sentence structure information */
  parse(n?: number): object[];
  /** Return only question sentences */
  isQuestion(): View;
  /** Return only exclamation sentences */
  isExclamation(): View;
  /** Return only statement sentences */
  isStatement(): View;
}

const doc = nlp("How are you? I am fine! This is a statement.");

// Extract sentences
const sentences = doc.sentences();
console.log(sentences.length); // 3

// Filter by sentence type
const questions = doc.sentences().isQuestion();
console.log(questions.out('array')); // ['How are you?']

const exclamations = doc.sentences().isExclamation();
console.log(exclamations.out('array')); // ['I am fine!']

const statements = doc.sentences().isStatement();
console.log(statements.out('array')); // ['This is a statement.']

// Parse sentence structure
const sentenceData = doc.sentences().parse();
console.log(sentenceData); // [{ type: 'question', ... }, ...]

/**
 * Return all contractions in the view
 * @param n - Optional limit on number of results
 * @returns Contractions view with specialized contraction methods
 */
contractions(n?: number): Contractions;

/**
 * Contract words that can combine
 * @returns View with contracted words
 */
contract(): View;

/**
 * Smart replace root forms while preserving grammar
 * @param fromLemma - Root form to replace
 * @param toLemma - Root form to replace with  
 * @param guardTag - Optional tag to constrain replacement
 * @returns View with smart replacements
 */
swap(fromLemma: string, toLemma: string, guardTag?: string): View;

/**
 * Average measure of tag confidence
 * @returns Confidence score between 0 and 1
 */
confidence(): number;

const doc = nlp("I don't think we'll be able to make it");

// Extract contractions
const contractions = doc.contractions();
console.log(contractions.out('array')); // ["don't", "we'll"]

// Expand contractions
const expanded = doc.contractions().expand();
console.log(expanded.out('text')); // "I do not think we will be able to make it"

// Contract expandable words
const contractedDoc = nlp("I did not see you will be there");
const contracted = contractedDoc.contract();
console.log(contracted.out('text')); // "I didn't see you'll be there"

// Smart replace preserving tense/form
const swapped = doc.swap('walk', 'run');
console.log(swapped.out('text')); // Smart replacement preserving grammar

// Check tagging confidence
const confidenceScore = doc.confidence();
console.log(confidenceScore); // 0.85 (confidence in tagging accuracy)

interface Verbs extends View {
  parse(n?: number): object[];
  subjects(): View;
  adverbs(): View;
  isSingular(): View;
  isPlural(): View;
  isImperative(): View;
  isNegative(): View;
  isPositive(): View;
  conjugate(): object[];
}

interface Nouns extends View {
  parse(n?: number): object[];
  isPlural(): View;
  adjectives(): View;
}

interface Adjectives extends View {
  adverbs(): View;
  conjugate(): object[];
}

interface Adverbs extends View {}

interface People extends View {
  parse(): object[];
}

interface Sentences extends View {
  parse(n?: number): object[];
  isQuestion(): View;
  isExclamation(): View;
  isStatement(): View;
}

interface Contractions extends View {
  /** Turn contractions like "i've" into "i have" */
  expand(): View;
}