.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) .\" .\" 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 .\" .\" Required to disable full justification in groff 1.23.0. .if n .ds AD l .\" ======================================================================== .\" .IX Title "PG_FORMAT 1" .TH PG_FORMAT 1 2026-09-04 "perl v5.42.2" "User Contributed Perl Documentation" .\" 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)" pg_format \- زیباساز و قالب‌بندی‌کننده نحو SQL در PostgreSQL .SH "توضیحات (DESCRIPTION)" .IX Header "DESCRIPTION" این قالب‌بندی‌کننده و زیباساز SQL از کلمات کلیدی SQL\-92، SQL\-99، SQL\-2003، SQL\-2008، SQL\-2011 و کلمات کلیدی اختصاصی PostgreSQL پشتیبانی می‌کند. همچنین با سایر پایگاه‌های داده نیز به خوبی کار می‌کند. .PP ابزار pgFormatter می‌تواند به عنوان یک برنامه کنسول یا به عنوان CGI اجرا شود. این برنامه محیط اجرای خود را به‌طور خودکار تشخیص داده و خروجی را بر اساس زمینه اجرایی به صورت متن یا HTML قالب‌بندی می‌کند. همچنین در صورت استفاده به عنوان CGI همراه با سرآیند \*(AqAccept: application/json\*(Aq می‌تواند پاسخ قالب‌بندی‌شده با JSON را بازگرداند. .PP برجسته‌سازی کلمات کلیدی تنها در محیط CGI در دسترس خواهد بود. .SS "اجرا در ترمینال/کنسول (Terminal/console execution)" .IX Subsection "Terminal/console execution" نحوه استفاده: pg_format [گزینه‌ها] file.sql .PP .Vb 1 \& PostgreSQL SQL queries and PL/PGSQL code beautifier. .Ve .PP آرگومان‌ها: .PP .Vb 1 \& شناسه file.sql می‌تواند یک فایل، چندین فایل یا \- برای خواندن کوئری از stdin باشد. \& \& خروجی SQL قالب‌بندی‌شده را به stdout یا در فایل مشخص‌شده با گزینه \-o | \-\-output بازمی‌گرداند. .Ve .PP گزینه‌ها: .PP .Vb 10 \& \-a | \-\-anonymize : مبهم‌سازی تمام مقادیر لغوی (literals) در کوئری‌ها؛ مفید برای مخفی‌سازی \& داده‌های محرمانه پیش از قالب‌بندی. \& \-b | \-\-comma\-start : در فهرست پارامترها، شروع با کاما (به \-e مراجعه کنید). \& \-B | \-\-comma\-break : در دستورات insert، افزودن خط جدید پس از هر کاما. \& \-c | \-\-config FILE : استفاده از فایل پیکربندی. در حالت پیش‌فرض از فایل پیکربندی \& استفاده نمی‌شود مگر اینکه فایل‌های ./.pg_format یا \& $HOME/.pg_format یا فایل مسیر پایه XDG یعنی \& $XDG_CONFIG_HOME/pg_format/pg_format.conf وجود داشته باشند. \& \-C | \-\-wrap\-comment : همراه با \-\-wrap\-limit، اعمال قالب‌بندی مجدد روی کامنت‌ها. \& \-d | \-\-debug : فعال‌سازی حالت اشکال‌زدایی. به‌طور پیش‌فرض غیرفعال است. \& \-e | \-\-comma\-end : در فهرست پارامترها، پایان با کاما (پیش‌فرض). \& \-f | \-\-function\-case N: تغییر حالت حروف توابع PostgreSQL. حالت پیش‌فرض بدون تغییر \& است: 0. مقادیر: 0=>بدون تغییر، 1=>حروف کوچک، \& 2=>حروف بزرگ، 3=>بزرگ کردن حرف اول کلمات. \& \-F | \-\-format STR : فرمت خروجی: text یا html. پیش‌فرض: text. \& \-g | \-\-nogrouping : افزودن یک خط جدید میان دستورات در گروه‌بندی تراکنش‌ها. \& حالت پیش‌فرض گروه‌بندی دستورات است. \& \-h | \-\-help : نمایش این پیام راهنما و خروج. \& \-i | \-\-inplace : بازنویسی فایل‌های ورودی با محتوای قالب‌بندی‌شده. \& \-k | \-\-keep\-newline : حفظ خطوط خالی در کدهای plpgsql. \& \-L | \-\-no\-extra\-line : عدم افزودن خط خالی اضافی در انتهای خروجی. \& \-m | \-\-maxlength SIZE : حداکثر طول یک کوئری؛ کوئری بیش از اندازه تعیین‌شده بریده \& خواهد شد. پیش‌فرض: بدون برش (no truncate). \& \-M | \-\-multiline : فعال‌سازی جستجوی چندخطی برای \-p یا \-\-placeholder. \& \-n | \-\-nocomment : حذف تمامی کامنت‌ها از کد SQL. \& \-N | \-\-numbering : شماره‌گذاری دستورات به صورت کامنت قبل از هر کوئری. \& \-o | \-\-output file : تعیین نام فایل برای خروجی. پیش‌فرض: stdout. \& \-p | \-\-placeholder RE : تنظیم عبارت منظم (regex) برای یافتن کدهایی که نباید تغییر کنند. \& \-r | \-\-redshift : افزودن کلمات کلیدی RedShift به فهرست کلمات کلیدی SQL. \& اکنون منسوخ شده است، به جای آن از \-\-extra\-keyword \*(Aqredshift\*(Aq استفاده کنید. \& \-s | \-\-spaces size : تغییر فاصله تورفتگی، پیش‌فرض ۴ فاصله. \& \-S | \-\-separator STR : جداکننده کد پویا، پیش‌فرض علامت نقل‌قول تکی (\*(Aq). \& \-t | \-\-format\-type : آزمودن نوع قالب‌بندی دیگر برای برخی دستورات. \& \-T | \-\-tabs : استفاده از تب به جای نویسه‌های فاصله؛ در صورت استفاده، \& فاصله‌ها صرف‌نظر از مقدار تنظیم‌شده برای \-s برابر ۱ قرار می‌گیرد. \& \-u | \-\-keyword\-case N : تغییر حالت حروف کلمات کلیدی رزروشده. حالت پیش‌فرض حروف \& بزرگ است: 2. مقادیر: 0=>بدون تغییر، 1=>حروف کوچک، \& 2=>حروف بزرگ، 3=>بزرگ کردن حرف اول کلمات. \& \-U | \-\-type\-case N : تغییر حالت حروف نام انواع داده. حالت پیش‌فرض حروف \& کوچک است: 1. مقادیر: 0=>بدون تغییر، 1=>حروف کوچک، \& 2=>حروف بزرگ، 3=>بزرگ کردن حرف اول کلمات. \& \-v | \-\-version : نمایش نسخه pg_format و خروج. \& \-w | \-\-wrap\-limit N : شکستن و پیچیدن خطوط کوئری‌ها در یک طول مشخص. \& \-W | \-\-wrap\-after N : تعداد ستون‌هایی که پس از آن فهرست‌ها باید شکسته شوند. \& پیش‌فرض: هر مورد در خط خودش قرار می‌گیرد. \& \-X | \-\-no\-rcfile : عدم خواندن خودکار فایل‌های rc (مانند ./.pg_format یا \& $HOME/.pg_format یا $XDG_CONFIG_HOME/pg_format). \& گزینه \-\-config / \-c این گزینه را لغو می‌کند. \& \-\-extra\-function FILE : فایل حاوی فهرستی از توابع جهت اعمال قالب‌بندی یکسان با توابع داخلی PostgreSQL. \& \-\-extra\-keyword FILE : فایل حاوی فهرستی از کلمات کلیدی جهت اعمال قالب‌بندی یکسان با کلمات کلیدی \& داخلی PostgreSQL. از مقدار ویژه \*(Aqredshift\*(Aq برای پشتیبانی از \& کلمات کلیدی Redshift که به صورت داخلی در pgFormatter تعریف شده‌اند استفاده کنید. \& \-\-no\-space\-function : حذف فاصله میان فراخوانی تابع و پرانتز باز پس از آن. \& \-\-redundant\-parenthesis: عدم حذف پرانتزهای اضافی در دستورات DML. .Ve .PP مثال‌ها: .PP .Vb 3 \& cat samples/ex1.sql | pg_format \- \& pg_format \-n samples/ex1.sql \& pg_format \-f 2 \-n \-o result.sql samples/ex1.sql .Ve .SS "محیط CGI (CGI context)" .IX Subsection "CGI context" فایل pg_format را در پوشه cgi\-bin خود نصب کنید، مجوز اجرای آن را به عنوان یک اسکریپت CGI اعطا نمایید (شاید نیاز باشد پسوند .cgi را اضافه کنید) و آن را از مرورگر دلخواه خود فراخوانی کنید. فایل‌های logo_pgformatter.png و icon_pgformatter.ico را در دایرکتوری CGI کپی کنید؛ اسکریپت pg_format.cgi در همان مسیر به دنبال آن‌ها می‌گردد. .PP یک نمونه زنده بدون محدودیت بیش از ده هزار کاراکتر در کوئری SQL در اینجا در دسترس است: .PP .Vb 1 \& http://sqlformat.darold.net .Ve .PP برنامه pg_format به‌طور خودکار اجرا در محیط CGI را تشخیص داده و تمامی کدهای html مورد نیاز را برای اجرای یک سایت برخط قالب‌بندی کد تولید می‌کند. هیچ کار دیگری لازم نیست انجام دهید. .PP ابتدا باید ماژول‌های پرل CGI و JSON را نصب کنید. اگر از قبل نصب نشده‌اند، با توجه به توزیع خود دستور زیر را اجرا کنید: .PP .Vb 5 \& yum install perl\-cgi \& yum install perl\-json \&یا \& apt install libcgi\-pm\-perl \& apt install libjson\-perl .Ve .PP با توجه به توزیع شما. .SH "نصب (INSTALLATION)" .IX Header "INSTALLATION" با توجه به توزیع لینوکس خود، ممکن است نیاز به نصب ماژول پرل autodie داشته باشید: .PP .Vb 1 \& sudo yum \-y install perl\-autodie .Ve .PP بسته tarball را از گیت‌هاب دانلود کرده و آرشیو را به صورت زیر استخراج کنید: .PP .Vb 7 \& version=5.3 #لطفاً از آخرین نسخه منتشرشده در گیت‌هاب استفاده کنید \& wget https://github.com/darold/pgFormatter/archive/refs/tags/v${version}.tar.gz \& tar xzf v${version}.tar.gz \& cd pgFormatter\-${version}/ \& perl Makefile.PL \& make && sudo make install \& cd ../ && rm \-rf v${version}.tar.gz && rm \-rf pgFormatter\-${version} #پاک‌سازی .Ve .PP این دستور اسکریپت پرل pg_format را به‌طور پیش‌فرض در دایرکتوری /usr/local/bin/pg_format و صفحه راهنما را در /usr/local/share/man/man1/pg_format.1 کپی می‌کند. این‌ها مسیرهای پیش‌فرض نصب برای حالت \*(Aqsite\*(Aq هستند. .PP اگر می‌خواهید همه موارد در مسیر /usr/ نصب شوند، مقدار INSTALLDIRS=\*(Aqperl\*(Aq را به عنوان آرگومان Makefile.PL ارسال کنید. اسکریپت در /usr/bin/pg_format و صفحه راهنما در /usr/share/man/man1/pg_format.1 نصب خواهد شد. .PP برای نمونه، جهت نصب دقیقاً همانند دبیان، مراحل زیر را دنبال کنید: .PP .Vb 1 \& perl Makefile.PL INSTALLDIRS=vendor .Ve .PP به‌طور پیش‌فرض مقدار INSTALLDIRS برابر site قرار دارد. .PP آزمون‌های رگرسیون را می‌توان با دستور زیر اجرا کرد: .PP .Vb 1 \& make test .Ve .PP اگر داکر بر روی سیستم شما نصب است، می‌توانید یک ایمیج pgFormatter با دستور زیر بسازید: .PP .Vb 1 \& docker build \-t darold.net/pgformatter . .Ve .PP سپس به سادگی از آن به صورت زیر استفاده کنید: .PP .Vb 1 \& cat file.sql | docker run \-\-rm \-a stdin \-a stdout \-i darold.net/pgformatter \- .Ve .SH "قالب‌بندی ویژه (SPECIAL FORMATTING)" .IX Header "SPECIAL FORMATTING" .SS "گزینه \-W، \-\-wrap\-after (Option -W, --wrap-after)" .IX Subsection "Option -W, --wrap-after" از این گزینه می‌توان برای تعیین تعداد ستون‌هایی که پس از آن فهرست‌ها باید شکسته شوند استفاده کرد. به‌طور پیش‌فرض pgFormatter هر مورد را در خط خودش قرار می‌دهد. این قالب‌بندی روی فهرست‌های SELECT و FROM اعمال می‌شود. برای نمونه کوئری زیر: .PP .Vb 1 \& SELECT a, b, c, d FROM t_1, t_2, t3 WHERE a = 10 AND b = 10; .Ve .PP با گزینه \-W 4 به این صورت قالب‌بندی خواهد شد: .PP .Vb 4 \& SELECT a, b, c, d \& FROM t_1, t_2, t3 \& WHERE a = 10 \& AND b = 10; .Ve .PP توجه داشته باشید که این شیوه قالب‌بندی با زیرکوئری‌های درون فهرست به خوبی سازگار نیست. .SS "گزینه \-w، \-\-wrap\-limit (Option -w, --wrap-limit)" .IX Subsection "Option -w, --wrap-limit" این گزینه خطوط کوئری‌ها را در یک طول مشخص می‌شکند، فارغ از اینکه چه بخشی از کوئری در مرز این محدودیت قرار داشته باشد، مگر اینکه آن بخش یک کامنت باشد. برای نمونه اگر محدودیت درون یک ثابت متنی رخ دهد، متن شکسته خواهد شد. تورفتگی‌ها در شمارش کاراکترها محاسبه نمی‌شوند. این گزینه در تمام حالات اعمال می‌شود، حتی زمانی که سایر گزینه‌ها استفاده شده باشند. .SS "گزینه \-C، \-\-wrap\-comment (Option -C, --wrap-comment)" .IX Subsection "Option -C, --wrap-comment" این گزینه کامنت‌ها را در طولی که توسط \-w یا \-\-wrap\-limit مشخص شده می‌شکند، بدون توجه به اینکه چه بخشی از کامنت باشد. تورفتگی‌ها در شمارش کاراکترها محاسبه نمی‌شوند. .SS "گزینه \-t، \-\-format\-type (Option -t, --format-type)" .IX Subsection "Option -t, --format-type" این گزینه یک قالب‌بندی جایگزین را فعال می‌کند که موارد زیر را اضافه می‌نماید: .PP .Vb 3 \& * خط جدید در فهرست پارامترهای رویه/تابع \& * خط جدید در تعاریف DDL مربوط به PUBLICATION و POLICY \& * حفظ عبارات شمارشی در بند GROUP BY در یک تک‌خط .Ve .PP انتظار می‌رود این فهرست در آینده با توجه به دیدگاه‌های جایگزین گسترش یابد. .SS "گزینه \-g، \-\-nogrouping (Option -g, --nogrouping)" .IX Subsection "Option -g, --nogrouping" به‌طور پیش‌فرض pgFormatter تمام دستوراتی را که درون یک تراکنش قرار دارند گروه‌بندی می‌کند: .PP .Vb 5 \& BEGIN; \& INSERT INTO foo VALUES (1, \*(Aqtext 1\*(Aq); \& INSERT INTO foo VALUES (2, \*(Aqtext 2\*(Aq); \& ... \& COMMIT; .Ve .PP با غیرفعال کردن گروه‌بندی دستورات، pgFormatter همیشه نویسه‌های خط جدید اضافی بین دستورات قرار می‌دهد، دقیقاً مشابه خارج از یک تراکنش: .PP .Vb 1 \& BEGIN; \& \& INSERT INTO foo VALUES (1, \*(Aqtext 1\*(Aq); \& \& INSERT INTO foo VALUES (2, \*(Aqtext 2\*(Aq); \& ... \& \& COMMIT; .Ve .PP این کار ممکن است خوانایی را در تراکنش‌های غیر DML افزایش دهد. .SS "گزینه \-L، \-\-no\-extra\-line (Option -L, --no-extra-line)" .IX Subsection "Option -L, --no-extra-line" به‌طور پیش‌فرض pgFormatter همیشه پس از پایان هر دستوری که با ; خاتمه می‌یابد یک خط خالی اضافه می‌کند، مگر اینکه درون یک بلوک کد plpgsql باشد. اگر خط خالی اضافی در انتهای خروجی کاربردی ندارد، می‌توانید با افزودن این گزینه به خط فرمان آن را حذف کنید. .SS "گزینه \-\-extra\-function (Option --extra-function)" .IX Subsection "Option --extra-function" برنامه pgFormatter قالب‌بندی‌هایی را بر روی فراخوانی توابع داخلی PostgreSQL اعمال می‌کند اما قادر به شناسایی توابع تعریف‌شده توسط کاربر نیست. می‌توان فهرستی از توابع را درون یک فایل (در هر خط نام یک تابع) مشخص کرد و آن را از طریق گزینه \-\-extra\-function به pgFormatter ارسال نمود تا مانند توابع داخلی PostgreSQL قالب‌بندی شوند. .SS "گزینه \-\-extra\-keyword (Option --extra-keyword)" .IX Subsection "Option --extra-keyword" برنامه pgFormatter قالب‌بندی‌هایی را بر روی کلمات کلیدی داخلی PostgreSQL اعمال می‌کند اما کلمات کلیدی سایر پایگاه‌های داده را تشخیص نمی‌دهد. می‌توان فهرستی از کلمات کلیدی را درون یک فایل (در هر خط یک کلمه کلیدی) مشخص کرد و آن را از طریق گزینه \-\-extra\-keyword به pgFormatter ارسال نمود تا همانند کلمات کلیدی داخلی PostgreSQL قالب‌بندی شوند. .PP همچنین می‌توانید مقدار ویژه \*(Aqredshift\*(Aq را ارسال نمایید تا کلمات کلیدی تعریف‌شده به صورت داخلی در pgFormatter برای این پایگاه داده بارگذاری شوند. این امکان پیش‌تر از طریق گزینه \-r | \-\-redshift فراهم بود که اکنون منسوخ شده و در آینده حذف خواهد شد. .SS "گزینه \-\-no\-space\-function (Option --no-space-function)" .IX Subsection "Option --no-space-function" از این گزینه برای حذف نویسه فاصله میان فراخوانی تابع و پرانتز باز پس از آن استفاده کنید. به‌طور پیش‌فرض pgFormatter یک نویسه فاصله اضافه می‌کند، برای نمونه: .PP .Vb 1 \& DROP FUNCTION IF EXISTS app_public.hello (a text); .Ve .PP هنگام استفاده از این گزینه، کوئری حاصل به صورت زیر قالب‌بندی می‌شود: .PP .Vb 1 \& DROP FUNCTION IF EXISTS app_public.hello(a text); .Ve .SS "گزینه \-\-redundant\-parenthesis (Option --redundant-parenthesis)" .IX Subsection "Option --redundant-parenthesis" به‌طور پیش‌فرض، pgFormatter تلاش می‌کند تا پرانتزهای زائد را در دستورات DML حذف کند، اما در برخی موارد حفظ آن‌ها الزامی است. استفاده از این گزینه، پرانتزهای زائد را دست‌نخورده نگه می‌دارد. .SS "گزینه \-\-vertical\-align (Option --vertical-align)" .IX Subsection "Option --vertical-align" از این گزینه برای تراز کردن عمودی تعاریف مستقیم و تک‌خطی ستون‌ها درون دستورات CREATE TABLE استفاده کنید. این گزینه نام ستون‌ها، انواع داده، قیود ستونی نظیر DEFAULT و کامنت‌های انتهایی را تراز می‌کند. برای نمونه: .PP .Vb 6 \& CREATE TABLE example ( \& id serial PRIMARY KEY, \-\- some comment \& name varchar(100) NOT NULL, \-\- another comment \& email varchar(100) NOT NULL, \-\- third comment \& created_at timestamp with time zone DEFAULT CURRENT_TIMESTAMP \-\- last comment \& ); .Ve .PP قیود در سطح جدول و تعاریف چندخطی ستون‌ها حفظ می‌شوند اما در محاسبه تراز گنجانده نمی‌شوند. این گزینه به‌طور پیش‌فرض غیرفعال است و تنها بر روی خروجی متنی اعمال می‌گردد. .SH "نکات و ترفندها (HINTS)" .IX Header "HINTS" .SS "پیکربندی (Configuration)" .IX Subsection "Configuration" اگر تنظیمات پیش‌فرض pg_format تمام نیازهای شما را برآورده نمی‌کند، می‌توانید رفتار pg_format را با استفاده از یک فایل پیکربندی سفارشی‌سازی کنید، به جای آنکه مکرراً گزینه‌های خط فرمان را تکرار نمایید. به‌طور پیش‌فرض pgFormatter در صورت وجود، به دنبال فایل‌های \&./.pg_format یا \f(CW$HOME\fR/.pg_format یا \f(CW$XDG_CONFIG_HOME\fR/pg_format/pg_format.conf می‌گردد، اما می‌توانید با استفاده از گزینه خط فرمان \-c | \-\-config یک فایل پیکربندی جایگزین را انتخاب کنید. .PP برای سفارشی‌سازی CGI، اسکریپت pg_format.cgi به دنبال یک فایل پیکربندی به نام pg_format.conf در همان دایرکتوری اسکریپت CGI می‌گردد. .PP برای مشاهده یک نمونه فایل پیکربندی به doc/pg_format.conf.sample مراجعه فرمایید. .PP برای جلوگیری از بررسی فایل‌های \f(CW$XDG_CONFIG_HOME\fR/pg_format یا \f(CW$HOME\fR/.pg_format توسط pg_format، می‌توانید از گزینه خط فرمان \-X | \-\-no\-rcfile استفاده نمایید. .SS "قالب‌بندی از ورودی استاندارد (Formatting from stdin)" .IX Subsection "Formatting from stdin" می‌توانید pg_format را بدون هیچ آرگومانی یا با \- اجرا کنید تا کد SQL از طریق stdin برای قالب‌بندی ارسال شود. .PP اگر از حالت تعاملی استفاده می‌کنید، پس از تایپ دستور SQL برای قالب‌بندی، باید کلیدهای \`ctrl+d\` را فشار دهید تا ورود متن خاتمه یابد. .PP .Vb 3 \& $ pg_format \& select * from customers; \& < ctrl+d > .Ve .PP می‌توانید از ورودی استاندارد در یک دستور تک‌خطی به صورت زیر استفاده کنید: .PP .Vb 1 \& echo "select * from customers;" | pg_format .Ve .SS "قالب‌بندی از VI (Formatting from VI)" .IX Subsection "Formatting from VI" با pgFormatter، کافی است خط زیر را به فایل ~/.vimrc خود اضافه کنید: .PP .Vb 1 \& au FileType sql setl formatprg=/usr/local/bin/pg_format\e \- .Ve .PP این کار باعث می‌شود دستورات gq شما به‌طور خودکار از pgFormatter استفاده کنند. برای نمونه اگر در خط اول هستید، با تایپ: .PP .Vb 1 \& ESC+gq+G .Ve .PP کل فایل قالب‌بندی می‌شود. .PP .Vb 1 \& ESC+gq+2j .Ve .PP دو خط بعدی قالب‌بندی خواهد شد. .PP با تشکر از David Fetter برای این نکته. .PP همچنین افزونه (Neo)vim برای قالب‌بندی کد برای انواع مختلف فایل وجود دارد که از pg_format برای قالب‌بندی فایل‌های نوع SQL پشتیبانی می‌کند. با تشکر از Anders Riutta برای پچ به (Neo)vim. .SS "قالب‌بندی از Atom (Formatting from Atom)" .IX Subsection "Formatting from Atom" اگر از atom به عنوان ویرایشگر دلخواه خود استفاده می‌کنید، می‌توانید بسته pg\-formatter را نصب کنید که یک پوشش Node.js برای pgFormatter است. .PP ویژگی‌ها: .PP .Vb 2 \& * قالب‌بندی متن انتخاب‌شده یا کل فایل از طریق کلید میانبر یا دستور. \& * قالب‌بندی فایل‌های SQL هنگام ذخیره‌سازی. .Ve .PP نصب: .PP بسته pg\-formatter را در رابط کاربری Atom جستجو کنید یا آن را از طریق خط فرمان دریافت نمایید: .PP .Vb 1 \& apm install pg\-formatter .Ve .PP نحوه استفاده: .PP کلیدهای Ctrl\-Alt\-F را برای قالب‌بندی متن انتخاب‌شده (یا کل فایل) فشار دهید یا میانبر خود را تعریف کنید: .PP .Vb 1 \& \*(Aqctrl\-alt\-p\*(Aq: \*(Aqpg\-formatter:format\*(Aq .Ve .PP همچنین، می‌توانید به‌طور خودکار فایل‌های SQL را هنگام ذخیره‌سازی قالب‌بندی کنید (به‌طور پیش‌فرض غیرفعال است). .PP می‌توانید بسته را از نشانی زیر دریافت کنید: .PP .Vb 1 \& https://atom.io/packages/pg\-formatter .Ve .PP سورس‌کدها در نشانی https://github.com/gajus/pg\-formatter در دسترس هستند. .PP با تشکر از Alex Fedoseev برای بسته atom. .SS "قالب‌بندی از Visual Studio (Formatting from Visual Studio)" .IX Subsection "Formatting from Visual Studio" با تشکر از Brady Holt یک افزونه Visual Studio Code برای قالب‌بندی SQL در PostgreSQL با استفاده از pgFormatter در دسترس است. .PP .Vb 1 \& https://marketplace.visualstudio.com/items?itemName=bradymholt.pgformatter .Ve .PP برای مشاهده دستورالعمل نصب و نحوه استفاده به نشانی بالا مراجعه فرمایید. .SS "جلوگیری از جایگزینی قطعه‌کدها (Prevent replacing code snippets)" .IX Subsection "Prevent replacing code snippets" با استفاده از گزینه خط فرمان \-p یا \-\-placeholder می‌توانید بخش‌هایی از کد را در کوئری‌های SQL خود توسط pgFormatter دست‌نخورده نگه دارید. برای نمونه در کوئری‌هایی مانند: .PP .Vb 2 \& SELECT * FROM projects WHERE projectnumber \& IN <> AND username = <>; .Ve .PP ممکن است بخواهید pgFormatter علامت‌های << و >> را به عنوان کلمات کلیدی جابجایی بیتی (bit\-shift) تفسیر نکند و قطعه‌کدهای شما را تغییر ندهد. می‌توانید از یک عبارت منظم پرل استفاده کنید تا به pgFormatter دستور دهید بخشی از کوئری را دست‌نخورده حفظ کند. برای نمونه: .PP .Vb 1 \& pg_format samples/ex9.sql \-p \*(Aq<<(?:.*)?>>\*(Aq .Ve .PP عملگرهای شبیه جابجایی بیتی را قالب‌بندی نخواهد کرد. .PP اگر می‌خواهید کوئری‌ها پس از ۶۰ کاراکتر شکسته شوند (\-w 60) و این محدودیت روی کامنت‌ها نیز اعمال شود (\-C)، ممکن است نشانی‌های وب (URL) موجود در کامنت‌ها نیز شکسته شوند. اگر ترجیح می‌دهید نشانی‌های وب شکسته نشوند، می‌توانید از یک عبارت منظم برای جلوگیری از شکستن نشانی‌های اینترنتی استفاده کنید. برای نمونه: .PP .Vb 1 \& pg_format samples/ex62.sql \-C \-w 60 \-p \*(Aqhttps?:\e/\e/(www\e.)?[\-a\-zA\-Z0\-9@:%._\e+~#=]{1,256}\e.[a\-zA\-Z0\-9()]{1,6}\eb([\-a\-zA\-Z0\-9()@:%_\e+.~#?&//=]*)\*(Aq .Ve .PP کوئری‌ها و کامنت‌ها شکسته می‌شوند، اما نشانی‌های وب بدون شکستگی باقی خواهند ماند. .SS "جلوگیری از قالب‌بندی کد پویا (Prevent dynamic code formatting)" .IX Subsection "Prevent dynamic code formatting" به‌طور پیش‌فرض pgFormatter تمام کدهای بین نقل‌قول تکی را به عنوان ثابت رشته‌ای در نظر می‌گیرد و هیچ قالب‌بندی روی این کدها انجام نمی‌دهد. استفاده از یک رشته به عنوان جداکننده کد برای جلوگیری از دو برابر کردن نقل‌قول تکی در تولید کدهای پویا متداول است، در این حالت ممکن است pgFormatter در تشخیص خودکار جداکننده کد ناموفق باشد. به‌طور پیش‌فرض هر رشته پس از کلمه کلیدی EXECUTE که با علامت دلار شروع شود جستجو خواهد شد. اگر نتواند جداکننده کد شما را به‌طور خودکار تشخیص دهد، می‌توانید از گزینه خط فرمان \-S یا \-\-separator برای تنظیم جداکننده کد مورد نظر استفاده کنید. .SS "پوشش‌دهنده سبک Node.js (Node.js thin\-wrapper)" .IX Subsection "Node.js thin-wrapper" آقای Gajus Kuizinas یک پوشش Node.js برای اجرای pgFormatter نوشته است. می‌توانید آن را در نشانی https://github.com/gajus/pg\-formatter بیابید. .SS "سفارشی‌سازی CSS برای خروجی CGI (Customize CSS for the CGI output)" .IX Subsection "Customize CSS for the CGI output" می‌توانید استایل HTML رندرشده توسط استایل پیش‌فرض CSS را با ایجاد فایلی به نام custom_css_file.css در پوشه اسکریپت CGI برنامه pgFormatter تغییر دهید. استایل پیش‌فرض CSS به‌طور کامل با محتوای این فایل سفارشی جایگزین خواهد شد. برای مشاهده کدهای پیش‌فرض CSS استفاده‌شده باید به خروجی HTML تولیدشده نگاه کنید. .SS "استفاده از pgFormatter به عنوان API (Using pgFormatter as an API)" .IX Subsection "Using pgFormatter as an API" می‌توانید با تنظیم سرآیند HTTP به نام \*(AqAccept\*(Aq روی مقدار \*(Aqapplication/json\*(Aq هنگام فراخوانی آن به عنوان یک برنامه CGI، از pgFormatter به عنوان یک API استفاده کنید. در صورتی که نمی‌خواهید این ویژگی فعال باشد، مقدار "$self\->{ \*(Aqenable_api\*(Aq } = 0" را در تابع "set_config" در lib/pgFormatter/CGI.pm تنظیم کنید. .SH "استفاده به عنوان PRE\-COMMIT HOOK (USING AS PRE\-COMMIT HOOK)" .IX Header "USING AS PRE-COMMIT HOOK" .Vb 6 \& \- repo: https://github.com/darold/pgFormatter \& rev: "v5.8" \& hooks: \& \- id: pg_format \& args: ["\-\-inplace", "\-\-wrap\-limit", "120"] \& files: \*(Aq.*\e.sql$\*(Aq .Ve .SH "نویسندگان (AUTHORS)" .IX Header "AUTHORS" برنامه pgFormatter اثری اصلی از Gilles Darold همراه با بازآرایی و بازنویسی عمده کد توسط Hubert depesz Lubaczewski است. .SH "حق نشر (COPYRIGHT)" .IX Header "COPYRIGHT" حق نشر 2012\-2026 Gilles Darold. تمامی حقوق محفوظ است. .SH "مجوز (LICENSE)" .IX Header "LICENSE" برنامه pgFormatter یک نرم‌افزار آزاد است که تحت پروانه PostgreSQL (PostgreSQL Licence) توزیع شده است. .PP نسخه‌ای تغییریافته از ماژول پرل SQL::Beautify در pgFormatter گنجانده شده که حق نشر (C) 2009 آن متعلق به Jonas Kramer است و تحت شرایط پروانه Artistic License 2.0 منتشر شده است.