https://github.com/localnerve/picklr
A simple, zero dependency, recursive, text replacer for NodeJS
https://github.com/localnerve/picklr
multiple-files nodejs text-replace
Last synced: 10 months ago
JSON representation
A simple, zero dependency, recursive, text replacer for NodeJS
- Host: GitHub
- URL: https://github.com/localnerve/picklr
- Owner: localnerve
- License: mit
- Created: 2016-02-02T03:09:28.000Z (about 10 years ago)
- Default Branch: master
- Last Pushed: 2025-02-18T16:26:30.000Z (about 1 year ago)
- Last Synced: 2025-05-15T07:47:16.752Z (11 months ago)
- Topics: multiple-files, nodejs, text-replace
- Language: JavaScript
- Homepage:
- Size: 487 KB
- Stars: 3
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Picklr
[](http://badge.fury.io/js/picklr)
[](https://coveralls.io/r/localnerve/picklr?branch=master)
> "`Pick` `l`ine & `r`eplace"
>
> A simple, zero dependency, recursive, text replacer.
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 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.
`function (startDir, options)`
### 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.
*signature:* **function (filePath, lineText): Boolean**
+ **logger** - {Function} A log function to receive output. Defaults to `console.log`.
## Example Usage
```javascript
// Example use for a copyright banner text update:
import picklr from 'picklr';
// Output what files WOULD be affected by includes/excludes:
picklr('.', {
action: 'echo',
includeExts: ['.js', '.jsx', '.scss'],
excludeDirsRe: /\/\.|node_modules|dist|tmp|reports/i
});
// Output what WOULD be processed using targetText/replacementText:
picklr('.', {
action: 'audit',
targetText: 'Copyright (c) 2015',
replacementText: 'Copyright (c) 2015, 2016',
includeExts: ['.js', '.jsx', '.scss'],
excludeDirsRe: /\/\.|node_modules|dist|tmp|reports/i
});
// Got it. Now, actually perform the pick line and replacement.
picklr('.', {
action: 'update',
targetText: 'Copyright (c) 2015',
replacementText: 'Copyright (c) 2015, 2016',
includeExts: ['.js', '.jsx', '.scss'],
excludeDirsRe: /\/\.|node_modules|dist|tmp|reports/i
});
```
### Non-module Usage
```javascript
// import the es module in a non-module environment, echo options example:
import('picklr').then(({ picklr }) => {
picklr('.', {
action: 'echo',
includeExts: ['.js', '.jsx', '.scss'],
excludeDirsRe: /\/\.|node_modules|dist|tmp|reports/i
});
});
```
### Omitted
To see only what files would be omitted, set your picklr script to use action 'audit', then grep the output for 'Omitted'.
```javascript
// myPicklrScript.js
import picklr from 'picklr';
picklr('.', {
action: 'audit',
targetText: 'Copyright (c) 2015',
replacementText: 'Copyright (c) 2015, 2016',
includeExts: ['.js', '.jsx', '.scss'],
excludeDirsRe: /\/\.|node_modules|dist|tmp|reports/i
});
```
```shell
node myPicklrScript.js | grep 'Omitted'
```
## License
MIT