// p≡p API Y language

// Copyleft (c) 2019-2020, p≡p foundation
// this file is under GNU General Public License 3.0
// see LICENSE.txt

// written by Volker Birk and Nana Karlstetter

// typekind
// --------
// typekinds are all idl defined
// typekinds can be used to create user defined types
// a basetype can be specialized
// an enum-type can be defined using items
// a struct-type can be defined using fields
// a list can be defined holding a type T, where T can be any defined type

// types
// -----
// types are either:
//      * idl-defined
//          * basetypes
//      * user-defined
//          * deftype
//          * enum
//          * struct
//          * list
//      * undefined
// any defined type can be instantiated.

// Generic types
// generic typeskinds list, pair, set
// can only be used to define types
// they can not be used as types (e.g. in params, fields)

idl {
    typekinds {
        basetype;
        deftype;
        enum;
        struct;
        generics {
            list;
            pair;
            set;
        }
    }
    basetypes {
        string;     // text
                    // p≡p engine uses UTF-8 strings which are NFC normalized.
                    // Cf. https //dev.pep.foundation/Engine/Basic%20Concepts%20of%20the%20pEp%20Engine
        binary;     // binary data
        int;        // signed integer number
        uint;       // unsigned integer number
        size;       // size in memory
        bool;       // true or false
        // timestamp;  // point of time
        opaque;     // opaque type (was: 'any')
    }
}


decl package @name;
decl api @name;

// deftype
decl deftype @name;
decl as @type;

// enum
decl enum @name;
decl item @name;

// struct
decl struct @name;
decl field @type @name;  // optional: function=free for a free function

// method
decl method @name;
decl param @mode @type @name;
decl throws @name;





// unimplemented
//-----------------
// decl internal < field >; // internal field, p≡p engine only
// decl flag @name;

// decl protocol @name;
// decl construct, new is construct;

// readonly in parm, ownership remains with caller
// decl use @type @name (mode=use) alias parm;

// inout parm, ownership remains with caller
// decl supply @type @name (mode=supply) alias parm;

// in parm, ownership goes to callee
// decl provide @type @name (mode=provide) alias parm;

// factory delivers this, ownership goes to caller
//decl create @type @name (mode=create) alias parm;

// decl throws @except;
// decl caveat(mode=caveat) alias doc;