Merge pull request #7 from NotNinja/develop

0.2.0 Release

CHANGES.md

@@ -1,3 +1,8 @@
+## Version 0.2.0, 2017.11.07
+
+* Improve support for custom Dictionary implementations [#5](https://github.com/NotNinja/searcherer/issues/5) (**breaking change**)
+* Change Searcherer#getDictionaries method to a getter [#6](https://github.com/NotNinja/searcherer/issues/6) (**breaking change**)
+
 ## Version 0.1.1, 2017.11.07
 
 * Searcherer.findDictionary should be an instance method [#3](https://github.com/NotNinja/searcherer/issues/3)

README.md

@@ -82,10 +82,10 @@ 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*   |
+| 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
 
@@ -131,14 +131,12 @@ const Searcherer = require('searcherer');
 
 A synchronous version of the `Searcherer.searchFile` method.
 
-### `Searcherer([dictionary])`
+### `Searcherer([options])`
 
-Creates an instance of `Searcherer`.
+Creates an instance of `Searcherer` using the `options` provided.
 
-Optionally, `dictionary` can be provided so that `Searcherer` is initialized with a single `Dictionary`.
-
-`dictionary` can either be a `Dictionary` instance or one or more of search patterns from which a `Dictionary` instance
-can be created.
+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
@@ -158,6 +156,13 @@ Additionally, the following instance methods exist that allow dictionaries to be
 * `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:

package.json

@@ -1,6 +1,6 @@
 {
   "name": "searcherer",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Searches contents of files",
   "homepage": "https://github.com/NotNinja/searcherer",
   "bugs": {

src/api/Dictionary.js

@@ -47,16 +47,18 @@ class Dictionary {
    * Optionally, <code>defaults</code> can be provided to control the default values that are to be used if the data
    * parsed from <code>str</code> is incomplete.
    *
-   * <code>str</code> is parsed as JSON and this method is primarily intended to be used internally to parse "dictionary
-   * files" via methods on {@link Searcherer}, however, this can be used externally as well. The parsed data can be any
-   * of the following types:
+   * By default, <code>str</code> is parsed as JSON and this method is primarily intended to be used internally to parse
+   * "dictionary files" via methods on {@link Searcherer}, however, this can be used externally as well. The parsed data
+   * can be any of the following types:
    *
    * <ul>
    *   <li>string - used as a single search pattern</li>
    *   <li>array - used as search patterns</li>
    *   <li>object - uses values of the <code>name</code> and <code>patterns</code> properties accordingly</li>
    * </ul>
    *
+   * However, implementations are free to override this behavior as needed.
+   *
    * This method will return <code>null</code> if <code>str</code> is <code>null</code> or the JSON is parsed to
    * <code>null</code>.
    *
@@ -105,6 +107,38 @@ class Dictionary {
     this[_regExpMaps] = new Map();
   }
 
+  /**
+   * Creates a <code>RegExp</code> instance for the specified <code>pattern</code> and <code>flags</code>.
+   *
+   * @param {string} pattern - the pattern for which the <code>RegExp</code> is to be created
+   * @param {string} flags - the flags to be used
+   * @return {RegExp} A newly created <code>RegExp</code>.
+   * @protected
+   */
+  createRegExp(pattern, flags) {
+    return new RegExp(pattern, flags);
+  }
+
+  /**
+   * Creates a search result based on the information provided.
+   *
+   * @param {string} pattern - the pattern responsible for the match
+   * @param {Dictionary~RegExpMatch} match - the regular expression match
+   * @param {Searcherer~SearchContext} context - the context whose line contained the match
+   * @return {Searcherer~Result} The search result.
+   * @public
+   */
+  createResult(pattern, match, context) {
+    return {
+      columnNumber: match.index,
+      dictionary: this,
+      line: context.line,
+      lineNumber: context.lineNumber,
+      match: match[0],
+      pattern
+    };
+  }
+
   /**
    * Returns whether this {@link Dictionary} contains the specified <code>pattern</code>.
    *
@@ -131,14 +165,7 @@ class Dictionary {
       let match;
 
       while ((match = regExp.exec(context.line)) != null) {
-        yield {
-          columnNumber: match.index,
-          dictionary: this,
-          line: context.line,
-          lineNumber: context.lineNumber,
-          match: match[0],
-          pattern
-        };
+        yield this.createResult(pattern, match, context);
       }
     }
   }
@@ -169,7 +196,7 @@ class Dictionary {
     regExpMap = new Map();
 
     for (const pattern of this[_patterns]) {
-      regExpMap.set(pattern, new RegExp(pattern, flags));
+      regExpMap.set(pattern, this.createRegExp(pattern, flags));
     }
 
     this[_regExpMaps].set(caseSensitive, regExpMap);
@@ -201,6 +228,14 @@ class Dictionary {
 
 module.exports = Dictionary;
 
+/**
+ * A {@link RegExp} match.
+ *
+ * @typedef {Array} Dictionary~RegExpMatch
+ * @property {number} index - The 0-based index of the match in the string.
+ * @property {string} input - The original string.
+ */
+
 /**
  * The options that can be passed to the {@link Dictionary} constructor.
  *