7. Expressões

Nota editorial

Importante

A Especificação de Linguagem 3.0 do Windows PowerShell foi publicada em dezembro de 2012 e é baseada no Windows PowerShell 3.0. Essa especificação não reflete o estado atual do PowerShell. Não há nenhum plano para atualizar essa documentação para refletir o estado atual. Esta documentação é apresentada aqui para referência histórica.

O documento de especificação está disponível como um documento do Microsoft Word do Centro de Download da Microsoft em: https://www.microsoft.com/download/details.aspx?id=36389 esse documento do Word foi convertido para apresentação aqui no Microsoft Learn. Durante a conversão, algumas alterações editoriais foram feitas para acomodar a formatação para a plataforma Docs. Alguns erros de digitação e pequenos foram corrigidos.

Sintaxe:

expression:
    primary-expression
    bitwise-expression
    logical-expression
    comparison-expression
    additive-expression
    multiplicative-expression

dash: one of
    - (U+002D)
    EnDash character (U+2013)
    EmDash character (U+2014)
    Horizontal bar character (U+2015)

dashdash:
    dash dash

Descrição:

Uma expressão é uma sequência de operadores e operandos que designa um método, uma função, um local gravável ou um valor; especifica a computação de um valor; produz um ou mais efeitos colaterais; ou executa alguma combinação dela. Por exemplo

• O literal 123 é uma expressão que designa o valor int 123.
• A expressão 1,2,3,4 designa o objeto de matriz de 4 elementos com os valores mostrados.
• A expressão 10.4 * $a especifica uma computação.
• A expressão $a++ produz um efeito colateral.
• A expressão $a[$i--] = $b[++$j] executa uma combinação dessas coisas.

Exceto conforme especificado para alguns operadores, a ordem de avaliação de termos em uma expressão e a ordem em que ocorrem efeitos colaterais não são especificados. Exemplos de comportamento não especificado incluem o seguinte: $i++ + $i, $i + --$ie $w[$j++] = $v[$j].

Uma implementação do PowerShell pode fornecer suporte para tipos definidos pelo usuário e esses tipos podem ter operações definidas neles. Todos os detalhes desses tipos e operações são definidos para implementação.

Uma expressão de de nível superior é uma que não faz parte de alguma expressão maior. Se uma expressão de nível superior contiver um operador de efeito colateral, o valor dessa expressão não será gravado no pipeline, caso contrário, será. Consulte do §7.1.1 para obter uma discussão detalhada sobre isso.

Normalmente, uma expressão que designa uma coleção ([§4§4]) é enumerada em seus elementos constituintes quando o valor dessa expressão é usado. No entanto, esse não é o caso quando a expressão é uma invocação de cmdlet. Por exemplo

$x = 10,20,30
$a = $($x; 99)                     # $a.Length is 4

$x = New-Object 'int[]' 3
$a = $($x; 99)                     # equivalent, $a.Length is 4

$a = $(New-Object 'int[]' 3; 99)   # $a.Length is 2

Nos dois primeiros usos do operador $(...), a expressão que designa a coleção é a variável $x, que é enumerada resultando em três valores int, além do int 99. No entanto, no terceiro caso, a expressão é uma chamada direta para um cmdlet, portanto, o resultado não é enumerado e $a é uma matriz de dois elementos, int[3] e int.

Se uma operação não for definida pelo PowerShell, o tipo do valor designado pelo operando esquerdo será inspecionado para ver se ele tem um método de op_<operation> correspondente.

7.1 Expressões primárias

Sintaxe:

primary-expression:
    value
    member-access
    element-access
    invocation-expression
    post-increment-expression
    post-decrement-expression

value:
    parenthesized-expression
    sub-expression
    array-expression
    script-block-expression
    hash-literal-expression
    literal
    type-literal
    variable

7.1.1 Parênteses de agrupamento

Sintaxe:

Dica

A notação ~opt~ nas definições de sintaxe indica que a entidade lexical é opcional na sintaxe.

parenthesized-expression:
    ( new-lines~opt~ pipeline new-lines~opt~ )

Descrição:

Uma expressão parêntese é uma expressão primária cujo tipo e valor são iguais aos da expressão sem os parênteses. Se a expressão designar uma variável, a expressão parêntese designa essa mesma variável. Por exemplo, $x.m e ($x).m são equivalentes.

O agrupamento de parênteses pode ser usado em uma expressão para documentar a precedência padrão e a associatividade dentro dessa expressão. Eles também podem ser usados para substituir essa precedência e associatividade padrão. Por exemplo

4 + 6 * 2    # 16
4 + (6 * 2)  # 16 document default precedence
(4 + 6) * 2  # 20 override default precedence

Normalmente, agrupar parênteses no nível mais alto é redundante. No entanto, nem sempre esse é o caso. Considere o seguinte exemplo:

2,4,6       # Length 3; values 2,4,6
(2,4),6     # Length 2; values [object[]],int

No segundo caso, os parênteses alteram a semântica, resultando em um array cujos dois elementos são um array de 2 ints e o escalar int 6.

Aqui está outra exceção:

23.5/2.4          # pipeline gets 9.79166666666667
$a = 1234 * 3.5   # value not written to pipeline
$a                # pipeline gets 4319

No primeiro e no terceiro casos, o valor do resultado é gravado no pipeline. No entanto, embora a expressão no segundo caso seja avaliada, o resultado não é gravado no pipeline devido à presença do operador de efeito colateral = no nível superior. (A remoção da parte $a = permite que o valor seja gravado, pois * não é um operador de efeito colateral.)

Para impedir que o valor de qualquer expressão que não contenha efeitos colaterais de nível superior seja gravado no pipeline, descarte-o explicitamente, da seguinte maneira:

# None of these value are written to pipeline
[void](23.5/2.4)
[void]$a
$null = $a
$a > $null

Para gravar no pipeline o valor de qualquer expressão que contenha efeitos colaterais de nível superior, coloque essa expressão entre parênteses, da seguinte maneira:

($a = 1234 * 3.5) # pipeline gets 4319

Dessa forma, os parênteses de agrupamento nesse caso não são redundantes.

No exemplo a seguir, temos a substituição de variável (seção 2.3.5.2) ocorrendo em um literal de cadeia de caracteres:

">$($a = -23)<"    # value not written to pipeline, get ><
">$(($a = -23))<"  # pipeline gets >-23<

No primeiro caso, os parênteses representam os delimitadores de uma subexpressão , e não parênteses de agrupamento . Além disso, como a expressão de nível superior contém um operador de efeito colateral, o valor da expressão não é gravado no pipeline. É claro que os caracteres > e < ainda estão escritos.) Se os parênteses de agrupamento forem adicionados conforme mostrado no segundo caso, a escrita será habilitada.

Os exemplos a seguir contêm operadores de efeito colateral de nível superior:

$a = $b = 0      # value not written to pipeline
$a = ($b = 0)    # value not written to pipeline
($a = ($b = 0))  # pipeline gets 0

++$a             # value not written to pipeline
(++$b)           # pipeline gets 1

$a--             # value not written to pipeline
($b--)           # pipeline gets 1

O uso de parênteses em torno de uma expressão que não contém efeitos colaterais no nível mais elevado torna esses parênteses redundantes. Por exemplo;

$a      # pipeline gets 0
($a)    # no side effect, so () redundant

Considere o exemplo a seguir que tem dois efeitos colaterais, nenhum dos quais está no nível superior:

12.6 + ($a = 10 - ++$b) # pipeline gets 21.6.

O resultado é gravado no pipeline, pois a expressão de nível superior não tem efeitos colaterais.

7.1.2 Acesso de membro

Sintaxe:

member-access:
    primary-expression . new-line~opt~ member-name
    primary-expression :: new-line~opt~ member-name

Observe que nenhum espaço em branco é permitido após expressão primária.

Descrição:

O operador . é usado para selecionar um membro de instância de um objeto ou uma chave de um Hashtable. O operando esquerdo deve designar um objeto e o operando direito deve designar um membro de instância acessível.

O operando à direita designa um membro de instância acessível dentro do tipo do objeto designado pelo operando esquerdo ou, se o operando esquerdo designar uma matriz, o operando direito designa membros de instância acessíveis dentro de cada elemento da matriz.

O espaço em branco não é permitido antes do operador ..

Esse operador é associativo à esquerda.

O operador :: é usado para selecionar um membro estático de um determinado tipo. O operando esquerdo deve designar um tipo e o operando à direita deve designar um membro estático acessível dentro desse tipo.

O espaço em branco não é permitido antes do operador ::.

Esse operador é associativo à esquerda.

Se o operando à direita designar um local gravável dentro do tipo do objeto designado pelo operando à esquerda, a expressão inteira designará um local gravável.

Exemplos:

$a = 10, 20, 30
$a.Length                    # get instance property

(10, 20, 30).Length

$property = "Length"
$a.$property                 # property name is a variable

$h1 = @{ FirstName = "James"; LastName = "Anderson"; IDNum = 123
}
$h1.FirstName                # designates the key FirstName
$h1.Keys                     # gets the collection of keys

[int]::MinValue              # get static property
[double]::PositiveInfinity   # get static property
$property = "MinValue"
[long]::$property            # property name is a variable

foreach ($t in [byte], [int], [long]) {
    $t::MaxValue             # get static property
}

$a = @{ID = 1 }, @{ID = 2 }, @{ID = 3 }
$a.ID                        # get ID from each element in the array

7.1.3 Expressões de invocação

Sintaxe:

invocation-expression:
    primary-expression . new-line~opt~ member-name argument-list
    primary-expression :: new-line~opt~ member-name argument-list

argument-list:
    ( argument-expression-list~opt~ new-lines~opt~ )

Observe que nenhum espaço em branco é permitido após primary-expression.

Descrição:

Uma expressão de invocação chama o método designado por primary-expression.member-name ou primary-expression::member-name. Os parênteses na lista de argumentos contêm uma lista possivelmente vazia, separada por vírgulas, de expressões que designam os argumentos cujos valores são passados para o método. Antes que o método seja chamado, os argumentos são avaliados e convertidos de acordo com as regras de §6, se necessário, para corresponder aos tipos esperados pelo método. A ordem de avaliação de primary-expression.member-name, primary-expression::member-namee os argumentos não é especificada.

Esse operador é associativo à esquerda.

O tipo do resultado de uma expressão de invocação é um designador de método (§4.5.24).

Exemplos:

[math]::Sqrt(2.0)            # call method with argument 2.0
[char]::IsUpper("a")         # call method
$b = "abc#$%XYZabc"
$b.ToUpper()                 # call instance method

[math]::Sqrt(2)              # convert 2 to 2.0 and call method
[math]::Sqrt(2D)             # convert 2D to 2.0 and call method
[math]::Sqrt($true)          # convert $true to 1.0 and call method
[math]::Sqrt("20")           # convert "20" to 20 and call method

$a = [math]::Sqrt            # get method descriptor for Sqrt
$a.Invoke(2.0)               # call Sqrt via the descriptor
$a = [math]::("Sq"+"rt")     # get method descriptor for Sqrt
$a.Invoke(2.0)               # call Sqrt via the descriptor
$a = [char]::ToLower         # get method descriptor for ToLower
$a.Invoke("X")               # call ToLower via the descriptor

Acesso ao elemento 7.1.4

Sintaxe:

element-access:
    primary-expression [ new-lines~opt~ expression new-lines~opt~ ]

Descrição:

Não deve haver nenhum espaço em branco entre de expressão primária e o colchete esquerdo ([).

7.1.4.1 Subscritando uma matriz

Descrição:

As matrizes são discutidas detalhadamente em §9. Se expressão for uma matriz unidimensional, consulte §7.1.4.5.

Quando expressão primária designa uma matriz unidimensional A, o operador [] retorna o elemento localizado em A[0 + expression] depois que o valor da expressão foi convertido em int. O resultado tem o tipo de elemento da matriz que está sendo indexada. Se a expressão for negativa, A[expression] designa o elemento localizado em A[A.Length + expression].

Quando primary-expression designar uma matriz bidimensional B, o operador [] retornará o elemento localizado em B[0 + row,0 + column] depois que o valor dos componentes de linha e coluna de expression (que são especificados em uma lista separada por vírgulas) forem convertidos em int. O resultado tem o tipo de elemento da matriz que está sendo indexada. Ao contrário de uma matriz unidimensional, as posições negativas não têm nenhum significado especial.

Quando expressão primária designa uma matriz de três ou mais dimensões, as regras para matrizes bidimensionais se aplicam e as posições de dimensão são especificadas como uma lista de valores separada por vírgulas.

Se um acesso de leitura em um elemento não existente for tentado, o resultado será $null. É um erro gravar em um elemento não existente.

Para uma expressão de indexação de matriz multidimensional, a ordem de avaliação das expressões de posição da dimensão não é especificada. Por exemplo, considerando uma matriz tridimensional $a, o comportamento de $a[$i++,$i,++$i] não é especificado.

Se expressão for uma matriz, consulte a seção 7.1.4.5.

Esse operador é associativo à esquerda.

Exemplos:

$a = [int[]](10,20,30) # [int[]], Length 3
$a[1] # returns int 20
$a[20] # no such position, returns $null
$a[-1] # returns int 30, i.e., $a[$a.Length-1]
$a[2] = 5 # changes int 30 to int 5
$a[20] = 5 # implementation-defined behavior

$a = New-Object 'double[,]' 3,2
$a[0,0] = 10.5 # changes 0.0 to 10.5
$a[0,0]++ # changes 10.5 to 10.6

$list = ("red",$true,10),20,(1.2, "yes")
$list[2][1] # returns string "yes"

$a = @{ A = 10 },@{ B = $true },@{ C = 123.45 }
$a[1]["B"] # $a[1] is a Hashtable, where B is a key

$a = "red","green"
$a[1][4] # returns string "n" from string in $a[1]

Se houver a tentativa de acesso de gravação a um elemento não existente, uma exceção IndexOutOfRange será gerada.

7.1.4.2 Subscrevendo uma cadeia de caracteres

Descrição:

Quando primary-expression designa uma cadeia de caracteres S, o operador [] retorna o caractere localizado na posição baseada em zero indicada por expression, como um char. Se expressão for maior ou igual ao comprimento da cadeia de caracteres, o resultado será $null. Se a expressão for negativa, S[expression] designa o elemento localizado em S[S.Length + expression].

Exemplos:

$s = "Hello"   # string, Length 5, positions 0-4
$c = $s[1]     # returns "e" as a string
$c = $s[20]    # no such position, returns $null
$c = $s[-1]    # returns "o", i.e., $s[$s.Length-1]

7.1.4.3 Indexação de uma tabela de hash

Descrição:

Quando primary-expression designa uma tabela de hash, o operador [] retorna os valores associados às chaves designadas por expression. O tipo de expressão não é restrito.

Quando a expressão em é o nome de uma única chave, o resultado é o valor associado e tem esse tipo, a menos que essa chave não exista; nesse caso, o resultado é . Se $null for usado como a chave, o comportamento será definido pela implementação. Se expressão for uma matriz de nomes de chave, consulte §7.1.4.5.

Se expressão for uma matriz, consulte a seção 7.1.4.5.

Exemplos:

$h1 = @{ FirstName = "James"; LastName = "Anderson"; IDNum = 123 }
$h1['FirstName']     # the value associated with key FirstName
$h1['BirthDate']     # no such key, returns $null

$h1 = @{ 10 = "James"; 20.5 = "Anderson"; $true = 123 }
$h1[10]              # returns value "James" using key 10
$h1[20.5]            # returns value "Anderson" using key 20.5
$h1[$true]           # returns value 123 using key $true

Quando expression for o nome de uma chave única e se $null for usado como o único valor para indexação de uma tabela de hash, uma exceção NullArrayIndex será gerada.

7.1.4.4 Subscrição de um documento XML

Descrição:

Quando primary-expression designa um objeto do tipo XML, expression é convertida em cadeia de caracteres, se necessário, e o operador [] retorna o primeiro elemento filho que tem o nome especificado por expression. O tipo de expressão deve ser cadeia de caracteres. O tipo do resultado é definido pela implementação. O resultado pode ser indexado para retornar seu primeiro elemento filho. Se não existir nenhum elemento filho com o nome especificado pela expressão , o resultado será $null. O resultado não designa um local gravável.

Exemplos:

$x = [xml]@"
<Name>
<FirstName>Mary</FirstName>
<LastName>King</LastName>
</Name>
"@

$x['Name']                # refers to the element Name
$x['Name']['FirstName']   # refers to the element FirstName within Name
$x['FirstName']           # No such child element at the top level, result is $null

O tipo do resultado é System.Xml.XmlElement ou System.String.

7.1.4.5 Gerando fatias de matriz

Quando primary-expression designar um objeto de um tipo que é enumerável (seção 4) ou uma Tabela de hash e expression for uma matriz unidimensional, o resultado será uma fatia de matriz (seção 9.9) contendo os elementos de primary-expression designados pelos elementos de expression.

No caso de um Hashtable, a fatia de matriz contém os valores associados às chaves fornecidas, a menos que essa chave não exista, nesse caso, o elemento correspondente é $null. Se $null for usado como qualquer nome de chave, o comportamento será definido pela implementação.

Exemplos:

$a = [int[]](30,40,50,60,70,80,90)
$a[1,3,5]                 # slice has Length 3, value 40,60,80
$a[,5]                    # slice with Length 1
$a[@()]                   # slice with Length 0
$a[-1..-3]                # slice with Length 3, value 90,80,70
$a = New-Object 'int[,]' 3,2
$a[0,0] = 10; $a[0,1] = 20; $a[1,0] = 30
$a[1,1] = 40; $a[2,0] = 50; $a[2,1] = 60
$a[(0,1),(1,0)]           # slice with Length 2, value 20,30, parens needed
$h1 = @{ FirstName = "James"; LastName = "Anderson"; IDNum = 123 }
$h1['FirstName']          # the value associated with key FirstName
$h1['BirthDate']          # no such key, returns $null
$h1['FirstName','IDNum']  # returns [object[]], Length 2 (James/123)
$h1['FirstName','xxx']    # returns [object[]], Length 2 (James/$null)
$h1[$null,'IDNum']        # returns [object[]], Length 2 ($null/123)

Windows PowerShell: quando expressão é uma coleção de dois ou mais nomes de chave, se $null for usado como qualquer nome de chave, essa chave será ignorada e não tiver nenhum elemento correspondente na matriz resultante.

7.1.5 Operadores de incremento e de decremento pós-fixados

Sintaxe:

post-increment-expression:
    primary-expression ++

post-decrement-expression:
    primary-expression dashdash

Descrição:

A primary-expression deve designar um local gravável com um valor de tipo numérico (seção 4) ou o valor $null. Se o valor designado pelo operando for $null, esse valor será convertido em tipo int e valor zero antes que o operador seja avaliado. O tipo de valor designado por expressão primária pode mudar quando o resultado é armazenado. Confira a seção 7.11 para uma discussão sobre alteração de tipo por meio de atribuição.

O resultado produzido pelo operador postfixo ++ é o valor designado pelo operando. Depois que esse resultado é obtido, o valor designado pelo operando é incrementado por 1 do tipo apropriado. O tipo do resultado da expressão E++ é o mesmo do resultado da expressão E + 1 (§7,7).

O resultado produzido pelo operador de postfixo -- é o valor designado pelo operando. Depois que esse resultado é obtido, o valor designado pelo operando é decrementado por 1 do tipo apropriado. O tipo do resultado da expressão E-- é o mesmo do resultado da expressão E - 1 (§7,7).

Esses operadores são associativos à esquerda.

Exemplos:

$i = 0                # $i = 0
$i++                  # $i is incremented by 1
$j = $i--             # $j takes on the value of $i before the decrement

$a = 1,2,3
$b = 9,8,7
$i = 0
$j = 1
$b[$j--] = $a[$i++]   # $b[1] takes on the value of $a[0], then $j is
                      # decremented, $i incremented

$i = 2147483647       # $i holds a value of type int
$i++                  # $i now holds a value of type double because
                      # 2147483648 is too big to fit in type int

[int]$k = 0           # $k is constrained to int
$k = [int]::MaxValue  # $k is set to 2147483647
$k++                  # 2147483648 is too big to fit, imp-def behavior

$x = $null            # target is unconstrained, $null goes to [int]0
$x++                  # value treated as int, 0->1

7.1.6 Operador $(...)

Sintaxe:

sub-expression:
    $( new-lines~opt~ statement-list~opt~ new-lines~opt~ )

Descrição:

Se statement-list for omitida, o resultado será $null. Caso contrário, statement-list será avaliada. Os objetos gravados no pipeline como parte da avaliação serão coletados em uma matriz unidimensional irrestrita e de acordo com uma ordem. Se a matriz de objetos coletados estiver vazia, o resultado será $null. Se a matriz de objetos coletados contiver um único elemento, o resultado será esse elemento; caso contrário, o resultado será a matriz unidimensional irrestrita de resultados coletados.

Exemplos:

$j = 20
$($i = 10) # pipeline gets nothing
$(($i = 10)) # pipeline gets int 10
$($i = 10; $j) # pipeline gets int 20
$(($i = 10); $j) # pipeline gets [object[]](10,20)
$(($i = 10); ++$j) # pipeline gets int 10
$(($i = 10); (++$j)) # pipeline gets [object[]](10,22)
$($i = 10; ++$j) # pipeline gets nothing
$(2,4,6) # pipeline gets [object[]](2,4,6)

7.1.7 Operador @(...)

Sintaxe:

array-expression:
    @( new-lines~opt~ statement-list~opt~ new-lines~opt~ )

Descrição:

Se statement-list for omitida, o resultado será uma matriz unidimensional irrestrita de comprimento zero. Caso contrário, se statement-list for avaliada, os objetos gravados no pipeline como parte da avaliação serão coletados em uma matriz unidimensional irrestrita e de acordo com uma ordem. O resultado é a matriz unidimensional não restrita (possivelmente vazia).

Exemplos:

$j = 20
@($i = 10)             # 10 not written to pipeline, result is array of 0
@(($i = 10))           # pipeline gets 10, result is array of 1
@($i = 10; $j)         # 10 not written to pipeline, result is array of 1
@(($i = 10); $j)       # pipeline gets 10, result is array of 2
@(($i = 10); ++$j)     # pipeline gets 10, result is array of 1
@(($i = 10); (++$j))   # pipeline gets both values, result is array of 2
@($i = 10; ++$j)       # pipeline gets nothing, result is array of 0

$a = @(2,4,6)          # result is array of 3
@($a)                  # result is the same array of 3
@(@($a))               # result is the same array of 3

7.1.8 Expressão de bloco de script

Sintaxe:

script-block-expression:
    { new-lines~opt~ script-block new-lines~opt~ }

script-block:
    param-block~opt~ statement-terminators~opt~ script-block-body~opt~

script-block-body:
    named-block-list
    statement-list

Descrição:

bloco de parâmetros é descrito na seção 8.10.9. named-block-list é descrito em §8.10.7.

Um bloco de script é um bloco de instruções sem nome que pode ser usado como uma única unidade. Os blocos de script podem ser usados para invocar um bloco de código como se fosse um único comando ou podem ser atribuídos a variáveis que podem ser executadas.

O named-block-list ou statement-list é executado e o tipo e os valores do resultado são do tipo e dos valores dos resultados desses conjuntos de instruções.

Um script-block-expression tem um tipo scriptblock (seção 4.3.7).

Se o bloco de parâmetros for omitido, todos os argumentos passados para o bloco de script estarão disponíveis por meio de $args (§8.10.1).

Durante a associação de parâmetro, um bloco de script pode ser passado como um objeto de bloco de script ou como resultado após a avaliação do bloco de script. Consulte §6.17 para obter mais informações.

7.1.9 Expressão literal de hash

Sintaxe:

hash-literal-expression:
    @{ new-lines~opt~ hash-literal-body~opt~ new-lines~opt~ }

hash-literal-body:
    hash-entry
    hash-literal-body statement-terminators hash-entry

hash-entry:
    key-expression = new-lines~opt~ statement

key-expression:
    simple-name
    unary-expression

statement-terminators:
    statement-terminator
    statement-terminators statement-terminator

statement-terminator:
    ;
    new-line-character

Descrição:

Uma hash-literal-expression é usada para criar uma Tabela de hash (seção 10) de zero ou mais elementos, cada qual sendo um par de chave/valor.

A chave pode ter qualquer tipo, exceto o tipo nulo. Os valores associados podem ter qualquer tipo, incluindo o tipo nulo, e cada um desses valores pode ser qualquer expressão que designe o valor desejado, incluindo $null.

A ordenação dos pares chave/valor não é significativa.

Exemplos:

$h1 = @{ FirstName = "James"; LastName = "Anderson"; IDNum = 123 }
$last = "Anderson"; $IDNum = 120
$h2 = @{ FirstName = "James"; LastName = $last; IDNum = $IDNum + 3 }
$h3 = @{ }
$h4 = @{ 10 = "James"; 20.5 = "Anderson"; $true = 123 }

que cria dois Hashtables, $h1 e $h2, cada um contendo três pares chave/valor e um terço, $h3, que está vazio. A Tabela de hash $h4 tem chaves de vários tipos.

7.1.10 Tipo de expressão literal

Sintaxe:

type-literal:
    [ type-spec ]

type-spec:
    array-type-name new-lines~opt~ dimension~opt~ ]
    generic-type-name new-lines~opt~ generic-type-arguments ]
    type-name

dimension:
    ,
    dimension ,

generic-type-arguments:
    type-spec new-lines~opt~
    generic-type-arguments , new-lines~opt~ type-spec

array-type-name:
    type-name [

generic-type-name:
    type-name [

Descrição:

Um type-literal é representado em uma implementação por algum tipo subjacente não especificado. Como resultado, um nome de tipo é um sinônimo para seu tipo subjacente.

Literais de tipo são usados em vários contextos:

• Especificando uma conversão explícita (§6, §7.2.9)
• Criando uma matriz restrita por tipo (§9,4)
• Acessando os membros estáticos de um objeto (§7.1.2)
• Especificando uma restrição de tipo em uma variável (§5.3) ou um parâmetro de função (§8.10.2)

Exemplos:

[int].IsPrimitive        # $true
[Object[]].FullName      # "System.Object[]"
[int[,,]].GetArrayRank() # 3

Um tipo de pilha genérico (seção 4.4) especializado para conter cadeias de caracteres pode ser escrito como [Stack[string]] e um tipo de dicionário genérico especializado para conter chaves int com valores de cadeia de caracteres associados pode ser escrito como [Dictionary[int,string]].

O tipo de um type-literal é System.Type. O nome completo do tipo Stack[string] sugerido acima é System.Collections.Generic.Stack[int]. O nome completo do tipo Dictionary[int,string] sugerido acima é System.Collections.Generic.Dictionary[int,string].

7.2 Operadores unários

Sintaxe:

unary-expression:
    primary-expression
    expression-with-unary-operator

expression-with-unary-operator:
    , new-lines~opt~ unary-expression
    -not new-lines~opt~ unary-expression
    ! new-lines~opt~ unary-expression
    -bnot new-lines~opt~ unary-expression
    + new-lines~opt~ unary-expression
    dash new-lines~opt~ unary-expression
    pre-increment-expression
    pre-decrement-expression
    cast-expression
    -split new-lines~opt~ unary-expression
    -join new-lines~opt~ unary-expression

pre-increment-expression:
    ++ new-lines~opt~ unary-expression

pre-decrement-expression:
    dashdash new-lines~opt~ unary-expression

dash: one of
    - (U+002D)
    EnDash character (U+2013)
    EmDash character (U+2014)
    Horizontal bar character (U+2015)

cast-expression:
    type-literal unary-expression

dashdash:
    dash dash

7.2.1 Operador de vírgula unário

Descrição:

O operador de vírgula (,) cria uma matriz unidimensional não restrita com um elemento, cujo tipo e valor são os de expressão unária.

Esse operador é associado à direita.

Exemplos:

$a = ,10         # create an unconstrained array of 1 element, $a[0],
                 # which has type int

$a = ,(10,"red") # create an unconstrained array of 1 element,
$a[0],
                 # which is an unconstrained array of 2 elements,
                 # $a[0][0] an int, and $a[0][1] a string

$a = ,,10        # create an unconstrained array of 1 element, which is
                 # an unconstrained array of 1 element, which is an int
                 # $a[0][0] is the int. Contrast this with @(@(10))

7.2.2 Lógico NÃO

Sintaxe:

logical-not-operator:
    dash not

dash: one of
    - (U+002D)
    EnDash character (U+2013)
    EmDash character (U+2014)
    Horizontal bar character (U+2015)

Descrição:

O operador -not converte o valor designado pela expressão unária para o tipo bool (§6.2), se necessário, e produz um resultado desse tipo. Se o valor de unary-expression for True, o resultado será False e vice-versa. O operador ! é uma ortografia alternativa para -not.

Esse operador é associado à direita.

Exemplos:

-not $true         # False
-not -not $false   # False
-not 0             # True
-not 1.23          # False
!"xyz"             # False

7.2.3 NOT bit a bit

Sintaxe:

bitwise-not-operator:
    dash bnot

dash: one of
    - (U+002D)
    EnDash character (U+2013)
    EmDash character (U+2014)
    Horizontal bar character (U+2015)

Descrição:

O operador -bnot converte o valor designado por de expressão unária em um tipo inteiro (§6,4), se necessário. Se o valor convertido puder ser representado no tipo int, esse será o tipo de resultado. Caso contrário, se o valor convertido puder ser representado no tipo longo, esse será o tipo de resultado. Caso contrário, a expressão é mal formada. O valor resultante é o complemento de uns do valor convertido.

Esse operador é associado à direita.

Exemplos:

-bnot $true         # int with value 0xFFFFFFFE
-bnot 10            # int with value 0xFFFFFFF5
-bnot 2147483648.1  # long with value 0xFFFFFFFF7FFFFFFF
-bnot $null         # int with value 0xFFFFFFFF
-bnot "0xabc"       # int with value 0xFFFFF543

7.2.4 Unary plus

Descrição:

Uma expressão do formulário + unary-expression é tratada como se tivesse sido escrita como 0 + unary-expression (§7,7). O literal inteiro 0 é do tipo int.

Esse operador é associado à direita.

Exemplos:

+123L         # type long, value 123
+0.12340D     # type decimal, value 0.12340
+"0xabc"      # type int, value 2748

7.2.5 Menos unário

Descrição:

Uma expressão do formulário - unary-expression é tratada como se tivesse sido escrita como 0 - unary-expression (§7,7). O literal inteiro 0 tem o tipo int. O operador menos pode ser qualquer um dos caracteres de traço listados em §7.2.

Esse operador é associado à direita.

Exemplos:

-$true     # type int, value -1
-123L      # type long, value -123
-0.12340D  # type decimal, value -0.12340

7.2.6 Operadores de incremento e de decremento pré-fixados

Descrição:

A expressão unária deve designar um local gravável com um valor de tipo numérico (§4) ou o valor $null. Se o valor designado pela respectiva unary-expression for $null, o valor da unary-expression será convertido no tipo int e no valor zero antes que o operador seja avaliado.

Nota

O tipo do valor designado por de expressão unária pode mudar quando o resultado é armazenado. Consulte §7.11 para uma discussão sobre a mudança de tipo por atribuição.

Para o operador de incremento de prefixo ++, o valor da expressão unária é incrementado por 1 do tipo apropriado. O resultado é o novo valor após o incremento ter ocorrido. A expressão ++E é equivalente a E += 1 (§7.11.2).

Para o operador de decremento de prefixo --, o valor da expressão unária é decrementado por 1 do tipo apropriado. O resultado é o novo valor após o decréscimo ter ocorrido. A expressão --E é equivalente a E -= 1 (§7.11.2). O operador de decremento de prefixo pode ser qualquer um dos padrões que correspondem ao padrão traçotraço em §7.2.

Esses operadores são associativos à direita.

Exemplos:

$i = 0                # $i = 0
++$i                  # $i is incremented by 1
$j = --$i             # $i is decremented then $j takes on the value of $i

$a = 1,2,3
$b = 9,8,7
$i = 0;
$j = 1
$b[--$j] = $a[++$i]   # $j is # decremented, $i incremented, then $b[0]
                      # takes on the value of $a[1]

$i = 2147483647       # $i holds a value of type int
++$i                  # $i now holds a value of type double because
                      # 2147483648 is too big to fit in type int

[int]$k = 0           # $k is constrained to int
$k = [int]::MinValue  # $k is set to -2147483648
--$k                  # -2147483649 is too small to fit, imp-def behavior

$x = $null            # target is unconstrained, $null goes to [int]0
--$x                  # value treated as int, 0 becomes -1

7.2.7 O operador unário -join

Sintaxe:

join-operator:
    dash join

dash: one of
    - (U+002D)
    EnDash character (U+2013)
    EmDash character (U+2014)
    Horizontal bar character (U+2015)

Descrição:

O operador unário -join produz uma cadeia de caracteres que é a concatenação do valor de um ou mais objetos designados pela expressão unária . (Um separador pode ser inserido usando a versão binária deste operador (§7.8.4.4).)

expressão unária pode ser um valor escalar ou uma coleção.

Exemplos:

-join (10, 20, 30)             # result is "102030"
-join (123, $false, 19.34e17)  # result is "123False1.934E+18"
-join 12345                    # result is "12345"
-join $null                    # result is ""

7.2.8 O operador unário -split

Sintaxe:

split-operator:
    dash split

dash: one of
    - (U+002D)
    EnDash character (U+2013)
    EmDash character (U+2014)
    Horizontal bar character (U+2015)

Descrição:

O operador unário -split divide uma ou mais cadeias de caracteres designadas pela expressão unária , retornando suas subpartes em uma matriz unidimensional restrita de cadeias de caracteres. Trata qualquer grupo contíguo de caracteres de espaço em branco como delimitador entre subpartes sucessivas. Uma cadeia de caracteres delimitador explícita pode ser especificada usando a versão binária desse operador (§7.8.4.5) ou suas duas variantes (§7.8).

O texto delimitador não está incluído nas cadeias de caracteres resultantes. O espaço em branco à esquerda e à direita na cadeia de caracteres de entrada é ignorado. Uma cadeia de caracteres de entrada vazia ou que contém espaço em branco resulta apenas em uma matriz de uma cadeia de caracteres, que está vazia.

expressão unária pode designar um valor escalar ou uma matriz de cadeias de caracteres.

Exemplos:

-split " red`tblue`ngreen " # 3 strings: "red", "blue", "green"
-split ("yes no", "up down") # 4 strings: "yes", "no", "up", "down"
-split " " # 1 (empty) string

7.2.9 Operador cast

Descrição:

Esse operador converte explicitamente (§6) o valor designado por expressão unária para o tipo designado por tipo literal (§7.1.10). Se type-literal for diferente de nulo, o tipo do resultado será o tipo nomeado e o valor será o valor após a conversão. Se type-literal for nulo, nenhum objeto será gravado no pipeline e não haverá resultados.

Quando uma expressão de qualquer tipo é convertida para esse mesmo tipo, o tipo e o valor resultantes correspondem ao tipo e valor da expressão unária .

Esse operador é associado à direita.

Exemplos:

[bool]-10        # a bool with value True
[int]-10.70D     # a decimal with value -10
[int]10.7        # an int with value 11
[long]"+2.3e+3"  # a long with value 2300
[char[]]"Hello"  # an array of 5 char with values H, e, l, l, and o.

7.3 Operador de vírgula binária

Sintaxe:

array-literal-expression:
    unary-expression , new-lines~opt~ array-literal-expression

Descrição:

O operador de vírgula binária cria uma matriz unidimensional cujos elementos são os valores designados por seus operandos, em ordem lexical. A matriz tem um tipo irrestrito.

Exemplos:

2,4,6                    # Length 3; values 2,4,6
(2,4),6                  # Length 2; values [object[]],int
(2,4,6),12,(2..4)        # Length 3; [object[]],int,[object[]]
2,4,6,"red",$null,$true  # Length 6

A adição de parênteses de agrupamento a determinadas expressões de vírgula binárias não documenta a precedência padrão; em vez disso, ele altera o resultado.

7.4 Operador range

Sintaxe:

range-expression:
    unary-expression .. new-lines~opt~ unary-expression

Descrição:

Uma expressão de intervalo cria uma matriz unidimensional sem restrições cujos elementos são os valores da variável int sequência especificada pelos limites do intervalo. Os valores designados pelos operandos são convertidos em int, se necessário (§6,4). O operando que designa o valor inferior após a conversão é o de limite inferior, enquanto o operando que designa o valor mais alto após a conversão é o limite superior. Ambos os limites podem ser os mesmos, nesse caso, a matriz resultante tem comprimento 1. Se o operando à esquerda designar o limite inferior, a sequência será em ordem crescente. Se o operando esquerdo indicar o limite superior, a sequência encontra-se em ordem decrescente.

Conceitualmente, esse operador é um atalho para a sequência de operadores de vírgula binária correspondente. Por exemplo, o intervalo 5..8 também pode ser gerado usando 5,6,7,8. No entanto, se uma sequência crescente ou decrescente for necessária sem ter uma matriz, uma implementação poderá evitar a geração de uma matriz real. Por exemplo, em foreach ($i in 1..5) { ... }, nenhuma matriz precisa ser criada.

Uma expressão de intervalo pode ser usada para especificar uma fatia de matriz (§9.9).

Exemplos:

1..10        # ascending range 1..10
-495..-500   # descending range -495..-500
16..16       # sequence of 1

$x = 1.5
$x..5.40D    # ascending range 2..5

$true..3     # ascending range 1..3
-2..$null    # ascending range -2..0
0xf..0xa     # descending range 15..10

Operador de formato 7.5

Sintaxe:

format-expression:
    format-specification-string format-operator new-lines~opt~ range-expression

format-operator:
    dash f

dash:
    - (U+002D)
    EnDash character (U+2013)
    EmDash character (U+2014)
    Horizontal bar character (U+2015)

Descrição:

Uma format-expression formata um ou mais valores designados por range-expression de acordo com format-specification-string designada por format-expression. As posições dos valores designados pela expressão de intervalo são numeradas a partir de zero e aumentam em ordem lexical. O resultado tem o tipo string.

Uma cadeia de caracteres de especificação de formato pode conter zero ou mais especificações de formato cada uma com o seguinte formulário:

{N [ ,M ][ : FormatString ]}

N representa uma posição de valor de range-expression (obrigatória), M representa a largura de exibição mínima (opcional) e FormatString indica o formato (opcional). Se a largura de um valor formatado exceder a largura especificada, a largura será aumentada adequadamente. Os valores cujas posições não são referenciadas em FormatString são ignorados após serem avaliados para quaisquer efeitos colaterais. Se N se referir a uma posição inexistente, o comportamento será definido pela implementação. O valor do tipo $null e void são formatados como cadeias de caracteres vazias. As matrizes são formatadas como para a subexpressão (§7.1.6). Para incluir os caracteres { e } em uma especificação de formato sem que eles sejam interpretados como delimitadores de formato, escreva-os como {{ e }}, respectivamente.

Para obter uma definição completa das especificações de formato, consulte o tipo System.IFormattable em Ecma Technical Report TR/84.

Exemplos:

"__{0,3}__" -f 5                         # __ 5__
"__{0,-3}__" -f 5                        # __5 __
"__{0,3:000}__" -f 5                     # __005__
"__{0,5:0.00}__" -f 5.0                  # __ 5.00__
"__{0:C}__" -f 1234567.888               # __$1,234,567.89__
"__{0:C}__" -f -1234.56                  # __($1,234.56)__
"__{0,12:e2}__" -f 123.456e2             # __ 1.23e+004__
"__{0,-12:p}__" -f -0.252                # __-25.20 % __

$i = 5; $j = 3
"__{0} + {1} <= {2}__" -f $i,$j,($i+$j)  # __5 + 3 <= 8__

$format = "__0x{0:X8}__"
$format -f 65535                         # __0x0000FFFF__

Em uma especificação de formato, se N referir-se a uma posição inexistente, um FormatError será gerado.

7.6 Operadores multiplicativos

Sintaxe:

multiplicative-expression:
    multiplicative-expression * new-lines~opt~ format-expression
    multiplicative-expression / new-lines~opt~ format-expression
    multiplicative-expression % new-lines~opt~ format-expression

7.6.1 Multiplicação

Descrição:

O resultado do operador de multiplicação * é o produto dos valores designados pelos dois operandos após a aplicação das conversões aritméticas usuais (§6,15).

Esse operador é associativo à esquerda.

Exemplos:

12 * -10L      # long result -120
-10.300D * 12  # decimal result -123.600
10.6 * 12      # double result 127.2
12 * "0xabc"   # int result 32976

7.6.2 Replicação de cadeia de caracteres

Descrição:

Quando o operando esquerdo designa uma cadeia de caracteres, o operador binário * cria uma nova cadeia de caracteres que contém a cadeia designada pelo operando esquerdo replicada o número de vezes determinado pelo valor do operando direito, convertido para o tipo inteiro (§6.4).

Esse operador é associativo à esquerda.

Exemplos:

"red" * "3"       # string replicated 3 times
"red" * 4         # string replicated 4 times
"red" * 0         # results in an empty string
"red" * 2.3450D   # string replicated twice
"red" * 2.7       # string replicated 3 times

7.6.3 Replicação de matriz

Descrição:

Quando o operando à esquerda designa uma matriz, o operador binário * cria uma nova matriz unidimensional sem restrições que contém o valor designado pelo operando à esquerda replicado o número de vezes designado pelo valor do operando à direita, conforme convertido em tipo inteiro (§6.4). Uma contagem de replicação de zero resulta em uma matriz de comprimento 1. Se o operando esquerdo designar uma matriz multidimensional, ela será achatada (§9.12) antes de ser utilizada.

Esse operador é associativo à esquerda.

Exemplos:

$a = [int[]](10,20)              # [int[]], Length 2*1
$a * "3"                         # [object[]], Length 2*3
$a * 4                           # [object[]], Length 2*4
$a * 0                           # [object[]], Length 2*0
$a * 2.3450D                     # [object[]], Length 2*2
$a * 2.7                         # [object[]], Length 2*3
(New-Object 'float[,]' 2,3) * 2  # [object[]], Length 2*2

7.6.4 Divisão

Descrição:

O resultado do operador de divisão / é o quociente quando o valor designado pelo operando esquerdo é dividido pelo valor designado pelo operando direito após as conversões aritméticas usuais (§6,15) terem sido aplicadas.

Se for feita uma tentativa de executar a divisão inteira ou decimal por zero, um erro de terminação definido pela implementação é gerado.

Esse operador é associativo à esquerda.

Exemplos:

10/-10      # int result -1
12/-10      # double result -1.2
12/-10D     # decimal result 1.2
12/10.6     # double result 1.13207547169811
12/"0xabc"  # double result 0.00436681222707424

Se for feita uma tentativa de realizar uma divisão inteira ou decimal por zero, será gerada uma exceção RuntimeException.

7.6.5 Restante

Descrição:

O resultado do operador restante % é o restante quando o valor designado pelo operando esquerdo é dividido pelo valor designado pelo operando direito após as conversões aritméticas usuais (§6,15) terem sido aplicadas.

Se for feita uma tentativa de executar uma divisão de inteiro ou decimal por zero, um erro de encerramento definido pela implementação será gerado.

Exemplos:

10 % 3          # int result 1
10.0 % 0.3      # double result 0.1
10.00D % "0x4"  # decimal result 2.00

Se for feita uma tentativa de executar uma divisão de inteiro ou decimal por zero, uma exceção RuntimeException será gerada.

7.7 Operadores aditivos

Sintaxe:

additive-expression:
    primary-expression + new-lines~opt~ expression
    primary-expression dash new-lines~opt~ expression

dash: one of
    - (U+002D)
    EnDash character (U+2013)
    EmDash character (U+2014)
    Horizontal bar character (U+2015)

7.7.1 Adição

Descrição:

O resultado do operador de adição + é a soma dos valores designados pelos dois operandos depois que as conversões aritméticas usuais (§6,15) foram aplicadas.

Esse operador é associativo à esquerda.

Exemplos:

12 + -10L       # long result 2
-10.300D + 12   # decimal result 1.700
10.6 + 12       # double result 22.6
12 + "0xabc"    # int result 2760

7.7.2 Concatenação de cadeia de caracteres

Descrição:

Quando o operando à esquerda designa uma cadeia de caracteres, o operador binário + cria uma nova cadeia de caracteres que contém o valor designado pelo operando esquerdo seguido imediatamente pelos valores designados pelo operando direito convertidos para o tipo cadeia de caracteres (§6.8).

Esse operador é associativo à esquerda.

Exemplos:

"red" + "blue"      # "redblue"
"red" + "123"       # "red123"
"red" + 123         # "red123"
"red" + 123.456e+5  # "red12345600"
"red" + (20,30,40)  # "red20 30 40"

7.7.3 Concatenação de matriz

Descrição:

Quando o operando esquerdo designa uma matriz, o operador binário + cria uma nova matriz unidimensional não restrita que contém os elementos designados pelo operando esquerdo seguidos imediatamente pelos valores designados pelo operando à direita. Matrizes multidimensionais presentes em qualquer operando são niveladas (§9,12) antes de serem usadas.

Esse operador é associativo à esquerda.

Exemplos:

$a = [int[]](10,20)               # [int[]], Length 2
$a + "red"                        # [object[]], Length 3
$a + 12.5,$true                   # [object[]], Length 4
$a + (New-Object 'float[,]' 2,3)  # [object[]], Length 8
(New-Object 'float[,]' 2,3) + $a  # [object[]], Length 8

7.7.4 Concatenação de tabela de hash

Descrição:

Quando ambos os operandos designam Hashtables, o operador binário + cria um novo Hashtable que contém os elementos designados pelo operando esquerdo seguidos imediatamente pelos elementos designados pelo operando direito.

Se os Hashtables contiverem a mesma chave, um erro de término definido pela implementação será gerado.

Esse operador é associativo à esquerda.

Exemplos:

$h1 = @{ FirstName = "James"; LastName = "Anderson" }
$h2 = @{ Dept = "Personnel" }
$h3 = $h1 + $h2      # new Hashtable, Count = 3

Se os Hashtables contiverem a mesma chave, uma exceção do tipo BadOperatorArgument será gerada.

7.7.5 Subtração

Descrição:

O resultado do operador de subtração - é a diferença quando o valor designado pelo operando direito é subtraído do valor designado pelo operando esquerdo depois que as conversões aritméticas usuais (§6,15) foram aplicadas. O operador de subtração pode ser qualquer um dos caracteres de traço listados em §7.7.

Esse operador é associativo à esquerda.

Exemplos:

12 - -10L      # long result 22
-10.300D - 12  # decimal result -22.300
10.6 - 12      # double result -1.4
12 - "0xabc"   # int result -2736

7.8 Operadores de comparação

Sintaxe:

comparison-expression:
    primary-expression comparison-operator new-lines~opt~ expression

comparison-operator:
    equality-operator
    relational-operator
    containment-operator
    type-operator
    like-operator
    match-operator

Descrição:

O tipo do valor designado pelo operando esquerdo determina como o valor designado pelo operando direito é convertido (§6), se necessário, antes que a comparação seja feita.

Alguns operadores de comparação têm duas variantes, uma que diferencia maiúsculas de minúsculas (-c<operator>) e outra que não diferencia maiúsculas de minúsculas (-i<operator>). A versão -<operator> é equivalente a -i<operator>. A distinção entre maiúsculas e minúsculas é significativa apenas nas comparações de valores do tipo cadeia de caracteres. Em contextos de comparação que não são de cadeia de caracteres, as duas variantes se comportam da mesma forma.

Esses operadores são associativos à esquerda.

7.8.1 Igualdade e operadores relacionais

Sintaxe:

equality-operator: one of
    dash eq     dash ceq    dash ieq
    dash ne     dash cne    dash ine

dash:
    - (U+002D)
    EnDash character (U+2013)
    EmDash character (U+2014)
    Horizontal bar character (U+2015)

relational-operator: one of
    dash lt     dash clt    dash ilt
    dash le     dash cle    dash ile
    dash gt     dash cgt    dash igt
    dash ge     dash cge    dash ige

Descrição:

Há dois operadores de igualdade: igualdade (-eq) e desigualdade (-ne); e quatro operadores relacionais: menor que (-lt), menor ou igual a (-le), maior que (-gt) e maior que ou igual a (-ge). Cada uma delas tem duas variantes (§7,8).

Para que duas cadeias de caracteres sejam consideradas iguais, elas devem ter o mesmo comprimento, conteúdo e caso das letras, se for o caso.

Se o valor designado pelo operando esquerdo não for uma coleção, o resultado terá o tipo bool. Caso contrário, o resultado é uma matriz unidimensional possivelmente vazia sem restrições que contém os elementos da coleção que testam True quando comparado ao valor designado pelo operando direito.

Exemplos:

10 -eq "010"           # True, int comparison
"010" -eq 10           # False, string comparison
"RED" -eq "Red"        # True, case-insensitive comparison
"RED" -ceq "Red"       # False, case-sensitive comparison
"ab" -lt "abc"         # True

10,20,30,20,10 -ne 20  # 10,30,10, Length 3
10,20,30,20,10 -eq 40  # Length 0
10,20,30,20,10 -ne 40  # 10,20,30,20,10, Length 5
10,20,30,20,10 -gt 25  # 30, Length 1
0,1,30 -ne $true       # 0,30, Length 2
0,"00" -eq "0"         # 0 (int), Length 1

7.8.2 Operadores de contenção

Sintaxe:

containment-operator: one of
    dash contains       dash ccontains      dash icontains
    dash notcontains    dash cnotcontains   dash inotcontains
    dash in             dash cin            dash iin
    dash notin          dash cnotin         dash inotin

dash:
    - (U+002D)
    EnDash character (U+2013)
    EmDash character (U+2014)
    Horizontal bar character (U+2015)

Descrição:

Há quatro operadores de contenção: contains (-contains), does-not-contain (-notcontains), em (-in) e not-in (-notin). Cada uma delas tem duas variantes (§7,8).

Os operadores de contenção retornam um resultado do tipo bool que indica se um valor ocorre (ou não ocorre) pelo menos uma vez nos elementos de uma matriz. Com -contains e -notcontains, o valor é designado pelo operando à direita e a matriz é designada pelo operando esquerdo. Com -in e -notin, os operadores são invertidos. O valor é designado pelo operando esquerdo e a matriz é designada pelo operando à direita.

Para fins desses operadores, se o operando de matriz tiver um valor escalar, o valor escalar será tratado como uma matriz de um elemento.

Exemplos:

10,20,30,20,10 -contains 20     # True
10,20,30,20,10 -contains 42.9   # False
10,20,30 -contains "10"         # True
"10",20,30 -contains 10         # True
"010",20,30 -contains 10        # False
10,20,30,20,10 -notcontains 15  # True
"Red",20,30 -ccontains "RED"    # False

7.8.3 Teste de tipo e operadores de conversão

Sintaxe:

type-operator: one of
    dash is
    dash as

dash:
    - (U+002D)
    EnDash character (U+2013)
    EmDash character (U+2014)
    Horizontal bar character (U+2015)

Descrição:

O operador de tipo -is testa se o valor designado pelo operando à esquerda tem o tipo ou é derivado de um tipo que tem o tipo, designado pelo operando à direita. O operando direito deve designar um tipo ou um valor que possa ser convertido em um tipo (como uma cadeia de caracteres que nomeia um tipo). O tipo de resultado é bool. O operador de tipo -isnot retorna a negação lógica da forma correspondente de -is.

O operador de tipo -as tenta converter o valor designado pelo operando esquerdo para o tipo designado pelo operando à direita. O operando direito deve designar um tipo ou um valor que possa ser convertido em um tipo (como uma cadeia de caracteres que nomeia um tipo). Se a conversão falhar, $null será retornado; caso contrário, o valor convertido é retornado e o tipo de retorno desse resultado é o tipo de runtime do valor convertido.

Exemplos:

$a = 10            # value 10 has type int
$a -is [int]       # True

$t = [int]
$a -isnot $t       # False
$a -is "int"       # True
$a -isnot [double] # True

$x = [int[]](10,20)
$x -is [int[]]     # True

$a = "abcd"        # string is derived from object
$a -is [object]    # True

$x = [double]
foreach ($t in [int],$x,[decimal],"string") {
    $b = (10.60D -as $t) * 2  # results in int 22, double 21.2
}                             # decimal 21.20, and string "10.6010.60"

7.8.4 Operadores de correspondência de padrões e manipulação de texto

7.8.4.1 Os operadores -like e -notlike

Sintaxe:

like-operator: one of
    dash like       dash clike      dash ilike
    dash notlike    dash cnotlike   dash inotlike

dash:
    - (U+002D)
    EnDash character (U+2013)
    EmDash character (U+2014)
    Horizontal bar character (U+2015)

Descrição:

Se o operando à esquerda não designar uma coleção, o resultado terá o tipo bool. Caso contrário, o resultado é uma matriz unidimensional possivelmente vazia sem restrições que contém os elementos da coleção que testam True quando comparado ao valor designado pelo operando direito. O operando à direita pode designar uma cadeia de caracteres que contém expressões curinga (seção 3.15). Esses operadores têm duas variantes (§7,8).

Exemplos:

"Hello" -like "h*"                   # True, starts with h
"Hello" -clike "h*"                  # False, does not start with lowercase h
"Hello" -like "*l*"                  # True, has an l in it somewhere
"Hello" -like "??l"                  # False, no length match

"-abc" -like "[-xz]*"                # True, - is not a range separator
"#$%\^&" -notlike "*[A-Za-z]"        # True, does not end with alphabetic character
"He" -like "h[aeiou]?*"              # False, need at least 3 characters
"When" -like "*[?]"                  # False, ? is not a wildcard character
"When?" -like "*[?]"                 # True, ? is not a wildcard character

"abc","abbcde","abcgh" -like "abc*"  # object[2], values
"abc" and "abcgh"

7.8.4.2 Os operadores -match e -notmatch

Sintaxe:

match-operator: one of
    dash match      dash cmatch     dash imatch
    dash notmatch   dash cnotmatch  dash inotmatch

dash:
    - (U+002D)
    EnDash character (U+2013)
    EmDash character (U+2014)
    Horizontal bar character (U+2015)

Descrição:

Se o operando esquerdo não designar uma coleção, o resultado terá o tipo bool e, se esse resultado for $true, os elementos do $matches Hashtable serão definidos para as cadeias de caracteres que correspondem (ou não correspondem) ao valor designado pelo operando à direita. Caso contrário, o resultado é uma matriz unidimensional sem restrições possivelmente vazia que contém os elementos da coleção que testam True quando comparado ao valor designado pelo operando direito e $matches não está definido. O operando direito pode designar uma cadeia de caracteres que contém expressões regulares (§3.16), nesse caso, ela é conhecida como um padrão . Esses operadores têm duas variantes (§7,8).

Esses operadores dão suporte a submatches (§7.8.4.6).

Exemplos:

"Hello" -match ".l"                    # True, $matches key/value is 0/"el"
"Hello" -match '\^h.*o$'               # True, $matches key/value is
0/"Hello"
"Hello" -cmatch '\^h.*o$'              # False, $matches not set
"abc\^ef" -match ".\\\^e"              # True, $matches key/value is 0/"c\^e"

"abc" -notmatch "[A-Za-z]"             # False
"abc" -match "[\^A-Za-z]"              # False
"He" -match "h[aeiou]."                # False, need at least 3 characters
"abc","abbcde","abcgh" -match "abc.*"  # Length is 2, values "abc", "abcgh"

7.8.4.3 O operador -replace

Sintaxe:

binary-replace-operator: one of
    dash replace    dash creplace   dash ireplace

dash:
    - (U+002D)
    EnDash character (U+2013)
    EmDash character (U+2014)
    Horizontal bar character (U+2015)

Descrição:

O operador -replace permite a substituição de texto em uma ou mais cadeias de caracteres designadas pelo operando esquerdo usando os valores designados pelo operando à direita. Esse operador tem duas variantes (§7,8). O operando à direita tem uma das seguintes formas:

• A cadeia de caracteres a ser localizada, que pode conter expressões regulares (§3.16). Nesse caso, a cadeia de caracteres de substituição é implicitamente "".
• Uma matriz de dois objetos que contêm a cadeia de caracteres a ser localizada, seguida pela cadeia de caracteres de substituição.

Se o operando à esquerda designar uma cadeia de caracteres, o resultado terá o tipo cadeia de caracteres. Se o operando esquerdo designar uma matriz unidimensional de cadeia de caracteres, o resultado será uma matriz unidimensional não restrita, cujo comprimento é o mesmo da matriz do operando esquerdo, contendo as cadeias de caracteres de entrada após a conclusão da substituição.

Esse operador dá suporte a submatches (§7.8.4.6).

Exemplos:

"Analogous","an apple" -replace "a","*"      # "*n*logous","*n *pple"
"Analogous" -creplace "[aeiou]","?"          # "An?l?g??s"
"Analogous","an apple" -replace '\^a',"%%A"  # "%%Analogous","%%An apple"
"Analogous" -replace "[aeiou]",'$&$&'        # "AAnaaloogoouus"

7.8.4.4 O operador de -join binário

Sintaxe:

binary-join-operator: one of
    dash join

dash:
    - (U+002D)
    EnDash character (U+2013)
    EmDash character (U+2014)
    Horizontal bar character (U+2015)

Descrição:

O operador binário -join produz uma cadeia de caracteres que é a concatenação do valor de um ou mais objetos designados pelo operando esquerdo após terem sido convertidos em cadeia de caracteres (§6.7), se necessário. A cadeia de caracteres designada pelo operando direito é usada para separar os valores (possivelmente vazios) na cadeia de caracteres resultante.

O operando esquerdo pode ser um valor escalar ou uma coleção.

Exemplos:

(10, 20, 30) -join "\|"    # result is "10\|20\|30"
12345 -join ","            # result is "12345", no separator needed
($null,$null) -join "<->"  # result is "<->", two zero-length values

7.8.4.5 O operador de -split binário

Sintaxe:

binary-split-operator: one of
    dash split      dash csplit     dash isplit

dash:
    - (U+002D)
    EnDash character (U+2013)
    EmDash character (U+2014)
    Horizontal bar character (U+2015)

Descrição:

O operador binário -split divide uma ou mais cadeias de caracteres designadas pelo operando à esquerda, retornando suas subpartes em uma matriz unidimensional restrita de cadeia de caracteres. Esse operador tem duas variantes (§7,8). O operando esquerdo pode designar um valor escalar ou uma matriz de cadeias de caracteres. O operando à direita tem uma das seguintes formas:

• Uma cadeia de caracteres delimitadora
• Uma matriz de dois objetos que contém uma cadeia de caracteres delimitadora seguida por uma contagem de divisão numérica
• Uma matriz de três objetos que contém uma cadeia de caracteres delimitadora, uma contagem de divisão numérica e uma cadeia de caracteres de opções
• Um bloco de script
• Uma matriz de dois objetos que contém um bloco de script seguido por uma contagem de divisão numérica

A cadeia de caracteres delimitador pode conter expressões regulares (§3.16). Ela é usada para localizar subpartes com as cadeias de caracteres de entrada. O delimitador não está incluído nas cadeias de caracteres resultantes. Se o operando esquerdo designar uma cadeia de caracteres vazia, isso resultará em um elemento de cadeia de caracteres vazio. Se a string delimitadora for vazia, ela será encontrada em cada posição de caractere nas strings de entrada.

Por padrão, todas as subparte das cadeias de caracteres de entrada são colocadas no resultado como elementos separados; no entanto, a contagem de divisão pode ser usada para modificar esse comportamento. Se essa contagem for negativa, zero ou maior ou igual ao número de subpartes em uma cadeia de caracteres de entrada, cada subparte entrará em um elemento separado. Se essa contagem for menor que o número de subpartes da cadeia de caracteres de entrada, haverá elementos de contagem no resultado, com o elemento final contendo todas as subpartes além da primeira contagem - 1 de subpartes.

Uma cadeia de caracteres de opções contém zero ou mais nomes de opção com cada par adjacente separado por uma vírgula. Os espaços em branco à esquerda, à direita e incorporados são ignorados. Os nomes de opção podem estar em qualquer ordem e diferenciam maiúsculas de minúsculas.

Se uma string de opções contiver o nome da opção SimpleMatch, ela também poderá conter o nome da opção IgnoreCase. Se uma cadeia de caracteres de opções contiver o nome da opção RegexMatch ou não contiver RegexMatch ou SimpleMatch, ela poderá conter qualquer nome de opção, exceto SimpleMatch. Entretanto, ele não deve conter tanto Multiline quanto Singleline.

Aqui está o conjunto de nomes de opção:

Opção	Descrição
CultureInvariant	Ignora diferenças culturais do idioma ao avaliar o delimitador.
ExplicitCapture	Ignora grupos de correspondências não nomeados para que apenas grupos de captura explícitos sejam retornados na lista de resultados.
IgnoreCase	Forçar a correspondência sem diferenciar maiúsculas e minúsculas, mesmo se -csplit for usado.
IgnorePatternWhitespace	Ignora espaços em branco sem escape e comentários marcados com o sinal de número (#).
Várias linhas	Esse modo reconhece o início e o fim das linhas e cadeias de caracteres. O modo padrão é Singleline.
RegexMatch	Use a correspondência de expressão regular para avaliar o delimitador. Esse é o padrão.
SimpleMatch	Use uma comparação de cadeia de caracteres simples ao avaliar o delimitador.
Linha única	Esse modo reconhece apenas o início e o fim das cadeias de caracteres. É o modo padrão.

O bloco de script (§7.1.8) especifica as regras para determinar o delimitador e deve ser avaliado como tipo bool.

Exemplos:

"one,forty two,," -split ","              # 5 strings: "one" "forty two" "" ""

"abc","de" -split ""                      # 9 strings: "" "a" "b" "c" "" "" "d" "e" ""

"ab,cd","1,5,7,8" -split ",", 2           # 4 strings: "ab" "cd" "1" "5,7,8"

"10X20x30" -csplit "X", 0, "SimpleMatch"  # 2 strings: "10" "20x30"

"analogous" -split "[AEIOU]", 0, "RegexMatch, IgnoreCase"
                                          # 6 strings: "" "n" "l" "g" "" "s"

"analogous" -split { $_ -eq "a" -or $_ -eq "o" }, 4
                                          # 4 strings: "" "n" "l" "gous"

7.8.4.6 Subcorrespondências

O padrão que está sendo correspondido por -match, -notmatch e -replace pode conter subpartes (chamadas subcorrespondências) delimitadas por parênteses. Considere o seguinte exemplo:

"red" -match "red"

O resultado é $true e a chave 0 de $matches contém "vermelho", aquela parte da cadeia de caracteres designada pelo operando esquerdo que correspondeu exatamente ao padrão designado pelo operando direito.

No exemplo a seguir, o padrão inteiro é uma subcorrespondência:

"red" -match "(red)"

Como antes, a chave 0 contém "red"; no entanto, a chave 1 também contém "red", que é a parte da cadeia de caracteres designada pelo operando à esquerda que correspondeu exatamente à subcorrespondência.

Considere o seguinte padrão, mais complexo:

"red" -match "((r)e)(d)"

Esse padrão permite subcorrespondências de "re", "r", "d" ou "red".

Novamente, a chave 0 contém "red". A chave 1 contém "re", a chave 2 contém "r" e a chave 3 contém "d". Os pares de chave/valor estão em ordem de correspondência da esquerda para a direita no padrão, com correspondências de cadeia de caracteres maiores anteriores às menores.

No caso de -replace, o texto de substituição pode acessar as subcorrespondências por meio de nomes no formato $n, em que a primeira correspondência é $1, a segunda é $3 e assim por diante. Por exemplo

"Monday morning" -replace '(Monday|Tuesday) (morning|afternoon|evening)','the $2 of $1'

A cadeia de caracteres resultante é "a manhã de segunda-feira".

Em vez de ter chaves $matches em índices baseados em zero, as subcorrespondências podem ser nomeadas usando o formato ?<*name*>. Por exemplo, "((r)e)(d)" pode ser escrito com três submatches nomeados, m1, m2e m3, da seguinte maneira: "(?<m1>(?<m2>r)e)(?<m3>d)".

7.8.5 Operadores de deslocamento

Sintaxe:

shift-operator: one of
    dash shl
    dash shr

dash:
    - (U+002D)
    EnDash character (U+2013)
    EmDash character (U+2014)
    Horizontal bar character (U+2015)

Descrição:

O operador shift left (-shl) e shift right (-shr) convertem o valor projetado pelo operando esquerdo em um tipo inteiro e o valor designado pelo operando direito para int, se necessário, usando as conversões aritméticas usuais (§6,15).

O operador deslocar à esquerda desloca o operando do lado esquerdo para a esquerda por um número de bits computados, conforme descrito abaixo. As posições de bits vazias de ordem baixa são definidas como zero.

O operador deslocar à direita desloca o operando do lado esquerdo para a direita por um número de bits computados, conforme descrito abaixo. Os bits de ordem inferior do operando à esquerda são descartados e os bits restantes são deslocados para a direita. Quando o operando à esquerda é um valor com sinal, as posições de bit vazias de ordem superior são definidas como zero se o operando à esquerda for não negativo, e definido como um se o operando à esquerda for negativo. Quando o operando à esquerda é um valor sem sinal, as posições de bit vazio de ordem superior são definidas como zero.

Quando o operando à esquerda tem o tipo int, a contagem do deslocamento é fornecida pelos cinco bits de ordem inferior do operando à direita. Quando o operando à direita tem o tipo long, a contagem do deslocamento é fornecida pelos seis bits de ordem inferior do operando à direita.

Exemplos:

0x0408 -shl 1             # int with value 0x0810
0x0408 -shr 3             # int with value 0x0081
0x100000000 -shr 0xfff81  # long with value 0x80000000

7.9 Operadores bit a bit

Sintaxe:

bitwise-expression:
    unary-expression -band new-lines~opt~ unary-expression
    unary-expression -bor new-lines~opt~ unary-expression
    unary-expression -bxor new-lines~opt~ unary-expression

Descrição:

O operador AND bit a bit -band, o operador OR bit a bit -bor, e o operador XOR bit a bit -bxor convertem os valores designados por seus operandos em tipos inteiros, se necessário, usando as conversões aritméticas usuais (§6.15). Após a conversão, se ambos os valores tiverem o tipo int, esse será o tipo do resultado. Caso contrário, se ambos os valores tiverem tipo longo, esse será o tipo do resultado. Se um valor tiver tipo int e o outro tiver tipo longo, o tipo do resultado será longo. Caso contrário, a expressão está mal formada. O resultado será o AND bit a bit, OR bit a bit ou XOR bit a bit, respectivamente, dos valores de operando possivelmente convertidos.

Esses operadores são associativos à esquerda. Eles serão comutativos se nenhum dos operandos contiver um efeito colateral.

Exemplos:

0x0F0F -band 0xFE    # int with value 0xE
0x0F0F -band 0xFEL   # long with value 0xE
0x0F0F -band 14.6    # long with value 0xF

0x0F0F -bor 0xFE     # int with value 0xFFF
0x0F0F -bor 0xFEL    # long with value 0xFFF
0x0F0F -bor 14.40D   # long with value 0xF0F

0x0F0F -bxor 0xFE    # int with value 0xFF1
0x0F0F -bxor 0xFEL   # long with value 0xFF1
0x0F0F -bxor 14.40D  # long with value 0xF01
0x0F0F -bxor 14.6    # long with value 0xF00

7.10 Operadores lógicos

Sintaxe:

logical-expression:
    unary-expression -and new-lines~opt~ unary-expression
    unary-expression -or new-lines~opt~ unary-expression
    unary-expression -xor new-lines~opt~ unary-expression

Descrição:

O operador AND lógico -and converte os valores designados por seus operandos em bool, se necessário (§6,2). O resultado será o AND lógico dos valores de operando possivelmente convertidos e terá o tipo bool. Se o operando à esquerda for avaliado como False, o operando à direita não será avaliado.

O operador OR lógico -or converte os valores designados por seus operandos em bool, se necessário (§6,2). O resultado será o OR lógico dos valores de operando possivelmente convertidos e terá o tipo bool. Se o operando à esquerda for avaliado como True, o operando à direita não será avaliado.

O operador XOR lógico -xor converte os valores designados por seus operandos em bool (§6.2). O resultado é o XOR lógico dos valores dos operandos possivelmente convertidos e tem o tipo bool.

Esses operadores são associativos à esquerda.

Exemplos:

$j = 10
$k = 20
($j -gt 5) -and (++$k -lt 15)   # True -and False -> False
($j -gt 5) -and ($k -le 21)     # True -and True -> True
($j++ -gt 5) -and ($j -le 10)   # True -and False -> False
($j -eq 5) -and (++$k -gt 15)   # False -and True -> False

$j = 10
$k = 20
($j++ -gt 5) -or (++$k -lt 15)  # True -or False -> True
($j -eq 10) -or ($k -gt 15)     # False -or True -> True
($j -eq 10) -or (++$k -le 20)   # False -or False -> False

$j = 10
$k = 20
($j++ -gt 5) -xor (++$k -lt 15) # True -xor False -> True
($j -eq 10) -xor ($k -gt 15)    # False -xor True -> True
($j -gt 10) -xor (++$k -le 25)  # True -xor True -> False

7.11 Operadores de atribuição

Sintaxe:

assignment-expression:
    expression assignment-operator statement

assignment-operator: *one of
    =   dash =   +=   *=   /=   %=

Descrição:

Um operador de atribuição armazena um valor no local gravável designado por expression. Para uma discussão sobre assignment-operator= consulte §7.11.1. Para uma discussão sobre todos os outros operadores de atribuição, consulte §7.11.2.

Uma expressão de atribuição tem o valor designado por expression após a atribuição ter sido realizada; no entanto, essa expressão de atribuição em si não designa um local gravável. Se expressão for restrita por tipo (§5.3), o tipo usado nessa restrição será o tipo do resultado; caso contrário, o tipo do resultado é o tipo após as conversões aritméticas usuais (§6,15) terem sido aplicadas.

Esse operador é associado à direita.

7.11.1 Atribuição simples

Descrição:

Na atribuição simples (=), o valor designado por statement substitui o valor armazenado no local gravável designado por expression. No entanto, se expression designar uma chave inexistente em uma Tabela de hash, essa chave será adicionada à Tabela de hash com um valor associado do valor designado por statement.

Conforme mostrado pela gramática, a expressão pode designar uma lista de locais graváveis, separada por vírgulas. Isso é conhecido como atribuição múltipla. declaração designa uma lista de um ou mais valores separados por vírgulas. As vírgulas em qualquer lista de operandos fazem parte da sintaxe de múltiplas atribuições e não representam o operador de vírgula binária. Os valores são obtidos da lista designada por statement em ordem lexical e armazenados no local gravável correspondente designado por expression. Se a lista designada pela instrução tiver menos valores do que os locais graváveis da expressão , os locais em excesso assumirão o valor $null. Se a lista designada por statement tiver mais valores do que os locais graváveis de expression, todos, exceto o local de expression mais à direita, assumirão o valor de statement correspondente e o local de expression mais à direita se tornará uma matriz unidimensional irrestrita com todos os valores de statement restantes como elementos.

Para instruções que têm valores (seção 8.1.2), statement pode ser uma instrução.

Exemplos:

$a = 20; $b = $a + 12L             # $b has type long, value 22
$hypot = [Math]::Sqrt(3*3 + 4*4)   # type double, value 5
$a = $b = $c = 10.20D              # all have type decimal, value 10.20
$a = (10,20,30),(1,2)              # type [object[]], Length 2
[int]$x = 10.6                     # type int, value 11
[long]$x = "0xabc"                 # type long, value 0xabc
$a = [float]                       # value type literal [float]
$i,$j,$k = 10,"red",$true          # $i is 10, $j is "red", $k is True
$i,$j = 10,"red",$true             # $i is 10, $j is [object[]], Length 2
$i,$j = (10,"red"),$true           # $i is [object[]], Length 2, $j is True
$i,$j,$k = 10                      # $i is 10, $j is $null, $k is $null

$h = @{}
[int] $h.Lower, [int] $h.Upper = -split "10 100"

$h1 = @{ FirstName = "James"; LastName = "Anderson"; IDNum = 123 }
$h1.Dept = "Finance"               # adds element Finance
$h1["City"] = "New York"           # adds element City

[int]$Variable:v = 123.456         # v takes on the value 123
${E:output.txt} = "a"              # write text to the given file
$Env:MyPath = "x:\data\file.txt"   # define the environment variable
$Function:F = { param ($a, $b) "Hello there, $a, $b" }
F 10 "red"                         # define and invoke a function
function Demo { "Hi there from inside Demo" }
$Alias:A = "Demo"                  # create alias for function Demo
A                                  # invoke function Demo via the alias

7.11.2 Atribuição composta

Descrição:

Uma atribuição composta tem o formulário E1 op= E2e é equivalente à expressão de atribuição simples E1 = E1 op (E2) exceto que, no caso de atribuição composta, a expressão E1 é avaliada apenas uma vez. Se expressão for restrita por tipo (§5.3), o tipo usado nessa restrição será o tipo do resultado; caso contrário, o tipo do resultado é determinado por op. Para *=, consulte §7.6.1, §7.6.2, §7.6.3; para /=, consulte §7.6.4; para %=, consulte §7.6.5; para +=, consulte §7.7.1, §7.7.2, §7.7.3; para -=, consulte §7.7.5.

Nota

Um operando que designa um valor não treinado do tipo numérico pode ter seu tipo alterado por um operador de atribuição quando o resultado é armazenado.

Exemplos:

$a = 1234; $a *= (3 + 2)  # type is int, value is 1234 * (3 + 2)
$b = 10,20,30             # $b[1] has type int, value 20
$b[1] /= 6                # $b[1] has type double, value 3.33...

$i = 0
$b = 10,20,30
$b[++$i] += 2             # side effect evaluated only once

[int]$Variable:v = 10     # v takes on the value 10
$Variable:v -= 3          # 3 is subtracted from v

${E:output.txt} = "a"     # write text to the given file
${E:output.txt} += "b"    # append text to the file giving ab
${E:output.txt} *= 4      # replicate ab 4 times giving abababab

7.12 Operadores de redirecionamento

Sintaxe:

pipeline:
    expression redirections~opt~ pipeline-tail~opt~
    command verbatim-command-argument~opt~ pipeline-tail~opt~

redirections:
    redirection
    redirections redirection

redirection:
    merging-redirection-operator
    file-redirection-operator redirected-file-name

redirected-file-name:
    command-argument
    primary-expression

file-redirection-operator: one of
    >   >>   2>   2>>   3>   3>>   4>   4>>
    5>  5>>  6>   6>>   >    >>    <

merging-redirection-operator: one of
    >&1   2>&1   3>&1   4>&1   5>&1   6>&1
    >&2   1>&2   3>&2   4>&2   5>&2   6>&2

Descrição:

O operador de redirecionamento > pega a saída padrão do pipeline e a redireciona para o local designado por redirected-file-name, sobrescrevendo o conteúdo atual desse local.

O operador de redirecionamento >> pega a saída padrão do pipeline e a redireciona para o local designado por redirected-file-name, acrescentando ao conteúdo atual desse local, se houver. Se esse local não existir, ele será criado.

O operador de redirecionamento com o formato n> pega a saída do fluxo n do pipeline e a redireciona para o local designado por redirected-file-name, sobrescrevendo o conteúdo atual desse local.

O operador de redirecionamento com o formato n>> pega a saída do fluxo n do pipeline e a redireciona para o local designado por redirected-file-name, acrescentando ao conteúdo atual desse local, se houver. Se esse local não existir, ele será criado.

O operador de redirecionamento com o formato m>&n grava a saída do fluxo m no mesmo local que o fluxo n.

Veja a seguir os fluxos válidos:

Fluxo	Descrição
1	Fluxo de saída padrão
2	Fluxo de saída de erro
3	Fluxo de saída de aviso
4	Fluxo de saída detalhado
5	Fluxo de saída de depuração
*	Fluxos de saída padrão, saída de erro, saída de aviso, saída detalhada e saída de depuração

Os operadores de redirecionamento 1>&2, 6>, 6>> e < são reservados para uso futuro.

Se o valor de saída de redirected-file-name for $null, a saída será descartada.

Normalmente, o valor de uma expressão que contém um efeito colateral de nível superior não é gravado no pipeline, a menos que essa expressão esteja entre parênteses. No entanto, se essa expressão for o operando esquerdo de um operador que redireciona a saída padrão, o valor será gravado.

Exemplos:

$i = 200                       # pipeline gets nothing
$i                             # pipeline gets result
$i > output1.txt               # result redirected to named file
++$i >> output1.txt            # result appended to named file
type file1.txt 2> error1.txt   # error output redirected to named file
type file2.txt 2>> error1.txt  # error output appended to named file
dir -Verbose 4> verbose1.txt   # verbose output redirected to named file

# Send all output to output2.txt
dir -Verbose -Debug -WarningAction Continue *> output2.txt

# error output redirected to named file, verbose output redirected
# to the same location as error output
dir -Verbose 4>&2 2> error2.txt