6 Package Queries

A package query is a colon-separated string that matches against the discovery information in package definitions. Use package queries to define version intervals.

6.1 Package Query Syntax

With no omissions, a query follows this form:

e.g. "example.com:htdp:teachers:8:201:ii"

<provider> is, as expected, the name of the package’s provider. This may or may not be the author of the package. A domain name for a provider name is not required, but using one is helpful if your package appears across multiple services.

<package> is the name of the package.

<revision-min> and <revision-max> can each be a revision number or a revision name.

Finally, <interval-bounds> can be "ee", "ie", "ei", or "ii". These characters control if <revision-min> or <revision-max> are interpreted as inclusive or exclusive interval boundaries. The first character controls <revision-min>. The second character controls <revision-max>. If the character is "i", then the boundary is inclusive of the defined revision. If "e", exclusive.

6.2 Package Query Omissions

To omit a field, use consecutive colons, or leave fields off the end of the string. An omitted field is set to the empty string.

e.g. "example.com:htdp::8::ie", or "example.com:htdp".

When a field is set to the empty string, a fallback value may be used instead. This section does not define a standard for default values because those details are catalog-specific.

The empty string is equivalent to using only default values.

6.3 Package Query Classifications

A parsed package query is an instance of parsed-package-query.

A well-formed package query is a parsed package query that uses strings for all fields.

A malformed package query is a parsed package query that is not a well-formed package query.

A resolved package query is a well-formed package query where the minimum and maximum revisions are digit strings that can be trivially converted to revision numbers.

An exact package query is a resolved package query where the minimum and maximum revisions form an inclusive interval that matches exactly one version.

6.4 Parsing a Package Query

Assume that a query Q is bound to a well-formed package query with no omissions. In that case you can construct an instance of parsed-package-query using (apply parsed-package-query (string-split Q ":")).

In the general case where fields may be omitted, any missing fields should be set to the empty string like so:

(define (parse-package-query s)

(define user-defined (string-split s ":"))

(define num-fields (length user-defined))

(apply parsed-package-query

(build-list (procedure-arity parsed-package-query)

(λ (i)

(if (< i num-fields)

(list-ref user-defined i)

"")))))

6.5 Package Query API

make-revision-number accepts two arguments.

If the first argument is #f, then the second argument is the same value bound to (parsed-package-query-revision-min query).

If the first argument is #t, then the second argument is the same value bound to (parsed-package-query-revision-max query).

The first argument is useful for generating mock data for tests, but is otherwise unhelpful when normalizing an arbitrary revision to a revision number.

Output integers are adjusted according to (parsed-package-query-interval-bounds query), or default-bounds if (boundary-flags-string? (parsed-package-query-interval-bounds query)) is #f.