learn-c-the-hard-waych20.txt

   Learn C The Hard Way A Learn Code The Hard Way Book
     * Book
     * Comments
     * Video Courses
     * Related Books

   [next] [prev] [prev-tail] [tail] [up]

Chapter 20
Exercise 19: A Simple Object System

   I learned C before I learned Object Oriented Programming, so it helped
   me to build an OOP system in C to understand the basics of what OOP
   meant. You are probably the kind of person who learned an OOP language
   before you learned C, so this kind of bridge might help you as well. In
   this exercise, you will build a simple object system, but also learn
   more about the C Pre-Processor or CPP.

   This exercise will build a simple game where you kill a Minotaur in a
   small little castle. Nothing fancy, just four rooms and a bad guy. This
   project will also be a multi-file project, and look more like a real C
   software project than your previous ones. This is why I'm introducing
   the CPP here because you need it to start using multiple files in your
   own software.

20.1 How The CPP Works

   The C Pre-Processor is a template processing system. It's a highly
   targeted one that helps make C easier to work with, but it does this by
   having a syntax aware templating mechanism. Traditionally people just
   used the CPP to store constants and make "macros" to simplify
   repetitive coding. In modern C you'll actually use the CPP as a code
   generator to create templated pieces of code.

   How the CPP works is you give it one file, usually a .c file, and it
   processes various bits of text starting with the # (octothorpe^1)
   character. When it encounters one of these it performs a specific
   replacement on the text of the input file. It's main advantage though
   is it can include other files, and then augment its list of macros
   based on that file's contents.

   A quick way to see what the CPP does is take the last exercise and run
   this:

     cpp ex18.c | less

   It will be a huge amount of output, but scroll through it and you'll
   see the contents of the other files you included with #include. Scroll
   down to the original code and you can see how the cpp is altering the
   source based on various #define macros in the header files.

   The C compiler is so tightly integrated with cpp that it just runs this
   for you and understands how it works intimately. In modern C, the cpp
   system is so integral to C's function that you might as well just
   consider it to be part of the language.

   In the remaining sections, we'll be using more of the CPP syntax and
   explaining it as we go.

20.2 The Prototype Object System

   The OOP system we'll create is a simple "prototype" style object system
   more like JavaScript. Instead of classes, you start with prototypes
   that have fields set, and then use those as the basis of creating other
   object instances. This "classless" design is much easier to implement
   and work with than a traditional class based one.

20.2.1 The Object Header File

   I want to put the data types and function declarations into a separate
   header file named object.h. This is standard C practice and it lets you
   ship binary libraries but still let the programmer compile against it.
   In this file I have several advanced CPP techniques I'm going to
   quickly describe and then have you see in action later:
     __________________________________________________________________

   Source 49: object.h
   1  #ifndef _object_h
   2  #define _object_h
   3
   4  typedef enum {
   5      NORTH, SOUTH, EAST, WEST
   6  } Direction;
   7
   8  typedef struct {
   9      char *description;
   10      int (*init)(void *self);
   11      void (*describe)(void *self);
   12      void (*destroy)(void *self);
   13      void *(*move)(void *self, Direction direction);
   14      int (*attack)(void *self, int damage);
   15  } Object;
   16
   17  int Object_init(void *self);
   18  void Object_destroy(void *self);
   19  void Object_describe(void *self);
   20  void *Object_move(void *self, Direction direction);
   21  int Object_attack(void *self, int damage);
   22  void *Object_new(size_t size, Object proto, char *description);
   23
   24  #define NEW(T, N) Object_new(sizeof(T), T##Proto, N)
   25  #define _(N) proto.N
   26
   27  #endif
     __________________________________________________________________

   Taking a look at this file, you can see we have a few new pieces of
   syntax you haven't encountered before:

   #ifndef
          You've seen a #define for making simple constants, but the CPP
          can also do logic and remove sections of code. This #ifndef is
          "if not defined" and checks if there's already a
          #define _object_h and if there is it skips all of this code. I
          do this so that we can include this file any time we want and
          not worry about it defining things multiple times.

   #define
          With the above #ifndef shielding this file from we then add the
          _object_h define so that any attempts to include it later cause
          the above to skip.

   #define NEW(T,N)
          This makes a macro, and it works like a template function that
          spits out the code on the right, whenever you write use the
          macro on the left. This one is simply making a short version of
          the normal way we'll call Object_new and avoids potential errors
          with calling it wrong. The way the macro works is the T and N
          parameters to NEW are "injected" into the line of code on the
          right. The syntax T##Proto says to "concat Proto at the end of
          T", so if you had NEW(Room, "Hello.") then it'd make RoomProto
          there.

   #define _(N)
          This macro is a bit of "syntactic sugar" for the object system
          and basically helps you write obj->proto.blah as simply
          obj->_(blah). It's not necessary, but it's a fun little trick
          that I'll use later.

20.2.2 The Object Source File

   The object.h file is declaring functions and data types that are
   defined (created) in the object.c, so that's next:
     __________________________________________________________________

   Source 50: object.c
   1  #include <stdio.h>
   2  #include <string.h>
   3  #include <stdlib.h>
   4  #include "object.h"
   5  #include <assert.h>
   6
   7  void Object_destroy(void *self)
   8  {
   9      Object *obj = self;
   10
   11      if(obj) {
   12          if(obj->description) free(obj->description);
   13          free(obj);
   14      }
   15  }
   16
   17  void Object_describe(void *self)
   18  {
   19      Object *obj = self;
   20      printf("%s.\n", obj->description);
   21  }
   22
   23  int Object_init(void *self)
   24  {
   25      // do nothing really
   26      return 1;
   27  }
   28
   29  void *Object_move(void *self, Direction direction)
   30  {
   31      printf("You can't go that direction.\n");
   32      return NULL;
   33  }
   34
   35  int Object_attack(void *self, int damage)
   36  {
   37      printf("You can't attack that.\n");
   38      return 0;
   39  }
   40
   41  void *Object_new(size_t size, Object proto, char *description)
   42  {
   43      // setup the default functions in case they aren't set
   44      if(!proto.init) proto.init = Object_init;
   45      if(!proto.describe) proto.describe = Object_describe;
   46      if(!proto.destroy) proto.destroy = Object_destroy;
   47      if(!proto.attack) proto.attack = Object_attack;
   48      if(!proto.move) proto.move = Object_move;
   49
   50      // this seems weird, but we can make a struct of one size,
   51      // then point a different pointer at it to "cast" it
   52      Object *el = calloc(1, size);
   53      *el = proto;
   54
   55      // copy the description over
   56      el->description = strdup(description);
   57
   58      // initialize it with whatever init we were given
   59      if(!el->init(el)) {
   60          // looks like it didn't initialize properly
   61          el->destroy(el);
   62          return NULL;
   63      } else {
   64          // all done, we made an object of any type
   65          return el;
   66      }
   67  }
     __________________________________________________________________

   There's really nothing new in this file, except one tiny little trick.
   The function Object_new uses an aspect of how structs work by putting
   the base prototype at the beginning of the struct. When you look at the
   ex19.h header later, you'll see how I make the first field in the
   struct an Object. Since C puts the fields in a struct in order, and
   since a pointer just points at a chunk of memory, I can "cast" a
   pointer to anything I want. In this case, even though I'm taking a
   potentially larger block of memory from calloc, I'm using a Object
   pointer to work with it.

   I explain this a bit better when we write the ex19.h file since it's
   easier to understand when you see it being used.

   That creates your base object system, but you'll need a way to compile
   it and link it into your ex19.c file to create a complete program. The
   object.c file on its own doesn't have a main so it isn't enough to make
   a full program. Here's a Makefile that will do this based on the one
   you've been using:
     __________________________________________________________________

   Source 51: The Makefile
   1CFLAGS=-Wall -g
   2
   3all: ex19
   4
   5ex19: object.o
   6
   7clean:
   8        rm -f ex19
     __________________________________________________________________

   This Makefile is doing nothing more than saying that ex19 depends on
   object.o. Remember how make knows how to build different kinds of files
   by their extensions? Doing this tells make the following:
    1. When I say run make the default all should just build ex19.
    2. When you build ex19, you need to also build object.o and include it
       in the build.
    3. make can't see anything in the file for object.o, but it does see
       an object.c file, and it knows how to turn a .c into a .o, so it
       does that.
    4. Once it has object.o built it then runs the correct compile command
       to build ex19 from ex19.c and object.o.

20.3 The Game Implementation

   Once you have those files you just need to implement the actual game
   using the object system, and first step is putting all the data types
   and function declarations in a ex19.h file:
     __________________________________________________________________

   Source 52: ex19.h
   1  #ifndef _ex19_h
   2  #define _ex19_h
   3
   4  #include "object.h"
   5
   6  struct Monster {
   7      Object proto;
   8      int hit_points;
   9  };
   10
   11  typedef struct Monster Monster;
   12
   13  int Monster_attack(void *self, int damage);
   14  int Monster_init(void *self);
   15
   16  struct Room {
   17      Object proto;
   18
   19      Monster *bad_guy;
   20
   21      struct Room *north;
   22      struct Room *south;
   23      struct Room *east;
   24      struct Room *west;
   25  };
   26
   27  typedef struct Room Room;
   28
   29  void *Room_move(void *self, Direction direction);
   30  int Room_attack(void *self, int damage);
   31  int Room_init(void *self);
   32
   33
   34  struct Map {
   35      Object proto;
   36      Room *start;
   37      Room *location;
   38  };
   39
   40  typedef struct Map Map;
   41
   42  void *Map_move(void *self, Direction direction);
   43  int Map_attack(void *self, int damage);
   44  int Map_init(void *self);
   45
   46  #endif
     __________________________________________________________________

   That sets up three new Objects you'll be using: Monster, Room, and Map.

   Taking a look at object.c:52 you can see where I use a pointer
   Object *el = calloc(1, size). Go back and look at the NEW macro in
   object.h and you can see that it is getting the sizeof another struct,
   say Room, and I allocate that much. However, because I've pointed a
   Object pointer at this block of memory, and because I put an Object
   proto field at the front of Room, I'm able to treat a Room like it's an
   Object.

   The way to break this down is like so:
    1. I call NEW(Room, "Hello.") which the CPP expands as a macro into
       Object_new(sizeof(Room), RoomProto, "Hello.").
    2. This runs, and inside Object_new I allocate a piece of memory
       that's Room in size, but point a Object *el pointer at it.
    3. Since C puts the Room.proto field first, that means the el pointer
       is really only pointing at enough of the block of memory to see a
       full Object struct. It has no idea that it's even called proto.
    4. It then uses this Object *el pointer to set the contents of the
       piece of memory correctly with *el = proto;. Remember that you can
       copy structs, and that *el means "the value of whatever el points
       at", so this means "assign the proto struct to whatever el points
       at".
    5. Now that this mystery struct is filled in with the right data from
       proto, the function can then call init or destroy on the Object,
       but the cool part is whoever called this function can change these
       out for whatever ones they want.

   And with that, we have a way to get this one function to construct new
   types, and give them new functions to change their behavior. This may
   seem like "hackery" but it's stock C and totally valid. In fact there's
   quite a few standard system functions that work this same way, and
   we'll be using some of them for converting addresses in network code.

   With the function definitions and data structures written out I can now
   actually implement the game with four rooms and a minotaur to beat up:
     __________________________________________________________________

   Source 53: ex19.c
   1  #include <stdio.h>
   2  #include <errno.h>
   3  #include <stdlib.h>
   4  #include <string.h>
   5  #include <time.h>
   6  #include "ex19.h"
   7
   8
   9  int Monster_attack(void *self, int damage)
   10  {
   11      Monster *monster = self;
   12
   13      printf("You attack %s!\n", monster->_(description));
   14
   15      monster->hit_points -= damage;
   16
   17      if(monster->hit_points > 0) {
   18          printf("It is still alive.\n");
   19          return 0;
   20      } else {
   21          printf("It is dead!\n");
   22          return 1;
   23      }
   24  }
   25
   26  int Monster_init(void *self)
   27  {
   28      Monster *monster = self;
   29      monster->hit_points = 10;
   30      return 1;
   31  }
   32
   33  Object MonsterProto = {
   34      .init = Monster_init,
   35      .attack = Monster_attack
   36  };
   37
   38
   39  void *Room_move(void *self, Direction direction)
   40  {
   41      Room *room = self;
   42      Room *next = NULL;
   43
   44      if(direction == NORTH && room->north) {
   45          printf("You go north, into:\n");
   46          next = room->north;
   47      } else if(direction == SOUTH && room->south) {
   48          printf("You go south, into:\n");
   49          next = room->south;
   50      } else if(direction == EAST && room->east) {
   51          printf("You go east, into:\n");
   52          next = room->east;
   53      } else if(direction == WEST && room->west) {
   54          printf("You go west, into:\n");
   55          next = room->west;
   56      } else {
   57          printf("You can't go that direction.");
   58          next = NULL;
   59      }
   60
   61      if(next) {
   62          next->_(describe)(next);
   63      }
   64
   65      return next;
   66  }
   67
   68
   69  int Room_attack(void *self, int damage)
   70  {
   71      Room *room = self;
   72      Monster *monster = room->bad_guy;
   73
   74      if(monster) {
   75          monster->_(attack)(monster, damage);
   76          return 1;
   77      } else {
   78          printf("You flail in the air at nothing. Idiot.\n");
   79          return 0;
   80      }
   81  }
   82
   83
   84  Object RoomProto = {
   85      .move = Room_move,
   86      .attack = Room_attack
   87  };
   88
   89
   90  void *Map_move(void *self, Direction direction)
   91  {
   92      Map *map = self;
   93      Room *location = map->location;
   94      Room *next = NULL;
   95
   96      next = location->_(move)(location, direction);
   97
   98      if(next) {
   99          map->location = next;
   100      }
   101
   102      return next;
   103  }
   104
   105  int Map_attack(void *self, int damage)
   106  {
   107      Map* map = self;
   108      Room *location = map->location;
   109
   110      return location->_(attack)(location, damage);
   111  }
   112
   113
   114  int Map_init(void *self)
   115  {
   116      Map *map = self;
   117
   118      // make some rooms for a small map
   119      Room *hall = NEW(Room, "The great Hall");
   120      Room *throne = NEW(Room, "The throne room");
   121      Room *arena = NEW(Room, "The arena, with the minotaur");
   122      Room *kitchen = NEW(Room, "Kitchen, you have the knife now");
   123
   124      // put the bad guy in the arena
   125      arena->bad_guy = NEW(Monster, "The evil minotaur");
   126
   127      // setup the map rooms
   128      hall->north = throne;
   129
   130      throne->west = arena;
   131      throne->east = kitchen;
   132      throne->south = hall;
   133
   134      arena->east = throne;
   135      kitchen->west = throne;
   136
   137      // start the map and the character off in the hall
   138      map->start = hall;
   139      map->location = hall;
   140
   141      return 1;
   142  }
   143
   144  Object MapProto = {
   145      .init = Map_init,
   146      .move = Map_move,
   147      .attack = Map_attack
   148  };
   149
   150  int process_input(Map *game)
   151  {
   152      printf("\n> ");
   153
   154      char ch = getchar();
   155      getchar(); // eat ENTER
   156
   157      int damage = rand() % 4;
   158
   159      switch(ch) {
   160          case -1:
   161              printf("Giving up? You suck.\n");
   162              return 0;
   163              break;
   164
   165          case 'n':
   166              game->_(move)(game, NORTH);
   167              break;
   168
   169          case 's':
   170              game->_(move)(game, SOUTH);
   171              break;
   172
   173          case 'e':
   174              game->_(move)(game, EAST);
   175              break;
   176
   177          case 'w':
   178              game->_(move)(game, WEST);
   179              break;
   180
   181          case 'a':
   182
   183              game->_(attack)(game, damage);
   184              break;
   185          case 'l':
   186              printf("You can go:\n");
   187              if(game->location->north) printf("NORTH\n");
   188              if(game->location->south) printf("SOUTH\n");
   189              if(game->location->east) printf("EAST\n");
   190              if(game->location->west) printf("WEST\n");
   191              break;
   192
   193          default:
   194              printf("What?: %d\n", ch);
   195      }
   196
   197      return 1;
   198  }
   199
   200  int main(int argc, char *argv[])
   201  {
   202      // simple way to setup the randomness
   203      srand(time(NULL));
   204
   205      // make our map to work with
   206      Map *game = NEW(Map, "The Hall of the Minotaur.");
   207
   208      printf("You enter the ");
   209      game->location->_(describe)(game->location);
   210
   211      while(process_input(game)) {
   212      }
   213
   214      return 0;
   215  }
     __________________________________________________________________

   Honestly there isn't much in this that you haven't seen, and only you
   might need to understand how I'm using the macros I made from the
   headers files. Here's the important key things to study and understand:
    1. Implementing a prototype involves creating its version of the
       functions, and then creating a single struct ending in "Proto".
       Look at MonsterProto, RoomProto and MapProto.
    2. Because of how Object_new is implemented, if you don't set a
       function in your prototype, then it will get the default
       implementation created in object.c.
    3. In Map_init I create the little world, but more importantly I use
       the NEW macro from object.h to build all of the objects. To get
       this concept in your head, try replacing the NEW usage with direct
       Object_new calls to see how it's being translated.
    4. Working with these objects involves calling functions on them, and
       the _(N) macro does this for me. If you look at the code
       monster->_(attack)(monster, damage) you see that I'm using the
       macro, which gets replaced with
       monster->proto.attack(monster, damage). Study this transformation
       again by rewriting these calls back to their original. Also, if you
       get stuck then run cpp manually to see what it's going to do.
    5. I'm using two new functions srand and rand, which setup a simple
       random number generator good enough for the game. I also use time
       to initialize the random number generator. Research those.
    6. I use a new function getchar that gets a single character from the
       stdin. Research it.

20.4 What You Should See

   Here's me playing my own game:
     __________________________________________________________________

   Source 54: ex19 output
   1$ make ex19
   2cc -Wall -g   -c -o object.o object.c
   3cc -Wall -g    ex19.c object.o   -o ex19
   4$ ./ex19
   5You enter the The great Hall.
   6
   7> l
   8You can go:
   9NORTH
   10
   11> n
   12You go north, into:
   13The throne room.
   14
   15> l
   16You can go:
   17SOUTH
   18EAST
   19WEST
   20
   21> e
   22You go east, into:
   23Kitchen, you have the knife now.
   24
   25> w
   26You go west, into:
   27The throne room.
   28
   29> s
   30You go south, into:
   31The great Hall.
   32
   33> n
   34You go north, into:
   35The throne room.
   36
   37> w
   38You go west, into:
   39The arena, with the minotaur.
   40
   41> a
   42You attack The evil minotaur!
   43It is still alive.
   44
   45> a
   46You attack The evil minotaur!
   47It is dead!
   48
   49> ^D
   50Giving up? You suck.
   51$
     __________________________________________________________________

20.5 Auditing The Game

   As an exercise for you I have left out all of the assert checks I
   normally put into a piece of software. You've seen me use assert to
   make sure a program is running correctly, but now I want you to go back
   and do the following:

    1. Look at each function you've defined, one file at a time.
    2. At the top of each function, add asserts that make sure the input
       parameters are correct. For example, in Object_new you want a
       assert(description != NULL).
    3. Go through each line of the function, and find any functions being
       called. Read the documentation (man page) for that function, and
       confirm what it returns for an error. Add another assert to check
       that the error didn't happen. For example, in Object_new you need
       one after the call to calloc that does assert(el != NULL).
    4. If a function is expected to return a value, either make sure it
       returns an error value (like NULL), or have an assert to make sure
       that the returned variable isn't invalid. For example, in
       Object_new, you need to have assert(el != NULL) again before the
       last return since that part can never be NULL.
    5. For every if-statement you write, make sure there's an else clause
       unless that if is an error check that causes an exit.
    6. For every switch-statement you write, make sure that there's a
       default case that handles anything you didn't anticipate.

   Take your time going through every line of the function and find any
   errors you make. Remember that the point of this exercise is to stop
   being a "coder" and switch your brain into being a "hacker". Try to see
   how you could break it, then write code to prevent it or abort early if
   you can.

20.6 Extra Credit

    1. Update the Makefile so that when you do make clean it will also
       remove the object.o file.
    2. Write a test script that works the game in different ways and
       augment the Makefile so you can run make test and it'll thrash the
       game with your script.
    3. Add more rooms and monsters to the game.
    4. Put the game mechanics into a third file, compile it to .o, and
       then use that to write another little game. If you're doing it
       right you should only have a new Map and a main function in the new
       game.

   ^1A.K.A. pound, hash, mesh, number symbol, pick whatever makes you
   happy

   [next] [prev] [prev-tail] [front] [up]
     __________________________________________________________________

   Please enable JavaScript to view the comments powered by Disqus.

Take An Online Video Course

   You can sign up for a video course at:

   http://www.udemy.com/learn-c-the-hard-way/

   This course is currently being built at the same time that the book is
   being built, but if you sign up now then you get early access to both
   the videos and PDF of the book.

Related Books

   You might want to check out these other books in the series:
    1. Learn Ruby The Hard Way
    2. Learn Regex The Hard Way
    3. Learn SQL The Hard Way
    4. Learn C The Hard Way
    5. Learn Python The Hard Way

   I'll be referencing other books shortly.

   Copyright 2011 Zed A. Shaw. All Rights Reserved.