1 """
2 :mod:`pyffi.formats` --- File format interfaces
3 ===============================================
4
5 When experimenting with any of the supported file formats, you can specify
6 an alternate location where you store your modified format description by means
7 of an environment variable. For instance,
8 to tell the library to use your version of :file:`cgf.xml`,
9 set the :envvar:`CGFXMLPATH` environment variable to the directory where
10 :file:`cgf.xml` can be found. The environment variables :envvar:`NIFXMLPATH`,
11 :envvar:`KFMXMLPATH`, :envvar:`DDSXMLPATH`, and :envvar:`TGAXMLPATH`
12 work similarly.
13
14 Supported formats
15 -----------------
16
17 .. toctree::
18 :maxdepth: 2
19
20 pyffi.formats.bsa
21 pyffi.formats.cgf
22 pyffi.formats.dae
23 pyffi.formats.dds
24 pyffi.formats.egm
25 pyffi.formats.egt
26 pyffi.formats.esp
27 pyffi.formats.kfm
28 pyffi.formats.nif
29 pyffi.formats.tga
30 pyffi.formats.tri
31
32 Adding new formats
33 ------------------
34
35 This section tries to explain how you can implement your own format in pyffi.
36
37 Getting Started
38 ^^^^^^^^^^^^^^^
39
40 Note that the files which make up the following example can all be found in
41 the examples/simple directory of the source distribution of pyffi.
42
43 Suppose you have a simple file format, which consists of an integer,
44 followed by a list of integers as many as described by the first
45 integer. We start by creating an XML file, call it :file:`simple.xml`,
46 which describes this format in a way that pyffi can understand:
47
48 .. literalinclude:: ../examples/simple/simple.xml
49 :language: xml
50
51 What pyffi does is convert this simple XML description into Python classes
52 which automatically can read and write the structure you've just described.
53 Say this is the contents of :file:`simple.py`:
54
55 .. literalinclude:: ../examples/simple/simple.py
56 :language: python
57
58 What happens in this piece of code?
59
60 - The :class:`pyffi.object_models.xml.FileFormat`
61 base class triggers the transformation of xml into Python classes;
62 how these classes can be used will be explained further.
63
64 - The :attr:`~pyffi.object_models.xml.FileFormat.xml_file_name`
65 class attribute provides the name of the xml file that describes
66 the structures we wish to generate. The
67 :attr:`~pyffi.object_models.xml.FileFormat.xml_file_path`
68 attribute gives a list of locations of where to look for this
69 file; in our case we have simply chosen to put :file:`simple.xml`
70 in the same directory as :file:`simple.py`.
71
72 - The :class:`SimpleFormat.Example` class
73 provides the generated class with a function :meth:`addInteger` in
74 addition to the attributes :attr:`numIntegers` and
75 :attr:`integers` which have been created from the XML.
76
77 - Finally, the :mod:`pyffi.object_models.common` module implements
78 the most common basic types, such as integers, characters, and
79 floats. In the above example we have taken advantage of
80 :class:`pyffi.object_models.common.Int`, which defines a signed
81 32-bit integer, exactly the type we need.
82
83 Reading and Writing Files
84 ^^^^^^^^^^^^^^^^^^^^^^^^^
85
86 To read the contents of a file of the format described by
87 simple.xml:
88
89 .. literalinclude:: ../examples/simple/testread.py
90 :language: python
91
92 Or, to create a new file in this format:
93
94 .. literalinclude:: ../examples/simple/testwrite.py
95 :language: python
96
97 Further References
98 ^^^^^^^^^^^^^^^^^^
99
100 With the above simple example in mind, you may wish to browse through
101 the source code of :mod:`pyffi.formats.cgf` or
102 :mod:`pyffi.formats.nif` to see how pyffi works for more complex file
103 formats.
104 """
105