gmplRefactorStatement

Owned by Mark Juras
Last updated: Jan 19, 2023
Table of Contents

Refactor Statement Summary

Refactor is a nonterminal, refactoring statement that occurs in command scripts, in reference scripts called RefactorLibraries, and in the GlobalSettings file within RefactorFile statements. The term "refactoring" generally refers to changing the implementation of user code when porting it to a new platform; while, the term "migration" refers to reformulating references to and replacing external libraries whose source code is not part of the source code being ported. Within actual portation projects, however, this distinction becomes blurred. Both terms are used throughout this discussion.


There are three places within a command scripts that a Refactor statement can occur. First, it can occur as a substatement of the Compile statement. It is applied after the compiler has built the symbol table but before it has processed any procedural code. This is a very effective place to strengthen the specifications of the symbols so that the compiler can take advantage of this additional information while generating the intermediate code. Second, it can occur directly in the command script after the Compile statement but before the Analyse statement. This is an excellent time to introduce target types explicitly and to do any removals. Third, it can occur directly in the command script after the Analyse statement but before the Author statement. This is the best time to do symbol renaming and code reauthoring.


A RefactorLibrary is a reference script initially authored by gmBasic from an IDL file for an external library that is being reformulated. To do the reformulation the actual declarations can be modified, but this can make those modifications difficult to track. There is a refactoring statement Migrate that is primarily intended to modify the properties of external components. The choice of using Migrate versus making modifications to declarations is entirely up to the user of gmBasic. Regardless of the choice made, reformulating external libraries always requires that additional information be added to the reference script describing the intended .NET side of the external and the transformation path needed to get there. This information as well, is supplied by a refactor statement added to the bottom of the original gmBasic authored file. The normal convention is to keep the original gmBasic file in the selected System location and to store the RefactorLibrary file in the selected target location. The refactoring statements within a RefactorLibrary are applied at the time the reference script is read and can, therefore, only be applied to the components of that library. If the user wishes to leave the gmBasic authored files alone, then another alternative is available. After a reference script is read, its filename is modified to be preceded by Mig. to form the name of a possible refactoring file which contains the Refactor statements modifying the characteristics of its components. If found, the statements in that file are treated as though they had been physically at the end of the original file. When these Mig files are used, the original file is left in the System location and the Mig file is placed in the Target location.


RefactorFile is a nonterminal registry type that is stored in the globalsettings storage area. The RefactorFile source attribute specifies the full pathname of the file whose symbols are to be refactored. The actual Refactor statements then form the target text buffer.


<Registry type="RefactorFile" source="Pathname of file to be refactored" >
   <Refactor>
      refactor statements
   </Refactor>
</Registry>
The registry is checked once for a RefactorFile entry for each class, module, form, or ASP file after the symbols for that file have been loaded but before the code has been compiled. There is nothing special about the refactor statements themselves. They behave exactly the same as Refactor statements placed within a Compile statement for a code project containing the specified file. Thus, the entry


   <Registry type="RefactorFile" source="\code\vb6\CommonFunctions.cls" >
     <Refactor>
       <FixType identifier="SortCollection.aObject" type="Interfaces.Icbn_Compare" />
    </Refactor>
  </Registry>
in a selected global settings file is identical to the following in a translation script


   <Compile project="\code\vb6\VariousCommonFunctions.vbp" >
      <Refactor fileFilter="[\code\vb6\CommonFunctions.cls]">
          <FixType identifier="SortCollection.aObject" type="Interfaces.Icbn_Compare" />
      </Refactor>
  </Compile>
There is no equivalent of the post-compiler refactoring statements, using RefactorFile. These can only be placed in command scripts.


A final distinction that is made within the Refactor statement is that of the hostid versus the filefilter. Refactor statements all identify the components in the symbol tree that they are referencing via qualified identifiers -- a series of identifiers separated by periods. To find the identified component the logic begins with a base symbol and then checks the first identifier to see if it is a child of that base. If so, that child becomes the new base and the next identifier is checked until all identifiers in the series have been processed. The final child found is the component being referenced. At issue here is the initial base symbol to be used. The Refactor introduces two potential base symbols -- the hostid which is the external library whose components are the primary focus of the migration and/or the filefilter which is the user code file whose components are being refactored. The various refactoring commands are either hostid oriented or filefilter oriented depending upon their primary use.


The attributes of the Refactor statement are as follows:


Attribute Description
DllNameThis attribute specifies the name of a dll file that should be loaded when the refactor statement is processed and should remain loaded for the remainder of the current gmBasic execution. Up to 64 Dlls may be loaded at the same time.
EventThis attribute is used to trigger a set of generic user migration code events within the analyser. These events are triggered first during the initialization phase and second during the code review phase for each code block in the current scope of the analyzer by references in the code to subcomponents that have a UserCode status flag set. The start of the string stored in the comment field of the component must match this attribute value to trigger the code events in the dll file.
IdThis attribute is the hostid. It is the identifier of the library or project being refactored. Libraries are identified via their local filename enclosed in square brackets like [mso.dll] or [msword9.olb] or [mscomctl.ocx] or [msado20.tlb]. In this context fully qualified names, whose identifiers are separated by periods can also be used. The brackets are used to avoid confusion.
ErrorStatusThis attribute controls the consequences of an error. If it is Ignore, then no message is displayed and the tool simply continues. If it is Warning, then a message is displayed and the and then to tool continues. If it is Error, then a message is displayed, and an abnormal exit to the operating system is taken. The default setting for this attribute is Error.
FileFilterThis attribute is the fully qualified identifier of the user code file whose components are being refactored. It specifies the filefilter for the following refactoring statements.

The declarations within the Class statement are as follows:


Substatement Description
FixtypeThis filefiler oriented statement changes the binary type of a component or group of components
CallByNameThis filefilter oriented statement changes symbol-related code events that yield CallByName late binding calls into direct boxed calls.
ImplementsThis filefilter oriented statement specifies that a VB6 class implements another class or interface.
RemoveThis filefilter oriented statement prevents a component from being authored.
MigrateThis hostid oriented statement specifies migration of a specific symbol within an external library.
RenameThis filefilter oriented statement changes the authored name of components.
ReauthorThis filefilter oriented statement replaces the content of a subprogram with a completely rewritten block of code
ExtendThis hostid oriented statement extends the content of a class by adding new components.
ReplaceThis hostid oriented statement replaces either members of an external class or the patterns of opcodes via replacement declarations.
MigclassThis hostid oriented statement defines a collection of related refactoring information used primarily to describe the components on the .NET side of the migration.
GmslThis command statement enters a gmSL subprogram that is needed in the authoring of the refactored code.
ReferenceThis command statement loads a reference script defining and external library whose components are being referenced within the refactoring block.

The script errors associated with the Refactor statement are as follows:


Error Description
1102Encountered illegal REFACTOR directive %1d




Table of Contents