docs(*): complete JSDoc for tokens.propagateNegations

docs-toc.yml

@@ -28,6 +28,7 @@ toc:
   - name: tokens
   - tokens.bow
   - tokens.phonetize
+  - tokens.propagateNegations
   - tokens.removeWords
   - tokens.soundex
   - tokens.sow

docs/index.html

@@ -314,6 +314,16 @@ <h3 class='mb0 no-anchor'>wink-nlp-utils</h3>
                 </li>
 
 
+                <li><a
+                  href='#tokenspropagatenegations'
+                  class="">
+                  tokens.propagateNegations
+
+                </a>
+
+                </li>
+
+
                 <li><a
                   href='#tokensremovewords'
                   class="">
@@ -2831,6 +2841,101 @@ <h3 class='fl m0' id='tokensphonetize'>
 
 
 
+</section>
+
+
+
+
+            <section class='p2 mb2 clearfix bg-white minishadow'>
+
+
+  <div class='clearfix'>
+
+    <h3 class='fl m0' id='tokenspropagatenegations'>
+      tokens.propagateNegations
+    </h3>
+
+
+  </div>
+
+
+  <p>It looks for negation tokens in the input array of tokens and propagates
+negation to subsequent <code>upto</code> tokens by prefixing them by a <code>!</code>. It is useful
+in handling text containing negations during tasks like similarity detection,
+classification or search.</p>
+
+
+  <div class='pre p1 fill-light mt0'>tokens.propagateNegations</div>
+
+
+
+
+
+
+
+
+
+
+
+    <div class='py1 quiet mt1 prose-big'>Parameters</div>
+    <div class='prose'>
+
+        <div class='space-bottom0'>
+          <div>
+            <span class='code bold'>tokens</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a>&#x3C;<a href="#string">string</a>>)</code>
+	    — the input tokens.
+
+          </div>
+
+        </div>
+
+        <div class='space-bottom0'>
+          <div>
+            <span class='code bold'>upto</span> <code class='quiet'>(<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number">number</a>
+            = <code>2</code>)</code>
+	    — number of tokens to be negated after the negation
+token. Note, tokens are only negated either 
+<code>upto</code>
+ tokens or up to the token
+preceeding the 
+<strong><code>, . ; : ! ?</code></strong>
+ punctuations.
+
+          </div>
+
+        </div>
+
+    </div>
+
+
+
+
+
+
+      <div class='py1 quiet mt1 prose-big'>Returns</div>
+      <code><a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array">Array</a>&#x3C;<a href="#string">string</a>></code>:
+        tokens with negation propagated.
+
+
+
+
+
+
+
+
+    <div class='py1 quiet mt1 prose-big'>Example</div>
+
+
+      <pre class='p1 overflow-auto round fill-light'>propagateNegations( [ <span class="hljs-string">'mary'</span>, <span class="hljs-string">'is'</span>, <span class="hljs-string">'not'</span>, <span class="hljs-string">'feeling'</span>, <span class="hljs-string">'good'</span>, <span class="hljs-string">'today'</span> ] );
+<span class="hljs-comment">// -&gt; [ 'mary', 'is', 'not', '!feeling', '!good', 'today' ]</span></pre>
+
+
+
+
+
+
+
+
 </section>
 
 

src/tokens-propagate-negations.js

@@ -0,0 +1,66 @@
+//     wink-nlp-utils
+//     NLP Functions for removing HTML Tags, Managing Elisions,
+//     propagateNegationss, Stemming, Phoneticising to Tokenizating and more.
+//
+//     Copyright (C) 2017  GRAYPE Systems Private Limited
+//
+//     This file is part of “wink-nlp-utils”.
+//
+//     “wink-nlp-utils” is free software: you can redistribute it
+//     and/or modify it under the terms of the GNU Affero
+//     General Public License as published by the Free
+//     Software Foundation, version 3 of the License.
+//
+//     “wink-nlp-utils” is distributed in the hope that it will
+//     be useful, but WITHOUT ANY WARRANTY; without even
+//     the implied warranty of MERCHANTABILITY or FITNESS
+//     FOR A PARTICULAR PURPOSE.  See the GNU Affero General
+//     Public License for more details.
+//
+//     You should have received a copy of the GNU Affero
+//     General Public License along with “wink-nlp-utils”.
+//     If not, see <http://www.gnu.org/licenses/>.
+
+//
+var rgx = require( './util_regexes.js' );
+
+// ## string
+
+// ### propagateNegations
+/**
+ *
+ * It looks for negation tokens in the input array of tokens and propagates
+ * negation to subsequent `upto` tokens by prefixing them by a `!`. It is useful
+ * in handling text containing negations during tasks like similarity detection,
+ * classification or search.
+ *
+ * @name tokens.propagateNegations
+ * @param {string[]} tokens — the input tokens.
+ * @param {number} [upto=2] — number of tokens to be negated after the negation
+ * token. Note, tokens are only negated either `upto` tokens or up to the token
+ * preceeding the **`, . ; : ! ?`** punctuations.
+ * @return {string[]} tokens with negation propagated.
+ * @example
+ * propagateNegations( [ 'mary', 'is', 'not', 'feeling', 'good', 'today' ] );
+ * // -> [ 'mary', 'is', 'not', '!feeling', '!good', 'today' ]
+ */
+var propagateNegations = function ( tokens, upto ) {
+  var i, imax, j, jmax;
+  var tkns = tokens;
+  var limit = upto || 2;
+  for ( i = 0, imax = tkns.length; i < imax; i += 1 ) {
+    if ( rgx.negations.test( tkns[ i ] ) ) {
+      for ( j = i + 1, jmax = Math.min( imax, i + limit + 1 ); j < jmax; j += 1 ) {
+        // Hit a punctuation mark, break out of the loop otherwise go *upto the limit*.
+        // > TODO: promote to utilities regex, after test cases have been added.
+        if ( /[\,\.\;\:\!\?]/.test( tkns[ j ] ) ) break;
+        // Propoage negation: invert the token by prefixing a `!` to it.
+        tkns[ j ] = '!' + tkns[ j ];
+      }
+      i = j;
+    }
+  }
+  return tkns;
+}; // propagateNegations()
+
+module.exports = propagateNegations;

src/wink-nlp-utils.js

@@ -22,7 +22,7 @@
 //     If not, see <http://www.gnu.org/licenses/>.
 
 //
-var rgx = require( './util_regexes.js' );
+// var rgx = require( './util_regexes.js' );
 // var ncrgx = require( './name_cleaner_regexes.js' );
 var porter2Stemmer = require( 'wink-porter2-stemmer' );
 // var phnrgx = require( './phonetize_regexes.js' );
@@ -299,24 +299,7 @@ prepare.tokens.sow = require( './tokens-sow.js' );
 
 // It looks for neagtion tokens in `t` and propagate negation in subsequent `upto`
 // tokens by prefixing them by a `!`.
-prepare.tokens.propagateNegations = function ( t, upto ) {
-  var i, imax, j, jmax;
-  var tokens = t;
-  var limit = upto || 2;
-  for ( i = 0, imax = tokens.length; i < imax; i += 1 ) {
-    if ( rgx.negations.test( tokens[ i ] ) ) {
-      for ( j = i + 1, jmax = Math.min( imax, i + limit + 1 ); j < jmax; j += 1 ) {
-        // Hit a punctuation mark, break out of the loop otherwise go *upto the limit*.
-        // > TODO: promote to utilities regex, after test cases have been added.
-        if ( /[\,\.\;\:\!\?]/.test( tokens[ j ] ) ) break;
-        // Propoage negation: invert the token by prefixing a `!` to it.
-        tokens[ j ] = '!' + tokens[ j ];
-      }
-      i = j;
-    }
-  }
-  return tokens;
-}; // propagateNegations()
+prepare.tokens.propagateNegations = require( './tokens-propagate-negations.js' );
 
 // #### Bigrams