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-2004 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 #
  59 # attr class and simple descendants
  60 #
  61
  62 class attr:
  63
  64     """ attr is the base class of all attributes, i.e., colors, decorators,
  65     styles, text attributes and trafos"""
  66
  67     def merge(self, attrs):
  68         """merge self into list of attrs
  69
  70         self may either be appended to attrs or inserted at a proper position
  71         immediately before a dependent attribute. Attributes of the same type
  72         should be removed, if redundant. Note that it is safe to modify
  73         attrs."""
  74
  75         attrs.append(self)
  76         return attrs
  77
  78
  79 class exclusiveattr(attr):
  80
  81     """an attribute which swallows all but the last of the same type (specified
  82     by the exlusiveclass argument to the constructor) in an attribute list"""
  83
  84     def __init__(self, exclusiveclass):
  85         self.exclusiveclass = exclusiveclass
  86
  87     def merge(self, attrs):
  88         attrs = [attr for attr in attrs if not isinstance(attr, self.exclusiveclass)]
  89         attrs.append(self)
  90         return attrs
  91
  92
  93 class sortbeforeattr(attr):
  94
  95     """an attribute which places itself previous to all attributes given
  96     in the beforetheclasses argument to the constructor"""
  97
  98     def __init__(self, beforetheclasses):
  99         self.beforetheclasses = tuple(beforetheclasses)
 100
 101     def merge(self, attrs):
 102         first = 1
 103         result = []
 104         for attr in attrs:
 105             if first and isinstance(attr, self.beforetheclasses):
 106                 result.append(self)
 107                 first = 0
 108             result.append(attr)
 109         if first:
 110             result.append(self)
 111         return result
 112
 113
 114 class sortbeforeexclusiveattr(attr):
 115
 116     """an attribute which swallows all but the last of the same type (specified
 117     by the exlusiveclass argument to the constructor) in an attribute list and
 118     places itself previous to all attributes given in the beforetheclasses
 119     argument to the constructor"""
 120
 121     def __init__(self, exclusiveclass, beforetheclasses):
 122         self.exclusiveclass = exclusiveclass
 123         self.beforetheclasses = tuple(beforetheclasses)
 124
 125     def merge(self, attrs):
 126         first = 1
 127         result = []
 128         for attr in attrs:
 129             if first and isinstance(attr, self.beforetheclasses):
 130                 result.append(self)
 131                 first = 0
 132             if not isinstance(attr, self.exclusiveclass):
 133                 result.append(attr)
 134         if first:
 135             result.append(self)
 136         return result
 137
 138
 139 class clearclass(attr):
 140
 141     """a special attribute which allows to remove all predecessing attributes of
 142     the same type in an attribute list"""
 143
 144     def __init__(self, clearclass):
 145         self.clearclass = clearclass
 146
 147     def merge(self, attrs):
 148         return [attr for attr in attrs if not isinstance(attr, self.clearclass)]
 149
 150
 151 class _clear(attr):
 152
 153     """a special attribute which removes all predecessing attributes
 154     in an attribute list"""
 155
 156     def merge(self, attrs):
 157         return []
 158
 159 # we define the attribute "clear", an instance of "_clear",
 160 # which can be used to remove all predecessing attributes
 161 # in an attribute list
 162
 163 clear = _clear()
 164
 165 #
 166 # changeable attrs
 167 #
 168
 169 def selectattrs(attrs, index, total):
 170     """performs select calls for all changeable attributes and
 171     returns the resulting attribute list
 172     - attrs should be a list containing attributes and changeable
 173       attributes
 174     - index should be an unsigned integer
 175     - total should be a positive number
 176     - valid sections fullfill 0<=index<total
 177     - returns None, when attrs is None
 178     - returns None, when a changeable attribute returns None"""
 179     if attrs is None:
 180         return None
 181     result = []
 182     for a in attrs:
 183         if isinstance(a, changeattr):
 184             select = a.select(index, total)
 185             if select is None:
 186                 return None
 187             result.append(select)
 188         else:
 189             result.append(a)
 190     return result
 191
 192
 193 def selectattr(attr, index, total):
 194     """as select, but for a single attribute"""
 195     if isinstance(attr, changeattr):
 196         select = attr.select(index, total)
 197         if select is None:
 198             return None
 199         return select
 200     else:
 201         return attr
 202
 203
 204 class changeattr:
 205
 206     """changeattr is the base class of all changeable attributes"""
 207
 208     def select(self, index, total):
 209         """returns an attribute for a given index out of a total number
 210         if attributes to be provided
 211         - index should be an unsigned integer
 212         - total should be a positive number
 213         - valid selections fullfill 0 <= index < total
 214         - the select method may raise a ValueError, when the
 215           changeable attribute does not allow for a requested
 216           selection"""
 217
 218         raise RuntimeError("not implemented")
 219
 220
 221 class changelist(changeattr):
 222
 223     """a changeable attribute over a list of attribute choises"""
 224
 225     def __init__(self, attrs, cyclic=1):
 226         """initializes the instance
 227         - attrs is a list of attributes to cycle
 228         - If cyclic is set, we restart from the beginning after
 229           the end of the list has been reached; otherwise
 230           selecting beyond the end of the list returns None"""
 231         self.attrs = attrs
 232         self.cyclic = cyclic
 233
 234     def select(self, index, total):
 235         if self.cyclic:
 236             return self.attrs[index % len(self.attrs)]
 237         elif index < len(self.attrs):
 238             return self.attrs[index]
 239         else:
 240             return None
 241
 242
 243 class multichangeattr(changeattr):
 244
 245     """a changeable attr, which selects a changeable attr from
 246     a given dict (or list) of changeable attrs depending on the
 247     value of total in the select call"""
 248
 249     def __init__(self, changeattrs):
 250         self.changeattrs = changeattrs
 251
 252     def select(self, index, total):
 253         return self.changeattrs[total].select(index, total)
 254