src/tools/docmaker/formatter.py

   1 #
   2 #  formatter.py
   3 #
   4 #    Convert parsed content blocks to a structured document (library file).
   5 #
   6 #  Copyright 2002, 2004, 2007, 2008, 2014 by
   7 #  David Turner.
   8 #
   9 #  This file is part of the FreeType project, and may only be used,
  10 #  modified, and distributed under the terms of the FreeType project
  11 #  license, LICENSE.TXT.  By continuing to use, modify, or distribute
  12 #  this file you indicate that you have read the license and
  13 #  understand and accept it fully.
  14
  15 #
  16 # This is the base Formatter class.  Its purpose is to convert a content
  17 # processor's data into specific documents (i.e., table of contents, global
  18 # index, and individual API reference indices).
  19 #
  20 # You need to sub-class it to output anything sensible.  For example, the
  21 # file `tohtml.py' contains the definition of the `HtmlFormatter' sub-class
  22 # to output HTML.
  23 #
  24
  25
  26 from sources import *
  27 from content import *
  28 from utils   import *
  29
  30
  31 ################################################################
  32 ##
  33 ##  FORMATTER CLASS
  34 ##
  35 class  Formatter:
  36
  37     def  __init__( self, processor ):
  38         self.processor   = processor
  39         self.identifiers = {}
  40         self.chapters    = processor.chapters
  41         self.sections    = processor.sections.values()
  42         self.block_index = []
  43
  44         # store all blocks in a dictionary
  45         self.blocks = []
  46         for section in self.sections:
  47             for block in section.blocks.values():
  48                 self.add_identifier( block.name, block )
  49
  50                 # add enumeration values to the index, since this is useful
  51                 for markup in block.markups:
  52                     if markup.tag == 'values':
  53                         for field in markup.fields:
  54                             self.add_identifier( field.name, block )
  55
  56         self.block_index = self.identifiers.keys()
  57         self.block_index.sort( key = index_key )
  58
  59     def  add_identifier( self, name, block ):
  60         if name in self.identifiers:
  61             # duplicate name!
  62             sys.stderr.write( "WARNING: duplicate definition for"
  63                               + " '" + name + "' "
  64                               + "in " + block.location() + ", "
  65                               + "previous definition in "
  66                               + self.identifiers[name].location()
  67                               + "\n" )
  68         else:
  69             self.identifiers[name] = block
  70
  71     #
  72     # formatting the table of contents
  73     #
  74     def  toc_enter( self ):
  75         pass
  76
  77     def  toc_chapter_enter( self, chapter ):
  78         pass
  79
  80     def  toc_section_enter( self, section ):
  81         pass
  82
  83     def  toc_section_exit( self, section ):
  84         pass
  85
  86     def  toc_chapter_exit( self, chapter ):
  87         pass
  88
  89     def  toc_index( self, index_filename ):
  90         pass
  91
  92     def  toc_exit( self ):
  93         pass
  94
  95     def  toc_dump( self, toc_filename = None, index_filename = None ):
  96         output = None
  97         if toc_filename:
  98             output = open_output( toc_filename )
  99
 100         self.toc_enter()
 101
 102         for chap in self.processor.chapters:
 103
 104             self.toc_chapter_enter( chap )
 105
 106             for section in chap.sections:
 107                 self.toc_section_enter( section )
 108                 self.toc_section_exit( section )
 109
 110             self.toc_chapter_exit( chap )
 111
 112         self.toc_index( index_filename )
 113
 114         self.toc_exit()
 115
 116         if output:
 117             close_output( output )
 118
 119     #
 120     # formatting the index
 121     #
 122     def  index_enter( self ):
 123         pass
 124
 125     def  index_name_enter( self, name ):
 126         pass
 127
 128     def  index_name_exit( self, name ):
 129         pass
 130
 131     def  index_exit( self ):
 132         pass
 133
 134     def  index_dump( self, index_filename = None ):
 135         output = None
 136         if index_filename:
 137             output = open_output( index_filename )
 138
 139         self.index_enter()
 140
 141         for name in self.block_index:
 142             self.index_name_enter( name )
 143             self.index_name_exit( name )
 144
 145         self.index_exit()
 146
 147         if output:
 148             close_output( output )
 149
 150     #
 151     # formatting a section
 152     #
 153     def  section_enter( self, section ):
 154         pass
 155
 156     def  block_enter( self, block ):
 157         pass
 158
 159     def  markup_enter( self, markup, block = None ):
 160         pass
 161
 162     def  field_enter( self, field, markup = None, block = None ):
 163         pass
 164
 165     def  field_exit( self, field, markup = None, block = None ):
 166         pass
 167
 168     def  markup_exit( self, markup, block = None ):
 169         pass
 170
 171     def  block_exit( self, block ):
 172         pass
 173
 174     def  section_exit( self, section ):
 175         pass
 176
 177     def  section_dump( self, section, section_filename = None ):
 178         output = None
 179         if section_filename:
 180             output = open_output( section_filename )
 181
 182         self.section_enter( section )
 183
 184         for name in section.block_names:
 185             skip_entry = 0
 186             try:
 187                 block = self.identifiers[name]
 188                 # `block_names' can contain field names also,
 189                 # which we filter out
 190                 for markup in block.markups:
 191                     if markup.tag == 'values':
 192                         for field in markup.fields:
 193                             if field.name == name:
 194                                 skip_entry = 1
 195             except:
 196                 skip_entry = 1   # this happens e.g. for `/empty/' entries
 197
 198             if skip_entry:
 199               continue
 200
 201             self.block_enter( block )
 202
 203             for markup in block.markups[1:]:   # always ignore first markup!
 204                 self.markup_enter( markup, block )
 205
 206                 for field in markup.fields:
 207                     self.field_enter( field, markup, block )
 208                     self.field_exit( field, markup, block )
 209
 210                 self.markup_exit( markup, block )
 211
 212             self.block_exit( block )
 213
 214         self.section_exit( section )
 215
 216         if output:
 217             close_output( output )
 218
 219     def  section_dump_all( self ):
 220         for section in self.sections:
 221             self.section_dump( section )
 222
 223 # eof