<WRAP centeralign round box>
<WRAP><color red><fs 200%>Corning Community College</fs></color></WRAP>
<WRAP><fs 150%>CSCS1320 C/C++ Programming</fs></WRAP>
</WRAP>

~~TOC~~

======Project: PIPE MATH======

=====Objective=====
To gain experience working on a collaborative project, developing the first version of tools that will be used together in various combinations in an interconnected manner.

=====Background=====
In UNIX, everything is a file.

In C, we've relied on this basic operational rule everytime we perform input and output. There are three files automatically opened for us each time we run a program. They are:

  * STDIN  - where you get input from (by default, your keyboard)
  * STDOUT - where your output goes (by default, your terminal)
  * STDERR - where any error messages go (by default, your terminal)

Because everything is a file, manipulations can more easily be performed.

A facility that UNIX provides is that of the pipe (the usage of the '<nowiki>|</nowiki>' character), which can string together seemingly separate commands, allowing the output of one to become the input to the next (and so on...) 

Examples of the pipe can be seen here, such as by counting the number of lines in a file:

<cli>
lab46:~$ cat /etc/motd | wc -l
19
lab46:~$ 
</cli>

**cat** will display data (the file's contents), **wc** counts data... so we put the two together, creating something that is unique in functionality.

=====Repository=====
This project is located in a dedicated mercurial repository hosted here in the LAIR. You'll need to clone a copy in your home directory.

Following are instructions to put it in a **~/src/cprog/pipemath/** directory. Should you be organizing your C/C++ Programming files in some other directory, please adjust the path as appropriate.

====Step 1: Ensure parent directories exist====
<cli>
lab46:~$ mkdir -p src/cprog
lab46:~$ 
</cli>

====Step 2: Change into directory====
<cli>
lab46:~$ cd src/cprog
lab46:~/src/cprog$ 
</cli>

====Step 3: clone the repository====
<cli>
lab46:~/src/cprog$ hg clone http://www/hg/project/pipemath-fall2014 pipemath
</cli>

Should the above box scroll, here is the line outside a cli tag:
  * hg clone <nowiki>http://www/hg/project/pipemath-fall2014 pipemath</nowiki>
    * there are 3 spaces, separating 4 arguments:
      * hg - the command
      * clone - the action we wish hg to perform
      * url - the location of the repository we wish for hg to clone
      * destination - a new directory, called pipemath, in our current directory

This will be followed by output (requiring you to authenticate with your lab46 username and password) resembling the following:

<cli>
http authorization required
realm: Lab46/LAIR Mercurial Repository (Authorization Required)
user: username
password: 
requesting all changes
adding changesets
adding manifests
adding file changes
added 1 changesets with 43 changes to 43 files
updating to branch default
43 files updated, 0 files merged, 0 files removed, 0 files unresolved
lab46:~/src/cprog$ 
</cli>

====Step 4: Change into repository directory====
<cli>
lab46:~/src/cprog$ cd pipemath
lab46:~/src/cprog/pipemath$ 
</cli>

====Step 5: Configure mercurial settings for your copy of the repository====
This can be confusing to first-time users, so I've created a way to hopefully automate it, leaving you to perform a visual inspection and make sure everything is in order.

<cli>
lab46:~/src/cprog/pipemath$ make config
</cli>

====All set====
At this point, you're ready to get started. In class we will cover the Makefile system and how it will facilitate the process of compiling everything.

Have fun!

=====Project=====
Your task is to implement three assigned programs in the **pipemath-fall2014** project repository you'll have cloned.

The three programs belong to one of each of these categories:

====numbers====
In **src/numbers/**, are files containing code that will display the numeric value of their namesake to STDOUT.

For example, here is the code to **src/numbers/one.c**:

<code c 1>
//////////////////////////////////////////////////////////////////////
//
// one.c     - program that displays the number '1' to STDOUT. It does
//             not take any input.
//
// Written By: Matthew Haas <wedge@lab46.corning-cc.edu>
// Compile:    run 'Make' from the project's base directory
// Execute:    change into project 'bin/' or add project bin/ to your
//             PATH
//
// Sample run:
//
//    lab46:~/src/pipemath-fall2014/bin$ ./one
//    1
//    lab46:~/src/pipemath-fall2014/bin$ 
//
#include <stdio.h>
#include <stdlib.h>

int main(int argc, char **argv)
{
    fprintf(stdout, "1\n");
    return (0);
}
</code>

It may seem nonsensically simple and straightforward, but again- a part of this project is to generate activity on the repository, and this will do just that.

====bases====
In **src/bases/**, are files containing code that will take input (from STDIN), and convert that input (assume base 10 for this project) to the indicated base.

For example, here is the code to **src/bases/tobase8.c**:

<code c 1>
//////////////////////////////////////////////////////////////////////
//
// tobase8.c - program that displays the number input from STDIN in
//             a base 8 representation to STDOUT.
//
// Written By: Matthew Haas <wedge@lab46.corning-cc.edu>
// Compile:    run 'Make' from the project's base directory
// Execute:    change into project 'bin/' or add project bin/ to
//             your PATH
//
// Sample run:
//
//    lab46:~/src/pipemath-fall2014/bin$ ./nine | ./plus 4 | ./tobase8
//    15
//    lab46:~/src/pipemath-fall2014/bin$ 
//
#include <stdio.h>
#include <stdlib.h>

int main(int argc, char **argv)
{
    int value;

    fscanf (stdin,  "%d",  &value);

    fprintf(stdout, "%o\n", value);

    return(0);
}
</code>

You'll notice usage examples are given in the comment banner up top.

You'll also notice I took the liberty of doing all the "easy" ones (base 8, base 10, base 16).

====maths====
What makes this project particularly fun is how we can perform fairly simple mathematical operations on the information we generate with all these tools.

In **src/maths/**, are files containing code that will take input (from STDIN), and will need to take in information from the command-line as another piece of information, and do the necessary processing to generate the correct result to STDOUT.

For example, here is the code to **src/maths/increment.c**:

<code c 1>
//////////////////////////////////////////////////////////////////////
//
// increment.c - program that accepts input from STDIN, and displays 
//               the result to STDOUT.
//
// Written By:   Matthew Haas <wedge@lab46.corning-cc.edu>
// Compile:      run 'Make' from the project's base directory
// Execute:      change into project 'bin/' or add project bin/ to
//               your PATH
//
// Sample run:
//
//    lab46:~/src/pipemath-fall2014/bin$ ./three | ./increment
//    4
//    lab46:~/src/pipemath-fall2014/bin$ 
//
#include <stdio.h>
#include <stdlib.h>

int main(int argc, char **argv)
{
    int input;

    fscanf (stdin,  "%d",   &input);

    fprintf(stdout, "%d\n", (input+1));

    return(0);
}
</code>

Both **increment** and **decrement** are exceptions here- they are unary operations, so they have no present need to process command-line arguments. But all the other operations are binary, so they do.

There are 8 math operations in need of implementing, they are:

  * divideby   (take input and divide it by the command-line argument)
  * log        (1st command-line argument is the 'base', input is x -- b^y = x)
  * minus      (take input and subtract the command-line argument from it)
  * modulus    (take input and obtain the remainder)
  * multiplyby (take input and multiply by command-line argument)
  * plus       (take input and add to command-line argument)
  * toplaces   (not really 'math', but format the output to provide leading zeros according to argument)
  * topowerof  (take input and raise it to the power of the command-line argument)

=====Items of Consideration=====
Now, there are a few ground rules we need to keep in mind:

  * you are to use only the basic math operators (+, -, *, /, %)
    * NO using the math library!
  * you are to do your own work.
    * these programs are very similar, so be careful not to give away the secrets.
  * you may use C library functions to convert the command-line argument to integer data (**atoi(3)**)
  * you may assume that only correct information ever gets provided
    * you do not need to worry about checking for incorrect data
  * you DO need to check, where appropriate, for the existence of a command-line argument
    * should a required argument be missing, you SHOULD:
      * display an error (to **STDERR**)
      * cause the program to **exit(3)**

=====Submission=====
To successfully complete this project, the following criteria must be met:

  * Code must compile cleanly (no warnings or errors)
  * Assigned programs must correctly handle input according to project requirements
  * Assigned programs must correctly perform processing according to project requirements
  * Assigned programs must correctly generate output according to project requirements
  * Code must be nicely and consistently indented (you may use the **indent** tool)
  * Code must be commented
    * have a properly filled-out comment banner at the top
    * have at least 20% of your program consist of **<nowiki>//</nowiki>**-style descriptive comments
  * Utilize mercurial version control to perform repository transactions
    * Appropriately resolve any conflicts, and obtain new changes by doing a pull/update as needed
    * Commit and Push at least 3 changes (your assigned programs, minimum of 1 commit per program)
      * This doubles as your assignment submission for this project