// This file (Requirement.cs) is a part of the IBBoard.WarFoundry.API project and is copyright 2011 IBBoard
// 
// The file and the library/program it is in are licensed and distributed, without warranty, under the GNU Affero GPL license, either version 3 of the License or (at your option) any later version. Please see COPYING for more information and the full license.
using System;
using IBBoard.WarFoundry.API.Objects.Requirement.Context;

namespace IBBoard.WarFoundry.API.Objects.Requirement
{
	/// <summary>
	/// Base interface for a Requirement that constrains the IWarFoundryObjects that can be taken in an army
	/// </summary>
	public interface IRequirement
	{
		/// <summary>
		/// Gets the ID of the requirement type. This is used by the requirement factories.
		/// It may be, but is not required to be, the name of the class.
		/// </summary>
		/// <value>
		/// The ID of the requirement type.
		/// </value>
		string RequirementID { get; }

		/// <summary>
		/// Checks whether the supplied IWarFoundryObject can be added to the supplied army.
		/// </summary>
		/// <returns>
		/// A <code>Validation</code> enum to show the result of the validation
		/// </returns>
		/// <param name='wfObject'>
		/// The object that we want to add. This may be involved in the check, or it may not affect the evaluation of the requirement
		/// </param>
		/// <param name='toArmy'>
		/// The army to add the object to.
		/// </param>
		Validation AllowsAdding(IWarFoundryObject wfObject, Army toArmy, AddingContext context);

		/// <summary>
		/// Checks whether the supplied army is currently valid according to this requirement.
		/// </summary>
		/// <returns>
		/// A <code>Validation</code> enum to show the result of the validation
		/// </returns>
		/// <param name='toValidate'>
		/// The army to validate
		/// </param>
		Validation ValidatesArmy(Army army);

		/// <summary>
		/// Gets the validation message from validating the army
		/// </summary>
		/// <returns>
		/// A validation message, if the validation fails, else an empty string.
		/// </returns>
		/// <param name='army'>
		/// The army to validate.
		/// </param>
		string GetValidationMessage(Army army);

		/// <summary>
		/// Gets the validation message for adding an IWarFoundryObject to the army
		/// </summary>
		/// <returns>
		/// A validation message, if the object cannot be added, else an empty string.
		/// </returns>
		/// <param name='toAdd'>
		/// The IWarFoundryObject to try to add
		/// </param>
		/// <param name='toArmy'>
		/// The army the object will be added to
		/// </param>
		/// <param name="context">
		/// The context of the addition
		/// </para>			
		string GetAllowsAddingMessage(IWarFoundryObject toAdd, Army toArmy, AddingContext context);
	}
}