.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "AUGPRINT 1"
.TH AUGPRINT 1 2023-07-14 "Augeas 1.14.1" Augeas
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "نام (NAME)"
augprint \- ایجاد یک اسکریپت برگشت‌پذیر (idempotent) برای augtool جهت یک پرونده مشخص
.SH "خلاصه دستور (SYNOPSIS)"
.IX Header "SYNOPSIS"
augprint [\-\-pretty|\-p] [\-\-regexp[=n]|\-r[n]] [\-\-noseq|\-s] [\-\-verbose|\-v] [\-\-lens name|\-l name] [\-\-target /target|\-t /target] FILE
.SH "توضیحات (DESCRIPTION)"
.IX Header "DESCRIPTION"
دستور \&\fBaugprint\fR یک اسکریپت augtool برای یک \fBFILE\fR مشخص ایجاد می‌کند
که عمدتاً از دستورات \f(CW\*(C`set\*(C'\fR تشکیل شده است.
.PP
اسکریپت حاصل از نوع خودتوان (idempotent) طراحی شده است و
اعمال آن روی پرونده اصلی تغییری در محتوا ایجاد نخواهد کرد.
.PP
دستور \&\fBaugprint\fR هر مکان شماره‌گذاری‌شده در درخت را با یک عبارت مسیر (path-expression) جایگزین می‌کند که با استفاده از مقادیر \fIدرون\fR آن جایگاه، موقعیت را به طور یکتا مشخص می‌سازد.
.PP
این کار عبارت مسیر را از شماره موقعیت مستقل می‌سازد،
و در نتیجه آن را برای پرونده‌هایی قابل اعمال می‌کند که در آن‌ها ممکن است همان داده در موقعیت شماره دیگری وجود داشته باشد.
.PP
برای نمونه خروجی به بخش «مثال‌ها» مراجعه کنید.
.SS "خروجی عبارت باقاعده (Regexp output)"
.IX Subsection "Regexp output"
به‌طور پیش‌فرض \fBaugprint\fR عبارت‌های مسیری تولید می‌کند که از مقایسه‌های برابری ساده \f(CW\*(C`=\*(C'\fR تشکیل شده‌اند:
.PP
.Vb 1
\&  set /files/etc/hosts/seq::*[ipaddr=\*(Aq127.0.0.1\*(Aq]/ipaddr \*(Aq127.0.0.1\*(Aq
.Ve
.PP
گزینه \fB\-\-regexp\fR خروجی را به گونه‌ای تغییر می‌دهد که مقایسه‌های مبتنی بر عبارت‌های باقاعده تولید کند:
.PP
.Vb 1
\&  set /files/etc/hosts/seq::*[ipaddr=~regexp(\*(Aq127\e\e.0\e\e..*\*(Aq)]/ipaddr \*(Aq127.0.0.1\*(Aq
.Ve
.PP
حداقل طول \fIN\fR عبارت باقاعده را می‌توان با \f(CW\*(C`\-\-regexp=N\*(C'\fR مشخص کرد.
.PP
اگر با عبارت باقاعده \fIN\fR نویسه‌ای چند مقدار مختلف مطابقت پیدا کنند، \&\fBaugprint\fR عبارت باقاعده طولانی‌تری از \fIN\fR را انتخاب خواهد کرد.
.SS "محدودیت‌ها (Limitations)"
.IX Subsection "Limitations"
\fIتنها پیوست‌شدن (Append-only)\fR
.IX Subsection "Append-only"
.PP
خروجی عمدتاً بر پایه عملیات‌های set استوار است.
عملیات set تنها می‌تواند:
.PP
الف) مقدار موجود را در همان جای خود تغییر دهد
.PP
ب) یک مقدار جدید را پس از آخرین موقعیت در گروه اضافه کند
.PP
این بدان معنی است که در صورت بازتولید یک مدخل، ممکن است در همان موقعیت مدنظر اولیه قرار نگیرد.
به عنوان مثال، اگر مدخل مربوط به \f(CW192.0.2.3\fR از قبل وجود نداشته باشد، به عنوان \fIآخرین\fR مدخل در \fI/etc/hosts\fR ایجاد خواهد شد.
.PP
اغلب، چنین ردیف‌های خارج از ترتیبی تأثیری در کارایی پرونده پیکربندی حاصل ندارند.
اگر ترتیب اهمیت داشته باشد، ویرایش دستی اسکریپت \f(CW\*(C`augtool\*(C'\fR مورد نیاز خواهد بود.
.PP
\fIمقادیر تکراری (Repeated Values)\fR
.IX Subsection "Repeated Values"
.PP
دستور \&\fBaugprint\fR همیشه در یافتن عبارت مسیر یکتا برای یک موقعیت موفق نمی‌شود.
در این صورت \fBaugprint\fR موقعیت ترتیبی را به عبارتی که یکتا نیست اضافه می‌کند.
.PP
این حالت به ویژه زمانی رخ می‌دهد که مقادیر تکراری در پرونده وجود داشته باشد.
.PP
برای پرونده \fI/etc/hosts\fR شامل:
.PP
.Vb 3
\&  #\-\-\-\-\-\-
\&  192.0.2.3   defaultdns
\&  #\-\-\-\-\-\-
.Ve
.PP
دستور \&\fBaugprint\fR خروجی زیر را تولید می‌کند:
.PP
.Vb 4
\&  set /files/etc/hosts/#comment[.=\*(Aq\-\-\-\-\-\-\-\-\*(Aq][1] \*(Aq\-\-\-\-\-\-\-\-\*(Aq
\&  set /files/etc/hosts/seq::*[ipaddr=\*(Aq192.0.2.3\*(Aq]/ipaddr \*(Aq192.0.2.3\*(Aq
\&  set /files/etc/hosts/seq::*[ipaddr=\*(Aq192.0.2.3\*(Aq]/canonical \*(Aqdefaultdns\*(Aq
\&  set /files/etc/hosts/#comment[.=\*(Aq\-\-\-\-\-\-\-\-\*(Aq][2] \*(Aq\-\-\-\-\-\-\-\-\*(Aq
.Ve
.PP
دقت کنید که چگونه به مسیرهای \f(CW\*(C`#comment\*(C'\fR به ترتیب \f(CW\*(C`[1]\*(C'\fR و \f(CW\*(C`[2]\*(C'\fR بعد از \f(CW\*(C`[expr]\*(C'\fR اضافه شده است.
.PP
سایر مسیرهایی که عبارت‌های یکتا دارند مستقیماً تحت تأثیر قرار نمی‌گیرند.
.SH "گزینه‌ها (OPTIONS)"
.IX Header "OPTIONS"
.IP "\fB\-v\fR, \fB\-\-verbose\fR" 4
.IX Item "-v, --verbose"
گنجاندن مسیرهای شماره‌گذاری‌شده اصلی به عنوان کامنت در خروجی
.IP "\fB\-p\fR, \fB\-\-pretty\fR" 4
.IX Item "-p, --pretty"
تولید خروجی خواناتر با افزودن فاصله‌ها و سطرهای خالی
.IP "\fB\-r\fR, \fB\-r\fR\fIN\fR, \fB\-\-regexp\fR, \fB\-\-regexp\fR=\fIN\fR" 4
.IX Item "-r, -rN, --regexp, --regexp=N"
تولید عبارات باقاعده برای تطبیق با مقادیر،
با استفاده از حداقل طول \fIN\fR نویسه از مقدار
.Sp
مقدار \fIN\fR اختیاری است و پیش‌فرض آن 8 است
.IP "\fB\-l\fR, \fB\-\-lens\fR=\fILENS\fR" 4
.IX Item "-l, --lens=LENS"
استفاده از \fILENS\fR مشخص‌شده برای پرونده؛ بدون این گزینه، \fBaugprint\fR از لنز پیش‌فرض برای پرونده استفاده می‌کند
.IP "\fB\-t\fR \fItargetfile\fR, \fB\-\-target\fR=\fItargetfile\fR" 4
.IX Item "-t targetfile, --target=targetfile"
تولید اسکریپت برای \fIFILE\fR مشخص‌شده به گونه‌ای که گویی مسیر واقعی آن \fItargetfile\fR بوده است
.Sp
این کار لنز متناظر با \fItargetfile\fR را روی \fIFILE\fR اعمال کرده و عبارت‌های مسیر حاصل را مطابق با \fItargetfile\fR تغییر می‌دهد
.Sp
مقدار \fItargetfile\fR باید نام کامل مسیر با شروع از '/' باشد
.Sp
برای نحوه استفاده عملی از \fB\-\-target\fR به بخش «مثال‌ها» مراجعه کنید
.IP "\fB\-s\fR, \fB\-\-noseq\fR" 4
.IX Item "-s, --noseq"
عدم استفاده از \f(CW\*(C`seq::*\*(C'\fR در خروجی و استفاده از \f(CW\*(C`*\*(C'\fR به جای آن؛
به عنوان مثال:
.Sp
.Vb 1
\&  set /files/etc/hosts/*[ipaddr=\*(Aq127.0.0.1\*(Aq]/ipaddr \*(Aq127.0.0.1\*(Aq
.Ve
.Sp
مهم: خروجی حاصل دیگر ورودی جدیدی برای \f(CW127.0.0.1\fR ایجاد نخواهد کرد اگر از قبل وجود نداشته باشد. گزینه \f(CW\*(C`\-\-noseq\*(C'\fR برای این است که مسیرهای حاصل با نسخه‌های augeas قبل از 1.13.0 قابل استفاده باشند (با در نظر گرفتن این محدودیت)
.SH "مثال‌ها (EXAMPLES)"
.IX Header "EXAMPLES"
این مثال‌ها از پرونده \fI/etc/hosts\fR زیر به عنوان \fIFILE\fR استفاده می‌کنند:
.PP
.Vb 3
\&  127.0.0.1   localhost localhost.localdomain localhost4 localhost4.localdomain4
\&  192.0.2.3   dns\-a
\&  192.0.2.4   dns\-b
.Ve
.PP
خروجی دستور \f(CW\*(C`augtool \*(Aqprint /files/etc/hosts\*(Aq\*(C'\fR چنین خواهد بود:
.PP
.Vb 10
\&  /files/etc/hosts
\&  /files/etc/hosts/1
\&  /files/etc/hosts/1/ipaddr = "127.0.0.1"
\&  /files/etc/hosts/1/canonical = "localhost"
\&  /files/etc/hosts/1/alias[1] = "localhost.localdomain"
\&  /files/etc/hosts/1/alias[2] = "localhost4"
\&  /files/etc/hosts/1/alias[3] = "localhost4.localdomain4"
\&  /files/etc/hosts/2
\&  /files/etc/hosts/2/ipaddr = "192.0.2.3"
\&  /files/etc/hosts/2/canonical = "dns\-a"
\&  /files/etc/hosts/3
\&  /files/etc/hosts/3/ipaddr = "192.0.2.4"
\&  /files/etc/hosts/3/canonical = "dns\-b"
.Ve
.SS "خروجی پیش‌فرض (Default output)"
.IX Subsection "Default output"
\&\f(CW\*(C`augprint /etc/hosts\*(C'\fR
.PP
.Vb 9
\&  set /files/etc/hosts/seq::*[ipaddr=\*(Aq127.0.0.1\*(Aq]/ipaddr \*(Aq127.0.0.1\*(Aq
\&  set /files/etc/hosts/seq::*[ipaddr=\*(Aq127.0.0.1\*(Aq]/canonical \*(Aqlocalhost\*(Aq
\&  set /files/etc/hosts/seq::*[ipaddr=\*(Aq127.0.0.1\*(Aq]/alias[.=\*(Aqlocalhost.localdomain\*(Aq] \*(Aqlocalhost.localdomain\*(Aq
\&  set /files/etc/hosts/seq::*[ipaddr=\*(Aq127.0.0.1\*(Aq]/alias[.=\*(Aqlocalhost4\*(Aq] \*(Aqlocalhost4\*(Aq
\&  set /files/etc/hosts/seq::*[ipaddr=\*(Aq127.0.0.1\*(Aq]/alias[.=\*(Aqlocalhost4.localdomain4\*(Aq] \*(Aqlocalhost4.localdomain4\*(Aq
\&  set /files/etc/hosts/seq::*[ipaddr=\*(Aq192.0.2.3\*(Aq]/ipaddr \*(Aq192.0.2.3\*(Aq
\&  set /files/etc/hosts/seq::*[ipaddr=\*(Aq192.0.2.3\*(Aq]/canonical \*(Aqdns\-a\*(Aq
\&  set /files/etc/hosts/seq::*[ipaddr=\*(Aq192.0.2.4\*(Aq]/ipaddr \*(Aq192.0.2.4\*(Aq
\&  set /files/etc/hosts/seq::*[ipaddr=\*(Aq192.0.2.4\*(Aq]/canonical \*(Aqdns\-b\*(Aq
.Ve
.SS "خروجی مشروح (Verbose output)"
.IX Subsection "Verbose output"
\&\f(CW\*(C`augprint \-\-verbose /etc/hosts\*(C'\fR
.PP
.Vb 9
\&  #   /files/etc/hosts
\&  #   /files/etc/hosts/1
\&  #   /files/etc/hosts/1/ipaddr  \*(Aq127.0.0.1\*(Aq
\&  set /files/etc/hosts/seq::*[ipaddr=\*(Aq127.0.0.1\*(Aq]/ipaddr \*(Aq127.0.0.1\*(Aq
\&  #   /files/etc/hosts/1/canonical  \*(Aqlocalhost\*(Aq
\&  set /files/etc/hosts/seq::*[ipaddr=\*(Aq127.0.0.1\*(Aq]/canonical \*(Aqlocalhost\*(Aq
\&  #   /files/etc/hosts/1/alias[1]  \*(Aqlocalhost.localdomain\*(Aq
\&  set /files/etc/hosts/seq::*[ipaddr=\*(Aq127.0.0.1\*(Aq]/alias[.=\*(Aqlocalhost.localdomain\*(Aq] \*(Aqlocalhost.localdomain\*(Aq
\&  ...
.Ve
.SS "خروجی عبارت باقاعده (Rexexp output)"
.IX Subsection "Rexexp output"
\&\f(CW\*(C`augprint \-\-regexp=4 /etc/hosts\*(C'\fR
.PP
.Vb 9
\&  set /files/etc/hosts/seq::*[ipaddr=~regexp(\*(Aq127\e\e..*\*(Aq)]/ipaddr \*(Aq127.0.0.1\*(Aq
\&  set /files/etc/hosts/seq::*[ipaddr=~regexp(\*(Aq127\e\e..*\*(Aq)]/canonical \*(Aqlocalhost\*(Aq
\&  set /files/etc/hosts/seq::*[ipaddr=~regexp(\*(Aq127\e\e..*\*(Aq)]/alias[.=~regexp(\*(Aqlocalhost\e\e..*\*(Aq)] \*(Aqlocalhost.localdomain\*(Aq
\&  set /files/etc/hosts/seq::*[ipaddr=~regexp(\*(Aq127\e\e..*\*(Aq)]/alias[.=~regexp(\*(Aqlocalhost4\*(Aq)] \*(Aqlocalhost4\*(Aq
\&  set /files/etc/hosts/seq::*[ipaddr=~regexp(\*(Aq127\e\e..*\*(Aq)]/alias[.=~regexp(\*(Aqlocalhost4\e\e..*\*(Aq)] \*(Aqlocalhost4.localdomain4\*(Aq
\&  set /files/etc/hosts/seq::*[ipaddr=~regexp(\*(Aq192\e\e.0\e\e.2\e\e.3\*(Aq)]/ipaddr \*(Aq192.0.2.3\*(Aq
\&  set /files/etc/hosts/seq::*[ipaddr=~regexp(\*(Aq192\e\e.0\e\e.2\e\e.3\*(Aq)]/canonical \*(Aqdns\-a\*(Aq
\&  set /files/etc/hosts/seq::*[ipaddr=~regexp(\*(Aq192\e\e.0\e\e.2\e\e.4\*(Aq)]/ipaddr \*(Aq192.0.2.4\*(Aq
\&  set /files/etc/hosts/seq::*[ipaddr=~regexp(\*(Aq192\e\e.0\e\e.2\e\e.4\*(Aq)]/canonical \*(Aqdns\-b\*(Aq
.Ve
.PP
توجه داشته باشید که گرچه حداقل طول ۴ تعیین شده است، اما \fBaugprint\fR در صورت لزوم عبارات باقاعده طولانی‌تری را برای اطمینان از تطبیق یکتا انتخاب خواهد کرد.
.SS "استفاده از \-\-lens (Using --lens)"
.IX Subsection "Using --lens"
اگر پرونده‌ای به‌طور پیش‌فرض به لنزی متصل نشده باشد، می‌توان از \fI\-\-lens lensname\fR برای تعیین یک لنز استفاده کرد.
.PP
هنگامی که \fI\-\-lens\fR مشخص شود، خروجی با دستورات مناسب \f(CW\*(C`transform\*(C'\fR و \f(CW\*(C`load\-file\*(C'\fR پیشوندگذاری می‌شود تا اسکریپت augtool تکمیل شود، و همچنین یک دستور \fIsetm\fR برای مستثنی کردن سایر لنزهای بارگذاری خودکار درج می‌گردد.
.PP
\&\f(CW\*(C`augprint \-\-lens shellvars /etc/skel/.bashrc\*(C'\fR
.PP
.Vb 9
\&  setm /augeas/load/*[incl=\*(Aq/etc/skel/.bashrc\*(Aq and label() != \*(Aqshellvars\*(Aq]/excl \*(Aq/etc/skel/.bashrc\*(Aq
\&  transform shellvars incl /etc/skel/.bashrc
\&  load\-file /etc/skel/.bashrc
\&  set /files/etc/skel/.bashrc/#comment[.=\*(Aq.bashrc\*(Aq] \*(Aq.bashrc\*(Aq
\&  set /files/etc/skel/.bashrc/#comment[.=\*(AqSource global definitions\*(Aq] \*(AqSource global definitions\*(Aq
\&  set /files/etc/skel/.bashrc/@if[.=\*(Aq[ \-f /etc/bashrc ]\*(Aq] \*(Aq[ \-f /etc/bashrc ]\*(Aq
\&  set /files/etc/skel/.bashrc/@if[.=\*(Aq[ \-f /etc/bashrc ]\*(Aq]/.source \*(Aq/etc/bashrc\*(Aq
\&  set /files/etc/skel/.bashrc/#comment[.=\*(AqUser specific environment\*(Aq] \*(AqUser specific environment\*(Aq
\&  ...
.Ve
.PP
لنزهای \f(CW\*(C`simplelines\*(C'\fR و \f(CW\*(C`shellvars\*(C'\fR معمولاً برای پرونده‌هایی که لنز اختصاصی ندارند بسیار مفیدند.
.SS "استفاده از \-\-target (Using --target)"
.IX Subsection "Using --target"
به منظور آماده‌سازی اسکریپت augtool برای یک پرونده خاص، ممکن است ترجیح داده شود به جای ویرایش پرونده اصلی، آن را در مکان دیگری کپی کرد.
.PP
گزینه \fI\-\-target\fR این فرایند را ساده می‌سازد:
.PP
الف) کپی کردن \fI/etc/hosts\fR به یک مکان جدید
.PP
.Vb 1
\&   cp /etc/hosts ~
.Ve
.PP
ب) ویرایش پرونده \fI~/hosts\fR بر اساس نیاز
.PP
.Vb 1
\&   echo \*(Aq192.0.2.7   defaultdns\*(Aq >> ~/hosts
.Ve
.PP
ج) اجرای \f(CW\*(C`augprint\*(C'\fR به صورت زیر
.PP
.Vb 1
\&   augprint \-\-target /etc/hosts ~/hosts
.Ve
.PP
د) رونوشت از بخش مرتبط خروجی و انتقال آن به اسکریپت augtool یا سایر کلاینت‌های Augeas
.PP
.Vb 2
\&   set /files/etc/hosts/seq::*[ipaddr=\*(Aq192.0.2.7\*(Aq]/ipaddr \*(Aq192.0.2.7\*(Aq
\&   set /files/etc/hosts/seq::*[ipaddr=\*(Aq192.0.2.7\*(Aq]/canonical \*(Aqdefaultdns\*(Aq
.Ve
.PP
توجه کنید که \f(CW\*(C`augprint\*(C'\fR مسیرها را متناظر با \fI\-\-target\fR (/etc/hosts) تولید کرده است به جای آرگومان \fIFILE\fR (~/hosts).
.SH "متغیرهای محیطی (ENVIRONMENT)"
.IX Header "ENVIRONMENT VARIABLES"
.IP \fBAUGEAS_ROOT\fR 4
.IX Item "AUGEAS_ROOT"
ریشه مؤثر سیستم پرونده؛ مقدار پیش‌فرض '/' است.
.IP \fBAUGEAS_LENS_LIB\fR 4
.IX Item "AUGEAS_LENS_LIB"
فهرست شاخه‌های حاوی لنزها که با دونقطه جدا شده‌اند. شاخه‌های تعیین‌شده در اینجا پیش از شاخه‌های پیش‌فرض \fI/usr/share/augeas/lenses\fR و \fI/usr/share/augeas/lenses/dist\fR جستجو می‌شوند.
.SH "وضعیت خروج (EXIT STATUS)"
.IX Header "EXIT STATUS"
وضعیت خروج در صورت موفقیت دستور صفر و در صورت بروز هرگونه خطا ۱ خواهد بود.
.SH "فایل‌ها (FILES)"
.IX Header "FILES"
تعاریف لنزها و شِماها در \fI/usr/share/augeas/lenses\fR و \fI/usr/share/augeas/lenses/dist\fR
.SH "نویسنده (AUTHOR)"
.IX Header "AUTHOR"
George Hansper <george@hansper.id.au>
.SH "کپی‌رایت و مجوز (COPYRIGHT AND LICENSE)"
.IX Header "COPYRIGHT AND LICENSE"
حق نشر ۲۰۲۲ متعلق به George Hansper است.
.PP
ابزار Augeas (و augprint) تحت مجوز کمتر فراگیر گنو (LGPL) نگارش ۲.۱ توزیع می‌شوند.
.SH "همچنین ببینید (SEE ALSO)"
.IX Header "SEE ALSO"
\&\fBaugtool\fR\|(1)
.PP
وب‌سایت پروژه \&\fBAugeas\fR: <https://www.augeas.net/>
.PP
عبارات مسیر در \&\fBAugeas\fR: <https://github.com/hercules\-team/augeas/wiki/Path\-expressions>