Safe Haskell | None |
---|---|

Language | Haskell2010 |

`AUTHOR`

- Dr. Alistair Ward
`DESCRIPTION`

- Define the data-structure, required to hold a single week's bookings, for any
*observer*-id. - It forms a complete
*timetable*, when combined with similar data-structures, for all observers.

## Synopsis

- type TimetableForWeek timeslotId resourceIds level = Array Day (TimetableForDay timeslotId resourceIds level)
- type Booking timeslotId resourceIds level = (Time timeslotId, Lesson resourceIds level)
- type GenericTimetableToMarkup minimumContrastRatio timetable = TimeAxes Bool -> TimeAxes Bool -> Weekend -> Maybe (GenerateLessonColourFrom, minimumContrastRatio) -> timetable -> Html
- type GenericTimetableToMarkup' locationId minimumContrastRatio teacherId timeslotId timetable = MeetingsByTime timeslotId locationId teacherId -> GenericTimetableToMarkup minimumContrastRatio timetable
- type GeneralisedLessonRunlengthByTimeslotIdByDay timeslotId resourceIds level = Array Day (GeneralisedLessonRunlengthByTimeslotId timeslotId resourceIds level)
- type RunlengthsByTimeslotIdByLessonByDay resourceIds level timeslotId = Array Day (RunlengthsByTimeslotIdByLesson resourceIds level timeslotId)
- observerViewTerminatorCSSIdentifier :: CSSIdentifier
- unavailableCSSIdentifier :: CSSIdentifier
- calculateAverageAbsoluteDeviationOfFreeLessonsPerDay :: (Ix timeslotId, Resource resource, Fractional average) => resource -> TimetableForWeek timeslotId resourceIds level -> average
- calculateUtilisationRatio :: (Ix timeslotId, HumanResource humanResource, Fractional teachingRatio) => NTimeslots -> humanResource -> TimetableForWeek timeslotId resourceIds level -> teachingRatio
- locateUnallocatedAvailableTimes :: (Ix timeslotId, Resource resource) => resource -> TimetableForWeek timeslotId resourceIds level -> [Time timeslotId]
- findGeneralisedLessonRunlengthsByTimeslotIdByDay :: (Ix timeslotId, Enum timeslotId, Eq resourceIds, Eq level) => TimetableForWeek timeslotId resourceIds level -> GeneralisedLessonRunlengthByTimeslotIdByDay timeslotId resourceIds level
- findSeparatedEqualLessonsWithinAnyDay :: (Ix timeslotId, Ord resourceIds, Ord level) => TimetableForWeek timeslotId resourceIds level -> LessonRunlengths resourceIds level
- findSeparatedEqualSubjectLessonsWithinAnyDay :: (Ix timeslotId, Eq resourceIds, Ord level) => TimetableForWeek timeslotId resourceIds level -> LessonRunlengths resourceIds level
- findSeparatedEqualLessonRunlengthsByStartingTimeslotIdByLessonByDay :: (Ix timeslotId, Ord resourceIds, Ord level) => TimetableForWeek timeslotId resourceIds level -> RunlengthsByTimeslotIdByLessonByDay resourceIds level timeslotId
- countSubjectWorkload :: (Ix timeslotId, Ord level) => Subject level -> TimetableForWeek timeslotId resourceIds level -> NTimeslots
- countWorkloadByLesson :: (Ix timeslotId, Ord level, Ord resourceIds) => TimetableForWeek timeslotId resourceIds level -> Map (Lesson resourceIds level) NTimeslots
- countUnallocatedAvailableTimeslots :: (Ix timeslotId, Resource resource) => resource -> TimetableForWeek timeslotId resourceIds level -> NTimeslots
- extractLessons :: Ix timeslotId => TimetableForWeek timeslotId resourceIds level -> [Lesson resourceIds level]
- extractTimes :: Ix timeslotId => TimetableForWeek timeslotId resourceIds level -> [Time timeslotId]
- extractDistinctLessons :: (Ix timeslotId, Ord resourceIds, Ord level) => TimetableForWeek timeslotId resourceIds level -> Set (Lesson resourceIds level)
- extractMaybeLessonsAt :: Ix timeslotId => timeslotId -> TimetableForWeek timeslotId resourceIds level -> Array Day (GeneralisedLesson resourceIds level)
- getFreePeriodCompliance :: (Ix timeslotId, Resource resource, Fractional ratio) => FreePeriodPreference -> TimesByDay timeslotId -> resource -> TimetableForWeek timeslotId resourceIds level -> [ratio]
- mkFreeTimetableForWeek :: (Ix timeslotId, Enum timeslotId) => Interval timeslotId -> TimetableForWeek timeslotId resourceIds level
- getMaybeLesson :: Ix timeslotId => Time timeslotId -> TimetableForWeek timeslotId resourceIds level -> GeneralisedLesson resourceIds level
- getBookedTime :: Booking timeslotId resourceIds level -> Time timeslotId
- getBookedLesson :: Booking timeslotId resourceIds level -> Lesson resourceIds level
- defineTimeslot :: Ix timeslotId => (Time timeslotId, GeneralisedLesson resourceIds level) -> TimetableForWeek timeslotId resourceIds level -> TimetableForWeek timeslotId resourceIds level
- undefineTimeslots :: (Ix timeslotId, Foldable foldable) => TimetableForWeek timeslotId resourceIds level -> foldable (Time timeslotId) -> TimetableForWeek timeslotId resourceIds level
- hasMatchingLessonAt :: Ix timeslotId => (Lesson resourceIds level -> Bool) -> Time timeslotId -> TimetableForWeek timeslotId resourceIds level -> Bool
- isBookedWith :: (Ix timeslotId, Eq level, Eq resourceIds) => Booking timeslotId resourceIds level -> TimetableForWeek timeslotId resourceIds level -> Bool
- areAllSpecifiedTimesBookable :: (Resource resource, Ix timeslotId) => resource -> TimetableForWeek timeslotId resourceIds level -> Course synchronisationId level timeslotId -> Bool
- isBookedOnAdjacentDay :: (Eq level, Eq resourceIds) => TimetableForWeek timeslotId resourceIds level -> Lesson resourceIds level -> Day -> Bool
- isDefinedTimeslot :: Ix timeslotId => Time timeslotId -> TimetableForWeek timeslotId resourceIds level -> Bool
- isRunlengthReducibleAt :: (Ix timeslotId, Enum timeslotId, Eq level, Eq resourceIds) => TimetableForWeek timeslotId resourceIds level -> Time timeslotId -> Course synchronisationId level timeslotId -> Bool
- toXHtml :: forall level locationId minimumContrastRatio resource resourceIds synchronisationId teacherId timeslotId. (Ix timeslotId, Resource resource, Eq level, Eq resourceIds, Fractional minimumContrastRatio, Ord minimumContrastRatio, Show level, Show resourceIds, HTML level, HTML locationId, HTML resourceIds, HTML synchronisationId, HTML teacherId, HTML timeslotId) => (Lesson resourceIds level -> Course synchronisationId level timeslotId) -> resource -> GenericTimetableToMarkup' locationId minimumContrastRatio teacherId timeslotId (TimetableForWeek timeslotId resourceIds level)
- xpickle :: (Ix timeslotId, XmlPickler level, XmlPickler resourceIds, XmlPickler timeslotId, Show level) => PU (TimetableForWeek timeslotId resourceIds level)

# Types

## Type-synonyms

type TimetableForWeek timeslotId resourceIds level = Array Day (TimetableForDay timeslotId resourceIds level) Source #

A timetable for observers with identical scheduling-requirements, for any week.

type Booking timeslotId resourceIds level = (Time timeslotId, Lesson resourceIds level) Source #

A *lesson* qualified by the *time* at which it is booked.

type GenericTimetableToMarkup minimumContrastRatio timetable Source #

= TimeAxes Bool | Whether to merge duplicate |

-> TimeAxes Bool | Whether to depict axis-labels. |

-> Weekend | Define the |

-> Maybe (GenerateLessonColourFrom, minimumContrastRatio) | Whether to generate the colour of a |

-> timetable | The |

-> Html |

- A basic specification required to convert a
*timetable*to XHTML. - The first three parameters supply auxiliary information required for styling.

type GenericTimetableToMarkup' locationId minimumContrastRatio teacherId timeslotId timetable = MeetingsByTime timeslotId locationId teacherId -> GenericTimetableToMarkup minimumContrastRatio timetable Source #

Enhance `GenericTimetableToMarkup`

, with parameters for styling.

type GeneralisedLessonRunlengthByTimeslotIdByDay timeslotId resourceIds level = Array Day (GeneralisedLessonRunlengthByTimeslotId timeslotId resourceIds level) Source #

A runlength-encoded list of generalised (i.e. potentially undefined) *lesson*s, indexed by the *day* & then *timeslotId*, at which each runlength begins.

type RunlengthsByTimeslotIdByLessonByDay resourceIds level timeslotId = Array Day (RunlengthsByTimeslotIdByLesson resourceIds level timeslotId) Source #

A runlength-encoded list of generalised (i.e. potentially undefined) *lesson*s, indexed by the *day* & then *timeslotId*, at which each runlength begins.

# Constants

observerViewTerminatorCSSIdentifier :: CSSIdentifier Source #

Used to qualify output.

unavailableCSSIdentifier :: CSSIdentifier Source #

Used to qualify output.

# Functions

calculateAverageAbsoluteDeviationOfFreeLessonsPerDay :: (Ix timeslotId, Resource resource, Fractional average) => resource -> TimetableForWeek timeslotId resourceIds level -> average Source #

Calculates the *average absolute deviation* (https://en.wikipedia.org/wiki/Absolute_deviation#Average_absolute_deviation) in the number of free-*period*s,
over the *day*s in the week on which the *resource* is actually *available*.

calculateUtilisationRatio :: (Ix timeslotId, HumanResource humanResource, Fractional teachingRatio) => NTimeslots -> humanResource -> TimetableForWeek timeslotId resourceIds level -> teachingRatio Source #

- The number of
*lesson*s booked for the specified*human-resource*, relative to the limit of their teaching-time. - This factors into the denominator, both the
*availability*of the*resource*, & the ratio of that working-time for which they're required to be in teaching rather than some other job-role.

locateUnallocatedAvailableTimes Source #

:: (Ix timeslotId, Resource resource) | |

=> resource | Used to determine |

-> TimetableForWeek timeslotId resourceIds level | |

-> [Time timeslotId] |

- Finds the
*coordinate*s of all unallocated*time*s, when the specified*resource*is*available*. - CAVEAT: doesn't account for
*time*s reserved for*meeting*s.

findGeneralisedLessonRunlengthsByTimeslotIdByDay :: (Ix timeslotId, Enum timeslotId, Eq resourceIds, Eq level) => TimetableForWeek timeslotId resourceIds level -> GeneralisedLessonRunlengthByTimeslotIdByDay timeslotId resourceIds level Source #

Finds consecutive equal generalised (i.e. potentially undefined) *lesson*s, & the run-length of each sequence, indexed by *day* & then *timeslotId*.

findSeparatedEqualLessonsWithinAnyDay :: (Ix timeslotId, Ord resourceIds, Ord level) => TimetableForWeek timeslotId resourceIds level -> LessonRunlengths resourceIds level Source #

Finds separated equal *lesson*s, within the *timetable* for any single *day*.

findSeparatedEqualSubjectLessonsWithinAnyDay :: (Ix timeslotId, Eq resourceIds, Ord level) => TimetableForWeek timeslotId resourceIds level -> LessonRunlengths resourceIds level Source #

Finds separated *lesson*s of equal *subject*, within the *timetable* for any single *day*.

findSeparatedEqualLessonRunlengthsByStartingTimeslotIdByLessonByDay :: (Ix timeslotId, Ord resourceIds, Ord level) => TimetableForWeek timeslotId resourceIds level -> RunlengthsByTimeslotIdByLessonByDay resourceIds level timeslotId Source #

- Finds runlengths of separated equal
*lesson*s, within the*timetable*for any single*day*; separated unallocated*time-slot*s don't qualify. - Returns an array indexed by
*day*, of lists associated by common*lesson*, of lists associated by starting*timeslotId*, of runlengths.

countSubjectWorkload :: (Ix timeslotId, Ord level) => Subject level -> TimetableForWeek timeslotId resourceIds level -> NTimeslots Source #

Returns the total number of *lesson*-definitions currently booked for the specified *subject*.

countWorkloadByLesson :: (Ix timeslotId, Ord level, Ord resourceIds) => TimetableForWeek timeslotId resourceIds level -> Map (Lesson resourceIds level) NTimeslots Source #

- Returns the total number of each type of
*lesson*currently booked. - CAVEAT: if zero of the requested
*lesson*have been booked, then there won't be any matching key in the map. - CAVEAT: be careful with the interpretation of these results,
unless it can be guaranteed that all
*lesson*s for a given*subject*are identical (i.e. they use the same*resourceIds*); otherwise the workload returned for a*subject*could be split amongst different*lesson*s. Whilst this is typically the case for the*student-view*of a*timetableForWeek*, it's may not be the case for other views, since the*student-class*may vary.

countUnallocatedAvailableTimeslots :: (Ix timeslotId, Resource resource) => resource -> TimetableForWeek timeslotId resourceIds level -> NTimeslots Source #

- Counts the total number of unallocated
*time-slot*s, discounting those when the*observer*is unavailable. - CAVEAT: this function takes no account of the possibility that when the
*observer*represents a*student-body*, some*time-slots*may be allocated for unsupervised study, & the remainder must be multiplied by the number of members in the*student-body*.

extractLessons :: Ix timeslotId => TimetableForWeek timeslotId resourceIds level -> [Lesson resourceIds level] Source #

Extracts the *lesson*s from the specified *timetable*, discarding the *booking-time*.

extractTimes :: Ix timeslotId => TimetableForWeek timeslotId resourceIds level -> [Time timeslotId] Source #

Extract the list of all *time*s in the specified *timetable*, regardless of whether a *lesson* has been booked there.

extractDistinctLessons :: (Ix timeslotId, Ord resourceIds, Ord level) => TimetableForWeek timeslotId resourceIds level -> Set (Lesson resourceIds level) Source #

Extracts the set of distinct *lesson*s from the specified *timetable*.

extractMaybeLessonsAt :: Ix timeslotId => timeslotId -> TimetableForWeek timeslotId resourceIds level -> Array Day (GeneralisedLesson resourceIds level) Source #

Extracts any *lesson*-definitions, from the specified *timeslot-Id* on each *day*.

getFreePeriodCompliance Source #

:: (Ix timeslotId, Resource resource, Fractional ratio) | |

=> FreePeriodPreference | This observer's preferred position, within any |

-> TimesByDay timeslotId | The |

-> resource | The observer for whom this weekly |

-> TimetableForWeek timeslotId resourceIds level | |

-> [ratio] | The portion of those free |

Measure the ratio, for each *day* on which the observer, for whom this weekly *timetable* was intended, is *available*,
of those free (neither reserved for a *meeting* nor booked with a *lesson*) *time-slot*s which comply with the specified preference,
to the total number of free *time-slot*s,

## Constructor

mkFreeTimetableForWeek :: (Ix timeslotId, Enum timeslotId) => Interval timeslotId -> TimetableForWeek timeslotId resourceIds level Source #

Constructor. Create an unallocated *timetable*, for a whole week.

## Accessors

getMaybeLesson :: Ix timeslotId => Time timeslotId -> TimetableForWeek timeslotId resourceIds level -> GeneralisedLesson resourceIds level Source #

Get any *lesson* booked at the specified *time*.

getBookedTime :: Booking timeslotId resourceIds level -> Time timeslotId Source #

Accessor.

getBookedLesson :: Booking timeslotId resourceIds level -> Lesson resourceIds level Source #

Accessor.

## Mutators

defineTimeslot :: Ix timeslotId => (Time timeslotId, GeneralisedLesson resourceIds level) -> TimetableForWeek timeslotId resourceIds level -> TimetableForWeek timeslotId resourceIds level Source #

Replace any *lesson*-definition at the specified *time-coordinate*.

undefineTimeslots :: (Ix timeslotId, Foldable foldable) => TimetableForWeek timeslotId resourceIds level -> foldable (Time timeslotId) -> TimetableForWeek timeslotId resourceIds level Source #

Undefines any *lesson* booked at each of the specified *time-coordinate*s.

## Predicates

:: Ix timeslotId | |

=> (Lesson resourceIds level -> Bool) | Determines the suitability of any |

-> Time timeslotId | The |

-> TimetableForWeek timeslotId resourceIds level | |

-> Bool |

True if a *booking* already exists in the *timetable* which matches the specified *predicate*.

:: (Ix timeslotId, Eq level, Eq resourceIds) | |

=> Booking timeslotId resourceIds level | The |

-> TimetableForWeek timeslotId resourceIds level | |

-> Bool |

True if the specified *booking* already exists in the *timetable*.

areAllSpecifiedTimesBookable Source #

:: (Resource resource, Ix timeslotId) | |

=> resource | |

-> TimetableForWeek timeslotId resourceIds level | The |

-> Course synchronisationId level timeslotId | The |

-> Bool |

`True`

if all the *time*s specified by a *course*, are currently unbooked,
& the *resource* is regularly *available* on each requested *day*.

isBookedOnAdjacentDay Source #

:: (Eq level, Eq resourceIds) | |

=> TimetableForWeek timeslotId resourceIds level | The |

-> Lesson resourceIds level | The |

-> Day | Today. |

-> Bool |

True if the specified *lesson* is booked an an adjacent *day*.

isDefinedTimeslot :: Ix timeslotId => Time timeslotId -> TimetableForWeek timeslotId resourceIds level -> Bool Source #

True if a *booking* has been made at the specified *time* in the *timetable*.

isRunlengthReducibleAt Source #

:: (Ix timeslotId, Enum timeslotId, Eq level, Eq resourceIds) | |

=> TimetableForWeek timeslotId resourceIds level | The |

-> Time timeslotId | |

-> Course synchronisationId level timeslotId | |

-> Bool |

- True if the
*course*requires only a trivial*minimumConsecutiveLessons*, or the referenced*lesson*is at either end of a runlength which exceeds*minimumConsecutiveLessons*. - If True, then
*minimumConsecutiveLessons*doesn't preclude the referenced*lesson*from being unbooked; though there may be other reasons why it shouldn't. - CAVEAT: if
`minimumConsecutiveLessons==1`

, but a runlength of three or more have been booked, then unbooking the middle one will result in a split session.

## Translation

:: (Ix timeslotId, Resource resource, Eq level, Eq resourceIds, Fractional minimumContrastRatio, Ord minimumContrastRatio, Show level, Show resourceIds, HTML level, HTML locationId, HTML resourceIds, HTML synchronisationId, HTML teacherId, HTML timeslotId) | |

=> (Lesson resourceIds level -> Course synchronisationId level timeslotId) | Find the |

-> resource | The |

-> GenericTimetableToMarkup' locationId minimumContrastRatio teacherId timeslotId (TimetableForWeek timeslotId resourceIds level) |

Render in *XHTML*, as a *table*, with *day*s varying horizontally & *timeslotId*s varying vertically.

xpickle :: (Ix timeslotId, XmlPickler level, XmlPickler resourceIds, XmlPickler timeslotId, Show level) => PU (TimetableForWeek timeslotId resourceIds level) Source #

Defines a pickler to convert the specified *timetable* to, or from, XML.