Package org.plumelib.lookup

Class Lookup

java.lang.Object
org.plumelib.lookup.Lookup
public final class Lookup extends Object
Lookup searches a set of files, much like grep does. However, Lookup searches by entry (by default, paragraphs) rather than by line, respects comments (ignores matches within them), respects \include directives (searches the named file), and has other features.

Each search criterion is a keyword or regular expression. Lookup outputs each entry that matches all the search criteria.

By default, search criteria are treated as keywords, and each paragraph is treated as an entry — in other words, Lookup prints each paragraph (in any of the files) that contains all the keywords, essentially performing paragraph-wise grep.

A file can contain one or more entries, each of which is a short entry or a long entry.

  • A short entry is a single paragraph (delimited from the next entry by a blank line). Lookup searches all of a short entry.
  • A long entry is introduced by a line that begins with '>entry'. The remainder of that line is a one-line description of the entry. A long entry is terminated by ' <entry', by the start of a new long entry, or by the start of a new file. Lookup searches only the first line of a long entry.

If multiple entries match, the first line of each is printed. If only one entry matches, then that entry is printed in its entirety.

By default, Lookup searches the file ~/lookup/root. Files can contain comments and can include other files. Comments start with a % sign in the first column. Any comment line is ignored (it is not treated as a blank line for the purpose of separating entries). A file can include another file via a line of the form '\include{filename}'.

The default behavior can be customized by way of command-line options.

The command-line options are as follows:

  • What to search for
    • -e --regular-expressions=boolean. Specifies that keywords are regular expressions. If false, keywords are text matches. [default: false]
    • -c --case-sensitive=boolean. If true, keywords matching is case sensistive. By default, both regular expressions and text keywords are case-insensitive. [default: false]
    • -w --word-match=boolean. If true, match a text keyword only as a separate word, not as a substring of a word. This option is ignored if regular_expressions is true. [default: false]
  • How to print matches
    • -a --print-all=boolean. By default, if multiple entries are matched, only a synopsis of each entry is printed. If 'print_all' is selected then the body of each matching entry is printed. [default: false]
    • -i --item-num=integer. Specifies which item to print when there are multiple matches. The index is 1-based; that is, it starts counting at 1.
    • -l --show-location=boolean. If true, show the filename/line number of each matching entry in the output. [default: false]
  • Customizing format of files to be searched
    • --entry-start-re=regex. Matches the start of a long entry. [default: ^>entry *()]
    • --entry-stop-re=regex. Matches the end of a long entry. [default: ^<entry]
    • --description-re=regex. Matches the description for a long entry.
    • --comment-re=string. Matches an entire comment. [default: ^%.*]
    • --include-re=string. Matches an include directive; group 1 is the file name. [default: \\include\{(.*)\}]
  • Getting help
    • -h --help=boolean. Show detailed help information and exit. [default: false]
    • -v --verbose=boolean. Print progress information. [default: false]

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static boolean
    case_sensitive
    If true, keywords matching is case sensistive.
    static @Nullable @Regex String
    comment_re
    Matches an entire comment.
    static @Nullable Pattern
    description_re
    Matches the description for a long entry.
    static String
    entry_file
    Specify the colon-separated search list for the file that contains information to be searched.
    static @Regex(1) Pattern
    entry_start_re
    Matches the start of a long entry.
    static Pattern
    entry_stop_re
    Matches the end of a long entry.
    static boolean
    help
    Show detailed help information and exit.
    static @Regex(1) String
    include_re
    Matches an include directive; group 1 is the file name.
    static @Nullable Integer
    item_num
    Specifies which item to print when there are multiple matches.
    static boolean
    print_all
    By default, if multiple entries are matched, only a synopsis of each entry is printed.
    static boolean
    regular_expressions
    Specifies that keywords are regular expressions.
    static boolean
    search_body
    Search the body of long entries in addition to the entry's description.
    static boolean
    show_location
    If true, show the filename/line number of each matching entry in the output.
    static boolean
    verbose
    Print progress information.
    static boolean
    word_match
    If true, match a text keyword only as a separate word, not as a substring of a word.

  • Method Summary

    Modifier and Type
    Method
    Description
    static String
    firstLine(String entry)
    Returns the first line of entry.
    static void
    main(String[] args)
    Look for the specified keywords in the file(s) and print the corresponding entries.
    static @Nullable org.plumelib.util.EntryReader.Entry
    old_getEntry(org.plumelib.util.EntryReader reader)
    Returns the next entry.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • entry_file

      public static String entry_file
      Specify the colon-separated search list for the file that contains information to be searched. Only the first file found is used, though it may itself contain include directives.

    • search_body

      public static boolean search_body
      Search the body of long entries in addition to the entry's description. The bodies of short entries are always searched.

    • regular_expressions

      public static boolean regular_expressions
      Specifies that keywords are regular expressions. If false, keywords are text matches.

    • case_sensitive

      public static boolean case_sensitive
      If true, keywords matching is case sensistive. By default, both regular expressions and text keywords are case-insensitive.

    • word_match

      public static boolean word_match
      If true, match a text keyword only as a separate word, not as a substring of a word. This option is ignored if regular_expressions is true.

    • item_num

      public static @Nullable Integer item_num
      Specifies which item to print when there are multiple matches. The index is 1-based; that is, it starts counting at 1.

    • show_location

      public static boolean show_location
      If true, show the filename/line number of each matching entry in the output.

    • entry_start_re

      public static @Regex(1) Pattern entry_start_re
      Matches the start of a long entry.

    • entry_stop_re

      public static Pattern entry_stop_re
      Matches the end of a long entry.

    • description_re

      public static @Nullable Pattern description_re
      Matches the description for a long entry.

    • comment_re

      public static @Nullable @Regex String comment_re
      Matches an entire comment.

    • include_re

      public static @Regex(1) String include_re
      Matches an include directive; group 1 is the file name.

    • help

      public static boolean help
      Show detailed help information and exit.

    • verbose

      public static boolean verbose
      Print progress information.

  • Method Details

    • main

      public static void main(String[] args) throws IOException
      Look for the specified keywords in the file(s) and print the corresponding entries.
      Parameters:
      args - command-line arguments; see documentation
      Throws:
      IOException - if there is a problem reading a file

    • old_getEntry

      public static @Nullable org.plumelib.util.EntryReader.Entry old_getEntry(org.plumelib.util.EntryReader reader) throws IOException
      Returns the next entry. If no more entries are available, returns null.
      Parameters:
      reader - where to read the entry from
      Returns:
      the next entry, or null
      Throws:
      IOException - if there is a problem reading a file

    • firstLine

      public static String firstLine(String entry)
      Returns the first line of entry.
      Parameters:
      entry - the entry whose first line to return
      Returns:
      the first line of entry