Kenaz

Metadata Specification

Metadata allows the association of data with Kenaz code. You can associate data, value, list of value with enum, class, element of an enum....

Quick Example :

metadata descField [apply({MetadataApply.Function, MetadataApply.Class, 
                           MetadataApply.Enum, MetadataApply.EnumElem})]
{
    string desc[required=true];
}

class test [descField(desc="this is a class")]
{
...
}
enum test2 [descField(desc="this is an enum")]
{
    a,
    b [descField(desc= "this is the element B of enum test2")]
}

What you can do with Kenaz metadata :

Create and define your own metadata in a easy-to-learn syntact.
Associate data with class, enum, element of enum, parametrable variable, function, external code.
apply constraints on metadata. Those constraints will be checked at compile-time

What you can't do with Kenaz metadata :

Check value of meta data in Kenaz code
modify metadata at run-time.
Store user-defined type. I don't think there is a need for it

Specification of a metadata file :

Metadata are described with the keyword metadata

metadata name-of-the-metadata-ensemble
{
}

Immediately after the name of the ensemble of metadata, come the metadata associated with the metadata definition. One important metadata is the "apply" metadata which can restrict the use of a metadata to a specified ensemble

metadata test[apply({list-of-application-target})]
{
}

the possible application target are described in the metadataApply enum :

enum MetadataApply [apiOutput()]
{
	Class,
	Function,		
	Enum,			
	Enum_element,		
	External_function,
	External_class,
	External_code,
	Metadata,
	Parametrable,
	Interface
}

Next comes the metadata-field. The syntact is :

field-type		field-name 
field-type		field-name [param] {constraints}
field-type []		field-name [param] {constraints}

field-type can be int,float,string or an enum.
[] tells the compiler that users are allowed to enter more than one value for this field. field-name can be anything that matches the Kenaz name definition.

Allowed params are :

required Boolean telling if the field must be filled or not. default = false
default Give a default value to the field. The type of the given default value must match the type of the field.
constraints See constraints above.

Kenaz metadata doesn't feature "positional paramater" like c#, and thus, you are forced to give the name of the field when you want to define it (like the "desc" field in our first example of metadata-use). But there is a special field name, "value". When using a metadata, if you don't give the name of the field you want to set, the kenaz compiler will automatically assign it to the field "value". Our first example can be rewritten like this :

metadata descField [apply({MetadataApply.Function, MetadataApply.Class,
                           MetadataApply.Enum, MetadataApply.EnumElem})]
{
    string value[required=true];
}

class test [descField("this is a class")] 
{
...
} 

 
enum test2 [descField("this is an enum")]
{ 
  a,
  b [descField("this is the element B of enum test2")] 
}

Note how we can omit mentioning the field name.

Constraints on metadata :

As you may know, users tends to do anything, and this also includes what you don't want them to do. To force them to give you only what you expect them to give, you can apply constraint on metadata. Let's take a simple example :

metadata intRange [apply=parametrable]
{
    int max;
    int min;
}

and, later in the Kenaz code :

class test
{
    parametrable int a [intRange(min=100, max=40)];
}

This is obviously stupid, as the min field is greater than the max one. Let's rewrite our metadata definition :

metadata intRange 
{
    int max {max > min};
    int min;
}

If later the user gives metadata with min>= max, the validation of metadata will fail, and so will the compilation process.
Constraints are nearly declared the same way as Kenaz conditional-code. Available operators are the standardcompare-operators(<,>,>=,<=, ==, != ), the logical operators ( &&, ||), and two extra operators, ! and ~.
The latter are used to force the presence (~) (or ! for the absence) of a field. In our previous exemple, the user isn't required to give a value to min or max field. He can also give min a value and not to max. Let's say, we want that if the user gives a value to min, then he must give one to max, while still allowing him to enter no value at all. We can do it that way :

metadata intRange
{
    int max {max > min} ;
    int min {~max};
}

In other words : if the user gives a value to min, he must give one to max, and max should always be greater than min.
A field not defined will have UNDEFINED value.

UNDEFINED < DEFINED yelds TRUE
UNDEFINED > DEFINED yelds TRUE
UNDEFINED <= DEFINED yelds TRUE
UNDEFINED =  < DEFINED yelds TRUE
UNDEFINED == DEFINED yelds FALSE
UNDEFINED != DEFINED  yelds FALSE
~UNDEFINED yelds FALSE
!UNDEFINED yelds TRUE

top of page