nucleus/library/basis/contracts.h

   1 #ifndef CONTRACTS_GROUP
   2 #define CONTRACTS_GROUP
   3
   4 /*****************************************************************************\
   5 *                                                                             *
   6 *  Name   : contracts                                                         *
   7 *  Author : Chris Koeritz                                                     *
   8 *                                                                             *
   9 *******************************************************************************
  10 * Copyright (c) 1989-$now By Author.  This program is free software; you can  *
  11 * redistribute it and/or modify it under the terms of the GNU General Public  *
  12 * License as published by the Free Software Foundation; either version 2 of   *
  13 * the License or (at your option) any later version.  This is online at:      *
  14 *     http://www.fsf.org/copyleft/gpl.html                                    *
  15 * Please send any updates to: fred@gruntose.com                               *
  16 \*****************************************************************************/
  17
  18 /*! @file contracts.h
  19   This is a collection of fairly vital interface classes.
  20 */
  21
  22 #include "outcome.h"
  23
  24 namespace basis {
  25
  26 // forward declarations.
  27 class base_string;
  28
  29 //////////////
  30
  31 //! Defines an attribute base class that supports get and set operations.
  32
  33 class attribute : public virtual root_object
  34 {
  35 public:
  36   virtual const root_object &get() const = 0;
  37   virtual void set(const root_object &new_value) = 0;
  38 };
  39
  40 //////////////
  41
  42 //! Base class for object that can tell itself apart from other instances.
  43 class equalizable : public virtual root_object
  44 {
  45 public:
  46   virtual bool equal_to(const equalizable &s2) const = 0;
  47     //! the virtual method for object equality.
  48   virtual bool operator == (const equalizable &s2) const { return equal_to(s2); }
  49     //! synactic sugar for comparison operators.
  50 };
  51
  52 //////////////
  53
  54 //! A base for objects that can be alphabetically (lexicographically) ordered.
  55
  56 class orderable : public virtual equalizable
  57 {
  58 public:
  59   virtual bool less_than(const orderable &s2) const  = 0;
  60     //! the virtual method for object ordering.
  61   virtual bool operator < (const orderable &s2) const { return less_than(s2); }
  62     //! synactic sugar for comparison operators.
  63 };
  64
  65 //////////////
  66
  67 //! Provides an abstract base for logging mechanisms.
  68
  69 class base_logger : public virtual root_object
  70 {
  71 public:
  72   virtual outcome log(const base_string &info, int filter) = 0;
  73     //!< writes the information in "info" to the logger using the "filter".
  74     /*!< the derived class can interpret the filter appropriately and only
  75     show the "info" if the filter is enabled. */
  76 };
  77
  78 //////////////
  79
  80 //! Macro for defining a logging filter value.
  81 #define DEFINE_FILTER(NAME, CURRENT_VALUE, INFO_STRING) NAME = CURRENT_VALUE
  82
  83 //! These filter values are the most basic, and need to be known everywhere.
  84 enum root_logging_filters {
  85   DEFINE_FILTER(NEVER_PRINT, -1, "This diagnostic entry should be dropped and never seen"),
  86   DEFINE_FILTER(ALWAYS_PRINT, 0, "This diagnostic entry will always be shown or recorded")
  87 };
  88
  89 //////////////
  90
  91 //! Interface for a simple form of synchronization.
  92 /*!
  93   Derived classes must provide a locking operation and a corresponding
  94   unlocking operation.
  95 */
  96
  97 class base_synchronizer : public virtual root_object
  98 {
  99 public:
 100   virtual void establish_lock() = 0;
 101   virtual void repeal_lock() = 0;
 102 };
 103
 104 //////////////
 105
 106 //! A clonable object knows how to make copy of itself.
 107
 108 class clonable : public virtual root_object
 109 {
 110 public:
 111   virtual clonable *clone() const = 0;
 112 };
 113
 114 //////////////
 115
 116 //! Root object for any class that knows its own name.
 117 /*!
 118   This is a really vital thing for debugging to be very helpful, and unfortunately it's not
 119   provided by C++.
 120 */
 121
 122 class nameable : public virtual root_object
 123 {
 124 public:
 125   virtual const char *class_name() const = 0;
 126     //!< Returns the bare name of this class as a constant character pointer.
 127     /*!< The name returned here is supposed to be just a class name and not
 128     provide any more information than that.  It is especially important not to
 129     add any syntactic elements like '::' to the name, since a bare alphanumeric
 130     name is expected. */
 131 };
 132
 133 //////////////
 134
 135 //! A base class for objects that can provide a synopsis of their current state.
 136 /*!
 137   This helps a lot during debugging and possibly even during normal runtime, since it causes
 138   the object to divulge its internal state for viewing in hopefully readable text.
 139 */
 140
 141 class text_formable : public virtual nameable
 142 {
 143 public:
 144   virtual const char *class_name() const = 0;  // forwarded requirement from nameable.
 145
 146   virtual void text_form(base_string &state_fill) const = 0;
 147     //!< Provides a text view of all the important info owned by this object.
 148     /*!< It is understood that there could be a large amount of information and that this
 149     function might take a relatively long time to complete. */
 150 };
 151
 152 //////////////
 153
 154 //! the base class of the most easily used and tested objects in the library.
 155 /*!
 156   Each hoople_standard object must know its name, how to print out its data members, and whether
 157   it's the same as another object or not.
 158 */
 159
 160 class hoople_standard : public virtual text_formable, public virtual equalizable
 161 {
 162 public:
 163   // this is a union class and has no extra behavior beyond its bases.
 164 };
 165
 166 //////////////
 167
 168 //! a base for classes that can stream their contents out to a textual form.
 169
 170 class text_streamable : public virtual nameable
 171 {
 172 public:
 173   virtual bool produce(base_string &target) const = 0;
 174     //!< sends the derived class's member data into the "target" in a reversible manner.
 175     /*!< this should use a tagging system of some sort so that not only can the derived class
 176     verify that its type is really right there in the string, but also that it gets all of its
 177     class data and no other data.  the "target" will be destructively consumed, and after a
 178     successful call will no longer contain the object's streamed form at its head. */
 179   virtual bool consume(const base_string &source) = 0;
 180     //!< chows down on a string that supposedly contains a streamed form.
 181     /*!< the derived class must know how to eat just the portion of the string that holds
 182     its data type and no more. */
 183 };
 184
 185 } //namespace.
 186
 187 #endif
 188