\usepackage{ruby}

واجهة API لتحويل LaTeX إلى PDF بلغة Ruby

جمّع LaTeX إلى PDF من Ruby باستخدام FormaTeX REST API. باستخدام Net::HTTP القياسية، دون الحاجة إلى أي gem أو تثبيت TeX Live.

Also available in:Python·Node.js·Go·PHP·Ruby·Rust·cURL|Full API reference

\section{لماذا Ruby}

لماذا Ruby + FormaTeX

لا حاجة إلى أي gem

واجهة FormaTeX API هي نقطة نهاية HTTPS بسيطة. استخدم المكتبة القياسية في Ruby، دون httparty ولا faraday ودون إضافة أي شيء إلى Gemfile.

Rails-ready

أضف إجراء وحدة تحكم واحدًا إلى تطبيق Rails لبثّ ملفات PDF مباشرةً إلى المتصفح، دون الحاجة إلى مهمة في الخلفية للمستندات الصغيرة.

دون تضمين ملفات تنفيذية

لا حاجة إلى إضافة TeX Live إلى Heroku buildpack أو صورة Docker. يتولى FormaTeX بنية التجميع التحتية بالكامل.

\section{البدء السريع}

البدء السريع

يجمّع المثال أدناه مستند LaTeX بسيطًا ويكتب ملف PDF الناتج على القرص باستخدام Net::HTTP المضمَّنة في Ruby. استبدل FORMATEX_API_KEY بمفتاح من لوحة التحكم الخاصة بك.

compile.rb
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}

وحدة تحكم Rails

أضف DocumentsController إلى تطبيق Rails الخاص بك. يقبل الإجراء compile جسم JSON يتضمن الحقل source والحقل الاختياري engine، ثم يبثّ ملف PDF المجمَّع عبر send_data.

app/controllers/documents_controller.rb
# 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:edit

Heroku

heroku config:set FORMATEX_API_KEY=fmtx_…

\section{Engines}

اختيار المُجمِّع

المُجمِّعالأنسب لـ
pdflatexالخيار الافتراضي. سريع ومتوافق على نطاق واسع ومناسب لمعظم المستندات
xelatexنصوص Unicode والخطوط المخصصة للنظام والكتابات العربية/CJK
lualatexطباعة متقدمة، وبرمجة نصية بلغة Lua، والمستندات الكبيرة
latexmkيشغّل تلقائيًا العدد الصحيح من الدورات لحل المراجع المتقاطعة

\section{Reference}

مرجع API

الحقلالنوعمطلوبالوصف
latexstringنعمشيفرة LaTeX المصدرية الكاملة كسلسلة نصية
enginestringلاالمُجمِّع المستخدم. الافتراضي: "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}

ابدأ تجميع LaTeX من Ruby

احصل على مفتاح API واحصل على مخرجات PDF من Ruby في دقائق، دون الحاجة إلى TeX Live.