Include

It may be that many plans will use the same set of requirements. For example, in Computer Science, the BCS Coop, BCS Regular, and BCS Joint all use the same depth and breadth requirement. Coding that requirement takes 100+ lines! We don’t want to have to type that in multiple times and, worse, keep all three versions up to date.

We’d like to apply the “DRY” principle – Don’t Repeat Yourself. To keep plan specifications DRY, use include. The simplest form is

include(breadthDepth, uw.u.math.bac.cs)

As described in Names & Locations, this will look for a file or database record in /uw/u/math/bac/cs/breadthDepth-TERMID.plan, where TERMID is replaced by the requirement term for this student. If that file does not exist, it will use the file with the most recent requirement term that is before the term given. If no such file exists, it will include a manualCheck.

Using this mechanism, the plan definition for the BCS Coop degree is:

include(mathCourseDefs, uw.u.math)
all of "Bachelor of Computer Science Honours Coop" using all passedCourses {
    minAverage(MAV, CSBHC, 60)
    include(coreCS, uw.u.math.bac.cs) 
    include(coreMath, uw.u.math.bac.cs)
    include(additionalCS, uw.u.math.bac.cs)
    include(breadthDepth, uw.u.math.bac.cs)

coreCS, coreMath represent requirements that are common to both BCS Coop and BCS Regular, so splitting them out avoids duplicating requirements in plan files.

Similarly, breadth and depth requirements change reasonably frequently but the first three have been stable across many years. Splitting them up like this means that the first three do NOT need to change just because the breadth and depth has changed.

Include search path

The description above is by far the most common use of include. However, there is also a further “search” mechanism that can be useful. This use of include is inspired (required) by a rule at the Math Faculty level that depends on the specific plan the student is enrolled in. Every Math student has a communications requirement but students in the CFM program, STATS/ACTSC, and the double degree Business Administration programs have versions that differ from the default.

This is handled by giving include a “search path”:

include(commReq,
            uw.u.id.bac.cfm,
            uw.u.math.bac.statactsc,
            uw.u.math.bac.cs.dd,
            uw.u.math.bac.mathbus.mathdd,
            uw.u.math.bac
)

The degree audit program will make a list of candidate files and then include the first one from the list that actually exists. If none of them exists, specify that a manual check must be done.

How does the degree audit know which of those locations it should look in for a specific plan? It looks in the same directory that the main plan file is in, and then in all the directories it traversed through to get to that main path.

For example, suppose we’re doing an audit of a student with plan code MATHFINHC (Mathematical Finance) with a requirement term of 1209. The plan group for this plan code is uw.u.math.bac.statactsc.mathfin. The program:

Filters the search path to include only those items that are a prefix of the plan group. Add the last item on the search path even if it isn’t a prefix. This results in
```
uw.u.math.bac.statactsc
uw.u.math.bac
```

Adds the file name plus requirement terms going back in time, starting with the student’s requirement term:

uw.u.math.bac.statactsc.commReq-1209.plan
uw.u.math.bac.statactsc.commReq-1205.plan
uw.u.math.bac.statactsc.commReq-1201.plan
uw.u.math.bac.statactsc.commReq-1199.plan
...
uw.u.math.bac.commReq-1209.plan
uw.u.math.bac.commReq-1205.plan
uw.u.math.bac.commReq-1201.plan
uw.u.math.bac.commReq-1199.plan
...

Goes through this list and selects the first file that exists.

Explicit requirement term and plan group

It is possible to explicitly override the requirement term and plan group:

include(CSBHC, 1239, uw.u.math.bac.cs.cs, uw.u.math.bac)

This is used internally, but at the present time there are no known uses in user-written plan specifications.

Sub-includes

It is also possible to specify an include that should be included within an include. Again, this is used internally but there are no known applications in user-written plan specifications. See Top Level for more information.

Best Practices

You are able to define course sets within one includes and then referance them in another includes as long as the second includes appears after the first one and the course sets within the first includes are not enclosed with any brackets. This is useful when multiple plans use the same sets of courses but require a different amount from each.
If a student has a main plan that has a requirement term defined as one that is earlier than the students actual requirement term, perhaps 1209 is the requirement term but the file starts with plan CSBH 1179 using all passedCourses { include(csCore, uw.u.math.bac.cs) }, includes files will be searched for using the ACTUAL REQUIREMENT TERM. This allows us to have one or two main plan files and then many includes files that are updated each time that part of the calendar is updated.