.d8888b.                                    888
d88P  Y88b                                   888
Y88b.                                        888
 "Y888b.    .d88b.   8888b.  888d888 .d8888b 88888b.   .d88b.  888d888 .d88b.  888d888
    "Y88b. d8P  Y8b     "88b 888P"  d88P"    888 "88b d8P  Y8b 888P"  d8P  Y8b 888P"
      "888 88888888 .d888888 888    888      888  888 88888888 888    88888888 888
Y88b  d88P Y8b.     888  888 888    Y88b.    888  888 Y8b.     888    Y8b.     888
 "Y8888P"   "Y8888  "Y888888 888     "Y8888P 888  888  "Y8888  888     "Y8888  888

Searcherer is a Node.js module for searching strings or files.

• Install
• CLI
• API
• Bugs
• Contributors
• License

Install

Install using npm:

$ npm install --save searcherer

You'll need to have at least Node.js 8 or newer.

If you want to use the command line interface you'll most likely want to install it globally so that you can run searcherer from anywhere:

$ npm install --global searcherer

CLI

Usage: searcherer [options] [files...]


Options:

  -V, --version              output the version number
  --no-color                 disables color output
  -c, --case-sensitive       enable case-sensitive search
  -d, --debug                enable debug level logging
  -e, --encoding <encoding>  specify encoding for input [utf8]
  -f, --filename <filename>  specify filename to process STDIN as [<text>]
  -p, --pattern <pattern>    search for pattern
  -s, --style <name>         specify style for output [default]
  -h, --help                 output usage information

API

The API has been designed to be just as simple to use as the CLI. It uses ECMAScript 2015's promises to handle the asynchronous flows of file reading (with Sync methods available as well) so you can keep your code nice and clean.

Each search result contains the following information:

Property	Type	Description
columnNumber	Number	Column number at which the match was found
dictionary	Dictionary	Dictionary to which the pattern responsible for the match belongs
line	String	Complete line of text in which the match was found
lineNumber	Number	Line number in relation to the whole string being searched
match	String	Exact match that was found
pattern	String	Pattern responsible for the match

Searcherer.search(value, dictionary[, options])

Searches the specified value for the patterns within the specified dictionary using the options provided.

dictionary can either be a Dictionary instance or one or more of search patterns from which a Dictionary instance can be created.

Options

Option	Description	Default
caseSensitive	Perform case-sensitive search on value	false
filter	Function to be used to filter which dictionaries are included in search	All

Examples

const Searcherer = require('searcherer');

const results = Searcherer.search('We love Searcherer! It is great for searching strings', 'search(er){0,2}');

console.log(results);

Searcherer.searchFile(filePath, dictionary[, options])

Searches the contents that are asynchronously read from the file at the specified path for the patterns within the specified dictionary using the options provided.

dictionary can either be a Dictionary instance or one or more of search patterns from which a Dictionary instance can be created.

The encoding option can be used to specify how the contents of the file are encoded.

Options

Has the same options as the standard Searcherer.search method but also supports the following additional options:

Option	Description	Default
encoding	Encoding of the contents of the file to be searched	"utf8"

Examples

const Searcherer = require('searcherer');

(async() => {
  const results = await Searcherer.searchFile('/path/to/file', 'search(er){0,2}', { caseSensitive: true });
  
  console.log(results);
})();

Searcherer.searchFileSync(filePath, dictionary[, options])

A synchronous version of the Searcherer.searchFile method.

Searcherer([options])

Creates an instance of Searcherer using the options provided.

The dictionary option can be specified to initialize Searcherer with a single Dictionary. It can be either a Dictionary instance or one or more of search patterns from which a Dictionary instance can be created.

While the static methods of Searcherer for searching work great, it's encouraged to create Searcherer instances when dealing with multiple dictionaries (collections of search patterns). Additionally, it's highly recommended that Dictionary instances are created when searching a large number of patterns and/or using the same patterns to search many different strings/files. Doing so will increase performance as regular expressions compiled from the patterns are cached.

The following instance methods exist to mirror the static methods for searching:

• Searcherer#search(value[, options])
• Searcherer#searchFile(filePath[, options])
• Searcherer#searchFileSync(filePath[, options])

Additionally, the following instance methods exist that allow dictionaries to be added to a Searcherer instance:

• Searcherer#addDictionary(dictionary)
• Searcherer#addDictionaryFile(filePath)
• Searcherer#addDictionaryFileSync(filePath)

Options

Option	Description	Default
dictionary	Initial Dictionary or the search pattern(s) to be used to create it	N/A
dictionaryType	Dictionary implementation whose instances are to be created	Dictionary

Events

Each of the search methods can emit the following events:

Event	Description
end	Fired once the search has completed
result	Fired immediately when a search result is found
search	Fired immediately before the value is searched

Examples

const Searcherer = require('searcherer');
const { Dictionary } = Searcherer;

(async() => {
  const searcherer = new Searcher();
  searcherer.addDictionary(new Dictionary({ name: 'foo', patterns: [ ... ] ));
  searcherer.addDictionary(new Dictionary({ name: 'bar', patterns: [ ... ] ));
  
  const results = await searcherer.searchFile('/path/to/file', { caseSensitive: true });
  
  console.log(results);
})();

Bugs

If you have any problems with Searcherer or would like to see changes currently in development you can do so here.

Contributors

If you want to contribute, you're a legend! Information on how you can do so can be found in CONTRIBUTING.md. We want your suggestions and pull requests!

A list of Searcherer contributors can be found in AUTHORS.md.

License

See LICENSE.md for more information on our MIT license.