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-2014, 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 os
  45
  46 import tracetool
  47
  48
  49 def get_list():
  50     """Get a list of (name, description) pairs."""
  51     res = []
  52     modnames = []
  53     for filename in os.listdir(tracetool.format.__path__[0]):
  54         if filename.endswith('.py') and filename != '__init__.py':
  55             modnames.append(filename.rsplit('.', 1)[0])
  56     for modname in sorted(modnames):
  57         module = tracetool.try_import("tracetool.format." + modname)
  58
  59         # just in case; should never fail unless non-module files are put there
  60         if not module[0]:
  61             continue
  62         module = module[1]
  63
  64         doc = module.__doc__
  65         if doc is None:
  66             doc = ""
  67         doc = doc.strip().split("\n")[0]
  68
  69         name = modname.replace("_", "-")
  70         res.append((name, doc))
  71     return res
  72
  73
  74 def exists(name):
  75     """Return whether the given format exists."""
  76     if len(name) == 0:
  77         return False
  78     name = name.replace("-", "_")
  79     return tracetool.try_import("tracetool.format." + name)[1]
  80
  81
  82 def _empty(events):
  83     pass
  84
  85 def generate_begin(name, events):
  86     """Generate the header of the format-specific file."""
  87     if not exists(name):
  88         raise ValueError("unknown format: %s" % name)
  89
  90     name = name.replace("-", "_")
  91     func = tracetool.try_import("tracetool.format." + name,
  92                                 "begin", _empty)[1]
  93     func(events)
  94
  95 def generate_end(name, events):
  96     """Generate the footer of the format-specific file."""
  97     if not exists(name):
  98         raise ValueError("unknown format: %s" % name)
  99
 100     name = name.replace("-", "_")
 101     func = tracetool.try_import("tracetool.format." + name,
 102                                 "end", _empty)[1]
 103     func(events)