Automatic Loading of Import/Export Converters

In addition to the interfaces of (RefLink[Import, paclet:ref/Import]) and (RefLink[Export, paclet:ref/Export]), the Wolfram Language comes with an autoloading mechanism that simplifies the registration of formats used by the (RefLink[Import, paclet:ref/Import]) and (RefLink[Export, paclet:ref/Export]) framework.

Autoloading versus Manual Loading

Manual Loading

Examples of manually loading converters are given in the tutorials, where the commands to register "MyFormat1" are explicitly evaluated.

ImportExport`RegisterImport[
"MyFormat1",
MyFormat1`MyFormat1Import
]

MyFormat1`MyFormat1Import[filename_String, options___]:=
Module[{strm, head, data},
strm = OpenRead[filename];
head = ReadList[strm,"String",3];
data = Partition[ReadList[strm, "Number"], 4];
Close[strm];
{
"Header" -> head,
"Data" -> data
}
]

Autoloading

By placing both the format registration and the converter in appropriate locations, the Wolfram Language can automatically load the format registration. Autoloading of (RefLink[Import, paclet:ref/Import]) and (RefLink[Export, paclet:ref/Export]) converters can be achieved by following these steps:

(In the steps below, you can use (RefLink[$UserBaseDirectory, paclet:ref/$UserBaseDirectory]) or (RefLink[$BaseDirectory, paclet:ref/$BaseDirectory]).)

1. If the directory (RefLink[$UserBaseDirectory, paclet:ref/$UserBaseDirectory])/SystemFiles/Formats does not exist, create it.

2. Under (RefLink[$UserBaseDirectory, paclet:ref/$UserBaseDirectory])/SystemFiles/Formats, create a directory with the name format, where format is the name of the format to be autoloaded.

3. Inside the format directory, place the ImportExport`RegisterImport[] code block into a file named Import.m.

For example, in the directory (RefLink[$UserBaseDirectory, paclet:ref/$UserBaseDirectory])/SystemFiles/Formats/MyFormat1, the file Import.m would have the following content.

(* content of Import.m *)
ImportExport`RegisterImport[
"MyFormat1",
MyFormat1`MyFormat1Import
]

4. Inside the format directory, place the converter source code into a file named Converter.m.

For example, in the directory (RefLink[$UserBaseDirectory, paclet:ref/$UserBaseDirectory])/SystemFiles/Formats/MyFormat1, the file Converter.m would have the following content.

(* content of Converter.m *)
MyFormat1`MyFormat1Import[filename_String, options___]:=
Module[{strm, head, data},
strm = OpenRead[filename];
head = ReadList[strm,"String",3];
data = Partition[ReadList[strm, "Number"], 4];
Close[strm];
{
"Header" -> head,
"Data" -> data
}
]

5. With the files in place, when the Wolfram Language starts, (RefLink[$ImportFormats, paclet:ref/$ImportFormats]) will contain the entry "MyFormat1", and (RefLink[Import, paclet:ref/Import])[ file,{"MyFormat1","Header"}] will evaluate appropriately.

In fact, all formats supported by the Wolfram Language are registered using this autoloading mechanism, with the format registration residing in (RefLink[$InstallationDirectory, paclet:ref/$InstallationDirectory])/SystemFiles/Formats.

Furthermore, several formats in the Wolfram Language are made available in source form in the directory (RefLink[$InstallationDirectory, paclet:ref/$InstallationDirectory])/SystemFiles/Formats.

Details of the Registration Mechanism

Directory Name Must Match the Format Name

When using the autoloading mechanism, the folder name must match the format name. Formats can effectively be renamed by using format aliases below.

"Sources" Must Be Explicitly Given If Source Files Are Not in Standard Locations

When using the autoloading mechanism, the (RefLink[Import, paclet:ref/Import])/(RefLink[Export, paclet:ref/Export]) framework assumes the source file to be located in either (RefLink[$UserBaseDirectory, paclet:ref/$UserBaseDirectory])/SystemFiles/Formats/format/Converter.m or (RefLink[$BaseDirectory, paclet:ref/$BaseDirectory])/SystemFiles/Formats/format/Converter.m. If the source files are located elsewhere, it must be explicitly declared using the "Sources" option. For example, "Sources"->{"MyFormatConverter/Converter.m","MyFormatConverter/Converter2.m" }.

Resolving Conflicts

In case of conflicts (for example, the "MyFormat" directory residing in both (RefLink[$InstallationDirectory, paclet:ref/$InstallationDirectory])/SystemFiles/Formats and (RefLink[$UserBaseDirectory, paclet:ref/$UserBaseDirectory])/SystemFiles/Formats), the registration in (RefLink[$UserBaseDirectory, paclet:ref/$UserBaseDirectory]) has highest priority, followed by (RefLink[$BaseDirectory, paclet:ref/$BaseDirectory]) and (RefLink[$InstallationDirectory, paclet:ref/$InstallationDirectory]).

Defining Format Aliases

It is often useful to define format aliases so that you may refer to a format with several different names. Suppose you would like to use "MyOtherFormat" and "MyDefaultFormat" as aliases of "MyFormat1". You can do this by creating the file (RefLink[$UserBaseDirectory, paclet:ref/$UserBaseDirectory])/SystemFiles/Formats/FormatMappings.m with the following contents.

(* content of FormatMappings.m *)
{
"MyOtherFormat" -> "MyFormat1",
"MyDefaultFormat" -> "MyFormat1"
}

The aliases work the same as the original format:

Import["ExampleData/ExampleData.txt",{"MyOtherFormat","Data"}]

The original format returns the same information:

Import["ExampleData/ExampleData.txt",{"MyFormat1","Data"}]