Experimental lexer generator: Clarify TransitionKeys.disjoint_keys.

tools/lexer_generator/transition_keys.py

 # Copyright 2013 the V8 project authors. All rights reserved.
 # Redistribution and use in source and binary forms, with or without
 # modification, are permitted provided that the following conditions are
 # met:
 #
 #     * Redistributions of source code must retain the above copyright
 #       notice, this list of conditions and the following disclaimer.
 #     * Redistributions in binary form must reproduce the above
 #       copyright notice, this list of conditions and the following
 #       disclaimer in the documentation and/or other materials provided
@@ skipping 143 matching lines @@
     else:
       raise Exception('bad key [%s]' % key)
 
   @staticmethod
   def character_class(graph, key_map):
     '''Processes 'graph' (a representation of a character class in the rule
     file), and constructs a TransitionKey based on it. 'key_map' contains
     already constructed aliases for character classes (they can be used in the
     new character class). It is a map from strings (character class names) to
     TransitionKeys. For example, graph might represent the character class
-    [a-z:digit:] where 'digit' is a previously constructed characte class found
+    [a-z:digit:] where 'digit' is a previously constructed character class found
     in "key_map".'''
     ranges = []
     assert graph[0] == 'CLASS' or graph[0] == 'NOT_CLASS'
     invert = graph[0] == 'NOT_CLASS'
     TransitionKey.__process_graph(graph[1], ranges, key_map)
     return TransitionKey.__key_from_ranges(invert, ranges)
 
   def matches_char(self, char):
     char = ord(char)
     # TODO class checks
@@ skipping 134 matching lines @@
           range_map[r[0]] = []
         range_map[r[0]].append(r[1])
     ranges = TransitionKey.__disjoint_keys(range_map)
     TransitionKey.__verify_ranges(ranges, False)
     return ranges
 
   @staticmethod
   def disjoint_keys(key_set):
     '''Takes a set of possibly overlapping TransitionKeys, returns a list of
     TransitionKeys which don't overlap and whose union is the same as the union
-    of the original key_set. key_set is a set of TransitionKeys.'''
+    of the original key_set. In addition, TransitionKeys are not merged, only
+    split.
+
+    For example, if key_set contains two TransitionKeys for ranges [1-10] and
+    [5-15], disjoint_keys returns a set of three TransitionKeys: [1-4], [5-10],
+    [11-16].'''
     ranges = TransitionKey.__disjoint_ranges_from_key_set(key_set)
     return map(lambda x : TransitionKey([x]), ranges)
 
   @staticmethod
   def inverse_key(key_set):
     '''Returns a TransitionKey which matches represents the inverse of the union
     of 'key_set'. The TransitionKeys contain a set of character ranges and a set
     of classes. The character ranges are inverted in relation to the latin_1
     character range, and the character classes are inverted in relation to all
     character classes in __class_bounds.'''
@@ skipping 59 matching lines @@
       elif last[1] + 1 < r[0]:
         inverted.append((last[1] + 1, r[0] - 1))
       last = r
     upper_bound = latin_1[1]
     if last == None:
       inverted.append(latin_1)
     elif last[1] < upper_bound:
       inverted.append((last[1] + 1, upper_bound))
     inverted += list(classes)
     return inverted