========================
BridgeSupport XML format
========================

-------------------
A short description
-------------------

Introduction
============

This project implements a generator for the XML metadata format introduced in
Leopard and shared between PyObjC and RubyCocoa. Hopefully other bridges will
start using this format as well.

At the time I'm writing this the XML format is in flux is desperately missing
some documentation. This document tries to fill the gap but is not reference
documentation for the medatadata format.

Document structure
==================

The document is an ``signatures`` element with an optional ``version`` 
attribute. This document describes version ``1.0``.

The child elements of the ``signatures`` describe the various objects that
can be wrapped. Classes are special: instead of describing all classes in the
metadata we only describe classes and methods that require special treatment,
that is those were the normal Objective-C runtime metadata doesn't contain
enough information to wrap them correctly.

The following section describe the various elements in the metadata format.

64-bit support
--------------

The metadata file supports 32-bit and 64-bit builds in a single file. This
is done by adding a 64-bit version of attributes when the attribute has 
different values on 64-bit and 32-bit builds. When the 64-bit version is not
present the value is assumed to be the same as on 32-bit builds.

BOOLEAN attributes
------------------

Attributes that are marked as ``BOOLEAN`` can have two values: ``true`` or
``false`` (with the obvious interpretation for those values).

``depends_on``
--------------

This elements is used to describe direct framework dependencies.

Attributes:

 * ``path``: Absolute path to the framework


``constant``
------------

This element is used to describe C-level variables that refer to constants (
such as "``NSString* NSWorkspaceCopyOperation``).

Attributes:

 * ``name``: Name of the constant

 * ``type``, ``type64``: Encoded type of the constant.

 * ``magic_cookie`` (BOOLEAN): if true this is a magic value, not a real object.
    

Note that the *value* of the constant is not described, this can be retrieved
from the actual framework using the ``CFBundle`` API.

``enum``
--------

This element is used to describe ``enum`` labels and ``#define``-s that map 
onto numbers.

Attributes:

  * ``name``: name of the constant

  * ``value``, ``value64``: the value of the constant. 
  
    If the value contains a dot (``"."``) the value is a floating-point
    number, otherwise it is an integer (of arbitrary size).

  * ``be_value``, ``le_value``: when a constant has a different value
    on big- and little-endian systems the ``value`` attribute won't be
    present and these two will be. 

    There will be very few values without a ``value`` attribute, basically
    only "four character codes".

``string_constant``
-------------------

This element is used to describe ``#define``-s that map onto string values 
(either C-style strings or literal NSString values).

Attributes:

  * ``name``: name of the contant

  * ``value``, ``value64``: the value of the constant
  
    The value is the value of the literal.

  * ``nsstring`` (BOOLEAN): if true the value is an NSString, otherwise it is a plain C string
    (defaults to ``false``).


``null_const``
--------------

This is used to describe null-pointer aliases.

Attributes:

  * ``name``: name of the value

The C value of these values is always ``NULL`` and these should be mapped
onto a "no-value" value by the brides (such as ``None`` in Python).

``cftype``
-----------

This element describes CoreFoundation based types.

Attributes:

 * ``name``: name of the type (such as ``CFArrayRef``).

 * ``type``, ``type64``: Encoding string for this type

 * ``tollfree``: if available this type is toll-free bridged to the named 
   Objective-C class

 * ``gettypeid_func``: if available this is the function that should be called
   to get the ``CFTypeID`` for this type. 

   This attribute must be present if ``tollfree`` isn't present and is optional
   otherwise.

``opaque``
-----------

Used to describe opaque types, that is 'pointer to struct' types where the
fields of the struct aren't public.

Attributes:

  * ``name``: name of the type (such as ``NSZone``)

  * ``type``, ``type64``: Encoding string for this type

``struct``
----------

Used to describe structs that are defined in the framework.

Attributes:

 * ``name``: name of the struct

 * ``type``, ``type64``: Encoding string for the this type. This is a verbose
   encoding that includes the field names, which isn't the same as the
   result of ``@encode(name)``.

``informal_protocol``
---------------------

This element describes informal protocols (but not formal ones, those can be
extracted from the Objective-C runtime).

Attributes:

  * ``name``: name of the informal protocol

This element has subelements that describe the methods that are part of the
protocol. All subelements have ``method`` as their tag.


``method``
...........

The ``method`` subelement of ``informal_protocol`` has the following attributes:

 * ``selector``: name of the method

 * ``classmethod`` (BOOLEAN): is this a class method? Defaults to ``false``.

 * ``encoding``, ``encoding64``: encoding of the method signature, as it would 
   exist in the Objective-C runtime

 * ``suggestion``: This method shouldn't be used. The attribute value contains
   a human-reable message.

 * ``variadic`` (BOOLEAN): If true this is a varargs method, defaults to 
   ``false``.


``class``
---------

This attribute is used to describe classes in the framework that contain methods were the metadata in the Objective-C runtime isn't good enough to wrap them.

Attributes:

 * ``name``: name of the class

This element has subelements of type ``method`` for all methods that require
further annotations. Furthermore subelements of type ``property`` are used
to describe Objective-C 2.0 properties that aren't present in the header files.

``method``
..........

This is used to describe metadata for methods, and only those bits of metadata
that cannot be derived from the information in the Objective-C runtime.

Attributes:

 * ``selector``: The method name

 * ``classmethod`` (BOOLEAN): Is this a class method? Defaults to ``false``

 * ``suggestion``: This method shouldn't be used. The attribute value contains
   a human-reable message.

 * ``variadic`` (BOOLEAN): If true this is a varargs function, defaults to false

 * ``c_array_delimited_by_null`` (BOOLEAN): Only valid when variadic is true,
    defaults to ``False``. The variadic arguments are a null-terminated array.

This element has subelements ``retval`` (present at most once) and ``argument``
(can be present multiple times) to describe the return value and arguments. See
the section `Method and function argument and return values`_ for more 
information on these elements.

When the ``suggestion`` attribute is present the bridge should emit a warning
containing the suggestion. It may not be possible to call the method at all.

``function``
------------

This is used to describe functions in the framework.

Attributes

 * ``name``: Function name

 * ``suggestion``: This method shouldn't be used. The attribute value contains
   a human-reable message.

 * ``variadic`` (BOOLEAN): If true this is a varargs function, defaults to false

 * ``c_array_delimited_by_null`` (BOOLEAN): Only valid when variadic is true,
    defaults to ``False``. The variadic arguments are a null-terminated array.
 
 * ``inline`` (BOOLEAN): If true the function is a static inline function
 
   NOTE: static inline functions cannot be loading from a bundle using the 
   CFBundle APIs because they aren't included as public functions. A bridge will
   have to implement some other mechanism to make this functions available.

This element has subelements ``retval`` (present at most once) and ``argument``
(can be present multiple times) to describe the return value and arguments. See
the section `Method and function argument and return values`_ for more 
information on these elements.

When the ``retval`` element is not present the function returns ``void``. 

All function arguments will be present in the right order and don't need an
``index`` attribute.

When the ``suggestion`` attribute is present the bridge should emit a warning
containing the suggestion. It may not be possible to call the function at all.



Method and function argument and return values
-----------------------------------------------

``retval``
...........

Attributes

 * ``already_retained`` (BOOLEAN): If true the function returns an object that
   is already retained, that is the user is responsible for releasing the 
   object when it is no longer needed. Only valid when the return type is an
   object (either a ``NSObject*`` or a ``CFTypeRef``). Defaults to ``false``.

 * ``type``, ``type64``: The return type. Only present when this is different
   from the information in the Objective-C runtime.

 * ``c_array_length_in_arg``: The return value is an array whose length is
   present in another argument. The value is the index of the argument
   that contains the array size. This argument must be an integer or NSRange
   value or an ``inout`` or ``out`` argument of type integer. If the value
   is a (pointer to a) value of type NSRange the ``length`` is used as the 
   array size.

   The value can also be two integers seperated by a comma, in which cases the
   first integer is the index of the argument that contains the length of the
   array on input and the second is index of the argument that contains the 
   size on output.

 * ``c_array_delimited_by_null`` (BOOLEAN): The return value is a 
   NULL-terminated array.  The basic type of the array must be a pointer-type 
   (object, opaque) or an integer type (in which case it is a 0-terminated 
   array). Defaults to ``false``.

 * ``c_array_of_fixed_length``: The return value is an array of a fixed size.
   The value of this attribute is said size.

 * ``c_array_of_variable_length`` (BOOLEAN): The return value is an array of 
   unspecified size.  Note that bridges cannot know or infer the size of 
   the array and have to raise an error when a method/function with this
   attribute is called. Defaults to ``false``.

 * ``unicode_string`` (BOOLEAN): the value is a unicode string instead of 
   an array of short integers.

   Needed because the encoded type for a unicode string and an array of short
   integers is the same. 
   
   Also used on for values of type ``UniChar` (that is: single unicode 
   characters).

   Defaults to false.

 * ``bool_is_BOOL`` (BOOLEAN): the type encoding says that the type is ``bool``,
   but it actually a ``BOOL``. Defaults to ``true`` (for backward compatiblity
   reasons).

   NOTE: this attribute is only present for functions, bridges can reconstruct
   this value from the objc runtime + metadata for plain methods.

``arg``
...........

Attributes

 * ``index``: Index of the argument. The first argument has index 0, and for
   selectors the two implict arguments are not counted. This attribute is 
   optional on function arguments, all function arguments are present in the
   right order.

 * ``type``, ``type64``: Encoded type of the argument. Only present when this
   is different from the type in the Objective-C runtime.

 * ``type_modifier``: One of ``_C_IN``, ``_C_OUT`` or ``_C_INOUT`` to describe
   if a pointer argument is an input, output or input/output argument. 
   
   This attribute is optional, but should be present on all pointer arguments
   as there is no default value.

 * ``c_array_length_in_arg``: The return value is an array whose length is
   present in another argument. The value is the index of the argument
   that contains the array size. This argument must be an integer value or
   an ``inout`` or ``out`` argument of type integer.

 * ``c_array_delimited_by_null``: The value is a NULL-terminated array.
   The basic type of the array must be a pointer-type (object, opaque) or
   an integer type (in which case it is a 0-terminated array). Defaults
   to ``false``.

 * ``c_array_of_fixed_length``: The value is an array of a fixed size.
   The value of this attribute is said size.

 * ``c_array_of_variable_length`` (BOOLEAN): The return value is an array of 
   unspecified size.  Defaults to ``false``.

   Bridges should assume that the length of the array passed in by the caller
   is the size of the array expected by the function/method. Note that this
   could cause crashes when the actually expected size is different.

 * ``c_array_length_in_result`` (BOOLEAN): The value is an array whose size is 
     is the return value. There MUST also be ``c_array_of_fixed_length`` or
    ``c_array_length_in_arg`` attribute that describes how large the buffer
    must be on input.  This attribute cannot be present on a ``rettype`` element
    and defaults to ``false``.

 * ``null_accepted`` (BOOLEAN): if true the pointer argument is allowed to
    be ``NULL``, otherwise it is not. Defaults to ``true``.

 * ``printf_format`` (BOOLEAN): if true this argument is a printf-style format.

   Only one of the arguments may have this property set to true, and only on
   a variadic function or method. Defaults to ``false``.

 * ``already_retained`` (BOOLEAN): If true the function returns an object that
   is already retained, that is the user is responsible for releasing the 
   object when it is no longer needed. Only valid when the return type is an
   object (either a ``NSObject*`` or a ``CFTypeRef``). Defaults to ``false``.

 * ``unicode_string`` (BOOLEAN): the value is a unicode string instead of 
   an array of short integers.

   Needed because the encoded type for a unicode string and an array of short
   integers is the same.

   Also used on for values of type ``UniChar` (that is: single unicode 
   characters).

   Defaults to false.

 * ``function_poiner`` (BOOLEAN): if true the argument is a callback function. 
   The signature of the callback is described by subelements of this element.

 * ``function_pointer_lifetime``: the livetime of a callback argument. 
   Defaults to ``undetermined``: Valid values are:

    * ``call``: The callback function is only used during the call to the
      function/method and won't be stored for later use.

    * ``undetermined``: The called function/method  may store a reference to 
      the callback function and may therefore call the function when the 
      call to this method/function has ended.

    Other lifetime values may be added in the future.

   NOTE: currently not supported by PyObjC.

 * ``sel_of_type``: if the type of the argument is ``SEL`` this attribute
   can contain the encoded signature for the selector. This can be used by
   bridges for additional type-checking.


Exceptions file
===============

The exceptions file has the same format as the metadata file, but with same
minor additions as described below.

1. All elements can have a BOOLEAN attribute ``ignore`` (defaulting to 
  ``false``). If the ``ignore`` attribute is false the element won't be 
   present in the actual metadata file

2. All elements can have an attribute ``comment`` that contains arbitrary
   text that is not further interpreted.

   This attribute is meant to be used as a place where metadata maintainers
   can leave documentation/notes when that's needed. Use this instead of 
   XML comments to ensure that tools keep the comment when rescanning a 
   framework.

3. Function arguments will have an ``index`` attribute and only the function
   arguments/return values that require manual markup will be present.

4. The ``type_modifier`` attribute may have an empty value, which means the
   metadata maintainer has looked at an argument/return-value node and 
   indicates that it doesn't need further markup (needed because the 
   both scanners are pessimistic by design as to what arguments require
   markup)
 
5. Structs may have  ``type`` and ``type64`` attributes in the exeption file
   (as the always have in the normal metadat file). If such fields are present
   those encodings are used instead of the output of ``@encode`` for this type
   and metadata will be generated for all methods that have a return or argument
   value of this type.
