vn
Class Inspector

java.lang.Object
  vn.Inspector

public class Inspector
extends Object

The driver class for the Inspector. This class parses the command-line arguments given to it and scans the VerbNet XML files while taking the desired actions. The arguments are used to set flag and view option variables that both this class and the Sweeper class use to customize the output. There are five operators added to the original Inspector to implement the VxC application: -C, -M, -F, A, and -S. Look at the full usage for further details. The general usage is:

   java vn.Inspector [flags] <x> [-V <v>] [-O <o>] -C <c> -M <m> -F <f> [-A <a>] [-S <s>]

See the usage note (java vn.Inspector -?) for full details.

Although the Inspector has two basic output modes: normal output mode, and class hierarchy mode, VxC is almost always run without either the -V opreator or -c flag supplied. VxC relies completely on the event system and its own external file manipulation. The -C operator specifies the Cyc input file containing all the verbSemTrans semantic predicates. The -M operator specifies the manual mapping file against which to compare automatic mapping results. The -F operator is the location of the file into which all the automatic matches should be placed.

There are two optional VxC operators, -A and -S. The -A operator specifies the constraints(s) to use when deciding which matches are valid and which should be discarded. The -S operator is similar to [flags], and just passes VxC-specific flags onto the underlying mapping system.

The default action is to process all XML files in the XML input directory. The -O operator allows the user to limit the processing to specific XML files, in order to avoid processing unwanted files. VxC is almost never run with the -O operator. It needs to look over matches from all the files. However, there is a Cyc.flManualClassesOnly flag (set with -Sm) which skips over those classes and subclasses not included in the manual mapping. This is useful for analysis of the rules chosen to determine a match between VN and Cyc - you can just concentrate on the classes for which you'll get a statistical measure of success (the manual mapping classes).

Errors are sent to stderr. All other output is sent to stdout. There are very few errors generated in the Inspector and usually deal with validating the command-line parameters. If using the Inspector as a stand-alone application you may use your shell to redirect the output to a file:

 sh/bash/csh/tcsh:
    java vn.Inspector verbnet-xml/ -Vfcm -Och > output

However, if you are embedding these classes in an application, then you can utilize the System.setOut(PrintStream) method to redirect stdout to an external file from within the Java code. One would most likely call this method in the 'start' event for the program in EventManager.fireEvent(int, int, String, String, String, Element, Element).

For debugging purposes, the Cyc.flShowDiscards flag (set with -Sd) option forces a line of text to be printed to stderr for each naive match that was discarded (after having the constraints specified by the -A operator applied to it). This text includes what naive match it was and why it was discarded. You can redirect stderr to a file with:

 sh/bash:
    java vn.Inspector verbnet-xml/ [...] -Sd 2> reasons-for-discard

 csh/tcsh:
    ( java vn.Inspector verbnet-xml/ [...] -Sd > temp ) >& reasons-for-discard

Above, [...] represents all the other operators and flags you would supply for the execution (i.e. -C, -M, -F). For csh/tcsh shells, the temp file is required to properly extract just the errors from the program into reasons-for-discard.

The only changes made to this class for the VxC extension pertained to adding the new command-line arguments. The usage/help message was modified and analyzeArguments(String[]) was enhanced to validate them and pass them on to the Cyc class.

For information about adding command line parameters when extending the Inspector into a custom application, refer to the last section of the Extension Guide.

The Inspector is ready for use right out of the box. There is very little to configure. However, these notes (all of which shown on Inspector, Sweeper, and EventManager classes) provide some more logistical details about the software.

NOTE 1: The Inspector is implemented almost entirely with static methods. Text parsing and scanning is a very serial process and the Inspector would only have been made more complicated with a more object-oriented scheme.

NOTE 2: The Inspector produces simple-text representations for frame syntax which are congruent with the representations for frame syntax presented in the Unified Verb Index. The only difference is that the UVI represents noun phrase thematic roles with underline (Agent) and the Inspector represents them with a preceding % sign (%Agent). Look at the UVI's key or the Inspector's key (-k option on command line) for more information.

NOTE 3: Use of the Inspector, either by extension or by insertion into an existing application, requires the entirety of the VerbNet XML files. They may be placed anywhere in relation to the Inspector source code, as the only required argument to the Inspector is this XML input directory path. They can be downloaded here. Finally, the DTD file contained in this download is required to be in the same directory as the XML files (it's already there, just don't remove it).

NOTE 4: This software assumes that the XML files it is processing match the VerbNet DTD. This means that elements appear in the proper order (MEMBERS, THEMROLES, FRAMES, SUBCLASSES) and all tag names are in upper case (i.e. <FRAME>). The files available for download should match the DTD almost 100%.

NOTE 5: This documentation utilizes the terms 'researcher' and 'future developer' so as to reduce confusion as much as possible. A researcher is one who downloads the Inspector source code from the website with the intention of extending it for his or her own purposes, or integrating it into an existing NLP application. A future developer is a member of the University of Colorado team responsible for the Inspector who might modify or enhance it over time. This documentation is written for both parties.

NOTE 6: This Javadoc documentation is not written like a standard public API might be written. First, all private members are displayed here because this is also made to be convenient documentation for future developers. Second, all "See Also" links below actually reference other places in the code that reference or are referenced by the given member. This is in contrast to public API documentation, in which the "See Also" links commonly refer the reader to class members of related or contrasted functionality.

NOTE 7: Although originally written with a few Java 1.5 features, the Inspector was downgraded so as to be compilable with javac 1.4.2. The reason for this was so researchers did not need to download and run Java 1.5 for this software. This software will however work with Java 1.5. If you do not have Java installed on your system, download the most recent release right here. Also, here are links to the 1.4.2 documentation and the 1.5.0 documentation.

Version:

1.0, 2006.10.25

Author:

Derek Trumbo

Nested Class Summary

private static class	Inspector.InvalidCommandLineArgumentException Exception class for identifying when the user did not supply a command-line of the proper format.
private static class	Inspector.InvalidPathException Exception class for identifying when the user did not supply a valid XML input directory.
private static class	Inspector.MyFilter Decides which files to select for the File.listFiles() method of the File class.
private static class	Inspector.UserWantsHelpMessage Exception class for identifying when the user requests to view the help/usage message for the program.
private static class	Inspector.UserWantsKey Exception class for identifying when the user requests to view the key.

Field Summary

private static String	ALL_OPER_CHARS All operators used on the command line.
private static String	ALL_VIEW_OPTS All view options.
private static String[]	allOnlyFiles An array representing all the tokens supplied to the -O operator.
(package private) static String	flags A string representation of all of the flags supplied on the command line.
(package private) static boolean	flClassCounts A flag set in analyzeArguments(String[]) and used to indicate that the user would like to view count information for each class and subclass that is displayed in normal output.
(package private) static boolean	flClassH A flag set in analyzeArguments(String[]) and used to indicate that the user would like to see the class hierarchy.
(package private) static boolean	flErrProgress A flag set in analyzeArguments(String[]) and used to indicate that the user would like each file name to be printed to stderr as it is encountered.
(package private) static boolean	flHelp A flag set in analyzeArguments(String[]) and used to indicate that the user would like to see the help/usage message.
(package private) static boolean	flIndent A flag set in analyzeArguments(String[]) and used to indicate that the user would like both the normal output and class hierarchy indented.
(package private) static boolean	flKey A flag set in analyzeArguments(String[]) and used to indicate that the user would like to see the key for the thematic role and syntax restrictions.
(package private) static boolean	flNoAbsence A flag set in analyzeArguments(String[]) and used to indicate that the user would like to supress the absence labels in the normal output and class hierarchy.
(package private) static boolean	flNoFinalCounts A flag set in analyzeArguments(String[]) and used to indicate that the user would like to suppress the final count information that is printed after normal output and class hierarchy.
(package private) static boolean	flNoHeader A flag set in analyzeArguments(String[]) and used to indicate that the user would like to suppress the header information that is printed before normal output and class hierarchy.
(package private) static boolean	flReplicate A flag set in analyzeArguments(String[]) and used to print all the labels that represent additional nesting (file, class, subclass, and frame) before every element that is printed.
(package private) static boolean	flSortMembers A flag set in analyzeArguments(String[]) and used to indicate that the user would like the verbs in the members section sorted.
(package private) static boolean	flSuppressEvents A flag set in analyzeArguments(String[]) and used to suppress the firing of all events.
(package private) static boolean	flVFPairs A flag set in analyzeArguments(String[]) and used to indicate that the user would like the Inspector to run in verb-frame pair mode.
(package private) static boolean	flVFPairsInvert A flag set in analyzeArguments(String[]) and used to indicate that the user would like the Sweeper to visit verb-frame pairs in frame-major order instead of a verb-major order.
(package private) static boolean	flZeroCounts A flag set in analyzeArguments(String[]) and used to indicate that the user would like to view those counts in both class counts and final counts that are equal to zero in addition to the non-zero counts.
private static String	onlyTheseFiles The files that the user has requested to see.
private static HashMap	tagCounterClass A map which ties an integer to a string.
private static HashMap	tagCounterGlobal A map which ties an integer to a string.
(package private) static String	viewOpts A string representation of all of the view options supplied on the command line.
private static File	vnDir The directory where the VerbNet XML files are located.
(package private) static boolean	voAll A view option set in analyzeArguments(String[]) and used to enable all basic view options in normal output mode.
(package private) static boolean	voClassName A view option set in analyzeArguments(String[]) and used to display class and subclass names in normal output mode.
(package private) static boolean	voComplete A view option set in analyzeArguments(String[]) and used to display non-standard attributes in normal output mode.
(package private) static boolean	voCount A view option set in analyzeArguments(String[]) and used to display member and frame counts in normal output mode.
(package private) static boolean	voExample A view option set in analyzeArguments(String[]) and used to display examples in normal output mode.
(package private) static boolean	voFileName A view option set in analyzeArguments(String[]) and used to display file names in normal output mode.
(package private) static boolean	voFrame A view option set in analyzeArguments(String[]) and used to display frame descriptions in normal output mode.
(package private) static boolean	voMember A view option set in analyzeArguments(String[]) and used to display member (verbs) in normal output mode.
(package private) static boolean	voSemantics A view option set in analyzeArguments(String[]) and used to display semantics in normal output mode.
(package private) static boolean	voSyntax A view option set in analyzeArguments(String[]) and used to display syntax in normal output mode.
(package private) static boolean	voThemRole A view option set in analyzeArguments(String[]) and used to display thematic roles in normal output mode.
(package private) static boolean	voTRSelRestr A view option set in analyzeArguments(String[]) and used to display selectional restrictions for thematic roles in normal output mode.
(package private) static boolean	voVFPairs A view option set in analyzeArguments(String[]) and used to display verb-frame pair descriptions in normal output mode.
(package private) static boolean	voWordNet A view option set in analyzeArguments(String[]) and used to display WordNet senses in normal output mode.
(package private) static boolean	voXSelRestr A view option set in analyzeArguments(String[]) and used to display selectional restrictions for noun phrases in normal output mode.
(package private) static boolean	voXSynRestr A view option set in analyzeArguments(String[]) and used to display the current file in normal output mode.
private static File[]	xmlFiles A list of just the XML files located in the XML input directory.

Constructor Summary

private

Inspector() This constructor is private because the class is not intended to ever be instantiated.

Method Summary

private static void	analyzeArguments(String[] args) Validates all of the command-line arguments and sets appropriate class-level variables.
(package private) static void	clearClassTagCounter() Empties the class counts tag counter.
private static void	eprint(String s) Used as shorthand for System.err.print.
private static void	eprintln(String s) Used as shorthand for System.err.println.
private static void	executeHTMLMethod(String which, Node n) Executes a method in the Sweeper class based on an XML element tag name (i.e. 'VNCLASS') and a 'start' or 'end' flag.
(package private) static String	filePath(File f) Returns a descriptive path for a File object.
private static int	getTagCount(HashMap tagCounter, String tagName) Returns the number of times a given tag name was encountered for the given counter.
(package private) static void	incrementTagCounter(String tagName) Increments the counter for a given tag by 1.
(package private) static void	incrementTagCounter(String tagName, int howMany) Increments the counter for a given tag by a given integer.
static void	main(String[] args) The main method of the program.
private static void	performInspection() Performs the scanning of the XML files in the XML input directory.
private static void	print(String s) Used as shorthand for System.out.print.
private static void	printHeader() Prints the header for this execution of the Inspector.
private static void	printKey() Prints the thematic role and syntax key.
private static void	println(String s) Used as shorthand for System.out.println.
private static void	printTagCount(HashMap tagCounter, String tagName) Prints a tag name along with the number of times it was encountered.
(package private) static void	printTagCounts(boolean useClassCounter) Prints all the counts from either the class counts tag counter or the final counts tag counter.
private static void	printUsage() Prints the usage (a.k.a. help message) for the Inspector.
private static void	processNode(Node n) Starts by outputting the simple text you would want to output upon encountering the start of the given node, then recursively prints all the simple text associated with this node's children nodes, and finally outputs the simple text needed for the close of the given node.
(package private) static void	processNodeByPairs(Node n, ArrayList prevFrames) Starts by outputting the simple text you would want to output upon encountering the start of the given node, then recursively prints all the simple text associated with this node's children nodes, and finally outputs the simple text needed for the close of the given node.
static void	run(String commandLine) Executes the Inspector application.
private static void	sortXMLFiles() Sorts the already loaded XML files array xmlFiles.
private static String	together(String[] array) Concatenates all the elements in a string array, separated by spaces.
(package private) static String	wrapString(String s) Massages a string that could be null for the header.

Methods inherited from class java.lang.Object

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

Field Detail

vnDir

private static File vnDir

The directory where the VerbNet XML files are located. This is the only required argument to the Inspector. The path supplied must exist, be a directory, and be readable by the Inspector.

See Also:

analyzeArguments(String[]), printHeader()

xmlFiles

private static File[] xmlFiles

A list of just the XML files located in the XML input directory. A filter is used (Inspector.MyFilter) to list just the XML files.

See Also:

analyzeArguments(String[]), performInspection()

flags

static String flags

A string representation of all of the flags supplied on the command line. All flags can be separate from one another or combined into a single command line token. This string accumulates all the flags supplied on the command line so they can all be printed out nicely in the header.

See Also:

analyzeArguments(String[]), printHeader()

flHelp

static boolean flHelp

A flag set in analyzeArguments(String[]) and used to indicate that the user would like to see the help/usage message. This flag is set with the -? option. If this option is supplied, the program prints the usage message and exits. No further processing occurs.

See Also:

analyzeArguments(String[])

flKey

static boolean flKey

A flag set in analyzeArguments(String[]) and used to indicate that the user would like to see the key for the thematic role and syntax restrictions. This flag is set with the -k option. If this option is supplied, the program prints the key and exits. No further processing occurs.

See Also:

analyzeArguments(String[])

flClassH

static boolean flClassH

A flag set in analyzeArguments(String[]) and used to indicate that the user would like to see the class hierarchy. This flag is set with the -c option. If this option is supplied, the program prints the class hierarchy and exits. No further processing occurs. The -V operator is ignored and the -m option is not honored. Only final counts can be seen when viewing the class hierarchy.

See Also:

analyzeArguments(String[]), processNode(Node), Sweeper.startVNCLASS(Node), Sweeper.classHierarchyPrint(Element, int)

flNoHeader

static boolean flNoHeader

A flag set in analyzeArguments(String[]) and used to indicate that the user would like to suppress the header information that is printed before normal output and class hierarchy. This flag is set with the -h option.

See Also:

analyzeArguments(String[]), main(String[])

flNoFinalCounts

static boolean flNoFinalCounts

A flag set in analyzeArguments(String[]) and used to indicate that the user would like to suppress the final count information that is printed after normal output and class hierarchy. This flag is set with the -n option.

See Also:

analyzeArguments(String[]), main(String[])

flClassCounts

static boolean flClassCounts

A flag set in analyzeArguments(String[]) and used to indicate that the user would like to view count information for each class and subclass that is displayed in normal output. This flag is set with the -m option. This option has no effect when the class hierarchy is printed.

See Also:

analyzeArguments(String[]), incrementTagCounter(String, int), Sweeper.endFRAMES(Node), printTagCounts(boolean)

flZeroCounts

static boolean flZeroCounts

A flag set in analyzeArguments(String[]) and used to indicate that the user would like to view those counts in both class counts and final counts that are equal to zero in addition to the non-zero counts. This flag is set with the -0 option.

See Also:

analyzeArguments(String[]), printTagCounts(boolean), printTagCount(HashMap, String)

flErrProgress

static boolean flErrProgress

A flag set in analyzeArguments(String[]) and used to indicate that the user would like each file name to be printed to stderr as it is encountered. This flag is set with the -w option. This option exists only as a convenience so that if stdout is being redirected to a file, one can still view the progress of the Inspector.

See Also:

analyzeArguments(String[]), performInspection()

flSortMembers

static boolean flSortMembers

A flag set in analyzeArguments(String[]) and used to indicate that the user would like the verbs in the members section sorted. This flag is set with the -s option. If the Inspector is running in verb-frame pair mode (-q or -Vq supplied) then the verb-frame pairs will also be sorted by the verb.

See Also:

analyzeArguments(String[]), Sweeper.startMEMBER(Node), Sweeper.printMembers()

flIndent

static boolean flIndent

A flag set in analyzeArguments(String[]) and used to indicate that the user would like both the normal output and class hierarchy indented. This flag is set with the -i option. Indentation occurs with files, classes, subclasses, and frames. All output which is logically under these elements is indented over one additional indent width. The indent width is 3 spaces.

See Also:

analyzeArguments(String[]), Sweeper.iprintln(String), Sweeper.iprint(String), Sweeper.classHierarchyPrint(Element, int), Sweeper.INDENT_WIDTH

flNoAbsence

static boolean flNoAbsence

A flag set in analyzeArguments(String[]) and used to indicate that the user would like to supress the absence labels in the normal output and class hierarchy. This flag is set with the -z option. An absence label is one of the following: <NO SUBCLASSES>, <NO MEMBERS>, <NO THEMROLES>, <NO FRAMES>, or <NO VF-PAIRS: reason>. The NO SUBCLASSES label is only printed in the class hierarchy. The NO VF-PAIRS label is paired with the reason why there are no verb-frame pairs for that class: no members, no frames, or both.

See Also:

analyzeArguments(String[]), Sweeper.classHierarchyPrint(Element, int), Sweeper.startMEMBERS(Node), Sweeper.startTHEMROLES(Node), Sweeper.startFRAMES(Node), Sweeper.printVerbFramePairs()

flVFPairs

static boolean flVFPairs

A flag set in analyzeArguments(String[]) and used to indicate that the user would like the Inspector to run in verb-frame pair mode. This flag is set with the -q option. The -Vq option implies the -q option. If the -q is set, then -Vm or -Vr imply -Vq.

Essentially a verb is a member of a class because it can participate in each of the frames of that class and each of the frames in ancestor classes. So if there are 5 members in a main class with 4 frames, then there are 20 verb-frame pairs for that class alone. A verb-frame pair means this verb can be used like this. If a subclass of that class contains 2 members and 2 frames, then there are 2 members x (2+4) frames = 12 verb-frame pairs, since members can participate in all frames contained in ancestor classes.

The processing changes in that a different recursive method is used in the driver (processNodeByPairs(Node, ArrayList) instead of processNode(Node)). Also, nothing besides thematic roles is printed until the closing of the FRAMES element. At which point, Sweeper.printVerbFramePairs() is called to print all the pairs.

Regardless of what is sent to stdout, there are almost 30,000 verb-frame pairs in VerbNet, so any execution with the options -q or -Vq could take a few moments (unless you are just looking at a subset of the XML files with the -O operator).

See Also:

analyzeArguments(String[]), performInspection(), Sweeper.startMEMBERS(Node), Sweeper.endMEMBERS(Node), Sweeper.startFRAMES(Node), Sweeper.endFRAMES(Node), Sweeper.startFRAME(Node), Sweeper.endFRAME(Node), Sweeper.startDESCRIPTION(Node), Sweeper.curVFFrameList

flVFPairsInvert

static boolean flVFPairsInvert

A flag set in analyzeArguments(String[]) and used to indicate that the user would like the Sweeper to visit verb-frame pairs in frame-major order instead of a verb-major order. This flag is set with the -v option. This option is ineffective unless -q or -Vq is supplied. To illustrate this option, here is a small table:

Verb Major	Frame Major
VERB 1 - FRAME 1 VERB 1 - FRAME 2 VERB 2 - FRAME 1 VERB 2 - FRAME 2	FRAME 1 - VERB 1 FRAME 1 - VERB 2 FRAME 2 - VERB 1 FRAME 2 - VERB 2

See Also:

analyzeArguments(String[]), Sweeper.printVerbFramePairs()

flSuppressEvents

static boolean flSuppressEvents

A flag set in analyzeArguments(String[]) and used to suppress the firing of all events. If this flag is set, the Inspector is only acting as a VerbNet viewer, printing out those elements of the XML files as specified by the -V operator.

See Also:

analyzeArguments(String[])

flReplicate

static boolean flReplicate

A flag set in analyzeArguments(String[]) and used to print all the labels that represent additional nesting (file, class, subclass, and frame) before every element that is printed. The output becomes abundant but this option is provided only for added interoperability with grep. The additional labels that are printed are still dependent on view options, but do not affect class or final counts.

See Also:

analyzeArguments(String[])

ALL_OPER_CHARS

private static final String ALL_OPER_CHARS

All operators used on the command line. There are two standard Inspector operators (-V and -O) and five VxC application-specific ones (-C, -M, -F, -A and -S). See usage for more details.

See Also:

analyzeArguments(String[]), Constant Field Values

ALL_VIEW_OPTS

private static final String ALL_VIEW_OPTS

All view options. These are all the letters which may comprise <v>, the argument to the -V operator. They may be listed in any order. This string is used to validate and set the appropriate view options in analyzeArguments(String[]).

See Also:

analyzeArguments(String[]), Constant Field Values

viewOpts

static String viewOpts

A string representation of all of the view options supplied on the command line. All view options can be provided in separate -V operators or combined into a single -V operator. This string accumulates all the view options supplied on the command line so they can all be printed out nicely in the header.

See Also:

analyzeArguments(String[]), printHeader()

voFileName

static boolean voFileName

A view option set in analyzeArguments(String[]) and used to display file names in normal output mode. This view option is set with the letter f.

See Also:

analyzeArguments(String[]), Sweeper.startVNCLASS(Node), Sweeper.endVNCLASS(Node)

voClassName

static boolean voClassName

A view option set in analyzeArguments(String[]) and used to display class and subclass names in normal output mode. This view option is set with the letter c.

See Also:

analyzeArguments(String[]), Sweeper.startVNCLASS(Node), Sweeper.endVNCLASS(Node), Sweeper.startVNSUBCLASS(Node), Sweeper.endVNSUBCLASS(Node)

voCount

static boolean voCount

A view option set in analyzeArguments(String[]) and used to display member and frame counts in normal output mode. This view option is set with the letter n. For this view option to have any effect, the -Vc option must also be supplied. Member and frame counts include only the class being processed, not ancestor or descendant classes.

See Also:

analyzeArguments(String[]), Sweeper.startVNCLASS(Node), Sweeper.startVNSUBCLASS(Node)

voMember

static boolean voMember

A view option set in analyzeArguments(String[]) and used to display member (verbs) in normal output mode. This view option is set with the letter m.

See Also:

analyzeArguments(String[]), Sweeper.startMEMBERS(Node), Sweeper.endMEMBER(Node), Sweeper.printMembers()

voWordNet

static boolean voWordNet

A view option set in analyzeArguments(String[]) and used to display WordNet senses in normal output mode. This view option is set with the letter w. For this view option to have any effect, the -Vm option must also be supplied.

See Also:

analyzeArguments(String[]), Sweeper.startDESCRIPTION(Node), Sweeper.printMembers()

voThemRole

static boolean voThemRole

A view option set in analyzeArguments(String[]) and used to display thematic roles in normal output mode. This view option is set with the letter t.

See Also:

analyzeArguments(String[]), Sweeper.startTHEMROLES(Node), Sweeper.endTHEMROLES(Node), Sweeper.startTHEMROLE(Node), Sweeper.endTHEMROLE(Node), Sweeper.startSELRESTRS(Node), Sweeper.endSELRESTRS(Node), Sweeper.startSELRESTR(Node), Sweeper.endSELRESTR(Node)

voTRSelRestr

static boolean voTRSelRestr

A view option set in analyzeArguments(String[]) and used to display selectional restrictions for thematic roles in normal output mode. This view option is set with the letter u. For this view option to have any effect, the -Vt option must also be supplied.

See Also:

analyzeArguments(String[]), Sweeper.startSELRESTRS(Node), Sweeper.endSELRESTRS(Node), Sweeper.startSELRESTR(Node), Sweeper.endSELRESTR(Node)

voFrame

static boolean voFrame

A view option set in analyzeArguments(String[]) and used to display frame descriptions in normal output mode. This view option is set with the letter r.

See Also:

analyzeArguments(String[]), Sweeper.startFRAMES(Node), Sweeper.endFRAMES(Node), Sweeper.startFRAME(Node), Sweeper.endFRAME(Node), Sweeper.startDESCRIPTION(Node), Sweeper.endDESCRIPTION(Node)

voExample

static boolean voExample

A view option set in analyzeArguments(String[]) and used to display examples in normal output mode. This view option is set with the letter e.

See Also:

analyzeArguments(String[]), Sweeper.startEXAMPLES(Node), Sweeper.endEXAMPLES(Node), Sweeper.startEXAMPLE(Node), Sweeper.endEXAMPLE(Node)

voSyntax

static boolean voSyntax

A view option set in analyzeArguments(String[]) and used to display syntax in normal output mode. This view option is set with the letter x. The format used is congruent to the Unified Verb Index save for the noun phrase thematic roles, which are preceded by a % sign instead of underline.

See Also:

analyzeArguments(String[]), Sweeper.startSELRESTRS(Node), Sweeper.endSELRESTRS(Node), Sweeper.startSELRESTR(Node), Sweeper.endSELRESTR(Node), Sweeper.startSYNTAX(Node), Sweeper.endSYNTAX(Node), Sweeper.startNP(Node), Sweeper.endNP(Node), Sweeper.startSYNRESTRS(Node), Sweeper.endSYNRESTRS(Node), Sweeper.startSYNRESTR(Node), Sweeper.endSYNRESTR(Node), Sweeper.startPREP(Node), Sweeper.endPREP(Node), Sweeper.startVERB(Node), Sweeper.endVERB(Node), Sweeper.startADJ(Node), Sweeper.endADJ(Node), Sweeper.startADV(Node), Sweeper.endADV(Node), Sweeper.startLEX(Node), Sweeper.endLEX(Node)

voXSynRestr

static boolean voXSynRestr

A view option set in analyzeArguments(String[]) and used to display the current file in normal output mode. This view option is set with the letter y. For this view option to have any effect, the -Vx option must also be supplied.

See Also:

analyzeArguments(String[]), Sweeper.startSYNRESTRS(Node), Sweeper.endSYNRESTRS(Node), Sweeper.startSYNRESTR(Node), Sweeper.endSYNRESTR(Node)

voXSelRestr

static boolean voXSelRestr

A view option set in analyzeArguments(String[]) and used to display selectional restrictions for noun phrases in normal output mode. This view option is set with the letter z. For this view option to have any effect, the -Vx option must also be supplied. Preposition classes also use selectional restrictions but are not affected by this view option.

See Also:

analyzeArguments(String[]), Sweeper.startSELRESTRS(Node), Sweeper.endSELRESTRS(Node), Sweeper.startSELRESTR(Node), Sweeper.endSELRESTR(Node)

voSemantics

static boolean voSemantics

A view option set in analyzeArguments(String[]) and used to display semantics in normal output mode. This view option is set with the letter s. One line of text is printed for each predicate.

See Also:

analyzeArguments(String[]), Sweeper.startSEMANTICS(Node), Sweeper.endSEMANTICS(Node), Sweeper.startPRED(Node), Sweeper.endPRED(Node), Sweeper.startARGS(Node), Sweeper.endARGS(Node), Sweeper.startARG(Node), Sweeper.endARG(Node)

voAll

static boolean voAll

A view option set in analyzeArguments(String[]) and used to enable all basic view options in normal output mode. This view option is set with the letter a. All basic view options include: fcnmwturexyzs.

See Also:

analyzeArguments(String[])

voVFPairs

static boolean voVFPairs

A view option set in analyzeArguments(String[]) and used to display verb-frame pair descriptions in normal output mode. This view option is set with the letter q. This forces the Inspector to run in verb-frame pair mode (see flVFPairs). This view option will display the line which shows the the verb and the frame description. Examples, syntax, and semantics will follow this line, if their corresponding view options are supplied. Although the flag flVFPairs creates most of the processing changes for verb-frame pairs, this flag makes sure the counters get incremented if a verb-frame pair description is printed and decides whether or not to print the absence label if a class or subclass has no verb-frame pairs.

See Also:

analyzeArguments(String[]), Sweeper.startFRAME(Node), Sweeper.printVerbFramePairs()

voComplete

static boolean voComplete

A view option set in analyzeArguments(String[]) and used to display non-standard attributes in normal output mode. This view option is set with the letter b. The non-standard attributes that are included are: DESCRIPTION/descriptionNumber, DESCRIPTION/xtag, and ARG/type. So to view as much of the XML files as possible, use -Vab.

See Also:

analyzeArguments(String[]), Sweeper.startDESCRIPTION(Node), Sweeper.startARG(Node)

onlyTheseFiles

private static String onlyTheseFiles

The files that the user has requested to see. This string remains null if the user did not specify the -O operator. If the user did not specify the -O operator, then all the XML files in the input directory are proessed. If the -O operator is supplied, its argument limits which XML files that are actually processed. Only those files whose names start with one of the tokens supplied to -O will be processed. For example, a possible value for this variable could be "ch,care" if the user supplied the option "-Och,care". If one of the tokens is not the beginning of any XML file name (i.e. -Oxyz), then it is ignored.

See Also:

analyzeArguments(String[]), printHeader(), performInspection()

allOnlyFiles

private static String[] allOnlyFiles

An array representing all the tokens supplied to the -O operator. The argument to the -O operator is a comma-delimited list of tokens. That list is broken apart into an array inside analyzeArguments(String[]). Later, each XML file is compared against the elements in this array. If its name starts with any one of the elements of this array, it is processed.

See Also:

analyzeArguments(String[]), performInspection()

tagCounterClass

private static HashMap tagCounterClass

A map which ties an integer to a string. In our case the integer is the number of times that the string has been encountered and the string is the label preceding each line of simple text sent to stdout. These labels are: FILE, CLASS, SUBCLASS, MEMBER, THEMROLE, FRAME, EXAMPLE, SYNTAX, SEMANTIC PRED, VF-PAIR. Counters hold only those labels that are actually printed to stdout, not those only for which events are fired. This counter holds the counts for each label (or "tag") for a given class or subclass ("class counts"). It is reset right before each new class or subclass begins. This counter is only active if the -m option is supplied.

See Also:

incrementTagCounter(String, int), clearClassTagCounter(), printTagCounts(boolean)

tagCounterGlobal

private static HashMap tagCounterGlobal

A map which ties an integer to a string. In our case the integer is the number of times that the string has been encountered and the string is the label preceding each line of simple text sent to stdout. These labels are: FILE, CLASS, SUBCLASS, MEMBER, THEMROLE, FRAME, EXAMPLE, SYNTAX, SEMANTIC PRED, VF-PAIR. Counters hold only those labels that are actually printed to stdout, not those only for which events are fired. This counter holds the counts for each label (or "tag") for the entire execution of the program ("final counts").

See Also:

incrementTagCounter(String, int), printTagCounts(boolean)

Constructor Detail

Inspector

private Inspector()

This constructor is private because the class is not intended to ever be instantiated. The Inspector is a very procedural process and thus all the members are static.

Method Detail

println

private static void println(String s)

Used as shorthand for System.out.println.

Parameters:

s - the string to print to stdout, followed by a carriage return

See Also:

PrintStream.println(String)

print

private static void print(String s)

Used as shorthand for System.out.print.

Parameters:

s - the string to print to stdout

See Also:

PrintStream.print(String)

eprintln

private static void eprintln(String s)

Used as shorthand for System.err.println.

Parameters:

s - the string to print

See Also:

PrintStream.println(String)

eprint

private static void eprint(String s)

Used as shorthand for System.err.print.

Parameters:

s - the string to print

See Also:

PrintStream.print(String)

together

private static String together(String[] array)

Concatenates all the elements in a string array, separated by spaces.

Parameters:

array - the string array

Returns:

a single string that is the concatenation of all the given array elements with spaces between each pair of elements

See Also:

main(String[])

sortXMLFiles

private static void sortXMLFiles()

Sorts the already loaded XML files array xmlFiles. This is because different operating systems will return a directory's contents in different orders but we want to always process the files in a consistent fashion.

main

public static void main(String[] args)

The main method of the program. It first scans the command line and then performs the processing of the XML files.

Parameters:

args - the command line arguments supplied to the Inspector

See Also:

analyzeArguments(String[]), performInspection(), printHeader(), printTagCounts(boolean)

run

public static void run(String commandLine)

Executes the Inspector application. Both this method and the main method execute the Inspector application, but this method is a wrapper for the main method that facilitates the easy integration of the Inspector into an existing application. The main method is required to execute the Inspection as a stand-alone application on the command line. The main method can also be invoked from another application but it requires an array of strings for the command line arguments, which is more complicated to produce than a single string of arguments. Here is how the Inspector would be invoked using the main method (for example):

vn.Inspector.main( new String[] { "../vn-xml", "-Vab", "-ir", "-Ocare" } );

The same thing can be accomplished more easily using this method:

vn.Inspector.run( "../vn-xml -Vab -ir -Ocare" );

The command line arguments can contain any number of spaces or tabs before, after, and between each one (just like the normal command line). See the Extension Guide for more information.

Parameters:

commandLine - a single string of all the command line arguments, separated by spaces

See Also:

main(String[])

printUsage

private static void printUsage()

Prints the usage (a.k.a. help message) for the Inspector.

See Also:

main(String[])

printKey

private static void printKey()

Prints the thematic role and syntax key.

See Also:

main(String[])

printHeader

private static void printHeader()

Prints the header for this execution of the Inspector. All command line arguments are regurgitated and the date and time of this execution is shown.

See Also:

main(String[]), wrapString(String), filePath(File)

wrapString

static String wrapString(String s)

Massages a string that could be null for the header. All the variables flags, vnDir, viewOpts, and onlyTheseFiles begin as null and are only given values if they have a corresponding value on the command line.

Parameters:

s - the string to massage

Returns:

the string given if it is not null, or the message "" if it is

See Also:

printHeader()

filePath

static String filePath(File f)

Returns a descriptive path for a File object. This is only a distinct method due to the possibility of the more desired method, File.getCanonicalPath() to throw an exception. If an exception is thrown, the basic File.getPath() is returned.

Parameters:

f - the file whose path to retrieve

Returns:

a descriptive path

See Also:

printHeader()

incrementTagCounter

static void incrementTagCounter(String tagName)

Increments the counter for a given tag by 1. This is used all over the sweeper method to count those tags (i.e. CLASS or THEMROLE) which are printed. Only those tags which are printed are counted. The counters for FILE and CLASS will always be identical if both -Vf and -Vc are supplied since there is exactly one main class per XML file. This method increments both the class counts tag counter and the final counts tag counter simultaneously.

Parameters:

tagName - the name of the tag whose counter to increment by 1

See Also:

tagCounterClass, tagCounterGlobal, Sweeper.startVNCLASS(Node), Sweeper.startVNSUBCLASS(Node), Sweeper.startTHEMROLE(Node), Sweeper.startFRAME(Node), Sweeper.startEXAMPLE(Node), Sweeper.startSYNTAX(Node), Sweeper.startPRED(Node), Sweeper.printMembers(), Sweeper.classHierarchyPrint(Element, int)

incrementTagCounter

static void incrementTagCounter(String tagName,
                                int howMany)

Increments the counter for a given tag by a given integer. This method is used directly by Sweeper.classHierarchyPrint(Element, int) to increment member and frame counters more quickly and indirectly by all thosme methods which directly call incrementTagCounter(String). This me,hod increments both the class counts tag counter and the final counts tag counter simultaneously.

Parameters:

tagName - the name of the tag whose counter to increment by howMany

howMany - the number of times to increment the tag counter for tagName

See Also:

tagCounterGlobal, Sweeper.classHierarchyPrint(Element, int), incrementTagCounter(String)

clearClassTagCounter

static void clearClassTagCounter()

Empties the class counts tag counter. Called at the start of each new class or subclass.

See Also:

Sweeper.startVNCLASS(Node), Sweeper.startVNSUBCLASS(Node)

printTagCounts

static void printTagCounts(boolean useClassCounter)

Prints all the counts from either the class counts tag counter or the final counts tag counter. The class counts, if the appropriate flag is supplied, are printed before each new class or subclass begins at the closing of the FRAMES element, since that will always be the last element in a VNCLASS or VNSUBCLASS element. The final counts are printed at the end of the entire program

Parameters:

useClassCounter - whether or not to print the class counts. If set to true the class counts are printed, otherwise the final counts are printed.

See Also:

main(String[]), Sweeper.endFRAMES(Node), printTagCount(HashMap, String)

printTagCount

private static void printTagCount(HashMap tagCounter,
                                  String tagName)

Prints a tag name along with the number of times it was encountered. If the count is zero, the line will only be printed if the flZeroCounts flag is set.

Parameters:

tagName - the tag name whose count to print

See Also:

printTagCounts(boolean), getTagCount(HashMap, String)

getTagCount

private static int getTagCount(HashMap tagCounter,
                               String tagName)

Returns the number of times a given tag name was encountered for the given counter.

Parameters:

tagName - the tag name whose count to return

Returns:

the count for the given tag name (the number of times the tag name was encountered)

See Also:

printTagCounts(boolean), printTagCount(HashMap, String)

analyzeArguments

private static void analyzeArguments(String[] args)
                              throws Inspector.InvalidCommandLineArgumentException,
                                     Inspector.InvalidPathException,
                                     Inspector.UserWantsHelpMessage,
                                     Inspector.UserWantsKey

Validates all of the command-line arguments and sets appropriate class-level variables.

Parameters:

args - the command-line arguments from main(String[])

Throws:

Inspector.InvalidCommandLineArgumentException - if the command-line contains invalid flags or does not contain the requisite XML input directory.

Inspector.InvalidPathException - if the XML input directory does not exist or does not have the appropriate permissions.

Inspector.UserWantsHelpMessage - if the user has supplied the help flag.

Inspector.UserWantsKey - if the user has supplied the key flag.

See Also:

main(String[]), Inspector.MyFilter

performInspection

private static void performInspection()

Performs the scanning of the XML files in the XML input directory. It locates the document root element (VNCLASS) in each file and requests that the node be processed. Processing of this node will recursively process all nodes below it (the entire file). If an -O operator was supplied, then only those files which match that operator's argument will be processed. No events will fire for those files not processed.

See Also:

main(String[]), processNode(Node), processNodeByPairs(Node, ArrayList)

processNode

private static void processNode(Node n)

Starts by outputting the simple text you would want to output upon encountering the start of the given node, then recursively prints all the simple text associated with this node's children nodes, and finally outputs the simple text needed for the close of the given node. The process by which this method outputs the 'start' or 'end' simple text for a given node is subtle. Reflection is used. For a node with tag name NODE, methods called 'startNODE' and 'endNODE' are located in the class called 'Sweeper'. If the method is found, it is executed. If it is not found, nothing happens.

Parameters:

n - the XML node for which to generate simple-text representation

See Also:

performInspection(), executeHTMLMethod(String, Node)

processNodeByPairs

static void processNodeByPairs(Node n,
                               ArrayList prevFrames)

Starts by outputting the simple text you would want to output upon encountering the start of the given node, then recursively prints all the simple text associated with this node's children nodes, and finally outputs the simple text needed for the close of the given node. The process by which this method outputs the 'start' or 'end' HTML for a given node is subtle. Reflection is used. For a node with tag name simple text, methods called 'startNODE' and 'endNODE' are located in the class called 'Sweeper'. If the method is found, it is executed. If it is not found, nothing happens.

The only difference between this method and processNode(Node) is that this method accumulates frames as it traverses down the class tree. This ensures that a subclass at depth 2 has all the frames of the main class (depth 0), the subclass at depth 1, and itself, the subclass at depth 2. See more information at Sweeper.curVFFrameList.

Parameters:

n - the XML node for which to generate simple-text representation

prevFrames - all the frames accumulated since the main class of the file

See Also:

performInspection(), executeHTMLMethod(String, Node), Sweeper.curVFFrameList

executeHTMLMethod

private static void executeHTMLMethod(String which,
                                      Node n)

Executes a method in the Sweeper class based on an XML element tag name (i.e. 'VNCLASS') and a 'start' or 'end' flag. Each of the methods in Sweeper, startVNCLASS, endVNCLASS, startMEMBERS, endMEMBERS, etc., produce simple text. This method just calls the right method based on the current node being processed by processNode(Node) or processNodeByPairs(Node, ArrayList).

Parameters:

which - either the value 'start' or 'end', the string to prepend to the tag name when locating the method in Sweeper

n - the node whose tag name should be located in the Sweeper methods

See Also:

processNode(Node), processNodeByPairs(Node, ArrayList)