Edit File Type

This window is reachable from the File Types options page. Use it to edit the file patterns that determine which type of comparison window to use to compare files.

Type

This field shows the type of comparison that should be opened for files whose name matches the pattern in the Pattern field. The available types are shown in the table below.

TypeDescription
TextA text comparison.
BinaryA binary comparison.
ImageAn image comparison.
Text XML/XHTMLA text comparison for XML and XHTML files where the files are reformatted when first loaded to enable them to be compared more easily. For more information, see Comparing Text Files (or Typed/Pasted Text).
Text with numeric dataA text comparison that compares numeric values within text. For more information, see Comparing Text Files (or Typed/Pasted Text).
Text Intel HexA text comparison with special handling for Intel Hex files. For more information, see see Comparing Text Files (or Typed/Pasted Text).

Pattern

Enter one or more semicolon-separated patterns that match the names of files that should be compared using the comparison type shown above. For example, you could use *.bmp;*.gif;*.jpg;*.png to match image files.

Filter program

Enter an optional filter program to be used to filter file content when files matching the Pattern are opened or saved. Filter programs enable Merge to compare the contents of files in formats that it would otherwise not understand.

The table below lists the various possible ways in which a filter program can be implemented. It also describes what should be provided in the Filter program field in each case.

Filter implementation Field value
Binary executable Path to executable
Script Path to script
DLL exporting function Path to DLL
DLL providing an in-process COM object Object CLSID

Binary executable, script, or DLL filters located in the Araxis Merge installation folder’s Filters subfolder do not require a fully-qualified path. User-provided binary executables, scripts, or DLLs can either be copied into that folder or located elsewhere. In the latter case, a fully-qualified path to the filter program should be entered into this field.

Implementing binary executable or script filters

When a binary executable or script is defined as the filter program, that program is run with an option flag and three filename arguments:

  • The option flag will be either -f or -r to indicate that a forward (when reading a file) or reverse (when writing to a file) transformation is required.
  • The first filename argument specifies the path of a file containing the data to be transformed by the filter program.
  • The second filename argument specifies a file into which the transformed data should be written.
  • The third filename argument specifies a file containing keys and values describing the transformation being performed. Comments within the file describe the data contained therein.

If the filter executable or script is unable to operate on the input file provided by Merge (if reverse transformations are not supported, for example), it should write an error message to standard error and return a non-zero exit code.

Merge may run multiple instances of the binary executable or script simultaneously. Filter programs must therefore be written accordingly.

Implementing DLL-based filters (deprecated)

Information Support for DLL-based filters is deprecated and may eventually be removed from Araxis Merge.

DLL-based filters can be written either as in-process COM objects or as DLLs that export a specific named function.

Information An example implementation of both types of DLL-based filter can be found in the AutomationSamples/Cpp/win32/ROT13Filter subfolder within the Araxis Merge installation folder.

Both types of DLL-based filter accept an object that implements the ITransformFilterInformation interface. This object’s properties are intended to provide the same information as the filter options that binary executable and script filter programs are given, as described above.

For languages that prefer to import a COM type library, merge.tlb can be imported from the Araxis Merge installation folder. For C/C++, a merge.h header file can be found in the AutomationSamples/Cpp/Idl subfolder within the Araxis Merge installation folder.

COM-object filters

COM-object filters should implement the ITransformFilter interface.

If the object is unable to operate on the input file provided by Merge, it should return an HRESULT indicating the error. Additional error information, including a message to be provided to the user, may be provided using the standard COM IErrorInfo mechanism. If an error message is not provided, Merge will create one based on the returned error code.

Each instance of the filter object will be used only by a single thread. The DLL must nevertheless support multiple concurrent instances and threads, since it is possible that Merge may have many threads simultaneously creating and using instances of the object. Apartment-threaded or free-threaded models are recommended.

Exported-function filters

If a filter is to be provided by exporting a function from the DLL, that function should have the following signature:

EXTERN_C STDAPI Transform(ITransformFilterInformation* information, BSTR* error)

If the function is unable to operate on the input file provided by Merge, it should return an HRESULT indicating the error. An additional error message to be shown to the user may be provided using the BSTR* error output parameter. If an error message is not provided, Merge will create one based on the returned error code.

The exported function may be called by multiple Merge threads simultaneously. It must therefore be fully re-entrant.