Pattern Matching

/**
 * Return matching patterns in the document
 * @param pattern - Pattern to match (string, regex, Net, or ParsedMatch)
 * @param group - Optional capture group to extract  
 * @param options - Matching options (fuzzy, caseSensitive)
 * @returns View containing all matches
 */
match(pattern: string | Net | ParsedMatch, group?: string | number, options?: object): View;

/**
 * Return only the first match
 * @param pattern - Pattern to match
 * @param group - Optional capture group to extract
 * @param options - Matching options
 * @returns View containing first match only
 */
matchOne(pattern: string | Net | ParsedMatch, group?: string | number, options?: object): View;

/**
 * Test if pattern exists in document
 * @param pattern - Pattern to test for
 * @param group - Optional capture group
 * @param options - Matching options
 * @returns Boolean indicating if pattern exists
 */
has(pattern: string | Net | ParsedMatch, group?: string | number, options?: object): boolean;

const doc = nlp("I love pizza and pasta, but I hate broccoli");

// Simple word matching
const foods = doc.match('(pizza|pasta|broccoli)');
console.log(foods.out('array')); // ['pizza', 'pasta', 'broccoli']

// Tag-based matching
const verbs = doc.match('#Verb');
console.log(verbs.out('array')); // ['love', 'hate']

// Test for existence
if (doc.has('pizza')) {
  console.log('Found pizza!');
}

// Case insensitive matching
const caseInsensitive = doc.match('PIZZA', null, { caseSensitive: false });
console.log(caseInsensitive.out('array')); // ['pizza']

// Get only first match
const firstFood = doc.matchOne('(pizza|pasta|broccoli)');
console.log(firstFood.out('text')); // 'pizza'

const doc = nlp("John Smith quickly walked to the big red car yesterday");

// Tag patterns
const adjectives = doc.match('#Adjective+');
console.log(adjectives.out('array')); // ['big red']

// Optional patterns
const namePattern = doc.match('#Person [#Adverb] #Verb');
console.log(namePattern.out('array')); // ['John Smith quickly walked']

// Capture groups
const captured = doc.match('(#Person) #Verb to the (#Adjective+ #Noun)', ['person', 'target']);
const groups = captured.groups();
console.log(groups.person.out('text')); // 'John Smith'
console.log(groups.target.out('text')); // 'big red car'

// Regex patterns
const timePattern = doc.match('/^(yesterday|today|tomorrow)$/');
console.log(timePattern.out('array')); // ['yesterday']

// Complex patterns
const verbPhrase = doc.match('#Adverb? #Verb #Preposition? the #Adjective* #Noun');
console.log(verbPhrase.out('text')); // 'quickly walked to the big red car'

/**
 * Return current phrases only if they contain the match
 * @param pattern - Pattern that must be present
 * @param group - Optional capture group
 * @param options - Matching options
 * @returns View with matching phrases only
 */
if(pattern: string | Net | ParsedMatch, group?: string | number, options?: object): View;

/**
 * Filter out phrases that contain the match
 * @param pattern - Pattern to exclude
 * @param group - Optional capture group  
 * @param options - Matching options
 * @returns View with non-matching phrases only
 */
ifNo(pattern: string | Net | ParsedMatch, group?: string | number, options?: object): View;

const doc = nlp("The quick brown fox jumps. The lazy dog sleeps. Birds fly high.");

// Get sentences containing specific words
const sentences = doc.sentences();
const withAnimals = sentences.if('#Animal');
console.log(withAnimals.out('array')); // ['The quick brown fox jumps.', 'The lazy dog sleeps.']

// Get sentences without specific patterns
const withoutJumping = sentences.ifNo('jump');
console.log(withoutJumping.out('array')); // ['The lazy dog sleeps.', 'Birds fly high.']

// Chain conditional matching
const specificSentences = doc.sentences().if('#Animal').ifNo('sleep');
console.log(specificSentences.out('array')); // ['The quick brown fox jumps.']

/**
 * Return terms before each match
 * @param pattern - Pattern to search before
 * @param group - Optional capture group
 * @param options - Matching options
 * @returns View with terms before matches
 */
before(pattern: string | Net | ParsedMatch, group?: string | number, options?: object): View;

/**
 * Return terms after each match
 * @param pattern - Pattern to search after
 * @param group - Optional capture group
 * @param options - Matching options  
 * @returns View with terms after matches
 */
after(pattern: string | Net | ParsedMatch, group?: string | number, options?: object): View;

// Aliases for before/after
lookBehind(pattern: string | Net | ParsedMatch, group?: string | number, options?: object): View;
lookBefore(pattern: string | Net | ParsedMatch, group?: string | number, options?: object): View;
lookAhead(pattern: string | Net | ParsedMatch, group?: string | number, options?: object): View;
lookAfter(pattern: string | Net | ParsedMatch, group?: string | number, options?: object): View;

const doc = nlp("I walked quickly to the red car and drove home");

// Find words before patterns
const beforeCar = doc.before('car');
console.log(beforeCar.out('text')); // 'I walked quickly to the red'

// Find words after patterns
const afterAnd = doc.after('and');
console.log(afterAnd.out('text')); // 'drove home'

// Use with more complex patterns
const beforeNoun = doc.before('#Noun');
console.log(beforeNoun.out('array')); // multiple results

// Chain positional matching
const contextWord = doc.after('to').before('and');
console.log(contextWord.out('text')); // 'the red car'

/**
 * Add immediately preceding matches to the view
 * @param pattern - Pattern to grow towards on the left
 * @param group - Optional capture group
 * @param options - Matching options
 * @returns View expanded leftward
 */
growLeft(pattern: string | Net | ParsedMatch, group?: string | number, options?: object): View;

/**
 * Add immediately following matches to the view
 * @param pattern - Pattern to grow towards on the right
 * @param group - Optional capture group
 * @param options - Matching options
 * @returns View expanded rightward
 */
growRight(pattern: string | Net | ParsedMatch, group?: string | number, options?: object): View;

/**
 * Expand the view with left or right matches
 * @param pattern - Pattern to grow towards
 * @param group - Optional capture group
 * @param options - Matching options
 * @returns View expanded in both directions
 */
grow(pattern: string | Net | ParsedMatch, group?: string | number, options?: object): View;

const doc = nlp("The very quick brown fox jumps high");

// Start with core match and grow
const fox = doc.match('fox');
const expandedLeft = fox.growLeft('#Adjective');
console.log(expandedLeft.out('text')); // 'quick brown fox'

const expandedRight = fox.growRight('#Verb');
console.log(expandedRight.out('text')); // 'fox jumps'

// Grow in both directions
const fullPhrase = fox.grow('#Adjective').grow('#Verb');
console.log(fullPhrase.out('text')); // 'quick brown fox jumps'

// Complex growth patterns
const verb = doc.match('#Verb');
const verbPhrase = verb.growLeft('#Adverb?').growRight('#Adverb?');
console.log(verbPhrase.out('text')); // 'jumps high'

/**
 * Turn a match-string into parsed JSON objects
 * @param match - Match string to parse
 * @param opts - Parsing options
 * @returns Parsed match object
 */
parseMatch(match: string, opts?: object): ParsedMatch;

/**
 * Compile a set of match objects to optimized form
 * @param matches - Array of match objects
 * @returns Compiled Net object for efficient matching
 */
buildNet(matches: Match[]): Net;

/**
 * Apply a sequence of match objects to the document
 * @param net - Compiled match network
 * @param opts - Sweep options
 * @returns Object with view and found matches
 */
sweep(net: Net, opts?: object): { view: View, found: object[] };

// Parse match strings into structured format
const parsed = nlp.parseMatch('#Adjective+ #Noun');
console.log(parsed); // [{ tag: 'Adjective', ... }, { tag: 'Noun', ... }]

// Compile multiple patterns for efficient matching
const patterns = [
  { match: '#Person #Verb', tag: 'PersonAction' },
  { match: '#Adjective+ #Noun', tag: 'DescribedThing' },
  { match: '#Verb #Preposition #Place', tag: 'Movement' }
];

const net = nlp.buildNet(patterns);
const doc = nlp("John walks to Paris with a red bag");

// Apply compiled patterns
const results = doc.sweep(net);
console.log(results.found); // Array of matched patterns with their tags

/**
 * Return all matches without duplicates
 * @param pattern - Pattern to union with current matches
 * @returns View with combined matches
 */
union(pattern: string | Net | ParsedMatch): View;
and(pattern: string | Net | ParsedMatch): View; // alias

/**
 * Return only overlapping matches
 * @param pattern - Pattern to intersect with current matches
 * @returns View with overlapping matches only
 */
intersection(pattern: string | Net | ParsedMatch): View;

/**
 * Return all results except for this pattern
 * @param pattern - Pattern to exclude
 * @param options - Matching options
 * @returns View with pattern excluded
 */
not(pattern: string | Net | ParsedMatch, options?: object): View;
difference(pattern: string | Net | ParsedMatch, options?: object): View; // alias

/**
 * Get everything that is not a match
 * @param pattern - Pattern to complement
 * @returns View with everything except pattern
 */
complement(pattern: string | Net | ParsedMatch): View;

const doc = nlp("The red car and blue truck were fast vehicles");

// Union - combine different patterns
const coloredThings = doc.match('#Adjective #Noun').union('#Vehicle');
console.log(coloredThings.out('array')); // ['red car', 'blue truck', 'vehicles']

// Intersection - find overlapping matches
const redThings = doc.match('#Adjective #Noun');
const vehicles = doc.match('#Vehicle');
const redVehicles = redThings.intersection('#Vehicle');
console.log(redVehicles.out('array')); // ['red car']

// Exclusion - remove specific patterns
const nonVehicles = doc.not('#Vehicle');
console.log(nonVehicles.out('text')); // text without vehicle words

// Complement - get everything else
const notAdjectives = doc.complement('#Adjective');
console.log(notAdjectives.out('array')); // all non-adjective words

// Pattern matching input types
type Matchable = string | View | Net | ParsedMatch;

// Matching options
interface MatchOptions {
  fuzzy?: number;
  caseSensitive?: boolean;
}

// Parsed match object structure
interface ParsedMatch extends Array<object> {}

// Compiled match network
interface Net {
  hooks: object;
  always?: any;
  isNet: boolean;
}

// Individual match definition
interface Match {
  match: string;
  tag?: string | string[];
  unTag?: string | string[];
  group?: string | number;
  reason?: string;
  freeze?: boolean;
}

// Sweep operation result
interface SweepResult {
  view: View;
  found: object[];
}