link-relations

This Haskell library provides a RFC-5988 web link relation datatype.

A simple web link between two web resources, e.g. a hyperlink in a webpage referring to another page, suggests that the resources are somehow related, but it doesn't say how they are related. For example, a blog post may link to the author's main page (relation: author of the post) but also link to the previous post (relation: previous post by chronological order).

Link relations provide a way to express the relation between resources linked by a web link.

A link relation type may be represented by a URI, or by a registered link relation name. IANA maintains a registry of link relations. This package provides access to them through a dedicated LinkRelation datatype.

How to Release

This package's source code is auto-generated using 3 files:

1. A Haskell source file template
2. CSV file containing the IANA link relation registry data
3. A Haskell program which embeds the data into the template as Haskell code

All 3 files are found in the util/ directory.

(1) Update the source

• To update the non-generated part of the code, edit the template file.
• To update the CSV to a new version, download it from https://www.iana.org/assignments/link-relations/link-relations-1.csv
• To modify the source generation process, edit the generator program

(2) Update version and date

If you downloaded a new CSV version, update the lastUpdated value in the generator program. You can find that date at http://www.iana.org/assignments/link-relations/link-relations.xhtml.

Update the package version number in the .cabal file. Use darcs diff to examine the changes in the generated source and pick a version number according to PVP. The most common change in the registry will probably be new link relations added, which means new API functions and therefore an increase of the minor version number (i.e. 3rd number, e.g. /0.1.5.3/ becomes /0.1.6.0/). That's because the LinkRelation constructors themselves aren't exported.

(3) Adjust other config

Near the top of the generator program file there is a configuration section (e.g. the update date, file paths, etc.). If you made any changes which require updates there, make the required modifications.

(4) Build and test

The generator program depends on the cassava package. The other dependencies are also dependencies of cassava (primarily bytestring and vector), which means you can install the dependencies like this:

$ stack install cassava

Run the generator program from the package toplevel. Either using the interpreter:

$ stack runhaskell util/generate.hs

Examine the result. Switch between the old generated source and the new one (which is generated as a separate file in the same directory).

Build the library itself:

$ stack build

(5) Record everything into the Darcs repo, make a tag, make a tarball etc.

As usual. Note that the 3 files in util/ (i.e. including the CSV data) and the generated source in src/, are all kept in the Darcs repo.