(****
 *
 * Module CalendarDB defines the major database objects of the calendar system
 * as well as the objects that define the underlying calendar structure.  The
 * core object of the calendar system is the UserCalendar, which is modeled as
 * a collection of scheduled items.  The calendar structure of years, months,
 * weeks, and days is not directly modeled in the UserCalendar.  These
 * structures are computed views that are derived from the underlying scheduled
 * item collection.
 *
 *)

module CalendarDB;

  from Schedule import ScheduledItem, Date;
  from Admin import UserDB, GroupDB, LocationDB, UserId;
  from File import FileSpace, File;
  from Edit import Clipboard, Selection, SelectionContext;
  export CalendarDB, UserWorkSpace, UserCalendar, RequiresSaving, UserOptions,
    GlobalOptions, PreviousState;

  object CalendarDB is
    components: user_calendars:UserCalendars and user_db:UserDB and
        group_db:GroupDB and loc_db:LocationDB and
        global_options:GlobalOptions and workspace:UserWorkSpace;
    description: (*
        The CalendarDB is the top-level object for the Calendar Tool.  The
        first component is the list of UserCalendars for all registered users.
        The next three components are the registered UserDB, the user GroupDB,
        and the LocationDB.  The GlobalOptions component is the set of calendar
        options common by default for all users, both registered and
        non-registered.  The UserWorkSpace component is active calendars upon
        which the current user is working.
    *);
  end;

  object UserWorkSpace is
    components: uid:UserId and calendars:UserCalendar* and
        options:UserOptions and previous_state:PreviousState and
        clipboard:Clipboard and selection:Selection and
        context:SelectionContext;
    description: (*
        The UserWorkSpace contains the active calendars upon which the user is
        working.  The first component is the UserId of the current user, which
        is used as necessary by operations that input the workspace to
        determine who the user is.  The UserCalendar* component is the list of
        active calendars; the list is maintained in the order visited by the
        user, with the first element being the most recently visited, and hence
        current, and the last element being the earliest visited.  The
        UserOptions component is the list of individualized user options, some
        of which may be different than the global calendar options.  The
        previous_state component is used to support one level of command undo.
        The Clipboard is used with the Edit cut, copy, and paste operations.
    *);
  end;

  object PreviousState is
    components: ScheduledItem*;
    description: (*
        PreviousState is the snapshot of scheduled items before the most
        recently performed scheduling operation used by EditUndo.  The
        Schedule, Change, and Delete operations save the previous state to
        support Undo.
    *);
  end PreviousState;

  object UserCalendars is
    components: UserCalendarFileName*;
    description: (*
        UserCalendars is the list of public calendars for all registered users.
        The list consists of calendar file names, not calendars themselves.  In
        this way, the list of user calendars is modeled as a distributed
        collection of user calendar files, not as a centralized database of
        calendars.  This allows users to retain autonomous control of their own
        individual calendars.
    *);
  end UserCalendars;

  object UserCalendarFileName is string
    description: (*
        A UserCalendarFileName is the unique path to a user calendar file.  The
        specific syntax of such a path is implementation-platform-specific.  In
        general, a file path is a sequence of file directory names, ending in a
        file name.
    *);
  end UserCalendarFileName;

  object UserCalendar
    components: uid:UserId and file:File and options:UserOptions and
        selected_date:Date and requires_saving:RequiresSaving and
        items:ScheduledItem*;
    description: (*
        A UserCalendar has the id of the user who owns it, the file it's stored
        on, the specialized user options for the calendar, the currently
        selected date, a flag indicating if the calendar requires saving, and
        the list of scheduled items.
    *);
  end UserCalendar;

  object UserName is string
    description: (* The name of a registered user. *);
  end Username;

  object UserOptions is Option*
    description: (*
        The personal options of a user, initially a copy of the default global
        options, and subsequently changed if the user chooses to do so using
        the Options commands.
    *);
  end UserOptions;

  object Option is ...;

  object RequiresSaving is boolean
    description: (*
        True if a calendar requires saving, which is the case if one or more
        successful edit operations has been performed on the calendar since the
        most recent save.  The calendar edit operations are Schedule, Change,
        and Delete.
    *);
  end RequiresSaving;

  object GlobalOptions is Option*
    description: (*
        The global default options for all users.  The local options for each
        user calendar are initially a copy of the global options.  The local
        options can be changed if the user chooses to do so using the
        EditPreferences dialog.
    *);
  end GlobalOptions;

end CalendarDB;