Changes in doc/user/user.tex [9e6d652:200fcb3]

File:

• doc/user/user.tex (modified) (7 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 May  5 18:24:50 2019
-%% Update Count     : 3489
+%% Last Modified On : Tue Dec 11 23:19:26 2018
+%% Update Count     : 3400
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
@@ -193 +193 @@
 \end{center}
 While the \CFA I/O looks similar to the \Index*[C++]{\CC{}} output style, there are important differences, such as automatic spacing between variables as in \Index*{Python} (see~\VRef{s:IOLibrary}).
-
 
 \subsection{Background}
@@ -433 +432 @@
 which conditionally includes the correct header file, if the program is compiled using \Indexc{gcc} or \Indexc{cfa}.
 
-The \CFA translator has multiple steps.
-The following flags control how the tranlator works, the stages run, and printing within a stage.
-The majority of these flags are used by \CFA developers, but some are occasionally useful to programmers.
-\begin{description}[topsep=5pt,itemsep=0pt,parsep=0pt]
-\item
-\Indexc{-h}\index{translator option!-h@{©-h©}}, \Indexc{--help}\index{translator option!--help@{©--help©}} \, print help message
-\item
-\Indexc{-l}\index{translator option!-l@{©-l©}}, \Indexc{--libcfa}\index{translator option!--libcfa@{©--libcfa©}} \, generate libcfa.c
-\item
-\Indexc{-L}\index{translator option!-L@{©-L©}}, \Indexc{--linemarks}\index{translator option!--linemarks@{©--linemarks©}} \, generate line marks
-\item
-\Indexc{-m}\index{translator option!-m@{©-m©}}, \Indexc{--no-main}\index{translator option!--no-main@{©--no-main©}} \, do not replace main
-\item
-\Indexc{-N}\index{translator option!-N@{©-N©}}, \Indexc{--no-linemarks}\index{translator option!--no-linemarks@{©--no-linemarks©}} \, do not generate line marks
-\item
-\Indexc{-n}\index{translator option!-n@{©-n©}}, \Indexc{--no-prelude}\index{translator option!--no-prelude@{©--no-prelude©}} \, do not read prelude
-\item
-\Indexc{-p}\index{translator option!-p@{©-p©}}, \Indexc{--prototypes}\index{translator option!--prototypes@{©--prototypes©}} \, generate prototypes for prelude functions
-\item
-\Indexc{-P}\index{translator option!-P@{©-P©}}, \Indexc{--print}\index{translator option!--print@{©--print©}} \, one of:
-\begin{description}[topsep=0pt,itemsep=0pt,parsep=0pt]
-\item
-\Indexc{altexpr}\index{translator option!-P@{©-P©}!©altexpr©}\index{translator option!--print@{©-print©}!©altexpr©} \, alternatives for expressions
-\item
-\Indexc{ascodegen}\index{translator option!-P@{©-P©}!©ascodegen©}\index{translator option!--print@{©-print©}!©ascodegen©} \, as codegen rather than AST
-\item
-\Indexc{ast}\index{translator option!-P@{©-P©}!©ast©}\index{translator option!--print@{©-print©}!©ast©} \, AST after parsing
-\item
-\Indexc{astdecl}\index{translator option!-P@{©-P©}!©astdecl©}\index{translator option!--print@{©-print©}!©astdecl©} \, AST after declaration validation pass
-\item
-\Indexc{asterr}\index{translator option!-P@{©-P©}!©asterr©}\index{translator option!--print@{©-print©}!©asterr©} \, AST on error
-\item
-\Indexc{astexpr}\index{translator option!-P@{©-P©}!©astexpr©}\index{translator option!--print@{©-print©}!©altexpr©} \, AST after expression analysis
-\item
-\Indexc{astgen}\index{translator option!-P@{©-P©}!©astgen©}\index{translator option!--print@{©-print©}!©astgen©} \, AST after instantiate generics
-\item
-\Indexc{box}\index{translator option!-P@{©-P©}!©box©}\index{translator option!--print@{©-print©}!©box©} \, before box step
-\item
-\Indexc{ctordtor}\index{translator option!-P@{©-P©}!©ctordtor©}\index{translator option!--print@{©-print©}!©ctordtor©} \, after ctor/dtor are replaced
-\item
-\Indexc{codegen}\index{translator option!-P@{©-P©}!©codegen©}\index{translator option!--print@{©-print©}!©codegen©} \, before code generation
-\item
-\Indexc{declstats}\index{translator option!-P@{©-P©}!©declstats©}\index{translator option!--print@{©-print©}!©declstats©} \, code property statistics
-\item
-\Indexc{parse}\index{translator option!-P@{©-P©}!©parse©}\index{translator option!--print@{©-print©}!©parse©} \, yacc (parsing) debug information
-\item
-\Indexc{pretty}\index{translator option!-P@{©-P©}!©pretty©}\index{translator option!--print@{©-print©}!©pretty©} \, prettyprint for ascodegen flag
-\item
-\Indexc{resolver}\index{translator option!-P@{©-P©}!©resolver©}\index{translator option!--print@{©-print©}!©resolver©} \, before resolver step
-\item
-\Indexc{rproto}\index{translator option!-P@{©-P©}!©rproto©}\index{translator option!--print@{©-print©}!©rproto©} \, resolver-proto instance
-\item
-\Indexc{rsteps}\index{translator option!-P@{©-P©}!©rsteps©}\index{translator option!--print@{©-print©}!©rsteps©} \, resolver steps
-\item
-\Indexc{symevt}\index{translator option!-P@{©-P©}!©symevt©}\index{translator option!--print@{©-print©}!©symevt©} \, symbol table events
-\item
-\Indexc{tree}\index{translator option!-P@{©-P©}!©tree©}\index{translator option!--print@{©-print©}!©tree©} \, parse tree
-\item
-\Indexc{tuple}\index{translator option!-P@{©-P©}!©tuple©}\index{translator option!--print@{©-print©}!©tuple©} \, after tuple expansion
-\end{description}
-\item
-\Indexc{--prelude-dir} <directory> \, prelude directory for debug/nodebug
-\item
-\Indexc{-S}\index{translator option!-S@{©-S©}!©counters,heap,time,all,none©}, \Indexc{--statistics}\index{translator option!--statistics@{©--statistics©}!©counters,heap,time,all,none©} <option-list> \, enable profiling information:
-\begin{description}[topsep=0pt,itemsep=0pt,parsep=0pt]
-\item
-\Indexc{counters,heap,time,all,none}
-\end{description}
-\item
-\Indexc{-t}\index{translator option!-t@{©-t©}}, \Indexc{--tree}\index{translator option!--tree@{©--tree©}} build in tree
-\end{description}
-
 
 \section{Backquote Identifiers}
@@ -581 +508 @@
 
 As for \Index{division}, there are exponentiation operators for integral and floating types, including the builtin \Index{complex} types.
-Integral exponentiation\index{exponentiation!unsigned integral} is performed with repeated multiplication\footnote{The multiplication computation is $O(\log y)$.} (or shifting if the exponent is 2).
-Overflow from large exponents or negative exponents return zero.
-Floating exponentiation\index{exponentiation!floating} is performed using \Index{logarithm}s\index{exponentiation!logarithm}, so the exponent cannot be negative.
-\begin{cfa}
-sout | 1 ®\® 0 | 1 ®\® 1 | 2 ®\® 8 | -4 ®\® 3 | 5 ®\® 3 | 5 ®\® 32 | 5L ®\® 32 | 5L ®\® 64 | -4 ®\® -3 | -4.0 ®\® -3 | 4.0 ®\® 2.1
-           | (1.0f+2.0fi) ®\® (3.0f+2.0fi);
-1 1 256 -64 125 ®0® 3273344365508751233 ®0® ®0® -0.015625 18.3791736799526 0.264715-1.1922i
-\end{cfa}
-Note, ©5 ®\® 32© and ©5L ®\® 64© overflow, and ©-4 ®\® -3© is a fraction but stored in an integer so all three computations generate an integral zero.
+Unsigned integral exponentiation\index{exponentiation!unsigned integral} is performed with repeated multiplication\footnote{The multiplication computation is $O(\log y)$.} (or shifting if the base is 2).
+Signed integral exponentiation\index{exponentiation!signed integral} is performed with repeated multiplication (or shifting if the base is 2), but yields a floating result because $x^{-y}=1/x^y$.
+Hence, it is important to designate exponent integral-constants as unsigned or signed: ©3 \ 3u© return an integral result, while ©3 \ 3© returns a floating result.
+Floating exponentiation\index{exponentiation!floating} is performed using \Index{logarithm}s\index{exponentiation!logarithm}, so the base cannot be negative.
+\begin{cfa}
+sout | 2 ®\® 8u | 4 ®\® 3u | -4 ®\® 3u | 4 ®\® -3 | -4 ®\® -3 | 4.0 ®\® 2.1 | (1.0f+2.0fi) ®\® (3.0f+2.0fi);
+256 64 -64 0.015625 -0.015625 18.3791736799526 0.264715-1.1922i
+\end{cfa}
 Parenthesis are necessary for complex constants or the expression is parsed as ©1.0f+®(®2.0fi \ 3.0f®)®+2.0fi©.
-The exponentiation operator is available for all the basic types, but for user-defined types, only the integral-computation version is available.
-\begin{cfa}
-forall( otype OT | { void ?{}( OT & this, one_t ); OT ?*?( OT, OT ); } )
-OT ?®\®?( OT ep, unsigned int y );
-forall( otype OT | { void ?{}( OT & this, one_t ); OT ?*?( OT, OT ); } )
-OT ?®\®?( OT ep, unsigned long int y );
-\end{cfa}
-The user type ©T© must define multiplication, one, ©1©, and, ©*©.
+The exponentiation operator is available for all the basic types, but for user-defined types, only the integral-computation versions are available.
+For returning an integral value, the user type ©T© must define multiplication, ©*©, and one, ©1©;
+for returning a floating value, an additional divide of type ©T© into a ©double© returning a ©double© (©double ?/?( double, T )©) is necessary for negative exponents.
 
 
@@ -628 +549 @@
 \subsection{Loop Control}
 
-The ©for©/©while©/©do-while© loop-control allows empty or simplified ranges (see Figure~\ref{f:LoopControlExamples}).
-\begin{itemize}
-\item
+The ©for©/©while©/©do-while© loop-control allows empty or simplified ranges.
 An empty conditional implies ©1©.
-\item
-The up-to range ©~©\index{~@©~©} means exclusive range [M,N).
-\item
-The up-to range ©~=©\index{~=@©~=©} means inclusive range [M,N].
-\item
-The down-to range ©-~©\index{-~@©-~©} means exclusive range [N,M).
-\item
-The down-to range ©-~=©\index{-~=@©-~=©} means inclusive range [N,M].
-\item
-©@© means put nothing in this field.
-\item
+The up-to range ©~©\index{~@©~©} means exclusive range [M,N);
+the up-to range ©~=©\index{~=@©~=©} means inclusive range [M,N].
+The down-to range ©-~©\index{-~@©-~©} means exclusive range [N,M);
+the down-to range ©-~=©\index{-~=@©-~=©} means inclusive range [N,M].
 ©0© is the implicit start value;
-\item
 ©1© is the implicit increment value.
-\item
 The up-to range uses ©+=© for increment;
-\item
-The down-to range uses ©-=© for decrement.
-\item
+the down-to range uses ©-=© for decrement.
 The loop index is polymorphic in the type of the start value or comparison value when start is implicitly ©0©.
-\end{itemize}
-
-\begin{figure}
 \begin{cquote}
-\begin{tabular}{@{}l|l@{}}
-\multicolumn{1}{c|}{loop control} & \multicolumn{1}{c}{output} \\
+\begin{tabular}{@{}ll|l@{}}
+\multicolumn{2}{c|}{loop control} & \multicolumn{1}{c}{output} \\
 \hline
 \begin{cfa}
-sout | nlOff;
-while ®()® { sout | "empty"; break; } sout | nl;
-do { sout | "empty"; break; } while ®()®; sout | nl;
-for ®()® { sout | "empty"; break; } sout | nl;
-for ( ®0® ) { sout | "A"; } sout | "zero" | nl;
-for ( ®1® ) { sout | "A"; } sout | nl;
-for ( ®10® ) { sout | "A"; } sout | nl;
-for ( ®1 ~= 10 ~ 2® ) { sout | "B"; } sout | nl;
-for ( ®10 -~= 1 ~ 2® ) { sout | "C"; } sout | nl;
-for ( ®0.5 ~ 5.5® ) { sout | "D"; } sout | nl;
-for ( ®5.5 -~ 0.5® ) { sout | "E"; } sout | nl;
-for ( ®i; 10® ) { sout | i; } sout | nl;
-for ( ®i; 1 ~= 10 ~ 2® ) { sout | i; } sout | nl;
-for ( ®i; 10 -~= 1 ~ 2® ) { sout | i; } sout | nl;
-for ( ®i; 0.5 ~ 5.5® ) { sout | i; } sout | nl;
-for ( ®i; 5.5 -~ 0.5® ) { sout | i; } sout | nl;
-for ( ®ui; 2u ~= 10u ~ 2u® ) { sout | ui; } sout | nl;
-for ( ®ui; 10u -~= 2u ~ 2u® ) { sout | ui; } sout | nl;
+while ®()® { sout | "empty"; break; }
+do { sout | "empty"; break; } while ®()®;
+for ®()® { sout | "empty"; break; }
+for ( ®0® ) { sout | "A"; }
+for ( ®1® ) { sout | "A"; }
+for ( ®10® ) { sout | "A"; }
+for ( ®1 ~= 10 ~ 2® ) { sout | "B"; }
+for ( ®10 -~= 1 ~ 2® ) { sout | "C"; }
+for ( ®0.5 ~ 5.5® ) { sout | "D"; }
+for ( ®5.5 -~ 0.5® ) { sout | "E"; }
+for ( ®i; 10® ) { sout | i; }
+for ( ®i; 1 ~= 10 ~ 2® ) { sout | i; }
+for ( ®i; 10 -~= 1 ~ 2® ) { sout | i; }
+for ( ®i; 0.5 ~ 5.5® ) { sout | i; }
+for ( ®i; 5.5 -~ 0.5® ) { sout | i; }
+for ( ®ui; 2u ~= 10u ~ 2u® ) { sout | ui; }
+for ( ®ui; 10u -~= 2u ~ 2u® ) { sout | ui; }
 enum { N = 10 };
-for ( ®N® ) { sout | "N"; } sout | nl;
-for ( ®i; N® ) { sout | i; } sout | nl;
-for ( ®i; N -~ 0® ) { sout | i; } sout | nl;
+for ( ®N® ) { sout | "N"; }
+for ( ®i; N® ) { sout | i; }
+for ( ®i; N -~ 0® ) { sout | i; }
 const int start = 3, comp = 10, inc = 2;
-for ( ®i; start ~ comp ~ inc + 1® ) { sout | i; } sout | nl;
-for ( ®i; 1 ~ @® ) { if ( i > 10 ) break;
-        sout | i; } sout | nl;
-for ( ®i; 10 -~ @® ) { if ( i < 0 ) break;
-        sout | i; } sout | nl;
-for ( ®i; 2 ~ @ ~ 2® ) { if ( i > 10 ) break;
-        sout | i; } sout | nl;
-for ( ®i; 2.1 ~ @ ~ @® ) { if ( i > 10.5 ) break;
-        sout | i; i += 1.7; } sout | nl;
-for ( ®i; 10 -~ @ ~ 2® ) { if ( i < 0 ) break;
-        sout | i; } sout | nl;
-for ( ®i; 12.1 ~ @ ~ @® ) { if ( i < 2.5 ) break;
-        sout | i; i -= 1.7; } sout | nl;
-for ( ®i; 5 : j; -5 ~ @® ) { sout | i | j; } sout | nl;
-for ( ®i; 5 : j; -5 -~ @® ) { sout | i | j; } sout | nl;
-for ( ®i; 5 : j; -5 ~ @ ~ 2® ) { sout | i | j; } sout | nl;
-for ( ®i; 5 : j; -5 -~ @ ~ 2® ) { sout | i | j; } sout | nl;
-for ( ®j; -5 ~ @ : i; 5® ) { sout | i | j; } sout | nl;
-for ( ®j; -5 -~ @ : i; 5® ) { sout | i | j; } sout | nl;
-for ( ®j; -5 ~ @ ~ 2 : i; 5® ) { sout | i | j; } sout | nl;
-for ( ®j; -5 -~ @ ~ 2 : i; 5® ) { sout | i | j; } sout | nl;
-for ( ®j; -5 -~ @ ~ 2 : i; 5 : k; 1.5 ~ @® ) {
-        sout | i | j | k; } sout | nl;
-for ( ®j; -5 -~ @ ~ 2 : k; 1.5 ~ @ : i; 5® ) {
-        sout | i | j | k; } sout | nl;
-for ( ®k; 1.5 ~ @ : j; -5 -~ @ ~ 2 : i; 5® ) {
-        sout | i | j | k; } sout | nl;
+for ( ®i; start ~ comp ~ inc + 1® ) { sout | i; }
 \end{cfa}
 &
 \begin{cfa}
-
+sout | nl;
+sout | nl;
+sout | nl;
+sout | "zero" | nl;
+sout | nl;
+sout | nl;
+sout | nl;
+sout | nl;
+sout | nl;
+sout | nl;
+sout | nl;
+sout | nl;
+sout | nl;
+sout | nl;
+sout | nl;
+sout | nl;
+sout | nl | nl;
+
+sout | nl;
+sout | nl;
+sout | nl | nl;
+
+sout | nl;
+\end{cfa}
+&
+\begin{cfa}
 empty
 empty
@@ -737 +640 @@
 
 3 6 9
-
-1 2 3 4 5 6 7 8 9 10
-
-10 9 8 7 6 5 4 3 2 1 0
-
-2 4 6 8 10
-
-2.1 3.8 5.5 7.2 8.9
-
-10 8 6 4 2 0
-
-12.1 10.4 8.7 7 5.3 3.6
-0 -5 1 -4 2 -3 3 -2 4 -1
-0 -5 1 -6 2 -7 3 -8 4 -9
-0 -5 1 -3 2 -1 3 1 4 3
-0 -5 1 -7 2 -9 3 -11 4 -13
-0 -5 1 -4 2 -3 3 -2 4 -1
-0 -5 1 -6 2 -7 3 -8 4 -9
-0 -5 1 -3 2 -1 3 1 4 3
-0 -5 1 -7 2 -9 3 -11 4 -13
-
-0 -5 1.5 1 -7 2.5 2 -9 3.5 3 -11 4.5 4 -13 5.5
-
-0 -5 1.5 1 -7 2.5 2 -9 3.5 3 -11 4.5 4 -13 5.5
-
-0 -5 1.5 1 -7 2.5 2 -9 3.5 3 -11 4.5 4 -13 5.5
 \end{cfa}
 \end{tabular}
 \end{cquote}
-\caption{Loop Control Examples}
-\label{f:LoopControlExamples}
-\end{figure}
 
 
@@ -1446 +1320 @@
 \end{cfa}
 Essentially, the return type is wrapped around the routine name in successive layers (like an \Index{onion}).
-While attempting to make the two contexts consistent is a laudable goal, it has not worked out in practice, even though Dennis Richie believed otherwise:
-\begin{quote}
-In spite of its difficulties, I believe that the C's approach to declarations remains plausible, and am comfortable with it; it is a useful unifying principle.~\cite[p.~12]{Ritchie93}
-\end{quote}
+While attempting to make the two contexts consistent is a laudable goal, it has not worked out in practice.
 
 \CFA provides its own type, variable and routine declarations, using a different syntax.