Changeset 6b6597c for doc


Ignore:
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:
2 edited

Legend:

Unmodified
Added
Removed
  • doc/user/Makefile

    r09d1ad0 r6b6597c  
    1212
    1313FIGURES = ${addsuffix .tex, \
     14Cdecl \
    1415}
    1516
  • doc/user/user.tex

    r09d1ad0 r6b6597c  
    1111%% Created On       : Wed Apr  6 14:53:29 2016
    1212%% Last Modified By : Peter A. Buhr
    13 %% Last Modified On : Sun Apr 10 22:50:15 2016
    14 %% Update Count     : 72
     13%% Last Modified On : Thu Apr 14 21:30:07 2016
     14%% Update Count     : 130
    1515%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
    1616
     
    2626\usepackage{upquote}
    2727\usepackage{fullpage,times}
     28\usepackage{epic,eepic}
    2829\usepackage{xspace}
    2930\usepackage{varioref}
     
    4849% Names used in the document.
    4950
     51\newcommand{\Version}{1.0.0}
    5052\newcommand{\CS}{C\raisebox{-0.9ex}{\large$^\sharp$}\xspace}
    5153
     
    105107The syntax of the \CFA language builds from C, and should look immediately familiar to C programmers.
    106108% Any language feature that is not described here can be assumed to be using the standard C11 syntax.
    107 \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.
     109\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.
    108110Like C, \CFA is a statically typed, procedural language with a low-overhead runtime, meaning there is no global garbage-collection.
    109111The primary new features include parametric-polymorphism routines and types, exceptions, concurrency, and modules.
     
    224226
    225227
    226 \section{Compiling \CFA}
     228\section{Compiling \CFA Program}
    227229
    228230The command \lstinline@cfa@ is used to compile \CFA program(s).
     
    231233cfa [ gcc-options ] C/@{\CFA}@-files [ assembler/loader-files ]
    232234\end{lstlisting}
     235\index{cfa@\lstinline$cfa$}\index{compilation!cfa@\lstinline$cfa$}
    233236By default, \CFA programs having the following \lstinline@gcc@ flags turned on:
    234237\begin{description}
    235238\item
    236239\hspace*{-4pt}\lstinline@-std=gnu99@
     240\index{-std=gnu99@{\lstinline$-std=gnu99$}}\index{compilation option!-std=gnu99@{\lstinline$-std=gnu99$}}
    237241The 1999 C standard plus GNU extensions.
    238242\end{description}
     
    241245\item
    242246\hspace*{-4pt}\lstinline@-CFA@
     247\index{-CFA@{\lstinline$-CFA$}}\index{compilation option!-CFA@{\lstinline$-CFA$}}
    243248Only 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.
    244249\end{description}
     250
     251The following preprocessor variables are available:
     252\begin{description}
     253\item
     254\hspace*{-4pt}\lstinline$__CFA__$
     255\index{__CFA__@{\lstinline$__CFA__$}}\index{preprocessor variables!__CFA__@{\lstinline$__CFA__$}}
     256is always available during preprocessing and its value is the current major \Index{version number} of \CFA.\footnote{
     257The C preprocessor allows only integer values in a preprocessor variable so a value like ``\Version'' is not allowed.
     258Hence, the need to have three variables for the major, minor and patch version number.}
     259
     260\item
     261\hspace*{-4pt}\lstinline$__CFA_MINOR__$
     262\index{__CFA_MINOR__@{\lstinline$__CFA_MINOR__$}}\index{preprocessor variables!__CFA_MINOR__@{\lstinline$__CFA_MINOR__$}}
     263is always available during preprocessing and its value is the current minor \Index{version number} of \CFA.
     264
     265\item
     266\hspace*{-4pt}\lstinline$__CFA_PATCH__$
     267\index{__CFA_PATCH__@%(__CFA_PATCH__%)}\index{preprocessor variables!__CFA_PATCH__@%(__CFA_PATCH__%)}
     268is always available during preprocessing and its value is the current patch \Index{version number} of \CFA.
     269
     270\item
     271\hspace*{-4pt}\lstinline$__CFORALL__$
     272\index{__CFORALL__@%(__CFORALL__%)}\index{preprocessor variables!__CFORALL__@%(__CFORALL__%)}
     273is always available during preprocessing and it has no value.
     274\end{description}
     275
     276These preprocessor variables allow conditional compilation of programs that must work differently in these situations.
     277For example, to toggle between C and \CFA extensions, using the following:
     278\begin{lstlisting}
     279#ifndef __CFORALL__
     280#include <stdio.h>              // C header file
     281#else
     282#include <fstream>              // @\CFA{}@ header file
     283#endif
     284\end{lstlisting}
     285which conditionally includes the correct header file, if the program is compiled using \lstinline@gcc@ or \lstinline@cfa@.
    245286
    246287
     
    284325C declaration syntax is notoriously confusing and error prone.
    285326For example, many C programmers are confused by a declaration as simple as:
    286 \begin{lstlisting}
    287 int *x[ 10 ]
    288 \end{lstlisting}
    289 Is this a pointer to an array of 10 integers or an array of 10 pointers to integers?
     327\begin{quote2}
     328\begin{tabular}{@{}ll@{}}
     329\begin{lstlisting}[aboveskip=0pt,belowskip=0pt]
     330int *x[ 5 ]
     331\end{lstlisting}
     332&
     333\raisebox{-0.75\totalheight}{\input{Cdecl}}
     334\end{tabular}
     335\end{quote2}
     336Is this an array of 5 pointers to integers or a pointer to an array of 5 integers?
    290337Another 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.
    291338For example, a routine returning a pointer to an array of integers is defined and used in the following way:
    292339\begin{lstlisting}
    293 int (*f())[ 10 ] {...};
    294 ... (*f())[  3 ] += 1;  // definition mimics usage
     340int (*f())[ 5 ] {...};  // definition mimics usage
     341... (*f())[ 3 ] += 1;
    295342\end{lstlisting}
    296343Essentially, the return type is wrapped around the routine name in successive layers (like an onion).
     
    322369\multicolumn{1}{c@{\hspace{30pt}}}{\textbf{\CFA}}       & \multicolumn{1}{c@{\hspace{20pt}}}{\textbf{C}}        \\
    323370\begin{lstlisting}
    324 [ 10 ] int z;
    325 [ 10 ] * char w;
    326 * [ 10 ] double v;
     371[ 5 ] int z;
     372[ 5 ] * char w;
     373* [ 5 ] double v;
    327374struct s {
    328375        int f0:3;
    329376        * int f1;
    330         [ 10 ] * int f2;
     377        [ 5 ] * int f2;
    331378};
    332379\end{lstlisting}
    333380&
    334381\begin{lstlisting}
    335 int z[ 10 ];
    336 char *w[ 10 ];
    337 double (*v)[ 10 ];
     382int z[ 5 ];
     383char *w[ 5 ];
     384double (*v)[ 5 ];
    338385struct s {
    339386        int f0:3;
    340387        int *f1;
    341         int *f2[ 10 ]
     388        int *f2[ 5 ]
    342389};
    343390\end{lstlisting}
    344391&
    345392\begin{lstlisting}
    346 // array of 10 integers
    347 // array of 10 pointers to char
    348 // pointer to array of 10 doubles
     393// array of 5 integers
     394// array of 5 pointers to char
     395// pointer to array of 5 doubles
    349396
    350397// common bit field syntax
     
    362409\begin{lstlisting}
    363410const * const int x;
    364 const * [ 10 ] const int y;
     411const * [ 5 ] const int y;
    365412\end{lstlisting}
    366413&
    367414\begin{lstlisting}
    368415int const * const x;
    369 const int (* const y)[ 10 ]
     416const int (* const y)[ 5 ]
    370417\end{lstlisting}
    371418&
    372419\begin{lstlisting}
    373420// const pointer to const integer
    374 // const pointer to array of 10 const integers
     421// const pointer to array of 5 const integers
    375422\end{lstlisting}
    376423\end{tabular}
     
    382429\multicolumn{1}{c@{\hspace{30pt}}}{\textbf{\CFA}}       & \multicolumn{1}{c@{\hspace{20pt}}}{\textbf{C}}        \\
    383430\begin{lstlisting}
    384 extern [ 10 ] int x;
     431extern [ 5 ] int x;
    385432static * const int y;
    386433\end{lstlisting}
    387434&
    388435\begin{lstlisting}
    389 int extern x[ 10 ];
     436int extern x[ 5 ];
    390437const int static *y;
    391438\end{lstlisting}
    392439&
    393440\begin{lstlisting}
    394 // externally visible array of 10 integers
     441// externally visible array of 5 integers
    395442// internally visible pointer to constant int
    396443\end{lstlisting}
     
    421468\begin{lstlisting}
    422469y = (* int)x;
    423 i = sizeof([ 10 ] * int);
     470i = sizeof([ 5 ] * int);
    424471\end{lstlisting}
    425472&
    426473\begin{lstlisting}
    427474y = (int *)x;
    428 i = sizeof(int *[ 10 ]);
     475i = sizeof(int *[ 5 ]);
    429476\end{lstlisting}
    430477\end{tabular}
     
    466513\CFA style declarations cannot be used to declare parameters for K\&R style routine definitions because of the following ambiguity:
    467514\begin{lstlisting}
    468 int (*f(x))[ 10 ] int x; {}
    469 \end{lstlisting}
    470 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.
     515int (*f(x))[ 5 ] int x; {}
     516\end{lstlisting}
     517The 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.
    471518Since the strings overlap starting with the open bracket, \lstinline@[@, there is an ambiguous interpretation for the string.
    472519As well, \CFA-style declarations cannot be used to declare parameters for C-style routine-definitions because of the following ambiguity:
     
    487534\begin{lstlisting}
    488535#define ptoa( n, d ) int (*n)[ d ]
    489 int f( ptoa(p,10) ) ...         // expands to int f( int (*p)[ 10 ] )
    490 [ int ] f( ptoa(p,10) ) ...     // expands to [ int ] f( int (*p)[ 10 ] )
     536int f( ptoa(p,5) ) ...          // expands to int f( int (*p)[ 5 ] )
     537[ int ] f( ptoa(p,5) ) ...      // expands to [ int ] f( int (*p)[ 5 ] )
    491538\end{lstlisting}
    492539Again, programmers are highly encouraged to use one declaration form or the other, rather than mixing the forms.
     
    807854which can be used to sort in ascending and descending order by locally redefining the less-than operator into greater-than.
    808855\begin{lstlisting}
    809 const unsigned int size = 10;
     856const unsigned int size = 5;
    810857int ia[size];
    811858...                                             // assign values to array ia
     
    874921[ double, double, double ]
    875922[ * int, int * ]                // mix of CFA and ANSI
    876 [ * [ 10 ] int, * * char, * [ [ int, int ] ] (int, int) ]
     923[ * [ 5 ] int, * * char, * [ [ int, int ] ] (int, int) ]
    877924\end{lstlisting}
    878925Like 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.
     
    22162263
    22172264        try {
    2218         throw 13;
     2265                throw 13;
    22192266        }
    22202267        catch(int e) {
    2221         printf(.caught an exception: %d\n., e);
     2268                printf(.caught an exception: %d\n., e);
    22222269        }
    22232270\end{lstlisting}
Note: See TracChangeset for help on using the changeset viewer.