= HOWTO: Powershell - Pass Command Line Arguments Between Scripts =
Jan 22 2016

[[Image(htdocs:images/powershell/PowerShell_5.0_icon.png, alt="PowerShell_5.0_icon", align=center)]]

=== Scenario ===

I have to invoke different sets of scripts conditionally for setting up the build environment based on which project(s) I want to build. This is related to porting my build environment scripts from bash to Powershell.

Let's say, `push0.ps1` is the main script and there are three other scripts, viz. `quake.push0.ps1`, `doom.push0.ps1` and `wolf.push0.ps1`. I want to invoke `push0.ps1` with some arguments from the command line and have `push0.ps1` invoke one of the `*.push0.ps1` scripts while passing all the command line arguments that `push0.ps1` was invoked with.

A bit of code would help make the example concrete:
{{{#!html
<pre><strong>push0.ps1</strong>
<span style="color: #008000;"># $args is the array of input arguments to any script
# Do some work here common to all projects</span>
<span style="color: #008000;"># like pushing code to the master repo for developer scripts, etc.</span>

<span style="color: #008000;"># invoke project specific scripts here
# $Env:Project will be set to quake, doom or wolf</span>
<span style="color: #008000;"># call project specific push0 script if it exists </span>
<span style="color: #008000;"># and pass all arguments to it</span>
$scriptName = $Env:Project + ".push0.ps1"
if (Test-Path $scriptName) {
    &amp; $scriptName $args
}</pre>
}}}

----

{{{#!html
<pre><strong>quake.push0.ps1</strong>
<span style="color: #008000;"># do quake specific work here
</span>$pushFolder = Join-Path $Env:QuakeBaseDir "win32"
cd $pushFolder
hg push

$winSpecificFolder = Join-Path $pushFolder $Env:QuakeWinSubDir
cd $winSpecificFolder
hg push

<span style="color: #008000;"># now push any external sub-repos
</span>$quakeExtBaseDir = Join-Path $Env:ExtBaseDir $QuakeExtWin32SubDir
$args | % {
    $extFolder = Join-Path $quakeExtBaseDir $_
    cd $extFolder
    hg push
}
</pre>
}}}

----

{{{#!html
<pre><strong>doom.push0.ps1</strong>
<span style="color: #008000;"># do doom specific work here
</span>$pushFolder = Join-Path $Env:DoomBaseDir "win16"
cd $pushFolder
hg push

$win16SpecificFolder = Join-Path $pushFolder $Env:DoomWin16SubDir
cd $win16SpecificFolder
hg push

<span style="color: #008000;"># now push assembly language library repos
</span>$doomAsmBaseDir = Join-Path $Env:AsmLibBaseDir $doomAsmSubDir
$args | % {
    $asmFolder = Join-Path $doomAsmBaseDir $_
    cd $asmFolder
    hg push
}</pre>
}}}

----

{{{#!html
<pre><strong>wolf.push0.ps1</strong>
<span style="color: #008000;"># do wolf specific work here
</span>$pushFolder = Join-Path $Env:WolfBaseDir "dos"
cd $pushFolder
hg push

$dosSpecificFolder = Join-Path $pushFolder $env:WolfDosSubDir
cd $dosSpecificFolder
hg push

<span style="color: #008000;"># now push dos assembly language library repos
</span>$wolfAsmBaseDir = Join-Path $Env:AsmLibBaseDir $wolfAsmSubDir
$args | % {
    $asmFolder = Join-Path $wolfAsmBaseDir $_
    cd $asmFolder
    hg push
}
</pre>
}}}

As you can see from the example above, the three project specific scripts push different sub-repos that are passed in as parameters.

=== Problem ===

The three project specific scripts `{quake|doom|wolf}.push0.ps1`, work fine as they are now, if they are individually invoked from Powershell. But if they are  invoked from another Powershell script, then they fail processing the arguments passed in via `$args`.

The issue is that when `$args` is passed to `push0.ps1`, it's an array of parameters, but when you invoke another script from within `push0.ps1`, the `$args` array (i.e. all the parameters) is treated as a single parameter passed to the callee script. If I add a line to print out the arguments in `quake.push0.ps1` like this:

{{{#!html
<pre><strong>quake.push0.ps1</strong>
...
...
Write-Host "Quake:- args[=" $args.Count "]: " $args
...
...</pre>
}}}

And invoke `push0.ps1` passing in some arguments, then the output looks like this:

{{{#!html
<pre>$&gt; .\push0.ps1 boost libssl lua
Quake:- args[=<span style="color: #ff0000;"><strong>1</strong></span>]: boost libssl lua</pre>
  }}}

As you can see, even though all 3 parameters are passed in, they are seen as <em>a single parameter</em>.

Essentially it would appear, that when the callee script is invoked, all 3 parameters as passed in as `$args[0]`. Now, Powershell is an object scripting language and it seems to pass an <em>array of strings</em> from the caller script as the first and only parameter to the callee script.

Knowing that since Powershell is built on top of .NET and deals with objects, we can verify this by checking the type of $args[0] like this:

{{{#!html
<pre><strong>quake.push0.ps1</strong>
...
...
Write-Host $args[0].GetType().IsArray
...
...

<strong>OUTPUT</strong>
<span style="color: #0000ff;">True</span></pre>
}}}

And we're in business! :-)

=== Solution ===

What we need to do in the callees, is check if the incoming $args has only 1 parameter and if it's an array. If so, then simply use $args[0] as the actual list of arguments and process it below.

Since this bit of the code is common to multiple scripts, I put it in a function and stick it in the $PROFILE file or some other file that can be dot-sourced. Here's the function:
{{{#!html
<pre><strong><span style="color: #0000ff;">function UnwrapArguments($params) {</span></strong>
<strong><span style="color: #0000ff;">    $unwrapped = @()</span></strong>
<strong><span style="color: #0000ff;">    if ($params.Count -gt 0) {</span></strong>
<strong><span style="color: #0000ff;">        if ($params.Count -eq 1 -and $params[0].GetType().IsArray) {</span></strong>
<strong><span style="color: #0000ff;">            $unwrapped = $params[0]</span></strong>
<strong><span style="color: #0000ff;">        } else {</span></strong>
<strong><span style="color: #0000ff;">            $unwrapped = $params</span></strong>
<strong><span style="color: #0000ff;">        }</span></strong>
<strong><span style="color: #0000ff;">    }</span></strong>
<strong><span style="color: #0000ff;">    return $unwrapped</span></strong>
<strong><span style="color: #0000ff;">}</span></strong></pre>
}}}

So our scripts end up looking like this (changes in blue):

{{{#!html
<pre><strong>push0.ps1
<span style="color: #0000ff;"># NOTE: No changes to the caller.</span></strong>
<span style="color: #008000;"># $args is the array of input arguments to any script
# Do some work here common to all projects</span>
<span style="color: #008000;"># like pushing code to the master repo for developer scripts, etc.</span>

<span style="color: #008000;"># invoke project specific scripts here
# $Env:Project will be set to quake, doom or wolf</span>
<span style="color: #008000;"># call project specific push0 script if it exists </span>
<span style="color: #008000;"># and pass all arguments to it</span>
$scriptName = $Env:Project + ".push0.ps1"
if (Test-Path $scriptName) {
    &amp; $scriptName $args
}</pre>
}}}

----

{{{#!html
<pre><strong>quake.push0.ps1
<span style="color: #0000ff;">$myargs = UnwrapArguments($args)
</span></strong>
<span style="color: #008000;"># do quake specific work here
</span>$pushFolder = Join-Path $Env:QuakeBaseDir "win32"
cd $pushFolder
hg push

$winSpecificFolder = Join-Path $pushFolder $Env:QuakeWinSubDir
cd $winSpecificFolder
hg push

<span style="color: #008000;"># now push any external sub-repos
</span>$quakeExtBaseDir = Join-Path $Env:ExtBaseDir $QuakeExtWin32SubDir
<span style="color: #0000ff;"><strong>$myargs</strong></span> | % {
    $extFolder = Join-Path $quakeExtBaseDir $_
    cd $extFolder
    hg push
}
</pre>
}}}

----

{{{#!html
<pre><strong>doom.push0.ps1
<span style="color: #0000ff;">$myargs = UnwrapArguments($args)
</span></strong>
<span style="color: #008000;"># do doom specific work here
</span>$pushFolder = Join-Path $Env:DoomBaseDir "win16"
cd $pushFolder
hg push

$win16SpecificFolder = Join-Path $pushFolder $Env:DoomWin16SubDir
cd $win16SpecificFolder
hg push

<span style="color: #008000;"># now push assembly language library repos
</span>$doomAsmBaseDir = Join-Path $Env:AsmLibBaseDir $doomAsmSubDir
<strong><span style="color: #0000ff;">$myargs</span></strong> | % {
    $asmFolder = Join-Path $doomAsmBaseDir $_
    cd $asmFolder
    hg push
}</pre>
}}}

----

{{{#!html
<pre><strong>wolf.push0.ps1
<span style="color: #0000ff;">$myargs = UnwrapArguments($args)
</span></strong>
<span style="color: #008000;"># do wolf specific work here
</span>$pushFolder = Join-Path $Env:WolfBaseDir "dos"
cd $pushFolder
hg push

$dosSpecificFolder = Join-Path $pushFolder $env:WolfDosSubDir
cd $dosSpecificFolder
hg push

<span style="color: #008000;"># now push dos assembly language library repos
</span>$wolfAsmBaseDir = Join-Path $Env:AsmLibBaseDir $wolfAsmSubDir
<strong><span style="color: #0000ff;">$myargs</span></strong> | % {
    $asmFolder = Join-Path $wolfAsmBaseDir $_
    cd $asmFolder
    hg push
}
</pre>
}}}

That's it. We're golden.