BATsh چیٹ شیٹ [UR] اردو
=======================

----------------------------------------------------------------------
خلاصہ
  BATsh ایک دو لسانی شیل ہے جو cmd.exe بیچ اور bash/sh نحو کو ایک ہی
  اسکرپٹ فائل میں چلاتا ہے۔ یہ فی سطر/حصہ خودکار طور پر موڈ بدلتا ہے۔
  کسی بیرونی شیل کی ضرورت نہیں -- خالص Perl نفاذ۔
  پائپ لائن، رخ موڑنے، فنکشن اور متغیر-توسیع کی سہولیات کی حمایت کرتا ہے۔

مخلوط موڈ نمونہ
  :: CMD حصہ (پہلا ٹوکن بڑے حروف میں)
  @ECHO OFF
  SET LANG=BATsh
  SET COUNT=3

  # SH حصہ (پہلا ٹوکن چھوٹے حروف میں)
  greet() { echo "Hello from $1 (bash mode)"; }
  greet $LANG
  for i in 1 2 3; do echo "  item $i of $COUNT"; done
  result=$(echo $LANG | perl -ne "print uc")
  echo "Uppercase: $result"

  :: دوبارہ CMD حصہ (برج کے ذریعے SH کا نتیجہ پڑھتا ہے)
  ECHO Back in CMD: %result%

  # اس سے چلائیں: perl lib/BATsh.pm script.batsh
  # یا:           use BATsh; BATsh->run('script.batsh');
----------------------------------------------------------------------


BATsh ایک دو لسانی شیل ہے جو cmd.exe اور bash/sh نحو کو ایک ہی اسکرپٹ میں
چلاتا ہے۔  اسکرپٹ کو حصوں میں تقسیم کیا جاتا ہے؛ ہر حصہ مناسب شیل کے ذریعے
جوں کا توں چلایا جاتا ہے۔

1. موڈ کی شناخت
---------------
  کسی حصے کی پہلی بامعنی سطر کا «پہلا ٹوکن» یہ طے کرتا ہے کہ اس حصے کو کون
  سا شیل چلائے گا:

  CMD موڈ: پہلا ٹوکن مکمل طور پر [A-Z 0-9 _ - \ / : . @ %] پر مشتمل ہو اور
           اس میں کم از کم ایک بڑا حرف A-Z ہو۔

    ECHO hello          -> CMD حصہ (cmd.exe)
    SET FOO=bar baz     -> CMD حصہ  (قدر والے حصے کی جانچ نہیں ہوتی)
    @ECHO OFF           -> CMD حصہ
    IF "%X%"=="Y" (     -> CMD حصہ

  SH موڈ: باقی سب کچھ (کوئی چھوٹا حرف ہو، یا کوئی حرف ہی نہ ہو)۔

    echo hello          -> SH حصہ  (bash/sh)
    export FOO=bar      -> SH حصہ
    if [ -f "$f" ]; then  -> SH حصہ
    #!/bin/sh           -> SH حصہ  (shebang ایک SH سطر ہے)

  تبصرے اور خالی سطریں موجودہ حصے میں شامل کر لی جاتی ہیں۔
  تبصرہ نحو:
    ::           CMD انداز کا تبصرہ
    REM ...      CMD انداز کا تبصرہ (بڑے چھوٹے حروف سے بے نیاز)
    @REM ...     CMD انداز کا تبصرہ
    # ...        SH انداز کا تبصرہ  (#! shebang نہیں)

2. شیل کا آغاز
--------------
  perl lib/BATsh.pm               # متعامل REPL
  perl lib/BATsh.pm script.batsh  # ایک اسکرپٹ فائل چلائیں
  perl lib/BATsh.pm -e "echo hi"  # ان لائن ایک سطری کمانڈ

  Perl سے:
    use BATsh;
    BATsh->run('script.batsh');
    BATsh->run_string("echo hello");
    BATsh->repl();

3. ماحولیاتی متغیر برج
----------------------
  ہر حصہ چلنے سے پہلے، BATsh موجودہ %ENV کو تمہید کے طور پر داخل کرتا ہے
  (CMD کے لیے SET سطریں، SH کے لیے export سطریں)۔  حصے کے بعد، شیل کا حتمی
  ماحول دوبارہ %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 کا اسنیپ شاٹ (cmd.exe نہیں، BATsh سنبھالتا ہے)
  SET TMP=local_val
  ECHO %TMP%
  ENDLOCAL           # %ENV بحال (TMP ختم)

  دائرے ایک دوسرے میں سما سکتے ہیں۔

5. حصے کی حد کی شناخت
---------------------
  کوئی حصہ تب ختم ہوتا ہے جب اس کے بلاک کی گہرائی صفر پر لوٹے اور اگلی
  بامعنی سطر کسی مختلف موڈ سے تعلق رکھے۔

  CMD حصے اقتباس سے باہر ( اور ) کی گہرائی کا پیچھا کرتے ہیں:

    IF "%X%"=="Y" (     <- بلاک کھولتا ہے (گہرائی 1)
        ECHO yes
    ) ELSE (            <- بند کر کے دوبارہ کھولتا ہے (گہرائی >=1 رہتی ہے)
        ECHO no
    )                   <- بلاک بند (گہرائی 0) -> حصہ ختم ہو سکتا ہے

  SH حصے کلیدی الفاظ کی گہرائی کا پیچھا کرتے ہیں:

    for x in 1 2; do   <- بلاک کھولتا ہے (گہرائی 1)
        echo $x
    done                <- بلاک بند (گہرائی 0) -> حصہ ختم ہو سکتا ہے

  کھلے بلاک کے اندر کی سطریں موجودہ حصے میں شامل ہو جاتی ہیں، چاہے ان کا
  پہلا ٹوکن دوسرے موڈ جیسا دکھے۔ اس سے یہ ممکن ہوتا ہے:

    for x in A B; do
        ECHO $x          <- SH بلاک کے اندر بڑے حروف: پھر بھی SH حصہ
    done

  SH کلیدی الفاظ کے جوڑے:
    کھولنے والے (+1) : if  for  while  until  case  function  select  {
    بند کرنے والے (-1) : fi  done  esac  }
    غیر جانبدار ( 0) : then  do  else  elif

6. سب روٹین کی تعریفیں
----------------------
  :GREET
  echo "Hello $BATSH_ARG1"
  RET

  لیبل : سے شروع ہوتے ہیں اور RET یا RETURN پر ختم ہوتے ہیں۔
  باڈی چلانے سے پہلے نکالی جاتی ہے (ان لائن نہیں چلتی)۔
  باڈی میں CMD سطریں، SH سطریں، یا مرکب ہو سکتا ہے۔

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 انحصار نہیں۔

11. CMD پائپ لائن اور پیرامیٹر موڈیفائرز
----------------------------------------
  cmd1 | cmd2              # عارضی فائل کے ذریعے پائپ لائن (خالص Perl)
  ECHO hello | perl -e "while(<STDIN>){print uc}"

  SET /P VAR=Prompt:       # STDIN سے ایک سطر پڑھ کر VAR میں رکھتا ہے

  بیچ-پیرامیٹر ٹِلڈ موڈیفائرز (مثلاً جب %0=C:\scripts\deploy.bat ہو):
    %~0   -> C:\scripts\deploy.bat  (صرف اقتباس ہٹانا)
    %~f0  -> C:/scripts/deploy.bat  (مکمل مطلق راستہ)
    %~d0  -> C:                     (ڈرائیو حرف)
    %~p0  -> /scripts/              (ڈائریکٹری راستہ)
    %~n0  -> deploy                 (توسیع کے بغیر فائل کا نام)
    %~x0  -> .bat                   (توسیع)
    %~dp0 -> C:/scripts/            (ڈرائیو + ڈائریکٹری، سب سے عام)
    %~nx1 -> deploy.bat             (نام + توسیع)

12. SH فنکشن اور توسیع
----------------------
  greet() {              # فنکشن کی تعریف
      echo "Hi $1"
  }
  function add {         # متبادل نحو
      echo $(( $1 + $2 ))
  }
  greet world            # فنکشن کال کریں
  add 3 4                # -> 7

  ${var%.*}    .* سے مماثل سب سے چھوٹا لاحقہ ہٹائیں
  ${var%%.*}   .* سے مماثل سب سے بڑا   لاحقہ ہٹائیں
  ${var#*.}    *. سے مماثل سب سے چھوٹا سابقہ ہٹائیں
  ${var##*.}   *. سے مماثل سب سے بڑا   سابقہ ہٹائیں
  ${var/a/b}   a کی پہلی موجودگی کو b سے بدلیں
  ${var//a/b}  a کی تمام موجودگیوں کو b سے بدلیں
  ${var^^}     سب بڑے حروف
  ${var,,}     سب چھوٹے حروف
  ${var:2:4}   آفسیٹ 2 سے لمبائی 4 کا ذیلی اسٹرنگ
  ${#var}      اسٹرنگ کی لمبائی
  ${var:-def}  سیٹ ہو تو قدر، ورنہ def

13. SH I/O رخ موڑنا
-------------------
  cmd > file      stdout اوور رائٹ
  cmd >> file     stdout میں اضافہ
  cmd < file      فائل سے stdin
  cmd 2> file     stderr فائل میں
  cmd 2>&1        stderr کو stdout میں ضم
  cmd > f 2>&1    stdout اور stderr دونوں فائل میں

  Here-document (stdin پر ان پٹ):
    cmd <<EOF       EOF تک باڈی سطریں؛ $VAR پھیلایا جاتا ہے
    cmd <<'EOF'     EOF تک باڈی سطریں؛ کوئی توسیع نہیں (لفظی)
    cmd <<-EOF      <<EOF کی طرح، مگر سطر کے شروع کے TAB حروف ہٹا دیے جاتے ہیں

14. SH مرکب کمانڈز
------------------
  cmd1 && cmd2    cmd2 تب چلائیں جب cmd1 کامیاب ہو
  cmd1 || cmd2    cmd2 تب چلائیں جب cmd1 ناکام ہو
  cmd1 ; cmd2     cmd2 غیر مشروط چلائیں

مزید دیکھیں: https://metacpan.org/dist/BATsh
