Package Torello.Java

Class GREP

  • public class GREP
extends java.lang.Object
    A utility that attempts to mimic the UNIX command 'grep'.

    GREP: Global Regular-Expressions Print


    GREP is a UNIX-Platform Search String for the File-System command-line program. It was written many years ago, in the 1980's.

    Stuff to Know:
    I absolutely never use this God-Damned Thing. Dallas Brain Control made me write it. At the command line, the original UNIX 'grep' Tool is what to stick by.

    Note that the "Java-ized" version of 'SED' (on the other hand) can be a real life-saver. Trying to figure out how to escape regular exressions on the command line is such a problem, that using the actual / original UNIX 'SED' is kind of difficult.

    Example:
    public static void main(String[] argv) throws IOException
{
    // This "builder" or "hamburger stack" of method invokations loads the HTML Documentation Files
    // into a FileNode.  The resulting tree is "flattened" from a tree-structure, to a Vector.
    // If there happen to be any non-HTML files in the named directory (which there aren't), they
    // will be "pruned" (filtered)

    Vector<FileNode> htmlFiles = FileNode
        .createRoot("Torello/Build/DocHTML/NodeSearch/")
        .loadTree(true, false)
        .prune(fileNode -> fileNode.getFullPathName().endsWith(".html"), false)
        .flatten();

    // This will search the through all "HTML" (Java Code Documentation Files) for the RegEx String
    // in the "Pattern.compile" method.  The command will use the "Simple" IOExceptionHandler (only
    // if there are any IOExceptions, which here, there won't be).  The command will use the "ALL"
    // (SearchAndPrint class) to print all matches.

    GREP.search(htmlFiles, SearchAndPrint.ALL(Pattern.compile
        ("<td>When this parameter is present, only HTMLNode's which are both <code>instanceof class TagNode</code> <i>\\*and\\*</i>"),
        true, System.out), IOExceptionHandler.SIMPLE);

    // ALSO NOTE: In the above line, the return results ARE NOT retained, but they easily could be
    // with the line:
    //
    // Vector<FileNode> matchResults = GREP.search(...)
}

    If the above class were called, it would print the following text to a UNIX terminal (with colors): 

    File: Torello/Build/DocHTML/NodeSearch/TagNodeFindInclusive.html, Line:      <td>When this parameter is present, only HTMLNode's which are both <code>instanceof class TagNode</code> <i>*and*</i> have
File: Torello/Build/DocHTML/NodeSearch/InnerTagPoll.html, Line:      <td>When this parameter is present, only HTMLNode's which are both <code>instanceof class TagNode</code> <i>*and*</i> have
File: Torello/Build/DocHTML/NodeSearch/InnerTagPoll.html, Line:      <td>When this parameter is present, only HTMLNode's which are both <code>instanceof class TagNode</code> <i>*and*</i> have
File: Torello/Build/DocHTML/NodeSearch/TagNodeCount.html, Line:      <td>When this parameter is present, only HTMLNode's which are both <code>instanceof class TagNode</code> <i>*and*</i> have
File: Torello/Build/DocHTML/NodeSearch/InnerTagRemove.html, Line:      <td>When this parameter is present, only HTMLNode's which are both <code>instanceof class TagNode</code> <i>*and*</i> have
File: Torello/Build/DocHTML/NodeSearch/InnerTagRemove.html, Line:      <td>When this parameter is present, only HTMLNode's which are both <code>instanceof class TagNode</code> <i>*and*</i> have
File: Torello/Build/DocHTML/NodeSearch/TagNodeGetL1Inclusive.html, Line:      <td>When this parameter is present, only HTMLNode's which are both <code>instanceof class TagNode</code> <i>*and*</i> have
File: Torello/Build/DocHTML/NodeSearch/InnerTagGetInclusive.html, Line:      <td>When this parameter is present, only HTMLNode's which are both <code>instanceof class TagNode</code> <i>*and*</i> have
File: Torello/Build/DocHTML/NodeSearch/InnerTagGetInclusive.html, Line:      <td>When this parameter is present, only HTMLNode's which are both <code>instanceof class TagNode</code> <i>*and*</i> have
File: Torello/Build/DocHTML/NodeSearch/InnerTagPollInclusive.html, Line:      <td>When this parameter is present, only HTMLNode's which are both <code>instanceof class TagNode</code> <i>*and*</i> have
File: Torello/Build/DocHTML/NodeSearch/InnerTagPollInclusive.html, Line:      <td>When this parameter is present, only HTMLNode's which are both <code>instanceof class TagNode</code> <i>*and*</i> have
File: Torello/Build/DocHTML/NodeSearch/InnerTagCount.html, Line:      <td>When this parameter is present, only HTMLNode's which are both <code>instanceof class TagNode</code> <i>*and*</i> have
File: Torello/Build/DocHTML/NodeSearch/InnerTagCount.html, Line:      <td>When this parameter is present, only HTMLNode's which are both <code>instanceof class TagNode</code> <i>*and*</i> have
File: Torello/Build/DocHTML/NodeSearch/TagNodePeekL1Inclusive.html, Line:      <td>When this parameter is present, only HTMLNode's which are both <code>instanceof class TagNode</code> <i>*and*</i> have
File: Torello/Build/DocHTML/NodeSearch/TagNodeFindL1Inclusive.html, Line:     <td>When this parameter is present, only HTMLNode's which are both <code>instanceof class TagNode</code> <i>*and*</i> have
File: Torello/Build/DocHTML/NodeSearch/TagNodeGet.html, Line:      <td>When this parameter is present, only HTMLNode's which are both <code>instanceof class TagNode</code> <i>*and*</i> have
File: Torello/Build/DocHTML/NodeSearch/TagNodeIterator.html, Line:      <td>When this parameter is present, only HTMLNode's which are both <code>instanceof class TagNode</code> <i>*and*</i> have
File: Torello/Build/DocHTML/NodeSearch/InnerTagIterator.html, Line:      <td>When this parameter is present, only HTMLNode's which are both <code>instanceof class TagNode</code> <i>*and*</i> have
File: Torello/Build/DocHTML/NodeSearch/InnerTagIterator.html, Line:      <td>When this parameter is present, only HTMLNode's which are both <code>instanceof class TagNode</code> <i>*and*</i> have
File: Torello/Build/DocHTML/NodeSearch/InnerTagRemoveInclusive.html, Line:      <td>When this parameter is present, only HTMLNode's which are both <code>instanceof class TagNode</code> <i>*and*</i> have
File: Torello/Build/DocHTML/NodeSearch/InnerTagRemoveInclusive.html, Line:      <td>When this parameter is present, only HTMLNode's which are both <code>instanceof class TagNode</code> <i>*and*</i> have
File: Torello/Build/DocHTML/NodeSearch/TagNodeFind.html, Line:      <td>When this parameter is present, only HTMLNode's which are both <code>instanceof class TagNode</code> <i>*and*</i> have
File: Torello/Build/DocHTML/NodeSearch/InnerTagPeekInclusive.html, Line:      <td>When this parameter is present, only HTMLNode's which are both <code>instanceof class TagNode</code> <i>*and*</i> have
File: Torello/Build/DocHTML/NodeSearch/InnerTagPeekInclusive.html, Line:      <td>When this parameter is present, only HTMLNode's which are both <code>instanceof class TagNode</code> <i>*and*</i> have
File: Torello/Build/DocHTML/NodeSearch/InnerTagFind.html, Line:      <td>When this parameter is present, only HTMLNode's which are both <code>instanceof class TagNode</code> <i>*and*</i> have
File: Torello/Build/DocHTML/NodeSearch/InnerTagFind.html, Line:      <td>When this parameter is present, only HTMLNode's which are both <code>instanceof class TagNode</code> <i>*and*</i> have
File: Torello/Build/DocHTML/NodeSearch/TagNodeRemoveInclusive.html, Line:      <td>When this parameter is present, only HTMLNode's which are both <code>instanceof class TagNode</code> <i>*and*</i> have
File: Torello/Build/DocHTML/NodeSearch/TagNodePeekInclusive.html, Line:      <td>When this parameter is present, only HTMLNode's which are both <code>instanceof class TagNode</code> <i>*and*</i> have
File: Torello/Build/DocHTML/NodeSearch/InnerTagPeek.html, Line:      <td>When this parameter is present, only HTMLNode's which are both <code>instanceof class TagNode</code> <i>*and*</i> have
File: Torello/Build/DocHTML/NodeSearch/InnerTagPeek.html, Line:      <td>When this parameter is present, only HTMLNode's which are both <code>instanceof class TagNode</code> <i>*and*</i> have
File: Torello/Build/DocHTML/NodeSearch/TagNodeInclusiveIterator.html, Line:      <td>When this parameter is present, only HTMLNode's which are both <code>instanceof class TagNode</code> <i>*and*</i> have
File: Torello/Build/DocHTML/NodeSearch/InnerTagGet.html, Line:      <td>When this parameter is present, only HTMLNode's which are both <code>instanceof class TagNode</code> <i>*and*</i> have
File: Torello/Build/DocHTML/NodeSearch/InnerTagGet.html, Line:      <td>When this parameter is present, only HTMLNode's which are both <code>instanceof class TagNode</code> <i>*and*</i> have
File: Torello/Build/DocHTML/NodeSearch/TagNodeGetInclusive.html, Line:      <td>When this parameter is present, only HTMLNode's which are both <code>instanceof class TagNode</code> <i>*and*</i> have
File: Torello/Build/DocHTML/NodeSearch/TagNodeRemove.html, Line:      <td>When this parameter is present, only HTMLNode's which are both <code>instanceof class TagNode</code> <i>*and*</i> have
File: Torello/Build/DocHTML/NodeSearch/InnerTagFindInclusive.html, Line:      <td>When this parameter is present, only HTMLNode's which are both <code>instanceof class TagNode</code> <i>*and*</i> have
File: Torello/Build/DocHTML/NodeSearch/InnerTagFindInclusive.html, Line:      <td>When this parameter is present, only HTMLNode's which are both <code>instanceof class TagNode</code> <i>*and*</i> have
File: Torello/Build/DocHTML/NodeSearch/TagNodePollInclusive.html, Line:      <td>When this parameter is present, only HTMLNode's which are both <code>instanceof class TagNode</code> <i>*and*</i> have
File: Torello/Build/DocHTML/NodeSearch/InnerTagInclusiveIterator.html, Line:      <td>When this parameter is present, only HTMLNode's which are both <code>instanceof class TagNode</code> <i>*and*</i> have
File: Torello/Build/DocHTML/NodeSearch/InnerTagInclusiveIterator.html, Line:      <td>When this parameter is present, only HTMLNode's which are both <code>instanceof class TagNode</code> <i>*and*</i> have
File: Torello/Build/DocHTML/NodeSearch/TagNodePeek.html, Line:      <td>When this parameter is present, only HTMLNode's which are both <code>instanceof class TagNode</code> <i>*and*</i> have
File: Torello/Build/DocHTML/NodeSearch/TagNodePoll.html, Line:      <td>When this parameter is present, only HTMLNode's which are both <code>instanceof class TagNode</code> <i>*and*</i> have



    Stateless Class:
    This class neither contains any program-state, nor can it be instantiated. The @StaticFunctional Annotation may also be called 'The Spaghetti Report'. Static-Functional classes are, essentially, C-Styled Files, without any constructors or non-static member fields. It is a concept very similar to the Java-Bean's @Stateless Annotation.

    • 1 Constructor(s), 1 declared private, zero-argument constructor
    • 4 Method(s), 4 declared static
    • 0 Field(s)


    • Method Detail

      • search

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static <T> T search​(RTC<T> dataStructureChoice,
                           java.util.Iterator<FileNode> iter,
                           SearchAndPrint sp,
                           IOExceptionHandler ioeh)
        This version of GREP shall search every file in a java Iterator<FileNode> data-structure. Any 'directories' (which are not files) returned by this Iterator shall be skipped / ignored.
        Parameters:
        dataStructureChoice - This allows the user to choose a particular Data-Container or List, such as Vector, Stream, or Array as a desired Return-Type for this method.

        In addition to the Data-Container, you may use this parameter to request that the output be sorted using a set of pre-selected sort Comparator's. You may also request that the data be converted to a String-Format (rather than a FileNode) that contains either the File-Name as a String, or the Full-Path (Complete) File-Name.

        See: class RTC for details.
        iter - Any Iterator of type Iterator<FileNode>. Each file that is returned in the return set shall be searched for the described matches using 'SearchAndPrint' parameter 'sp'
        sp - The 'sp' parameter is the implementation of the file-grep operation that the user is requesting. The actions that this SearchAndPrint method-pointer should perform include:

        • Test if the file contains a match - using whatever string-testing procedure required. Usually either a simple String token is being searched, or an entire String regular-expression is used.
        • Do some kind of output printing to a writable printing parameter to report these String-match results
        • return either TRUE or FALSE to indicate whether or not a particular file contained matches.


        IMPORTANT: This parameter cannot be null. It is the core of the grep-search algorithm. If the programmer wishes to rely on the standard 'token-search' or 'regular-expression-search' methods defined in class 'SearchAndPrint' - then the programmer should simply use one of the standard factory methods provided in 'SearchAndPrint' to build an instance of this class.
        ioeh - When performing these UNIX-GREP styled text-file searches, it becomes imperative to catch any potential IOException's so that if one file is failing to load to Java, the rest of the entire search will not be sacrificed or ceased. Using this parameter allows a programmer to log exceptions, or take any user-defined action when any potential IOException's occur while reading the files in a directory tree. Using this exception-handler allows the GREP-Search to continue, even if reading one particular file fails.

        NOTE: This parameter may be null, and if it is, it will be ignored - and all exceptions shall suppressed. This means that no exception information will be reported back to the user. If this parameter is null, and if an IOException is generated while traversing a particular file for GREP-search, that file will merely be skipped (gracefully), and its contents will not be searched.
        Returns:
        The return-list shall contain a reference of every instance of FileNode for which whose contents on the file-system contained a match - as determined by the SearchAndPrint instance that is passed to parameter 'sp'.

        class RTC allows a user of this API to specify this method's Return-Type. There are dozens of options included for choosing which Reference-Container Type to return, what Sorting-Method to employ, and even for selecting the how the FileNode instances are returned: File-Name String Full-PathString, FileNode etc..

        See: class RTC for details
        See Also:
        SearchAndPrint, FileRW.loadFileToString(String), FileNode.isDirectory, FileNode.toString(), SearchAndPrint.test(String, String), IOExceptionHandler.accept(FileNode, IOException)
        Code:
        Exact Method Body:
         while (iter.hasNext())
 {
     FileNode fn = iter.next();

     if (fn.isDirectory) continue;

     try
     {
         String  fileContents    = FileRW.loadFileToString(fn.toString());
         boolean wasMatch        = sp.test(fn.toString(), fileContents);

         if (wasMatch) dataStructureChoice.inserter.accept(fn);
     }

     catch (IOException e)
         { if (ioeh != null) ioeh.accept(fn, e); }
 }

 return dataStructureChoice.finisher.get();

      • searchFile

        🡅  ⇈  ⮫ 🗕  🗗  🗖 
        public static boolean searchFile​(FileNode file,
                                 SearchAndPrint sp,
                                 IOExceptionHandler ioeh)
        This version of GREP shall search a single file only. The passed parameter 'file' must be a FileNode instance that represents a UNIX or MS-DOS file, not a directory.
        Parameters:
        file - This is the file to be searched or "GREPPED."
        sp - The 'sp' parameter is the implementation of the file-grep operation that the user is requesting. The actions that this SearchAndPrint method-pointer should perform include:

        • Test if the file contains a match - using whatever string-testing procedure required. Usually either a simple String token is being searched, or an entire String regular-expression is used.
        • Do some kind of output printing to a writable printing parameter to report these String-match results
        • return either TRUE or FALSE to indicate whether or not a particular file contained matches.

        IMPORTANT: This parameter cannot be null. It is the core of the grep-search algorithm. If the programmer wishes to rely on the standard 'token-search' or 'regular-expression-search' methods defined in class 'SearchAndPrint' - then the programmer should simply use one of the standard factory methods provided in 'SearchAndPrint' to build an instance of this class.
        ioeh - This parameter may be used, or it may be left null. It is less emphasized here, because only a single file is being searched. That file is specified in the parameters to this method. Since there is only one file to search, catching the IOException's makes little difference because GREP-search on other files will not be hindered, since there are no other files being searched.
        Returns:
        A value of TRUE shall indicate that there was a match found.
        Throws:
        FileExpectedException - The parameter 'file' must actually be a 'file' instance of FileNode. If 'file' is not actually a file, but rather a directory, then this exception shall throw.
        See Also:
        FileExpectedException.check(FileNode), FileRW.loadFileToString(String), FileNode.toString(), SearchAndPrint.test(String, String), IOExceptionHandler.accept(FileNode, IOException)
        Code:
        Exact Method Body:
         // Can only test files, not directories...
 FileExpectedException.check(file);

 // Test to see if there is a match
 try
     { return sp.test(file.toString(), FileRW.loadFileToString(file.toString())); }

 catch (IOException e)
     { if (ioeh != null) ioeh.accept(file, e); return false; }