1#!/usr/bin/env python
2# -*- coding: utf-8 -*-
3
4"""
5Format management.
6
7
8Creating new formats
9--------------------
10
11A new format named 'foo-bar' corresponds to Python module
12'tracetool/format/foo_bar.py'.
13
14A format module should provide a docstring, whose first non-empty line will be
15considered its short description.
16
17All formats must generate their contents through the 'tracetool.out' routine.
18
19
20Format functions
21----------------
22
23All the following functions are optional, and no output will be generated if
24they do not exist.
25
26======== =======================================================================
27Function Description
28======== =======================================================================
29begin    Called to generate the format-specific file header.
30end      Called to generate the format-specific file footer.
31nop      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
44import os
45
46import tracetool
47
48
49def 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 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
74def 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
82def _empty(events):
83    pass
84
85def 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
95def 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)
104