BATsh Folha de referencia [PT] Portugues
=========================================

----------------------------------------------------------------------
RESUMO
  BATsh e um interpretador de shell bilingue que executa sintaxe cmd.exe
  e bash/sh no mesmo arquivo, alternando de modo linha por linha
  automaticamente. Nenhum shell externo necessario -- Perl puro.

EXEMPLO MISTO
  :: Secao CMD (primeiro token em maiusculas)
  @ECHO OFF
  SET LANG=BATsh

  # Secao SH (primeiro token com minusculas)
  greet() { echo "Ola $1 (modo bash)"; }
  greet $LANG
  result=$(echo $LANG | perl -e 'while(<STDIN>){chomp;print uc}')
  echo "Maiusculas: $result"

  :: De volta ao CMD (ler resultado SH)
  ECHO De volta CMD: %result%

  # Execucao: perl lib/BATsh.pm script.batsh
----------------------------------------------------------------------


BATsh e um shell bilingue que executa sintaxe cmd.exe e bash/sh
no mesmo script. O primeiro token de cada linha determina o modo.

1. Deteccao de modo
--------------------
  ECHO hello          -> modo cmd.exe  (primeiro token todo em maiusculas)
  echo hello          -> modo bash/sh  (primeiro token contem minusculas)
  # comentario        -> comentario (ignorado)
  :: comentario       -> comentario (estilo CMD, ignorado)
  REM comentario      -> comentario (estilo CMD, ignorado)

2. Iniciar o shell
-------------------
  perl lib/BATsh.pm                    # REPL interativo
  perl lib/BATsh.pm script.batsh       # executar um arquivo de script
  perl lib/BATsh.pm -e "echo ola"      # comando de uma linha

  Da API do Perl:
    use BATsh;
    BATsh->run('script.batsh');
    BATsh->run_string("echo ola");
    BATsh->repl();

3. Ponte de variaveis de ambiente
-----------------------------------
  Blocos CMD e SH compartilham variaveis atraves do %ENV do Perl.

  export FOO=ola     # SH define FOO
  ECHO %FOO%         # CMD le FOO pela ponte (Windows)

  SET BAR=mundo      # CMD define BAR
  echo $BAR          # SH le BAR pela ponte

4. SETLOCAL / ENDLOCAL
-----------------------
  SETLOCAL           # instantaneo de %ENV
  SET TMP=val_local
  ECHO %TMP%
  ENDLOCAL           # restaura %ENV (TMP desaparece)

  Os escopos podem ser aninhados.

5. Aninhamento (modo misto)
----------------------------
  As construcoes de bloco devem ser corretamente emparelhadas.
  Linhas de modo misto dentro de um bloco sao aceitas.

  for x in 1 2; do   # SH abre bloco
      ECHO item $x   # linha CMD no bloco SH (passada como esta)
  done               # SH fecha bloco

  Palavras-chave CMD: IF/ENDIF  FOR/NEXT  WHILE/WEND  DO/LOOP
  Palavras-chave SH:  if/fi  for/done  while/done  until/done
                      case/esac  { }

6. Definicoes de sub-rotinas
------------------------------
  :GREET
  echo "Ola $BATSH_ARG1"
  RET

  As etiquetas comecam com : e terminam com RET ou RETURN.
  O corpo e extraido antes da execucao.

7. CALL e source
-----------------
  CALL :GREET mundo      # chamar sub-rotina com argumento
  CALL outro.batsh       # incluir/executar outro arquivo .batsh (CMD)
  source outro.batsh     # incluir/executar outro arquivo .batsh (SH)
  . outro.batsh          # notacao ponto POSIX

  Argumentos: $BATSH_ARG1 .. $BATSH_ARGn  (%BATSH_ARG1% em CMD)
  Quantidade: $BATSH_ARGC

8. API do Perl
--------------
  BATsh->run($file)            # executar arquivo .batsh
  BATsh->run_string($source)   # executar string de fonte
  BATsh->run_lines(@lines)     # executar array de linhas
  BATsh->repl()                # REPL interativo
  BATsh->classify_token($tok)  # retorna 'CMD' ou 'SH'
  BATsh->setlocal()            # instantaneo de %ENV
  BATsh->endlocal()            # restaura %ENV
  BATsh->call_sub($lbl, @args) # chamar sub-rotina
  BATsh->source_file($file)    # incluir arquivo .batsh
  BATsh->version()             # string de versao

9. Notas de plataforma
-----------------------
  Windows: Secoes CMD e SH executam em Perl puro -- nenhum cmd.exe/bash/sh externo necessario.
  UNIX:    Secoes CMD e SH executam em Perl puro -- nenhum cmd.exe/bash/sh externo necessario.

10. Requisitos
--------------
  Perl 5.005_03 ou superior. Apenas modulos do nucleo (File::Spec, Carp).
  Sem dependencias do CPAN.

Veja tambem: https://metacpan.org/dist/BATsh

11. Pipeline CMD e modificadores de parametros
------------------------------------------------
  cmd1 | cmd2              # Pipeline via arquivo temporario (Pure Perl)
  SET /P VAR=Aviso:        # Ler uma linha do STDIN para VAR
  %~dp0                    # Unidade+diretorio de %0 (uso mais comum)
  %~n1, %~x1, %~nx1       # Nome de arquivo, extensao, ambos

12. Funcoes SH e expansao de variaveis
----------------------------------------
  f() { echo $1; }         # Definicao de funcao
  ${var%.*}  ${var%%.*}    # Remover sufixo (mais curto/mais longo)
  ${var#*.}  ${var##*.}    # Remover prefixo (mais curto/mais longo)
  ${var/a/b} ${var//a/b}   # Substituir (primeiro/todos)
  ${var^^} ${var,,}        # Maiusculas/minusculas
  cmd > f  cmd >> f  2>&1  # Redirecionamento
  cmd1 && cmd2             # Encadeamento E
  cmd1 || cmd2             # Encadeamento OU
