Source/DOH/README

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