%% $Date: 2003/10/21 22:39:51 $ $Author: nthiery $ $Revision: 1.1.1.2 $

\begin{Mhelppage}{bless}{N.~Thiéry}

\begin{MInfo}
  \eng{bless a function as belonging to a \mupad\ domain}
  \de{trage in eine bestehende Funktion eine neue Domain-Zugehörigkeit
  ein}
\end{MInfo} % end of MInfo

\begin{MIntro}
  \eng{\Margs{f, mydomain} blesses the function \Mpar{f} as belonging to
    the \mupad\ domain \Mpar{mydomain}}
  \de{\Mex{\Mthis(f, mydomain)} trägt in \Mex{f} die Zugehörigkeit zum
    Domain \Mex{mydomain} ein.}
\end{MIntro} % end of MIntro

\begin{MCalls}
  \call{f,  mydomain}
\end{MCalls} % end of MCalls

\begin{MParameters}
  \param{f}
    \eng{a \mupad\ function}
    \de{eine Funktion}
  \param{mydomain}
    \eng{a \mupad\ domain}
    \de{ein Domain}
\end{MParameters} % end of MParameters

\begin{MReturnValue}
  \eng{a copy of \Mpar{f}, as a member of the domain \Mpar{mydomain}}
  \de{eine Kopie von \Mex{f}, die zum Domain \Mex{mydomain} gehört}
\end{MReturnValue} % end of MReturnValue

\begin{MDetails}
  \eng{The call \Margs{f, mydomain} returns a copy of \Mpar{f} which
    as been blessed as a member of the domain \Mpar{mydomain}. That
    is, the value of \Mex{dom} inside of the copy of \Mpar{f} is set to
    \Mpar{mydomain} exactly as if \Mpar{f} had been assigned to the
    domain with \Mex{mydomain::dummy := f}.}%
  \de{Der Aufruf \Margs{f, mydomain} liefert eine Kopie von \Mex{f}
    zurück, die als Methode des Domains \Mex{mydomain} gekennzeichnet
    ist.  Das bedeutet, dass in dieser Kopie die spezielle Variable
    \Mex{dom} den Wert \Mex{mydomain} hat.}

  \eng{Ideally, there would never be a need for using this function.
    However, due to the specific behaviour of \Mex{dom} which does not have
    a standard lexical scope, there are some cases where it is helpful
    for the programmer to be able to set it explicitly. This kind of
    situation appears typically when generating code on the fly, or
    when having a table of functions in a domain.}
  \de{\Mthis\ existiert nur aus technischen Gründen, weil die
    Behandlung der speziellen Variable \Mex{dom} sehr kompliziert ist
    und in einigen Fällen nicht ganz das gewünschte Verhalten
    nachbildet, etwa bei zur Laufzeit generierten Prozeduren in einer
    Tabelle in einem Domain.}
\end{MDetails} % end of MDetails

\begin{MExample}{ex1}
  \eng{We create a domain, with a power function, and a function
    \Mex{curry} which returns a specialization of this function for a
    given \Mex{n}. Of course, this simple example is artificial, but
    this kind of situation appears naturally when generating code on
    the fly:}
  \de{Das folgende Domain hat eine Potenzfunktion und eine Funktion
    \Mex{curry}, die eine Spezialisierung dieser Funktion liefert.
    (Man stelle sich vor, hier würde ein spezieller, schnellerer
    Algorithmus implementiert.  Diese Sorte von Programmen in etwas
    komplizierterer Form ist in der Tat nicht unüblich:)}
  \begin{Mexin}
domain mydomain
    power := (n,x) -> x^n;
    curry :=
    proc(n)
        option escape;
    begin
        x -> dom::power(n,x)
    end_proc;
end_domain:
power2 := mydomain::curry(2):
power2(3)
  \end{Mexin}
  \begin{Mexout}
                               9
  \end{Mexout}
%%  \eng{This does not work with \mupad{} versions 2.5.3 and earlier,
%%    because \Mex{dom} is not set properly inside \Mex{power2}. We work
%%    around this by explicitly setting it with bless:}
%%  \begin{Mexin}
%%domain mydomain2
%%    power := (n,x) -> x^n;
%%    curry :=
%%    proc(n)
%%        option escape;
%%    begin
%%        prog::bless(x -> dom::power(n,x), dom)
%%    end_proc;
%%end_domain:
%%power2 := mydomain2::curry(2):
%%power2(3);
%%  \end{Mexin}
%%  \begin{Mexout}
%%                               9
%%  \end{Mexout}
%%  \eng{Here is another typical application, which is still relevant
%%    with \mupad{} 3.0.0. One wants to store a bunch of related domain
%%    functions inside a table:}
  \eng{While this code works as written with \mupad\ 3.0 (it does not
    work with 2.5.3 and earlier, which had slightly different rules
    for ``inheriting'' \Mex{dom}), the following code requires \Mthis,
    since \Mex{dom} is not set automatically for the functions inside
    the table:}
  \de{Dieser Code funktioniert mit \mupad\ 3.0.  (Mit \mupad\ 2.5.3
    und früheren Versionen läuft er nicht, weil die Regeln für die
    "`Vererbung"' von \Mex{dom} diese Verwendung noch nicht zuließen.)
    In der folgenden Situation aber erhalten die Funktionen innerhalb
    der Tabelle nicht automatisch den gewünschten Wert von \Mex{dom},
    so dass \Mthis\ nötig ist:}
  \begin{Mexin}
domain mydomain3
    new :=
    proc(x)
    begin
        if contains(dom::newFunctions, domtype(x)) then
           dom::newFunctions[domtype(x)](x);
        else
           error("Don't know how to convert x");
        end_if;
    end_proc;

    newFunctions :=
    map(table(
              DOM_INT  = (n -> new(dom, [$1..n])),
              DOM_LIST = (l -> new(dom, l))
             ),
        prog::bless, dom);
end_domain:
mydomain3(3);
mydomain3([1,2,3])
  \end{Mexin} %$
  \begin{Mexout}
                   new(mydomain3, [1, 2, 3])

                   new(mydomain3, [1, 2, 3])
  \end{Mexout}
\end{MExample} % end of MExample

\begin{MChanges}
  \version{3.0}
  \new
\end{MChanges}

\end{Mhelppage}
%% end of helppage 'bless'
