texd 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 676222ee01af1a31facb86ee1a4416f4f5b3307e0c8e7de9b6ee7357b5e8a838
-  data.tar.gz: 153a30b56379209ba62ec860de87ae3fc6dd322b6828df73557bef90cb526bc9
+  metadata.gz: 8f90c7123f60872130f0a2c36a6a6fa44154d1e3956c140f45e07e6815761363
+  data.tar.gz: a1c855d5a76517dae7eb2c5a2a9cc9be621236fa59018e62fbeeaa9b31ee0d49
 SHA512:
-  metadata.gz: 210eab22723d4f043cad09601022fa577769a3235bbbac5984c538594d83015559b2f1d92d8f537cd230e301fc97425c75aca12a310d210f60ff85a05b3e0df8
-  data.tar.gz: 82c1ebfedabb268f92871ad707aa0b1d611440bb641a134a449e112eac76d24476e3ddcf25c788b6620b364650085e09a2e5ffad0a8fcc4592b04e953d2583c5
+  metadata.gz: ecc5d22800aea0f4b77e76c0c052106cb80bb47c3c3a478696c712957fbc178ac74c7014d3927ff09bd45c4472a167fc8ebd7bcbd9ff154f12c90f2724df319d
+  data.tar.gz: 88dad14c7c7f95fbb53bb12bd9777de8033d8b8aceafe896efabcf8f0c33463ece25b90ef43e2e3108c617586007171c498a969fe7184763d73812cf35ed0cf4

data/.rubocop.yml

@@ -288,7 +288,9 @@ Style/RedundantAssignment:
   Enabled: true
 
 Style/RedundantFetchBlock:
-  Enabled: true
+  Enabled: false
+  Exclude:
+    - spec/lib/texd/cache_spec.rb # not called on Hash
 
 Style/RedundantFileExtensionInRequire:
   Enabled: true

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    texd (0.2.0)
+    texd (0.3.0)
       multipart-post (~> 2.0)
       rails (>= 6.0, < 8)
 

data/Makefile

@@ -50,5 +50,5 @@ texd-docker:
 		-p 127.0.0.1:2201:2201 \
 		-v $$(pwd)/tmp/jobs:/texd \
 		-v $$(pwd)/tmp/refs:/refs \
-		--user=$(id -u):$(id -g) \
+		--user=$$(id -u):$$(id -g) \
 			digineode/texd --reference-store dir:///refs

data/README.md

@@ -2,6 +2,10 @@
 
 texd is a Ruby client for the [texd web service](https://github.com/digineo/texd).
 
+It leverages ActionView's template rendering mechanism to compile `.tex`
+templates to PDF documents. The primary use case is to render documents
+in background jobs.
+
 ## Installation
 
 You need to meet the following requirements for this gem to work:
@@ -34,11 +38,15 @@ end
 
 ```rb
 Texd.configure do |config|
-  config.endpoint     = ENV.fetch("TEXD_ENDPOINT", "http://localhost:2201/")
-  config.error_format = ENV.fetch("TEXD_ERRORS", "full")
-  config.tex_engine   = ENV["TEXD_ENGINE"]
-  config.tex_image    = ENV["TEXD_IMAGE"]
-  config.helpers      = []
+  config.endpoint      = ENV.fetch("TEXD_ENDPOINT", "http://localhost:2201/")
+  config.open_timeout  = ENV.fetch("TEXD_OPEN_TIMEOUT", 60)
+  config.read_timeout  = ENV.fetch("TEXD_READ_TIMEOUT", 180)
+  config.write_timeout = ENV.fetch("TEXD_WRITE_TIMEOUT", 60)
+  config.error_format  = ENV.fetch("TEXD_ERRORS", "full")
+  config.tex_engine    = ENV["TEXD_ENGINE"]
+  config.tex_image     = ENV["TEXD_IMAGE"]
+  config.helpers       = []
+  config.lookup_paths  = [] # Rails.root.join("app/tex") is always inserted as first entry
 end
 ```
 
@@ -56,8 +64,115 @@ about other installation methods.
 
 ## Usage
 
-> TODO. See https://github.com/amagical-net/rails-latex#label-Synopsis
-> in the meantime.
+First, create a few files:
+
+<details><summary><code>app/views/layouts/application.tex.erb</code></summary>
+
+This is the default layout. Here, you should define a `\documentclass`
+and use `yield`. In this example, we're using ERB (Erubi) to include
+dynamic content into a `.tex` file.
+
+```erb
+\documentclass{article}
+\usepackage{graphicx}
+<%= content_for :preamble %>
+
+\begin{document}
+<%= yield %>
+\end{document}
+```
+
+</details>
+<details><summary><code>app/views/document/doc.tex.erb</code></summary>
+
+In `document/doc.tex`, we're specifying some stuff for the preamble,
+render a partial, and add content for the document:
+
+```erb
+<% content_for :preamble do %>
+\usepackage{blindtext}
+
+\title{Demo document}
+\date{\today}
+\author{<%= user.full_name %>}
+<% end %>
+
+<%= render partial: "document/title_page" %>
+
+\Blinddocument
+```
+
+OK, that wasn't true. We're leveraging the `blindtext` package to add
+content for us :)
+
+The `user` variable is passed as local method to `Texd.render` (see below).
+
+</details>
+<details><summary><code>app/views/document/_title_page.tex.erb</code></summary>
+
+This partial embeds an image and creates the title page.
+
+```erb
+\begin{center}
+  \includegraphics[width=0.5\linewidth]{<%= texd_attach "logo.png" %>}
+\end{center}
+
+\titlepage
+```
+
+With `texd_attach`, we're referencing a file *outside* ActionView's lookup
+paths, but in Texd's lookup paths (`RAILS_ROOT/app/tex` by default).
+
+You can use this directory to store and deploy static assets.
+
+Please be aware, that attachments will be renamed (`att00123.png`)
+in the POST body, and `att00123.png` will be returned from `texd_attach`.
+You can skip the renaming, if you want/need to:
+
+```erb
+% attaches RAILS_ROOT/app/tex/logo.png, and inserts "logo.png":
+<%= texd_attach "logo.png", rename: false %>
+
+% attaches RAILS_ROOT/app/tex/logo.png, and inserts "assets/logo.png":
+<%= texd_attach "logo.png", rename: "assets/logo.png" %>
+
+% attaches RAILS_ROOT/app/tex/common.tex, and inserts "att00042" (or similar):
+<%= texd_attach "common.tex", without_extension: true %>
+```
+
+</details>
+<details><summary><code>app/tex/logo.png</code></summary>
+
+*(Imagine your logo here.)*
+
+</details>
+
+With those files in place, you can create a PDF document:
+
+```rb
+begin
+  blob = Texd.render(template: "documents/doc", locals: {
+    user: User.find(1)
+  })
+  Rails.root.join("tmp/doc.pdf").open("wb") { |f|
+    f.write blob
+  }
+rescue Texd::Client::QueueError => err
+  # texd server is busy, please retry in a moment
+rescue Texd::Client::InputError => err
+  # file input processing failed, maybe some file names were invalid
+rescue Texd::Client::CompilationError => err
+  # compilation failed
+  if err.logs
+    # TeX compiler logs, only available if Texd.config.error_format
+    # is "full" or "condensed"
+  end
+end
+```
+
+All errors inherit from `Texd::Client::RenderError` and should have
+a `details` attribute (a Hash) containing the actual error returned
+from the server.
 
 ## Development
 

data/gemfiles/rails-6.0.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    texd (0.2.0)
+    texd (0.3.0)
       multipart-post (~> 2.0)
       rails (>= 6.0, < 8)
 

data/gemfiles/rails-6.1.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    texd (0.2.0)
+    texd (0.3.0)
       multipart-post (~> 2.0)
       rails (>= 6.0, < 8)
 

data/gemfiles/rails-7.0.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    texd (0.2.0)
+    texd (0.3.0)
       multipart-post (~> 2.0)
       rails (>= 6.0, < 8)
 

data/lib/texd/attachment.rb

@@ -202,9 +202,19 @@ module Texd
         }
       end
 
+      def self.cache
+        @cache ||= Cache.new(Texd.config.ref_cache_size)
+      end
+
       # @api private
       def checksum
-        @checksum ||= begin
+        @checksum ||= create_checksum
+      end
+
+      # @api private
+      def create_checksum
+        key = [::File.stat(absolute_path).mtime, absolute_path]
+        self.class.cache.fetch(key) do
           digest  = Digest::SHA256.file(absolute_path).digest
           encoded = Base64.urlsafe_encode64(digest)
           "sha256:#{encoded}"

data/lib/texd/cache.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Texd
+  # Cache is a simple LRU cache with a double linked list.
+  # If the cache is full the last element from the list will be removed.
+  class Cache
+    class LinkedList
+      attr_reader :head
+
+      def add(node)
+        if @head
+          node.next       = @head
+          node.prev       = @head.prev
+          @head.prev.next = node
+          @head.prev      = node
+        else
+          node.next = node
+          node.prev = node
+        end
+
+        @head = node
+      end
+
+      def remove(node)
+        if node.next == node
+          # remove last element, should never happen
+          @head = nil
+        else
+          node.prev.next = node.next
+          node.next.prev = node.prev
+          @head          = node.next if node == @head
+        end
+      end
+    end
+
+    class Node
+      attr_reader :key
+      attr_accessor :value, :prev, :next
+
+      def initialize(key)
+        @key = key
+      end
+    end
+
+    attr_reader :list, :count, :capacity
+    delegate :keys, to: :@hash
+
+    def initialize(capacity)
+      @list     = LinkedList.new
+      @hash     = {}
+      @mtx      = Mutex.new
+      @count    = 0
+      @capacity = capacity
+    end
+
+    def fetch(key)
+      read(key) || write(key, yield)
+    end
+
+    def read(key)
+      @mtx.synchronize do
+        node = @hash[key]
+        return unless node
+
+        list.remove(node)
+        list.add(node)
+        node.value
+      end
+    end
+
+    def write(key, value)
+      @mtx.synchronize do
+        node = @hash[key]
+
+        if node
+          list.remove(node)
+        else
+          node = add_node(key)
+        end
+
+        list.add(node)
+        node.value = value
+      end
+    end
+
+    private
+
+    def add_node(key)
+      node = Node.new(key)
+
+      if count >= capacity
+        last = list.head.prev
+        @hash.delete(last.key)
+        list.remove(last)
+      else
+        @count += 1
+      end
+
+      @hash[key] = node
+      node
+    end
+  end
+end

data/lib/texd/client.rb

@@ -60,24 +60,6 @@ module Texd
       "reference"   => ReferenceError,
     }.freeze
 
-    class ResponseError < Error
-      attr_reader :body, :content_type
-
-      def initialize(code, content_type, body)
-        @body         = body
-        @content_type = content_type
-
-        if json?
-          super format("%s error: %s", body.delete("category"), body.delete("error"))
-        elsif log?
-          tex_errors = body.lines.select { |l| l.start_with?("!") }.map(&:strip)
-          super "Compilation failed:\n\t#{tex_errors.join('\n\t')}"
-        else
-          super "Server responded with status #{code} (#{content_type})"
-        end
-      end
-    end
-
     USER_AGENT = "texd-ruby/#{VERSION} Ruby/#{RUBY_VERSION}"
 
     attr_reader :config

data/lib/texd/config.rb

@@ -22,15 +22,16 @@ module Texd
 
     # This is the default configuration. It is applied in the constructor.
     DEFAULT_CONFIGURATION = {
-      endpoint:      ENV.fetch("TEXD_ENDPOINT", "http://localhost:2201/"),
-      open_timeout:  ENV.fetch("TEXD_OPEN_TIMEOUT", 60),
-      read_timeout:  ENV.fetch("TEXD_READ_TIMEOUT", 180),
-      write_timeout: ENV.fetch("TEXD_WRITE_TIMEOUT", 60),
-      error_format:  ENV.fetch("TEXD_ERRORS", "full"),
-      tex_engine:    ENV["TEXD_ENGINE"],
-      tex_image:     ENV["TEXD_IMAGE"],
-      helpers:       Set.new,
-      lookup_paths:  [], # Rails.root.join("app/tex") is inserted in railtie.rb
+      endpoint:       ENV.fetch("TEXD_ENDPOINT", "http://localhost:2201/"),
+      open_timeout:   ENV.fetch("TEXD_OPEN_TIMEOUT", 60),
+      read_timeout:   ENV.fetch("TEXD_READ_TIMEOUT", 180),
+      write_timeout:  ENV.fetch("TEXD_WRITE_TIMEOUT", 60),
+      error_format:   ENV.fetch("TEXD_ERRORS", "full"),
+      tex_engine:     ENV["TEXD_ENGINE"],
+      tex_image:      ENV["TEXD_IMAGE"],
+      helpers:        Set.new,
+      lookup_paths:   [], # Rails.root.join("app/tex") is inserted in railtie.rb
+      ref_cache_size: 128,
     }.freeze
 
     # Supported endpoint protocols.
@@ -107,6 +108,13 @@ module Texd
     # A Texd::LookupContext is constructed from this set.
     attr_accessor :lookup_paths
 
+    # Cache size for file hashes computed by Texd::Attachment::Reference.
+    # Cannot be changed after the first document (using the `texd_reference`
+    # helper) was renderered.
+    #
+    # By default, the cache keeps hashes of the last 128 reference files.
+    attr_accessor :ref_cache_size
+
     def initialize(**options)
       DEFAULT_CONFIGURATION.each do |key, default_value|
         public_send "#{key}=", options.fetch(key, default_value.dup)

data/lib/texd/document.rb

@@ -6,8 +6,8 @@ module Texd
     attr_reader :attachments
 
     # Shorthand for `new.compile`.
-    def self.compile(*args)
-      new.compile(*args)
+    def self.compile(template:, locals: {})
+      new.compile(template: template, locals: locals)
     end
 
     def initialize
@@ -18,16 +18,16 @@ module Texd
     # Compile converts templates into TeX sources and collects file
     # references (created with `texd_attach` and `texd_reference` helpers).
     #
-    # @param args are forwarded to ApplicationController#render (which in turn
-    #   forwards to ActionView::Renderer#render).
+    # @param [String] template name of template file in ActionView's lookup
+    #   context.
+    # @param [Hash, nil] locals will be made available as getter methods in
+    #   the template.
     # @return [Compilation]
-    def compile(*args)
-      locals     = args.last.delete(:locals) if args.last.is_a?(Hash)
+    def compile(template:, locals: {})
       helper_mod = ::Texd.helpers(attachments, locals)
-
       tex_source = Class.new(ApplicationController) {
         helper helper_mod
-      }.render(*args)
+      }.render(template: template, format: :tex)
 
       main = attachments.main_input(tex_source)
       Compilation.new(main.name, attachments)

data/lib/texd/helpers.rb

@@ -28,8 +28,9 @@ module Texd
 
     # Escapes the given text, making it safe for use in TeX documents.
     def escape(text, line_break = "\\\\\\", typographic: true)
-      text = +text.to_s # text might be nil or a frozen string
-      text.tap do |str|
+      return "" if text.blank?
+
+      text.to_s.dup.tap do |str|
         str.gsub!(ESCAPE_RE) do |m|
           if Regexp.last_match(1)
             "\\#{m}"

data/lib/texd/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Texd
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/texd.rb

@@ -12,6 +12,7 @@ require "rails"
 require_relative "texd/version"
 require_relative "texd/config"
 require_relative "texd/helpers"
+require_relative "texd/cache"
 require_relative "texd/client"
 require_relative "texd/attachment"
 require_relative "texd/document"
@@ -94,8 +95,8 @@ module Texd
   # Render compiles a template, uploads the files to the texd instance,
   # and returns the PDF.
   #
-  # The arguments are directly forwarded to ApplicationController#render
-  # (which in turn delegates to ActionView::Renderer#render).
+  # The arguments are directly forwarded to Texd::Document (and end up in
+  # ActionView::Renderer#render).
   #
   # @example Render app/views/document/document.tex.erb
   #   begin
@@ -114,12 +115,16 @@ module Texd
   #     # something went wrong before we even got to sent data to the server
   #   end
   #
+  # @param [String] template name of template file in ActionView's lookup
+  #   context.
+  # @param [Hash, nil] locals will be made available as getter methods in
+  #   the template.
   # @raise [Texd::Client::ResponseError] on input and queue errors. Also on
   #   compilation errors, if Texd.config.error_format is set to JSON.
   # @raise [Texd::Error] on other Texd related errors.
   # @return [String] the PDF object
-  def render(*args)
-    doc = Document.compile(*args)
+  def render(template:, locals: {})
+    doc = Document.compile(template: template, locals: locals)
 
     client.render doc.to_upload_ios,
       input: doc.main_input_name

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: texd
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Dominik Menke
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-03-22 00:00:00.000000000 Z
+date: 2022-03-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: multipart-post
@@ -125,6 +125,7 @@ files:
 - gemfiles/rails-7.0.lock
 - lib/texd.rb
 - lib/texd/attachment.rb
+- lib/texd/cache.rb
 - lib/texd/client.rb
 - lib/texd/config.rb
 - lib/texd/document.rb
@@ -140,7 +141,7 @@ metadata:
   rubygems_mfa_required: 'true'
   homepage_uri: https://github.com/digineo/texd-ruby
   source_code_uri: https://github.com/digineo/texd-ruby
-  changelog_uri: https://github.com/digineo/texd-ruby/blob/v0.2.0/CHANGELOG.md
+  changelog_uri: https://github.com/digineo/texd-ruby/blob/v0.3.0/CHANGELOG.md
 post_install_message: 
 rdoc_options: []
 require_paths: