xp-framework/rfc — Issue #197: Type literals in tokens
Author: thekid
Created: 2011-10-17 16:05:14+00:00
State: closed
Labels: framework, implemented

Scope of Change
====
A common way to denote type literals in generated sourcecode will be
introduced.

Rationale
====
An example of where this is used is the type dispatching methods
described in xp-framework/rfc #195. Another example is generics generation,
as described in xp-framework/rfc #193.

Functionality
====
The type literals as used in strings in the XP Framework or literals
in the XP Language are currently defined as:

Primitives (lang.Primitive):
* string
* int
* double
* bool

Value types (lang.XPClass):
* lang.types.String (class, PHP literal: String)
* lang.Runnable (interface, PHP literal: Runnable)
* lang.reflect.Parameter (package class, PHP literal: lang·reflect·Parameter)

Special types (lang.Type):
* var (omit type in PHP)
* void (only for use in return types, PHP doesn't support this)

Requirements
----
The following issues must be addressed:

* The type literals used in generated sourcecode need to obey PHP's
syntax rules for class and method names (see "related documents").
* Because PHP's class and method tokens are case-insensitive, there
must be a way to distinguish classes and primitives with the same
name, e.g. the String class vs. the string primitive.
* Fully qualified class names (using the middle-dot) must be supported.
* There must be a way to distinguish generated tokens from those a
user has written, for reflection.

Definitions
----
Derived from this, the following definitions can be made:

A primitive is denoted by the sign `þ` (Alt-Gr+P) and the
primitive's name. Examples: `þstring`, `þint`.

A value type is denoted by its literal form, that is, what is
written inside the type declaration. Examples: `String`,
`Runnable`, `lang·reflect·Parameter`.

Type and method names containing these tokens include two
middle-dots (`··`, Alt-Gr+.) and the tokens thereafter.
Tokens are separated by a `¸`, Alt-Gr+´).

Example: Method generation
----
Because methods are unique by name in PHP, we need to generate a
dispatcher method and one for each variant:
Source:

```php

```

Generated:

```php

```

Example: Class generation
----
Here, classes will be generated by the `create()` function.
Because class names must be unique in PHP, we will need to generate
a class for each permutation of a generic type.

Declaration:

```php
implements Map { ... }
?>
```

Invocation:

```php
();
$t= new HashTable();
?>
```

Generated:

```php

```

Security considerations
====
n/a

Speed impact
====
n/a

Dependencies
====
Changes to core functionality, thus 5.8-SERIES.

Related documents
====
* xp-framework/rfc #37 - Fully qualified class names (where the middle-dot was
originally defined as usage).
* http://lxr.php.net/source/ZendEngine2/zend_language_scanner.l#1329 -
regex for PHP class and method tokens (a "LABEL").