Prawn: быстрое и гибкое создание PDF на Ruby

Prawn — это библиотека для создания PDF-файлов на чистом Ruby, которая предоставляет множество полезных функций, при этом оставаясь простой и достаточно производительной. Вот некоторые из важных возможностей, которые мы предоставляем:

• Поддержка векторного рисования, включая линии, многоугольники, кривые, эллипсы и т. д.
• Обширная поддержка рендеринга текста, включая плавный текст и ограниченные возможности форматирования в тексте.
• Поддержка встроенных шрифтов PDF, а также встраиваемых шрифтов TrueType.
• Разнообразные инструменты для базовых потребностей в макете, включая простую систему сетки.
• Встраивание изображений PNG и JPG с гибкими возможностями масштабирования.
• Функции безопасности, включая шифрование и защиту паролем.
• Инструменты для рендеринга повторяющегося контента (например, заголовки, нижние колонтитулы и номера страниц).
• Комплексные функции интернационализации, включая полную поддержку шрифтов на основе UTF-8, рендеринг текста справа налево, поддержку резервных шрифтов и точки расширения для настраиваемого переноса текста.
• Поддержка контуров PDF для навигации по документу.
• Низкоуровневые функции PDF, позволяющие пользователям создавать собственные расширения, опускаясь до уровня дерева объектов PDF. (В основном полезно для тех, кто знаком со спецификацией PDF.)
• И многое другое!

Стоит ли использовать Prawn?

Если вы ищете гибкую систему создания PDF-документов, Prawn может быть подходящим инструментом для вас. Это не инструмент для создания отчётов или цепочки инструментов для публикации, хотя его можно довольно легко использовать для их создания.

Одна вещь, которой Prawn не является и никогда не будет, — это генератор HTML в PDF. Для этих нужд рассмотрите использование FlyingSaucer через JRuby или один из инструментов на базе WebKit, таких как Wicked или PDFKit. У нас есть базовая поддержка встроенного стиля, но она ограничена очень небольшим набором функций и не подходит для рендеринга богатых HTML-документов.

Поддерживаемые версии Ruby и реализации

Поскольку Prawn написан на чистом Ruby и все его зависимости во время выполнения поддерживаются нами, он должен работать практически везде. Мы официально поддерживаем все версии Ruby, поддерживаемые Ruby Core Team, и версии JRuby, соответствующие версии Ruby. Однако мы примем патчи для исправления проблем на других платформах Ruby, если они не слишком инвазивны.

Установка Prawn

Prawn распространяется через RubyGems, и его можно установить обычным способом установки гемов: просто набрав gem install prawn в командной строке.

Вы также можете установить его из git, если хотите. В ветке master содержатся последние разработки. Мы стараемся поддерживать ветку master в рабочем состоянии, но вы можете столкнуться с некоторыми шероховатостями и свежими ошибками вместе с исправлениями. Мы рекомендуем вам попробовать ветку master с вашим приложением.

Hello World!

Если следующий код выполняется и создаёт рабочий файл PDF, значит, вы успешно установили Prawn.

require "prawn"

Prawn::Document.generate("hello.pdf") do
  text "Hello World!"
end

Конечно, вы, вероятно, захотите сделать что-то более интересное...

Руководство пользователя

Руководство представляет собой серию примеров, демонстрирующих использование широкого спектра функций, предоставляемых Prawn. Вы можете получить сгенерированную версию последней выпущенной версии Prawn на веб-сайте Prawn. Сами примеры можно найти в каталоге manual этого репозитория.

Обратите внимание, что, хотя руководство является отличным введением и руководством по Prawn, оно не исчерпывающее. Пожалуйста, обратитесь к документации API для получения более полной информации о том, что предоставляет Prawn и как его использовать.

Чтобы создать руководство, вот что вам нужно сделать:

1. Клонировать репозиторий.
2. Запустить gem install -g.
3. Запустить rake manual, который создаст manual.pdf. Ruby, что позволяет вам выбирать между условиями Матца, GPLv2 или GPLv3. Для получения подробной информации обратитесь к файлам LICENSE, GPLv2 и GPLv3.

Если вы вносите свой вклад в Prawn, вы сохраняете свои авторские права, но должны согласиться лицензировать свой код на тех же условиях, что и сам проект.

История

Prawn изначально был разработан Грегори Брауном под эгидой Ruby Mendicant Project — народной инициативы, в рамках которой сообщество Ruby коллективно предоставило финансирование, чтобы Грегори мог взять несколько месяцев отпуска от работы и сосредоточиться на этом проекте.

За последние несколько лет мы получили вклады кода от десятков людей, что удивительно, учитывая низкоуровневый характер этого проекта. Вы можете найти полный список людей, у которых есть хотя бы один принятый патч для Prawn на странице GitHub Contributors.

После длительного периода бездействия Prawn достиг своего рубежа 1.0 в 2014 году благодаря небольшому финансированию, предоставленному Грегори компанией Madriska, Inc. (компания Брэда Эйджера).