1.1.2 Describe-Compute

This is where poke comes into play. Basically, it allows you to describe the characteristics of the data you want to compute on, and then decodes and encodes it for you, taking care of the gory details. That way you can concentrate your energy on the fun part: computing on the data at your pleasure.

Of course, you are still required to provide a description of the data. In the Poke language, these descriptions take the form of type definitions, which are declarative: you specify what you want, and poke extracts the how from that.

For example, consider the following Poke type definition:

type Packet =
  struct
  {
    uint<16> magic == 0xef;
    uint<32> size;
    byte[size] data @ 8#B;
  };

This tells poke that, in order to decode a Packet, it should perform the following procedure (a similar procedure is implied for encoding):

• - Read two bytes from the IO space, mount them into an unsigned 16-bit integer using whatever current endianness, and put it in magic. If this unsigned 16-bit integer doesn’t equal to 0xef, then stop and emit a “data integrity” error.
• - Read four bytes, mount them into an unsigned 32-bit integer using the same endianness, and put it in size.
• - Seek the IO space to advance 16 bits.
• - Do size times:
  • - Read one byte and mount it into an unsigned 8-bit integer.
  • - Put the integer in the proper place in the data array.

If during this procedure an end of file is encountered, or some other erroneous condition happens, an appropriate error is raised.

In the procedure sketched above we find a sequence of operations, implied by the struct type, and a loop, implied by the array type. As we shall see later in this book, it is also possible to decode conditionally. Union types are used for that purpose.