'\" t
.\"     Title: esh
.\"    Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.23
.\"      Date: 2024-07-05
.\"    Manual: \ \&
.\"    Source: \ \&
.\"  Language: Persian
.\"
.TH "ESH" "1" "2024-07-05" "\ \&" "\ \&"
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.ss \n[.ss] 0
.nh
.ad l
.de URL
\fI\\$2\fP <\\$1>\\$3
..
.als MTO URL
.if \n[.g] \{\
.  mso www.tmac
.  am URL
.    ad l
.  .
.  am MTO
.    ad l
.  .
.  LINKSTYLE blue R < >
.\}
.SH "نام (NAME)"
esh \- سیستم قالب‌ساز ساده مبتنی بر شل
.SH "خلاصه دستور (SYNOPSIS)"
.sp
\fBesh\fP [\-d] [\-o \fIoutput\fP] [\-s \fIshell\fP] [\-\-] \fIfile\fP [\fIvariable\fP \fI...\fP]
.sp
\fBesh\fP <\-h | \-V>
.SH "توضیحات (DESCRIPTION)"
.sp
دستور \fBesh\fP (شل توکار / embedded shell) یک موتور قالب‌ساز برای ارزیابی دستورات شل قرارگرفته در قالب‌های دلخواه است.
این ابزار شبیه به ERB (Embedded RuBy) برای شل عمل می‌کند و هدف آن قالب‌سازی برای فایل‌های پیکربندی است.
برخلاف ERB، این ابزار امکان گنجاندن (include) یک قالب ESH درون قالبی دیگر را فراهم می‌آورد (از نسخه 0.2.0 به بعد).
.sp
دستور \fBesh\fP فایل قالب (\fIfile\fP)، یا در صورت مشخص شدن \(lq\-\(rq، ورودی استاندارد (\fIstdin\fP) را به دنباله‌ای از دستورات شل تبدیل می‌کند.
دستورات میان برچسب‌های \fI<%\fP و \fI%>\fP بدون تغییر منتقل می‌شوند، و سایر بخش‌ها اسکیپ شده و پیشوند دستور \fBprintf\fP به آن‌ها افزوده می‌شود.
این دستورات در نهایت با استفاده از \fIshell\fP ارزیابی و اجرا می‌شوند (مگر اینکه گزینه \fB\-d\fP مشخص شده باشد).
.SH "گزینه‌ها (OPTIONS)"
.sp
\fB\-d\fP
.RS 4
قالب را ارزیابی و اجرا نکن، فقط اسکریپت شل تولیدشده را در خروجی بریز.
.RE
.sp
\fB\-o\fP \fIfile\fP
.RS 4
فایل خروجی یا \(lq\-\(rq برای خروجی استاندارد (STDOUT).
پیش‌فرض برابر با \(lq\-\(rq است.
.RE
.sp
\fB\-s\fP \fIshell\fP
.RS 4
نام دستور یا مسیر شل مورد استفاده برای ارزیابی و اجرای قالب.
نباید شامل فاصله (space) باشد.
پیش‌فرض برابر با \(lq/bin/sh\(rq است.
.RE
.sp
\fB\-h\fP
.RS 4
نمایش پیام راهنما و خروج.
.RE
.sp
\fB\-V\fP
.RS 4
چاپ اطلاعات نسخه و خروج.
.RE
.SH "محیط (ENVIRONMENT)"
.sp
دستور \fBesh\fP می‌تواند با استفاده از متغیرهای محیطی زیر پیکربندی شود:
.sp
\fBESH_AWK\fP
.RS 4
نام دستور یا مسیر برنامه awk مورد استفاده.
نباید شامل فاصله باشد.
پیش‌فرض برابر با \(lqawk\(rq است.
.RE
.sp
\fBESH_MAX_DEPTH\fP
.RS 4
حداکثر عمق گنجاندن (include).
پیش‌فرض برابر با 3 است.
.RE
.sp
\fBESH_SHELL\fP
.RS 4
مشابه گزینه \fB\-s\fP \fIshell\fP است.
.RE
.sp
متغیرهای محیطی اضافی زیر درون قالب و برای فرایندهای ایجادشده توسط \fBesh\fP در دسترس هستند:
.sp
\fBESH\fP
.RS 4
مسیر مفسر \fBesh\fP.
.RE
.SH "وضعیت خروج (EXIT STATUS)"
.sp
دستور \fBesh\fP با وضعیت خروج \fIshell\fP یا awk خاتمه می‌یابد، مگر آنکه پیش از تبدیل قالب خطایی رخ داده باشد.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fB0\fP  \- خروج موفقیت‌آمیز، هیچ خطایی رخ نداده است.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fB1\fP  \- خطای عمومی.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fB10\fP \- استفاده نادرست یا آرگومان‌های نامعتبر.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fB11\fP \- خطای نحوی ESH.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fB12\fP \- خطای گنجاندن (include): فایل پیدا نشد.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\fB13\fP \- خطای گنجاندن: فراتر رفتن از حداکثر عمق مجاز (\fBESH_MAX_DEPTH\fP).
.RE
.SH "ساختار دستوری قالب (TEMPLATE SYNTAX)"
.sp
ابزار ESH دارای دو برچسب برای کدهای شل، یک برچسب برای گنجاندن (include)، برچسب توضیحات (کامنت) و روشی برای اسکیپ کردن جداکننده‌های برچسب است.
.sp
<% commands %>
.RS 4
دستورات (\fIcommands\fP) را اجرا کرده و این برچسب را با خروجی استاندارد (\fIstdout\fP) آن جایگزین می‌کند.
.RE
.sp
<%= values %>
.RS 4
دستور \fIprintf \*(Aq%s \*(Aq\fP را با مقادیر (\fIvalues\fP) به عنوان آرگومان اجرا می‌کند و این برچسب را با خروجی حاصل (بدون فاصله‌های انتهایی) جایگزین می‌نماید.
مقادیر در کوتیشن قرار نمی‌گیرند و اسکیپ نمی‌شوند، بنابراین تمام جایگزینی‌های شل روی آن‌ها اعمال خواهد شد.
.RE
.sp
<%+ filename %>
.RS 4
قالب ESH را از نام فایل مشخص‌شده (\fIfilename\fP) خوانده، تبدیل کرده و به جای این برچسب قرار می‌دهد.
عملیات گنجاندن (include) به صورت بازگشتی پردازش می‌شود، اما عمق آن به مقدار \fBESH_MAX_DEPTH\fP محدود است.
.sp
اگر \fIfilename\fP یک مسیر نسبی باشد، بر اساس دایرکتوری فایل قالبی که این برچسب در آن قرار دارد ارزیابی و حل می‌شود.
اگر قالب از ورودی استاندارد (\fIstdin\fP) خوانده شود، گنجاندن‌های سطح اول نسبت به دایرکتوری کاری فعلی ارزیابی می‌شوند.
لطفاً توجه داشته باشید که عملیات گنجاندن در طول مرحله تبدیل پردازش می‌شود، نه در مرحله ارزیابی و اجرا؛ بنابراین \fIfilename\fP نمی‌تواند یک عبارت یا متغیر باشد!
.sp
برخلاف سایر موارد، این برچسب باید در همان خط بسته شود، در غیر این صورت خطای نحوی رخ می‌دهد.
.RE
.sp
<%# comment %>
.RS 4
از خروجی نهایی حذف می‌شود.
.RE
.sp
\-%>
.RS 4
می‌تواند به جای \fI%>\fP استفاده شود.
اگر در انتهای خط به کار رود، شکست خط (انتقال به خط بعد) پس از خود را حذف می‌کند، در غیر این صورت هیچ تأثیری در حذف خط نخواهد داشت.
.RE
.sp
<%%
.RS 4
هنگامی که خارج از برچسب‌های فوق استفاده شود، کاراکترهای دقیق \fI<%\fP را در خروجی تولید می‌کند.
.RE
.sp
%%>
.RS 4
هنگامی که درون برچسب‌های فوق استفاده شود، کاراکترهای دقیق \fI%>\fP را در خروجی تولید می‌کند.
.RE
.sp
برچسب‌های باز و بسته ممکن است در یک خط نباشند.
.sp
متن‌های خارج از برچسب‌ها به صورت متن ساده در نظر گرفته می‌شوند، اما تحت تأثیر کدهای شل برچسب‌گذاری‌شده پیرامون خود قرار می‌گیرند.
به عنوان مثال، متنی که با یک دستور شرطی برچسب‌گذاری‌شده \fBif\fP احاطه شده باشد، تنها در صورتی در خروجی ظاهر می‌شود که شرط درست (true) باشد.
.SH "مثال‌ها (EXAMPLES)"
.sp
.B nginx.conf.esh
.br
.sp
.if n .RS 4
.nf
.fam C
http {
    access_log <%= $logs_dir/access.log %> main;

    resolver <%= $(sed \-En \*(Aqs/^nameserver ([^#]+)/\(rs1/p\*(Aq /etc/resolv.conf) %>;

    <% if nginx \-V 2>&1 | grep \-q lua\-nginx\-module; then \-%>
    lua_package_path \*(Aq<%= $(pkg\-config \-\-variable=INSTALL_LMOD lua) %>/?.lua\*(Aq;
    <% fi \-%>

    <%+ ./http\-common.esh %>

    <%# The rest of the config is omitted %>
}
.fam
.fi
.if n .RE
.sp
برای تولید فایل پیکربندی نهایی، این دستور را اجرا کنید:
.sp
.if n .RS 4
.nf
.fam C
esh \-o nginx.conf nginx.conf.esh logs_dir=/var/log/nginx
.fam
.fi
.if n .RE
.SH "نویسندگان (AUTHORS)"
.sp
نویسنده \fBesh\fP جاکوب جیروتکا (Jakub Jirutka) است.
.SH "گزارش باگ‌ها (REPORTING BUGS)"
.sp
گزارش باگ‌ها و مشکلات را به بخش ردیابی مشکلات پروژه ارسال کنید: \c
.URL "https://github.com/jirutka/esh/issues" "" "."
.SH "همچنین ببینید (SEE ALSO)"
.sp
sh(1)