Initial import from the monolithic Qt.

This is the beginning of revision history for this module. If you
want to look at revision history older than this, please refer to the
Qt Git wiki for how to use Git history grafting. At the time of
writing, this wiki is located here:

http://qt.gitorious.org/qt/pages/GitIntroductionWithQt

If you have already performed the grafting and you don't see any
history beyond this commit, try running "git log" with the "--follow"
argument.

Branched from the monolithic repo, Qt master branch, at commit
896db169ea224deb96c59ce8af800d019de63f12

1 files changed, 347 insertions, 0 deletions

diff --git a/src/3rdparty/freetype/src/tools/docmaker/sources.py b/src/3rdparty/freetype/src/tools/docmaker/sources.py
new file mode 100644
index 0000000000..7b68c07019
--- /dev/null
+++ b/src/3rdparty/freetype/src/tools/docmaker/sources.py
@@ -0,0 +1,347 @@
+#  Sources (c) 2002, 2003, 2004, 2006, 2007, 2008, 2009
+#    David Turner <david@freetype.org>
+#
+#
+# this file contains definitions of classes needed to decompose
+# C sources files into a series of multi-line "blocks". There are
+# two kinds of blocks:
+#
+#   - normal blocks, which contain source code or ordinary comments
+#
+#   - documentation blocks, which have restricted formatting, and
+#     whose text always start with a documentation markup tag like
+#     "<Function>", "<Type>", etc..
+#
+# the routines used to process the content of documentation blocks
+# are not contained here, but in "content.py"
+#
+# the classes and methods found here only deal with text parsing
+# and basic documentation block extraction
+#
+
+import fileinput, re, sys, os, string
+
+
+
+################################################################
+##
+##  BLOCK FORMAT PATTERN
+##
+##   A simple class containing compiled regular expressions used
+##   to detect potential documentation format block comments within
+##   C source code
+##
+##   note that the 'column' pattern must contain a group that will
+##   be used to "unbox" the content of documentation comment blocks
+##
+class  SourceBlockFormat:
+
+    def  __init__( self, id, start, column, end ):
+        """create a block pattern, used to recognize special documentation blocks"""
+        self.id     = id
+        self.start  = re.compile( start, re.VERBOSE )
+        self.column = re.compile( column, re.VERBOSE )
+        self.end    = re.compile( end, re.VERBOSE )
+
+
+
+#
+# format 1 documentation comment blocks look like the following:
+#
+#    /************************************/
+#    /*                                  */
+#    /*                                  */
+#    /*                                  */
+#    /************************************/
+#
+# we define a few regular expressions here to detect them
+#
+
+start = r'''
+  \s*      # any number of whitespace
+  /\*{2,}/ # followed by '/' and at least two asterisks then '/'
+  \s*$     # probably followed by whitespace
+'''
+
+column = r'''
+  \s*      # any number of whitespace
+  /\*{1}   # followed by '/' and precisely one asterisk
+  ([^*].*) # followed by anything (group 1)
+  \*{1}/   # followed by one asterisk and a '/'
+  \s*$     # probably followed by whitespace
+'''
+
+re_source_block_format1 = SourceBlockFormat( 1, start, column, start )
+
+
+#
+# format 2 documentation comment blocks look like the following:
+#
+#    /************************************ (at least 2 asterisks)
+#     *
+#     *
+#     *
+#     *
+#     **/       (1 or more asterisks at the end)
+#
+# we define a few regular expressions here to detect them
+#
+start = r'''
+  \s*     # any number of whitespace
+  /\*{2,} # followed by '/' and at least two asterisks
+  \s*$    # probably followed by whitespace
+'''
+
+column = r'''
+  \s*        # any number of whitespace
+  \*{1}(?!/) # followed by precisely one asterisk not followed by `/'
+  (.*)       # then anything (group1)
+'''
+
+end = r'''
+  \s*  # any number of whitespace
+  \*+/ # followed by at least one asterisk, then '/'
+'''
+
+re_source_block_format2 = SourceBlockFormat( 2, start, column, end )
+
+
+#
+# the list of supported documentation block formats, we could add new ones
+# relatively easily
+#
+re_source_block_formats = [re_source_block_format1, re_source_block_format2]
+
+
+#
+# the following regular expressions corresponds to markup tags
+# within the documentation comment blocks. they're equivalent
+# despite their different syntax
+#
+# notice how each markup tag _must_ begin a new line
+#
+re_markup_tag1 = re.compile( r'''\s*<(\w*)>''' )  # <xxxx> format
+re_markup_tag2 = re.compile( r'''\s*@(\w*):''' )  # @xxxx: format
+
+#
+# the list of supported markup tags, we could add new ones relatively
+# easily
+#
+re_markup_tags = [re_markup_tag1, re_markup_tag2]
+
+#
+# used to detect a cross-reference, after markup tags have been stripped
+#
+re_crossref = re.compile( r'@(\w*)(.*)' )
+
+#
+# used to detect italic and bold styles in paragraph text
+#
+re_italic = re.compile( r"_(\w(\w|')*)_(.*)" )     #  _italic_
+re_bold   = re.compile( r"\*(\w(\w|')*)\*(.*)" )   #  *bold*
+
+#
+# used to detect the end of commented source lines
+#
+re_source_sep = re.compile( r'\s*/\*\s*\*/' )
+
+#
+# used to perform cross-reference within source output
+#
+re_source_crossref = re.compile( r'(\W*)(\w*)' )
+
+#
+# a list of reserved source keywords
+#
+re_source_keywords = re.compile( '''\\b ( typedef   |
+                                          struct    |
+                                          enum      |
+                                          union     |
+                                          const     |
+                                          char      |
+                                          int       |
+                                          short     |
+                                          long      |
+                                          void      |
+                                          signed    |
+                                          unsigned  |
+                                          \#include |
+                                          \#define  |
+                                          \#undef   |
+                                          \#if      |
+                                          \#ifdef   |
+                                          \#ifndef  |
+                                          \#else    |
+                                          \#endif   ) \\b''', re.VERBOSE )
+
+
+################################################################
+##
+##  SOURCE BLOCK CLASS
+##
+##   A SourceProcessor is in charge of reading a C source file
+##   and decomposing it into a series of different "SourceBlocks".
+##   each one of these blocks can be made of the following data:
+##
+##   - A documentation comment block that starts with "/**" and
+##     whose exact format will be discussed later
+##
+##   - normal sources lines, including comments
+##
+##   the important fields in a text block are the following ones:
+##
+##     self.lines   : a list of text lines for the corresponding block
+##
+##     self.content : for documentation comment blocks only, this is the
+##                    block content that has been "unboxed" from its
+##                    decoration. This is None for all other blocks
+##                    (i.e. sources or ordinary comments with no starting
+##                     markup tag)
+##
+class  SourceBlock:
+
+    def  __init__( self, processor, filename, lineno, lines ):
+        self.processor = processor
+        self.filename  = filename
+        self.lineno    = lineno
+        self.lines     = lines[:]
+        self.format    = processor.format
+        self.content   = []
+
+        if self.format == None:
+            return
+
+        words = []
+
+        # extract comment lines
+        lines = []
+
+        for line0 in self.lines:
+            m = self.format.column.match( line0 )
+            if m:
+                lines.append( m.group( 1 ) )
+
+        # now, look for a markup tag
+        for l in lines:
+            l = string.strip( l )
+            if len( l ) > 0:
+                for tag in re_markup_tags:
+                    if tag.match( l ):
+                        self.content = lines
+                        return
+
+    def  location( self ):
+        return "(" + self.filename + ":" + repr( self.lineno ) + ")"
+
+    # debugging only - not used in normal operations
+    def  dump( self ):
+        if self.content:
+            print "{{{content start---"
+            for l in self.content:
+                print l
+            print "---content end}}}"
+            return
+
+        fmt = ""
+        if self.format:
+            fmt = repr( self.format.id ) + " "
+
+        for line in self.lines:
+            print line
+
+
+
+################################################################
+##
+##  SOURCE PROCESSOR CLASS
+##
+##   The SourceProcessor is in charge of reading a C source file
+##   and decomposing it into a series of different "SourceBlock"
+##   objects.
+##
+##   each one of these blocks can be made of the following data:
+##
+##   - A documentation comment block that starts with "/**" and
+##     whose exact format will be discussed later
+##
+##   - normal sources lines, include comments
+##
+##
+class  SourceProcessor:
+
+    def  __init__( self ):
+        """initialize a source processor"""
+        self.blocks   = []
+        self.filename = None
+        self.format   = None
+        self.lines    = []
+
+    def  reset( self ):
+        """reset a block processor, clean all its blocks"""
+        self.blocks = []
+        self.format = None
+
+    def  parse_file( self, filename ):
+        """parse a C source file, and add its blocks to the processor's list"""
+        self.reset()
+
+        self.filename = filename
+
+        fileinput.close()
+        self.format = None
+        self.lineno = 0
+        self.lines  = []
+
+        for line in fileinput.input( filename ):
+            # strip trailing newlines, important on Windows machines!
+            if line[-1] == '\012':
+                line = line[0:-1]
+
+            if self.format == None:
+                self.process_normal_line( line )
+            else:
+                if self.format.end.match( line ):
+                    # that's a normal block end, add it to 'lines' and
+                    # create a new block
+                    self.lines.append( line )
+                    self.add_block_lines()
+                elif self.format.column.match( line ):
+                    # that's a normal column line, add it to 'lines'
+                    self.lines.append( line )
+                else:
+                    # humm.. this is an unexpected block end,
+                    # create a new block, but don't process the line
+                    self.add_block_lines()
+
+                    # we need to process the line again
+                    self.process_normal_line( line )
+
+        # record the last lines
+        self.add_block_lines()
+
+    def  process_normal_line( self, line ):
+        """process a normal line and check whether it is the start of a new block"""
+        for f in re_source_block_formats:
+            if f.start.match( line ):
+                self.add_block_lines()
+                self.format = f
+                self.lineno = fileinput.filelineno()
+
+        self.lines.append( line )
+
+    def  add_block_lines( self ):
+        """add the current accumulated lines and create a new block"""
+        if self.lines != []:
+            block = SourceBlock( self, self.filename, self.lineno, self.lines )
+
+            self.blocks.append( block )
+            self.format = None
+            self.lines  = []
+
+    # debugging only, not used in normal operations
+    def  dump( self ):
+        """print all blocks in a processor"""
+        for b in self.blocks:
+            b.dump()
+
+# eof