diff --git a/msi.html b/msi.html index 328e8f0f0..82c168791 100644 --- a/msi.html +++ b/msi.html @@ -1,103 +1,108 @@ - + - - + + - -

-msi: Macro Substitution and Include Tool

-Marty Kraimer -
Argonne National Laboratory - Advanced Photon Source -
Original:  April 26, 1999 -

-Introduction

-msi is a general purpose macro substitution/include tool. It accepts as -input an ascii template file. It looks for lines containing two reserved -command names: include and substitute. It also looks for and performs substitutions + +

msi: Macro Substitution and Include Tool

+Marty Kraimer
+Argonne National Laboratory - Advanced Photon Source
+Original:  April 26, 1999 + +

Introduction

+msi is a general purpose macro substitution/include tool. It accepts as input +an ascii template file. It looks for lines containing two reserved command +names: include and substitute. It also looks for and performs substitutions on macros of the form $(var) and ${var}. It uses the macLib, an epics base library created by William Lupton, to perform the substitutions. +

msi also allows substitutions to be specified via a separate substitution -file. This substitution file allows the same format as the substitution -files accepted by dbLoadTemplate or subtool. -
  -

-Command Syntax:

+file. This substitution file allows the same format as the substitution files +accepted by dbLoadTemplate or subtool.
+ 

+

Command Syntax:

msi -V -ofile -Idir -Msub -Ssubfile template
-NOTE: All parameters are optional and a space is optional between  --o, -I, -M, and -S  and the  associated value. Output is written -to stdout unless the -o option is given. -

Where: -

-V -

--o file - +NOTE: All parameters are optional and a space is optional between  -o, +-I, -M, and -S  and the  associated value. Output is written to +stdout unless the -o option is given. --I dir - - -
-    msi -I "/home/phoebus/MRK/examples:." -I".." template
- -
-specifies the search path:
- -
-    /home/phoebus/MRK/examples:.:..
- -
-M substitutions - - -
-    msi -M "a=aval,b=bval" -M"c=cval" template
- - +

Where:

+

-V

+-o file + +-I dir + +
+
    msi -I "/home/phoebus/MRK/examples:." -I".." + template
+
+
specifies the search path:
+
    /home/phoebus/MRK/examples:.:..
+
+-M substitutions + +
+
    msi -M "a=aval,b=bval" -M"c=cval" + template
+
+ + -S subfile - + template - + NOTE: It is not possible to display usage by just typing msi since executing the command with no arguments i s a valid command. To show usage specify an illegal switch, e.g. +
msi -help
-

-Template File Format

+

Template File Format

This file contains the text to be read and written to the output after macro -substitution is performed. If no file is given then input is read from -stdin. In addition the file can have lines containing include and substitute +substitution is performed. If no file is given then input is read from stdin. +In addition the file can have lines containing include and substitute commands. The format of these commands are: 
    include "file"
- 
    substitute "var=value,var=value,..."
For example let the command be: 
    msi template
and file includeFile contain: 
    first name is ${first}
     family name is ${family}
-and template is -
  +and template is
+  
    substitute "first=Marty,family=Kraimer"
     include "includeFile"
     substitute "first=Irma,family=Kraimer"
@@ -108,27 +113,26 @@ then the following is written to the output.
     first name is Irma
     family name is Kraimer
-

-Substitution File Format

+

Substitution File Format

The optional substitution file has three formats: regular, pattern, and -dbTemplate format. Lets discuss  each separately -
  -

-regular format

+dbTemplate format. Lets discuss  each separately
+  + +

regular format

-
{var1=value1,var2=value2,...}
+  
{var1=value1,var2=value2,...}
 {var1=value1,var2=value2,...}
 ...
-After reading each set of replacements within braces,   the template -file is read and macro substitution performed. -
  -

-pattern  format:

+After reading each set of replacements within braces,   the +template file is read and macro substitution performed.
+  + +

pattern  format:

-
pattern {var1,var2,...}
+  
pattern {var1,var2,...}
 {value1,value2,...}
 {value1,value2,...}
 pattern {var1,var2,...}
@@ -136,32 +140,31 @@ pattern {var1,var2,...}
 {value1,value2,...}
This is the same as the regular format: +
-
{var1=value1,var2=value2}
+  
{var1=value1,var2=value2}
 ...
-

-dbTemplate Format

+

dbTemplate Format

-
file template {
+  
file template {
     pattern format or regular format
 }

-
-
file template {
+  
file template {
     pattern format or regular format
 }
-For the template format, the command line template argument is optional. -If it specified it is used, otherwise the file template is used. This format -is an extension of the format accepted by dbLoadTemplate. It allows templates -to be  expanded on the host rather via dbLoadTemplate. -The file name may appear inside double quotation marks; these are only required -if the name contains any environment variable macros of the form ${MOTOR} which -will be expanded before the file is opened. -

-Regular substitution example

+For the template format, the command line template argument is optional. If +it specified it is used, otherwise the file template is used. This format is +an extension of the format accepted by dbLoadTemplate. It allows templates to +be  expanded on the host rather via dbLoadTemplate. The file name may +appear inside double quotation marks; these are only required if the name +contains any environment variable macros of the form ${MOTOR} which will be +expanded before the file is opened. + +

Regular substitution example

Let the command be: 
    msi -S substitute template
template is @@ -176,8 +179,7 @@ The following is written to the output.     first name is Irma     family name is Kraimer -

-Pattern substitution example

+

Pattern substitution example

Let the command be: 
    msi -S pattern template
pattern is @@ -185,21 +187,23 @@ Let the command be:     {Marty,Kraimer}     {Irma,Kraimer} template is the same as in the previous example. -

The following is written to the output. + +

The following is written to the output.

    first name is Marty
     family name is Kraimer
     first name is Irma
     family name is Kraimer
-

-dbTemplate example

+

dbTemplate example

Let the command be +
-
msi -S xxx.substitutions
+ 
msi -S xxx.substitutions
xxx.substitutions is +
-
file template {
+  
file template {
     pattern {first,last}
     {Marty,Kraimer}
     {Irma,Kraimer}
@@ -213,9 +217,11 @@ file template {
 }
template is the same as in the previous example.. -

The following is written to the output + +

The following is written to the output

+
-
first name is Marty
+  
first name is Marty
 family name is Kraimer
 first name is Irma
 family name is Kraimer
@@ -229,60 +235,61 @@ first name is Irma
 family name is Kraimer
-

-Some Details

+

Some Details

Building msi - - -
-Line length limits
- - + +
+
Line length limits
+
+ macLib - + template file syntax -