new home directory
[feisty_meow.git] / 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