typst-rails 0.1.0 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,248 @@
1
+ # frozen_string_literal: true
2
+
3
+ module TypstRails
4
+ # Converts one Markdown document to Typst markup. Backs
5
+ # {Helpers#markdown_to_typst}; each conversion uses a new instance, so the
6
+ # state it keeps between passes never outlives the call.
7
+ #
8
+ # Markup the conversion writes (headings, list markers, links, images,
9
+ # code) is stashed behind placeholders as it is made. The text left over is
10
+ # escaped with {Helpers#escape_typst}, so it reads as written, and the
11
+ # stashed markup is then put back.
12
+ #
13
+ # @api private
14
+ class MarkdownConverter
15
+ include Helpers
16
+
17
+ # MARK: - Placeholders
18
+ #
19
+ # The conversion rewrites emphasis in several regex passes. Each pass
20
+ # must not re-match markers written by an earlier one, so markers are
21
+ # staged as these private sentinel bytes and swapped for real Typst syntax
22
+ # at the very end.
23
+ #
24
+ # They are drawn from the Unicode private use area rather than plain
25
+ # control bytes so they cannot collide with anything a text pipeline is
26
+ # likely to emit. Any that do appear in the source are held aside by
27
+ # {#protect_placeholder_bytes} and put back verbatim afterwards.
28
+ BOLD_OPEN = "\u{E000}"
29
+ BOLD_CLOSE = "\u{E001}"
30
+ ITALIC_OPEN = "\u{E002}"
31
+ ITALIC_CLOSE = "\u{E003}"
32
+
33
+ # Sentinel standing in for a placeholder byte that was already present in
34
+ # the caller's input.
35
+ LITERAL_PLACEHOLDER = "\u{E004}"
36
+
37
+ # Delimit the index of a stashed token: Typst markup the conversion has
38
+ # already written, such as a heading marker, a link or a code span,
39
+ # held aside so the escaping pass leaves it intact.
40
+ STASH_OPEN = "\u{E005}"
41
+ STASH_CLOSE = "\u{E006}"
42
+
43
+ # Follows a stashed embedded expression (#link, #image). Typst would read
44
+ # a "(" or a "." and a name straight after one as part of the expression,
45
+ # so there it becomes a ";" to end the expression, and elsewhere it is
46
+ # dropped.
47
+ EXPRESSION_END = "\u{E007}"
48
+
49
+ # All sentinels this class reserves, in a single character class.
50
+ PLACEHOLDER_PATTERN = /[\u{E000}-\u{E007}]/.freeze
51
+
52
+ STASH_PATTERN = /\u{E005}(\d+)\u{E006}/.freeze
53
+
54
+ # Fenced code blocks (``` or ~~~) and single-line inline code spans.
55
+ # Fences come first so their backticks are not read as inline spans.
56
+ CODE_PATTERN = /^(`{3,}|~{3,})[^\n]*\n.*?^\1[ \t]*$|(`+)[^`\n][^\n]*?\2(?!`)/m.freeze
57
+
58
+ # A Markdown backslash escape: a backslash before ASCII punctuation, or at
59
+ # the end of a line, where it is a hard line break.
60
+ BACKSLASH_ESCAPE_PATTERN = %r{\\([!-/:-@\[-`\{-~])|\\(?=\r?\n)}.freeze
61
+
62
+ HEADING_PATTERN = /^(\#{1,6})[ \t]+(.+)$/.freeze
63
+
64
+ # Bullets (-, +, *) and ordered items (1. or 1)) followed by whitespace.
65
+ LIST_MARKER_PATTERN = /^([ \t]*)([-+*]|\d+[.)])(?=[ \t])/.freeze
66
+
67
+ # A link destination with an optional quoted title, which Typst has no
68
+ # place for and is dropped.
69
+ LINK_TARGET = /\(\s*(\S+?)(?:\s+"[^"]*")?\s*\)/.freeze
70
+ IMAGE_PATTERN = /!\[[^\]]*\]#{LINK_TARGET}/.freeze
71
+ LINK_PATTERN = /\[([^\]]+)\]#{LINK_TARGET}/.freeze
72
+ AUTOLINK_PATTERN = /<((?:https?|mailto):[^\s<>]+)>/.freeze
73
+
74
+ # One piece of stashed markup, and the source text it came from, which is
75
+ # what a link destination needs when the piece turns up inside one.
76
+ StashedToken = Struct.new(:markup, :literal)
77
+
78
+ private_constant :BOLD_OPEN, :BOLD_CLOSE, :ITALIC_OPEN, :ITALIC_CLOSE, :LITERAL_PLACEHOLDER,
79
+ :STASH_OPEN, :STASH_CLOSE, :EXPRESSION_END, :PLACEHOLDER_PATTERN, :STASH_PATTERN,
80
+ :CODE_PATTERN, :BACKSLASH_ESCAPE_PATTERN, :HEADING_PATTERN, :LIST_MARKER_PATTERN,
81
+ :LINK_TARGET, :IMAGE_PATTERN, :LINK_PATTERN, :AUTOLINK_PATTERN, :StashedToken
82
+
83
+ # @param markdown [String] the Markdown source
84
+ def initialize(markdown)
85
+ super()
86
+ @markdown = markdown
87
+ @tokens = []
88
+ end
89
+
90
+ # @return [String] Typst-compatible markup
91
+ def convert
92
+ # The passes below use placeholder bytes to mark text they have already
93
+ # handled. Any such bytes already in the source would be
94
+ # indistinguishable from our own, so they are held aside and restored at
95
+ # the end.
96
+ result = protect_placeholder_bytes(@markdown.dup)
97
+
98
+ result = stash_literal_markdown(result)
99
+ result = stash_line_markers(result)
100
+ result = stash_links(result)
101
+ result = convert_inline_markdown(result)
102
+
103
+ restore_placeholder_bytes(restore_stash(result))
104
+ end
105
+
106
+ private
107
+
108
+ # MARK: - Markdown conversion passes
109
+
110
+ # Holds aside the parts of the source whose contents are literal: code,
111
+ # which is the same in Typst as in Markdown, and backslash escapes, which
112
+ # stand for their character.
113
+ def stash_literal_markdown(text)
114
+ text = text.gsub(CODE_PATTERN) { |code| stash(code, code) }
115
+
116
+ text.gsub(BACKSLASH_ESCAPE_PATTERN) do
117
+ char = Regexp.last_match(1)
118
+ next stash("\\", "") unless char
119
+
120
+ stash("\\#{char}", char)
121
+ end
122
+ end
123
+
124
+ # Converts the markers that only mean something at the start of a line:
125
+ # headings, and list items. Markdown bullets all become Typst's "-", since
126
+ # "+" would make a numbered item.
127
+ def stash_line_markers(text)
128
+ text = text.gsub(HEADING_PATTERN) do
129
+ heading = "#{"=" * Regexp.last_match(1).length} "
130
+ "#{stash(heading, heading)}#{Regexp.last_match(2)}"
131
+ end
132
+
133
+ text.gsub(LIST_MARKER_PATTERN) do
134
+ indent = Regexp.last_match(1)
135
+ marker = Regexp.last_match(2)
136
+ bullet = marker.match?(/\A\d/) ? "#{marker.to_i}." : "-"
137
+ "#{indent}#{stash(bullet, marker)}"
138
+ end
139
+ end
140
+
141
+ # Converts images and links, writing their destinations as Typst string
142
+ # literals. Images go first, since ![alt](url) also matches the link
143
+ # pattern, and so an image can sit inside a link's text.
144
+ def stash_links(text)
145
+ text = text.gsub(AUTOLINK_PATTERN) do
146
+ stash_expression("#link(#{typst_string(Regexp.last_match(1))})")
147
+ end
148
+
149
+ text = text.gsub(IMAGE_PATTERN) do
150
+ stash_expression("#image(#{typst_string(Regexp.last_match(1))})")
151
+ end
152
+
153
+ text.gsub(LINK_PATTERN) do
154
+ body = convert_inline_markdown(Regexp.last_match(1))
155
+ stash_expression("#link(#{typst_string(Regexp.last_match(2))})[#{body}]")
156
+ end
157
+ end
158
+
159
+ # Converts emphasis and escapes everything else, so whatever is left of
160
+ # the Markdown reads as literal text in Typst.
161
+ def convert_inline_markdown(text)
162
+ # Convert combined bold+italic first: ***text*** and ___text___ are a
163
+ # single Markdown token, and letting the bold pass see them would consume
164
+ # only two of the three markers and strand the leftover one mid-word.
165
+ # ***text*** -> *_text_*
166
+ #
167
+ # As in Markdown, an opening marker must be followed, and a closing one
168
+ # preceded, by non-whitespace, so "2 * 3 * 4" is not emphasis.
169
+ text = text.gsub(/(\*\*\*|___)(?=\S)(.+?)(?<=\S)\1/, "#{BOLD_OPEN}#{ITALIC_OPEN}\\2#{ITALIC_CLOSE}#{BOLD_CLOSE}")
170
+
171
+ # **text** or __text__ -> *text*
172
+ text = text.gsub(/(\*\*|__)(?=\S)(.+?)(?<=\S)\1/, "#{BOLD_OPEN}\\2#{BOLD_CLOSE}")
173
+
174
+ # *text* or _text_ -> _text_
175
+ text = text.gsub(/(?<!\*)\*(?![\s*])(.+?)(?<![\s*])\*(?!\*)/, "#{ITALIC_OPEN}\\1#{ITALIC_CLOSE}")
176
+ text = text.gsub(/(?<!_)_(?![\s_])(.+?)(?<![\s_])_(?!_)/, "#{ITALIC_OPEN}\\1#{ITALIC_CLOSE}")
177
+
178
+ # A literal slash before a bold marker would open a /* comment.
179
+ text = escape_typst(text).gsub(%r{/(?=#{BOLD_OPEN}|#{BOLD_CLOSE})}, "\\\\/")
180
+
181
+ text.tr("#{BOLD_OPEN}#{BOLD_CLOSE}#{ITALIC_OPEN}#{ITALIC_CLOSE}", "**__")
182
+ end
183
+
184
+ # @return [String] a placeholder for +markup+, which {#restore_stash}
185
+ # swaps back in
186
+ def stash(markup, literal)
187
+ @tokens << StashedToken.new(markup, literal)
188
+ "#{STASH_OPEN}#{@tokens.length - 1}#{STASH_CLOSE}"
189
+ end
190
+
191
+ def stash_expression(markup)
192
+ stash("#{markup}#{EXPRESSION_END}", markup)
193
+ end
194
+
195
+ # Puts stashed markup back, then ends each embedded expression where the
196
+ # text after it would otherwise continue it.
197
+ def restore_stash(text)
198
+ expand_stash(text).gsub(/#{EXPRESSION_END}(?=\(|\.[\p{L}_])/, ";").delete(EXPRESSION_END)
199
+ end
200
+
201
+ # Swaps placeholders for their markup, including any stashed inside other
202
+ # markup, such as code in a link's text.
203
+ def expand_stash(text)
204
+ text.gsub(STASH_PATTERN) { expand_stash(@tokens[Regexp.last_match(1).to_i].markup) }
205
+ end
206
+
207
+ # Writes +text+ as a Typst string literal. Stashed pieces inside it, such
208
+ # as a backslash escape in a URL, stand for their source text there.
209
+ def typst_string(text)
210
+ literal = text.gsub(STASH_PATTERN) { @tokens[Regexp.last_match(1).to_i].literal }
211
+
212
+ "\"#{literal.gsub(/[\\"]/) { |char| "\\#{char}" }}\""
213
+ end
214
+
215
+ # MARK: - Placeholder handling
216
+
217
+ # Stashes any of this class's sentinel characters that the caller's input
218
+ # already contained, so the emphasis passes cannot mistake them for markers
219
+ # they wrote themselves.
220
+ #
221
+ # Each occurrence is replaced by LITERAL_PLACEHOLDER and its original
222
+ # character recorded, in order, on +@placeholder_literals+.
223
+ #
224
+ # @param text [String] the source text
225
+ # @return [String] the text with pre-existing sentinels stashed
226
+ def protect_placeholder_bytes(text)
227
+ @placeholder_literals = []
228
+ return text unless text.match?(PLACEHOLDER_PATTERN)
229
+
230
+ text.gsub(PLACEHOLDER_PATTERN) do |char|
231
+ @placeholder_literals << char
232
+ LITERAL_PLACEHOLDER
233
+ end
234
+ end
235
+
236
+ # Puts back the characters stashed by {#protect_placeholder_bytes}, in the
237
+ # order they were found.
238
+ #
239
+ # @param text [String] the converted text
240
+ # @return [String] the text with the caller's original characters restored
241
+ def restore_placeholder_bytes(text)
242
+ return text if @placeholder_literals.empty?
243
+
244
+ index = -1
245
+ text.gsub(LITERAL_PLACEHOLDER) { @placeholder_literals[index += 1] }
246
+ end
247
+ end
248
+ end
@@ -1,18 +1,65 @@
1
1
  # frozen_string_literal: true
2
2
 
3
+ require "typst_rails/template_rendering"
4
+
3
5
  module TypstRails
4
- # Integration for Rage framework
6
+ # Integration for the Rage framework.
7
+ #
8
+ # Rage controllers render JSON or plain text and have no template handlers,
9
+ # so the integration adds a controller helper rather than a `.typ` handler.
5
10
  module RageIntegration
6
- def self.setup
7
- return unless defined?(::Rage)
11
+ # Mirrors the `assigns` reader Renderer expects from a view context, so
12
+ # locals get the same JSON conversion (models, dates) as in Rails. Kept
13
+ # for compatibility; the helper now goes through {TemplateRendering}.
14
+ ViewContext = ::TypstRails::TemplateRendering::ViewContext
8
15
 
9
- require "typst_rails/renderer"
16
+ # Mixed into RageController::API by {RageIntegration.setup}. Include it
17
+ # yourself if typst-rails loads before Rage's controllers are defined.
18
+ #
19
+ # @example
20
+ # class ReportsController < RageController::API
21
+ # def show
22
+ # @title = "Monthly Report"
23
+ # render_typst "app/views/reports/monthly.typ", { total: 42 }
24
+ # end
25
+ # end
26
+ module ControllerHelpers
27
+ include ::TypstRails::Helpers
10
28
 
11
- # Register Typst handler for Rage
12
- ::Rage.configure do |config|
13
- # Rage uses a similar template system to Rails
14
- # We can register our handler here when Rage's template system is available
29
+ # Renders a Typst template and responds with the PDF.
30
+ #
31
+ # The template runs through ERB first, in the controller's scope, with
32
+ # +locals+ as local variables; +locals+ are also written to
33
+ # typst_data.json for templates that read it.
34
+ #
35
+ # @param template [String] path to the .typ file
36
+ # @param locals [Hash] data for the template
37
+ # @param status [Integer, Symbol, nil] response status
38
+ # @return [void]
39
+ # @raise [TypstRails::CompileError] if Typst rejects the template
40
+ # @raise [TypstRails::Error] if compilation fails for another reason
41
+ def render_typst(template, locals = {}, status: nil, **extra)
42
+ # Ruby 2.7 binds a trailing symbol-keyed locals hash as keywords;
43
+ # fold those back into locals.
44
+ locals = locals.merge(extra) unless extra.empty?
45
+ pdf_data = ::TypstRails::TemplateRendering.render_file(template, self, locals, locals)
46
+
47
+ # Rage's render(plain:) sets text/plain, so override it afterwards.
48
+ render plain: pdf_data, status: status
49
+ headers["content-type"] = "application/pdf"
15
50
  end
16
51
  end
52
+
53
+ # Adds {ControllerHelpers} to RageController::API, if it is loaded.
54
+ #
55
+ # @return [void]
56
+ def self.setup
57
+ return unless defined?(::Rage)
58
+ return unless defined?(::RageController::API)
59
+ return if ::RageController::API.include?(ControllerHelpers)
60
+
61
+ ::RageController::API.include(ControllerHelpers)
62
+ nil
63
+ end
17
64
  end
18
65
  end
@@ -0,0 +1,58 @@
1
+ # frozen_string_literal: true
2
+
3
+ module TypstRails
4
+ # Renders `.typ` views through a Rails controller, so app helpers, route
5
+ # helpers, and partials work as in a request. Backs
6
+ # {TypstRails.render_with_rails}.
7
+ #
8
+ # Nothing here loads Rails. ActionController is looked up when a render
9
+ # happens, so typst-rails can be required before actionpack.
10
+ #
11
+ # @api private
12
+ module RailsRendering
13
+ # Raised as a {TypstRails::Error} message when ActionController is absent.
14
+ MISSING_ACTION_CONTROLLER = "render_with_rails requires ActionController; use TypstRails.render"
15
+
16
+ module_function
17
+
18
+ # @param template [String, Symbol, Pathname] Rails template name
19
+ # @param locals [Hash] view locals
20
+ # @param assigns [Hash] view instance variables
21
+ # @param controller [Class, nil] controller class to render with
22
+ # @return [String] binary PDF data
23
+ # @raise [TypstRails::Error] if ActionController is not loaded
24
+ def render(template, locals: {}, assigns: {}, controller: nil)
25
+ raise ArgumentError, "locals must be a Hash" unless locals.is_a?(Hash)
26
+ raise ArgumentError, "assigns must be a Hash" unless assigns.is_a?(Hash)
27
+ raise Error, MISSING_ACTION_CONTROLLER unless defined?(::ActionController::Base)
28
+
29
+ controller ||= default_controller
30
+ body = controller.render(template: template.to_s, formats: [:pdf], locals: locals, assigns: assigns)
31
+ binary(body)
32
+ end
33
+
34
+ # ApplicationController when the app defines one that renders views,
35
+ # otherwise ActionController::Base. An ApplicationController based on
36
+ # ActionController::API cannot render templates, so it is skipped.
37
+ #
38
+ # @return [Class]
39
+ def default_controller
40
+ if Object.const_defined?(:ApplicationController)
41
+ app_controller = ::ApplicationController
42
+ return app_controller if app_controller.is_a?(Class) && app_controller <= ::ActionController::Base
43
+ end
44
+
45
+ ::ActionController::Base
46
+ end
47
+
48
+ # Returns the rendered body as a plain binary String. Rails may hand
49
+ # back an ActionView::OutputBuffer or an ActiveSupport::SafeBuffer;
50
+ # callers want bytes they can write to a file or attach.
51
+ #
52
+ # @param body [#to_s]
53
+ # @return [String]
54
+ def binary(body)
55
+ String.new(body.to_s, encoding: Encoding::BINARY)
56
+ end
57
+ end
58
+ end
@@ -11,6 +11,13 @@ module TypstRails
11
11
  end
12
12
  end
13
13
 
14
+ initializer "typst_rails.view_helpers" do
15
+ ActiveSupport.on_load(:action_view) do
16
+ require "typst_rails/view_helpers"
17
+ include TypstRails::ViewHelpers
18
+ end
19
+ end
20
+
14
21
  rake_tasks do
15
22
  load File.expand_path("../tasks/typst_rails/tasks.rake", __dir__)
16
23
  end