rapa

rapa copied to clipboard

1. Overview

The Array#pack and String#unpack methods are essentially maps from one data representation to another where the transform is controlled by a simple regular language. These methods are used extensively in Ruby code to implement marshalling and encoding.

All Ruby implementations have ad hoc, hand coded versions of these methods. In contrast, this project uses Ragel to describe the language of directives that controls how the transformations are performed. The transformations are then coded in small snippits (Ragel actions). The grammar of directives is language agnostic while the actions are coded in the implementation's target language. In this way, the logic of the directives is shared across all implementations.

2. Organization

The implementation-independent specifications of the directives languages are in the "machines" directory. The implementation-specific code for the methods and the actions are in subdirectories of the "actions" directory. To add code for a specific implementation, follow the example of the implementation for Rubinius. The following diagrams illustrate the necessary files:

machines/ pack.rl # description of Array#pack directives unpack.rl # description of String#unpack directives

actions/rubinius/ pack_actions.rl # code for each Array#pack operation pack_code.rl # code for Array#pack method definition unpack_actions.rl # code for each String#unpack operation unpack_code.rl # code for String#unpack method definition

3. Generating Files

The Rakefile contains tasks to generate the final source code from the directives languages and the actions. The task for a particular implementation sets the include path for Ragel to use so that implementation-specific actions are used by the implementation-independent directives definitions. For example, to generate the files for Rubinius, run:

rake build:rbx

This will generate pack.cpp and unpack.cpp in the root directory. To generate the files in a specific directory, use the DIR environment variable:

rake build:rbx DIR=/path/to/rubinius/machine/class

4. Specs

The specs for Array#pack and String#unpack are contained in the RubySpec project. Each Ruby implementation has its own method for running the RubySpecs. This project is not independent of some Ruby implementation. To run the specs, generate the code for a particular implementation and run the specs under that implementation.