Changeset 8d66610 for doc/user/user.tex

Timestamp:

May 21, 2021, 4:48:10 PM (5 years ago)

Author:

Thierry Delisle <tdelisle@…>

Branches:

ADT, arm-eh, ast-experimental, enum, forall-pointer-decay, jacob/cs343-translation, master, new-ast-unique-expr, pthread-emulation, qualifiedEnum

Children:

f1bce515

Parents:

5407cdc (diff), 7404cdc (diff)
Note: this is a merge changeset, the changes displayed below correspond to the merge itself.
Use the (diff) links above to see all the changes relative to each parent.

Message:

Merge branch 'master' of plg.uwaterloo.ca:software/cfa/cfa-cc

File:

• doc/user/user.tex (modified) (23 diffs)

doc/user/user.tex

@@ -11 +11 @@
 %% Created On       : Wed Apr  6 14:53:29 2016
 %% Last Modified By : Peter A. Buhr
-%% Last Modified On : Sun Apr 25 19:03:03 2021
-%% Update Count     : 4951
+%% Last Modified On : Sat May  8 08:51:33 2021
+%% Update Count     : 5062
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
@@ -65 +65 @@
 % keyword escape ¶...¶ (pilcrow symbol) emacs: C-q M-^
 % math escape $...$ (dollar symbol)
-\input{common}                                          % common CFA document macros
+\usepackage{common}                                                                             % common CFA document macros
+%\input{common}                                                                                 % common CFA document macros
 \setlength{\gcolumnposn}{3in}
 \CFAStyle                                                                                               % use default CFA format-style
@@ -585 +586 @@
 For example, the octal ©0© or hexadecimal ©0x© prefix may end with an underscore ©0_377© or ©0x_ff©;
 the exponent infix ©E© may start or end with an underscore ©1.0_E10©, ©1.0E_10© or ©1.0_E_10©;
-the type suffixes ©U©, ©L©, etc. may start with an underscore ©1_U©, ©1_ll© or ©1.0E10_f©.
+the type suffixes ©U©, ©L©, \etc may start with an underscore ©1_U©, ©1_ll© or ©1.0E10_f©.
 \end{enumerate}
 It is significantly easier to read and enter long constants when they are broken up into smaller groupings (many cultures use comma and/or period among digits for the same purpose).
@@ -1570 +1571 @@
 \end{cquote}
 
-All type qualifiers, \eg ©const©, ©volatile©, etc., are used in the normal way with the new declarations and also appear left to right, \eg:
+All type qualifiers, \eg ©const©, ©volatile©, \etc, are used in the normal way with the new declarations and also appear left to right, \eg:
 \begin{cquote}
 \begin{tabular}{@{}l@{\hspace{1em}}l@{\hspace{1em}}l@{}}
@@ -1590 +1591 @@
 \end{tabular}
 \end{cquote}
-All declaration qualifiers, \eg ©extern©, ©static©, etc., are used in the normal way with the new declarations but can only appear at the start of a \CFA routine declaration,\footnote{\label{StorageClassSpecifier}
+All declaration qualifiers, \eg ©extern©, ©static©, \etc, are used in the normal way with the new declarations but can only appear at the start of a \CFA routine declaration,\footnote{\label{StorageClassSpecifier}
 The placement of a storage-class specifier other than at the beginning of the declaration specifiers in a declaration is an obsolescent feature.~\cite[\S~6.11.5(1)]{C11}} \eg:
 \begin{cquote}
@@ -3147 +3148 @@
 also, it is unnecessary to specify all the fields of a struct in a multiple record-field tuple.
 
-Since tuple-index expressions are a form of member-access expression, it is possible to use tuple-index expressions in conjunction with member-access expressions to restructure a tuple (\eg, rearrange components, drop components, duplicate components, etc.).
+Since tuple-index expressions are a form of member-access expression, it is possible to use tuple-index expressions in conjunction with member-access expressions to restructure a tuple (\eg, rearrange components, drop components, duplicate components, \etc).
 \begin{cfa}
 [ int, int, long, double ] x;
@@ -3312 +3313 @@
 
 \section{Tuples}
+\label{tuples}
 
 In C and \CFA, lists of elements appear in several contexts, such as the parameter list for a routine call.
@@ -3420 +3422 @@
 
 \subsection{Tuple Coercions}
+\label{tuple coercions}\label{coercions!tuple}
 
 There are four coercions that can be performed on tuples and tuple variables: closing, opening, flattening and structuring.
@@ -3464 +3467 @@
 
 \subsection{Mass Assignment}
+\label{mass assignment}\label{assignment!mass}
 
 \CFA permits assignment to several variables at once using mass assignment~\cite{CLU}.
@@ -3504 +3508 @@
 
 \subsection{Multiple Assignment}
+\label{multiple assignment}\label{assignment!multiple}
 
 \CFA also supports the assignment of several values at once, known as multiple assignment~\cite{CLU,Galletly96}.
@@ -3545 +3550 @@
 
 \subsection{Cascade Assignment}
+\index{cascade assignment}\index{assignment!cascade}
 
 As in C, \CFA mass and multiple assignments can be cascaded, producing cascade assignment.
@@ -3564 +3570 @@
 \section{Stream I/O Library}
 \label{s:StreamIOLibrary}
-\index{input/output stream library}
-\index{stream library}
+\index{input}\index{output}
+\index{stream library}\index{library!stream}
 
 The goal of \CFA stream input/output (I/O) is to simplify the common cases\index{I/O!common case}, while fully supporting polymorphism and user defined types in a consistent way.
 Stream I/O can be implicitly or explicitly formatted.
-Implicit formatting means \CFA selects the output or input format for values that match with the type of a variable.
+Implicit formatting means \CFA selects the output or input format for values that matches the variable's type.
 Explicit formatting means additional information is specified to augment how an output or input of value is interpreted.
-\CFA formatting is a cross between C ©printf© and \CC ©cout© manipulators, and Python implicit spacing and newline.
+\CFA formatting incorporates ideas from C ©printf©, \CC ©stream© manipulators, and Python implicit spacing and newline.
 Specifically:
 \begin{itemize}
@@ -3584 +3590 @@
 Hence, it is common programming practice to toggle manipulators on and then back to the default to prevent downstream side-effects.
 Without this programming style, errors occur when moving prints, as manipulator effects incorrectly flow into the new location.
-(To guarantee no side-effects, manipulator values must be saved and restored across function calls.)
-\item
-\CFA has more sophisticated implicit spacing between values than Python, plus implicit newline at the end of a print.
+Furthermore, to guarantee no side-effects, manipulator values must be saved and restored across function calls.
+\item
+\CFA has more sophisticated implicit value spacing than Python, plus implicit newline at the end of a print.
 \end{itemize}
+
+The standard polymorphic I/Os stream are ©stdin©/©sin© (input), ©stdout©/©sout© and ©stderr©/©serr© (output) (like C++ ©cin©/©cout©/©cerr©).
+Polymorphic streams ©exit© and ©abort© provide implicit program termination without and with generating a stack trace and core file.
+Stream ©exit© implicitly returns ©EXIT_FAILURE© to the shell.
+\begin{cfa}
+®exit®   | "x (" | x | ") negative value."; // terminate and return EXIT_FAILURE to shell
+®abort® | "x (" | x | ") negative value."; // terminate and generate stack trace and core file
+\end{cfa}
+Note, \CFA stream variables ©stdin©, ©stdout©, ©stderr©, ©exit©, and ©abort© overload C variables ©stdin©, ©stdout©, ©stderr©, and functions ©exit© and ©abort©, respectively.
 The \CFA header file for the I/O library is \Indexc{fstream.hfa}.
+
+
+\subsection{Basic I/O}
 
 For implicit formatted output, the common case is printing a series of variables separated by whitespace.
@@ -3601 +3619 @@
 \begin{cfa}
 
-cout << x ®<< " "® << y ®<< " "® << z << endl;
+cout  <<  x  ®<< " "®  <<  y  ®<< " "®  <<  z  << endl;
 \end{cfa}
 &
@@ -3653 +3671 @@
 \end{tabular}
 \end{cquote}
-Input and output use a uniform operator, ©|©, rather than separate operators, as in ©>>© and ©<<© for \CC.
+Input and output use a uniform operator, ©|©, rather than \CC's ©>>© and ©<<© input/output operators.
 There is a weak similarity between the \CFA logical-or operator and the \Index{Shell pipe-operator} for moving data, where data flows in the correct direction for input but the opposite direction for output.
 
@@ -3698 +3716 @@
 \end{cquote}
 
+\VRef[Figure]{f:CFACommand-LineProcessing} shows idiomatic \CFA command-line processing and copying an input file to an output file.
+Note, a stream variable may be copied because it is a reference to an underlying stream data-structures.
+All I/O errors are handles as exceptions, but end-of-file is not an exception as C programmers are use to explicitly checking for it.
+
+\begin{figure}
+\begin{cfa}
+#include ®<fstream.hfa>®
+
+int main( int argc, char * argv[] ) {
+        ®ifstream® in  = stdin;                                 $\C{// copy default files}$
+        ®ofstream® out = stdout;
+
+        try {
+                choose ( argc ) {
+                  case 2, 3:
+                        ®open®( in, argv[1] );                  $\C{// open input file first as output creates file}$
+                        if ( argc == 3 ) ®open®( out, argv[2] ); $\C{// do not create output unless input opens}$
+                  case 1: ;                                                     $\C{// use default files}$
+                  default:
+                        ®exit® | "Usage" | argv[0] | "[ input-file (default stdin) "
+                                   "[ output-file (default stdout) ] ]";
+                } // choose
+        } catch( ®Open_Failure® * ex; ex->istream == &in ) {
+                ®exit® | "Unable to open input file" | argv[1];
+        } catch( ®Open_Failure® * ex; ex->ostream == &out ) {
+                ®close®( in );                                          $\C{// optional}$
+                ®exit® | "Unable to open output file" | argv[2];
+        } // try
+
+        out | nlOff;                                                    $\C{// turn off auto newline}$
+        in | nlOn;                                                              $\C{// turn on reading newline}$
+        char ch;
+        for () {                                                                $\C{// read/write characters}$
+                in | ch;
+          if ( eof( in ) ) break;                               $\C{// eof ?}$
+                out | ch;
+        } // for
+} // main
+\end{cfa}
+\caption{\CFA Command-Line Processing}
+\label{f:CFACommand-LineProcessing}
+\end{figure}
+
+\VRef[Figure]{f:StreamFunctions} shows the stream operations.
+\begin{itemize}[topsep=4pt,itemsep=2pt,parsep=0pt]
+\item
+\Indexc{fail} tests the stream error-indicator, returning nonzero if it is set.
+\item
+\Indexc{clear} resets the stream error-indicator.
+\item
+\Indexc{flush} (©ofstream© only) causes any unwritten data for a stream to be written to the file.
+\item
+\Indexc{eof} (©ifstream© only) tests the end-of-file indicator for the stream pointed to by stream.
+Returns true if the end-of-file indicator is set, otherwise false.
+\item
+\Indexc{open} binds the file with ©name© to a stream accessed with ©mode© (see ©fopen©).
+\item
+\Indexc{close} flushes the stream and closes the file.
+\item
+\Indexc{write} (©ofstream© only) write ©size© bytes to the stream.
+The bytes are written lazily to file when internal buffers fill.
+Eager buffer writes are done with ©flush©
+\item
+\Indexc{read} (©ifstream© only) read ©size© bytes to the stream.
+\item
+\Indexc{ungetc} (©ifstream© only) pushes the character back to the input stream.
+Pushed-back characters returned by subsequent reads in the reverse order of pushing.
+\end{itemize}
+The constructor functions:
+\begin{itemize}[topsep=4pt,itemsep=2pt,parsep=0pt]
+\item
+create an unbound stream, which is subsequently bound to a file with ©open©.
+\item
+create a bound stream to the associated file with given ©mode©.
+\end{itemize}
+The destructor closes the stream.
+
+\begin{figure}
+\begin{cfa}
+// *********************************** ofstream ***********************************
+
+bool fail( ofstream & );$\indexc{fail}\index{ofstream@©ofstream©!©fail©}$
+void clear( ofstream & );$\indexc{clear}\index{ofstream@©ofstream©!©clear©}$
+int flush( ofstream & );$\indexc{flush}\index{ofstream@©ofstream©!©flush©}$
+void open( ofstream &, const char name[], const char mode[] = "w" );$\indexc{open}\index{ofstream@©ofstream©!©open©}$
+void close( ofstream & );$\indexc{close}\index{ofstream@©ofstream©!©close©}$
+ofstream & write( ofstream &, const char data[], size_t size );$\indexc{write}\index{ofstream@©ofstream©!©write©}$
+
+void ?{}( ofstream & );$\index{ofstream@©ofstream©!©?{}©}$
+void ?{}( ofstream &, const char name[], const char mode[] = "w" );
+void ^?{}( ofstream & );$\index{ofstream@©ofstream©!©^?{}©}$
+
+// *********************************** ifstream ***********************************
+
+bool fail( ifstream & is );$\indexc{fail}\index{ifstream@©ifstream©!©fail©}$
+void clear( ifstream & );$\indexc{clear}\index{ifstream@©ifstream©!©clear©}$
+bool eof( ifstream & is );$\indexc{eof}\index{ifstream@©ifstream©!©eof©}$
+void open( ifstream & is, const char name[], const char mode[] = "r" );$\indexc{open}\index{ifstream@©ifstream©!©open©}$
+void close( ifstream & is );$\indexc{close}\index{ifstream@©ifstream©!©close©}$
+ifstream & read( ifstream & is, char data[], size_t size );$\indexc{read}\index{ifstream@©ifstream©!©read©}$
+ifstream & ungetc( ifstream & is, char c );$\indexc{unget}\index{ifstream@©ifstream©!©unget©}$
+
+void ?{}( ifstream & is );$\index{ifstream@©ifstream©!©?{}©}$
+void ?{}( ifstream & is, const char name[], const char mode[] = "r" );
+void ^?{}( ifstream & is );$\index{ifstream@©ifstream©!©^?{}©}$
+\end{cfa}
+\caption{Stream Functions}
+\label{f:StreamFunctions}
+\end{figure}
 
 
@@ -3846 +3973 @@
 
 \item
-\Indexc{sepOn}\index{manipulator!sepOn@©sepOn©} and \Indexc{sepOff}\index{manipulator!sepOff@©sepOff©} toggle printing the separator with respect to the next printed item, and then return to the global seperator setting.
+\Indexc{sepOn}\index{manipulator!sepOn@©sepOn©} and \Indexc{sepOff}\index{manipulator!sepOff@©sepOff©} toggle printing the separator with respect to the next printed item, and then return to the global separator setting.
 \begin{cfa}[belowskip=0pt]
 sout | 1 | sepOff | 2 | 3; $\C{// turn off implicit separator for the next item}$
@@ -4030 +4157 @@
 sout | wd( 4, "ab" ) | wd( 3, "ab" ) | wd( 2, "ab" );
 \end{cfa}
-\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
+\begin{cfa}[showspaces=true,aboveskip=0pt]
 ®  ®34 ® ®34 34
 ®  ®4.000000 ® ®4.000000 4.000000
@@ -4378 +4505 @@
 \end{cfa}
 
-\Textbf{WARNING:} ©printf©\index{printf@©printf©}, ©scanf©\index{scanf@©scanf©} and their derivatives are unsafe when used with user-level threading, as in \CFA.
-These stream routines use kernel-thread locking (©futex©\index{futex@©futex©}), which block kernel threads, to prevent interleaving of I/O.
-However, the following simple example illustrates how a deadlock can occur (other complex scenarios are possible).
-Assume a single kernel thread and two user-level threads calling ©printf©.
-One user-level thread acquires the I/O lock and is time-sliced while performing ©printf©.
-The other user-level thread then starts execution, calls ©printf©, and blocks the only kernel thread because it cannot acquire the I/O lock.
-It does not help if the kernel lock is multiple acquisition, \ie, the lock owner can acquire it multiple times, because it then results in two user threads in the ©printf© critical section, corrupting the stream.
+
+\section{String Stream}
+
+All the stream formatting capabilities are available to format text to/from a C string rather than to a stream file.
+\VRef[Figure]{f:StringStreamProcessing} shows writing (output) and reading (input) from a C string.
+\begin{figure}
+\begin{cfa}
+#include <fstream.hfa>
+#include <strstream.hfa>
+
+int main() {
+        enum { size = 256 };
+        char buf[size]; $\C{// output buffer}$
+        ®ostrstream osstr = { buf, size };® $\C{// bind output buffer/size}$
+        int i = 3, j = 5, k = 7;
+        double x = 12345678.9, y = 98765.4321e-11;
+
+        osstr | i | hex(j) | wd(10, k) | sci(x) | unit(eng(y)); $\C{// same lines of output}$
+        write( osstr );
+        printf( "%s", buf );
+        sout | i | hex(j) | wd(10, k) | sci(x) | unit(eng(y));
+
+        char buf2[] = "12 14 15 3.5 7e4"; $\C{// input buffer}$
+        ®istrstream isstr = { buf2 };®
+        isstr | i | j | k | x | y;
+        sout | i | j | k | x | y;
+}
+\end{cfa}
+\caption{String Stream Processing}
+\label{f:StringStreamProcessing}
+\end{figure}
+
+\VRef[Figure]{f:StringStreamFunctions} shows the string stream operations.
+\begin{itemize}[topsep=4pt,itemsep=2pt,parsep=0pt]
+\item
+\Indexc{write} (©ostrstream© only) writes all the buffered characters to the specified stream (©stdout© default).
+\end{itemize}
+The constructor functions:
+\begin{itemize}[topsep=4pt,itemsep=2pt,parsep=0pt]
+\item
+create a bound stream to a write buffer (©ostrstream©) of ©size© or a read buffer (©istrstream©) containing a C string terminated with ©'\0'©.
+\end{itemize}
+
+\begin{figure}
+\begin{cfa}
+// *********************************** ostrstream ***********************************
+
+ostrstream & write( ostrstream & os, FILE * stream = stdout );
+
+void ?{}( ostrstream &, char buf[], size_t size );
+
+// *********************************** istrstream ***********************************
+
+void ?{}( istrstream & is, char buf[] );
+\end{cfa}
+\caption{String Stream Functions}
+\label{f:StringStreamFunctions}
+\end{figure}
 
 
@@ -5482 +5660 @@
 \item
 Package: a container to organize modules for distribution; It has attributes like name, author,
-version, dependences, etc.
-\item
-Project: a working set for a \CFA project; It has attributes like name, author, version, dependences, etc.
+version, dependences, \etc.
+\item
+Project: a working set for a \CFA project; It has attributes like name, author, version, dependences, \etc.
 \end{itemize}
 
@@ -5621 +5799 @@
 
 A package is defined by putting a project description file, Do.prj, with one or more modules into a directory.
-This project description file contains the package's meta data, including package name, author, version, dependences, etc.
+This project description file contains the package's meta data, including package name, author, version, dependences, \etc.
 It should be in the root of the package directory.
 
@@ -5678 +5856 @@
 Module: a container to organize a set of related types and methods; It has a module name, and several interfaces visible from outside
 \item
-Package: a container to organize modules for distribution; It has attributes like name, author, version, dependences, etc.
-\item
-Project: a working set for a \CFA project; It has attributes like name, author, version, dependences, etc.
+Package: a container to organize modules for distribution; It has attributes like name, author, version, dependences, \etc.
+\item
+Project: a working set for a \CFA project; It has attributes like name, author, version, dependences, \etc.
 \end{itemize}
 
@@ -8111 +8289 @@
 \begin{cquote}
 \begin{tabular}{@{}l@{\hspace{\parindentlnth}}|@{\hspace{\parindentlnth}}l@{}}
-\multicolumn{1}{@{}c|@{\hspace{\parindentlnth}}}{\textbf{\CFA}} & \multicolumn{1}{@{\hspace{\parindentlnth}}c}{\textbf{C}@{}}   \\
+\multicolumn{1}{@{}c|@{\hspace{\parindentlnth}}}{\textbf{\CFA}} & \multicolumn{1}{@{\hspace{\parindentlnth}}c@{}}{\textbf{C}}   \\
 \hline
 \begin{cfa}
-#include <gmp>$\indexc{gmp}$
+#include <gmp.hfa>$\indexc{gmp}$
 int main( void ) {
         sout | "Factorial Numbers";