qc2html.py

Quake 的 各 种 文 档 格 式 说 明

  # bool = a.IsKnown(anchor)	# returns true if it is an anchor
  # file = a.GetFile(anchor)    # return Href of anchor
  # hidden variables
  # dictionary of anchors 
  #_known = {} # {"name":"module", ...}
  # duplicated anchors
  #_dupli = {} # {"name":[ "module1", "module2", ...], ...}
  # name of current module
  _currentMod ="" # "moduleName"
  # anchor pattern
  _apatn = regex.compile("<a[ \t]+name=\"\(\w[a-zA-Z0-9_---]*\)\">")
  def __init__(self, knownanchor):
    self.Required = {}
    self.Mods = Modules()
    self._known = {}
    self._dupli = {}
    # declare all known anchors
    #for kn in known:
    #  (file, anchlist) = kn 
    #  self.DeclareModule(file)
    #  for anch in anchlist:
    #    self.Declare(anch)
    #  self._currentMod = ""
    for file in knownanchor:
      self.LookForAnchors(file)
    return
  # a.LookForAnchors(file)
  #  try to find known anchors in file
  def LookForAnchors(self, file):
    text = FileRead(file)
    if text == None: # can't read file
      return
    self.DeclareModule(file)
    print "Looking for anchors in ", file
    pos = 0
    while(1):
      pos = self._apatn.search(text, pos)
      if pos<0: break
      pos = pos + len(self._apatn.group(0))
#      print "   Found: ", self._apatn.group(1)
      anchor = self._apatn.group(1)
      # 
      self.Declare(anchor)
      # hack: declare a required function
      if anchor[0:2] == "f_":
        self.Required[anchor] = 1
    self._currentMod = ""
    return
  # a.DeclareModule(mod)
  #  mod = name of current module
  def DeclareModule(self, file):
    self._currentMod = self.Mods.DeclarePath(file)
    return
  # a.Declare(anchor)
  #  anchor = string, name of an anchor detected
  #   Declare anchor, only if not known already
  def Declare(self, anchor):
    if self._currentMod == None  or self._currentMod == "":
      print "ERROR no current module"
      return
    # detect duplicate anchors
    if self._known.has_key(anchor): #  
      if self._known[anchor] != "":  # not a  predeclared anchor
        if not self._dupli.has_key(anchor): self._dupli[anchor] = []
        self._dupli[anchor].append( self._currentMod )
        return
    # declare anchor, only if not known
    self._known[anchor] = self._currentMod
  # a.PreDeclare(anchor)
  #  anchor = string, name of an anchor detected
  # Pre-declare anchor
  def PreDeclare(self, anchor):
    # do not pre-declare if already known
    if self._known.has_key(anchor): return
    # pre-declare anchor, only if not known
    self._known[anchor] = ""
  ## bool= a.IsKnown(anchor)
  ##  return 1 if anchor is really an achor
  def IsKnown(self, anchor):
    return self._known.has_key(anchor)
  ##
  ## file = a.GetFile(anchor)
  ##  file = file reference, for anchor, suitable for use in <A HREF="">
  def GetFile(self, anchor): 
    if not self._known.has_key(anchor):
      print "ERROR unknown anchor: ", anchor
      return ""
    mod = self._known[anchor] # get module name
    return FileHtml(self.Mods.GetFile(mod)) # get file name
  ##
  ## anchor = a.Href(anchor, title) 
  ##   <a href=" file(anchor) # anchor "> title </a>
  def Href(self, anchor, title):
    #return "<a href=\"" + self.GetFile(anchor) + "#" + pointer + "\">" + title + "</a>"
    return "<a href=\"" + "@-@%@-@" + anchor + "@-@%@-@"+ "#" + anchor + "\">" + title + "</a>"
  def LateResolve(self, text):
    liste = string.splitfields(text, "@-@%@-@")
    for l in xrange(1, len(liste), 2):
      liste[l]= self.GetFile(liste[l]) # anchor
    return string.joinfields(liste,"")
##
## Translation table: [ (ExpC, Sub ,FFun, Start), ... ]
##
class Translater:
  ExpC = None # compiler regular expression
  Sub = ""    # substitution string
  FFun = None # function to execute
  Start = 0   # 0 if invalid, -1 if no more position
  Size = 0    # size of match
  ##
  ## Initialise
  ##
  def __init__(self, t):
    (exp , sub, ffun) = t
    self.ExpC = regex.compile(exp)
    self.Sub = sub
    self.FFun = ffun
    self.Reset()
    return
  def Reset(self):
    self.Start = 0
    self.Size = 0
  ##
  ## find next occurence
  ##
  def FindNext(self, text, pos):
    if self.Start < 0:    # no more patterns of that kind
      return -1
    if (self.Start > 0)&(self.Start>=pos):   # position is valid
      return self.Start
    else:
      self.Start = self.ExpC.search(text,pos)  
      if self.Start >= 0:
        self.Size = self.ExpC.match(text,self.Start)
      return self.Start  #last posisition found
  ##
  ## apply function
  ##
  def ApplyFunction(self, infos):
    if self.FFun == None:
      return ""
    return self.FFun(self.ExpC, infos)
  ##
  ## translate some text
  ##
  def Translate(self, text):
    if self.Sub == None:
      return ""
    return regsub.sub(self.ExpC.realpat, self.Sub, text)   
##
## Add an anchor to translation table
##
def TransTableAdd(word):
  t=Translater( ("\\b\("+word+"\)\\b", "<A HREF=\"#\\1\">\\1</A>", None))
  TransTable.append(t)
  return
##
## Reset the translation table
##
def TransTableReset():
  for translater in TransTable:
    translater.Reset()
  return
# 
  
## Compile translation table from TransDef
#
TransTable = map(Translater,TransDef)



  
##
## Infos structure for functions
##
class Transform:
  FileName = ""  # Obtain the current File name from here
  BasePath = ""
  LineNumber = 0 # Obtain the current Line Number from here
  def __init__(self, file):
    # declare known keywords, for user-defined functions
    self.Keys = KeyWords(KeywordList)
    # declare anchors, for user-defined functions
    self.Anchs = Anchors(KnownAnchors)
    liste = self._getFileList(file)
    self.TransFileList(liste)
    return
  ##
  ## infos._getFileList()
  ##  find, in file,  a list of files to parse
  def _getFileList(self, file): 
    print "Looking for file definitions in %s" % file
    txt = FileRead(file)
    # find file names according to TransPattern
    patn = regex.compile(TransPattern) 
    liste=[]
    pos = 0
    while 1:
      pos = patn.search(txt,pos)
      if pos<0: break
      pos = pos+len(patn.group(0))
      name = patn.group(1)
      print "found ", name
      liste.append( name)
    # save list in HTM  
    res = []
    res.append("<html><head><title>")
    res.append("Modules of Quake-C")
    res.append("</title></head><body>")
    res.append("<base target=examine>")
    res.append("<h2>Quake-C modules</h2>")
    res.append("<small>Generated by <a href=\"qc2html.py\">qc2html.py</a><br>")
    res.append("Underpowered by <a href=\"http://www.python.org\">Python</a>.</small>")
    res.append("<p><ul>")
    for name in liste:
      (root, ext) = os.path.splitext(name) 
      res.append("<li> <a href=\"" + FileHtml(root) + "\">" + name + "</a>")
    res.append("</ul></p>")
    res.append("</body></html>")
    file = self.SaveHtmlRaw(file, string.joinfields(res,"\n"))
    # create a void
    #res = []
    #res.append("<html><body>")
    #res.append("<h2>Quake-C</h2>")
    #res.append("</body></html>")
    #vide = self.SaveHtmlRaw("void", string.joinfields(res,"\n"))
    # create a frame
    res = []
    res.append("<frameset cols=\"30%,*\">")
    res.append("  <frame src=\""+file+"\" name=menu>")
    res.append("  <frame src=\"qk-menu.htm\" name=content>")
    res.append("</frameset>")
    res.append("<noframes>")
    res.append("<h2>Your browser is not frame capable (shame)!</h2>")
    res.append("<p>Maybe you would like the <a href=\""+ file + "\">No frame version</a>.</p>")
    res.append("</noframes>")
    self.SaveHtmlRaw("index", string.joinfields(res,"\n"))   
    # transform all the files in the list
    return liste
  ##
  ## res = self.TransformText(text)
  ##  res= Transformed text
  ##
  def TransformText(self, text):
    #
    # Translate text
    #
    TransTableReset()	# Clear search indexes in translation table
    liste = []		# clear result
    pos = 0 		# current position
    end = 0 		# current length  
    textlen = len(text) # length of text
    while end < textlen:
      # find closest regular expression in translation table
      pos = textlen
      mintranslater = None
      for translater in TransTable:
        if translater.FindNext(text, end) < 0 : # no more patterns of that kind
          continue #next translater
        if translater.Start < pos: # check is closest pattern
          #print " pos = ", translater.Start, " for ", translater.Sub
          pos = translater.Start
          mintranslater = translater
      # Preserve text that wasn't matched by regular expressions
      liste.append( text[end:pos] )
      # Add result of regular expressions
      if pos >= textlen:  # no regular expressions were matched
        end = textlen 	  # jump to end of text
      else:               # one regular expression matched
        translater = mintranslater  
        # find end of matched area
        end = pos + translater.Size
        # text[pos:end] = matched expression
        # transform the matched area, with a function
        res = translater.ApplyFunction(self)
        # transform the matched area, with regsub
        res = res + translater.Translate(text[pos:end])
	# append result
        liste.append(res)
    return string.joinfields(liste,"") # faster than + on strings
  ##
  ## Transform a list of files
  ##
  def TransFileList(self, liste):
    #
    print "Transforming all files..."
    processed = []
    for name in liste:
      if name == None or len(name)<1: 
        continue
      file = name
      print "Parsing File", file
      try:
        text= FileRead(file)
      except:
        print "Can't read file " + file 
      if text != None:
        #declare module
        self.LineNumber = 0
        self.FileName = file
        self.BasePath = ""
        # make module current, for anchors
        self.Anchs.DeclareModule(file)
        # transform
        text = self.TransformText(text)
        processed.append((file, text))
#        self.SaveHtml(file, text) # temporary file
    # resolve anchors, once everything is processed
    for pro in processed:
      (file, text) = pro
      text = self.Anchs.LateResolve(text)
      self.SaveHtml(file, text)
    return
  def SaveHtmlRaw(self, file, text):
    file = FileHtml(file)
    print "Saving file: ", file
    try:
      FileWrite( (file , text)) 
    except:
      print "Can't write file " + file
    return file
  def SaveHtml(self, file, text):
    res = TransHtmlHead(file) + text + TransHtmlTrail(file)
    return self.SaveHtmlRaw(file, res)
#
    
#
# Parse all the files
#   
print "Parsing files..."
infos = Transform(ProgsSrc)