gtkdoc-depscan.in

   1 #!@PYTHON@
   2
   3 import gzip, os.path, re
   4
   5 from os import environ, popen, walk
   6 from optparse import OptionParser
   7 from sys import stderr
   8
   9 from xml.sax import ContentHandler, make_parser
  10 from xml.sax.handler import feature_external_ges
  11
  12 default_books = ['atk', 'gdk', 'gdk-pixbuf', 'glib', 'gio', 'gobject', 'gtk', 'pango']
  13
  14 __comment_regex = re.compile(r'/\*.*?\*/', re.DOTALL)
  15 __word_regex = re.compile(r'\b[A-Za-z_][A-Za-z0-9_]*\b')
  16
  17 class Book(object):
  18     def __init__(self, name, folders, version=None):
  19         self.__catalog   = None
  20         self.__name      = name
  21         self.__symbols   = None
  22         self.__timestamp = 0
  23         self.__title     = None
  24         self.__version   = version
  25
  26         for f in folders:
  27             catalogs = map(
  28                 lambda n: os.path.join(f, name, n % name),
  29                 ['%s.devhelp2', '%s.devhelp2.gz'])
  30             catalogs = map(
  31                 lambda n: (os.path.getmtime(n), n),
  32                 filter(os.path.isfile, catalogs))
  33
  34             catalogs.sort()
  35
  36             if catalogs:
  37                 self.__catalog = catalogs[-1][1]
  38                 break
  39
  40         if not self.__catalog:
  41             raise IOError, 'No devhelp book found for "%s"' % name
  42
  43     def __cmp__(self, other):
  44         if isinstance(other, Book):
  45             return cmp(self.name, other.name)
  46
  47         return 0
  48
  49     def __repr__(self):
  50         return '<Book name="%s">' % self.__name
  51
  52     def parse(self):
  53         timestamp = os.path.getmtime(self.__catalog)
  54
  55         if not self.__symbols or timestamp > self.__timestamp:
  56             class DevhelpContentHandler(ContentHandler):
  57                 def __init__(self, book, symbols):
  58                     self.__book = book
  59                     self.__symbols = symbols
  60
  61                 def startElement(self, name, attrs):
  62                     if 'book' == name:
  63                         self.title = attrs.get('title')
  64                         return
  65
  66                     if 'keyword' == name:
  67                         symbol = Symbol.from_xml(self.__book, attrs)
  68                         if symbol: self.__symbols[symbol.name] = symbol
  69                         return
  70
  71             self.__symbols, self.__timestamp = dict(), timestamp
  72             handler = DevhelpContentHandler(self, self.__symbols)
  73
  74             parser = make_parser()
  75             parser.setFeature(feature_external_ges, False)
  76             parser.setContentHandler(handler)
  77
  78             if self.__catalog.endswith('.gz'):
  79                 parser.parse(gzip.open(self.__catalog))
  80
  81             else:
  82                 parser.parse(open(self.__catalog))
  83
  84             self.__title = handler.title
  85
  86     def _get_symbols(self):
  87         self.parse(); return self.__symbols
  88     def _get_title(self):
  89         self.parse(); return self.__title
  90
  91     def find_requirements(self):
  92         requirements = dict()
  93
  94         for symbol in self.symbols.values():
  95             if not symbol.matches:
  96                 continue
  97
  98             if symbol.since and symbol.since > self.version:
  99                 symbol_list = requirements.get(symbol.since, [])
 100                 requirements[symbol.since] = symbol_list
 101                 symbol_list.append(symbol)
 102
 103         return requirements
 104
 105     catalog = property(lambda self: self.__catalog)
 106     name    = property(lambda self: self.__name)
 107     version = property(lambda self: self.__version)
 108
 109     symbols = property(_get_symbols)
 110     title   = property(_get_title)
 111
 112 class Symbol(object):
 113     known_attributes = ('name', 'type', 'link', 'deprecated', 'since')
 114
 115     class DeprecationInfo(object):
 116         def __init__(self, text):
 117             if text.count(':'):
 118                 pair = text.split(':', 1)
 119
 120                 self.__version = Symbol.VersionInfo(pair[0])
 121                 self.__details = pair[1].strip()
 122
 123             else:
 124                 self.__version = None
 125                 self.__details = text.strip()
 126
 127         def __cmp__(self, other):
 128             if isinstance(other, Symbol.DeprecationInfo):
 129                 return cmp(self.version, other.version)
 130
 131             if isinstance(other, Symbol.VersionInfo):
 132                 return cmp(self.version, other)
 133
 134             return 1
 135
 136         def __str__(self):
 137             if not self.__version:
 138                 return self.__details and str(self.__details) or 'Deprecated'
 139
 140             if self.__details:
 141                 return 'Since %s: %s' % (self.__version, self.__details)
 142
 143             return 'Since %s' % self.__version
 144
 145         details = property(lambda self: self.__details)
 146         version = property(lambda self: self.__version)
 147
 148     class VersionInfo(object):
 149         def __init__(self, text):
 150             match = re.match(r'^\w*\s*((?:\d+\.)*\d+)', text)
 151
 152             self.__numbers = map(int, match.group(1).split('.'))
 153             self.__hash = reduce(lambda x, y: x * 1000 + y, reversed(self.__numbers))
 154             self.__text = text.strip()
 155
 156         def __get_number(self, index):
 157             if len(self.__numbers) > index:
 158                 return self.__numbers[index]
 159
 160             return 0
 161
 162         def __cmp__(self, other):
 163             if isinstance(other, Symbol.VersionInfo):
 164                 return cmp(self.numbers, other.numbers)
 165
 166             return 1
 167
 168         def __hash__(self):
 169             return self.__hash
 170
 171         def __repr__(self):
 172             return '.'.join(map(str, self.__numbers))
 173
 174         major   = property(lambda self: self.__get_number(0))
 175         minor   = property(lambda self: self.__get_number(1))
 176         patch   = property(lambda self: self.__get_number(2))
 177         numbers = property(lambda self: self.__numbers)
 178         text    = property(lambda self: self.__text)
 179
 180     @classmethod
 181     def from_xml(cls, book, attrs):
 182         name, type, link, deprecated, since = map(attrs.get, Symbol.known_attributes)
 183
 184         name = name.strip()
 185
 186         if name.endswith('()'):
 187             if not type in ('function', 'macro'):
 188                 type = (name[0].islower() and 'function' or 'macro')
 189
 190             name = name[:-2].strip()
 191
 192         words = name.split(' ')
 193
 194         if len(words) > 1:
 195             if words[0] in ('enum', 'struct', 'union'):
 196                 if not type: type = words[0]
 197                 name = name[len(words[0]):].strip()
 198             elif 'property' == words[-1]:
 199                 assert('The' == words[0])
 200                 owner = link.split('#', 1)[1].split('-', 1)[0]
 201                 type, name = 'property', '%s::%s' % (owner, name.split('"')[1])
 202             elif 'signal' == words[-1]:
 203                 assert('The' == words[0])
 204                 owner = link.split('#', 1)[1].split('-', 1)[0]
 205                 type, name = 'signal', '%s:%s' % (owner, name.split('"')[1])
 206
 207         if not type: return None
 208
 209         if None != deprecated: deprecated = Symbol.DeprecationInfo(deprecated)
 210         if since: since = Symbol.VersionInfo(since)
 211
 212         if name.count(' '):
 213             print >>stderr, (
 214                 'WARNING: Malformed symbol name: "%s" (type=%s) in %s.' % (
 215                 name, type, book.name))
 216
 217         return Symbol(book, name, type, link, deprecated, since)
 218
 219     def __init__(self, book, name, type, link=None, deprecated=None, since=None):
 220         self.__book       = book
 221         self.__name       = name
 222         self.__type       = type
 223         self.__link       = link
 224         self.__deprecated = deprecated
 225         self.__since      = since
 226         self.__matches    = []
 227
 228     def __repr__(self):
 229         return (
 230             '<Symbol: %s, type=%s, since=%s, deprecated=%s>' % (
 231             self.name, self.type, self.since, self.deprecated))
 232
 233
 234     book       = property(lambda self: self.__book)
 235     name       = property(lambda self: self.__name)
 236     type       = property(lambda self: self.__type)
 237     link       = property(lambda self: self.__link)
 238     deprecated = property(lambda self: self.__deprecated)
 239     matches    = property(lambda self: self.__matches)
 240     since      = property(lambda self: self.__since)
 241
 242 def parse_cmdline():
 243     options = OptionParser(version="@VERSION@")
 244
 245     options.add_option('-b', '--book', dest='books',
 246                        help='name of a devhelp book to consider',
 247                        default=[], action='append')
 248     options.add_option('-d', '--html-dir', metavar='PATH', dest='dirs',
 249                        help='path of additional folders with devhelp books',
 250                        default=[], action='append')
 251     options.add_option('-s', '--summarize', action='store_true', default=False,
 252                        help='print only a brief summary', dest='summarize')
 253     options.add_option('-u', '--list-unknown', action='store_true', default=False,
 254                        help='list symbols not found in any book', dest='unknown')
 255     options.add_option('-v', '--verbose', action='store_true', default=False,
 256                        help='print additional information')
 257
 258     return options.parse_args()
 259
 260 def merge_gnome_path(options):
 261     path = environ.get('GNOME2_PATH')
 262     path = path and path.split(':') or []
 263
 264     prefix = popen(
 265         'pkg-config --variable=prefix glib-2.0'
 266         ).readline().rstrip()
 267
 268     path.insert(0, prefix)
 269     path = filter(None, [p.strip() for p in path])
 270
 271     path = [[
 272         os.path.join(p, 'share', 'devhelp', 'books'),
 273         os.path.join(p, 'share', 'gtk-doc', 'html')]
 274         for p in path]
 275
 276     path = reduce(list.__add__, path)
 277     path = filter(os.path.isdir, path)
 278
 279     options.dirs += path
 280
 281 def summarize_matches(matches):
 282     counts = {}
 283     for filename, lineno, symbol in matches:
 284         if not isinstance(symbol, Symbol):
 285             if options.verbose:
 286                 print '%s:%d: unknown symbol %s' % (filename, lineno, symbol)
 287             continue
 288
 289         since = '%s-%s' % (symbol.book.name, symbol.since)
 290         name = symbol.name
 291         if since not in counts:
 292             counts[since] = {}
 293         counts[since][name] = counts[since].get(name, 0) + 1
 294
 295     for since, stats in counts.items():
 296         counts[since] = list(sorted(stats.items(), key=lambda x: -x[1]))
 297
 298     return counts
 299
 300 if '__main__' == __name__:
 301     options, args = parse_cmdline()
 302
 303     merge_gnome_path(options)
 304
 305     if not options.books:
 306         options.books = default_books
 307
 308     def trace(message, *args):
 309         if options.verbose: print message % args
 310
 311     def parse_book(name):
 312         try:
 313             match = re.match(r'^(.*?)(?::(\d+(?:\.\d+)*))?$', name)
 314             name, version = match.groups()
 315             trace('reading book: %s', name)
 316
 317             version = version and Symbol.VersionInfo(version)
 318             return name, Book(name, options.dirs, version)
 319
 320         except IOError, e:
 321             print >>stderr, 'WARNING: %s.' % e
 322
 323     def scan_source_file(name):
 324         contents = None
 325
 326         try:
 327             contents = __comment_regex.sub('', file(name).read())
 328
 329         except IOError, e:
 330             print >>stderr, e
 331
 332         if contents:
 333             trace('scanning: %s', name)
 334             lines = contents.split('\n')
 335
 336             for lineno in range(len(lines)):
 337                 for word in __word_regex.findall(lines[lineno]):
 338                     symbol = symbols.get(word)
 339
 340                     if symbol:
 341                         symbol.matches.append((name, lineno, symbol))
 342
 343                     elif options.unknown and word.find('_') > 0:
 344                         unknown_symbols.append((name, lineno, word))
 345
 346     unknown_symbols = []
 347     matches, symbols = dict(), dict()
 348     books = dict(filter(None, map(parse_book, set(options.books))))
 349
 350     for book in books.values():
 351         symbols.update(book.symbols)
 352
 353     for name in args:
 354         if os.path.isdir(name):
 355             for path, dirs, files in walk(name):
 356                 for f in files:
 357                     if f.endswith('.c'):
 358                         scan_source_file(os.path.join(path, f))
 359
 360         else:
 361             scan_source_file(name)
 362
 363     matches = []
 364
 365     for book in books.values():
 366         requirements = book.find_requirements().items()
 367         requirements.sort()
 368
 369         if requirements:
 370             for symbol in requirements[-1][1]:
 371                 matches += symbol.matches
 372
 373     if options.unknown:
 374         matches += unknown_symbols
 375
 376     matches.sort()
 377
 378     if options.summarize:
 379         summary = summarize_matches(matches)
 380         for since in sorted(summary.keys()):
 381             print '%s required for' % since
 382             for x in summary[since]:
 383                 print '    %u %s' % (x[1], x[0])
 384     else:
 385         for filename, lineno, symbol in matches:
 386             if isinstance(symbol, Symbol):
 387                 args = filename, lineno, symbol.book.name, symbol.since, symbol.name
 388                 print '%s:%d: %s-%s required for %s' % args
 389
 390             elif options.verbose:
 391                 print '%s:%d: unknown symbol %s' % (filename, lineno, symbol)
 392
 393     if options.unknown:
 394         unknown = [m[2].split('_')[0].lower() for m in unknown_symbols]
 395         unknown = list(set(unknown))
 396         unknown.sort()
 397
 398         print 'unknown prefixes: %s' % ', '.join(unknown)
 399
 400     raise SystemExit(matches and 1 or 0)