(****
 *
 * 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, Categories;
  from View import CustomLists, Filtering, WindowingMode;
  from Admin import UserDB, GroupDB, LocationDB, UserId;
  from File import FileSpace, File;
  from Edit import Clipboard, Selection, SelectionContext;
  from Options import Options;
  export CalendarDB, UserWorkSpace, UserCalendar, RequiresSaving,
        PreviousState;

  object CalendarDB is
    components: user_calendars:UserCalendars and user_db:UserDB and
        group_db:GroupDB and loc_db:LocationDB and options:Options 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 Options 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
        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
        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;

  (* NOTE: We may need to separate a UserCalendar into a local and remote
  versions, with only the latter having ther UID, the reason being that
  locally, a calendar shouldn't have an ID, in case the user hooks it up to
  more than one host. *)
  object UserCalendar
    components: items:ScheduledItem* and categories:Categories and
        lists:CustomLists and filtering:Filtering and options:Options and
        windowing_mode:WindowingMode and uid:UserId and file:File and
        selected_date:Date and requires_saving:RequiresSaving;
    description: (*
        A UserCalendar has a list of scheduled items and the calendar-specific
        information for categories, custom lists, filters, options, and
        windowing mode.  Calendar bookkeepting components are the ID of the
        user who owns the calendar, the file it's stored on, the currently
        selected date, and a flag indicating if the calendar requires saving.
    *);
  end UserCalendar;

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

  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;

end CalendarDB;