google · marrable · Jan 14, 2019 · Jan 14, 2019 · Jan 15, 2019 · Jan 16, 2019
diff --git a/textfsm/debugger.py b/textfsm/debugger.py
@@ -0,0 +1,335 @@
+#!/usr/bin/python
+#
+# Copyright 2011 Google Inc. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+""" Visual Debugger
+
+Provides a HTML-based debugging tool that allows authors of templates
+to view the behavior of templates when applied to some example CLI text.
+State changes are represented with color coding such that state
+transitions are clearly represented during parsing.
+
+Matches on lines are highlighted to show extracted values and hovering
+over a match shows the value and corresponding regex that was matched.
+"""
+from collections import namedtuple
+from textwrap import dedent
+
+import re
+
+LINE_SATURATION = 40
+LINE_LIGHTNESS = 60
+MATCH_SATURATION = 100
+MATCH_LIGHTNESS = 30
+
+
+class LineHistory(namedtuple('LineHistory', ['line', 'state', 'matches', 'match_index_pairs'])):
+ """" The match history for a given line when parsed using the FSM.
+
+ Contains the regex match objects for that line,
+ which are converted to indices for highlighting
+ """
+
+
+class MatchedPair(namedtuple('MatchPair', ['match_obj', 'rule'])):
+ """" Stores the line history when parsed using the FSM."""
+
+
+class StartStopIndex(namedtuple('StartStopIndex', ['start', 'end', 'value'])):
+ """Represents the start and stop indices of a match for a given template value."""
+ def __eq__(self, other):
+ return self.start == other.start and self.end == other.end
+
+ def __gt__(self, other):
+ return self.start > other.start
+
+
+class VisualDebugger(object):
+ """Responsible for building the parse history of a TextFSM object into a visual html doc. """
+
+ def __init__(self, fsm, cli_text):
+ self.fsm = fsm
+ self.cli_text = cli_text
+ self.state_colormap = {}
+
+ @staticmethod
+ def add_prelude_boilerplate(html_file):
+ prelude_lines = dedent('''
+ <!DOCTYPE html>
+ <html>
+ <head>
+ <meta charset='UTF-8'>
+ <title>visual debugger</title>
+ ''')
+
+ html_file.write(prelude_lines)
+
+ def build_state_colors(self):
+ """Basic colour wheel selection for state highlighting"""
+ cntr = 1
+ for state_name in self.fsm.states.keys():
+ self.state_colormap[state_name] = (67 * cntr) % 360
+ cntr += 1
+
+ @staticmethod
+ def hsl_css(h, s, l):
+ """Return the CSS string for HSL background color."""
+ return " background-color: hsl({},{}%,{}%);\n".format(h, s, l)
+
+ def add_css_styling(self, html_file):
+ css_prelude_lines = dedent('''
+ <style type='text/css'>
+ body {
+ font-family: Arial, Helvetica, sans-serif;
+ background-color: hsl(40, 1%, 25%);
+ margin: 0;
+ padding: 0;
+ }
+ h4 {
+ font-family: Arial, Helvetica, sans-serif;
+ color: white;
+ margin-top: 0;
+ }
+ .regex {
+ background-color: silver;
+ border: 2px;
+ border-style: solid;
+ border-color: black;
+ display: none;
+ border-radius: 5px;
+ padding: 0 10px;
+ }
+ .cli-title{
+ padding-top: 100px;
+ }
+ .states{
+ position: fixed;
+ background-color: dimgray;
+ width: 100%;
+ padding: 10px;
+ margin-top: 0;
+ box-shadow: 0 3px 8px #000000;
+ }
+ ''')
+
+ html_file.writelines(css_prelude_lines)
+
+ # Build and write state styling CSS
+ for state_name in self.fsm.states.keys():
+ state_block = [
+ ".{}{{\n".format(state_name),
+ self.hsl_css(
+ self.state_colormap[state_name],
+ LINE_SATURATION,
+ LINE_LIGHTNESS
+ ),
+ " border-radius: 5px;\n",
+ " padding: 0 10px;\n",
+ "}\n"
+ ]
+ html_file.writelines(state_block)
+
+ # Build and write state match styling CSS
+ new_parse_history = []
+ l_count = 0
+ for line in self.fsm.parse_history:
+
+ match_index_pairs = []
+
+ # Flatten match index structure
+ for match in line.matches:
+ for key in match.match_obj.groupdict().keys():
+ match_index_pairs.append(
+ StartStopIndex(
+ match.match_obj.start(key),
+ match.match_obj.end(key),
+ key
+ )
+ )
+
+ # Merge indexes that overlap due to multiple rule matches for a single line.
+ self.merge_indexes(match_index_pairs)
+ match_index_pairs.sort()
+
+ # Overwrite named tuple data member
+ line = line._replace(match_index_pairs=match_index_pairs)
+ new_parse_history.append(line)
+
+ # Generate CSS for match highlighting and on-hover regex display
+ if line.match_index_pairs:
+ match_count = 0
+ for index_pair in line.match_index_pairs:
+ match_block = [
+ ".{}-match-{}-{}{{\n".format(line.state, l_count, match_count),
+ self.hsl_css(
+ self.state_colormap[line.state],
+ MATCH_SATURATION,
+ MATCH_LIGHTNESS
+ ),
+ " border-radius: 5 px;\n",
+ " font-weight: bold;\n"
+ " color: white;\n",
+ " padding: 0 5px;\n",
+ "}\n",
+ ".{}-match-{}-{}:hover + .regex {{\n".format(line.state, l_count, match_count),
+ " display: inline;\n",
+ "}\n"
+ ]
+ html_file.writelines(match_block)
+ match_count += 1
+ l_count += 1
+
+ # Overwrite parse history from FSM with newly processed history
+ self.fsm.parse_history = new_parse_history
+
+ css_closing_lines = [
+ "</style>\n"
+ ]
+
+ html_file.writelines(css_closing_lines)
+
+ def merge_indexes(self, match_index_pairs):
+ """Merge overlapping index pairs that may occur due to multiple rule matches."""
+
+ def overlapping(index_a, index_b):
+ if index_a.end > index_b.start and index_a.start < index_b.end:
+ return True
+ if index_a.start < index_b.end and index_b.start < index_a.end:
+ return True
+ if index_a.start < index_b.start and index_a.end > index_b.end:
+ return True
+ if index_b.start < index_a.start and index_b.end > index_a.end:
+ return True
+
+ def merge_pairs(index_a, index_b):
+ start = 0
+ if index_a.start < index_b.start:
+ start = index_a.start
+ else:
+ start = index_b.start
+ if index_a.end < index_b.end:
+ end = index_b.end
+ else:
+ end = index_a.end
+ return StartStopIndex(start, end, [index_a.value, index_b.value])
+
+ for pair in match_index_pairs:
+ overlap = False
+ match_index_pairs.remove(pair)
+ for check_pair in match_index_pairs:
+ if overlapping(pair, check_pair):
+ overlap = True
+ match_index_pairs.remove(check_pair)
+ match_index_pairs.append(merge_pairs(pair, check_pair))
+ break
+ if not overlap:
+ match_index_pairs.append(pair)
+
+ def add_cli_text(self, html_file):
+ """Builds the HTML elements of the debug page including:
+ - Colored States Header Bar
+ - Highlighted CLI Text
+ """
+
+ cli_text_prelude = [
+ "</head>\n",
+ "<header class='states'>",
+ "<h4>States:</h4>\n"
+ ]
+
+ for state in self.state_colormap.keys():
+ cli_text_prelude += [
+ "<button style='font-weight: bold;' class='{}'>{}</button>\n".format(state, state)
+ ]
+
+ cli_text_prelude += [
+ "</header>\n",
+ "<body>\n",
+ "<h4 class='cli-title'>CLI Text:</h4>\n",
+ "<pre>\n"
+ ]
+
+ html_file.writelines(cli_text_prelude)
+
+ lines = self.cli_text.splitlines()
+ lines = [line + '\n' for line in lines]
+
+ # Process each line history and add highlighting where matches occur.
+ l_count = 0
+ for line_history in self.fsm.parse_history:
+ # Only process highlights where matches occur.
+ if line_history.match_index_pairs:
+ built_line = ""
+ prev_end = 0
+ match_count = 0
+
+ for index in line_history.match_index_pairs:
+ if index.start < 0 or index.end < 0:
+ continue
+
+ # Strip out useless pattern format characters and value label.
+ # Escape chevrons in regex pattern.
+ re_patterns = []
+ values = []
+ if type(index.value) is list:
+ values = index.value
+ for v in index.value:
+ value_pattern = self.fsm.value_map[v]
+ re_patterns.append(re.sub('\?P<.*?>', '', value_pattern).replace('<', '&lt').replace('>', '&gt'))
+ else:
+ values.append(index.value)
+ value_pattern = self.fsm.value_map[index.value]
+ re_patterns.append(re.sub('\?P<.*?>', '', value_pattern).replace('<', '&lt').replace('>', '&gt'))
+
+ # Build section of match and escape non HTML chevrons if present
+ built_line += (
+ lines[l_count][prev_end:index.start].replace('<', '&lt').replace('>', '&gt')
+ + "<span class='{}-match-{}-{}'>".format(line_history.state, l_count, match_count)
+ + lines[l_count][index.start:index.end].replace('<', '&lt').replace('>', '&gt')
+ + "</span><span class='regex'>{} >> {}</span>".format(', '.join(re_patterns), ', '.join(values))
+ )
+ prev_end = index.end
+ match_count += 1
+
+ built_line += lines[l_count][line_history.match_index_pairs[-1].end:].replace('<', '&lt').replace('>', '&gt')
+ lines[l_count] = built_line
+ else:
+ # Escape non HTML tag chevrons if present
+ lines[l_count] = lines[l_count].replace('<', '&lt').replace('>', '&gt')
+
+ # Add final span wrapping tag for line state color
+ lines[l_count] = ("<span class='{}'>".format(line_history.state)
+ + lines[l_count] + "</span>")
+ l_count += 1
+
+ # Close off document
+ end_body_end_html = dedent('''
+ </pre>
+ </body>
+ </html>
+ ''')
+
+ html_file.writelines(lines)
+
+ html_file.write(end_body_end_html)
+
+ def build_debug_html(self):
+ """Calls HTML building procedures in sequence to create debug HTML doc."""
+ with open("debug.html", "w+") as f:
+ self.add_prelude_boilerplate(f)
+ self.build_state_colors()
+ self.add_css_styling(f)
+ self.add_cli_text(f)