.\" Copyright (c) 2019 The Notion development team
.\" This file is hereby licensed Creative Commons CC0 - no rights reserved
.\" For more information, see https://creativecommons.org/share-your-work/public-domain/cc0
.\" This is an mdoc(7) manual page, as any manual page should be.
.Dd June 20, 2019
.Dt notionflux 1
.Os notion
.Sh "نام (NAME)"
.Nm notionflux
.Nd کنترل از راه دور مبتنی بر Lua برای notion
.Sh "خلاصه دستور (SYNOPSIS)"
.Nm
.Op Fl R | Fl e Ar lua-code | Pa file
.Sh "توضیحات (DESCRIPTION)"
.Nm
ابزاری برای ارسال اسکریپت‌ها به موتور اسکریپت‌نویسی Lua درون مدیر پنجره‌ی
.Xr notion 1
است.
بدین ترتیب اسکریپت می‌تواند به API داخلی Lua در notion دسترسی پیدا کند.
.Pp
دو حالت کاری وجود دارد: تعاملی و دسته‌ای (batch).
حالت تعاملی با اجرای
.Nm
در حالتی که ورودی استاندارد آن به یک ترمینال متصل باشد و بدون ارسال هیچ پرچمی در خط فرمان فعال می‌شود.
.Pp
در غیر این صورت، حالت دسته‌ای فعال می‌گردد:
.Bl -tag -width Ds
.It Fl R
اجبار به حالت دسته‌ای، حتی اگر stdin به یک ترمینال متصل باشد.
کد Lua از stdin تا رسیدن به انتهای فایل (end-of-file) خوانده شده، برای پردازش به notion ارسال می‌شود و نتیجه خوانده شده و نمایش داده می‌شود.
.It Fl e Ar code
تقریباً همانند مورد بالا، به جز اینکه به جای خواندن از stdin، پارامتر خط فرمان
.Ar code
برای پردازش ارسال می‌گردد.
.It Pa file
محتوای فایل ارزیابی می‌شود.
.El
.Sh "حالت تعاملی (INTERACTIVE MODE)"
این حالت مشابه اجرای یک پوسته تعاملی
.Xr lua 1
است.
قابلیت تکمیل خودکار با کلید Tab برای API زبان Lua در notion و همچنین ویرایش خط در دسترس است.
.Pp
کد وارد شده به محض اینکه به یک عبارت کامل Lua تبدیل شود، توسط notion ارزیابی می‌گردد.
نتیجه نمایش داده می‌شود و پس از آن می‌توان عبارت بعدی را وارد کرد.
.Sh "محیط (ENVIRONMENT)"
.Bl -tag -width DISPLAY
.It Ev DISPLAY
متغیر محیطی
.Ev DISPLAY
باید روی یک X server که notion را اجرا می‌کند تنظیم شده باشد تا
.Nm
بتواند مسیر سوکت را به دست آورد.
.El
.Sh "امنیت (SECURITY)"
.Nm
از طریق یک Unix domain socket به
.Xr notion 1
متصل می‌شود.
این سوکت تنها با مجوزهای خواندن/نوشتن برای کاربری که notion را اجرا کرده است ایجاد می‌شود.
مسیر سوکت را می‌توان با دستور زیر جویا شد:
.Bd -literal -offset indent
$ xprop \-root _NOTION_MOD_NOTIONFLUX_SOCKET
_NOTION_MOD_NOTIONFLUX_SOCKET(STRING) = "/tmp/fileuj6onu"
.Ed
.Sh "مثال‌ها (EXAMPLES)"
دستور
.Bd -literal -offset indent
$ notionflux -e "return notioncore.current():name()"
"emacs: notionflux.1"
.Ed
.Pp
عنوان پنجره‌ای که در حال حاضر دارای فوکوس است را نمایش می‌دهد، در حالی که
.Bd -literal -offset indent
$ notionflux -e "print(notioncore.current():name())"
"emacs: notionflux.1"
nil
.Ed
.Pp
پیام‌ها را جمع‌آوری کرده و پیش از بازگشت چاپ می‌کند.
به منظور نوشتن در خروجی استاندارد notion (معمولاً
.Pa ~/.xsession\-errors ) ،
همان‌طور که print در نگارش‌های پیشین
.Nm
انجام می‌داد، لطفاً از دستور زیر استفاده کنید:
.Bd -literal -offset indent
$ notionflux -e 'io.stdout:write("hello .xsession-errors!\\n")'
nil
.Ed
.Pp
با استفاده از تغییر مسیر ورودی:
.Bd -literal -offset indent
$ echo "return notioncore.current()" | notionflux
WClientWin: 0x9bb6b8
.Ed
.Pp
با استفاده از حالت تعاملی:
.Bd -literal -offset indent
$ notionflux
lua> notioncore.current():rootwin_of()
WRootWin: 0x8c9688
lua> do
\&...>   local x = 42 -- Lua defaults to global scope, don't litter
\&...>   return x
\&...> end
42
lua> ^D
.Ed
.Pp
در هر پاسخ از طرف mod_notionflux، رشته‌ها به گونه‌ای در علامت نقل‌قول قرار می‌گیرند که بتوان آن‌ها را مستقیماً مجدداً در یک مفسر Lua قرار داد تا همان رشته بازتولید شود، در حالی که سایر نوع‌ها با استفاده از
.Fn tostring
به نمایش رشته‌ای خود تبدیل می‌شوند.
به همین دلیل است که در مثال اول در اطراف پاسخ علامت‌های نقل‌قول وجود دارد اما nil (که مقدار بازگشتی بلاکی بدون عبارت return است) فاقد آن‌هاست.
.Sh "همچنین ببینید (SEE ALSO)"
.Lk https://notionwm.net "صفحه خانگی notion"
.Pp
.Lk https://raboof.github.io/notion-doc/notionconf "پیکربندی و توسعه Notion با Lua"
.Pp
.Lk https://www.lua.org/manual/5.4/manual.html "دفترچه راهنمای مرجع Lua 5.4"
.Pp
.Pa /usr/share/doc/notion/
.Pp
.Xr notion 1 ,
.Xr X 7 ,
.Xr lua 1 ,
.Xr readline 3
.Sh "تاریخچه (HISTORY)"
دستور ionflux حدود سال ۲۰۰۴ در ion3 معرفی شد.
این دستور هنگامی که notion در سال ۲۰۱۰ از ion3 منشعب گردید، توسط تیم توسعه notion با آن تطبیق داده شد.
.Sh "نویسندگان (AUTHORS)"
.Nm
در سال ۲۰۱۹ توسط
.An The Notion development team
تحت مجوز GNU GPL با هدف افزودن حالت تعاملی بازنویسی شد.
.Sh "گزارش باگ‌ها (BUGS)"
در حال حاضر، اسکریپت باید ۴۰۹۵ بایت یا کمتر باشد.
اگر به مقدار بیشتری نیاز دارید، ارسال یک نام فایل را مد نظر قرار دهید، که برای ارزیابی به notion منتقل می‌شود و در نتیجه این محدودیت را دور می‌زند.