===========
Pure Domain
===========

:author: Albert Graef <Dr.Graef at t-online.de>

Based on the Erlang domain by SHIBUKAWA Yoshiki <yoshiki at shibu.jp>

About
=====

This is the Pure domain for Sphinx 1.0. This extension provides directives and
roles to write Pure documentation.

The Pure Domain currently supports the following types of Pure objects:

* modules
* functions (and externs)
* macros
* variables and constants

URLs
====

:PyPI: http://pypi.python.org/pypi/sphinxcontrib-puredomain
:Detail Document: http://packages.python.org/sphinxcontrib-puredomain

Install
=======

.. code-block:: bash

   $ easy_install -U sphinxcontrib-puredomain

Or run the following in this directory:

.. code-block:: bash

   $ python setup.py build
   $ sudo python setup.py install

Quick Sample
============

For convenience, you can set Sphinx's ``default-domain`` to ``pure``, so that
you can simply write ``function::`` for ``pure:function::``, ``:func:`` for
``:pure:func:``, etc.

.. default-role:: emphasis
.. default-domain:: pure
.. highlight:: none

This is a sample function description outside of any module.

.. function:: sort p xs

   Sorts the elements of the list `xs` in ascending order according to the
   given predicate `p`, using the C `qsort` function. The predicate `p` is
   invoked with two arguments and should return a truth value indicating
   whether the first argument is "less than" the second. An exception is
   raised if the result of a comparison is not a machine integer. Example::

     > sort (>) (1..10);
     [10,9,8,7,6,5,4,3,2,1]
     > sort (<) ans;
     [1,2,3,4,5,6,7,8,9,10]

   This function also works with matrices, see :func:`sort/matrix` below.

Another entry for the same function. This happens a lot in Pure, as functions
are frequently overloaded. The Pure domain handles these gently, if you
specify a unique tag of the form ``/id`` after the function name for each
overloaded instance. (The tag is invisible in the rendered output, it just
becomes part of the link target.) Also note that in contrast to the other
Sphinx domains, parameter lists are generally written in Pure's curried style
and may contain arbitrary extra annotations such as type tags.

.. function:: sort /matrix p x::matrix

   Sorts the elements of a matrix `x` (non-destructively, i.e., without
   changing the original matrix) according to the given predicate `p`, using
   the C `qsort` function. This works exactly the same as with lists (see
   :func:`sort` above), except that it takes and returns a matrix instead
   of a list.

Operator notation is supported as well. To these ends, simply add one of the
``prefix``, ``postfix``, ``infix`` and ``outfix`` keywords at the beginning of
the function signature.

.. function:: infix + x y

   Add two values. This works with numbers, strings and lists.

.. function:: prefix - x

   Unary minus. Negates a number. This operator is special in Pure, as it's
   the only infix operator which is also used as a prefix operator.

.. function:: postfix & x

   Creates a thunk which gets evaluated lazily. This is the only postfix
   operator defined in the prelude.

.. function:: outfix {: :} x

   An outfix operator.

Modules and Namespaces
----------------------

.. module:: gsl
   :synopsis: Pure GSL module
   :platform: Windows, Mac, Unix

The current module can be set with the :rst:dir:`pure:module` directive. You
can refer to a module with the :rst:role:`pure:mod` role, e.g.: :mod:`gsl`.

In addition, you can also set the current namespace with
:rst:dir:`pure:namespace`. The following functions are declared in the ``gsl``
namespace.

.. namespace:: gsl

.. function:: sort_vector m::matrix

   Implements `gsl_sort` and `gsl_sort_int` without `stride` and `n`
   parameters.

.. function:: sort_vector_index m::matrix

   Implements `gsl_sort_index` and `gsl_sort_int_index` without `stride`
   and `n` parameters.

More markup
-----------

.. currentmodule:: None
.. namespace:: None

The usual markup for embellished function descriptions is supported as well,
e.g.:

.. function:: foldl f a xs -> b

   Accumulate the binary function `f` over all members of `xs`, starting from
   the initial value `a` and working from the front of the list towards its
   end.
   
   :param f:  accumulating function
   :type  f:  closure
   :param a:  initial value
   :type  a:  any type
   :param xs: values to be accumulated
   :type  xs: list
   :return:   accumulated value `b`
   :rtype:    any (usually the same as `a`, but that depends on `f`)

There's also special markup for extern functions, macros, constructors,
variables and constants.

.. extern:: puts s::string

   Output a string on the terminal.

.. macro:: void (catmap f x) = do f x
   		void (listmap f x) = do f x

   Helper macro to execute a list comprehension which is evaluated solely for
   its side-effects. This turns the implicit `map` of the comprehension into a
   `do` and thereby optimizes away the intermediate list result.

.. constructor:: infix : x xs

   The list constructor. Note that ``[x1,x2,...,xn] === x1:x2:...:xn:[]``.

.. variable:: stdin

   The standard input stream. This is a built-in variable.

.. constant:: c = 299792

   A constant. The speed of light, what else?
