--------------------------------------------------------------------------
--                           TRAFFIC JAM
--                     HIGH LEVEL DESIGN DOCUMENT
--------------------------------------------------------------------------
--
--  1. Identifying Information
--     TEAM   : MiracleWare  "If it works, it's a miracle."
--     AUTHOR : John Dalbey
--     VERSION: 2.0 (functional design)
--     DATE   : Feb 15, 1999
--     VERSION HISTORY:
--        2/15/99 first draft

--  2. Software Architecture:       Sequential. 
--     http://www.csc.calpoly.edu/~dstearns/205/Design/softwareArch.html
       
--  3. Design Overview. 
--     This version uses a classic functional decomposition.  
--
--     The main module controls the overall game logic.  It is 
--     essentially a loop which repeats taking turns until the player 
--     wins the game.
--        
--     The major game functions are accomplished in submodules whose
--     names correspond to their purpose:
--     Reset_Board   : Resetting the board
--     Display_Board : Displaying the Board
--     Take_Turn     : Taking a turn
--     Is_Win        : Seeing if the player won
--     Update_Board  : Updating the Board with a player's move.
   
--     The primary data structure is an array which represents the board.

--  4. Design Issues. 
--     The game functionality decomposed nicely into modules, so that 
--     aspect of the design is straightforward.
--     The choice of an array for the data structure was obvious, since we 
--     needed a linear structure which allowed access to any element.
--     The only tradeoff we made was whether or not to keep track of the spot
--     on the board that is empty.  
--     Cons:  Requires a "state" variable to record the empty position.  
--     Pros:  Avoids having to search the array each time to find where
--            the current empty spot is.
--     We decided that keeping an extra "state" variable was worth the 
--     reduction in algorithm complexity we would gain by not having to
--     search the array at each move.

--  5. Tools:  Meridian AdaVantage compiler for PC-DOS

--  6. Libraries: 
--             My_Int_IO:  MiracleWare integer I/O package.

--  7. External References: 
--     Software Specification: 
--     URL: http://www.csc.calpoly.edu/~jdalbey/205/Traffic

--------------------------------------------------------------------------


-----------------------------------------------------------------------------
--                         DATA DESIGN
-----------------------------------------------------------------------------


--  Traffic Puzzle Board

--  Description:
--    A traffic puzzle board is an abstraction of the playing board in the
--    traffic jam game.  It is a linear arrangement of 11 "stones" on which two
--    groups of five people are trying to pass each other.

--  Structure:
--    The board has a linear structure.

--  Elements:
--    There are 11 elements (stones) on the board, numbered 1 - 11, that can be
--    either occupied or empty.  If occupied, the rock contains a person facing
--    either left or right.

Procedure Traffic IS

SUBTYPE Stones IS INTEGER RANGE 1..11;  -- positions on the board

TYPE Marker is (L,R,E);                -- what's occupying a spot on the board

Board: Array (Stones) of Marker;       -- the board itself

Empty_Position: Stones;                -- position of the empty stone


-----------------------------------------------------------------------------
--                         MODULE HEADERS
-----------------------------------------------------------------------------
PROCEDURE Reset_Board;
-- PURPOSE : The board is reset to starting configuration
--     PRE : none
--    POST : The board contains markers in their starting arrangement
--  AUTHOR : JD


PROCEDURE Display;
-- PURPOSE : Show the current board
--     PRE : Board has been reset.
--    POST : current Board has been displayed.
--  AUTHOR : JD


PROCEDURE Update (
             The_Move: IN Stones -- the position of the person to move
             );
-- PURPOSE : Update the board using The_Move
--     PRE : The_Move is a valid move in the game.
--           Board has been reset.
--    POST : Board has been updated with The_Move.
--  AUTHOR : JD

 
FUNCTION Is_Win RETURN BOOLEAN;
-- PURPOSE : See if the board is in winning configuration
--     PRE : Board has been reset.
--    POST : Function value = board in winning configuration 
--  AUTHOR : JD
   

FUNCTION Is_Legal (
             The_Move: IN INTEGER  -- the player's desired move
             ) RETURN BOOLEAN;
-- PURPOSE : See if The_Move is legal
--     PRE : The_Move has a value.
--           Board has been reset.     
--    POST : function value = The_Move is valid
--  AUTHOR : JD

 
PROCEDURE Make_Move;
-- PURPOSE : Allow the player to complete a turn:
--           Prompt the player, obtain a valid move, and make the move.
--     PRE : Board has been reset.
--    POST : A turn in the game has been completed.
--  AUTHOR : JD


BEGIN  -- main
   NULL;
END;