attr.py

   1 # -*- encoding: utf-8 -*-
   2 #
   3 #
   4 # Copyright (C) 2003-2004 Jörg Lehmann <joergl@users.sourceforge.net>
   5 # Copyright (C) 2003-2004 Michael Schindler <m-schindler@users.sourceforge.net>
   6 # Copyright (C) 2003-2013 André Wobst <wobsta@users.sourceforge.net>
   7 #
   8 # This file is part of PyX (http://pyx.sourceforge.net/).
   9 #
  10 # PyX is free software; you can redistribute it and/or modify
  11 # it under the terms of the GNU General Public License as published by
  12 # the Free Software Foundation; either version 2 of the License, or
  13 # (at your option) any later version.
  14 #
  15 # PyX is distributed in the hope that it will be useful,
  16 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  17 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18 # GNU General Public License for more details.
  19 #
  20 # You should have received a copy of the GNU General Public License
  21 # along with PyX; if not, write to the Free Software
  22 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA
  23
  24 #
  25 # some helper functions for the attribute handling
  26 #
  27
  28 def mergeattrs(attrs):
  29     """perform merging of the attribute list attrs as defined by the
  30     merge methods of the attributes"""
  31     newattrs = []
  32     for a in attrs:
  33         # XXX Do we really need this test?
  34         if isinstance(a, attr):
  35             newattrs = a.merge(newattrs)
  36         else:
  37             raise TypeError("only instances of class attr.attr are allowed")
  38     return newattrs
  39
  40
  41 def getattrs(attrs, getclasses):
  42     """return all attributes in the attribute list attrs, which are
  43     instances of one of the classes in getclasses"""
  44     return [attr for attr in attrs if isinstance(attr, tuple(getclasses))]
  45
  46
  47 def checkattrs(attrs, allowedclasses):
  48     """check whether only attributes which are instances of classes in
  49     allowedclasses are present in the attribute list attrs; if not it
  50     raises a TypeError"""
  51     if len(attrs) != len(getattrs(attrs, allowedclasses)):
  52         for attr1, attr2 in zip(attrs, getattrs(attrs, allowedclasses)):
  53             if attr1 is not attr2:
  54                 raise TypeError("instance %r not allowed" % attr1)
  55         else:
  56             raise TypeError("instance %r not allowed" % attrs[len(getattrs(attrs, allowedclasses))])
  57
  58 def refineattrs(attrs, defaults, allowedclasses, allow_none=True):
  59     """combine the typical handling for attribues passed to a function in a
  60     single call"""
  61     # TODO the whole attribute handling needs some major documentation
  62     if allow_none and attrs is None:
  63         return None
  64     checkattrs(attrs, allowedclasses)
  65     return mergeattrs(defaults + attrs)
  66
  67 #
  68 # attr class and simple descendants
  69 #
  70
  71 class attr:
  72
  73     """ attr is the base class of all attributes, i.e., colors, decorators,
  74     styles, text attributes and trafos"""
  75
  76     def merge(self, attrs):
  77         """merge self into list of attrs
  78
  79         self may either be appended to attrs or inserted at a proper position
  80         immediately before a dependent attribute. Attributes of the same type
  81         should be removed, if redundant. Note that it is safe to modify
  82         attrs."""
  83
  84         attrs.append(self)
  85         return attrs
  86
  87
  88 class exclusiveattr(attr):
  89
  90     """an attribute which swallows all but the last of the same type (specified
  91     by the exlusiveclass argument to the constructor) in an attribute list"""
  92
  93     def __init__(self, exclusiveclass):
  94         self.exclusiveclass = exclusiveclass
  95
  96     def merge(self, attrs):
  97         attrs = [attr for attr in attrs if not isinstance(attr, self.exclusiveclass)]
  98         attrs.append(self)
  99         return attrs
 100
 101
 102 class sortbeforeattr(attr):
 103
 104     """an attribute which places itself previous to all attributes given
 105     in the beforetheclasses argument to the constructor"""
 106
 107     def __init__(self, beforetheclasses):
 108         self.beforetheclasses = tuple(beforetheclasses)
 109
 110     def merge(self, attrs):
 111         first = True
 112         result = []
 113         for attr in attrs:
 114             if first and isinstance(attr, self.beforetheclasses):
 115                 result.append(self)
 116                 first = False
 117             result.append(attr)
 118         if first:
 119             result.append(self)
 120         return result
 121
 122
 123 class sortbeforeexclusiveattr(attr):
 124
 125     """an attribute which swallows all but the last of the same type (specified
 126     by the exlusiveclass argument to the constructor) in an attribute list and
 127     places itself previous to all attributes given in the beforetheclasses
 128     argument to the constructor"""
 129
 130     def __init__(self, exclusiveclass, beforetheclasses):
 131         self.exclusiveclass = exclusiveclass
 132         self.beforetheclasses = tuple(beforetheclasses)
 133
 134     def merge(self, attrs):
 135         first = 1
 136         result = []
 137         for attr in attrs:
 138             if first and isinstance(attr, self.beforetheclasses):
 139                 result.append(self)
 140                 first = 0
 141             if not isinstance(attr, self.exclusiveclass):
 142                 result.append(attr)
 143         if first:
 144             result.append(self)
 145         return result
 146
 147
 148 class clearclass(attr):
 149
 150     """a special attribute which allows to remove all predecessing attributes of
 151     the same type in an attribute list"""
 152
 153     def __init__(self, clearclass):
 154         self.clearclass = clearclass
 155
 156     def merge(self, attrs):
 157         return [attr for attr in attrs if not isinstance(attr, self.clearclass)]
 158
 159
 160 class _clear(attr):
 161
 162     """a special attribute which removes all predecessing attributes
 163     in an attribute list"""
 164
 165     def merge(self, attrs):
 166         return []
 167
 168 # we define the attribute "clear", an instance of "_clear",
 169 # which can be used to remove all predecessing attributes
 170 # in an attribute list
 171
 172 clear = _clear()
 173
 174 #
 175 # changeable attrs
 176 #
 177
 178 def selectattrs(attrs, index, total):
 179     """performs select calls for all changeable attributes and
 180     returns the resulting attribute list
 181     - attrs should be a list containing attributes and changeable
 182       attributes
 183     - index should be an unsigned integer
 184     - total should be a positive number
 185     - valid sections fullfill 0<=index<total
 186     - returns None, when attrs is None
 187     - returns None, when a changeable attribute returns None"""
 188     if attrs is None:
 189         return None
 190     result = []
 191     for a in attrs:
 192         if isinstance(a, changeattr):
 193             select = a.select(index, total)
 194             if select is None:
 195                 return None
 196             result.append(select)
 197         else:
 198             result.append(a)
 199     return result
 200
 201
 202 def selectattr(attr, index, total):
 203     """as select, but for a single attribute"""
 204     if isinstance(attr, changeattr):
 205         select = attr.select(index, total)
 206         if select is None:
 207             return None
 208         return select
 209     else:
 210         return attr
 211
 212
 213 class changeattr:
 214
 215     """changeattr is the base class of all changeable attributes"""
 216
 217     def select(self, index, total):
 218         """returns an attribute for a given index out of a total number
 219         if attributes to be provided
 220         - index should be an unsigned integer
 221         - total should be a positive number
 222         - valid selections fullfill 0 <= index < total
 223         - the select method may raise a ValueError, when the
 224           changeable attribute does not allow for a requested
 225           selection"""
 226
 227         raise RuntimeError("not implemented")
 228
 229
 230 class changelist(changeattr):
 231
 232     """a changeable attribute over a list of attribute choises"""
 233
 234     def __init__(self, attrs, cyclic=1):
 235         """initializes the instance
 236         - attrs is a list of attributes to cycle
 237         - If cyclic is set, we restart from the beginning after
 238           the end of the list has been reached; otherwise
 239           selecting beyond the end of the list returns None"""
 240         self.attrs = attrs
 241         self.cyclic = cyclic
 242
 243     def select(self, index, total):
 244         if self.cyclic:
 245             return self.attrs[index % len(self.attrs)]
 246         elif index < len(self.attrs):
 247             return self.attrs[index]
 248         else:
 249             return None
 250
 251
 252 class multichangeattr(changeattr):
 253
 254     """a changeable attr, which selects a changeable attr from
 255     a given dict (or list) of changeable attrs depending on the
 256     value of total in the select call"""
 257
 258     def __init__(self, changeattrs):
 259         self.changeattrs = changeattrs
 260
 261     def select(self, index, total):
 262         return self.changeattrs[total].select(index, total)
 263