\documentclass[noanswers,addpoints,x11names,11pt]{exam}
\usepackage[xetex,text={6.5in,9in},centering]{geometry}
\usepackage{amsmath}
\usepackage{amssymb}
\usepackage{caption2}
\usepackage{soul}
\usepackage{xcolor}
\usepackage[most]{tcolorbox}
\usepackage{datetime}
\usepackage{enumerate}
\usepackage{xltxtra}

\usepackage{graphicx}
\usepackage[xetex]{hyperref}
\usepackage{makecell}
\usepackage{multicol}
\usepackage{multirow}

\usepackage{enumitem}
% compact itemized and then enumerated
\setlist{leftmargin=*,
  noitemsep,
  topsep=5pt,
  parsep=0pt,
  partopsep=0pt,
}

\setlist[enumerate]{leftmargin=*,
  itemsep=2pt,
  topsep=0pt,
  parsep=0pt,
  partopsep=0pt,
}

\setlist[description]{leftmargin=*,
  itemsep=2pt,
  topsep=0pt,
  parsep=0pt,
  partopsep=0pt,
}

\usepackage{tabu}
\usepackage{textcomp}
\usepackage{tikz}
\usetikzlibrary{arrows,automata,decorations.pathmorphing,backgrounds,positioning,fit}
\usepackage{pgf-umlcd}

\usepackage{fontspec}
\IfFontExistsTF{Gentium Book Plus}{
  \setmainfont{Gentium Book Plus}
}{
  \setmainfont{Times New Roman}
}

\IfFontExistsTF{Comic Code}{
  \setmonofont{Comic Code}[
  Scale = 0.85,
  ]
}{
}

\usepackage{float}
\usepackage{listings}
\lstset{
  basicstyle=\ttfamily,
  numberstyle=\footnotesize,
  language=java,
}

\newcommand{\checkpoint}{{\Large $\checkmark$} }

% classname
\newcommand{\semester}{Spring 2025}
\newcommand{\className}{CS III}
\newcommand{\classNumber}{CIS~205}
\newcommand{\classFullName}{\classNumber~\className}

\newcommand{\assignmentNumber}{01}
\newcommand{\assignmentName}{WordCount}
\newcommand{\assignmentDescription}{Implementing \texttt{wc} in Java}

\newcommand{\assignmentTitle}{\texttt{p\assignmentName} --- \assignmentDescription}

\newcommand{\gitRepoName}{p\assignmentNumber-\assignmentName}

\renewcommand{\dateseparator}{-}
\yyyymmdddate

% /classname

\pagestyle{headandfoot}
\firstpageheader{\classFullName\\\semester}{\assignmentName\\~}{\today\\~}
\runningheader{\assignmentName}{}{\today}

\newenvironment{showExample}[1]{
  \begingroup
  \renewcommand{\solutiontitle}{\noindent\textbf{Example:}\enspace}
  \printanswers
  \begin{solution}[#1]
  }{
  \end{solution}
  \endgroup
}

\definecolor{javafile}{rgb}{0.90, 0.87, 0.7}
\definecolor{inputfile}{rgb}{1.0, 0.7, 0.6}
\definecolor{configfile}{rgb}{0.75, 0.84, 0.66}
\definecolor{outputlisting}{rgb}{0.66, 0.75, 0.84}

\def\changemargin#1#2{\list{}{\rightmargin#2\leftmargin#1}\item[]}
\let\endchangemargin=\endlist

\begin{document}
\pointsinrightmargin{}

\begin{center}
  \textbf{\assignmentTitle{}}
\end{center}

\noindent
This assignment's \textbf{repo name} is \texttt{\gitRepoName}


\section*{Learning Outcomes}
After completing this assignment, a student should be able to
\begin{itemize}
\item \textbf{Implement} an ``instantiate-run'' Java program.
\item \textbf{Separate} concerns by using multiple java
  \lstinline{package}s.
\item \textbf{Use} the \lstinline{classpath} for multiple packages.
\item (Review) \textbf{Process} \emph{command-line arguments} -- checking the
  number, treating them as file names.
\item (Review) \textbf{Read} a text file \emph{by line}.
\item (Review) \textbf{Use} a \lstinline{Scanner} to parse a \lstinline{String}.
\item (Review) \textbf{Document} how to \emph{compile} and \emph{run}
  the program as well as how it was tested.
\end{itemize}

\section*{Overview}
Linux (Unix) has a utility program called \lstinline{wc},
\lstinline{w}ord \lstinline{c}ount, that counts the number of lines,
words, and characters in any number of files named on the
command-line.

Students will implement a simplified version in Java:
\lstinline{WordCount} will

\begin{itemize}
\item \emph{Verify} that there is exactly one (1) command-line
  argument; if there is a different number, program should terminate
  with an appropriate error message and a return code of 1.
\item \emph{Open} the named file for input; if the file does not exist
  then the program should terminate with an appropriate error message
  and a return code of 2. (\textbf{Notice} the error codes would
  permit the operating system to tell the difference between different
  abnormal terminations.)
\item \emph{Read} the input file by \textbf{line}, processing each
  line to count the number of \emph{words} and \emph{characters}. The
  program tracks the number of lines, words, and characters
  (remembering to count the end-of-line characters).
\item \emph{Print} the name of the file along with the various
  counts. The following output is for the provided
  \lstinline{LineReportInterface.java} file. The results of
  \lstinline{wc} on the same file are shown afterwards for comparison.

\begin{lstlisting}[backgroundcolor=\color{outputlisting},language={}]
$ java <class path stuff> WordCount LineReportInterface.java
  LineReportInterface.java:
    lines: 22
    words: 89
    chars: 566
$ wc LineReportInterface.java
   22  89 566 LineReportInterface.java
\end{lstlisting}
\end{itemize}

Define ``word'' as any collection of whitespace separated
non-whitespace characters. This is the same definition used by
\lstinline{Scanner.next()} (how convenient).

\textbf{Note:} ``terminate normally'' means to end with the program
returning the value 0 to the operating system; this is what Java does
whenever you run off of \lstinline{main} \textbf{or} call
\lstinline{System.exit(0)}. The other two termination conditions
described above are ``abnormal''; that can be signaled to the
operating system by exiting with a non-zero return code. That requires
using \lstinline{System.exit(<non-zero>)}.

\section*{Procedure}
\begin{questions}
\question{} Read the \textbf{whole} assignment. This is important for
  \emph{every} assignment: it puts the task into your brain so that it
  can begin working on answering the questions. Of particular interest
  when you read are the SLO (first section above); gives you the links
  between the assignment to the big picture (learning computer
  science).

\question{} Before writing any code: create a \emph{project} root
  directory. Initialize \lstinline{git} in the root, put in a
  \lstinline{.gitignore} file, and add a beginning
  \lstinline{README}. Something like this is the first step of every
  program you will turn in during the semester.

\question{} Set up your \emph{packages}. \textbf{Abstraction} is an
  important part of computer programming: the separation of concerns
  into small, single-concern \emph{functions} or \emph{classes} means
  that while programming one element you are protected from the
  details of any other part.

  This \textbf{separation of concerns} extends beyond the
  \lstinline{class}, into a \lstinline{package} of related
  classes. For example, a modern video game might have six
  \emph{thousand} source files. To make navigating and debugging so
  much code it is typically broken up into packages like
  \lstinline{sound}, \lstinline{video}, \lstinline{gameplay},
  \lstinline{networking}, \emph{etc.}

  This assignment breaks up into two major areas of concern: file
  handling (checking number of file names, opening file, reading file
  by line, all the errors) and line processing (counting words and
  (much easier) characters).

  In Java a \lstinline{package} corresponds to a \emph{directory}.
  Just as the \lstinline{class} \lstinline{Snoopy} must be in the file
  named \lstinline{Snoopy.java}, if that class's full name is
  \lstinline{peanuts.Snoopy}, it belongs in the file named
  \lstinline{peanuts/Snoopy.java}.

  With two distinct areas of concern, this program will have two
  packages:

\begin{lstlisting}[backgroundcolor=\color{outputlisting}]
<project-root>
|-- application
`-- counter
\end{lstlisting}

  Notice that the \lstinline{<project-root>} is where ever you put
  your code in your directory structure. The subdirectories should
  to be named exactly as shown.

  As has been discussed in class, this project will be \emph{run} from
  the project-root. This means using the \lstinline{--class-path}
  command-line argument for \lstinline{java}/\lstinline{javac}.

  You \textbf{will} document this in your \lstinline{README} file.

\question{} \textbf{Sketch} an \emph{instantiate-run} (all our
  programs from this point forward will have this ``shape'') solution
  to the overall problem from the top, down. Here, top means
  \lstinline{main} and down means moving to simpler and simpler
  methods.

  Remember to keep each method focused on exactly \emph{one}
  responsibility. You can even use that responsibility to write the
  header comment for the method.

  \begin{parts}
  \part{} Possible sketch of \lstinline{main}:

\begin{lstlisting}[backgroundcolor=\color{javafile},float=h]
// application.WordCount.main
// responsibility: verify number of command-line arguments
check number of command-line parameters
if ! exactly one parameter
  print usage message
  terminate with non-zero value

construct WordCount(file name)
call WordCount.run
\end{lstlisting}

  \noindent
  The sketch shows where one possible error is handled. It is
  therefore possible to write just the \lstinline{main} function and
  test it \emph{before} even implementing the word counting or line
  processing.

\part{} Possible sketch of \lstinline{WordCount} constructor:
\begin{lstlisting}[backgroundcolor=\color{javafile}]
// application.WordCount.WordCount
// responsibility: capture the filename, initialize counts
save file name into an object field
initialize the three counts in object fields
\end{lstlisting}

  \noindent
  This is a very simple function; \lstinline{run} will open the file
  and handle any corresponding errors. Separation of concerns makes
  functions simple.

\part{} Possible sketch of \lstinline{WordCount.run}:

\begin{lstlisting}[backgroundcolor=\color{javafile},float=h]
// application.WordCount.run
// responsibility: open file or handle errors
try
  open named file into a scanner

  process the file for the scanner

  print the results
catch FileNotFoundException
  print appropriate error message
  terminate with non-zero value
\end{lstlisting}
\begin{lstlisting}[backgroundcolor=\color{javafile},float=h]
// application.WordCount.processFile
// responsibility: read file by line; process each line
while file has a next line
  read line
  get a LineReportInterface on the line
  update all three counts
\end{lstlisting}

  \noindent
  Did you catch that? Two new classes introduced, bringing the total
  to three:



  \begin{description}[nosep,style=unboxed,font=\ttfamily]
  \item[application.WordCount]

    The class containing \lstinline{main} and \lstinline{run}. It is
    in its own package.
  \item[count.WordCount]
    Associate  word (\lstinline{String}) paired with its count
    (\lstinline{int}). It will implement the
    \lstinline{WordCountInterface} (which is provided in the
    \lstinline{src} folder; you will need to put it in the correct
    package):


    \noindent
    You may, of course, write any other \emph{private} functions you
    wish in \lstinline{WordCount}. Except when calling the
    \emph{constructor} you \textbf{must} use the \lstinline{interface} in all
    other classes.

    Look carefully at \lstinline{WordCountInterface}: there are no
    \lstinline{set*} methods. Think, for a minute, about why they are
    not needed (or \emph{wanted}).

    \noindent
    \ldots{}

    Since a \lstinline{WCI} (\lstinline{WordCountInterface}) object
    represents a \lstinline{<word, count>} pair, it seems obvious that
    after creation there is no reason to \emph{change} the word. What
    would it even mean to count the number of times \lstinline{snake}
    appears in some sequence of words and then change the word to
    \lstinline{chicken}?

    Similarly, changing the count by setting it to a smaller number or
    incrementing it by more than one does not seem to fit the software
    model we are building of the contents of the file.

    So the interface permits incrementing an existing \lstinline{WCI}
    (when we see another instance of the word), checking if the
    \lstinline{WCI} contains a given word, and to return a
    \lstinline{String} representation of the \lstinline{WCI}.

    The two \lstinline{get*} methods are there for testing/debugging. They
    \emph{are} used in the provided\\
    \lstinline{WordCountTestHarness.java} program; they are not needed
    in any other programs or classes.

  \item[list.WordList]

    A \emph{list} of \lstinline{WCI} objects. Limiting access to the
    \emph{interface} means that the list is implementation
    \textbf{agnostic} (it uses no knowledge about the implementation
    outside of the constructor call). Changing to a different
    implementation of the interface would not require more than a new
    \lstinline{import} and recompiling the list with a call to the
    different constructor.

    \newpage


    The interface expects list-like \emph{behavior} but does not specify how
    the list is to be \emph{implemented}. This \textbf{assignment} requires
    that \lstinline{WordList} be implemented as a linked-list where the data
    in each node is the \lstinline{WCI} object for some
    word.
  \end{description}

\part{} Assume the given interfaces are correctly implemented. Use
  \lstinline{WordListInterface} to expand the sketch of
  \lstinline{WordCount.run}. Once you read a word, how do you use
  the list object to determine whether to add it to the end or
  increment the existing entry.

  What does the list printing code look like?
\end{parts}

\question{} \emph{Incremental development} (also sometimes referred to
  as \emph{spiral development}) is the practice of building a program
  one small feature at a time. Figure out what the next feature should
  do and how you would verify that it works. Compile and test until it
  works and check the feature into version control
  (\lstinline{git}). Lather, rinse, and repeat.


  \noindent
  One path to solving this assignment would be:

  \begin{itemize}[nosep]
  \item \lstinline{application.WordCount.main} empty and
    compiling.
  \item \lstinline{main} checks number of arguments.
  \item \lstinline{WordCount} constructor that takes a
    \lstinline{String} (file name).
  \item \lstinline{run} exists.
  \item \lstinline{main} completed with construction and call to
    \lstinline{run}.
  \item \lstinline{run} opens the file or reports error.

  \item Get \lstinline{WordCount} working. Before you even get
    \lstinline{WordList} working, \lstinline{WordCountTestHarnes} can
    run unit tests\footnote{A \emph{unit test} is a test run on a
      ``unit'' of a program, the very smallest testable part of the
      code. Here it is a \emph{class} and the public \emph{methods} it
    exposes. Unit testing will be a major part of your programming
    this semester.} on \lstinline{WordCount}.

    \rule{0.9\textwidth}{1pt}

    \noindent
    Seven steps in and the code does almost nothing. \textbf{But}, the
    foundation for the program is laid. Now it is time to write the
    linked-list and its functions. You can decide on the order of
    implementation for them.

    \rule{0.9\textwidth}{1pt}

  \item Get \lstinline{WordList} working. Can be initially tested with
    \lstinline{WordListTestHarness}.
  \item Hook processing each word to adding it to a
    \lstinline{WordListInterface} object. Add the printing.
  \item \textbf{Test} the finished program. Make sure you see all the
    errors that come from the command-line in your testing (and only
    when you expect them).

    Make sure to \emph{document} your testing with what you expected,
    what you did, and what the results were. That goes in the
    \lstinline{README}.
  \end{itemize}



\question{} \emph{Testing} is important. The \lstinline{data}
  directory in this assignment has several files that you can
  run the program on. An example run (with the first few lines of
  output) is:\footnote{The execution line is stripped down to just
    show the name of the Java object with \texttt{main} in it. Assume
    that the correct \texttt{classpath} was specified.}

\begin{lstlisting}[backgroundcolor=\color{outputlisting}]
java WordCount data/oneFish.txt
One : 1
fish, : 7
Two : 1
Red : 1
Blue : 2
Black : 1
Old : 1
New : 1
fish. : 1
This : 2
one : 4
has : 3
a : 6
little : 2
  ...
\end{lstlisting}

Take a look at the data file and see if you believe that of the 207
words in \lstinline{oneFish.txt}, there are only 117 \emph{distinct}
words.\footnote{How to figure those two numbers: Linux has a utility
  called \texttt{wc} (for \emph{word count}). It give the number of
  lines, words, and characters in a file provided on the command
  line. That is where the 207 came from. The other comes from the
  number of lines that the sample solution produces when run.} Also
note that the order of the list is the order in the file of the
distinct words.

  You may want to think about what the output should look like before
  you program because if you \emph{cannot} describe the correct
  output, it is unlikely that you understand the problem well enough
  to program the correct output.

  You may want to develop some even shorter test data for quick
  feedback.

\question{}
  \noindent
  This assigment's \textbf{repo name} is \texttt{\gitRepoName}

  Commit your finished work (including \lstinline{README} w/ all your
  documentation) to your local \lstinline{git} repository. Then
  connect the local database to an on-line database on the Gitea
  server and \lstinline{push} the conents.

  The \emph{departmental} \lstinline{git} server, running Gitea
  software (hence our referring to it as the ``Gitea server'') is at
  \url{https://cs-devel.potsdam.edu}. Log in to your account.

  You created the \lstinline{F24-205-<CCID>}\footnote{\texttt{CCID} -- Campus Computer
    ID; your campus e-mail address w/o \texttt{\@potsdam.edu}.}
  organization in the first lab this semester. In it you will create a
  new, \textbf{private} \emph{repository} with the name
  \texttt{\gitRepoName}. Gitea will respond with a set of commands to
  connect a local repo to the newly created one on the server. Use
  them to connect the repos and push your program.

  If, after you do this, you change your \emph{local} repo contents,
  you will just need to rerun the \lstinline{push} command to copy the
  changes up to the server. Dr. Ladd will retrieve your code from
  Gitea for grading. Remember that commits are \emph{timestamped};
  don't commit things after they are due. Pushing the database is
  separate from the \lstinline{commit} operation; if it happens to be
  ``late'', as long as the commit is before the due time, all is well.

  The Gitea repository name is \textbf{specified} (and has nothing to
  do with local directory names) so that Dr. Ladd can automate
  harvesting all the repos for grading. Thanks for your consideration.
\end{questions}
\end{document}

%%% Local Variables:
%%% mode: latex
%%% TeX-master: t
%%% End:
