super_pdf 0.1.4 → 0.1.6

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 CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 1ce16f03d9694206743638dee7c85610b940706e7c214dae5a899ef159154f5d
4
- data.tar.gz: d699ea3e9a6fa88bca9ad177eae52fd9784c95802c646c49fdc8f4fc5ecd2b09
3
+ metadata.gz: b767317c59f42a442e1889f30d228e90b9ba4093e1598e33a78af5d5bbbb5936
4
+ data.tar.gz: 2e8b7d86dced0e852a9a54f0b2e61deacb4ad3391da36ed029fae0ae12ad4feb
5
5
  SHA512:
6
- metadata.gz: 7df200847d75c4170f8ce0b897362ed83adbdc00701b18d11ea0dbd3f304af3c6de0f36eb11d479391d63be16814d31a21101689a5cde3f0351f787b9635c8f1
7
- data.tar.gz: 7a9aee16a331fe56b612ba7fec4b6404eb9afd11da290db6bcf790cf29fa0a5ea053c68585f860b728762a9fe7c5577fc70b8de64a927293aed95e6c25ef5358
6
+ metadata.gz: 38b2faaec0d4655428ed27ee70c19bdd738635ef2beb4bd8f793452184e005f26224fec36447afba1f647630300ff216d98338a54aa5361ba81f8ca9b9b9197d
7
+ data.tar.gz: 1bed4dd3ac17cdc33e83532bf306e843c37e0a34d6dab2d318562894070cb0e8b6bb48de78383170c747448cdb20e5e7fedcb05c4a039003d8cc7134002c6641
@@ -0,0 +1,121 @@
1
+ name: Publish gem
2
+
3
+ # master 上 gemspec 版本號尚未發佈到 rubygems.org 時,自動以 Trusted Publishing (OIDC) 發佈。
4
+ # 版本已存在則跳過;不使用任何儲存的 RubyGems API key。
5
+ on:
6
+ push:
7
+ branches:
8
+ - master
9
+ workflow_dispatch:
10
+
11
+ permissions:
12
+ contents: read
13
+
14
+ concurrency:
15
+ group: publish-gem-${{ github.repository }}
16
+ cancel-in-progress: false
17
+
18
+ env:
19
+ # 此分支沒有既有 CI;採 gemfiles/ 中最新的 Rails 8.0(ActiveSupport 8.0.5.1)搭配 Ruby 3.4.11
20
+ RUBY_VERSION: '3.4.11'
21
+ BUNDLE_GEMFILE: ${{ github.workspace }}/gemfiles/rails_8.0.gemfile
22
+ GEM_NAME: super_pdf
23
+ GEMSPEC: super_pdf.gemspec
24
+
25
+ jobs:
26
+ check:
27
+ name: Check version on rubygems.org
28
+ runs-on: ubuntu-latest
29
+ outputs:
30
+ should_publish: ${{ steps.check.outputs.should_publish }}
31
+ gem_name: ${{ steps.spec.outputs.name }}
32
+ gem_version: ${{ steps.spec.outputs.version }}
33
+ steps:
34
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
35
+ with:
36
+ persist-credentials: false
37
+
38
+ - uses: ruby/setup-ruby@b1da4809b005e0178fe08a1d57317bffc00b7b4c # v1.332.0
39
+ with:
40
+ ruby-version: ${{ env.RUBY_VERSION }}
41
+
42
+ - name: Read gem name and version from gemspec
43
+ id: spec
44
+ run: |
45
+ ruby -e 'spec = Gem::Specification.load(ENV.fetch("GEMSPEC")) or abort("cannot load #{ENV["GEMSPEC"]}"); abort("gemspec name #{spec.name} != #{ENV["GEM_NAME"]}") unless spec.name == ENV["GEM_NAME"]; puts "name=#{spec.name}"; puts "version=#{spec.version}"' >> "$GITHUB_OUTPUT"
46
+ cat "$GITHUB_OUTPUT"
47
+
48
+ - name: Check whether this version already exists on rubygems.org
49
+ id: check
50
+ env:
51
+ GEM_NAME: ${{ steps.spec.outputs.name }}
52
+ GEM_VERSION: ${{ steps.spec.outputs.version }}
53
+ run: |
54
+ set -euo pipefail
55
+ status=$(curl -sS -o versions.json -w '%{http_code}' "https://rubygems.org/api/v1/versions/${GEM_NAME}.json")
56
+ if [ "$status" = "404" ]; then
57
+ echo "Gem ${GEM_NAME} not found on rubygems.org; will publish."
58
+ echo "should_publish=true" >> "$GITHUB_OUTPUT"
59
+ exit 0
60
+ fi
61
+ if [ "$status" != "200" ]; then
62
+ echo "::error::rubygems.org API returned HTTP ${status}"
63
+ exit 1
64
+ fi
65
+ if jq -e --arg v "$GEM_VERSION" 'any(.[]; .number == $v)' versions.json > /dev/null; then
66
+ echo "${GEM_NAME} ${GEM_VERSION} already on rubygems.org; skip publish."
67
+ echo "should_publish=false" >> "$GITHUB_OUTPUT"
68
+ else
69
+ echo "${GEM_NAME} ${GEM_VERSION} not on rubygems.org yet; will publish."
70
+ echo "should_publish=true" >> "$GITHUB_OUTPUT"
71
+ fi
72
+
73
+ test:
74
+ name: Test (Ruby 3.4 / Rails 8.0)
75
+ needs: check
76
+ if: needs.check.outputs.should_publish == 'true'
77
+ runs-on: ubuntu-latest
78
+ steps:
79
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
80
+ with:
81
+ persist-credentials: false
82
+
83
+ - uses: ruby/setup-ruby@b1da4809b005e0178fe08a1d57317bffc00b7b4c # v1.332.0
84
+ with:
85
+ ruby-version: ${{ env.RUBY_VERSION }}
86
+ bundler-cache: true
87
+
88
+ - run: bundle exec rake test
89
+
90
+ publish:
91
+ name: Publish ${{ needs.check.outputs.gem_name }} ${{ needs.check.outputs.gem_version }}
92
+ needs: [check, test]
93
+ if: needs.check.outputs.should_publish == 'true' && github.ref == 'refs/heads/master'
94
+ runs-on: ubuntu-latest
95
+ environment: gem-publish
96
+ permissions:
97
+ id-token: write # Trusted Publishing (OIDC)
98
+ contents: write # rake release 推送 vX.Y.Z tag
99
+ steps:
100
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
101
+ with:
102
+ persist-credentials: false
103
+
104
+ - uses: ruby/setup-ruby@b1da4809b005e0178fe08a1d57317bffc00b7b4c # v1.332.0
105
+ with:
106
+ ruby-version: ${{ env.RUBY_VERSION }}
107
+ bundler-cache: true
108
+
109
+ # setup-ruby 的 bundler-cache 會把 BUNDLE_PATH 等設定寫進 .bundle/config,
110
+ # 若該檔被 git 追蹤,rake release 的 guard_clean 會判定工作目錄不乾淨。
111
+ # 目前此 repo 沒有追蹤任何 .bundle/config;這一步對「有追蹤才標記」做容錯處理,
112
+ # 日後若加入 gemfiles/.bundle/config 或 .bundle/config 也不會讓發佈失敗。
113
+ - name: Ignore CI-only bundler config change
114
+ run: |
115
+ git status --porcelain
116
+ git ls-files -z '*.bundle/config' | xargs -0 -r git update-index --assume-unchanged
117
+ git status --porcelain
118
+
119
+ # 透過 rubygems/configure-rubygems-credentials 取得短效 OIDC token,
120
+ # 再執行 bundle exec rake release(build、建立並推送 vX.Y.Z tag、push gem)
121
+ - uses: rubygems/release-gem@7f9650160c1a4e7989fdc9855807bdbd421d8b6b # v1.4.1
@@ -0,0 +1,47 @@
1
+ name: Tests
2
+
3
+ on:
4
+ push:
5
+ branches: [ master, main ]
6
+ pull_request:
7
+ branches: [ master, main ]
8
+
9
+ permissions:
10
+ contents: read
11
+
12
+ jobs:
13
+ test:
14
+ name: Ruby ${{ matrix.ruby }} / Rails ${{ matrix.rails }}
15
+ runs-on: ubuntu-latest
16
+ strategy:
17
+ fail-fast: false
18
+ matrix:
19
+ ruby: ["3.0", "3.1", "3.2", "3.3", "3.4"]
20
+ rails: ["7.0", "7.1", "7.2", "8.0", "8.1"]
21
+ exclude:
22
+ # Rails 7.2 需要 Ruby >= 3.1
23
+ - ruby: "3.0"
24
+ rails: "7.2"
25
+ # Rails 8.0 / 8.1 需要 Ruby >= 3.2
26
+ - ruby: "3.0"
27
+ rails: "8.0"
28
+ - ruby: "3.0"
29
+ rails: "8.1"
30
+ - ruby: "3.1"
31
+ rails: "8.0"
32
+ - ruby: "3.1"
33
+ rails: "8.1"
34
+ env:
35
+ BUNDLE_GEMFILE: ${{ github.workspace }}/gemfiles/rails_${{ matrix.rails }}.gemfile
36
+ steps:
37
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
38
+ with:
39
+ persist-credentials: false
40
+
41
+ - uses: ruby/setup-ruby@b1da4809b005e0178fe08a1d57317bffc00b7b4c # v1.332.0
42
+ with:
43
+ ruby-version: ${{ matrix.ruby }}
44
+ bundler-cache: true
45
+
46
+ - name: Run tests
47
+ run: bundle exec rake test
data/.gitignore CHANGED
@@ -8,3 +8,7 @@
8
8
  /spec/reports/
9
9
  /tmp/
10
10
  *.gem
11
+
12
+ # gem 測試用(gemfiles/*.gemfile 由 CI 解析,不追蹤 lockfile,各 Ruby 版本的 Bundler 不同)
13
+ /gemfiles/*.gemfile.lock
14
+ /gemfiles/.bundle/
data/CHANGELOG.md ADDED
@@ -0,0 +1,77 @@
1
+ # 更新紀錄(Changelog)
2
+
3
+ 本檔記錄此專案所有值得注意的變更。
4
+
5
+ 格式參考 [Keep a Changelog](https://keepachangelog.com/zh-TW/1.1.0/),版本號遵循 [Semantic Versioning](https://semver.org/lang/zh-TW/)。
6
+
7
+ ## [Unreleased]
8
+
9
+ ### Added
10
+
11
+ - 新增 `CHANGELOG.md`。
12
+ - README:說明這個 gem 是什麼、環境需求、安裝、使用範例、開發與發版方式。
13
+ - CLAUDE.md:每個 PR 都必須同步更新 `README.md` 與 `CHANGELOG.md`;`README.md` 與 `CHANGELOG.md` 一律用繁體中文撰寫。
14
+
15
+ ### Changed
16
+
17
+ - `README.md`、`CHANGELOG.md` 改以繁體中文(zh-TW)撰寫。
18
+
19
+ ## [0.1.6] - 2026-10-27
20
+
21
+ ### Fixed
22
+
23
+ - `div`、`row` 與 `row.column` 在 Ruby 3.x 會 raise `ArgumentError (wrong number of arguments (given 2, expected 1))`,原因是 `div` 把 Hash 傳給使用 keyword argument 的 `margin_div` / `padding_div`。現在改成以 `**` 展開 options,因此可在 Ruby 3.0–3.4 運作,並且所有既有的呼叫方式(`div(margin: 10)`、`div({ margin: 10 })`、`row.column(width: "50%")`)都能繼續使用。公開 API 沒有變動。
24
+ - `row.column(options)` 不再刪除呼叫端傳入的 Hash 裡的 `:width`(改為對複本操作)。
25
+
26
+ ### Added
27
+
28
+ - `div`(keyword / hash options、邊框、背景色、百分比寬度、不會改動傳入的 options)以及 `row` / `column` 的測試。
29
+
30
+ ## [0.1.5] - 2026-10-27
31
+
32
+ ### Added
33
+
34
+ - GitHub Actions 測試 workflow:Ruby 3.0–3.4 × Rails(ActiveSupport)7.0–8.1 矩陣。
35
+ - GitHub Actions workflow `publish.yml`:新版本進到 `master` 時自動發佈到 RubyGems(Trusted Publishing)。
36
+ - CLAUDE.md:加入發版 / 跳版號規則。
37
+
38
+ ### Changed
39
+
40
+ - 支援 ActiveSupport 8 與 Ruby 3.3–3.4:gemspec 宣告 `required_ruby_version >= 2.7`,並相依 `matrix` 與 `ostruct`(在較新的 Ruby 已不再是 default gem);明確 require ActiveSupport 的 `Concern` / `delegation`;`draw_border` 的 keyword arguments 改用 splat 傳遞。
41
+ - 依 ActiveSupport 版本拆分 Gemfile(`gemfiles/rails_7.0.gemfile` … `rails_8.1.gemfile`)。
42
+
43
+ ## [0.1.4] - 2019-10-18
44
+
45
+ ### Added
46
+
47
+ - 新增 `SuperPDF.extension_add(base)` 與 `SuperPDF.extensions`,用來註冊 `Prawn::Document` 的擴充。
48
+
49
+ ### Fixed
50
+
51
+ - 放寬 `activesupport` 的版本限制(`>= 4`)。
52
+
53
+ ## [0.1.2] - 2019-09-17
54
+
55
+ ### Changed
56
+
57
+ - 動態 document:`SuperPDF::Enhance#pdf` 現在會建立一個匿名的 `Prawn::Document` 子類別(並 mix in `SuperPDF::Renderer`),不再使用靜態的 `SuperPDF::Document` class(該 class 已移除)。
58
+
59
+ ## [0.1.1] - 2019-09-17
60
+
61
+ ### Added
62
+
63
+ - 新增 runtime 相依套件 `prawn-icon`。
64
+
65
+ ## [0.1.0] - 2019-09-02
66
+
67
+ ### Added
68
+
69
+ - 首次發佈:在 Prawn 之上提供 `SuperPDF::Enhance`、`SuperPDF::Page`(頁面尺寸)、`SuperPDF::Font`(預設字型 family)與 `SuperPDF::Renderer`(`page`、`margin_div`、`padding_div`、`abs_div`、`row`/`column`、`scale`、邊框與背景色)。
70
+
71
+ [Unreleased]: https://github.com/superlanding/super_pdf/compare/v0.1.6...HEAD
72
+ [0.1.6]: https://github.com/superlanding/super_pdf/compare/v0.1.5...v0.1.6
73
+ [0.1.5]: https://github.com/superlanding/super_pdf/compare/v0.1.4...v0.1.5
74
+ [0.1.4]: https://github.com/superlanding/super_pdf/tree/v0.1.4
75
+ [0.1.2]: https://github.com/superlanding/super_pdf/tree/0.1.2
76
+ [0.1.1]: https://github.com/superlanding/super_pdf/tree/0.1.1
77
+ [0.1.0]: https://github.com/superlanding/super_pdf/commit/e85890b
data/CLAUDE.md ADDED
@@ -0,0 +1,21 @@
1
+ # CLAUDE.md
2
+
3
+ ## 發版規則(Ruby gem)
4
+
5
+ - 這個 gem(`super_pdf`,gemspec:`super_pdf.gemspec`)在 master 收到「新版本號」時,由 GitHub Actions(`.github/workflows/publish.yml`)自動發佈到 rubygems.org(Trusted Publishing,不使用 API key)。
6
+ - **每一個 PR 都必須跳版號**(改 `lib/super_pdf/version.rb`),除非這個 PR 只改文件、CI 或 CLAUDE.md 且明確不需要發版。沒跳版號的 PR 合進 master 後不會發佈。
7
+ - 跳版規則(Semantic Versioning):修 bug 跳 patch(x.y.Z);新增相容功能跳 minor(x.Y.0);不相容變更跳 major(X.0.0)。
8
+ - 版號只改在 PR 裡。AI 帳號只能開 branch 與 PR,不得合併到 master;只有真人帳號可以合併。合併就等於批准發佈。
9
+ - 不得為了讓測試通過而改變程式原本的行為。
10
+
11
+ ## 文件與更新紀錄(README / CHANGELOG)
12
+
13
+ - **每一個 PR 都必須同步更新文件**:
14
+ - 只要行為、用法、設定、相依套件或支援的 Ruby / Rails 版本有變,就要更新 `README.md`。
15
+ - 一律要在 `CHANGELOG.md` 新增一筆條目([Keep a Changelog](https://keepachangelog.com/zh-TW/1.1.0/) 格式,分類用 Added / Changed / Deprecated / Removed / Fixed / Security)。
16
+ - **語言規則**:`README.md` 與 `CHANGELOG.md` 一律用繁體中文(zh-TW,台灣用語)撰寫;程式碼、識別字(class / 方法 / 變數名稱)、指令、檔名與路徑維持英文,不要翻譯。
17
+ - `CHANGELOG.md` 的寫法:
18
+ - 沒有跳版號的 PR:寫在最上方的 `## [Unreleased]` 底下。
19
+ - 有跳版號的 PR:把條目寫在新的版本章節 `## [x.y.z] - YYYY-MM-DD`(日期為合併日),並同步更新檔尾的版本比較連結。
20
+ - 版本號必須與 rubygems.org 上實際發佈的版本一致,不得寫還沒發佈的版本。
21
+ - 只改文件、CI 或 CLAUDE.md 的 PR 不需要跳版號,但仍要在 `CHANGELOG.md` 的 `Unreleased` 補一筆。
data/README.md CHANGED
@@ -1,41 +1,166 @@
1
1
  # SuperPDF
2
2
 
3
- Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/super_pdf`. To experiment with that code, run `bin/console` for an interactive prompt.
3
+ [![Gem Version](https://badge.fury.io/rb/super_pdf.svg)](https://rubygems.org/gems/super_pdf)
4
+ [![Tests](https://github.com/superlanding/super_pdf/actions/workflows/test.yml/badge.svg)](https://github.com/superlanding/super_pdf/actions/workflows/test.yml)
4
5
 
5
- TODO: Delete this and the text above, and describe your gem
6
+ SuperPDF 是建構在 [Prawn](https://prawnpdf.org/) 之上的一層簡易排版工具。在任何一般的 Ruby class 裡 include
7
+ `SuperPDF::Enhance`,就會得到一個 `pdf` 物件(也就是 `Prawn::Document`),並附帶類似 CSS 的輔助方法:
8
+ 可設定 margin / padding / border / 背景色的區塊、絕對定位區塊、預設字型,以及具名的頁面尺寸。
6
9
 
7
- ## Installation
10
+ 它只依賴 `activesupport`(不需要完整的 Rails 應用程式),所以 Rails、Sidekiq job、一般腳本等環境都能使用。
8
11
 
9
- Add this line to your application's Gemfile:
12
+ ## 環境需求
13
+
14
+ | | 支援版本(CI 都有測試) |
15
+ |---|---|
16
+ | Ruby | 3.0、3.1、3.2、3.3、3.4(gemspec:`>= 2.7`) |
17
+ | ActiveSupport / Rails | 7.0、7.1、7.2、8.0、8.1(gemspec:`activesupport >= 4`) |
18
+ | Runtime 相依套件 | `prawn ~> 2.2`、`prawn-table 0.2.2`、`prawn-icon 2.4.0`、`matrix`、`ostruct` |
19
+
20
+ CI 會跑所有該 Ruby 版本允許的 Ruby × ActiveSupport 組合
21
+ (Rails 7.2 需要 Ruby >= 3.1,Rails 8.0 / 8.1 需要 Ruby >= 3.2)。
22
+ 詳見 [`.github/workflows/test.yml`](.github/workflows/test.yml)。
23
+
24
+ ## 安裝
25
+
26
+ 在應用程式的 Gemfile 加入這一行:
27
+
28
+ ```ruby
29
+ gem "super_pdf"
30
+ ```
31
+
32
+ 然後執行 `bundle install`,或自行執行 `gem install super_pdf` 安裝。
33
+
34
+ ## 使用方式
35
+
36
+ ### 1. 註冊字型與頁面尺寸(只需做一次,例如放在 initializer)
37
+
38
+ ```ruby
39
+ require "super_pdf"
40
+
41
+ # 頁面尺寸:名稱 => [寬, 高],單位為 PDF point(1 pt = 1/72 英吋),
42
+ # 也可以是 Prawn 的 :page_size 接受的任何值,例如 "A4"。預設為 "A4"。
43
+ SuperPDF::Page::SIZE["label_100x150"] = [283.46, 425.2]
44
+
45
+ # 字型:key 請用 String,value 是 Prawn 的 font family hash。
46
+ SuperPDF::Font::FAMILIES["NotoSansTC"] = {
47
+ normal: Rails.root.join("app/assets/fonts/NotoSansTC-Regular.ttf").to_s,
48
+ bold: Rails.root.join("app/assets/fonts/NotoSansTC-Bold.ttf").to_s
49
+ }
50
+ ```
51
+
52
+ ### 2. 在你的 class 裡 include `SuperPDF::Enhance`
53
+
54
+ ```ruby
55
+ class ShippingLabelPDF
56
+ include SuperPDF::Enhance
57
+
58
+ page_size "label_100x150" # SuperPDF::Page::SIZE 的 key(預設:"A4")
59
+ default_font "NotoSansTC" # SuperPDF::Font::FAMILIES 的 key
60
+
61
+ def render
62
+ pdf.page(margin: 10) do
63
+ pdf.margin_div([0, 0, 10, 0], height: 40, border: "1pt solid #222") do
64
+ pdf.text "Shipping label", size: 14, align: :center
65
+ end
66
+
67
+ pdf.padding_div(5, width: 200, height: 60, border: true) do
68
+ pdf.text "Padded box"
69
+ end
70
+
71
+ pdf.abs_div(left: 10, top: 150, right: 10, bottom: 10, background_color: "#f0ffc1") do
72
+ pdf.text "Absolutely positioned", size: 8
73
+ end
74
+
75
+ pdf.scale(0.8, position: :center) { pdf.text "Scaled" }
76
+ end
77
+
78
+ pdf.render # => PDF 二進位字串;要寫成檔案請用 pdf.render_file("label.pdf")
79
+ end
80
+ end
81
+
82
+ File.binwrite("label.pdf", ShippingLabelPDF.new.render)
83
+ ```
84
+
85
+ `pdf` 在每個 instance 內只會建立一次(memoize),建立時帶有 `skip_page_creation: true` 且 margin 為 0,
86
+ 所以一律要從 `pdf.page` 開始。
87
+
88
+ ### `pdf` 提供的輔助方法
89
+
90
+ | 方法 | 說明 |
91
+ |---|---|
92
+ | `page(options = {}) { }` | 開新的一頁(可帶 `size:`、`layout:`、`margin:`、`font:` 等),並以預設字型執行 block。`size:` 會到 `SuperPDF::Page::SIZE` 查詢。 |
93
+ | `text(string, family: "Name", **prawn_options)` | 即 `Prawn::Document#text`,可用 `family:` 指定這次呼叫使用的字型。 |
94
+ | `margin_div(margin, width:, height:, border:, background_color:) { }` | 帶外距(margin)的區塊。寬 / 高可傳 point 數值或 `"50%"` 字串。 |
95
+ | `padding_div(padding, width:, height:, border:, background_color:) { }` | 帶內距(padding)的區塊。 |
96
+ | `div(margin:, padding:, width:, height:, border:, background_color:) { }` | 一次呼叫就同時具備 `margin_div` 與 `padding_div`(options 可用 keyword 或 Hash 傳入)。 |
97
+ | `row { \|row\| row.column(width: "50%", **div_options) { } }` | 類似 Bootstrap 的 grid:欄(column)在 row 內由左到右排列。 |
98
+ | `abs_div(left:, right:, top:, bottom:, border:, background_color:) { }` | 在目前的 bounds 內做絕對定位的區塊(數值或 `"10%"`);結束後會還原游標位置。 |
99
+ | `scale(factor, origin: [x, y], position: :center) { }` | 縮放 block 內的內容。 |
100
+ | `fill_background_color("#f0ffc1")` | 以背景色填滿目前的 bounds(`#rgb` 或 `#rrggbb`)。 |
101
+ | `page_width`、`page_height` | 扣除 margin 之後的可用區域大小。 |
102
+
103
+ margin / padding 的值沿用 CSS 簡寫規則:`10`、`[vertical, horizontal]`、`[top, horizontal, bottom]`
104
+ 或 `[top, right, bottom, left]`。
105
+
106
+ border 的值可以是 `true`(1 pt 實線、黑色)、像 `"1pt dashed #222"` 這樣的字串
107
+ (`<width><mm|cm|dm|m|in|yd|ft|pt> <solid|dashed|dotted> #<rgb|rrggbb>`),或是 hash
108
+ `{ color: "222222", style: "solid", width: 1 }`。
109
+
110
+ ### 擴充 Prawn
10
111
 
11
112
  ```ruby
12
- gem 'super_pdf'
113
+ SuperPDF.extension_add(MyPrawnExtension) # 等同於 Prawn::Document.extensions << MyPrawnExtension
114
+ SuperPDF.extensions # => Prawn::Document.extensions
13
115
  ```
14
116
 
15
- And then execute:
117
+ ### 已知限制
16
118
 
17
- $ bundle
119
+ 以下是目前實作造成的限制,先寫在這裡,避免你踩到:
18
120
 
19
- Or install it yourself as:
121
+ - `div(width: "50%")` 會把百分比套用兩次(先套在 margin 區塊,再套在裡面的 padding 區塊),所以內容實際只有 25 % 寬。
122
+ 為了相容性保留這個行為;要精確的百分比請改用 `margin_div` / `padding_div`,或使用數值寬度。
123
+ - 目前版本的 Prawn 是以 String 查詢字型 family 名稱,所以註冊與選用字型時請用 **String** 名稱
124
+ (`"NotoSansTC"`,不要用 `:NotoSansTC`)。
125
+ - 此 repo 內的 `test/support/font/MSJH.ttf` 是空的佔位檔;測試不會用真正的字型來 render。
20
126
 
21
- $ gem install super_pdf
127
+ ## 開發
22
128
 
23
- ## Usage
129
+ ```bash
130
+ git clone https://github.com/superlanding/super_pdf.git
131
+ cd super_pdf
132
+ bin/setup # 用預設 Gemfile 執行 bundle install
24
133
 
25
- TODO: Write usage instructions here
134
+ # 針對單一 Ruby / Rails 組合跑測試(和 CI 的做法相同)
135
+ BUNDLE_GEMFILE=$PWD/gemfiles/rails_8.1.gemfile bundle install
136
+ BUNDLE_GEMFILE=$PWD/gemfiles/rails_8.1.gemfile bundle exec rake test
137
+
138
+ bin/console # 互動式 console
139
+ ```
26
140
 
27
- ## Development
141
+ 可用的 gemfile:`gemfiles/rails_7.0.gemfile` … `gemfiles/rails_8.1.gemfile`。測試使用 Minitest 與 Mocha
142
+ (`test/**/*_test.rb`)。`rake`(預設 task)會執行測試。
28
143
 
29
- After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
144
+ ## 發版
30
145
 
31
- To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
146
+ 發版透過 RubyGems [Trusted Publishing](https://guides.rubygems.org/trusted-publishing/) 自動完成
147
+ (repo 內不存放任何 API key):
32
148
 
33
- ## Contributing
149
+ 1. 在你的 pull request 裡,依 [Semantic Versioning](https://semver.org/lang/zh-TW/) 修改 `lib/super_pdf/version.rb` 的
150
+ `SuperPDF::VERSION`(修 bug → patch、相容的新功能 → minor、不相容的變更 → major)。
151
+ 2. 在 `CHANGELOG.md` 的新版本區塊新增對應條目。
152
+ 3. PR 經過 review 後**合併進 `master`**(只有真人可以合併)。
153
+ 4. [`.github/workflows/publish.yml`](.github/workflows/publish.yml) 會在 `master` 上執行:比對 gemspec 版本與
154
+ rubygems.org 上的版本,執行測試,若是新版本就發佈 gem 並推送 `vX.Y.Z` tag。
155
+ 沒有改版本號的合併不會發佈任何東西。
34
156
 
35
- Bug reports and pull requests are welcome on GitHub at https://github.com/vegeta/super_pdf.
157
+ 只改文件或 CI 的 pull request 不需要跳版號。貢獻規則請見 [CLAUDE.md](CLAUDE.md)
158
+ (每個 PR 也都必須更新 `README.md` 與 `CHANGELOG.md`)。
36
159
 
160
+ ## 貢獻
37
161
 
38
- ## License
162
+ 歡迎到 https://github.com/superlanding/super_pdf 回報問題與提交 pull request。
39
163
 
40
- The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
164
+ ## 授權
41
165
 
166
+ 本 gem 以 [MIT License](LICENSE.txt) 條款開源。
@@ -0,0 +1,21 @@
1
+ # frozen_string_literal: true
2
+ source "https://rubygems.org"
3
+
4
+ gemspec path: ".."
5
+
6
+ gem "activesupport", "~> 7.0.0"
7
+ gem "rake", ">= 13"
8
+ gem "minitest", "~> 5.0"
9
+ gem "mocha", "~> 1.9"
10
+
11
+ # concurrent-ruby 1.3.5 起不再自動 require logger,Rails 7.0 / 7.1 會載入失敗
12
+ gem "concurrent-ruby", "< 1.3.5"
13
+
14
+ # Ruby 3.4 已不再內建這些 gem;Rails 7.0 / 7.1 沒有自行宣告,故明確列出
15
+ gem "logger"
16
+ gem "mutex_m"
17
+ gem "bigdecimal"
18
+ gem "base64"
19
+ gem "drb"
20
+ gem "matrix"
21
+ gem "ostruct"
@@ -0,0 +1,21 @@
1
+ # frozen_string_literal: true
2
+ source "https://rubygems.org"
3
+
4
+ gemspec path: ".."
5
+
6
+ gem "activesupport", "~> 7.1.0"
7
+ gem "rake", ">= 13"
8
+ gem "minitest", "~> 5.0"
9
+ gem "mocha", "~> 1.9"
10
+
11
+ # concurrent-ruby 1.3.5 起不再自動 require logger,Rails 7.0 / 7.1 會載入失敗
12
+ gem "concurrent-ruby", "< 1.3.5"
13
+
14
+ # Ruby 3.4 已不再內建這些 gem;Rails 7.0 / 7.1 沒有自行宣告,故明確列出
15
+ gem "logger"
16
+ gem "mutex_m"
17
+ gem "bigdecimal"
18
+ gem "base64"
19
+ gem "drb"
20
+ gem "matrix"
21
+ gem "ostruct"
@@ -0,0 +1,14 @@
1
+ # frozen_string_literal: true
2
+ source "https://rubygems.org"
3
+
4
+ gemspec path: ".."
5
+
6
+ gem "activesupport", "~> 7.2.0"
7
+ gem "rake", ">= 13"
8
+ gem "minitest", "~> 5.0"
9
+ gem "mocha", "~> 1.9"
10
+ gem "logger"
11
+ gem "mutex_m"
12
+ gem "bigdecimal"
13
+ gem "matrix"
14
+ gem "ostruct"
@@ -0,0 +1,15 @@
1
+ # frozen_string_literal: true
2
+ source "https://rubygems.org"
3
+
4
+ gemspec path: ".."
5
+
6
+ # Target ActiveSupport 8.0.5.1 (Rails 8.0.x); 8.1.3.1 also exists on RubyGems
7
+ gem "activesupport", "8.0.5.1"
8
+ gem "rake", ">= 13"
9
+ gem "minitest", "~> 5.0"
10
+ gem "mocha", "~> 1.9"
11
+ gem "logger"
12
+ gem "mutex_m"
13
+ gem "bigdecimal"
14
+ gem "matrix"
15
+ gem "ostruct"
@@ -0,0 +1,18 @@
1
+ # frozen_string_literal: true
2
+ source "https://rubygems.org"
3
+
4
+ gemspec path: ".."
5
+
6
+ gem "activesupport", "~> 8.1.0"
7
+ gem "rake", ">= 13"
8
+ gem "minitest", "~> 5.0"
9
+ gem "mocha", "~> 1.9"
10
+
11
+ # Ruby 3.4 已不再內建這些 gem;Rails 7.0 / 7.1 沒有自行宣告,故明確列出
12
+ gem "logger"
13
+ gem "mutex_m"
14
+ gem "bigdecimal"
15
+ gem "base64"
16
+ gem "drb"
17
+ gem "matrix"
18
+ gem "ostruct"
@@ -31,6 +31,7 @@ module SuperPDF
31
31
 
32
32
  def column(options, &block)
33
33
  @left_pos ||= pdf.bounds.left
34
+ options = options.dup # do not mutate the caller's hash
34
35
  width = options.delete(:width)
35
36
  width = pdf.percent2pt_of_width(width) if pdf.percentage?(width)
36
37
  pdf.bounding_box([@left_pos, pdf.bounds.top], width: width, height: pdf.bounds.height) do
@@ -53,8 +53,10 @@ module SuperPDF
53
53
  # ...
54
54
  # end
55
55
  def div(options = {}, &block)
56
- margin_div(options[:margin], options.slice(:width, :height, :border, :background_color)) do
57
- padding_div(options[:padding], options.slice(:width, :height), &block)
56
+ # `margin_div` / `padding_div` take keyword arguments. Ruby 3 no longer converts a
57
+ # trailing Hash into keywords, so splat explicitly (works on Ruby 2.x - 3.x).
58
+ margin_div(options[:margin], **options.slice(:width, :height, :border, :background_color)) do
59
+ padding_div(options[:padding], **options.slice(:width, :height), &block)
58
60
  end
59
61
  end
60
62
 
@@ -96,7 +98,7 @@ module SuperPDF
96
98
  bounding_box([left, top], width: width, height: height) do
97
99
  yield if block_given?
98
100
  fill_background_color(background_color) if background_color
99
- draw_border(convert_border_options(border)) if border
101
+ draw_border(**convert_border_options(border)) if border
100
102
  end
101
103
  end
102
104
  end
@@ -124,7 +126,7 @@ module SuperPDF
124
126
  height ||= bounds.height - pre_height
125
127
 
126
128
  bounding_box([bounds.left, bounds.top - pre_height], width: width, height: height) do
127
- draw_border(convert_border_options(border)) if border
129
+ draw_border(**convert_border_options(border)) if border
128
130
  fill_background_color(background_color) if background_color
129
131
 
130
132
  left = bounds.left + padding.left
@@ -170,7 +172,7 @@ module SuperPDF
170
172
  bounds.left + left, bounds.top - top
171
173
  ], width: width, height: height) do
172
174
  fill_background_color(background_color) if background_color
173
- draw_border(convert_border_options(border)) if border
175
+ draw_border(**convert_border_options(border)) if border
174
176
  yield if block_given?
175
177
  end
176
178
  move_cursor_to cursor_cache
@@ -1,3 +1,3 @@
1
1
  module SuperPDF
2
- VERSION = "0.1.4"
2
+ VERSION = "0.1.6"
3
3
  end
data/lib/super_pdf.rb CHANGED
@@ -1,5 +1,8 @@
1
1
  require 'prawn'
2
+ require 'ostruct'
2
3
  require 'active_support'
4
+ require 'active_support/concern'
5
+ require 'active_support/core_ext/module/delegation'
3
6
  require "super_pdf/version"
4
7
  require "super_pdf/page"
5
8
  require "super_pdf/font"
data/super_pdf.gemspec CHANGED
@@ -14,6 +14,9 @@ Gem::Specification.new do |spec|
14
14
  spec.homepage = "https://github.com/superlanding/super_pdf"
15
15
  spec.license = "MIT"
16
16
 
17
+ # Compatible with ActiveSupport 4 through Rails 8 (AS 8.x); no upper bound.
18
+ spec.required_ruby_version = ">= 2.7"
19
+
17
20
  spec.files = `git ls-files -z`.split("\x0").reject do |f|
18
21
  f.match(%r{^(test|spec|features)/})
19
22
  end
@@ -21,12 +24,15 @@ Gem::Specification.new do |spec|
21
24
  spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
22
25
  spec.require_paths = ["lib"]
23
26
 
24
- spec.add_development_dependency "bundler", "~> 1.14"
25
- spec.add_development_dependency "rake", "~> 10.0"
27
+ spec.add_development_dependency "bundler", ">= 1.14"
28
+ spec.add_development_dependency "rake", ">= 10.0"
26
29
  spec.add_development_dependency "minitest", "~> 5.0"
27
30
  spec.add_development_dependency "mocha", "~> 1.9"
28
31
  spec.add_dependency "activesupport", ">= 4"
29
32
  spec.add_dependency "prawn", "~> 2.2", '>= 2.2.2'
33
+ # prawn needs matrix; extracted from default gems since Ruby 3.1
34
+ spec.add_dependency "matrix"
35
+ spec.add_dependency "ostruct"
30
36
  spec.add_dependency "prawn-table", "0.2.2"
31
37
  spec.add_dependency "prawn-icon", "2.4.0"
32
38
  end
metadata CHANGED
@@ -1,41 +1,40 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: super_pdf
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.4
4
+ version: 0.1.6
5
5
  platform: ruby
6
6
  authors:
7
7
  - vegeta
8
- autorequire:
9
8
  bindir: exe
10
9
  cert_chain: []
11
- date: 2019-10-18 00:00:00.000000000 Z
10
+ date: 1980-01-02 00:00:00.000000000 Z
12
11
  dependencies:
13
12
  - !ruby/object:Gem::Dependency
14
13
  name: bundler
15
14
  requirement: !ruby/object:Gem::Requirement
16
15
  requirements:
17
- - - "~>"
16
+ - - ">="
18
17
  - !ruby/object:Gem::Version
19
18
  version: '1.14'
20
19
  type: :development
21
20
  prerelease: false
22
21
  version_requirements: !ruby/object:Gem::Requirement
23
22
  requirements:
24
- - - "~>"
23
+ - - ">="
25
24
  - !ruby/object:Gem::Version
26
25
  version: '1.14'
27
26
  - !ruby/object:Gem::Dependency
28
27
  name: rake
29
28
  requirement: !ruby/object:Gem::Requirement
30
29
  requirements:
31
- - - "~>"
30
+ - - ">="
32
31
  - !ruby/object:Gem::Version
33
32
  version: '10.0'
34
33
  type: :development
35
34
  prerelease: false
36
35
  version_requirements: !ruby/object:Gem::Requirement
37
36
  requirements:
38
- - - "~>"
37
+ - - ">="
39
38
  - !ruby/object:Gem::Version
40
39
  version: '10.0'
41
40
  - !ruby/object:Gem::Dependency
@@ -100,6 +99,34 @@ dependencies:
100
99
  - - ">="
101
100
  - !ruby/object:Gem::Version
102
101
  version: 2.2.2
102
+ - !ruby/object:Gem::Dependency
103
+ name: matrix
104
+ requirement: !ruby/object:Gem::Requirement
105
+ requirements:
106
+ - - ">="
107
+ - !ruby/object:Gem::Version
108
+ version: '0'
109
+ type: :runtime
110
+ prerelease: false
111
+ version_requirements: !ruby/object:Gem::Requirement
112
+ requirements:
113
+ - - ">="
114
+ - !ruby/object:Gem::Version
115
+ version: '0'
116
+ - !ruby/object:Gem::Dependency
117
+ name: ostruct
118
+ requirement: !ruby/object:Gem::Requirement
119
+ requirements:
120
+ - - ">="
121
+ - !ruby/object:Gem::Version
122
+ version: '0'
123
+ type: :runtime
124
+ prerelease: false
125
+ version_requirements: !ruby/object:Gem::Requirement
126
+ requirements:
127
+ - - ">="
128
+ - !ruby/object:Gem::Version
129
+ version: '0'
103
130
  - !ruby/object:Gem::Dependency
104
131
  name: prawn-table
105
132
  requirement: !ruby/object:Gem::Requirement
@@ -135,13 +162,22 @@ executables: []
135
162
  extensions: []
136
163
  extra_rdoc_files: []
137
164
  files:
165
+ - ".github/workflows/publish.yml"
166
+ - ".github/workflows/test.yml"
138
167
  - ".gitignore"
168
+ - CHANGELOG.md
169
+ - CLAUDE.md
139
170
  - Gemfile
140
171
  - LICENSE.txt
141
172
  - README.md
142
173
  - Rakefile
143
174
  - bin/console
144
175
  - bin/setup
176
+ - gemfiles/rails_7.0.gemfile
177
+ - gemfiles/rails_7.1.gemfile
178
+ - gemfiles/rails_7.2.gemfile
179
+ - gemfiles/rails_8.0.gemfile
180
+ - gemfiles/rails_8.1.gemfile
145
181
  - lib/super_pdf.rb
146
182
  - lib/super_pdf/enhance.rb
147
183
  - lib/super_pdf/font.rb
@@ -156,7 +192,6 @@ homepage: https://github.com/superlanding/super_pdf
156
192
  licenses:
157
193
  - MIT
158
194
  metadata: {}
159
- post_install_message:
160
195
  rdoc_options: []
161
196
  require_paths:
162
197
  - lib
@@ -164,15 +199,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
164
199
  requirements:
165
200
  - - ">="
166
201
  - !ruby/object:Gem::Version
167
- version: '0'
202
+ version: '2.7'
168
203
  required_rubygems_version: !ruby/object:Gem::Requirement
169
204
  requirements:
170
205
  - - ">="
171
206
  - !ruby/object:Gem::Version
172
207
  version: '0'
173
208
  requirements: []
174
- rubygems_version: 3.0.6
175
- signing_key:
209
+ rubygems_version: 3.6.9
176
210
  specification_version: 4
177
211
  summary: Super PDF
178
212
  test_files: []