-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Simple deterministic game engine
--   
@package deterministic-game-engine
@version 0.4.0


-- | Library for creating simple deterministic games, such as tic-tac-toe.
--   The engine requires a minimal set of actions related to the game, and
--   then will run the game until a terminal state is reached.
--   
--   Simple generic example below. See the specs for a more detailed
--   example.
--   
--   <pre>
--   import Game.Deterministic.GameEngine
--   
--   game :: Monad m =&gt; GameEngine m [Char] [(Int, Char)]
--   game = GameEngine gameActions initialState
--   
--   gameActions :: Monad m =&gt; GameActions m [Char] [(Int, Char)]
--   gameActions = GameActions {
--      getPlayer  = -- find the next player from a game state,
--      getMove    = -- find a move from the game state,
--      getResult  = -- transitions from a state to another state,
--      isTerminal = -- determines if the game is terminal,
--      getScore   = -- get score from a terminal state
--    }
--   
--   initialState :: GameState [Char]
--   initialState = GameState ['x', 'x', 'x']
--   
--   -- run the game engine until a terminal state is reached
--   playSimple game
--   </pre>
module Game.Deterministic.GameEngine

-- | Set of actions that defines how the game will be played
data GameActions m a b
GameActions :: (GameState a -> m Player) -> (GameState a -> m (Move b)) -> (GameState a -> Move b -> m (GameState a)) -> (GameState a -> m Bool) -> (GameState a -> Player -> m Int) -> GameActions m a b

-- | Specifies which player has the move in the state
getPlayer :: GameActions m a b -> GameState a -> m Player

-- | Returns a legal move in the state
getMove :: GameActions m a b -> GameState a -> m (Move b)

-- | The transition model, which determines the result of a move
getResult :: GameActions m a b -> GameState a -> Move b -> m (GameState a)

-- | True if game is over, False otherwise
isTerminal :: GameActions m a b -> GameState a -> m Bool

-- | A utility function to determine the numeric value for a game that ends
--   in a terminal state
getScore :: GameActions m a b -> GameState a -> Player -> m Int
data GameState a
GameState :: a -> GameState a
data Move a
Move :: a -> Move a
data Player
Player :: String -> Player

-- | Holds information about how the game is played, and the current state
--   of the game.
data GameEngine m a b
GameEngine :: GameActions m a b -> GameState a -> GameEngine m a b

-- | Defines how the game will be played
gameEngineActions :: GameEngine m a b -> GameActions m a b

-- | The current state of the game
gameEngineState :: GameEngine m a b -> GameState a

-- | Run the provided game engine under a monadic context until a terminal
--   state is reached.
play :: Monad m => GameEngine m a b -> m Int

-- | Run the provided game engine without a context until a terminal state
--   is reached.
playSimple :: GameEngine Identity a b -> Int

-- | Run the provided game engine within an IO context until a terminal
--   state is reached.
playIO :: GameEngine IO a b -> IO Int