From 8476e77c421cf08c95aabfba4802179c045e7396 Mon Sep 17 00:00:00 2001 From: Lloyd Brookes Date: Sat, 1 May 2021 12:49:09 +0100 Subject: [PATCH] docs --- README.md | 6 ++- docs/API.md | 68 +++++++++++++++++---------------- example/api/result-iterator.mjs | 2 +- index.mjs | 6 +-- lib/cli-app.mjs | 2 +- lib/cli-options.mjs | 2 +- 6 files changed, 46 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index 77b7944..6dac318 100644 --- a/README.md +++ b/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. + ## Further reading diff --git a/docs/API.md b/docs/API.md index 6fba226..699c112 100644 --- a/docs/API.md +++ b/docs/API.md @@ -1,50 +1,54 @@ - - ## 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 - +### Renamer -### Renamer ⏏ **Kind**: Exported class - -#### renamer.rename(options) -A synchronous method to rename files in bulk. +#### [async] renamer.rename(options):`Array` -**Kind**: instance method of [Renamer](#exp_module_renamer--Renamer) -**Emits**: [replace-result](#module_renamer--Renamer+event_replace-result) +An asynchronous method to rename files in bulk. -| 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 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] | 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. | +**Kind**: Async instance method of [`Renamer`](#exp_module_renamer--Renamer) + +#### [async] renamer.results(options):`iterator` - +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 [Renamer](#exp_module_renamer--Renamer) -**Properties** +Contains information about the completed replace. + +**Kind**: Internal type +**Properties:** | Name | Type | Description | | --- | --- | --- | -| from | string | The filename before rename. | -| to | string | The filename after rename. | -| renamed | boolean | 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.` | 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.` | 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. | diff --git a/example/api/result-iterator.mjs b/example/api/result-iterator.mjs index cd075bb..7741115 100644 --- a/example/api/result-iterator.mjs +++ b/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) } diff --git a/index.mjs b/index.mjs index de0277a..70d3959 100644 --- a/index.mjs +++ b/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) diff --git a/lib/cli-app.mjs b/lib/cli-app.mjs index 06246f2..903147d 100644 --- a/lib/cli-app.mjs +++ b/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) } diff --git a/lib/cli-options.mjs b/lib/cli-options.mjs index 9c13540..5a330e4 100755 --- a/lib/cli-options.mjs +++ b/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',