design-notes.txt

Refactoring ideas.

The overall intended functions are:

  mirror   -- make a local mirror of the HTML we'll be parsing
  update   -- parse the local mirror and produce our local database
  
Then once you have a database you can use:

  schedql  -- a query language that generates valid schedules
  whatnow  -- suggests what courses to take based on what your
              major is and what you've already taken
  webschd  -- a web-based schedule editor


Module structure

  The current Fetch and Parse modules are not a bad first try but they won't
  do on their own. They need to be broken down into more modules.

  Schedool.Mirror - 
           This is the download part of the current Fetch module. The
           functions in here should attempt to read out of a local cache and
           download only when the cache is empty.

	   Exports:
	     openDepartmentData :: IO String
	     openSections       :: Department -> IO String
             recreate           :: IO Bool

           We can leave the part that actually hits the website
           internal, or we can expose the recreate method which will
           recreate the mirror by downloading the files.

  Schedool.Data -
           This is the load part of the Fetch module. The functions in here
           should do nothing more than find the data using Mirror and parse it
           using Parse. This will be the rest of the application's main entry
           point.

	   Exports:
	     getDepartments :: IO [Department]
	     getSections    :: IO [Section]

	   This module may have other exports for utilities such as
	   SectionMap, or these may appear somewhere else.

  Schedool.Parse -  
           This module simply parses the HTML and produces lists of sections
           or departments. The internals of this module are likely to be nasty
           and to change radically whenever the school changes the output of
           their Banweb server, so this part may not be verified completely.

	   Exports:
	     parseDepartments :: String -> [Department]
	     parseSections    :: String -> [Section]

  Schedool.Cache - 
           This module implements a simple cache of sections and
           departments. It's intended to be used by the Data module
           and hidden from the end user.

           Exports:
             cacheDepartments      :: [Department] -> IO ()
             cacheSections         :: [Section]    -> IO ()

             hasCache              :: IO Bool
             readCachedDepartments :: IO [Department]
             readCachedSections    :: IO [Section]

  Schedool.Query -
           This module implements the scheduling query language. It
           may need to be broken down internally into submodules for
           parsing and generating schedules, but its public interface
           will be very simple.

	   Exports:
	     runQuery  :: [Section] -> String -> [[Section]]


Query language

The most basic schedule is simply a single class entity:

  CSE 113

This query produces all schedules with this single necessary class,
CSE 113. SchedQL supports extending schedules with Boolean algebra,
hence the following identical formulations of a schedule with two
classes:

  CSE 113 and MATH 112
  CSE 113, MATH 112

And also the following formulations of a schedule with one of the two
classes:

  CSE 113 or MATH 112

Note that this is functionally an exclusive or, because
English-speakers expect that behavior from or. To effect inclusive or,
use the following operator:

  CSE 113 and/or MATH 112

The only remaining operator is parentheses, which can be used to group
together expressions into subexpressions:

  CSE 113, MATH 112 and (ENGL 113 or PHIL 101)

The "and" operation is implemented as combinations, the "or" operation
is implemented as union, "and/or" is implemented by both.