\usepackage{ruby}
جمّع LaTeX إلى PDF من Ruby باستخدام FormaTeX REST API. باستخدام Net::HTTP القياسية، دون الحاجة إلى أي gem أو تثبيت TeX Live.
\section{لماذا Ruby}
واجهة FormaTeX API هي نقطة نهاية HTTPS بسيطة. استخدم المكتبة القياسية في Ruby، دون httparty ولا faraday ودون إضافة أي شيء إلى Gemfile.
أضف إجراء وحدة تحكم واحدًا إلى تطبيق Rails لبثّ ملفات PDF مباشرةً إلى المتصفح، دون الحاجة إلى مهمة في الخلفية للمستندات الصغيرة.
لا حاجة إلى إضافة TeX Live إلى Heroku buildpack أو صورة Docker. يتولى FormaTeX بنية التجميع التحتية بالكامل.
\section{البدء السريع}
يجمّع المثال أدناه مستند LaTeX بسيطًا ويكتب ملف PDF الناتج على القرص باستخدام Net::HTTP المضمَّنة في Ruby. استبدل FORMATEX_API_KEY بمفتاح من لوحة التحكم الخاصة بك.
require 'net/http'
require 'json'
require 'uri'
API_KEY = ENV.fetch('FORMATEX_API_KEY')
API_URL = URI.parse('https://api.formatex.io/api/v1/compile')
def compile_latex(source, engine: 'pdflatex')
http = Net::HTTP.new(API_URL.host, API_URL.port)
http.use_ssl = true
request = Net::HTTP::Post.new(API_URL.path)
request['X-API-Key'] = API_KEY
request['Content-Type'] = 'application/json'
request.body = { latex: source, engine: engine }.to_json
response = http.request(request)
raise "API error #{response.code}: #{response.body}" unless response.code == '200'
response.body
end
latex = <<~'LATEX'
\documentclass{article}
\usepackage{amsmath}
\begin{document}
Hello from Ruby! $E = mc^2$
\end{document}
LATEX
pdf = compile_latex(latex)
File.binwrite('output.pdf', pdf)
puts 'PDF saved to output.pdf'\section{التكامل مع Rails}
أضف DocumentsController إلى تطبيق Rails الخاص بك. يقبل الإجراء compile جسم JSON يتضمن الحقل source والحقل الاختياري engine، ثم يبثّ ملف PDF المجمَّع عبر send_data.
# app/controllers/documents_controller.rb
require 'net/http'
require 'json'
require 'uri'
class DocumentsController < ApplicationController
FORMATEX_URL = URI.parse('https://api.formatex.io/api/v1/compile').freeze
# POST /documents/compile
def compile
source = params.require(:source)
engine = params.fetch(:engine, 'pdflatex')
pdf_bytes = call_formatex(source, engine)
send_data pdf_bytes,
type: 'application/pdf',
disposition: 'inline',
filename: 'document.pdf'
rescue => e
render json: { error: e.message }, status: :unprocessable_entity
end
private
def call_formatex(source, engine)
http = Net::HTTP.new(FORMATEX_URL.host, FORMATEX_URL.port)
http.use_ssl = true
http.open_timeout = 5
http.read_timeout = 60
req = Net::HTTP::Post.new(FORMATEX_URL.path)
req['X-API-Key'] = ENV.fetch('FORMATEX_API_KEY')
req['Content-Type'] = 'application/json'
req.body = { latex: source, engine: engine }.to_json
res = http.request(req)
raise "FormaTeX error #{res.code}: #{res.body}" unless res.code == '200'
res.body
end
end\section{Authentication}
خزّن مفتاح API في البيئة ولا تضفه أبدًا إلى نظام التحكم في الإصدارات. استخدم ENV.fetch ليُصدر تطبيقك خطأً عند بدء التشغيل إذا كان المفتاح مفقودًا:
API_KEY = ENV.fetch( 'FORMATEX_API_KEY' )
Shell / .env
export FORMATEX_API_KEY=fmtx_…Rails credentials
rails credentials:editHeroku
heroku config:set FORMATEX_API_KEY=fmtx_…\section{Engines}
| المُجمِّع | الأنسب لـ |
|---|---|
| pdflatex | الخيار الافتراضي. سريع ومتوافق على نطاق واسع ومناسب لمعظم المستندات |
| xelatex | نصوص Unicode والخطوط المخصصة للنظام والكتابات العربية/CJK |
| lualatex | طباعة متقدمة، وبرمجة نصية بلغة Lua، والمستندات الكبيرة |
| latexmk | يشغّل تلقائيًا العدد الصحيح من الدورات لحل المراجع المتقاطعة |
\section{Reference}
| الحقل | النوع | مطلوب | الوصف |
|---|---|---|---|
| latex | string | نعم | شيفرة LaTeX المصدرية الكاملة كسلسلة نصية |
| engine | string | لا | المُجمِّع المستخدم. الافتراضي: "pdflatex". الخيارات: pdflatex، xelatex، lualatex، latexmk |
POST https://api.formatex.io/api/v1/compile — تُعيد بايتات PDF خامًا عند النجاح ( 200)، أو خطأ JSON عند الفشل (422/ 401).
\section{معالجة الأخطاء}
تحقق من response.code قبل قراءة الجسم. تُعيد واجهة API رموز حالة HTTP القياسية:
200: بايتات PDF خام. اقرأها عبر response.body .422: خطأ في تجميع LaTeX. يحتوي جسم JSON على الحقل error مع مقتطف من سجل TeX.401: مفتاح API غير صالح أو مفقود.\end{ruby}
احصل على مفتاح API واحصل على مخرجات PDF من Ruby في دقائق، دون الحاجة إلى TeX Live.