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
34First(obj)              Iterator
35Next(iter)              Next iterator
36
37Mapping Operations (for hash table behavior)
38--------------------------------------------
39Getattr(hash,key)              Get an attribute
40Setattr(hash,key,value)        Set an attribute
41Delattr(hash,key)              Delete an attribute
42First(hash)                    Get first object (iterator)
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 *filename, char *mode, List *newfiles) 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
119