docs, more tests

docs/API.md

@@ -12,13 +12,13 @@ Rename files in bulk.
 
 **Kind**: Exported class
 
-#### [async] renamer.rename(options):`Array<ReplaceResult>`
+#### [async] renamer.rename(options:`RenamerOptions`):`Array<ReplaceResult>`
 
 An asynchronous method to rename files in bulk.
 
 **Kind**: Async instance method of [`Renamer`](#exp_module_renamer--Renamer)
 
-#### [async] renamer.results(options):`iterator`
+#### [async iterator] renamer.results(options:`RenamerOptions`):`ReplaceResult`
 
 An asynchronous generator function for iterating through the process one rename at a time. Each iteration yields a `ReplaceResult` object.
 

example/api/index-replace.mjs

@@ -1,9 +1,10 @@
-import Renamer from '../index.mjs'
+import Renamer from '../../index.mjs'
 
 const renamer = new Renamer()
 const results = await renamer.rename({
   files: ['./example/sandbox/**'],
   replace: '{{index}}.file',
-  dryRun: true
+  dryRun: true,
+  chain: 'find-replace'
 })
 console.log('results', results)

index.mjs

@@ -47,7 +47,7 @@ class Renamer {
   async * results (options = {}) {
     const files = expandGlobPatterns(arrayify(options.files))
     const replaceChain = new ReplaceChain()
-    await replaceChain.loadPlugins(options.plugin)
+    await replaceChain.loadPlugins(options.chain)
     const replaceResults = files
       .map((file, index) => replaceChain.replace(file, options, index, files))
     if (!options.dryRun) {

lib/cli-options.mjs

@@ -32,7 +32,7 @@ const optionDefinitions = [
     renamer --chain index-replace.mjs --chain ./test/lib/dummy-plugin.mjs *.mjs -d
     */
     lazyMultiple: true,
-    description: 'One or more replacer plugins to use, set the `--chain` option multiple times to build a chain. For each value, supply either: a) a path to a plugin file b) a path to a plugin package c) the name of a plugin package installed globally or in the current working directory (or above) or d) the name of a built-in plugin, either `default` or `index`. The default plugin chain is `default` then `index`, be sure to set `-p default -p index` before your plugin if you wish to extend default behaviour.',
+    description: 'One or more replace chain plugins to use, set the `--chain` option multiple times to build a chain. For each value, supply either: a) a path to a plugin file b) a path to an installed plugin package or c) the name of a built-in plugin, either `find-replace` or `index-replace`. The default plugin chain is `find-replace` then `index-replace`.',
     plugin: true
   },
   {

lib/util.mjs

@@ -7,6 +7,8 @@ import arrayify from 'array-back'
 import * as t from 'typical/index.mjs'
 import { loadModuleResolvedFrom, loadModuleRelativeTo } from 'load-module'
 import flatten from 'reduce-flatten'
+import FindReplace from './chain/find-replace.mjs'
+import IndexReplace from './chain/index-replace.mjs'
 import getModulePaths from 'current-module-paths'
 const __dirname = getModulePaths(import.meta.url).__dirname
 
@@ -63,7 +65,11 @@ export async function loadPlugins (pluginNames) {
   const plugins = []
   for (const pluginName of arrayify(pluginNames)) {
     let PluginClass
-    if (typeof pluginName === 'string') {
+    if (pluginName === 'find-replace') {
+      plugins.push(new FindReplace())
+    } else if (pluginName === 'index-replace') {
+      plugins.push(new IndexReplace())
+    } else if (typeof pluginName === 'string') {
       /* look for user-installed plugin */
       PluginClass = await loadModuleResolvedFrom(pluginName, process.cwd())
       if (PluginClass === null) {

test/api-find-replace.mjs

@@ -25,6 +25,33 @@ tom.test('simple rename', async function () {
   a.equal(fs.existsSync(`${testRoot}/${this.index}/ane`), true)
 })
 
+tom.test('simple rename, just find-replace in the chain', async function () {
+  const fixturePath = createFixture(`${testRoot}/${this.index}/one`)
+  const renamer = new Renamer()
+  const options = {
+    files: [fixturePath],
+    find: 'o',
+    replace: 'a',
+    chain: 'find-replace'
+  }
+  await renamer.rename(options)
+  a.equal(fs.existsSync(`${testRoot}/${this.index}/one`), false)
+  a.equal(fs.existsSync(`${testRoot}/${this.index}/ane`), true)
+})
+
+tom.test('no find-replace in chain, not renamed', async function () {
+  const fixturePath = createFixture(`${testRoot}/${this.index}/one`)
+  const renamer = new Renamer()
+  const options = {
+    files: [fixturePath],
+    find: 'o',
+    replace: 'a',
+    chain: 'index-replace'
+  }
+  a.equal(fs.existsSync(`${testRoot}/${this.index}/one`), true)
+  a.equal(fs.existsSync(`${testRoot}/${this.index}/ane`), false)
+})
+
 tom.test('nothing found', async function () {
   const fixturePath = createFixture(`${testRoot}/${this.index}/one`)
   const renamer = new Renamer()

test/api-plugin-custom.mjs

@@ -34,7 +34,7 @@ tom.test('simple', async function () {
   const renamer = new Renamer()
   const options = {
     files: [`${testFolder}/one`, `${testFolder}/two`],
-    plugin: [Plugin]
+    chain: [Plugin]
   }
   await renamer.rename(options)
   a.equal(assertionCount, 2)
@@ -65,7 +65,7 @@ tom.test('chain of two plugins', async function () {
   const renamer = new Renamer()
   const options = {
     files: [`${testFolder}/one`],
-    plugin: [Plugin, Plugin2]
+    chain: [Plugin, Plugin2]
   }
   await renamer.rename(options)
   a.equal(assertionCount, 2)
@@ -79,7 +79,7 @@ tom.test('invalid plugin, no .replace() function', async function () {
   const renamer = new Renamer()
   const options = {
     files: ['one'],
-    plugin: [InvalidPlugin]
+    chain: [InvalidPlugin]
   }
   await a.rejects(
     () => renamer.rename(options),
@@ -92,7 +92,7 @@ tom.test('invalid plugin, function doesn\'t return class', async function () {
   const renamer = new Renamer()
   const options = {
     files: ['one'],
-    plugin: [InvalidPlugin]
+    chain: [InvalidPlugin]
   }
   await a.rejects(
     () => renamer.rename(options),