/tags/rel-1-3-15/SWIG/Source/DOH/README

  1DOH  (Dave's Object Hack)
  2
  3Overview:
  4---------
  5DOH is a small C library that provides a number of simple yet powerful
  6data structures. The data structures are built around a dynamic typing
  7model in which any given object is allowed to support one or more
  8classes of operations.  Furthermore, a simple garbage collection
  9scheme and a variety of interesting library methods are available.
 10All and all, the operation of DOH makes massive abuse of the C type
 11system and would probably make the language purists scream and
 12performance addicts run away in horror.  However, I really don't
 13care--so there! However, for the rest of us, DOH is actually kind of
 14fun to use. This is only a short description of the methods and is no
 15way meant to be exhaustive.
 16
 17Common Operations (for all types)
 18---------------------------------
 19Delete(obj)             Decrease the reference count and destroy if zero
 20Copy(obj)               Make a copy of an object.
 21Clear(obj)              Clear an object.
 22Setscope(obj)           Set scope of an object (guru's only)
 23Str(obj)                Create a string representation of obj.
 24Data(obj)               Return pointer to raw data in an object
 25Char(obj)               Convert to a char *
 26Len(obj)                Length of an object
 27Hash(obj)               Hash value (used for mapping)
 28Cmp(obj1,obj2)          Compare two objects.
 29Name(obj)               Return the object name
 30First(obj)              Return first object (iterator)
 31Next(obj)               Return next object
 32Dump(obj,out)           Serialize on out
 33Load(in)                Unserialize from in
 34
 35Mapping Operations (for hash table behavior)
 36--------------------------------------------
 37Getattr(hash,key)              Get an attribute
 38Setattr(hash,key,value)        Set an attribute
 39Delattr(hash,key)              Delete an attribute
 40Firstkey(hash)                 Get first key
 41Nextkey(hash)                  Get next key
 42First(hash)                    Get first object
 43Next(hash)                     Get next object
 44GetInt(hash,key)               Get attribute as an 'int'
 45SetInt(hash,key,ivalue)        Set attribute as an 'int'
 46GetDouble(hash,key)            Get attribute as a 'double'
 47SetDouble(hash,key,dvalue)     Set Attribute as a 'double'
 48GetChar(hash,key)              Get attribute as a 'char *'
 49
 50Sequence Operations
 51-------------------
 52Getitem(list,index)             Get an item
 53Setitem(list,index,val)         Set an item
 54Delitem(list,index,val)         Delete an item
 55Insert(list,index,val)          Insert an item
 56Append(list,val)                Append to end
 57Push(list,val)                  Insert at beginning
 58
 59File Operations
 60---------------
 61Read(obj,buffer,len)            Read data
 62Write(obj,buffer,len)           Write data
 63Getc(obj)                       Get a character
 64Putc(ch,obj)                    Put a character
 65Ungetc(ch,obj)                  Put character back on input stream
 66Seek(obj,offset,whence)         Seek
 67Tell(obj)                       Return file pointer
 68Close(obj)                      Close
 69
 70String Operations
 71-----------------
 72Replace(obj, orig, rep, flags)  Replace occurences of orig with rep.
 73Chop(obj)                       Remove trailing whitespace
 74
 75flags is one of the following:
 76     DOH_REPLACE_ANY
 77     DOH_REPLACE_NOQUOTE
 78     DOH_REPLACE_ID
 79     DOH_REPLACE_FIRST
 80             
 81Callable Operations
 82-------------------
 83Call(obj, args)                 Perform a function call with arguments args.
 84
 85Miscellaneous library functions
 86-------------------------------
 87NewScope()                      Create a new scope
 88DelScope(s)                     Delete scope s
 89Readline(in)                    Read a line of input from in
 90Printf(out,fmt,...)             Formatted output
 91DohEncoding(name, fn)           Register a format encoding for Printf
 92
 93Currently Available datatypes
 94------------------------------
 95NewString(char *initial)                  Strings
 96NewHash()                                 Hash
 97NewList()                                 List
 98NewVoid(void *ptr, void (*del)(void *))   Void
 99NewFile(char *file, char *mode)           File
100NewCallable(DOH *(*func)(DOH *, DOH *))   Callable object
101
102
103Odds and ends:
104
105  1.   All objects are of type 'DOH *'
106  2.   When in doubt, see rule (1)
107  3.   In certain cases, DOH performs implicit conversions
108       of 'char *' to an appropriate DOH string representation. 
109       For operations involving files, DOH works with many
110       kinds of objects including FILE *, DOH File objects,
111       and DOH strings.  Don't even ask how this works.
112
113  4.   More complete documentation is forthcoming.
114
115
116
117
118