Merge pull request #1 from rmtuckerphx/custom-lists

Resolve kylestetz#16

README.md

@@ -41,6 +41,27 @@ Sentencer.configure({
   // the list of adjectives to use. Again, Sentencer comes with one!
   adjectiveList: [],
 
+  // additional lists that generate actions for the template engine to use.
+  customLists: [
+    {
+      // add action for animal
+      key: "animal",
+      values: ["dog", "cat", "elephant"],
+      // if named, add action for articlize
+      articlize: "an_animal",
+      // if named, add action for pluralize
+      pluralize: "animals"
+    },
+    {
+        key: "band",
+        values: ["The Beatles", "The Who", "Styx"],
+        // no key or empty value, don't articlize
+        articlize: "",
+        // no key or empty value, don't pluralize
+        pluralize: ""
+    }
+  ],
+
   // additional actions for the template engine to use.
   // you can also redefine the preset actions here if you need to.
   // See the "Add your own actions" section below.
@@ -145,6 +166,29 @@ console.log( Sentencer.make("I can count to {{ number(8, 10) }}.")
 // "I can count to 8."
 ```
 
+### Add your own custom lists
+When configuring `Sentencer` you can provide your own custom lists, which are converted to "actions". The `key` sets the name of the action and the `values` the list of values where one is selected when the action is called. You can also specify a name for the `articlize` and/or `pluralize` actions. These names are referenced within a sentence template.
+
+Here is an example of an animal list that includes options to prefix with an article or to make it plural.
+
+```javascript
+var Sentencer = require('sentencer');
+
+Sentencer.configure({
+  customLists: [
+    {
+        key: "animal",
+        values: ["dog", "cat", "elephant"],
+        articlize: "an_animal",
+        pluralize: "animals"
+    }
+  ],
+});
+
+console.log( Sentencer.make("I saw {{ an_animal }}, 1 {{ animal }}, and 2 {{ animals }}.")
+// "I saw an elephant, 1 dog, and 2 cats."
+```
+
 ### Where are the verbs?
 
 Verb pluralization, singularization, and tense modification are difficult computer science problems. `Sentencer` doesn't aim to solve those problems, however _present tense_ verb pluralization/singularization is an experimental feature of [`natural`](https://github.com/NaturalNode/natural) and could be integrated if necessary.

index.js

@@ -11,36 +11,58 @@ var _ = require('lodash');
 function Sentencer() {
   var self = this;
 
-  self._nouns      = require('./words/nouns.js');
+  self._nouns = require('./words/nouns.js');
   self._adjectives = require('./words/adjectives.js');
 
   self.actions = {
-    noun: function() {
+    noun: function () {
       return randy.choice(self._nouns);
     },
-    a_noun: function() {
-      return articles.articlize( self.actions.noun() );
+    a_noun: function () {
+      return articles.articlize(self.actions.noun());
     },
-    nouns: function() {
-      return nounInflector.pluralize( randy.choice(self._nouns) );
+    nouns: function () {
+      return nounInflector.pluralize(randy.choice(self._nouns));
     },
-    adjective: function() {
+    adjective: function () {
       return randy.choice(self._adjectives);
     },
-    an_adjective: function() {
-      return articles.articlize( self.actions.adjective() );
+    an_adjective: function () {
+      return articles.articlize(self.actions.adjective());
     }
   };
 
-  self.configure = function(options) {
+  // function definitions
+  self._func_normal = function(values) {
+    return randy.choice(values);
+  }
+  self._func_articlize = function(name) {
+    return articles.articlize( self.actions[name]() );
+  }
+  self._func_pluralize = function(values) {
+    return nounInflector.pluralize( randy.choice(values) );
+  }
+
+  self.configure = function (options) {
     // merge actions
-    self.actions     = _.merge(self.actions, options.actions || {});
+    self.actions = _.merge(self.actions, options.actions || {});
     // overwrite nouns and adjectives if we got some
-    self._nouns      = options.nounList || self._nouns;
+    self._nouns = options.nounList || self._nouns;
     self._adjectives = options.adjectiveList || self._adjectives;
+    self._customLists = options.customLists || [];
+
+    self._customLists.forEach(item => {
+      self.actions[item.key] = self._func_normal.bind(null, item.values);
+      if (item.articlize) {
+        self.actions[item.articlize] = self._func_articlize.bind(null, item.key);
+      }
+      if (item.pluralize) {
+        self.actions[item.pluralize] = self._func_pluralize.bind(null, item.values);
+      }
+    });
   };
 
-  self.use = function(options) {
+  self.use = function (options) {
     var newInstance = new Sentencer();
     newInstance.configure(options);
     return newInstance;
@@ -51,19 +73,19 @@ function Sentencer() {
 //                  THE GOODS
 // ---------------------------------------------
 
-Sentencer.prototype.make = function(template) {
+Sentencer.prototype.make = function (template) {
   var self = this;
 
   var sentence = template;
   var occurrences = template.match(/\{\{(.+?)\}\}/g);
 
-  if(occurrences && occurrences.length) {
-    for(var i = 0; i < occurrences.length; i++) {
+  if (occurrences && occurrences.length) {
+    for (var i = 0; i < occurrences.length; i++) {
       var action = occurrences[i].replace('{{', '').replace('}}', '').trim();
       var result = '';
       var actionIsFunctionCall = action.match(/^\w+\((.+?)\)$/);
 
-      if(actionIsFunctionCall) {
+      if (actionIsFunctionCall) {
         var actionNameWithParens = action.match(/^(\w+)\(/);
         var actionName = actionNameWithParens[1];
         var actionExists = self.actions[actionName];
@@ -75,10 +97,10 @@ Sentencer.prototype.make = function(template) {
             var args = _.map(actionContents.split(','), maybeCastToNumber);
             result = self.actions[actionName].apply(null, args);
           }
-          catch(e) { }
+          catch (e) { }
         }
       } else {
-        if(self.actions[action]) {
+        if (self.actions[action]) {
           result = self.actions[action]();
         } else {
           result = '{{ ' + action + ' }}';