From 67455dbd7dbe2b50344b9622a04b8fcd5e77116c Mon Sep 17 00:00:00 2001 From: Henrik Tidefelt Date: Fri, 6 Nov 2020 12:19:49 +0100 Subject: [PATCH] Cleanup listings related to external-clauses (#2688) * Improve readability of external-clauses * Clean up whitespace in listings related to external functions * Remove bad escaping in 'size\_t' inside lstlisting * Suggest that we add syntax highlighting for 'size_t' in C This would be similar to how we do syntax highlighting of certain recognized identifiers in Modelica, apart from the keywords. * Indent 'external' with to same level as 'function' The annotation of the external clause is indented one level deeper than the external-function-call, to avoid mixing it up with the function annotation. --- chapters/functions.tex | 90 ++++++++++++++++++++++++------------------ preamble.tex | 1 + 2 files changed, 53 insertions(+), 38 deletions(-) diff --git a/chapters/functions.tex b/chapters/functions.tex index df9ca85bc..79451cfc4 100644 --- a/chapters/functions.tex +++ b/chapters/functions.tex @@ -362,7 +362,8 @@ \section{Pure Modelica Functions}\label{pure-modelica-functions} impure function receiveRealSignal // impure function input HardwareDriverID id; output Real y; - external "C" y = receiveSignal(id); +external "C" + y = receiveSignal(id); end receiveRealSignal; \end{lstlisting} Examples of allowed optimizations of pure functions: @@ -1699,8 +1700,9 @@ \section{External Function Interface}\label{external-function-interface} function IDENT description-string { component-clause ";" } [ protected { component-clause ";" } ] - external [ language-specification ] [ - external-function-call ] [annotation ] ";" +external [ language-specification ] + [ external-function-call ] + [annotation ] ";" [ annotation ";" ] end IDENT; \end{lstlisting} @@ -1735,13 +1737,14 @@ \section{External Function Interface}\label{external-function-interface} function sin input Real x; output Real y; - external "builtin" y=sin(x); + external "builtin" + y = sin(x); end sin; end Math; end Modelica; model UserModel - parameter Real p=Modelica.Math.sin(2); + parameter Real p = Modelica.Math.sin(2); end UserModel; \end{lstlisting} \end{example} @@ -1932,7 +1935,7 @@ \subsubsection{Arrays}\label{arrays-1} function foo input Real a[:,:,:]; output Real x; - external "FORTRAN 77"; +external "FORTRAN 77"; end foo; \end{lstlisting} the default assumptions correspond to a FORTRAN~77 function @@ -1964,7 +1967,8 @@ \subsubsection{Arrays}\label{arrays-1} input Integer i; output Real u1[size(y,1)]; output Integer u2[size(y,2)]; - external "FORTRAN 77" myfoo(x, y, size(x,1), size(y,2), u1, i, u2); +external "FORTRAN 77" + myfoo(x, y, size(x,1), size(y,2), u1, i, u2); end foo; \end{lstlisting} The corresponding FORTRAN~77 subroutine would be declared as follows: @@ -1993,7 +1997,7 @@ \subsubsection{Arrays}\label{arrays-1} \end{lstlisting} This corresponds to the following C prototype: \begin{lstlisting}[language=C] -double fie(double *, size\_t, size\_t); +double fie(double *, size_t, size_t); \end{lstlisting} \end{example} @@ -2085,8 +2089,9 @@ \subsection{Aliasing}\label{aliasing} function foo input Real x; input Real y; - output Real z=x; - external "FORTRAN 77" myfoo(x,y,z); + output Real z = x; +external "FORTRAN 77" + myfoo(x, y, z); end foo; \end{lstlisting} The following Modelica function: @@ -2095,20 +2100,20 @@ \subsection{Aliasing}\label{aliasing} input Real a; output Real b; algorithm - b:=foo(a,a); - b:=foo(b,2*b); + b := foo(a, a); + b := foo(b, 2 * b); end f; \end{lstlisting} can on most systems be transformed into the following C function: \begin{lstlisting}[language=C] double f(double a) { - extern void myfoo_(double*,double*,double*); - double b,temp1,temp2; + extern void myfoo_(double*, double*, double*); + double b, temp1, temp2; - myfoo_(&a,&a,&b); - temp1=2*b; - temp2=b; - myfoo_(&b,&temp1,&temp2); + myfoo_(&a, &a, &b); + temp1 = 2 * b; + temp2 = b; + myfoo_(&b, &temp1, &temp2); return temp2; } @@ -2126,10 +2131,11 @@ \subsection{Aliasing}\label{aliasing} \begin{lstlisting}[language=modelica] function foo input Real x; - protected Real xtemp=x; // Temporary used because myfoo changes its input + protected Real xtemp = x; // Temporary used because myfoo changes its input public input Real y; output Real z; - external "FORTRAN 77" myfoo(xtemp,y,z); +external "FORTRAN 77" + myfoo(xtemp, y, z); end foo; \end{lstlisting} @@ -2140,8 +2146,8 @@ \subsection{Aliasing}\label{aliasing} follow the standard and are unable to handle aliasing between input variables the tool must transform the first call of \lstinline!foo! into: \begin{lstlisting}[language=C] -temp1=a; /* Temporary to avoid aliasing */ -myfoo_(&a,&temp1,&b); +temp1 = a; /* Temporary to avoid aliasing */ +myfoo_(&a, &temp1, &b); \end{lstlisting} The use of the function \lstinline!foo! in Modelica is uninfluenced by these considerations. @@ -2227,37 +2233,40 @@ \subsection{Annotations for External Libraries and Include Files}\label{annotati \begin{lstlisting}[language=modelica] package ExternalFunctions model Example - Real x(start=1.0),y(start=2.0); + Real x(start = 1.0), y(start = 2.0); equation - der(x)=-ExternalFunc1(x); - der(y)=-ExternalFunc2(y); + der(x) = -ExternalFunc1(x); + der(y) = -ExternalFunc2(y); end Example; model OtherExample - Real x(start=1.0); + Real x(start = 1.0); equation - der(x)=-ExternalFunc3(x); + der(x) = -ExternalFunc3(x); end OtherExample; function ExternalFunc1 input Real x; output Real y; - external "C" - y=ExternalFunc1_ext(x) annotation(Library="ExternalLib1", - Include="#include \"ExternalFunc1.h\""); + external "C" + y = ExternalFunc1_ext(x) + annotation(Library = "ExternalLib1", + Include = "#include \"ExternalFunc1.h\""); end ExternalFunc1; function ExternalFunc2 input Real x; output Real y; - external "C" annotation(Library="ExternalLib2", - Include="#include \"ExternalFunc2.h\""); + external "C" + annotation(Library = "ExternalLib2", + Include = "#include \"ExternalFunc2.h\""); end ExternalFunc2; function ExternalFunc3 input Real x; output Real y; - external "C" annotation(Include="#include \"ExternalFunc3.c\""); + external "C" + annotation(Include = "#include \"ExternalFunc3.c\""); end ExternalFunc3; end ExternalFunctions; @@ -2371,7 +2380,8 @@ \subsubsection{Arbitrary Placement of Output Parameters, No External Function Va input Integer y; output Real u1; output Integer u2; - external "C" myfoo(x, u1, y, u2); +external "C" + myfoo(x, u1, y, u2); end foo; \end{lstlisting} This corresponds to the following C prototype: @@ -2400,7 +2410,8 @@ \subsubsection{External Function with Both Function Value and Output Variable}\l input Integer y; output Real funcvalue; output Integer out1; - external "C" funcvalue = myfoo(x, y, out1); +external "C" + funcvalue = myfoo(x, y, out1); end foo; \end{lstlisting} This corresponds to the following C prototype: @@ -2630,12 +2641,14 @@ \subsection{External Objects}\label{external-objects} input String fileName = ""; input String tableName = ""; output MyTable table; - external "C" table = initMyTable(fileName, tableName); + external "C" + table = initMyTable(fileName, tableName); end constructor; function destructor "Release storage of table" input MyTable table; - external "C" closeMyTable(table); + external "C" + closeMyTable(table); end destructor; end MyTable; \end{lstlisting} @@ -2656,7 +2669,8 @@ \subsection{External Objects}\label{external-objects} input MyTable table; input Real u; output Real y; - external "C" y = interpolateMyTable(table, u); +external "C" + y = interpolateMyTable(table, u); end interpolateTable; \end{lstlisting} The external C functions may be defined in the following way: diff --git a/preamble.tex b/preamble.tex index 1b1b24eff..ee8236391 100644 --- a/preamble.tex +++ b/preamble.tex @@ -302,6 +302,7 @@ else,enum,extern,float,for,goto,if,int,long,register,return,% short,signed,sizeof,static,struct,switch,typedef,union,unsigned,% void,volatile,while}, + % henrikt-ma: How about adding some highlighting of 'size_t' as a recognized name? sensitive, morecomment=[s]{/*}{*/}, morecomment=[l]//, % nonstandard