/*******************************************************************************
* Copyright (c)                                                                *
*           2005   Tristan Allwood,                                            *
*           2005   Daniel Burke,                                               *
*           2005   Marc Hull,                                                  *
*           2005   Ekaterina Itskova,                                          *
*           2005   Steve Zymler                                                *
*                                                                              *
* Permission is hereby granted, free of charge, to any person obtaining a      *
* copy of this software and associated documentation files (the                *
* "Software"), to deal in the Software without restriction, including          *
* without limitation the rights to use, copy, modify, merge, publish,          *
* distribute, sublicense, and/or sell copies of the Software, and to           *
* permit persons to whom the Software is furnished to do so, subject to        *
* the following conditions:                                                    *
*                                                                              *
* The above copyright notice and this permission notice shall be included      *
* in all copies or substantial portions of the Software.                       *
*                                                                              *
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS      *
* OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF                   *
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.       *
* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY         *
* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,         *
* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE            *
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.                       *
*******************************************************************************/
/*
 * Created on 19-Oct-2004
 *
 */
package uk.ac.ic.doc.kevlar.api.programs.arguments;

import java.util.Set;

import uk.ac.ic.doc.kevlar.core.framework.typecheck.IInterfaceClass;
import uk.ac.ic.doc.kevlar.publicUtil.collections.IImmutableMap;
import uk.ac.ic.doc.kevlar.publicUtil.collections.IImmutableSet;

/**
 * 
 * Each program has an associated IArgumentModel
 * This model can be got from IProgram.
 * 
 * This class lists all the arguments, and all the mappings between
 * argument states and IO nodes.
 * 
 * Details provided for each argument includes
 * - Name
 * - The type (Found using instanceof/visitor)
 * - The values it can take (For set (aka dropdown menu) arguments)
 * - Which arguments are its children
 *   (So setting it can cause these children to potentially appear
 * - Which values lead to which of its children appearing
 * - The initial value
 * - What values are valid for this argument (Expressed using a regex)
 * 
 * @author Daniel Burke
 *
 */

public interface IArgumentModel {
	
    /**
     * IBasicArgumentInfo is guranteed to be one the subtypes in IArgumentVisitor
     * @return a map of argument names to information on that argument
     */
	public IImmutableMap<String, IBasicArgumentInfo> getArgumentNameMap();

	/**
	 * @return the set of arguments that are always visible
	 */
	public IImmutableSet<String> getRootArguments();
	
	/**
	 * @param assignments the current argument assignments
	 * @return the set of arguments that are visible for the given assignments
	 */
	public Set<String> getAvailableArguments(IArgumentInstance assignments);
	
	/**
	 * 
	 * @param instance the current argument assignments
	 * @return A tuple containing the list of input nodes and list of outputs nodes
	 */
	public IInputOutputNodeTuple getIOFunction(IArgumentInstance instance);
	
	/**
	 *
	 * @return the list of all types that might be part of the IO function
	 */
	public IImmutableSet<IInterfaceClass> getTypeDependancies();
	
	/**
	 * Prints arg model as XML
	 * @param depth indentation level (in terms of tabs)
	 * @return XML string
	 */
	public String toString(int depth);
}