\documentstyle[fullpage]{article}

\input{psfig}
\title{Fields.o --- Easy line and word processing of input}
\author{James S. Plank}
\begin{document}
\maketitle

{\tt Fields.o} defines and implements a data structure that simplifies
input processing in C.  The data structure consists of a type definition
and four procedure calls.  All are defined in {\tt fields.h}:

\centerline{}
\centerline{\psfig{figure=fields.eps}}

To use {\tt fields.o}, you must include {\tt fields.h} in your C program,
and compile it with {\tt fields.o}.  To read a file with {\tt fields.o}
you call {\tt new\_inputstruct()} on that file.  {\tt New\_inputstruct()}
takes a file name as its argument ({\tt NULL} for standard input), and
returns an {\tt IS} as a result.  If it cannot open the file, it
will return {\tt NULL}.  

Once you have an {\tt IS}, you call {\tt get\_line()} on it to read a line.
{\tt Get\_line()} changes the state of the {\tt IS} to reflect the 
reading of the line.  Specifically:
\begin{itemize}
\item It puts the contents of the line in {\tt text1}.
\item It breaks up the line into words.  The {\tt NF} field contains
      the number of words in the field.  The first {\tt NF} slots
      of the {\tt fields} array point to each of the {\tt NF} words
      (and these words are null-terminated).
\item The {\tt line} field contains the line number of the line.
\item {\tt get\_line()} returns the {\tt NF} field as its return value.
      It returns -1 when it reaches the end of the file.
\end{itemize}
{\tt Jettison\_inputstruct()} closes the file associated with the {\tt IS}
and deallocates the {\tt IS}.  Do not worry about {\tt pipe\_inputstruct()} 
for now. 

These procedures are very convenient for processing input files.  For
example, the following program (in {\tt printwords.c}) 
prints out every word of an input file prepended with its line number.

\centerline{}
\centerline{\psfig{figure=printwords.eps}}

So, for example, if the file {\tt rex.in} contains the following three
lines:

\centerline{}
\centerline{\psfig{figure=rexin.eps}}

Then running {\tt printwords} on {\tt rex.in} results in the following output:

\centerline{}
\centerline{\psfig{figure=rexout.eps}}

One important thing to note about {\tt fields.o} is that {\em only}
{\tt new\_inputstruct()} calls {\tt malloc()}.  {\tt Get\_line()} 
simply fills in the fields of the {\tt IS} structure --- it does {\em not}
perform memory allocation.  Therefore, suppose you wanted to print out
the first word on the second-to-last line.  The
following program ({\tt badword.c}) would not work:

\centerline{}
\centerline{\psfig{figure=badword.eps}}

Why?  Look at what happens when you execute it on {\tt rex.in}:

\centerline{}
\centerline{\psfig{figure=badout.eps}}

It prints ``{\tt June:}'' instead of ``{\tt Rex:}'' because {\tt get\_line()}
does not allocate any new memory.  Both {\tt penultimate\_word} and {\tt
last\_word} end up pointing to the same thing.  Make sure you understand
this example, because you can get yourself into a mess of trouble otherwise.
The correct version of the program is in {\tt goodword.c}: (note that this
is a very inefficient program because of all the {\tt strdup()} and 
{\tt free()} calls.  You could do better if you wanted to).

\centerline{}
\centerline{\psfig{figure=goodword.eps}}

{\tt Field.o} assumes that all input lines are less than 1000 characters.

\end{document}
