libtrilux

Compacta o $array em forma de uma string, usando $sep como separador.

Descompacta a $string em forma de um array (um item por linha, para facilitar o uso com o comando 'readarray'), usando $sep como separador

Exemplo de uso com 'readarray':

readarray myArray <<< $(unpack : "maçã:banana:carambola")

Separa a $string (usando o separador padrão da shell, definido em $IFS), e retorna um token por linha (pronto para uso com o 'readarray')

Exemplo de uso com 'readarray':

readarray myArray <<< $(tokenize que dia bonito)

Retorna apenas o n-ésimo token da string (v. 'tokenize').

Os tokens são numerados a partir de 1.

Retorna os n primeiros caracteres da $string

Retorna os n últimos caracteres da $string

Retorna um trecho arbitrário da $string, começando na posição $n, e com $largura caracteres.

A contagem de posições começa de 1, e não de 0.

Retorna o número de caracteres da $string.

Converte a $string para minúsculas.

Converte a $string para maiúsculas.

Retorna a posição de $agulha em $palheiro, contando a partir de 1.

Caso não esteja presente, retorna 0 (e um erro em RC).

Retorna sucesso (RC=0) se o $palheiro contiver $agulha – e um erro (RC=1), se ausente.

Remove espaços e tabs à esquerda de $str.

Remove espaços e tabs à direita de $str.

Remove espaços e tabs à direita e à esquerda de $str.

Substitui %%tags%% na $string com os valores correspondentes encontrados no array associativo mencionado.

As tags na $string usam o formato %%nome_da_tag%% - e são substituídas por ${nome_do_array[nome_da_tag]}, se esse elemento existir no array (ou silenciosamente mantidas no lugar, caso o elemento no array não exista). Os nomes de tag levam em conta maiúsculas e minúsculas.

Exemplo:

declare -A arrval

arrval[saudacao]="Boa tarde"

arrval[nome]="Fulano de Tal"

tags arrval "%%saudacao%%, %%nome%%, bem-vindo ao %%nome_site%%"

Retorna a string $str, centralizada em um campo com $largura caracteres.

Caso $str seja MAIOR do que a $largura, a string será cortada para caber no campo.

Retorna o valor absoluto (módulo) de $numero

retorna um número aleatório de 5 dígitos. ATENÇÃO: é um aleatório de baixo custo computacional, para mera conveniência. Esse recurso é inadequado para garantias de diferenciação, bem como para fins criptográficos.

Retorna o valor do primeiro argumento que não estiver vazio, ou um erro, se todos estiverem vazios.

Exemplo:

EDITOR=`first "$VISUAL" "$EDITOR" joe`

Verifica se $cond é um valor comumente associado a um TRUE booleano (ver abaixo).

Se for, imprime $str_verdadeiro (se estiver presente) e retorna 0 em RC; se não for, imprime $str_falso (se estiver presente) e retorna 1 em RC.

Ignora maiúsculas, e aceita como valores verdadeiros: yes|y|sim|s|v|1|true|on

Verifica se há uma variável chamada $var_name (mesmo que esteja vazia).

Exemplo:

is_set "options[h]" && { usage; exit; }

Testa se "$a" = "$b" (comparados como strings).

Exemplo:

is_equal "options[c]" "remote" && prepare_remote_backup;

Verifica se $val é um item contido no $array

Exemplo:

in_array "i" ${vogais[@]} && echo "i é uma vogal"

verifica se $arg é um valor numérico.

Além dos dígitos, aceita um sinal de menos à esquerda, e um ponto decimal.

Retorna apenas a última extensão do nome do arquivo em $file_path

Retorna o nome do arquivo em $file_path, sem sua última extensão.

Retorna versão encurtada do nome do arquivo em $file_path, caso ele se refira a um conteúdo na árvore do $HOME do usuário corrente (caso o arquivo esteja fora dessa árvore, retorna o path completo).

O path retornado por essa função é absoluto, ou seja, referenciado com base no diretório raiz do sistema.

Caso o arquivo em $file_path esteja na árvore do $HOME do usuário, retorna um PATH RELATIVO, com referência ao $HOME - útil em referências para sftp e outros acessos remotos que aceitam paths relativos ao $HOME. Caso o arquivo esteja fora dessa árvore, retorna o path absoluto.

Normaliza os caracteres de uma string para gerar nomes de arquivo adequados a uso com interoperabilidade entre sistemas.

Substitui caracteres acentuados dos idiomas latinos por suas versões sem acento, substitui espaços e underscores por hífens, e em seguida remove todos os caracteres que não sejam alfabéticos, numéricos, hífen ou ponto.

Nota: usar o comando 'iconv -f utf8 -t ascii//TRANSLIT' dá resultados mais completos, porém é mais um caso em que os sistemas da Apple vêm com uma versão desatualizada do utilitário, que impede esse uso (ou demandaria adaptação). A substituição pelas rotinas da shell, usada nesta função, é compatível em todos os sistemas que usem o Bash 5+.

Retorna $string em versão codificada para uso em URLs ("percent-encoding", RFC 3986).

Recebe a $string em versão codificada para uso em URLs, e a retorna decodificadas.

Imprime em ordem reversa as linhas recebidas da entrada padrão. Usa o 'tac' ou o 'tail -r', conforme disponibilidade no sistema local (GNU ou BSD).

Converte uma timestamp em descritor de tempo Unix (segundos desde o início de 1970)

-l : converte para o horário LOCAL (de um horário UTC) antes de processar

Retorna a representação Unix da data e hora correntes (contagem de segundos desde o início de 1970, UTC)

Retorna a data e a hora completas no formato ISO 8601 (RFC 3399, capítulo 5.6).

Será a hora atual, a menos que outro horário (no formato Unix - segundos desde 1970) seja passado como o parâmetro $unix_time.

-z : converte a hora para UTC ("Z" or GMT) antes da operação

Retorna a data e a hora completas no formato comum de registro de data e hora YYYYmmdd-HHMMSS.

Será a hora atual, a menos que outro horário (no formato Unix - segundos desde 1970) seja passado como o parâmetro $unix_time.

Retorna a data e a hora no formato amigável dd/mm/YYYY HH:MM:SS

-d : retorna apenas a data

-t : retorna apenas o horário

Será a hora atual, a menos que outro horário (no formato Unix - segundos desde 1970) seja passado como o parâmetro $unix_time.

Converte uma string de data em uma representação de tempo do Unix (segundos UTC desde o início de 1970).

A $str_data deve ter exatamente essa sequência de números: "ano mês dia hora minutos segundos".

Todos os zeros à esquerda são descartados. Também será descartada qualquer coisa que vier depois dos segundos (incluindo frações e eventual menção a um fuso horário, se presente).

Os separadores podem ser quaisquer combinações de letras, espaços, tabs e pontuação.

Assume que a hora é local, a menos que a flag -l esteja presente:

-l : converte de UTC para o horário local antes de processar

Adiciona $delta a uma representação de tempo do Unix (segundos UTC desde o início de 1970).

O valor de $delta será considerado em segundos, a não ser que uma $unidade tenha sido definida (s, m, h, d: para segundos, minutos, horas ou dias).

Para subtrair, passe $delta como um número negativo.

Calcula a diferença entre as duas representações de tempo do Unix (segundos UTC desde o início de 1970), e retornando o resultado em formato aproximado (por exemplo: "2d", "11h", "30min").

Importante: a diferença é analisada desprezando o sinal, ou seja, o resultado será idêntico para resultados positivos ou negativos.

Exibe mensagens formatadas, considerando opções adicionais de formatação e os diversos modos de exibição (verbose, quiet, debug, etc. - v. 'xechomode').

A mensagem em $str pode conter os códigos de formatação e cor (v. 'ansifmt')

As opções -B e -A adicionam uma linha em branco antes e depois da mensagem.

A opção -C centraliza a $str na linha do terminal (apenas nas formatações que usam a linha inteira, como -t, -s, -r e -c).

Dica: chame a biblioteca diretamente, com o parâmetro '-e', para ver a lista e exemplos dos tipos de mensagens disponíveis.

Tipos de formatação:

-t : título [desativado com xechomode +q]

-s : subtítulo [desativado com xechomode +q]

-r : linha reversa [desativado com xechomode +q]

-w : warning

-c : critical

-e : error

-v : verbose [desativado com xechomode -v]

-i : info [desativado com xechomode +q]

-n : normal

-d : debug [desativado com xechomode -d]

-D : debuglib [desativado com xechomode -D]

-f : fixline [desativado com xechomode +q]

Ativa e desativa os modos de exibição do comando xecho:

[-|+]q : quiet (silencia o xecho -itsrf: info, título, subtítulo, reverse, fixline)

[-|+]d : debug (permite o xecho -d: mensagens normais de debug)

[-|+]D : debuglib (permite o xecho -D: mensagens de debug para uso interno)

[-|+]v : verbose (permite o xecho -v: modo verbose)

sem parâmetros: Mostra o status de todos os modos definidos

Sim, dá para ativar simultaneamente 'quiet' e 'verbose' - eles lidam com mensagens diferentes.

Default: ao carregar a biblioteca, o modo 'verbose' é ativado por default, e os demais são desativados.

Importante: para mudar vários modos com um mesmo comando, passe-os na forma "+d +q -v", não agrupados (i. e. não os passe na forma "+dq -v").

Exibe mensagens com banners à esquerda, no estilo clássico das mensagens de boot e init de sistemas operacionais estilo Unix.

-d : exibe detalhes aninhados à linha anterior (sem banner e com tabulação extra).

Os banners “ok”, “test”, “fail” e “error” são identificados com cores especiais.

Mostra uma mensagem de debug contendo o nome e o valor de 'var'

Retorna a string, interpretando os códigos de formatação no modelo ,.código.

Os 'códigos' podem ser qualquer índice dos arrays tl_ansicode (como 'bold' ou 'rev') ou tl_colornames (como 'red' ou 'cyan'). Um nome de cor pode ser prefixado com um 'b' para indicar uma cor de fundo. Cada código é substituído pela sequência ANSI correspondente, definida em tl::setlibvars() (que é chamada automaticamente na inicialização da biblioteca).

Códigos extras: b/B (bold/unbold), r/R (rev/unrev), C (uncolor), x (reset)

Dica: chame a biblioteca diretamente, com o parâmetro '-c', para ver a lista e exemplos das cores e formatações disponíveis.

Exemplo:

ansifmt "Isto é ,.b.NEGRITO,.B., isso é ,.red.texto colorido,.x..

Nota: se a saída padrão não for um terminal (por exemplo, se for uma pipe ou um arquivo de saída, os códigos de formatação gerados na inicialização desta biblioteca estarão vazios, e esta função apenas removerá as marcações de formato, sem incluir formatação em seu lugar.

Retorna a largura de linha reportada pelo terminal - ou 80 caso não seja reportada.

Exibe um título, usando a largura completa de uma linha do terminal. Esta função deve ser chamada via 'xecho -t', e não diretamente.

Exibe um subtítulo. Esta função deve ser chamada via 'xecho -s', e não diretamente.

Exibe $str em uma linha reversa, usando a largura completa de uma linha do terminal. Esta função deve ser chamada via 'xecho -r', e não diretamente.

Exibe $str em uma linha vermelha/amarela de alta intensidade, usando a largura completa de uma linha do terminal. Esta função deve ser chamada via 'xecho -c', e não diretamente.

Exibe $str como um alerta. Esta função deve ser chamada via 'xecho -w', e não diretamente.

Exibe $str como uma mensagem de erro (em stdout, e não em stderr, porque é para comunicação interativa com o usuário, e não como um elemento de fluxo tradicional). Esta função deve ser chamada via 'xecho -e', e não diretamente.

Exibe $str como uma mensagem visível apenas no modo +v (ver 'xechomode'). Esta função deve ser chamada via 'xecho -v', e não diretamente.

Exibe $str como uma mensagem informacional complementar. Esta função deve ser chamada via 'xecho -i', e não diretamente.

Exibe $str como uma mensagem de prioridade normal (nem verbose, nem quiet). Esta função deve ser chamada via 'xecho -n', e não diretamente.

Exibe $str como uma mensagem de debug. Esta função deve ser chamada via 'xecho -d', e não diretamente.

Exibe $str como uma mensagem de debug especial, usada para diferenciar o debug interno desta própria biblioteca. Esta função deve ser chamada via 'xecho -D', e não diretamente.

Imprime uma string ocupando a linha inteira (com padding ou trunc se necessário) e retorna o cursor à primeira coluna da mesma linha, para uso em barras de progresso e outras animações simples. Esta função deve ser chamada via 'xecho -f', e não diretamente.

Antes de chamar, é recomendável testar (no seu script) se a saída padrão está conectada a um terminal, pois não faz sentido chamar esta função se o programa estiver conectado a uma pipe ou a um arquivo de saída, por exemplo. Uma forma de testar se a saída padrão é um terminal é:

if [ -t 1 ] ; then echo "é um terminal"; else echo "não é um terminal"; fi

Um wrapper completo para o getopts do Bash, que deve ser chamado dentro de um eval, como no exemplo:

eval "`mygetopts "hvd-:" return_array "$@"`"

O primeiro parâmetro define as opções válidas (no mesmo formato do 'getopts') e o segundo é o nome do array associativo ao qual serão adicionadas as opções selecionadas na linha de comando (no contexto do chamador).

O terceiro parâmetro será sempre "$@" (incluindo as aspas), a não ser que você esteja processando algo que não sejam os parâmetros da linha de comando.

O mygetopts suporta opções curtas (tipo '-v' ou '-o teste.txt') e longas (tipo '--help' ou '--outfile=teste.txt'), com ou sem os argumentos extras mostrados nestes exemplos (para ativar argumentos extras em opções curtas, use um : logo após o nome da opção em $valid_opts, ou veja a documentação do getopts).

Para ativar as opções longas, inclua "-:" no valor de $valid_opts.

O exemplo acima (usando o 'eval') chama o 'getopts' do sistema com os parâmetros "hvd-:" ativados, permitindo as opções -h, -v, -d e qualquer opção longa. Os resultados, apenas para as opções que estiverem presentes na linha de comando, serão armazenados em variáveis como: ${return_array[h]}, ${return_array[d]}, ${return_array[outfile]}, etc.

NOTAS SOBRE O MYGETOPTS:

1. APENAS parâmetros presentes na linha de comando são criados no array.

2. Os parâmetros são criados como índices no array, e seus argumentos extras (quando há) são armazenados como os valores correspondentes.

3. Quando não há argumento extra, o parâmetro é armazenado como índice e valor.

4. É possível usar o 'is_set' para facilitar o tratamento das opções, como neste exemplo real a seguir, extraído do utilitário test_libtrilux.sh e que lida com opções de help e modos verbose e quiet:

xechomode -q -d -v

eval "`mygetopts "hvq" toptions "$@"`"

is_set "toptions[h]" && { usage; exit 0; }

is_set "toptions[v]" && xechomode +v

is_set "toptions[q]" && xechomode +q

5. Nos bastidores, esta função retorna uma sequência de comandos da shell, pronta para ser executada pela shell (por isso o uso do 'eval'), declarando o array associativo, definindo seus valores e fazendo o 'shift' das opções e parâmetros que tiverem sido consumidos, deixando o restante da linha de comando original disponível para uso pelo chamador.

6. Assim, como o 'eval' roda no contexto do chamador, nós evitamos as complexidades de passar e receber arrays associativos como parâmetros, e fazer o 'shift', considerando os contextos do chamador e da função que é chamada. O outro lado da moeda é que o 'eval' tratando parâmetros trazidos pelo usuário introduz potenciais riscos de segurança, portanto você não deveria usar esta função em rotinas que demandem segurança superior (i. e. que não possam confiar nesta biblioteca ou no usuário que passará os parâmetros).

Exibe o conteúdo de $msg ou da variável $USAGE (que para isso deve estar definida no contexto do chamador).

Para definir a variável $USAGE no seu script, você pode usar um modelo como este:

USAGE=$(cat << ENDUSAGE

nome-do-script.sh [opções]

Este script faz ... [inclua aqui a descrição do script]

Opções:

-v ativa o modo "verbose" - amplia o detalhamento das mensagens.

-q ativa o modo "quiet" - reduz o detalhamento das mensagens.

-h exibe esta mensagem de ajuda

... [insira as demais opções]

Copyright (c) 2025, [seu nome] ([sua URL ou contato]).

[ sua licença - exemplo: Licensed under the Apache License, Version 2.0.]

ENDUSAGE

)

As seguintes tags HTML (de abertura e de fechamento) podem ser usadas: b, i, tt.

Todos os elementos de formatação visual desta biblioteca (v. 'ansifmt') podem ser utilizados.

DICA: para definir opções de linha de comando em seu script, consulte o 'mygetopts', neste guia.

Testa a presença de uma condição necessária; quando ausente, encerra prematuramente a execução do script. Pode ser dos tipos a seguir:

require --success command [args]

require --failure command [args]

require --cmd command # 'command' precisará estar no $PATH

require --file path

require --dir path

require --equal value1 value2

require --different value1 value2

require --contain haystack needle

require --dontcontain haystack needle

Repete o comando $cmd, n vezes.

Repete o comando $cmd até ele reportar sucesso, por no máximo $max tentativas, aguardando $segundos após cada tentativa.

Defaults: 3 tentativas, 2 segundos

Testa a função 'func', confirmando seu RC e, opcionalmente, a saída produzida.

-e # (error) "func" é uma função que deve falhar (RC≠0)

-o "SAIDA" # (output) "func" é uma função que deve retornar a string "SAIDA"

Os modos verbose e quiet (ver 'xechomode') influenciam no detalhamento exibido por esta função.

Dependendo do resultado do teste, incrementa as variáveis globals $TL_MYTEST_SUCCESS ou $TL_MYTEST_FAILURE.