More about script arguments.
In this section we will discuss several more details about script arguments.
First of all we would like to mention method
ShowUsage() of the
WScript.Arguments object.
This method makes a script self-documenting by displaying information about how it should be used. This method
takes no arguments and prints information about the correct usage of the script.
When you run the ShowUsage method, a help screen (referred to as the usage) appears and displays
details about the script's command line options. This information comes from the runtime section of the *.WSF
file. Everything written between the <runtime> and </runtime> tags is pieced
together to produce what is called a "usage statement." The usage statement tells the user how to use the script.
The general syntax of the <runtime> section is:
<runtime>
<description>Description text</description>
<named attributes />
<unnamed attributes />
<example>Example Text</example>
...
</runtime>
where
- description element marks the descriptive text that is displayed when the ShowUsage
method is executed or when the script is run with the /? command line switch.
- named element describes a named argument for the script. This element has the following syntax
<named
name = namedname
helpstring = helpstring
type = "string|boolean|simple"
required = "true|false"
/>
where
- name is a string that represents the name of the argument you are describing. Defines the
argument at the command line and in the script.
- helpstring is a string that represents the help description for the argument. The WSH runtime
provides the help description using the ShowUsage method or the /? argument.
- type is an optional argument that describes the type of argument, which defines how the argument
will be parsed from the command line. The default value is simple.
If the type is string, the argument is a string. The argument is passed to the script as
/named:stringvalue.
If the type is Boolean, the argument is Boolean. The argument is passed to the script as /named+
to turn it on, or /named- to turn it off.
If the type is simple, the argument takes no additional value and is passed as just the name,
/named.
- required is another optional argument. This argument is a Boolean value that indicates whether
an argument is required or not. Affects the display of the usage only.
- unnamed element describes an unnamed argument for the script. The syntax of this argument is
<unnamed
name = unnamedname
helpstring = helpstring
many = boolean
required = boolean or integer
/>
where
- name is the string that is used in the usage to represent this argument. This value is not used
elsewhere.
- helpstring is a string that represents the help description for the argument. The WSH runtime
provides the help description using the ShowUsage method or the /? argument.
- many is an optional boolean argument. If true, then this argument may be repeated more times
than specified by the required attribute. Otherwise, the required attribute represents the exact number of
the argument that is required.
- required is another optional argument. An integer value indicating how many times this argument
should appear in the command line.
- example element provides an example of usage for the job.
The example below shows how to create a runtime section for a script that requires one named argument
usage and three unnamed arguments (files) and also may take one optional named argument logo.
<runtime>
<description>
This is a small example that illustrates how the ShowUsage() method works.
</description>
<named
name = "usage"
helpstring = "Please don't show the usage"
type = "string"
required = "true"
/>
<named
name = "logo"
helpstring = "Display or not the logo"
type = "bolean"
required = "false"
/>
<unnamed
name = "outfile"
helpstring = "output file"
type = "string"
required = "true"
/>
<unnamed
name = "file"
helpstring = "file to search into"
type = "string"
required = 2
/>
<example>Example: usage.wsf test.log /usage:none /logo+</example>
</runtime>
Now, when we know how to pass named and unnamed arguments to a script, we need to know how to get information about
all script arguments inside the script. We have talked about the Arguments property if the
WScript object. We mentioned that this property is an instance of the WshArguments object.
This object itself has two properties that help us to retrieve all named and unnamed parameters. These properties are:
- Named that returns a collection of named arguments. This property has property length,
method Item(), and method Exists(). Both of the methods take a string that contains
an parameter name as an argument. Method Item returns the value of the parameter, and method Exists()
returns a boolean value indicating whether the parameter present or not.
- Unnamed that returns a collection of unnamed arguments. This object contains property
length and method Item().
The following example show how to access all unnamed arguments of a script and some named arguments:
var args = WScript.Arguments;
var unnamed = args.Unnamed;
var str = "\n------------------------\nUnnamed arguments:\n";
for(i=0;i<unnamed.length;i++)
str += unnamed.Item(i) + "\n";
str += "\n------------------------\nNamed arguments:\n";
str += "logo = " + args.Named.Item("logo") + "\n";
str += "usage = " + args.Named("usage") + "\n";
WScript.Echo(str);
Assignment: please combine these two examples together in one .wsf file and check ho wit works.
Once you are done with this you can take a look at the complete example
here.
References