0
# Plugin System
1

2
Extensible plugin architecture for adding custom functionality and extending existing classes. The plugin system allows developers to add new methods to any nlp_compromise class or modify the internal lexicon.
3

4
## Capabilities
5

6
### Plugin Function
7

8
Core function for registering plugins that extend nlp_compromise functionality.
9

10
```javascript { .api }
11
/**
12
 * Register a plugin to extend nlp_compromise functionality
13
 * @param {object|function} obj - Plugin object or function
14
 */
15
function plugin(obj): void;
16
```
17

18
### Plugin Structure
19

20
Plugins can extend any of the core classes by providing method objects:
21

22
```javascript { .api }
23
// Plugin object structure
24
const pluginObject = {
25
  Term: {
26
    // Methods to add to Term class
27
    customMethod(): any;
28
  },
29
  Text: {
30
    // Methods to add to Text class
31
    customTextMethod(): any;
32
  },
33
  Sentence: {
34
    // Methods to add to Sentence class
35
    customSentenceMethod(): any;
36
  },
37
  Noun: {
38
    // Methods to add to Noun class
39
    customNounMethod(): any;
40
  },
41
  Verb: {
42
    // Methods to add to Verb class
43
    customVerbMethod(): any;
44
  },
45
  // ... other classes
46
};
47
```
48

49
### Function-Based Plugins
50

51
Plugins can also be functions that receive the nlp instance and return method objects:
52

53
```javascript { .api }
54
/**
55
 * Function-based plugin that receives nlp instance
56
 * @param {object} nlp - The nlp_compromise instance
57
 * @returns {object} Plugin methods object
58
 */
59
function pluginFunction(nlp) {
60
  return {
61
    Term: {
62
      customMethod() {
63
        // Access to nlp instance and this (Term instance)
64
        return this.text + ' custom';
65
      }
66
    }
67
  };
68
}
69
```
70

71
**Usage Examples:**
72

73
```javascript
74
const nlp = require('nlp_compromise');
75

76
// Object-based plugin
77
const customPlugin = {
78
  Term: {
79
    reverse() {
80
      return this.text.split('').reverse().join('');
81
    },
82
    wordCount() {
83
      return this.text.split(' ').length;
84
    }
85
  },
86
  Text: {
87
    wordFrequency() {
88
      const words = {};
89
      this.terms().forEach(term => {
90
        const word = term.normal;
91
        words[word] = (words[word] || 0) + 1;
92
      });
93
      return words;
94
    }
95
  }
96
};
97

98
// Register the plugin
99
nlp.plugin(customPlugin);
100

101
// Use the new methods
102
const term = nlp.term('hello');
103
console.log(term.reverse()); // 'olleh'
104

105
const text = nlp.text('hello world hello');
106
console.log(text.wordFrequency()); // { hello: 2, world: 1 }
107
```
108

109
### Function-Based Plugin Examples
110

111
```javascript
112
// Function-based plugin with access to nlp instance
113
nlp.plugin(function(nlp) {
114
  return {
115
    Text: {
116
      analyze() {
117
        return {
118
          sentences: this.sentences.length,
119
          words: this.terms().length,
120
          people: this.people().length,
121
          places: this.places().length
122
        };
123
      }
124
    },
125
    Verb: {
126
      allTenses() {
127
        return {
128
          present: this.to_present(),
129
          past: this.to_past(),
130
          future: this.to_future()
131
        };
132
      }
133
    }
134
  };
135
});
136

137
// Use the function-based plugin methods
138
const text = nlp.text('John went to New York yesterday.');
139
console.log(text.analyze());
140
// { sentences: 1, words: 6, people: 1, places: 1 }
141

142
const verb = nlp.verb('run');
143
console.log(verb.allTenses());
144
// { present: 'runs', past: 'ran', future: 'will run' }
145
```
146

147
### Lexicon Function
148

149
Access and modify the internal lexicon used for part-of-speech tagging.
150

151
```javascript { .api }
152
/**
153
 * Access or modify the internal lexicon
154
 * @param {object} [obj] - Object with word->tag mappings to add
155
 * @returns {object} The lexicon object
156
 */
157
function lexicon(obj): object;
158
```
159

160
**Usage Examples:**
161

162
```javascript
163
// View current lexicon (partial)
164
const lex = nlp.lexicon();
165
console.log(lex.dog); // 'Noun'
166
console.log(lex.run); // 'Verb'
167

168
// Add custom words to lexicon
169
nlp.lexicon({
170
  'pokemon': 'Noun',
171
  'googling': 'Verb',
172
  'supercalifragilisticexpialidocious': 'Adjective'
173
});
174

175
// Test custom lexicon entries
176
const customTerm = nlp.term('pokemon');
177
console.log(customTerm.tag); // 'Noun'
178

179
const customVerb = nlp.verb('googling');
180
console.log(customVerb.tense()); // 'present'
181
```
182

183
### Available Plugin Extensions
184

185
Plugins can extend any of these classes:
186

187
```javascript { .api }
188
// Available classes for plugin extension
189
const extendableClasses = [
190
  'Term',           // Base term class
191
  'Text',           // Multi-sentence text
192
  'Sentence',       // Single sentence
193
  'Statement',      // Declarative sentence
194
  'Question',       // Interrogative sentence
195
  'Noun',           // Noun terms
196
  'Verb',           // Verb terms
197
  'Adjective',      // Adjective terms
198
  'Adverb',         // Adverb terms
199
  'Value',          // Numeric values
200
  'Person',         // Person entities
201
  'Place',          // Place entities
202
  'Date',           // Date entities
203
  'Organization'    // Organization entities
204
];
205
```
206

207
### Real-World Plugin Examples
208

209
Here are examples of useful plugins that extend nlp_compromise:
210

211
**Syllable Counter Plugin:**
212

213
```javascript
214
nlp.plugin({
215
  Term: {
216
    syllables() {
217
      // Simple syllable counting algorithm
218
      const word = this.text.toLowerCase();
219
      let count = word.match(/[aeiouy]+/g);
220
      if (count) {
221
        count = count.length;
222
        if (word.endsWith('e')) count--;
223
        if (count === 0) count = 1;
224
      } else {
225
        count = 1;
226
      }
227
      return count;
228
    }
229
  },
230
  Text: {
231
    readabilityScore() {
232
      const words = this.terms().length;
233
      const sentences = this.sentences.length;
234
      const syllables = this.terms().reduce((sum, term) => {
235
        return sum + (term.syllables ? term.syllables() : 1);
236
      }, 0);
237
      
238
      // Flesch Reading Ease formula
239
      return 206.835 - (1.015 * (words / sentences)) - (84.6 * (syllables / words));
240
    }
241
  }
242
});
243

244
// Usage
245
const text = nlp.text('The quick brown fox jumps over the lazy dog.');
246
console.log(text.readabilityScore()); // ~83 (easy to read)
247
```
248

249
**Sentiment Analysis Plugin:**
250

251
```javascript
252
nlp.plugin({
253
  Term: {
254
    sentiment() {
255
      const positive = ['good', 'great', 'excellent', 'amazing', 'wonderful'];
256
      const negative = ['bad', 'terrible', 'awful', 'horrible', 'sad'];
257
      
258
      const word = this.normal;
259
      if (positive.includes(word)) return 1;
260
      if (negative.includes(word)) return -1;
261
      return 0;
262
    }
263
  },
264
  Text: {
265
    overallSentiment() {
266
      const scores = this.terms().map(term => term.sentiment ? term.sentiment() : 0);
267
      const sum = scores.reduce((a, b) => a + b, 0);
268
      return sum / scores.length;
269
    }
270
  }
271
});
272

273
// Usage
274
const text = nlp.text('This is a great day but terrible weather.');
275
console.log(text.overallSentiment()); // Slightly negative due to "terrible"
276
```
277

278
### Plugin Development Guidelines
279

280
Best practices for developing nlp_compromise plugins:
281

282
1. **Naming**: Use descriptive method names that don't conflict with existing methods
283
2. **Context**: Remember that `this` refers to the instance of the class being extended
284
3. **Chaining**: Return `this` for methods that should be chainable
285
4. **Performance**: Avoid expensive operations in frequently called methods
286
5. **Documentation**: Document plugin methods clearly for other developers
287

288
**Plugin Template:**
289

290
```javascript
291
const myPlugin = {
292
  // Extend Term class
293
  Term: {
294
    myTermMethod() {
295
      // Access term properties: this.text, this.normal, this.tag, etc.
296
      return this; // Return this for chaining
297
    }
298
  },
299
  
300
  // Extend Text class
301
  Text: {
302
    myTextMethod() {
303
      // Access text properties: this.sentences, this.raw_text, etc.
304
      return this; // Return this for chaining
305
    }
306
  }
307
  
308
  // Add other class extensions as needed
309
};
310

311
// Register the plugin
312
nlp.plugin(myPlugin);
313
```