The RBL storage format is a text based alternative to the resource fork of a Mac OS file. Its primary purpose is storage of Mac OS resource on CVS servers.

RBL can be used in other ways as well. As its structure is very simple, one could create RBL files on UNIX or other foreign platforms and convert them to real resource forks on the Mac. This would e.g. be a much easier approach than implementing tools to manipulate a resource fork's binary image directly.

The idea behind RBL is to be able to store resource forks as text files in CVS repositories. Also the files should be diffable and mergeable with the built in text file handling mechanisms of CVS.

Therefore, the resulting structure of RBL files has two main aspects:

It is line based.

Hence its name — RBL stands for Resource By Line. Lines are terminated by the standard UNIX NEWLINE character 0x0a. Lines can be very long. Their length can easily amount to several kilobytes or more.

It is a text file.

The data in RBL files is 8-bit-text. Binary data is RBL7 converted and thus data characters are all inbetween and including SPACE and ('?' + 127).

An RBL file consists of two major blocks:

1. the file header and
2. the resource block.

A line in an RBL file can have one of a few different types. The type of an arbitrary line can be detected examining the line's first character. Every line (the last line as well) in an RBL file is terminated by UNIX NEWLINE characer(ASCII 0x0a).

Mac OS resource data in general is binary data. All byte values from 0x00 to 0xff can be used. As mentioned above, RBL is a text based file format. So, before storage, the resource data needs to be converted from binary data to text data.

The conversion scheme is quite simple. Suppose you want to encode a block of n raw data bytes. Step one is to chop the data block into 7 bit wide chunks.

The lower significant 7 bits of the first byte are the first chunk. The highest significant bit is carried on to the next chunk. All further seven bit wide chunks are built by taking the carried bits from the previous byte, shifting them to the right (down to lower significance), and filling them on the left (on the side of high significance) to the width of 7 with the lower significant bits of the current byte. Leftover high significant bits are carried on. This goes on until there are no data bits left. The high significant bits of the last seven bit chunk might stay unused and default to zero.

Now we have a row of seven bit chunks in the range of 0x00 to 0x7f — still binary. Step two is to fold every 7 bit raw data chunk to 8 bit text by adding 0x3f (character '?').

Let's call this data encoding scheme RBL7.

RBL7 encoding is robust to everything CVS might do to it. All RBL7 encoded bytes have codes equal to or higher than 0x3f (character '?'). The '$' sign does not show up there, so we're safe against CVS keyword substitution. The characters '>', '=', and '<' don't show up in RBL7 encoded data. Thus, CVS conflict markers can be recognized and do not interfere with RBL7 encoded data.

If it turns out that using 8 bit text is a problem, the RBL7 conversion can optionally be replaced by a similar RBL6 conversion which groups 6 bit chunks. Doing that results in 7 bit encoded text (pure ASCII). Here, the file size increases. At this moment, only the RBL7 encoding is supported in MacCVSClient.

Note that in this description of the RBL file header, two comment lines have been inserted. As mentioned earlier, these comment lines do not add any information to the file — their contents is ignored when the file is read.

They do have a purpose though. In MacCVSClient, RBL is used to store resource forks as text files in CVS repositories. In the CVS environment, it is useful to have file formats that are easily mergeable. The CVS merge mechanism is based on diff3. That one is creating better and more reliable results, if changed parts of the input texts (like e.g. three revisions of a CVSed RBL file) are clearly interspersed by unchanged portions of text.

When inserting a few empty comment lines inbetween data lines in the RBL file, we make diff3's job during a CVS merge easier.

The resource block of the RBL file consists of one resource line for each resource. The resource lines are sorted by increasing pairs of resource type and index. Inbetween two resource lines, a single empty comment line is inserted. See part File Header above for an explanation of the empty comments.

head

It consists of the resource type (four bytes, big endian), the resource index (two bytes, big endian), the resource attributes (one byte). These seven data bytes are RBL7 encoded and thus result in the eight byte wide head part.

name

This is the resource name in clear text. Normally, no conversion is performed on it. If the resource name contains characters below SPACE though these are replaced by SPACE characters.

data

The RBL7 converted raw resource data.