package org.bukkit.conversations;

/**
 * A Prompt is the main constituent of a {@link Conversation}. Each prompt
 * displays text to the user and optionally waits for a user's response.
 * Prompts are chained together into a directed graph that represents the
 * conversation flow. To halt a conversation, END_OF_CONVERSATION is returned
 * in liu of another Prompt object.
 */
public interface Prompt extends Cloneable
{

	/**
	 * A convenience constant for indicating the end of a conversation.
	 */
	static final Prompt END_OF_CONVERSATION = null;

	/**
	 * Gets the text to display to the user when this prompt is first
	 * presented.
	 *
	 * @param context Context information about the conversation.
	 * @return The text to display.
	 */
	String getPromptText(ConversationContext context);

	/**
	 * Checks to see if this prompt implementation should wait for user input
	 * or immediately display the next prompt.
	 *
	 * @param context Context information about the conversation.
	 * @return If true, the {@link Conversation} will wait for input before
	 * continuing.
	 */
	boolean blocksForInput(ConversationContext context);

	/**
	 * Accepts and processes input from the user. Using the input, the next
	 * Prompt in the prompt graph is returned.
	 *
	 * @param context Context information about the conversation.
	 * @param input   The input text from the user.
	 * @return The next Prompt in the prompt graph.
	 */
	Prompt acceptInput(ConversationContext context, String input);
}