embedc.fdoc

@tangler ex1 = examples/embedc/ex1.flx
@title Embedding C++
@h1 Basics
Felix is a unique language in that, unlike other languages, it does
not have any primitive types.

Instead, Felix provides machinery to <em>lift</em> types from C++ code.
This means Felix is really a C++ meta-programming language.

I will show the basics here but first a caveat: we have to use weird
names for things to avoid conflicts with the Felix standard library.

@tangle ex1
type cplx = "::std::complex<double>" 
  requires header '#include <complex>'
;
ctor cplx : double * double = 
  "::std::complex<double>($1,$2)"
;
fun + : cplx * cplx -> cplx = "$1+$2";
fun - : cplx * cplx -> cplx = "$1-$2";
fun * : cplx * cplx -> cplx = "$1*$2";
fun / : cplx * cplx -> cplx = "$1/$2";
fun == : cplx * cplx -> bool = "$1==$2";
fun real: cplx -> double = "$1.real()";
fun imag: cplx -> double = "$1.imag()";
fun abs: cplx -> double = "$1.abs()";
fun arg: cplx -> double = "$1.arg()";
fun norm: cplx -> double = "$1.norm()";
fun conj: cplx -> double = "$1.conj()";

typedef polarbear = cplx;
ctor polarbear: double * double = "::std::polar<double>($1,$2)";

fun str (x: cplx) => x.real.str + "+" + x.imag.str + "i";

// test
var x = cplx (1.0,2.0);
var y = polarbear (1.0,0.5);
println$ (x+y).str;
println$ (x == y).str;
@
@h2 Type Classes
Let us try an experiment:
@tangle ex1
println$ (x,y);
@

If you run it at this point without the rest of the tutorial, this happens:
@pre
CLIENT ERROR
[flx_frontend/flx_typeclass.ml:752: E367] [Cannotmatch] Cannot instantiate virtual str<17781>[Nominal[] cplx]
In /Users/skaller/felix/src/packages/core_type_constructors.fdoc: line 693, cols 4 to 59
692: instance[T] Str[T*T] {
693:    fun str (t1:T, t2:T) => "("+str t1 + ", " + str t2+")";
        ********************************************************
694: }
@
Its not very helpful. But here is a fix:
@tangle ex1
instance Str[cplx] {
  fun str (x: cplx) => x.real.str + "+" + x.imag.str + "i";
}
@
and now we get this:
@pre
(1+2i, 0.877583+0.479426i)
@
To understand what's going on you need to see some of the
Standard Library:
@felix
class Str [T] {
  virtual fun str: T -> string;
}
@
By instantiating the virtual function in an @{instance} the definition
is available universally.

@h1 Another type class
Since the last type class was a bit easy here's a slightly harder one.. only 
slightly harder I promise!
@felix
// equality: technically, equivalence relation
class Eq[t] {
  virtual fun == : t * t -> bool;
  virtual fun != (x:t,y:t):bool => not (x == y);

  axiom reflex(x:t): x == x;
  axiom sym(x:t, y:t): (x == y) == (y == x);
  axiom trans(x:t, y:t, z:t): x == y and y == z implies x == z;

  fun eq(x:t, y:t)=> x == y;
  fun ne(x:t, y:t)=> x != y;
  fun \ne(x:t, y:t)=> x != y;
  fun \neq(x:t, y:t)=> x != y;
}
@
This is a Felix <em>type class</em> . The design is modelled after Haskell.
It has:

<ol>
<li> A name @{Eq}
<li> A type parameter @{t}
<li> An undefined virtual function for equality
<li> An virtual function for inequality with a default definition
<li> A set of @{axiom} which help to define the semantics
<li> A collection of derived functions all of which are trivial renamings
</ol>

You have already seen the syntax for instantiating virtuals by
setting the type variable @{t} to the type @{cplx}. The inquality
can be defined as well but if not, as in this case, is derived
from the euqliaty.

The derived functions are available with the class also, but
cannot be defined in an @{instance}.

@h1 TeX symbols
You may have notices in the @{Eq} type class that there is a 
function with the weird name @{\ne}. Which shown as \(\neq\) in TeX.