# TrueType/OpenType Table Modules

This folder is a subpackage of `fontTools.ttLib`. Each module here is a specialized TT/OT table converter: they can convert raw data to Python objects and vice versa. Usually you don’t need to use the modules directly: they are imported and used automatically when needed by `fontTools.ttLib`. The tables currently supported are:

- `ankr`: Anchor Point Table
- `avar`: Axis Variations Table
- `BASE`: Baseline Table
- `bsln`: Baseline
- `CBDT`: Color Bitmap Data Table
- `CBLC`: Color Bitmap Location Table
- `CFF`: Compact Font Format Table
- `CFF2`: Compact Font Format (CFF) Version 2
- `cidg`: CID to Glyph ID table
- `cmap`: Character to Glyph Index Mapping Table
- `COLR`: Color Table
- `CPAL`: Color Palette Table
- `cvar`: CVT Variations Table
- `cvt`: Control Value Table
- `DSIG`: Digital Signature Table
- `EBDT`: Embedded Bitmap Data Table
- `EBLC`: Embedded Bitmap Location Table
- `Feat`: Graphite Feature Table
- `feat`: Feature name table
- `FFTM`: FontForge Time Stamp Table
- `fpgm`: Font Program
- `fvar`: Font Variations Table
- `gasp`: Grid-fitting and Scan-conversion Procedure Table
- `gcid`: Glyph ID to CID table
- `GDEF`: Glyph Definition Table
- `Glat`: Graphite Glyph Attributes Table
- `Gloc`: Graphite index to glyph attributes table
- `glyf`: Glyph Data
- `GMAP`: SING Glyphlet Summary Table
- `GPKG`: SING Glyphlet Wrapper Table
- `GPOS`: Glyph Positioning Table
- `GSUB`: Glyph Substitution Table
- `gvar`: Glyph Variations Table
- `hdmx`: Horizontal Device Metrics
- `head`: Font Header Table
- `hhea`: Horizontal Header Table
- `hmtx`: Horizontal Metrics Table
- `HVAR`:Horizontal Metrics Variations Table
- `JSTF`: Justification Table
- `kern`: Kerning
- `lcar`: Ligature Caret Table
- `loca`: Index to Location
- `ltag`: Language Tag
- `LTSH`: Linear Threshold
- `MATH`: Mathematical Typesetting Table
- `maxp`: Maximum Profile
- `META`: SING Glyphlet Metadata Table
- `meta`: Metadata Table
- `mort`: Glyph Metamorphosis Table
- `morx`: Extended Glyph Metamorphosis Table
- `MVAR`: Metrics Variations Table
- `name`: Naming Table
- `opbd`: Optical Bounds Table
- `OS/2`: OS/2 and Windows Metrics Table
- `post`: PostScript Table
- `prep`: Control Value Program
- `prop`: Glyph Properties Table
- `sbix`: Standard Bitmap Graphics Table
- `Silf`: Graphite Rules Table
- `Sill`: Graphite Languages Table
- `SING`: SING Glyphlet Basic Information Table
- `STAT`: Style Attributes Table
- `SVG`: SVG (Scalable Vector Graphics) Table
- `trak`: Tracking table
- `TTFA`: `ttfautohint` Parameter Table
- `VDMX`: Vertical Device Metrics
- `vhea`: Vertical Header Table
- `vmtx`: Vertical Metrics Table
- `VORG`: Vertical Origin Table
- Visual TrueType Private Tables
- `VVAR`: Vertical Metrics Variations Table

The Python modules representing the tables have pretty strange names: this is due to the fact that we need to map TT table tags (which are case sensitive) to filenames (which on Mac and Win aren’t case sensitive) as well as to Python identifiers. The latter means it can only contain `[A-Za-z0-9_]` and cannot start with a number.

`fontTools.ttLib` provides functions to expand a tag into the format used here:

    >>> from fontTools import ttLib
    >>> ttLib.tagToIdentifier("FOO ")
    'F_O_O_'
    >>> ttLib.tagToIdentifier("cvt ")
    '_c_v_t'
    >>> ttLib.tagToIdentifier("OS/2")
    'O_S_2f_2'
    >>> ttLib.tagToIdentifier("glyf")
    '_g_l_y_f'
    >>>

And vice versa:

    >>> ttLib.identifierToTag("F_O_O_")
    'FOO '
    >>> ttLib.identifierToTag("_c_v_t")
    'cvt '
    >>> ttLib.identifierToTag("O_S_2f_2")
    'OS/2'
    >>> ttLib.identifierToTag("_g_l_y_f")
    'glyf'
    >>>

Eg. the ‘glyf’ table converter lives in a Python file called:

    _g_l_y_f.py

The converter itself is a class, named `table_` + expandedtag. Eg:

    class table__g_l_y_f:
            etc.

Note that if you _do_ need to use such modules or classes manually, there are two convenient API functions that let you find them by tag:

    >>> ttLib.getTableModule('glyf')
    <module 'ttLib.tables._g_l_y_f'>
    >>> ttLib.getTableClass('glyf')
    <class ttLib.tables._g_l_y_f.table__g_l_y_f at 645f400>
    >>

## ttProgram: TrueType bytecode assembler/disassembler

ttLib.tables.ttProgram.py – Assembler/disassembler for TrueType bytecode programs.

class fontTools.ttLib.tables.ttProgram.Program
  fromAssembly(assembly)
  fromBytecode(bytecode)
  fromXML(name, attrs, content, ttFont)
  getAssembly(preserve=True)
  getBytecode()
  toXML(writer, ttFont)

fontTools.ttLib.tables.ttProgram.bitRepr(value, bits)

exception fontTools.ttLib.tables.ttProgram.tt_instructions_error(error)
  add_note()

    Exception.add_note(note) – add a note to the exception

  args
  with_traceback()

    Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

## Contributing your own table convertors

To add support for a new font table that fontTools does not currently implement, you must subclass from `fontTools.ttLib.tables.DefaultTable.DefaultTable`. It provides some default behavior, as well as a constructor method (`__init__`) that you don’t need to override.

Your converter should minimally provide two methods:

    class table_F_O_O_(DefaultTable.DefaultTable): # converter for table 'FOO '

        def decompile(self, data, ttFont):
            # 'data' is the raw table data. Unpack it into a
            # Python data structure.
            # 'ttFont' is a ttLib.TTfile instance, enabling you to
            # refer to other tables. Do ***not*** keep a reference to
            # it: it will cause a circular reference (ttFont saves
            # a reference to us), and that means we'll be leaking
            # memory. If you need to use it in other methods, just
            # pass it around as a method argument.

        def compile(self, ttFont):
            # Return the raw data, as converted from the Python
            # data structure.
            # Again, 'ttFont' is there so you can access other tables.
            # Same warning applies.

If you want to support TTX import/export as well, you need to provide two additional methods:

    def toXML(self, writer, ttFont):
       # XXX

    def fromXML(self, (name, attrs, content), ttFont):
       # XXX