Tools/bgen/bgen/bgenType.py

   1 """Type classes and a modest collection of standard types."""
   2
   3
   4 from bgenOutput import *
   5
   6
   7 class Type:
   8
   9         """Define the various things you can do with a C type.
  10
  11         Most methods are intended to be extended or overridden.
  12         """
  13
  14         def __init__(self, typeName, fmt):
  15                 """Call with the C name and getargs format for the type.
  16
  17                 Example: int = Type("int", "i")
  18                 """
  19                 self.typeName = typeName
  20                 self.fmt = fmt
  21
  22         def declare(self, name):
  23                 """Declare a variable of the type with a given name.
  24
  25                 Example: int.declare('spam') prints "int spam;"
  26                 """
  27                 Output("%s %s;", self.typeName, name)
  28
  29         def getargs(self):
  30                 return self.getargsFormat(), self.getargsArgs()
  31
  32         def getargsFormat(self):
  33                 """Return the format for this type for use with [new]getargs().
  34
  35                 Example: int.getargsFormat() returns the string "i".
  36                 """
  37                 return self.fmt
  38
  39         def getargsArgs(self, name):
  40                 """Return an argument for use with [new]getargs().
  41
  42                 Example: int.getargsArgs("spam") returns the string "&spam".
  43                 """
  44                 return "&" + name
  45
  46         def getargsCheck(self, name):
  47                 """Perform any needed post-[new]getargs() checks.
  48
  49                 This is type-dependent; the default does not check for errors.
  50                 An example would be a check for a maximum string length."""
  51
  52         def passInput(self, name):
  53                 """Return an argument for passing a variable into a call.
  54
  55                 Example: int.passInput("spam") returns the string "spam".
  56                 """
  57                 return name
  58
  59         def passOutput(self, name):
  60                 """Return an argument for returning a variable out of a call.
  61
  62                 Example: int.passOutput("spam") returns the string "&spam".
  63                 """
  64                 return "&" + name
  65
  66         def errorCheck(self, name):
  67                 """Check for an error returned in the variable.
  68
  69                 This is type-dependent; the default does not check for errors.
  70                 An example would be a check for a NULL pointer.
  71                 If an error is found, the generated routine should
  72                 raise an exception and return NULL.
  73
  74                 XXX There should be a way to add error clean-up code.
  75                 """
  76                 Output("/* XXX no err check for %s %s */", self.typeName, name)
  77
  78         def mkvalue(self):
  79                 return self.mkvalueFormat(), self.mkvalueArgs()
  80
  81         def mkvalueFormat(self):
  82                 """Return the format for this type for use with mkvalue().
  83
  84                 This is normally the same as getargsFormat() but it is
  85                 a separate function to allow future divergence.
  86                 """
  87                 return self.getargsFormat()
  88
  89         def mkvalueArgs(self, name):
  90                 """Return an argument for use with mkvalue().
  91
  92                 Example: int.mkvalueArgs("spam") returns the string "spam".
  93                 """
  94                 return name
  95
  96         def cleanup(self, name):
  97                 """Clean up if necessary.
  98
  99                 This is normally empty; it may deallocate buffers etc.
 100                 """
 101                 pass
 102
 103 class ByAddressType(Type):
 104         "Simple type that is also passed by address for input"
 105
 106         def passInput(self, name):
 107                 return "&%s" % name
 108
 109
 110
 111 # Sometimes it's useful to define a type that's only usable as input or output parameter
 112
 113 class InputOnlyMixIn:
 114
 115         "Mix-in class to boobytrap passOutput"
 116
 117         def passOutput(self, name):
 118                 raise RuntimeError, "this type can only be used for input parameters"
 119
 120 class InputOnlyType(InputOnlyMixIn, Type):
 121
 122         "Same as Type, but only usable for input parameters -- passOutput is boobytrapped"
 123
 124 class OutputOnlyMixIn:
 125
 126         "Mix-in class to boobytrap passInput"
 127
 128         def passInput(self, name):
 129                 raise RuntimeError, "this type can only be used for output parameters"
 130
 131 class OutputOnlyType(OutputOnlyMixIn, Type):
 132
 133         "Same as Type, but only usable for output parameters -- passInput is boobytrapped"
 134
 135
 136 # A modest collection of standard C types.
 137 void = None
 138 char = Type("char", "c")
 139 short = Type("short", "h")
 140 unsigned_short = Type("unsigned short", "H")
 141 int = Type("int", "i")
 142 long = Type("long", "l")
 143 unsigned_long = Type("unsigned long", "l")
 144 float = Type("float", "f")
 145 double = Type("double", "d")
 146
 147
 148 # The most common use of character pointers is a null-terminated string.
 149 # For input, this is easy.  For output, and for other uses of char *,
 150 # see the module bgenBuffer.
 151 stringptr = InputOnlyType("char*", "s")
 152
 153
 154 # Some Python related types.
 155 objectptr = Type("PyObject*", "O")
 156 stringobjectptr = Type("PyStringObject*", "S")
 157 # Etc.
 158
 159
 160 class FakeType(InputOnlyType):
 161
 162         """A type that is not represented in the Python version of the interface.
 163
 164         Instantiate with a value to pass in the call.
 165         """
 166
 167         def __init__(self, substitute):
 168                 self.substitute = substitute
 169                 self.typeName = None    # Don't show this argument in __doc__ string
 170
 171         def declare(self, name):
 172                 pass
 173
 174         def getargsFormat(self):
 175                 return ""
 176
 177         def getargsArgs(self, name):
 178                 return None
 179
 180         def passInput(self, name):
 181                 return self.substitute
 182
 183
 184 class OpaqueType(Type):
 185
 186         """A type represented by an opaque object type, always passed by address.
 187
 188         Instantiate with the type name and the names of the new and convert procs.
 189         If fewer than three arguments are passed, the second argument is used
 190         to derive the new and convert procs by appending _New and _Convert; it
 191         defaults to the first argument.
 192         """
 193
 194         def __init__(self, name, arg = None, extra = None):
 195                 self.typeName = name
 196                 if extra is None:
 197                          # Two arguments (name, usetype) or one (name)
 198                         arg = arg or name
 199                         self.new = arg + '_New'
 200                         self.convert = arg + '_Convert'
 201                 else:
 202                         # Three arguments (name, new, convert)
 203                         self.new = arg
 204                         self.convert = extra
 205
 206         def getargsFormat(self):
 207                 return "O&"
 208
 209         def getargsArgs(self, name):
 210                 return "%s, &%s" % (self.convert, name)
 211
 212         def passInput(self, name):
 213                 return "&%s" % name
 214
 215         def mkvalueFormat(self):
 216                 return "O&"
 217
 218         def mkvalueArgs(self, name):
 219                 return "%s, &%s" % (self.new, name)
 220
 221
 222 class OpaqueByValueType(OpaqueType):
 223
 224         """A type represented by an opaque object type, on input passed BY VALUE.
 225
 226         Instantiate with the type name, and optionally an object type name whose
 227         New/Convert functions will be used.
 228         """
 229
 230         def passInput(self, name):
 231                 return name
 232
 233         def mkvalueArgs(self, name):
 234                 return "%s, %s" % (self.new, name)
 235
 236
 237 class OpaqueArrayType(OpaqueByValueType):
 238
 239         """A type represented by an opaque object type, with ARRAY passing semantics.
 240
 241         Instantiate with the type name, and optional an object type name whose
 242         New/Convert functions will be used.
 243         """
 244
 245         def getargsArgs(self, name):
 246                 return "%s, %s" % (self.convert, name)
 247
 248         def passOutput(self, name):
 249                 return name