Editing HSFFIG/Tutorial (section)

==== Regular variables ====

Regular variables contain either values or pointers to other variables (not functions). For this sort of imports, the following identifiers are created:

* a pointer to the variable itself: prefix is "p_"
* a nullary function returning variable's value in the '''IO''' monad: prefix is "v_"
* a unary function taking a value and assigning it to the variable (in the  '''IO''' monad): prefix is "s_"

So, for a variable declared as

<pre>
extern int a;
</pre>

FFI import declarations will be as follows:

<pre>
foreign import ccall "header.h &a"
  ___2___ :: Ptr (CInt)
p_a = ___2___
v_a = peek ___2___
s_a = poke ___2___
</pre>

where ___''2''___ is one of internal unique names that '''hsffig''' assigns to all identifiers it encounters in the header file.

So, to retrieve value from a variable, ''v_a'' is used:

<pre>
x <- v_a -- equivalent to peek p_a
</pre>

To update the variable value, ''s_a'' is used:

<pre>
s_a 4 -- equivalent to poke p_a 4
</pre>

If a variable contains pointer to a value, e. g

<pre>
extern int *ap;
</pre>

then it is imported as follows:

<pre>
foreign import ccall "header.h &ap"
  ___3___ :: Ptr (Ptr (CInt))
p_ap = ___3___
v_ap = peek ___3___
s_ap = poke ___3___
</pre>

so to dereference the pointer, additional ''peek'' is needed:

<pre>
c <- v_ap >>= peek
</pre>

and ''s_ap'' will update the variable itself with new address, rather than the value it points to.