regexp: add S.replaceWith and S.replaceBy

.circleci/config.yml

@@ -28,7 +28,7 @@ jobs:
               nvm exec $1 npm test
             }
             case $CIRCLE_NODE_INDEX in
-              0) test_with_version 8 ;;
-              1) test_with_version 10 ;;
-              2) npm install && npm test ;;
+              0) test_with_version 10 ;;
+              1) npm install && npm test ;;
+              2) test_with_version 14 ;;
             esac

index.js

@@ -1731,12 +1731,12 @@
   //. Curries the given ternary function.
   //.
   //. ```javascript
-  //. > const replaceString = S.curry3 ((what, replacement, string) =>
-  //. .   string.replace (what, replacement)
-  //. . )
+  //. > const defineProperty = S.curry3 (Object.defineProperty)
+  //.
+  //. > const o = defineProperty ({}) ('x') ({value: 42, writable: false})
   //.
-  //. > replaceString ('banana') ('orange') ('banana icecream')
-  //. 'orange icecream'
+  //. > o.x
+  //. 42
   //. ```
   function curry3(f) {
     return function(x) {
@@ -4548,6 +4548,83 @@
     impl: matchAll
   };
 
+  //# replaceWith :: String -> RegExp -> String -> String
+  //.
+  //. Replaces occurrences of the given pattern with the given replacement
+  //. within the given string. Replaces all occurrences of the pattern if
+  //. its `g` flag is set; just the first occurrence otherwise.
+  //.
+  //. See also [`replaceBy`](#replaceBy).
+  //.
+  //. ```javascript
+  //. > S.replaceWith ('x') (/o/) ('foo')
+  //. 'fxo'
+  //.
+  //. > S.replaceWith ('x') (/o/g) ('foo')
+  //. 'fxx'
+  //. ```
+  function replaceWith(replacement) {
+    return function(pattern) {
+      return function(text) {
+        return text.replace (pattern, function() { return replacement; });
+      };
+    };
+  }
+  _.replaceWith = {
+    consts: {},
+    types: [$.String, $.RegExp, $.String, $.String],
+    impl: replaceWith
+  };
+
+  //# replaceBy :: (Array (Maybe String) -> String) -> RegExp -> String -> String
+  //.
+  //. Replaces occurrences of the given pattern within the given string
+  //. in accordance with the given replacement function, which receives an
+  //. array of captured values. Replaces all occurrences of the pattern if
+  //. its `g` flag is set; just the first occurrence otherwise.
+  //.
+  //. See also [`replaceWith`](#replaceWith).
+  //.
+  //. ```javascript
+  //. > S.replaceBy (([$1]) => S.maybe ('') (S.toUpper) ($1)) (/(\w)/) ('foo')
+  //. 'Foo'
+  //.
+  //. > S.replaceBy (([$1]) => S.maybe ('') (S.toUpper) ($1)) (/(\w)/g) ('foo')
+  //. 'FOO'
+  //.
+  //. > S.replaceBy (S.show) (/(foo)(bar)?/) ('<>')
+  //. '<>'
+  //.
+  //. > S.replaceBy (S.show) (/(foo)(bar)?/) ('<foo>')
+  //. '<[Just ("foo"), Nothing]>'
+  //.
+  //. > S.replaceBy (S.show) (/(foo)(bar)?/) ('<foobar>')
+  //. '<[Just ("foo"), Just ("bar")]>'
+  //. ```
+  function replaceBy(substitute) {
+    return function(pattern) {
+      return function(text) {
+        return text.replace (pattern, function() {
+          var groups = [];
+          var group, idx = 1;
+          //  eslint-disable-next-line no-plusplus
+          while (typeof (group = arguments[idx++]) !== 'number') {
+            groups.push (group == null ? Nothing : Just (group));
+          }
+          return substitute (groups);
+        });
+      };
+    };
+  }
+  _.replaceBy = {
+    consts: {},
+    types: [$.Fn ($.Array ($.Maybe ($.String))) ($.String),
+            $.RegExp,
+            $.String,
+            $.String],
+    impl: replaceBy
+  };
+
   //. ### String
 
   //# toUpper :: String -> String

test/.eslintrc.json

@@ -1,9 +1,11 @@
 {
   "root": true,
   "extends": ["../node_modules/sanctuary-style/eslint-es6.json"],
+  "parserOptions": {"ecmaVersion": 2018},
   "env": {"node": true},
   "globals": {"suite": false, "test": false},
   "rules": {
+    "comma-dangle": ["error", {"arrays": "always-multiline", "objects": "always-multiline", "functions": "never"}],
     "max-len": ["off"]
   }
 }

test/replaceBy.js

@@ -0,0 +1,19 @@
+'use strict';
+
+const S = require ('..');
+
+const eq = require ('./internal/eq');
+
+
+test ('replaceBy', () => {
+
+  eq (S.show (S.replaceBy)) ('replaceBy :: (Array (Maybe String) -> String) -> RegExp -> String -> String');
+
+  eq (S.replaceBy (([$1]) => S.maybe ('') (S.toUpper) ($1)) (/(\w)/) ('foo')) ('Foo');
+  eq (S.replaceBy (([$1]) => S.maybe ('') (S.toUpper) ($1)) (/(\w)/g) ('foo')) ('FOO');
+  eq (S.replaceBy (S.show) (/(foo)(bar)?/) ('<>')) ('<>');
+  eq (S.replaceBy (S.show) (/(foo)(bar)?/) ('<foo>')) ('<[Just ("foo"), Nothing]>');
+  eq (S.replaceBy (S.show) (/(foo)(bar)?/) ('<foobar>')) ('<[Just ("foo"), Just ("bar")]>');
+  eq (S.replaceBy (S.show) (/@(?<username>[-\w]+)/) ('@sanctuary-js')) ('[Just ("sanctuary-js")]');
+
+});

test/replaceWith.js

@@ -0,0 +1,21 @@
+'use strict';
+
+const S = require ('..');
+
+const eq = require ('./internal/eq');
+
+
+test ('replaceWith', () => {
+
+  eq (S.show (S.replaceWith)) ('replaceWith :: String -> RegExp -> String -> String');
+
+  eq (S.replaceWith ('x') (/o/) ('<bar>')) ('<bar>');
+  eq (S.replaceWith ('x') (/o/) ('<foo>')) ('<fxo>');
+  eq (S.replaceWith ('x') (/o/g) ('<bar>')) ('<bar>');
+  eq (S.replaceWith ('x') (/o/g) ('<foo>')) ('<fxx>');
+  eq (S.replaceWith ('$1') (/(o)/) ('<bar>')) ('<bar>');
+  eq (S.replaceWith ('$1') (/(o)/) ('<foo>')) ('<f$1o>');
+  eq (S.replaceWith ('$1') (/(o)/g) ('<bar>')) ('<bar>');
+  eq (S.replaceWith ('$1') (/(o)/g) ('<foo>')) ('<f$1$1>');
+
+});