PEEP Copyright © 2004 Stoney Jackson, Distributed under the GPL See: http://peephole.cs.ucdavis.edu/ SYNOPSIS This is a program for comparing the layout times of global vs peephole pretty-printing strategy, and for investigating the affects of width, height, and fisheye degree on the layout time of each strategy. Its primary function is to report the time it takes for each strategy to pretty-print a window of text around a given focal point. It can also be used to visually confirm the stability of the peephole layout strategy. TIMES REPORTED DO NOT INCLUDE THE TIME FOR LOT AND AST GENERATION. In practice, the AST and LOT would be generated when a file is first loaded, or if when the original source code has been modified. The AST and LOT can then be reused to produce different formats. NOR DO THE TIMES INCLUDE THE TIME SWING TAKES TO RENDER ITS INTERFACE. This time is dependent on the windowing environment and toolkit being used. This program is designed to measure the time it takes JUST to format code from a LOT. This program pretty-prints JavaML files (http://www.cs.washington.edu/homes/gjb/JavaML/) using the global and peephole pretty-print strategies and reports the time each takes in milliseconds for a sample of foci. JavaML parses Java files into an abstract syntax tree (AST) in an XML format. This program pretty-prints JavaML files conforming to java-ml-0.97.dtd. REQUIRES Java 1.4.1 or greater (I use the assert keyword and the Swing library). INSTALL $ tar zxvf peep.tgz # Extracts into a directory peep. (Optional) Modify PEEP_HOME in peep.sh to hole the path to peep.jar. For instance, if /home/jacksoni/peep contains peep.jar, then set PEEP_HOME=/home/jacksoni/peep in peep.sh. Alternatively, you can set PEEP_HOME in your environment $ export PEEP_HOME=/home/jacksoni/peep You may also want to put peep.sh in your path. $ export PATH=$PATH:/home/jacksoni/peep peep.jar also contains the source code for the global and peephole algorithms as well as the command line program used to time them. To look at the source, extract the peep.jar. $ jar -xvf peep.jar # If you want to look at the source. USAGE $ peep.sh [OPTIONS] javaml-file+ Note, a copy of java-ml-0.97.dtd must reside in the xml-unparse directory created by JavaML (see JavaML documentation for details). You can also run the program like this: $ java [JVM_OPTIONS] -jar $PEEP_HOME/peep.jar [OPTIONS] javaml-file+ Use this second method if you need to specify other options to the Java virtual machine. For instance, you may want to force the virtual machine to start with a larger initial heap size (via -Xms) and/or a larger maximum heap size (via -Xmx). OPTIONS -e ARG Turn on elision with a degree of ARG. Larger values display more. Default is no elision. -w ARG Sets the width to ARG pixels. -h ARG Sets the height to ARG pixels. -c ARG Run a batch of ARG number of foci (xor with -f). Defaults to 1, posting results. Use -s to control sampling. -p ARG Post results every ARG seconds. Use with -c to periodically post results during a batch run. -f ARG Specifies a single focus. Results are posted. (xor with -c) -s ARG Sets the focal selection strategy. Valid values for ARG: random (default), inorder, reverse. Use -S with random to seed the randomizer. -S ARG Seeds randomizer with ARG. -d ARG Dump list of foci and LOT to file ARG. -x Displays extra data. SAMPLES I've included several sample JavaML files in $PEEP_HOME/samples/xml-unparsed. They were generated from the Java source files located in samples. To run these examples, first change directories into $PEEP_HOME/samples/xml-unparsed. (These examples assume that peep.sh is in your path.) Simple run that formats and displays a global layout and a peephole layout for one randomly selected foci, and displays. Timing results are reported to the console. $ peep.sh BestEval2.java.xml The program can be run in batch to time a sample of runs with different foci. This is done by specifying the number of foci to sample with the -c option. If the number specified is greater than 1, then no windows will be displayed. For instance, to measure the layout times for 285 different foci... $ peep.sh -c 285 BestEval2.java.xml While running a batch of foci, you may want to see some of the resulting layouts in a window as you did before. You can do this by specifying how often results should be posted to a window using the -p option. For instance, to post results every 30 seconds... $ peep.sh -c 285 -p 30 BestEval2.java.xml Maybe during a batch run with periodic postings, a posting for a particular focus caught your eye. You can reproduce the layout using the -f option to specify a particular focus. The focus that was used to create a layout is named in the title of the window (e.g., '}':2439). The following displays the results for that one focus, and does nothing else. $ peep.sh -f "'}':2439" BestEval2.java.xml All of the examples so far have not used fisheye. Use the -e option to enable fisheye and specify the fisheye degree desired. The fisheye degree controls how much code is show. Larger values show more. The following enables fisheye with a degree of 5. $ peep.sh -e 5 -f "'}':2439" BestEval2.java.xml Finally, you can control the window dimensions with -w and -h. This next run formats for a 1600 x 1200 (pixel) window. $ peep.sh -w 1600 -h 1200 BestEval2.java.xml NOTES JavaML files must follow the 0.97 version of java-ml.dtd. Check the first few lines of the DTD for the version number. The version shipeeped in this distribution is version 0.97. I do not distribute JavaML (yet). Compiling a version that produces XML conforming to java-ml.dtd version 0.97 was a bit tricky. I plan to clean the process up, and eventually distribute it with my pretty-printer. For now, please enjoy the samples I've included. ACKNOWLEDGMENTS Thanks to Premkumar Devanbu and Brian Toone for testing this tool on various platforms.