An in-depth Example

We offer an example that presents the envelope and letter idiom in greater depth. For this discussion, we return to an example discussed in the earlier discussion on polymorphism. We use registration and prototypes to decouple creation from the base class.

Contents

• Introduction
• Usage
• The Envelope
• The Base Letter Class
• Letter Class Implementations
• Recommended Reading

main.cc

#include <shaperep.h>
#include <iostream>
#include <list>

using Shapes::Shape;

int main()
{
	std::string request;
	std::list<Shape> s;
	Shape tmp;

	while (request != "q" )	
		try {
			std::cout << "Enter the name of a shape (q to quit)" << std::endl;
			std::cin >> request;
			if ( request != "q" )
			{
				tmp = Shapes::God->make(request);
				s.push_back(tmp);
			}
		}
		catch (const Shapes::Exception& e)
		{
			std::cout << request << " is unsupported " << std::endl;
		}

	std::list<Shape>::iterator it;
	for ( it = s.begin(); it != s.end(); ++it )
		(*it)->draw();

	return 0;
}

Now let's explain what's happening here:

• request is the name of a shape that we want to create. We don't know if we'll be able to create the shape in advance or not, hence the try-catch block.
• s is a list of Shape. Because of the way the the envelope idiom works, we are no longer faced with the classic problem of containers of pointers breaking in several places, since the envelope gives us polymorphic behaviour with automatic storage.
• We have a loop where the user requests shapes to append to the list. God is the prototype that's reponsible for delegating requests. (It's of type ShapeRep which is the base letter class in this example. This is the only exposure clients have to letter classes)
• Then there's the catch block to trap the exception thrown by God->make() when a construction attempt fails.
• Then we draw all the shapes. Note that even though the Shape class is in automatic storage, we use operator-> to call methods, as this is the mechanism by which we delegate to the underlying letter class.
• Look ma, no destruction loop! We don't need to cycle through the list deleting what's in it, because it's in automatic storage.

I'm sorry if I labored the point about automatic storage, but it's an important one, as the idea of calling methods with -> on objects that don't require manual cleanup may seem a little odd.

Without further ado, we move on to the ...

• The Exception class should be self explanatory. It's a very primitive class, because I want to discuss envelopes and not exceptions. We need it because the prototype's psuedo-constructor throws exceptions when an unsupported object is requested.
• The Registration struct is a dummy object used to register classes in the prototype list. (See the discussion on registration if you're not clear what this means) The string members are primarily there for debugging purposes.
• The shape has all the usual methods that an automatic storage class should have: a default constructor, a copy constructor, an assignment operator and a destructor.
• There's also operator-> which is used to delegate to the polymorphic ShapeRep pointer.
• We also need a constructor that takes an argument of type ShapeRep (recall that this is the letter class). We need this to make our prototype generate Shapes (envelopes ) as oposed to ShapeReps (letters).
• The PrototypeList() function returns a reference to a singleton list. This is used to store all the prototypes. It's exactly the same in its purpose as that described in the registration discussion.

The only comment I have about shape.cc is the observation that one needs to test for self assignment (or in particular, to test that Rep != e.Rep, which is equivalent in our case) We could bypass the problem entirely by cloning before we delete, but there's another reason to do the check -- we can optimise an unneccessary allocation/deletion.

shape.h

#ifndef SHAPE_H
#define SHAPE_H
#include <string>
#include <list>

// Some of our classnames are very common (like Exception).  So we'd better
// have a namespace
namespace Shapes {

// Exception class for this application.

class Exception {
public:
	Exception(const char* s = "" ) : msg(s){}
	Exception(std::string s = "" ) : msg(s){}
	std::string message () const { return msg; }
private:
	std::string msg;
};

// Dummy class to distinguish registration constructor from other constructors

struct Registration {
	Registration(std::string name) : name(name){}
	std::string name;
};

class ShapeRep;

// Envelope class

class Shape {
public:	
	Shape();
	Shape(const Shape& e) ;
	Shape& operator= (const Shape& e);
	Shape(ShapeRep& r);
	~Shape();
	ShapeRep* operator->();
private:
	ShapeRep* Rep;
};

std::list<Shape>& PrototypeList();


} // namespace

#endif

shape.cc

#include <shape.h>
#include <shaperep.h>

using namespace Shapes;

Shape::Shape() : Rep(0){}

Shape::Shape(const Shape& e) 
{

	if (e.Rep)
		Rep = e.Rep->clone();
	else
		Rep = 0;
}

Shape::Shape(ShapeRep& r) 
{
	Rep = r.clone();
}

Shape& Shape::operator= (const Shape& e)
{
	if ( &e != this )
	{
		delete Rep;
		Rep = e.Rep->clone();
	}
	return *this;
}

Shape::~Shape() 
{ 
	delete Rep;
}

ShapeRep* Shape::operator->()
{
	return Rep;
}

std::list<Shape>& Shapes::PrototypeList()
{
	static std::list<Shape> x;
	return x;
}

ShapeRep serves as the base letter class. The letter class is where most of the intelligence of the whole scheme lies, the envelope typically does little besides provide automatic management for the letter. This class is similar to the base we offered in the previous discussion on registration. Some key points:

• ShapeRep is not abstract! The reason it is not abstract is because the prototype is a concrete class. However, the prototype should be the only concrete instance.
• As with any letter class, it provides the interface for the base class, with empty methods. In this instance, the only method is draw().
• make follows almost exactly the same pattern as the one offered in registration, the only difference being that it uses the Shape(ShapeRep) constructor to return a Shape.
• clone() is self explanatory and trivial. We need an implementation in the base class because it's used during prototype registration.
• isMine is no different in its behaviour to the one in the earlier discussion. Note that the base class implementation should always return false since the base letter only exists for prototype purposes.
• The ``usual'' creation methods are hidden because they should not be used by clients.
• What is God ? The creator, of course. God is what clients use to create objects. Calls to make are invoked as God->make()
• The function Prototype(), undelcared in the header, is in an unnamed namespace to make it invisible from outside. Unnamed namespaces perform the same role as the deprecated static internal linkage directive used by C programmers.

shaperep.h

#ifndef SHAPEREP_H
#define SHAPEREP_H
#include <iostream>
#include <list>
#include <string>
#include <shape.h>

// This class cannot have pure virtual methods because we need a prototype

namespace Shapes
{
class ShapeRep
{
public:
	ShapeRep(const Registration&)
	{
		PrototypeList().push_back(Shape(*this));	
	}
    virtual void draw() const {}
    virtual ~ShapeRep();
	virtual ShapeRep* clone() const 
	{
		return new ShapeRep;	
	}
	virtual Shape make(std::string request_code) const;
	virtual bool isMine (std::string request_code);
protected:
    ShapeRep(){}
    ShapeRep(const ShapeRep&){}
    ShapeRep& operator=(const ShapeRep&) { return *this; }
};

extern Shape God;

} //namespace
#endif

shaperep.cc

#include <iostream>
#include <list>
#include <string>
#include <shape.h>
#include <shaperep.h>

using namespace Shapes;

ShapeRep::~ShapeRep(){}

Shape
ShapeRep::make (std::string request_code) const
{
	std::list<Shape>::iterator it = PrototypeList().begin(); 
	for ( ; it != PrototypeList().end(); ++it)
	{
		if ( (*it)->isMine ( request_code )  )
			return (*it)->make( request_code );
	}
	throw Exception
		( std::string("make request failed for unknown shape ") + request_code );
}

bool 
ShapeRep::isMine (std::string request_code)
{
	return false;
}

namespace {
ShapeRep& Prototype()
{
	static ShapeRep t(Registration("Shape"));
	return t;
}
}

Shape Shapes::God ( Prototype() );

square.h

#ifndef SQUARE_H
#define SQUARE_H
#include <shaperep.h>
#include <string>
namespace Shapes 
{
class Square: public ShapeRep
{
public:
	Square(){}
	Square(const Registration&)
	{
		PrototypeList().push_back(Shape(*this));
	}
	virtual ShapeRep* clone () const;
	virtual Shape make (std::string request_code) const;
    virtual void draw ()const;
	virtual bool isMine(std::string request_code) { return request_code == "square"; }
    virtual ~Square ();
};

extern Shape Shapes::SquarePrototype;

} //namespace
#endif

square.cc

#include <square.h>
using namespace Shapes;

ShapeRep* Square::clone () const
{ 
	return new Square; 
}

Shape Square::make (std::string request_code) const
{ 
	Square* ret = new Square;
	return Shape(*ret); 
}

void Square::draw () const
{
    std::cout 
        <<  "      ______________    \n"
        <<  "     |/             |   \n"
        <<  "     |//  ====      |   \n"
        <<  "     |///       ====|   \n"
        <<  "     |/////         |   \n"
        <<  "     |//===         |   \n"
        <<  "     |////========  |   \n"
        <<  "     |/========//   |   \n"
        <<  "     |//==/--       |   \n"
        <<  "     L______________J   \n"
        << std:: endl;
}

Square::~Square()
{}

namespace {
Square& Prototype()
{
	static Square t(Registration("triangle"));
	return t;
}
}

Shape Shapes::SquarePrototype ( Prototype() );

triangle.h

#ifndef TRIANGLE_H
#define TRIANGLE_H
#include <shaperep.h>
#include <string>
namespace Shapes 
{
class Triangle : public ShapeRep
{
public:
	Triangle(){}
	Triangle(const Registration&)
	{
		PrototypeList().push_back(Shape(*this));	
	}
	virtual ShapeRep* clone ()const ;
	virtual Shape make (std::string request_code)const ;
    virtual void draw ()const ;
	virtual bool isMine(std::string request_code) { return request_code == "triangle";}
    virtual ~Triangle();
};

extern Shape Shapes::TrianglePrototype;

} // namespace

#endif

triangle.cc

#include <triangle.h>
#include <shape.h>
using namespace Shapes;


ShapeRep* Triangle::clone () const 
{ 
	return new Triangle; 
}
Shape Triangle::make (std::string request_code) const 
{ 
	Triangle* ret = new Triangle;
	return Shape(*ret); 
}
void Triangle::draw ()  const 
{
    std::cout 
        <<  "     |\\               \n"
        <<  "     |+\\              \n"
        <<  "     |= \\             \n"
        <<  "     |= =\\            \n"
        <<  "     |== =\\           \n"
        <<  "     |== ==\\          \n"
        <<  "     |== ===\\         \n"
        <<  "     |==    =\\        \n"
        <<  "     |=  +++==\\       \n"
        <<  "     |=+  +====\\      \n"
        <<  "     |== +     =\\     \n"
        <<  "     |=+       ==\\    \n"
        <<  "     L____________\\   \n"
        << std:: endl;
}

Triangle::~Triangle()
{ }

namespace {
Triangle& Prototype()
{
	static Triangle t(Registration("triangle"));
	return t;
}
}

Shape Shapes::TrianglePrototype ( Prototype() );

circle.h

#ifndef CIRCLE_H
#define CIRCLE_H
#include <shaperep.h>
#include <string>
namespace Shapes
{
class Circle : public ShapeRep
{
public:
	Circle(){}
	Circle(const Registration&)
	{
		PrototypeList().push_back(Shape(*this));	
	}
	virtual ShapeRep* clone () const;
	virtual Shape make (std::string request_code) const;
    virtual void draw () const;
	virtual bool isMine(std::string request_code) { return request_code == "circle"; }
    virtual ~Circle();
};

extern Shape Shapes::CirclePrototype;

}//namespace
#endif

circle.cc

#include <shape.h>
#include <circle.h>
#include <string>

using namespace Shapes;

ShapeRep* Circle::clone () const
{ 
	return new Circle; 
}

Shape Circle::make (std::string request_code) const
{ 
	Circle* ret = new Circle;
	return Shape(*ret); 
}
void Circle::draw () const
{
    std::cout 
        <<  "           ****         \n"
        <<  "        *        *      \n"
        <<  "      *            *    \n"
        <<  "     *              *   \n"
        <<  "     *              *   \n"
        <<  "     *              *   \n"
        <<  "     *              *   \n"
        <<  "      *            *    \n"
        <<  "        *        *      \n"
        <<  "           ****         \n"
        << std:: endl;
}

Circle::~Circle(){}


namespace {
Circle& Prototype()
{
	static Circle t(Registration("triangle"));
	return t;
}
}

Shape Shapes::CirclePrototype ( Prototype() );