<commit_before>% $Revision$
% $Header: E:/iwcvs/fc/doc/chapternative.tex,v 1.8 2010/11/06 22:32:25 ingo Exp $
% $Log: chapternative.tex,v $
% Revision 1.8  2010/11/06 22:32:25  ingo
% - described file dlabel things
%
% Revision 1.7  2010/11/02 14:30:07  ingo
% - twocolumn format
%
% Revision 1.6  2009/04/30 13:31:24  iw
% - continued documentation
%
% Revision 1.5  2009/04/22 21:27:24  iw
% - more text
%
% Revision 1.4  2009/03/19 22:02:23  iw
% - continue text
%
% Revision 1.3  2008/05/16 16:03:20  iw
% - continued the native chapter
%
% Revision 1.2  2008/05/14 22:03:11  iw
% - almost finished declaration chapter
%
% Revision 1.1  2007/10/01 16:16:58  iw
% - new chapters
%
%
%
%

\chapter{Native Interface} \label{native interface}

In this chapter, we describe how \hyperref[nativedat]{native data types} and \hyperref[nativefun]{native functions} work, establish some conventions for the work with mutable data types
and give a receipt for creating correct native function declarations.

\section{Purpose of the Native Interface}

The language constructs introduced so far make it possible to write \emph{pure} functional programs. Pure functional programs consist of pure functions that work on immutable data. For the purpose of this discussion, we define these terms as follows: 

\begin{description}
\item[pure function] A function $f$ is pure, if the following holds:
\begin{itemize}
\item $f$ computes the same result when given the same argument values during execution of the program that contains $f$.
\item The result must not depend on anything but the values of the arguments. Specifically, it may not depend on mutable state, on time or the current state of the input/output system.
\item Evaluation of $f$ must not cause any observable side effect or change in the state of the real world (such as magnetic properties of particles on the surface of a rotating disc).
\end{itemize}
This definition is not as rigid as others that can be found in the literature or in the Internet. For example, we may regard a function \exq{\term{getenv} \sym{::} \term{String} $\rightarrow$ \term{String}} as pure, even if it depends on some hidden data structure that maps string values to other string values (the environment), provided that it is guaranteed that this mapping remains constant during program execution. 

Regarding side effects, we exclude only effects in the real world (input/output, but not physical effects in the CPU or memory chips) and effects that are observable \emph{by the program that caused it}. For example, evaluation of the expression
\exq{ s1 ++ s2 }
where \term{s1} and \term{s2} are string values, will cause creation of a new \java{} \term{String} object and mutation of some memory where the new string's data is stored, this could even trigger a garbage collector run with mutation of huge portions of the program's memory. Yet, all this happens behind the scene and is observable only by \emph{another} program such as a debugger or run time monitor, if at all.

We also do not insist that a pure function must return the same value in different executions of the program. 

\item[immutable values] A value is immutable if there are no means to observably change it or any values it contains.

This is deliberately vague in view of the difficulties that \java{} has 

%\paragraph*{Rationale for this Less Rigid Point of View} 
%If we did insist on that, we could not use any functionality provided by the underlying platform, which is in our case \java{} and the \java{} Virtual Machine. For we could not guarantee that certain constants or pure methods we use will be unchanged in the next update or version of that component. 
%
%Alternatively, one could of course define the term \emph{program} in such a way that it encloses a specific version of the \java{} runtime system (and in turn specific versions of the libraries used by \java{}, and the libraries used by those libraries down to the operating system and even the hardware). But then, the term \emph{program} would become almost meaningless
%\footnote{Suppose, for example, that some chip producer finds a bug in one of the floating point units that he produces, which causes incorrect results to be returned by certain floating point divisions. Suppose further, that the faulty CPU chip is replaced by a fixed one in the computer used by an extremely rigid functional purist, who insists that functions must produce the same value across different program executions. Then, this person must either admit that some function he wrote was not pure (because it suddenly produces different results for the same argument values) or he must regard his program as having changed. He could, for instance, talk about how much more exact results "\emph{this new version of my program}"  produces, despite nobody hasn't changed a single bit on the hard disk!
%
%This argumentation is not invalidated by pointing out that the faulty CPU did not behave according to their specification. It remains the fact that results of computer functions depend on the computing environment they are executed in, no matter if one likes it or not.
%}.
%
%It is probably more rational to acknowledge that the idea of a function that \emph{depends on nothing but its arguments} is an utterly idealistic one that must necessarily abstract away many aspects of reality. In practice, the result of a function $\backslash x \rightarrow x/3145727.0$, when defined in some computer language and executed in some computing environment depends not only on $x$, but also on how the floating point unit works, how exact the divisor can be represented in floating point, in short, it depends on the computing environment where it is run. 
%
%We do not understand the concept of functional purity so narrowly that we require the same result of a pure function in all thinkable computing environments. Rather, we admit realistically that results may be different in different computing environments. The session environment\footnote{The mapping of values printed by the command \term{env} in a \textsc{Unix} session; similar features exist in other operating systems.} is a part of the computing environment that is constant during program execution (in \java{} programs, that is). Hence, the result of a pure function in a program may depend on environment variables, according to our definition. It may depend on the arguments passed on the command line. Yet, it may not depend on the current directory, for obtaining the name of it presupposes input/output to be performed. It may also not depend on \java{}s system properties, for those can be changed during program execution.
\end{description}

\section{Terminology and Definitions}

Let's recall the general forms of native data and function declarations:
\begin{quote}
\begin{flushleft}
\textbf{data} $T$ $s$ = \textbf{native} $J$\\
\textbf{native} $v$ $j$ :: $t$
\end{flushleft}
\end{quote}

We call $T$ a \emph{native type} and $J$ the \emph{java type} associated with it. If $T$ is associated with one of \texttt{byte}, \texttt{boolean}, \texttt{char}, \texttt{short}, \texttt{int}, \texttt{long}, \texttt{float} or \texttt{double}, then $T$ is a \emph{primitive type}, otherwise it is a  \emph{reference type}.

We call $v$ a \emph{native value} and $j$ the \emph{java item} associated with it. If $t$ is of the form $t_1 \rightarrow{} \cdots{} \rightarrow{} t_k \rightarrow{}t_R$, where $t_R$ is not itself a function type, we call $v$ a \emph{native function} with \emph{arity} $k$ $(k\ge 1)$ and \emph{return type} $t_R$. The $t_i$ are called \emph{argument types}. For $v$'s that are not native functions, the arity is 0 and the return type is $t$.

$J$ and $j$ are snippets of \java{} code and can be specified as identifiers, qualified identifiers or operator symbols as long as this does not violate the \frege{} lexical syntax. In all other cases the code snippets can be given in the form of string literals. In the following sections, we will frequently use the value of $j$ or just $j$. This is to be understood as the string that is described by the string literal, not the string literal itself.<commit_msg>just check if commit works from laptop<commit_after>% $Revision$
% $Header: E:/iwcvs/fc/doc/chapternative.tex,v 1.8 2010/11/06 22:32:25 ingo Exp $
% $Log: chapternative.tex,v $
% Revision 1.8  2010/11/06 22:32:25  ingo
% - described file dlabel things
%
% Revision 1.7  2010/11/02 14:30:07  ingo
% - twocolumn format
%
% Revision 1.6  2009/04/30 13:31:24  iw
% - continued documentation
%
% Revision 1.5  2009/04/22 21:27:24  iw
% - more text
%
% Revision 1.4  2009/03/19 22:02:23  iw
% - continue text
%
% Revision 1.3  2008/05/16 16:03:20  iw
% - continued the native chapter
%
% Revision 1.2  2008/05/14 22:03:11  iw
% - almost finished declaration chapter
%
% Revision 1.1  2007/10/01 16:16:58  iw
% - new chapters
%
%
%
%

\chapter{Native Interface} \label{native interface}

In this chapter, we describe how \hyperref[nativedat]{native data types} and \hyperref[nativefun]{native functions} work, establish some conventions for the work with mutable data types
and give a receipt for creating correct native function declarations.

\section{Purpose of the Native Interface}

The language constructs introduced so far make it possible to write \emph{pure} functional programs. Pure functional programs consist of pure functions that work on immutable data. For the purpose of this discussion, we define these terms as follows: 

\begin{description}
\item[pure function] A function $f$ is pure, if the following holds:
\begin{itemize}
\item $f$ computes the same result when given the same argument values during execution of the program that contains $f$.
\item The result must not depend on anything but the values of the arguments. Specifically, it may not depend on mutable state, on time or the current state of the input/output system.
\item Evaluation of $f$ must not cause any observable side effect or change in the state of the real world (such as magnetic properties of particles on the surface of a rotating disc).
\end{itemize}
This definition is not as rigid as others that can be found in the literature or in the Internet. For example, we may regard a function \exq{\term{getenv} \sym{::} \term{String} $\rightarrow$ \term{String}} as pure, even if it depends on some hidden data structure that maps string values to other string values (the environment), provided that it is guaranteed that this mapping remains constant during program execution. 

Regarding side effects, we exclude only effects in the real world (input/output, but not physical effects in the CPU or memory chips) and effects that are observable \emph{by the program that caused it}. For example, evaluation of the expression
\exq{ s1 ++ s2 }
where \term{s1} and \term{s2} are string values, will cause creation of a new \java{} \term{String} object and mutation of some memory where the new string's data is stored, this could even trigger a garbage collector run with mutation of huge portions of the program's memory. Yet, all this happens behind the scene and is observable only by \emph{another} program such as a debugger or run time monitor, if at all.

We also do not insist that a pure function must return the same value in different executions of the program. 

\item[immutable values] A value is immutable if there are no means to \emph{observably} change it or any values it contains.

This is deliberately vague in view of the difficulties in \java{} when it comes to enforcing immutability. \footnote{It is, for example.possible to break intended immutability with the help of  the reflection API. We are ignoring this possibility. After all, }

%\paragraph*{Rationale for this Less Rigid Point of View} 
%If we did insist on that, we could not use any functionality provided by the underlying platform, which is in our case \java{} and the \java{} Virtual Machine. For we could not guarantee that certain constants or pure methods we use will be unchanged in the next update or version of that component. 
%
%Alternatively, one could of course define the term \emph{program} in such a way that it encloses a specific version of the \java{} runtime system (and in turn specific versions of the libraries used by \java{}, and the libraries used by those libraries down to the operating system and even the hardware). But then, the term \emph{program} would become almost meaningless
%\footnote{Suppose, for example, that some chip producer finds a bug in one of the floating point units that he produces, which causes incorrect results to be returned by certain floating point divisions. Suppose further, that the faulty CPU chip is replaced by a fixed one in the computer used by an extremely rigid functional purist, who insists that functions must produce the same value across different program executions. Then, this person must either admit that some function he wrote was not pure (because it suddenly produces different results for the same argument values) or he must regard his program as having changed. He could, for instance, talk about how much more exact results "\emph{this new version of my program}"  produces, despite nobody hasn't changed a single bit on the hard disk!
%
%This argumentation is not invalidated by pointing out that the faulty CPU did not behave according to their specification. It remains the fact that results of computer functions depend on the computing environment they are executed in, no matter if one likes it or not.
%}.
%
%It is probably more rational to acknowledge that the idea of a function that \emph{depends on nothing but its arguments} is an utterly idealistic one that must necessarily abstract away many aspects of reality. In practice, the result of a function $\backslash x \rightarrow x/3145727.0$, when defined in some computer language and executed in some computing environment depends not only on $x$, but also on how the floating point unit works, how exact the divisor can be represented in floating point, in short, it depends on the computing environment where it is run. 
%
%We do not understand the concept of functional purity so narrowly that we require the same result of a pure function in all thinkable computing environments. Rather, we admit realistically that results may be different in different computing environments. The session environment\footnote{The mapping of values printed by the command \term{env} in a \textsc{Unix} session; similar features exist in other operating systems.} is a part of the computing environment that is constant during program execution (in \java{} programs, that is). Hence, the result of a pure function in a program may depend on environment variables, according to our definition. It may depend on the arguments passed on the command line. Yet, it may not depend on the current directory, for obtaining the name of it presupposes input/output to be performed. It may also not depend on \java{}s system properties, for those can be changed during program execution.
\end{description}

\section{Terminology and Definitions}

Let's recall the general forms of native data and function declarations:
\begin{quote}
\begin{flushleft}
\textbf{data} $T$ $s$ = \textbf{native} $J$\\
\textbf{native} $v$ $j$ :: $t$
\end{flushleft}
\end{quote}

We call $T$ a \emph{native type} and $J$ the \emph{java type} associated with it. If $T$ is associated with one of \texttt{byte}, \texttt{boolean}, \texttt{char}, \texttt{short}, \texttt{int}, \texttt{long}, \texttt{float} or \texttt{double}, then $T$ is a \emph{primitive type}, otherwise it is a  \emph{reference type}.

We call $v$ a \emph{native value} and $j$ the \emph{java item} associated with it. If $t$ is of the form $t_1 \rightarrow{} \cdots{} \rightarrow{} t_k \rightarrow{}t_R$, where $t_R$ is not itself a function type, we call $v$ a \emph{native function} with \emph{arity} $k$ $(k\ge 1)$ and \emph{return type} $t_R$. The $t_i$ are called \emph{argument types}. For $v$'s that are not native functions, the arity is 0 and the return type is $t$.

$J$ and $j$ are snippets of \java{} code and can be specified as identifiers, qualified identifiers or operator symbols as long as this does not violate the \frege{} lexical syntax. In all other cases the code snippets can be given in the form of string literals. In the following sections, we will frequently use the value of $j$ or just $j$. This is to be understood as the string that is described by the string literal, not the string literal itself.
{'fraction_non_alphanumeric': 0.06727976766698936, 'fraction_numerical': 0.019240077444336885, 'mean_word_length': 4.446128500823723, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2091321', 'n_tokens_mistral': 4466, 'n_tokens_neox': 4157, 'n_words': 2512}