sipref.txt

这是关于RFC3261实现sip的源代码

    *character-value* ::= ````` *character* `````

    *unary-operator* ::= [``!`` | ``~`` | ``-`` | ``+``]

    *binary-operator* ::= [``-`` | ``+`` | ``*`` | ``/`` | ``&`` | ``|``]

    *argument-annotations* ::= see `Argument Annotations`_

    *class-annotations* ::= see `Class Annotations`_

    *enum-annotations* ::= see `Enum Annotations`_

    *function-annotations* ::= see `Function Annotations`_

    *variable-annotations* ::= see `Variable Annotations`_

    *type* ::= [``const``] *base-type* {``*``} [``&``]

    *type-list* ::= *type* [``,`` *type-list*]

    *base-type* ::= [*scoped-name* | *template* | ``struct`` *scoped-name* |
            ``short`` | ``unsigned short`` | ``int`` | ``unsigned`` |
            ``unsigned int`` | ``long`` | ``unsigned long`` | ``float`` |
            ``double`` | ``bool`` | ``char`` | ``signed char`` |
            ``unsigned char`` | ``void`` | SIP_PYCALLABLE_ | SIP_PYDICT_ |
            SIP_PYLIST_ | SIP_PYOBJECT_ | SIP_PYSLICE_ | SIP_PYTUPLE_ |
            SIP_PYTYPE_]

    *scoped-name* ::= *name* [``::`` *scoped-name*]

    *template* ::= *scoped-name* ``<`` *type-list* ``>``

    *name* ::= _A-Za-z {_A-Za-z0-9}

Here is a short list of differences between C++ and the subset supported by
SIP that might trip you up.

    - SIP does not support the use of ``[]`` in types.  Use pointers instead.

    - A global ``operator`` can only be defined if its first argument is a
      class or a named enum that has been wrapped in the same module.

    - Variables declared outside of a class are effectively read-only.

    - A class's list of super-classes doesn't not include any access specifier
      (e.g. ``public``).


Variable Numbers of Arguments
-----------------------------

SIP supports the use of ``...`` as the last part of a function signature.  Any
remaining arguments are collected as a Python tuple.


Additional SIP Types
--------------------

SIP supports a number of additional data types that can be used in Python
signatures.


SIP_ANYSLOT
***********

This is both a ``const char *`` and a ``PyObject *`` that is used as the type
of the member instead of ``const char *`` in functions that implement the
connection or disconnection of an explicitly generated signal to a slot.
Handwritten code must be provided to interpret the conversion correctly.


SIP_PYCALLABLE
**************

This is a ``PyObject *`` that is a Python callable object.


SIP_PYDICT
**********

This is a ``PyObject *`` that is a Python dictionary object.


SIP_PYLIST
**********

This is a ``PyObject *`` that is a Python list object.


SIP_PYOBJECT
************

This is a ``PyObject *`` of any Python type.


SIP_PYSLICE
***********

This is a ``PyObject *`` that is a Python slice object.


SIP_PYTUPLE
***********

This is a ``PyObject *`` that is a Python tuple object.


SIP_PYTYPE
**********

This is a ``PyObject *`` that is a Python type object.


SIP_QOBJECT
***********

This is a ``QObject *`` that is a C++ instance of a class derived from Qt's
``QObject`` class.


SIP_RXOBJ_CON
*************

This is a ``QObject *`` that is a C++ instance of a class derived from Qt's
``QObject`` class.  It is used as the type of the receiver instead of ``const
QObject *`` in functions that implement a connection to a slot.


SIP_RXOBJ_DIS
*************

This is a ``QObject *`` that is a C++ instance of a class derived from Qt's
``QObject`` class.  It is used as the type of the receiver instead of ``const
QObject *`` in functions that implement a disconnection from a slot.


SIP_SIGNAL
**********

This is a ``const char *`` that is used as the type of the signal instead of
``const char *`` in functions that implement the connection or disconnection
of an explicitly generated signal to a slot.


SIP_SLOT
********

This is a ``const char *`` that is used as the type of the member instead of
``const char *`` in functions that implement the connection or disconnection
of an explicitly generated signal to a slot.


SIP_SLOT_CON
************

This is a ``const char *`` that is used as the type of the member instead of
``const char *`` in functions that implement the connection of an internally
generated signal to a slot.  The type includes a comma separated list of types
that is the C++ signature of of the signal.

To take an example, ``QAccel::connectItem()`` connects an internally generated
signal to a slot.  The signal is emitted when the keyboard accelerator is
activated and it has a single integer argument that is the ID of the
accelerator.  The C++ signature is::

    bool connectItem(int id, const QObject *receiver, const char *member);

The corresponding SIP specification is::

    bool connectItem(int, SIP_RXOBJ_CON, SIP_SLOT_CON(int));


SIP_SLOT_DIS
************

This is a ``const char *`` that is used as the type of the member instead of
``const char *`` in functions that implement the disconnection of an
internally generated signal to a slot.  The type includes a comma separated
list of types that is the C++ signature of of the signal.


SIP Directives
==============

In this section we describe each of the directives that can be used in
specification files.  All directives begin with ``%`` as the first
non-whitespace character in a line.

Some directives have arguments or contain blocks of code or documentation.  In
the following descriptions these are shown in *italics*.  Optional arguments
are enclosed in [*brackets*].

Some directives are used to specify handwritten code.  Handwritten code must
not define names that start with the prefix ``sip``.


%AccessCode
-----------

.. parsed-literal::

    %AccessCode
        *code*
    %End

This directive is used immediately after the declaration of an instance of a
wrapped class or structure, or a pointer to such an instance.  You use it to
provide handwritten code that overrides the default behaviour.

For example::

    class Klass;

    Klass *klassInstance;
    %AccessCode
        // In this contrived example the C++ library we are wrapping defines
        // klassInstance as Klass ** (which SIP doesn't support) so we
        // explicitly dereference it.
        if (klassInstance && *klassInstance)
            return *klassInstance;

        // This will get converted to None.
        return 0;
    %End


%BIGetCharBufferCode
--------------------

.. parsed-literal::

    %BIGetCharBufferCode
        *code*
    %End

This directive (along with `%BIGetReadBufferCode`_, `%BIGetSegCountCode`_ and
`%BIGetWriteBufferCode`_) is used to specify code that implements Python's
buffer interface.  See the section `Buffer Object Structures
<http://www.python.org/dev/doc/devel/api/buffer-structs.html>`__ for the
details.

The following variables are made available to the handwritten code:

*type* \*sipCpp
    This is a pointer to the structure or class instance.  Its *type* is a
    pointer to the structure or class.

void \*\*sipPtrPtr
    This is the pointer used to return the address of the character buffer.

int sipRes
    The handwritten code should set this to the length of the character buffer
    or -1 if there was an error.

int sipSegment
    This is the number of the segment of the character buffer.

PyObject \*sipSelf
    This is the Python object that wraps the the structure or class instance,
    i.e. ``self``.


%BIGetReadBufferCode
--------------------

.. parsed-literal::

    %BIGetReadBufferCode
        *code*
    %End

This directive (along with `%BIGetCharBufferCode`_, `%BIGetSegCountCode`_ and
`%BIGetWriteBufferCode`_) is used to specify code that implements Python's
buffer interface.

The following variables are made available to the handwritten code:

*type* \*sipCpp
    This is a pointer to the structure or class instance.  Its *type* is a
    pointer to the structure or class.

void \*\*sipPtrPtr
    This is the pointer used to return the address of the read buffer.

int sipRes
    The handwritten code should set this to the length of the read buffer or
    -1 if there was an error.

int sipSegment
    This is the number of the segment of the read buffer.

PyObject \*sipSelf
    This is the Python object that wraps the the structure or class instance,
    i.e. ``self``.


%BIGetSegCountCode
------------------

.. parsed-literal::

    %BIGetSegCountCode
        *code*
    %End

This directive (along with `%BIGetCharBufferCode`_, `%BIGetReadBufferCode`_ and
`%BIGetWriteBufferCode`_) is used to specify code that implements Python's
buffer interface.

The following variables are made available to the handwritten code:

*type* \*sipCpp
    This is a pointer to the structure or class instance.  Its *type* is a
    pointer to the structure or class.

int \*sipLenPtr
    This is the pointer used to return the total length in bytes of all
    segments of the buffer.

int sipRes
    The handwritten code should set this to the number of segments that make
    up the buffer.

PyObject \*sipSelf
    This is the Python object that wraps the the structure or class instance,
    i.e. ``self``.


%BIGetWriteBufferCode
---------------------

.. parsed-literal::

    %BIGetWriteBufferCode
        *code*
    %End

This directive (along with `%BIGetCharBufferCode`_, `%BIGetReadBufferCode`_
and `%BIGetSegCountCode`_ is used to specify code that implements Python's
buffer interface.

The following variables are made available to the handwritten code:

*type* \*sipCpp
    This is a pointer to the structure or class instance.  Its *type* is a
    pointer to the structure or class.

void \*\*sipPtrPtr
    This is the pointer used to return the address of the write buffer.

int sipRes
    The handwritten code should set this to the length of the write buffer or
    -1 if there was an error.

int sipSegment
    This is the number of the segment of the write buffer.

PyObject \*sipSelf
    This is the Python object that wraps the the structure or class instance,
    i.e. ``self``.