1This folder is a subpackage of ttLib. Each module here is a 
2specialized TT/OT table converter: they can convert raw data 
3to Python objects and vice versa. Usually you don't need to 
4use the modules directly: they are imported and used 
5automatically when needed by ttLib.
6
7If you are writing you own table converter the following is 
8important.
9
10The modules here have pretty strange names: this is due to the 
11fact that we need to map TT table tags (which are case sensitive) 
12to filenames (which on Mac and Win aren't case sensitive) as well 
13as to Python identifiers. The latter means it can only contain 
14[A-Za-z0-9_] and cannot start with a number. 
15
16ttLib provides functions to expand a tag into the format used here:
17
18>>> from fontTools import ttLib
19>>> ttLib.tagToIdentifier("FOO ")
20'F_O_O_'
21>>> ttLib.tagToIdentifier("cvt ")
22'_c_v_t'
23>>> ttLib.tagToIdentifier("OS/2")
24'O_S_2f_2'
25>>> ttLib.tagToIdentifier("glyf")
26'_g_l_y_f'
27>>> 
28
29And vice versa:
30
31>>> ttLib.identifierToTag("F_O_O_")
32'FOO '
33>>> ttLib.identifierToTag("_c_v_t")
34'cvt '
35>>> ttLib.identifierToTag("O_S_2f_2")
36'OS/2'
37>>> ttLib.identifierToTag("_g_l_y_f")
38'glyf'
39>>> 
40
41Eg. the 'glyf' table converter lives in a Python file called:
42
43	_g_l_y_f.py
44
45The converter itself is a class, named "table_" + expandedtag. Eg:
46
47	class table__g_l_y_f:
48		etc.
49
50Note that if you _do_ need to use such modules or classes manually, 
51there are two convenient API functions that let you find them by tag:
52
53>>> ttLib.getTableModule('glyf')
54<module 'ttLib.tables._g_l_y_f'>
55>>> ttLib.getTableClass('glyf')
56<class ttLib.tables._g_l_y_f.table__g_l_y_f at 645f400>
57>>> 
58
59You must subclass from DefaultTable.DefaultTable. It provides some default
60behavior, as well as a constructor method (__init__) that you don't need to 
61override.
62
63Your converter should minimally provide two methods:
64
65class table_F_O_O_(DefaultTable.DefaultTable): # converter for table 'FOO '
66	
67	def decompile(self, data, ttFont):
68		# 'data' is the raw table data. Unpack it into a
69		# Python data structure.
70		# 'ttFont' is a ttLib.TTfile instance, enabling you to
71		# refer to other tables. Do ***not*** keep a reference to
72		# it: it will cause a circular reference (ttFont saves 
73		# a reference to us), and that means we'll be leaking 
74		# memory. If you need to use it in other methods, just 
75		# pass it around as a method argument.
76	
77	def compile(self, ttFont):
78		# Return the raw data, as converted from the Python
79		# data structure. 
80		# Again, 'ttFont' is there so you can access other tables.
81		# Same warning applies.
82
83If you want to support TTX import/export as well, you need to provide two
84additional methods:
85
86	def toXML(self, writer, ttFont):
87		# XXX
88	
89	def fromXML(self, (name, attrs, content), ttFont):
90		# XXX
91
92