/** 
 *  OthelloRules Interface
 *  Interface for the Rules classes for use with Othello,
 *  a project by Sam Rebelsky's CSC 152 class.
 *
 *  The purpose of this interface is to declare the methods used 
 *  by all versions of the rules.  It serves to provide a generic method call
 *  for these common methods as well as to provide other groups with a list of
 *  methods they can expect to use.
 * 
 *
 *  @author Alex Ford, Jonathan Emmons, Rob Park, Arrel Gray
 *  @version 1.2 of March 2000
 *
 */

public interface OthelloRules {
    
    /** 
     *  startingPieces
     *  
     *  This method provides the board class with information on where to 
     *  place the initial pieces before the game starts.  These positions will
     *  be determined by the version of the game selected by the player through
     *  the GUI or TUI. The parameter is a blank GameState, with the rules for
     *  that particular game applied. The method returns the updated board 
     *  with the positions of the initial pieces.
     *
     */

    public GameState startingPieces(GameState g);


    /**
     *  getPlayer
     *
     *  This method is used to extract the field that tells whose turn
     *  it is.  This field will be used to determine the color of the piece to
     *  be played as well as to determine whether a particular move will be
     *  legal.  This field will need to be initialized, and different sets of
     *  rules may state that player one does not always go first.  Also, in the
     *  event of a player being unable to make a legal move or a rule variation
     *  which affects whose turn it is, it will be necessary to set this field.
     *  Within the given rules class. This field will provide more flexibility
     *  than simply initializing it upon declaration of the field.  The method
     *  will not take parameters and will return an integer value representing
     *  the player.
     *
     */

    public int getPlayer();

    
    /**
     *  numberPlayers
     *
     *  At some point in the game it will become necessary for other classes 
     *  to know the number of players playing the game.  This method will 
     *  provide that information by returning an integer corresponding to the
     *  number of players.  It will take a Board as its parameter to determine
     *  the number of players required for that board.
     *
     */

    public int numberPlayers(GameState g);


    /**
     *  legalMove
     *
     *  This method provides a test to see whether or not a move the player
     *  requests is a legal move.  The method will need parameters including 
     *  which player is requesting the move as well as which space he wishes 
     *  to place his piece.  This method is also dependant upon a method in
     *  the board class that will return whether or not a given space on the 
     *  board is occupied and who has that space.  legalMove returns a boolean 
     *  value indicating whether or not a move is legal.  Alternate versions
     *  of the game's rules may include different definitions of a legal move.
     *
     *  Assume the player is represented by an integer and a square on the 
     *  board can be expressed as a column number and row number.
     *
     */

    public boolean legalMove(int player, int row, int column);


    /**
     *  anyMove
     *
     *  This method is designed to determine whether or not a player has 
     *  a legal move available.  There are times in the game in which a player
     *  does not have a space he can move into that will surround one of his 
     *  opponent's pieces, and he will be forced to pass.  The method will need
     *  to know which player is attempting a move.  It will then check all 
     *  empty spaces on the board and test whether or not it is a valid option
     *  using legalMove.  If there is at least one legal move available, the
     *  method will return the boolean value true.  If not, it will return 
     *  false.  
     *
     *  This method can be implemented before every turn or whenever a
     *  player suspects he is "stuck," depending on the preference of the 
     *  designers of the appropriate class.
     *
     */

    public boolean anyMove(int player);


    /**
     *  allMoves
     *  
     *  This method is used by the AI and UI classes to determine the moves 
     *  available. The parameter is the current GameState and the current
     *  player and returns an array of all possible moves for that player.
     *
     */

    public int[] allMoves(GameState g, int player); 

    /**
     *  endOfGame
     *
     *  This method returns a boolean value indicating whether or not the game
     *  is over.  The game should end when 
     *  1) there are no spaces open on the board
     *  2) no player is capable of making a legal move. 
     *  GameState is taken as a parameter and returns -1 if it is not the end 
     *  of the game, otherwise it returns an integer indicating the winner. 
     *
     */

    public int endOfGame(GameState g);

} // interface OthelloRules