Developing an Export Converter

The Wolfram Language provides functions that allow developers to implement file format converters to be integrated with the the Wolfram Language (RefLink[Import, paclet:ref/Import]) and (RefLink[Export, paclet:ref/Export]) framework. You can implement format converters and use (RefLink[Export, paclet:ref/Export]) to export data from customized formats.

The interface between (RefLink[Export, paclet:ref/Export]) and low-level converter functions is specified by RegisterExport (under the ImportExport` context). In essence, RegisterExport tells the (RefLink[Import, paclet:ref/Import]) and (RefLink[Export, paclet:ref/Export]) framework how to make various function calls when exporting Wolfram Language expressions to a file format.

The Wolfram Language also includes source code for various converters. These are placed in the folders (RefLink[$InstallationDirectory, paclet:ref/$InstallationDirectory])/SystemFiles/Formats/format, where format is one of the following: (StringTypeLink[BDF, paclet:ref/format/BDF]), (StringTypeLink[DIF, paclet:ref/format/DIF]), (StringTypeLink[MTP, paclet:ref/format/MTP]), (StringTypeLink[SMILES, paclet:ref/format/SMILES]), (StringTypeLink[SurferGrid, paclet:ref/format/SurferGrid]), (StringTypeLink[TGF, paclet:ref/format/TGF]), or (StringTypeLink[TLE, paclet:ref/format/TLE]). The registration code can be found in the files Import.m and/or Export.m, and the converter sources reside in the files Converter.m.

Format Registration

An (RefLink[Export, paclet:ref/Export]) format must first be registered. Note that, unlike registering an (RefLink[Import, paclet:ref/Import]) format, RegisterExport accepts only one function.

Writing a Converter Function

For this example, imagine a file format that encodes an ASCII string by each character's ASCII code, with each code separated by a single space. A converter function for this format can be added to the (RefLink[Import, paclet:ref/Import]) and (RefLink[Export, paclet:ref/Export]) framework using RegisterExport.

ImportExport`RegisterExport["MyExportFormat", MyExportFormat`Exporter ]

When you use (RefLink[Export, paclet:ref/Export])[file.ext,"str","MyExportFormat"], the framework passes both the output file name and the data, str, to the exporter, so an example exporter function can be written as below.

MyExportFormat`Exporter[filename_, data_, opts___]:=
Module[{char, strm},
(* TODO: check for valid data here *)
char = ToCharacterCode[data];
char = Riffle[char, " "];
strm = OpenWrite[filename];
WriteString[strm, Sequence@@char];
Close[strm]
]

"MyExportFormat" can now be used in (RefLink[Export, paclet:ref/Export]) just like any other file format.

Export["sample.txt","Encode this string!", "MyExportFormat"];
FilePrint["sample.txt"]

Elements and Options for Converter Functions

Unlike (RefLink[Import, paclet:ref/Import]), which always imports elements, (RefLink[Export, paclet:ref/Export]) can directly export an expression (as in the example above) or a list of rules in the form of elementName->elementValue.

Elements can be designated as options, meaning that they will always be passed to the converter functions along with all other options. Here is a trivial converter to illustrate the handling of elements and options.

ImportExport`RegisterExport["ExportDemo", ExportDemo`func, "Options" -> {"opt1", "opt2"}]

ExportDemo`func[filename_, data_, opts___]:=
(Print["data: ", data,"\topts: ", Flatten[{opts}] ])

Export directly with expressions:

Export["file1",5,"ExportDemo"];

Export["file1",5,"ExportDemo","OpName" -> "OpVal"];

Export via elements:

Export["file1",{"E1"-> 1,"E2":> 2},{"ExportDemo","Rules"}];

Export["file1",{ 1, 2,3},{"ExportDemo",{"E1","E2","E3"}}];

Export via elements, with options:

Export["file1",{"E1"-> 1,"E2"-> 2},{"ExportDemo","Rules"},"opt3"-> 3];

Export["file1",{"E1"-> 1,"E2"-> 2},{"ExportDemo","Rules"},"opt3"-> 3,"opt4" -> 4];

Export via elements, with elements registered as options:

Export["file1",{"E1"-> 1,"opt2"-> 2},{"ExportDemo","Rules"},"opt3"-> 3];

Export["file1",{1,2},{"ExportDemo",{"E1","opt2"}},"opt3"-> 3,"opt4" -> 4];

Note that by specifying "Options"->{"opt1","opt2"}, the elements "opt1" and "opt2" are automatically passed as options to the exporters.