diff --git a/README.md b/README.md index ad28d04..8bf256a 100644 --- a/README.md +++ b/README.md @@ -6,13 +6,13 @@ > "`Pick` `l`ine & `r`eplace" > -> A simple, zero dependency, recursive, single-line text replacer. +> A simple, zero dependency, recursive, text replacer. -Use to update a specific, single line of text across multiple file types in a project. -Finds just the **first** matching line in a file, and runs a text replacement on just that one line. -Synchronous processing. +Use to update a specific text across multiple file types in a project. +Finds matching lines in files, based on text or regular expression, and runs a text replacement on just those lines matched*. +\* If you have special cases, you can supply a filter function to exclude those special cases. -You might be reading this because you're in a pickle where you have to change a line across a big project. No worries, picklr allows you to test behavior prior to any updates with actions `echo` and `audit`. It's good to see what would happen prior to any file being updated, and also what files will get omitted from the change set. +You might be reading this because you're in a pickle where you have to change a line or text pattern across a big project. No worries, picklr allows you to test replacement behavior prior to any updates with actions `echo` and `audit`. It's good to see what would happen prior to any file being updated across a project, and also what files will get omitted from the change set. ## API Picklr exports a single function that starts synchronous file processing when invoked. @@ -21,17 +21,17 @@ Picklr exports a single function that starts synchronous file processing when in ### Options A brief description of the options that control file selection and processing: - + `action` - {String} `echo|audit|update` The action taken on each file. Defaults to `echo`. Use `echo` and `audit` actions to test the results of picklr with options prior to running `update`. - + `echo` - Just output what files could be affected by a change. Tests `includeExts` and `excludeDirsRe` options. - + `audit` - Must use with `targetText` and `replacementText`. Outputs lines found and the change plus any files that would be omitted. Tests `includeExts`, `excludeDirsRe`, `targetText` and `replacementText` options. - + `update` - Does the actual update on the files in place. Use only if you have version control. - + `includeExts` - {Array} File extensions used to include files in processing. Must include the dot. - + `excludeDirsRe` - {RegExp} A regular expression used to exclude directories from processing. A match is an exclusion. - + `targetText` - {String|RegExp} Used to identify the line to process. First argument to `string.replace`. - + `replacementText` - {String|Function} Used to replace the `targetText`. Second argument to `string.replace`. - + `replacementFilter` - {Function} A function to deny a specific replacement otherwise matched by `targetText`. Return true to allow the replacement to proceed as normal, false to deny it. If not supplied, defaults to all matched replacements allowed. + + **action** - {String} `echo|audit|update` The action taken on each file. Defaults to `echo`. Use `echo` and `audit` actions to test the results of picklr with options prior to running `update`. + + **echo** - Just output what files could be affected by a change. Tests `includeExts` and `excludeDirsRe` options. + + **audit** - Must use with `targetText` and `replacementText`. Outputs lines found and the change plus any files that would be omitted. Tests `includeExts`, `excludeDirsRe`, `targetText` and `replacementText` options. + + **update** - Does the actual update on the files in place. Use only if you have version control. + + **includeExts** - {Array} File extensions used to include files in processing. Must include the dot. + + **excludeDirsRe** - {RegExp} A regular expression used to exclude directories from processing. A match is an exclusion. + + **targetText** - {String|RegExp} Used to identify the line to process. First argument to `string.replace`. + + **replacementText** - {String|Function} Used to replace the `targetText`. Second argument to `string.replace`. + + **replacementFilter** - {Function} A function to deny a specific replacement otherwise matched by `targetText`. Return true to allow the replacement to proceed as normal, false to deny it. If not supplied, defaults to all matched replacements allowed. *signature:* **function (filePath, lineText): Boolean** - + `logger` - {Function} A log function to receive output. Defaults to `console.log`. + + **logger** - {Function} A log function to receive output. Defaults to `console.log`. ## Example Usage diff --git a/package-lock.json b/package-lock.json index d1eacd1..3d72350 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,16 +1,16 @@ { "name": "picklr", - "version": "0.10.0", + "version": "0.11.1", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "picklr", - "version": "0.10.0", + "version": "0.11.1", "license": "MIT", "devDependencies": { - "c8": "^9.0.0", - "chai": "^5.0.0", + "c8": "^9.1.0", + "chai": "^5.0.3", "eslint": "^8.56.0", "mocha": "^10.2.0", "precommit-hook": "^3.0.0" @@ -346,9 +346,9 @@ "dev": true }, "node_modules/c8": { - "version": "9.0.0", - "resolved": "https://registry.npmjs.org/c8/-/c8-9.0.0.tgz", - "integrity": "sha512-nFJhU2Cz6Frh2awk3IW7wwk3wx27/U2v8ojQCHGc1GWTCHS6aMu4lal327/ZnnYj7oSThGF1X3qUP1yzAJBcOQ==", + "version": "9.1.0", + "resolved": "https://registry.npmjs.org/c8/-/c8-9.1.0.tgz", + "integrity": "sha512-mBWcT5iqNir1zIkzSPyI3NCR9EZCVI3WUD+AVO17MVWTSFNyUueXE82qTeampNtTr+ilN/5Ua3j24LgbCKjDVg==", "dev": true, "dependencies": { "@bcoe/v8-coverage": "^0.2.3", @@ -392,15 +392,15 @@ } }, "node_modules/chai": { - "version": "5.0.0", - "resolved": "https://registry.npmjs.org/chai/-/chai-5.0.0.tgz", - "integrity": "sha512-HO5p0oEKd5M6HEcwOkNAThAE3j960vIZvVcc0t2tI06Dd0ATu69cEnMB2wOhC5/ZyQ6m67w3ePjU/HzXsSsdBA==", + "version": "5.0.3", + "resolved": "https://registry.npmjs.org/chai/-/chai-5.0.3.tgz", + "integrity": "sha512-wKGCtYv2kVY5WEjKqQ3fSIZWtTFveZCtzinhTZbx3/trVkxefiwovhpU9kRVCwxvKKCEjTWXPdM1/T7zPoDgow==", "dev": true, "dependencies": { "assertion-error": "^2.0.1", "check-error": "^2.0.0", "deep-eql": "^5.0.1", - "loupe": "^3.0.0", + "loupe": "^3.1.0", "pathval": "^2.0.0" }, "engines": { @@ -1432,9 +1432,9 @@ } }, "node_modules/loupe": { - "version": "3.0.2", - "resolved": "https://registry.npmjs.org/loupe/-/loupe-3.0.2.tgz", - "integrity": "sha512-Tzlkbynv7dtqxTROe54Il+J4e/zG2iehtJGZUYpTv8WzlkW9qyEcE83UhGJCeuF3SCfzHuM5VWhBi47phV3+AQ==", + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/loupe/-/loupe-3.1.0.tgz", + "integrity": "sha512-qKl+FrLXUhFuHUoDJG7f8P8gEMHq9NFS0c6ghXG1J0rldmZFQZoNVv/vyirE9qwCIhWZDsvEFd1sbFu3GvRQFg==", "dev": true, "dependencies": { "get-func-name": "^2.0.1" diff --git a/package.json b/package.json index 8a352e5..63c438d 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "picklr", - "version": "0.11.0", + "version": "0.11.1", "description": "A utility to update a single line in multiple files", "main": "index.js", "type": "module", @@ -35,8 +35,8 @@ }, "homepage": "https://github.com/localnerve/picklr#readme", "devDependencies": { - "c8": "^9.0.0", - "chai": "^5.0.0", + "c8": "^9.1.0", + "chai": "^5.0.3", "eslint": "^8.56.0", "mocha": "^10.2.0", "precommit-hook": "^3.0.0"