woff 1.0.0 → 1.1.0

data/woffTools/Lib/woffTools/tools/validate.py

@@ -0,0 +1,2504 @@
+#! /usr/bin/env python
+
+"""
+A module for validating the the file structure of WOFF Files.
+*validateFont* is the only public function.
+
+This can also be used as a command line tool for validating WOFF files.
+"""
+
+# import
+
+import os
+import re
+import time
+import sys
+import struct
+import zlib
+import optparse
+import codecs
+from cStringIO import StringIO
+from xml.etree import ElementTree
+from xml.parsers.expat import ExpatError
+
+# ----------------------
+# Support: Metadata Spec
+# ----------------------
+
+"""
+The Extended Metadata specifications are defined as a set of
+nested Python objects. This allows for a very simple XML
+validation procedure. The common element structure is as follows:
+
+    {
+        # ----------
+        # Attributes
+        # ----------
+
+        # In all cases, the dictionary has the attribute name at the top
+        # with the possible value(s) as the value. If an attribute has
+        # more than one representation (for exmaple xml:lang and lang)
+        # the two are specified as a space separated string for example
+        # "xml:lang lang".
+
+        # Required
+        "requiredAttributes" : {
+            # empty or one or more of the following
+            "name" : "default as string, list of options or None"
+        },
+
+        # Recommended
+        "recommendedAttributes" : {
+            # empty or one or more of the following
+            "name" : "default as string, list of options or None"
+        },
+
+        # Optional
+        "optionalAttributes" : {
+            # empty or one or more of the following
+            "name" : "default as string, list of options or None"
+        },
+
+        # -------
+        # Content
+        # -------
+
+        "contentLevel" : "not allowed", "recommended" or "required",
+
+        # --------------
+        # Child Elements
+        # --------------
+
+        # In all cases, the dictionary has the element name at the top
+        # with a dictionary as the value. The value dictionary defines
+        # the number of times the shild-element may occur along with
+        # the specification for the child-element.
+
+        # Required
+        "requiredChildElements" : {
+            # empty or one or more of the following
+            "name" : {
+                "minimumOccurrences" : int or None,
+                "maximumOccurrences" : int or None,
+                "spec" : {}
+            }
+        },
+
+        # Recommended
+        "recommendedChildElements" : {
+            # empty or one or more of the following
+            "name" : {
+                # minimumOccurrences is implicitly 0
+                "maximumOccurrences" : int or None,
+                "spec" : {}
+            }
+        },
+
+        # Optional
+        "optionalChildElements" : {
+            # empty or one or more of the following
+            "name" : {
+                # minimumOccurrences is implicitly 0
+                "maximumOccurrences" : int or None,
+                "spec" : {}
+            }
+        }
+    }
+
+The recommendedAttributes and recommendedChildElements are optional
+but they are separated from the optionalAttributes and optionalChildElements
+to allow for more detailed reporting.
+"""
+
+# Metadata 1.0
+# ------------
+
+# Common Options
+
+dirOptions_1_0 = ["ltr", "rtl"]
+
+# Fourth-Level Elements
+
+divSpec_1_0 = {
+    "requiredAttributes" : {},
+    "recommendedAttributes" : {},
+    "optionalAttributes" : {
+        "dir" : dirOptions_1_0,
+        "class" : None
+    },
+    "content" : "recommended",
+    "requiredChildElements" : {},
+    "recommendedChildElements" : {},
+    "optionalChildElements" : {
+        "div" : {
+            "maximumOccurrences" : None,
+            "spec" : "recursive divSpec_1_0" # special override for recursion.
+        },
+        "span" : {
+            "maximumOccurrences" : None,
+            "spec" : "recursive spanSpec_1_0" # special override for recursion.
+        }
+    }
+}
+
+spanSpec_1_0 = {
+    "requiredAttributes" : {},
+    "recommendedAttributes" : {},
+    "optionalAttributes" : {
+        "dir" : dirOptions_1_0,
+        "class" : None
+    },
+    "content" : "recommended",
+    "requiredChildElements" : {},
+    "recommendedChildElements" : {},
+    "optionalChildElements" : {
+        "div" : {
+            "maximumOccurrences" : None,
+            "spec" : "recursive divSpec_1_0" # special override for recursion.
+        },
+        "span" : {
+            "maximumOccurrences" : None,
+            "spec" : "recursive spanSpec_1_0" # special override for recursion.
+        }
+    }
+}
+
+# Third-Level Elements
+
+creditSpec_1_0 = {
+    "requiredAttributes" : {
+        "name" : None
+    },
+    "recommendedAttributes" : {},
+    "optionalAttributes" : {
+        "url" : None,
+        "role" : None,
+        "dir" : dirOptions_1_0,
+        "class" : None
+    },
+    "content" : "not allowed",
+    "requiredChildElements" : {},
+    "recommendedChildElements" : {},
+    "optionalChildElements" : {}
+}
+
+textSpec_1_0 = {
+    "requiredAttributes" : {},
+    "recommendedAttributes" : {},
+    "optionalAttributes" : {
+        "url" : None,
+        "role" : None,
+        "dir" : dirOptions_1_0,
+        "class" : None,
+        "xml:lang lang" : None
+    },
+    "content" : "recommended",
+    "requiredChildElements" : {},
+    "recommendedChildElements" : {},
+    "optionalChildElements" : {
+        "div" : {
+            "maximumOccurrences" : None,
+            "spec" : divSpec_1_0
+        },
+        "span" : {
+            "maximumOccurrences" : None,
+            "spec" : spanSpec_1_0
+        }
+    }
+}
+
+extensionNameSpec_1_0 = {
+    "requiredAttributes" : {},
+    "recommendedAttributes" : {},
+    "optionalAttributes" : {
+        "dir" : dirOptions_1_0,
+        "class" : None,
+        "xml:lang lang" : None
+    },
+    "content" : "recommended",
+    "requiredChildElements" : {},
+    "recommendedChildElements" : {},
+    "optionalChildElements" : {}
+}
+
+extensionValueSpec_1_0 = {
+    "requiredAttributes" : {},
+    "recommendedAttributes" : {},
+    "optionalAttributes" : {
+        "dir" : dirOptions_1_0,
+        "class" : None,
+        "xml:lang lang" : None
+    },
+    "content" : "recommended",
+    "requiredChildElements" : {},
+    "recommendedChildElements" : {},
+    "optionalChildElements" : {}
+}
+
+extensionItemSpec_1_0 = {
+    "requiredAttributes" : {},
+    "recommendedAttributes" : {},
+    "optionalAttributes" : {
+        "id" : None
+    },
+    "content" : "not allowed",
+    "requiredChildElements" : {
+        "name" : {
+            "minimumOccurrences" : 1,
+            "maximumOccurrences" : None,
+            "spec" : extensionNameSpec_1_0
+        },
+        "value" : {
+            "minimumOccurrences" : 1,
+            "maximumOccurrences" : None,
+            "spec" : extensionValueSpec_1_0
+        }
+    },
+    "recommendedChildElements" : {
+    },
+    "optionalChildElements" : {}
+}
+
+# Second Level Elements
+
+uniqueidSpec_1_0 = {
+    "requiredAttributes" : {
+        "id" : None
+    },
+    "recommendedAttributes" : {},
+    "optionalAttributes" : {},
+    "content" : "not allowed",
+    "requiredChildElements" : {},
+    "recommendedChildElements" : {},
+    "optionalChildElements" : {}
+}
+
+vendorSpec_1_0 = {
+    "requiredAttributes" : {
+        "name" : None
+    },
+    "recommendedAttributes" : {},
+    "optionalAttributes" : {
+        "url" : None,
+        "dir" : dirOptions_1_0,
+        "class" : None
+    },
+    "content" : "not allowed",
+    "requiredChildElements" : {},
+    "recommendedChildElements" : {},
+    "optionalChildElements" : {}
+}
+
+creditsSpec_1_0 = {
+    "requiredAttributes" : {},
+    "recommendedAttributes" : {},
+    "optionalAttributes" : {},
+    "content" : "not allowed",
+    "requiredChildElements" : {
+        "credit" : {
+            "minimumOccurrences" : 1,
+            "maximumOccurrences" : None,
+            "spec" : creditSpec_1_0
+        }
+    },
+    "recommendedChildElements" : {},
+    "optionalChildElements" : {}
+}
+
+descriptionSpec_1_0 = {
+    "requiredAttributes" : {},
+    "recommendedAttributes" : {},
+    "optionalAttributes" : {
+        "url" : None,
+    },
+    "content" : "not allowed",
+    "requiredChildElements" : {
+        "text" : {
+            "minimumOccurrences" : 1,
+            "maximumOccurrences" : None,
+            "spec" : textSpec_1_0
+        }
+    },
+    "recommendedChildElements" : {},
+    "optionalChildElements" : {}
+}
+
+licenseSpec_1_0 = {
+    "requiredAttributes" : {},
+    "recommendedAttributes" : {},
+    "optionalAttributes" : {
+        "url" : None,
+        "id" : None
+    },
+    "content" : "not allowed",
+    "requiredChildElements" : {},
+    "recommendedChildElements" : {},
+    "optionalChildElements" : {
+        "text" : {
+            "maximumOccurrences" : None,
+            "spec" : textSpec_1_0
+        }
+    }
+}
+
+copyrightSpec_1_0 = {
+    "requiredAttributes" : {},
+    "recommendedAttributes" : {},
+    "optionalAttributes" : {},
+    "content" : "not allowed",
+    "requiredChildElements" : {
+        "text" : {
+            "minimumOccurrences" : 1,
+            "maximumOccurrences" : None,
+            "spec" : textSpec_1_0
+        }
+    },
+    "recommendedChildElements" : {},
+    "optionalChildElements" : {}
+}
+
+trademarkSpec_1_0 = {
+    "requiredAttributes" : {},
+    "recommendedAttributes" : {},
+    "optionalAttributes" : {},
+    "content" : "not allowed",
+    "requiredChildElements" : {
+        "text" : {
+            "minimumOccurrences" : 1,
+            "maximumOccurrences" : None,
+            "spec" : textSpec_1_0
+        }
+    },
+    "recommendedChildElements" : {},
+    "optionalChildElements" : {}
+}
+
+licenseeSpec_1_0 = {
+    "requiredAttributes" : {
+        "name" : None,
+    },
+    "recommendedAttributes" : {},
+    "optionalAttributes" : {
+        "dir" : dirOptions_1_0,
+        "class" : None
+    },
+    "content" : "not allowed",
+    "requiredChildElements" : {},
+    "recommendedChildElements" : {},
+    "optionalChildElements" : {}
+}
+
+extensionSpec_1_0 = {
+    "requiredAttributes" : {},
+    "recommendedAttributes" : {},
+    "optionalAttributes" : {
+        "id" : None
+    },
+    "content" : "not allowed",
+    "requiredChildElements" : {
+        "item" : {
+            "minimumOccurrences" : 1,
+            "maximumOccurrences" : None,
+            "spec" : extensionItemSpec_1_0
+        }
+    },
+    "recommendedChildElements" : {},
+    "optionalChildElements" : {
+        "name" : {
+            "maximumOccurrences" : None,
+            "spec" : extensionNameSpec_1_0
+        }
+    }
+}
+
+# First Level Elements
+
+metadataSpec_1_0 = {
+    "requiredAttributes" : {
+        "version" : "1.0"
+    },
+    "recommendedAttributes" : {},
+    "optionalAttributes" : {},
+    "content" : "not allowed",
+    "requiredChildElements" : {},
+    "recommendedChildElements" : {
+        "uniqueid" : {
+            "maximumOccurrences" : 1,
+            "spec" : uniqueidSpec_1_0
+        }
+    },
+    "optionalChildElements" : {
+        "vendor" : {
+            "maximumOccurrences" : 1,
+            "spec" : vendorSpec_1_0
+        },
+        "credits" : {
+            "maximumOccurrences" : 1,
+            "spec" : creditsSpec_1_0
+        },
+        "description" : {
+            "maximumOccurrences" : 1,
+            "spec" : descriptionSpec_1_0
+        },
+        "license" : {
+            "maximumOccurrences" : 1,
+            "spec" : licenseSpec_1_0
+        },
+        "copyright" : {
+            "maximumOccurrences" : 1,
+            "spec" : copyrightSpec_1_0
+        },
+        "trademark" : {
+            "maximumOccurrences" : 1,
+            "spec" : trademarkSpec_1_0
+        },
+        "licensee" : {
+            "maximumOccurrences" : 1,
+            "spec" : licenseeSpec_1_0
+        },
+        "licensee" : {
+            "maximumOccurrences" : 1,
+            "spec" : licenseeSpec_1_0
+        },
+        "extension" : {
+            "maximumOccurrences" : None,
+            "spec" : extensionSpec_1_0
+        }
+    }
+}
+
+# ----------------------
+# Support: struct Helper
+# ----------------------
+
+# This was inspired by Just van Rossum's sstruct module.
+# http://fonttools.svn.sourceforge.net/svnroot/fonttools/trunk/Lib/sstruct.py
+
+def structPack(format, obj):
+    keys, formatString = _structGetFormat(format)
+    values = []
+    for key in keys:
+        values.append(obj[key])
+    data = struct.pack(formatString, *values)
+    return data
+
+def structUnpack(format, data):
+    keys, formatString = _structGetFormat(format)
+    size = struct.calcsize(formatString)
+    values = struct.unpack(formatString, data[:size])
+    unpacked = {}
+    for index, key in enumerate(keys):
+        value = values[index]
+        unpacked[key] = value
+    return unpacked, data[size:]
+
+def structCalcSize(format):
+    keys, formatString = _structGetFormat(format)
+    return struct.calcsize(formatString)
+
+_structFormatCache = {}
+
+def _structGetFormat(format):
+    if format not in _structFormatCache:
+        keys = []
+        formatString = [">"] # always big endian
+        for line in format.strip().splitlines():
+            line = line.split("#", 1)[0].strip()
+            if not line:
+                continue
+            key, formatCharacter = line.split(":")
+            key = key.strip()
+            formatCharacter = formatCharacter.strip()
+            keys.append(key)
+            formatString.append(formatCharacter)
+        _structFormatCache[format] = (keys, "".join(formatString))
+    return _structFormatCache[format]
+
+# -------------
+# Tests: Header
+# -------------
+
+def testHeader(data, reporter):
+    """
+    Test the WOFF header.
+    """
+    functions = [
+        _testHeaderSignature,
+        _testHeaderFlavor,
+        _testHeaderLength,
+        _testHeaderReserved,
+        _testHeaderTotalSFNTSize,
+        _testHeaderNumTables
+    ]
+    for function in functions:
+        shouldStop = function(data, reporter)
+        if shouldStop:
+            return True
+    return False
+
+
+headerFormat = """
+    signature:      4s
+    flavor:         4s
+    length:         L
+    numTables:      H
+    reserved:       H
+    totalSfntSize:  L
+    majorVersion:   H
+    minorVersion:   H
+    metaOffset:     L
+    metaLength:     L
+    metaOrigLength: L
+    privOffset:     L
+    privLength:     L
+"""
+headerSize = structCalcSize(headerFormat)
+
+def _testHeaderStructure(data, reporter):
+    """
+    Tests:
+    - Header must be the proper structure.
+    """
+    try:
+        structUnpack(headerFormat, data)
+        reporter.logPass(message="The header structure is correct.")
+    except:
+        reporter.logError(message="The header is not properly structured.")
+        return True
+
+def _testHeaderSignature(data, reporter):
+    """
+    Tests:
+    - The signature must be "wOFF".
+    """
+    header = unpackHeader(data)
+    signature = header["signature"]
+    if signature != "wOFF":
+        reporter.logError(message="Invalid signature: %s." % signature)
+        return True
+    else:
+        reporter.logPass(message="The signature is correct.")
+
+def _testHeaderFlavor(data, reporter):
+    """
+    Tests:
+    - The flavor should be OTTO, 0x00010000 or true. Warn if another value is found.
+    - If the flavor is OTTO, the CFF table must be present.
+    - If the flavor is not OTTO, the CFF must not be present.
+    - If the directory cannot be unpacked, the flavor can not be validated. Issue a warning.
+    """
+    header = unpackHeader(data)
+    flavor = header["flavor"]
+    if flavor not in ("OTTO", "\000\001\000\000", "true"):
+        reporter.logWarning(message="Unknown flavor: %s." % flavor)
+    else:
+        try:
+            tags = [table["tag"] for table in unpackDirectory(data)]
+            if "CFF " in tags and flavor != "OTTO":
+                reporter.logError(message="A \"CFF\" table is defined in the font and the flavor is not set to \"OTTO\".")
+            elif "CFF " not in tags and flavor == "OTTO":
+                reporter.logError(message="The flavor is set to \"OTTO\" but no \"CFF\" table is defined.")
+            else:
+                reporter.logPass(message="The flavor is a correct value.")
+        except:
+            reporter.logWarning(message="Could not validate the flavor.")
+
+def _testHeaderLength(data, reporter):
+    """
+    Tests:
+    - The length of the data must match the defined length.
+    - The length of the data must be long enough for header and directory for defined number of tables.
+    - The length of the data must be long enough to contain the table lengths defined in the directory,
+      the metaLength and the privLength.
+    """
+    header = unpackHeader(data)
+    length = header["length"]
+    numTables = header["numTables"]
+    minLength = headerSize + (directorySize * numTables)
+    if length != len(data):
+        reporter.logError(message="Defined length (%d) does not match actual length of the data (%d)." % (length, len(data)))
+        return
+    if length < minLength:
+        reporter.logError(message="Invalid length defined (%d) for number of tables defined." % length)
+        return
+    directory = unpackDirectory(data)
+    for entry in directory:
+        compLength = entry["compLength"]
+        if compLength % 4:
+            compLength += 4 - (compLength % 4)
+        minLength += compLength
+    metaLength = privLength = 0
+    if header["metaOffset"]:
+        metaLength = header["metaLength"]
+    if header["privOffset"]:
+        privLength = header["privLength"]
+    if privLength and metaLength % 4:
+        metaLength += 4 - (metaLength % 4)
+    minLength += metaLength + privLength
+    if length < minLength:
+        reporter.logError(message="Defined length (%d) does not match the required length of the data (%d)." % (length, minLength))
+        return
+    reporter.logPass(message="The length defined in the header is correct.")
+
+def _testHeaderReserved(data, reporter):
+    """
+    Tests:
+    - The reserved bit must be set to 0.
+    """
+    header = unpackHeader(data)
+    reserved = header["reserved"]
+    if reserved != 0:
+        reporter.logError(message="Invalid value in reserved field (%d)." % reserved)
+    else:
+        reporter.logPass(message="The value in the reserved field is correct.")
+
+def _testHeaderTotalSFNTSize(data, reporter):
+    """
+    Tests:
+    - The size of the unpacked SFNT data must be a multiple of 4.
+    - The origLength values in the directory, with proper padding, must sum
+      to the totalSfntSize in the header.
+    """
+    header = unpackHeader(data)
+    directory = unpackDirectory(data)
+    totalSfntSize = header["totalSfntSize"]
+    isValid = True
+    if totalSfntSize % 4:
+        reporter.logError(message="The total sfnt size (%d) is not a multiple of four." % totalSfntSize)
+        isValid = False
+    else:
+        numTables = header["numTables"]
+        requiredSize = sfntHeaderSize + (numTables * sfntDirectoryEntrySize)
+        for table in directory:
+            origLength = table["origLength"]
+            if origLength % 4:
+                origLength += 4 - (origLength % 4)
+            requiredSize += origLength
+        if totalSfntSize != requiredSize:
+            reporter.logError(message="The total sfnt size (%d) does not match the required sfnt size (%d)." % (totalSfntSize, requiredSize))
+            isValid = False
+    if isValid:
+        reporter.logPass(message="The total sfnt size is valid.")
+
+def _testHeaderNumTables(data, reporter):
+    """
+    Tests:
+    - The number of tables must be at least 1.
+    - The directory entries for the specified number of tables must be properly formatted.
+    """
+    header = unpackHeader(data)
+    numTables = header["numTables"]
+    if numTables < 1:
+        reporter.logError(message="Invalid number of tables defined in header structure (%d)." % numTables)
+        return
+    data = data[headerSize:]
+    for index in range(numTables):
+        try:
+            d, data = structUnpack(directoryFormat, data)
+        except:
+            reporter.logError(message="The defined number of tables in the header (%d) does not match the actual number of tables (%d)." % (numTables, index))
+            return
+    reporter.logPass(message="The number of tables defined in the header is valid.")
+
+# -------------
+# Tests: Tables
+# -------------
+
+def testDataBlocks(data, reporter):
+    """
+    Test the WOFF data blocks.
+    """
+    functions = [
+        _testBlocksOffsetLengthZero,
+        _testBlocksPositioning
+    ]
+    for function in functions:
+        shouldStop = function(data, reporter)
+        if shouldStop:
+            return True
+
+def _testBlocksOffsetLengthZero(data, reporter):
+    """
+    - The metadata must have the offset and length set to zero consistently.
+    - The private data must have the offset and length set to zero consistently.
+    """
+    header = unpackHeader(data)
+    # metadata
+    metaOffset = header["metaOffset"]
+    metaLength = header["metaLength"]
+    if metaOffset == 0 or metaLength == 0:
+        if metaOffset == 0 and metaLength == 0:
+            reporter.logPass(message="The length and offset are appropriately set for empty metadata.")
+        else:
+            reporter.logError(message="The metadata offset (%d) and metadata length (%d) are not properly set. If one is 0, they both must be 0." % (metaOffset, metaLength))
+    # private data
+    privOffset = header["privOffset"]
+    privLength = header["privLength"]
+    if privOffset == 0 or privLength == 0:
+        if privOffset == 0 and privLength == 0:
+            reporter.logPass(message="The length and offset are appropriately set for empty private data.")
+        else:
+            reporter.logError(message="The private data offset (%d) and private data length (%d) are not properly set. If one is 0, they both must be 0." % (privOffset, privLength))
+
+def _testBlocksPositioning(data, reporter):
+    """
+    Tests:
+    - The table data must start immediately after the directory.
+    - The table data must end at the beginning of the metadata, the beginning of the private data or the end of the file.
+    - The metadata must start immediately after the table data.
+    - the metadata must end at the beginning of he private data (padded as needed) or the end of the file.
+    - The private data must start immediately after the table data or metadata.
+    - The private data must end at the edge of the file.
+    """
+    header = unpackHeader(data)
+    # table data start
+    directory = unpackDirectory(data)
+    if not directory:
+        return
+    expectedTableDataStart = headerSize + (directorySize * header["numTables"])
+    offsets = [entry["offset"] for entry in directory]
+    tableDataStart = min(offsets)
+    if expectedTableDataStart != tableDataStart:
+        reporter.logError(message="The table data does not start (%d) in the required position (%d)." % (tableDataStart, expectedTableDataStart))
+    else:
+        reporter.logPass(message="The table data begins in the required position.")
+    # table data end
+    if header["metaOffset"]:
+        definedTableDataEnd = header["metaOffset"]
+    elif header["privOffset"]:
+        definedTableDataEnd = header["privOffset"]
+    else:
+        definedTableDataEnd = header["length"]
+    directory = unpackDirectory(data)
+    ends = [table["offset"] + table["compLength"] + calcPaddingLength(table["compLength"]) for table in directory]
+    expectedTableDataEnd = max(ends)
+    if expectedTableDataEnd != definedTableDataEnd:
+        reporter.logError(message="The table data end (%d) is not in the required position (%d)." % (definedTableDataEnd, expectedTableDataEnd))
+    else:
+        reporter.logPass(message="The table data ends in the required position.")
+    # metadata
+    if header["metaOffset"]:
+        # start
+        expectedMetaStart = expectedTableDataEnd
+        definedMetaStart = header["metaOffset"]
+        if expectedMetaStart != definedMetaStart:
+            reporter.logError(message="The metadata does not start (%d) in the required position (%d)." % (definedMetaStart, expectedMetaStart))
+        else:
+            reporter.logPass(message="The metadata begins in the required position.")
+        # end
+        if header["privOffset"]:
+            definedMetaEnd = header["privOffset"]
+            needMetaPadding = True
+        else:
+            definedMetaEnd = header["length"]
+            needMetaPadding = False
+        expectedMetaEnd = header["metaOffset"] + header["metaLength"]
+        if needMetaPadding:
+            expectedMetaEnd += calcPaddingLength(header["metaLength"])
+        if expectedMetaEnd != definedMetaEnd:
+            reporter.logError(message="The metadata end (%d) is not in the required position (%d)." % (definedMetaEnd, expectedMetaEnd))
+        else:
+            reporter.logPass(message="The metadata ends in the required position.")
+    # private data
+    if header["privOffset"]:
+        # start
+        if header["metaOffset"]:
+            expectedPrivateStart = expectedMetaEnd
+        else:
+            expectedPrivateStart = expectedTableDataEnd
+        definedPrivateStart = header["privOffset"]
+        if expectedPrivateStart != definedPrivateStart:
+            reporter.logError(message="The private data does not start (%d) in the required position (%d)." % (definedPrivateStart, expectedPrivateStart))
+        else:
+            reporter.logPass(message="The private data begins in the required position.")
+        # end
+        expectedPrivateEnd = header["length"]
+        definedPrivateEnd = header["privOffset"] + header["privLength"]
+        if expectedPrivateEnd != definedPrivateEnd:
+            reporter.logError(message="The private data end (%d) is not in the required position (%d)." % (definedPrivateEnd, expectedPrivateEnd))
+        else:
+            reporter.logPass(message="The private data ends in the required position.")
+
+# ----------------------
+# Tests: Table Directory
+# ----------------------
+
+def testTableDirectory(data, reporter):
+    """
+    Test the WOFF table directory.
+    """
+    functions = [
+        _testTableDirectoryStructure,
+        _testTableDirectory4ByteOffsets,
+        _testTableDirectoryPadding,
+        _testTableDirectoryPositions,
+        _testTableDirectoryCompressedLength,
+        _testTableDirectoryDecompressedLength,
+        _testTableDirectoryChecksums,
+        _testTableDirectoryTableOrder
+    ]
+    for function in functions:
+        shouldStop = function(data, reporter)
+        if shouldStop:
+            return True
+
+directoryFormat = """
+    tag:            4s
+    offset:         L
+    compLength:     L
+    origLength:     L
+    origChecksum:   L
+"""
+directorySize = structCalcSize(directoryFormat)
+
+def _testTableDirectoryStructure(data, reporter):
+    """
+    Tests:
+    - The entries in the table directory can be unpacked.
+    """
+    header = unpackHeader(data)
+    numTables = header["numTables"]
+    data = data[headerSize:]
+    try:
+        for index in range(numTables):
+            table, data = structUnpack(directoryFormat, data)
+        reporter.logPass(message="The table directory structure is correct.")
+    except:
+        reporter.logError(message="The table directory is not properly structured.")
+        return True
+
+def _testTableDirectory4ByteOffsets(data, reporter):
+    """
+    Tests:
+    - The font tables must each begin on a 4-byte boundary.
+    """
+    directory = unpackDirectory(data)
+    for table in directory:
+        tag = table["tag"]
+        offset = table["offset"]
+        if offset % 4:
+            reporter.logError(message="The \"%s\" table does not begin on a 4-byte boundary (%d)." % (tag, offset))
+        else:
+            reporter.logPass(message="The \"%s\" table begins on a 4-byte boundary." % tag)
+
+def _testTableDirectoryPadding(data, reporter):
+    """
+    Tests:
+    - All tables, including the final table, must be padded to a
+      four byte boundary using null bytes as needed.
+    """
+    header = unpackHeader(data)
+    directory = unpackDirectory(data)
+    # test final table
+    endError = False
+    sfntEnd = None
+    if header["metaOffset"] != 0:
+        sfntEnd = header["metaOffset"]
+    elif header["privOffset"] != 0:
+        sfntEnd = header["privOffset"]
+    else:
+        sfntEnd = header["length"]
+    if sfntEnd % 4:
+        reporter.logError(message="The sfnt data does not end with proper padding.")
+    else:
+        reporter.logPass(message="The sfnt data ends with proper padding.")
+    # test the bytes used for padding
+    for table in directory:
+        tag = table["tag"]
+        offset = table["offset"]
+        length = table["compLength"]
+        paddingLength = calcPaddingLength(length)
+        if paddingLength:
+            paddingOffset = offset + length
+            padding = data[paddingOffset:paddingOffset+paddingLength]
+            expectedPadding = "\0" * paddingLength
+            if padding != expectedPadding:
+                reporter.logError(message="The \"%s\" table is not padded with null bytes." % tag)
+            else:
+                reporter.logPass(message="The \"%s\" table is padded with null bytes." % tag)
+
+def _testTableDirectoryPositions(data, reporter):
+    """
+    Tests:
+    - The table offsets must not be before the end of the header/directory.
+    - The table offset + length must not be greater than the edge of the available space.
+    - The table offsets must not be after the edge of the available space.
+    - Table blocks must not overlap.
+    - There must be no gaps between the tables.
+    """
+    directory = unpackDirectory(data)
+    tablesWithProblems = set()
+    # test for overlapping tables
+    locations = []
+    for table in directory:
+        offset = table["offset"]
+        length = table["compLength"]
+        length = length + calcPaddingLength(length)
+        locations.append((offset, offset + length, table["tag"]))
+    for start, end, tag in locations:
+        for otherStart, otherEnd, otherTag in locations:
+            if tag == otherTag:
+                continue
+            if start >= otherStart and start < otherEnd:
+                reporter.logError(message="The \"%s\" table overlaps the \"%s\" table." % (tag, otherTag))
+                tablesWithProblems.add(tag)
+                tablesWithProblems.add(otherTag)
+    # test for invalid offset, length and combo
+    header = unpackHeader(data)
+    if header["metaOffset"] != 0:
+        tableDataEnd = header["metaOffset"]
+    elif header["privOffset"] != 0:
+        tableDataEnd = header["privOffset"]
+    else:
+        tableDataEnd = header["length"]
+    numTables = header["numTables"]
+    minOffset = headerSize + (directorySize * numTables)
+    maxLength = tableDataEnd - minOffset
+    for table in directory:
+        tag = table["tag"]
+        offset = table["offset"]
+        length = table["compLength"]
+        # offset is before the beginning of the table data block
+        if offset < minOffset:
+            tablesWithProblems.add(tag)
+            message = "The \"%s\" table directory entry offset (%d) is before the start of the table data block (%d)." % (tag, offset, minOffset)
+            reporter.logError(message=message)
+        # offset is after the end of the table data block
+        elif offset > tableDataEnd:
+            tablesWithProblems.add(tag)
+            message = "The \"%s\" table directory entry offset (%d) is past the end of the table data block (%d)." % (tag, offset, tableDataEnd)
+            reporter.logError(message=message)
+        # offset + length is after the end of the table tada block
+        elif (offset + length) > tableDataEnd:
+            tablesWithProblems.add(tag)
+            message = "The \"%s\" table directory entry offset (%d) + length (%d) is past the end of the table data block (%d)." % (tag, offset, length, tableDataEnd)
+            reporter.logError(message=message)
+    # test for gaps
+    tables = []
+    for table in directory:
+        tag = table["tag"]
+        offset = table["offset"]
+        length = table["compLength"]
+        length += calcPaddingLength(length)
+        tables.append((offset, offset + length, tag))
+    tables.sort()
+    for index, (start, end, tag) in enumerate(tables):
+        if index == 0:
+            continue
+        prevStart, prevEnd, prevTag = tables[index - 1]
+        if prevEnd < start:
+            tablesWithProblems.add(prevTag)
+            tablesWithProblems.add(tag)
+            reporter.logError(message="Extraneous data between the \"%s\" and \"%s\" tables." % (prevTag, tag))
+    # log passes
+    for entry in directory:
+        tag = entry["tag"]
+        if tag in tablesWithProblems:
+            continue
+        reporter.logPass(message="The \"%s\" table directory entry has a valid offset and length." % tag)
+
+def _testTableDirectoryCompressedLength(data, reporter):
+    """
+    Tests:
+    - The compressed length must be less than or equal to the original length.
+    """
+    directory = unpackDirectory(data)
+    for table in directory:
+        tag = table["tag"]
+        compLength = table["compLength"]
+        origLength = table["origLength"]
+        if compLength > origLength:
+            reporter.logError(message="The \"%s\" table directory entry has a compressed length (%d) larger than the original length (%d)." % (tag, compLength, origLength))
+        else:
+            reporter.logPass(message="The \"%s\" table directory entry has proper compLength and origLength values." % tag)
+
+def _testTableDirectoryDecompressedLength(data, reporter):
+    """
+    Tests:
+    - The decompressed length of the data must match the defined original length.
+    """
+    directory = unpackDirectory(data)
+    tableData = unpackTableData(data)
+    for table in directory:
+        tag = table["tag"]
+        offset = table["offset"]
+        compLength = table["compLength"]
+        origLength = table["origLength"]
+        if compLength >= origLength:
+            continue
+        decompressedData = tableData[tag]
+        # couldn't be decompressed. handled elsewhere.
+        if decompressedData is None:
+            continue
+        decompressedLength = len(decompressedData)
+        if origLength != decompressedLength:
+            reporter.logError(message="The \"%s\" table directory entry has an original length (%d) that does not match the actual length of the decompressed data (%d)." % (tag, origLength, decompressedLength))
+        else:
+            reporter.logPass(message="The \"%s\" table directory entry has a proper original length compared to the actual decompressed data." % tag)
+
+def _testTableDirectoryChecksums(data, reporter):
+    """
+    Tests:
+    - The checksums for the tables must match the checksums in the directory.
+    - The head checksum adjustment must be correct.
+    """
+    # check the table directory checksums
+    directory = unpackDirectory(data)
+    tables = unpackTableData(data)
+    for entry in directory:
+        tag = entry["tag"]
+        origChecksum = entry["origChecksum"]
+        decompressedData = tables[tag]
+        # couldn't be decompressed.
+        if decompressedData is None:
+            continue
+        newChecksum = calcChecksum(tag, decompressedData)
+        if newChecksum != origChecksum:
+            reporter.logError(message="The \"%s\" table directory entry original checksum (%s) does not match the checksum (%s) calculated from the data." % (tag, hex(origChecksum), hex(newChecksum)))
+        else:
+            reporter.logPass(message="The \"%s\" table directory entry original checksum is correct." % tag)
+    # check the head checksum adjustment
+    if "head" not in tables:
+        reporter.logWarning(message="The font does not contain a \"head\" table.")
+    else:
+        newChecksum = calcHeadChecksum(data)
+        data = tables["head"]
+        try:
+            checksum = struct.unpack(">L", data[8:12])[0]
+            if checksum != newChecksum:
+                reporter.logError(message="The \"head\" table checkSumAdjustment (%s) does not match the calculated checkSumAdjustment (%s)." % (hex(checksum), hex(newChecksum)))
+            else:
+                reporter.logPass(message="The \"head\" table checkSumAdjustment is valid.")
+        except:
+            reporter.logError(message="The \"head\" table is not properly structured.")
+
+
+def _testTableDirectoryTableOrder(data, reporter):
+    """
+    Tests:
+    - The directory entries must be stored in ascending order based on their tag.
+    """
+    storedOrder = [table["tag"] for table in unpackDirectory(data)]
+    if storedOrder != sorted(storedOrder):
+        reporter.logError(message="The table directory entries are not stored in alphabetical order.")
+    else:
+        reporter.logPass(message="The table directory entries are stored in the proper order.")
+
+# -----------------
+# Tests: Table Data
+# -----------------
+
+def testTableData(data, reporter):
+    """
+    Test the table data.
+    """
+    functions = [
+        _testTableDataDecompression
+    ]
+    for function in functions:
+        shouldStop = function(data, reporter)
+        if shouldStop:
+            return True
+    return False
+
+def _testTableDataDecompression(data, reporter):
+    """
+    Tests:
+    - The table data, when the defined compressed length is less
+      than the original length, must be properly compressed.
+    """
+    for table in unpackDirectory(data):
+        tag = table["tag"]
+        offset = table["offset"]
+        compLength = table["compLength"]
+        origLength = table["origLength"]
+        if origLength <= compLength:
+            continue
+        entryData = data[offset:offset+compLength]
+        try:
+            decompressed = zlib.decompress(entryData)
+            reporter.logPass(message="The \"%s\" table data can be decompressed with zlib." % tag)
+        except zlib.error:
+            reporter.logError(message="The \"%s\" table data can not be decompressed with zlib." % tag)
+
+# ----------------
+# Tests: Metadata
+# ----------------
+
+def testMetadata(data, reporter):
+    """
+    Test the WOFF metadata.
+    """
+    if _shouldSkipMetadataTest(data, reporter):
+        return False
+    functions = [
+        _testMetadataPadding,
+        _testMetadataDecompression,
+        _testMetadataDecompressedLength,
+        _testMetadataParse,
+        _testMetadataEncoding,
+        _testMetadataStructure
+    ]
+    for function in functions:
+        shouldStop = function(data, reporter)
+        if shouldStop:
+            return True
+    return False
+
+def _shouldSkipMetadataTest(data, reporter):
+    """
+    This is used at the start of metadata test functions.
+    It writes a note and returns True if not metadata exists.
+    """
+    header = unpackHeader(data)
+    metaOffset = header["metaOffset"]
+    metaLength = header["metaLength"]
+    if metaOffset == 0 or metaLength == 0:
+        reporter.logNote(message="No metadata to test.")
+        return True
+
+def _testMetadataPadding(data, reporter):
+    """
+    - The padding must be null.
+    """
+    header = unpackHeader(data)
+    if not header["metaOffset"] or not header["privOffset"]:
+        return
+    paddingLength = calcPaddingLength(header["metaLength"])
+    if not paddingLength:
+        return
+    paddingOffset = header["metaOffset"] + header["metaLength"]
+    padding = data[paddingOffset:paddingOffset + paddingLength]
+    expectedPadding = "\0" * paddingLength
+    if padding != expectedPadding:
+        reporter.logError(message="The metadata is not padded with null bytes.")
+    else:
+        reporter.logPass(message="The metadata is padded with null bytes,")
+
+# does this need to be tested?
+#
+# def testMetadataIsCompressed(data, reporter):
+#     """
+#     Tests:
+#     - The metadata must be compressed.
+#     """
+#     if _shouldSkipMetadataTest(data, reporter):
+#         return
+#     header = unpackHeader(data)
+#     length = header["metaLength"]
+#     origLength = header["metaOrigLength"]
+#     if length >= origLength:
+#         reporter.logError(message="The compressed metdata length (%d) is higher than or equal to the original, uncompressed length (%d)." % (length, origLength))
+#         return True
+#     reporter.logPass(message="The compressed metdata length is smaller than the original, uncompressed length.")
+
+def _testMetadataDecompression(data, reporter):
+    """
+    Tests:
+    - Metadata must be compressed with zlib.
+    """
+    if _shouldSkipMetadataTest(data, reporter):
+        return
+    compData = unpackMetadata(data, decompress=False, parse=False)
+    try:
+        zlib.decompress(compData)
+    except zlib.error:
+        reporter.logError(message="The metadata can not be decompressed with zlib.")
+        return True
+    reporter.logPass(message="The metadata can be decompressed with zlib.")
+
+def _testMetadataDecompressedLength(data, reporter):
+    """
+    Tests:
+    - The length of the decompressed metadata must match the defined original length.
+    """
+    if _shouldSkipMetadataTest(data, reporter):
+        return
+    header = unpackHeader(data)
+    metadata = unpackMetadata(data, parse=False)
+    metaOrigLength = header["metaOrigLength"]
+    decompressedLength = len(metadata)
+    if metaOrigLength != decompressedLength:
+        reporter.logError(message="The decompressed metadata length (%d) does not match the original metadata length (%d) in the header." % (decompressedLength, metaOrigLength))
+    else:
+        reporter.logPass(message="The decompressed metadata length matches the original metadata length in the header.")
+
+def _testMetadataParse(data, reporter):
+    """
+    Tests:
+    - The metadata must be well-formed.
+    """
+    if _shouldSkipMetadataTest(data, reporter):
+        return
+    metadata = unpackMetadata(data, parse=False)
+    try:
+        tree = ElementTree.fromstring(metadata)
+    except (ExpatError, LookupError):
+        reporter.logError(message="The metadata can not be parsed.")
+        return True
+    reporter.logPass(message="The metadata can be parsed.")
+
+def _testMetadataEncoding(data, reporter):
+    """
+    Tests:
+    - The metadata must be UTF-8 encoded.
+    """
+    if _shouldSkipMetadataTest(data, reporter):
+        return
+    metadata = unpackMetadata(data, parse=False)
+    errorMessage = "The metadata encoding is not valid."
+    encoding = None
+    # check the BOM
+    if not metadata.startswith("<"):
+        if not metadata.startswith(codecs.BOM_UTF8):
+            reporter.logError(message=errorMessage)
+            return
+        else:
+            encoding = "UTF-8"
+    # sniff the encoding
+    else:
+        # quick test to ensure that the regular expression will work.
+        # the string must start with <?xml. this will catch
+        # other encodings such as: <\x00?\x00x\x00m\x00l
+        if not metadata.startswith("<?xml"):
+            reporter.logError(message=errorMessage)
+            return
+        # go to the first occurance of >
+        line = metadata.split(">", 1)[0]
+        # find an encoding string
+        pattern = re.compile(
+            "\s+"
+            "encoding"
+            "\s*"
+            "="
+            "\s*"
+            "[\"']+"
+            "([^\"']+)"
+        )
+        m = pattern.search(line)
+        if m:
+            encoding = m.group(1)
+        else:
+            encoding = "UTF-8"
+    # report
+    if encoding != "UTF-8":
+        reporter.logError(message=errorMessage)
+    else:
+        reporter.logPass(message="The metadata is properly encoded.")
+
+def _testMetadataStructure(data, reporter):
+    """
+    Test the metadata structure.
+    """
+    if _shouldSkipMetadataTest(data, reporter):
+        return
+    tree = unpackMetadata(data)
+    # make sure the top element is metadata
+    if tree.tag != "metadata":
+        reporter.logError("The top element is not \"metadata\".")
+        return
+    # sniff the version
+    version = tree.attrib.get("version")
+    if not version:
+        reporter.logError("The \"version\" attribute is not defined.")
+        return
+    # grab the appropriate specification
+    versionSpecs = {
+        "1.0" : metadataSpec_1_0
+    }
+    spec = versionSpecs.get(version)
+    if spec is None:
+        reporter.logError("Unknown version (\"%s\")." % version)
+        return
+    haveError = _validateMetadataElement(tree, spec, reporter)
+    if not haveError:
+        reporter.logPass("The \"metadata\" element is properly formatted.")
+
+def _validateMetadataElement(element, spec, reporter, parentTree=[]):
+    haveError = False
+    # unknown attributes
+    knownAttributes = []
+    for attrib in spec["requiredAttributes"].keys() + spec["recommendedAttributes"].keys() + spec["optionalAttributes"].keys():
+        attrib = _parseAttribute(attrib)
+        knownAttributes.append(attrib)
+    for attrib in sorted(element.attrib.keys()):
+        # the search is a bit complicated because there are
+        # attributes that have more than one name.
+        found = False
+        for knownAttrib in knownAttributes:
+            if knownAttrib == attrib:
+                found = True
+                break
+            elif isinstance(knownAttrib, list) and attrib in knownAttrib:
+                found = True
+                break
+        if not found:
+            _logMetadataResult(
+                reporter,
+                "error",
+                "Unknown attribute (\"%s\")" % attrib,
+                element.tag,
+                parentTree
+            )
+            haveError = True
+    # attributes
+    s = [
+        ("requiredAttributes", "required"),
+        ("recommendedAttributes", "recommended"),
+        ("optionalAttributes", "optional")
+    ]
+    for key, requirementLevel in s:
+        if spec[key]:
+            e = _validateAttributes(element, spec[key], reporter, parentTree, requirementLevel)
+            if e:
+                haveError = True
+    # unknown child-elements
+    knownChildElements = spec["requiredChildElements"].keys() + spec["recommendedChildElements"].keys() + spec["optionalChildElements"].keys()
+    for childElement in element:
+        if childElement.tag not in knownChildElements:
+           _logMetadataResult(
+               reporter,
+               "error",
+               "Unknown child-element (\"%s\")" % childElement.tag,
+               element.tag,
+               parentTree
+           )
+           haveError = True
+    # child elements
+    s = [
+        ("requiredChildElements", "required"),
+        ("recommendedChildElements", "recommended"),
+        ("optionalChildElements", "optional")
+    ]
+    for key, requirementLevel in s:
+        if spec[key]:
+            for childElementTag, childElementData in sorted(spec[key].items()):
+                e = _validateChildElements(element, childElementTag, childElementData, reporter, parentTree, requirementLevel)
+                if e:
+                    haveError = True
+    # content
+    content = element.text
+    if content is not None:
+        content = content.strip()
+    if content and spec["content"] == "not allowed":
+        _logMetadataResult(
+            reporter,
+            "error",
+            "Content defined",
+            element.tag,
+            parentTree
+        )
+        haveError = True
+    elif not content and content and spec["content"] == "required":
+        _logMetadataResult(
+            reporter,
+            "error",
+            "Content not defined",
+            element.tag,
+            parentTree
+        )
+    elif not content and spec["content"] == "recommended":
+        _logMetadataResult(
+            reporter,
+            "warn",
+            "Content not defined",
+            element.tag,
+            parentTree
+        )
+    # log the result
+    if not haveError and parentTree == ["metadata"]:
+        reporter.logPass("The \"%s\" element is properly formatted." % element.tag)
+    # done
+    return haveError
+
+def _parseAttribute(attrib):
+    if " " in attrib:
+        final = []
+        for a in attrib.split(" "):
+            if a.startswith("xml:"):
+                a = "{http://www.w3.org/XML/1998/namespace}" + a[4:]
+            final.append(a)
+        return final
+    return attrib
+
+def _unEtreeAttribute(attrib):
+    ns = "{http://www.w3.org/XML/1998/namespace}"
+    if attrib.startswith(ns):
+        attrib = "xml:" + attrib[len(ns):]
+    return attrib
+
+def _validateAttributes(element, spec, reporter, parentTree, requirementLevel):
+    haveError = False
+    for attrib, valueOptions in sorted(spec.items()):
+        attribs = _parseAttribute(attrib)
+        if isinstance(attribs, basestring):
+            attribs = [attribs]
+        found = []
+        for attrib in attribs:
+            if attrib in element.attrib:
+                found.append(attrib)
+        # make strings for reporting
+        if len(attribs) > 1:
+            attribString = ", ".join(["\"%s\"" % _unEtreeAttribute(i) for i in attribs])
+        else:
+            attribString = "\"%s\"" % attribs[0]
+        if len(found) == 0:
+            pass
+        elif len(found) > 1:
+            foundString = ", ".join(["\"%s\"" % _unEtreeAttribute(i) for i in found])
+        else:
+            foundString = "\"%s\"" % found[0]
+        # more than one of the mutually exclusive attributes found
+        if len(found) > 1:
+            _logMetadataResult(
+                reporter,
+                "error",
+                "More than one mutually exclusive attribute (%s) defined" % foundString,
+                element.tag,
+                parentTree
+            )
+            haveError = True
+        # missing
+        elif len(found) == 0:
+            if requirementLevel == "optional":
+                continue
+            elif requirementLevel == "required":
+                errorLevel = "error"
+            else:
+                errorLevel = "warn"
+            _logMetadataResult(
+                reporter,
+                errorLevel,
+                "%s \"%s\" attribute not defined" % (requirementLevel.title(), attrib),
+                element.tag,
+                parentTree
+            )
+            if requirementLevel == "required":
+                haveError = True
+        # incorrect value
+        else:
+            e = _validateAttributeValue(element, found[0], valueOptions, reporter, parentTree)
+            if e:
+                haveError = True
+    # done
+    return haveError
+
+def _validateAttributeValue(element, attrib, valueOptions, reporter, parentTree):
+    haveError = False
+    value = element.attrib[attrib]
+    if isinstance(valueOptions, basestring):
+        valueOptions = [valueOptions]
+    # no defined value options
+    if valueOptions is None:
+        # the string is empty
+        if not value:
+            _logMetadataResult(
+                reporter,
+                "warn",
+                "Value for the \"%s\" attribute is an empty string" % attrib,
+                element.tag,
+                parentTree
+            )
+    # illegal value
+    elif value not in valueOptions:
+        _logMetadataResult(
+            reporter,
+            "error",
+            "Invalid value (\"%s\") for the \"%s\" attribute" % (value, attrib),
+            element.tag,
+            parentTree
+        )
+        haveError = True
+    # return the error state
+    return haveError
+
+def _validateChildElements(element, childElementTag, childElementData, reporter, parentTree, requirementLevel):
+    haveError = False
+    # get the valid counts
+    minimumOccurrences = childElementData.get("minimumOccurrences", 0)
+    maximumOccurrences = childElementData.get("maximumOccurrences", None)
+    # find the appropriate elements
+    found = element.findall(childElementTag)
+    # not defined enough times
+    if minimumOccurrences == 1 and len(found) == 0:
+        _logMetadataResult(
+            reporter,
+            "error",
+            "%s \"%s\" child-element not defined" % (requirementLevel.title(), childElementTag),
+            element.tag,
+            parentTree
+        )
+        haveError = True
+    elif len(found) < minimumOccurrences:
+        _logMetadataResult(
+            reporter,
+            "error",
+            "%s \"%s\" child-element is defined %d times instead of the minimum %d times" % (requirementLevel.title(), childElementTag, len(found), minimumOccurrences),
+            element.tag,
+            parentTree
+        )
+        haveError = True
+    # not defined, but not recommended
+    elif len(found) == 0 and requirementLevel == "recommended":
+        _logMetadataResult(
+            reporter,
+            "warn",
+            "%s \"%s\" child-element is not defined" % (requirementLevel.title(), childElementTag),
+            element.tag,
+            parentTree
+        )
+    # defined too many times
+    if maximumOccurrences is not None:
+        if maximumOccurrences == 1 and len(found) > 1:
+            _logMetadataResult(
+                reporter,
+                "error",
+                "%s \"%s\" child-element defined more than once" % (requirementLevel.title(), childElementTag),
+                element.tag,
+                parentTree
+            )
+            haveError = True
+        elif len(found) > maximumOccurrences:
+            _logMetadataResult(
+                reporter,
+                "error",
+                "%s \"%s\" child-element defined %d times instead of the maximum %d times" % (requirementLevel.title(), childElementTag, len(found), minimumOccurrences),
+                element.tag,
+                parentTree
+            )
+            haveError = True
+    # validate the found elements
+    if not haveError:
+        for childElement in found:
+            # handle recursive child-elements
+            childElementSpec = childElementData["spec"]
+            if childElementSpec == "recursive divSpec_1_0":
+                childElementSpec = divSpec_1_0
+            elif childElementSpec == "recursive spanSpec_1_0":
+                childElementSpec = spanSpec_1_0
+            # dive
+            e = _validateMetadataElement(childElement, childElementSpec, reporter, parentTree + [element.tag])
+            if e:
+                haveError = True
+    # return the error state
+    return haveError
+
+# logging support
+
+def _logMetadataResult(reporter, result, message, elementTag, parentTree):
+    message = _formatMetadataResultMessage(message, elementTag, parentTree)
+    methods = {
+        "error" : reporter.logError,
+        "warn" : reporter.logWarning,
+        "note" : reporter.logNote,
+        "pass" : reporter.logPass
+    }
+    methods[result](message)
+
+def _formatMetadataResultMessage(message, elementTag, parentTree):
+    parentTree = parentTree + [elementTag]
+    if parentTree[0] == "metadata":
+        parentTree = parentTree[1:]
+    if parentTree:
+        parentTree = ["\"%s\"" % t for t in reversed(parentTree) if t is not None]
+        message += " in " + " in ".join(parentTree)
+    message += "."
+    return message
+
+# -------------------------
+# Support: Misc. SFNT Stuff
+# -------------------------
+
+# Some of this was adapted from fontTools.ttLib.sfnt
+
+sfntHeaderFormat = """
+    sfntVersion:    4s
+    numTables:      H
+    searchRange:    H
+    entrySelector:  H
+    rangeShift:     H
+"""
+sfntHeaderSize = structCalcSize(sfntHeaderFormat)
+
+sfntDirectoryEntryFormat = """
+    tag:            4s
+    checkSum:       L
+    offset:         L
+    length:         L
+"""
+sfntDirectoryEntrySize = structCalcSize(sfntDirectoryEntryFormat)
+
+def maxPowerOfTwo(value):
+    exponent = 0
+    while value:
+        value = value >> 1
+        exponent += 1
+    return max(exponent - 1, 0)
+
+def getSearchRange(numTables):
+    exponent = maxPowerOfTwo(numTables)
+    searchRange = (2 ** exponent) * 16
+    entrySelector = exponent
+    rangeShift = numTables * 16 - searchRange
+    return searchRange, entrySelector, rangeShift
+
+def calcPaddingLength(length):
+    if not length % 4:
+        return 0
+    return 4 - (length % 4)
+
+def padData(data):
+    data += "\0" * calcPaddingLength(len(data))
+    return data
+
+def sumDataULongs(data):
+    longs = struct.unpack(">%dL" % (len(data) / 4), data)
+    value = sum(longs) % (2 ** 32)
+    return value
+
+def calcChecksum(tag, data):
+    if tag == "head":
+        data = data[:8] + "\0\0\0\0" + data[12:]
+    data = padData(data)
+    value = sumDataULongs(data)
+    return value
+
+def calcHeadChecksum(data):
+    header = unpackHeader(data)
+    directory = unpackDirectory(data)
+    numTables = header["numTables"]
+    # build the sfnt directory
+    searchRange, entrySelector, rangeShift = getSearchRange(numTables)
+    sfntHeaderData = dict(
+        sfntVersion=header["flavor"],
+        numTables=numTables,
+        searchRange=searchRange,
+        entrySelector=entrySelector,
+        rangeShift=rangeShift
+    )
+    sfntData = structPack(sfntHeaderFormat, sfntHeaderData)
+    sfntEntries = {}
+    offset = sfntHeaderSize + (sfntDirectoryEntrySize * numTables)
+    directory = [(entry["offset"], entry) for entry in directory]
+    for o, entry in sorted(directory):
+        checksum = entry["origChecksum"]
+        tag = entry["tag"]
+        length = entry["origLength"]
+        sfntEntries[tag] = dict(
+            tag=tag,
+            checkSum=checksum,
+            offset=offset,
+            length=length
+        )
+        offset += length + calcPaddingLength(length)
+    for tag, sfntEntry in sorted(sfntEntries.items()):
+        sfntData += structPack(sfntDirectoryEntryFormat, sfntEntry)
+    # calculate
+    checkSums = [entry["checkSum"] for entry in sfntEntries.values()]
+    checkSums.append(sumDataULongs(sfntData))
+    checkSum = sum(checkSums)
+    checkSum = (0xB1B0AFBA - checkSum) & 0xffffffff
+    return checkSum
+
+# ------------------
+# Support XML Writer
+# ------------------
+
+class XMLWriter(object):
+
+    def __init__(self):
+        self._root = None
+        self._elements = []
+
+    def simpletag(self, tag, **kwargs):
+        ElementTree.SubElement(self._elements[-1], tag, **kwargs)
+
+    def begintag(self, tag, **kwargs):
+        if self._elements:
+            s = ElementTree.SubElement(self._elements[-1], tag, **kwargs)
+        else:
+            s = ElementTree.Element(tag, **kwargs)
+            if self._root is None:
+                self._root = s
+        self._elements.append(s)
+
+    def endtag(self, tag):
+        assert self._elements[-1].tag == tag
+        del self._elements[-1]
+
+    def write(self, text):
+        if self._elements[-1].text is None:
+            self._elements[-1].text = text
+        else:
+            self._elements[-1].text += text
+
+    def compile(self, encoding="utf-8"):
+        f = StringIO()
+        tree = ElementTree.ElementTree(self._root)
+        indent(tree.getroot())
+        tree.write(f, encoding=encoding)
+        text = f.getvalue()
+        del f
+        return text
+
+def indent(elem, level=0):
+    # this is from http://effbot.python-hosting.com/file/effbotlib/ElementTree.py
+    i = "\n" + level * "\t"
+    if len(elem):
+        if not elem.text or not elem.text.strip():
+            elem.text = i + "\t"
+        for e in elem:
+            indent(e, level + 1)
+        if not e.tail or not e.tail.strip():
+            e.tail = i
+    if level and (not elem.tail or not elem.tail.strip()):
+        elem.tail = i
+
+# ---------------------------------
+# Support: Reporters and HTML Stuff
+# ---------------------------------
+
+class TestResultGroup(list):
+
+    def __init__(self, title):
+        super(TestResultGroup, self).__init__()
+        self.title = title
+
+    def _haveType(self, tp):
+        for data in self:
+            if data["type"] == tp:
+                return True
+        return False
+
+    def haveNote(self):
+        return self._haveType("NOTE")
+
+    def haveWarning(self):
+        return self._haveType("WARNING")
+
+    def haveError(self):
+        return self._haveType("ERROR")
+
+    def havePass(self):
+        return self._haveType("PASS")
+
+    def haveTraceback(self):
+        return self._haveType("TRACEBACK")
+
+
+class BaseReporter(object):
+
+    """
+    Base reporter. This establishes the required API for reporters.
+    """
+
+    def __init__(self):
+        self.title = ""
+        self.fileInfo = []
+        self.testResults = []
+        self.haveReadError = False
+
+    def logTitle(self, title):
+        self.title = title
+
+    def logFileInfo(self, title, value):
+        self.fileInfo.append((title, value))
+
+    def logTableInfo(self, tag=None, offset=None, compLength=None, origLength=None, origChecksum=None):
+        self.tableInfo.append((tag, offset, compLength, origLength, origChecksum))
+
+    def logTestTitle(self, title):
+        self.testResults.append(TestResultGroup(title))
+
+    def logNote(self, message, information=""):
+        d = dict(type="NOTE", message=message, information=information)
+        self.testResults[-1].append(d)
+
+    def logWarning(self, message, information=""):
+        d = dict(type="WARNING", message=message, information=information)
+        self.testResults[-1].append(d)
+
+    def logError(self, message, information=""):
+        d = dict(type="ERROR", message=message, information=information)
+        self.testResults[-1].append(d)
+
+    def logPass(self, message, information=""):
+        d = dict(type="PASS", message=message, information=information)
+        self.testResults[-1].append(d)
+
+    def logTraceback(self, text):
+        d = dict(type="TRACEBACK", message=text, information="")
+        self.testResults[-1].append(d)
+
+    def getReport(self, *args, **kwargs):
+        raise NotImplementedError
+
+    def numErrors(self):
+        numErrors = 0
+        for group in self.testResults:
+            for result in group:
+                if result["type"] == "ERROR":
+                    numErrors = numErrors + 1
+        return numErrors
+
+class TextReporter(BaseReporter):
+
+    """
+    Plain text reporter.
+    """
+
+    def getReport(self, reportNote=True, reportWarning=True, reportError=True, reportPass=True):
+        report = []
+        for group in self.testResults:
+            for result in group:
+                typ = result["type"]
+                if typ == "NOTE" and not reportNote:
+                    continue
+                elif typ == "WARNING" and not reportWarning:
+                    continue
+                elif typ == "ERROR" and not reportError:
+                    continue
+                elif typ == "PASS" and not reportPass:
+                    continue
+                t = "%s - %s: %s" % (result["type"], group.title, result["message"])
+                report.append(t)
+        return "\n".join(report)
+
+
+class HTMLReporter(BaseReporter):
+
+    def getReport(self):
+        writer = startHTML(title=self.title)
+        # write the file info
+        self._writeFileInfo(writer)
+        # write major error alert
+        if self.haveReadError:
+            self._writeMajorError(writer)
+        # write the test overview
+        self._writeTestResultsOverview(writer)
+        # write the test groups
+        self._writeTestResults(writer)
+        # close the html
+        text = finishHTML(writer)
+        # done
+        return text
+
+    def _writeFileInfo(self, writer):
+        # write the font info
+        writer.begintag("div", c_l_a_s_s="infoBlock")
+        ## title
+        writer.begintag("h3", c_l_a_s_s="infoBlockTitle")
+        writer.write("File Information")
+        writer.endtag("h3")
+        ## table
+        writer.begintag("table", c_l_a_s_s="report")
+        ## items
+        for title, value in self.fileInfo:
+            # row
+            writer.begintag("tr")
+            # title
+            writer.begintag("td", c_l_a_s_s="title")
+            writer.write(title)
+            writer.endtag("td")
+            # message
+            writer.begintag("td")
+            writer.write(value)
+            writer.endtag("td")
+            # close row
+            writer.endtag("tr")
+        writer.endtag("table")
+        ## close the container
+        writer.endtag("div")
+
+    def _writeMajorError(self, writer):
+        writer.begintag("h2", c_l_a_s_s="readError")
+        writer.write("The file contains major structural errors!")
+        writer.endtag("h2")
+
+    def _writeTestResultsOverview(self, writer):
+        ## tabulate
+        notes = 0
+        passes = 0
+        errors = 0
+        warnings = 0
+        for group in self.testResults:
+            for data in group:
+                tp = data["type"]
+                if tp == "NOTE":
+                    notes += 1
+                elif tp == "PASS":
+                    passes += 1
+                elif tp == "ERROR":
+                    errors += 1
+                else:
+                    warnings += 1
+        total = sum((notes, passes, errors, warnings))
+        ## container
+        writer.begintag("div", c_l_a_s_s="infoBlock")
+        ## header
+        writer.begintag("h3", c_l_a_s_s="infoBlockTitle")
+        writer.write("Results for %d Tests" % total)
+        writer.endtag("h3")
+        ## results
+        results = [
+            ("PASS", passes),
+            ("WARNING", warnings),
+            ("ERROR", errors),
+            ("NOTE", notes),
+        ]
+        writer.begintag("table", c_l_a_s_s="report")
+        for tp, value in results:
+            # title
+            writer.begintag("tr", c_l_a_s_s="testReport%s" % tp.title())
+            writer.begintag("td", c_l_a_s_s="title")
+            writer.write(tp)
+            writer.endtag("td")
+            # count
+            writer.begintag("td", c_l_a_s_s="testReportResultCount")
+            writer.write(str(value))
+            writer.endtag("td")
+            # empty
+            writer.begintag("td")
+            writer.endtag("td")
+            # toggle button
+            buttonID = "testResult%sToggleButton" % tp
+            writer.begintag("td",
+                id=buttonID, c_l_a_s_s="toggleButton",
+                onclick="testResultToggleButtonHit(a_p_o_s_t_r_o_p_h_e%sa_p_o_s_t_r_o_p_h_e, a_p_o_s_t_r_o_p_h_e%sa_p_o_s_t_r_o_p_h_e);" % (buttonID, "test%s" % tp.title()))
+            writer.write("Hide")
+            writer.endtag("td")
+            # close the row
+            writer.endtag("tr")
+        writer.endtag("table")
+        ## close the container
+        writer.endtag("div")
+
+    def _writeTestResults(self, writer):
+        for infoBlock in self.testResults:
+            # container
+            writer.begintag("div", c_l_a_s_s="infoBlock")
+            # header
+            writer.begintag("h4", c_l_a_s_s="infoBlockTitle")
+            writer.write(infoBlock.title)
+            writer.endtag("h4")
+            # individual reports
+            writer.begintag("table", c_l_a_s_s="report")
+            for data in infoBlock:
+                tp = data["type"]
+                message = data["message"]
+                information = data["information"]
+                # row
+                writer.begintag("tr", c_l_a_s_s="test%s" % tp.title())
+                # title
+                writer.begintag("td", c_l_a_s_s="title")
+                writer.write(tp)
+                writer.endtag("td")
+                # message
+                writer.begintag("td")
+                writer.write(message)
+                ## info
+                if information:
+                    writer.begintag("p", c_l_a_s_s="info")
+                    writer.write(information)
+                    writer.endtag("p")
+                writer.endtag("td")
+                # close row
+                writer.endtag("tr")
+            writer.endtag("table")
+            # close container
+            writer.endtag("div")
+
+
+defaultCSS = """
+body {
+	background-color: #e5e5e5;
+	padding: 15px 15px 0px 15px;
+	margin: 0px;
+	font-family: Helvetica, Verdana, Arial, sans-serif;
+}
+
+h2.readError {
+	background-color: red;
+	color: white;
+	margin: 20px 15px 20px 15px;
+	padding: 10px;
+	border-radius: 5px;
+	font-size: 25px;
+}
+
+/* info blocks */
+
+.infoBlock {
+	background-color: white;
+	margin: 0px 0px 15px 0px;
+	padding: 15px;
+	border-radius: 5px;
+}
+
+h3.infoBlockTitle {
+	font-size: 20px;
+	margin: 0px 0px 15px 0px;
+	padding: 0px 0px 10px 0px;
+	border-bottom: 1px solid #e5e5e5;
+}
+
+h4.infoBlockTitle {
+	font-size: 17px;
+	margin: 0px 0px 15px 0px;
+	padding: 0px 0px 10px 0px;
+	border-bottom: 1px solid #e5e5e5;
+}
+
+table.report {
+	border-collapse: collapse;
+	width: 100%;
+	font-size: 14px;
+}
+
+table.report tr {
+	border-top: 1px solid white;
+}
+
+table.report tr.testPass, table.report tr.testReportPass {
+	background-color: #c8ffaf;
+}
+
+table.report tr.testError, table.report tr.testReportError {
+	background-color: #ffc3af;
+}
+
+table.report tr.testWarning, table.report tr.testReportWarning {
+	background-color: #ffe1af;
+}
+
+table.report tr.testNote, table.report tr.testReportNote {
+	background-color: #96e1ff;
+}
+
+table.report tr.testTraceback, table.report tr.testReportTraceback {
+	background-color: red;
+	color: white;
+}
+
+table.report td {
+	padding: 7px 5px 7px 5px;
+	vertical-align: top;
+}
+
+table.report td.title {
+	width: 80px;
+	text-align: right;
+	font-weight: bold;
+	text-transform: uppercase;
+}
+
+table.report td.testReportResultCount {
+	width: 100px;
+}
+
+table.report td.toggleButton {
+	text-align: center;
+	width: 50px;
+	border-left: 1px solid white;
+	cursor: pointer;
+}
+
+.infoBlock td p.info {
+	font-size: 12px;
+	font-style: italic;
+	margin: 5px 0px 0px 0px;
+}
+
+/* SFNT table */
+
+table.sfntTableData {
+	font-size: 14px;
+	width: 100%;
+	border-collapse: collapse;
+	padding: 0px;
+}
+
+table.sfntTableData th {
+	padding: 5px 0px 5px 0px;
+	text-align: left
+}
+
+table.sfntTableData tr.uncompressed {
+	background-color: #ffc3af;
+}
+
+table.sfntTableData td {
+	width: 20%;
+	padding: 5px 0px 5px 0px;
+	border: 1px solid #e5e5e5;
+	border-left: none;
+	border-right: none;
+	font-family: Consolas, Menlo, "Vera Mono", Monaco, monospace;
+}
+
+pre {
+	font-size: 12px;
+	font-family: Consolas, Menlo, "Vera Mono", Monaco, monospace;
+	margin: 0px;
+	padding: 0px;
+}
+
+/* Metadata */
+
+.metadataElement {
+	background: rgba(0, 0, 0, 0.03);
+	margin: 10px 0px 10px 0px;
+	border: 2px solid #d8d8d8;
+	padding: 10px;
+}
+
+h5.metadata {
+	font-size: 14px;
+	margin: 5px 0px 10px 0px;
+	padding: 0px 0px 5px 0px;
+	border-bottom: 1px solid #d8d8d8;
+}
+
+h6.metadata {
+	font-size: 12px;
+	font-weight: normal;
+	margin: 10px 0px 10px 0px;
+	padding: 0px 0px 5px 0px;
+	border-bottom: 1px solid #d8d8d8;
+}
+
+table.metadata {
+	font-size: 12px;
+	width: 100%;
+	border-collapse: collapse;
+	padding: 0px;
+}
+
+table.metadata td.key {
+	width: 5em;
+	padding: 5px 5px 5px 0px;
+	border-right: 1px solid #d8d8d8;
+	text-align: right;
+	vertical-align: top;
+}
+
+table.metadata td.value {
+	padding: 5px 0px 5px 5px;
+	border-left: 1px solid #d8d8d8;
+	text-align: left;
+	vertical-align: top;
+}
+
+p.metadata {
+	font-size: 12px;
+	font-style: italic;
+}
+}
+"""
+
+defaultJavascript = """
+
+//<![CDATA[
+	function testResultToggleButtonHit(buttonID, className) {
+		// change the button title
+		var element = document.getElementById(buttonID);
+		if (element.innerHTML == "Show" ) {
+			element.innerHTML = "Hide";
+		}
+		else {
+			element.innerHTML = "Show";
+		}
+		// toggle the elements
+		var elements = getTestResults(className);
+		for (var e = 0; e < elements.length; ++e) {
+			toggleElement(elements[e]);
+		}
+		// toggle the info blocks
+		toggleInfoBlocks();
+	}
+
+	function getTestResults(className) {
+		var rows = document.getElementsByTagName("tr");
+		var found = Array();
+		for (var r = 0; r < rows.length; ++r) {
+			var row = rows[r];
+			if (row.className == className) {
+				found[found.length] = row;
+			}
+		}
+		return found;
+	}
+
+	function toggleElement(element) {
+		if (element.style.display != "none" ) {
+			element.style.display = "none";
+		}
+		else {
+			element.style.display = "";
+		}
+	}
+
+	function toggleInfoBlocks() {
+		var tables = document.getElementsByTagName("table")
+		for (var t = 0; t < tables.length; ++t) {
+			var table = tables[t];
+			if (table.className == "report") {
+				var haveVisibleRow = false;
+				var rows = table.rows;
+				for (var r = 0; r < rows.length; ++r) {
+					var row = rows[r];
+					if (row.style.display == "none") {
+						var i = 0;
+					}
+					else {
+						haveVisibleRow = true;
+					}
+				}
+				var div = table.parentNode;
+				if (haveVisibleRow == true) {
+					div.style.display = "";
+				}
+				else {
+					div.style.display = "none";
+				}
+			}
+		}
+	}
+//]]>
+"""
+
+def startHTML(title=None, cssReplacements={}):
+    writer = XMLWriter()
+    # start the html
+    writer.begintag("html", xmlns="http://www.w3.org/1999/xhtml", lang="en")
+    # start the head
+    writer.begintag("head")
+    writer.simpletag("meta", http_equiv="Content-Type", content="text/html; charset=utf-8")
+    # title
+    if title is not None:
+        writer.begintag("title")
+        writer.write(title)
+        writer.endtag("title")
+    # write the css
+    writer.begintag("style", type="text/css")
+    css = defaultCSS
+    for before, after in cssReplacements.items():
+        css = css.replace(before, after)
+    writer.write(css)
+    writer.endtag("style")
+    # write the javascript
+    writer.begintag("script", type="text/javascript")
+    javascript = defaultJavascript
+    ## hack around some ElementTree escaping
+    javascript = javascript.replace("<", "l_e_s_s")
+    javascript = javascript.replace(">", "g_r_e_a_t_e_r")
+    writer.write(javascript)
+    writer.endtag("script")
+    # close the head
+    writer.endtag("head")
+    # start the body
+    writer.begintag("body")
+    # return the writer
+    return writer
+
+def finishHTML(writer):
+    # close the body
+    writer.endtag("body")
+    # close the html
+    writer.endtag("html")
+    # get the text
+    text = "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\" \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\">\n"
+    text += writer.compile()
+    text = text.replace("c_l_a_s_s", "class")
+    text = text.replace("a_p_o_s_t_r_o_p_h_e", "'")
+    text = text.replace("l_e_s_s", "<")
+    text = text.replace("g_r_e_a_t_e_r", ">")
+    text = text.replace("http_equiv", "http-equiv")
+    # return
+    return text
+
+# ------------------
+# Support: Unpackers
+# ------------------
+
+def unpackHeader(data):
+    return structUnpack(headerFormat, data)[0]
+
+def unpackDirectory(data):
+    header = unpackHeader(data)
+    numTables = header["numTables"]
+    data = data[headerSize:]
+    directory = []
+    for index in range(numTables):
+        table, data = structUnpack(directoryFormat, data)
+        directory.append(table)
+    return directory
+
+def unpackTableData(data):
+    directory = unpackDirectory(data)
+    tables = {}
+    for entry in directory:
+        tag = entry["tag"]
+        offset = entry["offset"]
+        origLength = entry["origLength"]
+        compLength = entry["compLength"]
+        if offset > len(data) or offset < 0 or (offset + compLength) < 0:
+            tableData = ""
+        elif offset + compLength > len(data):
+            tableData = data[offset:]
+        else:
+            tableData = data[offset:offset+compLength]
+        if compLength < origLength:
+            try:
+                td = zlib.decompress(tableData)
+                tableData = td
+            except zlib.error:
+                tableData = None
+        tables[tag] = tableData
+    return tables
+
+def unpackMetadata(data, decompress=True, parse=True):
+    header = unpackHeader(data)
+    data = data[header["metaOffset"]:header["metaOffset"]+header["metaLength"]]
+    if decompress and data:
+        data = zlib.decompress(data)
+    if parse and data:
+        data = ElementTree.fromstring(data)
+    return data
+
+def unpackPrivateData(data):
+    header = unpackHeader(data)
+    data = data[header["privOffset"]:header["privOffset"]+header["privLength"]]
+    return data
+
+# -----------------------
+# Support: Report Helpers
+# -----------------------
+
+def findUniqueFileName(path):
+    if not os.path.exists(path):
+        return path
+    folder = os.path.dirname(path)
+    fileName = os.path.basename(path)
+    fileName, extension = os.path.splitext(fileName)
+    stamp = time.strftime("%Y-%m-%d %H-%M-%S %Z")
+    newFileName = "%s (%s)%s" % (fileName, stamp, extension)
+    newPath = os.path.join(folder, newFileName)
+    # intentionally break to prevent a file overwrite.
+    # this could happen if the user has a directory full
+    # of files with future time stamped file names.
+    # not likely, but avoid it all the same.
+    assert not os.path.exists(newPath)
+    return newPath
+
+
+# ---------------
+# Public Function
+# ---------------
+
+tests = [
+    ("Header",          testHeader),
+    ("Data Blocks",     testDataBlocks),
+    ("Table Directory", testTableDirectory),
+    ("Table Data",      testTableData),
+    ("Metadata",        testMetadata)
+]
+
+def validateFont(path, options, writeFile=True):
+    # start the reporter
+    if options.outputFormat == "html":
+        reporter = HTMLReporter()
+    elif options.outputFormat == "text":
+        reporter = TextReporter()
+    else:
+        raise NotImplementedError
+    # log the title
+    reporter.logTitle("Report: %s" % os.path.basename(path))
+    # log fileinfo
+    reporter.logFileInfo("FILE", os.path.basename(path))
+    reporter.logFileInfo("DIRECTORY", os.path.dirname(path))
+    # run tests and log results
+    f = open(path, "rb")
+    data = f.read()
+    f.close()
+    shouldStop = False
+    for title, func in tests:
+        # skip groups that are not specified in the options
+        if options.testGroups and title not in options.testGroups:
+            continue
+        reporter.logTestTitle(title)
+        shouldStop = func(data, reporter)
+        if shouldStop:
+            break
+    reporter.haveReadError = shouldStop
+    # get the report
+    report = reporter.getReport()
+    # write
+    reportPath = None
+    if writeFile:
+        # make the output file name
+        if options.outputFileName is not None:
+            fileName = options.outputFileName
+        else:
+            fileName = os.path.splitext(os.path.basename(path))[0]
+            fileName += "_validate"
+            if options.outputFormat == "html":
+                fileName += ".html"
+            else:
+                fileName += ".txt"
+        # make the output directory
+        if options.outputDirectory is not None:
+            directory = options.outputDirectory
+        else:
+            directory = os.path.dirname(path)
+        # write the file
+        reportPath = os.path.join(directory, fileName)
+        reportPath = findUniqueFileName(reportPath)
+        f = open(reportPath, "wb")
+        f.write(report)
+        f.close()
+    return reportPath, report, reporter.numErrors()
+
+# --------------------
+# Command Line Behvior
+# --------------------
+
+usage = "%prog [options] fontpath1 fontpath2"
+
+description = """This tool examines the structure of one
+or more WOFF files and issues a detailed report about
+the validity of the file structure. It does not validate
+the wrapped font data.
+"""
+
+def main():
+    parser = optparse.OptionParser(usage=usage, description=description, version="%prog 0.1beta")
+    parser.add_option("-d", dest="outputDirectory", help="Output directory. The default is to output the report into the same directory as the font file.")
+    parser.add_option("-o", dest="outputFileName", help="Output file name. The default is \"fontfilename_validate.html\".")
+    parser.add_option("-f", dest="outputFormat", help="Output format, text|html. The default is html.", default="html")
+    parser.add_option("-q", dest="quiet", action="store_true", help="No report written", default=False)
+
+
+    parser.set_defaults(excludeTests=[])
+    (options, args) = parser.parse_args()
+    outputDirectory = options.outputDirectory
+    options.testGroups = None # don't expose this to the commandline. it's for testing only.
+    if outputDirectory is not None and not os.path.exists(outputDirectory):
+        print "Directory does not exist:", outputDirectory
+        sys.exit()
+    for fontPath in args:
+        if not os.path.exists(fontPath):
+            print "File does not exist:", fontPath
+            sys.exit()
+        else:
+            if not options.quiet: print "Testing: %s..." % fontPath
+            writeFile = True if not options.quiet else False
+            fontPath = fontPath.decode("utf-8")
+            outputPath, report, numErrors = validateFont(fontPath, options, writeFile)
+            if not options.quiet: print "Wrote report to: %s" % outputPath
+    # exit code
+    if numErrors > 0: sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()