docs: def flatten(self, lst=None):
          """syntax.flatten(token_stream) - compile period tokens
  
          This turns a stream of tokens into p-code for the trivial
          stack machine that evaluates period expressions in in_period.
          """
          tree = []
          uops = []                       # accumulated unary operations
          s = Stack()
          group_len = 0                   # in current precendence group
          for item in lst:
              if type(item) == type([]):
                  # Subexpression.
                  tree = tree + self.flatten(item)
                  group_len = group_len + 1
                  # Unary ops dump, for things like: '!(Monday|Wednesday)'
                  for uop in uops:
                      tree.append(uop)
                  uops = []
              elif item in self.ops and item not in self.uops:
                  # Operator.
                  if not s.empty():
                      prev_op = s.pop()
                      # If the precendence of the previous operation is
                      # higher then dump out everything so far, ensuring the
                      # order of evaluation.
                      if _precedence[prev_op] > _precedence[item]:
                          s.push(prev_op)  # put it back
                          for i in range(group_len - 1):
                              tree.append(s.pop())
                          group_len = 0
                      else:
                          s.push(prev_op)
                      s.push(item)
                  else:
                      s.push(item)
              elif item in self.uops:
                  uops.append(item)
              else:
                  # Token of some sort.
                  tree.append(item)
                  group_len = group_len + 1
                  # Dump any unary operations.
                  for uop in uops:
                      tree.append(uop)
                  uops = []
  
          while not s.empty():
              tree.append(s.pop())
  
          # Drop any remaining unary operations.
          for uop in uops:
              tree.append(uop)
  
          return tree