On this page:
6.1 Package Query Syntax
6.2 Package Query Omissions
6.3 Package Query Classifications
6.4 Parsing a Package Query
6.5 Package Query API
parsed-package-query
well-formed-package-query?
malformed-package-query?
resolved-package-query?
exact-package-query?
package-query?
package-query-variant?
boundary-flags-string?
coerce-parsed-package-query
format-parsed-package-query
make-exact-package-query
resolve-revision-interval
abbreviate-exact-package-query
parse-package-query
8.0

6 Package Queries

 (require xiden/query) package: xiden

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:

    <provider>:<package>:<edition>:<revision-min>:<revision-max>:<interval-bounds>

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

struct

(struct parsed-package-query (provider-name
    package-name
    edition-name
    revision-min
    revision-max
    interval-bounds))
  provider-name : string?
  package-name : string?
  edition-name : string?
  revision-min : string?
  revision-max : string?
  interval-bounds : string?
A parsed form of a package query.

procedure

(well-formed-package-query? v)  boolean?

  v : any/c

procedure

(malformed-package-query? v)  boolean?

  v : any/c

procedure

(resolved-package-query? v)  boolean?

  v : any/c

procedure

(exact-package-query? v)  boolean?

  v : any/c
Each procedure returns #t if v matches the respective rule in Package Query Classifications.

Returns #t if the input value is suitable for use as an argument to parse-package-query.

Returns #t if the input value is suitable for use as an argument to coerce-parsed-package-query. Specifically, the input can be a string, or an instance of parsed-package-query.

Returns #t if the argument is a suitable value for package-query-interval-bounds.

Returns a parsed-package-query from a variant value type.

Converts a parsed-package-query to a string, with no validation performed on the fields in advance. The fields set in query are joined into the string as-is.

procedure

(make-exact-package-query provider 
  name 
  revision-number) 
  exact-package-query?
  provider : string?
  name : string?
  revision-number : revision-number?
Returns an exact package query build from the arguments.

procedure

(resolve-revision-interval query 
  make-revision-number 
  #:default-bounds default-bounds) 
  
revision-number? revision-number?
  query : parsed-package-query?
  make-revision-number : (-> boolean? string? (or/c #f revision-number?))
  default-bounds : "ii"
Returns values created from make-revision-interval. The arguments for make-revision-interval is based on the information in query, such that each revision endpoint is first transformed to a revision number using make-revision-number.

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.

procedure

(abbreviate-exact-package-query query)  string?

  query : exact-package-query?
Like format-parsed-package-query, except the resulting string omits more fields. Since query is exact, this does not result in lost information.

procedure

(parse-package-query str)  parsed-package-query?

  str : string?
Converns a string to an instance of parsed-package-query.