On this page:
7.1 Simple Queries
7.2 Specifying an Edition
7.3 Specifying Accepted Revisions
7.4 Marking Inclusive and Exclusive Endpoints
7.5 Omitting Information
8.0

7 Package Queries

To aid package discovery, you can request package definitions from configured hosts using a colon-separated package query string.

7.1 Simple Queries

In the simplest case, a package query contains only a provider name and a package name, like example.com:calculator. Such a query is understood to mean "the calculator package provided by example.com".

Why not just say calculator? Because providers are presumed unique, and using a verifiable identity to scope packages helps establish a name for your software across hosts. It also establishes a basis for comparison when two developers use the same package name but deliver different work.

7.2 Specifying an Edition

If you prefer a scientific calculator, the package author can provide that design under a different edition. Specify an edition using the next field.

example.com:calculator:scientific

7.3 Specifying Accepted Revisions

The next field is for requesting a specific revision of a package.

example.com:calculator:scientific:288

example.com:calculator:scientific:open-beta

A revision can be an exact nonnegative integer or a name. Names are aliases for numbers.

What about version ranges? Just add another revision to act as the maximum accepted revision.

example.com:calculator:scientific:288:288

From here we can change the endpoints of the interval to accept alternative packages. This is useful if some implementations are not available.

example.com:calculator:scientific:102:288

7.4 Marking Inclusive and Exclusive Endpoints

By default, revision intervals are inclusive of their endpoints. You can add flags to mark the interval as inclusive or exclusive of each endpoint. Use the letter i for inclusive, and e for exclusive. In the below form, revision 288 will not match this query because of the e on the right side of the two flags.

example.com:calculator:scientific:102:288:ie

Using integer interval notation:

Marking exclusive bounds are useful with revision names. The below query requests a scientific calculator’s closed beta implementation, up to but not including the production-ready revision.

example.com:calculator:scientific:closed-beta:production:ie

If the author did not define a revision name marking the end of a beta, then you would have to know the revision number in advance of writing the query. With the interval flags, you do not have to know any revision numbers.

When resolving revision names, xiden will raise an error for queries like these because they each resolve to a backwards interval:

example.com:calculator:scientific:production:closed-beta

example.com:calculator:scientific:9:0

example.com:calculator:scientific:3:3:ee

7.5 Omitting Information

You may omit certain fields for convenience and to accept defaults. Two contiguous colons will set the associated field to the empty string. Any contiguous colon sequence at the end of a query is implied and does not need to be typed.

example.com:calculator::production

Provider names and package names are required, but Xiden interprets other empty strings as unset values in a query. When searching for packages, it will use default values according to the following rules:

By these rules, example.com:calculator:teacher:1 matches only revision 1 of a calculator’s teacher edition. When searching for multiple packages, omitting information will cause Xiden to match against more packages. In that case, omitting revision information will result in matching against all revisions.