زنده و بدون رابط کاربری

سرور در هر فراخوانی، از طریق فایل‌های قفلی که ویرایشگرها در ~/.erd-editor/ide/ نگه می‌دارند، به دنبال ویرایشگری می‌گردد که سند را در اختیار دارد. هر پنجرهٔ VS Code و هر پنجرهٔ خزانهٔ Obsidian که ERD Editor دارد یک فایل قفل نگه می‌دارد، و یک IDE از JetBrains یک فایل قفل برای کل IDE نگه می‌دارد که همهٔ پروژه‌های باز در آن را فهرست می‌کند. ویرایشگر هنگام بسته شدن، فایل قفل خود را حذف می‌کند. آنچه سرور پیدا می‌کند تعیین می‌کند که ویرایش کجا انجام شود.

آنچه پیدا می‌کند	کاری که یک ویرایش انجام می‌دهد
ویرایشگری که فضای کاری، خزانه یا پروژهٔ باز آن سند را دربر دارد، یا سند را باز کرده است	زنده. در صورت نیاز سند را در ERD Editor باز می‌کند، به نشست ویرایش می‌پیوندد و تغییر را در آنجا اعمال می‌کند. ویرایش‌ها بی‌درنگ نمایان می‌شوند و همان‌طور ذخیره می‌شوند که ویرایشگر ویرایش‌های خودتان را ذخیره می‌کند؛ ذخیره کردن را ببینید.
هیچ ویرایشگری	بدون رابط کاربری. فایل را بارگذاری می‌کند، تغییر را اعمال می‌کند و فایل را جایگزین می‌کند. erd_save کاری برای انجام دادن ندارد.
ویرایشگری که هابش خاموش است	ردشده. خواندن‌ها همچنان کار می‌کنند و از روی دیسک انجام می‌شوند. تغییری که در حضور یک ویرایشگر باز در فایل نوشته شود، ممکن است با ذخیرهٔ بعدی آن ویرایشگر بازنویسی شود، پس سرور هیچ چیز نمی‌نویسد.
ویرایشگری که هابش روشن است اما پروتکلی جز پروتکل سرور به کار می‌برد: با سرور نسخهٔ 1.0.0، افزونهٔ VS Code نسخهٔ 3.x، پلاگین Obsidian نسخهٔ 0.x یا پلاگین JetBrains نسخهٔ 0.9.0 یا 0.10.0؛ با سروری پیش از نسخهٔ 1.0.0، افزونهٔ نسخهٔ 4.0.0 یا بالاتر یا پلاگین نسخهٔ 1.0.0 یا بالاتر	ردشده، حتی برای خواندن‌ها، با protocolMismatch. پیام سمتی را که باید به‌روزرسانی شود نام می‌برد: افزونه یا پلاگین، یا سرور؛ به‌روزرسانی را ببینید.
در Windows، ویرایشگری که سند را با مسیر دیگری به همان فایل در اختیار دارد: عامل آن را از طریق یک پوشهٔ اشتراکی شبکه یا یک درایو نگاشت‌شدهٔ همین رایانه نام برده است، مانند \\localhost\C$\…، و ویرایشگر آن را با مسیر درایوش در اختیار دارد، یا برعکس	ردشده، حتی برای خواندن‌ها، با invalidPath. پیام مسیری را که ویرایشگر سند را با آن در اختیار دارد نام می‌برد؛ با همان مسیر دوباره فراخوانی کنید.
در Windows، ویرایشگری که Windows عامل را از آن دور نگه می‌دارد: ویرایشگری که با دسترسی مدیر سیستم اجرا شده در حالی که عامل این‌گونه اجرا نشده است، یا هر ویرایشگری وقتی عامل در یک سندباکس اجرا می‌شود	ردشده، حتی برای خواندن‌ها، با hubUnreachable و پیامی که دلیل را می‌گوید. ویرایشگر و عامل را با دسترسی‌های یکسان اجرا کنید، برای نمونه با اجرای دوبارهٔ ویرایشگر بدون دسترسی مدیر سیستم.

نتیجهٔ یک ویرایش حالتی را که در آن اجرا شده است، یعنی live یا headless، نام می‌برد و ویرایش ردشده دلیلش را می‌گوید. این جست‌وجو در هر فراخوانی دوباره انجام می‌شود، پس باز کردن یا بستن یک ویرایشگر، مقصد فراخوانی بعدی را هم با خود تغییر می‌دهد.

وقتی بیش از یک ویرایشگر سند را در اختیار دارد، ویرایشگری که آن را باز کرده است بر ویرایشگری که فقط به پوشهٔ دربرگیرندهٔ آن سرویس می‌دهد مقدم است، و از میان ویرایشگرهایی که به یک پوشه سرویس می‌دهند، آنکه پوشه‌اش در عمیق‌ترین سطح قرار دارد مقدم است. در حالت برابری، مانند دو ویرایشگری که هر دو سند را باز کرده‌اند، سند به ویرایشگری می‌رسد که فایل قفلش آخر از همه تغییر کرده است. بنابراین سندی در یک خزانهٔ Obsidian که درون پوشهٔ فضای کاری VS Code قرار دارد به Obsidian می‌رسد، مگر اینکه VS Code آن را باز کرده باشد و Obsidian نه.

فراخوانی‌های روی یک سند یکی‌یکی و به ترتیبی که به سرور رسیده‌اند اجرا می‌شوند. فراخوانی‌های روی اسناد مختلف هم‌زمان اجرا می‌شوند.

زنده

عامل مانند یک همکار دیگر به ویرایشگر می‌پیوندد. ویرایش‌هایش بی‌درنگ به همهٔ ویرایشگرهایی می‌رسد که سند را باز کرده‌اند، و فوکوس آن روی جدول و خانه‌ای که در حال ویرایش آن است نشان داده می‌شود، همان‌طور که فوکوس یک همکار نشان داده می‌شود؛ focusTracker را ببینید.

خواندن هرگز ویرایشگری را باز نمی‌کند. ویرایش، اگر سند هنوز باز نشده باشد، آن را بدون گرفتن فوکوس صفحه‌کلید در ERD Editor باز می‌کند.

ذخیره کردن

هر ویرایشگر ویرایش‌های عامل را به همان شیوه‌ای ذخیره می‌کند که ویرایش‌های خودتان را ذخیره می‌کند.

در VS Code، ویرایش‌های عامل مانند ویرایش‌های خودتان زبانه را در وضعیت ذخیره‌نشده قرار می‌دهند و فقط وقتی سند ذخیره شود به دیسک می‌رسند. erd_save آن را از طریق VS Code ذخیره می‌کند، همان‌طور که فرمان ذخیرهٔ خود VS Code این کار را می‌کند. می‌توانید به‌جای آن خودتان با Ctrl + S (Windows/Linux) یا ⌘ + S (Mac) ذخیره کنید. بستن ویرایشگر در حالی که ویرایش‌های ذخیره‌نشدهٔ عامل در آن وجود دارد، مانند هر تغییر ذخیره‌نشدهٔ دیگری، می‌پرسد که آیا آن‌ها ذخیره شوند.

Obsidian ویرایش‌های عامل را حدود دو ثانیه پس از توقف ویرایش ذخیره می‌کند، و بستن زبانه آن‌ها را بدون پرسیدن ذخیره می‌کند. یک IDE از JetBrains آن‌ها را کسری از ثانیه پس از توقف ویرایش می‌نویسد، و بستن زبانه آنچه را هنوز در انتظار است می‌نویسد؛ زبانه هرگز تغییریافته نشان داده نمی‌شود. در هر دو، erd_save آن‌ها را بی‌درنگ می‌نویسد.

erd_save ابتدا حداکثر دو ثانیه صبر می‌کند تا ویرایشگر همهٔ ویرایش‌هایی را که عامل انجام داده است در اختیار داشته باشد. وقتی ویرایشگر نتوانسته باشد این را تأیید کند، یا فایل را ننوشته باشد، با notSaved رد می‌شود: VS Code وقتی فایل روی دیسک تغییر کرده باشد زبانه را ذخیره‌نشده نگه می‌دارد، و یک IDE از JetBrains نتوانسته است فایل را بنویسد، مانند زمانی که یک کادر گفت‌وگو باز بوده یا وقتی که نمی‌توان در فایل نوشت.

در VS Code و یک IDE از JetBrains، erd_save روی سندی که چیزی برای ذخیره کردن در آن باقی نمانده است موفق می‌شود و فایل را همان‌طور که هست باقی می‌گذارد. این وضعیت زمانی پیش می‌آید که همهٔ ویرایش‌ها ذخیره شده باشند، کاری که یک IDE از JetBrains خودش انجام می‌دهد، و تا زمانی پابرجا می‌ماند که هر تغییر بعدی از نوعی باشد که یک قفل آن را از فایل دور نگه می‌دارد، مانند پیمایش یا بزرگ‌نمایی وقتی Viewport قفل است، یا جابه‌جایی میان زبانه‌ها وقتی Canvas Type قفل است. همهٔ قفل‌ها به‌طور پیش‌فرض روشن هستند. فایلی که یک IDE از JetBrains نمی‌تواند در آن بنویسد، حتی در این حالت هم رد می‌شود.

وقتی ویرایشگر پس از آخرین ویرایش عامل سند را ببندد، فراخوانی بعدی عامل نکته‌ای همراه دارد که می‌گوید آن ویرایش‌ها فقط در صورتی در فایل هستند که پیش از بسته شدن ویرایشگر ذخیره شده باشند.

واگرد

erd_undo آخرین ویرایشی را که عامل انجام داده است واگرد می‌کند و هرگز به ویرایش‌های خودتان دست نمی‌زند، و erd_redo آن را دوباره اعمال می‌کند. واگرد خود ویرایشگر برعکس کار می‌کند: ویرایش‌های خودتان را واگرد می‌کند و هرگز ویرایش‌های عامل را واگرد نمی‌کند، زیرا تغییراتی که از ویرایشگر دیگری می‌رسند در تاریخچهٔ شما ثبت نمی‌شوند.

چند ویرایش در ویرایشگر هیچ مدخل واگردی ثبت نمی‌کنند: erd_set_database و erd_set_database_name از میان ابزارهای تنظیمات، و erd_resize_memo. فراخوانی erd_move_table_group هم که گروه را در مجموع، یعنی جابه‌جایی افقی و عمودی با هم جمع‌شده، کمتر از 20 پیکسل جابه‌جا کند، مدخلی ثبت نمی‌کند، هرچند گروه در جای جدیدش باقی می‌ماند. فراخوانی‌ای که هیچ چیزی را تغییر ندهد هم مدخلی ثبت نمی‌کند: erd_set_column_primary_key، erd_set_column_unique، erd_set_column_not_null، erd_set_column_auto_increment، erd_set_index_unique یا erd_set_index_column_order وقتی مقداری را تنظیم کنند که سند از قبل دارد؛ erd_add_index_column با ستونی که از قبل در شاخص است؛ erd_set_table_group با جدول‌هایی که از قبل در همان گروه‌اند (یا با groupId برابر null، جدول‌هایی که از قبل در هیچ گروهی نیستند)؛ erd_move_table_group به نقطه‌ای که گروه از قبل در آن قرار دارد؛ erd_resize_table_group به مستطیلی که گروه از قبل دارد؛ erd_sort_tables روی سندی که هیچ جدولی ندارد؛ یا یک وارد کردن با mode برابر append که هیچ جدولی نمی‌آورد (برای erd_import_json، هیچ جدول و هیچ یادداشتی). erd_undo این‌ها را نادیده می‌گیرد و در نتیجهٔ خود نامشان را ذکر می‌کند. ویرایش‌های دیگر، مانند erd_change_relationship_type، erd_change_relationship_on_delete، erd_change_relationship_on_update، erd_change_table_group_name، erd_change_table_group_color و erd_set_ddl_script، حتی وقتی مقداری را تنظیم کنند که سند از قبل دارد، یک مدخل ثبت می‌کنند.

تاریخچهٔ واگرد عامل، همراه با نکته‌ای در نتیجه، در این موارد پایان می‌یابد:

• عامل دوباره به سند می‌پیوندد، برای نمونه پس از آنکه ویرایشگر عامل را از سند جدا کرده است.
• ویرایشگر از اجرا خارج می‌شود، یا سند را می‌بندد و دیگر به آن سرویس نمی‌دهد، و عامل ویرایش فایل را روی دیسک ادامه می‌دهد.
• ویرایشگری سندی را که عامل روی دیسک ویرایش می‌کرد در اختیار می‌گیرد.

سرور همچنین سندی را که عامل 30 دقیقه هیچ فراخوانی‌ای روی آن انجام نداده است می‌بندد، و تاریخچهٔ واگرد هم بدون هیچ نکته‌ای همراه آن از بین می‌رود.

وقتی ویرایشگر از دسترس خارج می‌شود

تا وقتی ویرایشگری سندی را در اختیار دارد، سرور هرگز خودبه‌خود به فایل روی نمی‌آورد. اگر اتصال قطع شود، دوباره متصل می‌شود. سرور فقط وقتی فایل را ویرایش می‌کند که ویرایشگر از اجرا خارج شده باشد، یا سند را بسته باشد و دیگر نه آن را فهرست کند و نه پوشه‌ای را که آن را دربر دارد، و این را در نتیجه اعلام می‌کند. این زمانی رخ می‌دهد که نموداری را ببندید که بیرون از همهٔ پوشه‌هایی است که ویرایشگر به آن‌ها سرویس می‌دهد (در VS Code، نموداری که از بیرون فضای کاری باز شده است)، وقتی پلاگین ERD Editor را در Obsidian خاموش کنید، و وقتی پروژه‌ای را که سند را دربر دارد در یک IDE از JetBrains ببندید یا پلاگین را در آنجا خاموش کنید. نمودار بسته‌شده‌ای که درون پوشه‌ای است که ویرایشگر به آن سرویس می‌دهد نزد ویرایشگر می‌ماند، و ویرایش بعدی عامل آن را دوباره باز می‌کند.

ویرایشگری که هنوز در حال اجراست، اما فایل قفلش از بین رفته و اتصالش بدون آنکه سند را ببندد بسته شده است، ویرایش بعدی را با hubGone رد می‌کند. پیام می‌گوید چه چیزی سند را آزاد می‌کند: در VS Code، آن پنجره را دوباره بارگذاری کنید، یا آن را ببندید تا عامل بتواند فایل را مستقیماً ویرایش کند؛ در Obsidian، پلاگین ERD Editor را دوباره روشن کنید، یا آن پنجره را ببندید؛ در یک IDE از JetBrains، پلاگین را دوباره روشن کنید، یا از IDE خارج شوید.

در دو حالت، خواندن به‌جای آن به سراغ فایل روی دیسک می‌رود، همراه با نکته‌ای مبنی بر اینکه ویرایش‌هایی که هنوز در ویرایشگر ذخیره نشده‌اند در آن نیستند: وقتی هاب ویرایشگری که سند را در اختیار دارد خاموش است، و در حالت hubGone که در بالا آمد. خواندنی که نتواند به هاب یک ویرایشگر متصل شود، مانند یک ویرایش، با hubUnreachable رد می‌شود.

بدون رابط کاربری

وقتی هیچ ویرایشگری به سند سرویس نمی‌دهد، هر ویرایش فایل را بارگذاری می‌کند، تغییر را اعمال می‌کند و فایل را دوباره می‌نویسد. نوشتن در یک فایل موقت کنار سند با نام .<name>.<id>.tmp انجام می‌شود که سپس جایگزین سند می‌شود، پس سند هرگز نیمه‌نوشته باقی نمی‌ماند، جز در Windows در حالت نوشتن درجا که در ادامه توضیح داده شده است.

پیش از آن گام آخر، سرور بررسی می‌کند که آیا فایل در طول فراخوانی روی دیسک تغییر کرده است یا نه. اگر تغییر کرده باشد، هیچ چیز نوشته نمی‌شود، فایل دوباره بارگذاری می‌شود و فراخوانی با conflict رد می‌شود. عامل دوباره فراخوانی می‌کند. فایلی که میان دو فراخوانی تغییر کرده باشد فقط دوباره بارگذاری می‌شود، و تاریخچهٔ واگرد عامل مربوط به پیش از آن کنار گذاشته می‌شود.

فایل فقط خواندنی همان‌طور که هست باقی می‌ماند و ویرایش با readonly رد می‌شود: فایلی که مالکش اجازهٔ نوشتن در آن را ندارد، یا در Windows ویژگی فقط خواندنی دارد، مانند فایلی از Perforce یا TFVC که چک‌اوت نشده است. آن را قابل نوشتن کنید، سپس دوباره فراخوانی کنید. خواندن‌ها همچنان کار می‌کنند.

اگر ویرایشگری در حالی که عامل سند را روی دیسک ویرایش می‌کند شروع به سرویس دادن به آن کند، همان یک ویرایش با hubAppeared رد می‌شود و هیچ چیز نوشته نمی‌شود. فراخوانی بعدی از طریق ویرایشگر ویرایش می‌کند.

در Windows دو قاعدهٔ دیگر هم اعمال می‌شود:

• سندی که مجوزهای خاص خود را دارد، متفاوت با مجوزهای پوشه‌اش، به‌جای جایگزین شدن درجا نوشته می‌شود تا آن مجوزها را حفظ کند، و فایل موقت پس از آن حذف می‌شود. برنامه‌ای که در طول این نوشتن سند را بخواند ممکن است به متنی برسد که قابل تجزیه نیست.
• فایلی را که برنامهٔ دیگری باز نگه داشته است نمی‌توان جایگزین کرد، پس سرور تا دو ثانیه دوباره تلاش می‌کند. هر تلاش ابتدا دوباره به دنبال ویرایشگر می‌گردد، و ویرایشگری که در این فاصله شروع به سرویس دادن به سند کرده باشد نوشتن را با hubAppeared رد می‌کند، یا وقتی هابش خاموش است با blocked. اگر فایل پس از دو ثانیه هنوز باز نگه داشته شده باشد، هیچ چیز نوشته نمی‌شود، فایل دوباره بارگذاری می‌شود و فراخوانی با پیامی که خطای سیستم را نقل می‌کند شکست می‌خورد.

ردشده

یک پنجرهٔ VS Code حتی وقتی هابش خاموش است فایل قفلش را نگه می‌دارد: وقتی dineug.erd-editor.agentHub.enabled خاموش است، وقتی فضای کاری مورد اعتماد نیست، یا وقتی هابش نتوانسته است به اتصال‌ها گوش دهد. یک پنجرهٔ خزانهٔ Obsidian وقتی گزینهٔ Coding agents خاموش است، و وقتی هابش نتوانسته است به اتصال‌ها گوش دهد، فایل قفلش را با هاب خاموش نگه می‌دارد. یک IDE از JetBrains وقتی گزینهٔ Coding agents خاموش است، وقتی هابش نتوانسته است به اتصال‌ها گوش دهد، و تا وقتی IDE در حال خروج است، فایل قفلش را با هاب خاموش نگه می‌دارد.

ویرایش چنین سندی با blocked رد می‌شود، زیرا ویرایشگر باز ممکن است تغییری را که در فایل نوشته شده است در ذخیرهٔ بعدی خود بازنویسی کند. خواندن‌ها همچنان کار می‌کنند و از فایل روی دیسک انجام می‌شوند.

برای اینکه عامل بتواند ویرایش کند، هاب را همان‌طور که پیام برای آن ویرایشگر می‌گوید دوباره روشن کنید: در VS Code، به فضای کاری اعتماد کنید و تنظیم را روشن کنید، یا پنجره را دوباره بارگذاری کنید؛ در Obsidian، گزینهٔ Coding agents را روشن کنید، یا Obsidian را دوباره بارگذاری کنید؛ در یک IDE از JetBrains، گزینهٔ Coding agents را روشن کنید، یا اگر از قبل روشن است IDE را دوباره راه‌اندازی کنید.

یک IDE از JetBrains همچنین تغییر سندی را که فقط در اختیار پروژه‌هایی است که به آن‌ها اعتماد ندارد، با hubDisabled رد می‌کند. عامل‌ها همچنان می‌توانند چنین سندی را بخوانند، و erd_list_documents آن را به‌صورت readonly فهرست می‌کند. به پروژه اعتماد کنید، سپس دوباره فراخوانی کنید.

ویرایشگری که هیچ فایل قفلی نگه نمی‌دارد از هیچ چیز محافظت نمی‌کند، و عامل فایل را روی دیسک ویرایش می‌کند، حتی وقتی نمودار در آن ویرایشگر باز است. این وضعیت برای Obsidian یا یک IDE از JetBrains که به‌صورت Flatpak در Linux نصب شده باشد، یک IDE از JetBrains بدون JCEF، و یک IDE از JetBrains که هابش نتوانسته است شروع به کار کند صدق می‌کند؛ راه‌اندازی Obsidian و راه‌اندازی یک IDE از JetBrains را ببینید. افزونهٔ VS Code پیش از نسخهٔ 3.0.0 و پلاگین JetBrains پیش از نسخهٔ 0.9.0 هم هیچ فایل قفلی نگه نمی‌دارند، چون هابی ندارند.

اسناد

هر سند با path مشخص می‌شود که مطلق یا نسبت به پوشهٔ کاری سرور است.

• اسناد جدید فایل‌های .erd.json هستند. erd_open_document با create فایل را می‌سازد و به نامی که پسوند ندارد .erd.json را می‌افزاید. مانند یک نمودار جدید در ویرایشگر، در سند جدید هر قفل روشن است، پس پیمایش، بزرگ‌نمایی، جابه‌جایی میان زبانه‌ها یا انتخاب زبان کد، شیوهٔ نگارش نام یا نوع علامت نقل‌قول دیگری در یک ویرایشگر هرگز فایل را تغییر نمی‌دهد. هیچ ابزاری یک قفل را به‌تنهایی روشن یا خاموش نمی‌کند: این کار را در زبانهٔ تنظیمات ویرایشگر انجام می‌دهید. erd_import_json در حالت replace همهٔ آن‌ها را با قفل‌های سندی که بارگذاری می‌کند جایگزین می‌کند؛ وارد کردن را ببینید.
• فایل‌های موجود .erd، .vuerd و .vuerd.json هم باز می‌شوند. مسیری با هر پسوند دیگری با invalidPath رد می‌شود.
• در Windows، مسیری که نامی دارد که Windows آن را همان‌طور که نوشته شده ذخیره نمی‌کند، پیش از خواندن یا نوشتن سند با invalidPath رد می‌شود، حتی برای خواندن: نامی با دونقطه یا نویسهٔ دیگری که Windows نمی‌پذیرد، مانند orders:v2.erd؛ نام یک دستگاه مانند NUL.erd یا CON.erd، با هر بزرگی و کوچکی حروف؛ یا نامی که به نقطه یا فاصله ختم می‌شود. نام آن را تغییر دهید، برای نمونه با - به‌جای :.
• فایلی که سندی نیست که ویرایشگر بتواند بخواند، مانند فایلی که نشانگرهای تعارض ادغام در آن باقی مانده است، با invalidDocument رد می‌شود و همان‌طور که هست باقی می‌ماند. چنین فایلی هرگز به‌صورت نمودار خالی بارگذاری و دوباره نوشته نمی‌شود.

عامل سند را فقط از طریق ابزارها تغییر می‌دهد و به آن گفته می‌شود که هرگز خودش در فایل ننویسد.

erd_list_documents اسناد را با path، open، active، dirty و readonly فهرست می‌کند. این ابزار از ویرایشگری که به پوشهٔ کاری سرویس می‌دهد و به همان شیوهٔ انتخاب ویرایشگر برای یک سند انتخاب می‌شود پرس‌وجو می‌کند، و ابتدا نمودارهای باز در آن را فهرست می‌کند و سپس فایل‌های ERD که به آن‌ها سرویس می‌دهد: فایل‌های درون پوشه‌های فضای کاری یک پنجرهٔ VS Code، درون یک خزانهٔ Obsidian، یا درون همهٔ پروژه‌های باز در یک IDE از JetBrains. در غیر این صورت، فایل‌های ERD زیر پوشهٔ کاری را فهرست می‌کند، که در آن فایل فقط خواندنی با readonly علامت‌گذاری می‌شود و در Windows، نامی که Windows آن را همان‌طور که نوشته شده ذخیره نمی‌کند کنار گذاشته می‌شود.