.. include:: ../../global.rst

.. _`keyword type`:

Keyword Type
============

Keywords are very similar to symbols but serve a slightly different
purpose.  Like symbols they are a word but must begin with a ``:``,
U+003A (COLON).

They exist as semantic flags -- rather than as symbols' programmatic
flags -- to be used to identify optional arguments to functions.
Think of a function with many possible optional arguments and if you
only want to set the ``foo`` optional parameter you might invoke:

.. parsed-literal::

   func *formals* :foo *arg*

There is a constraint on the possible keywords in that in order to
avoid clashing with the definition operators, ``:=`` etc., then the
characters of a keyword after the ``:`` must not start with a
punctuation character, (through :manpage:`ispunct(3)`).

So ``:foo=bar`` is fine but ``:=bar`` is not -- and will be
interpreted as a symbol.


Keyword Predicates
------------------


.. _`keyword?`:

.. idio:function:: keyword? o


   test if `o` is an keyword			
   						
   :param o: object to test			
   :return: ``#t`` if `o` is an keyword, ``#f`` otherwise	


Keyword Constructors
--------------------


.. _`make-keyword`:

.. idio:function:: make-keyword s


   create a keyword from `s`			
   						
   :param s: keyword				
   :type s: symbol or string			
   :return: keyword				
   :rtype: keyword					


Keyword Functions
-----------------


.. _`keywords`:

.. idio:function:: keywords


   return a list of all keywords			
   						
   :return: list					


.. _`keyword table type`:

Keyword Tables
--------------

Keyword tables are :ref:`hash tables <hash table type>` indexed by
keywords.

They are used primarily as :ref:`property tables <property tables>`.

.. _`make-keyword-table`:

.. idio:function:: make-keyword-table [size]


   used for constructing property tables		
   						
   :param size: size of underlying hash table	
   :type size: integer, optional			
   :return: keyword table				


.. _`keyword-ref`:

.. idio:function:: keyword-ref kt kw [default]


   return the value indexed by keyword `kw` in keyword	
   table `kt`						
   							
   :param kt: keyword table				
   :type kt: keyword table					
   :param kw: keyword index				
   :type kw: keyword					
   :param default: a default value to return if `kw` not found	
   :type default: value, optional				
   :return: value						
   :raises ^rt-keyword-error: if `key` is not		
   	found and no `default` is supplied		


.. _`keyword-set!`:

.. idio:function:: keyword-set! kt kw v


   set the index of `kw` in keyword table `kt` to `v`	
   							
   :param kt: keyword table				
   :type kt: keyword table					
   :param kw: keyword index				
   :type kw: keyword					
   :param v: value						
   :type v: a value					
   :return: ``#<unspec>``					




.. include:: ../../commit.rst