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            int complete (String buffer, int cursor, List candidates);
052    }