Changeset 6b6597c for doc/user

Timestamp:

Apr 19, 2016, 9:36:29 PM (8 years ago)

Author:

Peter A. Buhr <pabuhr@…>

Branches:

ADT, aaron-thesis, arm-eh, ast-experimental, cleanup-dtors, ctor, deferred_resn, demangler, enum, forall-pointer-decay, gc_noraii, jacob/cs343-translation, jenkins-sandbox, master, memory, new-ast, new-ast-unique-expr, new-env, no_list, persistent-indexer, pthread-emulation, qualifiedEnum, resolv-new, string, with_gc

Children:

0cb1d61, 6e991d6

Parents:

09d1ad0

Message:

user manual updates, extend I/O test, fix memset in stdlib, workaround for fstream

Location:

doc/user

Files:

• Makefile (modified) (1 diff)
• user.tex (modified) (17 diffs)

doc/user/Makefile

@@ -12 +12 @@
 
 FIGURES = ${addsuffix .tex, \
+Cdecl \
 }
 

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 10 22:50:15 2016
-%% Update Count     : 72
+%% Last Modified On : Thu Apr 14 21:30:07 2016
+%% Update Count     : 130
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
@@ -26 +26 @@
 \usepackage{upquote}
 \usepackage{fullpage,times}
+\usepackage{epic,eepic}
 \usepackage{xspace}
 \usepackage{varioref}
@@ -48 +49 @@
 % Names used in the document.
 
+\newcommand{\Version}{1.0.0}
 \newcommand{\CS}{C\raisebox{-0.9ex}{\large$^\sharp$}\xspace}
 
@@ -105 +107 @@
 The syntax of the \CFA language builds from C, and should look immediately familiar to C programmers.
 % Any language feature that is not described here can be assumed to be using the standard C11 syntax.
-\CFA adds many modern programming-language features, which directly leads to increased safety and productivity, while maintaining interoperability with existing C programs and maintaining C-like performance.
+\CFA adds many modern programming-language features, which directly leads to increased safety and productivity, while maintaining interoperability with existing C programs and achieving C performance.
 Like C, \CFA is a statically typed, procedural language with a low-overhead runtime, meaning there is no global garbage-collection.
 The primary new features include parametric-polymorphism routines and types, exceptions, concurrency, and modules.
@@ -224 +226 @@
 
 
-\section{Compiling \CFA}
+\section{Compiling \CFA Program}
 
 The command \lstinline@cfa@ is used to compile \CFA program(s).
@@ -231 +233 @@
 cfa [ gcc-options ] C/@{\CFA}@-files [ assembler/loader-files ]
 \end{lstlisting}
+\index{cfa@\lstinline$cfa$}\index{compilation!cfa@\lstinline$cfa$}
 By default, \CFA programs having the following \lstinline@gcc@ flags turned on:
 \begin{description}
 \item
 \hspace*{-4pt}\lstinline@-std=gnu99@
+\index{-std=gnu99@{\lstinline$-std=gnu99$}}\index{compilation option!-std=gnu99@{\lstinline$-std=gnu99$}}
 The 1999 C standard plus GNU extensions.
 \end{description}
@@ -241 +245 @@
 \item
 \hspace*{-4pt}\lstinline@-CFA@
+\index{-CFA@{\lstinline$-CFA$}}\index{compilation option!-CFA@{\lstinline$-CFA$}}
 Only the C preprocessor and the \CFA translator steps are performed and the transformed program is written to standard output, which makes it possible to examine the code generated by the \CFA translator.
 \end{description}
+
+The following preprocessor variables are available:
+\begin{description}
+\item
+\hspace*{-4pt}\lstinline$__CFA__$
+\index{__CFA__@{\lstinline$__CFA__$}}\index{preprocessor variables!__CFA__@{\lstinline$__CFA__$}}
+is always available during preprocessing and its value is the current major \Index{version number} of \CFA.\footnote{
+The C preprocessor allows only integer values in a preprocessor variable so a value like ``\Version'' is not allowed.
+Hence, the need to have three variables for the major, minor and patch version number.}
+
+\item
+\hspace*{-4pt}\lstinline$__CFA_MINOR__$
+\index{__CFA_MINOR__@{\lstinline$__CFA_MINOR__$}}\index{preprocessor variables!__CFA_MINOR__@{\lstinline$__CFA_MINOR__$}}
+is always available during preprocessing and its value is the current minor \Index{version number} of \CFA.
+
+\item
+\hspace*{-4pt}\lstinline$__CFA_PATCH__$
+\index{__CFA_PATCH__@%(__CFA_PATCH__%)}\index{preprocessor variables!__CFA_PATCH__@%(__CFA_PATCH__%)}
+is always available during preprocessing and its value is the current patch \Index{version number} of \CFA.
+
+\item
+\hspace*{-4pt}\lstinline$__CFORALL__$
+\index{__CFORALL__@%(__CFORALL__%)}\index{preprocessor variables!__CFORALL__@%(__CFORALL__%)}
+is always available during preprocessing and it has no value.
+\end{description}
+
+These preprocessor variables allow conditional compilation of programs that must work differently in these situations.
+For example, to toggle between C and \CFA extensions, using the following:
+\begin{lstlisting}
+#ifndef __CFORALL__
+#include <stdio.h>              // C header file
+#else
+#include <fstream>              // @\CFA{}@ header file
+#endif
+\end{lstlisting}
+which conditionally includes the correct header file, if the program is compiled using \lstinline@gcc@ or \lstinline@cfa@. 
 
 
@@ -284 +325 @@
 C declaration syntax is notoriously confusing and error prone.
 For example, many C programmers are confused by a declaration as simple as:
-\begin{lstlisting}
-int *x[ 10 ]
-\end{lstlisting}
-Is this a pointer to an array of 10 integers or an array of 10 pointers to integers?
+\begin{quote2}
+\begin{tabular}{@{}ll@{}}
+\begin{lstlisting}[aboveskip=0pt,belowskip=0pt]
+int *x[ 5 ]
+\end{lstlisting}
+&
+\raisebox{-0.75\totalheight}{\input{Cdecl}}
+\end{tabular}
+\end{quote2}
+Is this an array of 5 pointers to integers or a pointer to an array of 5 integers?
 Another example of confusion results from the fact that a routine name and its parameters are embedded within the return type, mimicking the way the return value is used at the routine's call site.
 For example, a routine returning a pointer to an array of integers is defined and used in the following way:
 \begin{lstlisting}
-int (*f())[ 10 ] {...};
-... (*f())[  3 ] += 1;  // definition mimics usage
+int (*f())[ 5 ] {...};  // definition mimics usage
+... (*f())[ 3 ] += 1;
 \end{lstlisting}
 Essentially, the return type is wrapped around the routine name in successive layers (like an onion).
@@ -322 +369 @@
 \multicolumn{1}{c@{\hspace{30pt}}}{\textbf{\CFA}}       & \multicolumn{1}{c@{\hspace{20pt}}}{\textbf{C}}        \\
 \begin{lstlisting}
-[ 10 ] int z;
-[ 10 ] * char w;
-* [ 10 ] double v;
+[ 5 ] int z;
+[ 5 ] * char w;
+* [ 5 ] double v;
 struct s {
         int f0:3;
         * int f1;
-        [ 10 ] * int f2;
+        [ 5 ] * int f2;
 };
 \end{lstlisting}
 &
 \begin{lstlisting}
-int z[ 10 ];
-char *w[ 10 ];
-double (*v)[ 10 ];
+int z[ 5 ];
+char *w[ 5 ];
+double (*v)[ 5 ];
 struct s {
         int f0:3;
         int *f1;
-        int *f2[ 10 ]
+        int *f2[ 5 ]
 };
 \end{lstlisting}
 &
 \begin{lstlisting}
-// array of 10 integers
-// array of 10 pointers to char
-// pointer to array of 10 doubles
+// array of 5 integers
+// array of 5 pointers to char
+// pointer to array of 5 doubles
 
 // common bit field syntax
@@ -362 +409 @@
 \begin{lstlisting}
 const * const int x;
-const * [ 10 ] const int y;
+const * [ 5 ] const int y;
 \end{lstlisting}
 &
 \begin{lstlisting}
 int const * const x;
-const int (* const y)[ 10 ]
+const int (* const y)[ 5 ]
 \end{lstlisting}
 &
 \begin{lstlisting}
 // const pointer to const integer
-// const pointer to array of 10 const integers
+// const pointer to array of 5 const integers
 \end{lstlisting}
 \end{tabular}
@@ -382 +429 @@
 \multicolumn{1}{c@{\hspace{30pt}}}{\textbf{\CFA}}       & \multicolumn{1}{c@{\hspace{20pt}}}{\textbf{C}}        \\
 \begin{lstlisting}
-extern [ 10 ] int x;
+extern [ 5 ] int x;
 static * const int y;
 \end{lstlisting}
 &
 \begin{lstlisting}
-int extern x[ 10 ];
+int extern x[ 5 ];
 const int static *y;
 \end{lstlisting}
 &
 \begin{lstlisting}
-// externally visible array of 10 integers
+// externally visible array of 5 integers
 // internally visible pointer to constant int
 \end{lstlisting}
@@ -421 +468 @@
 \begin{lstlisting}
 y = (* int)x;
-i = sizeof([ 10 ] * int);
+i = sizeof([ 5 ] * int);
 \end{lstlisting}
 &
 \begin{lstlisting}
 y = (int *)x;
-i = sizeof(int *[ 10 ]);
+i = sizeof(int *[ 5 ]);
 \end{lstlisting}
 \end{tabular}
@@ -466 +513 @@
 \CFA style declarations cannot be used to declare parameters for K\&R style routine definitions because of the following ambiguity:
 \begin{lstlisting}
-int (*f(x))[ 10 ] int x; {}
-\end{lstlisting}
-The string ``\lstinline@int (*f(x))[ 10 ]@'' declares a K\&R style routine of type returning a pointer to an array of 10 integers, while the string ``\lstinline@[ 10 ] int x@'' declares a \CFA style parameter x of type array of 10 integers.
+int (*f(x))[ 5 ] int x; {}
+\end{lstlisting}
+The string ``\lstinline@int (*f(x))[ 5 ]@'' declares a K\&R style routine of type returning a pointer to an array of 5 integers, while the string ``\lstinline@[ 5 ] int x@'' declares a \CFA style parameter x of type array of 5 integers.
 Since the strings overlap starting with the open bracket, \lstinline@[@, there is an ambiguous interpretation for the string.
 As well, \CFA-style declarations cannot be used to declare parameters for C-style routine-definitions because of the following ambiguity:
@@ -487 +534 @@
 \begin{lstlisting}
 #define ptoa( n, d ) int (*n)[ d ]
-int f( ptoa(p,10) ) ...         // expands to int f( int (*p)[ 10 ] )
-[ int ] f( ptoa(p,10) ) ...     // expands to [ int ] f( int (*p)[ 10 ] )
+int f( ptoa(p,5) ) ...          // expands to int f( int (*p)[ 5 ] )
+[ int ] f( ptoa(p,5) ) ...      // expands to [ int ] f( int (*p)[ 5 ] )
 \end{lstlisting}
 Again, programmers are highly encouraged to use one declaration form or the other, rather than mixing the forms.
@@ -807 +854 @@
 which can be used to sort in ascending and descending order by locally redefining the less-than operator into greater-than.
 \begin{lstlisting}
-const unsigned int size = 10;
+const unsigned int size = 5;
 int ia[size];
 ...                                             // assign values to array ia
@@ -874 +921 @@
 [ double, double, double ]
 [ * int, int * ]                // mix of CFA and ANSI
-[ * [ 10 ] int, * * char, * [ [ int, int ] ] (int, int) ]
+[ * [ 5 ] int, * * char, * [ [ int, int ] ] (int, int) ]
 \end{lstlisting}
 Like tuples, tuple types may be nested, such as \lstinline@[ [ int, int ], int ]@, which is a 2-element tuple type whose first element is itself a tuple type.
@@ -2216 +2263 @@
 
         try {
-        throw 13;
+                throw 13;
         }
         catch(int e) {
-        printf(.caught an exception: %d\n., e);
+                printf(.caught an exception: %d\n., e);
         }
 \end{lstlisting}