CMPU 235 : Software Design Methodologies
Assignment 1

Due: Thursday Feb 2, 2001

A string class

Until recently C++ did not contain a standard string type. There were several string class libraries available but they were not a part of the C++ language itself. That changed shortly after the introduction of the STL, which now provides a string class as a part of the standard C++ language.

Unfortunately, you are not permitted to use the STL string class in any of your assignments. Instead, each team will develop and maintain a string class that will be used by another team for the remainder of the term. The team using a string class is expected to request (and receive) bug fixes and enhancement from the developing team as the term progresses.

Namespaces

The string class we develop will be places inside a namespace called cs235. To create a namespace in C++ simply put anything you want inside a namespace declaration. You can have more than one namespace declaration with the same name; all classes, functions, etc. will simply be gathered into the same namespace. i.e.

namespace cs235
{
	class Foo 
	{
		...
	};
	class Bar 
	{
		...
	};
	...
}; 
...
namespace cs235
{
	class FooBar : public Foo, public Bar
	{
		...
	};
};

To use the Foo and Bar classes the cs235 namespace must now be used along with the class name.

cs235::Foo    a_foo_object;
cs235::Bar    a_bar_object;
cs235::FooBar a_foobar_object;

Note: if you put the class declaration inside a namespace in the header file you will also have to put the member function implementations inside the same namespace. See string.C and string.h.

The Public Interface

All teams will implement the public interface developed in class. See string.h.

Deliverables

Each team will submit the following files. Click on the links to obtain skeleton files to get you started.

string.h -- the header file must be named string.h
string.C
main.C - a simple driver program that tests your string class. The filename for the driver must be named main.C
HTML documentation for the string class. See below.
Any other .C files you write to implement the string class
A makefile that compiles and links main.C, string.C and any other files you create.
A README file that lists the files needed and any other instructions required to compile and run the program. This should be two or three paragraphs only.

Teams are free to implement the string class in any manner they wish.

You will also need the file cs235.h which defines a few handy macros. The DECLARE_NAMESPACE_CS235 and END_NAMESPACE_CS235 are simply used to spoof the emacs indenting algorithm. Since the curly braces used to declare the cs235 namespace are inside the macro emacs does not seem them and does not try in add an extra level of indentation to everything inside the namespace.

Obtaining the Required Files

Copy the makefile into your directory for assignment 1 and type "make copy". Make will copy all the required files from the assignment directory into your current working directory. At this point you would be able to type "make" and compile the skeleton version of the string class.

The makefile is located in /home/cs235/public_html/a1

Cocoon

Cocoon is run from the command line and takes a single parameter, the name of a configuration file. When run cocoon searches all header files in the current directory for specially formatted comments and generates webpages for the classes found. All classes, functions, constants, etc. defined in all the header files in the current directory will be combined into what cocoon refers to as a library. A simple configuration file is provided, however it will have to be modify slightly before it can be used. The contents are shown below.

webroot /home/username/public_html

customize
    usetable
    membersentinel /**
    docwithsentinel
    logo coclogo.gif
    rule <img src="divider.gif">
end_customize    

library CS235 /home/username/cs235/a1 string

The first line tells cocoon where your public_html directory is located. Simply change username above to your CS Unix id. All files will be copied to a subdirectory at this location

The section of the file between customize and end_customize define global options. The important ones are

membersentinel : this is what tells cocoon what to look for when seaching for documentation blocks. The sentinel must be something that starts a C++ comment. If omitted cocoon uses a string of 10 '/' characters. i.e.
```
     //////////
     // This is the start of a block of documentation
```
docwithsentinel : this tells cocoon to allow documentation to begin on the same line as the membersentinel. If this is omitted everything after the membersentinel is ignored.

The last line of the configuration file tells cocoon about the library to generate.

CS235	What to call the library. This essentially means the file CS235.html will be created that acts as the top level web page for the documentation. Change this to whatever you want.
/home/username/cs235/a1	The location of the source code being documented
string	Cocoon will copy all files created to a subdirectory by this name in the webroot directory. If the directory does not exist it will be created

Commenting Style

When the member sentinel string has been found the following comment block is assumed to document the next thing declared in the file. There cannot be a blank line between the comment block and the declaration. Blank lines in the comment blocks create paragraphs in the html file. If needed html tags can be embedded directly into the comments, but this should be kept to a minimum as the comments should be as readable as possible. See here for an example of cocoon's output and the header files the html was generated from.

See the Cocoon online manual for full information on using Cocoon.

CMPU 235 : Software Design Methodologies Assignment 1