scripts/tracetool/format/__init__.py

   1 #!/usr/bin/env python
   2 # -*- coding: utf-8 -*-
   3
   4 """
   5 Format management.
   6
   7
   8 Creating new formats
   9 --------------------
  10
  11 A new format named 'foo-bar' corresponds to Python module
  12 'tracetool/format/foo_bar.py'.
  13
  14 A format module should provide a docstring, whose first non-empty line will be
  15 considered its short description.
  16
  17 All formats must generate their contents through the 'tracetool.out' routine.
  18
  19
  20 Format functions
  21 ----------------
  22
  23 All the following functions are optional, and no output will be generated if
  24 they do not exist.
  25
  26 ======== =======================================================================
  27 Function Description
  28 ======== =======================================================================
  29 begin    Called to generate the format-specific file header.
  30 end      Called to generate the format-specific file footer.
  31 nop      Called to generate the per-event contents when the event is disabled or
  32          the selected backend is 'nop'.
  33 ======== =======================================================================
  34 """
  35
  36 __author__     = "Lluís Vilanova <vilanova@ac.upc.edu>"
  37 __copyright__  = "Copyright 2012, Lluís Vilanova <vilanova@ac.upc.edu>"
  38 __license__    = "GPL version 2 or (at your option) any later version"
  39
  40 __maintainer__ = "Stefan Hajnoczi"
  41 __email__      = "stefanha@linux.vnet.ibm.com"
  42
  43
  44 import pkgutil
  45
  46 import tracetool
  47
  48
  49 def get_list():
  50     """Get a list of (name, description) pairs."""
  51     res = []
  52     for _, modname, _ in pkgutil.iter_modules(tracetool.format.__path__):
  53         module = tracetool.try_import("tracetool.format." + modname)
  54
  55         # just in case; should never fail unless non-module files are put there
  56         if not module[0]:
  57             continue
  58         module = module[1]
  59
  60         doc = module.__doc__
  61         if doc is None:
  62             doc = ""
  63         doc = doc.strip().split("\n")[0]
  64
  65         name = modname.replace("_", "-")
  66         res.append((name, doc))
  67     return res
  68
  69
  70 def exists(name):
  71     """Return whether the given format exists."""
  72     if len(name) == 0:
  73         return False
  74     name = name.replace("-", "_")
  75     return tracetool.try_import("tracetool.format." + name)[1]
  76
  77
  78 def _empty(events):
  79     pass
  80
  81 def generate_begin(name, events):
  82     """Generate the header of the format-specific file."""
  83     if not exists(name):
  84         raise ValueError("unknown format: %s" % name)
  85
  86     name = name.replace("-", "_")
  87     func = tracetool.try_import("tracetool.format." + name,
  88                                 "begin", _empty)[1]
  89     func(events)
  90
  91 def generate_end(name, events):
  92     """Generate the footer of the format-specific file."""
  93     if not exists(name):
  94         raise ValueError("unknown format: %s" % name)
  95
  96     name = name.replace("-", "_")
  97     func = tracetool.try_import("tracetool.format." + name,
  98                                 "end", _empty)[1]
  99     func(events)