Skip to content

ValueFromRemainingArguments parameters are not reflected as such in syntax diagrams #4626

Closed

Description

Related: #4715 and #4135.

It is currently hard to discover if a given cmdlet/function has a ValueFromRemainingArguments parameter, so I suggest we add a new representation to syntax diagrams to signal that a given cmdlet / advanced supports does so.

We'll have to decide what an adequate representation is.

For instance, Write-Host -? shows the following for its ValueFromRemainingArguments -Object parameter:

[[-Object] <Object>]

which does not reflect its "specialness" - you can't tell that this parameter enables specifying multiple, independent arguments that are all bound to -Object, enabling convenient free-form invocations as Write-Host a b c in lieu of (the also supported) Write-Host -Object a, b, c

Perhaps something along the lines of (updated based on the discussion below):

[-Object <Object> | <Object> ... ]

With an array-typed parameter, such as Join-Path's -AdditionalChildPath:

[-AdditionalChildPath <string[]> | <string> ...]

Environment data

PowerShell Core v6.0.0-beta.5 on macOS 10.12.6
PowerShell Core v6.0.0-beta.5 on Ubuntu 16.04.3 LTS
PowerShell Core v6.0.0-beta.5 on Microsoft Windows 10 Pro (64-bit; v10.0.15063)
Windows PowerShell v5.1.15063.483 on Microsoft Windows 10 Pro (64-bit; v10.0.15063)

Activity

  1. iSazonov commented on Aug 21, 2017

    @iSazonov
    Collaborator

    I can not repo this on Windows PowerShell v5.1.16257.1 (and 10240 too)

  2. added
    Issue-Discussionthe issue may not have a clear classification yet. The issue may generate an RFC or may be reclassif
    on Aug 21, 2017
  3. mklement0 commented on Aug 21, 2017

    @mklement0
    ContributorAuthor

    Ilya (@iSazonov):

    Sorry - I wasn't clear in my original title and post - please see if the update helps.

    (I was also originally distracted by Join-Path -? not showing the new -AddtionalChildPath parameter at all - see MicrosoftDocs/PowerShell-Docs#1612)

  4. iSazonov commented on Aug 21, 2017

    @iSazonov
    Collaborator

    [[-Object] <Object>[, <Object> ...] ]

  5. mklement0 commented on Aug 21, 2017

    @mklement0
    ContributorAuthor

    Well, the , is tricky, because we want to convey that you do not need it when taking advantage of the feature.

  6. iSazonov commented on Aug 21, 2017

    @iSazonov
    Collaborator

    [[-Object] <Object>[[,] <Object> ...] ]

  7. mklement0 commented on Aug 21, 2017

    @mklement0
    ContributorAuthor

    Keep in mind that the parameter type need not be <Object>.

    Among the core cmdlets that have ValueFromRemainingArguments parameters, you'll also see <string[]>, for instance (Get-Command -Syntax Join-Path, parameter -AdditionalChildPath).

    Conceptually, a ValueFromRemainingArguments parameter is inherently a collection, given that it can bind multiple arguments.

    The tricky part is that if you don't use the parameter name explicitly, you actually must use individual arguments as opposed to an array to get the equivalent functionality
    (at least with advanced functions (as opposed to compiled cmdlets), which brings us back to our perennial favorite, #2035).

    In the example above, you'd really need two distinct representations:

    [-AdditionalChildPath <string[]>]

    or, without parameter name:

    [<string> ...]

    So perhaps the following?

    [-AdditionalChildPath <string[]> | <string> ...]
  8. iSazonov commented on Aug 21, 2017

    @iSazonov
    Collaborator

    If #2035 will be fixed comma should be here too? [<string>, <string> ...]
    Are there a difference between -AdditionalChildPath <string[]> and -AdditionalChildPath <string>, <string>?

  9. mklement0 commented on Aug 21, 2017

    @mklement0
    ContributorAuthor

    As I've argued here, I strongly feel that it should be fixed in the way that advanced functions already work (read: parameter binding must be fixed for cmdlets - the opposite of what #2035 proposes), which means that in no-parameter-name invocations you must not use , - because use of , changes the semantics to sticking an array into the first element of the parameter variable.

  10. iSazonov commented on Aug 21, 2017

    @iSazonov
    Collaborator

    Thanks for clarify! So we are blocked until #2035 will be resolved.

  11. mklement0 commented on Aug 21, 2017

    @mklement0
    ContributorAuthor

    Not necessarily, because the <string> ... (comma-less) syntax will work either way, irrespective of how #2035 is resolved (incidentally, I just tried to clarify my arguments there).

    The <string> ... (comma-less) syntax is not only the more convenient syntax, it is also the only one that works when you call a PS script from the outside.

    In short: Either way, the comma-less syntax is the one worth highlighting in the syntax diagram.

  12. mklement0 commented on Aug 21, 2017

    @mklement0
    ContributorAuthor

    P.S.: To put it differently: You don't need ValueFromRemainingArguments at all for the <string>, <string>, ... syntax - just a regular positional parameter that accepts an array.

    It is the <string> <string> ... syntax that is unique to ValueFromRemainingArguments.

  13. iSazonov commented on Aug 22, 2017

    @iSazonov
    Collaborator

    the comma-less syntax is the one worth highlighting in the syntax diagram.

    Thanks! Clear. It is good [-AdditionalChildPath <string[]> | <string> ...]

  14. added
    Issue-Enhancementthe issue is more of a feature request than a bug
    and removed
    Issue-Discussionthe issue may not have a clear classification yet. The issue may generate an RFC or may be reclassif
    on Aug 31, 2017
  15. microsoft-github-policy-service commented on Nov 16, 2023

    @microsoft-github-policy-service
    Contributor

    This issue has not had any activity in 6 months, if this is a bug please try to reproduce on the latest version of PowerShell and reopen a new issue and reference this issue if this is still a blocker for you.

  16. microsoft-github-policy-service commented on Nov 16, 2023

    @microsoft-github-policy-service
    Contributor

    This issue has not had any activity in 6 months, if this is a bug please try to reproduce on the latest version of PowerShell and reopen a new issue and reference this issue if this is still a blocker for you.

  17. microsoft-github-policy-service commented on Nov 16, 2023

    @microsoft-github-policy-service
    Contributor

    This issue has not had any activity in 6 months, if this is a bug please try to reproduce on the latest version of PowerShell and reopen a new issue and reference this issue if this is still a blocker for you.

  18. microsoft-github-policy-service commented on Nov 23, 2023

    @microsoft-github-policy-service
    Contributor

    This issue has been marked as "No Activity" as there has been no activity for 6 months. It has been closed for housekeeping purposes.

  19. microsoft-github-policy-service commented on Sep 9, 2025

    @microsoft-github-policy-service
    Contributor

    This issue has not had any activity in 6 months, if there is no further activity in 7 days, the issue will be closed automatically.

    Activity in this case refers only to comments on the issue. If the issue is closed and you are the author, you can re-open the issue using the button below. Please add more information to be considered during retriage. If you are not the author but the issue is impacting you after it has been closed, please submit a new issue with updated details and a link to this issue and the original.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Issue-Enhancementthe issue is more of a feature request than a bugResolution-No ActivityIssue has had no activity for 6 months or moreWG-Interactive-HelpSystemhelp infrastructure and formatting of help

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions