home *** CD-ROM | disk | FTP | other *** search
/ ProfitPress Mega CDROM2 …eeware (MSDOS)(1992)(Eng) / ProfitPress-MegaCDROM2.B6I / APPS / DATABASE / OCLIP.ZIP / OCLIP.DOC < prev    next >
Encoding:
Text File  |  1991-11-07  |  9.7 KB  |  251 lines
  1. ╔══════════════════════════════════════════════════════════════════════╗
  2. ║                                o:Clip                                ║
  3. ║             An Object Oriented Extension to Clipper 5.01             ║
  4. ║                 (c) 1991 Peter M. Freese, CyberSoft                  ║
  5. ╚══════════════════════════════════════════════════════════════════════╝
  6.  
  7. Version 1.01 - November 8, 1991
  8.  
  9. User Documentation
  10.  
  11.  
  12. LEGAL NOTICE:
  13.  
  14. o:Clip, an object oriented extension to Clipper, is FREEWARE.  It may be
  15. freely distributed and used by individuals and corporations without
  16. charge.  It may not, however, be sold or distributed for a price (other
  17. than user group diskette duplication and distribution fees.)  At all
  18. times, the copyright and title for o:Clip remain with CyberSoft, Box
  19. 718, Milton, WA  98354.  It must be distributed as a whole, including
  20. this accompanying documentation.
  21.  
  22. This software is provided on an as-is basis.  If you choose to use
  23. it, you do so at your own risk.  Neither the author nor CyberSoft offers
  24. any warranty or guarantee of any kind, nor do they (individually or
  25. together) accept any liability for any consequences of the use of this
  26. software.
  27.  
  28.  
  29. REQUIREMENTS:
  30.  
  31. o:Clip requires Clipper 5.01.
  32.  
  33. o:Clip is composed of two files:  OCLIP.LIB and OCLIP.CH
  34.  
  35. OCLIP.LIB contains functions to create classes, add methods and variables
  36. to classes, and to access self.
  37.  
  38. OCLIP.CH contains UDC's to allow class definitions.  The UDC's are
  39. extremely minimal, and make the function definition behind the
  40. definition of a class transparent.  The best way to get an idea of how
  41. they do this is to compile the examples with /p and examine the
  42. preprocessed output files.
  43.  
  44.  
  45. DESCRIPTION:
  46.  
  47. o:Clip is an extension to Clipper 5.01 to allow user defined objects and
  48. classes.
  49.  
  50. Clipper 5.01 is probably one of the most significant advances in X-Base
  51. programming since the invention of the .DBF file.  One of the least
  52. documented and most understood new features is that of objects.  Perhaps
  53. the reason for this is that unlike the rest of the language, Clipper
  54. classes and objects are inflexible - you can't change them, and you
  55. can't create your own.  Without these abilities, it is not truly an
  56. object-oriented programming (OOP) language, and yields none of the
  57. benefits of OOP such as polymorphism, reusability, or inheritance.
  58.  
  59. o:Clip fills in this small but glaring hole in the OOP ability of
  60. Clipper 5.01 by providing the ability to create your own classes and
  61. objects.  You can work with these objects just as you can the ones
  62. provided by Nantucket, with the added benefit of inheritance.  Objects
  63. created with o:Clip return VALTYPE() of "O", and are recognized
  64. internally as objects to Clipper itself.
  65.  
  66.  
  67. AN EXAMPLE:
  68.  
  69. Let's start with an example to see how to create our own class:
  70.  
  71.         CLASS Test
  72.           VAR FirstName
  73.           VAR LastName
  74.           METHOD New=TestNew
  75.         ENDCLASS
  76.  
  77. This class definition creates a 'Class Definition Function' for the
  78. class 'Test', with two instance variables, 'FirstName' and 'LastName',
  79. and one method, 'New'.  An object may be instantiated by calling the
  80. class definition function, 'Test()', which will return a new object of
  81. class 'Test'.
  82.  
  83. Before explaining what 'TestNew' does, let me describe briefly how the
  84. Class Definition Function works.  After preprocessing, the class
  85. definition looks like this:
  86.  
  87.         FUNCTION Test
  88.         STATIC hClass := 0
  89.           if hClass == 0
  90.             __DefineClass("Test",)
  91.             __AddVar("FirstName")
  92.             __AddVar("LastName")
  93.             __AddMethod("New", "TestNew")
  94.             hClass := __MakeClass()
  95.           end
  96.         RETURN __ClassIns(hClass)
  97.  
  98. This first time the Class Definition Function is called, the class
  99. structure is created dynamically, and a handle to the class is stored in
  100. hClass.  Subsequent calls to the Class Definition Function will create
  101. the class from the handle.
  102.  
  103. Each method is essentially a UDF that is assigned to the class.  The
  104. methods must be found in Clipper's symbol table, which means that they
  105. cannot be STATIC functions.  Since we might want several different
  106. classes each containing a method of the same name, o:Clip allows you
  107. to specify both a 'method name' and a 'method UDF'.  This appears in the
  108. class definition as:
  109.  
  110.         METHOD <MethodName> [ = <MethodUDF> ]
  111.  
  112. The method name is the name you will use to send messages to the object
  113. (or invoke the methods, if you prefer that paradigm).  The MethodUDF
  114. 'TestNew' might look like:
  115.  
  116.         FUNCTION TestNew(cFirst,cLast)
  117.           ::FirstName := cFirst
  118.           ::LastName := cLast
  119.         return Self
  120.  
  121. For readability, I recommend prepending the class name to the method
  122. name to create the MethodUDF name.  Thus we could have WindowNew,
  123. GetNew, FrameNew, ScrollNew, all of which could be called by the method
  124. name 'New' for their respective classes.
  125.  
  126.  
  127. THE CONCEPT OF SELF:
  128.  
  129. Objects need a way of referring to themselves explicitly, and there are
  130. two ways to accomplish that in o:Clip.
  131.  
  132. The first is the Self function.  When the Self function is called in a
  133. MethodUDF (and only then), it returns the current object.  It is a good
  134. idea for MethodUDF's to return Self as well, since it allows method
  135. chaining, i.e, object:method1():method2():method3().
  136.  
  137. The second way of referring to self is the use of '::'.  This is
  138. essentially a shorthand for 'Self:'.
  139.  
  140.  
  141. SYNTAX:
  142.  
  143. Class definitions:
  144.  
  145.         CLASS <ClassName> [FROM <ParentClass>]
  146.           VAR <Var1> [,<Var2>[,...<VarN>]]
  147.           METHOD {Method Definition1} [ , ...{Method DefinitionN} ]
  148.               where {MethodDefinition} is of the form:
  149.                   <MethodName> [ = <MethodUDF> ]
  150.         ENDCLASS
  151.  
  152. The optional <ParentClass> allows a new class to 'inherit' all the
  153. attributes of <ParentClass>.  Methods may be overridden in the new class
  154. simply by redefining them with a METHOD definition.  To call an
  155. overridden method from a parent class, preceed it with a "Parent" or
  156. "Super" message.  For example, suppose you have overridden the parent's
  157. New method in a subclass, but wish to call the parent's New method in
  158. you function.  You would use:
  159.  
  160.         ::Parent:New()
  161.  
  162. VAR definitions may be placed on separate lines or combined as taste
  163. dictates.
  164.  
  165. If the METHOD definition does not contain a <MethodUDF>, then the
  166. <MethodName> is used for both.  For example, 'METHOD Foo' is equivalent
  167. to 'METHOD Foo=Foo'.
  168.  
  169.  
  170. EXAMPLE PROGRAMS:
  171.  
  172. ODEMO1.PRG and ODEMO2.PRG provide simple examples of class definitions,
  173. sending messages, and inheritance.
  174.  
  175.  
  176. BACKGROUND:
  177.  
  178. The approach I have taken is a minimalistic one, for three reasons:
  179.  
  180. The first is to reduce the code overhead - o:Clip adds slightly less
  181. than 3K to your application in housekeeping code.  The small amount of
  182. code is indicative of extremely fast performance.  o:Clip uses
  183. assembler, not Clipper p-code.
  184.  
  185. The second reason is compatability.  o:Clip makes complete use of
  186. undocumented class and object creation functions added to Clipper in
  187. version 5.01.  The addition of these functions indicates a move by
  188. Nantucket to provide full OOP capabilities in the *very* near future.
  189. By using these functions instead of writing my own, I avoided not only
  190. duplicating code, but assured that I was following closely the path that
  191. Nantucket had laid out for themselves.
  192.  
  193. The final reason is one of simplicity.  There are some object oriented
  194. languages (C++ for example) that take a 'full blown' approach to object
  195. oriented programming.  If a little knowledge is a dangerous thing, then
  196. C++ is deadly.  I prefer a simple 'purist' approach.  This makes
  197. o:Clip easy to learn rather than intimidating and consuming.  The
  198. number of keywords to learn is minimal, and the concepts are easy to
  199. grasp.
  200.  
  201.  
  202. PROBLEMS:
  203.  
  204. There is a problem with the debugger when using 'mangled' method names
  205. (i.e., MethodUDF <> MethodName).  The debugger insists that the
  206. MethodName function does not exist.  I'm still working on getting this
  207. problem resolved, but I have a feeling the problem may be in one of the
  208. Clipper __Class functions....  This problem only manifests itself when
  209. single stepping through object instantiating in the debugger.  The only
  210. way to avoid it for now is:  a) don't single step over object
  211. instantiating code, or b) don't use the debugger.
  212.  
  213.  
  214. ACKNOWLEDGEMENTS:
  215.  
  216. Thanks go to Anton Von Straaton for his advice and assistance,
  217. particularly in promoting a common syntax between o:Clip and Class(y).
  218. Class(y) is a commercial OOP extension for Clipper which offers more
  219. powerful OOP capabilities than presented here.  Class(y) is available
  220. from Integrated Development Corporation - (800) 333-3429.  There's the
  221. plug, Anton!
  222.  
  223. Thanks also go to Art Fuller, for motivating me to finish this and
  224. getting it "out there", by lauding its virtues in the November DBA
  225. Opinions columns and the Antwerp DevCon.
  226.  
  227.  
  228. FEEDBACK:
  229.  
  230. As mentioned previously, this product is FREEWARE.  I don't ask anything
  231. of you save perhaps a mention in your credits/acknowledgements.  If
  232. sending a cash donation would be the best way to express your gratitude,
  233. ease your conscience, or balance your karma, then it won't be refused,
  234. but it's certainly not necessary.
  235.  
  236. o:Clip is a dynamic project.  It is by no means complete, and I will
  237. continue to support and modify it as time permits.
  238.  
  239. If something doesn't work, let me know.  If you feel that I've left
  240. something out, let me know that too.  Although source code is provided,
  241. and you are free to modify it, I ask that you do *not* distribute
  242. modified source code.  If someone has something of value to donate to
  243. the project, I'll be quite happy to add it in, giving the contributor
  244. full credit.
  245.  
  246. Peter M. Freese
  247.  
  248. CIS:    72600,141
  249.  
  250.  
  251.