.\"**************************************************************************
.\"*                                                                        *
.\"*                                 OCaml                                  *
.\"*                                                                        *
.\"*             Xavier Leroy, projet Cristal, INRIA Rocquencourt           *
.\"*                                                                        *
.\"*   Copyright 1996 Institut National de Recherche en Informatique et     *
.\"*     en Automatique.                                                    *
.\"*                                                                        *
.\"*   All rights reserved.  This file is distributed under the terms of    *
.\"*   the GNU Lesser General Public License version 2.1, with the          *
.\"*   special exception on linking described in the file LICENSE.          *
.\"*                                                                        *
.\"**************************************************************************
.\"
.TH OCAML 1

.SH "نام (NAME)"
ocaml \- محیط تعاملی سطح بالای OCaml

.SH "خلاصه دستور (SYNOPSIS)"
.B ocaml
[
.I options
]
[
.I object-files
]
[
.I script-file
]
.SH "توضیحات (DESCRIPTION)"

دستور
.BR ocaml (1)
سیستم تعاملی سطح بالا (toplevel) برای OCaml است که استفاده تعاملی از سیستم OCaml را از طریق یک حلقهٔ خواندن\-ارزیابی\-چاپ (read-eval-print loop) فراهم می‌کند. در این حالت، سیستم به‌طور مکرر عبارت‌های OCaml را از ورودی استاندارد می‌خواند، سپس نوع آن‌ها را بررسی، کامپایل و ارزیابی کرده و در نهایت نوع استنتاج‌شده و مقدار نتیجه را (در صورت وجود) چاپ می‌کند. رسیدن به انتهای فایل (End-of-file) در ورودی استاندارد به اجرای
.BR ocaml (1)
پایان می‌دهد.

ورودی محیط تعاملی می‌تواند چندین خط را در بر گیرد. این ورودی پس از اعلان # (sharp) چاپ‌شده توسط سیستم آغاز شده و با ;; (دو نقطه ویرگول متوالی) به همراه فاصله‌های خالی اختیاری و یک انتهای خط پایان می‌یابد. ورودی محیط تعاملی از یک یا چند عبارت (phrase) تشکیل می‌شود.

اگر یک یا چند
.I object-files
(که به .cmo یا .cma ختم می‌شوند) در خط فرمان مشخص شوند، پیش از شروع محیط تعاملی بدون نمایش پیام بارگذاری می‌شوند.

اگر یک
.I script-file
داده شود، عبارت‌ها بدون نمایش پیام از فایل خوانده شده و خطاها در خطای استاندارد چاپ می‌شوند.
.BR ocaml (1)
پس از اجرای آخرین عبارت خارج می‌شود.

.SH "گزینه‌ها (OPTIONS)"

گزینه‌های خط فرمان زیر توسط
.BR ocaml (1)
شناسایی می‌شوند.
.TP
.B \-absname
نمایش نام فایل‌ها به‌صورت مسیرهای مطلق در پیام‌های خطا.
.TP
.B \-no-absname
عدم تلاش برای نمایش نام فایل‌ها به‌صورت مسیرهای مطلق در پیام‌های خطا.
.TP
.B \-i-variance
باعث می‌شود کامپایلر واریانس محاسبه‌شدهٔ پارامترهای نوع را به ازای هر اعلان نوع چاپ کند. بدون این گزینه، واریانس فقط برای نوع‌های خصوصی (private) یا نوع‌های بدون مانیفست (مانند نوع‌های انتزاعی) چاپ می‌شود.
.TP
.BI \-I " directory"
افزودن دایرکتوری داده‌شده به فهرست دایرکتوری‌های جستجو برای فایل‌های منبع و کامپایل‌شده. به‌طور پیش‌فرض، ابتدا دایرکتوری جاری و سپس دایرکتوری کتابخانه استاندارد جستجو می‌شود. دایرکتوری‌های اضافه‌شده با
.B \-I
پس از دایرکتوری جاری و به همان ترتیبی که در خط فرمان مشخص شده‌اند، اما قبل از دایرکتوری کتابخانه استاندارد جستجو می‌شوند.
.IP
اگر دایرکتوری داده‌شده با
.BR +
آغاز شود، مسیر آن به صورت نسبی نسبت به دایرکتوری کتابخانه استاندارد در نظر گرفته می‌شود. برای نمونه،
.B \-I\ +compiler-libs
زیردایرکتوری
.B compiler-libs
از کتابخانه استاندارد را به مسیر جستجو اضافه می‌کند.
.IP
همچنین می‌توان پس از اجرای toplevel، دایرکتوری‌ها را با استفاده از دستورالعمل
.B #directory
به مسیر جستجو اضافه کرد.
.TP
.BI \-init " file"
بارگذاری فایل داده‌شده به‌جای فایل مقداردهی اولیه پیش‌فرض. بخش «فایل مقداردهی اولیه (Initialization file)» در زیر را ببینید.
.TP
.B \-labels
برچسب‌ها در نوع‌ها نادیده گرفته نمی‌شوند، می‌توان از برچسب‌ها در فراخوانی‌ها استفاده کرد، و پارامترهای برچسب‌دار می‌توانند با هر ترتیبی ارائه شوند. این حالت پیش‌فرض است.
.TP
.B \-no\-app\-funct
غیرفعال کردن رفتار کاربردی (applicative) فانکتورها. با این گزینه، هر بار اعمال فانکتور نوع‌های جدیدی در نتیجه‌اش ایجاد می‌کند و اعمال دوبارهٔ یک فانکتور یکسان روی آرگومانی مشابه، دو ساختار ناسازگار ایجاد خواهد کرد.
.TP
.B \-noassert
عدم کامپایل بررسی‌های assertion. توجه داشته باشید که عبارت خاص
.B assert\ false
همواره کامپایل می‌شود زیرا بررسی نوع آن به‌طور ویژه انجام می‌گیرد.
.TP
.B \-noinit
عدم بارگذاری هیچ فایل مقداردهی اولیه‌ای. بخش «فایل مقداردهی اولیه (Initialization file)» در زیر را ببینید.
.TP
.B \-nolabels
نادیده گرفتن برچسب‌های غیر اختیاری در نوع‌ها. برچسب‌ها نمی‌توانند در فراخوانی‌ها استفاده شوند و ترتیب پارامترها سخت‌گیرانه می‌شود.
.TP
.B \-noprompt
عدم نمایش اعلان (prompt) هنگام انتظار برای دریافت ورودی.
.TP
.B \-nopromptcont
عدم نمایش اعلان ثانویه هنگام انتظار برای خطوط ادامه در ورودی‌های چندخطی. این گزینه باید مثلاً هنگام اجرای
.BR ocaml (1)
در یک پنجرهٔ
.BR emacs (1)
استفاده شود.
.TP
.B \-nostdlib
عدم گنجاندن دایرکتوری کتابخانه استاندارد در فهرست دایرکتوری‌های جستجو برای فایل‌های منبع و کامپایل‌شده.
.TP
.BI \-open " module"
باز کردن ماژول داده‌شده پیش از شروع toplevel. اگر چندین گزینهٔ
.B \-open
داده شده باشد، آن‌ها به ترتیب پردازش می‌شوند، درست مانند اینکه دستورات
open! module1;; ... open! moduleN;;
وارد شده باشند.
.TP
.BI \-ppx " command"
پس از تجزیه، درخت نحو انتزاعی را از طریق لوله به پیش‌پردازندهٔ
.IR command
هدایت می‌کند. ماژول
.BR Ast_mapper (3)
رابط بیرونی یک پیش‌پردازنده را پیاده‌سازی می‌کند.
.TP
.B \-principal
بررسی مسیر اطلاعات در طول بررسی نوع، برای اطمینان از اینکه همهٔ نوع‌ها به روش اصلی (principal) به‌دست می‌آیند. هنگام استفاده از آرگومان‌های برچسب‌دار و/یا متدهای چندریختی، این پرچم لازم است تا تضمین کند نسخه‌های بعدی کامپایلر همچنان قادر به استنتاج صحیح نوع‌ها خواهند بود، حتی اگر الگوریتم‌های داخلی تغییر کنند. تمام برنامه‌های پذیرفته‌شده در حالت
.B \-principal
در حالت پیش‌فرض نیز با نوع‌های معادل اما امضاهای باینری متفاوت پذیرفته می‌شوند؛ این امر ممکن است بررسی نوع را کُند کند، با این حال ایده خوبی است که پیش از انتشار کد منبع یک‌بار از آن استفاده شود.
.TP
.B \-no\-principal
عدم بررسی اصل بودن (principality) استنتاج نوع. این حالت پیش‌فرض است.
.TP
.B \-rectypes
اجازه دادن به نوع‌های بازگشتی دلخواه هنگام بررسی نوع. به‌طور پیش‌فرض، فقط نوع‌های بازگشتی که در آن‌ها بازگشت از طریق یک نوع شیء انجام می‌شود پشتیبانی می‌شوند.
.TP
.B \-no\-rectypes
عدم اجازه به نوع‌های بازگشتی دلخواه هنگام بررسی نوع. این حالت پیش‌فرض است.
.TP
.B \-safe\-string
اجباری کردن جداسازی میان نوع‌های
.BR string " و " bytes ،
که در نتیجه رشته‌ها را فقط‌خواندنی می‌کند. این حالت پیش‌فرض است.
.TP
.B \-safer\-matching
عدم استفاده از اطلاعات نوع برای بهینه‌سازی تطبیق الگو (pattern-matching). این کار اجازه می‌دهد تا شکست‌های تطبیق شناسایی شوند، حتی اگر یک تطبیق الگو به اشتباه جامع (exhaustive) در نظر گرفته شده باشد. این گزینه فقط بر کامپایل GADT و گونه‌های چندریختی تأثیر می‌گذارد.
.TP
.B \-short\-paths
هنگامی که یک نوع در چند مسیر ماژول مختلف قابل دسترسی است، هنگام چاپ نام نوع در رابط‌های استنتاج‌شده و پیام‌های خطا و هشدار از کوتاه‌ترین مسیر استفاده می‌شود.
.TP
.B \-stdin
خواندن ورودی استاندارد به‌عنوان یک فایل اسکریپت به‌جای شروع یک نشست تعاملی..TP
.B \-strict\-sequence
بخش سمت چپ هر توالی را ملزم می‌کند تا دارای نوع unit باشد.
.TP
.B \-no\-strict\-sequence
بخش سمت چپ یک توالی نیازی ندارد که دارای نوع unit باشد.
این حالت پیش‌فرض است.
.TP
.B \-unboxed\-types
هنگامی که یک نوع unboxable باشد (یعنی یک رکورد با یک آرگومان یا یک نوع‌داده انضمامی با یک سازندهٔ تک‌آرگومانی)، unbox خواهد شد مگر آن‌که با
.BR [@@ocaml.boxed]
نشانه‌گذاری شده باشد.
.TP
.B \-no-unboxed\-types
هنگامی که یک نوع unboxable باشد، به‌صورت boxed درخواهد آمد مگر آن‌که با
.BR [@@ocaml.unboxed]
نشانه‌گذاری شده باشد.
این حالت پیش‌فرض است.
.TP
.B \-unsafe
بررسی مرزها را در دسترسی به آرایه‌ها و رشته‌ها (ساختارهای
.BR v.(i) " و " s.[i] )
غیرفعال می‌کند. بنابراین، برنامه‌های کامپایل‌شده با
.B \-unsafe
کمی سریع‌تر هستند، اما ناامن: اگر برنامه به خارج از مرزهای یک آرایه یا رشته دسترسی پیدا کند، ممکن است هر اتفاقی رخ دهد.
.TP
.B \-unsafe\-string
انواع
.BR string " و " bytes
را یکسان در نظر می‌گیرد و در نتیجه رشته‌ها را قابل‌نوشتن می‌کند.
این گزینه برای سازگاری با کدهای منبع قدیمی در نظر گرفته شده است و نباید در نرم‌افزارهای جدید استفاده شود.
.TP
.B \-version
رشتهٔ نسخه را چاپ کرده و خارج می‌شود.
.TP
.B \-vnum
شماره نسخه کوتاه را چاپ کرده و خارج می‌شود.
.TP
.B \-no\-version
بنر نسخه را هنگام راه‌اندازی چاپ نمی‌کند.
.TP
.BI \-w " warning\-list"
هشدارها را مطابق با آرگومان
.IR warning-list
فعال یا غیرفعال می‌کند. برای نحو نوشتاری آرگومان
.I warning\-list
به
.BR ocamlc (1)
مراجعه کنید.
.TP
.BI \-warn\-error " warning\-list"
هشدارهای توصیف‌شده توسط آرگومان
.IR warning-list
را به عنوان خطای مهلک علامت‌گذاری می‌کند. توجه داشته باشید که اگر هشداری توسط گزینهٔ
.B \-w
غیرفعال شده باشد، ایجاد نمی‌شود (و خطایی تولید نمی‌کند). برای نحو نوشتاری آرگومان
.I warning\-list
به
.BR ocamlc (1)
مراجعه کنید.
.TP
.BI \-color " mode"
رنگ‌ها را در پیام‌های کامپایلر (به‌ویژه هشدارها و خطاها) فعال یا غیرفعال می‌کند.
حالت‌های زیر پشتیبانی می‌شوند:

.B auto
استفاده از روش‌های اکتشافی برای فعال‌سازی رنگ‌ها تنها در صورتی که خروجی از آن‌ها پشتیبانی کند (یک ترمینال tty سازگار با ANSI)؛

.B always
فعال‌سازی بدون قیدوشرط رنگ‌ها؛

.B never
غیرفعال کردن خروجی رنگی.

در صورتی که \-color مشخص نشده باشد، متغیر محیطی "OCAML_COLOR" در نظر گرفته می‌شود. مقادیر آن مانند بالا auto/always/never هستند.

اگر \-color مشخص نشود، "OCAML_COLOR" تنظیم نشده باشد و متغیر محیطی "NO_COLOR" تنظیم شده باشد، خروجی رنگی غیرفعال می‌شود. در غیر این صورت، تنظیم پیش‌فرض
.B auto
است، و روش اکتشافی فعلی بررسی می‌کند که متغیر محیطی "TERM" وجود داشته و خالی یا "dumb" نباشد، و isatty(stderr) برقرار باشد.

.TP
.BI \-error\-style " mode"
نحوهٔ چاپ پیام‌های خطا و هشدارها را کنترل می‌کند.
حالت‌های زیر پشتیبانی می‌شوند:

.B short
فقط خطا و مکان آن را چاپ می‌کند؛

.B contextual
مانند "short"، اما همچنین قطعه‌کد منبع مربوط به مکان خطا را نیز نمایش می‌دهد.

تنظیم پیش‌فرض
.B contextual
است.

در صورتی که \-error\-style مشخص نشده باشد، متغیر محیطی "OCAML_ERROR_STYLE" در نظر گرفته می‌شود. مقادیر آن مانند بالا short/contextual هستند.

.TP
.B \-warn\-help
توضیحات تمام شماره‌های هشدار موجود را نمایش می‌دهد.
.TP
.BI \- " file"
از
.I file
به عنوان نام فایل اسکریپت استفاده می‌کند، حتی اگر با یک خط تیره (-) شروع شود.
.TP
.BR \-help " یا " \-\-help
یک خلاصهٔ کوتاه از نحوهٔ استفاده را نمایش داده و خارج می‌شود..SH "فایل مقداردهی اولیه (INITIALIZATION FILE)"

هنگامی که
.BR ocaml (1)
به‌عنوان toplevel فراخوانی می‌شود، پیش از واگذاری کنترل به کاربر، عبارت‌ها را از یک فایل مقداردهی اولیه می‌خواند. این اتفاق هنگام اجرای یک اسکریپت یا هنگام استفاده از \-e رخ نمی‌دهد.

فایل خوانده‌شده، اولین مورد یافت‌شده از موارد زیر است:
.IP 1.
\fB.ocamlinit\fP در دایرکتوری جاری؛
.IP 2.
\fBXDG_CONFIG_HOME/ocaml/init.ml\fP، اگر \fBXDG_CONFIG_HOME\fP یک مسیر مطلق باشد؛
.IP 3.
در غیر این صورت، در یونیکس، \fBHOME/ocaml/init.ml\fP یا در ویندوز، \fBocaml\\init.ml\fP در زیر \fBLocalAppData\fP
(برای مثال \fBC:\\Users\\Bactrian\\AppData\\Local\\ocaml\\init.ml\fP)؛
.IP 4.
\fBocaml/init.ml\fP در زیر هر یک از مسیرهای مطلق در \fBXDG_CONFIG_DIRS\fP.
مسیرها در \fBXDG_CONFIG_DIRS\fP در یونیکس با دو‌نقطه (colon) و در ویندوز با نقطه\-ویرگول (semicolon) از یکدیگر جدا می‌شوند؛
.IP 5.
اگر \fBXDG_CONFIG_DIRS\fP فاقد هرگونه مسیر مطلق باشد،
\fB/usr/xdg/ocaml/init.ml\fP در یونیکس یا \fBocaml\\init.ml\fP در زیر هر یک از
\fBLocalAppData\fP (برای مثال \fBC:\\Users\\Bactrian\\AppData\\Local\fP)،
\fBRoamingAppData\fP (برای مثال \fBC:\\Users\\Bactrian\\AppData\\Roaming\fP) یا
\fBProgramData\fP (برای مثال \fBC:\\ProgramData\fP) در ویندوز؛
.IP 6.
\fBHOME/.ocamlinit\fP، اگر \fBHOME\fP خالی نباشد؛

می‌توانید با استفاده از گزینهٔ
.BI \-init " file"
یک فایل مقداردهی اولیه دیگر مشخص کنید، و با استفاده از گزینهٔ
.B \-noinit
فایل‌های مقداردهی اولیه را غیرفعال نمایید.

توجه داشته باشید که همچنین می‌توانید از دستورالعمل
.B #use
برای خواندن عبارت‌ها از یک فایل استفاده کنید.

.SH "متغیرهای محیطی (ENVIRONMENT VARIABLES)"
.TP
.B OCAMLTOP_UTF_8
هنگام چاپ مقادیر رشته‌ای، اگر
.B OCAMLTOP_UTF_8
روی false تنظیم شده باشد، بایت‌های غیر اسکی (>0x7E) به‌صورت دنبالهٔ گریز ده‌دهی چاپ می‌شوند. در غیر این صورت بدون گریز چاپ خواهند شد.
.TP
.B TERM
هنگام چاپ پیام‌های خطا، سیستم toplevel تلاش می‌کند تا مکان خطا را به‌صورت بصری با خط زیرین مشخص کند. این سیستم متغیر TERM را برای تعیین نوع ترمینال خروجی بررسی کرده و قابلیت‌های آن را در پایگاه‌داده ترمینال جستجو می‌کند.
.TP
.B XDG_CONFIG_HOME HOME XDG_CONFIG_DIRS
بخش
.B "فایل مقداردهی اولیه (INITIALIZATION FILE)"
در بالا را ببینید.
.SH "همچنین ببینید (SEE ALSO)"
.BR ocamlc "(1), " ocamlopt "(1), " ocamlrun (1).
.br
.IR The\ OCaml\ user's\ manual ,
فصل "The toplevel system".