نام (NAME)

ly-server - دستکاری فایل‌های منبع LilyPond از طریق HTTP

نحوه استفاده:

ly-server [options]

یک سرور HTTP برای دستکاری کدهای ورودی LilyPond

گزینه‌های سرور (SERVER OPTIONS)

-v, --version: نمایش شماره نسخه و خروج
-h, --help: نمایش این متن راهنما و خروج
-p,--port PORT: درگاهی که سرور به آن گوش می‌دهد (پیش‌فرض 5432)
-t,--timeout TIME: در صورت تنظیم، سرور پس از -t ثانیه عدم فعالیت به طور خودکار خاموش می‌شود هنوز پیاده‌سازی نشده است!

گزینه‌های دستور (COMMAND OPTIONS)

-e,--encoding ENC: کدگذاری (ورودی) (پیش‌فرض UTF-8)
--output-encoding ENC: کدگذاری خروجی (پیش‌فرض همان کدگذاری ورودی)
-l,--language NAME: زبان پیش‌فرض نام زیروبمی (پیش‌فرض "nederlands")
-d <variable=value>: تنظیم یک متغیر (در ادامه را ببینید)

گزینه‌های دستور، مقادیر پیش‌فرض را برای اجرای دستورهایی تعیین می‌کنند که توسط درخواست‌های HTTP فراخوانی می‌شوند. این گزینه‌ها می‌توانند توسط هر درخواست HTTP مجزا بازنویسی شوند..SH "درخواست‌های HTTP (HTTP REQUESTS)"

درخواست‌های GET (GET Requests)

برخی درخواست‌های GET بعداً برای بازیابی مقادیر یا تغییر برخی تنظیمات کارساز بر اساس مسیر URL پیاده‌سازی خواهند شد.

درخواست‌های POST (POST Requests)

کارساز درخواست‌های POST را (در حال حاضر) بدون استفاده از مسیر URL می‌پذیرد. این کارساز به عنوان بدنهٔ درخواست، انتظار یک رشتهٔ JSON منفرد با عناصر زیر را دارد:

commands (اجباری): آرایه‌ای شامل یک یا چند دستور که باید به صورت متوالی اجرا شوند. هر مدخل شامل موارد زیر است:

command (اجباری):: نامی برای دستور. این مقدار باید یکی از موارد موجود در فهرست دستورهای دردسترس زیر باشد.
args (اختیاری):: اگر دستوری به آرگومان‌ها نیاز داشته باشد (مانند دستور transpose)، آن‌ها به عنوان یک مقدار رشته‌ای منفرد ارائه می‌شوند.
variables (اختیاری):: یک دیکشنری از انتساب‌های متغیرها. کلیدها باید از فهرست زیر باشند، و درستی نوع مقادیر بررسی می‌شود. اگر یک یا چند متغیر داده شود، پیش از اجرای دستور مقداردهی خواهند شد. ممکن است متغیری پیش از اجرای دستور بعدی دوباره تغییر کند، اما به طور خودکار بازنشانی نمی‌شود. تعیین یک متغیر با مقدار ''، آن را از حالت تنظیم خارج (unset) می‌کند.

options (اختیاری): یک دیکشنری از انتساب‌های گزینه‌ها. کلیدها باید از فهرست گزینه‌های دستور در بالا انتخاب شوند، به صورت نام بلند و بدون خط فاصله‌های آغازین، مانند { "encoding": "UTF-16" }. اگر گزینه‌ای در اینجا داده شود، گزینهٔ پیش‌فرض داده‌شده در خط فرمان را لغو می‌کند، اما تنها برای دستور فعلی.
data (اجباری): یک رشتهٔ منفرد حاوی سند ورودی LilyPond.

کارساز تلاش خواهد کرد سلسله‌ای از دستورها را از روی درخواست بسازد، و در صورت وجود هرگونه اشکال در آن، یک پیام "Bad Request" با کد وضعیت HTTP 400 ارسال می‌کند.

شیء پاسخ (Response Object)

اگر دستورها با موفقیت اجرا شوند، بدنهٔ پاسخ حاوی یک شیء JSON سریالی‌شده با عناصر زیر خواهد بود:

info: آرایه‌ای از مدخل‌ها شامل نتایج دستورهای "info" (به زیر مراجعه کنید). هر مدخل دارای یک فیلد command و یک فیلد info است.
doc: شیئی با دو فیلد:

content: رشته‌ای شامل محتوای سند با اعمال متوالی تمامی دستورهای "edit". (اگر هیچ دستور ویرایشی مشخص نشده باشد، این بخش حاوی ورودی اصلی است).
commands: آرایه‌ای شامل نام‌های دستورهایی که اعمال شده‌اند.

exports: آرایه‌ای شامل مدخل‌هایی به ازای هر دستور "export" اعمال‌شده. هر مدخل دارای فیلدهای زیر است:

doc: رشته‌ای شامل محتوای سند تبدیل‌شده/برون‌ریزی‌شده
command: نام دستور اعمال‌شده

سه نوع دستور وجود دارد که نتایج آن‌ها به‌طور مستقل مدیریت می‌شود:

دستورهای "info" فراداده‌ها را از سند ورودی بازیابی می‌کنند
دستورهای "edit" سند را تغییر می‌دهند؛ دستورهای ویرایش بعدی تغییرات را به‌صورت زنجیره‌ای اعمال می‌کنند
دستورهای "export" که ورودی را به قالبی دیگر تبدیل می‌کنند. دستورهای بعدی تحت تأثیر نتیجهٔ دستورهای export قرار نمی‌گیرند.

دستورهای اطلاعاتی که اطلاعات را بازمی‌گردانند و فایل را تغییر نمی‌دهند:

mode: چاپ حالت سند (در صورت مشخص نشدن، حدس زده می‌شود)
version: چاپ نسخهٔ LilyPond، در صورتی که در سند تعیین شده باشد
language: چاپ زبان نام‌های زیروبمی، در صورتی که در سند تعیین شده باشد

دستورهایی که ورودی را تغییر می‌دهند:

indent: دندانه‌گذاری مجدد فایل
reformat: قالب‌بندی مجدد فایل
translate <language>: ترجمهٔ نام‌های زیروبمی به زبان مشخص‌شده
transpose <from> <to>: تغییر گام (ترانسپوز) فایل همان‌گونه که LilyPond انجام می‌دهد؛ زیروبمی‌ها به زبان 'nederlands' مشخص می‌شوند
abs2rel: تبدیل موسیقی مطلق به نسبی
rel2abs: تبدیل موسیقی نسبی به مطلق

دستورهایی که ورودی را به قالبی دیگر تبدیل می‌کنند:

musicxml: تبدیل به MusicXML (در حال توسعه، هنوز کامل نیست)
highlight: خروجی گرفتن از سند به صورت HTML رنگ‌آمیزی‌شده با برجسته‌سازی نحو

متغیرها (Variables)

متغیرهای زیر را می‌توان برای تأثیرگذاری بر رفتار دستورها تنظیم کرد. در صورت وجود مقدار پیش‌فرض، درون قلاب نوشته شده است:

mode: حالت ورودی برای خواندن (پیش‌فرض خودکار)؛ می‌تواند یکی از این موارد باشد: lilypond, scheme, latex, html, docbook, texinfo.
encoding [UTF-8]: کدگذاری برای خواندن (همچنین با آرگومان -e تنظیم می‌شود)
default-language [nederlands]: زبان نام‌های زیروبمی برای استفاده به‌صورت پیش‌فرض، هنگامی که در سند به گونهٔ دیگری مشخص نشده باشد
output-encoding: کدگذاری برای نوشتن (پیش‌فرض آن encoding است؛ همچنین با آرگومان --output-encoding تنظیم می‌شود)
indent-tabs [false]: استفاده از تب برای دندانه‌گذاری یا خیر
indent-width [2]: تعداد فاصله‌ها برای هر سطح دندانه‌گذاری (در صورت عدم استفاده از تب)
full-html [True]: در صورت تنظیم روی True، یک سند کامل به صورت HTML با برجسته‌سازی نحو صادر می‌شود، در غیر این صورت تنها محتوای خالص قرارگرفته در عنصری که توسط متغیرهای wrapper- پیکربندی شده است صادر خواهد شد.
stylesheet: نام فایل برای ارجاع به‌عنوان شیوه‌نامهٔ خارجی جهت HTML با برجسته‌سازی نحو. این نام فایل عیناً در برچسب <link rel="stylesheet"> استفاده می‌شود.
inline-style [false]: استفاده از صفت‌های سبک درون‌خطی برای HTML با برجسته‌سازی نحو یا خیر. به‌طور پیش‌فرض یک شیوه‌نامهٔ css تعبیه می‌شود.
number-lines [false]: افزودن شماره خطوط هنگام ایجاد HTML با برجسته‌سازی نحو یا خیر.
wrapper-tag [pre]: برچسبی که HTML با نحو برجسته‌شده در آن قرار می‌گیرد. مقادیر ممکن: div، pre، id و code
wrapper-attribute [class]: صفت مورد استفاده برای برچسب دربرگیرنده. مقادیر ممکن: id و class.
document-id [lilypond]: نام اعمال‌شده به wrapper-attribute. اگر سه گزینهٔ آخر از تنظیمات پیش‌فرض خود استفاده کنند، عناصر HTML برجسته‌شده درون عنصر <pre class="lilypond"></pre> قرار می‌گیرند.
linenumbers-id [linenumbers]: در صورت صادر شدن شماره خطوط، این نام برای عناصر <td> استفاده می‌شود

در اینجا اجرای پایه آمده است که روی پورت 5432 شنود می‌کند:

ly-server

مشخص کردن پورت و مهلت زمانی (timeout):

ly-server -p 4000 -t 5000

درخواست‌های نمونه (Sample Requests)

ساده‌ترین درخواست، فقط با اعمال یک دستور ویرایش. در این حالت نتیجه در result['doc']['content'] خواهد بود:

{
    'commands': [
        {
            'command': 'indent'
        }
    ],
    'data' : "\relative c' { c ( d e f ) }"
}

درخواست ساده‌ای دیگر، این بار با اعمال یک دستور "info". نتیجه در result['info'] خواهد بود که حاوی lilypond در فیلد info و mode در فیلد command است:

{
    'commands': [
        {
            'command': 'mode'
        }
    ],
    'data' : "\relative c' { c ( d e f ) }"
}

و مثالی پیچیده‌تر. این نمونه ابتدا سند را ترانسپوز کرده و سپس نسخهٔ ترانسپوزشده را به‌طور مستقل به HTML برجسته‌سازی‌شده (highlighted) و MusicXML تبدیل می‌کند. علاوه بر این، حالت (mode) را نیز بازیابی خواهد کرد. این بار نتیجه در هر سه مکان خواهد بود: سند ترانسپوزشده در doc.content، حالت در info.info، و HTML و MusicXML در exports[0].doc و exports[1].doc.:

{
    'commands': [
        {
            'command': 'transpose',
            'args': 'c d'
        },
        {
            'command': 'highlight',
            'variables': { 'full-html': 'false' }
        },
        { 'command': 'musicxml' },
        { 'command': 'mode' },
    ],
    'options': {
        'language': "deutsch"
    },
    'data': "\relative c' { c4 ( d e ) }"
}

Wilbert Berendsen

کپی‌رایت و تکثیر (COPYRIGHT)

2025, Wilbert Berendsen

April 4, 2026

0.9.10