find-cli 1.4.7 → 1.4.10

package/README.md

@@ -1,6 +1,14 @@
 # Find-CLI
 
-Find...
+An alternative to `grep`.
+
+Find looks for occurrences in files' contents that match a supplied glob, string or regular expression.
+It filters files and directories by way of configurable path matching rules that are also based on globs, strings and regular expressions.
+It is quite like `grep` but it is arguably more user friendly and surprisingly just as fast.
+
+Find uses globs by default for matching both content and paths.
+Its use of them is slightly non-standard but hopefully de-mystifying.
+In fact there is is a section below devoted to how they are converted to regular expressions.
 
 ## Installation
 
@@ -45,15 +53,98 @@ Options:
 
   --version|-v                             Show the version
 
-  --dry-run|-d                             Traverse the directories and files but do not search
+  --dry-run|-d                             Traverse the directories and files only
 
-  --quietly|-q                             Execute shell commands without printing to the console
+  --quietly|-q                             Do not show the directory and file path matching
 ```
 
-In the directory that contains the sub-directories holding your project's packages and binaries, run the following command:
+### Setup
 
+Suppose that you want to search your `~/Development` directory.
+First run the following commands:
+
+    cd ~/Development
     find initialise
 
+This creates a `.findrc` configuration file in the `~/Development` directory that under normal circumstances should not be edited by hand.
+
+Now suppose that you also want to search a sibling `~/Sites` directory.
+You can configure this additional root directory and see the results with the following commands: 
+
+    find add-root-directory ../Sites/
+    find list-root-directories
+
+### Path rules
+
+Once you have the root directories set up you can start to add the rules that filter the file and directory paths.
+Start with a dry run so that there is no need to specify what to search for:
+
+    find -d
+
+Find works from four collections of rules for ignoring and permitting file and directory paths.
+It ignores paths first but can subsequently permit them.
+It must be able to match a rule to each path that it encounters.
+If not it will prompt you to configure one.
+For example, the very first file that it encounters may be its own `.findrc` configuration file.
+In that case it will ask you whether you want to ignore or permit that path and then prompt you for a glob, string or regular expression to match the path as a whole.
+The choice is yours but globs are the default and do not have delimiters.
+
+    .findrc     // gllob
+    ".findrc"   // string
+    /\.findrc/  // regular expression
+
+You may have several thousand files and directories that need matching and wildcards will obviously be needed.
+It can take several minutes to answer all the prompts but you can opt out at any time by hitting the enter key three times at any prompt.
+A little patience with the process and a couple of tries at it are recommended.
+
+Once the rules are set up there is little more to do other than to search for occurrences, again using globs, strings or regular expressions.
+For example:
+
+    find -q START_OF_CONTENT
+    find -q "Query.fromExpression"
+    find -q /"[^"]*"/
+
+The `-q` flag here suppresses the path matching messages.
+Only the occurrences will be shown once the search is complete.
+
+### Converting globs to regular expressions
+
+Find differentiates between directory and file paths and this is important when converting globs.
+Directory paths *must* end with a slash.
+So:
+
+    /        // root directory
+    ./       // current directory
+    ../      // parent directory
+    foo/  
+    foo/bar/
+
+Find will add the trailing slashes when matching directory paths.
+For example:
+
+    Ignore ../Sites/account.xomi.cloud/template/ */template/**/
+
+Note that the root directory has been prepended, but only for clarity when showing messages. 
+It is not prepended for the purpose of matching.
+A trailing slash has been prepended, however, and this has a bearing on how the glob is converted.
+
+One thing to note is that you do not have to remember to prepend trailing slashes yourself when prompted for globs, strings or regular expressions ot match directory paths.
+Find will always add them.
+
+Although non-standard, The presence of a trailing slash for directory paths means makes the conversion of globs to regular expressions easier.
+Here is a list of some of the conversions:
+
+| Glob  | Regular expression | Description          |
+|-------|--------------------|----------------------|
+| `**/` | `(?:[^/]*\\/)*`    | Repeated directories |
+| `*/`  | `[^/]*\\/`         | Single directory     |
+| `/`   | `\\/`              | Directory            |
+| `**`  | `.*`               | Repeated wildcard    |
+| `*`   | `.+?`              | Single wildcard      |
+
+Character classes and alternatives are also supported. 
+Their conversions are more or less standard.
+
 ## Contact
 
 * james.smith@djalbat.com

package/bin/action/find.js

@@ -5,8 +5,7 @@ const ruleOperation = require("../operation/rule"),
       readConfigurationOperation = require("../operation/readConfiguration");
 
 const { S, EMPTY_STRING } = require("../constants"),
-      { executeOperations } = require("../utilities/operation"),
-      { FAILED_FIND_MESSAGE, SUCCESSFUL_FIND_MESSAGE } = require("../messages");
+      { executeOperations } = require("../utilities/operation");
 
 function findAction(string, dryRun, quietly) {
   const operations = [
@@ -33,17 +32,13 @@ function findAction(string, dryRun, quietly) {
         };
 
   executeOperations(operations, (completed) => {
-    logTottals(context);
+    logLines(context);
 
     if (!completed) {
-      console.log(FAILED_FIND_MESSAGE);
-
       return;
     }
 
-    logLines(context);
-
-    console.log(SUCCESSFUL_FIND_MESSAGE);
+    logTottals(context);
   }, context);
 }
 

package/bin/action/help.js

@@ -25,9 +25,9 @@ Options:
 
   --version|-v                             Show the version
 
-  --dry-run|-d                             Traverse the directories and files but do not search
+  --dry-run|-d                             Traverse the directories and files only
 
-  --quietly|-q                             Execute shell commands without printing to the console
+  --quietly|-q                             Do not show the directory and file path matching
 
 Further information:
 

package/bin/messages.js

@@ -8,11 +8,9 @@ const NO_ARGUMENT_GIVEN_MESSAGE = "No argument has been given.",
       INVALID_ROOT_DIRECTORY_PATH_MESSAGE = "Additional root directories must be globs of the form '../**/'.",
       INVALID_GLOB_REGEX_OR_STRING_MESSAGE = "The glob, regex or string is invalid.",
       INVALID_ROOT_DIRECTORY_PATH_INDEX_MESSAGE = "The index is either not a number or not within range.",
-      FAILED_FIND_MESSAGE = "Failed to search everything.",
       FAILED_INITIALISE_MESSAGE = "Failed to create a configuration file because one is already present.",
       FAILED_ADD_ROOT_DIRECTORY_MESSAGE = "Failed to add the root directory.",
       FAILED_REMOVE_ROOT_DIRECTORY_MESSAGE = "Failed to remove the root directory.",
-      SUCCESSFUL_FIND_MESSAGE = "Searched everything successfully.",
       SUCCESSFUL_INITIALISE_MESSAGE = "The configuration file has been created successfully.",
       SUCCESSFUL_ADD_ROOT_DIRECTORY_MESSAGE = "Added the root directory successfully.",
       SUCCESSFUL_REMOVE_ROOT_DIRECTORY_MESSAGE = "Removed the root directory successfully.";
@@ -26,11 +24,9 @@ module.exports = {
   INVALID_ROOT_DIRECTORY_PATH_MESSAGE,
   INVALID_GLOB_REGEX_OR_STRING_MESSAGE,
   INVALID_ROOT_DIRECTORY_PATH_INDEX_MESSAGE,
-  FAILED_FIND_MESSAGE,
   FAILED_INITIALISE_MESSAGE,
   FAILED_ADD_ROOT_DIRECTORY_MESSAGE,
   FAILED_REMOVE_ROOT_DIRECTORY_MESSAGE,
-  SUCCESSFUL_FIND_MESSAGE,
   SUCCESSFUL_INITIALISE_MESSAGE,
   SUCCESSFUL_ADD_ROOT_DIRECTORY_MESSAGE,
   SUCCESSFUL_REMOVE_ROOT_DIRECTORY_MESSAGE

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "find-cli",
   "author": "James Smith",
-  "version": "1.4.7",
+  "version": "1.4.10",
   "license": "MIT, Anti-996",
   "homepage": "https://github.com/djalbat/find-cli",
   "description": "An alternative to grep.",