BATsh 速查表 [TW] 繁體中文
==============================

----------------------------------------------------------------------
執行摘要
  BATsh 是一個雙語 Shell，在同一腳本檔案中執行 cmd.exe 批次處理和
  bash/sh 語法，逐行自動切換模式，無需外部 Shell，純 Perl 實作。
  支援管道、重導向、函數、變數展開擴充。

混合模式範例
  :: CMD 區段（首標記為大寫）
  @ECHO OFF
  SET LANG=BATsh

  # SH 區段（首標記含小寫字母）
  greet() { echo "你好 $1 (bash 模式)"; }
  greet $LANG
  result=$(echo $LANG | perl -e 'while(<STDIN>){chomp;print uc}')
  echo "大寫: $result"

  :: 再次進入 CMD 區段（讀取 SH 結果）
  ECHO 返回CMD: %result%

  # 執行: perl lib/BATsh.pm script.batsh
----------------------------------------------------------------------


BATsh 是一個雙語 Shell，可在同一腳本中同時執行 cmd.exe 和 bash/sh 語法。
每行的第一個語彙基元決定執行模式。

1. 模式判斷
-----------
  ECHO hello          -> cmd.exe 模式（第一個語彙基元全部大寫）
  echo hello          -> bash/sh 模式（第一個語彙基元含有小寫字母）
  # 注解              -> 注解（略過）
  :: 注解             -> 注解（CMD 風格，略過）
  REM 注解            -> 注解（CMD 風格，略過）

2. 啟動 Shell
--------------
  perl lib/BATsh.pm                    # 互動式 REPL
  perl lib/BATsh.pm script.batsh       # 執行腳本檔案
  perl lib/BATsh.pm -e "echo hello"    # 內嵌單行命令

  透過 Perl API：
    use BATsh;
    BATsh->run('script.batsh');
    BATsh->run_string("echo hello");
    BATsh->repl();

3. 環境變數橋接
---------------
  CMD 區塊和 SH 區塊透過 Perl 的 %ENV 共用變數。

  export FOO=hello   # SH 設定 FOO
  ECHO %FOO%         # CMD 透過橋接讀取 FOO（Windows）

  SET BAR=world      # CMD 設定 BAR
  echo $BAR          # SH 透過橋接讀取 BAR

4. SETLOCAL / ENDLOCAL
-----------------------
  SETLOCAL           # 快照 %ENV
  SET TMP=local_val
  ECHO %TMP%
  ENDLOCAL           # 還原 %ENV（TMP 消失）

  支援巢狀。

5. 巢狀（混合模式）
--------------------
  區塊結構必須正確配對。巢狀區塊內允許混合模式行。

  for x in 1 2; do   # SH 開啟區塊
      ECHO item $x   # CMD 行（在 SH 區塊內原樣傳遞）
  done               # SH 關閉區塊

  CMD 關鍵字: IF/ENDIF  FOR/NEXT  WHILE/WEND  DO/LOOP
  SH  關鍵字: if/fi  for/done  while/done  until/done  case/esac  { }

6. 子程序定義
--------------
  :GREET
  echo "Hello $BATSH_ARG1"
  RET

  標籤以 : 開頭，以 RET 或 RETURN 結束。
  主體在執行前擷取（不內嵌執行）。

7. CALL 和 source
------------------
  CALL :GREET world      # 帶參數呼叫子程序
  CALL other.batsh       # 包含/執行另一個 .batsh 檔案（CMD）
  source other.batsh     # 包含/執行另一個 .batsh 檔案（SH）
  . other.batsh          # POSIX 點號寫法

  參數: $BATSH_ARG1 .. $BATSH_ARGn  （CMD 中用 %BATSH_ARG1%）
  個數: $BATSH_ARGC

8. Perl API
------------
  BATsh->run($file)            # 執行 .batsh 檔案
  BATsh->run_string($source)   # 執行來源字串
  BATsh->run_lines(@lines)     # 執行行陣列
  BATsh->repl()                # 互動式 REPL
  BATsh->classify_token($tok)  # 傳回 'CMD' 或 'SH'
  BATsh->setlocal()            # 快照 %ENV
  BATsh->endlocal()            # 還原 %ENV
  BATsh->call_sub($lbl, @args) # 呼叫子程序
  BATsh->source_file($file)    # 包含 .batsh 檔案
  BATsh->version()             # 版本字串

9. 平台說明
-----------
  Windows: CMD 與 SH 區塊均以純 Perl 執行 -- 無需外部 cmd.exe/bash/sh。
  UNIX:    CMD 與 SH 區塊均以純 Perl 執行 -- 無需外部 cmd.exe/bash/sh。

10. 執行需求
------------
  Perl 5.005_03 或更新版本。僅使用核心模組（File::Spec, Carp）。
  無需 CPAN 相依套件。

參見: https://metacpan.org/dist/BATsh

11. CMD 管道和參數修飾符
--------------------------
  cmd1 | cmd2              # 透過暫存檔案的管道（純 Perl）
  SET /P VAR=提示:         # 從 STDIN 讀取一行到 VAR
  %~dp0                    # %0 的磁碟機+目錄（最常用）
  %~n1, %~x1, %~nx1       # 檔名、副檔名、兩者

12. SH 函數和變數展開
---------------------
  f() { echo $1; }         # 函數定義
  ${var%.*}  ${var%%.*}    # 刪除後綴（最短/最長）
  ${var#*.}  ${var##*.}    # 刪除前綴（最短/最長）
  ${var/a/b} ${var//a/b}   # 替換（第一個/全部）
  ${var^^} ${var,,}        # 大寫/小寫
  cmd > f  cmd >> f  2>&1  # 重新導向
  cmd1 && cmd2             # AND 鏈接
  cmd1 || cmd2             # OR 鏈接
