Compartilhar via

Set-PSReadLineOption

  • Referência
Módulo:
PSReadLine

Personaliza o comportamento da edição de linha de comando no PSReadLine.

Syntax

Set-PSReadLineOption
   [-EditMode <EditMode>]
   [-ContinuationPrompt <String>]
   [-HistoryNoDuplicates]
   [-AddToHistoryHandler <System.Func`2[System.String,System.Object]>]
   [-CommandValidationHandler <System.Action`1[System.Management.Automation.Language.CommandAst]>]
   [-HistorySearchCursorMovesToEnd]
   [-MaximumHistoryCount <Int32>]
   [-MaximumKillRingCount <Int32>]
   [-ShowToolTips]
   [-ExtraPromptLineCount <Int32>]
   [-DingTone <Int32>]
   [-DingDuration <Int32>]
   [-BellStyle <BellStyle>]
   [-CompletionQueryItems <Int32>]
   [-WordDelimiters <String>]
   [-HistorySearchCaseSensitive]
   [-HistorySaveStyle <HistorySaveStyle>]
   [-HistorySavePath <String>]
   [-AnsiEscapeTimeout <Int32>]
   [-PromptText <String[]>]
   [-ViModeIndicator <ViModeStyle>]
   [-ViModeChangeHandler <ScriptBlock>]
   [-PredictionSource <PredictionSource>]
   [-PredictionViewStyle <PredictionViewStyle>]
   [-Colors <Hashtable>]
   [<CommonParameters>]

Description

O Set-PSReadLineOption cmdlet personaliza o comportamento do módulo PSReadLine quando você está editando a linha de comando. Para exibir as configurações do PSReadLine , use Get-PSReadLineOption.

As opções definidas por esse comando se aplicam somente à sessão atual. Para persistir as opções, adicione-as a um script de perfil. Para obter mais informações, consulte about_Profiles e Personalizando seu ambiente de shell.

Exemplos

Exemplo 1: definir cores de primeiro plano e tela de fundo

Este exemplo define PSReadLine para exibir o token De comentário com texto em primeiro plano verde em uma tela de fundo cinza. Na sequência de escape usada no exemplo, 32 representa a cor de primeiro plano e 47 representa a cor da tela de fundo.

Set-PSReadLineOption -Colors @{ "Comment"="`e[32;47m" }

Você pode optar por definir apenas uma cor de texto em primeiro plano. Por exemplo, uma cor de texto de primeiro plano verde brilhante para o token de comentário : "Comment"="`e[92m".

Exemplo 2: Definir estilo de sino

Neste exemplo, o PSReadLine responderá a erros ou condições que exigem atenção do usuário. O BellStyle está definido para emitir um bipe audível a 1221 Hz por 60 ms.

Set-PSReadLineOption -BellStyle Audible -DingTone 1221 -DingDuration 60

Observação

Esse recurso pode não funcionar em todos os hosts em plataformas.

Exemplo 3: definir várias opções

Set-PSReadLineOption pode definir várias opções com uma tabela de hash.

$PSReadLineOptions = @{
    EditMode = "Emacs"
    HistoryNoDuplicates = $true
    HistorySearchCursorMovesToEnd = $true
    Colors = @{
        "Command" = "#8181f7"
    }
}
Set-PSReadLineOption @PSReadLineOptions

A $PSReadLineOptions tabela de hash define as chaves e os valores. Set-PSReadLineOption usa as chaves e os valores com @PSReadLineOptions para atualizar as opções PSReadLine .

Você pode exibir as chaves e os valores que inserem o nome da tabela de hash na $PSReadLineOptions linha de comando do PowerShell.

Exemplo 4: definir várias opções de cor

Este exemplo mostra como definir mais de um valor de cor em um único comando.

Set-PSReadLineOption -Colors @{
  Command            = 'Magenta'
  Number             = 'DarkGray'
  Member             = 'DarkGray'
  Operator           = 'DarkGray'
  Type               = 'DarkGray'
  Variable           = 'DarkGreen'
  Parameter          = 'DarkGreen'
  ContinuationPrompt = 'DarkGray'
  Default            = 'DarkGray'
}

Exemplo 5: Definir valores de cor para vários tipos

Este exemplo mostra três métodos diferentes para definir a cor dos tokens exibidos em PSReadLine.

Set-PSReadLineOption -Colors @{
 # Use a ConsoleColor enum
 "Error" = [ConsoleColor]::DarkRed

 # 24 bit color escape sequence
 "String" = "$([char]0x1b)[38;5;100m"

 # RGB value
 "Command" = "#8181f7"
}

Exemplo 6: Usar ViModeChangeHandler para exibir alterações no modo Vi

Este exemplo emite um escape de VT de alteração de cursor em resposta a uma alteração no modo Vi .

function OnViModeChange {
    if ($args[0] -eq 'Command') {
        # Set the cursor to a blinking block.
        Write-Host -NoNewLine "`e[1 q"
    } else {
        # Set the cursor to a blinking line.
        Write-Host -NoNewLine "`e[5 q"
    }
}
Set-PSReadLineOption -ViModeIndicator Script -ViModeChangeHandler $Function:OnViModeChange

A função OnViModeChange define as opções de cursor para os modos Vi : insert e command. ViModeChangeHandler usa o Function: provedor para referenciar OnViModeChange como um objeto de bloco de script.

Para obter mais informações, consulte about_Providers.

Exemplo 7: Usar HistoryHandler para filtrar comandos adicionados ao histórico

O exemplo a seguir mostra como usar o AddToHistoryHandler para evitar salvar qualquer comando git no histórico.

$ScriptBlock = {
    Param([string]$line)

    if ($line -match "^git") {
        return $false
    } else {
        return $true
    }
}

Set-PSReadLineOption -AddToHistoryHandler $ScriptBlock

O scriptblock retornará $false se o comando tiver começado com git. Isso tem o mesmo efeito que retornar a SkipAdding enumeração AddToHistory. Se o comando não começar com git, o manipulador retornará $true e PSReadLine salvará o comando no histórico.

Exemplo 8: Usar CommandValidationHandler para validar um comando antes de sua execução

Este exemplo mostra como usar o parâmetro CommandValidationHandler para executar um comando de validação antes de ser executado. O exemplo verifica especificamente o comando git com o subcomando cmt e o substitui pelo nome commitcompleto . Dessa forma, você pode criar aliases abreviados para subcomandos.

# Load the namespace so you can use the [CommandAst] object type
using namespace System.Management.Automation.Language

Set-PSReadLineOption -CommandValidationHandler {
    param([CommandAst]$CommandAst)

    switch ($CommandAst.GetCommandName()) {
        'git' {
            $gitCmd = $CommandAst.CommandElements[1].Extent
            switch ($gitCmd.Text) {
                'cmt' {
                    [Microsoft.PowerShell.PSConsoleReadLine]::Replace(
                        $gitCmd.StartOffset, $gitCmd.EndOffset - $gitCmd.StartOffset, 'commit')
                }
            }
        }
    }
}
# This checks the validation script when you hit enter
Set-PSReadLineKeyHandler -Chord Enter -Function ValidateAndAcceptLine

Exemplo 9: usando o parâmetro PromptText

Quando há um erro de análise, o PSReadLine altera uma parte do prompt vermelho. O parâmetro PromptText informa ao PSReadLine a parte da cadeia de caracteres de prompt a ser vermelha.

Por exemplo, o exemplo a seguir cria um prompt que contém o caminho atual seguido pelo caractere maior que (>) e um espaço.

function prompt { "PS $pwd> " }`
Set-PSReadLineOption -PromptText '> ' # change the '>' character red
Set-PSReadLineOption -PromptText '> ', 'X ' # replace the '>' character with a red 'X'

A primeira cadeia de caracteres é a parte da cadeia de caracteres de prompt que você deseja deixar vermelho quando houver um erro de análise. A segunda cadeia de caracteres é uma cadeia de caracteres alternativa a ser usada para quando houver um erro de análise.

Parâmetros

-AddToHistoryHandler

Especifica um ScriptBlock que controla como os comandos são adicionados ao histórico do PSReadLine .

O ScriptBlock recebe a linha de comando como entrada.

O ScripBlock deve retornar um membro da enumeração AddToHistoryOption , o nome da cadeia de caracteres de um desses membros ou um valor booliano. A lista a seguir descreve os valores possíveis e seus efeitos.

  • MemoryAndFile – Adicione o comando ao arquivo de histórico e à sessão atual.
  • MemoryOnly – Adicione o comando ao histórico somente para a sessão atual.
  • SkipAdding – Não adicione o comando ao arquivo de histórico da sessão atual.
  • $false - O mesmo que se o valor fosse SkipAdding.
  • $true - O mesmo que se o valor fosse MemoryAndFile.
Type:Func<T,TResult>[System.String,System.Object]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-AnsiEscapeTimeout

Essa opção é específica para o Windows quando a entrada é redirecionada, por exemplo, ao executar em tmux ou screen.

Com a entrada redirecionada no Windows, muitas teclas são enviadas como uma sequência de caracteres começando com o caractere de escape. É impossível distinguir entre um único caractere de escape seguido por mais caracteres e uma sequência de escape válida.

A suposição é que o terminal pode enviar os caracteres mais rapidamente do que um tipo de usuário. O PSReadLine aguarda esse tempo limite antes de concluir que recebeu uma sequência de escape completa.

Se você vir caracteres aleatórios ou inesperados ao digitar, poderá ajustar esse tempo limite.

Type:Int32
Position:Named
Default value:100
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-BellStyle

Especifica como o PSReadLine responde a vários erros e condições ambíguas.

Os valores válidos são os seguintes:

  • Audível: um bipe curto.
  • Visual: o texto pisca brevemente.
  • Nenhum: sem comentários.
Type:BellStyle
Position:Named
Default value:Audible
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Colors

O parâmetro Colors especifica várias cores usadas pelo PSReadLine.

O argumento é uma tabela de hash em que as chaves especificam os elementos e os valores especificam a cor. Para obter mais informações, consulte about_Hash_Tables.

As cores podem ser um valor de ConsoleColor, por exemplo [ConsoleColor]::Red, ou uma sequência de escape ANSI válida. As sequências de escape válidas dependem do terminal. No PowerShell 5.0, um exemplo de sequência de escape para texto vermelho é $([char]0x1b)[91m. No PowerShell 6 e mais recente, a mesma sequência de escape é `e[91m. Você pode especificar outras sequências de escape, incluindo os seguintes tipos:

Duas configurações de cor foram adicionadas para dar suporte à personalização do ListView no PSReadLine 2.2.0:

  • ListPredictionColor - defina a cor para o caractere à esquerda > e o nome de origem à direita, como [History]. Por padrão, ele usa DarkYellow como a cor de primeiro plano.

  • ListPredictionSelectedColor - defina a cor para indicar que um item de lista está selecionado. Por padrão, ele usa DarkBlack como a cor da tela de fundo.

  • Cor 256

  • Cor de 24 bits

  • Primeiro plano, plano de fundo ou ambos

  • Inverso, negrito

Para obter mais informações sobre códigos de cores ANSI, consulte o artigo da Wikipédia Código de escape ANSI.

As chaves válidas incluem:

  • ContinuationPrompt: a cor do prompt de continuação.
  • Ênfase: a cor de ênfase. Por exemplo, o texto correspondente ao pesquisar o histórico.
  • Erro: a cor do erro. Por exemplo, no prompt.
  • Seleção: a cor para realçar a seleção do menu ou o texto selecionado.
  • Padrão: a cor do token padrão.
  • Comentário: a cor do token de comentário.
  • Palavra-chave: a cor do token palavra-chave.
  • Cadeia de caracteres: a cor do token de cadeia de caracteres.
  • Operador: a cor do token do operador.
  • Variável: a cor do token variável.
  • Comando: a cor do token de comando.
  • Parâmetro: a cor do token de parâmetro.
  • Tipo: a cor do token de tipo.
  • Número: a cor do token numérico.
  • Membro: a cor do token de nome de membro.
  • InlinePrediction: a cor da exibição embutida da sugestão preditiva.
  • ListPrediction: a cor do caractere à esquerda > e do nome da origem da previsão.
  • ListPredictionSelected: a cor da previsão selecionada no modo de exibição de lista.
Type:Hashtable
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-CommandValidationHandler

Especifica um ScriptBlock chamado de ValidateAndAcceptLine. Se uma exceção for gerada, a validação falhará e o erro será relatado.

Antes de lançar uma exceção, o manipulador de validação pode colocar o cursor no ponto do erro para facilitar a correção. Um manipulador de validação também pode alterar a linha de comando para corrigir erros tipográficos comuns.

ValidateAndAcceptLine é usado para evitar a confusão do histórico com comandos que não podem funcionar.

Type:Action<T>[CommandAst]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-CompletionQueryItems

Especifica o número máximo de itens de conclusão mostrados sem solicitação.

Se o número de itens a serem mostrados for maior que esse valor, PSReadLine solicitará sim/não antes de exibir os itens de conclusão.

Type:Int32
Position:Named
Default value:100
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ContinuationPrompt

Especifica a cadeia de caracteres exibida no início das linhas subsequentes quando a entrada de várias linhas é inserida. O padrão é duplo maior que sinais (>>). Uma cadeia de caracteres vazia é válida.

Type:String
Position:Named
Default value:>>
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-DingDuration

Especifica a duração do bipe quando BellStyle é definido como Audível.

Type:Int32
Position:Named
Default value:50ms
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-DingTone

Especifica o tom em Hertz (Hz) do bipe quando BellStyle é definido como Audível.

Type:Int32
Position:Named
Default value:1221
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-EditMode

Especifica o modo de edição de linha de comando. O uso desse parâmetro redefine todas as associações de chave definidas por Set-PSReadLineKeyHandler.

Os valores válidos são os seguintes:

  • Windows: associações de chave emulam PowerShell, cmd e Visual Studio.
  • Emacs: associações de chave emulam Bash ou Emacs.
  • Vi: Associações de chave emulam Vi.

Use Get-PSReadLineKeyHandler para ver as associações de chave para o EditMode configurado no momento.

Type:EditMode
Position:Named
Default value:Windows
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ExtraPromptLineCount

Especifica o número de linhas extras.

Se o prompt abranger mais de uma linha, especifique um valor para esse parâmetro. Use essa opção quando quiser que linhas extras estejam disponíveis quando o PSReadLine exibir o prompt depois de mostrar alguma saída. Por exemplo, PSReadLine retorna uma lista de conclusões.

Essa opção é necessária menos do que nas versões anteriores do PSReadLine, mas é útil quando a InvokePrompt função é usada.

Type:Int32
Position:Named
Default value:0
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-HistoryNoDuplicates

Essa opção controla o comportamento de recall. Comandos duplicados ainda são adicionados ao arquivo de histórico. Quando essa opção é definida, somente a invocação mais recente é exibida ao recuperar comandos. Comandos repetidos são adicionados ao histórico para preservar a ordenação durante o recall. No entanto, normalmente, você não deseja ver o comando várias vezes ao fazer recall ou pesquisar o histórico.

Por padrão, a propriedade HistoryNoDuplicates do objeto global PSConsoleReadLineOptions é definida como True. Para alterar o valor da propriedade, você deve especificar o valor do SwitchParameter da seguinte maneira: -HistoryNoDuplicates:$False. Você pode voltar a True usar apenas o SwitchParameter, -HistoryNoDuplicates.

Usando o seguinte comando, você pode definir o valor da propriedade diretamente:

(Get-PSReadLineOption).HistoryNoDuplicates = $False

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-HistorySavePath

Especifica o caminho para o arquivo em que o histórico é salvo. Computadores que executam plataformas Windows ou não Windows armazenam o arquivo em locais diferentes. O nome do arquivo é armazenado em uma variável $($Host.Name)_history.txt, por exemplo ConsoleHost_history.txt.

Se você não usar esse parâmetro, o caminho padrão será o seguinte:

Windows

  • $env:APPDATA\Microsoft\Windows\PowerShell\PSReadLine\$($Host.Name)_history.txt

não Windows

  • $env:XDG_DATA_HOME/powershell/PSReadLine/$($Host.Name)_history.txt
  • $HOME/.local/share/powershell/PSReadLine/$($Host.Name)_history.txt
Type:String
Position:Named
Default value:A file named $($Host.Name)_history.txt in $env:APPDATA\Microsoft\Windows\PowerShell\PSReadLine on Windows and $env:XDG_DATA_HOME/powershell/PSReadLine or $HOME/.local/share/powershell/PSReadLine on non-Windows platforms
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-HistorySaveStyle

Especifica como PSReadLine salva o histórico.

Estes são os valores válidos:

  • SaveIncrementally: salve o histórico depois que cada comando for executado e compartilhe em várias instâncias do PowerShell.
  • SaveAtExit: acrescente o arquivo de histórico quando o PowerShell for encerrado.
  • SaveNothing: não use um arquivo de histórico.

Observação

Se você definir HistorySaveStyle como SaveNothing e defini-lo como SaveIncrementally posteriormente na mesma sessão, PSReadLine salvará todos os comandos executados anteriormente na sessão.

Type:HistorySaveStyle
Position:Named
Default value:SaveIncrementally
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-HistorySearchCaseSensitive

Especifica que a pesquisa de histórico diferencia maiúsculas de minúsculas em funções como ReverseSearchHistory ou HistorySearchBackward.

Por padrão, a propriedade HistorySearchCaseSensitive do objeto global PSConsoleReadLineOptions é definida como False. O uso desse SwitchParameter define o valor da propriedade como True. Para alterar o valor da propriedade de volta, você deve especificar o valor do SwitchParameter da seguinte maneira: -HistorySearchCaseSensitive:$False.

Usando o seguinte comando, você pode definir o valor da propriedade diretamente:

(Get-PSReadLineOption).HistorySearchCaseSensitive = $False

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-HistorySearchCursorMovesToEnd

Indica que o cursor se move para o final dos comandos que você carrega do histórico usando uma pesquisa. Quando esse parâmetro é definido como $False, o cursor permanece na posição em que estava quando você pressionava as setas para cima ou para baixo.

Por padrão, a propriedade HistorySearchCursorMovesToEnd do objeto global PSConsoleReadLineOptions é definida como False. Usando esse SwitchParameter , defina o valor da propriedade como True. Para alterar o valor da propriedade de volta, você deve especificar o valor do SwitchParameter da seguinte maneira: -HistorySearchCursorMovesToEnd:$False.

Usando o seguinte comando, você pode definir o valor da propriedade diretamente:

(Get-PSReadLineOption).HistorySearchCursorMovesToEnd = $False

Type:SwitchParameter
Position:Named
Default value:False
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-MaximumHistoryCount

Especifica o número máximo de comandos a serem salvos no histórico PSReadLine .

O histórico do PSReadLine é separado do histórico do PowerShell.

Type:Int32
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-MaximumKillRingCount

Especifica o número máximo de itens armazenados no anel de encerramento.

Type:Int32
Position:Named
Default value:10
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-PredictionSource

Especifica a origem do PSReadLine para obter sugestões preditivas.

Os valores válidos são:

  • Nenhum – desabilite o recurso do IntelliSense preditivo (padrão).
  • Histórico – habilite o recurso do IntelliSense preditivo e use o histórico PSReadLine como a única origem.
  • Plug-in – habilite o recurso do IntelliSense preditivo e use os plug-ins (CommandPrediction) como a única origem. Esse valor foi adicionado no PSReadLine 2.2.0
  • HistoryAndPlugin – habilite o recurso do IntelliSense preditivo e use o histórico e o plug-in como fontes. Esse valor foi adicionado no PSReadLine 2.2.0
Type:Microsoft.PowerShell.PredictionSource
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-PredictionViewStyle

Define o estilo para a exibição do texto preditivo. O padrão é InlineView.

  • InlineView - o estilo existente atualmente, semelhante ao de casca de peixe e zsh. (padrão)
  • ListView – as sugestões são renderizadas em uma lista suspensa e os usuários podem selecionar usando UpArrow e DownArrow.

Esse parâmetro foi adicionado ao PSReadLine 2.2.0

Type:Microsoft.PowerShell.PredictionViewStyle
Position:Named
Default value:InlineView
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-PromptText

Esse parâmetro define o valor da propriedade PromptText . O valor padrão é "> ".

O PSReadLine analisa sua função de prompt para determinar como alterar apenas a cor de parte do prompt. Essa análise não é 100% confiável. Use essa opção se o PSReadLine estiver alterando seu prompt de maneiras inesperadas. Inclua qualquer espaço em branco à direita.

O valor desse parâmetro pode ser uma única cadeia de caracteres ou uma matriz de duas cadeias de caracteres. A primeira cadeia de caracteres é a parte da cadeia de caracteres de prompt que você deseja que seja alterada para vermelho quando houver um erro de análise. A segunda cadeia de caracteres é uma cadeia de caracteres alternativa a ser usada para quando houver um erro de análise.

Type:String[]
Position:Named
Default value:>
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ShowToolTips

Ao exibir possíveis conclusões, as dicas de ferramenta são mostradas na lista de conclusões.

Por padrão, essa opção é ativada. Essa opção não foi habilitada por padrão em versões anteriores do PSReadLine. Para desabilitar, defina essa opção como $False.

Por padrão, a propriedade ShowToolTips do objeto global PSConsoleReadLineOptions é definida como True. O uso desse SwitchParameter define o valor da propriedade como True. Para alterar o valor da propriedade, você deve especificar o valor do SwitchParameter da seguinte maneira: -ShowToolTips:$False.

Usando o seguinte comando, você pode definir o valor da propriedade diretamente:

(Get-PSReadLineOption).ShowToolTips = $False

Type:SwitchParameter
Position:Named
Default value:True
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ViModeChangeHandler

Quando o ViModeIndicator for definido como Script, o bloco de script fornecido será invocado sempre que o modo for alterado. O bloco de script é fornecido com um argumento do tipo ViMode.

Esse parâmetro foi introduzido no PowerShell 7.

Type:ScriptBlock
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ViModeIndicator

Essa opção define o indicador visual para o modo Vi atual. Modo de inserção ou modo de comando.

Os valores válidos são os seguintes:

  • Nenhum: não há indicador.
  • Prompt: o prompt altera a cor.
  • Cursor: o cursor altera o tamanho.
  • Script: o texto especificado pelo usuário é impresso.
Type:ViModeStyle
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-WordDelimiters

Especifica os caracteres que delimitam palavras para funções como ForwardWord ou KillWord.

Type:String
Position:Named
Default value:;:,.[]{}()/\|^&*-=+'"---
Required:False
Accept pipeline input:False
Accept wildcard characters:False

Entradas

None

Você não pode redirecionar objetos para este cmdlet.

Saídas

None

Esse cmdlet não retorna nenhuma saída.