Support for ``FSRef`` and ``FSSpec``
====================================

PyObjC has its own wrappers for the types ``FSRef`` and ``FSSpec``, and also
supports the wrappers for these types in ``Carbon.File``.

.. class:: objc.FSRef

    This type represents an opaque ``FSRef`` structure.

    New instances are created using the ``from_pathname`` method:

    .. sourcecode:: python
    
        >>> ref = objc.FSRef.from_pathname("/Libray")
        >>> isinstance(ref, objc.FSRef)
        True
    
    Instances of ``objc.FSRef`` are opaque and don't provide access to 
    specific fields in the structure. The following methods and properties
    are available to access an instance:

    .. attribute:: data

        A bytestring containing the value of the ``FSRef`` object.

    .. method:: as_pathname

        Returns the POSIX path for the ``FSRef`` object.

    .. method:: as_carbon

        Returns a ``Carbon.File.FSRef`` instance for the ``FSRef`` object.

        NOTE: This method is only available when ``Carbon`` support is
        enabled in the Python build.

    .. note:: ``Carbon.File.FSRef`` instances can be used as the argument
       of functions that have an ``FSRef`` structure as one of their
       arguments.


    .. note::
       All API's using the FSRef type are deprecated by Apple as of Mac OS X 10.8,
       for most of those APIs there are alternate APIs that use URL objects
       (:c:type:`NSURL` or :c:type:`CFURL`).

.. class:: objc.FSSpec

    This type represents an opaque ``FSSpec`` structure. It is not possible
    to create ``FSSpec`` instances in Python code.

    Instances of ``objc.FSSpec`` are opaque and don't provide access to 
    specific fields in the structure. The following methods and properties
    are available to access an instance:

    .. attribute:: aref.data

        A bytestring containing the value of the ``FSRef`` object.

    .. method:: aref.as_carbon

        Returns a ``Carbon.File.FSRef`` instance for the ``FSRef`` object.

        NOTE: This method is only available when ``Carbon`` support is
        enabled in the Python build.
    
    .. note:: 

       ``Carbon.File.FSSpec`` instances can be used as the argument
       of functions that have an ``FSSpec`` structure as one of their
       arguments.

    .. note::

       "FSSpec" is a deprecated type in Apple's APIs. The type is not 
       availble for 64-bit code, and shouldn't be used for new development.
