PackageDescription: FileOut30

File Out 3 0

Last published: January 21, 2011 by 'nross'

Defines 19 Classes
Extends 37 Classes

This goodie provides the ability to load and save code in a variety of formats other than the standard VisualWorks XML and Chunk formats: VisualWorks 3.0 file-out format, Squeak format, VASmalltalk .st and .app format, Dolphin .pac format.

- File-in formats are automatically recognized; look at implementors and senders of #canFormatStream: to see the rules. To set a namespace from which to resolve unqualified names, choose it in the Default File-in Namespace tab in the VisualWorks settings.

- To set a file-out format, choose it in the Source tab in the VisualWorks settings.

The "VW3.0 non-Envy" setting will create file-outs compatible with VisualWorks 3.0. Note that if you save a parcel while this 3.0 File-Out option is set, that parcel will have its source also saved in VisualWorks 3.0 format. The "VW 3.0 Envy generic" setting differs only in method deletion (possible when change sets or package differences are filed-out); Envy-synching requires a different protocol in that case if the image is not to be left inconsistent with the database. File-in from either VW 3.0 ignores both protocols and uses standard chunk, resolving unqualified class names in the default file-in namespace. (The non-default VW 3.0 Envy setting
System genericFormat: true
should be used - but see remarks after "VASmalltalk" below).

The remaining formats are provided for compatibility with other dialects, are not fully supported, lack documentation, and quite possibly have problems in edge cases. These formats allow you to read or write package formats from some other dialects with as much information as possible preserved between them. For all of these formats there are some conventions observed.
- A prerequisite of the form Port will be transformed appropriately on file-in or file-out, where dialect is one of VW, VA, or Dolphin. So, for example, FooVWPort would become FooDolphinPort if filed out in Dolphin format.
- On file-in, at least some properties are preserved. The most notable example is ENVY prerequisites. On file-in of an ENVY application, any prerequisites whose names did not correspond to packages in the image are preserved in the envyPrerequisites variable and will be added back into the prerequisite list on file-out in ENVY format.
- Note that these formats do not ensure valid syntax in the target dialect. For example, an ENVY application cannot have whitespace in its name, and a hyphen in a Dolphin method category indicates a hierarchical category. The system will attempt to compensate for some of these known differences, but in general you are responsible for writing portable code.
- These have been tested primarily for reading/writing complete packages/applications. Use for code fragments (e.g. differences between packages) may or may not work properly.

Squeak format is a format roughly compatible with Squeak file-out format. Note that it doesn't attempt to handle dialect differences such as the conversion between underscore/left arrow and :=. This was contributed by Roel Wuyts.

VASmalltalk-compatible format is a format which can read and write VisualAge .app format files. This can file out a complete Store package into a VASmalltalk or VisualAge application. Namespace information will be removed, and as much package information as possible will be preserved. It is also possible to file out a complete bundle with this format and get a single file which can recreate all of the component packages as applications (note that this does not at the moment attempt to create configuration maps or version the resulting code). Smaller units - classes or methods - can also be filed-out. (This format has been tested against versions of VASmalltalk and VisualAge. It may also work with little or no modification for VisualWorks/ENVY code with the default
System genericFormat: false
setting. However file-outs from a VW3.0 Envy image with this setting are not recognised by this format's #canFormatStream: method at this time.)

Dolphin 4.0-compatible format is a format which is compatible with the .pac files of Dolphin Smalltalk. These files should be directly loadable into a Dolphin image as packages.

Because this package contains several #canFormatStream: implementations, some of which scan the whole file looking for a diagnostic expression, it must avoid having such a #canFormatStream: method for another dialect accidentally match its own source code. Having a safe order of presentation of SourceFileFormat subclasses in #formatForStream:, both in the overridden and the overriding implementations, is key to this.