.. include:: ../global.rst

.. idio:currentmodule:: object

IOS Defined Classes
-------------------

IOS defines a number of classes, several of which are used internally
to define the meta-object protocol (MOP).

MOP Classes
^^^^^^^^^^^

The MOP classes are used to define the implementation of the
(user-level) use of classes and are (necessarily) circular in
definition.

Most classes have a MOP class of ``<class>`` -- including ``<class>``
itself.

MOP classes are distinct from the normal super-class element in a
class definition.  MOP classes do have super-classes as seen in this
table:

.. csv-table::
   :header: class, super-class, description
   :align: left
   :widths: auto

   ``<top>``, (none), the root
   ``<object>``, ``<top>``, the ancestor of all objects
   ``<procedure-class>``, ``<class>``, the ancestor of all invokable classes
   ``<entity-class>``, ``<procedure-class>``, the MOP class of generics
   ``<generic>``, ``<object>``,
   ``<method>``, ``<object>``,

Builtin Classes
^^^^^^^^^^^^^^^

The regular :lname:`Idio` types are represented by classes with a
super-class ``<builtin-class>`` (itself with a super-class of
``<top>``).

The builtin classes include:

``<C/char>`` ``<C/double>`` ``<C/float>`` ``<C/int>`` ``<C/long>``
``<C/longdouble>`` ``<C/longlong>`` ``<C/pointer>`` ``<C/schar>``
``<C/short>`` ``<C/uchar>`` ``<C/uint>`` ``<C/ulong>``
``<C/ulonglong>`` ``<C/ushort>`` ``<array>`` ``<bignum>`` ``<bitset>``
``<constant>`` ``<continuation>`` ``<fixnum>`` ``<handle>`` ``<hash>``
``<keyword>`` ``<module>`` ``<pair>`` ``<string>``
``<struct-instance>`` ``<struct-type>`` ``<symbol>`` ``<unicode>``


``<closure>`` and ``<primitive>`` are invokable classes.

.. idio:currentmodule:: object

Class Predicates
----------------

.. _`object/class?`:

.. idio:function:: object/class? o


   test if `o` is a class				
   						
   :param o: object to test			
   :return: ``#t`` if `o` is a class, ``#f`` otherwise	


.. _`object/generic?`:

.. idio:function:: object/generic? o


   test if `o` is a generic			
   						
   :param o: object to test			
   :return: ``#t`` if `o` is a generic, ``#f`` otherwise	


.. _`object/method?`:

.. idio:function:: object/method? o


   test if `o` is a method				
   						
   :param o: object to test			
   :return: ``#t`` if `o` is a method, ``#f`` otherwise	


.. _`object/instance?`:

.. idio:function:: object/instance? o


   test if `o` is a instance			
   						
   :param o: object to test			
   :return: ``#t`` if `o` is a instance, ``#f`` otherwise	


.. idio:currentmodule:: object

Class Constructors
------------------

.. _`object/define-class`:

.. idio:function:: object/define-class name [supers [slots]]


   define-template: (define-class name & args) (x e)

   define a new class, `name`, with optional super-classes and slots
   
   :param name: name of the class
   :type name: symbol
   :param supers: super-classes of the new class, defaults to ``#n``
   :type supers: list of symbols, a symbol or ``#n``, optional
   :param slots: slots of the new class, defaults to ``#n``
   :type slots: see below, optional
   :return: class
   :rtype: instance
   
   Additionally, the symbol `name` will be bound to the new class.
   
   `slots` can each be a simple symbol, the slot's name, or a list of a
   symbol, the slot's name, and some slot options.
   
   If a slot is declared as:
   
   * a simple symbol then it has no slot options
   
   * a list then, in addition to any slot options given, a slot option of
     ``:initarg`` with a keyword value of :samp:`:{slot-name}` is added
     if no ``:initarg`` is otherwise given
   
   Slot options include:
   
   * :samp:`:initarg {keyword}`
   
     Subsequently, :samp:`{keyword} {arg}` can be passed to
     :ref:`make-instance <object/make-instance>` to set the slot's value
     to :samp:`{arg}`
   
   * :samp:`:initform {func}`
   
     Here, if no ``:initarg`` overrides then :samp:`{func}` is applied to
     the `initargs` passed to :ref:`make-instance <object/make-instance>`
     to get the default slot value instead of a "default slot value"
     function which returns ``#f``.
   
     :samp:`{func}` should expect to be passed any number of arguments.
   
   :Example:
   
   .. code-block:: idio-console
   
      Idio> define-class A
      #<CLASS A>
      Idio> define-class B A
      #<CLASS B>
      Idio> define-class C (B)
      #<CLASS C>
      Idio> define-class D #n a b c
      #<CLASS D>
   

.. _`object/make-class`:

.. idio:function:: object/make-class name supers slots


   
   
   create a new class, `name`, with super-classes and slots
   
   :param name: name of the class
   :type name: symbol
   :param supers: super-classes of the new class
   :type supers: list of class instances
   :param slots: slots of the new class
   :type slots: list of symbols
   :return: new class
   :rtype: instance
   
   ``make-class`` would not normally be called by users.
   
   .. seealso:: :ref:`define-class <object/define-class>`
   


.. _`object/define-generic`:

.. idio:function:: object/define-generic name [doc]


   define-template: (define-generic name & args) (x e)

   define a new generic function, `name`, with optional documentation
   
   :param name: name of the generic function
   :type name: symbol
   :param doc: documentation string, defaults to ``#n``
   :type doc: string or ``#n``, optional
   :return: generic function
   :rtype: instance
   
   Additionally, the symbol `name` will be bound to the new generic function.
   
   ``define-generic`` would not normally be called by users as generic
   functions are implicitly created through the use of
   :ref:`define-method <object/define-method>`.
   
   .. seealso:: :ref:`define-method <object/define-method>`
   

.. _`object/define-method`:

.. idio:function:: object/define-method name [specialized-formals] [docstr] body ...


   define-template: (define-method args & body) (x e)

   define a new method for the generic function, `name`.  The generic
   function `name` will be created if it does not already exist.
   
   The `specialized-formals` take the form :samp:`[{specialized-formal}
   ...]` and :samp:`{specialized-formal}` can take either the form
   :samp:`({name} {class})` or the form :samp:`{name}` which implies a
   class of ``<object>``.
   
   If a documentation string is supplied then it will be used for the
   documentation for the generic function `name` unless `name` already
   exists.
   
   :Example:
   
   These two declarations are equivalent:
   
   .. code-block:: idio
   
      define-method (foo/1  arg) ...
   
      define-method (foo/1 (arg <object>)) ...
   
   Similarly for multiple arguments:
   
   .. code-block:: idio
   
      define-method (foo/2  arg1            arg2) ...
   
      define-method (foo/2 (arg1 <object>)  arg2) ...
   
      define-method (foo/2 (arg1 <object>) (arg2 <object>)) ...
   
      define-method (foo/2  arg1           (arg2 <object>)) ...
   

.. _`object/make-instance`:

.. idio:function:: object/make-instance cl [initargs]


   
   
   create an instance of class `cl` using `initargs`
   
   :param cl: class
   :type cl: instance
   :param initargs: initialization arguments
   :type initargs: list
   :return: instance
   :rtype: instance
   
   `initargs` should be a series of :samp:`{keyword} {arg}` pairs where
   the keyword and argument are dependent on the class of `cl`.
   


.. idio:currentmodule:: object

Class Accessors
---------------

.. _`object/class-name`:

.. idio:function:: object/class-name cl


   return the name of class `cl`		
   					
   :param cl: class			
   :type cl: instance			
   :return: name of class `cl`		


.. _`object/class-direct-supers`:

.. idio:function:: object/class-direct-supers cl


   return the direct-supers of class `cl`	
   					
   :param cl: class			
   :type cl: instance			
   :return: direct supers of class `cl`	


.. _`object/class-direct-slots`:

.. idio:function:: object/class-direct-slots cl


   return the direct-slots of class `cl`	
   					
   :param cl: class			
   :type cl: instance			
   :return: direct slots of class `cl`	


.. _`object/class-cpl`:

.. idio:function:: object/class-cpl cl


   return the cpl of class `cl`		
   					
   :param cl: class			
   :type cl: instance			
   :return: cpl of class `cl`		


.. _`object/class-slots`:

.. idio:function:: object/class-slots cl


   return the slots of class `cl`		
   					
   :param cl: class			
   :type cl: instance			
   :return: slots of class `cl`		


.. _`object/class-nfields`:

.. idio:function:: object/class-nfields cl


   return the nfields of class `cl`	
   					
   :param cl: class			
   :type cl: instance			
   :return: nfields of class `cl`		


.. _`object/class-getters-n-setters`:

.. idio:function:: object/class-getters-n-setters cl


   return the getters-n-setters of class `cl`	
   						
   :param cl: class				
   :type cl: instance				
   :return: getters-n-setters of class `cl`	


.. _`object/class-of`:

.. idio:function:: object/class-of o


   return the class of `o`				
   						
   :param o: object to query			
   :return: class of `o`				


.. idio:currentmodule:: object

Generic Accessors
-----------------

.. _`object/generic-name`:

.. idio:function:: object/generic-name gf


   return the name of generic function `gf`	
   						
   :param gf: generic function			
   :type gf: instance				
   :return: name of generic function `gf`		


.. _`object/generic-documentation`:

.. idio:function:: object/generic-documentation gf


   return the documentation of generic function `gf`	
   						
   :param gf: generic function			
   :type gf: instance				
   :return: documentation of generic function `gf`	


.. _`object/generic-methods`:

.. idio:function:: object/generic-methods gf


   return the methods of generic function `gf`	
   						
   :param gf: generic function			
   :type gf: instance				
   :return: methods of generic function `gf`	


.. idio:currentmodule:: object

Method Accessors
----------------

.. _`object/method-generic-function`:

.. idio:function:: object/method-generic-function m


   return the generic function of method function `m`	
   						
   :param m: method function			
   :type m: instance				
   :return: generic function of method function `m`	


.. _`object/method-procedure`:

.. idio:function:: object/method-procedure m


   return the procedure of method function `m`	
   						
   :param m: method function			
   :type m: instance				
   :return: procedure of method function `m`	


.. _`object/method-specializers`:

.. idio:function:: object/method-specializers m


   return the specializers of method function `m`	
   						
   :param m: method function			
   :type m: instance				
   :return: specializers of method function `m`	


.. _`object/%set-instance-proc!`:

.. idio:function:: object/%set-instance-proc! gf proc


   set the instance procedure of `gf` to `proc`	
   						
   :param gf: generic function to modify		
   :type gf: generic				
   :param proc: function to use			
   :type proc: function				
   :return: ``#<unspec>``				




.. include:: ../commit.rst