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

.. _`module type`:

Modules
=======

Modules in a programmatic sense declare a hierarchy of namespaces
through which the visibility of names can be controlled.

Underlying that is a module type which is a collection of useful
properties.


.. _`module?`:

.. idio:function:: module? o


   Is `o` a module?				
   						
   :param o: value to test				
   :type o: any					
   :return: ``#t`` if `o` is a module, ``#f`` otherwise	


.. _`module`:

.. idio:template:: module name


   switch to the namespace `name`
   
   :param name: name of module
   :type name: symbol
   
   .. note::
   
      As this is a template, you cannot pass a variable.
   

.. _`%find-or-create-module`:

.. idio:function:: %find-or-create-module name


   Find the module called `name` or create one	
   						
   :param name: module name to look for		
   :type name: symbol				
   :return: module called `name`			
   :rtype: module					


.. _`module-name`:

.. idio:function:: module-name module


   Return the name of `module`			
   						
   :param module: module to query			
   :type module: module				
   :return: module name				
   :rtype: symbol					


.. _`module-symbols`:

.. idio:function:: module-symbols [module]


   return the symbols in `module`				
   							
   :param module: module to use, defaults to the current module	
   :type module: module or symbol, optional		
   :return: list of symbols				
   :rtype: list						


.. _`module-exports`:

.. idio:function:: module-exports mod


   Return the exported names of `mod`			
   						
   :param mod: module to query			
   :type mod: module or name			
   :return: exported names				
   :rtype: list					


.. _`module-imports`:

.. idio:function:: module-imports mod


   Return the modules imported by `mod`			
   						
   :param mod: module to query			
   :type mod: module or name			
   :return: imported modules			
   :rtype: list					


.. _`module-alias`:

.. idio:function:: module-alias name [identity]


   Create `name` as an alias for `identity` or the current module	
   if `identity` is not supplied.			
   						
   :param name: module alias' name			
   :type name: symbol				
   :param identity: target module			
   :type identity: module or symbol		
   :return: ``#<unspec>``				
   						
   .. warning::					
   						
      If the `identity` module's symbols, exports or imports	
      are unset when ``module-alias`` is called then changes	
      will not be seen.				
   						
      If you are aliasing yourself, use ``module-alias`` after	
      the :ref:`provide <provide>` expression.			
   						
   .. seealso:: :ref:`module-identity <module-identity>`	


.. _`module-identity`:

.. idio:function:: module-identity mod


   Return the identity of module `mod`		
   						
   :param mod: module				
   :type mod: module or symbol			
   :return: module's identity			
   :rtype: module or ``#n``			
   						
   If `mod` is an alias of another module then the identity	
   of `mod` is the module it is aliasing -- which could be		
   another alias.					
   						
   .. seealso:: :ref:`module-alias <module-alias>`	


.. _`export`:

.. idio:template:: export [names]


   Add `names` to the list of names export by the current module
   
   :param names: names to be exported
   :type name: symbol or a list of symbols
   
   .. note::
   
      As this is a template, you cannot pass a variable.
   

.. _`in-module`:

.. idio:template:: in-module name [body]


   Run `body` in module `name`.
   
   :param name: module name
   :type name: symbol
   :param body: expressions
   :type body: list
   

.. _`all-modules`:

.. idio:function:: all-modules


   Return a list of all modules			
   						
   :return: all modules				
   :rtype: list					


.. _`find-module`:

.. idio:function:: find-module name [default]


   Find the module called `name`					
   								
   :param name: module name to look for				
   :type name: symbol						
   :param default: return value if `name` is not found		
   :type default: any, optional					
   :return: module called `name` or `default` (or ``#<unspec>``)	
   :rtype: module							
   :raises ^rt-module-error:					




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