001    /**
002     * LTAG-spinal API, an interface to the treebank format introduced by Libin Shen.
003     * Copyright (C) 2007  Lucas Champollion
004     *
005     * This program is free software: you can redistribute it and/or modify
006     * it under the terms of the GNU General Public License as published by
007     * the Free Software Foundation, either version 3 of the License, or
008     * (at your option) any later version.
009     * 
010     * This program is distributed in the hope that it will be useful,
011     * but WITHOUT ANY WARRANTY; without even the implied warranty of
012     * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
013     * GNU General Public License for more details.
014     *
015     * You should have received a copy of the GNU General Public License
016     * along with this program.  If not, see <http://www.gnu.org/licenses/>.
017     *
018     */
019    package edu.upenn.cis.spinal;
020    
021    import java.io.*;
022    import java.util.*;
023    
024    /**
025     * Inherit from this abstract class to create standalone command-line applications 
026     * that operate on a file containing an LTAG-spinal annotated sentence or sentences.
027     * See the other <code>XYZWalker</code> classes in this packages for examples.
028     * All inherited classes should include the following method:
029     * <pre> 
030     * public static void main(String argv[]) {
031     *      new XYZWalker().process(argv);
032     * }
033     * </pre>
034     * 
035     * @author Lucas Champollion
036     *
037     */
038    public abstract class AbstractWalker {
039        
040            /**
041             * Contains the arguments that have been passed to {@link #process(String[])}.
042             */
043            protected String[] args;
044            
045            /**
046             * Indicates whether {@link #terminate()} has been called.
047             */
048            protected boolean terminate=false;
049                    
050            /**
051             * Returns the string array of arguments that has been passed to 
052             * {@link #process(String[])}.
053             * 
054             * @return the arguments
055             */
056            protected String[] getArgs() {
057                return this.args;
058            }
059            
060    
061            /**
062             * Call this method from within {@link #forEachSentence(Sentence)} to 
063             * instruct {@link #process(String[])} to skip any remaining sentences. 
064             * {@link #process(String[])} will 
065             * still call {@link #wrapUp()} even after
066             * this method is invoked.
067             *
068             * 
069             */
070            protected void terminate() {
071                this.terminate=true;
072            }
073           
074            /**
075             * This method calls {@link #init()}, then opens a file in LTAG-spinal format
076             * using the first element
077             * of the <code>args</code> array as the filename, and reads in elementary trees from that file.
078             * On each of these trees, it calls {@link #forEachSentence(Sentence)}.
079             * When {@link #terminate()} is called or the end of the file is reached, 
080             * the method calls {@link #wrapUp()}. 
081             *
082             * @param args an array of arguments. The first of them is used as a filename
083             * to indicate the location of the file containing LTAG-spinal annotation.
084             *
085             */
086            protected void process(String[] args) {
087                
088                    this.args = args;
089                    
090                    if (args.length == 0) {
091                        printUsage();
092                        return;
093                    }
094                    
095                    init();
096                    
097                    
098                    String filename=args[0];
099                    BufferedReader input=null;
100                    
101                    try {
102                            input=new BufferedReader(new FileReader(filename));
103                    } catch (IOException e) {
104                            System.err.println(e);
105                            e.printStackTrace();
106                            System.exit(1);
107                    }
108                    
109                    
110                    Sentence t=null;
111                    
112                    
113                    try {
114                            while ((t=Sentence.readTree(input))!=null) {
115                                
116                                forEachSentence(t);
117                                if (terminate) return;
118                            }
119                    } catch (Exception e) {
120                            System.err.println(e);
121                            e.printStackTrace();
122                            System.exit(1);
123                    }
124                    
125                    wrapUp();
126            }
127            
128            
129            /**
130             * Implementations of this method should specify what (if anything)
131             * the class should do before attempting to read in a file.
132             *
133             */
134            protected abstract void init();
135            
136            /**
137             * Implementations of this method should specify what the class
138             * should do on reading in a sentence (a derivation tree) from the file.
139             *
140             * @param t the current <code>Sentence</code> object
141             */
142            public abstract void forEachSentence(Sentence t);
143            
144            /**
145             * Implementations of this method should specify what (if anything)
146             * the class should do upon reading all sentences from the file. The
147             * {@link #process(String[])} method also calls this if {@link #terminate()}
148             * has been invoked.
149             *
150             */
151            protected abstract void wrapUp();
152    
153            /**
154             * Implementations of this method should print out a short string 
155             * to <code>stdout</code>
156             * describing the function of the class. This method is automatically
157             * called by {@link #process(String[])} when no command-line
158             * argument is passed.
159             *
160             */
161            protected abstract void printUsage();
162            
163            
164    }