Next Previous Contents

5. TRL Language Reference

TRL (Trove Request Language) is used for two central purposes in the Trove architecture. First, it is the request language used to request updates to a Trove archive. Second, it is the format in which FTP-browseable dumps of index data are emitted (and from which the index may be regenerated).

5.1 TRL Reference

Lexical analysis of TRL is simple (it's modeled on RFC822 message format). It consists of the required begin marker with version, followed by any number of tagged logical lines, followed by the required end marker, followed by an optional PGP signature.

A tagged logical line consists of a tag, followed by a colon, followed by a line of text, optionally followed by continuation lines. A tag is any sequence of printable non-space, non-colon characters beginning with an alphabetic. Continuation lines begin with whitespace or tab. Blank lines are ignored. # and end-of-line delimit comments.

Values in keyword fields (Locked, Action, Icon-Action, Resource-Action, Resource-Role) are case-insensitive.

Semantically, a TRL request consists of a preamble followed by any number of person or package updates.

The preamble consists a Contributor field followed by an optional Comment field. The Contributor should be the name of the person submitting the TRL request; it must correspond to the PGP key if both are present.

A person update may include Home-Page, Authorization-Mode, and Authorization-Secret fields directly corresponding to the schema. A Rename-To field is also supported.

A package update contains a package section followed by any number of resource sections. Order of lines within sections is not significant.

The END-TRL field may be followed by MIME-multipart attachments corresponding to `attached' resources in the TRL header.

An optional cryptosignature following attached resources may be used to authenticate the request.

Here's a motivating example of a package update.


BEGIN-TRL 0.6
Contributor: "Eric S. Raymond" <[email protected]>
Comment: This is a sample
# Replace package metadata
# Note: if this TRL were a dump rather than an action request, it
# would include Created and Last-Modified date fields and an
# Update-Count integer.
Package: fetchmail
Summary: A full-featured POP/IMAP mail retrieval daemon.
Description: fetchmail is a free, full-featured, robust, and
    well-documented remote mail retrieval and forwarding utility
    intended to be used over on-demand TCP/IP links (such as SLIP or
    PPP connections).  It retrieves mail from remote POP and IMAP 
    servers and forwards it to your local (client) machine's delivery
    system, so it can then be be read by normal mail user agents such
    as mutt, elm, pine, or mailx.  Comes with an interactive GUI
    configurator suitable for end-users.
Update-Notes: Anybody running a version older than 4.3.0 should
    definitely upgrade.
Latest-Version: 4.5.0
Last-Stable-Version: 4.5.0 
Icon: https://tuxedo.org/~esr/fetchmail/fetchmail.gif
Icon-Location: replica
Home-Page: https://tuxedo.org/~esr/fetchmail
Crawl-To: https://tuxedo.org/~esr/fetchmail/TROVE-METADATA
Owner: "Eric S. Raymond" <[email protected]>
#
# The following are list fields which update package-to-person relations
#
Authors: "Eric S. Raymond" <[email protected]>
Contacts: "Eric S. Raymond" <[email protected]>
Maintainers: "Eric S. Raymond" <[email protected]>, "Rob Funk" <[email protected]>,
              "Dave Bodenstab" <[email protected]>,
              "Al Youngwerth" <[email protected]> 
# This adds a person to the package notification list.
# The entire list could have been set with a `Notify' header, 
# or individual unsubscriptions done with an `Unsubscribe' header.
Subscribe: "Catherine Olanich Raymond" <[email protected]>
#
# The following are list fields which update package-to-package
# relations.  The two other relations are Extends and See-Also.
#
Supersedes: popclient
Requires: smtpdaemon
#
Discriminators: system/mail/{pop, imap}, 
              audience/{end-users, sysadmins},
              status/production,
              embedding/application,
              interaction/utility,
              license/GPL,
              platforms/{Linux, BSD}, 

Locked: TRUE
Action: replace

# Delete old source tarball
Resource: https://tuxedo.org/~esr/fetchmail/fetchmail-4.4.8.tar.gz
Action: delete

# Create new source tarball.
# Note: if this TRL were a dump rather than an action request, it
# would include Created and Last-Modified date fields and an
# Update-Count integer. 
Resource: https://tuxedo.org/~esr/fetchmail/fetchmail-4.4.9.tar.gz
Resource-Role: source
Resource-Location: replica
Version: 4.4.9
MIME-Type: application/data
Description: Gzipped source tarball of fetchmail sources
Locked: TRUE
Action: replace

# Change version field of existing metadata for FAQ
Resource: https://tuxedo.org/~esr/fetchmail/fetchmail-FAQ.html
Resource-Role: documentation
Version: 4.4.9
Action: merge
END-TRL

Person fields

All Person update requests must be authenticated.

This is a test load for the Person record parsing. It would have the effect of replacing all metadata references to "Eric S. Raymond" with "Thaddeus Q. Foonly".

Normally such an update would be used to change a contributor's primary email address, the spelling of his/her name, or his/her home page.


BEGIN-TRL 0.6
Contributor: "Eric S. Raymond" <[email protected]>
Person: "Eric S. Raymond" <[email protected]>
Home-Page: https://tuxedo.org/~esr
Rename-To: Thaddeus Q. Foonly <[email protected]>
END-TRL

Package fields

Resource fields

Resource roles

5.2 TRL Future Directions

Define and implement an XML presentation of TRL semantically equivalent to this one (at present, mature XML tools to support this are lacking).

Dates should accepted in ISO-8601. This is the format to use with the XML syntax.

Next Previous Contents