Changeset e71b09a

Timestamp:

Jan 31, 2024, 12:14:17 PM (3 months ago)

Author:

Peter A. Buhr <pabuhr@…>

Branches:

master

Children:

32490deb

Parents:

3da5885

Message:

more word-smithing

File:

• doc/user/user.tex (modified) (14 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 Jan 28 13:28:23 2024
-%% Update Count     : 5979
+%% Last Modified On : Tue Jan 30 09:02:41 2024
+%% Update Count     : 6046
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
@@ -4148 +4148 @@
 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 matches the variable's type.
-Explicit formatting means additional information is specified to augment how an output or input of value is interpreted.
+Implicit formatting means \CFA selects an I/O format for values that matches a variable's type.
+Explicit formatting means additional I/O information is specified to control how a value is interpreted.
+
 \CFA formatting incorporates ideas from C ©printf©, \CC ©stream© manipulators, and Python implicit spacing and newline.
 Specifically:
@@ -4157 +4158 @@
 \CFA/\CC format manipulators are named, making them easier to read and remember.
 \item
-©printf©/Python separates format codes from associated variables, making it difficult to match codes with variables.
+©printf©/Python separate format codes from associated variables, making it difficult to match codes with variables.
 \CFA/\CC co-locate codes with associated variables, where \CFA has the tighter binding.
 \item
-Format manipulators in \CFA have local effect, whereas \CC have global effect, except ©setw©.
-Hence, it is common programming practice to toggle manipulators on and then back to the default to prevent downstream side-effects.
+Format manipulators in ©printf©/Python/\CFA have local effect, whereas \CC have global effect, except ©setw©.
+Hence, it is common \CC 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.
 Furthermore, to guarantee no side-effects, manipulator values must be saved and restored across function calls.
+\CC programers never do any of this.
 \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.
+
+\subsection{Basic I/O}
+
+The standard polymorphic I/O streams are ©stdin©/©sin© (input), ©stdout©/©sout©, and ©stderr©/©serr© (output) (like C++ ©cin©/©cout©/©cerr©).
+The standard I/O operator is the bit-wise (or) operator, ©'|'©, which is used to cascade multiple I/O operations.
 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.
@@ -4222 +4218 @@
 1®, ®2®, ®3 4®, ®5®, ®6
 \end{cfa}
-Finally, \CFA uses the logical-or operator for I/O as it is the lowest-priority \emph{overloadable} operator, other than assignment.
+The bit-wise ©|© operator is used for I/O, rather \CC shift-operators, ©<<© and ©>>©, as it is the lowest-priority \emph{overloadable} operator, other than assignment.
+(Operators ©||© and ©&&© are not overloadable in \CFA.)
 Therefore, fewer output expressions require parenthesis.
 \begin{cquote}
@@ -4245 +4242 @@
 \end{cquote}
 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.
-Input and output use a uniform operator, ©|©, rather than \CC's ©<<© and ©>>© input/output operators, which prevents this common error in \CC:
+Input and output use a uniform operator, ©|©, rather than \CC's ©<<© and ©>>© input/output operators to prevent this common error in \CC:
 \begin{C++}
 cin << i; // why is this generating a lot of error messages?
 \end{C++}
+
+Streams ©exit© and ©abort© provide output with immediate 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.";     §\C{// print, terminate, and return EXIT\_FAILURE to shell}§
+®abort® | "x (" | x | ") negative value.";      §\C{// print, 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.
 
 For implicit formatted input, the common case is reading a sequence of values separated by whitespace, where the type of an input constant must match with the type of the input variable.
@@ -4291 +4296 @@
 \end{tabular}
 \end{cquote}
-
-\VRef[Figure]{f:CFACommand-LineProcessing} shows idiomatic \CFA command-line processing and copying an input file to an output file.
+The format of numeric input values in the same as C constants without a trailing type suffix, as the input value-type is denoted by the input variable.
+For ©bool© type, the constants are ©true© and ©false©.
+For integral types, any number of digits, optionally preceded by a sign (©+© or ©-©), where a
+\begin{itemize}
+\item
+©1©-©9© prefix introduces a decimal value (©0©-©9©),
+\item
+©0© prefix introduces an octal value (©0©-©7©), and
+\item
+©0x© or ©0X© prefix introduces a hexadecimal value (©0©-©f©) with lower or upper case letters.
+\end{itemize}
+For floating-point types, any number of decimal digits, optionally preceded by a sign (©+© or ©-©), optionally containing a decimal point, and optionally followed by an exponent, ©e© or ©E©, with signed (optional) decimal digits.
+Floating-point values can also be written in hexadecimal format preceded by ©0x© or ©0X© with hexadecimal digits and exponent denoted by ©p© or ©P©.
+In all cases, all whitespace characters are skipped until an appropriate value is found.
+\Textbf{If an appropriate value is not found, the exception ©missing_data© is raised.}
+
+For the C-string type, there are two input forms: any number of \Textbf{non-whitespace} characters or a quoted sequence containing any characters except the closing quote, \ie there is no escape character supported in the string..
+In both cases, the string is null terminated ©'\0'©.
+For the quoted string, the start and end quote characters can be any character and do not have to match \see{\ref{XXX}}.
+
+\VRef[Figure]{f:IOStreamFunctions} shows the I/O stream operations for interacting with files other than ©cin©, ©cout©, and ©cerr©.
+\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) writes ©size© bytes to the stream.
+The bytes are written lazily when an internal buffer fills.
+Eager buffer writes are done with ©flush©
+\item
+\Indexc{read} (©ifstream© only) reads ©size© bytes from 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{I/O Stream Functions}
+\label{f:IOStreamFunctions}
+\end{figure}
+
+\VRef[Figure]{f:CFACommand-LineProcessing} demonstrates the file operations by showing the 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.
+\Textbf{All I/O errors are handled as exceptions}, but end-of-file is not an exception as C programmers are use to explicitly checking for it.
 
 \begin{figure}
@@ -4335 +4422 @@
 \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) writes ©size© bytes to the stream.
-The bytes are written lazily when an internal buffer fills.
-Eager buffer writes are done with ©flush©
-\item
-\Indexc{read} (©ifstream© only) reads ©size© bytes from 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}
-
 
 \subsection{Implicit Separator}
 
 The \Index{implicit separator}\index{I/O!separator} character (space/blank) is a separator not a terminator for output.
-The rules for implicitly adding the separator are:
+The rules for implicitly adding a separator are:
 \begin{enumerate}
 \item
@@ -4438 +4458 @@
 \end{cfa}
 \begin{cfa}[showspaces=true]
-1®,® x 2®.® x 3®;® x 4®!® x 5®?® x 6®%® x 7§\R{\LstStringStyle{\textcent}}§ x 8§\R{\LstStringStyle{\guillemotright}}§ x 9®)® x 10®]® x 11®}® x
+Input1®,® x 2®.® x 3®;® x 4®!® x 5®?® x 6®%® x 7§\R{\LstStringStyle{\textcent}}§ x 8§\R{\LstStringStyle{\guillemotright}}§ x 9®)® x 10®]® x 11®}® x
 \end{cfa}
 
@@ -4653 +4673 @@
 
 
-\subsection{Output Value Manipulators}
+\subsection{Output Manipulators}
 
 The following \Index{manipulator}s control formatting (printing) of the argument output values.
@@ -4911 +4931 @@
 
 
-\subsection{Input Value Manipulators}
-
-The format of numeric input values in the same as C constants without a trailing type suffix, as the input value-type is denoted by the input variable.
-For ©bool© type, the constants are ©true© and ©false©.
-For integral types, any number of digits, optionally preceded by a sign (©+© or ©-©), where a
-\begin{itemize}
-\item
-©1©-©9© prefix introduces a decimal value (©0©-©9©),
-\item
-©0© prefix introduces an octal value (©0©-©7©), and
-\item
-©0x© or ©0X© prefix introduces a hexadecimal value (©0©-©f©) with lower or upper case letters.
-\end{itemize}
-For floating-point types, any number of decimal digits, optionally preceded by a sign (©+© or ©-©), optionally containing a decimal point, and optionally followed by an exponent, ©e© or ©E©, with signed (optional) decimal digits.
-Floating-point values can also be written in hexadecimal format preceded by ©0x© or ©0X© with hexadecimal digits and exponent denoted by ©p© or ©P©.
-
-For the C-string type, the input values are \emph{not} the same as C-string constants, \ie double quotes bracketing arbitrary text with escape sequences.
-Instead, the next sequence of non-whitespace characters are read, and the input sequence is terminated with delimiter ©'\0'©.
-The string variable \emph{must} be large enough to contain the input sequence.
+\subsection{Input Manipulators}
+
+The following \Index{manipulator}s control scanning of input values (reading), and only affect the format of the argument.
+
+Certain manipulators support a \newterm{scanset}, which is a simple regular expression, where the matching set contains any Latin-1 character (8-bits) or character ranges using minus.
+For example, the scanset \lstinline{"a-zA-Z -/?§"} matches any number of characters between ©'a'© and ©'z'©, between ©'A'© and ©'Z'©, between space and ©'/'©, and characters ©'?'© and (Latin-1) ©'§'©.
+The following string is matched by this scanset:
+\begin{cfa}
+!&%$  abAA () ZZZ  ??  xx§\S\S\S§
+\end{cfa}
+To match a minus, put it as the first character, ©"-0-9"©.
+Other complex forms of regular-expression matching are not supported.
+
+A string variable \emph{must} be large enough to contain the input sequence.
 To force programmers to consider buffer overruns for C-string input, C-strings can only be read with a width field, which should specify a size less than or equal to the C-string size, \eg:
 \begin{cfa}
@@ -4936 +4951 @@
 \end{cfa}
 
-A scanset is a simple regular expression, where the matching set contains any Latin-1 character (8-bits) or character ranges using minus.
-For example, the scanset \lstinline{"a-zA-Z -/?§"} matches characters between ©'a'© and ©'z'©, between ©'A'© and ©'Z'©, between space and ©'/'©, and characters ©'?'© and (Latin-1) ©'§'©.
-The following string is matched by this scanset:
-\begin{cfa}
-!&%$  abAA () ZZZ  ??  xx§\S\S\S§
-\end{cfa}
-To match a minus, put it as the first character, ©"-0-9"©.
-Other complex forms of regular-expression matching are not supported.
-
-The following \Index{manipulator}s control scanning of input values (reading), and only affect the format of the argument.
+Currently, there is no mechanism to detect if a value read exceeds the capwhen Most types are finite sized, \eg integral types only store value that fit into their corresponding storage, 8, 16, 32, 64, 128 bits.
+Hence, an input value may be too large, and the result of the read is often considered undefined, which leads to difficlt to locate runtime errors.
+All reads in \CFA check if values do not fit into the argument variable's type and raise the exception 
+All types are
+
 \begin{enumerate}
 \item
-\Indexc{skip}( pattern )\index{manipulator!skip@©skip©}, ©skip©( length )
-The pattern is composed of white-space and non-white-space characters, where \emph{any} white-space character matches 0 or more input white-space characters (hence, consecutive white-space characters in the pattern are combined), and each non-white-space character matches exactly with an input character.
-The length is composed of the next $N$ characters, including the newline character.
+\Indexc{skip}( scanset )\index{manipulator!skip@©skip©}, ©skip©( $N$ )
+The first form uses a scanset to skip matching characters.
+The second form skips the next $N$ characters, including newline.
 If the match successes, the input characters are discarded, and input continues with the next character.
 If the match fails, the input characters are left unread.
@@ -4964 +4974 @@
 
 \item
-\Indexc{wdi}( maximum, reference )\index{manipulator!wdi@©wdi©}
-For all types except ©char *©, maximum is the maximum number of characters read for the current operation.
+\Indexc{wdi}( maximum, variable )\index{manipulator!wdi@©wdi©}
+For all types except ©char *©, whitespace is skipped until an appropriate value is found for the specified variable type.
+maximum is the maximum number of characters read for the current operation.
 \begin{cfa}[belowskip=0pt]
 char ch;   char ca[3];   int i;   double d;   
-sin | wdi( sizeof(ch), ch ) | wdi( sizeof(ca), ca[0] ) | wdi( 3, i ) | wdi( 8, d );  // c == 'a', ca = "bcd", i == 123, d == 345.6
+sin | wdi( sizeof(ch), ch ) | wdi( sizeof(ca), ca[0] ) | wdi( 3, i ) | wdi( 8, d );  // c == 'a', ca == "bcd", i == 123, d == 345.6
 \end{cfa}
 \begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
@@ -4977 +4988 @@
 Note, input ©wdi© cannot be overloaded with output ©wd© because both have the same parameters but return different types.
 Currently, \CFA cannot distinguish between these two manipulators in the middle of an ©sout©/©sin© expression based on return type.
+
+\item
+\Indexc{wdi}( maximum size, ©char s[]© )\index{manipulator!wdi@©wdi©}
+For type ©char *©, maximum is the maximum number of characters read for the current operation.
+Any number of non-whitespace characters, stopping at the first whitespace character found. A terminating null character is automatically added at the end of the stored sequence
+\begin{cfa}[belowskip=0pt]
+char cstr[10];
+sin | wdi( sizeof(cstr), cstr );
+\end{cfa}
+\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
+®abcd1233.456E+2®
+\end{cfa}
+
+\item
+\Indexc{wdi}( maximum size, maximum read, ©char s[]© )\index{manipulator!wdi@©wdi©}
+For type ©char *©, maximum is the maximum number of characters read for the current operation.
+\begin{cfa}[belowskip=0pt]
+char ch;   char ca[3];   int i;   double d;   
+sin | wdi( sizeof(ch), ch ) | wdi( sizeof(ca), ca[0] ) | wdi( 3, i ) | wdi( 8, d );  // c == 'a', ca == "bcd", i == 123, d == 345.6
+\end{cfa}
+\begin{cfa}[showspaces=true,aboveskip=0pt,belowskip=0pt]
+®abcd1233.456E+2®
+\end{cfa}
 
 \item
@@ -5013 +5047 @@
 \end{cfa}
 
+\Indexc{quoted}( char delimit, wdi-input-string )\index{manipulator!quoted@©quoted©}
+Is an ©excl© with scanset ©"delimit"©, which consumes all characters up to the delimit character.
+If the delimit character is omitted, it defaults to ©'\n'© (newline).
+
 \item
 \Indexc{getline}( char delimit, wdi-input-string )\index{manipulator!getline@©getline©}
-Is an @excl@ with scanset ©"delimit"©, which consumes all characters up to the delimit character.
+Is an ©excl© with scanset ©"delimit"©, which consumes all characters up to the delimit character.
 If the delimit character is omitted, it defaults to ©'\n'© (newline).
 \end{enumerate}