csv_preview 0.1.0
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.
- checksums.yaml +7 -0
- data/.yardopts +8 -0
- data/CHANGELOG.md +25 -0
- data/LICENSE +21 -0
- data/README.md +587 -0
- data/SECURITY.md +51 -0
- data/fonts/Inter-Regular.ttf +0 -0
- data/fonts/Inter-SemiBold.ttf +0 -0
- data/fonts/OFL.txt +92 -0
- data/lib/csv_preview/active_storage_previewer.rb +97 -0
- data/lib/csv_preview/cell_kind.rb +75 -0
- data/lib/csv_preview/configuration.rb +183 -0
- data/lib/csv_preview/deadline.rb +31 -0
- data/lib/csv_preview/errors.rb +30 -0
- data/lib/csv_preview/layout.rb +590 -0
- data/lib/csv_preview/painter.rb +194 -0
- data/lib/csv_preview/parser.rb +456 -0
- data/lib/csv_preview/railtie.rb +54 -0
- data/lib/csv_preview/reader.rb +259 -0
- data/lib/csv_preview/sample.rb +85 -0
- data/lib/csv_preview/sanitizer.rb +31 -0
- data/lib/csv_preview/text.rb +621 -0
- data/lib/csv_preview/theme.rb +207 -0
- data/lib/csv_preview/version.rb +6 -0
- data/lib/csv_preview.rb +149 -0
- data/skills/csv-preview/SKILL.md +171 -0
- metadata +121 -0
|
@@ -0,0 +1,207 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
module CsvPreview
|
|
4
|
+
# Every colour, size and structural switch the layout and painter use, as one immutable value
|
|
5
|
+
# (rendering.md section 2). Sizes are logical px; {#px} converts a token to device px. No other
|
|
6
|
+
# file holds a visual literal.
|
|
7
|
+
#
|
|
8
|
+
# Values are validated at construction. Colours, weights and the font family end up in Pango markup
|
|
9
|
+
# attributes and font descriptions, so validation is also what keeps them safe there.
|
|
10
|
+
# @api private
|
|
11
|
+
Theme = Data.define(
|
|
12
|
+
:name,
|
|
13
|
+
:font_family,
|
|
14
|
+
:body_size, :body_weight,
|
|
15
|
+
:header_size, :header_weight,
|
|
16
|
+
:footer_size, :footer_weight,
|
|
17
|
+
:number_features,
|
|
18
|
+
:true_minus,
|
|
19
|
+
:text_color,
|
|
20
|
+
:muted_color,
|
|
21
|
+
:header_text_color,
|
|
22
|
+
:header_fill,
|
|
23
|
+
:header_rule_color, :header_rule_width,
|
|
24
|
+
:row_rule_color, :row_rule_width,
|
|
25
|
+
:footer_rule_color, :footer_rule_width,
|
|
26
|
+
:frame_color, :frame_width,
|
|
27
|
+
:background,
|
|
28
|
+
:header_height, :row_height, :footer_height,
|
|
29
|
+
:cell_padding, :edge_padding,
|
|
30
|
+
:min_column_width, :max_column_width,
|
|
31
|
+
:min_width, :max_width,
|
|
32
|
+
:fade_width, :fade_exponent,
|
|
33
|
+
:peek_width,
|
|
34
|
+
:empty_body_rows
|
|
35
|
+
) do
|
|
36
|
+
def initialize(**tokens)
|
|
37
|
+
Theme::Validation.validate!(tokens)
|
|
38
|
+
super
|
|
39
|
+
end
|
|
40
|
+
|
|
41
|
+
# @param token [Symbol] a colour token, for example `:header_fill`
|
|
42
|
+
# @return [Array(Integer, Integer, Integer)] its red, green and blue values
|
|
43
|
+
def rgb(token)
|
|
44
|
+
raise ArgumentError, "#{token.inspect} is not a colour token" unless Theme::COLORS.include?(token)
|
|
45
|
+
|
|
46
|
+
token_value(token).delete_prefix("#").scan(/../).map { |pair| pair.to_i(16) }
|
|
47
|
+
end
|
|
48
|
+
|
|
49
|
+
# Converts one token to device px. Applied once per token, never to sums, so rounding never
|
|
50
|
+
# accumulates (rendering.md section 1).
|
|
51
|
+
#
|
|
52
|
+
# @param token [Symbol]
|
|
53
|
+
# @param scale [Numeric]
|
|
54
|
+
# @return [Integer]
|
|
55
|
+
def px(token, scale)
|
|
56
|
+
(token_value(token) * scale).round
|
|
57
|
+
end
|
|
58
|
+
|
|
59
|
+
# A rule or border width in device px: 0 when the token is 0 (not drawn), else at least 1.
|
|
60
|
+
#
|
|
61
|
+
# @param token [Symbol] a rule or frame width token
|
|
62
|
+
# @param scale [Numeric]
|
|
63
|
+
# @return [Integer]
|
|
64
|
+
def rule_px(token, scale)
|
|
65
|
+
token_value(token).zero? ? 0 : [1, px(token, scale)].max
|
|
66
|
+
end
|
|
67
|
+
|
|
68
|
+
# The text styles in device px. `font` (the `font:` option) replaces the family only; the bundled
|
|
69
|
+
# files are passed only when the family is the theme's own.
|
|
70
|
+
#
|
|
71
|
+
# @param scale [Integer]
|
|
72
|
+
# @param font [String, nil]
|
|
73
|
+
# @return [Styles]
|
|
74
|
+
def styles(scale:, font: nil)
|
|
75
|
+
tnum = !number_features.nil?
|
|
76
|
+
style = lambda do |size, weight, color, features|
|
|
77
|
+
Text::Style.new(family: font || font_family, fontfile: font ? nil : Theme::FONT_FILES.fetch(weight),
|
|
78
|
+
size_px: px(size, scale), weight: weight, color: color, tnum: features)
|
|
79
|
+
end
|
|
80
|
+
body = style.call(:body_size, body_weight, text_color, false)
|
|
81
|
+
header = style.call(:header_size, header_weight, header_text_color, false)
|
|
82
|
+
Theme::Styles.new(
|
|
83
|
+
body: body,
|
|
84
|
+
body_number: body.with(tnum: tnum),
|
|
85
|
+
header: header,
|
|
86
|
+
header_number: header.with(tnum: tnum),
|
|
87
|
+
footer: style.call(:footer_size, footer_weight, muted_color, tnum),
|
|
88
|
+
message: body.with(color: muted_color)
|
|
89
|
+
)
|
|
90
|
+
end
|
|
91
|
+
|
|
92
|
+
private
|
|
93
|
+
|
|
94
|
+
# One token's value. Tokens are internal constants, never input, so no dynamic send is needed.
|
|
95
|
+
def token_value(token)
|
|
96
|
+
deconstruct_keys([token]).fetch(token)
|
|
97
|
+
end
|
|
98
|
+
end
|
|
99
|
+
|
|
100
|
+
class Theme
|
|
101
|
+
# The text styles of one theme at one scale. Number columns use the `_number` styles (tabular
|
|
102
|
+
# figures); the footer always does. Messages ("Empty file", "No rows") use the body size and
|
|
103
|
+
# weight in the muted colour.
|
|
104
|
+
Styles = Data.define(:body, :body_number, :header, :header_number, :footer, :message)
|
|
105
|
+
|
|
106
|
+
# The bundled Inter files by weight. Theme weights must be one of these.
|
|
107
|
+
FONT_FILES = { 400 => Text::REGULAR, 600 => Text::SEMIBOLD }.freeze
|
|
108
|
+
|
|
109
|
+
COLORS = %i[
|
|
110
|
+
text_color muted_color header_text_color header_fill header_rule_color row_rule_color footer_rule_color
|
|
111
|
+
frame_color background
|
|
112
|
+
].freeze
|
|
113
|
+
RULE_WIDTHS = %i[header_rule_width row_rule_width footer_rule_width frame_width].freeze
|
|
114
|
+
WEIGHTS = %i[body_weight header_weight footer_weight].freeze
|
|
115
|
+
SIZES = %i[
|
|
116
|
+
body_size header_size footer_size header_height row_height footer_height cell_padding edge_padding
|
|
117
|
+
min_column_width max_column_width min_width max_width fade_width peek_width empty_body_rows
|
|
118
|
+
].freeze
|
|
119
|
+
COLOR_PATTERN = /\A#\h{6}\z/
|
|
120
|
+
NUMBER_FEATURES = [nil, "tnum"].freeze
|
|
121
|
+
|
|
122
|
+
# @api private
|
|
123
|
+
module Validation
|
|
124
|
+
module_function
|
|
125
|
+
|
|
126
|
+
def validate!(t)
|
|
127
|
+
raise ArgumentError, "name must be a Symbol" unless t[:name].is_a?(Symbol)
|
|
128
|
+
|
|
129
|
+
family = t[:font_family]
|
|
130
|
+
unless family.is_a?(String) && !family.strip.empty? && !family.match?(/[[:cntrl:]]/)
|
|
131
|
+
raise ArgumentError, "font_family must be a non-empty String without control characters"
|
|
132
|
+
end
|
|
133
|
+
|
|
134
|
+
COLORS.each do |token|
|
|
135
|
+
raise ArgumentError, "#{token} must be #RRGGBB" unless t[token].is_a?(String) && t[token].match?(COLOR_PATTERN)
|
|
136
|
+
end
|
|
137
|
+
SIZES.each do |token|
|
|
138
|
+
raise ArgumentError, "#{token} must be a positive Integer" unless t[token].is_a?(Integer) && t[token].positive?
|
|
139
|
+
end
|
|
140
|
+
RULE_WIDTHS.each do |token|
|
|
141
|
+
unless t[token].is_a?(Integer) && !t[token].negative?
|
|
142
|
+
raise ArgumentError, "#{token} must be an Integer, 0 or more"
|
|
143
|
+
end
|
|
144
|
+
end
|
|
145
|
+
WEIGHTS.each do |token|
|
|
146
|
+
next if FONT_FILES.key?(t[token])
|
|
147
|
+
|
|
148
|
+
raise ArgumentError, "#{token} must be #{FONT_FILES.keys.join(" or ")} (the bundled weights)"
|
|
149
|
+
end
|
|
150
|
+
validate_rest!(t)
|
|
151
|
+
end
|
|
152
|
+
|
|
153
|
+
def validate_rest!(t)
|
|
154
|
+
unless NUMBER_FEATURES.include?(t[:number_features])
|
|
155
|
+
raise ArgumentError, "number_features must be \"tnum\" or nil"
|
|
156
|
+
end
|
|
157
|
+
raise ArgumentError, "true_minus must be true or false" unless [true, false].include?(t[:true_minus])
|
|
158
|
+
|
|
159
|
+
exponent = t[:fade_exponent]
|
|
160
|
+
unless exponent.is_a?(Float) && exponent.positive? && exponent.finite?
|
|
161
|
+
raise ArgumentError, "fade_exponent must be a positive, finite Float"
|
|
162
|
+
end
|
|
163
|
+
raise ArgumentError, "min_width must be at most max_width" if t[:min_width] > t[:max_width]
|
|
164
|
+
if t[:min_column_width] > t[:max_column_width]
|
|
165
|
+
raise ArgumentError, "min_column_width must be at most max_column_width"
|
|
166
|
+
end
|
|
167
|
+
raise ArgumentError, "edge_padding must be at least cell_padding" if t[:edge_padding] < t[:cell_padding]
|
|
168
|
+
end
|
|
169
|
+
end
|
|
170
|
+
|
|
171
|
+
# The default look (rendering.md 2.2): logical px at scale 1.
|
|
172
|
+
LEDGER = new(
|
|
173
|
+
name: :ledger,
|
|
174
|
+
font_family: "Inter",
|
|
175
|
+
body_size: 13, body_weight: 400,
|
|
176
|
+
header_size: 12, header_weight: 600,
|
|
177
|
+
footer_size: 12, footer_weight: 400,
|
|
178
|
+
number_features: "tnum",
|
|
179
|
+
true_minus: true,
|
|
180
|
+
text_color: "#1F2328",
|
|
181
|
+
muted_color: "#6B7280",
|
|
182
|
+
header_text_color: "#5B6472",
|
|
183
|
+
header_fill: "#EEF0F3",
|
|
184
|
+
header_rule_color: "#DDE1E6", header_rule_width: 1,
|
|
185
|
+
row_rule_color: "#EDEFF2", row_rule_width: 1,
|
|
186
|
+
footer_rule_color: "#E3E6EA", footer_rule_width: 1,
|
|
187
|
+
frame_color: "#E3E6EA", frame_width: 1,
|
|
188
|
+
background: "#FFFFFF",
|
|
189
|
+
header_height: 36, row_height: 36, footer_height: 36,
|
|
190
|
+
cell_padding: 12, edge_padding: 20,
|
|
191
|
+
min_column_width: 56, max_column_width: 260,
|
|
192
|
+
min_width: 320, max_width: 1024,
|
|
193
|
+
fade_width: 72, fade_exponent: 1.5,
|
|
194
|
+
peek_width: 120,
|
|
195
|
+
empty_body_rows: 3
|
|
196
|
+
)
|
|
197
|
+
|
|
198
|
+
ALL = { ledger: LEDGER }.freeze
|
|
199
|
+
|
|
200
|
+
# @param name [Symbol]
|
|
201
|
+
# @return [Theme]
|
|
202
|
+
# @raise [ArgumentError] for an unknown name
|
|
203
|
+
def self.fetch(name)
|
|
204
|
+
ALL.fetch(name) { raise ArgumentError, "unknown theme #{name.inspect}" }
|
|
205
|
+
end
|
|
206
|
+
end
|
|
207
|
+
end
|
data/lib/csv_preview.rb
ADDED
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
|
|
3
|
+
# macOS: libvips ignores the bundled font unless Pango uses the fontconfig backend. This must be set
|
|
4
|
+
# before the first text draw, so it happens at load time. An application's own value is never replaced.
|
|
5
|
+
if RUBY_PLATFORM.include?("darwin") && ENV["PANGOCAIRO_BACKEND"].to_s.empty?
|
|
6
|
+
ENV["PANGOCAIRO_BACKEND"] = "fontconfig"
|
|
7
|
+
end
|
|
8
|
+
|
|
9
|
+
require_relative "csv_preview/version"
|
|
10
|
+
require_relative "csv_preview/errors"
|
|
11
|
+
require_relative "csv_preview/configuration"
|
|
12
|
+
require_relative "csv_preview/deadline"
|
|
13
|
+
require_relative "csv_preview/reader"
|
|
14
|
+
require_relative "csv_preview/sanitizer"
|
|
15
|
+
require_relative "csv_preview/cell_kind"
|
|
16
|
+
require_relative "csv_preview/sample"
|
|
17
|
+
require_relative "csv_preview/parser"
|
|
18
|
+
require_relative "csv_preview/text"
|
|
19
|
+
require_relative "csv_preview/theme"
|
|
20
|
+
require_relative "csv_preview/layout"
|
|
21
|
+
require_relative "csv_preview/painter"
|
|
22
|
+
|
|
23
|
+
# Renders CSV and TSV files as preview images. ruby-vips is loaded lazily, never by this file.
|
|
24
|
+
module CsvPreview
|
|
25
|
+
# Loaded on first reference; requires Active Storage. Nothing in the core requires it.
|
|
26
|
+
autoload :ActiveStoragePreviewer, "csv_preview/active_storage_previewer"
|
|
27
|
+
|
|
28
|
+
@config = Configuration.new.resolve
|
|
29
|
+
|
|
30
|
+
class << self
|
|
31
|
+
# Yields a mutable copy of the global configuration for editing at boot. The edited copy is
|
|
32
|
+
# validated, frozen and swapped in with one assignment, so a render running concurrently never sees
|
|
33
|
+
# a half-edited configuration. If the block or validation raises, the old configuration stays.
|
|
34
|
+
# @yieldparam config [Configuration] a mutable copy of the current configuration
|
|
35
|
+
# @return [Configuration] the new global configuration (frozen)
|
|
36
|
+
# @raise [ArgumentError] an invalid value
|
|
37
|
+
# @example Set defaults once at boot
|
|
38
|
+
# CsvPreview.configure do |config|
|
|
39
|
+
# config.max_rows = 12
|
|
40
|
+
# config.previewer_content_types += ["text/x-csv"]
|
|
41
|
+
# end
|
|
42
|
+
def configure
|
|
43
|
+
copy = @config.dup
|
|
44
|
+
yield copy
|
|
45
|
+
@config = copy.resolve
|
|
46
|
+
end
|
|
47
|
+
|
|
48
|
+
# @return [Configuration] the global defaults (frozen)
|
|
49
|
+
# @example
|
|
50
|
+
# CsvPreview.config.max_rows # => 20
|
|
51
|
+
def config
|
|
52
|
+
@config
|
|
53
|
+
end
|
|
54
|
+
|
|
55
|
+
# Renders the first rows of a CSV or TSV source as an image. Empty input (0 bytes, or only blank
|
|
56
|
+
# lines and whitespace) does not raise: it renders a small image saying the file is empty.
|
|
57
|
+
#
|
|
58
|
+
# @param source [String, Pathname, #read] a path, or an IO-like object read with `read(length)` only
|
|
59
|
+
# (never rewound or closed)
|
|
60
|
+
# @param options [Hash] per-call options; see {Configuration}. `format` picks :png (default), :jpeg
|
|
61
|
+
# or :webp.
|
|
62
|
+
# @return [String] the encoded image (binary)
|
|
63
|
+
# @raise [ArgumentError] invalid options or source
|
|
64
|
+
# @raise [UnreadableInput] binary or non-text content
|
|
65
|
+
# @raise [RenderFailed] libvips is missing, cannot draw text, or cannot encode the format
|
|
66
|
+
# @raise [TimeoutExceeded] the call ran past `timeout`
|
|
67
|
+
# @raise [SystemCallError] the path cannot be opened or read (for example `Errno::ENOENT`)
|
|
68
|
+
# @example Write a PNG preview of a file
|
|
69
|
+
# File.binwrite("orders.png", CsvPreview.render("orders.csv"))
|
|
70
|
+
# @example Render CSV text from memory as WebP (a String is always a path, so wrap text in StringIO)
|
|
71
|
+
# webp = CsvPreview.render(StringIO.new("Fruit,Qty\nApple,3\n"), format: :webp, max_rows: 10)
|
|
72
|
+
def render(source, **options)
|
|
73
|
+
config = self.config.resolve(**options)
|
|
74
|
+
deadline = Deadline.new(config.timeout)
|
|
75
|
+
layout = build_layout(source, config, deadline)
|
|
76
|
+
Painter.call(layout, format: config.format, deadline: deadline)
|
|
77
|
+
end
|
|
78
|
+
|
|
79
|
+
# Reads and parses a CSV or TSV source without rendering anything.
|
|
80
|
+
#
|
|
81
|
+
# @param source [String, Pathname, #read] a path, or an IO-like object read with `read(length)` only
|
|
82
|
+
# (never rewound or closed)
|
|
83
|
+
# @param options [Hash] per-call options; see {Configuration}
|
|
84
|
+
# @return [Sample]
|
|
85
|
+
# @raise [ArgumentError] invalid options or source
|
|
86
|
+
# @raise [UnreadableInput] binary or non-text content
|
|
87
|
+
# @raise [TimeoutExceeded] the call ran past `timeout`
|
|
88
|
+
# @raise [SystemCallError] the path cannot be opened or read (for example `Errno::ENOENT`)
|
|
89
|
+
# @example
|
|
90
|
+
# sample = CsvPreview.sample("orders.csv")
|
|
91
|
+
# sample.headers.first(2) # => ["Transaction ID", "Date"]
|
|
92
|
+
# sample.total_rows # => 1284, or nil when the file is larger than max_input_bytes
|
|
93
|
+
def sample(source, **options)
|
|
94
|
+
config = self.config.resolve(**options)
|
|
95
|
+
read(source, config, Deadline.new(config.timeout))
|
|
96
|
+
end
|
|
97
|
+
|
|
98
|
+
# Reads, parses and lays out a source: which columns and rows are shown, their widths, the exact
|
|
99
|
+
# display strings, the footer and the output size. For debugging and tests.
|
|
100
|
+
#
|
|
101
|
+
# @param source [String, Pathname, #read] as for {sample}
|
|
102
|
+
# @param options [Hash] per-call options; see {Configuration}
|
|
103
|
+
# @return [Layout]
|
|
104
|
+
# @raise [ArgumentError] invalid options or source
|
|
105
|
+
# @raise [UnreadableInput] binary or non-text content
|
|
106
|
+
# @raise [RenderFailed] libvips is missing or cannot draw text
|
|
107
|
+
# @raise [TimeoutExceeded] the call ran past `timeout`
|
|
108
|
+
# @raise [SystemCallError] the path cannot be opened or read
|
|
109
|
+
# @example
|
|
110
|
+
# layout = CsvPreview.layout("orders.csv")
|
|
111
|
+
# layout.footer_text # => "20 of 1,284 rows · 8 of 31 columns"
|
|
112
|
+
# [layout.width_px, layout.height_px] # => [2048, 1588]
|
|
113
|
+
def layout(source, **options)
|
|
114
|
+
config = self.config.resolve(**options)
|
|
115
|
+
build_layout(source, config, Deadline.new(config.timeout))
|
|
116
|
+
end
|
|
117
|
+
|
|
118
|
+
# Restores factory defaults. Intended for tests.
|
|
119
|
+
# @api private
|
|
120
|
+
# @return [Configuration] the factory defaults (frozen)
|
|
121
|
+
def reset_config!
|
|
122
|
+
@config = Configuration.new.resolve
|
|
123
|
+
end
|
|
124
|
+
|
|
125
|
+
# Whether libvips is installed and can draw text. Cheap and never renders; loads ruby-vips on
|
|
126
|
+
# first use.
|
|
127
|
+
# @return [Boolean]
|
|
128
|
+
# @example A health check
|
|
129
|
+
# raise "libvips cannot draw text" unless CsvPreview.text_supported?
|
|
130
|
+
def text_supported?
|
|
131
|
+
Text.supported?
|
|
132
|
+
end
|
|
133
|
+
|
|
134
|
+
private
|
|
135
|
+
|
|
136
|
+
# One deadline covers the whole call, from the first read to the last step.
|
|
137
|
+
def read(source, config, deadline)
|
|
138
|
+
result = Reader.call(source, config: config, deadline: deadline)
|
|
139
|
+
Parser.call(result, config: config, deadline: deadline)
|
|
140
|
+
end
|
|
141
|
+
|
|
142
|
+
def build_layout(source, config, deadline)
|
|
143
|
+
sample = read(source, config, deadline)
|
|
144
|
+
Layout.build(sample, config: config, theme: Theme.fetch(config.theme), deadline: deadline)
|
|
145
|
+
end
|
|
146
|
+
end
|
|
147
|
+
end
|
|
148
|
+
|
|
149
|
+
require_relative "csv_preview/railtie" if defined?(Rails::Railtie)
|
|
@@ -0,0 +1,171 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: csv-preview
|
|
3
|
+
description: Add CSV and TSV previews and thumbnails to Active Storage attachments in a Rails app, or render a CSV file as a PNG, JPEG or WebP image in Ruby, using the csv_preview gem. Use when CSV attachments show no thumbnail, when preview or representation raises ActiveStorage::UnpreviewableError or UnrepresentableError for text/csv, or when someone wants a picture of a CSV table without LibreOffice, a headless browser or ImageMagick.
|
|
4
|
+
license: MIT
|
|
5
|
+
compatibility: Ruby 3.3+, libvips 8.12+ with Pango; Rails 7.2+ for the Active Storage previewer.
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Add csv_preview to an app
|
|
9
|
+
|
|
10
|
+
csv_preview is a Ruby gem that renders CSV and TSV files as preview images (PNG, JPEG or WebP) and adds an Active Storage previewer to Rails. Beautiful CSV previews for Active Storage. No LibreOffice, no headless browser, no network. Built for untrusted uploads: it reads at most 2 MiB, stops after 5 seconds, and never runs another program or opens a network connection.
|
|
11
|
+
|
|
12
|
+
Follow the steps in order. The README beside this directory in the installed gem (`bundle info --path csv_preview`) has the details; online at https://github.com/garyhtou/csv_preview.
|
|
13
|
+
|
|
14
|
+
## 1. When not to use it
|
|
15
|
+
|
|
16
|
+
- XLSX, ODS, Numbers or other spreadsheet files: csv_preview reads CSV and TSV text only and raises `CsvPreview::UnreadableInput` for them. Use a LibreOffice-based previewer (such as activestorage-office-previewer) for Office files; it can be registered alongside csv_preview.
|
|
17
|
+
- Rendering a whole file: previews show the first rows (20 by default) and up to 12 columns.
|
|
18
|
+
- Dark images: previews are light, inside a bordered frame.
|
|
19
|
+
|
|
20
|
+
## 2. Check the environment
|
|
21
|
+
|
|
22
|
+
- Ruby 3.3 or newer, and Rails 7.2 or newer for the previewer: read `Gemfile.lock` (`RUBY VERSION`, `activestorage`).
|
|
23
|
+
- Find the attachments that hold CSV files: `grep -rn "has_one_attached\|has_many_attached" app/models`.
|
|
24
|
+
- Find the variant processor: `config.active_storage.variant_processor` in `config/`; without it, apps on `load_defaults 7.0` or newer use `:vips`.
|
|
25
|
+
- Find where the app is built and deployed (a `Dockerfile`, server provisioning): libvips is needed there, not only on the development machine.
|
|
26
|
+
|
|
27
|
+
## 3. Install
|
|
28
|
+
|
|
29
|
+
```sh
|
|
30
|
+
bundle add csv_preview
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
System packages, wherever the app runs:
|
|
34
|
+
|
|
35
|
+
```sh
|
|
36
|
+
# Debian and Ubuntu (Rails' generated Dockerfile already installs libvips when Active Storage is enabled)
|
|
37
|
+
apt-get install --no-install-recommends libvips
|
|
38
|
+
# Optional, for colour emoji, Chinese, Japanese and Korean, and scripts such as Thai and Hindi;
|
|
39
|
+
# then run fc-cache -f in images
|
|
40
|
+
apt-get install --no-install-recommends fontconfig fonts-noto-color-emoji fonts-noto-cjk fonts-noto-core
|
|
41
|
+
# macOS
|
|
42
|
+
brew install vips
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
## 4. Verify text support
|
|
46
|
+
|
|
47
|
+
```sh
|
|
48
|
+
bin/rails runner 'p CsvPreview.text_supported?'
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
It must print `true`. If it prints `false` or fails, libvips is missing or was built without Pango: fix the installation before going on. Do not work around it; without text support CSV files are simply not previewable.
|
|
52
|
+
|
|
53
|
+
## 5. Register the previewer, exactly once
|
|
54
|
+
|
|
55
|
+
In `config/application.rb`, inside the `Application` class:
|
|
56
|
+
|
|
57
|
+
```ruby
|
|
58
|
+
config.active_storage.previewers.unshift CsvPreview::ActiveStoragePreviewer
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
`unshift` puts csv_preview first, so it wins over any other previewer that accepts `text/csv`. The equivalent setting, if the app prefers settings:
|
|
62
|
+
|
|
63
|
+
```ruby
|
|
64
|
+
config.csv_preview.register_previewer = true
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Use one of the two. If the Gemfile has `require: false` for csv_preview, add `require "csv_preview"` at the top of `config/application.rb`.
|
|
68
|
+
|
|
69
|
+
## 6. Discard files that cannot be previewed
|
|
70
|
+
|
|
71
|
+
A file labelled `text/csv` can still be binary. csv_preview then raises, the previewer raises `ActiveStorage::PreviewError`, and Active Storage's jobs would retry it. Create `config/initializers/csv_preview.rb`:
|
|
72
|
+
|
|
73
|
+
```ruby
|
|
74
|
+
Rails.application.config.to_prepare do
|
|
75
|
+
ActiveStorage::PreviewImageJob.discard_on ActiveStorage::PreviewError
|
|
76
|
+
ActiveStorage::TransformJob.discard_on ActiveStorage::PreviewError
|
|
77
|
+
end
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
`to_prepare` is required: the job classes are reloaded in development.
|
|
81
|
+
|
|
82
|
+
## 7. Views and thumbnails
|
|
83
|
+
|
|
84
|
+
Always guard with `representable?`; it is false for files without a previewer and on hosts without text support.
|
|
85
|
+
|
|
86
|
+
```erb
|
|
87
|
+
<%= image_tag document.file.representation(resize_to_limit: [800, 800]) if document.file.representable? %>
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
For thumbnails, crop to the top-left corner so the header survives. A centred crop of a wide table shows nothing useful.
|
|
91
|
+
|
|
92
|
+
```ruby
|
|
93
|
+
has_one_attached :file do |attachable|
|
|
94
|
+
# libvips (Rails' default variant processor)
|
|
95
|
+
attachable.variant :thumb, resize_to_fill: [300, 300, { crop: :low }], preprocessed: true
|
|
96
|
+
# MiniMagick: resize_to_fill: [300, 300, { gravity: "NorthWest" }]
|
|
97
|
+
end
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
```erb
|
|
101
|
+
<%= image_tag document.file.representation(:thumb) if document.file.representable? %>
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
`preprocessed: true` renders the preview in a background job right after upload. If the attachment also holds photos, add a separate CSV-only variant and choose it in the view:
|
|
105
|
+
|
|
106
|
+
```ruby
|
|
107
|
+
attachable.variant :table_thumb, resize_to_fill: [300, 300, { crop: :low }],
|
|
108
|
+
preprocessed: ->(record) { CsvPreview::ActiveStoragePreviewer.accept?(record.file.blob) }
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
Global options go in the initializer from step 6, outside the `to_prepare` block:
|
|
112
|
+
|
|
113
|
+
```ruby
|
|
114
|
+
CsvPreview.configure do |config|
|
|
115
|
+
config.max_rows = 12
|
|
116
|
+
config.previewer_content_types += %w[text/x-csv application/csv]
|
|
117
|
+
end
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
## 8. Test it
|
|
121
|
+
|
|
122
|
+
Adapt the model and attachment names to the app:
|
|
123
|
+
|
|
124
|
+
```ruby
|
|
125
|
+
# test/models/csv_preview_test.rb
|
|
126
|
+
require "test_helper"
|
|
127
|
+
|
|
128
|
+
class CsvPreviewTest < ActiveSupport::TestCase
|
|
129
|
+
test "CSV attachments are previewable" do
|
|
130
|
+
assert CsvPreview.text_supported?, "libvips cannot draw text; see the csv_preview README, Installation"
|
|
131
|
+
|
|
132
|
+
document = Document.create!(file: { io: StringIO.new("Item,Amount\nCoffee,4.50\n"),
|
|
133
|
+
filename: "items.csv", content_type: "text/csv" })
|
|
134
|
+
|
|
135
|
+
assert document.file.previewable?
|
|
136
|
+
document.file.preview(resize_to_limit: [300, 300]).processed
|
|
137
|
+
assert document.file.blob.preview_image.attached?
|
|
138
|
+
end
|
|
139
|
+
end
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
Then run the app's test command (`bin/rails test`, or the RSpec equivalent) and a smoke check that writes an image you can open:
|
|
143
|
+
|
|
144
|
+
```sh
|
|
145
|
+
bin/rails runner 'File.binwrite("tmp/csv_preview_check.png", CsvPreview.render(StringIO.new("Item,Amount\nCoffee,4.50\n")))'
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
## 9. Pitfalls
|
|
149
|
+
|
|
150
|
+
- Do not pass user-supplied text to `CsvPreview.render` as a String: a String is always a file path. Wrap CSV text in `StringIO.new(text)`.
|
|
151
|
+
- Do not add `application/vnd.ms-excel` to `previewer_content_types`: it is the type of binary XLS workbooks. The README has a subclass that accepts it only for `.csv` filenames.
|
|
152
|
+
- Do not install LibreOffice, ImageMagick or a headless browser for CSV previews; csv_preview needs none of them.
|
|
153
|
+
- Do not register the previewer twice, or append it with `<<` when another previewer accepts `text/csv` (the first one that accepts a file wins).
|
|
154
|
+
- Do not expect existing preview images to change after an upgrade: purge and reprocess them (`blob.preview_image.purge`, then `blob.preview({}).processed`).
|
|
155
|
+
- Do not require the gem lazily inside a request: on macOS it must load before anything draws text, and the setting from step 5 is ignored when the gem loads after boot.
|
|
156
|
+
- Do not call `representation` without checking `representable?`, and do not use `resize_to_fill` without `crop: :low` (or `gravity: "NorthWest"`) for CSV thumbnails.
|
|
157
|
+
|
|
158
|
+
## 10. Plain Ruby
|
|
159
|
+
|
|
160
|
+
```ruby
|
|
161
|
+
require "csv_preview"
|
|
162
|
+
File.binwrite("orders.png", CsvPreview.render("orders.csv"))
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
`CsvPreview.render(path_or_io, **options)` returns image bytes; `format: :jpeg` or `format: :webp` changes the format. `CsvPreview.sample(path_or_io)` returns the cleaned cells without rendering. Rescue `CsvPreview::UnreadableInput` (not CSV text) and `CsvPreview::TimeoutExceeded` to show a fallback.
|
|
166
|
+
|
|
167
|
+
## Links
|
|
168
|
+
|
|
169
|
+
- README sections: Installation, Rails usage, Plain Ruby usage, Options, Security and FAQ, in `README.md` of the installed gem or at https://github.com/garyhtou/csv_preview
|
|
170
|
+
- Security policy: `SECURITY.md` in the installed gem
|
|
171
|
+
- API reference: https://rubydoc.info/gems/csv_preview
|
metadata
ADDED
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
--- !ruby/object:Gem::Specification
|
|
2
|
+
name: csv_preview
|
|
3
|
+
version: !ruby/object:Gem::Version
|
|
4
|
+
version: 0.1.0
|
|
5
|
+
platform: ruby
|
|
6
|
+
authors:
|
|
7
|
+
- Gary Tou
|
|
8
|
+
bindir: bin
|
|
9
|
+
cert_chain: []
|
|
10
|
+
date: 1980-01-02 00:00:00.000000000 Z
|
|
11
|
+
dependencies:
|
|
12
|
+
- !ruby/object:Gem::Dependency
|
|
13
|
+
name: csv
|
|
14
|
+
requirement: !ruby/object:Gem::Requirement
|
|
15
|
+
requirements:
|
|
16
|
+
- - ">="
|
|
17
|
+
- !ruby/object:Gem::Version
|
|
18
|
+
version: 3.2.8
|
|
19
|
+
- - "<"
|
|
20
|
+
- !ruby/object:Gem::Version
|
|
21
|
+
version: '4'
|
|
22
|
+
type: :runtime
|
|
23
|
+
prerelease: false
|
|
24
|
+
version_requirements: !ruby/object:Gem::Requirement
|
|
25
|
+
requirements:
|
|
26
|
+
- - ">="
|
|
27
|
+
- !ruby/object:Gem::Version
|
|
28
|
+
version: 3.2.8
|
|
29
|
+
- - "<"
|
|
30
|
+
- !ruby/object:Gem::Version
|
|
31
|
+
version: '4'
|
|
32
|
+
- !ruby/object:Gem::Dependency
|
|
33
|
+
name: ruby-vips
|
|
34
|
+
requirement: !ruby/object:Gem::Requirement
|
|
35
|
+
requirements:
|
|
36
|
+
- - ">="
|
|
37
|
+
- !ruby/object:Gem::Version
|
|
38
|
+
version: 2.2.2
|
|
39
|
+
- - "<"
|
|
40
|
+
- !ruby/object:Gem::Version
|
|
41
|
+
version: '3'
|
|
42
|
+
type: :runtime
|
|
43
|
+
prerelease: false
|
|
44
|
+
version_requirements: !ruby/object:Gem::Requirement
|
|
45
|
+
requirements:
|
|
46
|
+
- - ">="
|
|
47
|
+
- !ruby/object:Gem::Version
|
|
48
|
+
version: 2.2.2
|
|
49
|
+
- - "<"
|
|
50
|
+
- !ruby/object:Gem::Version
|
|
51
|
+
version: '3'
|
|
52
|
+
description: 'csv_preview is a Ruby gem that renders CSV and TSV files as preview
|
|
53
|
+
images (PNG, JPEG or WebP) and adds an Active Storage previewer to Rails. It turns
|
|
54
|
+
the first rows of a file into a clean, readable table image: a thumbnail for a file
|
|
55
|
+
list or a larger preview for a detail page. In Rails, CsvPreview::ActiveStoragePreviewer
|
|
56
|
+
(an ActiveStorage::Previewer) makes CSV attachments work with blob.preview, blob.representation
|
|
57
|
+
and previewable? the same way PDFs and videos do. It draws text with libvips (vips)
|
|
58
|
+
and Pango, needs no LibreOffice, headless browser or ImageMagick, never starts another
|
|
59
|
+
process or opens a network connection, and treats every file as untrusted input
|
|
60
|
+
with bounded reads, memory and time.'
|
|
61
|
+
executables: []
|
|
62
|
+
extensions: []
|
|
63
|
+
extra_rdoc_files: []
|
|
64
|
+
files:
|
|
65
|
+
- ".yardopts"
|
|
66
|
+
- CHANGELOG.md
|
|
67
|
+
- LICENSE
|
|
68
|
+
- README.md
|
|
69
|
+
- SECURITY.md
|
|
70
|
+
- fonts/Inter-Regular.ttf
|
|
71
|
+
- fonts/Inter-SemiBold.ttf
|
|
72
|
+
- fonts/OFL.txt
|
|
73
|
+
- lib/csv_preview.rb
|
|
74
|
+
- lib/csv_preview/active_storage_previewer.rb
|
|
75
|
+
- lib/csv_preview/cell_kind.rb
|
|
76
|
+
- lib/csv_preview/configuration.rb
|
|
77
|
+
- lib/csv_preview/deadline.rb
|
|
78
|
+
- lib/csv_preview/errors.rb
|
|
79
|
+
- lib/csv_preview/layout.rb
|
|
80
|
+
- lib/csv_preview/painter.rb
|
|
81
|
+
- lib/csv_preview/parser.rb
|
|
82
|
+
- lib/csv_preview/railtie.rb
|
|
83
|
+
- lib/csv_preview/reader.rb
|
|
84
|
+
- lib/csv_preview/sample.rb
|
|
85
|
+
- lib/csv_preview/sanitizer.rb
|
|
86
|
+
- lib/csv_preview/text.rb
|
|
87
|
+
- lib/csv_preview/theme.rb
|
|
88
|
+
- lib/csv_preview/version.rb
|
|
89
|
+
- skills/csv-preview/SKILL.md
|
|
90
|
+
homepage: https://github.com/garyhtou/csv_preview
|
|
91
|
+
licenses:
|
|
92
|
+
- MIT
|
|
93
|
+
- OFL-1.1
|
|
94
|
+
metadata:
|
|
95
|
+
homepage_uri: https://github.com/garyhtou/csv_preview
|
|
96
|
+
source_code_uri: https://github.com/garyhtou/csv_preview/tree/v0.1.0
|
|
97
|
+
changelog_uri: https://github.com/garyhtou/csv_preview/blob/main/CHANGELOG.md
|
|
98
|
+
documentation_uri: https://rubydoc.info/gems/csv_preview/0.1.0
|
|
99
|
+
bug_tracker_uri: https://github.com/garyhtou/csv_preview/issues
|
|
100
|
+
rubygems_mfa_required: 'true'
|
|
101
|
+
allowed_push_host: https://rubygems.org
|
|
102
|
+
rdoc_options: []
|
|
103
|
+
require_paths:
|
|
104
|
+
- lib
|
|
105
|
+
required_ruby_version: !ruby/object:Gem::Requirement
|
|
106
|
+
requirements:
|
|
107
|
+
- - ">="
|
|
108
|
+
- !ruby/object:Gem::Version
|
|
109
|
+
version: '3.3'
|
|
110
|
+
required_rubygems_version: !ruby/object:Gem::Requirement
|
|
111
|
+
requirements:
|
|
112
|
+
- - ">="
|
|
113
|
+
- !ruby/object:Gem::Version
|
|
114
|
+
version: '0'
|
|
115
|
+
requirements:
|
|
116
|
+
- libvips 8.12 or newer with Pango text support
|
|
117
|
+
rubygems_version: 4.0.20
|
|
118
|
+
specification_version: 4
|
|
119
|
+
summary: Render CSV and TSV files as preview images and thumbnails (PNG, JPEG, WebP)
|
|
120
|
+
using libvips. Includes an Active Storage previewer for Rails.
|
|
121
|
+
test_files: []
|