001 /* 002 * Copyright (C) 2010 eXo Platform SAS. 003 * 004 * This is free software; you can redistribute it and/or modify it 005 * under the terms of the GNU Lesser General Public License as 006 * published by the Free Software Foundation; either version 2.1 of 007 * the License, or (at your option) any later version. 008 * 009 * This software is distributed in the hope that it will be useful, 010 * but WITHOUT ANY WARRANTY; without even the implied warranty of 011 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 012 * Lesser General Public License for more details. 013 * 014 * You should have received a copy of the GNU Lesser General Public 015 * License along with this software; if not, write to the Free 016 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 017 * 02110-1301 USA, or see the FSF site: http://www.fsf.org. 018 */ 019 020 package org.crsh.cmdline.spi; 021 022 import org.crsh.cmdline.ParameterDescriptor; 023 024 /** 025 * A completer provides completion suffixes for a given prefix. The cmdline framework uses it when 026 * computing a completion. 027 * 028 * @author <a href="mailto:julien.viet@exoplatform.com">Julien Viet</a> 029 * @version $Revision$ 030 */ 031 public interface Completer { 032 033 /** 034 * <p>Query the completer for a set of completion for the given prefix. The returned {@link ValueCompletion} object 035 * provides the possible suffixes matching the prefix argument. Each entry of the result maps to a possible 036 * completion: an entry key is the possible completion, its corresponding boolean value indicates wether the value can 037 * be further more completed or not.<p> 038 * 039 * <p>The prefix value of the completion result is optional and gives a prefix to use more than one result is provided. 040 * The interest of the prefix is to limit the size of the completion to display when they can be long, for instance 041 * a pat completion returning several values could be display in columns, however only the last name of the path would 042 * be displayed and not the entire path.</p> 043 * 044 * <p>The following guidelines should be respected:</p> 045 * <ul> 046 * <li>An empty completion means no completion can be determined, the framework will not do anything.</li> 047 * <li>A singleton map means the match was entire and the framework will complete it with the sole map entry.</li> 048 * <li>A map containing string sharing a common prefix instruct the framework to insert this common prefix.</li> 049 * <li>A list containing strings with no common prefix (other than the empty string) instruct the framework to display 050 * the list of possible completions. In that case the completion result prefix is used to preped the returned suffixes 051 * when displayed in rows.</li> 052 * <li>When a match is considered as full (the entry value is set to true), the completion should contain a trailing 053 * value that is usually a white space (but it could be a quote for quoted values).</li> 054 * </ul> 055 * 056 * <p>Example: a completer that would complete colors could</p> 057 * <ul> 058 * <li>return the result ["lack ":true,"lue ":true] with the prefix "b" for the prefix "b".</li> 059 * <li>return the result ["e ":true] with the prefix "blu" for the prefix "blu".</li> 060 * <li>return the result [] for the prefix "z".</li> 061 * </ul> 062 * 063 * <p>Example: a completer that would complete java packages could</p> 064 * <ul> 065 * <li>return the map ["ext":true,"ext.spi":false] for the prefix "java.t"</li> 066 * </ul> 067 * 068 * @param parameter the completed parameter 069 * @param prefix the prefix to complete 070 * @return the possible suffix map 071 * @throws Exception any exception that would prevent completion to perform correctly 072 */ 073 ValueCompletion complete(ParameterDescriptor<?> parameter, String prefix) throws Exception; 074 075 }