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.
@@ -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
@@ -0,0 +1,6 @@
1
+ # frozen_string_literal: true
2
+
3
+ module CsvPreview
4
+ # The gem's version, following Semantic Versioning (see the README's "Versioning and support").
5
+ VERSION = "0.1.0"
6
+ end
@@ -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: []