<!--
ScriptRule Overview

   The ScriptRule.xml file defines named collections of script commands that
   may be conditionally merged with the template translation script creating 
   different actual translation scripts. This makes it possible, with one 
   template, to automate a variety of common and task-specific upgrade options.

   ScriptRule files are also needed for API-based upgrade tasks.  These 
   tasks use an EXE implemented using gmAPI rather than a XML script template.  
   The gmAPI framework includes a ScriptRule class providing services to 
   integrate ScriptRule file content with 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.
             
   Load         Insert commands as children of the Load block. Typically Fixcommands.
   
   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
   
   Author       Inserts commands as children of the Author block, typically Fix commands

   PostAuthor   Inserts commands after the Author block, typically top level gmPL commands

   The Condition attribute is used to control which rulescommands 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:

   OptionCondition attributes

   A Condition attribute may be applied to any other element. It specifies the 
   condition under which the element and its children will be merged with the 
   template script to create the actual script.

   Syntax             Inserts commands that replace%variable_expression% the <ScriptRule> tag in theop 'value_expression'
   
   where 
   
   variable_expression merged transcript, typicallyall Select,script Reference,variables and Registryother commands.characters 
   op             Compile      Inserts commands== astrue childrenif of the Compile block. Typically
   %variable_expression% == value_expression
            Select, Reference, Fix, and Refactor commands.        != true if %variable_expression% != value_expression
    Analyse      Inserts commands as children of the Analyse block    PreAnalyse   Inserts commands=~ beforetrue theif Analyse block, typically refactor commands%variable_expression% matches regex value_expression
    PostAnalyse  Inserts commands after the Analyse block, typically refactor commands        Author   !~ true if %variable_expression% Insertsdoes commandsnot asmatch childrenregex ofvalue_expression
the Author block, typically Fix commands     PostAuthor   Inserts commands after the Author block, typically top level gmPL commands  
  The Conditionvalue_expression attribute is used to control whicha commandsconstant arestring mergedor intoregex pattern
   to
the actual translation script.Comparisons are case insensitive using trimmed strings.
   Condition attributes     A Condition attribute may be applied to any other element. It specifies the    
condition under which theRelational elementoperators andare itsnot childrensupported, willbut beyou mergedcan withuse
the     template script to create the actual script. Condition="var1.var2=='val1.val2'" to simulate locical AND
      SyntaxCondition="var=~'val1|val2'"       to simulate logical OR

   For %variable_expression%example op 'value_expression'
   Condition="%SrcName%=='ScanToolUI'" indicates that the associated 
  where         variable_expression   all script variableselement andwill otheronly charactersbe merged for upgrade tasks having opSrcName equal
                to the == true if %variable_expression% == value_expressionstring "ScanToolUI".
               
<ForEach>, <Iterator>, and <Each> elements

   ForEach elements are !=children trueof if %variable_expression% != value_expression
the ScriptRule. They allow repeating 
   Command elements for each file in a specified folder that meets 
   certain criteria.  This element =~may truealso ifbe %variable_expression%used matchesto regexcopy value_expressionfiles
   from the specified folder to the .NET project folder.
   
   The set of files to iterate !~over trueis ifdefined %variable_expression%by doesa not<Iterator/FileInfo> matchelement regex
value_expression   according to its attributes:  
   
   The FileInfo@Criteria attribute is a search pattern (e.g. *.wav) used to 
  value_expression get files from the source afolder. constant string
or regex pattern 
   The FileInfo@Folder attribute Comparisonsspecifies arethe casefolder insensitiveto usingsearch trimmedfor stringsfiles.
   The default is the source folder associated with the        upgrade task.
   %SrcFolder%, %UserFolder%, and %ProjFolder% script variables Relationalmay operatorsalso arebe notused.
supported,
but you can useThe FileInfo@Recurse attribute may be "All" or Condition="Top"var1.var2=='val1.val2'" to simulate locical AND.  The default is "All".  
   If  ConditionFiles="var=~'val1|val2'"       to simulate logical OR
All", the root of the source folder and all of its sub-folders are 
  For examplesearched; if ConditionFiles="%SrcName%=='ScanToolUI'" indicates thatTop", only the root of the associatedsource folder is searched.
   
   The FileInfo@CopyFiles attribute may be "On" or element"Off". will onlyThe bedefault merged for upgrade tasks having SrcName equal
            is "On". If 
   CopyFiles="on", the files found in the source project folder will be copied
   to the stringcorresponding "ScanToolUI".NET project folder with directory structure preserved.
   The folders and files are copied prior to <ForEach>,the <Iterator>,translation andprocess.
<Each> elements  
  ForEach elementsWithin arethe children<Each> ofblock, the notation ScriptRule. They allow repeating%FileInfo.member% may be used to refer 
   to Commandinformation elementsabout forthe eachfiles filefound in the source project folder:
that
meet     certain criteria.  This element may also be used to copy files
   from %FileInfo.RelativeName%: path relative to the source project folderroot
to the .NET project folder%FileInfo.Name%: file name
   %FileInfo.FullName%: full Thepath
set of files to iterate over is defined by a <Iterator/FileInfo> element 
   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 Files attribute may be "All" or "Top".  The default is "All"%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. 

   If Files="All",For example the following rootScriptRule oftag: the
source
folder and all of its sub-folders are<ScriptRule id="IncludeResources" Criteria="*.wav" /> 

  searched; if Files="Top", only requests loading the rootcommand ofcollection thenamed sourceIncludeResouces folderand is
searched.   creates a ScriptRule variable named The%Criteria% CopyFileswith attributevalue may= be "On*.wav"
 or "Off". 
TheSpecifying defaultthe is "On". IfScriptRule file

   By CopyFiles="on"default, the ScriptRule XML filesis foundlocated 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 /> 

   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.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 the:
following ScriptRule tag:  
   <ScriptRule<Replace idstatus="IncludeResourcesactive" Criterianame="*.wav" /> 

   requests loading the command collection named IncludeResouces and 
   creates a ScriptRule variable named %Criteria% with value = "*.wav"
   
Specifying the ScriptRule file%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">
   
By default, the ScriptRuleThis XMLdata iswill locatedbe inplaced ainto filethe calledTranslation ScriptRuleLog.xml  If the log is andviewed isas typicallya keptGrid in gmStudio, double clicking the workspace\usr folder.grid line
   will take you to Ifthe desired,original youline mayin specifythe anScript alternateRule locationfile.
using a FileName attribute
   
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>