\section{\module{functional} ---
         Higher order functions, and operations on callable objects.}

\declaremodule{standard}{functional}		% standard library, in Python

\moduleauthor{Peter Harris}{scav@blueyonder.co.uk}
\sectionauthor{Peter Harris}{scav@blueyonder.co.uk}

\modulesynopsis{Higher-order functions, operations on callable objects.}


The \module{functional} module is for higher-order functions: functions
that act on or return other functions. In general, any callable object can be
treated as a function for the purposes of this module.


The \module{functional} module defines the following functions:

\begin{funcdesc}{partial}{function\optional{,*args}\optional{, **kwargs}}
Return a function which when called will behave like \var{function} called
with the positional arguments \var{args} and keyword arguments \var{kwargs} provided.
If more arguments are supplied when the function is called, additional positional arguments are appended, and keyword arguments override those provided when the new function was created.
\end{funcdesc}


\begin{classdesc}{Partial}{object}
A callable class implementing the same behaviour as the function \function{partial}.
\end{classdesc}


\subsection{Example \label{partial-example}}

The following example demonstrates two uses of the \function{partial} function: shorthand for lengthy object constructors, and GUI callback functions.

\begin{verbatim}
import Tkinter
import sys
from functional import partial

my_window = Tkinter.Tk()
my_canvas = Tkinter.Canvas(my_window,width=200,height=50)
my_canvas.pack()

Btn = partial(Tkinter.Button,my_window)  # shorthand
for colour in sys.argv[1:]:
    callback = partial(my_canvas.config,bg=colour)  # function to set canvas colour
    b = Btn(text=colour, command=callback)
    b.pack(side='left')
my_window.mainloop()
\end{verbatim}

\subsection{Partial Objects}
\label{partial-objects}

Partial objects are callable objects that are created, and mostly behave, like the
functions created by \function{partial}. The main difference is that because they
are Python objects, they have attributes that can be inspected or modified.

\begin{memberdesc}[callable]{fn}{}
The callable object or function that will be called when the Partial object is called.
\end{memberdesc}
\begin{memberdesc}[tuple]{args}{}
The leftmost positional arguments that will be supplied when the Partial object is called.
\end{memberdesc}
\begin{memberdesc}[dict]{kw}{}
The keyword arguments that will be supplied when the Partial object is called.
\end{memberdesc}
\end{document}