<!--
ScriptRule FileOverview
Syntax
    AThe ScriptRule.xml file defines isnamed collections anof XMLscript documentcommands that
may contain one ormay morebe ScriptRuleconditionally merged with the template translation elements.script creating These
elements and their attributesdifferent areactual describedtranslation belowscripts. This <ScriptRule id="name" Condition="condition" > elementsmakes it possible, with one 
   ScriptRuletemplate, elementsto containautomate nameda scriptvariety commandof collectionscommon and task-specific upgrade options.

  The idScriptRule attributefiles isare thealso nameneeded offor theAPI-based ScriptRuleupgrade andtasks. is alsoThese used
   tasks inuse youran translationEXE scriptimplemented tousing activategmAPI therather rule.than a XML script template. The Condition
 attribute is usedThe togmAPI controlframework whichincludes rulesa areScriptRule mergedclass intoproviding services to 
 to the actualintegrate translationScriptRule script.file content <Command Condition="condition"> elements

   Command elements are children of a ScriptRule that specify the content
   that should be merged into the translation script template.  The following 
   types of Command elements are currently supported:

   Option       Inserts commands that replace the <ScriptRule> tag in the 
                merged transcript, typically Select, Reference, and Registry commands.
             
   Compile      Inserts commands as children of the Compile block. Typically
                Select, Reference, Fix, and Refactor commands.
             
   Analyse      Inserts commands as children of the Analyse block
   PreAnalyse   Inserts commands before the Analyse block, typically refactor commands
   PostAnalyse  Inserts commands after the Analyse block, typically refactor commands
   
   Authorwith other gmAPI services.

ScriptRule File Syntax

   A ScriptRule file is an XML document that may contain one or more ScriptRule 
   elements.  These elements and their attributes are described below.

<ScriptRule id="name" Condition="condition" > elements

   ScriptRule elements contain named script command collections
   
   The id attribute is the name of the ScriptRule and is also used 
   in your translation script to activate the rule.

   The Condition attribute is used to control which rules are merged into 
   to the actual translation script.

<Command Condition="condition"> elements

   Command elements are children of a ScriptRule that specify the content
   that should be merged into the translation script template.  The following 
   types of Command elements are currently supported:

   Option       Inserts commands that replace the <ScriptRule> tag in the 
                merged transcript, typically Select, Reference, and Registry commands.
        Inserts commands as children of the
Author block, typically FixLoad commands     PostAuthor   InsertsInsert commands as children afterof the AuthorLoad block,. typicallyTypically topFixcommands.
level gmPL commands 
   TheCompile Condition attribute is used to control whichInserts commands areas mergedchildren intoof the Compile block. Typically
to the actual translation script.          Condition attributes Select, Reference, Fix, and ARefactor Conditioncommands.
attribute may be applied to any other element. It specifies the   
 condition under whichAnalyse the element and its children willInserts becommands mergedas withchildren of the Analyse block
  template scriptPreAnalyse to create theInserts actualcommands script.before the Analyse block, typically Syntaxrefactor commands
   PostAnalyse  Inserts commands after the Analyse block, typically refactor commands
%variable_expression% op 'value_expression' 
   Author   where    Inserts commands as children of variable_expressionthe Author block, alltypically scriptFix variablescommands
and
other characters  PostAuthor   Inserts opcommands after the Author block, typically top level gmPL commands

   The Condition attribute is used to ==control truewhich ifcommands %variable_expression% == value_expressionare merged into 
   to the actual translation script.

Condition attributes

   A Condition attribute may be applied to any other !=element. trueIt ifspecifies %variable_expression%the !=
value_expression   condition under which the element and its children will be merged with the 
   template script to create the actual =~script.
true
if %variable_expression% matches regexSyntax value_expression               %variable_expression% op 'value_expression'
   
   where !~
true if %variable_expression% does
not match regex valuevariable_expression   all script variables and other characters 
   op                 value_expression   == true if a constant string or regex pattern%variable_expression% == value_expression
          Comparisons are case insensitive using trimmed strings.         != true if %variable_expression% != value_expression
               Relational    operators are not supported, but you can=~ usetrue if %variable_expression% matches regex value_expression
 Condition="var1.var2=='val1.val2'" to simulate locical AND       Condition="var=~'val1|val2'"       to simulate logical OR   !~ true Forif example%variable_expression%  Condition="%SrcName%=='ScanToolUI'" indicates that the associateddoes not match regex value_expression
                  element will only be merged for upgrade tasks
having SrcName equal value_expression      a constant string or regex pattern
   
to the string "ScanToolUI".Comparisons are case insensitive using trimmed strings.
          <ForEach>, <Iterator>, and <Each> elements     ForEach elements are children of the ScriptRule.
They allow repeating Relational operators are not Commandsupported, elementsbut foryou eachcan fileuse
in the source project folder that meet 
   certain criteria.  This element may also be used to copy files
   from the source project folder to the .NET project folder.
  Condition="var1.var2=='val1.val2'" to simulate locical AND
      Condition="var=~'val1|val2'"       to simulate logical OR

   For example  Condition="%SrcName%=='ScanToolUI'" indicates that the associated 
    The set of files to iterate over is defined by a <Iterator/FileInfo> element will only be merged for accordingupgrade totasks itshaving attributes:SrcName equal
        The FileInfo Criteria attribute is a search pattern (e.g. *.wav) used to to the string "ScanToolUI".
      get files from the source folder.    
<ForEach>, <Iterator>, and <Each> elements
The
FileInfo Files attribute mayForEach beelements "All"are or "Top".  The default is "All".children of the ScriptRule. They allow repeating 
   Command If Files="All", the root of the sourceelements for each file in a specified folder andthat allmeets of
its sub-folders are certain criteria.  This searched;element if Files="Top", only the root ofmay also be used to copy files
   from the sourcespecified folder is searchedto the .NET project folder.
   
   The CopyFilesset attributeof mayfiles beto "On"iterate or "Off".  The default is "On". Ifover is defined by a <Iterator/FileInfo> element 
    CopyFiles="on", the files found in the source project folder will be copied
   to the corresponding .NET project folder with directory structure preserved.
   The folders and files are copied prior to the translation process.
   
   Within the <Each> block, the notation %FileInfo.member% may be used to refer 
   to information about the files found in the source folder:

   %FileInfo.RelativeName%: path relative to the source project root
   %FileInfo.Name%: file name
   %FileInfo.FullName%: full path
   %FileInfo.DirectoryName%: parent folder name

Activating a ScriptRule

   Adding a <ScriptRule> tag to the script requests the merging of the named
   script collection.

   <ScriptRule id="name" attributeList />according to its attributes:  
   
   The FileInfo@Criteria attribute is a search pattern (e.g. *.wav) used to 
   get files from the source folder.  
   
   The FileInfo@Folder attribute specifies the folder to search for files.
   The default is the source folder associated with the upgrade task.
   %SrcFolder%, %UserFolder%, and %ProjFolder% script variables may also be used.

   The FileInfo@Recurse attribute may be "All" or "Top".  The default is "All".  
   If Files="All", the root of the source folder and all of its sub-folders are 
   searched; if Files="Top", only the root of the source folder is searched.
   
   The idFileInfo@CopyFiles attribute specifiesmay thebe command"On" collection to add.

 or "Off".  The attributeListdefault specifies variables that may be referenced elsewhere 
  is "On". If 
   CopyFiles="on", the files found in the ScriptRule.source Variableproject referencesfolder arewill casebe insensitive.copied
   to  For example the followingcorresponding ScriptRule.NET tag:project folder with directory structure preserved.
<ScriptRule id="IncludeResources" Criteria="*.wav" /> 

   requests loading the command collection named IncludeResouces and 
   creates a ScriptRule variable named %Criteria% with value = "*.wav"
   
Specifying the ScriptRule file

   By default, the ScriptRule XML is located in a file called ScriptRule.xml 
   and is typically kept in the workspace\usr folder.
   
   If desired, you may specify an alternate location using a FileName attribute The folders and files are copied prior to the translation process.
   
   Within the <Each> block, the notation %FileInfo.member% may be used to refer 
   to information about the files found in the source folder:

   %FileInfo.RelativeName%: path relative to the source project root
   %FileInfo.Name%: file name
   %FileInfo.FullName%: full path
   %FileInfo.DirectoryName%: parent folder name

Activating a ScriptRule

   Adding a <ScriptRule> tag to the script requests the merging of the named
   script collection.

   <ScriptRule id="name" attributeList /> 

   The id attribute specifies the command collection to add.

   The attributeList specifies variables that may be referenced elsewhere 
   in the ScriptRule. Variable references are case insensitive. 

   For example the following ScriptRule tag: 

   <ScriptRule id="IncludeResources" Criteria="*.wav" /> 

   requests loading the command collection named IncludeResouces and 
   creates a ScriptRule variable named %Criteria% with value = "*.wav"
   
Specifying the ScriptRule file

   By default, the ScriptRule XML is located in a file called ScriptRule.xml 
   and is typically kept in the workspace\usr folder.
   
   If desired, you may specify an alternate location using a FileName attribute
   for example:
   
   <ScriptRule id="ADODBUpgrade" FileName="..\usr\ADODB.Rules.xml" /> 
   
   The above loads the ScriptRule file named ..\usr\ADODB.Rules.xml 
   (relative to the workspace log folder).  And then merges in the 
   ScriptRule element having id="ADODBUpgrade":
   
   <ScriptRule id="ADODBUpgrade" Condition="%TaskTag%=='upg'" >
   ... rules to perform ADODBUpgrade for tasks having TaskTag=='upg' ...
   </ScriptRule>

Line Pragma

   The token %LN% placed in a ScriptRule file will expand to the form
   
   @ScriptRulePath@LineNumber@ in actual script.  The expanded form may then
   be parsed by gmStudio to direct the text editor to that line of code.
   
   For example:
   
   <Replace status="active" name="%LN% Add Reference to dlls: gmRTL.Core and gmRTL.WPF" lang="vbp">
   becomes
   <Replace status="active" name="=@C:\gmTestBed\WPFScanTool\proj_csh\usr\ScriptRules_csh.xml@105@ Add Reference to dlls: gmRTL.Core and gmRTL.WPF" lang="vbp">
   
   This data will be placed into the Translation Log.  If the log is viewed as a Grid in gmStudio, double clicking the grid line
   will take you to the original line in the Script Rule file.
   
   
See Also:

   For more information, see the "Eval" VB6 Upgrade sample here 
   https://portal.greatmigrations.com/display/GMG/Samples
-->
<ScriptRules>
<!-- Here is a sample of the ScriptRule syntax -->
<ScriptRule id="BasicRulesStandardUpgrade">
   <Option>
      <!-- directories for configuration files -->

      <select Target="%UserFolder%" />
      <Select Local="%IdfFromCodeFolder%" />
      <Select System="%IdfFromIdlFolder%" />

      <!-- translation options -->

      <Select Progress="1" />
      <Select DevEnv="%DevEnv%" />
      <Select Dialect="%Dialect%" />
      <Select BuildFile="local" />

      <!-- directories for deployment and external assemblies -->

      <select VirtualRoot="%VirtualRoot%" />
      <Select DeployLocation="%NetProjFolder%" />
      <Select Library="%RuntimeFolder%" />

      <!-- custom processing commands -->

   </Option>
   <Compile Condition="%SrcName%=~'Project1|Project2'" >
      <!-- pre-edits -->
      <!-- compile refactors commands-->
   </Compile>
   <PreAnalyse>
      <!-- pre-analyse refactor commands -->
   </PreAnalyse>
   <PostAnalyse>
      <!-- post-analyse refactors commands-->
   </PostAnalyse>
   <Author Condition="%SrcName%=~'Project1|Project2'" >
      <!-- post-edits -->          
   </Author>
   <PostAuthor>
      <!-- post-author refactors commands-->
   </PostAuthor>
</ScriptRule>
</ScriptRules>
</ScriptRules>