Document `iftype`

[SeanTAllen]

It's been around for a long time as a "beta" sort of feature. It's required for some programs. At this point, I think we need to document it so that general users can access, use, and push our understanding of its shortcomings.

[rhagenson]

Looking at the tests on this directive the following clauses are recognized:

Standard if:

iftype A <: C then 
  ... 
end

With capability:

iftype A <: C box then 
  ... 
end

Tuple:

iftype (A, B) <: (C1, C2) then 
  ... 
end

Cardinality of tuples must match -- i.e., there is no deduplication via (A, B) <: C or nesting via A <: (C1, C2)

Recursive:

iftype A <: T[A] then 
  ... 
end

Mutually recursive:

iftype (A, B) <: (T[B], T[A]) then 
  ... 
end

Nested:

iftype A <: T then 
  iftype A <: C then 
    ... 
  end
end

Replace type args:

iftype X <: A #read then 
  ... 
end

[rhagenson]

My opinion on where this might best fit in the tutorial currently is Equality in Pony in a section called "Type Equality" or something similar. iftype checks both type equality and subtype relationship so A <: A is always true.

Forewarning: "the subtype in an iftype condition must be a type parameter or a tuple of type parameters" so the following does not pass the compiler:

primitive P
type T is P

actor Main
  new create(env: Env) =>
    iftype T <: P then
      None
    end

nor does replace the iftype expression with iftype P <: P then ... end

[EpicEric]

Also important to note that iftype has an else clause.