.\" This file Copyright 1992,93,94 Miquel van Smoorenburg
.\" 1998-2002 Jukka Lahtinen
.\" It may be distributed under the GNU Public License, version 2, or
.\" any higher version.  See section COPYING of the GNU Public license
.\" for conditions under which this file may be redistributed.
.TH RUNSCRIPT 1 "$Date: 2007-10-07 18:13:51 $" "User's Manual"
.SH "نام (NAME)"
runscript \- مفسر اسکریپت برای نرم‌افزار ارتباط سریال Minicom
.SH "خلاصه دستور (SYNOPSIS)"
.B runscript
.RI "scriptname [logfile [homedir]]"
.SH "توضیحات (DESCRIPTION)"
.B runscript
یک مفسر اسکریپت ساده است که می‌توان آن را از درون برنامه ارتباطی minicom فراخوانی کرد تا وظایفی مانند ورود به یک سیستم یونیکس یا BBS مورد علاقه‌تان را خودکار کند.
.SH "نحوه فراخوانی (INVOCATION)"
این برنامه نام اسکریپت و به صورت اختیاری نام یک فایل لاگ و دایرکتوری خانگی کاربر را به عنوان آرگومان دریافت می‌کند، و انتظار دارد ورودی و خروجی آن به «طرف مقابل» (سیستمی که به آن متصل می‌شوید) متصل باشد. تمام پیام‌های \fBrunscript\fP که برای صفحه نمایش محلی در نظر گرفته شده‌اند به خروجی خطای استاندارد (\fBstderr\fP) هدایت می‌شوند. اگر آن را از درون \fBminicom\fP اجرا کنید، تمام این موارد به طور خودکار مدیریت می‌شوند.
پارامترهای فایل لاگ و دایرکتوری خانگی فقط برای مشخص کردن نام فایل لاگ و محل ذخیره آن برای دستور log استفاده می‌شوند. اگر دایرکتوری خانگی مشخص نشود، runscript از دایرکتوری موجود در متغیر محیطی $HOME استفاده می‌کند. اگر نام فایل لاگ نیز حذف شود، دستورات log نادیده گرفته می‌شوند.
.SH "کلمات کلیدی (KEYWORDS)"
.TP 0.5i
دستور runscript کلمات کلیدی و فرمان‌های زیر را می‌شناسد:
.br
.RS
.nf

expect   send     goto     gosub    return   \^!<   \^!
exit     print    set      inc      dec      if   timeout
verbose  sleep    break    call     log

.fi
.RE
.SH "مرور کلمات کلیدی (OVERVIEW OF KEYWORDS)"
.TP 0.5i
.B "send <string>"
رشته <string> به مودم ارسال می‌شود. در انتهای آن یک نویسه '\\r' (بازگشت به ابتدای سطر) ارسال می‌گردد.
مقدار <string> می‌تواند به اشکال زیر باشد:
  \- متن معمولی، مانند 'send hello'
  \- متن محصور در علامت نقل‌قول، مانند 'send \^"hello world\^"'
.TP 0.5i
     درون <string> دنباله‌های گریز زیر شناسایی می‌شوند:
    \\n \- سطر جدید (newline)
    \\r \- بازگشت به ابتدای سطر (carriage return)
    \\a \- زنگ هشدار (bell)
    \\b \- پس‌بر (backspace)
    \\c \- عدم ارسال '\\r' پیش‌فرض
    \\f \- تعویض صفحه (formfeed)
    \\^ \- نویسه ^
    \\o \- ارسال نویسه با کد اکتال \fBo\fP (\fBo\fP یک عدد در مبنای هشت است)

.br
نویسه‌های کنترلی را می‌توان با پیشوند ^ در رشته استفاده کرد
(^A تا ^Z، ^[، ^\، ^]، ^^ و ^_). اگر نیاز به ارسال خود نویسه ^ دارید،
باید آن را با نویسه گریز \\ همراه کنید.
.br
نویسه‌های مبنای هشت (اکتال) یا چهار رقمی هستند یا با یک نویسه غیررقمی خاتمه می‌یابند؛
برای نمونه، نویسه تهی (null) را می‌توان با \\0000 ارسال کرد و دستور 'send 1234'
معادل 'send \\0061234' است.
.br
همچنین می‌توان از متغیرهای محیطی به صورت $(environment_variable) استفاده کرد، برای نمونه $(TERM).
نرم‌افزار Minicom سه متغیر محیطی ویژه را ارسال می‌کند: $(LOGIN) که نام کاربری است،
$(PASS) که گذرواژه است (همان‌طور که در مدخل مربوطه در دایرکتوری شماره‌گیری تعریف شده)،
و $(TERMLIN) که تعداد خطوط واقعی ترمینال در صفحه نمایش شماست (بدون احتساب خط وضعیت).
.TP 0.5i
.B "print <string>"
رشته <string> را در صفحه نمایش محلی چاپ می‌کند. به طور پیش‌فرض با '\\r\\n' پایان می‌یابد.
توضیحات 'send' در بالا را ببینید.
.TP 0.5i
.B "label:"
یک برچسب (با نام 'label') تعریف می‌کند تا با دستورات goto یا gosub استفاده شود.
.TP 0.5i
.B "goto <label>"
پرش به نقطه دیگری از برنامه.
.TP 0.5i
.B "gosub <label>"
پرش به نقطه دیگری از برنامه. هنگامی که به دستور 'return' برخورد شود،
کنترل برنامه به دستور پس از gosub بازمی‌گردد.
دستورات gosub می‌توانند تو در تو باشند.
.TP 0.5i
.BR "return"
بازگشت از یک gosub.
.TP 0.5i
.BR "! <command>"
یک پوسته اجرا کرده و دستور 'command' را در آن اجرا می‌کند. پس از بازگشت،
متغیر '$?' روی وضعیت خروج این دستور تنظیم می‌شود، بنابراین می‌توانید
سپس آن را با استفاده از 'if' بررسی کنید.
.TP 0.5i
.BR "!< <command>"
یک پوسته اجرا کرده و دستور 'command' را در آن اجرا می‌کند. خروجی استاندارد (stdout)
حاصل از اجرای دستور به مودم ارسال خواهد شد. پس از بازگشت، متغیر '$?'
روی وضعیت خروج این دستور تنظیم می‌شود، بنابراین می‌توانید سپس آن را
با استفاده از 'if' بررسی کنید.
.TP 0.5i
.B "exit [value]"
خروج از \^"runscript\^" با وضعیت خروج اختیاری (پیش‌فرض ۱).
.TP 0.5i
.B "set <variable> <value>"
مقدار متغیر <variable> (که یک حرف تکی a-z است) را روی مقدار <value> تنظیم می‌کند.
اگر <variable> وجود نداشته باشد، ایجاد خواهد شد.
مقدار <value> می‌تواند یک عدد صحیح یا یک متغیر دیگر باشد.
.TP 0.5i
.B "inc <variable>"
مقدار <variable> را یک واحد افزایش می‌دهد.
.TP 0.5i
.B "dec <variable>"
مقدار <variable> را یک واحد کاهش می‌دهد.
.TP 0.5i
.B "if <value> <operator> <value> <statement>"
اجرای شرطی دستور <statement>. عملگر <operator> می‌تواند <، >، != یا = باشد.
مانند 'if a > 3 goto exitlabel'.
.TP 0.5i
.B "timeout <value>"
مدت زمان انتظار سراسری (timeout) را تعیین می‌کند. به طور پیش‌فرض، 'runscript'
پس از ۱۲۰ ثانیه خارج می‌شود. این مقدار را می‌توان با این دستور تغییر داد.
هشدار: این دستور در درون یک بلوک 'expect' عملکرد متفاوتی دارد که در ادامه توضیح داده شده است.
.TP 0.5i
.B "verbose <on|off>"
به طور پیش‌فرض، این گزینه 'on' (روشن) است. این بدان معناست که هر آنچه
توسط 'runscript' از مودم خوانده می‌شود، در صفحه نمایش بازتاب می‌یابد
تا بتوانید عملکرد 'runscript' را مشاهده کنید.
.TP 0.5i
.B "sleep <value>"
توقف موقت اجرای برنامه به مدت <value> ثانیه.
.TP 0.5i
.B "expect"
.nf
  expect {
    pattern  [statement]
    pattern  [statement]
    [timeout <value> [statement] ]
    ....
  }
.fi
مهم‌ترین دستور از میان همه دستورات. دستور expect ورودی را به طور مداوم می‌خواند
تا زمانی که الگویی مطابق با یکی از الگوهای مشخص‌شده پیدا کند. اگر expect
پس از آن الگو با یک عبارت یا دستور اختیاری مواجه شود، آن را اجرا می‌کند؛
در غیر این صورت، رفتار پیش‌فرض خروج از بلوک expect است.
الگوی 'pattern' یک رشته متنی است، همانند دستور 'send' (در بالا ببینید).
به طور معمول، expect پس از ۶۰ ثانیه به اتمام زمان انتظار می‌رسد و خارج می‌شود،
اما این مقدار با دستور timeout قابل تغییر است.
.TP 0.5i
.B "break"
خروج از یک بلوک 'expect'. این دستور معمولاً فقط به عنوان آرگومان برای 'timeout'
درون expect مفید است، زیرا رفتار پیش‌فرض timeout خروج فوری از برنامه است.
.TP 0.5i
.B "call <scriptname>"
انتقال کنترل به یک فایل اسکریپت دیگر. هنگامی که آن اسکریپت بدون خطا به پایان برسد،
اسکریپت اصلی ادامه خواهد یافت.
.TP 0.5i
.B "log <text>"
نوشتن متن در فایل لاگ.
.SH "نکات (NOTES)"
اگر می‌خواهید اسکریپت شما باعث خروج از minicom شود (برای نمونه زمانی که با minicom به ISP خود شماره‌گیری می‌کنید و سپس یک نشست PPP یا SLIP را از طریق اسکریپت آغاز می‌نمایید)، دستور "! killall \-9 minicom" را به عنوان آخرین دستور اسکریپت امتحان کنید. گزینه \-9 مانع از قطع خط تلفن و ریست شدن مودم توسط minicom قبل از خروج می‌شود.
.br
.br
شاید این اطلاعات برای تبدیل شما به یک «برنامه‌نویس» باتجربه در 'runscript' کافی نباشد، اما همراه با مثال‌ها، نوشتن اسکریپت‌های کاربردی نباید چندان دشوار باشد. اگر با زبان BASIC آشنایی داشته باشید کار آسان‌تر خواهد بود. سورس کد \fBminicom\fP به همراه دو اسکریپت نمونه به نام‌های \fBscriptdemo\fP و \fBunixlogin\fP ارائه می‌شود. به خصوص اسکریپت دومی پایه مناسبی برای توسعه اسکریپت‌های خودتان است.
.SH "همچنین ببینید (SEE ALSO)"
.BR minicom (1)
.SH "اشکالات (BUGS)"
دستور runscript باید به صورت داخلی در minicom تعبیه شود.
.SH "نویسندگان (AUTHORS)"
Miquel van Smoorenburg, <miquels@drinkel.ow.org>
.br
Jukka Lahtinen, <walker@netsonic.fi>