PsiFS: File Format Converters

The !PsiFS file is split into several sections, each terminated by a line containing <EOF> on its own. Within each section, lines of the form tag=value are used to associate a value with a tag. Any other lines are treated as comments which are ignored; no special prefix character is required.

Note that both case and spaces are significant. In particular, trailing spaces prevent recognition of the <EOF> token, so if problems are encountered it is worth checking that there are no invisible trailing spaces.

The tags currently associated with selecting file format converters are:

Tag	Description
Convert	Any conversion.
Convert_type	Any conversion of type file.
Convert_type_Standard	Stand-alone conversion of type file.
Convert_type_InterceptLoad	Loading a type file into receiver.
Convert_type_InterceptLoad_receiver
Convert_type_InterceptRun	Running a type file from sender.
Convert_type_InterceptRun_sender
Convert_type_InterceptSave	Saving a type file from sender to receiver.
Convert_type_InterceptSave_sender
Convert_type_InterceptSave_sender_receiver

In these tags type is the file type as a three digit upper-case hexadecimal number, sender is the name of the task sending the file, and receiver is the name of the task receiving the file. Both sender and receiver are the task names displayed by the Task Manager, but with any spaces or equals signs removed.

The value associated with each of these tags is the Tag of the file format converter to use, or blank if no conversion should be applied.

When a conversion is required, PsiFS uses these options to select the default file format converter, starting from the most specific matching option and continuing until a selectable file format converter is found. This behaviour is especially important if automatic conversions are enabled.

The following additional tags are associated with the options for the file format converters:

Tag	Description
ConvertOptions_Tag	The most recently used options.
ConvertOptions_Tag_Version	The Options value of the converter, used to detect changes and prevent use of incompatible options.

It should not be necessary to include these tags within the !PsiFS file; they are described here for completeness. It is more effective to set default options within the !PsiFSRes toolbox resource file.

Each time a conversion is performed, PsiFS automatically updates the appropriate defaults to ensure that the most suitable conversion and options are selected for successive operations.

See the individual characteristics defined below for details of the available options.

File type lists consist of a space separated list of RISC OS file types, specified in either numeric or textual form. The following special file types are also supported: Directory, Application and Untyped. However, although they are fully supported, it is recommended that these special file types are not used to trigger file transfer intercepts. An additional special file type of NoConversion is also supported for the Output tag to indicate that no output file will be produced; some other side-effect will occur instead.

The list of files to intercept only apply if enabled within the PsiFS configuration, and may be overridden by the user pressing Left Alt to force an intercept or Right Alt to prevent an intercept.

The Options value starts with the name of a toolbox template from the !PsiFSRes file, followed by a space separated list of "-keyword gadget" pairs. The -keyword is the option that will be substituted for the <opt> character sequence within the Convert string, and gadget consists of a single letter gadget type followed by the component ID of the gadget in hexadecimal. Note that the options are sorted before use; ordering is not preserved.

The behaviour of the converter if unable to handle the supplied file depends on whether the command specified by the Convert or ConvertSilent tag is used. In both cases the converter must exit without producing an output file. If the Convert was used then the converter should generate an error using either OS_GenerateError or Wimp_ReportError before exiting, but if the ConvertSilent was used then no error should be reported. Error messages should not be output via the VDU drivers (stdout/stderr for a C program); if necessary output should be redirected to a file and post-processed to convert any messages to RISC OS errors.

Future versions may support converters running in a TaskWindow; this will be controlled by additional tags specifying the capabilities of individual converters.