Repository navigation
Expand file tree
/
Copy pathREADME
More file actions
57 lines (42 loc) · 2.42 KB
/
Copy pathREADME
File metadata and controls
57 lines (42 loc) · 2.42 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54<
69E7
/div>
55
56
57
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.