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
acc essor_method	Property	0, 1
array_ length_cname	Field	C identifier
arra y_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_nul l_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
chea der_filename	Anything (except parameters)	Header include path	Compiler will adds the specified header when thing is used.
c ommon_prefix	Enum	String	Removes a common prefix from enumeration values
` const_cname`	Class (non-GObject)	C type
c opy_function	Class (non-GObject)	C function name
cprefix	Module	String
ctype	Parameter (Function), Field	C type
d efault_value	Parameter (Function)	Any Vala value that would be valid for the type	Sets the default value for a parameter.
delegat e_target_pos	Parameter (Function)	Double (position between two Vala parameters)
deprecated	Anything (except parameters)	0, 1	Marks the thing as deprecated
depr ecated_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
f ree_function	Class (non-GObject)	C function name	Sets a free function for the struct
g ir_namespace	Module	String
` gir_version`	Module	Version
has_c opy_function	Struct	0, 1	marks the struct as having a copy function
has_dest roy_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	Double (Position between two Vala parameters)
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”
i s_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
na mespace_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
p rintf_format	Function	0, 1
rank	Struct	Integer
`` ref_function``	Class (non-GObject)	C function name
ref_f unction_void	Class (non-GObject)	0, 1
rename_to	Any Type	Vala identifier	Renames the 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
tak es_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
transf er_ownership	Function/D elegate/Signal (having a return value), Parameter (Function, Signal)	0, 1	Transfers ownership of the value
ty pe_arguments	Function/D elegate/Signal (having a return value), Property, Field, Parameter	Vala types, comma separated	Restricts the generic type of the thing
type_ch eck_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
typ e_parameters	Delegate, Class (non-GObject)	Vala generic type parameters, e.g. T, comma separated
un ref_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…

// ...