docs

README.md

@@ -39,7 +39,7 @@ As above but operates on all files and folders recursively.
 $ renamer --find jpeg --replace jpg "**"
 ```
 
-### Fine-tune which files are processed
+### Fine-tune which files to process
 
 If no filenames or patterns are specified, renamer will look for a newline-separated list of filenames on standard input. This approach is useful for crafting a specific input list using tools like `find`. This example operates on files modified less than 20 minutes ago.
 
@@ -71,7 +71,7 @@ $ renamer --find "/one/i" --replace "two" ONE.jpg
 
 ### Rename using JavaScript
 
-For more complex renames, or if you just prefer using code, you can define a replace chain plugin. A plugin is a module exporting a class which defines a `replace` method. This trivial plugin appends the text `[DONE]` to each file name.
+For more complex renames, or if you just prefer using code, you can write a replace function. Create a module exporting a class which defines a `replace` method. This trivial example appends the text `[DONE]` to each file name.
 
 ```js
 import path from 'path'
@@ -102,6 +102,8 @@ Rename complete: 2 of 6 files renamed.
 
 ## Views
 
+Use the default view, a built-in alternative (long, diff, one-line) or a custom view.
+
 <img src="https://i.imgur.com/7830Y9N.gif" width="620px" title="Renamer views demo">
 
 ## Further reading

docs/API.md

@@ -1,50 +1,54 @@
-<a name="module_renamer"></a>
-
 ## renamer
-Rename files in bulk.
 
+Rename files in bulk.
 
 * [renamer](#module_renamer)
-    * [Renamer](#exp_module_renamer--Renamer) ⏏
+    * [Renamer](#exp_module_renamer--Renamer)
         * [.rename(options)](#module_renamer--Renamer+rename)
-        * ["replace-result"](#module_renamer--Renamer+event_replace-result)
+        * [.results(options)](#asdf)
+        * ReplaceResult
 
-<a name="exp_module_renamer--Renamer"></a>
+### Renamer
 
-### Renamer ⏏
 **Kind**: Exported class
-<a name="module_renamer--Renamer+rename"></a>
 
-#### renamer.rename(options)
-A synchronous method to rename files in bulk.
+#### [async] renamer.rename(options):`Array<ReplaceResult>`
 
-**Kind**: instance method of [<code>Renamer</code>](#exp_module_renamer--Renamer)
-**Emits**: [<code>replace-result</code>](#module_renamer--Renamer+event_replace-result)
+An asynchronous method to rename files in bulk.
 
-| Param | Type | Description |
-| --- | --- | --- |
-| options | <code>object</code> | The renamer options |
-| [options.files] | <code>Array.&lt;string&gt;</code> | One or more glob patterns or filenames to process. |
-| [options.dryRun] | <code>boolean</code> | Set this to do everything but rename the file. You should always set this flag until certain the output looks correct. |
-| [options.force] | <code>boolean</code> | If a target path exists, renamer will stop. With this flag set the target path will be overwritten. The main use-case for this flag is to enable changing the case of files on case-insensitive systems. Use with caution. |
-| [options.chain] | <code>Array.&lt;string&gt;</code> | 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. |
-| [options.find] | <code>sting</code> \| <code>RegExp</code> | Optional find string (e.g. `one`) or regular expression literal (e.g. `/one/i`). If omitted, the whole filename will be matched and replaced. |
-| [options.replace] | <code>string</code> | The replace string. If omitted, defaults to a empty string. |
-| [options.pathElement] | <code>string</code> | The path element to rename, valid values are `base` (the default), `name` and `ext`. For example, in the path `pics/image.jpg`, the base is `image.jpg`, the name is `image` and the ext is `.jpg`. |
-| [options.indexFormat] | <code>string</code> | The format of the number to replace `{{index}}` with. Specify a standard printf format string, for example `%03d` would yield 001, 002, 003 etc. Defaults to `%d`. |
-| [options.indexRoot] | <code>string</code> | The initial value for `{{index}}`. Defaults to 1. |
+**Kind**: Async instance method of [`Renamer`](#exp_module_renamer--Renamer)
+
+#### [async] renamer.results(options):`iterator`
 
-<a name="module_renamer--Renamer+event_replace-result"></a>
+An asynchronous generator function for iterating through the process one rename at a time. Each iteration yields a `ReplaceResult` object.
 
-#### "replace-result"
-Emitted just before each file is processed.
+#### Type: ReplaceResult
 
-**Kind**: event emitted by [<code>Renamer</code>](#exp_module_renamer--Renamer)
-**Properties**
+Contains information about the completed replace.
+
+**Kind**: Internal type  
+**Properties:**
 
 | Name | Type | Description |
 | --- | --- | --- |
-| from | <code>string</code> | The filename before rename. |
-| to | <code>string</code> | The filename after rename. |
-| renamed | <code>boolean</code> | True if the file was renamed. |
+| from | `string` | The filename before rename. |
+| to | `string` | The filename after rename. |
+| renamed | `boolean` | True if the file was renamed. |
+
+#### Type: RenamerOptions
+
+**Kind**: Internal type  
+**Properties:**
 
+| Param | Type | Description |
+| --- | --- | --- |
+| options | `object` | The renamer options |
+| [options.files] | `Array.<string>` | One or more glob patterns or filenames to process. |
+| [options.dryRun] | `boolean` | Set this to do everything but rename the file. You should always set this flag until certain the output looks correct. |
+| [options.force] | `boolean` | If a target path exists, renamer will stop. With this flag set the target path will be overwritten. The main use-case for this flag is to enable changing the case of files on case-insensitive systems. Use with caution. |
+| [options.chain] | `Array.<string>` | 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`. |
+| [options.find] | `sting` \| `RegExp` | Optional find string (e.g. `one`) or regular expression literal (e.g. `/one/i`). If omitted, the whole filename will be matched and replaced. |
+| [options.replace] | `string` | The replace string. If omitted, defaults to a empty string. |
+| [options.pathElement] | `string` | The path element to rename, valid values are `base` (the default), `name` and `ext`. For example, in the path `pics/image.jpg`, the base is `image.jpg`, the name is `image` and the ext is `.jpg`. |
+| [options.indexFormat] | `string` | The format of the number to replace `{{index}}` with. Specify a standard printf format string, for example `%03d` would yield 001, 002, 003 etc. Defaults to `%d`. |
+| [options.indexRoot] | `string` | The initial value for `{{index}}`. Defaults to 1. |

example/api/result-iterator.mjs

@@ -7,6 +7,6 @@ const options = {
   replace: 'photo',
   dryRun: true
 }
-for await (const result of renamer.resultIterator(options)) {
+for await (const result of renamer.results(options)) {
   console.log(result)
 }

index.mjs

@@ -34,17 +34,17 @@ class Renamer {
   */
   async rename (options = {}) {
     const results = []
-    for await (const result of this.resultIterator(options)) {
+    for await (const result of this.results(options)) {
       results.push(result)
     }
     return results
   }
 
-  /** ø renamer.resultIterator(options):iterator
+  /** ø renamer.results(options):iterator
   ≈ Useful when you want process the renames one-by-one.
   ¥ ReplaceResult
   */
-  async * resultIterator (options = {}) {
+  async * results (options = {}) {
     const files = expandGlobPatterns(arrayify(options.files))
     const replaceChain = new ReplaceChain()
     await replaceChain.loadPlugins(options.plugin)

lib/cli-app.mjs

@@ -94,7 +94,7 @@ class CliApp {
           /* rename files */
           this.view.write('start', null, this.options)
           const results = []
-          for await (const replaceResult of renamer.resultIterator(cliArgs)) {
+          for await (const replaceResult of renamer.results(cliArgs)) {
             this.view.write('result', replaceResult, this.options)
             results.push(replaceResult)
           }

lib/cli-options.mjs

@@ -21,7 +21,7 @@ const optionDefinitions = [
   {
     name: 'view',
     type: String,
-    description: 'The default view outputs one line per rename. Set `--view long` to see a longer, less condensed view and `--view diff` to include a diff.'
+    description: 'Use one of the built-in views ("long", "diff", "one-line") or supply a path to a custom view. The default view outputs one line per rename. Set `--view long` to see a longer, less condensed view and `--view diff` to include a diff. Use `--view one-line` to output the summary line only.'
   },
   {
     name: 'chain',