عن المشروع

# bisql bisql هو محرك قوالب SQL ثنائي الاتجاه للغة Go. يتيح لك كتابة قوالب SQL تكون في نفس الوقت عبارات SQL صالحة (قابلة للتنفيذ في عميل SQL) ومنشئات استعلامات معلمة للتطبيقات. يتم التعبير عن التوجيهات كتعليقات SQL، بحيث يعمل النص نفسه في كلا السياقين. ## الميزات الرئيسية - **SQL ثنائي الاتجاه**: القوالب هي SQL صالحة؛ التوجيهات هي تعليقات. يعمل النص نفسه في عميل (مع قيم نموذجية) ويبني عبارات معلمة `(SQL, Args)` في Go. - **نموذج صريح**: لا إزالة ضمنية للجمل الفارغة أو الروابط المعلقة. يثبت المؤلفون الأجزاء الديناميكية (مثل `1 = 1`) لإخراج قابل للتنبؤ. - **التوجيهات**: الربط (`/* expr */literal`)، الإقحام الحرفي (`/*^ expr */literal`)، الشروط (`/*%if*/`, `/*%elseif*/`, `/*%else*/`, `/*%end*/`)، الحلقات (`/*%for x in xs*/`)، والتضمين (`/*%! @include name */`). - **تضمين الأجزاء**: أجزاء SQL قابلة لإعادة الاستخدام مكونة عبر `@include`، تُحل من `fs.FS`، سجلات في الذاكرة، أو محملات مخصصة. عودية مع حماية من الدورات/العمق. - **دعم اللهجات**: توليد العناصر النائبة لـ MySQL وSQLite وPostgreSQL وOracle وSQL Server. ربط المصفوفات لـ PostgreSQL. - **لغة التعبير**: تستخدم expr-lang للشروط والمتكررات، مع دعم المقارنة، العمليات المنطقية، الربط الاختياري، دمج القيم الفارغة، `in`، و`len`. - **آمنة بالتصميم**: لا استبدال نص خام لقيم عشوائية؛ يجب أن تكون المعرفات الديناميكية في القائمة البيضاء عبر فروع `/*%if*/`. ## الاستخدام القوالب هي ملفات `.sql`. حلل باستخدام `ParseFile` من أي `fs.FS` (مثل المضمن)، ثم ابنِ بخريطة معلمات أو بنية. ```go p := bisql.NewParser(bisql.WithDialect(dialect.PostgreSQL)) tmpl, err := p.ParseFile(sqlFS, "users/search.sql") stmt, err := tmpl.Build(map[string]any{"name": "Alice", "activeOnly": true, "status": "active"}) fmt.Println(stmt.SQL) // SQL معلمة fmt.Println(stmt.Args) // وسائط الربط ``` ## قواعد التأليف - ثبّت الأجزاء الديناميكية (مثل `1 = 1` لسلاسل `AND`، `1 = 0` لسلاسل `OR`). - للقوائم، استخدم روابط بادئة (`and`/`or`) أو `union all select` من بذرة صفرية الصفوف لقوائم الفواصل. - اقتبس السلاسل/المعرفات بمضاعفة معيار SQL؛ لا يُعترف بالهروب بالشرطة المائلة العكسية. - استخدم `/*%! … */` لتعليقات المحلل (تُزال) أو `/** … */` لتعليقات الكتل العادية. ## تخطيط الحزمة - `bisql`: واجهة برمجة التطبيقات العامة (Parser, Parse, Expand, loaders). - `dialect/`: تعريفات اللهجات. - `expr/`: واجهة المُقيّم وScope. - `internal/`: طبقة القوالب والمُقيّم الافتراضي. ## التطوير سلسلة الأدوات مثبتة في `mise.toml`؛ شغّل `mise run check` للتنسيق والبناء والفحص والتحليل والاختبارات. تتطلب اختبارات التكامل مع PostgreSQL علامة بناء وDSN. للوثائق الكاملة، راجع [مرجع Go](https://pkg.go.dev/github.com/mpyw/bisql).