[analyzer] exploded-graph-rewriter: Improve user-friendliness.

[NoQ]

Summary

Change the default behavior: the tool no longer dumps the rewritten .dot file to stdout, but instead it automatically converts it into an .html file (which essentially wraps an .svg file) and immediately opens it with the default web browser.

This means that the tool should be fairly easy to use:

$ exploded-graph-rewriter.py /tmp/ExprEngine.dot

The benefits of wrapping the .svg file into an .html file are:

• It'll open in a web browser, which is the intended behavior. An .svg file would be open with an image viewer/editor instead.
• It avoids the white background around the otherwise dark svg area in dark mode.

I also added more help text so that it was easier to figure out how to use the tool (suggestions are welcome!).

The new feature bypasses tests because i don't expect everybody (esp. buildbots) to have python-graphviz installed. The LIT substitution is specifically tweaked to enforce the old mode.

TODO: Add a -o flag to specify the output file.

[NoQ]

Make it a soft failure when graphviz is not installed. Display a friendly warning.

[NoQ]

Polish wording a bit.

[grandinj]

There is no need to wrap SVG in HTML if you want to display it in a web-browser, you can just open the web-browser explicitly, they already support opening SVG, use something like

webbrowser.open_new(url)

i.e. https://docs.python.org/2/library/webbrowser.html

[NoQ]

In D65250#1600776, @grandinj wrote:

There is no need to wrap SVG in HTML if you want to display it in a web-browser, you can just open the web-browser explicitly, they already support opening SVG, use something like

webbrowser.open_new(url)

i.e. https://docs.python.org/2/library/webbrowser.html

Mmm, interesting, maybe, but i don't see any obvious reasons to keep it in svg either. With html you can also save it and open up later without messing up your MIME associations, or even send it to others without having them mess with their MIME associations. With html you can also avoid the dark background glitch (the svg has limited size and would otherwise be displayed as a dark rectangle over a white background). Also it opens up opportunities for scripting, if we ever go that far (even if this gets more and more hacky). I guess i could do your suggestion under an --svg flag, but i'll prefer to have it off by default, because html is slightly better for most purposes. I guess it's worth it when the recipient doesn't trust html attachments (eg., for sending to the mailing lists).

[Charusso]

In D65250#1601187, @NoQ wrote:

In D65250#1600776, @grandinj wrote:

There is no need to wrap SVG in HTML if you want to display it in a web-browser

I guess it's worth it when the recipient doesn't trust html attachments (eg., for sending to the mailing lists).

You could put HTML inside the SVG (https://developer.mozilla.org/en-US/docs/Web/SVG/Element/foreignObject). That is a cool feature just I have not managed to use it yet, but I would use it for better performance in loading the SVG, and that definitely needs an HTML wrapper.

[Charusso]

I like the HTML output, thanks!

clang/utils/analyzer/exploded-graph-rewriter.py

846 ↗

(On Diff #211640)

Why we need multiple prints to print one message? According to the Stack Overflow:

print("""
Line1
Line2
""")

Link: https://stackoverflow.com/questions/34980251/how-to-print-multiple-lines-of-text-with-python

953 ↗

(On Diff #211640)

This flag is a little-bit too long and does not really emphasize what it suppose to do. What about just --dump or --stdout?

[NoQ]

clang/utils/analyzer/exploded-graph-rewriter.py

846 ↗

(On Diff #211640)

I dislike what it does to my formatting. We're in 4 nested scopes and it suddenly requires me to make an un-indented block.

953 ↗

(On Diff #211640)

Renamed to --dump-dot-only.

cfe/trunk/test/Analysis/exploded-graph-rewriter/lit.local.cfg

 # -*- Python -*-
 
 import lit.util
 import lit.formats
 import os
 
 use_lit_shell = os.environ.get("LIT_USE_INTERNAL_SHELL")
 config.test_format = lit.formats.ShTest(use_lit_shell == "0")
 
 config.substitutions.append(('%exploded_graph_rewriter',
-                             '\'%s\' %s' % (
+                             '\'%s\' %s --dump-dot-only' % (
                                  config.python_executable,
                                  lit.util.which('exploded-graph-rewriter.py',
                                                 os.path.join(
                                                     config.clang_src_dir,
                                                     'utils', 'analyzer')))))
 
 config.suffixes.add('.dot')

cfe/trunk/utils/analyzer/exploded-graph-rewriter.py

 # Visitors traverse a deserialized ExplodedGraph and do different things
 # with every node and edge.
 #===-----------------------------------------------------------------------===#
 
 
 # A visitor that dumps the ExplodedGraph into a DOT file with fancy HTML-based
 # syntax highlighing.
 class DotDumpVisitor(object):
-    def __init__(self, do_diffs, dark_mode, gray_mode, topo_mode):
+    def __init__(self, do_diffs, dark_mode, gray_mode,
+                 topo_mode, dump_dot_only):
         super(DotDumpVisitor, self).__init__()
         self._do_diffs = do_diffs
         self._dark_mode = dark_mode
         self._gray_mode = gray_mode
         self._topo_mode = topo_mode
+        self._dump_dot_only = dump_dot_only
+        self._output = []
 
-    @staticmethod
-    def _dump_raw(s):
+    def _dump_raw(self, s):
+        if self._dump_dot_only:
             print(s, end='')
+        else:
+            self._output.append(s)
+
+    def output(self):
+        assert not self._dump_dot_only
+        return ''.join(self._output)
 
     def _dump(self, s):
         s = s.replace('&', '&') \
              .replace('{', '\\{') \
              .replace('}', '\\}') \
              .replace('\\<', '&lt;') \
              .replace('\\>', '&gt;') \
              .replace('\\l', '<br />') \
def visit_edge(self, pred, succ):
         self._dump_raw('%s -> %s%s;\n' % (
             pred.node_name(), succ.node_name(),
             ' [color="white"]' if self._dark_mode else ''
         ))
 
     def visit_end_of_graph(self):
         self._dump_raw('}\n')
 
+        if not self._dump_dot_only:
+            import sys
+            import tempfile
+
+            def write_temp_file(suffix, data):
+                fd, filename = tempfile.mkstemp(suffix=suffix)
+                print('Writing "%s"...' % filename)
+                with os.fdopen(fd, 'w') as fp:
+                    fp.write(data)
+                print('Done! Please remember to remove the file.')
+                return filename
+
+            try:
+                import graphviz
+            except ImportError:
+                # The fallback behavior if graphviz is not installed!
+                print('Python graphviz not found. Please invoke')
+                print('  $ pip install graphviz')
+                print('in order to enable automatic conversion to HTML.')
+                print()
+                print('You may also convert DOT to SVG manually via')
+                print('  $ dot -Tsvg input.dot -o output.svg')
+                print()
+                write_temp_file('.dot', self.output())
+                return
+
+            svg = graphviz.pipe('dot', 'svg', self.output())
+
+            filename = write_temp_file(
+                '.html', '<html><body bgcolor="%s">%s</body></html>' % (
+                             '#1a1a1a' if self._dark_mode else 'white', svg))
+            if sys.platform == 'win32':
+                os.startfile(filename)
+            elif sys.platform == 'darwin':
+                os.system('open "%s"' % filename)
+            else:
+                os.system('xdg-open "%s"' % filename)
+
 
 #===-----------------------------------------------------------------------===#
 # Explorers know how to traverse the ExplodedGraph in a certain order.
 # They would invoke a Visitor on every node or edge they encounter.
 #===-----------------------------------------------------------------------===#
 
 
 # BasicExplorer explores the whole graph in no particular order.

 
 
 #===-----------------------------------------------------------------------===#
 # The entry point to the script.
 #===-----------------------------------------------------------------------===#
 
 
 def main():
-    parser = argparse.ArgumentParser()
-    parser.add_argument('filename', type=str)
+    parser = argparse.ArgumentParser(
+        description='Display and manipulate Exploded Graph dumps.')
+    parser.add_argument('filename', type=str,
+                        help='the .dot file produced by the Static Analyzer')
     parser.add_argument('-v', '--verbose', action='store_const',
                         dest='loglevel', const=logging.DEBUG,
                         default=logging.WARNING,
                         help='enable info prints')
     parser.add_argument('-d', '--diff', action='store_const', dest='diff',
                         const=True, default=False,
                         help='display differences between states')
     parser.add_argument('-t', '--topology', action='store_const',
                         dest='topology', const=True, default=False,
                         help='only display program points, omit states')
     parser.add_argument('-s', '--single-path', action='store_const',
                         dest='single_path', const=True, default=False,
                         help='only display the leftmost path in the graph '
                              '(useful for trimmed graphs that still '
                              'branch too much)')
     parser.add_argument('--dark', action='store_const', dest='dark',
                         const=True, default=False,
                         help='dark mode')
     parser.add_argument('--gray', action='store_const', dest='gray',
                         const=True, default=False,
                         help='black-and-white mode')
+    parser.add_argument('--dump-dot-only', action='store_const',
+                        dest='dump_dot_only', const=True, default=False,
+                        help='instead of writing an HTML file and immediately '
+                             'displaying it, dump the rewritten dot file '
+                             'to stdout')
     args = parser.parse_args()
     logging.basicConfig(level=args.loglevel)
 
     graph = ExplodedGraph()
     with open(args.filename) as fd:
         for raw_line in fd:
             raw_line = raw_line.strip()
             graph.add_raw_line(raw_line)
 
     explorer = SinglePathExplorer() if args.single_path else BasicExplorer()
-    visitor = DotDumpVisitor(args.diff, args.dark, args.gray, args.topology)
+    visitor = DotDumpVisitor(args.diff, args.dark, args.gray, args.topology,
+                             args.dump_dot_only)
 
     explorer.explore(graph, visitor)
 
 
 if __name__ == '__main__':
     main()