Source code: org/gnu/readline/ReadlineCompleter.java
1 // File: ReadlineCompleter.java
2 // Created: 2001-02-22 15:50:22, erik
3 // By: <erik@skiinfo.fr>
4 // Time-stamp: <2001-02-23 11:19:11, erik>
5 //
6 // $Id: ReadlineCompleter.java,v 1.1 2001/12/27 11:08:05 Bablokb Exp $
7 //
8 // Description:
9
10
11 package org.gnu.readline;
12
13 /**
14 * Callback interface that implements completion. You've to implement this
15 * interface in order to provide completion in your application. The default
16 * completion mode of the Readline library would otherwise be simple
17 * filename completion.
18 */
19 public interface ReadlineCompleter {
20
21 /**
22 * A generator function for filename completion in the general case.
23 * Note that completion in Bash is a little different because of all
24 * the pathnames that must be followed when looking up completions
25 * for a command. The Bash source is a useful reference for writing
26 * custom completion functions.
27 *
28 * <p>The completer method is called with the current text to be
29 * expanded (that is: the string of characters after the last
30 * {@link Readline#getWordBreakCharacters() word break character}) and
31 * an integer. The integer is zero to indicate, that the user just requested
32 * completion (usually by pressing the TAB-key). The completeter method now
33 * can return one possible choice or null to indicate that there is no
34 * choice. If the completer returned a non-null value it is called back by
35 * the readline library with increasing <code>state</code> variable until
36 * it returns null.
37 *
38 * <p>Depending on the state and the return value, the readline library
39 * reacts differently.
40 * <ul>
41 * <li>if the completer returns <code>null</code> for state=0, then
42 * the readline library will beep to indicate that there is no
43 * known completion.</li>
44 * <li>if the completer returns a value for state=0 and
45 * <code>null</code> for state=1, then there was exactly <em>one</em>
46 * possible completion, that is immediately expanded on the command line.</li>
47 * <li>if the completer returns choices for states >= 1, then these
48 * choices are displayed to the user to choose from.</li>
49 * </ul>
50 *
51 * <p><b>Example</b><br>
52 * Consider you have a sorted set (like a TreeSet) of commands:
53 * <hr><pre>
54 * SortedSet commandSet; // SortedSet<String>
55 * ...
56 * commandSet = new TreeSet();
57 * commandSet.add("copy");
58 * commandSet.add("copyme");
59 * commandSet.add("load");
60 * commandSet.add("list");
61 * ...
62 * </pre><hr>
63 * now, you could write a completion method that provides completion for these
64 * commands:
65 * <hr><pre>
66 * private Iterator possibleValues; // iterator for subsequent calls.
67 *
68 * public String completer(String text, int state) {
69 * if (state == 0) {
70 * // first call to completer(): initialize our choices-iterator
71 * possibleValues = commandSet.tailSet(text).iterator();
72 * }
73 * if (possibleValues.hasNext()) {
74 * String nextKey = (String) possibleValues.next();
75 * if (nextKey.startsWith(text))
76 * return nextKey;
77 * }
78 * return null; // we reached the last choice.
79 * }
80 * </pre><hr>
81 *
82 * @param text start of completion text. This is the text since the last
83 * word break character.
84 * @param state 0 or positive int. This state is zero on the first call
85 * for a completion request and increments for each subsequent
86 * call until the end of choices is reached.
87 *
88 * @return String with a completion choice or <code>null</code>, if there
89 * are no more choices.
90 *
91 * @see Readline#getWordBreakCharacters()
92 * @see test.TestCompleter
93 */
94 public String completer(String text, int state);
95 }
96
97 /*
98 * Local variables:
99 * c-basic-offset: 2
100 * End:
101 */