Revision as of 10:24, 2 December 2012

The idea of attributed types is that we would like to be able to refer to the _type_ that has already been assigned to another Vjet type's member.

By VJET types, we mean ctype, etype, mtype, itype,fytpe and mtype. Please read more about VJET Types in the VJET Type Reference Guide

Reasons

The initial motivations for this feature are:
* Ability to type exported members (functions and types)
* Reduce cut-n-paste errors with each client that wants to use export functions in a type-safe way
* Limit amount of physical typing and space taken up by redefined signatures

Structure

Here is the structure for an attributed type:
_Attributed-Global-Type_:  "::" _SimpleName_
_Attributed-Property-Type_: _Type-Name_ "::" _SimpleName_
_Attributed-Prototype-Type_: _Type-Name_ ":" _SimpleName_
_Attributed-Type_: _Attributed-Global-Type_ | _Attributed-Property-Type_ | _Attributed-Prototype-Type_
Since globals can be declared in more than 1 Vjet type (or in floating form), we do not support trying to use a global defined in a specific Vjet type as an attributed type.  All you need to do is refer to the global name since it is _global_.
Use of the colon and double-colon:
* ":" -- prototype ;  a.b.C:protoMember
* "::" -- property ;  a.b.C::propertyMember
* "::" -- global    ;  ::globalName

Restrictions

Due to circular dependencies and potential complexity between Vjet types referencing each other, the use of Attributed types is restricted to:
* Local variables -- var rate ;
* Function Expressions -- function(a, b) { ... }
* Object Literals -- {name: 'MrP', married: true}
* Object properties -- var p = new Object() ; p.age=10; p.name='MrP'

More

Some examples:

var a ; //< a.B:c  ; proto member "c" from type a.B
var j ; //< a.B::c ; property member "c" from type a.B
var k ; //< ::c    ; global member "c"

We use the :: to mean type, as in the type::SomeType syntax we use with Type References.  Thus it is consistent when we reuse the :: for global property (roughly speaking it means the property member in the global space).
In JavaScript you can have a ''property'' X and a ''prototypical'' ''property'' X.  To differentiate between these we use :: (property) and : (prototype) to identify which we mean within the Vjet type..

Example

The following type Donor, acts just like that.  We will have other code refer to its members to type some local variables.  That is to say, we will use Donor for our attributed type references.

vjo.ctype('Donor')
.globals({
MAX: 10, //< Number
NAME: 'eBay', //< String
OK: false, //< boolean
//> public boolean isEbay(String)
isEbay: function(name) {
return NAME == name ;
}
})
.props({
DATE: Date, //< type::Date
today: new Date //< Date
})
.protos({
notes: undefined, //< String[]
//> int len(String)
//> int len(Array)
len: function(obj) {
return obj.length ;
}
})
.endType();

The following declarations all leverage pre-declared type information from the ctype, Donor.

// attributed to globals in Donor
var +max+ = 123 ; //< ::MAX
var +name+ = 'abc'; //< ::NAME
var +ok+ = true ; //< ::OK
// attributed to props in Donor
var date ; //< Donor::DATE
var today ; //< Donor::today
// attributed to protos in Donor
var names = ['why', 'not']; //< Donor:notes
var f ; //< Donor:len
var length = f('Ebay') ; //< int
length = f(names) ;
 
var contract = \{
rate: undefined, //< ::MAX
start: undefined, //< Donor::today
isEbay: vjo.NEEDS''IMPL //< ::isEbay
}

Note that in freeform JavaScript (ie, not inside a Vjet structured type), you can simply declare a global by omitting the var in the declaration.  Vjet does not allow globals defined inside a Vjet .globals(...) section to use attributed types but does support it in freeform JavaScript.

// All the following are global variables that are declared
// using attributed types from Donor
// attributed to globals in Donor
max = 123 ; //< ::MAX
name = 'abc' ; //< ::NAME
ok = true ; //< ::OK
// attributed to props in Donor
date ; //< attrtypes.Donor::DATE
today ; //< attrtypes.Donor::today
// attributed to protos in Donor
names = ['why', 'not']; //< attrtypes.Donor:notes
f ; //< attrtypes.Donor:len
length = f('Ebay') ; //< int
length = f(names) ;
 
contract = {
rate: undefined, //< ::MAX
start: undefined, //< attrtypes.Donor::today
isEbay: vjo.NEEDS''IMPL //< ::isEbay
}