Struct Methods (GNU poke Manual)

4.10 Struct Methods

At this point you may be thinking something on the line of “hey, since variables and functions are also members of the struct, I should be able to access them the same way than fields, right?”.

So you will want to do:

(poke) var p = Packet  12#B
(poke) p.real_size
(poke) p.corrected_crc

But sorry, this won’t work.

To understand why, think about the struct building process we sketched above. The mapper and constructor functions are derived/compiled from the struct type. You can imagine them to have prototypes like:

Packet_mapper (IOspace, offset) -> Packet value
Packet_constructor (template)   -> Packet value

You can also picture the fields, variables and functions in the struct type specification as being defined inside the bodies of Packet_mapper and Packet_constructor, as their contents get mapped/constructed. For example, let’s see what the mapper does:

Packet_mapper:

  . Map a byte, put it in a local `magic'.
  . Map a byte, put it in a local `size'.
  . Calculate the real size, put it in a local `real_size'.
  . Map an array of real_size bytes, put it in a local `payload'.
  . Map an array of real_size bytes, put it in a local `control'.
  . Compile a function, put it in a local `corrected_crc'.
  . map a byte, call the function in the local `corrected_crc',
    complain if the values are not the same, otherwise put the
    mapped byte in a local `crc'.
  . Build a struct value with the values from the locals `magic',
    `size', `payload', `control' and `crc', and return it.

The pseudo-code for the constructor would be almost identical. Just replace "map a byte" with “construct a byte”.

So you see, both the values for the mapped fields and the values for the variables and functions defined inside the struct type end as locals of the mapping process, but only the values of the fields are actually put in the struct value that is returned in the last step.

This is where methods come in the picture. A method looks very similar to a function, but it is not quite the same thing. Let me show you an example:

load supercrc;

type Packet =
  struct
  {
    byte magic == 0xab;
    byte size;

    var real_size = (size == 0xff ? 0 : size);

    byte[real_size] payload;
    byte[real_size] control;

    fun corrected_crc = int:
    {
      try return calculate_crc (payload, control);
      catch if E_div_by_zero { return 0; }
    }

    int crc = corrected_crc;

    method c_crc = int:
    {
      return corrected_crc;
    }
  };

We have added a method c_crc to our Packet struct type, that just returns the corrected superCRC (patented, TM) of a packet. This can be invoked using dot-notation, once a Packet value is mapped/constructed:

(poke) var p = Packet  12#B
(poke) p.c_crc
0xdeadbeef

Now, the important bit here is that the method returns the corrected crc of a Packet. That’s it, it actually operates on a Packet value. This Packet value gets implicitly passed as an argument whenever a method is invoked.

We can visualize this with the following “pseudo Poke”:

method c_crc = (Packet SELF) int:
{
   return SELF.corrected_crc;
}

Fortunately, poke takes care to recognize when you are referring to fields of this implicit struct value, and does The Right Thing(TM) for you. This includes calling other methods:

method foo = void: { ... }
method bar = void:
{
 [...]
 foo;
}

The corresponding “pseudo-poke” being:

method bar = (Packet SELF) void:
{
 [...]
 SELF.foo ();
}

It is also possible to define methods that modify the contents of struct fields, no problem:

var packet_special = 0xff;

type Packet =
  struct
  {
    byte magic == 0xab;
    byte size;
    [...]

    method set_size = (byte s) void:
    {
      if (s == 0)
        size = packet_special;
      else
        size = s;
    }
  };

This is what is commonly known as a setter. Note, incidentally, how a method can also use regular variables. The Poke compiler knows when to generate a store in a normal variable such as packet_special, and when to generate a set to a SELF field.

Given the different nature of the variables, functions and methods, there are a couple of restrictions:

Functions can’t set fields defined in the struct type.
This will be rejected by the compiler:
```
type Foo =
  struct
  {
     int field;
     fun wrong = void: { field = 10; }
  };
```
Remember the construction/mapping process. When a function accesses a field of the struct type like in the example above, it is not doing one of these pseudo SELF.field = 10. Instead, it is simply updating the value of the local created in this step in Foo_mapper:
```
Foo_mapper:

 . Map an int, put it in a local `field'.
 . [...]
```
Setting that local would impact the mapping of the subsequent fields if they refer to field (for example, in their constraint expression) but it wouldn’t actually alter the value of the field field in the struct value that is created and returned from the mapper!

This is very confusing, so we just disallow this with a compiler error “invalid assignment to struct field”, for your own sanity 8-)
Methods can’t be used in field constraint expressions, nor in variables or functions defined in a struct type.
How could they be? The field constraint expressions, the initialization expressions of variables, and the functions defined in struct types are all executed as part of the mapper/constructor and, at that time, there is no struct value yet to pass to the method.

If you try to do this, the compiler will greet you with an “invalid reference to struct method” message.

Something to keep in mind about methods is that they can destroy the integrity of the data stored in a struct. Consider for example the following struct type:

type Packet =
  struct
  {
    byte magic == 0xab;
    byte size : size <= 4096;
    [...]

    method set_size = (byte s) void:
    {
      if (s == 0)
        size = packet_special;
      else
        size = s;
    }
  };

Observe how this new version of Packet has an additional constraint that specifies size should not exceed 4096. However, when the method set_size is executed the constraints are not checked again. This is useful at times, but can also lead to unintended data corruption.

A solution for this problem is to make methods aware of the restrictions. Like in this case:

type Packet =
  struct
  {
    var MAXSIZE = 4096;

    byte magic == 0xab;
    byte size : size <= MAXSIZE;
    [...]

    method set_size = (byte s) void:
    {
      if (s == 0)
        size = packet_special;
      else if (s > MAXSIZE)
        raise E_inval;
      else
        size = s;
    }
  };

Note how we use a variable MAXSIZE in order to avoid hard-coding 4096 twice in the struct definition.

Occasionally it is useful to access to additional properties of a containing struct or union in a method, other than its fields. For this purpose it is possible to refer explicitly to the struct using the SELF keyword. Note that the value referred has type any.

For example, this is how we could print the name of the current alternative in a pretty-printer for an union:

type Foo =
  union int<32>
    {
      int<32> One == 1;
      int<32> Two == 2;
      method _print = void:
      {
        printf ("%s (%v)", SELF'ename (0), SELF'elem (0));
      }
    };