Clarify function calling syntax

[RossBoylan]

It would be very useful for this page to say more about how to call a function. Minimally, note that f(x, y) is not the right way to make a call. That's point 1 below, followed by other nits:

1. Syntax for calling a function.
2. The reference near the top to getting parameters from a pipeline is unclear. It seems to imply function arguments can come from the pipeline, but the later discussion only mentions $_ and $input.
3. Can functions, including filters, that go in pipelines be defined with parameters? What happens if they are?
4. What is the allowable syntax for names of functions and parameters?
5. The reference to sending output to a pipe could explain exactly how that can be done. There seem to be several ways: as a return value; as a result of intermediate statements (not sure how it decides which statements count, since it doesn't seem to be all); maybe the result of write-output.
6. For a function with begin/process/end blocks, are variables shared between blocks? Concretely, if the begin block sets up $a, will later blocks have access to it?
7. Is $input defined in the process block? Is $_ defined in the other blocks?
8. Your example shows, I think, that $input has only the unprocessed inputs. Maybe make that explicit.
9. The following text was a bit confusing, because it sounded as if $input was the same as $_. It did later become clear it wasn't.

When you use a function in a pipeline, the objects piped to the function are assigned to the $input automatic variable.

The details of 4 may not belong here (though it would be nice if they were somewhere), and some of the issues about pipes might go better in the discussion of pipes.

5 is my current interest since I want to split an object in the pipe: an individual objects comes in, but multiple objects go out. I'm not sure if that's even possible, though I think with write-output it is.

But 1) is my main concern. Some additional comments on it:

• It would be better if the f(x, y) syntax just worked.
• Even if that were fixed, people using older versions will still be stuck.
• I, and I think many others, found the behavior really surprising and spent a couple hours debugging before I realized what was going on.
• In my searches I found some references to the f(a, b) syntax as working for functions that were defined in (maybe) .NET--maybe even being mandatory there.
• It's still unclear to me what is going on. When $a and $b are hash tables, $r = @($a, $b) produces $r.Count of 2. But if I call f($a, $b) and evaluates the counts of $a and $b inside the function, I get the sum of the counts of a and b in the caller for a in the function, and 0 for b in the function
  .

---

Document Details

⚠ Do not edit this section. It is required for docs.microsoft.com ➟ GitHub issue linking.

• ID: d3a3fb40-0e44-40a0-c43c-7c4db52e7b39
• Version Independent ID: c7397f10-91d3-c735-244f-bfaa1072545a
• Content: about_Functions
• Content Source: reference/6/Microsoft.PowerShell.Core/About/about_Functions.md
• Product: powershell
• Technology: powershell-cmdlets
• GitHub Login: @SteveL-MSFT
• Microsoft Alias: slee

[sdwheeler]

@RossBoylan Regarding the f(x, y) syntax, you may be confusing this syntax with the syntax required for calling a Method. Calling a method on an object always requires parentheses. For example:

$x = dir .\build.ps1
$x
$x.GetType()

IsPublic IsSerial Name                                     BaseType
-------- -------- ----                                     --------
True     False    FileInfo                                 System.IO.FileSystemInfo

If the method takes parameters, the parameters must be inside the parentheses. Multiple parameters must be separated by a comma.

Your other scenario is easy to explain. Take the following example:

$x = @{a=4; b="hello"}
$y = @{a=4; b="hello"; c=1.2}

function test {
  param($a, $b)

  'Parameter $a:'
  $a.count
  $a.GetType()

  'Parameter $b:'
  $b.count
  $b.GetType()
}

PS> $x.count
2
PS> $y.count
3

PS> test $x, $y
Parameter $a:
2

IsPublic IsSerial Name                                     BaseType
-------- -------- ----                                     --------
True     True     Object[]                                 System.Array
Parameter $b:
0
You cannot call a method on a null-valued expression.
At line:10 char:3
+   $b.GetType()
+   ~~~~~~~~~~~~
+ CategoryInfo          : InvalidOperation: (:) [], RuntimeException
+ FullyQualifiedErrorId : InvokeMethodOnNull

PS> test $x $y
Parameter $a:
2

IsPublic IsSerial Name                                     BaseType
-------- -------- ----                                     --------
True     True     Hashtable                                System.Object
Parameter $b:
3
True     True     Hashtable                                System.Object

When calling a function with multiple parameters, do not use a comma. Using a comma turns your parameter list into an arrary. So the function receives only one parameter (the array).

[sdwheeler]

Here a brief list of answers to your questions:

1. The syntax is the same as for cmdlets. Parameters are not separated by commas. Don't use parentheses.
2. See https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_functions_advanced_parameters
3. Yes. See about_functions_advanced_parameters
4. Basically this is the same as for variables.
   • A Unicode character of classes Lu, Ll, Lt, Lm, Lo, or Nd - (basically alphanumeric)
   • _ (The underscore character U+005F)
   • ? (The question mark)
5. Anything not written to a specific stream (Information, verbose, debug, etc.) is sent to the pipeline. Write-Host only writes to the host application, not the pipeline. Write-Output send objects to the pipeline. Implicit output happens when your script/function has an expression that is not assigned to a variable or redirected (like $a.count in the test function above). Implicit output is sent to the pipeline.
6. I think this is covered in the about_Functions article. See https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_function#piping-objects-to-functions
7. Same answer as 6.
8. Fair feedback. We can be more explicit.
9. We can be more explicit.