A requirement is a way to specify some subset of works: for example, those with a given title, and/or version number.

• §1. Creation
• §6. Writing
• §7. Meeting requirements

§1. Creation. A requirement is, in effect, the criteria for performing a search. We can specify the title, and/or the author name, and/or the genre — all given in the work field below, with those unspecified left blank — and/or we can give a semantic version number range:

typedef struct inbuild_requirement {
    struct inbuild_work *work;
    struct semver_range *version_range;
    CLASS_DEFINITION
} inbuild_requirement;

• The structure inbuild_requirement is accessed in 2/edt, 2/cps, 2/ce, 2/jm, 3/bg, 3/is, 3/is2, 4/em, 4/ebm, 4/km, 4/lm, 4/pm, 4/pbm, 4/pfm, 4/tm, 5/es, 5/ks, 5/ls, 5/ps2, 6/st, 6/hdn, 6/inc, 7/tm, 7/eip, 7/ti, 7/tc, 7/dc, 7/dr and here.

§2. Here are some creators:

inbuild_requirement *Requirements::new?Usage of Requirements::new:
Extension Services - §2.4.3.1.1, §2.4.3.2.1
Kit Services - §5.3.1.1
Project Services - §23.1
Inclusions - §5.1(inbuild_work *work, semver_range *R) {
    inbuild_requirement *req = CREATE(inbuild_requirement);
    req->work = work;
    req->version_range = R;
    return req;
}

inbuild_requirement *Requirements::any_version_of?Usage of Requirements::any_version_of:
Inter Skill - §3, §4
Extension Services - §2.4.3.1.2, §2.4.3.2.2, §2.6, §22
Kit Services - §5.3.1.2, §8
Language Services - §10
Project Services - §18, §21, §23.1
Inclusions - §6.1.2(inbuild_work *work) {
    return Requirements::new(work, VersionNumberRanges::any_range());
}

inbuild_requirement *Requirements::anything_of_genre?Usage of Requirements::anything_of_genre:
Language Services - §11
Project Services - §40
Extensions Index Page - §1.1
The Installer - §2.4.4(inbuild_genre *G) {
    return Requirements::any_version_of(Works::new(G, I"", I""));
}

inbuild_requirement *Requirements::anything?Usage of Requirements::anything:
§3(void) {
    return Requirements::anything_of_genre(NULL);
}

§3. The most involved of the creators parses text. An involved example might be:

    genre=extension,author=Emily Short,title=Locksmith,min=6.1-alpha.2,max=17.2

We should return a requirement if this is valid, and write an error message if it is not. (If the text has multiple things wrong with it, we write only the first error message arising.)

At the top level, we have a comma-separated list of clauses. Note that the empty text is legal here, and produces an unlimited requirement.

inbuild_requirement *Requirements::from_text(text_stream *T,
    text_stream *errors) {
    inbuild_requirement *req = Requirements::anything();
    int from = 0;
    for (int at = 0; at < Str::len(T); at++) {
        inchar32_t c = Str::get_at(T, at);
        if (c == ',') {
            TEMPORARY_TEXT(initial)
            Str::substr(initial, Str::at(T, from), Str::at(T, at));
            Requirements::impose_clause(req, initial, errors);
            DISCARD_TEXT(initial)
            from = at + 1;
        }
    }
    if (from < Str::len(T)) {
        TEMPORARY_TEXT(final)
        Str::substr(final, Str::at(T, from), Str::end(T));
        Requirements::impose_clause(req, final, errors);
        DISCARD_TEXT(final)
    }
    return req;
}

§4. Each clause must either be all or take the form term=value:

void Requirements::impose_clause?Usage of Requirements::impose_clause:
§3(inbuild_requirement *req, text_stream *T,
    text_stream *errors) {
    Str::trim_white_space(T);
    if (Str::eq(T, I"all")) return;

    TEMPORARY_TEXT(term)
    TEMPORARY_TEXT(value)
    for (int at = 0; at < Str::len(T); at++) {
        inchar32_t c = Str::get_at(T, at);
        if (c == '=') {
            Str::substr(term, Str::start(T), Str::at(T, at));
            Str::substr(value, Str::at(T, at+1), Str::end(T));
            break;
        }
    }
    Str::trim_white_space(term);
    Str::trim_white_space(value);
    if ((Str::len(term) > 0) && (Str::len(value) > 0)) {
        Deal with a term-value pair4.1;
    } else {
        if (Str::len(errors) == 0)
            WRITE_TO(errors, "clause not in the form 'term=value': '%S'", T);
    }
    DISCARD_TEXT(term)
    DISCARD_TEXT(value)
}

§4.1. Deal with a term-value pair4.1 =

    if (Str::eq(term, I"genre")) {
        inbuild_genre *G = Genres::by_name(value);
        if (G) req->work->genre = G;
        else if (Str::len(errors) == 0)
            WRITE_TO(errors, "not a valid genre: '%S'", value);
    } else if (Str::eq(term, I"title")) {
        Str::copy(req->work->title, value);
    } else if (Str::eq(term, I"author")) {
        Str::copy(req->work->author_name, value);
    } else if (Str::eq(term, I"version")) {
        semantic_version_number V = Requirements::semver(value, errors);
        req->version_range = VersionNumberRanges::compatibility_range(V);
    } else if (Str::eq(term, I"min")) {
        semantic_version_number V = Requirements::semver(value, errors);
        req->version_range = VersionNumberRanges::at_least_range(V);
    } else if (Str::eq(term, I"max")) {
        semantic_version_number V = Requirements::semver(value, errors);
        req->version_range = VersionNumberRanges::at_most_range(V);
    } else {
        if (Str::len(errors) == 0)
            WRITE_TO(errors, "no such term as '%S'", term);
    }

• This code is used in §4.

§5.

semantic_version_number Requirements::semver?Usage of Requirements::semver:
§4.1(text_stream *value, text_stream *errors) {
    semantic_version_number V = VersionNumbers::from_text(value);
    if (VersionNumbers::is_null(V))
        if (Str::len(errors) == 0)
            WRITE_TO(errors, "not a valid version number: '%S'", value);
    return V;
}

§6. Writing. This is the inverse of the above function, and uses the same notation.

void Requirements::write?Usage of Requirements::write:
Nests - §9
Build Graphs - §6(OUTPUT_STREAM, inbuild_requirement *req) {
    if (req == NULL) { WRITE("<none>"); return; }
    int claused = FALSE;
    if (req->work->genre) {
        if (claused) WRITE(","); claused = TRUE;
        WRITE("genre=%S", req->work->genre->genre_name);
    }
    if (Str::len(req->work->title) > 0) {
        if (claused) WRITE(","); claused = TRUE;
        WRITE("work=%S", req->work->title);
    }
    if (Str::len(req->work->author_name) > 0) {
        if (claused) WRITE(","); claused = TRUE;
        WRITE("author=%S", req->work->author_name);
    }
    if (VersionNumberRanges::is_any_range(req->version_range) == FALSE) {
        if (claused) WRITE(","); claused = TRUE;
        WRITE("range="); VersionNumberRanges::write_range(OUT, req->version_range);
    }
    if (claused == FALSE) WRITE("all");
}

§7. Meeting requirements. Finally, we actually use these intricacies for something. Given an edition, we return TRUE if it meets the requirements and FALSE if it does not.

Note that requirements are based on the edition, not on the copy. If one copy on file of Version 3.2 of Monkey Puzzle Trees by Capability Brown meets a requirement, then so will all other copies of it.

int Requirements::meets?Usage of Requirements::meets:
Extension Manager - §6
Extension Bundle Manager - §6
Kit Manager - §7
Language Manager - §5
Pipeline Manager - §5
Template Manager - §5
Extension Services - §24
Kit Services - §15
Inclusions - §6(inbuild_edition *edition, inbuild_requirement *req) {
    if (req == NULL) return TRUE;
    if (req->work) {
        if (req->work->genre)
            if (Genres::equivalent(req->work->genre, edition->work->genre) == FALSE)
                return FALSE;
        if (Str::len(req->work->title) > 0)
            if (Str::ne_insensitive(req->work->title, edition->work->title))
                return FALSE;
        if (Str::len(req->work->author_name) > 0)
            if (Str::ne_insensitive(req->work->author_name, edition->work->author_name))
                return FALSE;
    }
    return VersionNumberRanges::in_range(edition->version, req->version_range);
}

§8. This is a very weak form of testing that requirement A is stronger than requirement B concerning the same work; it only catches the case where B imposes no version constraints.

int Requirements::trumps?Usage of Requirements::trumps:
Kit Services - §15(inbuild_requirement *A, inbuild_requirement *B) {
    if (B == NULL) return TRUE;
    if (A == NULL) return FALSE;
    if (B->work) {
        if (B->work->genre)
            if (B->work->genre != A->work->genre)
                return FALSE;
        if (Str::len(B->work->title) > 0)
            if (Str::ne_insensitive(B->work->title, A->work->title))
                return FALSE;
        if (Str::len(B->work->author_name) > 0)
            if (Str::ne_insensitive(B->work->author_name, A->work->author_name))
                return FALSE;
    }
    if (VersionNumberRanges::is_any_range(B->version_range)) return TRUE;
    return FALSE;
}