plume

Class Lookup

@Nullable java.lang.Object

plume.Lookup

public class Lookup
extends @Nullable java.lang.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:

• Getting help
  • -h --help=boolean. Show detailed help information and exit. [default false]
  • -v --verbose=boolean. Print progress information [default false]
• Where to search
  • -f --entry-file=string. 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. [default ~/lookup/root]
  • -b --search-body=boolean. Search the body of long entries in addition to the entry's description. The bodies of short entries are always searched. [default false]
• 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.
  • -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. Regex that denotes the start of a long entry [default ^>entry *()]
  • --entry-stop-re=regex. Regex that denotes the end of a long entry [default ^<entry]
  • --description-re=regex. Regex that finds an entry's description (for long entries)
  • --comment-re=string. Regex that matches an entire comment (not just a comment start) [default ^%.*]
  • --include-re=string. Regex that matches an include directive; group 1 is the file name [default \\include\{(.*)\}]

Field Summary

Fields

Modifier and Type	Field and Description
static boolean	case_sensitive If true, keywords matching is case sensistive.
static @Nullable java.lang.String	comment_re
static @Regex(value=1) java.util.regex.Pattern	description_re
static @Nullable java.lang.String	entry_file Specify the colon-separated search list for the file that contains information to be searched.
static @Regex(value=1) java.util.regex.Pattern	entry_start_re
static @Regex(value=1) java.util.regex.Pattern	entry_stop_re
static boolean	help Show detailed help information and exit.
static @Nullable java.lang.String	include_re
static @Nullable java.lang.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
static boolean	word_match If true, match a text keyword only as a separate word, not as a substring of a word.

Constructor Summary

Constructors

Constructor and Description
Lookup()

Method Summary

Methods

Modifier and Type	Method and Description
static @Nullable java.lang.String	first_line(@Nullable java.lang.String entry) Returns the first line of entry.
static void	main(java.lang.String[] args) Look for the specified keywords in the file(s) and print the corresponding entries.
static @Nullable EntryReader.Entry	old_get_entry(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 Detail

help

public static boolean help

Show detailed help information and exit.

verbose

public static boolean verbose

entry_file

public static @Nullable java.lang.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.

print_all

public static boolean print_all

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.

item_num

public static @Nullable java.lang.Integer item_num

Specifies which item to print when there are multiple matches.

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(value=1) java.util.regex.Pattern entry_start_re

entry_stop_re

public static @Regex(value=1) java.util.regex.Pattern entry_stop_re

description_re

public static @Regex(value=1) java.util.regex.Pattern description_re

comment_re

public static @Nullable java.lang.String comment_re

include_re

public static @Nullable java.lang.String include_re

Constructor Detail

Lookup

public Lookup()

Method Detail

main

public static void main(java.lang.String[] args)
                 throws java.io.IOException

Look for the specified keywords in the file(s) and print the corresponding entries.

Throws:

java.io.IOException

old_get_entry

public static @Nullable EntryReader.Entry old_get_entry(EntryReader reader)
                                        throws java.io.IOException

Returns the next entry. If no more entries are available, returns null.

Throws:

java.io.IOException

first_line

public static @Nullable java.lang.String first_line(@Nullable java.lang.String entry)

Returns the first line of entry.