GIDL metadata format

This section describes the format of .metadata files as used by vapigen as additional information for .vapi file generation. Some of the information specified in the metadata can be used to set Attributes as well.

Comments

Comments start with a # and end at the end of a line. For example:

# this is a comment

Other Lines

Every non-comment line in the file is made of up two sections: the specifier, and the parameters.

The specifier is the first text to appear on the line, and it specifies what the rest of the line will be modifying.

The parameters are a space separated list of a parameter name, followed by an equals sign and the value enclosed in quotes.

For example, this line sets parameter1 and parameter2 on foo.bar:

foo.bar parameter1="value" parameter2="value"

Specifiers

Specifiers always use the C name for whatever it is you are modifying. For example if your namespace is Foo, and the Vala name for the type is Bar, then you would use FooBar.

Specifiers may also use wildcards, and all items that partially match the specifier will be selected. For example:

*.klass hidden="1"

will hide the klass field in all types.

Specifying Different Things

To specify a:

Function	name_of_function
Type	Type
Property	Type:property_name
Signal	Type::signal_name
Field	Type.field_name
Parameter (Function)	name_of_function.param
Parameter (Delegate)	DelegateName.param
Parameter (Signal)	Type::signal_name.param

For example, hiding a symbol:

Type	Foo hidden="1"
Function	some_function hidden="1"
Field	Foo.bar hidden="1"

Properties Reference

The format for the entries will be like so

Name	Applies To	Values	Description
foobar	Signal, Function, Class, Struct, etc	The acceptable values	The description goes here.

And in alphabetical order:

Name	Applies To	Values	Description
abstract	Class, Function	0, 1
accessor_method	Property	0, 1
array_length_cname	Field	C identifier
array_length_pos	Parameter (Function)	Double (position between two Vala parameters)	Sets the position of the length for the parameter, length needs to be hidden separately.
array_length_type	Parameter (Function), Function (returning an array), Field	C type
array_null_terminated	Function (returning an array), Parameter (Function), Field	0, 1
async	Function	0, 1	Force async function, even if it doesn’t end in _async
base_class	Class	C type	Marks the base class for the type
base_type	Struct	Vala type	Marks the struct as inheriting
cheader_filename	Anything (except parameters)	Header include path	Compiler will add the specified header when thing is used.
common_prefix	Enum	String	Removes a common prefix from enumeration values
const_cname	Class (non-GObject)	C type
copy_function	Class (non-GObject)	C function
cprefix	Module	String
ctype	Parameter (Function), Field	C type
default_value	Parameter (Function)	Any Vala value that would be valid for the type	Sets the default value for a parameter.
delegate_target_pos	Parameter (Function)	Double (position between two Vala parameters)
deprecated	Anything (except parameters)	0, 1	Marks the thing as deprecated
deprecated_since	Anything (except parameters)	Version	Marks the thing as deprecated
ellipsis	Function	0, 1	Marks that the function has a variable argument list
errordomain	Enum	0, 1	Marks the enumeration as a GError domain
finish_name	Function	C function name	Sets custom asynchronous finish function
free_function	Class (non-GObject)	C function name	Sets a free function for the struct
gir_namespace	Module	String
gir_version	Module	Version
has_copy_function	Struct	0, 1	marks the struct as having a copy function
has_destroy_function	Struct	0, 1
has_emitter	Signal	0, 1
has_target	Delegate	0, 1
has_type_id	Class, Enum, Struct	0, 1	Marks whether a GType is registered for this thing
hidden	Anything	0, 1	Causes the selected thing to not be output in the vapi file.
immutable	Struct	0, 1	Marks the struct as immutable
instance_pos	Delegate (Position between two Vala parameters)	Double
is_array	Function (returning an array), Parameter, Field	0, 1	Marks the thing as an array
is_fundamental	Class (non-GObject)	0, 1
is_immutable	Class (non-GObject)	0, 1
is_out	Parameter	0, 1	Marks the parameter as “out”
is_ref	Parameter	0, 1	Marks the parameter as “ref”
is_value_type	Struct, Union	0, 1	Marks type as a value type (aka struct)
lower_case_cprefix	Module	String
lower_case_csuffix	Interface	String
name	Any Type, Function, Signal	Vala identifier	Changes the name of the thing, does not change namespace
namespace	Any Type	String	Changes the namespace of the thing
namespace_name	Signal Parameter	String	Specify the namespace of the parameter type indicated with type_name
no_array_length	Function (returning an array), Parameter (Function, Delegate)	0, 1	Does not implicitly pass/return array length to/from function
nullable	Function (having a return value), Parameter	0, 1	Marks the value as nullable
owned_get	Property	0, 1
parent	Any module member	String (Namespace)	Strip namespace prefix from symbol and put it into given sub-namespace
printf_format	Function	0, 1
rank	Struct	Integer
ref_function	Class (non-GObject)	C function name
ref_function_void	Class (non-GObject)	0, 1
rename_to	Any Type	Vala	Renames the identifier type to something else, ie fooFloat to float (not exactly the same as name, AFAIK name changes both the vala name and the cname. rename_to adds the required code so that when the rename_to’ed type is used, the c type is used)
replacement	Anything (except parameters)	The thing that replaces this	Specifies a replacement for a deprecated symbol
sentinel	Function (with ellipsis)	C value	The sentinel value marking the end of the vararg list
simple_type	Struct	0, 1	Marks the struct as being a simple type, like int |
takes_ownership	Parameter (Function, Delegate)	0, 1
throws	Function	0, 1	Marks that the function should use an out parameter instead of throwing an error
to_string	Enum	C function name
transfer_ownership	Function/Delegate/Signal (having a return value), Parameter Signal)	0, 1	Transfers ownership of the value
type_arguments	Function/Delegate/Signal (having a return value), Property, Field, Parameter	Vala types, comma separated	Restricts the generic type of the thing
type_check_function	Class (GObject)	C function/macro name
type_id	Struct, Class (GObject)	C macro
type_name	Function (having a return value), Property, Parameter, Field	Vala type name	Changes the type of the selected thing. Overwrites old type, so “type_name” must be before any other type modifying metadata
type_parameters	Delegate, Class (non-GObject)	Vala generic type parameters, e.g. T, comma separated
unref_function	Class (non-GObject)	C function name
value_owned	Parameter (Function)	0, 1
vfunc_name	Function	C function pointer name
virtual	Function	0, 1
weak	Field	0, 1	Marks the field as weak

Examples

Demonstrating…

// ...