001    /**
002     * jline - Java console input library
003     * Copyright (c) 2002,2003 Marc Prud'hommeaux mwp1@cornell.edu
004     *
005     * This library is free software; you can redistribute it and/or
006     * modify it under the terms of the GNU Lesser General Public
007     * License as published by the Free Software Foundation; either
008     * version 2.1 of the License, or (at your option) any later version.
009     *
010     * This library 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 GNU
013     * Lesser General Public License for more details.
014     *
015     * You should have received a copy of the GNU Lesser General Public
016     * License along with this library; if not, write to the Free Software
017     * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
018     */
019    package jline;
020    
021    import java.io.*;
022    import java.util.*;
023    
024    /** 
025     *  A Completor is the mechanism by which tab-completion candidates
026     *  will be resolved.
027     *  <p>
028     *  <strong>TODO:</strong>
029     *  <ul>
030     *      <li>handle quotes and escaped quotes</li>
031     *      <li>enable automatic escaping of whitespace</li>
032     *  </ul>
033     *
034     *  @author  <a href="mailto:mwp1@cornell.edu">Marc Prud'hommeaux</a>
035     */
036    public interface Completor
037    {
038            /** 
039             *  Populates <i>candidates</i> with a list of possible
040             *  completions for the <i>buffer</i>. The <i>candidates</i>
041             *  list will not be sorted before being displayed to the
042             *  user: thus, the complete method should sort the
043             *  {@link List} before returning.
044             *
045             *  
046             *  @param  buffer              the buffer
047             *  @param  candidates  the {@link List} of candidates to populate
048             *  @return                             the index of the <i>buffer</i> for which
049             *                                      the completion will be relative
050             */
051            public int complete (String buffer, int cursor, List candidates);
052    }